Adding upstream version 1.23.0.upstream/1.23.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 18927 insertions, 0 deletions

diff --git a/doc/groff.texi b/doc/groff.texi
new file mode 100644
index 0000000..2a6635e
--- /dev/null
+++ b/doc/groff.texi
@@ -0,0 +1,18927 @@
+\input texinfo
+
+@c
+@c Please convert this manual with `texi2dvi -e groff.texi' due to
+@c problems in texinfo regarding expansion of user-defined macros.
+@c
+@c You need texinfo 5.0 or newer to format this document!
+@c
+
+@c %**start of header (This is for running Texinfo on a region.)
+@setfilename groff.info
+@settitle The GNU Troff Manual
+@setchapternewpage odd
+@footnotestyle separate
+@c %**end of header (This is for running Texinfo on a region.)
+
+@documentlanguage en
+@documentencoding ISO-8859-1
+
+
+@smallbook
+
+@finalout
+
+
+@copying
+This manual documents GNU @code{troff} version 1.23.0.
+
+Copyright @copyright{} 1994--2023 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
+copy of the license is included in the section entitled ``GNU Free
+Documentation License''.
+@end quotation
+@end copying
+
+
+@c We use the following indices:
+@c
+@c   cindex: concepts
+@c   rqindex: requests
+@c   esindex: escape sequences
+@c   vindex: registers
+@c   kindex: commands in font files
+@c   pindex: programs and files
+@c   tindex: environment variables
+@c   maindex: macros
+@c   stindex: strings
+@c   opindex: operators
+@c
+@c tindex and cindex are merged.
+
+@defcodeindex rq
+@defcodeindex es
+@defcodeindex ma
+@defcodeindex st
+@defcodeindex op
+@syncodeindex tp cp
+
+
+@c To avoid uppercasing in @deffn while converting to info, we define
+@c our special @Var{}.
+
+@macro Var{arg}
+@r{@slanted{\arg\}}
+@end macro
+
+
+@c To assure correct HTML translation, some ugly hacks are necessary.
+@c While processing a @def... request, the HTML translator looks at the
+@c next line to decide whether to start indentation, and if the line
+@c starts with @def... (e.g. @deffnx), indentation is started.  We must
+@c therefore ensure that a @def... is seen, during macro expansion.
+@c
+@c The following macros have to be used:
+@c
+@c One item:
+@c
+@c   @Def...
+@c
+@c Two items:
+@c
+@c   @Def...List
+@c   @Def...ListEnd
+@c
+@c More than two:
+@c
+@c   @Def...List
+@c   @Def...Item
+@c   @Def...Item
+@c   ...
+@c   @Def...ListEnd
+@c
+@c The definition block must end with
+@c
+@c   @endDef...
+@c
+@c The above is valid for texinfo 4.0f and above.
+@c
+@c By default, only the first item generates an index entry.  To
+@c override this, use a variant with a trailing `x' (like
+@c `@DefmacItemx').
+
+
+@c a dummy macro to assure the `@def...'
+
+@macro defdummy
+@c
+@end macro
+
+
+@c definition of requests
+
+@macro Defreq{name, arg}
+@deffn Request @t{.\name\} \arg\
+@rqindex \name\
+@c
+@end macro
+
+@macro DefreqList{name, arg}
+@deffn Request @t{.\name\} \arg\
+@defdummy
+@rqindex \name\
+@c
+@end macro
+
+@macro DefreqItem{name, arg}
+@deffnx Request @t{.\name\} \arg\
+@defdummy
+@c
+@end macro
+
+@macro DefreqItemx{name, arg}
+@deffnx Request @t{.\name\} \arg\
+@defdummy
+@rqindex \name\
+@c
+@end macro
+
+@macro DefreqListEnd{name, arg}
+@deffnx Request @t{.\name\} \arg\
+@c
+@end macro
+
+@macro DefreqListEndx{name, arg}
+@deffnx Request @t{.\name\} \arg\
+@rqindex \name\
+@c
+@end macro
+
+@macro endDefreq
+@end deffn
+@end macro
+
+
+@c definition of escape sequences
+
+@macro Defesc{name, delimI, arg, delimII}
+@deffn Escape@tie{}sequence @t{\name\\delimI\}@Var{\arg\}@t{\delimII\}
+@esindex \name\
+@c
+@end macro
+
+@macro DefescList{name, delimI, arg, delimII}
+@deffn Escape@tie{}sequence @t{\name\\delimI\}@Var{\arg\}@t{\delimII\}
+@defdummy
+@esindex \name\
+@c
+@end macro
+
+@macro DefescItem{name, delimI, arg, delimII}
+@deffnx Escape@tie{}sequence @t{\name\\delimI\}@Var{\arg\}@t{\delimII\}
+@defdummy
+@c
+@end macro
+
+@macro DefescItemx{name, delimI, arg, delimII}
+@deffnx Escape@tie{}sequence @t{\name\\delimI\}@Var{\arg\}@t{\delimII\}
+@defdummy
+@esindex \name\
+@c
+@end macro
+
+@macro DefescListEnd{name, delimI, arg, delimII}
+@deffnx Escape@tie{}sequence @t{\name\\delimI\}@Var{\arg\}@t{\delimII\}
+@c
+@end macro
+
+@macro DefescListEndx{name, delimI, arg, delimII}
+@deffnx Escape@tie{}sequence @t{\name\\delimI\}@Var{\arg\}@t{\delimII\}
+@esindex \name\
+@c
+@end macro
+
+@macro endDefesc
+@end deffn
+@end macro
+
+
+@c definition of registers (built in to GNU troff)
+
+@macro Defreg{name}
+@deffn Register @t{\\n[\name\]}
+@vindex \name\
+@c
+@end macro
+
+@macro DefregList{name}
+@deffn Register @t{\\n[\name\]}
+@defdummy
+@vindex \name\
+@c
+@end macro
+
+@macro DefregItem{name}
+@deffnx Register @t{\\n[\name\]}
+@defdummy
+@c
+@end macro
+
+@macro DefregItemx{name}
+@deffnx Register @t{\\n[\name\]}
+@defdummy
+@vindex \name\
+@c
+@end macro
+
+@macro DefregListEnd{name}
+@deffnx Register @t{\\n[\name\]}
+@c
+@end macro
+
+@macro DefregListEndx{name}
+@deffnx Register @t{\\n[\name\]}
+@vindex \name\
+@c
+@end macro
+
+@macro endDefreg
+@end deffn
+@end macro
+
+
+@c string definitions (built in to GNU troff)
+
+@macro Defstr{name}
+@deffn String @t{\\*[\name\]}
+@stindex \name\
+@c
+@end macro
+
+@macro DefstrList{name}
+@deffn String @t{\\*[\name\]}
+@defdummy
+@stindex \name\
+@c
+@end macro
+
+@macro DefstrItem{name}
+@deffnx String @t{\\*[\name\]}
+@defdummy
+@c
+@end macro
+
+@macro DefstrItemx{name}
+@deffnx String @t{\\*[\name\]}
+@defdummy
+@stindex \name\
+@c
+@end macro
+
+@macro DefstrListEnd{name}
+@deffnx String @t{\\*[\name\]}
+@c
+@end macro
+
+@macro DefstrListEndx{name}
+@deffnx String @t{\\*[\name\]}
+@stindex \name\
+@c
+@end macro
+
+@macro endDefstr
+@end deffn
+@end macro
+
+
+@c register definitions specific to macro packages, preprocessors, ...
+
+@macro Defmpreg{name, package}
+@deffn Register @t{\\n[\name\]}
+@vindex \name\ @r{[}\package\@r{]}
+@c
+@end macro
+
+@macro DefmpregList{name, package}
+@deffn Register @t{\\n[\name\]}
+@defdummy
+@vindex \name\ @r{[}\package\@r{]}
+@c
+@end macro
+
+@macro DefmpregItem{name, package}
+@deffnx Register @t{\\n[\name\]}
+@defdummy
+@c
+@end macro
+
+@macro DefmpregItemx{name, package}
+@deffnx Register @t{\\n[\name\]}
+@defdummy
+@vindex \name\ @r{[}\package\@r{]}
+@c
+@end macro
+
+@macro DefmpregListEnd{name, package}
+@deffnx Register @t{\\n[\name\]}
+@c
+@end macro
+
+@macro DefmpregListEndx{name, package}
+@deffnx Register @t{\\n[\name\]}
+@vindex \name\ @r{[}\package\@r{]}
+@c
+@end macro
+
+@macro endDefmpreg
+@end deffn
+@end macro
+
+
+@c definition of macros
+
+@macro Defmac{name, arg, package}
+@defmac @t{.\name\} \arg\
+@maindex \name\ @r{[}\package\@r{]}
+@c
+@end macro
+
+@macro DefmacList{name, arg, package}
+@defmac @t{.\name\} \arg\
+@defdummy
+@maindex \name\ @r{[}\package\@r{]}
+@c
+@end macro
+
+@macro DefmacItem{name, arg, package}
+@defmacx @t{.\name\} \arg\
+@defdummy
+@c
+@end macro
+
+@macro DefmacItemx{name, arg, package}
+@defmacx @t{.\name\} \arg\
+@defdummy
+@maindex \name\ @r{[}\package\@r{]}
+@c
+@end macro
+
+@macro DefmacListEnd{name, arg, package}
+@defmacx @t{.\name\} \arg\
+@c
+@end macro
+
+@macro DefmacListEndx{name, arg, package}
+@defmacx @t{.\name\} \arg\
+@maindex \name\ @r{[}\package\@r{]}
+@c
+@end macro
+
+@macro endDefmac
+@end defmac
+@end macro
+
+
+@c string definitions specific to macro packages, preprocessors, ...
+
+@macro Defmpstr{name, package}
+@deffn String @t{\\*[\name\]}
+@stindex \name\ @r{[}\package\@r{]}
+@c
+@end macro
+
+@macro DefmpstrList{name, package}
+@deffn String @t{\\*[\name\]}
+@defdummy
+@stindex \name\ @r{[}\package\@r{]}
+@c
+@end macro
+
+@macro DefmpstrItem{name, package}
+@deffnx String @t{\\*[\name\]}
+@defdummy
+@c
+@end macro
+
+@macro DefmpstrItemx{name, package}
+@deffnx String @t{\\*[\name\]}
+@defdummy
+@stindex \name\ @r{[}\package\@r{]}
+@c
+@end macro
+
+@macro DefmpstrListEnd{name, package}
+@deffnx String @t{\\*[\name\]}
+@c
+@end macro
+
+@macro DefmpstrListEndx{name, package}
+@deffnx String @t{\\*[\name\]}
+@stindex \name\ @r{[}\package\@r{]}
+@c
+@end macro
+
+@macro endDefmpstr
+@end deffn
+@end macro
+
+
+@c our example macros
+
+@macro Example
+@example
+@group
+@end macro
+
+@macro endExample
+@end group
+@end example
+@end macro
+
+@macro CartoucheExample
+@cartouche
+@example
+@end macro
+
+@macro endCartoucheExample
+@end example
+@end cartouche
+@end macro
+
+
+@c Render text with angle brackets around it, as in <text>.
+
+@macro angles{text}
+@guilsinglleft{}@r{\text\}@guilsinglright{}
+@end macro
+
+
+@c Note: We say `Roman numerals' but `roman font'.
+
+
+@dircategory Typesetting
+@direntry
+* Groff: (groff).               The GNU roff document formatting system.
+@end direntry
+
+
+@titlepage
+@title groff
+@subtitle The GNU implementation of @code{troff}
+@subtitle Edition 1.23.0
+@subtitle June 2023
+@author Trent@tie{}A.@: Fisher
+@author Werner Lemberg
+@author G.@tie{}Branden Robinson
+
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+@ifnottex
+@node Top, Introduction, (dir), (dir)
+@top GNU @code{troff}
+@end ifnottex
+
+@menu
+* Introduction::
+* Invoking groff::
+* Tutorial for Macro Users::
+* Major Macro Packages::
+* GNU troff Reference::
+* File Formats::
+* Copying This Manual::
+* Request Index::
+* Escape Sequence Index::
+* Operator Index::
+* Register Index::
+* Macro Index::
+* String Index::
+* File Keyword Index::
+* Program and File Index::
+* Concept Index::
+@end menu
+
+@ifnottex
+@insertcopying
+@end ifnottex
+
+
+
+@c =====================================================================
+@c =====================================================================
+
+@codequotebacktick on
+@codequoteundirected on
+
+@node Introduction, Invoking groff, Top, Top
+@chapter Introduction
+@cindex introduction
+
+GNU @code{roff} (or @code{groff}) is a programming system for
+typesetting documents.  It is highly flexible and has been used
+extensively for over thirty years.
+
+@menu
+* Background::
+* What Is @code{groff}?::
+* @code{groff} Capabilities::
+* Macro Package Intro::
+* Preprocessor Intro::
+* Output Device Intro::
+* Conventions Used in This Manual::
+* Installation::
+* Credits::
+@end menu
+
+
+@c =====================================================================
+
+@node Background, What Is @code{groff}?, Introduction, Introduction
+@section Background
+@cindex background
+
+M.@: Douglas McIlroy, formerly of AT&T Bell Laboratories and present at
+the creation of the Unix operating system, offers an authoritative
+historical summary.
+
+@quotation
+The prime reason for Unix was the desire of Ken [Thompson], Dennis
+[Ritchie], and Joe Ossanna to have a pleasant environment for software
+development.  The fig leaf that got the nod from @dots{}
+management was that an early use would be to develop a ``stand-alone''
+word-processing system for use in typing pools and secretarial offices.
+Perhaps they had in mind ``dedicated'', as distinct from
+``stand-alone''; that's what eventuated in various cases, most notably
+in the legal/patent department and in the AT&T CEO's office.
+
+Both those systems were targets of opportunity, not foreseen from the
+start.  When Unix was up and running on the PDP-11, Joe got wind of
+the legal department having installed a commercial word processor.
+He went to pitch Unix as an alternative and clinched a trial by
+promising to make @code{roff} able to number lines by tomorrow in order
+to fulfill a patent-office requirement that the commercial system did
+not support.
+
+Modems were installed so legal-department secretaries could try the
+Research machine.  They liked it and Joe's superb customer service.
+Soon the legal department got a system of their own.  Joe went on to
+create @code{nroff} and @code{troff}.  Document preparation became a
+widespread use of Unix, but no stand-alone word-processing system was
+ever undertaken.
+@end quotation
+@c https://minnie.tuhs.org/pipermail/tuhs/2022-March/025535.html
+
+A history relating @code{groff} to its predecessors @code{roff},
+@code{nroff}, and @code{troff} is available in the @cite{roff@r{(7)}}
+man page.
+
+
+@c =====================================================================
+
+@node What Is @code{groff}?, @code{groff} Capabilities, Introduction, Introduction
+@section What Is @code{groff}?
+@cindex what is @code{groff}?
+@cindex @code{groff}---what is it?
+
+@c BEGIN Keep parallel with groff(1), section "Description" (after the
+@c first sentence).
+@c This language is slightly expanded from that in the "ANNOUNCE" file
+@c and on the groff home page.
+@code{groff} (GNU @code{roff}) is a typesetting system that reads plain
+text input files that include formatting commands to produce output in
+PostScript, PDF, HTML, DVI, or other formats, or for display to a
+terminal.  Formatting commands can be low-level typesetting primitives,
+macros from a supplied package, or user-defined macros.  All three
+approaches can be combined.
+
+A reimplementation and extension of the typesetter from @acronym{AT&T}
+Unix, @code{groff} is present on most @acronym{POSIX} systems owing to
+its long association with Unix manuals (including man pages).  It and
+its predecessor are notable for their production of several best-selling
+software engineering texts.  @code{groff} is capable of producing
+typographically sophisticated documents while consuming minimal system
+resources.
+@c END Keep parallel with groff(1), section "Description" (after the
+@c first sentence).
+
+
+@c =====================================================================
+
+@node @code{groff} Capabilities, Macro Package Intro, What Is @code{groff}?, Introduction
+@section @code{groff} Capabilities
+@cindex @code{groff} capabilities
+@cindex capabilities of @code{groff}
+
+GNU @code{troff} is a typesetting document formatter; it provides a wide
+range of low-level text and page operations within the framework of a
+programming language.  These operations compose to generate footnotes,
+tables of contents, mathematical equations, diagrams, multi-column text,
+and other elements of typeset works.  Here is a survey of formatter
+features; all are under precise user control.
+
+@itemize @bullet
+@item
+text filling, breaking, alignment to the left or right margin; centering
+
+@item
+adjustment of inter-word space size to justify text, and of
+inter-sentence space size to suit local style conventions
+
+@item
+automatic and manual determination of hyphenation break points
+
+@item
+pagination
+
+@item
+selection of any font available to the output device
+
+@item
+adjustment of type size and vertical spacing (or ``leading'')
+
+@item
+configuration of line length and indentation amounts; columnation
+
+@item
+drawing of geometric primitives (lines, arcs, polygons, circles,
+@dots{})
+
+@item
+setup of stroke and fill colors (where supported by the output
+device)
+
+@item
+embedding of hyperlinks, images, document metadata, and other inclusions
+(where supported by the output device)
+@end itemize
+
+
+@c =====================================================================
+
+@node Macro Package Intro, Preprocessor Intro, @code{groff} Capabilities, Introduction
+@section Macro Packages
+@cindex macro package, introduction
+@cindex package, macro, introduction
+
+Elemental typesetting functions can be be challenging to use directly
+with complex documents.  A @dfn{macro} facility specifies how certain
+routine operations, such as starting paragraphs, or printing headers and
+footers, should be performed in terms of those low-level instructions.
+Macros can be specific to one document or collected together into a
+@dfn{macro package} for use by many.  Several macro packages available;
+the most widely used are provided with @code{groff}.  They are
+@file{man}, @file{mdoc}, @file{me}, @file{mm}, @file{mom}, and
+@file{ms}.
+
+
+@c =====================================================================
+
+@node Preprocessor Intro, Output Device Intro, Macro Package Intro, Introduction
+@section Preprocessors
+@cindex preprocessors
+
+An alternative approach to complexity management, particularly when
+constructing tables, setting mathematics, or drawing diagrams, lies in
+preprocessing.  A @dfn{preprocessor} employs a domian-specific language
+to ease the generation of tables, equations, and so forth in terms that
+are convenient for human entry.  Each preprocessor reads a document and
+translates the parts of it that apply to it into GNU @code{troff} input.
+Command-line options to @command{groff} tell it which preprocessors to
+use.
+
+@code{groff} provides preprocessors for laying out tables
+(@command{gtbl}), typesetting equations (@command{geqn}), drawing
+diagrams (@command{gpic} and @command{ggrn}), inserting bibliographic
+references (@command{grefer}), and drawing chemical structures
+(@command{gchem}).  An associated program that is useful when dealing
+with preprocessors is @command{gsoelim}.@footnote{The @samp{g} prefix is
+not used on all systems; see @ref{Invoking groff}.}
+
+@code{groff} also supports @code{grap}, a preprocessor for drawing
+graphs.  A free implementation of it can be obtained separately.
+
+Unique to @code{groff} is the @code{preconv} preprocessor that enables
+@code{groff} to handle documents in a variety of input encodings.
+
+Other preprocessors exist, but no free implementations
+are known.  An example is @command{ideal}, which draws diagrams using a
+mathematical constraint language.
+
+
+@c =====================================================================
+
+@node Output Device Intro, Installation, Preprocessor Intro, Introduction
+@section Output Devices
+@cindex postprocessors
+@cindex output devices
+@cindex devices for output
+
+GNU @code{troff}'s output is in a device-independent page description
+language, which is then read by an @dfn{output driver} that translates
+this language into a file format or byte stream that a piece of
+(possibly emulated) hardware understands.  @code{groff} features output
+drivers for PostScript devices, terminal emulators (and other simple
+typewriter-like machines), X11 (for previewing), @TeX{} DVI, HP
+LaserJet@tie{}4/PCL5 and Canon LBP printers (which use @acronym{CaPSL}),
+@acronym{HTML}, @acronym{XHTML}, and @acronym{PDF}.
+
+
+@c =====================================================================
+
+@node Installation, Conventions Used in This Manual, Output Device Intro, Introduction
+@section Installation
+@cindex installation
+
+Locate installation instructions in the files @file{INSTALL},
+@file{INSTALL.extra}, and @file{INSTALL.REPO} in the @code{groff} source
+distribution.  Being a GNU project, @code{groff} supports the familiar
+@samp{./configure && make} command sequence.
+
+
+@c =====================================================================
+
+@node Conventions Used in This Manual, Credits, Installation, Introduction
+@section Conventions Used in This Manual
+
+We apply the term ``groff'' to the language documented here, the GNU
+implementation of the overall system, the project that develops that
+system, and the command of that name.  In the first sense, @code{groff}
+is an extended dialect of the @code{roff} language, for which many
+similar implementations exist.
+
+The @code{roff} language features several major categories for which
+many items are predefined.  Presentations of these items feature the
+form in which the item is most commonly used on the left, and, aligned
+to the right margin, the name of the category in brackets.
+
+@deffn Register \n[example]
+The register @samp{example} is one that that @code{groff} @emph{doesn't}
+predefine.  You can create it yourself, though; see @ref{Setting
+Registers}.
+@end deffn
+
+To make this document useful as a reference and not merely amiable
+bedtime reading, we tend to present these syntax items in exhaustive
+detail when they arise.  References to topics discussed later in the
+text are frequent; skip material you don't understand yet.
+
+We use Texinfo's ``result'' (@result{}) and @error{} notations to
+present output written to the standard output and standard error
+streams, respectively.  Diagnostic messages from the GNU @code{troff}
+formatter and other programs are examples of the latter, but the
+formatter can also be directed to write user-specified messages to the
+standard error stream.  The notation then serves to identify the
+output stream and does not necessarily mean that an error has
+occurred.@footnote{Unix and related operating systems distinguish
+standard output and standard error streams @emph{because} of
+@code{troff}:@:
+@uref{https://minnie.tuhs.org/pipermail/tuhs/2013-December/006113.html}.}
+
+@Example
+$ echo "Twelve o'clock and" | groff -Tascii | sed '/^$/d'
+    @result{} Twelve o'clock and
+$ echo '.tm all is well.' | groff > /dev/null
+    @error{} all is well.
+@endExample
+
+Sometimes we use @result{} somewhat abstractly to represent formatted
+text that you will need to use a PostScript or PDF viewer program (or a
+printer) to observe.  While arguably an abuse of notation, we think this
+preferable to requiring the reader to understand the syntax of these
+page description languages.
+
+We also present diagnostic messages in an abbreviated form, often
+omitting the name of the program issuing them, the input file name, and
+line number or other positional information when such data do not serve
+to illuminate the topic under discussion.
+
+Most examples are of @code{roff} language input that would be placed in
+a text file.  Occasionally, we start an example with a @samp{$}
+character to indicate a shell prompt, as seen above.
+
+You are encouraged to try the examples yourself, and to alter them to
+better learn @code{groff}'s behavior.  Our examples frequently need to
+direct the formatter to set a line length (with @samp{.ll}) that will
+fit within the page margins of this manual.  We mention this so that you
+know why it is there before we discuss the @code{ll} request
+formally.@footnote{@xref{Line Layout}.}
+
+
+@c =====================================================================
+
+@node Credits,  , Conventions Used in This Manual, Introduction
+@section Credits
+@cindex credits
+
+We adapted portions of this manual from existing documents.  James
+Clark's man pages were an essential resource; we have updated them in
+parallel with the development of this manual.  We based the tutorial for
+macro users on Eric Allman's introduction to his @file{me} macro package
+(which we also provide, little altered from 4.4BSD).  Larry Kollar
+contributed much of the material on the @file{ms} macro package.
+
+
+@c =====================================================================
+@c =====================================================================
+
+@node Invoking groff, Tutorial for Macro Users, Introduction, Top
+@chapter Invoking @code{groff}
+@cindex invoking @code{groff}
+@cindex @code{groff} invocation
+
+This chapter focuses on how to invoke the @code{groff} front end.  This
+front end takes care of the details of constructing the pipeline among
+the preprocessors, @code{gtroff} and the postprocessor.
+
+It has become a tradition that GNU programs get the prefix @samp{g} to
+distinguish them from their original counterparts provided by the host
+(@pxref{Environment}).  Thus, for example, @code{geqn} is GNU
+@code{eqn}.  On operating systems like GNU/Linux or the Hurd, which
+don't contain proprietary versions of @code{troff}, and on
+MS-DOS/MS-Windows, where @code{troff} and associated programs are not
+available at all, this prefix is omitted since GNU @code{troff} is the
+only incarnation of @code{troff} used.  Exception: @samp{groff} is never
+replaced by @samp{roff}.
+
+In this document, we consequently say @samp{gtroff} when talking about
+the GNU @code{troff} program.  @c XXX: Not for much longer... -- GBR
+All other implementations of @code{troff} are called @acronym{AT&T}
+@code{troff}, which is the common origin of almost all @code{troff}
+implementations@footnote{Besides @code{groff}, @code{neatroff} is an
+exception.} (with more or less compatible changes).  Similarly, we say
+@samp{gpic}, @samp{geqn}, and so on.
+
+@menu
+* Groff Options::
+* Environment::
+* Macro Directories::
+* Font Directories::
+* Paper Format::
+* Invocation Examples::
+@end menu
+
+
+@c =====================================================================
+
+@node Groff Options, Environment, Invoking groff, Invoking groff
+@section Options
+@cindex options
+
+@pindex groff
+@pindex gtroff
+@pindex gpic
+@pindex geqn
+@pindex ggrn
+@pindex grap
+@pindex gtbl
+@pindex gchem
+@pindex grefer
+@pindex gsoelim
+@pindex preconv
+@code{groff} normally runs the @code{gtroff} program and a
+postprocessor appropriate for the selected device.  The default device
+is @samp{ps} (but it can be changed when @code{groff} is configured and
+built).  It can optionally preprocess with any of @code{gpic},
+@code{geqn}, @code{gtbl}, @code{ggrn}, @code{grap}, @code{gchem},
+@code{grefer}, @code{gsoelim}, or @code{preconv}.
+
+This section documents only options to the @code{groff} front end.  Many
+of the arguments to @code{groff} are passed on to @code{gtroff};
+therefore, those are also included.  Arguments to preprocessors and
+output drivers can be found in the man pages @cite{gpic@r{(1)}},
+@cite{geqn@r{(1)}}, @cite{gtbl@r{(1)}}, @cite{ggrn@r{(1)}},
+@cite{grefer@r{(1)}}, @cite{gchem@r{(1)}}, @cite{gsoelim@r{(1)}},
+@cite{preconv@r{(1)}}, @cite{grotty@r{(1)}}, @cite{grops@r{(1)}},
+@cite{gropdf@r{(1)}}, @cite{grohtml@r{(1)}}, @cite{grodvi@r{(1)}},
+@cite{grolj4@r{(1)}}, @cite{grolbp@r{(1)}}, and @cite{gxditview@r{(1)}}.
+
+The command-line format for @code{groff} is:
+
+@Example
+groff [ -abceghijklpstvzCEGNRSUVXZ ] [ -d@var{cs} ] [ -D@var{arg} ]
+      [ -f@var{fam} ] [ -F@var{dir} ] [ -I@var{dir} ] [ -K@var{arg} ]
+      [ -L@var{arg} ] [ -m@var{name} ] [ -M@var{dir} ] [ -n@var{num} ]
+      [ -o@var{list} ] [ -P@var{arg} ] [ -r@var{cn} ] [ -T@var{dev} ]
+      [ -w@var{name} ] [ -W@var{name} ] [ @var{files}@dots{} ]
+@endExample
+
+The command-line format for @code{gtroff} is as follows.
+
+@Example
+gtroff [ -abcivzCERU ] [ -d@var{cs} ] [ -f@var{fam} ] [ -F@var{dir} ]
+       [ -m@var{name} ] [ -M@var{dir} ] [ -n@var{num} ] [ -o@var{list} ]
+       [ -r@var{cn} ] [ -T@var{name} ] [ -w@var{name} ] [ -W@var{name} ]
+       [ @var{files}@dots{} ]
+@endExample
+
+@noindent
+Obviously, many of the options to @code{groff} are actually passed on to
+@code{gtroff}.
+
+Options without an argument can be grouped behind a
+single@tie{}@option{-}.  A filename of@tie{}@file{-} denotes the
+standard input.  Whitespace is permitted between an option and its
+argument.
+
+The @code{grog} command can be used to guess the correct @code{groff}
+command to format a file.  See its man page @cite{grog@r{(1)}}; type
+@samp{man grog} at the command line to view it.
+
+@command{groff}'s command-line options are as follows.
+
+@cindex command-line options
+@table @samp
+@item -a
+@cindex plain text approximation output register (@code{.A})
+Generate a plain text approximation of the typeset output.  The
+read-only register @code{.A} is set to@tie{}1.  @xref{Built-in
+Registers}.  This option produces a sort of abstract preview of the
+formatted output.
+
+@itemize @bullet
+@item
+Page breaks are marked by a phrase in angle brackets; for example,
+@samp{<beginning of page>}.
+
+@item
+Lines are broken where they would be in the formatted output.
+
+@item
+A horizontal motion of any size is represented as one space.  Adjacent
+horizontal motions are not combined.  Inter-sentence space nodes (those
+arising from the second argument to the @code{ss} request) are not
+represented.
+
+@item
+Vertical motions are not represented.
+
+@item
+Special characters are rendered in angle brackets; for example, the
+default soft hyphen character appears as @samp{<hy>}.
+@end itemize
+
+The above description should not be considered a specification; the
+details of @option{-a} output are subject to change.
+
+@item -b
+Write a backtrace reporting the state of @command{gtroff}'s input parser
+to the standard error stream with each diagnostic message.  The line
+numbers given in the backtrace might not always be correct, because
+@command{gtroff}'s idea of line numbers can be confused by requests that
+append to
+@c XXX: strings or (??? strings never contain newlines)
+macros.
+
+@item -c
+Start with color output disabled.
+
+@item -C
+Enable AT&T @command{troff} compatibility mode; implies @option{-c}.
+@xref{Implementation Differences}, for the list of incompatibilities
+between @command{groff} and @acronym{AT&T} @command{troff}.
+
+@item -d@var{c}@var{text}
+@itemx -d@var{string}=@var{text}
+Define @code{roff} string @var{c} or @var{string} as@tie{}@var{t} or
+@var{text}.  @var{c}@tie{}must be one character; @var{string} can be
+of arbitrary length.  Such string assignments happen before any macro
+file is loaded, including the startup file.  Due to @code{getopt_long}
+limitations, @var{c}@tie{}cannot be, and @var{string} cannot contain, an
+equals sign, even though that is a valid character in a @code{roff}
+identifier.
+
+@item -D@var{enc}
+Set fallback input encoding used by @command{preconv} to @var{enc};
+implies @option{-k}.
+
+@item -e
+Run @command{geqn} preprocessor.
+
+@item -E
+Inhibit @command{gtroff} error messages.  This option does @emph{not}
+suppress messages sent to the standard error stream by documents or
+macro packages using @code{tm} or related requests.
+
+@item -f@var{fam}
+Use @var{fam} as the default font family.  @xref{Font Families}.
+
+@item -F@var{dir}
+Search in directory @file{@var{dir}} for the selected output device's
+directory of device and font description files.  See the description of
+@env{GROFF_FONT_PATH} in @ref{Environment} below for the default search
+locations and ordering.
+
+@item -g
+Run @command{ggrn} preprocessor.
+
+@item -G
+Run @command{grap} preprocessor; implies @option{-p}.
+
+@item -h
+Display a usage message and exit.
+
+@item -i
+Read the standard input after all the named input files have been
+processed.
+
+@item -I@var{dir}
+Search the directory @var{dir} for files named in several contexts;
+implies @option{-g} and @option{-s}.
+
+@itemize
+@item
+@command{gsoelim} replaces @code{so} requests with the contents of their
+file name arguments.
+
+@item
+@command{gtroff} searches for files named as operands in its command
+line and as arguments to @code{psbb}, @code{so}, and @code{soquiet}
+requests.
+
+@item
+Output drivers may search for files; for instance, @command{grops} looks
+for files named in @samp{\X'ps: import @r{@dots{}}'}, @samp{\X'ps: file
+@r{@dots{}}'}, and @samp{\X'pdf: pdfpic @r{@dots{}}'} device control
+escape sequences.
+@end itemize
+
+This option may be specified more than once; the directories are
+searched in the order specified.  If you want to search the current
+directory before others, add @samp{-I .} at the desired place.  The
+current working directory is otherwise searched last.  @option{-I} works
+similarly to, and is named for, the ``include'' option of Unix C
+compilers.
+
+@option{-I} options are passed to @command{gsoelim}, @command{gtroff},
+and output drivers; with the flag letter changed to @option{-M}, they
+are also passed to @command{ggrn}.
+
+@item -j
+Run @command{gchem} preprocessor.  Implies @option{-p}.
+
+@item -k
+Run @command{preconv} preprocessor.  Refer to its man page for its
+behavior if neither of @command{groff}'s @option{-K} or @option{-D}
+options is also specified.
+
+@item -K@var{enc}
+Set input encoding used by @command{preconv} to @var{enc}; implies
+@option{-k}.
+
+@item -l
+Send the output to a spooler for printing.  The @code{print} directive
+in the device description file specifies the default command to be used;
+see @ref{Device and Font Description Files}.
+@c XXX: This document is not parameterized in configuration variables.
+@c If no such directive is present for the output device,
+@c .ie '@PSPRINT@'' \{\
+@c this option is ignored.
+@c .\}
+@c .el \{\
+@c output is piped to
+@c .MR @PSPRINT@ 1 .
+@c .\}
+See options @option{-L} and @option{-X}.
+
+@item -L@var{arg}
+Pass @var{arg} to the print spooler program.  If multiple @var{arg}s are
+required, pass each with a separate @option{-L} option.  @command{groff}
+does not prefix an option dash to @var{arg} before passing it to the
+spooler program.
+
+@item -m@var{name}
+Process the file @file{@var{name}.tmac} prior to any input files.
+If not found, @file{tmac.@var{name}} is attempted.  @var{name}
+(in both arrangements) is presumed to be a macro file; see the
+description of @env{GROFF_TMAC_PATH} in @ref{Environment} below for the
+default search locations and ordering.  This option and its argument are
+also passed to @command{geqn}, @command{grap}, and @command{ggrn}.
+
+@item -M@var{dir}
+Search directory @file{@var{dir}} for macro files;  see the description
+of @env{GROFF_TMAC_PATH} in @ref{Environment} below for the default
+search locations and ordering.  This option and its argument are also
+passed to @command{geqn}, @command{grap}, and @command{ggrn}.
+
+@item -n@var{num}
+Number the first page @var{num}.
+
+@item -N
+Prohibit newlines between @code{eqn} delimiters:@: pass @option{-N} to
+@command{geqn}.
+
+@item -o@var{list}
+@cindex print current page register (@code{.P})
+Output only pages in @var{list}, which is a comma-separated list of page
+ranges; @samp{@var{n}} means page@tie{}@var{n}, @samp{@var{m}-@var{n}}
+means every page between @var{m} and@tie{}@var{n}, @samp{-@var{n}} means
+every page up to@tie{}@var{n}, @samp{@var{n}-} means every page from
+@var{n}@tie{}on.  @command{gtroff} stops processing and exits after
+formatting the last page enumerated in @var{list}.
+
+@item -p
+Run @command{gpic} preprocessor.
+
+@item -P@var{arg}
+Pass @var{arg} to the postprocessor.  If multiple @var{arg}s are
+required, pass each with a separate @option{-P} option.  @command{groff}
+does not prefix an option dash to @var{arg} before passing it to the
+postprocessor.
+
+@item -r@var{c}@var{numeric-expression}
+@itemx -r@var{register}=@var{expr}
+Set @code{roff} register@tie{}@var{c} or @var{register} to the value
+@var{numeric-expression} (@pxref{Numeric Expressions}).
+@var{c}@tie{}must be one character; @var{register} can be of arbitrary
+length.  Such register assignments happen before any macro file is
+loaded, including the startup file.  Due to @code{getopt_long}
+limitations, @var{c}@tie{}cannot be, and @var{register} cannot contain,
+an equals sign, even though that is a valid character in a @code{roff}
+identifier.
+
+@item -R
+Run @command{grefer} preprocessor.  No mechanism is provided for passing
+arguments to @command{grefer} because most @command{grefer} options have
+equivalent language elements that can be specified within the document.
+
+@pindex troffrc
+@pindex troffrc-end
+@command{gtroff} also accepts a @option{-R} option, which is not
+accessible via @command{groff}.  This option prevents the loading of the
+@file{troffrc} and @file{troffrc-end} files.
+
+@item -s
+Run @command{gsoelim} preprocessor.
+
+@item -S
+@cindex @code{open} request, and safer mode
+@cindex @code{opena} request, and safer mode
+@cindex @code{pso} request, and safer mode
+@cindex @code{sy} request, and safer mode
+@cindex @code{pi} request, and safer mode
+@cindex safer mode
+@cindex mode, safer
+Operate in ``safer'' mode; see @option{-U} below for its opposite.  For
+security reasons, safer mode is enabled by default.
+
+@item -t
+Run @command{gtbl} preprocessor.
+
+@item -T@var{dev}
+Direct @command{gtroff} to format the input for the output device
+@var{dev}.  @command{groff} then calls an output driver to convert
+@command{gtroff}'s output to a form appropriate for @var{dev}.  The
+following output devices are available.
+
+@table @code
+@item ps
+For PostScript printers and previewers.
+
+@item pdf
+For @acronym{PDF} viewers or printers.
+
+@item dvi
+For @TeX{} DVI format.
+
+@item X75
+For a 75@dmn{dpi} X11 previewer.
+
+@item X75-12
+For a 75@dmn{dpi} X11 previewer with a 12-point base font in the
+document.
+
+@item X100
+For a 100@dmn{dpi} X11 previewer.
+
+@item X100-12
+For a 100@dmn{dpi} X11 previewer with a 12-point base font in the
+document.
+
+@item ascii
+@cindex encoding, output, @acronym{ASCII}
+@cindex encoding, output, ISO@tie{}646
+@cindex @acronym{ASCII} output encoding
+@cindex ISO@tie{}646 output encoding
+@cindex output encoding, @acronym{ASCII}
+@cindex output encoding, ISO@tie{}646
+For typewriter-like devices using the (7-bit) @acronym{ASCII}
+(ISO@tie{}646) character set.
+
+@item latin1
+@cindex encoding, output, @w{Latin-1} (ISO @w{8859-1})
+@cindex @w{Latin-1} (ISO @w{8859-1}) output encoding
+@cindex ISO @w{8859-1} (@w{Latin-1}) output encoding
+@cindex output encoding, @w{Latin-1} (ISO @w{8859-1})
+For typewriter-like devices that support the @w{Latin-1}
+(ISO@tie{}@w{8859-1}) character set.
+
+@item utf8
+@cindex encoding, output, @w{UTF-8}
+@cindex @w{UTF-8} output encoding
+@cindex output encoding, @w{UTF-8}
+For typewriter-like devices that use the Unicode (ISO@tie{}10646)
+character set with @w{UTF-8} encoding.
+
+@item cp1047
+@cindex encoding, output, @acronym{EBCDIC}
+@cindex @acronym{EBCDIC} output encoding
+@cindex output encoding, @acronym{EBCDIC}
+@cindex encoding, output, code page 1047
+@cindex code page 1047 output encoding
+@cindex output encoding, code page 1047
+@cindex IBM code page 1047 output encoding
+@cindex CCSID 1047 output encoding (EBCDIC)
+For typewriter-like devices that use the @acronym{EBCDIC} encoding IBM
+code page 1047.
+
+@item lj4
+For HP LaserJet4-compatible (or other PCL5-compatible) printers.
+
+@item lbp
+For Canon @acronym{CaPSL} printers (@w{LBP-4} and @w{LBP-8} series laser
+printers).
+
+@pindex pre-grohtml
+@pindex post-grohtml
+@cindex @code{grohtml}, the program
+@item html
+@itemx xhtml
+To produce @acronym{HTML} and @acronym{XHTML} output, respectively.
+This driver consists of two parts, a preprocessor
+(@command{pre-grohtml}) and a postprocessor (@command{post-grohtml}).
+@end table
+
+@cindex output device name string (@code{.T})
+@cindex output device usage register (@code{.T})
+The predefined GNU @code{troff} string @code{.T} contains the name of
+the output device; the read-only register @code{.T} is set to@tie{}1 if
+this option is used (which is always true if @command{groff} is used to
+call GNU @command{troff}).  @xref{Built-in Registers}.
+
+The postprocessor to be used for a device is specified by the
+@code{postpro} command in the device description file.  (@xref{Device
+and Font Description Files}.)  This can be overridden with the
+@option{-X} option.
+
+@item -U
+@cindex mode, unsafe
+@cindex unsafe mode
+Operate in @dfn{unsafe mode}, which enables the @code{open},
+@code{opena}, @code{pi}, @code{pso}, and @code{sy} requests.  These
+requests are disabled by default because they allow an untrusted input
+document to write to arbitrary file names and run arbitrary commands.
+This option also adds the current directory to the macro package search
+path; see the @option{-m} option above.  @option{-U} is passed to
+@command{gpic} and @command{gtroff}.
+
+@item -v
+Write version information for @command{groff} and all programs run by it
+to the standard output stream; that is, the given command line is
+processed in the usual way, passing @option{-v} to the formatter and any
+pre- or postprocessors invoked.
+
+@item -V
+Output the pipeline that would be run by @command{groff}
+(as a wrapper program) to the standard output stream, but do not execute
+it.  If given more than once, the pipeline is both written to the
+standard error stream and run.
+
+@item -w@var{category}
+Enable warnings in @var{category}.  Categories are listed in
+@ref{Warnings}.
+
+@item -W@var{category}
+Inhibit warnings in @var{category}.  Categories are listed in
+@ref{Warnings}.
+
+@item -X
+Use @command{gxditview} instead of the usual postprocessor to (pre)view
+a document on an X11 display.  Combining this option with
+@option{-Tps} uses the font metrics of the PostScript device, whereas
+the @option{-TX75} and @option{-TX100} options use the metrics of X11
+fonts.
+
+@item -z
+Suppress formatted output from @command{gtroff}.
+
+@item -Z
+Disable postprocessing.  @command{gtroff} output will appear on the
+standard output stream (unless suppressed with @option{-z}; see
+@ref{gtroff Output} for a description of this format.
+@end table
+
+
+@c =====================================================================
+
+@node Environment, Macro Directories, Groff Options, Invoking groff
+@section Environment
+@cindex environment variables
+@cindex variables in environment
+
+There are also several environment variables (of the operating system,
+not within @code{gtroff}) that can modify the behavior of @code{groff}.
+
+@table @code
+@item GROFF_BIN_PATH
+@tindex GROFF_BIN_PATH@r{, environment variable}
+This search path, followed by @code{PATH}, is used for commands executed
+by @code{groff}.
+
+@item GROFF_COMMAND_PREFIX
+@tindex GROFF_COMMAND_PREFIX@r{, environment variable}
+@cindex command prefix
+@cindex prefix, for commands
+If this is set to@tie{}@var{X}, then @command{groff} runs
+@command{@var{X}troff} instead of @command{gtroff}.  This also applies
+to @command{tbl}, @command{pic}, @command{eqn}, @command{grn},
+@command{chem}, @command{refer}, and @command{soelim}.  It does not
+apply to @command{grops}, @command{grodvi}, @command{grotty},
+@command{pre-grohtml}, @command{post-grohtml}, @command{preconv},
+@command{grolj4}, @command{gropdf}, and @command{gxditview}.
+
+The default command prefix is determined during the installation
+process.  If a non-GNU @code{troff} system is found, prefix @samp{g} is
+used, none otherwise.
+
+@item GROFF_ENCODING
+@tindex GROFF_ENCODING@r{, environment variable}
+The value of this variable is passed to the @code{preconv}
+preprocessor's @option{-e} option to select the character encoding of
+input files.  This variable's existence implies the @code{groff} option
+@option{-k}.  If set but empty, @code{groff} calls @code{preconv}
+without an @option{-e} option.  @code{groff}'s @option{-K} option
+overrides @env{GROFF_ENCODING}.  See the @cite{preconv@r{(7)}} man page;
+type @samp{man preconv} at the command line to view it.
+
+@item GROFF_FONT_PATH
+@tindex GROFF_FONT_PATH@r{, environment variable}
+A list of directories in which to seek the selected output device's
+directory of device and font description files.  GNU @code{troff}
+will search directories given as arguments to any specified @option{-F}
+options before these, and a built-in list of directories after them.
+@xref{Font Directories} and the @cite{troff@r{(1)}} or
+@cite{gtroff@r{(1)}} man pages.
+
+@item GROFF_TMAC_PATH
+@tindex GROFF_TMAC_PATH@r{, environment variable}
+A list of directories in which to seek macro files.  GNU @code{troff}
+will search directories given as arguments to any specified @option{-M}
+options before these, and a built-in list of directories after them.
+@xref{Macro Directories} and the @cite{troff@r{(1)}} or
+@cite{gtroff@r{(1)}} man pages.
+
+@item GROFF_TMPDIR
+@tindex GROFF_TMPDIR@r{, environment variable}
+@tindex TMPDIR@r{, environment variable}
+The directory in which @code{groff} creates temporary files.  If this is
+not set and @env{TMPDIR} is set, temporary files are created in that
+directory.  Otherwise temporary files are created in a system-dependent
+default directory (on Unix and GNU/Linux systems, this is usually
+@file{/tmp}).  @code{grops}, @code{grefer}, @code{pre-grohtml}, and
+@code{post-grohtml} can create temporary files in this directory.
+
+@item GROFF_TYPESETTER
+@tindex GROFF_TYPESETTER@r{, environment variable}
+Sets the default output device.  If empty or not set, a build-time
+default (often @code{ps}) is used.  The @option{-T@var{dev}} option
+overrides @env{GROFF_TYPESETTER}.
+
+@item SOURCE_DATE_EPOCH
+@tindex SOURCE_DATE_EPOCH@r{, environment variable}
+A timestamp (expressed as seconds since the Unix epoch) to use as the
+output creation timestamp in place of the current time.  The time is
+converted to human-readable form using @cite{localtime@r{(3)}} when the
+formatter starts up and stored in registers usable by documents and
+macro packages (@pxref{Built-in Registers}).
+
+@item TZ
+@tindex TZ@r{, environment variable}
+The time zone to use when converting the current time (or value of
+@env{SOURCE_DATE_EPOCH}) to human-readable form; see
+@cite{tzset@r{(3)}}.
+@end table
+
+MS-DOS and MS-Windows ports of @code{groff} use semicolons, rather than
+colons, to separate the directories in the lists described above.
+
+
+@c =====================================================================
+
+@node Macro Directories, Font Directories, Environment, Invoking groff
+@section Macro Directories
+@cindex macro directories
+@cindex directories for macros
+@cindex searching macros
+@cindex macros, searching
+
+A macro file must have a name in the form @code{@var{name}.tmac} or
+@code{tmac.@var{name}} and be placed in a @dfn{tmac directory} to be
+found by the @option{-m@var{name}} command-line option.@footnote{The
+@code{mso} request does not have these limitations.  @xref{I/O}.}
+@cindex tmac, directory
+@cindex directory, for tmac files
+@cindex tmac, path
+@cindex path, for tmac files
+@cindex locating macro files
+@cindex macro file search path
+@cindex file, macro, search path
+@cindex locating macro packages
+@cindex macro package search path
+@cindex package, macro, search path
+Together, these directories constitute the @dfn{tmac path}.  Each
+directory is searched in the following order until the desired macro
+file is found or the list is exhausted.
+
+@itemize @bullet
+@item
+Directories specified with GNU @code{troff}'s or @code{groff}'s
+@option{-M} command-line option.
+
+@item
+@tindex GROFF_TMAC_PATH@r{, environment variable}
+Directories listed in the @env{GROFF_TMAC_PATH} environment variable.
+
+@item
+@cindex safer mode
+@cindex mode, safer
+@cindex unsafe mode
+@cindex mode, unsafe
+@cindex current directory
+@cindex directory, current
+The current working directory (only if in unsafe mode using the
+@option{-U} command-line option).
+
+@item
+@cindex home directory
+@cindex directory, home
+The user's home directory, @env{HOME}.
+
+@item
+@cindex site-local directory
+@cindex directory, site-local
+@cindex platform-specific directory
+@cindex directory, platform-specific
+A platform-dependent directory, a site-local (platform-independent)
+directory, and the main @slanted{tmac} directory.  The locations
+corresponding to your installation are listed in section ``Environment''
+of @cite{gtroff@r{(1)}}.  If not otherwise configured, they are as
+follows.
+
+@Example
+/usr/local/lib/groff/site-tmac
+/usr/local/share/groff/site-tmac
+/usr/local/share/groff/1.23.0/tmac
+@endExample
+
+@noindent
+The foregoing assumes that the version of @code{groff} is 1.23.0, and
+that the installation prefix was @file{/usr/local}.  It is possible to
+fine-tune these locations during the source configuration process.
+@end itemize
+
+
+@c =====================================================================
+
+@node Font Directories, Paper Format, Macro Directories, Invoking groff
+@section Font Directories
+@cindex font directories
+@cindex directories for fonts
+@cindex searching fonts
+@cindex fonts, searching
+
+@code{groff} enforces few restrictions on how font description files are
+named.  For its family/style mechanism to work (@pxref{Font Families}),
+the names of fonts within a family should start with the family name,
+followed by the style.  For example, the Times family uses @samp{T} for
+the family name and @samp{R}, @samp{B}, @samp{I}, and @samp{BI} to
+indicate the styles `roman', `bold', `italic', and `bold italic',
+respectively.  Thus the final font names are @samp{TR}, @samp{TB},
+@samp{TI}, and @samp{TBI}.
+
+@cindex font path
+@cindex path, for font files
+Font description files are kept in @dfn{font directories}, which
+together constitute the @dfn{font path}.  The search procedure
+always appends the directory @code{dev}@var{name}, where @var{name} is
+the name of the output device.  Assuming @TeX{} DVI output, and
+@file{/foo/bar} as a font directory, the font description files for
+@command{grodvi} must be in @file{/foo/bar/devdvi}.
+Each directory in the font path is searched in the following order until
+the desired font description file is found or the list is exhausted.
+
+@itemize @bullet
+@item
+Directories specified with GNU @code{troff}'s or @code{groff}'s
+@option{-f} command-line option.  All output drivers (and some
+preprocessors) support this option as well, because they require
+information about the glyphs to be rendered in the document.
+
+@item
+@tindex GROFF_FONT_PATH@r{, environment variable}
+Directories listed in the @env{GROFF_FONT_PATH} environment variable.
+
+@item
+@cindex site-local directory
+@cindex directory, site-local
+A site-local directory and the main font description directory.
+The locations corresponding to your installation are listed in section
+``Environment'' of @cite{gtroff@r{(1)}}.  If not otherwise configured,
+they are as follows.
+
+@Example
+/usr/local/share/groff/site-font
+/usr/local/share/groff/1.23.0/font
+@endExample
+
+@noindent
+The foregoing assumes that the version of @code{groff} is 1.23.0, and
+that the installation prefix was @file{/usr/local}.  It is possible to
+fine-tune these locations during the source configuration process.
+@end itemize
+
+
+@c =====================================================================
+
+@node Paper Format, Invocation Examples, Font Directories, Invoking groff
+@section Paper Format
+@cindex paper format
+@cindex format, paper
+@cindex paper size
+@cindex size, paper
+@cindex landscape page orientation
+@cindex orientation, landscape
+@cindex page orientation, landscape
+
+In @code{groff}, the page dimensions for the formatter GNU @code{troff}
+and for output devices are handled separately.  @xref{Page Layout}, for
+vertical manipulation of the page size, and @xref{Line Layout}, for
+horizontal changes.
+@pindex papersize.tmac
+@pindex troffrc
+The @file{papersize} macro package, normally loaded by @file{troffrc} at
+startup, provides an interface for configuring page dimensions by
+convenient names, like @samp{letter} or @samp{a4}; see
+@cite{groff_tmac@r{(5)}}.  The default used by the formatter depends on
+its build configuration, but is usually one of the foregoing, as
+geographically appropriate.
+@c groff(1), being generated, says what the default is.
+
+It is up to each macro package to respect the page dimensions configured
+in this way.
+
+For each output device, the size of the output medium can be set in its
+@file{DESC} file.  Most output drivers also recognize a command-line
+option @option{-p} to override the default dimensions and an option
+@option{-l} to use landscape orientation.  @xref{DESC File Format}, for
+a description of the @code{papersize} keyword, which takes an argument
+of the same form as @option{-p}.  The output driver's man page, such as
+@cite{grops@r{(1)}}, may also be helpful.
+
+@code{groff} uses the command-line option @option{-P} to pass options to
+postprocessors; for example, use the following for PostScript output on
+A4 paper in landscape orientation.
+
+@Example
+groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps
+@endExample
+
+
+@c =====================================================================
+
+@c BEGIN Keep parallel with groff(1), section "Examples".
+@node Invocation Examples,  , Paper Format, Invoking groff
+@section Invocation Examples
+@cindex invocation examples
+@cindex examples of invocation
+
+@code{roff} systems are best known for formatting man pages.  Once a
+@command{man} librarian program has located a man page, it may execute
+a @code{groff} command much like the following.
+
+@Example
+groff -t -man -Tutf8 /usr/share/man/man1/groff.1
+@endExample
+
+The librarian will also pipe the output through a pager, which might not
+interpret the SGR terminal escape sequences @command{groff} emits for
+boldface, underlining, or italics; see the @cite{grotty@r{(1)}} man page
+for a discussion.
+
+To process a @code{roff} input file using the preprocessors
+@command{gtbl} and @command{gpic} and the @file{me} macro package in the
+way to which AT&T @code{troff} users were accustomed, one would type (or
+script) a pipeline.
+
+@Example
+gpic foo.me | gtbl | gtroff -me -Tutf8 | grotty
+@endExample
+
+Using @command{groff}, this pipe can be shortened to an equivalent
+command.
+
+@Example
+groff -p -t -me -T utf8 foo.me
+@endExample
+
+An even easier way to do this is to use @command{grog} to guess the
+preprocessor and macro options and execute the result by using the
+command substitution feature of the shell.
+
+@Example
+$(grog -Tutf8 foo.me)
+@endExample
+
+Each command-line option to a postprocessor must be specified with any
+required leading dashes @samp{-}
+@c No GNU roff postprocessor uses long options for anything except
+@c --help or --version.
+@c or @samp{--}
+@c XXX: grolbp does.
+because @command{groff} passes the arguments as-is to the postprocessor;
+this permits arbitrary arguments to be transmitted.  For example, to
+pass a title to the @command{gxditview} postprocessor,
+the shell commands
+
+@Example
+groff -X -P -title -P 'trial run' mydoc.t
+@endExample
+
+@noindent
+and
+
+@Example
+groff -X -Z mydoc.t | gxditview -title 'trial run' -
+@endExample
+
+@noindent
+are equivalent.
+@c END Keep parallel with groff(1), section "Examples".
+
+
+
+@c =====================================================================
+@c =====================================================================
+
+@node Tutorial for Macro Users, Major Macro Packages, Invoking groff, Top
+@chapter Tutorial for Macro Users
+@cindex tutorial for macro users
+@cindex macros, tutorial for users
+@cindex user's tutorial for macros
+@cindex user's macro tutorial
+
+Most users of the @code{roff} language employ a macro package to format
+their documents.  Successful macro packages ease the composition
+process; their users need not have mastered the full formatting
+language, nor understand features like diversions, traps, and
+environments.  This chapter aims to familiarize you with basic concepts
+and mechanisms common to many macro packages (like ``displays'').  If
+you prefer a meticulous and comprehensive presentation, try @ref{GNU
+troff Reference} instead.
+
+@menu
+* Basics::
+* Common Features::
+@end menu
+
+
+@c =====================================================================
+
+@node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro Users
+@section Basics
+@cindex basics of macro package usage
+@cindex macro package usage, basics of
+
+Let us first survey some basic concepts necessary to use a macro package
+fruitfully.@footnote{The remainder of this chapter is based on
+@cite{Writing Papers with nroff using -me} by Eric@tie{}P.@: Allman,
+which is distributed with @code{groff} as @file{meintro.me}.}
+References are made throughout to more detailed information.
+
+GNU @code{troff} reads an input file prepared by the user and outputs a
+formatted document suitable for publication or framing.  The input
+consists of text, or words to be printed, and embedded commands
+(@slanted{requests} and @slanted{escape sequences}), which tell GNU
+@code{troff} how to format the output.  @xref{Formatter Instructions}.
+
+The word @slanted{argument} is used in this chapter to mean a word or
+number that appears on the same line as a request, and which modifies
+the meaning of that request.  For example, the request
+
+@Example
+.sp
+@endExample
+
+@noindent
+spaces one line, but
+
+@Example
+.sp 4
+@endExample
+
+@noindent
+spaces four lines.  The number@tie{}4 is an argument to the @code{sp}
+request, which says to space four lines instead of one.  Arguments are
+separated from the request and from each other by spaces (@emph{not}
+tabs).  @xref{Invoking Requests}.
+
+The primary function of GNU @code{troff} is to collect words from input
+lines, fill output lines with those words, adjust the line to the
+right-hand margin by widening spaces, and output the result.  For
+example, the input:
+
+@Example
+Now is the time
+for all good men
+to come to the aid
+of their party.
+Four score and seven
+years ago, etc.
+@endExample
+
+@noindent
+is read, packed onto output lines, and justified to produce:
+
+@Example
+  @result{} Now is the time for all good men to come to the aid of
+  @result{} their party.  Four score and seven years ago, etc.
+@endExample
+
+Sometimes a new output line should be started even though the current
+line is not yet full---for example, at the end of a paragraph.  To do
+this it is possible to force a @slanted{break}, starting a new output
+line.  Some requests cause a break automatically, as do (normally) blank
+input lines and input lines beginning with a space or tab.
+
+Not all input lines are @slanted{text lines}---words to be formatted.
+Some are @slanted{control lines} that tell a macro package (or GNU
+@code{troff} directly) how to format the text.  Control lines start with
+a dot (@samp{.}) or an apostrophe (@samp{'}) as the first character, and
+can be followed by a @slanted{macro call}.
+
+The formatter also does more complex things, such as automatically
+numbering pages, skipping over page boundaries, putting footnotes in the
+correct place, and so forth.
+
+Here are a few hints for preparing text for input to GNU @code{troff}.
+
+@itemize @bullet
+@item
+First, keep the input lines short.  Short input lines are easier to
+edit, and GNU @code{troff} packs words onto longer lines anyhow.
+
+@item
+In keeping with this, it is helpful to begin a new line after every
+comma or phrase, since common corrections are to add or delete sentences
+or phrases.
+
+@item
+End each sentence with two spaces---or better, start each sentence on a
+new line.  GNU @code{troff} recognizes characters that usually end a
+sentence, and inserts inter-sentence space accordingly.
+
+@item
+Do not hyphenate words at the end of lines---GNU @code{troff} is smart
+enough to hyphenate words as needed, but is not smart enough to take
+hyphens out and join a word back together.  Also, words such as
+``mother-in-law'' should not be broken over a line, since then a space
+can occur where not wanted, such as ``@w{mother- in}-law''.
+@end itemize
+
+We offer further advice in @ref{Input Conventions}.
+
+@cindex vertical spacing (introduction)
+@cindex spacing, vertical (introduction)
+GNU @code{troff} permits alteration of the distance between lines of
+text.  This is termed @slanted{vertical spacing} and is expressed in the
+same units as the type size---the point.  The default is 10-point type
+on 12-point spacing.  To get @slanted{double-spaced} text you would set
+the vertical spacing to 24 points.  Some, but not all, macro packages
+expose a macro or register to configure the vertical spacing.
+
+A number of requests allow you to change the way the output is arranged
+on the page, sometimes called the @slanted{layout} of the output page.
+Most macro packages don't supply macros for performing these (at least
+not without performing other actions besides), as they are such basic
+operations.  The macro packages for writing man pages, @file{man} and
+@file{mdoc}, don't encourage explicit use of these requests at all.
+
+@cindex spacing (introduction)
+The request @w{@samp{.sp @var{N}}} leaves @var{N}@tie{}lines of blank
+space.  @var{N}@tie{}can be omitted (skipping a single line) or can
+be of the form @var{N}i (for @var{N}@tie{}inches) or @var{N}c (for
+@var{N}@tie{}centimeters).  For example, the input:
+
+@Example
+.sp 1.5i
+My thoughts on the subject
+.sp
+@endExample
+
+@noindent
+leaves one and a half inches of space, followed by the line ``My
+thoughts on the subject'', followed by a single blank line (more
+measurement units are available; see @ref{Measurements}).
+
+If you seek precision in spacing, be advised when using a macro package
+that it might not honor @code{sp} requests as you expect; it can use a
+formatter feature called @slanted{no-space mode} to prevent excess space
+from accumulating.  Macro packages typically offer registers to control
+spacing between paragraphs, before section headings, and around displays
+(discussed below); use these facilities preferentially.
+@xref{Manipulating Spacing}.
+
+@cindex centering lines (introduction)
+@cindex lines, centering (introduction)
+Text lines can be centered by using the @code{ce} request.  The line
+after @code{ce} is centered (horizontally) on the page.  To center more
+than one line, use @w{@samp{.ce @var{N}}} (where @var{N} is the number
+of lines to center), followed by the @var{N}@tie{}lines.  To center many
+lines without counting them, type:
+
+@Example
+.ce 1000
+lines to center
+.ce 0
+@endExample
+
+@noindent
+The @w{@samp{.ce 0}} request tells GNU @code{troff} to center zero more
+lines, in other words, stop centering.
+
+@cindex right-aligning lines (introduction)
+@cindex lines, right-aligning (introduction)
+@cindex right-justifying lines (introduction)
+@cindex lines, right-justifying (introduction)
+GNU @code{troff} also offers the @code{rj} request for right-aligning
+text.  It works analogously to @code{ce} and is convenient for setting
+epigraphs.
+
+@cindex page break (introduction)
+@cindex break, page (introduction)
+The @code{bp} request starts a new page; this necessarily implies an
+ordinary (line) break.
+
+@cindex break (introduction)
+@cindex line break (introduction)
+All of these requests cause a break; that is, they always start a new
+line.  To start a new line without performing any other action, use
+@code{br}.  If you invoke them with the apostrophe @samp{'}, the
+@slanted{no-break control character}, the (initial) break they normally
+perform is suppressed.  @samp{'br} does nothing.
+
+
+@c =====================================================================
+
+@node Common Features,  , Basics, Tutorial for Macro Users
+@section Common Features
+@cindex common features
+@cindex features, common
+
+GNU @code{troff} provides low-level operations for formatting a
+document.  Many routine operations are undertaken in nearly all
+documents that require a series of such primitive operations to be
+performed.  These common tasks are grouped into @slanted{macros}, which
+are then collected into a @slanted{macro package}.
+
+Macro packages come in two varieties:@: ``major'' or ``full-service''
+ones that manage page layout, and ``minor'' or ``auxiliary'' ones that
+do not, instead fulfilling narrow, specific tasks.  Find a list in the
+@cite{groff_tmac@r{(5)}} man page.  Type @samp{man groff_tmac} at the
+command line to view it.
+
+We survey several capabilities of full-service macro package below.
+Each package employs its own macros to exercise them.  For details,
+consult its man page or, for @file{ms}, see @ref{ms}.
+
+@menu
+* Paragraphs::
+* Sections and Chapters::
+* Headers and Footers::
+* Page Layout Adjustment::
+* Displays and Keeps::
+* Footnotes and Endnotes::
+* Table of Contents::
+* Indexing::
+* Document Formats::
+* Columnation::
+* Font and Size Changes::
+* Predefined Text::
+* Preprocessor Support::
+* Configuration and Customization::
+@end menu
+
+@c ---------------------------------------------------------------------
+
+@node Paragraphs, Sections and Chapters, Common Features, Common Features
+@subsection Paragraphs
+@cindex paragraphs
+
+Paragraphs can be separated and indented in various ways.  Some start
+with a blank line and have a first-line indentation, like most of the
+ones in this manual.  Block paragraphs omit the indentation.
+
+@Example
+  @result{} Some  men  look  at constitutions with sanctimonious
+  @result{} reverence,  and  deem  them  like  the  ark  of  the
+  @result{} covenant, too sacred to be touched.
+@endExample
+
+@cindex tags, paragraph
+@cindex tagged paragraphs
+@cindex lists
+@noindent
+We also frequently encounter @slanted{tagged} paragraphs, which begin
+with a tag or label at the left margin and indent the remaining text.
+
+@Example
+  @result{} one  This  is the first paragraph.  Notice how the
+  @result{}      first line of the resulting  paragraph  lines
+  @result{}      up with the other lines in the paragraph.
+@endExample
+
+@noindent
+If the tag is too wide for the indentation, the line is broken.
+
+@Example
+  @result{} longlabel
+  @result{}      The  label does not align with the subsequent
+  @result{}      lines, but they align with each other.
+@endExample
+
+@noindent
+A variation of the tagged paragraph is the itemized or enumerated
+paragraph, which might use punctuation or a digit for a tag,
+respectively.  These are frequently used to construct lists.
+
+@Example
+  @result{} o    This  list  item  starts with a bullet.  When
+  @result{}      producing output for a device using the ASCII
+  @result{}      character set, an 'o' is formatted instead.
+@endExample
+
+@noindent
+Often, use of the same macro without a tag continues such a discussion.
+
+@Example
+  @result{} -xyz  This option is recognized but ignored.
+  @result{}
+  @result{}       It had a security hole that we don't discuss.
+@endExample
+
+@c ---------------------------------------------------------------------
+
+@node Sections and Chapters, Headers and Footers, Paragraphs, Common Features
+@subsection Sections and Chapters
+
+The simplest kind of section heading is unnumbered, set in a bold or
+italic style, and occupies a line by itself.  Others possess
+automatically numbered multi-level headings and/or different typeface
+styles or sizes at different levels.  More sophisticated macro packages
+supply macros for designating chapters and appendices.
+
+@c ---------------------------------------------------------------------
+
+@node Headers and Footers, Page Layout Adjustment, Sections and Chapters, Common Features
+@subsection Headers and Footers
+
+@slanted{Headers} and @slanted{footers} occupy the top and bottom of
+each page, respectively, and contain data like the page number and the
+article or chapter title.  Their appearance is not affected by the
+running text.  Some packages allow for different titles on even- and
+odd-numbered pages (for printed, bound material).
+
+Headers and footers are together called @slanted{titles}, and comprise
+three parts:@: left-aligned, centered, and right-aligned.  A @samp{%}
+character appearing anywhere in a title is automatically replaced by the
+page number.  @xref{Page Layout}.
+
+@c ---------------------------------------------------------------------
+
+@node Page Layout Adjustment, Displays and Keeps, Headers and Footers, Common Features
+@subsection Page Layout
+
+Most macro packages let the user specify the size of the page margins.
+The top and bottom margins are typically handled differently than the
+left and right margins; the latter two are derived from the
+@slanted{page offset}, @slanted{indentation}, and @slanted{line length}.
+@xref{Line Layout}.  Commonly, packages support registers to tune these
+values.
+
+@c ---------------------------------------------------------------------
+
+@node Displays and Keeps, Footnotes and Endnotes, Page Layout Adjustment, Common Features
+@subsection Displays and Keeps
+@cindex displays
+
+@slanted{Displays} are sections of text set off from the surrounding
+material (typically paragraphs), often differing in indentation, and/or
+spacing.  Tables, block quotations, and figures are displayed.
+Equations and code examples, when not much shorter than an output line,
+often are.  Lists may or may not be.  Packages for setting man pages
+support example displays but not keeps.
+@c XXX: man, mdoc keep support planned
+
+@cindex keeps (introduction)
+A @slanted{keep} is a group of output lines, often a display, that is
+formatted on a single page if possible; it causes a page break to happen
+early so as to not interrupt the kept material.
+
+@cindex keep, floating
+@cindex floating keep
+@slanted{Floating keeps} can move, or ``float'', relative to the text
+around them in the input.  They are useful for displays that are
+captioned and referred to by name, as with ``See figure@tie{}3''.
+Depending on the package, a floating keep appears at the bottom of the
+current page if it fits, and at the top of the next otherwise.
+Alternatively, floating keeps might be deferred to the end of a section.
+Using a floating keep can avoid the large vertical spaces that may
+precede a tall keep of the ordinary sort when it won't fit on the page.
+
+@c ---------------------------------------------------------------------
+
+@node Footnotes and Endnotes, Table of Contents, Displays and Keeps, Common Features
+@subsection Footnotes and Endnotes
+@cindex footnotes
+@cindex endnotes
+
+@slanted{Footnotes} and @slanted{endnotes} are forms of delayed
+formatting.  They are recorded at their points of relevance in
+the input, but not formatted there.  Instead, a @slanted{mark} cues the
+reader to check the ``foot'', or bottom, of the current page, or in the
+case of endnotes, an annotation list later in the document.  Macro
+packages that support these features also supply a means of
+automatically numbering either type of annotation.
+
+@c ---------------------------------------------------------------------
+
+@node Table of Contents, Indexing, Footnotes and Endnotes, Common Features
+@subsection Table of Contents
+@cindex table of contents
+@cindex contents, table of
+
+A package may handle a @slanted{table of contents} by directing section
+heading macros to save section heading text and the page number where it
+occurs for use in a later @slanted{entry} for a table of contents.  It
+writes the collected entries at the end of the document, once all are
+known, upon request.  A row of dots (a @slanted{leader}) bridges the
+text on the left with its location on the right.  Other collections
+might work in this manner, providing lists of figures or tables.
+
+A table of contents is often found at the end of a GNU @code{troff}
+document because the formatter processes the document in a single pass.
+The @command{gropdf} output driver supports a PDF feature that relocates
+pages at the time the document is rendered; see the @cite{gropdf@r{(1)}}
+man page.  Type @samp{man gropdf} at the command line to view it.
+
+@c ---------------------------------------------------------------------
+
+@node Indexing, Document Formats, Table of Contents, Common Features
+@subsection Indexing
+@cindex index, in macro package
+
+@pindex makeindex
+An index is similar to a table of contents, in that entry labels and
+locations must be collected, but poses a greater challenge because it
+needs to be sorted before it is output.  Here, processing the document
+in multiple passes is inescapable, and tools like the @code{makeindex}
+program are necessary.
+
+@c ---------------------------------------------------------------------
+
+@node Document Formats, Columnation, Indexing, Common Features
+@subsection Document Formats
+@cindex document formats
+
+Some macro packages supply stock configurations of certain documents,
+like business letters and memoranda.  These often also have provision
+for a @slanted{cover sheet}, which may be rigid in its format.  With
+these features, it is even more important to use the package's macros in
+preference to the formatter requests presented earlier, where possible.
+
+@c ---------------------------------------------------------------------
+
+@node Columnation, Font and Size Changes, Document Formats, Common Features
+@subsection Columnation
+
+Macro packages apart from @file{man} and @file{mdoc} for man page
+formatting offer a facility for setting multiple columns on the page.
+
+@c ---------------------------------------------------------------------
+
+@node Font and Size Changes, Predefined Text, Columnation, Common Features
+@subsection Font and Size Changes
+
+The formatter's requests and escape sequences for setting the typeface
+and size are not always intuitive, so all macro packages provide macros
+to make these operations simpler.  They also make it more convenient to
+change typefaces in the middle of a word and can handle italic
+corrections automatically.  @xref{Italic Corrections}.
+
+@c ---------------------------------------------------------------------
+
+@node Predefined Text, Preprocessor Support, Font and Size Changes, Common Features
+@subsection Predefined Text
+
+Most macro packages supply predefined strings to set prepared text like
+the date, or to perform operations like super- and subscripting.
+
+@c ---------------------------------------------------------------------
+
+@node Preprocessor Support, Configuration and Customization, Predefined Text, Common Features
+@subsection Preprocessor Support
+
+All macro packages provide support for various preprocessors and may
+extend their functionality by defining macros to set their contents in
+displays.  Examples include @code{TS} and @code{TE} for @command{gtbl},
+@code{EQ} and @code{EN} for @command{geqn}, and @code{PS} and @code{PE}
+for @command{gpic}.
+
+@c ---------------------------------------------------------------------
+
+@node Configuration and Customization,  , Preprocessor Support, Common Features
+@subsection Configuration and Customization
+
+Packages provide means of customizing many of the details of how the
+package behaves.  These range from setting the default type size to
+changing the appearance of section headers.
+
+@codequotebacktick off
+@codequoteundirected off
+
+
+
+@c =====================================================================
+@c =====================================================================
+
+@node Major Macro Packages, GNU troff Reference, Tutorial for Macro Users, Top
+@chapter Macro Packages
+@cindex major macro package
+@cindex package, macro, major
+@cindex macro package, major
+
+This chapter surveys the ``major'' macro packages that come with
+@code{groff}.  One, @file{ms}, is presented in detail.
+
+@cindex full-service macro package
+@cindex package, macro, full-service
+@cindex macro package, full-service
+Major macro packages are also sometimes described as @dfn{full-service}
+due to the breadth of features they provide and because more than one
+cannot be used by the same document; for example
+
+@Example
+groff -m man foo.man -m ms bar.doc
+@endExample
+
+@noindent
+doesn't work.  Option arguments are processed before non-option
+arguments; the above (failing) sample is thus reordered to
+
+@Example
+groff -m man -m ms foo.man bar.doc
+@endExample
+
+@cindex minor macro package
+@cindex package, macro, minor
+@cindex macro package, minor
+@cindex auxiliary macro package
+@cindex package, macro, auxiliary
+@cindex macro package, auxiliary
+Many auxiliary, or ``minor'', macro packages are also available.  They
+may in general be used with any full-service macro package and handle a
+variety of tasks from character encoding selection, to language
+localization, to inlining of raster images.  See the
+@cite{groff_tmac@r{(5)}} man page for a list.  Type @samp{man
+groff_tmac} at the command line to view it.
+
+@menu
+* man::
+* mdoc::
+* me::
+* mm::
+* mom::
+* ms::
+@end menu
+
+
+@c =====================================================================
+
+@node man, mdoc, Major Macro Packages, Major Macro Packages
+@section @file{man}
+@cindex manual pages
+@cindex man pages
+@pindex an.tmac
+@pindex man.tmac
+
+The @code{man} macro package is the most widely used and probably the
+most important ever developed for @code{troff}.  It is easy to use, and
+a vast majority of manual pages (``man pages'') are written in it.
+
+@code{groff}'s implementation is documented in the
+@cite{groff_man@r{(7)}} man page.  Type @samp{man groff_man} at the
+command line to view it.
+
+@menu
+* Optional man extensions::
+@end menu
+
+@c ---------------------------------------------------------------------
+
+@node Optional man extensions,  ,  , man
+@subsection Optional @file{man} extensions
+
+@pindex man.local
+Use the file @file{man.local} for local extensions to the @code{man}
+macros or for style changes.
+
+@unnumberedsubsubsec Custom headers and footers
+@cindex @code{man} macros, custom headers and footers
+
+In @code{groff} versions 1.18.2 and later, you can specify custom
+headers and footers by redefining the following macros in
+@file{man.local}.
+
+@Defmac {PT, , man}
+Control the content of the headers.  Normally, the header prints the
+command name and section number on either side, and the optional fifth
+argument to @code{TH} in the center.
+@endDefmac
+
+@Defmac {BT, , man}
+Control the content of the footers.  Normally, the footer prints the
+page number and the third and fourth arguments to @code{TH}.
+
+Use the @code{FT} register to specify the footer position.  The default
+is @minus{}0.5@dmn{i}.
+@endDefmac
+
+@unnumberedsubsubsec Ultrix-specific man macros
+@cindex Ultrix-specific @code{man} macros
+@cindex @code{man} macros, Ultrix-specific
+
+@pindex man.ultrix
+The @code{groff} source distribution includes a file named
+@file{man.ultrix}, containing macros compatible with the Ultrix variant
+of @code{man}.  Copy this file into @file{man.local} (or use the
+@code{mso} request to load it) to enable the following macros.
+
+@Defmac {CT, @Var{key}, man}
+Print @samp{<CTRL/@var{key}>}.
+@endDefmac
+
+@Defmac {CW, , man}
+Print subsequent text using a ``constant-width'' (monospaced) typeface
+(Courier roman).
+@endDefmac
+
+@Defmac {Ds, , man}
+Begin a non-filled display.
+@endDefmac
+
+@Defmac {De, , man}
+End a non-filled display started with @code{Ds}.
+@endDefmac
+
+@Defmac {EX, [@Var{indent}], man}
+Begin a non-filled display using a monospaced typeface (Courier roman).
+Use the optional @var{indent} argument to indent the display.
+@endDefmac
+
+@Defmac {EE, , man}
+End a non-filled display started with @code{EX}.
+@endDefmac
+
+@Defmac {G, [@Var{text}], man}
+Set @var{text} in Helvetica.  If no text is present on the line where
+the macro is called, then the text of the next line appears in
+Helvetica.
+@endDefmac
+
+@Defmac {GL, [@Var{text}], man}
+Set @var{text} in Helvetica oblique.  If no text is present on the line
+where the macro is called, then the text of the next line appears in
+Helvetica Oblique.
+@endDefmac
+
+@Defmac {HB, [@Var{text}], man}
+Set @var{text} in Helvetica bold.  If no text is present on the line
+where the macro is called, then all text up to the next @code{HB}
+appears in Helvetica bold.
+@endDefmac
+
+@Defmac {TB, [@Var{text}], man}
+Identical to @code{HB}.
+@endDefmac
+
+@Defmac {MS, @Var{title} @Var{sect} [@Var{punct}], man}
+Set a man page reference in Ultrix format.  The @var{title} is in
+Courier instead of italic.  Optional punctuation follows the section
+number without an intervening space.
+@endDefmac
+
+@Defmac {NT, [@code{C}] [@Var{title}], man}
+Begin a note.  Print the optional @Var{title}, or the word ``Note'',
+centered on the page.  Text following the macro makes up the body of the
+note, and is indented on both sides.  If the first argument is @code{C},
+the body of the note is printed centered (the second argument replaces
+the word ``Note'' if specified).
+@endDefmac
+
+@Defmac {NE, , man}
+End a note begun with @code{NT}.
+@endDefmac
+
+@Defmac {PN, @Var{path} [@Var{punct}], man}
+Set the path name in a monospaced typeface (Courier roman), followed by
+optional punctuation.
+@endDefmac
+
+@Defmac {Pn, [@Var{punct}] @Var{path} [@Var{punct}], man}
+If called with two arguments, identical to @code{PN}.  If called with
+three arguments, set the second argument in a monospaced typeface
+(Courier roman), bracketed by the first and third arguments in the
+current font.
+@endDefmac
+
+@Defmac {R, , man}
+Switch to roman font and turn off any underlining in effect.
+@endDefmac
+
+@Defmac {RN, , man}
+Print the string @samp{<RETURN>}.
+@endDefmac
+
+@Defmac {VS, [@code{4}], man}
+Start printing a change bar in the margin if the number@tie{}@code{4} is
+specified.  Otherwise, this macro does nothing.
+@endDefmac
+
+@Defmac {VE, , man}
+End printing the change bar begun by @code{VS}.
+@endDefmac
+
+@unnumberedsubsubsec Simple example
+
+The following example @file{man.local} file alters the @code{SH} macro
+to add some extra vertical space before printing the heading.  Headings
+are printed in Helvetica bold.
+
+@Example
+.\" Make the heading fonts Helvetica
+.ds HF HB
+.
+.\" Put more space in front of headings.
+.rn SH SH-orig
+.de SH
+.  if t .sp (u;\\n[PD]*2)
+.  SH-orig \\$*
+..
+@endExample
+
+
+@c =====================================================================
+
+@node mdoc, me, man, Major Macro Packages
+@section @file{mdoc}
+@cindex @code{mdoc} macros
+
+@code{groff}'s implementation of the BSD @file{doc} package for man
+pages is documented in the @cite{groff_mdoc@r{(7)}} man page.  Type
+@samp{man groff_mdoc} at the command line to view it.
+
+
+@c =====================================================================
+
+@node me, mm, mdoc, Major Macro Packages
+@section @file{me}
+@cindex @code{me} macro package
+
+@code{groff}'s implementation of the BSD @file{me} macro package is
+documented using itself.  A tutorial, @file{meintro.me}, and reference,
+@file{meref.me}, are available in @code{groff}'s documentation
+directory.  A @cite{groff_me@r{(7)}} man page is also available and
+identifies the installation path for these documents.  Type @samp{man
+groff_me} at the command line to view it.
+
+A French translation of the tutorial is available as
+@file{meintro_fr.me} and installed parallel to the English version.
+
+
+@c =====================================================================
+
+@node mm, mom, me, Major Macro Packages
+@section @file{mm}
+@cindex @code{mm} macro package
+
+@code{groff}'s implementation of the @acronym{AT&T} memorandum macro
+package is documented in the @cite{groff_mm@r{(7)}} man page.  Type
+@samp{man groff_mm} at the command line) to view it.
+
+A Swedish localization of @file{mm} is also available; see
+@cite{groff_mmse@r{(7)}}.
+
+
+@c =====================================================================
+
+@node mom, ms, mm, Major Macro Packages
+@section @file{mom}
+@cindex @code{mom} macro package
+
+The main documentation files for the @file{mom} macros are in
+@acronym{HTML} format.  Additional, useful documentation is in
+@acronym{PDF} format.  See the @cite{groff@r{(1)}} man page, section
+``Installation Directories'', for their location.
+
+@itemize @bullet
+@item
+@file{toc.html}
+@noindent
+Entry point to the full mom manual.
+
+@item
+@file{macrolist.html}
+@noindent
+Hyperlinked index of macros with brief descriptions, arranged by
+category.
+
+@item
+@file{mom-pdf.pdf}
+@noindent
+@acronym{PDF} features and usage.
+@end itemize
+
+The mom macros are in active development between @code{groff} releases.
+The most recent version, along with up-to-date documentation, is
+available at @uref{http://www.schaffter.ca/mom/mom-05.html}.
+
+The @cite{groff_mom@r{(7)}} man page (type @samp{man groff_mom} at
+the command line) contains a partial list of available macros, however
+their usage is best understood by consulting the @acronym{HTML}
+documentation.
+
+
+@c =====================================================================
+
+@codequotebacktick on
+@codequoteundirected on
+
+@node ms,  , mom, Major Macro Packages
+@section @file{ms}
+@cindex @file{ms} macros
+
+The @file{ms} (``manuscript'') package is suitable for the preparation
+of letters, memoranda, reports, and books.  These @code{groff}
+macros feature cover page and table of contents generation,
+automatically numbered headings, several paragraph styles, a variety of
+text styling options, footnotes, and multi-column page layouts.
+@file{ms} supports the @command{tbl}, @command{eqn}, @command{pic}, and
+@command{refer} preprocessors for inclusion of tables, mathematical
+equations, diagrams, and standardized bibliographic citations.  This
+implementation is mostly compatible with the documented interface and
+behavior of AT&T Unix Version@tie{}7 @file{ms}.  Many extensions from
+4.2BSD (Berkeley)
+@c Few changes were made in 4.3, Tahoe, Reno, or 4.4.
+and Tenth Edition Research Unix have been recreated.
+
+@menu
+* ms Introduction::
+* ms Document Structure::
+* ms Document Control Settings::
+* ms Document Description Macros::
+* ms Body Text::
+* ms Page Layout::
+* Differences from AT&T ms::
+* ms Legacy Features::
+* ms Naming Conventions::
+@end menu
+
+@c ---------------------------------------------------------------------
+
+@node ms Introduction, ms Document Structure, ms, ms
+@subsection Introduction
+
+The @file{ms} macros are the oldest surviving package for @code{roff}
+systems.@footnote{While manual @emph{pages} are older, early ones used
+macros supplanted by the @file{man} package of Seventh Edition Unix
+(1979).  @file{ms} shipped with Sixth Edition (1975) and was documented
+by Mike Lesk in a Bell Labs internal memorandum.}  While the @file{man}
+package was designed for brief reference documents, the @file{ms} macros
+are also suitable for longer works intended for printing and possible
+publication.
+
+@menu
+* ms basic information::
+@end menu
+
+@c ---------------------------------------------------------------------
+
+@node ms basic information, ms Document Structure, ms Introduction, ms Introduction
+@subsubsection Basic information
+
+@file{ms} documents are plain text files; prepare them with your
+preferred text editor.  If you're in a hurry to start, know that
+@file{ms} needs one of its macros called at the beginning of a document
+so that it can initialize.  A @dfn{macro} is a formatting instruction to
+@file{ms}.  Put a macro call on a line by itself.  Use @samp{.PP} if you
+want your paragraph's first line to be indented, or @samp{.LP} if you
+don't.
+
+After that, start typing normally.  It is a good practice to start each
+sentence on a new line, or to put two spaces after sentence-ending
+punctuation, so that the formatter knows where the sentence boundaries
+are.  You can separate paragraphs with further paragraphing macros, or
+with blank lines, and you can indent with tabs.  When you need one of
+the features mentioned earlier (@pxref{ms}), return to this part of the
+manual.
+
+Format the document with the @command{groff} command.  @command{nroff}
+can be useful for previewing.
+
+@CartoucheExample
+$ editor radical.ms
+$ nroff -ww -z -ms radical.ms # check for errors
+$ nroff -ms radical.ms | less -R
+$ groff -T ps -ms radical.ms > radical.ps
+$ see radical.ps
+@endCartoucheExample
+
+Our @file{radical.ms} document might look like this.
+
+@CartoucheExample
+.LP
+Radical novelties are so disturbing that they tend to be
+suppressed or ignored, to the extent that even the
+possibility of their existence in general is more often
+denied than admitted.
+
+@arrow{}That's what Dijkstra said, anyway.
+@endCartoucheExample
+
+@file{ms} exposes many aspects of document layout to user control via
+@code{groff}'s @dfn{registers} and @dfn{strings}, which store numbers
+and text, respectively.  Measurements in @code{groff} are expressed with
+a suffix called a @dfn{scaling unit}.
+
+@table @code
+@item i
+inches
+
+@item c
+centimeters
+
+@item p
+points (1/72 inch)
+
+@item P
+picas (1/6 inch)
+
+@item v
+vees; current vertical spacing
+
+@item m
+ems; width of an ``M'' in the current font
+
+@item n
+ens; one-half em
+@end table
+
+Set registers with the @code{nr} request and strings with the @code{ds}
+request.  @dfn{Requests} are like macro calls; they go on lines by
+themselves and start with the @dfn{control character}, a dot (@code{.}).
+The difference is that they directly instruct the formatter program,
+rather than the macro package.  We'll discuss a few as applicable.  It
+is wise to specify a scaling unit when setting any register that
+represents a length, size, or distance.
+
+@CartoucheExample
+.nr PS 10.5p \" Use 10.5-point type.
+.ds FAM P    \" Use Palatino font family.
+@endCartoucheExample
+
+@noindent
+In the foregoing, we see that @code{\"} begins a comment.  This is an
+example of an @dfn{escape sequence}, the other kind of formatting
+instruction.  Escape sequences can appear anywhere.  They begin with the
+escape character (@code{\}) and are followed by at least one more
+character.  @file{ms} documents
+@c like this one
+tend to use only a few of @code{groff}'s many requests and escape
+sequences; see @ref{Request Index} and @ref{Escape Sequence Index} or
+the @cite{groff@r{(7)}} man page for complete lists.
+
+@table @code
+@item \"
+Begin comment; ignore remainder of line.
+
+@item \n[@var{reg}]
+Interpolate value of register @var{reg}.
+
+@item \*[@var{str}]
+Interpolate contents of string @var{str}.
+
+@item \*@var{s}
+abbreviation of @code{\*[@var{s}]}; the name @var{s} must be only one
+character
+
+@item \[@var{char}]
+Interpolate glyph of special character named @var{char}.
+
+@item \&
+dummy character
+
+@item \~
+Insert an unbreakable space that is adjustable like a normal space.
+
+@item \|
+Move horizontally by one-sixth em (``thin space'').
+@end table
+
+Prefix any words that start with a dot @samp{.} or neutral apostrophe
+@samp{'} with @code{\&} if they are at the beginning of an input line
+(or might become that way in editing) to prevent them from being
+interpreted as macro calls or requests.  Suffix @samp{.}, @samp{?}, and
+@samp{!} with @code{\&} when needed to cancel end-of-sentence detection.
+
+@CartoucheExample
+My exposure was \&.5 to \&.6 Sv of neutrons, said Dr.\&
+Wallace after the criticality incident.
+@endCartoucheExample
+
+@c ---------------------------------------------------------------------
+
+@node ms Document Structure, ms Document Control Settings, ms Introduction, ms
+@subsection Document Structure
+@cindex @file{ms} macros, general structure
+
+The @file{ms} macro package expects a certain amount of structure:
+a well-formed document contains at least one paragraphing or heading
+macro call.  Longer documents have a structure as follows.
+
+@table @strong
+@item Document type
+Calling the @code{RP} macro at the beginning of your document puts the
+document description (see below) on a cover page.  Otherwise, @file{ms}
+places the information (if any) on the first page, followed immediately
+by the body text.  Some document types found in other @file{ms}
+implementations are specific to @acronym{AT&T} or Berkeley, and are not
+supported by @code{groff} @file{ms}.
+
+@item Format and layout
+By setting registers and strings, you can configure your document's
+typeface, margins, spacing, headers and footers, and footnote
+arrangement.  @xref{ms Document Control Settings}.
+
+@item Document description
+A document description consists of any of: a title, one or more authors'
+names and affiliated institutions, an abstract, and a date or other
+identifier.  @xref{ms Document Description Macros}.
+
+@item Body text
+The main matter of your document follows its description (if any).
+@file{ms} supports highly structured text consisting of paragraphs
+interspersed with multi-level headings (chapters, sections, subsections,
+and so forth) and augmented by lists, footnotes, tables, diagrams, and
+similar material.  @xref{ms Body Text}.
+
+@item Tables of contents
+Macros enable the collection of entries for a table of contents (or
+index) as the material they discuss appears in the document.  You then
+call a macro to emit the table of contents at the end of your document.
+The table of contents must necessarily follow the rest of the text since
+GNU @code{troff} is a single-pass formatter; it thus cannot determine
+the page number of a division of the text until it has been set and
+output.  Since @file{ms} was designed for the production of hard copy,
+the traditional procedure was to manually relocate the pages containing
+the table of contents between the cover page and the body text.  Today,
+page resequencing is more often done in the digital domain.  An index
+works similarly, but because it typically needs to be sorted after
+collection, its preparation requires separate processing.
+@end table
+
+@c ---------------------------------------------------------------------
+
+@node ms Document Control Settings, ms Document Description Macros, ms Document Structure, ms
+@subsection Document Control Settings
+@cindex @file{ms} macros, document control settings
+
+@file{ms} exposes many aspects of document layout to user control via
+@code{groff} requests.  To use them, you must understand how to define
+registers and strings.
+
+@Defreq {nr, reg value}
+Set register @var{reg} to @var{value}.  If @var{reg} doesn't exist, GNU
+@code{troff} creates it.
+@endDefreq
+
+@Defreq {ds, name contents}
+Set string @var{name} to @var{contents}.
+@endDefreq
+
+A list of document control registers and strings follows.  For any
+parameter whose default is unsatisfactory, define its register or string
+before calling any @file{ms} macro other than @code{RP}.
+
+@unnumberedsubsubsec Margin settings
+
+@Defmpreg {PO, ms}
+Defines the page offset (i.e., the left margin).
+@c not in V6
+
+Effective: next page.
+
+Default: Varies by output device and paper format; 1@dmn{i} is used for
+typesetters using U.S.@: letter paper, and zero for terminals.
+@xref{Paper Format}.
+@endDefmpreg
+
+@Defmpreg {LL, ms}
+Defines the line length (i.e., the width of the body text).
+
+Effective: next paragraph.
+
+Default: Varies by output device and paper format; 6.5@dmn{i} is used
+for typesetters using U.S.@: letter paper (@pxref{Paper Format}) and
+65@dmn{n} on terminals.
+@endDefmpreg
+
+@Defmpreg {LT, ms}
+Defines the title line length (i.e., the header and footer width).  This
+is usually the same as @code{LL}, but need not be.
+
+Effective: next paragraph.
+
+Default: Varies by output device and paper format; 6.5@dmn{i} is used
+for typesetters using U.S.@: letter paper (@pxref{Paper Format}) and
+65@dmn{n} on terminals.
+@endDefmpreg
+
+@Defmpreg {HM, ms}
+Defines the header margin height at the top of the page.
+@c not in V6
+
+Effective: next page.
+
+Default: 1@dmn{i}.
+@endDefmpreg
+
+@Defmpreg {FM, ms}
+Defines the footer margin height at the bottom of the page.
+@c not in V6
+
+Effective: next page.
+
+Default: 1@dmn{i}.
+@endDefmpreg
+
+@unnumberedsubsubsec Titles (headers, footers)
+
+@Defmpstr {LH, ms}
+Defines the text displayed in the left header position.
+
+Effective: next header.
+
+Default: empty.
+@endDefmpstr
+
+@Defmpstr {CH, ms}
+Defines the text displayed in the center header position.
+
+Effective: next header.
+
+Default: @samp{-\n[%]-}.
+@endDefmpstr
+
+@Defmpstr {RH, ms}
+Defines the text displayed in the right header position.
+
+Effective: next header.
+
+Default: empty.
+@endDefmpstr
+
+@Defmpstr {LF, ms}
+Defines the text displayed in the left footer position.
+
+Effective: next footer.
+
+Default: empty.
+@endDefmpstr
+
+@Defmpstr {CF, ms}
+Defines the text displayed in the center footer position.
+
+Effective: next footer.
+
+Default: empty.
+@endDefmpstr
+
+@Defmpstr {RF, ms}
+Defines the text displayed in the right footer position.
+
+Effective: next footer.
+
+Default: empty.
+@endDefmpstr
+
+@unnumberedsubsubsec Text settings
+
+@Defmpreg {PS, ms}
+Defines the type size of the body text.
+
+Effective: next paragraph.
+
+Default: 10@dmn{p}.
+@endDefmpreg
+
+@Defmpreg {VS, ms}
+Defines the vertical spacing (type size plus leading).
+
+Effective: next paragraph.
+
+Default: 12@dmn{p}.
+@endDefmpreg
+
+@Defmpreg {HY, ms}
+Defines the automatic hyphenation mode used with the @code{hy} request.
+Setting @code{HY} to@tie{}0 is equivalent to using the @code{nh}
+request.  This is a Tenth Edition Research Unix extension.
+@c possibly 9th, but definitely not Berkeley
+
+Effective: next paragraph.
+
+Default: 6.
+@endDefmpreg
+
+@Defmpstr {FAM, ms}
+Defines the font family used to typeset the document.  This is a GNU
+extension.
+
+Effective: next paragraph.
+
+Default: defined by the output device; often @samp{T} (@pxref{ms Body
+Text})
+@endDefmpstr
+
+@unnumberedsubsubsec Paragraph settings
+
+@Defmpreg {PI, ms}
+Defines the indentation amount used by the @code{PP}, @code{IP} (unless
+overridden by an optional argument), @code{XP}, and @code{RS} macros.
+@c not in V6
+
+Effective: next paragraph.
+
+Default: 5@dmn{n}.
+@endDefmpreg
+
+@Defmpreg {PD, ms}
+Defines the space between paragraphs.
+@c not in V6
+
+Effective: next paragraph.
+
+Default: 0.3@dmn{v} (1@dmn{v} on low-resolution devices).
+@endDefmpreg
+
+@Defmpreg {QI, ms}
+Defines the indentation amount used on both sides of a paragraph set
+with the @code{QP} or between the @code{QS} and @code{QE} macros.
+
+Effective: next paragraph.
+
+Default: 5@dmn{n}.
+@endDefmpreg
+
+@Defmpreg {PORPHANS, ms}
+Defines the minimum number of initial lines of any paragraph that must
+be kept together to avoid isolated lines at the bottom of a page.  If a
+new paragraph is started close to the bottom of a page, and there is
+insufficient space to accommodate @code{PORPHANS} lines before an
+automatic page break, then a page break is forced before the start of
+the paragraph.  This is a GNU extension.
+
+Effective: next paragraph.
+
+Default: 1.
+@endDefmpreg
+
+@unnumberedsubsubsec Heading settings
+
+@Defmpreg {PSINCR, ms}
+Defines an increment in type size to be applied to a heading at a
+lesser depth than that specified in @code{GROWPS}.  The value of
+@code{PSINCR} should be specified in points with the @dmn{p} scaling
+unit and may include a fractional component; for example, @w{@samp{.nr
+PSINCR 1.5p}} sets a type size increment of 1.5@dmn{p}.  This is a GNU
+extension.
+
+Effective: next heading.
+
+Default: 1@dmn{p}.
+@endDefmpreg
+
+@Defmpreg {GROWPS, ms}
+Defines the heading depth above which the type size increment set by
+@code{PSINCR} becomes effective.  For each heading depth less than the
+value of @code{GROWPS}, the type size is increased by @code{PSINCR}.
+Setting @code{GROWPS} to any value less than@tie{}2 disables the
+incremental heading size feature.  This is a GNU extension.
+
+Effective: next heading.
+
+Default: 0.
+@endDefmpreg
+
+@Defmpreg {HORPHANS, ms}
+Defines the minimum number of lines of an immediately succeeding
+paragraph that should be kept together with any heading introduced by
+the @code{NH} or @code{SH} macros.  If a heading is placed close to the
+bottom of a page, and there is insufficient space to accommodate both
+the heading and at least @code{HORPHANS} lines of the following
+paragraph, before an automatic page break, then the page break is forced
+before the heading.  This is a GNU extension.
+
+Effective: next paragraph.
+
+Default: 1.
+@endDefmpreg
+
+@Defmpstr {SN-STYLE, ms}
+Defines the style used to print numbered headings.  @xref{Headings in
+ms}.  This is a GNU extension.
+
+Effective: next heading.
+
+Default: alias of @code{SN-DOT}
+@endDefmpstr
+
+@unnumberedsubsubsec Footnote settings
+
+@Defmpreg {FI, ms}
+Defines the footnote indentation.  This is a Berkeley extension.
+
+Effective: next footnote.
+
+Default: 2@dmn{n}.
+@endDefmpreg
+
+@Defmpreg {FF, ms}
+Defines the format of automatically numbered footnotes,
+and those for which the @code{FS} request is given a marker argument, at
+the bottom of a column or page.  This is a Berkeley extension.
+@table @code
+@item 0
+Set an automatic number@footnote{defined in @ref{ms Footnotes}} as a
+superscript (on typesetter devices) or surrounded by square brackets (on
+terminals).  The footnote paragraph is indented as with @code{PP} if
+there is an @code{FS} argument or an automatic number, and as with
+@code{LP} otherwise.  This is the default.
+
+@item 1
+As @code{0}, but set the marker as regular text and follow an
+automatic number with a period.
+
+@item 2
+As @code{1}, but without indentation (like @code{LP}).
+
+@item 3
+As @code{1}, but set the footnote paragraph with the marker hanging
+(like @code{IP}).
+@end table
+
+Effective: next footnote.
+
+Default: 0.
+@endDefmpreg
+
+@Defmpreg {FPS, ms}
+Defines the footnote type size.
+
+Effective: next footnote.
+
+Default: @code{\n[PS] - 2p}.
+@endDefmpreg
+
+@Defmpreg {FVS, ms}
+Defines the footnote vertical spacing.
+
+Effective: next footnote.
+
+Default: @code{\n[FPS] + 2p}.
+@endDefmpreg
+
+@Defmpreg {FPD, ms}
+Defines the footnote paragraph spacing.  This is a GNU extension.
+
+Effective: next footnote.
+
+Default: @code{\n[PD] / 2}.
+@endDefmpreg
+
+@Defmpstr {FR, ms}
+Defines the ratio of the footnote line length to the current line
+length.  This is a GNU extension.
+
+Effective: next footnote in single-column arrangements, next page
+otherwise.
+
+Default: @code{11/12}.
+@endDefmpstr
+
+@unnumberedsubsubsec Display settings
+
+@Defmpreg {DD, ms}
+Sets the display distance---the vertical spacing before and after a
+display, a @code{tbl} table, an @code{eqn} equation, or a @code{pic}
+image.  This is a Berkeley extension.
+
+Effective: next display boundary.
+
+Default: 0.5@dmn{v} (1@dmn{v} on low-resolution devices).
+@endDefmpreg
+
+@Defmpreg {DI, ms}
+Sets the default amount by which to indent a display started with
+@code{DS} and @code{ID} without arguments, to @samp{.DS@tie{}I} without
+an indentation argument, and to equations set with @samp{.EQ@tie{}I}.
+This is a GNU extension.
+
+Effective: next indented display.
+
+Default: 0.5@dmn{i}.
+@endDefmpreg
+
+@unnumberedsubsubsec Other settings
+
+@Defmpreg {MINGW, ms}
+Defines the default minimum width between columns in a multi-column
+document.  This is a GNU extension.
+
+Effective: next page.
+
+Default: 2@dmn{n}.
+@endDefmpreg
+
+@Defmpreg {TC-MARGIN, ms}
+Defines the width of the field in which page numbers are set in a table
+of contents entry; the right margin thus moves inboard by this amount.
+This is a GNU extension.
+
+Effective: next @code{PX} call.
+
+Default: @code{\w'000'}
+@endDefmpreg
+
+@c XXX: Normally we'd have an entry for TC-LEADER here, but it's a
+@c special character and we have no custom Texinfo macros for defining
+@c (and indexing) these.  There would be little point in an index for
+@c one item, and the plan is to drop this entire @section from this
+@c manual once doc/ms.ms is ready.  See Savannah #60061.
+
+@c ---------------------------------------------------------------------
+
+@node ms Document Description Macros, ms Body Text, ms Document Control Settings, ms
+@subsection Document Description Macros
+@cindex @file{ms} macros, document description
+@cindex document description macros, [@file{ms}]
+
+Only the simplest document lacks a title.@footnote{Distinguish a
+document title from ``titles'', which are what @code{roff} systems call
+headers and footers collectively.}  As its level of sophistication (or
+complexity) increases, it tends to acquire a date of revision,
+explicitly identified authors, sponsoring institutions for authors, and,
+at the rarefied heights, an abstract of its content.  Define these
+data by calling the macros below in the order shown; @code{DA} or
+@code{ND} can be called to set the document date (or other identifier)
+at any time before (a) the abstract, if present, or (b) its information
+is required in a header or footer.  Use of these macros is optional,
+except that @code{TL} is mandatory if any of @code{RP}, @code{AU},
+@code{AI}, or @code{AB} is called, and @code{AE} is mandatory if
+@code{AB} is called.
+
+@Defmac {RP, [@code{no-repeat-info}] [@code{no-renumber}], ms}
+Use the ``report'' (@acronym{AT&T}: ``released paper'') format for your
+document, creating a separate cover page.  The default arrangement is to
+place most of the document description (title, author names and
+institutions, and abstract, but not the date) at the top of the first
+page.  If the optional @code{no-repeat-info} argument is given,
+@file{ms} produces a cover page but does not repeat any of its
+information subsequently (but see the @code{DA} macro below regarding
+the date).  Normally, @code{RP} sets the page number following the cover
+page to@tie{}1.  Specifying the optional @code{no-renumber} argument
+suppresses this alteration.  Optional arguments can occur in any order.
+@code{no} is recognized as a synonym of @code{no-repeat-info} for
+@code{AT&T} compatibility.
+@endDefmac
+
+@Defmac {TL, , ms}
+Specify the document title.  @file{ms} collects text on input lines
+following this call into the title until reaching @code{AU}, @code{AB},
+or a heading or paragraphing macro call.
+@endDefmac
+
+@Defmac {AU, , ms}
+Specify an author's name.  @file{ms} collects text on input lines
+following this call into the author's name until reaching @code{AI},
+@code{AB}, another @code{AU}, or a heading or paragraphing macro call.
+Call it repeatedly to specify multiple authors.
+@endDefmac
+
+@Defmac {AI, , ms}
+Specify the preceding author's institution.  An @code{AU} call is
+usefully followed by at most one @code{AI} call; if there are more, the
+last @code{AI} call controls.  @file{ms} collects text on input lines
+following this call into the author's institution until reaching
+@code{AU}, @code{AB}, or a heading or paragraphing macro call.
+@endDefmac
+
+@Defmac {DA, [@Var{x} @dots{}], ms}
+Typeset the current date, or any arguments @var{x}, in the center
+footer, and, if @code{RP} is also called, left-aligned at the end of the
+description information on the cover page.
+@endDefmac
+
+@Defmac {ND, [@Var{x} @dots{}], ms}
+Typeset the current date, or any arguments @var{x}, if @code{RP} is also
+called, left-aligned at the end of the document description on the cover
+page.  This is @code{groff} @file{ms}'s default.
+@endDefmac
+
+@Defmac {AB, [@code{no}], ms}
+Begin the abstract.  @file{ms} collects text on input lines following
+this call into the abstract until reaching an @code{AE} call.  By
+default, @file{ms} places the word ``ABSTRACT'' centered and in italics
+above the text of the abstract.  The optional argument @code{no}
+suppresses this heading.
+@endDefmac
+
+@Defmac {AE, , ms}
+End the abstract.
+@endDefmac
+
+An example document description, using a cover page, follows.
+@cindex cover page in [@file{ms}], example markup
+@cindex example markup, cover page in [@file{ms}]
+
+@CartoucheExample
+.RP
+.TL
+The Inevitability of Code Bloat
+in Commercial and Free Software
+.AU
+J.\& Random Luser
+.AI
+University of West Bumblefuzz
+.AB
+This report examines the long-term growth of the code
+bases in two large,
+popular software packages;
+the free Emacs and the commercial Microsoft Word.
+While differences appear in the type or order of
+features added,
+due to the different methodologies used,
+the results are the same in the end.
+.PP
+The free software approach is shown to be superior in
+that while free software can become as bloated as
+commercial offerings,
+free software tends to have fewer serious bugs and the
+added features are more in line with user demand.
+.AE
+
+@r{@dots{}the rest of the paper@dots{}}
+@endCartoucheExample
+
+@c ---------------------------------------------------------------------
+
+@node ms Body Text, ms Page Layout, ms Document Description Macros, ms
+@subsection Body Text
+@cindex @file{ms} macros, body text
+
+A variety of macros, registers, and strings can be used to structure and
+style the body of your document.  They organize your text into
+paragraphs, headings, footnotes, and inclusions of material such as
+tables and figures.
+
+@menu
+* Text settings in ms::
+* Typographical symbols in ms::
+* Paragraphs in ms::
+* Headings in ms::
+* Typeface and decoration::
+* Lists in ms::
+* Indented regions in ms::
+* ms keeps and displays::
+* ms Insertions::
+* ms Footnotes::
+* ms language and localization::
+@end menu
+
+@c ---------------------------------------------------------------------
+
+@node Text settings in ms, Typographical symbols in ms, ms Body Text, ms Body Text
+@subsubsection Text settings
+@cindex @file{ms} macros, text settings
+
+The @code{FAM} string, a GNU extension, sets the font family for body
+text; the default is @samp{T}.  The @code{PS} and @code{VS} registers
+set the type size and vertical spacing (distance between text
+baselines), respectively.  The font family and type size are ignored on
+terminal devices.  Setting these parameters before the first call of a
+heading, paragraphing, or (non-date) document description macro also
+applies them to headers, footers, and (for @code{FAM}) footnotes.
+
+Which font families are available depends on the output device; as a
+convention, @code{T} selects a serif family (``Times''), @code{H} a
+sans-serif family (``Helvetica''), and @code{C} a monospaced family
+(``Courier'').  The man page for the output driver documents its font
+repertoire.  Consult the @cite{groff@r{(1)}} man page for lists of
+available output devices and their drivers.
+
+The hyphenation mode (as used by the @code{hy} request) is set from the
+@code{HY} register.  Setting @code{HY} to @samp{0} is equivalent to
+using the @code{nh} request.  This is a Tenth Edition Research Unix
+extension.
+
+@c ---------------------------------------------------------------------
+
+@node Typographical symbols in ms, Paragraphs in ms, Text settings in ms, ms Body Text
+@subsubsection Typographical symbols
+@cindex @file{ms} macros, obtaining typographical symbols
+
+@file{ms} provides a few strings to obtain typographical symbols not
+easily entered with the keyboard.  These and many others are available
+as special character escape sequences---see the @cite{groff_char@r{(7)}}
+man page.
+
+@Defmpstr {-, ms}
+Interpolate an em dash.
+@endDefmpstr
+
+@DefmpstrList {Q, ms}
+@DefmpstrListEndx {U, ms}
+Interpolate typographer's quotation marks where available, and neutral
+double quotes otherwise.  @code{\*Q} is the left quote and @code{\*U}
+the right.
+@endDefmpstr
+
+@c ---------------------------------------------------------------------
+
+@node Paragraphs in ms, Headings in ms, Typographical symbols in ms, ms Body Text
+@subsubsection Paragraphs
+@cindex @file{ms} macros, paragraph handling
+
+Paragraphing macros @dfn{break}, or terminate, any pending output line
+so that a new paragraph can begin.  Several paragraph types are
+available, differing in how indentation applies to them: to left, right,
+or both margins; to the first output line of the paragraph, all output
+lines, or all but the first.  All paragraphing macro calls cause the
+insertion of vertical space in the amount stored in the @code{PD}
+register, except at page or column breaks.  Alternatively, a blank input
+line breaks the output line and vertically spaces by one vee.
+
+@Defmac {LP, , ms}
+Set a paragraph without any (additional) indentation.
+@endDefmac
+
+@Defmac {PP, , ms}
+Set a paragraph with a first-line left indentation in the amount stored
+in the @code{PI} register.
+@endDefmac
+
+@Defmac {IP, [@Var{marker} [@Var{width}]], ms}
+Set a paragraph with a left indentation.  The optional @var{marker} is
+not indented and is empty by default.  It has several applications;
+see @ref{Lists in ms}.  @var{width} overrides the indentation amount
+stored in the @code{PI} register; its default unit is @samp{n}.  Once
+specified, @var{width} applies to further @code{IP} calls until
+specified again or a heading or different paragraphing macro is called.
+@endDefmac
+
+@Defmac {QP, , ms}
+Set a paragraph indented from both left and right margins by the amount
+stored in the @code{QI} register.
+@endDefmac
+
+@DefmacList {QS, , ms}
+@DefmacListEndx {QE, , ms}
+Begin (@code{QS}) and end (@code{QE}) a region where each paragraph is
+indented from both margins by the amount stored in the @code{QI}
+register.  The text between @code{QS} and @code{QE} can be structured
+further by use of other paragraphing macros.
+@endDefmac
+
+@Defmac {XP, , ms}
+Set an ``exdented'' paragraph---one with a left indentation in the
+amount stored in the @code{PI} register on every line @emph{except} the
+first (also known as a hanging indent).  This is a Berkeley extension.
+@endDefmac
+
+The following example illustrates the use of paragraphing macros.
+
+@CartoucheExample
+.NH 2
+Cases used in the 2001 study
+.LP
+Two software releases were considered for this report.
+.PP
+The first is commercial software;
+the second is free.
+.IP \[bu]
+Microsoft Word for Windows,
+starting with version 1.0 through the current version
+(Word 2000).
+.IP \[bu]
+GNU Emacs,
+from its first appearance as a standalone editor through
+the current version (v20).
+See [Bloggs 2002] for details.
+.QP
+Franklin's Law applied to software:
+software expands to outgrow both RAM and disk space over
+time.
+.SH
+Bibliography
+.XP
+Bloggs, Joseph R.,
+.I "Everyone's a Critic" ,
+Underground Press, March 2002.
+A definitive work that answers all questions and
+criticisms about the quality and usability of free
+software.
+@endCartoucheExample
+
+@c ---------------------------------------------------------------------
+
+@node Headings in ms, Typeface and decoration, Paragraphs in ms, ms Body Text
+@subsubsection Headings
+@cindex @file{ms} macros, headings
+
+Use headings to create a sequential or hierarchical structure for your
+document.  The @file{ms} macros print headings in @strong{bold} using
+the same font family and, by default, type size as the body text.
+Headings are available with and without automatic numbering.  Text on
+input lines following the macro call becomes the heading's title.  Call
+a paragraphing macro to end the heading text and start the section's
+content.
+
+@DefmacList {NH, [@Var{depth}], ms}
+@DefmacListEnd {NH, @t{S} @Var{heading-depth-index} @dots{}, ms}
+Set an automatically numbered heading.
+
+@file{ms} produces a numbered heading the form @var{a.b.c@dots{}}, to
+any depth desired, with the numbering of each depth increasing
+automatically and being reset to zero when a more significant level is
+increased.  ``1''@tie{}is the most significant or coarsest division of
+the document.  Only non-zero values are output.  If @var{depth} is
+omitted, it is taken to be @samp{1}.
+
+If you specify @var{depth} such that an ascending gap occurs relative to
+the previous @code{NH} call---that is, you ``skip a depth'', as by
+@samp{.NH 1} and then @samp{.NH 3}---@code{groff} @file{ms} emits a
+warning on the standard error stream.
+
+Alternatively, you can give @code{NH} a first argument of@tie{}@code{S},
+followed by integers to number the heading depths explicitly.  Further
+automatic numbering, if used, resumes using the specified indices as
+their predecessors.
+@c Although undocumented in Tuthill's 4.2BSD ms.diffs paper...
+This feature is a Berkeley extension.
+@endDefmac
+
+An example may be illustrative.
+
+@CartoucheExample
+.NH 1
+Animalia
+.NH 2
+Arthropoda
+.NH 3
+Crustacea
+.NH 2
+Chordata
+.NH S 6 6 6
+Daimonia
+.NH 1
+Plantae
+@endCartoucheExample
+
+The above results in numbering as follows; the vertical space that
+normally precedes each heading is omitted.
+
+@Example
+1.  Animalia
+1.1.  Arthropoda
+1.1.1.  Crustacea
+1.2.  Chordata
+6.6.6.  Daimonia
+7.  Plantae
+@endExample
+
+@DefmpstrList {SN-STYLE, ms}
+@DefmpstrItemx {SN-DOT, ms}
+@DefmpstrItemx {SN-NO-DOT, ms}
+@DefmpstrListEndx {SN, ms}
+After @code{NH} is called, the assigned number is made available in the
+strings @code{SN-DOT} (as it appears in a printed heading with default
+formatting, followed by a terminating period) and @code{SN-NO-DOT} (with
+the terminating period omitted).  These are GNU extensions.
+
+You can control the style used to print numbered headings by defining an
+appropriate alias for the string @code{SN-STYLE}.  By default,
+@code{SN-STYLE} is aliased to @code{SN-DOT}.  If you prefer to omit the
+terminating period from numbers appearing in numbered headings, you may
+define the alias as follows.
+
+@Example
+.als SN-STYLE SN-NO-DOT
+@endExample
+
+@noindent
+Any such change in numbering style becomes effective from the next use
+of @code{NH} following redefinition of the alias for @code{SN-STYLE}.
+The formatted number of the current heading is available in the
+@code{SN} string (a feature first documented by Berkeley), which
+facilitates its inclusion in, for example, table captions, equation
+labels, and @code{XS}/@code{XA}/@code{XE} table of contents entries.
+@endDefmpstr
+
+@Defmac {SH, [@Var{depth}], ms}
+Set an unnumbered heading.
+
+The optional @var{depth} argument is a GNU extension indicating the
+heading depth corresponding to the @var{depth} argument of @code{NH}.
+It matches the type size at which the heading is set to that of a
+numbered heading at the same depth when the @code{GROWPS} and
+@code{PSINCR} heading size adjustment mechanism is in effect.
+@endDefmac
+
+If the @code{GROWPS} register is set to a value greater than the
+@var{level} argument to @code{NH} or @code{SH}, the type size of a
+heading produced by these macros increases by @code{PSINCR} units over
+the size specified by @code{PS} multiplied by the difference of
+@code{GROWPS} and @var{level}.  The value stored in @code{PSINCR} is
+interpreted in @code{groff} basic units; the @code{p} scaling unit
+should be employed when assigning a value specified in points.  For
+example, the sequence
+
+@CartoucheExample
+.nr PS 10
+.nr GROWPS 3
+.nr PSINCR 1.5p
+.NH 1
+Carnivora
+.NH 2
+Felinae
+.NH 3
+Felis catus
+.SH 2
+Machairodontinae
+@endCartoucheExample
+
+@noindent
+will cause ``1. Carnivora'' to be printed in 13-point text, followed by
+``1.1. Felinae'' in 11.5-point text, while ``1.1.1. Felis catus'' and
+all more deeply nested heading levels will remain in the 10-point text
+specified by the @code{PS} register.  ``Machairodontinae'' is printed at
+11.5 points, since it corresponds to heading level@tie{}2.
+
+The @code{HORPHANS} register operates in conjunction with the @code{NH}
+and @code{SH} macros to inhibit the printing of isolated headings at the
+bottom of a page; it specifies the minimum number of lines of an
+immediately subsequent paragraph that must be kept on the same page as
+the heading.  If insufficient space remains on the current page to
+accommodate the heading and this number of lines of paragraph text, a
+page break is forced before the heading is printed.  Any display macro
+call or @code{tbl}, @code{pic}, or @code{eqn} region between the heading
+and the subsequent paragraph suppresses this grouping.  @xref{ms keeps
+and displays} and @ref{ms Insertions}.
+
+@c ---------------------------------------------------------------------
+
+@node Typeface and decoration, Lists in ms, Headings in ms, ms Body Text
+@subsubsection Typeface and decoration
+
+The @file{ms} macros provide a variety of ways to style text.
+Attend closely to the ordering of arguments labeled @var{pre} and
+@var{post}, which is not intuitive.  Support for @var{pre}
+arguments is a GNU extension.@footnote{This idiosyncrasy arose through
+feature accretion; for example, the @code{B} macro in Version@tie{}6
+Unix @file{ms} (1975) accepted only one argument, the text to be set in
+boldface.  By Version@tie{}7 (1979) it recognized a second argument; in
+1990, @code{groff} @file{ms} added a ``pre'' argument, placing it third
+to avoid breaking support for older documents.}
+
+@Defmac {B, [@Var{text} [@Var{post} [@Var{pre}]]], ms}
+Style @var{text} in @b{bold}, followed by @var{post} in the previous
+font style without intervening space, and preceded by @var{pre}
+similarly.  Without arguments, @file{ms} styles subsequent text in bold
+until the next paragraphing, heading, or no-argument typeface macro
+call.
+@endDefmac
+
+@Defmac {R, [@Var{text} [@Var{post} [@Var{pre}]]], ms}
+As @code{B}, but use the roman style (upright text of normal weight)
+instead of bold.  Argument recognition is a GNU extension.
+@endDefmac
+
+@Defmac {I, [@Var{text} [@Var{post} [@Var{pre}]]], ms}
+As @code{B}, but use an @i{italic} or oblique style instead of bold.
+@endDefmac
+
+@Defmac {BI, [@Var{text} [@Var{post} [@Var{pre}]]], ms}
+As @code{B}, but use a bold italic or bold oblique style instead of
+upright bold.  This is a Tenth Edition Research Unix extension.
+@c possibly 9th, but definitely not Berkeley
+@endDefmac
+
+@Defmac {CW, [@Var{text} [@Var{post} [@Var{pre}]]], ms}
+As @code{B}, but use a @t{constant-width} (monospaced) roman typeface
+instead of bold.  This is a Tenth Edition Research Unix extension.
+@c possibly 9th, but definitely not Berkeley
+@endDefmac
+
+@Defmac {BX, [@Var{text}], ms}
+Typeset @var{text} and draw a box around it.  On terminal devices,
+reverse video is used instead.  If you want @var{text} to contain space,
+use unbreakable space or horizontal motion escape sequences (@code{\~},
+@code{\@key{SP}}, @code{\^}, @code{\|}, @code{\0} or @code{\h}).
+@endDefmac
+
+@Defmac {UL, [@Var{text} [@Var{post}]], ms}
+Typeset @var{text} with an underline.  @var{post}, if present, is set
+after @var{text} with no intervening space.
+@endDefmac
+
+@Defmac {LG, , ms}
+Set subsequent text in larger type (two points larger than the
+current size) until the next type size, paragraphing, or heading macro
+call.  You can specify this macro multiple times to enlarge the type
+size as needed.
+@endDefmac
+
+@Defmac {SM, , ms}
+Set subsequent text in smaller type (two points smaller than the current
+size) until the next type size, paragraphing, or heading macro call.
+You can specify this macro multiple times to reduce the type size as
+needed.
+@endDefmac
+
+@Defmac {NL, , ms}
+Set subsequent text at the normal type size (the amount in the @code{PS}
+register).
+@endDefmac
+
+@var{pre} and @var{post} arguments are typically used to simplify the
+attachment of punctuation to styled words.  When @var{pre} is used,
+a hyphenation control escape sequence @code{\%} that would ordinarily
+start @var{text} must start @var{pre} instead to have the desired
+effect.
+
+@CartoucheExample
+The CS course's students found one C language keyword
+.CW static ) \%(
+most troublesome.
+@endCartoucheExample
+
+The foregoing example produces output as follows.
+
+@CartoucheExample
+@r{The CS course's students found one C language keyword (@t{static})
+most troublesome.}
+@endCartoucheExample
+
+You can use the output line continuation escape sequence @code{\c} to
+achieve the same result (@pxref{Line Continuation}).  It is also
+portable to older @file{ms} implementations.
+
+@CartoucheExample
+The CS course's students found one C language keyword
+\%(\c
+.CW \%static )
+most troublesome.
+@endCartoucheExample
+
+@code{groff} @file{ms} also offers strings to begin and end super- and
+subscripting.  These are GNU extensions.
+
+@DefmpstrList {@lbracechar{}, ms}
+@DefmpstrListEndx {@rbracechar{}, ms}
+Begin and end superscripting, respectively.
+@endDefmpstr
+
+@DefmpstrList {<, ms}
+@DefmpstrListEndx {>, ms}
+Begin and end subscripting, respectively.
+@endDefmpstr
+
+Rather than calling the @code{CW} macro, in @code{groff} @file{ms} you
+might prefer to change the font family to Courier by setting the
+@code{FAM} string to @samp{C}.  You can then use all four style macros
+above, returning to the default family (Times) with @samp{.ds FAM T}.
+Because changes to @code{FAM} take effect only at the next paragraph,
+@code{CW} remains useful to ``inline'' a change to the font family,
+similarly to the practice of this document in noting syntactical
+elements of @file{ms} and @code{groff}.
+
+@c ---------------------------------------------------------------------
+
+@node Lists in ms, Indented regions in ms, Typeface and decoration, ms Body Text
+@subsubsection Lists
+@cindex @file{ms} macros, lists
+
+The @var{marker} argument to the @code{IP} macro can be employed to
+present a variety of lists; for instance, you can use a bullet glyph
+(@code{\[bu]}) for unordered lists, a number (or auto-incrementing
+register) for numbered lists, or a word or phrase for glossary-style or
+definition lists.  If you set the paragraph indentation register
+@code{PI} before calling @code{IP}, you can later reorder the items in
+the list without having to ensure that a @var{width} argument remains
+affixed to the first call.
+
+The following is an example of a bulleted list.
+@cindex example markup, bulleted list [@file{ms}]
+@cindex bulleted list, example markup [@file{ms}]
+
+@CartoucheExample
+.nr PI 2n
+A bulleted list:
+.IP \[bu]
+lawyers
+.IP \[bu]
+guns
+.IP \[bu]
+money
+@endCartoucheExample
+
+@Example
+A bulleted list:
+
+@bullet{} lawyers
+
+@bullet{} guns
+
+@bullet{} money
+@endExample
+
+The following is an example of a numbered list.
+@cindex example markup, numbered list [@file{ms}]
+@cindex numbered list, example markup [@file{ms}]
+
+@CartoucheExample
+.nr step 0 1
+.nr PI 3n
+A numbered list:
+.IP \n+[step]
+lawyers
+.IP \n+[step]
+guns
+.IP \n+[step]
+money
+@endCartoucheExample
+
+@Example
+A numbered list:
+
+1. lawyers
+
+2. guns
+
+3. money
+@endExample
+
+Here we have employed the @code{nr} request to create a register of our
+own, @samp{step}.  We initialized it to zero and assigned it an
+auto-increment of 1.  Each time we use the escape sequence
+@samp{\n+[PI]} (note the plus sign), the formatter applies the increment
+just before interpolating the register's value.  Preparing the @code{PI}
+register as well enables us to rearrange the list without the tedium of
+updating macro calls.
+
+The next example illustrates a glossary-style list.
+@cindex example markup, glossary-style list [@file{ms}]
+@cindex glossary-style list, example markup [@file{ms}]
+
+@CartoucheExample
+A glossary-style list:
+.IP lawyers 0.4i
+Two or more attorneys.
+.IP guns
+Firearms,
+preferably large-caliber.
+.IP money
+Gotta pay for those
+lawyers and guns!
+@endCartoucheExample
+
+@Example
+A glossary-style list:
+
+lawyers
+      Two or more attorneys.
+
+guns  Firearms, preferably large-caliber.
+
+money
+      Gotta pay for those lawyers and guns!
+@endExample
+
+In the previous example, observe how the @code{IP} macro places the
+definition on the same line as the term if it has enough space.  If this
+is not what you want, there are a few workarounds we will illustrate by
+modifying the example.  First, you can use a @code{br} request to force
+a break after printing the term or label.
+
+@CartoucheExample
+.IP guns
+.br
+Firearms,
+@endCartoucheExample
+
+Second, you could apply the @code{\p} escape sequence to force a break.
+The space following the escape sequence is important; if you omit it,
+@code{groff} prints the first word of the paragraph text on the same
+line as the term or label (if it fits) @emph{then} breaks the line.
+
+@CartoucheExample
+.IP guns
+\p Firearms,
+@endCartoucheExample
+
+Finally, you may append a horizontal motion to the marker with the
+@code{\h} escape sequence; using the same amount as the indentation will
+ensure that the marker is too wide for @code{groff} to treat it as
+``fitting'' on the same line as the paragraph text.
+
+@CartoucheExample
+.IP guns\h'0.4i'
+Firearms,
+@endCartoucheExample
+
+In each case, the result is the same.
+
+@Example
+A glossary-style list:
+
+lawyers
+      Two or more attorneys.
+
+guns
+      Firearms, preferably large-caliber.
+
+money
+      Gotta pay for those lawyers and guns!
+@endExample
+
+@c ---------------------------------------------------------------------
+
+@node Indented regions in ms, ms keeps and displays, Lists in ms, ms Body Text
+@subsubsection Indented regions
+
+You may need to indent a region of text while otherwise formatting it
+normally.  Indented regions can be nested; you can change @code{\n[PI]}
+before each call to vary the amount of inset.
+
+@Defmac {RS, , ms}
+Begin a region where headings, paragraphs, and displays are indented
+(further) by the amount stored in the @code{PI} register.
+@endDefmac
+
+@Defmac {RE, , ms}
+End the (next) most recent indented region.
+@endDefmac
+
+This feature enables you to easily line up text under hanging and
+indented paragraphs.
+@cindex @file{ms} macros, nested lists
+@cindex nested lists [@file{ms}]
+For example, you may wish to structure lists hierarchically.
+
+@CartoucheExample
+.IP \[bu] 2
+Lawyers:
+.RS
+.IP \[bu]
+Dewey,
+.IP \[bu]
+Cheatham,
+and
+.IP \[bu]
+and Howe.
+.RE
+.IP \[bu]
+Guns
+@endCartoucheExample
+
+@Example
+@bullet{} Lawyers:
+
+  @bullet{}  Dewey,
+
+  @bullet{}  Cheatham, and
+
+  @bullet{}  Howe.
+
+@bullet{} Guns
+@endExample
+
+@c ---------------------------------------------------------------------
+
+@node ms keeps and displays, ms Insertions, Indented regions in ms, ms Body Text
+@subsubsection Keeps, boxed keeps, and displays
+@cindex @file{ms} macros, displays
+@cindex @file{ms} macros, keeps
+@cindex keeps [@file{ms}]
+
+On occasion, you may want to @dfn{keep} several lines of text, or a
+region of a document, together on a single page, preventing an automatic
+page break within certain boundaries.  This can cause a page break to
+occur earlier than it normally would.  For example, you may want to keep
+two paragraphs together, or a paragraph that refers to a table, list, or
+figure adjacent to the item it discusses.  @file{ms} provides the
+@code{KS} and @code{KE} macros for this purpose.
+
+You can alternatively specify a @dfn{floating keep}:@: if a keep cannot
+fit on the current page, @file{ms} holds its contents and
+allows material following the keep (in the source document) to fill the
+remainder of the current page.  When the page breaks, whether by
+reaching the end or @code{bp} request, @file{ms} puts the floating keep
+at the beginning of the next page.  This is useful for placing large
+graphics or tables that do not need to appear exactly where they occur
+in the source document.
+
+@DefmacList {KS, , ms}
+@DefmacItemx {KF, , ms}
+@DefmacListEndx {KE, , ms}
+@code{KS} begins a keep, @code{KF} a floating keep, and @code{KE} ends a
+keep of either kind.
+@endDefmac
+
+As an alternative to the keep mechanism, the @code{ne} request forces a
+page break if there is not at least the amount of vertical space
+specified in its argument remaining on the page (@pxref{Page Control}).
+One application of @code{ne} is to reserve space on the page for a
+figure or illustration to be included later.
+
+@cindex boxes [@file{ms}]
+A @dfn{boxed keep} has a frame drawn around it.
+
+@DefmacList {B1, , ms}
+@DefmacListEndx {B2, , ms}
+@code{B1} begins a keep with a box drawn around it.  @code{B2} ends a
+boxed keep.
+@endDefmac
+
+Boxed keep macros cause breaks; if you need to box a word or phrase
+within a line, see the @code{BX} macro in @ref{Typeface and decoration}.
+Box lines are drawn as close as possible to the text they enclose so
+that they are usable within paragraphs.  If you wish to box one or more
+paragraphs, you may improve the appearance by calling @code{B1} after
+the first paragraphing macro, and by adding a small amount of vertical
+space before calling @code{B2}.
+
+@c Wrap example at 58 columns.
+@CartoucheExample
+.LP
+.B1
+.I Warning:
+Happy Fun Ball may suddenly accelerate to dangerous
+speeds.
+.sp \n[PD]/2 \" space by half the inter-paragraph distance
+.B2
+@endCartoucheExample
+
+If you want a boxed keep to float, you will need to enclose the
+@code{B1} and @code{B2} calls within a pair of @code{KF} and @code{KE}
+calls.
+
+@cindex displays [@file{ms}]
+@dfn{Displays} turn off filling; lines of verse or program code are
+shown with their lines broken as in the source document without
+requiring @code{br} requests between lines.  Displays can be kept on a
+single page or allowed to break across pages.  The @code{DS} macro
+begins a kept display of the layout specified in its first argument;
+non-kept displays are begun with dedicated macros corresponding to their
+layout.
+
+@DefmacList {DS, @t{L}, ms}
+@DefmacListEndx {LD, , ms}
+Begin (@code{DS}:@: kept) left-aligned display.
+@endDefmac
+
+@DefmacList {DS, [@t{I} [@Var{indent}]], ms}
+@DefmacListEndx {ID, [@Var{indent}], ms}
+Begin (@code{DS}:@: kept) display indented by @var{indent} if specified,
+and by the amount of the @code{DI} register otherwise.
+@endDefmac
+
+@DefmacList {DS, @t{B}, ms}
+@DefmacListEndx {BD, , ms}
+Begin a (@code{DS}:@: kept) a block display:@: the entire display is
+left-aligned, but indented such that the longest line in the display
+is centered on the page.
+@endDefmac
+
+@DefmacList {DS, @t{C}, ms}
+@DefmacListEndx {CD, , ms}
+Begin a (@code{DS}:@: kept) centered display:@: each line in the display
+is centered.
+@endDefmac
+
+@DefmacList {DS, @t{R}, ms}
+@DefmacListEndx {RD, , ms}
+Begin a (@code{DS}:@: kept) right-aligned display.  This is a GNU
+extension.
+@endDefmac
+
+@Defmac {DE, , ms}
+End any display.
+@endDefmac
+
+The distance stored in the @code{DD} register is inserted before and
+after each pair of display macros; this is a Berkeley extension.  In
+@code{groff} @file{ms}, this distance replaces any adjacent
+inter-paragraph distance or subsequent spacing prior to a section
+heading.  The @code{DI} register is a GNU extension; its value is an
+indentation applied to displays created with @samp{.DS} and @samp{.ID}
+without arguments, to @samp{.DS I} without an indentation argument, and
+to indented equations set with @samp{.EQ}.  Changes to either register
+take effect at the next display boundary.
+
+@c ---------------------------------------------------------------------
+
+@node ms Insertions, ms Footnotes, ms keeps and displays, ms Body Text
+@subsubsection Tables, figures, equations, and references
+@cindex @file{ms} macros, tables
+@cindex @file{ms} macros, figures
+@cindex @file{ms} macros, equations
+@cindex @file{ms} macros, references
+@cindex tables [@file{ms}]
+@cindex figures [@file{ms}]
+@cindex equations [@file{ms}]
+@cindex references [@file{ms}]
+
+The @file{ms} package is often used with the @code{tbl}, @code{pic},
+@code{eqn}, and @code{refer} preprocessors.
+@pindex tbl
+@pindex pic
+@pindex eqn
+@pindex refer
+Mark text meant for preprocessors by enclosing it in pairs of tokens
+as follows, with nothing between the dot and the macro name.  The
+preprocessors match these tokens only at the start of an input line.
+
+@DefmacList {TS, [@code{H}], ms}
+@DefmacListEndx {TE, , ms}
+Demarcate a table to be processed by the @code{tbl} preprocessor.  The
+optional argument@tie{}@code{H} to @code{TS} instructs @file{ms} to
+repeat table rows (often column headings) at the top of each new page
+the table spans, if applicable; calling the @code{TH} macro marks the
+end of such rows.  The GNU @cite{tbl@r{(1)}} man page provides a
+comprehensive reference to the preprocessor and offers examples of its
+use.
+@endDefmac
+
+@DefmacList {PS, , ms}
+@DefmacItemx {PE, , ms}
+@DefmacListEndx {PF, , ms}
+@code{PS} begins a picture to be processed by the @command{gpic}
+preprocessor; either of @code{PE} or @code{PF} ends it, the latter with
+``flyback'' to the vertical position at its top.  You can create
+@code{pic} input manually or with a program such as @code{xfig}.
+@endDefmac
+
+@DefmacList {EQ, [@Var{align} [@Var{label}]], ms}
+@DefmacListEndx {EN, , ms}
+Demarcate an equation to be processed by the @code{eqn} preprocessor.
+The equation is centered by default; @var{align} can be @samp{C},
+@samp{L}, or @samp{I} to (explicitly) center, left-align, or indent it
+by the amount stored in the @code{DI} register, respectively.  If
+specified, @var{label} is set right-aligned.
+@endDefmac
+
+@DefmacList {[, , ms}
+@DefmacListEndx {], , ms}
+Demarcate a bibliographic citation to be processed by the @code{refer}
+preprocessor.  The GNU @cite{refer@r{(1)}} man page provides a
+comprehensive reference to the preprocessor and the format of its
+bibliographic database.  Type @samp{man refer} at the command line to
+view it.
+@endDefmac
+
+When @code{refer} emits collected references (as might be done on a
+``Works Cited'' page), it interpolates the @code{REFERENCES} string as
+an unnumbered heading (@code{SH}).
+
+@cindex table, multi-page, example [@file{ms}]
+@cindex multi-page table example [@file{ms}]
+The following is an example of how to set up a table that may print
+across two or more pages.
+
+@CartoucheExample
+.TS H
+allbox;
+Cb | Cb .
+Part@arrow{}Description
+_
+.TH
+.T&
+GH-1978@arrow{}Fribulating gonkulator
+@r{@dots{}the rest of the table follows@dots{}}
+.TE
+@endCartoucheExample
+
+@noindent
+Attempting to place a multi-page table inside a keep can lead to
+unpleasant results, particularly if the @code{tbl} @code{allbox} option
+is used.
+
+@cindex equation example [@file{ms}]
+Mathematics can be typeset using the language of the @code{eqn}
+preprocessor.
+
+@CartoucheExample
+.EQ C (\*[SN-NO-DOT]a)
+p ~ = ~ q sqrt @{ ( 1 + ~ ( x / q sup 2 ) @}
+.EN
+@endCartoucheExample
+
+@noindent
+This input formats a labelled equation.  We used the @code{SN-NO-DOT}
+string to base the equation label on the current heading number, giving
+us more flexibility to reorganize the document.
+
+Use @command{groff} options to run preprocessors on the input:@:
+@option{-e} for @command{geqn}, @option{-p} for @command{gpic},
+@option{-R} for @command{grefer}, and @option{-t} for @command{gtbl}.
+
+@c ---------------------------------------------------------------------
+
+@node ms Footnotes, , ms Insertions, ms Body Text
+@subsubsection Footnotes
+@cindex @file{ms} macros, footnotes
+@cindex footnotes [@file{ms}]
+
+@cindex footnote marker [@file{ms}]
+@cindex marker, footnote [@file{ms}]
+A footnote is typically anchored to a place in the text with a
+@dfn{marker}, which is a small integer, a symbol such as a dagger, or
+arbitrary user-specified text.
+
+@Defmpstr {*, ms}
+Place an @dfn{automatic number}, an automatically generated numeric
+footnote marker, in the text.  Each time this string is interpolated,
+the number it produces increments by one.  Automatic numbers start at 1.
+This is a Berkeley extension.
+@endDefesc
+
+Enclose the footnote text in @code{FS} and @code{FE} macro calls to set
+it at the nearest available ``foot'', or bottom, of a text column or
+page.
+
+@DefmacList {FS, [@Var{marker}], ms}
+@DefmacListEndx {FE, , ms}
+Begin (@code{FS}) and end (@code{FE}) a footnote.  @code{FS} calls
+@code{FS-MARK} with any supplied @var{marker} argument, which is then
+also placed at the beginning of the footnote text.  If @var{marker} is
+omitted, the next pending automatic footnote number enqueued by
+interpolation of the @code{*} string is used, and if none exists,
+nothing is prefixed.
+@endDefmac
+
+You may not desire automatically numbered footnotes in spite of their
+convenience.  You can indicate a footnote with a symbol or other text by
+specifying its marker at the appropriate place (for example, by using
+@code{\[dg]} for the dagger glyph) @emph{and} as an argument to the
+@code{FS} macro.  Such manual marks should be repeated as arguments to
+@code{FS} or as part of the footnote text to disambiguate their
+correspondence.  You may wish to use @code{\*@{} and @code{\*@}} to
+superscript the marker at the anchor point, in the footnote text, or
+both.
+
+@code{groff} @file{ms} provides a hook macro, @code{FS-MARK}, for
+user-determined operations to be performed when the @code{FS} macro is
+called.  It is passed the same arguments as @code{FS} itself.  An
+application of @code{FS-MARK} is anchor placement for a hyperlink
+reference, so that a footnote can link back to its referential
+context.@footnote{``Portable Document Format Publishing with GNU
+Troff'', @file{pdfmark.ms} in the @code{groff} distribution, uses this
+technique.}  By default, this macro has an empty definition.
+@code{FS-MARK} is a GNU extension.
+
+@cindex footnotes, and keeps [@file{ms}]
+@cindex keeps, and footnotes [@file{ms}]
+@cindex footnotes, and displays [@file{ms}]
+@cindex displays, and footnotes [@file{ms}]
+Footnotes can be safely used within keeps and displays, but you should
+avoid using automatically numbered footnotes within floating keeps.  You
+can place a second @code{\**} interpolation between a @code{\**} and its
+corresponding @code{FS} call as long as each @code{FS} call occurs
+@emph{after} the corresponding @code{\**} and occurrences of @code{FS}
+are in the same order as corresponding occurrences of @code{\**}.
+
+Footnote text is formatted as paragraphs are, using analogous
+parameters.  The registers @code{FI}, @code{FPD}, @code{FPS}, and
+@code{FVS} correspond to @code{PI}, @code{PD}, @code{PS}, and @code{CS},
+respectively; @code{FPD}, @code{FPS}, and @code{FVS} are GNU extensions.
+
+The @code{FF} register controls the formatting of automatically numbered
+footnote paragraphs and those for which @code{FS} is given a marker
+argument.  @xref{ms Document Control Settings}.
+
+The default footnote line length is 11/12ths of the normal line length
+for compatibility with the expectations of historical @file{ms}
+documents; you may wish to set the @code{FR} string to @samp{1} to align
+with contemporary typesetting practices.  In the
+past,@footnote{Unix Version@tie{}7 @file{ms}, its descendants, and GNU
+@file{ms} prior to @code{groff} version 1.23.0} an @code{FL} register
+was used for the line length in footnotes; however, setting this
+register at document initialization time had no effect on the footnote
+line length in multi-column arrangements.@footnote{You could reset it
+after each call to @code{.1C}, @code{.2C}, or @code{.MC}.}
+
+@code{FR} should be used in preference to the old @code{FL} register in
+contemporary documents.  The footnote line length is effectively
+computed as @samp{@slanted{column-width} * \*[FR]}.  If an absolute
+footnote line length is required, recall that arithmetic expressions in
+@code{roff} input are evaluated strictly from left to right, with no
+operator precedence (parentheses are honored).
+
+@Example
+.ds FR 0+3i \" Set footnote line length to 3 inches.
+@endExample
+
+@c ---------------------------------------------------------------------
+
+@node ms language and localization, ms Page Layout, ms Footnotes, ms Body Text
+@subsubsection Language and localization
+@cindex @file{ms} macros, language
+@cindex @file{ms} macros, localization
+@cindex language [@file{ms}]
+@cindex localization [@file{ms}]
+
+@code{groff} @file{ms} provides several strings that you can customize
+for your own purposes, or redefine to adapt the macro package to
+languages other than English.  It is already localized for
+@c cs, de, fr, it, sv
+Czech, German, French, Italian, and Swedish.  Load the desired
+localization macro package after @file{ms}; see the
+@cite{groff_tmac@r{(5)}} man page.
+
+@CartoucheExample
+$ groff -ms -mfr bienvenue.ms
+@endCartoucheExample
+
+The following strings are available.
+
+@Defmpstr {REFERENCES, ms}
+Contains the string printed at the beginning of a references
+(bibliography) page produced with GNU @cite{refer@r{(1)}}.  The default
+is @samp{References}.
+@c XXX: Use of refer(1) with ms is insufficiently documented.
+@endDefmpstr
+
+@Defmpstr {ABSTRACT, ms}
+Contains the string printed at the beginning of the abstract.  The
+default is @samp{\f[I]ABSTRACT\f[]}; it includes font selection escape
+sequences to set the word in italics.
+@endDefmpstr
+
+@Defmpstr {TOC, ms}
+Contains the string printed at the beginning of the table of contents.
+The default is @samp{Table of Contents}.
+@endDefmpstr
+
+@DefmpstrList {MONTH1, ms}
+@DefmpstrItemx {MONTH2, ms}
+@DefmpstrItemx {MONTH3, ms}
+@DefmpstrItemx {MONTH4, ms}
+@DefmpstrItemx {MONTH5, ms}
+@DefmpstrItemx {MONTH6, ms}
+@DefmpstrItemx {MONTH7, ms}
+@DefmpstrItemx {MONTH8, ms}
+@DefmpstrItemx {MONTH9, ms}
+@DefmpstrItemx {MONTH10, ms}
+@DefmpstrItemx {MONTH11, ms}
+@DefmpstrListEndx {MONTH12, ms}
+Contain the full names of the calendar months.  The defaults are in
+English: @samp{January}, @samp{February}, and so on.
+@endDefmpstr
+
+@c ---------------------------------------------------------------------
+
+@node ms Page Layout, Differences from AT&T ms, ms Body Text, ms
+@subsection Page layout
+@cindex @file{ms} macros, page layout
+@cindex page layout [@file{ms}]
+
+@file{ms}'s default page layout arranges text in a single column with
+the page number between hyphens centered in a header on each page except
+the first, and produces no footers.  You can customize this arrangement.
+
+@menu
+* ms Headers and Footers::
+* Tab Stops in ms::
+* ms Margins::
+* ms Multiple Columns::
+* ms TOC::
+@end menu
+
+@c ---------------------------------------------------------------------
+
+@node ms Headers and Footers, Tab Stops in ms, ms Page Layout, ms Page Layout
+@subsubsection Headers and footers
+@cindex @file{ms} macros, headers
+@cindex @file{ms} macros, footers
+@cindex headers [@file{ms}]
+@cindex footers [@file{ms}]
+
+There are multiple ways to produce headers and footers.  One is to
+define the strings @code{LH}, @code{CH}, and @code{RH} to set the left,
+center, and right headers, respectively; and @code{LF}, @code{CF}, and
+@code{RF} to set the left, center, and right footers.  This approach
+suffices for documents that do not distinguish odd- and even-numbered
+pages.
+
+Another method is to call macros that set headers or footers for odd- or
+even-numbered pages.  Each such macro takes a delimited argument
+separating the left, center, and right header or footer texts from each
+other.  You can replace the neutral apostrophes (@code{'}) shown below
+with any character not appearing in the header or footer text.  These
+macros are Berkeley extensions.
+
+@DefmacList {OH, @code{'}@Var{left}@code{'}@Var{center}@code{'}@Var{right}@code{'}, ms}
+@DefmacItemx {EH, @code{'}@Var{left}@code{'}@Var{center}@code{'}@Var{right}@code{'}, ms}
+@DefmacItemx {OF, @code{'}@Var{left}@code{'}@Var{center}@code{'}@Var{right}@code{'}, ms}
+@DefmacListEndx {EF, @code{'}@Var{left}@code{'}@Var{center}@code{'}@Var{right}@code{'}, ms}
+The @code{OH} and @code{EH} macros define headers for odd- (recto)
+and even-numbered (verso) pages, respectively; the @code{OF} and
+@code{EF} macros define footers for them.
+@endDefmac
+
+With either method, a percent sign @code{%} in header or footer text is
+replaced by the current page number.  By default, @file{ms} places no
+header on a page numbered ``1'' (regardless of its number format).
+
+@Defmac {P1, , ms}
+Typeset the header even on page@tie{}1.  To be effective, this macro
+must be called before the header trap is sprung on any page numbered
+``1''; in practice, unless your page numbering is unusual, this means
+that you should call it early, before @code{TL} or any heading or
+paragraphing macro.  This is a Berkeley extension.
+@endDefmac
+
+For even greater flexibility, @file{ms} is designed to permit the
+redefinition of the macros that are called when the @code{groff} traps
+that ordinarily cause the headers and footers to be output are sprung.
+@code{PT} (``page trap'') is called by @file{ms} when the header is to
+be written, and @code{BT} (``bottom trap'') when the footer is to be.
+The @code{groff} page location trap that @file{ms} sets up to format the
+header also calls the (normally undefined) @code{HD} macro after
+@code{PT}; you can define @code{HD} if you need additional processing
+after setting the header (for example, to draw a line below it).
+@c Although undocumented in Tuthill's 4.2BSD ms.diffs paper...
+The @code{HD} hook is a Berkeley extension.  Any such macros you
+(re)define must implement any desired specialization for odd-, even-, or
+first numbered pages.
+
+@c ---------------------------------------------------------------------
+
+@node Tab Stops in ms, ms Margins, ms Headers and Footers, ms Page Layout
+@subsubsection Tab stops
+
+Use the @code{ta} request to define tab stops as needed.  @xref{Tabs and
+Fields}.
+
+@Defmac {TA, , ms}
+Reset the tab stops to the @file{ms} default (every 5 ens).
+Redefine this macro to create a different set of default tab stops.
+@endDefmac
+
+@c ---------------------------------------------------------------------
+
+@node ms Margins, ms Multiple Columns, Tab Stops in ms, ms Page Layout
+@subsubsection Margins
+@cindex @file{ms} macros, margins
+
+Control margins using the registers summarized in ``Margin settings'' in
+@ref{ms Document Control Settings} above.  There is no setting for the
+right margin; the combination of page offset @code{\n[PO]} and line
+length @code{\n[LL]} determines it.
+
+@c ---------------------------------------------------------------------
+
+@node ms Multiple Columns, ms TOC, ms Margins, ms Page Layout
+@subsubsection Multiple columns
+@cindex @file{ms} macros, multiple columns
+@cindex multiple columns [@file{ms}]
+
+@file{ms} can set text in as many columns as reasonably fit on the page.
+The following macros force a page break if a multi-column layout is
+active when they are called.  The @code{MINGW} register stores the
+default minimum gutter width; it is a GNU extension.  When multiple
+columns are in use, keeps and the @code{HORPHANS} and @code{PORPHANS}
+registers work with respect to column breaks instead of page breaks.
+
+@Defmac {1C, , ms}
+Arrange page text in a single column (the default).
+@endDefmac
+
+@Defmac {2C, , ms}
+Arrange page text in two columns.
+@endDefmac
+
+@Defmac {MC, [@Var{column-width} [@Var{gutter-width}]], ms}
+Arrange page text in multiple columns.  If you specify no arguments, it
+is equivalent to the @code{2C} macro.  Otherwise, @var{column-width} is
+the width of each column and @var{gutter-width} is the minimum distance
+between columns.
+@endDefmac
+
+@c ---------------------------------------------------------------------
+
+@node ms TOC, Differences from AT&T ms, ms Multiple Columns, ms Page Layout
+@subsubsection Creating a table of contents
+@cindex @file{ms} macros, creating table of contents
+@cindex table of contents, creating [@file{ms}]
+
+Because @code{roff} formatters process their input in a single pass,
+material on page 50, for example, cannot influence what appears on
+page@tie{}1---this poses a challenge for a table of contents at its
+traditional location in front matter, if you wish to avoid manually
+maintaining it.  @file{ms} enables the collection of material to be
+presented in the table of contents as it appears, saving its page number
+along with it, and then emitting the collected contents on demand toward
+the end of the document.  The table of contents can then be resequenced
+to its desired location by physically rearranging the pages of a printed
+document, or as part of post-processing---with a @cite{sed@r{(1)}}
+script to reorder the pages in @command{troff}'s output, with
+@cite{pdfjam@r{(1)}}, or with @cite{gropdf@r{(1)}}'s
+@samp{.pdfswitchtopage} feature, for example.
+
+Define an entry to appear in the table of contents by bracketing its
+text between calls to the @code{XS} and @code{XE} macros.  A typical
+application is to call them immediately after @code{NH} or @code{SH} and
+repeat the heading text within them.  The @code{XA} macro, used within
+@samp{.XS}/@samp{.XE} pairs, supplements an entry---for instance, when
+it requires multiple output lines, whether because a heading is too long
+to fit or because style dictates that page numbers not be repeated.  You
+may wish to indent the text thus wrapped to correspond to its heading
+depth; this can be done in the entry text by prefixing it with tabs or
+horizontal motion escape sequences, or by providing a second argument to
+the @code{XA} macro.  @code{XS} and @code{XA} automatically associate
+the page number where they are called with the text following them, but
+they accept arguments to override this behavior.  At the end of the
+document, call @code{TC} or @code{PX} to emit the table of contents;
+@code{TC} resets the page number to @samp{i} (Roman numeral one), and
+then calls @code{PX}.  All of these macros are Berkeley extensions.
+
+@DefmacList {XS, [@Var{page-number}], ms}
+@DefmacItemx {XA, [@Var{page-number} [@Var{indentation}]], ms}
+@DefmacListEndx {XE, , ms}
+Begin, supplement, and end a table of contents entry.  Each entry is
+associated with @var{page-number} (otherwise the current page number); a
+@var{page-number} of @samp{no} prevents a leader and page number from
+being emitted for that entry.  Use of @code{XA} within
+@code{XS}/@code{XE} is optional; it can be repeated.  If
+@var{indentation} is present, a supplemental entry is indented by that
+amount; ens are assumed if no unit is indicated.  Text on input lines
+between @code{XS} and @code{XE} is stored for later recall by @code{PX}.
+@endDefmac
+
+@Defmac {PX, [@code{no}], ms}
+Switch to single-column layout.  Unless @code{no} is specified, center
+and interpolate the @code{TOC} string in bold and two points larger than
+the body text.  Emit the table of contents entries.
+@endDefmac
+
+@Defmac {TC, [@code{no}], ms}
+Set the page number to@tie{}1, the page number format to lowercase Roman
+numerals, and call @code{PX} (with a @code{no} argument, if present).
+@endDefmac
+
+Here's an example of typical @file{ms} table of contents preparation.
+We employ horizontal escape sequences @code{\h} to indent the entries by
+sectioning depth.
+
+@CartoucheExample
+.NH 1
+Introduction
+.XS
+Introduction
+.XE
+@r{@dots{}}
+.NH 2
+Methodology
+.XS
+\h'2n'Methodology
+.XA
+\h'4n'Fassbinder's Approach
+\h'4n'Kahiu's Approach
+.XE
+@r{@dots{}}
+.NH 1
+Findings
+.XS
+Findings
+.XE
+@r{@dots{}}
+.TC
+@endCartoucheExample
+
+The remaining features in this subsubsection are GNU extensions.
+@code{groff} @file{ms} obviates the need to repeat heading text after
+@code{XS} calls.  Call @code{XN} and @code{XH} after @code{NH} and
+@code{SH}, respectively.
+
+@DefmacList {XN, @Var{heading-text}, ms}
+@DefmacListEndx {XH, @Var{depth} @Var{heading-text}, ms}
+Format @var{heading-text} and create a corresponding table of contents
+entry.  @code{XN} computes the indentation from the depth of the
+preceding @code{NH} call; @code{XH} requires a @var{depth} argument to
+do so.
+@endDefmac
+
+@code{groff} @file{ms} encourages customization of table of contents
+entry production.
+
+@DefmacList {XN-REPLACEMENT, @Var{heading-text}, ms}
+@DefmacListEndx {XH-REPLACEMENT, @Var{depth} @Var{heading-text}, ms}
+These hook macros implement @code{XN} and @code{XH}, respectively.
+They call @code{XN-INIT} and pass their @var{heading-text} arguments to
+@code{XH-UPDATE-TOC}.
+@endDefmac
+
+@DefmacList {XN-INIT, , ms}
+@DefmacListEndx {XH-UPDATE-TOC, @Var{depth} @Var{heading-text}, ms}
+The @code{XN-INIT} hook macro does nothing by default.
+@code{XH-UPDATE-TOC} brackets @var{heading-text} with @code{XS} and
+@code{XE} calls, indenting it by 2 ens per level of @var{depth} beyond
+the first.
+@endDefmac
+
+We could therefore produce a table of contents similar to that in the
+previous example with fewer macro calls.  (The difference is that this
+input follows the ``Approach'' entries with leaders and page numbers.)
+
+@CartoucheExample
+.NH 1
+.XN Introduction
+@r{@dots{}}
+.NH 2
+.XN Methodology
+.XH 3 "Fassbinder's Approach"
+.XH 3 "Kahiu's Approach"
+@r{@dots{}}
+.NH 1
+.XN Findings
+@r{@dots{}}
+@endCartoucheExample
+
+To get the section number of the numbered headings into the table of
+contents entries, we might define @code{XN-REPLACEMENT} as follows.
+(We obtain the heading depth from @code{groff} @file{ms}'s internal
+register @code{nh*hl}.)
+
+@CartoucheExample
+.de XN-REPLACEMENT
+.XN-INIT
+.XH-UPDATE-TOC \\n[nh*hl] \\$@@
+\&\\*[SN] \\$*
+..
+@endCartoucheExample
+
+You can change the style of the leader that bridges each table of
+contents entry with its page number; define the @code{TC-LEADER} special
+character by using the @code{char} request.  A typical leader combines
+the dot glyph @samp{.} with a horizontal motion escape sequence to
+spread the dots.  The width of the page number field is stored in the
+@code{TC-MARGIN} register.
+
+@c ---------------------------------------------------------------------
+
+@node Differences from AT&T ms, ms Naming Conventions, ms Page Layout, ms
+@subsection Differences from @acronym{AT&T} @file{ms}
+@cindex @file{ms} macros, @code{groff} differences from @acronym{AT&T}
+@cindex @acronym{AT&T} @file{ms}, macro package differences
+
+The @code{groff} @file{ms} macros are an independent reimplementation,
+using no @acronym{AT&T} code.  Since they take advantage of the extended
+features of @code{groff}, they cannot be used with @acronym{AT&T}
+@code{troff}.  @code{groff} @file{ms} supports features described above
+as Berkeley and Tenth Edition Research Unix extensions, and adds several
+of its own.
+
+@itemize @bullet
+@item
+The internals of @code{groff} @file{ms} differ from the internals of
+@acronym{AT&T} @file{ms}.  Documents that depend upon implementation
+details of @acronym{AT&T} @file{ms} may not format properly with
+@code{groff} @file{ms}.  Such details include macros whose function was
+not documented in the @acronym{AT&T} @file{ms}
+manual.@footnote{@cite{Typing Documents on the UNIX System: Using the
+-ms Macros with Troff and Nroff}, M.@tie{}E.@: Lesk, Bell Laboratories,
+1978}
+@c XXX: We support RT anyway; maybe we should stop?
+
+@item
+The error-handling policy of @code{groff} @file{ms} is to detect and
+report errors, rather than to ignore them silently.
+
+@item
+Tenth Edition @c possibly 9th
+Research Unix supported @code{P1}/@code{P2} macros to bracket code
+examples; @code{groff} @file{ms} does not.
+
+@item
+@code{groff} @file{ms} does not work in GNU @code{troff}'s
+@acronym{AT&T} compatibility mode.  If loaded when that mode is enabled,
+it aborts processing with a diagnostic message.
+
+@item
+Multiple line spacing is not supported.  Use a larger vertical spacing
+instead.
+
+@item
+@code{groff} @file{ms} uses the same header and footer defaults in both
+@code{nroff} and @code{troff} modes as @acronym{AT&T} @file{ms} does in
+@code{troff} mode; @acronym{AT&T}'s default in @code{nroff} mode is to
+put the date, in U.S.@: traditional format (e.g., ``January 1, 2021''),
+in the center footer (the @code{CF} string).
+
+@item
+Many @code{groff} @file{ms} macros, including those for paragraphs,
+headings, and displays, cause a reset of paragraph rendering parameters,
+and may change the indentation; they do so not by incrementing or
+decrementing it, but by setting it absolutely.  This can cause problems
+for documents that define additional macros of their own that try to
+manipulate indentation.  Use the @file{ms} @code{RS} and @code{RE}
+macros instead of the @code{in} request.
+
+@item
+@cindex fractional type sizes in @file{ms} macros
+@cindex @file{ms} macros, fractional type sizes in
+@acronym{AT&T} @file{ms} interpreted the values of the registers
+@code{PS} and @code{VS} in points, and did not support the use of
+scaling units with them.  @code{groff} @file{ms} interprets values of
+the registers @code{PS}, @code{VS}, @code{FPS}, and @code{FVS} equal to
+or larger than@tie{}1,000 (one thousand) as decimal fractions multiplied
+by@tie{}1,000.@footnote{Register values are converted to and stored as
+basic units.  @xref{Measurements}.}  This threshold makes use of a
+scaling unit with these parameters practical for high-resolution
+devices while preserving backward compatibility.  It also permits
+expression of non-integral type sizes.  For example, @samp{groff
+-rPS=10.5p} at the shell prompt is equivalent to placing @samp{.nr PS
+10.5p} at the beginning of the document.
+
+@item
+@acronym{AT&T} @file{ms}'s @code{AU} macro supported arguments used with
+some document types; @code{groff} @file{ms} does not.
+
+@item
+Right-aligned displays are available.  The @acronym{AT&T} @file{ms}
+manual observes that ``it is tempting to assume that @samp{.DS R} will
+right adjust lines, but it doesn't work''.  In @code{groff} @file{ms},
+it does.
+
+@item
+To make @code{groff} @file{ms} use the default page offset (which also
+specifies the left margin), the @code{PO} register must stay undefined
+until the first @file{ms} macro is called.
+
+This implies that @samp{\n[PO]} should not be used early in the
+document, unless it is changed also: accessing an undefined register
+automatically defines it.
+
+@item
+@code{groff} @file{ms} supports the @code{PN} register, but it is not
+necessary; you can access the page number via the usual @code{%}
+register and invoke the @code{af} request to assign a different format
+to it if desired.@footnote{If you redefine the @file{ms} @code{PT} macro
+@c I wouldn't mention that, but Lesk 1978 encourages doing so.  :-/
+and desire special treatment of certain page numbers (like @samp{1}),
+you may need to handle a non-Arabic page number format, as @code{groff}
+@file{ms}'s @code{PT} does; see the macro package source.  @code{groff}
+@file{ms} aliases the @code{PN} register to @code{%}.}
+
+@item
+The @acronym{AT&T} @file{ms} manual documents registers @code{CW} and
+@code{GW} as setting the default column width and ``intercolumn gap'',
+respectively, and which applied when @code{MC} was called with fewer
+than two arguments.  @code{groff} @file{ms} instead treats @code{MC}
+without arguments as synonymous with @code{2C}; there is thus no
+occasion for a default column width register.  Further, the @code{MINGW}
+register and the second argument to @code{MC} specify a @emph{minimum}
+space between columns, not the fixed gutter width of @acronym{AT&T}
+@file{ms}.
+
+@item
+The @acronym{AT&T} @file{ms} manual did not document the @code{QI}
+register; Berkeley and @code{groff} @file{ms} do.
+@end itemize
+
+@Defmpreg {GS, ms}
+The register @code{GS} is set to@tie{}1 by the @code{groff} @file{ms}
+macros, but is not used by the @acronym{AT&T} @file{ms} package.
+Documents that need to determine whether they are being formatted with
+@code{groff} @file{ms} or another implementation should test this
+register.
+@endDefmpreg
+
+@menu
+* Missing Unix Version 7 ms Macros::
+@end menu
+
+@c ---------------------------------------------------------------------
+
+@node Missing Unix Version 7 ms Macros, , Differences from AT&T ms, Differences from AT&T ms
+@subsubsection Unix Version 7 @file{ms} macros not implemented by @code{groff} @file{ms}
+
+Several macros described in the Unix Version@tie{}7 @file{ms}
+documentation are unimplemented by @code{groff} @file{ms} because they
+are specific to the requirements of documents produced internally by
+Bell Laboratories, some of which also require a glyph for the Bell
+System logo that @code{groff} does not support.  These macros
+implemented several document type formats
+(@code{EG}, @c engineer's notes
+@code{IM}, @c internal memorandum
+@code{MF}, @c memorandum for file
+@code{MR}, @c memorandum for record
+@code{TM}, @c technical memorandum
+@code{TR}), @c technical report
+were meaningful only in conjunction with the use of certain document
+types
+(@code{AT}, @c attachments
+@code{CS}, @c cover sheet info for `TM` documents
+@code{CT}, @c copies to
+@code{OK}, @c "other keywords" for `TM` documents
+@code{SG}), @c signatures for `TM` documents
+stored the postal addresses of Bell Labs sites
+(@code{HO}, @c Holmdel
+@code{IH}, @c Naperville
+@code{MH}, @c Murray Hill
+@code{PY}, @c Piscataway
+@code{WH}), @c Whippany
+or lacked a stable definition over time
+(@code{UX}). @c Unix; on 1st use, add footnote id'ing trademark owner
+To compatibly render historical @file{ms} documents using these macros,
+we advise your documents to invoke the @code{rm} request to remove any
+such macros it uses and then define replacements with an authentically
+typeset original at hand.@footnote{The removal beforehand is necessary
+because @code{groff} @file{ms} aliases these macros to a diagnostic
+macro, and you want to redefine the aliased name, not its target.}  For
+informal purposes, a simple definition of @code{UX} should maintain the
+readability of the document's substance.
+
+@CartoucheExample
+.rm UX
+.ds UX Unix\"
+@endCartoucheExample
+
+@c ---------------------------------------------------------------------
+
+@node ms Legacy Features, ms Naming Conventions, Differences from AT&T ms, ms
+@subsection Legacy Features
+@cindex @file{ms} macros, strings
+@cindex @file{ms} macros, special characters
+@cindex @file{ms} macros, accent marks
+@cindex accent marks [@file{ms}]
+@cindex special characters [@file{ms}]
+@cindex strings [@file{ms}]
+
+@code{groff} @file{ms} retains some legacy features solely to support
+formatting of historical documents; contemporary ones should not use
+them because they can render poorly.  See the @cite{groff_char@r{(7)}}
+man page.
+
+@unnumberedsubsubsec AT&T accent mark strings
+
+AT&T @file{ms} defined accent mark strings as follows.
+
+@Defmpstr {@code{'}, ms}
+Apply acute accent to subsequent glyph.
+@endDefmpstr
+
+@Defmpstr {@code{`}, ms}
+Apply grave accent to subsequent glyph.
+@endDefmpstr
+
+@Defmpstr {:, ms}
+Apply dieresis (umlaut) to subsequent glyph.
+@endDefmpstr
+
+@Defmpstr {^, ms}
+Apply circumflex accent to subsequent glyph.
+@endDefmpstr
+
+@Defmpstr {~, ms}
+Apply tilde accent to subsequent glyph.
+@endDefmpstr
+
+@Defmpstr {C, ms}
+Apply caron to subsequent glyph.
+@endDefmpstr
+
+@Defmpstr {\,, ms}
+Apply cedilla to subsequent glyph.
+@endDefmpstr
+
+@unnumberedsubsubsec Berkeley accent mark and glyph strings
+
+Berkeley @file{ms} offered an @code{AM} macro; calling it redefined the
+AT&T accent mark strings (except for @samp{\*C}), applied them to the
+@emph{preceding} glyph, and defined additional strings, some for spacing
+glyphs.
+
+@Defmac {AM, , ms}
+Enable alternative accent mark and glyph-producing strings.
+@endDefmac
+
+@Defmpstr {@code{'}, ms}
+Apply acute accent to preceding glyph.
+@endDefmpstr
+
+@Defmpstr {@code{`}, ms}
+Apply grave accent to preceding glyph.
+@endDefmpstr
+
+@Defmpstr {:, ms}
+Apply dieresis (umlaut) to preceding glyph.
+@endDefmpstr
+
+@Defmpstr {^, ms}
+Apply circumflex accent to preceding glyph.
+@endDefmpstr
+
+@Defmpstr {~, ms}
+Apply tilde accent to preceding glyph.
+@endDefmpstr
+
+@Defmpstr {\,, ms}
+Apply cedilla to preceding glyph.
+@endDefmpstr
+
+@Defmpstr {/, ms}
+Apply stroke (slash) to preceding glyph.
+@endDefmpstr
+
+@Defmpstr {v, ms}
+Apply caron to preceding glyph.
+@endDefmpstr
+
+@Defmpstr {_, ms}
+Apply macron to preceding glyph.
+@endDefmpstr
+
+@Defmpstr {., ms}
+Apply underdot to preceding glyph.
+@endDefmpstr
+
+@Defmpstr {o, ms}
+Apply ring accent to preceding glyph.
+@endDefmpstr
+
+@Defmpstr {?, ms}
+Interpolate inverted question mark.
+@endDefmpstr
+
+@Defmpstr {!, ms}
+Interpolate inverted exclamation mark.
+@endDefmpstr
+
+@Defmpstr {8, ms}
+Interpolate small letter sharp s.
+@endDefmpstr
+
+@Defmpstr {q, ms}
+Interpolate small letter o with hook accent (ogonek).
+@endDefmpstr
+
+@Defmpstr {3, ms}
+Interpolate small letter yogh.
+@endDefmpstr
+
+@Defmpstr {d-, ms}
+Interpolate small letter eth.
+@endDefmpstr
+
+@Defmpstr {D-, ms}
+Interpolate capital letter eth.
+@endDefmpstr
+
+@Defmpstr {th, ms}
+Interpolate small letter thorn.
+@endDefmpstr
+
+@Defmpstr {Th, ms}
+Interpolate capital letter thorn.
+@endDefmpstr
+
+@Defmpstr {ae, ms}
+Interpolate small æ ligature.
+@endDefmpstr
+
+@Defmpstr {Ae, ms}
+Interpolate capital Æ ligature.
+@endDefmpstr
+
+@Defmpstr {oe, ms}
+Interpolate small oe ligature.
+@endDefmpstr
+
+@Defmpstr {OE, ms}
+Interpolate capital OE ligature.
+@endDefmpstr
+
+@c ---------------------------------------------------------------------
+
+@node ms Naming Conventions,  , ms Legacy Features, ms
+@subsection Naming Conventions
+@cindex @file{ms} macros, naming conventions
+@cindex naming conventions, @file{ms} macros
+
+The following conventions are used for names of macros, strings, and
+registers.  External names available to documents that use the
+@code{groff} @file{ms} macros contain only uppercase letters and digits.
+
+Internally, the macros are divided into modules.  Conventions for
+identifier names are as follows.
+
+@itemize @bullet
+@item
+Names used only within one module are of the form
+@var{module}@code{*}@var{name}.
+
+@item
+Names used outside the module in which they are defined are of the form
+@var{module}@code{@@}@var{name}.
+
+@item
+Names associated with a particular environment are of the form
+@var{environment}@code{:}@var{name}; these are used only within the
+@code{par} module.
+
+@item
+@var{name} does not have a module prefix.
+
+@item
+Constructed names used to implement arrays are of the form
+@var{array}@code{!}@var{index}.
+@end itemize
+
+Thus the @code{groff} @file{ms} macros reserve the following names.
+
+@itemize @bullet
+@item
+Names containing the characters @code{*}, @code{@@}, and@tie{}@code{:}.
+
+@item
+Names containing only uppercase letters and digits.
+@end itemize
+
+
+@c =====================================================================
+@c =====================================================================
+
+@node GNU troff Reference, File Formats, Major Macro Packages, Top
+@chapter GNU @code{troff} Reference
+@cindex reference, @code{gtroff}
+@cindex @code{gtroff}, reference
+
+This chapter covers @emph{all} of the facilities of the GNU
+@code{troff} formatting engine.  Users of macro packages may skip it if
+not interested in details.
+
+
+@menu
+* Text::
+* Page Geometry::
+* Measurements::
+* Numeric Expressions::
+* Identifiers::
+* Formatter Instructions::
+* Comments::
+* Registers::
+* Manipulating Filling and Adjustment::
+* Manipulating Hyphenation::
+* Manipulating Spacing::
+* Tabs and Fields::
+* Character Translations::
+* @code{troff} and @code{nroff} Modes::
+* Line Layout::
+* Line Continuation::
+* Page Layout::
+* Page Control::
+* Using Fonts::
+* Manipulating Type Size and Vertical Spacing::
+* Colors::
+* Strings::
+* Conditionals and Loops::
+* Writing Macros::
+* Page Motions::
+* Drawing Geometric Objects::
+* Deferring Output::
+* Traps::
+* Diversions::
+* Punning Names::
+* Environments::
+* Suppressing Output::
+* I/O::
+* Postprocessor Access::
+* Miscellaneous::
+* Gtroff Internals::
+* Debugging::
+* Implementation Differences::
+@end menu
+
+
+@c =====================================================================
+
+@c BEGIN Keep roughly parallel with roff(7) section "Concepts".
+@node Text, Measurements, GNU troff Reference, GNU troff Reference
+@section Text
+@cindex text, GNU @code{troff} processing
+
+@acronym{AT&T} @code{troff} was designed to take input as it would be
+composed on a typewriter, including the teletypewriters used as early
+computer terminals, and relieve the user drafting a document of concern
+with details like line length, hyphenation breaking, and the achievement
+of straight margins.  Early in its development, the program gained the
+ability to prepare output for a phototypesetter; a document could then
+be prepared for output to either a teletypewriter, a phototypesetter, or
+both.  GNU @code{troff} continues this tradition of permitting an author
+to compose a single master version of a document which can then be
+rendered for a variety of output formats or devices.
+
+@code{roff} input files contain text interspersed with instructions to
+control the formatter.  Even in the absence of such instructions, GNU
+@code{troff} still processes its input in several ways, by filling,
+hyphenating, breaking, and adjusting it, and supplementing it with
+inter-sentence space.
+
+@menu
+* Filling::
+* Hyphenation::
+* Sentences::
+* Breaking::
+* Adjustment::
+* Tabs and Leaders::
+* Requests and Macros::
+* Macro Packages::
+* Input Encodings::
+* Input Conventions::
+@end menu
+
+@c ---------------------------------------------------------------------
+
+@node Filling, Sentences, Text, Text
+@subsection Filling
+
+When GNU @code{troff} starts up, it obtains information about the device
+for which it is preparing output.@footnote{@xref{Device and Font
+Description Files}.}  An essential property is the length of the output
+line, such as ``6.5 inches''.
+
+@cindex word, definition of
+@cindex filling
+GNU @code{troff} interprets plain text files employing the Unix
+line-ending convention.  It reads input a character at a time,
+collecting words as it goes, and fits as many words together on an
+output line as it can---this is known as @dfn{filling}.  To GNU
+@code{troff}, a @dfn{word} is any sequence of one or more characters
+that aren't spaces or newlines.  The exceptions separate
+words.@footnote{@slanted{Tabs} and @slanted{leaders} also separate
+words.  @slanted{Escape sequences} can function as word characters, word
+separators, or neither---the last simply have no effect on GNU
+@code{troff}'s idea of whether an input character is within a word.
+We'll discuss all of these in due course.}  To disable filling, see
+@ref{Manipulating Filling and Adjustment}.
+
+@Example
+It is a truth universally acknowledged
+that a single man in possession of a
+good fortune must be in want of a wife.
+    @result{} It is a truth universally acknowledged that a
+    @result{} single man in possession of a good fortune must
+    @result{} be in want of a wife.
+@endExample
+
+@c ---------------------------------------------------------------------
+
+@node Sentences, Hyphenation, Filling, Text
+@subsection Sentences
+@cindex sentences
+
+A passionate debate has raged for decades among writers of the English
+language over whether more space should appear between adjacent
+sentences than between words within a sentence, and if so, how much, and
+what other circumstances should influence this spacing.@footnote{A
+well-researched jeremiad appreciated by @code{groff} contributors on
+both sides of the sentence-spacing debate can be found at
+@uref{https://web.archive.org@//web@//20171217060354@//http://www.heracliteanriver.com@//?p=324}.}
+GNU @code{troff} follows the example of @acronym{AT&T} @code{troff};
+it attempts to detect the boundaries between sentences, and supplies
+additional inter-sentence space between them.
+
+@Example
+Hello, world!
+Welcome to groff.
+    @result{} Hello, world!  Welcome to groff.
+@endExample
+
+@cindex end-of-sentence characters
+@cindex sentence space
+@cindex space between sentences
+@cindex French spacing
+GNU @code{troff} flags certain characters (normally @samp{!}, @samp{?},
+and @samp{.}) as potentially ending a sentence.  When GNU @code{troff}
+encounters one of these @dfn{end-of-sentence characters} at the end of
+an input line, or one of them is followed by two (unescaped) spaces on
+the same input line, it appends an inter-word space followed by an
+inter-sentence space in the output.
+
+@Example
+R. Harper subscribes to a maxim of P. T. Barnum.
+    @result{} R. Harper subscribes to a maxim of P. T. Barnum.
+@endExample
+
+In the above example, inter-sentence space is not added after @samp{P.}
+or @samp{T.} because the periods do not occur at the end of an input
+line, nor are they followed by two or more spaces.  Let's imagine that
+we've heard something about defamation from Mr.@: Harper's attorney,
+recast the sentence, and reflowed it in our text editor.
+
+@Example
+I submit that R. Harper subscribes to a maxim of P. T.
+Barnum.
+    @result{} I submit that R. Harper subscribes to a maxim of
+    @result{} P. T.  Barnum.
+@endExample
+
+``Barnum'' doesn't begin a sentence!  What to do?  Let us meet our first
+@dfn{escape sequence}, a series of input characters that give
+instructions to GNU @code{troff} instead of being used to construct
+output device glyphs.@footnote{This statement oversimplifies; there are
+escape sequences whose purpose is precisely to produce glyphs on the
+output device, and input characters that @emph{aren't} part of escape
+sequences can undergo a great deal of processing before getting to the
+output.} An escape sequence begins with the backslash character @code{\}
+by default, an uncommon character in natural language text, and is
+@emph{always} followed by at least one other character, hence the term
+``sequence''.
+
+@cindex @code{\&}, at end of sentence
+The dummy character escape sequence @code{\&} can be used after an
+end-of-sentence character to defeat end-of-sentence detection on a
+per-instance basis.  We can therefore rewrite our input more
+defensively.
+
+@Example
+I submit that R.\& Harper subscribes to a maxim of P.\&
+T.\& Barnum.
+    @result{} I submit that R. Harper subscribes to a maxim of
+    @result{} P. T. Barnum.
+@endExample
+
+Adding text caused our input to wrap; now, we don't need @code{\&} after
+@samp{T.} but we do after @samp{P.}.  Consistent use of the escape
+sequence ensures that potential sentence boundaries are robust to
+editing activities.  Further advice along these lines will follow in
+@ref{Input Conventions}.
+
+@cindex end-of-sentence transparent characters
+@cindex characters, end-of-sentence transparent
+@cindex @code{dg} glyph, at end of sentence
+@cindex @code{dd} glyph, at end of sentence
+@cindex @code{rq} glyph, at end of sentence
+@cindex @code{cq} glyph, at end of sentence
+@cindex @code{"}, at end of sentence
+@cindex @code{'}, at end of sentence
+@cindex @code{)}, at end of sentence
+@cindex @code{]}, at end of sentence
+@cindex @code{*}, at end of sentence
+@cindex special characters
+@cindex characters, special
+Normally, the occurrence of a visible non-end-of-sentence character (as
+opposed to a space or tab) immediately after an end-of-sentence
+character cancels detection of the end of a sentence.  For example, it
+would be incorrect for GNU @code{troff} to infer the end of a sentence
+after the dot in @samp{3.14159}.  However, several characters are
+treated @emph{transparently} after the occurrence of an end-of-sentence
+character.  That is, GNU @code{troff} does not cancel end-of-sentence
+detection when it processes them.  This is because such characters are
+often used as footnote markers or to close quotations and
+parentheticals.  The default set is @samp{"}, @samp{'}, @samp{)},
+@samp{]}, @samp{*}, @code{\[dg]}, @code{\[dd]}, @code{\[rq]}, and
+@code{\[cq]}.  The last four are examples of @dfn{special characters},
+escape sequences whose purpose is to obtain glyphs that are not easily
+typed at the keyboard, or which have special meaning to GNU @code{troff}
+(like @code{\} itself).@footnote{The mnemonics for the special
+characters shown here are ``dagger'', ``double dagger'', ``right
+(double) quote'', and ``closing (single) quote''.  See the
+@cite{groff_char@r{(7)}} man page.}
+
+@Example
+\[lq]The idea that the poor should have leisure has always
+been shocking to the rich.\[rq]
+(Bertrand Russell, 1935)
+@c XXX: @iftex puts a blank line on the output.  This seems like a bug.
+@c @newline works around it.  But we need a weird inverse indent.
+@iftex @
+  @result{} @quotedblleft{}The idea that the poor should have
+    @result{} leisure has always been shocking to
+    @result{} the rich.@quotedblright{}  (Bertrand Russell, 1935)
+@end iftex
+@ifnottex
+    @result{} "The idea that the poor should have
+    @result{} leisure has always been shocking to
+    @result{} the rich."  (Bertrand Russell, 1935)
+@end ifnottex
+@endExample
+
+The sets of characters that potentially end sentences or are transparent
+to sentence endings are configurable.  See the @code{cflags} request in
+@ref{Using Symbols}.  To change the additional inter-sentence space
+amount---even to remove it entirely---see @ref{Manipulating Filling and
+Adjustment}.
+
+@c ---------------------------------------------------------------------
+
+@node Hyphenation, Breaking, Sentences, Text
+@subsection Hyphenation
+@cindex hyphenation
+
+When an output line is nearly full, it is uncommon for the next word
+collected from the input to exactly fill it---typically, there is room
+left over only for part of the next word.  The process of splitting a
+word so that it appears partially on one line (with a hyphen to indicate
+to the reader that the word has been broken) with its remainder on the
+next is @dfn{hyphenation}.  Hyphenation points can be manually
+specified; GNU @code{troff} also uses a hyphenation algorithm and
+language-specific pattern files (based on those used in @TeX{}) to
+decide which words can be hyphenated and where.
+
+Hyphenation does not always occur even when the hyphenation rules for a
+word allow it; it can be disabled, and when not disabled there are
+several parameters that can prevent it in certain circumstances.
+@xref{Manipulating Hyphenation}.
+
+@c ---------------------------------------------------------------------
+
+@node Breaking, Adjustment, Hyphenation, Text
+@subsection Breaking
+@cindex break
+@cindex implicit line break
+@cindex line break, output
+@cindex output line break
+
+Once an output line is full, the next word (or remainder of a hyphenated
+one) is placed on a different output line; this is called a @dfn{break}.
+In this manual and in @code{roff} discussions generally, a ``break'' if
+not further qualified always refers to the termination of an output
+line.  When the formatter is filling text, it introduces breaks
+automatically to keep output lines from exceeding the configured line
+length.  After an automatic break, GNU @code{troff} adjusts the line if
+applicable (see below), and then resumes collecting and filling text on
+the next output line.
+
+Sometimes, a line cannot be broken automatically.  This usually does
+not happen with natural language text unless the output line length has
+been manipulated to be extremely short, but it can with specialized
+text like program source code.  We can use @code{perl} at the shell
+prompt to contrive an example of failure to break the line.  We also
+employ the @option{-z} option to suppress normal output.
+
+@Example
+$ perl -e 'print "#" x 80, "\n";' | nroff -z
+    @error{} warning: cannot break line
+@endExample
+
+The remedy for these cases is to tell GNU @code{troff} where the line
+may be broken without hyphens.  This is done with the non-printing break
+point escape sequence @samp{\:}; see @ref{Manipulating Hyphenation}.
+
+@cindex blank line
+@cindex empty line
+@cindex line, blank
+@cindex blank line macro (@code{blm})
+What if the document author wants to stop filling lines temporarily, for
+instance to start a new paragraph?  There are several solutions.  A
+blank input line not only causes a break, but by default it also outputs
+a one-line vertical space (effectively a blank output line).  This
+behavior can be modified; see @ref{Blank Line Traps}.  Macro packages
+may discourage or disable the blank line method of paragraphing in favor
+of their own macros.
+
+@cindex leading spaces
+@cindex spaces, leading and trailing
+@cindex trailing spaces on text lines
+@cindex leading space macro (@code{lsm})
+A line that begins with one or more spaces causes a break.  The spaces
+are output at the beginning of the next line without being
+@emph{adjusted} (see below); however, this behavior can be modified
+(@pxref{Leading Space Traps}).  Again, macro packages may provide other
+methods of producing indented paragraphs.  Trailing spaces on text lines
+are discarded.@footnote{``Text lines'' are defined in @ref{Requests and
+Macros}.}
+
+What if the file ends before enough words have been collected to fill an
+output line?  Or the output line is exactly full but not yet broken, and
+there is no more input?  GNU @code{troff} interprets the end of input as
+a break.  Certain requests also cause breaks, implicitly or explicitly.
+This is discussed in @ref{Manipulating Filling and Adjustment}.
+
+@c ---------------------------------------------------------------------
+
+@node Adjustment, Tabs and Leaders, Breaking, Text
+@subsection Adjustment
+
+@cindex extra spaces between words
+After GNU @code{troff} performs an automatic break, it may then
+@dfn{adjust} the line, widening inter-word spaces until the text reaches
+the right margin.  Extra spaces between words are preserved.  Leading
+and trailing spaces are handled as noted above.  Text can be aligned to
+the left or right margin only, or centered; see @ref{Manipulating
+Filling and Adjustment}.
+@c END Keep roughly parallel with roff(7) section "Concepts".
+
+@c ---------------------------------------------------------------------
+
+@node Tabs and Leaders, Input Conventions, Adjustment, Text
+@subsection Tabs and Leaders
+
+@cindex horizontal tab character
+@cindex tab character
+@cindex character, horizontal tab
+@cindex leader character
+@cindex character, leader
+@cindex tab stops
+@cindex stops, tab
+GNU @code{troff} translates input horizontal tab characters (``tabs'')
+and @key{Control+A} characters (``leaders'') into movements to the next
+tab stop.  Tabs simply move to the next tab stop; leaders place enough
+periods to fill the space.  Tab stops are by default located every half
+inch measured from the drawing position corresponding to the beginning
+of the input line; see @ref{Page Geometry}.   Tabs and leaders do not
+cause breaks and therefore do not interrupt filling.  Below, we use
+arrows @arrow{} and bullets @bullet{} to indicate input tabs and
+leaders, respectively.
+
+@Example
+1
+@arrow{} 2 @arrow{} 3 @bullet{} 4
+@arrow{} @bullet{} 5
+@result{} 1         2       3.......4         ........5
+@endExample
+
+Tabs and leaders lend themselves to table construction.@footnote{``Tab''
+is short for ``tabulation'', revealing the term's origin as a spacing
+mechanism for table arrangement.} The tab and leader glyphs can be
+configured, and further facilities for sophisticated table composition
+are available; see @ref{Tabs and Fields}.  There are many details to
+track when using such low-level features, so most users turn to the
+@cite{tbl@r{(1)}} preprocessor to lay out tables.
+
+@c ---------------------------------------------------------------------
+
+@node Requests and Macros, Macro Packages, Tabs and Leaders, Text
+@subsection Requests and Macros
+
+We have now encountered almost all of the syntax there is in the
+@code{roff} language, with an exception already noted in passing.
+@cindex request
+@cindex control character (@code{.})
+@cindex character, control (@code{.})
+@cindex no-break control character (@code{'})
+@cindex character, no-break control (@code{'})
+@cindex control character, no-break (@code{'})
+A @dfn{request} is an instruction to the formatter that occurs after a
+@dfn{control character}, which is recognized at the beginning of an
+input line.  The regular control character is a dot (@code{.}).  Its
+counterpart, the @dfn{no-break control character}, a neutral apostrophe
+(@code{'}), suppresses the break that is implied by some requests.
+These characters were chosen because it is uncommon for lines of text in
+natural languages to begin with them.
+@cindex dummy character (@code{\&}), as control character suppressor
+@cindex character, dummy (@code{\&}), as control character suppressor
+If you require a formatted period or apostrophe (closing single
+quotation mark) where GNU @code{troff} is expecting a control character,
+prefix the dot or neutral apostrophe with the dummy character escape
+sequence, @samp{\&}.
+
+@cindex control line
+An input line beginning with a control character is called a
+@dfn{control line}.
+@cindex text line
+Every line of input that is not a control line is a @dfn{text
+line}.@footnote{The @code{\@key{RET}} escape sequence can alter how an
+input line is classified; see @ref{Line Continuation}.}
+
+@cindex argument
+Requests often take @dfn{arguments}, words (separated from the request
+name and each other by spaces) that specify details of the action GNU
+@code{troff} is expected to perform.  If a request is meaningless
+without arguments, it is typically ignored.
+
+GNU @code{troff}'s requests and escape sequences comprise the control
+language of the formatter.  Of key importance are the requests that
+define macros.  Macros are invoked like requests, enabling the request
+repertoire to be extended or overridden.@footnote{Argument handling in
+macros is more flexible but also more complex.  @xref{Calling Macros}.}
+
+@cindex macro
+@cindex calling a macro
+@cindex interpolation
+A @dfn{macro} can be thought of as an abbreviation you can define for a
+collection of control and text lines.  When the macro is @dfn{called} by
+giving its name after a control character, it is replaced with what it
+stands for.  The process of textual replacement is known as
+@dfn{interpolation}.@footnote{Some escape sequences undergo
+interpolation as well.}  Interpolations are handled as soon as they are
+recognized, and once performed, a @code{roff} formatter scans the
+replacement for further requests, macro calls, and escape sequences.
+
+In @code{roff} systems, the @code{de} request defines a
+macro.@footnote{GNU @code{troff} offers additional ones.  @xref{Writing
+Macros}.}
+
+@Example
+.de DATE
+2020-11-14
+..
+@endExample
+
+@noindent
+The foregoing input produces no output by itself; all we have done is
+store some information.  Observe the pair of dots that ends the macro
+definition.  This is a default; you can specify your own terminator for
+the macro definition as the second argument to the @code{de} request.
+
+@Example
+.de NAME ENDNAME
+Heywood Jabuzzoff
+.ENDNAME
+@endExample
+
+In fact, the ending marker is itself the name of a macro to be
+called, or a request to be invoked, if it is defined at the time its
+control line is read.
+
+@Example
+.de END
+Big Rip
+..
+.de START END
+Big Bang
+.END
+.START
+    @result{} Big Rip Big Bang
+@endExample
+
+@noindent
+In the foregoing example, ``Big Rip'' printed before ``Big Bang''
+because its macro was @emph{called} first.  Consider what would happen
+if we dropped @code{END} from the @samp{.de START} line and added
+@code{..} after @code{.END}.  Would the order change?
+
+Let us consider a more elaborate example.
+
+@Example
+.de DATE
+2020-10-05
+..
+.
+.de BOSS
+D.\& Kruger,
+J.\& Peterman
+..
+.
+.de NOTICE
+Approved:
+.DATE
+by
+.BOSS
+..
+.
+Insert tedious regulatory compliance paragraph here.
+
+.NOTICE
+
+Insert tedious liability disclaimer paragraph here.
+
+.NOTICE
+    @result{} Insert tedious regulatory compliance paragraph here.
+    @result{}
+    @result{} Approved: 2020-10-05 by D. Kruger, J. Peterman
+    @result{}
+    @result{} Insert tedious liability disclaimer paragraph here.
+    @result{}
+    @result{} Approved: 2020-10-05 by D. Kruger, J. Peterman
+@endExample
+
+@noindent
+The above document started with a series of control lines.  Three macros
+were defined, with a @code{de} request declaring each macro's name, and
+the ``body'' of the macro starting on the next line and continuing until
+a line with two dots @samp{@code{..}} marked its end.  The text proper
+began only after the macros were defined; this is a common pattern.
+Only the @code{NOTICE} macro was called ``directly'' by the document;
+@code{DATE} and @code{BOSS} were called only by @code{NOTICE} itself.
+Escape sequences were used in @code{BOSS}, two levels of macro
+interpolation deep.
+
+The advantage in typing and maintenance economy may not be obvious from
+such a short example, but imagine a much longer document with dozens of
+such paragraphs, each requiring a notice of managerial approval.
+Consider what must happen if you are in charge of generating a new
+version of such a document with a different date, for a different boss.
+With well-chosen macros, you only have to change each datum in one
+place.
+
+In practice, we would probably use strings (@pxref{Strings}) instead of
+macros for such simple interpolations; what is important here is to
+glimpse the potential of macros and the power of recursive
+interpolation.
+
+We could have defined @code{DATE} and @code{BOSS} in the opposite order;
+perhaps less obviously, we could also have defined them @emph{after}
+@code{NOTICE}.  ``Forward references'' like this are acceptable because
+the body of a macro definition is not (completely) interpreted, but
+stored instead (@pxref{Copy Mode}).  While a macro is being defined (or
+appended to), requests are not interpreted and macros not interpolated,
+whereas some commonly used escape sequences @emph{are} interpreted.
+@code{roff} systems also support recursive macro calls, as long as you
+have a way to break the recursion (@pxref{Conditionals and Loops}).
+Maintainable @code{roff} documents tend to arrange macro definitions to
+minimize forward references.
+
+@c ---------------------------------------------------------------------
+
+@node Macro Packages, Input Encodings, Requests and Macros, Text
+@subsection Macro Packages
+@cindex macro package
+@cindex package, macro
+
+@c TODO: Consider parallelizing with groff_tmac(5) "Description".
+Macro definitions can be collected into @dfn{macro files}, @code{roff}
+input files designed to produce no output themselves but instead ease
+the preparation of other @code{roff} documents.  There is no syntactical
+difference between a macro file and any other @code{roff} document; only
+its purpose distinguishes it.  When a macro file is installed at a
+standard location and suitable for use by a general audience, it is
+often termed a @dfn{macro package}.@footnote{Macro files and packages
+frequently define registers and strings as well.}  Macro packages can be
+loaded by supplying the @option{-m} option to GNU @command{troff} or a
+@code{groff} front end.  Alternatively, a document requiring a macro
+package can load it with the @code{mso} (``macro source'') request.
+
+@c ---------------------------------------------------------------------
+
+@c TODO: Move a lot of this node to the "Invoking groff" chapter.  Some
+@c of the discussion is better placed in discussion of output drivers
+@c (e.g., what character encodings _they_ support for output and their
+@c responsibility for converting to them) as well.
+
+@node Input Encodings, Input Conventions, Macro Packages, Text
+@subsection Input Encodings
+
+The @command{groff} command's @option{-k} option calls the
+@command{preconv} preprocessor to perform input character encoding
+conversions.  Input to the GNU @code{troff} formatter itself, on the
+other hand, must be in one of two encodings it can recognize.
+
+@table @code
+@item cp1047
+@cindex encoding, input, @acronym{EBCDIC}
+@cindex @acronym{EBCDIC}, input encoding
+@cindex input encoding, @acronym{EBCDIC}
+@cindex encoding, input, code page 1047
+@cindex code page 1047, input encoding
+@cindex input encoding, code page 1047
+@cindex IBM code page 1047 input encoding
+@pindex cp1047.tmac
+The code page 1047 input encoding works only on @acronym{EBCDIC}
+platforms (and conversely, the other input encodings don't work with
+@acronym{EBCDIC}); the file @file{cp1047.tmac} is loaded at startup.
+
+@item latin1
+@cindex encoding, input, @w{Latin-1} (ISO @w{8859-1})
+@cindex @w{Latin-1} (ISO @w{8859-1}), input encoding
+@cindex ISO @w{8859-1} (@w{Latin-1}), input encoding
+@cindex input encoding, @w{Latin-1} (ISO @w{8859-1})
+@pindex latin1.tmac
+ISO @w{Latin-1}, an encoding for Western European languages, is the
+default input encoding on non-@acronym{EBCDIC} platforms; the file
+@file{latin1.tmac} is loaded at startup.
+@end table
+
+@noindent
+Any document that is encoded in ISO 646:1991 (a descendant of USAS
+@w{X3.4-1968} or ``US-ASCII''), or, equivalently, uses only code points
+from the ``C0 Controls'' and ``Basic Latin'' parts of the Unicode
+character set is also a valid ISO @w{Latin-1} document; the standards
+are interchangeable in their first 128 code points.@footnote{The
+@emph{semantics} of certain punctuation code points have gotten stricter
+with the successive standards, a cause of some frustration among man
+page writers; see the @cite{groff_char@r{(7)}} man page.}
+
+Other encodings are supported by means of macro packages.
+
+@table @code
+@item latin2
+@cindex encoding, input, @w{Latin-2} (ISO @w{8859-2})
+@cindex @w{Latin-2} (ISO @w{8859-2}), input encoding
+@cindex ISO @w{8859-2} (@w{Latin-2}), input encoding
+@cindex input encoding, @w{Latin-2} (ISO @w{8859-2})
+@pindex latin2.tmac
+To use ISO @w{Latin-2}, an encoding for Central and Eastern European
+languages, invoke @w{@samp{.mso latin2.tmac}} at the beginning of your
+document or supply @samp{-mlatin2} as a command-line argument to
+@code{groff}.
+
+@item latin5
+@cindex encoding, input, @w{Latin-5} (ISO @w{8859-9})
+@cindex @w{Latin-5} (ISO @w{8859-9}), input encoding
+@cindex ISO @w{8859-9} (@w{Latin-5}), input encoding
+@cindex input encoding, @w{Latin-5} (ISO @w{8859-9})
+@pindex latin5.tmac
+To use ISO @w{Latin-5}, an encoding for the Turkish language, invoke
+@w{@samp{.mso latin5.tmac}} at the beginning of your document or
+supply @samp{-mlatin5} as a command-line argument to @code{groff}.
+
+@item latin9
+@cindex encoding, input, @w{Latin-9} (ISO @w{8859-15})
+@cindex @w{Latin-9} (ISO @w{8859-15}), input encoding
+@cindex ISO @w{8859-15} (@w{Latin-9}), input encoding
+@cindex input encoding, @w{Latin-9} (ISO @w{8859-15})
+@pindex latin9.tmac
+ISO @w{Latin-9} succeeds @w{Latin-1}; it includes a Euro sign and better
+glyph coverage for French.  To use this encoding, invoke @w{@samp{.mso
+latin9.tmac}} at the beginning of your document or supply
+@samp{-mlatin9} as a command-line argument to @code{groff}.
+@end table
+
+Some characters from an input encoding may not be available with a
+particular output driver, or their glyphs may not have representation in
+the font used.  For terminal devices, fallbacks are defined, like
+@samp{EUR} for the Euro sign and @samp{(C)} for the copyright sign.  For
+typesetter devices, you may need to ``mount'' fonts that support glyphs
+required by the document.  @xref{Font Positions}.
+
+@pindex freeeuro.pfa
+@pindex ec.tmac
+Because a Euro glyph was not historically defined in PostScript fonts,
+@code{groff} comes with a font called @file{freeeuro.pfa} that provides
+the Euro in several styles.  Standard PostScript fonts contain the
+glyphs from @w{Latin-5} and @w{Latin-9} that @w{Latin-1} lacks, so these
+encodings are supported for the @option{ps} and @option{pdf} output
+devices as @code{groff} ships, while @w{Latin-2} is not.
+
+Unicode supports characters from all other input encodings; the
+@option{utf8} output driver for terminals therefore does as well.  The
+DVI output driver supports the @w{Latin-2} and @w{Latin-9} encodings if
+the command-line option @option{-mec} is used as well.  @footnote{The
+DVI output device defaults to using the Computer Modern (CM) fonts;
+@file{ec.tmac} loads the EC fonts instead, which provide Euro
+@samp{\[Eu]} and per mille @samp{\[%0]} glyphs.}
+
+@c ---------------------------------------------------------------------
+
+@node Input Conventions, , Input Encodings, Text
+@subsection Input Conventions
+@cindex input conventions
+@cindex conventions for input
+
+Since GNU @code{troff} fills text automatically, it is common practice
+in the @code{roff} language to avoid visual composition of text in input
+files: the esthetic appeal of the formatted output is what matters.
+Therefore, @code{roff} input should be arranged such that it is easy for
+authors and maintainers to compose and develop the document, understand
+the syntax of @code{roff} requests, macro calls, and preprocessor
+languages used, and predict the behavior of the formatter.  Several
+traditions have accrued in service of these goals.
+
+@itemize @bullet
+@item
+Follow sentence endings in the input with newlines to ease their
+recognition (@pxref{Sentences}).  It is frequently convenient to end
+text lines after colons and semicolons as well, as these typically
+precede independent clauses.  Consider doing so after commas; they often
+occur in lists that become easy to scan when itemized by line, or
+constitute supplements to the sentence that are added, deleted, or
+updated to clarify it.  Parenthetical and quoted phrases are also good
+candidates for placement on text lines by themselves.
+
+@item
+Set your text editor's line length to 72 characters or
+fewer.@footnote{Emacs: @code{fill-column: 72}; Vim: @code{textwidth=72}}
+This limit, combined with the previous item of advice, makes it less
+common that an input line will wrap in your text editor, and thus will
+help you perceive excessively long constructions in your text.  Recall
+that natural languages originate in speech, not writing, and that
+punctuation is correlated with pauses for breathing and changes in
+prosody.
+
+@item
+Use @code{\&} after @samp{!}, @samp{?}, and @samp{.} if they are
+followed by space, tab, or newline characters and don't end a sentence.
+
+@item
+In filled text lines, use @code{\&} before @samp{.} and @samp{'} if they
+are preceded by space, so that reflowing the input doesn't turn them
+into control lines.
+
+@item
+Do not use spaces to perform indentation or align columns of a table.
+Leading spaces are reliable when text is not being filled.
+
+@item
+Comment your document.  It is never too soon to apply comments to
+record information of use to future document maintainers (including your
+future self).  We thus introduce another escape sequence, @code{\"},
+which causes GNU @code{troff} to ignore the remainder of the input line.
+
+@item
+Use the empty request---a control character followed immediately by a
+newline---to visually manage separation of material in input files.
+Many of the @code{groff} project's own documents use an empty request
+between sentences, after macro definitions, and where a break is
+expected, and two empty requests between paragraphs or other requests or
+macro calls that will introduce vertical space into the document.
+
+You can combine the empty request with the comment escape sequence to
+include whole-line comments in your document, and even ``comment out''
+sections of it.
+@end itemize
+
+We conclude this section with an example sufficiently long to illustrate
+most of the above suggestions in practice.  For the purpose of fitting
+the example between the margins of this manual with the font used for
+its typeset version, we have shortened the input line length to 56
+columns.  As before, an arrow @arrow{} indicates a tab character.
+
+@c Wrap example at 56 columns (not counting @arrow{}).
+@CartoucheExample
+.\"   nroff this_file.roff | less
+.\"   groff -T ps this_file.roff > this_file.ps
+@arrow{}The theory of relativity is intimately connected with
+the theory of space and time.
+.
+I shall therefore begin with a brief investigation of
+the origin of our ideas of space and time,
+although in doing so I know that I introduce a
+controversial subject.  \" remainder of paragraph elided
+.
+.
+
+@arrow{}The experiences of an individual appear to us arranged
+in a series of events;
+in this series the single events which we remember
+appear to be ordered according to the criterion of
+\[lq]earlier\[rq] and \[lq]later\[rq], \" punct swapped
+which cannot be analysed further.
+.
+There exists,
+therefore,
+for the individual,
+an I-time,
+or subjective time.
+.
+This itself is not measurable.
+.
+I can,
+indeed,
+associate numbers with the events,
+in such a way that the greater number is associated with
+the later event than with an earlier one;
+but the nature of this association may be quite
+arbitrary.
+.
+This association I can define by means of a clock by
+comparing the order of events furnished by the clock
+with the order of a given series of events.
+.
+We understand by a clock something which provides a
+series of events which can be counted,
+and which has other properties of which we shall speak
+later.
+.\" Albert Einstein, _The Meaning of Relativity_, 1922
+@endCartoucheExample
+
+@node Page Geometry, Measurements, Text, GNU troff Reference
+@section Page Geometry
+@cindex page, geometry of
+@cindex geometry, page
+
+@code{roff} systems format text under certain assumptions about the size
+of the output medium, or page.  For the formatter to correctly break a
+line it is filling, it must know the line length, which it derives from
+the page width (@pxref{Line Layout}).  For it to decide whether to write
+an output line to the current page or wait until the next one, it must
+know the page length (@pxref{Page Layout}).
+
+@cindex device resolution
+@cindex resolution, device
+@cindex basic units
+@cindex units, basic
+@cindex machine units
+@cindex units, machine
+A device's @dfn{resolution} converts practical units like inches or
+centimeters to @dfn{basic units}, a convenient length measure for the
+output device or file format.  The formatter and output driver use basic
+units to reckon page measurements.  The device description file defines
+its resolution and page dimensions (@pxref{DESC File Format}).
+
+@cindex page
+A @dfn{page} is a two-dimensional structure upon which a @code{roff}
+system imposes a rectangular coordinate system with its upper left
+corner as the origin.  Coordinate values are in basic units and increase
+down and to the right.  Useful ones are therefore always positive and
+within numeric ranges corresponding to the page boundaries.
+
+@cindex drawing position
+@cindex position, drawing
+While the formatter (and, later, output driver) is processing a page, it
+keeps track of its @dfn{drawing position}, which is the location at
+which the next glyph will be written, from which the next motion will be
+measured, or where a geometric object will commence rendering.
+@cindex text baseline
+@cindex baseline, text
+Notionally, glyphs are drawn from the text baseline upward and to the
+right.@footnote{@code{groff} does not yet support right-to-left
+scripts.}  The @dfn{text baseline} is a (usually invisible) line upon
+which the glyphs of a typeface are aligned.  A glyph therefore
+``starts'' at its bottom-left corner.  If drawn at the origin, a typical
+letter glyph would lie partially or wholly off the page, depending on
+whether, like ``g'', it features a descender below the baseline.
+
+@cindex page offset
+@cindex offset, page
+Such a situation is nearly always undesirable.  It is furthermore
+conventional not to write or draw at the extreme edges of the page.
+Therefore the initial drawing position of a @code{roff} formatter is not
+at the origin, but below and to the right of it.  This rightward shift
+from the left edge is known as the @dfn{page
+offset}.@footnote{@code{groff}'s terminal output devices have page
+offsets of zero.}  The downward shift leaves room for a text output
+line.
+
+Text is arranged on a one-dimensional lattice of text baselines from the
+top to the bottom of the page.
+@cindex vertical spacing
+@cindex spacing, vertical
+@cindex vee
+@dfn{Vertical spacing} is the distance between adjacent text baselines.
+Typographic tradition sets this quantity to 120% of the type size.  The
+initial drawing position is one unit of vertical spacing below the page
+top.  Typographers term this unit a @slanted{vee}.
+
+@cindex page break
+@cindex break, page
+@cindex page ejection
+@cindex ejection, page
+Vertical spacing has an impact on page-breaking decisions.  Generally,
+when a break occurs, the formatter moves the drawing position to the
+next text baseline automatically.  If the formatter were already writing
+to the last line that would fit on the page, advancing by one vee would
+place the next text baseline off the page.  Rather than let that happen,
+@code{roff} formatters instruct the output driver to eject the page,
+start a new one, and again set the drawing position to one vee below the
+page top; this is a @dfn{page break}.
+
+When the last line of input text corresponds to the last output line
+that fits on the page, the break caused by the end of input will also
+break the page, producing a useless blank one.  Macro packages keep
+users from having to confront this difficulty by setting ``traps''
+(@pxref{Traps}); moreover, all but the simplest page layouts tend to
+have headers and footers, or at least bear vertical margins larger than
+one vee.
+
+
+@c =====================================================================
+@c TODO: Add a section here about interpolations and input processing.
+@c
+@c We need to level up the reader's macro brain from reasoning about
+@c interpolation at the scope of input lines to interpolations _within_
+@c lines.  It is also a good time to introduce the \n and \* escape
+@c sequences to avoid painful, "WTF"-producing forward references later.
+@c Some materal from groff_mm(7) might be adaptable to this purpose.
+@c
+@c Earlier material from @Defesc{\\n}:
+@c "This means that the value of the register is expanded in place while
+@c GNU @code{troff} is parsing the input line.  Nested assignments (also
+@c called indirect assignments) are possible."
+@c
+@c We can probably drop the term "indirect assignments"; there's nothing
+@c special about these--they are a consequence of *roffs' left-to-right
+@c parsing and they apply to escape sequences in general.
+@c =====================================================================
+
+@c BEGIN Keep (roughly) parallel with section "Measurements" of
+@c groff(7).
+@node Measurements, Numeric Expressions, Text, GNU troff Reference
+@section Measurements
+@cindex measurements
+@cindex scaling indicator
+@cindex indicator, scaling
+
+@cindex units of measurement
+@cindex measurement units
+The formatter sometimes requires the input of numeric parameters to
+specify measurements.  These are specified as integers or decimal
+fractions with an optional @dfn{scaling unit} suffixed.  A scaling unit
+is a letter that immediately follows the last digit of a number.  Digits
+after the decimal point are optional.  Measurement expressions include
+@samp{10.5p}, @samp{11i}, and @samp{3.c}.
+
+@cindex basic units, conversion to
+@cindex units, basic, conversion to
+@cindex conversion to basic units
+Measurements are scaled by the scaling unit and stored internally (with
+any fractional part discarded) in basic units.
+@cindex device resolution, obtaining in the formatter
+@cindex resolution, device, obtaining in the formatter
+The device resolution can therefore be obtained by storing a value of
+@samp{1i} to a register.  The only constraint on the basic unit is that
+it is at least as small as any other unit.
+@c That's a fib.  A device resolution of around 2^31 would surely also
+@c cause problems.  But nobody does that.
+
+@table @code
+@cindex basic scaling unit (@code{u})
+@cindex @code{u} scaling unit
+@cindex unit, scaling, @code{u}
+@cindex scaling unit @code{u}
+@item u
+Basic unit.
+
+@item i
+@cindex inch scaling unit (@code{i})
+@cindex @code{i} scaling unit
+@cindex unit, scaling, @code{i}
+@cindex scaling unit @code{i}
+Inch; defined as 2.54@tie{}centimeters.
+
+@item c
+@cindex centimeter scaling unit (@code{c})
+@cindex @code{c} scaling unit
+@cindex unit, scaling, @code{c}
+@cindex scaling unit @code{c}
+Centimeter; a centimeter is about 0.3937@tie{}inches.
+
+@item p
+@cindex point scaling unit (@code{p})
+@cindex @code{p} scaling unit
+@cindex unit, scaling, @code{p}
+@cindex scaling unit @code{p}
+Point; a typesetter's unit used for measuring type size.
+There are 72@tie{}points to an inch.
+
+@item P
+@cindex pica scaling unit (@code{P})
+@cindex @code{P} scaling unit
+@cindex unit, scaling, @code{P}
+@cindex scaling unit @code{P}
+Pica; another typesetter's unit.  There are 6@tie{}picas to an inch and
+12@tie{}points to a pica.
+
+@item s
+@itemx z
+@xref{Using Fractional Type Sizes}, for a discussion of these units.
+
+@item f
+GNU @code{troff} defines this unit to scale decimal fractions in the
+interval [0, 1] to 16-bit unsigned integers.  It multiplies a quantity
+by 65,536.  @xref{Colors}, for usage.
+@end table
+
+The magnitudes of other scaling units depend on the text formatting
+parameters in effect.  These are useful when specifying measurements
+that need to scale with the typeface or vertical spacing.
+
+@table @code
+@item m
+@cindex em scaling unit (@code{m})
+@cindex @code{m} scaling unit
+@cindex unit, scaling, @code{m}
+@cindex scaling unit @code{m}
+Em; an em is equal to the current type size in points.  It is named thus
+because it is approximately the width of the letter@tie{}@samp{M}.
+
+@item n
+@cindex en scaling unit (@code{n})
+@cindex @code{n} scaling unit
+@cindex unit, scaling, @code{n}
+@cindex scaling unit @code{n}
+En; an en is one-half em.
+
+@item v
+@cindex vertical space unit (@code{v})
+@cindex space, vertical, unit (@code{v})
+@cindex vee scaling unit (@code{v})
+@cindex @code{v} scaling unit
+@cindex unit, scaling, @code{v}
+@cindex scaling unit @code{v}
+Vee; recall @ref{Page Geometry}.
+
+@item M
+@cindex @code{M} scaling unit
+@cindex unit, scaling, @code{M}
+@cindex scaling unit @code{M}
+Hundredth of an em.
+@end table
+
+@menu
+* Motion Quanta::
+* Default Units::
+@end menu
+@c END Keep (roughly) parallel with section "Measurements" of groff(7).
+
+@c ---------------------------------------------------------------------
+
+@node Motion Quanta, Default Units, Measurements, Measurements
+@subsection Motion Quanta
+@cindex motion quanta
+@cindex quanta, motion
+
+@c BEGIN Keep (roughly) parallel with subsection "Motion quanta" of
+@c groff(7).
+An output device's basic unit @code{u} is not necessarily its smallest
+addressable length; @code{u} can be smaller to avoid problems with
+integer roundoff.  The minimum distances that a device can work with in
+the horizontal and vertical directions are termed its @dfn{motion
+quanta}.  Measurements are rounded to applicable motion quanta.
+Half-quantum fractions round toward zero.
+
+@cindex horizontal motion quantum register (@code{.H})
+@cindex motion quantum, horizontal, register (@code{.H})
+@cindex horizontal resolution register (@code{.H})
+@cindex resolution, horizontal, register (@code{.H})
+@DefregList {.H}
+@DefregListEndx {.V}
+These read-only registers interpolate the horizontal and vertical motion
+quanta, respectively, of the output device in basic units.
+@endDefreg
+
+For example, we might draw short baseline rules on a terminal device as
+follows.  @xref{Drawing Geometric Objects}.
+
+@Example
+.tm \n[.H]
+    @error{} 24
+.nf
+\l'36u' 36u
+\l'37u' 37u
+    @result{} _ 36u
+    @result{} __ 37u
+@endExample
+@c END Keep (roughly) parallel with subsection "Motion quanta" of
+@c groff(7).
+
+@c ---------------------------------------------------------------------
+
+@node Default Units,  , Motion Quanta, Measurements
+@subsection Default Units
+@cindex default units
+@cindex units, default
+
+@c BEGIN Keep (roughly) parallel with subsection "Default units" of
+@c groff(7).
+A general-purpose register (one created or updated with the @code{nr}
+request; see @pxref{Registers}) is implicitly dimensionless, or reckoned
+in basic units if interpreted in a measurement context.  But it is
+convenient for many requests and escape sequences to infer a scaling
+unit for an argument if none is specified.  An explicit scaling unit
+(not after a closing parenthesis) can override an undesirable default.
+Effectively, the default unit is suffixed to the expression if a scaling
+unit is not already present.  GNU @code{troff}'s use of integer
+arithmetic should also be kept in mind (@pxref{Numeric Expressions}).
+
+The @code{ll} request interprets its argument in ems by default.
+Consider several attempts to set a line length of 3.5@tie{}inches when
+the type size is 10@tie{}points on a terminal device with a resolution
+of 240 basic units and horizontal motion quantum of 24.  Some
+expressions become zero; the request clamps them to that quantum.
+
+@Example
+.ll 3.5i      \" 3.5i (= 840u)
+.ll 7/2       \" 7u/2u -> 3u -> 3m -> 0, clamped to 24u
+.ll (7 / 2)u  \" 7u/2u -> as above
+.ll 7/2i      \" 7u/2i -> 7u/480u -> 0 -> as above
+.ll 7i/2      \" 7i/2u -> 1680u/2m -> 1680u/24u -> 35u
+.ll 7i/2u     \" 3.5i (= 840u)
+@endExample
+
+@noindent
+@cindex measurements, specifying safely
+The safest way to specify measurements is to attach a scaling unit.  To
+multiply or divide by a dimensionless quantity, use @samp{u} as its
+scaling unit.
+@c END Keep (roughly) parallel with subsection "Default units" of
+@c groff(7).
+
+
+@c =====================================================================
+
+@c BEGIN Keep (roughly) parallel with section "Numeric expressions" of
+@c groff(7).
+@node Numeric Expressions, Identifiers, Measurements, GNU troff Reference
+@section Numeric Expressions
+@cindex numeric expressions
+@cindex expressions, numeric
+
+A @dfn{numeric expression} evaluates to an integer:@: it can be as
+simple as a literal @samp{0} or it can be a complex sequence of register
+and string interpolations interleaved with measurements and operators.
+
+GNU @code{troff} provides a set of mathematical and logical operators
+familiar to programmers---as well as some unusual ones---but supports
+only integer arithmetic.@footnote{Provision is made for interpreting and
+reporting decimal fractions in certain cases.}  The internal data type
+used for computing results is usually a 32-bit signed integer, which
+suffices to represent magnitudes within a range of ±2
+billion.@footnote{If that's not enough, see the @cite{groff_tmac@r{(5)}}
+man page for the @file{62bit.tmac} macro package.}
+
+@cindex arithmetic operators
+@cindex operators, arithmetic
+@cindex truncating division
+@cindex addition
+@cindex subtraction
+@cindex multiplication
+@cindex division, truncating
+@cindex modulus
+@opindex +
+@opindex -
+@opindex *
+@opindex /
+@opindex %
+Arithmetic infix operators perform a function on the numeric expressions
+to their left and right; they are @code{+} (addition), @code{-}
+(subtraction), @code{*} (multiplication), @code{/} (truncating
+division), and @code{%} (modulus).  @dfn{Truncating division} rounds to
+the integer nearer to zero, no matter how large the fractional portion.
+Overflow and division (or modulus) by zero are errors and abort
+evaluation of a numeric expression.
+@cindex unary arithmetic operators
+@cindex operators, unary arithmetic
+@cindex negation
+@cindex assertion (arithmetic operator)
+@opindex -
+@opindex +
+@cindex @code{if} request, and the @samp{!} operator
+@cindex @code{while} request, and the @samp{!} operator
+
+Arithmetic unary operators operate on the numeric expression to their
+right; they are @code{-} (negation) and @code{+} (assertion---for
+completeness; it does nothing).  The unary minus must often be used
+with parentheses to avoid confusion with the decrementation operator,
+discussed below.
+
+Observe the rounding behavior and effect of negative operands on the
+modulus and truncating division operators.
+
+@Example
+.nr T 199/100
+.nr U 5/2
+.nr V (-5)/2
+.nr W 5/-2
+.nr X 5%2
+.nr Y (-5)%2
+.nr Z 5%-2
+T=\n[T] U=\n[U] V=\n[V] W=\n[W] X=\n[X] Y=\n[Y] Z=\n[Z]
+    @result{} T=1 U=2 V=-2 W=-2 X=1 Y=-1 Z=1
+@endExample
+
+@noindent
+The sign of the modulus of operands of mixed signs is determined by the
+sign of the first.  Division and modulus operators satisfy the following
+property:@: given a dividend@tie{}@var{a} and a divisor@tie{}@var{b}, a
+quotient@tie{}@var{q} formed by @samp{(a / b)} and a
+remainder@tie{}@var{r} by @samp{(a % b)}, then @math{qb + r = a}.
+
+@cindex scaling operator
+@cindex operator, scaling
+@opindex ;
+GNU @code{troff}'s scaling operator, used with parentheses as
+@code{(@var{c};@var{e})}, evaluates a numeric expression@tie{}@var{e}
+using@tie{}@var{c} as the default scaling unit.  If @var{c} is omitted,
+scaling units are ignored in the evaluation of@tie{}@var{e}.  This
+operator can save typing by avoiding the attachment of scaling units to
+every operand out of caution.  Your macros can select a sensible default
+unit in case the user neglects to supply one.
+
+@Example
+.\" Indent by amount given in first argument; assume ens.
+.de Indent
+.  in (n;\\$1)
+..
+@endExample
+
+@noindent
+Without the scaling operator, the foregoing macro would, if called with
+a unitless argument, cause indentation by the @code{in} request's
+default scaling unit (ems).  The result would be twice as much
+indentation as expected.
+
+@cindex extremum operators (@code{>?}, @code{<?})
+@cindex operators, extremum (@code{>?}, @code{<?})
+@cindex maximum operator
+@cindex minimum operator
+@opindex >?
+@opindex <?
+GNU @code{troff} also provides a pair of operators to compute the
+extrema of two operands: @code{>?} (maximum) and @code{<?} (minimum).
+
+@Example
+.nr slots 5
+.nr candidates 3
+.nr salaries (\n[slots] <? \n[candidates])
+Looks like we'll end up paying \n[salaries] salaries.
+    @result{} Looks like we'll end up paying 3 salaries.
+@endExample
+
+@cindex comparison operators
+@cindex operators, comparison
+@cindex greater than (or equal to) operator
+@cindex less than (or equal to) operator
+@cindex equality operator
+@opindex <
+@opindex >
+@opindex >=
+@opindex <=
+@opindex =
+@opindex ==
+Comparison operators comprise @code{<} (less than), @code{>} (greater
+than), @code{<=} (less than or equal), @code{>=} (greater than or
+equal), and @code{=} (equal).  @code{==} is a synonym for @code{=}.
+When evaluated, a comparison is replaced with @samp{0} if it is false
+and @samp{1} if true.  In the @code{roff} language, positive values are
+true, others false.
+
+@cindex logical operators
+@cindex operators, logical
+@cindex logical ``and'' operator
+@cindex logical conjunction operator
+@cindex logical ``or'' operator
+@cindex logical disjunction operator
+@opindex &
+@ifnotinfo
+@opindex :
+@end ifnotinfo
+@ifinfo
+@opindex @r{<colon>}
+@end ifinfo
+We can operate on truth values with the logical operators @code{&}
+(logical conjunction or ``and'') and @code{:} (logical disjunction or
+``or'').  They evaluate as comparison operators do.
+
+@opindex !
+@cindex complementation, logical
+@cindex logical complementation operator
+@cindex logical not, limitation in expression
+@cindex expression, limitation of logical not in
+A logical complementation (``not'') operator, @code{!}, works only
+within @code{if}, @code{ie}, and @code{while} requests.
+@c This is worded to avoid implying that the operator doesn't apply
+@c to conditional expressions in general, albeit without mentioning them
+@c because they're out of scope.
+Furthermore, @code{!} is recognized only at the beginning of a numeric
+expression not contained by another numeric expression.  In other words,
+it must be the ``outermost'' operator.  Including it elsewhere in the
+expression produces a warning in the @samp{number} category
+(@pxref{Warnings}), and its expression evaluates false.  This
+unfortunate limitation maintains compatibility with @acronym{AT&T}
+@code{troff}.  Test a numeric expression for falsity by
+comparing it to a false value.@footnote{@xref{Conditionals and Loops}.}
+
+@Example
+.nr X 1
+.nr Y 0
+.\" This does not work as expected.
+.if (\n[X])&(!\n[Y]) .nop A: X is true, Y is false
+.
+.\" Use this construct instead.
+.if (\n[X])&(\n[Y]<=0) .nop B: X is true, Y is false
+    @error{} warning: expected numeric expression, got '!'
+    @result{} B: X is true, Y is false
+@endExample
+
+@cindex parentheses
+@cindex order of evaluation in expressions
+@cindex expression, order of evaluation
+@opindex (
+@opindex )
+The @code{roff} language has no operator precedence:@: expressions are
+evaluated strictly from left to right, in contrast to schoolhouse
+arithmetic.  Use parentheses @code{(} @code{)} to impose a desired
+precedence upon subexpressions.
+
+@Example
+.nr X 3+5*4
+.nr Y (3+5)*4
+.nr Z 3+(5*4)
+X=\n[X] Y=\n[Y] Z=\n[Z]
+    @result{} X=32 Y=32 Z=23
+@endExample
+
+@cindex @code{+}, and page motion
+@cindex @code{-}, and page motion
+@cindex motion operators
+@cindex operators, motion
+@opindex + @r{(unary)}
+@opindex - @r{(unary)}
+For many requests and escape sequences that cause motion on the page,
+the unary operators @code{+} and @code{-} work differently when leading
+a numeric expression.  They then indicate a motion relative to the
+drawing position:@: positive is down in vertical contexts, right in
+horizontal ones.
+
+@cindex @code{bp} request, using @code{+} and@tie{}@code{-} with
+@cindex @code{in} request, using @code{+} and@tie{}@code{-} with
+@cindex @code{ll} request, using @code{+} and@tie{}@code{-} with
+@cindex @code{lt} request, using @code{+} and@tie{}@code{-} with
+@cindex @code{nm} request, using @code{+} and@tie{}@code{-} with
+@cindex @code{nr} request, using @code{+} and@tie{}@code{-} with
+@cindex @code{pl} request, using @code{+} and@tie{}@code{-} with
+@cindex @code{pn} request, using @code{+} and@tie{}@code{-} with
+@cindex @code{po} request, using @code{+} and@tie{}@code{-} with
+@cindex @code{ps} request, using @code{+} and@tie{}@code{-} with
+@cindex @code{pvs} request, using @code{+} and@tie{}@code{-} with
+@cindex @code{rt} request, using @code{+} and@tie{}@code{-} with
+@cindex @code{ti} request, using @code{+} and@tie{}@code{-} with
+@cindex @code{\H}, using @code{+} and@tie{}@code{-} with
+@cindex @code{\R}, using @code{+} and@tie{}@code{-} with
+@cindex @code{\s}, using @code{+} and@tie{}@code{-} with
+@code{+} and @code{-} are also treated differently by the following
+requests and escape sequences:@: @code{bp}, @code{in}, @code{ll},
+@code{lt}, @code{nm}, @code{nr}, @code{pl}, @code{pn}, @code{po},
+@code{ps}, @code{pvs}, @code{rt}, @code{ti}, @code{\H}, @code{\R}, and
+@code{\s}.  Here, leading plus and minus signs serve as incrementation
+and decrementation operators, respectively.  To negate an expression,
+subtract it from zero or include the unary minus in parentheses with its
+argument.  @xref{Setting Registers}, for examples.
+
+@opindex |
+@cindex @code{|}, and page motion
+@cindex absolute @slanted{(sic)} position operator (@code{|})
+@cindex position, absolute @slanted{(sic)} operator (@code{|})
+@cindex boundary-relative motion operator (@code{|})
+@c "motion" and "operators" already indexed above
+A leading @code{|} operator indicates a motion relative not to the
+drawing position but to a boundary.  For horizontal motions, the
+measurement specifies a distance relative to a drawing position
+corresponding to the beginning of the @emph{input} line.  By default,
+tab stops reckon movements in this way.  Most escape sequences do not;
+@c XXX: Which ones do?
+@code{|} tells them to do so.
+
+@Example
+Mind the \h'1.2i'gap.
+.br
+Mind the \h'|1.2i'gap.
+.br
+Mind the
+\h'|1.2i'gap.
+@c 13 spaces, 4 spaces, 13 spaces
+    @result{} Mind the             gap.
+    @result{} Mind the    gap.
+    @result{} Mind the             gap.
+@endExample
+
+One use of this feature is to define macros whose scope is limited to
+the output they format.
+
+@Example
+.\" underline word $1 with trailing punctuation $2
+.de Underline
+.  nop \\$1\l'|0\[ul]'\\$2
+..
+Typographical emphasis is best used
+.Underline sparingly .
+@endExample
+
+@noindent
+In the above example, @samp{|0} specifies a negative motion from the
+current position (at the end of the argument just emitted, @code{\$1})
+to the beginning of the input line.  Thus, the @code{\l} escape sequence
+in this case draws a line from right to left.  A macro call occurs at
+the beginning of an input line;@footnote{Control structure syntax
+creates an exception to this rule, but is designed to remain useful:@:
+recalling our example, @samp{.if 1 .Underline this} would underline only
+``this'', precisely.  @xref{Conditionals and Loops}.} if the @code{|}
+operator were omitted, then the underline would be drawn at zero
+distance from the current position, producing device-dependent, and
+likely undesirable, results.  On the @samp{ps} output device, it
+underlines the period.
+
+For vertical motions, the @code{|} operator specifies a distance from
+the first text baseline on the page or in the current
+diversion,@footnote{@xref{Diversions}.}  using the current vertical
+spacing.
+
+@Example
+A
+.br
+B \Z'C'\v'|0'D
+    @result{} A D
+    @result{} B C
+@endExample
+
+In the foregoing example, we've used the @code{\Z} escape sequence
+(@pxref{Page Motions}) to restore the drawing position after formatting
+@samp{C}, then moved vertically to the first text baseline on the page.
+
+@Defesc {\\B, @code{'}, anything, @code{'}}
+@cindex numeric expression, valid
+@cindex valid numeric expression
+Interpolate@tie{}1 if @var{anything} is a valid numeric expression,
+and@tie{}0 otherwise.  The delimiter need not be a neutral apostrophe;
+see @ref{Delimiters}.
+@endDefesc
+
+You might use @code{\B} along with the @code{if} request to filter out
+invalid macro or string arguments.  @xref{Conditionals and Loops}.
+
+@Example
+.\" Indent by amount given in first argument; assume ens.
+.de Indent
+.  if \B'\\$1' .in (n;\\$1)
+..
+@endExample
+
+A register interpolated as an operand in a numeric expression must have
+an Arabic format; luckily, this is the default.  @xref{Assigning
+Register Formats}.
+
+@cindex space characters, in expressions
+@cindex expressions, and space characters
+Because spaces separate arguments to requests, spaces are not allowed in
+numeric expressions unless the (sub)expression containing them is
+surrounded by parentheses.  @xref{Invoking Requests}, and
+@ref{Conditionals and Loops}.
+
+@Example
+.nf
+.nr a 1+2 + 2+1
+\na
+    @error{} expected numeric expression, got a space
+    @result{} 3
+.nr a 1+(2 + 2)+1
+\na
+    @result{} 6
+@endExample
+
+The @code{nr} request (@pxref{Setting Registers}) expects its second and
+optional third arguments to be numeric expressions; a bare @code{+} does
+not qualify, so our first attempt got a warning.
+@c END Keep (roughly) parallel with section "Numeric expressions" of
+@c groff(7).
+
+
+@c =====================================================================
+
+@c BEGIN Keep (roughly) parallel with section "Identifiers" of groff(7).
+@node Identifiers, Formatter Instructions, Numeric Expressions, GNU troff Reference
+@section Identifiers
+@cindex identifiers
+
+An @dfn{identifier} labels a GNU @code{troff} datum such as a register,
+name (macro, string, or diversion), typeface, color, special character,
+character class, environment, or stream.  Valid identifiers consist of
+one or more ordinary characters.
+@cindex ordinary character
+@cindex character, ordinary
+An @slanted{ordinary character} is an input character that is not the
+escape character, a leader, tab, newline, or invalid as GNU @code{troff}
+input.
+
+@c XXX: We might move this discussion earlier since it is applicable to
+@c troff input in general, and include a reference to the `trin`
+@c request.
+@cindex invalid input characters
+@cindex input characters, invalid
+@cindex characters, invalid input
+@cindex Unicode
+Invalid input characters are a subset of control characters (from the
+sets ``C0 Controls'' and ``C1 Controls'' as Unicode describes them).
+When GNU @code{troff} encounters one in an identifier, it produces a
+warning in category @samp{input} (@pxref{Warnings}).  They are removed
+during interpretation: an identifier @samp{foo}, followed by an invalid
+character and then @samp{bar}, is processed as @samp{foobar}.
+
+On a machine using the ISO 646, 8859, or 10646 character encodings,
+invalid input characters are @code{0x00}, @code{0x08}, @code{0x0B},
+@code{0x0D}--@code{0x1F}, and @code{0x80}--@code{0x9F}.  On an
+@acronym{EBCDIC} host, they are @code{0x00}--@code{0x01}, @code{0x08},
+@code{0x09}, @code{0x0B}, @code{0x0D}--@code{0x14},
+@code{0x17}--@code{0x1F}, and
+@code{0x30}--@code{0x3F}.@footnote{Historically, control characters like
+ASCII STX, ETX, and BEL (@key{Control+B}, @key{Control+C}, and
+@key{Control+G}) have been observed in @code{roff} documents,
+particularly in macro packages employing them as delimiters with the
+output comparison operator to try to avoid collisions with the content
+of arbitrary user-supplied parameters (@pxref{Operators in
+Conditionals}).  We discourage this expedient; in GNU @code{troff} it is
+unnecessary (outside of compatibility mode) because delimited arguments
+are parsed at a different input level than the surrounding context.
+@xref{Implementation Differences}.}  Some of these code points are used
+by GNU @code{troff} internally, making it non-trivial to extend the
+program to accept UTF-8 or other encodings that use characters from
+these ranges.@footnote{Consider what happens when a C1 control
+@code{0x80}--@code{0x9F} is necessary as a continuation byte in a UTF-8
+sequence.}
+
+Thus, the identifiers @samp{br}, @samp{PP}, @samp{end-list},
+@samp{ref*normal-print}, @samp{|}, @samp{@@_}, and @samp{!"#$%'()*+,-./}
+are all valid.  Discretion should be exercised to prevent confusion.
+Identifiers starting with @samp{(} or @samp{[} require care.
+
+@Example
+.nr x 9
+.nr y 1
+.nr (x 2
+.nr [y 3
+.nr sum1 (\n(x + \n[y])
+    @error{} a space character is not allowed in an escape
+    @error{}   sequence parameter
+A:2+3=\n[sum1]
+.nr sum2 (\n((x + \n[[y])
+B:2+3=\n[sum2]
+.nr sum3 (\n[(x] + \n([y)
+C:2+3=\n[sum3]
+    @result{} A:2+3=1 B:2+3=5 C:2+3=5
+@endExample
+
+@cindex @code{]}, as part of an identifier
+@noindent
+An identifier with a closing bracket (@samp{]}) in its name can't be
+accessed with bracket-form escape sequences that expect an identifier as
+a parameter.  For example, @samp{\[foo]]} accesses the glyph @samp{foo},
+followed by @samp{]} in whatever the surrounding context is, whereas
+@samp{\C'foo]'} formats a glyph named @samp{foo]}.  Similarly, the
+identifier @samp{(} can't be interpolated @emph{except} with bracket
+forms.
+
+@cindex @code{refer}, and macro names starting with @code{[} or @code{]}
+@cindex @code{[}, macro names starting with, and @code{refer}
+@cindex @code{]}, macro names starting with, and @code{refer}
+@cindex macro names, starting with @code{[} or @code{]}, and @code{refer}
+If you begin a macro, string, or diversion name with either of the
+characters @samp{[} or @samp{]}, you foreclose use of the @code{grefer}
+preprocessor, which recognizes @samp{.[} and @samp{.]} as bibliographic
+reference delimiters.
+
+@Defesc {\\A, @code{'}, anything, @code{'}}
+Interpolate@tie{}1 if @var{anything} is a valid identifier, and@tie{}0
+otherwise.  The delimiter need not be a neutral apostrophe; see
+@ref{Delimiters}.  Because invalid input characters are removed (see
+above), invalid identifiers are empty or contain spaces, tabs, or
+newlines.
+
+You can employ @code{\A} to validate a macro argument before using it to
+construct another escape sequence or identifier.
+
+@Example
+.\" usage: .init-coordinate-pair name val1 val2
+.\" Create a coordinate pair where name!x=val1 and
+.\" name!y=val2.
+.de init-coordinate-pair
+.  if \A'\\$1' \@{\
+.    if \B'\\$2' .nr \\$1!x \\$2
+.    if \B'\\$3' .nr \\$1!y \\$3
+.  \@}
+..
+.init-coordinate-pair center 5 10
+The center is at (\n[center!x], \n[center!y]).
+.init-coordinate-pair "poi@arrow{}nt" trash garbage \" ignored
+.init-coordinate-pair point trash garbage \" ignored
+    @result{} The center is at (5, 10).
+@endExample
+
+@noindent
+In this example, we also validated the numeric arguments; the registers
+@samp{point!x} and @samp{point!y} remain undefined.  @xref{Numeric
+Expressions} for the @code{\B} escape sequence.
+@endDefesc
+
+@cindex undefined identifiers
+@cindex identifiers, undefined
+How GNU @code{troff} handles the interpretation of an undefined
+identifier depends on the context.  There is no way to invoke an
+undefined request; such syntax is interpreted as a macro call instead.
+If the identifier is interpreted as a string, macro, or diversion, GNU
+@code{troff} emits a warning in category @samp{mac}, defines it as
+empty, and interpolates nothing.  If the identifier is interpreted as a
+register, GNU @code{troff} emits a warning in category @samp{reg},
+initializes it to zero, and interpolates that value.  @xref{Warnings},
+@ref{Interpolating Registers}, and @ref{Strings}.  Attempting to use an
+undefined typeface, special character, color, character class,
+environment, or stream generally provokes an error diagnostic.
+
+@need 1000
+@cindex name space, common, of macros, diversions, and strings
+@cindex common name space of macros, diversions, and strings
+@cindex macros, shared name space with strings and diversions
+@cindex strings, shared name space with macros and diversions
+@cindex diversions, shared name space with macros and strings
+Identifiers for requests, macros, strings, and diversions share one name
+space; special characters and character classes another.  No other
+object types do.
+
+@Example
+.de xxx
+.  nop foo
+..
+@c . slack line for pagination management
+.di xxx
+bar
+.br
+.di
+.
+.xxx
+    @result{} bar
+@endExample
+
+@noindent
+The foregoing example shows that GNU @code{troff} reuses the identifier
+@samp{xxx}, changing it from a macro to a diversion.  No warning is
+emitted, and the previous contents of @samp{xxx} are lost.
+@c END Keep (roughly) parallel with section "Identifiers" of groff(7).
+
+
+@c =====================================================================
+
+@node Formatter Instructions, Registers, Identifiers, GNU troff Reference
+@section Formatter Instructions
+@cindex formatter instructions
+@cindex instructing the formatter
+
+To support documents that require more than filling, automatic line
+breaking and hyphenation, adjustment, and supplemental inter-sentence
+space, the @code{roff} language offers two means of embedding
+instructions to the formatter.
+
+@cindex request
+One is a @dfn{request}, which begins with a control character and takes
+up the remainder of the input line.  Requests often perform relatively
+large-scale operations such as setting the page length, breaking the
+line, or starting a new page.  They also conduct internal operations
+like defining macros.
+
+@cindex escape sequence
+@cindex sequence, escape
+The other is an @dfn{escape sequence}, which begins with the escape
+character and can be embedded anywhere in the input, even in arguments
+to requests and other escape sequences.  Escape sequences interpolate
+special characters, strings, or registers, and handle comparatively
+minor formatting tasks like sub- and superscripting.
+
+Some operations, such as font selection and type size alteration, are
+available via both requests and escape sequences.
+
+@menu
+* Control Characters::
+* Invoking Requests::
+* Calling Macros::
+* Using Escape Sequences::
+* Delimiters::
+@end menu
+
+@c ---------------------------------------------------------------------
+
+@node Control Characters, Invoking Requests, Formatter Instructions, Formatter Instructions
+@subsection Control Characters
+@cindex control characters
+@cindex configuring control characters
+@cindex changing control characters
+
+The mechanism of using @code{roff}'s control characters to invoke
+requests and call macros was introduced in @ref{Requests and Macros}.
+Control characters are recognized only at the beginning of an input
+line, or at the beginning of the branch of a control structure request;
+see @ref{Conditionals and Loops}.
+
+A few requests cause a break implicitly; use the no-break control
+character to prevent the break.  Break suppression is its sole
+behavioral distinction.  Employing the no-break control character to
+invoke requests that don't cause breaks is harmless but poor style.
+@xref{Manipulating Filling and Adjustment}.
+
+@cindex control character, changing (@code{cc})
+@cindex character, control, changing (@code{cc})
+@cindex no-break control character, changing (@code{c2})
+@cindex character, no-break control, changing (@code{c2})
+@cindex control character, no-break, changing (@code{c2})
+The control @samp{.} and no-break control @samp{'} characters can each
+be changed to any ordinary character@footnote{Recall @ref{Identifiers}.}
+with the @code{cc} and @code{c2} requests, respectively.
+
+@Defreq {cc, [@Var{o}]}
+Recognize the ordinary character@tie{}@var{o} as the control character.
+If@tie{}@var{o} is absent or invalid, the default control character
+@samp{.} is selected.  The identity of the control character is
+associated with the environment (@pxref{Environments}).
+@endDefreq
+
+@Defreq {c2, [@Var{o}]}
+Recognize the ordinary character@tie{}@var{o} as the no-break control
+character.  If@tie{}@var{o} is absent or invalid, the default no-break
+control character @samp{'} is selected.  The identity of the no-break
+control character is associated with the environment
+(@pxref{Environments}).
+@endDefreq
+
+When writing a macro, you might wish to know which control character was
+used to call it.
+
+@Defreg {.br}
+This read-only register interpolates@tie{}1 if the currently executing
+macro was called using the normal control character and@tie{}0
+otherwise.  If a macro is interpolated as a string, the @code{.br}
+register's value is inherited from the context of the string
+interpolation.  @xref{Strings}.
+
+@cindex intercepting requests
+@cindex requests, intercepting
+@cindex modifying requests
+@cindex requests, modifying
+Use this register to reliably intercept requests that imply breaks.
+
+@Example
+.als bp*orig bp
+.de bp
+.  ie \\n[.br] .bp*orig
+.  el          'bp*orig
+..
+@endExample
+
+Testing the @code{.br} register outside of a macro definition makes no
+sense.
+@endDefreg
+
+@c ---------------------------------------------------------------------
+
+@c BEGIN Keep (roughly) parallel with section "Requests" of groff(7).
+@node Invoking Requests, Calling Macros, Control Characters, Formatter Instructions
+@subsection Invoking Requests
+@cindex invoking requests
+@cindex requests, invoking
+
+A control character is optionally followed by tabs and/or spaces and
+then an identifier naming a request or macro.  The invocation of an
+unrecognized request is interpreted as a macro call.  Defining a macro
+with the same name as a request replaces the request.  Deleting a
+request name with the @code{rm} request makes it unavailable.  The
+@code{als} request can alias requests, permitting them to be wrapped or
+non-destructively replaced.  @xref{Strings}.
+
+@cindex request arguments
+@cindex arguments to requests
+@cindex tabs, and macro arguments
+@cindex macro arguments, and tabs
+@cindex arguments to macros, and tabs
+@cindex tabs, and request arguments
+@cindex request arguments, and tabs
+@cindex arguments to requests, and tabs
+There is no inherent limit on argument length or quantity.  Most
+requests take one or more arguments, and ignore any they do not expect.
+A request may be separated from its arguments by tabs or spaces, but
+only spaces can separate an argument from its successor.  Only one
+between arguments is necessary; any excess is ignored.  GNU @code{troff}
+does not allow tabs for argument separation.@footnote{In compatibility
+mode, a space is not necessary after a request or macro name of two
+characters' length.  Also, Plan@tie{}9 @code{troff} allows tabs to
+separate arguments.}
+
+Generally, a space @emph{within} a request argument is not relevant, not
+meaningful, or is supported by bespoke provisions, as with the @code{tl}
+request's delimiters (@pxref{Page Layout}).  Some requests, like
+@code{ds}, interpret the remainder of the control line as a single
+argument.  @xref{Strings}.
+
+@need 1000
+@cindex structuring source code of documents or macro packages
+@cindex documents, structuring the source of
+@cindex macro package, structuring the source of
+@cindex package, package, structuring the source of
+@cindex indentation, of @code{roff} source code
+Spaces and tabs immediately after a control character are ignored.
+Commonly, authors structure the source of documents or macro files with
+them.
+
+@Example
+.de center
+.  if \\n[.br] \
+.    br
+.  ce \\$1
+..
+.
+.
+.de right-align
+.@arrow{}if \\n[.br] \
+.@arrow{}@arrow{}br
+.@arrow{}rj \\$1
+..
+@endExample
+
+@cindex blank line trap (@code{blm})
+@cindex blank line macro (@code{blm})
+If you assign an empty blank line trap, you can separate macro
+definitions (or any input lines) with blank lines.
+
+@Example
+.de do-nothing
+..
+.blm do-nothing  \" activate blank line trap
+
+.de center
+.  if \\n[.br] \
+.    br
+.  ce \\$1
+..
+
+
+.de right-align
+.@arrow{}if \\n[.br] \
+.@arrow{}@arrow{}br
+.@arrow{}rj \\$1
+..
+
+.blm             \" deactivate blank line trap
+@endExample
+
+@xref{Blank Line Traps}.
+@c END Keep (roughly) parallel with section "Requests" of groff(7).
+
+@c ---------------------------------------------------------------------
+
+@need 1000
+@node Calling Macros, Using Escape Sequences, Invoking Requests, Formatter Instructions
+@subsection Calling Macros
+@cindex calling macros
+@cindex macro arguments
+@cindex arguments to macros
+
+If a macro of the desired name does not exist when called, it is
+created, assigned an empty definition, and a warning in category
+@samp{mac} is emitted.  Calling an undefined macro @emph{does} end a
+macro definition naming it as its end macro (@pxref{Writing Macros}).
+
+@cindex spaces, in a macro argument
+To embed spaces @emph{within} a macro argument, enclose the argument in
+neutral double quotes @code{"}.  Horizontal motion escape sequences are
+sometimes a better choice for arguments to be formatted as text.
+
+Consider calls to a hypothetical section heading macro @samp{uh}.
+
+@Example
+.uh The Mouse Problem
+.uh "The Mouse Problem"
+.uh The\~Mouse\~Problem
+.uh The\ Mouse\ Problem
+@endExample
+
+@cindex @code{\~}, difference from @code{\@key{SP}}
+@cindex @code{\@key{SP}}, difference from @code{\~}
+@noindent
+The first line calls @code{uh} with three arguments: @samp{The},
+@samp{Mouse}, and @samp{Problem}.  The remainder call the @code{uh}
+macro with one argument, @samp{The Mouse Problem}.  The last solution,
+using escaped spaces, can be found in documents prepared for
+@acronym{AT&T} @code{troff}.  It can cause surprise when text is
+adjusted, because @code{\@key{SP}} inserts a @emph{fixed-width},
+non-breaking space.  GNU @code{troff}'s @code{\~} escape sequence
+inserts an adjustable, non-breaking space.@footnote{@code{\~} is fairly
+portable; see @ref{Other Differences}.}
+
+@cindex @code{"}, embedding in a macro argument
+@cindex double quote, embedding in a macro argument
+@cindex @code{\}, embedding in a macro argument
+@cindex backslash, embedding in a macro argument
+The foregoing raises the question of how to embed neutral double quotes
+or backslashes in macro arguments when @emph{those} characters are
+desired as literals.  In GNU @code{troff}, the special character escape
+sequence @code{\[rs]} produces a backslash and @code{\[dq]} a neutral
+double quote.
+
+In GNU @code{troff}'s @acronym{AT&T} compatibility mode, these
+characters remain available as @code{\(rs} and @code{\(dq},
+respectively.  @acronym{AT&T} @code{troff} did not consistently define
+these special characters,
+@c It seems that AT&T troff never recognized \(rs, though DWB 3.3
+@c defined \(bs as an alias of "\" on its "Latin1" device, in
+@c deliberate(?) collision with the Bell System logo identifier.  It
+@c also defined \(dq for several devices (pcl, Latin1, nroff, ...) along
+@c with \(aq.
+but its descendants can be made to support them.  @xref{Device and Font
+Description Files}.
+
+If even that is not feasible, options remain.  To obtain a literal
+escape character in a macro argument, you can simply type it if you
+change or disable the escape character first.  @xref{Using Escape
+Sequences}.  Otherwise, you must escape the escape character repeatedly
+to a context-dependent extent.  @xref{Copy Mode}.
+
+For the (neutral) double quote, you have recourse to an obscure
+syntactical feature of @acronym{AT&T} @code{troff}.  Because a double
+quote can begin a macro argument, the formatter keeps track of whether
+the current argument was started thus, and doesn't require a space after
+the double quote that ends it.@footnote{Strictly, you can neglect to
+close the last quoted macro argument, relying on the end of the control
+line to do so.   We consider this lethargic practice poor style.}  In
+the argument list to a macro, a double quote that @emph{isn't} preceded
+by a space @emph{doesn't} start a macro argument.  If not preceded by a
+double quote that began an argument, this double quote becomes part of
+the argument.  Furthermore, within a quoted argument, a pair of adjacent
+double quotes becomes a literal double quote.
+
+@Example
+.de eq
+.  tm arg1:\\$1 arg2:\\$2 arg3:\\$3
+.  tm arg4:\\$4 arg5:\\$5 arg6:\\$6
+.. \" 4 backslashes on the next line
+.eq a" "b c" "de"f\\\\g" h""i "j""k"
+    @error{} arg1:a" arg2:b c arg3:de
+    @error{} arg4:f\g" arg5:h""i arg6:j"k
+@endExample
+
+Apart from the complexity of the rules, this traditional solution has
+the disadvantage that double quotes don't survive repeated argument
+expansion in @acronym{AT&T} @code{troff} or GNU @code{troff}'s
+compatibility mode.  This can frustrate efforts to pass such arguments
+intact through multiple macro calls.
+
+@Example
+.cp 1
+.de eq
+.  tm arg1:\\$1 arg2:\\$2 arg3:\\$3
+.  tm arg4:\\$4 arg5:\\$5 arg6:\\$6
+..
+.de xe
+.  eq \\$1 \\$2 \\$3 \\$4 \\$5 \\$6
+.. \" 8 backslashes on the next line
+.xe a" "b c" "de"f\\\\\\\\g" h""i "j""k"
+    @error{} arg1:a" arg2:b arg3:c
+    @error{} arg4:de arg5:f\g" arg6:h""i
+@endExample
+
+@cindex input level
+@cindex level, input
+@cindex interpolation depth
+@cindex depth, interpolation
+Outside of compatibility mode, GNU @code{troff} doesn't exhibit this
+problem because it tracks the nesting depth of interpolations.
+@xref{Implementation Differences}.
+
+@c ---------------------------------------------------------------------
+
+@c BEGIN Keep (roughly) parallel with section "Using escape sequences"
+@c of groff(7).
+@node Using Escape Sequences, Delimiters, Calling Macros, Formatter Instructions
+@subsection Using Escape Sequences
+@cindex using escape sequences
+@cindex escape sequences
+
+Whereas requests must occur on control lines, escape sequences can occur
+intermixed with text and may appear in arguments to requests, macros,
+and other escape sequences.
+@esindex \
+An escape sequence is introduced by the escape character, a backslash
+@code{\} (but see the @code{ec} request below).  The next character
+selects the escape's function.
+
+Escape sequences vary in length.  Some take an argument, and of those,
+some have different syntactical forms for a one-character,
+two-character, or arbitrary-length argument.  Others accept @emph{only}
+an arbitrary-length argument.  In the former scheme, a one-character
+argument follows the function character immediately, an opening
+parenthesis @samp{(} introduces a two-character argument (no closing
+parenthesis is used), and an argument of arbitrary length is enclosed in
+brackets @samp{[]}.  In the latter scheme, the user selects a delimiter
+character.  A few escape sequences are idiosyncratic, and support both
+of the foregoing conventions (@code{\s}), designate their own
+termination sequence (@code{\?}), consume input until the next newline
+(@code{\!}, @code{\"}, @code{\#}), or support an additional modifier
+character (@code{\s} again, and @code{\n}).  As with requests, use of
+some escape sequences in source documents may interact poorly with a
+macro package you use; consult its documentation to learn of ``safe''
+sequences or alternative facilities it provides to achieve the desired
+result.
+
+If an escape character is followed by a character that does not
+identify a defined operation, the escape character is ignored (producing
+a diagnostic of the @samp{escape} warning category, which is not enabled
+by default) and the following character is processed normally.
+
+@Example
+$ groff -Tps -ww
+.nr N 12
+.ds co white
+.ds animal elephant
+I have \fI\nN \*(co \*[animal]s,\f[]
+said \P.\&\~Pseudo Pachyderm.
+    @error{} warning: escape character ignored before 'P'
+    @result{} I have @slanted{12 white elephants,} said P. Pseudo Pachyderm.
+@endExample
+
+Escape sequence interpolation is of higher precedence than escape
+sequence argument interpretation.  This rule affords flexibility in
+using escape sequences to construct parameters to other escape
+sequences.
+@c END Keep (roughly) parallel with section "Escape sequences" of
+@c groff(7).
+
+@Example
+.ds family C\" Courier
+.ds style I\" oblique
+Choice a typeface \f(\*[family]\*[style]wisely.
+    @result{} Choose a typeface @slanted{wisely.}
+@endExample
+
+@noindent
+In the above, the syntax form @samp{\f(} accepts only two characters for
+an argument; the example works because the subsequent escape sequences
+are interpolated before the selection escape sequence argument is
+processed, and strings @code{family} and @code{style} interpolate one
+character each.@footnote{The omission of spaces before the comment
+escape sequences is necessary; see @ref{Strings}.}
+
+@c @need 1000
+The escape character is nearly always interpreted when encountered; it
+is therefore desirable to have a way to interpolate it, disable it, or
+change it.
+
+@cindex formatting the escape character (@code{\e})
+@cindex escape character, formatting (@code{\e})
+@Defesc {\\e, , , }
+Interpolate the escape character.
+@endDefesc
+
+@cindex formatting a backslash glyph (@code{\[rs]})
+@cindex backslash glyph, formatting (@code{\[rs]})
+The @code{\[rs]} special character escape sequence formats a backslash
+glyph.  In macro and string definitions, the input sequences @code{\\}
+and @code{\E} defer interpretation of escape sequences.  @xref{Copy
+Mode}.
+
+@Defreq {eo, }
+@cindex disabling @code{\} (@code{eo})
+@cindex @code{\}, disabling (@code{eo})
+Disable the escape mechanism except in copy mode.  Once this request is
+invoked, no input character is recognized as starting an escape
+sequence in interpretation mode.
+@endDefreq
+
+@Defreq {ec, [@Var{o}]}
+@cindex escape character, changing (@code{ec})
+@cindex character, escape, changing (@code{ec})
+Recognize the ordinary character@tie{}@var{o} as the escape character.
+If@tie{}@var{o} is absent or invalid, the default escape character
+@samp{\} is selected.
+@endDefreq
+
+Switching escape sequence interpretation off to define a macro and back
+on afterward can obviate the need to double the escape character within
+the definition.  @xref{Writing Macros}.  This technique is not available
+if your macro needs to interpolate values at the time it is
+@emph{defined}---but many do not.
+
+@Example
+.\" simplified `BR` macro from the man(7) macro package
+.eo
+.de BR
+.  ds result \&
+.  while (\n[.$] >= 2) \@{\
+.    as result \fB\$1\fR\$2\"
+.    shift 2
+.  \@}
+.  if \n[.$] .as result \fB\$1\"
+\*[result]
+.  rm result
+.  ft R
+..
+.ec
+@endExample
+
+@DefreqList {ecs, }
+@DefreqListEndx {ecr, }
+The @code{ecs} request stores the escape character for recall with
+@code{ecr}.  @code{ecr} sets the escape character to @samp{\} if none
+has been saved.
+
+Use these requests together to temporarily change the escape character.
+@endDefreq
+
+Using a different escape character, or disabling it, when calling macros
+not under your control will likely cause errors, since GNU @code{troff}
+has no mechanism to ``intern'' macros---that is, to convert a macro
+definition into a form independent of its
+representation.@footnote{@TeX{} does have such a mechanism.}  When a
+macro is called, its contents are interpreted literally.
+@c XXX: all that stuff mapped into the C0 and C1 controls seems pretty
+@c close to an interning mechanism to me, though... --GBR
+
+@c XXX: Motivation?  Why are we directing the reader to these?
+@c @xref{Diversions}, and @ref{Identifiers}.
+
+@c BEGIN Keep (roughly) parallel with subsection "Delimiters" of
+@c groff(7).
+@node Delimiters, , Using Escape Sequences, Formatter Instructions
+@subsection Delimiters
+@cindex delimiting escape sequence arguments
+@cindex escape sequence argument delimiters
+@cindex delimiters, for escape sequence arguments
+@cindex arguments, to escape sequences, delimiting
+
+@cindex @code{'}, as delimiter
+@cindex @code{"}, as delimiter
+Some escape sequences that require parameters use delimiters.  The
+neutral apostrophe @code{'} is a popular choice and shown in this
+document.  The neutral double quote @code{"} is also commonly seen.
+Letters, numerals, and leaders can be used.  Punctuation characters
+are likely better choices, except for those defined as infix operators
+in numeric expressions; see below.
+
+@Example
+\l'1.5i\[bu]' \" draw 1.5 inches of bullet glyphs
+@endExample
+
+@cindex @code{\%}, as delimiter
+@cindex @code{\@key{SP}}, as delimiter
+@cindex @code{\|}, as delimiter
+@cindex @code{\^}, as delimiter
+@cindex @code{\@{}, as delimiter
+@cindex @code{\@}}, as delimiter
+@cindex @code{\'}, as delimiter
+@cindex @code{\`}, as delimiter
+@cindex @code{\-}, as delimiter
+@cindex @code{\_}, as delimiter
+@cindex @code{\!}, as delimiter
+@cindex @code{\?}, as delimiter
+@cindex @code{\)}, as delimiter
+@cindex @code{\/}, as delimiter
+@cindex @code{\,}, as delimiter
+@cindex @code{\&}, as delimiter
+@cindex @code{\:}, as delimiter
+@cindex @code{\~}, as delimiter
+@cindex @code{\0}, as delimiter
+@cindex @code{\a}, as delimiter
+@cindex @code{\c}, as delimiter
+@cindex @code{\d}, as delimiter
+@cindex @code{\e}, as delimiter
+@cindex @code{\E}, as delimiter
+@cindex @code{\p}, as delimiter
+@cindex @code{\r}, as delimiter
+@cindex @code{\t}, as delimiter
+@cindex @code{\u}, as delimiter
+The following escape sequences don't take arguments and thus are allowed
+as delimiters:
+@code{\@key{SP}}, @code{\%}, @code{\|}, @code{\^}, @code{\@{},
+@code{\@}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
+@code{\?}, @code{\)}, @code{\/}, @code{\,}, @code{\&}, @code{\:},
+@code{\~}, @code{\0}, @code{\a}, @code{\c}, @code{\d}, @code{\e},
+@code{\E}, @code{\p}, @code{\r}, @code{\t}, and @code{\u}.  However,
+using them this way is discouraged; they can make the input confusing to
+read.
+
+@cindex @code{\A}, delimiters allowed by
+@cindex @code{\b}, delimiters allowed by
+@cindex @code{\o}, delimiters allowed by
+@cindex @code{\w}, delimiters allowed by
+@cindex @code{\X}, delimiters allowed by
+@cindex @code{\Z}, delimiters allowed by
+@cindex newline, as delimiter
+A few escape sequences,
+@code{\A},
+@code{\b},
+@code{\o},
+@code{\w},
+@code{\X},
+and @code{\Z}, accept a newline as a delimiter.  Newlines that serve
+as delimiters continue to be recognized as input line terminators.
+
+@Example
+A caf\o
+e\(aa
+in Paris
+    @result{} A café in Paris
+@endExample
+
+@noindent
+Use of newlines as delimiters in escape sequences is also discouraged.
+
+@cindex @code{\D}, delimiters allowed by
+@cindex @code{\h}, delimiters allowed by
+@cindex @code{\H}, delimiters allowed by
+@cindex @code{\l}, delimiters allowed by
+@cindex @code{\L}, delimiters allowed by
+@cindex @code{\N}, delimiters allowed by
+@cindex @code{\R}, delimiters allowed by
+@cindex @code{\s}, delimiters allowed by
+@cindex @code{\S}, delimiters allowed by
+@cindex @code{\v}, delimiters allowed by
+@cindex @code{\x}, delimiters allowed by
+Finally, the escape sequences @code{\D}, @code{\h}, @code{\H},
+@code{\l}, @code{\L}, @code{\N}, @code{\R}, @code{\s}, @code{\S},
+@code{\v}, and @code{\x} prohibit many delimiters.
+
+@itemize @bullet
+@item
+@cindex numerals, as delimiters
+@cindex digits, as delimiters
+@cindex @code{.}, as delimiter
+@cindex decimal point, as delimiter
+@cindex dot, as delimiter
+the numerals @code{0}-@code{9} and the decimal point @code{.}
+
+@item
+@cindex operators, as delimiters
+@cindex @code{+}, as delimiter
+@cindex @code{-}, as delimiter
+@cindex @code{/}, as delimiter
+@cindex @code{*}, as delimiter
+@cindex @code{%}, as delimiter
+@cindex @code{<}, as delimiter
+@cindex @code{>}, as delimiter
+@cindex @code{=}, as delimiter
+@cindex @code{&}, as delimiter
+@ifnotinfo
+@cindex @code{:}, as delimiter
+@end ifnotinfo
+@ifinfo
+@cindex <colon>, as delimiter
+@end ifinfo
+@cindex @code{(}, as delimiter
+@cindex @code{)}, as delimiter
+the (single-character) operators @samp{+-/*%<>=&:()}
+
+@item
+@cindex space character, as delimiter
+@cindex tab character, as delimiter
+the space and tab characters
+
+@item
+@cindex @code{\%}, as delimiter
+@cindex @code{\:}, as delimiter
+@cindex @code{\@{}, as delimiter
+@cindex @code{\@}}, as delimiter
+@cindex @code{\'}, as delimiter
+@cindex @code{\`}, as delimiter
+@cindex @code{\-}, as delimiter
+@cindex @code{\_}, as delimiter
+@cindex @code{\!}, as delimiter
+@cindex @code{\/}, as delimiter
+@cindex @code{\c}, as delimiter
+@cindex @code{\e}, as delimiter
+@cindex @code{\p}, as delimiter
+any escape sequences other than @code{\%}, @code{\:}, @code{\@{},
+@code{\@}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
+@code{\/}, @code{\c}, @code{\e}, and @code{\p}
+@end itemize
+
+Delimiter syntax is complex and flexible primarily for historical
+reasons; the foregoing restrictions need be kept in mind mainly when
+using @code{groff} in @acronym{AT&T} compatibility mode.  GNU
+@code{troff} keeps track of the nesting depth of escape sequence
+interpolations, so the only characters you need to avoid using as
+delimiters are those that appear in the arguments you input, not any
+that result from interpolation. Typically, @code{'} works fine.
+@xref{Implementation Differences}.
+
+@Example
+$ groff -Tps
+.de Mw
+.  nr wd \w'\\$1'
+.  tm "\\$1" is \\n(wd units wide.
+..
+.Mw Wet'suwet'en
+.Mw Wet+200i
+.cp 1 \" turn on compatibility mode
+.Mw Wet'suwet'en
+.Mw Wet'
+.Mw Wet+200i
+    @error{} "Wet'suwet'en" is 54740 units wide.
+    @error{} "Wet'+200i" is 42610 units wide.
+    @error{} "Wet'suwet'en" is 15860 units wide.
+    @error{} "Wet'" is 15860 units wide.
+    @error{} "Wet'+200i" is 14415860 units wide.
+@endExample
+
+We see here that in compatibility mode, the part of the argument after
+the @code{'} delimiter escapes from its context and, if nefariously
+crafted, influences the computation of the @var{wd} register's value in
+a surprising way.
+@c END Keep (roughly) parallel with subsection " Delimiters" of
+@c groff(7).
+
+@node Comments, Registers, Formatter Instructions, GNU troff Reference
+@section Comments
+@cindex comments
+
+One of the most common forms of escape sequence is the
+comment.@footnote{This claim may be more aspirational than descriptive.}
+
+@Defesc {\\", , , }
+Start a comment.  Everything up to the next newline is ignored.
+
+This may sound simple, but it can be tricky to keep the comments from
+interfering with the appearance of the output.
+@cindex @code{ds}, @code{ds1} requests, and comments
+@cindex @code{as}, @code{as1} requests, and comments
+If the escape sequence is to the right of some text or a request, that
+portion of the line is ignored, but spaces preceding it are processed
+normally by GNU @code{troff}.  This affects only the @code{ds} and
+@code{as} requests and their variants.
+
+@cindex tabs, before comments
+@cindex comments, lining up with tabs
+One possibly irritating idiosyncrasy is that tabs should not be used to
+vertically align comments in the source document.  Tab characters are
+not treated as separators between a request name and its first argument,
+nor between arguments.
+
+@cindex undefined request
+@cindex request, undefined
+A comment on a line by itself is treated as a blank line, because after
+eliminating the comment, that is all that remains.
+
+@Example
+Test
+\" comment
+Test
+    @result{} Test
+    @result{}
+    @result{} Test
+@endExample
+
+To avoid this, it is common to combine the empty request with the
+comment escape sequence as @samp{.\"}, causing the input line to be
+ignored.
+
+@cindex @code{'}, as a comment
+Another commenting scheme sometimes seen is three consecutive single
+quotes (@code{'''}) at the beginning of a line.  This works, but GNU
+@code{troff} emits a warning diagnostic (if enabled) about an undefined
+macro (namely @samp{''}).
+@endDefesc
+
+@Defesc {\\#, , , }
+Start a comment; everything up to and including the next newline is
+ignored.  This @code{groff} extension was introduced to avoid the
+problems described above.
+
+@Example
+Test
+\# comment
+Test
+    @result{} Test Test
+@endExample
+@endDefesc
+
+@Defreq {ig, [@Var{end}]}
+Ignore input until, in the current conditional block (if
+any),@footnote{@xref{Conditional Blocks}.} the macro @var{end} is called
+at the start of a control line, or the control line @samp{..} is
+encountered if @var{end} is not specified.  @code{ig} is parsed as if it
+were a macro definition, but its contents are discarded, not
+stored.@footnote{Exception: auto-incrementing registers defined outside
+the ignored region @emph{will} be modified if interpolated with
+@code{\n±} inside it.  @xref{Auto-increment}.}
+
+@c Wrap example at 56 columns.
+@Example
+hand\c
+.de TX
+fasting
+..
+.ig TX
+This is part of a large block of input that has been
+temporarily(?) commented out.
+We can restore it simply by removing the .ig request and
+the call of its end macro.
+.TX
+@endExample
+@Example
+    @result{} handfasting
+@endExample
+@endDefreq
+
+
+@c =====================================================================
+
+@c BEGIN Keep (roughly) parallel with subsection "Registers" of
+@c groff(7).
+@node Registers, Manipulating Filling and Adjustment, Formatter Instructions, GNU troff Reference
+@section Registers
+@cindex registers
+
+In the @code{roff} language, numbers can be stored in @dfn{registers}.
+Many built-in registers exist, supplying anything from the date to
+details of formatting parameters.  You can also define your own.
+@xref{Identifiers}, for information on constructing a valid name for a
+register.
+
+@menu
+* Setting Registers::
+* Interpolating Registers::
+* Auto-increment::
+* Assigning Register Formats::
+* Built-in Registers::
+@end menu
+
+@c ---------------------------------------------------------------------
+
+@node Setting Registers, Interpolating Registers, Registers, Registers
+@subsection Setting Registers
+@cindex setting registers (@code{nr}, @code{\R})
+@cindex registers, setting (@code{nr}, @code{\R})
+
+Define registers and update their values with the @code{nr} request or
+the @code{\R} escape sequence.
+
+@DefreqList {nr, ident value}
+@DefescListEndx {\\R, @code{'}, ident value, @code{'}}
+Set register @var{ident} to @var{value}.  If @var{ident} doesn't exist,
+GNU @code{troff} creates it.  In the @code{\R} escape sequence, the
+delimiter need not be a neutral apostrophe; see @ref{Delimiters}.  It
+also does not produce an input token in GNU @code{troff}.  @xref{Gtroff
+Internals}.
+
+@Example
+.nr a (((17 + (3 * 4))) % 4)
+\n[a]
+.\R'a (((17 + (3 * 4))) % 4)'
+\n[a]
+    @result{} 1 1
+@endExample
+
+(Later, we will discuss additional forms of @code{nr} and @code{\R} that
+can change a register's value after it is dereferenced but before it is
+interpolated.  @xref{Auto-increment}.)
+
+The complete transparency of @code{\R} can cause surprising effects if
+you use registers like @code{.k}, which get evaluated at the time they
+are accessed.
+
+@Example
+.ll 1.6i
+.
+aaa bbb ccc ddd eee fff ggg hhh\R':k \n[.k]'
+.tm :k == \n[:k]
+    @result{} :k == 126950
+.
+.br
+.
+aaa bbb ccc ddd eee fff ggg hhh\h'0'\R':k \n[.k]'
+.tm :k == \n[:k]
+    @result{} :k == 15000
+@endExample
+
+If you process this with the PostScript device (@code{-Tps}), there will
+be a line break eventually after @code{ggg} in both input lines.
+However, after processing the space after @code{ggg}, the partially
+collected line is not overfull yet, so GNU @code{troff} continues to
+collect input until it sees the space (or in this case, the newline)
+after @code{hhh}.  At this point, the line is longer than the line
+length, and the line gets broken.
+
+In the first input line, since the @code{\R} escape sequence leaves no
+traces, the check for the overfull line hasn't been done yet at the
+point where @code{\R} gets handled, and you get a value for the
+@code{.k} register that is even greater than the current line length.
+
+In the second input line, the insertion of @code{\h'0'} to cause a
+zero-width motion forces GNU @code{troff} to check the line length,
+which in turn causes the start of a new output line.  Now @code{.k}
+returns the expected value.
+@endDefreq
+
+@code{nr} and @code{\R} each have two additional special forms to
+increment or decrement a register.
+
+@DefreqList {nr, ident @t{+}@Var{value}}
+@DefreqItem {nr, ident @t{-}@Var{value}}
+@DefescItemx {\\R, @code{'}, ident @t{+}value, @code{'}}
+@DefescListEnd {\\R, @code{'}, ident @t{-}value, @code{'}}
+Increment (decrement) register @var{ident} by @var{value}.  In the
+@code{\R} escape sequence, the delimiter need not be a neutral
+apostrophe; see @ref{Delimiters}.
+
+@Example
+.nr a 1
+.nr a +1
+\na
+    @result{} 2
+@endExample
+
+@cindex negating register values
+A leading minus sign in @var{value} is always interpreted as a
+decrementation operator, not an algebraic sign.  To assign a register a
+negative value or the negated value of another register, you can
+force GNU @code{troff} to interpret @samp{-} as a negation or minus,
+rather than decrementation, operator: enclose it with its operand in
+parentheses or subtract it from zero.
+
+@Example
+.nr a 7
+.nr b 3
+.nr a -\nb
+\na
+    @result{} 4
+.nr a (-\nb)
+\na
+    @result{} -3
+.nr a 0-\nb
+\na
+    @result{} -3
+@endExample
+
+If a register's prior value does not exist (the register was undefined),
+an increment or decrement is applied as if to@tie{}0.
+@endDefreq
+
+@Defreq {rr, ident}
+@cindex removing a register (@code{rr})
+@cindex register, removing (@code{rr})
+Remove register @var{ident}.  If @var{ident} doesn't exist, the request
+is ignored.  Technically, only the name is removed; the register's
+contents are still accessible under aliases created with @code{aln}, if
+any.
+@endDefreq
+
+@Defreq {rnn, ident1 ident2}
+@cindex renaming a register (@code{rnn})
+@cindex register, renaming (@code{rnn})
+Rename register @var{ident1} to @var{ident2}.  If @var{ident1} doesn't
+exist, the request is ignored.  Renaming a built-in register does not
+otherwise alter its properties.
+@endDefreq
+
+@Defreq {aln, new old}
+@cindex alias, register, creating (@code{aln})
+@cindex creating alias for register (@code{aln})
+@cindex register, creating alias for (@code{aln})
+Create an alias @var{new} for an existing register @var{old}, causing
+the names to refer to the same stored object.  If @var{old} is
+undefined, a warning in category @samp{reg} is produced and the request
+is ignored.  @xref{Warnings}, for information about the enablement and
+suppression of warnings.
+
+@cindex alias, register, removing (@code{rr})
+@cindex removing alias for register (@code{rr})
+@cindex register, removing alias for (@code{rr})
+To remove a register alias, invoke @code{rr} on its name.  A register's
+contents do not become inaccessible until it has no more names.
+@endDefreq
+@c END Keep (roughly) parallel with subsection "Registers" of groff(7).
+
+@c ---------------------------------------------------------------------
+
+@node Interpolating Registers, Auto-increment, Setting Registers, Registers
+@subsection Interpolating Registers
+@cindex interpolating registers (@code{\n})
+@cindex registers, interpolating (@code{\n})
+
+Register contents are interpolated with the @code{\n} escape sequence.
+
+@DefescList {\\n, , i, }
+@DefescItem {\\n, (, id, }
+@DefescListEnd {\\n, [, ident, ]}
+@cindex nested assignments
+@cindex assignments, nested
+@cindex indirect assignments
+@cindex assignments, indirect
+Interpolate register with name @var{ident} (one-character
+name@tie{}@var{i}, two-character name @var{id}).  @code{\n} is
+interpreted even in copy mode (@pxref{Copy Mode}).  If the register is
+undefined, it is created and assigned a value of@tie{}@samp{0}, that
+value is interpolated, and a warning in category @samp{reg} is emitted.
+@xref{Warnings}, for information about the enablement and suppression of
+warnings.
+
+@Example
+.nr a 5
+.nr as \na+\na
+\n(as
+    @result{} 10
+@endExample
+
+@Example
+.nr a1 5
+.nr ab 6
+.ds str b
+.ds num 1
+\n[a\n[num]]
+    @result{} 5
+\n[a\*[str]]
+    @result{} 6
+@endExample
+@endDefesc
+
+@c ---------------------------------------------------------------------
+
+@node Auto-increment, Assigning Register Formats, Interpolating Registers, Registers
+@subsection Auto-increment
+@cindex auto-incrementation of a register
+@cindex incrementation, automatic, of a register
+@cindex decrementation, automatic, of a register
+
+Registers can also be incremented or decremented by a configured amount
+at the time they are interpolated.  The value of the increment is
+specified with a third argument to the @code{nr} request, and a special
+interpolation syntax is used to alter and then retrieve the register's
+value.  Together, these features are called
+@dfn{auto-increment}.@footnote{A negative auto-increment can be
+considered an ``auto-decrement''.}
+
+@Defreq {nr, ident value incr}
+@cindex @code{\R}, difference from @code{nr}
+Set register @var{ident} to @var{value} and its auto-incrementation
+amount to to @var{incr}.  The @code{\R} escape sequence doesn't support
+an @var{incr} argument.
+@endDefreq
+
+Auto-incrementation is not @emph{completely} automatic; the @code{\n}
+escape sequence in its basic form never alters the value of a register.
+To apply auto-incrementation to a register, interpolate it with
+@samp{\n±}.
+
+@DefescList {\\n, +, i, }
+@DefescItem {\\n, -, i, }
+@DefescItem {\\n, +(, id, }
+@DefescItem {\\n, -(, id, }
+@DefescItem {\\n, +[, ident, ]}
+@DefescListEnd {\\n, -[, ident, ]}
+Increment or decrement @var{ident} (one-character
+name@tie{}@var{i}, two-character name @var{id}) by the register's
+auto-incrementation value and then interpolate the new register value.
+If @var{ident} has no auto-incrementation value, interpolate as with
+@code{\n}.
+@endDefesc
+
+@need 1000
+@Example
+.nr a 0 1
+.nr xx 0 5
+.nr foo 0 -2
+\n+a, \n+a, \n+a, \n+a, \n+a
+.br
+\n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx
+.br
+\n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo]
+    @result{} 1, 2, 3, 4, 5
+    @result{} -5, -10, -15, -20, -25
+    @result{} -2, -4, -6, -8, -10
+@endExample
+
+@cindex increment value without changing the register
+@cindex value, incrementing without changing the register
+To change the increment value without changing the value of a register,
+assign the register's value to itself by interpolating it, and specify
+the desired increment normally.  Apply an increment of @samp{0} to
+disable auto-incrementation of the register.
+
+@c ---------------------------------------------------------------------
+
+@node Assigning Register Formats, Built-in Registers, Auto-increment, Registers
+@subsection Assigning Register Formats
+@cindex assign number format to register (@code{af})
+@cindex number formats, assigning to register (@code{af})
+@cindex register, assigning number format to (@code{af})
+
+A writable register's value can be interpolated in several number
+formats.  By default, conventional Arabic numerals are used.
+Other formats see use in sectioning and outlining schemes and
+alternative page numbering arrangements.
+
+@Defreq {af, reg fmt}
+Use number format @var{fmt} when interpolating register @var{reg}.
+Valid number formats are as follows.
+
+@table @code
+@item 0@r{@dots{}}
+Arabic numerals 0, 1, 2, and so on.
+Any decimal digit is equivalent to @samp{0}; the formatter merely counts
+the digits specified.  Multiple Arabic numerals in @var{fmt} cause
+interpolations to be zero-padded on the left if necessary to at least as
+many digits as specified (interpolations never truncate a register
+value).  A register with format @samp{00} interpolates values 1, 2, 3 as
+@samp{01}, @samp{02}, @samp{03}.  The default format for all writable
+registers is @samp{0}.
+
+@item I
+@cindex Roman numerals
+@cindex numerals, Roman
+Uppercase Roman numerals: 0, I, II, III, IV,@tie{}@enddots{}
+
+@item i
+Lowercase Roman numerals: 0, i, ii, iii, iv,@tie{}@enddots{}
+
+@item A
+Uppercase letters: 0, A, B, C, @dots{},@tie{}Z, AA, AB,@tie{}@enddots{}
+
+@item a
+Lowercase letters: 0, a, b, c, @dots{},@tie{}z, aa, ab,@tie{}@enddots{}
+@end table
+
+Omitting @var{fmt} causes a warning in category @samp{missing}.
+@xref{Warnings}, for information about the enablement and suppression of
+warnings.  Specifying an unrecognized format is an error.
+
+Zero values are interpolated as @samp{0} in non-Arabic formats.
+Negative quantities are prefixed with @samp{-} irrespective of format.
+In Arabic formats, the sign supplements the field width.  If @var{reg}
+doesn't exist, it is created with a zero value.
+
+@Example
+.nr a 10
+.af a 0           \" the default format
+\na,
+.af a I
+\na,
+.af a 321
+.nr a (-\na)
+\na,
+.af a a
+\na
+    @result{} 10, X, -010, -j
+@endExample
+
+@cindex Roman numerals, extrema (maximum and minimum)
+@cindex extreme values representable with Roman numerals
+@cindex maximum value representable with Roman numerals
+@cindex minimum value representable with Roman numerals
+The representable extrema in the @samp{i} and @samp{I} formats
+correspond to Arabic ±39,999.  GNU @code{troff} uses @samp{w} and
+@samp{z} to represent 5,000 and 10,000 in Roman numerals, respectively,
+following the convention of @acronym{AT&T} @code{troff}---currently, the
+correct glyphs for Roman numerals five thousand (@code{U+2181}) and ten
+thousand (@code{U+2182}) are not used.
+
+@cindex read-only register, changing format
+@cindex changing format, and read-only registers
+Assigning the format of a read-only register is an error.  Instead, copy
+the read-only register's value to, and assign the format of, a writable
+register.
+@endDefreq
+
+@DefescList {\\g, , r, }
+@DefescItem {\\g, (, rg, }
+@DefescListEnd {\\g, [, reg, ]}
+@cindex format of register (@code{\g})
+@cindex register, format (@code{\g})
+Interpolate the format of the register @var{reg} (one-character
+name@tie{}@var{r}, two-character name @var{rg}).  Zeroes represent
+Arabic formats.  If @var{reg} is not defined, @var{reg} is not created
+and nothing is interpolated.  @code{\g} is interpreted even in copy mode
+(@pxref{Copy Mode}).
+@endDefesc
+
+@cindex register format, in expressions
+@cindex expressions, and register format
+GNU @code{troff} interprets only Arabic numerals.  The Roman numeral or
+alphabetic formats cannot be used as operands to arithmetic operators in
+expressions (@pxref{Numeric Expressions}).  For instance, it may be
+desirable to test the page number independently of its format.
+
+@Example
+.af % i \" front matter
+.de header-trap
+.  \" To test the page number, we need it in Arabic.
+.  ds saved-page-number-format \\g%\"
+.  af % 0
+.  nr page-number-in-decimal \\n%
+.  af % \\*[saved-page-number-format]
+.  ie \\n[page-number-in-decimal]=1 .do-first-page-stuff
+.  el \@{\
+.    ie o .do-odd-numbered-page-stuff
+.    el   .do-even-numbered-page-stuff
+.  \@}
+.  rm saved-page-number-format
+..
+.wh 0 header-trap
+@endExample
+
+@c ---------------------------------------------------------------------
+
+@node Built-in Registers,  , Assigning Register Formats, Registers
+@subsection Built-in Registers
+@cindex built-in registers
+@cindex registers, built-in
+
+Predefined registers whose identifiers start with a dot are read-only.
+Many are Boolean-valued, interpolating a true or false value testable
+with the @code{if}, @code{ie}, or @code{while} requests.  Some read-only
+registers are string-valued, meaning that they interpolate text.
+
+@cindex removing a built-in register
+@cindex register, built-in, removing
+@cindex built-in register, removing
+@strong{Caution:@:} Built-in registers are subject to removal like
+others; once removed, they can be recreated only as normal writable
+registers and will not reflect formatter state.
+
+A register name (without the dot) is often associated with a request of
+the same name.  A complete listing of all built-in registers can be
+found in @ref{Register Index}.
+
+We present here a few built-in registers that are not described
+elsewhere in this manual; they have to do with invariant properties of
+GNU @code{troff}, or obtain information about the formatter's
+command-line options, processing progress, or the operating environment.
+
+@table @code
+@item \n[.A]
+@vindex .A
+@cindex approximation output register (@code{.A})
+@cindex plain text approximation output register (@code{.A})
+Approximate output is being formatted (Boolean-valued); see
+@command{groff} @option{-a} option (@ref{Groff Options}).
+
+@item \n[.c]
+@vindex .c
+@itemx \n[c.]
+@vindex c.
+@cindex input line number register (@code{.c}, @code{c.})
+@cindex line number, input, register (@code{.c}, @code{c.})
+Input line number.  @samp{c.} is a writable synonym,
+@c introduced in AT&T device-independent troff (CSTR #54, 1981-01)
+affecting subsequent interpolations of both @samp{.c} and @samp{c.}.
+
+@item \n[.F]
+@cindex current input file name register (@code{.F})
+@cindex input file name, current, register (@code{.F})
+@vindex .F
+Name of input file (string-valued).
+
+@item \n[.g]
+@vindex .g
+@cindex GNU @code{troff}, identification register (@code{.g})
+@cindex GNU-specific register (@code{.g})
+Always true in GNU @code{troff} (Boolean-valued).  Documents can use
+this to ask the formatter if it claims @code{groff} compatibility.
+
+@item \n[.P]
+@vindex .P
+Output page selection status (Boolean-valued); see @command{groff}
+@option{-o} option (@ref{Groff Options}).
+
+@item \n[.R]
+@cindex number of registers register (@code{.R})
+@cindex registers, number of, register (@code{.R})
+@vindex .R
+Count of available unused registers; always 10,000 in GNU
+@code{troff}.@footnote{GNU @code{troff} dynamically allocates memory for
+as many registers as required.}
+
+@item \n[.T]
+@vindex .T
+Indicator of output device selection (Boolean-valued); see
+@command{groff} @option{-T} option (@ref{Groff Options}).
+
+@item \n[.U]
+@cindex safer mode
+@cindex mode, safer
+@cindex unsafe mode
+@cindex mode, unsafe
+@vindex .U
+Unsafe mode enablement status (Boolean-valued); see @command{groff}
+@option{-U} option (@ref{Groff Options}).
+
+@item \n[.x]
+@vindex .x
+@cindex major version number register (@code{.x})
+@cindex version number, major, register (@code{.x})
+Major version number of the running GNU @code{troff} formatter.  For
+example, if the version number is 1.23.0, then @code{.x}
+contains@tie{}@samp{1}.
+
+@item \n[.y]
+@vindex .y
+@cindex minor version number register (@code{.y})
+@cindex version number, minor, register (@code{.y})
+Minor version number of the running GNU @code{troff} formatter.  For
+example, if the version number is 1.23.0, then @code{.y}
+contains@tie{}@samp{23}.
+
+@item \n[.Y]
+@vindex .Y
+@cindex revision number register (@code{.Y})
+Revision number of the running GNU @code{troff} formatter.  For example,
+if the version number is 1.23.0, then @code{.Y} contains@tie{}@samp{0}.
+
+@item \n[$$]
+@vindex $$
+@cindex process ID of GNU @code{troff} register (@code{$$})
+@cindex PID of GNU @code{troff} register (@code{$$})
+@cindex GNU @code{troff}, process ID register (@code{$$})
+@cindex GNU @code{troff}, PID register (@code{$$})
+Process identifier (PID) of the GNU @code{troff} program in its
+operating environment.
+@end table
+
+Date- and time-related registers are set per the local time as
+determined by @cite{localtime@r{(3)}} when the formatter launches.  This
+initialization can be overridden by @env{SOURCE_DATE_EPOCH} and
+@env{TZ}; see @ref{Environment}.
+
+@table @code
+@item \n[seconds]
+@cindex seconds, current time (@code{seconds})
+@cindex time, current, seconds (@code{seconds})
+@cindex current time, seconds (@code{seconds})
+@vindex seconds
+Count of seconds elapsed in the minute (0--60). @c not 59; see POSIX
+
+@item \n[minutes]
+@cindex minutes, current time (@code{minutes})
+@cindex time, current, minutes (@code{minutes})
+@cindex current time, minutes (@code{minutes})
+@vindex minutes
+Count of minutes elapsed in the hour (0--59).
+
+@item \n[hours]
+@cindex hours, current time (@code{hours})
+@cindex time, current, hours (@code{hours})
+@cindex current time, hours (@code{hours})
+@vindex hours
+Count of hours elapsed since midnight (0--23).
+
+@item \n[dw]
+@cindex day of the week register (@code{dw})
+@cindex date, day of the week register (@code{dw})
+@vindex dw
+Day of the week (1--7; 1 is Sunday).
+
+@item \n[dy]
+@cindex day of the month register (@code{dy})
+@cindex date, day of the month register (@code{dy})
+@vindex dy
+Day of the month (1--31).
+
+@item \n[mo]
+@cindex month of the year register (@code{mo})
+@cindex date, month of the year register (@code{mo})
+@vindex mo
+Month of the year (1--12).
+
+@item \n[year]
+@cindex date, year register (@code{year}, @code{yr})
+@cindex year, current, register (@code{year}, @code{yr})
+@vindex year
+Gregorian year.
+
+@cindex CSTR@tie{}#54 errata
+@cindex CSTR@tie{}#54 erratum, @code{yr} register
+@item \n[yr]
+@vindex yr
+Gregorian year minus@tie{}1900.  This register is incorrectly documented
+in the @acronym{AT&T} @code{troff} manual as storing the last two digits
+of the current year.  That claim stopped being true in 2000.  Old
+@code{troff} input that looks like:
+
+@Example
+'\" The year number is a surprise after 1999.
+This document was formatted in 19\n(yr.
+@endExample
+
+@noindent
+can be corrected to:
+
+@Example
+This document was formatted in \n[year].
+@endExample
+
+@noindent
+or, for portability across many @code{roff} programs, to the following.
+
+@Example
+.nr y4 1900+\n(yr
+This document was formatted in \n(y4.
+@endExample
+@end table
+
+
+@c =====================================================================
+
+@node Manipulating Filling and Adjustment, Manipulating Hyphenation, Registers, GNU troff Reference
+@section Manipulating Filling and Adjustment
+@cindex manipulating filling and adjustment
+@cindex filling and adjustment, manipulating
+@cindex adjustment and filling, manipulating
+@cindex justifying text
+@cindex text, justifying
+
+@cindex break
+@cindex line break
+@cindex @code{bp} request, causing implicit break
+@cindex @code{ce} request, causing implicit break
+@cindex @code{cf} request, causing implicit break
+@cindex @code{fi} request, causing implicit break
+@cindex @code{fl} request, causing implicit break
+@cindex @code{in} request, causing implicit break
+@cindex @code{nf} request, causing implicit break
+@cindex @code{rj} request, causing implicit break
+@cindex @code{sp} request, causing implicit break
+@cindex @code{ti} request, causing implicit break
+@cindex @code{trf} request, causing implicit break
+When an output line is pending (see below), a break moves the drawing
+position to the beginning of the next text baseline, interrupting
+filling.  Various ways of causing breaks were shown in @ref{Breaking}.
+The @code{br} request likewise causes a break.  Several other requests
+imply breaks:@: @code{bp}, @code{ce}, @code{cf}, @code{fi}, @code{fl},
+@code{in}, @code{nf}, @code{rj}, @code{sp}, @code{ti}, and @code{trf}.
+If the no-break control character is used with any of these requests,
+GNU @code{troff} suppresses the break; instead the requested operation
+takes effect at the next break.  @samp{'br} does nothing.
+
+@Example
+.ll 55n
+This line is normally filled and adjusted.
+.br
+A line's alignment is decided
+'ce \" Center the next input line (no break).
+when it is output.
+This line returns to normal filling and adjustment.
+    @result{} This line is normally filled and adjusted.
+    @result{}    A line's alignment is decided when it is output.
+    @result{} This line returns to normal filling and adjustment.
+@endExample
+
+@noindent
+@cindex pending output line
+@cindex partially collected line
+@cindex output line properties
+@cindex properties of output lines
+Output line properties like page offset, indentation, adjustment, and
+even the location of its text baseline, are not determined until the
+line has been broken.  An output line is said to be @dfn{pending} if
+some input has been collected but an output line corresponding to it has
+not yet been written; such an output line is also termed @dfn{partially
+collected}.  If no output line is pending, it is as if a break has
+already happened; additional breaks, whether explicit or implicit, have
+no effect.  If the vertical drawing position is negative---as it is when
+the formatter starts up---a break starts a new page (even if no output
+line is pending) unless an end-of-input macro is being interpreted.
+@xref{End-of-input Traps}.
+
+@Defreq {br, }
+Break the line: emit any pending output line without adjustment.
+
+@Example
+foo bar
+.br
+baz
+'br
+qux
+    @result{} foo bar
+    @result{} baz qux
+@endExample
+@endDefreq
+
+Sometimes you want to prevent a break within a phrase or between a
+quantity and its units.
+
+@Defesc {\\~, , , }
+@cindex unbreakable space (@code{\~})
+@cindex space, unbreakable (@code{\~})
+Insert an unbreakable space that is adjustable like an ordinary space.
+It is discarded from the end of an output line if a break is forced.
+
+@Example
+Set the output speed to\~1.
+There are 1,024\~bytes in 1\~KiB.
+J.\~F.\~Ossanna wrote the original CSTR\~#54.
+@endExample
+@endDefesc
+
+By default, GNU @code{troff} fills text and adjusts it to reach the
+output line length.  The @code{nf} request disables filling; the
+@code{fi} request reënables it.
+
+@DefreqList {fi, }
+@DefregListEndx {.u}
+@cindex filling of output, enabling (@code{fi})
+@cindex output, filling, enablement of (@code{fi})
+@cindex fill mode (@code{fi}), enabling
+@cindex mode, fill (@code{fi}), enabling
+Enable filling of output lines; a pending output line is broken.  The
+read-only register @code{.u} is set to@tie{}1.  The filling enablement
+status, sometimes called @dfn{fill mode}, is associated with the
+environment (@pxref{Environments}).  @xref{Line Continuation}, for
+interaction with the @code{\c} escape sequence.
+@endDefreq
+
+@Defreq {nf, }
+@cindex filling of output, disabling (@code{nf})
+@cindex output, filling, disablement of (@code{nf})
+@cindex no-fill mode
+@cindex mode, no-fill
+@cindex fill mode, disabling
+@cindex mode, fill, disabling
+Disable filling of output lines: the output line length (@pxref{Line
+Layout}) is ignored and output lines are broken where the input lines
+are.  A pending output line is broken and adjustment is suppressed.  The
+read-only register @code{.u} is set to@tie{}0.  The filling enablement
+status is associated with the environment (@pxref{Environments}).  See
+@ref{Line Continuation}, for interaction with the @code{\c} escape
+sequence.
+@endDefreq
+
+@DefreqList {ad, [@Var{mode}]}
+@DefregListEndx {.j}
+Enable output line adjustment in @var{mode}, taking effect when the
+pending (or next) output line is broken.  Adjustment is suppressed when
+filling is.  @var{mode} can have one of the following values.
+
+@table @code
+@item b
+@itemx n
+Adjust ``normally'':@: if the output line does not consume the distance
+between the indentation and the configured output line length, GNU
+@code{troff} stretches adjustable spaces within the line until that
+length is reached.  When the indentation is zero, this mode spreads the
+line to both the left and right margins.  This is the GNU @code{troff}
+default.
+
+@item c
+@cindex centered text (filled)
+Center filled text.  Contrast with the @code{ce} request, which centers
+text @emph{without} filling it.
+
+@item l
+@cindex ragged-right text
+Align text to the left without adjusting it.
+
+@item r
+@cindex ragged-left text
+Align text to the right without adjusting it.
+@end table
+
+@var{mode} can also be a value previously stored in the @code{.j}
+register.  Using @code{ad} without an argument is the same as @samp{.ad
+\n[.j]}; unless filling is disabled, GNU @code{troff} resumes adjusting
+lines in the same way it did before adjustment was disabled by
+invocation of the @code{na} request.
+
+@cindex adjustment mode register (@code{.j})
+The adjustment mode and enablement status are encoded in the read-only
+register @code{.j}.  These parameters are associated with the
+environment (@pxref{Environments}).
+
+The value of @code{.j} for any adjustment mode is an implementation
+detail and should not be relied upon as a programmer's interface.  Do
+not write logic to interpret or perform arithmetic on it.
+
+@Example
+.ll 48n
+.de AD
+.  br
+.  ad \\$1
+..
+@c . @c XXX: Restore this line when the page has room for it.
+.de NA
+.  br
+.  na
+..
+@c . @c XXX: Restore this line when the page has room for it.
+left
+.AD r
+.nr ad \n(.j
+right
+.AD c
+center
+.NA
+left
+.AD
+center
+.AD \n(ad
+right
+@endExample
+@Example
+    @result{} left
+    @result{}                                            right
+    @result{}                      center
+    @result{} left
+    @result{}                      center
+    @result{}                                            right
+@endExample
+@endDefreq
+
+@Defreq {na, }
+Disable output line adjustment.  This produces the same output as
+left-alignment, but the value of the adjustment mode register @code{.j}
+is altered differently.  The adjustment mode and enablement status are
+associated with the environment (@pxref{Environments}).
+@endDefreq
+
+@DefreqList {brp, }
+@DefescListEndx {\\p, , , }
+Break, adjusting the line per the current adjustment mode.  @code{\p}
+schedules a break with adjustment at the next word boundary.  The escape
+sequence is itself neither a break nor a space of any kind; it can thus
+be placed in the middle of a word to cause a break at the end of that
+word.
+
+Breaking with immediate adjustment can produce ugly results since GNU
+@code{troff} doesn't have a sophisticated paragraph-building algorithm,
+as @TeX{} has, for example.  Instead, GNU @code{troff} fills and adjusts
+a paragraph line by line.
+
+@Example
+.ll 4.5i
+This is an uninteresting sentence.
+This is an uninteresting sentence.\p
+This is an uninteresting sentence.
+@endExample
+
+@noindent
+is formatted as follows.
+
+@Example
+This  is  an uninteresting sentence.  This is
+an          uninteresting           sentence.
+This is an uninteresting sentence.
+@endExample
+@endDefreq
+
+@cindex productive input line
+@cindex input line, productive
+@cindex line, productive input
+To clearly present the next couple of requests, we must introduce the
+concept of ``productive'' input lines.  A @dfn{productive input line} is
+one that directly produces formatted output.  Text lines produce
+output,@footnote{unless diverted; see @ref{Diversions}} as do control
+lines containing requests like @code{tl} or escape sequences like
+@code{\D}.  Macro calls are not @emph{directly} productive, and thus not
+counted, but their interpolated contents can be.  Empty requests, and
+requests and escape sequences that define registers or strings or alter
+the formatting environment (as with changes to the size, face, height,
+slant, or color of the type) are not productive.  We will also preview
+the output line continuation escape sequence, @code{\c}, which
+``connects'' two input lines that would otherwise be counted separately.
+@footnote{@xref{Line Continuation}.}
+
+@Example
+@c .ll 56n
+.de hello
+Hello, world!
+..
+.ce \" center output of next productive input line
+.
+.nr junk-reg 1
+.ft I
+Chorus: \c
+.ft
+.hello
+Went the day well?
+  @result{}                  @slanted{Chorus:} Hello, world!
+  @result{} Went the day well?
+@endExample
+
+@DefreqList {ce, [@Var{n}]}
+@DefregListEndx {.ce}
+@cindex centered text (unfilled)
+@cindex centering lines (@code{ce})
+@cindex lines, centering (@code{ce})
+Break (unless the no-break control character is used), center the output
+of the next @var{n} productive input lines with respect to the line
+length and indentation without filling, then break again regardless of
+the invoking control character.
+@c Temporary indentation is ignored.
+If the argument is not positive, centering is disabled.  Omitting the
+argument implies an @var{n} of @samp{1}.  The count of lines remaining
+to be centered is stored in the read-only register @code{.ce} and is
+associated with the environment (@pxref{Environments}).
+
+@cindex @code{ce} request, difference from @w{@samp{.ad c}}
+While the @w{@samp{.ad c}} request also centers text, it fills the text
+as well.
+
+@c Wrap example at 56 columns.
+@Example
+.de FR
+This is a small text fragment that shows the differences
+between the `.ce' and the `.ad c' requests.
+..
+.ll 4i
+.ce 1000
+.FR
+.ce 0
+
+.ad c
+.FR
+    @result{} This is a small text fragment that shows
+    @result{}              the differences
+    @result{} between the @quoteleft{}.ce@quoteright{} and the @quoteleft{}.ad c@quoteright{} requests.
+    @result{}
+    @result{} This is a small text fragment that shows
+    @result{}  the differences between the @quoteleft{}.ce@quoteright{} and
+    @result{}         the @quoteleft{}.ad c@quoteright{} requests.
+@endExample
+
+The previous example illustrates a common idiom of turning centering on
+for a quantity of lines far in excess of what is required, and off again
+after the text to be centered.  This technique relieves humans of
+counting lines for requests that take a count of input lines as an
+argument.
+@endDefreq
+
+@DefreqList {rj, [@Var{n}]}
+@DefregListEndx {.rj}
+@cindex justifying text (@code{rj})
+@cindex text, justifying (@code{rj})
+@cindex right-justifying (@code{rj})
+Break (unless the no-break control character is used), align the output
+of the next @var{n} productive input lines to the right margin without
+filling, then break again regardless of the control character.
+@c Temporary indentation is ignored.
+If the argument is not positive, right-alignment is disabled.  Omitting
+the argument implies an @var{n} of @samp{1}.  The count of lines
+remaining to be right-aligned is stored in the read-only register
+@code{.rj} and is associated with the environment
+(@pxref{Environments}).
+
+@Example
+.ll 49n
+.rj 3
+At first I hoped that such a technically unsound
+project would collapse but I soon realized it was
+doomed to success. \[em] C. A. R. Hoare
+    @result{}  At first I hoped that such a technically unsound
+    @result{} project would collapse but I soon realized it was
+    @result{}              doomed to success. -- C. A. R. Hoare
+@endExample
+@endDefreq
+
+@need 2000
+@DefreqList {ss, word-space-size [@Var{additional-sentence-space-size}]}
+@DefregItemx {.ss}
+@DefregListEndx {.sss}
+@cindex word space size register (@code{.ss})
+@cindex size of word space register (@code{.ss})
+@cindex space between words register (@code{.ss})
+@cindex inter-sentence space size register (@code{.sss})
+@cindex sentence space size register (@code{.sss})
+@cindex size of sentence space register (@code{.sss})
+@cindex space between sentences register (@code{.sss})
+Set the sizes of spaces between words and
+sentences@footnote{Recall @ref{Filling} and @ref{Sentences} for the
+definitions of word and sentence boundaries, respectively.} in twelfths
+of font's space width (typically one-fourth to one-third em for Western
+scripts).  The default for both parameters is@tie{}12.  Negative values
+are erroneous.
+@cindex inter-word spacing, minimal
+@cindex minimal inter-word spacing
+@cindex space, between words
+The first argument is a minimum; if an output line undergoes adjustment,
+such spaces may increase in width.
+@cindex inter-sentence space, additional
+@cindex additional inter-sentence space
+@cindex space, between sentences
+The optional second argument sets the amount of additional space
+separating sentences on the same output line.  If omitted, this amount
+is set to @var{word-space-size}.  The request is ignored if there are no
+parameters.
+
+@cindex filling, and inter-sentence space
+@cindex mode, fill, and inter-sentence space
+Additional inter-sentence space is used only if the output line is not
+full when the end of a sentence occurs in the input.  If a sentence ends
+at the end of an input line, then both an inter-word space and an
+inter-sentence 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.  Further input spaces after the second, if
+present, are adjusted as normal.
+
+The read-only registers @code{.ss} and @code{.sss} hold the minimal
+inter-word space and additional inter-sentence space amounts,
+respectively.  These parameters are part of the environment
+(@pxref{Environments}), and rounded down to the nearest multiple
+of@tie{}12 on terminals.
+
+@cindex discardable horizontal space
+@cindex space, discardable, horizontal
+@cindex horizontal discardable space
+The @code{ss} request can insert discardable horizontal space; that is,
+space that is discarded at a break.  For example, some footnote styles
+collect the notes into a single paragraph with large gaps between
+each note.
+
+@Example
+.ll 48n
+1.\~J. Fict. Ch. Soc. 6 (2020), 3\[en]14.
+.ss 12 48 \" applies to next sentence ending
+Reprints no longer available through FCS.
+.ss 12 \" go back to normal
+2.\~Better known for other work.
+    @result{} 1.  J.  Fict. Ch. Soc. 6 (2020), 3-14.  Reprints
+    @result{} no longer available through FCS.      2.  Better
+    @result{} known for other work.
+@endExample
+
+@noindent
+If @emph{undiscardable} space is required, use the @code{\h} escape
+sequence.
+@endDefreq
+
+
+@c =====================================================================
+
+@node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and Adjustment, GNU troff Reference
+@section Manipulating Hyphenation
+@cindex manipulating hyphenation
+@cindex hyphenation, manipulating
+
+@cindex hyphenation, automatic
+@cindex automatic hyphenation
+When filling, GNU @code{troff} hyphenates words as needed at
+user-specified and automatically determined hyphenation points.  The
+machine-driven determination of hyphenation points in words requires
+algorithms and data, and is susceptible to conventions and preferences.
+Before tackling such @dfn{automatic hyphenation}, let us consider how
+hyphenation points can be set explicitly.
+
+@cindex hyphenation, explicit
+@cindex explicit hyphenation
+@cindex hyphenation, manual
+@cindex manual hyphenation
+Explicitly hyphenated words such as ``mother-in-law'' are eligible for
+breaking after each of their hyphens.  Relatively few words in a
+language offer such obvious break points, however, and automatic
+detection of syllabic (or phonetic) boundaries for hyphenation is not
+perfect,@footnote{Whether a perfect algorithm for this application is
+even possible is an unsolved problem in computer science:@:
+@url{https://tug.org/docs/liang/liang-thesis.pdf}.} particularly for
+unusual words found in technical literature.  We can instruct GNU
+@code{troff} how to hyphenate specific words if the need arises.
+
+@cindex hyphenation exceptions
+@Defreq {hw, word @dots{}}
+Define each @dfn{hyphenation exception} @var{word} with each hyphen `-'
+in the word indicating a hyphenation point.  For example, the request
+
+@Example
+.hw in-sa-lub-rious alpha
+@endExample
+
+@c Serendipitously, in PDF output, the "alpha" below gets hyphenated.
+@c Try to preserve this felicity in future edits.
+marks potential hyphenation points in ``insalubrious'', and prevents
+``alpha'' from being hyphenated at all.
+
+Besides the space character, any character whose hyphenation code is
+zero can be used to separate the arguments of @code{hw} (see the
+@code{hcode} request below).  In addition, this request can be used more
+than once.
+
+@cindex @code{hw} request, and @code{hy} restrictions
+Hyphenation points specified with @code{hw} are not subject to the
+within-word placement restrictions imposed by the @code{hy} request (see
+below).
+
+Hyphenation exceptions specified with the @code{hw} request are
+associated with the hyphenation language (see the @code{hla} request
+below) and environment (@pxref{Environments}); invoking the @code{hw}
+request in the absence of a hyphenation language is an error.
+
+The request is ignored if there are no parameters.
+@endDefreq
+
+These are known as hyphenation @slanted{exceptions} in the expectation
+that most users will avail themselves of automatic hyphenation; these
+exceptions override any rules that would normally apply to a word
+matching a hyphenation exception defined with @code{hw}.
+
+Situations also arise when only a specific occurrence of a word needs
+its hyphenation altered or suppressed, or when a URL or similar string
+needs to be breakable in sensible places without hyphenation.
+
+@DefescList {\\%, , , }
+@DefescListEndx {\:, , , }
+@cindex hyphenation character (@code{\%})
+@cindex character, hyphenation (@code{\%})
+@cindex disabling hyphenation (@code{\%})
+@cindex hyphenation, disabling (@code{\%})
+To tell GNU @code{troff} how to hyphenate words as they occur in input,
+use the @code{\%} escape sequence; it is the default @dfn{hyphenation
+character}.  Each instance within a word indicates to GNU @code{troff}
+that the word may be hyphenated at that point, while prefixing a word
+with this escape sequence prevents it from being otherwise hyphenated.
+This mechanism affects only that occurrence of the word; to change the
+hyphenation of a word for the remainder of input processing, use the
+@code{hw} request.
+
+@cindex @code{\X}, followed by @code{\%}
+@cindex @code{\Y}, followed by @code{\%}
+@cindex @code{\%}, following @code{\X} or @code{\Y}
+GNU @code{troff} regards the escape sequences @code{\X} and @code{\Y} as
+starting a word; that is, the @code{\%} escape sequence in, say,
+@w{@samp{\X'...'\%foobar}} or @w{@samp{\Y'...'\%foobar}} no longer
+prevents hyphenation of @samp{foobar} but inserts a hyphenation point
+just prior to it; most likely this isn't what you want.
+@xref{Postprocessor Access}.
+
+@cindex non-printing break point (@code{\:})
+@cindex breaking without hyphens (@code{\:})
+@cindex file names, breaking (@code{\:})
+@cindex breaking file names (@code{\:})
+@cindex URLs, breaking (@code{\:})
+@cindex breaking URLs (@code{\:})
+@code{\:} inserts a non-printing break point; that is, a word can break
+there, but the soft hyphen glyph (see below) is not written to the
+output if it does.  This escape sequence is an input word boundary, so
+the remainder of the word is subject to hyphenation as normal.
+
+You can combine @code{\:} and @code{\%} to control breaking of a file
+name or URL, or to permit hyphenation only after certain explicit
+hyphens within a word.
+
+@Example
+@c Wrap example at 56 columns.
+The \%Lethbridge-Stewart-\:\%Sackville-Baggins divorce
+was, in retrospect, inevitable once the contents of
+\%/var/log/\:\%httpd/\:\%access_log on the family web
+server came to light, revealing visitors from Hogwarts.
+@endExample
+@endDefesc
+
+@Defreq {hc, [@Var{char}]}
+Change the hyphenation character to @var{char}.  This character then
+works as the @code{\%} escape sequence normally does, and thus no longer
+appears in the output.@footnote{@code{\%} itself stops marking
+hyphenation points but still produces no output glyph.}  Without an
+argument, @code{hc} resets the hyphenation character to @code{\%} (the
+default).  The hyphenation character is associated with the environment
+(@pxref{Environments}).
+@endDefreq
+
+@Defreq {shc, [@Var{c}]}
+@cindex soft hyphen character, setting (@code{shc})
+@cindex character, soft hyphen, setting (@code{shc})
+@cindex glyph, soft hyphen (@code{hy})
+@cindex soft hyphen glyph (@code{hy})
+@cindex @code{char} request, and soft hyphen character
+@cindex @code{tr} request, and soft hyphen character
+Set the @dfn{soft hyphen character}, inserted when a word is hyphenated
+automatically or at a hyphenation character, to the ordinary or special
+character@tie{}@var{c}.@footnote{``Soft'' because it appears in output
+only where a hyphenation break is performed; a ``hard'' hyphen, as in
+``long-term'', always appears.}  If the argument is omitted, the soft
+hyphen character is set to the default, @code{\[hy]}.  If no glyph for
+@var{c} exists in the font in use at a potential hyphenation point, then
+the line is not broken there.  Neither character definitions (specified
+with the @code{char} and similar requests) nor translations (specified
+with the @code{tr} request) are applied to @var{c}.
+@endDefreq
+
+@cindex hyphenation parameters, automatic
+@cindex automatic hyphenation parameters
+Several requests influence automatic hyphenation.  Because conventions
+vary, a variety of hyphenation modes is available to the @code{hy}
+request; these determine whether hyphenation will apply to a
+word prior to breaking a line at the end of a page (more or less; see
+below for details), and at which positions within that word
+automatically determined hyphenation points are permissible.  The places
+within a word that are eligible for hyphenation are determined by
+language-specific data and lettercase relationships.  Furthermore,
+hyphenation of a word might be suppressed due to a limit on
+consecutive hyphenated lines (@code{hlm}), a minimum line length
+threshold (@code{hym}), or because the line can instead be adjusted with
+additional inter-word space (@code{hys}).
+
+@cindex hyphenation mode register (@code{.hy})
+@DefreqList {hy, [@Var{mode}]}
+@DefregListEndx {.hy}
+Set automatic hyphenation mode to @var{mode}, an integer encoding
+conditions for hyphenation; if omitted, @samp{1} is implied.  The
+hyphenation mode is available in the read-only register @samp{.hy}; it
+is associated with the environment (@pxref{Environments}).  The default
+hyphenation mode depends on the localization file loaded when GNU
+@code{troff} starts up; see the @code{hpf} request below.
+
+Typesetting practice generally does not avail itself of every
+opportunity for hyphenation, but the details differ by language and site
+mandates.  The hyphenation modes of @acronym{AT&T} @code{troff} were
+implemented with English-language publishing practices of the 1970s in
+mind, not a scrupulous enumeration of conceivable parameters.  GNU
+@code{troff} extends those modes such that finer-grained control is
+possible, favoring compatibility with older implementations over a more
+intuitive arrangement.  The means of hyphenation mode control is a set
+of numbers that can be added up to encode the behavior
+sought.@footnote{The mode is a vector of Booleans encoded as an integer.
+To a programmer, this fact is easily deduced from the exclusive use of
+powers of two for the configuration parameters; they are computationally
+easy to ``mask off'' and compare to zero.  To almost everyone else, the
+arrangement seems recondite and unfriendly.}  The entries in the
+following table are termed @dfn{values}; the sum of the desired
+values is the @dfn{mode}.
+
+@table @code
+@item 0
+disables hyphenation.
+
+@item 1
+enables hyphenation except after the first and before the last character
+of a word.
+@end table
+
+The remaining values ``imply'' 1; that is, they enable hyphenation
+under the same conditions as @samp{.hy 1}, and then apply or lift
+restrictions relative to that basis.
+
+@table @code
+@item 2
+disables hyphenation of the last word on a page,@footnote{Hyphenation is
+prevented if the next page location trap is closer to the vertical
+drawing position than the next text baseline would be.  @xref{Page
+Location Traps}.} even for explicitly hyphenated words.
+
+@item 4
+disables hyphenation before the last two characters of a word.
+
+@item 8
+disables hyphenation after the first two characters of a word.
+
+@item 16
+enables hyphenation before the last character of a word.
+
+@item 32
+enables hyphenation after the first character of a word.
+@end table
+
+Apart from value@tie{}2, restrictions imposed by the hyphenation mode
+are @emph{not} respected for words whose hyphenations have been
+specified with the hyphenation character (@samp{\%} by default) or the
+@code{hw} request.
+
+Nonzero values in the previous table are additive.  For example,
+mode@tie{}12 causes GNU @code{troff} to hyphenate neither the last two
+nor the first two characters of a word.  Some values cannot be used
+together because they contradict; for instance, values 4 and@tie{}16,
+and values 8 and@tie{}32.  As noted, it is superfluous to add 1 to any
+non-zero even mode.
+
+@cindex hyphenation pattern files
+@cindex pattern files, for hyphenation
+The automatic placement of hyphens in words is determined by
+@dfn{pattern files}, which are derived from @TeX{} and available for
+several languages.  The number of characters at the beginning of a word
+after which the first hyphenation point should be inserted is determined
+by the patterns themselves; it can't be reduced further without
+introducing additional, invalid hyphenation points (unfortunately, this
+information is not part of a pattern file---you have to know it in
+advance).  The same is true for the number of characters at the end of
+a word before the last hyphenation point should be inserted.  For
+example, you can supply the following input to @samp{echo $(nroff)}.
+
+@Example
+.ll 1
+.hy 48
+splitting
+@endExample
+
+@noindent
+You will get
+
+@Example
+s- plit- t- in- g
+@endExample
+
+@noindent
+instead of the correct `split- ting'.  English patterns as distributed
+with GNU @code{troff} need two characters at the beginning and three
+characters at the end; this means that value@tie{}4 of @code{hy} is
+mandatory.  Value@tie{}8 is possible as an additional restriction, but
+values@tie{}16 and@tie{}32 should be avoided, as should mode@tie{}1.
+Modes@tie{}4 and@tie{}6 are typical.
+
+A table of left and right minimum character counts for hyphenation as
+needed by the patterns distributed with GNU @code{troff} follows; see
+the @cite{groff_tmac@r{(5)}} man page for more information on GNU
+@code{troff}'s language macro files.
+
+@multitable {German traditional}    {pattern name}    {left min}    {right min}
+@headitem    language           @tab pattern name @tab left min @tab right min
+@item        Czech              @tab cs           @tab 2        @tab 2
+@item        English            @tab en           @tab 2        @tab 3
+@item        French             @tab fr           @tab 2        @tab 3
+@item        German traditional @tab det          @tab 2        @tab 2
+@item        German reformed    @tab den          @tab 2        @tab 2
+@item        Italian            @tab it           @tab 2        @tab 2
+@item        Swedish            @tab sv           @tab 1        @tab 2
+@end multitable
+
+Hyphenation exceptions within pattern files (i.e., the words within a
+@TeX{} @code{\hyphenation} group) obey the hyphenation restrictions
+given by @code{hy}.
+@endDefreq
+
+@Defreq {nh, }
+Disable automatic hyphenation; i.e., set the hyphenation mode to@tie{}0
+(see above).  The hyphenation mode of the last call to @code{hy} is not
+remembered.
+@endDefreq
+
+@need 200
+@DefreqList {hpf, pattern-file}
+@DefreqItemx {hpfa, pattern-file}
+@DefreqListEndx {hpfcode, a b [c d] @dots{}}
+@cindex hyphenation patterns (@code{hpf})
+@cindex patterns for hyphenation (@code{hpf})
+Read hyphenation patterns from @var{pattern-file}, which is sought
+in the same way that macro files are with the @code{mso} request or the
+@option{-m@var{name}} command-line option to @code{groff}.  The
+@var{pattern-file} should have the same format as (simple) @TeX{}
+pattern files.  More specifically, the following scanning rules are
+implemented.
+
+@itemize @bullet
+@item
+A percent sign starts a comment (up to the end of the line) even if
+preceded by a backslash.
+
+@item
+``Digraphs'' like @code{\$} are not supported.
+
+@item
+@code{^^@var{xx}} (where each @var{x} is 0--9 or a--f) and
+@code{^^@var{c}} (character @var{c} in the code point range 0--127
+decimal) are recognized; other uses of @code{^} cause an error.
+
+@item
+No macro expansion is performed.
+
+@item
+@code{hpf} checks for the expression @code{\patterns@{@dots{}@}}
+(possibly with whitespace before or after the braces).  Everything
+between the braces is taken as hyphenation patterns.  Consequently,
+@code{@{} and @code{@}} are not allowed in patterns.
+
+@item
+Similarly, @code{\hyphenation@{@dots{}@}} gives a list of hyphenation
+exceptions.
+
+@item
+@code{\endinput} is recognized also.
+
+@item
+For backward compatibility, if @code{\patterns} is missing, the whole
+file is treated as a list of hyphenation patterns (except that the
+@code{%} character is recognized as the start of a comment).
+@end itemize
+
+The @code{hpfa} request appends a file of patterns to the current list.
+
+The @code{hpfcode} request defines mapping values for character codes in
+pattern files.  It is an older mechanism no longer used by GNU
+@code{troff}'s own macro files; for its successor, see @code{hcode}
+below.  @code{hpf} or @code{hpfa} apply the mapping after reading the
+patterns but before replacing or appending to the active list of
+patterns.  Its arguments are pairs of character codes---integers from 0
+to@tie{}255.  The request maps character code@tie{}@var{a} to
+code@tie{}@var{b}, code@tie{}@var{c} to code@tie{}@var{d}, and so on.
+Character codes that would otherwise be invalid in GNU @code{troff} 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'.
+
+@cindex localization
+@pindex troffrc
+@pindex cs.tmac
+@pindex de.tmac
+@pindex en.tmac
+@pindex fr.tmac
+@pindex it.tmac
+@pindex ja.tmac
+@pindex sv.tmac
+@pindex zh.tmac
+The set of hyphenation patterns is associated with the language set by
+the @code{hla} request (see below).  The @code{hpf} request is usually
+invoked by a localization file loaded by the @file{troffrc}
+file.@footnote{For more on localization, see the
+@cite{groff_tmac@r{(5)}} man page.}
+
+A second call to @code{hpf} (for the same language) replaces the
+hyphenation patterns with the new ones.  Invoking @code{hpf} or
+@code{hpfa} causes an error if there is no hyphenation language.  If no
+@code{hpf} request is specified (either in the document, in a file
+loaded at startup, or in a macro package), GNU @code{troff} won't
+automatically hyphenate at all.
+@endDefreq
+
+@Defreq {hcode, c1 code1 [c2 code2] @dots{}}
+@cindex hyphenation code (@code{hcode})
+@cindex code, hyphenation (@code{hcode})
+Set the hyphenation code of character @var{c1} to @var{code1}, that of
+@var{c2} to @var{code2}, and so on.  A hyphenation code must be an
+ordinary character (not a special character escape sequence) other than
+a digit or a space.  The request is ignored if given no arguments.
+
+For hyphenation to work, hyphenation codes must be set up.  At
+startup, GNU @code{troff} assigns hyphenation codes to the letters
+@samp{a}--@samp{z} (mapped to themselves), to the letters
+@samp{A}--@samp{Z} (mapped to @samp{a}--@samp{z}), and zero to all other
+characters.  Normally, hyphenation 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 @code{hcode} request extends this principle to letters
+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 @code{hcode} requests are necessary to assign
+hyphenation codes to the letters @samp{ÄäÖöÜüß}, needed for German.
+
+@Example
+.hcode ä ä  Ä ä
+.hcode ö ö  Ö ö
+.hcode ü ü  Ü ü
+.hcode ß ß
+@endExample
+
+Without these assignments, GNU @code{troff} treats the German word
+@w{`Kindergärten'} (the plural form of `kindergarten') as two words
+@w{`kinderg'} and @w{`rten'} because the hyphenation code of the
+umlaut@tie{}a is zero by default, just like a space.  There is a German
+hyphenation pattern that covers @w{`kinder'}, so GNU @code{troff} finds
+the hyphenation `kin-der'.  The other two hyphenation points
+(`kin-der-gär-ten') are missed.
+@endDefreq
+
+@DefreqList {hla, lang}
+@DefregListEndx {.hla}
+@cindex @code{hpf} request, and hyphenation language
+@cindex @code{hw} request, and hyphenation language
+@pindex troffrc
+@pindex troffrc-end
+Set the hyphenation language to @var{lang}.  Hyphenation exceptions
+specified with the @code{hw} request and hyphenation patterns and
+exceptions specified with the @code{hpf} and @code{hpfa} requests are
+associated with the hyphenation language.  The @code{hla} request is
+usually invoked by a localization file, which is turn loaded by the
+@file{troffrc} or @file{troffrc-end} file; see the @code{hpf} request
+above.
+
+@cindex hyphenation language register (@code{.hla})
+The hyphenation language is available in the read-only string-valued
+register @samp{.hla}; it is associated with the environment
+(@pxref{Environments}).
+@endDefreq
+
+@DefreqList {hlm, [@Var{n}]}
+@DefregItemx {.hlm}
+@DefregListEndx {.hlc}
+@cindex explicit hyphen (@code{\%})
+@cindex hyphen, explicit (@code{\%})
+@cindex consecutive hyphenated lines (@code{hlm})
+@cindex lines, consecutive hyphenated (@code{hlm})
+@cindex hyphenated lines, consecutive (@code{hlm})
+Set the maximum quantity of consecutive hyphenated lines to @var{n}.  If
+@var{n} is negative, there is no maximum.  If omitted, @var{n}
+is@tie{}@minus{}1.  This value is associated with the environment
+(@pxref{Environments}).  Only lines output from a given environment
+count toward the maximum associated with that environment.  Hyphens
+resulting from @code{\%} are counted; explicit hyphens are not.
+
+@cindex hyphenation consecutive line limit register (@code{.hlm})
+@cindex hyphenation consecutive line count register (@code{.hlc})
+The @code{.hlm} read-only register stores this maximum.  The count of
+immediately preceding consecutive hyphenated lines is available in the
+read-only register @code{.hlc}.
+@endDefreq
+
+@DefreqList {hym, [@Var{length}]}
+@DefregListEndx {.hym}
+@cindex hyphenation margin (@code{hym})
+@cindex margin for hyphenation (@code{hym})
+@cindex @code{ad} request, and hyphenation margin
+Set the (right) hyphenation margin to @var{length}.  If the adjustment
+mode is not @samp{b} or @samp{n}, the line is not hyphenated if it is
+shorter than @var{length}.  Without an argument, the hyphenation margin
+is reset to its default value, 0.  The default scaling unit is @samp{m}.
+The hyphenation margin is associated with the environment
+(@pxref{Environments}).
+
+A negative argument resets the hyphenation margin to zero, emitting a
+warning in category @samp{range}.
+
+@cindex hyphenation margin register (@code{.hym})
+The hyphenation margin is available in the @code{.hym} read-only
+register.
+@endDefreq
+
+@DefreqList {hys, [@Var{hyphenation-space}]}
+@DefregListEndx {.hys}
+@cindex hyphenation space (@code{hys})
+@cindex hyphenation space adjustment threshold
+@cindex @code{ad} request, and hyphenation space
+Suppress hyphenation of the line in adjustment modes @samp{b} or
+@samp{n} if it can be justified by adding no more than
+@var{hyphenation-space} extra space to each inter-word space.  Without
+an argument, the hyphenation space adjustment threshold is set to its
+default value, 0.  The default scaling unit is @samp{m}.  The
+hyphenation space adjustment threshold is associated with the
+environment (@pxref{Environments}).
+
+A negative argument resets the hyphenation space adjustment threshold to
+zero, emitting a warning in category @samp{range}.
+
+@cindex hyphenation space adjustment threshold register (@code{.hys})
+The hyphenation space adjustment threshold is available in the
+@code{.hys} read-only register.
+@endDefreq
+
+
+@c =====================================================================
+
+@node Manipulating Spacing, Tabs and Fields, Manipulating Hyphenation, GNU troff Reference
+@section Manipulating Spacing
+@cindex manipulating spacing
+@cindex spacing, manipulating
+
+A break causes the formatter to update the vertical drawing position at
+which the new text baseline is aligned.  You can alter this location.
+
+@Defreq {sp, [@Var{distance}]}
+Break and move the next text baseline down by @var{distance}, or until
+springing a page location trap.@footnote{@xref{Page Location Traps}.}
+If invoked with the no-break control character, @code{sp} moves the
+pending output line's text baseline by @var{distance}.  A negative
+@var{distance} will not reduce the position of the text baseline below
+zero.  Inside a diversion, any @var{distance} argument is ignored.  The
+default scaling unit is @samp{v}.  If @var{distance} is not specified,
+@samp{1v} is assumed.
+
+@Example
+.pl 5v \" Set page length to 5 vees.
+.de xx
+\-\-\-
+.  br
+..
+.wh 0 xx \" Set a trap at the top of the page.
+foo on page \n%
+.sp 2v
+bar on page \n%
+.sp 50v \" This will cause a page break.
+baz on page \n%
+.pl \n(nlu \" Truncate page to current position.
+    @result{} ---
+    @result{} foo on page 1
+    @result{}
+    @result{}
+    @result{} bar on page 1
+    @result{} ---
+    @result{} baz on page 2
+@endExample
+
+You might use the following macros to set the baseline of the next
+output text at a given distance from the top or the bottom of the page.
+We subtract one line height (@code{\n[.v]}) because the @code{|}
+operator moves to one vee below the page top (recall @ref{Numeric
+Expressions}).
+
+@Example
+.de y-from-top-down
+.  sp |\\$1-\\n[.v]u
+..
+.
+.de y-from-bot-up
+.  sp |\\n[.p]u-\\$1-\\n[.v]u
+..
+@endExample
+
+@noindent
+A call to @samp{.y-from-bot-up 10c} means that the next text baseline
+will be 10@tie{}cm from the bottom edge of the paper.
+@endDefreq
+
+@DefreqList {ls, [@Var{count}]}
+@DefregListEndx {.L}
+@cindex double-spacing (@code{ls})
+Set the line spacing; add @w{@var{count}@minus{}1} blank lines after each
+line of text.  With no argument, GNU @code{troff} uses the previous
+value before the last @code{ls} call.  The default is @code{1}.
+
+@c This example is fairly obvious, doesn't realistically reflect the
+@c fact that formatted text would occur between each of these requests,
+@c and doesn't fit well on the (PDF) page as of this writing.
+@c @Example
+@c .ls 2    \" begin double-spaced output
+@c .ls 3    \" begin triple-spaced output
+@c .ls      \" return to double-spaced output
+@c @endExample
+
+@cindex line spacing register (@code{.L})
+The read-only register @code{.L} contains the current line spacing; it
+is associated with the environment (@pxref{Environments}).
+@endDefreq
+
+The @code{ls} request is a coarse mechanism.  @xref{Changing the Type
+Size}, for the requests @code{vs} and @code{pvs} as alternatives to
+@code{ls}.
+
+@DefescList {\\x, @code{'}, spacing, @code{'}}
+@DefregListEndx {.a}
+Sometimes, an output line requires additional vertical spacing, for
+instance to allow room for a tall construct like an inline equation with
+exponents or subscripts (particularly if they are iterated).  The
+@code{\x} escape sequence takes a delimited measurement (like
+@samp{\x'3p'}) to increase the vertical spacing of the pending output
+line.  The default scaling unit is @samp{v}.  If the measurement is
+positive, extra vertical space is inserted below the current line; a
+negative measurement adds space above.  If @code{\x} is applied to the
+pending output line multiple times, the maxima of the positive and
+negative adjustments are separately applied.  The delimiter need not be
+a neutral apostrophe; see @ref{Delimiters}.
+
+@cindex extra post-vertical line space register (@code{.a})
+The @code{.a} read-only register contains the extra vertical spacing
+@emph{after} the text baseline of the most recently emitted output line.
+(In other words, it is the largest positive argument to @code{\x}
+encountered on that line.)  This quantity is exposed via a register
+because if an output line requires this ``extra post-vertical line
+spacing'', and the subsequent output line requires ``extra pre-vertical
+line spacing'' (a negative argument to @code{\x}), then applying both
+can lead to excessive spacing between the output lines.  Text that is
+piling high on line @var{n} might not require (as much) extra
+pre-vertical line spacing if line @var{n}@minus{}1 carries extra
+post-vertical line spacing.
+
+Use of @code{\x} can be necessary in combination with the
+bracket-building escape sequence @code{\b},@footnote{@xref{Drawing
+Geometric Objects}.} as the following example shows.
+
+@Example
+.nf
+This is a test of \[rs]b (1).
+This is a test of \[rs]b (2).
+This is a test of \b'xyz'\x'-1m'\x'1m' (3).
+This is a test of \[rs]b (4).
+This is a test of \[rs]b (5).
+    @result{} This is a test of \b (1).
+    @result{} This is a test of \b (2).
+    @result{}                   x
+    @result{} This is a test of y (3).
+    @result{}                   z
+    @result{} This is a test of \b (4).
+    @result{} This is a test of \b (5).
+@endExample
+@endDefesc
+
+@noindent
+Without @code{\x}, the backslashes on the lines marked @samp{(2)} and
+@samp{(4)} would be overprinted.
+
+@need 1000
+@DefreqList {ns, }
+@DefreqItemx {rs, }
+@DefregListEndx {.ns}
+@cindex @code{sp} request, and no-space mode
+@cindex no-space mode (@code{ns})
+@cindex mode, no-space (@code{ns})
+@cindex blank lines, disabling
+@cindex lines, blank, disabling
+Enable @dfn{no-space mode}.  Vertical spacing, whether by @code{sp}
+requests or blank input lines, is disabled.  The @code{bp} request to
+advance to the next page is also disabled, unless it is accompanied by a
+page number (@pxref{Page Control}).  No-space mode ends automatically
+when text@footnote{or geometric objects; see @ref{Drawing Geometric
+Objects}} is formatted for output @footnote{to the top-level diversion;
+see @ref{Diversions}} or the @code{rs} request is invoked, which ends
+no-space mode.  The read-only register @code{.ns} interpolates a Boolean
+value indicating the enablement of no-space mode.
+
+A paragraphing macro might ordinarily insert vertical space to separate
+paragraphs.  A section heading macro could invoke @code{ns} to suppress
+this spacing for the first paragraph in a section.
+@endDefreq
+
+
+@c =====================================================================
+
+@node Tabs and Fields, Character Translations, Manipulating Spacing, GNU troff Reference
+@section Tabs and Fields
+@cindex tabs, and fields
+@cindex fields, and tabs
+
+@cindex tab character encoding
+A tab character (@acronym{ISO} code point@tie{}9, @acronym{EBCDIC}
+code point@tie{}5) causes a horizontal movement to the next tab stop, if
+any.
+
+@Defesc {\\t, , , }
+@cindex tab character, non-interpreted (@code{\t})
+@cindex character, tab, non-interpreted (@code{\t})
+@cindex @code{\t}, and copy mode
+@cindex copy mode, and @code{\t}
+@cindex mode, copy, and @code{\t}
+Interpolate a tab in copy mode; see @ref{Copy Mode}.
+@endDefesc
+
+@DefreqList {ta, [[@Var{n1} @Var{n2} @dots{} @Var{nn} ]@t{T} @Var{r1} @
+ @Var{r2} @dots{} @Var{rn}]}
+@DefregListEndx {.tabs}
+Change tab stop positions.  This request takes a series of tab
+specifiers as arguments (optionally divided into two groups with the
+letter @samp{T}) that indicate where each tab stop is to be, overriding
+any previous settings.  The default scaling unit is @samp{m}.  Invoking
+@code{ta} without an argument removes all tab stops.
+@cindex default tab stops
+@cindex tab stops, default
+GNU @code{troff}'s startup value is @w{@samp{T 0.5i}}.
+
+Tab stops can be specified absolutely---as distances from the left
+margin.  The following example sets six tab stops, one every inch.
+
+@Example
+.ta 1i 2i 3i 4i 5i 6i
+@endExample
+
+Tab stops can also be specified using a leading @samp{+}, which means
+that the specified tab stop is set relative to the previous tab stop.
+For example, the following is equivalent to the previous example.
+
+@Example
+.ta 1i +1i +1i +1i +1i +1i
+@endExample
+
+GNU @code{troff} supports an extended syntax to specify repeating tab
+stops.  These stops appear after a @samp{T} argument.  Their values are
+always taken as distances relative to the previous tab stop.  This is
+the idiomatic way to specify tab stops at equal intervals in
+@code{groff}.  The following is, yet again, the same as the previous
+examples.  It does more, in fact, since it defines an infinite number of
+tab stops at one-inch intervals.
+
+@Example
+.ta T 1i
+@endExample
+
+Now we are ready to interpret the full syntax given above.  The
+@code{ta} request sets tabs at positions @var{n1}, @var{n2}, @dots{},
+@var{nn}, then at @var{nn}+@var{r1}, @var{nn}+@var{r2}, @dots{},
+@var{nn}+@var{rn}, then at @var{nn}+@var{rn}+@var{r1},
+@var{nn}+@var{rn}+@var{r2}, @dots{}, @var{nn}+@var{rn}+@var{rn}, and so
+on.
+
+For example, @samp{4c +6c T 3c 5c 2c} is equivalent to @samp{4c 10c 13c
+18c 20c 23c 28c 30c @dots{}}.
+
+Text written to a tab column (i.e., between two tab stops, or between a
+tab stop and an output line boundary) may be aligned to the right or
+left, or centered in the column.  This alignment is determined by
+appending @samp{R}, @samp{L}, or @samp{C} to the tab specifier.  The
+default is @samp{L}.
+
+@Example
+.ta 1i 2iC 3iR
+@endExample
+
+The beginning of an output line is not a tab stop; the text that begins
+an output line is placed according to the configured alignment and
+indentation; see @ref{Manipulating Filling and Adjustment} and @ref{Line
+Layout}.
+
+A tab stop is converted into a non-breakable horizontal movement that
+cannot be adjusted.
+
+@Example
+.ll 2i
+.ds foo a\tb\tc
+.ta T 1i
+\*[foo]
+    @error{} warning: cannot break line
+    @result{} a         b         c
+@endExample
+
+@noindent
+The above creates a single output line that is a bit longer than two
+inches (we use a string to show exactly where the tab stops are).
+Now consider the following.
+
+@Example
+.ll 2i
+.ds bar a\tb c\td
+.ta T 1i
+\*[bar]
+    @error{} warning: cannot adjust line
+    @result{} a         b
+    @result{} c       d
+@endExample
+
+@noindent
+GNU @code{troff} first converts the line's tab stops into unbreakable
+horizontal movements, then breaks after @samp{b}.  This usually isn't
+what you want.
+
+Superfluous tab characters---those that do not correspond to a tab
+stop---are ignored except for the first, which delimits the characters
+belonging to the last tab stop for right-alignment or centering.
+
+@Example
+.ds Z   foo\tbar\tbaz
+.ds ZZ  foo\tbar\tbazqux
+.ds ZZZ foo\tbar\tbaz\tqux
+.ta 2i 4iR
+\*[Z]
+.br
+\*[ZZ]
+.br
+\*[ZZZ]
+.br
+    @result{} foo                 bar              baz
+    @result{} foo                 bar           bazqux
+    @result{} foo                 bar              bazqux
+@endExample
+
+@noindent
+The first line right-aligns ``baz'' within the second tab stop.  The
+second line right-aligns ``bazqux'' within it.  The third line
+right-aligns only ``baz'' because of the additional tab character, which
+marks the end of the text occupying the last tab stop defined.
+
+Tab stops are associated with the environment (@pxref{Environments}).
+
+@cindex tab stop settings register (@code{.tabs})
+@cindex @code{.S} register, Plan@tie{}9 alias for @code{.tabs}
+@cindex @code{.tabs} register, Plan@tie{}9 alias (@code{.S})
+The read-only register @code{.tabs} contains a string
+representation of the current tab settings suitable for use as an
+argument to the @code{ta} request.@footnote{Plan@tie{}9 @code{troff}
+uses the register @code{.S} for this purpose.}
+
+@Example
+.ds tab-string \n[.tabs]
+\*[tab-string]
+    @result{} T120u
+@endExample
+@endDefreq
+
+@Defreq {tc, [@Var{c}]}
+@cindex tab repetition character (@code{tc})
+@cindex character, tab repetition (@code{tc})
+@cindex glyph, tab repetition (@code{tc})
+Set the tab repetition character to the ordinary or special character
+@var{c}; normally, no glyph is written when moving to a tab stop (and
+some output devices may output space characters to achieve this motion).
+A @dfn{tab repetition character} causes the formatter to write as many
+instances of @var{c} as are necessary to occupy the interval from the
+horizontal drawing position to the next tab stop.  With no argument, GNU
+@code{troff} reverts to the default behavior.  The tab repetition
+character is associated with the environment (@pxref{Environments}).
+Only a single character of @var{c} is recognized; any excess is ignored.
+@endDefreq
+
+@DefreqList {linetabs, n}
+@DefregListEndx {.linetabs}
+@cindex tab, line-tabs mode
+@cindex line-tabs mode
+@cindex mode, line-tabs
+If @var{n} is missing or non-zero, activate @dfn{line-tabs}; deactivate
+it otherwise (the default).  Active line-tabs cause GNU @code{troff}
+to compute tab distances relative to the start of the output line
+instead of the input line.
+
+@Example
+.de Tabs
+.  ds x a\t\c
+.  ds y b\t\c
+.  ds z c
+.  ta 1i 3i
+\\*x
+\\*y
+\\*z
+..
+.Tabs
+.br
+.linetabs
+.Tabs
+    @result{} a         b         c
+    @result{} a         b                   c
+@endExample
+
+Line-tabs activation is associated with the environment
+(@pxref{Environments}).  The read-only register @code{.linetabs}
+interpolates@tie{}1 if line-tabs are active, and 0 otherwise.
+@endDefreq
+
+@menu
+* Leaders::
+* Fields::
+@end menu
+
+@c ---------------------------------------------------------------------
+
+@node Leaders, Fields, Tabs and Fields, Tabs and Fields
+@subsection Leaders
+@cindex leaders
+
+Sometimes it is desirable to fill a tab stop with a given glyph,
+but also use tab stops normally on the same output line.  An example is
+a table of contents entry that uses dots to bridge the entry name with
+its page number, which is itself aligned between tab stops.  The
+@code{roff} language provides @dfn{leaders} for this
+purpose.@footnote{This is pronounced to rhyme with ``feeder'', and
+refers to how the glyphs ``lead'' the eye across the page to the
+corresponding page number or other datum.}
+
+@cindex leader character
+A leader character (@acronym{ISO} and @acronym{EBCDIC} code
+point@tie{}1, also known as @acronym{SOH} or ``start of heading''),
+behaves similarly to a tab character:@: it moves to the next tab stop.
+The difference is that for this movement, the default fill character is
+a period @samp{.}.
+
+@Defesc {\\a, , , }
+@cindex leader character, non-interpreted (@code{\a})
+@cindex character, leader, non-interpreted (@code{\a})
+@cindex @code{\a}, and copy mode
+@cindex copy mode, and @code{\a}
+@cindex mode, copy, and @code{\a}
+Interpolate a leader in copy mode; see @ref{Copy Mode}.
+@endDefesc
+
+@Defreq {lc, [@Var{c}]}
+@cindex leader repetition character (@code{lc})
+@cindex character, leader repetition (@code{lc})
+@cindex glyph, leader repetition (@code{lc})
+Set the leader repetition character to the ordinary or special character
+@var{c}.  Recall @ref{Tabs and Leaders}:@: when encountering a leader
+character in the input, the formatter writes as many dots @samp{.} as
+are necessary until
+reaching the next tab stop; this is the @dfn{leader definition
+character}.  Omitting @var{c} unsets the leader
+character.  With no argument, GNU @code{troff} treats leaders the same
+as tabs.  The leader repetition character is associated with the
+environment (@pxref{Environments}).  Only a single @var{c} is
+recognized; any excess is ignored.
+@endDefreq
+
+@cindex table of contents
+@cindex contents, table of
+A table of contents, for example, may define tab stops after a section
+number, a title, and a gap to be filled with leader dots.  The page
+number follows the leader, after a right-aligned final tab stop wide
+enough to house the largest page number occurring in the document.
+
+@Example
+.ds entry1 19.\tThe Prophet\a\t98
+.ds entry2 20.\tAll Astir\a\t101
+.ta .5i 4.5i +.5iR
+.nf
+\*[entry1]
+\*[entry2]
+    @result{} 19.  The Prophet.............................   98
+    @result{} 20.  All Astir...............................  101
+@endExample
+
+@c ---------------------------------------------------------------------
+
+@node Fields,  , Leaders, Tabs and Fields
+@subsection Fields
+@cindex fields
+
+@cindex field delimiting character (@code{fc})
+@cindex delimiting character, for fields (@code{fc})
+@cindex character, field delimiting (@code{fc})
+@cindex field padding character (@code{fc})
+@cindex padding character, for fields (@code{fc})
+@cindex character, field padding (@code{fc})
+@dfn{Fields} are a more general way of laying out tabular data.  A field
+is defined as the data between a pair of @dfn{delimiting characters}.
+It contains substrings that are separated by @dfn{padding characters}.
+The width of a field is the distance on the @emph{input} line from the
+position where the field starts to the next tab stop.  A padding
+character inserts an adjustable space similar to @TeX{}'s @code{\hss}
+command (thus it can even be negative) to make the sum of all substring
+lengths plus the adjustable space equal to the field width.  If more
+than one padding character is inserted, the available space is evenly
+distributed among them.
+
+@Defreq {fc, [@Var{delim-char} [@Var{padding-char}]]}
+Define a delimiting and a padding character for fields.  If the latter
+is missing, the padding character defaults to a space character.  If
+there is no argument at all, the field mechanism is disabled (which is
+the default).  In contrast to, e.g., the tab repetition character,
+delimiting and padding characters are @emph{not} associated with the
+environment (@pxref{Environments}).
+
+@Example
+.fc # ^
+.ta T 3i
+#foo^bar^smurf#
+.br
+#foo^^bar^smurf#
+    @result{} foo         bar          smurf
+    @result{} foo            bar       smurf
+@endExample
+@endDefreq
+
+
+@c =====================================================================
+
+@node Character Translations, @code{troff} and @code{nroff} Modes, Tabs and Fields, GNU troff Reference
+@section Character Translations
+@cindex character translations
+@cindex translations of characters
+
+A @dfn{translation} is a mapping of an input character to an output
+glyph.  The mapping occurs at output time, i.e., the input character
+gets assigned the metric information of the mapped output character
+right before input tokens are converted to nodes (@pxref{Gtroff
+Internals}, for more on this process).
+
+@DefreqList {tr, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
+@DefreqListEndx {trin, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
+Translate character @var{a} to glyph@tie{}@var{b}, character @var{c} to
+glyph@tie{}@var{d}, and so on.  If there is an odd number of characters
+in the argument, the last one is translated to a fixed-width space (the
+same one obtained by the @code{\@key{SP}} escape sequence).
+
+The @code{trin} request is identical to @code{tr}, but when you unformat
+a diversion with @code{asciify} it ignores the translation.
+@xref{Diversions}, for details about the @code{asciify} request.
+
+Some notes:
+
+@itemize @bullet
+@item
+@cindex @code{\(}, and translations
+@cindex @code{\[}, and translations
+@cindex @code{\'}, and translations
+@cindex @code{\`}, and translations
+@cindex @code{\-}, and translations
+@cindex @code{\_}, and translations
+@cindex @code{\C}, and translations
+@cindex @code{\N}, and translations
+@cindex @code{char} request, and translations
+@cindex special characters
+@cindex character, special
+@cindex numbered glyph (@code{\N})
+@cindex glyph, numbered (@code{\N})
+Special characters (@code{\(@var{xx}}, @code{\[@var{xxx}]},
+@code{\C'@var{xxx}'}, @code{\'}, @code{\`}, @code{\-}, @code{\_}),
+glyphs defined with the @code{char} request, and numbered glyphs
+(@code{\N'@var{xxx}'}) can be translated also.
+
+@item
+@cindex @code{\e}, and translations
+The @code{\e} escape can be translated also.
+
+@item
+@cindex @code{\%}, and translations
+@cindex @code{\~}, and translations
+Characters can be mapped onto the @code{\%} and @code{\~} escape
+sequences (but @code{\%} and @code{\~} can't be mapped onto another
+glyph).
+
+@item
+@cindex backspace character, and translations
+@cindex character, backspace, and translations
+@cindex leader character, and translations
+@cindex character, leader, and translations
+@cindex newline character, and translations
+@cindex character, newline, and translations
+@cindex tab character, and translations
+@cindex character, tab, and translations
+@cindex @code{\a}, and translations
+@cindex @code{\t}, and translations
+The following characters can't be translated: space (with one exception,
+see below), backspace, newline, leader (and @code{\a}), tab (and
+@code{\t}).
+
+@item
+@cindex @code{shc} request, and translations
+Translations are not considered for finding the soft hyphen character
+set with the @code{shc} request.
+
+@item
+@cindex @code{\&}, and translations
+The pair @samp{@var{c}\&} (an arbitrary character@tie{}@var{c} followed
+by the dummy character) maps this character to ``nothing''.
+
+@Example
+.tr a\&
+foo bar
+    @result{} foo br
+@endExample
+
+@noindent
+Even the space character can be mapped to the dummy character.
+
+@Example
+.tr aa \&
+foo bar
+    @result{} foobar
+@endExample
+
+@noindent
+As shown in the example, the space character can't be the first
+character/glyph pair as an argument of @code{tr}.  Additionally, it is
+not possible to map the space character to any other glyph; requests
+like @w{@samp{.tr aa x}} undo @w{@samp{.tr aa \&}} instead.
+
+If justification is active, lines are justified in spite of the `empty'
+space character (but there is no minimal distance, i.e., the space
+character, between words).
+
+@item
+After an output glyph has been constructed (this happens at the moment
+immediately before the glyph is appended to an output glyph list, either
+by direct output, in a macro, diversion, or string), it is no longer
+affected by @code{tr}.
+
+@item
+Translating character to glyphs where one of them or both are undefined
+is possible also; @code{tr} does not check whether the elements of its
+argument exist.
+
+@xref{Gtroff Internals}.
+
+@item
+Without an argument, the @code{tr} request is ignored.
+@end itemize
+@endDefreq
+
+@Defreq {trnt, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
+@cindex @code{\!}, and @code{trnt}
+@code{trnt} is the same as the @code{tr} request except that the
+translations do not apply to text that is transparently throughput into
+a diversion with @code{\!}.  @xref{Diversions}.
+
+For example,
+
+@Example
+.tr ab
+.di x
+\!.tm a
+.di
+.x
+@endExample
+
+@noindent
+prints @samp{b} to the standard error stream; if @code{trnt} is used
+instead of @code{tr} it prints @samp{a}.
+@endDefreq
+
+
+@c =====================================================================
+
+@node @code{troff} and @code{nroff} Modes, Line Layout, Character Translations, GNU troff Reference
+@section @code{troff} and @code{nroff} Modes
+@cindex @code{troff} mode
+@cindex mode, @code{troff}
+@cindex @code{nroff} mode
+@cindex mode, @code{nroff}
+
+Historically, @code{nroff} and @code{troff} were two separate programs;
+the former for terminal output, the latter for typesetters.  GNU
+@code{troff} merges both functions into one executable@footnote{A
+GNU @command{nroff} program is available for convenience; it calls GNU
+@code{troff} to perform the formatting.} that sends its output to a
+device driver (@code{grotty} for terminal devices, @code{grops} for
+PostScript, and so on) which interprets this intermediate output format.
+When discussing @acronym{AT&T} @code{troff}, it makes sense to talk
+about @dfn{@code{nroff} mode} and @dfn{@code{troff} mode} since the
+differences are hard-coded.  GNU @code{troff} takes information from
+device and font description files without handling requests specially if
+a terminal output device is used, so such a strong distinction is
+unnecessary.
+
+Usually, a macro package can be used with all output devices.
+Nevertheless, it is sometimes necessary to make a distinction between
+terminal and non-terminal devices: GNU @code{troff} provides two
+built-in conditions @samp{n} and @samp{t} for the @code{if}, @code{ie},
+and @code{while} requests to decide whether GNU @code{troff} shall
+behave like @code{nroff} or like @code{troff}.
+
+@Defreq {troff, }
+@pindex troffrc
+@pindex troffrc-end
+Make the @samp{t} built-in condition true (and the @samp{n} built-in
+condition false) for @code{if}, @code{ie}, and @code{while} conditional
+requests.  This is the default if GNU @code{troff} (@emph{not}
+@code{groff}) is started with the @option{-R} switch to avoid loading of
+the startup files @file{troffrc} and @file{troffrc-end}.  Without
+@option{-R}, GNU @code{troff} stays in @code{troff} mode if the output
+device is not a terminal (e.g., `ps').
+@endDefreq
+
+@Defreq {nroff, }
+@pindex tty.tmac
+Make the @samp{n} built-in condition true (and the @samp{t} built-in
+condition false) for @code{if}, @code{ie}, and @code{while} conditional
+requests.  This is the default if GNU @code{troff} uses a terminal
+output device; the code for switching to @code{nroff} mode is in the
+file @file{tty.tmac}, which is loaded by the startup file
+@code{troffrc}.
+@endDefreq
+
+@xref{Conditionals and Loops}, for more details on built-in conditions.
+
+
+@c =====================================================================
+
+@node Line Layout, Line Continuation, @code{troff} and @code{nroff} Modes, GNU troff Reference
+@section Line Layout
+@cindex line layout
+@cindex layout, line
+
+@cindex dimensions, line
+@cindex line dimensions
+The following drawing shows the dimensions that @code{gtroff} uses for
+placing a line of output onto the page.  They are labeled with the
+request that manipulates each dimension.
+
+@Example
+     -->| in |<--
+        |<-----------ll------------>|
+   +----+----+----------------------+----+
+   |    :    :                      :    |
+   +----+----+----------------------+----+
+-->| po |<--
+   |<--------paper width---------------->|
+@endExample
+
+@noindent
+These dimensions are:
+
+@ftable @code
+@item po
+@cindex left margin (@code{po})
+@cindex margin, left (@code{po})
+@cindex page offset (@code{po})
+@cindex offset, page (@code{po})
+@dfn{Page offset}---this is the leftmost position of text on the final
+output, defining the @dfn{left margin}.
+
+@item in
+@cindex indentation (@code{in})
+@cindex line indentation (@code{in})
+@dfn{Indentation}---this is the distance from the left margin where
+text is printed.
+
+@item ll
+@cindex line length (@code{ll})
+@cindex length of line (@code{ll})
+@dfn{Line length}---this is the distance from the left margin to right
+margin.
+@end ftable
+
+@cindex margin, right
+@cindex right margin
+The right margin is not explicitly configured; the combination of page
+offset and line length provides the information necessary to derive it.
+
+A simple demonstration:
+
+@Example
+.ll 3i
+This is text without indentation.
+The line length has been set to 3\~inches.
+.in +.5i
+.ll -.5i
+Now the left and right margins are both increased.
+.in
+.ll
+Calling .in and .ll without parameters restores
+the previous values.
+@endExample
+
+@Example
+    @result{} This  is text without indenta-
+    @result{} tion.   The  line  length  has
+    @result{} been set to 3 inches.
+    @result{}      Now   the  left  and
+    @result{}      right  margins   are
+    @result{}      both increased.
+    @result{} Calling  .in  and  .ll without
+    @result{} parameters restores the previ-
+    @result{} ous values.
+@endExample
+
+@DefreqList {po, [@Var{offset}]}
+@DefreqItem {po, @t{+}@Var{offset}}
+@DefreqItem {po, @t{-}@Var{offset}}
+@DefregListEndx {.o}
+@pindex tty.tmac
+Set page offset to @var{offset} (or increment or decrement its current
+value by @var{offset}).  If invoked without an argument, the page offset
+is restored to the value before the previous @code{po} request.
+This request does not cause a break; the page offset in effect when an
+output line is broken prevails (@pxref{Manipulating Filling and
+Adjustment}).  The initial value is 1@dmn{i} and the default scaling
+unit is @samp{m}.  On terminal devices, the page offset is set to zero
+by a driver-specific macro file, @file{tty.tmac}.  The current page
+offset can be found in the read-only register @samp{.o}.
+@cindex CSTR@tie{}#54 errata
+@cindex CSTR@tie{}#54 erratum, @code{po} request
+This request is incorrectly documented in the @acronym{AT&T}
+@code{troff} manual as using a default scaling unit of @samp{v}.
+
+@Example
+.po 3i
+\n[.o]
+    @result{} 720
+.po -1i
+\n[.o]
+    @result{} 480
+.po
+\n[.o]
+    @result{} 720
+@endExample
+@endDefreq
+
+@DefreqList {in, [@Var{indent}]}
+@DefreqItem {in, @t{+}@Var{indent}}
+@DefreqItem {in, @t{-}@Var{indent}}
+@DefregListEndx {.i}
+Set indentation to @var{indent} (or increment or decrement the current
+value by @var{indent}).  This request causes a break.  Initially, there
+is no indentation.
+
+If @code{in} is called without an argument, the indentation is reset to
+the previous value before the last call to @code{in}.  The default
+scaling unit is @samp{m}.
+
+If a negative indentation value is specified (which is not allowed),
+@code{gtroff} emits a warning in category @samp{range} and sets the
+indentation to zero.
+
+The effect of @code{in} is delayed until a partially collected line (if
+it exists) is output.  A temporary indentation value is reset to zero
+also.
+
+The current indentation (as set by @code{in}) can be found in the
+read-only register @samp{.i}.  The indentation is associated with the
+environment (@pxref{Environments}).
+@endDefreq
+
+@DefreqList {ti, offset}
+@DefreqItem {ti, @t{+}@Var{offset}}
+@DefreqItem {ti, @t{-}@Var{offset}}
+@DefregListEndx {.in}
+Temporarily indent the next output line by @var{offset}.  If an
+increment or decrement value is specified, adjust the temporary
+indentation relative to the value set by the @code{in} request.
+
+This request causes a break; its value is associated with the
+environment (@pxref{Environments}).  The default scaling unit is
+@samp{m}.  A call of @code{ti} without an argument is ignored.
+
+If the total indentation value is negative (which is not allowed),
+@code{gtroff} emits a warning in category @samp{range} and sets the
+temporary indentation to zero.  `Total indentation' is either
+@var{offset} if specified as an absolute value, or the temporary plus
+normal indentation, if @var{offset} is given as a relative value.
+
+The effect of @code{ti} is delayed until a partially collected line (if
+it exists) is output.
+
+The read-only register @code{.in} is the indentation that applies to the
+current output line.
+
+The difference between @code{.i} and @code{.in} is that the latter takes
+into account whether a partially collected line still uses the old
+indentation value or a temporary indentation value is active.
+@endDefreq
+
+@DefreqList {ll, [@Var{length}]}
+@DefreqItem {ll, @t{+}@Var{length}}
+@DefreqItem {ll, @t{-}@Var{length}}
+@DefregItemx {.l}
+@DefregListEndx {.ll}
+Set the line length to @var{length} (or increment or decrement the
+current value by @var{length}).  Initially, the line length is set to
+6.5@dmn{i}.  The effect of @code{ll} is delayed until a partially
+collected line (if it exists) is output.  The default scaling unit is
+@samp{m}.
+
+If @code{ll} is called without an argument, the line length is reset to
+the previous value before the last call to @code{ll}.  If a negative
+line length is specified (which is not allowed), @code{gtroff} emits a
+warning in category @samp{range} and sets the line length to zero.  The
+line length is associated with the environment (@pxref{Environments}).
+
+@cindex line length register (@code{.l})
+The current line length (as set by @code{ll}) can be found in the
+read-only register @samp{.l}.  The read-only register @code{.ll} is the
+line length that applies to the current output line.
+
+Similar to @code{.i} and @code{.in}, the difference between @code{.l}
+and @code{.ll} is that the latter takes into account whether a partially
+collected line still uses the old line length value.
+@endDefreq
+
+
+@c =====================================================================
+
+@node Line Continuation, Page Layout, Line Layout, GNU troff Reference
+@section Line Continuation
+@cindex line control
+@cindex control, line
+
+When filling is enabled, input and output line breaks generally do not
+correspond.  The @code{roff} language therefore distinguishes input and
+output line continuation.
+
+@Defesc {\\@key{RET}, , ,}
+@cindex input line continuation (@code{\@key{RET}})
+@cindex line, input, continuation (@code{\@key{RET}})
+@cindex continuation, input line (@code{\@key{RET}})
+@c We use the following notation in our man pages; Texinfo is bound to
+@c the GNU Emacs dialect.
+@esindex \@slanted{newline}
+@code{\@key{RET}} (a backslash immediately followed by a newline)
+suppresses the effects of that newline in the input.  The next input
+line thus retains the classification of its predecessor as a control or
+text line.  @code{\@key{RET}} is useful for managing line lengths in the
+input during document maintenance; you can break an input line in the
+middle of a request invocation, macro call, or escape sequence.  Input
+line continuation is invisible to the formatter, with two exceptions:
+the @code{|} operator recognizes the new input line
+(@pxref{Numeric Expressions}), and the input line counter register
+@code{.c} is incremented.
+
+@c Wrap example at 56 columns (on the _output_).  We use 50n in the
+@c groff input to avoid line adjustment.
+@Example
+.ll 50n
+.de I
+.  ft I
+.  nop \\$*
+.  ft
+..
+Our film class watched
+.I The Effect of Gamma Rays on Man-in-the-Moon
+Marigolds. \" whoops, the input line wrapped
+.br
+.I My own opus begins on line \n[.c] \
+and ends on line \n[.c].
+@endExample
+@Example
+    @result{} Our film class watched @i{The Effect of Gamma Rays on}
+    @result{} @i{Man-in-the-Moon} Marigolds.
+    @result{} @i{My own opus begins on line 11 and ends on line 12.}
+@endExample
+@endDefesc
+
+@DefescList {\\c, , ,}
+@DefregListEndx {.int}
+@cindex output line, continuation (@code{\c})
+@cindex line, output, continuation (@code{\c})
+@cindex continuation, output line (@code{\c})
+@cindex interrupted line
+@cindex line, interrupted
+@cindex @code{\R}, after @code{\c}
+@code{\c} continues an output line.  Nothing after it on the input line
+is formatted.  In contrast to @code{\@key{RET}}, a line after @code{\c}
+remains a new input line, so a control character is recognized at its
+beginning.  The visual results depend on whether filling is enabled; see
+@ref{Manipulating Filling and Adjustment}.
+
+@itemize @bullet
+@item
+@cindex @code{\c}, when filling enabled
+@cindex fill mode, and @code{\c}
+@cindex mode, fill, and @code{\c}
+If filling is enabled, a word interrupted with @code{\c} is continued
+with the text on the next input text line, without an intervening space.
+
+@Example
+This is a te\c
+st.
+    @result{} This is a test.
+@endExample
+
+@item
+@cindex @code{\c}, when filling disabled
+@cindex no-fill mode, and @code{\c}
+@cindex mode, no-fill, and @code{\c}
+If filling is disabled, the next input text line after @code{\c} is
+handled as a continuation of the same input text line.
+
+@Example
+.nf
+This is a \c
+test.
+    @result{} This is a test.
+@endExample
+@end itemize
+
+An intervening control line that causes a break overrides @code{\c},
+flushing out the pending output line in the usual way.
+
+@cindex interrupted line register (@code{.int})
+@cindex continued output line register (@code{.int})
+The @code{.int} register contains a positive value if the last output
+line was continued with @code{\c}; this datum is associated with the
+environment (@pxref{Environments}).@footnote{Historically, the @code{\c}
+escape sequence has proven challenging to characterize.  Some sources
+say it ``connects the next input text'' (to the input line on which it
+appears); others describe it as ``interrupting'' text, on the grounds
+that a text line is interrupted without breaking, perhaps to inject a
+request invocation or macro call.}
+@endDefesc
+
+
+@c =====================================================================
+
+@node Page Layout, Page Control, Line Continuation, GNU troff Reference
+@section Page Layout
+@cindex page layout
+@cindex layout, page
+
+The formatter permits configuration of the page length and page number.
+
+@DefreqList {pl, [@Var{length}]}
+@DefreqItem {pl, @t{+}@Var{length}}
+@DefreqItem {pl, @t{-}@Var{length}}
+@DefregListEndx {.p}
+@cindex page length, configuring (@code{pl})
+@cindex length of the page, configuring (@code{pl})
+@cindex configuring the page length (@code{pl})
+@cindex setting the page length (@code{pl})
+Change (increase or decrease) the page length per the numeric expression
+@var{length}.  The default scaling unit is @samp{v}.  A negative
+@var{length} is valid, but an uncommon application:@: it prevents page
+location traps from being sprung,@footnote{@xref{Traps}.} and each
+output line is placed on a new page.  If @var{length} is invalid, GNU
+@code{troff} emits a warning in category @samp{number}.  If @var{length}
+is absent or invalid, @samp{11i} is assumed.
+
+@cindex page length register (@code{.p})
+The read-only register @samp{.p} interpolates the current page length.
+@endDefreq
+
+@DefreqList {pn, num}
+@DefreqItem {pn, @t{+}@Var{num}}
+@DefreqItem {pn, @t{-}@Var{num}}
+@DefregListEndx {.pn}
+@cindex page number, configuring next (@code{pn})
+@cindex next page number, configuring (@code{pn})
+@cindex number, page, next, configuring (@code{pn})
+Change (increase or decrease) the page number of the @emph{next} page
+per the numeric expression @var{num}.  If @var{num} is invalid, GNU
+@code{troff} emits a warning in category @samp{number} and ignores the
+request.  Without an argument, @code{pn} is ignored.
+
+@cindex next page number register (@code{.pn})
+@cindex page number, next, register (@code{.pn})
+The read-only register @code{.pn} interpolates @var{num} if set by
+@code{pn} on the current page, or the current page number plus@tie{}1.
+@endDefreq
+
+@cindex headers
+@cindex footers
+@cindex titles
+The formatter offers special support for typesetting headers and
+footers, collectively termed @dfn{titles}.  Titles have an independent
+line length, and their placement on the page is not restricted.
+
+@Defreq {tl, @code{'}@Var{left}@code{'}@Var{center}@code{'}@Var{right}@code{'}}
+@cindex title line, formatting (@code{tl})
+@cindex formatting a title line (@code{tl})
+@cindex three-part title (@code{tl})
+@cindex page number character (@code{%})
+Format an output line as a title consisting of @var{left}, @var{center},
+and @var{right}, each aligned accordingly.  The delimiter need not be a
+neutral apostrophe: @code{tl} accepts the same delimiters as most escape
+sequences; see @ref{Delimiters}.  If not used as the delimiter, any
+@dfn{page number character} character is replaced with the current page
+number; the default is @samp{%}; see the the @code{pc} request below.
+Without an argument, @code{tl} is ignored.  @code{tl} writes the title
+line immediately, ignoring any partially collected line.
+
+It is not an error to omit delimiters after the first.  For example,
+@w{@samp{.tl /Thesis}} is interpreted as @w{@samp{.tl /Thesis///}}:@: it
+sets a title line comprising only the left-aligned word @samp{Thesis}.
+@endDefreq
+
+@DefreqList {lt, [@Var{length}]}
+@DefreqItem {lt, @t{+}@Var{length}}
+@DefreqItem {lt, @t{-}@Var{length}}
+@DefregListEndx {.lt}
+@cindex length of title line, configuring (@code{lt})
+@cindex title length, configuring (@code{lt})
+Change (increase or decrease) the line length used by titles per the
+numeric expression @var{length}.  The default scaling unit is @samp{m}.
+If @var{length} is negative, GNU emits a warning in category
+@samp{range} and treats @var{length} as @samp{0}.  If @var{length} is
+invalid, GNU @code{troff} emits a warning in category @samp{number} and
+ignores the request.  The formatter's default title length is
+@samp{6.5i}.  With no argument, the title length is restored to the
+previous value.  The title length is is associated with the environment
+(@pxref{Environments}).
+
+@cindex title line length register (@code{.lt})
+The read-only register @samp{.lt} interpolates the title line length.
+@endDefreq
+
+@Defreq {pc, [@Var{char}]}
+@cindex changing the page number character (@code{pc})
+@cindex page number character, changing (@code{pc})
+@vindex %
+Set the page number character to @var{char}.  With no argument, the page
+number character is disabled.  @code{pc} does not affect the
+register@tie{}@code{%}.
+@endDefreq
+
+The following example exercises title features.
+
+@Example
+.lt 50n
+This is my partially collected
+.tl 'Isomers 2023'%'Dextrose Edition'
+line.
+    @result{} Isomers 2023             1        Dextrose Edition
+    @result{} This is my partially collected line.
+@endExample
+
+We most often see titles used in page header and footer traps.
+@xref{Traps}.
+
+@c =====================================================================
+
+@node Page Control, Using Fonts, Page Layout, GNU troff Reference
+@section Page Control
+@cindex page control
+@cindex control, page
+
+@cindex page break
+@cindex break, page
+@cindex page ejection
+@cindex ejection, page
+Discretionary page breaks can prevent the unwanted separation of
+content.  A new page number takes effect during page ejection; see
+@ref{The Implicit Page Trap}.
+
+@DefreqList {bp, [@Var{page-number}]}
+@DefreqItem {bp, @t{+}@Var{page-number}}
+@DefreqItem {bp, @t{-}@Var{page-number}}
+@DefregListEndx {%}
+@cindex new page (@code{bp})
+@cindex page, new (@code{bp})
+Break the page and change (increase or decrease) the next page number
+per the numeric expression @var{page-number}.  If @var{page-number} is
+invalid, GNU @code{troff} emits a warning in category @samp{number} and
+ignores the argument.  This request causes a break.  A page break
+advances the vertical drawing position to the bottom of the page,
+springing traps.  @xref{Page Location Traps}.
+@cindex @code{bp} request, and top-level diversion
+@cindex top-level diversion, and @code{bp}
+@cindex diversion, top-level, and @code{bp}
+@code{bp} has effect only if invoked within the top-level
+diversion.@footnote{@xref{Diversions}.}
+@cindex CSTR@tie{}#54 errata
+@cindex CSTR@tie{}#54 erratum, @code{bp} request
+This request is incorrectly documented in the @acronym{AT&T}
+@code{troff} manual as having a default scaling unit of @samp{v}.
+
+@cindex page number register (@code{%})
+@cindex current page number (@code{%})
+The register @code{%} interpolates the current page number.
+
+@Example
+.de BP
+'  bp \" schedule page break once current line is output
+..
+@endExample
+@endDefreq
+
+@Defreq {ne, [@Var{space}]}
+@cindex orphan lines, preventing with @code{ne}
+@cindex conditional page break (@code{ne})
+@cindex page break, conditional (@code{ne})
+Force a page break if insufficient vertical space is available (assert
+``needed'' space).  @code{ne} tests the distance to the next page
+location trap; see @ref{Page Location Traps}, and breaks the page if
+that amount is less than @var{space}.  The default scaling unit is
+@samp{v}.  If @var{space} is invalid, GNU @code{troff} emits a warning
+in category @samp{number} and ignores the argument.  If @var{space} is
+not specified, @samp{1v} is assumed.
+
+@cindex widow
+We can require space for at least the first two output lines of a
+paragraph, preventing its first line from being @slanted{widowed} at the
+page bottom.
+
+@Example
+.ne 2v
+Considering how common illness is,
+how tremendous the spiritual change that it brings,
+how astonishing,
+when the lights of health go down,
+the undiscovered countries that are then disclosed,
+what wastes and deserts of the soul a slight attack
+of influenza brings to view,
+@c -- Virgina Woolf, "On Being Ill", 1926
+@endExample
+
+@c XXX: Some of this might be better placed in a revised Chapter 3.
+This method is reliable only if no output line is pending when @code{ne}
+is invoked.  When macro packages are used, this is often not the case:@:
+their paragraphing macros perform the break.  You may need to experiment
+with placing the @code{ne} after the paragraphing macro, or @code{br}
+and @code{ne} before it.
+
+@cindex orphan
+@cindex widow
+@code{ne} is also useful to force grouping of section headings with
+their subsequent paragraphs, or tables with their captions and/or
+explanations.  Macro packages often use @code{ne} with diversions to
+implement keeps and displays; see @ref{Diversions}.  They may also offer
+parameters for widow and orphan management.
+@endDefreq
+
+@DefreqList {sv, [@Var{space}]}
+@DefreqListEndx {os, }
+@cindex @code{ne} request, comparison with @code{sv}
+Require vertical space as @code{ne} does, but also @slanted{save} it for
+later output by the @code{os} request.  If @var{space} is available
+before the next page location trap, it is output immediately.  Both
+requests ignore a partially collected line, taking effect at the next
+break.
+@cindex @code{sv} request, and no-space mode
+@cindex @code{os} request, and no-space mode
+@code{sv} and @code{os} ignore no-space mode (recall @ref{Manipulating
+Spacing}).  While the @code{sv} request allows negative values for
+@var{space}, @code{os} ignores them.  The default scaling unit is
+@samp{v}.  If @var{space} is not specified, @samp{1v} is assumed.
+@endDefreq
+
+@Defreg {nl}
+@cindex vertical drawing position (@code{nl})
+@cindex vertical position, drawing (@code{nl})
+@cindex drawing position, vertical (@code{nl})
+@c TODO: We should talk somewhere prior to this point about how the
+@c formatter doesn't start a page until it has to.
+@code{nl} interpolates or sets the vertical drawing position.  When the
+formatter starts, the first page transition hasn't happened yet, and
+@code{nl} is negative.  If a header trap has been planted on the page
+(typically at vertical position @code{0}), you can assign a negative
+value to @code{nl} to spring it if that page has already started
+(@pxref{Page Location Traps}).
+
+@Example
+.de HD
+.  sp
+.  tl ''Goldbach Solution''
+.  sp
+..
+.
+First page.
+.bp
+.wh 0 HD \" plant header trap at top of page
+.nr nl (-1)
+Second page.
+    @result{} First page.
+    @result{}
+    @result{} @r{@i{(blank lines elided)}}
+    @result{}
+    @result{}                         Goldbach Solution
+    @result{}
+    @result{} @r{@i{(blank lines elided)}}
+    @result{}
+    @result{} Second page.
+@endExample
+
+@noindent
+Without resetting @code{nl} to a negative value, the trap just planted
+would be active beginning with the @emph{next} page, not the current
+one.
+
+@xref{Diversions}, for a comparison of @code{nl} with the @code{.h} and
+@code{.d} registers.
+@endDefreg
+
+
+@c =====================================================================
+
+@c BEGIN Keep (roughly) parallel with section "Using fonts" of groff(7).
+@node Using Fonts, Manipulating Type Size and Vertical Spacing, Page Control, GNU troff Reference
+@section Using Fonts
+@cindex font
+
+@cindex typeface
+@cindex font family
+@cindex font style
+@cindex style, font
+@cindex family, font
+@cindex text font
+@cindex special font
+@cindex unstyled font
+@cindex font, text
+@cindex font, special
+@cindex font, unstyled
+In digital typography, a @dfn{font} is a collection of characters in a
+specific typeface that a device can render as glyphs at a desired
+size.@footnote{Terminals and some output devices have fonts that render
+at only one or two sizes.  As examples of the latter, take the
+@code{groff} @code{lj4} device's Lineprinter, and @code{lbp}'s Courier
+and Elite faces.}  A @code{roff} formatter can change typefaces at any
+point in the text.  The basic faces are a set of @dfn{styles} combining
+upright and slanted shapes with normal and heavy stroke weights:
+@samp{R}, @samp{I}, @samp{B}, and @samp{BI}---these stand for
+@slanted{roman}, @slanted{italic}, @slanted{bold}, and
+@slanted{bold-italic}.  For linguistic text, GNU @code{troff} groups
+typefaces into @dfn{families} containing each of these
+styles.@footnote{Font designers prepare families such that the styles
+share esthetic properties.}  A @dfn{text font} is thus often a family
+combined with a style, but it need not be:@: consider the @code{ps} and
+@code{pdf} devices' @code{ZCMI} (Zapf Chancery Medium italic)---often,
+no other style of Zapf Chancery Medium is provided.  On typesetting
+devices, at least one @dfn{special font} is available, comprising
+@dfn{unstyled} glyphs for mathematical operators and other purposes.
+
+@cindex font description file
+@cindex description file, font
+@cindex file, font description
+@cindex font metrics
+@cindex metrics, font
+@cindex mounting position
+@cindex mounting position
+@cindex position, mounting
+Like @acronym{AT&T} @code{troff}, GNU @code{troff} does not itself load
+or manipulate a digital font file;@footnote{Historically, the fonts
+@code{troff}s dealt with were not Free Software or, as with the Graphic
+Systems C/A/T, did not even exist in the digital domain.} instead it
+works with a @dfn{font description file} that characterizes it,
+including its glyph repertoire and the @dfn{metrics} (dimensions) of
+each glyph.@footnote{@xref{Font Description File Format}.}  This
+information permits the formatter to accurately place glyphs with
+respect to each other.  Before using a font description, the formatter
+associates it with a @dfn{mounting position}, a place in an ordered list
+of available typefaces.
+@cindex abstract font style
+@cindex font style, abstract
+@cindex style, font, abstract
+So that a document need not be strongly coupled to a specific font
+family, in GNU @code{troff} an output device can associate a style in
+the abstract sense with a mounting position.  Thus the default family
+can be combined with a style dynamically, producing a @dfn{resolved font
+name}.
+
+Fonts often have trademarked names, and even Free Software fonts can
+require renaming upon modification.  @code{groff} maintains a
+convention that a device's serif font family is given the name @samp{T}
+(``Times''), its sans-serif family @samp{H} (``Helvetica''), and its
+monospaced family @samp{C} (``Courier'').  Historical inertia has driven
+@code{groff}'s font identifiers to short uppercase abbreviations of font
+names, as with @samp{TR}, @samp{TI}, @samp{TB}, @samp{TBI}, and a
+special font @samp{S}.
+
+The default family used with abstract styles can be changed at any time;
+initially, it is @samp{T}.  Typically, abstract styles are arranged in
+the first four mounting positions in the order shown above.  The default
+mounting position, and therefore style, is always @samp{1} (@samp{R}).
+By issuing appropriate formatter instructions, you can override these
+defaults before your document writes its first glyph.
+
+@cindex graphic renditions
+@cindex renditions, graphic
+@cindex character cell attributes
+@cindex attributes, character cell
+@cindex cell, character, attributes
+Terminal output devices cannot change font families and lack special
+fonts.  They support style changes by overstriking, or by altering
+ISO@tie{}6429/ECMA-48 @dfn{graphic renditions} (character cell
+attributes).
+@c END Keep (roughly) parallel with section "Using fonts" of groff(7).
+
+@menu
+* Selecting Fonts::
+* Font Families::
+* Font Positions::
+* Using Symbols::
+* Character Classes::
+* Special Fonts::
+* Artificial Fonts::
+* Ligatures and Kerning::
+* Italic Corrections::
+* Dummy Characters::
+@end menu
+
+@c ---------------------------------------------------------------------
+
+@node Selecting Fonts, Font Families, Using Fonts, Using Fonts
+@subsection Selecting Fonts
+@cindex font, selection
+
+We use @dfn{font} to refer to any of several means of identifying a
+font: by mounting position (@samp{3}), by abstract style (@samp{B}), or
+by its identifier (@samp{TB}).
+
+@DefreqList {ft, [@Var{font}]}
+@DefescItemx {\\f, , f, }
+@DefescItem {\\f, (, fn, }
+@DefescItem {\\f, [, font, ]}
+@DefregListEndx {.fn}
+@cindex changing fonts (@code{ft}, @code{\f})
+@cindex fonts, changing (@code{ft}, @code{\f})
+@cindex @code{sty} request, and changing fonts
+@cindex @code{fam} request, and changing fonts
+@cindex @code{\F}, and changing fonts
+@kindex styles
+@kindex family
+@pindex DESC
+@cindex selecting the previous font (@code{ft})
+@cindex previous font, selecting (@code{ft})
+@cindex font, previous, slecting (@code{ft})
+The @code{ft} request selects the typeface @var{font}.  If the argument
+is absent or @samp{P}, it selects the previously chosen font.  If
+@var{font} is a non-negative integer, it is interpreted as mounting
+position; the font mounted there is selected.  If that position refers
+to an abstract style, it is combined with the default family (see
+@code{fam} and @code{\F} below) to make a resolved font name.  If the
+mounting position is not a style and no font is mounted there, GNU
+@code{troff} emits a warning in category @samp{font} and ignores the
+request.
+
+If @var{font} matches a style name, it is combined with the current
+family to make a resolved font name.  Otherwise, @var{font} is assumed
+to already be a resolved font name.
+
+@cindex automatic font mounting
+@cindex font mounting, automatic
+@cindex mounting, font, automatic
+The resolved font name is subject to translation (see request @code{ftr}
+below).  Next, the (possibly translated) font name's mounting position
+is looked up; if not mounted, @var{font} is sought on the file system as
+a font description file and, if located, automatically mounted at the
+next available position (see register @code{.fp} below).  If the font
+was mounted using an identifier different from its font description file
+name (see request @code{fp} below), that file name is then looked up.
+If a font description file for the resolved font name is not found, GNU
+@code{troff} emits a warning in category @samp{font} and ignores the
+request.
+
+The @code{\f} escape sequence is similar, using one-character name (or
+mounting position) @var{f}, two-character name @var{fn}, or a name
+@var{font} of arbitrary length.
+@cindex previous font, selecting (@code{\f[]}, @code{\fP})
+@cindex font, previous, selecting (@code{\f[]}, @code{\fP})
+@samp{\f[]} selects the previous font.  The syntax form @samp{\fP} is
+supported for backward compatibility, and @samp{\f[P]} for consistency.
+
+@Example
+eggs, bacon,
+.ft I
+spam,
+.ft
+and sausage.
+.br
+eggs, bacon, \fIspam,\fP and sausage.
+    @result{} eggs, bacon, @slanted{spam,} and sausage
+    @result{} eggs, bacon, @slanted{spam,} and sausage
+@endExample
+
+The current and previously selected fonts are properties of the
+environment (@pxref{Environments}).
+
+The read-only string-valued register @code{.fn} contains the resolved
+font name of the selected font.
+
+@code{\f} doesn't produce an input token in GNU @code{troff}; it thus
+can be used in requests that expect a single-character argument.  We can
+assign a font to a margin character as follows (@pxref{Miscellaneous}).
+
+@Example
+.mc \f[I]x\f[]
+@endExample
+@endDefreq
+
+@Defreq {ftr, f [@Var{g}]}
+@cindex font translation (@code{ftr})
+@cindex @code{ft} request, and font translations
+@cindex @code{ul} request, and font translations
+@cindex @code{bd} request, and font translations
+@cindex @code{\f}, and font translations
+@cindex @code{cs} request, and font translations
+@cindex @code{tkf} request, and font translations
+@cindex @code{special} request, and font translations
+@cindex @code{fspecial} request, and font translations
+@cindex @code{fp} request, and font translations
+@cindex @code{sty} request, and font translations
+@cindex @code{if} request, and font translations
+@cindex @code{ie} request, and font translations
+@cindex @code{while} request, and font translations
+Translate font@tie{}@var{f} to font@tie{}@var{g}.  Whenever a font
+named@tie{}@var{f} is referred to in a @code{\f} escape sequence, in the
+@code{F} and @code{S} conditional operators, or in the @code{ft},
+@code{ul}, @code{bd}, @code{cs}, @code{tkf}, @code{special},
+@code{fspecial}, @code{fp}, or @code{sty} requests, font@tie{}@var{g} is
+used.  If @var{g} is missing or equal to@tie{}@var{f} the translation is
+undone.
+@c XXX: Do font translations work on mounting positions?  Abstract
+@c styles?
+
+Font translations cannot be chained.
+
+@Example
+.ftr XXX TR
+.ftr XXX YYY
+.ft XXX
+    @error{} warning: can't find font 'XXX'
+@endExample
+@endDefreq
+
+@DefreqList {fzoom, f [@Var{zoom}]}
+@DefregListEndx {.zoom}
+@cindex magnification of a font (@code{fzoom})
+@cindex font, magnification (@code{fzoom})
+@cindex zoom factor of a font (@code{fzoom})
+@cindex factor, zoom, of a font (@code{fzoom})
+@cindex font, zoom factor (@code{fzoom})
+@cindex optical size of a font
+@cindex font, optical size
+@cindex size, optical, of a font
+Set magnification of font@tie{}@var{f} to factor @var{zoom}, which must
+be a non-negative integer multiple of 1/1000th.  This request is useful
+to adjust the optical size of a font in relation to the others.  In the
+example below, font @code{CR} is magnified by 10% (the zoom factor is
+thus 1.1).
+
+@Example
+.fam P
+.fzoom CR 1100
+.ps 12
+Palatino and \f[CR]Courier\f[]
+@endExample
+
+A missing or zero value of @var{zoom} is the same as a value of 1000,
+which means no magnification.  @var{f}@tie{}must be a resolved font
+name, not an abstract style.
+@c XXX: What about a mounting position?  It's not rejected...
+
+The magnification of a font is completely transparent to GNU
+@code{troff}; a change of the zoom factor doesn't cause any effect
+except that the dimensions of glyphs, (word) spaces, kerns, etc., of the
+affected font are adjusted accordingly.
+
+The zoom factor of the current font is available in the read-only
+register @samp{.zoom}, in multiples of 1/1000th.  It returns zero if
+there is no magnification.
+@endDefreq
+
+@c ---------------------------------------------------------------------
+
+@node Font Families, Font Positions, Selecting Fonts, Using Fonts
+@subsection Font Families
+@cindex font families
+@cindex families, font
+@cindex font styles
+@cindex styles, font
+
+To accommodate the wide variety of fonts available, GNU @code{troff}
+distinguishes @dfn{font families} and @dfn{font styles}.  A resolved
+font name is the catenation of a font family and a style.  Selecting an
+abstract style causes GNU @code{troff} to combine it with the default
+font family.
+
+You can thus compose a document using abstract styles exclusively for
+its body or running text, selecting a specific family only for titles or
+examples, for instance, and change the default family on the command
+line (recall @ref{Groff Options}).
+
+Fonts for the devices @code{ps}, @code{pdf}, @code{dvi}, @code{lj4},
+@code{lbp}, and the X11 devices support this mechanism.  By default,
+GNU @code{troff} uses the Times family with the four styles @samp{R},
+@samp{I}, @samp{B}, and @samp{BI}.
+
+@DefreqList {fam, [@Var{family}]}
+@DefregItemx {.fam}
+@DefescItemx {\\F, , f, }
+@DefescItem {\\F, (, fm, }
+@DefescListEnd {\\F, [, family, ]}
+@cindex changing font family (@code{fam}, @code{\F})
+@cindex font family, changing (@code{fam}, @code{\F})
+Set the default font family, used in combination with abstract styles to
+construct a resolved font name, to @var{family} (one-character
+name@tie{}@var{f}, two-character name @var{fm}).  If no argument is
+given, GNU @code{troff} selects the previous font family; if there none,
+is it falls back to the device's default@footnote{@xref{DESC File
+Format}.} or its own (@samp{T}).
+
+The @code{\F} escape sequence works similarly.  In disanalogy to
+@code{\f}, @samp{\FP} makes @samp{P} the default family.  Use
+@samp{\F[]} to select the previous default family.  The default font
+family is available in the read-only string-valued register @code{.fam};
+it is associated with the environment (@pxref{Environments}).
+
+@Example
+spam,     \" startup defaults are T (Times) R (roman)
+.fam H    \" make Helvetica the default family
+spam,     \" family H + style R = HR
+.ft B     \" family H + style B = HB
+spam,
+.ft CR    \" Courier roman (default family not changed)
+spam,
+.ft       \" back to Helvetica bold
+spam,
+.fam T    \" make Times the default family
+spam,     \" family T + style B = TB
+.ft AR    \" font AR (not a style)
+baked beans,
+.ft R     \" family T + style R = TR
+and spam.
+@endExample
+
+@code{\F} doesn't produce an input token in GNU @code{troff}.  As a
+consequence, it can be used in requests like @code{mc} (which expects
+a single character as an argument) to change the font family on the fly.
+
+@Example
+.mc \F[P]x\F[]
+@endExample
+@endDefreq
+
+@need 1000
+@DefreqList {sty, n style}
+@DefregListEndx {.sty}
+@cindex setting up an abstract font style (@code{sty})
+@cindex abstract font style, setting up (@code{sty})
+@cindex font style, abstract, setting up (@code{sty})
+@cindex style, font, abstract, setting up (@code{sty})
+@cindex @code{cs} request, and font styles
+@cindex @code{bd} request, and font styles
+@cindex @code{tkf} request, and font styles
+@cindex @code{uf} request, and font styles
+@cindex @code{fspecial} request, and font styles
+Associate an abstract style @var{style} with mounting
+position@tie{}@var{n}, which must be a non-negative integer.  If the
+requests @code{cs}, @code{bd}, @code{tkf}, @code{uf}, or @code{fspecial}
+are applied to an abstract style, they are instead applied to the member
+of the current family corresponding to that style.
+
+@pindex DESC
+@kindex styles
+The default family can be set with the @option{-f} option (@pxref{Groff
+Options}).  The @code{styles} command in the @file{DESC} file controls
+which font positions (if any) are initially associated with abstract
+styles rather than fonts.
+
+@strong{Caution:@:} The @var{style} argument is not validated.
+@c XXX: This would be a really good thing to fix.
+Errors may occur later, when the formatter attempts to construct a
+resolved font name, or format a character for output.
+
+@Example
+.nr BarPos \n[.fp]
+.sty \n[.fp] Bar
+.fam Foo
+.ft \n[BarPos]
+.tm .f=\n[.f]
+A
+    @error{} error: no font family named 'Foo' exists
+    @error{} .f=41
+    @error{} error: cannot format glyph: no current font
+@endExample
+
+When an abstract style has been selected, the read-only string-valued
+register @samp{.sty} interpolates its name; this datum is associated
+with the environment (@pxref{Environments}).  Otherwise, @samp{.sty}
+interpolates nothing.
+@endDefreq
+
+@c ---------------------------------------------------------------------
+
+@node Font Positions, Using Symbols, Font Families, Using Fonts
+@subsection Font Positions
+@cindex font positions
+@cindex positions, font
+
+To support typeface indirection through abstract styles, and for
+compatibility with @acronym{AT&T} @code{troff}, the formatter maintains
+a list of font @dfn{positions} at which fonts required by a document are
+@dfn{mounted}.  An output device's description file @file{DESC}
+typically configures a set of pre-mounted fonts; see @ref{Device and
+Font Description Files}.  A font need not be explicitly mounted before
+it is selected; GNU @code{troff} will search @env{GROFF_FONT_PATH} for
+it by name and mount it at the first free mounting position on demand.
+
+@need 500
+@DefreqList {fp, pos id [@Var{font-description-file-name}]}
+@DefregItemx {.f}
+@DefregListEndx {.fp}
+@cindex mounting a font (@code{fp})
+@cindex font, mounting (@code{fp})
+Mount a font under the name @var{id} at mounting position @var{pos}, a
+non-negative integer.  When the formatter starts up, it reads the output
+device's description to mount an initial set of faces, and selects font
+position@tie{}1.  Position@tie{}0 is unused by default.  Unless the
+@var{font-description-file-name} argument is given, @var{id} should be
+the name of a font description file stored in a directory corresponding
+to the selected output device.  GNU @code{troff} does not traverse
+directories to locate the font description file.
+
+@c The third argument was a late revision to device-independent troff.
+@c It wasn't in the "Unix 4.0" version of CSTR #54 (January 1981), which
+@c featured Kernighan's device-independent rewrite, but appeared by the
+@c time of its 1992 revision.
+@cindex font aliasing with third argument to @code{fp} request
+@cindex aliasing fonts with third argument to @code{fp} request
+The optional third argument enables font names to be aliased, which can
+be necessary in compatibility mode since AT&T @code{troff} syntax
+affords no means of identifying fonts with names longer than two
+characters, like @samp{TBI} or @samp{ZCMI}, in a font selection escape
+sequence.  @xref{Compatibility Mode}.  You can also alias fonts on
+mounting for convenience or abstraction.  (See below regarding the
+@code{.fp} register.)
+
+@Example
+.fp \n[.fp] SC ZCMI
+Send a \f(SChand-written\fP thank-you note.
+.fp \n[.fp] Emph TI
+.fp \n[.fp] Strong TB
+Are \f[Emph]these names\f[] \f[Strong]comfortable\f[]?
+@endExample
+
+@samp{DESC}, @samp{P}, and non-negative integers are not usable as font
+identifiers.
+@c XXX: TODO: Catch the DESC case earlier and throw an error for it.
+@c XXX: This identifier could be used as a style name, but no one's
+@c exercised this freedom in 30+ years, and we should consider
+@c prohibiting it.  --GBR
+
+@cindex font position register (@code{.f})
+The position of the currently selected font (or abstract style) is
+available in the read-only register @samp{.f}.  It is associated with
+the environment (@pxref{Environments}).
+
+You can copy the value of @code{.f} to another register to save it for
+later use.
+
+@Example
+.nr saved-font \n[.f]
+@r{@dots{} @i{text involving many font changes} @dots{}}
+.ft \n[saved-font]
+@endExample
+
+@cindex next free font position register (@code{.fp})
+The index of the next (non-zero) free font position is available in the
+read-only register @samp{.fp}.
+@cindex @file{DESC} file, and font mounting
+Fonts not listed in the @file{DESC} file are automatically mounted at
+position @samp{\n[.fp]} when selected with the @code{ft} request or
+@code{\f} escape sequence.  When mounting a font at a position
+explicitly with the @code{fp} request, this same practice should be
+followed, although GNU @code{troff} does not enforce this strictly.
+@endDefreq
+
+@c ---------------------------------------------------------------------
+
+@node Using Symbols, Character Classes, Font Positions, Using Fonts
+@subsection Using Symbols
+@cindex using symbols
+@cindex symbols, using
+
+@cindex glyph
+@cindex character
+@cindex glyph, distinguished from character
+@cindex character, distinguished from glyph
+@cindex ligature
+A @dfn{glyph} is a graphical representation of a @dfn{character}.  While
+a character is an abstraction of semantic information, a glyph is
+something that can be seen on screen or paper.  A character has many
+possible representation forms (for example, the character `A' can be
+written in an upright or slanted typeface, producing distinct
+glyphs).  Sometimes, a sequence of characters map to a single glyph:@:
+this is a @dfn{ligature}---the most common is `fi'.
+
+Space characters never become glyphs in GNU @code{troff}.  If not
+discarded (as when trailing on text lines), they are represented by
+horizontal motions in the output.
+
+@cindex symbol
+@cindex special fonts
+@kindex fonts
+@pindex DESC
+@cindex @code{special} request, and glyph search order
+@cindex @code{fspecial} request, and glyph search order
+A @dfn{symbol} is simply a named glyph.  Within @code{gtroff}, all glyph
+names of a particular font are defined in its font file.  If the user
+requests a glyph not available in this font, @code{gtroff} looks up an
+ordered list of @dfn{special fonts}.  By default, the PostScript output
+device supports the two special fonts @samp{SS} (slanted symbols) and
+@samp{S} (symbols) (the former is looked up before the latter).  Other
+output devices use different names for special fonts.  Fonts mounted
+with the @code{fonts} keyword in the @file{DESC} file are globally
+available.  To install additional special fonts locally (i.e., for a
+particular font), use the @code{fspecial} request.
+
+Here are the exact rules how @code{gtroff} searches a given symbol:
+
+@itemize @bullet
+@item
+If the symbol has been defined with the @code{char} request, use it.
+This hides a symbol with the same name in the current font.
+
+@item
+Check the current font.
+
+@item
+If the symbol has been defined with the @code{fchar} request, use it.
+
+@item
+Check whether the current font has a font-specific list of special
+fonts; test all fonts in the order of appearance in the last
+@code{fspecial} call if appropriate.
+
+@item
+If the symbol has been defined with the @code{fschar} request for the
+current font, use it.
+
+@item
+Check all fonts in the order of appearance in the last @code{special}
+call.
+
+@item
+If the symbol has been defined with the @code{schar} request, use it.
+
+@item
+As a last resort, consult all fonts loaded up to now for special fonts
+and check them, starting with the lowest font number.  This can
+sometimes lead to surprising results since the @code{fonts} line in
+the @file{DESC} file often contains empty positions, which are filled
+later on.  For example, consider the following:
+
+@Example
+fonts 3 0 0 FOO
+@endExample
+
+@noindent
+This mounts font @code{foo} at font position@tie{}3.  We assume that
+@code{FOO} is a special font, containing glyph @code{foo}, and that no
+font has been loaded yet.  The line
+
+@Example
+.fspecial BAR BAZ
+@endExample
+
+@noindent
+makes font @code{BAZ} special only if font @code{BAR} is active.  We
+further assume that @code{BAZ} is really a special font, i.e., the font
+description file contains the @code{special} keyword, and that it also
+contains glyph @code{foo} with a special shape fitting to font
+@code{BAR}.  After executing @code{fspecial}, font @code{BAR} is loaded
+at font position@tie{}1, and @code{BAZ} at position@tie{}2.
+
+We now switch to a new font @code{XXX}, trying to access glyph
+@code{foo} that is assumed to be missing.  There are neither
+font-specific special fonts for @code{XXX} nor any other fonts made
+special with the @code{special} request, so @code{gtroff} starts the
+search for special fonts in the list of already mounted fonts, with
+increasing font positions.  Consequently, it finds @code{BAZ} before
+@code{FOO} even for @code{XXX}, which is not the intended behaviour.
+@end itemize
+
+@xref{Device and Font Description Files}, and @ref{Special Fonts}, for
+more details.
+
+@cindex list of special characters (@cite{groff_char@r{(7)}} man page)
+@cindex special characters, list of (@cite{groff_char@r{(7)}} man page)
+@cindex characters, special, list of (@cite{groff_char@r{(7)}} man page)
+@cindex available glyphs, list of (@cite{groff_char@r{(7)}} man page)
+@cindex glyphs, available, list of (@cite{groff_char@r{(7)}} man page)
+The @cite{groff_char@r{(7)}} man page houses a complete list of
+predefined special character names, but the availability of any as a
+glyph is device- and font-dependent.  For example, say
+
+@Example
+man -Tdvi groff_char > groff_char.dvi
+@endExample
+
+@noindent
+to obtain those available with the DVI device and default font
+configuration.@footnote{Not all versions of the @code{man} program
+support the @option{-T} option; use the subsequent example for an
+alternative.}  If you want to use an additional macro package to change
+the fonts used, @code{groff} (or @code{gtroff}) must be run directly.
+
+@Example
+groff -Tdvi -mec -man groff_char.7 > groff_char.dvi
+@endExample
+
+@cindex composite glyph names
+@cindex glyph names, composite
+@cindex @code{groff} glyph list (GGL)
+@cindex GGL (@code{groff} glyph list)
+@cindex Adobe Glyph List (AGL)
+Special character names not listed in @cite{groff_char@r{(7)}} are
+derived algorithmically, using a simplified version of the Adobe Glyph
+List (AGL) algorithm, which is described in
+@uref{https://github.com@//adobe-type-tools@//agl-aglfn}.  The (frozen)
+set of names that can't be derived algorithmically is called the
+@dfn{@code{groff} glyph list (GGL)}.
+
+@itemize @bullet
+@item
+A glyph for Unicode character U+@var{XXXX}[@var{X}[@var{X}]], which is
+not a composite character is named
+@code{u@var{XXXX}@r{[}@var{X}@r{[}@var{X}@r{]]}}.  @var{X} must be an
+uppercase hexadecimal digit.  Examples: @code{u1234}, @code{u008E},
+@code{u12DB8}.  The largest Unicode value is 0x10FFFF.  There must be at
+least four @code{X} digits; if necessary, add leading zeroes (after the
+@samp{u}).  No zero padding is allowed for character codes greater than
+0xFFFF.  Surrogates (i.e., Unicode values greater than 0xFFFF
+represented with character codes from the surrogate area U+D800-U+DFFF)
+are not allowed either.
+
+@item
+A glyph representing more than a single input character is named
+
+@display
+@samp{u} @var{component1} @samp{_} @var{component2} @samp{_} @var{component3} @dots{}
+@end display
+
+@noindent
+Example: @code{u0045_0302_0301}.
+
+For simplicity, all Unicode characters that are composites must be
+maximally decomposed to NFD;@footnote{This is ``Normalization Form D''
+as documented in Unicode Standard Annex #15
+(@uref{https://unicode.org@//reports@//tr15/}).} for example,
+@code{u00CA_0301} is not a valid glyph name since U+00CA (@sc{latin
+capital letter e with circumflex}) can be further decomposed into U+0045
+(@sc{latin capital letter e}) and U+0302 (@sc{combining circumflex
+accent}).  @code{u0045_0302_0301} is thus the glyph name for U+1EBE,
+@sc{latin capital letter e with circumflex and acute}.
+
+@item
+groff maintains a table to decompose all algorithmically derived glyph
+names that are composites itself.  For example, @code{u0100} (@sc{latin
+letter a with macron}) is automatically decomposed into
+@code{u0041_0304}.  Additionally, a glyph name of the GGL is preferred
+to an algorithmically derived glyph name; @code{groff} also
+automatically does the mapping.  Example: The glyph @code{u0045_0302} is
+mapped to @code{^E}.
+
+@item
+glyph names of the GGL can't be used in composite glyph names; for
+example, @code{^E_u0301} is invalid.
+@end itemize
+
+@DefescList {\\, (, nm, }
+@DefescItem {\\, [, name, ]}
+@DefescListEnd {\\, [, base-glyph combining-component @dots{}, ]}
+@esindex \(
+@esindex \[
+Typeset a special character @var{name} (two-character name @var{nm}) or
+a composite glyph consisting of @var{base-glyph} overlaid with one or
+more @var{combining-component}s.  For example, @samp{\[A ho]} is a
+capital letter ``A'' with a ``hook accent'' (ogonek).
+
+There is no special syntax for one-character names---the analogous form
+@samp{\@var{n}} would collide with other escape sequences.  However, the
+four escape sequences @code{\'}, @code{\-}, @code{\_}, and @code{\`},
+are translated on input to the special character escape sequences
+@code{\[aa]}, @code{\[-]}, @code{\[ul]}, and @code{\[ga]}, respectively.
+
+A special character name of length one is not the same thing as an
+ordinary character: that is, the character @code{a} is not the same as
+@code{\[a]}.
+
+If @var{name} is undefined, a warning in category @samp{char} is
+produced and the escape is ignored.  @xref{Warnings}, for information
+about the enablement and suppression of warnings.
+
+GNU @code{troff} resolves @code{\[@r{@dots{}}]} with more than a single
+component as follows:
+
+@itemize @bullet
+@item
+Any component that is found in the GGL is converted to the
+@code{u@var{XXXX}} form.
+
+@item
+Any component @code{u@var{XXXX}} that is found in the list of
+decomposable glyphs is decomposed.
+
+@item
+The resulting elements are then concatenated with @samp{_} in between,
+dropping the leading @samp{u} in all elements but the first.
+@end itemize
+
+No check for the existence of any component (similar to @code{tr}
+request) is done.
+
+Examples:
+
+@table @code
+@item \[A ho]
+@samp{A} maps to @code{u0041}, @samp{ho} maps to @code{u02DB}, thus the
+final glyph name would be @code{u0041_02DB}.  This is not the expected
+result:@: the ogonek glyph @samp{ho} is a spacing ogonek, but for a
+proper composite a non-spacing ogonek (U+0328) is necessary.  Looking
+into the file @file{composite.tmac}, one can find @w{@samp{.composite ho
+u0328}}, which changes the mapping of @samp{ho} while a composite glyph
+name is constructed, causing the final glyph name to be
+@code{u0041_0328}.
+
+@item \[^E u0301]
+@itemx \[^E aa]
+@itemx \[E a^ aa]
+@itemx \[E ^ @code{'}]
+@samp{^E} maps to @code{u0045_0302}, thus the final glyph name is
+@code{u0045_0302_0301} in all forms (assuming proper calls of the
+@code{composite} request).
+@end table
+
+It is not possible to define glyphs with names like @w{@samp{A ho}}
+within a @code{groff} font file.  This is not really a limitation;
+instead, you have to define @code{u0041_0328}.
+@endDefesc
+
+@Defesc {\\C, @code{'}, xxx, @code{'}}
+@cindex named character (@code{\C})
+@cindex character, named (@code{\C})
+Typeset the glyph of the special character @var{xxx}.  Normally, it is
+more convenient to use @code{\[@var{xxx}]}, but @code{\C} has some
+advantages: it is compatible with @acronym{AT&T} device-independent
+@code{troff} (and therefore available in compatibility
+mode@footnote{@xref{Compatibility Mode}.}) and can interpolate special
+characters with @samp{]} in their names.  The delimiter need not be
+a neutral apostrophe; see @ref{Delimiters}.
+@endDefesc
+
+@Defreq {composite, id1 id2}
+@pindex composite.tmac
+Map special character name @var{id1} to @var{id2} if @var{id1} is used
+in @code{\[...]} with more than one component.  See above for examples.
+This is a strict rewriting of the special character name; no check is
+performed for the existence of a glyph for either.  A set of default
+mappings for many accents can be found in the file
+@file{composite.tmac}, loaded by the default @file{troffrc} at startup.
+@endDefreq
+
+@Defesc {\\N, @code{'}, n, @code{'}}
+@cindex numbered glyph (@code{\N})
+@cindex glyph, numbered (@code{\N})
+@cindex @code{char} request, used with @code{\N}
+@cindex Unicode
+Typeset the glyph with code@tie{}@var{n} in the current font
+(@code{n}@tie{}is @emph{not} the input character code).  The number
+@var{n}@tie{}can be any non-negative decimal integer.  Most devices only
+have glyphs with codes between 0 and@tie{}255; the Unicode output device
+uses codes in the range 0--65535.  If the current font does not contain
+a glyph with that code, special fonts are @emph{not} searched.  The
+@code{\N} escape sequence can be conveniently used in conjunction with
+the @code{char} request:
+
+@Example
+.char \[phone] \f[ZD]\N'37'
+@endExample
+
+@noindent
+@pindex DESC
+@cindex unnamed glyphs
+@cindex glyphs, unnamed
+The code of each glyph is given in the fourth column in the font
+description file after the @code{charset} command.  It is possible to
+include unnamed glyphs in the font description file by using a name of
+@samp{---}; the @code{\N} escape sequence is the only way to use these.
+
+No kerning is applied to glyphs accessed with @code{\N}.  The delimiter
+need not be a neutral apostrophe; see @ref{Delimiters}.
+@endDefesc
+
+A few escape sequences are also special characters.
+
+@Defesc {\@code{'}, , , }
+An escaped neutral apostrophe is a synonym for @code{\[aa]} (acute
+accent).
+@endDefesc
+
+@Defesc {\@code{`}, , , }
+An escaped grave accent is a synonym for @code{\[ga]} (grave accent).
+@endDefesc
+
+@Defesc {\\-, , , }
+An escaped hyphen-minus is a synonym for @code{\[-]} (minus sign).
+@endDefesc
+
+@Defesc {\\_, , , }
+An escaped underscore (``low line'') is a synonym for @code{\[ul]}
+(underrule).  On typesetting devices, the underrule is font-invariant
+and drawn lower than the underscore @samp{_}.
+@endDefesc
+
+@Defreq {cflags, n c1 c2 @dots{}}
+@cindex glyph properties (@code{cflags})
+@cindex character properties (@code{cflags})
+@cindex properties of glyphs (@code{cflags})
+@cindex properties of characters (@code{cflags})
+Assign properties encoded by the number @var{n} to characters @var{c1},
+@var{c2}, and so on.
+
+Input characters, including special characters introduced by an escape,
+have certain properties associated with them.@footnote{Output glyphs
+don't---to GNU @code{troff}, a glyph is simply a box with an index into
+a font, a given height above and depth below the baseline, and a width.}
+These properties can be modified with this request.  The first argument
+is the sum of the desired flags and the remaining arguments are the
+characters to be assigned those properties.  Spaces between the @var{cn}
+arguments are optional.  Any argument @var{cn} can be a character class
+defined with the @code{class} request rather than an individual
+character.  @xref{Character Classes}.
+
+The non-negative integer @var{n} is the sum of any of the following.
+Some combinations are nonsensical, such as @samp{33} (1 + 32).
+
+@table @code
+@item 1
+@cindex end-of-sentence characters
+@cindex characters, end-of-sentence
+Recognize the character as ending a sentence if followed by a newline
+or two spaces.  Initially, characters @samp{.?!} have this property.
+
+@item 2
+@cindex hyphenating characters
+@cindex characters, hyphenation
+Enable breaks before the character.  A line is not broken at a character
+with this property unless the characters on each side both have non-zero
+hyphenation codes.  This exception can be overridden by adding 64.
+Initially, no characters have this property.
+
+@item 4
+@cindex @code{\-} glyph, and @code{cflags}
+@cindex @code{hy} glyph, and @code{cflags}
+@cindex @code{em} glyph, and @code{cflags}
+Enable breaks after the character.  A line is not broken at a character
+with this property unless the characters on each side both have non-zero
+hyphenation codes.  This exception can be overridden by adding 64.
+Initially, characters @samp{\-\[hy]\[em]} have this property.
+
+@item 8
+@cindex overlapping characters
+@cindex characters, overlapping
+@cindex @code{ul} glyph, and @code{cflags}
+@cindex @code{rn} glyph, and @code{cflags}
+@cindex @code{ru} glyph, and @code{cflags}
+@cindex @code{radicalex} glyph, and @code{cflags}
+@cindex @code{sqrtex} glyph, and @code{cflags}
+Mark the glyph associated with this character as overlapping other
+instances of itself horizontally.  Initially, characters
+@samp{\[ul]\[rn]\[ru]\[radicalex]\[sqrtex]} have this property.
+
+@item 16
+@cindex @code{br} glyph, and @code{cflags}
+Mark the glyph associated with this character as overlapping other
+instances of itself vertically.  Initially, the character @samp{\[br]}
+has this property.
+
+@item 32
+@cindex transparent characters
+@cindex character, transparent
+@cindex @code{"}, at end of sentence
+@cindex @code{'}, at end of sentence
+@cindex @code{)}, at end of sentence
+@cindex @code{]}, at end of sentence
+@cindex @code{*}, at end of sentence
+@cindex @code{dg} glyph, at end of sentence
+@cindex @code{dd} glyph, at end of sentence
+@cindex @code{rq} glyph, at end of sentence
+@cindex @code{cq} glyph, at end of sentence
+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 characters with this property is treated as the end of a
+sentence if followed by a newline or two spaces.  This is the same as
+having a zero space factor in @TeX{}.  Initially, characters
+@samp{"')]*\[dg]\[dd]\[rq]\[cq]} have this property.
+
+@item 64
+Ignore hyphenation codes of the surrounding characters.  Use this in
+combination with values 2 and@tie{}4 (initially, no characters have this
+property).
+
+For example, if you need an automatic break point after the en-dash in
+numeric ranges like ``3000--5000'', insert
+
+@Example
+.cflags 68 \[en]
+@endExample
+
+@noindent
+into your document.  However, this practice can lead to bad layout if
+done thoughtlessly; in most situations, a better solution instead of
+changing the @code{cflags} value is to insert @code{\:} right after the
+hyphen at the places that really need a break point.
+@end table
+
+The remaining values were implemented for East Asian language support;
+those who use alphabetic scripts exclusively can disregard them.
+
+@table @code
+@item 128
+Prohibit a line break before the character, but allow a line break after
+the character.  This works only in combination with flags 256 and 512
+and has no effect otherwise.  Initially, no characters have this
+property.
+
+@item 256
+Prohibit a line break after the character, but allow a line break before
+the character.  This works only in combination with flags 128 and 512
+and has no effect otherwise.  Initially, no characters have this
+property.
+
+@item 512
+Allow line break before or after the character.  This works only in
+combination with flags 128 and 256 and has no effect otherwise.
+Initially, no characters have this property.
+@end table
+
+In contrast to values 2 and@tie{}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 automatically inserted between
+them.  If we use value@tie{}6 instead for the left character, a break
+after the character can't be suppressed since the neighboring character
+on the right doesn't get examined.
+@endDefreq
+
+@DefreqList {char, c [@Var{contents}]}
+@DefreqItemx {fchar, c [@Var{contents}]}
+@DefreqItemx {fschar, f c [@Var{contents}]}
+@DefreqListEndx {schar, c [@Var{contents}]}
+@cindex defining character (@code{char})
+@cindex defining fallback character (@code{fchar}, @code{fschar}, @code{schar})
+@cindex character, defining (@code{char})
+@cindex character, defining fallback (@code{fchar}, @code{fschar}, @code{schar})
+@cindex fallback character, defining (@code{fchar}, @code{fschar}, @code{schar})
+@cindex creating new characters (@code{char})
+@cindex defining symbol (@code{char})
+@cindex symbol, defining (@code{char})
+@cindex defining glyph (@code{char})
+@cindex glyph, defining (@code{char})
+@cindex escape character, while defining glyph
+@cindex character, escape, while defining glyph
+@cindex @code{tr} request, and glyph definitions
+@cindex @code{cp} request, and glyph definitions
+@cindex @code{rc} request, and glyph definitions
+@cindex @code{lc} request, and glyph definitions
+@cindex @code{\l}, and glyph definitions
+@cindex @code{\L}, and glyph definitions
+@cindex @code{\&}, and glyph definitions
+@cindex @code{\e}, and glyph definitions
+@cindex @code{hcode} request, and glyph definitions
+Define a new character or glyph@tie{}@var{c} to be @var{contents}, which
+can be empty.  More precisely, @code{char} defines a @code{groff} object
+(or redefines an existing one) that is accessed with the
+name@tie{}@var{c} on input, and produces @var{contents} on output.
+Every time glyph@tie{}@var{c} needs to be printed, @var{contents} is
+processed 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@tie{}@code{\} while @var{contents} is processed.
+Any emboldening, constant spacing, or track kerning is applied to this
+object rather than to individual glyphs in @var{contents}.
+
+An object defined by these requests can be used just like a normal glyph
+provided by the output device.  In particular, other characters can be
+translated to it with the @code{tr} or @code{trin} requests; it can be
+made the leader character with the @code{lc} request; repeated patterns
+can be drawn with it using the @code{\l} and @code{\L} escape sequences;
+and words containing@tie{}@var{c} can be hyphenated correctly if the
+@code{hcode} request is used to give the object a hyphenation code.
+
+There is a special anti-recursion feature: use of the object within its
+own definition is handled like a normal character (not
+defined with @code{char}).
+
+The @code{tr} and @code{trin} requests take precedence if @code{char}
+accesses the same symbol.
+
+@Example
+.tr XY
+X
+    @result{} Y
+.char X Z
+X
+    @result{} Y
+.tr XX
+X
+    @result{} Z
+@endExample
+
+The @code{fchar} request defines a fallback glyph: @code{gtroff} only
+checks for glyphs defined with @code{fchar} if it cannot find the glyph
+in the current font.  @code{gtroff} carries out this test before
+checking special fonts.
+
+@code{fschar} defines a fallback glyph for font@tie{}@var{f}:
+@code{gtroff} checks for glyphs defined with @code{fschar} after the
+list of fonts declared as font-specific special fonts with the
+@code{fspecial} request, but before the list of fonts declared as global
+special fonts with the @code{special} request.
+
+Finally, the @code{schar} request defines a global fallback glyph:
+@code{gtroff} checks for glyphs defined with @code{schar} after the list
+of fonts declared as global special fonts with the @code{special}
+request, but before the already mounted special fonts.
+
+@xref{Character Classes}.
+@endDefreq
+
+@DefreqList {rchar, c @dots{}}
+@DefreqListEndx {rfschar, f c @dots{}}
+@cindex removing glyph definition (@code{rchar}, @code{rfschar})
+@cindex glyph, removing definition (@code{rchar}, @code{rfschar})
+@cindex fallback glyph, removing definition (@code{rchar}, @code{rfschar})
+Remove definition of each ordinary or special character @var{c},
+undoing the effect of a @code{char}, @code{fchar}, or @code{schar}
+request.  Those supplied by font description files cannot be removed.
+Spaces and tabs may separate @var{c}@tie{}arguments.
+
+The request @code{rfschar} removes glyph definitions defined with
+@code{fschar} for font@tie{}@var{f}.
+@endDefreq
+
+@c ---------------------------------------------------------------------
+
+@node Character Classes, Special Fonts, Using Symbols, Using Fonts
+@subsection Character Classes
+@cindex character classes
+@cindex classes, character
+
+Classes are particularly useful for East Asian languages such as
+Chinese, Japanese, and Korean, where the number of needed characters is
+much larger than in European languages, and where large sets of
+characters share the same properties.
+
+@Defreq {class, name c1 c2 @dots{}}
+@cindex character class (@code{class})
+@cindex defining character class (@code{class})
+@cindex class of characters (@code{class})
+Define a character class (or simply ``class'') @var{name} comprising
+the characters @var{c1}, @var{c2}, and so on.
+
+A class thus defined can then be referred to in lieu of listing all the
+characters within it.  Currently, only the @code{cflags} request can
+handle references to character classes.
+
+In the request's simplest form, each @var{cn} is a character (or special
+character).
+
+@Example
+.class [quotes] ' \[aq] \[dq] \[oq] \[cq] \[lq] \[rq]
+@endExample
+
+Since class and glyph names share the same name space, it is recommended
+to start and end the class name with @code{[} and @code{]},
+respectively, to avoid collisions with existing character names defined
+by GNU @code{troff} or the user (with @code{char} and related requests).
+This practice applies the presence of @code{]} in the class name to
+prevent the use of the special character escape form
+@code{\[@r{@dots{}}]}, thus you must use the @code{\C} escape to access
+a class with such a name.
+
+@cindex GGL (@code{groff} glyph list)
+@cindex @code{groff} glyph list (GGL)
+You can also use a character range notation consisting of a
+start character followed by @samp{-} and then an end character.
+Internally, GNU @code{troff} converts these two symbol names to
+Unicode code points (according to the @code{groff} glyph list [GGL]),
+which then give the start and end value of the range.  If that fails,
+the class definition is skipped.
+
+Furthermore, classes can be nested.
+
+@Example
+.class [prepunct] , : ; > @}
+.class [prepunctx] \C'[prepunct]' \[u2013]-\[u2016]
+@endExample
+
+@noindent
+The class @samp{[prepunctx]} thus contains the contents of the class
+@code{[prepunct]} as defined above (the set @samp{, : ; > @}}), and
+characters in the range between @code{U+2013} and @code{U+2016}.
+
+If you want to include @samp{-} in a class, it must be the first
+character value in the argument list, otherwise it gets misinterpreted
+as part of the range syntax.
+
+It is not possible to use class names as end points of range
+definitions.
+
+A typical use of the @code{class} request is to control line-breaking
+and hyphenation rules as defined by the @code{cflags} request.  For
+example, to inhibit line breaks before the characters belonging to the
+@code{prepunctx} class defined in the previous example, you can write
+the following.
+
+@Example
+.cflags 2 \C'[prepunctx]'
+@endExample
+
+@noindent
+See the @code{cflags} request in @ref{Using Symbols}, for more details.
+@endDefreq
+
+@c ---------------------------------------------------------------------
+
+@node Special Fonts, Artificial Fonts, Character Classes, Using Fonts
+@subsection Special Fonts
+@cindex special fonts
+@cindex fonts, special
+
+Special fonts are those that @code{gtroff} searches when it cannot find
+the requested glyph in the current font.  The Symbol font is usually a
+special font.
+
+@code{gtroff} provides the following two requests to add more special
+fonts.  @xref{Using Symbols}, for a detailed description of the glyph
+searching mechanism in @code{gtroff}.
+
+Usually, only non-TTY devices have special fonts.
+
+@DefreqList {special, [@Var{s1} @Var{s2} @dots{}]}
+@DefreqListEndx {fspecial, f [@Var{s1} @Var{s2} @dots{}]}
+@kindex fonts
+@pindex DESC
+Use the @code{special} request to define special fonts.  Initially, this
+list is empty.
+
+Use the @code{fspecial} request to designate special fonts only when
+font@tie{}@var{f} is active.  Initially, this list is empty.
+
+Previous calls to @code{special} or @code{fspecial} are overwritten;
+without arguments, the particular list of special fonts is set to empty.
+Special fonts are searched in the order they appear as arguments.
+
+All fonts that appear in a call to @code{special} or @code{fspecial}
+are loaded.
+
+@xref{Using Symbols}, for the exact search order of glyphs.
+@endDefreq
+
+@c ---------------------------------------------------------------------
+
+@node Artificial Fonts, Ligatures and Kerning, Special Fonts, Using Fonts
+@subsection Artificial Fonts
+@cindex artificial fonts
+@cindex fonts, artificial
+
+There are a number of requests and escape sequences for artificially
+creating fonts.  These are largely vestiges of the days when output
+devices did not have a wide variety of fonts, and when @code{nroff} and
+@code{troff} were separate programs.  Most of them are no longer
+necessary in GNU @code{troff}.  Nevertheless, they are supported.
+
+@DefescList {\\H, @code{'}, height, @code{'}}
+@DefescItem {\\H, @code{'}, @t{+}height, @code{'}}
+@DefescItem {\\H, @code{'}, @t{-}height, @code{'}}
+@DefregListEndx {.height}
+@cindex changing the font height (@code{\H})
+@cindex font height, changing (@code{\H})
+@cindex height, font, changing (@code{\H})
+Change (increment, decrement) the height of the current font, but not
+the width.  If @var{height} is zero, restore the original height.
+Default scaling unit is @samp{z}.
+
+The read-only register @code{.height} contains the font height as set by
+@code{\H}.
+
+Currently, only the @option{-Tps} and @option{-Tpdf} devices support
+this feature.
+
+@code{\H} doesn't produce an input token in GNU @code{troff}.  As a
+consequence, it can be used in requests like @code{mc} (which expects
+a single character as an argument) to change the font on the fly:
+
+@Example
+.mc \H'+5z'x\H'0'
+@endExample
+
+In compatibility mode, @code{gtroff} behaves differently: If an
+increment or decrement is used, it is always taken relative to the
+current type size and not relative to the previously selected font
+height.  Thus,
+
+@Example
+.cp 1
+\H'+5'test \H'+5'test
+@endExample
+
+@noindent
+prints the word @samp{test} twice with the same font height (five points
+larger than the current font size).
+@endDefesc
+
+@DefescList {\\S, @code{'}, slant, @code{'}}
+@DefregListEndx {.slant}
+@cindex changing the font slant (@code{\S})
+@cindex font slant, changing (@code{\S})
+@cindex slant, font, changing (@code{\S})
+Slant the current font by @var{slant} degrees.  Positive values slant to
+the right.  Only integer values are possible.
+
+The read-only register @code{.slant} contains the font slant as set by
+@code{\S}.
+
+Currently, only the @option{-Tps} and @option{-Tpdf} devices support
+this feature.
+
+@code{\S} doesn't produce an input token in GNU @code{troff}.  As a
+consequence, it can be used in requests like @code{mc} (which expects
+a single character as an argument) to change the font on the fly:
+
+@Example
+.mc \S'20'x\S'0'
+@endExample
+
+@cindex CSTR@tie{}#54 errata
+@cindex CSTR@tie{}#54 erratum, @code{\S} escape
+This escape is incorrectly documented in the @acronym{AT&T}
+@code{troff} manual; the slant is always set to an absolute value.
+@endDefesc
+
+@Defreq {ul, [@Var{lines}]}
+@cindex underlining (@code{ul})
+The @code{ul} request normally underlines subsequent lines if a TTY
+output device is used.  Otherwise, the lines are printed in italics
+(only the term `underlined' is used in the following).  The single
+argument is the quantity of input lines to be underlined; with no
+argument, the next line is underlined.  If @var{lines} is zero or
+negative, stop the effects of @code{ul} (if it was active).  Requests
+and empty lines do not count for computing the number of underlined
+input lines, even if they produce some output like @code{tl}.  Lines
+inserted by macros (e.g., invoked by a trap) do count.
+
+At the beginning of @code{ul}, the current font is stored and the
+underline font is activated.  Within the span of a @code{ul} request, it
+is possible to change fonts, but after the last line affected by
+@code{ul} the saved font is restored.
+
+This number of lines still to be underlined is associated with the
+environment (@pxref{Environments}).  The underline font can be changed
+with the @code{uf} request.
+
+@c XXX @xref should be changed to grotty
+
+@c @xref{@code{troff} and @code{nroff} Modes}, for a discussion of how
+@c underlining is implemented for terminal output devices, and what
+@c problems can arise.
+
+The @code{ul} request does not underline spaces.
+@endDefreq
+
+@Defreq {cu, [@Var{lines}]}
+@cindex continuous underlining (@code{cu})
+@cindex underlining, continuous (@code{cu})
+The @code{cu} request is similar to @code{ul} but underlines spaces as
+well (if a TTY output device is used).
+@endDefreq
+
+@Defreq {uf, font}
+@cindex underline font (@code{uf})
+@cindex font for underlining (@code{uf})
+Set the underline font (globally) used by @code{ul} and @code{cu}.  By
+default, this is the font at position@tie{}2.  @var{font} can be either
+a non-negative font position or the name of a font.
+@endDefreq
+
+@DefreqList {bd, font [@Var{offset}]}
+@DefreqItem {bd, font1 font2 [@Var{offset}]}
+@DefregListEndx {.b}
+@cindex imitating boldface (@code{bd})
+@cindex boldface, imitating (@code{bd})
+Embolden @var{font} by overstriking its glyphs offset by @var{offset}
+units minus one.
+
+Two syntax forms are available.
+
+@itemize @bullet
+@item
+Imitate a bold font unconditionally.  The first argument specifies the
+font to embolden, and the second is the number of basic units, minus
+one, by which the two glyphs are offset.  If the second argument is
+missing, emboldening is turned off.
+
+@var{font} can be either a non-negative font position or the name of a
+font.
+
+@var{offset} is available in the @code{.b} read-only register if a
+special font is active; in the @code{bd} request, its default unit is
+@samp{u}.
+
+@cindex @code{fspecial} request, and imitating bold
+@kindex special
+@cindex embolding of special fonts
+@cindex special fonts, emboldening
+@item
+Imitate a bold form conditionally.  Embolden @var{font1} by @var{offset}
+only if font @var{font2} is the current font.  This request can be
+issued repeatedly to set up different emboldening values for different
+current fonts.  If the second argument is missing, emboldening is turned
+off for this particular current font.
+
+This affects special fonts only (either set up with the @code{special}
+command in font files or with the @code{fspecial} request).
+@end itemize
+@endDefreq
+
+@Defreq {cs, font [@Var{width} [@Var{em-size}]]}
+@cindex constant glyph space mode (@code{cs})
+@cindex mode for constant glyph space (@code{cs})
+@cindex glyph, constant space
+@cindex @code{ps} request, and constant glyph space mode
+Switch to and from @dfn{constant glyph space mode}.  If activated, the
+width of every glyph is @math{@var{width}/36} ems.  The em size is given
+absolutely by @var{em-size}; if this argument is missing, the em value
+is taken from the current font size (as set with the @code{ps} request)
+when the font is effectively in use.  Without second and third argument,
+constant glyph space mode is deactivated.
+
+Default scaling unit for @var{em-size} is @samp{z}; @var{width} is an
+integer.
+@endDefreq
+
+@c ---------------------------------------------------------------------
+
+@node Ligatures and Kerning, Dummy Characters, Artificial Fonts, Using Fonts
+@subsection Ligatures and Kerning
+@cindex ligatures and kerning
+@cindex kerning and ligatures
+
+Ligatures are groups of characters that are run together, i.e, producing
+a single glyph.  For example, the letters `f' and `i' can form a
+ligature `fi' as in the word `file'.  This produces a cleaner look
+(albeit subtle) to the printed output.  Usually, ligatures are not
+available in fonts for TTY output devices.
+
+Most PostScript fonts support the fi and fl ligatures.  The C/A/T
+typesetter that was the target of @acronym{AT&T} @code{troff} also
+supported `ff', `ffi', and `ffl' ligatures.  Advanced typesetters or
+`expert' fonts may include ligatures for `ft' and `ct', although GNU
+@code{troff} does not support these (yet).
+
+Only the current font is checked for ligatures and kerns; neither
+special fonts nor special charcters defined with the @code{char} request
+(and its siblings) are taken into account.
+
+@DefreqList {lg, [@Var{flag}]}
+@DefregListEndx {.lg}
+@cindex activating ligatures (@code{lg})
+@cindex ligatures, activating (@code{lg})
+@cindex ligatures enabled register (@code{.lg})
+Switch the ligature mechanism on or off; if the parameter is non-zero or
+missing, ligatures are enabled, otherwise disabled.  Default is on.  The
+current ligature mode can be found in the read-only register @code{.lg}
+(set to 1 or@tie{}2 if ligatures are enabled, 0@tie{}otherwise).
+
+Setting the ligature mode to@tie{}2 enables the two-character ligatures
+(fi, fl, and ff) and disables the three-character ligatures (ffi and
+ffl).
+@endDefreq
+
+@dfn{Pairwise kerning} is another subtle typesetting mechanism that
+modifies the distance between a glyph pair to improve readability.  In
+most cases (but not always) the distance is decreased.
+@iftex
+For example, compare the combination of the letters `V' and `A'.  With
+kerning, `VA' is printed.  Without kerning it appears as `V@w{}A'.
+@end iftex
+Typewriter-like fonts and fonts for terminals where all glyphs have the
+same width don't use kerning.
+
+@DefreqList {kern, [@Var{flag}]}
+@DefregListEndx {.kern}
+@cindex activating kerning (@code{kern})
+@cindex kerning, activating (@code{kern})
+@cindex kerning enabled register (@code{.kern})
+Switch kerning on or off.  If the parameter is non-zero or missing,
+enable pairwise kerning, otherwise disable it.  The read-only register
+@code{.kern} is set to@tie{}1 if pairwise kerning is enabled,
+0@tie{}otherwise.
+
+@cindex dummy character (@code{\&}), effect on kerning
+@cindex character, dummy (@code{\&}), effect on kerning
+If the font description file contains pairwise kerning information,
+glyphs from that font are kerned.  Kerning between two glyphs can be
+inhibited by placing @code{\&} between them: @samp{V\&A}.
+
+@xref{Font Description File Format}.
+@endDefreq
+
+@cindex track kerning
+@cindex kerning, track
+@dfn{Track kerning} expands or reduces the space between glyphs.  This
+can be handy, for example, if you need to squeeze a long word onto a
+single line or spread some text to fill a narrow column.  It must be
+used with great care since it is usually considered bad typography if
+the reader notices the effect.
+
+@Defreq {tkf, f s1 n1 s2 n2}
+@cindex activating track kerning (@code{tkf})
+@cindex track kerning, activating (@code{tkf})
+Enable track kerning for font@tie{}@var{f}.  If the current font
+is@tie{}@var{f} the width of every glyph is increased by an amount
+between @var{n1} and @var{n2} (@var{n1}, @var{n2} can be negative); if
+the current type size is less than or equal to @var{s1} the width is
+increased by @var{n1}; if it is greater than or equal to @var{s2} the
+width is increased by @var{n2}; if the type size is greater than or
+equal to @var{s1} and less than or equal to @var{s2} the increase in
+width is a linear function of the type size.
+
+The default scaling unit is @samp{z} for @var{s1} and @var{s2}, @samp{p}
+for @var{n1} and @var{n2}.
+
+The track kerning amount is added even to the rightmost glyph in a line;
+for large values it is thus recommended to increase the line length by
+the same amount to compensate.
+@endDefreq
+
+@c ---------------------------------------------------------------------
+
+@node Italic Corrections, Dummy Characters, Ligatures and Kerning, Using Fonts
+@subsection Italic Corrections
+
+When typesetting adjacent glyphs from typefaces of different slants, the
+space between them may require adjustment.
+
+@Defesc {\\/, , , }
+@cindex italic correction (@code{\/})
+@cindex correction, italic (@code{\/})
+@cindex correction between oblique and upright glyph (@code{\/}, @code{\,})
+@cindex roman glyph, correction after italic glyph (@code{\/})
+@cindex upright glyph, correction after oblique glyph (@code{\/})
+Apply an @dfn{italic correction}:@: modify the spacing of the preceding
+glyph so that the distance between it and the following glyph is correct
+if the latter is of upright shape.  For example, if an
+italic@tie{}@samp{f} is followed immediately by a roman right
+parenthesis, then in many fonts the top right portion of
+the@tie{}@samp{f} overlaps the top left of the right parenthesis, which
+is ugly.  Use this escape sequence whenever an oblique glyph is
+immediately followed by an upright glyph without any intervening space.
+@endDefesc
+
+@Defesc {\\\,, , , }
+@cindex left italic correction (@code{\,})
+@cindex correction, left italic (@code{\,})
+@cindex correction between upright and oblique glyph (@code{\/}, @code{\,})
+@cindex roman glyph, correction before italic glyph (@code{\,})
+@cindex upright glyph, correction before oblique glyph (@code{\,})
+Apply a @dfn{left italic correction}:@: modify the spacing of the
+following glyph so that the distance between it and the preceding
+glyph is correct if the latter is of upright shape.  For example,
+if a roman left parenthesis is immediately followed by an
+italic@tie{}@samp{f}, then in many fonts the bottom left portion of
+the@tie{}@samp{f} overlaps the bottom of the left parenthesis, which is
+ugly.  Use this escape sequence whenever an upright glyph is followed
+immediately by an oblique glyph without any intervening space.
+@endDefesc
+
+@c XXX: Can we move this node earlier in the text?  Should it come
+@c before some of the dummy character's multifarious effects?
+@need 1000
+@node Dummy Characters,  , Italic Corrections, Using Fonts
+@subsection Dummy Characters
+
+As discussed in @ref{Requests and Macros}, the first character on an
+input line is treated specially.  Further, formatting a glyph has many
+consequences on formatter state (@pxref{Environments}).  Occasionally,
+we want to escape this context or embrace some of those consequences
+without actually rendering a glyph to the output.
+
+@Defesc {\\&, , , }
+@cindex dummy character (@code{\&})
+@cindex character, dummy (@code{\&})
+Interpolate a dummy character, which is constitutive of output but
+invisible.@footnote{Opinions of this escape sequence's name abound.
+``Zero-width space'' is a popular misnomer:@: @code{roff} formatters do
+not treat it like a space.  Ossanna called it a ``non-printing,
+zero-width character'', but the character causes @emph{output} even
+though it does not ``print''.  If no output line is pending, the dummy
+character starts one.  Contrast an empty input document with one
+containing only @code{\&}.  The former produces no output; the latter, a
+blank page.}  Its presence alters the interpretation context of a
+subsequent input character, and enjoys several applications.
+
+@itemize @bullet
+@item
+Prevent insertion of extra space after an end-of-sentence character.
+
+@Example
+Test.
+Test.
+    @result{} Test.  Test.
+Test.\&
+Test.
+    @result{} Test. Test.
+@endExample
+
+@item
+Prevent recognition of a control character.
+
+@Example
+.Test
+    @error{} warning: macro 'Test' not defined
+\&.Test
+    @result{} .Test
+@endExample
+
+@item
+Prevent kerning between two glyphs.
+
+@iftex
+@c can't use @Example...@endExample here
+@example
+@group
+VA
+    @result{} @r{VA}
+V\&A
+    @result{} @r{V@w{}A}
+@end group
+@end example
+@end iftex
+
+@item
+Translate a character to ``nothing''.
+
+@Example
+.tr JIjiK\&k\&UVuv
+@c XXX: I might have the wrong noun declension in "university" here.
+Post universitum, alea jacta est, OK?
+    @result{} Post vniversitvm, alea iacta est, O?
+@endExample
+@end itemize
+
+The dummy character escape sequence sees use in macro definitions as a
+means of ensuring that arguments are treated as text even if they begin
+with spaces or control characters.
+
+@Example
+.de HD \" typeset a simple bold heading
+.  sp
+.  ft B
+\&\\$1 \" exercise: remove the \&
+.  ft
+.  sp
+..
+.HD .\|.\|.\|surprised?
+@endExample
+@endDefesc
+
+One way to think about the dummy character is to imagine placing the
+symbol @samp{&} in the input at a certain location; if doing so has all
+the side effects on formatting that you desire except for sticking an
+ugly ampersand in the midst of your text, the dummy character is what
+you want in its place.
+
+@c XXX: This feature seems nearly impossible to motivate.  The _only_
+@c use of it in the groff source tree is for the mdoc package, for which
+@c it seems to be special pleading for that package's unique approach to
+@c macro argument reprocessing, which also involves an idiosyncratic
+@c approach to punctuation characters in macro argument lists.
+@Defesc {\\), , , }
+@cindex transparent dummy character (@code{\)})
+@cindex character, transparent dummy (@code{\)})
+@cindex dummy character, transparent (@code{\)})
+Interpolate a @slanted{transparent} dummy character---one that is
+transparent to end-of-sentence detection.  It behaves as @code{\&},
+except that @code{\&} is treated as letters and numerals normally are
+after @samp{.}, @samp{?} and @samp{!}; @code{\&} cancels end-of-sentence
+detection, and @code{\)} does not.
+@c This feature seems too weak to me; see Savannah #60571.  -- GBR
+
+@Example
+.de Suffix-&
+.  nop \&\\$1
+..
+.
+.de Suffix-)
+.  nop \)\\$1
+..
+.
+Here's a sentence.\c
+.Suffix-& '
+Another one.\c
+.Suffix-) '
+And a third.
+    @result{} Here's a sentence.' Another one.'  And a third.
+@endExample
+@endDefesc
+
+
+@c =====================================================================
+
+@c TODO: Move the troff and nroff mode stuff here.  Try to keep stuff
+@c that isn't ignored in nroff above this point, and stuff for
+@c typesetters below, until we hit the programming/advanced concepts.
+@c XXX: Thorny issue: nroff/terminal devices ignore type size but
+@c _honor_ vertical spacing (to within their crude vertical motion
+@c quanta).
+
+@need 2000
+@node Manipulating Type Size and Vertical Spacing, Colors, Using Fonts, GNU troff Reference
+@section Manipulating Type Size and Vertical Spacing
+@cindex manipulating type size and vertical spacing
+
+@cindex text baseline
+@cindex baseline, text
+@cindex type size
+@cindex size, size
+@cindex vertical spacing
+@cindex spacing, vertical
+These concepts were introduced in @ref{Page Geometry}.  The height of a
+font's tallest glyph is one em, which is equal to the type size in
+points.@footnote{In text fonts, the tallest glyphs are typically
+parentheses.  Unfortunately, in many cases the actual dimensions of the
+glyphs in a font do not closely match its declared type size!  For
+example, in the standard PostScript font families, 10-point Times sets
+better with 9-point Helvetica and 11-point Courier than if all three
+were used at 10@tie{}points.}  A vertical spacing of less than 120% of
+the type size can make a document hard to read.  Larger proportions can
+be useful to spread the text for annotations or proofreader's marks.  By
+default, GNU @code{troff} uses 10@tie{}point type on 12@tie{}point
+spacing.
+@cindex leading
+Typographers call the difference between type size and vertical spacing
+@dfn{leading}.@footnote{Rhyme with ``sledding''; mechanical typography
+used lead metal (Latin @emph{plumbum}).}
+
+@menu
+* Changing the Type Size::
+* Changing the Vertical Spacing::
+* Using Fractional Type Sizes::
+@end menu
+
+@c ---------------------------------------------------------------------
+
+@node Changing the Type Size, Changing the Vertical Spacing, Manipulating Type Size and Vertical Spacing, Manipulating Type Size and Vertical Spacing
+@subsection Changing the Type Size
+
+@DefreqList {ps, [@Var{size}]}
+@DefreqItem {ps, @t{+}@Var{size}}
+@DefreqItem {ps, @t{-}@Var{size}}
+@DefescItemx {\\s, , size, }
+@DefregListEndx {.s}
+@cindex changing type sizes (@code{ps}, @code{\s})
+@cindex type sizes, changing (@code{ps}, @code{\s})
+@cindex point sizes, changing (@code{ps}, @code{\s})
+Use the @code{ps} request or the @code{\s} escape sequence to change
+(increase, decrease) the type size (in scaled points).  Specify
+@var{size} as either an absolute type size, or as a relative change from
+the current size.  @code{ps} with no argument restores the previous
+size.  The @code{ps} request's default scaling unit is @samp{z}.  The
+requested size is rounded to the nearest valid size (with ties rounding
+down) within the limits supported by the device.  If the requested size
+is non-positive, it is treated as 1@dmn{u}.
+
+@cindex CSTR@tie{}#54 errata
+@cindex CSTR@tie{}#54 erratum, @code{ps} request
+@cindex CSTR@tie{}#54 erratum, @code{\s} escape sequence
+Type size alteration is incorrectly documented in the @acronym{AT&T}
+@code{troff} manual, which claims ``if [the requested size] is invalid,
+the next larger valid size will result, with a maximum of
+36''.@footnote{The claim appears to have been true of Ossanna
+@code{troff} for the C/A/T device; Kernighan made device-independent
+@code{troff} more flexible.}
+
+@cindex type size registers (@code{.s}, @code{.ps})
+@cindex point size registers (@code{.s}, @code{.ps})
+The read-only string-valued register @code{.s} interpolates the type
+size in points as a decimal fraction; it is associated with the
+environment (@pxref{Environments}).  To obtain the type size in scaled
+points, interpolate the @code{.ps} register instead (@pxref{Using
+Fractional Type Sizes}).
+
+The @code{\s} escape sequence supports a variety of syntax forms.
+
+@table @code
+@item \s@var{n}
+Set the type size to @var{n}@tie{}points.  @var{n}@tie{}must be a single
+digit.  If @var{n}@tie{}is 0, restore the previous size.
+
+@item \s+@var{n}
+@itemx \s-@var{n}
+Increase or decrease the type size by @var{n}@tie{}points.
+@var{n}@tie{}must be exactly one digit.
+
+@item \s(@var{nn}
+Set the type size to @var{nn}@tie{}points.  @var{nn} must be exactly two
+digits.
+
+@item \s+(@var{nn}
+@itemx \s-(@var{nn}
+@itemx \s(+@var{nn}
+@itemx \s(-@var{nn}
+Alter the type size in points by the two-digit value @var{nn}.
+@end table
+
+@xref{Using Fractional Type Sizes}, for further syntactical forms of the
+@code{\s} escape sequence that additionally accept decimal fractions.
+
+@Example
+snap, snap,
+.ps +2
+grin, grin,
+.ps +2
+wink, wink, \s+2nudge, nudge,\s+8 say no more!
+.ps 10
+@endExample
+@endDefreq
+
+The @code{\s} escape sequence affects the environment immediately and
+doesn't produce an input token.  Consequently, it can be used in
+requests like @code{mc}, which expects a single character as an
+argument, to change the type size on the fly.
+
+@Example
+.mc \s[20]x\s[0]
+@endExample
+
+@Defreq {sizes, s1 s2 @dots{} sn [@t{0}]}
+The @file{DESC} file specifies which type sizes are allowed by the
+output device; see @ref{DESC File Format}.  Use the @code{sizes} request
+to change this set of permissible sizes.  Arguments are in scaled
+points; see @ref{Using Fractional Type Sizes}.  Each can be a single
+type size (such as @samp{12000}), or a range of sizes (such as
+@samp{4000-72000}).  You can optionally end the list with a @samp{0}.
+@endDefreq
+
+@need 1000
+@node Changing the Vertical Spacing, Using Fractional Type Sizes, Changing the Type Size, Manipulating Type Size and Vertical Spacing
+@subsection Changing the Vertical Spacing
+
+@DefreqList {vs, [@Var{space}]}
+@DefreqItem {vs, @t{+}@Var{space}}
+@DefreqItem {vs, @t{-}@Var{space}}
+@DefregListEndx {.v}
+@cindex changing vertical line spacing (@code{vs})
+@cindex vertical line spacing, changing (@code{vs})
+@cindex vertical line spacing register (@code{.v})
+Set the vertical spacing to, or alter it by, @var{space}.  The default
+scaling unit is @samp{p}.  If @code{vs} is called without an argument,
+the vertical spacing is reset to the previous value before the last call
+to @code{vs}.
+@cindex @code{.V} register, and @code{vs}
+GNU @code{troff} emits a warning in category @samp{range} if @var{space}
+is negative; the vertical spacing is then set to the smallest possible
+positive value, the vertical motion quantum (as found in the @code{.V}
+register).
+
+@w{@samp{.vs 0}} isn't saved in a diversion since it doesn't result in
+a vertical motion.  You must explicitly issue this request before
+interpolating the diversion.
+
+The read-only register @code{.v} contains the vertical spacing; it is
+associated with the environment (@pxref{Environments}).
+@endDefreq
+
+@cindex vertical line spacing, effective value
+@noindent
+When a break occurs, GNU @code{troff} performs the following procedure.
+
+@itemize @bullet
+@item
+@cindex extra pre-vertical line space (@code{\x})
+@cindex line space, extra pre-vertical (@code{\x})
+Move the drawing position vertically by the @dfn{extra pre-vertical line
+space}, the minimum of all negative @code{\x} escape sequence arguments
+in the pending output line.
+
+@item
+Move the drawing position vertically by the vertical line spacing.
+
+@item
+Write out the pending output line.
+
+@item
+@cindex extra post-vertical line space (@code{\x})
+@cindex line space, extra post-vertical (@code{\x})
+Move the drawing position vertically by the @dfn{extra post-vertical line
+space}, the maximum of all positive @code{\x} escape sequence arguments
+in the line that has just been output.
+
+@item
+@cindex post-vertical line spacing
+@cindex line spacing, post-vertical (@code{pvs})
+Move the drawing position vertically by the @dfn{post-vertical line
+spacing} (see below).
+@end itemize
+
+@cindex double-spacing (@code{vs}, @code{pvs})
+Prefer @code{vs} or @code{pvs} over @code{ls} to produce double-spaced
+documents.  @code{vs} and @code{pvs} have finer granularity than
+@code{ls}; moreover, some preprocessors assume single spacing.
+@xref{Manipulating Spacing}, regarding the @code{\x} escape sequence and
+the @code{ls} request.
+
+@DefreqList {pvs, [@Var{space}]}
+@DefreqItem {pvs, @t{+}@Var{space}}
+@DefreqItem {pvs, @t{-}@Var{space}}
+@DefregListEndx {.pvs}
+@cindex @code{ls} request, alternative to (@code{pvs})
+@cindex post-vertical line spacing, changing (@code{pvs})
+@cindex post-vertical line spacing register (@code{.pvs})
+Set the post-vertical spacing to, or alter it by, @var{space}.  The
+default scaling unit is @samp{p}.  If @code{pvs} is called without an
+argument, the post-vertical spacing is reset to the previous value
+before the last call to @code{pvs}.  GNU @code{troff} emits a warning in
+category @samp{range} if @var{space} is negative; the post-vertical
+spacing is then set to zero.
+
+The read-only register @code{.pvs} contains the post-vertical spacing;
+it is associated with the environment (@pxref{Environments}).
+@endDefreq
+
+@c ---------------------------------------------------------------------
+
+@c BEGIN Keep (roughly) parallel with subsection "Fractional type sizes
+@c and new scaling units" of groff_diff(7).
+@node Using Fractional Type Sizes,  , Changing the Type Size, Manipulating Type Size and Vertical Spacing
+@subsection Using Fractional Type Sizes
+@cindex fractional type sizes
+@cindex fractional point sizes
+@cindex type sizes, fractional
+@cindex point sizes, fractional
+@cindex sizes, fractional type
+
+AT&T @code{troff} interpreted all type size measurements in points.
+Combined with integer arithmetic, this design choice made it impossible
+to support, for instance, ten and a half-point type.  In GNU
+@code{troff}, an output device can select a scaling factor that
+subdivides a point into ``scaled points''.  A type size expressed in
+scaled points can thus represent a non-integral type size.
+
+@cindex @code{s} scaling unit
+@cindex unit, scaling, @code{s}
+@cindex scaling unit @code{s}
+@cindex @code{z} scaling unit
+@cindex unit, scaling, @code{z}
+@cindex scaling unit @code{z}
+@cindex @code{ps} request, with fractional type sizes
+@cindex @code{cs} request, with fractional type sizes
+@cindex @code{tkf} request, with fractional type sizes
+@cindex @code{\H}, with fractional type sizes
+@cindex @code{\s}, with fractional type sizes
+A @dfn{scaled point} is equal to @math{1/@var{sizescale}} points, where
+@var{sizescale} is specified in the device description file @file{DESC},
+and defaults to@tie{}1.@footnote{@xref{Device and Font Description
+Files}.}  Requests and escape sequences in GNU @code{troff} interpret
+arguments that represent a type size in scaled points, which the
+formatter multiplies by @var{sizescale} and converts to an integer.
+Arguments treated in this way comprise those to the escape sequences
+@code{\H} and @code{\s}, to the request @code{ps}, the third argument to
+the @code{cs} request, and the second and fourth arguments to the
+@code{tkf} request.  Scaled points may be specified explicitly with the
+@code{z} scaling unit.
+
+For example, if @var{sizescale} is@tie{}1000, then a scaled point is one
+thousandth of a point.  The request @samp{.ps 10.5} is synonymous with
+@samp{.ps 10.5z} and sets the type size to 10,500@tie{}scaled points, or
+10.5@tie{}points.  Consequently, in GNU @code{troff}, the register
+@code{.s} can interpolate a non-integral type size.
+
+@Defreg {.ps}
+This read-only register interpolates the type size in scaled points; it
+is associated with the environment (@pxref{Environments}).
+@endDefreg
+
+It makes no sense to use the @samp{z} scaling unit in a numeric
+expression whose default scaling unit is neither @samp{u} nor @samp{z},
+so GNU @code{troff} disallows this.  Similarly, it is nonsensical to use
+a scaling unit other than @samp{z} or @samp{u} in a numeric expression
+whose default scaling unit is @samp{z}, and so GNU @code{troff}
+disallows this as well.
+
+Another GNU @code{troff} scaling unit, @samp{s}, multiplies by the
+number of basic units in a scaled point.  Thus, @samp{\n[.ps]s} is equal
+to @samp{1m} by definition.  Do not confuse the @samp{s} and @samp{z}
+scaling units.
+@c END Keep (roughly) parallel with subsection "Fractional type sizes
+@c and new scaling units" of groff_diff(7).
+
+@DefregList {.psr}
+@DefregListEndx {.sr}
+@cindex last-requested type size registers (@code{.psr}, @code{.sr})
+@cindex type size registers, last-requested (@code{.psr}, @code{.sr})
+@cindex last-requested point size registers (@code{.psr}, @code{.sr})
+@cindex point size registers, last-requested (@code{.psr}, @code{.sr})
+@cindex @code{.ps} register, in comparison with @code{.psr}
+@cindex @code{.s} register, in comparison with @code{.sr}
+Output devices may be limited in the type sizes they can employ.  The
+@code{.s} and @code{.ps} registers represent the type size selected by
+the output driver as it understands a device's capability.  The last
+@emph{requested} type size is interpolated in scaled points by the
+read-only register @code{.psr} and in points as a decimal fraction by
+the read-only string-valued register @code{.sr}.  Both are associated
+with the environment (@pxref{Environments}).
+
+For example, if a type size of 10.95 points is requested, and the
+nearest size permitted by a @code{sizes} request (or by the @code{sizes}
+or @code{sizescale} directives in the device's @file{DESC} file) is 11
+points, the output driver uses the latter value.
+@endDefreg
+
+The @code{\s} escape sequence offers the following syntax forms that
+work with fractional type sizes and accept scaling units.  You may of
+course give them integral arguments.  The delimited forms need not use
+the neutral apostrophe; see @ref{Delimiters}.
+
+@table @code
+@item \s[@var{n}]
+@itemx \s'@var{n}'
+Set the type size to @var{n}@tie{}scaled points; @var{n}@tie{}is a
+numeric expression with a default scaling unit of @samp{z}.
+
+@item \s[+@var{n}]
+@itemx \s[-@var{n}]
+@itemx \s+[@var{n}]
+@itemx \s-[@var{n}]
+@itemx \s'+@var{n}'
+@itemx \s'-@var{n}'
+@itemx \s+'@var{n}'
+@itemx \s-'@var{n}'
+Increase or decrease the type size by @var{n}@tie{}scaled points;
+@var{n}@tie{}is a numeric expression (which may start with a minus sign)
+with a default scaling unit of @samp{z}.
+@end table
+
+
+@c =====================================================================
+
+@c BEGIN Keep (roughly) parallel with section "Colors" of groff(7).
+@node Colors, Strings, Manipulating Type Size and Vertical Spacing, GNU troff Reference
+@section Colors
+@cindex colors
+
+@cindex stroke color
+@cindex color, stroke
+@cindex fill color
+@cindex color, fill
+GNU @code{troff} supports color output with a variety of color spaces
+and up to 16 bits per channel.  Some devices, particularly terminals,
+may be more limited.  When color support is enabled, two colors are
+current at any given time: the @dfn{stroke color}, with which glyphs,
+rules (lines), and geometric objects like circles and polygons are
+drawn, and the @dfn{fill color}, which can be used to paint the interior
+of a closed geometric figure.
+
+@DefreqList {color, [@Var{n}]}
+@DefregListEndx {.color}
+If @var{n} is missing or non-zero, enable the output of color-related
+device-independent output commands (this is the default); otherwise,
+disable them.  This request sets a global flag; it does not produce an
+input token (@pxref{Gtroff Internals}).
+
+The read-only register @code{.color} is@tie{}1 if colors are enabled,
+0@tie{}otherwise.
+
+Color can also be disabled with the @option{-c} command-line option.
+@endDefreq
+
+@Defreq {defcolor, ident scheme color-component @dots{}}
+Define a color named @var{ident}.  @var{scheme} selects a color space
+and determines the quantity of required @var{color-component}s; it must
+be one of @samp{rgb} (three components), @samp{cmy} (three), @samp{cmyk}
+(four), or @samp{gray} (one).  @samp{grey} is accepted as a synonym of
+@samp{gray}.  The color components can be encoded as a single
+hexadecimal value starting with @samp{#} or @samp{##}.  The former
+indicates that each component is in the range 0--255 (0--FF), the latter
+the range 0--65,535 (0--FFFF).
+
+@Example
+.defcolor half gray #7f
+.defcolor pink rgb #FFC0CB
+.defcolor magenta rgb  ##ffff0000ffff
+@endExample
+
+@cindex @code{f} scaling unit
+@cindex unit, scaling, @code{f}
+@cindex scaling unit @code{f}
+Alternatively, each color component can be specified as a decimal
+fraction in the range 0--1, interpreted using a default scaling
+unit of@tie{}@code{f}, which multiplies its value by 65,536 (but
+clamps it at 65,535).
+
+@Example
+.defcolor gray50 rgb 0.5 0.5 0.5
+.defcolor darkgreen rgb 0.1f 0.5f 0.2f
+@endExample
+@endDefreq
+
+@cindex default color
+@cindex color, default
+Each output device has a color named @samp{default}, which cannot be
+redefined.  A device's default stroke and fill colors are not
+necessarily the same.  For the @code{dvi}, @code{html}, @code{pdf},
+@code{ps}, and @code{xhtml} output devices, GNU @code{troff}
+automatically loads a macro file defining many color names at startup.
+By the same mechanism, the devices supported by @code{grotty} recognize
+the eight standard ISO@tie{}6429/EMCA-48 color names.@footnote{also
+known vulgarly as ``ANSI colors''}
+
+@DefreqList {gcolor, [@Var{color}]}
+@DefescItemx {\\m, , c, }
+@DefescItem {\\m, (, co, }
+@DefescItem {\\m, [, color, ]}
+@DefregListEndx {.m}
+Set the stroke color to @var{color}.
+
+@Example
+.gcolor red
+The next words
+.gcolor
+\m[red]are in red\m[]
+and these words are in the previous color.
+@endExample
+
+The escape sequence @code{\m[]} restores the previous stroke color, as
+does a @code{gcolor} request without an argument.
+
+@cindex stroke color name register (@code{.m})
+@cindex name, stroke color, register (@code{.m})
+@cindex color name, stroke, register (@code{.m})
+The name of the current stroke color is available in the read-only
+string-valued register @samp{.m}; it is associated with the environment
+(@pxref{Environments}).  It interpolates nothing when the stroke color
+is the default.
+
+@code{\m} doesn't produce an input token in GNU @code{troff}
+(@pxref{Gtroff Internals}).  It therefore can be used in requests like
+@code{mc} (which expects a single character as an argument) to change
+the color on the fly:
+
+@Example
+.mc \m[red]x\m[]
+@endExample
+@endDefesc
+
+@DefreqList {fcolor, [@Var{color}]}
+@DefescItemx {\\M, , c, }
+@DefescItem {\\M, (, co, }
+@DefescItem {\\M, [, color, ]}
+@DefregListEndx {.M}
+Set the fill color for objects drawn with @code{\D'@dots{}'} escape
+sequences.  The escape sequence @code{\M[]} restores the previous fill
+color, as does an @code{fcolor} request without an argument.
+
+@cindex background color name register (@code{.M})
+@cindex name, background color, register (@code{.M})
+@cindex color name, background, register (@code{.M})
+@cindex fill color name register (@code{.M})
+@cindex name, fill color, register (@code{.M})
+@cindex color name, fill, register (@code{.M})
+The name of the current fill color is available in the read-only
+string-valued register @samp{.M}; it is associated with the environment
+(@pxref{Environments}).  It interpolates nothing when the fill color
+is the default.  @code{\M} doesn't produce an input token in GNU
+@code{troff}.
+
+Create an ellipse with a red interior as follows.
+
+@Example
+\M[red]\h'0.5i'\D'E 2i 1i'\M[]
+@endExample
+@endDefesc
+@c END Keep (roughly) parallel with section "Colors" of groff(7).
+
+
+@c =====================================================================
+
+@c BEGIN Keep (roughly) parallel with section "Strings" of groff(7).
+@node Strings, Conditionals and Loops, Colors, GNU troff Reference
+@section Strings
+@cindex strings
+
+GNU @code{troff} supports strings primarily for user convenience.
+Conventionally, if one would define a macro only to interpolate a small
+amount of text, without invoking requests or calling any other macros,
+one defines a string instead.  Only one string is predefined by the
+language.
+
+@Defstr {.T}
+@stindex .T
+@cindex output device name string (@code{.T})
+Contains the name of the output device (for example, @samp{utf8} or
+@samp{pdf}).
+@endDefmpstr
+
+The @code{ds} request creates a string with a specified name and
+contents and the @code{\*} escape sequence dereferences its name,
+interpolating its contents.  If the string named by the @code{\*} escape
+sequence does not exist, it is defined as empty, nothing is
+interpolated, and a warning in category @samp{mac} is emitted.
+@xref{Warnings}, for information about the enablement and suppression of
+warnings.
+
+@DefreqList {ds, name [@Var{contents}]}
+@DefreqItemx {ds1, name [@Var{contents}]}
+@DefescItemx {\\*, , n, }
+@DefescItem {\\*, (, nm, }
+@c XXX: Can't mark the parameters with @Var because @Var gets called
+@c recursively if we do.
+@c @DefescListEnd {\\*, [, name [@Var{arg1} @Var{arg2} @dots{}], ]}
+@DefescListEnd {\\*, [, name @sansserif{[}arg1 arg2 @dots{}@sansserif{]}, ]}
+@cindex string interpolation (@code{\*})
+@cindex string expansion (@code{\*})
+@cindex interpolation of strings (@code{\*})
+@cindex expansion of strings (@code{\*})
+@cindex string arguments
+@cindex arguments, to strings
+Define a string called @var{name} with contents @var{contents}.  If
+@var{name} already exists as an alias, the target of the alias is
+redefined; see @code{als} and @code{rm} below.  If @code{ds} is called
+with only one argument, @var{name} is defined as an empty string.
+Otherwise, GNU @code{troff} stores @var{contents} in copy
+mode.@footnote{@xref{Copy Mode}.}
+
+The @code{\*} escape sequence interpolates a previously defined string
+variable @var{name} (one-character name@tie{}@var{n}, two-character name
+@var{nm}).  The bracketed interpolation form accepts arguments that are
+handled as macro arguments are; recall @ref{Calling Macros}.  In
+contrast to macro calls, however, if a closing bracket @samp{]} occurs
+in a string argument, that argument must be enclosed in double quotes.
+@code{\*} is interpreted even in copy mode.  When defining strings,
+argument interpolations must be escaped if they are to reference
+parameters from the calling context; @xref{Parameters}.
+
+@Example
+.ds cite (\\$1, \\$2)
+Gray codes are explored in \*[cite Morgan 1998].
+    @result{} Gray codes are explored in (Morgan, 1998).
+@endExample
+
+@c TODO: Consider examples of recursive string calls, particularly where
+@c one interpolation is constructed from the argument of an enclosing
+@c macro, to illustrate ".ds a \$1 \\$1".
+@c
+@c @Example
+@c .ds a \\$1 wildebeest
+@c .ds b big, \*[a hairy]
+@c I see a \*[b].
+@c     @result{} I see a big, hairy wildebeest.
+@c @endExample
+
+@cindex trailing spaces in string definitions and appendments
+@cindex comments, with @code{ds}
+@cindex @code{ds} request, and comments
+@strong{Caution:@:} Unlike other requests, the second argument to the
+@code{ds} request consumes the remainder of the input line, including
+trailing spaces.  This means that comments on a line with such a request
+can introduce unwanted space into a string when they are set off from
+the material they annotate, as is conventional.
+
+@Example
+.ds H2O H\v'+.3m'\s'-2'2\v'-.3m'\s0O \" water
+@endExample
+
+@noindent
+Instead, place the comment on another line or put the comment escape
+sequence immediately adjacent to the last character of the string.
+
+@Example
+.ds H2O H\v'+.3m'\s'-2'2\v'-.3m'\s0O\" water
+@endExample
+
+Ending string definitions (and appendments) with a comment, even an
+empty one, prevents unwanted space from creeping into them during source
+document maintenance.
+
+@Example
+.ds author Alice Pleasance Liddell\"
+.ds empty \" might be appended to later with .as
+@endExample
+
+@cindex trailing double quotes in strings
+@cindex double quotes, trailing, in strings
+@cindex @code{ds} request, and double quotes
+@cindex leading spaces with @code{ds}
+@cindex spaces with @code{ds}
+@cindex @code{ds} request, and leading spaces
+An initial neutral double quote @code{"} in @var{contents} is stripped
+to allow embedding of leading spaces.  Any other @code{"} is interpreted
+literally, but it is wise to use the special character escape sequence
+@code{\[dq]} instead if the string might be interpolated as part of a
+macro argument; see @ref{Calling Macros}.
+
+@c Examples should be more accessible than Unix nerd stuff like this,
+@c but in general document authors shouldn't want to use "straight"
+@c double quotes for ordinary prose anyway.  Also, 56 chars is as fat
+@c as these examples can get and not overrun the right margin in PDF.
+@Example
+.ds salutation "         Yours in a white wine sauce,\"
+.ds c-var-defn "  char mydate[]=\[dq]2020-07-29\[dq];\"
+@endExample
+
+@cindex multi-line strings
+@cindex strings, multi-line
+@cindex newline character, in strings, escaping
+@cindex escaping newline characters, in strings
+Strings are not limited to a single input line of text.
+@code{\@key{RET}} works just as it does elsewhere.  The resulting string
+is stored @emph{without} the newlines.  Care is therefore required when
+interpolating strings while filling is disabled.
+
+@Example
+.ds foo This string contains \
+text on multiple lines \
+of input.
+@endExample
+
+It is not possible to embed a newline in a string that will be
+interpreted as such when the string is interpolated.  To achieve that
+effect, use @code{\*} to interpolate a macro instead; see @ref{Punning
+Names}.
+
+Because strings are similar to macros, they too can be defined so as to
+suppress AT&T @code{troff} compatibility mode when used; see
+@ref{Writing Macros} and @ref{Compatibility Mode}.  The @code{ds1}
+request defines a string such that compatibility mode is off when the
+string is later interpolated.  To be more precise, a @dfn{compatibility
+save} input token is inserted at the beginning of the string, and a
+@dfn{compatibility restore} input token at the end.
+
+@Example
+.nr xxx 12345
+.ds aa The value of xxx is \\n[xxx].
+.ds1 bb The value of xxx is \\n[xxx].
+.
+.cp 1
+.
+\*(aa
+    @error{} warning: register '[' not defined
+    @result{} The value of xxx is 0xxx].
+\*(bb
+    @result{} The value of xxx is 12345.
+@endExample
+@endDefreq
+
+@DefreqList {as, name [@Var{contents}]}
+@DefreqListEndx {as1, name [@Var{contents}]}
+@cindex appending to a string (@code{as})
+@cindex string, appending (@code{as})
+The @code{as} request is similar to @code{ds} but appends @var{contents}
+to the string stored as @var{name} instead of redefining it.  If
+@var{name} doesn't exist yet, it is created.  If @code{as} is called
+with only one argument, no operation is performed (beyond dereferencing
+the string).
+
+@Example
+.as salutation " with shallots, onions and garlic,\"
+@endExample
+
+The @code{as1} request is similar to @code{as}, but compatibility mode
+is switched off when the appended portion of the string is later
+interpolated.  To be more precise, a @dfn{compatibility save} input
+token is inserted at the beginning of the appended string, and a
+@dfn{compatibility restore} input token at the end.
+@endDefreq
+
+Several requests exist to perform rudimentary string operations.
+Strings can be queried (@code{length}) and modified (@code{chop},
+@code{substring}, @code{stringup}, @code{stringdown}), and their names
+can be manipulated through renaming, removal, and aliasing (@code{rn},
+@code{rm}, @code{als}).
+
+@Defreq {length, reg anything}
+@cindex length of a string (@code{length})
+@cindex string, length of (@code{length})
+@cindex @code{length} request, and copy mode
+@cindex copy mode, and @code{length} request
+@cindex mode, copy, and @code{length} request
+Compute the number of characters of @var{anything} and store the count
+in the register @var{reg}.  If @var{reg} doesn't exist, it is created.
+@var{anything} is read in copy mode.
+
+@Example
+.ds xxx abcd\h'3i'efgh
+.length yyy \*[xxx]
+\n[yyy]
+    @result{} 14
+@endExample
+@endDefreq
+
+@Defreq {chop, object}
+Remove the last character from the macro, string, or diversion named
+@var{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 @var{object}; see @ref{Gtroff Internals},
+for details on nodes inserted additionally by GNU @code{troff}.
+@endDefreq
+
+@Defreq {substring, str start [@Var{end}]}
+@cindex substring (@code{substring})
+Replace the string named @var{str} with its substring bounded by the
+indices @var{start} and @var{end}, inclusively.  The first character in
+the string has index@tie{}0.  If @var{end} is omitted, it is implicitly
+set to the largest valid value (the string length minus one).  Negative
+indices count backward from the end of the string:@: the last character
+has index@tie{}@minus{}1, the character before the last has
+index@tie{}@minus{}2, and so on.
+
+@Example
+.ds xxx abcdefgh
+.substring xxx 1 -4
+\*[xxx]
+    @result{} bcde
+.substring xxx 2
+\*[xxx]
+    @result{} de
+@endExample
+@endDefreq
+
+@DefreqList {stringdown, str}
+@DefreqListEndx {stringup, str}
+@cindex case-transforming a string (@code{stringdown}, @code{stringup})
+@cindex uppercasing a string (@code{stringup})
+@cindex lowercasing a string (@code{stringdown})
+@cindex up-casing a string (@code{stringup})
+@cindex down-casing a string (@code{stringdown})
+Alter the string named @var{str} by replacing each of its bytes with its
+lowercase (@code{stringdown}) or uppercase (@code{stringup}) version (if
+one exists).  Special characters in the string will often transform in
+the expected way due to the regular naming convention for accented
+characters.  When they do not, use substrings and/or catenation.
+
+@Example
+.ds resume R\['e]sum\['e]
+\*[resume]
+.stringdown resume
+\*[resume]
+.stringup resume
+\*[resume]
+    @result{} Résumé résumé RÉSUMÉ
+@endExample
+@endDefreq
+
+(In practice, we would end the @code{ds} request with a comment escape
+@code{\"} to prevent space from creeping into the definition during
+source document maintenance.)
+
+@Defreq {rn, old new}
+@cindex renaming request (@code{rn})
+@cindex request, renaming (@code{rn})
+@cindex renaming macro (@code{rn})
+@cindex macro, renaming (@code{rn})
+@cindex renaming string (@code{rn})
+@cindex string, renaming (@code{rn})
+@cindex renaming diversion (@code{rn})
+@cindex diversion, renaming (@code{rn})
+Rename the request, macro, diversion, or string @var{old} to @var{new}.
+@endDefreq
+
+@Defreq {rm, name}
+@cindex removing request (@code{rm})
+@cindex request, removing (@code{rm})
+@cindex removing macro (@code{rm})
+@cindex macro, removing (@code{rm})
+@cindex removing string (@code{rm})
+@cindex string, removing (@code{rm})
+@cindex removing diversion (@code{rm})
+@cindex diversion, removing (@code{rm})
+Remove the request, macro, diversion, or string @var{name}.  GNU
+@code{troff} treats subsequent invocations as if the name had never
+been defined.
+@endDefreq
+
+@anchor{als}
+@Defreq {als, new old}
+@cindex alias, string, creating (@code{als})
+@cindex alias, macro, creating (@code{als})
+@cindex alias, diversion, creating (@code{als})
+@cindex creating alias, for string (@code{als})
+@cindex creating alias, for macro (@code{als})
+@cindex creating alias, for diversion (@code{als})
+@cindex string, creating alias for (@code{als})
+@cindex macro, creating alias for (@code{als})
+@cindex diversion, creating alias for (@code{als})
+Create an alias @var{new} for the existing request, string, macro, or
+diversion object named @var{old}, causing the names to refer to the same
+stored object.  If @var{old} is undefined, a warning in category
+@samp{mac} is produced, and the request is ignored.  @xref{Warnings},
+for information about the enablement and suppression of warnings.
+
+To understand how the @code{als} request works, consider two different
+storage pools:@: one for objects (macros, strings, etc.), and another
+for names.  As soon as an object is defined, GNU @code{troff} adds it to
+the object pool, adds its name to the name pool, and creates a link
+between them.  When @code{als} creates an alias, it adds a new name to
+the name pool that gets linked to the same object as the old name.
+
+Now consider this example.
+
+@Example
+.de foo
+..
+.
+.als bar foo
+.
+.de bar
+.  foo
+..
+.
+.bar
+    @error{} input stack limit exceeded (probable infinite
+    @error{} loop)
+@endExample
+
+@noindent
+In the above, @code{bar} remains an @emph{alias}---another name
+for---the object referred to by @code{foo}, which the second @code{de}
+request replaces.  Alternatively, imagine that the @code{de} request
+@emph{dereferences} its argument before replacing it.  Either way, the
+result of calling @code{bar} is a recursive loop that finally leads to
+an error.  @xref{Writing Macros}.
+
+@cindex alias, string, removing (@code{rm})
+@cindex alias, macro, removing (@code{rm})
+@cindex alias, diversion, removing (@code{rm})
+@cindex removing alias, for string (@code{rm})
+@cindex removing alias, for macro (@code{rm})
+@cindex removing alias, for diversion (@code{rm})
+@cindex string, removing alias for (@code{rm})
+@cindex macro, removing alias for (@code{rm})
+@cindex diversion, removing alias for (@code{rm})
+To remove an alias, call @code{rm} on its name.  The object itself is
+not destroyed until it has no more names.
+
+When a request, macro, string, or diversion is aliased, redefinitions
+and appendments ``write through'' alias names.  To replace an alias with
+a separately defined object, you must use the @code{rm} request on its
+name first.
+@endDefreq
+@c END Keep (roughly) parallel with section "Strings" of groff(7).
+
+
+@c =====================================================================
+
+@node Conditionals and Loops, Writing Macros, Strings, GNU troff Reference
+@section Conditionals and Loops
+@cindex conditionals and loops
+@cindex loops and conditionals
+
+@code{groff} has @code{if} and @code{while} control structures like
+other languages.  However, the syntax for grouping multiple input lines
+in the branches or bodies of these structures is unusual.
+
+@menu
+* Operators in Conditionals::
+* if-then::
+* if-else::
+* Conditional Blocks::
+* while::
+@end menu
+
+@c ---------------------------------------------------------------------
+
+@c BEGIN Keep (roughly) parallel with subsection "Conditional
+@c expressions" of groff(7).
+@node Operators in Conditionals, if-then, Conditionals and Loops, Conditionals and Loops
+@subsection Operators in Conditionals
+
+@cindex @code{if} request, operators to use with
+@cindex @code{ie} request, operators to use with
+@cindex @code{while} request, operators to use with
+@cindex conditional expressions
+@cindex expressions, conditional
+In @code{if}, @code{ie}, and @code{while} requests, in addition to the
+numeric expressions described in @ref{Numeric Expressions}, several
+Boolean operators are available; the members of this expanded class are
+termed @dfn{conditional expressions}.
+
+@table @code
+@item c @var{glyph}
+True if @var{glyph} is available, where @var{glyph} is an ordinary
+character, a special character @samp{\(@var{xx}} or @samp{\[@var{xxx}]},
+@samp{\N'@var{xxx}'}, or has been defined by any of the @code{char},
+@code{fchar}, @code{fschar}, or @code{schar} requests.
+
+@item d @var{name}
+True if a string, macro, diversion, or request called @var{name} exists.
+
+@item e
+True if the current page is even-numbered.
+
+@item F @var{font}
+True if @var{font} exists.  @var{font} is handled as if it were opened
+with the @code{ft} request (that is, font translation and styles are
+applied), without actually mounting it.
+
+@item m @var{color}
+True if @var{color} is defined.
+
+@item n
+@cindex conditional output for terminal (TTY)
+@cindex TTY, conditional output for
+@cindex terminal, conditional output for
+True if the document is being processed in @code{nroff} mode.
+@xref{@code{troff} and @code{nroff} Modes}.
+
+@item o
+True if the current page is odd-numbered.
+
+@item r @var{register}
+True if @var{register} exists.
+
+@item S @var{style}
+True if @var{style} is available for the current font family.  Font
+translation is applied.
+
+@item t
+True if the document is being processed in @code{troff} mode.
+@xref{@code{troff} and @code{nroff} Modes}.
+
+@pindex vtroff
+@item v
+Always false.  This condition is recognized only for compatibility with
+certain other @code{troff} implementations.@footnote{This refers to
+@code{vtroff}, a translator that would convert the C/A/T output from
+early-vintage @acronym{AT&T} @code{troff} to a form suitable for
+Versatec and Benson-Varian plotters.}
+@end table
+
+If the first argument to an @code{if}, @code{ie}, or @code{while}
+request begins with a non-alphanumeric character apart from @code{!}
+(see below); it performs an @slanted{output comparison test}.
+@footnote{Strictly, letters not otherwise recognized @emph{are} treated
+as output comparison delimiters.  For portability, it is wise to avoid
+using letters not in the list above; for example, Plan@tie{}9
+@code{troff} uses @samp{h} to test a mode it calls @code{htmlroff}, and
+GNU @code{troff} may provide additional operators in the future.}
+
+@cindex output comparison operator
+@table @code
+@item @code{'}@var{xxx}@code{'}@var{yyy}@code{'}
+True if formatting the comparands @var{xxx} and @var{yyy} produces the
+same output commands.  The delimiter need not be a neutral apostrophe:
+the output comparison operator accepts the same delimiters as most
+escape sequences; see @ref{Delimiters}.  This @dfn{output comparison
+operator} formats @var{xxx} and @var{yyy} in separate environments;
+after the comparison, the resulting data are discarded.
+
+@Example
+.ie "|"\fR|\fP" true
+.el false
+    @result{} true
+@endExample
+
+@noindent
+The resulting glyph properties, including font family, style, size, and
+slant, must match, but not necessarily the requests and/or escape
+sequences used to obtain them.  In the previous example, @samp{|} and
+@samp{\fR|\fP} result in @samp{|} glyphs in the same typefaces at the
+same positions, so the comparands are equal.  If @samp{.ft@tie{}I} had
+been added before the @samp{.ie}, they would differ: the first @samp{|}
+would produce an italic @samp{|}, not a roman one.  Motions must match
+in orientation and magnitude to within the applicable horizontal and
+vertical motion quanta of the device, after rounding.  @samp{.if
+"\u\d"\v'0'"} is false even though both comparands result in zero net
+motion, because motions are not interpreted or optimized but sent as-is
+to the output.@footnote{Because formatting of the comparands takes place
+in a dummy environment, vertical motions within them cannot spring
+traps.}  On the other hand, @samp{.if "\d"\v'0.5m'"} is true, because
+@code{\d} is defined as a downward motion of one-half em.@footnote{All
+of this is to say that the lists of output nodes created by formatting
+@var{xxx} and @var{yyy} must be identical.  @xref{Gtroff Internals}.}
+
+@cindex string comparison
+@cindex comparison of strings
+Surround the comparands with @code{\?} to avoid formatting them; this
+causes them to be compared character by character, as with string
+comparisons in other programming languages.
+
+@Example
+.ie "\?|\?"\?\fR|\fP\?" true
+.el false
+    @result{} false
+@endExample
+
+@cindex @code{\?}, and copy mode
+@cindex copy mode, and @code{\?}
+@cindex mode, copy, and @code{\?}
+@noindent
+Since comparands protected with @code{\?} are read in copy mode
+(@pxref{Copy Mode}), they need not even be valid @code{groff} syntax.
+The escape character is still lexically recognized, however, and
+consumes the next character.
+
+@Example
+.ds a \[
+.ds b \[
+.if '\?\*a\?'\?\*b\?' a and b equivalent
+.if '\?\\?'\?\\?' backslashes equivalent
+    @result{} a and b equivalent
+@c slack lines for pagination control
+@c    @error{} warning: missing closing delimiter in
+@c    @error{} conditional expression (got newline)
+@endExample
+@end table
+
+The above operators can't be combined with most others, but a leading
+@samp{!}, not followed immediately by spaces or tabs, complements an
+expression.
+
+@Example
+.nr x 1
+.ie !r x register x is not defined
+.el      register x is defined
+    @result{} register x is defined
+@endExample
+
+Spaces and tabs are optional immediately after the @samp{c}, @samp{d},
+@samp{F}, @samp{m}, @samp{r}, and @samp{S} operators, but right after
+@samp{!}, they end the predicate and the conditional evaluates
+true.@footnote{This bizarre behavior maintains compatibility with
+@acronym{AT&T} @code{troff}.}
+
+@Example
+.nr x 1
+.ie ! r x register x is not defined
+.el       register x is defined
+    @result{} r x register x is not defined
+@endExample
+
+@noindent
+The unexpected @samp{r x} in the output is a clue that our conditional
+was not interpreted as we planned, but matters may not always be so
+obvious.
+@c END Keep (roughly) parallel with subsection "Conditional expressions"
+@c of groff(7).
+
+@c ---------------------------------------------------------------------
+
+@node if-then, if-else, Operators in Conditionals, Conditionals and Loops
+@subsection if-then
+@cindex if-then
+
+@Defreq {if, cond-expr anything}
+Evaluate the conditional expression @var{cond-expr}, and if it evaluates
+true (or to a positive value), interpret the remainder of the line
+@var{anything} as if it were an input line.  Recall from @ref{Invoking
+Requests} that any quantity of spaces between arguments to requests
+serves only to separate them; leading spaces in @var{anything} are thus
+not seen.  @var{anything} effectively @emph{cannot} be omitted; if
+@var{cond-expr} is true and @var{anything} is empty, the newline at the
+end of the control line is interpreted as a blank input line (and
+therefore a blank text line).
+
+@Example
+super\c
+tanker
+.nr force-word-break 1
+super\c
+.if ((\n[force-word-break] = 1) & \n[.int])
+tanker
+    @result{} supertanker super tanker
+@endExample
+@endDefreq
+
+@Defreq {nop, anything}
+Interpret @var{anything} as if it were an input line.  This is similar
+to @samp{.if@tie{}1}.  @code{nop} is not really ``no operation''; its
+argument @emph{is} processed---unconditionally.  It can be used to cause
+text lines to share indentation with surrounding control lines.
+
+@Example
+.als real-MAC MAC
+.de wrapped-MAC
+.  tm MAC: called with arguments \\$@@
+.  nop \\*[real-MAC]\\
+..
+.als MAC wrapped-MAC
+\# Later...
+.als MAC real-MAC
+@endExample
+
+In the above, we've used aliasing, @code{nop}, and the interpolation of
+a macro as a string to interpose a wrapper around the macro @samp{MAC}
+(perhaps to debug it).
+@endDefreq
+
+@c ---------------------------------------------------------------------
+
+@node if-else, while, Operators in Conditionals, Conditionals and Loops
+@subsection if-else
+@cindex if-else
+
+@DefreqList {ie, cond-expr anything}
+@DefreqListEndx {el, anything}
+Use the @code{ie} and @code{el} requests to write an if-then-else.  The
+first request is the ``if'' part and the latter is the ``else'' part.
+Unusually among programming languages, any number of non-conditional
+requests may be interposed between the @code{ie} branch and the
+@code{el} branch.
+
+@Example
+.nr a 0
+.ie \na a is non-zero.
+.nr a +1
+.el a was not positive but is now \na.
+    @result{} a was not positive but is now 1.
+@endExample
+
+Another way in which @code{el} is an ordinary request is that it does
+not lexically ``bind'' more tightly to its @code{ie} counterpart than it
+does to any other request.  This fact can surprise C programmers.
+
+@Example
+.nr a 1
+.nr z 0
+.ie \nz \
+.  ie \na a is true
+.  el     a is false
+.el z is false
+    @error{} warning: unbalanced 'el' request
+    @result{} a is false
+@endExample
+
+@c Turn the following into a proper @{x,}ref if the conditional blocks
+@c node is relocated elsewhere--but consider if it is wise to do so.
+To conveniently nest conditionals, keep reading.
+
+@endDefreq
+
+@c ---------------------------------------------------------------------
+
+@node Conditional Blocks, while, Operators in Conditionals, Conditionals and Loops
+@subsection Conditional Blocks
+@cindex conditional blocks
+@cindex blocks, conditional
+
+It is frequently desirable for a control structure to govern more than
+one request, macro call, text line, or a combination of the foregoing.
+The opening and closing brace escape sequences @code{\@{} and @code{\@}}
+define such groups.  These @dfn{conditional blocks} can furthermore be
+nested.
+
+@DefescList {\@\{, , , }
+@DefescListEnd {\@\}, , , }
+@esindex \@{
+@esindex \@}
+@cindex beginning of conditional block (@code{\@{})
+@cindex end of conditional block (@code{\@}})
+@cindex conditional block, beginning (@code{\@{})
+@cindex conditional block, end (@code{\@}})
+@cindex block, conditional, beginning (@code{\@{})
+@cindex block, conditional, end (@code{\@}})
+@cindex brace escape sequences (@code{\@{}, @code{\@}})
+@cindex escape sequences, brace (@code{\@{}, @code{\@}})
+@cindex opening brace escape sequence (@code{\@}})
+@cindex closing brace escape sequence (@code{\@})}
+@cindex brace escape sequence, opening (@code{\@})}
+@cindex brace escape sequence, closing (@code{\@})}
+@code{\@{} begins a conditional block; it must appear (after optional
+spaces and tabs) immediately subsequent to the conditional expression of
+an @code{if}, @code{ie}, or @code{while}
+request,@footnote{@xref{while}.} or as the argument to an @code{el}
+request.
+
+@code{\@}} ends a condition block and should appear on a line with other
+occurrences of itself as necessary to match @code{\@{} sequences.  It
+can be preceded by a control character, spaces, and tabs.  Input after
+any quantity of @code{\@}} sequences on the same line is processed only
+if all of the preceding conditions to which they correspond are true.
+Furthermore, a @code{\@}} closing the body of a @code{while} request
+must be the last such escape sequence on an input line.
+
+Brace escape sequences outside of control structures have no meaning and
+produce no output.
+
+@strong{Caution:@:} Input lines using @code{\@{} often end with
+@code{\RET}, especially in macros that consist primarily of control
+lines.  Forgetting to use @code{\RET} on an input line after @code{\@{}
+is a common source of error.
+@endDefesc
+
+@need 1000
+We might write the following in a page header macro.  If we delete
+@code{\RET}, the header will carry an unwanted extra empty line (except
+on page@tie{}1).
+
+@Example
+.if (\\n[%] != 1) \@{\
+.  ie ((\\n[%] % 2) = 0) .tl \\*[even-numbered-page-title]
+.  el                    .tl \\*[odd-numbered-page-title]
+.\@}
+@endExample
+
+Let us take a closer look at how conditional blocks nest.
+
+@Example
+A
+.if 0 \@{ B
+C
+D
+\@}E
+F
+    @result{} A F
+@endExample
+
+@Example
+N
+.if 1 \@{ O
+.  if 0 \@{ P
+Q
+R\@} S\@} T
+U
+    @result{} N O U
+@endExample
+
+The above behavior may challenge the intuition; it was implemented to
+retain compatibility with @acronym{AT&T} @code{troff}.  For clarity, it
+is idiomatic to end input lines with @code{\@{} (followed by
+@code{\@key{RET}} if appropriate), and to precede @code{\@}} on an input
+line with nothing more than a control character, spaces, tabs, and other
+instances of itself.
+
+We can use @code{ie}, @code{el}, and conditional blocks to simulate the
+multi-way ``switch'' or ``case'' control structures of other languages.
+The following example is adapted from the @code{groff} @file{man}
+package.  Indentation is used to clarify the logic.
+
+@Example
+.\" Simulate switch/case in roff.
+.      ie '\\$2'1' .ds title General Commands\"
+.el \@{.ie '\\$2'2' .ds title System Calls\"
+.el \@{.ie '\\$2'3' .ds title Library Functions\"
+.el \@{.ie '\\$2'4' .ds title Kernel Interfaces\"
+.el \@{.ie '\\$2'5' .ds title File Formats\"
+.el \@{.ie '\\$2'6' .ds title Games\"
+.el \@{.ie '\\$2'7' .ds title Miscellaneous Information\"
+.el \@{.ie '\\$2'8' .ds title System Management\"
+.el \@{.ie '\\$2'9' .ds title Kernel Development\"
+.el                .ds title \" empty
+.\@}\@}\@}\@}\@}\@}\@}\@}
+@endExample
+
+@c ---------------------------------------------------------------------
+
+@node while,  , if-else, Conditionals and Loops
+@subsection while
+@cindex while
+
+@code{groff} provides a looping construct:@: the @code{while} request.
+Its syntax matches the @code{if} request.
+
+@cindex body, of a while request
+@Defreq {while, cond-expr anything}
+Evaluate the conditional expression @var{cond-expr}, and repeatedly
+execute @var{anything} unless and until @var{cond-expr} evaluates false.
+@var{anything}, which is often a conditional block, is referred to as
+the @code{while} request's @dfn{body}.
+
+@Example
+.nr a 0 1
+.while (\na < 9) \@{\
+\n+a,
+.\@}
+\n+a
+    @result{} 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
+@endExample
+
+@cindex @code{de} request, and @code{while}
+GNU @code{troff} treats the body of a @code{while} request similarly to
+that of a @code{de} request (albeit one not read in copy
+mode@footnote{@xref{Copy Mode}.}), but stores it under an internal name
+and deletes it when the loop finishes.  The operation of a macro
+containing a @code{while} request can slow significantly if the
+@code{while} body is large.  Each time the macro is executed, the
+@code{while} body is parsed and stored again.
+
+@Example
+.de xxx
+.  nr num 10
+.  while (\\n[num] > 0) \@{\
+.    \" many lines of code
+.    nr num -1
+.  \@}
+..
+@endExample
+
+@cindex recursive macros
+@cindex macros, recursive
+@noindent
+An often better solution---and one that is more portable, since
+@acronym{AT&T} @code{troff} lacked the @code{while} request---is to
+instead write a recursive macro.  It will be parsed only
+once.@footnote{unless you redefine it}
+
+@Example
+.de yyy
+.  if (\\n[num] > 0) \@{\
+.    \" many lines of code
+.    nr num -1
+.    yyy
+.  \@}
+..
+.
+.de xxx
+.  nr num 10
+.  yyy
+..
+@endExample
+
+@noindent
+To prevent infinite loops, the default number of available recursion
+levels is 1,000 or somewhat less.@footnote{``somewhat less'' because
+things other than macro calls can be on the input stack}  You can
+disable this protective measure, or raise the limit, by setting the
+@code{slimit} register.  @xref{Debugging}.
+
+As noted above, if a @code{while} body begins with a conditional block,
+its closing brace must end an input line.
+
+@Example
+.if 1 \@{\
+.  nr a 0 1
+.  while (\n[a] < 10) \@{\
+.    nop \n+[a]
+.\@}\@}
+    @error{} unbalanced brace escape sequences
+@endExample
+@endDefreq
+
+@Defreq {break, }
+@cindex @code{while} request, confusing with @code{br}
+@cindex @code{break} request, in a @code{while} loop
+@cindex @code{continue} request, in a @code{while} loop
+Exit a @code{while} loop.  Do not confuse this request with a
+typographical break or the @code{br} request.
+@endDefreq
+
+@Defreq {continue, }
+Skip the remainder of a @code{while} loop's body, immediately starting
+the next iteration.
+@endDefreq
+
+
+@c =====================================================================
+
+@node Writing Macros, Page Motions, Conditionals and Loops, GNU troff Reference
+@section Writing Macros
+@cindex writing macros
+@cindex macros, writing
+
+A @dfn{macro} is a stored collection of text and control lines that can
+be interpolated multiple times.  Use macros to define common operations.
+Macros are called in the same way that requests are invoked.  While
+requests exist for the purpose of creating macros, simply calling an
+undefined macro, or interpolating it as a string, will cause it to be
+defined as empty.  @xref{Identifiers}.
+
+@Defreq {de, name [@Var{end}]}
+Define a macro @var{name}, replacing the definition of any existing
+request, macro, string, or diversion called @var{name}.  If
+@var{name} already exists as an alias, the target of the alias is
+redefined; recall @ref{Strings}.  GNU @code{troff} enters copy
+mode,@footnote{@xref{Copy Mode}.} storing subsequent input lines as the
+macro definition.  If the optional second argument is not specified, the
+definition ends with the control line @samp{..} (two dots).
+Alternatively, @var{end} identifies a macro whose call syntax at the
+start of a control line ends the definition of @var{name}; @var{end} is
+then called normally.  A macro definition must end in the same
+conditional block (if any) in which it began (@pxref{Conditional
+Blocks}).  Spaces or tabs are permitted after the control character in
+the line containing this ending token (either @samp{.} or
+@samp{@var{end}}), but a tab immediately after the token prevents its
+recognition as the end of a macro definition.  The macro @var{end} can
+be called with arguments.@footnote{While it is possible to define and
+call a macro @samp{.}, you can't use it as an end macro: during a macro
+definition, @samp{..} is never handled as calling @samp{.}, even if
+@samp{.de @var{name} .} explicitly precedes it.}
+@c
+@c @Example
+@c .de .
+@c (dot macro)
+@c ..
+@c .
+@c ..    \" This calls macro '.'!
+@c .de m1 .
+@c (m1 macro)
+@c ..    \" This does not.
+@c .m1
+@c     @result{} (dot macro) (m1 macro)
+@c @endExample
+
+Here is a small example macro called @samp{P} that causes a break and
+inserts some vertical space.  It could be used to separate paragraphs.
+
+@Example
+.de P
+.  br
+.  sp .8v
+..
+@endExample
+
+We can define one macro within another.  Attempting to nest @samp{..}
+naïvely will end the outer definition because the inner definition
+isn't interpreted as such until the outer macro is later interpolated.
+We can use an end macro instead.  Each level of nesting should use a
+unique end macro.
+
+An end macro need not be defined until it is called.  This fact enables
+a nested macro definition to begin inside one macro and end inside
+another.  Consider the following example.@footnote{Its structure is
+adapted from, and isomorphic to, part of a solution by Tadziu Hoffman to
+the problem of reflowing text multiple times to find an optimal
+configuration for it.
+@uref{https://lists.gnu.org/archive/html/groff/2008-12/msg00006.html}}
+
+@Example
+.de m1
+.  de m2 m3
+you
+..
+.de m3
+Hello,
+Joe.
+..
+.de m4
+do
+..
+.m1
+know?
+.  m3
+What
+.m4
+.m2
+    @result{} Hello, Joe.  What do you know?
+@endExample
+
+@noindent
+A nested macro definition @emph{can} be terminated with @samp{..} and
+nested macros @emph{can} reuse end macros, but these control lines must
+be escaped multiple times for each level of nesting.  The necessity of
+this escaping and the utility of nested macro definitions will become
+clearer when we employ macro parameters and consider the behavior of
+copy mode in detail.
+@endDefreq
+
+@code{de} defines a macro that inherits the compatibility mode
+enablement status of its context (@pxref{Implementation Differences}).
+Often it is desirable to make a macro that uses @code{groff} features
+callable from contexts where compatibility mode is on; for instance,
+when writing extensions to a historical macro package.  To achieve this,
+compatibility mode needs to be switched off while such a macro is
+interpreted---without disturbing that state when it is finished.
+
+@Defreq {de1, name [@Var{end}]}
+The @code{de1} request defines a macro to be interpreted with
+compatibility mode disabled.  When @var{name} is called, compatibility
+mode enablement status is saved; it is restored when the call completes.
+Observe the extra backlash before the interpolation of register
+@samp{xxx}; we'll explore this subject in @ref{Copy Mode}.
+
+@Example
+.nr xxx 12345
+.de aa
+The value of xxx is \\n[xxx].
+.  br
+..
+.de1 bb
+The value of xxx is \\n[xxx].
+..
+.cp 1
+.aa
+    @error{} warning: register '[' not defined
+    @result{} The value of xxx is 0xxx].
+.bb
+    @result{} The value of xxx is 12345.
+@endExample
+@endDefreq
+
+@DefreqList {dei, name [@Var{end}]}
+@DefreqListEndx {dei1, name [@Var{end}]}
+The @code{dei} request defines a macro with its name and end
+macro indirected through strings.  That is, it interpolates strings
+named @var{name} and @var{end} before performing the definition.
+
+The following examples are equivalent.
+
+@Example
+.ds xx aa
+.ds yy bb
+.dei xx yy
+@endExample
+
+@Example
+.de aa bb
+@endExample
+
+The @code{dei1} request bears the same relationship to @code{dei} as
+@code{de1} does to @code{de}; it temporarily turns compatibility mode
+off when @var{name} is called.
+@endDefreq
+
+@DefreqList {am, name [@Var{end}]}
+@DefreqItemx {am1, name [@Var{end}]}
+@DefreqItemx {ami, name [@Var{end}]}
+@DefreqListEndx {ami1, name [@Var{end}]}
+@cindex appending to a macro (@code{am})
+@cindex macro, appending to (@code{am})
+@code{am} appends subsequent input lines to macro @var{name}, extending
+its definition, and otherwise working as @code{de} does.
+
+To make the previously defined @samp{P} macro set indented instead of
+block paragraphs, add the necessary code to the existing macro.
+
+@Example
+.am P
+.ti +5n
+..
+@endExample
+
+The other requests are analogous to their @samp{de} counterparts.  The
+@code{am1} request turns off compatibility mode during interpretation of
+the appendment.  The @code{ami} request appends indirectly, meaning that
+strings @var{name} and @var{end} are interpolated with the resulting
+names used before appending.  The @code{ami1} request is similar to
+@code{ami}, disabling compatibility mode during interpretation of the
+appended lines.
+@endDefreq
+
+@pindex trace.tmac
+Using @file{trace.tmac}, you can trace calls to @code{de},
+@code{de1}, @code{am}, and @code{am1}.  You can also use the
+@code{backtrace} request at any point desired to troubleshoot tricky
+spots (@pxref{Debugging}).
+
+@xref{Strings}, for the @code{als}, @code{rm}, and @code{rn} requests to
+create an alias of, remove, and rename a macro, respectively.
+
+@cindex object creation
+Macro identifiers share their name space with requests, strings, and
+diversions; see @ref{Identifiers}.  The @code{am}, @code{as}, @code{da},
+@code{de}, @code{di}, and @code{ds} requests (together with their
+variants) create a new object only 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.  @xref{als,,the
+description of the @code{als} request}, for pitfalls when redefining a
+macro that is aliased.
+
+@Defreq {return, [@Var{anything}]}
+Exit a macro, immediately returning to the caller.  If called with an
+argument @var{anything}, exit twice---the current macro and the macro
+one level higher.  This is used to define a wrapper macro for
+@code{return} in @file{trace.tmac}.
+@endDefreq
+
+@menu
+* Parameters::
+* Copy Mode::
+@end menu
+
+@c ---------------------------------------------------------------------
+
+@node Parameters, Copy Mode, Writing Macros, Writing Macros
+@subsection Parameters
+@cindex parameters
+
+Macro calls and string interpolations optionally accept a list of
+arguments; recall @ref{Calling Macros}.  At the time such an
+interpolation takes place, these @dfn{parameters} can be examined using
+a register and a variety of escape sequences starting with @samp{\$}.
+All such escape sequences are interpreted even in copy mode, a fact we
+shall motivate and explain below (@pxref{Copy Mode}).
+
+@Defreg {.$}
+@cindex parameter count register (@code{.$})
+The count of parameters available to a macro or string is kept in this
+read-only register.  The @code{shift} request can change its value.
+@endDefreg
+
+Any individual parameter can be accessed by its position in the list of
+arguments to the macro call, numbered from left to right starting at 1,
+with one of the following escape sequences.
+
+@DefescList {\\$, , n, }
+@DefescItem {\\$, (, nn, }
+@DefescListEnd {\\$, [, nnn, ]}
+Interpolate the @var{n}th, @var{nn}th, or @var{nnn}th parameter.  The
+first form expects only a single digit (1@leq{}@var{n}@leq{}9)), the
+second two digits (01@leq{}@var{nn}@leq{}99)), and the third any
+positive integer @var{nnn}.  Macros and strings accept an unlimited
+number of parameters.
+@endDefesc
+
+@Defreq {shift, [@Var{n}]}
+Shift the parameters @var{n} places (1@tie{}by default).  This is a
+``left shift'': what was parameter@tie{}@var{i} becomes parameter
+@math{@var{i}-@var{n}}.  The parameters formerly in positions 1
+to@tie{}@var{n} are no longer available.  Shifting by a non-positive
+amount performs no operation.  The register @code{.$} is adjusted
+accordingly.
+@endDefreq
+
+@cindex copy mode, and macro parameters
+@cindex mode, copy, and macro parameters
+@cindex macro, parameters (@code{\$})
+@cindex parameters, macro (@code{\$})
+In practice, parameter interpolations are usually seen prefixed with an
+extra escape character.  This is because the @code{\$} family of escape
+sequences is interpreted even in copy mode.@footnote{If they were not,
+parameter interpolations would be similar to command-line
+parameters---fixed for the entire duration of a @code{roff} program's
+run.  The advantage of interpolating @code{\$} escape sequences even in
+copy mode is that they can interpolate different contents from one call
+to the next, like function parameters in a procedural language.  The
+additional escape character is the price of this power.}
+
+@DefescList {\\$*, , , }
+@DefescItemx {\\$@@, , , }
+@DefescListEndx {\\$^, , , }
+In some cases it is convenient to interpolate all of the parameters at
+once (to pass them to a request, for instance).  The @code{\$*} escape
+concatenates the parameters, separating them with spaces.  @code{\$@@}
+is similar, concatenating the parameters, surrounding each with double
+quotes and separating them with spaces.  If not in compatibility mode,
+the interpolation depth of double quotes is preserved (@pxref{Calling
+Macros}).  @code{\$^} interpolates all parameters as if they were
+arguments to the @code{ds} request.
+
+@Example
+.de foo
+. tm $1='\\$1'
+. tm $2='\\$2'
+. tm $*='\\$*'
+. tm $@@='\\$@@'
+. tm $^='\\$^'
+..
+.foo " This is a "test"
+    @error{} $1=' This is a '
+    @error{} $2='test"'
+    @error{} $*=' This is a  test"'
+    @error{} $@@='" This is a " "test""'
+    @error{} $^='" This is a "test"'
+@endExample
+
+@code{\$*} is useful when writing a macro that doesn't need to
+distinguish its arguments, or even to not interpret them; examples
+include macros that produce diagnostic messages by wrapping the
+@code{tm} or @code{ab} requests.  Use @code{\$@@} when writing a macro
+that may need to shift its parameters and/or wrap a macro or request
+that finds the count significant.  If in doubt, prefer @code{\$@@} to
+@code{\$*}.  An application of @code{\$^} is seen in @file{trace.tmac},
+which redefines some requests and macros for debugging purposes.
+@endDefesc
+
+@Defesc {\\$0, , , }
+@cindex macro name register (@code{\$0})
+@cindex @code{als} request, and @code{\$0}
+Interpolate the name by which the macro being interpreted was called.
+The @code{als} request can cause a macro to have more than one name.
+Applying string interpolation to a macro does not change this name.
+
+@Example
+.de foo
+.  tm \\$0
+..
+.als bar foo
+.
+.de aaa
+.  foo
+..
+.de bbb
+.  bar
+..
+.de ccc
+\\*[foo]\\
+..
+.de ddd
+\\*[bar]\\
+..
+.
+.aaa
+    @error{} foo
+.bbb
+    @error{} bar
+.ccc
+    @error{} ccc
+.ddd
+    @error{} ddd
+@endExample
+@endDefesc
+
+@c ---------------------------------------------------------------------
+
+@node Copy Mode, , Parameters, Writing Macros
+@subsection Copy Mode
+@cindex copy mode
+@cindex copy mode
+@cindex mode, copy
+@cindex mode, copy
+
+@cindex @code{\n}, when reading text for a macro
+@cindex @code{\$}, when reading text for a macro
+@cindex @code{\*}, when reading text for a macro
+@cindex \@key{RET}, when reading text for a macro
+When GNU @code{troff} processes certain requests, most importantly those
+which define or append to a macro or string, it does so in @dfn{copy
+mode}: it copies the characters of the definition into a dedicated
+storage region, interpolating the escape sequences @code{\n}, @code{\g},
+@code{\$}, @code{\*}, @code{\V}, and @code{\?} normally; interpreting
+@code{\@key{RET}} immediately; discarding comments @code{\"} and
+@code{\#}; interpolating the current leader, escape, or tab character
+with @code{\a}, @code{\e}, and @code{\t}, respectively; and storing all
+other escape sequences in an encoded form.
+
+@cindex interpretation mode
+@cindex mode, interpretation
+The complement of copy mode---a @code{roff} formatter's behavior when
+not defining or appending to a macro, string, or diversion---where all
+macros are interpolated, requests invoked, and valid escape sequences
+processed immediately upon recognition, can be termed
+@dfn{interpretation mode}.
+
+@Defesc {\\\\, , , }
+The escape character, @code{\} by default, can escape itself.  This
+enables you to control whether a given @code{\n}, @code{\g}, @code{\$},
+@code{\*}, @code{\V}, or @code{\?} escape sequence is interpreted at the
+time the macro containing it is defined, or later when the macro is
+called.@footnote{Compare this to the @code{\def} and @code{\edef}
+commands in @TeX{}.}
+
+@Example
+.nr x 20
+.de y
+.nr x 10
+\&\nx
+\&\\nx
+..
+.y
+    @result{} 20 10
+@endExample
+
+You can think of @code{\\} as a ``delayed'' backslash; it is the escape
+character followed by a backslash from which the escape character has
+removed its special meaning.  Consequently, @samp{\\} is not an escape
+sequence in the usual sense.  In any escape sequence @samp{\@var{X}}
+that GNU @code{troff} does not recognize, the escape character is
+ignored and @var{X} is output.  An unrecognized escape sequence causes
+a warning in category @samp{escape}, with two exceptions---@samp{\\} is
+the first.
+@endDefesc
+
+@cindex @code{\\}, when reading text for a macro
+@Defesc {\\., , , }
+@code{\.} escapes the control character.  It is similar to @code{\\} in
+that it isn't a true escape sequence.  It is used to permit nested macro
+definitions to end without a named macro call to conclude them.  Without
+a syntax for escaping the control character, this would not be possible.
+
+@Example
+.de m1
+foo
+.
+.  de m2
+bar
+\\..
+.
+..
+.m1
+.m2
+    @result{} foo bar
+@endExample
+
+@noindent
+The first backslash is consumed while the macro is read, and the second
+is interpreted when macro @code{m1} is called.
+@endDefesc
+
+@code{roff} documents should not use the @code{\\} or @code{\.}
+character sequences outside of copy mode; they serve only to obfuscate
+the input.  Use @code{\e} to represent the escape character,
+@code{\[rs]} to obtain a backslash glyph, and @code{\&} before @samp{.}
+and @samp{'} where GNU @code{troff} expects them as control characters
+if you mean to use them literally (recall @ref{Requests and Macros}).
+
+Macro definitions can be nested to arbitrary depth.  The mechanics of
+parsing the escape character have significant consequences for this
+practice.
+
+@Example
+.de M1
+\\$1
+.  de M2
+\\\\$1
+.    de M3
+\\\\\\\\$1
+\\\\..
+.    M3 hand.
+\\..
+.  M2 of
+..
+This understeer is getting
+.M1 out
+    @result{} This understeer is getting out of hand.
+@endExample
+
+Each escape character is interpreted twice---once in copy mode, when the
+macro is defined, and once in interpretation mode, when the macro is
+called.  As seen above, this fact leads to exponential growth in the
+quantity of escape characters required to delay interpolation of
+@code{\n}, @code{\g}, @code{\$}, @code{\*}, @code{\V}, and @code{\?} at
+each nesting level, which can be daunting.  GNU @code{troff} offers a
+solution.
+
+@Defesc {\\E, , , }
+@code{\E} represents an escape character that is not interpreted in copy
+mode.  You can use it to ease the writing of nested macro definitions.
+
+@Example
+.de M1
+.  nop \E$1
+.  de M2
+.    nop \E$1
+.    de M3
+.      nop \E$1
+\\\\..
+.    M3 better.
+\\..
+.  M2 bit
+..
+This vehicle handles
+.M1 a
+    @result{} This vehicle handles a bit better.
+@endExample
+
+Observe that because @code{\.} is not a true escape sequence, we can't
+use @code{\E} to keep @samp{..} from ending a macro definition
+prematurely.  If the multiplicity of backslashes complicates
+maintenance, use end macros.
+
+@code{\E} is also convenient to define strings containing escape
+sequences that need to work when used in copy mode (for example, as
+macro arguments), or which will be interpolated at varying macro nesting
+depths.  We might define strings to begin and end superscripting
+as follows.@footnote{These are lightly adapted from the @code{groff}
+implementation of the @file{ms} macros.}
+
+@Example
+.ds @{ \v'-.9m\s'\En[.s]*7u/10u'+.7m'
+.ds @} \v'-.7m\s0+.9m'
+@endExample
+
+When the @code{ec} request is used to redefine the escape character,
+@code{\E} also makes it easier to distinguish the semantics of an escape
+character from the other meaning(s) its character might have.  Consider
+the use of an unusual escape character, @samp{-}.
+
+@Example
+.nr a 1
+.ec -
+.de xx
+--na
+..
+.xx
+    @result{} -na
+@endExample
+
+@noindent
+This result may surprise you; some people expect @samp{1} to be output
+since register @samp{a} has clearly been defined with that value.  What
+has happened?  The robotic replacement of @samp{\} with @samp{-} has led
+us astray.  You might recognize the sequence @samp{--} more readily with
+the default escape character as @samp{\-}, the special character escape
+sequence for the minus sign glyph.
+
+@Example
+.nr a 1
+.ec -
+.de xx
+-Ena
+..
+.xx
+    @result{} 1
+@endExample
+@endDefesc
+
+
+@c =====================================================================
+
+@node Page Motions, Drawing Geometric Objects, Writing Macros, GNU troff Reference
+@section Page Motions
+@cindex page motions
+@cindex motions, page
+
+@xref{Manipulating Spacing}, for a discussion of the most commonly used
+request for vertical motion, @code{sp}, which spaces downward by one
+vee.
+
+@DefreqList {mk, [@Var{reg}]}
+@DefreqListEndx {rt, [@Var{dist}]}
+@cindex marking vertical page location (@code{mk})
+@cindex page location, vertical, marking (@code{mk})
+@cindex location, vertical, page, marking (@code{mk})
+@cindex vertical page location, marking (@code{mk})
+@cindex returning to marked vertical page location (@code{rt})
+@cindex page location, vertical, returning to marked (@code{rt})
+@cindex location, vertical, page, returning to marked (@code{rt})
+@cindex vertical page location, returning to marked (@code{rt})
+You can @dfn{mark} a location on a page for subsequent @dfn{return}.
+@code{mk} takes an argument, a register name in which to store the
+current page location.  If given no argument, it stores the location in
+an internal register.  This location can be used later by the @code{rt}
+or the @code{sp} requests (or the @code{\v} escape).
+
+The @code{rt} request returns @emph{upward} to the location marked with
+the last @code{mk} request.  If used with an argument, it returns to a
+vertical position@tie{}@var{dist} from the top of the page (no previous
+call to @code{mk} is necessary in this case).  The default scaling
+unit is @samp{v}.
+
+If a page break occurs between a @code{mk} request and its matching
+@code{rt} request, the @code{rt} request is silently ignored.
+
+A simple implementation of a macro to set text in two columns follows.
+
+@Example
+.nr column-length 1.5i
+.nr column-gap 4m
+.nr bottom-margin 1m
+.
+.de 2c
+.  br
+.  mk
+.  ll \\n[column-length]u
+.  wh -\\n[bottom-margin]u 2c-trap
+.  nr right-side 0
+..
+.
+.de 2c-trap
+.  ie \\n[right-side] \@{\
+.    nr right-side 0
+.    po -(\\n[column-length]u + \\n[column-gap]u)
+.    \" remove trap
+.    wh -\\n[bottom-margin]u
+.  \@}
+.  el \@{\
+.    \" switch to right side
+.    nr right-side 1
+.    po +(\\n[column-length]u + \\n[column-gap]u)
+.    rt
+.  \@}
+..
+@endExample
+
+Now let us apply our two-column macro.
+
+@Example
+.pl 1.5i
+.ll 4i
+This is a small test that shows how the
+rt request works in combination with mk.
+
+.2c
+Starting here, text is typeset in two columns.
+Note that this implementation isn't robust
+and thus not suited for a real two-column
+macro.
+    @result{} This is a small test that shows how the
+    @result{} rt request works in combination with mk.
+    @result{}
+    @result{} Starting  here,    isn't    robust
+    @result{} text is typeset    and   thus  not
+    @result{} in two columns.    suited  for   a
+    @result{} Note that  this    real two-column
+    @result{} implementation     macro.
+@endExample
+@endDefreq
+
+Several escape sequences enable fine control of movement about the page.
+
+@Defesc {\\v, @code{'}, expr, @code{'}}
+@cindex vertical motion (@code{\v})
+@cindex motion, vertical (@code{\v})
+Vertically move the drawing position.  @var{expr} indicates the
+magnitude of motion: positive is downward and and negative upward.  The
+default scaling unit is @samp{v}.  The motion is relative to the current
+drawing position unless @var{expr} begins with the boundary-relative
+motion operator @samp{|}.  @xref{Numeric Expressions}.
+
+Text processing continues at the new drawing position; usually, vertical
+motions should be in balanced pairs to avoid a confusing page layout.
+
+@code{\v} will not spring a vertical position trap.  This can be useful;
+for example, consider a page bottom trap macro that prints a marker in
+the margin to indicate continuation of a footnote.  @xref{Traps}.
+@endDefesc
+
+A few escape sequences that produce vertical motion are unusual.  They
+are thought to originate early in AT&T @code{nroff} history to achieve
+super- and subscripting by half-line motions on line printers and
+teletypewriters before the phototypesetter made more precise positioning
+available.  They are reckoned in ems---not vees---to maintain continuity
+with their original purpose of moving relative to the size of the type
+rather than the distance between text baselines (vees).@footnote{At the
+@code{grops} defaults of 10-point type on 12-point vertical spacing, the
+difference between half a vee and half an em can be subtle:@: large
+spacings like @samp{.vs .5i} make it obvious.}
+
+@DefescList {\\r, , , }
+@DefescItemx {\\u, , , }
+@DefescListEndx {\\d, , , }
+Move upward@tie{}1@dmn{m}, upward@tie{}.5@dmn{m}, and
+downward@tie{}.5@dmn{m}, respectively.
+@endDefesc
+
+@noindent
+Let us see these escape sequences in use.
+
+@Example
+Obtain 100 cm\u3\d of \ka\d\092\h'|\nau'\r233\dU.
+@endExample
+
+In the foregoing we have paired @code{\u} and @code{\d} to typeset a
+superscript, and later a full em negative (``reverse'') motion to place
+a superscript above a subscript.  A numeral-width horizontal motion
+escape sequence aligns the proton and nucleon numbers, while @code{\k}
+marks a horizontal position to which @code{\h} returns so that we could
+stack them.  (We shall discuss these horizontal motion escape sequences
+presently.)  In serious applications, we often want to alter the type
+size of the -scripts and to fine-tune the vertical motions, as the
+@code{groff} @file{ms} package does with its super- and subscripting
+string definitions.
+
+@Defesc {\\h, @code{'}, expr, @code{'}}
+@cindex inserting horizontal space (@code{\h})
+@cindex horizontal space (@code{\h})
+@cindex space, horizontal (@code{\h})
+@cindex horizontal motion (@code{\h})
+@cindex motion, horizontal (@code{\h})
+Horizontally move the drawing position.  @var{expr} indicates the
+magnitude of motion: positive is rightward and negative leftward.  The
+default scaling unit is @samp{m}.  The motion is relative to the current
+drawing position unless @var{expr} begins with the boundary-relative
+motion operator @samp{|}.  @xref{Numeric Expressions}.
+@endDefesc
+
+The following string definition sets the @TeX{}
+logo.@footnote{@xref{Strings}, for an explanation of the trailing
+@samp{\"}.}
+
+@Example
+.ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X\"
+@endExample
+
+There are a number of special-case escape sequences for horizontal
+motion.
+
+@Defesc {\\@key{SP}, , , }
+@cindex space, unbreakable and unadjustable (@code{\@key{SP}})
+@cindex unbreakable and unadjustable space (@code{\@key{SP}})
+@cindex unadjustable and unbreakable space (@code{\@key{SP}})
+@c We use the following notation in our man pages; Texinfo is bound to
+@c the GNU Emacs dialect.
+@esindex \@slanted{space}
+Move right one word space.  (The input is a backslash followed by a
+space.)  This escape sequence can be thought of as a non-adjustable,
+unbreakable space.  Usually you want @code{\~} instead; see
+@ref{Manipulating Filling and Adjustment}.
+@endDefesc
+
+@cindex thin space (@code{\|})
+@cindex space, thin (@code{\|})
+@Defesc {\\|, , , }
+Move one-sixth @dmn{em} to the right on typesetting output devices.  If
+a glyph named @samp{\|} is defined in the current font, its width is
+used instead, even on terminal output devices.
+@endDefesc
+
+@cindex hair space (@code{\^})
+@cindex space, hair (@code{\^})
+@Defesc {\\^, , , }
+Move one-twelfth @dmn{em} to the right on typesetting output devices.
+If a glyph named @samp{\^} is defined in the current font, its width is
+used instead, even on terminal output devices.
+@endDefesc
+
+@Defesc {\\0, , , }
+@cindex space, width of a digit (numeral) (@code{\0})
+@cindex digit-width space (@code{\0})
+@cindex figure space (@code{\0})
+@cindex numeral-width space (@code{\0})
+Move right by the width of a numeral in the current font.
+@endDefesc
+
+Horizontal motions are not discarded at the end of an output line as
+word spaces are.  @xref{Breaking}.
+
+@DefescList {\\w, @code{'}, anything, @code{'}}
+@DefregItemx {st}
+@DefregItemx {sb}
+@DefregItemx {rst}
+@DefregItemx {rsb}
+@DefregItemx {ct}
+@DefregItemx {ssc}
+@DefregListEndx {skw}
+@cindex width escape (@code{\w})
+Interpolate the width of @var{anything} in basic units.  This escape
+sequence allows several properties of formatted output to be measured
+without writing it out.
+
+@Example
+The length of the string 'abc' is \w'abc'u.
+    @result{} The length of the string 'abc' is 72u.
+@endExample
+
+@cindex dummy environment, used by @code{\w} escape sequence
+@cindex environment, dummy, used by @code{\w} escape sequence
+@var{anything} is processed in a dummy environment:@: this means that
+font and type size changes, for example, may occur within it without
+affecting subsequent output.
+
+@need 500
+After each use, @code{\w} sets several registers.
+
+@cindex CSTR@tie{}#54 errata
+@cindex CSTR@tie{}#54 erratum, @code{sb} register
+@cindex CSTR@tie{}#54 erratum, @code{st} register
+@table @code
+@item st
+@itemx sb
+The maximum vertical displacements of the text baseline above and below,
+respectively.  The sign convention is opposite that of relative vertical
+motions; that is, depth below the (original) baseline is negative.
+These registers are incorrectly documented in the @acronym{AT&T}
+@code{troff} manual as ``the highest and lowest extent of [the argument
+to @code{\w}] relative to the baseline''.
+
+@item rst
+@itemx rsb
+Like @code{st} and @code{sb}, but taking account of the heights and
+depths of glyphs.  In other words, these registers store the highest and
+lowest vertical positions attained by @var{anything}, doing what
+@acronym{AT&T} @code{troff} documented @code{st} and @code{sb} as doing.
+
+@item ct
+Characterizes the geometry of glyphs occurring in @var{anything}.
+
+@table @asis
+@item 0
+only short glyphs, no descenders or tall glyphs
+
+@item 1
+at least one descender
+
+@item 2
+at least one tall glyph
+
+@item 3
+at least one each of a descender and a tall glyph
+@end table
+
+@item ssc
+The amount of horizontal space (possibly negative) that should be added
+to the last glyph before a subscript.
+
+@item skw
+How far to right of the center of the last glyph in the @code{\w}
+argument, the center of an accent from a roman font should be placed
+over that glyph.
+@end table
+@endDefesc
+
+@DefescList {\\k, , p, }
+@DefescItem {\\k, (, ps, }
+@DefescListEnd {\\k, [, position, ]}
+@cindex saving horizontal input line position (@code{\k})
+@cindex horizontal input line position, saving (@code{\k})
+@cindex input line position, horizontal, saving (@code{\k})
+@cindex position, horizontal input line, saving (@code{\k})
+@cindex line, input, horizontal position, saving (@code{\k})
+Store the current horizontal position in the @emph{input} line in a
+register with the name @var{position} (one-character name@tie{}@var{p},
+two-character name @var{ps}).  Use this, for example, to return to the
+beginning of a string for highlighting or other decoration.
+@endDefesc
+
+@Defreg {hp}
+@cindex horizontal input line position register (@code{hp})
+@cindex input line, horizontal position, register (@code{hp})
+@cindex position, horizontal, in input line, register (@code{hp})
+@cindex line, input, horizontal position, register (@code{hp})
+The current horizontal position at the input line.
+@endDefreg
+
+@Defreg {.k}
+@cindex horizontal output line position register (@code{.k})
+@cindex output line, horizontal position, register (@code{.k})
+@cindex position, horizontal, in output line, register (@code{.k})
+@cindex line, output, horizontal position, register (@code{.k})
+A read-only register containing the current horizontal output position
+(relative to the current indentation).
+@endDefreg
+
+@Defesc {\\o, @code{'}, abc@dots{}, @code{'}}
+@cindex overstriking glyphs (@code{\o})
+@cindex glyphs, overstriking (@code{\o})
+Overstrike the glyphs of characters @var{a}, @var{b}, @var{c}, @dots{};
+the glyphs are centered, written, and the drawing position advanced by
+the widest of the glyphs.
+@endDefesc
+
+@Defesc {\\z, , c, }
+@cindex zero-width printing (@code{\z}, @code{\Z})
+@cindex printing, zero-width (@code{\z}, @code{\Z})
+Format the character @var{c} with zero width; that is, without advancing
+the drawing position.  Use @code{\z} to overstrike glyphs aligned to
+their left edges, in contrast to @code{\o}'s centering.
+@endDefesc
+
+@Defesc {\\Z, @code{'}, anything, @code{'}}
+@cindex zero-width printing (@code{\z}, @code{\Z})
+@cindex printing, zero-width (@code{\z}, @code{\Z})
+Save the drawing position, format @var{anything}, then restore it.  Tabs
+and leaders in the argument are ignored with an error diagnostic.
+
+We might implement a strike-through macro thus.
+
+@Example
+.de ST
+.nr width \w'\\$1'
+\Z@@\v'-.25m'\l'\\n[width]u'@@\\$1
+..
+.
+This is
+.ST "a test"
+an actual emergency!
+@endExample
+@endDefesc
+
+
+@c =====================================================================
+
+@node Drawing Geometric Objects, Traps, Page Motions, GNU troff Reference
+@section Drawing Geometric Objects
+@cindex drawing requests
+@cindex requests for drawing
+
+A few of the formatter's escape sequences draw lines and other geometric
+objects.  Combined with each other and with page motion commands
+(@pxref{Page Motions}), a wide variety of figures is possible.  For
+complex drawings, these operations can be cumbersome; the preprocessors
+@code{gpic} or @code{ggrn} are typically used instead.
+
+The @code{\l} and @code{\L} escape sequences draw horizontal and
+vertical sequences of glyphs, respectively.  Even the simplest of
+output devices supports them.
+
+@DefescList {\\l, @code{'}, l, @code{'}}
+@DefescListEnd {\\l, @code{'}, lc, @code{'}}
+@cindex drawing horizontal lines (@code{\l})
+@cindex horizontal line, drawing (@code{\l})
+@cindex line, horizontal, drawing (@code{\l})
+Draw a horizontal line of length @var{l} from the drawing position.
+Rightward motion is positive.  Afterward, the drawing position is at the
+right end of the line.  The default scaling unit is @samp{m}.
+
+@cindex baseline rule special character(@code{\[ru]})
+@cindex glyph, underscore (@code{\[ru]})
+@cindex line drawing glyph
+@cindex glyph, for line drawing
+The optional second parameter@tie{}@var{c} is a character with which to
+draw the line.  The default is the baseline rule special character,
+@code{\[ru]}.
+
+@cindex dummy character (@code{\&}), effect on @code{\l} escape sequence
+@cindex character, dummy (@code{\&}), effect on @code{\l} escape sequence
+If @var{c} is a valid scaling unit, put @code{\&} after @var{l} to
+disambiguate the input.
+
+@Example
+.de textbox
+\[br]\\$*\[br]\l'|0\[rn]'\l'|0\[ul]'
+..
+@endExample
+
+@noindent
+The foregoing outputs a box rule (a vertical line), the text
+argument(s), and another box rule.  We employ the boundary-relative
+motion operator @samp{|}.  Finally, the line-drawing escape sequences
+draw a radical extender (a form of overline) and an underline from the
+drawing position to the position coresponding to beginning of the
+@emph{input} line.  The drawing position returns to just after the
+right-hand box rule because the lengths of the drawn lines are negative,
+as noted above.
+@endDefesc
+
+@DefescList {\\L, @code{'}, l, @code{'}}
+@DefescListEnd {\\L, @code{'}, lc, @code{'}}
+@cindex drawing vertical lines (@code{\L})
+@cindex vertical line drawing (@code{\L})
+@cindex line, vertical, drawing (@code{\L})
+@cindex line drawing glyph
+@cindex glyph for line drawing
+@cindex box rule glyph (@code{\[br]})
+@cindex glyph, box rule (@code{\[br]})
+Draw a vertical line of length @var{l} from the drawing position.
+Downward motion is positive.  The default scaling unit is @samp{v}.  The
+default character is the box rule, @code{\[br]}.  As with vertical
+motion escape sequences, text processing continues where the line ends.
+@code{\L} is otherwise similar to @code{\l}.
+
+@Example
+$ nroff <<EOF
+This is a \L'3v'test.
+EOF
+    @result{} This is a
+    @result{}           |
+    @result{}           |
+    @result{}           |test.
+@endExample
+
+@noindent
+When writing text, the drawing position is at the text baseline; recall
+@ref{Page Geometry}.
+@endDefesc
+
+@c BEGIN Keep (roughly) parallel with subsection "Drawing commands" of
+@c groff(7).
+The @code{\D} escape sequence provides @dfn{drawing commands} that
+direct the output device to render geometrical objects rather than
+glyphs.  Specific devices may support only a subset, or may feature
+additional ones; consult the man page for the output driver in use.
+Terminal devices in particular implement almost none.  @xref{Graphics
+Commands}.
+
+Rendering starts at the drawing position; when finished, the drawing
+position is left at the rightmost point of the object, even for closed
+figures, except where noted.  GNU @code{troff} draws stroked (outlined)
+objects with the stroke color, and shades filled ones with the fill
+color.  @xref{Colors}.  Coordinates @var{h} and @var{v} are horizontal
+and vertical motions relative to the drawing position or previous point
+in the command.  The default scaling unit for horizontal measurements
+(and diameters of circles) is @samp{m}; for vertical ones, @samp{v}.
+
+Circles, ellipses, and polygons can be drawn filled or stroked.  These
+are independent properties; if you want a filled, stroked figure, you
+must draw the same figure twice using each drawing command.  A filled
+figure is always smaller than an outlined one because the former is
+drawn only within its defined area, whereas strokes have a line
+thickness (set with @samp{\D't'}).
+
+@Example
+\h'1i'\v'1i'\
+\# increase line thickness
+\Z'\D't 5p''\
+\# draw stroked (unfilled) polygon
+\Z'\D'p 3 3 -6 0''\
+\# draw filled (solid) polygon
+\Z'\D'P 3 3 -6 0''
+@endExample
+
+@need 500
+@Defesc {\\D, @code{'}, command argument @dots{}, @code{'}}
+Drawing command escape sequence parameters begin with an ordinary
+character, @var{command}, selecting the type of object to be drawn,
+followed by @var{argument}s whose meaning is determined by
+@var{command}.
+
+@table @code
+@item \D'~ @var{h1} @var{v1} @dots{} @var{hn} @var{vn}'
+@cindex drawing a spline (@samp{\D'~ @dots{}'})
+@cindex spline, drawing (@samp{\D'~ @dots{}'})
+Draw a B-spline to each point in sequence, leaving the drawing position
+at (@var{hn}, @var{vn}).
+
+@item \D'a @var{hc} @var{vc} @var{h} @var{v}'
+@cindex arc, drawing (@samp{\D'a @dots{}'})
+@cindex drawing an arc (@samp{\D'a @dots{}'})
+Draw a circular arc centered at (@var{hc}, @var{vc}) counterclockwise
+from the drawing position to a point (@var{h}, @var{v}) relative to the
+center.  @footnote{(@var{hc}, @var{vc}) is adjusted to the point nearest
+the perpendicular bisector of the arc's chord.}
+
+@item \D'c @var{d}'
+@cindex circle, stroked, drawing (@samp{\D'c @dots{}'})
+@cindex drawing a stroked circle (@samp{\D'c @dots{}'})
+@cindex stroked circle, drawing (@samp{\D'c @dots{}'})
+@cindex circle, outlined, drawing (@samp{\D'c @dots{}'})
+@cindex drawing an outlined circle (@samp{\D'c @dots{}'})
+@cindex outlined circle, drawing (@samp{\D'c @dots{}'})
+Draw a circle of diameter @var{d} with its leftmost point at the drawing
+position.
+
+@item \D'C @var{d}'
+@cindex circle, filled, drawing (@samp{\D'C @dots{}'})
+@cindex drawing a filled circle (@samp{\D'C @dots{}'})
+@cindex filled circle, drawing (@samp{\D'C @dots{}'})
+@cindex circle, solid, drawing (@samp{\D'C @dots{}'})
+@cindex drawing a solid circle (@samp{\D'C @dots{}'})
+@cindex solid circle, drawing (@samp{\D'C @dots{}'})
+As @samp{\D'C @r{@dots{}}'}, but the circle is filled.
+
+@item \D'e @var{h} @var{v}'
+@cindex ellipse, stroked, drawing (@samp{\D'e @dots{}'})
+@cindex drawing a stroked ellipse (@samp{\D'e @dots{}'})
+@cindex stroked ellipse, drawing (@samp{\D'e @dots{}'})
+@cindex ellipse, outlined, drawing (@samp{\D'e @dots{}'})
+@cindex drawing an outlined ellipse (@samp{\D'e @dots{}'})
+@cindex outlined ellipse, drawing (@samp{\D'e @dots{}'})
+Draw an ellipse of width @var{h} and height @var{v} with its leftmost
+point at the drawing position.
+
+@item \D'E @var{x} @var{y}'
+@cindex ellipse, filled, drawing (@samp{\D'E @dots{}'})
+@cindex drawing a filled ellipse (@samp{\D'E @dots{}'})
+@cindex filled ellipse, drawing (@samp{\D'E @dots{}'})
+@cindex ellipse, solid, drawing (@samp{\D'E @dots{}'})
+@cindex drawing a solid ellipse (@samp{\D'E @dots{}'})
+@cindex solid ellipse, drawing (@samp{\D'E @dots{}'})
+As @samp{\D'e @r{@dots{}}'}, but the ellipse is filled.
+
+@item \D'l @var{dx} @var{dy}'
+@cindex line, drawing (@samp{\D'l @dots{}'})
+@cindex drawing a line (@samp{\D'l @dots{}'})
+Draw line from the drawing position to (@var{h}, @var{v}).
+
+The following is a macro for drawing a box around a text argument; for
+simplicity, the box margin is a fixed at 0.2@dmn{m}.
+
+@Example
+.de TEXTBOX
+.  nr @@wd \w'\\$1'
+\h'.2m'\
+\h'-.2m'\v'(.2m - \\n[rsb]u)'\
+\D'l 0 -(\\n[rst]u - \\n[rsb]u + .4m)'\
+\D'l (\\n[@@wd]u + .4m) 0'\
+\D'l 0 (\\n[rst]u - \\n[rsb]u + .4m)'\
+\D'l -(\\n[@@wd]u + .4m) 0'\
+\h'.2m'\v'-(.2m - \\n[rsb]u)'\
+\\$1\
+\h'.2m'
+..
+@endExample
+
+@noindent
+The argument is measured with the @code{\w} escape sequence.  Its width
+is stored in register @code{@@wd}.  @code{\w} also sets the registers
+@code{rst} and @code{rsb}; these contain its maximum vertical extents of
+the argument.  Then, four lines are drawn to form a box, offset by the
+box margin.
+
+@item \D'p @var{h1} @var{v1} @dots{} @var{hn} @var{vn}'
+@cindex polygon, stroked, drawing (@samp{\D'p @dots{}'})
+@cindex drawing a stroked polygon (@samp{\D'p @dots{}'})
+@cindex stroked polygon, drawing (@samp{\D'p @dots{}'})
+@cindex polygon, outlined, drawing (@samp{\D'p @dots{}'})
+@cindex drawing an outlined polygon (@samp{\D'p @dots{}'})
+@cindex outlined polygon, drawing (@samp{\D'p @dots{}'})
+Draw polygon with vertices at drawing position and each point in
+sequence.  GNU @code{troff} closes the polygon by drawing a line from
+(@var{hn}, @var{vn}) back to the initial drawing position.
+@c XXX: This would be the "STUPID_DRAWING_POSITIONING" complained of in
+@c src/libs/libdriver/input.cpp.  It is neither the rightmost point
+@c of the figure nor the initial drawing position that GNU troff
+@c automatically returned to to close the figure.
+Afterward, the drawing position is left at (@var{hn}, @var{vn}).
+
+@item \D'P @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}'
+@cindex polygon, filled, drawing (@samp{\D'P @dots{}'})
+@cindex drawing a filled polygon (@samp{\D'P @dots{}'})
+@cindex filled polygon, drawing (@samp{\D'P @dots{}'})
+@cindex polygon, solid, drawing (@samp{\D'P @dots{}'})
+@cindex drawing a solid polygon (@samp{\D'P @dots{}'})
+@cindex solid polygon, drawing (@samp{\D'P @dots{}'})
+As @samp{\D'P @r{@dots{}}'}, but the polygon is filled.
+
+The following macro is like the @samp{\D'l'} example, but shades the
+box.  We draw the box before writing the text because colors in GNU
+@code{troff} have no transparency; in othe opposite order, the filled
+polygon would occlude the text.
+
+@Example
+.de TEXTBOX
+.  nr @@wd \w'\\$1'
+\h'.2m'\
+\h'-.2m'\v'(.2m - \\n[rsb]u)'\
+\M[lightcyan]\
+\D'P 0 -(\\n[rst]u - \\n[rsb]u + .4m) \
+     (\\n[@@wd]u + .4m) 0 \
+     0 (\\n[rst]u - \\n[rsb]u + .4m) \
+     -(\\n[@@wd]u + .4m) 0'\
+\h'.2m'\v'-(.2m - \\n[rsb]u)'\
+\M[]\
+\\$1\
+\h'.2m'
+..
+@endExample
+
+@item \D't @var{n}'
+@cindex line thickness (@samp{\D't @dots{}'})
+@cindex thickness of lines (@samp{\D't @dots{}'})
+Set the stroke thickness of geometric objects to @var{n} basic units.  A
+zero @var{n} selects the minimal supported thickness.  A negative
+@var{n} selects a thickness proportional to the type size; this is the
+default.
+@end table
+@endDefesc
+@c END Keep (roughly) parallel with subsection "Drawing commands" of
+@c groff(7).
+
+In a hazy penumbra between text rendering and drawing commands we locate
+the bracket-building escape sequence, @code{\b}.  It can assemble
+apparently large glyphs by vertically stacking ordinary ones.
+
+@Defesc {\\b, @code{'}, contents, @code{'}}
+@cindex pile, glyph (@code{\b})
+@cindex glyph pile (@code{\b})
+@cindex stacking glyphs (@code{\b})
+Pile and center a sequence of glyphs vertically on the output line.
+@dfn{Piling} stacks glyphs corresponding to each character in
+@var{contents}, read from left to right, and placed from top to bottom.
+GNU @code{troff} separates the glyphs vertically by 1@dmn{m}, and the
+pile itself is centered 0.5@dmn{m} above the text baseline.  The
+horizontal drawing position is then advanced by the width of the widest
+glyph in the pile.
+
+@cindex @code{\b}, limitations of
+@cindex limitations of @code{\b} escape sequence
+This rather inflexible positioning algorithm doesn't work with the
+@code{dvi} output device since its bracket pieces vary in height.
+Instead, use the @code{geqn} preprocessor.
+
+@ref{Manipulating Spacing} describes how to adjust the vertical spacing
+of the output line with the @code{\x} escape sequence.
+
+The application of @code{\b} that lends its name is construction of
+brackets, braces, and parentheses when typesetting mathematics.  We
+might construct a large opening (left) brace as follows.
+
+@Example
+\b'\[lt]\[bv]\[lk]\[bv]\[lb]'
+@endExample
+
+See @cite{groff_char@r{(7)}} for a list of special character
+identifiers.
+@endDefesc
+
+
+@c =====================================================================
+
+@node Deferring Output, Traps, Drawing Geometric Objects, GNU troff Reference
+@section Deferring Output
+@cindex deferred output
+
+@cindex environment
+@cindex diversion
+@cindex trap
+A few @code{roff} language elements are generally not used in simple
+documents, but arise as page layouts become more sophisticated and
+demanding.  @dfn{Environments} collect formatting parameters like line
+length and typeface.  A @dfn{diversion} stores formatted output for
+later use.  A @dfn{trap} is a condition on the input or output, tested
+automatically by the formatter, that is associated with a macro, causing
+it to be called when that condition is fulfilled.
+
+Footnote support often exercises all three of the foregoing features.  A
+simple implementation might work as follows.  A pair of macros is
+defined: one starts a footnote and the other ends it.  The author calls
+the first macro where a footnote marker is desired.  The macro
+establishes a diversion so that the footnote text is collected at the
+place in the body text where its corresponding marker appears.  An
+environment is created for the footnote so that it is set at a smaller
+typeface.  The footnote text is formatted in the diversion using that
+environment, but it does not yet appear in the output.  The document
+author calls the footnote end macro, which returns to the previous
+environment and ends the diversion.  Later, after much more body text in
+the document, a trap, set a small distance above the page bottom, is
+sprung.  The macro called by the trap draws a line across the page and
+emits the stored diversion.  Thus, the footnote is rendered.
+
+Diversions and traps make the text formatting process non-linear.  Let
+us imagine a set of text lines or paragraphs labelled @samp{A},
+@samp{B}, and so on.  If we set up a trap that produces text @samp{T}
+(as a page footer, say), and we also use a diversion to store the
+formatted text @samp{D}, then a document with input text in the order
+@samp{A B C D E F} might render as @samp{A B C E T F}.  The diversion
+@samp{D} will never be output if we do not call for it.
+
+Environments of themselves are not a source of non-linearity in document
+formatting:@: environment switches have immediate effect.  One could
+always write a macro to change as many formatting parameters as desired
+with a single convenient call.  But because diversions can be nested and
+macros called by traps that are sprung by other trap-called macros, they
+may be called upon in varying contexts.  For example, consider a page
+header that is always to be set in Helvetica.  A document that uses
+Times for most of its body text, but Courier for displayed code
+examples, poses a challenge if a page break occurs in the middle of a
+code display; if the header trap assumes that the ``previous font'' is
+always Times, the rest of the example will be formatted in the wrong
+typeface.  One could carefully save all formatting parameters upon
+entering the trap and restore them upon leaving it, but this is verbose,
+error-prone, and not future-proof as the @code{groff} language develops.
+Environments save us considerable effort.
+
+@c =====================================================================
+
+@need 1000
+@c BEGIN Keep (roughly) parallel with subsection "Traps" of groff(7).
+@node Traps, Diversions, Deferring Output, GNU troff Reference
+@section Traps
+@cindex traps
+
+@dfn{Traps} are locations in the output or conditions on the input that,
+when reached or fulfilled, call a specified macro.  These traps can
+occur at a given location on the page, at a given location in the
+current diversion (together, these are known as @slanted{vertical
+position traps}), at a blank line, at a line with leading space
+characters, after a quantity of input lines, or at the end of input.
+Macros called by traps are passed no arguments.
+@cindex planting a trap
+@cindex trap, planting
+Setting a trap is also called @dfn{planting} one.
+@cindex trap, springing
+@cindex springing a trap
+It is said that a trap is @dfn{sprung} if its condition is fulfilled.
+@c END Keep (roughly) parallel with subsection "Traps" of groff(7).
+
+@menu
+* Vertical Position Traps::
+* Diversion Traps::
+* Input Line Traps::
+* Blank Line Traps::
+* Leading Space Traps::
+* End-of-input Traps::
+@end menu
+
+@c ---------------------------------------------------------------------
+
+@node Vertical Position Traps, Page Location Traps, Traps, Traps
+@subsection Vertical Position Traps
+@cindex vertical position traps
+@cindex traps, vertical position
+
+A @dfn{vertical position trap} calls a macro when the formatter's
+vertical drawing position reaches or passes, in the downward direction,
+a certain location on the output page or in a diversion.  Its
+applications include setting page headers and footers, body text in
+multiple columns, and footnotes.
+
+@DefreqList {vpt, [@Var{flag}]}
+@DefregListEndx {.vpt}
+@cindex enabling vertical position traps (@code{vpt})
+@cindex vertical position traps, enabling (@code{vpt})
+@cindex vertical position trap enable register (@code{.vpt})
+Enable vertical position traps if @var{flag} is non-zero or absent;
+disable them otherwise.  Vertical position traps are those set by the
+@code{wh} request or by @code{dt} within a diversion.  The parameter
+that controls whether vertical position traps are enabled is global.
+Initially, vertical position traps are enabled.  The current value is
+stored in the @code{.vpt} read-only register.
+
+@cindex page break, prevented by @code{vpt}
+@cindex break, page, prevented by @code{vpt}
+@cindex page ejection, prevented by @code{vpt}
+@cindex ejection, page, prevented by @code{vpt}
+A page can't be ejected if @code{vpt} is set to zero; see @ref{The
+Implicit Page Trap}.
+@endDefreq
+
+@menu
+* Page Location Traps::
+* The Implicit Page Trap::
+* Diversion Traps::
+@end menu
+
+@c ---------------------------------------------------------------------
+
+@node Page Location Traps, The Implicit Page Trap, Vertical Position Traps, Vertical Position Traps
+@subsubsection Page Location Traps
+@cindex page location traps
+@cindex traps, page location
+
+A @dfn{page location trap} is a vertical position trap that applies to
+the page; that is, to undiverted output.  Many can be present; manage
+them with the @code{wh} and @code{ch} requests.
+
+@Defreq {wh, dist [@Var{name}]}
+Plant macro @var{name} as page location trap at @var{dist}.  The default
+scaling unit is @samp{v}.  Non-negative values for @var{dist} set the
+trap relative to the top of the page; negative values set the trap
+relative to the bottom of the page.  It is not possible to plant a trap
+less than one basic unit from the page bottom: a @var{dist} of @code{-0}
+is interpreted as @code{0}, the top of the page.@footnote{@xref{The
+Implicit Page Trap}.}  An existing @emph{visible} trap (see below) at
+@var{dist} is removed; this is @code{wh}'s sole function if @var{name}
+is missing.
+
+A trap is sprung only if it is @dfn{visible}, meaning that its location
+is reachable on the page@footnote{A trap planted at @samp{20i} or
+@samp{-30i} will not be sprung on a page of length @samp{11i}.} and it
+is not hidden by another trap at the same location already planted
+there.
+
+@need 1000
+@cindex page headers
+@cindex page footers
+@cindex headers
+@cindex footers
+@cindex top margin
+@cindex margin, top
+@cindex bottom margin
+@cindex margin, bottom
+A macro package might set headers and footers as follows; this example
+configures vertical margins of one inch to the body text, and one
+half-inch to the titles.  Observe the use of the no-break control
+character with @code{sp} request to position our text baselines,
+and the page number character @samp{%} used with the @code{tl} request.
+
+@Example
+.\" hdfo.roff
+.de hd                  \" page header
+'  sp .5i
+'  tl '\\*(Ti''\\*(Da'  \" title and date strings
+'  sp .5i
+..
+.de fo                  \" page footer
+'  sp .5i
+.  tl ''%''
+.  bp
+..
+.wh 0   hd             \" trap at top of the page
+.wh -1i fo             \" trap 1 inch from bottom
+@endExample
+
+To use these traps, copy the above (or load it from a file with the
+@code{so} or @code{mso} requests), then set up the strings it uses.
+
+@Example
+.so hdfo.roff
+.ds Ti Final Report\"
+.ds Da 21 May 2023\"
+.ti
+On 5 August of last year,
+this committee tasked me with the investigation of the
+CFIT (controlled flight into terrain) incident of
+.\" @i{...and so on...}
+@endExample
+
+A trap above the top or at or below the bottom of the page can be made
+visible by either moving it into the page area or increasing the page
+length so that the trap is on the page.  Negative trap values always use
+the @emph{current} page length; they are not converted to an absolute
+vertical position.
+@cindex page location traps, debugging
+@cindex debugging page location traps
+We can use the @code{ptr} request to dump our page location traps to the
+standard error stream (@pxref{Debugging}).  Their positions are reported
+in basic units; an @code{nroff} device example follows.
+
+@Example
+.pl 5i
+.wh -1i xx
+.ptr
+    @error{} xx      -240
+.pl 100i
+.ptr
+    @error{} xx      -240
+@endExample
+
+It is possible to have more than one trap at the same location (although
+only one at a time can be visible); to achieve this, the traps must be
+defined at different locations, then moved to the same place with the
+@code{ch} request.  In the following example, the many empty lines
+caused by the @code{bp} request are not shown in the output.
+
+@Example
+.de a
+.  nop a
+..
+.de b
+.  nop b
+..
+.de c
+.  nop c
+..
+.
+.wh 1i a
+.wh 2i b
+.wh 3i c
+.bp
+    @result{} a b c
+@endExample
+@Example
+.ch b 1i
+.ch c 1i
+.bp
+    @result{} a
+@endExample
+@Example
+.ch a 0.5i
+.bp
+    @result{} a b
+@endExample
+@endDefreq
+
+@Defreg {.t}
+@cindex distance to next vertical position trap register (@code{.t})
+@cindex trap, distance to next vertical position, register (@code{.t})
+The read-only register @code{.t} holds the distance to the next vertical
+position trap.  If there are no traps between the current position and
+the bottom of the page, it contains the distance to the page bottom.
+Within a diversion, in the absence of a diversion trap, this distance is
+the largest representable integer in basic units---effectively infinite.
+@endDefreg
+
+@Defreq {ch, name [@Var{dist}]}
+@cindex changing trap location (@code{ch})
+@cindex trap, changing location (@code{ch})
+Change the location of a trap by moving macro @var{name} to new location
+@var{dist}, or by unplanting it altogether if @var{dist} is absent.  The
+default scaling unit is @samp{v}.  Parameters to @code{ch} are specified
+in the opposite order from @code{wh}.  If @var{name} is the earliest
+planted macro of multiple traps at the same location, (re)moving it from
+that location exposes the macro next least recently planted at the same
+place.@footnote{It may help to think of each trap location as
+maintaining a queue; @code{wh} operates on the head of the queue, and
+@code{ch} operates on its tail.  Only the trap at the head of the queue
+is visible.}
+
+Changing a trap's location is useful for building up footnotes in a
+diversion to allow more space at the bottom of the page for them.
+
+@c XXX
+
+@ignore
+@Example
+... (simplified) footnote example ...
+@endExample
+@end ignore
+@endDefreq
+
+The same macro can be installed simultaneously at multiple locations;
+however, only the earliest-planted instance---that has not yet been
+deleted with @code{wh}---will be moved by @code{ch}.  The following
+example (using an @code{nroff} device) illustrates this behavior.  Blank
+lines have been elided from the output.
+
+@Example
+.de T
+Trap sprung at \\n(nlu.
+.br
+..
+.wh 1i T
+.wh 2i T
+foo
+.sp 11i
+.bp
+.ch T 4i
+bar
+.sp 11i
+.bp
+.ch T 5i
+baz
+.sp 11i
+.bp
+.wh 5i
+.ch T 6i
+qux
+.sp 11i
+@endExample
+@Example
+    @result{} foo
+    @result{} Trap sprung at 240u.
+    @result{} Trap sprung at 480u.
+    @result{} bar
+    @result{} Trap sprung at 480u.
+    @result{} Trap sprung at 960u.
+    @result{} baz
+    @result{} Trap sprung at 480u.
+    @result{} Trap sprung at 1200u.
+    @result{} qux
+    @result{} Trap sprung at 1440u.
+@endExample
+
+@Defreg {.ne}
+The read-only register @code{.ne} contains the amount of space that was
+needed in the last @code{ne} request that caused a trap to be sprung;
+it is useful in conjunction with the @code{.trunc} register.  @xref{Page
+Control}.  Since the @code{.ne} register is set only by traps, it
+doesn't make sense to interpolate it outside of macros called by traps.
+@endDefreg
+
+@Defreg {.trunc}
+@cindex @code{ne} request, and the @code{.trunc} register
+@cindex truncated vertical space register (@code{.trunc})
+A read-only register containing the amount of vertical space truncated
+from an @code{sp} request by the most recently sprung vertical
+position trap, or, if the trap was sprung by an @code{ne} request,
+minus the amount of vertical motion produced by the @code{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 vertical position actually is.
+Since the @code{.trunc} register is set only by traps, it doesn't make
+sense to interpolate it outside of macros called by traps.
+@endDefreg
+
+@Defreg {.pe}
+@cindex @code{bp} request, and traps (@code{.pe})
+@cindex traps, sprung by @code{bp} request (@code{.pe})
+@cindex page ejection status register (@code{.pe})
+This Boolean-valued, read-only register interpolates@tie{}1 while a page
+is being ejected, and 0@tie{}otherwise.
+
+In the following example, we plant the same trap at the top and the
+bottom of the page.  We also make the trap report its name and the
+vertical drawing position.
+
+@Example
+.de T
+.tm \\$0: page \\n%, nl=\\n[nl] .pe=\\n[.pe]
+..
+.ll 46n
+.wh 0 T
+.wh -1v T
+Those who can make you believe absurdities can make you
+commit atrocities. \[em] Voltaire
+    @error{} T: page 1, nl=0 .pe=0
+    @error{} T: page 1, nl=2600 .pe=1
+    @result{} Those who can make you believe absurdities can
+    @result{} make you commit atrocities. -- Voltaire
+@endExample
+@endDefreg
+
+@cindex diversions, and traps
+@cindex traps, and diversions
+When designing macros, keep in mind that diversions and traps do
+normally interact.  For example, if a trap calls a header macro (while
+outputting a diversion) that tries to change the font on the current
+page, the effect is not visible before the diversion has completely been
+printed (except for input protected with @code{\!} or @code{\?}) since
+the data in the diversion is already formatted.  In most cases, this is
+not the expected behaviour.
+
+@c ---------------------------------------------------------------------
+
+@c BEGIN Keep (roughly) parallel with subsection "The implicit page
+@c trap" of groff(7).
+@node The Implicit Page Trap, Diversion Traps, Page Location Traps, Vertical Position Traps
+@subsubsection The Implicit Page Trap
+@cindex implicit trap
+@cindex trap, implicit
+
+@cindex page break
+@cindex break, page
+@cindex page ejection
+@cindex ejection, page
+If, after starting GNU @code{troff} without loading a macro package, you
+use the @code{ptr} request to dump a list of the active traps to the
+standard error stream,@footnote{@xref{Debugging}.}  nothing is reported.
+Yet the @code{.t} register will report a steadily decreasing value with
+every output line your document produces, and once the value of
+@code{.t} gets to within @code{.V} of zero, you will notice that
+something trap-like happens---the page is ejected, a new one begins, and
+the value of @code{.t} becomes large once more.
+
+This @dfn{implicit page trap} always exists in the top-level
+diversion;@footnote{@xref{Diversions}.} it works like a trap in some
+ways but not others.  Its purpose is to eject the current page and start
+the next one.  It has no name, so it cannot be moved or deleted with
+@code{wh} or @code{ch} requests.  You cannot hide it by placing another
+trap at its location, and can move it only by redefining the page length
+with @code{pl}.  Its operation is suppressed when vertical page traps
+are disabled with GNU @code{troff}'s @code{vpt} request.
+@c END Keep (roughly) parallel with subsection "The implicit trap" of
+@c groff(7).
+
+@c ---------------------------------------------------------------------
+
+@node Diversion Traps, Input Line Traps, The Implicit Page Trap, Vertical Position Traps
+@subsubsection Diversion Traps
+@cindex diversion traps
+@cindex traps, diversion
+
+A diversion is not formatted in the context of a page, so it lacks page
+location traps; instead it can have a @dfn{diversion trap}.  There can
+exist at most one such vertical position trap per diversion.
+
+@Defreq {dt, [@Var{dist} @Var{name}]}
+@cindex @code{.t} register, and diversions
+@cindex setting diversion trap (@code{dt})
+@cindex diversion trap, setting (@code{dt})
+@cindex trap, diversion, setting (@code{dt})
+Set a trap @emph{within} a diversion at location @var{dist}, which is
+interpreted relative to diversion rather than page boundaries.  If invoked with
+fewer than two arguments, any diversion trap in the current diversion is
+removed.  The register @code{.t} works within diversions.  It is an
+error to invoke @code{dt} in the top-level diversion.
+@xref{Diversions}.
+@endDefreq
+
+@c ---------------------------------------------------------------------
+
+@node Input Line Traps, Blank Line Traps, Diversion Traps, Traps
+@subsection Input Line Traps
+@cindex input line traps
+@cindex traps, input line
+
+@DefreqList {it, [@Var{n} @Var{name}]}
+@DefreqListEndx {itc, [@Var{n} @Var{name}]}
+@cindex setting input line trap (@code{it}, @code{itc})
+@cindex input line trap, setting (@code{it}, @code{itc})
+@cindex trap, input line, setting (@code{it}, @code{itc})
+@cindex clearing input line trap (@code{it}, @code{itc})
+@cindex input line trap, clearing (@code{it}, @code{itc})
+@cindex trap, input line, clearing (@code{it}, @code{itc})
+Set an input line trap, calling macro @var{name} after processing the
+next @var{n}@tie{}productive input lines (recall @ref{Manipulating
+Filling and Adjustment}).  Any existing input line trap in the
+environment is replaced.  Without arguments, @code{it} and @code{itc}
+clear any input line trap that has not yet sprung.
+
+Consider a macro @samp{.ST @var{s n}} which sets the next
+@var{n}@tie{}input lines in the font style@tie{}@var{s}.
+
+@Example
+.de ST \" Use style $1 for next $2 text lines.
+.  it \\$2 ES
+.  ft \\$1
+..
+.de ES \" end ST
+.  ft R
+..
+.ST I 1
+oblique
+face
+.ST I 1
+oblique\c
+face
+    @result{} @i{oblique} face @i{oblique}face @
+@r{(second ``face'' upright)}
+@endExample
+
+@cindex input line traps and interrupted lines (@code{itc})
+@cindex interrupted lines and input line traps (@code{itc})
+@cindex traps, input line, and interrupted lines (@code{itc})
+@cindex lines, interrupted, and input line traps (@code{itc})
+Unlike the @code{ce} and @code{rj} requests, @code{it} counts lines
+interrupted with the @code{\c} escape sequence separately (@pxref{Line
+Continuation}); @code{itc} does not.  To see the difference, let's
+change the previous example to use @code{itc} instead.
+
+@Example
+@r{@dots{}}
+.  itc \\$2 ES
+@r{@dots{}}
+    @result{} @i{oblique} face @i{obliqueface} @
+@r{(second ``face'' oblique)}
+@endExample
+
+You can think of the @code{ce} and @code{rj} requests as implicitly
+creating an input line trap with @code{itc} that schedules a break when
+the trap is sprung.
+
+@Example
+.de BR
+.  br
+.  @slanted{internal: disable centering-without-filling}
+..
+.
+.de ce
+.  if \\n[.br] .br
+.  itc \\$1 BR
+.  @slanted{internal: enable centering-without-filling}
+..
+@endExample
+
+@need 500
+Let us consider in more detail the sorts of input lines that are or are
+not ``productive''.
+
+@Example
+.de Trap
+TRAP SPRUNG
+..
+.de Mac
+.if r a \l'5n'
+..
+.it 2 Trap
+.
+foo
+.Mac
+bar
+baz
+.it 1 Trap
+.sp \" moves, but does not write or draw
+qux
+.itc 1 Trap
+\h'5n'\c \" moves, but does not write or draw
+jat
+@endExample
+
+@noindent
+When @samp{Trap} gets called depends on whether the @samp{a} register is
+defined; the control line with the @code{if} request may or may not
+produce written output.  We also see that the spacing request @code{sp},
+while certainly affecting the output, does not spring the input line
+trap.  Similarly, the horizontal motion escape sequence @code{\h} also
+affected the output, but was not ``written''.  Observe that we had to
+follow it with @code{\c} and use @code{itc} to prevent the newline at
+the end of the text line from causing a word break, which, like an
+ordinary space character, counts as written output.
+
+@Example
+$ groff -Tascii input-trap-example.groff
+    @result{} foo bar TRAP SPRUNG baz
+    @result{}
+    @result{} qux TRAP SPRUNG      jat TRAP SPRUNG
+$ groff -Tascii -ra1 input-trap-example.groff
+    @result{} foo _____ TRAP SPRUNG bar baz
+    @result{}
+    @result{} qux TRAP SPRUNG      jat TRAP SPRUNG
+@endExample
+@endDefreq
+
+Input line traps are associated with the environment
+(@pxref{Environments}); switching to another environment suspends the
+current input line trap, and going back resumes it, restoring the count
+of qualifying lines enumerated in that environment.
+
+@c ---------------------------------------------------------------------
+
+@node Blank Line Traps, Leading Space Traps, Input Line Traps, Traps
+@subsection Blank Line Traps
+@cindex blank line traps
+@cindex traps, blank line
+
+@Defreq {blm, [@Var{name}]}
+@cindex blank line macro (@code{blm})
+Set a blank line trap, calling the macro @var{name} when GNU
+@code{troff} encounters a blank line in an input file, instead of the
+usual behavior (@pxref{Breaking}).  A line consisting only of spaces is
+also treated as blank and subject to this trap.  If no argument is
+supplied, the default blank line behavior is (re-)established.
+@endDefreq
+
+@c ---------------------------------------------------------------------
+
+@node Leading Space Traps, End-of-input Traps, Blank Line Traps, Traps
+@subsection Leading Space Traps
+@cindex leading space traps
+@cindex traps, leading space
+
+@DefreqList {lsm, [@Var{name}]}
+@DefregItemx {lsn}
+@DefregListEndx {lss}
+@cindex leading spaces macro (@code{lsm})
+Set a leading space trap, calling the macro @var{name} when GNU
+@code{troff} encounters leading spaces in an input line; the implicit
+line break that normally happens in this case is suppressed.  If no
+argument is supplied, the default leading space behavior is
+(re-)established (@pxref{Breaking}).
+
+The count of leading spaces on an input line is stored in register
+@code{lsn}, and the amount of corresponding horizontal motion in
+register @code{lss}, irrespective of whether a leading space trap is
+set.  When it is, the leading spaces are removed from the input line,
+and no motion is produced before calling @var{name}.
+
+@c XXX The following discussion does not seem to be correct; leading
+@c space traps don't "see" _any_ input tokens.  Nothing on the line is
+@c passed to it as arguments, and tokens after leading spaces are
+@c processed normally after the designated macro is interpolated. XXX
+@c
+@c The first thing a leading space macro sees is a token.  However, some
+@c escape sequences, like @code{\f} and @code{\m}, are handled on the
+@c fly (@pxref{Gtroff Internals} for a complete list) without creating a
+@c token at all.  Consider a line that starts with two spaces followed
+@c by @samp{\fIfoo}.  After skipping the spaces, @samp{\fI} is handled
+@c as well such that @code{groff}'s current font is set to @code{I}, but
+@c the leading space macro sees only @samp{foo} without the preceding
+@c @samp{\fI}.  If the macro should see the font escape, you have to
+@c ``protect'' it with something that creates a token, like the
+@c dummy character; for example, @samp{\&\fIfoo}.
+@endDefreq
+
+@c ---------------------------------------------------------------------
+
+@node End-of-input Traps,  , Leading Space Traps, Traps
+@subsection End-of-input Traps
+@cindex end-of-input traps
+@cindex traps, end-of-input
+
+@Defreq {em, [@Var{name}]}
+@cindex setting end-of-input trap (@code{em})
+@cindex end-of-input trap, setting (@code{em})
+@cindex trap, end-of-input, setting (@code{em})
+@cindex end-of-input macro (@code{em})
+@cindex macro, end-of-input (@code{em})
+Set a trap at the end of input, calling macro @var{name} after the last
+line of the last input file has been processed.  If no argument is
+given, any existing end-of-input trap is removed.
+
+For example, if the document had to have a section at the bottom of the
+last page for someone to approve it, the @code{em} request could be
+used.
+
+@Example
+.de approval
+\c
+.  ne 3v
+.  sp (\\n[.t]u - 3v)
+.  in +4i
+.  lc _
+.  br
+Approved:\t\a
+.  sp
+Date:\t\t\a
+..
+.
+.em approval
+@endExample
+
+The @code{\c} in the above example needs explanation.  For historical
+reasons (compatibility with @acronym{AT&T} @code{troff}), the
+end-of-input macro exits as soon as it causes a page break if no
+partially collected line remains.@footnote{While processing an
+end-of-input macro, the formatter assumes that the next page break must
+be the last; it goes into ``sudden death overtime''.}
+
+@cindex page break, final
+@cindex break, page, final
+@cindex page ejection, of final page
+@cindex ejection, page, of final page
+Let us assume that there is no @code{\c} in the above @code{approval}
+macro, that the page is full, and last output line has been broken with,
+say, a @code{br} request.  Because there is no more room, a @code{ne}
+request at this point causes a page ejection, which in turn makes
+@code{troff} exit immediately as just described.  In most situations,
+this is not desired; people generally want to format the input after
+@code{ne}.
+
+To force processing of the whole end-of-input macro independently of
+this behavior, it is thus advisable to (invisibly) ensure the existence
+of a partially collected line (@code{\c}) whenever there is a chance
+that a page break can happen.  In the above example, invoking the
+@code{ne} request ensures that there is room for the subsequent
+formatted output on the same page, so we need insert @code{\c} only
+once.
+
+The next example shows how to append three lines, then start a new page
+unconditionally.  Since @w{@samp{.ne 1}} doesn't give the desired
+effect---there is always one line available or we are already at the
+beginning of the next page---we temporarily increase the page length by
+one line so that we can use @w{@samp{.ne 2}}.
+
+@Example
+.de EM
+.pl +1v
+\c
+.ne 2
+line one
+.br
+\c
+.ne 2
+line two
+.br
+\c
+.ne 2
+line three
+.br
+.pl -1v
+\c
+'bp
+..
+.em EM
+@endExample
+
+This specific feature affects only the first potential page break caused
+by the end-of-input macro; further page breaks emitted by the macro are
+handled normally.
+
+Another possible use of the @code{em} request is to make GNU
+@code{troff} emit a single large page instead of multiple pages.  For
+example, one may want to produce a long plain text file for reading
+in a terminal or emulator without page footers and headers interrupting
+the body of the document.  One approach is to set the page length at the
+beginning of the document to a very large value to hold all the
+text,@footnote{Another, taken by the @code{groff} @code{man} macros, is
+to intercept @code{ne} requests and wrap @code{bp} ones.} and
+automatically adjust it to the exact height of the document after the
+text has been output.
+
+@Example
+.de adjust-page-length
+.  br
+.  pl \\n[nl]u \" \n[nl]: current vertical position
+..
+.
+.de single-page-mode
+.  pl 99999
+.  em adjust-page-length
+..
+.
+.\" Activate the above code if configured.
+.if \n[do-continuous-rendering] \
+.  single-page-mode
+@endExample
+
+Since only one end-of-input trap exists and another macro package may
+already use it, care must be taken not to break the mechanism.  A simple
+solution would be to append the above macro to the macro package's
+end-of-input macro using the @code{am} request.
+@endDefreq
+
+
+@c =====================================================================
+
+@c BEGIN Keep (roughly) parallel with subsection "Diversions" of
+@c groff(7).
+@node Diversions, Punning Names, Traps, GNU troff Reference
+@section Diversions
+@cindex diversions
+
+In @code{roff} systems it is possible to format text as if for output,
+but instead of writing it immediately, one can @dfn{divert} the
+formatted text into a named storage area.  It is retrieved later by
+specifying its name after a control character.   The same name space is
+used for such @slanted{diversions} as for strings and macros; see
+@ref{Identifiers}.  Such text is sometimes said to be ``stored in a
+macro'', but this coinage obscures the important distinction between
+macros and strings on one hand and diversions on the other; the former
+store @emph{unformatted} input text, and the latter capture
+@emph{formatted} output.  Diversions also do not interpret arguments.
+Applications of diversions include ``keeps'' (preventing a page break
+from occurring at an inconvenient place by forcing a set of output lines
+to be set as a group), footnotes, tables of contents, and indices.
+@cindex top-level diversion
+@cindex diversion, top-level
+For orthogonality it is said that GNU @code{troff} is in the
+@dfn{top-level diversion} if no diversion is active (that is, formatted
+output is being ``diverted'' immediately to the output device).
+
+Dereferencing an undefined diversion will create an empty one of that
+name and cause a warning in category @samp{mac} to be emitted.
+@xref{Warnings}, for information about the enablement and suppression of
+warnings.  A diversion does not exist for the purpose of testing with
+the @code{d} conditional operator until its initial definition ends
+(@pxref{Operators in Conditionals}).  The following requests are used to
+create and alter diversions.
+@c END Keep (roughly) parallel with subsection "Diversions" of groff(7).
+
+@DefreqList {di, [@Var{name}]}
+@DefreqListEndx {da, [@Var{name}]}
+@cindex beginning diversion (@code{di}, @code{box})
+@cindex diversion, beginning (@code{di}, @code{box})
+@cindex ending diversion (@code{di}, @code{box})
+@cindex diversion, ending (@code{di}, @code{box})
+@cindex appending to a diversion (@code{da}, @code{boxa})
+@cindex diversion, appending to (@code{da}, @code{boxa})
+Start collecting formatted output in a diversion called @var{name}.  The
+@code{da} request appends to a diversion called @var{name}, creating it
+if necessary.  If @var{name} already exists as an alias, the target of
+the alias is replaced or appended to; recall @ref{Strings}.  The pending
+output line is diverted as well.  Switching to another environment (with
+the @code{ev} request) before invoking @code{di} or @code{da} avoids
+including any pending output line in the diversion; see
+@ref{Environments}.
+
+Invoking @code{di} or @code{da} without an argument stops diverting
+output to the diversion named by the most recent corresponding request.
+If @code{di} or @code{da} is called without an argument when there is no
+current diversion, a warning in category @samp{di} is produced.
+@xref{Warnings}, for information about the enablement and suppression
+of warnings.
+
+@Example
+Before the diversion.
+.di yyy
+In the diversion.
+.br
+.di
+After the diversion.
+.br
+    @result{} After the diversion.
+.yyy
+    @result{} Before the diversion.  In the diversion.
+@endExample
+@endDefreq
+
+@cindex box (diversion operation)
+GNU @code{troff} supports @dfn{box} requests to exclude a partially
+collected line from a diversion, as this is often desirable.
+
+@DefreqList {box, [@Var{name}]}
+@DefreqListEndx {boxa, [@Var{name}]}
+Divert (or append) output to @var{name}, similarly to the @code{di} and
+@code{da} requests, respectively.  Any pending output line is @emph{not}
+included in the diversion.  Without an argument, stop diverting output;
+any pending output line inside the diversion is discarded.
+
+@Example
+Before the box.
+.box xxx
+In the box.
+.br
+Hidden treasure.
+.box
+After the box.
+.br
+    @result{} Before the box.  After the box.
+.xxx
+    @result{} In the box.
+@endExample
+@endDefreq
+
+Apart from pending output line inclusion and the request names that
+populate them, boxes are handled exactly as diversions are.  All of the
+following @code{groff} language elements can be used with them
+interchangeably.
+
+@DefregList {.z}
+@DefregListEndx {.d}
+@cindex @code{nl} register, and @code{.d}
+@cindex nested diversions
+@cindex diversion, nested
+@cindex diversion name register (@code{.z})
+@cindex vertical position in diversion register (@code{.d})
+@cindex position, vertical, in diversion, register (@code{.d})
+@cindex diversion, vertical position in, register (@code{.d})
+Diversions may be nested.  The read-only string-valued register
+@code{.z} contains the name of the current diversion.  The read-only
+register @code{.d} contains the current vertical place in the diversion.
+If the input text is not being diverted, @code{.d} reports the same
+location as the register @code{nl}.
+@endDefreg
+
+@Defreg {.h}
+@cindex high-water mark register (@code{.h})
+@cindex mark, high-water, register (@code{.h})
+@cindex position of lowest text line (@code{.h})
+@cindex text line, position of lowest (@code{.h})
+The read-only register @code{.h} stores the @dfn{high-water mark} on the
+current page or in the current diversion.  It corresponds to the text
+baseline of the lowest line on the page.@footnote{Thus, the ``water''
+gets ``higher'' proceeding @emph{down} the page.}
+
+@Example
+.tm .h==\n[.h], nl==\n[nl]
+    @result{} .h==0, nl==-1
+This is a test.
+.br
+.sp 2
+.tm .h==\n[.h], nl==\n[nl]
+    @result{} .h==40, nl==120
+@endExample
+
+@cindex @code{.h} register, difference from @code{nl}
+@cindex @code{nl} register, difference from @code{.h}
+@noindent
+As implied by the example, vertical motion does not produce text
+baselines and thus does not increase the value interpolated by
+@samp{\n[.h]}.
+@endDefreg
+
+@DefregList {dn}
+@DefregListEndx {dl}
+@cindex @code{dn} register, and @code{da} (@code{boxa})
+@cindex @code{dl} register, and @code{da} (@code{boxa})
+@cindex @code{da} request, and @code{dn} (@code{dl})
+@cindex @code{boxa} request, and @code{dn} (@code{dl})
+After completing a diversion, the writable registers @code{dn} and
+@code{dl} contain its vertical and horizontal sizes.  Only the lines
+just processed are counted: for the computation of @code{dn} and
+@code{dl}, the requests @code{da} and @code{boxa} are handled as if
+@code{di} and @code{box} had been used, respectively---lines that have
+been already stored in the diversion (box) are not taken into account.
+
+@Example
+.\" Center text both horizontally and vertically.
+.\" Macro .(c starts centering mode; .)c terminates it.
+.
+.\" Disable the escape character with .eo so that we
+.\" don't have to double backslashes on the "\n"s.
+.eo
+.de (c
+.  br
+.  ev (c
+.  evc 0
+.  in 0
+.  nf
+.  di @@c
+..
+@endExample
+@Example
+.de )c
+.  br
+.  ev
+.  di
+.  nr @@s (((\n[.t]u - \n[dn]u) / 2u) - 1v)
+.  sp \n[@@s]u
+.  ce 1000
+.  @@c
+.  ce 0
+.  sp \n[@@s]u
+.  br
+.  fi
+.  rr @@s
+.  rm @@c
+..
+.ec
+@endExample
+@endDefreg
+
+@DefescList {\\!, , anything, }
+@DefescListEndx {\\?, , anything, \\?}
+@cindex transparent output (@code{\!}, @code{\?})
+@cindex output, transparent (@code{\!}, @code{\?})
+@dfn{Transparently} embed @var{anything} into the current diversion,
+preventing requests, macro calls, and escape sequences from being
+interpreted when read into a diversion.  This is useful for preventing
+them from taking effect until the diverted text is actually output.  The
+@code{\!} escape sequence transparently embeds input up to and including
+the end of the line.  The @code{\?} escape sequence transparently embeds
+input until its own next occurrence.
+
+@cindex @code{\?}, and copy mode
+@cindex copy mode, and @code{\?}
+@cindex mode, copy, and @code{\?}
+@cindex @code{\!}, and copy mode
+@cindex copy mode, and @code{\!}
+@cindex mode, copy, and @code{\!}
+@noindent
+@var{anything} may not contain newlines; use @code{\!} by itself to
+embed newlines in a diversion.  The escape sequence @code{\?} is also
+recognized in copy mode and turned into a single internal code; it is
+this code that terminates @var{anything}.  Thus the following example
+prints@tie{}4.
+
+@Example
+.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
+@endExample
+
+Both escape sequences read the data in copy mode.
+
+@cindex @code{\!}, in top-level diversion
+@cindex top-level diversion, and @code{\!}
+@cindex diversion, top-level, and @code{\!}
+If @code{\!} is used in the top-level diversion, its argument is
+directly embedded into GNU @code{troff}'s intermediate output.  This can
+be used, for example, to control a postprocessor that processes the data
+before it is sent to an output driver.
+
+@cindex @code{\?}, in top-level diversion
+@cindex top-level diversion, and @code{\?}
+@cindex diversion, top-level, and @code{\?}
+The @code{\?} escape used in the top-level diversion produces no output
+at all; its argument is simply ignored.
+@endDefesc
+
+@cindex @code{\!}, and @code{output} request
+@cindex @code{output} request, and @code{\!}
+@cindex @code{output} request, and copy mode
+@cindex copy mode, and @code{output} request
+@cindex mode, copy, and @code{output} request
+@Defreq {output, contents}
+Emit @var{contents} directly to GNU @code{troff}'s intermediate output
+(subject to copy mode interpretation); this is similar to @code{\!} used
+at the top level.  An initial neutral double quote in @var{contents} is
+stripped to allow embedding of leading spaces.
+
+This request can't be used before the first page has started---if you
+get an error, simply insert @code{.br} before the @code{output} request.
+
+Use with caution!  It is normally only needed for mark-up used by a
+postprocessor that does something with the output before sending it to
+the output device, filtering out @var{contents} again.
+@endDefreq
+
+@Defreq {asciify, div}
+@cindex unformatting diversions (@code{asciify})
+@cindex diversion, unformatting (@code{asciify})
+@cindex @code{trin} request, and @code{asciify}
+@dfn{Unformat} the diversion @var{div} in a way such that Unicode basic
+Latin (@acronym{ASCII}) characters, characters translated with the
+@code{trin} request, space characters, and some escape sequences, that
+were formatted and diverted into @var{div} are treated like ordinary
+input characters when @var{div} is reread.  Doing so can be useful in
+conjunction with the @code{writem} request.  @code{asciify} can be also
+used for gross hacks; for example, the following sets
+register@tie{}@code{n} to@tie{}1.
+
+@Example
+.tr @@.
+.di x
+@@nr n 1
+.br
+.di
+.tr @@@@
+.asciify x
+.x
+@endExample
+
+@code{asciify} cannot return all items in a diversion to their source
+equivalent: nodes such as those produced by the @code{\N} escape
+sequence will remain nodes, so the result cannot be guaranteed to be a
+pure string.  @xref{Copy Mode}.  Glyph parameters such as the type face
+and size are not preserved; use @code{unformat} to achieve that.
+@endDefreq
+
+@Defreq {unformat, div}
+Like @code{asciify}, unformat the diversion @var{div}.  However,
+@code{unformat} handles only tabs and spaces between words, the latter
+usually arising from spaces or newlines in the input.  Tabs are treated
+as input tokens, and spaces become adjustable again.  The vertical sizes
+of lines are not preserved, but glyph information (font, type size,
+space width, and so on) is retained.
+@endDefreq
+
+
+@c =====================================================================
+
+@node Punning Names, Environments, Diversions, GNU troff Reference
+@section Punning Names
+@cindex diversions
+
+Macros, strings, and diversions share a name space; recall
+@ref{Identifiers}.  Internally, the same mechanism is used to store
+them.  You can thus call a macro with string interpolation syntax and
+vice versa.
+
+@Example
+.de subject
+Typesetting
+..
+.de predicate
+rewards attention to detail
+..
+\*[subject] \*[predicate].
+Truly.
+    @result{} Typesetting
+    @result{}  rewards attention to detail Truly.
+@endExample
+
+@noindent
+What went wrong?  Strings don't contain newlines, but macros do.  String
+interpolation placed a newline at the end of @samp{\*[subject]}, and the
+next thing on the input was a space.  Then when @samp{\*[predicate]} was
+interpolated, it was followed by the empty request @samp{.} on a line by
+itself.  If we want to use macros as strings, we must take interpolation
+behavior into account.
+
+@Example
+.de subject
+Typesetting\\
+..
+.de predicate
+rewards attention to detail\\
+..
+\*[subject] \*[predicate].
+Truly.
+    @result{} Typesetting rewards attention to detail.  Truly.
+@endExample
+
+@noindent
+By ending each text line of the macros with an escaped
+@code{\@key{RET}}, we get the desired effect (@pxref{Line
+Continuation}).@footnote{The backslash is doubled.  @xref{Copy Mode}.}
+What would have happened if we had used only one backslash at a time
+instead?
+
+Interpolating a string does not hide existing macro arguments.  We can
+also place the escaped newline outside the string interpolation instead
+of within the string definition.  Thus, in a macro, a more efficient way
+of doing
+
+@Example
+.xx \\$@@
+@endExample
+
+@noindent
+is
+
+@Example
+\\*[xx]\\
+@endExample
+
+@noindent
+The latter calling syntax doesn't change the value of @code{\$0}, which
+is then inherited from the calling macro (@pxref{Parameters}).
+
+Diversions can be also called with string syntax.  It is sometimes
+convenient to copy one-line diversions to a string.
+
+@Example
+.di xx
+the
+.ft I
+interpolation system
+.ft
+.br
+.di
+.ds yy This is a test of \*(xx\c
+\*(yy.
+    @result{} This is a test of the @i{interpolation system}.
+@endExample
+
+@noindent
+As the previous example shows, it is possible to store formatted output
+in strings.  The @code{\c} escape sequence prevents the subsequent
+newline from being interpreted as a break (again,
+@pxref{Line Continuation}).
+
+Copying multi-output line diversions produces unexpected results.
+
+@Example
+.di xxx
+a funny
+.br
+test
+.br
+.di
+.ds yyy This is \*[xxx]\c
+\*[yyy].
+    @result{} test This is a funny.
+@endExample
+
+Usually, it is not predictable whether a diversion contains one or more
+output lines, so this mechanism should be avoided.  With @acronym{AT&T}
+@code{troff}, this was the only solution to strip off a final newline
+from a diversion.  Another disadvantage is that the spaces in the copied
+string are already formatted, preventing their adjustment.  This can
+cause ugly results.
+
+@cindex stripping final newline in diversions
+@cindex diversion, stripping final newline
+@cindex final newline, stripping in diversions
+@cindex newline, final, stripping in diversions
+@cindex horizontal space, unformatting
+@cindex space, horizontal, unformatting
+@cindex unformatting horizontal space
+A clean solution to this problem is available in GNU @code{troff}, using
+the requests @code{chop} to remove the final newline of a diversion, and
+@code{unformat} to make the horizontal spaces adjustable again.
+
+@Example
+.box xxx
+a funny
+.br
+test
+.br
+.box
+.chop xxx
+.unformat xxx
+This is \*[xxx].
+    @result{} This is a funny test.
+@endExample
+
+@xref{Gtroff Internals}.
+
+@c =====================================================================
+
+@c BEGIN Keep parallel with section "Environments" of groff(7).
+@node Environments, Suppressing Output, Diversions, GNU troff Reference
+@section Environments
+@cindex environments
+
+As discussed in @ref{Deferring Output}, environments store most of the
+parameters that determine the appearance of text.  A default environment
+named @samp{0} exists when GNU @code{troff} starts up; it is modified by
+formatting-related requests and escape sequences.
+
+@cindex stack
+You can create new environments and switch among them.  Only one is
+current at any given time.  Active environments are managed using a
+@dfn{stack}, a data structure supporting ``push'' and ``pop''
+operations.  The current environment is at the top of the stack.
+The same environment name can be pushed onto the stack multiple times,
+possibly interleaved with others.  Popping the environment stack does
+not destroy the current environment; it remains accessible by name and
+can be made current again by pushing it at any time.  Environments
+cannot be renamed or deleted, and can only be modified when current.  To
+inspect the environment stack, use the @code{pev} request; see
+@ref{Debugging}.
+
+Environments store the following information.
+
+@itemize @bullet
+@item
+a partially collected line, if any
+
+@item
+data about the most recently output glyph and line (registers
+@code{.cdp}, @code{.cht}, @code{.csk}, @code{.n}, @code{.w})
+
+@item
+typeface parameters (size, family, style, height and slant, inter-word
+and inter-sentence space sizes)
+
+@item
+page parameters (line length, title length, vertical spacing, line
+spacing, indentation, line numbering, centering, right-alignment,
+underlining, hyphenation parameters)
+
+@item
+filling enablement; adjustment enablement and mode
+
+@item
+tab stops; tab, leader, escape, control, no-break control, hyphenation,
+and margin characters
+
+@item
+input line traps
+
+@item
+stroke and fill colors
+@end itemize
+@c END Keep parallel with section "Environments" of groff(7).
+
+@DefreqList {ev, [@Var{ident}]}
+@DefregListEndx {.ev}
+@cindex switching environments (@code{ev})
+@cindex environment, switching (@code{ev})
+@cindex environment number/name register (@code{.ev})
+Enter the environment @var{ident}, which is created if it does not
+already exist, using the same parameters as for the default environment
+used at startup.  With no argument, GNU @code{troff} switches to the
+previous environment.
+
+Invoking @code{ev} with an argument puts environment @var{ident} onto
+the top of the environment stack.  (If it isn't already present in the
+stack, this is a proper push.)  Without an argument, @code{ev} pops the
+environment stack, making the previous environment current.  It is an
+error to pop the environment stack with no previous environment
+available.  The read-only string-valued register @code{.ev} contains the
+name of the current environment---the one at the top of the stack.
+
+@Example
+.ev footnote-env
+.fam N
+.ps 6
+.vs 8
+.ll -.5i
+.ev
+
+@r{@dots{}}
+
+.ev footnote-env
+\[dg] Observe the smaller text and vertical spacing.
+.ev
+@endExample
+
+We can familiarize ourselves with stack behavior by wrapping the
+@code{ev} request with a macro that reports the contents of the
+@code{.ev} register to the standard error stream.
+
+@Example
+.de EV
+.  ev \\$1
+.  tm environment is now \\n[.ev]
+..
+.
+.EV foo
+.EV bar
+.EV
+.EV baz
+.EV
+.EV
+.EV
+@endExample
+
+@Example
+    @error{} environment is now foo
+    @error{} environment is now bar
+    @error{} environment is now foo
+    @error{} environment is now baz
+    @error{} environment is now foo
+    @error{} environment is now 0
+    @error{} error: environment stack underflow
+    @error{} environment is now 0
+@endExample
+
+@endDefreq
+
+@Defreq {evc, environment}
+@cindex copying environment (@code{evc})
+@cindex environment, copying (@code{evc})
+Copy the contents of @var{environment} to the current environment.
+
+The following environment data are not copied.
+
+@itemize @bullet
+@item
+a partially collected line, if present;
+
+@item
+the interruption status of the previous input line (due to use of the
+@code{\c} escape sequence);
+
+@item
+the count of remaining lines to center, to right-justify, or to
+underline (with or without underlined spaces)---these are set to zero;
+
+@item
+the activation status of temporary indentation;
+
+@item
+input line traps and their associated data;
+
+@item
+the activation status of line numbering (which can be reactivated with
+@w{@samp{.nm +0}}); and
+
+@item
+the count of consecutive hyphenated lines (set to zero).
+@end itemize
+@endDefreq
+
+@DefregList {.w}
+@DefregItemx {.cht}
+@DefregItemx {.cdp}
+@DefregListEndx {.csk}
+@cindex environment, dimensions of last glyph (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk})
+@cindex width, of last glyph (@code{.w})
+@cindex height, of last glyph (@code{.cht})
+@cindex depth, of last glyph (@code{.cdp})
+@cindex skew, of last glyph (@code{.csk})
+@cindex last glyph, dimensions (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk})
+@cindex glyph, last, dimensions (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk})
+The @code{\n[.w]} register contains the width of the last glyph
+formatted in the environment.
+
+The @code{\n[.cht]} register contains the height of the last glyph
+formatted in the environment.
+
+The @code{\n[.cdp]} register contains the depth of the last glyph
+formatted in the environment.  It is positive for glyphs extending below
+the baseline.
+
+The @code{\n[.csk]} register contains the @dfn{skew} (how far to the
+right of the glyph's center that GNU @code{troff} should place an
+accent) of the last glyph formatted in the environment.
+@endDefreg
+
+@Defreg {.n}
+@cindex environment, previous line length (@code{.n})
+@cindex line length, previous (@code{.n})
+@cindex length of previous line (@code{.n})
+@cindex previous line length (@code{.n})
+The @code{\n[.n]} register contains the length of the previous output
+line emitted in the environment.
+@endDefreg
+
+@codequotebacktick off
+@codequoteundirected off
+
+
+@c =====================================================================
+
+@node Suppressing Output, Colors, Environments, GNU troff Reference
+@section Suppressing Output
+
+@Defesc {\\O, [, num, ]}
+@cindex suppressing output (@code{\O})
+@cindex output, suppressing (@code{\O})
+Suppress GNU @code{troff} output of glyphs and geometric objects.  The
+sequences @code{\O2}, @code{\O3}, @code{\O4}, and @code{\O5} are
+intended for internal use by @code{grohtml}.
+
+@table @samp
+@item \O0
+Disable the emission of glyphs and geometric objects to the output
+driver, provided that this sequence occurs at the outermost suppression
+level (see @code{\O3} and @code{\04} below).  Horizontal motions
+corresponding to non-overstruck glyph widths still occur.
+
+@item \O1
+Enable the emission of glyphs and geometric objects to the output
+driver, provided that this sequence occurs at the outermost suppression
+level.
+@end table
+
+@vindex opminx
+@vindex opminy
+@vindex opmaxx
+@vindex opmaxy
+@code{\O0} and @code{\O1} also reset the four registers @code{opminx},
+@code{opminy}, @code{opmaxx}, and @code{opmaxy} to @minus{}1.  These
+four registers mark the top left and bottom right hand corners of a box
+encompassing all written or drawn output.
+
+@table @samp
+@item \O2
+At the outermost suppression level, enable emission of glyphs and
+geometric objects, and write to the standard error stream the page
+number and values of the four aforementioned registers encompassing
+glyphs written since the last interpolation of a @code{\O} sequence, as
+well as the page offset, line length, image file name (if any),
+horizontal and vertical device motion quanta, and input file name.
+Numeric values are in basic units.
+
+@item \O3
+Begin a nested suppression level.  @command{grohtml} uses this mechanism
+to create images of output preprocessed with @command{gpic},
+@command{geqn}, and @command{gtbl}.  At startup, GNU @code{troff} is at
+the outermost suppression level.  @command{pre-grohtml} generates these
+sequences when processing the document, using GNU @command{troff} with
+the @code{ps} output device, Ghostscript, and the PNM tools to produce
+images in PNG format.  They start a new page if the device is not
+@code{html} or @code{xhtml}, to reduce the number of images crossing a
+page boundary.
+
+@item \O4
+End a nested suppression level.
+@end table
+
+@table @samp
+@item \O[5@var{P}@var{file}]
+At the outermost suppression level, write the name @code{file} to the
+standard error stream at position @var{P}, which must be one of
+@code{l}, @code{r}, @code{c}, or@tie{}@code{i}, corresponding to left,
+right, centered, and inline alignments within the document,
+respectively.  @var{file} is a name associated with the production of
+the next image.
+@end table
+@endDefesc
+
+@Defreg {.O}
+@cindex suppression nesting level register
+@cindex nesting level, suppression, register
+@cindex level, suppression nesting, register
+Output suppression nesting level applied by @code{\O3} and @code{\O4}
+escape sequences.
+@endDefreg
+
+@c =====================================================================
+
+@codequotebacktick on
+@codequoteundirected on
+
+@c TODO: Rename this node to "Operating Environment Access" or similar,
+@c and move the date/time, process ID, etc., read-only registers here.
+@node I/O, Postprocessor Access, Suppressing Output, GNU troff Reference
+@section I/O
+@cindex i/o
+@cindex input and output requests
+@cindex requests for input and output
+@cindex output and input requests
+
+@code{gtroff} has several requests for including files:
+
+@DefreqList {so, file}
+@DefreqListEndx {soquiet, file}
+@cindex including a file (@code{so})
+@cindex file, inclusion (@code{so})
+Replace the @code{so} request's control line with the contents of the
+file named by the argument, ``sourcing'' it.  @var{file} is sought in
+the directories specified by @option{-I} command-line option.  If
+@var{file} does not exist, a warning in category @samp{file} is produced
+and the request has no further effect.  @xref{Warnings}, for
+information about the enablement and suppression of warnings.
+
+@code{so} can be useful for large documents; e.g., allowing each chapter
+of a book to be kept in a separate file.  However, files interpolated
+with @code{so} are not preprocessed; to overcome this limitation, see
+the @cite{gsoelim@r{(1)}} man page.
+
+Since GNU @code{troff} replaces the entire control line with the
+contents of a file, it matters whether @code{file} is terminated with a
+newline or not.  Assume that file @file{xxx} contains only the word
+@samp{foo} without a trailing newline.
+
+@Example
+$ printf 'foo' > xxx
+
+The situation is
+.so xxx
+bar.
+    @result{} The situation is foobar.
+@endExample
+
+@code{soquiet} works the same way, except that no warning diagnostic is
+issued if @var{file} does not exist.
+@endDefreq
+
+@Defreq {pso, command}
+Read the standard output from the specified @var{command} and include
+it in place of the @code{pso} request.
+
+@cindex safer mode
+@cindex mode, safer
+@cindex unsafe mode
+@cindex mode, unsafe
+It is an error to use this request in safer mode, which is the
+default.  Invoke GNU @code{troff} or a front end with the @option{-U}
+option to enable unsafe mode.
+
+The comment regarding a final newline for the @code{so} request is valid
+for @code{pso} also.
+@endDefreq
+
+@DefreqList {mso, file}
+@DefreqListEndx {msoquiet, file}
+Identical to the @code{so} and @code{soquiet} requests, respectively,
+except that @code{gtroff} searches for the specified @var{file} in the
+same directories as macro files for the @option{-m} command-line option.
+If the file name to be included has the form @file{@var{name}.tmac} and
+it isn't found, these requests try to include @file{tmac.@var{name}} and
+vice versa.
+@endDefreq
+
+@DefreqList {trf, file}
+@DefreqListEndx {cf, file}
+@cindex transparent output (@code{cf}, @code{trf})
+@cindex output, transparent (@code{cf}, @code{trf})
+@cindex @code{cf} request, and copy mode
+@cindex copy mode, and @code{cf} request
+@cindex mode, copy, and @code{cf} request
+@cindex @code{trf} request, and copy mode
+@cindex copy mode, and @code{trf} request
+@cindex mode, copy, and @code{trf} request
+Transparently output the contents of @var{file}.  Each line is output as
+if it were preceded by @code{\!}; however, the lines are @emph{not}
+subject to copy mode interpretation.  If the file does not end with a
+newline, @code{trf} adds one.  Both requests cause a break.
+
+When used in a diversion, these requests embed a node (@pxref{Gtroff
+Internals}) in it that, when reread, causes the contents of @var{file}
+to be transparently copied to the output.  In @acronym{AT&T}
+@code{troff}, the contents of @var{file} are immediately copied to the
+output regardless of whether there is a current diversion; this
+behaviour is so anomalous that it must be considered a bug.
+
+@cindex @code{trf} request, and invalid characters
+@cindex characters, invalid for @code{trf} request
+@cindex invalid characters for @code{trf} request
+While @code{cf} copies the contents of @var{file} completely
+unprocessed, @code{trf} disallows characters such as NUL that are not
+valid @code{gtroff} input characters (@pxref{Identifiers}).
+
+For @code{cf}, within a diversion, ``completely unprocessed'' means that
+each line of a file to be inserted is handled as if it were preceded by
+@code{\!\\!}.
+
+To define a macro@tie{}@code{x} containing the contents of
+file@tie{}@file{f}, use
+
+@Example
+.ev 1
+.di x
+.trf f
+.di
+.ev
+@endExample
+
+@noindent
+The calls to @code{ev} prevent the partially collected output line
+from becoming part of the diversion (@pxref{Diversions}).
+@endDefreq
+
+@Defreq {nx, [@Var{file}]}
+@cindex processing next file (@code{nx})
+@cindex file, processing next (@code{nx})
+@cindex next file, processing (@code{nx})
+Force @code{gtroff} to continue processing of the file specified as an
+argument.  If no argument is given, immediately jump to the end of file.
+@endDefreq
+
+@Defreq {rd, [@Var{prompt} [@Var{arg1} @Var{arg2} @dots{}]]}
+@cindex reading from standard input (@code{rd})
+@cindex standard input, reading from (@code{rd})
+@cindex input, standard, reading from (@code{rd})
+Read from standard input, and include what is read as though it were
+part of the input file.  Text is read until a blank line is encountered.
+
+If standard input is a TTY input device (keyboard), write @var{prompt}
+to standard error, followed by a colon (or send BEL for a beep if no
+argument is given).
+
+Arguments after @var{prompt} are available for the input.  For example,
+the line
+
+@Example
+.rd data foo bar
+@endExample
+
+with the input @w{@samp{This is \$2.}} prints
+
+@Example
+This is bar.
+@endExample
+@endDefreq
+
+@cindex form letters
+@cindex letters, form
+Using the @code{nx} and @code{rd} requests, it is easy to set up form
+letters.  The form letter template is constructed like this, putting the
+following lines into a file called @file{repeat.let}:
+
+@Example
+.ce
+\*(td
+.sp 2
+.nf
+.rd
+.sp
+.rd
+.fi
+Body of letter.
+.bp
+.nx repeat.let
+@endExample
+
+@cindex @code{ex} request, used with @code{nx} and @code{rd}
+@noindent
+When this is run, a file containing the following lines should be
+redirected in.  Requests included in this file are executed as though
+they were part of the form letter.  The last block of input is the
+@code{ex} request, which tells GNU @code{troff} to stop processing.  If
+this were not there, @code{troff} would not know when to stop.
+
+@Example
+Trent A. Fisher
+708 NW 19th Av., #202
+Portland, OR  97209
+
+Dear Trent,
+
+Len Adollar
+4315 Sierra Vista
+San Diego, CA  92103
+
+Dear Mr. Adollar,
+
+.ex
+@endExample
+
+@Defreq {pi, pipe}
+Pipe the output of @code{gtroff} to the shell command(s) specified by
+@var{pipe}.  This request must occur before @code{gtroff} has a chance
+to print anything.
+
+@cindex safer mode
+@cindex mode, safer
+@cindex unsafe mode
+@cindex mode, unsafe
+It is an error to use this request in safer mode, which is the
+default.  Invoke GNU @code{troff} or a front end with the @option{-U}
+option to enable unsafe mode.
+
+Multiple calls to @code{pi} are allowed, acting as a chain.  For
+example,
+
+@Example
+.pi foo
+.pi bar
+...
+@endExample
+
+is the same as @w{@samp{.pi foo | bar}}.
+
+@cindex @code{groff}, and @code{pi} request
+@cindex @code{pi} request, and @code{groff}
+The intermediate output format of GNU @code{troff} is piped to the
+specified commands.  Consequently, calling @code{groff} without the
+@option{-Z} option normally causes a fatal error.
+@endDefreq
+
+@cindex system commands, running
+@cindex running system commands
+@DefreqList {sy, cmds}
+@DefregListEndx {systat}
+Execute the shell command(s) specified by @var{cmds}.  The output is not
+saved anywhere, so it is up to the user to do so.
+
+@cindex safer mode
+@cindex mode, safer
+@cindex unsafe mode
+@cindex mode, unsafe
+It is an error to use this request in safer mode; this is the default.
+Give GNU @code{troff} or a front end program the @option{-U} option to
+enable unsafe mode.
+
+The following code fragment introduces the current time into a document.
+
+@pindex perl
+@Example
+.sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\
+             (localtime(time))[2,1,0]' > /tmp/x\n[$$]
+.so /tmp/x\n[$$]
+.sy rm /tmp/x\n[$$]
+\nH:\nM:\nS
+@endExample
+
+@noindent
+This works by having the Perl script (run by @code{sy}) write
+@code{nr} requests that set the registers @code{H}, @code{M}, and
+@code{S} to a temporary file.  The @code{roff} document then reads the
+temporary file using the @code{so} request.
+
+@cindex time, formatting
+@cindex formatting the time
+The registers @code{seconds}, @code{minutes}, and @code{hours},
+initialized at startup of GNU @code{troff}, should satisfy most
+requirements.  Use the @code{af} request to format their values for
+output.
+
+@Example
+.af hours 00
+.af minutes 00
+.af seconds 00
+\n[hours]:\n[minutes]:\n[seconds]
+    @result{} 02:17:54
+@endExample
+
+@cindex @code{system()} return value register (@code{systat})
+The writable register @code{systat} contains the return value of the
+@code{system()} function executed by the last @code{sy} request.
+@endDefreq
+
+@DefreqList {open, stream file}
+@DefreqListEndx {opena, stream file}
+@cindex opening file (@code{open})
+@cindex file, opening (@code{open})
+@cindex appending to a file (@code{opena})
+@cindex file, appending to (@code{opena})
+Open the specified @var{file} for writing and associates the specified
+@var{stream} with it.
+
+The @code{opena} request is like @code{open}, but if the file exists,
+append to it instead of truncating it.
+
+@cindex safer mode
+@cindex mode, safer
+@cindex unsafe mode
+@cindex mode, unsafe
+It is an error to use these requests in safer mode; this is the default.
+Give GNU @code{troff} or a front end program the @option{-U} option to
+enable unsafe mode.
+@endDefreq
+
+@DefreqList {write, stream data}
+@DefreqListEndx {writec, stream data}
+@cindex copy mode, and @code{write} request
+@cindex @code{write} request, and copy mode
+@cindex mode, copy, and @code{write} request
+@cindex copy mode, and @code{writec} request
+@cindex @code{writec} request, and copy mode
+@cindex mode, copy, and @code{writec} request
+@cindex writing to file (@code{write}, @code{writec})
+@cindex file, writing to (@code{write}, @code{writec})
+Write to the file associated with the specified @var{stream}.  The
+stream must previously have been the subject of an open request.  The
+remainder of the line is interpreted as the @code{ds} request reads its
+second argument: an initial neutral double quote in @var{contents} is
+stripped to allow embedding of leading spaces, and it is read in copy
+mode.
+
+The @code{writec} request is like @code{write}, but only @code{write}
+appends a newline to the data.
+@endDefreq
+
+@Defreq {writem, stream xx}
+@cindex @code{asciify} request, and @code{writem}
+Write the contents of the macro or string @var{xx} to the file
+associated with the specified @var{stream}.
+
+@cindex @code{writem} request, and copy mode
+@cindex copy mode, and @code{writem} request
+@cindex mode, copy, and @code{writem} request
+@var{xx} is read in copy mode, i.e., already formatted elements are
+ignored.  Consequently, diversions must be unformatted with the
+@code{asciify} request before calling @code{writem}.  Usually, this
+means a loss of information.
+@endDefreq
+
+@Defreq {close, stream}
+@cindex closing file (@code{close})
+@cindex file, closing (@code{close})
+Close the specified @var{stream}; the stream is no longer an acceptable
+argument to the @code{write} request.
+
+Here a simple macro to write an index entry.
+
+@Example
+.open idx test.idx
+.
+.de IX
+.  write idx \\n[%] \\$*
+..
+.
+.IX test entry
+.
+.close idx
+@endExample
+@endDefreq
+
+@DefescList {\\V, , e, }
+@DefescItem {\\V, (, ev, }
+@DefescListEnd {\\V, [, env, ]}
+@cindex @code{\V}, and copy mode
+@cindex copy mode, and @code{\V}
+@cindex mode, copy, and @code{\V}
+Interpolate the contents of the specified environment variable @var{env}
+(one-character name@tie{}@var{e}, two-character name @var{ev}) as
+returned by the function @cite{getenv@r{(3)}}.  @code{\V} is interpreted
+even in copy mode (@pxref{Copy Mode}).
+@endDefesc
+
+
+@c =====================================================================
+
+@node Postprocessor Access, Miscellaneous, I/O, GNU troff Reference
+@section Postprocessor Access
+@cindex postprocessor access
+@cindex access to postprocessor
+
+Two escape sequences and two requests enable documents to pass
+information directly to a postprocessor.  These are useful for
+exercising device-specific capabilities that the @code{groff} language
+does not abstract or generalize; examples include the embedding of
+hyperlinks and image files.  Device-specific functions are documented in
+each output driver's man page, such as @cite{gropdf@r{(1)}},
+@cite{grops@r{(1)}}, or @cite{grotty@r{(1)}}.
+
+@DefreqList {device, xxx @r{@dots{}}}
+@DefescListEndx {\\X, @code{'}, xxx @r{@dots{}}, @code{'}}
+Embed all @var{xxx} arguments into GNU @code{troff} output as parameters
+to a device control command @w{@samp{x X}}.  The meaning and
+interpretation of such parameters is determined by the output driver or
+other postprocessor.
+
+@cindex @code{device} request, and copy mode
+@cindex copy mode, and @code{device} request
+@cindex mode, copy, and @code{device} request
+The @code{device} request processes its arguments in copy mode
+(@pxref{Copy Mode}).  An initial neutral double quote in @var{contents}
+is stripped to allow embedding of leading spaces.
+@cindex @code{\&}, in @code{\X}
+@cindex @code{\)}, in @code{\X}
+@cindex @code{\%}, in @code{\X}
+@ifnotinfo
+@cindex @code{\:}, in @code{\X}
+@end ifnotinfo
+@ifinfo
+@cindex @code{\@r{<colon>}}, in @code{\X}
+@end ifinfo
+By contrast, within @code{\X} arguments, the escape sequences @code{\&},
+@code{\)}, @code{\%}, and @code{\:} are ignored; @code{\@key{SP}} and
+@code{\~} are converted to single space characters; and @code{\\} has
+its escape character stripped.  So that the basic Latin subset of the
+Unicode character set@footnote{that is, ISO@tie{}646:1991-IRV or,
+popularly, ``US-ASCII''} can be reliably encoded in device control
+commands, seven special character escape sequences (@samp{\-},
+@samp{\[aq]}, @samp{\[dq]}, @samp{\[ga]}, @samp{\[ha]}, @samp{\[rs]},
+and @samp{\[ti]},) are mapped to basic Latin characters; see the
+@cite{groff_char@r{(7)}} man page.  For this transformation, character
+translations and special character definitions are
+ignored.@footnote{They are bypassed because these parameters are not
+rendered as glyphs in the output; instead, they remain abstract
+characters---in a PDF bookmark or a URL, for example.} The use of any
+other escape sequence in @code{\X} parameters is normally an error.
+
+@kindex use_charnames_in_special
+@cindex @file{DESC} file, and @code{use_charnames_in_special} keyword
+@cindex @code{\X}, and special characters
+If the @code{use_charnames_in_special} directive appears in the output
+device's @file{DESC} file, the use of special character escape sequences
+is @emph{not} an error; they are simply output verbatim (with the
+exception of the seven mapped to Unicode basic Latin characters,
+discussed above).  @code{use_charnames_in_special} is currently employed
+only by @code{grohtml}.
+@endDefesc
+
+@DefreqList {devicem, name}
+@DefescItemx {\\Y, , n, }
+@DefescItem {\\Y, (, nm, }
+@DefescListEnd {\\Y, [, name, ]}
+This is approximately equivalent to @samp{\X'\*[@var{name}]'}
+(one-character name@tie{}@var{n}, two-character name @var{nm}).
+However, the contents of the string or macro @var{name} are not
+interpreted; also it is permitted for @var{name} to have been defined as
+a macro and thus contain newlines (it is not permitted for the argument
+to @code{\X} to contain newlines).  The inclusion of newlines requires
+an extension to the @acronym{AT&T} @code{troff} output format, and
+confuses drivers that do not know about this extension (@pxref{Device
+Control Commands}).
+@endDefesc
+
+@DefreqList {tag, name}
+@DefreqListEndx {taga, name}
+Reserved for internal use.
+@endDefreq
+
+
+@c =====================================================================
+
+@node Miscellaneous, Gtroff Internals, Postprocessor Access, GNU troff Reference
+@section Miscellaneous
+
+We document here GNU @code{troff} features that fit poorly elsewhere.
+
+@DefreqList {nm, [@Var{start} [@Var{increment} [@Var{space} [@Var{indentation}]]]]}
+@DefregItemx {ln}
+@DefregListEndx {.nm}
+@cindex printing line numbers (@code{nm})
+@cindex line numbers, printing (@code{nm})
+@cindex numbers, line, printing (@code{nm})
+Begin (or, with no arguments, cease) numbering output lines.
+@var{start} assigns the number of the @emph{next} output line.  Only
+line numbers divisible by @var{increment} are marked (default:
+@samp{1}).  @var{space} configures the horizontal spacing between the
+number and the text (default: @samp{1}).  Any given @var{indentation} is
+applied to the numbers (default: @samp{0}).  The third and fourth
+arguments are reckoned in numeral widths (@code{\0}).  @var{start} must
+be non-negative and @var{increment} positive.
+
+The formatter aligns the number to the right in a width of three numeral
+spaces plus @var{indentation}, then catenates @var{space} and the output
+line.  The line length is @emph{not} reduced.  Depending on the value of
+the page offset,@footnote{Recall @ref{Line Layout}.} numbers wider than
+the allocated space protrude into the left margin, or shift the output
+line to the right.
+
+Line numbering parameters corresponding to missing arguments are not
+altered.  After numbering is disabled, @samp{.nm +0} resumes it using
+the previously active parameters.
+
+The parameters of @code{nm} are associated with the environment
+(@pxref{Environments}).
+
+@cindex output line number register (@code{ln})
+@cindex line number, output, register (@code{ln})
+While numbering is enabled, the output line number register @code{ln} is
+updated as each line is output, even if no line number is formatted with
+it because it is being skipped (it is not a multiple of @var{increment})
+or because numbering is suppressed (see the @code{nn} request below).
+
+The @code{.nm} register tracks the enablement status of numbering.
+Temporary suspension of numbering with the @code{nn} request does
+@emph{not} alter its value.
+
+@Example
+.po 5n
+.ll 44n
+Programming,
+when stripped of all its circumstantial irrelevancies,
+.nm 999 1 1 -4
+boils down to no more and no less than
+.nm +0 3
+very effective thinking so as to avoid unmastered
+.nn 2
+complexity,
+to very vigorous separation of your many
+different concerns.
+.br
+\(em Edsger Dijkstra
+.sp
+.nm 1 1 1
+This guy's arrogance takes your breath away.
+.br
+\(em John Backus
+    @result{}      Programming,  when  stripped of all its cir-
+    @result{}  999 cumstantial irrelevancies, boils down to  no
+    @result{}      more  and no less than very effective think-
+    @result{}      ing so as to avoid unmastered complexity, to
+    @result{}      very vigorous separation of your  many  dif-
+    @result{}      ferent concerns.
+    @result{} 1002 -- Edsger Dijkstra
+    @result{}
+    @result{}    1 This guy@quoteright{}s arrogance takes your breath away.
+    @result{}    2 -- John Backus
+@endExample
+@endDefreq
+
+@DefreqList {nn, [@Var{skip}]}
+@DefregListEndx {.nn}
+Suppress numbering of the next @var{skip} output lines that would
+otherwise be numbered.  The default is@tie{}1.  @code{nn} can be invoked
+when line numbering is not active; suppression of numbering will take
+effect for @var{skip} lines once @code{nm} enables it.
+
+The @code{.nn} register stores the count of output lines still to have
+their numbering suppressed.
+
+This count is associated with the environment (@pxref{Environments}).
+@endDefreq
+
+@need 1000
+To test whether the current output line will be numbered, you must check
+both the @code{.nm} and @code{.nn} registers.
+
+@Example
+  .de is-numbered
+  .  nop This line
+  .  ie (\\n[.nm] & (1-\\n[.nn])) IS
+  .  el                           ISN'T
+  .  nop numbered.
+  .  br
+  ..
+  Test line numbering.
+  .is-numbered
+  .nm 1
+  .nn 1
+  .is-numbered
+  .is-numbered
+  .nm
+  .is-numbered
+    @result{} Test line numbering.  This line ISN@quoteright{}T numbered.
+    @result{} This line ISN@quoteright{}T numbered.
+    @result{}   1 This line IS numbered.
+    @result{} This line ISN@quoteright{}T numbered.
+@endExample
+
+@Defreq {mc, [@Var{margin-character} [@Var{distance}]}
+@cindex margin glyph (@code{mc})
+@cindex glyph, for margins (@code{mc})
+Begin (or, with no arguments, cease) writing a @dfn{margin-character} to
+the right of each output line.  The @var{distance} argument separates
+@var{margin-character} from the right margin.  If absent, the most
+recent value is used; the default is 10@tie{}points.  If an output line
+exceeds the line length, the margin character is appended to it.
+@cindex @code{tl} request, and @code{mc}
+No margin character is written on lines produced by the @code{tl}
+request.
+
+The margin character is a property of the output line; the margin
+character last configured when the line is output controls.  If the
+margin character is disabled before an output line breaks, none is
+output (but see below).
+
+The margin character is associated with the environment
+(@pxref{Environments}).
+
+@Example
+.ll 5i
+.nf
+.mc \[br]
+This paragraph is marked with a margin character.
+.sp
+As seen above, vertical space isn't thus marked.
+\&
+An output line that is present, but empty, is.
+@c We deliberately overset these lines to mimic `mc`'s behavior.
+    @result{} This paragraph is marked with a margin character.  |
+    @result{}
+    @result{} As seen above, vertical space isn@quoteright{}t thus marked.   |
+    @result{}                                                    |
+    @result{} An output line that is present, but empty, is.     |
+@endExample
+@endDefreq
+
+For compatibility with @acronym{AT&T} @code{troff}, a call to @code{mc}
+to set the margin character can't be undone immediately; at least one
+line gets a margin character.
+
+@Example
+.ll 10n
+.nf
+.mc |
+.mc *
+.mc
+foo
+bar
+    @result{} foo        *
+    @result{} bar
+@endExample
+
+@pindex gdiffmk
+@pindex nrchbar
+@pindex changebar
+@pindex diffmk
+The margin character mechanism is commonly used to annotate changes in
+documents.  The @code{groff} distribution ships a program,
+@command{gdiffmk}, to assist with this task.@footnote{Historically,
+tools named @command{nrchbar} and @command{changebar} were developed for
+marking changes with margin characters and could be found in archives of
+the @code{comp.sources.unix} @acronym{USENET} group.  Some proprietary
+Unices also offer(ed) a @command{diffmk} program.}
+
+@DefreqList {psbb, file}
+@DefregItemx {llx}
+@DefregItemx {lly}
+@DefregItemx {urx}
+@DefregListEndx {ury}
+@cindex PostScript, bounding box
+@cindex bounding box
+Retrieve the bounding box of the PostScript image found in @var{file},
+which must conform to Adobe's @dfn{Document Structuring Conventions}
+(DSC), locate a @code{%%BoundingBox} comment, and store the (upper-,
+lower-, @w{-left}, @w{-right}) values into the registers @code{llx},
+@code{lly}, @code{urx}, and @code{ury}.  If an error occurs (for
+example, if no @code{%%BoundingBox} comment is present), the formatter
+sets these registers to@tie{}0.
+
+The search path for @var{file} can be controlled with the @option{-I}
+command-line option.
+@endDefreq
+
+@codequotebacktick off
+@codequoteundirected off
+
+
+@c =====================================================================
+
+@node Gtroff Internals, Debugging, Miscellaneous, GNU troff Reference
+@section @code{gtroff} Internals
+
+@cindex input token
+@cindex token, input
+@cindex output node
+@cindex node, output
+@code{gtroff} processes input in three steps.  One or more input
+characters are converted to an @dfn{input token}.@footnote{Except the
+escape sequences @code{\f}, @code{\F}, @code{\H}, @code{\m}, @code{\M},
+@code{\R}, @code{\s}, and @code{\S}, which are processed immediately if
+not in copy mode.}  Then, one or more input tokens are converted to
+an @dfn{output node}.  Finally, output nodes are converted to the
+intermediate output language understood by all output devices.
+
+Actually, before step one happens, @code{gtroff} converts certain escape
+sequences into reserved input characters (not accessible by the user);
+such reserved characters are used for other internal processing also --
+this is the very reason why not all characters are valid input.
+@xref{Identifiers}, for more on this topic.
+
+For example, the input string @samp{fi\[:u]} is converted into a
+character token @samp{f}, a character token @samp{i}, and a special
+token @samp{:u} (representing u@tie{}umlaut).  Later on, the character
+tokens @samp{f} and @samp{i} are merged to a single output node
+representing the ligature glyph @samp{fi} (provided the current font has
+a glyph for this ligature); the same happens with @samp{:u}.  All output
+glyph nodes are `processed', which means that they are invariably
+associated with a given font, font size, advance width, etc.  During the
+formatting process, @code{gtroff} itself adds various nodes to control
+the data flow.
+
+Macros, diversions, and strings collect elements in two chained lists: a
+list of input tokens that have been passed unprocessed, and a list of
+output nodes.  Consider the following diversion.
+
+@Example
+.di xxx
+a
+\!b
+c
+.br
+.di
+@endExample
+
+@noindent
+It contains these elements.
+
+@multitable {@i{vertical size node}} {token list} {element number}
+@item node list               @tab token list @tab element number
+
+@item @i{line start node}     @tab ---        @tab 1
+@item @i{glyph node @code{a}} @tab ---        @tab 2
+@item @i{word space node}     @tab ---        @tab 3
+@item ---                     @tab @code{b}   @tab 4
+@item ---                     @tab @code{\n}  @tab 5
+@item @i{glyph node @code{c}} @tab ---        @tab 6
+@item @i{vertical size node}  @tab ---        @tab 7
+@item @i{vertical size node}  @tab ---        @tab 8
+@item ---                     @tab @code{\n}  @tab 9
+@end multitable
+
+@cindex @code{\v}, internal representation
+@noindent
+Elements 1, 7, and@tie{}8 are inserted by @code{gtroff}; the latter two
+(which are always present) specify the vertical extent of the last line,
+possibly modified by @code{\x}.  The @code{br} request finishes the
+pending output line, inserting a newline input token, which is
+subsequently converted to a space when the diversion is reread.  Note
+that the word space node has a fixed width that isn't adjustable
+anymore.  To convert horizontal space nodes back to input tokens, use
+the @code{unformat} request.
+
+Macros only contain elements in the token list (and the node list is
+empty); diversions and strings can contain elements in both lists.
+
+The @code{chop} request simply reduces the number of elements in a
+macro, string, or diversion by one.  Exceptions are @dfn{compatibility
+save} and @dfn{compatibility ignore} input tokens, which are ignored.
+The @code{substring} request also ignores those input tokens.
+
+Some requests like @code{tr} or @code{cflags} work on glyph identifiers
+only; this means that the associated glyph can be changed without
+destroying this association.  This can be very helpful for substituting
+glyphs.  In the following example, we assume that glyph @samp{foo} isn't
+available by default, so we provide a substitution using the
+@code{fchar} request and map it to input character @samp{x}.
+
+@Example
+.fchar \[foo] foo
+.tr x \[foo]
+@endExample
+
+@noindent
+Now let us assume that we install an additional special font @samp{bar}
+that has glyph @samp{foo}.
+
+@Example
+.special bar
+.rchar \[foo]
+@endExample
+
+@noindent
+Since glyphs defined with @code{fchar} are searched before glyphs in
+special fonts, we must call @code{rchar} to remove the definition of the
+fallback glyph.  Anyway, the translation is still active; @samp{x} now
+maps to the real glyph @samp{foo}.
+
+@cindex compatibility mode, and parameters
+@cindex mode, compatibility, and parameters
+@cindex arguments, and compatibility mode
+@cindex parameters, and compatibility mode
+@cindex macro arguments, and compatibility mode
+@cindex request arguments, and compatibility mode
+Macro and request arguments preserve compatibility mode enablement.
+
+@Example
+.cp 1     \" switch to compatibility mode
+.de xx
+\\$1
+..
+.cp 0     \" switch compatibility mode off
+.xx caf\['e]
+    @result{} café
+@endExample
+
+@noindent
+Since compatibility mode is enabled while @code{de} is invoked, the
+macro @code{xx} enables compatibility mode when it is called.  Argument
+@code{$1} can still be handled properly because it inherits the
+compatibility mode enablement status that was active at the point where
+@code{xx} was called.
+
+After interpolation of the parameters, the compatibility save and
+restore tokens are removed.
+
+
+@c =====================================================================
+
+@codequotebacktick on
+@codequoteundirected on
+
+@need 1000
+@c BEGIN Keep parallel with section "Debugging" of groff(7).
+@node Debugging, Implementation Differences, Gtroff Internals, GNU troff Reference
+@section Debugging
+@cindex debugging
+
+@flushright
+@slanted{Standard troff voodoo, just put a power of two backslashes in
+front of it until it works and if you still have problems add a \c.}
+--- Ron Natalie
+@c https://minnie.tuhs.org/pipermail/tuhs/2021-February/023137.html
+@end flushright
+
+GNU @code{troff} is not the easiest language to debug, in part thanks to
+its design features of recursive interpolation and the use of
+multi-stage pipeline processing in the surrounding system.  Nevertheless
+there exist several features useful for troubleshooting.
+
+Preprocessors use the @code{lf} request to preserve the identity of the
+line numbers and names of input files.  GNU @code{troff} emits a variety
+of error diagnostics and supports several categories of warning; the
+output of these can be selectively suppressed.  A trace of the
+formatter's input processing stack can be emitted when errors or
+warnings occur by means of GNU @code{troff}'s @option{-b} option, or
+produced on demand with the @code{backtrace} request.  The @code{tm}
+and related requests can be used to emit customized diagnostic messages
+or for instrumentation while troubleshooting.  The @code{ex} and
+@code{ab} requests cause early termination with successful and error
+exit codes respectively, to halt further processing when continuing
+would be fruitless.  Examine the state of the formatter with requests
+that write lists of defined names (macros, strings, and diversions),
+environments, registers, and page location traps to the standard error
+stream.
+@c END Keep parallel with section "Debugging" of groff(7).
+
+@Defreq {lf, line [@Var{file}]}
+@pindex soelim
+@cindex multi-file documents
+@cindex documents, multi-file
+@cindex setting input line number (@code{lf})
+@cindex input line number, setting (@code{lf})
+@cindex number, input line, setting (@code{lf})
+Set the input line number (and, optionally, the file name) GNU
+@code{troff} shall use for error and warning messages.  @var{line} is
+the input line number of the @emph{next} line.  Without an argument, the
+request is ignored.
+
+@code{lf}'s primary purpose is to aid the debugging of documents that
+undergo preprocessing.  Programs like @command{tbl} that transform input
+in their own languages into @code{roff} requests use it so that any
+diagnostic messages emitted by @code{troff} correspond to the source
+document.
+@endDefreq
+
+@DefreqList {tm, message}
+@DefreqItemx {tm1, message}
+@DefreqListEndx {tmc, message}
+@cindex printing to stderr (@code{tm}, @code{tm1}, @code{tmc})
+@cindex stderr, printing to (@code{tm}, @code{tm1}, @code{tmc})
+Send @var{message}, which consumes the remainder of the input line and
+cannot contain special characters, to the standard error stream,
+followed by a newline.  Leading spaces in @var{message} are ignored.
+
+@code{tm1} is similar, but recognizes and strips a leading neutral
+double quote from @var{message} to allow the embedding of leading
+spaces.
+
+@code{tmc} works as @code{tm1}, but does not append a newline.
+@endDefreq
+
+@Defreq {ab, [@Var{message}]}
+@cindex aborting (@code{ab})
+Write any @var{message} to the standard error stream (like @code{tm})
+and then abort GNU @code{troff}; that is, stop processing and terminate
+with a failure status.
+@endDefreq
+
+@Defreq {ex, }
+@cindex @code{ex} request, use in debugging
+@cindex exiting (@code{ex})
+Exit GNU @code{troff}; that is, stop processing and terminate with a
+successful status.  To stop processing only the current file, use the
+@code{nx} request; see @ref{I/O}.
+@endDefreq
+
+When doing something involved, it is useful to leave the debugging
+statements in the code and have them turned on by a command-line flag.
+
+@Example
+.if \n[DB] .tm debugging output
+@endExample
+
+@noindent
+To activate such statements, use the @option{-r} option to set the
+register.
+
+@Example
+groff -rDB=1 @slanted{file}
+@endExample
+
+If it is known in advance that there are many errors and no useful
+output, GNU @code{troff} can be forced to suppress formatted output with
+the @option{-z} option.
+
+@Defreq {pev, }
+@cindex dumping environments (@code{pev})
+@cindex environments, dumping (@code{pev})
+Report the state of the current environment followed by that of all
+other environments to the standard error stream.
+@endDefreq
+
+@Defreq {pm, }
+@cindex dumping symbol table (@code{pm})
+@cindex symbol table, dumping (@code{pm})
+Report, to the standard error stream, the names of all defined macros,
+strings, and diversions with their sizes in bytes.
+@endDefreq
+
+@Defreq {pnr, }
+@cindex dumping registers (@code{pnr})
+@cindex registers, dumping (@code{pnr})
+Report the names and contents of all currently defined registers to the
+standard error stream.
+@endDefreq
+
+@Defreq {ptr, }
+@cindex dumping page location traps (@code{ptr})
+@cindex listing page location traps (@code{ptr})
+@cindex traps, page location, dumping (@code{ptr})
+@cindex traps, page location, listing (@code{ptr})
+Report the names and positions of all page location traps to the
+standard error stream.  Empty slots in the list, where a trap has been
+planted but subsequently (re)moved, are printed as well.
+@c "because they can affect the priority of subsequently planted traps."
+@c XXX Is that right?  It's useful to print the empty slots, I think,
+@c but a trap planted in an "empty" slot with .wh will become active.
+@c The slot seems to act as an immobile dummy list head, but does not
+@c change the basic list semantics.  .wh plants a trap at the head of
+@c the trap list at a location, and .ch plants a trap at the tail.
+@endDefreq
+
+@Defreq {fl, }
+@cindex flush output (@code{fl})
+@cindex output, flush (@code{fl})
+@cindex interactive use of @code{gtroff}
+@cindex @code{gtroff}, interactive use
+Instruct @code{gtroff} to flush its output immediately.  The intent is
+for interactive use, but this behaviour is currently not implemented in
+@code{gtroff}.  Contrary to Unix @code{troff}, TTY output is sent to a
+device driver also (@code{grotty}), making it non-trivial to communicate
+interactively.
+
+This request causes a line break.
+@endDefreq
+
+@Defreq {backtrace, }
+@cindex backtrace of input stack (@code{backtrace})
+@cindex input stack, backtrace (@code{backtrace})
+Write the state of the input stack to the standard error stream.
+
+Consider the following in a file @file{test}.
+
+@Example
+.de xxx
+.  backtrace
+..
+.de yyy
+.  xxx
+..
+.
+.yyy
+    @error{} troff: backtrace: 'test':2: macro 'xxx'
+    @error{} troff: backtrace: 'test':5: macro 'yyy'
+    @error{} troff: backtrace: file 'test':8
+@endExample
+
+The @option{-b} option of GNU @code{troff} causes a backtrace to be
+generated on each error or warning.  Some warnings have to be enabled;
+@xref{Warnings}.
+@endDefreq
+
+@Defreg {slimit}
+@cindex input stack, setting limit
+If greater than@tie{}0, sets the maximum quantity of objects on GNU
+@code{troff}'s internal input stack.  If less than or equal to@tie{}0,
+there is no limit: recursion can continue until program memory is
+exhausted.  The default is 1,000.
+@endDefreg
+
+@Defreq {warnscale, su}
+Set the scaling unit used in certain warnings @c `output_warning()`
+to @var{su}, which can take the values @samp{u}, @samp{i}, @samp{c},
+@samp{p}, and @samp{P}.  The default is @samp{i}.
+@endDefreq
+
+@Defreq {spreadwarn, [@Var{limit}]}
+Emit a @code{break} warning if the additional space inserted for each
+space between words in an output line adjusted to both margins with
+@w{@samp{.ad b}} is larger than or equal to @var{limit}.  A negative
+value is treated as zero; an absent argument toggles the warning on and
+off without changing @var{limit}.  The default scaling unit is @samp{m}.
+At startup, @code{spreadwarn} is inactive and @var{limit} is 3@dmn{m}.
+
+For example,
+
+@Example
+.spreadwarn 0.2m
+@endExample
+
+@noindent
+causes a warning if @code{break} warnings are not suppressed and
+@code{gtroff} must add 0.2@dmn{m} or more for each inter-word space in a
+line.  @xref{Warnings}.
+@endDefreq
+
+@cindex warnings
+GNU @code{troff} has command-line options for reporting warnings
+(@option{-w}) and backtraces (@option{-b}) when a warning or an error
+occurs.
+
+@DefreqList {warn, [@Var{n}]}
+@DefregListEndx {.warn}
+@cindex warning level (@code{warn})
+Select the categories, or ``types'', of reported warnings.
+@var{n}@tie{}is the sum of the numeric codes associated with each
+warning category that is to be enabled; all other categories are
+disabled.  The categories and their associated codes are listed in
+@ref{Warnings}.  For example, @samp{.warn 0} disables all warnings, and
+@samp{.warn 1} disables all warnings except those about missing glyphs.
+If no argument is given, all warning categories are enabled.
+
+The read-only register @code{.warn} contains the sum of the numeric
+codes of enabled warning categories.
+@endDefreq
+
+@menu
+* Warnings::
+@end menu
+
+@c ---------------------------------------------------------------------
+
+@c BEGIN Keep parallel with section "Warnings" of troff(1).
+@c Caveat: the man page sorts them by name, not number.
+@node Warnings,  , Debugging, Debugging
+@subsection Warnings
+@cindex warnings
+
+Warning diagnostics emitted by GNU @code{troff} are divided into named,
+numbered categories.  The name associated with each warning category is
+used by the @option{-w} and @option{-W} options.  Each category is also
+assigned a power of two; the sum of enabled category values is used by
+the @code{warn} request and the @code{.warn} register.
+
+Warnings of each category are produced under the following
+circumstances.
+
+@cindex categories, warning
+@cindex warning categories
+@table @samp
+@item char
+@itemx 1
+No mounted font defines a glyph for the requested character.  This
+category is enabled by default.
+
+@item number
+@itemx 2
+An invalid numeric expression was encountered.  This category is enabled
+by default.
+@xref{Numeric Expressions}.
+
+@item break
+@itemx 4
+@cindex filling, and @code{break} warnings
+@cindex mode, fill, and @code{break} warnings
+A filled output line could not be broken such that its length was less
+than the output line length @samp{\n[.l]}.  This category is enabled by
+default.
+
+@item delim
+@itemx 8
+The closing delimiter in an escape sequence was missing or mismatched.
+
+@item el
+@itemx 16
+@cindex @code{ie} request, and warnings
+@cindex @code{el} request, and warnings
+The @code{el} request was encountered with no prior corresponding
+@code{ie} request.  @xref{if-else}.
+
+@item scale
+@itemx 32
+A scaling unit inappropriate to its context was used in a numeric
+expression.
+
+@item range
+@itemx 64
+A numeric expression was out of range for its context.
+
+@item syntax
+@itemx 128
+A self-contradictory hyphenation mode was requested; an empty or
+incomplete numeric expression was encountered; an operand to a numeric
+operator was missing; an attempt was made to define a recursive, empty,
+or nonsensical character class; or a @code{groff} extension conditional
+expression operator was used while in compatibility mode.
+
+@item di
+@itemx 256
+@cindex @code{di} request, and warnings
+@cindex @code{da} request, and warnings
+@cindex @code{box} request, and warnings
+@cindex @code{boxa} request, and warnings
+A @code{di}, @code{da}, @code{box}, or @code{boxa} request was invoked
+without an argument when there was no current diversion.
+
+@item mac
+@itemx 512
+@cindex @code{de}, @code{de1}, @code{dei} requests, and warnings
+@cindex @code{am}, @code{am1}, @code{ami} requests, and warnings
+@cindex @code{ds}, @code{ds1} requests, and warnings
+@cindex @code{as}, @code{as1} requests, and warnings
+@cindex @code{di} request, and warnings
+@cindex @code{da} request, and warnings
+@cindex @code{box}, @code{boxa} requests, and warnings
+@cindex @code{\*}, and warnings
+An undefined string, macro, or diversion was used.  When such an object
+is dereferenced, an empty one of that name is automatically created.
+So, unless it is later deleted, at most one warning is given for each.
+
+This warning is also emitted upon an attempt to move an unplanted trap
+macro (@pxref{Page Location Traps}).  In such cases, the unplanted macro
+is @emph{not} dereferenced, so it is not created if it does not exist.
+
+@item reg
+@itemx 1024
+@cindex @code{nr} request, and warnings
+@cindex @code{\R}, and warnings
+@cindex @code{\n}, and warnings
+An undefined register was used.  When an undefined register is
+dereferenced, it is automatically defined with a value of@tie{}0.  So,
+unless it is later deleted, at most one warning is given for each.
+
+@item tab
+@itemx 2048
+@cindex @code{\t}, and warnings
+A tab character was encountered where a number was expected, or appeared
+in an unquoted macro argument.
+
+@item right-brace
+@itemx 4096
+@cindex @code{\@}}, and warnings
+A right brace escape sequence @code{\@}} was encountered where a number
+was expected.
+
+@item missing
+@itemx 8192
+A request was invoked with a mandatory argument absent.
+
+@item input
+@itemx 16384
+An invalid character occurred on the input stream.
+
+@item escape
+@itemx 32768
+An unsupported escape sequence was encountered.
+
+@item space
+@itemx 65536
+@cindex compatibility mode
+A space was missing between a request or macro and its argument.  This
+warning is produced when an undefined name longer than two characters is
+encountered and the first two characters of the name constitute a
+defined name.  No request is invoked, no macro called, and an empty
+macro is not defined.  This category is enabled by default.  It never
+occurs in compatibility mode.
+
+@item font
+@itemx 131072
+A non-existent font was selected, or the selection was ignored because a
+font selection escape sequence was used after the output line
+continuation escape sequence on an input line.  This category is enabled
+by default.
+
+@item ig
+@itemx 262144
+An invalid escape sequence occurred in input ignored using the @code{ig}
+request.  This warning category diagnoses a condition that is an error
+when it occurs in non-ignored input.
+
+@item color
+@itemx 524288
+An undefined color was selected, an attempt was made to define a color
+using an unrecognized color space, an invalid component in a color
+definition was encountered, or an attempt was made to redefine a default
+color.
+
+@item file
+@itemx 1048576
+An attempt was made to load a file that does not exist.  This category
+is enabled by default.
+@end table
+
+Two warning names group other warning categories for convenience.
+
+@table @samp
+@item all
+All warning categories except @samp{di}, @samp{mac} and @samp{reg}.
+This shorthand is intended to produce all warnings that are useful with
+macro packages written for @acronym{AT&T} @code{troff} and its
+descendants, which have less fastidious diagnostics than GNU
+@code{troff}.
+
+@item w
+All warning categories.  Authors of documents and macro packages
+targeting @code{groff} are encouraged to use this setting.
+@end table
+@c END Keep parallel with section "Warnings" of troff(1).
+
+@c =====================================================================
+
+@node Implementation Differences, Safer Mode, Debugging, GNU troff Reference
+@section Implementation Differences
+@cindex implementation differences
+@cindex differences in implementation
+@cindex incompatibilities with @acronym{AT&T} @code{troff}
+
+GNU @code{troff} has a number of features that cause incompatibilities
+with documents written for other versions of @code{troff}.  Some GNU
+extensions to @code{troff} have become supported by other
+implementations.
+
+@menu
+* Safer Mode::
+* Compatibility Mode::
+* Other Differences::
+@end menu
+
+@c ---------------------------------------------------------------------
+
+@node Safer Mode, Compatibility Mode, Implementation Differences, Implementation Differences
+@subsection Safer Mode
+@cindex safer mode
+@cindex mode, safer
+
+@cindex @code{pi} request, disabled by default
+@cindex @code{sy} request, disabled by default
+The formatter operates in ``safer'' mode by default; to mitigate risks
+from untrusted input documents, the @code{pi} and @code{sy} requests are
+disabled.  GNU @code{troff}'s @option{-U} option enables ``unsafe
+mode'', restoring their function and enabling additional @code{groff}
+extension requests, @code{open}, @code{opena}, and @code{pso}.
+@xref{I/O}.
+
+@c ---------------------------------------------------------------------
+
+@node Compatibility Mode, Safer Mode, Other Differences, Implementation Differences
+@subsection Compatibility Mode
+@cindex compatibility mode
+@cindex mode, compatibility
+
+@cindex long names
+@cindex names, long
+@cindex @code{\*}, incompatibilities with @acronym{AT&T} @code{troff}
+@cindex @code{\n}, incompatibilities with @acronym{AT&T} @code{troff}
+Long identifier names may be GNU @code{troff}'s most obvious innovation.
+@acronym{AT&T} @code{troff} interprets @samp{.dsabcd} as defining a
+string @samp{ab} with contents @samp{cd}.  Normally, GNU @code{troff}
+interprets this as a call of a macro named @code{dsabcd}.
+@acronym{AT&T} @code{troff} also interprets @samp{\*[} and @samp{\n[} as
+an interpolation of a string or register, respectively, named @samp{[}.
+In GNU @code{troff}, however, the @samp{[} is normally interpreted as
+delimiting a long name.  In compatibility mode, GNU @code{troff}
+interprets names in the traditional way; they thus can be two characters
+long at most.
+
+@DefreqList {cp, [@Var{n}]}
+@DefregListEndx {.C}
+If @var{n} is missing or non-zero, turn on compatibility mode;
+otherwise, turn it off.
+
+The read-only register @code{.C} is@tie{}1 if compatibility mode is on,
+0@tie{}otherwise.
+
+Compatibility mode can be also turned on with the @option{-C}
+command-line option.
+@endDefreq
+
+@DefreqList {do, name}
+@DefregListEndx {.cp}
+The @code{do} request interprets the string, request, diversion, or
+macro @var{name} (along with any further arguments) with compatibility
+mode disabled.  Compatibility mode is restored (only if it was active)
+when the @emph{expansion} of @var{name} is interpreted; that is, the
+restored compatibility state applies to the contents of the macro,
+string, or diversion @var{name} as well as data read from files or pipes
+if @var{name} is any of the @code{so}, @code{soquiet}, @code{mso},
+@code{msoquiet}, or @code{pso} requests.
+
+The following example illustrates several aspects of @code{do} behavior.
+
+@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
+    @result{} FOO groff FOO compatibility c1 ~
+@endExample
+
+The read-only register @code{.cp}, meaningful only when dereferenced
+from a @code{do} request, is@tie{}1 if compatibility mode was on when
+the @code{do} request was encountered, and 0@tie{}if it was not.  This
+register is specialized and may require a statement of rationale.
+
+When writing macro packages or documents that use GNU @code{troff}
+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 @code{so} or @code{mso} requests---you may desire correct operation
+regardless of compatibility mode enablement in the surrounding context.
+It may occur to you to save the existing value of @samp{\n(.C} into a
+register, say, @samp{_C}, at the beginning of your file, turn
+compatibility mode off with @samp{.cp 0}, then restore it from that
+register at the end with @samp{.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 lest you
+``clobber'' the value from a preceding or enclosing context.  The
+two-character register name space of @acronym{AT&T} @code{troff} is
+confining and mnemonically challenging; you may wish to use the more
+capacious name space of GNU @code{troff}.  However, attempting @samp{.nr
+_my_saved_C \n(.C} will not work in compatibility mode; the register
+name is too long.  ``This is exactly what @code{do} is for,'' you think,
+@samp{.do nr _my_saved_C \n(.C}.  The foregoing will always save zero to
+your register, because @code{do} turns compatibility mode @emph{off}
+while it interprets its argument list.
+
+@need 375 @c 250 < x < 500
+To robustly save compatibility mode before switching it off, use
+
+@Example
+.do nr _my_saved_C \n[.cp]
+.cp 0
+@endExample
+
+at the beginning of your file, followed by
+
+@Example
+.cp \n[_my_saved_C]
+.do rr _my_saved_C
+@endExample
+
+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.
+@endDefreq
+
+@cindex input level in delimited arguments
+@cindex interpolation depth in delimited arguments
+@cindex delimited arguments, incompatibilities with @acronym{AT&T} @code{troff}
+Normally, GNU @code{troff} preserves the interpolation depth in
+delimited arguments, but not in compatibility mode.
+
+@Example
+.ds xx '
+\w'abc\*(xxdef'
+    @result{} 168 @r{(normal mode on a terminal device)}
+    @result{} 72def' @r{(compatibility mode on a terminal device)}
+@endExample
+
+@cindex @code{\f}, incompatibilities with @acronym{AT&T} @code{troff}
+@cindex @code{\H}, incompatibilities with @acronym{AT&T} @code{troff}
+@cindex @code{\s}, incompatibilities with @acronym{AT&T} @code{troff}
+@cindex @code{\S}, incompatibilities with @acronym{AT&T} @code{troff}
+Furthermore, the escape sequences @code{\f}, @code{\H}, @code{\m},
+@code{\M}, @code{\R}, @code{\s}, and @code{\S} are transparent for the
+purpose of recognizing a control character at the beginning of a line
+only in compatibility mode.  For example, this code produces bold output
+in both cases, but the text differs.
+
+@Example
+.de xx
+Hello!
+..
+\fB.xx\fP
+    @result{} .xx @r{(normal mode)}
+    @result{} Hello! @r{(compatibility mode)}
+@endExample
+
+@cindex @code{\s}, incompatibilities with @acronym{AT&T} @code{troff}
+Normally, the syntax form @code{\s}@var{n} accepts only a single
+character (a digit) for @var{n}, consistently with other forms that
+originated in @acronym{AT&T} @code{troff}, like @code{\*}, @code{\$},
+@code{\f}, @code{\g}, @code{\k}, @code{\n}, and @code{\z}.  In
+compatibility mode only, a non-zero@tie{}@var{n} must be in the range
+4--39.  Legacy documents relying upon this quirk of parsing@footnote{The
+Graphic Systems C/A/T phototypesetter (the original device target for
+@acronym{AT&T} @code{troff}) supported only a few discrete type sizes
+in the range 6--36 points, 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@tie{}#54 (§2.3), and more recently, McIlroy
+referred to it as a ``living fossil''.} should be migrated to another
+@code{\s} form.
+
+@c ---------------------------------------------------------------------
+
+@node Other Differences, , Compatibility Mode, Implementation Differences
+@subsection Other Differences
+
+@code{groff} request names unrecognized by other @code{troff}
+implementations will likely be ignored by them; escape sequences that
+are @code{groff} extensions are liable to be interpreted as if the
+escape character were not present.
+@cindex @code{\~}, incompatibilities with @acronym{AT&T} @code{troff}
+For example, the adjustable, non-breaking escape sequence @code{\~}
+@c BEGIN Keep in sync with groff_diff(7) and groff_man_style(7).
+is also supported by Heirloom Doctools @code{troff} 050915 (September
+2005), @code{mandoc} 1.9.5 (2009-09-21), @code{neatroff} (commit
+1c6ab0f6e, 2016-09-13), and Plan@tie{}9 from User Space @code{troff}
+(commit 93f8143600, 2022-08-12), but not by Solaris or Documenter's
+Workbench @code{troff}s.
+@c as of this writing, 2022-08-13
+@c END Keep in sync with groff_diff(7) and groff_man_style(7).
+@xref{Manipulating Filling and Adjustment}.
+
+@cindex @code{\A}, incompatibilities with @acronym{AT&T} @code{troff}
+@cindex @code{\|}, incompatibilities with @acronym{AT&T} @code{troff}
+@cindex @code{\^}, incompatibilities with @acronym{AT&T} @code{troff}
+@cindex @code{\&}, incompatibilities with @acronym{AT&T} @code{troff}
+@cindex @code{\@{}, incompatibilities with @acronym{AT&T} @code{troff}
+@cindex @code{\@}}, incompatibilities with @acronym{AT&T} @code{troff}
+@cindex @code{\@key{SP}}, incompatibilities with @acronym{AT&T} @code{troff}
+@cindex @code{\'}, incompatibilities with @acronym{AT&T} @code{troff}
+@cindex @code{\`}, incompatibilities with @acronym{AT&T} @code{troff}
+@cindex @code{\-}, incompatibilities with @acronym{AT&T} @code{troff}
+@cindex @code{\_}, incompatibilities with @acronym{AT&T} @code{troff}
+@cindex @code{\!}, incompatibilities with @acronym{AT&T} @code{troff}
+@cindex @code{\%}, incompatibilities with @acronym{AT&T} @code{troff}
+@cindex @code{\c}, incompatibilities with @acronym{AT&T} @code{troff}
+GNU @code{troff} does not allow the use of the escape sequences
+@code{\|}, @code{\^}, @code{\&}, @code{\@{}, @code{\@}},
+@code{\@key{SP}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
+@code{\%}, and @code{\c} in identifiers; @acronym{AT&T} @code{troff}
+does.  The @code{\A} escape sequence (@pxref{Identifiers}) may be
+helpful in avoiding use of these escape sequences in names.
+
+@cindex adjustment to both margins, difference from @acronym{AT&T} @code{troff}
+@cindex rivers
+When adjusting to both margins, @acronym{AT&T} @code{troff} at first
+adjusts spaces starting from the right; GNU @code{troff} begins from
+the left.  Both implementations adjust spaces from opposite ends on
+alternating output lines in this adjustment mode to prevent ``rivers''
+in the text.
+
+@cindex hyphenation, incompatibilities with @acronym{AT&T} @code{troff}
+GNU @code{troff} does not always hyphenate words as @acronym{AT&T}
+@code{troff} does.  The @acronym{AT&T} implementation uses a set of
+hard-coded rules specific to English, while GNU @code{troff} uses
+language-specific hyphenation pattern files derived from @TeX{}.
+Furthermore, in old versions of @code{troff} there was a limited amount
+of space to store hyphenation exceptions (arguments to the @code{hw}
+request); GNU @code{troff} has no such restriction.
+
+@cindex output device name string (@code{.T}), in other implementations
+GNU @code{troff} predefines a string @code{.T} containing the argument
+given to the @option{-T} command-line option, namely the current output
+device (for example, @samp{pdf} or @samp{utf8}).  The existence of this
+string is a common feature of post-CSTR@tie{}#54
+@code{troff}s@footnote{DWB@tie{}3.3, Solaris, Heirloom Doctools, and
+Plan@tie{}9 @code{troff} all support it.} but valid values are specific
+to each implementation.
+
+@cindex removal of read-only registers, incompatibility with @acronym{AT&T} @code{troff}
+@cindex register, read-only, removal, incompatibility with @acronym{AT&T} @code{troff}
+@cindex read-only register removal, incompatibility with @acronym{AT&T} @code{troff}
+@acronym{AT&T} @code{troff} ignored attempts to remove read-only
+registers; GNU @code{troff} honors such requests.  @xref{Built-in
+Registers}.
+
+@cindex output device usage register (@code{.T}), incompatibility with @acronym{AT&T} @code{troff}
+The (read-only) register @code{.T} interpolates@tie{}1 if GNU
+@code{troff} is called with the @option{-T} command-line option, and
+0@tie{}otherwise.  This behavior differs from AT&T @code{troff}, which
+interpolated@tie{}1 only if @code{nroff} was the formatter and was
+called with @option{-T}.
+
+@cindex @code{lf} request, incompatibilities with @acronym{AT&T} @code{troff}
+@acronym{AT&T} @code{troff} and other implementations handle the
+@code{lf} request differently.  For them, its @var{line} argument
+changes the line number of the @emph{current} line.
+
+@cindex environment availability and naming, incompatibilities with
+@acronym{AT&T} @code{troff} had only environments named @samp{0},
+@samp{1}, and @samp{2}.  In GNU @code{troff}, any number of environments
+may exist, using any valid identifiers for their names
+(@pxref{Identifiers}.)
+
+@cindex fractional point sizes
+@cindex fractional type sizes
+@cindex point sizes, fractional
+@cindex type sizes, fractional
+@cindex sizes, fractional
+@cindex @code{ps} request, incompatibilities with @acronym{AT&T} @code{troff}
+Fractional type sizes cause one noteworthy incompatibility.  In
+@acronym{AT&T} @code{troff} the @code{ps} request ignores scaling units
+and thus @samp{.ps 10u} sets the type size to 10@tie{}points, whereas in
+GNU @code{troff} it sets the type size to 10@tie{}@emph{scaled} points.
+@xref{Using Fractional Type Sizes}.
+
+@cindex @code{ab} request, incompatibilities with @acronym{AT&T} @code{troff}
+The @code{ab} request differs from @acronym{AT&T} @code{troff}:
+GNU @code{troff} writes no message to the standard error stream if no
+arguments are given, and it exits with a failure status instead of a
+successful one.
+
+@cindex @code{bp} request, incompatibilities with @acronym{AT&T} @code{troff}
+The @code{bp} request differs from @acronym{AT&T} @code{troff}:
+GNU @code{troff} does not accept a scaling unit on the argument, a page
+number; the former (somewhat uselessly) does.
+
+@cindex @code{pm} request, incompatibilities with @acronym{AT&T} @code{troff}
+The @code{pm} request differs from @acronym{AT&T} @code{troff}:
+GNU @code{troff} reports the sizes of macros, strings, and diversions in
+bytes and ignores an argument to report only the sum of the sizes.
+
+@cindex @code{ss} request, incompatibilities with @acronym{AT&T} @code{troff}
+Unlike @acronym{AT&T} @code{troff}, GNU @code{troff} does not ignore the
+@code{ss} request if the output is a terminal device; instead, the
+values of minimal inter-word and additional inter-sentence space are
+each rounded down to the nearest multiple of@tie{}12.
+
+@cindex @code{bd} request, incompatibilities with @acronym{AT&T} @code{troff}
+@cindex @code{cs} request, incompatibilities with @acronym{AT&T} @code{troff}
+@cindex @code{tr} request, incompatibilities with @acronym{AT&T} @code{troff}
+@cindex @code{fp} request, incompatibilities with @acronym{AT&T} @code{troff}
+@cindex input characters and output glyphs, compatibility with @acronym{AT&T} @code{troff}
+@cindex output glyphs, and input characters, compatibility with @acronym{AT&T} @code{troff}
+@cindex characters, input, and output glyphs, compatibility with @acronym{AT&T} @code{troff}
+@cindex glyphs, output, and input characters, compatibility with @acronym{AT&T} @code{troff}
+In GNU @code{troff} there is a fundamental difference between
+(unformatted) characters and (formatted) glyphs.  Everything that
+affects how a glyph is output is stored with the glyph node; once a
+glyph node has been constructed, it is unaffected by any subsequent
+requests that are executed, including @code{bd}, @code{cs}, @code{tkf},
+@code{tr}, or @code{fp} requests.  Normally, glyphs are constructed from
+characters immediately before the glyph is added to an output line.
+Macros, diversions, and strings are all, in fact, the same type of
+object; they contain a sequence of intermixed character and glyph nodes.
+Special characters transform from one to the other:@: before being added
+to the output, they behave as characters; afterward, they are glyphs.  A
+glyph node does not behave like a character node when it is processed by
+a macro:@: it does not inherit any of the special properties that the
+character from which it was constructed might have had.  For example,
+the input
+
+@Example
+.di x
+\\\\
+.br
+.di
+.x
+@endExample
+
+@noindent
+produces @samp{\\} in GNU @code{troff}.  Each pair of backslashes
+becomes one backslash @emph{glyph}; the resulting backslashes are thus
+not interpreted as escape @emph{characters} when they are reread as the
+diversion is output.  @acronym{AT&T} @code{troff} @emph{would} interpret
+them as escape characters when rereading them and end up printing one
+@samp{\}.
+
+@cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
+@cindex backslash, printing (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]})
+@cindex @code{\e}, incompatibilities with @acronym{AT&T} @code{troff}
+@cindex @code{\!}, incompatibilities with @acronym{AT&T} @code{troff}
+@cindex @code{\?}, incompatibilities with @acronym{AT&T} @code{troff}
+@cindex transparent output, incompatibilities with @acronym{AT&T} @code{troff}
+@cindex output, transparent, incompatibilities with @acronym{AT&T} @code{troff}
+One correct way to obtain a printable backslash in most documents is to
+use the @code{\e} escape sequence; this always prints a single instance
+of the current escape character,@footnote{Naturally, if you've changed
+the escape character, you need to prefix the @code{e} with whatever it
+is---and you'll likely get something other than a backslash in the
+output.} regardless of whether or not it is used in a diversion; it
+also works in both GNU @code{troff} and @acronym{AT&T} @code{troff}.
+
+The other correct way, appropriate in contexts independent of the
+backslash's common use as a @code{troff} escape character---perhaps in
+discussion of character sets or other programming languages---is
+the character escape @code{\(rs} or @code{\[rs]}, for ``reverse
+solidus'', from its name in the @acronym{ECMA-6} (@acronym{ISO/IEC} 646)
+standard.@footnote{The @code{rs} special character identifier was not
+defined in @acronym{AT&T} @code{troff}'s font description files, but is
+in those of its lineal descendant, Heirloom Doctools @code{troff}, as of
+the latter's 060716 release (July 2006).}
+
+To store an escape sequence in a diversion that is interpreted when the
+diversion is reread, either use the traditional @code{\!} transparent
+output facility, or, if this is unsuitable, the new @code{\?} escape
+sequence.  @xref{Diversions} and @ref{Gtroff Internals}.
+
+In the somewhat pathological case where a diversion exists containing a
+partially collected line and a partially collected line at the top-level
+diversion has never existed, @acronym{AT&T} @code{troff} will output the
+partially collected line at the end of input; GNU @code{troff} will not.
+
+@codequotebacktick off
+@codequoteundirected off
+
+
+
+@c =====================================================================
+@c =====================================================================
+
+@node File Formats, Copying This Manual, GNU troff Reference, Top
+@chapter File Formats
+@cindex file formats
+@cindex formats, file
+
+All files read and written by @code{gtroff} are text files.  The
+following two sections describe their format.
+
+@menu
+* gtroff Output::
+* Device and Font Description Files::
+@end menu
+
+
+@c =====================================================================
+
+@codequotebacktick on
+@codequoteundirected on
+
+@c BEGIN TODO: Make parallel with groff_out(5).
+@node gtroff Output, Device and Font Description Files, File Formats, File Formats
+@section @code{gtroff} Output
+@cindex @code{gtroff}, output
+@cindex output, @code{gtroff}
+
+This section describes the @code{groff} intermediate output format
+produced by GNU @code{troff}.
+
+As @code{groff} is a wrapper program around GNU @code{troff} and
+automatically calls an output driver (or ``postprocessor''), this output
+does not show up normally.  This is why it is called
+@emph{intermediate}.  @code{groff} provides the option @option{-Z} to
+inhibit postprocessing such that the produced intermediate output is
+sent to standard output just as it is when calling GNU @code{troff}
+directly.
+
+@cindex @code{troff} output
+@cindex output, @code{troff}
+@cindex intermediate output
+@cindex output, intermediate
+Here, the term @dfn{troff output} describes what is output by
+GNU @code{troff}, while @dfn{intermediate output} refers to the language
+that is accepted by the parser that prepares this output for the output
+drivers.  This parser handles whitespace more flexibly than
+@acronym{AT&T}'s implementation and implements obsolete elements for
+compatibility; otherwise, both formats are the same.@footnote{The parser
+and postprocessor for intermediate output can be found in the file@*
+@file{@var{groff-source-dir}/src/libs/libdriver/input.cpp}.}
+
+The main purpose of the intermediate output concept is to facilitate the
+development of postprocessors by providing a common programming
+interface for all devices.  It has a language of its own that is
+completely different from the @code{gtroff} language.  While the
+@code{gtroff} language is a high-level programming language for text
+processing, the intermediate output language is a kind of low-level
+assembler language by specifying all positions on the page for writing
+and drawing.
+
+The intermediate output produced by @code{gtroff} is fairly readable,
+while output from @acronym{AT&T} @code{troff} is rather hard to
+understand because of strange habits that are still supported, but not
+used any longer by @code{gtroff}.
+
+@menu
+* Language Concepts::
+* Command Reference::
+* Intermediate Output Examples::
+* Output Language Compatibility::
+@end menu
+
+@c ---------------------------------------------------------------------
+
+@node Language Concepts, Command Reference, gtroff Output, gtroff Output
+@subsection Language Concepts
+
+The fundamental operation of the GNU @code{troff} formatter is the
+translation of the @code{groff} input language into a device-independent
+form primarily concerned with what has to be written or drawn at
+specific positions on the output device.  This language is simple and
+imperative.  In the following discussion, the term @dfn{command} always
+refers to this intermediate output language, and never to the
+@code{groff} language intended for direct use by document authors.
+Intermediate output commands comprise several categories: glyph output;
+font, color, and text size selection; motion of the printing position;
+page advancement; drawing of geometric objects; and device control
+commands, a catch-all for operations not easily classified as any of the
+foregoing, such as directives to start and stop output, identify the
+intended output device, or place URL hyperlinks in supported output
+formats.
+
+@menu
+* Separation::
+* Argument Units::
+* Document Parts::
+@end menu
+
+@node Separation, Argument Units, Language Concepts, Language Concepts
+@subsubsection Separation
+
+@acronym{AT&T} @code{troff} output has strange requirements regarding
+whitespace.  The @code{gtroff} output parser, however, is more tolerant,
+making whitespace maximally optional.  Such characters, i.e., the tab,
+space, and newline, always have a syntactical meaning.  They are never
+printable because spacing within the output is always done by
+positioning commands.
+
+Any sequence of space or tab characters is treated as a single
+@dfn{syntactical space}.  It separates commands and arguments, but is
+only required when there would occur a clashing between the command code
+and the arguments without the space.  Most often, this happens when
+variable-length command names, arguments, argument lists, or command
+clusters meet.  Commands and arguments with a known, fixed length need
+not be separated by syntactical space.
+
+A line break is a syntactical element, too.  Every command argument can
+be followed by whitespace, a comment, or a newline character.  Thus a
+@dfn{syntactical line break} is defined to consist of optional
+syntactical space that is optionally followed by a comment, and a
+newline character.
+
+The normal commands, those for positioning and text, consist of a single
+letter taking a fixed number of arguments.  For historical reasons, the
+parser allows stacking of such commands on the same line, but
+fortunately, in @code{gtroff}'s intermediate output, every command with
+at least one argument is followed by a line break, thus providing
+excellent readability.
+
+The other commands---those for drawing and device controlling---have a
+more complicated structure; some recognize long command names, and some
+take a variable number of arguments.  So all @samp{D} and @samp{x}
+commands were designed to request a syntactical line break after their
+last argument.  Only one command, @w{@samp{x X}}, has an argument that
+can span several input lines; all other commands must have all of
+their arguments on the same line as the command, i.e., the arguments may
+not be split by a line break.
+
+Empty lines (these are lines containing only space and/or a comment),
+can occur everywhere.  They are just ignored.
+
+@node Argument Units, Document Parts, Separation, Language Concepts
+@subsubsection Argument Units
+
+Some commands take integer arguments that are assumed to represent
+values in a measurement unit, but the letter for the corresponding
+scaling unit is not written with the output command arguments.  Most
+commands assume the scaling unit @samp{u}, the basic unit of the device,
+some use @samp{z}, the scaled point unit of the device, while others,
+such as the color commands, expect plain integers.
+
+Single characters can have the eighth bit set, as can the names of
+fonts and special characters.  The names of characters and fonts can be
+of arbitrary length.  A character that is to be printed is always in
+the current font.
+
+A string argument is always terminated by the next whitespace character
+(space, tab, or newline); an embedded @samp{#} character is regarded as
+part of the argument, not as the beginning of a comment command.  An
+integer argument is already terminated by the next non-digit character,
+which then is regarded as the first character of the next argument or
+command.
+
+@node Document Parts,  , Argument Units, Language Concepts
+@subsubsection Document Parts
+
+A correct intermediate output document consists of two parts, the
+@dfn{prologue} and the @dfn{body}.
+
+The task of the prologue is to set the general device parameters using
+three exactly specified commands.  @code{gtroff}'s prologue is
+guaranteed to consist of the following three lines (in that order):
+
+@Example
+x T @var{device}
+x res @var{n} @var{h} @var{v}
+x init
+@endExample
+
+@noindent
+with the arguments set as outlined in @ref{Device Control Commands}.
+The parser for the intermediate output format is able to interpret
+additional whitespace and comments as well even in the prologue.
+
+The body is the main section for processing the document data.
+Syntactically, it is a sequence of any commands different from the ones
+used in the prologue.  Processing is terminated as soon as the first
+@w{@samp{x stop}} command is encountered; the last line of any
+@code{gtroff} intermediate output always contains such a command.
+
+Semantically, the body is page oriented.  A new page is started by a
+@samp{p} command.  Positioning, writing, and drawing commands are always
+done within the current page, so they cannot occur before the first
+@samp{p} command.  Absolute positioning (by the @samp{H} and @samp{V}
+commands) is done relative to the current page; all other positioning is
+done relative to the current location within this page.
+
+@c ---------------------------------------------------------------------
+
+@node Command Reference, Intermediate Output Examples, Language Concepts, gtroff Output
+@subsection Command Reference
+
+This section describes all intermediate output commands, both from
+@acronym{AT&T} @code{troff} as well as the @code{gtroff} extensions.
+
+@menu
+* Comment Command::
+* Simple Commands::
+* Graphics Commands::
+* Device Control Commands::
+* Obsolete Command::
+@end menu
+
+@node Comment Command, Simple Commands, Command Reference, Command Reference
+@subsubsection Comment Command
+
+@table @code
+@item #@var{anything}@angles{end of line}
+A comment.  Ignore any characters from the @samp{#} character up to the
+next newline character.
+
+This command is the only possibility for commenting in the intermediate
+output.  Each comment can be preceded by arbitrary syntactical space;
+every command can be terminated by a comment.
+@end table
+
+@node Simple Commands, Graphics Commands, Comment Command, Command Reference
+@subsubsection Simple Commands
+
+The commands in this subsection have a command code consisting of a
+single character, taking a fixed number of arguments.  Most of them are
+commands for positioning and text writing.  These commands are tolerant
+of whitespace.  Optionally, syntactical space can be inserted before,
+after, and between the command letter and its arguments.  All of these
+commands are stackable; i.e., they can be preceded by other simple
+commands or followed by arbitrary other commands on the same line.  A
+separating syntactical space is necessary only when two integer
+arguments would clash or if the preceding argument ends with a string
+argument.
+
+@table @code
+@ignore
+.if (\n[@USE_ENV_STACK] == 1) \{\
+.command {
+Open a new environment by copying the actual device configuration data
+to the environment stack.
+.
+The current environment is setup by the device specification and
+manipulated by the setting commands.
+.
+.
+.command }
+Close the actual environment (opened by a preceding
+.BR { \~command)
+and restore the previous environment from the environment
+stack as the actual device configuration data.
+.
+\}              \" endif @USE_ENV_STACK
+@end ignore
+
+@item C @var{id}@angles{whitespace}
+Typeset the glyph of the special character @var{id}.  Trailing
+syntactical space is necessary to allow special character names of
+arbitrary length.  The drawing position is not advanced.
+
+@item c @var{g}
+Typeset the glyph of the ordinary character@tie{}@var{c}.  The drawing
+position is not advanced.
+
+@item f @var{n}
+Select the font mounted at position@tie{}@var{n}.  @var{n}@tie{}cannot
+be negative.
+
+@item H @var{n}
+Horizontally move the drawing position to @var{n}@tie{}basic units from
+the left edge of the page.  @var{n}@tie{}cannot be negative.
+
+@item h @var{n}
+Move the drawing position right @var{n} basic units.  @acronym{AT&T}
+@code{troff} allowed negative @var{n}; GNU @code{troff} does not produce
+such values, but @code{groff}'s output driver library handles them.
+
+@item m @var{color-scheme} @r{[}@var{component} @dots{}@r{]}
+Select the stroke color using the @var{component}s in the color space
+@var{scheme}.  Each @var{component} is an integer between 0 and 65535.
+The quantity of components and their meanings vary with each
+@var{scheme}.  This command is a @code{groff} extension.
+
+@table @code
+@item mc @var{cyan} @var{magenta} @var{yellow}
+Use the CMY color scheme with components cyan, magenta, and yellow.
+
+@item md
+Use the default color (no components; black in most cases).
+
+@item mg @var{gray}
+Use a grayscale color scheme with a component ranging between 0 (black)
+and 65535 (white).
+
+@item mk @var{cyan} @var{magenta} @var{yellow} @var{black}
+Use the CMYK color scheme with components cyan, magenta, yellow, and
+black.
+
+@item mr @var{red} @var{green} @var{blue}
+Use the RGB color scheme with components red, green, and blue.
+@end table
+
+@item N @var{n}
+Typeset the glyph with index@tie{}@var{n} in the current font.
+@var{n}@tie{}is normally a non-negative integer.  The drawing position
+is not advanced.  The @code{html} and @code{xhtml} devices use this
+command with negative@tie{}@var{n} to produce unbreakable space; the
+absolute value of @var{n} is taken and interpreted in basic units.
+
+@item n @var{b} @var{a}
+Indicate a break.  No action is performed; the command is present to
+make the output more easily parsed.  The integers @var{b}
+and@tie{}@var{a} describe the vertical space amounts before and after
+the break, respectively.  GNU @code{troff} issues this command but
+@code{groff}'s output driver library ignores it.  See @code{v} and
+@code{V} below.
+
+@item p @var{n}
+Begin a new page, setting its number to@tie{}@var{n}.  Each page is
+independent, even from those using the same number.  The vertical
+drawing position is set to@tie{}0.  All positioning, writing, and
+drawing commands are interpreted in the context of a page, so a
+@code{p}@tie{}command must precede them.
+
+@item s @var{n}
+Set type size to @var{n} scaled points (unit@tie{}@code{z} in GNU
+@code{troff}.
+@acronym{AT&T} @code{troff} used unscaled points @code{p} instead;
+see @ref{Output Language Compatibility}.
+
+@item t @var{xyz}@angles{whitespace}
+@itemx t @var{xyz} @var{dummy-arg}@angles{whitespace}
+Typeset a word @var{xyz}; that is, set a sequence of ordinary glyphs
+named @var{x}, @var{y}, @var{z}, @dots{}, terminated by a space
+character or a line break; an optional second integer argument is
+ignored (this allows the formatter to generate an even number of
+arguments). @c XXX: Why?
+Each glyph is set at the current drawing position, and the position is
+then advanced horizontally by the glyph's width.  A glyph's width is
+read from its metrics in the font description file, scaled to the
+current type size, and rounded to a multiple of the horizontal motion
+quantum.  Use the @code{C} command to emplace glyphs of special
+characters.  The @code{t}@tie{}command is a @code{groff} extension and
+is output only for devices whose @file{DESC} file contains the
+@code{tcommand} directive; see @ref{DESC File Format}.
+
+@item u @var{n} @var{xyz}@angles{whitespace}
+Typeset word @var{xyz} with track kerning.  As @code{t}, but after
+placing each glyph, the drawing position is further advanced
+horizontally by@tie{}@var{n} basic units (@code{u}).  The
+@code{u}@tie{}command is a @code{groff} extension and is output only for
+devices whose @file{DESC} file contains the @code{tcommand} directive;
+see @ref{DESC File Format}.
+
+@item V @var{n}
+Vertically move the drawing position to @var{n}@tie{}basic units from
+the top edge of the page.  @var{n}@tie{}cannot be negative.
+
+@item v @var{n}
+Move the drawing position down @var{n} basic units.  @acronym{AT&T}
+@code{troff} allowed negative @var{n}; GNU @code{troff} does not produce
+such values, but @code{groff}'s output driver library handles them.
+
+@item w
+Indicate an inter-word space.  No action is performed; the command is
+present to make the output more easily parsed.  Only adjustable,
+breakable inter-word spaces are thus described; those resulting from
+@code{\~} or horizontal motion escape sequences are not.  GNU
+@code{troff} issues this command but @code{groff}'s output driver
+library ignores it.  See @code{h} and @code{H} above.
+@end table
+
+@node Graphics Commands, Device Control Commands, Simple Commands, Command Reference
+@subsubsection Graphics Commands
+
+Each graphics or drawing command in the intermediate output starts with
+the letter @samp{D}, followed by one or two characters that specify a
+subcommand; this is followed by a fixed or variable number of integer
+arguments that are separated by a single space character.  A @samp{D}
+command may not be followed by another command on the same line (apart
+from a comment), so each @samp{D} command is terminated by a syntactical
+line break.
+
+@code{gtroff} output follows the classical spacing rules (no space
+between command and subcommand, all arguments are preceded by a single
+space character), but the parser allows optional space between the
+command letters and makes the space before the first argument optional.
+As usual, each space can be any sequence of tab and space characters.
+
+Some graphics commands can take a variable number of arguments.  In this
+case, they are integers representing a size measured in basic units
+@samp{u}.  The arguments called @var{h1}, @var{h2}, @dots{}, @var{hn}
+stand for horizontal distances where positive means right, negative
+left.  The arguments called @var{v1}, @var{v2}, @dots{}, @var{vn} stand
+for vertical distances where positive means down, negative up.  All
+these distances are offsets relative to the current location.
+
+Each graphics command directly corresponds to a similar @code{gtroff}
+@code{\D} escape sequence.  @xref{Drawing Geometric Objects}.
+
+Unknown @samp{D} commands are assumed to be device-specific.  Its
+arguments are parsed as strings; the whole information is then sent to
+the postprocessor.
+
+In the following command reference, the syntax element @angles{line
+break} means a syntactical line break as defined above.
+
+@table @code
+@item D~ @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break}
+Draw B-spline from current position to offset (@var{h1},@var{v1}), then
+to offset (@var{h2},@var{v2}), if given, etc., up to
+(@var{hn},@var{vn}).  This command takes a variable number of argument
+pairs; the current position is moved to the terminal point of the drawn
+curve.
+
+@item Da @var{h1} @var{v1} @var{h2} @var{v2}@angles{line break}
+Draw arc from current position to
+(@var{h1},@var{v1})@math{+}(@var{h2},@var{v2}) with center at
+(@var{h1},@var{v1}); then move the current position to the final point
+of the arc.
+
+@item DC @var{d}@angles{line break}
+@itemx DC @var{d} @var{dummy-arg}@angles{line break}
+Draw a solid circle using the current fill color with
+diameter@tie{}@var{d} (integer in basic units @samp{u}) with leftmost
+point at the current position; then move the current position to the
+rightmost point of the circle.  An optional second integer argument is
+ignored (this allows the formatter to generate an even number of
+arguments).  This command is a @code{gtroff} extension.
+
+@item Dc @var{d}@angles{line break}
+Draw circle line with diameter@tie{}@var{d} (integer in basic units
+@samp{u}) with leftmost point at the current position; then move the
+current position to the rightmost point of the circle.
+
+@item DE @var{h} @var{v}@angles{line break}
+Draw a solid ellipse in the current fill color with a horizontal
+diameter of@tie{}@var{h} and a vertical diameter of@tie{}@var{v} (both
+integers in basic units @samp{u}) with the leftmost point at the current
+position; then move to the rightmost point of the ellipse.  This command
+is a @code{gtroff} extension.
+
+@item De @var{h} @var{v}@angles{line break}
+Draw an outlined ellipse with a horizontal diameter of@tie{}@var{h} and
+a vertical diameter of@tie{}@var{v} (both integers in basic units
+@samp{u}) with the leftmost point at current position; then move to the
+rightmost point of the ellipse.
+
+@item DF @var{color-scheme} @r{[}@var{component} @dots{}@r{]}@angles{line break}
+Set fill color for solid drawing objects using different color schemes;
+the analogous command for setting the color of text, line graphics, and
+the outline of graphic objects is @samp{m}.  The color components are
+specified as integer arguments between 0 and 65535.  The number of color
+components and their meaning vary for the different color schemes.
+These commands are generated by @code{gtroff}'s escape sequences
+@samp{\D'F @dots{}'} and @code{\M} (with no other corresponding
+graphics commands).  No position changing.  This command is a
+@code{gtroff} extension.
+
+@table @code
+@item DFc @var{cyan} @var{magenta} @var{yellow}@angles{line break}
+Set fill color for solid drawing objects using the CMY color scheme,
+having the 3@tie{}color components @var{cyan}, @var{magenta}, and
+@var{yellow}.
+
+@item DFd@angles{line break}
+Set fill color for solid drawing objects to the default fill color value
+(black in most cases).  No component arguments.
+
+@item DFg @var{gray}@angles{line break}
+Set fill color for solid drawing objects to the shade of gray given by
+the argument, an integer between 0 (black) and 65535 (white).
+
+@item DFk @var{cyan} @var{magenta} @var{yellow} @var{black}@angles{line break}
+Set fill color for solid drawing objects using the CMYK color scheme,
+having the 4@tie{}color components @var{cyan}, @var{magenta},
+@var{yellow}, and @var{black}.
+
+@item DFr @var{red} @var{green} @var{blue}@angles{line break}
+Set fill color for solid drawing objects using the RGB color scheme,
+having the 3@tie{}color components @var{red}, @var{green}, and
+@var{blue}.
+@end table
+
+@item Df @var{n}@angles{line break}
+The argument@tie{}@var{n} must be an integer in the range @math{-32767}
+to 32767.
+
+@table @asis
+@item @math{0 @leq{} @var{n} @leq{} 1000}
+Set the color for filling solid drawing objects to a shade of gray,
+where 0 corresponds to solid white, 1000 (the default) to solid black,
+and values in between to intermediate shades of gray; this is obsoleted
+by command @samp{DFg}.
+
+@item @math{@var{n} < 0} or @math{@var{n} > 1000}
+Set the filling color to the color that is currently being used for the
+text and the outline, see command @samp{m}.  For example, the command
+sequence
+
+@Example
+mg 0 0 65535
+Df -1
+@endExample
+
+@noindent
+sets all colors to blue.
+@end table
+
+@noindent
+No position changing.  This command is a @code{gtroff} extension.
+
+@item Dl @var{h} @var{v}@angles{line break}
+Draw line from current position to offset (@var{h},@var{v}) (integers in
+basic units @samp{u}); then set current position to the end of the drawn
+line.
+
+@item Dp @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break}
+Draw a polygon line from current position to offset (@var{h1},@var{v1}),
+from there to offset (@var{h2},@var{v2}), etc., up to offset
+(@var{hn},@var{vn}), and from there back to the starting position.  For
+historical reasons, the position is changed by adding the sum of all
+arguments with odd index to the actual horizontal position and the even
+ones to the vertical position.  Although this doesn't make sense it is
+kept for compatibility.
+@ignore
+As the polygon is closed, the end of drawing is the starting point, so
+the position doesn't change.
+@end ignore
+This command is a @code{gtroff} extension.
+
+@item DP @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break}
+Draw a solid polygon in the current fill color rather than an outlined
+polygon, using the same arguments and positioning as the corresponding
+@samp{Dp} command.
+@ignore
+No position changing.
+@end ignore
+This command is a @code{gtroff} extension.
+
+@item Dt @var{n}@angles{line break}
+Set the current line thickness to@tie{}@var{n} (an integer in basic
+units @samp{u}) if @math{@var{n}>0}; if @math{@var{n}=0} select the
+smallest available line thickness; if @math{@var{n}<0} set the line
+thickness proportional to the type size (this is the default before the
+first @samp{Dt} command was specified).  For historical reasons, the
+horizontal position is changed by adding the argument to the actual
+horizontal position, while the vertical position is not changed.
+Although this doesn't make sense it is kept for compatibility.
+@ignore
+No position changing.
+@end ignore
+This command is a @code{gtroff} extension.
+@end table
+
+@node Device Control Commands, Obsolete Command, Graphics Commands, Command Reference
+@subsubsection Device Control Commands
+
+Each device control command starts with the letter @samp{x}, followed by
+a space character (optional or arbitrary space or tab in @code{gtroff})
+and a subcommand letter or word; each argument (if any) must be preceded
+by a syntactical space.  All @samp{x} commands are terminated by a
+syntactical line break; no device control command can be followed by
+another command on the same line (except a comment).
+
+The subcommand is basically a single letter, but to increase
+readability, it can be written as a word, i.e., an arbitrary sequence of
+characters terminated by the next tab, space, or newline character.  All
+characters of the subcommand word but the first are simply ignored.  For
+example, @code{gtroff} outputs the initialization command @w{@samp{x i}}
+as @w{@samp{x init}} and the resolution command @w{@samp{x r}} as
+@w{@samp{x res}}.
+
+In the following, the syntax element @angles{line break} means a
+syntactical line break (@pxref{Separation}).
+
+@table @code
+@item xF @var{name}@angles{line break}
+The @samp{F} stands for @var{Filename}.
+
+Use @var{name} as the intended name for the current file in error
+reports.  This is useful for remembering the original file name when
+@code{gtroff} uses an internal piping mechanism.  The input file is not
+changed by this command.  This command is a @code{gtroff} extension.
+
+@item xf @var{n} @var{s}@angles{line break}
+The @samp{f} stands for @var{font}.
+
+Mount font position@tie{}@var{n} (a non-negative integer) with font
+named@tie{}@var{s} (a text word).  @xref{Font Positions}.
+
+@item xH @var{n}@angles{line break}
+The @samp{H} stands for @var{Height}.
+
+Set glyph height to@tie{}@var{n} (a positive integer in scaled points
+@samp{z}).  @acronym{AT&T} @code{troff} uses the unit points (@samp{p})
+instead.  @xref{Output Language Compatibility}.
+
+@item xi@angles{line break}
+The @samp{i} stands for @var{init}.
+
+Initialize device.  This is the third command of the prologue.
+
+@item xp@angles{line break}
+The @samp{p} stands for @var{pause}.
+
+Parsed but ignored.  The @acronym{AT&T} @code{troff} manual documents
+this command as
+
+@display
+pause device, can be restarted
+@end display
+
+but GNU @code{troff} output drivers do nothing with this command.
+
+@item xr @var{n} @var{h} @var{v}@angles{line break}
+The @samp{r} stands for @var{resolution}.
+
+Resolution is@tie{}@var{n}, while @var{h} is the minimal horizontal
+motion, and @var{v} the minimal vertical motion possible with this
+device; all arguments are positive integers in basic units @samp{u} per
+inch.  This is the second command of the prologue.
+
+@item xS @var{n}@angles{line break}
+The @samp{S} stands for @var{Slant}.
+
+Set slant to@tie{}@var{n} (an integer in basic units @samp{u}).
+
+@item xs@angles{line break}
+The @samp{s} stands for @var{stop}.
+
+Terminates the processing of the current file; issued as the last
+command of any intermediate @code{troff} output.
+
+@item xt@angles{line break}
+The @samp{t} stands for @var{trailer}.
+
+Generate trailer information, if any.  In GNU @code{troff}, this is
+ignored.
+
+@item xT @var{xxx}@angles{line break}
+The @samp{T} stands for @var{Typesetter}.
+
+Set the name of the output driver to @var{xxx}, a sequence of
+non-whitespace characters terminated by whitespace.  The possible names
+correspond to those of @code{groff}'s @option{-T} option.  This is the
+first command of the prologue.
+
+@item xu @var{n}@angles{line break}
+The @samp{u} stands for @var{underline}.
+
+Configure underlining of spaces.  If @var{n} is@tie{}1, start
+underlining of spaces; if @var{n} is@tie{}0, stop underlining of spaces.
+This is needed for the @code{cu} request in @code{nroff} mode and is
+ignored otherwise.  This command is a @code{gtroff} extension.
+
+@item xX @var{anything}@angles{line break}
+The @samp{x} stands for @var{X-escape}.
+
+Send string @var{anything} uninterpreted to the device.  If the line
+following this command starts with a @samp{+} character this line is
+interpreted as a continuation line in the following sense.  The @samp{+}
+is ignored, but a newline character is sent instead to the device, the
+rest of the line is sent uninterpreted.  The same applies to all
+following lines until the first character of a line is not a @samp{+}
+character.  This command is generated by the @code{gtroff} escape
+sequence @code{\X}.  The line-continuing feature is a @code{gtroff}
+extension.
+@end table
+
+@node Obsolete Command,  , Device Control Commands, Command Reference
+@subsubsection Obsolete Command
+In @acronym{AT&T} @code{troff} output, the writing of a single glyph is
+mostly done by a very strange command that combines a horizontal move
+and a single character giving the glyph name.  It doesn't have a command
+code, but is represented by a 3-character argument consisting of exactly
+2@tie{}digits and a character.
+
+@table @asis
+@item @var{dd}@var{g}
+Move right @var{dd} (exactly two decimal digits) basic units @samp{u},
+then print glyph@tie{}@var{g} (represented as a single character).
+
+In GNU @code{troff}, arbitrary syntactical space around and within this
+command is allowed.  Only when a preceding command on the same line ends
+with an argument of variable length is a separating space obligatory.
+In @acronym{AT&T} @code{troff}, large clusters of these and other
+commands are used, mostly without spaces; this made such output almost
+unreadable.
+@end table
+
+For modern high-resolution devices, this command does not make sense
+because the width of the glyphs can become much larger than two decimal
+digits.  In @code{gtroff}, this is only used for the devices @code{X75},
+@code{X75-12}, @code{X100}, and @code{X100-12}.  For other devices, the
+commands @samp{t} and @samp{u} provide a better functionality.
+
+@c ---------------------------------------------------------------------
+
+@node Intermediate Output Examples, Output Language Compatibility, Command Reference, gtroff Output
+@subsection Intermediate Output Examples
+
+This section presents the intermediate output generated from the same
+input for three different devices.  The input is the sentence @samp{hell
+world} fed into @code{gtroff} on the command line.
+
+@table @asis
+@item High-resolution device @code{ps}
+
+This is the standard output of @code{gtroff} if no @option{-T} option is
+given.
+
+@example
+@group
+shell> echo "hell world" | groff -Z -T ps
+
+x T ps
+x res 72000 1 1
+x init
+@end group
+p1
+x font 5 TR
+f5
+s10000
+V12000
+H72000
+thell
+wh2500
+tw
+H96620
+torld
+n12000 0
+@group
+x trailer
+V792000
+x stop
+@end group
+@end example
+
+@noindent
+This output can be fed into @code{grops} to get its representation as a
+PostScript file.
+
+@item Low-resolution device @code{latin1}
+
+This is similar to the high-resolution device except that the
+positioning is done at a minor scale.  Some comments (lines starting
+with @samp{#}) were added for clarification; they were not generated by
+the formatter.
+
+@example
+@group
+shell> echo "hell world" | groff -Z -T latin1
+
+# prologue
+x T latin1
+x res 240 24 40
+x init
+@end group
+# begin a new page
+p1
+# font setup
+x font 1 R
+f1
+s10
+# initial positioning on the page
+V40
+H0
+# write text 'hell'
+thell
+# inform about space, and issue a horizontal jump
+wh24
+# write text 'world'
+tworld
+# announce line break, but do nothing because...
+n40 0
+@group
+# ...the end of the document has been reached
+x trailer
+V2640
+x stop
+@end group
+@end example
+
+@noindent
+This output can be fed into @code{grotty} to get a formatted text
+document.
+
+@item @acronym{AT&T} @code{troff} output
+Since a computer monitor has a much lower resolution than modern
+printers, the intermediate output for X11 devices can use the
+jump-and-write command with its 2-digit displacements.
+
+@example
+@group
+shell> echo "hell world" | groff -Z -T X100
+
+x T X100
+x res 100 1 1
+x init
+@end group
+p1
+x font 5 TR
+f5
+s10
+V16
+H100
+# write text with jump-and-write commands
+ch07e07l03lw06w11o07r05l03dh7
+n16 0
+@group
+x trailer
+V1100
+x stop
+@end group
+@end example
+
+@noindent
+This output can be fed into @code{xditview} or @code{gxditview} for
+displaying in@tie{}X.
+
+Due to the obsolete jump-and-write command, the text clusters in the
+@acronym{AT&T} @code{troff} output are almost unreadable.
+@end table
+
+@c ---------------------------------------------------------------------
+
+@node Output Language Compatibility,  , Intermediate Output Examples, gtroff Output
+@subsection Output Language Compatibility
+
+The intermediate output language of @acronym{AT&T} @code{troff} was
+first documented in @cite{A Typesetter-independent TROFF}, by Brian
+Kernighan, and by 1992 the @acronym{AT&T} @code{troff} manual was
+updated to incorprate a description of it.
+
+The GNU @code{troff} intermediate output format is compatible with this
+specification except for the following features.
+
+@itemize @bullet
+@item
+The classical quasi-device independence is not yet implemented.
+
+@item
+The old hardware was very different from what we use today.  So the
+@code{groff} devices are also fundamentally different from the ones
+in @acronym{AT&T} @code{troff}.  For example, the @acronym{AT&T}
+PostScript device is called @code{post} and has a resolution of only 720
+units per inch, suitable for printers 20 years ago, while @code{groff}'s
+@code{ps} device has a resolution of 72000 units per inch.  Maybe, by
+implementing some rescaling mechanism similar to the classical
+quasi-device independence, @code{groff} could emulate @acronym{AT&T}'s
+@code{post} device.
+
+@item
+The B-spline command @samp{D~} is correctly handled by the intermediate
+output parser, but the drawing routines aren't implemented in some of
+the postprocessor programs.
+
+@item
+The argument of the commands @samp{s} and @w{@samp{x H}} has the
+implicit unit scaled point @samp{z} in @code{gtroff}, while
+@acronym{AT&T} @code{troff} has point (@samp{p}).  This isn't an
+incompatibility but a compatible extension, for both units coincide for
+all devices without a @code{sizescale} parameter in the @file{DESC}
+file, including all postprocessors from @acronym{AT&T} and
+@code{groff}'s text devices.  The few @code{groff} devices with a
+@code{sizescale} parameter either do not exist for @acronym{AT&T}
+@code{troff}, have a different name, or seem to have a different
+resolution.  So conflicts are very unlikely.
+
+@item
+The position changing after the commands @samp{Dp}, @samp{DP}, and
+@samp{Dt} is illogical, but as old versions of @code{gtroff} used this
+feature it is kept for compatibility reasons.
+
+@ignore
+Temporarily, there existed some confusion on the positioning after the
+@samp{D} commands that are @code{groff} extensions.  This has been
+clarified by establishing the classical rule for all @code{groff}
+drawing commands:
+
+@itemize
+@item
+The position after a graphic object has been drawn is at its end; for
+circles and ellipses, the `end' is at the right side.
+
+@item
+From this, the positionings specified for the drawing commands above
+follow quite naturally.
+@end itemize
+@end ignore
+
+@end itemize
+@c END TODO: Make parallel with groff_out(5).
+
+
+@c =====================================================================
+
+@c BEGIN Keep parallel with groff_font(5).
+@node Device and Font Description Files,  , gtroff Output, File Formats
+@section Device and Font Description Files
+@cindex font files
+@cindex files, font
+
+The @code{groff} font and output device description formats are slight
+extensions of those used by @acronym{AT&T} device-independent
+@code{troff}.  In distinction to the @acronym{AT&T} implementation,
+@code{groff} lacks a binary format; all files are text
+files.@footnote{Plan@tie{}9 @code{troff} has also abandoned the binary
+format.}  The device and font description files for a device @var{name}
+are stored in a @file{dev@var{name}} directory.  The device description
+file is called @file{DESC}, and, for each font supported by the device,
+a font description file is called@tie{}@file{@var{f}}, where
+@var{f}@tie{}is usually an abbreviation of a font's name and/or style.
+For example, the @code{ps} (PostScript) device has @code{groff} font
+description files for Times roman (@file{TR}) and Zapf Chancery Medium
+italic (@file{ZCMI}), among many others, while the @code{utf8} device
+(for terminal emulators) has only font descriptions for the roman,
+italic, bold, and bold-italic styles (@file{R}, @file{I}, @file{B}, and
+@file{BI}, respectively).
+
+Device and font description files are read both by the formatter, GNU
+@code{troff}, and by output drivers.  The programs delegate these files'
+processing to an internal library, @file{libgroff}, ensuring their
+consistent interpretation.
+
+@menu
+* DESC File Format::
+* Font Description File Format::
+@end menu
+
+@c ---------------------------------------------------------------------
+
+@node DESC File Format, Font Description File Format, Device and Font Description Files, Device and Font Description Files
+@subsection @file{DESC} File Format
+@cindex @file{DESC} file format
+@cindex font description file format
+@cindex format of font description file
+
+The @file{DESC} file contains a series of directives; each begins a
+line.  Their order is not important, with two exceptions: (1) the
+@code{res} directive must precede any @code{papersize} directive; and
+(2) the @code{charset} directive must come last (if at all).  If a
+directive name is repeated, later entries in the file override previous
+ones (except that the paper dimensions are computed based on the
+@code{res} directive last seen when @code{papersize} is encountered).
+Spaces and/or tabs separate words and are ignored at line boundaries.
+@cindex comments in device description files
+@cindex device description files, comments
+@kindex #
+Comments start with the @samp{#} character and extend to the end of a
+line.  Empty lines are ignored.
+
+@table @code
+@item family @var{fam}
+@kindex family
+The default font family is @var{fam}.
+
+@item fonts @var{n} @var{F1} @r{@dots{}} @var{Fn}
+@kindex fonts
+Fonts @var{F1}, @dots{}, @var{Fn} are mounted at font positions
+@var{m}+1, @dots{}, @var{m}+@var{n} where @var{m} is the number of
+@code{styles} (see below).  This directive may extend over more than one
+line.  A font name of@tie{}@code{0} causes no font to be mounted at the
+corresponding position.
+
+@item hor @var{n}
+@kindex hor
+@cindex horizontal motion quantum
+@cindex motion quantum, horizontal
+@cindex quantum, horizontal motion
+@cindex horizontal resolution
+@cindex resolution, horizontal
+The horizontal motion quantum is @var{n}@tie{}basic units.  All
+horizontal quantities are rounded to multiples of@tie{}@var{n}.
+
+@item image_generator @var{program}
+@kindex image_generator
+@cindex PostScript, PNG image generation
+@cindex PNG image generation from PostScript
+Use @var{program} to generate PNG images from PostScript input.  Under
+GNU/Linux, this is usually @code{gs}, but under other systems (notably
+Cygwin) it might be set to another name.  The @code{grohtml} driver uses
+this directive.
+
+@item paperlength @var{n}
+@kindex paperlength
+The vertical dimension of the output medium is @var{n}@tie{}basic units
+(deprecated: use @code{papersize} instead).
+
+@item papersize @var{format-or-dimension-pair-or-file-name} @r{@dots{}}
+@kindex papersize
+The dimensions of the output medium are as according to the
+argument, which is either a standard paper format, a pair of dimensions,
+or the name of a plain text file containing either of the foregoing.
+
+Recognized paper formats are the ISO and DIN formats
+@code{A0}--@code{A7}, @code{B0}--@code{B7}, @code{C0}--@code{C7},
+@code{D0}--@code{D7}; the U.S.@: paper types @code{letter},
+@code{legal}, @code{tabloid}, @code{ledger}, @code{statement}, and
+@code{executive}; and the envelope formats @code{com10}, @code{monarch},
+and @code{DL}.  Matching is performed without regard for lettercase.
+
+Alternatively, the argument can be a custom paper format in the format
+@code{@var{length},@var{width}} (with no spaces before or after the
+comma).  Both @var{length} and @var{width} must have a unit appended;
+valid units are @samp{i} for inches, @samp{c} for centimeters, @samp{p}
+for points, and @samp{P} for picas.  Example: @samp{12c,235p}.  An
+argument that starts with a digit is always treated as a custom paper
+format.
+
+Finally, the argument can be a file name (e.g., @file{/etc/papersize});
+if the file can be opened, the first line is read and a match attempted
+against each of the other forms.  No comment syntax is supported.
+
+More than one argument can be specified;
+each is scanned in turn and the first valid paper specification used.
+
+@item paperwidth @var{n}
+@kindex paperwidth
+The horizontal dimension of the output medium is @var{n}@tie{}basic
+units (deprecated: use @code{papersize} instead).
+
+@item pass_filenames
+@kindex pass_filenames
+Direct GNU @code{troff} to emit the name of the source file being
+processed.  This is achieved with the intermediate output command
+@samp{x F}, which @code{grohtml} interprets.
+
+@item postpro @var{program}
+@kindex postpro
+Use @var{program} as the postprocessor.
+
+@item prepro @var{program}
+@kindex prepro
+Use @var{program} as a preprocessor.  The @code{html} and @code{xhtml}
+output devices use this directive.
+
+@item print @var{program}
+@kindex print
+Use @var{program} as a spooler program for printing.  If omitted, the
+@option{-l} and @option{-L} options of @code{groff} are ignored.
+
+@item res @var{n}
+@kindex res
+@cindex device resolution
+@cindex resolution, device
+The device resolution is @var{n}@tie{}basic units per inch.
+
+@item sizes @var{s1} @r{@dots{}} @var{sn} 0
+@kindex sizes
+The device has fonts at @var{s1}, @dots{}, @var{sn} scaled points (see
+below).  The list of sizes must be terminated by@tie{}@code{0}.  Each
+@var{si} can also be a range of sizes @var{m}--@var{n}.  The list can
+extend over more than one line.
+
+@item sizescale @var{n}
+@kindex sizescale
+A typographical point is subdivided into @var{n}@tie{}scaled points.
+The default is@tie{}@code{1}.  @xref{Using Fractional Type Sizes}.
+
+@item styles @var{S1} @r{@dots{}} @var{Sm}
+@kindex styles
+The first@tie{}@var{m} mounting positions are associated with styles
+@var{S1}, @dots{}, @var{Sm}.
+
+@item tcommand
+@kindex tcommand
+The postprocessor can handle the @samp{t} and @samp{u} intermediate
+output commands.
+
+@item unicode
+@kindex unicode
+The output device supports the complete Unicode repertoire.  This
+directive is useful only for devices that produce character entities
+instead of glyphs.
+
+If @code{unicode} is present, no @code{charset} section is required in
+the font description files since the Unicode handling built into
+@code{groff} is used.  However, if there are entries in a font
+description file's @code{charset} section, they either override the
+default mappings for those particular characters or add new mappings
+(normally for composite characters).
+
+The @code{utf8}, @code{html}, and @code{xhtml} output devices use this
+directive.
+
+@item unitwidth @var{n}
+@kindex unitwidth
+Quantities in the font description files are in basic units for fonts
+whose type size is @var{n}@tie{}scaled points.
+
+@item unscaled_charwidths
+@kindex unscaled_charwidths
+Make the font handling module always return unscaled character widths.
+The @code{grohtml} driver uses this directive.
+
+@item use_charnames_in_special
+@kindex use_charnames_in_special
+GNU @code{troff} should encode special characters inside device control
+commands; see @ref{Postprocessor Access}.  The @code{grohtml} driver
+uses this directive.
+
+@item vert @var{n}
+@kindex vert
+@cindex vertical motion quantum
+@cindex motion quantum, vertical
+@cindex quantum, vertical motion
+@cindex vertical resolution
+@cindex resolution, vertical
+The vertical motion quantum is @var{n}@tie{}basic units.  All vertical
+quantities are rounded to multiples of@tie{}@var{n}.
+
+@item charset
+@kindex charset
+This line and everything following it in the file are ignored.  It is
+recognized for compatibility with other @code{troff} implementations.
+In GNU @code{troff}, character set repertoire is described on a
+per-font basis.
+@end table
+
+@kindex spare1
+@kindex spare2
+@kindex biggestfont
+GNU @code{troff} recognizes but ignores the directives @code{spare1},
+@code{spare2}, and @code{biggestfont}.
+
+The @code{res}, @code{unitwidth}, @code{fonts}, and @code{sizes} lines
+are mandatory.  Directives not listed above are ignored by GNU
+@code{troff} but may be used by postprocessors to obtain further
+information about the device.
+
+@c ---------------------------------------------------------------------
+
+@node Font Description File Format,  , DESC File Format, Device and Font Description Files
+@subsection Font Description File Format
+@cindex font file, format
+@cindex font description file, format
+@cindex format of font files
+@cindex format of font description files
+
+On typesetting output devices, each font is typically available at
+multiple sizes.  While paper measurements in the device description file
+are in absolute units, measurements applicable to fonts must be
+proportional to the type size.  @code{groff} achieves this using the
+precedent set by @acronym{AT&T} device-independent @code{troff}: one
+font size is chosen as a norm, and all others are scaled linearly
+relative to that basis.  The ``unit width'' is the number of basic units
+per point when the font is rendered at this nominal size.
+
+For instance, @code{groff}'s @code{lbp} device uses a @code{unitwidth}
+of@tie{}800.  Its Times roman font @samp{TR} has a @code{spacewidth}
+of@tie{}833; this is also the width of its comma, period, centered
+period, and mathematical asterisk, while its @samp{M} is 2,963 basic
+units.  Thus, an @samp{M} on the @code{lbp} device is 2,963 basic units
+wide at a notional type size of 800@tie{}points.@footnote{800-point type
+is not practical for most purposes, but using it enables the quantities
+in the font description files to be expressed as integers.}
+
+A font description file has two sections.  The first is a sequence of
+directives, and is parsed similarly to the @file{DESC} file described
+above.  Except for the directive names that begin the second section,
+their ordering is immaterial.  Later directives of the same name
+override earlier ones, spaces and tabs are handled in the same way,
+@cindex comments in font description files
+@cindex font description files, comments
+@kindex #
+and the same comment syntax is supported.  Empty lines are ignored
+throughout.
+
+@table @code
+@item name @var{f}
+@kindex name
+The name of the font is@tie{}@var{f}.  @samp{DESC} is an invalid font
+name.  Simple integers are valid, but their use is
+discouraged.@footnote{@code{groff} requests and escape sequences
+interpret non-negative font names as mounting positions instead.
+Further, a font named @samp{0} cannot be automatically mounted by the
+@code{fonts} directive of a @file{DESC} file.}
+
+@item spacewidth @var{n}
+@kindex spacewidth
+The width of an unadjusted inter-word space is @var{n}@tie{}basic units.
+@end table
+
+The directives above must appear in the first section; those below are
+optional.
+
+@table @code
+@item slant @var{n}
+@kindex slant
+The font's glyphs have a slant of @var{n}@tie{}degrees; a positive
+@var{n} slants in the direction of text flow.
+
+@item ligatures @var{lig1} @r{@dots{}} @var{lign} @r{[}0@r{]}
+@kindex ligatures
+Glyphs @var{lig1}, @dots{}, @var{lign} are ligatures; possible ligatures
+are @samp{ff}, @samp{fi}, @samp{fl}, @samp{ffi} and @samp{ffl}.  For
+compatibility with other @code{troff} implementations, the list of
+ligatures may be terminated with a@tie{}@code{0}.  The list of ligatures
+must not extend over more than one line.
+
+@item special
+@cindex special fonts
+@kindex special
+The font is @dfn{special}: when a glyph is requested that is not present
+in the current font, it is sought in any mounted fonts that bear this
+property.
+@end table
+
+Other directives in this section are ignored by GNU @code{troff}, but
+may be used by postprocessors to obtain further information about the
+font.
+
+The second section contains one or two subsections.  These can appear in
+either order; the first one encountered commences the second section.
+Each starts with a directive on a line by itself.  A @code{charset}
+subsection is mandatory unless the associated @file{DESC} file contains
+the @code{unicode} directive.  Another subsection, @code{kernpairs},
+is optional.
+
+@kindex charset
+The directive @code{charset} starts the character set
+subsection.@footnote{For typesetter devices, this directive is misnamed
+since it starts a list of glyphs, not characters.}  It precedes a series
+of glyph descriptions, one per line.  Each such glyph description
+comprises a set of fields separated by spaces or tabs and organized as
+follows.
+
+@quotation
+@var{name} @var{metrics} @var{type} @var{code} [@var{entity-name}]
+[@code{--} @var{comment}]
+@end quotation
+
+@cindex 8-bit input
+@cindex input, 8-bit
+@cindex accessing unnamed glyphs with @code{\N}
+@cindex unnamed glyphs, accessing with @code{\N}
+@cindex characters, unnamed, accessing with @code{\N}
+@cindex glyphs, unnamed, accessing with @code{\N}
+@kindex ---
+@noindent
+@var{name} identifies the glyph:
+@c XXX: Move this footnote to a more general discussion since it is
+@c applicable to the groff system overall.
+@c
+@c @footnote{The distinction between input, characters, and output,
+@c glyphs, is not clearly separated in the terminology of @code{groff};
+@c for example, the @code{char} request should be called @code{glyph}
+@c since it defines an output entity.}
+if @var{name} is a printable character@tie{}@var{c}, it corresponds to
+the @code{troff} ordinary character@tie{}@var{c}.  If @var{name} is a
+multi-character sequence not beginning with @code{\}, it corresponds to
+the GNU @code{troff} special character escape sequence
+@samp{\[@var{name}]}.  A name consisting of three minus signs,
+@samp{---}, is special and indicates that the glyph is unnamed: such
+glyphs can be accessed only by the @code{\N} escape sequence in
+@code{troff}.  A special character named @samp{---} can still be defined
+using @code{char} and similar requests.  The @var{name} @samp{\-}
+defines the minus sign glyph.  Finally, @var{name} can be the
+unbreakable one-sixth and one-twelfth space escape sequences, @code{\|}
+and @code{\^} (``thin'' and ``hair'' spaces, respectively), in which
+case only the width metric described below is interpreted; a font can
+thus customize the widths of these spaces.
+@c XXX: For exhaustivity purposes...you can define "\whatever", which
+@c has to be accessed with \C'\\whatever' or \[\\whatever], but the
+@c parser matches predefined escape sequences before looking up special
+@c characters.  Most such definitions are inaccessible from the
+@c language, because nearly every '\x', where 'x' is a Unicode basic
+@c Latin character, is a predefined groff escape sequence.
+@c
+@c XXX: Commented out because the charXXX feature is very legacy, and as
+@c noted below, discouraged in font description files.
+@c
+@c GNU @code{troff} supports 8-bit input characters; however some
+@c utilities have difficulties with eight-bit characters.  For this
+@c reason, there is a convention that the entity name @samp{char@var{n}}
+@c is equivalent to the single input character whose code
+@c is@tie{}@var{n}.  For example, @samp{char163} would be equivalent to
+@c the character with code@tie{}163, which is the pounds sterling sign
+@c in the ISO@tie{}@w{Latin-1} character set.  You shouldn't use
+@c @samp{char@var{n}} entities in font description files since they are
+@c related to input, not output.  Otherwise, you get hard-coded
+@c connections between input and output encoding, which prevents use of
+@c different (input) character sets.
+
+The form of the @var{metrics} field is as follows.
+
+@display
+@group
+@var{width}[@code{,}[@var{height}[@code{,}[@var{depth}[@code{,}[@var{italic-correction}
+  [@code{,}[@var{left-italic-correction}[@code{,}[@var{subscript-correction}]]]]]]]]]]
+@end group
+@end display
+
+@noindent
+There must not be any spaces, tabs, or newlines between these
+@dfn{subfields} (which have been split here into two lines only for
+better legibility).  The subfields are in basic units expressed as
+decimal integers.  Unspecified subfields default to@tie{}@code{0}.
+Since there is no associated binary format, these values are not
+required to fit into the C language data type @samp{char} as they are in
+@acronym{AT&T} device-independent @code{troff}.
+
+The @var{width} subfield gives the width of the glyph.  The @var{height}
+subfield gives the height of the glyph (upward is positive); if a glyph
+does not extend above the baseline, it should be given a zero height,
+rather than a negative height.  The @var{depth} subfield gives the depth
+of the glyph, that is, the distance below the baseline to which the
+glyph extends (downward is positive); if a glyph does not extend below
+the baseline, it should be given a zero depth, rather than a negative
+depth.  Italic corrections are relevant to glyphs in italic or oblique
+styles.  The @var{italic-correction} is the amount of space that should
+be added after an oblique glyph to be followed immediately by an upright
+glyph.  The @var{left-italic-correction} is the amount of space that
+should be added before an oblique glyph to be preceded immediately by an
+upright glyph.  The @var{subscript-correction} is the amount of space
+that should be added after an oblique glyph to be followed by a
+subscript; it should be less than the italic correction.
+
+For fonts used with typesetting devices, the @var{type} field gives a
+featural description of the glyph: it is a bit mask recording whether
+the glyph is an ascender, descender, both, or neither.  When a @code{\w}
+escape sequence is interpolated, these values are bitwise or-ed
+together for each glyph and stored in the @code{nr} register.  In font
+descriptions for terminal devices, all glyphs might have a type of zero,
+regardless of their appearance.
+
+@table @code
+@item 0
+means the glyph lies entirely between the baseline and a horizontal line
+at the ``x-height'' of the font; typical examples are @samp{a},
+@samp{c}, and @samp{x};
+
+@item 1
+means the glyph descends below the baseline, like @samp{p};
+
+@item 2
+means the glyph ascends above the font's x-height, like @samp{A} or
+@samp{b}; and
+
+@item 3
+means the glyph is both an ascender and a descender---this is true of
+parentheses in some fonts.
+@end table
+
+The @var{code} field gives a numeric identifier that the postprocessor
+uses to render the glyph.  The glyph can be specified to @code{troff}
+using this code by means of the @code{\N} escape sequence.  @var{code}
+can be any integer.@footnote{that is, any integer parsable by the C
+standard library's @cite{strtol@r{(3)}} function}
+
+The @var{entity-name} field defines an identifier for the glyph that the
+postprocessor uses to print the GNU @code{troff} glyph @var{name}.  This
+field is optional; it was introduced so that the @code{grohtml} output
+driver could encode its character set.  For example, the glyph
+@samp{\[Po]} is represented by @samp{&pound;} in @acronym{HTML} 4.0.
+For efficiency, these data are now compiled directly into
+@code{grohtml}.  @code{grops} uses the field to build sub-encoding
+arrays for PostScript fonts containing more than 256 glyphs.  Anything
+on the line after the @var{entity-name} field or @samp{--} is ignored.
+
+A line in the @code{charset} section can also have the form
+
+@Example
+@var{name} "
+@endExample
+
+@noindent
+identifying @var{name} as another name for the glyph mentioned in the
+preceding line.  Such aliases can be chained.
+
+@kindex kernpairs
+The directive @code{kernpairs} starts a list of kerning adjustments to
+be made to adjacent glyph pairs from this font.  It contains a sequence
+of lines formatted as follows.
+
+@Example
+@var{g1} @var{g2} @var{n}
+@endExample
+
+@noindent
+The foregoing means that when glyph @var{g1} is typeset immediately
+before @var{g2}, the space between them should be increased
+by@tie{}@var{n}.  Most kerning pairs should have a negative value
+for@tie{}@var{n}.
+@c END Keep parallel with groff_font(5).
+
+@codequotebacktick off
+@codequoteundirected off
+
+
+
+@c =====================================================================
+@c =====================================================================
+
+@node Copying This Manual, Request Index, Font Description File Format, Top
+@appendix Copying This Manual
+
+@include fdl.texi
+
+
+
+@c =====================================================================
+@c =====================================================================
+
+@c This'll do us for the rest of the file...
+@codequotebacktick on
+@codequoteundirected on
+
+@node Request Index, Escape Sequence Index, Copying This Manual, Top
+@appendix Request Index
+
+Request names appear without a leading control character; the defaults
+are @code{.} for the regular control character and @code{'} for the
+no-break control character.
+
+@printindex rq
+
+
+
+@c =====================================================================
+@c =====================================================================
+
+@node Escape Sequence Index, Operator Index, Request Index, Top
+@appendix Escape Sequence Index
+
+The escape character, @code{\} by default, is always followed by at
+least one more input character, making an escape @emph{sequence}.  Any
+input token @code{\@var{X}} with @var{X} not in the list below emits a
+warning and interpolates glyph @var{X}.  Note the entries for @code{\.},
+which may be obscured by the leader dots, and for @code{\@key{RET}} and
+@code{\@key{SP}}, which are sorted alphabetically, not by code point
+order.
+
+@printindex es
+
+
+
+@c =====================================================================
+@c =====================================================================
+
+@node Operator Index, Register Index, Escape Sequence Index, Top
+@appendix Operator Index
+
+@printindex op
+
+
+
+@c =====================================================================
+@c =====================================================================
+
+@node Register Index, Macro Index, Operator Index, Top
+@appendix Register Index
+
+The macro package or program a specific register belongs to is appended
+in brackets.
+
+A register name@tie{}@code{x} consisting of exactly one character can be
+accessed as @samp{\nx}.  A register name @code{xx} consisting of exactly
+two characters can be accessed as @samp{\n(xx}.  Register names
+@code{xxx} of any length can be accessed as @samp{\n[xxx]}.
+
+@printindex vr
+
+
+
+@c =====================================================================
+@c =====================================================================
+
+@node Macro Index, String Index, Register Index, Top
+@appendix Macro Index
+
+The macro package a specific macro belongs to is appended in brackets.
+They appear without the leading control character (normally @samp{.}).
+
+@printindex ma
+
+
+
+@c =====================================================================
+@c =====================================================================
+
+@node String Index, File Keyword Index, Macro Index, Top
+@appendix String Index
+
+The macro package or program a that defines or uses each string is
+appended in brackets. (Only one string, @code{.T}, is defined by the
+@code{troff} formatter itself.)  @xref{Strings}.
+
+
+@printindex st
+
+
+
+@c =====================================================================
+@c =====================================================================
+
+@node File Keyword Index, Program and File Index, String Index, Top
+@appendix File Keyword Index
+
+@printindex ky
+
+
+
+@c =====================================================================
+@c =====================================================================
+
+@node Program and File Index, Concept Index, File Keyword Index, Top
+@appendix Program and File Index
+
+@printindex pg
+
+
+
+@c =====================================================================
+@c =====================================================================
+
+@node Concept Index,  , Program and File Index, Top
+@appendix Concept Index
+
+@printindex cp
+
+
+@bye
+
+@c Local Variables:
+@c mode: texinfo
+@c coding: latin-1
+@c fill-column: 72
+@c End:
+@c vim: set textwidth=72: