I wondered about converting the troff source to some other format (maybe DocBook) and using that source to generate both the man page and the same data in a format suitable for inclusion in the Upstart Cookbook. However, DocBook seemed a bit heavy weight and I'm not convinced it could handle it (tell me if I'm wrong!)
My preference actually is to keep the source as troff since:
- troff+tbl is a very rich language which provides a lot of control.
- I want full control over the width of the tables
The man page may look a little "cramped". I could have padded it out and made it a little easier on the eye, but I set myself a width constraint of 80 columns specifically for all the server folk out there who may want to view the page over an SSH connection.
$ cd /tmp $ doclifter upstart-events.7 $ xsltproc -o upstart-events.7.html \ /usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl \ upstart-events.7.xml $ tidy -indent -utf8 -o upstart-events.7.xhtml \ -asxhtml upstart-events.7.html $ elinks -dump-width 100 -dump upstart-events.7.xhtml > tmp.txt $ sed -e '1i ::\n' -e 's/^/ /g' tmp.txt > upstart-events.7.txt
The workflow above converts the troff+tbl to XML (using
doclifter), then to reformatted XHTML (using
xsltproc), then to ASCII (using
elinks), and finally it adds a reStructuredText "header" to show the ASCII is to be treated verbatim (using
Once I've generated
upstart-events.7.txt, I can include it into the cookbook like this:
.. include:: upstart-events.7.txt
Note that I could have left the data in XHTML for inclusion into the Cookbook, but that would have meant the PDF version of the Cookbook wouldn't have contained this data.
Of course all the commands above can be wrapped up into a Makefile so we don't have to worry about typing them in again. Having done all that, let's look at the result: