groff_tmac

groff_tmac - macro files in the roff typesetting system

. . . groff_tmac.5 File position: <groff-source>/man/groff_tmac.man Last update: 21 Aug 2002 This file is part of groff, the GNU roff type-setting system. Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc. written by Bernd Warken <bwarken@mayn.de> and Werner Lemberg <wl@gnu.org> Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being this .ig-section and AUTHOR, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the Free Documentation License is included as a file called FDL in the main directory of the groff source package. A copy of the GNU Free Documentation License is also available in this Debian package as /usr/share/doc/groff/copyright. . . . . . . . . . . . The roff(7) type-setting system provides a set of macro packages suitable for special kinds of documents. . Each macro package stores its macros and definitions in a file called the package's R tmac file . The name is deduced from `T\c B roff MAC\c R ros '. .

The tmac files are normal roff source documents, except that they usually contain only definitions and setup commands, but no text. . All tmac files are kept in a single or a small number of directories, the tmac directories. . .

. groff provides all classical macro packages, some more full packages, and some secondary packages for special purposes. . .

Man\~Pages

.

man

doc

mdoc

me

mm

mom

ms

tty-char

www

. In classical roff systems, there was a funny naming scheme for macro packages, due to a simplistic design in option parsing. . Macro packages were always included by option when this option was directly followed by its argument without an intervening space, this looked like a long option preceded by a single minus \[em] a sensation in the computer stone age. . To make this optically working for macro package names, all classical macro packages choose a name that started with the letter .'char m , which was omitted in the naming of the macro file. . .

For example, the macro package for the man pages was called R man , while its macro file R tmac.an . So it could be activated by the argument an to option or for short. . .

For similar reasons, macro packages that did not start with an .'char m had a leading .'char m added in the documentation and in talking; for example, the package corresponding to tmac.doc was called mdoc in the documentation, although a more suitable name would be R doc . For, when omitting the space between the option and its argument, the command line option for activating this package reads . .

To cope with all situations, actual versions of groff(1) are smart about both naming schemes by providing two macro files for the inflicted macro packages; one with a leading .'char m , the other one without it. . So in R groff , the man macro package may be specified as on of the following four methods: .

. .

Recent packages that do not start with .'char m do not use an additional .'char m in the documentation. . For example, the www macro package may be specified only as one of the two methods: .

. .

Obviously, variants like -mmwww would not make much sense. . .

A second strange feature of classical troff was to name macro files according to IR tmac. name . In modern operating systems, the type of a file is specified as postfix, the file name extension. . Again, groff copes with this situation by searching both B anything .tmac and I tmac. anything if only anything is specified. . .

The easiest way to find out which macro packages are available on a system is to check the man\~page groff(1), or the contents of the tmac directories. . .

In R groff , most macro packages are described in\~man pages called groff_\f[I]name\f[](7), with a leading .'char m for the classical packages. . .

. There are several ways to use a macro package in a document. . The classical way is to specify the troff/groff option at run-time; this makes the contents of the macro package name available. . In groff, the file B name .tmac is searched within the tmac path; if not found, I tmac. name will be searched for instead. . .

Alternatively, it is also possible to include a macro file by adding the request filename into the document; the argument must be the full file name of an existing file, possibly with the directory where it is kept. . In groff, this was improved by the similar request R package , which added searching in the tmac path, just like option does. . .

Note that in order to resolve the and requests, the roff preprocessor soelim(1) must be called if the files to be included need preprocessing. . This can be done either directly by a pipeline on the command line or by using the troff/groff option . man calls soelim automatically. . .

For example, suppose a macro file is stored as /usr/share/groff/1.18.1/tmac/macros.tmac and is used in some document called R docu.roff . . .

At run-time, the formatter call for this is .

. .

To include the macro file directly in the document either .

./Example .

is used or .

./Example . .

In both cases, the formatter is called with

. .

If you want to write your own groff macro file, call it B whatever .tmac and put it in some directory of the tmac path, see section R FILES . Then documents can include it with the request or the option . .

. . There is a convention that is supported by many modern roff type-setters and man(1) programs, the preprocessor word described in the following. .

If the first line in a document is a comment, the first word (after the comment characters and a blank) constitutes the preprocessor R word . That means that the letters of this word are interpreted as abbreviations for those preprocessor commands that should be run when formatting the document. . Mostly, only the letters corresponding to the options for the preprocessors are recognized, .'char e (for R eqn ), .'char p , (for R pic ), .'char R (for R refer ), .'char s (for R soelim ), and .'char t (for R tbl ). (see roff(7)). . .

Besides being a good reminder for the user, some formatters (like the man(1) program) are even able to automatically start the preprocessors specified in the preprocessor word, but do not bet on this. . .

