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

[Paul Wouters]

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