groff_mm

Name

groff_mm - memorandum macros for GNU roff

Synopsis

groff -mm [option ...] [file ...] groff -m mm [option ...] [file ...]

Description

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.

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.

Document styles

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. A simple mm document might use only H (or HU) and P for headings and paragraphing, respectively.

Localization

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/ local/share/groff/1.23.0/tmac/xx.tmac, where xx is an ISO 639 two-letter language identifier. For Swedish, this is sv.tmac; “sv”, not “se”.

This package can also be localized by site or territory; for example, /usr/ local/share/groff/1.23.0/tmac/mse.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/local/share/groff/1.23.0/ tmac/mm/territory_locale to be loaded at package initialization. If this mechanism is not used, /usr/local/share/groff/1.23.0/tmac/mm/locale is loaded instead. No diagnostic is produced if these files do not exist.

Registers and strings

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 troff.

Register format

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.

Fonts

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 backwards 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 refer(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”.

Macros

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.
)E level text

Add heading text text to the table of contents with level, which is either 0 or in the range 1 to 7. See also .H. This undocumented DWB mm macro is exposed by groff mm to enable customized tables of contents.

1C [1]

Begin one-column formatting after breaking the page. A 1 argument suppresses the page break, but if a footnote is pending, it may be overprinted. See 2C, MC, and NCOL.

AF [name-of-firm]

Author’s firm, should be called before AU, see also COVER.

AL [type [text-indent [1]]]

Start an auto-incrementing list. Items are numbered beginning with one. The type argument assigns the register format (see above) of the list item enumerators. The default is 1. An explicitly empty type also indicates the default. text-indent sets the indentation in ens, overriding register Li. If a third argument, conventionally 1, is given, the blank line that normally precedes each list item is suppressed. Use LI to declare list items, and LE to end the list.

APP [id [title]]

Begin an appendix. If the identifier id is omitted, it is incremented (or initialized, if necessary). The register format used for id is “A”. The page is broken. The register Aph determines whether an appendix heading is then formatted. This heading uses the string App followed by id. Appendices appear in any table of contents (see TC). The string Apptxt is set to title if the latter is present, and made empty otherwise.

APPSK id n [title]

As .APP, but increment the page number by n. Use this macro to “skip pages” when diagrams or other materials not formatted by troff are included in appendices.

AS [placement [indentation]]

Abstract start; begin collecting abstract. Input up to the next AE call is included in the abstract. placement influences the location of the abstract on the cover sheet of a memorandum (see MT). COVER, by contrast, ignores placement by default, but can be customized to interpret it.

An abstract does not appear at all in external letters (.MT 5). A placement of 2 was supported by DWB mm but is not by groff mm.

A second argument increases the indentation by indentation and reduces the line length by twice this amount. A scaling unit of ens is assumed. The default is 0.

AST [heading]

Set the heading above the abstract to heading, or clear it if there is no argument. The default is “ABSTRACT”.

AT title [...]

Author’s title(s). If present, AT must appear just after the corresponding author’s AU. Each title shows up on a separate output line after the name in the signature block and in the ms cover sheet style.

AU [name [initials [loc [dept [ext [room [arg1 [arg2 [arg3]]]]]]]]]

Specify author. AU terminates a document title being collected with TL, and can be called without arguments for that sole purpose. Author information is used by cover sheets and predefined memorandum types (MT). It can contain initials, location, department, telephone extension, room number or name, and up to three additional arguments. Repeat AU to identify multiple authors.

Use WA/WE instead to identify the author for documents employing LT.

AV [name [1]]

Approval signature. Generates an approval line with place for signature and date. The text “APPROVED:” can be changed with the string Letapp; it is replaced with an empty line if there is a second argument. The text “Date” can be changed with the string Letdate.

AVL [name]

Letter signature. Generates a line with place for signature.

B [bold-text [previous-font-text]] ...

Join bold-text in boldface with previous-font-text in the previous font, without space between the arguments. If no arguments, switch font to bold style.

