4.6.5.4 Headings

Use headings to create a sequential or 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.

Macro: .NH [depth]

Macro: .NH S heading-depth-index …

Set an automatically numbered heading.

ms produces a numbered heading the form a.b.c…, to any depth desired, with the numbering of each depth increasing automatically and being reset to zero when a more significant level is increased. “1” is the most significant or coarsest division of the document. Only non-zero values are output. If depth is omitted, it is taken to be ‘1’.

If you specify depth such that an ascending gap occurs relative to the previous NH call—that is, you “skip a depth”, as by ‘.NH 1’ and then ‘.NH 3’—groff ms emits a warning on the standard error stream.

Alternatively, you can give NH a first argument of S, followed by integers to number the heading depths explicitly. Further automatic numbering, if used, resumes using the specified indices as their predecessors. This feature is a Berkeley extension.

An example may be illustrative.

.NH 1
Animalia
.NH 2
Arthropoda
.NH 3
Crustacea
.NH 2
Chordata
.NH S 6 6 6
Daimonia
.NH 1
Plantae

The above results in numbering as follows; the vertical space that normally precedes each heading is omitted.

1.  Animalia
1.1.  Arthropoda
1.1.1.  Crustacea
1.2.  Chordata
6.6.6.  Daimonia
7.  Plantae

String: \*[SN-STYLE]

String: \*[SN-DOT]

String: \*[SN-NO-DOT]

String: \*[SN]

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.

.als SN-STYLE 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 the SN string (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.

Macro: .SH [depth]

Set an unnumbered heading.

The optional depth argument is a GNU extension indicating the heading depth corresponding to the depth argument of NH. It matches the type size at which the heading is set to that of a numbered heading at the same depth when the GROWPS and PSINCR heading size adjustment mechanism is in effect.

If the GROWPS register is set to a value greater than the level argument to NH or SH, the type size of a heading produced by these macros increases by PSINCR units over the size specified by PS multiplied by the difference of GROWPS and level. The value stored in PSINCR is interpreted in groff basic units; the p scaling unit should be employed when assigning a value specified in points. For example, the sequence

.nr PS 10
.nr GROWPS 3
.nr PSINCR 1.5p
.NH 1
Carnivora
.NH 2
Felinae
.NH 3
Felis catus
.SH 2
Machairodontinae

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 heading levels will remain in the 10-point text specified by the PS register. “Machairodontinae” is printed at 11.5 points, since it corresponds to heading level 2.

The 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 an immediately 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. See ms keeps and displays and ms Insertions.