The roff(7) type-setting system provides a set of macro packages suitable for special kinds of documents. Each macro package stores its macros and definitions in a file called the package's tmac file. The name is deduced from `Troff MACros'.
In classical roff systems, there was a funny naming scheme. If the name of a macro package started with `m' this letter was omitted, e.g., the macro package for the man pages man was called an and its macro file tmac.an (note that in recent versions of groff this file is called an.tmac instead).
By a similar reasoning, macro packages that did not start with an `m' were often referred to by adding an `m', e.g., the package corresponding to tmac.doc was called mdoc because the command-line for activating it reads
Actual versions of groff(1) provide both naming schemes for the inflicted macro packages, with and without the leading `m'. So in groff, the man macro package may be specified as
groff -m man, groff -man, groff -mman, or groff -m an.
The easiest way to find out which macro packages are available on a system is to check the contents of the tmac directories. For example, a file called tmac.anything or anything.tmac determines a macro package named anything.
There are several ways to use a macro package in documents. At run-time, the groff option -m name makes the definitions in the macro file name.tmac available as described in the section NAMING. If this file isn't found, tmac.name will be searched.
It is also possible to include the macro file into the document by using the groff requests .so or .mso. For .so the full filename of the macro file must be specified -- including the directory where it is kept. If the macro file is stored in one of the tmac directories it is more convenient to use .mso instead because it searches the tmac path for the filename. Additionally, if the file name to be included has the form name.tmac and it isn't found, .mso will try to open tmac.name instead and vice versa.
You can also supply the letter `s' in the preprocessor word as described in section CONVENTION.
For example, suppose a macro file is stored as /usr/share/groff/1.17.2/tmac/macros.tmac and is used in some document called docu.roff.
At run-time, the formatter call for this is
groff -m macros docu.roff
To include the macro file directly in the document either
is used or
In both cases, the formatter is called with
There is a convention that is supported by many modern roff type-setters: the preprocessor word described in the following.
If the first line in a document is a comment, the first word (after the comment characters and a blank) constitutes the preprocessor word. That means that the letters of this word are interpreted as abbreviations for those preprocessor commands that should be run when formatting the document. Mostly, only the letters corresponding to the options for the preprocessors are recognized, `e', `G', `g', `p', `R', `s', and `t' (see roff(7)).
Writing a groff macro file is easy. Design a set of macros, strings, registers, etc. Store them in a single file. Documents that use the macros include this macro file with the .so request as described in the INCLUSION section.
To use the tmac functionality, call the macro file whatever.tmac (or tmac.whatever) and put it in some directory of the tmac path, cf. section FILES. Then documents can include it with the .mso request or the groff -m option as described in the INCLUSION section.
If your macros might be of general usage contact the groff maintainers to have them included in the groff contrib source directory.
Some general guidelines might be helpful in writing macros.
Double all functional backslashes, `' -
All printable backslashes must be written as `e'.
Escape all dots, `.' -
Make ample use of the non-printable character `
Use the character `@' in temporary variable names.
All macro names must be named name.tmac or tmac.name to use the tmac mechanism.
The macro files are kept in the tmac directories, all of which constitute the tmac path.
The elements of the search path for macro files are (in that order):
the directories specified with troff's resp. groff's -M command line option
the directories given in the GROFF_TMAC_PATH environment variable
the current directory (only if in unsafe mode using the -U command line switch)
the home directory
a site-specific (platform-independent) directory, a platform-specific directory, and the main tmac directory:
This document is part of groff, the GNU roff distribution. It was written by Bernd Warken
It is distributed under the terms of the FDL (GNU Free Documentation License) version 1.1 or later. You should have received a copy of the FDL on your system, it is also available on-line under
The authoritative source of information for all details of the groff system is the groff info(1) file.
For a groff overview, see roff(7) and the file README in the groff source package.