[nsd-users] nsd manpages

[Ondřej Surý]

On Tue, Aug 25, 2015, at 18:19, Tim van der Molen wrote:
> Jan Stary (2015-08-25 17:27 +0200):
> > Currently, the NSD manpages are written in the legacy man(7) language.
> > I propose to rewrite them into the markup of the mdoc(7) language.
> > 
> > Both languages are sets of roff macros, supported for decades
> > by mostly groff (on linuxes) and mandoc (on the BSD's).
> > The main difference is that mdoc(7) does _semantic_ markup,
> > so the macros mean e.g. "this is a command line option"
> > as opposed to e.g. "make it italics and put brackets around it".
> > See http://mdocml.bsd.lv/ about the whole story.
> 
> The only disadvantage of mdoc, however, is that some systems still don't
> support it. I believe Solaris is one of them. So, for portability, you'd
> have to be able to provide man pages in both mdoc and man format.

I believe a better option would be to rewrite the man pages (and
documentation) into sphinx-build + build manpages (and documentation) at
the "make dist" step, so they are included in the final distribution
tarball.

The reStructuredText is much more readable (and editable) than man(7) or
mdoc(7) format.

An example man page for kdig:
https://gitlab.labs.nic.cz/labs/knot/raw/master/doc/man_kdig.rst

Cheers,
-- 
Ondřej Surý <ondrej at sury.org>
Knot DNS (https://www.knot-dns.cz/) – a high-performance DNS server