diff options
Diffstat (limited to 'doc/groff.txt')
| -rw-r--r-- | doc/groff.txt | 18123 |
1 files changed, 18123 insertions, 0 deletions
diff --git a/doc/groff.txt b/doc/groff.txt new file mode 100644 index 0000000..fab73d4 --- /dev/null +++ b/doc/groff.txt @@ -0,0 +1,18123 @@ +GNU 'troff' +1 Introduction + 1.1 Background + 1.2 What Is 'groff'? + 1.3 'groff' Capabilities + 1.4 Macro Packages + 1.5 Preprocessors + 1.6 Output Devices + 1.7 Installation + 1.8 Conventions Used in This Manual + 1.9 Credits +2 Invoking 'groff' + 2.1 Options + 2.2 Environment + 2.3 Macro Directories + 2.4 Font Directories + 2.5 Paper Format + 2.6 Invocation Examples +3 Tutorial for Macro Users + 3.1 Basics + 3.2 Common Features + 3.2.1 Paragraphs + 3.2.2 Sections and Chapters + 3.2.3 Headers and Footers + 3.2.4 Page Layout + 3.2.5 Displays and Keeps + 3.2.6 Footnotes and Endnotes + 3.2.7 Table of Contents + 3.2.8 Indexing + 3.2.9 Document Formats + 3.2.10 Columnation + 3.2.11 Font and Size Changes + 3.2.12 Predefined Text + 3.2.13 Preprocessor Support + 3.2.14 Configuration and Customization +4 Macro Packages + 4.1 'man' + 4.1.1 Optional 'man' extensions + Custom headers and footers + Ultrix-specific man macros + Simple example + 4.2 'mdoc' + 4.3 'me' + 4.4 'mm' + 4.5 'mom' + 4.6 'ms' + 4.6.1 Introduction + 4.6.1.1 Basic information + 4.6.2 Document Structure + 4.6.3 Document Control Settings + Margin settings + Titles (headers, footers) + Text settings + Paragraph settings + Heading settings + Footnote settings + Display settings + Other settings + 4.6.4 Document Description Macros + 4.6.5 Body Text + 4.6.5.1 Text settings + 4.6.5.2 Typographical symbols + 4.6.5.3 Paragraphs + 4.6.5.4 Headings + 4.6.5.5 Typeface and decoration + 4.6.5.6 Lists + 4.6.5.7 Indented regions + 4.6.5.8 Keeps, boxed keeps, and displays + 4.6.5.9 Tables, figures, equations, and references + 4.6.5.10 Footnotes + 4.6.5.11 Language and localization + 4.6.6 Page layout + 4.6.6.1 Headers and footers + 4.6.6.2 Tab stops + 4.6.6.3 Margins + 4.6.6.4 Multiple columns + 4.6.6.5 Creating a table of contents + 4.6.7 Differences from AT&T 'ms' + 4.6.7.1 Unix Version 7 'ms' macros not implemented by 'groff' 'ms' + 4.6.8 Legacy Features + AT&T accent mark strings + Berkeley accent mark and glyph strings + 4.6.9 Naming Conventions +5 GNU 'troff' Reference + 5.1 Text + 5.1.1 Filling + 5.1.2 Sentences + 5.1.3 Hyphenation + 5.1.4 Breaking + 5.1.5 Adjustment + 5.1.6 Tabs and Leaders + 5.1.7 Requests and Macros + 5.1.8 Macro Packages + 5.1.9 Input Encodings + 5.1.10 Input Conventions + 5.2 Page Geometry + 5.3 Measurements + 5.3.1 Motion Quanta + 5.3.2 Default Units + 5.4 Numeric Expressions + 5.5 Identifiers + 5.6 Formatter Instructions + 5.6.1 Control Characters + 5.6.2 Invoking Requests + 5.6.3 Calling Macros + 5.6.4 Using Escape Sequences + 5.6.5 Delimiters + 5.7 Comments + 5.8 Registers + 5.8.1 Setting Registers + 5.8.2 Interpolating Registers + 5.8.3 Auto-increment + 5.8.4 Assigning Register Formats + 5.8.5 Built-in Registers + 5.9 Manipulating Filling and Adjustment + 5.10 Manipulating Hyphenation + 5.11 Manipulating Spacing + 5.12 Tabs and Fields + 5.12.1 Leaders + 5.12.2 Fields + 5.13 Character Translations + 5.14 'troff' and 'nroff' Modes + 5.15 Line Layout + 5.16 Line Continuation + 5.17 Page Layout + 5.18 Page Control + 5.19 Using Fonts + 5.19.1 Selecting Fonts + 5.19.2 Font Families + 5.19.3 Font Positions + 5.19.4 Using Symbols + 5.19.5 Character Classes + 5.19.6 Special Fonts + 5.19.7 Artificial Fonts + 5.19.8 Ligatures and Kerning + 5.19.9 Italic Corrections + 5.19.10 Dummy Characters + 5.20 Manipulating Type Size and Vertical Spacing + 5.20.1 Changing the Type Size + 5.20.2 Changing the Vertical Spacing + 5.20.3 Using Fractional Type Sizes + 5.21 Colors + 5.22 Strings + 5.23 Conditionals and Loops + 5.23.1 Operators in Conditionals + 5.23.2 if-then + 5.23.3 if-else + 5.23.4 Conditional Blocks + 5.23.5 while + 5.24 Writing Macros + 5.24.1 Parameters + 5.24.2 Copy Mode + 5.25 Page Motions + 5.26 Drawing Geometric Objects + 5.27 Deferring Output + 5.28 Traps + 5.28.1 Vertical Position Traps + 5.28.1.1 Page Location Traps + 5.28.1.2 The Implicit Page Trap + 5.28.1.3 Diversion Traps + 5.28.2 Input Line Traps + 5.28.3 Blank Line Traps + 5.28.4 Leading Space Traps + 5.28.5 End-of-input Traps + 5.29 Diversions + 5.30 Punning Names + 5.31 Environments + 5.32 Suppressing Output + 5.33 I/O + 5.34 Postprocessor Access + 5.35 Miscellaneous + 5.36 'gtroff' Internals + 5.37 Debugging + 5.37.1 Warnings + 5.38 Implementation Differences + 5.38.1 Safer Mode + 5.38.2 Compatibility Mode + 5.38.3 Other Differences +6 File Formats + 6.1 'gtroff' Output + 6.1.1 Language Concepts + 6.1.1.1 Separation + 6.1.1.2 Argument Units + 6.1.1.3 Document Parts + 6.1.2 Command Reference + 6.1.2.1 Comment Command + 6.1.2.2 Simple Commands + 6.1.2.3 Graphics Commands + 6.1.2.4 Device Control Commands + 6.1.2.5 Obsolete Command + 6.1.3 Intermediate Output Examples + 6.1.4 Output Language Compatibility + 6.2 Device and Font Description Files + 6.2.1 'DESC' File Format + 6.2.2 Font Description File Format +Appendix A Copying This Manual +Appendix B Request Index +Appendix C Escape Sequence Index +Appendix D Operator Index +Appendix E Register Index +Appendix F Macro Index +Appendix G String Index +Appendix H File Keyword Index +Appendix I Program and File Index +Appendix J Concept Index +GNU 'troff' +*********** + +This manual documents GNU 'troff' version 1.23.0. + + Copyright © 1994-2023 Free Software Foundation, Inc. + + 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". + +1 Introduction +************** + +GNU 'roff' (or 'groff') is a programming system for typesetting +documents. It is highly flexible and has been used extensively for over +thirty years. + +1.1 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. + + 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 ... + 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 '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 'nroff' and 'troff'. Document preparation became a + widespread use of Unix, but no stand-alone word-processing system + was ever undertaken. + + A history relating 'groff' to its predecessors 'roff', 'nroff', and +'troff' is available in the 'roff(7)' man page. + +1.2 What Is 'groff'? +==================== + +'groff' (GNU '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 AT&T Unix, +'groff' is present on most 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. 'groff' is capable of producing typographically +sophisticated documents while consuming minimal system resources. + +1.3 'groff' Capabilities +======================== + +GNU '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. + + * text filling, breaking, alignment to the left or right margin; + centering + + * adjustment of inter-word space size to justify text, and of + inter-sentence space size to suit local style conventions + + * automatic and manual determination of hyphenation break points + + * pagination + + * selection of any font available to the output device + + * adjustment of type size and vertical spacing (or "leading") + + * configuration of line length and indentation amounts; columnation + + * drawing of geometric primitives (lines, arcs, polygons, circles, + ...) + + * setup of stroke and fill colors (where supported by the output + device) + + * embedding of hyperlinks, images, document metadata, and other + inclusions (where supported by the output device) + +1.4 Macro Packages +================== + +Elemental typesetting functions can be be challenging to use directly +with complex documents. A "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 +"macro package" for use by many. Several macro packages available; the +most widely used are provided with 'groff'. They are 'man', 'mdoc', +'me', 'mm', 'mom', and 'ms'. + +1.5 Preprocessors +================= + +An alternative approach to complexity management, particularly when +constructing tables, setting mathematics, or drawing diagrams, lies in +preprocessing. A "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 'troff' input. +Command-line options to 'groff' tell it which preprocessors to use. + + 'groff' provides preprocessors for laying out tables ('gtbl'), +typesetting equations ('geqn'), drawing diagrams ('gpic' and 'ggrn'), +inserting bibliographic references ('grefer'), and drawing chemical +structures ('gchem'). An associated program that is useful when dealing +with preprocessors is 'gsoelim'.(1) (*note Preprocessor +Intro-Footnote-1::) + + 'groff' also supports 'grap', a preprocessor for drawing graphs. A +free implementation of it can be obtained separately. + + Unique to 'groff' is the 'preconv' preprocessor that enables 'groff' +to handle documents in a variety of input encodings. + + Other preprocessors exist, but no free implementations are known. An +example is 'ideal', which draws diagrams using a mathematical constraint +language. + + (1) The 'g' prefix is not used on all systems; see *note Invoking +groff::. + +1.6 Output Devices +================== + +GNU 'troff''s output is in a device-independent page description +language, which is then read by an "output driver" that translates this +language into a file format or byte stream that a piece of (possibly +emulated) hardware understands. 'groff' features output drivers for +PostScript devices, terminal emulators (and other simple typewriter-like +machines), X11 (for previewing), TeX DVI, HP LaserJet 4/PCL5 and Canon +LBP printers (which use CaPSL), HTML, XHTML, and PDF. + +1.7 Installation +================ + +Locate installation instructions in the files 'INSTALL', +'INSTALL.extra', and 'INSTALL.REPO' in the 'groff' source distribution. +Being a GNU project, 'groff' supports the familiar './configure && make' +command sequence. + +1.8 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, 'groff' is an +extended dialect of the 'roff' language, for which many similar +implementations exist. + + The '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. + + -- Register: \n[example] + The register 'example' is one that that 'groff' _doesn't_ + predefine. You can create it yourself, though; see *note Setting + Registers::. + + 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" (=>) and error-> notations to present +output written to the standard output and standard error streams, +respectively. Diagnostic messages from the GNU '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.(1) (*note Conventions Used +in This Manual-Footnote-1::) + + $ echo "Twelve o'clock and" | groff -Tascii | sed '/^$/d' + => Twelve o'clock and + $ echo '.tm all is well.' | groff > /dev/null + error-> all is well. + + Sometimes we use => 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 'roff' language input that would be placed in a +text file. Occasionally, we start an example with a '$' character to +indicate a shell prompt, as seen above. + + You are encouraged to try the examples yourself, and to alter them to +better learn 'groff''s behavior. Our examples frequently need to direct +the formatter to set a line length (with '.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 'll' request formally.(2) (*note +Conventions Used in This Manual-Footnote-2::) + + (1) Unix and related operating systems distinguish standard output +and standard error streams _because_ of 'troff': +<https://minnie.tuhs.org/pipermail/tuhs/2013-December/006113.html>. + + (2) *Note Line Layout::. + +1.9 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 'me' macro package +(which we also provide, little altered from 4.4BSD). Larry Kollar +contributed much of the material on the 'ms' macro package. + +2 Invoking 'groff' +****************** + +This chapter focuses on how to invoke the 'groff' front end. This front +end takes care of the details of constructing the pipeline among the +preprocessors, 'gtroff' and the postprocessor. + + It has become a tradition that GNU programs get the prefix 'g' to +distinguish them from their original counterparts provided by the host +(*note Environment::). Thus, for example, 'geqn' is GNU 'eqn'. On +operating systems like GNU/Linux or the Hurd, which don't contain +proprietary versions of 'troff', and on MS-DOS/MS-Windows, where 'troff' +and associated programs are not available at all, this prefix is omitted +since GNU 'troff' is the only incarnation of 'troff' used. Exception: +'groff' is never replaced by 'roff'. + + In this document, we consequently say 'gtroff' when talking about the +GNU 'troff' program. All other implementations of 'troff' are called +AT&T 'troff', which is the common origin of almost all 'troff' +implementations(1) (*note Invoking groff-Footnote-1::) (with more or +less compatible changes). Similarly, we say 'gpic', 'geqn', and so on. + + (1) Besides 'groff', 'neatroff' is an exception. + +2.1 Options +=========== + +'groff' normally runs the 'gtroff' program and a postprocessor +appropriate for the selected device. The default device is 'ps' (but it +can be changed when 'groff' is configured and built). It can optionally +preprocess with any of 'gpic', 'geqn', 'gtbl', 'ggrn', 'grap', 'gchem', +'grefer', 'gsoelim', or 'preconv'. + + This section documents only options to the 'groff' front end. Many +of the arguments to 'groff' are passed on to 'gtroff'; therefore, those +are also included. Arguments to preprocessors and output drivers can be +found in the man pages 'gpic(1)', 'geqn(1)', 'gtbl(1)', 'ggrn(1)', +'grefer(1)', 'gchem(1)', 'gsoelim(1)', 'preconv(1)', 'grotty(1)', +'grops(1)', 'gropdf(1)', 'grohtml(1)', 'grodvi(1)', 'grolj4(1)', +'grolbp(1)', and 'gxditview(1)'. + + The command-line format for 'groff' is: + + groff [ -abceghijklpstvzCEGNRSUVXZ ] [ -dCS ] [ -DARG ] + [ -fFAM ] [ -FDIR ] [ -IDIR ] [ -KARG ] + [ -LARG ] [ -mNAME ] [ -MDIR ] [ -nNUM ] + [ -oLIST ] [ -PARG ] [ -rCN ] [ -TDEV ] + [ -wNAME ] [ -WNAME ] [ FILES... ] + + The command-line format for 'gtroff' is as follows. + + gtroff [ -abcivzCERU ] [ -dCS ] [ -fFAM ] [ -FDIR ] + [ -mNAME ] [ -MDIR ] [ -nNUM ] [ -oLIST ] + [ -rCN ] [ -TNAME ] [ -wNAME ] [ -WNAME ] + [ FILES... ] + +Obviously, many of the options to 'groff' are actually passed on to +'gtroff'. + + Options without an argument can be grouped behind a single '-'. A +filename of '-' denotes the standard input. Whitespace is permitted +between an option and its argument. + + The 'grog' command can be used to guess the correct 'groff' command +to format a file. See its man page 'grog(1)'; type 'man grog' at the +command line to view it. + + 'groff''s command-line options are as follows. + +'-a' + Generate a plain text approximation of the typeset output. The + read-only register '.A' is set to 1. *Note Built-in Registers::. + This option produces a sort of abstract preview of the formatted + output. + + * Page breaks are marked by a phrase in angle brackets; for + example, '<beginning of page>'. + + * Lines are broken where they would be in the formatted output. + + * 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 + 'ss' request) are not represented. + + * Vertical motions are not represented. + + * Special characters are rendered in angle brackets; for + example, the default soft hyphen character appears as '<hy>'. + + The above description should not be considered a specification; the + details of '-a' output are subject to change. + +'-b' + Write a backtrace reporting the state of '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 + 'gtroff''s idea of line numbers can be confused by requests that + append to macros. + +'-c' + Start with color output disabled. + +'-C' + Enable AT&T 'troff' compatibility mode; implies '-c'. *Note + Implementation Differences::, for the list of incompatibilities + between 'groff' and AT&T 'troff'. + +'-dCTEXT' +'-dSTRING=TEXT' + Define 'roff' string C or STRING as T or TEXT. C must be one + character; STRING can be of arbitrary length. Such string + assignments happen before any macro file is loaded, including the + startup file. Due to 'getopt_long' limitations, C cannot be, and + STRING cannot contain, an equals sign, even though that is a valid + character in a 'roff' identifier. + +'-DENC' + Set fallback input encoding used by 'preconv' to ENC; implies '-k'. + +'-e' + Run 'geqn' preprocessor. + +'-E' + Inhibit 'gtroff' error messages. This option does _not_ suppress + messages sent to the standard error stream by documents or macro + packages using 'tm' or related requests. + +'-fFAM' + Use FAM as the default font family. *Note Font Families::. + +'-FDIR' + Search in directory 'DIR' for the selected output device's + directory of device and font description files. See the + description of 'GROFF_FONT_PATH' in *note Environment:: below for + the default search locations and ordering. + +'-g' + Run 'ggrn' preprocessor. + +'-G' + Run 'grap' preprocessor; implies '-p'. + +'-h' + Display a usage message and exit. + +'-i' + Read the standard input after all the named input files have been + processed. + +'-IDIR' + Search the directory DIR for files named in several contexts; + implies '-g' and '-s'. + + * 'gsoelim' replaces 'so' requests with the contents of their + file name arguments. + + * 'gtroff' searches for files named as operands in its command + line and as arguments to 'psbb', 'so', and 'soquiet' requests. + + * Output drivers may search for files; for instance, 'grops' + looks for files named in '\X'ps: import ...'', '\X'ps: file + ...'', and '\X'pdf: pdfpic ...'' device control escape + sequences. + + 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 '-I .' at the desired place. The + current working directory is otherwise searched last. '-I' works + similarly to, and is named for, the "include" option of Unix C + compilers. + + '-I' options are passed to 'gsoelim', 'gtroff', and output drivers; + with the flag letter changed to '-M', they are also passed to + 'ggrn'. + +'-j' + Run 'gchem' preprocessor. Implies '-p'. + +'-k' + Run 'preconv' preprocessor. Refer to its man page for its behavior + if neither of 'groff''s '-K' or '-D' options is also specified. + +'-KENC' + Set input encoding used by 'preconv' to ENC; implies '-k'. + +'-l' + Send the output to a spooler for printing. The 'print' directive + in the device description file specifies the default command to be + used; see *note Device and Font Description Files::. See options + '-L' and '-X'. + +'-LARG' + Pass ARG to the print spooler program. If multiple ARGs are + required, pass each with a separate '-L' option. 'groff' does not + prefix an option dash to ARG before passing it to the spooler + program. + +'-mNAME' + Process the file 'NAME.tmac' prior to any input files. If not + found, 'tmac.NAME' is attempted. NAME (in both arrangements) is + presumed to be a macro file; see the description of + 'GROFF_TMAC_PATH' in *note Environment:: below for the default + search locations and ordering. This option and its argument are + also passed to 'geqn', 'grap', and 'ggrn'. + +'-MDIR' + Search directory 'DIR' for macro files; see the description of + 'GROFF_TMAC_PATH' in *note Environment:: below for the default + search locations and ordering. This option and its argument are + also passed to 'geqn', 'grap', and 'ggrn'. + +'-nNUM' + Number the first page NUM. + +'-N' + Prohibit newlines between 'eqn' delimiters: pass '-N' to 'geqn'. + +'-oLIST' + Output only pages in LIST, which is a comma-separated list of page + ranges; 'N' means page N, 'M-N' means every page between M and N, + '-N' means every page up to N, 'N-' means every page from N on. + 'gtroff' stops processing and exits after formatting the last page + enumerated in LIST. + +'-p' + Run 'gpic' preprocessor. + +'-PARG' + Pass ARG to the postprocessor. If multiple ARGs are required, pass + each with a separate '-P' option. 'groff' does not prefix an + option dash to ARG before passing it to the postprocessor. + +'-rCNUMERIC-EXPRESSION' +'-rREGISTER=EXPR' + Set 'roff' register C or REGISTER to the value NUMERIC-EXPRESSION + (*note Numeric Expressions::). C must be one character; REGISTER + can be of arbitrary length. Such register assignments happen + before any macro file is loaded, including the startup file. Due + to 'getopt_long' limitations, C cannot be, and REGISTER cannot + contain, an equals sign, even though that is a valid character in a + 'roff' identifier. + +'-R' + Run 'grefer' preprocessor. No mechanism is provided for passing + arguments to 'grefer' because most 'grefer' options have equivalent + language elements that can be specified within the document. + + 'gtroff' also accepts a '-R' option, which is not accessible via + 'groff'. This option prevents the loading of the 'troffrc' and + 'troffrc-end' files. + +'-s' + Run 'gsoelim' preprocessor. + +'-S' + Operate in "safer" mode; see '-U' below for its opposite. For + security reasons, safer mode is enabled by default. + +'-t' + Run 'gtbl' preprocessor. + +'-TDEV' + Direct 'gtroff' to format the input for the output device DEV. + 'groff' then calls an output driver to convert 'gtroff''s output to + a form appropriate for DEV. The following output devices are + available. + + 'ps' + For PostScript printers and previewers. + + 'pdf' + For PDF viewers or printers. + + 'dvi' + For TeX DVI format. + + 'X75' + For a 75dpi X11 previewer. + + 'X75-12' + For a 75dpi X11 previewer with a 12-point base font in the + document. + + 'X100' + For a 100dpi X11 previewer. + + 'X100-12' + For a 100dpi X11 previewer with a 12-point base font in the + document. + + 'ascii' + For typewriter-like devices using the (7-bit) ASCII (ISO 646) + character set. + + 'latin1' + For typewriter-like devices that support the Latin-1 + (ISO 8859-1) character set. + + 'utf8' + For typewriter-like devices that use the Unicode (ISO 10646) + character set with UTF-8 encoding. + + 'cp1047' + For typewriter-like devices that use the EBCDIC encoding IBM + code page 1047. + + 'lj4' + For HP LaserJet4-compatible (or other PCL5-compatible) + printers. + + 'lbp' + For Canon CaPSL printers (LBP-4 and LBP-8 series laser + printers). + + 'html' + 'xhtml' + To produce HTML and XHTML output, respectively. This driver + consists of two parts, a preprocessor ('pre-grohtml') and a + postprocessor ('post-grohtml'). + + The predefined GNU 'troff' string '.T' contains the name of the + output device; the read-only register '.T' is set to 1 if this + option is used (which is always true if 'groff' is used to call GNU + 'troff'). *Note Built-in Registers::. + + The postprocessor to be used for a device is specified by the + 'postpro' command in the device description file. (*Note Device + and Font Description Files::.) This can be overridden with the + '-X' option. + +'-U' + Operate in "unsafe mode", which enables the 'open', 'opena', 'pi', + 'pso', and '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 '-m' option above. '-U' is passed to 'gpic' and 'gtroff'. + +'-v' + Write version information for '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 '-v' to the formatter and any + pre- or postprocessors invoked. + +'-V' + Output the pipeline that would be run by '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. + +'-wCATEGORY' + Enable warnings in CATEGORY. Categories are listed in *note + Warnings::. + +'-WCATEGORY' + Inhibit warnings in CATEGORY. Categories are listed in *note + Warnings::. + +'-X' + Use 'gxditview' instead of the usual postprocessor to (pre)view a + document on an X11 display. Combining this option with '-Tps' uses + the font metrics of the PostScript device, whereas the '-TX75' and + '-TX100' options use the metrics of X11 fonts. + +'-z' + Suppress formatted output from 'gtroff'. + +'-Z' + Disable postprocessing. 'gtroff' output will appear on the + standard output stream (unless suppressed with '-z'; see *note + gtroff Output:: for a description of this format. + +2.2 Environment +=============== + +There are also several environment variables (of the operating system, +not within 'gtroff') that can modify the behavior of 'groff'. + +'GROFF_BIN_PATH' + This search path, followed by 'PATH', is used for commands executed + by 'groff'. + +'GROFF_COMMAND_PREFIX' + If this is set to X, then 'groff' runs 'Xtroff' instead of + 'gtroff'. This also applies to 'tbl', 'pic', 'eqn', 'grn', 'chem', + 'refer', and 'soelim'. It does not apply to 'grops', 'grodvi', + 'grotty', 'pre-grohtml', 'post-grohtml', 'preconv', 'grolj4', + 'gropdf', and 'gxditview'. + + The default command prefix is determined during the installation + process. If a non-GNU 'troff' system is found, prefix 'g' is used, + none otherwise. + +'GROFF_ENCODING' + The value of this variable is passed to the 'preconv' + preprocessor's '-e' option to select the character encoding of + input files. This variable's existence implies the 'groff' option + '-k'. If set but empty, 'groff' calls 'preconv' without an '-e' + option. 'groff''s '-K' option overrides 'GROFF_ENCODING'. See the + 'preconv(7)' man page; type 'man preconv' at the command line to + view it. + +'GROFF_FONT_PATH' + A list of directories in which to seek the selected output device's + directory of device and font description files. GNU 'troff' will + search directories given as arguments to any specified '-F' options + before these, and a built-in list of directories after them. *Note + Font Directories:: and the 'troff(1)' or 'gtroff(1)' man pages. + +'GROFF_TMAC_PATH' + A list of directories in which to seek macro files. GNU 'troff' + will search directories given as arguments to any specified '-M' + options before these, and a built-in list of directories after + them. *Note Macro Directories:: and the 'troff(1)' or 'gtroff(1)' + man pages. + +'GROFF_TMPDIR' + The directory in which 'groff' creates temporary files. If this is + not set and '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 '/tmp'). 'grops', 'grefer', 'pre-grohtml', and + 'post-grohtml' can create temporary files in this directory. + +'GROFF_TYPESETTER' + Sets the default output device. If empty or not set, a build-time + default (often 'ps') is used. The '-TDEV' option overrides + 'GROFF_TYPESETTER'. + +'SOURCE_DATE_EPOCH' + 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 'localtime(3)' when + the formatter starts up and stored in registers usable by documents + and macro packages (*note Built-in Registers::). + +'TZ' + The time zone to use when converting the current time (or value of + 'SOURCE_DATE_EPOCH') to human-readable form; see 'tzset(3)'. + + MS-DOS and MS-Windows ports of 'groff' use semicolons, rather than +colons, to separate the directories in the lists described above. + +2.3 Macro Directories +===================== + +A macro file must have a name in the form 'NAME.tmac' or 'tmac.NAME' and +be placed in a "tmac directory" to be found by the '-mNAME' command-line +option.(1) (*note Macro Directories-Footnote-1::) Together, these +directories constitute the "tmac path". Each directory is searched in +the following order until the desired macro file is found or the list is +exhausted. + + * Directories specified with GNU 'troff''s or 'groff''s '-M' + command-line option. + + * Directories listed in the 'GROFF_TMAC_PATH' environment variable. + + * The current working directory (only if in unsafe mode using the + '-U' command-line option). + + * The user's home directory, 'HOME'. + + * A platform-dependent directory, a site-local (platform-independent) + directory, and the main tmac directory. The locations + corresponding to your installation are listed in section + "Environment" of 'gtroff(1)'. If not otherwise configured, they + are as follows. + + /usr/local/lib/groff/site-tmac + /usr/local/share/groff/site-tmac + /usr/local/share/groff/1.23.0/tmac + + The foregoing assumes that the version of 'groff' is 1.23.0, and + that the installation prefix was '/usr/local'. It is possible to + fine-tune these locations during the source configuration process. + + (1) The 'mso' request does not have these limitations. *Note I/O::. + +2.4 Font Directories +==================== + +'groff' enforces few restrictions on how font description files are +named. For its family/style mechanism to work (*note 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 'T' for the +family name and 'R', 'B', 'I', and 'BI' to indicate the styles 'roman', +'bold', 'italic', and 'bold italic', respectively. Thus the final font +names are 'TR', 'TB', 'TI', and 'TBI'. + + Font description files are kept in "font directories", which together +constitute the "font path". The search procedure always appends the +directory 'dev'NAME, where NAME is the name of the output device. +Assuming TeX DVI output, and '/foo/bar' as a font directory, the font +description files for 'grodvi' must be in '/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. + + * Directories specified with GNU 'troff''s or 'groff''s '-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. + + * Directories listed in the 'GROFF_FONT_PATH' environment variable. + + * A site-local directory and the main font description directory. + The locations corresponding to your installation are listed in + section "Environment" of 'gtroff(1)'. If not otherwise configured, + they are as follows. + + /usr/local/share/groff/site-font + /usr/local/share/groff/1.23.0/font + + The foregoing assumes that the version of 'groff' is 1.23.0, and + that the installation prefix was '/usr/local'. It is possible to + fine-tune these locations during the source configuration process. + +2.5 Paper Format +================ + +In 'groff', the page dimensions for the formatter GNU 'troff' and for +output devices are handled separately. *Note Page Layout::, for +vertical manipulation of the page size, and *Note Line Layout::, for +horizontal changes. The 'papersize' macro package, normally loaded by +'troffrc' at startup, provides an interface for configuring page +dimensions by convenient names, like 'letter' or 'a4'; see +'groff_tmac(5)'. The default used by the formatter depends on its build +configuration, but is usually one of the foregoing, as geographically +appropriate. + + 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 'DESC' file. Most output drivers also recognize a command-line +option '-p' to override the default dimensions and an option '-l' to use +landscape orientation. *Note DESC File Format::, for a description of +the 'papersize' keyword, which takes an argument of the same form as +'-p'. The output driver's man page, such as 'grops(1)', may also be +helpful. + + 'groff' uses the command-line option '-P' to pass options to +postprocessors; for example, use the following for PostScript output on +A4 paper in landscape orientation. + + groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps + +2.6 Invocation Examples +======================= + +'roff' systems are best known for formatting man pages. Once a 'man' +librarian program has located a man page, it may execute a 'groff' +command much like the following. + + groff -t -man -Tutf8 /usr/share/man/man1/groff.1 + + The librarian will also pipe the output through a pager, which might +not interpret the SGR terminal escape sequences 'groff' emits for +boldface, underlining, or italics; see the 'grotty(1)' man page for a +discussion. + + To process a 'roff' input file using the preprocessors 'gtbl' and +'gpic' and the 'me' macro package in the way to which AT&T 'troff' users +were accustomed, one would type (or script) a pipeline. + + gpic foo.me | gtbl | gtroff -me -Tutf8 | grotty + + Using 'groff', this pipe can be shortened to an equivalent command. + + groff -p -t -me -T utf8 foo.me + + An even easier way to do this is to use 'grog' to guess the +preprocessor and macro options and execute the result by using the +command substitution feature of the shell. + + $(grog -Tutf8 foo.me) + + Each command-line option to a postprocessor must be specified with +any required leading dashes '-' because 'groff' passes the arguments +as-is to the postprocessor; this permits arbitrary arguments to be +transmitted. For example, to pass a title to the 'gxditview' +postprocessor, the shell commands + + groff -X -P -title -P 'trial run' mydoc.t + +and + + groff -X -Z mydoc.t | gxditview -title 'trial run' - + +are equivalent. + +3 Tutorial for Macro Users +************************** + +Most users of the '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 *note GNU troff +Reference:: instead. + +3.1 Basics +========== + +Let us first survey some basic concepts necessary to use a macro package +fruitfully.(1) (*note Basics-Footnote-1::) References are made +throughout to more detailed information. + + GNU '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 +(requests and escape sequences), which tell GNU 'troff' how to format +the output. *Note Formatter Instructions::. + + The word 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 + + .sp + +spaces one line, but + + .sp 4 + +spaces four lines. The number 4 is an argument to the 'sp' request, +which says to space four lines instead of one. Arguments are separated +from the request and from each other by spaces (_not_ tabs). *Note +Invoking Requests::. + + The primary function of GNU '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: + + Now is the time + for all good men + to come to the aid + of their party. + Four score and seven + years ago, etc. + +is read, packed onto output lines, and justified to produce: + + => Now is the time for all good men to come to the aid of + => their party. Four score and seven years ago, etc. + + 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 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 text lines--words to be formatted. Some are +control lines that tell a macro package (or GNU 'troff' directly) how to +format the text. Control lines start with a dot ('.') or an apostrophe +(''') as the first character, and can be followed by a 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 'troff'. + + * First, keep the input lines short. Short input lines are easier to + edit, and GNU 'troff' packs words onto longer lines anyhow. + + * 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. + + * End each sentence with two spaces--or better, start each sentence + on a new line. GNU 'troff' recognizes characters that usually end + a sentence, and inserts inter-sentence space accordingly. + + * Do not hyphenate words at the end of lines--GNU '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 "mother- in-law". + + We offer further advice in *note Input Conventions::. + + GNU 'troff' permits alteration of the distance between lines of text. +This is termed 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 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 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, 'man' and 'mdoc', +don't encourage explicit use of these requests at all. + + The request '.sp N' leaves N lines of blank space. N can be omitted +(skipping a single line) or can be of the form Ni (for N inches) or Nc +(for N centimeters). For example, the input: + + .sp 1.5i + My thoughts on the subject + .sp + +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 *note Measurements::). + + If you seek precision in spacing, be advised when using a macro +package that it might not honor 'sp' requests as you expect; it can use +a formatter feature called 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. *Note +Manipulating Spacing::. + + Text lines can be centered by using the 'ce' request. The line after +'ce' is centered (horizontally) on the page. To center more than one +line, use '.ce N' (where N is the number of lines to center), followed +by the N lines. To center many lines without counting them, type: + + .ce 1000 + lines to center + .ce 0 + +The '.ce 0' request tells GNU 'troff' to center zero more lines, in +other words, stop centering. + + GNU 'troff' also offers the 'rj' request for right-aligning text. It +works analogously to 'ce' and is convenient for setting epigraphs. + + The 'bp' request starts a new page; this necessarily implies an +ordinary (line) break. + + 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 +'br'. If you invoke them with the apostrophe ''', the no-break control +character, the (initial) break they normally perform is suppressed. +''br' does nothing. + + (1) The remainder of this chapter is based on 'Writing Papers with +nroff using -me' by Eric P. Allman, which is distributed with 'groff' as +'meintro.me'. + +3.2 Common Features +=================== + +GNU '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 macros, which are then collected into a +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 +'groff_tmac(5)' man page. Type '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 'ms', see *note ms::. + +3.2.1 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. + + => Some men look at constitutions with sanctimonious + => reverence, and deem them like the ark of the + => covenant, too sacred to be touched. + +We also frequently encounter tagged paragraphs, which begin with a tag +or label at the left margin and indent the remaining text. + + => one This is the first paragraph. Notice how the + => first line of the resulting paragraph lines + => up with the other lines in the paragraph. + +If the tag is too wide for the indentation, the line is broken. + + => longlabel + => The label does not align with the subsequent + => lines, but they align with each other. + +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. + + => o This list item starts with a bullet. When + => producing output for a device using the ASCII + => character set, an 'o' is formatted instead. + +Often, use of the same macro without a tag continues such a discussion. + + => -xyz This option is recognized but ignored. + => + => It had a security hole that we don't discuss. + +3.2.2 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. + +3.2.3 Headers and Footers +------------------------- + +Headers and 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 titles, and comprise three +parts: left-aligned, centered, and right-aligned. A '%' character +appearing anywhere in a title is automatically replaced by the page +number. *Note Page Layout::. + +3.2.4 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 page offset, +indentation, and line length. *Note Line Layout::. Commonly, packages +support registers to tune these values. + +3.2.5 Displays and Keeps +------------------------ + +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. + + A 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. + + 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 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. + +3.2.6 Footnotes and Endnotes +---------------------------- + +Footnotes and endnotes are forms of delayed formatting. They are +recorded at their points of relevance in the input, but not formatted +there. Instead, a 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. + +3.2.7 Table of Contents +----------------------- + +A package may handle a 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 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 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 'troff' +document because the formatter processes the document in a single pass. +The 'gropdf' output driver supports a PDF feature that relocates pages +at the time the document is rendered; see the 'gropdf(1)' man page. +Type 'man gropdf' at the command line to view it. + +3.2.8 Indexing +-------------- + +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 'makeindex' +program are necessary. + +3.2.9 Document Formats +---------------------- + +Some macro packages supply stock configurations of certain documents, +like business letters and memoranda. These often also have provision +for a 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. + +3.2.10 Columnation +------------------ + +Macro packages apart from 'man' and 'mdoc' for man page formatting offer +a facility for setting multiple columns on the page. + +3.2.11 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. *Note Italic Corrections::. + +3.2.12 Predefined Text +---------------------- + +Most macro packages supply predefined strings to set prepared text like +the date, or to perform operations like super- and subscripting. + +3.2.13 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 'TS' and 'TE' for 'gtbl', 'EQ' and 'EN' for +'geqn', and 'PS' and 'PE' for 'gpic'. + +3.2.14 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. + +4 Macro Packages +**************** + +This chapter surveys the "major" macro packages that come with 'groff'. +One, 'ms', is presented in detail. + + Major macro packages are also sometimes described as "full-service" +due to the breadth of features they provide and because more than one +cannot be used by the same document; for example + + groff -m man foo.man -m ms bar.doc + +doesn't work. Option arguments are processed before non-option +arguments; the above (failing) sample is thus reordered to + + groff -m man -m ms foo.man bar.doc + + 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 'groff_tmac(5)' man +page for a list. Type 'man groff_tmac' at the command line to view it. + +4.1 'man' +========= + +The 'man' macro package is the most widely used and probably the most +important ever developed for 'troff'. It is easy to use, and a vast +majority of manual pages ("man pages") are written in it. + + 'groff''s implementation is documented in the 'groff_man(7)' man +page. Type 'man groff_man' at the command line to view it. + +4.1.1 Optional 'man' extensions +------------------------------- + +Use the file 'man.local' for local extensions to the 'man' macros or for +style changes. + +Custom headers and footers +.......................... + +In 'groff' versions 1.18.2 and later, you can specify custom headers and +footers by redefining the following macros in 'man.local'. + + -- Macro: .PT + 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 'TH' in the center. + + -- Macro: .BT + Control the content of the footers. Normally, the footer prints + the page number and the third and fourth arguments to 'TH'. + + Use the 'FT' register to specify the footer position. The default + is -0.5i. + +Ultrix-specific man macros +.......................... + +The 'groff' source distribution includes a file named 'man.ultrix', +containing macros compatible with the Ultrix variant of 'man'. Copy +this file into 'man.local' (or use the 'mso' request to load it) to +enable the following macros. + + -- Macro: .CT key + Print '<CTRL/KEY>'. + + -- Macro: .CW + Print subsequent text using a "constant-width" (monospaced) + typeface (Courier roman). + + -- Macro: .Ds + Begin a non-filled display. + + -- Macro: .De + End a non-filled display started with 'Ds'. + + -- Macro: .EX [indent] + Begin a non-filled display using a monospaced typeface (Courier + roman). Use the optional INDENT argument to indent the display. + + -- Macro: .EE + End a non-filled display started with 'EX'. + + -- Macro: .G [text] + Set 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. + + -- Macro: .GL [text] + Set 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. + + -- Macro: .HB [text] + Set TEXT in Helvetica bold. If no text is present on the line + where the macro is called, then all text up to the next 'HB' + appears in Helvetica bold. + + -- Macro: .TB [text] + Identical to 'HB'. + + -- Macro: .MS title sect [punct] + Set a man page reference in Ultrix format. The TITLE is in Courier + instead of italic. Optional punctuation follows the section number + without an intervening space. + + -- Macro: .NT [C] [title] + Begin a note. Print the optional 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 'C', the body of the note is printed centered (the second + argument replaces the word "Note" if specified). + + -- Macro: .NE + End a note begun with 'NT'. + + -- Macro: .PN path [punct] + Set the path name in a monospaced typeface (Courier roman), + followed by optional punctuation. + + -- Macro: .Pn [punct] path [punct] + If called with two arguments, identical to '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. + + -- Macro: .R + Switch to roman font and turn off any underlining in effect. + + -- Macro: .RN + Print the string '<RETURN>'. + + -- Macro: .VS [4] + Start printing a change bar in the margin if the number '4' is + specified. Otherwise, this macro does nothing. + + -- Macro: .VE + End printing the change bar begun by 'VS'. + +Simple example +.............. + +The following example 'man.local' file alters the 'SH' macro to add some +extra vertical space before printing the heading. Headings are printed +in Helvetica bold. + + .\" 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 \\$* + .. + +4.2 'mdoc' +========== + +'groff''s implementation of the BSD 'doc' package for man pages is +documented in the 'groff_mdoc(7)' man page. Type 'man groff_mdoc' at +the command line to view it. + +4.3 'me' +======== + +'groff''s implementation of the BSD 'me' macro package is documented +using itself. A tutorial, 'meintro.me', and reference, 'meref.me', are +available in 'groff''s documentation directory. A 'groff_me(7)' man +page is also available and identifies the installation path for these +documents. Type 'man groff_me' at the command line to view it. + + A French translation of the tutorial is available as 'meintro_fr.me' +and installed parallel to the English version. + +4.4 'mm' +======== + +'groff''s implementation of the AT&T memorandum macro package is +documented in the 'groff_mm(7)' man page. Type 'man groff_mm' at the +command line) to view it. + + A Swedish localization of 'mm' is also available; see +'groff_mmse(7)'. + +4.5 'mom' +========= + +The main documentation files for the 'mom' macros are in HTML format. +Additional, useful documentation is in PDF format. See the 'groff(1)' +man page, section "Installation Directories", for their location. + + * 'toc.html' Entry point to the full mom manual. + + * 'macrolist.html' Hyperlinked index of macros with brief + descriptions, arranged by category. + + * 'mom-pdf.pdf' PDF features and usage. + + The mom macros are in active development between 'groff' releases. +The most recent version, along with up-to-date documentation, is +available at <http://www.schaffter.ca/mom/mom-05.html>. + + The 'groff_mom(7)' man page (type 'man groff_mom' at the command +line) contains a partial list of available macros, however their usage +is best understood by consulting the HTML documentation. + +4.6 'ms' +======== + +The 'ms' ("manuscript") package is suitable for the preparation of +letters, memoranda, reports, and books. These '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. 'ms' supports the 'tbl', +'eqn', 'pic', and '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 7 'ms'. Many extensions +from 4.2BSD (Berkeley) and Tenth Edition Research Unix have been +recreated. + +4.6.1 Introduction +------------------ + +The 'ms' macros are the oldest surviving package for 'roff' systems.(1) +(*note ms Introduction-Footnote-1::) While the 'man' package was +designed for brief reference documents, the 'ms' macros are also +suitable for longer works intended for printing and possible +publication. + + (1) While manual _pages_ are older, early ones used macros supplanted +by the 'man' package of Seventh Edition Unix (1979). 'ms' shipped with +Sixth Edition (1975) and was documented by Mike Lesk in a Bell Labs +internal memorandum. + +4.6.1.1 Basic information +......................... + +'ms' documents are plain text files; prepare them with your preferred +text editor. If you're in a hurry to start, know that 'ms' needs one of +its macros called at the beginning of a document so that it can +initialize. A "macro" is a formatting instruction to 'ms'. Put a macro +call on a line by itself. Use '.PP' if you want your paragraph's first +line to be indented, or '.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 (*note ms::), return to this part of the +manual. + + Format the document with the 'groff' command. 'nroff' can be useful +for previewing. + + $ 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 + + Our 'radical.ms' document might look like this. + + .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. + + ->That's what Dijkstra said, anyway. + + 'ms' exposes many aspects of document layout to user control via +'groff''s "registers" and "strings", which store numbers and text, +respectively. Measurements in 'groff' are expressed with a suffix +called a "scaling unit". + +'i' + inches + +'c' + centimeters + +'p' + points (1/72 inch) + +'P' + picas (1/6 inch) + +'v' + vees; current vertical spacing + +'m' + ems; width of an "M" in the current font + +'n' + ens; one-half em + + Set registers with the 'nr' request and strings with the 'ds' +request. "Requests" are like macro calls; they go on lines by +themselves and start with the "control character", a dot ('.'). 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. + + .nr PS 10.5p \" Use 10.5-point type. + .ds FAM P \" Use Palatino font family. + +In the foregoing, we see that '\"' begins a comment. This is an example +of an "escape sequence", the other kind of formatting instruction. +Escape sequences can appear anywhere. They begin with the escape +character ('\') and are followed by at least one more character. 'ms' +documents tend to use only a few of 'groff''s many requests and escape +sequences; see *note Request Index:: and *note Escape Sequence Index:: +or the 'groff(7)' man page for complete lists. + +'\"' + Begin comment; ignore remainder of line. + +'\n[REG]' + Interpolate value of register REG. + +'\*[STR]' + Interpolate contents of string STR. + +'\*S' + abbreviation of '\*[S]'; the name S must be only one character + +'\[CHAR]' + Interpolate glyph of special character named CHAR. + +'\&' + dummy character + +'\~' + Insert an unbreakable space that is adjustable like a normal space. + +'\|' + Move horizontally by one-sixth em ("thin space"). + + Prefix any words that start with a dot '.' or neutral apostrophe ''' +with '\&' 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 '.', '?', and '!' with '\&' when needed to +cancel end-of-sentence detection. + + My exposure was \&.5 to \&.6 Sv of neutrons, said Dr.\& + Wallace after the criticality incident. + +4.6.2 Document Structure +------------------------ + +The '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. + +*Document type* + Calling the 'RP' macro at the beginning of your document puts the + document description (see below) on a cover page. Otherwise, 'ms' + places the information (if any) on the first page, followed + immediately by the body text. Some document types found in other + 'ms' implementations are specific to AT&T or Berkeley, and are not + supported by 'groff' 'ms'. + +*Format and layout* + By setting registers and strings, you can configure your document's + typeface, margins, spacing, headers and footers, and footnote + arrangement. *Note ms Document Control Settings::. + +*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. *Note ms Document Description Macros::. + +*Body text* + The main matter of your document follows its description (if any). + '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. *Note ms Body Text::. + +*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 '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 '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. + +4.6.3 Document Control Settings +------------------------------- + +'ms' exposes many aspects of document layout to user control via 'groff' +requests. To use them, you must understand how to define registers and +strings. + + -- Request: .nr reg value + Set register REG to VALUE. If REG doesn't exist, GNU 'troff' + creates it. + + -- Request: .ds name contents + Set string NAME to CONTENTS. + + A list of document control registers and strings follows. For any +parameter whose default is unsatisfactory, define its register or string +before calling any 'ms' macro other than 'RP'. + +Margin settings +............... + + -- Register: \n[PO] + Defines the page offset (i.e., the left margin). + + Effective: next page. + + Default: Varies by output device and paper format; 1i is used for + typesetters using U.S. letter paper, and zero for terminals. *Note + Paper Format::. + + -- Register: \n[LL] + Defines the line length (i.e., the width of the body text). + + Effective: next paragraph. + + Default: Varies by output device and paper format; 6.5i is used for + typesetters using U.S. letter paper (*note Paper Format::) and 65n + on terminals. + + -- Register: \n[LT] + Defines the title line length (i.e., the header and footer width). + This is usually the same as 'LL', but need not be. + + Effective: next paragraph. + + Default: Varies by output device and paper format; 6.5i is used for + typesetters using U.S. letter paper (*note Paper Format::) and 65n + on terminals. + + -- Register: \n[HM] + Defines the header margin height at the top of the page. + + Effective: next page. + + Default: 1i. + + -- Register: \n[FM] + Defines the footer margin height at the bottom of the page. + + Effective: next page. + + Default: 1i. + +Titles (headers, footers) +......................... + + -- String: \*[LH] + Defines the text displayed in the left header position. + + Effective: next header. + + Default: empty. + + -- String: \*[CH] + Defines the text displayed in the center header position. + + Effective: next header. + + Default: '-\n[%]-'. + + -- String: \*[RH] + Defines the text displayed in the right header position. + + Effective: next header. + + Default: empty. + + -- String: \*[LF] + Defines the text displayed in the left footer position. + + Effective: next footer. + + Default: empty. + + -- String: \*[CF] + Defines the text displayed in the center footer position. + + Effective: next footer. + + Default: empty. + + -- String: \*[RF] + Defines the text displayed in the right footer position. + + Effective: next footer. + + Default: empty. + +Text settings +............. + + -- Register: \n[PS] + Defines the type size of the body text. + + Effective: next paragraph. + + Default: 10p. + + -- Register: \n[VS] + Defines the vertical spacing (type size plus leading). + + Effective: next paragraph. + + Default: 12p. + + -- Register: \n[HY] + Defines the automatic hyphenation mode used with the 'hy' request. + Setting 'HY' to 0 is equivalent to using the 'nh' request. This is + a Tenth Edition Research Unix extension. + + Effective: next paragraph. + + Default: 6. + + -- String: \*[FAM] + Defines the font family used to typeset the document. This is a + GNU extension. + + Effective: next paragraph. + + Default: defined by the output device; often 'T' (*note ms Body + Text::) + +Paragraph settings +.................. + + -- Register: \n[PI] + Defines the indentation amount used by the 'PP', 'IP' (unless + overridden by an optional argument), 'XP', and 'RS' macros. + + Effective: next paragraph. + + Default: 5n. + + -- Register: \n[PD] + Defines the space between paragraphs. + + Effective: next paragraph. + + Default: 0.3v (1v on low-resolution devices). + + -- Register: \n[QI] + Defines the indentation amount used on both sides of a paragraph + set with the 'QP' or between the 'QS' and 'QE' macros. + + Effective: next paragraph. + + Default: 5n. + + -- Register: \n[PORPHANS] + 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 '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. + +Heading settings +................ + + -- Register: \n[PSINCR] + Defines an increment in type size to be applied to a heading at a + lesser depth than that specified in 'GROWPS'. The value of + 'PSINCR' should be specified in points with the p scaling unit and + may include a fractional component; for example, '.nr PSINCR 1.5p' + sets a type size increment of 1.5p. This is a GNU extension. + + Effective: next heading. + + Default: 1p. + + -- Register: \n[GROWPS] + Defines the heading depth above which the type size increment set + by 'PSINCR' becomes effective. For each heading depth less than + the value of 'GROWPS', the type size is increased by 'PSINCR'. + Setting 'GROWPS' to any value less than 2 disables the incremental + heading size feature. This is a GNU extension. + + Effective: next heading. + + Default: 0. + + -- Register: \n[HORPHANS] + Defines the minimum number of lines of an immediately succeeding + paragraph that should be kept together with any heading introduced + by the 'NH' or '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 '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. + + -- String: \*[SN-STYLE] + Defines the style used to print numbered headings. *Note Headings + in ms::. This is a GNU extension. + + Effective: next heading. + + Default: alias of 'SN-DOT' + +Footnote settings +................. + + -- Register: \n[FI] + Defines the footnote indentation. This is a Berkeley extension. + + Effective: next footnote. + + Default: 2n. + + -- Register: \n[FF] + Defines the format of automatically numbered footnotes, and those + for which the 'FS' request is given a marker argument, at the + bottom of a column or page. This is a Berkeley extension. + '0' + Set an automatic number(1) (*note ms Document Control + Settings-Footnote-1::) as a superscript (on typesetter + devices) or surrounded by square brackets (on terminals). The + footnote paragraph is indented as with 'PP' if there is an + 'FS' argument or an automatic number, and as with 'LP' + otherwise. This is the default. + + '1' + As '0', but set the marker as regular text and follow an + automatic number with a period. + + '2' + As '1', but without indentation (like 'LP'). + + '3' + As '1', but set the footnote paragraph with the marker hanging + (like 'IP'). + + Effective: next footnote. + + Default: 0. + + -- Register: \n[FPS] + Defines the footnote type size. + + Effective: next footnote. + + Default: '\n[PS] - 2p'. + + -- Register: \n[FVS] + Defines the footnote vertical spacing. + + Effective: next footnote. + + Default: '\n[FPS] + 2p'. + + -- Register: \n[FPD] + Defines the footnote paragraph spacing. This is a GNU extension. + + Effective: next footnote. + + Default: '\n[PD] / 2'. + + -- String: \*[FR] + 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: '11/12'. + +Display settings +................ + + -- Register: \n[DD] + Sets the display distance--the vertical spacing before and after a + display, a 'tbl' table, an 'eqn' equation, or a 'pic' image. This + is a Berkeley extension. + + Effective: next display boundary. + + Default: 0.5v (1v on low-resolution devices). + + -- Register: \n[DI] + Sets the default amount by which to indent a display started with + 'DS' and 'ID' without arguments, to '.DS I' without an indentation + argument, and to equations set with '.EQ I'. This is a GNU + extension. + + Effective: next indented display. + + Default: 0.5i. + +Other settings +.............. + + -- Register: \n[MINGW] + Defines the default minimum width between columns in a multi-column + document. This is a GNU extension. + + Effective: next page. + + Default: 2n. + + -- Register: \n[TC-MARGIN] + 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 'PX' call. + + Default: '\w'000'' + + (1) defined in *note ms Footnotes:: + +4.6.4 Document Description Macros +--------------------------------- + +Only the simplest document lacks a title.(1) (*note ms Document +Description Macros-Footnote-1::) 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; 'DA' or 'ND' can be +called to set the document date (or other identifier) at any time before +(a) the abstract, if present, or (b) its information is required in a +header or footer. Use of these macros is optional, except that 'TL' is +mandatory if any of 'RP', 'AU', 'AI', or 'AB' is called, and 'AE' is +mandatory if 'AB' is called. + + -- Macro: .RP [no-repeat-info] [no-renumber] + Use the "report" (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 'no-repeat-info' argument is given, + 'ms' produces a cover page but does not repeat any of its + information subsequently (but see the 'DA' macro below regarding + the date). Normally, 'RP' sets the page number following the cover + page to 1. Specifying the optional 'no-renumber' argument + suppresses this alteration. Optional arguments can occur in any + order. 'no' is recognized as a synonym of 'no-repeat-info' for + 'AT&T' compatibility. + + -- Macro: .TL + Specify the document title. 'ms' collects text on input lines + following this call into the title until reaching 'AU', 'AB', or a + heading or paragraphing macro call. + + -- Macro: .AU + Specify an author's name. 'ms' collects text on input lines + following this call into the author's name until reaching 'AI', + 'AB', another 'AU', or a heading or paragraphing macro call. Call + it repeatedly to specify multiple authors. + + -- Macro: .AI + Specify the preceding author's institution. An 'AU' call is + usefully followed by at most one 'AI' call; if there are more, the + last 'AI' call controls. 'ms' collects text on input lines + following this call into the author's institution until reaching + 'AU', 'AB', or a heading or paragraphing macro call. + + -- Macro: .DA [x ...] + Typeset the current date, or any arguments X, in the center footer, + and, if 'RP' is also called, left-aligned at the end of the + description information on the cover page. + + -- Macro: .ND [x ...] + Typeset the current date, or any arguments X, if 'RP' is also + called, left-aligned at the end of the document description on the + cover page. This is 'groff' 'ms''s default. + + -- Macro: .AB [no] + Begin the abstract. 'ms' collects text on input lines following + this call into the abstract until reaching an 'AE' call. By + default, 'ms' places the word "ABSTRACT" centered and in italics + above the text of the abstract. The optional argument 'no' + suppresses this heading. + + -- Macro: .AE + End the abstract. + + An example document description, using a cover page, follows. + + .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 + + ...the rest of the paper... + + (1) Distinguish a document title from "titles", which are what 'roff' +systems call headers and footers collectively. + +4.6.5 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. + +4.6.5.1 Text settings +..................... + +The 'FAM' string, a GNU extension, sets the font family for body text; +the default is 'T'. The 'PS' and '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 'FAM') footnotes. + + Which font families are available depends on the output device; as a +convention, 'T' selects a serif family ("Times"), 'H' a sans-serif +family ("Helvetica"), and 'C' a monospaced family ("Courier"). The man +page for the output driver documents its font repertoire. Consult the +'groff(1)' man page for lists of available output devices and their +drivers. + + The hyphenation mode (as used by the 'hy' request) is set from the +'HY' register. Setting 'HY' to '0' is equivalent to using the 'nh' +request. This is a Tenth Edition Research Unix extension. + +4.6.5.2 Typographical symbols +............................. + +'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 'groff_char(7)' man page. + + -- String: \*[-] + Interpolate an em dash. + + -- String: \*[Q] + -- String: \*[U] + Interpolate typographer's quotation marks where available, and + neutral double quotes otherwise. '\*Q' is the left quote and '\*U' + the right. + +4.6.5.3 Paragraphs +.................. + +Paragraphing macros "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 'PD' register, except at page +or column breaks. Alternatively, a blank input line breaks the output +line and vertically spaces by one vee. + + -- Macro: .LP + Set a paragraph without any (additional) indentation. + + -- Macro: .PP + Set a paragraph with a first-line left indentation in the amount + stored in the 'PI' register. + + -- Macro: .IP [marker [width]] + Set a paragraph with a left indentation. The optional MARKER is + not indented and is empty by default. It has several applications; + see *note Lists in ms::. WIDTH overrides the indentation amount + stored in the 'PI' register; its default unit is 'n'. Once + specified, WIDTH applies to further 'IP' calls until specified + again or a heading or different paragraphing macro is called. + + -- Macro: .QP + Set a paragraph indented from both left and right margins by the + amount stored in the 'QI' register. + + -- Macro: .QS + -- Macro: .QE + Begin ('QS') and end ('QE') a region where each paragraph is + indented from both margins by the amount stored in the 'QI' + register. The text between 'QS' and 'QE' can be structured further + by use of other paragraphing macros. + + -- Macro: .XP + Set an "exdented" paragraph--one with a left indentation in the + amount stored in the 'PI' register on every line _except_ the first + (also known as a hanging indent). This is a Berkeley extension. + + The following example illustrates the use of paragraphing macros. + + .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. + +4.6.5.4 Headings +................ + +Use headings to create a sequential or hierarchical structure for your +document. The 'ms' macros print headings in *bold* using the same font +family and, by default, type size as the body text. Headings are +available with and without automatic numbering. Text on input lines +following the macro call becomes the heading's title. Call a +paragraphing macro to end the heading text and start the section's +content. + + -- Macro: .NH [depth] + -- Macro: .NH S heading-depth-index ... + Set an automatically numbered heading. + + 'ms' produces a numbered heading the form A.B.C..., to any depth + desired, with the numbering of each depth increasing automatically + and being reset to zero when a more significant level is increased. + "1" is the most significant or coarsest division of the document. + Only non-zero values are output. If DEPTH is omitted, it is taken + to be '1'. + + If you specify DEPTH such that an ascending gap occurs relative to + the previous 'NH' call--that is, you "skip a depth", as by '.NH 1' + and then '.NH 3'--'groff' 'ms' emits a warning on the standard + error stream. + + Alternatively, you can give 'NH' a first argument of 'S', followed + by integers to number the heading depths explicitly. Further + automatic numbering, if used, resumes using the specified indices + as their predecessors. This feature is a Berkeley extension. + + An example may be illustrative. + + .NH 1 + Animalia + .NH 2 + Arthropoda + .NH 3 + Crustacea + .NH 2 + Chordata + .NH S 6 6 6 + Daimonia + .NH 1 + Plantae + + The above results in numbering as follows; the vertical space that +normally precedes each heading is omitted. + + 1. Animalia + 1.1. Arthropoda + 1.1.1. Crustacea + 1.2. Chordata + 6.6.6. Daimonia + 7. Plantae + + -- String: \*[SN-STYLE] + -- String: \*[SN-DOT] + -- String: \*[SN-NO-DOT] + -- String: \*[SN] + After 'NH' is called, the assigned number is made available in the + strings 'SN-DOT' (as it appears in a printed heading with default + formatting, followed by a terminating period) and 'SN-NO-DOT' (with + the terminating period omitted). These are GNU extensions. + + You can control the style used to print numbered headings by + defining an appropriate alias for the string 'SN-STYLE'. By + default, 'SN-STYLE' is aliased to 'SN-DOT'. If you prefer to omit + the terminating period from numbers appearing in numbered headings, + you may define the alias as follows. + + .als SN-STYLE SN-NO-DOT + + Any such change in numbering style becomes effective from the next + use of 'NH' following redefinition of the alias for 'SN-STYLE'. + The formatted number of the current heading is available in the + 'SN' string (a feature first documented by Berkeley), which + facilitates its inclusion in, for example, table captions, equation + labels, and 'XS'/'XA'/'XE' table of contents entries. + + -- Macro: .SH [depth] + Set an unnumbered heading. + + The optional DEPTH argument is a GNU extension indicating the + heading depth corresponding to the DEPTH argument of 'NH'. It + matches the type size at which the heading is set to that of a + numbered heading at the same depth when the 'GROWPS' and 'PSINCR' + heading size adjustment mechanism is in effect. + + If the 'GROWPS' register is set to a value greater than the LEVEL +argument to 'NH' or 'SH', the type size of a heading produced by these +macros increases by 'PSINCR' units over the size specified by 'PS' +multiplied by the difference of 'GROWPS' and LEVEL. The value stored in +'PSINCR' is interpreted in 'groff' basic units; the 'p' scaling unit +should be employed when assigning a value specified in points. For +example, the sequence + + .nr PS 10 + .nr GROWPS 3 + .nr PSINCR 1.5p + .NH 1 + Carnivora + .NH 2 + Felinae + .NH 3 + Felis catus + .SH 2 + Machairodontinae + +will cause "1. Carnivora" to be printed in 13-point text, followed by +"1.1. Felinae" in 11.5-point text, while "1.1.1. Felis catus" and all +more deeply nested heading levels will remain in the 10-point text +specified by the 'PS' register. "Machairodontinae" is printed at 11.5 +points, since it corresponds to heading level 2. + + The 'HORPHANS' register operates in conjunction with the 'NH' and +'SH' macros to inhibit the printing of isolated headings at the bottom +of a page; it specifies the minimum number of lines of an immediately +subsequent paragraph that must be kept on the same page as the heading. +If insufficient space remains on the current page to accommodate the +heading and this number of lines of paragraph text, a page break is +forced before the heading is printed. Any display macro call or 'tbl', +'pic', or 'eqn' region between the heading and the subsequent paragraph +suppresses this grouping. *Note ms keeps and displays:: and *note ms +Insertions::. + +4.6.5.5 Typeface and decoration +............................... + +The 'ms' macros provide a variety of ways to style text. Attend closely +to the ordering of arguments labeled PRE and POST, which is not +intuitive. Support for PRE arguments is a GNU extension.(1) (*note +Typeface and decoration-Footnote-1::) + + -- Macro: .B [text [post [pre]]] + Style TEXT in bold, followed by POST in the previous font style + without intervening space, and preceded by PRE similarly. Without + arguments, 'ms' styles subsequent text in bold until the next + paragraphing, heading, or no-argument typeface macro call. + + -- Macro: .R [text [post [pre]]] + As 'B', but use the roman style (upright text of normal weight) + instead of bold. Argument recognition is a GNU extension. + + -- Macro: .I [text [post [pre]]] + As 'B', but use an italic or oblique style instead of bold. + + -- Macro: .BI [text [post [pre]]] + As 'B', but use a bold italic or bold oblique style instead of + upright bold. This is a Tenth Edition Research Unix extension. + + -- Macro: .CW [text [post [pre]]] + As 'B', but use a constant-width (monospaced) roman typeface + instead of bold. This is a Tenth Edition Research Unix extension. + + -- Macro: .BX [text] + Typeset TEXT and draw a box around it. On terminal devices, + reverse video is used instead. If you want TEXT to contain space, + use unbreakable space or horizontal motion escape sequences ('\~', + '\<SP>', '\^', '\|', '\0' or '\h'). + + -- Macro: .UL [text [post]] + Typeset TEXT with an underline. POST, if present, is set after + TEXT with no intervening space. + + -- Macro: .LG + 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. + + -- Macro: .SM + 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. + + -- Macro: .NL + Set subsequent text at the normal type size (the amount in the 'PS' + register). + + PRE and POST arguments are typically used to simplify the attachment +of punctuation to styled words. When PRE is used, a hyphenation control +escape sequence '\%' that would ordinarily start TEXT must start PRE +instead to have the desired effect. + + The CS course's students found one C language keyword + .CW static ) \%( + most troublesome. + + The foregoing example produces output as follows. + + The CS course's students found one C language keyword (static) + most troublesome. + + You can use the output line continuation escape sequence '\c' to +achieve the same result (*note Line Continuation::). It is also +portable to older 'ms' implementations. + + The CS course's students found one C language keyword + \%(\c + .CW \%static ) + most troublesome. + + 'groff' 'ms' also offers strings to begin and end super- and +subscripting. These are GNU extensions. + + -- String: \*[{] + -- String: \*[}] + Begin and end superscripting, respectively. + + -- String: \*[<] + -- String: \*[>] + Begin and end subscripting, respectively. + + Rather than calling the 'CW' macro, in 'groff' 'ms' you might prefer +to change the font family to Courier by setting the 'FAM' string to 'C'. +You can then use all four style macros above, returning to the default +family (Times) with '.ds FAM T'. Because changes to 'FAM' take effect +only at the next paragraph, 'CW' remains useful to "inline" a change to +the font family, similarly to the practice of this document in noting +syntactical elements of 'ms' and 'groff'. + + (1) This idiosyncrasy arose through feature accretion; for example, +the 'B' macro in Version 6 Unix 'ms' (1975) accepted only one argument, +the text to be set in boldface. By Version 7 (1979) it recognized a +second argument; in 1990, 'groff' 'ms' added a "pre" argument, placing +it third to avoid breaking support for older documents. + +4.6.5.6 Lists +............. + +The MARKER argument to the 'IP' macro can be employed to present a +variety of lists; for instance, you can use a bullet glyph ('\[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 'PI' before calling 'IP', you +can later reorder the items in the list without having to ensure that a +WIDTH argument remains affixed to the first call. + + The following is an example of a bulleted list. + + .nr PI 2n + A bulleted list: + .IP \[bu] + lawyers + .IP \[bu] + guns + .IP \[bu] + money + + A bulleted list: + + * lawyers + + * guns + + * money + + The following is an example of a numbered list. + + .nr step 0 1 + .nr PI 3n + A numbered list: + .IP \n+[step] + lawyers + .IP \n+[step] + guns + .IP \n+[step] + money + + A numbered list: + + 1. lawyers + + 2. guns + + 3. money + + Here we have employed the 'nr' request to create a register of our +own, 'step'. We initialized it to zero and assigned it an +auto-increment of 1. Each time we use the escape sequence '\n+[PI]' +(note the plus sign), the formatter applies the increment just before +interpolating the register's value. Preparing the '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. + + 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! + + A glossary-style list: + + lawyers + Two or more attorneys. + + guns Firearms, preferably large-caliber. + + money + Gotta pay for those lawyers and guns! + + In the previous example, observe how the '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 'br' request to force a +break after printing the term or label. + + .IP guns + .br + Firearms, + + Second, you could apply the '\p' escape sequence to force a break. +The space following the escape sequence is important; if you omit it, +'groff' prints the first word of the paragraph text on the same line as +the term or label (if it fits) _then_ breaks the line. + + .IP guns + \p Firearms, + + Finally, you may append a horizontal motion to the marker with the +'\h' escape sequence; using the same amount as the indentation will +ensure that the marker is too wide for 'groff' to treat it as "fitting" +on the same line as the paragraph text. + + .IP guns\h'0.4i' + Firearms, + + In each case, the result is the same. + + A glossary-style list: + + lawyers + Two or more attorneys. + + guns + Firearms, preferably large-caliber. + + money + Gotta pay for those lawyers and guns! + +4.6.5.7 Indented regions +........................ + +You may need to indent a region of text while otherwise formatting it +normally. Indented regions can be nested; you can change '\n[PI]' +before each call to vary the amount of inset. + + -- Macro: .RS + Begin a region where headings, paragraphs, and displays are + indented (further) by the amount stored in the 'PI' register. + + -- Macro: .RE + End the (next) most recent indented region. + + This feature enables you to easily line up text under hanging and +indented paragraphs. For example, you may wish to structure lists +hierarchically. + + .IP \[bu] 2 + Lawyers: + .RS + .IP \[bu] + Dewey, + .IP \[bu] + Cheatham, + and + .IP \[bu] + and Howe. + .RE + .IP \[bu] + Guns + + * Lawyers: + + * Dewey, + + * Cheatham, and + + * Howe. + + * Guns + +4.6.5.8 Keeps, boxed keeps, and displays +........................................ + +On occasion, you may want to "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. 'ms' provides the 'KS' and +'KE' macros for this purpose. + + You can alternatively specify a "floating keep": if a keep cannot fit +on the current page, '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 'bp' +request, '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. + + -- Macro: .KS + -- Macro: .KF + -- Macro: .KE + 'KS' begins a keep, 'KF' a floating keep, and 'KE' ends a keep of + either kind. + + As an alternative to the keep mechanism, the '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 (*note Page Control::). +One application of 'ne' is to reserve space on the page for a figure or +illustration to be included later. + + A "boxed keep" has a frame drawn around it. + + -- Macro: .B1 + -- Macro: .B2 + 'B1' begins a keep with a box drawn around it. 'B2' ends a boxed + keep. + + Boxed keep macros cause breaks; if you need to box a word or phrase +within a line, see the 'BX' macro in *note 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 'B1' after the +first paragraphing macro, and by adding a small amount of vertical space +before calling 'B2'. + + .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 + + If you want a boxed keep to float, you will need to enclose the 'B1' +and 'B2' calls within a pair of 'KF' and 'KE' calls. + + "Displays" turn off filling; lines of verse or program code are shown +with their lines broken as in the source document without requiring 'br' +requests between lines. Displays can be kept on a single page or +allowed to break across pages. The '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. + + -- Macro: .DS L + -- Macro: .LD + Begin ('DS': kept) left-aligned display. + + -- Macro: .DS [I [indent]] + -- Macro: .ID [indent] + Begin ('DS': kept) display indented by INDENT if specified, and by + the amount of the 'DI' register otherwise. + + -- Macro: .DS B + -- Macro: .BD + Begin a ('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. + + -- Macro: .DS C + -- Macro: .CD + Begin a ('DS': kept) centered display: each line in the display is + centered. + + -- Macro: .DS R + -- Macro: .RD + Begin a ('DS': kept) right-aligned display. This is a GNU + extension. + + -- Macro: .DE + End any display. + + The distance stored in the 'DD' register is inserted before and after +each pair of display macros; this is a Berkeley extension. In 'groff' +'ms', this distance replaces any adjacent inter-paragraph distance or +subsequent spacing prior to a section heading. The 'DI' register is a +GNU extension; its value is an indentation applied to displays created +with '.DS' and '.ID' without arguments, to '.DS I' without an +indentation argument, and to indented equations set with '.EQ'. Changes +to either register take effect at the next display boundary. + +4.6.5.9 Tables, figures, equations, and references +.................................................. + +The 'ms' package is often used with the 'tbl', 'pic', 'eqn', and 'refer' +preprocessors. 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. + + -- Macro: .TS [H] + -- Macro: .TE + Demarcate a table to be processed by the 'tbl' preprocessor. The + optional argument 'H' to 'TS' instructs 'ms' to repeat table rows + (often column headings) at the top of each new page the table + spans, if applicable; calling the 'TH' macro marks the end of such + rows. The GNU 'tbl(1)' man page provides a comprehensive reference + to the preprocessor and offers examples of its use. + + -- Macro: .PS + -- Macro: .PE + -- Macro: .PF + 'PS' begins a picture to be processed by the 'gpic' preprocessor; + either of 'PE' or 'PF' ends it, the latter with "flyback" to the + vertical position at its top. You can create 'pic' input manually + or with a program such as 'xfig'. + + -- Macro: .EQ [align [label]] + -- Macro: .EN + Demarcate an equation to be processed by the 'eqn' preprocessor. + The equation is centered by default; ALIGN can be 'C', 'L', or 'I' + to (explicitly) center, left-align, or indent it by the amount + stored in the 'DI' register, respectively. If specified, LABEL is + set right-aligned. + + -- Macro: .[ + -- Macro: .] + Demarcate a bibliographic citation to be processed by the 'refer' + preprocessor. The GNU 'refer(1)' man page provides a comprehensive + reference to the preprocessor and the format of its bibliographic + database. Type 'man refer' at the command line to view it. + + When 'refer' emits collected references (as might be done on a "Works +Cited" page), it interpolates the 'REFERENCES' string as an unnumbered +heading ('SH'). + + The following is an example of how to set up a table that may print +across two or more pages. + + .TS H + allbox; + Cb | Cb . + Part->Description + _ + .TH + .T& + GH-1978->Fribulating gonkulator + ...the rest of the table follows... + .TE + +Attempting to place a multi-page table inside a keep can lead to +unpleasant results, particularly if the 'tbl' 'allbox' option is used. + + Mathematics can be typeset using the language of the 'eqn' +preprocessor. + + .EQ C (\*[SN-NO-DOT]a) + p ~ = ~ q sqrt { ( 1 + ~ ( x / q sup 2 ) } + .EN + +This input formats a labelled equation. We used the 'SN-NO-DOT' string +to base the equation label on the current heading number, giving us more +flexibility to reorganize the document. + + Use 'groff' options to run preprocessors on the input: '-e' for +'geqn', '-p' for 'gpic', '-R' for 'grefer', and '-t' for 'gtbl'. + +4.6.5.10 Footnotes +.................. + +A footnote is typically anchored to a place in the text with a "marker", +which is a small integer, a symbol such as a dagger, or arbitrary +user-specified text. + + -- String: \*[*] + Place an "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. + + Enclose the footnote text in 'FS' and 'FE' macro calls to set it at +the nearest available "foot", or bottom, of a text column or page. + + -- Macro: .FS [marker] + -- Macro: .FE + Begin ('FS') and end ('FE') a footnote. 'FS' calls 'FS-MARK' with + any supplied MARKER argument, which is then also placed at the + beginning of the footnote text. If MARKER is omitted, the next + pending automatic footnote number enqueued by interpolation of the + '*' string is used, and if none exists, nothing is prefixed. + + 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 +'\[dg]' for the dagger glyph) _and_ as an argument to the 'FS' macro. +Such manual marks should be repeated as arguments to 'FS' or as part of +the footnote text to disambiguate their correspondence. You may wish to +use '\*{' and '\*}' to superscript the marker at the anchor point, in +the footnote text, or both. + + 'groff' 'ms' provides a hook macro, 'FS-MARK', for user-determined +operations to be performed when the 'FS' macro is called. It is passed +the same arguments as 'FS' itself. An application of 'FS-MARK' is +anchor placement for a hyperlink reference, so that a footnote can link +back to its referential context.(1) (*note ms Footnotes-Footnote-1::) +By default, this macro has an empty definition. 'FS-MARK' is a GNU +extension. + + 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 '\**' interpolation between a '\**' and +its corresponding 'FS' call as long as each 'FS' call occurs _after_ the +corresponding '\**' and occurrences of 'FS' are in the same order as +corresponding occurrences of '\**'. + + Footnote text is formatted as paragraphs are, using analogous +parameters. The registers 'FI', 'FPD', 'FPS', and 'FVS' correspond to +'PI', 'PD', 'PS', and 'CS', respectively; 'FPD', 'FPS', and 'FVS' are +GNU extensions. + + The 'FF' register controls the formatting of automatically numbered +footnote paragraphs and those for which 'FS' is given a marker argument. +*Note ms Document Control Settings::. + + The default footnote line length is 11/12ths of the normal line +length for compatibility with the expectations of historical 'ms' +documents; you may wish to set the 'FR' string to '1' to align with +contemporary typesetting practices. In the past,(2) (*note ms +Footnotes-Footnote-2::) an '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.(3) (*note ms Footnotes-Footnote-3::) + + 'FR' should be used in preference to the old 'FL' register in +contemporary documents. The footnote line length is effectively +computed as 'column-width * \*[FR]'. If an absolute footnote line +length is required, recall that arithmetic expressions in 'roff' input +are evaluated strictly from left to right, with no operator precedence +(parentheses are honored). + + .ds FR 0+3i \" Set footnote line length to 3 inches. + + (1) "Portable Document Format Publishing with GNU Troff", +'pdfmark.ms' in the 'groff' distribution, uses this technique. + + (2) Unix Version 7 'ms', its descendants, and GNU 'ms' prior to +'groff' version 1.23.0 + + (3) You could reset it after each call to '.1C', '.2C', or '.MC'. + +4.6.5.11 Language and localization +.................................. + +'groff' '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 Czech, German, French, +Italian, and Swedish. Load the desired localization macro package after +'ms'; see the 'groff_tmac(5)' man page. + + $ groff -ms -mfr bienvenue.ms + + The following strings are available. + + -- String: \*[REFERENCES] + Contains the string printed at the beginning of a references + (bibliography) page produced with GNU 'refer(1)'. The default is + 'References'. + + -- String: \*[ABSTRACT] + Contains the string printed at the beginning of the abstract. The + default is '\f[I]ABSTRACT\f[]'; it includes font selection escape + sequences to set the word in italics. + + -- String: \*[TOC] + Contains the string printed at the beginning of the table of + contents. The default is 'Table of Contents'. + + -- String: \*[MONTH1] + -- String: \*[MONTH2] + -- String: \*[MONTH3] + -- String: \*[MONTH4] + -- String: \*[MONTH5] + -- String: \*[MONTH6] + -- String: \*[MONTH7] + -- String: \*[MONTH8] + -- String: \*[MONTH9] + -- String: \*[MONTH10] + -- String: \*[MONTH11] + -- String: \*[MONTH12] + Contain the full names of the calendar months. The defaults are in + English: 'January', 'February', and so on. + +4.6.6 Page layout +----------------- + +'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. + +4.6.6.1 Headers and footers +........................... + +There are multiple ways to produce headers and footers. One is to +define the strings 'LH', 'CH', and 'RH' to set the left, center, and +right headers, respectively; and 'LF', 'CF', and '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 (''') shown below with +any character not appearing in the header or footer text. These macros +are Berkeley extensions. + + -- Macro: .OH 'left'center'right' + -- Macro: .EH 'left'center'right' + -- Macro: .OF 'left'center'right' + -- Macro: .EF 'left'center'right' + The 'OH' and 'EH' macros define headers for odd- (recto) and + even-numbered (verso) pages, respectively; the 'OF' and 'EF' macros + define footers for them. + + With either method, a percent sign '%' in header or footer text is +replaced by the current page number. By default, 'ms' places no header +on a page numbered "1" (regardless of its number format). + + -- Macro: .P1 + Typeset the header even on page 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 'TL' or any + heading or paragraphing macro. This is a Berkeley extension. + + For even greater flexibility, 'ms' is designed to permit the +redefinition of the macros that are called when the 'groff' traps that +ordinarily cause the headers and footers to be output are sprung. 'PT' +("page trap") is called by 'ms' when the header is to be written, and +'BT' ("bottom trap") when the footer is to be. The 'groff' page +location trap that 'ms' sets up to format the header also calls the +(normally undefined) 'HD' macro after 'PT'; you can define 'HD' if you +need additional processing after setting the header (for example, to +draw a line below it). The 'HD' hook is a Berkeley extension. Any such +macros you (re)define must implement any desired specialization for +odd-, even-, or first numbered pages. + +4.6.6.2 Tab stops +................. + +Use the 'ta' request to define tab stops as needed. *Note Tabs and +Fields::. + + -- Macro: .TA + Reset the tab stops to the 'ms' default (every 5 ens). Redefine + this macro to create a different set of default tab stops. + +4.6.6.3 Margins +............... + +Control margins using the registers summarized in "Margin settings" in +*note ms Document Control Settings:: above. There is no setting for the +right margin; the combination of page offset '\n[PO]' and line length +'\n[LL]' determines it. + +4.6.6.4 Multiple columns +........................ + +'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 'MINGW' register stores the default minimum +gutter width; it is a GNU extension. When multiple columns are in use, +keeps and the 'HORPHANS' and 'PORPHANS' registers work with respect to +column breaks instead of page breaks. + + -- Macro: .1C + Arrange page text in a single column (the default). + + -- Macro: .2C + Arrange page text in two columns. + + -- Macro: .MC [column-width [gutter-width]] + Arrange page text in multiple columns. If you specify no + arguments, it is equivalent to the '2C' macro. Otherwise, + COLUMN-WIDTH is the width of each column and GUTTER-WIDTH is the + minimum distance between columns. + +4.6.6.5 Creating a table of contents +.................................... + +Because 'roff' formatters process their input in a single pass, material +on page 50, for example, cannot influence what appears on page 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. '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 'sed(1)' script to reorder the pages +in 'troff''s output, with 'pdfjam(1)', or with 'gropdf(1)''s +'.pdfswitchtopage' feature, for example. + + Define an entry to appear in the table of contents by bracketing its +text between calls to the 'XS' and 'XE' macros. A typical application +is to call them immediately after 'NH' or 'SH' and repeat the heading +text within them. The 'XA' macro, used within '.XS'/'.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 'XA' macro. 'XS' +and '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 'TC' or 'PX' to emit the +table of contents; 'TC' resets the page number to 'i' (Roman numeral +one), and then calls 'PX'. All of these macros are Berkeley extensions. + + -- Macro: .XS [page-number] + -- Macro: .XA [page-number [indentation]] + -- Macro: .XE + Begin, supplement, and end a table of contents entry. Each entry + is associated with PAGE-NUMBER (otherwise the current page number); + a PAGE-NUMBER of 'no' prevents a leader and page number from being + emitted for that entry. Use of 'XA' within 'XS'/'XE' is optional; + it can be repeated. If INDENTATION is present, a supplemental + entry is indented by that amount; ens are assumed if no unit is + indicated. Text on input lines between 'XS' and 'XE' is stored for + later recall by 'PX'. + + -- Macro: .PX [no] + Switch to single-column layout. Unless 'no' is specified, center + and interpolate the 'TOC' string in bold and two points larger than + the body text. Emit the table of contents entries. + + -- Macro: .TC [no] + Set the page number to 1, the page number format to lowercase Roman + numerals, and call 'PX' (with a 'no' argument, if present). + + Here's an example of typical 'ms' table of contents preparation. We +employ horizontal escape sequences '\h' to indent the entries by +sectioning depth. + + .NH 1 + Introduction + .XS + Introduction + .XE + ... + .NH 2 + Methodology + .XS + \h'2n'Methodology + .XA + \h'4n'Fassbinder's Approach + \h'4n'Kahiu's Approach + .XE + ... + .NH 1 + Findings + .XS + Findings + .XE + ... + .TC + + The remaining features in this subsubsection are GNU extensions. +'groff' 'ms' obviates the need to repeat heading text after 'XS' calls. +Call 'XN' and 'XH' after 'NH' and 'SH', respectively. + + -- Macro: .XN heading-text + -- Macro: .XH depth heading-text + Format HEADING-TEXT and create a corresponding table of contents + entry. 'XN' computes the indentation from the depth of the + preceding 'NH' call; 'XH' requires a DEPTH argument to do so. + + 'groff' 'ms' encourages customization of table of contents entry +production. + + -- Macro: .XN-REPLACEMENT heading-text + -- Macro: .XH-REPLACEMENT depth heading-text + These hook macros implement 'XN' and 'XH', respectively. They call + 'XN-INIT' and pass their HEADING-TEXT arguments to 'XH-UPDATE-TOC'. + + -- Macro: .XN-INIT + -- Macro: .XH-UPDATE-TOC depth heading-text + The 'XN-INIT' hook macro does nothing by default. 'XH-UPDATE-TOC' + brackets HEADING-TEXT with 'XS' and 'XE' calls, indenting it by 2 + ens per level of DEPTH beyond the first. + + 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.) + + .NH 1 + .XN Introduction + ... + .NH 2 + .XN Methodology + .XH 3 "Fassbinder's Approach" + .XH 3 "Kahiu's Approach" + ... + .NH 1 + .XN Findings + ... + + To get the section number of the numbered headings into the table of +contents entries, we might define 'XN-REPLACEMENT' as follows. (We +obtain the heading depth from 'groff' 'ms''s internal register 'nh*hl'.) + + .de XN-REPLACEMENT + .XN-INIT + .XH-UPDATE-TOC \\n[nh*hl] \\$@ + \&\\*[SN] \\$* + .. + + You can change the style of the leader that bridges each table of +contents entry with its page number; define the 'TC-LEADER' special +character by using the 'char' request. A typical leader combines the +dot glyph '.' with a horizontal motion escape sequence to spread the +dots. The width of the page number field is stored in the 'TC-MARGIN' +register. + +4.6.7 Differences from AT&T 'ms' +-------------------------------- + +The 'groff' 'ms' macros are an independent reimplementation, using no +AT&T code. Since they take advantage of the extended features of +'groff', they cannot be used with AT&T 'troff'. 'groff' 'ms' supports +features described above as Berkeley and Tenth Edition Research Unix +extensions, and adds several of its own. + + * The internals of 'groff' 'ms' differ from the internals of AT&T + 'ms'. Documents that depend upon implementation details of AT&T + 'ms' may not format properly with 'groff' 'ms'. Such details + include macros whose function was not documented in the AT&T 'ms' + manual.(1) (*note Differences from AT&T ms-Footnote-1::) + + * The error-handling policy of 'groff' 'ms' is to detect and report + errors, rather than to ignore them silently. + + * Tenth Edition Research Unix supported 'P1'/'P2' macros to bracket + code examples; 'groff' 'ms' does not. + + * 'groff' 'ms' does not work in GNU 'troff''s AT&T compatibility + mode. If loaded when that mode is enabled, it aborts processing + with a diagnostic message. + + * Multiple line spacing is not supported. Use a larger vertical + spacing instead. + + * 'groff' 'ms' uses the same header and footer defaults in both + 'nroff' and 'troff' modes as AT&T 'ms' does in 'troff' mode; AT&T's + default in 'nroff' mode is to put the date, in U.S. traditional + format (e.g., "January 1, 2021"), in the center footer (the 'CF' + string). + + * Many 'groff' '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 'ms' 'RS' and 'RE' + macros instead of the 'in' request. + + * AT&T 'ms' interpreted the values of the registers 'PS' and 'VS' in + points, and did not support the use of scaling units with them. + 'groff' 'ms' interprets values of the registers 'PS', 'VS', 'FPS', + and 'FVS' equal to or larger than 1,000 (one thousand) as decimal + fractions multiplied by 1,000.(2) (*note Differences from AT&T + ms-Footnote-2::) 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, 'groff -rPS=10.5p' at the + shell prompt is equivalent to placing '.nr PS 10.5p' at the + beginning of the document. + + * AT&T 'ms''s 'AU' macro supported arguments used with some document + types; 'groff' 'ms' does not. + + * Right-aligned displays are available. The AT&T 'ms' manual + observes that "it is tempting to assume that '.DS R' will right + adjust lines, but it doesn't work". In 'groff' 'ms', it does. + + * To make 'groff' 'ms' use the default page offset (which also + specifies the left margin), the 'PO' register must stay undefined + until the first 'ms' macro is called. + + This implies that '\n[PO]' should not be used early in the + document, unless it is changed also: accessing an undefined + register automatically defines it. + + * 'groff' 'ms' supports the 'PN' register, but it is not necessary; + you can access the page number via the usual '%' register and + invoke the 'af' request to assign a different format to it if + desired.(3) (*note Differences from AT&T ms-Footnote-3::) + + * The AT&T 'ms' manual documents registers 'CW' and 'GW' as setting + the default column width and "intercolumn gap", respectively, and + which applied when 'MC' was called with fewer than two arguments. + 'groff' 'ms' instead treats 'MC' without arguments as synonymous + with '2C'; there is thus no occasion for a default column width + register. Further, the 'MINGW' register and the second argument to + 'MC' specify a _minimum_ space between columns, not the fixed + gutter width of AT&T 'ms'. + + * The AT&T 'ms' manual did not document the 'QI' register; Berkeley + and 'groff' 'ms' do. + + -- Register: \n[GS] + The register 'GS' is set to 1 by the 'groff' 'ms' macros, but is + not used by the AT&T 'ms' package. Documents that need to + determine whether they are being formatted with 'groff' 'ms' or + another implementation should test this register. + + (1) 'Typing Documents on the UNIX System: Using the -ms Macros with +Troff and Nroff', M. E. Lesk, Bell Laboratories, 1978 + + (2) Register values are converted to and stored as basic units. +*Note Measurements::. + + (3) If you redefine the 'ms' 'PT' macro and desire special treatment +of certain page numbers (like '1'), you may need to handle a non-Arabic +page number format, as 'groff' 'ms''s 'PT' does; see the macro package +source. 'groff' 'ms' aliases the 'PN' register to '%'. + +4.6.7.1 Unix Version 7 'ms' macros not implemented by 'groff' 'ms' +.................................................................. + +Several macros described in the Unix Version 7 'ms' documentation are +unimplemented by 'groff' '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 'groff' does +not support. These macros implemented several document type formats +('EG', 'IM', 'MF', 'MR', 'TM', 'TR'), were meaningful only in +conjunction with the use of certain document types ('AT', 'CS', 'CT', +'OK', 'SG'), stored the postal addresses of Bell Labs sites ('HO', 'IH', +'MH', 'PY', 'WH'), or lacked a stable definition over time ('UX'). To +compatibly render historical 'ms' documents using these macros, we +advise your documents to invoke the 'rm' request to remove any such +macros it uses and then define replacements with an authentically +typeset original at hand.(1) (*note Missing Unix Version 7 ms +Macros-Footnote-1::) For informal purposes, a simple definition of 'UX' +should maintain the readability of the document's substance. + + .rm UX + .ds UX Unix\" + + (1) The removal beforehand is necessary because 'groff' 'ms' aliases +these macros to a diagnostic macro, and you want to redefine the aliased +name, not its target. + +4.6.8 Legacy Features +--------------------- + +'groff' '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 'groff_char(7)' man page. + +AT&T accent mark strings +........................ + +AT&T 'ms' defined accent mark strings as follows. + + -- String: \*['] + Apply acute accent to subsequent glyph. + + -- String: \*[`] + Apply grave accent to subsequent glyph. + + -- String: \*[:] + Apply dieresis (umlaut) to subsequent glyph. + + -- String: \*[^] + Apply circumflex accent to subsequent glyph. + + -- String: \*[~] + Apply tilde accent to subsequent glyph. + + -- String: \*[C] + Apply caron to subsequent glyph. + + -- String: \*[,] + Apply cedilla to subsequent glyph. + +Berkeley accent mark and glyph strings +...................................... + +Berkeley 'ms' offered an 'AM' macro; calling it redefined the AT&T +accent mark strings (except for '\*C'), applied them to the _preceding_ +glyph, and defined additional strings, some for spacing glyphs. + + -- Macro: .AM + Enable alternative accent mark and glyph-producing strings. + + -- String: \*['] + Apply acute accent to preceding glyph. + + -- String: \*[`] + Apply grave accent to preceding glyph. + + -- String: \*[:] + Apply dieresis (umlaut) to preceding glyph. + + -- String: \*[^] + Apply circumflex accent to preceding glyph. + + -- String: \*[~] + Apply tilde accent to preceding glyph. + + -- String: \*[,] + Apply cedilla to preceding glyph. + + -- String: \*[/] + Apply stroke (slash) to preceding glyph. + + -- String: \*[v] + Apply caron to preceding glyph. + + -- String: \*[_] + Apply macron to preceding glyph. + + -- String: \*[.] + Apply underdot to preceding glyph. + + -- String: \*[o] + Apply ring accent to preceding glyph. + + -- String: \*[?] + Interpolate inverted question mark. + + -- String: \*[!] + Interpolate inverted exclamation mark. + + -- String: \*[8] + Interpolate small letter sharp s. + + -- String: \*[q] + Interpolate small letter o with hook accent (ogonek). + + -- String: \*[3] + Interpolate small letter yogh. + + -- String: \*[d-] + Interpolate small letter eth. + + -- String: \*[D-] + Interpolate capital letter eth. + + -- String: \*[th] + Interpolate small letter thorn. + + -- String: \*[Th] + Interpolate capital letter thorn. + + -- String: \*[ae] + Interpolate small æ ligature. + + -- String: \*[Ae] + Interpolate capital Æ ligature. + + -- String: \*[oe] + Interpolate small oe ligature. + + -- String: \*[OE] + Interpolate capital OE ligature. + +4.6.9 Naming Conventions +------------------------ + +The following conventions are used for names of macros, strings, and +registers. External names available to documents that use the 'groff' +'ms' macros contain only uppercase letters and digits. + + Internally, the macros are divided into modules. Conventions for +identifier names are as follows. + + * Names used only within one module are of the form MODULE'*'NAME. + + * Names used outside the module in which they are defined are of the + form MODULE'@'NAME. + + * Names associated with a particular environment are of the form + ENVIRONMENT':'NAME; these are used only within the 'par' module. + + * NAME does not have a module prefix. + + * Constructed names used to implement arrays are of the form + ARRAY'!'INDEX. + + Thus the 'groff' 'ms' macros reserve the following names. + + * Names containing the characters '*', '@', and ':'. + + * Names containing only uppercase letters and digits. + +5 GNU 'troff' Reference +*********************** + +This chapter covers _all_ of the facilities of the GNU 'troff' +formatting engine. Users of macro packages may skip it if not +interested in details. + +5.1 Text +======== + +AT&T '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 '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. + + 'roff' input files contain text interspersed with instructions to +control the formatter. Even in the absence of such instructions, GNU +'troff' still processes its input in several ways, by filling, +hyphenating, breaking, and adjusting it, and supplementing it with +inter-sentence space. + +5.1.1 Filling +------------- + +When GNU 'troff' starts up, it obtains information about the device for +which it is preparing output.(1) (*note Filling-Footnote-1::) An +essential property is the length of the output line, such as "6.5 +inches". + + GNU '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 "filling". To GNU 'troff', a +"word" is any sequence of one or more characters that aren't spaces or +newlines. The exceptions separate words.(2) (*note +Filling-Footnote-2::) To disable filling, see *note Manipulating Filling +and Adjustment::. + + It is a truth universally acknowledged + that a single man in possession of a + good fortune must be in want of a wife. + => It is a truth universally acknowledged that a + => single man in possession of a good fortune must + => be in want of a wife. + + (1) *Note Device and Font Description Files::. + + (2) Tabs and leaders also separate words. Escape sequences can +function as word characters, word separators, or neither--the last +simply have no effect on GNU 'troff''s idea of whether an input +character is within a word. We'll discuss all of these in due course. + +5.1.2 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.(1) (*note +Sentences-Footnote-1::) GNU 'troff' follows the example of AT&T 'troff'; +it attempts to detect the boundaries between sentences, and supplies +additional inter-sentence space between them. + + Hello, world! + Welcome to groff. + => Hello, world! Welcome to groff. + + GNU 'troff' flags certain characters (normally '!', '?', and '.') as +potentially ending a sentence. When GNU 'troff' encounters one of these +"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. + + R. Harper subscribes to a maxim of P. T. Barnum. + => R. Harper subscribes to a maxim of P. T. Barnum. + + In the above example, inter-sentence space is not added after 'P.' or +'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. + + I submit that R. Harper subscribes to a maxim of P. T. + Barnum. + => I submit that R. Harper subscribes to a maxim of + => P. T. Barnum. + + "Barnum" doesn't begin a sentence! What to do? Let us meet our +first "escape sequence", a series of input characters that give +instructions to GNU 'troff' instead of being used to construct output +device glyphs.(2) (*note Sentences-Footnote-2::) An escape sequence +begins with the backslash character '\' by default, an uncommon +character in natural language text, and is _always_ followed by at least +one other character, hence the term "sequence". + + The dummy character escape sequence '\&' 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. + + I submit that R.\& Harper subscribes to a maxim of P.\& + T.\& Barnum. + => I submit that R. Harper subscribes to a maxim of + => P. T. Barnum. + + Adding text caused our input to wrap; now, we don't need '\&' after +'T.' but we do after '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 *note Input +Conventions::. + + 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 'troff' to infer the end of a sentence after +the dot in '3.14159'. However, several characters are treated +_transparently_ after the occurrence of an end-of-sentence character. +That is, GNU '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 '"', ''', ')', ']', '*', '\[dg]', '\[dd]', '\[rq]', and '\[cq]'. +The last four are examples of "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 'troff' (like '\' +itself).(3) (*note Sentences-Footnote-3::) + + \[lq]The idea that the poor should have leisure has always + been shocking to the rich.\[rq] + (Bertrand Russell, 1935) + => "The idea that the poor should have + => leisure has always been shocking to + => the rich." (Bertrand Russell, 1935) + + The sets of characters that potentially end sentences or are +transparent to sentence endings are configurable. See the 'cflags' +request in *note Using Symbols::. To change the additional +inter-sentence space amount--even to remove it entirely--see *note +Manipulating Filling and Adjustment::. + + (1) A well-researched jeremiad appreciated by 'groff' contributors on +both sides of the sentence-spacing debate can be found at +<https://web.archive.org/web/20171217060354/http://www.heracliteanriver.com/?p=324>. + + (2) This statement oversimplifies; there are escape sequences whose +purpose is precisely to produce glyphs on the output device, and input +characters that _aren't_ part of escape sequences can undergo a great +deal of processing before getting to the output. + + (3) The mnemonics for the special characters shown here are "dagger", +"double dagger", "right (double) quote", and "closing (single) quote". +See the 'groff_char(7)' man page. + +5.1.3 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 "hyphenation". Hyphenation points can be manually specified; +GNU '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. *Note +Manipulating Hyphenation::. + +5.1.4 Breaking +-------------- + +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 "break". In +this manual and in '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 '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 'perl' at the shell prompt to +contrive an example of failure to break the line. We also employ the +'-z' option to suppress normal output. + + $ perl -e 'print "#" x 80, "\n";' | nroff -z + error-> warning: cannot break line + + The remedy for these cases is to tell GNU 'troff' where the line may +be broken without hyphens. This is done with the non-printing break +point escape sequence '\:'; see *note Manipulating Hyphenation::. + + 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 *note Blank Line Traps::. Macro packages +may discourage or disable the blank line method of paragraphing in favor +of their own macros. + + 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 +_adjusted_ (see below); however, this behavior can be modified (*note +Leading Space Traps::). Again, macro packages may provide other methods +of producing indented paragraphs. Trailing spaces on text lines are +discarded.(1) (*note Breaking-Footnote-1::) + + 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 'troff' interprets the end of input as +a break. Certain requests also cause breaks, implicitly or explicitly. +This is discussed in *note Manipulating Filling and Adjustment::. + + (1) "Text lines" are defined in *note Requests and Macros::. + +5.1.5 Adjustment +---------------- + +After GNU 'troff' performs an automatic break, it may then "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 *note Manipulating Filling and +Adjustment::. + +5.1.6 Tabs and Leaders +---------------------- + +GNU 'troff' translates input horizontal tab characters ("tabs") and +<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 *note Page Geometry::. Tabs and leaders do not cause +breaks and therefore do not interrupt filling. Below, we use arrows -> +and bullets * to indicate input tabs and leaders, respectively. + + 1 + -> 2 -> 3 * 4 + -> * 5 + => 1 2 3.......4 ........5 + + Tabs and leaders lend themselves to table construction.(1) (*note +Tabs and Leaders-Footnote-1::) The tab and leader glyphs can be +configured, and further facilities for sophisticated table composition +are available; see *note Tabs and Fields::. There are many details to +track when using such low-level features, so most users turn to the +'tbl(1)' preprocessor to lay out tables. + + (1) "Tab" is short for "tabulation", revealing the term's origin as a +spacing mechanism for table arrangement. + +5.1.7 Requests and Macros +------------------------- + +We have now encountered almost all of the syntax there is in the 'roff' +language, with an exception already noted in passing. A "request" is an +instruction to the formatter that occurs after a "control character", +which is recognized at the beginning of an input line. The regular +control character is a dot ('.'). Its counterpart, the "no-break +control character", a neutral apostrophe ('''), 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. If you require a formatted period or apostrophe (closing single +quotation mark) where GNU 'troff' is expecting a control character, +prefix the dot or neutral apostrophe with the dummy character escape +sequence, '\&'. + + An input line beginning with a control character is called a "control +line". Every line of input that is not a control line is a "text +line".(1) (*note Requests and Macros-Footnote-1::) + + Requests often take "arguments", words (separated from the request +name and each other by spaces) that specify details of the action GNU +'troff' is expected to perform. If a request is meaningless without +arguments, it is typically ignored. + + GNU '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.(2) (*note Requests and +Macros-Footnote-2::) + + A "macro" can be thought of as an abbreviation you can define for a +collection of control and text lines. When the macro is "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 +"interpolation".(3) (*note Requests and Macros-Footnote-3::) +Interpolations are handled as soon as they are recognized, and once +performed, a 'roff' formatter scans the replacement for further +requests, macro calls, and escape sequences. + + In 'roff' systems, the 'de' request defines a macro.(4) (*note +Requests and Macros-Footnote-4::) + + .de DATE + 2020-11-14 + .. + +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 'de' request. + + .de NAME ENDNAME + Heywood Jabuzzoff + .ENDNAME + + 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. + + .de END + Big Rip + .. + .de START END + Big Bang + .END + .START + => Big Rip Big Bang + +In the foregoing example, "Big Rip" printed before "Big Bang" because +its macro was _called_ first. Consider what would happen if we dropped +'END' from the '.de START' line and added '..' after '.END'. Would the +order change? + + Let us consider a more elaborate 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 + => Insert tedious regulatory compliance paragraph here. + => + => Approved: 2020-10-05 by D. Kruger, J. Peterman + => + => Insert tedious liability disclaimer paragraph here. + => + => Approved: 2020-10-05 by D. Kruger, J. Peterman + +The above document started with a series of control lines. Three macros +were defined, with a '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 ''..'' marked its end. The text proper began only +after the macros were defined; this is a common pattern. Only the +'NOTICE' macro was called "directly" by the document; 'DATE' and 'BOSS' +were called only by 'NOTICE' itself. Escape sequences were used in +'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 (*note 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 'DATE' and 'BOSS' in the opposite order; +perhaps less obviously, we could also have defined them _after_ +'NOTICE'. "Forward references" like this are acceptable because the +body of a macro definition is not (completely) interpreted, but stored +instead (*note 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 _are_ interpreted. 'roff' +systems also support recursive macro calls, as long as you have a way to +break the recursion (*note Conditionals and Loops::). Maintainable +'roff' documents tend to arrange macro definitions to minimize forward +references. + + (1) The '\<RET>' escape sequence can alter how an input line is +classified; see *note Line Continuation::. + + (2) Argument handling in macros is more flexible but also more +complex. *Note Calling Macros::. + + (3) Some escape sequences undergo interpolation as well. + + (4) GNU 'troff' offers additional ones. *Note Writing Macros::. + +5.1.8 Macro Packages +-------------------- + +Macro definitions can be collected into "macro files", 'roff' input +files designed to produce no output themselves but instead ease the +preparation of other 'roff' documents. There is no syntactical +difference between a macro file and any other '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 "macro package".(1) (*note Macro Packages-Footnote-1::) Macro +packages can be loaded by supplying the '-m' option to GNU 'troff' or a +'groff' front end. Alternatively, a document requiring a macro package +can load it with the 'mso' ("macro source") request. + + (1) Macro files and packages frequently define registers and strings +as well. + +5.1.9 Input Encodings +--------------------- + +The 'groff' command's '-k' option calls the 'preconv' preprocessor to +perform input character encoding conversions. Input to the GNU 'troff' +formatter itself, on the other hand, must be in one of two encodings it +can recognize. + +'cp1047' + The code page 1047 input encoding works only on EBCDIC platforms + (and conversely, the other input encodings don't work with EBCDIC); + the file 'cp1047.tmac' is loaded at startup. + +'latin1' + ISO Latin-1, an encoding for Western European languages, is the + default input encoding on non-EBCDIC platforms; the file + 'latin1.tmac' is loaded at startup. + +Any document that is encoded in ISO 646:1991 (a descendant of USAS +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 Latin-1 document; the standards are interchangeable +in their first 128 code points.(1) (*note Input Encodings-Footnote-1::) + + Other encodings are supported by means of macro packages. + +'latin2' + To use ISO Latin-2, an encoding for Central and Eastern European + languages, invoke '.mso latin2.tmac' at the beginning of your + document or supply '-mlatin2' as a command-line argument to + 'groff'. + +'latin5' + To use ISO Latin-5, an encoding for the Turkish language, invoke + '.mso latin5.tmac' at the beginning of your document or supply + '-mlatin5' as a command-line argument to 'groff'. + +'latin9' + ISO Latin-9 succeeds Latin-1; it includes a Euro sign and better + glyph coverage for French. To use this encoding, invoke + '.mso latin9.tmac' at the beginning of your document or supply + '-mlatin9' as a command-line argument to 'groff'. + + 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 'EUR' +for the Euro sign and '(C)' for the copyright sign. For typesetter +devices, you may need to "mount" fonts that support glyphs required by +the document. *Note Font Positions::. + + Because a Euro glyph was not historically defined in PostScript +fonts, 'groff' comes with a font called 'freeeuro.pfa' that provides the +Euro in several styles. Standard PostScript fonts contain the glyphs +from Latin-5 and Latin-9 that Latin-1 lacks, so these encodings are +supported for the 'ps' and 'pdf' output devices as 'groff' ships, while +Latin-2 is not. + + Unicode supports characters from all other input encodings; the +'utf8' output driver for terminals therefore does as well. The DVI +output driver supports the Latin-2 and Latin-9 encodings if the +command-line option '-mec' is used as well. (2) (*note Input +Encodings-Footnote-2::) + + (1) The _semantics_ of certain punctuation code points have gotten +stricter with the successive standards, a cause of some frustration +among man page writers; see the 'groff_char(7)' man page. + + (2) The DVI output device defaults to using the Computer Modern (CM) +fonts; 'ec.tmac' loads the EC fonts instead, which provide Euro '\[Eu]' +and per mille '\[%0]' glyphs. + +5.1.10 Input Conventions +------------------------ + +Since GNU 'troff' fills text automatically, it is common practice in the +'roff' language to avoid visual composition of text in input files: the +esthetic appeal of the formatted output is what matters. Therefore, +'roff' input should be arranged such that it is easy for authors and +maintainers to compose and develop the document, understand the syntax +of 'roff' requests, macro calls, and preprocessor languages used, and +predict the behavior of the formatter. Several traditions have accrued +in service of these goals. + + * Follow sentence endings in the input with newlines to ease their + recognition (*note 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. + + * Set your text editor's line length to 72 characters or fewer.(1) + (*note Input Conventions-Footnote-1::) 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. + + * Use '\&' after '!', '?', and '.' if they are followed by space, + tab, or newline characters and don't end a sentence. + + * In filled text lines, use '\&' before '.' and ''' if they are + preceded by space, so that reflowing the input doesn't turn them + into control lines. + + * Do not use spaces to perform indentation or align columns of a + table. Leading spaces are reliable when text is not being filled. + + * 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, + '\"', which causes GNU 'troff' to ignore the remainder of the input + line. + + * Use the empty request--a control character followed immediately by + a newline--to visually manage separation of material in input + files. Many of the '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. + + 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 -> indicates a tab character. + + .\" nroff this_file.roff | less + .\" groff -T ps this_file.roff > this_file.ps + ->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 + . + . + + ->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 + + (1) Emacs: 'fill-column: 72'; Vim: 'textwidth=72' + +5.2 Page Geometry +================= + +'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 (*note 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 (*note Page Layout::). + + A device's "resolution" converts practical units like inches or +centimeters to "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 (*note DESC File Format::). + + A "page" is a two-dimensional structure upon which a '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. + + While the formatter (and, later, output driver) is processing a page, +it keeps track of its "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. +Notionally, glyphs are drawn from the text baseline upward and to the +right.(1) (*note Page Geometry-Footnote-1::) The "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. + + 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 '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 "page offset".(2) (*note Page +Geometry-Footnote-2::) 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. "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 vee. + + 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, '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 "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" (*note +Traps::); moreover, all but the simplest page layouts tend to have +headers and footers, or at least bear vertical margins larger than one +vee. + + (1) 'groff' does not yet support right-to-left scripts. + + (2) 'groff''s terminal output devices have page offsets of zero. + +5.3 Measurements +================ + +The formatter sometimes requires the input of numeric parameters to +specify measurements. These are specified as integers or decimal +fractions with an optional "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 +'10.5p', '11i', and '3.c'. + + Measurements are scaled by the scaling unit and stored internally +(with any fractional part discarded) in basic units. The device +resolution can therefore be obtained by storing a value of '1i' to a +register. The only constraint on the basic unit is that it is at least +as small as any other unit. + +'u' + Basic unit. + +'i' + Inch; defined as 2.54 centimeters. + +'c' + Centimeter; a centimeter is about 0.3937 inches. + +'p' + Point; a typesetter's unit used for measuring type size. There are + 72 points to an inch. + +'P' + Pica; another typesetter's unit. There are 6 picas to an inch and + 12 points to a pica. + +'s' +'z' + *Note Using Fractional Type Sizes::, for a discussion of these + units. + +'f' + GNU '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. *Note Colors::, for usage. + + 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. + +'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 'M'. + +'n' + En; an en is one-half em. + +'v' + Vee; recall *note Page Geometry::. + +'M' + Hundredth of an em. + +5.3.1 Motion Quanta +------------------- + +An output device's basic unit 'u' is not necessarily its smallest +addressable length; '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 "motion quanta". +Measurements are rounded to applicable motion quanta. Half-quantum +fractions round toward zero. + + -- Register: \n[.H] + -- Register: \n[.V] + These read-only registers interpolate the horizontal and vertical + motion quanta, respectively, of the output device in basic units. + + For example, we might draw short baseline rules on a terminal device +as follows. *Note Drawing Geometric Objects::. + + .tm \n[.H] + error-> 24 + .nf + \l'36u' 36u + \l'37u' 37u + => _ 36u + => __ 37u + +5.3.2 Default Units +------------------- + +A general-purpose register (one created or updated with the 'nr' +request; see *note 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 'troff''s use of integer arithmetic +should also be kept in mind (*note Numeric Expressions::). + + The 'll' request interprets its argument in ems by default. Consider +several attempts to set a line length of 3.5 inches when the type size +is 10 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. + + .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) + +The safest way to specify measurements is to attach a scaling unit. To +multiply or divide by a dimensionless quantity, use 'u' as its scaling +unit. + +5.4 Numeric Expressions +======================= + +A "numeric expression" evaluates to an integer: it can be as simple as a +literal '0' or it can be a complex sequence of register and string +interpolations interleaved with measurements and operators. + + GNU 'troff' provides a set of mathematical and logical operators +familiar to programmers--as well as some unusual ones--but supports only +integer arithmetic.(1) (*note Numeric Expressions-Footnote-1::) 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.(2) (*note Numeric Expressions-Footnote-2::) + + Arithmetic infix operators perform a function on the numeric +expressions to their left and right; they are '+' (addition), '-' +(subtraction), '*' (multiplication), '/' (truncating division), and '%' +(modulus). "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. + + Arithmetic unary operators operate on the numeric expression to their +right; they are '-' (negation) and '+' (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. + + .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] + => T=1 U=2 V=-2 W=-2 X=1 Y=-1 Z=1 + +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 A and a divisor B, a quotient Q formed by '(a +/ b)' and a remainder R by '(a % b)', then qb + r = a. + + GNU 'troff''s scaling operator, used with parentheses as '(C;E)', +evaluates a numeric expression E using C as the default scaling unit. +If C is omitted, scaling units are ignored in the evaluation of 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. + + .\" Indent by amount given in first argument; assume ens. + .de Indent + . in (n;\\$1) + .. + +Without the scaling operator, the foregoing macro would, if called with +a unitless argument, cause indentation by the 'in' request's default +scaling unit (ems). The result would be twice as much indentation as +expected. + + GNU 'troff' also provides a pair of operators to compute the extrema +of two operands: '>?' (maximum) and '<?' (minimum). + + .nr slots 5 + .nr candidates 3 + .nr salaries (\n[slots] <? \n[candidates]) + Looks like we'll end up paying \n[salaries] salaries. + => Looks like we'll end up paying 3 salaries. + + Comparison operators comprise '<' (less than), '>' (greater than), +'<=' (less than or equal), '>=' (greater than or equal), and '=' +(equal). '==' is a synonym for '='. When evaluated, a comparison is +replaced with '0' if it is false and '1' if true. In the 'roff' +language, positive values are true, others false. + + We can operate on truth values with the logical operators '&' +(logical conjunction or "and") and ':' (logical disjunction or "or"). +They evaluate as comparison operators do. + + A logical complementation ("not") operator, '!', works only within +'if', 'ie', and 'while' requests. Furthermore, '!' 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 'number' category (*note Warnings::), and its expression +evaluates false. This unfortunate limitation maintains compatibility +with AT&T 'troff'. Test a numeric expression for falsity by comparing +it to a false value.(3) (*note Numeric Expressions-Footnote-3::) + + .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 '!' + => B: X is true, Y is false + + The 'roff' language has no operator precedence: expressions are +evaluated strictly from left to right, in contrast to schoolhouse +arithmetic. Use parentheses '(' ')' to impose a desired precedence upon +subexpressions. + + .nr X 3+5*4 + .nr Y (3+5)*4 + .nr Z 3+(5*4) + X=\n[X] Y=\n[Y] Z=\n[Z] + => X=32 Y=32 Z=23 + + For many requests and escape sequences that cause motion on the page, +the unary operators '+' and '-' 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. + + '+' and '-' are also treated differently by the following requests +and escape sequences: 'bp', 'in', 'll', 'lt', 'nm', 'nr', 'pl', 'pn', +'po', 'ps', 'pvs', 'rt', 'ti', '\H', '\R', and '\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. *Note Setting +Registers::, for examples. + + A leading '|' 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 _input_ line. By default, tab stops reckon movements +in this way. Most escape sequences do not; '|' tells them to do so. + + Mind the \h'1.2i'gap. + .br + Mind the \h'|1.2i'gap. + .br + Mind the + \h'|1.2i'gap. + => Mind the gap. + => Mind the gap. + => Mind the gap. + + One use of this feature is to define macros whose scope is limited to +the output they format. + + .\" underline word $1 with trailing punctuation $2 + .de Underline + . nop \\$1\l'|0\[ul]'\\$2 + .. + Typographical emphasis is best used + .Underline sparingly . + +In the above example, '|0' specifies a negative motion from the current +position (at the end of the argument just emitted, '\$1') to the +beginning of the input line. Thus, the '\l' escape sequence in this +case draws a line from right to left. A macro call occurs at the +beginning of an input line;(4) (*note Numeric Expressions-Footnote-4::) +if the '|' 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 'ps' output device, it underlines +the period. + + For vertical motions, the '|' operator specifies a distance from the +first text baseline on the page or in the current diversion,(5) (*note +Numeric Expressions-Footnote-5::) using the current vertical spacing. + + A + .br + B \Z'C'\v'|0'D + => A D + => B C + + In the foregoing example, we've used the '\Z' escape sequence (*note +Page Motions::) to restore the drawing position after formatting 'C', +then moved vertically to the first text baseline on the page. + + -- Escape sequence: \B'anything' + Interpolate 1 if ANYTHING is a valid numeric expression, and 0 + otherwise. The delimiter need not be a neutral apostrophe; see + *note Delimiters::. + + You might use '\B' along with the 'if' request to filter out invalid +macro or string arguments. *Note Conditionals and Loops::. + + .\" Indent by amount given in first argument; assume ens. + .de Indent + . if \B'\\$1' .in (n;\\$1) + .. + + A register interpolated as an operand in a numeric expression must +have an Arabic format; luckily, this is the default. *Note Assigning +Register Formats::. + + Because spaces separate arguments to requests, spaces are not allowed +in numeric expressions unless the (sub)expression containing them is +surrounded by parentheses. *Note Invoking Requests::, and *note +Conditionals and Loops::. + + .nf + .nr a 1+2 + 2+1 + \na + error-> expected numeric expression, got a space + => 3 + .nr a 1+(2 + 2)+1 + \na + => 6 + + The 'nr' request (*note Setting Registers::) expects its second and +optional third arguments to be numeric expressions; a bare '+' does not +qualify, so our first attempt got a warning. + + (1) Provision is made for interpreting and reporting decimal +fractions in certain cases. + + (2) If that's not enough, see the 'groff_tmac(5)' man page for the +'62bit.tmac' macro package. + + (3) *Note Conditionals and Loops::. + + (4) Control structure syntax creates an exception to this rule, but +is designed to remain useful: recalling our example, '.if 1 .Underline +this' would underline only "this", precisely. *Note Conditionals and +Loops::. + + (5) *Note Diversions::. + +5.5 Identifiers +=============== + +An "identifier" labels a GNU '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. An ordinary character is an input +character that is not the escape character, a leader, tab, newline, or +invalid as GNU 'troff' input. + + Invalid input characters are a subset of control characters (from the +sets "C0 Controls" and "C1 Controls" as Unicode describes them). When +GNU 'troff' encounters one in an identifier, it produces a warning in +category 'input' (*note Warnings::). They are removed during +interpretation: an identifier 'foo', followed by an invalid character +and then 'bar', is processed as 'foobar'. + + On a machine using the ISO 646, 8859, or 10646 character encodings, +invalid input characters are '0x00', '0x08', '0x0B', '0x0D'-'0x1F', and +'0x80'-'0x9F'. On an EBCDIC host, they are '0x00'-'0x01', '0x08', +'0x09', '0x0B', '0x0D'-'0x14', '0x17'-'0x1F', and '0x30'-'0x3F'.(1) +(*note Identifiers-Footnote-1::) Some of these code points are used by +GNU 'troff' internally, making it non-trivial to extend the program to +accept UTF-8 or other encodings that use characters from these +ranges.(2) (*note Identifiers-Footnote-2::) + + Thus, the identifiers 'br', 'PP', 'end-list', 'ref*normal-print', +'|', '@_', and '!"#$%'()*+,-./' are all valid. Discretion should be +exercised to prevent confusion. Identifiers starting with '(' or '[' +require care. + + .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] + => A:2+3=1 B:2+3=5 C:2+3=5 + +An identifier with a closing bracket (']') in its name can't be accessed +with bracket-form escape sequences that expect an identifier as a +parameter. For example, '\[foo]]' accesses the glyph 'foo', followed by +']' in whatever the surrounding context is, whereas '\C'foo]'' formats a +glyph named 'foo]'. Similarly, the identifier '(' can't be interpolated +_except_ with bracket forms. + + If you begin a macro, string, or diversion name with either of the +characters '[' or ']', you foreclose use of the 'grefer' preprocessor, +which recognizes '.[' and '.]' as bibliographic reference delimiters. + + -- Escape sequence: \A'anything' + Interpolate 1 if ANYTHING is a valid identifier, and 0 otherwise. + The delimiter need not be a neutral apostrophe; see *note + Delimiters::. Because invalid input characters are removed (see + above), invalid identifiers are empty or contain spaces, tabs, or + newlines. + + You can employ '\A' to validate a macro argument before using it to + construct another escape sequence or identifier. + + .\" 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->nt" trash garbage \" ignored + .init-coordinate-pair point trash garbage \" ignored + => The center is at (5, 10). + + In this example, we also validated the numeric arguments; the + registers 'point!x' and 'point!y' remain undefined. *Note Numeric + Expressions:: for the '\B' escape sequence. + + How GNU '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 'troff' emits a +warning in category 'mac', defines it as empty, and interpolates +nothing. If the identifier is interpreted as a register, GNU 'troff' +emits a warning in category 'reg', initializes it to zero, and +interpolates that value. *Note Warnings::, *note Interpolating +Registers::, and *note Strings::. Attempting to use an undefined +typeface, special character, color, character class, environment, or +stream generally provokes an error diagnostic. + + Identifiers for requests, macros, strings, and diversions share one +name space; special characters and character classes another. No other +object types do. + + .de xxx + . nop foo + .. + .di xxx + bar + .br + .di + . + .xxx + => bar + +The foregoing example shows that GNU 'troff' reuses the identifier +'xxx', changing it from a macro to a diversion. No warning is emitted, +and the previous contents of 'xxx' are lost. + + (1) Historically, control characters like ASCII STX, ETX, and BEL +(<Control+B>, <Control+C>, and <Control+G>) have been observed in '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 (*note Operators in +Conditionals::). We discourage this expedient; in GNU 'troff' it is +unnecessary (outside of compatibility mode) because delimited arguments +are parsed at a different input level than the surrounding context. +*Note Implementation Differences::. + + (2) Consider what happens when a C1 control '0x80'-'0x9F' is +necessary as a continuation byte in a UTF-8 sequence. + +5.6 Formatter Instructions +========================== + +To support documents that require more than filling, automatic line +breaking and hyphenation, adjustment, and supplemental inter-sentence +space, the 'roff' language offers two means of embedding instructions to +the formatter. + + One is a "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. + + The other is an "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. + +5.6.1 Control Characters +------------------------ + +The mechanism of using 'roff''s control characters to invoke requests +and call macros was introduced in *note 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 *note +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. +*Note Manipulating Filling and Adjustment::. + + The control '.' and no-break control ''' characters can each be +changed to any ordinary character(1) (*note Control +Characters-Footnote-1::) with the 'cc' and 'c2' requests, respectively. + + -- Request: .cc [o] + Recognize the ordinary character O as the control character. If O + is absent or invalid, the default control character '.' is + selected. The identity of the control character is associated with + the environment (*note Environments::). + + -- Request: .c2 [o] + Recognize the ordinary character O as the no-break control + character. If O is absent or invalid, the default no-break control + character ''' is selected. The identity of the no-break control + character is associated with the environment (*note + Environments::). + + When writing a macro, you might wish to know which control character +was used to call it. + + -- Register: \n[.br] + This read-only register interpolates 1 if the currently executing + macro was called using the normal control character and 0 + otherwise. If a macro is interpolated as a string, the '.br' + register's value is inherited from the context of the string + interpolation. *Note Strings::. + + Use this register to reliably intercept requests that imply breaks. + + .als bp*orig bp + .de bp + . ie \\n[.br] .bp*orig + . el 'bp*orig + .. + + Testing the '.br' register outside of a macro definition makes no + sense. + + (1) Recall *note Identifiers::. + +5.6.2 Invoking Requests +----------------------- + +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 'rm' request makes it unavailable. The 'als' +request can alias requests, permitting them to be wrapped or +non-destructively replaced. *Note Strings::. + + 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 'troff' does +not allow tabs for argument separation.(1) (*note Invoking +Requests-Footnote-1::) + + Generally, a space _within_ a request argument is not relevant, not +meaningful, or is supported by bespoke provisions, as with the 'tl' +request's delimiters (*note Page Layout::). Some requests, like 'ds', +interpret the remainder of the control line as a single argument. *Note +Strings::. + + Spaces and tabs immediately after a control character are ignored. +Commonly, authors structure the source of documents or macro files with +them. + + .de center + . if \\n[.br] \ + . br + . ce \\$1 + .. + . + . + .de right-align + .->if \\n[.br] \ + .->->br + .->rj \\$1 + .. + + If you assign an empty blank line trap, you can separate macro +definitions (or any input lines) with blank lines. + + .de do-nothing + .. + .blm do-nothing \" activate blank line trap + + .de center + . if \\n[.br] \ + . br + . ce \\$1 + .. + + + .de right-align + .->if \\n[.br] \ + .->->br + .->rj \\$1 + .. + + .blm \" deactivate blank line trap + + *Note Blank Line Traps::. + + (1) In compatibility mode, a space is not necessary after a request +or macro name of two characters' length. Also, Plan 9 'troff' allows +tabs to separate arguments. + +5.6.3 Calling 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 'mac' +is emitted. Calling an undefined macro _does_ end a macro definition +naming it as its end macro (*note Writing Macros::). + + To embed spaces _within_ a macro argument, enclose the argument in +neutral double quotes '"'. Horizontal motion escape sequences are +sometimes a better choice for arguments to be formatted as text. + + Consider calls to a hypothetical section heading macro 'uh'. + + .uh The Mouse Problem + .uh "The Mouse Problem" + .uh The\~Mouse\~Problem + .uh The\ Mouse\ Problem + +The first line calls 'uh' with three arguments: 'The', 'Mouse', and +'Problem'. The remainder call the 'uh' macro with one argument, 'The +Mouse Problem'. The last solution, using escaped spaces, can be found +in documents prepared for AT&T 'troff'. It can cause surprise when text +is adjusted, because '\<SP>' inserts a _fixed-width_, non-breaking +space. GNU 'troff''s '\~' escape sequence inserts an adjustable, +non-breaking space.(1) (*note Calling Macros-Footnote-1::) + + The foregoing raises the question of how to embed neutral double +quotes or backslashes in macro arguments when _those_ characters are +desired as literals. In GNU 'troff', the special character escape +sequence '\[rs]' produces a backslash and '\[dq]' a neutral double +quote. + + In GNU 'troff''s AT&T compatibility mode, these characters remain +available as '\(rs' and '\(dq', respectively. AT&T 'troff' did not +consistently define these special characters, but its descendants can be +made to support them. *Note 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. *Note Using Escape +Sequences::. Otherwise, you must escape the escape character repeatedly +to a context-dependent extent. *Note Copy Mode::. + + For the (neutral) double quote, you have recourse to an obscure +syntactical feature of AT&T '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.(2) (*note Calling Macros-Footnote-2::) In the +argument list to a macro, a double quote that _isn't_ preceded by a +space _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. + + .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 + + Apart from the complexity of the rules, this traditional solution has +the disadvantage that double quotes don't survive repeated argument +expansion in AT&T 'troff' or GNU 'troff''s compatibility mode. This can +frustrate efforts to pass such arguments intact through multiple macro +calls. + + .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 + + Outside of compatibility mode, GNU 'troff' doesn't exhibit this +problem because it tracks the nesting depth of interpolations. *Note +Implementation Differences::. + + (1) '\~' is fairly portable; see *note Other Differences::. + + (2) 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. + +5.6.4 Using 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. An escape sequence is introduced by the +escape character, a backslash '\' (but see the '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 _only_ an +arbitrary-length argument. In the former scheme, a one-character +argument follows the function character immediately, an opening +parenthesis '(' introduces a two-character argument (no closing +parenthesis is used), and an argument of arbitrary length is enclosed in +brackets '[]'. In the latter scheme, the user selects a delimiter +character. A few escape sequences are idiosyncratic, and support both +of the foregoing conventions ('\s'), designate their own termination +sequence ('\?'), consume input until the next newline ('\!', '\"', +'\#'), or support an additional modifier character ('\s' again, and +'\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 'escape' warning category, which is not enabled by +default) and the following character is processed normally. + + $ 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' + => I have 12 white elephants, said P. Pseudo Pachyderm. + + 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. + + .ds family C\" Courier + .ds style I\" oblique + Choice a typeface \f(\*[family]\*[style]wisely. + => Choose a typeface wisely. + +In the above, the syntax form '\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 'family' and 'style' interpolate one character each.(1) +(*note Using Escape Sequences-Footnote-1::) + + 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. + + -- Escape sequence: \e + Interpolate the escape character. + + The '\[rs]' special character escape sequence formats a backslash +glyph. In macro and string definitions, the input sequences '\\' and +'\E' defer interpretation of escape sequences. *Note Copy Mode::. + + -- Request: .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. + + -- Request: .ec [o] + Recognize the ordinary character O as the escape character. If O + is absent or invalid, the default escape character '\' is selected. + + 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. *Note Writing Macros::. This technique is not +available if your macro needs to interpolate values at the time it is +_defined_--but many do not. + + .\" 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 + + -- Request: .ecs + -- Request: .ecr + The 'ecs' request stores the escape character for recall with + 'ecr'. 'ecr' sets the escape character to '\' if none has been + saved. + + Use these requests together to temporarily change the escape + character. + + Using a different escape character, or disabling it, when calling +macros not under your control will likely cause errors, since GNU +'troff' has no mechanism to "intern" macros--that is, to convert a macro +definition into a form independent of its representation.(2) (*note +Using Escape Sequences-Footnote-2::) When a macro is called, its +contents are interpreted literally. + + (1) The omission of spaces before the comment escape sequences is +necessary; see *note Strings::. + + (2) TeX does have such a mechanism. + +5.6.5 Delimiters +---------------- + +Some escape sequences that require parameters use delimiters. The +neutral apostrophe ''' is a popular choice and shown in this document. +The neutral double quote '"' 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. + + \l'1.5i\[bu]' \" draw 1.5 inches of bullet glyphs + + The following escape sequences don't take arguments and thus are +allowed as delimiters: '\<SP>', '\%', '\|', '\^', '\{', '\}', '\'', +'\`', '\-', '\_', '\!', '\?', '\)', '\/', '\,', '\&', '\:', '\~', '\0', +'\a', '\c', '\d', '\e', '\E', '\p', '\r', '\t', and '\u'. However, +using them this way is discouraged; they can make the input confusing to +read. + + A few escape sequences, '\A', '\b', '\o', '\w', '\X', and '\Z', +accept a newline as a delimiter. Newlines that serve as delimiters +continue to be recognized as input line terminators. + + A caf\o + e\(aa + in Paris + => A café in Paris + +Use of newlines as delimiters in escape sequences is also discouraged. + + Finally, the escape sequences '\D', '\h', '\H', '\l', '\L', '\N', +'\R', '\s', '\S', '\v', and '\x' prohibit many delimiters. + + * the numerals '0'-'9' and the decimal point '.' + + * the (single-character) operators '+-/*%<>=&:()' + + * the space and tab characters + + * any escape sequences other than '\%', '\:', '\{', '\}', '\'', '\`', + '\-', '\_', '\!', '\/', '\c', '\e', and '\p' + + Delimiter syntax is complex and flexible primarily for historical +reasons; the foregoing restrictions need be kept in mind mainly when +using 'groff' in AT&T compatibility mode. GNU '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, ''' works fine. *Note Implementation Differences::. + + $ 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. + + We see here that in compatibility mode, the part of the argument +after the ''' delimiter escapes from its context and, if nefariously +crafted, influences the computation of the WD register's value in a +surprising way. + +5.7 Comments +============ + +One of the most common forms of escape sequence is the comment.(1) +(*note Comments-Footnote-1::) + + -- Escape sequence: \" + 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. 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 'troff'. This affects only the 'ds' and 'as' requests and + their variants. + + 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. + + A comment on a line by itself is treated as a blank line, because + after eliminating the comment, that is all that remains. + + Test + \" comment + Test + => Test + => + => Test + + To avoid this, it is common to combine the empty request with the + comment escape sequence as '.\"', causing the input line to be + ignored. + + Another commenting scheme sometimes seen is three consecutive + single quotes (''''') at the beginning of a line. This works, but + GNU 'troff' emits a warning diagnostic (if enabled) about an + undefined macro (namely ''''). + + -- Escape sequence: \# + Start a comment; everything up to and including the next newline is + ignored. This 'groff' extension was introduced to avoid the + problems described above. + + Test + \# comment + Test + => Test Test + + -- Request: .ig [end] + Ignore input until, in the current conditional block (if any),(2) + (*note Comments-Footnote-2::) the macro END is called at the start + of a control line, or the control line '..' is encountered if END + is not specified. 'ig' is parsed as if it were a macro definition, + but its contents are discarded, not stored.(3) (*note + Comments-Footnote-3::) + + 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 + => handfasting + + (1) This claim may be more aspirational than descriptive. + + (2) *Note Conditional Blocks::. + + (3) Exception: auto-incrementing registers defined outside the +ignored region _will_ be modified if interpolated with '\n±' inside it. +*Note Auto-increment::. + +5.8 Registers +============= + +In the 'roff' language, numbers can be stored in "registers". Many +built-in registers exist, supplying anything from the date to details of +formatting parameters. You can also define your own. *Note +Identifiers::, for information on constructing a valid name for a +register. + +5.8.1 Setting Registers +----------------------- + +Define registers and update their values with the 'nr' request or the +'\R' escape sequence. + + -- Request: .nr ident value + -- Escape sequence: \R'ident value' + Set register IDENT to VALUE. If IDENT doesn't exist, GNU 'troff' + creates it. In the '\R' escape sequence, the delimiter need not be + a neutral apostrophe; see *note Delimiters::. It also does not + produce an input token in GNU 'troff'. *Note Gtroff Internals::. + + .nr a (((17 + (3 * 4))) % 4) + \n[a] + .\R'a (((17 + (3 * 4))) % 4)' + \n[a] + => 1 1 + + (Later, we will discuss additional forms of 'nr' and '\R' that can + change a register's value after it is dereferenced but before it is + interpolated. *Note Auto-increment::.) + + The complete transparency of '\R' can cause surprising effects if + you use registers like '.k', which get evaluated at the time they + are accessed. + + .ll 1.6i + . + aaa bbb ccc ddd eee fff ggg hhh\R':k \n[.k]' + .tm :k == \n[:k] + => :k == 126950 + . + .br + . + aaa bbb ccc ddd eee fff ggg hhh\h'0'\R':k \n[.k]' + .tm :k == \n[:k] + => :k == 15000 + + If you process this with the PostScript device ('-Tps'), there will + be a line break eventually after 'ggg' in both input lines. + However, after processing the space after 'ggg', the partially + collected line is not overfull yet, so GNU 'troff' continues to + collect input until it sees the space (or in this case, the + newline) after 'hhh'. At this point, the line is longer than the + line length, and the line gets broken. + + In the first input line, since the '\R' escape sequence leaves no + traces, the check for the overfull line hasn't been done yet at the + point where '\R' gets handled, and you get a value for the '.k' + register that is even greater than the current line length. + + In the second input line, the insertion of '\h'0'' to cause a + zero-width motion forces GNU 'troff' to check the line length, + which in turn causes the start of a new output line. Now '.k' + returns the expected value. + + 'nr' and '\R' each have two additional special forms to increment or +decrement a register. + + -- Request: .nr ident +value + -- Request: .nr ident -value + -- Escape sequence: \R'ident +value' + -- Escape sequence: \R'ident -value' + Increment (decrement) register IDENT by VALUE. In the '\R' escape + sequence, the delimiter need not be a neutral apostrophe; see *note + Delimiters::. + + .nr a 1 + .nr a +1 + \na + => 2 + + A leading minus sign in 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 'troff' to interpret '-' as a negation or minus, + rather than decrementation, operator: enclose it with its operand + in parentheses or subtract it from zero. + + .nr a 7 + .nr b 3 + .nr a -\nb + \na + => 4 + .nr a (-\nb) + \na + => -3 + .nr a 0-\nb + \na + => -3 + + If a register's prior value does not exist (the register was + undefined), an increment or decrement is applied as if to 0. + + -- Request: .rr ident + Remove register IDENT. If 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 'aln', if + any. + + -- Request: .rnn ident1 ident2 + Rename register IDENT1 to IDENT2. If IDENT1 doesn't exist, the + request is ignored. Renaming a built-in register does not + otherwise alter its properties. + + -- Request: .aln new old + Create an alias NEW for an existing register OLD, causing the names + to refer to the same stored object. If OLD is undefined, a warning + in category 'reg' is produced and the request is ignored. *Note + Warnings::, for information about the enablement and suppression of + warnings. + + To remove a register alias, invoke 'rr' on its name. A register's + contents do not become inaccessible until it has no more names. + +5.8.2 Interpolating Registers +----------------------------- + +Register contents are interpolated with the '\n' escape sequence. + + -- Escape sequence: \ni + -- Escape sequence: \n(id + -- Escape sequence: \n[ident] + Interpolate register with name IDENT (one-character name I, + two-character name ID). '\n' is interpreted even in copy mode + (*note Copy Mode::). If the register is undefined, it is created + and assigned a value of '0', that value is interpolated, and a + warning in category 'reg' is emitted. *Note Warnings::, for + information about the enablement and suppression of warnings. + + .nr a 5 + .nr as \na+\na + \n(as + => 10 + + .nr a1 5 + .nr ab 6 + .ds str b + .ds num 1 + \n[a\n[num]] + => 5 + \n[a\*[str]] + => 6 + +5.8.3 Auto-increment +-------------------- + +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 'nr' request, and a special +interpolation syntax is used to alter and then retrieve the register's +value. Together, these features are called "auto-increment".(1) (*note +Auto-increment-Footnote-1::) + + -- Request: .nr ident value incr + Set register IDENT to VALUE and its auto-incrementation amount to + to INCR. The '\R' escape sequence doesn't support an INCR + argument. + + Auto-incrementation is not _completely_ automatic; the '\n' escape +sequence in its basic form never alters the value of a register. To +apply auto-incrementation to a register, interpolate it with '\n±'. + + -- Escape sequence: \n+i + -- Escape sequence: \n-i + -- Escape sequence: \n+(id + -- Escape sequence: \n-(id + -- Escape sequence: \n+[ident] + -- Escape sequence: \n-[ident] + Increment or decrement IDENT (one-character name I, two-character + name ID) by the register's auto-incrementation value and then + interpolate the new register value. If IDENT has no + auto-incrementation value, interpolate as with '\n'. + + .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] + => 1, 2, 3, 4, 5 + => -5, -10, -15, -20, -25 + => -2, -4, -6, -8, -10 + + 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 '0' to +disable auto-incrementation of the register. + + (1) A negative auto-increment can be considered an "auto-decrement". + +5.8.4 Assigning Register Formats +-------------------------------- + +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. + + -- Request: .af reg fmt + Use number format FMT when interpolating register REG. Valid + number formats are as follows. + + '0...' + Arabic numerals 0, 1, 2, and so on. Any decimal digit is + equivalent to '0'; the formatter merely counts the digits + specified. Multiple Arabic numerals in 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 '00' + interpolates values 1, 2, 3 as '01', '02', '03'. The default + format for all writable registers is '0'. + + 'I' + Uppercase Roman numerals: 0, I, II, III, IV, ... + + 'i' + Lowercase Roman numerals: 0, i, ii, iii, iv, ... + + 'A' + Uppercase letters: 0, A, B, C, ..., Z, AA, AB, ... + + 'a' + Lowercase letters: 0, a, b, c, ..., z, aa, ab, ... + + Omitting FMT causes a warning in category 'missing'. *Note + Warnings::, for information about the enablement and suppression of + warnings. Specifying an unrecognized format is an error. + + Zero values are interpolated as '0' in non-Arabic formats. + Negative quantities are prefixed with '-' irrespective of format. + In Arabic formats, the sign supplements the field width. If REG + doesn't exist, it is created with a zero value. + + .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 + => 10, X, -010, -j + + The representable extrema in the 'i' and 'I' formats correspond to + Arabic ±39,999. GNU 'troff' uses 'w' and 'z' to represent 5,000 + and 10,000 in Roman numerals, respectively, following the + convention of AT&T 'troff'--currently, the correct glyphs for Roman + numerals five thousand ('U+2181') and ten thousand ('U+2182') are + not used. + + 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. + + -- Escape sequence: \gr + -- Escape sequence: \g(rg + -- Escape sequence: \g[reg] + Interpolate the format of the register REG (one-character name R, + two-character name RG). Zeroes represent Arabic formats. If REG + is not defined, REG is not created and nothing is interpolated. + '\g' is interpreted even in copy mode (*note Copy Mode::). + + GNU 'troff' interprets only Arabic numerals. The Roman numeral or +alphabetic formats cannot be used as operands to arithmetic operators in +expressions (*note Numeric Expressions::). For instance, it may be +desirable to test the page number independently of its format. + + .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 + +5.8.5 Built-in Registers +------------------------ + +Predefined registers whose identifiers start with a dot are read-only. +Many are Boolean-valued, interpolating a true or false value testable +with the 'if', 'ie', or 'while' requests. Some read-only registers are +string-valued, meaning that they interpolate text. + + *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 *note 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 'troff', or obtain information about the formatter's command-line +options, processing progress, or the operating environment. + +'\n[.A]' + Approximate output is being formatted (Boolean-valued); see 'groff' + '-a' option (*note Groff Options::). + +'\n[.c]' +'\n[c.]' + Input line number. 'c.' is a writable synonym, affecting + subsequent interpolations of both '.c' and 'c.'. + +'\n[.F]' + Name of input file (string-valued). + +'\n[.g]' + Always true in GNU 'troff' (Boolean-valued). Documents can use + this to ask the formatter if it claims 'groff' compatibility. + +'\n[.P]' + Output page selection status (Boolean-valued); see 'groff' '-o' + option (*note Groff Options::). + +'\n[.R]' + Count of available unused registers; always 10,000 in GNU + 'troff'.(1) (*note Built-in Registers-Footnote-1::) + +'\n[.T]' + Indicator of output device selection (Boolean-valued); see 'groff' + '-T' option (*note Groff Options::). + +'\n[.U]' + Unsafe mode enablement status (Boolean-valued); see 'groff' '-U' + option (*note Groff Options::). + +'\n[.x]' + Major version number of the running GNU 'troff' formatter. For + example, if the version number is 1.23.0, then '.x' contains '1'. + +'\n[.y]' + Minor version number of the running GNU 'troff' formatter. For + example, if the version number is 1.23.0, then '.y' contains '23'. + +'\n[.Y]' + Revision number of the running GNU 'troff' formatter. For example, + if the version number is 1.23.0, then '.Y' contains '0'. + +'\n[$$]' + Process identifier (PID) of the GNU 'troff' program in its + operating environment. + + Date- and time-related registers are set per the local time as +determined by 'localtime(3)' when the formatter launches. This +initialization can be overridden by 'SOURCE_DATE_EPOCH' and 'TZ'; see +*note Environment::. + +'\n[seconds]' + Count of seconds elapsed in the minute (0-60). + +'\n[minutes]' + Count of minutes elapsed in the hour (0-59). + +'\n[hours]' + Count of hours elapsed since midnight (0-23). + +'\n[dw]' + Day of the week (1-7; 1 is Sunday). + +'\n[dy]' + Day of the month (1-31). + +'\n[mo]' + Month of the year (1-12). + +'\n[year]' + Gregorian year. + +'\n[yr]' + Gregorian year minus 1900. This register is incorrectly documented + in the AT&T 'troff' manual as storing the last two digits of the + current year. That claim stopped being true in 2000. Old 'troff' + input that looks like: + + '\" The year number is a surprise after 1999. + This document was formatted in 19\n(yr. + + can be corrected to: + + This document was formatted in \n[year]. + + or, for portability across many 'roff' programs, to the following. + + .nr y4 1900+\n(yr + This document was formatted in \n(y4. + + (1) GNU 'troff' dynamically allocates memory for as many registers as +required. + +5.9 Manipulating Filling and Adjustment +======================================= + +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 *note Breaking::. +The 'br' request likewise causes a break. Several other requests imply +breaks: 'bp', 'ce', 'cf', 'fi', 'fl', 'in', 'nf', 'rj', 'sp', 'ti', and +'trf'. If the no-break control character is used with any of these +requests, GNU 'troff' suppresses the break; instead the requested +operation takes effect at the next break. ''br' does nothing. + + .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. + => This line is normally filled and adjusted. + => A line's alignment is decided when it is output. + => This line returns to normal filling and adjustment. + +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 "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 "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. +*Note End-of-input Traps::. + + -- Request: .br + Break the line: emit any pending output line without adjustment. + + foo bar + .br + baz + 'br + qux + => foo bar + => baz qux + + Sometimes you want to prevent a break within a phrase or between a +quantity and its units. + + -- Escape sequence: \~ + 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. + + Set the output speed to\~1. + There are 1,024\~bytes in 1\~KiB. + J.\~F.\~Ossanna wrote the original CSTR\~#54. + + By default, GNU 'troff' fills text and adjusts it to reach the output +line length. The 'nf' request disables filling; the 'fi' request +reënables it. + + -- Request: .fi + -- Register: \n[.u] + Enable filling of output lines; a pending output line is broken. + The read-only register '.u' is set to 1. The filling enablement + status, sometimes called "fill mode", is associated with the + environment (*note Environments::). *Note Line Continuation::, for + interaction with the '\c' escape sequence. + + -- Request: .nf + Disable filling of output lines: the output line length (*note 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 '.u' is set to 0. The filling + enablement status is associated with the environment (*note + Environments::). See *note Line Continuation::, for interaction + with the '\c' escape sequence. + + -- Request: .ad [mode] + -- Register: \n[.j] + Enable output line adjustment in MODE, taking effect when the + pending (or next) output line is broken. Adjustment is suppressed + when filling is. MODE can have one of the following values. + + 'b' + 'n' + Adjust "normally": if the output line does not consume the + distance between the indentation and the configured output + line length, GNU '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 'troff' default. + + 'c' + Center filled text. Contrast with the 'ce' request, which + centers text _without_ filling it. + + 'l' + Align text to the left without adjusting it. + + 'r' + Align text to the right without adjusting it. + + MODE can also be a value previously stored in the '.j' register. + Using 'ad' without an argument is the same as '.ad \n[.j]'; unless + filling is disabled, GNU 'troff' resumes adjusting lines in the + same way it did before adjustment was disabled by invocation of the + 'na' request. + + The adjustment mode and enablement status are encoded in the + read-only register '.j'. These parameters are associated with the + environment (*note Environments::). + + The value of '.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. + + .ll 48n + .de AD + . br + . ad \\$1 + .. + .de NA + . br + . na + .. + left + .AD r + .nr ad \n(.j + right + .AD c + center + .NA + left + .AD + center + .AD \n(ad + right + => left + => right + => center + => left + => center + => right + + -- Request: .na + Disable output line adjustment. This produces the same output as + left-alignment, but the value of the adjustment mode register '.j' + is altered differently. The adjustment mode and enablement status + are associated with the environment (*note Environments::). + + -- Request: .brp + -- Escape sequence: \p + Break, adjusting the line per the current adjustment mode. '\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 'troff' doesn't have a sophisticated paragraph-building + algorithm, as TeX has, for example. Instead, GNU 'troff' fills and + adjusts a paragraph line by line. + + .ll 4.5i + This is an uninteresting sentence. + This is an uninteresting sentence.\p + This is an uninteresting sentence. + + is formatted as follows. + + This is an uninteresting sentence. This is + an uninteresting sentence. + This is an uninteresting sentence. + + To clearly present the next couple of requests, we must introduce the +concept of "productive" input lines. A "productive input line" is one +that directly produces formatted output. Text lines produce output,(1) +(*note Manipulating Filling and Adjustment-Footnote-1::) as do control +lines containing requests like 'tl' or escape sequences like '\D'. +Macro calls are not _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, '\c', which "connects" two +input lines that would otherwise be counted separately. (2) (*note +Manipulating Filling and Adjustment-Footnote-2::) + + .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? + => Chorus: Hello, world! + => Went the day well? + + -- Request: .ce [n] + -- Register: \n[.ce] + Break (unless the no-break control character is used), center the + output of the next N productive input lines with respect to the + line length and indentation without filling, then break again + regardless of the invoking control character. If the argument is + not positive, centering is disabled. Omitting the argument implies + an N of '1'. The count of lines remaining to be centered is stored + in the read-only register '.ce' and is associated with the + environment (*note Environments::). + + While the '.ad c' request also centers text, it fills the text as + well. + + .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 + => This is a small text fragment that shows + => the differences + => between the `.ce' and the `.ad c' requests. + => + => This is a small text fragment that shows + => the differences between the `.ce' and + => the `.ad c' requests. + + 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. + + -- Request: .rj [n] + -- Register: \n[.rj] + Break (unless the no-break control character is used), align the + output of the next N productive input lines to the right margin + without filling, then break again regardless of the control + character. If the argument is not positive, right-alignment is + disabled. Omitting the argument implies an N of '1'. The count of + lines remaining to be right-aligned is stored in the read-only + register '.rj' and is associated with the environment (*note + Environments::). + + .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 + => At first I hoped that such a technically unsound + => project would collapse but I soon realized it was + => doomed to success. -- C. A. R. Hoare + + -- Request: .ss word-space-size [additional-sentence-space-size] + -- Register: \n[.ss] + -- Register: \n[.sss] + Set the sizes of spaces between words and sentences(3) (*note + Manipulating Filling and Adjustment-Footnote-3::) in twelfths of + font's space width (typically one-fourth to one-third em for + Western scripts). The default for both parameters is 12. Negative + values are erroneous. The first argument is a minimum; if an + output line undergoes adjustment, such spaces may increase in + width. The optional second argument sets the amount of additional + space separating sentences on the same output line. If omitted, + this amount is set to WORD-SPACE-SIZE. The request is ignored if + there are no parameters. + + 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 '.ss' and '.sss' hold the minimal + inter-word space and additional inter-sentence space amounts, + respectively. These parameters are part of the environment (*note + Environments::), and rounded down to the nearest multiple of 12 on + terminals. + + The '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. + + .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. + => 1. J. Fict. Ch. Soc. 6 (2020), 3-14. Reprints + => no longer available through FCS. 2. Better + => known for other work. + + If _undiscardable_ space is required, use the '\h' escape sequence. + + (1) unless diverted; see *note Diversions:: + + (2) *Note Line Continuation::. + + (3) Recall *note Filling:: and *note Sentences:: for the definitions +of word and sentence boundaries, respectively. + +5.10 Manipulating Hyphenation +============================= + +When filling, GNU '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 "automatic hyphenation", let us consider how hyphenation +points can be set explicitly. + + 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,(1) (*note Manipulating Hyphenation-Footnote-1::) particularly +for unusual words found in technical literature. We can instruct GNU +'troff' how to hyphenate specific words if the need arises. + + -- Request: .hw word ... + Define each "hyphenation exception" WORD with each hyphen '-' in + the word indicating a hyphenation point. For example, the request + + .hw in-sa-lub-rious alpha + + 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 'hw' (see the + 'hcode' request below). In addition, this request can be used more + than once. + + Hyphenation points specified with 'hw' are not subject to the + within-word placement restrictions imposed by the 'hy' request (see + below). + + Hyphenation exceptions specified with the 'hw' request are + associated with the hyphenation language (see the 'hla' request + below) and environment (*note Environments::); invoking the 'hw' + request in the absence of a hyphenation language is an error. + + The request is ignored if there are no parameters. + + These are known as hyphenation 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 '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. + + -- Escape sequence: \% + -- Escape sequence: \: + To tell GNU 'troff' how to hyphenate words as they occur in input, + use the '\%' escape sequence; it is the default "hyphenation + character". Each instance within a word indicates to GNU '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 'hw' request. + + GNU 'troff' regards the escape sequences '\X' and '\Y' as starting + a word; that is, the '\%' escape sequence in, say, + '\X'...'\%foobar' or '\Y'...'\%foobar' no longer prevents + hyphenation of 'foobar' but inserts a hyphenation point just prior + to it; most likely this isn't what you want. *Note Postprocessor + Access::. + + '\:' 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 '\:' and '\%' to control breaking of a file name or + URL, or to permit hyphenation only after certain explicit hyphens + within a word. + + 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. + + -- Request: .hc [char] + Change the hyphenation character to CHAR. This character then + works as the '\%' escape sequence normally does, and thus no longer + appears in the output.(2) (*note Manipulating + Hyphenation-Footnote-2::) Without an argument, 'hc' resets the + hyphenation character to '\%' (the default). The hyphenation + character is associated with the environment (*note + Environments::). + + -- Request: .shc [c] + Set the "soft hyphen character", inserted when a word is hyphenated + automatically or at a hyphenation character, to the ordinary or + special character C.(3) (*note Manipulating + Hyphenation-Footnote-3::) If the argument is omitted, the soft + hyphen character is set to the default, '\[hy]'. If no glyph for 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 'char' and similar requests) nor translations + (specified with the 'tr' request) are applied to C. + + Several requests influence automatic hyphenation. Because +conventions vary, a variety of hyphenation modes is available to the +'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 +('hlm'), a minimum line length threshold ('hym'), or because the line +can instead be adjusted with additional inter-word space ('hys'). + + -- Request: .hy [mode] + -- Register: \n[.hy] + Set automatic hyphenation mode to MODE, an integer encoding + conditions for hyphenation; if omitted, '1' is implied. The + hyphenation mode is available in the read-only register '.hy'; it + is associated with the environment (*note Environments::). The + default hyphenation mode depends on the localization file loaded + when GNU 'troff' starts up; see the '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 AT&T 'troff' were + implemented with English-language publishing practices of the 1970s + in mind, not a scrupulous enumeration of conceivable parameters. + GNU '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.(4) (*note Manipulating Hyphenation-Footnote-4::) The + entries in the following table are termed "values"; the sum of the + desired values is the "mode". + + '0' + disables hyphenation. + + '1' + enables hyphenation except after the first and before the last + character of a word. + + The remaining values "imply" 1; that is, they enable hyphenation + under the same conditions as '.hy 1', and then apply or lift + restrictions relative to that basis. + + '2' + disables hyphenation of the last word on a page,(5) (*note + Manipulating Hyphenation-Footnote-5::) even for explicitly + hyphenated words. + + '4' + disables hyphenation before the last two characters of a word. + + '8' + disables hyphenation after the first two characters of a word. + + '16' + enables hyphenation before the last character of a word. + + '32' + enables hyphenation after the first character of a word. + + Apart from value 2, restrictions imposed by the hyphenation mode + are _not_ respected for words whose hyphenations have been + specified with the hyphenation character ('\%' by default) or the + 'hw' request. + + Nonzero values in the previous table are additive. For example, + mode 12 causes GNU '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 16, + and values 8 and 32. As noted, it is superfluous to add 1 to any + non-zero even mode. + + The automatic placement of hyphens in words is determined by + "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 'echo $(nroff)'. + + .ll 1 + .hy 48 + splitting + + You will get + + s- plit- t- in- g + + instead of the correct 'split- ting'. English patterns as + distributed with GNU 'troff' need two characters at the beginning + and three characters at the end; this means that value 4 of 'hy' is + mandatory. Value 8 is possible as an additional restriction, but + values 16 and 32 should be avoided, as should mode 1. Modes 4 + and 6 are typical. + + A table of left and right minimum character counts for hyphenation + as needed by the patterns distributed with GNU 'troff' follows; see + the 'groff_tmac(5)' man page for more information on GNU 'troff''s + language macro files. + + language pattern name left min right min + ----------------------------------------------------------- + Czech cs 2 2 + English en 2 3 + French fr 2 3 + German traditional det 2 2 + German reformed den 2 2 + Italian it 2 2 + Swedish sv 1 2 + + Hyphenation exceptions within pattern files (i.e., the words within + a TeX '\hyphenation' group) obey the hyphenation restrictions given + by 'hy'. + + -- Request: .nh + Disable automatic hyphenation; i.e., set the hyphenation mode to 0 + (see above). The hyphenation mode of the last call to 'hy' is not + remembered. + + -- Request: .hpf pattern-file + -- Request: .hpfa pattern-file + -- Request: .hpfcode a b [c d] ... + Read hyphenation patterns from PATTERN-FILE, which is sought in the + same way that macro files are with the 'mso' request or the + '-mNAME' command-line option to 'groff'. The PATTERN-FILE should + have the same format as (simple) TeX pattern files. More + specifically, the following scanning rules are implemented. + + * A percent sign starts a comment (up to the end of the line) + even if preceded by a backslash. + + * "Digraphs" like '\$' are not supported. + + * '^^XX' (where each X is 0-9 or a-f) and '^^C' (character C in + the code point range 0-127 decimal) are recognized; other uses + of '^' cause an error. + + * No macro expansion is performed. + + * 'hpf' checks for the expression '\patterns{...}' (possibly + with whitespace before or after the braces). Everything + between the braces is taken as hyphenation patterns. + Consequently, '{' and '}' are not allowed in patterns. + + * Similarly, '\hyphenation{...}' gives a list of hyphenation + exceptions. + + * '\endinput' is recognized also. + + * For backward compatibility, if '\patterns' is missing, the + whole file is treated as a list of hyphenation patterns + (except that the '%' character is recognized as the start of a + comment). + + The 'hpfa' request appends a file of patterns to the current list. + + The 'hpfcode' request defines mapping values for character codes in + pattern files. It is an older mechanism no longer used by GNU + 'troff''s own macro files; for its successor, see 'hcode' below. + 'hpf' or '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 255. + The request maps character code A to code B, code C to code D, and + so on. Character codes that would otherwise be invalid in GNU + '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'. + + The set of hyphenation patterns is associated with the language set + by the 'hla' request (see below). The 'hpf' request is usually + invoked by a localization file loaded by the 'troffrc' file.(6) + (*note Manipulating Hyphenation-Footnote-6::) + + A second call to 'hpf' (for the same language) replaces the + hyphenation patterns with the new ones. Invoking 'hpf' or 'hpfa' + causes an error if there is no hyphenation language. If no 'hpf' + request is specified (either in the document, in a file loaded at + startup, or in a macro package), GNU 'troff' won't automatically + hyphenate at all. + + -- Request: .hcode c1 code1 [c2 code2] ... + Set the hyphenation code of character C1 to CODE1, that of C2 to + CODE2, and so on. A hyphenation code must be 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 'troff' assigns hyphenation codes to the letters + 'a'-'z' (mapped to themselves), to the letters 'A'-'Z' (mapped to + 'a'-'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 + '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 'hcode' requests are necessary to assign + hyphenation codes to the letters 'ÄäÖöÜüß', needed for German. + + .hcode ä ä Ä ä + .hcode ö ö Ö ö + .hcode ü ü Ü ü + .hcode ß ß + + Without these assignments, GNU 'troff' treats the German word + 'Kindergärten' (the plural form of 'kindergarten') as two words + 'kinderg' and 'rten' because the hyphenation code of the umlaut a + is zero by default, just like a space. There is a German + hyphenation pattern that covers 'kinder', so GNU 'troff' finds the + hyphenation 'kin-der'. The other two hyphenation points + ('kin-der-gär-ten') are missed. + + -- Request: .hla lang + -- Register: \n[.hla] + Set the hyphenation language to LANG. Hyphenation exceptions + specified with the 'hw' request and hyphenation patterns and + exceptions specified with the 'hpf' and 'hpfa' requests are + associated with the hyphenation language. The 'hla' request is + usually invoked by a localization file, which is turn loaded by the + 'troffrc' or 'troffrc-end' file; see the 'hpf' request above. + + The hyphenation language is available in the read-only + string-valued register '.hla'; it is associated with the + environment (*note Environments::). + + -- Request: .hlm [n] + -- Register: \n[.hlm] + -- Register: \n[.hlc] + Set the maximum quantity of consecutive hyphenated lines to N. If + N is negative, there is no maximum. If omitted, N is -1. This + value is associated with the environment (*note Environments::). + Only lines output from a given environment count toward the maximum + associated with that environment. Hyphens resulting from '\%' are + counted; explicit hyphens are not. + + The '.hlm' read-only register stores this maximum. The count of + immediately preceding consecutive hyphenated lines is available in + the read-only register '.hlc'. + + -- Request: .hym [length] + -- Register: \n[.hym] + Set the (right) hyphenation margin to LENGTH. If the adjustment + mode is not 'b' or 'n', the line is not hyphenated if it is shorter + than LENGTH. Without an argument, the hyphenation margin is reset + to its default value, 0. The default scaling unit is 'm'. The + hyphenation margin is associated with the environment (*note + Environments::). + + A negative argument resets the hyphenation margin to zero, emitting + a warning in category 'range'. + + The hyphenation margin is available in the '.hym' read-only + register. + + -- Request: .hys [hyphenation-space] + -- Register: \n[.hys] + Suppress hyphenation of the line in adjustment modes 'b' or 'n' if + it can be justified by adding no more than 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 'm'. The hyphenation space + adjustment threshold is associated with the environment (*note + Environments::). + + A negative argument resets the hyphenation space adjustment + threshold to zero, emitting a warning in category 'range'. + + The hyphenation space adjustment threshold is available in the + '.hys' read-only register. + + (1) Whether a perfect algorithm for this application is even possible +is an unsolved problem in computer science: +<https://tug.org/docs/liang/liang-thesis.pdf>. + + (2) '\%' itself stops marking hyphenation points but still produces +no output glyph. + + (3) "Soft" because it appears in output only where a hyphenation +break is performed; a "hard" hyphen, as in "long-term", always appears. + + (4) 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. + + (5) Hyphenation is prevented if the next page location trap is closer +to the vertical drawing position than the next text baseline would be. +*Note Page Location Traps::. + + (6) For more on localization, see the 'groff_tmac(5)' man page. + +5.11 Manipulating Spacing +========================= + +A break causes the formatter to update the vertical drawing position at +which the new text baseline is aligned. You can alter this location. + + -- Request: .sp [distance] + Break and move the next text baseline down by DISTANCE, or until + springing a page location trap.(1) (*note Manipulating + Spacing-Footnote-1::) If invoked with the no-break control + character, 'sp' moves the pending output line's text baseline by + DISTANCE. A negative DISTANCE will not reduce the position of the + text baseline below zero. Inside a diversion, any DISTANCE + argument is ignored. The default scaling unit is 'v'. If DISTANCE + is not specified, '1v' is assumed. + + .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. + => --- + => foo on page 1 + => + => + => bar on page 1 + => --- + => baz on page 2 + + 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 ('\n[.v]') because the '|' + operator moves to one vee below the page top (recall *note Numeric + Expressions::). + + .de y-from-top-down + . sp |\\$1-\\n[.v]u + .. + . + .de y-from-bot-up + . sp |\\n[.p]u-\\$1-\\n[.v]u + .. + + A call to '.y-from-bot-up 10c' means that the next text baseline + will be 10 cm from the bottom edge of the paper. + + -- Request: .ls [count] + -- Register: \n[.L] + Set the line spacing; add COUNT-1 blank lines after each line of + text. With no argument, GNU 'troff' uses the previous value before + the last 'ls' call. The default is '1'. + + The read-only register '.L' contains the current line spacing; it + is associated with the environment (*note Environments::). + + The 'ls' request is a coarse mechanism. *Note Changing the Type +Size::, for the requests 'vs' and 'pvs' as alternatives to 'ls'. + + -- Escape sequence: \x'spacing' + -- Register: \n[.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 '\x' escape sequence takes a delimited measurement (like + '\x'3p'') to increase the vertical spacing of the pending output + line. The default scaling unit is 'v'. If the measurement is + positive, extra vertical space is inserted below the current line; + a negative measurement adds space above. If '\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 *note Delimiters::. + + The '.a' read-only register contains the extra vertical spacing + _after_ the text baseline of the most recently emitted output line. + (In other words, it is the largest positive argument to '\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 '\x'), then + applying both can lead to excessive spacing between the output + lines. Text that is piling high on line N might not require (as + much) extra pre-vertical line spacing if line N-1 carries extra + post-vertical line spacing. + + Use of '\x' can be necessary in combination with the + bracket-building escape sequence '\b',(2) (*note Manipulating + Spacing-Footnote-2::) as the following example shows. + + .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). + => This is a test of \b (1). + => This is a test of \b (2). + => x + => This is a test of y (3). + => z + => This is a test of \b (4). + => This is a test of \b (5). + +Without '\x', the backslashes on the lines marked '(2)' and '(4)' would +be overprinted. + + -- Request: .ns + -- Request: .rs + -- Register: \n[.ns] + Enable "no-space mode". Vertical spacing, whether by 'sp' requests + or blank input lines, is disabled. The 'bp' request to advance to + the next page is also disabled, unless it is accompanied by a page + number (*note Page Control::). No-space mode ends automatically + when text(3) (*note Manipulating Spacing-Footnote-3::) is formatted + for output (4) (*note Manipulating Spacing-Footnote-4::) or the + 'rs' request is invoked, which ends no-space mode. The read-only + register '.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 'ns' to + suppress this spacing for the first paragraph in a section. + + (1) *Note Page Location Traps::. + + (2) *Note Drawing Geometric Objects::. + + (3) or geometric objects; see *note Drawing Geometric Objects:: + + (4) to the top-level diversion; see *note Diversions:: + +5.12 Tabs and Fields +==================== + +A tab character (ISO code point 9, EBCDIC code point 5) causes a +horizontal movement to the next tab stop, if any. + + -- Escape sequence: \t + Interpolate a tab in copy mode; see *note Copy Mode::. + + -- Request: .ta [[n1 n2 ... nn ]T r1 r2 ... rn] + -- Register: \n[.tabs] + Change tab stop positions. This request takes a series of tab + specifiers as arguments (optionally divided into two groups with + the letter 'T') that indicate where each tab stop is to be, + overriding any previous settings. The default scaling unit is 'm'. + Invoking 'ta' without an argument removes all tab stops. GNU + 'troff''s startup value is '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. + + .ta 1i 2i 3i 4i 5i 6i + + Tab stops can also be specified using a leading '+', 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. + + .ta 1i +1i +1i +1i +1i +1i + + GNU 'troff' supports an extended syntax to specify repeating tab + stops. These stops appear after a '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 + '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. + + .ta T 1i + + Now we are ready to interpret the full syntax given above. The + 'ta' request sets tabs at positions N1, N2, ..., NN, then at NN+R1, + NN+R2, ..., NN+RN, then at NN+RN+R1, NN+RN+R2, ..., NN+RN+RN, and + so on. + + For example, '4c +6c T 3c 5c 2c' is equivalent to '4c 10c 13c 18c + 20c 23c 28c 30c ...'. + + 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 'R', 'L', or 'C' to the tab specifier. The + default is 'L'. + + .ta 1i 2iC 3iR + + 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 *note Manipulating Filling and + Adjustment:: and *note Line Layout::. + + A tab stop is converted into a non-breakable horizontal movement + that cannot be adjusted. + + .ll 2i + .ds foo a\tb\tc + .ta T 1i + \*[foo] + error-> warning: cannot break line + => a b c + + 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. + + .ll 2i + .ds bar a\tb c\td + .ta T 1i + \*[bar] + error-> warning: cannot adjust line + => a b + => c d + + GNU 'troff' first converts the line's tab stops into unbreakable + horizontal movements, then breaks after '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. + + .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 + => foo bar baz + => foo bar bazqux + => foo bar bazqux + + 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 (*note + Environments::). + + The read-only register '.tabs' contains a string representation of + the current tab settings suitable for use as an argument to the + 'ta' request.(1) (*note Tabs and Fields-Footnote-1::) + + .ds tab-string \n[.tabs] + \*[tab-string] + => T120u + + -- Request: .tc [c] + Set the tab repetition character to the ordinary or special + character 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 "tab repetition character" causes the + formatter to write as many instances of C as are necessary to + occupy the interval from the horizontal drawing position to the + next tab stop. With no argument, GNU 'troff' reverts to the + default behavior. The tab repetition character is associated with + the environment (*note Environments::). Only a single character of + C is recognized; any excess is ignored. + + -- Request: .linetabs n + -- Register: \n[.linetabs] + If N is missing or non-zero, activate "line-tabs"; deactivate it + otherwise (the default). Active line-tabs cause GNU 'troff' to + compute tab distances relative to the start of the output line + instead of the input line. + + .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 + => a b c + => a b c + + Line-tabs activation is associated with the environment (*note + Environments::). The read-only register '.linetabs' interpolates 1 + if line-tabs are active, and 0 otherwise. + + (1) Plan 9 'troff' uses the register '.S' for this purpose. + +5.12.1 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 'roff' +language provides "leaders" for this purpose.(1) (*note +Leaders-Footnote-1::) + + A leader character (ISO and EBCDIC code point 1, also known as 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 '.'. + + -- Escape sequence: \a + Interpolate a leader in copy mode; see *note Copy Mode::. + + -- Request: .lc [c] + Set the leader repetition character to the ordinary or special + character C. Recall *note Tabs and Leaders::: when encountering a + leader character in the input, the formatter writes as many dots + '.' as are necessary until reaching the next tab stop; this is the + "leader definition character". Omitting C unsets the leader + character. With no argument, GNU 'troff' treats leaders the same + as tabs. The leader repetition character is associated with the + environment (*note Environments::). Only a single C is recognized; + any excess is ignored. + + 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. + + .ds entry1 19.\tThe Prophet\a\t98 + .ds entry2 20.\tAll Astir\a\t101 + .ta .5i 4.5i +.5iR + .nf + \*[entry1] + \*[entry2] + => 19. The Prophet............................. 98 + => 20. All Astir............................... 101 + + (1) 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. + +5.12.2 Fields +------------- + +"Fields" are a more general way of laying out tabular data. A field is +defined as the data between a pair of "delimiting characters". It +contains substrings that are separated by "padding characters". The +width of a field is the distance on the _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 '\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. + + -- Request: .fc [delim-char [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 _not_ + associated with the environment (*note Environments::). + + .fc # ^ + .ta T 3i + #foo^bar^smurf# + .br + #foo^^bar^smurf# + => foo bar smurf + => foo bar smurf + +5.13 Character Translations +=========================== + +A "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 (*note Gtroff Internals::, +for more on this process). + + -- Request: .tr abcd... + -- Request: .trin abcd... + Translate character A to glyph B, character C to glyph 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 '\<SP>' escape sequence). + + The 'trin' request is identical to 'tr', but when you unformat a + diversion with 'asciify' it ignores the translation. *Note + Diversions::, for details about the 'asciify' request. + + Some notes: + + * Special characters ('\(XX', '\[XXX]', '\C'XXX'', '\'', '\`', + '\-', '\_'), glyphs defined with the 'char' request, and + numbered glyphs ('\N'XXX'') can be translated also. + + * The '\e' escape can be translated also. + + * Characters can be mapped onto the '\%' and '\~' escape + sequences (but '\%' and '\~' can't be mapped onto another + glyph). + + * The following characters can't be translated: space (with one + exception, see below), backspace, newline, leader (and '\a'), + tab (and '\t'). + + * Translations are not considered for finding the soft hyphen + character set with the 'shc' request. + + * The pair 'C\&' (an arbitrary character C followed by the dummy + character) maps this character to "nothing". + + .tr a\& + foo bar + => foo br + + Even the space character can be mapped to the dummy character. + + .tr aa \& + foo bar + => foobar + + As shown in the example, the space character can't be the + first character/glyph pair as an argument of 'tr'. + Additionally, it is not possible to map the space character to + any other glyph; requests like '.tr aa x' undo '.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). + + * 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 'tr'. + + * Translating character to glyphs where one of them or both are + undefined is possible also; 'tr' does not check whether the + elements of its argument exist. + + *Note Gtroff Internals::. + + * Without an argument, the 'tr' request is ignored. + + -- Request: .trnt abcd... + 'trnt' is the same as the 'tr' request except that the translations + do not apply to text that is transparently throughput into a + diversion with '\!'. *Note Diversions::. + + For example, + + .tr ab + .di x + \!.tm a + .di + .x + + prints 'b' to the standard error stream; if 'trnt' is used instead + of 'tr' it prints 'a'. + +5.14 'troff' and 'nroff' Modes +============================== + +Historically, 'nroff' and 'troff' were two separate programs; the former +for terminal output, the latter for typesetters. GNU 'troff' merges +both functions into one executable(1) (*note troff and nroff +Modes-Footnote-1::) that sends its output to a device driver ('grotty' +for terminal devices, 'grops' for PostScript, and so on) which +interprets this intermediate output format. When discussing AT&T +'troff', it makes sense to talk about "'nroff' mode" and "'troff' mode" +since the differences are hard-coded. GNU '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 'troff' provides two built-in +conditions 'n' and 't' for the 'if', 'ie', and 'while' requests to +decide whether GNU 'troff' shall behave like 'nroff' or like 'troff'. + + -- Request: .troff + Make the 't' built-in condition true (and the 'n' built-in + condition false) for 'if', 'ie', and 'while' conditional requests. + This is the default if GNU 'troff' (_not_ 'groff') is started with + the '-R' switch to avoid loading of the startup files 'troffrc' and + 'troffrc-end'. Without '-R', GNU 'troff' stays in 'troff' mode if + the output device is not a terminal (e.g., 'ps'). + + -- Request: .nroff + Make the 'n' built-in condition true (and the 't' built-in + condition false) for 'if', 'ie', and 'while' conditional requests. + This is the default if GNU 'troff' uses a terminal output device; + the code for switching to 'nroff' mode is in the file 'tty.tmac', + which is loaded by the startup file 'troffrc'. + + *Note Conditionals and Loops::, for more details on built-in +conditions. + + (1) A GNU 'nroff' program is available for convenience; it calls GNU +'troff' to perform the formatting. + +5.15 Line Layout +================ + +The following drawing shows the dimensions that 'gtroff' uses for +placing a line of output onto the page. They are labeled with the +request that manipulates each dimension. + + -->| in |<-- + |<-----------ll------------>| + +----+----+----------------------+----+ + | : : : | + +----+----+----------------------+----+ + -->| po |<-- + |<--------paper width---------------->| + +These dimensions are: + +'po' + "Page offset"--this is the leftmost position of text on the final + output, defining the "left margin". + +'in' + "Indentation"--this is the distance from the left margin where text + is printed. + +'ll' + "Line length"--this is the distance from the left margin to 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: + + .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. + + => This is text without indenta- + => tion. The line length has + => been set to 3 inches. + => Now the left and + => right margins are + => both increased. + => Calling .in and .ll without + => parameters restores the previ- + => ous values. + + -- Request: .po [offset] + -- Request: .po +offset + -- Request: .po -offset + -- Register: \n[.o] + Set page offset to OFFSET (or increment or decrement its current + value by OFFSET). If invoked without an argument, the page offset + is restored to the value before the previous 'po' request. This + request does not cause a break; the page offset in effect when an + output line is broken prevails (*note Manipulating Filling and + Adjustment::). The initial value is 1i and the default scaling + unit is 'm'. On terminal devices, the page offset is set to zero + by a driver-specific macro file, 'tty.tmac'. The current page + offset can be found in the read-only register '.o'. This request + is incorrectly documented in the AT&T 'troff' manual as using a + default scaling unit of 'v'. + + .po 3i + \n[.o] + => 720 + .po -1i + \n[.o] + => 480 + .po + \n[.o] + => 720 + + -- Request: .in [indent] + -- Request: .in +indent + -- Request: .in -indent + -- Register: \n[.i] + Set indentation to INDENT (or increment or decrement the current + value by INDENT). This request causes a break. Initially, there + is no indentation. + + If 'in' is called without an argument, the indentation is reset to + the previous value before the last call to 'in'. The default + scaling unit is 'm'. + + If a negative indentation value is specified (which is not + allowed), 'gtroff' emits a warning in category 'range' and sets the + indentation to zero. + + The effect of '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 'in') can be found in the + read-only register '.i'. The indentation is associated with the + environment (*note Environments::). + + -- Request: .ti offset + -- Request: .ti +offset + -- Request: .ti -offset + -- Register: \n[.in] + Temporarily indent the next output line by OFFSET. If an increment + or decrement value is specified, adjust the temporary indentation + relative to the value set by the 'in' request. + + This request causes a break; its value is associated with the + environment (*note Environments::). The default scaling unit is + 'm'. A call of 'ti' without an argument is ignored. + + If the total indentation value is negative (which is not allowed), + 'gtroff' emits a warning in category 'range' and sets the temporary + indentation to zero. 'Total indentation' is either OFFSET if + specified as an absolute value, or the temporary plus normal + indentation, if OFFSET is given as a relative value. + + The effect of 'ti' is delayed until a partially collected line (if + it exists) is output. + + The read-only register '.in' is the indentation that applies to the + current output line. + + The difference between '.i' and '.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. + + -- Request: .ll [length] + -- Request: .ll +length + -- Request: .ll -length + -- Register: \n[.l] + -- Register: \n[.ll] + Set the line length to LENGTH (or increment or decrement the + current value by LENGTH). Initially, the line length is set to + 6.5i. The effect of 'll' is delayed until a partially collected + line (if it exists) is output. The default scaling unit is 'm'. + + If 'll' is called without an argument, the line length is reset to + the previous value before the last call to 'll'. If a negative + line length is specified (which is not allowed), 'gtroff' emits a + warning in category 'range' and sets the line length to zero. The + line length is associated with the environment (*note + Environments::). + + The current line length (as set by 'll') can be found in the + read-only register '.l'. The read-only register '.ll' is the line + length that applies to the current output line. + + Similar to '.i' and '.in', the difference between '.l' and '.ll' is + that the latter takes into account whether a partially collected + line still uses the old line length value. + +5.16 Line Continuation +====================== + +When filling is enabled, input and output line breaks generally do not +correspond. The 'roff' language therefore distinguishes input and +output line continuation. + + -- Escape sequence: \<RET> + '\<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. '\<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 '|' operator recognizes the new input line (*note + Numeric Expressions::), and the input line counter register '.c' is + incremented. + + .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]. + => Our film class watched The Effect of Gamma Rays on + => Man-in-the-Moon Marigolds. + => My own opus begins on line 11 and ends on line 12. + + -- Escape sequence: \c + -- Register: \n[.int] + '\c' continues an output line. Nothing after it on the input line + is formatted. In contrast to '\<RET>', a line after '\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 *note Manipulating Filling and Adjustment::. + + * If filling is enabled, a word interrupted with '\c' is + continued with the text on the next input text line, without + an intervening space. + + This is a te\c + st. + => This is a test. + + * If filling is disabled, the next input text line after '\c' is + handled as a continuation of the same input text line. + + .nf + This is a \c + test. + => This is a test. + + An intervening control line that causes a break overrides '\c', + flushing out the pending output line in the usual way. + + The '.int' register contains a positive value if the last output + line was continued with '\c'; this datum is associated with the + environment (*note Environments::).(1) (*note Line + Continuation-Footnote-1::) + + (1) Historically, the '\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. + +5.17 Page Layout +================ + +The formatter permits configuration of the page length and page number. + + -- Request: .pl [length] + -- Request: .pl +length + -- Request: .pl -length + -- Register: \n[.p] + Change (increase or decrease) the page length per the numeric + expression LENGTH. The default scaling unit is 'v'. A negative + LENGTH is valid, but an uncommon application: it prevents page + location traps from being sprung,(1) (*note Page + Layout-Footnote-1::) and each output line is placed on a new page. + If LENGTH is invalid, GNU 'troff' emits a warning in category + 'number'. If LENGTH is absent or invalid, '11i' is assumed. + + The read-only register '.p' interpolates the current page length. + + -- Request: .pn num + -- Request: .pn +num + -- Request: .pn -num + -- Register: \n[.pn] + Change (increase or decrease) the page number of the _next_ page + per the numeric expression NUM. If NUM is invalid, GNU 'troff' + emits a warning in category 'number' and ignores the request. + Without an argument, 'pn' is ignored. + + The read-only register '.pn' interpolates NUM if set by 'pn' on the + current page, or the current page number plus 1. + + The formatter offers special support for typesetting headers and +footers, collectively termed "titles". Titles have an independent line +length, and their placement on the page is not restricted. + + -- Request: .tl 'left'center'right' + Format an output line as a title consisting of LEFT, CENTER, and + RIGHT, each aligned accordingly. The delimiter need not be a + neutral apostrophe: 'tl' accepts the same delimiters as most escape + sequences; see *note Delimiters::. If not used as the delimiter, + any "page number character" character is replaced with the current + page number; the default is '%'; see the the 'pc' request below. + Without an argument, 'tl' is ignored. 'tl' writes the title line + immediately, ignoring any partially collected line. + + It is not an error to omit delimiters after the first. For + example, '.tl /Thesis' is interpreted as '.tl /Thesis///': it sets + a title line comprising only the left-aligned word 'Thesis'. + + -- Request: .lt [length] + -- Request: .lt +length + -- Request: .lt -length + -- Register: \n[.lt] + Change (increase or decrease) the line length used by titles per + the numeric expression LENGTH. The default scaling unit is 'm'. + If LENGTH is negative, GNU emits a warning in category 'range' and + treats LENGTH as '0'. If LENGTH is invalid, GNU 'troff' emits a + warning in category 'number' and ignores the request. The + formatter's default title length is '6.5i'. With no argument, the + title length is restored to the previous value. The title length + is is associated with the environment (*note Environments::). + + The read-only register '.lt' interpolates the title line length. + + -- Request: .pc [char] + Set the page number character to CHAR. With no argument, the page + number character is disabled. 'pc' does not affect the + register '%'. + + The following example exercises title features. + + .lt 50n + This is my partially collected + .tl 'Isomers 2023'%'Dextrose Edition' + line. + => Isomers 2023 1 Dextrose Edition + => This is my partially collected line. + + We most often see titles used in page header and footer traps. *Note +Traps::. + + (1) *Note Traps::. + +5.18 Page Control +================= + +Discretionary page breaks can prevent the unwanted separation of +content. A new page number takes effect during page ejection; see *note +The Implicit Page Trap::. + + -- Request: .bp [page-number] + -- Request: .bp +page-number + -- Request: .bp -page-number + -- Register: \n[%] + Break the page and change (increase or decrease) the next page + number per the numeric expression PAGE-NUMBER. If PAGE-NUMBER is + invalid, GNU 'troff' emits a warning in category '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. *Note Page Location Traps::. 'bp' has effect + only if invoked within the top-level diversion.(1) (*note Page + Control-Footnote-1::) This request is incorrectly documented in the + AT&T 'troff' manual as having a default scaling unit of 'v'. + + The register '%' interpolates the current page number. + + .de BP + ' bp \" schedule page break once current line is output + .. + + -- Request: .ne [space] + Force a page break if insufficient vertical space is available + (assert "needed" space). 'ne' tests the distance to the next page + location trap; see *note Page Location Traps::, and breaks the page + if that amount is less than SPACE. The default scaling unit is + 'v'. If SPACE is invalid, GNU 'troff' emits a warning in category + 'number' and ignores the argument. If SPACE is not specified, '1v' + is assumed. + + We can require space for at least the first two output lines of a + paragraph, preventing its first line from being widowed at the page + bottom. + + .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, + + This method is reliable only if no output line is pending when '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 'ne' after the paragraphing macro, or + 'br' and 'ne' before it. + + '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 'ne' with diversions to + implement keeps and displays; see *note Diversions::. They may + also offer parameters for widow and orphan management. + + -- Request: .sv [space] + -- Request: .os + Require vertical space as 'ne' does, but also save it for later + output by the 'os' request. If 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. 'sv' + and 'os' ignore no-space mode (recall *note Manipulating + Spacing::). While the 'sv' request allows negative values for + SPACE, 'os' ignores them. The default scaling unit is 'v'. If + SPACE is not specified, '1v' is assumed. + + -- Register: \n[nl] + 'nl' interpolates or sets the vertical drawing position. When the + formatter starts, the first page transition hasn't happened yet, + and 'nl' is negative. If a header trap has been planted on the + page (typically at vertical position '0'), you can assign a + negative value to 'nl' to spring it if that page has already + started (*note Page Location Traps::). + + .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. + => First page. + => + => (blank lines elided) + => + => Goldbach Solution + => + => (blank lines elided) + => + => Second page. + + Without resetting 'nl' to a negative value, the trap just planted + would be active beginning with the _next_ page, not the current + one. + + *Note Diversions::, for a comparison of 'nl' with the '.h' and '.d' + registers. + + (1) *Note Diversions::. + +5.19 Using Fonts +================ + +In digital typography, a "font" is a collection of characters in a +specific typeface that a device can render as glyphs at a desired +size.(1) (*note Using Fonts-Footnote-1::) A 'roff' formatter can change +typefaces at any point in the text. The basic faces are a set of +"styles" combining upright and slanted shapes with normal and heavy +stroke weights: 'R', 'I', 'B', and 'BI'--these stand for roman, italic, +bold, and bold-italic. For linguistic text, GNU 'troff' groups +typefaces into "families" containing each of these styles.(2) (*note +Using Fonts-Footnote-2::) A "text font" is thus often a family combined +with a style, but it need not be: consider the 'ps' and 'pdf' devices' +'ZCMI' (Zapf Chancery Medium italic)--often, no other style of Zapf +Chancery Medium is provided. On typesetting devices, at least one +"special font" is available, comprising "unstyled" glyphs for +mathematical operators and other purposes. + + Like AT&T 'troff', GNU 'troff' does not itself load or manipulate a +digital font file;(3) (*note Using Fonts-Footnote-3::) instead it works +with a "font description file" that characterizes it, including its +glyph repertoire and the "metrics" (dimensions) of each glyph.(4) +(*note Using Fonts-Footnote-4::) 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 "mounting +position", a place in an ordered list of available typefaces. So that a +document need not be strongly coupled to a specific font family, in GNU +'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 "resolved font name". + + Fonts often have trademarked names, and even Free Software fonts can +require renaming upon modification. 'groff' maintains a convention that +a device's serif font family is given the name 'T' ("Times"), its +sans-serif family 'H' ("Helvetica"), and its monospaced family 'C' +("Courier"). Historical inertia has driven 'groff''s font identifiers +to short uppercase abbreviations of font names, as with 'TR', 'TI', +'TB', 'TBI', and a special font 'S'. + + The default family used with abstract styles can be changed at any +time; initially, it is '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 '1' ('R'). By issuing +appropriate formatter instructions, you can override these defaults +before your document writes its first glyph. + + Terminal output devices cannot change font families and lack special +fonts. They support style changes by overstriking, or by altering +ISO 6429/ECMA-48 "graphic renditions" (character cell attributes). + + (1) Terminals and some output devices have fonts that render at only +one or two sizes. As examples of the latter, take the 'groff' 'lj4' +device's Lineprinter, and 'lbp''s Courier and Elite faces. + + (2) Font designers prepare families such that the styles share +esthetic properties. + + (3) Historically, the fonts '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. + + (4) *Note Font Description File Format::. + +5.19.1 Selecting Fonts +---------------------- + +We use "font" to refer to any of several means of identifying a font: by +mounting position ('3'), by abstract style ('B'), or by its identifier +('TB'). + + -- Request: .ft [font] + -- Escape sequence: \ff + -- Escape sequence: \f(fn + -- Escape sequence: \f[font] + -- Register: \n[.fn] + The 'ft' request selects the typeface FONT. If the argument is + absent or 'P', it selects the previously chosen font. If 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 'fam' + and '\F' below) to make a resolved font name. If the mounting + position is not a style and no font is mounted there, GNU 'troff' + emits a warning in category 'font' and ignores the request. + + If FONT matches a style name, it is combined with the current + family to make a resolved font name. Otherwise, FONT is assumed to + already be a resolved font name. + + The resolved font name is subject to translation (see request 'ftr' + below). Next, the (possibly translated) font name's mounting + position is looked up; if not mounted, FONT is sought on the file + system as a font description file and, if located, automatically + mounted at the next available position (see register '.fp' below). + If the font was mounted using an identifier different from its font + description file name (see request 'fp' below), that file name is + then looked up. If a font description file for the resolved font + name is not found, GNU 'troff' emits a warning in category 'font' + and ignores the request. + + The '\f' escape sequence is similar, using one-character name (or + mounting position) F, two-character name FN, or a name FONT of + arbitrary length. '\f[]' selects the previous font. The syntax + form '\fP' is supported for backward compatibility, and '\f[P]' for + consistency. + + eggs, bacon, + .ft I + spam, + .ft + and sausage. + .br + eggs, bacon, \fIspam,\fP and sausage. + => eggs, bacon, spam, and sausage + => eggs, bacon, spam, and sausage + + The current and previously selected fonts are properties of the + environment (*note Environments::). + + The read-only string-valued register '.fn' contains the resolved + font name of the selected font. + + '\f' doesn't produce an input token in GNU '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 (*note + Miscellaneous::). + + .mc \f[I]x\f[] + + -- Request: .ftr f [g] + Translate font F to font G. Whenever a font named F is referred to + in a '\f' escape sequence, in the 'F' and 'S' conditional + operators, or in the 'ft', 'ul', 'bd', 'cs', 'tkf', 'special', + 'fspecial', 'fp', or 'sty' requests, font G is used. If G is + missing or equal to F the translation is undone. + + Font translations cannot be chained. + + .ftr XXX TR + .ftr XXX YYY + .ft XXX + error-> warning: can't find font 'XXX' + + -- Request: .fzoom f [zoom] + -- Register: \n[.zoom] + Set magnification of font F to factor 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 'CR' is magnified by 10% (the zoom factor + is thus 1.1). + + .fam P + .fzoom CR 1100 + .ps 12 + Palatino and \f[CR]Courier\f[] + + A missing or zero value of ZOOM is the same as a value of 1000, + which means no magnification. F must be a resolved font name, not + an abstract style. + + The magnification of a font is completely transparent to GNU + '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 '.zoom', in multiples of 1/1000th. It returns zero if + there is no magnification. + +5.19.2 Font Families +-------------------- + +To accommodate the wide variety of fonts available, GNU 'troff' +distinguishes "font families" and "font styles". A resolved font name +is the catenation of a font family and a style. Selecting an abstract +style causes GNU '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 *note Groff Options::). + + Fonts for the devices 'ps', 'pdf', 'dvi', 'lj4', 'lbp', and the X11 +devices support this mechanism. By default, GNU 'troff' uses the Times +family with the four styles 'R', 'I', 'B', and 'BI'. + + -- Request: .fam [family] + -- Register: \n[.fam] + -- Escape sequence: \Ff + -- Escape sequence: \F(fm + -- Escape sequence: \F[family] + Set the default font family, used in combination with abstract + styles to construct a resolved font name, to FAMILY (one-character + name F, two-character name FM). If no argument is given, GNU + 'troff' selects the previous font family; if there none, is it + falls back to the device's default(1) (*note Font + Families-Footnote-1::) or its own ('T'). + + The '\F' escape sequence works similarly. In disanalogy to '\f', + '\FP' makes 'P' the default family. Use '\F[]' to select the + previous default family. The default font family is available in + the read-only string-valued register '.fam'; it is associated with + the environment (*note Environments::). + + 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. + + '\F' doesn't produce an input token in GNU 'troff'. As a + consequence, it can be used in requests like 'mc' (which expects a + single character as an argument) to change the font family on the + fly. + + .mc \F[P]x\F[] + + -- Request: .sty n style + -- Register: \n[.sty] + Associate an abstract style STYLE with mounting position N, which + must be a non-negative integer. If the requests 'cs', 'bd', 'tkf', + 'uf', or 'fspecial' are applied to an abstract style, they are + instead applied to the member of the current family corresponding + to that style. + + The default family can be set with the '-f' option (*note Groff + Options::). The 'styles' command in the 'DESC' file controls which + font positions (if any) are initially associated with abstract + styles rather than fonts. + + *Caution:* The STYLE argument is not validated. Errors may occur + later, when the formatter attempts to construct a resolved font + name, or format a character for output. + + .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 + + When an abstract style has been selected, the read-only + string-valued register '.sty' interpolates its name; this datum is + associated with the environment (*note Environments::). Otherwise, + '.sty' interpolates nothing. + + (1) *Note DESC File Format::. + +5.19.3 Font Positions +--------------------- + +To support typeface indirection through abstract styles, and for +compatibility with AT&T 'troff', the formatter maintains a list of font +"positions" at which fonts required by a document are "mounted". An +output device's description file 'DESC' typically configures a set of +pre-mounted fonts; see *note Device and Font Description Files::. A +font need not be explicitly mounted before it is selected; GNU 'troff' +will search 'GROFF_FONT_PATH' for it by name and mount it at the first +free mounting position on demand. + + -- Request: .fp pos id [font-description-file-name] + -- Register: \n[.f] + -- Register: \n[.fp] + Mount a font under the name ID at mounting position 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 1. Position 0 is unused by default. Unless + the FONT-DESCRIPTION-FILE-NAME argument is given, ID should be the + name of a font description file stored in a directory corresponding + to the selected output device. GNU 'troff' does not traverse + directories to locate the font description file. + + The optional third argument enables font names to be aliased, which + can be necessary in compatibility mode since AT&T 'troff' syntax + affords no means of identifying fonts with names longer than two + characters, like 'TBI' or 'ZCMI', in a font selection escape + sequence. *Note Compatibility Mode::. You can also alias fonts on + mounting for convenience or abstraction. (See below regarding the + '.fp' register.) + + .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[]? + + 'DESC', 'P', and non-negative integers are not usable as font + identifiers. + + The position of the currently selected font (or abstract style) is + available in the read-only register '.f'. It is associated with + the environment (*note Environments::). + + You can copy the value of '.f' to another register to save it for + later use. + + .nr saved-font \n[.f] + ... text involving many font changes ... + .ft \n[saved-font] + + The index of the next (non-zero) free font position is available in + the read-only register '.fp'. Fonts not listed in the 'DESC' file + are automatically mounted at position '\n[.fp]' when selected with + the 'ft' request or '\f' escape sequence. When mounting a font at + a position explicitly with the 'fp' request, this same practice + should be followed, although GNU 'troff' does not enforce this + strictly. + +5.19.4 Using Symbols +-------------------- + +A "glyph" is a graphical representation of a "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 +"ligature"--the most common is 'fi'. + + Space characters never become glyphs in GNU 'troff'. If not +discarded (as when trailing on text lines), they are represented by +horizontal motions in the output. + + A "symbol" is simply a named glyph. Within '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, 'gtroff' looks up an ordered list of +"special fonts". By default, the PostScript output device supports the +two special fonts 'SS' (slanted symbols) and 'S' (symbols) (the former +is looked up before the latter). Other output devices use different +names for special fonts. Fonts mounted with the 'fonts' keyword in the +'DESC' file are globally available. To install additional special fonts +locally (i.e., for a particular font), use the 'fspecial' request. + + Here are the exact rules how 'gtroff' searches a given symbol: + + * If the symbol has been defined with the 'char' request, use it. + This hides a symbol with the same name in the current font. + + * Check the current font. + + * If the symbol has been defined with the 'fchar' request, use it. + + * Check whether the current font has a font-specific list of special + fonts; test all fonts in the order of appearance in the last + 'fspecial' call if appropriate. + + * If the symbol has been defined with the 'fschar' request for the + current font, use it. + + * Check all fonts in the order of appearance in the last 'special' + call. + + * If the symbol has been defined with the 'schar' request, use it. + + * 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 'fonts' line in + the 'DESC' file often contains empty positions, which are filled + later on. For example, consider the following: + + fonts 3 0 0 FOO + + This mounts font 'foo' at font position 3. We assume that 'FOO' is + a special font, containing glyph 'foo', and that no font has been + loaded yet. The line + + .fspecial BAR BAZ + + makes font 'BAZ' special only if font 'BAR' is active. We further + assume that 'BAZ' is really a special font, i.e., the font + description file contains the 'special' keyword, and that it also + contains glyph 'foo' with a special shape fitting to font 'BAR'. + After executing 'fspecial', font 'BAR' is loaded at font + position 1, and 'BAZ' at position 2. + + We now switch to a new font 'XXX', trying to access glyph 'foo' + that is assumed to be missing. There are neither font-specific + special fonts for 'XXX' nor any other fonts made special with the + 'special' request, so 'gtroff' starts the search for special fonts + in the list of already mounted fonts, with increasing font + positions. Consequently, it finds 'BAZ' before 'FOO' even for + 'XXX', which is not the intended behaviour. + + *Note Device and Font Description Files::, and *note Special Fonts::, +for more details. + + The 'groff_char(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 + + man -Tdvi groff_char > groff_char.dvi + +to obtain those available with the DVI device and default font +configuration.(1) (*note Using Symbols-Footnote-1::) If you want to use +an additional macro package to change the fonts used, 'groff' (or +'gtroff') must be run directly. + + groff -Tdvi -mec -man groff_char.7 > groff_char.dvi + + Special character names not listed in 'groff_char(7)' are derived +algorithmically, using a simplified version of the Adobe Glyph List +(AGL) algorithm, which is described in +<https://github.com/adobe-type-tools/agl-aglfn>. The (frozen) set of +names that can't be derived algorithmically is called the "'groff' glyph +list (GGL)". + + * A glyph for Unicode character U+XXXX[X[X]], which is not a + composite character is named 'uXXXX[X[X]]'. X must be an uppercase + hexadecimal digit. Examples: 'u1234', 'u008E', 'u12DB8'. The + largest Unicode value is 0x10FFFF. There must be at least four 'X' + digits; if necessary, add leading zeroes (after the '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. + + * A glyph representing more than a single input character is named + + 'u' COMPONENT1 '_' COMPONENT2 '_' COMPONENT3 ... + + Example: 'u0045_0302_0301'. + + For simplicity, all Unicode characters that are composites must be + maximally decomposed to NFD;(2) (*note Using Symbols-Footnote-2::) + for example, 'u00CA_0301' is not a valid glyph name since U+00CA + (LATIN CAPITAL LETTER E WITH CIRCUMFLEX) can be further decomposed + into U+0045 (LATIN CAPITAL LETTER E) and U+0302 (COMBINING + CIRCUMFLEX ACCENT). 'u0045_0302_0301' is thus the glyph name for + U+1EBE, LATIN CAPITAL LETTER E WITH CIRCUMFLEX AND ACUTE. + + * groff maintains a table to decompose all algorithmically derived + glyph names that are composites itself. For example, 'u0100' + (LATIN LETTER A WITH MACRON) is automatically decomposed into + 'u0041_0304'. Additionally, a glyph name of the GGL is preferred + to an algorithmically derived glyph name; 'groff' also + automatically does the mapping. Example: The glyph 'u0045_0302' is + mapped to '^E'. + + * glyph names of the GGL can't be used in composite glyph names; for + example, '^E_u0301' is invalid. + + -- Escape sequence: \(nm + -- Escape sequence: \[name] + -- Escape sequence: \[base-glyph combining-component ...] + Typeset a special character NAME (two-character name NM) or a + composite glyph consisting of BASE-GLYPH overlaid with one or more + COMBINING-COMPONENTs. For example, '\[A ho]' is a capital letter + "A" with a "hook accent" (ogonek). + + There is no special syntax for one-character names--the analogous + form '\N' would collide with other escape sequences. However, the + four escape sequences '\'', '\-', '\_', and '\`', are translated on + input to the special character escape sequences '\[aa]', '\[-]', + '\[ul]', and '\[ga]', respectively. + + A special character name of length one is not the same thing as an + ordinary character: that is, the character 'a' is not the same as + '\[a]'. + + If NAME is undefined, a warning in category 'char' is produced and + the escape is ignored. *Note Warnings::, for information about the + enablement and suppression of warnings. + + GNU 'troff' resolves '\[...]' with more than a single component as + follows: + + * Any component that is found in the GGL is converted to the + 'uXXXX' form. + + * Any component 'uXXXX' that is found in the list of + decomposable glyphs is decomposed. + + * The resulting elements are then concatenated with '_' in + between, dropping the leading 'u' in all elements but the + first. + + No check for the existence of any component (similar to 'tr' + request) is done. + + Examples: + + '\[A ho]' + 'A' maps to 'u0041', 'ho' maps to 'u02DB', thus the final + glyph name would be 'u0041_02DB'. This is not the expected + result: the ogonek glyph 'ho' is a spacing ogonek, but for a + proper composite a non-spacing ogonek (U+0328) is necessary. + Looking into the file 'composite.tmac', one can find + '.composite ho u0328', which changes the mapping of 'ho' while + a composite glyph name is constructed, causing the final glyph + name to be 'u0041_0328'. + + '\[^E u0301]' + '\[^E aa]' + '\[E a^ aa]' + '\[E ^ ']' + '^E' maps to 'u0045_0302', thus the final glyph name is + 'u0045_0302_0301' in all forms (assuming proper calls of the + 'composite' request). + + It is not possible to define glyphs with names like 'A ho' within a + 'groff' font file. This is not really a limitation; instead, you + have to define 'u0041_0328'. + + -- Escape sequence: \C'xxx' + Typeset the glyph of the special character XXX. Normally, it is + more convenient to use '\[XXX]', but '\C' has some advantages: it + is compatible with AT&T device-independent 'troff' (and therefore + available in compatibility mode(3) (*note Using + Symbols-Footnote-3::)) and can interpolate special characters with + ']' in their names. The delimiter need not be a neutral + apostrophe; see *note Delimiters::. + + -- Request: .composite id1 id2 + Map special character name ID1 to ID2 if ID1 is used in '\[...]' + 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 + 'composite.tmac', loaded by the default 'troffrc' at startup. + + -- Escape sequence: \N'n' + Typeset the glyph with code N in the current font ('n' is _not_ the + input character code). The number N can be any non-negative + decimal integer. Most devices only have glyphs with codes between + 0 and 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 _not_ searched. The '\N' escape sequence + can be conveniently used in conjunction with the 'char' request: + + .char \[phone] \f[ZD]\N'37' + + The code of each glyph is given in the fourth column in the font + description file after the 'charset' command. It is possible to + include unnamed glyphs in the font description file by using a name + of '---'; the '\N' escape sequence is the only way to use these. + + No kerning is applied to glyphs accessed with '\N'. The delimiter + need not be a neutral apostrophe; see *note Delimiters::. + + A few escape sequences are also special characters. + + -- Escape sequence: \' + An escaped neutral apostrophe is a synonym for '\[aa]' (acute + accent). + + -- Escape sequence: \` + An escaped grave accent is a synonym for '\[ga]' (grave accent). + + -- Escape sequence: \- + An escaped hyphen-minus is a synonym for '\[-]' (minus sign). + + -- Escape sequence: \_ + An escaped underscore ("low line") is a synonym for '\[ul]' + (underrule). On typesetting devices, the underrule is + font-invariant and drawn lower than the underscore '_'. + + -- Request: .cflags n c1 c2 ... + Assign properties encoded by the number N to characters C1, C2, and + so on. + + Input characters, including special characters introduced by an + escape, have certain properties associated with them.(4) (*note + Using Symbols-Footnote-4::) 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 CN arguments are optional. Any + argument CN can be a character class defined with the 'class' + request rather than an individual character. *Note Character + Classes::. + + The non-negative integer N is the sum of any of the following. + Some combinations are nonsensical, such as '33' (1 + 32). + + '1' + Recognize the character as ending a sentence if followed by a + newline or two spaces. Initially, characters '.?!' have this + property. + + '2' + 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. + + '4' + 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 + '\-\[hy]\[em]' have this property. + + '8' + Mark the glyph associated with this character as overlapping + other instances of itself horizontally. Initially, characters + '\[ul]\[rn]\[ru]\[radicalex]\[sqrtex]' have this property. + + '16' + Mark the glyph associated with this character as overlapping + other instances of itself vertically. Initially, the + character '\[br]' has this property. + + '32' + Mark the character as transparent for the purpose of + end-of-sentence recognition. In other words, an + end-of-sentence character followed by any number of 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 + '"')]*\[dg]\[dd]\[rq]\[cq]' have this property. + + '64' + Ignore hyphenation codes of the surrounding characters. Use + this in combination with values 2 and 4 (initially, no + characters have this property). + + For example, if you need an automatic break point after the + en-dash in numeric ranges like "3000-5000", insert + + .cflags 68 \[en] + + into your document. However, this practice can lead to bad + layout if done thoughtlessly; in most situations, a better + solution instead of changing the 'cflags' value is to insert + '\:' right after the hyphen at the places that really need a + break point. + + The remaining values were implemented for East Asian language + support; those who use alphabetic scripts exclusively can disregard + them. + + '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. + + '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. + + '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. + + In contrast to values 2 and 4, the values 128, 256, and 512 work + pairwise. If, for example, the left character has value 512, and + the right character 128, no break will be automatically inserted + between them. If we use value 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. + + -- Request: .char c [contents] + -- Request: .fchar c [contents] + -- Request: .fschar f c [contents] + -- Request: .schar c [contents] + Define a new character or glyph C to be CONTENTS, which can be + empty. More precisely, 'char' defines a 'groff' object (or + redefines an existing one) that is accessed with the name C on + input, and produces CONTENTS on output. Every time glyph C needs + to be printed, 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 '\' while CONTENTS + is processed. Any emboldening, constant spacing, or track kerning + is applied to this object rather than to individual glyphs in + 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 'tr' or 'trin' + requests; it can be made the leader character with the 'lc' + request; repeated patterns can be drawn with it using the '\l' and + '\L' escape sequences; and words containing C can be hyphenated + correctly if the '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 'char'). + + The 'tr' and 'trin' requests take precedence if 'char' accesses the + same symbol. + + .tr XY + X + => Y + .char X Z + X + => Y + .tr XX + X + => Z + + The 'fchar' request defines a fallback glyph: 'gtroff' only checks + for glyphs defined with 'fchar' if it cannot find the glyph in the + current font. 'gtroff' carries out this test before checking + special fonts. + + 'fschar' defines a fallback glyph for font F: 'gtroff' checks for + glyphs defined with 'fschar' after the list of fonts declared as + font-specific special fonts with the 'fspecial' request, but before + the list of fonts declared as global special fonts with the + 'special' request. + + Finally, the 'schar' request defines a global fallback glyph: + 'gtroff' checks for glyphs defined with 'schar' after the list of + fonts declared as global special fonts with the 'special' request, + but before the already mounted special fonts. + + *Note Character Classes::. + + -- Request: .rchar c ... + -- Request: .rfschar f c ... + Remove definition of each ordinary or special character C, undoing + the effect of a 'char', 'fchar', or 'schar' request. Those + supplied by font description files cannot be removed. Spaces and + tabs may separate C arguments. + + The request 'rfschar' removes glyph definitions defined with + 'fschar' for font F. + + (1) Not all versions of the 'man' program support the '-T' option; +use the subsequent example for an alternative. + + (2) This is "Normalization Form D" as documented in Unicode Standard +Annex #15 (<https://unicode.org/reports/tr15/>). + + (3) *Note Compatibility Mode::. + + (4) Output glyphs don't--to GNU '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. + +5.19.5 Character Classes +------------------------ + +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. + + -- Request: .class name c1 c2 ... + Define a character class (or simply "class") NAME comprising the + characters C1, 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 'cflags' request can + handle references to character classes. + + In the request's simplest form, each CN is a character (or special + character). + + .class [quotes] ' \[aq] \[dq] \[oq] \[cq] \[lq] \[rq] + + Since class and glyph names share the same name space, it is + recommended to start and end the class name with '[' and ']', + respectively, to avoid collisions with existing character names + defined by GNU 'troff' or the user (with 'char' and related + requests). This practice applies the presence of ']' in the class + name to prevent the use of the special character escape form + '\[...]', thus you must use the '\C' escape to access a class with + such a name. + + You can also use a character range notation consisting of a start + character followed by '-' and then an end character. Internally, + GNU 'troff' converts these two symbol names to Unicode code points + (according to the '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. + + .class [prepunct] , : ; > } + .class [prepunctx] \C'[prepunct]' \[u2013]-\[u2016] + + The class '[prepunctx]' thus contains the contents of the class + '[prepunct]' as defined above (the set ', : ; > }'), and characters + in the range between 'U+2013' and 'U+2016'. + + If you want to include '-' 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 'class' request is to control line-breaking + and hyphenation rules as defined by the 'cflags' request. For + example, to inhibit line breaks before the characters belonging to + the 'prepunctx' class defined in the previous example, you can + write the following. + + .cflags 2 \C'[prepunctx]' + + See the 'cflags' request in *note Using Symbols::, for more + details. + +5.19.6 Special Fonts +-------------------- + +Special fonts are those that 'gtroff' searches when it cannot find the +requested glyph in the current font. The Symbol font is usually a +special font. + + 'gtroff' provides the following two requests to add more special +fonts. *Note Using Symbols::, for a detailed description of the glyph +searching mechanism in 'gtroff'. + + Usually, only non-TTY devices have special fonts. + + -- Request: .special [s1 s2 ...] + -- Request: .fspecial f [s1 s2 ...] + Use the 'special' request to define special fonts. Initially, this + list is empty. + + Use the 'fspecial' request to designate special fonts only when + font F is active. Initially, this list is empty. + + Previous calls to 'special' or '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 'special' or 'fspecial' are + loaded. + + *Note Using Symbols::, for the exact search order of glyphs. + +5.19.7 Artificial Fonts +----------------------- + +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 'nroff' and +'troff' were separate programs. Most of them are no longer necessary in +GNU 'troff'. Nevertheless, they are supported. + + -- Escape sequence: \H'height' + -- Escape sequence: \H'+height' + -- Escape sequence: \H'-height' + -- Register: \n[.height] + Change (increment, decrement) the height of the current font, but + not the width. If HEIGHT is zero, restore the original height. + Default scaling unit is 'z'. + + The read-only register '.height' contains the font height as set by + '\H'. + + Currently, only the '-Tps' and '-Tpdf' devices support this + feature. + + '\H' doesn't produce an input token in GNU 'troff'. As a + consequence, it can be used in requests like 'mc' (which expects a + single character as an argument) to change the font on the fly: + + .mc \H'+5z'x\H'0' + + In compatibility mode, '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, + + .cp 1 + \H'+5'test \H'+5'test + + prints the word 'test' twice with the same font height (five points + larger than the current font size). + + -- Escape sequence: \S'slant' + -- Register: \n[.slant] + Slant the current font by SLANT degrees. Positive values slant to + the right. Only integer values are possible. + + The read-only register '.slant' contains the font slant as set by + '\S'. + + Currently, only the '-Tps' and '-Tpdf' devices support this + feature. + + '\S' doesn't produce an input token in GNU 'troff'. As a + consequence, it can be used in requests like 'mc' (which expects a + single character as an argument) to change the font on the fly: + + .mc \S'20'x\S'0' + + This escape is incorrectly documented in the AT&T 'troff' manual; + the slant is always set to an absolute value. + + -- Request: .ul [lines] + The '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 LINES is zero or + negative, stop the effects of '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 'tl'. Lines + inserted by macros (e.g., invoked by a trap) do count. + + At the beginning of 'ul', the current font is stored and the + underline font is activated. Within the span of a 'ul' request, it + is possible to change fonts, but after the last line affected by + 'ul' the saved font is restored. + + This number of lines still to be underlined is associated with the + environment (*note Environments::). The underline font can be + changed with the 'uf' request. + + The 'ul' request does not underline spaces. + + -- Request: .cu [lines] + The 'cu' request is similar to 'ul' but underlines spaces as well + (if a TTY output device is used). + + -- Request: .uf font + Set the underline font (globally) used by 'ul' and 'cu'. By + default, this is the font at position 2. FONT can be either a + non-negative font position or the name of a font. + + -- Request: .bd font [offset] + -- Request: .bd font1 font2 [offset] + -- Register: \n[.b] + Embolden FONT by overstriking its glyphs offset by OFFSET units + minus one. + + Two syntax forms are available. + + * 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. + + FONT can be either a non-negative font position or the name of + a font. + + OFFSET is available in the '.b' read-only register if a + special font is active; in the 'bd' request, its default unit + is 'u'. + + * Imitate a bold form conditionally. Embolden FONT1 by OFFSET + only if font 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 + 'special' command in font files or with the 'fspecial' + request). + + -- Request: .cs font [width [em-size]] + Switch to and from "constant glyph space mode". If activated, the + width of every glyph is WIDTH/36 ems. The em size is given + absolutely by EM-SIZE; if this argument is missing, the em value is + taken from the current font size (as set with the 'ps' request) + when the font is effectively in use. Without second and third + argument, constant glyph space mode is deactivated. + + Default scaling unit for EM-SIZE is 'z'; WIDTH is an integer. + +5.19.8 Ligatures and Kerning +---------------------------- + +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 AT&T 'troff' also supported 'ff', +'ffi', and 'ffl' ligatures. Advanced typesetters or 'expert' fonts may +include ligatures for 'ft' and 'ct', although GNU '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 'char' request (and +its siblings) are taken into account. + + -- Request: .lg [flag] + -- Register: \n[.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 '.lg' (set to 1 or 2 if ligatures are enabled, + 0 otherwise). + + Setting the ligature mode to 2 enables the two-character ligatures + (fi, fl, and ff) and disables the three-character ligatures (ffi + and ffl). + + "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. Typewriter-like +fonts and fonts for terminals where all glyphs have the same width don't +use kerning. + + -- Request: .kern [flag] + -- Register: \n[.kern] + Switch kerning on or off. If the parameter is non-zero or missing, + enable pairwise kerning, otherwise disable it. The read-only + register '.kern' is set to 1 if pairwise kerning is enabled, + 0 otherwise. + + If the font description file contains pairwise kerning information, + glyphs from that font are kerned. Kerning between two glyphs can + be inhibited by placing '\&' between them: 'V\&A'. + + *Note Font Description File Format::. + + "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. + + -- Request: .tkf f s1 n1 s2 n2 + Enable track kerning for font F. If the current font is F the + width of every glyph is increased by an amount between N1 and N2 + (N1, N2 can be negative); if the current type size is less than or + equal to S1 the width is increased by N1; if it is greater than or + equal to S2 the width is increased by N2; if the type size is + greater than or equal to S1 and less than or equal to S2 the + increase in width is a linear function of the type size. + + The default scaling unit is 'z' for S1 and S2, 'p' for N1 and 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. + +5.19.9 Italic Corrections +------------------------- + +When typesetting adjacent glyphs from typefaces of different slants, the +space between them may require adjustment. + + -- Escape sequence: \/ + Apply an "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 'f' is followed immediately by a roman right parenthesis, + then in many fonts the top right portion of the '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. + + -- Escape sequence: \, + Apply a "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 'f', then in many fonts the bottom left portion of the '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. + +5.19.10 Dummy Characters +------------------------ + +As discussed in *note Requests and Macros::, the first character on an +input line is treated specially. Further, formatting a glyph has many +consequences on formatter state (*note Environments::). Occasionally, +we want to escape this context or embrace some of those consequences +without actually rendering a glyph to the output. + + -- Escape sequence: \& + Interpolate a dummy character, which is constitutive of output but + invisible.(1) (*note Dummy Characters-Footnote-1::) Its presence + alters the interpretation context of a subsequent input character, + and enjoys several applications. + + * Prevent insertion of extra space after an end-of-sentence + character. + + Test. + Test. + => Test. Test. + Test.\& + Test. + => Test. Test. + + * Prevent recognition of a control character. + + .Test + error-> warning: macro 'Test' not defined + \&.Test + => .Test + + * Prevent kerning between two glyphs. + + * Translate a character to "nothing". + + .tr JIjiK\&k\&UVuv + Post universitum, alea jacta est, OK? + => Post vniversitvm, alea iacta est, O? + + 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. + + .de HD \" typeset a simple bold heading + . sp + . ft B + \&\\$1 \" exercise: remove the \& + . ft + . sp + .. + .HD .\|.\|.\|surprised? + + One way to think about the dummy character is to imagine placing the +symbol '&' 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. + + -- Escape sequence: \) + Interpolate a transparent dummy character--one that is transparent + to end-of-sentence detection. It behaves as '\&', except that '\&' + is treated as letters and numerals normally are after '.', '?' and + '!'; '\&' cancels end-of-sentence detection, and '\)' does not. + + .de Suffix-& + . nop \&\\$1 + .. + . + .de Suffix-) + . nop \)\\$1 + .. + . + Here's a sentence.\c + .Suffix-& ' + Another one.\c + .Suffix-) ' + And a third. + => Here's a sentence.' Another one.' And a third. + + (1) Opinions of this escape sequence's name abound. "Zero-width +space" is a popular misnomer: 'roff' formatters do not treat it like a +space. Ossanna called it a "non-printing, zero-width character", but +the character causes _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 '\&'. The former produces +no output; the latter, a blank page. + +5.20 Manipulating Type Size and Vertical Spacing +================================================ + +These concepts were introduced in *note Page Geometry::. The height of +a font's tallest glyph is one em, which is equal to the type size in +points.(1) (*note Manipulating Type Size and Vertical +Spacing-Footnote-1::) 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 'troff' uses 10 point type on 12 point spacing. Typographers call +the difference between type size and vertical spacing "leading".(2) +(*note Manipulating Type Size and Vertical Spacing-Footnote-2::) + + (1) 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 points. + + (2) Rhyme with "sledding"; mechanical typography used lead metal +(Latin _plumbum_). + +5.20.1 Changing the Type Size +----------------------------- + + -- Request: .ps [size] + -- Request: .ps +size + -- Request: .ps -size + -- Escape sequence: \ssize + -- Register: \n[.s] + Use the 'ps' request or the '\s' escape sequence to change + (increase, decrease) the type size (in scaled points). Specify + SIZE as either an absolute type size, or as a relative change from + the current size. 'ps' with no argument restores the previous + size. The 'ps' request's default scaling unit is '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 1u. + + Type size alteration is incorrectly documented in the AT&T 'troff' + manual, which claims "if [the requested size] is invalid, the next + larger valid size will result, with a maximum of 36".(1) (*note + Changing the Type Size-Footnote-1::) + + The read-only string-valued register '.s' interpolates the type + size in points as a decimal fraction; it is associated with the + environment (*note Environments::). To obtain the type size in + scaled points, interpolate the '.ps' register instead (*note Using + Fractional Type Sizes::). + + The '\s' escape sequence supports a variety of syntax forms. + + '\sN' + Set the type size to N points. N must be a single digit. If + N is 0, restore the previous size. + + '\s+N' + '\s-N' + Increase or decrease the type size by N points. N must be + exactly one digit. + + '\s(NN' + Set the type size to NN points. NN must be exactly two + digits. + + '\s+(NN' + '\s-(NN' + '\s(+NN' + '\s(-NN' + Alter the type size in points by the two-digit value NN. + + *Note Using Fractional Type Sizes::, for further syntactical forms + of the '\s' escape sequence that additionally accept decimal + fractions. + + snap, snap, + .ps +2 + grin, grin, + .ps +2 + wink, wink, \s+2nudge, nudge,\s+8 say no more! + .ps 10 + + The '\s' escape sequence affects the environment immediately and +doesn't produce an input token. Consequently, it can be used in +requests like 'mc', which expects a single character as an argument, to +change the type size on the fly. + + .mc \s[20]x\s[0] + + -- Request: .sizes s1 s2 ... sn [0] + The 'DESC' file specifies which type sizes are allowed by the + output device; see *note DESC File Format::. Use the 'sizes' + request to change this set of permissible sizes. Arguments are in + scaled points; see *note Using Fractional Type Sizes::. Each can + be a single type size (such as '12000'), or a range of sizes (such + as '4000-72000'). You can optionally end the list with a '0'. + + (1) The claim appears to have been true of Ossanna 'troff' for the +C/A/T device; Kernighan made device-independent 'troff' more flexible. + +5.20.2 Changing the Vertical Spacing +------------------------------------ + + -- Request: .vs [space] + -- Request: .vs +space + -- Request: .vs -space + -- Register: \n[.v] + Set the vertical spacing to, or alter it by, SPACE. The default + scaling unit is 'p'. If 'vs' is called without an argument, the + vertical spacing is reset to the previous value before the last + call to 'vs'. GNU 'troff' emits a warning in category 'range' if + SPACE is negative; the vertical spacing is then set to the smallest + possible positive value, the vertical motion quantum (as found in + the '.V' register). + + '.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 '.v' contains the vertical spacing; it is + associated with the environment (*note Environments::). + +When a break occurs, GNU 'troff' performs the following procedure. + + * Move the drawing position vertically by the "extra pre-vertical + line space", the minimum of all negative '\x' escape sequence + arguments in the pending output line. + + * Move the drawing position vertically by the vertical line spacing. + + * Write out the pending output line. + + * Move the drawing position vertically by the "extra post-vertical + line space", the maximum of all positive '\x' escape sequence + arguments in the line that has just been output. + + * Move the drawing position vertically by the "post-vertical line + spacing" (see below). + + Prefer 'vs' or 'pvs' over 'ls' to produce double-spaced documents. +'vs' and 'pvs' have finer granularity than 'ls'; moreover, some +preprocessors assume single spacing. *Note Manipulating Spacing::, +regarding the '\x' escape sequence and the 'ls' request. + + -- Request: .pvs [space] + -- Request: .pvs +space + -- Request: .pvs -space + -- Register: \n[.pvs] + Set the post-vertical spacing to, or alter it by, SPACE. The + default scaling unit is 'p'. If 'pvs' is called without an + argument, the post-vertical spacing is reset to the previous value + before the last call to 'pvs'. GNU 'troff' emits a warning in + category 'range' if SPACE is negative; the post-vertical spacing is + then set to zero. + + The read-only register '.pvs' contains the post-vertical spacing; + it is associated with the environment (*note Environments::). + +5.20.3 Using Fractional Type Sizes +---------------------------------- + +AT&T '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 '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. + + A "scaled point" is equal to 1/SIZESCALE points, where SIZESCALE is +specified in the device description file 'DESC', and defaults to 1.(1) +(*note Using Fractional Type Sizes-Footnote-1::) Requests and escape +sequences in GNU 'troff' interpret arguments that represent a type size +in scaled points, which the formatter multiplies by SIZESCALE and +converts to an integer. Arguments treated in this way comprise those to +the escape sequences '\H' and '\s', to the request 'ps', the third +argument to the 'cs' request, and the second and fourth arguments to the +'tkf' request. Scaled points may be specified explicitly with the 'z' +scaling unit. + + For example, if SIZESCALE is 1000, then a scaled point is one +thousandth of a point. The request '.ps 10.5' is synonymous with '.ps +10.5z' and sets the type size to 10,500 scaled points, or 10.5 points. +Consequently, in GNU 'troff', the register '.s' can interpolate a +non-integral type size. + + -- Register: \n[.ps] + This read-only register interpolates the type size in scaled + points; it is associated with the environment (*note + Environments::). + + It makes no sense to use the 'z' scaling unit in a numeric expression +whose default scaling unit is neither 'u' nor 'z', so GNU 'troff' +disallows this. Similarly, it is nonsensical to use a scaling unit +other than 'z' or 'u' in a numeric expression whose default scaling unit +is 'z', and so GNU 'troff' disallows this as well. + + Another GNU 'troff' scaling unit, 's', multiplies by the number of +basic units in a scaled point. Thus, '\n[.ps]s' is equal to '1m' by +definition. Do not confuse the 's' and 'z' scaling units. + + -- Register: \n[.psr] + -- Register: \n[.sr] + Output devices may be limited in the type sizes they can employ. + The '.s' and '.ps' registers represent the type size selected by + the output driver as it understands a device's capability. The + last _requested_ type size is interpolated in scaled points by the + read-only register '.psr' and in points as a decimal fraction by + the read-only string-valued register '.sr'. Both are associated + with the environment (*note Environments::). + + For example, if a type size of 10.95 points is requested, and the + nearest size permitted by a 'sizes' request (or by the 'sizes' or + 'sizescale' directives in the device's 'DESC' file) is 11 points, + the output driver uses the latter value. + + The '\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 *note Delimiters::. + +'\s[N]' +'\s'N'' + Set the type size to N scaled points; N is a numeric expression + with a default scaling unit of 'z'. + +'\s[+N]' +'\s[-N]' +'\s+[N]' +'\s-[N]' +'\s'+N'' +'\s'-N'' +'\s+'N'' +'\s-'N'' + Increase or decrease the type size by N scaled points; N is a + numeric expression (which may start with a minus sign) with a + default scaling unit of 'z'. + + (1) *Note Device and Font Description Files::. + +5.21 Colors +=========== + +GNU '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 "stroke color", with which glyphs, rules (lines), +and geometric objects like circles and polygons are drawn, and the "fill +color", which can be used to paint the interior of a closed geometric +figure. + + -- Request: .color [n] + -- Register: \n[.color] + If 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 (*note Gtroff Internals::). + + The read-only register '.color' is 1 if colors are enabled, + 0 otherwise. + + Color can also be disabled with the '-c' command-line option. + + -- Request: .defcolor ident scheme color-component ... + Define a color named IDENT. SCHEME selects a color space and + determines the quantity of required COLOR-COMPONENTs; it must be + one of 'rgb' (three components), 'cmy' (three), 'cmyk' (four), or + 'gray' (one). 'grey' is accepted as a synonym of 'gray'. The + color components can be encoded as a single hexadecimal value + starting with '#' or '##'. The former indicates that each + component is in the range 0-255 (0-FF), the latter the range + 0-65,535 (0-FFFF). + + .defcolor half gray #7f + .defcolor pink rgb #FFC0CB + .defcolor magenta rgb ##ffff0000ffff + + Alternatively, each color component can be specified as a decimal + fraction in the range 0-1, interpreted using a default scaling unit + of 'f', which multiplies its value by 65,536 (but clamps it at + 65,535). + + .defcolor gray50 rgb 0.5 0.5 0.5 + .defcolor darkgreen rgb 0.1f 0.5f 0.2f + + Each output device has a color named 'default', which cannot be +redefined. A device's default stroke and fill colors are not +necessarily the same. For the 'dvi', 'html', 'pdf', 'ps', and 'xhtml' +output devices, GNU 'troff' automatically loads a macro file defining +many color names at startup. By the same mechanism, the devices +supported by 'grotty' recognize the eight standard ISO 6429/EMCA-48 +color names.(1) (*note Colors-Footnote-1::) + + -- Request: .gcolor [color] + -- Escape sequence: \mc + -- Escape sequence: \m(co + -- Escape sequence: \m[color] + -- Register: \n[.m] + Set the stroke color to COLOR. + + .gcolor red + The next words + .gcolor + \m[red]are in red\m[] + and these words are in the previous color. + + The escape sequence '\m[]' restores the previous stroke color, as + does a 'gcolor' request without an argument. + + The name of the current stroke color is available in the read-only + string-valued register '.m'; it is associated with the environment + (*note Environments::). It interpolates nothing when the stroke + color is the default. + + '\m' doesn't produce an input token in GNU 'troff' (*note Gtroff + Internals::). It therefore can be used in requests like 'mc' + (which expects a single character as an argument) to change the + color on the fly: + + .mc \m[red]x\m[] + + -- Request: .fcolor [color] + -- Escape sequence: \Mc + -- Escape sequence: \M(co + -- Escape sequence: \M[color] + -- Register: \n[.M] + Set the fill color for objects drawn with '\D'...'' escape + sequences. The escape sequence '\M[]' restores the previous fill + color, as does an 'fcolor' request without an argument. + + The name of the current fill color is available in the read-only + string-valued register '.M'; it is associated with the environment + (*note Environments::). It interpolates nothing when the fill + color is the default. '\M' doesn't produce an input token in GNU + 'troff'. + + Create an ellipse with a red interior as follows. + + \M[red]\h'0.5i'\D'E 2i 1i'\M[] + + (1) also known vulgarly as "ANSI colors" + +5.22 Strings +============ + +GNU '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. + + -- String: \*[.T] + Contains the name of the output device (for example, 'utf8' or + 'pdf'). + + The 'ds' request creates a string with a specified name and contents +and the '\*' escape sequence dereferences its name, interpolating its +contents. If the string named by the '\*' escape sequence does not +exist, it is defined as empty, nothing is interpolated, and a warning in +category 'mac' is emitted. *Note Warnings::, for information about the +enablement and suppression of warnings. + + -- Request: .ds name [contents] + -- Request: .ds1 name [contents] + -- Escape sequence: \*n + -- Escape sequence: \*(nm + -- Escape sequence: \*[name [arg1 arg2 ...]] + Define a string called NAME with contents CONTENTS. If NAME + already exists as an alias, the target of the alias is redefined; + see 'als' and 'rm' below. If 'ds' is called with only one + argument, NAME is defined as an empty string. Otherwise, GNU + 'troff' stores CONTENTS in copy mode.(1) (*note + Strings-Footnote-1::) + + The '\*' escape sequence interpolates a previously defined string + variable NAME (one-character name N, two-character name NM). The + bracketed interpolation form accepts arguments that are handled as + macro arguments are; recall *note Calling Macros::. In contrast to + macro calls, however, if a closing bracket ']' occurs in a string + argument, that argument must be enclosed in double quotes. '\*' is + interpreted even in copy mode. When defining strings, argument + interpolations must be escaped if they are to reference parameters + from the calling context; *Note Parameters::. + + .ds cite (\\$1, \\$2) + Gray codes are explored in \*[cite Morgan 1998]. + => Gray codes are explored in (Morgan, 1998). + + *Caution:* Unlike other requests, the second argument to the '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. + + .ds H2O H\v'+.3m'\s'-2'2\v'-.3m'\s0O \" water + + Instead, place the comment on another line or put the comment + escape sequence immediately adjacent to the last character of the + string. + + .ds H2O H\v'+.3m'\s'-2'2\v'-.3m'\s0O\" water + + Ending string definitions (and appendments) with a comment, even an + empty one, prevents unwanted space from creeping into them during + source document maintenance. + + .ds author Alice Pleasance Liddell\" + .ds empty \" might be appended to later with .as + + An initial neutral double quote '"' in CONTENTS is stripped to + allow embedding of leading spaces. Any other '"' is interpreted + literally, but it is wise to use the special character escape + sequence '\[dq]' instead if the string might be interpolated as + part of a macro argument; see *note Calling Macros::. + + .ds salutation " Yours in a white wine sauce,\" + .ds c-var-defn " char mydate[]=\[dq]2020-07-29\[dq];\" + + Strings are not limited to a single input line of text. '\<RET>' + works just as it does elsewhere. The resulting string is stored + _without_ the newlines. Care is therefore required when + interpolating strings while filling is disabled. + + .ds foo This string contains \ + text on multiple lines \ + of input. + + 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 '\*' to interpolate a macro instead; see *note + Punning Names::. + + Because strings are similar to macros, they too can be defined so + as to suppress AT&T 'troff' compatibility mode when used; see *note + Writing Macros:: and *note Compatibility Mode::. The 'ds1' request + defines a string such that compatibility mode is off when the + string is later interpolated. To be more precise, a "compatibility + save" input token is inserted at the beginning of the string, and a + "compatibility restore" input token at the end. + + .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 + => The value of xxx is 0xxx]. + \*(bb + => The value of xxx is 12345. + + -- Request: .as name [contents] + -- Request: .as1 name [contents] + The 'as' request is similar to 'ds' but appends CONTENTS to the + string stored as NAME instead of redefining it. If NAME doesn't + exist yet, it is created. If 'as' is called with only one + argument, no operation is performed (beyond dereferencing the + string). + + .as salutation " with shallots, onions and garlic,\" + + The 'as1' request is similar to 'as', but compatibility mode is + switched off when the appended portion of the string is later + interpolated. To be more precise, a "compatibility save" input + token is inserted at the beginning of the appended string, and a + "compatibility restore" input token at the end. + + Several requests exist to perform rudimentary string operations. +Strings can be queried ('length') and modified ('chop', 'substring', +'stringup', 'stringdown'), and their names can be manipulated through +renaming, removal, and aliasing ('rn', 'rm', 'als'). + + -- Request: .length reg anything + Compute the number of characters of ANYTHING and store the count in + the register REG. If REG doesn't exist, it is created. ANYTHING + is read in copy mode. + + .ds xxx abcd\h'3i'efgh + .length yyy \*[xxx] + \n[yyy] + => 14 + + -- Request: .chop object + Remove the last character from the macro, string, or diversion + named OBJECT. This is useful for removing the newline from the end + of a diversion that is to be interpolated as a string. This + request can be used repeatedly on the same OBJECT; see *note Gtroff + Internals::, for details on nodes inserted additionally by GNU + 'troff'. + + -- Request: .substring str start [end] + Replace the string named STR with its substring bounded by the + indices START and END, inclusively. The first character in the + string has index 0. If 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 -1, the character before the last has index -2, + and so on. + + .ds xxx abcdefgh + .substring xxx 1 -4 + \*[xxx] + => bcde + .substring xxx 2 + \*[xxx] + => de + + -- Request: .stringdown str + -- Request: .stringup str + Alter the string named STR by replacing each of its bytes with its + lowercase ('stringdown') or uppercase ('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. + + .ds resume R\['e]sum\['e] + \*[resume] + .stringdown resume + \*[resume] + .stringup resume + \*[resume] + => Résumé résumé RÉSUMÉ + + (In practice, we would end the 'ds' request with a comment escape +'\"' to prevent space from creeping into the definition during source +document maintenance.) + + -- Request: .rn old new + Rename the request, macro, diversion, or string OLD to NEW. + + -- Request: .rm name + Remove the request, macro, diversion, or string NAME. GNU 'troff' + treats subsequent invocations as if the name had never been + defined. + + -- Request: .als new old + Create an alias NEW for the existing request, string, macro, or + diversion object named OLD, causing the names to refer to the same + stored object. If OLD is undefined, a warning in category 'mac' is + produced, and the request is ignored. *Note Warnings::, for + information about the enablement and suppression of warnings. + + To understand how the '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 'troff' adds it to + the object pool, adds its name to the name pool, and creates a link + between them. When '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. + + .de foo + .. + . + .als bar foo + . + .de bar + . foo + .. + . + .bar + error-> input stack limit exceeded (probable infinite + error-> loop) + + In the above, 'bar' remains an _alias_--another name for--the + object referred to by 'foo', which the second 'de' request + replaces. Alternatively, imagine that the 'de' request + _dereferences_ its argument before replacing it. Either way, the + result of calling 'bar' is a recursive loop that finally leads to + an error. *Note Writing Macros::. + + To remove an alias, call '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 + 'rm' request on its name first. + + (1) *Note Copy Mode::. + +5.23 Conditionals and Loops +=========================== + +'groff' has 'if' and 'while' control structures like other languages. +However, the syntax for grouping multiple input lines in the branches or +bodies of these structures is unusual. + +5.23.1 Operators in Conditionals +-------------------------------- + +In 'if', 'ie', and 'while' requests, in addition to the numeric +expressions described in *note Numeric Expressions::, several Boolean +operators are available; the members of this expanded class are termed +"conditional expressions". + +'c GLYPH' + True if GLYPH is available, where GLYPH is an ordinary character, a + special character '\(XX' or '\[XXX]', '\N'XXX'', or has been + defined by any of the 'char', 'fchar', 'fschar', or 'schar' + requests. + +'d NAME' + True if a string, macro, diversion, or request called NAME exists. + +'e' + True if the current page is even-numbered. + +'F FONT' + True if FONT exists. FONT is handled as if it were opened with the + 'ft' request (that is, font translation and styles are applied), + without actually mounting it. + +'m COLOR' + True if COLOR is defined. + +'n' + True if the document is being processed in 'nroff' mode. *Note + troff and nroff Modes::. + +'o' + True if the current page is odd-numbered. + +'r REGISTER' + True if REGISTER exists. + +'S STYLE' + True if STYLE is available for the current font family. Font + translation is applied. + +'t' + True if the document is being processed in 'troff' mode. *Note + troff and nroff Modes::. + +'v' + Always false. This condition is recognized only for compatibility + with certain other 'troff' implementations.(1) (*note Operators in + Conditionals-Footnote-1::) + + If the first argument to an 'if', 'ie', or 'while' request begins +with a non-alphanumeric character apart from '!' (see below); it +performs an output comparison test. (2) (*note Operators in +Conditionals-Footnote-2::) + +''XXX'YYY'' + True if formatting the comparands XXX and 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 *note Delimiters::. This "output comparison + operator" formats XXX and YYY in separate environments; after the + comparison, the resulting data are discarded. + + .ie "|"\fR|\fP" true + .el false + => true + + 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, '|' + and '\fR|\fP' result in '|' glyphs in the same typefaces at the + same positions, so the comparands are equal. If '.ft I' had been + added before the '.ie', they would differ: the first '|' would + produce an italic '|', 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. '.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.(3) (*note Operators in + Conditionals-Footnote-3::) On the other hand, '.if "\d"\v'0.5m'"' + is true, because '\d' is defined as a downward motion of one-half + em.(4) (*note Operators in Conditionals-Footnote-4::) + + Surround the comparands with '\?' to avoid formatting them; this + causes them to be compared character by character, as with string + comparisons in other programming languages. + + .ie "\?|\?"\?\fR|\fP\?" true + .el false + => false + + Since comparands protected with '\?' are read in copy mode (*note + Copy Mode::), they need not even be valid 'groff' syntax. The + escape character is still lexically recognized, however, and + consumes the next character. + + .ds a \[ + .ds b \[ + .if '\?\*a\?'\?\*b\?' a and b equivalent + .if '\?\\?'\?\\?' backslashes equivalent + => a and b equivalent + + The above operators can't be combined with most others, but a leading +'!', not followed immediately by spaces or tabs, complements an +expression. + + .nr x 1 + .ie !r x register x is not defined + .el register x is defined + => register x is defined + + Spaces and tabs are optional immediately after the 'c', 'd', 'F', +'m', 'r', and 'S' operators, but right after '!', they end the predicate +and the conditional evaluates true.(5) (*note Operators in +Conditionals-Footnote-5::) + + .nr x 1 + .ie ! r x register x is not defined + .el register x is defined + => r x register x is not defined + +The unexpected '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. + + (1) This refers to 'vtroff', a translator that would convert the +C/A/T output from early-vintage AT&T 'troff' to a form suitable for +Versatec and Benson-Varian plotters. + + (2) Strictly, letters not otherwise recognized _are_ treated as +output comparison delimiters. For portability, it is wise to avoid +using letters not in the list above; for example, Plan 9 'troff' uses +'h' to test a mode it calls 'htmlroff', and GNU 'troff' may provide +additional operators in the future. + + (3) Because formatting of the comparands takes place in a dummy +environment, vertical motions within them cannot spring traps. + + (4) All of this is to say that the lists of output nodes created by +formatting XXX and YYY must be identical. *Note Gtroff Internals::. + + (5) This bizarre behavior maintains compatibility with AT&T 'troff'. + +5.23.2 if-then +-------------- + + -- Request: .if cond-expr anything + Evaluate the conditional expression COND-EXPR, and if it evaluates + true (or to a positive value), interpret the remainder of the line + ANYTHING as if it were an input line. Recall from *note Invoking + Requests:: that any quantity of spaces between arguments to + requests serves only to separate them; leading spaces in ANYTHING + are thus not seen. ANYTHING effectively _cannot_ be omitted; if + COND-EXPR is true and 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). + + super\c + tanker + .nr force-word-break 1 + super\c + .if ((\n[force-word-break] = 1) & \n[.int]) + tanker + => supertanker super tanker + + -- Request: .nop anything + Interpret ANYTHING as if it were an input line. This is similar to + '.if 1'. 'nop' is not really "no operation"; its argument _is_ + processed--unconditionally. It can be used to cause text lines to + share indentation with surrounding control lines. + + .als real-MAC MAC + .de wrapped-MAC + . tm MAC: called with arguments \\$@ + . nop \\*[real-MAC]\\ + .. + .als MAC wrapped-MAC + \# Later... + .als MAC real-MAC + + In the above, we've used aliasing, 'nop', and the interpolation of + a macro as a string to interpose a wrapper around the macro 'MAC' + (perhaps to debug it). + +5.23.3 if-else +-------------- + + -- Request: .ie cond-expr anything + -- Request: .el anything + Use the 'ie' and '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 'ie' branch + and the 'el' branch. + + .nr a 0 + .ie \na a is non-zero. + .nr a +1 + .el a was not positive but is now \na. + => a was not positive but is now 1. + + Another way in which 'el' is an ordinary request is that it does + not lexically "bind" more tightly to its 'ie' counterpart than it + does to any other request. This fact can surprise C programmers. + + .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 + => a is false + + To conveniently nest conditionals, keep reading. + +5.23.4 Conditional Blocks +------------------------- + +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 '\{' and '\}' define such +groups. These "conditional blocks" can furthermore be nested. + + -- Escape sequence: \{ + -- Escape sequence: \} + '\{' begins a conditional block; it must appear (after optional + spaces and tabs) immediately subsequent to the conditional + expression of an 'if', 'ie', or 'while' request,(1) (*note + Conditional Blocks-Footnote-1::) or as the argument to an 'el' + request. + + '\}' ends a condition block and should appear on a line with other + occurrences of itself as necessary to match '\{' sequences. It can + be preceded by a control character, spaces, and tabs. Input after + any quantity of '\}' sequences on the same line is processed only + if all of the preceding conditions to which they correspond are + true. Furthermore, a '\}' closing the body of a '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. + + *Caution:* Input lines using '\{' often end with '\RET', especially + in macros that consist primarily of control lines. Forgetting to + use '\RET' on an input line after '\{' is a common source of error. + + We might write the following in a page header macro. If we delete +'\RET', the header will carry an unwanted extra empty line (except on +page 1). + + .if (\\n[%] != 1) \{\ + . ie ((\\n[%] % 2) = 0) .tl \\*[even-numbered-page-title] + . el .tl \\*[odd-numbered-page-title] + .\} + + Let us take a closer look at how conditional blocks nest. + + A + .if 0 \{ B + C + D + \}E + F + => A F + + N + .if 1 \{ O + . if 0 \{ P + Q + R\} S\} T + U + => N O U + + The above behavior may challenge the intuition; it was implemented to +retain compatibility with AT&T 'troff'. For clarity, it is idiomatic to +end input lines with '\{' (followed by '\<RET>' if appropriate), and to +precede '\}' on an input line with nothing more than a control +character, spaces, tabs, and other instances of itself. + + We can use 'ie', 'el', and conditional blocks to simulate the +multi-way "switch" or "case" control structures of other languages. The +following example is adapted from the 'groff' 'man' package. +Indentation is used to clarify the logic. + + .\" 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 + .\}\}\}\}\}\}\}\} + + (1) *Note while::. + +5.23.5 while +------------ + +'groff' provides a looping construct: the 'while' request. Its syntax +matches the 'if' request. + + -- Request: .while cond-expr anything + Evaluate the conditional expression COND-EXPR, and repeatedly + execute ANYTHING unless and until COND-EXPR evaluates false. + ANYTHING, which is often a conditional block, is referred to as the + 'while' request's "body". + + .nr a 0 1 + .while (\na < 9) \{\ + \n+a, + .\} + \n+a + => 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 + + GNU 'troff' treats the body of a 'while' request similarly to that + of a 'de' request (albeit one not read in copy mode(1) (*note + while-Footnote-1::)), but stores it under an internal name and + deletes it when the loop finishes. The operation of a macro + containing a 'while' request can slow significantly if the 'while' + body is large. Each time the macro is executed, the 'while' body + is parsed and stored again. + + .de xxx + . nr num 10 + . while (\\n[num] > 0) \{\ + . \" many lines of code + . nr num -1 + . \} + .. + + An often better solution--and one that is more portable, since AT&T + 'troff' lacked the 'while' request--is to instead write a recursive + macro. It will be parsed only once.(2) (*note while-Footnote-2::) + + .de yyy + . if (\\n[num] > 0) \{\ + . \" many lines of code + . nr num -1 + . yyy + . \} + .. + . + .de xxx + . nr num 10 + . yyy + .. + + To prevent infinite loops, the default number of available + recursion levels is 1,000 or somewhat less.(3) (*note + while-Footnote-3::) You can disable this protective measure, or + raise the limit, by setting the 'slimit' register. *Note + Debugging::. + + As noted above, if a 'while' body begins with a conditional block, + its closing brace must end an input line. + + .if 1 \{\ + . nr a 0 1 + . while (\n[a] < 10) \{\ + . nop \n+[a] + .\}\} + error-> unbalanced brace escape sequences + + -- Request: .break + Exit a 'while' loop. Do not confuse this request with a + typographical break or the 'br' request. + + -- Request: .continue + Skip the remainder of a 'while' loop's body, immediately starting + the next iteration. + + (1) *Note Copy Mode::. + + (2) unless you redefine it + + (3) "somewhat less" because things other than macro calls can be on +the input stack + +5.24 Writing Macros +=================== + +A "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. *Note Identifiers::. + + -- Request: .de name [end] + Define a macro NAME, replacing the definition of any existing + request, macro, string, or diversion called NAME. If NAME already + exists as an alias, the target of the alias is redefined; recall + *note Strings::. GNU 'troff' enters copy mode,(1) (*note Writing + Macros-Footnote-1::) storing subsequent input lines as the macro + definition. If the optional second argument is not specified, the + definition ends with the control line '..' (two dots). + Alternatively, END identifies a macro whose call syntax at the + start of a control line ends the definition of NAME; END is then + called normally. A macro definition must end in the same + conditional block (if any) in which it began (*note Conditional + Blocks::). Spaces or tabs are permitted after the control + character in the line containing this ending token (either '.' or + 'END'), but a tab immediately after the token prevents its + recognition as the end of a macro definition. The macro END can be + called with arguments.(2) (*note Writing Macros-Footnote-2::) + + Here is a small example macro called 'P' that causes a break and + inserts some vertical space. It could be used to separate + paragraphs. + + .de P + . br + . sp .8v + .. + + We can define one macro within another. Attempting to nest '..' + 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.(3) (*note Writing + Macros-Footnote-3::) + + .de m1 + . de m2 m3 + you + .. + .de m3 + Hello, + Joe. + .. + .de m4 + do + .. + .m1 + know? + . m3 + What + .m4 + .m2 + => Hello, Joe. What do you know? + + A nested macro definition _can_ be terminated with '..' and nested + macros _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. + + 'de' defines a macro that inherits the compatibility mode enablement +status of its context (*note Implementation Differences::). Often it is +desirable to make a macro that uses '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. + + -- Request: .de1 name [end] + The 'de1' request defines a macro to be interpreted with + compatibility mode disabled. When 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 'xxx'; we'll explore this subject in *note Copy Mode::. + + .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 + => The value of xxx is 0xxx]. + .bb + => The value of xxx is 12345. + + -- Request: .dei name [end] + -- Request: .dei1 name [end] + The 'dei' request defines a macro with its name and end macro + indirected through strings. That is, it interpolates strings named + NAME and END before performing the definition. + + The following examples are equivalent. + + .ds xx aa + .ds yy bb + .dei xx yy + + .de aa bb + + The 'dei1' request bears the same relationship to 'dei' as 'de1' + does to 'de'; it temporarily turns compatibility mode off when NAME + is called. + + -- Request: .am name [end] + -- Request: .am1 name [end] + -- Request: .ami name [end] + -- Request: .ami1 name [end] + 'am' appends subsequent input lines to macro NAME, extending its + definition, and otherwise working as 'de' does. + + To make the previously defined 'P' macro set indented instead of + block paragraphs, add the necessary code to the existing macro. + + .am P + .ti +5n + .. + + The other requests are analogous to their 'de' counterparts. The + 'am1' request turns off compatibility mode during interpretation of + the appendment. The 'ami' request appends indirectly, meaning that + strings NAME and END are interpolated with the resulting names used + before appending. The 'ami1' request is similar to 'ami', + disabling compatibility mode during interpretation of the appended + lines. + + Using 'trace.tmac', you can trace calls to 'de', 'de1', 'am', and +'am1'. You can also use the 'backtrace' request at any point desired to +troubleshoot tricky spots (*note Debugging::). + + *Note Strings::, for the 'als', 'rm', and 'rn' requests to create an +alias of, remove, and rename a macro, respectively. + + Macro identifiers share their name space with requests, strings, and +diversions; see *note Identifiers::. The 'am', 'as', 'da', 'de', 'di', +and '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. *Note the description of the 'als' +request: als, for pitfalls when redefining a macro that is aliased. + + -- Request: .return [anything] + Exit a macro, immediately returning to the caller. If called with + an argument ANYTHING, exit twice--the current macro and the macro + one level higher. This is used to define a wrapper macro for + 'return' in 'trace.tmac'. + + (1) *Note Copy Mode::. + + (2) While it is possible to define and call a macro '.', you can't +use it as an end macro: during a macro definition, '..' is never handled +as calling '.', even if '.de NAME .' explicitly precedes it. + + (3) 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. +<https://lists.gnu.org/archive/html/groff/2008-12/msg00006.html> + +5.24.1 Parameters +----------------- + +Macro calls and string interpolations optionally accept a list of +arguments; recall *note Calling Macros::. At the time such an +interpolation takes place, these "parameters" can be examined using a +register and a variety of escape sequences starting with '\$'. All such +escape sequences are interpreted even in copy mode, a fact we shall +motivate and explain below (*note Copy Mode::). + + -- Register: \n[.$] + The count of parameters available to a macro or string is kept in + this read-only register. The 'shift' request can change its value. + + 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. + + -- Escape sequence: \$n + -- Escape sequence: \$(nn + -- Escape sequence: \$[nnn] + Interpolate the Nth, NNth, or NNNth parameter. The first form + expects only a single digit (1<=N<=9)), the second two digits + (01<=NN<=99)), and the third any positive integer NNN. Macros and + strings accept an unlimited number of parameters. + + -- Request: .shift [n] + Shift the parameters N places (1 by default). This is a "left + shift": what was parameter I becomes parameter I-N. The parameters + formerly in positions 1 to N are no longer available. Shifting by + a non-positive amount performs no operation. The register '.$' is + adjusted accordingly. + + In practice, parameter interpolations are usually seen prefixed with +an extra escape character. This is because the '\$' family of escape +sequences is interpreted even in copy mode.(1) (*note +Parameters-Footnote-1::) + + -- Escape sequence: \$* + -- Escape sequence: \$@ + -- Escape sequence: \$^ + In some cases it is convenient to interpolate all of the parameters + at once (to pass them to a request, for instance). The '\$*' + escape concatenates the parameters, separating them with spaces. + '\$@' 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 (*note Calling Macros::). '\$^' interpolates all + parameters as if they were arguments to the 'ds' request. + + .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"' + + '\$*' 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 + 'tm' or 'ab' requests. Use '\$@' 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 '\$@' to '\$*'. + An application of '\$^' is seen in 'trace.tmac', which redefines + some requests and macros for debugging purposes. + + -- Escape sequence: \$0 + Interpolate the name by which the macro being interpreted was + called. The 'als' request can cause a macro to have more than one + name. Applying string interpolation to a macro does not change + this name. + + .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 + + (1) If they were not, parameter interpolations would be similar to +command-line parameters--fixed for the entire duration of a 'roff' +program's run. The advantage of interpolating '\$' 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. + +5.24.2 Copy Mode +---------------- + +When GNU 'troff' processes certain requests, most importantly those +which define or append to a macro or string, it does so in "copy mode": +it copies the characters of the definition into a dedicated storage +region, interpolating the escape sequences '\n', '\g', '\$', '\*', '\V', +and '\?' normally; interpreting '\<RET>' immediately; discarding +comments '\"' and '\#'; interpolating the current leader, escape, or tab +character with '\a', '\e', and '\t', respectively; and storing all other +escape sequences in an encoded form. + + The complement of copy mode--a '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 "interpretation mode". + + -- Escape sequence: \\ + The escape character, '\' by default, can escape itself. This + enables you to control whether a given '\n', '\g', '\$', '\*', + '\V', or '\?' escape sequence is interpreted at the time the macro + containing it is defined, or later when the macro is called.(1) + (*note Copy Mode-Footnote-1::) + + .nr x 20 + .de y + .nr x 10 + \&\nx + \&\\nx + .. + .y + => 20 10 + + You can think of '\\' as a "delayed" backslash; it is the escape + character followed by a backslash from which the escape character + has removed its special meaning. Consequently, '\\' is not an + escape sequence in the usual sense. In any escape sequence '\X' + that GNU 'troff' does not recognize, the escape character is + ignored and X is output. An unrecognized escape sequence causes a + warning in category 'escape', with two exceptions--'\\' is the + first. + + -- Escape sequence: \. + '\.' escapes the control character. It is similar to '\\' 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. + + .de m1 + foo + . + . de m2 + bar + \\.. + . + .. + .m1 + .m2 + => foo bar + + The first backslash is consumed while the macro is read, and the + second is interpreted when macro 'm1' is called. + + 'roff' documents should not use the '\\' or '\.' character sequences +outside of copy mode; they serve only to obfuscate the input. Use '\e' +to represent the escape character, '\[rs]' to obtain a backslash glyph, +and '\&' before '.' and ''' where GNU 'troff' expects them as control +characters if you mean to use them literally (recall *note Requests and +Macros::). + + Macro definitions can be nested to arbitrary depth. The mechanics of +parsing the escape character have significant consequences for this +practice. + + .de M1 + \\$1 + . de M2 + \\\\$1 + . de M3 + \\\\\\\\$1 + \\\\.. + . M3 hand. + \\.. + . M2 of + .. + This understeer is getting + .M1 out + => This understeer is getting out of hand. + + 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 '\n', +'\g', '\$', '\*', '\V', and '\?' at each nesting level, which can be +daunting. GNU 'troff' offers a solution. + + -- Escape sequence: \E + '\E' represents an escape character that is not interpreted in copy + mode. You can use it to ease the writing of nested macro + definitions. + + .de M1 + . nop \E$1 + . de M2 + . nop \E$1 + . de M3 + . nop \E$1 + \\\\.. + . M3 better. + \\.. + . M2 bit + .. + This vehicle handles + .M1 a + => This vehicle handles a bit better. + + Observe that because '\.' is not a true escape sequence, we can't + use '\E' to keep '..' from ending a macro definition prematurely. + If the multiplicity of backslashes complicates maintenance, use end + macros. + + '\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.(2) (*note Copy Mode-Footnote-2::) + + .ds { \v'-.9m\s'\En[.s]*7u/10u'+.7m' + .ds } \v'-.7m\s0+.9m' + + When the 'ec' request is used to redefine the escape character, + '\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, '-'. + + .nr a 1 + .ec - + .de xx + --na + .. + .xx + => -na + + This result may surprise you; some people expect '1' to be output + since register 'a' has clearly been defined with that value. What + has happened? The robotic replacement of '\' with '-' has led us + astray. You might recognize the sequence '--' more readily with + the default escape character as '\-', the special character escape + sequence for the minus sign glyph. + + .nr a 1 + .ec - + .de xx + -Ena + .. + .xx + => 1 + + (1) Compare this to the '\def' and '\edef' commands in TeX. + + (2) These are lightly adapted from the 'groff' implementation of the +'ms' macros. + +5.25 Page Motions +================= + +*Note Manipulating Spacing::, for a discussion of the most commonly used +request for vertical motion, 'sp', which spaces downward by one vee. + + -- Request: .mk [reg] + -- Request: .rt [dist] + You can "mark" a location on a page for subsequent "return". '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 'rt' or + the 'sp' requests (or the '\v' escape). + + The 'rt' request returns _upward_ to the location marked with the + last 'mk' request. If used with an argument, it returns to a + vertical position DIST from the top of the page (no previous call + to 'mk' is necessary in this case). The default scaling unit is + 'v'. + + If a page break occurs between a 'mk' request and its matching 'rt' + request, the 'rt' request is silently ignored. + + A simple implementation of a macro to set text in two columns + follows. + + .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 + . \} + .. + + Now let us apply our two-column macro. + + .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. + => This is a small test that shows how the + => rt request works in combination with mk. + => + => Starting here, isn't robust + => text is typeset and thus not + => in two columns. suited for a + => Note that this real two-column + => implementation macro. + + Several escape sequences enable fine control of movement about the +page. + + -- Escape sequence: \v'expr' + Vertically move the drawing position. EXPR indicates the magnitude + of motion: positive is downward and and negative upward. The + default scaling unit is 'v'. The motion is relative to the current + drawing position unless EXPR begins with the boundary-relative + motion operator '|'. *Note Numeric Expressions::. + + Text processing continues at the new drawing position; usually, + vertical motions should be in balanced pairs to avoid a confusing + page layout. + + '\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. *Note + Traps::. + + A few escape sequences that produce vertical motion are unusual. +They are thought to originate early in AT&T '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).(1) (*note Page +Motions-Footnote-1::) + + -- Escape sequence: \r + -- Escape sequence: \u + -- Escape sequence: \d + Move upward 1m, upward .5m, and downward .5m, respectively. + +Let us see these escape sequences in use. + + Obtain 100 cm\u3\d of \ka\d\092\h'|\nau'\r233\dU. + + In the foregoing we have paired '\u' and '\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 '\k' marks a +horizontal position to which '\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 'groff' 'ms' +package does with its super- and subscripting string definitions. + + -- Escape sequence: \h'expr' + Horizontally move the drawing position. EXPR indicates the + magnitude of motion: positive is rightward and negative leftward. + The default scaling unit is 'm'. The motion is relative to the + current drawing position unless EXPR begins with the + boundary-relative motion operator '|'. *Note Numeric + Expressions::. + + The following string definition sets the TeX logo.(2) (*note Page +Motions-Footnote-2::) + + .ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X\" + + There are a number of special-case escape sequences for horizontal +motion. + + -- Escape sequence: \<SP> + 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 '\~' instead; + see *note Manipulating Filling and Adjustment::. + + -- Escape sequence: \| + Move one-sixth em to the right on typesetting output devices. If a + glyph named '\|' is defined in the current font, its width is used + instead, even on terminal output devices. + + -- Escape sequence: \^ + Move one-twelfth em to the right on typesetting output devices. If + a glyph named '\^' is defined in the current font, its width is + used instead, even on terminal output devices. + + -- Escape sequence: \0 + Move right by the width of a numeral in the current font. + + Horizontal motions are not discarded at the end of an output line as +word spaces are. *Note Breaking::. + + -- Escape sequence: \w'anything' + -- Register: \n[st] + -- Register: \n[sb] + -- Register: \n[rst] + -- Register: \n[rsb] + -- Register: \n[ct] + -- Register: \n[ssc] + -- Register: \n[skw] + Interpolate the width of ANYTHING in basic units. This escape + sequence allows several properties of formatted output to be + measured without writing it out. + + The length of the string 'abc' is \w'abc'u. + => The length of the string 'abc' is 72u. + + 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. + + After each use, '\w' sets several registers. + + 'st' + '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 AT&T 'troff' manual as "the + highest and lowest extent of [the argument to '\w'] relative + to the baseline". + + 'rst' + 'rsb' + Like 'st' and '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 ANYTHING, + doing what AT&T 'troff' documented 'st' and 'sb' as doing. + + 'ct' + Characterizes the geometry of glyphs occurring in ANYTHING. + + 0 + only short glyphs, no descenders or tall glyphs + + 1 + at least one descender + + 2 + at least one tall glyph + + 3 + at least one each of a descender and a tall glyph + + 'ssc' + The amount of horizontal space (possibly negative) that should + be added to the last glyph before a subscript. + + 'skw' + How far to right of the center of the last glyph in the '\w' + argument, the center of an accent from a roman font should be + placed over that glyph. + + -- Escape sequence: \kp + -- Escape sequence: \k(ps + -- Escape sequence: \k[position] + Store the current horizontal position in the _input_ line in a + register with the name POSITION (one-character name P, + two-character name PS). Use this, for example, to return to the + beginning of a string for highlighting or other decoration. + + -- Register: \n[hp] + The current horizontal position at the input line. + + -- Register: \n[.k] + A read-only register containing the current horizontal output + position (relative to the current indentation). + + -- Escape sequence: \o'abc...' + Overstrike the glyphs of characters A, B, C, ...; the glyphs are + centered, written, and the drawing position advanced by the widest + of the glyphs. + + -- Escape sequence: \zc + Format the character C with zero width; that is, without advancing + the drawing position. Use '\z' to overstrike glyphs aligned to + their left edges, in contrast to '\o''s centering. + + -- Escape sequence: \Z'anything' + Save the drawing position, format ANYTHING, then restore it. Tabs + and leaders in the argument are ignored with an error diagnostic. + + We might implement a strike-through macro thus. + + .de ST + .nr width \w'\\$1' + \Z@\v'-.25m'\l'\\n[width]u'@\\$1 + .. + . + This is + .ST "a test" + an actual emergency! + + (1) At the '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 '.vs .5i' make it obvious. + + (2) *Note Strings::, for an explanation of the trailing '\"'. + +5.26 Drawing Geometric Objects +============================== + +A few of the formatter's escape sequences draw lines and other geometric +objects. Combined with each other and with page motion commands (*note +Page Motions::), a wide variety of figures is possible. For complex +drawings, these operations can be cumbersome; the preprocessors 'gpic' +or 'ggrn' are typically used instead. + + The '\l' and '\L' escape sequences draw horizontal and vertical +sequences of glyphs, respectively. Even the simplest of output devices +supports them. + + -- Escape sequence: \l'l' + -- Escape sequence: \l'lc' + Draw a horizontal line of length 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 'm'. + + The optional second parameter C is a character with which to draw + the line. The default is the baseline rule special character, + '\[ru]'. + + If C is a valid scaling unit, put '\&' after L to disambiguate the + input. + + .de textbox + \[br]\\$*\[br]\l'|0\[rn]'\l'|0\[ul]' + .. + + The foregoing outputs a box rule (a vertical line), the text + argument(s), and another box rule. We employ the boundary-relative + motion operator '|'. 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 _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. + + -- Escape sequence: \L'l' + -- Escape sequence: \L'lc' + Draw a vertical line of length L from the drawing position. + Downward motion is positive. The default scaling unit is 'v'. The + default character is the box rule, '\[br]'. As with vertical + motion escape sequences, text processing continues where the line + ends. '\L' is otherwise similar to '\l'. + + $ nroff <<EOF + This is a \L'3v'test. + EOF + => This is a + => | + => | + => |test. + + When writing text, the drawing position is at the text baseline; + recall *note Page Geometry::. + + The '\D' escape sequence provides "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. *Note 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 'troff' draws stroked (outlined) +objects with the stroke color, and shades filled ones with the fill +color. *Note Colors::. Coordinates H and 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 'm'; for vertical ones, '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 '\D't''). + + \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'' + + -- Escape sequence: \D'command argument ...' + Drawing command escape sequence parameters begin with an ordinary + character, COMMAND, selecting the type of object to be drawn, + followed by ARGUMENTs whose meaning is determined by COMMAND. + + '\D'~ H1 V1 ... HN VN'' + Draw a B-spline to each point in sequence, leaving the drawing + position at (HN, VN). + + '\D'a HC VC H V'' + Draw a circular arc centered at (HC, VC) counterclockwise from + the drawing position to a point (H, V) relative to the center. + (1) (*note Drawing Geometric Objects-Footnote-1::) + + '\D'c D'' + Draw a circle of diameter D with its leftmost point at the + drawing position. + + '\D'C D'' + As '\D'C ...'', but the circle is filled. + + '\D'e H V'' + Draw an ellipse of width H and height V with its leftmost + point at the drawing position. + + '\D'E X Y'' + As '\D'e ...'', but the ellipse is filled. + + '\D'l DX DY'' + Draw line from the drawing position to (H, V). + + The following is a macro for drawing a box around a text + argument; for simplicity, the box margin is a fixed at 0.2m. + + .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' + .. + + The argument is measured with the '\w' escape sequence. Its + width is stored in register '@wd'. '\w' also sets the + registers 'rst' and 'rsb'; these contain its maximum vertical + extents of the argument. Then, four lines are drawn to form a + box, offset by the box margin. + + '\D'p H1 V1 ... HN VN'' + Draw polygon with vertices at drawing position and each point + in sequence. GNU 'troff' closes the polygon by drawing a line + from (HN, VN) back to the initial drawing position. + Afterward, the drawing position is left at (HN, VN). + + '\D'P DX1 DY1 DX2 DY2 ...'' + As '\D'P ...'', but the polygon is filled. + + The following macro is like the '\D'l'' example, but shades + the box. We draw the box before writing the text because + colors in GNU 'troff' have no transparency; in othe opposite + order, the filled polygon would occlude the text. + + .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' + .. + + '\D't N'' + Set the stroke thickness of geometric objects to N basic + units. A zero N selects the minimal supported thickness. A + negative N selects a thickness proportional to the type size; + this is the default. + + In a hazy penumbra between text rendering and drawing commands we +locate the bracket-building escape sequence, '\b'. It can assemble +apparently large glyphs by vertically stacking ordinary ones. + + -- Escape sequence: \b'contents' + Pile and center a sequence of glyphs vertically on the output line. + "Piling" stacks glyphs corresponding to each character in CONTENTS, + read from left to right, and placed from top to bottom. GNU + 'troff' separates the glyphs vertically by 1m, and the pile itself + is centered 0.5m above the text baseline. The horizontal drawing + position is then advanced by the width of the widest glyph in the + pile. + + This rather inflexible positioning algorithm doesn't work with the + 'dvi' output device since its bracket pieces vary in height. + Instead, use the 'geqn' preprocessor. + + *note Manipulating Spacing:: describes how to adjust the vertical + spacing of the output line with the '\x' escape sequence. + + The application of '\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. + + \b'\[lt]\[bv]\[lk]\[bv]\[lb]' + + See 'groff_char(7)' for a list of special character identifiers. + + (1) (HC, VC) is adjusted to the point nearest the perpendicular +bisector of the arc's chord. + +5.27 Deferring Output +===================== + +A few 'roff' language elements are generally not used in simple +documents, but arise as page layouts become more sophisticated and +demanding. "Environments" collect formatting parameters like line +length and typeface. A "diversion" stores formatted output for later +use. A "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 'A', 'B', and +so on. If we set up a trap that produces text 'T' (as a page footer, +say), and we also use a diversion to store the formatted text 'D', then +a document with input text in the order 'A B C D E F' might render as 'A +B C E T F'. The diversion '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 'groff' language develops. +Environments save us considerable effort. + +5.28 Traps +========== + +"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 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. Setting a trap is also called "planting" +one. It is said that a trap is "sprung" if its condition is fulfilled. + +5.28.1 Vertical Position Traps +------------------------------ + +A "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. + + -- Request: .vpt [flag] + -- Register: \n[.vpt] + Enable vertical position traps if FLAG is non-zero or absent; + disable them otherwise. Vertical position traps are those set by + the 'wh' request or by '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 '.vpt' read-only register. + + A page can't be ejected if 'vpt' is set to zero; see *note The + Implicit Page Trap::. + +5.28.1.1 Page Location Traps +............................ + +A "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 'wh' and 'ch' requests. + + -- Request: .wh dist [name] + Plant macro NAME as page location trap at DIST. The default + scaling unit is 'v'. Non-negative values for 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 DIST of '-0' + is interpreted as '0', the top of the page.(1) (*note Page + Location Traps-Footnote-1::) An existing _visible_ trap (see below) + at DIST is removed; this is 'wh''s sole function if NAME is + missing. + + A trap is sprung only if it is "visible", meaning that its location + is reachable on the page(2) (*note Page Location + Traps-Footnote-2::) and it is not hidden by another trap at the + same location already planted there. + + 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 'sp' request to position our text baselines, + and the page number character '%' used with the 'tl' request. + + .\" 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 + + To use these traps, copy the above (or load it from a file with the + 'so' or 'mso' requests), then set up the strings it uses. + + .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 + .\" ...and so on... + + 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 _current_ page length; they are not converted + to an absolute vertical position. We can use the 'ptr' request to + dump our page location traps to the standard error stream (*note + Debugging::). Their positions are reported in basic units; an + 'nroff' device example follows. + + .pl 5i + .wh -1i xx + .ptr + error-> xx -240 + .pl 100i + .ptr + error-> xx -240 + + 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 'ch' request. In the following example, the + many empty lines caused by the 'bp' request are not shown in the + output. + + .de a + . nop a + .. + .de b + . nop b + .. + .de c + . nop c + .. + . + .wh 1i a + .wh 2i b + .wh 3i c + .bp + => a b c + .ch b 1i + .ch c 1i + .bp + => a + .ch a 0.5i + .bp + => a b + + -- Register: \n[.t] + The read-only register '.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. + + -- Request: .ch name [dist] + Change the location of a trap by moving macro NAME to new location + DIST, or by unplanting it altogether if DIST is absent. The + default scaling unit is 'v'. Parameters to 'ch' are specified in + the opposite order from 'wh'. If 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.(3) (*note Page Location Traps-Footnote-3::) + + 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. + + The same macro can be installed simultaneously at multiple locations; +however, only the earliest-planted instance--that has not yet been +deleted with 'wh'--will be moved by 'ch'. The following example (using +an 'nroff' device) illustrates this behavior. Blank lines have been +elided from the output. + + .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 + => foo + => Trap sprung at 240u. + => Trap sprung at 480u. + => bar + => Trap sprung at 480u. + => Trap sprung at 960u. + => baz + => Trap sprung at 480u. + => Trap sprung at 1200u. + => qux + => Trap sprung at 1440u. + + -- Register: \n[.ne] + The read-only register '.ne' contains the amount of space that was + needed in the last 'ne' request that caused a trap to be sprung; it + is useful in conjunction with the '.trunc' register. *Note Page + Control::. Since the '.ne' register is set only by traps, it + doesn't make sense to interpolate it outside of macros called by + traps. + + -- Register: \n[.trunc] + A read-only register containing the amount of vertical space + truncated from an 'sp' request by the most recently sprung vertical + position trap, or, if the trap was sprung by an 'ne' request, minus + the amount of vertical motion produced by the 'ne' request. In + other words, at the point a trap is sprung, it represents the + difference of what the vertical position would have been but for + the trap, and what the vertical position actually is. Since the + '.trunc' register is set only by traps, it doesn't make sense to + interpolate it outside of macros called by traps. + + -- Register: \n[.pe] + This Boolean-valued, read-only register interpolates 1 while a page + is being ejected, and 0 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. + + .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 + => Those who can make you believe absurdities can + => make you commit atrocities. -- Voltaire + + 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 '\!' or '\?') since the data in +the diversion is already formatted. In most cases, this is not the +expected behaviour. + + (1) *Note The Implicit Page Trap::. + + (2) A trap planted at '20i' or '-30i' will not be sprung on a page of +length '11i'. + + (3) It may help to think of each trap location as maintaining a +queue; 'wh' operates on the head of the queue, and 'ch' operates on its +tail. Only the trap at the head of the queue is visible. + +5.28.1.2 The Implicit Page Trap +............................... + +If, after starting GNU 'troff' without loading a macro package, you use +the 'ptr' request to dump a list of the active traps to the standard +error stream,(1) (*note The Implicit Page Trap-Footnote-1::) nothing is +reported. Yet the '.t' register will report a steadily decreasing value +with every output line your document produces, and once the value of +'.t' gets to within '.V' of zero, you will notice that something +trap-like happens--the page is ejected, a new one begins, and the value +of '.t' becomes large once more. + + This "implicit page trap" always exists in the top-level +diversion;(2) (*note The Implicit Page Trap-Footnote-2::) 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 'wh' or 'ch' requests. You cannot hide it by placing +another trap at its location, and can move it only by redefining the +page length with 'pl'. Its operation is suppressed when vertical page +traps are disabled with GNU 'troff''s 'vpt' request. + + (1) *Note Debugging::. + + (2) *Note Diversions::. + +5.28.1.3 Diversion Traps +........................ + +A diversion is not formatted in the context of a page, so it lacks page +location traps; instead it can have a "diversion trap". There can exist +at most one such vertical position trap per diversion. + + -- Request: .dt [dist name] + Set a trap _within_ a diversion at location 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 '.t' works within + diversions. It is an error to invoke 'dt' in the top-level + diversion. *Note Diversions::. + +5.28.2 Input Line Traps +----------------------- + + -- Request: .it [n name] + -- Request: .itc [n name] + Set an input line trap, calling macro NAME after processing the + next N productive input lines (recall *note Manipulating Filling + and Adjustment::). Any existing input line trap in the environment + is replaced. Without arguments, 'it' and 'itc' clear any input + line trap that has not yet sprung. + + Consider a macro '.ST S N' which sets the next N input lines in the + font style S. + + .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 + => oblique face obliqueface (second "face" upright) + + Unlike the 'ce' and 'rj' requests, 'it' counts lines interrupted + with the '\c' escape sequence separately (*note Line + Continuation::); 'itc' does not. To see the difference, let's + change the previous example to use 'itc' instead. + + ... + . itc \\$2 ES + ... + => oblique face obliqueface (second "face" oblique) + + You can think of the 'ce' and 'rj' requests as implicitly creating + an input line trap with 'itc' that schedules a break when the trap + is sprung. + + .de BR + . br + . internal: disable centering-without-filling + .. + . + .de ce + . if \\n[.br] .br + . itc \\$1 BR + . internal: enable centering-without-filling + .. + + Let us consider in more detail the sorts of input lines that are or + are not "productive". + + .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 + + When 'Trap' gets called depends on whether the 'a' register is + defined; the control line with the 'if' request may or may not + produce written output. We also see that the spacing request 'sp', + while certainly affecting the output, does not spring the input + line trap. Similarly, the horizontal motion escape sequence '\h' + also affected the output, but was not "written". Observe that we + had to follow it with '\c' and use '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. + + $ groff -Tascii input-trap-example.groff + => foo bar TRAP SPRUNG baz + => + => qux TRAP SPRUNG jat TRAP SPRUNG + $ groff -Tascii -ra1 input-trap-example.groff + => foo _____ TRAP SPRUNG bar baz + => + => qux TRAP SPRUNG jat TRAP SPRUNG + + Input line traps are associated with the environment (*note +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. + +5.28.3 Blank Line Traps +----------------------- + + -- Request: .blm [name] + Set a blank line trap, calling the macro NAME when GNU 'troff' + encounters a blank line in an input file, instead of the usual + behavior (*note 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. + +5.28.4 Leading Space Traps +-------------------------- + + -- Request: .lsm [name] + -- Register: \n[lsn] + -- Register: \n[lss] + Set a leading space trap, calling the macro NAME when GNU '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 + (*note Breaking::). + + The count of leading spaces on an input line is stored in register + 'lsn', and the amount of corresponding horizontal motion in + register '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 NAME. + +5.28.5 End-of-input Traps +------------------------- + + -- Request: .em [name] + Set a trap at the end of input, calling macro 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 'em' request could be + used. + + .de approval + \c + . ne 3v + . sp (\\n[.t]u - 3v) + . in +4i + . lc _ + . br + Approved:\t\a + . sp + Date:\t\t\a + .. + . + .em approval + + The '\c' in the above example needs explanation. For historical + reasons (compatibility with AT&T 'troff'), the end-of-input macro + exits as soon as it causes a page break if no partially collected + line remains.(1) (*note End-of-input Traps-Footnote-1::) + + Let us assume that there is no '\c' in the above 'approval' macro, + that the page is full, and last output line has been broken with, + say, a 'br' request. Because there is no more room, a 'ne' request + at this point causes a page ejection, which in turn makes 'troff' + exit immediately as just described. In most situations, this is + not desired; people generally want to format the input after '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 ('\c') whenever there is a + chance that a page break can happen. In the above example, + invoking the 'ne' request ensures that there is room for the + subsequent formatted output on the same page, so we need insert + '\c' only once. + + The next example shows how to append three lines, then start a new + page unconditionally. Since '.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 '.ne 2'. + + .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 + + 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 'em' request is to make GNU '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,(2) (*note End-of-input Traps-Footnote-2::) and + automatically adjust it to the exact height of the document after + the text has been output. + + .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 + + 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 'am' request. + + (1) 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". + + (2) Another, taken by the 'groff' 'man' macros, is to intercept 'ne' +requests and wrap 'bp' ones. + +5.29 Diversions +=============== + +In 'roff' systems it is possible to format text as if for output, but +instead of writing it immediately, one can "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 +diversions as for strings and macros; see *note 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 _unformatted_ input +text, and the latter capture _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. For orthogonality it is said that GNU 'troff' +is in the "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 'mac' to be emitted. *Note +Warnings::, for information about the enablement and suppression of +warnings. A diversion does not exist for the purpose of testing with +the 'd' conditional operator until its initial definition ends (*note +Operators in Conditionals::). The following requests are used to create +and alter diversions. + + -- Request: .di [name] + -- Request: .da [name] + Start collecting formatted output in a diversion called NAME. The + 'da' request appends to a diversion called NAME, creating it if + necessary. If NAME already exists as an alias, the target of the + alias is replaced or appended to; recall *note Strings::. The + pending output line is diverted as well. Switching to another + environment (with the 'ev' request) before invoking 'di' or 'da' + avoids including any pending output line in the diversion; see + *note Environments::. + + Invoking 'di' or 'da' without an argument stops diverting output to + the diversion named by the most recent corresponding request. If + 'di' or 'da' is called without an argument when there is no current + diversion, a warning in category 'di' is produced. *Note + Warnings::, for information about the enablement and suppression of + warnings. + + Before the diversion. + .di yyy + In the diversion. + .br + .di + After the diversion. + .br + => After the diversion. + .yyy + => Before the diversion. In the diversion. + + GNU 'troff' supports "box" requests to exclude a partially collected +line from a diversion, as this is often desirable. + + -- Request: .box [name] + -- Request: .boxa [name] + Divert (or append) output to NAME, similarly to the 'di' and 'da' + requests, respectively. Any pending output line is _not_ included + in the diversion. Without an argument, stop diverting output; any + pending output line inside the diversion is discarded. + + Before the box. + .box xxx + In the box. + .br + Hidden treasure. + .box + After the box. + .br + => Before the box. After the box. + .xxx + => In the box. + + Apart from pending output line inclusion and the request names that +populate them, boxes are handled exactly as diversions are. All of the +following 'groff' language elements can be used with them +interchangeably. + + -- Register: \n[.z] + -- Register: \n[.d] + Diversions may be nested. The read-only string-valued register + '.z' contains the name of the current diversion. The read-only + register '.d' contains the current vertical place in the diversion. + If the input text is not being diverted, '.d' reports the same + location as the register 'nl'. + + -- Register: \n[.h] + The read-only register '.h' stores the "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.(1) (*note + Diversions-Footnote-1::) + + .tm .h==\n[.h], nl==\n[nl] + => .h==0, nl==-1 + This is a test. + .br + .sp 2 + .tm .h==\n[.h], nl==\n[nl] + => .h==40, nl==120 + + As implied by the example, vertical motion does not produce text + baselines and thus does not increase the value interpolated by + '\n[.h]'. + + -- Register: \n[dn] + -- Register: \n[dl] + After completing a diversion, the writable registers 'dn' and 'dl' + contain its vertical and horizontal sizes. Only the lines just + processed are counted: for the computation of 'dn' and 'dl', the + requests 'da' and 'boxa' are handled as if 'di' and 'box' had been + used, respectively--lines that have been already stored in the + diversion (box) are not taken into account. + + .\" 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 + .. + .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 + + -- Escape sequence: \!anything + -- Escape sequence: \?anything\? + "Transparently" embed 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 '\!' escape sequence transparently embeds + input up to and including the end of the line. The '\?' escape + sequence transparently embeds input until its own next occurrence. + + ANYTHING may not contain newlines; use '\!' by itself to embed + newlines in a diversion. The escape sequence '\?' is also + recognized in copy mode and turned into a single internal code; it + is this code that terminates ANYTHING. Thus the following example + prints 4. + + .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 + + Both escape sequences read the data in copy mode. + + If '\!' is used in the top-level diversion, its argument is + directly embedded into GNU '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. + + The '\?' escape used in the top-level diversion produces no output + at all; its argument is simply ignored. + + -- Request: .output contents + Emit CONTENTS directly to GNU 'troff''s intermediate output + (subject to copy mode interpretation); this is similar to '\!' used + at the top level. An initial neutral double quote in 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 '.br' before the '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 CONTENTS again. + + -- Request: .asciify div + "Unformat" the diversion DIV in a way such that Unicode basic Latin + (ASCII) characters, characters translated with the 'trin' request, + space characters, and some escape sequences, that were formatted + and diverted into DIV are treated like ordinary input characters + when DIV is reread. Doing so can be useful in conjunction with the + 'writem' request. 'asciify' can be also used for gross hacks; for + example, the following sets register 'n' to 1. + + .tr @. + .di x + @nr n 1 + .br + .di + .tr @@ + .asciify x + .x + + 'asciify' cannot return all items in a diversion to their source + equivalent: nodes such as those produced by the '\N' escape + sequence will remain nodes, so the result cannot be guaranteed to + be a pure string. *Note Copy Mode::. Glyph parameters such as the + type face and size are not preserved; use 'unformat' to achieve + that. + + -- Request: .unformat div + Like 'asciify', unformat the diversion DIV. However, '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. + + (1) Thus, the "water" gets "higher" proceeding _down_ the page. + +5.30 Punning Names +================== + +Macros, strings, and diversions share a name space; recall *note +Identifiers::. Internally, the same mechanism is used to store them. +You can thus call a macro with string interpolation syntax and vice +versa. + + .de subject + Typesetting + .. + .de predicate + rewards attention to detail + .. + \*[subject] \*[predicate]. + Truly. + => Typesetting + => rewards attention to detail Truly. + +What went wrong? Strings don't contain newlines, but macros do. String +interpolation placed a newline at the end of '\*[subject]', and the next +thing on the input was a space. Then when '\*[predicate]' was +interpolated, it was followed by the empty request '.' on a line by +itself. If we want to use macros as strings, we must take interpolation +behavior into account. + + .de subject + Typesetting\\ + .. + .de predicate + rewards attention to detail\\ + .. + \*[subject] \*[predicate]. + Truly. + => Typesetting rewards attention to detail. Truly. + +By ending each text line of the macros with an escaped '\<RET>', we get +the desired effect (*note Line Continuation::).(1) (*note Punning +Names-Footnote-1::) 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 + + .xx \\$@ + +is + + \\*[xx]\\ + +The latter calling syntax doesn't change the value of '\$0', which is +then inherited from the calling macro (*note Parameters::). + + Diversions can be also called with string syntax. It is sometimes +convenient to copy one-line diversions to a string. + + .di xx + the + .ft I + interpolation system + .ft + .br + .di + .ds yy This is a test of \*(xx\c + \*(yy. + => This is a test of the interpolation system. + +As the previous example shows, it is possible to store formatted output +in strings. The '\c' escape sequence prevents the subsequent newline +from being interpreted as a break (again, *note Line Continuation::). + + Copying multi-output line diversions produces unexpected results. + + .di xxx + a funny + .br + test + .br + .di + .ds yyy This is \*[xxx]\c + \*[yyy]. + => test This is a funny. + + Usually, it is not predictable whether a diversion contains one or +more output lines, so this mechanism should be avoided. With AT&T +'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. + + A clean solution to this problem is available in GNU 'troff', using +the requests 'chop' to remove the final newline of a diversion, and +'unformat' to make the horizontal spaces adjustable again. + + .box xxx + a funny + .br + test + .br + .box + .chop xxx + .unformat xxx + This is \*[xxx]. + => This is a funny test. + + *Note Gtroff Internals::. + + (1) The backslash is doubled. *Note Copy Mode::. + +5.31 Environments +================= + +As discussed in *note Deferring Output::, environments store most of the +parameters that determine the appearance of text. A default environment +named '0' exists when GNU 'troff' starts up; it is modified by +formatting-related requests and escape sequences. + + You can create new environments and switch among them. Only one is +current at any given time. Active environments are managed using a +"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 'pev' request; see *note Debugging::. + + Environments store the following information. + + * a partially collected line, if any + + * data about the most recently output glyph and line (registers + '.cdp', '.cht', '.csk', '.n', '.w') + + * typeface parameters (size, family, style, height and slant, + inter-word and inter-sentence space sizes) + + * page parameters (line length, title length, vertical spacing, line + spacing, indentation, line numbering, centering, right-alignment, + underlining, hyphenation parameters) + + * filling enablement; adjustment enablement and mode + + * tab stops; tab, leader, escape, control, no-break control, + hyphenation, and margin characters + + * input line traps + + * stroke and fill colors + + -- Request: .ev [ident] + -- Register: \n[.ev] + Enter the environment 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 'troff' + switches to the previous environment. + + Invoking 'ev' with an argument puts environment 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, '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 '.ev' contains the + name of the current environment--the one at the top of the stack. + + .ev footnote-env + .fam N + .ps 6 + .vs 8 + .ll -.5i + .ev + + ... + + .ev footnote-env + \[dg] Observe the smaller text and vertical spacing. + .ev + + We can familiarize ourselves with stack behavior by wrapping the + 'ev' request with a macro that reports the contents of the '.ev' + register to the standard error stream. + + .de EV + . ev \\$1 + . tm environment is now \\n[.ev] + .. + . + .EV foo + .EV bar + .EV + .EV baz + .EV + .EV + .EV + + 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 + + -- Request: .evc environment + Copy the contents of ENVIRONMENT to the current environment. + + The following environment data are not copied. + + * a partially collected line, if present; + + * the interruption status of the previous input line (due to use + of the '\c' escape sequence); + + * the count of remaining lines to center, to right-justify, or + to underline (with or without underlined spaces)--these are + set to zero; + + * the activation status of temporary indentation; + + * input line traps and their associated data; + + * the activation status of line numbering (which can be + reactivated with '.nm +0'); and + + * the count of consecutive hyphenated lines (set to zero). + + -- Register: \n[.w] + -- Register: \n[.cht] + -- Register: \n[.cdp] + -- Register: \n[.csk] + The '\n[.w]' register contains the width of the last glyph + formatted in the environment. + + The '\n[.cht]' register contains the height of the last glyph + formatted in the environment. + + The '\n[.cdp]' register contains the depth of the last glyph + formatted in the environment. It is positive for glyphs extending + below the baseline. + + The '\n[.csk]' register contains the "skew" (how far to the right + of the glyph's center that GNU 'troff' should place an accent) of + the last glyph formatted in the environment. + + -- Register: \n[.n] + The '\n[.n]' register contains the length of the previous output + line emitted in the environment. + +5.32 Suppressing Output +======================= + + -- Escape sequence: \O[num] + Suppress GNU 'troff' output of glyphs and geometric objects. The + sequences '\O2', '\O3', '\O4', and '\O5' are intended for internal + use by 'grohtml'. + + '\O0' + Disable the emission of glyphs and geometric objects to the + output driver, provided that this sequence occurs at the + outermost suppression level (see '\O3' and '\04' below). + Horizontal motions corresponding to non-overstruck glyph + widths still occur. + + '\O1' + Enable the emission of glyphs and geometric objects to the + output driver, provided that this sequence occurs at the + outermost suppression level. + + '\O0' and '\O1' also reset the four registers 'opminx', 'opminy', + 'opmaxx', and 'opmaxy' to -1. These four registers mark the top + left and bottom right hand corners of a box encompassing all + written or drawn output. + + '\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 '\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. + + '\O3' + Begin a nested suppression level. 'grohtml' uses this + mechanism to create images of output preprocessed with 'gpic', + 'geqn', and 'gtbl'. At startup, GNU 'troff' is at the + outermost suppression level. 'pre-grohtml' generates these + sequences when processing the document, using GNU 'troff' with + the 'ps' output device, Ghostscript, and the PNM tools to + produce images in PNG format. They start a new page if the + device is not 'html' or 'xhtml', to reduce the number of + images crossing a page boundary. + + '\O4' + End a nested suppression level. + + '\O[5PFILE]' + At the outermost suppression level, write the name 'file' to + the standard error stream at position P, which must be one of + 'l', 'r', 'c', or 'i', corresponding to left, right, centered, + and inline alignments within the document, respectively. FILE + is a name associated with the production of the next image. + + -- Register: \n[.O] + Output suppression nesting level applied by '\O3' and '\O4' escape + sequences. + +5.33 I/O +======== + +'gtroff' has several requests for including files: + + -- Request: .so file + -- Request: .soquiet file + Replace the 'so' request's control line with the contents of the + file named by the argument, "sourcing" it. FILE is sought in the + directories specified by '-I' command-line option. If FILE does + not exist, a warning in category 'file' is produced and the request + has no further effect. *Note Warnings::, for information about the + enablement and suppression of warnings. + + '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 'so' are not preprocessed; to overcome this + limitation, see the 'gsoelim(1)' man page. + + Since GNU 'troff' replaces the entire control line with the + contents of a file, it matters whether 'file' is terminated with a + newline or not. Assume that file 'xxx' contains only the word + 'foo' without a trailing newline. + + $ printf 'foo' > xxx + + The situation is + .so xxx + bar. + => The situation is foobar. + + 'soquiet' works the same way, except that no warning diagnostic is + issued if FILE does not exist. + + -- Request: .pso command + Read the standard output from the specified COMMAND and include it + in place of the 'pso' request. + + It is an error to use this request in safer mode, which is the + default. Invoke GNU 'troff' or a front end with the '-U' option to + enable unsafe mode. + + The comment regarding a final newline for the 'so' request is valid + for 'pso' also. + + -- Request: .mso file + -- Request: .msoquiet file + Identical to the 'so' and 'soquiet' requests, respectively, except + that 'gtroff' searches for the specified FILE in the same + directories as macro files for the '-m' command-line option. If + the file name to be included has the form 'NAME.tmac' and it isn't + found, these requests try to include 'tmac.NAME' and vice versa. + + -- Request: .trf file + -- Request: .cf file + Transparently output the contents of FILE. Each line is output as + if it were preceded by '\!'; however, the lines are _not_ subject + to copy mode interpretation. If the file does not end with a + newline, 'trf' adds one. Both requests cause a break. + + When used in a diversion, these requests embed a node (*note Gtroff + Internals::) in it that, when reread, causes the contents of FILE + to be transparently copied to the output. In AT&T 'troff', the + contents of 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. + + While 'cf' copies the contents of FILE completely unprocessed, + 'trf' disallows characters such as NUL that are not valid 'gtroff' + input characters (*note Identifiers::). + + For 'cf', within a diversion, "completely unprocessed" means that + each line of a file to be inserted is handled as if it were + preceded by '\!\\!'. + + To define a macro 'x' containing the contents of file 'f', use + + .ev 1 + .di x + .trf f + .di + .ev + + The calls to 'ev' prevent the partially collected output line from + becoming part of the diversion (*note Diversions::). + + -- Request: .nx [file] + Force 'gtroff' to continue processing of the file specified as an + argument. If no argument is given, immediately jump to the end of + file. + + -- Request: .rd [prompt [arg1 arg2 ...]] + 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 PROMPT to + standard error, followed by a colon (or send BEL for a beep if no + argument is given). + + Arguments after PROMPT are available for the input. For example, + the line + + .rd data foo bar + + with the input 'This is \$2.' prints + + This is bar. + + Using the 'nx' and '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 'repeat.let': + + .ce + \*(td + .sp 2 + .nf + .rd + .sp + .rd + .fi + Body of letter. + .bp + .nx repeat.let + +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 'ex' +request, which tells GNU 'troff' to stop processing. If this were not +there, 'troff' would not know when to stop. + + 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 + + -- Request: .pi pipe + Pipe the output of 'gtroff' to the shell command(s) specified by + PIPE. This request must occur before 'gtroff' has a chance to + print anything. + + It is an error to use this request in safer mode, which is the + default. Invoke GNU 'troff' or a front end with the '-U' option to + enable unsafe mode. + + Multiple calls to 'pi' are allowed, acting as a chain. For + example, + + .pi foo + .pi bar + ... + + is the same as '.pi foo | bar'. + + The intermediate output format of GNU 'troff' is piped to the + specified commands. Consequently, calling 'groff' without the '-Z' + option normally causes a fatal error. + + -- Request: .sy cmds + -- Register: \n[systat] + Execute the shell command(s) specified by CMDS. The output is not + saved anywhere, so it is up to the user to do so. + + It is an error to use this request in safer mode; this is the + default. Give GNU 'troff' or a front end program the '-U' option + to enable unsafe mode. + + The following code fragment introduces the current time into a + document. + + .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 + + This works by having the Perl script (run by 'sy') write 'nr' + requests that set the registers 'H', 'M', and 'S' to a temporary + file. The 'roff' document then reads the temporary file using the + 'so' request. + + The registers 'seconds', 'minutes', and 'hours', initialized at + startup of GNU 'troff', should satisfy most requirements. Use the + 'af' request to format their values for output. + + .af hours 00 + .af minutes 00 + .af seconds 00 + \n[hours]:\n[minutes]:\n[seconds] + => 02:17:54 + + The writable register 'systat' contains the return value of the + 'system()' function executed by the last 'sy' request. + + -- Request: .open stream file + -- Request: .opena stream file + Open the specified FILE for writing and associates the specified + STREAM with it. + + The 'opena' request is like 'open', but if the file exists, append + to it instead of truncating it. + + It is an error to use these requests in safer mode; this is the + default. Give GNU 'troff' or a front end program the '-U' option + to enable unsafe mode. + + -- Request: .write stream data + -- Request: .writec stream data + Write to the file associated with the specified STREAM. The stream + must previously have been the subject of an open request. The + remainder of the line is interpreted as the 'ds' request reads its + second argument: an initial neutral double quote in CONTENTS is + stripped to allow embedding of leading spaces, and it is read in + copy mode. + + The 'writec' request is like 'write', but only 'write' appends a + newline to the data. + + -- Request: .writem stream xx + Write the contents of the macro or string XX to the file associated + with the specified STREAM. + + XX is read in copy mode, i.e., already formatted elements are + ignored. Consequently, diversions must be unformatted with the + 'asciify' request before calling 'writem'. Usually, this means a + loss of information. + + -- Request: .close stream + Close the specified STREAM; the stream is no longer an acceptable + argument to the 'write' request. + + Here a simple macro to write an index entry. + + .open idx test.idx + . + .de IX + . write idx \\n[%] \\$* + .. + . + .IX test entry + . + .close idx + + -- Escape sequence: \Ve + -- Escape sequence: \V(ev + -- Escape sequence: \V[env] + Interpolate the contents of the specified environment variable ENV + (one-character name E, two-character name EV) as returned by the + function 'getenv(3)'. '\V' is interpreted even in copy mode (*note + Copy Mode::). + +5.34 Postprocessor Access +========================= + +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 '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 'gropdf(1)', 'grops(1)', or +'grotty(1)'. + + -- Request: .device xxx ... + -- Escape sequence: \X'xxx ...' + Embed all XXX arguments into GNU 'troff' output as parameters to a + device control command 'x X'. The meaning and interpretation of + such parameters is determined by the output driver or other + postprocessor. + + The 'device' request processes its arguments in copy mode (*note + Copy Mode::). An initial neutral double quote in CONTENTS is + stripped to allow embedding of leading spaces. By contrast, within + '\X' arguments, the escape sequences '\&', '\)', '\%', and '\:' are + ignored; '\<SP>' and '\~' are converted to single space characters; + and '\\' has its escape character stripped. So that the basic + Latin subset of the Unicode character set(1) (*note Postprocessor + Access-Footnote-1::) can be reliably encoded in device control + commands, seven special character escape sequences ('\-', '\[aq]', + '\[dq]', '\[ga]', '\[ha]', '\[rs]', and '\[ti]',) are mapped to + basic Latin characters; see the 'groff_char(7)' man page. For this + transformation, character translations and special character + definitions are ignored.(2) (*note Postprocessor + Access-Footnote-2::) The use of any other escape sequence in '\X' + parameters is normally an error. + + If the 'use_charnames_in_special' directive appears in the output + device's 'DESC' file, the use of special character escape sequences + is _not_ an error; they are simply output verbatim (with the + exception of the seven mapped to Unicode basic Latin characters, + discussed above). 'use_charnames_in_special' is currently employed + only by 'grohtml'. + + -- Request: .devicem name + -- Escape sequence: \Yn + -- Escape sequence: \Y(nm + -- Escape sequence: \Y[name] + This is approximately equivalent to '\X'\*[NAME]'' (one-character + name N, two-character name NM). However, the contents of the + string or macro NAME are not interpreted; also it is permitted for + NAME to have been defined as a macro and thus contain newlines (it + is not permitted for the argument to '\X' to contain newlines). + The inclusion of newlines requires an extension to the AT&T 'troff' + output format, and confuses drivers that do not know about this + extension (*note Device Control Commands::). + + -- Request: .tag name + -- Request: .taga name + Reserved for internal use. + + (1) that is, ISO 646:1991-IRV or, popularly, "US-ASCII" + + (2) 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. + +5.35 Miscellaneous +================== + +We document here GNU 'troff' features that fit poorly elsewhere. + + -- Request: .nm [start [increment [space [indentation]]]] + -- Register: \n[ln] + -- Register: \n[.nm] + Begin (or, with no arguments, cease) numbering output lines. START + assigns the number of the _next_ output line. Only line numbers + divisible by INCREMENT are marked (default: '1'). SPACE configures + the horizontal spacing between the number and the text (default: + '1'). Any given INDENTATION is applied to the numbers (default: + '0'). The third and fourth arguments are reckoned in numeral + widths ('\0'). START must be non-negative and INCREMENT positive. + + The formatter aligns the number to the right in a width of three + numeral spaces plus INDENTATION, then catenates SPACE and the + output line. The line length is _not_ reduced. Depending on the + value of the page offset,(1) (*note Miscellaneous-Footnote-1::) + 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, '.nm +0' resumes it + using the previously active parameters. + + The parameters of 'nm' are associated with the environment (*note + Environments::). + + While numbering is enabled, the output line number register '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 + INCREMENT) or because numbering is suppressed (see the 'nn' request + below). + + The '.nm' register tracks the enablement status of numbering. + Temporary suspension of numbering with the 'nn' request does _not_ + alter its value. + + .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 + => Programming, when stripped of all its cir- + => 999 cumstantial irrelevancies, boils down to no + => more and no less than very effective think- + => ing so as to avoid unmastered complexity, to + => very vigorous separation of your many dif- + => ferent concerns. + => 1002 -- Edsger Dijkstra + => + => 1 This guy's arrogance takes your breath away. + => 2 -- John Backus + + -- Request: .nn [skip] + -- Register: \n[.nn] + Suppress numbering of the next SKIP output lines that would + otherwise be numbered. The default is 1. 'nn' can be invoked when + line numbering is not active; suppression of numbering will take + effect for SKIP lines once 'nm' enables it. + + The '.nn' register stores the count of output lines still to have + their numbering suppressed. + + This count is associated with the environment (*note + Environments::). + + To test whether the current output line will be numbered, you must +check both the '.nm' and '.nn' registers. + + .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 + => Test line numbering. This line ISN'T numbered. + => This line ISN'T numbered. + => 1 This line IS numbered. + => This line ISN'T numbered. + + -- Request: .mc [margin-character [distance] + Begin (or, with no arguments, cease) writing a "margin-character" + to the right of each output line. The DISTANCE argument separates + MARGIN-CHARACTER from the right margin. If absent, the most recent + value is used; the default is 10 points. If an output line exceeds + the line length, the margin character is appended to it. No margin + character is written on lines produced by the '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 (*note + Environments::). + + .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. + => This paragraph is marked with a margin character. | + => + => As seen above, vertical space isn't thus marked. | + => | + => An output line that is present, but empty, is. | + + For compatibility with AT&T 'troff', a call to 'mc' to set the margin +character can't be undone immediately; at least one line gets a margin +character. + + .ll 10n + .nf + .mc | + .mc * + .mc + foo + bar + => foo * + => bar + + The margin character mechanism is commonly used to annotate changes +in documents. The 'groff' distribution ships a program, 'gdiffmk', to +assist with this task.(2) (*note Miscellaneous-Footnote-2::) + + -- Request: .psbb file + -- Register: \n[llx] + -- Register: \n[lly] + -- Register: \n[urx] + -- Register: \n[ury] + Retrieve the bounding box of the PostScript image found in FILE, + which must conform to Adobe's "Document Structuring Conventions" + (DSC), locate a '%%BoundingBox' comment, and store the (upper-, + lower-, -left, -right) values into the registers 'llx', 'lly', + 'urx', and 'ury'. If an error occurs (for example, if no + '%%BoundingBox' comment is present), the formatter sets these + registers to 0. + + The search path for FILE can be controlled with the '-I' + command-line option. + + (1) Recall *note Line Layout::. + + (2) Historically, tools named 'nrchbar' and 'changebar' were +developed for marking changes with margin characters and could be found +in archives of the 'comp.sources.unix' USENET group. Some proprietary +Unices also offer(ed) a 'diffmk' program. + +5.36 'gtroff' Internals +======================= + +'gtroff' processes input in three steps. One or more input characters +are converted to an "input token".(1) (*note Gtroff +Internals-Footnote-1::) Then, one or more input tokens are converted to +an "output node". Finally, output nodes are converted to the +intermediate output language understood by all output devices. + + Actually, before step one happens, '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. *Note +Identifiers::, for more on this topic. + + For example, the input string 'fi\[:u]' is converted into a character +token 'f', a character token 'i', and a special token ':u' (representing +u umlaut). Later on, the character tokens 'f' and 'i' are merged to a +single output node representing the ligature glyph 'fi' (provided the +current font has a glyph for this ligature); the same happens with ':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, '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. + + .di xxx + a + \!b + c + .br + .di + +It contains these elements. + +node list token list element number + +line start node -- 1 +glyph node 'a' -- 2 +word space node -- 3 +-- 'b' 4 +-- '\n' 5 +glyph node 'c' -- 6 +vertical size node -- 7 +vertical size node -- 8 +-- '\n' 9 + +Elements 1, 7, and 8 are inserted by 'gtroff'; the latter two (which are +always present) specify the vertical extent of the last line, possibly +modified by '\x'. The '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 '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 'chop' request simply reduces the number of elements in a macro, +string, or diversion by one. Exceptions are "compatibility save" and +"compatibility ignore" input tokens, which are ignored. The 'substring' +request also ignores those input tokens. + + Some requests like 'tr' or '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 'foo' isn't available by +default, so we provide a substitution using the 'fchar' request and map +it to input character 'x'. + + .fchar \[foo] foo + .tr x \[foo] + +Now let us assume that we install an additional special font 'bar' that +has glyph 'foo'. + + .special bar + .rchar \[foo] + +Since glyphs defined with 'fchar' are searched before glyphs in special +fonts, we must call 'rchar' to remove the definition of the fallback +glyph. Anyway, the translation is still active; 'x' now maps to the +real glyph 'foo'. + + Macro and request arguments preserve compatibility mode enablement. + + .cp 1 \" switch to compatibility mode + .de xx + \\$1 + .. + .cp 0 \" switch compatibility mode off + .xx caf\['e] + => café + +Since compatibility mode is enabled while 'de' is invoked, the macro +'xx' enables compatibility mode when it is called. Argument '$1' can +still be handled properly because it inherits the compatibility mode +enablement status that was active at the point where 'xx' was called. + + After interpolation of the parameters, the compatibility save and +restore tokens are removed. + + (1) Except the escape sequences '\f', '\F', '\H', '\m', '\M', '\R', +'\s', and '\S', which are processed immediately if not in copy mode. + +5.37 Debugging +============== + + 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 + + GNU '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 'lf' request to preserve the identity of the +line numbers and names of input files. GNU '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 'troff''s '-b' option, or produced on demand with the +'backtrace' request. The 'tm' and related requests can be used to emit +customized diagnostic messages or for instrumentation while +troubleshooting. The 'ex' and '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. + + -- Request: .lf line [file] + Set the input line number (and, optionally, the file name) GNU + 'troff' shall use for error and warning messages. LINE is the + input line number of the _next_ line. Without an argument, the + request is ignored. + + 'lf''s primary purpose is to aid the debugging of documents that + undergo preprocessing. Programs like 'tbl' that transform input in + their own languages into 'roff' requests use it so that any + diagnostic messages emitted by 'troff' correspond to the source + document. + + -- Request: .tm message + -- Request: .tm1 message + -- Request: .tmc message + Send 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 MESSAGE are ignored. + + 'tm1' is similar, but recognizes and strips a leading neutral + double quote from MESSAGE to allow the embedding of leading spaces. + + 'tmc' works as 'tm1', but does not append a newline. + + -- Request: .ab [message] + Write any MESSAGE to the standard error stream (like 'tm') and then + abort GNU 'troff'; that is, stop processing and terminate with a + failure status. + + -- Request: .ex + Exit GNU 'troff'; that is, stop processing and terminate with a + successful status. To stop processing only the current file, use + the 'nx' request; see *note I/O::. + + 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. + + .if \n[DB] .tm debugging output + +To activate such statements, use the '-r' option to set the register. + + groff -rDB=1 file + + If it is known in advance that there are many errors and no useful +output, GNU 'troff' can be forced to suppress formatted output with the +'-z' option. + + -- Request: .pev + Report the state of the current environment followed by that of all + other environments to the standard error stream. + + -- Request: .pm + Report, to the standard error stream, the names of all defined + macros, strings, and diversions with their sizes in bytes. + + -- Request: .pnr + Report the names and contents of all currently defined registers to + the standard error stream. + + -- Request: .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. + + -- Request: .fl + Instruct 'gtroff' to flush its output immediately. The intent is + for interactive use, but this behaviour is currently not + implemented in 'gtroff'. Contrary to Unix 'troff', TTY output is + sent to a device driver also ('grotty'), making it non-trivial to + communicate interactively. + + This request causes a line break. + + -- Request: .backtrace + Write the state of the input stack to the standard error stream. + + Consider the following in a file 'test'. + + .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 + + The '-b' option of GNU 'troff' causes a backtrace to be generated + on each error or warning. Some warnings have to be enabled; *Note + Warnings::. + + -- Register: \n[slimit] + If greater than 0, sets the maximum quantity of objects on GNU + 'troff''s internal input stack. If less than or equal to 0, there + is no limit: recursion can continue until program memory is + exhausted. The default is 1,000. + + -- Request: .warnscale su + Set the scaling unit used in certain warnings to SU, which can take + the values 'u', 'i', 'c', 'p', and 'P'. The default is 'i'. + + -- Request: .spreadwarn [limit] + Emit a 'break' warning if the additional space inserted for each + space between words in an output line adjusted to both margins with + '.ad b' is larger than or equal to LIMIT. A negative value is + treated as zero; an absent argument toggles the warning on and off + without changing LIMIT. The default scaling unit is 'm'. At + startup, 'spreadwarn' is inactive and LIMIT is 3m. + + For example, + + .spreadwarn 0.2m + + causes a warning if 'break' warnings are not suppressed and + 'gtroff' must add 0.2m or more for each inter-word space in a line. + *Note Warnings::. + + GNU 'troff' has command-line options for reporting warnings ('-w') +and backtraces ('-b') when a warning or an error occurs. + + -- Request: .warn [n] + -- Register: \n[.warn] + Select the categories, or "types", of reported warnings. N 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 *note + Warnings::. For example, '.warn 0' disables all warnings, and + '.warn 1' disables all warnings except those about missing glyphs. + If no argument is given, all warning categories are enabled. + + The read-only register '.warn' contains the sum of the numeric + codes of enabled warning categories. + +5.37.1 Warnings +--------------- + +Warning diagnostics emitted by GNU 'troff' are divided into named, +numbered categories. The name associated with each warning category is +used by the '-w' and '-W' options. Each category is also assigned a +power of two; the sum of enabled category values is used by the 'warn' +request and the '.warn' register. + + Warnings of each category are produced under the following +circumstances. + +'char' +'1' + No mounted font defines a glyph for the requested character. This + category is enabled by default. + +'number' +'2' + An invalid numeric expression was encountered. This category is + enabled by default. *Note Numeric Expressions::. + +'break' +'4' + A filled output line could not be broken such that its length was + less than the output line length '\n[.l]'. This category is + enabled by default. + +'delim' +'8' + The closing delimiter in an escape sequence was missing or + mismatched. + +'el' +'16' + The 'el' request was encountered with no prior corresponding 'ie' + request. *Note if-else::. + +'scale' +'32' + A scaling unit inappropriate to its context was used in a numeric + expression. + +'range' +'64' + A numeric expression was out of range for its context. + +'syntax' +'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 'groff' + extension conditional expression operator was used while in + compatibility mode. + +'di' +'256' + A 'di', 'da', 'box', or 'boxa' request was invoked without an + argument when there was no current diversion. + +'mac' +'512' + 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 (*note Page Location Traps::). In such cases, the + unplanted macro is _not_ dereferenced, so it is not created if it + does not exist. + +'reg' +'1024' + An undefined register was used. When an undefined register is + dereferenced, it is automatically defined with a value of 0. So, + unless it is later deleted, at most one warning is given for each. + +'tab' +'2048' + A tab character was encountered where a number was expected, or + appeared in an unquoted macro argument. + +'right-brace' +'4096' + A right brace escape sequence '\}' was encountered where a number + was expected. + +'missing' +'8192' + A request was invoked with a mandatory argument absent. + +'input' +'16384' + An invalid character occurred on the input stream. + +'escape' +'32768' + An unsupported escape sequence was encountered. + +'space' +'65536' + 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. + +'font' +'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. + +'ig' +'262144' + An invalid escape sequence occurred in input ignored using the 'ig' + request. This warning category diagnoses a condition that is an + error when it occurs in non-ignored input. + +'color' +'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. + +'file' +'1048576' + An attempt was made to load a file that does not exist. This + category is enabled by default. + + Two warning names group other warning categories for convenience. + +'all' + All warning categories except 'di', 'mac' and 'reg'. This + shorthand is intended to produce all warnings that are useful with + macro packages written for AT&T 'troff' and its descendants, which + have less fastidious diagnostics than GNU 'troff'. + +'w' + All warning categories. Authors of documents and macro packages + targeting 'groff' are encouraged to use this setting. + +5.38 Implementation Differences +=============================== + +GNU 'troff' has a number of features that cause incompatibilities with +documents written for other versions of 'troff'. Some GNU extensions to +'troff' have become supported by other implementations. + +5.38.1 Safer Mode +----------------- + +The formatter operates in "safer" mode by default; to mitigate risks +from untrusted input documents, the 'pi' and 'sy' requests are disabled. +GNU 'troff''s '-U' option enables "unsafe mode", restoring their +function and enabling additional 'groff' extension requests, 'open', +'opena', and 'pso'. *Note I/O::. + +5.38.2 Compatibility Mode +------------------------- + +Long identifier names may be GNU 'troff''s most obvious innovation. +AT&T 'troff' interprets '.dsabcd' as defining a string 'ab' with +contents 'cd'. Normally, GNU 'troff' interprets this as a call of a +macro named 'dsabcd'. AT&T 'troff' also interprets '\*[' and '\n[' as +an interpolation of a string or register, respectively, named '['. In +GNU 'troff', however, the '[' is normally interpreted as delimiting a +long name. In compatibility mode, GNU 'troff' interprets names in the +traditional way; they thus can be two characters long at most. + + -- Request: .cp [n] + -- Register: \n[.C] + If N is missing or non-zero, turn on compatibility mode; otherwise, + turn it off. + + The read-only register '.C' is 1 if compatibility mode is on, + 0 otherwise. + + Compatibility mode can be also turned on with the '-C' command-line + option. + + -- Request: .do name + -- Register: \n[.cp] + The 'do' request interprets the string, request, diversion, or + macro NAME (along with any further arguments) with compatibility + mode disabled. Compatibility mode is restored (only if it was + active) when the _expansion_ of NAME is interpreted; that is, the + restored compatibility state applies to the contents of the macro, + string, or diversion NAME as well as data read from files or pipes + if NAME is any of the 'so', 'soquiet', 'mso', 'msoquiet', or 'pso' + requests. + + The following example illustrates several aspects of 'do' behavior. + + .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 + => FOO groff FOO compatibility c1 ~ + + The read-only register '.cp', meaningful only when dereferenced + from a 'do' request, is 1 if compatibility mode was on when the + 'do' request was encountered, and 0 if it was not. This register + is specialized and may require a statement of rationale. + + When writing macro packages or documents that use GNU '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 'so' or '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 '\n(.C' into a register, say, '_C', at the beginning of + your file, turn compatibility mode off with '.cp 0', then restore + it from that register at the end with '.cp \n(_C'. At the same + time, a modular design of a document or macro package may lead you + to multiple layers of inclusion. You cannot use the same register + name everywhere lest you "clobber" the value from a preceding or + enclosing context. The two-character register name space of AT&T + 'troff' is confining and mnemonically challenging; you may wish to + use the more capacious name space of GNU 'troff'. However, + attempting '.nr _my_saved_C \n(.C' will not work in compatibility + mode; the register name is too long. "This is exactly what 'do' is + for," you think, '.do nr _my_saved_C \n(.C'. The foregoing will + always save zero to your register, because 'do' turns compatibility + mode _off_ while it interprets its argument list. + + To robustly save compatibility mode before switching it off, use + + .do nr _my_saved_C \n[.cp] + .cp 0 + + at the beginning of your file, followed by + + .cp \n[_my_saved_C] + .do rr _my_saved_C + + at the end. As in the C language, we all have to share one big + name space, so choose a register name that is unlikely to collide + with other uses. + + Normally, GNU 'troff' preserves the interpolation depth in delimited +arguments, but not in compatibility mode. + + .ds xx ' + \w'abc\*(xxdef' + => 168 (normal mode on a terminal device) + => 72def' (compatibility mode on a terminal device) + + Furthermore, the escape sequences '\f', '\H', '\m', '\M', '\R', '\s', +and '\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. + + .de xx + Hello! + .. + \fB.xx\fP + => .xx (normal mode) + => Hello! (compatibility mode) + + Normally, the syntax form '\s'N accepts only a single character (a +digit) for N, consistently with other forms that originated in AT&T +'troff', like '\*', '\$', '\f', '\g', '\k', '\n', and '\z'. In +compatibility mode only, a non-zero N must be in the range 4-39. Legacy +documents relying upon this quirk of parsing(1) (*note Compatibility +Mode-Footnote-1::) should be migrated to another '\s' form. + + (1) The Graphic Systems C/A/T phototypesetter (the original device +target for AT&T '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 #54 (§2.3), and more recently, McIlroy referred to it +as a "living fossil". + +5.38.3 Other Differences +------------------------ + +'groff' request names unrecognized by other 'troff' implementations will +likely be ignored by them; escape sequences that are 'groff' extensions +are liable to be interpreted as if the escape character were not +present. For example, the adjustable, non-breaking escape sequence '\~' +is also supported by Heirloom Doctools 'troff' 050915 (September 2005), +'mandoc' 1.9.5 (2009-09-21), 'neatroff' (commit 1c6ab0f6e, 2016-09-13), +and Plan 9 from User Space 'troff' (commit 93f8143600, 2022-08-12), but +not by Solaris or Documenter's Workbench 'troff's. *Note Manipulating +Filling and Adjustment::. + + GNU 'troff' does not allow the use of the escape sequences '\|', +'\^', '\&', '\{', '\}', '\<SP>', '\'', '\`', '\-', '\_', '\!', '\%', and +'\c' in identifiers; AT&T 'troff' does. The '\A' escape sequence (*note +Identifiers::) may be helpful in avoiding use of these escape sequences +in names. + + When adjusting to both margins, AT&T 'troff' at first adjusts spaces +starting from the right; GNU '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. + + GNU 'troff' does not always hyphenate words as AT&T 'troff' does. +The AT&T implementation uses a set of hard-coded rules specific to +English, while GNU 'troff' uses language-specific hyphenation pattern +files derived from TeX. Furthermore, in old versions of 'troff' there +was a limited amount of space to store hyphenation exceptions (arguments +to the 'hw' request); GNU 'troff' has no such restriction. + + GNU 'troff' predefines a string '.T' containing the argument given to +the '-T' command-line option, namely the current output device (for +example, 'pdf' or 'utf8'). The existence of this string is a common +feature of post-CSTR #54 'troff's(1) (*note Other +Differences-Footnote-1::) but valid values are specific to each +implementation. + + AT&T 'troff' ignored attempts to remove read-only registers; GNU +'troff' honors such requests. *Note Built-in Registers::. + + The (read-only) register '.T' interpolates 1 if GNU 'troff' is called +with the '-T' command-line option, and 0 otherwise. This behavior +differs from AT&T 'troff', which interpolated 1 only if 'nroff' was the +formatter and was called with '-T'. + + AT&T 'troff' and other implementations handle the 'lf' request +differently. For them, its LINE argument changes the line number of the +_current_ line. + + AT&T 'troff' had only environments named '0', '1', and '2'. In GNU +'troff', any number of environments may exist, using any valid +identifiers for their names (*note Identifiers::.) + + Fractional type sizes cause one noteworthy incompatibility. In AT&T +'troff' the 'ps' request ignores scaling units and thus '.ps 10u' sets +the type size to 10 points, whereas in GNU 'troff' it sets the type size +to 10 _scaled_ points. *Note Using Fractional Type Sizes::. + + The 'ab' request differs from AT&T 'troff': GNU '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. + + The 'bp' request differs from AT&T 'troff': GNU 'troff' does not +accept a scaling unit on the argument, a page number; the former +(somewhat uselessly) does. + + The 'pm' request differs from AT&T 'troff': GNU 'troff' reports the +sizes of macros, strings, and diversions in bytes and ignores an +argument to report only the sum of the sizes. + + Unlike AT&T 'troff', GNU 'troff' does not ignore the '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 12. + + In GNU '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 'bd', 'cs', 'tkf', 'tr', or '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 + + .di x + \\\\ + .br + .di + .x + +produces '\\' in GNU 'troff'. Each pair of backslashes becomes one +backslash _glyph_; the resulting backslashes are thus not interpreted as +escape _characters_ when they are reread as the diversion is output. +AT&T 'troff' _would_ interpret them as escape characters when rereading +them and end up printing one '\'. + + One correct way to obtain a printable backslash in most documents is +to use the '\e' escape sequence; this always prints a single instance of +the current escape character,(2) (*note Other Differences-Footnote-2::) +regardless of whether or not it is used in a diversion; it also works in +both GNU 'troff' and AT&T 'troff'. + + The other correct way, appropriate in contexts independent of the +backslash's common use as a 'troff' escape character--perhaps in +discussion of character sets or other programming languages--is the +character escape '\(rs' or '\[rs]', for "reverse solidus", from its name +in the ECMA-6 (ISO/IEC 646) standard.(3) (*note Other +Differences-Footnote-3::) + + To store an escape sequence in a diversion that is interpreted when +the diversion is reread, either use the traditional '\!' transparent +output facility, or, if this is unsuitable, the new '\?' escape +sequence. *Note Diversions:: and *note 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, AT&T 'troff' will output the +partially collected line at the end of input; GNU 'troff' will not. + + (1) DWB 3.3, Solaris, Heirloom Doctools, and Plan 9 'troff' all +support it. + + (2) Naturally, if you've changed the escape character, you need to +prefix the 'e' with whatever it is--and you'll likely get something +other than a backslash in the output. + + (3) The 'rs' special character identifier was not defined in AT&T +'troff''s font description files, but is in those of its lineal +descendant, Heirloom Doctools 'troff', as of the latter's 060716 release +(July 2006). + +6 File Formats +************** + +All files read and written by 'gtroff' are text files. The following +two sections describe their format. + +6.1 'gtroff' Output +=================== + +This section describes the 'groff' intermediate output format produced +by GNU 'troff'. + + As 'groff' is a wrapper program around GNU 'troff' and automatically +calls an output driver (or "postprocessor"), this output does not show +up normally. This is why it is called _intermediate_. 'groff' provides +the option '-Z' to inhibit postprocessing such that the produced +intermediate output is sent to standard output just as it is when +calling GNU 'troff' directly. + + Here, the term "troff output" describes what is output by GNU +'troff', while "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 AT&T's implementation +and implements obsolete elements for compatibility; otherwise, both +formats are the same.(1) (*note gtroff Output-Footnote-1::) + + 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 'gtroff' language. While the '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 'gtroff' is fairly readable, +while output from AT&T 'troff' is rather hard to understand because of +strange habits that are still supported, but not used any longer by +'gtroff'. + + (1) The parser and postprocessor for intermediate output can be found +in the file +'GROFF-SOURCE-DIR/src/libs/libdriver/input.cpp'. + +6.1.1 Language Concepts +----------------------- + +The fundamental operation of the GNU 'troff' formatter is the +translation of the '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 "command" always refers to this +intermediate output language, and never to the '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. + +6.1.1.1 Separation +.................. + +AT&T 'troff' output has strange requirements regarding whitespace. The +'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 +"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 "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 '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 'D' and 'x' commands were +designed to request a syntactical line break after their last argument. +Only one command, '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. + +6.1.1.2 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 'u', the basic unit of the device, some +use '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 '#' 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. + +6.1.1.3 Document Parts +...................... + +A correct intermediate output document consists of two parts, the +"prologue" and the "body". + + The task of the prologue is to set the general device parameters +using three exactly specified commands. 'gtroff''s prologue is +guaranteed to consist of the following three lines (in that order): + + x T DEVICE + x res N H V + x init + +with the arguments set as outlined in *note 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 +'x stop' command is encountered; the last line of any 'gtroff' +intermediate output always contains such a command. + + Semantically, the body is page oriented. A new page is started by a +'p' command. Positioning, writing, and drawing commands are always done +within the current page, so they cannot occur before the first 'p' +command. Absolute positioning (by the 'H' and 'V' commands) is done +relative to the current page; all other positioning is done relative to +the current location within this page. + +6.1.2 Command Reference +----------------------- + +This section describes all intermediate output commands, both from AT&T +'troff' as well as the 'gtroff' extensions. + +6.1.2.1 Comment Command +....................... + +'#ANYTHING<end of line>' + A comment. Ignore any characters from the '#' 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. + +6.1.2.2 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. + +'C ID<whitespace>' + Typeset the glyph of the special character ID. Trailing + syntactical space is necessary to allow special character names of + arbitrary length. The drawing position is not advanced. + +'c G' + Typeset the glyph of the ordinary character C. The drawing + position is not advanced. + +'f N' + Select the font mounted at position N. N cannot be negative. + +'H N' + Horizontally move the drawing position to N basic units from the + left edge of the page. N cannot be negative. + +'h N' + Move the drawing position right N basic units. AT&T 'troff' + allowed negative N; GNU 'troff' does not produce such values, but + 'groff''s output driver library handles them. + +'m COLOR-SCHEME [COMPONENT ...]' + Select the stroke color using the COMPONENTs in the color space + SCHEME. Each COMPONENT is an integer between 0 and 65535. The + quantity of components and their meanings vary with each SCHEME. + This command is a 'groff' extension. + + 'mc CYAN MAGENTA YELLOW' + Use the CMY color scheme with components cyan, magenta, and + yellow. + + 'md' + Use the default color (no components; black in most cases). + + 'mg GRAY' + Use a grayscale color scheme with a component ranging between + 0 (black) and 65535 (white). + + 'mk CYAN MAGENTA YELLOW BLACK' + Use the CMYK color scheme with components cyan, magenta, + yellow, and black. + + 'mr RED GREEN BLUE' + Use the RGB color scheme with components red, green, and blue. + +'N N' + Typeset the glyph with index N in the current font. N is normally + a non-negative integer. The drawing position is not advanced. The + 'html' and 'xhtml' devices use this command with negative N to + produce unbreakable space; the absolute value of N is taken and + interpreted in basic units. + +'n B A' + Indicate a break. No action is performed; the command is present + to make the output more easily parsed. The integers B and A + describe the vertical space amounts before and after the break, + respectively. GNU 'troff' issues this command but 'groff''s output + driver library ignores it. See 'v' and 'V' below. + +'p N' + Begin a new page, setting its number to N. Each page is + independent, even from those using the same number. The vertical + drawing position is set to 0. All positioning, writing, and + drawing commands are interpreted in the context of a page, so a + 'p' command must precede them. + +'s N' + Set type size to N scaled points (unit 'z' in GNU 'troff'. AT&T + 'troff' used unscaled points 'p' instead; see *note Output Language + Compatibility::. + +'t XYZ<whitespace>' +'t XYZ DUMMY-ARG<whitespace>' + Typeset a word XYZ; that is, set a sequence of ordinary glyphs + named X, Y, Z, ..., 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). 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 'C' command to emplace glyphs of special + characters. The 't' command is a 'groff' extension and is output + only for devices whose 'DESC' file contains the 'tcommand' + directive; see *note DESC File Format::. + +'u N XYZ<whitespace>' + Typeset word XYZ with track kerning. As 't', but after placing + each glyph, the drawing position is further advanced horizontally + by N basic units ('u'). The 'u' command is a 'groff' extension and + is output only for devices whose 'DESC' file contains the + 'tcommand' directive; see *note DESC File Format::. + +'V N' + Vertically move the drawing position to N basic units from the top + edge of the page. N cannot be negative. + +'v N' + Move the drawing position down N basic units. AT&T 'troff' allowed + negative N; GNU 'troff' does not produce such values, but 'groff''s + output driver library handles them. + +'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 '\~' or horizontal motion escape sequences are not. GNU + 'troff' issues this command but 'groff''s output driver library + ignores it. See 'h' and 'H' above. + +6.1.2.3 Graphics Commands +......................... + +Each graphics or drawing command in the intermediate output starts with +the letter '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 'D' command +may not be followed by another command on the same line (apart from a +comment), so each 'D' command is terminated by a syntactical line break. + + '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 +'u'. The arguments called H1, H2, ..., HN stand for horizontal +distances where positive means right, negative left. The arguments +called V1, V2, ..., 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 'gtroff' '\D' +escape sequence. *Note Drawing Geometric Objects::. + + Unknown '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 <line break> +means a syntactical line break as defined above. + +'D~ H1 V1 H2 V2 ... HN VN<line break>' + Draw B-spline from current position to offset (H1,V1), then to + offset (H2,V2), if given, etc., up to (HN,VN). This command takes + a variable number of argument pairs; the current position is moved + to the terminal point of the drawn curve. + +'Da H1 V1 H2 V2<line break>' + Draw arc from current position to (H1,V1)+(H2,V2) with center at + (H1,V1); then move the current position to the final point of the + arc. + +'DC D<line break>' +'DC D DUMMY-ARG<line break>' + Draw a solid circle using the current fill color with diameter D + (integer in basic units '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 'gtroff' extension. + +'Dc D<line break>' + Draw circle line with diameter D (integer in basic units 'u') with + leftmost point at the current position; then move the current + position to the rightmost point of the circle. + +'DE H V<line break>' + Draw a solid ellipse in the current fill color with a horizontal + diameter of H and a vertical diameter of V (both integers in basic + units 'u') with the leftmost point at the current position; then + move to the rightmost point of the ellipse. This command is a + 'gtroff' extension. + +'De H V<line break>' + Draw an outlined ellipse with a horizontal diameter of H and a + vertical diameter of V (both integers in basic units 'u') with the + leftmost point at current position; then move to the rightmost + point of the ellipse. + +'DF COLOR-SCHEME [COMPONENT ...]<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 '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 + 'gtroff''s escape sequences '\D'F ...'' and '\M' (with no other + corresponding graphics commands). No position changing. This + command is a 'gtroff' extension. + + 'DFc CYAN MAGENTA YELLOW<line break>' + Set fill color for solid drawing objects using the CMY color + scheme, having the 3 color components CYAN, MAGENTA, and + YELLOW. + + 'DFd<line break>' + Set fill color for solid drawing objects to the default fill + color value (black in most cases). No component arguments. + + 'DFg GRAY<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). + + 'DFk CYAN MAGENTA YELLOW BLACK<line break>' + Set fill color for solid drawing objects using the CMYK color + scheme, having the 4 color components CYAN, MAGENTA, YELLOW, + and BLACK. + + 'DFr RED GREEN BLUE<line break>' + Set fill color for solid drawing objects using the RGB color + scheme, having the 3 color components RED, GREEN, and BLUE. + +'Df N<line break>' + The argument N must be an integer in the range -32767 to 32767. + + 0 <= N <= 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 'DFg'. + + N < 0 or N > 1000 + Set the filling color to the color that is currently being + used for the text and the outline, see command 'm'. For + example, the command sequence + + mg 0 0 65535 + Df -1 + + sets all colors to blue. + + No position changing. This command is a 'gtroff' extension. + +'Dl H V<line break>' + Draw line from current position to offset (H,V) (integers in basic + units 'u'); then set current position to the end of the drawn line. + +'Dp H1 V1 H2 V2 ... HN VN<line break>' + Draw a polygon line from current position to offset (H1,V1), from + there to offset (H2,V2), etc., up to offset (HN,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. This command is a 'gtroff' extension. + +'DP H1 V1 H2 V2 ... HN VN<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 'Dp' command. This command is a 'gtroff' extension. + +'Dt N<line break>' + Set the current line thickness to N (an integer in basic units 'u') + if N>0; if N=0 select the smallest available line thickness; if N<0 + set the line thickness proportional to the type size (this is the + default before the first '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. This command is a 'gtroff' extension. + +6.1.2.4 Device Control Commands +............................... + +Each device control command starts with the letter 'x', followed by a +space character (optional or arbitrary space or tab in 'gtroff') and a +subcommand letter or word; each argument (if any) must be preceded by a +syntactical space. All '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, 'gtroff' outputs the initialization command 'x i' as 'x init' +and the resolution command 'x r' as 'x res'. + + In the following, the syntax element <line break> means a syntactical +line break (*note Separation::). + +'xF NAME<line break>' + The 'F' stands for FILENAME. + + Use NAME as the intended name for the current file in error + reports. This is useful for remembering the original file name + when 'gtroff' uses an internal piping mechanism. The input file is + not changed by this command. This command is a 'gtroff' extension. + +'xf N S<line break>' + The 'f' stands for FONT. + + Mount font position N (a non-negative integer) with font named S (a + text word). *Note Font Positions::. + +'xH N<line break>' + The 'H' stands for HEIGHT. + + Set glyph height to N (a positive integer in scaled points 'z'). + AT&T 'troff' uses the unit points ('p') instead. *Note Output + Language Compatibility::. + +'xi<line break>' + The 'i' stands for INIT. + + Initialize device. This is the third command of the prologue. + +'xp<line break>' + The 'p' stands for PAUSE. + + Parsed but ignored. The AT&T 'troff' manual documents this command + as + + pause device, can be restarted + + but GNU 'troff' output drivers do nothing with this command. + +'xr N H V<line break>' + The 'r' stands for RESOLUTION. + + Resolution is N, while H is the minimal horizontal motion, and V + the minimal vertical motion possible with this device; all + arguments are positive integers in basic units 'u' per inch. This + is the second command of the prologue. + +'xS N<line break>' + The 'S' stands for SLANT. + + Set slant to N (an integer in basic units 'u'). + +'xs<line break>' + The 's' stands for STOP. + + Terminates the processing of the current file; issued as the last + command of any intermediate 'troff' output. + +'xt<line break>' + The 't' stands for TRAILER. + + Generate trailer information, if any. In GNU 'troff', this is + ignored. + +'xT XXX<line break>' + The 'T' stands for TYPESETTER. + + Set the name of the output driver to XXX, a sequence of + non-whitespace characters terminated by whitespace. The possible + names correspond to those of 'groff''s '-T' option. This is the + first command of the prologue. + +'xu N<line break>' + The 'u' stands for UNDERLINE. + + Configure underlining of spaces. If N is 1, start underlining of + spaces; if N is 0, stop underlining of spaces. This is needed for + the 'cu' request in 'nroff' mode and is ignored otherwise. This + command is a 'gtroff' extension. + +'xX ANYTHING<line break>' + The 'x' stands for X-ESCAPE. + + Send string ANYTHING uninterpreted to the device. If the line + following this command starts with a '+' character this line is + interpreted as a continuation line in the following sense. The '+' + 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 + '+' character. This command is generated by the 'gtroff' escape + sequence '\X'. The line-continuing feature is a 'gtroff' + extension. + +6.1.2.5 Obsolete Command +........................ + +In AT&T '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 digits and +a character. + +DDG + Move right DD (exactly two decimal digits) basic units 'u', then + print glyph G (represented as a single character). + + In GNU '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 AT&T 'troff', large clusters of these and other + commands are used, mostly without spaces; this made such output + almost unreadable. + + 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 'gtroff', this is only used for the devices 'X75', 'X75-12', +'X100', and 'X100-12'. For other devices, the commands 't' and 'u' +provide a better functionality. + +6.1.3 Intermediate Output Examples +---------------------------------- + +This section presents the intermediate output generated from the same +input for three different devices. The input is the sentence 'hell +world' fed into 'gtroff' on the command line. + +High-resolution device 'ps' + + This is the standard output of 'gtroff' if no '-T' option is given. + + shell> echo "hell world" | groff -Z -T ps + + x T ps + x res 72000 1 1 + x init + p1 + x font 5 TR + f5 + s10000 + V12000 + H72000 + thell + wh2500 + tw + H96620 + torld + n12000 0 + x trailer + V792000 + x stop + + This output can be fed into 'grops' to get its representation as a + PostScript file. + +Low-resolution device 'latin1' + + This is similar to the high-resolution device except that the + positioning is done at a minor scale. Some comments (lines + starting with '#') were added for clarification; they were not + generated by the formatter. + + shell> echo "hell world" | groff -Z -T latin1 + + # prologue + x T latin1 + x res 240 24 40 + x init + # 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 + # ...the end of the document has been reached + x trailer + V2640 + x stop + + This output can be fed into 'grotty' to get a formatted text + document. + +AT&T '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. + + shell> echo "hell world" | groff -Z -T X100 + + x T X100 + x res 100 1 1 + x init + p1 + x font 5 TR + f5 + s10 + V16 + H100 + # write text with jump-and-write commands + ch07e07l03lw06w11o07r05l03dh7 + n16 0 + x trailer + V1100 + x stop + + This output can be fed into 'xditview' or 'gxditview' for + displaying in X. + + Due to the obsolete jump-and-write command, the text clusters in + the AT&T 'troff' output are almost unreadable. + +6.1.4 Output Language Compatibility +----------------------------------- + +The intermediate output language of AT&T 'troff' was first documented in +'A Typesetter-independent TROFF', by Brian Kernighan, and by 1992 the +AT&T 'troff' manual was updated to incorprate a description of it. + + The GNU 'troff' intermediate output format is compatible with this +specification except for the following features. + + * The classical quasi-device independence is not yet implemented. + + * The old hardware was very different from what we use today. So the + 'groff' devices are also fundamentally different from the ones in + AT&T 'troff'. For example, the AT&T PostScript device is called + 'post' and has a resolution of only 720 units per inch, suitable + for printers 20 years ago, while 'groff''s 'ps' device has a + resolution of 72000 units per inch. Maybe, by implementing some + rescaling mechanism similar to the classical quasi-device + independence, 'groff' could emulate AT&T's 'post' device. + + * The B-spline command 'D~' is correctly handled by the intermediate + output parser, but the drawing routines aren't implemented in some + of the postprocessor programs. + + * The argument of the commands 's' and 'x H' has the implicit unit + scaled point 'z' in 'gtroff', while AT&T 'troff' has point ('p'). + This isn't an incompatibility but a compatible extension, for both + units coincide for all devices without a 'sizescale' parameter in + the 'DESC' file, including all postprocessors from AT&T and + 'groff''s text devices. The few 'groff' devices with a 'sizescale' + parameter either do not exist for AT&T 'troff', have a different + name, or seem to have a different resolution. So conflicts are + very unlikely. + + * The position changing after the commands 'Dp', 'DP', and 'Dt' is + illogical, but as old versions of 'gtroff' used this feature it is + kept for compatibility reasons. + +6.2 Device and Font Description Files +===================================== + +The 'groff' font and output device description formats are slight +extensions of those used by AT&T device-independent 'troff'. In +distinction to the AT&T implementation, 'groff' lacks a binary format; +all files are text files.(1) (*note Device and Font Description +Files-Footnote-1::) The device and font description files for a device +NAME are stored in a 'devNAME' directory. The device description file +is called 'DESC', and, for each font supported by the device, a font +description file is called 'F', where F is usually an abbreviation of a +font's name and/or style. For example, the 'ps' (PostScript) device has +'groff' font description files for Times roman ('TR') and Zapf Chancery +Medium italic ('ZCMI'), among many others, while the 'utf8' device (for +terminal emulators) has only font descriptions for the roman, italic, +bold, and bold-italic styles ('R', 'I', 'B', and 'BI', respectively). + + Device and font description files are read both by the formatter, GNU +'troff', and by output drivers. The programs delegate these files' +processing to an internal library, 'libgroff', ensuring their consistent +interpretation. + + (1) Plan 9 'troff' has also abandoned the binary format. + +6.2.1 'DESC' File Format +------------------------ + +The 'DESC' file contains a series of directives; each begins a line. +Their order is not important, with two exceptions: (1) the 'res' +directive must precede any 'papersize' directive; and (2) the '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 'res' directive last seen when +'papersize' is encountered). Spaces and/or tabs separate words and are +ignored at line boundaries. Comments start with the '#' character and +extend to the end of a line. Empty lines are ignored. + +'family FAM' + The default font family is FAM. + +'fonts N F1 ... FN' + Fonts F1, ..., FN are mounted at font positions M+1, ..., M+N where + M is the number of 'styles' (see below). This directive may extend + over more than one line. A font name of '0' causes no font to be + mounted at the corresponding position. + +'hor N' + The horizontal motion quantum is N basic units. All horizontal + quantities are rounded to multiples of N. + +'image_generator PROGRAM' + Use PROGRAM to generate PNG images from PostScript input. Under + GNU/Linux, this is usually 'gs', but under other systems (notably + Cygwin) it might be set to another name. The 'grohtml' driver uses + this directive. + +'paperlength N' + The vertical dimension of the output medium is N basic units + (deprecated: use 'papersize' instead). + +'papersize FORMAT-OR-DIMENSION-PAIR-OR-FILE-NAME ...' + 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 'A0'-'A7', + 'B0'-'B7', 'C0'-'C7', 'D0'-'D7'; the U.S. paper types 'letter', + 'legal', 'tabloid', 'ledger', 'statement', and 'executive'; and the + envelope formats 'com10', 'monarch', and 'DL'. Matching is + performed without regard for lettercase. + + Alternatively, the argument can be a custom paper format in the + format 'LENGTH,WIDTH' (with no spaces before or after the comma). + Both LENGTH and WIDTH must have a unit appended; valid units are + 'i' for inches, 'c' for centimeters, 'p' for points, and 'P' for + picas. Example: '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., '/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. + +'paperwidth N' + The horizontal dimension of the output medium is N basic units + (deprecated: use 'papersize' instead). + +'pass_filenames' + Direct GNU 'troff' to emit the name of the source file being + processed. This is achieved with the intermediate output command + 'x F', which 'grohtml' interprets. + +'postpro PROGRAM' + Use PROGRAM as the postprocessor. + +'prepro PROGRAM' + Use PROGRAM as a preprocessor. The 'html' and 'xhtml' output + devices use this directive. + +'print PROGRAM' + Use PROGRAM as a spooler program for printing. If omitted, the + '-l' and '-L' options of 'groff' are ignored. + +'res N' + The device resolution is N basic units per inch. + +'sizes S1 ... SN 0' + The device has fonts at S1, ..., SN scaled points (see below). The + list of sizes must be terminated by '0'. Each SI can also be a + range of sizes M-N. The list can extend over more than one line. + +'sizescale N' + A typographical point is subdivided into N scaled points. The + default is '1'. *Note Using Fractional Type Sizes::. + +'styles S1 ... SM' + The first M mounting positions are associated with styles S1, ..., + SM. + +'tcommand' + The postprocessor can handle the 't' and 'u' intermediate output + commands. + +'unicode' + The output device supports the complete Unicode repertoire. This + directive is useful only for devices that produce character + entities instead of glyphs. + + If 'unicode' is present, no 'charset' section is required in the + font description files since the Unicode handling built into + 'groff' is used. However, if there are entries in a font + description file's 'charset' section, they either override the + default mappings for those particular characters or add new + mappings (normally for composite characters). + + The 'utf8', 'html', and 'xhtml' output devices use this directive. + +'unitwidth N' + Quantities in the font description files are in basic units for + fonts whose type size is N scaled points. + +'unscaled_charwidths' + Make the font handling module always return unscaled character + widths. The 'grohtml' driver uses this directive. + +'use_charnames_in_special' + GNU 'troff' should encode special characters inside device control + commands; see *note Postprocessor Access::. The 'grohtml' driver + uses this directive. + +'vert N' + The vertical motion quantum is N basic units. All vertical + quantities are rounded to multiples of N. + +'charset' + This line and everything following it in the file are ignored. It + is recognized for compatibility with other 'troff' implementations. + In GNU 'troff', character set repertoire is described on a per-font + basis. + + GNU 'troff' recognizes but ignores the directives 'spare1', 'spare2', +and 'biggestfont'. + + The 'res', 'unitwidth', 'fonts', and 'sizes' lines are mandatory. +Directives not listed above are ignored by GNU 'troff' but may be used +by postprocessors to obtain further information about the device. + +6.2.2 Font Description File Format +---------------------------------- + +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. 'groff' achieves this using the +precedent set by AT&T device-independent '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, 'groff''s 'lbp' device uses a 'unitwidth' of 800. Its +Times roman font 'TR' has a 'spacewidth' of 833; this is also the width +of its comma, period, centered period, and mathematical asterisk, while +its 'M' is 2,963 basic units. Thus, an 'M' on the 'lbp' device is 2,963 +basic units wide at a notional type size of 800 points.(1) (*note Font +Description File Format-Footnote-1::) + + A font description file has two sections. The first is a sequence of +directives, and is parsed similarly to the '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, and the same +comment syntax is supported. Empty lines are ignored throughout. + +'name F' + The name of the font is F. 'DESC' is an invalid font name. Simple + integers are valid, but their use is discouraged.(2) (*note Font + Description File Format-Footnote-2::) + +'spacewidth N' + The width of an unadjusted inter-word space is N basic units. + + The directives above must appear in the first section; those below +are optional. + +'slant N' + The font's glyphs have a slant of N degrees; a positive N slants in + the direction of text flow. + +'ligatures LIG1 ... LIGN [0]' + Glyphs LIG1, ..., LIGN are ligatures; possible ligatures are 'ff', + 'fi', 'fl', 'ffi' and 'ffl'. For compatibility with other 'troff' + implementations, the list of ligatures may be terminated with + a '0'. The list of ligatures must not extend over more than one + line. + +'special' + The font is "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. + + Other directives in this section are ignored by GNU '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 'charset' +subsection is mandatory unless the associated 'DESC' file contains the +'unicode' directive. Another subsection, 'kernpairs', is optional. + + The directive 'charset' starts the character set subsection.(3) +(*note Font Description File Format-Footnote-3::) 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. + + NAME METRICS TYPE CODE [ENTITY-NAME] ['--' COMMENT] + +NAME identifies the glyph: if NAME is a printable character C, it +corresponds to the 'troff' ordinary character C. If NAME is a +multi-character sequence not beginning with '\', it corresponds to the +GNU 'troff' special character escape sequence '\[NAME]'. A name +consisting of three minus signs, '---', is special and indicates that +the glyph is unnamed: such glyphs can be accessed only by the '\N' +escape sequence in 'troff'. A special character named '---' can still +be defined using 'char' and similar requests. The NAME '\-' defines the +minus sign glyph. Finally, NAME can be the unbreakable one-sixth and +one-twelfth space escape sequences, '\|' and '\^' ("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. + + The form of the METRICS field is as follows. + + WIDTH[','[HEIGHT[','[DEPTH[','[ITALIC-CORRECTION + [','[LEFT-ITALIC-CORRECTION[','[SUBSCRIPT-CORRECTION]]]]]]]]]] + +There must not be any spaces, tabs, or newlines between these +"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 '0'. Since there is no +associated binary format, these values are not required to fit into the +C language data type 'char' as they are in AT&T device-independent +'troff'. + + The WIDTH subfield gives the width of the glyph. The 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 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 +ITALIC-CORRECTION is the amount of space that should be added after an +oblique glyph to be followed immediately by an upright glyph. The +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 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 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 '\w' +escape sequence is interpolated, these values are bitwise or-ed together +for each glyph and stored in the 'nr' register. In font descriptions +for terminal devices, all glyphs might have a type of zero, regardless +of their appearance. + +'0' + means the glyph lies entirely between the baseline and a horizontal + line at the "x-height" of the font; typical examples are 'a', 'c', + and 'x'; + +'1' + means the glyph descends below the baseline, like 'p'; + +'2' + means the glyph ascends above the font's x-height, like 'A' or 'b'; + and + +'3' + means the glyph is both an ascender and a descender--this is true + of parentheses in some fonts. + + The CODE field gives a numeric identifier that the postprocessor uses +to render the glyph. The glyph can be specified to 'troff' using this +code by means of the '\N' escape sequence. CODE can be any integer.(4) +(*note Font Description File Format-Footnote-4::) + + The ENTITY-NAME field defines an identifier for the glyph that the +postprocessor uses to print the GNU 'troff' glyph NAME. This field is +optional; it was introduced so that the 'grohtml' output driver could +encode its character set. For example, the glyph '\[Po]' is represented +by '£' in HTML 4.0. For efficiency, these data are now compiled +directly into 'grohtml'. 'grops' uses the field to build sub-encoding +arrays for PostScript fonts containing more than 256 glyphs. Anything +on the line after the ENTITY-NAME field or '--' is ignored. + + A line in the 'charset' section can also have the form + + NAME " + +identifying NAME as another name for the glyph mentioned in the +preceding line. Such aliases can be chained. + + The directive '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. + + G1 G2 N + +The foregoing means that when glyph G1 is typeset immediately before G2, +the space between them should be increased by N. Most kerning pairs +should have a negative value for N. + + (1) 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. + + (2) 'groff' requests and escape sequences interpret non-negative font +names as mounting positions instead. Further, a font named '0' cannot +be automatically mounted by the 'fonts' directive of a 'DESC' file. + + (3) For typesetter devices, this directive is misnamed since it +starts a list of glyphs, not characters. + + (4) that is, any integer parsable by the C standard library's +'strtol(3)' function + +Appendix A Copying This Manual +****************************** + + Version 1.3, 3 November 2008 + + Copyright © 2000-2018 Free Software Foundation, Inc. + <http://fsf.org/> + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. We + recommend this License principally for works whose purpose is + instruction or reference. + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it can + be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + "Document", below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as "you". You accept + the license if you copy, modify or distribute the work in a way + requiring permission under copyright law. + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in the + notice that says that the Document is released under this License. + If a section does not fit the above definition of Secondary then it + is not allowed to be designated as Invariant. The Document may + contain zero Invariant Sections. If the Document does not identify + any Invariant Sections then there are none. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images composed + of pixels) generic paint programs or (for drawings) some widely + available drawing editor, and that is suitable for input to text + formatters or for automatic translation to a variety of formats + suitable for input to text formatters. A copy made in an otherwise + Transparent file format whose markup, or absence of markup, has + been arranged to thwart or discourage subsequent modification by + readers is not Transparent. An image format is not Transparent if + used for any substantial amount of text. A copy that is not + "Transparent" is called "Opaque". + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and standard-conforming + simple HTML, PostScript or PDF designed for human modification. + Examples of transparent image formats include PNG, XCF and JPG. + Opaque formats include proprietary formats that can be read and + edited only by proprietary word processors, SGML or XML for which + the DTD and/or processing tools are not generally available, and + the machine-generated HTML, PostScript or PDF produced by some word + processors for output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + The "publisher" means any person or entity that distributes copies + of the Document to the public. + + A section "Entitled XYZ" means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + "Acknowledgements", "Dedications", "Endorsements", or "History".) + To "Preserve the Title" of such a section when you modify the + Document means that it remains a section "Entitled XYZ" according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow the + conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the title + equally prominent and visible. You may add other material on the + covers in addition. Copying with changes limited to the covers, as + long as they preserve the title of the Document and satisfy these + conditions, can be treated as verbatim copying in other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a machine-readable + Transparent copy along with each Opaque copy, or state in or with + each Opaque copy a computer-network location from which the general + network-using public has access to download using public-standard + network protocols a complete Transparent copy of the Document, free + of added material. If you use the latter option, you must take + reasonably prudent steps, when you begin distribution of Opaque + copies in quantity, to ensure that this Transparent copy will + remain thus accessible at the stated location until at least one + year after the last time you distribute an Opaque copy (directly or + through your agents or retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of copies, + to give them a chance to provide you with an updated version of the + Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with the + Modified Version filling the role of the Document, thus licensing + distribution and modification of the Modified Version to whoever + possesses a copy of it. In addition, you must do these things in + the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of previous + versions (which should, if there were any, be listed in the + History section of the Document). You may use the same title + as a previous version if the original publisher of that + version gives permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in + the Modified Version, together with at least five of the + principal authors of the Document (all of its principal + authors, if it has fewer than five), unless they release you + from this requirement. + + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified + Version under the terms of this License, in the form shown in + the Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section Entitled "History", Preserve its Title, + and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on the + Title Page. If there is no section Entitled "History" in the + Document, create one stating the title, year, authors, and + publisher of the Document as given on its Title Page, then add + an item describing the Modified Version as stated in the + previous sentence. + + J. Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in the + "History" section. You may omit a network location for a work + that was published at least four years before the Document + itself, or if the original publisher of the version it refers + to gives permission. + + K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section + all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, unaltered + in their text and in their titles. Section numbers or the + equivalent are not considered part of the section titles. + + M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + + N. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option designate + some or all of these sections as invariant. To do this, add their + titles to the list of Invariant Sections in the Modified Version's + license notice. These titles must be distinct from any other + section titles. + + You may add a section Entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end of + the list of Cover Texts in the Modified Version. Only one passage + of Front-Cover Text and one of Back-Cover Text may be added by (or + through arrangements made by) any one entity. If the Document + already includes a cover text for the same cover, previously added + by you or by arrangement made by the same entity you are acting on + behalf of, you may not add another; but you may replace the old + one, on explicit permission from the previous publisher that added + the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination all + of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections Entitled + "History" in the various original documents, forming one section + Entitled "History"; likewise combine any sections Entitled + "Acknowledgements", and any sections Entitled "Dedications". You + must delete all sections Entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the documents + in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow this + License in all other respects regarding verbatim copying of that + document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of a + storage or distribution medium, is called an "aggregate" if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation's users beyond what the individual + works permit. When the Document is included in an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document's Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License, and all the license notices in the + Document, and any Warranty Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled "Acknowledgements", + "Dedications", or "History", the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided under this License. Any attempt + otherwise to copy, modify, sublicense, or distribute it is void, + and will automatically terminate your rights under this License. + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly and + finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from you + under this License. If your rights have been terminated and not + permanently reinstated, receipt of a copy of some or all of the + same material does not give you any rights to use it. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + <http://www.gnu.org/copyleft/>. + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If the + Document does not specify a version number of this License, you may + choose any version ever published (not as a draft) by the Free + Software Foundation. If the Document specifies that a proxy can + decide which future versions of this License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Document. + + 11. RELICENSING + + "Massive Multiauthor Collaboration Site" (or "MMC Site") means any + World Wide Web server that publishes copyrightable works and also + provides prominent facilities for anybody to edit those works. A + public wiki that anybody can edit is an example of such a server. + A "Massive Multiauthor Collaboration" (or "MMC") contained in the + site means any set of copyrightable works thus published on the MMC + site. + + "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 + license published by Creative Commons Corporation, a not-for-profit + corporation with a principal place of business in San Francisco, + California, as well as future copyleft versions of that license + published by that same organization. + + "Incorporate" means to publish or republish a Document, in whole or + in part, as part of another Document. + + An MMC is "eligible for relicensing" if it is licensed under this + License, and if all works that were first published under this + License somewhere other than this MMC, and subsequently + incorporated in whole or in part into the MMC, (1) had no cover + texts or invariant sections, and (2) were thus incorporated prior + to November 1, 2008. + + The operator of an MMC Site may republish an MMC contained in the + site under CC-BY-SA on the same site at any time before August 1, + 2009, provided the MMC is eligible for relicensing. + +ADDENDUM: How to use this License for your documents +==================================================== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + 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''. + + If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with + the Front-Cover Texts being LIST, and with the Back-Cover Texts + being LIST. + + If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of free +software license, such as the GNU General Public License, to permit +their use in free software. + +Appendix B Request Index +************************ + +Request names appear without a leading control character; the defaults +are '.' for the regular control character and ''' for the no-break +control character. + +* Menu: + +* ab: Debugging. (line 12127) +* ad: Manipulating Filling and Adjustment. + (line 5701) +* af: Assigning Register Formats. + (line 5419) +* aln: Setting Registers. (line 5323) +* als: Strings. (line 8972) +* am: Writing Macros. (line 9530) +* am1: Writing Macros. (line 9531) +* ami: Writing Macros. (line 9532) +* ami1: Writing Macros. (line 9533) +* as: Strings. (line 8888) +* as1: Strings. (line 8889) +* asciify: Diversions. (line 11120) +* backtrace: Debugging. (line 12176) +* bd: Artificial Fonts. (line 8211) +* blm: Blank Line Traps. (line 10779) +* box: Diversions. (line 10975) +* boxa: Diversions. (line 10976) +* bp: Page Control. (line 7175) +* br: Manipulating Filling and Adjustment. + (line 5657) +* break: while. (line 9393) +* brp: Manipulating Filling and Adjustment. + (line 5774) +* c2: Control Characters. + (line 4749) +* cc: Control Characters. + (line 4743) +* ce: Manipulating Filling and Adjustment. + (line 5826) +* cf: I/O. (line 11521) +* cflags: Using Symbols. (line 7846) +* ch: Page Location Traps. + (line 10528) +* char: Using Symbols. (line 7945) +* chop: Strings. (line 8919) +* class: Character Classes. (line 8034) +* close: I/O. (line 11703) +* color: Colors. (line 8687) +* composite: Using Symbols. (line 7802) +* continue: while. (line 9397) +* cp: Compatibility Mode. + (line 12414) +* cs: Artificial Fonts. (line 8241) +* cu: Artificial Fonts. (line 8202) +* da: Diversions. (line 10944) +* de: Writing Macros. (line 9418) +* de1: Writing Macros. (line 9490) +* defcolor: Colors. (line 8699) +* dei: Writing Macros. (line 9512) +* dei1: Writing Macros. (line 9513) +* device: Postprocessor Access. + (line 11738) +* devicem: Postprocessor Access. + (line 11768) +* di: Diversions. (line 10943) +* do: Compatibility Mode. + (line 12425) +* ds: ms Document Control Settings. + (line 1803) +* ds <1>: Strings. (line 8798) +* ds1: Strings. (line 8799) +* dt: Diversion Traps. (line 10668) +* ec: Using Escape Sequences. + (line 5012) +* ecr: Using Escape Sequences. + (line 5038) +* ecs: Using Escape Sequences. + (line 5037) +* el: if-else. (line 9213) +* em: End-of-input Traps. + (line 10807) +* eo: Using Escape Sequences. + (line 5007) +* ev: Environments. (line 11308) +* evc: Environments. (line 11362) +* ex: Debugging. (line 12132) +* fam: Font Families. (line 7463) +* fc: Fields. (line 6704) +* fchar: Using Symbols. (line 7946) +* fcolor: Colors. (line 8757) +* fi: Manipulating Filling and Adjustment. + (line 5684) +* fl: Debugging. (line 12167) +* fp: Font Positions. (line 7550) +* fschar: Using Symbols. (line 7947) +* fspecial: Special Fonts. (line 8104) +* ft: Selecting Fonts. (line 7348) +* ftr: Selecting Fonts. (line 7406) +* fzoom: Selecting Fonts. (line 7420) +* gcolor: Colors. (line 8729) +* hc: Manipulating Hyphenation. + (line 6023) +* hcode: Manipulating Hyphenation. + (line 6228) +* hla: Manipulating Hyphenation. + (line 6262) +* hlm: Manipulating Hyphenation. + (line 6275) +* hpf: Manipulating Hyphenation. + (line 6168) +* hpfa: Manipulating Hyphenation. + (line 6169) +* hpfcode: Manipulating Hyphenation. + (line 6170) +* hw: Manipulating Hyphenation. + (line 5957) +* hy: Manipulating Hyphenation. + (line 6055) +* hym: Manipulating Hyphenation. + (line 6289) +* hys: Manipulating Hyphenation. + (line 6304) +* ie: if-else. (line 9212) +* if: if-then. (line 9171) +* ig: Comments. (line 5180) +* in: Line Layout. (line 6935) +* it: Input Line Traps. (line 10679) +* itc: Input Line Traps. (line 10680) +* kern: Ligatures and Kerning. + (line 8288) +* lc: Leaders. (line 6661) +* length: Strings. (line 8909) +* lf: Debugging. (line 12103) +* lg: Ligatures and Kerning. + (line 8270) +* linetabs: Tabs and Fields. (line 6614) +* ll: Line Layout. (line 6987) +* ls: Manipulating Spacing. + (line 6395) +* lsm: Leading Space Traps. + (line 10789) +* lt: Page Layout. (line 7134) +* mc: Miscellaneous. (line 11897) +* mk: Page Motions. (line 9867) +* mso: I/O. (line 11512) +* msoquiet: I/O. (line 11513) +* na: Manipulating Filling and Adjustment. + (line 5768) +* ne: Page Control. (line 7195) +* nf: Manipulating Filling and Adjustment. + (line 5692) +* nh: Manipulating Hyphenation. + (line 6163) +* nm: Miscellaneous. (line 11796) +* nn: Miscellaneous. (line 11861) +* nop: if-then. (line 9190) +* nr: ms Document Control Settings. + (line 1799) +* nr <1>: Setting Registers. (line 5223) +* nr <2>: Setting Registers. (line 5277) +* nr <3>: Auto-increment. (line 5372) +* nroff: troff and nroff Modes. + (line 6840) +* ns: Manipulating Spacing. + (line 6454) +* nx: I/O. (line 11553) +* open: I/O. (line 11670) +* opena: I/O. (line 11671) +* os: Page Control. (line 7230) +* output: Diversions. (line 11107) +* pc: Page Layout. (line 7149) +* pev: Debugging. (line 12150) +* pi: I/O. (line 11612) +* pl: Page Layout. (line 7090) +* pm: Debugging. (line 12154) +* pn: Page Layout. (line 7104) +* pnr: Debugging. (line 12158) +* po: Line Layout. (line 6909) +* ps: Changing the Type Size. + (line 8462) +* psbb: Miscellaneous. (line 11945) +* pso: I/O. (line 11501) +* ptr: Debugging. (line 12162) +* pvs: Changing the Vertical Spacing. + (line 8581) +* rchar: Using Symbols. (line 8004) +* rd: I/O. (line 11558) +* return: Writing Macros. (line 9567) +* rfschar: Using Symbols. (line 8005) +* rj: Manipulating Filling and Adjustment. + (line 5865) +* rm: Strings. (line 8967) +* rn: Strings. (line 8964) +* rnn: Setting Registers. (line 5318) +* rr: Setting Registers. (line 5312) +* rs: Manipulating Spacing. + (line 6455) +* rt: Page Motions. (line 9868) +* schar: Using Symbols. (line 7948) +* shc: Manipulating Hyphenation. + (line 6032) +* shift: Parameters. (line 9610) +* sizes: Changing the Type Size. + (line 8526) +* so: I/O. (line 11472) +* soquiet: I/O. (line 11473) +* sp: Manipulating Spacing. + (line 6348) +* special: Special Fonts. (line 8103) +* spreadwarn: Debugging. (line 12207) +* ss: Manipulating Filling and Adjustment. + (line 5885) +* stringdown: Strings. (line 8944) +* stringup: Strings. (line 8945) +* sty: Font Families. (line 7504) +* substring: Strings. (line 8927) +* sv: Page Control. (line 7229) +* sy: I/O. (line 11634) +* ta: Tabs and Fields. (line 6488) +* tag: Postprocessor Access. + (line 11781) +* taga: Postprocessor Access. + (line 11782) +* tc: Tabs and Fields. (line 6602) +* ti: Line Layout. (line 6959) +* tkf: Ligatures and Kerning. + (line 8307) +* tl: Page Layout. (line 7120) +* tm: Debugging. (line 12115) +* tm1: Debugging. (line 12116) +* tmc: Debugging. (line 12117) +* tr: Character Translations. + (line 6729) +* trf: I/O. (line 11520) +* trin: Character Translations. + (line 6730) +* trnt: Character Translations. + (line 6795) +* troff: troff and nroff Modes. + (line 6832) +* uf: Artificial Fonts. (line 8206) +* ul: Artificial Fonts. (line 8180) +* unformat: Diversions. (line 11145) +* vpt: Vertical Position Traps. + (line 10406) +* vs: Changing the Vertical Spacing. + (line 8540) +* warn: Debugging. (line 12226) +* warnscale: Debugging. (line 12203) +* wh: Page Location Traps. + (line 10425) +* while: while. (line 9331) +* write: I/O. (line 11682) +* writec: I/O. (line 11683) +* writem: I/O. (line 11694) + +Appendix C Escape Sequence Index +******************************** + +The escape character, '\' by default, is always followed by at least one +more input character, making an escape _sequence_. Any input token '\X' +with X not in the list below emits a warning and interpolates glyph X. +Note the entries for '\.', which may be obscured by the leader dots, and +for '\<RET>' and '\<SP>', which are sorted alphabetically, not by code +point order. + +* Menu: + +* \: Using Escape Sequences. + (line 4944) +* \ <1>: Using Symbols. (line 7731) +* \!: Diversions. (line 11065) +* \": Comments. (line 5136) +* \#: Comments. (line 5170) +* \$: Parameters. (line 9602) +* \$*: Parameters. (line 9622) +* \$0: Parameters. (line 9657) +* \$@: Parameters. (line 9623) +* \$^: Parameters. (line 9624) +* \%: Manipulating Hyphenation. + (line 5991) +* \&: Dummy Characters. (line 8357) +* \': Using Symbols. (line 7831) +* \(: Using Symbols. (line 7733) +* \): Dummy Characters. (line 8407) +* \*: Strings. (line 8800) +* \,: Italic Corrections. + (line 8338) +* \-: Using Symbols. (line 7838) +* \.: Copy Mode. (line 9739) +* \/: Italic Corrections. + (line 8328) +* \0: Page Motions. (line 10014) +* \:: Manipulating Hyphenation. + (line 5992) +* \?: Diversions. (line 11066) +* \A: Identifiers. (line 4628) +* \a: Leaders. (line 6658) +* \B: Numeric Expressions. + (line 4522) +* \b: Drawing Geometric Objects. + (line 10308) +* \c: Line Continuation. (line 7047) +* \C: Using Symbols. (line 7793) +* \d: Page Motions. (line 9965) +* \D: Drawing Geometric Objects. + (line 10216) +* \e: Using Escape Sequences. + (line 5000) +* \E: Copy Mode. (line 9794) +* \f: Selecting Fonts. (line 7349) +* \F: Font Families. (line 7465) +* \g: Assigning Register Formats. + (line 5477) +* \H: Artificial Fonts. (line 8129) +* \h: Page Motions. (line 9982) +* \k: Page Motions. (line 10082) +* \l: Drawing Geometric Objects. + (line 10141) +* \L: Drawing Geometric Objects. + (line 10167) +* \m: Colors. (line 8730) +* \M: Colors. (line 8758) +* \n: Interpolating Registers. + (line 5338) +* \n <1>: Auto-increment. (line 5381) +* \N: Using Symbols. (line 7810) +* \newline: Line Continuation. (line 7019) +* \o: Page Motions. (line 10097) +* \O: Suppressing Output. + (line 11410) +* \p: Manipulating Filling and Adjustment. + (line 5775) +* \R: Setting Registers. (line 5224) +* \R <1>: Setting Registers. (line 5279) +* \r: Page Motions. (line 9963) +* \<RET>: Line Continuation. (line 7019) +* \S: Artificial Fonts. (line 8160) +* \s: Changing the Type Size. + (line 8465) +* \<SP>: Page Motions. (line 9998) +* \space: Page Motions. (line 9998) +* \t: Tabs and Fields. (line 6485) +* \u: Page Motions. (line 9964) +* \v: Page Motions. (line 9938) +* \V: I/O. (line 11719) +* \w: Page Motions. (line 10020) +* \x: Manipulating Spacing. + (line 6407) +* \X: Postprocessor Access. + (line 11739) +* \Y: Postprocessor Access. + (line 11769) +* \z: Page Motions. (line 10102) +* \Z: Page Motions. (line 10107) +* \[: Using Symbols. (line 7733) +* \\: Copy Mode. (line 9714) +* \^: Page Motions. (line 10009) +* \_: Using Symbols. (line 7841) +* \`: Using Symbols. (line 7835) +* \{: Conditional Blocks. + (line 9249) +* \{ <1>: Conditional Blocks. + (line 9250) +* \|: Page Motions. (line 10004) +* \}: Conditional Blocks. + (line 9250) +* \~: Manipulating Filling and Adjustment. + (line 5671) + +Appendix D Operator Index +************************* + +* Menu: + +* !: Numeric Expressions. + (line 4426) +* %: Numeric Expressions. + (line 4359) +* &: Numeric Expressions. + (line 4422) +* (: Numeric Expressions. + (line 4446) +* ): Numeric Expressions. + (line 4446) +* *: Numeric Expressions. + (line 4359) +* +: Numeric Expressions. + (line 4359) +* + <1>: Numeric Expressions. + (line 4365) +* + (unary): Numeric Expressions. + (line 4457) +* -: Numeric Expressions. + (line 4359) +* - <1>: Numeric Expressions. + (line 4365) +* - (unary): Numeric Expressions. + (line 4457) +* /: Numeric Expressions. + (line 4359) +* ;: Numeric Expressions. + (line 4390) +* <: Numeric Expressions. + (line 4416) +* <=: Numeric Expressions. + (line 4416) +* <?: Numeric Expressions. + (line 4407) +* <colon>: Numeric Expressions. + (line 4422) +* =: Numeric Expressions. + (line 4416) +* ==: Numeric Expressions. + (line 4416) +* >: Numeric Expressions. + (line 4416) +* >=: Numeric Expressions. + (line 4416) +* >?: Numeric Expressions. + (line 4407) +* |: Numeric Expressions. + (line 4471) + +Appendix E Register Index +************************* + +The macro package or program a specific register belongs to is appended +in brackets. + + A register name 'x' consisting of exactly one character can be +accessed as '\nx'. A register name 'xx' consisting of exactly two +characters can be accessed as '\n(xx'. Register names 'xxx' of any +length can be accessed as '\n[xxx]'. + +* Menu: + +* $$: Built-in Registers. + (line 5571) +* %: Page Layout. (line 7149) +* % <1>: Page Control. (line 7178) +* .$: Parameters. (line 9594) +* .A: Built-in Registers. + (line 5527) +* .a: Manipulating Spacing. + (line 6408) +* .b: Artificial Fonts. (line 8213) +* .br: Control Characters. + (line 4759) +* .c: Built-in Registers. + (line 5531) +* .C: Compatibility Mode. + (line 12415) +* .cdp: Environments. (line 11387) +* .ce: Manipulating Filling and Adjustment. + (line 5827) +* .cht: Environments. (line 11386) +* .color: Colors. (line 8688) +* .cp: Compatibility Mode. + (line 12426) +* .csk: Environments. (line 11388) +* .d: Diversions. (line 11000) +* .ev: Environments. (line 11309) +* .F: Built-in Registers. + (line 5536) +* .f: Font Positions. (line 7551) +* .fam: Font Families. (line 7464) +* .fn: Selecting Fonts. (line 7352) +* .fp: Font Positions. (line 7552) +* .g: Built-in Registers. + (line 5539) +* .H: Motion Quanta. (line 4300) +* .h: Diversions. (line 11007) +* .height: Artificial Fonts. (line 8132) +* .hla: Manipulating Hyphenation. + (line 6263) +* .hlc: Manipulating Hyphenation. + (line 6277) +* .hlm: Manipulating Hyphenation. + (line 6276) +* .hy: Manipulating Hyphenation. + (line 6056) +* .hym: Manipulating Hyphenation. + (line 6290) +* .hys: Manipulating Hyphenation. + (line 6305) +* .i: Line Layout. (line 6938) +* .in: Line Layout. (line 6962) +* .int: Line Continuation. (line 7048) +* .j: Manipulating Filling and Adjustment. + (line 5702) +* .k: Page Motions. (line 10093) +* .kern: Ligatures and Kerning. + (line 8289) +* .L: Manipulating Spacing. + (line 6396) +* .l: Line Layout. (line 6990) +* .lg: Ligatures and Kerning. + (line 8271) +* .linetabs: Tabs and Fields. (line 6615) +* .ll: Line Layout. (line 6991) +* .lt: Page Layout. (line 7137) +* .m: Colors. (line 8733) +* .M: Colors. (line 8761) +* .n: Environments. (line 11403) +* .ne: Page Location Traps. + (line 10579) +* .nm: Miscellaneous. (line 11798) +* .nn: Miscellaneous. (line 11862) +* .ns: Manipulating Spacing. + (line 6456) +* .o: Line Layout. (line 6912) +* .O: Suppressing Output. + (line 11463) +* .P: Built-in Registers. + (line 5543) +* .p: Page Layout. (line 7093) +* .pe: Page Location Traps. + (line 10598) +* .pn: Page Layout. (line 7107) +* .ps: Using Fractional Type Sizes. + (line 8622) +* .psr: Using Fractional Type Sizes. + (line 8637) +* .pvs: Changing the Vertical Spacing. + (line 8584) +* .R: Built-in Registers. + (line 5547) +* .rj: Manipulating Filling and Adjustment. + (line 5866) +* .s: Changing the Type Size. + (line 8466) +* .slant: Artificial Fonts. (line 8161) +* .sr: Using Fractional Type Sizes. + (line 8638) +* .ss: Manipulating Filling and Adjustment. + (line 5886) +* .sss: Manipulating Filling and Adjustment. + (line 5887) +* .sty: Font Families. (line 7505) +* .T: Built-in Registers. + (line 5551) +* .t: Page Location Traps. + (line 10520) +* .tabs: Tabs and Fields. (line 6489) +* .trunc: Page Location Traps. + (line 10587) +* .U: Built-in Registers. + (line 5555) +* .u: Manipulating Filling and Adjustment. + (line 5685) +* .V: Motion Quanta. (line 4301) +* .v: Changing the Vertical Spacing. + (line 8543) +* .vpt: Vertical Position Traps. + (line 10407) +* .w: Environments. (line 11385) +* .warn: Debugging. (line 12227) +* .x: Built-in Registers. + (line 5559) +* .y: Built-in Registers. + (line 5563) +* .Y: Built-in Registers. + (line 5567) +* .z: Diversions. (line 10999) +* .zoom: Selecting Fonts. (line 7421) +* c.: Built-in Registers. + (line 5532) +* ct: Page Motions. (line 10025) +* DD [ms]: ms Document Control Settings. + (line 2089) +* DI [ms]: ms Document Control Settings. + (line 2098) +* dl: Diversions. (line 11026) +* dn: Diversions. (line 11025) +* dw: Built-in Registers. + (line 5589) +* dy: Built-in Registers. + (line 5592) +* FF [ms]: ms Document Control Settings. + (line 2029) +* FI [ms]: ms Document Control Settings. + (line 2022) +* FM [ms]: ms Document Control Settings. + (line 1848) +* FPD [ms]: ms Document Control Settings. + (line 2070) +* FPS [ms]: ms Document Control Settings. + (line 2056) +* FVS [ms]: ms Document Control Settings. + (line 2063) +* GROWPS [ms]: ms Document Control Settings. + (line 1987) +* GS [ms]: Differences from AT&T ms. + (line 3360) +* HM [ms]: ms Document Control Settings. + (line 1841) +* HORPHANS [ms]: ms Document Control Settings. + (line 1998) +* hours: Built-in Registers. + (line 5586) +* hp: Page Motions. (line 10090) +* HY [ms]: ms Document Control Settings. + (line 1917) +* LL [ms]: ms Document Control Settings. + (line 1822) +* llx: Miscellaneous. (line 11946) +* lly: Miscellaneous. (line 11947) +* ln: Miscellaneous. (line 11797) +* lsn: Leading Space Traps. + (line 10790) +* lss: Leading Space Traps. + (line 10791) +* LT [ms]: ms Document Control Settings. + (line 1831) +* MINGW [ms]: ms Document Control Settings. + (line 2111) +* minutes: Built-in Registers. + (line 5583) +* mo: Built-in Registers. + (line 5595) +* nl: Page Control. (line 7240) +* opmaxx: Suppressing Output. + (line 11426) +* opmaxy: Suppressing Output. + (line 11426) +* opminx: Suppressing Output. + (line 11426) +* opminy: Suppressing Output. + (line 11426) +* PD [ms]: ms Document Control Settings. + (line 1946) +* PI [ms]: ms Document Control Settings. + (line 1938) +* PO [ms]: ms Document Control Settings. + (line 1813) +* PORPHANS [ms]: ms Document Control Settings. + (line 1961) +* PS [ms]: ms Document Control Settings. + (line 1903) +* PSINCR [ms]: ms Document Control Settings. + (line 1976) +* QI [ms]: ms Document Control Settings. + (line 1953) +* rsb: Page Motions. (line 10024) +* rst: Page Motions. (line 10023) +* sb: Page Motions. (line 10022) +* seconds: Built-in Registers. + (line 5580) +* skw: Page Motions. (line 10027) +* slimit: Debugging. (line 12197) +* ssc: Page Motions. (line 10026) +* st: Page Motions. (line 10021) +* systat: I/O. (line 11635) +* TC-MARGIN [ms]: ms Document Control Settings. + (line 2119) +* urx: Miscellaneous. (line 11948) +* ury: Miscellaneous. (line 11949) +* VS [ms]: ms Document Control Settings. + (line 1910) +* year: Built-in Registers. + (line 5598) +* yr: Built-in Registers. + (line 5601) + +Appendix F Macro Index +********************** + +The macro package a specific macro belongs to is appended in brackets. +They appear without the leading control character (normally '.'). + +* Menu: + +* 1C [ms]: ms Multiple Columns. + (line 3125) +* 2C [ms]: ms Multiple Columns. + (line 3128) +* [ [ms]: ms Insertions. (line 2876) +* ] [ms]: ms Insertions. (line 2877) +* AB [ms]: ms Document Description Macros. + (line 2187) +* AE [ms]: ms Document Description Macros. + (line 2194) +* AI [ms]: ms Document Description Macros. + (line 2170) +* AM [ms]: ms Legacy Features. (line 3443) +* AU [ms]: ms Document Description Macros. + (line 2164) +* B [ms]: Typeface and decoration. + (line 2485) +* B1 [ms]: ms keeps and displays. + (line 2774) +* B2 [ms]: ms keeps and displays. + (line 2775) +* BD [ms]: ms keeps and displays. + (line 2815) +* BI [ms]: Typeface and decoration. + (line 2498) +* BT [man]: Optional man extensions. + (line 1442) +* BX [ms]: Typeface and decoration. + (line 2506) +* CD [ms]: ms keeps and displays. + (line 2821) +* CT [man]: Optional man extensions. + (line 1457) +* CW [man]: Optional man extensions. + (line 1460) +* CW [ms]: Typeface and decoration. + (line 2502) +* DA [ms]: ms Document Description Macros. + (line 2177) +* De [man]: Optional man extensions. + (line 1467) +* DE [ms]: ms keeps and displays. + (line 2830) +* Ds [man]: Optional man extensions. + (line 1464) +* DS [ms]: ms keeps and displays. + (line 2805) +* DS [ms] <1>: ms keeps and displays. + (line 2809) +* DS [ms] <2>: ms keeps and displays. + (line 2814) +* DS [ms] <3>: ms keeps and displays. + (line 2820) +* DS [ms] <4>: ms keeps and displays. + (line 2825) +* EE [man]: Optional man extensions. + (line 1474) +* EF [ms]: ms Headers and Footers. + (line 3069) +* EH [ms]: ms Headers and Footers. + (line 3067) +* EN [ms]: ms Insertions. (line 2869) +* EQ [ms]: ms Insertions. (line 2868) +* EX [man]: Optional man extensions. + (line 1470) +* FE [ms]: ms Footnotes. (line 2935) +* FS [ms]: ms Footnotes. (line 2934) +* G [man]: Optional man extensions. + (line 1477) +* GL [man]: Optional man extensions. + (line 1482) +* HB [man]: Optional man extensions. + (line 1487) +* I [ms]: Typeface and decoration. + (line 2495) +* ID [ms]: ms keeps and displays. + (line 2810) +* IP [ms]: Paragraphs in ms. (line 2294) +* KE [ms]: ms keeps and displays. + (line 2762) +* KF [ms]: ms keeps and displays. + (line 2761) +* KS [ms]: ms keeps and displays. + (line 2760) +* LD [ms]: ms keeps and displays. + (line 2806) +* LG [ms]: Typeface and decoration. + (line 2516) +* LP [ms]: Paragraphs in ms. (line 2287) +* MC [ms]: ms Multiple Columns. + (line 3131) +* MS [man]: Optional man extensions. + (line 1495) +* ND [ms]: ms Document Description Macros. + (line 2182) +* NE [man]: Optional man extensions. + (line 1507) +* NH [ms]: Headings in ms. (line 2361) +* NL [ms]: Typeface and decoration. + (line 2528) +* NT [man]: Optional man extensions. + (line 1500) +* OF [ms]: ms Headers and Footers. + (line 3068) +* OH [ms]: ms Headers and Footers. + (line 3066) +* P1 [ms]: ms Headers and Footers. + (line 3078) +* PE [ms]: ms Insertions. (line 2861) +* PF [ms]: ms Insertions. (line 2862) +* PN [man]: Optional man extensions. + (line 1510) +* Pn [man]: Optional man extensions. + (line 1514) +* PP [ms]: Paragraphs in ms. (line 2290) +* PS [ms]: ms Insertions. (line 2860) +* PT [man]: Optional man extensions. + (line 1437) +* PX [ms]: ms TOC. (line 3181) +* QE [ms]: Paragraphs in ms. (line 2307) +* QP [ms]: Paragraphs in ms. (line 2302) +* QS [ms]: Paragraphs in ms. (line 2306) +* R [man]: Optional man extensions. + (line 1520) +* R [ms]: Typeface and decoration. + (line 2491) +* RD [ms]: ms keeps and displays. + (line 2826) +* RE [ms]: Indented regions in ms. + (line 2710) +* RN [man]: Optional man extensions. + (line 1523) +* RP [ms]: ms Document Description Macros. + (line 2145) +* RS [ms]: Indented regions in ms. + (line 2706) +* SH [ms]: Headings in ms. (line 2431) +* SM [ms]: Typeface and decoration. + (line 2522) +* TA [ms]: Tab Stops in ms. (line 3103) +* TB [man]: Optional man extensions. + (line 1492) +* TC [ms]: ms TOC. (line 3186) +* TE [ms]: ms Insertions. (line 2852) +* TL [ms]: ms Document Description Macros. + (line 2159) +* TS [ms]: ms Insertions. (line 2851) +* UL [ms]: Typeface and decoration. + (line 2512) +* VE [man]: Optional man extensions. + (line 1530) +* VS [man]: Optional man extensions. + (line 1526) +* XA [ms]: ms TOC. (line 3170) +* XE [ms]: ms TOC. (line 3171) +* XH [ms]: ms TOC. (line 3222) +* XH-REPLACEMENT [ms]: ms TOC. (line 3231) +* XH-UPDATE-TOC [ms]: ms TOC. (line 3236) +* XN [ms]: ms TOC. (line 3221) +* XN-INIT [ms]: ms TOC. (line 3235) +* XN-REPLACEMENT [ms]: ms TOC. (line 3230) +* XP [ms]: Paragraphs in ms. (line 2313) +* XS [ms]: ms TOC. (line 3169) + +Appendix G String Index +*********************** + +The macro package or program a that defines or uses each string is +appended in brackets. (Only one string, '.T', is defined by the 'troff' +formatter itself.) *Note Strings::. + +* Menu: + +* ! [ms]: ms Legacy Features. (line 3482) +* ' [ms]: ms Legacy Features. (line 3415) +* ' [ms] <1>: ms Legacy Features. (line 3446) +* * [ms]: ms Footnotes. (line 2925) +* , [ms]: ms Legacy Features. (line 3433) +* , [ms] <1>: ms Legacy Features. (line 3461) +* - [ms]: Typographical symbols in ms. + (line 2266) +* . [ms]: ms Legacy Features. (line 3473) +* .T: Strings. (line 8787) +* .T <1>: Strings. (line 8787) +* / [ms]: ms Legacy Features. (line 3464) +* 3 [ms]: ms Legacy Features. (line 3491) +* 8 [ms]: ms Legacy Features. (line 3485) +* : [ms]: ms Legacy Features. (line 3421) +* : [ms] <1>: ms Legacy Features. (line 3452) +* < [ms]: Typeface and decoration. + (line 2562) +* > [ms]: Typeface and decoration. + (line 2563) +* ? [ms]: ms Legacy Features. (line 3479) +* ^ [ms]: ms Legacy Features. (line 3424) +* ^ [ms] <1>: ms Legacy Features. (line 3455) +* _ [ms]: ms Legacy Features. (line 3470) +* ` [ms]: ms Legacy Features. (line 3418) +* ` [ms] <1>: ms Legacy Features. (line 3449) +* { [ms]: Typeface and decoration. + (line 2558) +* } [ms]: Typeface and decoration. + (line 2559) +* ~ [ms]: ms Legacy Features. (line 3427) +* ~ [ms] <1>: ms Legacy Features. (line 3458) +* ABSTRACT [ms]: ms language and localization. + (line 3019) +* ae [ms]: ms Legacy Features. (line 3506) +* Ae [ms]: ms Legacy Features. (line 3509) +* C [ms]: ms Legacy Features. (line 3430) +* CF [ms]: ms Document Control Settings. + (line 1886) +* CH [ms]: ms Document Control Settings. + (line 1865) +* d- [ms]: ms Legacy Features. (line 3494) +* D- [ms]: ms Legacy Features. (line 3497) +* FAM [ms]: ms Document Control Settings. + (line 1926) +* FR [ms]: ms Document Control Settings. + (line 2077) +* LF [ms]: ms Document Control Settings. + (line 1879) +* LH [ms]: ms Document Control Settings. + (line 1858) +* MONTH1 [ms]: ms language and localization. + (line 3028) +* MONTH10 [ms]: ms language and localization. + (line 3037) +* MONTH11 [ms]: ms language and localization. + (line 3038) +* MONTH12 [ms]: ms language and localization. + (line 3039) +* MONTH2 [ms]: ms language and localization. + (line 3029) +* MONTH3 [ms]: ms language and localization. + (line 3030) +* MONTH4 [ms]: ms language and localization. + (line 3031) +* MONTH5 [ms]: ms language and localization. + (line 3032) +* MONTH6 [ms]: ms language and localization. + (line 3033) +* MONTH7 [ms]: ms language and localization. + (line 3034) +* MONTH8 [ms]: ms language and localization. + (line 3035) +* MONTH9 [ms]: ms language and localization. + (line 3036) +* o [ms]: ms Legacy Features. (line 3476) +* oe [ms]: ms Legacy Features. (line 3512) +* OE [ms]: ms Legacy Features. (line 3515) +* Q [ms]: Typographical symbols in ms. + (line 2269) +* q [ms]: ms Legacy Features. (line 3488) +* REFERENCES [ms]: ms language and localization. + (line 3014) +* RF [ms]: ms Document Control Settings. + (line 1893) +* RH [ms]: ms Document Control Settings. + (line 1872) +* SN [ms]: Headings in ms. (line 2410) +* SN-DOT [ms]: Headings in ms. (line 2408) +* SN-NO-DOT [ms]: Headings in ms. (line 2409) +* SN-STYLE [ms]: ms Document Control Settings. + (line 2011) +* SN-STYLE [ms] <1>: Headings in ms. (line 2407) +* th [ms]: ms Legacy Features. (line 3500) +* Th [ms]: ms Legacy Features. (line 3503) +* TOC [ms]: ms language and localization. + (line 3024) +* U [ms]: Typographical symbols in ms. + (line 2270) +* v [ms]: ms Legacy Features. (line 3467) + +Appendix H File Keyword Index +***************************** + +* Menu: + +* #: DESC File Format. (line 13432) +* # <1>: Font Description File Format. + (line 13592) +* ---: Font Description File Format. + (line 13639) +* biggestfont: DESC File Format. (line 13562) +* charset: DESC File Format. (line 13557) +* charset <1>: Font Description File Format. + (line 13631) +* family: Selecting Fonts. (line 7352) +* family <1>: DESC File Format. (line 13436) +* fonts: Using Symbols. (line 7612) +* fonts <1>: Special Fonts. (line 8104) +* fonts <2>: DESC File Format. (line 13439) +* hor: DESC File Format. (line 13445) +* image_generator: DESC File Format. (line 13449) +* kernpairs: Font Description File Format. + (line 13727) +* ligatures: Font Description File Format. + (line 13611) +* name: Font Description File Format. + (line 13596) +* paperlength: DESC File Format. (line 13455) +* papersize: DESC File Format. (line 13459) +* paperwidth: DESC File Format. (line 13486) +* pass_filenames: DESC File Format. (line 13490) +* postpro: DESC File Format. (line 13495) +* prepro: DESC File Format. (line 13498) +* print: DESC File Format. (line 13502) +* res: DESC File Format. (line 13506) +* sizes: DESC File Format. (line 13509) +* sizescale: DESC File Format. (line 13514) +* slant: Font Description File Format. + (line 13607) +* spacewidth: Font Description File Format. + (line 13601) +* spare1: DESC File Format. (line 13562) +* spare2: DESC File Format. (line 13562) +* special: Artificial Fonts. (line 8230) +* special <1>: Font Description File Format. + (line 13618) +* styles: Selecting Fonts. (line 7352) +* styles <1>: Font Families. (line 7511) +* styles <2>: DESC File Format. (line 13518) +* tcommand: DESC File Format. (line 13522) +* unicode: DESC File Format. (line 13526) +* unitwidth: DESC File Format. (line 13540) +* unscaled_charwidths: DESC File Format. (line 13544) +* use_charnames_in_special: Postprocessor Access. + (line 11760) +* use_charnames_in_special <1>: DESC File Format. (line 13548) +* vert: DESC File Format. (line 13553) + +Appendix I Program and File Index +********************************* + +* Menu: + +* an.tmac: man. (line 1417) +* changebar: Miscellaneous. (line 11940) +* composite.tmac: Using Symbols. (line 7802) +* cp1047.tmac: Input Encodings. (line 3986) +* cs.tmac: Manipulating Hyphenation. + (line 6215) +* de.tmac: Manipulating Hyphenation. + (line 6215) +* DESC: Selecting Fonts. (line 7352) +* DESC <1>: Font Families. (line 7511) +* DESC <2>: Using Symbols. (line 7612) +* DESC <3>: Using Symbols. (line 7820) +* DESC <4>: Special Fonts. (line 8104) +* diffmk: Miscellaneous. (line 11940) +* ec.tmac: Input Encodings. (line 4027) +* en.tmac: Manipulating Hyphenation. + (line 6215) +* eqn: ms Insertions. (line 2845) +* fr.tmac: Manipulating Hyphenation. + (line 6215) +* freeeuro.pfa: Input Encodings. (line 4027) +* gchem: Groff Options. (line 478) +* gdiffmk: Miscellaneous. (line 11940) +* geqn: Groff Options. (line 478) +* ggrn: Groff Options. (line 478) +* gpic: Groff Options. (line 478) +* grap: Groff Options. (line 478) +* grefer: Groff Options. (line 478) +* groff: Groff Options. (line 478) +* gsoelim: Groff Options. (line 478) +* gtbl: Groff Options. (line 478) +* gtroff: Groff Options. (line 478) +* it.tmac: Manipulating Hyphenation. + (line 6215) +* ja.tmac: Manipulating Hyphenation. + (line 6215) +* latin1.tmac: Input Encodings. (line 3991) +* latin2.tmac: Input Encodings. (line 4004) +* latin5.tmac: Input Encodings. (line 4010) +* latin9.tmac: Input Encodings. (line 4015) +* makeindex: Indexing. (line 1340) +* man.local: Optional man extensions. + (line 1427) +* man.tmac: man. (line 1417) +* man.ultrix: Optional man extensions. + (line 1451) +* nrchbar: Miscellaneous. (line 11940) +* papersize.tmac: Paper Format. (line 975) +* perl: I/O. (line 11645) +* pic: ms Insertions. (line 2845) +* post-grohtml: Groff Options. (line 766) +* pre-grohtml: Groff Options. (line 766) +* preconv: Groff Options. (line 478) +* refer: ms Insertions. (line 2845) +* soelim: Debugging. (line 12103) +* sv.tmac: Manipulating Hyphenation. + (line 6215) +* tbl: ms Insertions. (line 2845) +* trace.tmac: Writing Macros. (line 9551) +* troffrc: Groff Options. (line 699) +* troffrc <1>: Paper Format. (line 975) +* troffrc <2>: Manipulating Hyphenation. + (line 6215) +* troffrc <3>: Manipulating Hyphenation. + (line 6263) +* troffrc <4>: troff and nroff Modes. + (line 6832) +* troffrc-end: Groff Options. (line 699) +* troffrc-end <1>: Manipulating Hyphenation. + (line 6263) +* troffrc-end <2>: troff and nroff Modes. + (line 6832) +* tty.tmac: troff and nroff Modes. + (line 6840) +* tty.tmac <1>: Line Layout. (line 6912) +* vtroff: Operators in Conditionals. + (line 9070) +* zh.tmac: Manipulating Hyphenation. + (line 6215) + +Appendix J Concept Index +************************ + +* Menu: + +* ", as delimiter: Delimiters. (line 5060) +* ", at end of sentence: Sentences. (line 3663) +* ", at end of sentence <1>: Using Symbols. (line 7892) +* ", embedding in a macro argument: Calling Macros. (line 4875) +* %, as delimiter: Delimiters. (line 5092) +* &, as delimiter: Delimiters. (line 5092) +* ', as a comment: Comments. (line 5164) +* ', as delimiter: Delimiters. (line 5060) +* ', at end of sentence: Sentences. (line 3663) +* ', at end of sentence <1>: Using Symbols. (line 7892) +* (, as delimiter: Delimiters. (line 5092) +* ), as delimiter: Delimiters. (line 5092) +* ), at end of sentence: Sentences. (line 3663) +* ), at end of sentence <1>: Using Symbols. (line 7892) +* *, as delimiter: Delimiters. (line 5092) +* *, at end of sentence: Sentences. (line 3663) +* *, at end of sentence <1>: Using Symbols. (line 7892) +* +, and page motion: Numeric Expressions. + (line 4457) +* +, as delimiter: Delimiters. (line 5092) +* -, and page motion: Numeric Expressions. + (line 4457) +* -, as delimiter: Delimiters. (line 5092) +* ., as delimiter: Delimiters. (line 5090) +* .h register, difference from nl: Diversions. (line 11020) +* .ps register, in comparison with .psr: Using Fractional Type Sizes. + (line 8638) +* .s register, in comparison with .sr: Using Fractional Type Sizes. + (line 8638) +* .S register, Plan 9 alias for .tabs: Tabs and Fields. (line 6593) +* .t register, and diversions: Diversion Traps. (line 10668) +* .tabs register, Plan 9 alias (.S): Tabs and Fields. (line 6593) +* .V register, and vs: Changing the Vertical Spacing. + (line 8546) +* /, as delimiter: Delimiters. (line 5092) +* 8-bit input: Font Description File Format. + (line 13639) +* <, as delimiter: Delimiters. (line 5092) +* <colon>, as delimiter: Delimiters. (line 5092) +* =, as delimiter: Delimiters. (line 5092) +* >, as delimiter: Delimiters. (line 5092) +* [, macro names starting with, and refer: Identifiers. (line 4623) +* \!, and copy mode: Diversions. (line 11074) +* \!, and output request: Diversions. (line 11106) +* \!, and trnt: Character Translations. + (line 6795) +* \!, as delimiter: Delimiters. (line 5069) +* \!, as delimiter <1>: Delimiters. (line 5096) +* \!, in top-level diversion: Diversions. (line 11098) +* \!, incompatibilities with AT&T troff: Other Differences. (line 12546) +* \!, incompatibilities with AT&T troff <1>: Other Differences. + (line 12636) +* \$, when reading text for a macro: Copy Mode. (line 9699) +* \%, and translations: Character Translations. + (line 6747) +* \%, as delimiter: Delimiters. (line 5069) +* \%, as delimiter <1>: Delimiters. (line 5096) +* \%, following \X or \Y: Manipulating Hyphenation. + (line 6001) +* \%, in \X: Postprocessor Access. + (line 11746) +* \%, incompatibilities with AT&T troff: Other Differences. (line 12546) +* \&, and glyph definitions: Using Symbols. (line 7948) +* \&, and translations: Character Translations. + (line 6758) +* \&, as delimiter: Delimiters. (line 5069) +* \&, at end of sentence: Sentences. (line 3647) +* \&, in \X: Postprocessor Access. + (line 11746) +* \&, incompatibilities with AT&T troff: Other Differences. (line 12546) +* \', and translations: Character Translations. + (line 6741) +* \', as delimiter: Delimiters. (line 5069) +* \', as delimiter <1>: Delimiters. (line 5096) +* \', incompatibilities with AT&T troff: Other Differences. (line 12546) +* \(, and translations: Character Translations. + (line 6741) +* \), as delimiter: Delimiters. (line 5069) +* \), in \X: Postprocessor Access. + (line 11746) +* \*, and warnings: Warnings. (line 12301) +* \*, incompatibilities with AT&T troff: Compatibility Mode. + (line 12404) +* \*, when reading text for a macro: Copy Mode. (line 9699) +* \, disabling (eo): Using Escape Sequences. + (line 5007) +* \, embedding in a macro argument: Calling Macros. (line 4875) +* \,, as delimiter: Delimiters. (line 5069) +* \- glyph, and cflags: Using Symbols. (line 7875) +* \-, and translations: Character Translations. + (line 6741) +* \-, as delimiter: Delimiters. (line 5069) +* \-, as delimiter <1>: Delimiters. (line 5096) +* \-, incompatibilities with AT&T troff: Other Differences. (line 12546) +* \/, as delimiter: Delimiters. (line 5069) +* \/, as delimiter <1>: Delimiters. (line 5096) +* \0, as delimiter: Delimiters. (line 5069) +* \:, as delimiter: Delimiters. (line 5069) +* \:, as delimiter <1>: Delimiters. (line 5096) +* \<colon>, in \X: Postprocessor Access. + (line 11746) +* \?, and copy mode: Operators in Conditionals. + (line 9116) +* \?, and copy mode <1>: Diversions. (line 11074) +* \?, as delimiter: Delimiters. (line 5069) +* \?, in top-level diversion: Diversions. (line 11103) +* \?, incompatibilities with AT&T troff: Other Differences. (line 12636) +* \a, and copy mode: Leaders. (line 6658) +* \a, and translations: Character Translations. + (line 6751) +* \a, as delimiter: Delimiters. (line 5069) +* \A, delimiters allowed by: Delimiters. (line 5076) +* \A, incompatibilities with AT&T troff: Other Differences. (line 12546) +* \b, delimiters allowed by: Delimiters. (line 5076) +* \b, limitations of: Drawing Geometric Objects. + (line 10316) +* \C, and translations: Character Translations. + (line 6741) +* \c, as delimiter: Delimiters. (line 5069) +* \c, as delimiter <1>: Delimiters. (line 5096) +* \c, incompatibilities with AT&T troff: Other Differences. (line 12546) +* \c, when filling disabled: Line Continuation. (line 7062) +* \c, when filling enabled: Line Continuation. (line 7054) +* \d, as delimiter: Delimiters. (line 5069) +* \D, delimiters allowed by: Delimiters. (line 5087) +* \e, and glyph definitions: Using Symbols. (line 7948) +* \e, and translations: Character Translations. + (line 6745) +* \e, as delimiter: Delimiters. (line 5069) +* \E, as delimiter: Delimiters. (line 5069) +* \e, as delimiter <1>: Delimiters. (line 5096) +* \e, incompatibilities with AT&T troff: Other Differences. (line 12636) +* \F, and changing fonts: Selecting Fonts. (line 7352) +* \f, and font translations: Selecting Fonts. (line 7406) +* \f, incompatibilities with AT&T troff: Compatibility Mode. + (line 12506) +* \h, delimiters allowed by: Delimiters. (line 5087) +* \H, delimiters allowed by: Delimiters. (line 5087) +* \H, incompatibilities with AT&T troff: Compatibility Mode. + (line 12506) +* \H, using + and - with: Numeric Expressions. + (line 4463) +* \H, with fractional type sizes: Using Fractional Type Sizes. + (line 8604) +* \l, and glyph definitions: Using Symbols. (line 7948) +* \L, and glyph definitions: Using Symbols. (line 7948) +* \l, delimiters allowed by: Delimiters. (line 5087) +* \L, delimiters allowed by: Delimiters. (line 5087) +* \N, and translations: Character Translations. + (line 6741) +* \n, and warnings: Warnings. (line 12313) +* \N, delimiters allowed by: Delimiters. (line 5087) +* \n, incompatibilities with AT&T troff: Compatibility Mode. + (line 12404) +* \n, when reading text for a macro: Copy Mode. (line 9699) +* \o, delimiters allowed by: Delimiters. (line 5076) +* \p, as delimiter: Delimiters. (line 5069) +* \p, as delimiter <1>: Delimiters. (line 5096) +* \R, after \c: Line Continuation. (line 7048) +* \R, and warnings: Warnings. (line 12313) +* \r, as delimiter: Delimiters. (line 5069) +* \R, delimiters allowed by: Delimiters. (line 5087) +* \R, difference from nr: Auto-increment. (line 5372) +* \R, using + and - with: Numeric Expressions. + (line 4463) +* \<RET>, when reading text for a macro: Copy Mode. (line 9699) +* \s, delimiters allowed by: Delimiters. (line 5087) +* \S, delimiters allowed by: Delimiters. (line 5087) +* \s, incompatibilities with AT&T troff: Compatibility Mode. + (line 12506) +* \S, incompatibilities with AT&T troff: Compatibility Mode. + (line 12506) +* \s, incompatibilities with AT&T troff <1>: Compatibility Mode. + (line 12519) +* \s, using + and - with: Numeric Expressions. + (line 4463) +* \s, with fractional type sizes: Using Fractional Type Sizes. + (line 8604) +* \<SP>, as delimiter: Delimiters. (line 5069) +* \<SP>, difference from \~: Calling Macros. (line 4867) +* \<SP>, incompatibilities with AT&T troff: Other Differences. + (line 12546) +* \t, and copy mode: Tabs and Fields. (line 6485) +* \t, and translations: Character Translations. + (line 6751) +* \t, and warnings: Warnings. (line 12319) +* \t, as delimiter: Delimiters. (line 5069) +* \u, as delimiter: Delimiters. (line 5069) +* \V, and copy mode: I/O. (line 11721) +* \v, delimiters allowed by: Delimiters. (line 5087) +* \v, internal representation: Gtroff Internals. (line 12017) +* \w, delimiters allowed by: Delimiters. (line 5076) +* \X, and special characters: Postprocessor Access. + (line 11760) +* \X, delimiters allowed by: Delimiters. (line 5076) +* \x, delimiters allowed by: Delimiters. (line 5087) +* \X, followed by \%: Manipulating Hyphenation. + (line 6001) +* \Y, followed by \%: Manipulating Hyphenation. + (line 6001) +* \Z, delimiters allowed by: Delimiters. (line 5076) +* \[, and translations: Character Translations. + (line 6741) +* \\, when reading text for a macro: Copy Mode. (line 9738) +* \^, as delimiter: Delimiters. (line 5069) +* \^, incompatibilities with AT&T troff: Other Differences. (line 12546) +* \_, and translations: Character Translations. + (line 6741) +* \_, as delimiter: Delimiters. (line 5069) +* \_, as delimiter <1>: Delimiters. (line 5096) +* \_, incompatibilities with AT&T troff: Other Differences. (line 12546) +* \`, and translations: Character Translations. + (line 6741) +* \`, as delimiter: Delimiters. (line 5069) +* \`, as delimiter <1>: Delimiters. (line 5096) +* \`, incompatibilities with AT&T troff: Other Differences. (line 12546) +* \{, as delimiter: Delimiters. (line 5069) +* \{, as delimiter <1>: Delimiters. (line 5096) +* \{, incompatibilities with AT&T troff: Other Differences. (line 12546) +* \|, as delimiter: Delimiters. (line 5069) +* \|, incompatibilities with AT&T troff: Other Differences. (line 12546) +* \}, and warnings: Warnings. (line 12324) +* \}, as delimiter: Delimiters. (line 5069) +* \}, as delimiter <1>: Delimiters. (line 5096) +* \}, incompatibilities with AT&T troff: Other Differences. (line 12546) +* \~, and translations: Character Translations. + (line 6747) +* \~, as delimiter: Delimiters. (line 5069) +* \~, difference from \<SP>: Calling Macros. (line 4867) +* \~, incompatibilities with AT&T troff: Other Differences. (line 12539) +* ], as part of an identifier: Identifiers. (line 4616) +* ], at end of sentence: Sentences. (line 3663) +* ], at end of sentence <1>: Using Symbols. (line 7892) +* ], macro names starting with, and refer: Identifiers. (line 4623) +* |, and page motion: Numeric Expressions. + (line 4471) +* ab request, incompatibilities with AT&T troff: Other Differences. + (line 12592) +* aborting (ab): Debugging. (line 12127) +* absolute (sic) position operator (|): Numeric Expressions. + (line 4471) +* abstract font style: Using Fonts. (line 7302) +* abstract font style, setting up (sty): Font Families. (line 7505) +* accent marks [ms]: ms Legacy Features. + (line 3405) +* access to postprocessor: Postprocessor Access. + (line 11729) +* accessing unnamed glyphs with \N: Font Description File Format. + (line 13639) +* activating kerning (kern): Ligatures and Kerning. + (line 8289) +* activating ligatures (lg): Ligatures and Kerning. + (line 8271) +* activating track kerning (tkf): Ligatures and Kerning. + (line 8307) +* ad request, and hyphenation margin: Manipulating Hyphenation. + (line 6290) +* ad request, and hyphenation space: Manipulating Hyphenation. + (line 6305) +* addition: Numeric Expressions. + (line 4359) +* additional inter-sentence space: Manipulating Filling and Adjustment. + (line 5893) +* adjustment and filling, manipulating: Manipulating Filling and Adjustment. + (line 5624) +* adjustment mode register (.j): Manipulating Filling and Adjustment. + (line 5731) +* adjustment to both margins, difference from AT&T troff: Other Differences. + (line 12552) +* Adobe Glyph List (AGL): Using Symbols. (line 7688) +* alias, diversion, creating (als): Strings. (line 8972) +* alias, diversion, removing (rm): Strings. (line 9007) +* alias, macro, creating (als): Strings. (line 8972) +* alias, macro, removing (rm): Strings. (line 9007) +* alias, register, creating (aln): Setting Registers. (line 5323) +* alias, register, removing (rr): Setting Registers. (line 5329) +* alias, string, creating (als): Strings. (line 8972) +* alias, string, removing (rm): Strings. (line 9007) +* aliasing fonts with third argument to fp request: Font Positions. + (line 7561) +* als request, and \$0: Parameters. (line 9657) +* am, am1, ami requests, and warnings: Warnings. (line 12301) +* appending to a diversion (da, boxa): Diversions. (line 10944) +* appending to a file (opena): I/O. (line 11671) +* appending to a macro (am): Writing Macros. (line 9533) +* appending to a string (as): Strings. (line 8889) +* approximation output register (.A): Built-in Registers. + (line 5527) +* arc, drawing (\D'a ...'): Drawing Geometric Objects. + (line 10225) +* argument: Requests and Macros. + (line 3829) +* arguments to macros: Calling Macros. (line 4851) +* arguments to macros, and tabs: Invoking Requests. (line 4789) +* arguments to requests: Invoking Requests. (line 4789) +* arguments to requests, and tabs: Invoking Requests. (line 4789) +* arguments, and compatibility mode: Gtroff Internals. (line 12054) +* arguments, to escape sequences, delimiting: Delimiters. (line 5060) +* arguments, to strings: Strings. (line 8802) +* arithmetic operators: Numeric Expressions. + (line 4359) +* artificial fonts: Artificial Fonts. (line 8122) +* as, as1 requests, and comments: Comments. (line 5139) +* as, as1 requests, and warnings: Warnings. (line 12301) +* ASCII output encoding: Groff Options. (line 743) +* asciify request, and writem: I/O. (line 11694) +* assertion (arithmetic operator): Numeric Expressions. + (line 4365) +* assign number format to register (af): Assigning Register Formats. + (line 5413) +* assignments, indirect: Interpolating Registers. + (line 5340) +* assignments, nested: Interpolating Registers. + (line 5340) +* AT&T ms, macro package differences: Differences from AT&T ms. + (line 3276) +* attributes, character cell: Using Fonts. (line 7323) +* auto-incrementation of a register: Auto-increment. (line 5364) +* automatic font mounting: Selecting Fonts. (line 7365) +* automatic hyphenation: Manipulating Hyphenation. + (line 5941) +* automatic hyphenation parameters: Manipulating Hyphenation. + (line 6042) +* auxiliary macro package: Major Macro Packages. + (line 1408) +* available glyphs, list of (groff_char(7) man page): Using Symbols. + (line 7675) +* background: Background. (line 229) +* background color name register (.M): Colors. (line 8765) +* backslash glyph, formatting (\[rs]): Using Escape Sequences. + (line 5002) +* backslash, embedding in a macro argument: Calling Macros. (line 4875) +* backslash, printing (\\, \e, \E, \[rs]): Other Differences. + (line 12636) +* backspace character, and translations: Character Translations. + (line 6751) +* backtrace of input stack (backtrace): Debugging. (line 12176) +* baseline rule special character(\[ru]): Drawing Geometric Objects. + (line 10146) +* baseline, text: Page Geometry. (line 4184) +* baseline, text <1>: Manipulating Type Size and Vertical Spacing. + (line 8438) +* basic scaling unit (u): Measurements. (line 4245) +* basic units: Page Geometry. (line 4169) +* basic units, conversion to: Measurements. (line 4239) +* basics of macro package usage: Basics. (line 1058) +* bd request, and font styles: Font Families. (line 7505) +* bd request, and font translations: Selecting Fonts. (line 7406) +* bd request, incompatibilities with AT&T troff: Other Differences. + (line 12609) +* beginning diversion (di, box): Diversions. (line 10944) +* beginning of conditional block (\{): Conditional Blocks. + (line 9250) +* blank line: Breaking. (line 3749) +* blank line macro (blm): Breaking. (line 3749) +* blank line macro (blm) <1>: Invoking Requests. (line 4820) +* blank line macro (blm) <2>: Blank Line Traps. (line 10779) +* blank line trap (blm): Invoking Requests. (line 4820) +* blank line traps: Blank Line Traps. (line 10778) +* blank lines, disabling: Manipulating Spacing. + (line 6456) +* block, conditional, beginning (\{): Conditional Blocks. + (line 9250) +* block, conditional, end (\}): Conditional Blocks. + (line 9250) +* blocks, conditional: Conditional Blocks. + (line 9243) +* body, of a while request: while. (line 9330) +* boldface, imitating (bd): Artificial Fonts. (line 8213) +* bottom margin: Page Location Traps. + (line 10440) +* boundary-relative motion operator (|): Numeric Expressions. + (line 4471) +* bounding box: Miscellaneous. (line 11949) +* box (diversion operation): Diversions. (line 10971) +* box request, and warnings: Warnings. (line 12296) +* box rule glyph (\[br]): Drawing Geometric Objects. + (line 10168) +* box, boxa requests, and warnings: Warnings. (line 12301) +* boxa request, and dn (dl): Diversions. (line 11026) +* boxa request, and warnings: Warnings. (line 12296) +* boxes [ms]: ms keeps and displays. + (line 2771) +* bp request, and top-level diversion: Page Control. (line 7183) +* bp request, and traps (.pe): Page Location Traps. + (line 10598) +* bp request, causing implicit break: Manipulating Filling and Adjustment. + (line 5624) +* bp request, incompatibilities with AT&T troff: Other Differences. + (line 12596) +* bp request, using + and - with: Numeric Expressions. + (line 4463) +* br glyph, and cflags: Using Symbols. (line 7887) +* brace escape sequence, closing (\}): Conditional Blocks. + (line 9250) +* brace escape sequence, opening (\}): Conditional Blocks. + (line 9250) +* brace escape sequences (\{, \}): Conditional Blocks. + (line 9250) +* break: Breaking. (line 3725) +* break <1>: Manipulating Filling and Adjustment. + (line 5624) +* break (introduction): Basics. (line 1188) +* break request, in a while loop: while. (line 9393) +* break, page: Page Geometry. (line 4208) +* break, page <1>: Page Control. (line 7170) +* break, page <2>: The Implicit Page Trap. + (line 10638) +* break, page (introduction): Basics. (line 1185) +* break, page, final: End-of-input Traps. + (line 10834) +* break, page, prevented by vpt: Vertical Position Traps. + (line 10414) +* breaking file names (\:): Manipulating Hyphenation. + (line 6008) +* breaking URLs (\:): Manipulating Hyphenation. + (line 6008) +* breaking without hyphens (\:): Manipulating Hyphenation. + (line 6008) +* built-in register, removing: Built-in Registers. + (line 5513) +* built-in registers: Built-in Registers. + (line 5508) +* bulleted list, example markup [ms]: Lists in ms. (line 2590) +* c scaling unit: Measurements. (line 4252) +* calling a macro: Requests and Macros. + (line 3840) +* calling macros: Calling Macros. (line 4851) +* capabilities of groff: groff Capabilities. + (line 281) +* case-transforming a string (stringdown, stringup): Strings. + (line 8945) +* categories, warning: Warnings. (line 12250) +* CCSID 1047 output encoding (EBCDIC): Groff Options. (line 755) +* ce request, causing implicit break: Manipulating Filling and Adjustment. + (line 5624) +* ce request, difference from .ad c: Manipulating Filling and Adjustment. + (line 5836) +* cell, character, attributes: Using Fonts. (line 7323) +* centered text (filled): Manipulating Filling and Adjustment. + (line 5716) +* centered text (unfilled): Manipulating Filling and Adjustment. + (line 5827) +* centering lines (ce): Manipulating Filling and Adjustment. + (line 5827) +* centering lines (introduction): Basics. (line 1170) +* centimeter scaling unit (c): Measurements. (line 4252) +* cf request, and copy mode: I/O. (line 11521) +* cf request, causing implicit break: Manipulating Filling and Adjustment. + (line 5624) +* changing control characters: Control Characters. + (line 4726) +* changing font family (fam, \F): Font Families. (line 7467) +* changing fonts (ft, \f): Selecting Fonts. (line 7352) +* changing format, and read-only registers: Assigning Register Formats. + (line 5472) +* changing the font height (\H): Artificial Fonts. (line 8132) +* changing the font slant (\S): Artificial Fonts. (line 8161) +* changing the page number character (pc): Page Layout. (line 7149) +* changing trap location (ch): Page Location Traps. + (line 10528) +* changing type sizes (ps, \s): Changing the Type Size. + (line 8466) +* changing vertical line spacing (vs): Changing the Vertical Spacing. + (line 8543) +* char request, and soft hyphen character: Manipulating Hyphenation. + (line 6032) +* char request, and translations: Character Translations. + (line 6741) +* char request, used with \N: Using Symbols. (line 7810) +* character: Using Symbols. (line 7600) +* character cell attributes: Using Fonts. (line 7323) +* character class (class): Character Classes. (line 8034) +* character classes: Character Classes. (line 8028) +* character properties (cflags): Using Symbols. (line 7846) +* character translations: Character Translations. + (line 6722) +* character, backspace, and translations: Character Translations. + (line 6751) +* character, control (.): Requests and Macros. + (line 3813) +* character, control, changing (cc): Control Characters. + (line 4738) +* character, defining (char): Using Symbols. (line 7948) +* character, defining fallback (fchar, fschar, schar): Using Symbols. + (line 7948) +* character, distinguished from glyph: Using Symbols. (line 7600) +* character, dummy (\&): Dummy Characters. (line 8357) +* character, dummy (\&), as control character suppressor: Requests and Macros. + (line 3820) +* character, dummy (\&), effect on kerning: Ligatures and Kerning. + (line 8294) +* character, dummy (\&), effect on \l escape sequence: Drawing Geometric Objects. + (line 10150) +* character, escape, changing (ec): Using Escape Sequences. + (line 5012) +* character, escape, while defining glyph: Using Symbols. (line 7948) +* character, field delimiting (fc): Fields. (line 6692) +* character, field padding (fc): Fields. (line 6692) +* character, horizontal tab: Tabs and Leaders. (line 3785) +* character, hyphenation (\%): Manipulating Hyphenation. + (line 5992) +* character, leader: Tabs and Leaders. (line 3785) +* character, leader repetition (lc): Leaders. (line 6661) +* character, leader, and translations: Character Translations. + (line 6751) +* character, leader, non-interpreted (\a): Leaders. (line 6658) +* character, named (\C): Using Symbols. (line 7793) +* character, newline, and translations: Character Translations. + (line 6751) +* character, no-break control ('): Requests and Macros. + (line 3813) +* character, no-break control, changing (c2): Control Characters. + (line 4738) +* character, ordinary: Identifiers. (line 4577) +* character, soft hyphen, setting (shc): Manipulating Hyphenation. + (line 6032) +* character, special: Character Translations. + (line 6741) +* character, tab repetition (tc): Tabs and Fields. (line 6602) +* character, tab, and translations: Character Translations. + (line 6751) +* character, tab, non-interpreted (\t): Tabs and Fields. (line 6485) +* character, transparent: Using Symbols. (line 7892) +* character, transparent dummy (\)): Dummy Characters. (line 8407) +* characters, end-of-sentence: Using Symbols. (line 7863) +* characters, end-of-sentence transparent: Sentences. (line 3663) +* characters, hyphenation: Using Symbols. (line 7868) +* characters, input, and output glyphs, compatibility with AT&T troff: Other Differences. + (line 12609) +* characters, invalid for trf request: I/O. (line 11533) +* characters, invalid input: Identifiers. (line 4581) +* characters, overlapping: Using Symbols. (line 7882) +* characters, special: Sentences. (line 3663) +* characters, special, list of (groff_char(7) man page): Using Symbols. + (line 7675) +* characters, unnamed, accessing with \N: Font Description File Format. + (line 13639) +* circle, filled, drawing (\D'C ...'): Drawing Geometric Objects. + (line 10234) +* circle, outlined, drawing (\D'c ...'): Drawing Geometric Objects. + (line 10230) +* circle, solid, drawing (\D'C ...'): Drawing Geometric Objects. + (line 10234) +* circle, stroked, drawing (\D'c ...'): Drawing Geometric Objects. + (line 10230) +* class of characters (class): Character Classes. (line 8034) +* classes, character: Character Classes. (line 8028) +* clearing input line trap (it, itc): Input Line Traps. (line 10680) +* closing brace escape sequence (\}): Conditional Blocks. + (line 9250) +* closing file (close): I/O. (line 11703) +* code page 1047 output encoding: Groff Options. (line 755) +* code page 1047, input encoding: Input Encodings. (line 3986) +* code, hyphenation (hcode): Manipulating Hyphenation. + (line 6228) +* color name, background, register (.M): Colors. (line 8765) +* color name, fill, register (.M): Colors. (line 8765) +* color name, stroke, register (.m): Colors. (line 8744) +* color, default: Colors. (line 8720) +* color, fill: Colors. (line 8678) +* color, stroke: Colors. (line 8678) +* colors: Colors. (line 8678) +* command prefix: Environment. (line 835) +* command-line options: Groff Options. (line 520) +* comments: Comments. (line 5132) +* comments in device description files: DESC File Format. (line 13432) +* comments in font description files: Font Description File Format. + (line 13592) +* comments, lining up with tabs: Comments. (line 5145) +* comments, with ds: Strings. (line 8823) +* common features: Common Features. (line 1201) +* common name space of macros, diversions, and strings: Identifiers. + (line 4668) +* comparison of strings: Operators in Conditionals. + (line 9108) +* comparison operators: Numeric Expressions. + (line 4416) +* compatibility mode: Warnings. (line 12341) +* compatibility mode <1>: Compatibility Mode. + (line 12404) +* compatibility mode, and parameters: Gtroff Internals. (line 12054) +* complementation, logical: Numeric Expressions. + (line 4426) +* composite glyph names: Using Symbols. (line 7688) +* conditional block, beginning (\{): Conditional Blocks. + (line 9250) +* conditional block, end (\}): Conditional Blocks. + (line 9250) +* conditional blocks: Conditional Blocks. + (line 9243) +* conditional expressions: Operators in Conditionals. + (line 9027) +* conditional output for terminal (TTY): Operators in Conditionals. + (line 9053) +* conditional page break (ne): Page Control. (line 7195) +* conditionals and loops: Conditionals and Loops. + (line 9020) +* configuring control characters: Control Characters. + (line 4726) +* configuring the page length (pl): Page Layout. (line 7093) +* consecutive hyphenated lines (hlm): Manipulating Hyphenation. + (line 6277) +* constant glyph space mode (cs): Artificial Fonts. (line 8241) +* contents, table of: Table of Contents. (line 1323) +* contents, table of <1>: Leaders. (line 6671) +* continuation, input line (\<RET>): Line Continuation. (line 7019) +* continuation, output line (\c): Line Continuation. (line 7048) +* continue request, in a while loop: while. (line 9393) +* continued output line register (.int): Line Continuation. (line 7073) +* continuous underlining (cu): Artificial Fonts. (line 8202) +* control character (.): Requests and Macros. + (line 3813) +* control character, changing (cc): Control Characters. + (line 4738) +* control character, no-break ('): Requests and Macros. + (line 3813) +* control character, no-break, changing (c2): Control Characters. + (line 4738) +* control characters: Control Characters. + (line 4726) +* control line: Requests and Macros. + (line 3825) +* control, line: Line Continuation. (line 7014) +* control, page: Page Control. (line 7170) +* conventions for input: Input Conventions. (line 4051) +* conversion to basic units: Measurements. (line 4239) +* copy mode: Copy Mode. (line 9699) +* copy mode <1>: Copy Mode. (line 9699) +* copy mode, and cf request: I/O. (line 11521) +* copy mode, and device request: Postprocessor Access. + (line 11744) +* copy mode, and length request: Strings. (line 8909) +* copy mode, and macro parameters: Parameters. (line 9616) +* copy mode, and output request: Diversions. (line 11106) +* copy mode, and trf request: I/O. (line 11521) +* copy mode, and write request: I/O. (line 11683) +* copy mode, and writec request: I/O. (line 11683) +* copy mode, and writem request: I/O. (line 11697) +* copy mode, and \!: Diversions. (line 11074) +* copy mode, and \?: Operators in Conditionals. + (line 9116) +* copy mode, and \? <1>: Diversions. (line 11074) +* copy mode, and \a: Leaders. (line 6658) +* copy mode, and \t: Tabs and Fields. (line 6485) +* copy mode, and \V: I/O. (line 11721) +* copying environment (evc): Environments. (line 11362) +* correction between oblique and upright glyph (\/, \,): Italic Corrections. + (line 8328) +* correction between upright and oblique glyph (\/, \,): Italic Corrections. + (line 8338) +* correction, italic (\/): Italic Corrections. + (line 8328) +* correction, left italic (\,): Italic Corrections. + (line 8338) +* cover page in [ms], example markup: ms Document Description Macros. + (line 2196) +* cp request, and glyph definitions: Using Symbols. (line 7948) +* cq glyph, at end of sentence: Sentences. (line 3663) +* cq glyph, at end of sentence <1>: Using Symbols. (line 7892) +* creating alias for register (aln): Setting Registers. (line 5323) +* creating alias, for diversion (als): Strings. (line 8972) +* creating alias, for macro (als): Strings. (line 8972) +* creating alias, for string (als): Strings. (line 8972) +* creating new characters (char): Using Symbols. (line 7948) +* credits: Credits. (line 444) +* cs request, and font styles: Font Families. (line 7505) +* cs request, and font translations: Selecting Fonts. (line 7406) +* cs request, incompatibilities with AT&T troff: Other Differences. + (line 12609) +* cs request, with fractional type sizes: Using Fractional Type Sizes. + (line 8604) +* CSTR #54 errata: Built-in Registers. + (line 5600) +* CSTR #54 errata <1>: Line Layout. (line 6920) +* CSTR #54 errata <2>: Page Control. (line 7185) +* CSTR #54 errata <3>: Artificial Fonts. (line 8176) +* CSTR #54 errata <4>: Changing the Type Size. + (line 8475) +* CSTR #54 errata <5>: Page Motions. (line 10040) +* CSTR #54 erratum, bp request: Page Control. (line 7185) +* CSTR #54 erratum, po request: Line Layout. (line 6920) +* CSTR #54 erratum, ps request: Changing the Type Size. + (line 8475) +* CSTR #54 erratum, sb register: Page Motions. (line 10040) +* CSTR #54 erratum, st register: Page Motions. (line 10040) +* CSTR #54 erratum, yr register: Built-in Registers. + (line 5600) +* CSTR #54 erratum, \S escape: Artificial Fonts. (line 8176) +* CSTR #54 erratum, \s escape sequence: Changing the Type Size. + (line 8475) +* current directory: Macro Directories. (line 910) +* current input file name register (.F): Built-in Registers. + (line 5536) +* current page number (%): Page Control. (line 7188) +* current time, hours (hours): Built-in Registers. + (line 5586) +* current time, minutes (minutes): Built-in Registers. + (line 5583) +* current time, seconds (seconds): Built-in Registers. + (line 5580) +* da request, and dn (dl): Diversions. (line 11026) +* da request, and warnings: Warnings. (line 12296) +* da request, and warnings <1>: Warnings. (line 12301) +* date, day of the month register (dy): Built-in Registers. + (line 5592) +* date, day of the week register (dw): Built-in Registers. + (line 5589) +* date, month of the year register (mo): Built-in Registers. + (line 5595) +* date, year register (year, yr): Built-in Registers. + (line 5598) +* day of the month register (dy): Built-in Registers. + (line 5592) +* day of the week register (dw): Built-in Registers. + (line 5589) +* dd glyph, at end of sentence: Sentences. (line 3663) +* dd glyph, at end of sentence <1>: Using Symbols. (line 7892) +* de request, and while: while. (line 9343) +* de, de1, dei requests, and warnings: Warnings. (line 12301) +* debugging: Debugging. (line 12078) +* debugging page location traps: Page Location Traps. + (line 10476) +* decimal point, as delimiter: Delimiters. (line 5090) +* decrementation, automatic, of a register: Auto-increment. (line 5364) +* default color: Colors. (line 8720) +* default tab stops: Tabs and Fields. (line 6493) +* default units: Default Units. (line 4318) +* deferred output: Deferring Output. (line 10337) +* defining character (char): Using Symbols. (line 7948) +* defining character class (class): Character Classes. (line 8034) +* defining fallback character (fchar, fschar, schar): Using Symbols. + (line 7948) +* defining glyph (char): Using Symbols. (line 7948) +* defining symbol (char): Using Symbols. (line 7948) +* delimited arguments, incompatibilities with AT&T troff: Compatibility Mode. + (line 12498) +* delimiters, for escape sequence arguments: Delimiters. (line 5060) +* delimiting character, for fields (fc): Fields. (line 6692) +* delimiting escape sequence arguments: Delimiters. (line 5060) +* depth, interpolation: Calling Macros. (line 4929) +* depth, of last glyph (.cdp): Environments. (line 11388) +* DESC file format: DESC File Format. (line 13425) +* DESC file, and font mounting: Font Positions. (line 7590) +* DESC file, and use_charnames_in_special keyword: Postprocessor Access. + (line 11760) +* description file, font: Using Fonts. (line 7295) +* device description files, comments: DESC File Format. (line 13432) +* device request, and copy mode: Postprocessor Access. + (line 11744) +* device resolution: Page Geometry. (line 4169) +* device resolution <1>: DESC File Format. (line 13506) +* device resolution, obtaining in the formatter: Measurements. + (line 4240) +* devices for output: Output Device Intro. + (line 359) +* dg glyph, at end of sentence: Sentences. (line 3663) +* dg glyph, at end of sentence <1>: Using Symbols. (line 7892) +* di request, and warnings: Warnings. (line 12296) +* di request, and warnings <1>: Warnings. (line 12301) +* differences in implementation: Implementation Differences. + (line 12388) +* digit-width space (\0): Page Motions. (line 10014) +* digits, as delimiters: Delimiters. (line 5090) +* dimensions, line: Line Layout. (line 6855) +* directories for fonts: Font Directories. (line 934) +* directories for macros: Macro Directories. (line 898) +* directory, current: Macro Directories. (line 910) +* directory, for tmac files: Macro Directories. (line 900) +* directory, home: Macro Directories. (line 913) +* directory, platform-specific: Macro Directories. (line 915) +* directory, site-local: Macro Directories. (line 915) +* directory, site-local <1>: Font Directories. (line 957) +* disabling hyphenation (\%): Manipulating Hyphenation. + (line 5992) +* disabling \ (eo): Using Escape Sequences. + (line 5007) +* discardable horizontal space: Manipulating Filling and Adjustment. + (line 5914) +* displays: Displays and Keeps. + (line 1290) +* displays [ms]: ms keeps and displays. + (line 2797) +* displays, and footnotes [ms]: ms Footnotes. (line 2958) +* distance to next vertical position trap register (.t): Page Location Traps. + (line 10520) +* diversion: Deferring Output. (line 10337) +* diversion name register (.z): Diversions. (line 11000) +* diversion trap, setting (dt): Diversion Traps. (line 10668) +* diversion traps: Diversion Traps. (line 10663) +* diversion, appending to (da, boxa): Diversions. (line 10944) +* diversion, beginning (di, box): Diversions. (line 10944) +* diversion, creating alias for (als): Strings. (line 8972) +* diversion, ending (di, box): Diversions. (line 10944) +* diversion, nested: Diversions. (line 11000) +* diversion, removing (rm): Strings. (line 8967) +* diversion, removing alias for (rm): Strings. (line 9007) +* diversion, renaming (rn): Strings. (line 8964) +* diversion, stripping final newline: Punning Names. (line 11246) +* diversion, top-level: Diversions. (line 10930) +* diversion, top-level, and bp: Page Control. (line 7183) +* diversion, top-level, and \!: Diversions. (line 11098) +* diversion, top-level, and \?: Diversions. (line 11103) +* diversion, unformatting (asciify): Diversions. (line 11120) +* diversion, vertical position in, register (.d): Diversions. + (line 11000) +* diversions: Diversions. (line 10918) +* diversions <1>: Punning Names. (line 11157) +* diversions, and traps: Page Location Traps. + (line 10618) +* diversions, shared name space with macros and strings: Identifiers. + (line 4668) +* division, truncating: Numeric Expressions. + (line 4359) +* dl register, and da (boxa): Diversions. (line 11026) +* dn register, and da (boxa): Diversions. (line 11026) +* document description macros, [ms]: ms Document Description Macros. + (line 2132) +* document formats: Document Formats. (line 1349) +* documents, multi-file: Debugging. (line 12103) +* documents, structuring the source of: Invoking Requests. (line 4803) +* dot, as delimiter: Delimiters. (line 5090) +* double quote, embedding in a macro argument: Calling Macros. + (line 4875) +* double quotes, trailing, in strings: Strings. (line 8844) +* double-spacing (ls): Manipulating Spacing. + (line 6396) +* double-spacing (vs, pvs): Changing the Vertical Spacing. + (line 8575) +* down-casing a string (stringdown): Strings. (line 8945) +* drawing a filled circle (\D'C ...'): Drawing Geometric Objects. + (line 10234) +* drawing a filled ellipse (\D'E ...'): Drawing Geometric Objects. + (line 10241) +* drawing a filled polygon (\D'P ...'): Drawing Geometric Objects. + (line 10275) +* drawing a line (\D'l ...'): Drawing Geometric Objects. + (line 10244) +* drawing a solid circle (\D'C ...'): Drawing Geometric Objects. + (line 10234) +* drawing a solid ellipse (\D'E ...'): Drawing Geometric Objects. + (line 10241) +* drawing a solid polygon (\D'P ...'): Drawing Geometric Objects. + (line 10275) +* drawing a spline (\D'~ ...'): Drawing Geometric Objects. + (line 10221) +* drawing a stroked circle (\D'c ...'): Drawing Geometric Objects. + (line 10230) +* drawing a stroked ellipse (\D'e ...'): Drawing Geometric Objects. + (line 10237) +* drawing a stroked polygon (\D'p ...'): Drawing Geometric Objects. + (line 10269) +* drawing an arc (\D'a ...'): Drawing Geometric Objects. + (line 10225) +* drawing an outlined circle (\D'c ...'): Drawing Geometric Objects. + (line 10230) +* drawing an outlined ellipse (\D'e ...'): Drawing Geometric Objects. + (line 10237) +* drawing an outlined polygon (\D'p ...'): Drawing Geometric Objects. + (line 10269) +* drawing horizontal lines (\l): Drawing Geometric Objects. + (line 10142) +* drawing position: Page Geometry. (line 4181) +* drawing position, vertical (nl): Page Control. (line 7240) +* drawing requests: Drawing Geometric Objects. + (line 10130) +* drawing vertical lines (\L): Drawing Geometric Objects. + (line 10168) +* ds request, and comments: Strings. (line 8823) +* ds request, and double quotes: Strings. (line 8844) +* ds request, and leading spaces: Strings. (line 8844) +* ds, ds1 requests, and comments: Comments. (line 5139) +* ds, ds1 requests, and warnings: Warnings. (line 12301) +* dummy character (\&): Dummy Characters. (line 8357) +* dummy character (\&), as control character suppressor: Requests and Macros. + (line 3820) +* dummy character (\&), effect on kerning: Ligatures and Kerning. + (line 8294) +* dummy character (\&), effect on \l escape sequence: Drawing Geometric Objects. + (line 10150) +* dummy character, transparent (\)): Dummy Characters. (line 8407) +* dummy environment, used by \w escape sequence: Page Motions. + (line 10034) +* dumping environments (pev): Debugging. (line 12150) +* dumping page location traps (ptr): Debugging. (line 12162) +* dumping registers (pnr): Debugging. (line 12158) +* dumping symbol table (pm): Debugging. (line 12154) +* EBCDIC output encoding: Groff Options. (line 755) +* EBCDIC, input encoding: Input Encodings. (line 3986) +* ejection, page: Page Geometry. (line 4208) +* ejection, page <1>: Page Control. (line 7170) +* ejection, page <2>: The Implicit Page Trap. + (line 10638) +* ejection, page, of final page: End-of-input Traps. + (line 10834) +* ejection, page, prevented by vpt: Vertical Position Traps. + (line 10414) +* el request, and warnings: Warnings. (line 12273) +* ellipse, filled, drawing (\D'E ...'): Drawing Geometric Objects. + (line 10241) +* ellipse, outlined, drawing (\D'e ...'): Drawing Geometric Objects. + (line 10237) +* ellipse, solid, drawing (\D'E ...'): Drawing Geometric Objects. + (line 10241) +* ellipse, stroked, drawing (\D'e ...'): Drawing Geometric Objects. + (line 10237) +* em glyph, and cflags: Using Symbols. (line 7875) +* em scaling unit (m): Measurements. (line 4277) +* embolding of special fonts: Artificial Fonts. (line 8230) +* empty line: Breaking. (line 3749) +* en scaling unit (n): Measurements. (line 4281) +* enabling vertical position traps (vpt): Vertical Position Traps. + (line 10407) +* encoding, input, code page 1047: Input Encodings. (line 3986) +* encoding, input, EBCDIC: Input Encodings. (line 3986) +* encoding, input, Latin-1 (ISO 8859-1): Input Encodings. (line 3991) +* encoding, input, Latin-2 (ISO 8859-2): Input Encodings. (line 4004) +* encoding, input, Latin-5 (ISO 8859-9): Input Encodings. (line 4010) +* encoding, input, Latin-9 (ISO 8859-15): Input Encodings. (line 4015) +* encoding, output, ASCII: Groff Options. (line 743) +* encoding, output, code page 1047: Groff Options. (line 755) +* encoding, output, EBCDIC: Groff Options. (line 755) +* encoding, output, ISO 646: Groff Options. (line 743) +* encoding, output, Latin-1 (ISO 8859-1): Groff Options. (line 747) +* encoding, output, UTF-8: Groff Options. (line 751) +* end of conditional block (\}): Conditional Blocks. + (line 9250) +* end-of-input macro (em): End-of-input Traps. + (line 10807) +* end-of-input trap, setting (em): End-of-input Traps. + (line 10807) +* end-of-input traps: End-of-input Traps. + (line 10806) +* end-of-sentence characters: Sentences. (line 3619) +* end-of-sentence characters <1>: Using Symbols. (line 7863) +* end-of-sentence transparent characters: Sentences. (line 3663) +* ending diversion (di, box): Diversions. (line 10944) +* endnotes: Footnotes and Endnotes. + (line 1313) +* environment: Deferring Output. (line 10337) +* environment availability and naming, incompatibilities with: Other Differences. + (line 12583) +* environment number/name register (.ev): Environments. (line 11309) +* environment variables: Environment. (line 827) +* environment, copying (evc): Environments. (line 11362) +* environment, dimensions of last glyph (.w, .cht, .cdp, .csk): Environments. + (line 11388) +* environment, dummy, used by \w escape sequence: Page Motions. + (line 10034) +* environment, previous line length (.n): Environments. (line 11403) +* environment, switching (ev): Environments. (line 11309) +* environments: Environments. (line 11268) +* environments, dumping (pev): Debugging. (line 12150) +* equality operator: Numeric Expressions. + (line 4416) +* equation example [ms]: ms Insertions. (line 2903) +* equations [ms]: ms Insertions. (line 2844) +* escape character, changing (ec): Using Escape Sequences. + (line 5012) +* escape character, formatting (\e): Using Escape Sequences. + (line 4999) +* escape character, while defining glyph: Using Symbols. (line 7948) +* escape sequence: Formatter Instructions. + (line 4714) +* escape sequence argument delimiters: Delimiters. (line 5060) +* escape sequences: Using Escape Sequences. + (line 4942) +* escape sequences, brace (\{, \}): Conditional Blocks. + (line 9250) +* escaping newline characters, in strings: Strings. (line 8853) +* ex request, use in debugging: Debugging. (line 12132) +* ex request, used with nx and rd: I/O. (line 11591) +* example markup, bulleted list [ms]: Lists in ms. (line 2590) +* example markup, cover page in [ms]: ms Document Description Macros. + (line 2196) +* example markup, glossary-style list [ms]: Lists in ms. (line 2637) +* example markup, numbered list [ms]: Lists in ms. (line 2609) +* examples of invocation: Invocation Examples. + (line 1002) +* exiting (ex): Debugging. (line 12132) +* expansion of strings (\*): Strings. (line 8802) +* explicit hyphen (\%): Manipulating Hyphenation. + (line 6277) +* explicit hyphenation: Manipulating Hyphenation. + (line 5948) +* expression, limitation of logical not in: Numeric Expressions. + (line 4426) +* expression, order of evaluation: Numeric Expressions. + (line 4446) +* expressions, and register format: Assigning Register Formats. + (line 5484) +* expressions, and space characters: Numeric Expressions. + (line 4538) +* expressions, conditional: Operators in Conditionals. + (line 9027) +* expressions, numeric: Numeric Expressions. + (line 4348) +* extra post-vertical line space (\x): Changing the Vertical Spacing. + (line 8568) +* extra post-vertical line space register (.a): Manipulating Spacing. + (line 6420) +* extra pre-vertical line space (\x): Changing the Vertical Spacing. + (line 8560) +* extra spaces between words: Adjustment. (line 3775) +* extreme values representable with Roman numerals: Assigning Register Formats. + (line 5465) +* extremum operators (>?, <?): Numeric Expressions. + (line 4407) +* f scaling unit: Colors. (line 8712) +* factor, zoom, of a font (fzoom): Selecting Fonts. (line 7421) +* fallback character, defining (fchar, fschar, schar): Using Symbols. + (line 7948) +* fallback glyph, removing definition (rchar, rfschar): Using Symbols. + (line 8005) +* fam request, and changing fonts: Selecting Fonts. (line 7352) +* families, font: Font Families. (line 7448) +* family, font: Using Fonts. (line 7280) +* features, common: Common Features. (line 1201) +* fi request, causing implicit break: Manipulating Filling and Adjustment. + (line 5624) +* field delimiting character (fc): Fields. (line 6692) +* field padding character (fc): Fields. (line 6692) +* fields: Fields. (line 6692) +* fields, and tabs: Tabs and Fields. (line 6481) +* figure space (\0): Page Motions. (line 10014) +* figures [ms]: ms Insertions. (line 2844) +* file formats: File Formats. (line 12674) +* file names, breaking (\:): Manipulating Hyphenation. + (line 6008) +* file, appending to (opena): I/O. (line 11671) +* file, closing (close): I/O. (line 11703) +* file, font description: Using Fonts. (line 7295) +* file, inclusion (so): I/O. (line 11473) +* file, macro, search path: Macro Directories. (line 900) +* file, opening (open): I/O. (line 11671) +* file, processing next (nx): I/O. (line 11553) +* file, writing to (write, writec): I/O. (line 11683) +* files, font: Device and Font Description Files. + (line 13401) +* fill color: Colors. (line 8678) +* fill color name register (.M): Colors. (line 8765) +* fill mode (fi), enabling: Manipulating Filling and Adjustment. + (line 5685) +* fill mode, and \c: Line Continuation. (line 7054) +* fill mode, disabling: Manipulating Filling and Adjustment. + (line 5692) +* filled circle, drawing (\D'C ...'): Drawing Geometric Objects. + (line 10234) +* filled ellipse, drawing (\D'E ...'): Drawing Geometric Objects. + (line 10241) +* filled polygon, drawing (\D'P ...'): Drawing Geometric Objects. + (line 10275) +* filling: Filling. (line 3581) +* filling and adjustment, manipulating: Manipulating Filling and Adjustment. + (line 5624) +* filling of output, disabling (nf): Manipulating Filling and Adjustment. + (line 5692) +* filling of output, enabling (fi): Manipulating Filling and Adjustment. + (line 5685) +* filling, and break warnings: Warnings. (line 12262) +* filling, and inter-sentence space: Manipulating Filling and Adjustment. + (line 5898) +* final newline, stripping in diversions: Punning Names. (line 11246) +* fl request, causing implicit break: Manipulating Filling and Adjustment. + (line 5624) +* floating keep: Displays and Keeps. + (line 1301) +* flush output (fl): Debugging. (line 12167) +* font: Using Fonts. (line 7280) +* font aliasing with third argument to fp request: Font Positions. + (line 7561) +* font description file: Using Fonts. (line 7295) +* font description file format: DESC File Format. (line 13425) +* font description file, format: Font Description File Format. + (line 13572) +* font description files, comments: Font Description File Format. + (line 13592) +* font directories: Font Directories. (line 934) +* font families: Font Families. (line 7448) +* font family: Using Fonts. (line 7280) +* font family, changing (fam, \F): Font Families. (line 7467) +* font file, format: Font Description File Format. + (line 13572) +* font files: Device and Font Description Files. + (line 13401) +* font for underlining (uf): Artificial Fonts. (line 8206) +* font height, changing (\H): Artificial Fonts. (line 8132) +* font metrics: Using Fonts. (line 7295) +* font mounting, automatic: Selecting Fonts. (line 7365) +* font path: Font Directories. (line 942) +* font position register (.f): Font Positions. (line 7578) +* font positions: Font Positions. (line 7540) +* font slant, changing (\S): Artificial Fonts. (line 8161) +* font style: Using Fonts. (line 7280) +* font style, abstract: Using Fonts. (line 7302) +* font style, abstract, setting up (sty): Font Families. (line 7505) +* font styles: Font Families. (line 7448) +* font translation (ftr): Selecting Fonts. (line 7406) +* font, magnification (fzoom): Selecting Fonts. (line 7421) +* font, mounting (fp): Font Positions. (line 7552) +* font, optical size: Selecting Fonts. (line 7421) +* font, previous, selecting (\f[], \fP): Selecting Fonts. (line 7378) +* font, previous, slecting (ft): Selecting Fonts. (line 7352) +* font, selection: Selecting Fonts. (line 7343) +* font, special: Using Fonts. (line 7280) +* font, text: Using Fonts. (line 7280) +* font, unstyled: Using Fonts. (line 7280) +* font, zoom factor (fzoom): Selecting Fonts. (line 7421) +* fonts, artificial: Artificial Fonts. (line 8122) +* fonts, changing (ft, \f): Selecting Fonts. (line 7352) +* fonts, searching: Font Directories. (line 934) +* fonts, special: Special Fonts. (line 8092) +* footers: Page Layout. (line 7115) +* footers <1>: Page Location Traps. + (line 10440) +* footers [ms]: ms Headers and Footers. + (line 3052) +* footnote marker [ms]: ms Footnotes. (line 2920) +* footnotes: Footnotes and Endnotes. + (line 1313) +* footnotes [ms]: ms Footnotes. (line 2920) +* footnotes, and displays [ms]: ms Footnotes. (line 2958) +* footnotes, and keeps [ms]: ms Footnotes. (line 2958) +* form letters: I/O. (line 11575) +* format of font description file: DESC File Format. (line 13425) +* format of font description files: Font Description File Format. + (line 13572) +* format of font files: Font Description File Format. + (line 13572) +* format of register (\g): Assigning Register Formats. + (line 5479) +* format, paper: Paper Format. (line 972) +* formats, file: File Formats. (line 12674) +* formatter instructions: Formatter Instructions. + (line 4703) +* formatting a backslash glyph (\[rs]): Using Escape Sequences. + (line 5002) +* formatting a title line (tl): Page Layout. (line 7120) +* formatting the escape character (\e): Using Escape Sequences. + (line 4999) +* formatting the time: I/O. (line 11656) +* fp request, and font translations: Selecting Fonts. (line 7406) +* fp request, incompatibilities with AT&T troff: Other Differences. + (line 12609) +* fractional point sizes: Using Fractional Type Sizes. + (line 8597) +* fractional point sizes <1>: Other Differences. (line 12587) +* fractional type sizes: Using Fractional Type Sizes. + (line 8597) +* fractional type sizes <1>: Other Differences. (line 12587) +* fractional type sizes in ms macros: Differences from AT&T ms. + (line 3315) +* French spacing: Sentences. (line 3619) +* fspecial request, and font styles: Font Families. (line 7505) +* fspecial request, and font translations: Selecting Fonts. (line 7406) +* fspecial request, and glyph search order: Using Symbols. (line 7612) +* fspecial request, and imitating bold: Artificial Fonts. (line 8230) +* ft request, and font translations: Selecting Fonts. (line 7406) +* full-service macro package: Major Macro Packages. + (line 1397) +* geometry, page: Page Geometry. (line 4162) +* GGL (groff glyph list): Using Symbols. (line 7688) +* GGL (groff glyph list) <1>: Character Classes. (line 8055) +* glossary-style list, example markup [ms]: Lists in ms. (line 2637) +* glyph: Using Symbols. (line 7600) +* glyph for line drawing: Drawing Geometric Objects. + (line 10168) +* glyph names, composite: Using Symbols. (line 7688) +* glyph pile (\b): Drawing Geometric Objects. + (line 10308) +* glyph properties (cflags): Using Symbols. (line 7846) +* glyph, box rule (\[br]): Drawing Geometric Objects. + (line 10168) +* glyph, constant space: Artificial Fonts. (line 8241) +* glyph, defining (char): Using Symbols. (line 7948) +* glyph, distinguished from character: Using Symbols. (line 7600) +* glyph, for line drawing: Drawing Geometric Objects. + (line 10146) +* glyph, for margins (mc): Miscellaneous. (line 11897) +* glyph, last, dimensions (.w, .cht, .cdp, .csk): Environments. + (line 11388) +* glyph, leader repetition (lc): Leaders. (line 6661) +* glyph, numbered (\N): Character Translations. + (line 6741) +* glyph, numbered (\N) <1>: Using Symbols. (line 7810) +* glyph, removing definition (rchar, rfschar): Using Symbols. + (line 8005) +* glyph, soft hyphen (hy): Manipulating Hyphenation. + (line 6032) +* glyph, tab repetition (tc): Tabs and Fields. (line 6602) +* glyph, underscore (\[ru]): Drawing Geometric Objects. + (line 10146) +* glyphs, available, list of (groff_char(7) man page): Using Symbols. + (line 7675) +* glyphs, output, and input characters, compatibility with AT&T troff: Other Differences. + (line 12609) +* glyphs, overstriking (\o): Page Motions. (line 10097) +* glyphs, unnamed: Using Symbols. (line 7820) +* glyphs, unnamed, accessing with \N: Font Description File Format. + (line 13639) +* GNU troff, identification register (.g): Built-in Registers. + (line 5539) +* GNU troff, PID register ($$): Built-in Registers. + (line 5571) +* GNU troff, process ID register ($$): Built-in Registers. + (line 5571) +* GNU-specific register (.g): Built-in Registers. + (line 5539) +* graphic renditions: Using Fonts. (line 7323) +* greater than (or equal to) operator: Numeric Expressions. + (line 4416) +* groff capabilities: groff Capabilities. + (line 281) +* groff glyph list (GGL): Using Symbols. (line 7688) +* groff glyph list (GGL) <1>: Character Classes. (line 8055) +* groff invocation: Invoking groff. (line 454) +* groff, and pi request: I/O. (line 11629) +* groff--what is it?: What Is groff?. (line 264) +* GROFF_BIN_PATH, environment variable: Environment. (line 831) +* GROFF_COMMAND_PREFIX, environment variable: Environment. (line 835) +* GROFF_ENCODING, environment variable: Environment. (line 846) +* GROFF_FONT_PATH, environment variable: Environment. (line 855) +* GROFF_FONT_PATH, environment variable <1>: Font Directories. + (line 955) +* GROFF_TMAC_PATH, environment variable: Environment. (line 862) +* GROFF_TMAC_PATH, environment variable <1>: Macro Directories. + (line 908) +* GROFF_TMPDIR, environment variable: Environment. (line 869) +* GROFF_TYPESETTER, environment variable: Environment. (line 877) +* grohtml, the program: Groff Options. (line 766) +* gtroff, interactive use: Debugging. (line 12167) +* gtroff, output: gtroff Output. (line 12680) +* gtroff, reference: GNU troff Reference. + (line 3549) +* hair space (\^): Page Motions. (line 10008) +* hcode request, and glyph definitions: Using Symbols. (line 7948) +* headers: Page Layout. (line 7115) +* headers <1>: Page Location Traps. + (line 10440) +* headers [ms]: ms Headers and Footers. + (line 3052) +* height, font, changing (\H): Artificial Fonts. (line 8132) +* height, of last glyph (.cht): Environments. (line 11388) +* high-water mark register (.h): Diversions. (line 11007) +* home directory: Macro Directories. (line 913) +* horizontal discardable space: Manipulating Filling and Adjustment. + (line 5914) +* horizontal input line position register (hp): Page Motions. + (line 10090) +* horizontal input line position, saving (\k): Page Motions. + (line 10084) +* horizontal line, drawing (\l): Drawing Geometric Objects. + (line 10142) +* horizontal motion (\h): Page Motions. (line 9982) +* horizontal motion quantum: DESC File Format. (line 13445) +* horizontal motion quantum register (.H): Motion Quanta. (line 4299) +* horizontal output line position register (.k): Page Motions. + (line 10093) +* horizontal resolution: DESC File Format. (line 13445) +* horizontal resolution register (.H): Motion Quanta. (line 4299) +* horizontal space (\h): Page Motions. (line 9982) +* horizontal space, unformatting: Punning Names. (line 11246) +* horizontal tab character: Tabs and Leaders. (line 3785) +* hours, current time (hours): Built-in Registers. + (line 5586) +* hpf request, and hyphenation language: Manipulating Hyphenation. + (line 6263) +* hw request, and hy restrictions: Manipulating Hyphenation. + (line 5970) +* hw request, and hyphenation language: Manipulating Hyphenation. + (line 6263) +* hy glyph, and cflags: Using Symbols. (line 7875) +* hyphen, explicit (\%): Manipulating Hyphenation. + (line 6277) +* hyphenated lines, consecutive (hlm): Manipulating Hyphenation. + (line 6277) +* hyphenating characters: Using Symbols. (line 7868) +* hyphenation: Hyphenation. (line 3707) +* hyphenation character (\%): Manipulating Hyphenation. + (line 5992) +* hyphenation code (hcode): Manipulating Hyphenation. + (line 6228) +* hyphenation consecutive line count register (.hlc): Manipulating Hyphenation. + (line 6284) +* hyphenation consecutive line limit register (.hlm): Manipulating Hyphenation. + (line 6284) +* hyphenation exceptions: Manipulating Hyphenation. + (line 5956) +* hyphenation language register (.hla): Manipulating Hyphenation. + (line 6270) +* hyphenation margin (hym): Manipulating Hyphenation. + (line 6290) +* hyphenation margin register (.hym): Manipulating Hyphenation. + (line 6300) +* hyphenation mode register (.hy): Manipulating Hyphenation. + (line 6054) +* hyphenation parameters, automatic: Manipulating Hyphenation. + (line 6042) +* hyphenation pattern files: Manipulating Hyphenation. + (line 6116) +* hyphenation patterns (hpf): Manipulating Hyphenation. + (line 6170) +* hyphenation space (hys): Manipulating Hyphenation. + (line 6305) +* hyphenation space adjustment threshold: Manipulating Hyphenation. + (line 6305) +* hyphenation space adjustment threshold register (.hys): Manipulating Hyphenation. + (line 6316) +* hyphenation, automatic: Manipulating Hyphenation. + (line 5941) +* hyphenation, disabling (\%): Manipulating Hyphenation. + (line 5992) +* hyphenation, explicit: Manipulating Hyphenation. + (line 5948) +* hyphenation, incompatibilities with AT&T troff: Other Differences. + (line 12557) +* hyphenation, manipulating: Manipulating Hyphenation. + (line 5941) +* hyphenation, manual: Manipulating Hyphenation. + (line 5948) +* i scaling unit: Measurements. (line 4249) +* i/o: I/O. (line 11469) +* IBM code page 1047 input encoding: Input Encodings. (line 3986) +* IBM code page 1047 output encoding: Groff Options. (line 755) +* identifiers: Identifiers. (line 4574) +* identifiers, undefined: Identifiers. (line 4656) +* ie request, and font translations: Selecting Fonts. (line 7406) +* ie request, and warnings: Warnings. (line 12273) +* ie request, operators to use with: Operators in Conditionals. + (line 9027) +* if request, and font translations: Selecting Fonts. (line 7406) +* if request, and the ! operator: Numeric Expressions. + (line 4365) +* if request, operators to use with: Operators in Conditionals. + (line 9027) +* if-else: if-else. (line 9211) +* if-then: if-then. (line 9170) +* imitating boldface (bd): Artificial Fonts. (line 8213) +* implementation differences: Implementation Differences. + (line 12388) +* implicit line break: Breaking. (line 3725) +* implicit trap: The Implicit Page Trap. + (line 10638) +* in request, causing implicit break: Manipulating Filling and Adjustment. + (line 5624) +* in request, using + and - with: Numeric Expressions. + (line 4463) +* inch scaling unit (i): Measurements. (line 4249) +* including a file (so): I/O. (line 11473) +* incompatibilities with AT&T troff: Implementation Differences. + (line 12388) +* increment value without changing the register: Auto-increment. + (line 5403) +* incrementation, automatic, of a register: Auto-increment. (line 5364) +* indentation (in): Line Layout. (line 6874) +* indentation, of roff source code: Invoking Requests. (line 4803) +* index, in macro package: Indexing. (line 1340) +* indicator, scaling: Measurements. (line 4232) +* indirect assignments: Interpolating Registers. + (line 5340) +* input and output requests: I/O. (line 11469) +* input characters and output glyphs, compatibility with AT&T troff: Other Differences. + (line 12609) +* input characters, invalid: Identifiers. (line 4581) +* input conventions: Input Conventions. (line 4051) +* input encoding, code page 1047: Input Encodings. (line 3986) +* input encoding, EBCDIC: Input Encodings. (line 3986) +* input encoding, Latin-1 (ISO 8859-1): Input Encodings. (line 3991) +* input encoding, Latin-2 (ISO 8859-2): Input Encodings. (line 4004) +* input encoding, Latin-5 (ISO 8859-9): Input Encodings. (line 4010) +* input encoding, Latin-9 (ISO 8859-15): Input Encodings. (line 4015) +* input file name, current, register (.F): Built-in Registers. + (line 5536) +* input level: Calling Macros. (line 4929) +* input level in delimited arguments: Compatibility Mode. + (line 12498) +* input line continuation (\<RET>): Line Continuation. (line 7019) +* input line number register (.c, c.): Built-in Registers. + (line 5532) +* input line number, setting (lf): Debugging. (line 12103) +* input line position, horizontal, saving (\k): Page Motions. + (line 10084) +* input line trap, clearing (it, itc): Input Line Traps. (line 10680) +* input line trap, setting (it, itc): Input Line Traps. (line 10680) +* input line traps: Input Line Traps. (line 10678) +* input line traps and interrupted lines (itc): Input Line Traps. + (line 10704) +* input line, horizontal position, register (hp): Page Motions. + (line 10090) +* input line, productive: Manipulating Filling and Adjustment. + (line 5797) +* input stack, backtrace (backtrace): Debugging. (line 12176) +* input stack, setting limit: Debugging. (line 12197) +* input token: Gtroff Internals. (line 11970) +* input, 8-bit: Font Description File Format. + (line 13639) +* input, standard, reading from (rd): I/O. (line 11558) +* inserting horizontal space (\h): Page Motions. (line 9982) +* installation: Installation. (line 370) +* instructing the formatter: Formatter Instructions. + (line 4703) +* inter-sentence space size register (.sss): Manipulating Filling and Adjustment. + (line 5887) +* inter-sentence space, additional: Manipulating Filling and Adjustment. + (line 5893) +* inter-word spacing, minimal: Manipulating Filling and Adjustment. + (line 5891) +* interactive use of gtroff: Debugging. (line 12167) +* intercepting requests: Control Characters. + (line 4765) +* intermediate output: gtroff Output. (line 12690) +* interpolating registers (\n): Interpolating Registers. + (line 5335) +* interpolation: Requests and Macros. + (line 3840) +* interpolation depth: Calling Macros. (line 4929) +* interpolation depth in delimited arguments: Compatibility Mode. + (line 12498) +* interpolation of strings (\*): Strings. (line 8802) +* interpretation mode: Copy Mode. (line 9708) +* interrupted line: Line Continuation. (line 7048) +* interrupted line register (.int): Line Continuation. (line 7073) +* interrupted lines and input line traps (itc): Input Line Traps. + (line 10704) +* introduction: Introduction. (line 222) +* invalid characters for trf request: I/O. (line 11533) +* invalid input characters: Identifiers. (line 4581) +* invocation examples: Invocation Examples. + (line 1002) +* invoking groff: Invoking groff. (line 454) +* invoking requests: Invoking Requests. (line 4781) +* ISO 646 output encoding: Groff Options. (line 743) +* ISO 8859-1 (Latin-1) output encoding: Groff Options. (line 747) +* ISO 8859-1 (Latin-1), input encoding: Input Encodings. (line 3991) +* ISO 8859-15 (Latin-9), input encoding: Input Encodings. (line 4015) +* ISO 8859-2 (Latin-2), input encoding: Input Encodings. (line 4004) +* ISO 8859-9 (Latin-5), input encoding: Input Encodings. (line 4010) +* italic correction (\/): Italic Corrections. + (line 8328) +* justifying text: Manipulating Filling and Adjustment. + (line 5624) +* justifying text (rj): Manipulating Filling and Adjustment. + (line 5866) +* keep, floating: Displays and Keeps. + (line 1301) +* keeps (introduction): Displays and Keeps. + (line 1297) +* keeps [ms]: ms keeps and displays. + (line 2743) +* keeps, and footnotes [ms]: ms Footnotes. (line 2958) +* kerning and ligatures: Ligatures and Kerning. + (line 8253) +* kerning enabled register (.kern): Ligatures and Kerning. + (line 8289) +* kerning, activating (kern): Ligatures and Kerning. + (line 8289) +* kerning, track: Ligatures and Kerning. + (line 8300) +* landscape page orientation: Paper Format. (line 972) +* language [ms]: ms language and localization. + (line 3003) +* last glyph, dimensions (.w, .cht, .cdp, .csk): Environments. + (line 11388) +* last-requested point size registers (.psr, .sr): Using Fractional Type Sizes. + (line 8638) +* last-requested type size registers (.psr, .sr): Using Fractional Type Sizes. + (line 8638) +* Latin-1 (ISO 8859-1) output encoding: Groff Options. (line 747) +* Latin-1 (ISO 8859-1), input encoding: Input Encodings. (line 3991) +* Latin-2 (ISO 8859-2), input encoding: Input Encodings. (line 4004) +* Latin-5 (ISO 8859-9), input encoding: Input Encodings. (line 4010) +* Latin-9 (ISO 8859-15), input encoding: Input Encodings. (line 4015) +* layout, line: Line Layout. (line 6855) +* layout, page: Page Layout. (line 7087) +* lc request, and glyph definitions: Using Symbols. (line 7948) +* leader character: Tabs and Leaders. (line 3785) +* leader character <1>: Leaders. (line 6652) +* leader character, and translations: Character Translations. + (line 6751) +* leader character, non-interpreted (\a): Leaders. (line 6658) +* leader repetition character (lc): Leaders. (line 6661) +* leaders: Leaders. (line 6645) +* leading: Manipulating Type Size and Vertical Spacing. + (line 8444) +* leading space macro (lsm): Breaking. (line 3757) +* leading space traps: Leading Space Traps. + (line 10788) +* leading spaces: Breaking. (line 3757) +* leading spaces macro (lsm): Leading Space Traps. + (line 10791) +* leading spaces with ds: Strings. (line 8844) +* left italic correction (\,): Italic Corrections. + (line 8338) +* left margin (po): Line Layout. (line 6870) +* length of a string (length): Strings. (line 8909) +* length of line (ll): Line Layout. (line 6878) +* length of previous line (.n): Environments. (line 11403) +* length of the page, configuring (pl): Page Layout. (line 7093) +* length of title line, configuring (lt): Page Layout. (line 7137) +* length request, and copy mode: Strings. (line 8909) +* less than (or equal to) operator: Numeric Expressions. + (line 4416) +* letters, form: I/O. (line 11575) +* level, input: Calling Macros. (line 4929) +* level, suppression nesting, register: Suppressing Output. + (line 11463) +* lf request, incompatibilities with AT&T troff: Other Differences. + (line 12579) +* ligature: Using Symbols. (line 7600) +* ligatures and kerning: Ligatures and Kerning. + (line 8253) +* ligatures enabled register (.lg): Ligatures and Kerning. + (line 8271) +* ligatures, activating (lg): Ligatures and Kerning. + (line 8271) +* limitations of \b escape sequence: Drawing Geometric Objects. + (line 10316) +* line break: Manipulating Filling and Adjustment. + (line 5624) +* line break (introduction): Basics. (line 1188) +* line break, output: Breaking. (line 3725) +* line control: Line Continuation. (line 7014) +* line dimensions: Line Layout. (line 6855) +* line drawing glyph: Drawing Geometric Objects. + (line 10146) +* line drawing glyph <1>: Drawing Geometric Objects. + (line 10168) +* line indentation (in): Line Layout. (line 6874) +* line layout: Line Layout. (line 6855) +* line length (ll): Line Layout. (line 6878) +* line length register (.l): Line Layout. (line 7003) +* line length, previous (.n): Environments. (line 11403) +* line number, input, register (.c, c.): Built-in Registers. + (line 5532) +* line number, output, register (ln): Miscellaneous. (line 11820) +* line numbers, printing (nm): Miscellaneous. (line 11798) +* line space, extra post-vertical (\x): Changing the Vertical Spacing. + (line 8568) +* line space, extra pre-vertical (\x): Changing the Vertical Spacing. + (line 8560) +* line spacing register (.L): Manipulating Spacing. + (line 6400) +* line spacing, post-vertical (pvs): Changing the Vertical Spacing. + (line 8572) +* line thickness (\D't ...'): Drawing Geometric Objects. + (line 10298) +* line, blank: Breaking. (line 3749) +* line, drawing (\D'l ...'): Drawing Geometric Objects. + (line 10244) +* line, horizontal, drawing (\l): Drawing Geometric Objects. + (line 10142) +* line, input, continuation (\<RET>): Line Continuation. (line 7019) +* line, input, horizontal position, register (hp): Page Motions. + (line 10090) +* line, input, horizontal position, saving (\k): Page Motions. + (line 10084) +* line, interrupted: Line Continuation. (line 7048) +* line, output, continuation (\c): Line Continuation. (line 7048) +* line, output, horizontal position, register (.k): Page Motions. + (line 10093) +* line, productive input: Manipulating Filling and Adjustment. + (line 5797) +* line, vertical, drawing (\L): Drawing Geometric Objects. + (line 10168) +* line-tabs mode: Tabs and Fields. (line 6615) +* lines, blank, disabling: Manipulating Spacing. + (line 6456) +* lines, centering (ce): Manipulating Filling and Adjustment. + (line 5827) +* lines, centering (introduction): Basics. (line 1170) +* lines, consecutive hyphenated (hlm): Manipulating Hyphenation. + (line 6277) +* lines, interrupted, and input line traps (itc): Input Line Traps. + (line 10704) +* lines, right-aligning (introduction): Basics. (line 1182) +* lines, right-justifying (introduction): Basics. (line 1182) +* list of special characters (groff_char(7) man page): Using Symbols. + (line 7675) +* listing page location traps (ptr): Debugging. (line 12162) +* lists: Paragraphs. (line 1228) +* ll request, using + and - with: Numeric Expressions. + (line 4463) +* localization: Manipulating Hyphenation. + (line 6215) +* localization [ms]: ms language and localization. + (line 3003) +* locating macro files: Macro Directories. (line 900) +* locating macro packages: Macro Directories. (line 900) +* location, vertical, page, marking (mk): Page Motions. (line 9868) +* location, vertical, page, returning to marked (rt): Page Motions. + (line 9868) +* logical "and" operator: Numeric Expressions. + (line 4422) +* logical "or" operator: Numeric Expressions. + (line 4422) +* logical complementation operator: Numeric Expressions. + (line 4426) +* logical conjunction operator: Numeric Expressions. + (line 4422) +* logical disjunction operator: Numeric Expressions. + (line 4422) +* logical not, limitation in expression: Numeric Expressions. + (line 4426) +* logical operators: Numeric Expressions. + (line 4422) +* long names: Compatibility Mode. + (line 12404) +* loops and conditionals: Conditionals and Loops. + (line 9020) +* lowercasing a string (stringdown): Strings. (line 8945) +* ls request, alternative to (pvs): Changing the Vertical Spacing. + (line 8584) +* lt request, using + and - with: Numeric Expressions. + (line 4463) +* m scaling unit: Measurements. (line 4277) +* M scaling unit: Measurements. (line 4287) +* machine units: Page Geometry. (line 4169) +* macro: Requests and Macros. + (line 3840) +* macro arguments: Calling Macros. (line 4851) +* macro arguments, and compatibility mode: Gtroff Internals. + (line 12054) +* macro arguments, and tabs: Invoking Requests. (line 4789) +* macro directories: Macro Directories. (line 898) +* macro file search path: Macro Directories. (line 900) +* macro name register (\$0): Parameters. (line 9657) +* macro names, starting with [ or ], and refer: Identifiers. + (line 4623) +* macro package: Macro Packages. (line 3963) +* macro package search path: Macro Directories. (line 900) +* macro package usage, basics of: Basics. (line 1058) +* macro package, auxiliary: Major Macro Packages. + (line 1408) +* macro package, full-service: Major Macro Packages. + (line 1397) +* macro package, introduction: Macro Package Intro. + (line 316) +* macro package, major: Major Macro Packages. + (line 1394) +* macro package, minor: Major Macro Packages. + (line 1408) +* macro package, structuring the source of: Invoking Requests. + (line 4803) +* macro, appending to (am): Writing Macros. (line 9533) +* macro, creating alias for (als): Strings. (line 8972) +* macro, end-of-input (em): End-of-input Traps. + (line 10807) +* macro, parameters (\$): Parameters. (line 9616) +* macro, removing (rm): Strings. (line 8967) +* macro, removing alias for (rm): Strings. (line 9007) +* macro, renaming (rn): Strings. (line 8964) +* macros, recursive: while. (line 9359) +* macros, searching: Macro Directories. (line 898) +* macros, shared name space with strings and diversions: Identifiers. + (line 4668) +* macros, tutorial for users: Tutorial for Macro Users. + (line 1046) +* macros, writing: Writing Macros. (line 9410) +* magnification of a font (fzoom): Selecting Fonts. (line 7421) +* major macro package: Major Macro Packages. + (line 1394) +* major version number register (.x): Built-in Registers. + (line 5559) +* man macros, custom headers and footers: Optional man extensions. + (line 1433) +* man macros, Ultrix-specific: Optional man extensions. + (line 1451) +* man pages: man. (line 1417) +* manipulating filling and adjustment: Manipulating Filling and Adjustment. + (line 5624) +* manipulating hyphenation: Manipulating Hyphenation. + (line 5941) +* manipulating spacing: Manipulating Spacing. + (line 6344) +* manipulating type size and vertical spacing: Manipulating Type Size and Vertical Spacing. + (line 8438) +* manual hyphenation: Manipulating Hyphenation. + (line 5948) +* manual pages: man. (line 1417) +* margin for hyphenation (hym): Manipulating Hyphenation. + (line 6290) +* margin glyph (mc): Miscellaneous. (line 11897) +* margin, bottom: Page Location Traps. + (line 10440) +* margin, left (po): Line Layout. (line 6870) +* margin, right: Line Layout. (line 6881) +* margin, top: Page Location Traps. + (line 10440) +* mark, high-water, register (.h): Diversions. (line 11007) +* marker, footnote [ms]: ms Footnotes. (line 2920) +* marking vertical page location (mk): Page Motions. (line 9868) +* maximum operator: Numeric Expressions. + (line 4407) +* maximum value representable with Roman numerals: Assigning Register Formats. + (line 5465) +* mdoc macros: mdoc. (line 1552) +* me macro package: me. (line 1559) +* measurement units: Measurements. (line 4232) +* measurements: Measurements. (line 4232) +* measurements, specifying safely: Default Units. (line 4341) +* metrics, font: Using Fonts. (line 7295) +* minimal inter-word spacing: Manipulating Filling and Adjustment. + (line 5891) +* minimum operator: Numeric Expressions. + (line 4407) +* minimum value representable with Roman numerals: Assigning Register Formats. + (line 5465) +* minor macro package: Major Macro Packages. + (line 1408) +* minor version number register (.y): Built-in Registers. + (line 5563) +* minutes, current time (minutes): Built-in Registers. + (line 5583) +* mm macro package: mm. (line 1571) +* mode for constant glyph space (cs): Artificial Fonts. (line 8241) +* mode, compatibility: Compatibility Mode. + (line 12404) +* mode, compatibility, and parameters: Gtroff Internals. (line 12054) +* mode, copy: Copy Mode. (line 9699) +* mode, copy <1>: Copy Mode. (line 9699) +* mode, copy, and cf request: I/O. (line 11521) +* mode, copy, and device request: Postprocessor Access. + (line 11744) +* mode, copy, and length request: Strings. (line 8909) +* mode, copy, and macro parameters: Parameters. (line 9616) +* mode, copy, and output request: Diversions. (line 11106) +* mode, copy, and trf request: I/O. (line 11521) +* mode, copy, and write request: I/O. (line 11683) +* mode, copy, and writec request: I/O. (line 11683) +* mode, copy, and writem request: I/O. (line 11697) +* mode, copy, and \!: Diversions. (line 11074) +* mode, copy, and \?: Operators in Conditionals. + (line 9116) +* mode, copy, and \? <1>: Diversions. (line 11074) +* mode, copy, and \a: Leaders. (line 6658) +* mode, copy, and \t: Tabs and Fields. (line 6485) +* mode, copy, and \V: I/O. (line 11721) +* mode, fill (fi), enabling: Manipulating Filling and Adjustment. + (line 5685) +* mode, fill, and break warnings: Warnings. (line 12262) +* mode, fill, and inter-sentence space: Manipulating Filling and Adjustment. + (line 5898) +* mode, fill, and \c: Line Continuation. (line 7054) +* mode, fill, disabling: Manipulating Filling and Adjustment. + (line 5692) +* mode, interpretation: Copy Mode. (line 9708) +* mode, line-tabs: Tabs and Fields. (line 6615) +* mode, no-fill: Manipulating Filling and Adjustment. + (line 5692) +* mode, no-fill, and \c: Line Continuation. (line 7062) +* mode, no-space (ns): Manipulating Spacing. + (line 6456) +* mode, nroff: troff and nroff Modes. + (line 6813) +* mode, safer: Groff Options. (line 707) +* mode, safer <1>: Macro Directories. (line 910) +* mode, safer <2>: Built-in Registers. + (line 5555) +* mode, safer <3>: I/O. (line 11504) +* mode, safer <4>: I/O. (line 11616) +* mode, safer <5>: I/O. (line 11638) +* mode, safer <6>: I/O. (line 11677) +* mode, safer <7>: Safer Mode. (line 12395) +* mode, troff: troff and nroff Modes. + (line 6813) +* mode, unsafe: Groff Options. (line 783) +* mode, unsafe <1>: Macro Directories. (line 910) +* mode, unsafe <2>: Built-in Registers. + (line 5555) +* mode, unsafe <3>: I/O. (line 11504) +* mode, unsafe <4>: I/O. (line 11616) +* mode, unsafe <5>: I/O. (line 11638) +* mode, unsafe <6>: I/O. (line 11677) +* modifying requests: Control Characters. + (line 4765) +* modulus: Numeric Expressions. + (line 4359) +* mom macro package: mom. (line 1581) +* month of the year register (mo): Built-in Registers. + (line 5595) +* motion operators: Numeric Expressions. + (line 4457) +* motion quanta: Motion Quanta. (line 4292) +* motion quantum, horizontal: DESC File Format. (line 13445) +* motion quantum, horizontal, register (.H): Motion Quanta. (line 4299) +* motion quantum, vertical: DESC File Format. (line 13553) +* motion, horizontal (\h): Page Motions. (line 9982) +* motion, vertical (\v): Page Motions. (line 9938) +* motions, page: Page Motions. (line 9863) +* mounting a font (fp): Font Positions. (line 7552) +* mounting position: Using Fonts. (line 7295) +* mounting position <1>: Using Fonts. (line 7295) +* mounting, font, automatic: Selecting Fonts. (line 7365) +* ms macros: ms. (line 1603) +* ms macros, accent marks: ms Legacy Features. + (line 3405) +* ms macros, body text: ms Body Text. (line 2231) +* ms macros, creating table of contents: ms TOC. (line 3139) +* ms macros, displays: ms keeps and displays. + (line 2743) +* ms macros, document control settings: ms Document Control Settings. + (line 1794) +* ms macros, document description: ms Document Description Macros. + (line 2132) +* ms macros, equations: ms Insertions. (line 2844) +* ms macros, figures: ms Insertions. (line 2844) +* ms macros, footers: ms Headers and Footers. + (line 3052) +* ms macros, footnotes: ms Footnotes. (line 2920) +* ms macros, fractional type sizes in: Differences from AT&T ms. + (line 3315) +* ms macros, general structure: ms Document Structure. + (line 1747) +* ms macros, groff differences from AT&T: Differences from AT&T ms. + (line 3276) +* ms macros, headers: ms Headers and Footers. + (line 3052) +* ms macros, headings: Headings in ms. (line 2352) +* ms macros, keeps: ms keeps and displays. + (line 2743) +* ms macros, language: ms language and localization. + (line 3003) +* ms macros, lists: Lists in ms. (line 2582) +* ms macros, localization: ms language and localization. + (line 3003) +* ms macros, margins: ms Margins. (line 3109) +* ms macros, multiple columns: ms Multiple Columns. + (line 3117) +* ms macros, naming conventions: ms Naming Conventions. + (line 3520) +* ms macros, nested lists: Indented regions in ms. + (line 2713) +* ms macros, obtaining typographical symbols: Typographical symbols in ms. + (line 2261) +* ms macros, page layout: ms Page Layout. (line 3045) +* ms macros, paragraph handling: Paragraphs in ms. (line 2277) +* ms macros, references: ms Insertions. (line 2844) +* ms macros, special characters: ms Legacy Features. + (line 3405) +* ms macros, strings: ms Legacy Features. + (line 3405) +* ms macros, tables: ms Insertions. (line 2844) +* ms macros, text settings: Text settings in ms. + (line 2239) +* multi-file documents: Debugging. (line 12103) +* multi-line strings: Strings. (line 8853) +* multi-page table example [ms]: ms Insertions. (line 2886) +* multiple columns [ms]: ms Multiple Columns. + (line 3117) +* multiplication: Numeric Expressions. + (line 4359) +* n scaling unit: Measurements. (line 4281) +* name space, common, of macros, diversions, and strings: Identifiers. + (line 4668) +* name, background color, register (.M): Colors. (line 8765) +* name, fill color, register (.M): Colors. (line 8765) +* name, stroke color, register (.m): Colors. (line 8744) +* named character (\C): Using Symbols. (line 7793) +* names, long: Compatibility Mode. + (line 12404) +* naming conventions, ms macros: ms Naming Conventions. + (line 3520) +* ne request, and the .trunc register: Page Location Traps. + (line 10587) +* ne request, comparison with sv: Page Control. (line 7230) +* negating register values: Setting Registers. (line 5289) +* negation: Numeric Expressions. + (line 4365) +* nested assignments: Interpolating Registers. + (line 5340) +* nested diversions: Diversions. (line 11000) +* nested lists [ms]: Indented regions in ms. + (line 2713) +* nesting level, suppression, register: Suppressing Output. + (line 11463) +* new page (bp): Page Control. (line 7178) +* newline character, and translations: Character Translations. + (line 6751) +* newline character, in strings, escaping: Strings. (line 8853) +* newline, as delimiter: Delimiters. (line 5076) +* newline, final, stripping in diversions: Punning Names. (line 11246) +* next file, processing (nx): I/O. (line 11553) +* next free font position register (.fp): Font Positions. (line 7589) +* next page number register (.pn): Page Layout. (line 7112) +* next page number, configuring (pn): Page Layout. (line 7107) +* nf request, causing implicit break: Manipulating Filling and Adjustment. + (line 5624) +* nl register, and .d: Diversions. (line 11000) +* nl register, difference from .h: Diversions. (line 11020) +* nm request, using + and - with: Numeric Expressions. + (line 4463) +* no-break control character ('): Requests and Macros. + (line 3813) +* no-break control character, changing (c2): Control Characters. + (line 4738) +* no-fill mode: Manipulating Filling and Adjustment. + (line 5692) +* no-fill mode, and \c: Line Continuation. (line 7062) +* no-space mode (ns): Manipulating Spacing. + (line 6456) +* node, output: Gtroff Internals. (line 11970) +* non-printing break point (\:): Manipulating Hyphenation. + (line 6008) +* nr request, and warnings: Warnings. (line 12313) +* nr request, using + and - with: Numeric Expressions. + (line 4463) +* nroff mode: troff and nroff Modes. + (line 6813) +* number formats, assigning to register (af): Assigning Register Formats. + (line 5413) +* number of registers register (.R): Built-in Registers. + (line 5547) +* number, input line, setting (lf): Debugging. (line 12103) +* number, page, next, configuring (pn): Page Layout. (line 7107) +* numbered glyph (\N): Character Translations. + (line 6741) +* numbered glyph (\N) <1>: Using Symbols. (line 7810) +* numbered list, example markup [ms]: Lists in ms. (line 2609) +* numbers, line, printing (nm): Miscellaneous. (line 11798) +* numeral-width space (\0): Page Motions. (line 10014) +* numerals, as delimiters: Delimiters. (line 5090) +* numerals, Roman: Assigning Register Formats. + (line 5433) +* numeric expression, valid: Numeric Expressions. + (line 4522) +* numeric expressions: Numeric Expressions. + (line 4348) +* object creation: Writing Macros. (line 9558) +* offset, page: Page Geometry. (line 4193) +* offset, page (po): Line Layout. (line 6870) +* open request, and safer mode: Groff Options. (line 707) +* opena request, and safer mode: Groff Options. (line 707) +* opening brace escape sequence (\}): Conditional Blocks. + (line 9250) +* opening file (open): I/O. (line 11671) +* operator, scaling: Numeric Expressions. + (line 4390) +* operators, arithmetic: Numeric Expressions. + (line 4359) +* operators, as delimiters: Delimiters. (line 5092) +* operators, comparison: Numeric Expressions. + (line 4416) +* operators, extremum (>?, <?): Numeric Expressions. + (line 4407) +* operators, logical: Numeric Expressions. + (line 4422) +* operators, motion: Numeric Expressions. + (line 4457) +* operators, unary arithmetic: Numeric Expressions. + (line 4365) +* optical size of a font: Selecting Fonts. (line 7421) +* options: Groff Options. (line 478) +* order of evaluation in expressions: Numeric Expressions. + (line 4446) +* ordinary character: Identifiers. (line 4577) +* orientation, landscape: Paper Format. (line 972) +* orphan: Page Control. (line 7222) +* orphan lines, preventing with ne: Page Control. (line 7195) +* os request, and no-space mode: Page Control. (line 7233) +* outlined circle, drawing (\D'c ...'): Drawing Geometric Objects. + (line 10230) +* outlined ellipse, drawing (\D'e ...'): Drawing Geometric Objects. + (line 10237) +* outlined polygon, drawing (\D'p ...'): Drawing Geometric Objects. + (line 10269) +* output and input requests: I/O. (line 11469) +* output comparison operator: Operators in Conditionals. + (line 9080) +* output device name string (.T): Groff Options. (line 772) +* output device name string (.T) <1>: Strings. (line 8787) +* output device name string (.T), in other implementations: Other Differences. + (line 12564) +* output device usage register (.T): Groff Options. (line 772) +* output device usage register (.T), incompatibility with AT&T troff: Other Differences. + (line 12574) +* output devices: Output Device Intro. + (line 359) +* output encoding, ASCII: Groff Options. (line 743) +* output encoding, code page 1047: Groff Options. (line 755) +* output encoding, EBCDIC: Groff Options. (line 755) +* output encoding, ISO 646: Groff Options. (line 743) +* output encoding, Latin-1 (ISO 8859-1): Groff Options. (line 747) +* output encoding, UTF-8: Groff Options. (line 751) +* output glyphs, and input characters, compatibility with AT&T troff: Other Differences. + (line 12609) +* output line break: Breaking. (line 3725) +* output line number register (ln): Miscellaneous. (line 11820) +* output line properties: Manipulating Filling and Adjustment. + (line 5644) +* output line, continuation (\c): Line Continuation. (line 7048) +* output line, horizontal position, register (.k): Page Motions. + (line 10093) +* output node: Gtroff Internals. (line 11970) +* output request, and copy mode: Diversions. (line 11106) +* output request, and \!: Diversions. (line 11106) +* output, filling, disablement of (nf): Manipulating Filling and Adjustment. + (line 5692) +* output, filling, enablement of (fi): Manipulating Filling and Adjustment. + (line 5685) +* output, flush (fl): Debugging. (line 12167) +* output, gtroff: gtroff Output. (line 12680) +* output, intermediate: gtroff Output. (line 12690) +* output, suppressing (\O): Suppressing Output. + (line 11410) +* output, transparent (cf, trf): I/O. (line 11521) +* output, transparent (\!, \?): Diversions. (line 11066) +* output, transparent, incompatibilities with AT&T troff: Other Differences. + (line 12636) +* output, troff: gtroff Output. (line 12690) +* overlapping characters: Using Symbols. (line 7882) +* overstriking glyphs (\o): Page Motions. (line 10097) +* p scaling unit: Measurements. (line 4255) +* P scaling unit: Measurements. (line 4259) +* package, macro: Macro Packages. (line 3963) +* package, macro, auxiliary: Major Macro Packages. + (line 1408) +* package, macro, full-service: Major Macro Packages. + (line 1397) +* package, macro, introduction: Macro Package Intro. + (line 316) +* package, macro, major: Major Macro Packages. + (line 1394) +* package, macro, minor: Major Macro Packages. + (line 1408) +* package, macro, search path: Macro Directories. (line 900) +* package, package, structuring the source of: Invoking Requests. + (line 4803) +* padding character, for fields (fc): Fields. (line 6692) +* page: Page Geometry. (line 4175) +* page break: Page Geometry. (line 4208) +* page break <1>: Page Control. (line 7170) +* page break <2>: The Implicit Page Trap. + (line 10638) +* page break (introduction): Basics. (line 1185) +* page break, conditional (ne): Page Control. (line 7195) +* page break, final: End-of-input Traps. + (line 10834) +* page break, prevented by vpt: Vertical Position Traps. + (line 10414) +* page control: Page Control. (line 7170) +* page ejection: Page Geometry. (line 4208) +* page ejection <1>: Page Control. (line 7170) +* page ejection <2>: The Implicit Page Trap. + (line 10638) +* page ejection status register (.pe): Page Location Traps. + (line 10598) +* page ejection, of final page: End-of-input Traps. + (line 10834) +* page ejection, prevented by vpt: Vertical Position Traps. + (line 10414) +* page footers: Page Location Traps. + (line 10440) +* page headers: Page Location Traps. + (line 10440) +* page layout: Page Layout. (line 7087) +* page layout [ms]: ms Page Layout. (line 3045) +* page length register (.p): Page Layout. (line 7101) +* page length, configuring (pl): Page Layout. (line 7093) +* page location traps: Page Location Traps. + (line 10420) +* page location traps, debugging: Page Location Traps. + (line 10476) +* page location, vertical, marking (mk): Page Motions. (line 9868) +* page location, vertical, returning to marked (rt): Page Motions. + (line 9868) +* page motions: Page Motions. (line 9863) +* page number character (%): Page Layout. (line 7120) +* page number character, changing (pc): Page Layout. (line 7149) +* page number register (%): Page Control. (line 7188) +* page number, configuring next (pn): Page Layout. (line 7107) +* page number, next, register (.pn): Page Layout. (line 7112) +* page offset: Page Geometry. (line 4193) +* page offset (po): Line Layout. (line 6870) +* page orientation, landscape: Paper Format. (line 972) +* page, geometry of: Page Geometry. (line 4162) +* page, new (bp): Page Control. (line 7178) +* paper format: Paper Format. (line 972) +* paper size: Paper Format. (line 972) +* paragraphs: Paragraphs. (line 1220) +* parameter count register (.$): Parameters. (line 9594) +* parameters: Parameters. (line 9586) +* parameters, and compatibility mode: Gtroff Internals. (line 12054) +* parameters, macro (\$): Parameters. (line 9616) +* parentheses: Numeric Expressions. + (line 4446) +* partially collected line: Manipulating Filling and Adjustment. + (line 5644) +* path, for font files: Font Directories. (line 942) +* path, for tmac files: Macro Directories. (line 900) +* pattern files, for hyphenation: Manipulating Hyphenation. + (line 6116) +* patterns for hyphenation (hpf): Manipulating Hyphenation. + (line 6170) +* pending output line: Manipulating Filling and Adjustment. + (line 5644) +* pi request, and groff: I/O. (line 11629) +* pi request, and safer mode: Groff Options. (line 707) +* pi request, disabled by default: Safer Mode. (line 12395) +* pica scaling unit (P): Measurements. (line 4259) +* PID of GNU troff register ($$): Built-in Registers. + (line 5571) +* pile, glyph (\b): Drawing Geometric Objects. + (line 10308) +* pl request, using + and - with: Numeric Expressions. + (line 4463) +* plain text approximation output register (.A): Groff Options. + (line 521) +* plain text approximation output register (.A) <1>: Built-in Registers. + (line 5527) +* planting a trap: Traps. (line 10393) +* platform-specific directory: Macro Directories. (line 915) +* pm request, incompatibilities with AT&T troff: Other Differences. + (line 12600) +* pn request, using + and - with: Numeric Expressions. + (line 4463) +* PNG image generation from PostScript: DESC File Format. (line 13449) +* po request, using + and - with: Numeric Expressions. + (line 4463) +* point scaling unit (p): Measurements. (line 4255) +* point size registers (.s, .ps): Changing the Type Size. + (line 8480) +* point size registers, last-requested (.psr, .sr): Using Fractional Type Sizes. + (line 8638) +* point sizes, changing (ps, \s): Changing the Type Size. + (line 8466) +* point sizes, fractional: Using Fractional Type Sizes. + (line 8597) +* point sizes, fractional <1>: Other Differences. (line 12587) +* polygon, filled, drawing (\D'P ...'): Drawing Geometric Objects. + (line 10275) +* polygon, outlined, drawing (\D'p ...'): Drawing Geometric Objects. + (line 10269) +* polygon, solid, drawing (\D'P ...'): Drawing Geometric Objects. + (line 10275) +* polygon, stroked, drawing (\D'p ...'): Drawing Geometric Objects. + (line 10269) +* position of lowest text line (.h): Diversions. (line 11007) +* position, absolute (sic) operator (|): Numeric Expressions. + (line 4471) +* position, drawing: Page Geometry. (line 4181) +* position, horizontal input line, saving (\k): Page Motions. + (line 10084) +* position, horizontal, in input line, register (hp): Page Motions. + (line 10090) +* position, horizontal, in output line, register (.k): Page Motions. + (line 10093) +* position, mounting: Using Fonts. (line 7295) +* position, vertical, in diversion, register (.d): Diversions. + (line 11000) +* positions, font: Font Positions. (line 7540) +* post-vertical line spacing: Changing the Vertical Spacing. + (line 8572) +* post-vertical line spacing register (.pvs): Changing the Vertical Spacing. + (line 8584) +* post-vertical line spacing, changing (pvs): Changing the Vertical Spacing. + (line 8584) +* postprocessor access: Postprocessor Access. + (line 11729) +* postprocessors: Output Device Intro. + (line 359) +* PostScript, bounding box: Miscellaneous. (line 11949) +* PostScript, PNG image generation: DESC File Format. (line 13449) +* prefix, for commands: Environment. (line 835) +* preprocessors: Preprocessor Intro. + (line 328) +* previous font, selecting (ft): Selecting Fonts. (line 7352) +* previous font, selecting (\f[], \fP): Selecting Fonts. (line 7378) +* previous line length (.n): Environments. (line 11403) +* print current page register (.P): Groff Options. (line 670) +* printing backslash (\\, \e, \E, \[rs]): Other Differences. + (line 12636) +* printing line numbers (nm): Miscellaneous. (line 11798) +* printing to stderr (tm, tm1, tmc): Debugging. (line 12117) +* printing, zero-width (\z, \Z): Page Motions. (line 10102) +* printing, zero-width (\z, \Z) <1>: Page Motions. (line 10107) +* process ID of GNU troff register ($$): Built-in Registers. + (line 5571) +* processing next file (nx): I/O. (line 11553) +* productive input line: Manipulating Filling and Adjustment. + (line 5797) +* properties of characters (cflags): Using Symbols. (line 7846) +* properties of glyphs (cflags): Using Symbols. (line 7846) +* properties of output lines: Manipulating Filling and Adjustment. + (line 5644) +* ps request, and constant glyph space mode: Artificial Fonts. + (line 8241) +* ps request, incompatibilities with AT&T troff: Other Differences. + (line 12587) +* ps request, using + and - with: Numeric Expressions. + (line 4463) +* ps request, with fractional type sizes: Using Fractional Type Sizes. + (line 8604) +* pso request, and safer mode: Groff Options. (line 707) +* pvs request, using + and - with: Numeric Expressions. + (line 4463) +* quanta, motion: Motion Quanta. (line 4292) +* quantum, horizontal motion: DESC File Format. (line 13445) +* quantum, vertical motion: DESC File Format. (line 13553) +* radicalex glyph, and cflags: Using Symbols. (line 7882) +* ragged-left text: Manipulating Filling and Adjustment. + (line 5723) +* ragged-right text: Manipulating Filling and Adjustment. + (line 5720) +* rc request, and glyph definitions: Using Symbols. (line 7948) +* read-only register removal, incompatibility with AT&T troff: Other Differences. + (line 12571) +* read-only register, changing format: Assigning Register Formats. + (line 5472) +* reading from standard input (rd): I/O. (line 11558) +* recursive macros: while. (line 9359) +* refer, and macro names starting with [ or ]: Identifiers. (line 4623) +* reference, gtroff: GNU troff Reference. + (line 3549) +* references [ms]: ms Insertions. (line 2844) +* register format, in expressions: Assigning Register Formats. + (line 5484) +* register, assigning number format to (af): Assigning Register Formats. + (line 5413) +* register, built-in, removing: Built-in Registers. + (line 5513) +* register, creating alias for (aln): Setting Registers. (line 5323) +* register, format (\g): Assigning Register Formats. + (line 5479) +* register, read-only, removal, incompatibility with AT&T troff: Other Differences. + (line 12571) +* register, removing (rr): Setting Registers. (line 5312) +* register, removing alias for (rr): Setting Registers. (line 5329) +* register, renaming (rnn): Setting Registers. (line 5318) +* registers: Registers. (line 5210) +* registers, built-in: Built-in Registers. + (line 5508) +* registers, dumping (pnr): Debugging. (line 12158) +* registers, interpolating (\n): Interpolating Registers. + (line 5335) +* registers, number of, register (.R): Built-in Registers. + (line 5547) +* registers, setting (nr, \R): Setting Registers. (line 5219) +* removal of read-only registers, incompatibility with AT&T troff: Other Differences. + (line 12571) +* removing a built-in register: Built-in Registers. + (line 5513) +* removing a register (rr): Setting Registers. (line 5312) +* removing alias for register (rr): Setting Registers. (line 5329) +* removing alias, for diversion (rm): Strings. (line 9007) +* removing alias, for macro (rm): Strings. (line 9007) +* removing alias, for string (rm): Strings. (line 9007) +* removing diversion (rm): Strings. (line 8967) +* removing glyph definition (rchar, rfschar): Using Symbols. + (line 8005) +* removing macro (rm): Strings. (line 8967) +* removing request (rm): Strings. (line 8967) +* removing string (rm): Strings. (line 8967) +* renaming a register (rnn): Setting Registers. (line 5318) +* renaming diversion (rn): Strings. (line 8964) +* renaming macro (rn): Strings. (line 8964) +* renaming request (rn): Strings. (line 8964) +* renaming string (rn): Strings. (line 8964) +* renditions, graphic: Using Fonts. (line 7323) +* request: Requests and Macros. + (line 3813) +* request <1>: Formatter Instructions. + (line 4708) +* request arguments: Invoking Requests. (line 4789) +* request arguments, and compatibility mode: Gtroff Internals. + (line 12054) +* request arguments, and tabs: Invoking Requests. (line 4789) +* request, removing (rm): Strings. (line 8967) +* request, renaming (rn): Strings. (line 8964) +* request, undefined: Comments. (line 5150) +* requests for drawing: Drawing Geometric Objects. + (line 10130) +* requests for input and output: I/O. (line 11469) +* requests, intercepting: Control Characters. + (line 4765) +* requests, invoking: Invoking Requests. (line 4781) +* requests, modifying: Control Characters. + (line 4765) +* resolution, device: Page Geometry. (line 4169) +* resolution, device <1>: DESC File Format. (line 13506) +* resolution, device, obtaining in the formatter: Measurements. + (line 4240) +* resolution, horizontal: DESC File Format. (line 13445) +* resolution, horizontal, register (.H): Motion Quanta. (line 4299) +* resolution, vertical: DESC File Format. (line 13553) +* returning to marked vertical page location (rt): Page Motions. + (line 9868) +* revision number register (.Y): Built-in Registers. + (line 5567) +* right margin: Line Layout. (line 6881) +* right-aligning lines (introduction): Basics. (line 1182) +* right-justifying (rj): Manipulating Filling and Adjustment. + (line 5866) +* right-justifying lines (introduction): Basics. (line 1182) +* rivers: Other Differences. (line 12552) +* rj request, causing implicit break: Manipulating Filling and Adjustment. + (line 5624) +* rn glyph, and cflags: Using Symbols. (line 7882) +* roman glyph, correction after italic glyph (\/): Italic Corrections. + (line 8328) +* roman glyph, correction before italic glyph (\,): Italic Corrections. + (line 8338) +* Roman numerals: Assigning Register Formats. + (line 5433) +* Roman numerals, extrema (maximum and minimum): Assigning Register Formats. + (line 5465) +* rq glyph, at end of sentence: Sentences. (line 3663) +* rq glyph, at end of sentence <1>: Using Symbols. (line 7892) +* rt request, using + and - with: Numeric Expressions. + (line 4463) +* ru glyph, and cflags: Using Symbols. (line 7882) +* running system commands: I/O. (line 11633) +* s scaling unit: Using Fractional Type Sizes. + (line 8604) +* safer mode: Groff Options. (line 707) +* safer mode <1>: Macro Directories. (line 910) +* safer mode <2>: Built-in Registers. + (line 5555) +* safer mode <3>: I/O. (line 11504) +* safer mode <4>: I/O. (line 11616) +* safer mode <5>: I/O. (line 11638) +* safer mode <6>: I/O. (line 11677) +* safer mode <7>: Safer Mode. (line 12395) +* saving horizontal input line position (\k): Page Motions. (line 10084) +* scaling indicator: Measurements. (line 4232) +* scaling operator: Numeric Expressions. + (line 4390) +* scaling unit c: Measurements. (line 4252) +* scaling unit f: Colors. (line 8712) +* scaling unit i: Measurements. (line 4249) +* scaling unit m: Measurements. (line 4277) +* scaling unit M: Measurements. (line 4287) +* scaling unit n: Measurements. (line 4281) +* scaling unit p: Measurements. (line 4255) +* scaling unit P: Measurements. (line 4259) +* scaling unit s: Using Fractional Type Sizes. + (line 8604) +* scaling unit u: Measurements. (line 4245) +* scaling unit v: Measurements. (line 4284) +* scaling unit z: Using Fractional Type Sizes. + (line 8604) +* searching fonts: Font Directories. (line 934) +* searching macros: Macro Directories. (line 898) +* seconds, current time (seconds): Built-in Registers. + (line 5580) +* selecting the previous font (ft): Selecting Fonts. (line 7352) +* sentence space: Sentences. (line 3619) +* sentence space size register (.sss): Manipulating Filling and Adjustment. + (line 5887) +* sentences: Sentences. (line 3607) +* sequence, escape: Formatter Instructions. + (line 4714) +* setting diversion trap (dt): Diversion Traps. (line 10668) +* setting end-of-input trap (em): End-of-input Traps. + (line 10807) +* setting input line number (lf): Debugging. (line 12103) +* setting input line trap (it, itc): Input Line Traps. (line 10680) +* setting registers (nr, \R): Setting Registers. (line 5219) +* setting the page length (pl): Page Layout. (line 7093) +* setting up an abstract font style (sty): Font Families. (line 7505) +* shc request, and translations: Character Translations. + (line 6755) +* site-local directory: Macro Directories. (line 915) +* site-local directory <1>: Font Directories. (line 957) +* size of sentence space register (.sss): Manipulating Filling and Adjustment. + (line 5887) +* size of word space register (.ss): Manipulating Filling and Adjustment. + (line 5887) +* size, optical, of a font: Selecting Fonts. (line 7421) +* size, paper: Paper Format. (line 972) +* size, size: Manipulating Type Size and Vertical Spacing. + (line 8438) +* sizes, fractional: Other Differences. (line 12587) +* sizes, fractional type: Using Fractional Type Sizes. + (line 8597) +* skew, of last glyph (.csk): Environments. (line 11388) +* slant, font, changing (\S): Artificial Fonts. (line 8161) +* soft hyphen character, setting (shc): Manipulating Hyphenation. + (line 6032) +* soft hyphen glyph (hy): Manipulating Hyphenation. + (line 6032) +* solid circle, drawing (\D'C ...'): Drawing Geometric Objects. + (line 10234) +* solid ellipse, drawing (\D'E ...'): Drawing Geometric Objects. + (line 10241) +* solid polygon, drawing (\D'P ...'): Drawing Geometric Objects. + (line 10275) +* SOURCE_DATE_EPOCH, environment variable: Environment. (line 882) +* sp request, and no-space mode: Manipulating Spacing. + (line 6456) +* sp request, causing implicit break: Manipulating Filling and Adjustment. + (line 5624) +* space between sentences: Sentences. (line 3619) +* space between sentences register (.sss): Manipulating Filling and Adjustment. + (line 5887) +* space between words register (.ss): Manipulating Filling and Adjustment. + (line 5887) +* space character, as delimiter: Delimiters. (line 5094) +* space characters, in expressions: Numeric Expressions. + (line 4538) +* space, between sentences: Manipulating Filling and Adjustment. + (line 5893) +* space, between words: Manipulating Filling and Adjustment. + (line 5891) +* space, discardable, horizontal: Manipulating Filling and Adjustment. + (line 5914) +* space, hair (\^): Page Motions. (line 10008) +* space, horizontal (\h): Page Motions. (line 9982) +* space, horizontal, unformatting: Punning Names. (line 11246) +* space, thin (\|): Page Motions. (line 10003) +* space, unbreakable (\~): Manipulating Filling and Adjustment. + (line 5671) +* space, unbreakable and unadjustable (\<SP>): Page Motions. + (line 9998) +* space, vertical, unit (v): Measurements. (line 4284) +* space, width of a digit (numeral) (\0): Page Motions. (line 10014) +* spaces with ds: Strings. (line 8844) +* spaces, in a macro argument: Calling Macros. (line 4856) +* spaces, leading and trailing: Breaking. (line 3757) +* spacing (introduction): Basics. (line 1150) +* spacing, manipulating: Manipulating Spacing. + (line 6344) +* spacing, vertical: Page Geometry. (line 4202) +* spacing, vertical <1>: Manipulating Type Size and Vertical Spacing. + (line 8438) +* spacing, vertical (introduction): Basics. (line 1136) +* special characters: Sentences. (line 3663) +* special characters <1>: Character Translations. + (line 6741) +* special characters [ms]: ms Legacy Features. + (line 3405) +* special characters, list of (groff_char(7) man page): Using Symbols. + (line 7675) +* special font: Using Fonts. (line 7280) +* special fonts: Using Symbols. (line 7612) +* special fonts <1>: Special Fonts. (line 8092) +* special fonts <2>: Font Description File Format. + (line 13618) +* special fonts, emboldening: Artificial Fonts. (line 8230) +* special request, and font translations: Selecting Fonts. (line 7406) +* special request, and glyph search order: Using Symbols. (line 7612) +* spline, drawing (\D'~ ...'): Drawing Geometric Objects. + (line 10221) +* springing a trap: Traps. (line 10394) +* sqrtex glyph, and cflags: Using Symbols. (line 7882) +* ss request, incompatibilities with AT&T troff: Other Differences. + (line 12604) +* stack: Environments. (line 11273) +* stacking glyphs (\b): Drawing Geometric Objects. + (line 10308) +* standard input, reading from (rd): I/O. (line 11558) +* stderr, printing to (tm, tm1, tmc): Debugging. (line 12117) +* stops, tab: Tabs and Leaders. (line 3785) +* string arguments: Strings. (line 8802) +* string comparison: Operators in Conditionals. + (line 9108) +* string expansion (\*): Strings. (line 8802) +* string interpolation (\*): Strings. (line 8802) +* string, appending (as): Strings. (line 8889) +* string, creating alias for (als): Strings. (line 8972) +* string, length of (length): Strings. (line 8909) +* string, removing (rm): Strings. (line 8967) +* string, removing alias for (rm): Strings. (line 9007) +* string, renaming (rn): Strings. (line 8964) +* strings: Strings. (line 8780) +* strings [ms]: ms Legacy Features. + (line 3405) +* strings, multi-line: Strings. (line 8853) +* strings, shared name space with macros and diversions: Identifiers. + (line 4668) +* stripping final newline in diversions: Punning Names. (line 11246) +* stroke color: Colors. (line 8678) +* stroke color name register (.m): Colors. (line 8744) +* stroked circle, drawing (\D'c ...'): Drawing Geometric Objects. + (line 10230) +* stroked ellipse, drawing (\D'e ...'): Drawing Geometric Objects. + (line 10237) +* stroked polygon, drawing (\D'p ...'): Drawing Geometric Objects. + (line 10269) +* structuring source code of documents or macro packages: Invoking Requests. + (line 4803) +* sty request, and changing fonts: Selecting Fonts. (line 7352) +* sty request, and font translations: Selecting Fonts. (line 7406) +* style, font: Using Fonts. (line 7280) +* style, font, abstract: Using Fonts. (line 7302) +* style, font, abstract, setting up (sty): Font Families. (line 7505) +* styles, font: Font Families. (line 7448) +* substring (substring): Strings. (line 8927) +* subtraction: Numeric Expressions. + (line 4359) +* suppressing output (\O): Suppressing Output. + (line 11410) +* suppression nesting level register: Suppressing Output. + (line 11463) +* sv request, and no-space mode: Page Control. (line 7233) +* switching environments (ev): Environments. (line 11309) +* sy request, and safer mode: Groff Options. (line 707) +* sy request, disabled by default: Safer Mode. (line 12395) +* symbol: Using Symbols. (line 7612) +* symbol table, dumping (pm): Debugging. (line 12154) +* symbol, defining (char): Using Symbols. (line 7948) +* symbols, using: Using Symbols. (line 7600) +* system commands, running: I/O. (line 11633) +* system() return value register (systat): I/O. (line 11666) +* tab character: Tabs and Leaders. (line 3785) +* tab character encoding: Tabs and Fields. (line 6481) +* tab character, and translations: Character Translations. + (line 6751) +* tab character, as delimiter: Delimiters. (line 5094) +* tab character, non-interpreted (\t): Tabs and Fields. (line 6485) +* tab repetition character (tc): Tabs and Fields. (line 6602) +* tab stop settings register (.tabs): Tabs and Fields. (line 6593) +* tab stops: Tabs and Leaders. (line 3785) +* tab stops, default: Tabs and Fields. (line 6493) +* tab, line-tabs mode: Tabs and Fields. (line 6615) +* table of contents: Table of Contents. (line 1323) +* table of contents <1>: Leaders. (line 6671) +* table of contents, creating [ms]: ms TOC. (line 3139) +* table, multi-page, example [ms]: ms Insertions. (line 2886) +* tables [ms]: ms Insertions. (line 2844) +* tabs, and fields: Tabs and Fields. (line 6481) +* tabs, and macro arguments: Invoking Requests. (line 4789) +* tabs, and request arguments: Invoking Requests. (line 4789) +* tabs, before comments: Comments. (line 5145) +* tagged paragraphs: Paragraphs. (line 1228) +* tags, paragraph: Paragraphs. (line 1228) +* terminal, conditional output for: Operators in Conditionals. + (line 9053) +* text baseline: Page Geometry. (line 4184) +* text baseline <1>: Manipulating Type Size and Vertical Spacing. + (line 8438) +* text font: Using Fonts. (line 7280) +* text line: Requests and Macros. + (line 3826) +* text line, position of lowest (.h): Diversions. (line 11007) +* text, GNU troff processing: Text. (line 3556) +* text, justifying: Manipulating Filling and Adjustment. + (line 5624) +* text, justifying (rj): Manipulating Filling and Adjustment. + (line 5866) +* thickness of lines (\D't ...'): Drawing Geometric Objects. + (line 10298) +* thin space (\|): Page Motions. (line 10003) +* three-part title (tl): Page Layout. (line 7120) +* ti request, causing implicit break: Manipulating Filling and Adjustment. + (line 5624) +* ti request, using + and - with: Numeric Expressions. + (line 4463) +* time, current, hours (hours): Built-in Registers. + (line 5586) +* time, current, minutes (minutes): Built-in Registers. + (line 5583) +* time, current, seconds (seconds): Built-in Registers. + (line 5580) +* time, formatting: I/O. (line 11656) +* title length, configuring (lt): Page Layout. (line 7137) +* title line length register (.lt): Page Layout. (line 7146) +* title line, formatting (tl): Page Layout. (line 7120) +* titles: Page Layout. (line 7115) +* tkf request, and font styles: Font Families. (line 7505) +* tkf request, and font translations: Selecting Fonts. (line 7406) +* tkf request, with fractional type sizes: Using Fractional Type Sizes. + (line 8604) +* tl request, and mc: Miscellaneous. (line 11901) +* tmac, directory: Macro Directories. (line 900) +* tmac, path: Macro Directories. (line 900) +* TMPDIR, environment variable: Environment. (line 869) +* token, input: Gtroff Internals. (line 11970) +* top margin: Page Location Traps. + (line 10440) +* top-level diversion: Diversions. (line 10930) +* top-level diversion, and bp: Page Control. (line 7183) +* top-level diversion, and \!: Diversions. (line 11098) +* top-level diversion, and \?: Diversions. (line 11103) +* tr request, and glyph definitions: Using Symbols. (line 7948) +* tr request, and soft hyphen character: Manipulating Hyphenation. + (line 6032) +* tr request, incompatibilities with AT&T troff: Other Differences. + (line 12609) +* track kerning: Ligatures and Kerning. + (line 8300) +* track kerning, activating (tkf): Ligatures and Kerning. + (line 8307) +* trailing double quotes in strings: Strings. (line 8844) +* trailing spaces in string definitions and appendments: Strings. + (line 8823) +* trailing spaces on text lines: Breaking. (line 3757) +* translations of characters: Character Translations. + (line 6722) +* transparent characters: Using Symbols. (line 7892) +* transparent dummy character (\)): Dummy Characters. (line 8407) +* transparent output (cf, trf): I/O. (line 11521) +* transparent output (\!, \?): Diversions. (line 11066) +* transparent output, incompatibilities with AT&T troff: Other Differences. + (line 12636) +* trap: Deferring Output. (line 10337) +* trap, changing location (ch): Page Location Traps. + (line 10528) +* trap, distance to next vertical position, register (.t): Page Location Traps. + (line 10520) +* trap, diversion, setting (dt): Diversion Traps. (line 10668) +* trap, end-of-input, setting (em): End-of-input Traps. + (line 10807) +* trap, implicit: The Implicit Page Trap. + (line 10638) +* trap, input line, clearing (it, itc): Input Line Traps. (line 10680) +* trap, input line, setting (it, itc): Input Line Traps. (line 10680) +* trap, planting: Traps. (line 10393) +* trap, springing: Traps. (line 10394) +* traps: Traps. (line 10387) +* traps, and diversions: Page Location Traps. + (line 10618) +* traps, blank line: Blank Line Traps. (line 10778) +* traps, diversion: Diversion Traps. (line 10663) +* traps, end-of-input: End-of-input Traps. + (line 10806) +* traps, input line: Input Line Traps. (line 10678) +* traps, input line, and interrupted lines (itc): Input Line Traps. + (line 10704) +* traps, leading space: Leading Space Traps. + (line 10788) +* traps, page location: Page Location Traps. + (line 10420) +* traps, page location, dumping (ptr): Debugging. (line 12162) +* traps, page location, listing (ptr): Debugging. (line 12162) +* traps, sprung by bp request (.pe): Page Location Traps. + (line 10598) +* traps, vertical position: Vertical Position Traps. + (line 10399) +* trf request, and copy mode: I/O. (line 11521) +* trf request, and invalid characters: I/O. (line 11533) +* trf request, causing implicit break: Manipulating Filling and Adjustment. + (line 5624) +* trin request, and asciify: Diversions. (line 11120) +* troff mode: troff and nroff Modes. + (line 6813) +* troff output: gtroff Output. (line 12690) +* truncated vertical space register (.trunc): Page Location Traps. + (line 10587) +* truncating division: Numeric Expressions. + (line 4359) +* TTY, conditional output for: Operators in Conditionals. + (line 9053) +* tutorial for macro users: Tutorial for Macro Users. + (line 1046) +* type size: Manipulating Type Size and Vertical Spacing. + (line 8438) +* type size registers (.s, .ps): Changing the Type Size. + (line 8480) +* type size registers, last-requested (.psr, .sr): Using Fractional Type Sizes. + (line 8638) +* type sizes, changing (ps, \s): Changing the Type Size. + (line 8466) +* type sizes, fractional: Using Fractional Type Sizes. + (line 8597) +* type sizes, fractional <1>: Other Differences. (line 12587) +* typeface: Using Fonts. (line 7280) +* TZ, environment variable: Environment. (line 889) +* u scaling unit: Measurements. (line 4245) +* uf request, and font styles: Font Families. (line 7505) +* ul glyph, and cflags: Using Symbols. (line 7882) +* ul request, and font translations: Selecting Fonts. (line 7406) +* Ultrix-specific man macros: Optional man extensions. + (line 1451) +* unadjustable and unbreakable space (\<SP>): Page Motions. (line 9998) +* unary arithmetic operators: Numeric Expressions. + (line 4365) +* unbreakable and unadjustable space (\<SP>): Page Motions. (line 9998) +* unbreakable space (\~): Manipulating Filling and Adjustment. + (line 5671) +* undefined identifiers: Identifiers. (line 4656) +* undefined request: Comments. (line 5150) +* underline font (uf): Artificial Fonts. (line 8206) +* underlining (ul): Artificial Fonts. (line 8180) +* underlining, continuous (cu): Artificial Fonts. (line 8202) +* unformatting diversions (asciify): Diversions. (line 11120) +* unformatting horizontal space: Punning Names. (line 11246) +* Unicode: Identifiers. (line 4581) +* Unicode <1>: Using Symbols. (line 7810) +* unit, scaling, c: Measurements. (line 4252) +* unit, scaling, f: Colors. (line 8712) +* unit, scaling, i: Measurements. (line 4249) +* unit, scaling, m: Measurements. (line 4277) +* unit, scaling, M: Measurements. (line 4287) +* unit, scaling, n: Measurements. (line 4281) +* unit, scaling, p: Measurements. (line 4255) +* unit, scaling, P: Measurements. (line 4259) +* unit, scaling, s: Using Fractional Type Sizes. + (line 8604) +* unit, scaling, u: Measurements. (line 4245) +* unit, scaling, v: Measurements. (line 4284) +* unit, scaling, z: Using Fractional Type Sizes. + (line 8604) +* units of measurement: Measurements. (line 4232) +* units, basic: Page Geometry. (line 4169) +* units, basic, conversion to: Measurements. (line 4239) +* units, default: Default Units. (line 4318) +* units, machine: Page Geometry. (line 4169) +* unnamed glyphs: Using Symbols. (line 7820) +* unnamed glyphs, accessing with \N: Font Description File Format. + (line 13639) +* unsafe mode: Groff Options. (line 783) +* unsafe mode <1>: Macro Directories. (line 910) +* unsafe mode <2>: Built-in Registers. + (line 5555) +* unsafe mode <3>: I/O. (line 11504) +* unsafe mode <4>: I/O. (line 11616) +* unsafe mode <5>: I/O. (line 11638) +* unsafe mode <6>: I/O. (line 11677) +* unstyled font: Using Fonts. (line 7280) +* up-casing a string (stringup): Strings. (line 8945) +* uppercasing a string (stringup): Strings. (line 8945) +* upright glyph, correction after oblique glyph (\/): Italic Corrections. + (line 8328) +* upright glyph, correction before oblique glyph (\,): Italic Corrections. + (line 8338) +* URLs, breaking (\:): Manipulating Hyphenation. + (line 6008) +* user's macro tutorial: Tutorial for Macro Users. + (line 1046) +* user's tutorial for macros: Tutorial for Macro Users. + (line 1046) +* using escape sequences: Using Escape Sequences. + (line 4942) +* using symbols: Using Symbols. (line 7600) +* UTF-8 output encoding: Groff Options. (line 751) +* v scaling unit: Measurements. (line 4284) +* valid numeric expression: Numeric Expressions. + (line 4522) +* value, incrementing without changing the register: Auto-increment. + (line 5403) +* variables in environment: Environment. (line 827) +* vee: Page Geometry. (line 4202) +* vee scaling unit (v): Measurements. (line 4284) +* version number, major, register (.x): Built-in Registers. + (line 5559) +* version number, minor, register (.y): Built-in Registers. + (line 5563) +* vertical drawing position (nl): Page Control. (line 7240) +* vertical line drawing (\L): Drawing Geometric Objects. + (line 10168) +* vertical line spacing register (.v): Changing the Vertical Spacing. + (line 8543) +* vertical line spacing, changing (vs): Changing the Vertical Spacing. + (line 8543) +* vertical line spacing, effective value: Changing the Vertical Spacing. + (line 8558) +* vertical motion (\v): Page Motions. (line 9938) +* vertical motion quantum: DESC File Format. (line 13553) +* vertical page location, marking (mk): Page Motions. (line 9868) +* vertical page location, returning to marked (rt): Page Motions. + (line 9868) +* vertical position in diversion register (.d): Diversions. (line 11000) +* vertical position trap enable register (.vpt): Vertical Position Traps. + (line 10407) +* vertical position traps: Vertical Position Traps. + (line 10399) +* vertical position traps, enabling (vpt): Vertical Position Traps. + (line 10407) +* vertical position, drawing (nl): Page Control. (line 7240) +* vertical resolution: DESC File Format. (line 13553) +* vertical space unit (v): Measurements. (line 4284) +* vertical spacing: Page Geometry. (line 4202) +* vertical spacing <1>: Manipulating Type Size and Vertical Spacing. + (line 8438) +* vertical spacing (introduction): Basics. (line 1136) +* warning categories: Warnings. (line 12250) +* warning level (warn): Debugging. (line 12227) +* warnings: Debugging. (line 12222) +* warnings <1>: Warnings. (line 12241) +* what is groff?: What Is groff?. (line 264) +* while: while. (line 9327) +* while request, and font translations: Selecting Fonts. (line 7406) +* while request, and the ! operator: Numeric Expressions. + (line 4365) +* while request, confusing with br: while. (line 9393) +* while request, operators to use with: Operators in Conditionals. + (line 9027) +* widow: Page Control. (line 7203) +* widow <1>: Page Control. (line 7222) +* width escape (\w): Page Motions. (line 10027) +* width, of last glyph (.w): Environments. (line 11388) +* word space size register (.ss): Manipulating Filling and Adjustment. + (line 5887) +* word, definition of: Filling. (line 3581) +* write request, and copy mode: I/O. (line 11683) +* writec request, and copy mode: I/O. (line 11683) +* writem request, and copy mode: I/O. (line 11697) +* writing macros: Writing Macros. (line 9410) +* writing to file (write, writec): I/O. (line 11683) +* year, current, register (year, yr): Built-in Registers. + (line 5598) +* z scaling unit: Using Fractional Type Sizes. + (line 8604) +* zero-width printing (\z, \Z): Page Motions. (line 10102) +* zero-width printing (\z, \Z) <1>: Page Motions. (line 10107) +* zoom factor of a font (fzoom): Selecting Fonts. (line 7421) + |