BI [bold-text [italic-text]] ...

Join bold-text in boldface with italic-text in italics, without space between the arguments.

BL [text-indent [1]]

Start bullet list. Initializes a list with a bullet and a space in the beginning of each list item (see LI). text-indent sets the indentation in ens, overriding register Pi. A third argument prohibits printing of a blank line before each item.

BR [bold-text [roman-text]] ...

Join bold-text in boldface with roman-text in roman style, without space between the arguments.

BVL text-indent [mark-indent [1]]

Start of broken variable-item list. Broken variable-item list has no fixed mark, it assumes that every LI has a mark instead. The text always begins at the next line after the mark. text-indent sets the indentation to the text, and mark-indent the distance from the current indentation to the mark. A third argument prohibits printing of a blank line before each item.

COVER [style]

Begin a cover sheet description. It is important that COVER appear before any of the body text (or main matter) of a document. The argument style is used to construct the file name /usr/local/share/ groff/1.23.0/tmac/mm/style.cov and load it with the mso request. Therefore it is possible to create unlimited types of cover sheets. The default style is ms; it structures a cover sheet to resemble that used by the ms package. COVER requires a COVEND at the end of the cover description. Always use the following ordering of the cover sheet macros.

.COVER
.TL
.AF
.AU
.AT
.AS
.AE
.COVEND

Only .TL and .AU are required.

COVEND

End the cover description and output the cover page. This macro is defined in the cover sheet macro file.

DF [format [fill [rindent]]]

Begin floating display. A floating display is saved in a queue and is printed in the order entered. The arguments format, fill, and rindent are handled as in DS. Floating displays cannot be nested. Floating display output is controlled by the registers De and Df.

DL [text-indent [1 [1]]]

Dash list start. Begins a list where each item is printed after a dash. text-indent sets the indentation in ens, overriding register Pi. A second argument prevents an empty line between each list item. See LI. A third argument prohibits printing of a blank line before each item.

DS [format [fill [rindent]]]

Static display start. Begins collection of text until DE. The text is printed together on the same page, unless it is longer than the height of the page. DS can be nested arbitrarily.

The values “L”, “I”, “C”, and “CB” can also be specified as “0”, “1”, “2”, and “3”, respectively, for compatibility reasons.

“N” and “F” can also be specified as “0” and “1”, respectively.

By default, an empty line is printed before and after the display. Setting register Ds to 0 prevents this. rindent shortens the line length by that amount.

EC [title [override [flag [refname]]]]

Caption an equation. The caption consists of the string Liec followed by an automatically incrementing counter stored in the register Ec, punctuation configured by the register Of, then title (if any). Use the af request to configure Ec’s number format. override and flag alter the equation number as follows. Omitting flag and specifying 0 in its place are equivalent.

Equation captions are centered irrespective of the alignment of any enclosing display.

refname stores the equation number using SETR; it can be retreived with “.GETST refname”. This argument is a GNU extension.

Captioned equations are listed in a table of contents (see TC) if the Boolean register Le is true. Such a list uses the string Le as a heading.

EF ["'left'center'right'"]

Define the even-page footer, which is formatted just above the normal page footer on even-numbered pages. See PF. EF defines the string EOPef.

EH ["'left'center'right'"]

Define the even-page header, which is formatted just below the normal page header on even-numbered pages. See PH. EH defines the string TPeh.

Strings available to EOP

EPIC [-L] width height [name]

Draw a box with the given width and height. It also prints the text name or a default string if name is not specified. This is used to include external pictures; just give the size of the picture. -L left-aligns the picture; the default is to center. See PIC.

EQ [label]

Start equation input preprocessed by eqn(1). EQ and EN macro calls bracket an equation region. Such regions must be contained in displays (DS/DE), except when the region is used only to configure eqn and not to produce output. If present, label appears at the aligned to the right and centered vertically within the display; see register Eq. If multiple eqn regions occur within a display, only the last label (if any) is used.

EX [title [override [flag [refname]]]]

