groff_diff(7) — Linux manual page

Name | Description | Language | Intermediate Output Format | Implementation Differences | Authors | See Also | COLOPHON

groff_diff(7)         Miscellaneous Information Manual         groff_diff(7)

Name         top

       groff_diff - differences between GNU roff and AT&T troff

Description         top

       The GNU roff text processing system, groff, is largely compatible
       with AT&T troff, the typesetting system originating in Unix systems
       of the 1970s.  At the same time, groff removes many arbitrary
       limitations and adds features, both to the language and to the
       intermediate, device-independent output format.  Differences arising
       from groff's implementation of AT&T troff features are also noted.

Language         top

       groff features identifiers of arbitrary length, supports non-integral
       point sizes, adds new escapes and requests, provides new conditional
       tests, recognizes additional scale indicators and numerical
       operators, and extends the function of some escapes and requests
       already present in AT&T troff.

   Long names
       groff introduces many new requests; with three exceptions, they all
       have names longer than two characters.  The names of number
       registers, fonts, strings/macros/diversions, environments, special
       characters (glyphs), and colors can be of any length.  More
       generally, anywhere AT&T troff supports an escape form that uses an
       opening parenthesis “(” to introduce a two-character argument, groff
       supports a square-bracketed form “[]” where the argument within can
       be of arbitrary length.

   Fractional point sizes and new scale indicators
       A scaled point is equal to 1/sizescale points, where sizescale is a
       parameter specified in the device description file, DESC, and
       defaults to 1.  A new scale indicator “z” has the effect of
       multiplying by sizescale.  Requests and escapes in groff interpret
       arguments that represent a point size as being in units of scaled
       points; that is, they evaluate such arguments using an implied
       default scale indicator of “z”.  Arguments treated in this way
       comprise those to the escapes \H and \s, to the request .ps, the
       third argument to the .cs request, and the second and fourth
       arguments to the .tkf request.

       For example, if sizescale is 1000, then a scaled point is one one-
       thousandth of a point.  The request “.ps 10.25” is synonymous with
       “.ps 10.25z” and sets the point size to 10250 scaled points, or
       10.25 points.

       Consequently, in groff, the number register \n[.s] can contain a non-
       integral point size.  The new number register \n[.ps] returns the
       point size in scaled points.

       It makes no sense to use the “z” scale indicator in a numeric
       expression whose default scale indicator is neither “u” nor “z”, so
       groff disallows this.  Similarly, it is nonsensical to use a scaling
       indicator other than “z” or “u” in a numeric expression whose default
       scale indicator is “z”, so groff disallows this as well.

       Another new scale indicator, “s”, multiplies by the number of basic
       units in a scaled point.  For instance, “\n[.ps]s” is equal to “1m”
       by definition.  Do not confuse the “s” and [lq]z” scale indicators.

       A further two new measurement units available in groff are “M”, which
       indicates hundredths of an em, and “f”, which is defined as 65536
       basic units.  The latter provides convenient fractions for color
       definitions with the .defcolor request.  For example, 0.5f equals
       32768u.

   Numeric expressions
       Spaces are permitted in a numeric expression within parentheses.
       Three new operators are available as well.

       e1>?e2 Compute the maximum of e1 and e2.

       e1<?e2 Compute the minimum of e1 and e2.

       (c;e)  Evaluate e using c as the default scaling indicator.  If c is
              missing, ignore scaling indicators in the evaluation of e.

   Conditions
       More conditions can be tested with the .if and .ie requests, as well
       as the new .while request.

       c g    True if a glyph g is available, where g is a Unicode basic
              Latin character; a groff special character \(xx or \[xxx];
              \N'xxx'; or has been defined by the .char request.

       d name True if there is a string, macro, diversion, or request called
              name.

       F font True if a font called font exists.  font is handled as if it
              were opened with the .ft request (that is, font translation
              and styles are applied), without actually mounting it.  This
              test doesn't load the complete font, but only its header, to
              verify its validity.

       m color
              True if there is a color called color.

       r reg  True if there is a number register called reg.

       S style
              True if a style called style has been registered.  Font
              translation is applied.

       v      Always false.  This condition is for compatibility with
              certain other troff implementations only.  (This refers to
              vtroff, a translator that would convert the C/A/T output from
              early-vintage AT&T troff to a form suitable for Versatec and
              Benson-Varian plotters.)

   Escape sequences
       groff introduces several new escape sequences and extends the syntax
       of a few AT&T troff escapes (namely, \D, \f, \k, \n, \$, and \*).  In
       the following list, escapes are collated alphabetically at first, and
       then by symbol roughly in Unicode code point order.

       \A'anything'
              This expands to 1 or 0, depending on whether anything is or is
              not acceptable as the name of a string, macro, diversion,
              number register, environment, font, or color.  It returns 0 if
              anything is empty.  This is useful if you want to look up user
              input in some sort of associative table.

       \B'anything'
              This expands to 1 or 0, depending on whether anything is or is
              not a valid numeric expression.  It returns 0 if anything is
              empty.

       \D'...'
              All drawing commands supported by the AT&T troff device-
              independent intermediate output format are accepted.  See
              subsection “Drawing Commands” below for GNU extensions.

       \E     This is equivalent to an escape character, but it is not
              interpreted in copy mode.  For example, strings to start and
              end superscripting could be defined like this

                     .ds { \v'-.3m'\s'\En[.s]*6u/10u'
                     .ds } \s0\v'.3m'

              The use of \E ensures that these definitions work even if \*{
              gets interpreted in copy mode (for example, by being used in a
              macro argument).

       \f[xxx]
              Set font xxx.  Additionally, \f[] is a new syntax form equal
              to \fP, i.e., to return to the previous font.

       \Ff
       \F(fm
       \F[fam]
              Change font family.  This is the same as the fam request.
              \F[] switches back to the previous font family (note that \FP
              won't work; it selects font family ‘P’ instead).

       \k(rg
       \k[reg]
              Mark horizontal position in register with two-character
              name rg or arbitrarily long name reg.

       \mx
       \m(xx
       \m[xxx]
              Set drawing color.  \m[] switches back to the previous color.

       \Mx
       \M(xx
       \M[xxx]
              Set background color for filled objects drawn with the \D'...'
              commands.  \M[] switches back to the previous color.

       \n[xxx]
              Interpolate number register xxx.

       \On
       \O[n]  Suppress troff output.  The escapes \O2, \O3, \O4, and \O5 are
              intended for internal use by grohtml.

              \O0    Disable any ditroff glyphs from being emitted to the
                     device driver, provided that the escape occurs at the
                     outer level (see \O3 and \O4).

              \O1    Enable output of glyphs, provided that the escape
                     occurs at the outer level.

                     \O0 and \O1 also reset the registers \n[opminx],
                     \n[opminy], \n[opmaxx], and \n[opmaxy] to -1.  These
                     four registers mark the top left and bottom right hand
                     corners of a box which encompasses all written glyphs.

              \O2    Provided that the escape occurs at the outer level,
                     enable output of glyphs and also write out to stderr
                     the page number and four registers encompassing the
                     glyphs previously written since the last call to \O.

              \O3    Begin a nesting level.  At start-up, troff is at outer
                     level.  This is really an internal mechanism for
                     grohtml while producing images.  They are generated by
                     running the troff source through troff to the Post‐
                     Script device and ghostscript to produce images in PNG
                     format.  The \O3 escape starts a new page if the device
                     is not html (to reduce the possibility of images cross‐
                     ing a page boundary).

              \O4    End a nesting level.

              \O5[Pfilename]
                     This escape is grohtml specific.  Provided that this
                     escape occurs at the outer nesting level, write file‐
                     name to stderr.  The position of the image, P, must be
                     specified and must be one of l, r, c, or i (left,
                     right, centered, inline).  filename is associated with
                     the production of the next inline image.

       \R'name ±n'
              This has the same effect as

                     .nr name ±n

       \s[±n]
       \s±[n]
       \s'±n'
       \s±'n' Set the point size to n scaled points; n is a numeric expres‐
              sion with a default scale indicator of z.

       \Vx
       \V(xx
       \V[xxx]
              Interpolate the contents of the environment variable xxx, as
              returned by getenv(3).  \V is interpreted in copy mode.

       \Yx
       \Y(xx
       \Y[xxx]
              This is approximately equivalent to \X'\*[xxx]'.  However the
              contents of the string or macro xxx are not interpreted; also
              it is permitted for xxx to have been defined as a macro and
              thus contain newlines (it is not permitted for the argument to
              \X to contain newlines).  The inclusion of newlines requires
              an extension to the AT&T troff output format, and confuses
              drivers that do not know about this extension.

       \Z'anything'
              Print anything and then restore the horizontal and vertical
              position; anything may not contain tabs or leaders.

       \#     Everything up to and including the next newline is ignored.
              This is interpreted in copy mode.  It is like \" except that
              \" does not ignore the terminating newline.

       \$0    The name by which the current macro was invoked.  The als
              request can make a macro have more than one name.

       \$(nn
       \$[nnn]
              In a macro or string, this gives the nn-th or nnn-th argument.
              Macros and strings can have an unlimited number of arguments.

       \$*    In a macro or string, the concatenation of all the arguments
              separated by spaces.

       \$@    In a macro or string, the concatenation of all the arguments
              with each surrounded by double quotes, and separated by spa‐
              ces.

       \$^    In a macro, the representation of all parameters as if they
              were an argument to the ds request.

       \)     Like \& except that it behaves like a character declared with
              the .cflags request to be transparent for the purposes of end-
              of-sentence recognition.

       \*[xxx arg1 arg2
              ...]  Interpolate string xxx, taking arg1, arg2, ... as argu‐
              ments.

       \/     This increases the width of the preceding glyph so that the
              spacing between that glyph and the following glyph is correct
              if the following glyph is a roman glyph.  It is a good idea to
              use this escape sequence whenever an italic glyph is immedi‐
              ately followed by a roman glyph without any intervening space.

       \,     This modifies the spacing of the following glyph so that the
              spacing between that glyph and the preceding glyph is correct
              if the preceding glyph is a roman glyph.  It is a good idea to
              use this escape sequence whenever a roman glyph is immediately
              followed by an italic glyph without any intervening space.

       \:     Insert a zero-width break point.  This resembles \% within a
              word but does not output the soft hyphen glyph prior to the
              break.

       \?anything\?
              When used in a diversion, this transparently embeds anything
              in the diversion.  anything is read in copy mode.  When the
              diversion is reread, anything is interpreted.  anything may
              not contain newlines; use \! if you want to embed newlines in
              a diversion.  The escape sequence \? is also recognized in
              copy mode and turned into a single internal code; it is this
              code that terminates anything.  Thus

                     .nr x 1
                     .nf
                     .di d
                     \?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
                     .di
                     .nr x 2
                     .di e
                     .d
                     .di
                     .nr x 3
                     .di f
                     .e
                     .di
                     .nr x 4
                     .f

              prints 4.

       \[xxx] Print the special character (glyph) called xxx.

       \[comp1 comp2
              ...]  Print composite glyph consisting of multiple components.
              Example: ‘\[A ho]’ is capital letter A with ogonek which
              finally maps to glyph name ‘u0041_0328’.  See Groff: The GNU
              Implementation of troff, the groff Texinfo manual, for details
              of how a glyph name for a composite glyph is constructed, and
              groff_char(7) for a list of glyph name components used in com‐
              posite glyph names.

       \~     This produces an unbreakable space that stretches like a nor‐
              mal inter-word space when a line is adjusted.

   New requests
       .aln new old
              Create an alias new for an existing number register named old,
              causing the names to refer to the same stored object.  If old
              is undefined, a warning of type “reg” is generated and the
              request is ignored.  To remove a number register alias, call
              .rr on its name.  A number register's contents do not become
              inaccessible until it has no more names.

       .als new old
              Create an alias new for the existing request, string, macro,
              or diversion named old, causing the names to refer to the same
              stored object.  If old is undefined, a warning of type “mac”
              is generated and the request is ignored.  The .am, .as, .da,
              .de, .di, and .ds requests (together with their variants) only
              create a new object if the name of the macro, diversion, or
              string is currently undefined or if it is defined as a
              request; normally, they modify the value of an existing
              object.  To remove an alias, simply call .rm on its name.  The
              object itself is not destroyed until it has no more names.

       .am1 xx yy
              Similar to .am, but compatibility mode is switched off during
              execution.  To be more precise, a “compatibility save” token
              is inserted at the beginning, and a “compatibility restore”
              token at the end.  As a consequence, the requests .am, .am1,
              .de, and .de1 can be intermixed freely since the compatibility
              save/restore tokens only affect the macro parts defined by
              .am1 and .ds1.

       .ami xx yy
              Append to macro indirectly.  See the dei request below for
              more information.

       .ami1 xx yy
              Same as the ami request but compatibility mode is switched off
              during execution.

       .as1 name string
              Similar to .as, but compatibility mode is switched off while
              the appended portion of the string is interpolated.  To be
              more precise, a “compatibility save” token is inserted at the
              beginning of the appended string string, and a “compatibility
              restore” token at the end.  As a consequence, the requests as,
              as1, ds, and ds1 can be intermixed freely since the compati‐
              bility save/restore tokens only affect the (sub)strings
              defined by as1 and ds1.

       .asciify xx
              This request ‘unformats’ the diversion xx in such a way that
              ASCII and space characters (and some escape sequences) that
              were formatted and diverted into xx are treated like ordinary
              input characters when xx is reread.  Useful for diversions in
              conjunction with the writem request.  It can be also used for
              gross hacks; for example, this

                     .tr @.
                     .di x
                     @nr n 1
                     .br
                     .di
                     .tr @@
                     .asciify x
                     .x

              sets register n to 1.  Note that glyph information (font, font
              size, etc.) is not preserved; use .unformat instead.

       .backtrace
              Write a backtrace of the input stack to the standard error
              stream.  Also see the -b option of groff(1).

       .blm [ macro] Set a blank line trap.  If a blank line macro is thus
              defined, groff executes macro when a blank line is encountered
              in the input file, instead of the usual behavior.  If no argu‐
              ment is supplied, the default blank line behavior is
              (re-)asserted.

       .box xx
       .boxa xx
              These requests are similar to the di and da requests with the
              exception that a partially filled line does not become part of
              the diversion (i.e., the diversion always starts with a new
              line) but is restored after ending the diversion, discarding
              the partially filled line which possibly comes from the diver‐
              sion.

       .break Break out of a while loop.  See also the while and continue
              requests.  Be sure not to confuse this with the br request.

       .brp   This is the same as \p.

       .cflags n c1 c2
              ...  Assign properties encoded by the number n to characters
              c1, c2, and so on.

              Input characters, including special characters introduced by
              an escape, have certain properties associated with them.
              (Note that output glyphs don't have such properties.  In
              groff, a glyph is a numbered box with a given height above and
              depth below the baseline, and a width—nothing more.)  These
              properties can be modified with this request.  The first argu‐
              ment is the sum of the desired flags and the remaining argu‐
              ments are the characters to be assigned those properties.
              Spaces between the cn arguments are optional.  Any argument cn
              can be a character class defined with the .class request
              rather than an individual character.

              The non-negative integer n is the sum of any of the following.
              Some combinations are nonsensical, such as “33” (1 + 32).

              1      Recognize the character as ending a sentence if fol‐
                     lowed by a newline or two spaces.  Initially, charac‐
                     ters “.?!”  have this property.

              2      Enable breaks before the character.  A line is not bro‐
                     ken at a character with this property unless the char‐
                     acters on each side both have non-zero hyphenation
                     codes.  This exception can be overridden by adding 64.
                     Initially, no characters have this property.

              4      Enable breaks after the character.  A line is not bro‐
                     ken at a character with this property unless the char‐
                     acters on each side both have non-zero hyphenation
                     codes.  This exception can be overridden by adding 64.
                     Initially, characters “-\[hy]\[em]” have this property.

              8      Mark the glyph associated with this character as over‐
                     lapping other instances of itself horizontally.  Ini‐
                     tially, characters “\[ul]\[rn]\[ru]\[radicalex]\[sqr‐
                     tex]” have this property.

              16     Mark the glyph associated with this character as over‐
                     lapping other instances of itself vertically.  Ini‐
                     tially, the character “\[br]” has this property.

              32     Mark the character as transparent for the purpose of
                     end-of-sentence recognition.  In other words, an end-
                     of-sentence character followed by any number of charac‐
                     ters with this property is treated as the end of a sen‐
                     tence if followed by a newline or two spaces.  This is
                     the same as having a zero space factor in TeX.  Ini‐
                     tially, characters “'")]*\[dg]\[dd]\[rq]\[cq]” have
                     this property.

              64     Ignore hyphenation codes of the surrounding characters.
                     Use this value in combination with values 2 and 4.
                     Initially, no characters have this property.

                     For example, if you need an automatic break point after
                     the en-dash in numerical ranges like “3000–5000”,
                     insert
                            .cflags 68 \[en]
                     into your document.  Note, however, that this can lead
                     to bad layout if done without thinking; in most situa‐
                     tions, a better solution than changing the .cflags
                     value is inserting “\:” right after the hyphen at the
                     places that really need a break point.

              The remaining values were implemented for East Asian language
              support; those who use alphabetic scripts exclusively can dis‐
              regard them.

              128    Prohibit a break before the character, but allow a
                     break after the character.  This works only in combina‐
                     tion with values 256 and 512 and has no effect other‐
                     wise.  Initially, no characters have this property.

              256    Prohibit a break after the character, but allow a break
                     before the character.  This works only in combination
                     with values 128 and 512 and has no effect otherwise.
                     Initially, no characters have this property.

              512    Allow a break before or after the character.  This
                     works only in combination with values 128 and 256 and
                     has no effect otherwise.  Initially, no characters have
                     this property.

              In contrast to values 2 and 4, the values 128, 256, and 512
              work pairwise.  If, for example, the left character has value
              512, and the right character 128, no break will be automati‐
              cally inserted between them.  If we use value 6 instead for
              the left character, a break after the character can't be sup‐
              pressed since the neighboring character on the right doesn't
              get examined.

       .char c string
              [This request can both define characters and glyphs.]

              Define entity c to be string.  To be more precise, define (or
              even override) a groff entity which can be accessed with
              name c on the input side, and which uses string on the output
              side.  Every time glyph c needs to be printed, string is pro‐
              cessed in a temporary environment and the result is wrapped up
              into a single object.  Compatibility mode is turned off and
              the escape character is set to \ while string is being pro‐
              cessed.  Any emboldening, constant spacing or track kerning is
              applied to this object rather than to individual glyphs in
              string.

              A groff object defined by this request can be used just like a
              normal glyph provided by the output device.  In particular
              other characters can be translated to it with the tr request;
              it can be made the leader glyph by the lc request; repeated
              patterns can be drawn with the glyph using the \l and \L
              escape sequences; words containing c can be hyphenated cor‐
              rectly, if the hcode request is used to give the object a
              hyphenation code.

              There is a special anti-recursion feature: Use of glyph within
              the glyph's definition is handled like normal glyphs not
              defined with char.

              A glyph definition can be removed with the rchar request.

       .chop object
              Remove the last character from the macro, string, or diversion
              named object.  This is useful for removing the newline from
              the end of a diversion that is to be interpolated as a string.
              This request can be used repeatedly on the same object; see
              section “Gtroff Internals” in Groff: The GNU Implementation of
              troff, the groff Texinfo manual, for details on nodes inserted
              additionally by groff.

       .class name c1 c2
              ...  Define a character class (or simply “class”) name com‐
              prising the characters or range expressions c1, c2, and so on.

              A class thus defined can then be referred to in lieu of list‐
              ing all the characters within it.  Currently, only the .cflags
              request can handle references to character classes.

              In the request's simplest form, each cn is a character (or
              special character).
                     .class [quotes] ' \[aq] \[dq] \[oq] \[cq] \[lq] \[rq]

              Since class and glyph names share the same name space, it is
              recommended to start and end the class name with “[” and “]”,
              respectively, to avoid collisions with existing character
              names defined by groff or the user (with .char and related
              requests).  This practice applies the presence of “]” in the
              class name to prevent the usage of the special character
              escape form “\[...]”, thus you must use the \C escape to
              access a class with such a name.

              You can also use a character range expression consisting of a
              start character followed by “-” and then an end character.
              Internally, groff converts these two character names to Uni‐
              code code points (according to the groff glyph list [GGL]),
              which determine the start and end values of the range.  If
              that fails, the class definition is skipped.  Furthermore,
              classes can be nested.
                     .class [prepunct] , : ; > }
                     .class [prepunctx] \C'[prepunct]' \[u2013]-\[u2016]
              The class “[prepunctx]” thus contains the contents of the
              class “[prepunct]” and characters in the range U+2013–U+2016.

              If you want to include “-” in a class, it must be the first
              character value in the argument list, otherwise it gets misin‐
              terpreted as part of the range syntax.

              Note that it is not possible to use class names as end points
              of range definitions.

              A typical use of the .class request is to control line-break‐
              ing and hyphenation rules as defined by the .cflags request.
              For example, to inhibit line breaks before the characters
              belonging to the “[prepunctx]” class defined in the previous
              example, you can write the following.
                     .cflags 2 \C'[prepunctx]'

       .close stream
              Close the stream named stream; stream will no longer be an
              acceptable argument to the write request.  See the open
              request.

       .composite glyph1 glyph2
              Map glyph name glyph1 to glyph name glyph2 if it is used in
              \[...] with more than one component.

       .continue
              Finish the current iteration of a while loop.  See also the
              while and break requests.

       .color n
              If n is non-zero or missing, enable colors (this is the
              default), otherwise disable them.

       .cp n  If n is non-zero or missing, enable compatibility mode, other‐
              wise disable it.  In compatibility mode, long names are not
              recognized, and the incompatibilities caused by long names do
              not arise.

       .defcolor xxx scheme color_components
              Define color xxx.  scheme can be one of the following values:
              rgb (three components), cmy (three components), cmyk (four
              components), and gray or grey (one component).  Color compo‐
              nents can be given either as a hexadecimal string or as posi‐
              tive decimal integers in the range 0–65535.  A hexadecimal
              string contains all color components concatenated; it must
              start with either # or ##.  The former specifies hex values in
              the range 0–255 (which are internally multiplied by 257), the
              latter in the range 0–65535.  Examples: #FFC0CB (pink),
              ##ffff0000ffff (magenta).  A new scaling indicator f has been
              introduced which multiplies its value by 65536; this makes it
              convenient to specify color components as fractions in the
              range 0 to 1.  Example:

                     .defcolor darkgreen rgb 0.1f 0.5f 0.2f

              Note that f is the default scaling indicator for the defcolor
              request, thus the above statement is equivalent to

                     .defcolor darkgreen rgb 0.1 0.5 0.2

              The color named default (which is device-specific) can't be
              redefined.  It is possible that the default color for \M and
              \m is not the same.

       .de1 xx yy
              Similar to .de, but compatibility mode is switched off during
              execution.  On entry, the current compatibility mode is saved
              and restored at exit.

       .dei xx yy
              Define macro indirectly.  The following example

                     .ds xx aa
                     .ds yy bb
                     .dei xx yy

              is equivalent to

                     .de aa bb

       .dei1 xx yy
              Similar to the dei request but compatibility mode is switched
              off during execution.

       .device anything
              This is (almost) the same as the \X escape.  anything is read
              in copy mode; a leading " is stripped.

       .devicem xx
              This is the same as the \Y escape (to embed the contents of a
              macro into the intermediate output preceded with ‘x X’).

       .do name
              ...  Interpret the string, request, diversion, or macro name
              (along with any arguments) with compatibility mode disabled.
              Note that compatibility mode is restored (if and only if it
              was active) when the expansion of name is interpreted; that
              is, the restored compatibility state applies to the contents
              of the macro (string, ...) name as well as file or pipe data
              read if name is the .so, .mso, or .pso request.

              For example,
                     .de mac1
                     FOO
                     ..
                     .de1 mac2
                     groff
                     .mac1
                     ..
                     .de mac3
                     compatibility
                     .mac1
                     ..
                     .de ma
                     \\$1
                     ..
                     .cp 1
                     .do mac1
                     .do mac2 \" mac2, defined with .de1, calls "mac1"
                     .do mac3 \" mac3 calls "ma" with argument "c1"
                     .do mac3 \[ti] \" groff syntax accepted in .do arguments
              results in
                     FOO groff FOO compatibility c1 ~
              as output.

       .ds1 name string
              Similar to .ds, but compatibility mode is switched off when
              the string is later interpolated.  but compatibility mode is
              switched off during expansion.  To be more precise, a “compat‐
              ibility save” token is inserted at the beginning of the
              string, and a “compatibility restore” token at the end.

       .ecs   Save current escape character.

       .ecr   Restore escape character saved with ecs.  Without a previous
              call to ecs, ‘\’ will be the new escape character.

       .evc xx
              Copy the contents of environment xx to the current environ‐
              ment.  No pushing or popping of environments is done.

       .fam xx
              Set the current font family to xx.  The current font family is
              part of the current environment.  If xx is missing, switch
              back to previous font family.  The value at start-up is ‘T’.
              See the description of the sty request for more information on
              font families.

       .fchar c string
              Define fallback character (or glyph) c to be string.  The syn‐
              tax of this request is the same as the char request; the only
              difference is that a glyph defined with char hides the glyph
              with the same name in the current font, whereas a glyph
              defined with fchar is checked only if the particular glyph
              isn't found in the current font.  This test happens before
              checking special fonts.

       .fcolor c
              Set the fill color to c.  If c is missing, switch to the pre‐
              vious fill color.

       .fschar f c string
              Define fallback character (or glyph) c for font f to be
              string.  The syntax of this request is the same as the char
              request (with an additional argument to specify the font); a
              glyph defined with fschar is searched after the list of fonts
              declared with the fspecial request but before the list of
              fonts declared with .special.

       .fspecial f s1 s2
              ...  When the current font is f, fonts s1, s2, ... are spe‐
              cial, that is, they are searched for glyphs not in the current
              font.  Any fonts specified in the .special request are
              searched after fonts specified in the .fspecial request.
              Without argument, reset the list of global special fonts to be
              empty.

       .ftr f g
              Translate font f to g.  Whenever a font named f is referred to
              in an \f escape sequence, in the F and S conditional opera‐
              tors, or in the ft, ul, bd, cs, tkf, special, fspecial, fp, or
              sty requests, font g is used.  If g is missing, or equal to f
              then font f is not translated.

       .fzoom f zoom
              Set zoom factor zoom for font f.  zoom must a non-negative
              integer multiple of 1/1000th.  If it is missing or is equal to
              zero, it means the same as 1000, namely no magnification.
              f must be a real font name, not a style.

       .gcolor c
              Set the glyph color to c.  If c is missing, switch to the pre‐
              vious glyph color.

       .hcode c1 code1
              [c2 code2] ...  Set the hyphenation code of character c1 to
              code1, that of c2 to code2, and so on.  A hyphenation code
              must be a single input character (not a special character)
              other than a digit or a space.  The request is ignored if it
              has no parameters.

              For hyphenation to work, hyphenation codes must be set up.  At
              start-up, groff assigns hyphenation codes to the letters “a–z”
              (mapped to themselves) and to the letters “A–Z” (mapped to
              “a–z”) and zero to all other characters.  Normally, hyphen‐
              ation patterns contain only lowercase letters which should be
              applied regardless of case.  In other words, they assume that
              the words “FOO” and “Foo” should be hyphenated exactly as
              “foo” is.  The .hcode request extends this principle to let‐
              ters outside the Unicode basic Latin alphabet; without it,
              words containing such letters won't be hyphenated properly
              even if the corresponding hyphenation patterns contain them.
              For example, the following .hcode requests are necessary to
              assign hyphenation codes to the letters “ÄäÖöÜüß” (needed for
              German):

                     .hcode ä ä  Ä ä
                     .hcode ö ö  Ö ö
                     .hcode ü ü  Ü ü
                     .hcode ß ß

              Without those assignments, groff treats German words like
              “Kindergärten” (the plural form of “kindergarten”) as two sub‐
              strings “kinderg” and “rten”) because the hyphenation code of
              the umlaut a is zero by default.  There is a German hyphen‐
              ation pattern that covers “kinder”, so groff finds the hyphen‐
              ation “kin-der”.  The other two hyphenation points (“kin-der-
              gär-ten”) are missed.

       .hla lang
              Set the hyphenation language to lang.  Hyphenation exceptions
              specified with the .hw request and hyphenation patterns and
              exceptions specified with the .hpf and .hpfa requests are
              associated with the hyphenation language.  The .hla request is
              usually invoked by the troffrc or troffrc-end files; troffrc
              sets the default language to “us” (U.S. English).

              The hyphenation language is associated with the current envi‐
              ronment.

       .hlm [ n] Set the maximum number of consecutive hyphenated lines
              to n.  If n is negative, there is no maximum.  If omitted, n
              is -1.  This value is associated with the current environment.
              Only lines output from an environment count towards the maxi‐
              mum associated with that environment.  Hyphens resulting from
              \% are counted; explicit hyphens are not.

       .hpf pattern-file
              Read hyphenation patterns from pattern-file.  This file is
              sought in the same way that macro files are with the .mso
              request or the -mname command-line option to groff(1).

              The pattern-file should have the same format as (simple) TeX
              pattern files.  More specifically, the following scanning
              rules are implemented.

              ·      A percent sign starts a comment (up to the end of the
                     line) even if preceded by a backslash.

              ·      “Digraphs” like \$ are not supported.

              ·      “^^xx” (where each x is 0–9 or a–f) and ^^c (charac‐
                     ter c in the code point range 0–127 decimal) are recog‐
                     nized; other uses of ^ cause an error.

              ·      No macro expansion is performed.

              ·      hpf checks for the expression \patterns{...} (possibly
                     with whitespace before or after the braces).  Every‐
                     thing between the braces is taken as hyphenation pat‐
                     terns.  Consequently, “{” and “}” are not allowed in
                     patterns.

              ·      Similarly, \hyphenation{...} gives a list of hyphen‐
                     ation exceptions.

              ·      \endinput is recognized also.

              ·      For backwards compatibility, if \patterns is missing,
                     the whole file is treated as a list of hyphenation pat‐
                     terns (except that the “%” character is recognized as
                     the start of a comment).

              Use the .hpfcode request (see below) to map the encoding used
              in hyphenation pattern files to groff's input encoding.

              The set of hyphenation patterns is associated with the hyphen‐
              ation language set by the .hla request.  The .hpf request is
              usually invoked by the troffrc or troffrc-end file; by
              default, troffrc loads hyphenation patterns and exceptions for
              U.S. English from the files hyphen.us and hyphenex.us, respec‐
              tively.

              A second call to .hpf (for the same language) replaces the old
              patterns with the new ones.

              Invoking .hpf causes an error if there is no hyphenation lan‐
              guage.

              If no .hpf request is specified (either in the document, in a
              troffrc or troffrc-end file, or in a macro package), groff
              won't automatically hyphenate at all.

       .hpfa pattern-file
              As .hpf, except that the hyphenation patterns and exceptions
              from pattern-file are appended to the patterns already applied
              to the hyphenation language of the environment.

       .hpfcode a b
               [c d] ...  Define mapping values for character codes in pat‐
              tern files; after reading a pattern file with the .hpf or
              .hpfa request, convert all characters with character code a in
              the recently read patterns to character code b, code c to d,
              and so on, before replacing or appending to the active list of
              patterns.  Each argument must be an integer in the range 0
              to 255.  Character codes that would otherwise be invalid in
              groff can be used.  By default, every code maps to itself
              except those for letters “A” to “Z”, which map to those for
              “a” to “z”.

       .hym [ length] Set the (right) hyphenation margin to length.  If the
              adjustment mode is not “b” or “n”, the line is not hyphenated
              if it is shorter than length.  Without an argument, the
              default hyphenation margin is reset to its default value, 0.
              The default scaling indicator is “m”.  The hyphenation margin
              is associated with the current environment.

              A negative argument resets the hyphenation margin to zero,
              emitting a warning of type “range”.

       .hys [ hyphenation-space] Suppress hyphenation of the line in adjust‐
              ment modes “b” or “n”, if it can be justified by adding no
              more than hyphenation-space extra space to each word space.
              Without an argument, the hyphenation space adjustment thresh‐
              old is set to its default value, 0.  The default scaling indi‐
              cator is “m”.  The hyphenation space adjustment threshold is
              associated with the current environment.

              A negative argument resets the hyphenation space adjustment
              threshold to zero, emitting a warning of type “range”.

       .itc n macro
              Variant of .it for which a line interrupted with \c is not
              counted as an input line.

       .kern n
              If n is non-zero or missing, enable pairwise kerning, other‐
              wise disable it.

       .length reg anything
              Compute the number of characters in anything and return the
              count in the number register reg.  If reg doesn't exist, it is
              created.  anything is read in copy mode.

                     .ds xxx abcd\h'3i'efgh
                     .length yyy \*[xxx]
                     \n[yyy]
                     14

       .linetabs n
              If n is non-zero or missing, enable line-tabs mode, otherwise
              disable it (which is the default).  In line-tabs mode, tab
              distances are computed relative to the (current) output line.
              Otherwise they are taken relative to the input line.  For
              example, the following

                     .ds x a\t\c
                     .ds y b\t\c
                     .ds z c
                     .ta 1i 3i
                     \*x
                     \*y
                     \*z

              yields

                     a         b         c

              In line-tabs mode, the same code gives

                     a         b                   c

              Line-tabs mode is associated with the current environment; the
              read-only number register \n[.linetabs] is set to 1 if in
              line-tabs mode, and 0 otherwise.

       .lsm xx
              Set the leading spaces macro to xx.  If there are leading spa‐
              ces in an input line, it is invoked instead of the usual troff
              behaviour; the leading spaces are removed.  Registers \n[lsn]
              and \n[lss] hold the number of removed leading spaces and the
              corresponding horizontal space, respectively.

       .mso file
              The same as the so request except that file is searched for in
              the same directories as macro files for the -m command-line
              option.  If the file name to be included has the form
              name.tmac and it isn't found, mso tries to include tmac.name
              instead and vice versa.  A warning of type file is generated
              if file can't be loaded, and the request is ignored.

       .nop anything
              Execute anything.  This is similar to ‘.if 1’.

       .nroff Make the n built-in condition true and the t built-in condi‐
              tion false.  This can be reversed using the troff request.

       .open stream filename
              Open filename for writing and associate the stream named
              stream with it.  See also the close and write requests.

       .opena stream filename
              Like open, but if filename exists, append to it instead of
              truncating it.

       .output string
              Emit string directly to the intermediate output (subject to
              copy-mode interpretation); this is similar to \! used at the
              top level.  An initial double quote in string is stripped off
              to allow initial blanks.

       .pev   Print the current environment and each defined environment
              state on stderr.

       .pnr   Print the names and contents of all currently defined number
              registers on stderr.

       .psbb filename
              Get the bounding box of a PostScript image filename.  This
              file must conform to Adobe's Document Structuring Conventions;
              the command looks for a %%BoundingBox comment to extract the
              bounding box values.  After a successful call, the coordinates
              (in PostScript units) of the lower left and upper right corner
              can be found in the registers \n[llx], \n[lly], \n[urx], and
              \n[ury], respectively.  If some error has occurred, the four
              registers are set to zero.

       .pso command
              This behaves like the so request except that input comes from
              the standard output of command.

       .ptr   Print the names and positions of all traps (not including
              input line traps and diversion traps) on stderr.  Empty slots
              in the page trap list are printed as well, because they can
              affect the priority of subsequently planted traps.

       .pvs ±n
              Set the post-vertical line space to n; default scale indicator
              is p.  This value is added to each line after it has been out‐
              put.  With no argument, the post-vertical line space is set to
              its previous value.

              The total vertical line spacing consists of four components:
              .vs and \x with a negative value which are applied before the
              line is output, and .pvs and \x with a positive value which
              are applied after the line is output.

       .rchar c1 c2
              ...  Remove the definitions of glyphs c1, c2, and so on.  This
              undoes the effect of a .char request.

       .return
              Within a macro, return immediately.  If called with an argu‐
              ment, return twice, namely from the current macro and from the
              macro one level higher.  No effect otherwise.

       .rfschar f c1 c2
              ...  Remove the font-specific definitions of glyphs c1, c2,
              ... for font f.  Whitespace is optional between cn arguments.
              See .fschar.

       .rj
       .rj n  Right justify the next n input lines.  Without an argument
              right justify the next input line.  The number of lines to be
              right justified is available in the \n[.rj] register.  This
              implicitly does .ce 0.  The ce request implicitly does .rj 0.

       .rnn xx yy
              Rename number register xx to yy.

       .schar c string
              Define global fallback character (or glyph) c to be string.
              The syntax of this request is the same as the char request; a
              glyph defined with schar is searched after the list of fonts
              declared with the special request but before the mounted spe‐
              cial fonts.

       .shc glyph
              Set the soft hyphen character to glyph.  If glyph is omitted,
              the soft hyphen character is set to the default, \[hy].  The
              soft hyphen character is the glyph that is inserted when a
              word is automatically hyphenated at a line break.  If the soft
              hyphen character does not exist in the font of the character
              immediately preceding a potential break point, then the line
              is not broken at that point.  Neither definitions (specified
              with the .char request) nor translations (specified with the
              .tr request) are considered when determining the soft hyphen
              character.

       .shift n
              In a macro, shift the arguments by n positions: argument i
              becomes argument i-n; arguments 1 to n are no longer avail‐
              able.  If n is missing, arguments are shifted by 1.  Shifting
              by negative amounts is currently undefined.

       .sizes s1 s2
              ... sn [0] This request is similar to the sizes command of a
              DESC file.  It sets the available font sizes for the current
              font to s1, s2, ... sn scaled points.  The list of sizes can
              be terminated by an optional “0”.  Each si can also be a range
              of sizes mn.  Contrary to the font file command, the list
              can't extend over more than a single line.

       .special s1 s2
              ...  Fonts s1, s2, ... are special and are searched for glyphs
              not in the current font.  Without arguments, reset the list of
              special fonts to be empty.

       .spreadwarn
               [limit] Emit a break warning if the additional space inserted
              for each space between words in an output line adjusted to
              both margins with “.ad b” is larger than or equal to limit.  A
              negative value is treated as zero; an absent argument toggles
              the warning on and off without changing limit.  The default
              scaling indicator is m.  At startup, .spreadwarn is inactive
              and limit is 3 m.

              For example,

                     .spreadwarn 0.2m

              causes a warning if break warnings are not suppressed and
              troff must add 0.2 m or more for each interword space in a
              line.  See troff(1) for warning types and control.

       .stringdown str
       .stringup str
              Alter the string named str by replacing each of its bytes with
              its lowercase (down) or uppercase (up) version (if one
              exists).  groff special characters (see groff_char(7)) can be
              used and the output will usually transform in the expected way
              due to the regular naming convention of the special character
              escapes.

                     .ds resume R\['e]sum\['e]\"
                     \*[resume] \# Résumé
                     .stringdown resume
                     \*[resume] \# résumé
                     .stringup resume
                     \*[resume] \# RÉSUMÉ

       .sty n f
              Associate style f with font position n.  A font position can
              be associated either with a font or with a style.  The current
              font is the index of a font position and so is also either a
              font or a style.  When it is a style, the font that is actu‐
              ally used is the font the name of which is the concatenation
              of the name of the current family and the name of the current
              style.  For example, if the current font is 1 and font posi‐
              tion 1 is associated with style R and the current font family
              is T, then font TR is used.  If the current font is not a
              style, then the current family is ignored.  When the requests
              cs, bd, tkf, uf, or fspecial are applied to a style, then they
              are applied instead to the member of the current family corre‐
              sponding to that style.  The default family can be set with
              the -f command-line option.  The styles command in the DESC
              file controls which font positions (if any) are initially
              associated with styles rather than fonts.

       .substring str start
              [end] Replace the string named str with its substring bounded
              by the indices start and end, inclusive.  The first character
              in the string has index 0.  If end is omitted, it is implic‐
              itly set to the largest valid value (the string length minus
              one).  Negative indices count backwards from the end of the
              string: the last character has index -1, the character before
              the last has index -2, and so on.

                     .ds xxx abcdefgh
                     .substring xxx 1 -4
                     \*[xxx]
                     bcde
                     .substring xxx 2
                     \*[xxx]
                     de

       .tkf f s1 n1 s2 n2
              Enable track kerning for font f.  When the current font is f
              the width of every glyph is increased by an amount between n1
              and n2; when the current point size is less than or equal to
              s1 the width is increased by n1; when it is greater than or
              equal to s2 the width is increased by n2; when the point size
              is greater than or equal to s1 and less than or equal to s2
              the increase in width is a linear function of the point size.

       .tm1 string
              Similar to the tm request, string is read in copy mode and
              written on the standard error, but an initial double quote in
              string is stripped off to allow initial blanks.

       .tmc string
              Similar to tm1 but without writing a final newline.

       .trf filename
              Transparently output the contents of file filename.  Each line
              is output as if preceded by \!; however, the lines are not
              subject to copy-mode interpretation.  If the file does not end
              with a newline, then a newline is added.  For example, you can
              define a macro x containing the contents of file f, using

                     .di x
                     .trf f
                     .di

              Unlike with the cf request, the file cannot contain charac‐
              ters, such as NUL, that are not valid troff input characters.

       .trin abcd
              This is the same as the tr request except that the asciify
              request uses the character code (if any) before the character
              translation.  Example:

                     .trin ax
                     .di xxx
                     a
                     .br
                     .di
                     .xxx
                     .trin aa
                     .asciify xxx
                     .xxx

              The result is x a.  Using tr, the result would be x x.

       .trnt abcd
              This is the same as the tr request except that the transla‐
              tions do not apply to text that is transparently throughput
              into a diversion with \!.  For example,

                     .tr ab
                     .di x
                     \!.tm a
                     .di
                     .x

              prints b; if trnt is used instead of tr it prints a.

       .troff Make the n built-in condition false, and the t built-in condi‐
              tion true.  This undoes the effect of the nroff request.

       .unformat xx
              This request ‘unformats’ the diversion xx.  Contrary to the
              asciify request, which tries to convert formatted elements of
              the diversion back to input tokens as much as possible,
              .unformat only handles tabs and spaces between words (usually
              caused by spaces or newlines in the input) specially.  The
              former are treated as if they were input tokens, and the lat‐
              ter are stretchable again.  Note that the vertical size of
              lines is not preserved.  Glyph information (font, font size,
              space width, etc.) is retained.  Useful in conjunction with
              the box and boxa requests.

       .vpt n Enable vertical position traps if n is non-zero, disable them
              otherwise.  Vertical position traps are traps set by the wh or
              dt requests.  Traps set by the it request are not vertical
              position traps.  The parameter that controls whether vertical
              position traps are enabled is global.  Initially vertical
              position traps are enabled.

       .warn n
              Control warnings.  n is the sum of the numbers associated with
              each warning that is to be enabled; all other warnings are
              disabled.  The number associated with each warning is listed
              in troff(1).  For example, .warn 0 disables all warnings, and
              .warn 1 disables all warnings except that about missing
              glyphs.  If n is not given, all warnings are enabled.

       .warnscale si
              Set the scaling indicator used in warnings to si.  Valid val‐
              ues for si are u, i, c, p, and P.  At startup, it is set to i.

       .while c anything
              While condition c is true, accept anything as input; c can be
              any condition acceptable to an if request; anything can com‐
              prise multiple lines if the first line starts with \{ and the
              last line ends with \}.  See also the break and continue
              requests.

       .write stream anything
              Write anything to the stream named stream.  stream must previ‐
              ously have been the subject of an open request.  anything is
              read in copy mode; a leading " is stripped.

       .writec stream anything
              Similar to write but without writing a final newline.

       .writem stream xx
              Write the contents of the macro or string xx to the stream
              named stream.  stream must previously have been the subject of
              an open request.  xx is read in copy mode.

   Extended requests
       .cf filename
              When used in a diversion, this embeds in the diversion an
              object which, when reread, will cause the contents of filename
              to be transparently copied through to the output.  In
              AT&T troff, the contents of filename are immediately copied
              through to the output regardless of whether there is a current
              diversion; this behavior is so anomalous that it must be con‐
              sidered a bug.

       .de xx yy
       .am xx yy
       .ds xx yy
       .as xx yy
              In compatibility mode, these requests behave similarly to
              .de1, .am1, .ds1, and .as1, respectively: a “compatibility
              save” token is inserted at the beginning, and a “compatibility
              restore” token at the end, with compatibility mode switched on
              during execution.

       .ev xx If xx is not a number, this switches to a named environment
              called xx.  The environment should be popped with a matching
              ev request without any arguments, just as for numbered envi‐
              ronments.  There is no limit on the number of named environ‐
              ments; they are created the first time that they are refer‐
              enced.

       .hy n  New values 16 and 32 are available; the former enables hyphen‐
              ation before the last character in a word, and the latter
              enables hyphenation after the first character in a word.

       .ss word-space-size sentence-space-size
              A second argument to the .ss request determines the additional
              inter-sentence spacing used in fill mode.  If omitted, this
              value is the same as the minimal inter-word spacing (the first
              argument).  Both are in units of twelfths of the space-width
              parameter of the current font (see groff_font(5)) and default
              to  12.  Unlike AT&T troff, groff does not ignore the .ss
              request if the output is a terminal device; instead, the val‐
              ues of minimal inter-word and additional inter-sentence spac‐
              ing are rounded down to the nearest multiple of 12.

              Additional inter-sentence spacing is used only in fill mode,
              and only if the output line is not full when the end of a sen‐
              tence occurs in the input.  If a sentence ends at the end of
              an input line, then both an inter-word space and an inter-sen‐
              tence space are added to the output; if two spaces follow the
              end of a sentence in the middle of an input line, then the
              second space becomes an inter-sentence space in the output.
              Additional inter-sentence space is not adjusted, but the
              inter-word space that always precedes it may be.

              If a second argument is never given to the .ss request, groff
              separates sentences as AT&T troff does.  In groff, as in
              AT&T troff, you should always follow a sentence with either a
              newline or two spaces.

              A related application of the .ss request is to insert discard‐
              able horizontal space; i.e., space that is discarded at a line
              break.  For example, some footnote styles collect the notes
              into a single paragraph with large spaces between each.
                     .ie n .ll 50n
                     .el   .ll 2.75i
                     .ss 12 48
                     1. J. Fict. Ch. Soc. 6 (2020), 3\[en]14.
                     2. Better known for other work.

              The result has obvious inter-sentence spacing.
                     1. J. Fict. Ch. Soc. 6 (2020), 3-14.     2. Better
                     known for other work.

       .ta [[ n1 n2 ... nn ]Tr1 r2 ... rn] Set tabs at positions n1, n2,
              ..., nn and then set tabs at nn+r1, nn+r2, ..., nn+rn and then
              at nn+rn+r1, nn+rn+r2, ..., nn+rn+rn, and so on.  For example,

                     .ta T .5i

              sets tabs every half an inch.

   New number registers
       The following read-only registers are available:

       \n[.br]
              Within a macro call, it is set to 1 if the macro is called
              with the ‘normal’ control character (‘.’ by default), and set
              to 0 otherwise.  This allows the reliable modification of
              requests.

                     .als bp*orig bp
                     .de bp
                     .tm before bp
                     .ie \\n[.br] .bp*orig
                     .el 'bp*orig
                     .tm after bp
                     ..

              Using this register outside of a macro makes no sense (it
              always returns zero in such cases).

       \n[.C] 1 if compatibility mode is in effect, 0 otherwise.

       \n[.cdp]
              The depth of the last glyph added to the current environment.
              It is positive if the glyph extends below the baseline.

       \n[.ce]
              The number of lines remaining to be centered, as set by the ce
              request.

       \n[.cht]
              The height of the last glyph added to the current environment.
              It is positive if the glyph extends above the baseline.

       \n[.color]
              1 if colors are enabled, 0 otherwise.

       \n[.cp]
              Within a .do request, holds the saved value of compatibility
              mode (see \n[.C] above).

       \n[.csk]
              The skew of the last glyph added to the current environment.
              The skew of a glyph is how far to the right of the center of a
              glyph the center of an accent over that glyph should be
              placed.

       \n[.ev]
              The name or number of the current environment.  This is a
              string-valued register.

       \n[.fam]
              The current font family.  This is a string-valued register.

       \n[.fn]
              The current (internal) real font name.  This is a string-val‐
              ued register.  If the current font is a style, the value of
              \n[.fn] is the proper concatenation of family and style name.

       \n[.fp]
              The number of the next free font position.

       \n[.g] Always 1.  Macros should use this to determine whether they
              are running under GNU troff.

       \n[.height]
              The current height of the font as set with \H.

       \n[.hla]
              The hyphenation language in the current environment.

       \n[.hlc]
              The count of immediately preceding consecutive hyphenated
              lines in the current environment.

       \n[.hlm]
              The maximum number of consecutive hyphenated lines allowed in
              the current environment.

       \n[.hy]
              The hyphenation mode in the current environment.

       \n[.hym]
              The hyphenation margin in the current environment.

       \n[.hys]
              The hyphenation space adjustment threshold in the current
              environment.

       \n[.in]
              The indentation that applies to the current output line.

       \n[.int]
              Set to a positive value if last output line is interrupted
              (i.e., if it contains \c).

       \n[.kern]
              1 if pairwise kerning is enabled, 0 otherwise.

       \n[.lg]
              The current ligature mode (as set by the lg request).

       \n[.linetabs]
              The current line-tabs mode (as set by the linetabs request).

       \n[.ll]
              The line length that applies to the current output line.

       \n[.lt]
              The title length as set by the lt request.

       \n[.m] The name of the current drawing color.  This is a string-val‐
              ued register.

       \n[.M] The name of the current background color.  This is a string-
              valued register.

       \n[.ne]
              The amount of space that was needed in the last ne request
              that caused a trap to be sprung.  Useful in conjunction with
              the \n[.trunc] register.

       \n[.ns]
              1 if no-space mode is active, 0 otherwise.

       \n[.O] The current output level as set with \O.

       \n[.P] 1 if the current page is in the output list set with -o.

       \n[.pe]
              1 during a page ejection caused by the bp request, 0 other‐
              wise.

       \n[.pn]
              The number of the next page, either the value set by a pn
              request, or the number of the current page plus 1.

       \n[.ps]
              The current point size in scaled points.

       \n[.psr]
              The last-requested point size in scaled points.

       \n[.pvs]
              The current post-vertical line space as set with the pvs
              request.

       \n[.rj]
              The number of lines to be right-justified as set by the rj
              request.

       \n[.slant]
              The slant of the current font as set with \S.

       \n[.sr]
              The last requested point size in points as a decimal fraction.
              This is a string-valued register.

       \n[.ss]
       \n[.sss]
              The values of minimal inter-word spacing and additional inter-
              sentence spacing, respectively, in twelfths of the space width
              of the current font.  Set by the .ss request.

       \n[.sty]
              The current font style.  This is a string-valued register.

       \n[.tabs]
              A string representation of the current tab settings suitable
              for use as an argument to the ta request.

       \n[.trunc]
              The amount of vertical space truncated by the most recently
              sprung vertical position trap, or, if the trap was sprung by
              an ne request, minus the amount of vertical motion produced by
              the ne request.  In other words, at the point a trap is
              sprung, it represents the difference of what the vertical
              position would have been but for the trap, and what the verti‐
              cal position actually is.  Useful in conjunction with the
              \n[.ne] register.

       \n[.U] Set to 1 if in safer mode and to 0 if in unsafe mode (as given
              with the -U command-line option).

       \n[.vpt]
              1 if vertical position traps are enabled, 0 otherwise.

       \n[.warn]
              The sum of the numbers associated with each of the currently
              enabled warnings.  The number associated with each warning is
              listed in troff(1).

       \n[.x] The major version number.  For example, if the version number
              is 1.03, then \n[.x] contains 1.

       \n[.y] The minor version number.  For example, if the version number
              is 1.03, then \n[.y] contains 03.

       \n[.Y] The revision number of groff.

       \n[.zoom]
              The zoom value of the current font, in multiples of 1/1000th.
              Zero if no magnification.

       \n[llx]
       \n[lly]
       \n[urx]
       \n[ury]
              These four read/write registers are set by the psbb request
              and contain the bounding box values (in PostScript units) of a
              given PostScript image.

       The following read/write registers are set by the \w escape sequence:

       \n[rst]
       \n[rsb]
              Like the st and sb registers, but take account of the heights
              and depths of glyphs.

       \n[ssc]
              The amount of horizontal space (possibly negative) that should
              be added to the last glyph before a subscript.

       \n[skw]
              How far to right of the center of the last glyph in the \w
              argument, the center of an accent from a roman font should be
              placed over that glyph.

       Other available read/write number registers are:

       \n[c.] The current input line number.  \n[.c] is a read-only alias to
              this register.

       \n[hours]
              The number of hours past midnight.  Initialized at start-up.

       \n[hp] The current horizontal position at input line.

       \n[lsn]
       \n[lss]
              If there are leading spaces in an input line, these registers
              hold the number of leading spaces and the corresponding hori‐
              zontal space, respectively.

       \n[minutes]
              The number of minutes after the hour.  Initialized at start-
              up.

       \n[seconds]
              The number of seconds after the minute.  Initialized at start-
              up.

       \n[systat]
              The return value of the system() function executed by the last
              sy request.

       \n[slimit]
              If greater than 0, the maximum number of objects on the input
              stack.  If less than or equal to 0, there is no limit on the
              number of objects on the input stack.  With no limit, recur‐
              sion can continue until virtual memory is exhausted.

       \n[year]
              The current year.  Note that the traditional troff number reg‐
              ister \n[yr] is the current year minus 1900.

   Miscellaneous
       troff predefines a single (read/write) string-based register, \*[.T],
       which contains the argument given to the -T command-line option,
       namely the current output device (for example, latin1 or ascii).
       Note that this is not the same as the (read-only) number register
       \n[.T] which is defined to be 1 if troff is called with the -T com‐
       mand-line option, and zero otherwise.  This behavior is different
       from AT&T troff.

       Fonts not listed in the DESC file are automatically mounted on the
       next available font position when they are referenced.  If a font is
       to be mounted explicitly with the fp request on an unused font posi‐
       tion, it should be mounted on the first unused font position, which
       can be found in the \n[.fp] register; although troff does not enforce
       this strictly, it does not allow a font to be mounted at a position
       whose number is much greater than that of any currently used posi‐
       tion.

       Interpolating a string does not hide existing macro arguments.  Thus
       in a macro, a more efficient way of doing

              .xx \\$@

       is

              \\*[xx]\\

       If the font description file contains pairwise kerning information,
       glyphs from that font are kerned.  Kerning between two glyphs can be
       inhibited by placing a \& between them.

       In a string comparison in a condition, characters that appear at dif‐
       ferent input levels to the first delimiter character are not recog‐
       nized as the second or third delimiters.  This applies also to the tl
       request.  In a \w escape sequence, a character that appears at a dif‐
       ferent input level to the starting delimiter character is not recog‐
       nized as the closing delimiter character.  The same is true for \A,
       \b, \B, \C, \l, \L, \o, \X, and \Z.  When decoding a macro or string
       argument that is delimited by double quotes, a character that appears
       at a different input level to the starting delimiter character is not
       recognized as the closing delimiter character.  The implementation of
       \$@ ensures that the double quotes surrounding an argument appear at
       the same input level, which is different to the input level of the
       argument itself.  In a long escape name ] is not recognized as a
       closing delimiter except when it occurs at the same input level as
       the opening [.  In compatibility mode, no attention is paid to the
       input-level.

       The tr request can now map characters onto \~.

       The space width emitted by the \| and \^ escape sequences can be con‐
       trolled on a per-font basis.  If there is a glyph named \| or \^,
       respectively (note the leading backslash), defined in the current
       font file, use this glyph's width instead of the default value.

       It is now possible to have whitespace between the first and second
       dot (or the name of the ending macro) to end a macro definition.
       Example:

              .if t \{\
              .  de bar
              .    nop Hello, I'm ‘bar’.
              .  .
              .\}

Intermediate Output Format         top

       The output format of groff is modeled after that used AT&T troff once
       it adopted a device-independent approach in the early 1980s.  Only
       the differences are documented here.

   Units
       The argument to the s command is in scaled points (units of points/n,
       where n is the argument to the sizescale command  in the DESC file).
       The argument to the x Height command is also in scaled points.

   Text commands
       Nn     Print glyph with index n (a non-negative integer) of the
              current font.

       If the tcommand line is present in the DESC file, troff uses the
       following two commands.

       txxx   xxx is any sequence of characters terminated by a space or a
              newline (to be more precise, it is a sequence of glyphs which
              are accessed with the corresponding characters); the first
              character should be printed at the current position, the
              current horizontal position should be increased by the width
              of the first character, and so on for each character.  The
              width of the glyph is that given in the font file,
              appropriately scaled for the current point size, and rounded
              so that it is a multiple of the horizontal resolution.
              Special characters cannot be printed using this command.

       un xxx This is same as the t command except that after printing each
              character, the current horizontal position is increased by the
              sum of the width of that character and n.

       Note that single characters can have the eighth bit set, as can the
       names of fonts and special characters.

       The names of glyphs and fonts can be of arbitrary length; drivers
       should not assume that they are only two characters long.

       When a glyph is to be printed, that glyph is always in the current
       font.  Unlike device-independent troff, it is not necessary for
       drivers to search special fonts to find a glyph.

       For color support, some new commands have been added:

       mc cyan magenta yellow
       md
       mg gray
       mk cyan magenta yellow black
       mr red green blue
              Set the color components of the current drawing color, using
              various color schemes.  md resets the drawing color to the
              default value.  The arguments are integers in the range 0 to
              65536.

       The x device control command has been extended.

       x u n  If n is 1, start underlining of spaces.  If n is 0, stop
              underlining of spaces.  This is needed for the cu request in
              nroff mode and is ignored otherwise.

   Drawing commands
       The D drawing command has been extended.  These extensions are not
       used by GNU pic if the -n option is given.

       Df n\n Set the shade of gray to be used for filling solid objects to
              n; n must be an integer between 0 and 1000, where 0
              corresponds solid white and 1000 to solid black, and values in
              between correspond to intermediate shades of gray.  This
              applies only to solid circles, solid ellipses and solid
              polygons.  By default, a level of 1000 is used.  Whatever
              color a solid object has, it should completely obscure
              everything beneath it.  A value greater than 1000 or less
              than 0 can also be used: this means fill with the shade of
              gray that is currently being used for lines and text.
              Normally this is black, but some drivers may provide a way of
              changing this.

              The corresponding \D'f...' command shouldn't be used since its
              argument is always rounded to an integer multiple of the
              horizontal resolution which can lead to surprising results.

       DC d\n Draw a solid circle with a diameter of d with the leftmost
              point at the current position.

       DE dx dy\n
              Draw a solid ellipse with a horizontal diameter of dx and a
              vertical diameter of dy with the leftmost point at the current
              position.  delim $$

       Dp $dx sub 1$ $dy sub 1$ $dx sub 2$ $dy sub 2$ $...$
              $dx sub n$ $dy sub n$\n Draw a polygon with, for $i = 1 ,...,
              n+1$, the i-th vertex at the current position $+ sum from j=1
              to i-1 ( dx sub j , dy sub j )$.  At the moment, GNU pic only
              uses this command to generate triangles and rectangles.

       DP $dx sub 1$ $dy sub 1$ $dx sub 2$ $dy sub 2$ $...$
              $dx sub n$ $dy sub n$\n Like Dp but draw a solid rather than
              outlined polygon.

       Dt n\n Set the current line thickness to n machine units.
              Traditionally, AT&T troff drivers use a line thickness
              proportional to the current point size; drivers should
              continue to do this if no Dt command has been given, or if a
              Dt command has been given with a negative value of n.  A zero
              value of n selects the smallest available line thickness.

       A difficulty arises in how the current position should be changed
       after the execution of these commands.  This is not of great
       importance since the code generated by GNU pic does not depend on
       this.  Given a drawing command of the form

              \D'c $x sub 1$ $y sub 1$ $x sub 2$ $y sub 2$ $...$ $x sub n$
              $y sub n$'

       where c is not one of c, e, l, a, or ~, AT&T troff treats each of the
       $x sub i$ as a horizontal quantity, and each of the $y sub i$ as a
       vertical quantity and assumes that the width of the drawn object is
       $sum from i=1 to n x sub i$, and that the height is $sum from i=1 to
       n y sub i$.  (The assumption about the height can be seen by
       examining the st and sb registers after using such a D command in a
       \w escape sequence).  This rule also holds for all the original
       drawing commands with the exception of De.  For the sake of
       compatibility GNU troff also follows this rule, even though it
       produces an ugly result in the case of the Dt and Df, and, to a
       lesser extent, DE commands.  Thus after executing a D command of the
       form

              Dc $x sub 1$ $y sub 1$ $x sub 2$ $y sub 2$ $...$ $x sub n$ $y
              sub n$\n

       the current position should be increased by $( sum from i=1 to n x
       sub i , sum from i=1 to n y sub i )$.  delim off

       Another set of extensions is

       DFc cyan magenta yellow\n
       DFd\n
       DFg gray\n
       DFk cyan magenta yellow black\n
       DFr red green blue\n
              Set the color components of the filling color similar to the
              m commands above.

       The current position isn't changed by those colour commands (contrary
       to Df).

   Device control commands
       There is a continuation convention which permits the argument to the
       x X command to contain newlines: when outputting the argument to the
       x X command, GNU troff follows each newline in the argument with a +
       character (as usual, it terminates the entire argument with a
       newline); thus if the line after the line containing the x X command
       starts with +, then the newline ending the line containing the x X
       command should be treated as part of the argument to the x X command,
       the + should be ignored, and the part of the line following the +
       should be treated like the part of the line following the x X
       command.

       The first three output commands are guaranteed to be:

              x T device
              x res n h v
              x init

Implementation Differences         top

       groff has a number of features that cause incompatibilities with
       documents written using old versions of roff.  Some GNU extensions to
       roff have become supported by other implementations.

       groff does not always hyphenate words as AT&T troff does.  The AT&T
       implementation uses a set of hard-coded rules specific to U.S.
       English, while groff uses language-specific hyphenation pattern files
       derived from TeX.  Furthermore, in old versions of troff there was a
       limited amount of space to store hyphenation exceptions (arguments to
       the .hw request); groff has no such restriction.

       Long names may be groff's most obvious innovation.  AT&T troff
       interprets “.dsabcd” as defining a string “ab” with contents “cd”.
       Normally, groff interprets this as a call of a macro named “dsabcd”.
       AT&T troff also interprets \*[ and \n[ as a reference to a string or
       number register, respectively, called “[”.  In groff, however, the
       “[” is normally interpreted as delimiting a long name.  In
       compatibility mode, groff interprets names in the traditional way,
       which means that they are limited to one or two characters.  See the
       -C option in groff(1) and, above, the .C and .cp registers, and .cp
       and .do requests, for more on compatibility mode.

       The register \n[.cp] is specialized and may require a statement of
       rationale.  When writing macro packages or documents that use groff
       features and which may be mixed with other packages or documents that
       do not—common scenarios include serial processing of man pages or use
       of the .so or .mso requests—you may desire correct operation
       regardless of compatibility mode in the surrounding context.  It may
       occur to you to save the existing value of \n(.C into a register,
       say, _C, at the beginning of your file, turn compatibility mode off
       with “.cp 0”, then restore it from that register at the end with
       “.cp \n(_C”.  At the same time, a modular design of a document or
       macro package may lead you to multiple layers of inclusion.  You
       cannot use the same register name everywhere or you risk “clobbering”
       the value from a preceding or enclosing context.  The two-character
       register name space of AT&T troff is confining and mnemonically
       challenging; you may wish to use groff's more capacious name space.
       However, attempting “.nr _my_saved_C \n(.C” will not work in
       compatibility mode; the register name is too long.  “This is exactly
       what .do is for,” you think, “.do nr _my_saved_C \n(.C”.  The
       foregoing will always save zero to your register, because .do turns
       compatibility mode off while it interprets its argument list.  What
       you need is:
              .do nr _my_saved_C \n[.cp]
              .cp 0
       at the beginning of your file, followed by
              .cp _my_saved_C
       at the end.  As in the C language, we all have to share one big name
       space, so choose a register name that is unlikely to collide with
       other uses.

       Normally, groff preserves the input level in delimited arguments, but
       not in compatibility mode.  For example, on terminal devices,
              .ds xx '
              \w'abc\*(xxdef'
       produces “168” ordinarily, but “72def'” in compatibility mode.

       Furthermore, the escapes \f, \H, \m, \M, \R, \s, and \S are transpar‐
       ent for recognizing the beginning of a line only in compatibility
       mode.  For example, this code produces bold output in both cases, but
       the text differs,
              .de xx '
              Hello!
              ..
              \fB.xx\fP
       producing “.xx” in normal mode and “Hello!” in compatibility mode.

       groff does not allow the use of the escape sequences \|, \^, \&, \{,
       \}, “\ , \', \`, \-, \_, \!, \%, \c, in names of strings, macros,
       diversions, number registers, fonts, or environments; AT&T troff
       does.  The \A escape sequence (see subsection “Escape sequences”
       above) may be helpful in avoiding use of these escape sequences in
       names.

       Normally, the syntax form \sn accepts only a single character (a
       digit) for n, consistently with other forms that originated in
       AT&T troff, like \*, \$, \f, \g, \k, \n, and \z.  In compatibility
       mode only, a non-zero n must be in the range 4–39.  Legacy documents
       relying upon this quirk of parsing should be migrated to another \s
       form.  [Background: The Graphic Systems C/A/T phototypesetter (the
       original device target for AT&T troff) supported only a few discrete
       point sizes in the range 6–36, so Ossanna contrived a special case in
       the parser to do what the user must have meant.  Kernighan warned of
       this in the 1992 revision of CSTR #54 (§2.3), and more recently,
       McIlroy referred to it as a “living fossil”.]

       Fractional point sizes cause one noteworthy incompatibility.  In
       AT&T troff the .ps request ignores scale indicators and thus
       “.ps 10u” sets the point size to 10 points, whereas in groff it sets
       the point size to 10 scaled points.  See subsection “Fractional point
       sizes and new scale indicators” above.

       In AT&T troff the .pm request reports macro, string, and diversion
       sizes in units of 128-byte blocks, and an argument reduces the report
       to a sum of the above in the same units.  groff ignores any arguments
       and reports the sizes in bytes.

       In groff, there is a fundamental difference between unformatted input
       characters, and formatted output characters (glyphs).  Everything
       that affects how a glyph is output is stored with the glyph; once a
       glyph has been constructed, it is unaffected by any subsequent
       requests that are executed, including the .bd, .cs, .tkf, .tr, or .fp
       requests.  Normally, glyphs are constructed from input characters
       immediately before the glyph is added to the current output line.
       Macros, diversions, and strings are all, in fact, the same type of
       object; they contain lists of input characters and glyphs in any com‐
       bination.  Special characters can be both: before being added to the
       output, they act as input entities; afterwards, they denote glyphs.
       A glyph does not behave like an input character for the purposes of
       macro processing; it does not inherit any of the special properties
       that the input character from which it was constructed might have
       had.  The following example,
              .di x
              \\\\
              .br
              .di
              .x,
       prints “\\” in groff; each pair of input backslashes is turned into
       one output backslash and the resulting output backslashes are not
       interpreted as escape characters when they are reread.  AT&T troff
       would interpret them as escape characters when they were reread and
       would end up printing one “\”.

       One correct way to obtain a printable backslash in most documents is
       to use the \e escape sequence; this always prints a single instance
       of the current escape character, regardless of whether or not it is
       used in a diversion; it also works in both groff and AT&T troff.
       (Naturally, if you've changed the escape character, you need to pre‐
       fix the “e” with whatever it is—and you'll likely get something other
       than a backslash in the output.)

       The other correct way, appropriate in contexts independent of the
       backslash's common use as a roff escape character—perhaps in discus‐
       sion of character sets or other programming languages—is the charac‐
       ter escape \(rs or \[rs], for “reverse solidus”, from its name in the
       ECMA-6 (ISO/IEC 646) standard.  [This character escape is not porta‐
       ble to AT&T troff, but is to its lineal descendant, Heirloom Doctools
       troff, as of its 060716 release (July 2006).]

       To store an escape sequence in a diversion that is interpreted when
       the diversion is reread, either use the traditional \! transparent
       output facility, or, if this is unsuitable, the new \? escape
       sequence.  See subsection “Escape sequences” above and sections
       “Diversions” and “Gtroff Internals” in Groff: The GNU Implementation
       of troff, the groff Texinfo manual.

   Intermediate output format
       Its extensions notwithstanding, the groff intermediate output format
       has some incompatibilities with that of AT&T troff, but full compati‐
       bility is sought; problem reports and patches are welcome.  The fol‐
       lowing incompatibilities are known.

       ·      The positioning after drawing polygons conflicts with the
              AT&T troff practice.

       ·      The intermediate output cannot be rescaled to other devices as
              AT&T troff's could.

Authors         top

       This document was written by James Clark and modified by Werner
       Lemberg and Bernd Warken.

See Also         top

       Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner
       Lemberg, is the primary groff manual.  You can browse it
       interactively with “info groff”.

       “Troff User's Manual” by Joseph F. Ossanna, 1976 (revised by Brian W.
       Kernighan, 1992), AT&T Bell Laboratories Computing Science Techical
       Report No. 54, widely called simply “CSTR #54”, documents the
       language, device and font description file formats, and device-
       independent output format referred to collectively in groff
       documentation as “AT&T troff”.

       “A Typesetter-independent TROFF” by Brian W. Kernighan, 1982, AT&T
       Bell Laboratories Computing Science Techical Report No. 97, provides
       additional insights into the device and font description file formats
       and device-independent output format.

       groff(1), groff(7), roff(7)

COLOPHON         top

       This page is part of the groff (GNU troff) project.  Information
       about the project can be found at 
       ⟨http://www.gnu.org/software/groff/⟩.  If you have a bug report for
       this manual page, see ⟨http://www.gnu.org/software/groff/⟩.  This
       page was obtained from the project's upstream Git repository
       ⟨https://git.savannah.gnu.org/git/groff.git⟩ on 2020-08-13.  (At that
       time, the date of the most recent commit that was found in the repos‐
       itory was 2020-08-12.)  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 man-pages@man7.org

groff 1.22.4.234-3ba6          12 August 2020                  groff_diff(7)

Pages that refer to this page: groff(1)troff(1)groff_filenames(5)groff_out(5)groff(7)