1GROFF_TMAC(5)                 File Formats Manual                GROFF_TMAC(5)
2
3
4

NAME

6       groff_tmac - macro files in the roff typesetting system
7

DESCRIPTION

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
14       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

GROFF MACRO PACKAGES

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
25              sh# groff -m man -m ms foo
26
27       or
28
29              sh# groff -m man foo -m ms bar
30
31       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
35   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
40       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
45       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
50   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
55       me     The classical me macro package; see groff_me(7).
56
57       mm     The semi-classical mm macro package; see groff_mm(7).
58
59       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
64       ms     The classical ms macro package; see groff_ms(7).
65
66   Language-specific Packages
67       cs     This  file  adds  support  for Czech localization, including the
68              main macro packages (me, mom, mm, and ms).
69
70              Note that cs.tmac sets the input encoding to latin-2.
71
72       de
73       den    German localization support, including the main  macro  packages
74              (me, mom, mm, and ms).
75
76              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
81       fr     This file adds support for French  localization,  including  the
82              main macro packages (me, mom, mm, and ms).  Example:
83
84                     sh# groff -ms -mfr foo.ms > foo.ps
85
86              Note  that  fr.tmac  sets  the  input encoding to latin-9 to get
87              proper support of the ‘oe’ ligature.
88
89       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
94   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
104       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
109       Note that it can happen that some input  encoding  characters  are  not
110       available for a particular output device.  For example, saying
111
112       groff -Tlatin1 -mlatin9 ...
113
114       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
119   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
124       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
128       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
132       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
138       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 a7d7.  An appended l (ell) char‐
145              acter denotes landscape orientation.  Examples:  a4,  c3l,  let‐
146              terl.
147
148              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
153              sh# groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps
154
155       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
162       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
167       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
175              Syntax:
176
177                     .PSPIC [-L|-R|-C|-I n] file [width [height]]
178
179              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
193              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
197                     .am PSPIC
198                     .  vpt 0
199                     \h'(\\n[ps-offset]u + \\n[ps-deswid]u)'
200                     .  sp -1
201                     .  vpt 1
202                     ..
203
204       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
209       trace  Use  this for tracing macro calls.  It is only useful for debug‐
210              ging.  See groff_trace(7).
211
212       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
218       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

NAMING

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
233       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
237       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
244       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
250              sh# groff -m man
251              sh# groff -man
252              sh# groff -mman
253              sh# groff -m an
254
255       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
259              sh# groff -m www
260              sh# groff -mwww
261
262       Obviously, variants like -mmwww would not make much sense.
263
264       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
270       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
274       In groff, most  macro  packages  are  described  in  man  pages  called
275       groff_name(7), with a leading ‘m’ for the classical packages.
276

INCLUSION

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
284       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
291       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
297       For example, suppose a macro file is stored as
298
299              /usr/share/groff/1.22.4/tmac/macros.tmac
300
301       and is used in some document called docu.roff.
302
303       At run-time, the formatter call for this is
304
305              sh# groff -m macros docu.roff
306
307       To include the macro file directly in the document either
308
309              .mso macros.tmac
310
311       is used or
312
313              .so /usr/share/groff/1.22.4/tmac/macros.tmac
314
315       In both cases, the formatter should be called with option -s to  invoke
316       soelim.
317
318              sh# groff -s docu.roff
319
320       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

WRITING MACROS

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
330       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
335       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
342   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
347       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
357              .ds midpart was called with
358              .de print_args
359              .  tm \f[I]\\$0\f[] \*[midpart] \\n[.$] arguments:
360              .  tm \\$*
361              ..
362
363       When calling this macro by
364
365              .print_args arg1 arg2
366
367       the following text is printed to the terminal:
368
369              print_args was called with the following 2 arguments:
370              arg1 arg2
371
372       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
378       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
383   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
391              .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
399       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
406   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
411                     .de Text
412                     .  if (\\n[.$] == 0) \
413                     .    return
414                     .  nop \)\\$*\)
415                     ..
416
417       •      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
422                     .de c
423                     ..
424                     .c This is like a comment line.
425
426       •      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
430       •      To increase readability, use groff's  indentation  facility  for
431              requests and macro calls (arbitrary whitespace after the leading
432              dot).
433
434   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
439       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
444       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
455       [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
459       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

FILES

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
469       The  macro  files  are  kept in the tmac directories; a colon separated
470       list of these constitutes the tmac path.
471
472       The search sequence for macro files is (in that order):
473
474       •      the directories specified with troff/groff's -M command-line op‐
475              tion
476
477       •      the  directories  given in the GROFF_TMAC_PATH environment vari‐
478              able
479
480       •      the current directory (only if in unsafe mode, which is  enabled
481              by the -U command-line switch)
482
483       •      the home directory
484
485       •      a platform-specific directory, being
486
487                     /etc/groff/site-tmac
488
489              in this installation
490
491       •      a site-specific (platform-independent) directory, being
492
493                     /etc/groff/site-tmac
494
495              in this installation
496
497       •      the main tmac directory, being
498
499                     /usr/share/groff/1.22.4/tmac
500
501              in this installation
502

ENVIRONMENT

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

AUTHORS

510       This  document  was  written  by  Bernd  Warken ⟨groff-bernd.warken-72@
511       web.de⟩ and Werner Lemberg ⟨wl@gnu.org⟩.
512

SEE ALSO

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
518       groff(1)
519              an overview of the groff system.
520
521       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
531       groff(7)
532              the groff language.
533
534       The Filesystem Hierarchy Standard is available  at  the  FHS  web  site
535http://www.pathname.com/fhs/⟩.
536
537
538
539groff 1.22.4                    20 January 2022                  GROFF_TMAC(5)
Impressum