groff_ms(7) — Linux manual page

Name | Synopsis | Description | Usage | Differences from troff ms | Naming Conventions | Files | Authors | See also | COLOPHON

groff_ms(7)         Miscellaneous Information Manual         groff_ms(7)

Name         top

       groff_ms - GNU roff manuscript macro package for formatting

Synopsis         top

       groff -ms [option ...] [input-file ...]
       groff -m ms [option ...] [input-file ...]

Description         top

       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

Usage         top

       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 call the RP macro at the beginning of the document,
              groff prints the document description on its own page;
              otherwise it prints the information (if any) on the first
              page with your document text immediately following.  Some
              document types found in other ms implementations are
              specific to AT&T or Berkeley, and are not supported in
              groff ms.

       Format and layout
              By setting registers and strings, you can change your
              document's margins, spacing, headers and footers,
              footnotes, and the base point size for the text.  See
              subsection “Document control settings” below.

       Document description
              A document description consists of any of: a title, one or
              more authors' names and affiliated institutions, an
              abstract, and a date or other identifier.  See subsection
              “Document description macros” below.

       Body   The main matter of your document follows its description
              (if any).  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 settings
       The following tables list the document control registers and
       strings.  For the sake of consistency, set parameters related to
       margins at the beginning of your document, or just after the RP

                                Margin settings
       Parameter           Definition             Effective      Default
       \n[PO]      Page offset (left margin)    next page        1i

       \n[LL]      Line length                  next paragraph   6i
       \n[LT]      Header/footer length         next paragraph   6i
       \n[HM]      Top (header) margin          next page        1i
       \n[FM]      Bottom (footer) margin       next page        1i

                                 Text settings
       Parameter           Definition             Effective      Default
       \n[PS]      Point size                   next paragraph   10p
       \n[VS]      Line spacing (leading)       next paragraph   12p
       \n[HY]      Hyphenation mode             next paragraph   6
       \*[FAM]     Font family                  next paragraph   T

                               Paragraph settings
        Parameter            Definition            Effective      Default
       \n[PI]         Initial indent             next paragraph   5n
       \n[PD]         Space between paragraphs   next paragraph   0.3v
       \n[QI]         Quoted paragraph indent    next paragraph   5n
       \n[PORPHANS]   # of initial lines kept    next paragraph   1

                                 Heading settings
        Parameter            Definition            Effective      Default
       \n[PSINCR]     Point size increment        next heading   1p
       \n[GROWPS]     Size increase level limit   next heading   0
       \n[HORPHANS]   # of following lines kept   next heading   1
       \*[SN-STYLE]   Numbering style (alias)     next heading   \*[SN-DOT]

       \*[SN-STYLE] can alternatively be made an alias of \*[SN-NO-DOT]
       with the als request.

                               Footnote settings
       Parameter          Definition             Effective      Default
       \n[FI]      Indentation                 next footnote   2n
       \n[FF]      Format                      next footnote   0
       \n[FPS]     Point size                  next footnote   \n[PS]-2
       \n[FVS]     Vertical spacing            next footnote   \n[FPS]+2
       \n[FPD]     Paragraph spacing           next footnote   \n[PD]/2
       \*[FR]      Line length ratio           special         11/12

       Changes to the footnote line length ratio \*[FR] take effect with
       the next footnote written in single-column arrangements, but on
       the next page in multiple-column contexts.

                                Other settings
       Parameter           Definition             Effective      Default
       \n[DD]      Display distance (spacing)   next paragraph   0.5v
       \n[MINGW]   Minimum gutter width         next page        2n

       The \n[DD] distance used before and after each pair of display
       macros is also applied to regions of the document preprocessed
       with eqn(1), pic(1), and tbl(1).  The “gutter” affected by
       \n[MINGW] is the gap between columns in multiple-column page

   Document description macros
       Define information describing the document by using the macros
       below in the order shown; .DA or .ND can be called to set the
       document date (or other identifier) at any time before (a) the
       abstract, if present, or (b) the end of the first page.  Use of
       these macros is optional, except that .TL is mandatory if any of
       .RP, .AU, .AI, or .AB is called, and .AE is mandatory if .AB is

       .RP [no]
              Use the “report” (AT&T: “released paper”) format for your
              document, creating a separate cover page.  The default
              arrangement is to print most of the document description
              (title, author names and institutions, and abstract, but
              not the date) at the top of page 1.

              If the optional no argument is given, ms prints a cover
              page but does not repeat any of its information on page 1
              (but see the DA macro below regarding the date).

       .TL    Specify the document title.  ms collects text on input
              lines following a call to this macro into the title until
              reaching an .AU, .AB, or heading or paragraph macro call.

       .AU    Specify an author's name.  ms collects text on input lines
              following a call to this macro into the author's name
              until reaching an .AI, .AB, or heading or paragraph macro.
              Call .AU repeatedly to specify multiple authors.

       .AI    Specify the preceding author's institution.  An .AU call
              is usefully followed by at most one .AI call; if there are
              more, the last .AI call controls.  ms collects text on
              input lines following a call to this macro into the
              author's institution until reaching an .AU, .AB, or
              heading or paragraph macro call.

       .DA [x ...]
              Print the current date, or any arguments x, in footers,
              and, if .RP is also called, left-aligned after other
              document description information on the cover page.

       .ND [x ...]
              Print the current date, or any arguments x, if .RP is also
              called, left-aligned after other document description
              information on the cover page, but not in footers.

       .AB [no]
              Begin the abstract.  ms collects text on input lines
              following a call to this macro into the abstract until
              reaching an .AE call.  By default, ms places the word
              “ABSTRACT” centered and in italics above the text of the
              abstract.  The optional argument no suppresses this

       .AE    End the abstract.

       Several paragraph types are available, differing in how
       indentation is applied: to left, right, or both margins; to the
       first output line of the paragraph, all output lines, or all but
       the first.  All paragraphing macro calls cause the insertion of
       vertical space in the amount stored in the PD register, except at
       page breaks.

       The PORPHANS register defines the minimum number of initial lines
       of any paragraph that must be kept together to avoid orphaned
       lines at the bottom of a page.  If a new paragraph is started
       close to the bottom of a page, and there is insufficient space to
       accommodate \n[PORPHANS] lines before an automatic page break,
       then a page break is forced before the start of the paragraph.
       This is a GNU extension.

       .LP    Set a paragraph without any (additional) indentation.

       .PP    Set a paragraph with a first-line left indentation in the
              amount stored in the PI register.

       .IP [marker [width]]
              Set a paragraph with a left indentation.  The optional
              marker is not indented and is empty by default.  width
              overrides the default indentation amount of \n[PI]; its
              default unit is “n”.  Once specified, width applies to
              further .IP calls until specified again or a different
              paragraphing macro is called.

       .QP    Set a paragraph indented from both left and right margins
              by \n[PI].  This is a Berkeley extension.

       .QE    Begin (QS) and end (QE) a region where each paragraph is
              indented from both margins by \n[QI].  The text between
              .QS and .QE can be structured further by use of other
              paragraphing macros.  These macros are GNU extensions.

       .XP    Set an “exdented” paragraph—one with a left indentation of
              \n[PI] on every line except the first (also known as a
              hanging indent).  This is a Berkeley extension.

       Use headings to create a hierarchical structure for your
       document.  The ms macros print headings in bold using the same
       font family and, by default, point size as the body text.
       Numbered and unnumbered headings are available.  Text lines after
       heading macros are treated as part of the heading, rendered on
       the same output line in the same style.

       .NH level
              Numbered heading.  The level argument instructs ms to
              number heading in the form a.b.c..., to any depth desired,
              with the numbering of each level increasing automatically
              and being reset when a more significant level is
              increased.  “1” is the most significant or coarsest
              division of the document.  Only nonzero values are output.
              If you specify heading levels with a gap in an ascending
              sequence, such as by invoking “.NH 3” after “.NH 1”, groff
              ms emits a warning on the standard error stream.

       .NH S heading-level-index ...
              Alternatively, a first argument of “S” can be given,
              followed by integral arguments to number the levels of the
              heading explicitly.  Further automatic numbering, if used,
              resumes using the specified heading level indices as their
              predecessors.  This feature is a GNU extension.

       After invocation of .NH, 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).

       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 alias it to \*[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].

       .SH [level]
              Unnumbered heading.  The optional level argument is a GNU
              extension indicating the heading level corresponding to
              the level argument of .NH.  It matches the point size at
              which the heading is printed to that of a numbered heading
              at the same level when the \n[GROWPS] and \n[PSINCR]
              heading size adjustment mechanism is in effect.

       The PSINCR register defines an increment in point size to be
       applied to headings at nesting levels more significant
       (numerically less) than the value specified in \n[GROWPS].  The
       value of \n[PSINCR] should be specified in points with the “p”
       scaling indicator and may include a fractional component.

       The GROWPS register defines the heading level at which the point
       size increment set by \n[PSINCR] becomes effective.  Headings
       more significant (numerically less) than that specified by
       \n[GROWPS] are printed at the point size set by \n[PS]; for each
       level below the value of \n[GROWPS], the point size is increased
       by \n[PSINCR].  Setting \n[GROWPS] to a value less than 2
       disables the incremental heading size feature.

       In other words, if the GROWPS register is greater than the level
       argument to a .NH or .SH call, the point size of a heading
       produced by these macros increases by \n[PSINCR] units over
       \n[PS] multiplied by the difference between level and \n[GROWPS].

       The \n[HORPHANS] register operates in conjunction with the NH and
       SH macros to inhibit the printing of orphaned headings at the
       bottom of a page; it specifies the minimum number of lines of the
       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 or tbl, pic, or eqn region between the heading and
       the subsequent paragraph suppresses this grouping.

       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.

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

       .CW [txt [post [pre]]]
              Sets its first argument in a “constant-width” (monospaced)
              roman typeface.  It operates similarly to the B macro
              otherwise.  This is a Version 10 Research Unix extension.

       .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 (\0).

       .UL [txt [post]]
              Prints its first argument with an underline.  If you
              specify a second argument, groff prints it in the previous
              font after the underlined text, with no intervening space.

       .LG    Prints all text following in larger type (2 points larger
              than the current point size) until the next font size,
              highlighting, paragraph, or heading macro.  You can
              specify this macro multiple times to enlarge the point
              size as needed.

       .SM    Prints all text following in smaller type (2 points
              smaller than the current point size) until the next type
              size, highlighting, paragraph, or heading macro.  You can
              specify this macro multiple times to reduce the point size
              as needed.

       .NL    Prints all text following in the normal point size (that
              is, the value of the PS register).

              Print the enclosed text as a superscript.

              Print the enclosed text as a subscript.

   Indented regions
       You may need to indent a region of text while still wrapping and

       .RS    Begin a region indented by \n[PI], affecting the placement
              of headings, paragraphs, and displays.

       .RE    End the most recent indented region.

       You can use .RS/ .RE regions to line up text under hanging and
       indented paragraphs.  For example, you may wish to nest lists.

   Tab stops
       Use the ta request to set tab stops as needed.  Use the TA macro
       to reset tabs to the default (every 5n).  You can redefine the TA
       macro to create a different set of default tab stops.

   Displays and keeps
       Use displays to show text-based examples or figures (such as code
       listings).  Displays turn off filling, so lines of code can be
       displayed as-is without inserting br requests in between each
       line.  Displays can be kept on a single page, or allowed to break
       across pages.  The following table shows the display types

                   Display macro                 Type of display
                With keep      No keep
              .DS L            .LD       Left-justified.
              .DS I [indent]   .ID       Indented (default indent in the
                                         DI register).
              .DS B            .BD       Block-centered (left-justified,
                                         longest line centered).
              .DS C            .CD       Centered.

              .DS R            .RD       Right-justified.

       Use the DE macro to end any display type.

       To keep text together on a page, such as a paragraph that refers
       to a table (or list, or other item) immediately following, use
       the KS and KE macros.  The KS macro begins a block of text to be
       kept on a single page, and the KE macro ends the block.

       You can specify a floating keep using the KF and KE macros.  If
       the keep cannot fit on the current page, groff holds the contents
       of the keep and allows text following the keep (in the source
       file) to fill in the remainder of the current page.  When the
       page breaks, whether by an explicit bp request or by reaching the
       end of the page, groff prints the floating keep at the top of the
       new page.  This is useful for printing large graphics or tables
       that do not need to appear exactly where specified.

       The macros B1 and B2 can be used to enclose a text within a box;
       .B1 begins the box, and .B2 ends it.  Text in the box is
       automatically placed in a diversion (keep).

   Tables, figures, equations, and references
       The ms macros support the standard groff preprocessors: tbl, pic,
       eqn, and refer(1).  Mark text meant for preprocessors by
       enclosing it in pairs of tags as follows.

       .TS [H] and .TE
              Denote a table to be processed by the tbl preprocessor.
              The optional H argument instructs groff to create a
              running header with the information up to the TH macro.
              groff prints the header at the beginning of the table; if
              the table runs onto another page, groff prints the header
              on the next page as well.

       .PS and .PE
              Denote a graphic to be processed by the pic preprocessor.
              You can create a pic file by hand, using the AT&T pic
              manual available on the Web as a reference, or by using a
              graphics program such as xfig.

       .EQ [align] and .EN
              Denote an equation to be processed by the eqn
              preprocessor.  The optional align argument can be C, L,
              or I to center (the default), left-justify, or indent the
              equation, respectively.

       .[ and .]
              Denote a reference to be processed by the refer
              preprocessor.  The GNU refer(1) manual page provides a
              comprehensive reference to the preprocessor and the format
              of the bibliographic database.

       Attempting to place a multi-page table inside a keep can lead to
       unpleasant results, particularly if the tblallbox” option is

       The ms macros provide a flexible footnote system.  You can
       specify a numbered footnote by using the \** escape, followed by
       the text of the footnote enclosed by FS and FE macros.

       You can specify symbolic footnotes by placing the mark character
       (such as \[dg] for the dagger character) in the body text,
       followed by the text of the footnote enclosed by FS \[dg] and FE

       You can control how ms prints footnote numbers by changing the
       value of the FF register as follows.

              0      Prints the footnote number as a superscript and
                     indents the footnote (default).

              1      Prints the number followed by a period (that
                     is, “1.”) and indents the footnote.

              2      Like 1, without an indent.

              3      Like 1, but prints the footnote number as a
                     paragraph with a hanging indent.

       You can use footnotes safely within keeps and displays, but avoid
       using numbered footnotes within floating keeps.  You can set a
       second \** between a \** and its corresponding .FS, as long as
       each .FS occurs after the corresponding \** and the occurrences
       of .FS are in the same order as the corresponding occurrences of

   Headers and footers
       There are three ways to define headers and footers:

       •  Use the strings LH, CH, and RH to set the left, center, and
          right headers.  Use LF, CF, and RF to set the left, center,
          and right footers.  The string-setting approach works best for
          documents that do not distinguish between odd and even pages.

       •  Use the OH and EH macros to define headers for the odd and
          even pages, and OF and EF macros to define footers for the odd
          and even pages.  This is more flexible than defining the
          individual strings.  The syntax for these macros is as

                 .XX 'left'center'right'

          where XX is one of the foregoing four macros and each of left,
          center, and right is text of your choice.  You can replace the
          quote (') marks with any character not appearing in the header
          or footer text.

          Print the header on page 1.  By default, no header is printed
          on that page.  This is a Berkeley extension.

       •  You can redefine the PT and BT macros to change the behavior
          of the header and footer, respectively.  The header process
          also calls the (undefined) HD macro after PT; you can define
          this macro if you need additional processing after printing
          the header (for example, to draw a line below the header).

       Control margins using registers.  These are summarized in the
       “Margin settings” table in subsection “Document control settings”
       above.  There is no right margin setting; the combination of page
       offset and line length provide the information necessary to
       derive the right margin.

   Multiple columns
       The ms macros can set text in as many columns as will reasonably
       fit on the page.  The following macros are available.  All of
       them force a page break if a multi-column mode is already set.
       However, if the current mode is single-column, starting a multi-
       column mode does not force a page break.

       .1C    Single-column mode.

       .2C    Two-column mode.

       .MC [column-width [gutter-width]]
              Multi-column mode.  If you specify no arguments, it is
              equivalent to the 2C macro.  Otherwise, column-width is
              the width of each column and gutter-width is the space
              between columns.  The MINGW register is the default gutter

   Creating a table of contents
       Wrap text that you want to appear in the table of contents in XS
       and XE macros.  Use the TC macro to print the table of contents
       at the end of the document, resetting the page number to i (Roman
       numeral 1).

       You can manually create a table of contents by specifying a page
       number as the first argument to XS.  Add subsequent entries using
       the XA macro.  For example:

              .XS 1
              .XA 2
              A Brief History of the Universe
              .XA 729
              Details of Galactic Formation

       Use the PX macro to print a manually-generated table of contents
       without resetting the page number.

       If you give the argument no to either PX or TC, groff suppresses
       printing the title specified by the \*[TOC] string.

   Fractional point sizes
       Traditionally, the ms macros only support integer values for the
       document's font size and vertical spacing.  To overcome this
       restriction, values larger than or equal to 1000 are taken as
       fractional values, multiplied by 1000.  For example,
       ‘.nr PS 10250’ sets the font size to 10.25 points.

       The following four registers accept fractional point sizes: PS,
       VS, FPS, and FVS.

Differences from troff ms         top

       The groff ms macros are a complete re-implementation, using no
       original AT&T code.  Since they take advantage of the extended
       features in groff, they cannot be used with AT&T troff.  Other
       differences include:

       •  The internals of groff ms differ from the internals of Unix
          ms.  Documents that depend upon implementation details of Unix
          ms may not format properly with groff ms.

       •  The error-handling policy of groff ms is to detect and report
          errors, rather than silently to ignore them.

       •  Berkeley localisms, in particular the TM and CT macros, are
          not implemented.

       •  (Version 10 Research Unix supported a pair of P1 and P2 macros
          for setting code examples; groff ms does not.)

       •  groff ms does not work in compatibility mode (e.g., with the
          -C option).

       •  There is no support for typewriter-like devices.

       •  groff ms does not provide cut marks.

       •  Multiple line spacing is not supported (use a larger vertical
          spacing instead).

       •  Some Unix ms documentation says that the CW and GW registers
          can be used to control the column width and gutter width,
          respectively.  These registers are not used in groff ms.

       •  Macros that cause a reset (paragraphs, headings, etc.) may
          change the indent.  Macros that change the indent do not
          increment or decrement the indent, but rather set it
          absolutely.  This can cause problems for documents that define
          additional macros of their own.  The solution is to use not
          the in request but instead the RS and RE macros.

       •  The register GS is set to 1 by the groff ms macros, but is not
          used by the Unix ms macros.  Documents that need to determine
          whether they are being formatted with Unix ms or groff ms
          should use this register.

       •  To make groff ms use the default page offset (which also
          specifies the left margin), the PO register must stay
          undefined until the first ms macro is evaluated.  This implies
          that PO should not be used early in the document, unless it is
          changed also: remember that accessing an undefined register
          automatically defines it.

   Localization strings
       You can redefine the following strings to adapt the groff ms
       macros to languages other than English.

                String          Default
              REFERENCES   References
              ABSTRACT     ABSTRACT
              TOC          Table of Contents
              MONTH1       January
              MONTH2       February
              MONTH3       March
              MONTH4       April
              MONTH5       May
              MONTH6       June
              MONTH7       July
              MONTH8       August
              MONTH9       September
              MONTH10      October
              MONTH11      November
              MONTH12      December

       The \*- string produces an em dash—like this.

       Use \*Q and \*U to get a left and right typographer's quote,
       respectively, in troff (and plain quotes in nroff).

   Text settings
       The FAM string sets the default font family.  If this string is
       undefined at initialization, it is set to Times.

       The point size, vertical spacing, and inter-paragraph spacing for
       footnotes are controlled by the registers FPS, FVS, and FPD; at
       initialization these are set to \n(PS-2, \n[FPS]+2, and \n(PD/2,
       respectively.  If any of these registers are defined before
       initialization, the initialization macro does not change them.

       The hyphenation flags (as set by the hy request) are set from the
       HY register; the default is 6.

       Improved accent marks (as originally defined in Berkeley's ms
       version) are available by specifying the AM macro at the
       beginning of your document.  You can place an accent over most
       characters by specifying the string defining the accent directly
       after the character.  For example, n\*~ produces an n with a
       tilde over it.

Naming Conventions         top

       The following conventions are used for names of macros, strings,
       and registers.  External names available to documents that use
       the groff ms macros contain only uppercase letters and digits.

       Internally the macros are divided into modules; naming
       conventions are as follows:

       •  Names used only within one module are of the form module*name.

       •  Names used outside the module in which they are defined are of
          the form module@name.

       •  Names associated with a particular environment are of the form
          environment:name; these are used only within the par module.

       •  name does not have a module prefix.

       •  Constructed names used to implement arrays are of the form

       Thus the groff ms macros reserve the following names:

       •  Names containing the characters *, @, and :.

       •  Names containing only uppercase letters and digits.

Files         top

              groff implementation of manuscript macros.

              Wrapper to load s.tmac.

Authors         top

       The GNU version of the ms macro package was written by James
       Clark and contributors.  This document was (re-)written by Larry
       Kollar ⟨⟩.

See also         top

       A manual is available in source and rendered form.  On your
       system, it may be compressed and/or available in additional

              “Using groff with the ms Macro Package”; Larry Kollar.

       Groff: The GNU Implementation of troff, by Trent A. Fisher and
       Werner Lemberg

       groff(1), troff(1), tbl(1), pic(1), eqn(1), refer(1)

COLOPHON         top

       This page is part of the groff (GNU troff) project.  Information
       about the project can be found at 
       ⟨⟩.  If you have a bug report
       for this manual page, see ⟨⟩.
       This page was obtained from the project's upstream Git repository
       ⟨⟩ on 2021-04-01.  (At
       that time, the date of the most recent commit that was found in
       the repository was 2021-03-29.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to

groff 1.23.0.rc1.259-531129-dir1tyApril 2021                   groff_ms(7)

Pages that refer to this page: groff(1)groff_tmac(5)groff(7)