Links about troff

Troff is a typesetting system for Unix, arguably Unix’s first “killer app”. It is old and weird and clunky, but I like it.

For reference, I use the version of troff in Plan 9. If you’re not on Plan 9 (and can’t or don’t want to use plan9ports), I recommend the version from The Heirloom Documentation Tools.

General Reference

The troff user’s manual (archive) is worth reading, even though the majority of documents can get away with just using the macro packages. It’s worth getting a rough understanding of how things work if you even maybe might want to do anything outside them some day (heck, even just inline font changes are sometimes nicer).

Macros and Helper Programs

Most uses of troff rely on existing macro packages. The general pattern for troff users is that you start off writing entirely using an existing macro package, then find you want to do a one-off thing that requires raw troff, and you eventually (if you use it long enough) build up your own small collection of macros.

Almost certainly the most widely used are the man macros, used for writing unix manual pages (although some systems have switched over to the newer mdoc). The ms macros are the most widely used for writing documents; mm is the other popular old-school one for that.

troff.org had a decent collection of macros (archive), although by no means exhaustive. I wish it was more complete, but it’s a nice start. There are versions of most of these that work on heirloom troff, and many of those will work on Plan 9 troff, but some are gnu specific. I wish troff.org called out the differences more clearly.

There are also helper programs for troff, which generally have a paired macro that goes with them. This allows you do have a “little language” for, say, defining an equation, and the eqn program and corresponding macro can get you a nicely typeset version, without you having to worry about the troff details.

Troff.org has info on some companion programs (archive), too, although I’m a bit surprised not to see more here. I’d really like to get something like dformat working on Plan 9.

I tried vgrind but couldn’t really get it to work the way I wanted. I’ll come back to that at some point.

I don’t really like the -me macros: they break too many conventions without much purpose. They just don’t feel right to my understanding of troff, although that’s not really any sort of fundamental critique. Regardless, the paper and Reference Manual are good reading.

W. Richard Stevens has a good list of troff resources (archive).

One of my two current troff projects right now is to understand all the bibliography/indexing bits better. There’s ptx and mptx for permuted indexes. The 9fans threads on troff citations and bibliographies (archive) and troff bibliography (archive) were helpful, although I wish there were a more concrete “how to” in either.

There is a USENET cookbook (archive) (pdf (archive)) made from recipes submitted to alt.gourmand using a particular troff macro.

Implementations

Most unix-like systems already come with some version of troff (and nroff), and in most cases what you have is probably fine. I am most used to Plan 9’s version, which was the first to handle Unicode (not all do, even today). I use it on both Plan 9 and Unix, via Plan 9 from User Space.

Heirloom troff is my second-favorite implementation, and better in a lot of ways. If I wasn’t already running plan9port for other reasons, I’d probably use heirloom on Unix. In addition to the core troff/nroff engine, they offer most of the They produce some other neat tools as well, although I don’t use any of those.

Neatroff is another good option. It’s more of a fresh start, with a much more modern code organizaiton. I think the biggest win over Plan 9’s is the ability to use OpenType fonts. I haven’t played around with it enough to make a solid comparison, but my impression is that it’s narrower in scope than the above two options.