[ovs-dev] manpages in rst?

[Ben Pfaff]

On Fri, Feb 17, 2017 at 07:34:10AM -0500, Stephen Finucane wrote:
> On Thu, 2017-02-16 at 09:24 -0800, Ben Pfaff wrote:
> > Currently, we have some manpages written directly in nroff.  This is
> > an
> > awful format, that is difficult to read and difficult to
> > write.  Other
> > manpages are written in a custom XML format that, while it is easier
> > to
> > read and write, isn't any standard format and so we can't expect
> > anyone
> > else (person or program) to understand it.  This is not ideal.  It's
> > difficult to include either format in the readthedocs documentation,
> > too.
> 
> I started on a converter for that XML format but I haven't had a chance
> to finish it. The biggest problem I encountered was that rST is
> slightly lossy - it's not possible to nest elements the way you can
> nest XML or HTML so you have to drop some stuff. For example,
> converting '<b><i>' is impossible, since rST doesn't have markup for
> bold AND italic. Figuring out what to drop proved tougher than I
> thought. I basically needed to build a parser rather than hacking
> something together with regexes :(

Hmm.  I think that the XML format, in nroff translation, effectively
ends up with whatever is the innermost markup.  I don't think it does
anything smarter than that.  (I don't even know how to produce
bold-italic in nroff.)

> > I'm thinking about starting to write manpages in REstructured Text
> > (rst).  This would make it much easier to include them in the
> > readthedocs pages, and ReST seems to convert pretty well to nroff for
> > installing as real manpages.  For example, try fetching
> > http://docutils.sourceforge.net/sandbox/manpage-writer/input/test.txt
> > ,
> > which is a rst file, and then running "rst2man test.txt > test.man"
> > and
> > viewing test.man with "man -l" or "groffer".  The output looks fine.
> > 
> > I think that all we'd need for this is a build dependency on
> > python-docutils to ensure that rst2man is available at build time.
> 
> Pure rST would be my recommendation. Sphinx (python-sphinx) supports
> man page output [2] and could be an even better option that rst2man. We
> already have this (optional) dependency for the docs.

Can you help me understand the trade-off?  That is, how is one better
than the other?

> I do note that Django includes the generated man pages in the repo
> itself [1]. While the general policy for version control is not to
> include anything that's autogenerated, this could make packaging and
> installation from source slightly easier by avoiding adding another
> dependency. Then again, Sphinx is widely enough used that we could be
> pretty certain it would be available. I'll leave this to you to decide.

We already have a build dependency on Python, so I don't think that
depending on python-docutils would add much to that; it seems like it's
close to being core Python in any case.  I don't know whether adding
sphinx is a big deal.

> I have a couple of the man pages already converted to rST so, if you're
> happy to wait until after the OpenStack PTG, I could submit these. Also
> happy to review if someone else would like to work on it.

It'd be great to see what you've converted, so that we'd have a head
start.

I'm going to be out of town through next Wednesday, so I'll probably be
unresponsive until then.