Automate documentation refresh

[k0ekk0ek]

As noted by @janstary on the nsd-users mailing list, the documentation is slightly outdated. The obvious fix is to automate the process.

[AlexanderBand]

@janstary As mentioned in the mailing list thread by @oerdnj, using RST and Sphinx is quite nice. It's what NLnet Labs uses for the Routinator manpage and we're leaning towards this workflow for Unbound as well.

For example, the canonical source for the Routinator manpage is here and is published with Sphinx/ReadTheDocs here. We use rst2man to generate the manpage here.

[oerdnj]

FTR we use: $(SPHINX_BUILD) -b man -d $(SPHINXBUILDDIR)/.doctrees/man $(man_SPHINXOPTS) $(SPHINXBUILDDIR)/man to pre-build <foo>.[158]in and then we use:

man_SUBST =                                                     \
        $(AM_V_SED)$(SED)                                       \
          -e 's,[@]PACKAGE_VERSION@,$(PACKAGE_VERSION),'        \
          -e 's,[@]RELEASE_DATE@,$(RELEASE_DATE),'              \
          -e 's,[@]libdir[@],$(libdir),g'                       \
          -e 's,[@]runstatedir[@],$(runstatedir),g'             \
          -e 's,[@]sysconfdir[@],$(sysconfdir),g'               \
          $(srcdir)/$@in >$@

.1in.1:
        $(man_SUBST)

.5in.5:
        $(man_SUBST)

.8in.8:
        $(man_SUBST)

to update the paths, versions, etc. in the manpages.

This is automake, so you would have to adjust to your build system.

[janstary]

If https://github.com/NLnetLabs/routinator/blob/main/doc/routinator.1 is considered "quite nice" then I can only rest my case ...

[oerdnj]

@janstary I would recommend you to use less sarcasms and less foul language when you are talking about other people’s work.

[k0ekk0ek]

Apparently, you can use mandoc to convert to Markdown. Not as ideal as RST directly, but Sphinx can render Markdown too. Not to say that we must use it, simply an option to consider.

[AlexanderBand]

If https://github.com/NLnetLabs/routinator/blob/main/doc/routinator.1 is considered "quite nice" then I can only rest my case ...

Snark aside, I'd really like to understand what the problem is with a manpage generated from RST. Sure, the current routinator.1 file may not be the prettiest in formatting, but it's no longer a file that you directly edit so human readability is not as important.

Here's the manpage of Routinator 0.7.0 using hand-crafted groff/troff:

Compared to the same manpage of Routinator 0.12.0 generated by rst2man:

I think we're shipping a perfectly usable manpage with this methodology and optimises the limited resources we have as open-source maintainers. This workflow lets us manage documentation in a much friendlier markup language as a single canonical source. Additionally, in the online documentation we can easily link to options described in the manpage, which users really appreciate.

[mahtin]

Alex,

... using hand-crafted groff/troff

But nroff/troff was always hand edited back in the day! For some of us, old habits die hard!

[Jakker]

When I needed a manpage for routinator I used the man(7) macros because that was quick. How it currently is maintained I don't know and actually don't care.

Alex,

... using hand-crafted groff/troff

But nroff/troff was always hand edited back in the day! For some of us, old habits die hard!

Yes, but it is not the point the way the source is generated (I used an editor).
The crucial point is that g/n/t/roff is available on all unix line systems as a lingua-franca for text formatting and is used by man(1). The choice of man(7) or mdoc(7) is a matter of custom and/or taste. The problem with these semi-structured macros packages is that it asks for discipline by the writer not to throw in raw formatting requests as shortcuts. It is not unlike throwing using assembler code in the source for C or rust programs.

A proper manual page generation system will prevent such a practice. It has some added benefits that they can often generate input for other systems as well.

[janstary]

The problem with these semi-structured macros packages is that it asks for discipline by the writer not to throw in raw formatting requests as shortcuts.

Exactly: the man(7) pages that currently ship with nsd* are full of these low-level roff formating requests,
such as \fInsd.conf\fR; that's what I'm trying to get rid of by using mdoc(7).

[janstary]

I'd really like to understand what the problem is with a manpage generated from RST.

I'm not saying there's a problem with them. I'm saying they would be better
(simpler, more readable, more maintainable) if they were in mdoc(7),
as opposed to man(7) generated from RST.

That's a matter of taste to an extent of course. So consider this:

.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..

Yes, first define what it means to "indent". That's manpage formatting at its worst.
That's what https://github.com/NLnetLabs/routinator/blob/main/doc/routinator.1 does,
to be used like this, 102 times:

.UNINDENT
.INDENT 0.0
.TP

Sure, the man(7)page still renders fine to the user, meaning man(1) (using groff or mandoc of whatever)
can process it and show it to the user; that's not what I'm talking about
(is that what the screenshots are supposed to illustrate?)

[k0ekk0ek]

Just to finish up, the NSD and Unbound developers have collectively decided to go with Sphinx. The announcement can be read in more detail on the mailing list. Thanks to everyone who kindly took time to provide input.

I'll leave this open to serve as the reminder it was intended to be 🙂

[k0ekk0ek]

Sort-of fixed once #371 is merged (if approved)(?). Chose not to move to .rst yet as I wanted to focus on getting the online documentation up-to-date first.

[k0ekk0ek]

So, we generate the online documentation from the nsd repository now, so it's up-to-date. That takes care of the original intent of this ticket. We'll continue working on the docs from here.