groff_mm(7)

📦
version 1.24.2 · 18 versions
, in alpine 3.24

✨ you're reading groff_mm(7) from the Miscellaneous Information Manual, and honestly? iconic. buckle up bestie 💅

💖 NAME 💖

groff_mm — memorandum macros for GNU roff, and that's the whole vibe 🫶

✨ SYNOPSIS ✨

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

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

🦋 DESCRIPTION 🦋

okay so. the mm macro package ships with the groff document formatting system, and it's literally made for composing letters, memoranda, reports, and books 💖 no cap.

call an mm macro at the beginning of a document to initialize the package. a simple mm document might use only P for paragraphing — that's it, that's the whole setup. 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 within a word with BI, BR, IB, IR, RB, and RI — yes, mid-word glow-ups are a thing ✨. 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. LB begins a list with customizable layout parameters. DS and DF start static and floating displays, respectively; DE terminates either.

groff mm is intended to be compatible with the mm implementation found in the AT&T Documenter's Workbench 3.3 (“DWB”), with the following limitations and changes 👀:

  • omitted features include the logo and company name strings, }Z and ]S, respectively; the encoded company site location addresses recognized as the third argument to the AU macro; the Pv (“private” heading) register; and the OK (other keywords) and PM (proprietary markings) macros.
  • groff mm implements the CS (output cover page or “sheet”) macro only for memorandum type 4.
  • the grap preprocessor is not explicitly supported; groff mm defines no G1 or G2 macros.
  • registers A, C, T, and U, set from the troff or nroff command lines with DWB, are not recognized.
  • when setting the registers L or W from the command line, use an explicit scaling unit to avoid surprises 🙈.
  • the Le register defaults to 1, consistently with Lf, Lt, and Lx in DWB; equations captioned with EC appear in tables of contents produced by TC.
  • the Li register configures the text indentation of RL list items; DWB used a hard-coded value of 6 ens.
  • groff mm uses the same adjustment and font style defaults in nroff and troff modes.
  • cut marks are not supported.

DWB supported only seven heading levels. as a compatible extension, groff mm supports fourteen, introducing new registers H8 through H14, and affecting the interpretation of the HF and HP strings 🔥.

groff mm features a citation (or “bookmark”) system, permitting the document to make (customizable) internal references like “See chapter 5, page 128.”. forward references require two-pass formatting. see the INITR macro description below and mmroff(1).

macro, register, and string descriptions in this page frequently mention each other; most 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 — iykyk 🎀.

except where noted, mm assumes that horizontal measurements are reckoned in ens (scaling unit n) and vertical ones in vees (scaling unit v). groff mm permits use of non-integral typographical points (scaling unit z). use explicit scaling units for clarity and predictable behavior 💯.

🌸 Document styles 🌸

groff mm offers three 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 🫶.

🌈 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/share/groff/1.24.2/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.24.2/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/share/groff/1.24.2/tmac/mm/territory_locale to be loaded at package initialization. if this mechanism is not used, /usr/share/groff/1.24.2/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. the nr request assigns a value to a register.

.nr ident [±]n [i]

ident is the name of the register, and n is the value to be assigned. prefixing n with a plus or minus sign increments or decrements (respectively) its existing value. 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's value automatically changes 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. the brackets around ident are literal ⭐.

many of the registers mm provides are Boolean-valued, meaning that they are considered “true” (on, enabled) when they have a positive value, and “false” (off, disabled) otherwise.

define strings 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. interpolate strings 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. don't do it bestie 😭

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

  • 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, ...

🦋 Fonts 🦋

mm assumes that the font styles R (roman), I (italic), and B (bold) are mounted at font positions 1, 2, and 3, respectively. use the fp request to mount substitute fonts at these positions as desired. the default font family is “T” (Times). to select a different one, invoke groff's fam request or use its -f command-line option 🌸.

🔥 Macros 🔥

double-quote macro arguments that contain space characters. an explicitly empty argument may be specified with an empty pair of double quotes; for example, the following macro call has three arguments.

.XX "foo bar" "" baz

some macros are documented as causing a page break; this does not occur if such a macro is called when the drawing position is already at the top of a page (after a page heading, if any) 💅.

hook macros are undefined by default; mm calls them to enable customization of its behavior. (DWB termed these “exits”.)

macro names longer than two characters are extensions; some shorter names were not part of DWB's published interface but are documented aspects of groff mm ⭐.

  • 1C [1] — format page text in one column (the default layout). the page is broken. a 1 argument suppresses this break; its use may cause body text and a pending footnote to overprint 😭. see 2C, MC, and NCOL.
  • 2C — begin two-column formatting. this is a special case of MC. see 1C and NCOL.
  • AE — abstract end; stop collecting abstract text. see AS.
  • AF [org-name] — specify a memorandum's organizational affiliation. at most one can be declared; org-name is used by MT memoranda and available to cover pages. see COVER.
  • AFX — define this hook macro to assume responsibility for formatting the affiliated firm name defined by AF in memorandum types 0 and 4 and documents using the ms cover page style. if not defined (the default), internally defined macros handle this task; see subsection “Internals” and section “Files” below. applications include setting the firm name in a different font family or at a larger type size, drawing a rule across the page, and including a logo image using groff's PDFPIC or PSPIC macros 🎨. see MT, COVER, and groff_tmac(5).
  • AL [number-format [text-indent [1]]] — begin an auto-incrementing numbered list, where item numbers start at one and are followed by a dot. number-format assigns the register format (see above) mm uses for the list item enumerators. the default is 0. a text-indent argument overrides register Li. a third argument suppresses the vertical space that normally precedes each list item; see register Lsp. vertical space in the amount of Lsp precedes the list itself, but does not accumulate with pre-item space when this list is nested in another. AL calls LB; use LI to declare list items, and LE to end the list.
  • APP [sequence-number [title]] — begin an appendix. if sequence-number is omitted, it increments (or is initialized to 1, if necessary). the register format used for sequence-number 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 sequence-number. 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 sequence-number 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]] 💖

Ok so this is how you start your abstract, bestie — it begins collecting everything you type, and it keeps collecting right up until the next AE call. Everything in between = your abstract, no cap.

The placement arg decides where your abstract lands on the cover page of a memorandum (peep MT for that whole situation). And COVER, by contrast, ignores placement by default — but it can be customized to interpret it. Slay.

  • 0 — the abstract appears on page 1 and the cover page if the doc is a "released paper" memorandum (".MT 4"); otherwise it shows up on page 1 without any cover page.
  • 1 — the abstract appears only on the cover page (and only for ".MT 4").
Heads up babes: an abstract does not appear at all in external letters (".MT 5"). And a placement of 2 was supported by DWB — but groff mm does not support it, so don't come for me. 💀

A second argument (indentation) increases the indentation by indentation and reduces the line length by twice that amount. Default is 0.

AT title ... 🎀

Specifies your author's title(s). If you're using it, AT has to appear just after the corresponding author's AU — like, immediately, no wiggle room.

Each title takes up an output line beneath the author's name in the signature block used by LT letters (see SG) and in MT memoranda. The ms cover page style also formats these data. Cute, right?

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

Specify an author. Big one, iconic, main character energy.

