1GROFF_TMAC(5) File Formats Manual GROFF_TMAC(5)
2
6 groff_tmac - macro files in the roff typesetting system
7
9 The roff(7) type-setting system provides a set of macro packages suit‐
10 able for special kinds of documents. Each macro package stores its
11 macros and definitions in a file called the package's tmac file. The
12 name is deduced from `TroffMACros'.
13 The tmac files are normal roff source documents, except that they usu‐
15 ally contain only definitions and setup commands, but no text. All
16 tmac files are kept in a single or a small number of directories, the
17 tmac directories.
18
20 groff provides all classical macro packages, some more full packages,
21 and some secondary packages for special purposes.
22 Man Pages
24 man This is the classical macro package for UNIX manual pages
25 (man pages); it is quite handy and easy to use; see
26 groff_man(7).
27 doc
29 mdoc An alternative macro package for man pages mainly used in BSD
30 systems; it provides many new features, but it is not the stan‐
31 dard for man pages; see groff_mdoc(7).
32 Full Packages
34 The packages in this section provide a complete set of macros for writ‐
35 ing documents of any kind, up to whole books. They are similar in
36 functionality; it is a matter of taste which one to use.
37 me The classical me macro package; see groff_me(7).
39 mm The semi-classical mm macro package; see groff_mm(7).
41 mom The new mom macro package, only available in groff. As this is
43 not based on other packages, it can be freely designed. So it
44 is expected to become quite a nice, modern macro package. See
45 groff_mom(7).
46 ms The classical ms macro package; see groff_ms(7).
48 Special Packages
50 The macro packages in this section are not intended for stand-alone
51 usage, but can be used to add special functionality to any other macro
52 package or to plain groff.
53 tty-char
55 Overrides the definition of standard troff characters and some
56 groff characters for tty devices. The optical appearance is
57 intentionally inferior compared to that of normal tty formatting
58 to allow processing with critical equipment.
59 www Additions of elements known from the html format, as being used
61 in the internet (World Wide Web) pages; this includes URL links
62 and mail addresses; see groff_www(7).
63
65 In classical roff systems, there was a funny naming scheme for macro
66 packages, due to a simplistic design in option parsing. Macro packages
67 were always included by option -m; when this option was directly fol‐
68 lowed by its argument without an intervening space, this looked like a
69 long option preceded by a single minus — a sensation in the computer
70 stone age. To make this optically working for macro package names, all
71 classical macro packages choose a name that started with the letter
72 `m', which was omitted in the naming of the macro file.
73 For example, the macro package for the man pages was called man, while
75 its macro file tmac.an. So it could be activated by the argument an to
76 option -m, or -man for short.
77 For similar reasons, macro packages that did not start with an `m' had
79 a leading `m' added in the documentation and in talking; for example,
80 the package corresponding to tmac.doc was called mdoc in the documenta‐
81 tion, although a more suitable name would be doc. For, when omitting
82 the space between the option and its argument, the command line option
83 for activating this package reads -mdoc.
84 To cope with all situations, actual versions of groff(1) are smart
86 about both naming schemes by providing two macro files for the
87 inflicted macro packages; one with a leading `m', the other one without
88 it. So in groff, the man macro package may be specified as on of the
89 following four methods:
90 sh# groff -m man
92 sh# groff -man
93 sh# groff -mman
94 sh# groff -m an
95 Recent packages that do not start with `m' do not use an additional `m'
97 in the documentation. For example, the www macro package may be speci‐
98 fied only as one of the two methods:
99 sh# groff -m www
101 sh# groff -mwww
102 Obviously, variants like -mmwww would not make much sense.
104 A second strange feature of classical troff was to name macro files ac‐
106 cording to tmac.name. In modern operating systems, the type of a file
107 is specified as postfix, the file name extension. Again, groff copes
108 with this situation by searching both anything.tmac and tmac.anything
109 if only anything is specified.
110 The easiest way to find out which macro packages are available on a
112 system is to check the man page groff(1), or the contents of the tmac
113 directories.
114 In groff, most macro packages are described in man pages called
116 groff_[22mname(7), with a leading `m' for the classical packages.
117
119 There are several ways to use a macro package in a document. The clas‐
120 sical way is to specify the troff/groff option -m name at run-time;
121 this makes the contents of the macro package name available. In groff,
122 the file name.tmac is searched within the tmac path; if not found,
123 tmac.name will be searched for instead.
124 Alternatively, it is also possible to include a macro file by adding
126 the request .so filename into the document; the argument must be the
127 full file name of an existing file, possibly with the directory where
128 it is kept. In groff, this was improved by the similar request .mso
129 package, which added searching in the tmac path, just like option -m
130 does.
131 Note that in order to resolve the .so and .mso requests, the roff pre‐
133 processor soelim(1) must be called if the files to be included need
134 preprocessing. This can be done either directly by a pipeline on the
135 command line or by using the troff/groff option -s. man calls soelim
136 automatically.
137 For example, suppose a macro file is stored as
139 /usr/share/groff/1.18.1.4/tmac/macros.tmac and is used in some document
140 called docu.roff.
141 At run-time, the formatter call for this is
143 sh# groff -m macrofile document.roff
145 To include the macro file directly in the document either
147 .mso macrofile.tmac
149 is used or
151 .so /usr/share/groff/1.18.1.4/tmac/macros.tmac
153 In both cases, the formatter is called with
155 sh# troff -s docu.roff
157 If you want to write your own groff macro file, call it whatever.tmac
159 and put it in some directory of the tmac path, see section FILES. Then
160 documents can include it with the .mso request or the option -m.
161
163 A roff(7) document is a text file that is enriched by predefined for‐
164 matting constructs, such as requests, escape sequences, strings, numer‐
165 ic registers, and macros from a macro package. These elements are de‐
166 scribed in roff(7).
167 To give a document a personal style, it is most useful to extend the
169 existing elements by defining some macros for repeating tasks; the best
170 place for this is near the beginning of the document or in a separate
171 file.
172 Macros without arguments are just like strings. But the full power of
174 macros reveals when arguments are passed with a macro call. Within the
175 macro definition, the arguments are available as the escape sequences
176 $1, ..., $9, $[...], $*, and $@, the name under which the macro was
177 called is in $0, and the number of arguments is in register 0; see
178 groff(7).
179 Copy-in Mode
181 The phase when groff reads a macro is called copy-in mode in roff-talk.
182 This is comparable to the C preprocessing phase during the development
183 of a program written in the C language.
184 In this phase, groff interprets all backslashes; that means that all
186 escape sequences in the macro body are interpreted and replaced by
187 their value. For constant expression, this is wanted, but strings and
188 registers that might change between calls of the macro must be protect‐
189 ed from being evaluated. This is most easily done by doubling the
190 backslash that introduces the escape sequence. This doubling is most
191 important for the positional parameters. For example, to print infor‐
192 mation on the arguments that were passed to the macro to the terminal,
193 define a macro named `.print_args', say.
194 .ds midpart was called with
196 .de print_args
197 . tm \f[I]\\$0\f[] \\*[midpart] \\n[.$] arguments:
198 . tm \\$*
199 ..
200 When calling this macro by
202 .print_args arg1 arg2
204 the following text is printed to the terminal:
206 print_args was called with the following 2 arguments:
207 arg1 arg2
208 Let's analyze each backslash in the macro definition. As the position‐
210 al parameters and the number of arguments will change with each call of
211 the macro their leading backslash must be doubled, which results in
212 \\$* and \\[.$]. The same applies to the macro name because it could
213 be called with an alias name, so \\$0.
214 On the other hand, midpart is a constant string, it will not change, so
216 no doubling for \*[midpart]. The \f escape sequences are predefined
217 groff elements for setting the font within the text. Of course, this
218 behavior will not change, so no doubling with \f[I] and \f[].
219 Draft Mode
221 Writing groff macros is easy when the escaping mechanism is temporarily
222 disabled. In groff, this is done by enclosing the macro definition(s)
223 into a pair of .eo and .ec requests. Then the body in the macro defi‐
224 nition is just like a normal part of the document — text enhanced by
225 calls of requests, macros, strings, registers, etc. For example, the
226 code above can be written in a simpler way by
227 .eo
229 .ds midpart was called with
230 .de print_args
231 . tm \f[I]\$0\f[] \*[midpart] \n[.$] arguments:
232 . tm \$*
233 ..
234 .ec
235 Unfortunately, draft mode cannot be used universally. Although it is
237 good enough for defining normal macros, draft mode will fail with ad‐
238 vanced applications, such as indirectly defined strings, registers,
239 etc. An optimal way is to define and test all macros in draft mode and
240 then do the backslash doubling as a final step; do not forget to remove
241 the .eo request.
242 Tips for Macro Definitions
244 · Start every line with a dot, for example, by using the groff request
245 .nop for text lines, or write your own macro that handles also text
246 lines with a leading dot.
247 .de Text
249 . if (\\n[.$] == 0) \
250 . return
251 . nop \)\\$*[rs]
252 ..
253 · Write a comment macro that works both for copy-in and draft mode; for
255 as escaping is off in draft mode, trouble might occur when normal
256 comments are used. For example, the following macro just ignores its
257 arguments, so it acts like a comment line:
258 .de c
260 ..
261 .c This is like a comment line.
262 · In long macro definitions, make ample use of comment lines or empty
264 lines for a better structuring.
265 · To increase readability, use groff's indentation facility for re‐
267 quests and macro calls (arbitrary whitespace after the leading dot).
268 Diversions
270 Diversions can be used to realize quite advanced programming con‐
271 structs. They are comparable to pointers to large data structures in
272 the C programming language, but their usage is quite different.
273 In their simplest form, diversions are multi-line strings, but they get
275 their power when diversions are used dynamically within macros. The
276 information stored in a diversion can be retrieved by calling the di‐
277 version just like a macro.
278 Most of the problems arising with diversions can be avoided if you are
280 conscious about the fact that diversions always deal with complete
281 lines. If diversions are used when the line buffer has not been
282 flashed, strange results are produced; not knowing this, many people
283 get desperate about diversions. To ensure that a diversion works, line
284 breaks should be added at the right places. To be on the secure side,
285 enclose everything that has to do with diversions into a pair of line
286 breaks; for example, by amply using .br requests. This rule should be
287 applied to diversion definition, both inside and outside, and to all
288 calls of diversions. This is a bit of overkill, but it works nicely.
289 [If you really need diversions which should ignore the current partial
291 line, use environments to save the current partial line and/or use the
292 .box request.]
293 The most powerful feature using diversions is to start a diversion
295 within a macro definition and end it within another macro. Then every‐
296 thing between each call of this macro pair is stored within the diver‐
297 sion and can be manipulated from within the macros.
298
300 All macro names must be named name.tmac to fully use the tmac mecha‐
301 nism. tmac.name as with classical packages is possible as well, but
302 deprecated.
303 The macro files are kept in the tmac directories; a colon separated
305 list of these constitutes the tmac path.
306 The search sequence for macro files is (in that order):
308 · the directories specified with troff/groff's -M command line option
310 · the directories given in the $GROFF_TMAC_PATH environment variable
312 · the current directory (only if in unsafe mode, which is enabled by
314 the -U command line switch)
315 · the home directory
317 · a platform-specific directory, being /usr/lib64/groff/site-tmac in
319 this installation
320 · a site-specific (platform-independent) directory, being
322 /usr/share/groff/site-tmac in this installation
323 · the main tmac directory, being /usr/share/groff/1.18.1.4/tmac in this
325 installation
326
328 $GROFF_TMAC_PATH
329 A colon separated list of additional tmac directories in which
330 to search for macro files. See the previous section for a de‐
331 tailed description.
332
334 Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc.
335 This document is distributed under the terms of the FDL (GNU Free Docu‐
337 mentation License) version 1.1 or later. You should have received a
338 copy of the FDL on your system, it is also available on-line at the GNU
339 copyleft site ⟨http://www.gnu.org/copyleft/fdl.html⟩.
340 This document is part of groff, the GNU roff distribution. It was
342 written by Bernd Warken ⟨bwarken@mayn.de⟩; it is maintained by Werner
343 Lemberg ⟨wl@gnu.org⟩.
344
346 A complete reference for all parts of the groff system is found in the
347 groff info(1) file.
348 groff(1)
350 an overview of the groff system.
351 groff_man(7),
353 groff_mdoc(7),
354 groff_me(7),
355 groff_mm(7),
356 groff_mom(7),
357 groff_ms(7),
358 groff_www(7).
359 the groff tmac macro packages.
360 groff(7)
362 the groff language.
363 The Filesystem Hierarchy Standard is available at the FHS web site
365 ⟨http://www.pathname.com/fhs/⟩.
366Groff Version 1.18.1.4 21 August 2002 GROFF_TMAC(5)