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@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 > > _______________________________________________ > 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
