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

[Jan Stary]

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