Caption an exhibit. Arguments are handled analogously to EC. The register Ex is the exhibit counter. The string Liex precedes the exhibit number and any title. Exhibit captions are centered irrespective of the alignment of any enclosing display.

Captioned exhibits are listed in a table of contents (see TC) if the Boolean register Lx is true. Such a list uses the string Lx as a heading.

FC [closing]

Print “Yours very truly,” as a formal closing of a letter or memorandum. The argument replaces the default string. The default is stored in the string Letfc.

FD [arg [1]]

Footnote default format. Controls the hyphenation (hyphen), adjustment to the right margin (adjust), and indentation of footnote text (indent). It can also change the label justification (ljust).

An argument greater than or equal to 11 is considered as value 0. The default for mm is 10.

FG [title [override [flag [refname]]]]

Caption a figure. Arguments are handled analogously to EC. The register Fg is the figure counter. The string Lifg precedes the figure number and any title. Figure captions are centered irrespective of the alignment of any enclosing display.

Captioned figures are listed in a table of contents (see TC) if the Boolean register Lf is true. Such a list uses the string Lf as a heading.

FS [label]

Footnote start. Text until FE is called is collected into a footnote. By default, footnotes are automatically numbered starting at 1; the number is available in register :p and, with a trailing period, in string F. This string precedes the footnote text at the bottom of the column or page. Footnotes are vertically separated by the product of registers Fs and Lsp. In groff mm, footnotes may be used in displays.

A label argument replaces the contents of the string F; it need not be numeric. In this event, the footnote marker in the body text must be explicitly written.

GETHN refname [varname]

Include the header number where the corresponding “.SETR refname” was placed. This is displayed as “X.X.X.” in pass 1. See INITR. If varname is used, GETHN sets the string varname to the header number.

GETPN refname [varname]

Include the page number where the corresponding “.SETR refname” was placed. This is displayed as “9999” in pass 1. See INITR. If varname is used, GETPN sets the string varname to the page number.

GETR refname

Combine GETHN and GETPN with the text “chapter” and “, page”. The string Qrf contains the text for the cross reference:

.ds Qrf See chapter \\*[Qrfh], page \\*[Qrfp].

Qrf may be changed to support other languages. Strings Qrfh and Qrfp are set by GETR and contain the page and header number, respectively.

GETST refname [varname]

Include the string saved with the second argument to .SETR. This is a dummy string in pass 1. If varname is used, GETST sets it to the saved string. See INITR.

H level [title [suffix]]

Set a numbered section heading at level. mm produces numbered headings in the form a.b.c..., with up to fourteen levels of nesting. The numbering of each level increases automatically and is reset to zero when a more significant level is specified. “1” is the most significant or coarsest division of the document. Text after an H call is formatted as a paragraph; calling P is unnecessary.

title specifies an optional title; it must be double-quoted if it contains spaces. suffix is appended to the heading title in the body of the document, but omitted from any table of contents (see TC). This facility can be used to annotate the heading title with a footnote. suffix should not include \*F; specify a footnote mark explicitly. See FS.

Heading behavior is highly configurable. Several registers set a threshold, where heading levels at or below the threshold value are handled in one way, and those above it another. For example, a heading level within the threshold of register Cl is included in the table of contents (see TC).

Heading layout. Register Ej sets a threshold for page breaking (ejection) prior to a heading. If not preceded by a page break, a heading level below the threshold in register Hps is preceded by the amount of vertical space in register Hps1, and by the amount in Hps2 otherwise. The Hb register sets a threshold below which a break occurs after the heading, and register Hs sets a threshold below which vertical space follows it. If the heading level is not less than both of these, a run-in heading is produced; paragraph text follows on the same output line. Otherwise, register Hi configures the indentation of text after headings. Threshold register Hc enables the centering of headers; a heading level below both of the Hb and Hc thresholds is centered.

Heading typeface and size. The fonts used for heading numbers and titles at each level are configured by the HF string. The string HP likewise assigns a type size to each heading level. The vertical spacing used by headings may be controlled by the user-definable macros HX and/or HZ.

