On Tue, Aug 25, 2015, at 18:19, Tim van der Molen wrote:> Jan Stary (2015-08-25 17:27 +0200): > > Currently, the NSD manpages are written in the legacy man(7) language. > > I propose to rewrite them into the markup of the mdoc(7) language. > > > > Both languages are sets of roff macros, supported for decades > > by mostly groff (on linuxes) and mandoc (on the BSD's). > > The main difference is that mdoc(7) does _semantic_ markup, > > so the macros mean e.g. "this is a command line option" > > as opposed to e.g. "make it italics and put brackets around it". > > See http://mdocml.bsd.lv/ about the whole story. > > The only disadvantage of mdoc, however, is that some systems still don't > support it. I believe Solaris is one of them. So, for portability, you'd > have to be able to provide man pages in both mdoc and man format.I believe a better option would be to rewrite the man pages (and documentation) into sphinx-build + build manpages (and documentation) at the "make dist" step, so they are included in the final distribution tarball. The reStructuredText is much more readable (and editable) than man(7) or mdoc(7) format. An example man page for kdig: https://gitlab.labs.nic.cz/labs/knot/raw/master/doc/man_kdig.rst Cheers, -- Ond?ej Sur? <ondrej at sury.org> Knot DNS (https://www.knot-dns.cz/) ? a high-performance DNS server
> On 26 Aug 2015, at 6:27 pm, Ond?ej Sur? <ondrej at sury.org> wrote: > > > > On Tue, Aug 25, 2015, at 18:19, Tim van der Molen wrote: >> Jan Stary (2015-08-25 17:27 +0200): >>> Currently, the NSD manpages are written in the legacy man(7) language. >>> I propose to rewrite them into the markup of the mdoc(7) language. >>> >>> Both languages are sets of roff macros, supported for decades >>> by mostly groff (on linuxes) and mandoc (on the BSD's). >>> The main difference is that mdoc(7) does _semantic_ markup, >>> so the macros mean e.g. "this is a command line option" >>> as opposed to e.g. "make it italics and put brackets around it". >>> See http://mdocml.bsd.lv/ about the whole story. >> >> The only disadvantage of mdoc, however, is that some systems still don't >> support it. I believe Solaris is one of them. So, for portability, you'd >> have to be able to provide man pages in both mdoc and man format. > > I believe a better option would be to rewrite the man pages (and > documentation) into sphinx-build + build manpages (and documentation) at > the "make dist" step, so they are included in the final distribution > tarball. > > The reStructuredText is much more readable (and editable) than man(7) or > mdoc(7) format. > > An example man page for kdig: > https://gitlab.labs.nic.cz/labs/knot/raw/master/doc/man_kdig.rsti disagree. restructuredtext lacks the semantic markup that mdoc features and what jan was originally proposing. if providing man(7) for legacy systems is necessary, mandoc is a far lighter build depend than sphinx.
On Wed, 26 Aug 2015, Ond?ej Sur? wrote:> I believe a better option would be to rewrite the man pages (and > documentation) into sphinx-build + build manpages (and documentation) at > the "make dist" step, so they are included in the final distribution > tarball. > > The reStructuredText is much more readable (and editable) than man(7) or > mdoc(7) format.I agree that editing in roff/man is about as fun as writing sendmail.cf :)> An example man page for kdig: > https://gitlab.labs.nic.cz/labs/knot/raw/master/doc/man_kdig.rstThat looks much better. Although to add more options to this, I find the xml more readable (it converts with 'xmlto man') example: https://github.com/libreswan/libreswan/blob/master/programs/pluto/ipsec_pluto.8.xml Paul
On Wed, Aug 26, 2015, at 15:33, Paul Wouters wrote:> On Wed, 26 Aug 2015, Ond?ej Sur? wrote: > > > I believe a better option would be to rewrite the man pages (and > > documentation) into sphinx-build + build manpages (and documentation) at > > the "make dist" step, so they are included in the final distribution > > tarball. > > > > The reStructuredText is much more readable (and editable) than man(7) or > > mdoc(7) format. > > I agree that editing in roff/man is about as fun as writing sendmail.cf > :)Well, that was the point. We also had a documentation in texinfo format, which is ok if you use emacs that autoupdates the references :), but for the rest of people with inferior editors the sphinx-build is currently the best option.> > An example man page for kdig: > > https://gitlab.labs.nic.cz/labs/knot/raw/master/doc/man_kdig.rst > > That looks much better. Although to add more options to this,> I find the xml more readable (it converts with 'xmlto man')Do you? Remind me to check for a crazy look in your eyes next time we meet :) Anyway I understand that mdoc might have more formatting options, but the question is whether they are really needed for nsd manpages and also whether the comfort of the authors have some priority over the tricks you can do with the format. JFTR for the rST you can also have something they call an "option list": http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#option-lists which works nicely if you don't need an optional parameters to the options. Cheers, -- Ond?ej Sur? <ondrej at sury.org> Knot DNS (https://www.knot-dns.cz/) ? a high-performance DNS server