[ovs-dev] manpages in rst?

[Russell Bryant]

On Thu, Feb 16, 2017 at 12:24 PM, Ben Pfaff <blp at ovn.org> 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'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.
>
> Does anyone have comments?
>

+1 for rst.  That should make it easier to integrate the same content into
docs.openvswitch.org.

I think sphinx has support for man pages, but it has been a long time since
I've used it.

-- 
Russell Bryant