groff_tmac - macro files in the roff typesetting system
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'.
The tmac files are normal roff source documents, except
that they usually contain only definitions and setup commands,
but no text. All tmac files are kept in a single
or a small number of directories, the tmac directories.
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.
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
troff -mdoc.
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 content of the tmac
directories. For example, a file called tmac.anything
determines a macro package named anything.
In groff, most macro packages are described in man pages
called groff_<name>(7), with a leading `m' for the classical
packages.
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 tmac.name available as
described in the section NAMING.
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 additionally
searches the tmac path for the filename.
Note that in order to resolve the .so and .mso requests
the roff preprocessor soelim must be called. This can be
done either directly by a pipeline on the command line or
by using the -s option of groff.
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/tmac/tmac.macros 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
.mso tmac.macros
is used or
.so /usr/share/groff/tmac/tmac.macros
In both cases, the formatter is called with
groff -s docu.roff
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)).
Besides being a good reminder for the user, some formatters
(like the man(1) program) are even able to automatically
start the preprocessors specified in the preprocessor
word, but do not bet on this.
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
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.
o Double all functional backslashes, `\' -> `\\'.
o All printable backslashes must be written as `\e'.
o Escape all dots, `.' -> `\.'.
o Make ample use of the non-printable character `\&' in
text parts, esp. before `\' and at the beginning of a
line, but not before a delayed command.
o Use the character `@' in temporary variable names.
o Test your macros for text and graphical devices, e.g.,
latin1 and ps.
All macro names that want to use the tmac mechanism must
be named according to the form tmac.name.
The macro files are kept in the tmac directories, all of
which constitue the tmac path. In accordance with the
Filesystem Hierarchy Standard (FHS), the standard tmac
directory location for groff is /usr/share/groff/tmac, a
local installation will use /usr/local/share/groff/tmac.
Older systems used a subdirectory of /usr/lib. Independently
of the default tmac path, the tmac path actually
used by a document can always be set by a shell environment
variable, cf. section ENVIRONMENT.
GROFF_TMAC_PATH
A colon separated list of tmac directories in which
to search for macro files, the tmac path. If unset
a default path is used as is outlined in the FILES
section.
The groff documentation is in evolution at the moment. It
is possible that small inconsistencies between different
documents exist temporarily.
This document is part of groff, the GNU roff distribution.
It was written by Bernd Warken <[email protected]>.
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
<http://www.gnu.org/copyleft/fdl.html>.
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.
The groff tmac macro packages are groff_man(7),
groff_markup(7), groff_mdoc(7), groff_mdoc.samples(7),
groff_me(7), groff_mm(7), groff_mmroff(7), groff_ms(7),
groff_msafer(7).
The groff language is described in groff(7) and the formatters
in groff(1), troff(1).
The Filesystem Hierarchy Standard (FHS) is available at
http://www.pathname.com/fhs/.
Groff Version 1.16.1 April 8, 2001 GROFF_TMAC(5)
[ Back ] |
