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 us‐
121 age, but can be used to add special functionality to any other macro
122 package or to plain groff.
123 62bit Provides macros for addition, multiplication, and division of
125 62-bit integers (allowing safe multiplication of 31-bit 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 hdtbl The Heidelberger table macros, contributed by Joachim Walsdorff,
133 allow the generation of tables through a syntax similar to the
134 HTML table model. Note that hdtbl is a macro package, not a
135 preprocessor like tbl(1). hdtbl works only with the -Tps and
136 -Tpdf output devices. See groff_hdtbl(7).
137 papersize
139 This macro file is already loaded at start-up by troff so it
140 isn't necessary to call it explicitly. It provides an interface
141 to set the paper size on the command line with the option
142 -dpaper=size. Possible values for size are the same as the pre‐
143 defined papersize values in the DESC file (only lowercase; see
144 groff_font(5) for more) except a7–d7. An appended l (ell) char‐
145 acter denotes landscape orientation. Examples: a4, c3l, let‐
146 terl.
147 Most output drivers need additional command-line switches -p and
149 -l to override the default paper length and orientation as set
150 in the driver-specific DESC file. For example, use the follow‐
151 ing for PS output on A4 paper in landscape orientation:
152 sh# groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps
154 pdfpic A single macro is provided in this file, PSPIC, to include a PDF
156 graphic in a document, i.e., under the output device -Tpdf. For
157 all other devices, pspic is used. So pdfpic is an extension of
158 pspic. By that you can now even replace all PSPIC by PDFPIC,
159 nothing gets lost by that. The options of PDFPIC are identical
160 to the PSDIF options.
161 pic This file provides proper definitions for the macros PS and PE,
163 needed for the pic(1) preprocessor. They center each picture.
164 Use it only if your macro package doesn't provide proper defini‐
165 tions for those two macros (actually, most of them already do).
166 pspic A single macro is provided in this file, PSPIC, to include a
168 PostScript graphic in a document. The following output devices
169 support inclusion of PS images: -Tps, -Tdvi, -Thtml, and -Tx‐
170 html; for all other devices the image is replaced with a hollow
171 rectangle of the same size. This macro file is already loaded
172 at start-up by troff so it isn't necessary to call it explic‐
173 itly.
174 Syntax:
176 .PSPIC [-L|-R|-C|-I n] file [width [height]]
178 file is the name of the PostScript file; width and height give
180 the desired width and height of the image. If neither a width
181 nor a height argument is specified, the image's natural width
182 (as given in the file's bounding box) or the current line length
183 is used as the width, whatever is smaller. The width and height
184 arguments may have scaling indicators attached; the default
185 scaling indicator is i. This macro scales the graphic uniformly
186 in the x and y directions so that it is no more than width wide
187 and height high. Option -C centers the graphic horizontally,
188 which is the default. The -L and -R options cause the graphic
189 to be left-aligned and right-aligned, respectively. The -I op‐
190 tion causes the graphic to be indented by n (default scaling in‐
191 dicator is m).
192 For use of .PSPIC within a diversion it is recommended to extend
194 it with the following code, assuring that the diversion's width
195 completely covers the image's width.
196 .am PSPIC
198 . vpt 0
199 \h'(\\n[ps-offset]u + \\n[ps-deswid]u)'
200 . sp -1
201 . vpt 1
202 ..
203 ptx A single macro is provided in this file, xx, for formatting per‐
205 muted index entries as produced by the GNU ptx(1) program. In
206 case you need a different formatting, copy the macro into your
207 document and adapt it to your needs.
208 trace Use this for tracing macro calls. It is only useful for debug‐
210 ging. See groff_trace(7).
211 tty-char
213 Overrides the definition of standard troff characters and some
214 groff characters for TTY devices. The optical appearance is in‐
215 tentionally inferior compared to that of normal TTY formatting
216 to allow processing with critical equipment.
217 www Additions of elements known from the HTML format, as used in the
219 internet (World Wide Web) pages; this includes URL links and
220 mail addresses; see groff_www(7).
221
223 Classical roff systems were designed before the conventions of the mod‐
224 ern C getopt(3) call evolved, and used a naming scheme for macro pack‐
225 ages that looks odd to modern eyes. Macro packages were always in‐
226 cluded with the option -m; when this option was directly followed by
227 its argument without an intervening space, this looked like a long op‐
228 tion preceded by a single minus — a sensation in the computer stone
229 age. To make this invocation form work, classical troff macro packages
230 used names that started with the letter ‘m’, which was omitted in the
231 naming of the macro file.
232 For example, the macro package for the man pages was called man, while
234 its macro file tmac.an. So it could be activated by the argument an to
235 option -m, or -man for short.
236 For similar reasons, macro packages that did not start with an ‘m’ had
238 a leading ‘m’ added in the documentation and in speech; for example,
239 the package corresponding to tmac.doc was called mdoc in the documenta‐
240 tion, although a more suitable name would be doc. For, when omitting
241 the space between the option and its argument, the command-line option
242 for activating this package reads -mdoc.
243 To cope with all situations, actual versions of groff(1) are smart
245 about both naming schemes by providing two macro files for the in‐
246 flicted macro packages; one with a leading ‘m’ the other one without
247 it. So in groff, the man macro package may be specified as one of the
248 following four methods:
249 sh# groff -m man
251 sh# groff -man
252 sh# groff -mman
253 sh# groff -m an
254 Recent packages that do not start with ‘m’ do not use an additional ‘m’
256 in the documentation. For example, the www macro package may be speci‐
257 fied only as one of the two methods:
258 sh# groff -m www
260 sh# groff -mwww
261 Obviously, variants like -mmwww would not make much sense.
263 A second strange feature of classical troff was to name macro files in
265 the form tmac.name. In modern operating systems, the type of a file is
266 specified as a postfix, the file name extension. Again, groff copes
267 with this situation by searching both anything.tmac and tmac.anything
268 if only anything is specified.
269 The easiest way to find out which macro packages are available on a
271 system is to check the man page groff(1), or the contents of the tmac
272 directories.
273 In groff, most macro packages are described in man pages called
275 groff_[22mname(7), with a leading ‘m’ for the classical packages.
276
278 There are several ways to use a macro package in a document. The clas‐
279 sical way is to specify the troff/groff option -m name at run-time;
280 this makes the contents of the macro package name available. In groff,
281 the file name.tmac is searched within the tmac path; if not found,
282 tmac.name is searched for instead.
283 Alternatively, it is also possible to include a macro file by adding
285 the request .so filename into the document; the argument must be the
286 full file name of an existing file, possibly with the directory where
287 it is kept. In groff, this was improved by the similar request .mso
288 package, which added searching in the tmac path, just like option -m
289 does.
290 Note that in order to resolve the .so and .mso requests, the roff pre‐
292 processor soelim(1) must be called if the files to be included need
293 preprocessing. This can be done either directly by a pipeline on the
294 command line or by using the troff/groff option -s. man calls soelim
295 automatically.
296 For example, suppose a macro file is stored as
298 /usr/share/groff/1.22.4/tmac/macros.tmac
300 and is used in some document called docu.roff.
302 At run-time, the formatter call for this is
304 sh# groff -m macros docu.roff
306 To include the macro file directly in the document either
308 .mso macros.tmac
310 is used or
312 .so /usr/share/groff/1.22.4/tmac/macros.tmac
314 In both cases, the formatter should be called with option -s to invoke
316 soelim.
317 sh# groff -s docu.roff
319 If you want to write your own groff macro file, call it whatever.tmac
321 and put it in a directory in the tmac path; see section “Files” below.
322 Then documents can include it with the .mso request or the option -m.
323
325 A roff(7) document is a text file that is enriched by predefined for‐
326 matting constructs, such as requests, escape sequences, strings, nu‐
327 meric registers, and macros from a macro package. These elements are
328 described in roff(7).
329 To give a document a personal style, it is most useful to extend the
331 existing elements by defining some macros for repeating tasks; the best
332 place for this is near the beginning of the document or in a separate
333 file.
334 Macros without arguments are just like strings. But the full power of
336 macros reveals when arguments are passed with a macro call. Within the
337 macro definition, the arguments are available as the escape sequences
338 \$1, ..., \$9, \$[...], \$*, and \$@, the name under which the macro
339 was called is in \$0, and the number of arguments is in register
340 \n[.$]; see groff(7).
341 Copy-in Mode
343 The phase when groff reads a macro is called copy-in mode or copy mode
344 in roff-talk. This is comparable to the C preprocessing phase during
345 the development of a program written in the C language.
346 In this phase, groff interprets all backslashes; that means that all
348 escape sequences in the macro body are interpreted and replaced by
349 their value. For constant expressions, this is wanted, but strings and
350 registers that might change between calls of the macro must be pro‐
351 tected from being evaluated. This is most easily done by doubling the
352 backslash that introduces the escape sequence. This doubling is most
353 important for the positional parameters. For example, to print infor‐
354 mation on the arguments that were passed to the macro to the terminal,
355 define a macro named ‘.print_args’, say.
356 .ds midpart was called with
358 .de print_args
359 . tm \f[I]\\$0\f[] \*[midpart] \\n[.$] arguments:
360 . tm \\$*
361 ..
362 When calling this macro by
364 .print_args arg1 arg2
366 the following text is printed to the terminal:
368 print_args was called with the following 2 arguments:
370 arg1 arg2
371 Let's analyze each backslash in the macro definition. As the posi‐
373 tional parameters and the number of arguments change with each call of
374 the macro their leading backslash must be doubled, which results in
375 \\$* and \\[.$]. The same applies to the macro name because it could
376 be called with an alias name, so \\$0.
377 On the other hand, midpart is a constant string, it does not change, so
379 no doubling for \*[midpart]. The \f escape sequences are predefined
380 groff elements for setting the font within the text. Of course, this
381 behavior does not change, so no doubling with \f[I] and \f[].
382 Draft Mode
384 Writing groff macros is easy when the escaping mechanism is temporarily
385 disabled. In groff, this is done by enclosing the macro definition(s)
386 into a pair of .eo and .ec requests. Then the body in the macro defi‐
387 nition is just like a normal part of the document — text enhanced by
388 calls of requests, macros, strings, registers, etc. For example, the
389 code above can be written in a simpler way by
390 .eo
392 .ds midpart was called with
393 .de print_args
394 . tm \f[I]\$0\f[] \*[midpart] \n[.$] arguments:
395 . tm \$*
396 ..
397 .ec
398 Unfortunately, draft mode cannot be used universally. Although it is
400 good enough for defining normal macros, draft mode fails with advanced
401 applications, such as indirectly defined strings, registers, etc. An
402 optimal way is to define and test all macros in draft mode and then do
403 the backslash doubling as a final step; do not forget to remove the .eo
404 request.
405 Tips for Macro Definitions
407 • Start every line with a dot, for example, by using the groff re‐
408 quest .nop for text lines, or write your own macro that handles
409 also text lines with a leading dot.
410 .de Text
412 . if (\\n[.$] == 0) \
413 . return
414 . nop \)\\$*\)
415 ..
416 • Write a comment macro that works both for copy-in and draft
418 mode; for as escaping is off in draft mode, trouble might occur
419 when normal comments are used. For example, the following macro
420 just ignores its arguments, so it acts like a comment line:
421 .de c
423 ..
424 .c This is like a comment line.
425 • In long macro definitions, make ample use of comment lines or
427 almost-empty lines (this is, lines which have a leading dot and
428 nothing else) for a better structuring.
429 • To increase readability, use groff's indentation facility for
431 requests and macro calls (arbitrary whitespace after the leading
432 dot).
433 Diversions
435 Diversions can be used to implement quite advanced programming con‐
436 structs. They are comparable to pointers to large data structures in
437 the C programming language, but their usage is quite different.
438 In their simplest form, diversions are multi-line strings, but they get
440 their power when diversions are used dynamically within macros. The
441 (formatted) information stored in a diversion can be retrieved by call‐
442 ing the diversion just like a macro.
443 Most of the problems arising with diversions can be avoided if you re‐
445 main aware of the fact that diversions always store complete lines. If
446 diversions are used when the line buffer has not been flushed, strange
447 results are produced; not knowing this, many people get desperate about
448 diversions. To ensure that a diversion works, line breaks should be
449 added at the right places. To be on the secure side, enclose every‐
450 thing that has to do with diversions into a pair of line breaks; for
451 example, by explicitly using .br requests. This rule should be applied
452 to diversion definition, both inside and outside, and to all calls of
453 diversions. This is a bit of overkill, but it works nicely.
454 [If you really need diversions which should ignore the current partial
456 line, use environments to save the current partial line and/or use the
457 .box request.]
458 The most powerful feature using diversions is to start a diversion
460 within a macro definition and end it within another macro. Then every‐
461 thing between each call of this macro pair is stored within the diver‐
462 sion and can be manipulated from within the macros.
463
465 All macro package files must be named name.tmac to fully use the tmac
466 mechanism. tmac.name as with classical packages is possible as well,
467 but deprecated.
468 The macro files are kept in the tmac directories; a colon separated
470 list of these constitutes the tmac path.
471 The search sequence for macro files is (in that order):
473 • the directories specified with troff/groff's -M command-line op‐
475 tion
476 • the directories given in the GROFF_TMAC_PATH environment vari‐
478 able
479 • the current directory (only if in unsafe mode, which is enabled
481 by the -U command-line switch)
482 • the home directory
484 • a platform-specific directory, being
486 /etc/groff/site-tmac
488 in this installation
490 • a site-specific (platform-independent) directory, being
492 /etc/groff/site-tmac
494 in this installation
496 • the main tmac directory, being
498 /usr/share/groff/1.22.4/tmac
500 in this installation
502
504 GROFF_TMAC_PATH
505 A colon separated list of additional tmac directories in which
506 to search for macro files. See the previous section for a de‐
507 tailed description.
508
510 This document was written by Bernd Warken ⟨groff-bernd.warken-72@
511 web.de⟩ and Werner Lemberg ⟨wl@gnu.org⟩.
512
514 Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner
515 Lemberg, is the primary groff manual. You can browse it interactively
516 with “info groff”.
517 groff(1)
519 an overview of the groff system.
520 groff_man(7),
522 groff_mdoc(7),
523 groff_me(7),
524 groff_mm(7),
525 groff_mom(7),
526 groff_ms(7),
527 groff_trace(7),
528 groff_www(7).
529 the groff tmac macro packages.
530 groff(7)
532 the groff language.
533 The Filesystem Hierarchy Standard is available at the FHS web site
535 ⟨http://www.pathname.com/fhs/⟩.
536groff 1.22.4 22 July 2021 GROFF_TMAC(5)