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

[Ondřej Surý]

My experience with several projects are to use RST and Sphinx. It’s human readable, the output is really nice, and you can publish the results to RTD.

Ondrej
--
Ondřej Surý <ondrej at sury.org> (He/Him)

> On 31. 12. 2022, at 17:51, Jeroen Koekkoek via nsd-users <nsd-users at lists.nlnetlabs.nl> wrote:
> 
> Hi Jan, Paul,
> 
> The others will have to chip in as well. I don't have a strong opinion
> about either, but we do have to build on all supported platforms. I
> think the most strict build is OpenBSD. As we're part of base, we need
> to ensure we don't depend on packages that are not in base(?) I think
> mdoc is in OpenBSD, but I'm not sure.
> 
> I agree with Paul that neiter man/mdoc is easy to write. Though that's
> probably because I don't do it on a regular base...
> 
> What I'd prefer is have the documentation in reStructuredText so we can
> easily include it in the online documentation too. There's probably
> some nifty way to convert that to manpages, but I haven't looked into
> that in great detail.
> 
> - Jeroen
> 
> 
>> On Sat, 2022-12-31 at 11:43 -0500, Paul Wouters via nsd-users wrote:
>> Why not go to xml and use xml2man / pandoc ?
>> 
>> That’s what we use for libreswan. xml is easier to write and read
>> than man/mdoc.
>> 
>> Paul
>> 
>> Sent using a virtual keyboard on a phone
>> 
>>> On Dec 31, 2022, at 11:31, Jan Stary via nsd-users
>>> <nsd-users at lists.nlnetlabs.nl> wrote:
>>> 
>>> Dear authors of NSD,
>>> 
>>> currently, the manpages that come with NSD
>>> are written in the traditional man(7) markup language.
>>> I am proposing to rewrite them into the semantic markup
>>> of the mdoc(7) language. I am willing to do the work.
>>> See a version of nsd-checkzone.8 below as an example.
>>> 
>>> Both the man(7) and mdoc(7) languages have been around for decades,
>>> and are supported by the prevalent formatters: groff(1) on most
>>> Linuxes
>>> and mandoc(1) on the *BSDs and some others. In particular,
>>> there is nothing to install or reconfigure on most systems
>>> - both formats can be both rendered with existing man(1)
>>> implemnetations and processed into plaintext, html, pdf, ps
>>> and possibly other formats.
>>> 
>>> The main point is that mdoc(7) allows for constructs like
>>> 
>>>    .Op Fl f Ar arg
>>> 
>>> meaning
>>> 
>>>    there is an optional 'f' flag
>>>    which takes an 'arg' argument
>>> 
>>> as opposed to
>>> 
>>>    switch to italics, type a bracket, a dash, "f",
>>>    then switch to boldface and type "arg"
>>> 
>>> in the physical roff markup of man(7).
>>> This leads to much better readability and maintainability.
>>> 
>>> Please let me know if you are interested.
>>> 
>>>    Jan
>>> 
>>> 
>>> 
>>> .Dd December 31, 2022
>>> .Dt NSD-CHECKZONE 8
>>> .Os
>>> .Sh NAME
>>> .Nm nsd-checkzone
>>> .Nd check NSD zone file syntax
>>> .Sh SYNOPSIS
>>> .Nm
>>> .Op Fl hp
>>> .Op Fl i Ar oldfile
>>> .Op Fl n Ar number
>>> .Op Fl s Ar size
>>> .Ar zonename
>>> .Ar zonefile
>>> .Sh DESCRIPTION
>>> .Nm
>>> reads a DNS zone file and checks it for errors.
>>> It prints errors to stderr.
>>> On failure it exits with nonzero exit status.
>>> This is used to check files before feeding them to the
>>> .Xr nsd 8
>>> daemon.
>>> The
>>> .Ar zonename
>>> is the zone to check,
>>> the
>>> .Ar zonefile
>>> is the file to read.
>>> .Pp
>>> The options are as follows:
>>> .Bl -tag -width Ds
>>> .It Fl h
>>> Print usage help information and exit.
>>> .It Fl p
>>> Print the zone contents to stdout if the zone is ok.
>>> This prints the contents as it has been parsed,
>>> not literally a copy of the input,
>>> but as printed by the formatting routines in NSD,
>>> much like the
>>> .Xr nsd-control 8
>>> command write does.
>>> .It Fl i Ar oldfile
>>> Create an IXFR from the differences between the old zone file
>>> and the new zone file.
>>> The
>>> .Ar oldfile
>>> argument to the
>>> .Fl i
>>> option is the old zonefile, the
>>> .Ar zonefile
>>> argument passed to
>>> .Nm
>>> is the new zonefile.
>>> The difference is computed between the two zonefiles
>>> by keeping one version of the zone in memory,
>>> and another version in a temporary file.
>>> The temporary file is located in the zonefile directory.
>>> This is also where the result is written
>>> in a file with the zonefile name, ending with
>>> .Sq .ixfr .
>>> This is also where NSD reads it when IXFRs are configured for the
>>> zone.
>>> If other ixfr files exist for the zone,
>>> they are renamed to become older IXFR contents for the zone.
>>> If the output file already exists with the correct contents,
>>> as determined by checking its header,
>>> no new file is created.
>>> .It Fl n Ar number
>>> The number of IXFR versions to store at the most, 5 by default.
>>> This is the number of ixfr files that get created for the zone.
>>> Older ixfr files are deleted when the number is exceeded.
>>> .It Fl s Ar size
>>> The number of bytes of storage to use for IXFRs for the zone;
>>> 1048576 by default.
>>> If an IXFR is bigger it is not created.
>>> If the sum of IXFR file sizes exceeds this number,
>>> older versions are deleted.
>>> .El
>>> .Sh SEE ALSO
>>> .Xr nsd 8 ,
>>> .Xr nsd-checkconf 8
>>> .Sh AUTHORS
>>> NSD was written by NLnet Labs and RIPE NCC joint team.
>>> Please see CREDITS file in the distribution for further details.
>>> _______________________________________________
>>> nsd-users mailing list
>>> nsd-users at lists.nlnetlabs.nl
>>> https://lists.nlnetlabs.nl/mailman/listinfo/nsd-users
>> _______________________________________________
>> nsd-users mailing list
>> nsd-users at lists.nlnetlabs.nl
>> https://lists.nlnetlabs.nl/mailman/listinfo/nsd-users
> 
> _______________________________________________
> nsd-users mailing list
> nsd-users at lists.nlnetlabs.nl
> https://lists.nlnetlabs.nl/mailman/listinfo/nsd-users