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 \
      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 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:

Comments

Post a Comment

Popular posts from this blog

Byobu Bling with Unicode Custom Indicators

Image
Introduction In these heady times of almost daily advances in UI pizzazz, you could be forgiven for thinking the terminal is somewhat of a dead-zone when it comes to excitement. Oh how wrong you would be though...! If you've never used  Byobu ,  Dustin's  awesome text-based window manage, sudo apt-get install it without delay to be bathed in pure terminal goodness. As shown below, byobu comes with a whole host of standard indicators, allowing the display of useful snippets of information. The indicators are minimal out of terminal-width real estate necessity, but that's also their strength - they provide just the details you really care about in a tight ASCII format. And they're cute of course :-) However, byobu has a well-kept secret: when running with the tmux backend, it supports Unicode indicators. So with the proviso that you are running " byobu-tmux " rather than " byobu-screen ", you can squeeze down those indicators even further...
Read more

Procenv 0.46 - now with more platform goodness

I have just released procenv version 0.46 . Although this is a very minor release for the existing platforms (essentially 1 bug fix), this release now introduces support for a new platform... Darwin Yup - OS X now joins the ranks of supported platforms. Although adding support for Darwin was made significantly easier as a result of the recent internal restructure of the procenv code, it did present a challenge: I don't own any Apple hardware. I could have borrowed a Macbook, but instead I decided to see this as a challenge: Could I port procenv to Darwin without actually having a local Apple system?  Well, you've just read the answer, but how did I do this? Stage 1: Docker Whilst surfing around I came across this interesting docker image: https://hub.docker.com/r/andrewd/osxcross/ It provides a Darwin toolchain that I could run under Linux. It didn't take very long to follow my own instructions on porting procenv to a new platform . But although I...
Read more

Upstart User Sessions in Ubuntu Raring

Image
Overview Ubuntu Raring now includes Upstart 1.8 . Upstart 1.7 and 1.8 combined mark a major milestone since they bring the proven power of Upstart to the user as never before: not only is Upstart now managing the system, but it is also capable of managing the default Ubuntu user's desktop sessions too. Why? Question:  Why reuse a system facility at the user level in this way? The modern Linux desktop environment is a very dynamic one: users start and stop applications, switch workspaces, search the dash, adjust personal settings in the panel, connect to different networks, hot-plug USB devices and so on. All of these activities can be represented by "events". Stepping back a second, recall that Upstart was written  from the outset  to take advantage of  the dynamic nature of a modern Linux system . Long gone are the days when a system booted serially. A modern Linux system abounds with "events" from all sorts of different sources: The user plugs or ...
Read more