My experience with several projects are to use RST and Sphinx. It’s human readable, the output is really nice, and you can publish the results to RTD.
Ondrej -- Ondřej Surý <ond...@sury.org> (He/Him) > On 31. 12. 2022, at 17:51, Jeroen Koekkoek via nsd-users > <nsd-users@lists.nlnetlabs.nl> 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
