groff_mm(7) | Standards, Environments, and Macros | groff_mm(7) |
groff_mm - memorandum macros for GNU roff
groff -mgm |
[option ...] [file ...] |
groff -m mgm |
[option ...] [file ...] |
The GNU implementation of the mm macro package is part of the groff document formatting system. The mm package is suitable for the composition of letters, memoranda, reports, and books.
Call an mm macro at the beginning of a document to initialize the package. A simple mm document might use only P for paragraphing. Set numbered and unnumbered section headings with H and HU, respectively. Change the style of the typeface with B, I, and R; you can alternate styles with BI, BR, IB, IR, RB, and RI. Several nestable list types are available via AL, BL, BVL, DL, ML, RL, and VL; each of these begins a list, to which LI adds an item and LE ends the (nested) list. Customized list arrangements are supported by LB. DS and DF start static and floating displays, respectively; either is terminated with DE.
groff mm is intended to be compatible with the mm implementation found in the AT&T Documenter's Workbench (DWB), with the following limitations.
DWB mm supported only seven levels of heading. As a compatible extension, groff mm supports fourteen, introducing new registers H8 through H14, and affecting the interpretation of the HF and HP strings.
Macro, register, and string descriptions in this page frequently mention each other; most cross references are to macros. Where a register or string is referenced, its type is explicitly identified. mm's macro names are usually in full capitals; registers and strings tend to have mixed-case names.
groff mm offers three different frameworks for document organization. COVER/COVEND is a flexible means of preparing any document requiring a cover page. LT/LO aids preparation of typical Anglophone correspondence (business letters, for example). The MT memorandum type mechanism implements a group of formal styles historically used by AT&T Bell Laboratories. Your document can select at most one of these approaches; when used, each disables the others.
groff mm is designed to be easily localized. For languages other than English, strings that can appear in output are collected in the file /usr/share/groff/1.23.0/tmac/xx.tmac, where xx is an ISO 639 two-letter language identifier. Localization packages should be loaded after mm; for example, you might format a Swedish mm document with the command “groff -mm -msv”.
This package can also be localized by site or territory; for example, /usr/share/groff/1.23.0/tmac/gmse.tmac illustrates how to adapt the output to a national standard using its ISO 3166 territory code. Such a package can define a string that causes a macro file /usr/share/groff/1.23.0/tmac/mm/territory_locale to be loaded at package initialization. If this mechanism is not used, /usr/share/groff/1.23.0/tmac/mm/locale is loaded instead. No diagnostic is produced if these files do not exist.
Much mm behavior can be configured by registers and strings. A register is assigned with the nr request.
.nr ident [±]n [i]
ident is the name of the register, and n is the value to be assigned. n can be prefixed with a plus or minus sign if incrementation or decrementation (respectively) of the register's existing value by n is desired. If assignment of a (possibly) negative n is required, further prefix it with a zero or enclose it in parentheses. If i is specified, the register is automatically modified by i prior to interpolation if a plus or minus sign is included in the escape sequence as follows.
\n[±][ident]
i can be negative; it combines algebraically with the sign in the interpolation escape sequence.
Strings are defined with the ds request.
.ds ident contents
contents consumes everything up to the end of the line, including trailing spaces. It is a good practice to end contents with a comment escape sequence (\") so that extraneous spaces do not intrude during document maintenance. To include leading spaces in contents, prefix it with a double quote. Strings are interpolated with the \* escape sequence.
\*[ident]
Register and string name spaces are distinct, but strings and macros share a name space. Defining a string with the same name as an mm macro is not supported and may cause incorrect rendering, the emission of diagnostic messages, and an error exit status from gtroff.
A register is interpolated using Arabic numerals if no other format has been assigned to it. Assign a format to a register with the af request.
.af R c
R is the name of the register, and c is the format. If c is a sequence of Arabic numerals, their quantity defines a zero-padded minimum width for the interpolated register value.
Form | Sequence |
1 | 0, 1, 2, 3, ..., 10, ... |
001 | 000, 001, 002, 003, ..., 1000, ... |
i | 0, i, ii, iii, iv, ... |
I | 0, I, II, III, IV, ... |
a | 0, a, b, c, ..., z, aa, ab, ... |
A | 0, A, B, C, ..., Z, AA, AB, ... |
In groff mm, the fonts (or rather, font styles) R (roman), I (italic), and B (bold) are mounted at font positions 1, 2, and 3, respectively. Internally, font positions are used for backward compatibility. From a practical point of view, it doesn't make a big difference—a different font family can still be selected by invoking groff's fam request or using its -f command-line option. On the other hand, if you want to replace just, for example, font I with Zapf Chancery Medium italic (available on groff's pdf and ps output devices), you have to use the fp request, replacing the font at position 2 with “.fp 2 ZCMI”). Because the cover sheet, memorandum type, and grefer(1) integration macros explicitly request fonts named B, I, and R, you will also need to remap these font names with the ftr request, for instance with “.ftr I ZCMI”.
An explicitly empty argument may be specified with a pair of double quotes; to call a macro XX with an empty second argument but non-empty first and third ones, you could input the following.
.XX foo "" baz
Macro names longer than two characters are GNU extensions; some shorter names were not part of DWB mm's published interface but are documented aspects of groff mm.
placement | Effect |
0 | The abstract appears on page 1 and cover sheet if the document is a “released paper” memorandum (“ ".MT 4" ”); otherwise, it appears on page 1 without a cover sheet. |
1 | The abstract appears only on the cover sheet (“ ".MT 4" ” only). |
.COVER .TL .AF .AU .AT .AS .AE .COVEND
format | Effect |
none | Do not indent the display. |
L | Do not indent the display. |
I | Indent text by \n[Si] . |
C | Center each line. |
CB | Center the whole display as a block. |
R | Right-adjust the lines. |
RB | Right-adjust the whole display as a block. |
fill | Effect |
none | Disable filling. |
N | Disable filling. |
F | Enable filling. |
flag | Effect |
0 | Prefix number with override . |
1 | Suffix number with override . |
2 | Replace number with override . |
Strings available to EOP | |
EOPf | argument to PF |
EOPef | argument to EF |
EOPof | argument to OF |
arg | Hyphenate? | Adjust? | Indent? | Label alignment |
0 | no | yes | yes | left |
1 | yes | yes | yes | left |
2 | no | no | yes | left |
3 | yes | no | yes | left |
4 | no | yes | no | left |
5 | yes | yes | no | left |
6 | no | no | no | left |
7 | yes | no | no | left |
8 | no | yes | yes | right |
9 | yes | yes | yes | right |
10 | no | no | yes | right |
11 | yes | no | yes | right |
location-type | Entry format |
N | page number |
H | heading mark |
B | page number, tab character, heading mark |
type | Output for a mark “x” |
1 | x. |
2 | x) |
3 | (x) |
4 | [x] |
5 | <x> |
6 | {x} |
option | Effect |
AT | Attention; put contents of string LetAT and value left-aligned after the inside address. |
CN | Confidential; put value, or contents of string LetCN , left-aligned after the date. |
RN | Reference; put contents of string LetRN and value after the confidental notation (if any) and the date, aligned with the latter. |
SA | Salutation; put value, or contents of string LetSA , left-aligned after the inside address and the confidental notation (if any). |
SJ | Subject; put contents of string LetSJ and value left-aligned after the inside address and the attention and salutation notations (if any). . In letter type “SP”, LetSJ is ignored and value is set in full capitals. |
style | Description |
BL | Blocked: the writer's address, date, formal closing, and signature are indented to the center of the line. . Everything else is left-aligned. |
SB | Semi-blocked: as BL , but the first line of each paragraph is indented by 5m . . |
FB | Fully blocked: everything begins at the left margin. |
SP | Simplified: as FB , but a formal closing is omitted, and the signature is set in full capitals. |
type | Description |
0 | normal memorandum; no caption |
1 | captioned “MEMORANDUM FOR FILE” |
2 | captioned “PROGRAMMER'S NOTES” |
3 | captioned “ENGINEER'S NOTES” |
4 | released paper |
5 | external letter |
"''- % -''"
Strings available to TP | |
TPh | argument to PH |
TPeh | argument to EH |
TPoh | argument to OH |
Value | Effect |
1 | Disable the formatter's escape character (\). |
2 | Vertically space before the display. |
4 | Vertically space after the display. |
8 | Number output lines; call formatter's nm request with arguments in string Verbnm . |
16 | Indent by the amount stored in register Verbin . |
format | Effect |
N | equivalent to “ "-WF -FF -WD" ” . (default) |
WF | set footnotes at full line length, even in two-column mode . |
-WF | set footnotes using column line length |
FF | apply width of first footnote to encountered to subsequent ones |
-FF | footnote width determined by WF and -WF |
WD | set displays at full line length, even in two-column mode . |
-WD | set displays using column line length |
Many mm strings interpolate predefined, localizable text. These are presented in quotation marks.
NS code | String | Contents |
0 | Letns!0 | Copy to |
1 | Letns!1 | Copy (with att.) to |
2 | Letns!2 | Copy (without att.) to |
3 | Letns!3 | Att. |
4 | Letns!4 | Atts. |
5 | Letns!5 | Enc. |
6 | Letns!6 | Encs. |
7 | Letns!7 | Under separate cover |
8 | Letns!8 | Letter to |
9 | Letns!9 | Memorandum to |
10 | Letns!10 | Copy (with atts.) to |
11 | Letns!11 | Copy (without atts.) to |
12 | Letns!12 | Abstract Only to |
13 | Letns!13 | Complete Memorandum to |
14 | Letns!14 | CC |
— | Letns!copy | Copy (with trailing space) |
— | Letns!to | to (note leading space) |
Value | Meaning |
co | Table of contents |
fg | List of figures |
tb | List of tables |
ec | List of equations |
ex | List of exhibits |
ap | Appendix |
Default register values, where meaningful, are shown in parentheses. Many are also marked as Boolean-valued, meaning that they are considered “true” (on, enabled) when they have a positive value, and “false” (off, disabled) otherwise.
Value | Effect |
0 | Flush pending displays at the end of each section when section-page numbering is active, otherwise at the end of the document. |
1 | Flush a pending display on the current page or column if there is enough space, otherwise at the end of the document. |
2 | Flush one pending display at the top of each page or column. |
3 | Flush a pending display on the current page or column if there is enough space, otherwise at the top of the next. |
4 | Flush as many pending displays as possible in a new page or column. |
5 | Fill columns or pages with flushed displays until none remain. |
Value | Effect |
0 | no indentation |
1 | indent per the paragraph type |
2 | indent to align with heading title |
Value | Effect |
0 | Set header on all pages. |
1 | Move header to footer on page 1. |
2 | Omit header on page 1. |
3 | Use “section-page” numbering style on all pages. |
4 | Omit header on all pages. |
5 | Use “section-page” and “section-figure” numbering style on all pages. |
Value | Effect |
0 | ". " |
1 | " — " |
Value | Effect |
0 | never |
1 | always |
2 | always, except immediately after H , DE , or LE |
Value | Effect |
0 | Break the page before and after the list of references. |
1 | Suppress page break after the list. |
2 | Suppress page break before the list. |
3 | Suppress page breaks before and after the list. |
The LT letter macros call further macros depending on the letter type, with which they are suffixed. It is therefore possible to define additional letter types, either in the territory-specific macro file, or as local additions. LT sets the registers Pt and Pi to 0 and 5, respectively. The following macros must be defined to support a new letter type.
LO implements letter options. It requires that a string named Lettype be defined, where type is the letter type. LO then assigns its second argument (value) to the string let*lo-type.
The GNU version of the mm macro package was written by Jörgen Hägg of Lund, Sweden.
MM - A Macro Package for Generating Documents, the DWB 3.3 mm manual, introduces the package but does not document GNU extensions.
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), gtroff(1), gtbl(1), gpic(1), geqn(1), grefer(1), groff_mmse(7)
2 July 2023 | groff 1.23.0 |