5. Which macro package should I use?

There are a number of macro packages especially designed for use in writing man pages. Usually they are in the groff macro directory /usr/lib/groff/tmac. The file names are tmac.<something>, where <something> is the argument to groff's -m option. Groff will use tmac.<something> when it is given the `-m <something>' option. Often the blank between `-m' and `<something>' is omitted so we may say `groff -man' when we are formatting man pages using the tmac.an macro package. That's the reason for the strange name `tmac.an'. Besides tmac.an there is another popular macro package, tmac.doc, which originated at the University of California at Berkeley. Many BSD man pages use it and it seems that UCB has made it its standard for documentation. The tmac.doc macros are much more flexible but alas, there are manual browsers that will not use them but always call groff -man. For example, all xman programs I have seen will screw up on man pages requiring tmac.doc. So do yourself a favor: use tmac.an -- use of any other macro package is considered harmful. tmac.andoc is a pseudo macro package that takes a look at the source and then loads either tmac.an or tmac.doc. Actually, any man page browser should use it but to this point, not all of them do, so it is best we cling to ye olde tmac.an. Anything I tell you from now on and concerning macros only holds true for tmac.an. If you want to use the tmac.doc macros anyway, have a look at the tutorial sampler, mdoc.samples. Some distros (I'm told) also come with mdoc(7), mdoc.samples(7) and groff_man(7).

The definitive dope for troff, with all macros explained, is the Troff User's Manual, available as html, PostScript (ps, 760K) or Portable Document Format (pdf, 240K). by Jospeh F. Ossanna and Brian W. Kernighan, revised November 1992. AT&T Bell Labs have made it publicly available. Don't forget to check out the late great W. Richard Steven's homepage (famous for Unix Network Programming as well as the TCP/IP Illustrated trilogy), who also has a list of Troff Resources including tbl, eqn, pic and other filters.