Groff_ms (7) Linux Manual Page

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

will cause “1. Top Level Heading” to be printed in 13pt bold text, followed by “1.1. Second Level Heading” in 11.5pt bold text, while “1.1.1. Third Level Heading”, and all more deeply nested heading levels, will remain in the 10pt bold text which is specified by the PS register.

Note that the value stored in PSINCR is interpreted in groff basic units; the p scaling factor should be employed when assigning a value specified in points.

The style used to represent the section number, within a numbered heading, is controlled by the SN-STYLE string; this may be set to either the SN-DOT or the SN-NO-DOT style, (described below), by aliasing SN-STYLE accordingly. By default, SN-STYLE is initialised by defining the alias


.als SN-STYLE SN-DOT

it may be changed to the SN-NO-DOT style, if preferred, by defining the alternative alias


.als SN-STYLE SN-NO-DOT

Any such change becomes effective with the first use of .NH, after the new alias is defined.

After invoking .NH, the assigned heading number is available in the strings SN-DOT (as it appears in the default formatting style for numbered headings, with a terminating period following the number), and SN-NO-DOT (with this terminating period omitted). The string SN is also defined, as an alias for SN-DOT; if preferred, the user may redefine it as an alias for SN-NO-DOT, by including the initialisation:


.als SN SN-NO-DOT

at any time; the change becomes effective with the next use of .NH, after the new alias is defined.

.SH

[xx] Unnumbered subheading. The use of the optional xx argument is a GNU extension, which adjusts the point size of the unnumbered subheading to match that of a numbered heading, introduced using .NH xx with the same value of xx. For example, given the same settings for PS, GROWPS and PSINCR, as used in the preceding .NH example, the sequence:


.SH 2
An Unnumbered Subheading

will print “An Unnumbered Subheading” in 11.5pt bold text.

Highlighting

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

.B

[txt [post [pre]]] Sets its first argument in bold type. If you specify a second argument, groff prints it in the previous font after the bold text, with no intervening space (this allows you to set punctuation after the highlighted text without highlighting the punctuation). Similarly, it prints the third argument (if any) in the previous font before the first argument. For example,

.B foo ) (

prints “(foo)”.

If you give this macro no arguments, groff prints all text following in bold until the next highlighting, paragraph, or heading macro.

.R

[txt [post [pre]]] Sets its first argument in roman (or regular) type. It operates similarly to the B macro otherwise.

.I

[txt [post [pre]]] Sets its first argument in italic type. It operates similarly to the B macro otherwise.

.CW

[txt [post [pre]]] Sets its first argument in a constant-width face. It operates similarly to the B macro otherwise.

.BI

[txt [post [pre]]] Sets its first argument in bold italic type. It operates similarly to the B macro otherwise.

.BX

[txt] Prints its argument and draws a box around it. If you want to box a string that contains spaces, use a digit-width space (

groff_ms (7) Linux Manual Page