Using groff with the ms Macro Package

Larry Kollar
kollar@alltel.net
G. Branden Robinson
g.branden.robinson@gmail.com

The ms (“manuscript”) package is suitable for the composition of letters, memoranda, reports, and books. These groff macros feature 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 tbl, eqn, pic, and refer 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.

1. Introduction

The ms macros are the oldest surviving package for roff systems. 1

While manual pages are older, early ones used macros supplanted by the man package of Seventh Edition Unix (1979). ms shipped with Sixth Edition (1975) and was documented by Mike Lesk in a Bell Labs internal memorandum.

While the man package was designed for brief reference documents, the ms macros are also suitable for longer works intended for printing and possible publication.

In this document, a right arrow (→) is used to indicate a tab character in the input.

1.1. Basic information

ms documents are plain text files; prepare them with your preferred text editor. If you’re in a hurry to start, know that ms needs one of its macros called at the beginning of a document so that it can initialize. A macro is a formatting instruction to ms. Put a macro call on a line by itself. Use .PP if you want your paragraph’s first line to be indented, or .LP if you don’t.

After that, start typing normally. It is a good practice to start each sentence on a new line, or to put two spaces after sentence-ending punctuation, so that the formatter knows where the sentence boundaries are. You can separate paragraphs with further paragraphing macro calls, or with blank lines, and you can indent with tabs. When you need one of the features mentioned earlier, return to this manual.

Format the document with the groff(1) command. nroff(1) can be useful for previewing.

Our radical.ms document might look like this.

ms exposes many aspects of document layout to user control via groff’s registers and strings, which store numbers and text, respectively. Measurements in groff are expressed with a suffix called a scaling unit.

Set registers with the nr request and strings with the ds request. Requests are like macro calls; they go on lines by themselves and start with the control character, a dot (.). The difference is that they directly instruct the formatter program, rather than the macro package. We’ll discuss a few as applicable. It is wise to specify a scaling unit when setting any register that represents a length, size, or distance.

In the foregoing, we see that \" begins a comment. This is an example of an escape sequence, the other kind of formatting instruction. Escape sequences can appear anywhere. They begin with the escape character (\) and are followed by at least one more character. ms documents like this one tend to use only a few of groff’s many requests and escape sequences; see the groff(7) man page for complete lists.

Prefix any words that start with a dot (.) or neutral apostrophe (') with \& if they are at the beginning of an input line (or might become that way in editing) to prevent them from being interpreted as macro calls or requests. Suffix ., ?, and ! with \& when needed to cancel end-of-sentence detection.

2 May 2023

2. General structure of an ms document

The ms macro package expects a certain amount of structure: a well-formed document contains at least one paragraphing or heading macro call. Longer documents have a structure as follows.

Calling the RP macro at the beginning of your document puts the document description (see below) on a cover page. Otherwise, ms places this information (if any) on the first page, followed immediately by the body text. Some document types found in other ms implementations are specific to AT&T or Berkeley, and are not supported by groff ms.

By setting registers and strings, you can configure your document’s typeface, margins, spacing, headers and footers, and footnote arrangement. See section “Document control settings” below.

A document description consists of any of: a title, one or more authors’ names and affiliated institutions, an abstract, and a date or other identifier. See section “Document description macros” below.

The main matter of your document follows its description (if any). ms supports highly structured text consisting of paragraphs interspersed with multi-level headings (chapters, sections, subsections, and so forth) and augmented by lists, footnotes, tables, diagrams, and similar material. See section “Body text” below.

Macros enable the collection of entries for a table of contents (or index) as the material they discuss appears in the document. You then call a macro to emit the table of contents at the end of your document. The table of contents must necessarily follow the rest of the text since GNU troff is a single-pass formatter; it thus cannot determine the page number of a division of the text until it has been set and output. Since ms output was designed for the production of hard copy, the traditional procedure was to manually relocate the pages containing the table of contents between the cover page and the body text. Today, page resequencing is more often done in the digital domain. An index works similarly, but because it typically needs to be sorted after collection, its preparation requires separate processing.

Using groff with the ms macros 3

3. Document control settings

The document parameters below are presented in the syntax used to interpolate their values. For any unsatisfactory default, define its register, string, or special character before calling any ms macro other than RP. The “Next” heading indicates that changes to the parameter are effective as of the next new element processed of the listed type. For entries marked special, see the discussion in the applicable section.

4 May 2023

4. Document description macros

Only the simplest document lacks a title. 2

Distinguish a document title from “titles”, which are what roff systems call headers and footers collectively.

As its level of sophistication (or complexity) increases, it tends to acquire a date of revision, explicitly identified authors, sponsoring institutions for authors, and, at the rarefied heights, an abstract of its content. By default, ms arranges most of the document description (the title, author names and institutions, and abstract, but not the date) at the top of the first page.

Define these data 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.      

An example document description, using a cover page, follows.

Using groff with the ms macros 5

5. Body text

A variety of macros, registers, and strings can be used to structure and style the body of your document. They organize your text into paragraphs, headings, footnotes, and inclusions of material such as tables and figures.

5.1. Text settings

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.

Which font families are available depends on the output device; as a convention, T selects a serif family (“Times”), H a sans-serif family (“Helvetica”), and C a monospaced family (“Courier”). The man page for the output driver documents its font repertoire. Consult the groff(1) man page for lists of available output devices and their drivers.

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.

5.2. Typographical symbols

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 the groff_char(7) man page.

5.3. Paragraphs

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. Alternatively, a blank input line breaks the output line and vertically spaces by one vee.

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.

The following example illustrates the use of paragraphing macros.

5.4. Headings

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.

An example may be illustrative.

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 define the alias as follows.

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), which 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; for example,

