On Fri, Apr 14, 2017 at 09:00:49PM +0100, Stephen Finucane wrote: > 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 <[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.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?
I understand now. I think that this change should be invisible to the Debian and RHEL packaging, because both kinds of packaging use "make install DESTDIR=..." to install the manpages into a staging tree, then package them from that staging tree. With this change, "make install" behaves the same way as before: both before and after the change, "make install" puts nroff versions of the manpages into $(DESTDIR)/usr/share/man/man#/ (or wherever they are configured to go). (I have not actually tested either kind of packaging.) _______________________________________________ dev mailing list [email protected] https://mail.openvswitch.org/mailman/listinfo/ovs-dev
