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. Stephen Finucane (4): doc: Add man page section to documentation guide doc: Convert ovs-vlan-test to rST doc: Convert ovs-test to rST doc: Remove latex output configuration Documentation/automake.mk | 23 +-- Documentation/conf.py | 6 +- .../internals/contributing/documentation-style.rst | 85 ++++++++++- Documentation/intro/install/documentation.rst | 4 +- Documentation/ref/index.rst | 17 ++- Documentation/ref/ovs-test.rst | 165 +++++++++++++++++++++ Documentation/ref/ovs-vlan-test.rst | 114 ++++++++++++++ debian/openvswitch-switch.manpages | 1 - debian/openvswitch-test.manpages | 1 - manpages.mk | 20 --- utilities/automake.mk | 6 - 11 files changed, 389 insertions(+), 53 deletions(-) create mode 100644 Documentation/ref/ovs-test.rst create mode 100644 Documentation/ref/ovs-vlan-test.rst -- 2.9.3 _______________________________________________ dev mailing list [email protected] https://mail.openvswitch.org/mailman/listinfo/ovs-dev
