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

[Jan Stary]

On Jan 02 20:52:35, nsd-users at lists.nlnetlabs.nl wrote:
> I would recommend to think about the “producers” and “consumers” here.
> 
> The consumers are users, so ideally you want output that’s easy to read
> - both man pages and the documentation (HTML, PDF, EPUB…)

To be clear: I am only talking about the manpages.
While the mdoc(7) language could be (ab?)used to annotate
other kinds of texts (such as lengthy structured prose),
it is intended as a semantic annotation of manpages.

> The producers are developers and contributors - ideally you want
> a format that doesn’t have steep learning curve to promote people
> contributing fixes to the documentation.

I might be misunderstanding "promote" here, but sure:
you want a simple, well-established, standardized language;
such as mdoc(7), the language of manpages since the 70's.

> Personally, I don’t think there’s much to gain by converting
> from a format only a handful people can read and write to another
> format that only handful people can read and write.

While true, this misses the point of my proposal entirely.
The benefit is (1) the semantic markup, (2) the ease of
reading, writing and maintaining the mapages (meaning source).

	.Xr nsd 8
	=> see also the manpage of nsd in section 8

as opposed to

	\fInsd\fR(8)
	=> switch to italics, type "nsd",
	   switch back to roman, and type 8 in parenthesis
	
> If you already have in-house experience with Sphinx,

Apparently, the content of
https://nsd.docs.nlnetlabs.nl/en/latest/
is produce by Sphinx.

> I would strongly suggest to stick with that. There are options
> how to make the dependency optional - either stick the pre-generated
> man pages to the git repository as I suggested in the GH issue

Having _generated_ code in the repository
is just asking for unsynced versions.

Manpage is a manpage. It should be written by hand and maintained,
just like any other source file.

Maybe that is where our views differ: manpage is the source, to be
formatted with man(1) (i.e. eventualy by groff or mandoc or whatever
behind the curtains), or processed into html od pdf or whatever else,
not something that gets created automaticaly;
it's source code, just like the C files.

> or just skip the man page generation if Sphinx is not available.

That's a joke, right?
Or are you seriously proposing to _not_ have manpages?

> The integration with the documentation is something
> that you cannot easily achieve with neither man or medic formats.

I don't know what medic is, but html integration of mdoc(7) source
is trivial with mandoc -Thtml, and perfectly doable with groff -Thtml,
and has been for a long time. Stop the fud.

> Python is pretty much ubiquitous nowadays and installing pypi
> packages is a common skill. I don’t consider this to be really a blocker.

For comparison, man(7) and mdoc(7) formatters have been around
since the seventies.

> And just another data point - BIND 9 used to
> have documentation in DocBook (XML) and it wasn’t that terrible

See here for why DocBook would be a terrible choice:
https://undeadly.org/cgi?action=article&sid=20190419101505

> The other thing to consider is the shared wisdom - BIND 9,
> Knot and PowerDNS projects are already using Sphinx,

Yes, and entire operating system, including macOS and all the BSDs
have their manpages in mdoc(7), for comparison.

	Jan