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@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@lists.nlnetlabs.nl > https://lists.nlnetlabs.nl/mailman/listinfo/nsd-users _______________________________________________ nsd-users mailing list nsd-users@lists.nlnetlabs.nl https://lists.nlnetlabs.nl/mailman/listinfo/nsd-users
