Headings in ms (The GNU Troff Manual)

+Next: Typeface and decoration, Previous: Paragraphs, Up: Body Text [Contents][Index]

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. +

+ +