Hi,
We had a discussion amongst the NSD and Unbound developers to determine
the best way forward. We choose to go with rst2man and Sphinx.
We're aware that this is not everybody's favorite choice, but we think
it's the best way to avoid duplication and have good quality
documentation both online and through man pages. The man page(s) will
be included in the release tarball as usual (ensuring no extra
dependencies are introduced). Maybe we'll include it in the master
branch too, automated checks can be applied to ensure it is up-to-date.
Suggestions/improvements to both the build process and (documentation)
sources are appreciated as always!
Of course, this does not directly address Jan's question regarding a
possible switch to mdoc. Which is theoretically still possible, it's
just that Sphinx does not currently seem to offer a builder for that.
Should one come into existence, we may consider adding or switching to
generated man pages in that format. To be determined if the option
presents itself. For now, thank you for your suggestion and your offer,
but reformatting the manual pages would only complicate the switch.
Thanks to everyone who provided input!
- Jeroen
>
> > > 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)
Perhaps what confused me was the sheer nonsequiturity of that.
Yes, we don't want to make the manpages worse. In fact, that's
what lies in the very core of my proposal to make them better.
Thank you.
It's a moot point anyway: it's not gonna happen.