AU terminates a document title started with TL, and you can call it with no arguments at all just for that purpose (it's giving "I'm just here to end things").

Author info gets used by cover pages, MT memoranda, and SG.

The further arguments are, in order:

  • initials
  • location (loc)
  • department (dept)
  • telephone extension (ext)
  • room number or name (room)
  • and up to three additional items (arg1, arg2, arg3)

Repeat AU to identify multiple authors — yes, you can stack them, we love a group project. 🫶

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

AV [name [1]] ✨

Formats approval lines for a handwritten signature and date. Two horizontal rules get drawn, with the specified name and the text of the string Letdate respectively, sitting beneath them.

Above these rules, mm formats the text in the string Letapp. A second argument replaces this text with one vee of vertical space. See LT.

AVL [name] 🦋

Same as AV, but it skips the approval notation (the Letapp string), the date rule, and the label below the date rule (the Letdate string). Basically AV on a diet. 💅

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

Joins bold-text in boldface with previous-font-text in the previous font, with no space between the arguments. Sneaky little font switch.

No arguments? It just switches the font to bold style. Periodt.

B1 🎁

Begin a boxed static display. The text is indented by 1n, and the line length is reduced by 2n. See DS.

This is a groff mm extension, iykyk.

B2 🎁

End the boxed static display. See B1. (Also a groff mm extension. Also the natural other half of B1, obviously.)

BE 🧚

Ends the bottom block — see BS for where it all begins.

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

Joins bold-text in boldface with italic-text in italics, with no space between the arguments. Bold-italic besties fr fr.

BL [text-indent [1]] 🍓

Begin a bulleted list. mm marks each item with the string BU. 🎯

  • A text-indent argument overrides register Pi.
  • A second argument suppresses the vertical space that normally precedes each list item — see register Lsp.
  • Vertical space in the amount of Lsp precedes the list itself, but it does not accumulate with pre-item space when this list is nested inside another. (Nested lists stay chill.)

BL calls LB. Use LI to declare list items, and LE to end the list. ✨

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

Joins bold-text in boldface with roman-text in roman style, with no space between the arguments. The classic glow-up combo.

BS 🧵

Begin the bottom block. mm collects input into the bottom block until the document calls BE, then outputs it between the footnote area and the footer of each page. Sneaky real estate, honestly.

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

Begin a broken variable-item (or "tagged") list. Each item supplies its own mark. The line is always broken after the mark — contrast that with VL, which does not do this.

  • A text-indent argument overrides register Pi.
  • mark-indent sets the distance from the indentation of the current list to the mark.
  • A third argument suppresses the vertical space that normally precedes each list item — see register Lsp.
  • Vertical space in the amount of Lsp precedes the list itself, but does not accumulate with pre-item space when this list is nested in another.

BVL calls LB. Use LI to declare list items, and LE to end the list. 🫶

COVER [style] 💐

Begin a cover page description. This has to appear before the body text (or main matter) of your document — no last-minute cover pages, babes.

The style argument is used to construct the file name /usr/share/groff/1.24.2/tmac/mm/style.cov and loads it with the mso request.

The default style is "ms" — and the ms.cov file prepares a cover page resembling that of the ms package, iconic behavior honestly.

A .cov file must define a COVEND macro, which your document must call at the end of the cover description. Non-negotiable.

Use the cover description macros in the following order — only TL and AU are required:

.COVER
.AF
.TL
.AU
.AT
.\" Add additional AU and AT calls as needed.
.AS
.AE
.COVEND

COVEND 🎬

Ends the cover description. That's it, that's the whole macro, and honestly good for her.

DE 🛑

Ends a static or floating display begun with DS or DF. Closing time, you don't gotta go home but you gotta get out of this display.

DF [format [fill [right-indentation]]] 🦄

Begin a floating display. A floating display gets saved in a queue and output in the order entered. Arguments are handled exactly as in DS.

Floating displays cannot be nested. Just so we're clear. 🙈

Placement of floating displays is controlled by the registers De and Df.

DL [text-indent [1]] ⭐

Begin a dashed list. mm marks each item with the string EM.

  • A text-indent argument overrides register Pi.
  • A second argument suppresses the vertical space that normally precedes each list item — see register Lsp.
  • Vertical space in the amount of Lsp precedes the list itself, but does not accumulate with pre-item space when this list is nested in another.

DL calls LB; use LI to declare list items, and LE to end the list. 💖

DS [format [fill [right-indentation]]] 💅

Begin a static display. mm collects input into a display until the document calls DE. The display is output on a single page unless it's taller than the height of the page (in which case, it's out of your hands).

DS can be nested — contrast with DF, which absolutely cannot. Noted.

The format argument:

  • 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-align each line.
  • RB — right-align the whole display as a block.

The values "L", "I", "C", and "CB" can also be specified as "0", "1", "2", and "3", respectively, for compatibility with DWB. (Yes, the old numbers still work. Vintage.)

The fill argument:

  • none — disable filling.
  • N — disable filling.
  • F — enable filling.

"N" and "F" can also be specified as "0" and "1", respectively, for compatibility with DWB. Same vintage deal.

A third argument, right-indentation, reduces the line length by that amount.

mm normally places vertical space before and after the display. Set register Ds to "0" to suppress it. ✂️

EC [title [override [flag [ref-name]]]] 🧮

Captions an equation. The caption is made of the string Capec, followed by an automatically incrementing counter stored in the register Ec, then punctuation configured by the register Of, then title (if there is one).

Use the af request to configure Ec's number format. Fancy.

override and flag alter the equation number like this — and, note, omitting flag and specifying 0 in its place are equivalent:

  • 0 — prefix the number with override.
  • 1 — suffix the number with override.
  • 2 — replace the number with override.

mm centers equation captions no matter how any enclosing display is aligned. It simply will not be told otherwise.

Specifying ref-name stores the equation number as if by ".SETR ref-name \n[Ec]".

Recognition of this argument is a groff mm extension.

The package lists captioned equations in a table of contents (see TC) if the Boolean register Le is true. The string Le captions this list. 📚

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

Defines the even-page footer, which gets formatted just above the normal page footer on even-numbered pages. See PF.

EF defines the string EOPef. Don't forget that part.

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

Defines the even-page header, which gets formatted just below the normal page header on even-numbered pages. See PH.

EH defines the string TPeh. Matching set with EF, we love a symmetry moment. ✨

EN 🧊

Ends mathematical expression input preprocessed by eqn(1) — see EQ. The other bookend, bestie.

EOP 🚪

This is a hook macro that groff mm calls in lieu of the normal page footer layout. The package uses a separate environment to format headers and footers. See TP.

Strings available to EOP:

  • EOPf — the argument to PF
  • EOPef — the argument to EF
  • EOPof — the argument to OF

Three strings, all yours, go wild. 💜

EPIC [-L] width height [name] 🖼️

Draws a box with the given width and height. The text name (or the default text) is formatted inside the box — and no attempt is made to size the box to fit the text. It's a box, not a tailor.

An application of this macro is to indicate the placement of an image to be determined later, or externally composited in postprocessing. It's giving "reserved seating." 🪑

-L as the first argument left-aligns the box; the default is to center it. See PIC.

EQ [label] 📐

Starts mathematical expression input preprocessed by eqn(1). EQ and EN macro calls bracket an equation region together, like the two halves of a friendship bracelet.

Such regions must be contained in displays (DS/DE), except when the region is used only to configure eqn and not to produce output. Read that twice, honestly.

If present, label appears 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. Sorry to the earlier labels, they simply don't make the cut. 💀

  • EX [title [override [flag [ref-name]]]] — gives your exhibit a caption, bestie. The arguments work exactly like EC's do. The register Ex is the exhibit counter. The string Capex sits in front of the exhibit number and any title you gave. And mm centers exhibit captions no matter how the enclosing display is aligned — it does not care, it's centering. ✨

Also: the package lists captioned exhibits in a table of contents (see TC) if the Boolean register Lx is true. The string Lx is what captions that list.

  • FC [closing-text] — spits out the string Letfc, or whatever closing-text you handed it, as the formal closing of a letter or memorandum. See LT and MT. 💌
  • FD [arg [1]] — configures how footnotes get displayed. The first argument is a little encoded bundle of four things: whether automatic hyphenation is on, whether text is adjusted to both margins, whether footnote text is indented, and whether the footnote label is left- or right-aligned inside the space set aside for it. 🎀