sets a type size increment of 1.5 points.

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. For example, the sequence

will cause “1. Carnivora” to be printed in 13-point text, followed by “1.1. Felinae” in 11.5-point text, while “1.1.1. Felis catus” and all more deeply nested headings will remain in the 10-point text specified by the PS register. “Machairodontinae” is printed at 11.5 points, since it corresponds to heading depth 2.

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 (see subsequent sections) between the heading and the subsequent paragraph suppresses this grouping.

5.5. Typeface and decoration

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

This idiosyncrasy arose through feature accretion; for example, the B macro in Version 6 Unix ms (1975) accepted only one argument, the text to be set in boldface. By Version 7 (1979) it recognized a second argument; in 1990, groff ms added a “pre” argument, placing it third to avoid breaking support for older documents.    

pre and post arguments are typically used to simplify the attachment of punctuation to styled words. When pre is used, a hyphenation control escape sequence \% that would ordinarily start text must start pre instead to have the desired effect.

You can use the output line continuation escape sequence \c to achieve the same result. It is also portable to some older ms implementations.

Rather than calling the CW macro, in groff ms you might prefer to change the font family to Courier by setting \*[FAM] to “C”. You can then use all four style macros above, returning to the default family (Times) with “.ds FAM T”. Because changes to \*[FAM] take effect only at the next paragraph, this document uses .CW to “inline” a change to the font family, marking syntactical elements of ms and groff.

groff ms also offers strings to begin and end super- and subscripting. These are GNU extensions.

5.6. Lists

The marker argument to the IP macro can be employed to present a variety of lists; for instance, you can use a bullet glyph (\[bu]) for unordered lists, a number (or auto-incrementing register) for numbered lists, or a word or phrase for glossary-style or definition lists. If you set the paragraph indentation register PI before calling IP, you can later reorder the items in the list without having to ensure that a width argument remains affixed to the first call.

In the enumerated list example, we employed the nr request to create a register of our own, step. We initialized it to zero and assigned it an auto-increment of 1. Each time we use the escape sequence \n+[PI] (note the plus sign), the formatter applies the increment just before interpolating the register’s value. Preparing the PI register as well enables us to rearrange the list without the tedium of updating macro calls.

In the glossary example, observe how the IP macro places the definition on the same line as the term if it has enough space. If this is not what you want, there are a few workarounds we will illustrate by modifying the example. First, you can use a br request to force a break after printing the term or label. Second, you could apply the \p escape sequence to force a break. The space following the escape sequence is important; if you omit it, groff prints the first word of the paragraph text on the same line as the term or label (if it fits) then breaks the line. Finally, you may append a horizontal motion to the marker with the \h escape sequence; using the same amount as the indentation will ensure that the marker is too wide for groff to treat it as “fitting” on the same line as the paragraph text.

