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? > 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. ++ Stephen [1] https://gitlab.labs.nic.cz/labs/knot/blob/bab62de/doc/Makefile.am#L 149-158 [2] https://gitlab.labs.nic.cz/labs/knot/blob/bab62de/doc/man/kdig.1in _______________________________________________ dev mailing list d...@openvswitch.org https://mail.openvswitch.org/mailman/listinfo/ovs-dev
