nsd users - Jan 2023 - rewrite manpages to mdoc(7)

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.

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

Jan Stary <hans at stare.cz> 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.
I know. And Paul suggested xml, and you replied that it's crap. Other people
were suggesting other tools. I was just adding to the conversation that if
some other route was taken, it WASN'T at the expense of the manpages.
> > </bikeshed>
>
> I am concerned that you consider the quality of documentation bikeshiding.
Don't be a prick. I was making a humourous remark regarding my contribution.
If I wasn't concerned about the quality of the documentation, I wouldn't
have made my reply (which you obviously were unable to read)