5.7. Indented regions

You may need to indent a region of text while otherwise formatting it normally. Indented regions can be nested; you can change \n[PI] before each call to vary the amount of inset.

This feature enables you to easily line up text under hanging and indented paragraphs. For example, you may wish to structure lists hierarchically.

5.8. Keeps, boxed keeps, and displays

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. For example, you may want to keep two paragraphs together, or a paragraph that refers to a table, list, or figure adjacent to the item it discusses. ms provides the KS and KE macros for this purpose.

You can alternatively specify a floating keep: if a keep cannot fit on the current page, ms holds its contents and allows material following the keep (in the source document) to fill 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. This is useful for placing large graphics or tables that do not need to appear exactly where they occur in the source document.

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. One application of ne is to reserve space on the page for a figure or illustration to be included later.

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 “Typeface and decoration” 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.

5.9. Tables, figures, equations, and references

The ms package is often used with the tbl, pic, eqn, and refer preprocessors. The \n[DD] distance is also applied to regions of the document preprocessed with tbl, pic, and eqn. 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 refer emits collected references (as might be done on a “Works Cited” page), it interpolates the string \*[REFERENCES] as an unnumbered heading (.SH).

The following is an example of how to set up a table that may print across two or more pages.

Attempting to place a multi-page table inside a keep can lead to unpleasant results, particularly if the tbl allbox option is used.

Mathematics can be typeset using the language of the eqn preprocessor.

This input formats a labelled equation. We used the SN-NO-DOT string to base the equation label on the current heading number, giving us more flexibility to reorganize the document.

Use
groff
options
to run preprocessors on the input:
-e
for
eqn,
-p
for
pic,
-R
for
refer,
and
-t
for
tbl.

5.10. Footnotes

A footnote is typically anchored to a place in the text with a marker, which is a small integer, 4

like this numeric footnote

a symbol, †

like this symbolic footnote

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.

You may not desire automatically numbered footnotes in spite of their convenience. You can indicate a footnote with a symbol or other text by specifying its marker at the appropriate place (for example, by using \[dg] for the dagger glyph) and as an argument to the FS macro. Such manual marks should be repeated as arguments to .FS or as part of the footnote text to disambiguate their correspondence. You may wish to use \*{ and \*} to superscript the marker at the anchor point, in the footnote text, or both.

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. An application of FS-MARK is anchor placement for a hyperlink reference, so that a footnote can link back to its referential context. 5

“Portable Document Format Publishing with GNU Troff”, pdfmark.ms in the groff distribution, uses this technique.

By default, this macro has an empty definition. FS-MARK is a GNU extension.

The following input was used to produce the first sentence in this section.

Footnotes can be safely used within keeps and displays, but you should avoid using automatically numbered footnotes within floating keeps. You can place a second \** interpolation between a \** and its corresponding .FS call as long as each .FS call occurs after the corresponding \** and occurrences of .FS are in the same order as corresponding occurrences of \**.

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.

The default footnote line length is 11/12ths of the normal line length for compatibility with the expectations of historical ms documents; you may wish to set \*[FR] to 1 to align with contemporary typesetting practices. In the past, 6

Unix Version 7 ms, its descendants, and groff ms prior to version 1.23.0

an FL register was used for the line length in footnotes; however, setting this register at document initialization time had no effect on the footnote line length in multi-column arrangements. 7

You could reset it after each call to .1C, .2C, or .MC.

\*[FR] should be used in preference to \n[FL] in contemporary documents. The footnote line length is effectively computed as “column-width  * \*[FR]”. If an absolute footnote line length is required, recall that arithmetic expressions in the roff language are evaluated strictly from left to right, with no operator precedence (parentheses are honored).

Changes to the footnote length ratio \*[FR] take effect with the next footnote written in single-column arrangements, but on the next page in multiple-column contexts.

5.11. Language and localization

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 the groff_tmac(5) man page.

The following strings are available.

The default for \*[ABSTRACT] includes font selection escape sequences to set the word in italics.

