Technical writing with GNU groff

Many technical writers of my era may have started with a text formatting system rather than a word processor. Nroff and troff were the original text formatters on Unix systems, and remain in use today, typically implemented as GNU groff. With nroff and troff, technical writers add formatting instructions in the body of a document, such as .br to create a line break or .sp 3 to add a few lines of empty space between paragraphs or sections. Troff also provides tools like eqn to generate equations and tbl to build tables within documents.

I asked Brian Kernighan about the history of nroff and troff, and how technical writers can explore these tools today. You may recognize Brian Kernighan's name. He is the "K" in Awk, the "K" in "K&R C" (he co-wrote the original "Kernighan and Ritchie" book about the C programming language), and he has authored and co-authored many books about Unix, programming, and technology. On my own bookshelf, I can find several of Kernighan's books, including Understanding the Digital World, Unix: A History and a Memoir, The Unix Programming Environment (with Rob Pike), The Awk Programming Language (with Alfred Aho and Peter J. Weinberger), and The C Programming Language (with Dennis M. Ritchie).

What are nroff and troff, and where did they come from?

Nroff is for basically ASCII text in a fixed-width font; it mimics ancient terminals like the Model 37 Teletype and line printers of the 1970s. Troff is for typesetters, which provide variable-width characters in multiple fonts, which is what we see in print today. That includes books, magazines, newspapers, and so on. 

The first such program was Runoff, written by Jerry Saltzer at MIT in maybe 1966; it was (in my experience) the first such formatting program and provided the model for a lot of subsequent ones. In 1968, I wrote a simpler version for printing my PhD thesis at Princeton that I called "roff," but I think Doug McIlroy at Bell Labs wrote a different version in the same style that he also called "roff." Nroff and troff adopted the same style of formatting commands, but were significantly more powerful and could do more complicated formatting, especially page layout.

The original version of troff by Joe Ossanna in about 1973 was aimed at a particular typesetter, the Graphics Systems Model C/A/T. Ditroff ("device independent troff") was my updated version of troff that produced output that was independent of any particular typesetter. It generated output that was parameterized for specific devices, and separate drivers produced final output on different typesetters.

How can people get started with groff to write documents? Would you recommend a popular macro set like -me or -ms or -mm?

Absolutely start with a macro package. I use -ms since that's the one that I'm familiar with, but there are several others that are widely used. Troff is straightforward for simple formatting but page layout is harder, and the macro packages take care of that, along with providing convenient shorthands for standard formatting operations like paragraphs, headings, numbered items, and so on. Floating figures is an example of something that is challenging to get right, but the macro packages take care of that.

Nroff and troff can generate a variety of printed materials. What kinds of documents did you write in nroff and troff during your time at Bell Labs?

We used nroff and troff for pretty much everything. There were a lot of internal documents at Bell Labs; the Unix manuals were done in nroff and later in troff; a fair number of books used troff (including all books that I have ever written); patent applications were done with nroff (that was the original killer app for Unix internally); and even already-formatted documents for journals long before that became the standard. Lorinda Cherry and I published a paper about eqn in Communications of the ACM in 1975 that was formatted with troff and published in exactly that form; so far as I know, it was the first such paper.

What kinds of documents do you write in groff today?

Groff is a great piece of work. It's compatible with troff, including all the old warts, and it comes with new versions of eqn (equations), tbl (tables), pic (pictures), grap (diagrams) and other standard preprocessors. At the same time, it adds new capabilities, a bigger namespace for user commands, and a variety of convenience features. I am eternally grateful to James Clark for his work on groff, and to the others who continue to maintain it.

Today, my use of groff is entirely for books. Most recently, I have done a second edition of the original Awk book with Al Aho and Peter Weinberger; that should appear in a couple of months. I also did a second edition of Understanding the Digital World, and the Unix: A History and a Memoir three or four years ago. All groff.

What groff macros do you use to write your books?

Groff is just like troff in this respect: it's a toolkit, not a specific set of macros. What I do is to take some basic macro package (-ms in my case), then modify existing commands for headings, titles, and so on, and add new macros for special purposes. For example, I almost always add new macros for things like starting and ending blocks of code; those macros change the font to a monospace font like Courier, set the point size, vertical spacing and indent, turn off line filling, and so on, then revert to normal text at the end. I do similar things for other kinds of displays, and I usually have macros for inline font changes for including monospace program words in running text.

I often supplement all of this with code in Awk or Python to do cross references in text, set up running headers for pages, indexing, and so on. So printing a document is more involved than just running a groff command - it's a shell script with a bunch of steps.

When I write in groff, I find I get into a flow where I don't notice the macros, I just focus on the content. What is your workflow when writing with groff?

My style is perhaps a bit different. You're right that after a bit, you don't see the commands much. But what I do is to edit the text, save it, run a troff command (usually groff with various ancillary tools), and look at the result in a PDF viewer like Preview on a Mac. The whole process only takes maybe 15 to 30 seconds even for a book of a couple of hundred pages, so it's reasonably interactive.

Thanks to Brian Kernighan for talking with me about technical writing with groff. You can find Brian at www.cs.princeton.edu/~bwk