How to use troff & friends

This not a complete guide to using troff. There is excellent reference material out there, and some very good tutorials. I do wish there were “gentler” introductions, but that’s outside the scope of this document (at least for now). Rather, this is a set of tips, notes, tricks &. from my use — largely for my reference later (I recently couldn’t figure something out and eventually found the answer in a post to a mailing list from 13 years ago… written by me).

I use the troff version found on Plan 9 and plan9ports, with the associated macros, as a starting point. There are likely some differences in the specific macros on other troff distributions. Unfortunately many external macros make use of groff-specific extensions, which aren’t supported here. That’s a shame; there are some which look very promising. I haven’t used it, but mom looks particularly interesting, but is heavily tied to groff. I’d like to try BSD’s mdoc at some point.

Neat Usage

Adding a signature

I used to use troff to generate contracts and invoices. The contracts all contain my digital signature - that is, a postscript image of my signature - like so:

.BP /usr/a/Pictures/sigs/signature.ps .5 "" "" "" l

I generate postscript for these documents like so:

troff -mm -mpictures foo.mm | lp -d stdout | addpsfonts > foo.ps

(I no longer have to generate invoices and haven’t had to generate a contract in a while, but I’d still use this same method.)

Useful Macros

Inserting pictures

I use this wrapper for mpictures(7), which is derived from the one in /sys/doc/sam/sam.ms.

.\" Use like XP filename size allignment
.de XP
.ie h .html - <center><img src="\\$1.png" width="500" height="500" alt="\\$4" /></center>
.el .BP \\$1.ps \\$2 \\$2 \\$3 "" \\$3 "\\$4"
..

I would like to have the html version automatically point to a thumbnail and link to the reference picture, and have the mkfile ensure the thumbnails are generated, but haven’t gotten there yet. This doesn’t change the note about .EP, below.

Nota Bene

mhtml(7) replaces the definition of .FS in ms(7), but incompletely

I spent a foolish amount of time trying to figure out why, when using ms(7), footnotes in the abstract worked as expected but those in the body vanished. I saw that ms actually defines FS, uses that definition in the abstract, and then replaces it with a previously-defined FJ when the first body paragraph starts. But I couldn’t understand why FS/FE worked as expected but FJ/FK didn’t.

The answer, it turns out, is that neither works. The FS/FE I was picking up were those defined by mhtml(7). The definitions in mhtml overwrites those in ms, making those calls work, but when ms moves FJ/FK onto FS/FE, they stop working. The best solution I came up with is simply repeating the definitions of FS/FE in tmac.html as FJ/FK.

This is imperfect, as the formatting of those footnotes is not the same. I’m not sure how much this relates to the differences noted in htmlroff(7), but it works well enough for me for now.

mpictures(7) wants .EP more than it implies.

Reading mpictures(7), this line in .EP’s description threw me:

.EP is usually called implicitly by a trap at frame bottom.

I’m not sure what “usually” means here, but I find I need to explicitly include .EP more often than I’d expected. Omitting it inside a keep gave me errors like this:

troff: diversion KK invokes itself during diversion; tll-rs232.ms:72
stack: RQ KE 
troff: lost diversion ; tll-rs232.ms:71
stack: XF FO 
troff: exit 64

This seems to relate to troff wrapping text around the picture, but I wasn’t able to nail down specifics. I simply avoid the problem by calling .EQ explicitly after the text I’m trying to wrap around it, before ending any keep.

References

See also: [troff_links].

Troff Users’s Manual — The original Computing Science Technical Report No. 54 from Ossanna and Kernighan, revised. This is the basis for Plan 9’s /sys/doc/troff.ms.

Brian Kernighan’s troff tutorial is probably the best starting point for raw troff. troff.org has postscript available.

While I’ve mostly switched back to using the ms(7) macros — mostly because htmlroff and mhtml do a better job with them — I had mild preference for the output from mm(7), originally from the Documenter’s Workbench. Here’s a good [overview for mm]. That site also provides a bit of history on mm, as well.

The Heirloom Documentation Tools contains a version of troff and friends I’d likely be using if I weren’t on Plan 9 and didn’t want to deal with plan9port for whatever reason.

troff.org has lots of additional references, including to other macros.