Heading number format. Registers named H1 through H14 store counters for each heading level. Their values are printed using Arabic numerals by default; see HM. The heading levels are catenated with dots for formatting; to typeset only the deepest, set the Ht register. Heading numbers are not suffixed with a trailing dot except when only the first level is output; to omit a dot in this case as well, clear the H1dot register.

Customizing heading behavior. mm calls hook macros to enable further customization of headings. (DWB mm called these “exits”.) They can be used to change the heading’s mark (the numbered portion before any heading title), its vertical spacing, and its vertical space requirements (for instance, to require a minimum quantity of subsequent output lines). Define hook macros in expectation of the following parameters. The argument declared-level is the level argument to H, or 0 for unnumbered headings (see HU). actual-level is the same as declared-level for numbered headings, and the value of register Hu for unnumbered headings. title is the corresponding argument to H or HU.
HX declared-level actual-level title

mm calls HX before setting the heading. Your definition may alter }0, }2, and ;3.
}0 (string)

contains the heading mark plus two spaces if declared-level is non-zero, and otherwise is empty.

;0 (register)

encodes a position for the text after the heading. 0 means that the heading is to be run in, 1 means that a break is to occur before the text, and 2 means that vertical space is to separate heading and text.

}2 (string)

is the suffix that separates a run-in heading from the text. It contains two spaces if register ;0 is 0, and otherwise is empty.

;3 (register)

contains the vertical space required for the heading to be typeset. If that amount is not available, the page is broken prior to the heading. The default is 2v.

HY declared-level actual-level title

mm calls HY after determing the header typeface and size. It might be used to change indentation.

HZ declared-level actual-level title

mm calls HZ after formatting the heading, just before H or HU returns. It might be used to change the page header to include a section heading.

HC [hyphenation-character]

Set hyphenation character. Default value is “\%”. Resets to the default if called without argument. Hyphenation can be turned off by setting register Hy to 0 at the beginning of the file.

HM [arg1 [arg2 [... [arg14]]]]

Set the heading mark style. Each argument assigns the specified register format (see above) to the corresponding heading level. The default is 1 for all levels. An explicitly empty argument also indicates the default.

HU heading-text

Set an unnumbered section heading. Except for a heading number, it is treated as a numbered heading of the level stored in register Hu; see H. see H.

I [italic-text [previous-font-text]] ...

Join italic-text in italics with previous-font-text in the previous font, without space between the arguments. If no arguments, switch font to italic style.

IA [addressee-name [title]]

Begin specification of the addressee and addressee’s address in letter style. Several names can be specified with empty IA/IE-pairs, but only one address. See LT.

IB [italic-text [bold-text]] ...

Join italic-text in italics with bold-text in boldface, without space between the arguments.

INITI type filename [macro]

Initialize the new index system and set the filename to collect index lines in with IND. Argument type selects the type of index: page number, header marks or both. The default is page numbers.

It is also possible to create a macro that is responsible for formatting each row; just add the name of the macro as a third argument. The macro is then called with the index as argument(s).

INITR id

Initialize the cross reference macros. Cross references are written to the standard error stream, which should be redirected into a file named id.qrf. mmroff(1) handles this and the two formatting passes it requires. The first pass identifies cross references, and the second one includes them.

See SETR, GETPN, and GETHN.

IND arg1 [arg2 [...]]

Write a line in the index file selected by INITI with all arguments and the page number or header mark separated by tabs.

Examples

arg1\tpage number
arg1\targ2\tpage number
arg1\theader mark
arg1\tpage number\theader mark

IR [italic-text [roman-text]] ...

Join italic-text in italics with roman-text in roman style, without space between the arguments.

ISODATE [0]

Use ISO 8601 format for the date string DT used by some cover sheet and memorandum types; that is, YYYY-MM-DD. Must be called before ND to be effective. If given an argument of 0, the traditional date format for the groff locale is used; this is also the default.