5.12. Glyphs for special characters

Some of the special character escape sequences used in this document are listed below. The minus sign glyph can also be accessed by the shorthand \−. These and many others are documented in the groff_char(7) man page.

6 May 2023

6. Page layout

ms’s default page layout arranges text in a single column with the page number between hyphens centered in a header on each page except the first, and produces no footers. You can customize this arrangement.

6.1. Headers and footers

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 Berkeley extensions.

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 is designed to permit the redefinition of the macros that are called when the groff traps that ordinarily cause the headers and footers to be output 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 (for example, to draw a line below it). 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.

6.2. Tab stops

Use the ta request to set tab stops as needed.

6.3. Margins

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.

6.4. Multiple columns

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.

6.5. Creating a table of contents

Because roff formatters process their input in a single pass, material on page 50, for example, cannot influence what appears on page 1—this poses a challenge for a table of contents at its traditional location in front matter, if you wish to avoid manually maintaining it. ms enables the collection of material to be presented in the table of contents as it appears, saving its page number along with it, and then emitting the collected contents on demand toward the end of the document. The table of contents can then be resequenced to its desired location by physically rearranging the pages of a printed document, or as part of post-processing—with a sed(1) script to reorder the pages in troff’s output, with pdfjam(1), or with gropdf(1)’s .pdfswitchtopage feature, for example.

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.

Here’s an example of typical ms table of contents preparation and its result. We employ horizontal escape sequences \h to indent the entries by sectioning depth.

_________________________________________________________________

Table of Contents

. . . . . . . . . . . . . . . . . . . . . . . . . 1

Methodology

. . . . . . . . . . . . . . . . . . . . . . . . 2
Fassbinder’s Approach
Kahiu’s Approach

. . . . . . . . . . . . . . . . . . . . . . . . . . . 5 _________________________________________________________________

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.

groff ms encourages customization of table of contents entry production.

You can change 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.

Using groff with the ms macros 7

7. Differences from AT&T ms

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.

The internals of groff ms differ from those of AT&T ms. Documents that depend upon implementation details of AT&T ms may not format properly with groff ms. Such details include macros whose function was not documented in the AT&T ms manual [Lesk 1978].

The error-handling policy of groff ms is to detect and report errors, rather than to ignore them silently.

Tenth Edition Research Unix supported P1/ P2 macros to bracket code examples; groff ms does not.

groff ms does not work in GNU troff’s AT&T compatibility mode. If loaded when that mode is enabled, it aborts processing with a diagnostic message.

Multiple line spacing is not supported. Use a larger vertical spacing instead.

groff ms uses the same header and footer defaults in both nroff and troff modes as AT&T ms does in troff mode; AT&T’s default in nroff mode is to put the date, in U.S. traditional format (e.g., “January 1, 2021”), in the center footer (the CF string).

Many groff ms macros, including those for paragraphs, headings, and displays, cause a reset of formatting parameters, and may change the indentation; they do so not by incrementing or decrementing it, but by setting it absolutely. This can cause problems for documents that define additional macros of their own that try to manipulate indentation. Use .RS and .RE instead of the in request.

AT&T ms interpreted the values of the registers PS and VS in points, and did not support the use of scaling units with them. groff ms interprets values of the registers PS, VS, FPS, and FVS equal to or larger than 1,000 (one thousand) as decimal fractions multiplied by 1,000. 8

Register values are converted to and stored as basic units. See “Measurements” in the groff Texinfo manual or in groff(7).

This threshold makes use of a scaling unit with these parameters practical for high-resolution devices while preserving backward compatibility. It also permits expression of non-integral type sizes. For example, “groff -rPS=10.5p” at the shell prompt is equivalent to placing “.nr PS 10.5p” at the beginning of the document.

AT&T ms’s AU macro supported arguments used with some document types; groff ms does not.

Right-aligned displays are available. The AT&T ms manual observes that “it is tempting to assume that .DS R will right adjust lines, but it doesn’t work”. In groff ms, it does.

To make groff ms use the default page offset (which also specifies the left margin), the PO register must stay undefined until the first ms macro is called. This implies that \n[PO] should not be used early in the document, unless it is changed also: accessing an undefined register automatically defines it.

