[nsd-users] nsd manpages

[Ondřej Surý]

On Wed, Aug 26, 2015, at 15:33, Paul Wouters wrote:
> On Wed, 26 Aug 2015, Ondřej Surý wrote:
> 
> > 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.
> 
> I agree that editing in roff/man is about as fun as writing sendmail.cf
> :)

Well, that was the point. We also had a documentation in texinfo format,
which is ok if you use emacs that autoupdates the references :), but for
the rest of people with inferior editors the sphinx-build is currently
the best option.

> > An example man page for kdig:
> > https://gitlab.labs.nic.cz/labs/knot/raw/master/doc/man_kdig.rst
> 
> That looks much better. Although to add more options to this,

> I find the xml more readable (it converts with 'xmlto man')

Do you? Remind me to check for a crazy look in your eyes next time we
meet :)

Anyway I understand that mdoc might have more formatting options, but
the question is whether they are really needed for nsd manpages and also
whether the comfort of the authors have some priority over the tricks
you can do with the format.

JFTR for the rST you can also have something they call an "option list":

http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#option-lists

which works nicely if you don't need an optional parameters to the
options.

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