Cthulhuian Document Preparation With Troff

Chris Wilson October 6, 2012

tl;dr: If you are looking for a lightweight document preparation system in the style of LaTeX, try out troff which is probably already on your system.

Intro

Lurking deep in UNIX, even on your shiny new Mac, is the eldritch horror of troff. It waits, dead but dreaming, for when the stars are right to reëmerge from the unplumbed deeps of the icy dark waves…

Actually, troff is a typesetting program that you may not have even realized you had. And while troff is old, and perhaps obscure, it is surprisingly useful for making clean, simple documents. If you need something like LaTeX, but balk at the multi-gigabyte install, then troff is worth taking a look at. As an added benefit, you’ll also understand that weird syntax behind man pages!

First some preliminaries, if you are the kind of person who knows about, or has heard of LaTeX, then you’re the person this post is aimed at. If LaTeX is news to you then here’s the gist: LaTeX and troff are both “document preparation” systems. This means that you type out a plain-text document, interspersed with formatting instructions, and run a sort of compiler over that document. This is in contrast to the dominant style embodied in programs like Microsoft Word.

Example

An example is worth a thousand blog posts. I happened to find this on the hard drive of Miskatonic University’s first UNIX system:

Using troff (compiling)

To compile this document, saved as request.1, you just do:

groff -Tps -ms -t request.1

The arguments given:

Specify PostScript output
Use the ms (manuscript) macro package (similar to article in LaTeX)
Run through tbl(1), to format the table

In this day and age, especially if exchanging documents with Windows, PDF output may be more useful:

groff -Tps -ms -t request.1 | pstopdf -i -o request.pdf

That pipeline should produce a PDF that looks like this:

request.pdf

I should also point out that even if you just produce the PostScript output, Mac’s preview will by default convert from ps to pdf upon opening the file.

Other cool stuff

Once you have a handle on troff, you can also write man pages without much fuss. The macro package that formats man pages is called -man (get it?)

A nice feature is that troff documents diff very well due to having commands on a line by themselves.

Also have a look at the little sub-languages:

eqn(1) for formatting mathematical equations
tbl(1) for laying out tables
pic(1) for drawing diagrams

ASCII Output

Troff can also produce plain-text:

groff -Tascii -ms -t request.1

will produce:

Request  for  Funds In Support of An Expedition to
                  the Antarctic Continent

                     William Dyer Ph.D.
        Professor of Geology, Miskatonic University

                          ABSTRACT

          Being a request for funds necessary  to  sup-
     port  a lively expedition to the southernmost con-
     tinent of the world. Reasons for the outlays shall
     be explained herein.

1.  A Description of the Expedition

We  are going to the antarctic continent to look for a weird
city.

1.1.  Required Personnel

We will require not more than ten  (10)  graduate  students.
Some  aptitude is important, though if they are, let us say,
not the finest students in  the  University,  that  will  be
fine.

2.  Required Materials

We will need the following things procured:

 +---------------------------------------------------------+
 |                       Equipment                         |
 +-------------------+----------+--------------------------+
 |       Name        | Quantity |          Notes           |
 +-------------------+----------+--------------------------+
 |    Flashlight     |    30    | Shock and cold resistant |
 +-------------------+----------+--------------------------+
 |    Batteries      |   100    |           Cold resistant |
 +-------------------+----------+--------------------------+
 |Anti-monster spray |    50    |           Extra-strength |
 +-------------------+----------+--------------------------+

Which loses some fidelity, but gives a nice preview.

HTML Output

Likewise, we can do HTML:

groff -Thtml -ms -t request.1

This spits out the following HTML:

Summary

So troff is there, slim at one megabyte, and, I would say, still quite useful. This is how man pages are formatted¹ , how AT&T technical memos were typeset, and sits in the standard UNIX toolset.

Even if you don’t end up using it, you’ll know where to look if you want to write UNIX-standard documentation.

References

A Troff tutorial: trofftut.ps
Using the manuscript macro package: msmacros.ps
There’s a section on troff in the back of Kernighan & Pike’s (excellent) “Unix Programming Environment”
A Linux Journal article on writing man pages: http://www.linuxjournal.com/article/1158

Notes

(1) See also BSD’s mandoc, an improved and updated formatter for BSD manuals.

Category: Development

Tags: Tutorial