groff ms supports the PN register, but it is not necessary; you can access the page number via the usual % register and invoke the af request to assign a different format to it if desired. 9

If you redefine the ms PT macro and desire special treatment of certain page numbers (like “1”), you may need to handle a non-Arabic page number format, as groff ms’s .PT does; see the macro package source. groff ms aliases the PN register to %.

The AT&T ms manual documents registers CW and GW as setting the default column width and “intercolumn gap”, respectively, and which applied when .MC was called with fewer than two arguments. groff ms instead treats .MC without arguments as synonymous with .2C; there is thus no occasion for a default column width register. Further, the MINGW register and the second argument to .MC specify a minimum space between columns, not the fixed gutter width of AT&T ms.

The AT&T ms manual did not document the QI register; Berkeley and groff ms do.

The register GS is set to 1 by the groff ms macros, but is not used by the AT&T ms package. Documents that need to determine whether they are being formatted with groff ms or another implementation should test this register.

7.1. Unix Version 7 ms macros not implemented by groff ms

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). To compatibly render historical ms documents using these macros, we advise your documents to invoke the rm request to remove any such macros it uses and then define replacements with an authentically typeset original at hand. 10

The removal beforehand is necessary because groff ms aliases these macros to a diagnostic macro, and you want to redefine the aliased name, not its target.

For informal purposes, a simple definition of UX should maintain the readability of the document’s substance.

8 May 2023

8. Legacy features

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.

8.1. AT&T ms accent mark strings

AT&T ms defined accent mark strings as follows.

8.2. Berkeley ms accent mark and glyph strings

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.

Using groff with the ms macros 9

9. Further reading

“Typing Documents on the Unix System: Using the -ms Macros with Troff and Nroff”; M. E. Lesk; November 13, 1978. This document describes the ms supplied with AT&T Unix Version 7.

“A Revised Version of -ms”; Bill Tuthill; August 1983. The 4.2BSD release featured several extensions to ms, most of which are recreated in groff ms. (The exceptions are the TM and CT macros for setting a doctoral thesis in the format required by the contemporaneous degree-granting authorities of the University of California at Berkeley.)

“Using PDF boxes with groff and the ms macros”; Deri James; March 2021. BOXSTART and BOXSTOP macros are available via the sboxes extension package, enabling colored, bordered boxes when the pdf output device is used. This document is distributed with groff as the file msboxes.pdf.

This manual was composed using groff ms; the curious may consult its source in the file ms.ms to see how its formatting was achieved.

Using groff with the ms macros i

Table of Contents

Introduction

. . . . . . . . . . . . . . . . . . . . . . . . . 1

. . . . . . . . . . . . . . . . . . . . 1

. . . . . . . . . . . . . 2

. . . . . . . . . . . . . . . . . . 3

. . . . . . . . . . . . . . . . . 4

. . . . . . . . . . . . . . . . . . . . . . . . . . 5

. . . . . . . . . . . . . . . . . . . . . . 5

. . . . . . . . . . . . . . . . . . 5

. . . . . . . . . . . . . . . . . . . . . . . 5

. . . . . . . . . . . . . . . . . . . . . . . . 5

. . . . . . . . . . . . . . . . . 5

. . . . . . . . . . . . . . . . . . . . . . . . . . 5

. . . . . . . . . . . . . . . . . . . . 5

. . . . . . . . . . . . 5

. . . . . . . 5

. . . . . . . . . . . . . . . . . . . . . . . . 5

. . . . . . . . . . . . . . . . 5

. . . . . . . . . . . . . . 5

. . . . . . . . . . . . . . . . . . . . . . . . . 6

. . . . . . . . . . . . . . . . . . . 6

. . . . . . . . . . . . . . . . . . . . . . . . 6

. . . . . . . . . . . . . . . . . . . . . . . . . 6

. . . . . . . . . . . . . . . . . . . . 6

. . . . . . . . . . . . . . 6

. . . . . . . . . . . . . . . . . . . 7

7

. . . . . . . . . . . . . . . . . . . . . . . 8

. . . . . . . . . . . . . . . 8

. . . . . . . . 8

. . . . . . . . . . . . . . . . . . . . . . . 9