nsd users - Jan 2023 - rewrite manpages to mdoc(7)

> On Jan 2, 2023, at 14:19, Jan Stary via nsd-users <nsd-users at
lists.nlnetlabs.nl> wrote:
> 
> For example, the entirety of manpages.debian.org is done with that.
For comparison here?s one of the bind9 man pages ? I for one much prefer the
resulting output.

https://bind9.readthedocs.io/en/v9_18_10/manpages.html#delv-dns-lookup-and-validation-utility

Some of the output formats have to be generated (man pages, too, I guess!). I?m
not sure why it?s important that the man pages are the ?source? as long as they
get generated, too.


Ask

On 2023/01/03 05:22, Ask Bj?rn Hansen via nsd-users
wrote:
> 
> 
> > On Jan 2, 2023, at 14:19, Jan Stary via nsd-users <nsd-users at
lists.nlnetlabs.nl> wrote:
> > 
> > For example, the entirety of manpages.debian.org is done with that.
> 
> For comparison here?s one of the bind9 man pages ? I for one much prefer
the resulting output.
> 
>
https://bind9.readthedocs.io/en/v9_18_10/manpages.html#delv-dns-lookup-and-validation-utility
If you're comparing the same manual between bind9.readthedocs.io (rst
straight to html) and manpages.debian.org (first rst is converted to
man, and that is then converted to html) it's obvious which is going
to look best, simply because it has more information available
(semantic markup rather than basic formatting information).

A better comparison would be between html pages generated from a
"proper" mdoc conversion and from the rst source, e.g.

https://bind9.readthedocs.io/en/v9_18_10/manpages.html#dig-dns-lookup-utility
https://man.openbsd.org/dig

- the content is a bit different between the two as the version of dig
in openbsd is from an old fork and cut-down compared to current ISC
releases, but ignoring that, you get a better picture of what high
quality output looks like from each of the source formats.

Both look pretty much ok to me; the semantic information in mdoc is
pretty good for searches, and mandoc's linter can be helpful to maintain
quality, on the other hand rst has a slightly lower barrier for users to
edit at the expense of heavier dependencies. The key thing is to use
something that whoever does most work to maintain the documentation is
happy with really imho.

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