diff options
Diffstat (limited to 'doc/groff.texi')
| -rw-r--r-- | doc/groff.texi | 18927 |
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{£} 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: |