The man program handles some preprocessors automatically, such that in man\~pages only the following characters should be used: .'char e , .'char p , and .'char t . . .

. 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. . These elements are described in roff(7). . .

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 reveals when arguments are passed with a macro call. . Within the macro definition, the arguments are available as the escape sequences R $1 , \*[Ellipsis], R $9 , R $[ \*[Ellipsis] ] , R $* , and R $@ , the name under which the macro was called is in R $0 , and the number of arguments is in register R \n[.$] ; see groff(7). . .

Copy-in Mode

. The phase when groff reads a macro is called copy-in mode in roff-talk. . This is comparable to the C\~preprocessing phase during the development of a program written in the C\~language. . .

In this phase, groff interprets all backslashes; that means that all escape sequences in the macro body are interpreted and replaced by their value. . For constant expression, this is wanted, but strings and registers that might change between calls of the macro must be protected from being evaluated. . This is most easily done by doubling the backslash that introduces the escape sequence. . This doubling is most important for the positional parameters. . For example, to print information on the arguments that were passed to the macro to the terminal, define a macro named `.print_args', say. . .

./Example . .

When calling this macro by

./Example

the following text is printed to the terminal: arg1 arg2 ./Example . .

Let's analyze each backslash in the macro definition. . As the positional parameters and the number of arguments will change with each call of the macro their leading backslash must be doubled, which results in \[rs]\[rs]$* and R \[rs]\[rs][.$] . The same applies to the macro name because it could be called with an alias name, so R \[rs]\[rs]$0 . . .

On the other hand, midpart is a constant string, it will not change, so no doubling for R \[rs]*[midpart] . The \[rs]f escape sequences are predefined groff elements for setting the font within the text. . Of course, this behavior will not change, so no doubling with \[rs]f[I] and R \[rs]f[] . . .

Draft Mode

. Writing groff macros is easy when the escaping mechanism is temporarily disabled. . In groff, this is done by enclosing the macro definition(s) into a pair of .eo and .ec requests. . Then the body in the macro definition is just like a normal part of the document \[em] text enhanced by calls of requests, macros, strings, registers, etc. . For example, the code above can be written in a simpler way by . .

./Example . .

Unfortunately, draft mode cannot be used universally. . Although it is good enough for defining normal macros, draft mode will fail with advanced applications, such as indirectly defined strings, registers, etc. . An optimal way is to define and test all macros in draft mode and then do the backslash doubling as a final step; do not forget to remove the .eo request. . .

Tips for Macro Definitions

. Start every line with a dot, for example, by using the groff request .nop for text lines, or write your own macro that handles also text lines with a leading dot. .

./Example . Write a comment macro that works both for copy-in and draft mode; for as escaping is off in draft mode, trouble might occur when normal comments are used. . For example, the following macro just ignores its arguments, so it acts like a comment line: .

./Example . In long macro definitions, make ample use of comment lines or empty lines for a better structuring. . To increase readability, use groff's indentation facility for requests and macro calls (arbitrary whitespace after the leading dot). . .

Diversions

. Diversions can be used to realize 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 they get their power when diversions are used dynamically within macros. . The 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 are conscious about the fact that diversions always deal with complete lines. . If diversions are used when the line buffer has not been flashed, strange results are produced; not knowing this, many people get desperate about diversions. . To ensure that a diversion works, line breaks should be added at the right places. . To be on the secure side, enclose everything that has to do with diversions into a pair of line breaks; for example, by amply 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. . .

. All macro names must be named B name .tmac to fully use the tmac mechanism. . I tmac. name as with classical packages is possible as well, but deprecated. . .

The macro files are kept in the R tmac directories ; a colon separated list of these constitutes the R tmac path . . .

The search sequence for macro files is (in that order): . the directories specified with troff/groff's -M command line option . the directories given in the environment variable . the current directory (only if in unsafe mode, which is enabled by the -U command line switch) . the home directory . a platform-specific directory, being /usr/lib/groff/site-tmac in this installation . a site-specific (platform-independent) directory, being /usr/share/groff/site-tmac in this installation . the main tmac directory, being /usr/share/groff/1.18.1/tmac in this installation . .

.

. Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc. .

This document is distributed under the terms of the FDL (GNU Free Documentation License) version 1.1 or later. . You should have received a copy of the FDL on your system, it is also available on-line at the .

This document is part of R groff , the GNU roff distribution. . It was written by it is maintained by . .

. A complete reference for all parts of the groff system is found in the groff info(1) file. .

groff(1)

groff_man(7),

groff_mdoc(7),

groff_me(7),

groff_mm(7),

groff_mom(7),

groff_ms(7),

groff_www(7).

groff(7)

The Filesystem Hierarchy Standard is available at the .