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. Note that it is not
22 possible to use multiple primary macro packages at the same time; say‐
23 ing e.g.
24 sh# groff -m man -m ms foo
26 or
28 sh# groff -m man foo -m ms bar
30 fails. Exception to this is the use of man pages written with either
32 the mdoc or the man macro package. See below the description of the
33 andoc.tmac file.
34 Man Pages
36 man This is the classical macro package for UNIX manual pages
37 (man pages); it is quite handy and easy to use; see
38 groff_man(7).
39 doc
41 mdoc An alternative macro package for man pages mainly used in BSD
42 systems; it provides many new features, but it is not the stan‐
43 dard for man pages; see groff_mdoc(7).
44 andoc
46 mandoc Use this file in case you don't know whether the man macros or
47 the mdoc package should be used. Multiple man pages (in either
48 format) can be handled.
49 Full Packages
51 The packages in this section provide a complete set of macros for writ‐
52 ing documents of any kind, up to whole books. They are similar in
53 functionality; it is a matter of taste which one to use.
54 me The classical me macro package; see groff_me(7).
56 mm The semi-classical mm macro package; see groff_mm(7).
58 mom The new mom macro package, only available in groff. As this is
60 not based on other packages, it can be freely designed. So it
61 is expected to become quite a nice, modern macro package. See
62 groff_mom(7).
63 ms The classical ms macro package; see groff_ms(7).
65 Language-specific Packages
67 cs This file adds support for Czech localization, including the
68 main macro packages (me, mom, mm, and ms).
69 Note that cs.tmac sets the input encoding to latin-2.
71 de
73 den German localization support, including the main macro packages
74 (me, mom, mm, and ms).
75 de.tmac selects hyphenation patterns for traditional orthogra‐
77 phy, and den.tmac does the same for the new orthography (`Recht‐
78 schreibreform'). It should be used as the last macro package on
79 the command line.
80 fr This file adds support for French localization, including the
82 main macro packages (me, mom, mm, and ms). Example:
83 sh# groff -ms -mfr foo.ms > foo.ps
85 Note that fr.tmac sets the input encoding to latin-9 to get
87 proper support of the `oe' ligature.
88 sv Swedish localization support, including the me, mom, and ms
90 macro packages. Note that Swedish for the mm macros is handled
91 separately; see groff_mmse(7). It should be used as the last
92 macro package on the command line.
93 Input Encodings
95 latin1
96 latin2
97 latin5
98 latin9 Various input encodings supported directly by groff. Normally,
99 this macro is loaded at the very beginning of a document or
100 specified as the first macro argument on the command line. roff
101 loads latin1 by default at start-up. Note that these macro
102 packages don't work on EBCDIC hosts.
103 cp1047 Encoding support for EBCDIC. On those platforms it is loaded
105 automatically at start-up. Due to different character ranges
106 used in roff it doesn't work on architectures which are based on
107 ASCII.
108 Note that it can happen that some input encoding characters are not
110 available for a particular output device. For example, saying
111 groff -Tlatin1 -mlatin9 ...
113 fails if you use the Euro character in the input. Usually, this limi‐
115 tation is present only for devices which have a limited set of output
116 glyphs (-Tascii, -Tlatin1); for other devices it is usually sufficient
117 to install proper fonts which contain the necessary glyphs.
118 Special Packages
120 The macro packages in this section are not intended for stand-alone
121 usage, but can be used to add special functionality to any other macro
122 package or to plain groff.
123 60bit Provide some macros for addition, multiplication, and division
125 of 60bit integers (allowing safe multiplication of 30bit inte‐
126 gers, for example).
127 ec Switch to the EC and TC font families. To be used with
129 grodvi(1) – this man page also gives more details of how to use
130 it.
131 papersize
133 This macro file is already loaded at start-up by troff so it
134 isn't necessary to call it explicitly. It provides an interface
135 to set the paper size on the command line with the option
136 -dpaper=size. Possible values for size are the same as the pre‐
137 defined papersize values in the DESC file (only lowercase; see
138 groff_font(5) for more) except a7-d7. An appended l (ell) char‐
139 acter denotes landscape orientation. Examples: a4, c3l, let‐
140 terl.
141 Most output drivers need additional command line switches -p and
143 -l to override the default paper length and orientation as set
144 in the driver specific DESC file. For example, use the follow‐
145 ing for PS output on A4 paper in landscape orientation:
146 sh# groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps
148 pic This file provides proper definitions for the macros PS and PE,
150 needed for the pic(1) preprocessor. They center each picture.
151 Use it only if your macro package doesn't provide proper defini‐
152 tions for those two macros (actually, most of them already do).
153 pspic A single macro is provided in this file, PSPIC, to include a
155 PostScript graphic in a document. The following output devices
156 support inclusion of PS images: -Tps, -Tdvi, -Thtml, and
157 -Txhtml; for all other devices the image is replaced with a hol‐
158 low rectangle of the same size. This macro file is already
159 loaded at start-up by troff so it isn't necessary to call it
160 explicitly.
161 Syntax:
163 .PSPIC [-L|-R|-C|-I n] file [width [height]]
165 file is the name of the PostScript file; width and height give
167 the desired width and height of the image. If neither a width
168 nor a height argument is specified, the image's natural width
169 (as given in the file's bounding box) or the current line length
170 is used as the width, whatever is smaller. The width and height
171 arguments may have scaling indicators attached; the default
172 scaling indicator is i. This macro scales the graphic uniformly
173 in the x and y directions so that it is no more than width wide
174 and height high. Option -C centers the graphic horizontally,
175 which is the default. The -L and -R options cause the graphic
176 to be left-aligned and right-aligned, respectively. The -I
177 option causes the graphic to be indented by n (default scaling
178 indicator is m).
179 For use of .PSPIC within a diversion it is recommended to extend
181 it with the following code, assuring that the diversion's width
182 completely covers the image's width.
183 .am PSPIC
185 . vpt 0
186 \h'(\\n[ps-offset]u + \\n[ps-deswid]u)'
187 . sp -1
188 . vpt 1
189 ..
190 ptx A single macro is provided in this file, xx, for formatting per‐
192 muted index entries as produces by the GNU ptx(1) program. In
193 case you need a different formatting, copy the macro into your
194 document and adapt it to your needs.
195 trace Use this for tracing macro calls. It is only useful for debug‐
197 ging. See groff_trace(7).
198 tty-char
200 Overrides the definition of standard troff characters and some
201 groff characters for TTY devices. The optical appearance is
202 intentionally inferior compared to that of normal TTY formatting
203 to allow processing with critical equipment.
204 www Additions of elements known from the HTML format, as used in the
206 internet (World Wide Web) pages; this includes URL links and
207 mail addresses; see groff_www(7).
208
210 Classical roff systems were designed before the conventions of the mod‐
211 ern C getopt(3) call evolved, and used a naming scheme for macro pack‐
212 ages that looks odd to modern eyes. Macro packages were always included
213 with the option -m; when this option was directly followed by its argu‐
214 ment without an intervening space, this looked like a long option pre‐
215 ceded by a single minus — a sensation in the computer stone age. To
216 make this invocation form work, classical troff macro packages used
217 names that started with the letter `m', which was omitted in the naming
218 of the macro file.
219 For example, the macro package for the man pages was called man, while
221 its macro file tmac.an. So it could be activated by the argument an to
222 option -m, or -man for short.
223 For similar reasons, macro packages that did not start with an `m' had
225 a leading `m' added in the documentation and in speech; for example,
226 the package corresponding to tmac.doc was called mdoc in the documenta‐
227 tion, although a more suitable name would be doc. For, when omitting
228 the space between the option and its argument, the command line option
229 for activating this package reads -mdoc.
230 To cope with all situations, actual versions of groff(1) are smart
232 about both naming schemes by providing two macro files for the
233 inflicted macro packages; one with a leading `m' the other one without
234 it. So in groff, the man macro package may be specified as on of the
235 following four methods:
236 sh# groff -m man
238 sh# groff -man
239 sh# groff -mman
240 sh# groff -m an
241 Recent packages that do not start with `m' do not use an additional `m'
243 in the documentation. For example, the www macro package may be speci‐
244 fied only as one of the two methods:
245 sh# groff -m www
247 sh# groff -mwww
248 Obviously, variants like -mmwww would not make much sense.
250 A second strange feature of classical troff was to name macro files in
252 the form tmac.name. In modern operating systems, the type of a file is
253 specified as a postfix, the file name extension. Again, groff copes
254 with this situation by searching both anything.tmac and tmac.anything
255 if only anything is specified.
256 The easiest way to find out which macro packages are available on a
258 system is to check the man page groff(1), or the contents of the tmac
259 directories.
260 In groff, most macro packages are described in man pages called
262 groff_[22mname(7), with a leading `m' for the classical packages.
263
265 There are several ways to use a macro package in a document. The clas‐
266 sical way is to specify the troff/groff option -m name at run-time;
267 this makes the contents of the macro package name available. In groff,
268 the file name.tmac is searched within the tmac path; if not found,
269 tmac.name is searched for instead.
270 Alternatively, it is also possible to include a macro file by adding
272 the request .so filename into the document; the argument must be the
273 full file name of an existing file, possibly with the directory where
274 it is kept. In groff, this was improved by the similar request .mso
275 package, which added searching in the tmac path, just like option -m
276 does.
277 Note that in order to resolve the .so and .mso requests, the roff pre‐
279 processor soelim(1) must be called if the files to be included need
280 preprocessing. This can be done either directly by a pipeline on the
281 command line or by using the troff/groff option -s. man calls soelim
282 automatically.
283 For example, suppose a macro file is stored as
285 /usr/share/groff/1.20.1/tmac/macros.tmac
287 and is used in some document called docu.roff.
289 At run-time, the formatter call for this is
291 sh# groff -m macros docu.roff
293 To include the macro file directly in the document either
295 .mso macros.tmac
297 is used or
299 .so /usr/share/groff/1.20.1/tmac/macros.tmac
301 In both cases, the formatter should be called with option -s to invoke
303 soelim.
304 sh# groff -s docu.roff
306 If you want to write your own groff macro file, call it whatever.tmac
308 and put it in some directory of the tmac path, see section FILES. Then
309 documents can include it with the .mso request or the option -m.
310
312 A roff(7) document is a text file that is enriched by predefined for‐
313 matting constructs, such as requests, escape sequences, strings,
314 numeric registers, and macros from a macro package. These elements are
315 described in roff(7).
316 To give a document a personal style, it is most useful to extend the
318 existing elements by defining some macros for repeating tasks; the best
319 place for this is near the beginning of the document or in a separate
320 file.
321 Macros without arguments are just like strings. But the full power of
323 macros reveals when arguments are passed with a macro call. Within the
324 macro definition, the arguments are available as the escape sequences
325 \$1, ..., \$9, \$[...], \$*, and \$@, the name under which the macro
326 was called is in \$0, and the number of arguments is in register
327 \n[.$]; see groff(7).
328 Copy-in Mode
330 The phase when groff reads a macro is called copy-in mode or copy mode
331 in roff-talk. This is comparable to the C preprocessing phase during
332 the development of a program written in the C language.
333 In this phase, groff interprets all backslashes; that means that all
335 escape sequences in the macro body are interpreted and replaced by
336 their value. For constant expressions, this is wanted, but strings and
337 registers that might change between calls of the macro must be pro‐
338 tected from being evaluated. This is most easily done by doubling the
339 backslash that introduces the escape sequence. This doubling is most
340 important for the positional parameters. For example, to print infor‐
341 mation on the arguments that were passed to the macro to the terminal,
342 define a macro named `.print_args', say.
343 .ds midpart was called with
345 .de print_args
346 . tm \f[I]\\$0\f[] \*[midpart] \\n[.$] arguments:
347 . tm \\$*
348 ..
349 When calling this macro by
351 .print_args arg1 arg2
353 the following text is printed to the terminal:
355 print_args was called with the following 2 arguments:
357 arg1 arg2
358 Let's analyze each backslash in the macro definition. As the posi‐
360 tional parameters and the number of arguments change with each call of
361 the macro their leading backslash must be doubled, which results in
362 \\$* and \\[.$]. The same applies to the macro name because it could
363 be called with an alias name, so \\$0.
364 On the other hand, midpart is a constant string, it does not change, so
366 no doubling for \*[midpart]. The \f escape sequences are predefined
367 groff elements for setting the font within the text. Of course, this
368 behavior does not change, so no doubling with \f[I] and \f[].
369 Draft Mode
371 Writing groff macros is easy when the escaping mechanism is temporarily
372 disabled. In groff, this is done by enclosing the macro definition(s)
373 into a pair of .eo and .ec requests. Then the body in the macro defi‐
374 nition is just like a normal part of the document — text enhanced by
375 calls of requests, macros, strings, registers, etc. For example, the
376 code above can be written in a simpler way by
377 .eo
379 .ds midpart was called with
380 .de print_args
381 . tm \f[I]\$0\f[] \*[midpart] \n[.$] arguments:
382 . tm \$*
383 ..
384 .ec
385 Unfortunately, draft mode cannot be used universally. Although it is
387 good enough for defining normal macros, draft mode fails with advanced
388 applications, such as indirectly defined strings, registers, etc. An
389 optimal way is to define and test all macros in draft mode and then do
390 the backslash doubling as a final step; do not forget to remove the .eo
391 request.
392 Tips for Macro Definitions
394 · Start every line with a dot, for example, by using the groff
395 request .nop for text lines, or write your own macro that han‐
396 dles also text lines with a leading dot.
397 .de Text
399 . if (\\n[.$] == 0) \
400 . return
401 . nop \)\\$*\)
402 ..
403 · Write a comment macro that works both for copy-in and draft
405 mode; for as escaping is off in draft mode, trouble might occur
406 when normal comments are used. For example, the following macro
407 just ignores its arguments, so it acts like a comment line:
408 .de c
410 ..
411 .c This is like a comment line.
412 · In long macro definitions, make ample use of comment lines or
414 almost-empty lines (this is, lines which have a leading dot and
415 nothing else) for a better structuring.
416 · To increase readability, use groff's indentation facility for
418 requests and macro calls (arbitrary whitespace after the leading
419 dot).
420 Diversions
422 Diversions can be used to implement quite advanced programming con‐
423 structs. They are comparable to pointers to large data structures in
424 the C programming language, but their usage is quite different.
425 In their simplest form, diversions are multi-line strings, but they get
427 their power when diversions are used dynamically within macros. The
428 (formatted) information stored in a diversion can be retrieved by call‐
429 ing the diversion just like a macro.
430 Most of the problems arising with diversions can be avoided if you
432 remain aware of the fact that diversions always store complete lines.
433 If diversions are used when the line buffer has not been flushed,
434 strange results are produced; not knowing this, many people get desper‐
435 ate about diversions. To ensure that a diversion works, line breaks
436 should be added at the right places. To be on the secure side, enclose
437 everything that has to do with diversions into a pair of line breaks;
438 for example, by explicitly using .br requests. This rule should be
439 applied to diversion definition, both inside and outside, and to all
440 calls of diversions. This is a bit of overkill, but it works nicely.
441 [If you really need diversions which should ignore the current partial
443 line, use environments to save the current partial line and/or use the
444 .box request.]
445 The most powerful feature using diversions is to start a diversion
447 within a macro definition and end it within another macro. Then every‐
448 thing between each call of this macro pair is stored within the diver‐
449 sion and can be manipulated from within the macros.
450
452 All macro names must be named name.tmac to fully use the tmac mecha‐
453 nism. tmac.name as with classical packages is possible as well, but
454 deprecated.
455 The macro files are kept in the tmac directories; a colon separated
457 list of these constitutes the tmac path.
458 The search sequence for macro files is (in that order):
460 · the directories specified with troff/groff's -M command line
462 option
463 · the directories given in the $GROFF_TMAC_PATH environment vari‐
465 able
466 · the current directory (only if in unsafe mode, which is enabled
468 by the -U command line switch)
469 · the home directory
471 · a platform-specific directory, being
473 /usr/lib64/groff/site-tmac
475 in this installation
477 · a site-specific (platform-independent) directory, being
479 /usr/share/groff/site-tmac
481 in this installation
483 · the main tmac directory, being
485 /usr/share/groff/1.20.1/tmac
487 in this installation
489
491 $GROFF_TMAC_PATH
492 A colon separated list of additional tmac directories in which
493 to search for macro files. See the previous section for a
494 detailed description.
495
497 Copyright (C) 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009 Free
498 Software Foundation, Inc.
499 This document is distributed under the terms of the FDL (GNU Free Docu‐
501 mentation License) version 1.3 or later. You should have received a
502 copy of the FDL on your system, it is also available on-line at the GNU
503 copyleft site ⟨http://www.gnu.org/copyleft/fdl.html⟩.
504 This document is part of groff, the GNU roff distribution. It was
506 written by Bernd Warken ⟨bwarken@mayn.de⟩; it is maintained by Werner
507 Lemberg ⟨wl@gnu.org⟩.
508
510 A complete reference for all parts of the groff system is found in the
511 groff info(1) file.
512 groff(1)
514 an overview of the groff system.
515 groff_man(7),
517 groff_mdoc(7),
518 groff_me(7),
519 groff_mm(7),
520 groff_mom(7),
521 groff_ms(7),
522 groff_trace(7),
523 groff_www(7).
524 the groff tmac macro packages.
525 groff(7)
527 the groff language.
528 The Filesystem Hierarchy Standard is available at the FHS web site
530 ⟨http://www.pathname.com/fhs/⟩.
531Groff Version 1.20.1 9 January 2009 GROFF_TMAC(5)