[nsd-users] nsd manpages

[David Gwynne]

> On 26 Aug 2015, at 6:27 pm, Ondřej Surý <ondrej at sury.org> wrote:
> 
> 
> 
> On Tue, Aug 25, 2015, at 18:19, Tim van der Molen wrote:
>> Jan Stary (2015-08-25 17:27 +0200):
>>> Currently, the NSD manpages are written in the legacy man(7) language.
>>> I propose to rewrite them into the markup of the mdoc(7) language.
>>> 
>>> Both languages are sets of roff macros, supported for decades
>>> by mostly groff (on linuxes) and mandoc (on the BSD's).
>>> The main difference is that mdoc(7) does _semantic_ markup,
>>> so the macros mean e.g. "this is a command line option"
>>> as opposed to e.g. "make it italics and put brackets around it".
>>> See http://mdocml.bsd.lv/ about the whole story.
>> 
>> The only disadvantage of mdoc, however, is that some systems still don't
>> support it. I believe Solaris is one of them. So, for portability, you'd
>> have to be able to provide man pages in both mdoc and man format.
> 
> I believe a better option would be to rewrite the man pages (and
> documentation) into sphinx-build + build manpages (and documentation) at
> the "make dist" step, so they are included in the final distribution
> tarball.
> 
> The reStructuredText is much more readable (and editable) than man(7) or
> mdoc(7) format.
> 
> An example man page for kdig:
> https://gitlab.labs.nic.cz/labs/knot/raw/master/doc/man_kdig.rst

i disagree. restructuredtext lacks the semantic markup that mdoc features and what jan was originally proposing. if providing man(7) for legacy systems is necessary, mandoc is a far lighter build depend than sphinx.