Using groff with the -ms Macro Package

Larry Kollar
kollar@alltel.net

This document describes the GNU re-implementation of the popular groff -ms macro package.

The -ms macros are suitable for reports, letters, books, user manuals, and so forth. The package provides macros for cover pages, section headings, paragraphs, lists, footnotes, pagination, and a table of contents.

This document provides both tutorial and reference material. It also discusses differences from the AT&T -ms macros, both omissions and additions.

1. Introduction

The original -ms macros were included with AT&T troff as well as the -man macros. While the -man package is intended for brief documents that can be read on-line as well as printed, the -ms macros are suitable for longer documents that are meant to be printed rather than read on-line.

The -ms macro package included with -groff is a complete, bottom-up re-implementation. Several macros (specific to AT&T or Berkeley) are not included, while several new commands are. See Differences from AT&T -ms, later in this document, for more information.

1.1. Basic information

Most number registers have a default unit of measurement. Specifying a unit explicitly does not cause any problems, and can avoid problems in complex situations. The following are typical units:

You set number registers by using the .nr request; for example:

.nr PS 12

2 v0.1, April 2001

2. General structure of an -ms document

The -ms macro package expects a certain amount of structure, but not as much as packages such as -man or -mdoc.

The simplest documents can begin with a paragraph macro (such as .LP or .PP), and consist of text separated by paragraph macros or even blank lines. Longer documents have a structure as follows:

If you invoke the .RP (report) macro on the first line of the document, groff prints the cover page information on its own page; otherwise it prints the information on the first page with your document text immediately following. Other document formats found in AT&T troff are specific to AT&T or Berkeley, and are not supported in groff.

By setting number registers, you can change your document’s type (font and size), margins, spacing, headers and footers, and footnotes. See Document control registers below for more details.

A cover page consists of a title, the author’s name and institution, an abstract, and the date. 1

Actually, only the title is required.

See Cover page macros below for more details.

Following the cover page is your document. You can use the -ms macros to write reports, letters, books, and so forth. The package is designed for structured documents, consisting of paragraphs interspersed with headings and augmented by lists, footnotes, tables, and other common constructs. See Body text below for more details.

Longer documents include a table of contents, which you can invoke by placing the .TC macro at the end of your document. 2

The -ms macros have minimal indexing facilities, consisting of the .IX macro, which prints an entry on standard error.

Printing the table of contents at the end is necessary since groff is a single-pass text formatter, thus it cannot determine the page number of each section until that section has actually been set and printed. Since -ms output was intended for hardcopy, the standard procedure was to manually relocate the pages containing the table of contents between the cover page and the body text.

Using groff with the -ms macros 3

3. Document control registers

The following table lists the document control number registers. For the sake of consistency, set registers related to margins at the beginning of your document, or just after the .RP macro. You can set other registers later in your document, but you should keep them together at the beginning to make them easy to find and edit as necessary.

4 v0.1, April 2001

4. Cover page macros

Use the following macros to create a cover page for your document in the order shown.

The following is example mark-up for a title page.

Using groff with the -ms macros 5

5. Body text

This section describes macros used to mark up the body of your document. Examples include paragraphs, sections, and other groups.

5.1. Paragraphs

Use the .PP macro to create indented paragraphs (like the next paragraph), and the .LP macro to create paragraphs with no initial indent (like this one).

The .QP macro indents its text at both left and right margins. The effect is identical to the HTML <BLOCKQUOTE> element. The next paragraph or heading returns margins to normal.

The following markup uses all three paragraph macros.

5.2. Headings

Use headings to create a hierarchical structure for your document. The -ms macros print headings in bold, using the same font family and point size as the body text.

The following table describes the heading macros:

5.3. Highlighting

The -ms macros provide a variety of methods to highlight or emphasize text:

5.4. Lists

The .IP macro handles duties for all lists. Its syntax is as follows:

.IP [marker [width]]

