groff_ms(7)

groff_ms – GNU roff manuscript macro package for formatting documents

Synopsis

[option …] [input-file …] [option …] [input-file …]

Description

This manual page describes the GNU version of the ms macros, part of the groff typesetting system. The ms macros are mostly compatible with the documented behavior of the 4.3 BSD Unix ms macros (see Differences from troff ms below for details). The ms macros are suitable for reports, letters, books, and technical documentation.

Usage

The ms macro package expects files to have a certain amount of structure. The simplest documents can begin with a paragraph macro and consist of text separated by paragraph macros or even blank lines. Longer documents have a structure as follows:

Document type

If you use the RP (report) macro at the beginning 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 ms.

Format and layout

By setting number registers, you can change your document’s margins, spacing, headers and footers, footnotes, and the base point size for the text. See Document control registers below for more details.

Cover page

A cover page consists of a title, and optionally the author’s name and institution, an abstract, and the date. See Cover page macros below for more details.

Body

Following the cover page is your document. It consists of paragraphs, headings, and lists.

Table of contents

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

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.

Margin settings

Reg.	Definition	Effective	Default
PO	Page offset (left margin)	next page	1i
LL	Line length	next paragraph	6i
LT	Header/footer length	next paragraph	6i
HM	Top (header) margin	next page	1i
FM	Bottom (footer) margin	next page	1i

Text settings

Reg.	Definition	Effective	Default
PS	Point size	next paragraph	10p
VS	Line spacing (leading)	next paragraph	12p
PSINCR	Point size increment for section headings of increasing importance	next heading	1p
GROWPS	Heading level beyond which PSINCR is ignored	next heading	0

Paragraph settings

Reg.	Definition	Effective	Default
PI	Initial indent	next paragraph	5n
PD	Space between paragraphs	next paragraph	0.3v
QI	Quoted paragraph indent	next paragraph	5n
PORPHANS	Number of initial lines to be kept together	next paragraph	1
HORPHANS	Number of initial lines to be kept with heading	next heading	1

Footnote settings

Reg.	Definition	Effective	Default
FL	Footnote length	next footnote	[LL]*5/6
FI	Footnote indent	next footnote	2n
FF	Footnote format	next footnote	0
FPS	Point size	next footnote	[PS]-2
FVS	Vert. spacing	next footnote	[FPS]+2
FPD	Para. spacing	next footnote	[PD]/2

Other settings

Reg.	Definition	Effective	Default
DD	Display, table, eqn, pic spacing	next para.	0.5v
MINGW	Minimum width between columns	next page	2n

Cover page macros

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

.RP [no]

Specifies the report format for your document. The report format creates a separate cover page. With no RP macro, groff prints a subset of the cover page on page~1 of your document.

If you use the optional no argument, groff prints a title page but does not repeat any of the title page information (title, author, abstract, etc.) on page~1 of the document.

.P1

(P-one) Prints the header on page~1. The default is to suppress the header.

.DA

[xxx] (optional) Print the current date, or the arguments to the macro if any, on the title page (if specified) and in the footers. This is the default for nroff.

.ND

[xxx] (optional) Print the current date, or the arguments to the macro if any, on the title page (if specified) but not in the footers. This is the default for troff.

.TL

Specifies the document title. Groff collects text following the TL macro into the title, until reaching the author name or abstract.

.AU

Specifies the author’s name. You can specify multiple authors by using an AU macro for each author.

.AI

Specifies the author’s institution. You can specify multiple institutions.

.AB [no]

Begins the abstract. The default is to print the word ABSTRACT, centered and in italics, above the text of the abstract. The option no suppresses this heading.

.AE

End the abstract.

Paragraphs

Use the PP macro to create indented paragraphs, and the LP macro to create paragraphs with no initial indent.

The QP macro indents all text at both left and right margins by the amount of the register QI. The effect is reminiscent of the HTML <BLOCKQUOTE> tag. The next paragraph or heading returns the margins to normal. QP inserts the vertical space specified in register PD as inter-paragraph spacing.

A paragraph bracketed between the macros QS and QE has the same appearance as a paragraph started with QP and a following paragraph started with LP. Both QS and QE insert the inter-paragraph spacing specified in PD and the text is indented on both sides by the amount of register QI. The text between QS and QE can be split into further paragraphs by using .LP or .PP.

The XP macro produces an “exdented” paragraph; that is, one with a hanging indent. The first line of the paragraph begins at the left margin, and subsequent lines are indented (the opposite of PP).

For each of the above paragraph types, and also for any list entry introduced by the IP macro (described later), the document control register PORPHANS, sets the minimum number of lines which must be printed, after the start of the paragraph, and before any page break occurs. If there is insufficient space remaining on the current page to accommodate this number of lines, then a page break is forced before the first line of the paragraph is printed.

Similarly, when a section heading (see subsection “Headings” below) precedes any of these paragraph types, the HORPHANS document control register specifies the minimum number of lines of the paragraph which 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, then a page break is forced before the heading is printed.

Headings

Use headings to create a hierarchical structure for your document. By default, the ms macros print headings in bold using the same font family and point size as the body text. For output devices which support scalable fonts, this behaviour may be modified by defining the document control registers GROWPS and PSINCR.

The following heading macros are available:

.NH xx

Numbered heading. The argument xx is either a numeric argument to indicate the level of the heading, or S~xx~xx~… to set the section number explicitly. If you specify heading levels out of sequence, such as invoking .NH 3 after .NH 1, groff prints a warning on standard error.

If the GROWPS register is set to a value greater than the level of the heading, then the point size of the heading will be increased by PSINCR units over the text size specified by the PS register, for each level by which the heading level is less than the value of GROWPS. For example, the sequence:

.nr PS 10
.nr GROWPS 3
.nr PSINCR 1.5p
.
.NH 1
Top Level Heading
.
.NH 2
Second Level Heading
.
.NH 3
Third Level Heading