Here's the whole decoder ring, every single value:

  • 0 — hyphenate? no · adjust? yes · indent? yes · label alignment: left
  • 1 — hyphenate? yes · adjust? yes · indent? yes · label alignment: left
  • 2 — hyphenate? no · adjust? no · indent? yes · label alignment: left
  • 3 — hyphenate? yes · adjust? no · indent? yes · label alignment: left
  • 4 — hyphenate? no · adjust? yes · indent? no · label alignment: left
  • 5 — hyphenate? yes · adjust? yes · indent? no · label alignment: left
  • 6 — hyphenate? no · adjust? no · indent? no · label alignment: left
  • 7 — hyphenate? yes · adjust? no · indent? no · label alignment: left
  • 8 — hyphenate? no · adjust? yes · indent? yes · label alignment: right
  • 9 — hyphenate? yes · adjust? yes · indent? yes · label alignment: right
  • 10 — hyphenate? no · adjust? no · indent? yes · label alignment: right
  • 11 — hyphenate? yes · adjust? no · indent? yes · label alignment: right
An arg greater than 11 is treated as 0. mm's default is 0. No cap, it just rounds you back to zero, iykyk. 💀

A second argument resets footnote numbering when a first-level heading is encountered. See FS.

  • FE — ends the footnote. See FS. Short and sweet, we love a closer. 🫶
  • FG [title [override [flag [ref-name]]]] — captions a figure. Arguments handled analogously to EC, same deal. The register Fg is the figure counter. The string Capfg comes before the figure number and any title. mm centers figure captions irrespective of the alignment of any enclosing display — centering is its whole personality. 🌸

The package lists captioned figures in a table of contents (see TC) if the Boolean register Lf is true. The string Lf captions this list.

  • FS [mark] — starts a footnote. mm collects all your input into a footnote until the document calls FE, then outputs it when the vertical drawing position gets near the page bottom. 🦋

By default mm automatically numbers footnotes starting at 1. That number lives in register Ftnum and, with a trailing period, in string F. If you want, interpolate this string in the body text to format the footnote mark. mm interpolates string F prior to the footnote text. Footnotes are vertically separated by the product of registers Fs and Lsp. And in groff mm, footnotes may be used in displays — yes, even in there. ✨

A mark argument, which does not have to be numeric, replaces the default footnote mark and leaves the string F unchanged. In that event, you must explicitly write any footnote mark you want to appear in the footnote itself. Nobody's doing it for you, bestie. 😭

  • GETHN ref-name [string] — interpolates ref-name's heading mark, or, if string is specified, stores it there. In neither case does GETHN suffix the interpolation with space. See INITR. 💅
  • GETPN ref-name [string] — interpolates ref-name's page number, or, if string is specified, stores it there. In neither case does GETPN suffix the interpolation with space. See INITR.
  • GETR ref-name — retrieves the location data for reference ref-name, calls GETHN and GETPN to populate strings Qrfh and Qrfn respectively, and interpolates string Qrf as an internal reference to it. See INITR. 🔥
  • GETST ref-name [string] — interpolates ref-name's auxiliary reference datum, or, if string is specified, stores it there. In neither case does GETST suffix the interpolation with space. See INITR.
  • H level [title [suffix]] — sets a numbered section heading at level. mm calls LC to clear any lists, then produces numbered heading marks shaped like a.b.c..., with up to fourteen levels of nesting. Each level's number increments automatically with every H call and resets to zero whenever a more significant level is specified. 1 is the most significant — the coarsest division of your document, the main character. 👑

Text after an H call is formatted as a paragraph, so calling P is unnecessary. Save yourself the keystroke, bestie.

The optional title must be double-quoted if it contains spaces. mm appends suffix to title in the body of the document but omits it from any table of contents (see TC). This is how you annotate a heading title with a footnote. suffix should not interpolate the F string — specify a footnote mark explicitly. See FS. 🙈

Heading behavior is configurable. Several registers set thresholds, where heading levels at or below a threshold value get handled one way and those above it get handled another. For example, mm populates a table of contents (see TC) with the title of a heading if its level falls within the Cl register threshold.

💖 Heading layout

Register Ej sets a threshold for page breaking (ejection) prior to a heading. If there's no page break before it, a heading level within 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 at which a break occurs after the heading, and register Hs sets a threshold within which vertical space follows it. If the heading level is above both of those, and the paragraph isn't numbered, mm produces a run-in heading — the paragraph text just follows on the same output line. Otherwise, register Hi configures the indentation of text after headings. Threshold register Hc permits centering; mm centers a heading with a level within both the Hb and Hc thresholds. It's giving very layered. ✨

🎀 Heading typeface and size

The HF string configures the fonts used for heading marks and titles at each level. The string HP likewise assigns a type size to each heading level. The hook macros HX and/or HZ can control the vertical spacing used by headings.

💅 Heading number format

Registers named H1 through H14 store counters for each heading level. Their values print as Arabic numerals by default; see HM. The heading levels are catenated with dots for formatting; to typeset only the deepest one, set the Ht register. Heading numbers are not suffixed with a trailing dot except when only the first level is output — and to omit the dot in that case too, clear the H1dot register. Periodt. 🔥

🌈 Customizing heading behavior

H calls the HX, HY, and HZ hook macros to further customize headings. These can change the heading's mark (that's 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 on the page, breaking the page otherwise. 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-suffix is the catenation of the corresponding arguments to H or HU.

  • HX declared-level actual-level title-suffix — 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 the heading is to be run in, 1 means a break is to occur before the text, and 2 means 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 isn't available, the page is broken prior to the heading. The default is 2v.
  • HY declared-level actual-level title-suffix — mm calls HY after determining the heading typeface and size. Could be used to change indentation. 💜
  • HZ declared-level actual-level title-suffix — mm calls HZ after formatting the heading, just before H or HU returns. Could be used to change the page header to include a section heading. ⭐
  • HC [hyphenation-character] — sets the hyphenation character, selecting the default, \%, if called without an argument. 🌸
  • HM [arg1 [arg2 [... [arg14]]]] — sets 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 title [suffix] — sets an unnumbered section heading with title and, as a groff mm extension, an optional suffix. The heading is treated as a numbered heading of the level stored in register Hu, but no heading mark is output. See H. 💫
  • I [italic-text [previous-font-text]] ... — joins italic-text in italics with previous-font-text in the previous font, with no space between the arguments. If you pass no arguments at all, it switches the font to italic style. Slay. 💅

IA [recipient-name [title]] 💌

okay so this is the letter one — it sets the inside address. each argument gives a recipient a recipient-name and title. mm just collects input into the inside address until the document calls IE, and then it outputs the whole thing. you can totally specify multiple recipients with empty IA/IE pairs, but heads up: mm uses only the last address. see LT.

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

joins italic-text in italics with bold-text in boldface, with no space between the arguments. cute, iconic, does exactly one thing 💅

IE

ends the inside address that IA started. that's the whole macro, bestie — no arguments, no notes.

IND argument ...

if the Boolean register Ref is true, this writes an index entry as a specially prepared roff comment to the standard error stream, with each argument separated from its predecessor by a tab character. the entry's location info is arranged exactly how you set it up with the most recent INITI call. ✨

INDP

outputs the index that INITI set up and IND calls populated. by default, INDP calls SK and writes a centered caption interpolating the string Index. then it disables filling and calls 2C; afterward, it restores filling and calls 1C. 🌀

want to customize any of that? define macros, because INDP calls TXIND before the caption, TYIND instead of writing the caption, and TZIND after formatting the index. very demure, very modular.

INITI location-type file-name [macro]

