Headings in ms (The GNU Troff Manual)

#### 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 Keeps, boxed keeps, and displays and Tables, figures, equations, and references.