LB text-indent mark-indent pad type [mark [LI-space [LB-space]]]

List-begin macro. This is the common macro used for all lists. text-indent is the number of spaces to indent the text from the current indentation.

pad and mark-indent control where to put the mark. The mark is placed within the mark area, and mark-indent sets the number of spaces before this area. By default it is 0. The mark area ends where the text begins. The start of the text is still controlled by text-indent.

The mark is left-justified within the mark area if pad is 0. If pad is greater than 0, mark-indent is ignored, and the mark is placed pad spaces before the text. This right-justifies the mark.

type selects one of six possible ways to display the mark.

If type is 0 the list either has a hanging indentation or, if argument mark is given, the string mark as a mark.

If type is greater than 0 automatic numbering occurs, using Arabic numerals if mark is empty. mark can then be any of “1”, “A”, “a”, “I”, or “i”.

Every item in the list gets LI-space number of blank lines before them. Default is 1.

LB itself prints LB-space blank lines. Default is 0.

LC [list-level]

List-status clear. Terminates all current active lists down to list-level, or 0 if no argument is given. This is used by H to clear any active list.

LE [1]

List end. The current list is terminated. If an argument 1 is present, vertical space in the amount of register Lsp follows.

LI [mark [1|2]]

List item preceding every item in a list. Without argument, LI prints the mark determined by the current list type. By giving LI one argument, it uses that as the mark instead. Two arguments to LI makes mark a prefix to the current mark. There is no separating space between the prefix and the mark if the second argument is “2” instead of “1”. This behaviour can also be achieved by setting register Limsp to zero. A zero length mark makes a hanging indentation instead.

A list item is preceded by vertical space unless its nesting level is greater than the value of register Ls. The amount of space is determined by the register Lsp and an argument to LB.

The Li register configures the indentation amount in ens.

All lists begin with a list initialization macro, LB. There are, however, seven predefined list types to make lists easier to use. They all call LB with different default values.

LO type [arg]

Specify options in letter (see .LT). This is a list of the standard options:

LT [arg]

Format a letter in one of four different styles depending on the argument. Also see section “Internals” below.

MC column-width [gutter-width]

Begin multi-column layout. groff mm creates as many columns of column-width as the line length will permit. gutter-width is the interior spacing between columns. It defaults to column-width/15. 1C returns to single-column layout. MC is a GNU extension. See MULB for an alternative.

ML mark [text-indent [1]]

Start a list with the mark argument preceding each list item. text-indent overrides the default indentation of the list items set by register Li. If a third argument, conventionally 1, is given, the blank line that normally precedes each list item is suppressed. Use LI to declare list items, and LE to end the list.

MT [type [addressee]]

Select memorandum type. These correspond to formats used by AT&T Bell Laboratories, where the mm package was initially developed, affecting the document layout. Some of these included a cover page with a caption categorizing the document. groff mm uses type to construct the file name /usr/local/share/groff/1.23.0/tmac/mm/type .MT and load it with the mso request. Memorandum types 0 to 5 are supported; any other value of type is mapped to type 6. If type is omitted, 0 is implied. addressee sets a string analogous to one used by AT&T cover sheet macros that are not implemented in groff mm.

See COVER for a more flexible cover sheet mechanism.

MOVE y-pos [x-pos [line-length]]

Move to a position, setting page offset to x-pos. If line-length is not given, the difference between current and new page offset is used. Use PGFORM without arguments to return to normal.

MULB cw1 space1 [cw2 space2] ... cwn

Begin alternative multi-column mode. All column widths must be specified, as must the amount of space between each column pair. The default unit for the width and space arguments is “n”. .MULB uses a diversion and operates in a separate environment.

ND new-date

New date. Overrides the current date. Date is not printed if new-date is an empty string.

nP [type]

Print numbered paragraph with header level two. See .P.

NS [arg [1]]

