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

[Ondřej Surý]

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