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

[Jeroen Koekkoek]

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