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

[Stuart Henderson]

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.