Hi Jeroen, I would recommend to think about the ?producers? and ?consumers? here. The consumers are users, so ideally you want output that?s easy to read - both man pages and the documentation (HTML, PDF, EPUB?) The producers are developers and contributors - ideally you want a format that doesn?t have steep learning curve to promote people contributing fixes to the documentation. Personally, I don?t think there?s much to gain by converting from a format only a handful people can read and write to another format that only handful people can read and write. If you already have in-house experience with Sphinx, I would strongly suggest to stick with that. There are options how to make the dependency optional - either stick the pre-generated man pages to the git repository as I suggested in the GH issue (I?ve done this for both Knot DNS and BIND 9, so I can provide some hints on how to do that), or just skip the man page generation if Sphinx is not available. The integration with the documentation is something that you cannot easily achieve with neither man or medic formats. Python is pretty much ubiquitous nowadays and installing pypi packages is a common skill. I don?t consider this to be really a blocker. And just another data point - BIND 9 used to have documentation in DocBook (XML) and it wasn?t that terrible, but we haven?t looked back since we converted the documentation to Sphinx. The only hiccups we hit from time to time are the old Sphinx versions in the older distributions. The other thing to consider is the shared wisdom - BIND 9, Knot and PowerDNS projects are already using Sphinx, and you know where to find us ;) Ondrej -- Ond?ej Sur? <ondrej at sury.org> (He/Him)> On 2. 1. 2023, at 19:37, Jeroen Koekkoek via nsd-users <nsd-users at lists.nlnetlabs.nl> wrote: > > ?Hi Jan, > > Was typing this on GitHub, but this is fine too :) > > It's really very nice of you that you want to do some of the work! > > There's other angles to consider here too though. mdoc does not > automatically improve all things and that we can easily include the man > page from the online documentation is very compelling to us. Your > message simply brought that subject up too. > > I can see why you want to have good manpages and maybe rst2man is not > ideal for that(?) I wouldn't know personally, but I can see that having > a dependency on Python is not ideal for all builds. > > So, I was thinking, why not man2rst (other way around). I found this > article which uses mandoc to convert man pages written in mdoc to rst > (https://undeadly.org/cgi?action=article&sid=20170304230520). > > I have to test it to see if it's viable. The added benefit would be > that we have "proper" or "plain" man pages for the basic builds and > have a dependency on Python, Sphinx, etc only for developers and online > documentation builds. > > If my suggestions work, personally, I'd be more than happy to take you > up on your offer :) > > Of course, this too is subject to discussion, it's merely an idea for > now, but I'll run some tests. > > Thanks! > > - Jeroen > > >> On Mon, 2023-01-02 at 18:41 +0100, Jan Stary via nsd-users wrote: >>> On Jan 01 00:05:09, jamie at catflap.org wrote: >>> Jan Stary via nsd-users <nsd-users at lists.nlnetlabs.nl> wrote: >>> >>>> On Dec 31 11:43:56, paul at nohats.ca wrote: >>>>> Why not go to xml and use xml2man / pandoc ? >>>> >>>> Because it is a terrible manpage format >>>> and the toolchain produces broken crap. >>> >>> I have no specific knowledge on this, but would just like to "me >>> too" >>> to this thread that whatever format is used, it MUSTN'T impact on >>> the >>> quality of any resultant man/mdoc conversion. >> >> What I am proposing is to _write_ the mdoc(7) manpages, >> not have them produced by some toolchain or another. >> >>> </bikeshed> >> >> I am concerned that you consider the quality of documentation >> bikeshiding. >> _______________________________________________ >> 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
On Jan 02 20:52:35, nsd-users at lists.nlnetlabs.nl wrote:> I would recommend to think about the ?producers? and ?consumers? here. > > The consumers are users, so ideally you want output that?s easy to read > - both man pages and the documentation (HTML, PDF, EPUB?)To be clear: I am only talking about the manpages. While the mdoc(7) language could be (ab?)used to annotate other kinds of texts (such as lengthy structured prose), it is intended as a semantic annotation of manpages.> The producers are developers and contributors - ideally you want > a format that doesn?t have steep learning curve to promote people > contributing fixes to the documentation.I might be misunderstanding "promote" here, but sure: you want a simple, well-established, standardized language; such as mdoc(7), the language of manpages since the 70's.> Personally, I don?t think there?s much to gain by converting > from a format only a handful people can read and write to another > format that only handful people can read and write.While true, this misses the point of my proposal entirely. The benefit is (1) the semantic markup, (2) the ease of reading, writing and maintaining the mapages (meaning source). .Xr nsd 8 => see also the manpage of nsd in section 8 as opposed to \fInsd\fR(8) => switch to italics, type "nsd", switch back to roman, and type 8 in parenthesis> If you already have in-house experience with Sphinx,Apparently, the content of https://nsd.docs.nlnetlabs.nl/en/latest/ is produce by Sphinx.> I would strongly suggest to stick with that. There are options > how to make the dependency optional - either stick the pre-generated > man pages to the git repository as I suggested in the GH issueHaving _generated_ code in the repository is just asking for unsynced versions. Manpage is a manpage. It should be written by hand and maintained, just like any other source file. Maybe that is where our views differ: manpage is the source, to be formatted with man(1) (i.e. eventualy by groff or mandoc or whatever behind the curtains), or processed into html od pdf or whatever else, not something that gets created automaticaly; it's source code, just like the C files.> or just skip the man page generation if Sphinx is not available.That's a joke, right? Or are you seriously proposing to _not_ have manpages?> The integration with the documentation is something > that you cannot easily achieve with neither man or medic formats.I don't know what medic is, but html integration of mdoc(7) source is trivial with mandoc -Thtml, and perfectly doable with groff -Thtml, and has been for a long time. Stop the fud.> Python is pretty much ubiquitous nowadays and installing pypi > packages is a common skill. I don?t consider this to be really a blocker.For comparison, man(7) and mdoc(7) formatters have been around since the seventies.> And just another data point - BIND 9 used to > have documentation in DocBook (XML) and it wasn?t that terribleSee here for why DocBook would be a terrible choice: https://undeadly.org/cgi?action=article&sid=20190419101505> The other thing to consider is the shared wisdom - BIND 9, > Knot and PowerDNS projects are already using Sphinx,Yes, and entire operating system, including macOS and all the BSDs have their manpages in mdoc(7), for comparison. Jan