groff_tmac(5) — Linux manual page

Name | Description | Macro packages | Naming | Inclusion | Writing macros | Authors | See also | COLOPHON

groff_tmac(5)              File Formats Manual             groff_tmac(5)

Name         top

       groff_tmac - macro files in the GNU roff typesetting system

Description         top

       Definitions of macros, strings, and registers for use in a
       roff(7) document can be collected into macro files, roff input
       files designed to produce no output themselves but instead ease
       the preparation of other roff documents.  There is no syntactical
       difference between a macro file and any other roff document; only
       its purpose distinguishes it.  When a macro file is installed at
       a standard location, named according to a certain convention, and
       suitable for use by a general audience, it is termed a macro
       package.  The “tmac” name originated in early Unix culture as an
       abbreviation of “troff macros”.

       Macro packages can be loaded by supplying the -m option to
       troff(1) or a groff front end.  A macro file's name must have the
       form name.tmac (or tmac.name) and be placed in a “tmac directory”
       to be loadable with the “-m name” option.  Section “Environment”
       of troff(1) lists these directories.  Alternatively, a groff
       document requiring a macro file can load it with the mso (“macro
       source”) request.

       Macro files are named for their most noteworthy application, but
       a macro file need not define any macros.  It can restrict itself
       to defining registers and strings or invoking other groff
       requests.  It can even be empty.

       Encode macro files in ISO 646 (“ASCII”) or either of CCSID (“code
       page”) 1047 (on EBCDIC systems) or ISO Latin-1 (8859-1)
       (otherwise).  soelim(1) by design does not interpret mso
       requests, and the encodings used by documents employing a macro
       file can vary.

