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

Sat Dec 31 17:09:48 UTC 2022

Actually, perhaps the other way is possible too if that easier(?) So,
mdoc to rst. But also, for that xml2man/pandoc maybe a better fit
because it's structured?

That being said, maybe mdoc is just a very nice first step. If it's
available on all supported systems and you're excited about it/willing
to do the work. Then feel free to do so, any improvement is always
appreciated! 

Before you start though, I'd check with Wouter and Willem. There may be
a reason we're using what we're currently using and they'd know.

Thanks!

- Jeroen

On Sat, 2022-12-31 at 17:51 +0100, Jeroen Koekkoek via nsd-users 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