[ovs-dev] manpages in rst?

[Stephen Finucane]

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 :(

> 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.

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.

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.

Cheers,
Stephen

[1] https://github.com/django/django/tree/master/docs/man
[2] http://www.sphinx-doc.org/en/stable/builders.html#sphinx.builders.m
anpage.ManualPageBuilder