|groff_ms(7)||Standards, Environments, and Macros||groff_ms(7)|
groff_ms - GNU roff manuscript macro package for formatting documents
||[option ...] [file ...]|
||[option ...] [file ...]|
The GNU implementation of the ms macro package is part of the groff document formatting system. The ms package is suitable for the composition of letters, memoranda, reports, and books.
These groff macros support cover page and table of contents generation, automatically numbered headings, several paragraph styles, a variety of text styling options, footnotes, and multi-column page layouts. ms supports the gtbl(1), geqn(1), gpic(1), and grefer(1) preprocessors for inclusion of tables, mathematical equations, diagrams, and standardized bibliographic citations.
This implementation is mostly compatible with the documented interface and behavior of AT&T Unix Version 7 ms. Many extensions from 4.2BSD (Berkeley) and Tenth Edition Research Unix have been recreated.
The ms macro package expects a certain amount of structure: a well-formed document contains at least one paragraphing or heading macro call. To compose a simple document from scratch, begin it by calling .LP or .PP. Longer documents have a structure as follows.
The following tables list the document control registers, strings, and special characters. For any parameter whose default is unsatisfactory, define it before calling any ms macro other than RP.
|\n[PO]||Page offset (left margin)||next page||1i (0)|
|\n[LL]||Line length||next paragraph||6.5i (65n)|
|\n[LT]||Title line length||next paragraph||6.5i (65n)|
|\n[HM]||Top (header) margin||next page||1i|
|\n[FM]||Bottom (footer) margin||next page||1i|
|Titles (headers, footers)|
|\*[LH]||Left header text||next header||empty|
|\*[CH]||Center header text||next header||-\n[%]-|
|\*[RH]||Right header text||next header||empty|
|\*[LF]||Left footer text||next footer||empty|
|\*[CF]||Center footer text||next footer||empty|
|\*[RF]||Right footer text||next footer||empty|
|\n[PS]||Point size||next paragraph||10p|
|\n[VS]||Vertical spacing (leading)||next paragraph||12p|
|\n[HY]||Hyphenation mode||next paragraph||6|
|\*[FAM]||Font family||next paragraph||T|
|\n[PD]||Paragraph distance (spacing)||next paragraph||0.3v (1v)|
|\n[QI]||Quotation indentation||next paragraph||5n|
|\n[PORPHANS]||# of initial lines kept||next paragraph||1|
|\n[PSINCR]||Point size increment||next heading||1p|
|\n[GROWPS]||Size increase depth limit||next heading||0|
|\n[HORPHANS]||# of following lines kept||next heading||1|
|\*[SN-STYLE]||Numbering style (alias)||next heading||\*[SN-DOT]|
\*[SN-STYLE] can alternatively be made an alias of \*[SN-NO-DOT] with the als request.
|\n[FPS]||Point size||next footnote||\n[PS]-2p|
|\n[FVS]||Vertical spacing (leading)||next footnote||\n[FPS]+2p|
|\n[FPD]||Paragraph distance (spacing)||next footnote||\n[PD]/2|
|\*[FR]||Line length ratio||special||11/12|
|\n[DD]||Display distance (spacing)||special||0.5v (1v)|
|\n[MINGW]||Minimum gutter width||next page||2n|
|\n[TC-MARGIN]||TOC page number margin width||next PX call||\w'000'|
|\[TC-LEADER]||TOC leader character||next PX call||.\h'1m'|
For entries marked “special” in the “Effective” column, see the discussion in the applicable section below. The PO, LL, and LT register defaults vary by output device and paper format; the values shown are for typesetters using U.S. letter paper, and then terminals. See section “Paper format” of groff(1). The PD and DD registers use the larger value if the vertical motion quantum of the output device is too coarse for the smaller one; usually, this is the case only for output to terminals and emulators thereof. The “gutter” affected by \n[MINGW] is the gap between columns in multiple-column page arrangements. The TC-MARGIN register and TC-LEADER special character affect the formatting of tables of contents assembled by the XS, XA, and XE macros.
Define information describing the document by calling the macros below in the order shown; .DA or .ND can be called to set the document date (or other identifier) at any time before (a) the abstract, if present, or (b) its information is required in a header or footer. Use of these macros is optional, except that .TL is mandatory if any of .RP, .AU, .AI, or .AB is called, and .AE is mandatory if .AB is called.
The FAM string, a GNU extension, sets the font family for
body text; the default is “T”. The PS and
VS registers set the type size and vertical spacing (distance between
text baselines), respectively. The font family and type size are ignored on
terminal devices. Setting these parameters before the first call of a
heading, paragraphing, or (non-date) document description macro also applies
them to headers, footers, and (for FAM) footnotes.
The HY register defines the automatic hyphenation mode used with the hy request. Setting \n[HY] to 0 is equivalent to using the nh request. This is a Tenth Edition Research Unix extension.
ms provides a few strings to obtain typographical symbols not easily entered with the keyboard. These and many others are available as special character escape sequences—see groff_char(7).
Paragraphing macros break, or terminate, any pending output line so that a new paragraph can begin. Several paragraph types are available, differing in how indentation applies to them: to left, right, or both margins; to the first output line of the paragraph, all output lines, or all but the first. All paragraphing macro calls cause the insertion of vertical space in the amount stored in the PD register, except at page or column breaks, or adjacent to displays.
The PORPHANS register defines the minimum number of initial lines of any paragraph that must be kept together to avoid isolated lines at the bottom of a page. If a new paragraph is started close to the bottom of a page, and there is insufficient space to accommodate \n[PORPHANS] lines before an automatic page break, then a page break is forced before the start of the paragraph. This is a GNU extension.
Use headings to create a hierarchical structure for your document. The ms macros print headings in bold using the same font family and, by default, type size as the body text. Headings are available with and without automatic numbering. Text on input lines following the macro call becomes the heading's title. Call a paragraphing macro to end the heading text and start the section's content.
After .NH is called, the assigned number is made available in the strings SN-DOT (as it appears in a printed heading with default formatting, followed by a terminating period) and SN-NO-DOT (with the terminating period omitted). These are GNU extensions.
You can control the style used to print numbered headings by defining an appropriate alias for the string SN-STYLE. By default, \*[SN-STYLE] is aliased to \*[SN-DOT]. If you prefer to omit the terminating period from numbers appearing in numbered headings, you may alias it to \*[SN-NO-DOT]. Any such change in numbering style becomes effective from the next use of .NH following redefinition of the alias for \*[SN-STYLE]. The formatted number of the current heading is available in \*[SN] (a feature first documented by Berkeley); this string facilitates its inclusion in, for example, table captions, equation labels, and .XS/.XA/.XE table of contents entries.
The PSINCR register defines an increment in type size to be applied to a heading at a lesser depth than that specified in \n[GROWPS]. The value of \n[PSINCR] should be specified in points with the “p” scaling unit and may include a fractional component.
The GROWPS register defines the heading depth above which the type size increment set by \n[PSINCR] becomes effective. For each heading depth less than the value of \n[GROWPS], the type size is increased by \n[PSINCR]. Setting \n[GROWPS] to a value less than 2 disables the incremental heading size feature.
In other words, if the value of GROWPS register is greater than the depth argument to a .NH or .SH call, the type size of a heading produced by these macros increases by \n[PSINCR] units over \n[PS] multiplied by the difference of \n[GROWPS] and depth.
The \n[HORPHANS] register operates in conjunction with the NH and SH macros to inhibit the printing of isolated headings at the bottom of a page; it specifies the minimum number of lines of the subsequent paragraph that must be kept on the same page as the heading. If insufficient space remains on the current page to accommodate the heading and this number of lines of paragraph text, a page break is forced before the heading is printed. Any display macro call or tbl, pic, or eqn region between the heading and the subsequent paragraph suppresses this grouping.
The ms macros provide a variety of ways to style text. Attend closely to the ordering of arguments labeled pre and post, which is not intuitive. Support for pre arguments is a GNU extension.
When pre is used, a hyphenation control escape sequence \% that would ordinarily start text must start pre instead.
groff ms also offers strings to begin and end super- and subscripting. These are GNU extensions.
You may need to indent a region of text while otherwise formatting it normally. Indented regions can be nested.
On occasion, you may want to keep several lines of text, or a region of a document, together on a single page, preventing an automatic page break within certain boundaries. This can cause a page break to occur earlier than it normally would.
You can alternatively specify a floating keep: if a keep cannot fit on the current page, ms holds its contents and allows text following the keep (in the source document) to fill in the remainder of the current page. When the page breaks, whether by reaching the end or bp request, ms puts the floating keep at the beginning of the next page.
As an alternative to the keep mechanism, the ne request forces a page break if there is not at least the amount of vertical space specified in its argument remaining on the page.
A boxed keep has a frame drawn around it.
Boxed keep macros cause breaks; if you need to box a word or
phrase within a line, see the BX macro in section
“Highlighting” above. Box lines are drawn as close as possible
to the text they enclose so that they are usable within paragraphs. If you
wish to place one or more paragraphs in a boxed keep, you may improve their
appearance by calling .B1 after the first paragraphing macro, and by
adding a small amount of vertical space before calling .B2.
If you want a boxed keep to float, you will need to enclose the .B1 and .B2 calls within a pair of .KF and .KE calls.
Displays turn off filling; lines of verse or program code are shown with their lines broken as in the source document without requiring br requests between lines. Displays can be kept on a single page or allowed to break across pages. The DS macro begins a kept display of the layout specified in its first argument; non-kept displays are begun with dedicated macros corresponding to their layout.
The distance stored in \n[DD] is inserted before and after each pair of display macros; this is a Berkeley extension. In groff ms, this distance replaces any adjacent inter-paragraph distance or subsequent spacing prior to a section heading. The DI register is a GNU extension; its value is an indentation applied to displays created with .DS and .ID without arguments, to “.DS I” without an indentation argument, and to equations set with “.EQ I”. Changes to either register take effect at the next display boundary.
The ms package is often used with the gtbl, gpic, geqn, and grefer preprocessors. The \n[DD] distance is also applied to regions of the document preprocessed with geqn, gpic, and gtbl. Mark text meant for preprocessors by enclosing it in pairs of tokens as follows, with nothing between the dot and the macro name. The preprocessors match these tokens only at the start of an input line.
When grefer emits collected references (as might be done on
a “Works Cited” page), it interpolates the string
\*[REFERENCES] as an unnumbered heading (.SH).
Attempting to place a multi-page table inside a keep can lead to unpleasant results, particularly if the tbl “allbox” option is used.
A footnote is typically anchored to a place in the text with a marker, which is a small integer, a symbol, or arbitrary user-specified text.
Enclose the footnote text in FS and FE macro calls to set it at the nearest available “foot”, or bottom, of a text column or page.
groff ms provides a hook macro, FS-MARK, for user-determined operations to be performed when the FS macro is called. It is passed the same arguments as .FS itself. By default, this macro has an empty definition. .FS-MARK is a GNU extension.
Footnote text is formatted as paragraphs are, using analogous parameters. The registers FI, FPD, FPS, and FVS correspond to PI, PD, PS, and VS, respectively; FPD, FPS, and FVS are GNU extensions.
The FF register controls the formatting of automatically numbered footnote paragraphs, and those for which .FS is given a marker argument, at the bottom of a column or page as follows.
groff ms provides several strings that you can customize for your own purposes, or redefine to adapt the macro package to languages other than English. It is already localized for Czech, German, French, Italian, and Swedish. Load the desired localization macro package after ms; see groff_tmac(5).
|\*[TOC]||Table of Contents|
There are multiple ways to produce headers and footers. One is to define the strings LH, CH, and RH to set the left, center, and right headers, respectively; and LF, CF, and RF to set the left, center, and right footers. This approach suffices for documents that do not distinguish odd- and even-numbered pages.
Another method is to call macros that set headers or footers for
odd- or even-numbered pages. Each such macro takes a delimited argument
separating the left, center, and right header or footer texts from each
other. You can replace the neutral apostrophes (') shown below with any
character not appearing in the header or footer text. These macros are
With either method, a percent sign % in header or footer text is replaced by the current page number. By default, ms places no header on a page numbered “1” (regardless of its number format).
For even greater flexibility, ms permits redefinition of the macros called when the page header and footer traps are sprung. PT (“page trap”) is called by ms when the header is to be written, and BT (“bottom trap”) when the footer is to be. The groff page location trap that ms sets up to format the header also calls the (normally undefined) HD macro after .PT; you can define .HD if you need additional processing after setting the header. The HD hook is a Berkeley extension. Any such macros you (re)define must implement any desired specialization for odd-, even-, or first numbered pages.
Use the ta request to set tab stops as needed.
Control margins using the registers summarized in the “Margins” portion of the table in section “Document control settings” above. There is no setting for the right margin; the combination of page offset \n[PO] and line length \n[LL] determines it.
ms can set text in as many columns as reasonably fit on the page. The following macros force a page break if a multi-column layout is active when they are called. \n[MINGW] is the default minimum gutter width; it is a GNU extension. When multiple columns are in use, keeps and the HORPHANS and PORPHANS registers work with respect to column breaks instead of page breaks.
Define an entry to appear in the table of contents by bracketing its text between calls to the XS and XE macros. A typical application is to call them immediately after NH or SH and repeat the heading text within them. The XA macro, used within .XS/.XE pairs, supplements an entry—for instance, when it requires multiple output lines, whether because a heading is too long to fit or because style dictates that page numbers not be repeated. You may wish to indent the text thus wrapped to correspond to its heading depth; this can be done in the entry text by prefixing it with tabs or horizontal motion escape sequences, or by providing a second argument to the XA macro. .XS and .XA automatically associate the page number where they are called with the text following them, but they accept arguments to override this behavior. At the end of the document, call TC or PX to emit the table of contents; .TC resets the page number to i (Roman numeral one), and then calls PX. All of these macros are Berkeley extensions.
The remaining features in this subsection are GNU extensions. groff ms obviates the need to repeat heading text after .XS calls. Call .XN and .XH after .NH and .SH, respectively. Text to be appended to the formatted section heading, but not to appear in the table of contents entry, can follow these calls.
groff ms encourages customization of table of contents entry production. (Re-)define any of the following macros as desired.
You can customize the style of the leader that bridges each table of contents entry with its page number; define the TC-LEADER special character by using the char request. A typical leader combines the dot glyph “.” with a horizontal motion escape sequence to spread the dots. The width of the page number field is stored in the TC-MARGIN register.
The groff ms macros are an independent reimplementation, using no AT&T code. Since they take advantage of the extended features of groff, they cannot be used with AT&T troff. groff ms supports features described above as Berkeley and Tenth Edition Research Unix extensions, and adds several of its own.
Several macros described in the Unix Version 7 ms documentation are unimplemented by groff ms because they are specific to the requirements of documents produced internally by Bell Laboratories, some of which also require a glyph for the Bell System logo that groff does not support. These macros implemented several document type formats (EG, IM, MF, MR, TM, TR), were meaningful only in conjunction with the use of certain document types (AT, CS, CT, OK, SG), stored the postal addresses of Bell Labs sites (HO, IH, MH, PY, WH), or lacked a stable definition over time (UX).
groff ms retains some legacy features solely to support formatting of historical documents; contemporary ones should not use them because they can render poorly. See groff_char(7) instead.
AT&T ms defined accent mark strings as follows.
|\*[']||Apply acute accent to subsequent glyph.|
|\*[`]||Apply grave accent to subsequent glyph.|
|\*[:]||Apply dieresis (umlaut) to subsequent glyph.|
|\*[^]||Apply circumflex accent to subsequent glyph.|
|\*[~]||Apply tilde accent to subsequent glyph.|
|\*[C]||Apply caron to subsequent glyph.|
|\*[,]||Apply cedilla to subsequent glyph.|
Berkeley ms offered an AM macro; calling it redefined the AT&T accent mark strings (except for \*C), applied them to the preceding glyph, and defined additional strings, some for spacing glyphs.
|\*[']||Apply acute accent to preceding glyph.|
|\*[`]||Apply grave accent to preceding glyph.|
|\*[:]||Apply dieresis (umlaut) to preceding glyph.|
|\*[^]||Apply circumflex accent to preceding glyph.|
|\*[~]||Apply tilde accent to preceding glyph.|
|\*[,]||Apply cedilla to preceding glyph.|
|\*[/]||Apply stroke (slash) to preceding glyph.|
|\*[v]||Apply caron to preceding glyph.|
|\*[_]||Apply macron to preceding glyph.|
|\*[.]||Apply underdot to preceding glyph.|
|\*[o]||Apply ring accent to preceding glyph.|
|\*[?]||Interpolate inverted question mark.|
|\*[!]||Interpolate inverted exclamation mark.|
|\*||Interpolate small letter sharp s.|
|\*[q]||Interpolate small letter o with hook accent (ogonek).|
|\*||Interpolate small letter yogh.|
|\*[d-]||Interpolate small letter eth.|
|\*[D-]||Interpolate capital letter eth.|
|\*[th]||Interpolate small letter thorn.|
|\*[TH]||Interpolate capital letter thorn.|
|\*[ae]||Interpolate small ae ligature.|
|\*[AE]||Interpolate capital ae ligature.|
|\*[oe]||Interpolate small oe ligature.|
|\*[OE]||Interpolate capital oe ligature.|
The following conventions are used for names of macros, strings, and registers. External names available to documents that use the groff ms macros contain only uppercase letters and digits.
Internally, the macros are divided into modules. Conventions for identifier names are as follows.
Thus the groff ms macros reserve the following names:
A manual is available in source and rendered form. On your system, it may be compressed and/or available in additional formats.
Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner Lemberg, is the primary groff manual. You can browse it interactively with “info groff”.
groff(1), gtroff(1), gtbl(1), gpic(1), geqn(1), grefer(1)
|2 July 2023||groff 1.23.0|