Which macro package should I use?

Linux Man Page Howto
Prev |  | Next

# 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.

Prev | Home | Next
How do I document several programs/functions in a single man page? |  | What preprocessors may I use?