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
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
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? <ondrej at sury.org> (He/Him)> On 31. 12. 2022, at 17:51, Jeroen Koekkoek via nsd-users <nsd-users at 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 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