Thursday, 5 January 2012

Converting troff tables to ASCII

One particularly useful piece of information I've been wanting to add to the Upstart Cookbook for a while now is the upstart-events(7) manual page. This page shows a summary of the "well-known" Upstart events that are provided on an Ubuntu system.  However, as show in the link, formatting this data is tricky due to the number and complexity of the tables.

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.
Recently, I've found a workflow that I'm happy with and it all hinges on the legendary Eric S. Raymond's awesome tool called doclifter. Here's the process:

$ cd /tmp
$ doclifter upstart-events.7
$ xsltproc -o upstart-events.7.html \
      /usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl \
$ 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 echo and sed).

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:

1 comment:

  1. Nice Post, Thanks for your very useful information... I will bookmark for next reference.