Manpages

GROFF_TMAC

NAME

DESCRIPTION

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.  

NAMING

By a similar reasoning, macro packages that did not start with an were often referred to by adding an e.g., the package corresponding to tmac.doc was called mdoc because the command-line for activating it reads

Rtroff -mdoc.

Actual versions of groff(1) provide both naming schemes for the inflicted macro packages, with and without the leading So in groff, the man macro package may be specified as

Rgroff -m man,
Rgroff -man,
Rgroff -mman,or
Rgroff -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.

In groff, most macro packages are described in man pages called groff_<name>(7), with a leading for the classical packages.  

INCLUSION

It is also possible to include the macro file into the document by using the groff requests or For 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 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, will try to open tmac.name instead and vice versa.

Note that in order to resolve the and requests the roff preprocessor must be called if the files to be included needs preprocessing. This can be done either directly by a pipeline on the command line or by using the option of

You can also supply the letter 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

To include the macro file directly in the document either

.mso macros.tmac

.so /usr/share/groff/1.17.2/tmac/macros.tmac

In both cases, the formatter is called with

groff -s docu.roff

CONVENTION

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, (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 MACRO FILE

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 request or the 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

*

Escape all dots, ->

*

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.

*

Use the character in temporary variable names.

*

Test your macros for text and graphical devices, e.g., latin1 and ps.

FILES

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:

/usr/share/groff/site-tmac
/usr/lib/groff/site-tmac
/usr/share/groff/1.17.2/tmac

ENVIRONMENT

GROFF_TMAC_PATH

A colon separated list of additional tmac directories in which to search for macro files. See the previous section for a detailed description.

BUGS

AUTHOR

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

SEE ALSO

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_mwww(7), groff_mdoc(7), groff_mdoc.samples(7), groff_me(7), groff_mm(7), groff_mmroff(7), and groff_ms(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/.

Index

NAME

DESCRIPTION

NAMING

INCLUSION

CONVENTION

WRITING A MACRO FILE

FILES

ENVIRONMENT

BUGS

AUTHOR

SEE ALSO