Collect notations of the type specified by arg until NE is called; filling is disabled. If a second argument, conventionally 1, is given, then the argument becomes the entire notation and NE is not necessary. If arg does not match one of the predefined types listed below, the notations are prefixed with “Copy (arg) to”. In groff mm, you can set up further notations to be recognized by NS; see the strings Letns and Letnsdef below.

OF ["'left'center'right'"]

Define the odd-page footer, which is formatted just above the normal page footer on odd-numbered pages. See PF. OF defines the string EOPof.

OH ["'left'center'right'"]

Define the odd-page header, which is formatted just below the normal page header on odd-numbered pages. See PH. OH defines the string TPoh.

P [type]

Begin new paragraph. P without argument produces left-justified text, even the first line of the paragraph. This is the same as setting type to 0. If type is 1, the first output line of the paragraph is indented by \[Pi] ens.

Instead of giving an argument to P it is possible to set the paragraph type in register Pt. Using 0 and 1 is the same as adding that value to P. A value of 2 indents all paragraphs, except after headings, lists, and displays (this value can’t be used as an argument to P itself).

The space between two paragraphs is controlled by register Ps, and is 1 by default (one blank line).

PGFORM [linelength [pagelength [pageoffset [1]]]]

Set line length, page length, and/or page offset. This macro can be used for special formatting, like letter heads and other. It is normally the first macro call in a file, though it is not necessary. PGFORM can be used without arguments to reset everything after a MOVE call. A line break is done unless the fourth argument is given. This can be used to avoid the page number on the first page while setting new width and length. (It seems as if this macro sometimes doesn’t work too well. Use the command-line arguments to change line length, page length, and page offset instead.)

PIC [-B] [-C|-I n|-L|-R] file [width [height]]

Include PostScript document file. This macro depends on mmroff(1) and INITR. The optional -B argument draws a box around the picture. The optional -L, -C, -R, and -I n arguments align the picture or indent it by n (assuming a scaling unit of m). By default, the picture is left-aligned. Optional width and height arguments resize the picture.

PF ["'left'center'right'"]

Define the page footer. The footer is formatted at the bottom of each page; the argument is otherwise as described in PH. PF defines the string EOPf. See EF, OF, and EOP.

PH ["'left'center'right'"]

Define the page header, formatted at the top of each page, as the argument, where left, center, and right are aligned to the respective locations on the line. A “%” character appearing within arg is replaced by the current page number. If the argument is absent, no page header is set. The default page header is

"''- % -''"

which centers the page number between hyphens and formats nothing at the upper left and right. Header macros call PX (if defined) after formatting the header. PH defines the string TPh. See EH, OH, and TP.

R [roman-text [previous-font-text]] ...

Join roman-text in roman style with previous-font-text in the previous font, without space between the arguments. If no arguments, switch font to roman style.

RB [roman-text [bold-text]] ...

Join roman-text in roman style with bold-text in boldface, without space between the arguments.

RD [prompt [diversion [string]]]

Read from standard input to diversion and/or string. The text is saved in a diversion named diversion. Recall the text by writing the name of the diversion after a dot on an empty line. A string is also defined if string is given. Diversion and/or prompt can be empty ("").

RI [roman-text [italic-text]] ...

Join roman-text in roman style with italic-text in italics, without space between the arguments.

RL [text-indent[1]]

Reference list start. Begins a list where each item is preceded with an automatically incremented number between square brackets. text-indent changes the default indentation.

RP [suppress-counter-reset [page-ejection-policy]]

Format a reference page, listing items accumulated within RS/RF pairs. The reference counter is reset unless the first argument is 1. Normally, page breaks occur before and after the references are output; the register Rpe configures this behavior, and a second argument overrides its value. TC calls RP automatically if references have accumulated.

References are list items, and thus are vertically separated (see LB). Setting register Ls to 0 suppresses this spacing. The string Rp contains the reference page caption.

RS [string-name]

