On Mon, Apr 10, 2017 at 01:12:26PM +0100, Stephen Finucane wrote: > This series introduces the use of Sphinx for building man pages. There are a > couple of reasons for doing this: > > - roff is ruff to write > > Sorry. roff is an old markup format that's mostly used for man pages today. > While certainly not impossible to parse, it isn't very pleasant to either > read or write (as evidenced by the XML-roff toolchain used for the OVN > sources). Sphinx/rST isn't perfect but it's certainly easier on the eyes. > > - Sphinx/rST über alles > > We already use Sphinx for every other bit of documentation in the toolchain. > Why force people to learn a second syntax for man pages? > > - Integration with other documentation > > By building with Sphinx, we can do basic things like output the man pages as > part of the documentation along with more advanced things like > cross-referencing applications from elesewhere in the docs. > > This series begins work on converting the docs, starting with two small > utilities: ovs-test and ovs-vlan-test. We can use these to tease out any > issues > we might have with the idea before expanding this to more complex man pages > (ovs-vsctl, I'm looking at you). The eventual goal would be to move all man > pages to rST/Sphinx. > --- > I meant to send this months ago, but I completely forgot about it. It's > unfinished, as evidenced by the commit footers. However, I think with a little > help from the maintainers of the packaging in OVS, it will be easy push this > over the line and move onto the bigger, more important man pages.
This is great. I've spent a few hours getting it better integrated into the build and install. I'm going to send out a revised version of the series in a bit, but I also have some questions and comments that I'll send on individual patches. _______________________________________________ dev mailing list d...@openvswitch.org https://mail.openvswitch.org/mailman/listinfo/ovs-dev
