[nsd-users] rewrite manpages to mdoc(7)

[Jeroen Koekkoek]

Hi,

We had a discussion amongst the NSD and Unbound developers to determine
the best way forward. We choose to go with rst2man and Sphinx.

We're aware that this is not everybody's favorite choice, but we think
it's the best way to avoid duplication and have good quality
documentation both online and through man pages. The man page(s) will
be included in the release tarball as usual (ensuring no extra
dependencies are introduced). Maybe we'll include it in the master
branch too, automated checks can be applied to ensure it is up-to-date.
Suggestions/improvements to both the build process and (documentation)
sources are appreciated as always!

Of course, this does not directly address Jan's question regarding a
possible switch to mdoc. Which is theoretically still possible, it's
just that Sphinx does not currently seem to offer a builder for that.
Should one come into existence, we may consider adding or switching to
generated man pages in that format. To be determined if the option
presents itself. For now, thank you for your suggestion and your offer,
but reformatting the manual pages would only complicate the switch.

Thanks to everyone who provided input!

- Jeroen


On Tue, 2023-01-03 at 15:28 +0100, Jan Stary via nsd-users wrote:
> On Jan 03 05:22:52, ask at develooper.com wrote:
> > > For example, the entirety of manpages.debian.org is done with
> > > that.
> > 
> > For comparison here’s one of the bind9 man pages
> > https://bind9.readthedocs.io/en/v9_18_10/manpages.html#delv-dns-lookup-and-validation-utility
> > — I for one much prefer the resulting output.
> 
> This "resulting output" is a html rendering of
> https://raw.githubusercontent.com/isc-projects/bind9/main/bin/delv/delv.rst
> apparently produced with http://docutils.sourceforge.net/
> 
> Compare the above to e.g.
> 
>         http://man.openbsd.org/ls
>         https://manpages.debian.org/bullseye/coreutils/ls.1.en.html
> 
> That's three different html layouts.
> That's not what I'm talking about; these are just examples
> to show that having manpages in mdoc(7), or man(7) for that matter,
> is no obstacle to having html versions too, as FUDed here previously.
> 
> The html content of 
> https://manpages.debian.org/bullseye/coreutils/ls.1.en.html
> is in fact a rendering of
> https://manpages.debian.org/bullseye/coreutils/ls.1.en.gz
> 
> Similarly, the html content of
> http://man.openbsd.org/ls
> is a rendering of
> http://cvsweb.openbsd.org/cgi-bin/cvsweb/~checkout~/src/bin/ls/ls.1
> 
> You are comparing the html outputs;
> that's not what I'm talking about.
> 
> > Some of the output formats have to be generated (man pages, too, I
> > guess!).
> 
> Currently, nsd* has a set of *.8 manpages in man(7)
> (in fact, *.8.in run through some sed replacements).
> What I'm proposing is to have a set of *.8 manpges in mdoc(7),
> because mdoc(7) is a better manpage annotation language then man(7).
> 
> Formats such as html (and pdf and ps and ...) can be generated from
> both,
> which has been the case for decades.
> 
> > I’m not sure why it’s important that the man pages are the “source”
> > as long as they get generated, too.
> 
> Generated from what? That's the issue here: the source format
> of the manpages. Currently it's man(7); I say mdoc(7),
> and am offering to do the work.
> 
> Compare https://manpages.debian.org/bullseye/coreutils/ls.1.en.gz
> to
> http://cvsweb.openbsd.org/cgi-bin/cvsweb/~checkout~/src/bin/ls/ls.1
> and compare nsd's nsd-checkzone.8, written in man(7), to the one I
> sent,
> written in mdoc(7). That's what I'm proposing.
> 
>         Jan
> 
> _______________________________________________
> nsd-users mailing list
> nsd-users at lists.nlnetlabs.nl
> https://lists.nlnetlabs.nl/mailman/listinfo/nsd-users