View Source: groff_tmac(5) - Waikato Linux Users Group

Edit PageHistory Diff Info LikePages
GROFF_TMAC
!!!GROFF_TMAC
NAME
DESCRIPTION
NAMING
INCLUSION
CONVENTION
WRITING A MACRO FILE
FILES
ENVIRONMENT
BUGS
AUTHOR
SEE ALSO
----
!!NAME


groff_tmac - macro files in the roff typesetting system
!!DESCRIPTION


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 `__T__roff __MAC__ros'.


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


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


__troff -m__''doc''.


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 -m__''an'',__
groff -m__''man'', 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''.


In ''groff'', most macro packages are described in man
pages called groff_(7), with a leading
`m' for the classical packages.
!!INCLUSION


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.


Note that in order to resolve the .so and .mso requests the
roff preprocessor soelim 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
-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/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


.mso macros.tmac


is used or


.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, `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 MACRO FILE


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.


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


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:


/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


The groff documentation is in evolution at the moment. It is
possible that small inconsistencies between different
documents exist temporarily.
!!AUTHOR


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


''''.
!!SEE ALSO


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_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/__.
----
3 pages link to groff_tmac(5):
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.
Last edited on Tuesday, June 4, 2002 12:30:37 am by "perry"
Edit PageHistory Diff Info LikePages