On Fri, 2017-04-14 at 12:49 -0700, Ben Pfaff wrote: > 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.
Correct. > I'm not sure there are any serious disadvantages to writing Make > rules to install and uninstall manpages. The only significant advantage would be simplicity for use in other build systems. Would the rules you've proposed work for the Debian and RHEL packaging, for example? Stephen _______________________________________________ dev mailing list d...@openvswitch.org https://mail.openvswitch.org/mailman/listinfo/ovs-dev