The marker is usually a bullet character (\(bu) for unordered lists, a number (or auto-incrementing number register) for numbered lists, or a word or phrase for indented (glossary-style) lists.

The width specifies the indent for the body of each list item. Once specified, the indent remains the same for all list items in the document until specified again.

The following are examples of each type of list:

In the last example, note how the .IP macro places the definition on the same line as the term if it has enough space. This may or may not be the effect you want. The following example shows two possible workarounds:

The first example uses the .br request to force a break after printing the term or label. The second example uses the \p escape to do the same thing. Note the space following the escape; this is important. If you omit the space, groff prints the first word on the same line as the term or label (if it fits) then breaks the line.

To set nested lists, use the .RS and .RE macros. These macros begin and end a section indented to line up with the body of an .IP macro. For example:

5.5. Displays and keeps

Use displays to show text-based examples or figures (such as code listings). This document shows groff code examples inside displays, for example.

Displays turn off filling, so lines of code can be displayed as-is without inserting .br requests in between each line. Displays can be kept on a single page, or allowed to break across pages. The following table shows the display types available.

Use the .DE macro to end any display type.

On occasion, you may want to keep other text together on a page. For example, you may want to keep two paragraphs together, or a paragraph that refers to a table (or list, or other item) immediately following. The -ms macros provide the .KS and .KE macros for this purpose. The .KS macro begins a block of text to be kept on a single page, and the .KE macro ends the block.

You can specify a floating keep; if the keep cannot fit on the current page, groff holds the contents of the keep and allows text following the keep (in the source file) to fill in the remainder of the current page. When the page breaks, whether by an explicit .bp request or by reaching the end of the page, groff prints the floating keep at the top of the new page. This is useful for printing large graphics or tables that do not need to appear exactly where specified. Use the .KF and .KE macros to specify a floating keep.

You can also use the .ne request to force a page break if there is not enough vertical space remaining on the page.

5.6. Tables, figures, equations, and references

The -ms macros support the standard groff preprocessors: tbl, pic, eqn, and refer. You mark text meant for preprocessors by enclosing it in pairs of tags as follows:

5.6.1. An example multi-page table

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

5.7. Footnotes

The -ms macro package has a flexible footnote system. You can specify a numbered footnote 3

This is a numbered footnote.

by using the \** escape, followed by the text of the footnote enclosed by .FS and .FE macros.

You can specify symbolic footnotes†

†This is a symbolic footnote.

by placing the character (such as \(dg for the dagger character used here), followed by the symbol and the text of the footnote enclosed by .FS and .FE macros.

You can control how groff prints footnote numbers by changing the
value of the FF register as follows:

6. Page layout

The default output from the -ms macros provides a minimalist page layout: it prints a single column, with the page number centered at the top of each page. It prints no footers.

You can change the layout by setting the proper number registers and strings.

6.1. Headers and footers

There are two ways to define headers and footers:

.OH ’left’center’right’

You can replace the quote (’) marks with any character not appearing in the header or footer text.

6.2. Margins

You control margins using a set of number registers. The following table lists the register names and defaults:

Note that there is no right margin setting. The combination of page offset and line length provide the information necessary to derive the right margin.

6.3. Multiple columns

The -ms macros can set text in as many columns as will reasonably fit on the page. The following macros are available. All of them force a page break if a multi-column mode is already set. However, if the current mode is single-column, starting a multi-column mode does not force a page break.

6.4. Creating a table of contents

The facilities in the -ms macro package for creating a table of contents are semi-automated at best. Assuming that you want the table of contents to consist of the document’s headings, you need to repeat those headings wrapped in .XS and .XE macros.

In addition, the .XS macro does not know to indent a heading based on its level. The easiest way to work around this is to add tabs to the table of contents string. The following is an example:

The Groff and Friends HOWTO includes a sed script that automatically inserts .XS and .XE entries after each heading in a document.

Altering the .NH macro to automatically build the table of contents is perhaps initially more difficult, but would save a great deal of time in the long run if you use -ms regularly.

7. Differences from AT&T -ms

This section lists the (minor) differences between the groff -ms macros and AT&T troff -ms macros.

7.1. troff macros not appearing in groff

Macros missing from groff -ms are cover page macros specific to Bell Labs. The macros known to be missing are:

7.2. groff macros not appearing in AT&T troff

The groff -ms macros have a few minor extensions compared to the AT&T troff -ms macros.

The MINGW number register specifies a minimum space between columns (for multi-column output); this takes the place of the GW register that was documented but apparently not implemented in AT&T troff. Several new string registers are available as well. You can change these to handle (for example) the local language.

Contains the string printed at the beginning of the references (bibliography) page.

Contains the string printed at the beginning of the abstract.

Contains the string printed at the beginning of the table of contents.

6 v0.1, April 2001

8. Acknowledgements

Two documents provided essential reference material:

Without these documents close at hand, writing this document would have been a much more difficult task.

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

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

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

. . . . . . . . . . 5

. . . . . . . . 5

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