Macro packages         top

       Macro packages come in two varieties; those which assume
       responsibility for page layout and other critical functions
       (“major” or “full-service”) and those that do not (“supplemental”
       or “auxiliary”).  GNU roff provides most major macro packages
       found in AT&T and BSD Unix systems, an additional full-service
       package, and many supplemental packages.  Multiple full-service
       macro packages cannot be used by the same document.  Auxiliary
       packages can, in general, be freely combined, though attention to
       their use of the groff language name spaces for identifiers
       (particularly registers, macros, strings, and diversions) should
       be paid.  Name space management was a significant challenge in
       AT&T troff; groff's support for arbitrarily long identifiers
       affords few excuses for name collisions, apart from attempts at
       compatibility with the demands of historical documents.  As a
       rule, direct the formatter to load full-service macro packages
       using the -m option of troff(1) (or a wrapper).  A document
       should load auxiliary macro files with the mso request.

   Man pages
       Two full-service macro packages are specialized for formatting
       Unix reference manuals; they do not support features like
       footnotes or multiple columnation.

       an     constructs man pages in a format introduced by Seventh
              Edition Unix (1979).  Its macro interface is small, and
              the package widely used; see groff_man(7).

       doc    constructs man pages in a format introduced by 4.3BSD-Reno
              (1990).  It provides many more features than an, but is
              also larger, more complex, and not as widely adopted; see
              groff_mdoc(7).

       Because readers of man pages often do not know in advance which
       macros are used to format a given document, a wrapper is
       available.

       andoc  recognizes a document's use of an or doc and loads the
              corresponding macro package.  Multiple man pages, in
              either format, can be handled; andoc reloads each macro
              package as necessary.

   Full-service packages
       The following packages each support composition of documents of
       any kind, from single-page memos to lengthy monographs.  They are
       similar in functionality; select one that suits your taste.

       me     originates in 2BSD (1978); see groff_me(7).

       mm     originates in Programmer's Workbench (PWB) Unix 1.0
              (1977); see groff_mm(7).

       mom    was contributed to groff in 2002, and freely exercises its
              many extended features.  See groff_mom(7).

       ms     originates in Sixth Edition Unix (1975); see groff_ms(7).

   Localization packages
       For Western languages, the localization file sets the hyphenation
       mode and loads hyphenation patterns and exceptions.  Localization
       files can also adjust the date format and provide translations of
       strings used by some of the full-service macro packages; alter
       the input encoding (see the next section); and change the amount
       of additional inter-sentence space.  For Eastern languages, the
       localization file defines character classes and sets flags on
       them.  By default, troffrc loads the localization file for
       English.

       trans  loads localized strings used by various macro packages
              after their localized forms have been prepared by a
              localization macro file.

       groff provides the following localization files.

       cs     Czech; localizes man, me, mm, mom, and ms.  Sets the input
              encoding to Latin-2 by loading latin2.tmac.

       de
       den    German; localizes man, me, mm, mom, and ms.  Sets the
              input encoding to Latin-1 by loading latin1.tmac.

              de.tmac selects hyphenation patterns for traditional
              orthography, and den.tmac does the same for the new
              orthography (“Rechtschreibreform”).

       en     English.

       es     Spanish; localizes man, me, mm, mom, and ms.  Sets the
              input encoding to Latin-9 by loading latin9.tmac.

       fr     French; localizes man, me, mm, mom, and ms.  Sets the
              input encoding to Latin-9 by loading latin9.tmac.

       it     Italian; localizes man, me, mm, mom, and ms.

       ja     Japanese.

       ru     Russian; localizes man, me, mm, mom, and ms.  Sets the
              input encoding to KOI8-R by loading koi8-r.tmac.

       sv     Swedish; localizes man, me, mm, mom, and ms.  Sets the
              input encoding to Latin-1 by loading latin1.tmac.  Some of
              the localization of the mm package is handled separately;
              see groff_mmse(7).

       zh     Chinese.

   Input encodings
       latin1
       latin2
       latin5
       latin9 are various ISO 8859 input encodings supported by groff.
              On systems using ISO character encodings, groff loads
              latin1.tmac automatically at startup.  A document that
              uses Latin-2, Latin-5, or Latin-9 can specify one of these
              alternative encodings.

       cp1047 provides support for EBCDIC-based systems.  On those
              platforms, groff loads cp1047.tmac automatically at
              startup.

       koi8-r provides support for the KOI8-R encoding.  KOI8-R code
              points in the range 0x80–0x9F are not valid input on
              systems using ISO character codings natively; see section
              “Identifiers” in groff(7).  This should be no impediment
              to practical documents, as these KOI8-R code points do not
              encode letters, but box-drawing symbols and characters
              that are better obtained via special character escape
              sequences; see groff_char(7).

       Because different input character codes constitute valid GNU
       troff input on ISO and EBCDIC systems, the latin and koi8-r macro
       files cannot be used on EBCDIC systems, and cp1047 cannot be used
       on ISO systems.

   Auxiliary packages
       The macro packages in this section are not intended for stand-
       alone use, but can add functionality to any other macro package
       or to plain (“raw”) groff documents.

       62bit  provides macros for addition, multiplication, and division
              of 62-bit integers (allowing safe multiplication of signed
              31-bit integers, for example).

       hdtbl  allows the generation of tables using a syntax similar to
              the HTML table model.  This Heidelberger table macro
              package is not a preprocessor, which can be useful if the
              contents of table entries are determined by macro calls or
              string interpolations.  Compare to tbl(1).  It works only
              with the ps and pdf output devices.  See groff_hdtbl(7).

       papersize
              enables the paper format to be set on the command line by
              giving a “-d paper=format” option to troff.  Possible
              values for format are the ISO and DIN formats “A0A6”,
              “B0B6”, “C0C6”, and “D0D6”; the U.S. formats “letter”,
              “legal”, “tabloid”, “ledger”, “statement”, and
              “executive”; and the envelope formats “com10”, “monarch”,
              and “DL”.  All formats, even those for envelopes, are in
              portrait orientation: the length measurement is vertical.
              Appending “l” (ell) to any of these denotes landscape
              orientation instead.  This macro file assumes one-inch
              horizontal margins, and sets registers recognized by the
              groff man, mdoc, mm, mom, and ms packages to configure
              them accordingly.  If you want different margins, you will
              need to use those packages' facilities, or troff ll and/or
              po requests to adjust them.  An output device typically
              requires command-line options -p and -l to override the
              paper dimensions and orientation, respectively, defined in
              its DESC file; see subsection “Paper format” of groff(1).
              This macro file is normally loaded at startup by the
              troffrc file when formatting for a typesetter (but not a
              terminal).

       pdfpic provides a single macro, PDFPIC, to include a PDF graphic
              in a document using features of the pdf output driver.
              For other output devices, PDFPIC calls PSPIC, with which
              it shares an interface (see below).  This macro file is
              normally loaded at startup by the troffrc file.

       pic    supplies definitions of the macros PS, PE, and PF, usable
              with the pic(1) preprocessor.  They center each picture.
              Use it if your document does not use a full-service macro
              package, or that package does not supply working pic macro
              definitions.  Except for man and mdoc, those provided with
              groff already do so (exception: mm employs the name PF for
              a different purpose).

       pspic  provides a macro, PSPIC, that includes a PostScript
              graphic in a document.  The ps, dvi, html, and xhtml
              output devices support such inclusions; for all other
              drivers, the image is replaced with a rectangular border
              of the same size.  pspic.tmac is loaded at startup by the
              troffrc file.

              Its syntax is as follows.

                     .PSPIC [-L|-R|-C|-I n] file [width [height]]

              file is the name of the PostScript file; width and height
              give the desired width and height of the image.  If
              neither a width nor a height argument is specified, the
              image's natural width (as given in the file's bounding
              box) or the current line length is used as the width,
              whatever is smaller.  The width and height arguments may
              have scaling units attached; the default scaling unit
              is i.  PSPIC scales the graphic uniformly in the
              horizontal and vertical directions so that it is no more
              than width wide and height high.  Option -C centers the
              graphic horizontally; this is the default.  -L and -R
              left- and right-align the graphic, respectively.  -I
              indents the graphic by n (with a default scaling unit
              of m).

              To use PSPIC within a diversion, we recommend extending it
              with the following code, assuring that the diversion's
              width completely covers the image's width.

                     .am PSPIC
                     .  vpt 0
                     \h'(\\n[ps-offset]u + \\n[ps-deswid]u)'
                     .  sp -1
                     .  vpt 1
                     ..

              Failure to load PSPIC's image argument is not an error.
              (The psbb request does issue an error diagnostic.)  To
              make such a failure fatal, append to the pspic*error-hook
              macro.

                     .am pspic*error-hook
                     .  ab
                     ..

       ptx    provides a macro, xx, to format permuted index entries as
              produced by the GNU ptx(1) program.  If your formatting
              needs differ, copy the macro into your document and adapt
              it to your needs.

       rfc1345
              defines special character escape sequences named for the
              glyph mnemonics specified in RFC 1345 and the digraph
              table of the Vim text editor.  See groff_rfc1345(7).

       sboxes offers an interface to the “pdf: background” device
              control command supported by gropdf(1).  Using this
              package, groff ms documents can draw colored rectangles
              beneath any output.

              .BOXSTART SHADED color OUTLINED color INDENT size WEIGHT size
                     begins a box, where the argument after SHADED gives
                     the fill color and that after OUTLINED the border
                     color.  Omit the former to get a borderless filled
                     box and the latter for a border with no fill.  The
                     specified WEIGHT is used if the box is OUTLINED.

                     INDENT precedes a value that leaves a gap between
                     the border and the contents inside the box.

                     Each color must be a defined groff color name, and
                     each size a valid groff numeric expression.  The
                     keyword/value pairs can be specified in any order.

              Boxes can be stacked, so you can start a box within
              another box; usually the later boxes would be smaller than
              the containing box, but this is not enforced.  When using
              BOXSTART, the left position is the current indent minus
              the INDENT in the command, and the right position is the
              left position (calculated above) plus the current line
              length and twice the indent.

              .BOXSTOP
                     takes no parameters.  It closes the most recently
                     started box at the current vertical position after
                     adding its INDENT spacing.

              Your groff documents can conditionally exercise the sboxes
              macros.  The register GSBOX is defined if the package is
              loaded, and interpolates a true value if the pdf output
              device is in use.

              sboxes furthermore hooks into the groff_ms(7) package to
              receive notifications when footnotes are growing, so that
              it can close boxes on a page before footnotes are printed.
              When that condition obtains, sboxes will close open boxes
              two points above the footnote separator and re-open them
              on the next page.  (This amount probably will not match
              the box's INDENT.)

              See “Using PDF boxes with groff and the ms macros”
              ⟨file:///usr/local/share/doc/groff-1.23.0/msboxes.pdf⟩ for
              a demonstration.

       trace  aids the debugging of groff documents by tracing macro
              calls.  See groff_trace(7).

       www    defines macros corresponding to HTML elements.  See
              groff_www(7).

Naming         top

       AT&T nroff and troff were implemented before the conventions of
       the modern C getopt(3) call evolved, and used a naming scheme for
       macro packages that looks oddly terse to modern eyes.  The
       formatter's -m option was the main means of loading a macro
       package, and its argument had to follow immediately without
       intervening space.  This looked like a long option name preceded
       by a single minus—a sensation in the computer stone age.  Macro
       packages therefore came to be known by names that started with
       the letter “m”, which was omitted from the name of the macro file
       as stored on disk.  For example, the manuscript macro package was
       stored as tmac.s and loaded with the option -ms.  It has since
       become conventional in operating systems to use a suffixed file
       name extension to suggest a file type or format, thus we see roff
       documents with names ending in .man, .me, and so on.

       groff commands permit space between an option and its argument.
       The syntax “groff -m s” makes the macro file name more clear but
       may surprise users familiar with the original convention, unaware
       that the package's “real” name was “s” all along.  For such
       packages of long pedigree, groff accommodates different users'
       expectations by supplying wrapper macro files that load the
       desired file with mso requests.  Thus, all of “groff -m s”,
       “groff -m ms”, “groff -ms”, and “groff -mms” serve to load the
       manuscript macros.

Inclusion         top

       The traditional method of employing a macro package is to specify
       the “-m package” option to the formatter, which then reads
       package's macro file prior to any input files.  Historically,
       package was sought in a file named tmac.package (that is, with a
       “tmac.” prefix).  GNU troff searches for package.tmac in the
       macro path; if not found, it looks for tmac.package instead, and
       vice versa.

       Alternatively, one could include a macro file with the request
       “so file-name”; the argument is resolved as fopen(3) would, from
       the current working directory of the formatter.  This approach
       was inadequate to locate macro packages, since systems stored
       them in varying locations.  GNU troff offers an improved feature
       in the similar request “mso package-file-name”, which searches
       the macro path for package-file-name.  Because its argument is a
       file name, its “.tmac” component must be included for the file to
       be found; however, as a convenience, if opening it fails, mso
       strips any such suffix and tries again with a “tmac.” prefix, and
       vice versa.

       If a sourced file requires preprocessing, for example if it
       includes tbl tables or eqn equations, the preprocessor soelim(1)
       must be used.  This can be achieved with a pipeline or by
       specifying the -s option to groff(1).  man(1) librarian programs
       typically run soelim automatically.  (As a rule, macro packages
       themselves do not require preprocessing.)

Writing macros         top

       A roff(7) document is a text file that is enriched by predefined
       formatting constructs, such as requests, escape sequences,
       strings, numeric registers, and macros from a macro package.
       roff(7) describes these elements.

       To give a document a personal style, it is most useful to extend
       the existing elements by defining some macros for repeating
       tasks; the best place for this is near the beginning of the
       document or in a separate file.

       Macros without arguments are just like strings.  But the full
       power of macros occurs when arguments are passed with a macro
       call.  Within the macro definition, the arguments are available
       as the escape sequences \$1, ..., \$9, \$[...], \$*, and \$@, the
       name under which the macro was called is in \$0, and the number
       of arguments is in register \n[.$]; see groff(7).

   Drafting macros
       Temporarily disabling the escape mechanism can ease macro
       composition; bracket a macro definition with eo and ec requests.
              .eo
              .ds midpart was called with the following
              .de print_args
              \f[I]\$0\f[] \*[midpart] \n[.$] arguments:
              \$*
              ..
              .ec

       This drafting procedure has limitations; it is unsuitable for a
       macro that requires certain interpolations at the time it is
       defined, or for indirect definitions of identifiers.  See section
       “Copy mode” of groff(7).  In such cases, you might define and
       test the macro with the escape mechanism doubled, then double the
       backslashes and remove the eo and ec requests as a final step.

   Tips for macro definitions
       •  Use only control lines in macro definitions; that is, start
          every input line with a control character.  groff's nop
          request makes use of text lines unnecessary.

                 .de Text
                 .  if (\\n[.$] == 0) \
                 .    return
                 .  nop \&\\$*\&
                 ..

       •  Write a comment macro that works in both draft and non-draft
          modes; since the escape character is disabled in draft mode,
          trouble might occur when comment escape sequences are used.
          For example, the following macro ignores its arguments, so
          calling it is a harmless (if somewhat busy) null operation.

                 .de c
                 ..
                 .c This is my comment.

       •  Comment lengthy macro definitions.

       •  Use empty requests, and indentation after control characters,
          to clarify a macro's structure.

   Diversions
       Diversions can be used to implement quite advanced programming
       constructs.  They are comparable to pointers to large data
       structures in the C programming language, but their usage is
       quite different.

       In their simplest form, diversions are multi-line strings, but
       diversions get their power when used dynamically within macros.
       The (formatted) information stored in a diversion can be
       retrieved by calling the diversion just like a macro.

       Most of the problems arising with diversions can be avoided if
       you remember that diversions always store complete lines.  Using
       diversions when the line buffer has not been flushed produces
       strange results; not knowing this, many people get desperate
       about diversions.  To ensure that a diversion works, add line
       breaks at the right places.  To be safe, enclose everything that
       has to do with diversions within a pair of line breaks; for
       example, by explicitly using .br requests.  This rule should be
       applied to diversion definition, both inside and outside, and to
       all calls of diversions.  This is a bit of overkill, but it works
       nicely.

       (If you really need diversions which should ignore the current
       partial line, use environments to save the current partial line
       and/or use the .box request.)

       The most powerful feature using diversions is to start a
       diversion within a macro definition and end it within another
       macro.  Then everything between each call of this macro pair is
       stored within the diversion and can be manipulated from within
       the macros.

Authors         top

       This document was written by Bernd Warken ⟨groff-bernd.warken-72@
       web.de⟩, Werner Lemberg ⟨wl@gnu.org⟩, and G. Branden Robinson
       ⟨g.branden.robinson@gmail.com⟩.

See also         top

       Groff: The GNU Implementation of troff, by Trent A. Fisher and
       Werner Lemberg, is the primary groff manual.  You can browse it
       interactively with “info groff”.

       groff(1)
              is an overview of the groff system.

       groff_man(7),
       groff_mdoc(7),
       groff_me(7),
       groff_mm(7),
       groff_mom(7),
       groff_ms(7),
       groff_rfc1345(7),
       groff_trace(7),
       and
       groff_www(7)
              are groff macro packages.

       groff(7)
              summarizes the language recognized by GNU troff.

       troff(1)
              documents the default macro file search path.

COLOPHON         top

       This page is part of the groff (GNU troff) project.  Information
       about the project can be found at 
       ⟨http://www.gnu.org/software/groff/⟩.  If you have a bug report
       for this manual page, see ⟨http://www.gnu.org/software/groff/⟩.
       This page was obtained from the project's upstream Git repository
       ⟨https://git.savannah.gnu.org/git/groff.git⟩ on 2023-12-22.  (At
       that time, the date of the most recent commit that was found in
       the repository was 2023-12-08.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

groff 1.23.0.453-330f9-dirty 1 November 2023               groff_tmac(5)