On Fri, Apr 14, 2017 at 06:55:38PM +0100, Stephen Finucane wrote: > On Thu, 2017-04-13 at 21:27 -0700, Ben Pfaff wrote: > > 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 <step...@that.guru> > > > --- > > > 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.h > > > tml > > > > 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. > > I still need to have a look into the patch (anything to do with > autotools is generally worth avoiding, heh), but I had a crazy idea > over the weekend: couldn't we just include the compiled man pages in > the source? The only issue with this would be the '.TH' line, but there > are solutions for avoiding this [1][2]. If we have man pages included > in the source, would that be adequate to use the standard autotools > setup for manpages?
I might not understand this idea yet. Do you mean, to include the nroff output of sphinx in the Git repository? I don't know why this would help. I'm not sure there are any serious disadvantages to writing Make rules to install and uninstall manpages. _______________________________________________ dev mailing list d...@openvswitch.org https://mail.openvswitch.org/mailman/listinfo/ovs-dev
