File: groff.info,  Node: Headings in ms,  Next: Typeface and decoration,  Prev: Paragraphs in ms,  Up: ms Body Text

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.  *Note ms keeps and displays:: and *note ms
Insertions::.