kicks off groff mm's indexing system. location-type selects how the location of each index entry gets reported, and file-name populates an internal string that INDP uses later. 👑

location-type → what the entry looks like:

  • N — page number
  • H — heading mark
  • B — page number, tab character, heading mark

if macro is specified, groff mm calls it for each index entry with the arguments you gave to IND.

INITR file-name-prefix

initializes the internal reference macros. internal references get written to the standard error stream, which you should redirect into a file named file-name-prefix.qrf. mmroff(1) handles this plus the two formatting passes it requires: the first pass identifies internal references, the second includes them. see SETR, GETHN, GETPN, and GETST.

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

joins italic-text in italics with roman-text in roman style, with no space between the arguments. yes, IR is the roman sibling of IB — matching set, slay ✨

LB text-indent mark-indent pad type [mark-or-format [pre-item-space [pre-list-space]]]

begin list. lowkey, the macros AL, BL, BVL, DL, ML, RL, and VL all call LB in various ways — they're simpler to use and may be preferred if they suit what you're trying to do.

mm tracks the nesting level of lists, and the outermost one is 0. it indents each list item (the text formatted after an LI call) by text-indent. the mark is left-aligned at mark-indent, and padded on the left with pad ens of space. type decides the mark's format:

  • 0 → x
  • 1 → x.
  • 2 → x)
  • 3 → (x)
  • 4 → [x]
  • 5 → <x>
  • 6 → {x}

if type is 0, mark-or-format specifies each item's mark (which an argument to LI can override, fyi). if mark-or-format is empty (or the dummy character \&), mm sets items at mark-indent with a hanging indent at text-indent.

if type is greater than zero, mm supplies an automatically incrementing numeric mark, and interprets mark-or-format as a register format.

a type of -1 causes groff mm to break the line after the mark even if it fits within text-indent — that's a groff mm extension, no cap 🧚

the last two arguments manage vertical space. unless a list's nesting level is greater than the value of register Ls, its items are preceded by pre-item-space multiplied by the register Lsp; the default is 1. LB precedes the list by pre-list-space multiplied by the register Lsp; the default is 0.

LC [list-level]

