On Thu, Apr 13, 2017 at 05:40:37PM -0700, Ben Pfaff wrote: > 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.
And now I've posted my version: https://mail.openvswitch.org/pipermail/ovs-dev/2017-April/330842.html Thanks again! _______________________________________________ dev mailing list [email protected] https://mail.openvswitch.org/mailman/listinfo/ovs-dev
