Thank you! rST is much more readable than nroff. I have some comments below.
On Mon, Apr 10, 2017 at 01:12:28PM +0100, Stephen Finucane wrote: > Let's start with a simple one that lets us focus on setting up most of > the required "infrastructure" for building man pages using Sphinx. > > There are a couple of things worth noting here: > > - The 'check-htmldocs' target becomes 'check-docs' as its now > responsible for building man page docs too. > > - The outputted file will always have a '.1' suffix. This is Sphinx's > decision, and likely stems from the man page guidelines [1] which > state that "the name of the man page's source file...is the name of > the command, function or file name, followed by a dot, followed by the > section character". It looks to me like the last element of the tuples inside man_pages in conf.py controls the section. When I changed 1 to 8 there, it switched the manpage to section 8. So I made that change in conf.py and I removed the above paragraph from the commit message. > Other than that, hurrah for (mostly) legible syntaxes. > > [1] http://www.tldp.org/HOWTO/Man-Page/q2.html > > Signed-off-by: Stephen Finucane <[email protected]> > --- > I don't know if this is correctly integrated into the docs build system > or not. I need someone to double check this for me. In particular, I > think I need to integrate the 'dh_sphinxdoc' package [2] into the Debian > build but I've no idea how to. > > [2] http://manpages.ubuntu.com/manpages/zesty/man1/dh_sphinxdoc.1.html I spent a couple of hours working on the build and install system here. My first thought was to add rules to allow Automake to find and install the generated manpages. This turned out to be a huge mess that required tons of nasty GNU Make specific crap in the makefiles, and I didn't like it. My second approach was better. I gave up on integrating with the builtin Automake rules for manpages. All those really do anyway is handle install and uninstall, so I wrote some Make rules to do that. They're ugly because they're make+shell, but readable enough if you squint. The main question for install and uninstall is how to choose the right section. The easiest way seems to be to give the .rst files names that embed the section, like "ovs-vlan-test.8.rst". This is also handy to distinguish manpages with the same name but in different sections, which is sometimes a reasonable thing to have, so that's what I did. The patch didn't delete the old manpage, so I did that too. I noticed that the "Synposis" section of the new ovs-vlan-test.rst did not use bold and italic in the canonical way for manpages, so I added * and ** in the right places. _______________________________________________ dev mailing list [email protected] https://mail.openvswitch.org/mailman/listinfo/ovs-dev