clears list state. active lists are terminated as if with LE — either all of them (that's the default) or only those from the current level down to list-level if you pass it. main character energy: it ends the whole group chat or just the sub-thread.

LE [1]

end list. the current list is terminated. an argument of 1 causes vertical space in the amount of register Lsp to follow the list. 🌸

LI [mark [pad-prefix]]

begin a list item. mm collects input into a list item until the document terminates the current list or calls LI again. by default, the item's text is preceded by any mark configured by the current list. if mark is the only argument, it replaces the mark configured in the corresponding LB call.

if the width of the mark plus any pad specified in the LB call exceeds the text indentation, groff mm warns and uses one en of padding between the mark and the text. (it's giving "we tried" 💀)

the presence of a second argument prefixes mark to the LB-configured mark and, as a groff mm extension, conditionally puts an unbreakable space between the prefix and mark per the argument's Boolean value.

LO option [value]

specify letter options; see LT. by default, mm recognizes the following option values. (see IA regarding the inside address, and string DT regarding the date.)

  • AT — Attention; put the contents of string LetAT and value left-aligned after the inside address.
  • CN — Confidential; put value, or the contents of string LetCN, left-aligned after the date.
  • RN — Reference; put the contents of string LetRN and value after the confidential notation (if any) and the date, aligned with the latter.
  • SA — Salutation; put value, or the contents of string LetSA, left-aligned after the inside address and the confidential notation (if any).
  • SJ — Subject; put the 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.

LT [style]

formats a letter in the designated style, defaulting to BL (see below). a letter begins with the writer's address (WA/WE), followed by the date (ND), the inside address (IA/IE), the body of the letter (P and other general-purpose mm macros), the formal closing (FC), the signature (SG), and the notations (NS/NE). any of these except the body text may be omitted. letter options specified with LO add further annotations, and those are extensible — see subsection "Internals" below. 🎀

  • 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 \n[Pi] ens.
  • FB — Fully blocked: everything is left-aligned.
  • SP — Simplified: as FB, but a formal closing is omitted, and the signature is set in full capitals.

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, and it defaults to column-width/15. NCOL moves to the next column, and 1C returns to single-column layout. MC is a groff mm extension that generalizes 2C. see MULB for an alternative. 🌈

ML mark [text-indent [1]]

start a marked list; the mark argument precedes each item. text-indent overrides the default indentation of the list items, which is the width of mark plus one en. a third argument suppresses the vertical space that normally precedes each list item; see register Lsp. vertical space in the amount of Lsp precedes the list itself, but it does not accumulate with pre-item space when this list is nested in another. ML calls LB; use LI to declare list items, and LE to end the list. 💖

MT [type [addressee]]

select the memorandum type. these correspond to formats used by AT&T Bell Laboratories, where the mm package was initially developed, and they affect 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/share/groff/1.24.2/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. omitting type implies 1. addressee sets a string analogous to one used by AT&T cover page macros that are not implemented in groff mm.

  • 0 — normal memorandum; no caption
  • 1 — captioned "TECHNICAL MEMORANDUM"
  • 2 — captioned "INTERNAL MEMORANDUM"
  • 3 — captioned "ADMINISTRATIVE MEMORANDUM"
  • 4 — released paper
  • 5 — external letter
  • string — captioned string

see COVER for a more flexible cover page mechanism. 🦋

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

move to a position, setting the page offset to x-pos. if line-length isn't given, the difference between the current and the new page offset is used. use PGFORM without arguments to return to normal. it's a little relocation moment, no biggie ✨

MULB cw1 sp1 [cw2 sp2] ... cwn

begin alternative multi-column mode. all the column widths cwi must be specified, and so must the amount of space spi between each column pair. MULB uses a diversion and operates in a separate environment. 👑

MULE

end alternative multi-column mode and emit the columns. short king of a macro.

MULN

start the next column in alternative column mode.

NCOL

start the next column (only when you're using 2C or MC). contrast with MULN — they're cousins, not twins, iykyk.

ND [arg]

set the document's date. mm does not interpret arg; it can be a revision identifier (or empty). mm calls ND itself when initializing. 🗓️

NE

end the notation begun with NS; filling is enabled. that's it, bestie 💜

nP [type]

Okay so this is P's dramatic sibling 💅 — it begins a new paragraph and drops a paragraph number on it in the form x.yy, where x is the number of the second heading level and yy just keeps incrementing every time you call nP. Important detail bestie: that yy does not reset when the second-level heading number changes. mm formats yy using a register format of 00. ✨

NS [code [1]]

Declare notations, bb — typically for letters or memoranda — of the type given by code. The text that corresponds to code gets output, and filling is disabled until the document calls NE. Usually you've got a list of names or attachments sitting inside that NS/NE sandwich. 🥪

If code is missing, or doesn't match any of the values listed under the Letns string description further down, every line of notations gets formatted as Copy (line) to.

If you pass a second argument — conventionally 1 — then code becomes the entire notation and you don't need NE at all. And in groff mm you can totally set up more notations for NS to recognize; peep the Letns and Letnsdef strings below. 👀

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

Define the odd-page footer, which gets 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, formatted just below the normal page header on odd-numbered pages. See PH. OH defines the string TPoh. 🌸

OP

Make sure whatever text comes next is formatted at the top of an odd-numbered page. And no, it won't page-break if the drawing position is already sitting there — very "if you're already here, stay here" of it. 😌

P [type]

Begin a new paragraph, bestie. If type is missing or 0, P sets the paragraph fully left-aligned. A type of 1 indents the first line by \[Pi] ens.

Set the register Pt to pick a default paragraph indentation style. The register Ps decides how much vertical space sits between paragraphs.

Want a hanging indent? Use VL with your desired indentation as the argument, then LI (no argument!), then LE. That's the combo. 🫶

PE

End picture input that was preprocessed by pic(1). See PS. 🎀

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

Define the page footer, formatted at the bottom of every page. Everything else about the argument works exactly like PH describes. PF defines the string EOPf. See EF, OF, and EOP. 💜

PGFORM [line-length [page-length [page-offset [1]]]]

Set the line length, page length, and/or page offset — iconic for letterheads and that whole vibe. It's normally the very first macro call in a file, though honestly it doesn't have to be.

You can call PGFORM with zero arguments to reset everything after a MOVE call. A line break happens unless you give that fourth argument — which is exactly how you dodge the page number on page one while still setting your new width and length. Chef's kiss. 👑

Real talk though: it seems like this macro sometimes doesn't work too well 😭. Use the command-line arguments to change line length, page length, and page offset instead.

PGNH

Suppress the header on the next page. Want no header on the first page? Call this macro before you format any text in the document. Also see register N. 🙈

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

Define the page header, formatted at the top of every page. The argument holds left, center, and right, aligned to their respective spots on the line. A % character anywhere in the argument gets replaced by the 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 up in the upper left or right corners. Header macros call PX (if it's defined) after formatting the header. PH defines the string TPh. See EH, OH, and TP. ⭐

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

Include a PostScript document file.

  • -B — draw a box around the picture. 🖼️
  • -L, -C, -R, -I n — align the picture, or indent it by n.

By default the picture is left-aligned. The optional width and height arguments resize it. Heads up: this macro needs two-pass processing — see INITR and mmroff(1). 🌀

PS

Start picture input that's been preprocessed by pic(1). 💫

PY

Exactly like PE, but with "flyback" — it returns the drawing position to wherever it was before the picture. This is a groff mm extension. 🧚

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

Join roman-text in roman style with previous-font-text in the previous font, with no space between the arguments. Give it no arguments at all and it just switches the font to roman style. Simple, clean, slays. 💅

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

Join roman-text in roman style with bold-text in boldface. No space between the arguments, obviously. ✨

RD [prompt [div [str]]]

If you give a prompt, it writes it — plus a tab and a colon : — to the standard error stream, then reads a response from the standard input stream, optionally into a diversion div and/or a string str. 🎤

To interpolate that saved text, just call its name like a macro. And if a string name is present, the input is also stored in a string of that name. Double duty.

RF

End a bibliographic reference citation that you started with RS. See RP. 📚

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

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

RL [text-indent [1]]

Begin an auto-incrementing numbered list, where item numbers start at one and get set between square brackets — like [1], [2], you get it. 🔢

A text-indent argument overrides the register Li. A second argument suppresses the vertical space that normally precedes each list item — see register Lsp. Vertical space in the amount of Lsp precedes the list itself, but it does not accumulate with the pre-item space when this list is nested inside another one. Nested-list girlies know. 🪆

RL calls LB; use LI to declare list items and LE to end the list.

"RL" is a mnemonic for "reference list", but bestie — this macro has no relationship with mm's bibliographic reference list facilities. Do not confuse them, I'm begging 😭.

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

Format the reference list, listing all the items you accumulated inside RS/RF pairs. 📖

The reference counter gets reset unless the first argument is 1. Normally there are page breaks before and after the references get output — the register Rpej configures that behavior, and a second argument overrides its value. TC calls RP automatically if references have accumulated, so it lowkey handles itself.

groff mm calls LB to format the reference list, and the Rpfmt string configures what the list looks like. Set register Ls to 0 to suppress spacing after the list. The string Rp holds the reference list caption. 💜

RPX

This is a hook macro — it assumes responsibility for formatting the heading of the reference page that RP produces. If it's not defined (which is the default), mm sets the reference list caption in the string Rp, after two vees of space, centered in italics, followed by another vee of space. 🎀

RS [reference-string]

Begin a citation of an automatically numbered bibliographic reference entry. mm collects your input into a reference entry until the document calls RF, and then a later RP call emits everything you've accumulated. 📝

References are numbered starting at 1; the register :R stores the most recently assigned number. Interpolate the string Rf wherever the reference mark should go, then place the entry between the RS and RF calls on text lines after the reference mark. The Rfstyle register determines whether that mark is bracketed, superscripted, or both. ✨

If reference-string is given, mm also stores the reference mark in a string of that name.

S [type-size [vertical-spacing]]

Set the type size and vertical spacing. Each argument is a groff measurement — use an appropriate scaling unit, and an optional + or - prefix to increment or decrement the current value. 🔍

  • P — restores the previous value.
  • C — retains the current value.
  • D — requests the default.

And mm treats an empty or omitted argument as P. So yes, you can be lazy about it. 😌

SA [mode]

Set or restore the default enablement of adjustment. Pass 0 or 1 as mode to set a document's default explicitly — groff mm assumes 1. Invoke the na request whenever you want to temporarily suspend adjustment. H and HU, and SA when called with no mode argument, all restore the default adjustment. ⚖️

SETR ref-name [string]

Create a reference called ref-name, storing its heading and page numbers. If string is present, groff mm saves it as an auxiliary datum you can retrieve later with GETST. See INITR. 🗂️

SG [arg [1]]

Output author signature block(s) in LT letters and MT memoranda. The format of the signature block depends on the letter or memorandum type. See subsection "Internals" below. ✍️

LT letters emit a signature for one author at most (see WA). The author's title, if there is one, gets set on the next line, indented so it lines up with the name — except in letter type SP, where it's set in full capitals (just like the name) after a comma and space.

Memorandum type 4 uses no signature block at all. In other memoranda, each of an author's titles gets set on a subsequent line, indented to line up with the name. They also encode a secretarial annotation — including the location, department, and initials specified in each author's AU call — followed by any arg, and write it at the left margin preceding the last author's name… or preceding the first one if a second SG argument is present. 😮‍💨 (Yes, that's a whole lot. Read it twice, bestie.)

SK [n]

Skip n pages. 🦘

  • If n is 0 or omitted, mm breaks the page if necessary.
  • Otherwise, mm prints n pages — blank except for any headers and footers.

SM text [post] and SM pre text post

Format text at a smaller type size, joined with any specified pre and post at normal size, with no space between the arguments. 🐜

SM text [post]
SM pre text post

SP [distance]

Space downward by distance. Fun fact: multiple SP calls in a row only produce the largest of the distances you specified — no stacking. 📏

SP does accept boundary-relative motions specified with a prefixed | operator… but not negative ones. 🙅‍♀️

ok so real talk bestie: SP is that friend who refuses to show up if they're not the main character 😭 it has no effect when the drawing position is at the top of the page. The fix is iconic and simple — put the dummy character escape sequence \& on a text line prior to calling SP (add \c after it if you want to prevent a break, no pressure) and the restriction is literally gone. periodt.

  • TAB — resets the tab stops to every 5 ens. The ta request is what customizes them, iykyk.
  • TB [title [override [flag [ref-name]]]] — captions a table. The arguments are handled analogously to EC. The register Tb is the table counter, and the string Captb goes before the table number and any title. mm centers table captions no matter what the alignment of any enclosing display is doing — queen behavior.

The package lists captioned tables in a table of contents (see TC) if the Boolean register Lt is true. The string Lt captions this list.

  • TC [slevel [spacing [tlevel [tab [h1 [h2 [h3 [h4 [h5]]]]]]]]] — outputs the table of contents. This macro is normally the last one called in the document, the grand finale 💅 it flushes any pending displays and, if any references are pending (see RS), it calls RP. Then it begins a new page with the contents caption — that's stored in the string Captc — 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, mm indents an entry by an amount corresponding to its heading level and the maximum heading length encountered at that heading level; if it's defined, the string Ci overrides those 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 gets 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 the document calls TC with at most four arguments, mm calls the hook macro TX prior to formatting the contents caption, and TY (if defined) instead of formatting the contents caption.

Then mm presents lists of figures, tables, equations, and exhibits — in that exact order, no cutting the line. A list only shows up if at least one such captioned item is present and if its corresponding register (Le, Lf, Lt, or Lx) is set. The TXxx and TYxx macros, where xx is “FG”, “TB”, “EC”, or “EX”, and the strings Capfg, Captb, Capec, and Capex analogously configure the output of each captioned list. so many little levers, obsessed.

  • TE — ends a tbl(1) table. See TS for the whole story.
  • TH — marks the end of a TS/TE table heading. When a table spans multiple pages, the heading repeats at the top of each page (slay, consistency ✨). Heads up though: groff mm does not implement the N argument supported by DWB.
  • TL [charging-case-number [filing-case-number]] — begins the document title. mm collects input into the title until a subsequent AU call and formats it as directed by the MT memorandum type or cover page macros. mm saves charging-case-number and filing-case-number for use in all memorandum types except 4.
  • TM number ... — declares technical memorandum number(s) used with MT memoranda.
  • TP — mm calls this hook macro in lieu of the normal page header layout. The package uses a separate environment to format headers and footers. See EOP.

Strings available to TP:

  • TPh — argument to PH
  • TPeh — argument to EH
  • TPoh — argument to OH
  • TS [H] — starts a tbl(1) table. The argument “H” tells mm that the table's heading should repeat after page breaks. See TE, TH, and tbl(1).
  • VERBON [format [type-size [font]]] — begins a display of verbatim content. format controls several parameters — add up the values of the features you want, and the default is 0. Further arguments configure the type-size in typographical points (on typesetting devices) and the face (font). On typesetting devices, the default face is CR (Courier roman), a monospaced font, meaning all glyphs are equally wide. democracy 💖
    • 1 — disable the formatter's escape character (\)
    • 2 — vertically space before the display
    • 4 — vertically space after the display
    • 8 — number output lines; call the formatter's nm request with arguments in string Verbnm
    • 16 — indent by the amount stored in register Verbin
  • VERBOFF — ends the verbatim display. bye bestie 👋
  • VL [text-indent [mark-indent [1]]] — begins a variable-item (or “tagged”) list. Each item should supply its own mark, or tag. A text-indent argument overrides register Pi; mark-indent sets the distance from the indentation of the current list to the mark. A third argument suppresses the vertical space that normally precedes each list item — see register Lsp. Vertical space in the amount of Lsp precedes the list itself, but it does not accumulate with pre-item space when this list is nested in another (no double-spacing jumpscare 🙈). RL calls LB; use LI to declare list items, and LE to end the list.
  • VM [-T] [top [bottom]] — configures vertical margins.

Without a -T argument, it increments the top and bottom margins by top and bottom, respectively. If absent, it sets the corresponding margin to zero.

With the -T argument, it sets the top and bottom margins to top and bottom, respectively. If absent, it sets the respective margin to the default (top: 7v, bottom: 6v).

We recommend defining the hook macros TP and/or EOP if you're using -T and setting the top and/or bottom margin to values less than the default. groff mm exposes this undocumented DWB macro to enable greater user control of page layout. you're welcome, go wild 🦋
  • WA [writer's-name [title]] — specifies the writer(s) of an LT letter. mm collects input into the writer's address until the document calls WE, then it outputs it. You can specify multiple writers with empty WA/WE pairs; only the last address is used though, just so you know 👀. The arguments give each writer a name and title.
  • WC [format ...] — controls the width of footnotes and displays.
    • N — equivalent to -WF -FF -WD (the default)
    • WF — set footnotes at full line length, even in two-column mode
    • -WF — set footnotes using column line length
    • FF — apply the width of the first footnote 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
  • WE — ends the writer's address begun with WA. closing the loop, love that for us 🎀

✨ STRINGS ✨

Okay bestie, so like — a ton of mm strings interpolate predefined, localizable text. We're presenting their contents in quotation marks, because that's just how we do. 💅

  • Abstract — “ABSTRACT”
  • App — “APPENDIX”
  • Apptxt — stores the title argument to the most recent APP call.
  • Aumt — lists space-separated indices of positional arguments to the AU macro that should be suppressed from appearance in the document heading on the first page of MT memorandum types 0–3 and 6. By default, it is undefined; all arguments are formatted except the second (author initials).
  • BU — interpolates a bullet mark, \[bu].
  • Capec — “Equation”
  • Capex — “Exhibit”
  • Capfg — “Figure”
  • Captb — “Table”
  • Captc — “CONTENTS”
  • Ci — assigns indentation amounts used by each heading level listed in a table of contents, in one-to-one correspondence, overriding those computed by TC. Each word must be a horizontal measurement (like “1i”).
  • DT — stores the date or other identifier set by ND, if called, and otherwise one constructed using the formatter's date registers; see groff(1). The groff locale determines its format, but register Isodate may override it.
  • EM — interpolates an em dash, \[em].
  • F — interpolates an automatically numbered footnote mark; the number is used by the next FS call without an argument. In troff mode, the mark is superscripted; in nroff mode, it is surrounded by square brackets.
  • H1txt — stores the text of the current first-level heading; H and HU update it, as does TC when processing table of contents entries and captions of displayed figures, tables, equations, and exhibits.
  • HF — assigns font identifiers, separated by spaces, to heading levels in one-to-one correspondence. Each identifier may be a font mounting position, font name, or style name. Omitted values are assumed to be 1. The default is “2 2 2 2 2 2 2 2 2 2 2 2 2 2”, which places all headings in italics. DWB's default was “3 3 2 2 2 2 2”.
  • HP — assigns type sizes, separated by spaces, to heading levels in one-to-one correspondence. groff mm interprets each size in typographical points, translating zero values to 10. Omitted values are assumed to be 0 (and are translated accordingly). The default is “0 0 0 0 0 0 0 0 0 0 0 0 0 0”.
  • Index — “INDEX”
  • Le — “LIST OF EQUATIONS”
  • Letfc — “Yours very truly,” (see FC)
  • Letapp — “APPROVED:” (see AV)
  • LetAT — “ATTENTION:” (see LO)
  • LetCN — “CONFIDENTIAL” (see LO)
  • Letdate — “Date” (see AV)

Letns is a whole group of strings structuring the notations produced by NS. If the code argument to NS has no corresponding string, the notation is included between parentheses, prefixed with Letns!copy, and suffixed with Letns!to. Observe the spaces after “Copy” and before “to” — like, they're load-bearing, don't touch them. 🫶

  • Letns!0 (NS code 0) — Copy to
  • Letns!1 (NS code 1) — Copy (with att.) to
  • Letns!2 (NS code 2) — Copy (without att.) to
  • Letns!3 (NS code 3) — Att.
  • Letns!4 (NS code 4) — Atts.
  • Letns!5 (NS code 5) — Enc.
  • Letns!6 (NS code 6) — Encs.
  • Letns!7 (NS code 7) — Under separate cover
  • Letns!8 (NS code 8) — Letter to
  • Letns!9 (NS code 9) — Memorandum to
  • Letns!10 (NS code 10) — Copy (with atts.) to
  • Letns!11 (NS code 11) — Copy (without atts.) to
  • Letns!12 (NS code 12) — Abstract Only to
  • Letns!13 (NS code 13) — Complete Memorandum to
  • Letns!14 (NS code 14) — CC
  • Letns!copy (no code) — Copy (with trailing space, yes trailing, it matters)
  • Letns!to (no code) — to (note leading space, also matters, we love a subtle space moment)
  • Letnsdef — selects the notation format when NS is given no argument. The default is 0.
  • LetRN — “In reference to:” (see LO)
  • LetSA — “To Whom It May Concern:” (see LO)
  • LetSJ — “SUBJECT:” (see LO)
  • Lf — “LIST OF FIGURES”
  • Lt — “LIST OF TABLES”
  • Lx — “LIST OF EXHIBITS”
  • MO1 … MO12 — “January” through “December”
  • Qrf — “See chapter \E*[Qrfh], page \En[Qrfp].” If your document uses multiple heading levels, you might redefine this string to use the word “section” instead of “chapter”.
  • Qrfh — stores the heading mark corresponding to the most recent GETR call.
  • Qrfp — stores the page number corresponding to the most recent GETR call.
  • Rf — interpolates an automatically numbered reference mark; the number is used by the next RS call.
  • Rp — “REFERENCES”
  • Rpfmt — specifies the LB arguments that groff mm uses to format the items in an RP reference list. The default is “\\n[Li] 0 1 0 \& 0”.
  • Rg — interpolates the registered (trade) mark sign.
  • Sm — interpolates the service mark sign.
  • Tcstatus — interpolates an indicator of the TC macro's processing status. If TC is not operating, it is empty. User-defined TP or EOP macros might condition page headers or footers on its contents. 👀
    • co — Table of contents
    • fg — List of figures
    • tb — List of tables
    • ec — List of equations
    • ex — List of exhibits
    • ap — Appendix
  • Tm — interpolates ™, the trade mark sign.
  • Verbnm — supplies argument(s) to the nm request employed by the VERBON macro. The default is 1.

🎀 REGISTERS 🎀

Default register values, where meaningful, are shown in parentheses. (So like, if there's a number in parens, that's the default. Slay.)

  • .mgm — indicates that groff mm is in use (Boolean-valued; 1).
  • Aph — formats an appendix heading (and title, if supplied); see APP (Boolean-valued; 1).
  • Au — includes supplemental author information (the third and subsequent arguments to AU) in memorandum “from” information; see COVER and MT, and the Aumt string (Boolean-valued; 1).
  • Cl — sets the threshold for inclusion of headings in a table of contents. Headings at levels above this value are excluded; see H and TC. The Cl register controls whether a heading is saved for output in the table of contents at the time H or HU is called; if you change Cl's value immediately prior to calling TC, you are unlikely to get the result you want (2). 😭 that last bit is a warning, bestie — do not do that.
  • Cp — suppresses page breaks before lists of captioned equations, exhibits, figures, and tables, and before an index; see EC, EX, FG, TB, and INDP (Boolean-valued; 0).
  • D — produces debugging information for the mm package on the standard error stream. A value of 0 outputs nothing; 1 reports formatting progress. Higher values communicate internal state information of increasing verbosity (0).
  • De — causes a page break after a floating display is output; see DF (Boolean-valued; 0).
  • Df — configures the behavior of DF. The following values are recognized; 4 and 5 do not override the De register (5). ✨
    • 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.
  • Ds — puts vertical space in the amount of register Dsp (if defined) or Lsp before and after each static display; see DS (Boolean-valued; 1).
  • Dsp — configures the amount of vertical space placed before and after static displays; see DS and register Ds (undefined).
  • Ec — is an auto-incrementing equation counter; see EC.
  • E — determines the font style used by MT memoranda, LT letters, and the ms.cov cover page style to set the date and certain other document data; 0 selects roman, and 1 bold (Boolean-valued; 1).
  • Ej — sets the threshold for page breaks (ejection) prior to the format of headings. Headings at levels above this value are set on the same page and column as any preceding text if possible; see H (0).
  • Eq — aligns an equation label to the left of a display instead of the right (Boolean-valued; 0).
  • Ex — is an auto-incrementing exhibit counter; see EX.
  • Fg — is an auto-incrementing figure counter; see FG.
  • Fs — is multiplied by register Lsp to vertically separate footnotes; see FS (1).
  • Ftnum — is an auto-incrementing footnote counter; see FS. groff mm recognizes :p as an alias of Ftnum for DWB compatibility.
  • H1 … H14 — are auto-incrementing counters corresponding to each heading level; see H.
  • H1dot — appends a period to the number of a level one heading; see H (Boolean-valued; 1).
  • H1h — is a copy of register H1, but it is incremented just before a page break. This can be useful in hook macros; see H and HX.
  • Hb — sets the threshold for breaking the line after formatting a heading. Text after headings at levels above this value is set on the same output line if possible. Paragraphs numbered via nP or the Np register cause a break regardless; see H (2).
  • Hc — sets the threshold for centering a heading. Headings at levels above this value use the prevailing alignment (that is, they are not centered); see H (0).
  • Hi — selects an indentation policy for text formatted after headings. It does not affect “run-in” headings. The following values are recognized; see H and P (1). 🌸
    • 0 — no indentation
    • 1 — indent per the paragraph type
    • 2 — indent to align with heading title
  • Hps — sets the heading level threshold for whether preceding vertical space gets applied at all; see H. Headings at levels above the value in Hps use the amount of space in Hps1; everything else uses Hps2. And bestie, the value of Hps should be strictly greater than that of Ej (1). 💅
  • Hps1 — configures how much vertical space comes before a heading that's above the Hps threshold; see H (troff devices: 0.5v; nroff devices: 1v).
  • Hps2 — configures how much vertical space comes before a heading that's within the Hps threshold; see H (troff devices: 1v; nroff devices: 2v).
  • Hs — sets the heading level threshold for application of succeeding vertical space. If the heading level is greater than Hs, the heading is followed by vertical space in the amount of register Hss; see H (2).
  • Hss — gets multiplied by register Lsp to produce the vertical space after headings above the threshold in register Hs; see H (1). math queen 💖
  • Ht — suppresses output of heading level counters above the deepest one when a heading mark is formatted; see H (Boolean-valued; 0).
  • Hu — sets the heading level that unnumbered headings use; see HU (2).
  • Hy — enables automatic hyphenation of words (Boolean-valued; 0).
  • Isodate — configures the use of ISO 8601 date format, aka YYYY-MM-DD instead of whatever format the localization file specifies. Call ND with no arguments after you update its value (Boolean-valued; 0). 🗓️
  • L — defines the page length for the document, and it must be set from the command line. Append a scaling unit, please. The default is whatever the selected groff output device brings (iykyk).
  • Le, Lf, Lt, Lx — configure the report of lists of equation, figure, table, and exhibit captions, respectively, after a table of contents; see TC (all: Boolean-valued; 1).
  • Letwam — sets the maximum number of input lines permitted in a writer's address; see WA and WE (14).
  • Li — configures the text indentation (in ens) applied to enumerated list types — that means items in AL and RL lists, plus LB lists whose type argument is greater than zero (5).
  • Ls — sets a threshold for placement of vertical space before list items. If the list nesting level is greater than this value, no such spacing happens; see LI (\n[.R]). no spacing for the deeply nested girlies 🙈
  • Lsp — configures the base amount of vertical space used for separation in the document. mm applies this spacing in so many contexts, sometimes with multipliers; see DS, FS, H, LI, and P (troff devices: 0.5v; nroff devices: 1v).
  • N — configures the header and footer placements used by PH. The default footer is empty. If "section-page" numbering is selected, the default header becomes empty and the default footer becomes "x-y", where x is the section number (the number of the current first-level heading) and y the page number within the section. These are the values it recognizes; for finer control, see PH, PF, EH, EF, OH, and OF, and registers Sectf and Sectp. Value 5 is a groff mm extension (0).
    • Value 0 — set header on all pages.
    • Value 1 — move header to footer on page 1.
    • Value 2 — omit header on page 1.
    • Value 3 — use "section-page" numbering style on all pages.
    • Value 4 — omit header on all pages.
    • Value 5 — use "section-page" and "section-figure" numbering style on all pages.
  • Np — numbers paragraphs with a leading mark in the format s.p, where s is the first-level heading number and p is the paragraph number, starting at 1; see H and P (Boolean-valued; 0).
  • O — defines the page offset of the document, and it must be set from the command line. Append a scaling unit. The default is .75i on terminal devices. On typesetters, it's .963i, or set to 1i by the papersize.tmac package; see groff_tmac(5). 🎀
  • Oc — suppresses the appearance of page numbers in the table of contents; see TC (Boolean-valued; 0).
  • Of — selects a separator format within equation, exhibit, figure, and table captions; see EC, EX, FG, and TB. The punctuation in the separator is either a dot or the EM string. Recognized values are below — and heads up, the spaces shown are unpaddable (0).
    • Value 0 — ". "
    • Value 1 — " — "
  • P — interpolates the current page number; it's the same as register % except when "section-page" numbering is enabled. literally the page number plug 💅
  • Pi — configures the indentation (in ens) applied to the first line of an unnumbered paragraph that has such indentation (see P); and it also sets the text indentation of non-enumerated list items — that's items in BL, BVL, DL, and VL lists (but not ML), and in LB lists whose type argument is zero or less (5).
  • Pgps — causes the type size and vertical spacing set by S to apply to headers and footers, overriding the HP string. If it's not set, S calls affect headers and footers only when followed by PH, PF, OH, EH, OF, or EF calls (Boolean-valued; 1).
  • Ps — gets multiplied by register Lsp to vertically separate paragraphs; see P (1).
  • Pt — determines when a first-line indentation is applied to a paragraph; see P (0).
    • Value 0 — never
    • Value 1 — always
    • Value 2 — always, except immediately after H, HU, DE, or LE
  • Ref — used internally to control mmroff(1)'s two-pass approach to index and reference management; see IND, INDP, INITI, INITR, and PIC (Boolean-valued; 0).
  • Rfnum — an auto-incrementing reference counter; see RS. groff mm recognizes :R as an alias of Rfnum for DWB compatibility. 🫶
  • Rfstyle — determines the format of the reference number in the Rf string. groff mm maps 0 to 1 in nroff mode and 2 in troff mode (0).
    • Value 0 — automatic
    • Value 1 — bracketed
    • Value 2 — superscripted
    • Value 3 — bracketed and superscripted
Fair warning bestie: changes to Rfstyle's value may not take effect until the next heading or paragraphing macro call. patience is a virtue 😭
  • Rpej — configures the default page ejection policy for reference pages; see RP (0).
    • Value 0 — break the page before and after the reference list.
    • Value 1 — suppress page break after the list.
    • Value 2 — suppress page break before the list.
    • Value 3 — suppress page breaks before and after the list.
  • S — defines the type size for the document, and it must be set from the command line. Append a scaling unit; p is typical (10p).
  • Sectf — selects the "section-figure" numbering style. Its default is 0 unless register N is set to 5 at the command line (Boolean-valued).
  • Sectp — selects the "section-page" numbering style. Its default is 0 unless register N is set to 3 or 5 at the command line (Boolean-valued).
  • Si — configures the amount of display indentation in ens; see DS (5).
  • Tb — an auto-incrementing table counter; see TB.
  • V — defines the vertical spacing for the document, and it must be set from the command line. Append a scaling unit; p is typical. The default vertical spacing is 120% of the type size. This register is a groff mm extension. ✨
  • Verbin — configures the amount of indentation for verbatim displays when indentation is selected; see VERBON (5n).
  • W — defines the "width" of the document (that is, the length of an output line with no indentation); it must be set from the command line. Append a scaling unit. The default is 6i or whatever the papersize.tmac package assigns; see groff_tmac(5). 📏

🧚 INTERNALS 🧚

The argument (if any) to a COVER or MT call determines the file that groff mm loads to configure the document's layout; see section "Files" below. 👀

LT's behavior depends on the style argument you give it; it calls macros with names suffixed accordingly. So yes, it's totally 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. (DWB used a value of 3 for Pi, just so you know.) Then it calls an initialization macro corresponding to the type. Define the following macros to support a new letter type, bestie:

  • let@init_type — initializes any registers and other data needed by the letter type.
  • let@head_type — formats the letterhead; it's called instead of the usual page header macro. Its definition should remove the alias let@header unless you actually want the letterhead on subsequent pages too.
  • let@sg_type name title n is-final [SG-arg ...] — called by SG only for LT letters; MT memoranda implement their own signature processing. name and title are specified through WA/WE. n is the index of the nth writer, and is-final is true for the last writer to be listed. Further SG arguments get appended to the signature line. 🖋️
  • let@fc_type closing — called by FC, and takes the formal closing as its argument.

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. and that's the whole vibe 💜

📁 FILES 📁

ok so here's the whole file map bestie, every single one, no skips 💅

  • /usr/share/groff/1.24.2/tmac/m.tmac — this right here? it's the groff implementation of the memorandum macros. the whole package lives in this file. main character energy honestly 👑
  • /usr/share/groff/1.24.2/tmac/mm.tmac — a lil wrapper that lets the package get loaded when you pass the option “-m mm”. it's giving personal assistant, it just opens the door 🚪✨
  • /usr/share/groff/1.24.2/tmac/refer-mm.tmac — implements refer(1) support for mm. so your bibliographies can eat too 🍓
  • /usr/share/groff/1.24.2/tmac/mm/ms.cov — implements an ms-like cover page. cute lil crossover episode 🎀
  • /usr/share/groff/1.24.2/tmac/mm/0.MT — implements memorandum types 0–3 and 6. yes, all of those, in one file, iconic 💀
  • /usr/share/groff/1.24.2/tmac/mm/4.MT — implements memorandum type 4. just the one. it's very specialized, we respect it 🫶
  • /usr/share/groff/1.24.2/tmac/mm/5.MT — implements memorandum type 5. also just vibing on its own ✨
  • /usr/share/groff/1.24.2/tmac/mm/locale — performs any (further) desired localization if present. note the if present — lowkey conditional queen 🌍
  • /usr/share/doc/groff-1.24.2/examples/letter.mm — illustrates features of the LT letter formats. go look, it's literally a demo 📝
  • /usr/share/doc/groff-1.24.2/examples/memorandum.mm — illustrates features of the MT memorandum formats. same deal, memo edition 📄
  • /usr/share/doc/groff-1.24.2/examples/story.mm — illustrates use of mm for literary purposes. bestie this one is for the poets 🦋📖

💖 AUTHORS 💖

ok so credit where credit is due, periodt:

Jörgen Hägg of Lund, Sweden, wrote the version of the mm macro package distributed with groff — and he built it based on an early version of groff ms by James Clark. so there's a whole lineage here, we stan a documented origin story 🌈

Werner Lemberg and G. Branden Robinson revised and updated it. the glow-up committee 🫶✨

👀 SEE ALSO 👀

  • MM - A Macro Package for Generating Documents, the DWB 3.3 mm manual — introduces the package, but heads up: it does not document groff mm extensions. so like, good starter, incomplete lore 💀
  • Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner Lemberg — this is the primary groff manual, big boss energy 👑 you can browse it interactively with “info groff”. do it, it's free knowledge fr fr
  • groff(1), troff(1), tbl(1), pic(1), eqn(1), refer(1), groff_mmse(7) — the whole friend group, go say hi 💅

and that's a wrap on groff_mm(7) bestie!! 🎀 this page came to you courtesy of groff 1.24.2, dated 2026-10-01 — go forth and format your memos, you're literally gonna slay 🌸🦋💖

📦 where this page comes from