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

[Jeroen Koekkoek]

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