Begin an automatically numbered reference definition. Put the string \*(Rf where the reference mark should be and write the reference between RS/RF at next new line after the reference mark. The reference number is stored in register :R. If string-name is given, a string with that name is defined and contains the current reference mark. The string can be referenced as \*[string-name] later in the text.

S [size [spacing]]

Set point size and vertical spacing. If any argument is equal to “P”, the previous value is used. A “C” means the current value, and “D” the default value. If “+” or “-” is used before the value, the current value is incremented or decremented, respectively.

SA [mode]

Set or restore the default enablement of adjustment. Specify 0 or 1 as mode to set a document’s default explicitly; 1 is assumed by mm. Adjustment can be temporarily suspended with the na request. When the H or HU macros are used to format a heading, or when SA is called without a mode argument, the default adjustment is restored.

SETR refname [string]

Remember the current header and page number as refname. Saves string if string is defined. string is retrieved with .GETST. See INITR.

SG [arg [1]]

Signature line. Prints the authors name(s) after the formal closing. The argument is appended to the reference data, printed at either the first or last author. The reference data is the location, department, and initials specified with .AU. It is printed at the first author if the second argument is given, otherwise at the last. No reference data is printed if the author(s) is specified through .WA/.WE. See section “Internals” below.

SK [n]

Skip n pages. If n is 0 or omitted, the page is broken unless the drawing position is already at the top of a page. Otherwise, n pages, blank except for any headers and footers, are printed.

SM string1 [string2 [string3]]

Make a string smaller. If string2 is given, string1 is made smaller and string2 stays at normal size, concatenated with string1. With three arguments, everything is concatenated, but only string2 is made smaller.

SP [lines]

Space vertically. lines can have any scaling factor, like “3i” or “8v”. Several SP calls in a line only produces the maximum number of lines, not the sum. SP is ignored also until the first text line in a page. Add \& before a call to SP to avoid this.

TB [title [override [flag [refname]]]]

Caption a table. Arguments are handled analogously to EC. The register Tb is the table counter. The string Litb precedes the table number and any title. Table captions are centered irrespective of the alignment of any enclosing display.

Captioned tables are listed in a table of contents (see TC) if the Boolean register Lt is true. Such a list uses the string Lt as a heading.

TC [slevel [spacing [tlevel [tab [h1 [h2 [h3 [h4 [h5]]]]]]]]]

Output table of contents. This macro is normally the last called in the document. It flushes any pending displays and, if any references are pending (see RS), calls RP. It then begins a new page with the contents caption, stored in the string Licon, centered at the top. The entries follow after three vees of space. Each entry is a saved section (number and) heading title (see the Cl register), along with its associated page number. By default, an entry is indented by an amount corresponding to its heading level and the maximum heading length encountered at that heading level; if defined, the string Ci overrides these indentations. Entries at heading levels up to and including slevel are preceded by spacing vees of space. Entries at heading levels up to and including tlevel are followed by a leader and a right-aligned page number. If the Boolean-valued tab argument is true, the leader is replaced with horizontal motion in the same amount. For entries above heading level tlevel, the page number follows the heading text after a word space. Each argument h1...h5 appears in order on its own line, centered, above the contents caption. Page numbering restarts at 1, in register format “i”. If the Oc register is true, numbering of these pages is suppressed.

If TC is called with at most four arguments, it calls the user-defined macro TX (if defined) prior to formatting the contents caption, and TY (if defined) instead of formatting the contents caption.

Analogous handling of lists of figures, tables, equations, and exhibits is achieved by defining TXxx and TYxx macros, where xx is “FG”, “TB”, “EC”, or “EX”, respectively. Similarly, the strings Lifg, Litb, Liex, and Liec determine captions for their respective lists.

TH [N]

Table header. See TS. TH ends the header of the table. This header is printed again if a page break occurs. Argument “N” isn’t implemented yet.

TL [charging-case-number [filing-case-number]]

Begin collecting document title. Text up to the next AU call is included in the title. charging-case-number and filing-case-number are saved for use in memorandum types 0 and 5. See MT.

TM number ...

Declare technical memorandum number(s) used by MT.

strings available to TP

TS [H]

Table start. This is the start of a table specification to tbl(1). TS ends with TE. Argument “H” tells mm that the table has a header. See TH.

VERBON [format [type-size [font]]]

Begin verbatim display, where characters have equal width. format controls several parameters. Add up the values of desired features; the default is 0.

On typesetting devices, type-size selects a different type size in scaled points, and font chooses a face—the default is Courier roman.

VERBOFF

End verbatim display.

VL text-indent [mark-indent [1]]

Variable-item list. It has no fixed mark, it assumes that every LI has a mark instead. text-indent sets the indent to the text, and mark-indent the distance from the current indentation to the mark. A third argument prohibits printing of a blank line before each item.

VM [-T] [top [bottom]]

Vertical margin. Increase the top and bottom margin by top and bottom, respectively. If option -T is specified, set those margins to top and bottom. If no argument is given, reset the margin to zero, or to the default (“7v 5v”) if -T is used. It is highly recommended that macros TP and/or EOP are defined if using -T and setting top and/or bottom margin to less than the default. This undocumented DWB mm macro is exposed by groff mm to increase user control of page layout.

WA [writer-name [title]]

Begin specification of the writer and writer’s address. Several names can be specified with empty WA/WE pairs, but only one address.

WC [format1] [format2] [...]

Footnote and display width control.

Strings

Many mm strings interpolate predefined, localizable text. These are presented in quotation marks.

Apptxt

stores the title argument to the last APP call.

Indcmd

Contains the index command. Default value is “sort -t\t”.

Letapp

“APPROVED:” (see AV)

Letdate

“Date” (see AV)

Letnsdef

Define the standard notation used when no argument is given to .NS. Default is 0.

MO1...MO12

“January” through “December”

Verbnm

Argument to .nm in the .VERBON macro. Default is 1.

Registers

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.

H1...H14

are auto-incrementing counters corresponding to each heading level; see H.

Letwam

sets the maximum number of input lines permitted in a writer’s address; see WA and WE (14).

Verbin

configures the amount of indentation for verbatim displays when indentation is selected; see VERBON (5n).

Internals

The letter macros use different submacros depending on the letter type. The name of the submacro has the letter type as suffix. It is therefore possible to define other 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 strings and macros must be defined for a new letter type.
let@init_type

This macro is called directly by .LT. It is supposed to initialize registers and other stuff.

let@head_type

This macro prints the letter head, and is called instead of the normal page header. It is supposed to remove the alias let@header, otherwise it is called for all pages.

let@sg_type name title n is-surname [SG-arg ...]

.SG calls this macro only for letters; memoranda have their own processing. name and title are specified through .WA/.WE. n is the index of the nth author, and is-surname is true for the last name. Further .SG arguments are appended to the signature line.

let@fc_type closing

This macro is called by .FC, and has the formal closing as the argument.

.LO is implemented as a general option-macro. It demands that a string named Lettype is defined, where type is the letter type. .LO then assigns the argument to the string let*lo-type.

Files

/usr/local/share/groff/1.23.0/tmac/m.tmac

is the groff implementation of the memorandum macros.

/usr/local/share/groff/1.23.0/tmac/mm.tmac

is wrapper to load m.tmac.

/usr/local/share/groff/1.23.0/tmac/refer-mm.tmac

implements refer(1) support for mm.

/usr/local/share/groff/1.23.0/tmac/mm/ms.cov

implements an ms-like cover sheet.

/usr/local/share/groff/1.23.0/tmac/mm/0.MT

implements memorandum types 0–3 and 6.

/usr/local/share/groff/1.23.0/tmac/mm/4.MT

implements memorandum type 4.

/usr/local/share/groff/1.23.0/tmac/mm/5.MT

implements memorandum type 5.

/usr/local/share/groff/1.23.0/tmac/mm/locale

performs any (further) desired necessary localization; empty by default.

Authors

The GNU version of the mm macro package was written by Jörgen Hägg of Lund, Sweden.

See also

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), troff(1), tbl(1), pic(1), eqn(1), refer(1), groff_mmse(7)