5 This file is part of groff, the GNU roff type-setting system.
7 Copyright (C) 2000 Free Software Foundation, Inc.
8 written by Bernd Warken <bwarken@mayn.de>
10 Last update: 17 May 2000
12 Permission is granted to copy, distribute and/or modify this document
13 under the terms of the GNU Free Documentation License, Version 1.1 or
14 any later version published by the Free Software Foundation; with the
15 Invariant Sections being this .ig-section and AUTHOR, with no
16 Front-Cover Texts, and with no Back-Cover Texts.
18 A copy of the Free Documentation License is included as a file called
19 FDL in the main directory of the groff source package.
22 .\" --------------------------------------------------------------------
24 .\" --------------------------------------------------------------------
33 .\" text lines in macro definitions or bracketed sections \{...\}
42 . ds @tmp@ \fB\\$1\fP\fI\\$2\fP
44 . text \\*[@tmp@]\fR\\$*\fP
50 . ds @tmp@ `\f(CB\\$1\fP'
57 . ds @tmp@ \f(CB\\$1\fP
63 .als shellcommand option
66 . ds @tmp@ \f(CI\\$1\fP
73 . ds @tmp@ \f(CB\\$1\fP
79 .\" --------------------------------------------------------------------
81 .\" --------------------------------------------------------------------
82 .TH GROFF_TMAC @MAN5EXT@ "@MDATE@" "Groff Version @VERSION@"
84 groff_tmac \- macro files in the roff typesetting system
85 .\" --------------------------------------------------------------------
87 .\" --------------------------------------------------------------------
90 type-setting system provides a set of macro packages suitable for
91 special kinds of documents. Each macro package stores its macros and
92 definitions in a file called the package's
94 The name is deduced from
98 The tmac files are normal roff source documents, except that they
99 usually contain only definitions and setup commands, but no text. All
100 tmac files are kept in a single or a small number of directories, the
103 .\" --------------------------------------------------------------------
105 .\" --------------------------------------------------------------------
106 In classical roff systems, there was a funny naming scheme.
107 If the name of a macro package started with
109 this letter was omitted, e.g., the macro package for the man pages
115 (note that in recent versions of groff this file is called
119 By a similar reasoning, macro packages that did not start with an
121 were often referred to by adding an
123 e.g., the package corresponding to
127 because the command-line for activating it reads
130 .BIR "troff\ \-m" doc .
134 .BR groff (@MAN1EXT@)
135 provide both naming schemes for the inflicted macro packages, with and
142 macro package may be specified as
145 .BIR "groff\ \-m\ " man ,
147 .BIR "groff\ \-m" an ,
149 .BIR "groff\ \-m" man , or
151 .BIR "groff\ \-m " an .
154 The easiest way to find out which macro packages are available on a
155 system is to check the contents of the
158 For example, a file called
162 determines a macro package named
167 most macro packages are described in man pages called
168 .BR groff_<name> (@MAN7EXT@),
171 for the classical packages.
172 .\" --------------------------------------------------------------------
174 .\" --------------------------------------------------------------------
175 There are several ways to use a macro package in documents. At
176 run-time, the groff option
179 makes the definitions in the macro file
181 available as described in the section
183 If this file isn't found,
187 It is also possible to include the macro file into the document by using
194 the full filename of the macro file must be specified \(em including the
195 directory where it is kept.
196 If the macro file is stored in one of the tmac directories it is more
199 instead because it searches the tmac path for the filename.
200 Additionally, if the file name to be included has the form
206 instead and vice versa.
208 Note that in order to resolve the
212 requests the roff preprocessor
214 must be called if the files to be included needs preprocessing.
215 This can be done either directly by a pipeline on the command line or by
219 .shellcommand groff .
221 You can also supply the letter
223 in the preprocessor word as described in section
226 For example, suppose a macro file is stored as
227 .I @MACRODIR@/macros.tmac
228 and is used in some document called
231 At run-time, the formatter call for this is
235 .shellcommand "groff\ \-m"
241 To include the macro file directly in the document either
250 \&\.so @MACRODIR@/macros.tmac
254 In both cases, the formatter is called with
261 .\" --------------------------------------------------------------------
263 .\" --------------------------------------------------------------------
265 There is a convention that is supported by many modern roff
268 described in the following.
270 If the first line in a document is a comment, the first word (after the
271 comment characters and a blank) constitutes the
274 That means that the letters of this word are interpreted as
275 abbreviations for those preprocessor commands that should be run
276 when formatting the document. Mostly, only the letters corresponding to
277 the options for the preprocessors are recognized,
286 .BR roff (@MAN7EXT@)).
288 Besides being a good reminder for the user, some formatters (like the
290 program) are even able to automatically start the preprocessors
291 specified in the preprocessor word, but do not bet on this.
292 .\" --------------------------------------------------------------------
293 .SH "WRITING A MACRO FILE"
294 .\" --------------------------------------------------------------------
295 Writing a groff macro file is easy. Design a set of macros, strings,
296 registers, etc. Store them in a single file. Documents that use the
297 macros include this macro file with the
299 request as described in the
303 To use the tmac functionality, call the macro file
307 ) and put it in some directory of the tmac path, cf. section
309 Then documents can include it with the
312 .shellcommand "groff\ \-m"
313 option as described in the
317 If your macros might be of general usage contact the groff maintainers
318 to have them included in the groff
322 Some general guidelines might be helpful in writing macros.
324 Double all functional backslashes,
329 All printable backslashes must be written as
337 Make ample use of the non-printable character
339 in text parts, esp. before
341 and at the beginning of a line, but not before a delayed command.
345 in temporary variable names.
347 Test your macros for text and graphical devices, e.g.,
351 .\" --------------------------------------------------------------------
353 .\" --------------------------------------------------------------------
354 All macro names must be named
358 to use the tmac mechanism.
360 The macro files are kept in the
363 all of which constitute the
367 The elements of the search path for macro files are (in that order):
369 the directories specified with troff's resp. groff's
373 the directories given in the
377 the current directory
379 a site-specific (platform-independent) directory, a platform-specific
380 directory, and the main tmac directory:
387 .\" --------------------------------------------------------------------
389 .\" --------------------------------------------------------------------
392 A colon separated list of additional tmac directories in which to search
394 See the previous section for a detailed description.
395 .\" --------------------------------------------------------------------
397 .\" --------------------------------------------------------------------
398 The groff documentation is in evolution at the moment. It is possible
399 that small inconsistencies between different documents exist
401 .\" --------------------------------------------------------------------
403 .\" --------------------------------------------------------------------
404 This document is part of groff, the GNU roff distribution. It was
405 written by Bernd Warken <bwarken@mayn.de>.
407 It is distributed under the terms of the FDL (GNU Free Documentation
408 License) version 1.1 or later. You should have received a copy of the
409 FDL on your system, it is also available on-line under
412 .IR <http://www.gnu.org/copyleft/fdl.html> .
414 .\" --------------------------------------------------------------------
416 .\" --------------------------------------------------------------------
417 The authoritative source of information for all details of the groff
422 For a groff overview, see
426 in the groff source package.
428 The groff tmac macro packages are
429 .BR groff_man (@MAN7EXT@),
430 .BR groff_markup (@MAN7EXT@),
431 .BR groff_mdoc (@MAN7EXT@),
432 .BR groff_mdoc.samples (@MAN7EXT@),
433 .BR groff_me (@MAN7EXT@),
434 .BR groff_mm (@MAN7EXT@),
435 .BR groff_mmroff (@MAN7EXT@),
437 .BR groff_ms (@MAN7EXT@).
439 The groff language is described in
440 .BR groff (@MAN7EXT@)
441 and the formatters in
442 .BR groff (@MAN1EXT@),
443 .BR troff (@MAN1EXT@).
445 The Filesystem Hierarchy Standard (FHS) is available at
446 .BR http://www.pathname.com/fhs/ .