{ "mode": "info", "parameter": "groff", "section": "", "url": "https://www.chedong.com/phpMan.php/info/groff/json", "generated": "2026-11-15T15:37:48Z", "sections": { "File: groff.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)": { "content": "", "subsections": [] }, "GNU 'troff'": { "content": "* Menu:\n\n* Introduction::\n* Invoking groff::\n* Tutorial for Macro Users::\n* Major Macro Packages::\n* GNU troff Reference::\n* File Formats::\n* Copying This Manual::\n* Request Index::\n* Escape Sequence Index::\n* Operator Index::\n* Register Index::\n* Macro Index::\n* String Index::\n* File Keyword Index::\n* Program and File Index::\n* Concept Index::\n\nThis manual documents GNU 'troff' version 1.23.0.\n\nCopyright (C) 1994-2023 Free Software Foundation, Inc.\n\nPermission is granted to copy, distribute and/or modify this\ndocument under the terms of the GNU Free Documentation License,\nVersion 1.3 or any later version published by the Free Software\nFoundation; with no Invariant Sections, no Front-Cover Texts, and\nno Back-Cover Texts. A copy of the license is included in the\nsection entitled \"GNU Free Documentation License\".\n", "subsections": [] }, "File: groff.info, Node: Introduction, Next: Invoking groff, Prev: Top, Up: Top": { "content": "", "subsections": [] }, "1 Introduction": { "content": "GNU 'roff' (or 'groff') is a programming system for typesetting\ndocuments. It is highly flexible and has been used extensively for over\nthirty years.\n\n* Menu:\n\n* Background::\n* What Is groff?::\n* groff Capabilities::\n* Macro Package Intro::\n* Preprocessor Intro::\n* Output Device Intro::\n* Conventions Used in This Manual::\n* Installation::\n* Credits::\n\nFile: groff.info, Node: Background, Next: What Is groff?, Prev: Introduction, Up: Introduction\n", "subsections": [ { "name": "1.1 Background", "content": "M. Douglas McIlroy, formerly of AT&T Bell Laboratories and present at\nthe creation of the Unix operating system, offers an authoritative\nhistorical summary.\n\nThe prime reason for Unix was the desire of Ken [Thompson], Dennis\n[Ritchie], and Joe Ossanna to have a pleasant environment for\nsoftware development. The fig leaf that got the nod from ...\nmanagement was that an early use would be to develop a\n\"stand-alone\" word-processing system for use in typing pools and\nsecretarial offices. Perhaps they had in mind \"dedicated\", as\ndistinct from \"stand-alone\"; that's what eventuated in various\ncases, most notably in the legal/patent department and in the AT&T\nCEO's office.\n\nBoth those systems were targets of opportunity, not foreseen from\nthe start. When Unix was up and running on the PDP-11, Joe got\nwind of the legal department having installed a commercial word\nprocessor. He went to pitch Unix as an alternative and clinched a\ntrial by promising to make 'roff' able to number lines by tomorrow\nin order to fulfill a patent-office requirement that the commercial\nsystem did not support.\n\nModems were installed so legal-department secretaries could try the\nResearch machine. They liked it and Joe's superb customer service.\nSoon the legal department got a system of their own. Joe went on\nto create 'nroff' and 'troff'. Document preparation became a\nwidespread use of Unix, but no stand-alone word-processing system\nwas ever undertaken.\n\nA history relating 'groff' to its predecessors 'roff', 'nroff', and\n'troff' is available in the 'roff(7)' man page.\n\nFile: groff.info, Node: What Is groff?, Next: groff Capabilities, Prev: Introduction, Up: Introduction\n" }, { "name": "1.2 What Is 'groff'?", "content": "'groff' (GNU 'roff') is a typesetting system that reads plain text input\nfiles that include formatting commands to produce output in PostScript,\nPDF, HTML, DVI, or other formats, or for display to a terminal." } ] }, "Formatting commands can be low-level typesetting primitives, macros from": { "content": "a supplied package, or user-defined macros. All three approaches can be\ncombined.\n\nA reimplementation and extension of the typesetter from AT&T Unix,\n'groff' is present on most POSIX systems owing to its long association\nwith Unix manuals (including man pages). It and its predecessor are\nnotable for their production of several best-selling software\nengineering texts. 'groff' is capable of producing typographically\nsophisticated documents while consuming minimal system resources.\n\nFile: groff.info, Node: groff Capabilities, Next: Macro Package Intro, Prev: What Is groff?, Up: Introduction\n", "subsections": [ { "name": "1.3 'groff' Capabilities", "content": "GNU 'troff' is a typesetting document formatter; it provides a wide\nrange of low-level text and page operations within the framework of a\nprogramming language. These operations compose to generate footnotes,\ntables of contents, mathematical equations, diagrams, multi-column text,\nand other elements of typeset works. Here is a survey of formatter\nfeatures; all are under precise user control.\n\n* text filling, breaking, alignment to the left or right margin;\ncentering\n\n* adjustment of inter-word space size to justify text, and of\ninter-sentence space size to suit local style conventions\n\n* automatic and manual determination of hyphenation break points\n\n* pagination\n\n* selection of any font available to the output device\n\n* adjustment of type size and vertical spacing (or \"leading\")\n\n* configuration of line length and indentation amounts; columnation\n\n* drawing of geometric primitives (lines, arcs, polygons, circles,\n...)\n\n* setup of stroke and fill colors (where supported by the output\ndevice)\n\n* embedding of hyperlinks, images, document metadata, and other\ninclusions (where supported by the output device)\n" } ] }, "File: groff.info, Node: Macro Package Intro, Next: Preprocessor Intro, Prev: groff Capabilities, Up: Introduction": { "content": "", "subsections": [ { "name": "1.4 Macro Packages", "content": "" } ] }, "Elemental typesetting functions can be be challenging to use directly": { "content": "with complex documents. A \"macro\" facility specifies how certain\nroutine operations, such as starting paragraphs, or printing headers and\nfooters, should be performed in terms of those low-level instructions.", "subsections": [] }, "Macros can be specific to one document or collected together into a": { "content": "\"macro package\" for use by many. Several macro packages available; the\nmost widely used are provided with 'groff'. They are 'man', 'mdoc',\n'me', 'mm', 'mom', and 'ms'.\n", "subsections": [] }, "File: groff.info, Node: Preprocessor Intro, Next: Output Device Intro, Prev: Macro Package Intro, Up: Introduction": { "content": "", "subsections": [ { "name": "1.5 Preprocessors", "content": "" } ] }, "An alternative approach to complexity management, particularly when": { "content": "constructing tables, setting mathematics, or drawing diagrams, lies in\npreprocessing. A \"preprocessor\" employs a domian-specific language to\nease the generation of tables, equations, and so forth in terms that are\nconvenient for human entry. Each preprocessor reads a document and\ntranslates the parts of it that apply to it into GNU 'troff' input.\nCommand-line options to 'groff' tell it which preprocessors to use.\n\n'groff' provides preprocessors for laying out tables ('gtbl'),\ntypesetting equations ('geqn'), drawing diagrams ('gpic' and 'ggrn'),\ninserting bibliographic references ('grefer'), and drawing chemical\nstructures ('gchem'). An associated program that is useful when dealing\nwith preprocessors is 'gsoelim'.(1) (*note Preprocessor", "subsections": [] }, "Intro-Footnote-1::)": { "content": "'groff' also supports 'grap', a preprocessor for drawing graphs. A\nfree implementation of it can be obtained separately.\n\nUnique to 'groff' is the 'preconv' preprocessor that enables 'groff'\nto handle documents in a variety of input encodings.\n\nOther preprocessors exist, but no free implementations are known. An\nexample is 'ideal', which draws diagrams using a mathematical constraint\nlanguage.\n", "subsections": [] }, "File: groff.info, Node: Output Device Intro, Next: Installation, Prev: Preprocessor Intro, Up: Introduction": { "content": "", "subsections": [ { "name": "1.6 Output Devices", "content": "GNU 'troff''s output is in a device-independent page description\nlanguage, which is then read by an \"output driver\" that translates this\nlanguage into a file format or byte stream that a piece of (possibly\nemulated) hardware understands. 'groff' features output drivers for" } ] }, "PostScript devices, terminal emulators (and other simple typewriter-like": { "content": "machines), X11 (for previewing), TeX DVI, HP LaserJet 4/PCL5 and Canon\nLBP printers (which use CaPSL), HTML, XHTML, and PDF.\n", "subsections": [] }, "File: groff.info, Node: Conventions Used in This Manual, Next: Credits, Prev: Installation, Up: Introduction": { "content": "", "subsections": [ { "name": "1.8 Conventions Used in This Manual", "content": "We apply the term \"groff\" to the language documented here, the GNU\nimplementation of the overall system, the project that develops that\nsystem, and the command of that name. In the first sense, 'groff' is an\nextended dialect of the 'roff' language, for which many similar\nimplementations exist.\n\nThe 'roff' language features several major categories for which many\nitems are predefined. Presentations of these items feature the form in\nwhich the item is most commonly used on the left, and, aligned to the\nright margin, the name of the category in brackets.\n\n-- Register: \\n[example]\nThe register 'example' is one that that 'groff' doesn't\npredefine. You can create it yourself, though; see *note Setting\nRegisters::.\n\nTo make this document useful as a reference and not merely amiable\nbedtime reading, we tend to present these syntax items in exhaustive\ndetail when they arise. References to topics discussed later in the\ntext are frequent; skip material you don't understand yet.\n\nWe use Texinfo's \"result\" (=>) and error-> notations to present\noutput written to the standard output and standard error streams,\nrespectively. Diagnostic messages from the GNU 'troff' formatter and\nother programs are examples of the latter, but the formatter can also be\ndirected to write user-specified messages to the standard error stream." } ] }, "The notation then serves to identify the output stream and does not": { "content": "necessarily mean that an error has occurred.(1) (*note Conventions Used\nin This Manual-Footnote-1::)\n\n$ echo \"Twelve o'clock and\" | groff -Tascii | sed '/^$/d'\n=> Twelve o'clock and\n$ echo '.tm all is well.' | groff > /dev/null\nerror-> all is well.\n\nSometimes we use => somewhat abstractly to represent formatted text\nthat you will need to use a PostScript or PDF viewer program (or a\nprinter) to observe. While arguably an abuse of notation, we think this\npreferable to requiring the reader to understand the syntax of these\npage description languages.\n\nWe also present diagnostic messages in an abbreviated form, often\nomitting the name of the program issuing them, the input file name, and\nline number or other positional information when such data do not serve\nto illuminate the topic under discussion.\n\nMost examples are of 'roff' language input that would be placed in a\ntext file. Occasionally, we start an example with a '$' character to\nindicate a shell prompt, as seen above.\n\nYou are encouraged to try the examples yourself, and to alter them to\nbetter learn 'groff''s behavior. Our examples frequently need to direct\nthe formatter to set a line length (with '.ll') that will fit within the\npage margins of this manual. We mention this so that you know why it is\nthere before we discuss the 'll' request formally.(2) (*note", "subsections": [] }, "Conventions Used in This Manual-Footnote-2::)": { "content": "", "subsections": [] }, "File: groff.info, Node: Installation, Next: Conventions Used in This Manual, Prev: Output Device Intro, Up: Introduction": { "content": "", "subsections": [ { "name": "1.7 Installation", "content": "" } ] }, "Locate installation instructions in the files 'INSTALL',": { "content": "'INSTALL.extra', and 'INSTALL.REPO' in the 'groff' source distribution.\nBeing a GNU project, 'groff' supports the familiar './configure && make'\ncommand sequence.\n", "subsections": [] }, "File: groff.info, Node: Credits, Prev: Conventions Used in This Manual, Up: Introduction": { "content": "", "subsections": [ { "name": "1.9 Credits", "content": "" } ] }, "We adapted portions of this manual from existing documents. James": { "content": "", "subsections": [] }, "Clark's man pages were an essential resource; we have updated them in": { "content": "parallel with the development of this manual. We based the tutorial for\nmacro users on Eric Allman's introduction to his 'me' macro package\n(which we also provide, little altered from 4.4BSD). Larry Kollar\ncontributed much of the material on the 'ms' macro package.\n", "subsections": [] }, "File: groff.info, Node: Invoking groff, Next: Tutorial for Macro Users, Prev: Introduction, Up: Top": { "content": "", "subsections": [] }, "2 Invoking 'groff'": { "content": "", "subsections": [] }, "This chapter focuses on how to invoke the 'groff' front end. This front": { "content": "end takes care of the details of constructing the pipeline among the\npreprocessors, 'gtroff' and the postprocessor.\n\nIt has become a tradition that GNU programs get the prefix 'g' to\ndistinguish them from their original counterparts provided by the host\n(*note Environment::). Thus, for example, 'geqn' is GNU 'eqn'. On\noperating systems like GNU/Linux or the Hurd, which don't contain\nproprietary versions of 'troff', and on MS-DOS/MS-Windows, where 'troff'\nand associated programs are not available at all, this prefix is omitted\nsince GNU 'troff' is the only incarnation of 'troff' used. Exception:\n'groff' is never replaced by 'roff'.\n\nIn this document, we consequently say 'gtroff' when talking about the\nGNU 'troff' program. All other implementations of 'troff' are called\nAT&T 'troff', which is the common origin of almost all 'troff'\nimplementations(1) (*note Invoking groff-Footnote-1::) (with more or\nless compatible changes). Similarly, we say 'gpic', 'geqn', and so on.\n\n* Menu:\n\n* Groff Options::\n* Environment::\n* Macro Directories::\n* Font Directories::\n* Paper Format::\n* Invocation Examples::\n", "subsections": [] }, "File: groff.info, Node: Groff Options, Next: Environment, Prev: Invoking groff, Up: Invoking groff": { "content": "", "subsections": [ { "name": "2.1 Options", "content": "'groff' normally runs the 'gtroff' program and a postprocessor\nappropriate for the selected device. The default device is 'ps' (but it\ncan be changed when 'groff' is configured and built). It can optionally\npreprocess with any of 'gpic', 'geqn', 'gtbl', 'ggrn', 'grap', 'gchem',\n'grefer', 'gsoelim', or 'preconv'.\n\nThis section documents only options to the 'groff' front end. Many\nof the arguments to 'groff' are passed on to 'gtroff'; therefore, those\nare also included. Arguments to preprocessors and output drivers can be\nfound in the man pages 'gpic(1)', 'geqn(1)', 'gtbl(1)', 'ggrn(1)',\n'grefer(1)', 'gchem(1)', 'gsoelim(1)', 'preconv(1)', 'grotty(1)',\n'grops(1)', 'gropdf(1)', 'grohtml(1)', 'grodvi(1)', 'grolj4(1)',\n'grolbp(1)', and 'gxditview(1)'.\n\nThe command-line format for 'groff' is:\n\ngroff [ -abceghijklpstvzCEGNRSUVXZ ] [ -dCS ] [ -DARG ]\n[ -fFAM ] [ -FDIR ] [ -IDIR ] [ -KARG ]\n[ -LARG ] [ -mNAME ] [ -MDIR ] [ -nNUM ]\n[ -oLIST ] [ -PARG ] [ -rCN ] [ -TDEV ]\n[ -wNAME ] [ -WNAME ] [ FILES... ]\n\nThe command-line format for 'gtroff' is as follows.\n\ngtroff [ -abcivzCERU ] [ -dCS ] [ -fFAM ] [ -FDIR ]\n[ -mNAME ] [ -MDIR ] [ -nNUM ] [ -oLIST ]\n[ -rCN ] [ -TNAME ] [ -wNAME ] [ -WNAME ]\n[ FILES... ]\n" } ] }, "Obviously, many of the options to 'groff' are actually passed on to": { "content": "'gtroff'.\n\nOptions without an argument can be grouped behind a single '-'. A\nfilename of '-' denotes the standard input. Whitespace is permitted\nbetween an option and its argument.\n\nThe 'grog' command can be used to guess the correct 'groff' command\nto format a file. See its man page 'grog(1)'; type 'man grog' at the\ncommand line to view it.\n\n'groff''s command-line options are as follows.\n\n'-a'\nGenerate a plain text approximation of the typeset output. The\nread-only register '.A' is set to 1. *Note Built-in Registers::.\nThis option produces a sort of abstract preview of the formatted\noutput.\n\n* Page breaks are marked by a phrase in angle brackets; for\nexample, ''.\n\n* Lines are broken where they would be in the formatted output.\n\n* A horizontal motion of any size is represented as one space.\nAdjacent horizontal motions are not combined. Inter-sentence\nspace nodes (those arising from the second argument to the\n'ss' request) are not represented.\n\n* Vertical motions are not represented.\n\n* Special characters are rendered in angle brackets; for\nexample, the default soft hyphen character appears as ''.\n\nThe above description should not be considered a specification; the\ndetails of '-a' output are subject to change.\n\n'-b'\nWrite a backtrace reporting the state of 'gtroff''s input parser to\nthe standard error stream with each diagnostic message. The line\nnumbers given in the backtrace might not always be correct, because\n'gtroff''s idea of line numbers can be confused by requests that\nappend to macros.\n\n'-c'\nStart with color output disabled.\n\n'-C'\nEnable AT&T 'troff' compatibility mode; implies '-c'. *Note\nImplementation Differences::, for the list of incompatibilities\nbetween 'groff' and AT&T 'troff'.\n\n'-dCTEXT'\n'-dSTRING=TEXT'\nDefine 'roff' string C or STRING as T or TEXT. C must be one\ncharacter; STRING can be of arbitrary length. Such string\nassignments happen before any macro file is loaded, including the\nstartup file. Due to 'getoptlong' limitations, C cannot be, and\nSTRING cannot contain, an equals sign, even though that is a valid\ncharacter in a 'roff' identifier.\n\n'-DENC'\nSet fallback input encoding used by 'preconv' to ENC; implies '-k'.\n\n'-e'\nRun 'geqn' preprocessor.\n\n'-E'\nInhibit 'gtroff' error messages. This option does not suppress\nmessages sent to the standard error stream by documents or macro\npackages using 'tm' or related requests.\n\n'-fFAM'\nUse FAM as the default font family. *Note Font Families::.\n\n'-FDIR'\nSearch in directory 'DIR' for the selected output device's\ndirectory of device and font description files. See the\ndescription of 'GROFFFONTPATH' in *note Environment:: below for\nthe default search locations and ordering.\n\n'-g'\nRun 'ggrn' preprocessor.\n\n'-G'\nRun 'grap' preprocessor; implies '-p'.\n\n'-h'\nDisplay a usage message and exit.\n\n'-i'\nRead the standard input after all the named input files have been\nprocessed.\n\n'-IDIR'\nSearch the directory DIR for files named in several contexts;\nimplies '-g' and '-s'.\n\n* 'gsoelim' replaces 'so' requests with the contents of their\nfile name arguments.\n\n* 'gtroff' searches for files named as operands in its command\nline and as arguments to 'psbb', 'so', and 'soquiet' requests.\n\n* Output drivers may search for files; for instance, 'grops'\nlooks for files named in '\\X'ps: import ...'', '\\X'ps: file\n...'', and '\\X'pdf: pdfpic ...'' device control escape\nsequences.\n\nThis option may be specified more than once; the directories are\nsearched in the order specified. If you want to search the current\ndirectory before others, add '-I .' at the desired place. The\ncurrent working directory is otherwise searched last. '-I' works\nsimilarly to, and is named for, the \"include\" option of Unix C\ncompilers.\n\n'-I' options are passed to 'gsoelim', 'gtroff', and output drivers;\nwith the flag letter changed to '-M', they are also passed to\n'ggrn'.\n\n'-j'\nRun 'gchem' preprocessor. Implies '-p'.\n\n'-k'\nRun 'preconv' preprocessor. Refer to its man page for its behavior\nif neither of 'groff''s '-K' or '-D' options is also specified.\n\n'-KENC'\nSet input encoding used by 'preconv' to ENC; implies '-k'.\n\n'-l'\nSend the output to a spooler for printing. The 'print' directive\nin the device description file specifies the default command to be\nused; see *note Device and Font Description Files::. See options\n'-L' and '-X'.\n\n'-LARG'\nPass ARG to the print spooler program. If multiple ARGs are\nrequired, pass each with a separate '-L' option. 'groff' does not\nprefix an option dash to ARG before passing it to the spooler\nprogram.\n\n'-mNAME'\nProcess the file 'NAME.tmac' prior to any input files. If not\nfound, 'tmac.NAME' is attempted. NAME (in both arrangements) is\npresumed to be a macro file; see the description of\n'GROFFTMACPATH' in *note Environment:: below for the default\nsearch locations and ordering. This option and its argument are\nalso passed to 'geqn', 'grap', and 'ggrn'.\n\n'-MDIR'\nSearch directory 'DIR' for macro files; see the description of\n'GROFFTMACPATH' in *note Environment:: below for the default\nsearch locations and ordering. This option and its argument are\nalso passed to 'geqn', 'grap', and 'ggrn'.\n\n'-nNUM'\nNumber the first page NUM.\n\n'-N'\nProhibit newlines between 'eqn' delimiters: pass '-N' to 'geqn'.\n\n'-oLIST'\nOutput only pages in LIST, which is a comma-separated list of page\nranges; 'N' means page N, 'M-N' means every page between M and N,\n'-N' means every page up to N, 'N-' means every page from N on.\n'gtroff' stops processing and exits after formatting the last page\nenumerated in LIST.\n\n'-p'\nRun 'gpic' preprocessor.\n\n'-PARG'\nPass ARG to the postprocessor. If multiple ARGs are required, pass\neach with a separate '-P' option. 'groff' does not prefix an\noption dash to ARG before passing it to the postprocessor.\n\n'-rCNUMERIC-EXPRESSION'\n'-rREGISTER=EXPR'\nSet 'roff' register C or REGISTER to the value NUMERIC-EXPRESSION\n(*note Numeric Expressions::). C must be one character; REGISTER\ncan be of arbitrary length. Such register assignments happen\nbefore any macro file is loaded, including the startup file. Due\nto 'getoptlong' limitations, C cannot be, and REGISTER cannot\ncontain, an equals sign, even though that is a valid character in a\n'roff' identifier.\n\n'-R'\nRun 'grefer' preprocessor. No mechanism is provided for passing\narguments to 'grefer' because most 'grefer' options have equivalent\nlanguage elements that can be specified within the document.\n\n'gtroff' also accepts a '-R' option, which is not accessible via\n'groff'. This option prevents the loading of the 'troffrc' and\n'troffrc-end' files.\n\n'-s'\nRun 'gsoelim' preprocessor.\n\n'-S'\nOperate in \"safer\" mode; see '-U' below for its opposite. For\nsecurity reasons, safer mode is enabled by default.\n\n'-t'\nRun 'gtbl' preprocessor.\n\n'-TDEV'\nDirect 'gtroff' to format the input for the output device DEV.\n'groff' then calls an output driver to convert 'gtroff''s output to\na form appropriate for DEV. The following output devices are\navailable.\n\n'ps'\nFor PostScript printers and previewers.\n\n'pdf'\nFor PDF viewers or printers.\n\n'dvi'\nFor TeX DVI format.\n\n'X75'\nFor a 75dpi X11 previewer.\n\n'X75-12'\nFor a 75dpi X11 previewer with a 12-point base font in the\ndocument.\n\n'X100'\nFor a 100dpi X11 previewer.\n\n'X100-12'\nFor a 100dpi X11 previewer with a 12-point base font in the\ndocument.\n\n'ascii'\nFor typewriter-like devices using the (7-bit) ASCII (ISO 646)\ncharacter set.\n\n'latin1'\nFor typewriter-like devices that support the Latin-1\n(ISO 8859-1) character set.\n\n'utf8'\nFor typewriter-like devices that use the Unicode (ISO 10646)\ncharacter set with UTF-8 encoding.\n\n'cp1047'\nFor typewriter-like devices that use the EBCDIC encoding IBM\ncode page 1047.\n\n'lj4'\nFor HP LaserJet4-compatible (or other PCL5-compatible)\nprinters.\n\n'lbp'\nFor Canon CaPSL printers (LBP-4 and LBP-8 series laser\nprinters).\n\n'html'\n'xhtml'\nTo produce HTML and XHTML output, respectively. This driver\nconsists of two parts, a preprocessor ('pre-grohtml') and a\npostprocessor ('post-grohtml').\n\nThe predefined GNU 'troff' string '.T' contains the name of the\noutput device; the read-only register '.T' is set to 1 if this\noption is used (which is always true if 'groff' is used to call GNU\n'troff'). *Note Built-in Registers::.\n\nThe postprocessor to be used for a device is specified by the\n'postpro' command in the device description file. (*Note Device\nand Font Description Files::.) This can be overridden with the\n'-X' option.\n\n'-U'\nOperate in \"unsafe mode\", which enables the 'open', 'opena', 'pi',\n'pso', and 'sy' requests. These requests are disabled by default\nbecause they allow an untrusted input document to write to\narbitrary file names and run arbitrary commands. This option also\nadds the current directory to the macro package search path; see\nthe '-m' option above. '-U' is passed to 'gpic' and 'gtroff'.\n\n'-v'\nWrite version information for 'groff' and all programs run by it to\nthe standard output stream; that is, the given command line is\nprocessed in the usual way, passing '-v' to the formatter and any\npre- or postprocessors invoked.\n\n'-V'\nOutput the pipeline that would be run by 'groff' (as a wrapper\nprogram) to the standard output stream, but do not execute it. If\ngiven more than once, the pipeline is both written to the standard\nerror stream and run.\n\n'-wCATEGORY'\nEnable warnings in CATEGORY. Categories are listed in *note\nWarnings::.\n\n'-WCATEGORY'\nInhibit warnings in CATEGORY. Categories are listed in *note\nWarnings::.\n\n'-X'\nUse 'gxditview' instead of the usual postprocessor to (pre)view a\ndocument on an X11 display. Combining this option with '-Tps' uses\nthe font metrics of the PostScript device, whereas the '-TX75' and\n'-TX100' options use the metrics of X11 fonts.\n\n'-z'\nSuppress formatted output from 'gtroff'.\n\n'-Z'\nDisable postprocessing. 'gtroff' output will appear on the\nstandard output stream (unless suppressed with '-z'; see *note\ngtroff Output:: for a description of this format.\n", "subsections": [] }, "File: groff.info, Node: Environment, Next: Macro Directories, Prev: Groff Options, Up: Invoking groff": { "content": "", "subsections": [ { "name": "2.2 Environment", "content": "" } ] }, "There are also several environment variables (of the operating system,": { "content": "not within 'gtroff') that can modify the behavior of 'groff'.\n\n'GROFFBINPATH'\nThis search path, followed by 'PATH', is used for commands executed\nby 'groff'.\n\n'GROFFCOMMANDPREFIX'\nIf this is set to X, then 'groff' runs 'Xtroff' instead of\n'gtroff'. This also applies to 'tbl', 'pic', 'eqn', 'grn', 'chem',\n'refer', and 'soelim'. It does not apply to 'grops', 'grodvi',\n'grotty', 'pre-grohtml', 'post-grohtml', 'preconv', 'grolj4',\n'gropdf', and 'gxditview'.\n\nThe default command prefix is determined during the installation\nprocess. If a non-GNU 'troff' system is found, prefix 'g' is used,\nnone otherwise.\n\n'GROFFENCODING'\nThe value of this variable is passed to the 'preconv'\npreprocessor's '-e' option to select the character encoding of\ninput files. This variable's existence implies the 'groff' option\n'-k'. If set but empty, 'groff' calls 'preconv' without an '-e'\noption. 'groff''s '-K' option overrides 'GROFFENCODING'. See the\n'preconv(7)' man page; type 'man preconv' at the command line to\nview it.\n\n'GROFFFONTPATH'\nA list of directories in which to seek the selected output device's\ndirectory of device and font description files. GNU 'troff' will\nsearch directories given as arguments to any specified '-F' options\nbefore these, and a built-in list of directories after them. *Note\nFont Directories:: and the 'troff(1)' or 'gtroff(1)' man pages.\n\n'GROFFTMACPATH'\nA list of directories in which to seek macro files. GNU 'troff'\nwill search directories given as arguments to any specified '-M'\noptions before these, and a built-in list of directories after\nthem. *Note Macro Directories:: and the 'troff(1)' or 'gtroff(1)'\nman pages.\n\n'GROFFTMPDIR'\nThe directory in which 'groff' creates temporary files. If this is\nnot set and 'TMPDIR' is set, temporary files are created in that\ndirectory. Otherwise temporary files are created in a\nsystem-dependent default directory (on Unix and GNU/Linux systems,\nthis is usually '/tmp'). 'grops', 'grefer', 'pre-grohtml', and\n'post-grohtml' can create temporary files in this directory.\n\n'GROFFTYPESETTER'\nSets the default output device. If empty or not set, a build-time\ndefault (often 'ps') is used. The '-TDEV' option overrides\n'GROFFTYPESETTER'.\n\n'SOURCEDATEEPOCH'\nA timestamp (expressed as seconds since the Unix epoch) to use as\nthe output creation timestamp in place of the current time. The\ntime is converted to human-readable form using 'gmtime(3)' and\n'asctime(3)' when the formatter starts up and stored in registers\nusable by documents and macro packages (*note Built-in\nRegisters::).\n\n'TZ'\nThe time zone to use when converting the current time to\nhuman-readable form; see 'tzset(3)'. If 'SOURCEDATEEPOCH' is\nused, it is always converted to human-readable form using UTC.\n\nMS-DOS and MS-Windows ports of 'groff' use semicolons, rather than\ncolons, to separate the directories in the lists described above.\n", "subsections": [] }, "File: groff.info, Node: Macro Directories, Next: Font Directories, Prev: Environment, Up: Invoking groff": { "content": "", "subsections": [ { "name": "2.3 Macro Directories", "content": "A macro file must have a name in the form 'NAME.tmac' or 'tmac.NAME' and\nbe placed in a \"tmac directory\" to be found by the '-mNAME' command-line\noption.(1) (*note Macro Directories-Footnote-1::) Together, these\ndirectories constitute the \"tmac path\". Each directory is searched in\nthe following order until the desired macro file is found or the list is\nexhausted.\n\n* Directories specified with GNU 'troff''s or 'groff''s '-M'\ncommand-line option.\n\n* Directories listed in the 'GROFFTMACPATH' environment variable.\n\n* The current working directory (only if in unsafe mode using the\n'-U' command-line option).\n\n* The user's home directory, 'HOME'.\n\n* A platform-dependent directory, a site-local (platform-independent)\ndirectory, and the main tmac directory. The locations\ncorresponding to your installation are listed in section\n\"Environment\" of 'gtroff(1)'. If not otherwise configured, they\nare as follows.\n\n/usr/local/lib/groff/site-tmac\n/usr/local/share/groff/site-tmac\n/usr/local/share/groff/1.23.0/tmac\n\nThe foregoing assumes that the version of 'groff' is 1.23.0, and\nthat the installation prefix was '/usr/local'. It is possible to\nfine-tune these locations during the source configuration process.\n" } ] }, "File: groff.info, Node: Font Directories, Next: Paper Format, Prev: Macro Directories, Up: Invoking groff": { "content": "", "subsections": [ { "name": "2.4 Font Directories", "content": "'groff' enforces few restrictions on how font description files are\nnamed. For its family/style mechanism to work (*note Font Families::),\nthe names of fonts within a family should start with the family name,\nfollowed by the style. For example, the Times family uses 'T' for the\nfamily name and 'R', 'B', 'I', and 'BI' to indicate the styles 'roman',\n'bold', 'italic', and 'bold italic', respectively. Thus the final font\nnames are 'TR', 'TB', 'TI', and 'TBI'.\n\nFont description files are kept in \"font directories\", which together\nconstitute the \"font path\". The search procedure always appends the\ndirectory 'dev'NAME, where NAME is the name of the output device." } ] }, "Assuming TeX DVI output, and '/foo/bar' as a font directory, the font": { "content": "description files for 'grodvi' must be in '/foo/bar/devdvi'. Each\ndirectory in the font path is searched in the following order until the\ndesired font description file is found or the list is exhausted.\n\n* Directories specified with GNU 'troff''s or 'groff''s '-f'\ncommand-line option. All output drivers (and some preprocessors)\nsupport this option as well, because they require information about\nthe glyphs to be rendered in the document.\n\n* Directories listed in the 'GROFFFONTPATH' environment variable.\n\n* A site-local directory and the main font description directory.\nThe locations corresponding to your installation are listed in\nsection \"Environment\" of 'gtroff(1)'. If not otherwise configured,\nthey are as follows.\n\n/usr/local/share/groff/site-font\n/usr/local/share/groff/1.23.0/font\n\nThe foregoing assumes that the version of 'groff' is 1.23.0, and\nthat the installation prefix was '/usr/local'. It is possible to\nfine-tune these locations during the source configuration process.\n", "subsections": [] }, "File: groff.info, Node: Paper Format, Next: Invocation Examples, Prev: Font Directories, Up: Invoking groff": { "content": "", "subsections": [ { "name": "2.5 Paper Format", "content": "" } ] }, "In 'groff', the page dimensions for the formatter GNU 'troff' and for": { "content": "output devices are handled separately. *Note Page Layout::, for\nvertical manipulation of the page size, and *Note Line Layout::, for\nhorizontal changes. The 'papersize' macro package, normally loaded by\n'troffrc' at startup, provides an interface for configuring page\ndimensions by convenient names, like 'letter' or 'a4'; see\n'grofftmac(5)'. The default used by the formatter depends on its build\nconfiguration, but is usually one of the foregoing, as geographically\nappropriate.\n\nIt is up to each macro package to respect the page dimensions\nconfigured in this way.\n\nFor each output device, the size of the output medium can be set in\nits 'DESC' file. Most output drivers also recognize a command-line\noption '-p' to override the default dimensions and an option '-l' to use\nlandscape orientation. *Note DESC File Format::, for a description of\nthe 'papersize' keyword, which takes an argument of the same form as\n'-p'. The output driver's man page, such as 'grops(1)', may also be\nhelpful.\n\n'groff' uses the command-line option '-P' to pass options to\npostprocessors; for example, use the following for PostScript output on\nA4 paper in landscape orientation.\n\ngroff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps\n", "subsections": [] }, "File: groff.info, Node: Invocation Examples, Prev: Paper Format, Up: Invoking groff": { "content": "", "subsections": [ { "name": "2.6 Invocation Examples", "content": "'roff' systems are best known for formatting man pages. Once a 'man'\nlibrarian program has located a man page, it may execute a 'groff'\ncommand much like the following.\n\ngroff -t -man -Tutf8 /usr/share/man/man1/groff.1\n\nThe librarian will also pipe the output through a pager, which might\nnot interpret the SGR terminal escape sequences 'groff' emits for\nboldface, underlining, or italics; see the 'grotty(1)' man page for a\ndiscussion.\n\nTo process a 'roff' input file using the preprocessors 'gtbl' and\n'gpic' and the 'me' macro package in the way to which AT&T 'troff' users\nwere accustomed, one would type (or script) a pipeline.\n\ngpic foo.me | gtbl | gtroff -me -Tutf8 | grotty\n\nUsing 'groff', this pipe can be shortened to an equivalent command.\n\ngroff -p -t -me -T utf8 foo.me\n\nAn even easier way to do this is to use 'grog' to guess the\npreprocessor and macro options and execute the result by using the\ncommand substitution feature of the shell.\n\n$(grog -Tutf8 foo.me)\n\nEach command-line option to a postprocessor must be specified with\nany required leading dashes '-' because 'groff' passes the arguments\nas-is to the postprocessor; this permits arbitrary arguments to be\ntransmitted. For example, to pass a title to the 'gxditview'\npostprocessor, the shell commands\n\ngroff -X -P -title -P 'trial run' mydoc.t\n\nand\n\ngroff -X -Z mydoc.t | gxditview -title 'trial run' -\n\nare equivalent.\n" } ] }, "File: groff.info, Node: Tutorial for Macro Users, Next: Major Macro Packages, Prev: Invoking groff, Up: Top": { "content": "", "subsections": [] }, "3 Tutorial for Macro Users": { "content": "", "subsections": [] }, "Most users of the 'roff' language employ a macro package to format their": { "content": "documents. Successful macro packages ease the composition process;\ntheir users need not have mastered the full formatting language, nor\nunderstand features like diversions, traps, and environments. This\nchapter aims to familiarize you with basic concepts and mechanisms\ncommon to many macro packages (like \"displays\"). If you prefer a\nmeticulous and comprehensive presentation, try *note GNU troff\nReference:: instead.\n\n* Menu:\n\n* Basics::\n* Common Features::\n", "subsections": [] }, "File: groff.info, Node: Basics, Next: Common Features, Prev: Tutorial for Macro Users, Up: Tutorial for Macro Users": { "content": "", "subsections": [ { "name": "3.1 Basics", "content": "" } ] }, "Let us first survey some basic concepts necessary to use a macro package": { "content": "fruitfully.(1) (*note Basics-Footnote-1::) References are made\nthroughout to more detailed information.\n\nGNU 'troff' reads an input file prepared by the user and outputs a\nformatted document suitable for publication or framing. The input\nconsists of text, or words to be printed, and embedded commands\n(requests and escape sequences), which tell GNU 'troff' how to format\nthe output. *Note Formatter Instructions::.\n\nThe word argument is used in this chapter to mean a word or number\nthat appears on the same line as a request, and which modifies the\nmeaning of that request. For example, the request\n\n.sp\n\nspaces one line, but\n\n.sp 4\n\nspaces four lines. The number 4 is an argument to the 'sp' request,\nwhich says to space four lines instead of one. Arguments are separated\nfrom the request and from each other by spaces (not tabs). *Note\nInvoking Requests::.\n\nThe primary function of GNU 'troff' is to collect words from input\nlines, fill output lines with those words, adjust the line to the\nright-hand margin by widening spaces, and output the result. For\nexample, the input:\n\nNow is the time\nfor all good men\nto come to the aid\nof their party.\nFour score and seven\nyears ago, etc.\n\nis read, packed onto output lines, and justified to produce:\n\n=> Now is the time for all good men to come to the aid of\n=> their party. Four score and seven years ago, etc.\n\nSometimes a new output line should be started even though the current\nline is not yet full--for example, at the end of a paragraph. To do\nthis it is possible to force a break, starting a new output line. Some\nrequests cause a break automatically, as do (normally) blank input lines\nand input lines beginning with a space or tab.\n\nNot all input lines are text lines--words to be formatted. Some are\ncontrol lines that tell a macro package (or GNU 'troff' directly) how to\nformat the text. Control lines start with a dot ('.') or an apostrophe\n(''') as the first character, and can be followed by a macro call.\n\nThe formatter also does more complex things, such as automatically\nnumbering pages, skipping over page boundaries, putting footnotes in the\ncorrect place, and so forth.\n\nHere are a few hints for preparing text for input to GNU 'troff'.\n\n* First, keep the input lines short. Short input lines are easier to\nedit, and GNU 'troff' packs words onto longer lines anyhow.\n\n* In keeping with this, it is helpful to begin a new line after every\ncomma or phrase, since common corrections are to add or delete\nsentences or phrases.\n\n* End each sentence with two spaces--or better, start each sentence\non a new line. GNU 'troff' recognizes characters that usually end\na sentence, and inserts inter-sentence space accordingly.\n\n* Do not hyphenate words at the end of lines--GNU 'troff' is smart\nenough to hyphenate words as needed, but is not smart enough to\ntake hyphens out and join a word back together. Also, words such\nas \"mother-in-law\" should not be broken over a line, since then a\nspace can occur where not wanted, such as \"mother- in-law\".\n\nWe offer further advice in *note Input Conventions::.\n\nGNU 'troff' permits alteration of the distance between lines of text.", "subsections": [] }, "This is termed vertical spacing and is expressed in the same units as": { "content": "the type size--the point. The default is 10-point type on 12-point\nspacing. To get double-spaced text you would set the vertical spacing\nto 24 points. Some, but not all, macro packages expose a macro or\nregister to configure the vertical spacing.\n\nA number of requests allow you to change the way the output is\narranged on the page, sometimes called the layout of the output page.", "subsections": [] }, "Most macro packages don't supply macros for performing these (at least": { "content": "not without performing other actions besides), as they are such basic\noperations. The macro packages for writing man pages, 'man' and 'mdoc',\ndon't encourage explicit use of these requests at all.\n\nThe request '.sp N' leaves N lines of blank space. N can be omitted\n(skipping a single line) or can be of the form Ni (for N inches) or Nc\n(for N centimeters). For example, the input:\n\n.sp 1.5i\nMy thoughts on the subject\n.sp\n\nleaves one and a half inches of space, followed by the line \"My thoughts\non the subject\", followed by a single blank line (more measurement units\nare available; see *note Measurements::).\n\nIf you seek precision in spacing, be advised when using a macro\npackage that it might not honor 'sp' requests as you expect; it can use\na formatter feature called no-space mode to prevent excess space from\naccumulating. Macro packages typically offer registers to control\nspacing between paragraphs, before section headings, and around displays\n(discussed below); use these facilities preferentially. *Note\nManipulating Spacing::.\n\nText lines can be centered by using the 'ce' request. The line after\n'ce' is centered (horizontally) on the page. To center more than one\nline, use '.ce N' (where N is the number of lines to center), followed\nby the N lines. To center many lines without counting them, type:\n\n.ce 1000\nlines to center\n.ce 0\n", "subsections": [] }, "The '.ce 0' request tells GNU 'troff' to center zero more lines, in": { "content": "other words, stop centering.\n\nGNU 'troff' also offers the 'rj' request for right-aligning text. It\nworks analogously to 'ce' and is convenient for setting epigraphs.\n\nThe 'bp' request starts a new page; this necessarily implies an\nordinary (line) break.\n\nAll of these requests cause a break; that is, they always start a new\nline. To start a new line without performing any other action, use\n'br'. If you invoke them with the apostrophe ''', the no-break control\ncharacter, the (initial) break they normally perform is suppressed.\n''br' does nothing.\n", "subsections": [] }, "File: groff.info, Node: Common Features, Prev: Basics, Up: Tutorial for Macro Users": { "content": "", "subsections": [ { "name": "3.2 Common Features", "content": "GNU 'troff' provides low-level operations for formatting a document." } ] }, "Many routine operations are undertaken in nearly all documents that": { "content": "require a series of such primitive operations to be performed. These\ncommon tasks are grouped into macros, which are then collected into a\nmacro package.\n\nMacro packages come in two varieties: \"major\" or \"full-service\" ones\nthat manage page layout, and \"minor\" or \"auxiliary\" ones that do not,\ninstead fulfilling narrow, specific tasks. Find a list in the\n'grofftmac(5)' man page. Type 'man grofftmac' at the command line to\nview it.\n\nWe survey several capabilities of full-service macro package below.", "subsections": [] }, "Each package employs its own macros to exercise them. For details,": { "content": "consult its man page or, for 'ms', see *note ms::.\n\n* Menu:\n\n* Paragraphs::\n* Sections and Chapters::\n* Headers and Footers::\n* Page Layout Adjustment::\n* Displays and Keeps::\n* Footnotes and Endnotes::\n* Table of Contents::\n* Indexing::\n* Document Formats::\n* Columnation::\n* Font and Size Changes::\n* Predefined Text::\n* Preprocessor Support::\n* Configuration and Customization::\n", "subsections": [] }, "File: groff.info, Node: Paragraphs, Next: Sections and Chapters, Prev: Common Features, Up: Common Features": { "content": "", "subsections": [] }, "Paragraphs can be separated and indented in various ways. Some start": { "content": "with a blank line and have a first-line indentation, like most of the\nones in this manual. Block paragraphs omit the indentation.\n\n=> Some men look at constitutions with sanctimonious\n=> reverence, and deem them like the ark of the\n=> covenant, too sacred to be touched.\n", "subsections": [] }, "We also frequently encounter tagged paragraphs, which begin with a tag": { "content": "or label at the left margin and indent the remaining text.\n\n=> one This is the first paragraph. Notice how the\n=> first line of the resulting paragraph lines\n=> up with the other lines in the paragraph.\n\nIf the tag is too wide for the indentation, the line is broken.\n\n=> longlabel\n=> The label does not align with the subsequent\n=> lines, but they align with each other.\n\nA variation of the tagged paragraph is the itemized or enumerated\nparagraph, which might use punctuation or a digit for a tag,\nrespectively. These are frequently used to construct lists.\n\n=> o This list item starts with a bullet. When\n=> producing output for a device using the ASCII\n=> character set, an 'o' is formatted instead.\n\nOften, use of the same macro without a tag continues such a discussion.\n\n=> -xyz This option is recognized but ignored.\n=>\n=> It had a security hole that we don't discuss.\n", "subsections": [] }, "File: groff.info, Node: Sections and Chapters, Next: Headers and Footers, Prev: Paragraphs, Up: Common Features": { "content": "", "subsections": [] }, "The simplest kind of section heading is unnumbered, set in a bold or": { "content": "italic style, and occupies a line by itself. Others possess\nautomatically numbered multi-level headings and/or different typeface\nstyles or sizes at different levels. More sophisticated macro packages\nsupply macros for designating chapters and appendices.\n", "subsections": [] }, "File: groff.info, Node: Headers and Footers, Next: Page Layout Adjustment, Prev: Sections and Chapters, Up: Common Features": { "content": "", "subsections": [] }, "Headers and footers occupy the top and bottom of each page,": { "content": "respectively, and contain data like the page number and the article or\nchapter title. Their appearance is not affected by the running text.", "subsections": [] }, "Some packages allow for different titles on even- and odd-numbered pages": { "content": "(for printed, bound material).\n\nHeaders and footers are together called titles, and comprise three\nparts: left-aligned, centered, and right-aligned. A '%' character\nappearing anywhere in a title is automatically replaced by the page\nnumber. *Note Page Layout::.\n", "subsections": [] }, "File: groff.info, Node: Page Layout Adjustment, Next: Displays and Keeps, Prev: Headers and Footers, Up: Common Features": { "content": "Most macro packages let the user specify the size of the page margins.", "subsections": [] }, "The top and bottom margins are typically handled differently than the": { "content": "left and right margins; the latter two are derived from the page offset,\nindentation, and line length. *Note Line Layout::. Commonly, packages\nsupport registers to tune these values.\n", "subsections": [] }, "File: groff.info, Node: Displays and Keeps, Next: Footnotes and Endnotes, Prev: Page Layout Adjustment, Up: Common Features": { "content": "", "subsections": [] }, "Displays are sections of text set off from the surrounding material": { "content": "(typically paragraphs), often differing in indentation, and/or spacing.", "subsections": [] }, "Tables, block quotations, and figures are displayed. Equations and code": { "content": "examples, when not much shorter than an output line, often are. Lists\nmay or may not be. Packages for setting man pages support example\ndisplays but not keeps.\n\nA keep is a group of output lines, often a display, that is formatted\non a single page if possible; it causes a page break to happen early so\nas to not interrupt the kept material.\n\nFloating keeps can move, or \"float\", relative to the text around them\nin the input. They are useful for displays that are captioned and\nreferred to by name, as with \"See figure 3\". Depending on the package,\na floating keep appears at the bottom of the current page if it fits,\nand at the top of the next otherwise. Alternatively, floating keeps\nmight be deferred to the end of a section. Using a floating keep can\navoid the large vertical spaces that may precede a tall keep of the\nordinary sort when it won't fit on the page.\n", "subsections": [] }, "File: groff.info, Node: Footnotes and Endnotes, Next: Table of Contents, Prev: Displays and Keeps, Up: Common Features": { "content": "", "subsections": [] }, "Footnotes and endnotes are forms of delayed formatting. They are": { "content": "recorded at their points of relevance in the input, but not formatted\nthere. Instead, a mark cues the reader to check the \"foot\", or bottom,\nof the current page, or in the case of endnotes, an annotation list\nlater in the document. Macro packages that support these features also\nsupply a means of automatically numbering either type of annotation.\n", "subsections": [] }, "File: groff.info, Node: Table of Contents, Next: Indexing, Prev: Footnotes and Endnotes, Up: Common Features": { "content": "A package may handle a table of contents by directing section heading\nmacros to save section heading text and the page number where it occurs\nfor use in a later entry for a table of contents. It writes the\ncollected entries at the end of the document, once all are known, upon\nrequest. A row of dots (a leader) bridges the text on the left with its\nlocation on the right. Other collections might work in this manner,\nproviding lists of figures or tables.\n\nA table of contents is often found at the end of a GNU 'troff'\ndocument because the formatter processes the document in a single pass.", "subsections": [] }, "The 'gropdf' output driver supports a PDF feature that relocates pages": { "content": "at the time the document is rendered; see the 'gropdf(1)' man page.\nType 'man gropdf' at the command line to view it.\n", "subsections": [] }, "File: groff.info, Node: Indexing, Next: Document Formats, Prev: Table of Contents, Up: Common Features": { "content": "", "subsections": [] }, "An index is similar to a table of contents, in that entry labels and": { "content": "locations must be collected, but poses a greater challenge because it\nneeds to be sorted before it is output. Here, processing the document\nin multiple passes is inescapable, and tools like the 'makeindex'\nprogram are necessary.\n", "subsections": [] }, "File: groff.info, Node: Document Formats, Next: Columnation, Prev: Indexing, Up: Common Features": { "content": "", "subsections": [] }, "Some macro packages supply stock configurations of certain documents,": { "content": "like business letters and memoranda. These often also have provision\nfor a cover sheet, which may be rigid in its format. With these\nfeatures, it is even more important to use the package's macros in\npreference to the formatter requests presented earlier, where possible.\n", "subsections": [] }, "File: groff.info, Node: Columnation, Next: Font and Size Changes, Prev: Document Formats, Up: Common Features": { "content": "", "subsections": [] }, "Macro packages apart from 'man' and 'mdoc' for man page formatting offer": { "content": "a facility for setting multiple columns on the page.\n", "subsections": [] }, "File: groff.info, Node: Font and Size Changes, Next: Predefined Text, Prev: Columnation, Up: Common Features": { "content": "", "subsections": [] }, "The formatter's requests and escape sequences for setting the typeface": { "content": "and size are not always intuitive, so all macro packages provide macros\nto make these operations simpler. They also make it more convenient to\nchange typefaces in the middle of a word and can handle italic\ncorrections automatically. *Note Italic Corrections::.\n", "subsections": [] }, "File: groff.info, Node: Predefined Text, Next: Preprocessor Support, Prev: Font and Size Changes, Up: Common Features": { "content": "", "subsections": [] }, "Most macro packages supply predefined strings to set prepared text like": { "content": "the date, or to perform operations like super- and subscripting.\n", "subsections": [] }, "File: groff.info, Node: Preprocessor Support, Next: Configuration and Customization, Prev: Predefined Text, Up: Common Features": { "content": "", "subsections": [] }, "All macro packages provide support for various preprocessors and may": { "content": "extend their functionality by defining macros to set their contents in\ndisplays. Examples include 'TS' and 'TE' for 'gtbl', 'EQ' and 'EN' for\n'geqn', and 'PS' and 'PE' for 'gpic'.\n", "subsections": [] }, "File: groff.info, Node: Configuration and Customization, Prev: Preprocessor Support, Up: Common Features": { "content": "", "subsections": [] }, "Packages provide means of customizing many of the details of how the": { "content": "package behaves. These range from setting the default type size to\nchanging the appearance of section headers.\n", "subsections": [] }, "File: groff.info, Node: Major Macro Packages, Next: GNU troff Reference, Prev: Tutorial for Macro Users, Up: Top": { "content": "", "subsections": [] }, "4 Macro Packages": { "content": "This chapter surveys the \"major\" macro packages that come with 'groff'.\nOne, 'ms', is presented in detail.\n\nMajor macro packages are also sometimes described as \"full-service\"\ndue to the breadth of features they provide and because more than one\ncannot be used by the same document; for example\n\ngroff -m man foo.man -m ms bar.doc\n\ndoesn't work. Option arguments are processed before non-option\narguments; the above (failing) sample is thus reordered to\n\ngroff -m man -m ms foo.man bar.doc\n\nMany auxiliary, or \"minor\", macro packages are also available. They\nmay in general be used with any full-service macro package and handle a\nvariety of tasks from character encoding selection, to language\nlocalization, to inlining of raster images. See the 'grofftmac(5)' man\npage for a list. Type 'man grofftmac' at the command line to view it.\n\n* Menu:\n\n* man::\n* mdoc::\n* me::\n* mm::\n* mom::\n* ms::\n", "subsections": [] }, "File: groff.info, Node: man, Next: mdoc, Prev: Major Macro Packages, Up: Major Macro Packages": { "content": "", "subsections": [ { "name": "4.1 'man'", "content": "" } ] }, "The 'man' macro package is the most widely used and probably the most": { "content": "important ever developed for 'troff'. It is easy to use, and a vast\nmajority of manual pages (\"man pages\") are written in it.\n\n'groff''s implementation is documented in the 'groffman(7)' man\npage. Type 'man groffman' at the command line to view it.\n\n* Menu:\n\n* Optional man extensions::\n", "subsections": [] }, "File: groff.info, Node: Optional man extensions, Up: man": { "content": "", "subsections": [] }, "Use the file 'man.local' for local extensions to the 'man' macros or for": { "content": "style changes.\n", "subsections": [] }, "Custom headers and footers": { "content": "..........................\n", "subsections": [] }, "In 'groff' versions 1.18.2 and later, you can specify custom headers and": { "content": "footers by redefining the following macros in 'man.local'.\n\n-- Macro: .PT\nControl the content of the headers. Normally, the header prints\nthe command name and section number on either side, and the\noptional fifth argument to 'TH' in the center.\n\n-- Macro: .BT\nControl the content of the footers. Normally, the footer prints\nthe page number and the third and fourth arguments to 'TH'.\n\nUse the 'FT' register to specify the footer position. The default\nis -0.5i.\n", "subsections": [] }, "Ultrix-specific man macros": { "content": "..........................\n", "subsections": [] }, "The 'groff' source distribution includes a file named 'man.ultrix',": { "content": "containing macros compatible with the Ultrix variant of 'man'. Copy\nthis file into 'man.local' (or use the 'mso' request to load it) to\nenable the following macros.\n\n-- Macro: .CT key\nPrint ''.\n\n-- Macro: .CW\nPrint subsequent text using a \"constant-width\" (monospaced)\ntypeface (Courier roman).\n\n-- Macro: .Ds\nBegin a non-filled display.\n\n-- Macro: .De\nEnd a non-filled display started with 'Ds'.\n\n-- Macro: .EX [indent]\nBegin a non-filled display using a monospaced typeface (Courier\nroman). Use the optional INDENT argument to indent the display.\n\n-- Macro: .EE\nEnd a non-filled display started with 'EX'.\n\n-- Macro: .G [text]\nSet TEXT in Helvetica. If no text is present on the line where the\nmacro is called, then the text of the next line appears in\nHelvetica.\n\n-- Macro: .GL [text]\nSet TEXT in Helvetica oblique. If no text is present on the line\nwhere the macro is called, then the text of the next line appears\nin Helvetica Oblique.\n\n-- Macro: .HB [text]\nSet TEXT in Helvetica bold. If no text is present on the line\nwhere the macro is called, then all text up to the next 'HB'\nappears in Helvetica bold.\n\n-- Macro: .TB [text]\nIdentical to 'HB'.\n\n-- Macro: .MS title sect [punct]\nSet a man page reference in Ultrix format. The TITLE is in Courier\ninstead of italic. Optional punctuation follows the section number\nwithout an intervening space.\n\n-- Macro: .NT [C] [title]\nBegin a note. Print the optional title, or the word \"Note\",\ncentered on the page. Text following the macro makes up the body\nof the note, and is indented on both sides. If the first argument\nis 'C', the body of the note is printed centered (the second\nargument replaces the word \"Note\" if specified).\n\n-- Macro: .NE\nEnd a note begun with 'NT'.\n\n-- Macro: .PN path [punct]\nSet the path name in a monospaced typeface (Courier roman),\nfollowed by optional punctuation.\n\n-- Macro: .Pn [punct] path [punct]\nIf called with two arguments, identical to 'PN'. If called with\nthree arguments, set the second argument in a monospaced typeface\n(Courier roman), bracketed by the first and third arguments in the\ncurrent font.\n\n-- Macro: .R\nSwitch to roman font and turn off any underlining in effect.\n\n-- Macro: .RN\nPrint the string ''.\n\n-- Macro: .VS [4]\nStart printing a change bar in the margin if the number '4' is\nspecified. Otherwise, this macro does nothing.\n\n-- Macro: .VE\nEnd printing the change bar begun by 'VS'.\n", "subsections": [] }, "Simple example": { "content": "..............\n", "subsections": [] }, "The following example 'man.local' file alters the 'SH' macro to add some": { "content": "extra vertical space before printing the heading. Headings are printed\nin Helvetica bold.\n\n.\\\" Make the heading fonts Helvetica\n.ds HF HB\n.\n.\\\" Put more space in front of headings.\n.rn SH SH-orig\n.de SH\n. if t .sp (u;\\\\n[PD]*2)\n. SH-orig \\\\$*\n..\n", "subsections": [] }, "File: groff.info, Node: mdoc, Next: me, Prev: man, Up: Major Macro Packages": { "content": "", "subsections": [ { "name": "4.2 'mdoc'", "content": "'groff''s implementation of the BSD 'doc' package for man pages is\ndocumented in the 'groffmdoc(7)' man page. Type 'man groffmdoc' at\nthe command line to view it.\n" } ] }, "File: groff.info, Node: me, Next: mm, Prev: mdoc, Up: Major Macro Packages": { "content": "", "subsections": [ { "name": "4.3 'me'", "content": "'groff''s implementation of the BSD 'me' macro package is documented\nusing itself. A tutorial, 'meintro.me', and reference, 'meref.me', are\navailable in 'groff''s documentation directory. A 'groffme(7)' man\npage is also available and identifies the installation path for these\ndocuments. Type 'man groffme' at the command line to view it.\n\nA French translation of the tutorial is available as 'meintrofr.me'\nand installed parallel to the English version.\n" } ] }, "File: groff.info, Node: mm, Next: mom, Prev: me, Up: Major Macro Packages": { "content": "", "subsections": [ { "name": "4.4 'mm'", "content": "'groff''s implementation of the AT&T memorandum macro package is\ndocumented in the 'groffmm(7)' man page. Type 'man groffmm' at the\ncommand line) to view it.\n\nA Swedish localization of 'mm' is also available; see\n'groffmmse(7)'.\n" } ] }, "File: groff.info, Node: mom, Next: ms, Prev: mm, Up: Major Macro Packages": { "content": "", "subsections": [ { "name": "4.5 'mom'", "content": "The main documentation files for the 'mom' macros are in HTML format." } ] }, "Additional, useful documentation is in PDF format. See the 'groff(1)'": { "content": "man page, section \"Installation Directories\", for their location.\n\n* 'toc.html' Entry point to the full mom manual.\n\n* 'macrolist.html' Hyperlinked index of macros with brief\ndescriptions, arranged by category.\n\n* 'mom-pdf.pdf' PDF features and usage.\n\nThe mom macros are in active development between 'groff' releases.", "subsections": [] }, "The most recent version, along with up-to-date documentation, is": { "content": "available at .\n\nThe 'groffmom(7)' man page (type 'man groffmom' at the command\nline) contains a partial list of available macros, however their usage\nis best understood by consulting the HTML documentation.\n", "subsections": [] }, "File: groff.info, Node: ms, Prev: mom, Up: Major Macro Packages": { "content": "", "subsections": [ { "name": "4.6 'ms'", "content": "The 'ms' (\"manuscript\") package is suitable for the preparation of\nletters, memoranda, reports, and books. These 'groff' macros feature\ncover page and table of contents generation, automatically numbered\nheadings, several paragraph styles, a variety of text styling options,\nfootnotes, and multi-column page layouts. 'ms' supports the 'tbl',\n'eqn', 'pic', and 'refer' preprocessors for inclusion of tables,\nmathematical equations, diagrams, and standardized bibliographic\ncitations. This implementation is mostly compatible with the documented\ninterface and behavior of AT&T Unix Version 7 'ms'. Many extensions\nfrom 4.2BSD (Berkeley) and Tenth Edition Research Unix have been\nrecreated.\n\n* Menu:\n\n* ms Introduction::\n* ms Document Structure::\n* ms Document Control Settings::\n* ms Document Description Macros::\n* ms Body Text::\n* ms Page Layout::\n* Differences from AT&T ms::\n* ms Legacy Features::\n* ms Naming Conventions::\n" } ] }, "File: groff.info, Node: ms Introduction, Next: ms Document Structure, Prev: ms, Up: ms": { "content": "", "subsections": [] }, "The 'ms' macros are the oldest surviving package for 'roff' systems.(1)": { "content": "(*note ms Introduction-Footnote-1::) While the 'man' package was\ndesigned for brief reference documents, the 'ms' macros are also\nsuitable for longer works intended for printing and possible\npublication.\n\n* Menu:\n\n* ms basic information::\n", "subsections": [] }, "File: groff.info, Node: ms basic information, Next: ms Document Structure, Prev: ms Introduction, Up: ms Introduction": { "content": "4.6.1.1 Basic information\n.........................\n\n'ms' documents are plain text files; prepare them with your preferred\ntext editor. If you're in a hurry to start, know that 'ms' needs one of\nits macros called at the beginning of a document so that it can\ninitialize. A \"macro\" is a formatting instruction to 'ms'. Put a macro\ncall on a line by itself. Use '.PP' if you want your paragraph's first\nline to be indented, or '.LP' if you don't.\n\nAfter that, start typing normally. It is a good practice to start\neach sentence on a new line, or to put two spaces after sentence-ending\npunctuation, so that the formatter knows where the sentence boundaries\nare. You can separate paragraphs with further paragraphing macros, or\nwith blank lines, and you can indent with tabs. When you need one of\nthe features mentioned earlier (*note ms::), return to this part of the\nmanual.\n\nFormat the document with the 'groff' command. 'nroff' can be useful\nfor previewing.\n\n$ editor radical.ms\n$ nroff -ww -z -ms radical.ms # check for errors\n$ nroff -ms radical.ms | less -R\n$ groff -T ps -ms radical.ms > radical.ps\n$ see radical.ps\n\nOur 'radical.ms' document might look like this.\n\n.LP\nRadical novelties are so disturbing that they tend to be\nsuppressed or ignored, to the extent that even the\npossibility of their existence in general is more often\ndenied than admitted.\n\n->That's what Dijkstra said, anyway.\n\n'ms' exposes many aspects of document layout to user control via\n'groff''s \"registers\" and \"strings\", which store numbers and text,\nrespectively. Measurements in 'groff' are expressed with a suffix\ncalled a \"scaling unit\".\n\n'i'\ninches\n\n'c'\ncentimeters\n\n'p'\npoints (1/72 inch)\n\n'P'\npicas (1/6 inch)\n\n'v'\nvees; current vertical spacing\n\n'm'\nems; width of an \"M\" in the current font\n\n'n'\nens; one-half em\n\nSet registers with the 'nr' request and strings with the 'ds'\nrequest. \"Requests\" are like macro calls; they go on lines by\nthemselves and start with the \"control character\", a dot ('.'). The\ndifference is that they directly instruct the formatter program, rather\nthan the macro package. We'll discuss a few as applicable. It is wise\nto specify a scaling unit when setting any register that represents a\nlength, size, or distance.\n\n.nr PS 10.5p \\\" Use 10.5-point type.\n.ds FAM P \\\" Use Palatino font family.\n\nIn the foregoing, we see that '\\\"' begins a comment. This is an example\nof an \"escape sequence\", the other kind of formatting instruction.", "subsections": [] }, "Escape sequences can appear anywhere. They begin with the escape": { "content": "character ('\\') and are followed by at least one more character. 'ms'\ndocuments tend to use only a few of 'groff''s many requests and escape\nsequences; see *note Request Index:: and *note Escape Sequence Index::\nor the 'groff(7)' man page for complete lists.\n\n'\\\"'\nBegin comment; ignore remainder of line.\n\n'\\n[REG]'\nInterpolate value of register REG.\n\n'\\*[STR]'\nInterpolate contents of string STR.\n\n'\\*S'\nabbreviation of '\\*[S]'; the name S must be only one character\n\n'\\[CHAR]'\nInterpolate glyph of special character named CHAR.\n\n'\\&'\ndummy character\n\n'\\~'\nInsert an unbreakable space that is adjustable like a normal space.\n\n'\\|'\nMove horizontally by one-sixth em (\"thin space\").\n\nPrefix any words that start with a dot '.' or neutral apostrophe '''\nwith '\\&' if they are at the beginning of an input line (or might become\nthat way in editing) to prevent them from being interpreted as macro\ncalls or requests. Suffix '.', '?', and '!' with '\\&' when needed to\ncancel end-of-sentence detection.\n\nMy exposure was \\&.5 to \\&.6 Sv of neutrons, said Dr.\\&\nWallace after the criticality incident.\n", "subsections": [] }, "File: groff.info, Node: ms Document Structure, Next: ms Document Control Settings, Prev: ms Introduction, Up: ms": { "content": "", "subsections": [] }, "The 'ms' macro package expects a certain amount of structure: a": { "content": "well-formed document contains at least one paragraphing or heading macro\ncall. Longer documents have a structure as follows.\n\n*Document type*\nCalling the 'RP' macro at the beginning of your document puts the\ndocument description (see below) on a cover page. Otherwise, 'ms'\nplaces the information (if any) on the first page, followed\nimmediately by the body text. Some document types found in other\n'ms' implementations are specific to AT&T or Berkeley, and are not\nsupported by 'groff' 'ms'.\n\n*Format and layout*\nBy setting registers and strings, you can configure your document's\ntypeface, margins, spacing, headers and footers, and footnote\narrangement. *Note ms Document Control Settings::.\n\n*Document description*\nA document description consists of any of: a title, one or more\nauthors' names and affiliated institutions, an abstract, and a date\nor other identifier. *Note ms Document Description Macros::.\n\n*Body text*\nThe main matter of your document follows its description (if any).\n'ms' supports highly structured text consisting of paragraphs\ninterspersed with multi-level headings (chapters, sections,\nsubsections, and so forth) and augmented by lists, footnotes,\ntables, diagrams, and similar material. *Note ms Body Text::.\n\n*Tables of contents*\nMacros enable the collection of entries for a table of contents (or\nindex) as the material they discuss appears in the document. You\nthen call a macro to emit the table of contents at the end of your\ndocument. The table of contents must necessarily follow the rest\nof the text since GNU 'troff' is a single-pass formatter; it thus\ncannot determine the page number of a division of the text until it\nhas been set and output. Since 'ms' was designed for the\nproduction of hard copy, the traditional procedure was to manually\nrelocate the pages containing the table of contents between the\ncover page and the body text. Today, page resequencing is more\noften done in the digital domain. An index works similarly, but\nbecause it typically needs to be sorted after collection, its\npreparation requires separate processing.\n", "subsections": [] }, "File: groff.info, Node: ms Document Control Settings, Next: ms Document Description Macros, Prev: ms Document Structure, Up: ms": { "content": "'ms' exposes many aspects of document layout to user control via 'groff'\nrequests. To use them, you must understand how to define registers and\nstrings.\n\n-- Request: .nr reg value\nSet register REG to VALUE. If REG doesn't exist, GNU 'troff'\ncreates it.\n\n-- Request: .ds name contents\nSet string NAME to CONTENTS.\n\nA list of document control registers and strings follows. For any\nparameter whose default is unsatisfactory, define its register or string\nbefore calling any 'ms' macro other than 'RP'.\n", "subsections": [] }, "Margin settings": { "content": "...............\n\n-- Register: \\n[PO]\nDefines the page offset (i.e., the left margin).\n\nEffective: next page.\n\nDefault: Varies by output device and paper format; 1i is used for\ntypesetters using U.S. letter paper, and zero for terminals. *Note\nPaper Format::.\n\n-- Register: \\n[LL]\nDefines the line length (i.e., the width of the body text).\n\nEffective: next paragraph.\n\nDefault: Varies by output device and paper format; 6.5i is used for\ntypesetters using U.S. letter paper (*note Paper Format::) and 65n\non terminals.\n\n-- Register: \\n[LT]\nDefines the title line length (i.e., the header and footer width).\nThis is usually the same as 'LL', but need not be.\n\nEffective: next paragraph.\n\nDefault: Varies by output device and paper format; 6.5i is used for\ntypesetters using U.S. letter paper (*note Paper Format::) and 65n\non terminals.\n\n-- Register: \\n[HM]\nDefines the header margin height at the top of the page.\n\nEffective: next page.\n\nDefault: 1i.\n\n-- Register: \\n[FM]\nDefines the footer margin height at the bottom of the page.\n\nEffective: next page.\n\nDefault: 1i.\n", "subsections": [] }, "Titles (headers, footers)": { "content": ".........................\n\n-- String: \\*[LH]\nDefines the text displayed in the left header position.\n\nEffective: next header.\n\nDefault: empty.\n\n-- String: \\*[CH]\nDefines the text displayed in the center header position.\n\nEffective: next header.\n\nDefault: '-\\n[%]-'.\n\n-- String: \\*[RH]\nDefines the text displayed in the right header position.\n\nEffective: next header.\n\nDefault: empty.\n\n-- String: \\*[LF]\nDefines the text displayed in the left footer position.\n\nEffective: next footer.\n\nDefault: empty.\n\n-- String: \\*[CF]\nDefines the text displayed in the center footer position.\n\nEffective: next footer.\n\nDefault: empty.\n\n-- String: \\*[RF]\nDefines the text displayed in the right footer position.\n\nEffective: next footer.\n\nDefault: empty.\n", "subsections": [] }, "Text settings": { "content": ".............\n\n-- Register: \\n[PS]\nDefines the type size of the body text.\n\nEffective: next paragraph.\n\nDefault: 10p.\n\n-- Register: \\n[VS]\nDefines the vertical spacing (type size plus leading).\n\nEffective: next paragraph.\n\nDefault: 12p.\n\n-- Register: \\n[HY]\nDefines the automatic hyphenation mode used with the 'hy' request.\nSetting 'HY' to 0 is equivalent to using the 'nh' request. This is\na Tenth Edition Research Unix extension.\n\nEffective: next paragraph.\n\nDefault: 6.\n\n-- String: \\*[FAM]\nDefines the font family used to typeset the document. This is a\nGNU extension.\n\nEffective: next paragraph.\n\nDefault: defined by the output device; often 'T' (*note ms Body\nText::)\n", "subsections": [] }, "Paragraph settings": { "content": "..................\n\n-- Register: \\n[PI]\nDefines the indentation amount used by the 'PP', 'IP' (unless\noverridden by an optional argument), 'XP', and 'RS' macros.\n\nEffective: next paragraph.\n\nDefault: 5n.\n\n-- Register: \\n[PD]\nDefines the space between paragraphs.\n\nEffective: next paragraph.\n\nDefault: 0.3v (1v on low-resolution devices).\n\n-- Register: \\n[QI]\nDefines the indentation amount used on both sides of a paragraph\nset with the 'QP' or between the 'QS' and 'QE' macros.\n\nEffective: next paragraph.\n\nDefault: 5n.\n\n-- Register: \\n[PORPHANS]\nDefines the minimum number of initial lines of any paragraph that\nmust be kept together to avoid isolated lines at the bottom of a\npage. If a new paragraph is started close to the bottom of a page,\nand there is insufficient space to accommodate 'PORPHANS' lines\nbefore an automatic page break, then a page break is forced before\nthe start of the paragraph. This is a GNU extension.\n\nEffective: next paragraph.\n\nDefault: 1.\n", "subsections": [] }, "Heading settings": { "content": "................\n\n-- Register: \\n[PSINCR]\nDefines an increment in type size to be applied to a heading at a\nlesser depth than that specified in 'GROWPS'. The value of\n'PSINCR' should be specified in points with the p scaling unit and\nmay include a fractional component; for example, '.nr PSINCR 1.5p'\nsets a type size increment of 1.5p. This is a GNU extension.\n\nEffective: next heading.\n\nDefault: 1p.\n\n-- Register: \\n[GROWPS]\nDefines the heading depth above which the type size increment set\nby 'PSINCR' becomes effective. For each heading depth less than\nthe value of 'GROWPS', the type size is increased by 'PSINCR'.\nSetting 'GROWPS' to any value less than 2 disables the incremental\nheading size feature. This is a GNU extension.\n\nEffective: next heading.\n\nDefault: 0.\n\n-- Register: \\n[HORPHANS]\nDefines the minimum number of lines of an immediately succeeding\nparagraph that should be kept together with any heading introduced\nby the 'NH' or 'SH' macros. If a heading is placed close to the\nbottom of a page, and there is insufficient space to accommodate\nboth the heading and at least 'HORPHANS' lines of the following\nparagraph, before an automatic page break, then the page break is\nforced before the heading. This is a GNU extension.\n\nEffective: next paragraph.\n\nDefault: 1.\n\n-- String: \\*[SN-STYLE]\nDefines the style used to print numbered headings. *Note Headings\nin ms::. This is a GNU extension.\n\nEffective: next heading.\n\nDefault: alias of 'SN-DOT'\n", "subsections": [] }, "Footnote settings": { "content": ".................\n\n-- Register: \\n[FI]\nDefines the footnote indentation. This is a Berkeley extension.\n\nEffective: next footnote.\n\nDefault: 2n.\n\n-- Register: \\n[FF]\nDefines the format of automatically numbered footnotes, and those\nfor which the 'FS' request is given a marker argument, at the\nbottom of a column or page. This is a Berkeley extension.\n'0'\nSet an automatic number(1) (*note ms Document Control\nSettings-Footnote-1::) as a superscript (on typesetter\ndevices) or surrounded by square brackets (on terminals). The\nfootnote paragraph is indented as with 'PP' if there is an\n'FS' argument or an automatic number, and as with 'LP'\notherwise. This is the default.\n\n'1'\nAs '0', but set the marker as regular text and follow an\nautomatic number with a period.\n\n'2'\nAs '1', but without indentation (like 'LP').\n\n'3'\nAs '1', but set the footnote paragraph with the marker hanging\n(like 'IP').\n\nEffective: next footnote.\n\nDefault: 0.\n\n-- Register: \\n[FPS]\nDefines the footnote type size.\n\nEffective: next footnote.\n\nDefault: '\\n[PS] - 2p'.\n\n-- Register: \\n[FVS]\nDefines the footnote vertical spacing.\n\nEffective: next footnote.\n\nDefault: '\\n[FPS] + 2p'.\n\n-- Register: \\n[FPD]\nDefines the footnote paragraph spacing. This is a GNU extension.\n\nEffective: next footnote.\n\nDefault: '\\n[PD] / 2'.\n\n-- String: \\*[FR]\nDefines the ratio of the footnote line length to the current line\nlength. This is a GNU extension.\n\nEffective: next footnote in single-column arrangements, next page\notherwise.\n\nDefault: '11/12'.\n", "subsections": [] }, "Display settings": { "content": "................\n\n-- Register: \\n[DD]\nSets the display distance--the vertical spacing before and after a\ndisplay, a 'tbl' table, an 'eqn' equation, or a 'pic' image. This\nis a Berkeley extension.\n\nEffective: next display boundary.\n\nDefault: 0.5v (1v on low-resolution devices).\n\n-- Register: \\n[DI]\nSets the default amount by which to indent a display started with\n'DS' and 'ID' without arguments, to '.DS I' without an indentation\nargument, and to equations set with '.EQ I'. This is a GNU\nextension.\n\nEffective: next indented display.\n\nDefault: 0.5i.\n", "subsections": [] }, "Other settings": { "content": "..............\n\n-- Register: \\n[MINGW]\nDefines the default minimum width between columns in a multi-column\ndocument. This is a GNU extension.\n\nEffective: next page.\n\nDefault: 2n.\n\n-- Register: \\n[TC-MARGIN]\nDefines the width of the field in which page numbers are set in a\ntable of contents entry; the right margin thus moves inboard by\nthis amount. This is a GNU extension.\n\nEffective: next 'PX' call.\n\nDefault: '\\w'000''\n", "subsections": [] }, "File: groff.info, Node: ms Document Description Macros, Next: ms Body Text, Prev: ms Document Control Settings, Up: ms": { "content": "Only the simplest document lacks a title.(1) (*note ms Document", "subsections": [] }, "Description Macros-Footnote-1::) As its level of sophistication (or": { "content": "complexity) increases, it tends to acquire a date of revision,\nexplicitly identified authors, sponsoring institutions for authors, and,\nat the rarefied heights, an abstract of its content. Define these data\nby calling the macros below in the order shown; 'DA' or 'ND' can be\ncalled to set the document date (or other identifier) at any time before\n(a) the abstract, if present, or (b) its information is required in a\nheader or footer. Use of these macros is optional, except that 'TL' is\nmandatory if any of 'RP', 'AU', 'AI', or 'AB' is called, and 'AE' is\nmandatory if 'AB' is called.\n\n-- Macro: .RP [no-repeat-info] [no-renumber]\nUse the \"report\" (AT&T: \"released paper\") format for your document,\ncreating a separate cover page. The default arrangement is to\nplace most of the document description (title, author names and\ninstitutions, and abstract, but not the date) at the top of the\nfirst page. If the optional 'no-repeat-info' argument is given,\n'ms' produces a cover page but does not repeat any of its\ninformation subsequently (but see the 'DA' macro below regarding\nthe date). Normally, 'RP' sets the page number following the cover\npage to 1. Specifying the optional 'no-renumber' argument\nsuppresses this alteration. Optional arguments can occur in any\norder. 'no' is recognized as a synonym of 'no-repeat-info' for\n'AT&T' compatibility.\n\n-- Macro: .TL\nSpecify the document title. 'ms' collects text on input lines\nfollowing this call into the title until reaching 'AU', 'AB', or a\nheading or paragraphing macro call.\n\n-- Macro: .AU\nSpecify an author's name. 'ms' collects text on input lines\nfollowing this call into the author's name until reaching 'AI',\n'AB', another 'AU', or a heading or paragraphing macro call. Call\nit repeatedly to specify multiple authors.\n\n-- Macro: .AI\nSpecify the preceding author's institution. An 'AU' call is\nusefully followed by at most one 'AI' call; if there are more, the\nlast 'AI' call controls. 'ms' collects text on input lines\nfollowing this call into the author's institution until reaching\n'AU', 'AB', or a heading or paragraphing macro call.\n\n-- Macro: .DA [x ...]\nTypeset the current date, or any arguments X, in the center footer,\nand, if 'RP' is also called, left-aligned at the end of the\ndescription information on the cover page.\n\n-- Macro: .ND [x ...]\nTypeset the current date, or any arguments X, if 'RP' is also\ncalled, left-aligned at the end of the document description on the\ncover page. This is 'groff' 'ms''s default.\n\n-- Macro: .AB [no]\nBegin the abstract. 'ms' collects text on input lines following\nthis call into the abstract until reaching an 'AE' call. By\ndefault, 'ms' places the word \"ABSTRACT\" centered and in italics\nabove the text of the abstract. The optional argument 'no'\nsuppresses this heading.\n\n-- Macro: .AE\nEnd the abstract.\n\nAn example document description, using a cover page, follows.\n\n.RP\n.TL\nThe Inevitability of Code Bloat\nin Commercial and Free Software\n.AU\nJ.\\& Random Luser\n.AI\nUniversity of West Bumblefuzz\n.AB\nThis report examines the long-term growth of the code\nbases in two large,\npopular software packages;\nthe free Emacs and the commercial Microsoft Word.\nWhile differences appear in the type or order of\nfeatures added,\ndue to the different methodologies used,\nthe results are the same in the end.\n.PP\nThe free software approach is shown to be superior in\nthat while free software can become as bloated as\ncommercial offerings,\nfree software tends to have fewer serious bugs and the\nadded features are more in line with user demand.\n.AE\n\n...the rest of the paper...\n", "subsections": [] }, "File: groff.info, Node: ms Body Text, Next: ms Page Layout, Prev: ms Document Description Macros, Up: ms": { "content": "A variety of macros, registers, and strings can be used to structure and\nstyle the body of your document. They organize your text into\nparagraphs, headings, footnotes, and inclusions of material such as\ntables and figures.\n\n* Menu:\n\n* Text settings in ms::\n* Typographical symbols in ms::\n* Paragraphs in ms::\n* Headings in ms::\n* Typeface and decoration::\n* Lists in ms::\n* Indented regions in ms::\n* ms keeps and displays::\n* ms Insertions::\n* ms Footnotes::\n* ms language and localization::\n", "subsections": [] }, "File: groff.info, Node: Text settings in ms, Next: Typographical symbols in ms, Prev: ms Body Text, Up: ms Body Text": { "content": "4.6.5.1 Text settings\n.....................\n", "subsections": [] }, "The 'FAM' string, a GNU extension, sets the font family for body text;": { "content": "the default is 'T'. The 'PS' and 'VS' registers set the type size and\nvertical spacing (distance between text baselines), respectively. The\nfont family and type size are ignored on terminal devices. Setting\nthese parameters before the first call of a heading, paragraphing, or\n(non-date) document description macro also applies them to headers,\nfooters, and (for 'FAM') footnotes.\n\nWhich font families are available depends on the output device; as a\nconvention, 'T' selects a serif family (\"Times\"), 'H' a sans-serif\nfamily (\"Helvetica\"), and 'C' a monospaced family (\"Courier\"). The man\npage for the output driver documents its font repertoire. Consult the\n'groff(1)' man page for lists of available output devices and their\ndrivers.\n\nThe hyphenation mode (as used by the 'hy' request) is set from the\n'HY' register. Setting 'HY' to '0' is equivalent to using the 'nh'\nrequest. This is a Tenth Edition Research Unix extension.\n", "subsections": [] }, "File: groff.info, Node: Typographical symbols in ms, Next: Paragraphs in ms, Prev: Text settings in ms, Up: ms Body Text": { "content": "4.6.5.2 Typographical symbols\n.............................\n\n'ms' provides a few strings to obtain typographical symbols not easily\nentered with the keyboard. These and many others are available as\nspecial character escape sequences--see the 'groffchar(7)' man page.\n\n-- String: \\*[-]\nInterpolate an em dash.\n\n-- String: \\*[Q]\n-- String: \\*[U]\nInterpolate typographer's quotation marks where available, and\nneutral double quotes otherwise. '\\*Q' is the left quote and '\\*U'\nthe right.\n", "subsections": [] }, "File: groff.info, Node: Paragraphs in ms, Next: Headings in ms, Prev: Typographical symbols in ms, Up: ms Body Text": { "content": "4.6.5.3 Paragraphs\n..................\n\nParagraphing macros \"break\", or terminate, any pending output line so\nthat a new paragraph can begin. Several paragraph types are available,\ndiffering in how indentation applies to them: to left, right, or both\nmargins; to the first output line of the paragraph, all output lines, or\nall but the first. All paragraphing macro calls cause the insertion of\nvertical space in the amount stored in the 'PD' register, except at page\nor column breaks. Alternatively, a blank input line breaks the output\nline and vertically spaces by one vee.\n\n-- Macro: .LP\nSet a paragraph without any (additional) indentation.\n\n-- Macro: .PP\nSet a paragraph with a first-line left indentation in the amount\nstored in the 'PI' register.\n\n-- Macro: .IP [marker [width]]\nSet a paragraph with a left indentation. The optional MARKER is\nnot indented and is empty by default. It has several applications;\nsee *note Lists in ms::. WIDTH overrides the indentation amount\nstored in the 'PI' register; its default unit is 'n'. Once\nspecified, WIDTH applies to further 'IP' calls until specified\nagain or a heading or different paragraphing macro is called.\n\n-- Macro: .QP\nSet a paragraph indented from both left and right margins by the\namount stored in the 'QI' register.\n\n-- Macro: .QS\n-- Macro: .QE\nBegin ('QS') and end ('QE') a region where each paragraph is\nindented from both margins by the amount stored in the 'QI'\nregister. The text between 'QS' and 'QE' can be structured further\nby use of other paragraphing macros.\n\n-- Macro: .XP\nSet an \"exdented\" paragraph--one with a left indentation in the\namount stored in the 'PI' register on every line except the first\n(also known as a hanging indent). This is a Berkeley extension.\n\nThe following example illustrates the use of paragraphing macros.\n\n.NH 2\nCases used in the 2001 study\n.LP\nTwo software releases were considered for this report.\n.PP\nThe first is commercial software;\nthe second is free.\n.IP \\[bu]\nMicrosoft Word for Windows,\nstarting with version 1.0 through the current version\n(Word 2000).\n.IP \\[bu]\nGNU Emacs,\nfrom its first appearance as a standalone editor through\nthe current version (v20).\nSee [Bloggs 2002] for details.\n.QP\nFranklin's Law applied to software:\nsoftware expands to outgrow both RAM and disk space over\ntime.\n.SH\nBibliography\n.XP\nBloggs, Joseph R.,\n.I \"Everyone's a Critic\" ,\nUnderground Press, March 2002.\nA definitive work that answers all questions and\ncriticisms about the quality and usability of free\nsoftware.\n", "subsections": [] }, "File: groff.info, Node: Headings in ms, Next: Typeface and decoration, Prev: Paragraphs in ms, Up: ms Body Text": { "content": "4.6.5.4 Headings\n................\n", "subsections": [] }, "Use headings to create a sequential or hierarchical structure for your": { "content": "document. The 'ms' macros print headings in *bold* using the same font\nfamily and, by default, type size as the body text. Headings are\navailable with and without automatic numbering. Text on input lines\nfollowing the macro call becomes the heading's title. Call a\nparagraphing macro to end the heading text and start the section's\ncontent.\n\n-- Macro: .NH [depth]\n-- Macro: .NH S heading-depth-index ...\nSet an automatically numbered heading.\n\n'ms' produces a numbered heading the form A.B.C..., to any depth\ndesired, with the numbering of each depth increasing automatically\nand being reset to zero when a more significant level is increased.\n\"1\" is the most significant or coarsest division of the document.\nOnly non-zero values are output. If DEPTH is omitted, it is taken\nto be '1'.\n\nIf you specify DEPTH such that an ascending gap occurs relative to\nthe previous 'NH' call--that is, you \"skip a depth\", as by '.NH 1'\nand then '.NH 3'--'groff' 'ms' emits a warning on the standard\nerror stream.\n\nAlternatively, you can give 'NH' a first argument of 'S', followed\nby integers to number the heading depths explicitly. Further\nautomatic numbering, if used, resumes using the specified indices\nas their predecessors. This feature is a Berkeley extension.\n\nAn example may be illustrative.\n\n.NH 1\nAnimalia\n.NH 2\nArthropoda\n.NH 3\nCrustacea\n.NH 2\nChordata\n.NH S 6 6 6\nDaimonia\n.NH 1\nPlantae\n\nThe above results in numbering as follows; the vertical space that\nnormally precedes each heading is omitted.\n\n1. Animalia\n1.1. Arthropoda\n1.1.1. Crustacea\n1.2. Chordata\n6.6.6. Daimonia\n7. Plantae\n\n-- String: \\*[SN-STYLE]\n-- String: \\*[SN-DOT]\n-- String: \\*[SN-NO-DOT]\n-- String: \\*[SN]\nAfter 'NH' is called, the assigned number is made available in the\nstrings 'SN-DOT' (as it appears in a printed heading with default\nformatting, followed by a terminating period) and 'SN-NO-DOT' (with\nthe terminating period omitted). These are GNU extensions.\n\nYou can control the style used to print numbered headings by\ndefining an appropriate alias for the string 'SN-STYLE'. By\ndefault, 'SN-STYLE' is aliased to 'SN-DOT'. If you prefer to omit\nthe terminating period from numbers appearing in numbered headings,\nyou may define the alias as follows.\n\n.als SN-STYLE SN-NO-DOT\n\nAny such change in numbering style becomes effective from the next\nuse of 'NH' following redefinition of the alias for 'SN-STYLE'.\nThe formatted number of the current heading is available in the\n'SN' string (a feature first documented by Berkeley), which\nfacilitates its inclusion in, for example, table captions, equation\nlabels, and 'XS'/'XA'/'XE' table of contents entries.\n\n-- Macro: .SH [depth]\nSet an unnumbered heading.\n\nThe optional DEPTH argument is a GNU extension indicating the\nheading depth corresponding to the DEPTH argument of 'NH'. It\nmatches the type size at which the heading is set to that of a\nnumbered heading at the same depth when the 'GROWPS' and 'PSINCR'\nheading size adjustment mechanism is in effect.\n\nIf the 'GROWPS' register is set to a value greater than the LEVEL\nargument to 'NH' or 'SH', the type size of a heading produced by these\nmacros increases by 'PSINCR' units over the size specified by 'PS'\nmultiplied by the difference of 'GROWPS' and LEVEL. The value stored in\n'PSINCR' is interpreted in 'groff' basic units; the 'p' scaling unit\nshould be employed when assigning a value specified in points. For\nexample, the sequence\n\n.nr PS 10\n.nr GROWPS 3\n.nr PSINCR 1.5p\n.NH 1\nCarnivora\n.NH 2\nFelinae\n.NH 3\nFelis catus\n.SH 2\nMachairodontinae\n\nwill cause \"1. Carnivora\" to be printed in 13-point text, followed by\n\"1.1. Felinae\" in 11.5-point text, while \"1.1.1. Felis catus\" and all\nmore deeply nested heading levels will remain in the 10-point text\nspecified by the 'PS' register. \"Machairodontinae\" is printed at 11.5\npoints, since it corresponds to heading level 2.\n\nThe 'HORPHANS' register operates in conjunction with the 'NH' and\n'SH' macros to inhibit the printing of isolated headings at the bottom\nof a page; it specifies the minimum number of lines of an immediately\nsubsequent paragraph that must be kept on the same page as the heading.", "subsections": [] }, "If insufficient space remains on the current page to accommodate the": { "content": "heading and this number of lines of paragraph text, a page break is\nforced before the heading is printed. Any display macro call or 'tbl',\n'pic', or 'eqn' region between the heading and the subsequent paragraph\nsuppresses this grouping. *Note ms keeps and displays:: and *note ms\nInsertions::.\n", "subsections": [] }, "File: groff.info, Node: Typeface and decoration, Next: Lists in ms, Prev: Headings in ms, Up: ms Body Text": { "content": "4.6.5.5 Typeface and decoration\n...............................\n", "subsections": [] }, "The 'ms' macros provide a variety of ways to style text. Attend closely": { "content": "to the ordering of arguments labeled PRE and POST, which is not\nintuitive. Support for PRE arguments is a GNU extension.(1) (*note", "subsections": [] }, "Typeface and decoration-Footnote-1::)": { "content": "-- Macro: .B [text [post [pre]]]\nStyle TEXT in bold, followed by POST in the previous font style\nwithout intervening space, and preceded by PRE similarly. Without\narguments, 'ms' styles subsequent text in bold until the next\nparagraphing, heading, or no-argument typeface macro call.\n\n-- Macro: .R [text [post [pre]]]\nAs 'B', but use the roman style (upright text of normal weight)\ninstead of bold. Argument recognition is a GNU extension.\n\n-- Macro: .I [text [post [pre]]]\nAs 'B', but use an italic or oblique style instead of bold.\n\n-- Macro: .BI [text [post [pre]]]\nAs 'B', but use a bold italic or bold oblique style instead of\nupright bold. This is a Tenth Edition Research Unix extension.\n\n-- Macro: .CW [text [post [pre]]]\nAs 'B', but use a constant-width (monospaced) roman typeface\ninstead of bold. This is a Tenth Edition Research Unix extension.\n\n-- Macro: .BX [text]\nTypeset TEXT and draw a box around it. On terminal devices,\nreverse video is used instead. If you want TEXT to contain space,\nuse unbreakable space or horizontal motion escape sequences ('\\~',\n'\\', '\\^', '\\|', '\\0' or '\\h').\n\n-- Macro: .UL [text [post]]\nTypeset TEXT with an underline. POST, if present, is set after\nTEXT with no intervening space.\n\n-- Macro: .LG\nSet subsequent text in larger type (two points larger than the\ncurrent size) until the next type size, paragraphing, or heading\nmacro call. You can specify this macro multiple times to enlarge\nthe type size as needed.\n\n-- Macro: .SM\nSet subsequent text in smaller type (two points smaller than the\ncurrent size) until the next type size, paragraphing, or heading\nmacro call. You can specify this macro multiple times to reduce\nthe type size as needed.\n\n-- Macro: .NL\nSet subsequent text at the normal type size (the amount in the 'PS'\nregister).\n\nPRE and POST arguments are typically used to simplify the attachment\nof punctuation to styled words. When PRE is used, a hyphenation control\nescape sequence '\\%' that would ordinarily start TEXT must start PRE\ninstead to have the desired effect.\n\nThe CS course's students found one C language keyword\n.CW static ) \\%(\nmost troublesome.\n\nThe foregoing example produces output as follows.\n\nThe CS course's students found one C language keyword (static)\nmost troublesome.\n\nYou can use the output line continuation escape sequence '\\c' to\nachieve the same result (*note Line Continuation::). It is also\nportable to older 'ms' implementations.\n\nThe CS course's students found one C language keyword\n\\%(\\c\n.CW \\%static )\nmost troublesome.\n\n'groff' 'ms' also offers strings to begin and end super- and\nsubscripting. These are GNU extensions.\n\n-- String: \\*[{]\n-- String: \\*[}]\nBegin and end superscripting, respectively.\n\n-- String: \\*[<]\n-- String: \\*[>]\nBegin and end subscripting, respectively.\n\nRather than calling the 'CW' macro, in 'groff' 'ms' you might prefer\nto change the font family to Courier by setting the 'FAM' string to 'C'.", "subsections": [] }, "You can then use all four style macros above, returning to the default": { "content": "family (Times) with '.ds FAM T'. Because changes to 'FAM' take effect\nonly at the next paragraph, 'CW' remains useful to \"inline\" a change to\nthe font family, similarly to the practice of this document in noting\nsyntactical elements of 'ms' and 'groff'.\n", "subsections": [] }, "File: groff.info, Node: Lists in ms, Next: Indented regions in ms, Prev: Typeface and decoration, Up: ms Body Text": { "content": "4.6.5.6 Lists\n.............\n", "subsections": [] }, "The MARKER argument to the 'IP' macro can be employed to present a": { "content": "variety of lists; for instance, you can use a bullet glyph ('\\[bu]') for\nunordered lists, a number (or auto-incrementing register) for numbered\nlists, or a word or phrase for glossary-style or definition lists. If\nyou set the paragraph indentation register 'PI' before calling 'IP', you\ncan later reorder the items in the list without having to ensure that a\nWIDTH argument remains affixed to the first call.\n\nThe following is an example of a bulleted list.\n\n.nr PI 2n\nA bulleted list:\n.IP \\[bu]\nlawyers\n.IP \\[bu]\nguns\n.IP \\[bu]\nmoney\n\nA bulleted list:\n\n* lawyers\n\n* guns\n\n* money\n\nThe following is an example of a numbered list.\n\n.nr step 0 1\n.nr PI 3n\nA numbered list:\n.IP \\n+[step]\nlawyers\n.IP \\n+[step]\nguns\n.IP \\n+[step]\nmoney\n\nA numbered list:\n\n1. lawyers\n\n2. guns\n\n3. money\n\nHere we have employed the 'nr' request to create a register of our\nown, 'step'. We initialized it to zero and assigned it an\nauto-increment of 1. Each time we use the escape sequence '\\n+[PI]'\n(note the plus sign), the formatter applies the increment just before\ninterpolating the register's value. Preparing the 'PI' register as well\nenables us to rearrange the list without the tedium of updating macro\ncalls.\n\nThe next example illustrates a glossary-style list.\n\nA glossary-style list:\n.IP lawyers 0.4i\nTwo or more attorneys.\n.IP guns\nFirearms,\npreferably large-caliber.\n.IP money\nGotta pay for those\nlawyers and guns!\n\nA glossary-style list:\n\nlawyers\nTwo or more attorneys.\n\nguns Firearms, preferably large-caliber.\n\nmoney\nGotta pay for those lawyers and guns!\n\nIn the previous example, observe how the 'IP' macro places the\ndefinition on the same line as the term if it has enough space. If this\nis not what you want, there are a few workarounds we will illustrate by\nmodifying the example. First, you can use a 'br' request to force a\nbreak after printing the term or label.\n\n.IP guns\n.br\nFirearms,\n\nSecond, you could apply the '\\p' escape sequence to force a break.", "subsections": [] }, "The space following the escape sequence is important; if you omit it,": { "content": "'groff' prints the first word of the paragraph text on the same line as\nthe term or label (if it fits) then breaks the line.\n\n.IP guns\n\\p Firearms,\n\nFinally, you may append a horizontal motion to the marker with the\n'\\h' escape sequence; using the same amount as the indentation will\nensure that the marker is too wide for 'groff' to treat it as \"fitting\"\non the same line as the paragraph text.\n\n.IP guns\\h'0.4i'\nFirearms,\n\nIn each case, the result is the same.\n\nA glossary-style list:\n\nlawyers\nTwo or more attorneys.\n\nguns\nFirearms, preferably large-caliber.\n\nmoney\nGotta pay for those lawyers and guns!\n", "subsections": [] }, "File: groff.info, Node: Indented regions in ms, Next: ms keeps and displays, Prev: Lists in ms, Up: ms Body Text": { "content": "4.6.5.7 Indented regions\n........................\n", "subsections": [] }, "You may need to indent a region of text while otherwise formatting it": { "content": "normally. Indented regions can be nested; you can change '\\n[PI]'\nbefore each call to vary the amount of inset.\n\n-- Macro: .RS\nBegin a region where headings, paragraphs, and displays are\nindented (further) by the amount stored in the 'PI' register.\n\n-- Macro: .RE\nEnd the (next) most recent indented region.\n\nThis feature enables you to easily line up text under hanging and\nindented paragraphs. For example, you may wish to structure lists\nhierarchically.\n\n.IP \\[bu] 2\nLawyers:\n.RS\n.IP \\[bu]\nDewey,\n.IP \\[bu]\nCheatham,\nand\n.IP \\[bu]\nand Howe.\n.RE\n.IP \\[bu]\nGuns\n\n* Lawyers:\n\n* Dewey,\n\n* Cheatham, and\n\n* Howe.\n\n* Guns\n", "subsections": [] }, "File: groff.info, Node: ms keeps and displays, Next: ms Insertions, Prev: Indented regions in ms, Up: ms Body Text": { "content": "4.6.5.8 Keeps, boxed keeps, and displays\n........................................\n\nOn occasion, you may want to \"keep\" several lines of text, or a region\nof a document, together on a single page, preventing an automatic page\nbreak within certain boundaries. This can cause a page break to occur\nearlier than it normally would. For example, you may want to keep two\nparagraphs together, or a paragraph that refers to a table, list, or\nfigure adjacent to the item it discusses. 'ms' provides the 'KS' and\n'KE' macros for this purpose.\n\nYou can alternatively specify a \"floating keep\": if a keep cannot fit\non the current page, 'ms' holds its contents and allows material\nfollowing the keep (in the source document) to fill the remainder of the\ncurrent page. When the page breaks, whether by reaching the end or 'bp'\nrequest, 'ms' puts the floating keep at the beginning of the next page.", "subsections": [] }, "This is useful for placing large graphics or tables that do not need to": { "content": "appear exactly where they occur in the source document.\n\n-- Macro: .KS\n-- Macro: .KF\n-- Macro: .KE\n'KS' begins a keep, 'KF' a floating keep, and 'KE' ends a keep of\neither kind.\n\nAs an alternative to the keep mechanism, the 'ne' request forces a\npage break if there is not at least the amount of vertical space\nspecified in its argument remaining on the page (*note Page Control::).", "subsections": [] }, "One application of 'ne' is to reserve space on the page for a figure or": { "content": "illustration to be included later.\n\nA \"boxed keep\" has a frame drawn around it.\n\n-- Macro: .B1\n-- Macro: .B2\n'B1' begins a keep with a box drawn around it. 'B2' ends a boxed\nkeep.\n\nBoxed keep macros cause breaks; if you need to box a word or phrase\nwithin a line, see the 'BX' macro in *note Typeface and decoration::.", "subsections": [] }, "Box lines are drawn as close as possible to the text they enclose so": { "content": "that they are usable within paragraphs. If you wish to box one or more\nparagraphs, you may improve the appearance by calling 'B1' after the\nfirst paragraphing macro, and by adding a small amount of vertical space\nbefore calling 'B2'.\n\n.LP\n.B1\n.I Warning:\nHappy Fun Ball may suddenly accelerate to dangerous\nspeeds.\n.sp \\n[PD]/2 \\\" space by half the inter-paragraph distance\n.B2\n\nIf you want a boxed keep to float, you will need to enclose the 'B1'\nand 'B2' calls within a pair of 'KF' and 'KE' calls.\n\n\"Displays\" turn off filling; lines of verse or program code are shown\nwith their lines broken as in the source document without requiring 'br'\nrequests between lines. Displays can be kept on a single page or\nallowed to break across pages. The 'DS' macro begins a kept display of\nthe layout specified in its first argument; non-kept displays are begun\nwith dedicated macros corresponding to their layout.\n\n-- Macro: .DS L\n-- Macro: .LD\nBegin ('DS': kept) left-aligned display.\n\n-- Macro: .DS [I [indent]]\n-- Macro: .ID [indent]\nBegin ('DS': kept) display indented by INDENT if specified, and by\nthe amount of the 'DI' register otherwise.\n\n-- Macro: .DS B\n-- Macro: .BD\nBegin a ('DS': kept) a block display: the entire display is\nleft-aligned, but indented such that the longest line in the\ndisplay is centered on the page.\n\n-- Macro: .DS C\n-- Macro: .CD\nBegin a ('DS': kept) centered display: each line in the display is\ncentered.\n\n-- Macro: .DS R\n-- Macro: .RD\nBegin a ('DS': kept) right-aligned display. This is a GNU\nextension.\n\n-- Macro: .DE\nEnd any display.\n\nThe distance stored in the 'DD' register is inserted before and after\neach pair of display macros; this is a Berkeley extension. In 'groff'\n'ms', this distance replaces any adjacent inter-paragraph distance or\nsubsequent spacing prior to a section heading. The 'DI' register is a\nGNU extension; its value is an indentation applied to displays created\nwith '.DS' and '.ID' without arguments, to '.DS I' without an\nindentation argument, and to indented equations set with '.EQ'. Changes\nto either register take effect at the next display boundary.\n", "subsections": [] }, "File: groff.info, Node: ms Insertions, Next: ms Footnotes, Prev: ms keeps and displays, Up: ms Body Text": { "content": "4.6.5.9 Tables, figures, equations, and references\n..................................................\n", "subsections": [] }, "The 'ms' package is often used with the 'tbl', 'pic', 'eqn', and 'refer'": { "content": "preprocessors. Mark text meant for preprocessors by enclosing it in\npairs of tokens as follows, with nothing between the dot and the macro\nname. The preprocessors match these tokens only at the start of an\ninput line.\n\n-- Macro: .TS [H]\n-- Macro: .TE\nDemarcate a table to be processed by the 'tbl' preprocessor. The\noptional argument 'H' to 'TS' instructs 'ms' to repeat table rows\n(often column headings) at the top of each new page the table\nspans, if applicable; calling the 'TH' macro marks the end of such\nrows. The GNU 'tbl(1)' man page provides a comprehensive reference\nto the preprocessor and offers examples of its use.\n\n-- Macro: .PS\n-- Macro: .PE\n-- Macro: .PF\n'PS' begins a picture to be processed by the 'gpic' preprocessor;\neither of 'PE' or 'PF' ends it, the latter with \"flyback\" to the\nvertical position at its top. You can create 'pic' input manually\nor with a program such as 'xfig'.\n\n-- Macro: .EQ [align [label]]\n-- Macro: .EN\nDemarcate an equation to be processed by the 'eqn' preprocessor.\nThe equation is centered by default; ALIGN can be 'C', 'L', or 'I'\nto (explicitly) center, left-align, or indent it by the amount\nstored in the 'DI' register, respectively. If specified, LABEL is\nset right-aligned.\n\n-- Macro: .[\n-- Macro: .]\nDemarcate a bibliographic citation to be processed by the 'refer'\npreprocessor. The GNU 'refer(1)' man page provides a comprehensive\nreference to the preprocessor and the format of its bibliographic\ndatabase. Type 'man refer' at the command line to view it.\n\nWhen 'refer' emits collected references (as might be done on a \"Works\nCited\" page), it interpolates the 'REFERENCES' string as an unnumbered\nheading ('SH').\n\nThe following is an example of how to set up a table that may print\nacross two or more pages.\n\n.TS H\nallbox;\nCb | Cb .\nPart->Description\n\n.TH\n.T&\nGH-1978->Fribulating gonkulator\n...the rest of the table follows...\n.TE\n", "subsections": [] }, "Attempting to place a multi-page table inside a keep can lead to": { "content": "unpleasant results, particularly if the 'tbl' 'allbox' option is used.\n\nMathematics can be typeset using the language of the 'eqn'\npreprocessor.\n\n.EQ C (\\*[SN-NO-DOT]a)\np ~ = ~ q sqrt { ( 1 + ~ ( x / q sup 2 ) }\n.EN\n", "subsections": [] }, "This input formats a labelled equation. We used the 'SN-NO-DOT' string": { "content": "to base the equation label on the current heading number, giving us more\nflexibility to reorganize the document.\n\nUse 'groff' options to run preprocessors on the input: '-e' for\n'geqn', '-p' for 'gpic', '-R' for 'grefer', and '-t' for 'gtbl'.\n", "subsections": [] }, "File: groff.info, Node: ms Footnotes, Prev: ms Insertions, Up: ms Body Text": { "content": "4.6.5.10 Footnotes\n..................\n\nA footnote is typically anchored to a place in the text with a \"marker\",\nwhich is a small integer, a symbol such as a dagger, or arbitrary\nuser-specified text.\n\n-- String: \\*[*]\nPlace an \"automatic number\", an automatically generated numeric\nfootnote marker, in the text. Each time this string is\ninterpolated, the number it produces increments by one. Automatic\nnumbers start at 1. This is a Berkeley extension.\n\nEnclose the footnote text in 'FS' and 'FE' macro calls to set it at\nthe nearest available \"foot\", or bottom, of a text column or page.\n\n-- Macro: .FS [marker]\n-- Macro: .FE\nBegin ('FS') and end ('FE') a footnote. 'FS' calls 'FS-MARK' with\nany supplied MARKER argument, which is then also placed at the\nbeginning of the footnote text. If MARKER is omitted, the next\npending automatic footnote number enqueued by interpolation of the\n'*' string is used, and if none exists, nothing is prefixed.\n\nYou may not desire automatically numbered footnotes in spite of their\nconvenience. You can indicate a footnote with a symbol or other text by\nspecifying its marker at the appropriate place (for example, by using\n'\\[dg]' for the dagger glyph) and as an argument to the 'FS' macro.", "subsections": [] }, "Such manual marks should be repeated as arguments to 'FS' or as part of": { "content": "the footnote text to disambiguate their correspondence. You may wish to\nuse '\\*{' and '\\*}' to superscript the marker at the anchor point, in\nthe footnote text, or both.\n\n'groff' 'ms' provides a hook macro, 'FS-MARK', for user-determined\noperations to be performed when the 'FS' macro is called. It is passed\nthe same arguments as 'FS' itself. An application of 'FS-MARK' is\nanchor placement for a hyperlink reference, so that a footnote can link\nback to its referential context.(1) (*note ms Footnotes-Footnote-1::)", "subsections": [] }, "By default, this macro has an empty definition. 'FS-MARK' is a GNU": { "content": "extension.\n\nFootnotes can be safely used within keeps and displays, but you\nshould avoid using automatically numbered footnotes within floating\nkeeps. You can place a second '\\' interpolation between a '\\' and\nits corresponding 'FS' call as long as each 'FS' call occurs after the\ncorresponding '\\' and occurrences of 'FS' are in the same order as\ncorresponding occurrences of '\\'.\n\nFootnote text is formatted as paragraphs are, using analogous\nparameters. The registers 'FI', 'FPD', 'FPS', and 'FVS' correspond to\n'PI', 'PD', 'PS', and 'CS', respectively; 'FPD', 'FPS', and 'FVS' are\nGNU extensions.\n\nThe 'FF' register controls the formatting of automatically numbered\nfootnote paragraphs and those for which 'FS' is given a marker argument.\n*Note ms Document Control Settings::.\n\nThe default footnote line length is 11/12ths of the normal line\nlength for compatibility with the expectations of historical 'ms'\ndocuments; you may wish to set the 'FR' string to '1' to align with\ncontemporary typesetting practices. In the past,(2) (*note ms", "subsections": [] }, "Footnotes-Footnote-2::) an 'FL' register was used for the line length in": { "content": "footnotes; however, setting this register at document initialization\ntime had no effect on the footnote line length in multi-column\narrangements.(3) (*note ms Footnotes-Footnote-3::)\n\n'FR' should be used in preference to the old 'FL' register in\ncontemporary documents. The footnote line length is effectively\ncomputed as 'column-width * \\*[FR]'. If an absolute footnote line\nlength is required, recall that arithmetic expressions in 'roff' input\nare evaluated strictly from left to right, with no operator precedence\n(parentheses are honored).\n\n.ds FR 0+3i \\\" Set footnote line length to 3 inches.\n", "subsections": [] }, "File: groff.info, Node: ms language and localization, Next: ms Page Layout, Prev: ms Footnotes, Up: ms Body Text": { "content": "4.6.5.11 Language and localization\n..................................\n\n'groff' 'ms' provides several strings that you can customize for your\nown purposes, or redefine to adapt the macro package to languages other\nthan English. It is already localized for Czech, German, French,", "subsections": [] }, "Italian, and Swedish. Load the desired localization macro package after": { "content": "'ms'; see the 'grofftmac(5)' man page.\n\n$ groff -ms -mfr bienvenue.ms\n\nThe following strings are available.\n\n-- String: \\*[REFERENCES]\nContains the string printed at the beginning of a references\n(bibliography) page produced with GNU 'refer(1)'. The default is\n'References'.\n\n-- String: \\*[ABSTRACT]\nContains the string printed at the beginning of the abstract. The\ndefault is '\\f[I]ABSTRACT\\f[]'; it includes font selection escape\nsequences to set the word in italics.\n\n-- String: \\*[TOC]\nContains the string printed at the beginning of the table of\ncontents. The default is 'Table of Contents'.\n\n-- String: \\*[MONTH1]\n-- String: \\*[MONTH2]\n-- String: \\*[MONTH3]\n-- String: \\*[MONTH4]\n-- String: \\*[MONTH5]\n-- String: \\*[MONTH6]\n-- String: \\*[MONTH7]\n-- String: \\*[MONTH8]\n-- String: \\*[MONTH9]\n-- String: \\*[MONTH10]\n-- String: \\*[MONTH11]\n-- String: \\*[MONTH12]\nContain the full names of the calendar months. The defaults are in\nEnglish: 'January', 'February', and so on.\n\nFile: groff.info, Node: ms Page Layout, Next: Differences from AT&T ms, Prev: ms Body Text, Up: ms\n\n\n'ms''s default page layout arranges text in a single column with the\npage number between hyphens centered in a header on each page except the\nfirst, and produces no footers. You can customize this arrangement.\n\n* Menu:\n\n* ms Headers and Footers::\n* Tab Stops in ms::\n* ms Margins::\n* ms Multiple Columns::\n* ms TOC::\n", "subsections": [] }, "File: groff.info, Node: ms Headers and Footers, Next: Tab Stops in ms, Prev: ms Page Layout, Up: ms Page Layout": { "content": "4.6.6.1 Headers and footers\n...........................\n", "subsections": [] }, "There are multiple ways to produce headers and footers. One is to": { "content": "define the strings 'LH', 'CH', and 'RH' to set the left, center, and\nright headers, respectively; and 'LF', 'CF', and 'RF' to set the left,\ncenter, and right footers. This approach suffices for documents that do\nnot distinguish odd- and even-numbered pages.\n\nAnother method is to call macros that set headers or footers for odd-\nor even-numbered pages. Each such macro takes a delimited argument\nseparating the left, center, and right header or footer texts from each\nother. You can replace the neutral apostrophes (''') shown below with\nany character not appearing in the header or footer text. These macros\nare Berkeley extensions.\n\n-- Macro: .OH 'left'center'right'\n-- Macro: .EH 'left'center'right'\n-- Macro: .OF 'left'center'right'\n-- Macro: .EF 'left'center'right'\nThe 'OH' and 'EH' macros define headers for odd- (recto) and\neven-numbered (verso) pages, respectively; the 'OF' and 'EF' macros\ndefine footers for them.\n\nWith either method, a percent sign '%' in header or footer text is\nreplaced by the current page number. By default, 'ms' places no header\non a page numbered \"1\" (regardless of its number format).\n\n-- Macro: .P1\nTypeset the header even on page 1. To be effective, this macro\nmust be called before the header trap is sprung on any page\nnumbered \"1\"; in practice, unless your page numbering is unusual,\nthis means that you should call it early, before 'TL' or any\nheading or paragraphing macro. This is a Berkeley extension.\n\nFor even greater flexibility, 'ms' is designed to permit the\nredefinition of the macros that are called when the 'groff' traps that\nordinarily cause the headers and footers to be output are sprung. 'PT'\n(\"page trap\") is called by 'ms' when the header is to be written, and\n'BT' (\"bottom trap\") when the footer is to be. The 'groff' page\nlocation trap that 'ms' sets up to format the header also calls the\n(normally undefined) 'HD' macro after 'PT'; you can define 'HD' if you\nneed additional processing after setting the header (for example, to\ndraw a line below it). The 'HD' hook is a Berkeley extension. Any such\nmacros you (re)define must implement any desired specialization for\nodd-, even-, or first numbered pages.\n", "subsections": [] }, "File: groff.info, Node: Tab Stops in ms, Next: ms Margins, Prev: ms Headers and Footers, Up: ms Page Layout": { "content": "4.6.6.2 Tab stops\n.................\n\nUse the 'ta' request to define tab stops as needed. *Note Tabs and\nFields::.\n\n-- Macro: .TA\nReset the tab stops to the 'ms' default (every 5 ens). Redefine\nthis macro to create a different set of default tab stops.\n", "subsections": [] }, "File: groff.info, Node: ms Margins, Next: ms Multiple Columns, Prev: Tab Stops in ms, Up: ms Page Layout": { "content": "4.6.6.3 Margins\n...............\n\nControl margins using the registers summarized in \"Margin settings\" in\n*note ms Document Control Settings:: above. There is no setting for the\nright margin; the combination of page offset '\\n[PO]' and line length\n'\\n[LL]' determines it.\n", "subsections": [] }, "File: groff.info, Node: ms Multiple Columns, Next: ms TOC, Prev: ms Margins, Up: ms Page Layout": { "content": "4.6.6.4 Multiple columns\n........................\n\n'ms' can set text in as many columns as reasonably fit on the page. The\nfollowing macros force a page break if a multi-column layout is active\nwhen they are called. The 'MINGW' register stores the default minimum\ngutter width; it is a GNU extension. When multiple columns are in use,\nkeeps and the 'HORPHANS' and 'PORPHANS' registers work with respect to\ncolumn breaks instead of page breaks.\n\n-- Macro: .1C\nArrange page text in a single column (the default).\n\n-- Macro: .2C\nArrange page text in two columns.\n\n-- Macro: .MC [column-width [gutter-width]]\nArrange page text in multiple columns. If you specify no\narguments, it is equivalent to the '2C' macro. Otherwise,\nCOLUMN-WIDTH is the width of each column and GUTTER-WIDTH is the\nminimum distance between columns.\n\nFile: groff.info, Node: ms TOC, Next: Differences from AT&T ms, Prev: ms Multiple Columns, Up: ms Page Layout\n\n4.6.6.5 Creating a table of contents\n....................................\n", "subsections": [] }, "Because 'roff' formatters process their input in a single pass, material": { "content": "on page 50, for example, cannot influence what appears on page 1--this\nposes a challenge for a table of contents at its traditional location in\nfront matter, if you wish to avoid manually maintaining it. 'ms'\nenables the collection of material to be presented in the table of\ncontents as it appears, saving its page number along with it, and then\nemitting the collected contents on demand toward the end of the\ndocument. The table of contents can then be resequenced to its desired\nlocation by physically rearranging the pages of a printed document, or\nas part of post-processing--with a 'sed(1)' script to reorder the pages\nin 'troff''s output, with 'pdfjam(1)', or with 'gropdf(1)''s\n'.pdfswitchtopage' feature, for example.\n\nDefine an entry to appear in the table of contents by bracketing its\ntext between calls to the 'XS' and 'XE' macros. A typical application\nis to call them immediately after 'NH' or 'SH' and repeat the heading\ntext within them. The 'XA' macro, used within '.XS'/'.XE' pairs,\nsupplements an entry--for instance, when it requires multiple output\nlines, whether because a heading is too long to fit or because style\ndictates that page numbers not be repeated. You may wish to indent the\ntext thus wrapped to correspond to its heading depth; this can be done\nin the entry text by prefixing it with tabs or horizontal motion escape\nsequences, or by providing a second argument to the 'XA' macro. 'XS'\nand 'XA' automatically associate the page number where they are called\nwith the text following them, but they accept arguments to override this\nbehavior. At the end of the document, call 'TC' or 'PX' to emit the\ntable of contents; 'TC' resets the page number to 'i' (Roman numeral\none), and then calls 'PX'. All of these macros are Berkeley extensions.\n\n-- Macro: .XS [page-number]\n-- Macro: .XA [page-number [indentation]]\n-- Macro: .XE\nBegin, supplement, and end a table of contents entry. Each entry\nis associated with PAGE-NUMBER (otherwise the current page number);\na PAGE-NUMBER of 'no' prevents a leader and page number from being\nemitted for that entry. Use of 'XA' within 'XS'/'XE' is optional;\nit can be repeated. If INDENTATION is present, a supplemental\nentry is indented by that amount; ens are assumed if no unit is\nindicated. Text on input lines between 'XS' and 'XE' is stored for\nlater recall by 'PX'.\n\n-- Macro: .PX [no]\nSwitch to single-column layout. Unless 'no' is specified, center\nand interpolate the 'TOC' string in bold and two points larger than\nthe body text. Emit the table of contents entries.\n\n-- Macro: .TC [no]\nSet the page number to 1, the page number format to lowercase Roman\nnumerals, and call 'PX' (with a 'no' argument, if present).\n\nHere's an example of typical 'ms' table of contents preparation. We\nemploy horizontal escape sequences '\\h' to indent the entries by\nsectioning depth.\n\n.NH 1\nIntroduction\n.XS\nIntroduction\n.XE\n...\n.NH 2\nMethodology\n.XS\n\\h'2n'Methodology\n.XA\n\\h'4n'Fassbinder's Approach\n\\h'4n'Kahiu's Approach\n.XE\n...\n.NH 1\nFindings\n.XS\nFindings\n.XE\n...\n.TC\n\nThe remaining features in this subsubsection are GNU extensions.\n'groff' 'ms' obviates the need to repeat heading text after 'XS' calls.\nCall 'XN' and 'XH' after 'NH' and 'SH', respectively.\n\n-- Macro: .XN heading-text\n-- Macro: .XH depth heading-text\nFormat HEADING-TEXT and create a corresponding table of contents\nentry. 'XN' computes the indentation from the depth of the\npreceding 'NH' call; 'XH' requires a DEPTH argument to do so.\n\n'groff' 'ms' encourages customization of table of contents entry\nproduction.\n\n-- Macro: .XN-REPLACEMENT heading-text\n-- Macro: .XH-REPLACEMENT depth heading-text\nThese hook macros implement 'XN' and 'XH', respectively. They call\n'XN-INIT' and pass their HEADING-TEXT arguments to 'XH-UPDATE-TOC'.\n\n-- Macro: .XN-INIT\n-- Macro: .XH-UPDATE-TOC depth heading-text\nThe 'XN-INIT' hook macro does nothing by default. 'XH-UPDATE-TOC'\nbrackets HEADING-TEXT with 'XS' and 'XE' calls, indenting it by 2\nens per level of DEPTH beyond the first.\n\nWe could therefore produce a table of contents similar to that in the\nprevious example with fewer macro calls. (The difference is that this\ninput follows the \"Approach\" entries with leaders and page numbers.)\n\n.NH 1\n.XN Introduction\n...\n.NH 2\n.XN Methodology\n.XH 3 \"Fassbinder's Approach\"\n.XH 3 \"Kahiu's Approach\"\n...\n.NH 1\n.XN Findings\n...\n\nTo get the section number of the numbered headings into the table of\ncontents entries, we might define 'XN-REPLACEMENT' as follows. (We\nobtain the heading depth from 'groff' 'ms''s internal register 'nh*hl'.)\n\n.de XN-REPLACEMENT\n.XN-INIT\n.XH-UPDATE-TOC \\\\n[nh*hl] \\\\$@\n\\&\\\\*[SN] \\\\$*\n..\n\nYou can change the style of the leader that bridges each table of\ncontents entry with its page number; define the 'TC-LEADER' special\ncharacter by using the 'char' request. A typical leader combines the\ndot glyph '.' with a horizontal motion escape sequence to spread the\ndots. The width of the page number field is stored in the 'TC-MARGIN'\nregister.\n\nFile: groff.info, Node: Differences from AT&T ms, Next: ms Naming Conventions, Prev: ms Page Layout, Up: ms\n\n", "subsections": [] }, "The 'groff' 'ms' macros are an independent reimplementation, using no": { "content": "AT&T code. Since they take advantage of the extended features of\n'groff', they cannot be used with AT&T 'troff'. 'groff' 'ms' supports\nfeatures described above as Berkeley and Tenth Edition Research Unix\nextensions, and adds several of its own.\n\n* The internals of 'groff' 'ms' differ from the internals of AT&T\n'ms'. Documents that depend upon implementation details of AT&T\n'ms' may not format properly with 'groff' 'ms'. Such details\ninclude macros whose function was not documented in the AT&T 'ms'\nmanual.(1) (*note Differences from AT&T ms-Footnote-1::)\n\n* The error-handling policy of 'groff' 'ms' is to detect and report\nerrors, rather than to ignore them silently.\n\n* Tenth Edition Research Unix supported 'P1'/'P2' macros to bracket\ncode examples; 'groff' 'ms' does not.\n\n* 'groff' 'ms' does not work in GNU 'troff''s AT&T compatibility\nmode. If loaded when that mode is enabled, it aborts processing\nwith a diagnostic message.\n\n* Multiple line spacing is not supported. Use a larger vertical\nspacing instead.\n\n* 'groff' 'ms' uses the same header and footer defaults in both\n'nroff' and 'troff' modes as AT&T 'ms' does in 'troff' mode; AT&T's\ndefault in 'nroff' mode is to put the date, in U.S. traditional\nformat (e.g., \"January 1, 2021\"), in the center footer (the 'CF'\nstring).\n\n* Many 'groff' 'ms' macros, including those for paragraphs, headings,\nand displays, cause a reset of paragraph rendering parameters, and\nmay change the indentation; they do so not by incrementing or\ndecrementing it, but by setting it absolutely. This can cause\nproblems for documents that define additional macros of their own\nthat try to manipulate indentation. Use the 'ms' 'RS' and 'RE'\nmacros instead of the 'in' request.\n\n* AT&T 'ms' interpreted the values of the registers 'PS' and 'VS' in\npoints, and did not support the use of scaling units with them.\n'groff' 'ms' interprets values of the registers 'PS', 'VS', 'FPS',\nand 'FVS' equal to or larger than 1,000 (one thousand) as decimal\nfractions multiplied by 1,000.(2) (*note Differences from AT&T\nms-Footnote-2::) This threshold makes use of a scaling unit with\nthese parameters practical for high-resolution devices while\npreserving backward compatibility. It also permits expression of\nnon-integral type sizes. For example, 'groff -rPS=10.5p' at the\nshell prompt is equivalent to placing '.nr PS 10.5p' at the\nbeginning of the document.\n\n* AT&T 'ms''s 'AU' macro supported arguments used with some document\ntypes; 'groff' 'ms' does not.\n\n* Right-aligned displays are available. The AT&T 'ms' manual\nobserves that \"it is tempting to assume that '.DS R' will right\nadjust lines, but it doesn't work\". In 'groff' 'ms', it does.\n\n* To make 'groff' 'ms' use the default page offset (which also\nspecifies the left margin), the 'PO' register must stay undefined\nuntil the first 'ms' macro is called.\n\nThis implies that '\\n[PO]' should not be used early in the\ndocument, unless it is changed also: accessing an undefined\nregister automatically defines it.\n\n* 'groff' 'ms' supports the 'PN' register, but it is not necessary;\nyou can access the page number via the usual '%' register and\ninvoke the 'af' request to assign a different format to it if\ndesired.(3) (*note Differences from AT&T ms-Footnote-3::)\n\n* The AT&T 'ms' manual documents registers 'CW' and 'GW' as setting\nthe default column width and \"intercolumn gap\", respectively, and\nwhich applied when 'MC' was called with fewer than two arguments.\n'groff' 'ms' instead treats 'MC' without arguments as synonymous\nwith '2C'; there is thus no occasion for a default column width\nregister. Further, the 'MINGW' register and the second argument to\n'MC' specify a minimum space between columns, not the fixed\ngutter width of AT&T 'ms'.\n\n* The AT&T 'ms' manual did not document the 'QI' register; Berkeley\nand 'groff' 'ms' do.\n\n-- Register: \\n[GS]\nThe register 'GS' is set to 1 by the 'groff' 'ms' macros, but is\nnot used by the AT&T 'ms' package. Documents that need to\ndetermine whether they are being formatted with 'groff' 'ms' or\nanother implementation should test this register.\n\n* Menu:\n\n* Missing Unix Version 7 ms Macros::\n\nFile: groff.info, Node: Missing Unix Version 7 ms Macros, Prev: Differences from AT&T ms, Up: Differences from AT&T ms\n\n4.6.7.1 Unix Version 7 'ms' macros not implemented by 'groff' 'ms'\n..................................................................\n", "subsections": [] }, "Several macros described in the Unix Version 7 'ms' documentation are": { "content": "unimplemented by 'groff' 'ms' because they are specific to the\nrequirements of documents produced internally by Bell Laboratories, some\nof which also require a glyph for the Bell System logo that 'groff' does\nnot support. These macros implemented several document type formats\n('EG', 'IM', 'MF', 'MR', 'TM', 'TR'), were meaningful only in\nconjunction with the use of certain document types ('AT', 'CS', 'CT',\n'OK', 'SG'), stored the postal addresses of Bell Labs sites ('HO', 'IH',\n'MH', 'PY', 'WH'), or lacked a stable definition over time ('UX'). To\ncompatibly render historical 'ms' documents using these macros, we\nadvise your documents to invoke the 'rm' request to remove any such\nmacros it uses and then define replacements with an authentically\ntypeset original at hand.(1) (*note Missing Unix Version 7 ms", "subsections": [] }, "Macros-Footnote-1::) For informal purposes, a simple definition of 'UX'": { "content": "should maintain the readability of the document's substance.\n\n.rm UX\n.ds UX Unix\\\"\n\nFile: groff.info, Node: ms Legacy Features, Next: ms Naming Conventions, Prev: Differences from AT&T ms, Up: ms\n\n\n'groff' 'ms' retains some legacy features solely to support formatting\nof historical documents; contemporary ones should not use them because\nthey can render poorly. See the 'groffchar(7)' man page.\n\nAT&T accent mark strings\n........................\n\nAT&T 'ms' defined accent mark strings as follows.\n\n-- String: \\*[']\nApply acute accent to subsequent glyph.\n\n-- String: \\*[`]\nApply grave accent to subsequent glyph.\n\n-- String: \\*[:]\nApply dieresis (umlaut) to subsequent glyph.\n\n-- String: \\*[^]\nApply circumflex accent to subsequent glyph.\n\n-- String: \\*[~]\nApply tilde accent to subsequent glyph.\n\n-- String: \\*[C]\nApply caron to subsequent glyph.\n\n-- String: \\*[,]\nApply cedilla to subsequent glyph.\n", "subsections": [] }, "Berkeley accent mark and glyph strings": { "content": "......................................\n\nBerkeley 'ms' offered an 'AM' macro; calling it redefined the AT&T\naccent mark strings (except for '\\*C'), applied them to the preceding\nglyph, and defined additional strings, some for spacing glyphs.\n\n-- Macro: .AM\nEnable alternative accent mark and glyph-producing strings.\n\n-- String: \\*[']\nApply acute accent to preceding glyph.\n\n-- String: \\*[`]\nApply grave accent to preceding glyph.\n\n-- String: \\*[:]\nApply dieresis (umlaut) to preceding glyph.\n\n-- String: \\*[^]\nApply circumflex accent to preceding glyph.\n\n-- String: \\*[~]\nApply tilde accent to preceding glyph.\n\n-- String: \\*[,]\nApply cedilla to preceding glyph.\n\n-- String: \\*[/]\nApply stroke (slash) to preceding glyph.\n\n-- String: \\*[v]\nApply caron to preceding glyph.\n\n-- String: \\*[]\nApply macron to preceding glyph.\n\n-- String: \\*[.]\nApply underdot to preceding glyph.\n\n-- String: \\*[o]\nApply ring accent to preceding glyph.\n\n-- String: \\*[?]\nInterpolate inverted question mark.\n\n-- String: \\*[!]\nInterpolate inverted exclamation mark.\n\n-- String: \\*[8]\nInterpolate small letter sharp s.\n\n-- String: \\*[q]\nInterpolate small letter o with hook accent (ogonek).\n\n-- String: \\*[3]\nInterpolate small letter yogh.\n\n-- String: \\*[d-]\nInterpolate small letter eth.\n\n-- String: \\*[D-]\nInterpolate capital letter eth.\n\n-- String: \\*[th]\nInterpolate small letter thorn.\n\n-- String: \\*[Th]\nInterpolate capital letter thorn.\n\n-- String: \\*[ae]\nInterpolate small ae ligature.\n\n-- String: \\*[Ae]\nInterpolate capital ? ligature.\n\n-- String: \\*[oe]\nInterpolate small oe ligature.\n\n-- String: \\*[OE]\nInterpolate capital OE ligature.\n", "subsections": [] }, "File: groff.info, Node: ms Naming Conventions, Prev: ms Legacy Features, Up: ms": { "content": "", "subsections": [] }, "The following conventions are used for names of macros, strings, and": { "content": "registers. External names available to documents that use the 'groff'\n'ms' macros contain only uppercase letters and digits.\n\nInternally, the macros are divided into modules. Conventions for\nidentifier names are as follows.\n\n* Names used only within one module are of the form MODULE'*'NAME.\n\n* Names used outside the module in which they are defined are of the\nform MODULE'@'NAME.\n\n* Names associated with a particular environment are of the form\nENVIRONMENT':'NAME; these are used only within the 'par' module.\n\n* NAME does not have a module prefix.\n\n* Constructed names used to implement arrays are of the form\nARRAY'!'INDEX.\n\nThus the 'groff' 'ms' macros reserve the following names.\n\n* Names containing the characters '*', '@', and ':'.\n\n* Names containing only uppercase letters and digits.\n", "subsections": [] }, "File: groff.info, Node: GNU troff Reference, Next: File Formats, Prev: Major Macro Packages, Up: Top": { "content": "", "subsections": [] }, "5 GNU 'troff' Reference": { "content": "", "subsections": [] }, "This chapter covers all of the facilities of the GNU 'troff'": { "content": "formatting engine. Users of macro packages may skip it if not\ninterested in details.\n\n* Menu:\n\n* Text::\n* Page Geometry::\n* Measurements::\n* Numeric Expressions::\n* Identifiers::\n* Formatter Instructions::\n* Comments::\n* Registers::\n* Manipulating Filling and Adjustment::\n* Manipulating Hyphenation::\n* Manipulating Spacing::\n* Tabs and Fields::\n* Character Translations::\n* troff and nroff Modes::\n* Line Layout::\n* Line Continuation::\n* Page Layout::\n* Page Control::\n* Using Fonts::\n* Manipulating Type Size and Vertical Spacing::\n* Colors::\n* Strings::\n* Conditionals and Loops::\n* Writing Macros::\n* Page Motions::\n* Drawing Geometric Objects::\n* Deferring Output::\n* Traps::\n* Diversions::\n* Punning Names::\n* Environments::\n* Suppressing Output::\n* I/O::\n* Postprocessor Access::\n* Miscellaneous::\n* Gtroff Internals::\n* Debugging::\n* Implementation Differences::\n", "subsections": [] }, "File: groff.info, Node: Text, Next: Measurements, Prev: GNU troff Reference, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.1 Text", "content": "AT&T 'troff' was designed to take input as it would be composed on a\ntypewriter, including the teletypewriters used as early computer\nterminals, and relieve the user drafting a document of concern with\ndetails like line length, hyphenation breaking, and the achievement of\nstraight margins. Early in its development, the program gained the\nability to prepare output for a phototypesetter; a document could then\nbe prepared for output to either a teletypewriter, a phototypesetter, or\nboth. GNU 'troff' continues this tradition of permitting an author to\ncompose a single master version of a document which can then be rendered\nfor a variety of output formats or devices.\n\n'roff' input files contain text interspersed with instructions to\ncontrol the formatter. Even in the absence of such instructions, GNU\n'troff' still processes its input in several ways, by filling,\nhyphenating, breaking, and adjusting it, and supplementing it with\ninter-sentence space.\n\n* Menu:\n\n* Filling::\n* Hyphenation::\n* Sentences::\n* Breaking::\n* Adjustment::\n* Tabs and Leaders::\n* Requests and Macros::\n* Macro Packages::\n* Input Encodings::\n* Input Conventions::\n" } ] }, "File: groff.info, Node: Filling, Next: Sentences, Prev: Text, Up: Text": { "content": "", "subsections": [] }, "When GNU 'troff' starts up, it obtains information about the device for": { "content": "which it is preparing output.(1) (*note Filling-Footnote-1::) An\nessential property is the length of the output line, such as \"6.5\ninches\".\n\nGNU 'troff' interprets plain text files employing the Unix\nline-ending convention. It reads input a character at a time,\ncollecting words as it goes, and fits as many words together on an\noutput line as it can--this is known as \"filling\". To GNU 'troff', a\n\"word\" is any sequence of one or more characters that aren't spaces or\nnewlines. The exceptions separate words.(2) (*note\nFilling-Footnote-2::) To disable filling, see *note Manipulating Filling\nand Adjustment::.\n\nIt is a truth universally acknowledged\nthat a single man in possession of a\ngood fortune must be in want of a wife.\n=> It is a truth universally acknowledged that a\n=> single man in possession of a good fortune must\n=> be in want of a wife.\n", "subsections": [] }, "File: groff.info, Node: Hyphenation, Next: Breaking, Prev: Sentences, Up: Text": { "content": "", "subsections": [] }, "When an output line is nearly full, it is uncommon for the next word": { "content": "collected from the input to exactly fill it--typically, there is room\nleft over only for part of the next word. The process of splitting a\nword so that it appears partially on one line (with a hyphen to indicate\nto the reader that the word has been broken) with its remainder on the\nnext is \"hyphenation\". Hyphenation points can be manually specified;\nGNU 'troff' also uses a hyphenation algorithm and language-specific\npattern files (based on those used in TeX) to decide which words can be\nhyphenated and where.\n\nHyphenation does not always occur even when the hyphenation rules for\na word allow it; it can be disabled, and when not disabled there are\nseveral parameters that can prevent it in certain circumstances. *Note\nManipulating Hyphenation::.\n", "subsections": [] }, "File: groff.info, Node: Sentences, Next: Hyphenation, Prev: Filling, Up: Text": { "content": "A passionate debate has raged for decades among writers of the English\nlanguage over whether more space should appear between adjacent\nsentences than between words within a sentence, and if so, how much, and\nwhat other circumstances should influence this spacing.(1) (*note\nSentences-Footnote-1::) GNU 'troff' follows the example of AT&T 'troff';\nit attempts to detect the boundaries between sentences, and supplies\nadditional inter-sentence space between them.\n\nHello, world!\nWelcome to groff.\n=> Hello, world! Welcome to groff.\n\nGNU 'troff' flags certain characters (normally '!', '?', and '.') as\npotentially ending a sentence. When GNU 'troff' encounters one of these\n\"end-of-sentence characters\" at the end of an input line, or one of them\nis followed by two (unescaped) spaces on the same input line, it appends\nan inter-word space followed by an inter-sentence space in the output.\n\nR. Harper subscribes to a maxim of P. T. Barnum.\n=> R. Harper subscribes to a maxim of P. T. Barnum.\n\nIn the above example, inter-sentence space is not added after 'P.' or\n'T.' because the periods do not occur at the end of an input line, nor\nare they followed by two or more spaces. Let's imagine that we've heard\nsomething about defamation from Mr. Harper's attorney, recast the\nsentence, and reflowed it in our text editor.\n\nI submit that R. Harper subscribes to a maxim of P. T.\nBarnum.\n=> I submit that R. Harper subscribes to a maxim of\n=> P. T. Barnum.\n\n\"Barnum\" doesn't begin a sentence! What to do? Let us meet our\nfirst \"escape sequence\", a series of input characters that give\ninstructions to GNU 'troff' instead of being used to construct output\ndevice glyphs.(2) (*note Sentences-Footnote-2::) An escape sequence\nbegins with the backslash character '\\' by default, an uncommon\ncharacter in natural language text, and is always followed by at least\none other character, hence the term \"sequence\".\n\nThe dummy character escape sequence '\\&' can be used after an\nend-of-sentence character to defeat end-of-sentence detection on a\nper-instance basis. We can therefore rewrite our input more\ndefensively.\n\nI submit that R.\\& Harper subscribes to a maxim of P.\\&\nT.\\& Barnum.\n=> I submit that R. Harper subscribes to a maxim of\n=> P. T. Barnum.\n\nAdding text caused our input to wrap; now, we don't need '\\&' after\n'T.' but we do after 'P.'. Consistent use of the escape sequence\nensures that potential sentence boundaries are robust to editing\nactivities. Further advice along these lines will follow in *note Input\nConventions::.\n\nNormally, the occurrence of a visible non-end-of-sentence character\n(as opposed to a space or tab) immediately after an end-of-sentence\ncharacter cancels detection of the end of a sentence. For example, it\nwould be incorrect for GNU 'troff' to infer the end of a sentence after\nthe dot in '3.14159'. However, several characters are treated\ntransparently after the occurrence of an end-of-sentence character.", "subsections": [] }, "That is, GNU 'troff' does not cancel end-of-sentence detection when it": { "content": "processes them. This is because such characters are often used as\nfootnote markers or to close quotations and parentheticals. The default\nset is '\"', ''', ')', ']', '*', '\\[dg]', '\\[dd]', '\\[rq]', and '\\[cq]'.\nThe last four are examples of \"special characters\", escape sequences\nwhose purpose is to obtain glyphs that are not easily typed at the\nkeyboard, or which have special meaning to GNU 'troff' (like '\\'\nitself).(3) (*note Sentences-Footnote-3::)\n\n\\[lq]The idea that the poor should have leisure has always\nbeen shocking to the rich.\\[rq]\n(Bertrand Russell, 1935)\n=> \"The idea that the poor should have\n=> leisure has always been shocking to\n=> the rich.\" (Bertrand Russell, 1935)\n\nThe sets of characters that potentially end sentences or are\ntransparent to sentence endings are configurable. See the 'cflags'\nrequest in *note Using Symbols::. To change the additional\ninter-sentence space amount--even to remove it entirely--see *note\nManipulating Filling and Adjustment::.\n", "subsections": [] }, "File: groff.info, Node: Breaking, Next: Adjustment, Prev: Hyphenation, Up: Text": { "content": "", "subsections": [] }, "Once an output line is full, the next word (or remainder of a hyphenated": { "content": "one) is placed on a different output line; this is called a \"break\". In\nthis manual and in 'roff' discussions generally, a \"break\" if not\nfurther qualified always refers to the termination of an output line.", "subsections": [] }, "When the formatter is filling text, it introduces breaks automatically": { "content": "to keep output lines from exceeding the configured line length. After\nan automatic break, GNU 'troff' adjusts the line if applicable (see\nbelow), and then resumes collecting and filling text on the next output\nline.\n\nSometimes, a line cannot be broken automatically. This usually does\nnot happen with natural language text unless the output line length has\nbeen manipulated to be extremely short, but it can with specialized text\nlike program source code. We can use 'perl' at the shell prompt to\ncontrive an example of failure to break the line. We also employ the\n'-z' option to suppress normal output.\n\n$ perl -e 'print \"#\" x 80, \"\\n\";' | nroff -z\nerror-> warning: cannot break line\n\nThe remedy for these cases is to tell GNU 'troff' where the line may\nbe broken without hyphens. This is done with the non-printing break\npoint escape sequence '\\:'; see *note Manipulating Hyphenation::.\n\nWhat if the document author wants to stop filling lines temporarily,\nfor instance to start a new paragraph? There are several solutions. A\nblank input line not only causes a break, but by default it also outputs\na one-line vertical space (effectively a blank output line). This\nbehavior can be modified; see *note Blank Line Traps::. Macro packages\nmay discourage or disable the blank line method of paragraphing in favor\nof their own macros.\n\nA line that begins with one or more spaces causes a break. The\nspaces are output at the beginning of the next line without being\nadjusted (see below); however, this behavior can be modified (*note", "subsections": [] }, "Leading Space Traps::). Again, macro packages may provide other methods": { "content": "of producing indented paragraphs. Trailing spaces on text lines are\ndiscarded.(1) (*note Breaking-Footnote-1::)\n\nWhat if the file ends before enough words have been collected to fill\nan output line? Or the output line is exactly full but not yet broken,\nand there is no more input? GNU 'troff' interprets the end of input as\na break. Certain requests also cause breaks, implicitly or explicitly.\nThis is discussed in *note Manipulating Filling and Adjustment::.\n", "subsections": [] }, "File: groff.info, Node: Adjustment, Next: Tabs and Leaders, Prev: Breaking, Up: Text": { "content": "After GNU 'troff' performs an automatic break, it may then \"adjust\" the\nline, widening inter-word spaces until the text reaches the right\nmargin. Extra spaces between words are preserved. Leading and trailing\nspaces are handled as noted above. Text can be aligned to the left or\nright margin only, or centered; see *note Manipulating Filling and\nAdjustment::.\n", "subsections": [] }, "File: groff.info, Node: Tabs and Leaders, Next: Input Conventions, Prev: Adjustment, Up: Text": { "content": "GNU 'troff' translates input horizontal tab characters (\"tabs\") and\n characters (\"leaders\") into movements to the next tab stop.", "subsections": [] }, "Tabs simply move to the next tab stop; leaders place enough periods to": { "content": "fill the space. Tab stops are by default located every half inch\nmeasured from the drawing position corresponding to the beginning of the\ninput line; see *note Page Geometry::. Tabs and leaders do not cause\nbreaks and therefore do not interrupt filling. Below, we use arrows ->\nand bullets * to indicate input tabs and leaders, respectively.\n\n1\n-> 2 -> 3 * 4\n-> * 5\n=> 1 2 3.......4 ........5\n\nTabs and leaders lend themselves to table construction.(1) (*note", "subsections": [] }, "Tabs and Leaders-Footnote-1::) The tab and leader glyphs can be": { "content": "configured, and further facilities for sophisticated table composition\nare available; see *note Tabs and Fields::. There are many details to\ntrack when using such low-level features, so most users turn to the\n'tbl(1)' preprocessor to lay out tables.\n", "subsections": [] }, "File: groff.info, Node: Requests and Macros, Next: Macro Packages, Prev: Tabs and Leaders, Up: Text": { "content": "", "subsections": [] }, "We have now encountered almost all of the syntax there is in the 'roff'": { "content": "language, with an exception already noted in passing. A \"request\" is an\ninstruction to the formatter that occurs after a \"control character\",\nwhich is recognized at the beginning of an input line. The regular\ncontrol character is a dot ('.'). Its counterpart, the \"no-break\ncontrol character\", a neutral apostrophe ('''), suppresses the break\nthat is implied by some requests. These characters were chosen because\nit is uncommon for lines of text in natural languages to begin with\nthem. If you require a formatted period or apostrophe (closing single\nquotation mark) where GNU 'troff' is expecting a control character,\nprefix the dot or neutral apostrophe with the dummy character escape\nsequence, '\\&'.\n\nAn input line beginning with a control character is called a \"control\nline\". Every line of input that is not a control line is a \"text\nline\".(1) (*note Requests and Macros-Footnote-1::)\n\nRequests often take \"arguments\", words (separated from the request\nname and each other by spaces) that specify details of the action GNU\n'troff' is expected to perform. If a request is meaningless without\narguments, it is typically ignored.\n\nGNU 'troff''s requests and escape sequences comprise the control\nlanguage of the formatter. Of key importance are the requests that\ndefine macros. Macros are invoked like requests, enabling the request\nrepertoire to be extended or overridden.(2) (*note Requests and", "subsections": [] }, "Macros-Footnote-2::)": { "content": "A \"macro\" can be thought of as an abbreviation you can define for a\ncollection of control and text lines. When the macro is \"called\" by\ngiving its name after a control character, it is replaced with what it\nstands for. The process of textual replacement is known as\n\"interpolation\".(3) (*note Requests and Macros-Footnote-3::)", "subsections": [] }, "Interpolations are handled as soon as they are recognized, and once": { "content": "performed, a 'roff' formatter scans the replacement for further\nrequests, macro calls, and escape sequences.\n\nIn 'roff' systems, the 'de' request defines a macro.(4) (*note", "subsections": [] }, "Requests and Macros-Footnote-4::)": { "content": ".de DATE\n2020-11-14\n..\n", "subsections": [] }, "The foregoing input produces no output by itself; all we have done is": { "content": "store some information. Observe the pair of dots that ends the macro\ndefinition. This is a default; you can specify your own terminator for\nthe macro definition as the second argument to the 'de' request.\n\n.de NAME ENDNAME\nHeywood Jabuzzoff\n.ENDNAME\n\nIn fact, the ending marker is itself the name of a macro to be\ncalled, or a request to be invoked, if it is defined at the time its\ncontrol line is read.\n\n.de END\nBig Rip\n..\n.de START END\nBig Bang\n.END\n.START\n=> Big Rip Big Bang\n\nIn the foregoing example, \"Big Rip\" printed before \"Big Bang\" because\nits macro was called first. Consider what would happen if we dropped\n'END' from the '.de START' line and added '..' after '.END'. Would the\norder change?\n\nLet us consider a more elaborate example.\n\n.de DATE\n2020-10-05\n..\n.\n.de BOSS\nD.\\& Kruger,\nJ.\\& Peterman\n..\n.\n.de NOTICE\nApproved:\n.DATE\nby\n.BOSS\n..\n.\nInsert tedious regulatory compliance paragraph here.\n\n.NOTICE\n\nInsert tedious liability disclaimer paragraph here.\n\n.NOTICE\n=> Insert tedious regulatory compliance paragraph here.\n=>\n=> Approved: 2020-10-05 by D. Kruger, J. Peterman\n=>\n=> Insert tedious liability disclaimer paragraph here.\n=>\n=> Approved: 2020-10-05 by D. Kruger, J. Peterman\n", "subsections": [] }, "The above document started with a series of control lines. Three macros": { "content": "were defined, with a 'de' request declaring each macro's name, and the\n\"body\" of the macro starting on the next line and continuing until a\nline with two dots ''..'' marked its end. The text proper began only\nafter the macros were defined; this is a common pattern. Only the\n'NOTICE' macro was called \"directly\" by the document; 'DATE' and 'BOSS'\nwere called only by 'NOTICE' itself. Escape sequences were used in\n'BOSS', two levels of macro interpolation deep.\n\nThe advantage in typing and maintenance economy may not be obvious\nfrom such a short example, but imagine a much longer document with\ndozens of such paragraphs, each requiring a notice of managerial\napproval. Consider what must happen if you are in charge of generating\na new version of such a document with a different date, for a different\nboss. With well-chosen macros, you only have to change each datum in\none place.\n\nIn practice, we would probably use strings (*note Strings::) instead\nof macros for such simple interpolations; what is important here is to\nglimpse the potential of macros and the power of recursive\ninterpolation.\n\nWe could have defined 'DATE' and 'BOSS' in the opposite order;\nperhaps less obviously, we could also have defined them after\n'NOTICE'. \"Forward references\" like this are acceptable because the\nbody of a macro definition is not (completely) interpreted, but stored\ninstead (*note Copy Mode::). While a macro is being defined (or\nappended to), requests are not interpreted and macros not interpolated,\nwhereas some commonly used escape sequences are interpreted. 'roff'\nsystems also support recursive macro calls, as long as you have a way to\nbreak the recursion (*note Conditionals and Loops::). Maintainable\n'roff' documents tend to arrange macro definitions to minimize forward\nreferences.\n", "subsections": [] }, "File: groff.info, Node: Macro Packages, Next: Input Encodings, Prev: Requests and Macros, Up: Text": { "content": "Macro definitions can be collected into \"macro files\", 'roff' input\nfiles designed to produce no output themselves but instead ease the\npreparation of other 'roff' documents. There is no syntactical\ndifference between a macro file and any other 'roff' document; only its\npurpose distinguishes it. When a macro file is installed at a standard\nlocation and suitable for use by a general audience, it is often termed\na \"macro package\".(1) (*note Macro Packages-Footnote-1::) Macro\npackages can be loaded by supplying the '-m' option to GNU 'troff' or a\n'groff' front end. Alternatively, a document requiring a macro package\ncan load it with the 'mso' (\"macro source\") request.\n", "subsections": [] }, "File: groff.info, Node: Input Encodings, Next: Input Conventions, Prev: Macro Packages, Up: Text": { "content": "", "subsections": [] }, "The 'groff' command's '-k' option calls the 'preconv' preprocessor to": { "content": "perform input character encoding conversions. Input to the GNU 'troff'\nformatter itself, on the other hand, must be in one of two encodings it\ncan recognize.\n\n'cp1047'\nThe code page 1047 input encoding works only on EBCDIC platforms\n(and conversely, the other input encodings don't work with EBCDIC);\nthe file 'cp1047.tmac' is loaded at startup.\n\n'latin1'\nISO Latin-1, an encoding for Western European languages, is the\ndefault input encoding on non-EBCDIC platforms; the file\n'latin1.tmac' is loaded at startup.\n", "subsections": [] }, "Any document that is encoded in ISO 646:1991 (a descendant of USAS": { "content": "X3.4-1968 or \"US-ASCII\"), or, equivalently, uses only code points from\nthe \"C0 Controls\" and \"Basic Latin\" parts of the Unicode character set\nis also a valid ISO Latin-1 document; the standards are interchangeable\nin their first 128 code points.(1) (*note Input Encodings-Footnote-1::)\n\nOther encodings are supported by means of macro packages.\n\n'latin2'\nTo use ISO Latin-2, an encoding for Central and Eastern European\nlanguages, invoke '.mso latin2.tmac' at the beginning of your\ndocument or supply '-mlatin2' as a command-line argument to\n'groff'.\n\n'latin5'\nTo use ISO Latin-5, an encoding for the Turkish language, invoke\n'.mso latin5.tmac' at the beginning of your document or supply\n'-mlatin5' as a command-line argument to 'groff'.\n\n'latin9'\nISO Latin-9 succeeds Latin-1; it includes a Euro sign and better\nglyph coverage for French. To use this encoding, invoke\n'.mso latin9.tmac' at the beginning of your document or supply\n'-mlatin9' as a command-line argument to 'groff'.\n\nSome characters from an input encoding may not be available with a\nparticular output driver, or their glyphs may not have representation in\nthe font used. For terminal devices, fallbacks are defined, like 'EUR'\nfor the Euro sign and '(C)' for the copyright sign. For typesetter\ndevices, you may need to \"mount\" fonts that support glyphs required by\nthe document. *Note Font Positions::.\n\nBecause a Euro glyph was not historically defined in PostScript\nfonts, 'groff' comes with a font called 'freeeuro.pfa' that provides the", "subsections": [] }, "Euro in several styles. Standard PostScript fonts contain the glyphs": { "content": "from Latin-5 and Latin-9 that Latin-1 lacks, so these encodings are\nsupported for the 'ps' and 'pdf' output devices as 'groff' ships, while\nLatin-2 is not.\n\nUnicode supports characters from all other input encodings; the\n'utf8' output driver for terminals therefore does as well. The DVI\noutput driver supports the Latin-2 and Latin-9 encodings if the\ncommand-line option '-mec' is used as well. (2) (*note Input", "subsections": [] }, "Encodings-Footnote-2::)": { "content": "", "subsections": [] }, "File: groff.info, Node: Input Conventions, Prev: Input Encodings, Up: Text": { "content": "", "subsections": [] }, "Since GNU 'troff' fills text automatically, it is common practice in the": { "content": "'roff' language to avoid visual composition of text in input files: the\nesthetic appeal of the formatted output is what matters. Therefore,\n'roff' input should be arranged such that it is easy for authors and\nmaintainers to compose and develop the document, understand the syntax\nof 'roff' requests, macro calls, and preprocessor languages used, and\npredict the behavior of the formatter. Several traditions have accrued\nin service of these goals.\n\n* Follow sentence endings in the input with newlines to ease their\nrecognition (*note Sentences::). It is frequently convenient to\nend text lines after colons and semicolons as well, as these\ntypically precede independent clauses. Consider doing so after\ncommas; they often occur in lists that become easy to scan when\nitemized by line, or constitute supplements to the sentence that\nare added, deleted, or updated to clarify it. Parenthetical and\nquoted phrases are also good candidates for placement on text lines\nby themselves.\n\n* Set your text editor's line length to 72 characters or fewer.(1)\n(*note Input Conventions-Footnote-1::) This limit, combined with\nthe previous item of advice, makes it less common that an input\nline will wrap in your text editor, and thus will help you perceive\nexcessively long constructions in your text. Recall that natural\nlanguages originate in speech, not writing, and that punctuation is\ncorrelated with pauses for breathing and changes in prosody.\n\n* Use '\\&' after '!', '?', and '.' if they are followed by space,\ntab, or newline characters and don't end a sentence.\n\n* In filled text lines, use '\\&' before '.' and ''' if they are\npreceded by space, so that reflowing the input doesn't turn them\ninto control lines.\n\n* Do not use spaces to perform indentation or align columns of a\ntable. Leading spaces are reliable when text is not being filled.\n\n* Comment your document. It is never too soon to apply comments to\nrecord information of use to future document maintainers (including\nyour future self). We thus introduce another escape sequence,\n'\\\"', which causes GNU 'troff' to ignore the remainder of the input\nline.\n\n* Use the empty request--a control character followed immediately by\na newline--to visually manage separation of material in input\nfiles. Many of the 'groff' project's own documents use an empty\nrequest between sentences, after macro definitions, and where a\nbreak is expected, and two empty requests between paragraphs or\nother requests or macro calls that will introduce vertical space\ninto the document.\n\nYou can combine the empty request with the comment escape sequence\nto include whole-line comments in your document, and even \"comment\nout\" sections of it.\n\nWe conclude this section with an example sufficiently long to\nillustrate most of the above suggestions in practice. For the purpose\nof fitting the example between the margins of this manual with the font\nused for its typeset version, we have shortened the input line length to\n56 columns. As before, an arrow -> indicates a tab character.\n\n.\\\" nroff thisfile.roff | less\n.\\\" groff -T ps thisfile.roff > thisfile.ps\n->The theory of relativity is intimately connected with\nthe theory of space and time.\n.\nI shall therefore begin with a brief investigation of\nthe origin of our ideas of space and time,\nalthough in doing so I know that I introduce a\ncontroversial subject. \\\" remainder of paragraph elided\n.\n.\n\n->The experiences of an individual appear to us arranged\nin a series of events;\nin this series the single events which we remember\nappear to be ordered according to the criterion of\n\\[lq]earlier\\[rq] and \\[lq]later\\[rq], \\\" punct swapped\nwhich cannot be analysed further.\n.\nThere exists,\ntherefore,\nfor the individual,\nan I-time,\nor subjective time.\n.\nThis itself is not measurable.\n.\nI can,\nindeed,\nassociate numbers with the events,\nin such a way that the greater number is associated with\nthe later event than with an earlier one;\nbut the nature of this association may be quite\narbitrary.\n.\nThis association I can define by means of a clock by\ncomparing the order of events furnished by the clock\nwith the order of a given series of events.\n.\nWe understand by a clock something which provides a\nseries of events which can be counted,\nand which has other properties of which we shall speak\nlater.\n.\\\" Albert Einstein, The Meaning of Relativity, 1922\n", "subsections": [] }, "File: groff.info, Node: Page Geometry, Next: Measurements, Prev: Text, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.2 Page Geometry", "content": "'roff' systems format text under certain assumptions about the size of\nthe output medium, or page. For the formatter to correctly break a line\nit is filling, it must know the line length, which it derives from the\npage width (*note Line Layout::). For it to decide whether to write an\noutput line to the current page or wait until the next one, it must know\nthe page length (*note Page Layout::).\n\nA device's \"resolution\" converts practical units like inches or\ncentimeters to \"basic units\", a convenient length measure for the output\ndevice or file format. The formatter and output driver use basic units\nto reckon page measurements. The device description file defines its\nresolution and page dimensions (*note DESC File Format::).\n\nA \"page\" is a two-dimensional structure upon which a 'roff' system\nimposes a rectangular coordinate system with its upper left corner as\nthe origin. Coordinate values are in basic units and increase down and\nto the right. Useful ones are therefore always positive and within\nnumeric ranges corresponding to the page boundaries.\n\nWhile the formatter (and, later, output driver) is processing a page,\nit keeps track of its \"drawing position\", which is the location at which\nthe next glyph will be written, from which the next motion will be\nmeasured, or where a geometric object will commence rendering." } ] }, "Notionally, glyphs are drawn from the text baseline upward and to the": { "content": "right.(1) (*note Page Geometry-Footnote-1::) The \"text baseline\" is a\n(usually invisible) line upon which the glyphs of a typeface are\naligned. A glyph therefore \"starts\" at its bottom-left corner. If\ndrawn at the origin, a typical letter glyph would lie partially or\nwholly off the page, depending on whether, like \"g\", it features a\ndescender below the baseline.\n\nSuch a situation is nearly always undesirable. It is furthermore\nconventional not to write or draw at the extreme edges of the page.", "subsections": [] }, "Therefore the initial drawing position of a 'roff' formatter is not at": { "content": "the origin, but below and to the right of it. This rightward shift from\nthe left edge is known as the \"page offset\".(2) (*note Page", "subsections": [] }, "Geometry-Footnote-2::) The downward shift leaves room for a text output": { "content": "line.\n\nText is arranged on a one-dimensional lattice of text baselines from\nthe top to the bottom of the page. \"Vertical spacing\" is the distance\nbetween adjacent text baselines. Typographic tradition sets this\nquantity to 120% of the type size. The initial drawing position is one\nunit of vertical spacing below the page top. Typographers term this\nunit a vee.\n\nVertical spacing has an impact on page-breaking decisions.", "subsections": [] }, "Generally, when a break occurs, the formatter moves the drawing position": { "content": "to the next text baseline automatically. If the formatter were already\nwriting to the last line that would fit on the page, advancing by one\nvee would place the next text baseline off the page. Rather than let\nthat happen, 'roff' formatters instruct the output driver to eject the\npage, start a new one, and again set the drawing position to one vee\nbelow the page top; this is a \"page break\".\n\nWhen the last line of input text corresponds to the last output line\nthat fits on the page, the break caused by the end of input will also\nbreak the page, producing a useless blank one. Macro packages keep\nusers from having to confront this difficulty by setting \"traps\" (*note", "subsections": [] }, "Traps::); moreover, all but the simplest page layouts tend to have": { "content": "headers and footers, or at least bear vertical margins larger than one\nvee.\n", "subsections": [] }, "File: groff.info, Node: Measurements, Next: Numeric Expressions, Prev: Text, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.3 Measurements", "content": "" } ] }, "The formatter sometimes requires the input of numeric parameters to": { "content": "specify measurements. These are specified as integers or decimal\nfractions with an optional \"scaling unit\" suffixed. A scaling unit is a\nletter that immediately follows the last digit of a number. Digits\nafter the decimal point are optional. Measurement expressions include\n'10.5p', '11i', and '3.c'.\n\nMeasurements are scaled by the scaling unit and stored internally\n(with any fractional part discarded) in basic units. The device\nresolution can therefore be obtained by storing a value of '1i' to a\nregister. The only constraint on the basic unit is that it is at least\nas small as any other unit.\n\n'u'\nBasic unit.\n\n'i'\nInch; defined as 2.54 centimeters.\n\n'c'\nCentimeter; a centimeter is about 0.3937 inches.\n\n'p'\nPoint; a typesetter's unit used for measuring type size. There are\n72 points to an inch.\n\n'P'\nPica; another typesetter's unit. There are 6 picas to an inch and\n12 points to a pica.\n\n's'\n'z'\n*Note Using Fractional Type Sizes::, for a discussion of these\nunits.\n\n'f'\nGNU 'troff' defines this unit to scale decimal fractions in the\ninterval [0, 1] to 16-bit unsigned integers. It multiplies a\nquantity by 65,536. *Note Colors::, for usage.\n\nThe magnitudes of other scaling units depend on the text formatting\nparameters in effect. These are useful when specifying measurements\nthat need to scale with the typeface or vertical spacing.\n\n'm'\nEm; an em is equal to the current type size in points. It is named\nthus because it is approximately the width of the letter 'M'.\n\n'n'\nEn; an en is one-half em.\n\n'v'\nVee; recall *note Page Geometry::.\n\n'M'\nHundredth of an em.\n\n* Menu:\n\n* Motion Quanta::\n* Default Units::\n", "subsections": [] }, "File: groff.info, Node: Motion Quanta, Next: Default Units, Prev: Measurements, Up: Measurements": { "content": "", "subsections": [] }, "An output device's basic unit 'u' is not necessarily its smallest": { "content": "addressable length; 'u' can be smaller to avoid problems with integer\nroundoff. The minimum distances that a device can work with in the\nhorizontal and vertical directions are termed its \"motion quanta\".", "subsections": [] }, "Measurements are rounded to applicable motion quanta. Half-quantum": { "content": "fractions round toward zero.\n\n-- Register: \\n[.H]\n-- Register: \\n[.V]\nThese read-only registers interpolate the horizontal and vertical\nmotion quanta, respectively, of the output device in basic units.\n\nFor example, we might draw short baseline rules on a terminal device\nas follows. *Note Drawing Geometric Objects::.\n\n.tm \\n[.H]\nerror-> 24\n.nf\n\\l'36u' 36u\n\\l'37u' 37u\n=> 36u\n=> 37u\n", "subsections": [] }, "File: groff.info, Node: Default Units, Prev: Motion Quanta, Up: Measurements": { "content": "A general-purpose register (one created or updated with the 'nr'\nrequest; see *note Registers::) is implicitly dimensionless, or reckoned\nin basic units if interpreted in a measurement context. But it is\nconvenient for many requests and escape sequences to infer a scaling\nunit for an argument if none is specified. An explicit scaling unit\n(not after a closing parenthesis) can override an undesirable default.", "subsections": [] }, "Effectively, the default unit is suffixed to the expression if a scaling": { "content": "unit is not already present. GNU 'troff''s use of integer arithmetic\nshould also be kept in mind (*note Numeric Expressions::).\n\nThe 'll' request interprets its argument in ems by default. Consider\nseveral attempts to set a line length of 3.5 inches when the type size\nis 10 points on a terminal device with a resolution of 240 basic units\nand horizontal motion quantum of 24. Some expressions become zero; the\nrequest clamps them to that quantum.\n\n.ll 3.5i \\\" 3.5i (= 840u)\n.ll 7/2 \\\" 7u/2u -> 3u -> 3m -> 0, clamped to 24u\n.ll (7 / 2)u \\\" 7u/2u -> as above\n.ll 7/2i \\\" 7u/2i -> 7u/480u -> 0 -> as above\n.ll 7i/2 \\\" 7i/2u -> 1680u/2m -> 1680u/24u -> 35u\n.ll 7i/2u \\\" 3.5i (= 840u)\n", "subsections": [] }, "The safest way to specify measurements is to attach a scaling unit. To": { "content": "multiply or divide by a dimensionless quantity, use 'u' as its scaling\nunit.\n", "subsections": [] }, "File: groff.info, Node: Numeric Expressions, Next: Identifiers, Prev: Measurements, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.4 Numeric Expressions", "content": "A \"numeric expression\" evaluates to an integer: it can be as simple as a\nliteral '0' or it can be a complex sequence of register and string\ninterpolations interleaved with measurements and operators.\n\nGNU 'troff' provides a set of mathematical and logical operators\nfamiliar to programmers--as well as some unusual ones--but supports only\ninteger arithmetic.(1) (*note Numeric Expressions-Footnote-1::) The\ninternal data type used for computing results is usually a 32-bit signed\ninteger, which suffices to represent magnitudes within a range of ?2\nbillion.(2) (*note Numeric Expressions-Footnote-2::)\n\nArithmetic infix operators perform a function on the numeric\nexpressions to their left and right; they are '+' (addition), '-'\n(subtraction), '*' (multiplication), '/' (truncating division), and '%'\n(modulus). \"Truncating division\" rounds to the integer nearer to zero,\nno matter how large the fractional portion. Overflow and division (or\nmodulus) by zero are errors and abort evaluation of a numeric\nexpression.\n\nArithmetic unary operators operate on the numeric expression to their\nright; they are '-' (negation) and '+' (assertion--for completeness; it\ndoes nothing). The unary minus must often be used with parentheses to\navoid confusion with the decrementation operator, discussed below.\n\nObserve the rounding behavior and effect of negative operands on the\nmodulus and truncating division operators.\n\n.nr T 199/100\n.nr U 5/2\n.nr V (-5)/2\n.nr W 5/-2\n.nr X 5%2\n.nr Y (-5)%2\n.nr Z 5%-2\nT=\\n[T] U=\\n[U] V=\\n[V] W=\\n[W] X=\\n[X] Y=\\n[Y] Z=\\n[Z]\n=> T=1 U=2 V=-2 W=-2 X=1 Y=-1 Z=1\n" } ] }, "The sign of the modulus of operands of mixed signs is determined by the": { "content": "sign of the first. Division and modulus operators satisfy the following\nproperty: given a dividend A and a divisor B, a quotient Q formed by '(a\n/ b)' and a remainder R by '(a % b)', then qb + r = a.\n\nGNU 'troff''s scaling operator, used with parentheses as '(C;E)',\nevaluates a numeric expression E using C as the default scaling unit.", "subsections": [] }, "If C is omitted, scaling units are ignored in the evaluation of E. This": { "content": "operator can save typing by avoiding the attachment of scaling units to\nevery operand out of caution. Your macros can select a sensible default\nunit in case the user neglects to supply one.\n\n.\\\" Indent by amount given in first argument; assume ens.\n.de Indent\n. in (n;\\\\$1)\n..\n", "subsections": [] }, "Without the scaling operator, the foregoing macro would, if called with": { "content": "a unitless argument, cause indentation by the 'in' request's default\nscaling unit (ems). The result would be twice as much indentation as\nexpected.\n\nGNU 'troff' also provides a pair of operators to compute the extrema\nof two operands: '>?' (maximum) and ' Looks like we'll end up paying 3 salaries.\n\nComparison operators comprise '<' (less than), '>' (greater than),\n'<=' (less than or equal), '>=' (greater than or equal), and '='\n(equal). '==' is a synonym for '='. When evaluated, a comparison is\nreplaced with '0' if it is false and '1' if true. In the 'roff'\nlanguage, positive values are true, others false.\n\nWe can operate on truth values with the logical operators '&'\n(logical conjunction or \"and\") and ':' (logical disjunction or \"or\").\nThey evaluate as comparison operators do.\n\nA logical complementation (\"not\") operator, '!', works only within\n'if', 'ie', and 'while' requests. Furthermore, '!' is recognized only\nat the beginning of a numeric expression not contained by another\nnumeric expression. In other words, it must be the \"outermost\"\noperator. Including it elsewhere in the expression produces a warning\nin the 'number' category (*note Warnings::), and its expression\nevaluates false. This unfortunate limitation maintains compatibility\nwith AT&T 'troff'. Test a numeric expression for falsity by comparing\nit to a false value.(3) (*note Numeric Expressions-Footnote-3::)\n\n.nr X 1\n.nr Y 0\n.\\\" This does not work as expected.\n.if (\\n[X])&(!\\n[Y]) .nop A: X is true, Y is false\n.\n.\\\" Use this construct instead.\n.if (\\n[X])&(\\n[Y]<=0) .nop B: X is true, Y is false\nerror-> warning: expected numeric expression, got '!'\n=> B: X is true, Y is false\n\nThe 'roff' language has no operator precedence: expressions are\nevaluated strictly from left to right, in contrast to schoolhouse\narithmetic. Use parentheses '(' ')' to impose a desired precedence upon\nsubexpressions.\n\n.nr X 3+5*4\n.nr Y (3+5)*4\n.nr Z 3+(5*4)\nX=\\n[X] Y=\\n[Y] Z=\\n[Z]\n=> X=32 Y=32 Z=23\n\nFor many requests and escape sequences that cause motion on the page,\nthe unary operators '+' and '-' work differently when leading a numeric\nexpression. They then indicate a motion relative to the drawing\nposition: positive is down in vertical contexts, right in horizontal\nones.\n\n'+' and '-' are also treated differently by the following requests\nand escape sequences: 'bp', 'in', 'll', 'lt', 'nm', 'nr', 'pl', 'pn',\n'po', 'ps', 'pvs', 'rt', 'ti', '\\H', '\\R', and '\\s'. Here, leading plus\nand minus signs serve as incrementation and decrementation operators,\nrespectively. To negate an expression, subtract it from zero or include\nthe unary minus in parentheses with its argument. *Note Setting\nRegisters::, for examples.\n\nA leading '|' operator indicates a motion relative not to the drawing\nposition but to a boundary. For horizontal motions, the measurement\nspecifies a distance relative to a drawing position corresponding to the\nbeginning of the input line. By default, tab stops reckon movements\nin this way. Most escape sequences do not; '|' tells them to do so.\n\nMind the \\h'1.2i'gap.\n.br\nMind the \\h'|1.2i'gap.\n.br\nMind the\n\\h'|1.2i'gap.\n=> Mind the gap.\n=> Mind the gap.\n=> Mind the gap.\n\nOne use of this feature is to define macros whose scope is limited to\nthe output they format.\n\n.\\\" underline word $1 with trailing punctuation $2\n.de Underline\n. nop \\\\$1\\l'|0\\[ul]'\\\\$2\n..\nTypographical emphasis is best used\n.Underline sparingly .\n\nIn the above example, '|0' specifies a negative motion from the current\nposition (at the end of the argument just emitted, '\\$1') to the\nbeginning of the input line. Thus, the '\\l' escape sequence in this\ncase draws a line from right to left. A macro call occurs at the\nbeginning of an input line;(4) (*note Numeric Expressions-Footnote-4::)\nif the '|' operator were omitted, then the underline would be drawn at\nzero distance from the current position, producing device-dependent, and\nlikely undesirable, results. On the 'ps' output device, it underlines\nthe period.\n\nFor vertical motions, the '|' operator specifies a distance from the\nfirst text baseline on the page or in the current diversion,(5) (*note\nNumeric Expressions-Footnote-5::) using the current vertical spacing.\n\nA\n.br\nB \\Z'C'\\v'|0'D\n=> A D\n=> B C\n\nIn the foregoing example, we've used the '\\Z' escape sequence (*note", "subsections": [] }, "Page Motions::) to restore the drawing position after formatting 'C',": { "content": "then moved vertically to the first text baseline on the page.\n\n-- Escape sequence: \\B'anything'\nInterpolate 1 if ANYTHING is a valid numeric expression, and 0\notherwise. The delimiter need not be a neutral apostrophe; see\n*note Delimiters::.\n\nYou might use '\\B' along with the 'if' request to filter out invalid\nmacro or string arguments. *Note Conditionals and Loops::.\n\n.\\\" Indent by amount given in first argument; assume ens.\n.de Indent\n. if \\B'\\\\$1' .in (n;\\\\$1)\n..\n\nA register interpolated as an operand in a numeric expression must\nhave an Arabic format; luckily, this is the default. *Note Assigning\nRegister Formats::.\n\nBecause spaces separate arguments to requests, spaces are not allowed\nin numeric expressions unless the (sub)expression containing them is\nsurrounded by parentheses. *Note Invoking Requests::, and *note\nConditionals and Loops::.\n\n.nf\n.nr a 1+2 + 2+1\n\\na\nerror-> expected numeric expression, got a space\n=> 3\n.nr a 1+(2 + 2)+1\n\\na\n=> 6\n\nThe 'nr' request (*note Setting Registers::) expects its second and\noptional third arguments to be numeric expressions; a bare '+' does not\nqualify, so our first attempt got a warning.\n", "subsections": [] }, "File: groff.info, Node: Identifiers, Next: Formatter Instructions, Prev: Numeric Expressions, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.5 Identifiers", "content": "An \"identifier\" labels a GNU 'troff' datum such as a register, name\n(macro, string, or diversion), typeface, color, special character,\ncharacter class, environment, or stream. Valid identifiers consist of\none or more ordinary characters. An ordinary character is an input\ncharacter that is not the escape character, a leader, tab, newline, or\ninvalid as GNU 'troff' input.\n\nInvalid input characters are a subset of control characters (from the\nsets \"C0 Controls\" and \"C1 Controls\" as Unicode describes them). When\nGNU 'troff' encounters one in an identifier, it produces a warning in\ncategory 'input' (*note Warnings::). They are removed during\ninterpretation: an identifier 'foo', followed by an invalid character\nand then 'bar', is processed as 'foobar'.\n\nOn a machine using the ISO 646, 8859, or 10646 character encodings,\ninvalid input characters are '0x00', '0x08', '0x0B', '0x0D'-'0x1F', and\n'0x80'-'0x9F'. On an EBCDIC host, they are '0x00'-'0x01', '0x08',\n'0x09', '0x0B', '0x0D'-'0x14', '0x17'-'0x1F', and '0x30'-'0x3F'.(1)\n(*note Identifiers-Footnote-1::) Some of these code points are used by\nGNU 'troff' internally, making it non-trivial to extend the program to\naccept UTF-8 or other encodings that use characters from these\nranges.(2) (*note Identifiers-Footnote-2::)\n\nThus, the identifiers 'br', 'PP', 'end-list', 'ref*normal-print',\n'|', '@', and '!\"#$%'()*+,-./' are all valid. Discretion should be\nexercised to prevent confusion. Identifiers starting with '(' or '['\nrequire care.\n\n.nr x 9\n.nr y 1\n.nr (x 2\n.nr [y 3\n.nr sum1 (\\n(x + \\n[y])\nerror-> a space character is not allowed in an escape\nerror-> sequence parameter\nA:2+3=\\n[sum1]\n.nr sum2 (\\n((x + \\n[[y])\nB:2+3=\\n[sum2]\n.nr sum3 (\\n[(x] + \\n([y)\nC:2+3=\\n[sum3]\n=> A:2+3=1 B:2+3=5 C:2+3=5\n\nAn identifier with a closing bracket (']') in its name can't be accessed\nwith bracket-form escape sequences that expect an identifier as a\nparameter. For example, '\\[foo]]' accesses the glyph 'foo', followed by\n']' in whatever the surrounding context is, whereas '\\C'foo]'' formats a\nglyph named 'foo]'. Similarly, the identifier '(' can't be interpolated\nexcept with bracket forms.\n\nIf you begin a macro, string, or diversion name with either of the\ncharacters '[' or ']', you foreclose use of the 'grefer' preprocessor,\nwhich recognizes '.[' and '.]' as bibliographic reference delimiters.\n\n-- Escape sequence: \\A'anything'\nInterpolate 1 if ANYTHING is a valid identifier, and 0 otherwise.\nThe delimiter need not be a neutral apostrophe; see *note\nDelimiters::. Because invalid input characters are removed (see\nabove), invalid identifiers are empty or contain spaces, tabs, or\nnewlines.\n\nYou can employ '\\A' to validate a macro argument before using it to\nconstruct another escape sequence or identifier.\n\n.\\\" usage: .init-coordinate-pair name val1 val2\n.\\\" Create a coordinate pair where name!x=val1 and\n.\\\" name!y=val2.\n.de init-coordinate-pair\n. if \\A'\\\\$1' \\{\\\n. if \\B'\\\\$2' .nr \\\\$1!x \\\\$2\n. if \\B'\\\\$3' .nr \\\\$1!y \\\\$3\n. \\}\n..\n.init-coordinate-pair center 5 10\nThe center is at (\\n[center!x], \\n[center!y]).\n.init-coordinate-pair \"poi->nt\" trash garbage \\\" ignored\n.init-coordinate-pair point trash garbage \\\" ignored\n=> The center is at (5, 10).\n\nIn this example, we also validated the numeric arguments; the\nregisters 'point!x' and 'point!y' remain undefined. *Note Numeric\nExpressions:: for the '\\B' escape sequence.\n\nHow GNU 'troff' handles the interpretation of an undefined identifier\ndepends on the context. There is no way to invoke an undefined request;\nsuch syntax is interpreted as a macro call instead. If the identifier\nis interpreted as a string, macro, or diversion, GNU 'troff' emits a\nwarning in category 'mac', defines it as empty, and interpolates\nnothing. If the identifier is interpreted as a register, GNU 'troff'\nemits a warning in category 'reg', initializes it to zero, and\ninterpolates that value. *Note Warnings::, *note Interpolating\nRegisters::, and *note Strings::. Attempting to use an undefined\ntypeface, special character, color, character class, environment, or\nstream generally provokes an error diagnostic.\n\nIdentifiers for requests, macros, strings, and diversions share one\nname space; special characters and character classes another. No other\nobject types do.\n\n.de xxx\n. nop foo\n..\n.di xxx\nbar\n.br\n.di\n.\n.xxx\n=> bar\n" } ] }, "The foregoing example shows that GNU 'troff' reuses the identifier": { "content": "'xxx', changing it from a macro to a diversion. No warning is emitted,\nand the previous contents of 'xxx' are lost.\n", "subsections": [] }, "File: groff.info, Node: Formatter Instructions, Next: Registers, Prev: Identifiers, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.6 Formatter Instructions", "content": "" } ] }, "To support documents that require more than filling, automatic line": { "content": "breaking and hyphenation, adjustment, and supplemental inter-sentence\nspace, the 'roff' language offers two means of embedding instructions to\nthe formatter.\n\nOne is a \"request\", which begins with a control character and takes\nup the remainder of the input line. Requests often perform relatively\nlarge-scale operations such as setting the page length, breaking the\nline, or starting a new page. They also conduct internal operations\nlike defining macros.\n\nThe other is an \"escape sequence\", which begins with the escape\ncharacter and can be embedded anywhere in the input, even in arguments\nto requests and other escape sequences. Escape sequences interpolate\nspecial characters, strings, or registers, and handle comparatively\nminor formatting tasks like sub- and superscripting.\n\nSome operations, such as font selection and type size alteration, are\navailable via both requests and escape sequences.\n\n* Menu:\n\n* Control Characters::\n* Invoking Requests::\n* Calling Macros::\n* Using Escape Sequences::\n* Delimiters::\n", "subsections": [] }, "File: groff.info, Node: Control Characters, Next: Invoking Requests, Prev: Formatter Instructions, Up: Formatter Instructions": { "content": "", "subsections": [] }, "The mechanism of using 'roff''s control characters to invoke requests": { "content": "and call macros was introduced in *note Requests and Macros::. Control\ncharacters are recognized only at the beginning of an input line, or at\nthe beginning of the branch of a control structure request; see *note\nConditionals and Loops::.\n\nA few requests cause a break implicitly; use the no-break control\ncharacter to prevent the break. Break suppression is its sole\nbehavioral distinction. Employing the no-break control character to\ninvoke requests that don't cause breaks is harmless but poor style.\n*Note Manipulating Filling and Adjustment::.\n\nThe control '.' and no-break control ''' characters can each be\nchanged to any ordinary character(1) (*note Control\nCharacters-Footnote-1::) with the 'cc' and 'c2' requests, respectively.\n\n-- Request: .cc [o]\nRecognize the ordinary character O as the control character. If O\nis absent or invalid, the default control character '.' is\nselected. The identity of the control character is associated with\nthe environment (*note Environments::).\n\n-- Request: .c2 [o]\nRecognize the ordinary character O as the no-break control\ncharacter. If O is absent or invalid, the default no-break control\ncharacter ''' is selected. The identity of the no-break control\ncharacter is associated with the environment (*note\nEnvironments::).\n\nWhen writing a macro, you might wish to know which control character\nwas used to call it.\n\n-- Register: \\n[.br]\nThis read-only register interpolates 1 if the currently executing\nmacro was called using the normal control character and 0\notherwise. If a macro is interpolated as a string, the '.br'\nregister's value is inherited from the context of the string\ninterpolation. *Note Strings::.\n\nUse this register to reliably intercept requests that imply breaks.\n\n.als bp*orig bp\n.de bp\n. ie \\\\n[.br] .bp*orig\n. el 'bp*orig\n..\n\nTesting the '.br' register outside of a macro definition makes no\nsense.\n", "subsections": [] }, "File: groff.info, Node: Invoking Requests, Next: Calling Macros, Prev: Control Characters, Up: Formatter Instructions": { "content": "A control character is optionally followed by tabs and/or spaces and\nthen an identifier naming a request or macro. The invocation of an\nunrecognized request is interpreted as a macro call. Defining a macro\nwith the same name as a request replaces the request. Deleting a\nrequest name with the 'rm' request makes it unavailable. The 'als'\nrequest can alias requests, permitting them to be wrapped or\nnon-destructively replaced. *Note Strings::.\n\nThere is no inherent limit on argument length or quantity. Most\nrequests take one or more arguments, and ignore any they do not expect.\nA request may be separated from its arguments by tabs or spaces, but\nonly spaces can separate an argument from its successor. Only one\nbetween arguments is necessary; any excess is ignored. GNU 'troff' does\nnot allow tabs for argument separation.(1) (*note Invoking", "subsections": [] }, "Requests-Footnote-1::)": { "content": "Generally, a space within a request argument is not relevant, not\nmeaningful, or is supported by bespoke provisions, as with the 'tl'\nrequest's delimiters (*note Page Layout::). Some requests, like 'ds',\ninterpret the remainder of the control line as a single argument. *Note\nStrings::.\n\nSpaces and tabs immediately after a control character are ignored.", "subsections": [] }, "Commonly, authors structure the source of documents or macro files with": { "content": "them.\n\n.de center\n. if \\\\n[.br] \\\n. br\n. ce \\\\$1\n..\n.\n.\n.de right-align\n.->if \\\\n[.br] \\\n.->->br\n.->rj \\\\$1\n..\n\nIf you assign an empty blank line trap, you can separate macro\ndefinitions (or any input lines) with blank lines.\n\n.de do-nothing\n..\n.blm do-nothing \\\" activate blank line trap\n\n.de center\n. if \\\\n[.br] \\\n. br\n. ce \\\\$1\n..\n\n\n.de right-align\n.->if \\\\n[.br] \\\n.->->br\n.->rj \\\\$1\n..\n\n.blm \\\" deactivate blank line trap\n\n*Note Blank Line Traps::.\n", "subsections": [] }, "File: groff.info, Node: Calling Macros, Next: Using Escape Sequences, Prev: Invoking Requests, Up: Formatter Instructions": { "content": "", "subsections": [] }, "If a macro of the desired name does not exist when called, it is": { "content": "created, assigned an empty definition, and a warning in category 'mac'\nis emitted. Calling an undefined macro does end a macro definition\nnaming it as its end macro (*note Writing Macros::).\n\nTo embed spaces within a macro argument, enclose the argument in\nneutral double quotes '\"'. Horizontal motion escape sequences are\nsometimes a better choice for arguments to be formatted as text.\n\nConsider calls to a hypothetical section heading macro 'uh'.\n\n.uh The Mouse Problem\n.uh \"The Mouse Problem\"\n.uh The\\~Mouse\\~Problem\n.uh The\\ Mouse\\ Problem\n", "subsections": [] }, "The first line calls 'uh' with three arguments: 'The', 'Mouse', and": { "content": "'Problem'. The remainder call the 'uh' macro with one argument, 'The", "subsections": [] }, "Mouse Problem'. The last solution, using escaped spaces, can be found": { "content": "in documents prepared for AT&T 'troff'. It can cause surprise when text\nis adjusted, because '\\' inserts a fixed-width, non-breaking\nspace. GNU 'troff''s '\\~' escape sequence inserts an adjustable,\nnon-breaking space.(1) (*note Calling Macros-Footnote-1::)\n\nThe foregoing raises the question of how to embed neutral double\nquotes or backslashes in macro arguments when those characters are\ndesired as literals. In GNU 'troff', the special character escape\nsequence '\\[rs]' produces a backslash and '\\[dq]' a neutral double\nquote.\n\nIn GNU 'troff''s AT&T compatibility mode, these characters remain\navailable as '\\(rs' and '\\(dq', respectively. AT&T 'troff' did not\nconsistently define these special characters, but its descendants can be\nmade to support them. *Note Device and Font Description Files::.\n\nIf even that is not feasible, options remain. To obtain a literal\nescape character in a macro argument, you can simply type it if you\nchange or disable the escape character first. *Note Using Escape", "subsections": [] }, "Sequences::. Otherwise, you must escape the escape character repeatedly": { "content": "to a context-dependent extent. *Note Copy Mode::.\n\nFor the (neutral) double quote, you have recourse to an obscure\nsyntactical feature of AT&T 'troff'. Because a double quote can begin a\nmacro argument, the formatter keeps track of whether the current\nargument was started thus, and doesn't require a space after the double\nquote that ends it.(2) (*note Calling Macros-Footnote-2::) In the\nargument list to a macro, a double quote that isn't preceded by a\nspace doesn't start a macro argument. If not preceded by a double\nquote that began an argument, this double quote becomes part of the\nargument. Furthermore, within a quoted argument, a pair of adjacent\ndouble quotes becomes a literal double quote.\n\n.de eq\n. tm arg1:\\\\$1 arg2:\\\\$2 arg3:\\\\$3\n. tm arg4:\\\\$4 arg5:\\\\$5 arg6:\\\\$6\n.. \\\" 4 backslashes on the next line\n.eq a\" \"b c\" \"de\"f\\\\\\\\g\" h\"\"i \"j\"\"k\"\nerror-> arg1:a\" arg2:b c arg3:de\nerror-> arg4:f\\g\" arg5:h\"\"i arg6:j\"k\n\nApart from the complexity of the rules, this traditional solution has\nthe disadvantage that double quotes don't survive repeated argument\nexpansion in AT&T 'troff' or GNU 'troff''s compatibility mode. This can\nfrustrate efforts to pass such arguments intact through multiple macro\ncalls.\n\n.cp 1\n.de eq\n. tm arg1:\\\\$1 arg2:\\\\$2 arg3:\\\\$3\n. tm arg4:\\\\$4 arg5:\\\\$5 arg6:\\\\$6\n..\n.de xe\n. eq \\\\$1 \\\\$2 \\\\$3 \\\\$4 \\\\$5 \\\\$6\n.. \\\" 8 backslashes on the next line\n.xe a\" \"b c\" \"de\"f\\\\\\\\\\\\\\\\g\" h\"\"i \"j\"\"k\"\nerror-> arg1:a\" arg2:b arg3:c\nerror-> arg4:de arg5:f\\g\" arg6:h\"\"i\n\nOutside of compatibility mode, GNU 'troff' doesn't exhibit this\nproblem because it tracks the nesting depth of interpolations. *Note\nImplementation Differences::.\n", "subsections": [] }, "File: groff.info, Node: Using Escape Sequences, Next: Delimiters, Prev: Calling Macros, Up: Formatter Instructions": { "content": "", "subsections": [] }, "Whereas requests must occur on control lines, escape sequences can occur": { "content": "intermixed with text and may appear in arguments to requests, macros,\nand other escape sequences. An escape sequence is introduced by the\nescape character, a backslash '\\' (but see the 'ec' request below). The\nnext character selects the escape's function.\n\nEscape sequences vary in length. Some take an argument, and of\nthose, some have different syntactical forms for a one-character,\ntwo-character, or arbitrary-length argument. Others accept only an\narbitrary-length argument. In the former scheme, a one-character\nargument follows the function character immediately, an opening\nparenthesis '(' introduces a two-character argument (no closing\nparenthesis is used), and an argument of arbitrary length is enclosed in\nbrackets '[]'. In the latter scheme, the user selects a delimiter\ncharacter. A few escape sequences are idiosyncratic, and support both\nof the foregoing conventions ('\\s'), designate their own termination\nsequence ('\\?'), consume input until the next newline ('\\!', '\\\"',\n'\\#'), or support an additional modifier character ('\\s' again, and\n'\\n'). As with requests, use of some escape sequences in source\ndocuments may interact poorly with a macro package you use; consult its\ndocumentation to learn of \"safe\" sequences or alternative facilities it\nprovides to achieve the desired result.\n\nIf an escape character is followed by a character that does not\nidentify a defined operation, the escape character is ignored (producing\na diagnostic of the 'escape' warning category, which is not enabled by\ndefault) and the following character is processed normally.\n\n$ groff -Tps -ww\n.nr N 12\n.ds co white\n.ds animal elephant\nI have \\fI\\nN \\*(co \\*[animal]s,\\f[]\nsaid \\P.\\&\\~Pseudo Pachyderm.\nerror-> warning: escape character ignored before 'P'\n=> I have 12 white elephants, said P. Pseudo Pachyderm.\n\nEscape sequence interpolation is of higher precedence than escape\nsequence argument interpretation. This rule affords flexibility in\nusing escape sequences to construct parameters to other escape\nsequences.\n\n.ds family C\\\" Courier\n.ds style I\\\" oblique\nChoice a typeface \\f(\\*[family]\\*[style]wisely.\n=> Choose a typeface wisely.\n\nIn the above, the syntax form '\\f(' accepts only two characters for an\nargument; the example works because the subsequent escape sequences are\ninterpolated before the selection escape sequence argument is processed,\nand strings 'family' and 'style' interpolate one character each.(1)\n(*note Using Escape Sequences-Footnote-1::)\n\nThe escape character is nearly always interpreted when encountered;\nit is therefore desirable to have a way to interpolate it, disable it,\nor change it.\n\n-- Escape sequence: \\e\nInterpolate the escape character.\n\nThe '\\[rs]' special character escape sequence formats a backslash\nglyph. In macro and string definitions, the input sequences '\\\\' and\n'\\E' defer interpretation of escape sequences. *Note Copy Mode::.\n\n-- Request: .eo\nDisable the escape mechanism except in copy mode. Once this\nrequest is invoked, no input character is recognized as starting an\nescape sequence in interpretation mode.\n\n-- Request: .ec [o]\nRecognize the ordinary character O as the escape character. If O\nis absent or invalid, the default escape character '\\' is selected.\n\nSwitching escape sequence interpretation off to define a macro and\nback on afterward can obviate the need to double the escape character\nwithin the definition. *Note Writing Macros::. This technique is not\navailable if your macro needs to interpolate values at the time it is\ndefined--but many do not.\n\n.\\\" simplified `BR` macro from the man(7) macro package\n.eo\n.de BR\n. ds result \\&\n. while (\\n[.$] >= 2) \\{\\\n. as result \\fB\\$1\\fR\\$2\\\"\n. shift 2\n. \\}\n. if \\n[.$] .as result \\fB\\$1\\\"\n\\*[result]\n. rm result\n. ft R\n..\n.ec\n\n-- Request: .ecs\n-- Request: .ecr\nThe 'ecs' request stores the escape character for recall with\n'ecr'. 'ecr' sets the escape character to '\\' if none has been\nsaved.\n\nUse these requests together to temporarily change the escape\ncharacter.\n\nUsing a different escape character, or disabling it, when calling\nmacros not under your control will likely cause errors, since GNU\n'troff' has no mechanism to \"intern\" macros--that is, to convert a macro\ndefinition into a form independent of its representation.(2) (*note", "subsections": [] }, "Using Escape Sequences-Footnote-2::) When a macro is called, its": { "content": "contents are interpreted literally.\n", "subsections": [] }, "File: groff.info, Node: Delimiters, Prev: Using Escape Sequences, Up: Formatter Instructions": { "content": "", "subsections": [] }, "Some escape sequences that require parameters use delimiters. The": { "content": "neutral apostrophe ''' is a popular choice and shown in this document.\nThe neutral double quote '\"' is also commonly seen. Letters, numerals,\nand leaders can be used. Punctuation characters are likely better\nchoices, except for those defined as infix operators in numeric\nexpressions; see below.\n\n\\l'1.5i\\[bu]' \\\" draw 1.5 inches of bullet glyphs\n\nThe following escape sequences don't take arguments and thus are\nallowed as delimiters: '\\', '\\%', '\\|', '\\^', '\\{', '\\}', '\\'',\n'\\`', '\\-', '\\', '\\!', '\\?', '\\)', '\\/', '\\,', '\\&', '\\:', '\\~', '\\0',\n'\\a', '\\c', '\\d', '\\e', '\\E', '\\p', '\\r', '\\t', and '\\u'. However,\nusing them this way is discouraged; they can make the input confusing to\nread.\n\nA few escape sequences, '\\A', '\\b', '\\o', '\\w', '\\X', and '\\Z',\naccept a newline as a delimiter. Newlines that serve as delimiters\ncontinue to be recognized as input line terminators.\n\nA caf\\o\ne\\(aa\nin Paris\n=> A cafe' in Paris\n\nUse of newlines as delimiters in escape sequences is also discouraged.\n\nFinally, the escape sequences '\\D', '\\h', '\\H', '\\l', '\\L', '\\N',\n'\\R', '\\s', '\\S', '\\v', and '\\x' prohibit many delimiters.\n\n* the numerals '0'-'9' and the decimal point '.'\n\n* the (single-character) operators '+-/*%<>=&:()'\n\n* the space and tab characters\n\n* any escape sequences other than '\\%', '\\:', '\\{', '\\}', '\\'', '\\`',\n'\\-', '\\', '\\!', '\\/', '\\c', '\\e', and '\\p'\n\nDelimiter syntax is complex and flexible primarily for historical\nreasons; the foregoing restrictions need be kept in mind mainly when\nusing 'groff' in AT&T compatibility mode. GNU 'troff' keeps track of\nthe nesting depth of escape sequence interpolations, so the only\ncharacters you need to avoid using as delimiters are those that appear\nin the arguments you input, not any that result from interpolation.\nTypically, ''' works fine. *Note Implementation Differences::.\n\n$ groff -Tps\n.de Mw\n. nr wd \\w'\\\\$1'\n. tm \"\\\\$1\" is \\\\n(wd units wide.\n..\n.Mw Wet'suwet'en\n.Mw Wet+200i\n.cp 1 \\\" turn on compatibility mode\n.Mw Wet'suwet'en\n.Mw Wet'\n.Mw Wet+200i\nerror-> \"Wet'suwet'en\" is 54740 units wide.\nerror-> \"Wet'+200i\" is 42610 units wide.\nerror-> \"Wet'suwet'en\" is 15860 units wide.\nerror-> \"Wet'\" is 15860 units wide.\nerror-> \"Wet'+200i\" is 14415860 units wide.\n\nWe see here that in compatibility mode, the part of the argument\nafter the ''' delimiter escapes from its context and, if nefariously\ncrafted, influences the computation of the WD register's value in a\nsurprising way.\n", "subsections": [] }, "File: groff.info, Node: Comments, Next: Registers, Prev: Formatter Instructions, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.7 Comments", "content": "" } ] }, "One of the most common forms of escape sequence is the comment.(1)": { "content": "(*note Comments-Footnote-1::)\n\n-- Escape sequence: \\\"\nStart a comment. Everything up to the next newline is ignored.\n\nThis may sound simple, but it can be tricky to keep the comments\nfrom interfering with the appearance of the output. If the escape\nsequence is to the right of some text or a request, that portion of\nthe line is ignored, but spaces preceding it are processed normally\nby GNU 'troff'. This affects only the 'ds' and 'as' requests and\ntheir variants.\n\nOne possibly irritating idiosyncrasy is that tabs should not be\nused to vertically align comments in the source document. Tab\ncharacters are not treated as separators between a request name and\nits first argument, nor between arguments.\n\nA comment on a line by itself is treated as a blank line, because\nafter eliminating the comment, that is all that remains.\n\nTest\n\\\" comment\nTest\n=> Test\n=>\n=> Test\n\nTo avoid this, it is common to combine the empty request with the\ncomment escape sequence as '.\\\"', causing the input line to be\nignored.\n\nAnother commenting scheme sometimes seen is three consecutive\nsingle quotes (''''') at the beginning of a line. This works, but\nGNU 'troff' emits a warning diagnostic (if enabled) about an\nundefined macro (namely '''').\n\n-- Escape sequence: \\#\nStart a comment; everything up to and including the next newline is\nignored. This 'groff' extension was introduced to avoid the\nproblems described above.\n\nTest\n\\# comment\nTest\n=> Test Test\n\n-- Request: .ig [end]\nIgnore input until, in the current conditional block (if any),(2)\n(*note Comments-Footnote-2::) the macro END is called at the start\nof a control line, or the control line '..' is encountered if END\nis not specified. 'ig' is parsed as if it were a macro definition,\nbut its contents are discarded, not stored.(3) (*note\nComments-Footnote-3::)\n\nhand\\c\n.de TX\nfasting\n..\n.ig TX\nThis is part of a large block of input that has been\ntemporarily(?) commented out.\nWe can restore it simply by removing the .ig request and\nthe call of its end macro.\n.TX\n=> handfasting\n", "subsections": [] }, "File: groff.info, Node: Registers, Next: Manipulating Filling and Adjustment, Prev: Formatter Instructions, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.8 Registers", "content": "In the 'roff' language, numbers can be stored in \"registers\". Many\nbuilt-in registers exist, supplying anything from the date to details of\nformatting parameters. You can also define your own. *Note" } ] }, "Identifiers::, for information on constructing a valid name for a": { "content": "register.\n\n* Menu:\n\n* Setting Registers::\n* Interpolating Registers::\n* Auto-increment::\n* Assigning Register Formats::\n* Built-in Registers::\n", "subsections": [] }, "File: groff.info, Node: Setting Registers, Next: Interpolating Registers, Prev: Registers, Up: Registers": { "content": "", "subsections": [] }, "Define registers and update their values with the 'nr' request or the": { "content": "'\\R' escape sequence.\n\n-- Request: .nr ident value\n-- Escape sequence: \\R'ident value'\nSet register IDENT to VALUE. If IDENT doesn't exist, GNU 'troff'\ncreates it. In the '\\R' escape sequence, the delimiter need not be\na neutral apostrophe; see *note Delimiters::. It also does not\nproduce an input token in GNU 'troff'. *Note Gtroff Internals::.\n\n.nr a (((17 + (3 * 4))) % 4)\n\\n[a]\n.\\R'a (((17 + (3 * 4))) % 4)'\n\\n[a]\n=> 1 1\n\n(Later, we will discuss additional forms of 'nr' and '\\R' that can\nchange a register's value after it is dereferenced but before it is\ninterpolated. *Note Auto-increment::.)\n\nThe complete transparency of '\\R' can cause surprising effects if\nyou use registers like '.k', which get evaluated at the time they\nare accessed.\n\n.ll 1.6i\n.\naaa bbb ccc ddd eee fff ggg hhh\\R':k \\n[.k]'\n.tm :k == \\n[:k]\n=> :k == 126950\n.\n.br\n.\naaa bbb ccc ddd eee fff ggg hhh\\h'0'\\R':k \\n[.k]'\n.tm :k == \\n[:k]\n=> :k == 15000\n\nIf you process this with the PostScript device ('-Tps'), there will\nbe a line break eventually after 'ggg' in both input lines.\nHowever, after processing the space after 'ggg', the partially\ncollected line is not overfull yet, so GNU 'troff' continues to\ncollect input until it sees the space (or in this case, the\nnewline) after 'hhh'. At this point, the line is longer than the\nline length, and the line gets broken.\n\nIn the first input line, since the '\\R' escape sequence leaves no\ntraces, the check for the overfull line hasn't been done yet at the\npoint where '\\R' gets handled, and you get a value for the '.k'\nregister that is even greater than the current line length.\n\nIn the second input line, the insertion of '\\h'0'' to cause a\nzero-width motion forces GNU 'troff' to check the line length,\nwhich in turn causes the start of a new output line. Now '.k'\nreturns the expected value.\n\n'nr' and '\\R' each have two additional special forms to increment or\ndecrement a register.\n\n-- Request: .nr ident +value\n-- Request: .nr ident -value\n-- Escape sequence: \\R'ident +value'\n-- Escape sequence: \\R'ident -value'\nIncrement (decrement) register IDENT by VALUE. In the '\\R' escape\nsequence, the delimiter need not be a neutral apostrophe; see *note\nDelimiters::.\n\n.nr a 1\n.nr a +1\n\\na\n=> 2\n\nA leading minus sign in VALUE is always interpreted as a\ndecrementation operator, not an algebraic sign. To assign a\nregister a negative value or the negated value of another register,\nyou can force GNU 'troff' to interpret '-' as a negation or minus,\nrather than decrementation, operator: enclose it with its operand\nin parentheses or subtract it from zero.\n\n.nr a 7\n.nr b 3\n.nr a -\\nb\n\\na\n=> 4\n.nr a (-\\nb)\n\\na\n=> -3\n.nr a 0-\\nb\n\\na\n=> -3\n\nIf a register's prior value does not exist (the register was\nundefined), an increment or decrement is applied as if to 0.\n\n-- Request: .rr ident\nRemove register IDENT. If IDENT doesn't exist, the request is\nignored. Technically, only the name is removed; the register's\ncontents are still accessible under aliases created with 'aln', if\nany.\n\n-- Request: .rnn ident1 ident2\nRename register IDENT1 to IDENT2. If IDENT1 doesn't exist, the\nrequest is ignored. Renaming a built-in register does not\notherwise alter its properties.\n\n-- Request: .aln new old\nCreate an alias NEW for an existing register OLD, causing the names\nto refer to the same stored object. If OLD is undefined, a warning\nin category 'reg' is produced and the request is ignored. *Note\nWarnings::, for information about the enablement and suppression of\nwarnings.\n\nTo remove a register alias, invoke 'rr' on its name. A register's\ncontents do not become inaccessible until it has no more names.\n", "subsections": [] }, "File: groff.info, Node: Interpolating Registers, Next: Auto-increment, Prev: Setting Registers, Up: Registers": { "content": "Register contents are interpolated with the '\\n' escape sequence.\n\n-- Escape sequence: \\ni\n-- Escape sequence: \\n(id\n-- Escape sequence: \\n[ident]\nInterpolate register with name IDENT (one-character name I,\ntwo-character name ID). '\\n' is interpreted even in copy mode\n(*note Copy Mode::). If the register is undefined, it is created\nand assigned a value of '0', that value is interpolated, and a\nwarning in category 'reg' is emitted. *Note Warnings::, for\ninformation about the enablement and suppression of warnings.\n\n.nr a 5\n.nr as \\na+\\na\n\\n(as\n=> 10\n\n.nr a1 5\n.nr ab 6\n.ds str b\n.ds num 1\n\\n[a\\n[num]]\n=> 5\n\\n[a\\*[str]]\n=> 6\n", "subsections": [] }, "File: groff.info, Node: Auto-increment, Next: Assigning Register Formats, Prev: Interpolating Registers, Up: Registers": { "content": "", "subsections": [] }, "Registers can also be incremented or decremented by a configured amount": { "content": "at the time they are interpolated. The value of the increment is\nspecified with a third argument to the 'nr' request, and a special\ninterpolation syntax is used to alter and then retrieve the register's\nvalue. Together, these features are called \"auto-increment\".(1) (*note", "subsections": [] }, "Auto-increment-Footnote-1::)": { "content": "-- Request: .nr ident value incr\nSet register IDENT to VALUE and its auto-incrementation amount to\nto INCR. The '\\R' escape sequence doesn't support an INCR\nargument.\n\nAuto-incrementation is not completely automatic; the '\\n' escape\nsequence in its basic form never alters the value of a register. To\napply auto-incrementation to a register, interpolate it with '\\n?'.\n\n-- Escape sequence: \\n+i\n-- Escape sequence: \\n-i\n-- Escape sequence: \\n+(id\n-- Escape sequence: \\n-(id\n-- Escape sequence: \\n+[ident]\n-- Escape sequence: \\n-[ident]\nIncrement or decrement IDENT (one-character name I, two-character\nname ID) by the register's auto-incrementation value and then\ninterpolate the new register value. If IDENT has no\nauto-incrementation value, interpolate as with '\\n'.\n\n.nr a 0 1\n.nr xx 0 5\n.nr foo 0 -2\n\\n+a, \\n+a, \\n+a, \\n+a, \\n+a\n.br\n\\n-(xx, \\n-(xx, \\n-(xx, \\n-(xx, \\n-(xx\n.br\n\\n+[foo], \\n+[foo], \\n+[foo], \\n+[foo], \\n+[foo]\n=> 1, 2, 3, 4, 5\n=> -5, -10, -15, -20, -25\n=> -2, -4, -6, -8, -10\n\nTo change the increment value without changing the value of a\nregister, assign the register's value to itself by interpolating it, and\nspecify the desired increment normally. Apply an increment of '0' to\ndisable auto-incrementation of the register.\n", "subsections": [] }, "File: groff.info, Node: Assigning Register Formats, Next: Built-in Registers, Prev: Auto-increment, Up: Registers": { "content": "A writable register's value can be interpolated in several number\nformats. By default, conventional Arabic numerals are used. Other\nformats see use in sectioning and outlining schemes and alternative page\nnumbering arrangements.\n\n-- Request: .af reg fmt\nUse number format FMT when interpolating register REG. Valid\nnumber formats are as follows.\n\n'0...'\nArabic numerals 0, 1, 2, and so on. Any decimal digit is\nequivalent to '0'; the formatter merely counts the digits\nspecified. Multiple Arabic numerals in FMT cause\ninterpolations to be zero-padded on the left if necessary to\nat least as many digits as specified (interpolations never\ntruncate a register value). A register with format '00'\ninterpolates values 1, 2, 3 as '01', '02', '03'. The default\nformat for all writable registers is '0'.\n\n'I'\nUppercase Roman numerals: 0, I, II, III, IV, ...\n\n'i'\nLowercase Roman numerals: 0, i, ii, iii, iv, ...\n\n'A'\nUppercase letters: 0, A, B, C, ..., Z, AA, AB, ...\n\n'a'\nLowercase letters: 0, a, b, c, ..., z, aa, ab, ...\n\nOmitting FMT causes a warning in category 'missing'. *Note\nWarnings::, for information about the enablement and suppression of\nwarnings. Specifying an unrecognized format is an error.\n\nZero values are interpolated as '0' in non-Arabic formats.\nNegative quantities are prefixed with '-' irrespective of format.\nIn Arabic formats, the sign supplements the field width. If REG\ndoesn't exist, it is created with a zero value.\n\n.nr a 10\n.af a 0 \\\" the default format\n\\na,\n.af a I\n\\na,\n.af a 321\n.nr a (-\\na)\n\\na,\n.af a a\n\\na\n=> 10, X, -010, -j\n\nThe representable extrema in the 'i' and 'I' formats correspond to\nArabic ?39,999. GNU 'troff' uses 'w' and 'z' to represent 5,000\nand 10,000 in Roman numerals, respectively, following the\nconvention of AT&T 'troff'--currently, the correct glyphs for Roman\nnumerals five thousand ('U+2181') and ten thousand ('U+2182') are\nnot used.\n\nAssigning the format of a read-only register is an error. Instead,\ncopy the read-only register's value to, and assign the format of, a\nwritable register.\n\n-- Escape sequence: \\gr\n-- Escape sequence: \\g(rg\n-- Escape sequence: \\g[reg]\nInterpolate the format of the register REG (one-character name R,\ntwo-character name RG). Zeroes represent Arabic formats. If REG\nis not defined, REG is not created and nothing is interpolated.\n'\\g' is interpreted even in copy mode (*note Copy Mode::).\n\nGNU 'troff' interprets only Arabic numerals. The Roman numeral or\nalphabetic formats cannot be used as operands to arithmetic operators in\nexpressions (*note Numeric Expressions::). For instance, it may be\ndesirable to test the page number independently of its format.\n\n.af % i \\\" front matter\n.de header-trap\n. \\\" To test the page number, we need it in Arabic.\n. ds saved-page-number-format \\\\g%\\\"\n. af % 0\n. nr page-number-in-decimal \\\\n%\n. af % \\\\*[saved-page-number-format]\n. ie \\\\n[page-number-in-decimal]=1 .do-first-page-stuff\n. el \\{\\\n. ie o .do-odd-numbered-page-stuff\n. el .do-even-numbered-page-stuff\n. \\}\n. rm saved-page-number-format\n..\n.wh 0 header-trap\n", "subsections": [] }, "File: groff.info, Node: Built-in Registers, Prev: Assigning Register Formats, Up: Registers": { "content": "Predefined registers whose identifiers start with a dot are read-only.", "subsections": [] }, "Many are Boolean-valued, interpolating a true or false value testable": { "content": "with the 'if', 'ie', or 'while' requests. Some read-only registers are\nstring-valued, meaning that they interpolate text.\n\n*Caution:* Built-in registers are subject to removal like others;\nonce removed, they can be recreated only as normal writable registers\nand will not reflect formatter state.\n\nA register name (without the dot) is often associated with a request\nof the same name. A complete listing of all built-in registers can be\nfound in *note Register Index::.\n\nWe present here a few built-in registers that are not described\nelsewhere in this manual; they have to do with invariant properties of\nGNU 'troff', or obtain information about the formatter's command-line\noptions, processing progress, or the operating environment.\n\n'\\n[.A]'\nApproximate output is being formatted (Boolean-valued); see 'groff'\n'-a' option (*note Groff Options::).\n\n'\\n[.c]'\n'\\n[c.]'\nInput line number. 'c.' is a writable synonym, affecting\nsubsequent interpolations of both '.c' and 'c.'.\n\n'\\n[.F]'\nName of input file (string-valued).\n\n'\\n[.g]'\nAlways true in GNU 'troff' (Boolean-valued). Documents can use\nthis to ask the formatter if it claims 'groff' compatibility.\n\n'\\n[.P]'\nOutput page selection status (Boolean-valued); see 'groff' '-o'\noption (*note Groff Options::).\n\n'\\n[.R]'\nCount of available unused registers; always 10,000 in GNU\n'troff'.(1) (*note Built-in Registers-Footnote-1::)\n\n'\\n[.T]'\nIndicator of output device selection (Boolean-valued); see 'groff'\n'-T' option (*note Groff Options::).\n\n'\\n[.U]'\nUnsafe mode enablement status (Boolean-valued); see 'groff' '-U'\noption (*note Groff Options::).\n\n'\\n[.x]'\nMajor version number of the running GNU 'troff' formatter. For\nexample, if the version number is 1.23.0, then '.x' contains '1'.\n\n'\\n[.y]'\nMinor version number of the running GNU 'troff' formatter. For\nexample, if the version number is 1.23.0, then '.y' contains '23'.\n\n'\\n[.Y]'\nRevision number of the running GNU 'troff' formatter. For example,\nif the version number is 1.23.0, then '.Y' contains '0'.\n\n'\\n[$$]'\nProcess identifier (PID) of the GNU 'troff' program in its\noperating environment.\n\nDate- and time-related registers are set per the local time as\ndetermined by 'localtime(3)' when the formatter launches. This\ninitialization can be overridden by 'SOURCEDATEEPOCH' and 'TZ'; see\n*note Environment::.\n\n'\\n[seconds]'\nCount of seconds elapsed in the minute (0-60).\n\n'\\n[minutes]'\nCount of minutes elapsed in the hour (0-59).\n\n'\\n[hours]'\nCount of hours elapsed since midnight (0-23).\n\n'\\n[dw]'\nDay of the week (1-7; 1 is Sunday).\n\n'\\n[dy]'\nDay of the month (1-31).\n\n'\\n[mo]'\nMonth of the year (1-12).\n\n'\\n[year]'\nGregorian year.\n\n'\\n[yr]'\nGregorian year minus 1900. This register is incorrectly documented\nin the AT&T 'troff' manual as storing the last two digits of the\ncurrent year. That claim stopped being true in 2000. Old 'troff'\ninput that looks like:\n\n'\\\" The year number is a surprise after 1999.\nThis document was formatted in 19\\n(yr.\n\ncan be corrected to:\n\nThis document was formatted in \\n[year].\n\nor, for portability across many 'roff' programs, to the following.\n\n.nr y4 1900+\\n(yr\nThis document was formatted in \\n(y4.\n", "subsections": [] }, "File: groff.info, Node: Manipulating Filling and Adjustment, Next: Manipulating Hyphenation, Prev: Registers, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.9 Manipulating Filling and Adjustment", "content": "" } ] }, "When an output line is pending (see below), a break moves the drawing": { "content": "position to the beginning of the next text baseline, interrupting\nfilling. Various ways of causing breaks were shown in *note Breaking::.", "subsections": [] }, "The 'br' request likewise causes a break. Several other requests imply": { "content": "breaks: 'bp', 'ce', 'cf', 'fi', 'fl', 'in', 'nf', 'rj', 'sp', 'ti', and\n'trf'. If the no-break control character is used with any of these\nrequests, GNU 'troff' suppresses the break; instead the requested\noperation takes effect at the next break. ''br' does nothing.\n\n.ll 55n\nThis line is normally filled and adjusted.\n.br\nA line's alignment is decided\n'ce \\\" Center the next input line (no break).\nwhen it is output.\nThis line returns to normal filling and adjustment.\n=> This line is normally filled and adjusted.\n=> A line's alignment is decided when it is output.\n=> This line returns to normal filling and adjustment.\n", "subsections": [] }, "Output line properties like page offset, indentation, adjustment, and": { "content": "even the location of its text baseline, are not determined until the\nline has been broken. An output line is said to be \"pending\" if some\ninput has been collected but an output line corresponding to it has not\nyet been written; such an output line is also termed \"partially\ncollected\". If no output line is pending, it is as if a break has\nalready happened; additional breaks, whether explicit or implicit, have\nno effect. If the vertical drawing position is negative--as it is when\nthe formatter starts up--a break starts a new page (even if no output\nline is pending) unless an end-of-input macro is being interpreted.\n*Note End-of-input Traps::.\n\n-- Request: .br\nBreak the line: emit any pending output line without adjustment.\n\nfoo bar\n.br\nbaz\n'br\nqux\n=> foo bar\n=> baz qux\n\nSometimes you want to prevent a break within a phrase or between a\nquantity and its units.\n\n-- Escape sequence: \\~\nInsert an unbreakable space that is adjustable like an ordinary\nspace. It is discarded from the end of an output line if a break\nis forced.\n\nSet the output speed to\\~1.\nThere are 1,024\\~bytes in 1\\~KiB.\nJ.\\~F.\\~Ossanna wrote the original CSTR\\~#54.\n\nBy default, GNU 'troff' fills text and adjusts it to reach the output\nline length. The 'nf' request disables filling; the 'fi' request\nree\"nables it.\n\n-- Request: .fi\n-- Register: \\n[.u]\nEnable filling of output lines; a pending output line is broken.\nThe read-only register '.u' is set to 1. The filling enablement\nstatus, sometimes called \"fill mode\", is associated with the\nenvironment (*note Environments::). *Note Line Continuation::, for\ninteraction with the '\\c' escape sequence.\n\n-- Request: .nf\nDisable filling of output lines: the output line length (*note Line\nLayout::) is ignored and output lines are broken where the input\nlines are. A pending output line is broken and adjustment is\nsuppressed. The read-only register '.u' is set to 0. The filling\nenablement status is associated with the environment (*note\nEnvironments::). See *note Line Continuation::, for interaction\nwith the '\\c' escape sequence.\n\n-- Request: .ad [mode]\n-- Register: \\n[.j]\nEnable output line adjustment in MODE, taking effect when the\npending (or next) output line is broken. Adjustment is suppressed\nwhen filling is. MODE can have one of the following values.\n\n'b'\n'n'\nAdjust \"normally\": if the output line does not consume the\ndistance between the indentation and the configured output\nline length, GNU 'troff' stretches adjustable spaces within\nthe line until that length is reached. When the indentation\nis zero, this mode spreads the line to both the left and right\nmargins. This is the GNU 'troff' default.\n\n'c'\nCenter filled text. Contrast with the 'ce' request, which\ncenters text without filling it.\n\n'l'\nAlign text to the left without adjusting it.\n\n'r'\nAlign text to the right without adjusting it.\n\nMODE can also be a value previously stored in the '.j' register.\nUsing 'ad' without an argument is the same as '.ad \\n[.j]'; unless\nfilling is disabled, GNU 'troff' resumes adjusting lines in the\nsame way it did before adjustment was disabled by invocation of the\n'na' request.\n\nThe adjustment mode and enablement status are encoded in the\nread-only register '.j'. These parameters are associated with the\nenvironment (*note Environments::).\n\nThe value of '.j' for any adjustment mode is an implementation\ndetail and should not be relied upon as a programmer's interface.\nDo not write logic to interpret or perform arithmetic on it.\n\n.ll 48n\n.de AD\n. br\n. ad \\\\$1\n..\n.de NA\n. br\n. na\n..\nleft\n.AD r\n.nr ad \\n(.j\nright\n.AD c\ncenter\n.NA\nleft\n.AD\ncenter\n.AD \\n(ad\nright\n=> left\n=> right\n=> center\n=> left\n=> center\n=> right\n\n-- Request: .na\nDisable output line adjustment. This produces the same output as\nleft-alignment, but the value of the adjustment mode register '.j'\nis altered differently. The adjustment mode and enablement status\nare associated with the environment (*note Environments::).\n\n-- Request: .brp\n-- Escape sequence: \\p\nBreak, adjusting the line per the current adjustment mode. '\\p'\nschedules a break with adjustment at the next word boundary. The\nescape sequence is itself neither a break nor a space of any kind;\nit can thus be placed in the middle of a word to cause a break at\nthe end of that word.\n\nBreaking with immediate adjustment can produce ugly results since\nGNU 'troff' doesn't have a sophisticated paragraph-building\nalgorithm, as TeX has, for example. Instead, GNU 'troff' fills and\nadjusts a paragraph line by line.\n\n.ll 4.5i\nThis is an uninteresting sentence.\nThis is an uninteresting sentence.\\p\nThis is an uninteresting sentence.\n\nis formatted as follows.\n\nThis is an uninteresting sentence. This is\nan uninteresting sentence.\nThis is an uninteresting sentence.\n\nTo clearly present the next couple of requests, we must introduce the\nconcept of \"productive\" input lines. A \"productive input line\" is one\nthat directly produces formatted output. Text lines produce output,(1)\n(*note Manipulating Filling and Adjustment-Footnote-1::) as do control\nlines containing requests like 'tl' or escape sequences like '\\D'.", "subsections": [] }, "Macro calls are not directly productive, and thus not counted, but": { "content": "their interpolated contents can be. Empty requests, and requests and\nescape sequences that define registers or strings or alter the\nformatting environment (as with changes to the size, face, height,\nslant, or color of the type) are not productive. We will also preview\nthe output line continuation escape sequence, '\\c', which \"connects\" two\ninput lines that would otherwise be counted separately. (2) (*note", "subsections": [] }, "Manipulating Filling and Adjustment-Footnote-2::)": { "content": ".de hello\nHello, world!\n..\n.ce \\\" center output of next productive input line\n.\n.nr junk-reg 1\n.ft I\nChorus: \\c\n.ft\n.hello\nWent the day well?\n=> Chorus: Hello, world!\n=> Went the day well?\n\n-- Request: .ce [n]\n-- Register: \\n[.ce]\nBreak (unless the no-break control character is used), center the\noutput of the next N productive input lines with respect to the\nline length and indentation without filling, then break again\nregardless of the invoking control character. If the argument is\nnot positive, centering is disabled. Omitting the argument implies\nan N of '1'. The count of lines remaining to be centered is stored\nin the read-only register '.ce' and is associated with the\nenvironment (*note Environments::).\n\nWhile the '.ad c' request also centers text, it fills the text as\nwell.\n\n.de FR\nThis is a small text fragment that shows the differences\nbetween the `.ce' and the `.ad c' requests.\n..\n.ll 4i\n.ce 1000\n.FR\n.ce 0\n\n.ad c\n.FR\n=> This is a small text fragment that shows\n=> the differences\n=> between the `.ce' and the `.ad c' requests.\n=>\n=> This is a small text fragment that shows\n=> the differences between the `.ce' and\n=> the `.ad c' requests.\n\nThe previous example illustrates a common idiom of turning\ncentering on for a quantity of lines far in excess of what is\nrequired, and off again after the text to be centered. This\ntechnique relieves humans of counting lines for requests that take\na count of input lines as an argument.\n\n-- Request: .rj [n]\n-- Register: \\n[.rj]\nBreak (unless the no-break control character is used), align the\noutput of the next N productive input lines to the right margin\nwithout filling, then break again regardless of the control\ncharacter. If the argument is not positive, right-alignment is\ndisabled. Omitting the argument implies an N of '1'. The count of\nlines remaining to be right-aligned is stored in the read-only\nregister '.rj' and is associated with the environment (*note\nEnvironments::).\n\n.ll 49n\n.rj 3\nAt first I hoped that such a technically unsound\nproject would collapse but I soon realized it was\ndoomed to success. \\[em] C. A. R. Hoare\n=> At first I hoped that such a technically unsound\n=> project would collapse but I soon realized it was\n=> doomed to success. -- C. A. R. Hoare\n\n-- Request: .ss word-space-size [additional-sentence-space-size]\n-- Register: \\n[.ss]\n-- Register: \\n[.sss]\nSet the sizes of spaces between words and sentences(3) (*note\nManipulating Filling and Adjustment-Footnote-3::) in twelfths of\nfont's space width (typically one-fourth to one-third em for\nWestern scripts). The default for both parameters is 12. Negative\nvalues are erroneous. The first argument is a minimum; if an\noutput line undergoes adjustment, such spaces may increase in\nwidth. The optional second argument sets the amount of additional\nspace separating sentences on the same output line. If omitted,\nthis amount is set to WORD-SPACE-SIZE. The request is ignored if\nthere are no parameters.\n\nAdditional inter-sentence space is used only if the output line is\nnot full when the end of a sentence occurs in the input. If a\nsentence ends at the end of an input line, then both an inter-word\nspace and an inter-sentence space are added to the output; if two\nspaces follow the end of a sentence in the middle of an input line,\nthen the second space becomes an inter-sentence space in the\noutput. Additional inter-sentence space is not adjusted, but the\ninter-word space that always precedes it may be. Further input\nspaces after the second, if present, are adjusted as normal.\n\nThe read-only registers '.ss' and '.sss' hold the minimal\ninter-word space and additional inter-sentence space amounts,\nrespectively. These parameters are part of the environment (*note\nEnvironments::), and rounded down to the nearest multiple of 12 on\nterminals.\n\nThe 'ss' request can insert discardable horizontal space; that is,\nspace that is discarded at a break. For example, some footnote\nstyles collect the notes into a single paragraph with large gaps\nbetween each note.\n\n.ll 48n\n1.\\~J. Fict. Ch. Soc. 6 (2020), 3\\[en]14.\n.ss 12 48 \\\" applies to next sentence ending\nReprints no longer available through FCS.\n.ss 12 \\\" go back to normal\n2.\\~Better known for other work.\n=> 1. J. Fict. Ch. Soc. 6 (2020), 3-14. Reprints\n=> no longer available through FCS. 2. Better\n=> known for other work.\n\nIf undiscardable space is required, use the '\\h' escape sequence.\n", "subsections": [] }, "File: groff.info, Node: Manipulating Hyphenation, Next: Manipulating Spacing, Prev: Manipulating Filling and Adjustment, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.10 Manipulating Hyphenation", "content": "" } ] }, "When filling, GNU 'troff' hyphenates words as needed at user-specified": { "content": "and automatically determined hyphenation points. The machine-driven\ndetermination of hyphenation points in words requires algorithms and\ndata, and is susceptible to conventions and preferences. Before\ntackling such \"automatic hyphenation\", let us consider how hyphenation\npoints can be set explicitly.\n\nExplicitly hyphenated words such as \"mother-in-law\" are eligible for\nbreaking after each of their hyphens. Relatively few words in a\nlanguage offer such obvious break points, however, and automatic\ndetection of syllabic (or phonetic) boundaries for hyphenation is not\nperfect,(1) (*note Manipulating Hyphenation-Footnote-1::) particularly\nfor unusual words found in technical literature. We can instruct GNU\n'troff' how to hyphenate specific words if the need arises.\n\n-- Request: .hw word ...\nDefine each \"hyphenation exception\" WORD with each hyphen '-' in\nthe word indicating a hyphenation point. For example, the request\n\n.hw in-sa-lub-rious alpha\n\nmarks potential hyphenation points in \"insalubrious\", and prevents\n\"alpha\" from being hyphenated at all.\n\nBesides the space character, any character whose hyphenation code\nis zero can be used to separate the arguments of 'hw' (see the\n'hcode' request below). In addition, this request can be used more\nthan once.\n\nHyphenation points specified with 'hw' are not subject to the\nwithin-word placement restrictions imposed by the 'hy' request (see\nbelow).\n\nHyphenation exceptions specified with the 'hw' request are\nassociated with the hyphenation language (see the 'hla' request\nbelow) and environment (*note Environments::); invoking the 'hw'\nrequest in the absence of a hyphenation language is an error.\n\nThe request is ignored if there are no parameters.\n\nThese are known as hyphenation exceptions in the expectation that\nmost users will avail themselves of automatic hyphenation; these\nexceptions override any rules that would normally apply to a word\nmatching a hyphenation exception defined with 'hw'.\n\nSituations also arise when only a specific occurrence of a word needs\nits hyphenation altered or suppressed, or when a URL or similar string\nneeds to be breakable in sensible places without hyphenation.\n\n-- Escape sequence: \\%\n-- Escape sequence: \\:\nTo tell GNU 'troff' how to hyphenate words as they occur in input,\nuse the '\\%' escape sequence; it is the default \"hyphenation\ncharacter\". Each instance within a word indicates to GNU 'troff'\nthat the word may be hyphenated at that point, while prefixing a\nword with this escape sequence prevents it from being otherwise\nhyphenated. This mechanism affects only that occurrence of the\nword; to change the hyphenation of a word for the remainder of\ninput processing, use the 'hw' request.\n\nGNU 'troff' regards the escape sequences '\\X' and '\\Y' as starting\na word; that is, the '\\%' escape sequence in, say,\n'\\X'...'\\%foobar' or '\\Y'...'\\%foobar' no longer prevents\nhyphenation of 'foobar' but inserts a hyphenation point just prior\nto it; most likely this isn't what you want. *Note Postprocessor\nAccess::.\n\n'\\:' inserts a non-printing break point; that is, a word can break\nthere, but the soft hyphen glyph (see below) is not written to the\noutput if it does. This escape sequence is an input word boundary,\nso the remainder of the word is subject to hyphenation as normal.\n\nYou can combine '\\:' and '\\%' to control breaking of a file name or\nURL, or to permit hyphenation only after certain explicit hyphens\nwithin a word.\n\nThe \\%Lethbridge-Stewart-\\:\\%Sackville-Baggins divorce\nwas, in retrospect, inevitable once the contents of\n\\%/var/log/\\:\\%httpd/\\:\\%accesslog on the family web\nserver came to light, revealing visitors from Hogwarts.\n\n-- Request: .hc [char]\nChange the hyphenation character to CHAR. This character then\nworks as the '\\%' escape sequence normally does, and thus no longer\nappears in the output.(2) (*note Manipulating\nHyphenation-Footnote-2::) Without an argument, 'hc' resets the\nhyphenation character to '\\%' (the default). The hyphenation\ncharacter is associated with the environment (*note\nEnvironments::).\n\n-- Request: .shc [c]\nSet the \"soft hyphen character\", inserted when a word is hyphenated\nautomatically or at a hyphenation character, to the ordinary or\nspecial character C.(3) (*note Manipulating\nHyphenation-Footnote-3::) If the argument is omitted, the soft\nhyphen character is set to the default, '\\[hy]'. If no glyph for C\nexists in the font in use at a potential hyphenation point, then\nthe line is not broken there. Neither character definitions\n(specified with the 'char' and similar requests) nor translations\n(specified with the 'tr' request) are applied to C.\n\nSeveral requests influence automatic hyphenation. Because\nconventions vary, a variety of hyphenation modes is available to the\n'hy' request; these determine whether hyphenation will apply to a word\nprior to breaking a line at the end of a page (more or less; see below\nfor details), and at which positions within that word automatically\ndetermined hyphenation points are permissible. The places within a word\nthat are eligible for hyphenation are determined by language-specific\ndata and lettercase relationships. Furthermore, hyphenation of a word\nmight be suppressed due to a limit on consecutive hyphenated lines\n('hlm'), a minimum line length threshold ('hym'), or because the line\ncan instead be adjusted with additional inter-word space ('hys').\n\n-- Request: .hy [mode]\n-- Register: \\n[.hy]\nSet automatic hyphenation mode to MODE, an integer encoding\nconditions for hyphenation; if omitted, '1' is implied. The\nhyphenation mode is available in the read-only register '.hy'; it\nis associated with the environment (*note Environments::). The\ndefault hyphenation mode depends on the localization file loaded\nwhen GNU 'troff' starts up; see the 'hpf' request below.\n\nTypesetting practice generally does not avail itself of every\nopportunity for hyphenation, but the details differ by language and\nsite mandates. The hyphenation modes of AT&T 'troff' were\nimplemented with English-language publishing practices of the 1970s\nin mind, not a scrupulous enumeration of conceivable parameters.\nGNU 'troff' extends those modes such that finer-grained control is\npossible, favoring compatibility with older implementations over a\nmore intuitive arrangement. The means of hyphenation mode control\nis a set of numbers that can be added up to encode the behavior\nsought.(4) (*note Manipulating Hyphenation-Footnote-4::) The\nentries in the following table are termed \"values\"; the sum of the\ndesired values is the \"mode\".\n\n'0'\ndisables hyphenation.\n\n'1'\nenables hyphenation except after the first and before the last\ncharacter of a word.\n\nThe remaining values \"imply\" 1; that is, they enable hyphenation\nunder the same conditions as '.hy 1', and then apply or lift\nrestrictions relative to that basis.\n\n'2'\ndisables hyphenation of the last word on a page,(5) (*note\nManipulating Hyphenation-Footnote-5::) even for explicitly\nhyphenated words.\n\n'4'\ndisables hyphenation before the last two characters of a word.\n\n'8'\ndisables hyphenation after the first two characters of a word.\n\n'16'\nenables hyphenation before the last character of a word.\n\n'32'\nenables hyphenation after the first character of a word.\n\nApart from value 2, restrictions imposed by the hyphenation mode\nare not respected for words whose hyphenations have been\nspecified with the hyphenation character ('\\%' by default) or the\n'hw' request.\n\nNonzero values in the previous table are additive. For example,\nmode 12 causes GNU 'troff' to hyphenate neither the last two nor\nthe first two characters of a word. Some values cannot be used\ntogether because they contradict; for instance, values 4 and 16,\nand values 8 and 32. As noted, it is superfluous to add 1 to any\nnon-zero even mode.\n\nThe automatic placement of hyphens in words is determined by\n\"pattern files\", which are derived from TeX and available for\nseveral languages. The number of characters at the beginning of a\nword after which the first hyphenation point should be inserted is\ndetermined by the patterns themselves; it can't be reduced further\nwithout introducing additional, invalid hyphenation points\n(unfortunately, this information is not part of a pattern file--you\nhave to know it in advance). The same is true for the number of\ncharacters at the end of a word before the last hyphenation point\nshould be inserted. For example, you can supply the following\ninput to 'echo $(nroff)'.\n\n.ll 1\n.hy 48\nsplitting\n\nYou will get\n\ns- plit- t- in- g\n\ninstead of the correct 'split- ting'. English patterns as\ndistributed with GNU 'troff' need two characters at the beginning\nand three characters at the end; this means that value 4 of 'hy' is\nmandatory. Value 8 is possible as an additional restriction, but\nvalues 16 and 32 should be avoided, as should mode 1. Modes 4\nand 6 are typical.\n\nA table of left and right minimum character counts for hyphenation\nas needed by the patterns distributed with GNU 'troff' follows; see\nthe 'grofftmac(5)' man page for more information on GNU 'troff''s\nlanguage macro files.\n\nCzech cs 2 2\nEnglish en 2 3\nFrench fr 2 3\nGerman traditional det 2 2\nGerman reformed den 2 2\nItalian it 2 2\nSwedish sv 1 2\n\nHyphenation exceptions within pattern files (i.e., the words within\na TeX '\\hyphenation' group) obey the hyphenation restrictions given\nby 'hy'.\n\n-- Request: .nh\nDisable automatic hyphenation; i.e., set the hyphenation mode to 0\n(see above). The hyphenation mode of the last call to 'hy' is not\nremembered.\n\n-- Request: .hpf pattern-file\n-- Request: .hpfa pattern-file\n-- Request: .hpfcode a b [c d] ...\nRead hyphenation patterns from PATTERN-FILE, which is sought in the\nsame way that macro files are with the 'mso' request or the\n'-mNAME' command-line option to 'groff'. The PATTERN-FILE should\nhave the same format as (simple) TeX pattern files. More\nspecifically, the following scanning rules are implemented.\n\n* A percent sign starts a comment (up to the end of the line)\neven if preceded by a backslash.\n\n* \"Digraphs\" like '\\$' are not supported.\n\n* '^^XX' (where each X is 0-9 or a-f) and '^^C' (character C in\nthe code point range 0-127 decimal) are recognized; other uses\nof '^' cause an error.\n\n* No macro expansion is performed.\n\n* 'hpf' checks for the expression '\\patterns{...}' (possibly\nwith whitespace before or after the braces). Everything\nbetween the braces is taken as hyphenation patterns.\nConsequently, '{' and '}' are not allowed in patterns.\n\n* Similarly, '\\hyphenation{...}' gives a list of hyphenation\nexceptions.\n\n* '\\endinput' is recognized also.\n\n* For backward compatibility, if '\\patterns' is missing, the\nwhole file is treated as a list of hyphenation patterns\n(except that the '%' character is recognized as the start of a\ncomment).\n\nThe 'hpfa' request appends a file of patterns to the current list.\n\nThe 'hpfcode' request defines mapping values for character codes in\npattern files. It is an older mechanism no longer used by GNU\n'troff''s own macro files; for its successor, see 'hcode' below.\n'hpf' or 'hpfa' apply the mapping after reading the patterns but\nbefore replacing or appending to the active list of patterns. Its\narguments are pairs of character codes--integers from 0 to 255.\nThe request maps character code A to code B, code C to code D, and\nso on. Character codes that would otherwise be invalid in GNU\n'troff' can be used. By default, every code maps to itself except\nthose for letters 'A' to 'Z', which map to those for 'a' to 'z'.\n\nThe set of hyphenation patterns is associated with the language set\nby the 'hla' request (see below). The 'hpf' request is usually\ninvoked by a localization file loaded by the 'troffrc' file.(6)\n(*note Manipulating Hyphenation-Footnote-6::)\n\nA second call to 'hpf' (for the same language) replaces the\nhyphenation patterns with the new ones. Invoking 'hpf' or 'hpfa'\ncauses an error if there is no hyphenation language. If no 'hpf'\nrequest is specified (either in the document, in a file loaded at\nstartup, or in a macro package), GNU 'troff' won't automatically\nhyphenate at all.\n\n-- Request: .hcode c1 code1 [c2 code2] ...\nSet the hyphenation code of character C1 to CODE1, that of C2 to\nCODE2, and so on. A hyphenation code must be an ordinary character\n(not a special character escape sequence) other than a digit or a\nspace. The request is ignored if given no arguments.\n\nFor hyphenation to work, hyphenation codes must be set up. At\nstartup, GNU 'troff' assigns hyphenation codes to the letters\n'a'-'z' (mapped to themselves), to the letters 'A'-'Z' (mapped to\n'a'-'z'), and zero to all other characters. Normally, hyphenation\npatterns contain only lowercase letters which should be applied\nregardless of case. In other words, they assume that the words\n'FOO' and 'Foo' should be hyphenated exactly as 'foo' is. The\n'hcode' request extends this principle to letters outside the\nUnicode basic Latin alphabet; without it, words containing such\nletters won't be hyphenated properly even if the corresponding\nhyphenation patterns contain them.\n\nFor example, the following 'hcode' requests are necessary to assign\nhyphenation codes to the letters 'A\"a\"O\"o\"U\"u\"ss', needed for German.\n\n.hcode a\" a\" A\" a\"\n.hcode o\" o\" O\" o\"\n.hcode u\" u\" U\" u\"\n.hcode ss ss\n\nWithout these assignments, GNU 'troff' treats the German word\n'Kinderga\"rten' (the plural form of 'kindergarten') as two words\n'kinderg' and 'rten' because the hyphenation code of the umlaut a\nis zero by default, just like a space. There is a German\nhyphenation pattern that covers 'kinder', so GNU 'troff' finds the\nhyphenation 'kin-der'. The other two hyphenation points\n('kin-der-ga\"r-ten') are missed.\n\n-- Request: .hla lang\n-- Register: \\n[.hla]\nSet the hyphenation language to LANG. Hyphenation exceptions\nspecified with the 'hw' request and hyphenation patterns and\nexceptions specified with the 'hpf' and 'hpfa' requests are\nassociated with the hyphenation language. The 'hla' request is\nusually invoked by a localization file, which is turn loaded by the\n'troffrc' or 'troffrc-end' file; see the 'hpf' request above.\n\nThe hyphenation language is available in the read-only\nstring-valued register '.hla'; it is associated with the\nenvironment (*note Environments::).\n\n-- Request: .hlm [n]\n-- Register: \\n[.hlm]\n-- Register: \\n[.hlc]\nSet the maximum quantity of consecutive hyphenated lines to N. If\nN is negative, there is no maximum. If omitted, N is -1. This\nvalue is associated with the environment (*note Environments::).\nOnly lines output from a given environment count toward the maximum\nassociated with that environment. Hyphens resulting from '\\%' are\ncounted; explicit hyphens are not.\n\nThe '.hlm' read-only register stores this maximum. The count of\nimmediately preceding consecutive hyphenated lines is available in\nthe read-only register '.hlc'.\n\n-- Request: .hym [length]\n-- Register: \\n[.hym]\nSet the (right) hyphenation margin to LENGTH. If the adjustment\nmode is not 'b' or 'n', the line is not hyphenated if it is shorter\nthan LENGTH. Without an argument, the hyphenation margin is reset\nto its default value, 0. The default scaling unit is 'm'. The\nhyphenation margin is associated with the environment (*note\nEnvironments::).\n\nA negative argument resets the hyphenation margin to zero, emitting\na warning in category 'range'.\n\nThe hyphenation margin is available in the '.hym' read-only\nregister.\n\n-- Request: .hys [hyphenation-space]\n-- Register: \\n[.hys]\nSuppress hyphenation of the line in adjustment modes 'b' or 'n' if\nit can be justified by adding no more than HYPHENATION-SPACE extra\nspace to each inter-word space. Without an argument, the\nhyphenation space adjustment threshold is set to its default value,\n0. The default scaling unit is 'm'. The hyphenation space\nadjustment threshold is associated with the environment (*note\nEnvironments::).\n\nA negative argument resets the hyphenation space adjustment\nthreshold to zero, emitting a warning in category 'range'.\n\nThe hyphenation space adjustment threshold is available in the\n'.hys' read-only register.\n", "subsections": [] }, "File: groff.info, Node: Manipulating Spacing, Next: Tabs and Fields, Prev: Manipulating Hyphenation, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.11 Manipulating Spacing", "content": "A break causes the formatter to update the vertical drawing position at\nwhich the new text baseline is aligned. You can alter this location.\n\n-- Request: .sp [distance]\nBreak and move the next text baseline down by DISTANCE, or until\nspringing a page location trap.(1) (*note Manipulating\nSpacing-Footnote-1::) If invoked with the no-break control\ncharacter, 'sp' moves the pending output line's text baseline by\nDISTANCE. A negative DISTANCE will not reduce the position of the\ntext baseline below zero. Inside a diversion, any DISTANCE\nargument is ignored. The default scaling unit is 'v'. If DISTANCE\nis not specified, '1v' is assumed.\n\n.pl 5v \\\" Set page length to 5 vees.\n.de xx\n\\-\\-\\-\n. br\n..\n.wh 0 xx \\\" Set a trap at the top of the page.\nfoo on page \\n%\n.sp 2v\nbar on page \\n%\n.sp 50v \\\" This will cause a page break.\nbaz on page \\n%\n.pl \\n(nlu \\\" Truncate page to current position.\n=> ---\n=> foo on page 1\n=>\n=>\n=> bar on page 1\n=> ---\n=> baz on page 2\n\nYou might use the following macros to set the baseline of the next\noutput text at a given distance from the top or the bottom of the\npage. We subtract one line height ('\\n[.v]') because the '|'\noperator moves to one vee below the page top (recall *note Numeric\nExpressions::).\n\n.de y-from-top-down\n. sp |\\\\$1-\\\\n[.v]u\n..\n.\n.de y-from-bot-up\n. sp |\\\\n[.p]u-\\\\$1-\\\\n[.v]u\n..\n\nA call to '.y-from-bot-up 10c' means that the next text baseline\nwill be 10 cm from the bottom edge of the paper.\n\n-- Request: .ls [count]\n-- Register: \\n[.L]\nSet the line spacing; add COUNT-1 blank lines after each line of\ntext. With no argument, GNU 'troff' uses the previous value before\nthe last 'ls' call. The default is '1'.\n\nThe read-only register '.L' contains the current line spacing; it\nis associated with the environment (*note Environments::).\n\nThe 'ls' request is a coarse mechanism. *Note Changing the Type\nSize::, for the requests 'vs' and 'pvs' as alternatives to 'ls'.\n\n-- Escape sequence: \\x'spacing'\n-- Register: \\n[.a]\nSometimes, an output line requires additional vertical spacing, for\ninstance to allow room for a tall construct like an inline equation\nwith exponents or subscripts (particularly if they are iterated).\nThe '\\x' escape sequence takes a delimited measurement (like\n'\\x'3p'') to increase the vertical spacing of the pending output\nline. The default scaling unit is 'v'. If the measurement is\npositive, extra vertical space is inserted below the current line;\na negative measurement adds space above. If '\\x' is applied to the\npending output line multiple times, the maxima of the positive and\nnegative adjustments are separately applied. The delimiter need\nnot be a neutral apostrophe; see *note Delimiters::.\n\nThe '.a' read-only register contains the extra vertical spacing\nafter the text baseline of the most recently emitted output line.\n(In other words, it is the largest positive argument to '\\x'\nencountered on that line.) This quantity is exposed via a register\nbecause if an output line requires this \"extra post-vertical line\nspacing\", and the subsequent output line requires \"extra\npre-vertical line spacing\" (a negative argument to '\\x'), then\napplying both can lead to excessive spacing between the output\nlines. Text that is piling high on line N might not require (as\nmuch) extra pre-vertical line spacing if line N-1 carries extra\npost-vertical line spacing.\n\nUse of '\\x' can be necessary in combination with the\nbracket-building escape sequence '\\b',(2) (*note Manipulating\nSpacing-Footnote-2::) as the following example shows.\n\n.nf\nThis is a test of \\[rs]b (1).\nThis is a test of \\[rs]b (2).\nThis is a test of \\b'xyz'\\x'-1m'\\x'1m' (3).\nThis is a test of \\[rs]b (4).\nThis is a test of \\[rs]b (5).\n=> This is a test of \\b (1).\n=> This is a test of \\b (2).\n=> x\n=> This is a test of y (3).\n=> z\n=> This is a test of \\b (4).\n=> This is a test of \\b (5).\n\nWithout '\\x', the backslashes on the lines marked '(2)' and '(4)' would\nbe overprinted.\n\n-- Request: .ns\n-- Request: .rs\n-- Register: \\n[.ns]\nEnable \"no-space mode\". Vertical spacing, whether by 'sp' requests\nor blank input lines, is disabled. The 'bp' request to advance to\nthe next page is also disabled, unless it is accompanied by a page\nnumber (*note Page Control::). No-space mode ends automatically\nwhen text(3) (*note Manipulating Spacing-Footnote-3::) is formatted\nfor output (4) (*note Manipulating Spacing-Footnote-4::) or the\n'rs' request is invoked, which ends no-space mode. The read-only\nregister '.ns' interpolates a Boolean value indicating the\nenablement of no-space mode.\n\nA paragraphing macro might ordinarily insert vertical space to\nseparate paragraphs. A section heading macro could invoke 'ns' to\nsuppress this spacing for the first paragraph in a section.\n" } ] }, "File: groff.info, Node: Tabs and Fields, Next: Character Translations, Prev: Manipulating Spacing, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.12 Tabs and Fields", "content": "A tab character (ISO code point 9, EBCDIC code point 5) causes a\nhorizontal movement to the next tab stop, if any.\n\n-- Escape sequence: \\t\nInterpolate a tab in copy mode; see *note Copy Mode::.\n\n-- Request: .ta [[n1 n2 ... nn ]T r1 r2 ... rn]\n-- Register: \\n[.tabs]\nChange tab stop positions. This request takes a series of tab\nspecifiers as arguments (optionally divided into two groups with\nthe letter 'T') that indicate where each tab stop is to be,\noverriding any previous settings. The default scaling unit is 'm'.\nInvoking 'ta' without an argument removes all tab stops. GNU\n'troff''s startup value is 'T 0.5i'.\n\nTab stops can be specified absolutely--as distances from the left\nmargin. The following example sets six tab stops, one every inch.\n\n.ta 1i 2i 3i 4i 5i 6i\n\nTab stops can also be specified using a leading '+', which means\nthat the specified tab stop is set relative to the previous tab\nstop. For example, the following is equivalent to the previous\nexample.\n\n.ta 1i +1i +1i +1i +1i +1i\n\nGNU 'troff' supports an extended syntax to specify repeating tab\nstops. These stops appear after a 'T' argument. Their values are\nalways taken as distances relative to the previous tab stop. This\nis the idiomatic way to specify tab stops at equal intervals in\n'groff'. The following is, yet again, the same as the previous\nexamples. It does more, in fact, since it defines an infinite\nnumber of tab stops at one-inch intervals.\n\n.ta T 1i\n\nNow we are ready to interpret the full syntax given above. The\n'ta' request sets tabs at positions N1, N2, ..., NN, then at NN+R1,\nNN+R2, ..., NN+RN, then at NN+RN+R1, NN+RN+R2, ..., NN+RN+RN, and\nso on.\n\nFor example, '4c +6c T 3c 5c 2c' is equivalent to '4c 10c 13c 18c\n20c 23c 28c 30c ...'.\n\nText written to a tab column (i.e., between two tab stops, or\nbetween a tab stop and an output line boundary) may be aligned to\nthe right or left, or centered in the column. This alignment is\ndetermined by appending 'R', 'L', or 'C' to the tab specifier. The\ndefault is 'L'.\n\n.ta 1i 2iC 3iR\n\nThe beginning of an output line is not a tab stop; the text that\nbegins an output line is placed according to the configured\nalignment and indentation; see *note Manipulating Filling and\nAdjustment:: and *note Line Layout::.\n\nA tab stop is converted into a non-breakable horizontal movement\nthat cannot be adjusted.\n\n.ll 2i\n.ds foo a\\tb\\tc\n.ta T 1i\n\\*[foo]\nerror-> warning: cannot break line\n=> a b c\n\nThe above creates a single output line that is a bit longer than\ntwo inches (we use a string to show exactly where the tab stops\nare). Now consider the following.\n\n.ll 2i\n.ds bar a\\tb c\\td\n.ta T 1i\n\\*[bar]\nerror-> warning: cannot adjust line\n=> a b\n=> c d\n\nGNU 'troff' first converts the line's tab stops into unbreakable\nhorizontal movements, then breaks after 'b'. This usually isn't\nwhat you want.\n\nSuperfluous tab characters--those that do not correspond to a tab\nstop--are ignored except for the first, which delimits the\ncharacters belonging to the last tab stop for right-alignment or\ncentering.\n\n.ds Z foo\\tbar\\tbaz\n.ds ZZ foo\\tbar\\tbazqux\n.ds ZZZ foo\\tbar\\tbaz\\tqux\n.ta 2i 4iR\n\\*[Z]\n.br\n\\*[ZZ]\n.br\n\\*[ZZZ]\n.br\n=> foo bar baz\n=> foo bar bazqux\n=> foo bar bazqux\n\nThe first line right-aligns \"baz\" within the second tab stop. The\nsecond line right-aligns \"bazqux\" within it. The third line\nright-aligns only \"baz\" because of the additional tab character,\nwhich marks the end of the text occupying the last tab stop\ndefined.\n\nTab stops are associated with the environment (*note\nEnvironments::).\n\nThe read-only register '.tabs' contains a string representation of\nthe current tab settings suitable for use as an argument to the\n'ta' request.(1) (*note Tabs and Fields-Footnote-1::)\n\n.ds tab-string \\n[.tabs]\n\\*[tab-string]\n=> T120u\n\n-- Request: .tc [c]\nSet the tab repetition character to the ordinary or special\ncharacter C; normally, no glyph is written when moving to a tab\nstop (and some output devices may output space characters to\nachieve this motion). A \"tab repetition character\" causes the\nformatter to write as many instances of C as are necessary to\noccupy the interval from the horizontal drawing position to the\nnext tab stop. With no argument, GNU 'troff' reverts to the\ndefault behavior. The tab repetition character is associated with\nthe environment (*note Environments::). Only a single character of\nC is recognized; any excess is ignored.\n\n-- Request: .linetabs n\n-- Register: \\n[.linetabs]\nIf N is missing or non-zero, activate \"line-tabs\"; deactivate it\notherwise (the default). Active line-tabs cause GNU 'troff' to\ncompute tab distances relative to the start of the output line\ninstead of the input line.\n\n.de Tabs\n. ds x a\\t\\c\n. ds y b\\t\\c\n. ds z c\n. ta 1i 3i\n\\\\*x\n\\\\*y\n\\\\*z\n..\n.Tabs\n.br\n.linetabs\n.Tabs\n=> a b c\n=> a b c\n\nLine-tabs activation is associated with the environment (*note\nEnvironments::). The read-only register '.linetabs' interpolates 1\nif line-tabs are active, and 0 otherwise.\n\n* Menu:\n\n* Leaders::\n* Fields::\n" } ] }, "File: groff.info, Node: Leaders, Next: Fields, Prev: Tabs and Fields, Up: Tabs and Fields": { "content": "", "subsections": [] }, "Sometimes it is desirable to fill a tab stop with a given glyph, but": { "content": "also use tab stops normally on the same output line. An example is a\ntable of contents entry that uses dots to bridge the entry name with its\npage number, which is itself aligned between tab stops. The 'roff'\nlanguage provides \"leaders\" for this purpose.(1) (*note", "subsections": [] }, "Leaders-Footnote-1::)": { "content": "A leader character (ISO and EBCDIC code point 1, also known as SOH or\n\"start of heading\"), behaves similarly to a tab character: it moves to\nthe next tab stop. The difference is that for this movement, the\ndefault fill character is a period '.'.\n\n-- Escape sequence: \\a\nInterpolate a leader in copy mode; see *note Copy Mode::.\n\n-- Request: .lc [c]\nSet the leader repetition character to the ordinary or special\ncharacter C. Recall *note Tabs and Leaders::: when encountering a\nleader character in the input, the formatter writes as many dots\n'.' as are necessary until reaching the next tab stop; this is the\n\"leader definition character\". Omitting C unsets the leader\ncharacter. With no argument, GNU 'troff' treats leaders the same\nas tabs. The leader repetition character is associated with the\nenvironment (*note Environments::). Only a single C is recognized;\nany excess is ignored.\n\nA table of contents, for example, may define tab stops after a\nsection number, a title, and a gap to be filled with leader dots. The\npage number follows the leader, after a right-aligned final tab stop\nwide enough to house the largest page number occurring in the document.\n\n.ds entry1 19.\\tThe Prophet\\a\\t98\n.ds entry2 20.\\tAll Astir\\a\\t101\n.ta .5i 4.5i +.5iR\n.nf\n\\*[entry1]\n\\*[entry2]\n=> 19. The Prophet............................. 98\n=> 20. All Astir............................... 101\n", "subsections": [] }, "File: groff.info, Node: Fields, Prev: Leaders, Up: Tabs and Fields": { "content": "\"Fields\" are a more general way of laying out tabular data. A field is\ndefined as the data between a pair of \"delimiting characters\". It\ncontains substrings that are separated by \"padding characters\". The\nwidth of a field is the distance on the input line from the position\nwhere the field starts to the next tab stop. A padding character\ninserts an adjustable space similar to TeX's '\\hss' command (thus it can\neven be negative) to make the sum of all substring lengths plus the\nadjustable space equal to the field width. If more than one padding\ncharacter is inserted, the available space is evenly distributed among\nthem.\n\n-- Request: .fc [delim-char [padding-char]]\nDefine a delimiting and a padding character for fields. If the\nlatter is missing, the padding character defaults to a space\ncharacter. If there is no argument at all, the field mechanism is\ndisabled (which is the default). In contrast to, e.g., the tab\nrepetition character, delimiting and padding characters are not\nassociated with the environment (*note Environments::).\n\n.fc # ^\n.ta T 3i\n#foo^bar^smurf#\n.br\n#foo^^bar^smurf#\n=> foo bar smurf\n=> foo bar smurf\n", "subsections": [] }, "File: groff.info, Node: Character Translations, Next: troff and nroff Modes, Prev: Tabs and Fields, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.13 Character Translations", "content": "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": { "content": "assigned the metric information of the mapped output character right\nbefore input tokens are converted to nodes (*note Gtroff Internals::,\nfor more on this process).\n\n-- Request: .tr abcd...\n-- Request: .trin abcd...\nTranslate character A to glyph B, character C to glyph D, and so\non. If there is an odd number of characters in the argument, the\nlast one is translated to a fixed-width space (the same one\nobtained by the '\\' escape sequence).\n\nThe 'trin' request is identical to 'tr', but when you unformat a\ndiversion with 'asciify' it ignores the translation. *Note\nDiversions::, for details about the 'asciify' request.\n\nSome notes:\n\n* Special characters ('\\(XX', '\\[XXX]', '\\C'XXX'', '\\'', '\\`',\n'\\-', '\\'), glyphs defined with the 'char' request, and\nnumbered glyphs ('\\N'XXX'') can be translated also.\n\n* The '\\e' escape can be translated also.\n\n* Characters can be mapped onto the '\\%' and '\\~' escape\nsequences (but '\\%' and '\\~' can't be mapped onto another\nglyph).\n\n* The following characters can't be translated: space (with one\nexception, see below), backspace, newline, leader (and '\\a'),\ntab (and '\\t').\n\n* Translations are not considered for finding the soft hyphen\ncharacter set with the 'shc' request.\n\n* The pair 'C\\&' (an arbitrary character C followed by the dummy\ncharacter) maps this character to \"nothing\".\n\n.tr a\\&\nfoo bar\n=> foo br\n\nEven the space character can be mapped to the dummy character.\n\n.tr aa \\&\nfoo bar\n=> foobar\n\nAs shown in the example, the space character can't be the\nfirst character/glyph pair as an argument of 'tr'.\nAdditionally, it is not possible to map the space character to\nany other glyph; requests like '.tr aa x' undo '.tr aa \\&'\ninstead.\n\nIf justification is active, lines are justified in spite of\nthe 'empty' space character (but there is no minimal distance,\ni.e., the space character, between words).\n\n* After an output glyph has been constructed (this happens at\nthe moment immediately before the glyph is appended to an\noutput glyph list, either by direct output, in a macro,\ndiversion, or string), it is no longer affected by 'tr'.\n\n* Translating character to glyphs where one of them or both are\nundefined is possible also; 'tr' does not check whether the\nelements of its argument exist.\n\n*Note Gtroff Internals::.\n\n* Without an argument, the 'tr' request is ignored.\n\n-- Request: .trnt abcd...\n'trnt' is the same as the 'tr' request except that the translations\ndo not apply to text that is transparently throughput into a\ndiversion with '\\!'. *Note Diversions::.\n\nFor example,\n\n.tr ab\n.di x\n\\!.tm a\n.di\n.x\n\nprints 'b' to the standard error stream; if 'trnt' is used instead\nof 'tr' it prints 'a'.\n", "subsections": [] }, "File: groff.info, Node: troff and nroff Modes, Next: Line Layout, Prev: Character Translations, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.14 'troff' and 'nroff' Modes", "content": "" } ] }, "Historically, 'nroff' and 'troff' were two separate programs; the former": { "content": "for terminal output, the latter for typesetters. GNU 'troff' merges\nboth functions into one executable(1) (*note troff and nroff", "subsections": [] }, "Modes-Footnote-1::) that sends its output to a device driver ('grotty'": { "content": "for terminal devices, 'grops' for PostScript, and so on) which\ninterprets this intermediate output format. When discussing AT&T\n'troff', it makes sense to talk about \"'nroff' mode\" and \"'troff' mode\"\nsince the differences are hard-coded. GNU 'troff' takes information\nfrom device and font description files without handling requests\nspecially if a terminal output device is used, so such a strong\ndistinction is unnecessary.\n\nUsually, a macro package can be used with all output devices.", "subsections": [] }, "Nevertheless, it is sometimes necessary to make a distinction between": { "content": "terminal and non-terminal devices: GNU 'troff' provides two built-in\nconditions 'n' and 't' for the 'if', 'ie', and 'while' requests to\ndecide whether GNU 'troff' shall behave like 'nroff' or like 'troff'.\n\n-- Request: .troff\nMake the 't' built-in condition true (and the 'n' built-in\ncondition false) for 'if', 'ie', and 'while' conditional requests.\nThis is the default if GNU 'troff' (not 'groff') is started with\nthe '-R' switch to avoid loading of the startup files 'troffrc' and\n'troffrc-end'. Without '-R', GNU 'troff' stays in 'troff' mode if\nthe output device is not a terminal (e.g., 'ps').\n\n-- Request: .nroff\nMake the 'n' built-in condition true (and the 't' built-in\ncondition false) for 'if', 'ie', and 'while' conditional requests.\nThis is the default if GNU 'troff' uses a terminal output device;\nthe code for switching to 'nroff' mode is in the file 'tty.tmac',\nwhich is loaded by the startup file 'troffrc'.\n\n*Note Conditionals and Loops::, for more details on built-in\nconditions.\n", "subsections": [] }, "File: groff.info, Node: Line Layout, Next: Line Continuation, Prev: troff and nroff Modes, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.15 Line Layout", "content": "" } ] }, "The following drawing shows the dimensions that 'gtroff' uses for": { "content": "placing a line of output onto the page. They are labeled with the\nrequest that manipulates each dimension.\n\n-->| in |<--\n|<-----------ll------------>|\n+----+----+----------------------+----+\n| : : : |\n+----+----+----------------------+----+\n-->| po |<--\n|<--------paper width---------------->|\n\nThese dimensions are:\n\n'po'\n\"Page offset\"--this is the leftmost position of text on the final\noutput, defining the \"left margin\".\n\n'in'\n\"Indentation\"--this is the distance from the left margin where text\nis printed.\n\n'll'\n\"Line length\"--this is the distance from the left margin to right\nmargin.\n\nThe right margin is not explicitly configured; the combination of\npage offset and line length provides the information necessary to derive\nit.\n\nA simple demonstration:\n\n.ll 3i\nThis is text without indentation.\nThe line length has been set to 3\\~inches.\n.in +.5i\n.ll -.5i\nNow the left and right margins are both increased.\n.in\n.ll\nCalling .in and .ll without parameters restores\nthe previous values.\n\n=> This is text without indenta-\n=> tion. The line length has\n=> been set to 3 inches.\n=> Now the left and\n=> right margins are\n=> both increased.\n=> Calling .in and .ll without\n=> parameters restores the previ-\n=> ous values.\n\n-- Request: .po [offset]\n-- Request: .po +offset\n-- Request: .po -offset\n-- Register: \\n[.o]\nSet page offset to OFFSET (or increment or decrement its current\nvalue by OFFSET). If invoked without an argument, the page offset\nis restored to the value before the previous 'po' request. This\nrequest does not cause a break; the page offset in effect when an\noutput line is broken prevails (*note Manipulating Filling and\nAdjustment::). The initial value is 1i and the default scaling\nunit is 'm'. On terminal devices, the page offset is set to zero\nby a driver-specific macro file, 'tty.tmac'. The current page\noffset can be found in the read-only register '.o'. This request\nis incorrectly documented in the AT&T 'troff' manual as using a\ndefault scaling unit of 'v'.\n\n.po 3i\n\\n[.o]\n=> 720\n.po -1i\n\\n[.o]\n=> 480\n.po\n\\n[.o]\n=> 720\n\n-- Request: .in [indent]\n-- Request: .in +indent\n-- Request: .in -indent\n-- Register: \\n[.i]\nSet indentation to INDENT (or increment or decrement the current\nvalue by INDENT). This request causes a break. Initially, there\nis no indentation.\n\nIf 'in' is called without an argument, the indentation is reset to\nthe previous value before the last call to 'in'. The default\nscaling unit is 'm'.\n\nIf a negative indentation value is specified (which is not\nallowed), 'gtroff' emits a warning in category 'range' and sets the\nindentation to zero.\n\nThe effect of 'in' is delayed until a partially collected line (if\nit exists) is output. A temporary indentation value is reset to\nzero also.\n\nThe current indentation (as set by 'in') can be found in the\nread-only register '.i'. The indentation is associated with the\nenvironment (*note Environments::).\n\n-- Request: .ti offset\n-- Request: .ti +offset\n-- Request: .ti -offset\n-- Register: \\n[.in]\nTemporarily indent the next output line by OFFSET. If an increment\nor decrement value is specified, adjust the temporary indentation\nrelative to the value set by the 'in' request.\n\nThis request causes a break; its value is associated with the\nenvironment (*note Environments::). The default scaling unit is\n'm'. A call of 'ti' without an argument is ignored.\n\nIf the total indentation value is negative (which is not allowed),\n'gtroff' emits a warning in category 'range' and sets the temporary\nindentation to zero. 'Total indentation' is either OFFSET if\nspecified as an absolute value, or the temporary plus normal\nindentation, if OFFSET is given as a relative value.\n\nThe effect of 'ti' is delayed until a partially collected line (if\nit exists) is output.\n\nThe read-only register '.in' is the indentation that applies to the\ncurrent output line.\n\nThe difference between '.i' and '.in' is that the latter takes into\naccount whether a partially collected line still uses the old\nindentation value or a temporary indentation value is active.\n\n-- Request: .ll [length]\n-- Request: .ll +length\n-- Request: .ll -length\n-- Register: \\n[.l]\n-- Register: \\n[.ll]\nSet the line length to LENGTH (or increment or decrement the\ncurrent value by LENGTH). Initially, the line length is set to\n6.5i. The effect of 'll' is delayed until a partially collected\nline (if it exists) is output. The default scaling unit is 'm'.\n\nIf 'll' is called without an argument, the line length is reset to\nthe previous value before the last call to 'll'. If a negative\nline length is specified (which is not allowed), 'gtroff' emits a\nwarning in category 'range' and sets the line length to zero. The\nline length is associated with the environment (*note\nEnvironments::).\n\nThe current line length (as set by 'll') can be found in the\nread-only register '.l'. The read-only register '.ll' is the line\nlength that applies to the current output line.\n\nSimilar to '.i' and '.in', the difference between '.l' and '.ll' is\nthat the latter takes into account whether a partially collected\nline still uses the old line length value.\n", "subsections": [] }, "File: groff.info, Node: Line Continuation, Next: Page Layout, Prev: Line Layout, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.16 Line Continuation", "content": "" } ] }, "When filling is enabled, input and output line breaks generally do not": { "content": "correspond. The 'roff' language therefore distinguishes input and\noutput line continuation.\n\n-- Escape sequence: \\\n'\\' (a backslash immediately followed by a newline) suppresses\nthe effects of that newline in the input. The next input line thus\nretains the classification of its predecessor as a control or text\nline. '\\' is useful for managing line lengths in the input\nduring document maintenance; you can break an input line in the\nmiddle of a request invocation, macro call, or escape sequence.\nInput line continuation is invisible to the formatter, with two\nexceptions: the '|' operator recognizes the new input line (*note\nNumeric Expressions::), and the input line counter register '.c' is\nincremented.\n\n.ll 50n\n.de I\n. ft I\n. nop \\\\$*\n. ft\n..\nOur film class watched\n.I The Effect of Gamma Rays on Man-in-the-Moon\nMarigolds. \\\" whoops, the input line wrapped\n.br\n.I My own opus begins on line \\n[.c] \\\nand ends on line \\n[.c].\n=> Our film class watched The Effect of Gamma Rays on\n=> Man-in-the-Moon Marigolds.\n=> My own opus begins on line 11 and ends on line 12.\n\n-- Escape sequence: \\c\n-- Register: \\n[.int]\n'\\c' continues an output line. Nothing after it on the input line\nis formatted. In contrast to '\\', a line after '\\c' remains a\nnew input line, so a control character is recognized at its\nbeginning. The visual results depend on whether filling is\nenabled; see *note Manipulating Filling and Adjustment::.\n\n* If filling is enabled, a word interrupted with '\\c' is\ncontinued with the text on the next input text line, without\nan intervening space.\n\nThis is a te\\c\nst.\n=> This is a test.\n\n* If filling is disabled, the next input text line after '\\c' is\nhandled as a continuation of the same input text line.\n\n.nf\nThis is a \\c\ntest.\n=> This is a test.\n\nAn intervening control line that causes a break overrides '\\c',\nflushing out the pending output line in the usual way.\n\nThe '.int' register contains a positive value if the last output\nline was continued with '\\c'; this datum is associated with the\nenvironment (*note Environments::).(1) (*note Line\nContinuation-Footnote-1::)\n", "subsections": [] }, "File: groff.info, Node: Page Layout, Next: Page Control, Prev: Line Continuation, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.17 Page Layout", "content": "The formatter permits configuration of the page length and page number.\n\n-- Request: .pl [length]\n-- Request: .pl +length\n-- Request: .pl -length\n-- Register: \\n[.p]\nChange (increase or decrease) the page length per the numeric\nexpression LENGTH. The default scaling unit is 'v'. A negative\nLENGTH is valid, but an uncommon application: it prevents page\nlocation traps from being sprung,(1) (*note Page\nLayout-Footnote-1::) and each output line is placed on a new page.\nIf LENGTH is invalid, GNU 'troff' emits a warning in category\n'number'. If LENGTH is absent or invalid, '11i' is assumed.\n\nThe read-only register '.p' interpolates the current page length.\n\n-- Request: .pn num\n-- Request: .pn +num\n-- Request: .pn -num\n-- Register: \\n[.pn]\nChange (increase or decrease) the page number of the next page\nper the numeric expression NUM. If NUM is invalid, GNU 'troff'\nemits a warning in category 'number' and ignores the request.\nWithout an argument, 'pn' is ignored.\n\nThe read-only register '.pn' interpolates NUM if set by 'pn' on the\ncurrent page, or the current page number plus 1.\n\nThe formatter offers special support for typesetting headers and\nfooters, collectively termed \"titles\". Titles have an independent line\nlength, and their placement on the page is not restricted.\n\n-- Request: .tl 'left'center'right'\nFormat an output line as a title consisting of LEFT, CENTER, and\nRIGHT, each aligned accordingly. The delimiter need not be a\nneutral apostrophe: 'tl' accepts the same delimiters as most escape\nsequences; see *note Delimiters::. If not used as the delimiter,\nany \"page number character\" character is replaced with the current\npage number; the default is '%'; see the the 'pc' request below.\nWithout an argument, 'tl' is ignored. 'tl' writes the title line\nimmediately, ignoring any partially collected line.\n\nIt is not an error to omit delimiters after the first. For\nexample, '.tl /Thesis' is interpreted as '.tl /Thesis///': it sets\na title line comprising only the left-aligned word 'Thesis'.\n\n-- Request: .lt [length]\n-- Request: .lt +length\n-- Request: .lt -length\n-- Register: \\n[.lt]\nChange (increase or decrease) the line length used by titles per\nthe numeric expression LENGTH. The default scaling unit is 'm'.\nIf LENGTH is negative, GNU emits a warning in category 'range' and\ntreats LENGTH as '0'. If LENGTH is invalid, GNU 'troff' emits a\nwarning in category 'number' and ignores the request. The\nformatter's default title length is '6.5i'. With no argument, the\ntitle length is restored to the previous value. The title length\nis is associated with the environment (*note Environments::).\n\nThe read-only register '.lt' interpolates the title line length.\n\n-- Request: .pc [char]\nSet the page number character to CHAR. With no argument, the page\nnumber character is disabled. 'pc' does not affect the\nregister '%'.\n\nThe following example exercises title features.\n\n.lt 50n\nThis is my partially collected\n.tl 'Isomers 2023'%'Dextrose Edition'\nline.\n=> Isomers 2023 1 Dextrose Edition\n=> This is my partially collected line.\n\nWe most often see titles used in page header and footer traps. *Note\nTraps::.\n" } ] }, "File: groff.info, Node: Page Control, Next: Using Fonts, Prev: Page Layout, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.18 Page Control", "content": "" } ] }, "Discretionary page breaks can prevent the unwanted separation of": { "content": "content. A new page number takes effect during page ejection; see *note\nThe Implicit Page Trap::.\n\n-- Request: .bp [page-number]\n-- Request: .bp +page-number\n-- Request: .bp -page-number\n-- Register: \\n[%]\nBreak the page and change (increase or decrease) the next page\nnumber per the numeric expression PAGE-NUMBER. If PAGE-NUMBER is\ninvalid, GNU 'troff' emits a warning in category 'number' and\nignores the argument. This request causes a break. A page break\nadvances the vertical drawing position to the bottom of the page,\nspringing traps. *Note Page Location Traps::. 'bp' has effect\nonly if invoked within the top-level diversion.(1) (*note Page\nControl-Footnote-1::) This request is incorrectly documented in the\nAT&T 'troff' manual as having a default scaling unit of 'v'.\n\nThe register '%' interpolates the current page number.\n\n.de BP\n' bp \\\" schedule page break once current line is output\n..\n\n-- Request: .ne [space]\nForce a page break if insufficient vertical space is available\n(assert \"needed\" space). 'ne' tests the distance to the next page\nlocation trap; see *note Page Location Traps::, and breaks the page\nif that amount is less than SPACE. The default scaling unit is\n'v'. If SPACE is invalid, GNU 'troff' emits a warning in category\n'number' and ignores the argument. If SPACE is not specified, '1v'\nis assumed.\n\nWe can require space for at least the first two output lines of a\nparagraph, preventing its first line from being widowed at the page\nbottom.\n\n.ne 2v\nConsidering how common illness is,\nhow tremendous the spiritual change that it brings,\nhow astonishing,\nwhen the lights of health go down,\nthe undiscovered countries that are then disclosed,\nwhat wastes and deserts of the soul a slight attack\nof influenza brings to view,\n\nThis method is reliable only if no output line is pending when 'ne'\nis invoked. When macro packages are used, this is often not the\ncase: their paragraphing macros perform the break. You may need to\nexperiment with placing the 'ne' after the paragraphing macro, or\n'br' and 'ne' before it.\n\n'ne' is also useful to force grouping of section headings with\ntheir subsequent paragraphs, or tables with their captions and/or\nexplanations. Macro packages often use 'ne' with diversions to\nimplement keeps and displays; see *note Diversions::. They may\nalso offer parameters for widow and orphan management.\n\n-- Request: .sv [space]\n-- Request: .os\nRequire vertical space as 'ne' does, but also save it for later\noutput by the 'os' request. If SPACE is available before the next\npage location trap, it is output immediately. Both requests ignore\na partially collected line, taking effect at the next break. 'sv'\nand 'os' ignore no-space mode (recall *note Manipulating\nSpacing::). While the 'sv' request allows negative values for\nSPACE, 'os' ignores them. The default scaling unit is 'v'. If\nSPACE is not specified, '1v' is assumed.\n\n-- Register: \\n[nl]\n'nl' interpolates or sets the vertical drawing position. When the\nformatter starts, the first page transition hasn't happened yet,\nand 'nl' is negative. If a header trap has been planted on the\npage (typically at vertical position '0'), you can assign a\nnegative value to 'nl' to spring it if that page has already\nstarted (*note Page Location Traps::).\n\n.de HD\n. sp\n. tl ''Goldbach Solution''\n. sp\n..\n.\nFirst page.\n.bp\n.wh 0 HD \\\" plant header trap at top of page\n.nr nl (-1)\nSecond page.\n=> First page.\n=>\n=> (blank lines elided)\n=>\n=> Goldbach Solution\n=>\n=> (blank lines elided)\n=>\n=> Second page.\n\nWithout resetting 'nl' to a negative value, the trap just planted\nwould be active beginning with the next page, not the current\none.\n\n*Note Diversions::, for a comparison of 'nl' with the '.h' and '.d'\nregisters.\n", "subsections": [] }, "File: groff.info, Node: Using Fonts, Next: Manipulating Type Size and Vertical Spacing, Prev: Page Control, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.19 Using Fonts", "content": "In digital typography, a \"font\" is a collection of characters in a\nspecific typeface that a device can render as glyphs at a desired\nsize.(1) (*note Using Fonts-Footnote-1::) A 'roff' formatter can change\ntypefaces at any point in the text. The basic faces are a set of\n\"styles\" combining upright and slanted shapes with normal and heavy\nstroke weights: 'R', 'I', 'B', and 'BI'--these stand for roman, italic,\nbold, and bold-italic. For linguistic text, GNU 'troff' groups\ntypefaces into \"families\" containing each of these styles.(2) (*note\nUsing Fonts-Footnote-2::) A \"text font\" is thus often a family combined\nwith a style, but it need not be: consider the 'ps' and 'pdf' devices'\n'ZCMI' (Zapf Chancery Medium italic)--often, no other style of Zapf" } ] }, "Chancery Medium is provided. On typesetting devices, at least one": { "content": "\"special font\" is available, comprising \"unstyled\" glyphs for\nmathematical operators and other purposes.\n\nLike AT&T 'troff', GNU 'troff' does not itself load or manipulate a\ndigital font file;(3) (*note Using Fonts-Footnote-3::) instead it works\nwith a \"font description file\" that characterizes it, including its\nglyph repertoire and the \"metrics\" (dimensions) of each glyph.(4)\n(*note Using Fonts-Footnote-4::) This information permits the formatter\nto accurately place glyphs with respect to each other. Before using a\nfont description, the formatter associates it with a \"mounting\nposition\", a place in an ordered list of available typefaces. So that a\ndocument need not be strongly coupled to a specific font family, in GNU\n'troff' an output device can associate a style in the abstract sense\nwith a mounting position. Thus the default family can be combined with\na style dynamically, producing a \"resolved font name\".\n\nFonts often have trademarked names, and even Free Software fonts can\nrequire renaming upon modification. 'groff' maintains a convention that\na device's serif font family is given the name 'T' (\"Times\"), its\nsans-serif family 'H' (\"Helvetica\"), and its monospaced family 'C'\n(\"Courier\"). Historical inertia has driven 'groff''s font identifiers\nto short uppercase abbreviations of font names, as with 'TR', 'TI',\n'TB', 'TBI', and a special font 'S'.\n\nThe default family used with abstract styles can be changed at any\ntime; initially, it is 'T'. Typically, abstract styles are arranged in\nthe first four mounting positions in the order shown above. The default\nmounting position, and therefore style, is always '1' ('R'). By issuing\nappropriate formatter instructions, you can override these defaults\nbefore your document writes its first glyph.\n\nTerminal output devices cannot change font families and lack special\nfonts. They support style changes by overstriking, or by altering\nISO 6429/ECMA-48 \"graphic renditions\" (character cell attributes).\n\n* Menu:\n\n* Selecting Fonts::\n* Font Families::\n* Font Positions::\n* Using Symbols::\n* Character Classes::\n* Special Fonts::\n* Artificial Fonts::\n* Ligatures and Kerning::\n* Italic Corrections::\n* Dummy Characters::\n", "subsections": [] }, "File: groff.info, Node: Selecting Fonts, Next: Font Families, Prev: Using Fonts, Up: Using Fonts": { "content": "We use \"font\" to refer to any of several means of identifying a font: by\nmounting position ('3'), by abstract style ('B'), or by its identifier\n('TB').\n\n-- Request: .ft [font]\n-- Escape sequence: \\ff\n-- Escape sequence: \\f(fn\n-- Escape sequence: \\f[font]\n-- Register: \\n[.fn]\nThe 'ft' request selects the typeface FONT. If the argument is\nabsent or 'P', it selects the previously chosen font. If FONT is a\nnon-negative integer, it is interpreted as mounting position; the\nfont mounted there is selected. If that position refers to an\nabstract style, it is combined with the default family (see 'fam'\nand '\\F' below) to make a resolved font name. If the mounting\nposition is not a style and no font is mounted there, GNU 'troff'\nemits a warning in category 'font' and ignores the request.\n\nIf FONT matches a style name, it is combined with the current\nfamily to make a resolved font name. Otherwise, FONT is assumed to\nalready be a resolved font name.\n\nThe resolved font name is subject to translation (see request 'ftr'\nbelow). Next, the (possibly translated) font name's mounting\nposition is looked up; if not mounted, FONT is sought on the file\nsystem as a font description file and, if located, automatically\nmounted at the next available position (see register '.fp' below).\nIf the font was mounted using an identifier different from its font\ndescription file name (see request 'fp' below), that file name is\nthen looked up. If a font description file for the resolved font\nname is not found, GNU 'troff' emits a warning in category 'font'\nand ignores the request.\n\nThe '\\f' escape sequence is similar, using one-character name (or\nmounting position) F, two-character name FN, or a name FONT of\narbitrary length. '\\f[]' selects the previous font. The syntax\nform '\\fP' is supported for backward compatibility, and '\\f[P]' for\nconsistency.\n\neggs, bacon,\n.ft I\nspam,\n.ft\nand sausage.\n.br\neggs, bacon, \\fIspam,\\fP and sausage.\n=> eggs, bacon, spam, and sausage\n=> eggs, bacon, spam, and sausage\n\nThe current and previously selected fonts are properties of the\nenvironment (*note Environments::).\n\nThe read-only string-valued register '.fn' contains the resolved\nfont name of the selected font.\n\n'\\f' doesn't produce an input token in GNU 'troff'; it thus can be\nused in requests that expect a single-character argument. We can\nassign a font to a margin character as follows (*note\nMiscellaneous::).\n\n.mc \\f[I]x\\f[]\n\n-- Request: .ftr f [g]\nTranslate font F to font G. Whenever a font named F is referred to\nin a '\\f' escape sequence, in the 'F' and 'S' conditional\noperators, or in the 'ft', 'ul', 'bd', 'cs', 'tkf', 'special',\n'fspecial', 'fp', or 'sty' requests, font G is used. If G is\nmissing or equal to F the translation is undone.\n\nFont translations cannot be chained.\n\n.ftr XXX TR\n.ftr XXX YYY\n.ft XXX\nerror-> warning: can't find font 'XXX'\n\n-- Request: .fzoom f [zoom]\n-- Register: \\n[.zoom]\nSet magnification of font F to factor ZOOM, which must be a\nnon-negative integer multiple of 1/1000th. This request is useful\nto adjust the optical size of a font in relation to the others. In\nthe example below, font 'CR' is magnified by 10% (the zoom factor\nis thus 1.1).\n\n.fam P\n.fzoom CR 1100\n.ps 12\nPalatino and \\f[CR]Courier\\f[]\n\nA missing or zero value of ZOOM is the same as a value of 1000,\nwhich means no magnification. F must be a resolved font name, not\nan abstract style.\n\nThe magnification of a font is completely transparent to GNU\n'troff'; a change of the zoom factor doesn't cause any effect\nexcept that the dimensions of glyphs, (word) spaces, kerns, etc.,\nof the affected font are adjusted accordingly.\n\nThe zoom factor of the current font is available in the read-only\nregister '.zoom', in multiples of 1/1000th. It returns zero if\nthere is no magnification.\n", "subsections": [] }, "File: groff.info, Node: Font Families, Next: Font Positions, Prev: Selecting Fonts, Up: Using Fonts": { "content": "", "subsections": [] }, "To accommodate the wide variety of fonts available, GNU 'troff'": { "content": "distinguishes \"font families\" and \"font styles\". A resolved font name\nis the catenation of a font family and a style. Selecting an abstract\nstyle causes GNU 'troff' to combine it with the default font family.\n\nYou can thus compose a document using abstract styles exclusively for\nits body or running text, selecting a specific family only for titles or\nexamples, for instance, and change the default family on the command\nline (recall *note Groff Options::).\n\nFonts for the devices 'ps', 'pdf', 'dvi', 'lj4', 'lbp', and the X11\ndevices support this mechanism. By default, GNU 'troff' uses the Times\nfamily with the four styles 'R', 'I', 'B', and 'BI'.\n\n-- Request: .fam [family]\n-- Register: \\n[.fam]\n-- Escape sequence: \\Ff\n-- Escape sequence: \\F(fm\n-- Escape sequence: \\F[family]\nSet the default font family, used in combination with abstract\nstyles to construct a resolved font name, to FAMILY (one-character\nname F, two-character name FM). If no argument is given, GNU\n'troff' selects the previous font family; if there none, is it\nfalls back to the device's default(1) (*note Font\nFamilies-Footnote-1::) or its own ('T').\n\nThe '\\F' escape sequence works similarly. In disanalogy to '\\f',\n'\\FP' makes 'P' the default family. Use '\\F[]' to select the\nprevious default family. The default font family is available in\nthe read-only string-valued register '.fam'; it is associated with\nthe environment (*note Environments::).\n\nspam, \\\" startup defaults are T (Times) R (roman)\n.fam H \\\" make Helvetica the default family\nspam, \\\" family H + style R = HR\n.ft B \\\" family H + style B = HB\nspam,\n.ft CR \\\" Courier roman (default family not changed)\nspam,\n.ft \\\" back to Helvetica bold\nspam,\n.fam T \\\" make Times the default family\nspam, \\\" family T + style B = TB\n.ft AR \\\" font AR (not a style)\nbaked beans,\n.ft R \\\" family T + style R = TR\nand spam.\n\n'\\F' doesn't produce an input token in GNU 'troff'. As a\nconsequence, it can be used in requests like 'mc' (which expects a\nsingle character as an argument) to change the font family on the\nfly.\n\n.mc \\F[P]x\\F[]\n\n-- Request: .sty n style\n-- Register: \\n[.sty]\nAssociate an abstract style STYLE with mounting position N, which\nmust be a non-negative integer. If the requests 'cs', 'bd', 'tkf',\n'uf', or 'fspecial' are applied to an abstract style, they are\ninstead applied to the member of the current family corresponding\nto that style.\n\nThe default family can be set with the '-f' option (*note Groff\nOptions::). The 'styles' command in the 'DESC' file controls which\nfont positions (if any) are initially associated with abstract\nstyles rather than fonts.\n\n*Caution:* The STYLE argument is not validated. Errors may occur\nlater, when the formatter attempts to construct a resolved font\nname, or format a character for output.\n\n.nr BarPos \\n[.fp]\n.sty \\n[.fp] Bar\n.fam Foo\n.ft \\n[BarPos]\n.tm .f=\\n[.f]\nA\nerror-> error: no font family named 'Foo' exists\nerror-> .f=41\nerror-> error: cannot format glyph: no current font\n\nWhen an abstract style has been selected, the read-only\nstring-valued register '.sty' interpolates its name; this datum is\nassociated with the environment (*note Environments::). Otherwise,\n'.sty' interpolates nothing.\n", "subsections": [] }, "File: groff.info, Node: Font Positions, Next: Using Symbols, Prev: Font Families, Up: Using Fonts": { "content": "", "subsections": [] }, "To support typeface indirection through abstract styles, and for": { "content": "compatibility with AT&T 'troff', the formatter maintains a list of font\n\"positions\" at which fonts required by a document are \"mounted\". An\noutput device's description file 'DESC' typically configures a set of\npre-mounted fonts; see *note Device and Font Description Files::. A\nfont need not be explicitly mounted before it is selected; GNU 'troff'\nwill search 'GROFFFONTPATH' for it by name and mount it at the first\nfree mounting position on demand.\n\n-- Request: .fp pos id [font-description-file-name]\n-- Register: \\n[.f]\n-- Register: \\n[.fp]\nMount a font under the name ID at mounting position POS, a\nnon-negative integer. When the formatter starts up, it reads the\noutput device's description to mount an initial set of faces, and\nselects font position 1. Position 0 is unused by default. Unless\nthe FONT-DESCRIPTION-FILE-NAME argument is given, ID should be the\nname of a font description file stored in a directory corresponding\nto the selected output device. GNU 'troff' does not traverse\ndirectories to locate the font description file.\n\nThe optional third argument enables font names to be aliased, which\ncan be necessary in compatibility mode since AT&T 'troff' syntax\naffords no means of identifying fonts with names longer than two\ncharacters, like 'TBI' or 'ZCMI', in a font selection escape\nsequence. *Note Compatibility Mode::. You can also alias fonts on\nmounting for convenience or abstraction. (See below regarding the\n'.fp' register.)\n\n.fp \\n[.fp] SC ZCMI\nSend a \\f(SChand-written\\fP thank-you note.\n.fp \\n[.fp] Emph TI\n.fp \\n[.fp] Strong TB\nAre \\f[Emph]these names\\f[] \\f[Strong]comfortable\\f[]?\n\n'DESC', 'P', and non-negative integers are not usable as font\nidentifiers.\n\nThe position of the currently selected font (or abstract style) is\navailable in the read-only register '.f'. It is associated with\nthe environment (*note Environments::).\n\nYou can copy the value of '.f' to another register to save it for\nlater use.\n\n.nr saved-font \\n[.f]\n... text involving many font changes ...\n.ft \\n[saved-font]\n\nThe index of the next (non-zero) free font position is available in\nthe read-only register '.fp'. Fonts not listed in the 'DESC' file\nare automatically mounted at position '\\n[.fp]' when selected with\nthe 'ft' request or '\\f' escape sequence. When mounting a font at\na position explicitly with the 'fp' request, this same practice\nshould be followed, although GNU 'troff' does not enforce this\nstrictly.\n", "subsections": [] }, "File: groff.info, Node: Using Symbols, Next: Character Classes, Prev: Font Positions, Up: Using Fonts": { "content": "A \"glyph\" is a graphical representation of a \"character\". While a\ncharacter is an abstraction of semantic information, a glyph is\nsomething that can be seen on screen or paper. A character has many\npossible representation forms (for example, the character 'A' can be\nwritten in an upright or slanted typeface, producing distinct glyphs).", "subsections": [] }, "Sometimes, a sequence of characters map to a single glyph: this is a": { "content": "\"ligature\"--the most common is 'fi'.\n\nSpace characters never become glyphs in GNU 'troff'. If not\ndiscarded (as when trailing on text lines), they are represented by\nhorizontal motions in the output.\n\nA \"symbol\" is simply a named glyph. Within 'gtroff', all glyph names\nof a particular font are defined in its font file. If the user requests\na glyph not available in this font, 'gtroff' looks up an ordered list of\n\"special fonts\". By default, the PostScript output device supports the\ntwo special fonts 'SS' (slanted symbols) and 'S' (symbols) (the former\nis looked up before the latter). Other output devices use different\nnames for special fonts. Fonts mounted with the 'fonts' keyword in the\n'DESC' file are globally available. To install additional special fonts\nlocally (i.e., for a particular font), use the 'fspecial' request.\n\nHere are the exact rules how 'gtroff' searches a given symbol:\n\n* If the symbol has been defined with the 'char' request, use it.\nThis hides a symbol with the same name in the current font.\n\n* Check the current font.\n\n* If the symbol has been defined with the 'fchar' request, use it.\n\n* Check whether the current font has a font-specific list of special\nfonts; test all fonts in the order of appearance in the last\n'fspecial' call if appropriate.\n\n* If the symbol has been defined with the 'fschar' request for the\ncurrent font, use it.\n\n* Check all fonts in the order of appearance in the last 'special'\ncall.\n\n* If the symbol has been defined with the 'schar' request, use it.\n\n* As a last resort, consult all fonts loaded up to now for special\nfonts and check them, starting with the lowest font number. This\ncan sometimes lead to surprising results since the 'fonts' line in\nthe 'DESC' file often contains empty positions, which are filled\nlater on. For example, consider the following:\n\nfonts 3 0 0 FOO\n\nThis mounts font 'foo' at font position 3. We assume that 'FOO' is\na special font, containing glyph 'foo', and that no font has been\nloaded yet. The line\n\n.fspecial BAR BAZ\n\nmakes font 'BAZ' special only if font 'BAR' is active. We further\nassume that 'BAZ' is really a special font, i.e., the font\ndescription file contains the 'special' keyword, and that it also\ncontains glyph 'foo' with a special shape fitting to font 'BAR'.\nAfter executing 'fspecial', font 'BAR' is loaded at font\nposition 1, and 'BAZ' at position 2.\n\nWe now switch to a new font 'XXX', trying to access glyph 'foo'\nthat is assumed to be missing. There are neither font-specific\nspecial fonts for 'XXX' nor any other fonts made special with the\n'special' request, so 'gtroff' starts the search for special fonts\nin the list of already mounted fonts, with increasing font\npositions. Consequently, it finds 'BAZ' before 'FOO' even for\n'XXX', which is not the intended behaviour.\n\n*Note Device and Font Description Files::, and *note Special Fonts::,\nfor more details.\n\nThe 'groffchar(7)' man page houses a complete list of predefined\nspecial character names, but the availability of any as a glyph is\ndevice- and font-dependent. For example, say\n\nman -Tdvi groffchar > groffchar.dvi\n\nto obtain those available with the DVI device and default font\nconfiguration.(1) (*note Using Symbols-Footnote-1::) If you want to use\nan additional macro package to change the fonts used, 'groff' (or\n'gtroff') must be run directly.\n\ngroff -Tdvi -mec -man groffchar.7 > groffchar.dvi\n\nSpecial character names not listed in 'groffchar(7)' are derived\nalgorithmically, using a simplified version of the Adobe Glyph List\n(AGL) algorithm, which is described in\n. The (frozen) set of\nnames that can't be derived algorithmically is called the \"'groff' glyph\nlist (GGL)\".\n\n* A glyph for Unicode character U+XXXX[X[X]], which is not a\ncomposite character is named 'uXXXX[X[X]]'. X must be an uppercase\nhexadecimal digit. Examples: 'u1234', 'u008E', 'u12DB8'. The\nlargest Unicode value is 0x10FFFF. There must be at least four 'X'\ndigits; if necessary, add leading zeroes (after the 'u'). No zero\npadding is allowed for character codes greater than 0xFFFF.\nSurrogates (i.e., Unicode values greater than 0xFFFF represented\nwith character codes from the surrogate area U+D800-U+DFFF) are not\nallowed either.\n\n* A glyph representing more than a single input character is named\n\n'u' COMPONENT1 '' COMPONENT2 '' COMPONENT3 ...\n\nExample: 'u004503020301'.\n\nFor simplicity, all Unicode characters that are composites must be\nmaximally decomposed to NFD;(2) (*note Using Symbols-Footnote-2::)\nfor example, 'u00CA0301' is not a valid glyph name since U+00CA\n(LATIN CAPITAL LETTER E WITH CIRCUMFLEX) can be further decomposed\ninto U+0045 (LATIN CAPITAL LETTER E) and U+0302 (COMBINING\nCIRCUMFLEX ACCENT). 'u004503020301' is thus the glyph name for\nU+1EBE, LATIN CAPITAL LETTER E WITH CIRCUMFLEX AND ACUTE.\n\n* groff maintains a table to decompose all algorithmically derived\nglyph names that are composites itself. For example, 'u0100'\n(LATIN LETTER A WITH MACRON) is automatically decomposed into\n'u00410304'. Additionally, a glyph name of the GGL is preferred\nto an algorithmically derived glyph name; 'groff' also\nautomatically does the mapping. Example: The glyph 'u00450302' is\nmapped to '^E'.\n\n* glyph names of the GGL can't be used in composite glyph names; for\nexample, '^Eu0301' is invalid.\n\n-- Escape sequence: \\(nm\n-- Escape sequence: \\[name]\n-- Escape sequence: \\[base-glyph combining-component ...]\nTypeset a special character NAME (two-character name NM) or a\ncomposite glyph consisting of BASE-GLYPH overlaid with one or more\nCOMBINING-COMPONENTs. For example, '\\[A ho]' is a capital letter\n\"A\" with a \"hook accent\" (ogonek).\n\nThere is no special syntax for one-character names--the analogous\nform '\\N' would collide with other escape sequences. However, the\nfour escape sequences '\\'', '\\-', '\\', and '\\`', are translated on\ninput to the special character escape sequences '\\[aa]', '\\[-]',\n'\\[ul]', and '\\[ga]', respectively.\n\nA special character name of length one is not the same thing as an\nordinary character: that is, the character 'a' is not the same as\n'\\[a]'.\n\nIf NAME is undefined, a warning in category 'char' is produced and\nthe escape is ignored. *Note Warnings::, for information about the\nenablement and suppression of warnings.\n\nGNU 'troff' resolves '\\[...]' with more than a single component as\nfollows:\n\n* Any component that is found in the GGL is converted to the\n'uXXXX' form.\n\n* Any component 'uXXXX' that is found in the list of\ndecomposable glyphs is decomposed.\n\n* The resulting elements are then concatenated with '' in\nbetween, dropping the leading 'u' in all elements but the\nfirst.\n\nNo check for the existence of any component (similar to 'tr'\nrequest) is done.\n\nExamples:\n\n'\\[A ho]'\n'A' maps to 'u0041', 'ho' maps to 'u02DB', thus the final\nglyph name would be 'u004102DB'. This is not the expected\nresult: the ogonek glyph 'ho' is a spacing ogonek, but for a\nproper composite a non-spacing ogonek (U+0328) is necessary.\nLooking into the file 'composite.tmac', one can find\n'.composite ho u0328', which changes the mapping of 'ho' while\na composite glyph name is constructed, causing the final glyph\nname to be 'u00410328'.\n\n'\\[^E u0301]'\n'\\[^E aa]'\n'\\[E a^ aa]'\n'\\[E ^ ']'\n'^E' maps to 'u00450302', thus the final glyph name is\n'u004503020301' in all forms (assuming proper calls of the\n'composite' request).\n\nIt is not possible to define glyphs with names like 'A ho' within a\n'groff' font file. This is not really a limitation; instead, you\nhave to define 'u00410328'.\n\n-- Escape sequence: \\C'xxx'\nTypeset the glyph of the special character XXX. Normally, it is\nmore convenient to use '\\[XXX]', but '\\C' has some advantages: it\nis compatible with AT&T device-independent 'troff' (and therefore\navailable in compatibility mode(3) (*note Using\nSymbols-Footnote-3::)) and can interpolate special characters with\n']' in their names. The delimiter need not be a neutral\napostrophe; see *note Delimiters::.\n\n-- Request: .composite id1 id2\nMap special character name ID1 to ID2 if ID1 is used in '\\[...]'\nwith more than one component. See above for examples. This is a\nstrict rewriting of the special character name; no check is\nperformed for the existence of a glyph for either. A set of\ndefault mappings for many accents can be found in the file\n'composite.tmac', loaded by the default 'troffrc' at startup.\n\n-- Escape sequence: \\N'n'\nTypeset the glyph with code N in the current font ('n' is not the\ninput character code). The number N can be any non-negative\ndecimal integer. Most devices only have glyphs with codes between\n0 and 255; the Unicode output device uses codes in the range\n0-65535. If the current font does not contain a glyph with that\ncode, special fonts are not searched. The '\\N' escape sequence\ncan be conveniently used in conjunction with the 'char' request:\n\n.char \\[phone] \\f[ZD]\\N'37'\n\nThe code of each glyph is given in the fourth column in the font\ndescription file after the 'charset' command. It is possible to\ninclude unnamed glyphs in the font description file by using a name\nof '---'; the '\\N' escape sequence is the only way to use these.\n\nNo kerning is applied to glyphs accessed with '\\N'. The delimiter\nneed not be a neutral apostrophe; see *note Delimiters::.\n\nA few escape sequences are also special characters.\n\n-- Escape sequence: \\'\nAn escaped neutral apostrophe is a synonym for '\\[aa]' (acute\naccent).\n\n-- Escape sequence: \\`\nAn escaped grave accent is a synonym for '\\[ga]' (grave accent).\n\n-- Escape sequence: \\-\nAn escaped hyphen-minus is a synonym for '\\[-]' (minus sign).\n\n-- Escape sequence: \\\nAn escaped underscore (\"low line\") is a synonym for '\\[ul]'\n(underrule). On typesetting devices, the underrule is\nfont-invariant and drawn lower than the underscore ''.\n\n-- Request: .cflags n c1 c2 ...\nAssign properties encoded by the number N to characters C1, C2, and\nso on.\n\nInput characters, including special characters introduced by an\nescape, have certain properties associated with them.(4) (*note\nUsing Symbols-Footnote-4::) These properties can be modified with\nthis request. The first argument is the sum of the desired flags\nand the remaining arguments are the characters to be assigned those\nproperties. Spaces between the CN arguments are optional. Any\nargument CN can be a character class defined with the 'class'\nrequest rather than an individual character. *Note Character\nClasses::.\n\nThe non-negative integer N is the sum of any of the following.\nSome combinations are nonsensical, such as '33' (1 + 32).\n\n'1'\nRecognize the character as ending a sentence if followed by a\nnewline or two spaces. Initially, characters '.?!' have this\nproperty.\n\n'2'\nEnable breaks before the character. A line is not broken at a\ncharacter with this property unless the characters on each\nside both have non-zero hyphenation codes. This exception can\nbe overridden by adding 64. Initially, no characters have\nthis property.\n\n'4'\nEnable breaks after the character. A line is not broken at a\ncharacter with this property unless the characters on each\nside both have non-zero hyphenation codes. This exception can\nbe overridden by adding 64. Initially, characters\n'\\-\\[hy]\\[em]' have this property.\n\n'8'\nMark the glyph associated with this character as overlapping\nother instances of itself horizontally. Initially, characters\n'\\[ul]\\[rn]\\[ru]\\[radicalex]\\[sqrtex]' have this property.\n\n'16'\nMark the glyph associated with this character as overlapping\nother instances of itself vertically. Initially, the\ncharacter '\\[br]' has this property.\n\n'32'\nMark the character as transparent for the purpose of\nend-of-sentence recognition. In other words, an\nend-of-sentence character followed by any number of characters\nwith this property is treated as the end of a sentence if\nfollowed by a newline or two spaces. This is the same as\nhaving a zero space factor in TeX. Initially, characters\n'\"')]*\\[dg]\\[dd]\\[rq]\\[cq]' have this property.\n\n'64'\nIgnore hyphenation codes of the surrounding characters. Use\nthis in combination with values 2 and 4 (initially, no\ncharacters have this property).\n\nFor example, if you need an automatic break point after the\nen-dash in numeric ranges like \"3000-5000\", insert\n\n.cflags 68 \\[en]\n\ninto your document. However, this practice can lead to bad\nlayout if done thoughtlessly; in most situations, a better\nsolution instead of changing the 'cflags' value is to insert\n'\\:' right after the hyphen at the places that really need a\nbreak point.\n\nThe remaining values were implemented for East Asian language\nsupport; those who use alphabetic scripts exclusively can disregard\nthem.\n\n'128'\nProhibit a line break before the character, but allow a line\nbreak after the character. This works only in combination\nwith flags 256 and 512 and has no effect otherwise.\nInitially, no characters have this property.\n\n'256'\nProhibit a line break after the character, but allow a line\nbreak before the character. This works only in combination\nwith flags 128 and 512 and has no effect otherwise.\nInitially, no characters have this property.\n\n'512'\nAllow line break before or after the character. This works\nonly in combination with flags 128 and 256 and has no effect\notherwise. Initially, no characters have this property.\n\nIn contrast to values 2 and 4, the values 128, 256, and 512 work\npairwise. If, for example, the left character has value 512, and\nthe right character 128, no break will be automatically inserted\nbetween them. If we use value 6 instead for the left character, a\nbreak after the character can't be suppressed since the neighboring\ncharacter on the right doesn't get examined.\n\n-- Request: .char c [contents]\n-- Request: .fchar c [contents]\n-- Request: .fschar f c [contents]\n-- Request: .schar c [contents]\nDefine a new character or glyph C to be CONTENTS, which can be\nempty. More precisely, 'char' defines a 'groff' object (or\nredefines an existing one) that is accessed with the name C on\ninput, and produces CONTENTS on output. Every time glyph C needs\nto be printed, CONTENTS is processed in a temporary environment and\nthe result is wrapped up into a single object. Compatibility mode\nis turned off and the escape character is set to '\\' while CONTENTS\nis processed. Any emboldening, constant spacing, or track kerning\nis applied to this object rather than to individual glyphs in\nCONTENTS.\n\nAn object defined by these requests can be used just like a normal\nglyph provided by the output device. In particular, other\ncharacters can be translated to it with the 'tr' or 'trin'\nrequests; it can be made the leader character with the 'lc'\nrequest; repeated patterns can be drawn with it using the '\\l' and\n'\\L' escape sequences; and words containing C can be hyphenated\ncorrectly if the 'hcode' request is used to give the object a\nhyphenation code.\n\nThere is a special anti-recursion feature: use of the object within\nits own definition is handled like a normal character (not defined\nwith 'char').\n\nThe 'tr' and 'trin' requests take precedence if 'char' accesses the\nsame symbol.\n\n.tr XY\nX\n=> Y\n.char X Z\nX\n=> Y\n.tr XX\nX\n=> Z\n\nThe 'fchar' request defines a fallback glyph: 'gtroff' only checks\nfor glyphs defined with 'fchar' if it cannot find the glyph in the\ncurrent font. 'gtroff' carries out this test before checking\nspecial fonts.\n\n'fschar' defines a fallback glyph for font F: 'gtroff' checks for\nglyphs defined with 'fschar' after the list of fonts declared as\nfont-specific special fonts with the 'fspecial' request, but before\nthe list of fonts declared as global special fonts with the\n'special' request.\n\nFinally, the 'schar' request defines a global fallback glyph:\n'gtroff' checks for glyphs defined with 'schar' after the list of\nfonts declared as global special fonts with the 'special' request,\nbut before the already mounted special fonts.\n\n*Note Character Classes::.\n\n-- Request: .rchar c ...\n-- Request: .rfschar f c ...\nRemove definition of each ordinary or special character C, undoing\nthe effect of a 'char', 'fchar', or 'schar' request. Those\nsupplied by font description files cannot be removed. Spaces and\ntabs may separate C arguments.\n\nThe request 'rfschar' removes glyph definitions defined with\n'fschar' for font F.\n", "subsections": [] }, "File: groff.info, Node: Character Classes, Next: Special Fonts, Prev: Using Symbols, Up: Using Fonts": { "content": "", "subsections": [] }, "Classes are particularly useful for East Asian languages such as": { "content": "", "subsections": [] }, "Chinese, Japanese, and Korean, where the number of needed characters is": { "content": "much larger than in European languages, and where large sets of\ncharacters share the same properties.\n\n-- Request: .class name c1 c2 ...\nDefine a character class (or simply \"class\") NAME comprising the\ncharacters C1, C2, and so on.\n\nA class thus defined can then be referred to in lieu of listing all\nthe characters within it. Currently, only the 'cflags' request can\nhandle references to character classes.\n\nIn the request's simplest form, each CN is a character (or special\ncharacter).\n\n.class [quotes] ' \\[aq] \\[dq] \\[oq] \\[cq] \\[lq] \\[rq]\n\nSince class and glyph names share the same name space, it is\nrecommended to start and end the class name with '[' and ']',\nrespectively, to avoid collisions with existing character names\ndefined by GNU 'troff' or the user (with 'char' and related\nrequests). This practice applies the presence of ']' in the class\nname to prevent the use of the special character escape form\n'\\[...]', thus you must use the '\\C' escape to access a class with\nsuch a name.\n\nYou can also use a character range notation consisting of a start\ncharacter followed by '-' and then an end character. Internally,\nGNU 'troff' converts these two symbol names to Unicode code points\n(according to the 'groff' glyph list [GGL]), which then give the\nstart and end value of the range. If that fails, the class\ndefinition is skipped.\n\nFurthermore, classes can be nested.\n\n.class [prepunct] , : ; > }\n.class [prepunctx] \\C'[prepunct]' \\[u2013]-\\[u2016]\n\nThe class '[prepunctx]' thus contains the contents of the class\n'[prepunct]' as defined above (the set ', : ; > }'), and characters\nin the range between 'U+2013' and 'U+2016'.\n\nIf you want to include '-' in a class, it must be the first\ncharacter value in the argument list, otherwise it gets\nmisinterpreted as part of the range syntax.\n\nIt is not possible to use class names as end points of range\ndefinitions.\n\nA typical use of the 'class' request is to control line-breaking\nand hyphenation rules as defined by the 'cflags' request. For\nexample, to inhibit line breaks before the characters belonging to\nthe 'prepunctx' class defined in the previous example, you can\nwrite the following.\n\n.cflags 2 \\C'[prepunctx]'\n\nSee the 'cflags' request in *note Using Symbols::, for more\ndetails.\n", "subsections": [] }, "File: groff.info, Node: Special Fonts, Next: Artificial Fonts, Prev: Character Classes, Up: Using Fonts": { "content": "", "subsections": [] }, "Special fonts are those that 'gtroff' searches when it cannot find the": { "content": "requested glyph in the current font. The Symbol font is usually a\nspecial font.\n\n'gtroff' provides the following two requests to add more special\nfonts. *Note Using Symbols::, for a detailed description of the glyph\nsearching mechanism in 'gtroff'.\n\nUsually, only non-TTY devices have special fonts.\n\n-- Request: .special [s1 s2 ...]\n-- Request: .fspecial f [s1 s2 ...]\nUse the 'special' request to define special fonts. Initially, this\nlist is empty.\n\nUse the 'fspecial' request to designate special fonts only when\nfont F is active. Initially, this list is empty.\n\nPrevious calls to 'special' or 'fspecial' are overwritten; without\narguments, the particular list of special fonts is set to empty.\nSpecial fonts are searched in the order they appear as arguments.\n\nAll fonts that appear in a call to 'special' or 'fspecial' are\nloaded.\n\n*Note Using Symbols::, for the exact search order of glyphs.\n", "subsections": [] }, "File: groff.info, Node: Artificial Fonts, Next: Ligatures and Kerning, Prev: Special Fonts, Up: Using Fonts": { "content": "", "subsections": [] }, "There are a number of requests and escape sequences for artificially": { "content": "creating fonts. These are largely vestiges of the days when output\ndevices did not have a wide variety of fonts, and when 'nroff' and\n'troff' were separate programs. Most of them are no longer necessary in\nGNU 'troff'. Nevertheless, they are supported.\n\n-- Escape sequence: \\H'height'\n-- Escape sequence: \\H'+height'\n-- Escape sequence: \\H'-height'\n-- Register: \\n[.height]\nChange (increment, decrement) the height of the current font, but\nnot the width. If HEIGHT is zero, restore the original height.\nDefault scaling unit is 'z'.\n\nThe read-only register '.height' contains the font height as set by\n'\\H'.\n\nCurrently, only the '-Tps' and '-Tpdf' devices support this\nfeature.\n\n'\\H' doesn't produce an input token in GNU 'troff'. As a\nconsequence, it can be used in requests like 'mc' (which expects a\nsingle character as an argument) to change the font on the fly:\n\n.mc \\H'+5z'x\\H'0'\n\nIn compatibility mode, 'gtroff' behaves differently: If an\nincrement or decrement is used, it is always taken relative to the\ncurrent type size and not relative to the previously selected font\nheight. Thus,\n\n.cp 1\n\\H'+5'test \\H'+5'test\n\nprints the word 'test' twice with the same font height (five points\nlarger than the current font size).\n\n-- Escape sequence: \\S'slant'\n-- Register: \\n[.slant]\nSlant the current font by SLANT degrees. Positive values slant to\nthe right. Only integer values are possible.\n\nThe read-only register '.slant' contains the font slant as set by\n'\\S'.\n\nCurrently, only the '-Tps' and '-Tpdf' devices support this\nfeature.\n\n'\\S' doesn't produce an input token in GNU 'troff'. As a\nconsequence, it can be used in requests like 'mc' (which expects a\nsingle character as an argument) to change the font on the fly:\n\n.mc \\S'20'x\\S'0'\n\nThis escape is incorrectly documented in the AT&T 'troff' manual;\nthe slant is always set to an absolute value.\n\n-- Request: .ul [lines]\nThe 'ul' request normally underlines subsequent lines if a TTY\noutput device is used. Otherwise, the lines are printed in italics\n(only the term 'underlined' is used in the following). The single\nargument is the quantity of input lines to be underlined; with no\nargument, the next line is underlined. If LINES is zero or\nnegative, stop the effects of 'ul' (if it was active). Requests\nand empty lines do not count for computing the number of underlined\ninput lines, even if they produce some output like 'tl'. Lines\ninserted by macros (e.g., invoked by a trap) do count.\n\nAt the beginning of 'ul', the current font is stored and the\nunderline font is activated. Within the span of a 'ul' request, it\nis possible to change fonts, but after the last line affected by\n'ul' the saved font is restored.\n\nThis number of lines still to be underlined is associated with the\nenvironment (*note Environments::). The underline font can be\nchanged with the 'uf' request.\n\nThe 'ul' request does not underline spaces.\n\n-- Request: .cu [lines]\nThe 'cu' request is similar to 'ul' but underlines spaces as well\n(if a TTY output device is used).\n\n-- Request: .uf font\nSet the underline font (globally) used by 'ul' and 'cu'. By\ndefault, this is the font at position 2. FONT can be either a\nnon-negative font position or the name of a font.\n\n-- Request: .bd font [offset]\n-- Request: .bd font1 font2 [offset]\n-- Register: \\n[.b]\nEmbolden FONT by overstriking its glyphs offset by OFFSET units\nminus one.\n\nTwo syntax forms are available.\n\n* Imitate a bold font unconditionally. The first argument\nspecifies the font to embolden, and the second is the number\nof basic units, minus one, by which the two glyphs are offset.\nIf the second argument is missing, emboldening is turned off.\n\nFONT can be either a non-negative font position or the name of\na font.\n\nOFFSET is available in the '.b' read-only register if a\nspecial font is active; in the 'bd' request, its default unit\nis 'u'.\n\n* Imitate a bold form conditionally. Embolden FONT1 by OFFSET\nonly if font FONT2 is the current font. This request can be\nissued repeatedly to set up different emboldening values for\ndifferent current fonts. If the second argument is missing,\nemboldening is turned off for this particular current font.\n\nThis affects special fonts only (either set up with the\n'special' command in font files or with the 'fspecial'\nrequest).\n\n-- Request: .cs font [width [em-size]]\nSwitch to and from \"constant glyph space mode\". If activated, the\nwidth of every glyph is WIDTH/36 ems. The em size is given\nabsolutely by EM-SIZE; if this argument is missing, the em value is\ntaken from the current font size (as set with the 'ps' request)\nwhen the font is effectively in use. Without second and third\nargument, constant glyph space mode is deactivated.\n\nDefault scaling unit for EM-SIZE is 'z'; WIDTH is an integer.\n", "subsections": [] }, "File: groff.info, Node: Ligatures and Kerning, Next: Dummy Characters, Prev: Artificial Fonts, Up: Using Fonts": { "content": "", "subsections": [] }, "Ligatures are groups of characters that are run together, i.e, producing": { "content": "a single glyph. For example, the letters 'f' and 'i' can form a\nligature 'fi' as in the word 'file'. This produces a cleaner look\n(albeit subtle) to the printed output. Usually, ligatures are not\navailable in fonts for TTY output devices.\n\nMost PostScript fonts support the fi and fl ligatures. The C/A/T\ntypesetter that was the target of AT&T 'troff' also supported 'ff',\n'ffi', and 'ffl' ligatures. Advanced typesetters or 'expert' fonts may\ninclude ligatures for 'ft' and 'ct', although GNU 'troff' does not\nsupport these (yet).\n\nOnly the current font is checked for ligatures and kerns; neither\nspecial fonts nor special charcters defined with the 'char' request (and\nits siblings) are taken into account.\n\n-- Request: .lg [flag]\n-- Register: \\n[.lg]\nSwitch the ligature mechanism on or off; if the parameter is\nnon-zero or missing, ligatures are enabled, otherwise disabled.\nDefault is on. The current ligature mode can be found in the\nread-only register '.lg' (set to 1 or 2 if ligatures are enabled,\n0 otherwise).\n\nSetting the ligature mode to 2 enables the two-character ligatures\n(fi, fl, and ff) and disables the three-character ligatures (ffi\nand ffl).\n\n\"Pairwise kerning\" is another subtle typesetting mechanism that\nmodifies the distance between a glyph pair to improve readability. In\nmost cases (but not always) the distance is decreased. Typewriter-like\nfonts and fonts for terminals where all glyphs have the same width don't\nuse kerning.\n\n-- Request: .kern [flag]\n-- Register: \\n[.kern]\nSwitch kerning on or off. If the parameter is non-zero or missing,\nenable pairwise kerning, otherwise disable it. The read-only\nregister '.kern' is set to 1 if pairwise kerning is enabled,\n0 otherwise.\n\nIf the font description file contains pairwise kerning information,\nglyphs from that font are kerned. Kerning between two glyphs can\nbe inhibited by placing '\\&' between them: 'V\\&A'.\n\n*Note Font Description File Format::.\n\n\"Track kerning\" expands or reduces the space between glyphs. This\ncan be handy, for example, if you need to squeeze a long word onto a\nsingle line or spread some text to fill a narrow column. It must be\nused with great care since it is usually considered bad typography if\nthe reader notices the effect.\n\n-- Request: .tkf f s1 n1 s2 n2\nEnable track kerning for font F. If the current font is F the\nwidth of every glyph is increased by an amount between N1 and N2\n(N1, N2 can be negative); if the current type size is less than or\nequal to S1 the width is increased by N1; if it is greater than or\nequal to S2 the width is increased by N2; if the type size is\ngreater than or equal to S1 and less than or equal to S2 the\nincrease in width is a linear function of the type size.\n\nThe default scaling unit is 'z' for S1 and S2, 'p' for N1 and N2.\n\nThe track kerning amount is added even to the rightmost glyph in a\nline; for large values it is thus recommended to increase the line\nlength by the same amount to compensate.\n", "subsections": [] }, "File: groff.info, Node: Italic Corrections, Next: Dummy Characters, Prev: Ligatures and Kerning, Up: Using Fonts": { "content": "", "subsections": [] }, "When typesetting adjacent glyphs from typefaces of different slants, the": { "content": "space between them may require adjustment.\n\n-- Escape sequence: \\/\nApply an \"italic correction\": modify the spacing of the preceding\nglyph so that the distance between it and the following glyph is\ncorrect if the latter is of upright shape. For example, if an\nitalic 'f' is followed immediately by a roman right parenthesis,\nthen in many fonts the top right portion of the 'f' overlaps the\ntop left of the right parenthesis, which is ugly. Use this escape\nsequence whenever an oblique glyph is immediately followed by an\nupright glyph without any intervening space.\n\n-- Escape sequence: \\,\nApply a \"left italic correction\": modify the spacing of the\nfollowing glyph so that the distance between it and the preceding\nglyph is correct if the latter is of upright shape. For example,\nif a roman left parenthesis is immediately followed by an\nitalic 'f', then in many fonts the bottom left portion of the 'f'\noverlaps the bottom of the left parenthesis, which is ugly. Use\nthis escape sequence whenever an upright glyph is followed\nimmediately by an oblique glyph without any intervening space.\n", "subsections": [] }, "File: groff.info, Node: Dummy Characters, Prev: Italic Corrections, Up: Using Fonts": { "content": "As discussed in *note Requests and Macros::, the first character on an\ninput line is treated specially. Further, formatting a glyph has many\nconsequences on formatter state (*note Environments::). Occasionally,\nwe want to escape this context or embrace some of those consequences\nwithout actually rendering a glyph to the output.\n\n-- Escape sequence: \\&\nInterpolate a dummy character, which is constitutive of output but\ninvisible.(1) (*note Dummy Characters-Footnote-1::) Its presence\nalters the interpretation context of a subsequent input character,\nand enjoys several applications.\n\n* Prevent insertion of extra space after an end-of-sentence\ncharacter.\n\nTest.\nTest.\n=> Test. Test.\nTest.\\&\nTest.\n=> Test. Test.\n\n* Prevent recognition of a control character.\n\n.Test\nerror-> warning: macro 'Test' not defined\n\\&.Test\n=> .Test\n\n* Prevent kerning between two glyphs.\n\n* Translate a character to \"nothing\".\n\n.tr JIjiK\\&k\\&UVuv\nPost universitum, alea jacta est, OK?\n=> Post vniversitvm, alea iacta est, O?\n\nThe dummy character escape sequence sees use in macro definitions\nas a means of ensuring that arguments are treated as text even if\nthey begin with spaces or control characters.\n\n.de HD \\\" typeset a simple bold heading\n. sp\n. ft B\n\\&\\\\$1 \\\" exercise: remove the \\&\n. ft\n. sp\n..\n.HD .\\|.\\|.\\|surprised?\n\nOne way to think about the dummy character is to imagine placing the\nsymbol '&' in the input at a certain location; if doing so has all the\nside effects on formatting that you desire except for sticking an ugly\nampersand in the midst of your text, the dummy character is what you\nwant in its place.\n\n-- Escape sequence: \\)\nInterpolate a transparent dummy character--one that is transparent\nto end-of-sentence detection. It behaves as '\\&', except that '\\&'\nis treated as letters and numerals normally are after '.', '?' and\n'!'; '\\&' cancels end-of-sentence detection, and '\\)' does not.\n\n.de Suffix-&\n. nop \\&\\\\$1\n..\n.\n.de Suffix-)\n. nop \\)\\\\$1\n..\n.\nHere's a sentence.\\c\n.Suffix-& '\nAnother one.\\c\n.Suffix-) '\nAnd a third.\n=> Here's a sentence.' Another one.' And a third.\n", "subsections": [] }, "File: groff.info, Node: Manipulating Type Size and Vertical Spacing, Next: Colors, Prev: Using Fonts, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.20 Manipulating Type Size and Vertical Spacing", "content": "These concepts were introduced in *note Page Geometry::. The height of\na font's tallest glyph is one em, which is equal to the type size in\npoints.(1) (*note Manipulating Type Size and Vertical\nSpacing-Footnote-1::) A vertical spacing of less than 120% of the type\nsize can make a document hard to read. Larger proportions can be useful\nto spread the text for annotations or proofreader's marks. By default,\nGNU 'troff' uses 10 point type on 12 point spacing. Typographers call\nthe difference between type size and vertical spacing \"leading\".(2)\n(*note Manipulating Type Size and Vertical Spacing-Footnote-2::)\n\n* Menu:\n\n* Changing the Type Size::\n* Changing the Vertical Spacing::\n* Using Fractional Type Sizes::\n" } ] }, "File: groff.info, Node: Changing the Type Size, Next: Changing the Vertical Spacing, Prev: Manipulating Type Size and Vertical Spacing, Up: Manipulating Type Size and Vertical Spacing": { "content": "-- Request: .ps [size]\n-- Request: .ps +size\n-- Request: .ps -size\n-- Escape sequence: \\ssize\n-- Register: \\n[.s]\nUse the 'ps' request or the '\\s' escape sequence to change\n(increase, decrease) the type size (in scaled points). Specify\nSIZE as either an absolute type size, or as a relative change from\nthe current size. 'ps' with no argument restores the previous\nsize. The 'ps' request's default scaling unit is 'z'. The\nrequested size is rounded to the nearest valid size (with ties\nrounding down) within the limits supported by the device. If the\nrequested size is non-positive, it is treated as 1u.\n\nType size alteration is incorrectly documented in the AT&T 'troff'\nmanual, which claims \"if [the requested size] is invalid, the next\nlarger valid size will result, with a maximum of 36\".(1) (*note\nChanging the Type Size-Footnote-1::)\n\nThe read-only string-valued register '.s' interpolates the type\nsize in points as a decimal fraction; it is associated with the\nenvironment (*note Environments::). To obtain the type size in\nscaled points, interpolate the '.ps' register instead (*note Using\nFractional Type Sizes::).\n\nThe '\\s' escape sequence supports a variety of syntax forms.\n\n'\\sN'\nSet the type size to N points. N must be a single digit. If\nN is 0, restore the previous size.\n\n'\\s+N'\n'\\s-N'\nIncrease or decrease the type size by N points. N must be\nexactly one digit.\n\n'\\s(NN'\nSet the type size to NN points. NN must be exactly two\ndigits.\n\n'\\s+(NN'\n'\\s-(NN'\n'\\s(+NN'\n'\\s(-NN'\nAlter the type size in points by the two-digit value NN.\n\n*Note Using Fractional Type Sizes::, for further syntactical forms\nof the '\\s' escape sequence that additionally accept decimal\nfractions.\n\nsnap, snap,\n.ps +2\ngrin, grin,\n.ps +2\nwink, wink, \\s+2nudge, nudge,\\s+8 say no more!\n.ps 10\n\nThe '\\s' escape sequence affects the environment immediately and\ndoesn't produce an input token. Consequently, it can be used in\nrequests like 'mc', which expects a single character as an argument, to\nchange the type size on the fly.\n\n.mc \\s[20]x\\s[0]\n\n-- Request: .sizes s1 s2 ... sn [0]\nThe 'DESC' file specifies which type sizes are allowed by the\noutput device; see *note DESC File Format::. Use the 'sizes'\nrequest to change this set of permissible sizes. Arguments are in\nscaled points; see *note Using Fractional Type Sizes::. Each can\nbe a single type size (such as '12000'), or a range of sizes (such\nas '4000-72000'). You can optionally end the list with a '0'.\n", "subsections": [] }, "File: groff.info, Node: Changing the Vertical Spacing, Next: Using Fractional Type Sizes, Prev: Changing the Type Size, Up: Manipulating Type Size and Vertical Spacing": { "content": "-- Request: .vs [space]\n-- Request: .vs +space\n-- Request: .vs -space\n-- Register: \\n[.v]\nSet the vertical spacing to, or alter it by, SPACE. The default\nscaling unit is 'p'. If 'vs' is called without an argument, the\nvertical spacing is reset to the previous value before the last\ncall to 'vs'. GNU 'troff' emits a warning in category 'range' if\nSPACE is negative; the vertical spacing is then set to the smallest\npossible positive value, the vertical motion quantum (as found in\nthe '.V' register).\n\n'.vs 0' isn't saved in a diversion since it doesn't result in a\nvertical motion. You must explicitly issue this request before\ninterpolating the diversion.\n\nThe read-only register '.v' contains the vertical spacing; it is\nassociated with the environment (*note Environments::).\n\nWhen a break occurs, GNU 'troff' performs the following procedure.\n\n* Move the drawing position vertically by the \"extra pre-vertical\nline space\", the minimum of all negative '\\x' escape sequence\narguments in the pending output line.\n\n* Move the drawing position vertically by the vertical line spacing.\n\n* Write out the pending output line.\n\n* Move the drawing position vertically by the \"extra post-vertical\nline space\", the maximum of all positive '\\x' escape sequence\narguments in the line that has just been output.\n\n* Move the drawing position vertically by the \"post-vertical line\nspacing\" (see below).\n\nPrefer 'vs' or 'pvs' over 'ls' to produce double-spaced documents.\n'vs' and 'pvs' have finer granularity than 'ls'; moreover, some\npreprocessors assume single spacing. *Note Manipulating Spacing::,\nregarding the '\\x' escape sequence and the 'ls' request.\n\n-- Request: .pvs [space]\n-- Request: .pvs +space\n-- Request: .pvs -space\n-- Register: \\n[.pvs]\nSet the post-vertical spacing to, or alter it by, SPACE. The\ndefault scaling unit is 'p'. If 'pvs' is called without an\nargument, the post-vertical spacing is reset to the previous value\nbefore the last call to 'pvs'. GNU 'troff' emits a warning in\ncategory 'range' if SPACE is negative; the post-vertical spacing is\nthen set to zero.\n\nThe read-only register '.pvs' contains the post-vertical spacing;\nit is associated with the environment (*note Environments::).\n", "subsections": [] }, "File: groff.info, Node: Using Fractional Type Sizes, Prev: Changing the Type Size, Up: Manipulating Type Size and Vertical Spacing": { "content": "AT&T 'troff' interpreted all type size measurements in points. Combined\nwith integer arithmetic, this design choice made it impossible to\nsupport, for instance, ten and a half-point type. In GNU 'troff', an\noutput device can select a scaling factor that subdivides a point into\n\"scaled points\". A type size expressed in scaled points can thus\nrepresent a non-integral type size.\n\nA \"scaled point\" is equal to 1/SIZESCALE points, where SIZESCALE is\nspecified in the device description file 'DESC', and defaults to 1.(1)\n(*note Using Fractional Type Sizes-Footnote-1::) Requests and escape\nsequences in GNU 'troff' interpret arguments that represent a type size\nin scaled points, which the formatter multiplies by SIZESCALE and\nconverts to an integer. Arguments treated in this way comprise those to\nthe escape sequences '\\H' and '\\s', to the request 'ps', the third\nargument to the 'cs' request, and the second and fourth arguments to the\n'tkf' request. Scaled points may be specified explicitly with the 'z'\nscaling unit.\n\nFor example, if SIZESCALE is 1000, then a scaled point is one\nthousandth of a point. The request '.ps 10.5' is synonymous with '.ps\n10.5z' and sets the type size to 10,500 scaled points, or 10.5 points.", "subsections": [] }, "Consequently, in GNU 'troff', the register '.s' can interpolate a": { "content": "non-integral type size.\n\n-- Register: \\n[.ps]\nThis read-only register interpolates the type size in scaled\npoints; it is associated with the environment (*note\nEnvironments::).\n\nIt makes no sense to use the 'z' scaling unit in a numeric expression\nwhose default scaling unit is neither 'u' nor 'z', so GNU 'troff'\ndisallows this. Similarly, it is nonsensical to use a scaling unit\nother than 'z' or 'u' in a numeric expression whose default scaling unit\nis 'z', and so GNU 'troff' disallows this as well.\n\nAnother GNU 'troff' scaling unit, 's', multiplies by the number of\nbasic units in a scaled point. Thus, '\\n[.ps]s' is equal to '1m' by\ndefinition. Do not confuse the 's' and 'z' scaling units.\n\n-- Register: \\n[.psr]\n-- Register: \\n[.sr]\nOutput devices may be limited in the type sizes they can employ.\nThe '.s' and '.ps' registers represent the type size selected by\nthe output driver as it understands a device's capability. The\nlast requested type size is interpolated in scaled points by the\nread-only register '.psr' and in points as a decimal fraction by\nthe read-only string-valued register '.sr'. Both are associated\nwith the environment (*note Environments::).\n\nFor example, if a type size of 10.95 points is requested, and the\nnearest size permitted by a 'sizes' request (or by the 'sizes' or\n'sizescale' directives in the device's 'DESC' file) is 11 points,\nthe output driver uses the latter value.\n\nThe '\\s' escape sequence offers the following syntax forms that work\nwith fractional type sizes and accept scaling units. You may of course\ngive them integral arguments. The delimited forms need not use the\nneutral apostrophe; see *note Delimiters::.\n\n'\\s[N]'\n'\\s'N''\nSet the type size to N scaled points; N is a numeric expression\nwith a default scaling unit of 'z'.\n\n'\\s[+N]'\n'\\s[-N]'\n'\\s+[N]'\n'\\s-[N]'\n'\\s'+N''\n'\\s'-N''\n'\\s+'N''\n'\\s-'N''\nIncrease or decrease the type size by N scaled points; N is a\nnumeric expression (which may start with a minus sign) with a\ndefault scaling unit of 'z'.\n", "subsections": [] }, "File: groff.info, Node: Colors, Next: Strings, Prev: Manipulating Type Size and Vertical Spacing, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.21 Colors", "content": "GNU 'troff' supports color output with a variety of color spaces and up\nto 16 bits per channel. Some devices, particularly terminals, may be\nmore limited. When color support is enabled, two colors are current at\nany given time: the \"stroke color\", with which glyphs, rules (lines),\nand geometric objects like circles and polygons are drawn, and the \"fill\ncolor\", which can be used to paint the interior of a closed geometric\nfigure.\n\n-- Request: .color [n]\n-- Register: \\n[.color]\nIf N is missing or non-zero, enable the output of color-related\ndevice-independent output commands (this is the default);\notherwise, disable them. This request sets a global flag; it does\nnot produce an input token (*note Gtroff Internals::).\n\nThe read-only register '.color' is 1 if colors are enabled,\n0 otherwise.\n\nColor can also be disabled with the '-c' command-line option.\n\n-- Request: .defcolor ident scheme color-component ...\nDefine a color named IDENT. SCHEME selects a color space and\ndetermines the quantity of required COLOR-COMPONENTs; it must be\none of 'rgb' (three components), 'cmy' (three), 'cmyk' (four), or\n'gray' (one). 'grey' is accepted as a synonym of 'gray'. The\ncolor components can be encoded as a single hexadecimal value\nstarting with '#' or '##'. The former indicates that each\ncomponent is in the range 0-255 (0-FF), the latter the range\n0-65,535 (0-FFFF).\n\n.defcolor half gray #7f\n.defcolor pink rgb #FFC0CB\n.defcolor magenta rgb ##ffff0000ffff\n\nAlternatively, each color component can be specified as a decimal\nfraction in the range 0-1, interpreted using a default scaling unit\nof 'f', which multiplies its value by 65,536 (but clamps it at\n65,535).\n\n.defcolor gray50 rgb 0.5 0.5 0.5\n.defcolor darkgreen rgb 0.1f 0.5f 0.2f\n\nEach output device has a color named 'default', which cannot be\nredefined. A device's default stroke and fill colors are not\nnecessarily the same. For the 'dvi', 'html', 'pdf', 'ps', and 'xhtml'\noutput devices, GNU 'troff' automatically loads a macro file defining\nmany color names at startup. By the same mechanism, the devices\nsupported by 'grotty' recognize the eight standard ISO 6429/EMCA-48\ncolor names.(1) (*note Colors-Footnote-1::)\n\n-- Request: .gcolor [color]\n-- Escape sequence: \\mc\n-- Escape sequence: \\m(co\n-- Escape sequence: \\m[color]\n-- Register: \\n[.m]\nSet the stroke color to COLOR.\n\n.gcolor red\nThe next words\n.gcolor\n\\m[red]are in red\\m[]\nand these words are in the previous color.\n\nThe escape sequence '\\m[]' restores the previous stroke color, as\ndoes a 'gcolor' request without an argument.\n\nThe name of the current stroke color is available in the read-only\nstring-valued register '.m'; it is associated with the environment\n(*note Environments::). It interpolates nothing when the stroke\ncolor is the default.\n\n'\\m' doesn't produce an input token in GNU 'troff' (*note Gtroff\nInternals::). It therefore can be used in requests like 'mc'\n(which expects a single character as an argument) to change the\ncolor on the fly:\n\n.mc \\m[red]x\\m[]\n\n-- Request: .fcolor [color]\n-- Escape sequence: \\Mc\n-- Escape sequence: \\M(co\n-- Escape sequence: \\M[color]\n-- Register: \\n[.M]\nSet the fill color for objects drawn with '\\D'...'' escape\nsequences. The escape sequence '\\M[]' restores the previous fill\ncolor, as does an 'fcolor' request without an argument.\n\nThe name of the current fill color is available in the read-only\nstring-valued register '.M'; it is associated with the environment\n(*note Environments::). It interpolates nothing when the fill\ncolor is the default. '\\M' doesn't produce an input token in GNU\n'troff'.\n\nCreate an ellipse with a red interior as follows.\n\n\\M[red]\\h'0.5i'\\D'E 2i 1i'\\M[]\n" } ] }, "File: groff.info, Node: Strings, Next: Conditionals and Loops, Prev: Colors, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.22 Strings", "content": "GNU 'troff' supports strings primarily for user convenience." } ] }, "Conventionally, if one would define a macro only to interpolate a small": { "content": "amount of text, without invoking requests or calling any other macros,\none defines a string instead. Only one string is predefined by the\nlanguage.\n\n-- String: \\*[.T]\nContains the name of the output device (for example, 'utf8' or\n'pdf').\n\nThe 'ds' request creates a string with a specified name and contents\nand the '\\*' escape sequence dereferences its name, interpolating its\ncontents. If the string named by the '\\*' escape sequence does not\nexist, it is defined as empty, nothing is interpolated, and a warning in\ncategory 'mac' is emitted. *Note Warnings::, for information about the\nenablement and suppression of warnings.\n\n-- Request: .ds name [contents]\n-- Request: .ds1 name [contents]\n-- Escape sequence: \\*n\n-- Escape sequence: \\*(nm\n-- Escape sequence: \\*[name [arg1 arg2 ...]]\nDefine a string called NAME with contents CONTENTS. If NAME\nalready exists as an alias, the target of the alias is redefined;\nsee 'als' and 'rm' below. If 'ds' is called with only one\nargument, NAME is defined as an empty string. Otherwise, GNU\n'troff' stores CONTENTS in copy mode.(1) (*note\nStrings-Footnote-1::)\n\nThe '\\*' escape sequence interpolates a previously defined string\nvariable NAME (one-character name N, two-character name NM). The\nbracketed interpolation form accepts arguments that are handled as\nmacro arguments are; recall *note Calling Macros::. In contrast to\nmacro calls, however, if a closing bracket ']' occurs in a string\nargument, that argument must be enclosed in double quotes. '\\*' is\ninterpreted even in copy mode. When defining strings, argument\ninterpolations must be escaped if they are to reference parameters\nfrom the calling context; *Note Parameters::.\n\n.ds cite (\\\\$1, \\\\$2)\nGray codes are explored in \\*[cite Morgan 1998].\n=> Gray codes are explored in (Morgan, 1998).\n\n*Caution:* Unlike other requests, the second argument to the 'ds'\nrequest consumes the remainder of the input line, including\ntrailing spaces. This means that comments on a line with such a\nrequest can introduce unwanted space into a string when they are\nset off from the material they annotate, as is conventional.\n\n.ds H2O H\\v'+.3m'\\s'-2'2\\v'-.3m'\\s0O \\\" water\n\nInstead, place the comment on another line or put the comment\nescape sequence immediately adjacent to the last character of the\nstring.\n\n.ds H2O H\\v'+.3m'\\s'-2'2\\v'-.3m'\\s0O\\\" water\n\nEnding string definitions (and appendments) with a comment, even an\nempty one, prevents unwanted space from creeping into them during\nsource document maintenance.\n\n.ds author Alice Pleasance Liddell\\\"\n.ds empty \\\" might be appended to later with .as\n\nAn initial neutral double quote '\"' in CONTENTS is stripped to\nallow embedding of leading spaces. Any other '\"' is interpreted\nliterally, but it is wise to use the special character escape\nsequence '\\[dq]' instead if the string might be interpolated as\npart of a macro argument; see *note Calling Macros::.\n\n.ds salutation \" Yours in a white wine sauce,\\\"\n.ds c-var-defn \" char mydate[]=\\[dq]2020-07-29\\[dq];\\\"\n\nStrings are not limited to a single input line of text. '\\'\nworks just as it does elsewhere. The resulting string is stored\nwithout the newlines. Care is therefore required when\ninterpolating strings while filling is disabled.\n\n.ds foo This string contains \\\ntext on multiple lines \\\nof input.\n\nIt is not possible to embed a newline in a string that will be\ninterpreted as such when the string is interpolated. To achieve\nthat effect, use '\\*' to interpolate a macro instead; see *note\nPunning Names::.\n\nBecause strings are similar to macros, they too can be defined so\nas to suppress AT&T 'troff' compatibility mode when used; see *note\nWriting Macros:: and *note Compatibility Mode::. The 'ds1' request\ndefines a string such that compatibility mode is off when the\nstring is later interpolated. To be more precise, a \"compatibility\nsave\" input token is inserted at the beginning of the string, and a\n\"compatibility restore\" input token at the end.\n\n.nr xxx 12345\n.ds aa The value of xxx is \\\\n[xxx].\n.ds1 bb The value of xxx is \\\\n[xxx].\n.\n.cp 1\n.\n\\*(aa\nerror-> warning: register '[' not defined\n=> The value of xxx is 0xxx].\n\\*(bb\n=> The value of xxx is 12345.\n\n-- Request: .as name [contents]\n-- Request: .as1 name [contents]\nThe 'as' request is similar to 'ds' but appends CONTENTS to the\nstring stored as NAME instead of redefining it. If NAME doesn't\nexist yet, it is created. If 'as' is called with only one\nargument, no operation is performed (beyond dereferencing the\nstring).\n\n.as salutation \" with shallots, onions and garlic,\\\"\n\nThe 'as1' request is similar to 'as', but compatibility mode is\nswitched off when the appended portion of the string is later\ninterpolated. To be more precise, a \"compatibility save\" input\ntoken is inserted at the beginning of the appended string, and a\n\"compatibility restore\" input token at the end.\n\nSeveral requests exist to perform rudimentary string operations.", "subsections": [] }, "Strings can be queried ('length') and modified ('chop', 'substring',": { "content": "'stringup', 'stringdown'), and their names can be manipulated through\nrenaming, removal, and aliasing ('rn', 'rm', 'als').\n\n-- Request: .length reg anything\nCompute the number of characters of ANYTHING and store the count in\nthe register REG. If REG doesn't exist, it is created. ANYTHING\nis read in copy mode.\n\n.ds xxx abcd\\h'3i'efgh\n.length yyy \\*[xxx]\n\\n[yyy]\n=> 14\n\n-- Request: .chop object\nRemove the last character from the macro, string, or diversion\nnamed OBJECT. This is useful for removing the newline from the end\nof a diversion that is to be interpolated as a string. This\nrequest can be used repeatedly on the same OBJECT; see *note Gtroff\nInternals::, for details on nodes inserted additionally by GNU\n'troff'.\n\n-- Request: .substring str start [end]\nReplace the string named STR with its substring bounded by the\nindices START and END, inclusively. The first character in the\nstring has index 0. If END is omitted, it is implicitly set to the\nlargest valid value (the string length minus one). Negative\nindices count backward from the end of the string: the last\ncharacter has index -1, the character before the last has index -2,\nand so on.\n\n.ds xxx abcdefgh\n.substring xxx 1 -4\n\\*[xxx]\n=> bcde\n.substring xxx 2\n\\*[xxx]\n=> de\n\n-- Request: .stringdown str\n-- Request: .stringup str\nAlter the string named STR by replacing each of its bytes with its\nlowercase ('stringdown') or uppercase ('stringup') version (if one\nexists). Special characters in the string will often transform in\nthe expected way due to the regular naming convention for accented\ncharacters. When they do not, use substrings and/or catenation.\n\n.ds resume R\\['e]sum\\['e]\n\\*[resume]\n.stringdown resume\n\\*[resume]\n.stringup resume\n\\*[resume]\n=> Re'sume' re'sume' R?SUM?\n\n(In practice, we would end the 'ds' request with a comment escape\n'\\\"' to prevent space from creeping into the definition during source\ndocument maintenance.)\n\n-- Request: .rn old new\nRename the request, macro, diversion, or string OLD to NEW.\n\n-- Request: .rm name\nRemove the request, macro, diversion, or string NAME. GNU 'troff'\ntreats subsequent invocations as if the name had never been\ndefined.\n\n-- Request: .als new old\nCreate an alias NEW for the existing request, string, macro, or\ndiversion object named OLD, causing the names to refer to the same\nstored object. If OLD is undefined, a warning in category 'mac' is\nproduced, and the request is ignored. *Note Warnings::, for\ninformation about the enablement and suppression of warnings.\n\nTo understand how the 'als' request works, consider two different\nstorage pools: one for objects (macros, strings, etc.), and another\nfor names. As soon as an object is defined, GNU 'troff' adds it to\nthe object pool, adds its name to the name pool, and creates a link\nbetween them. When 'als' creates an alias, it adds a new name to\nthe name pool that gets linked to the same object as the old name.\n\nNow consider this example.\n\n.de foo\n..\n.\n.als bar foo\n.\n.de bar\n. foo\n..\n.\n.bar\nerror-> input stack limit exceeded (probable infinite\nerror-> loop)\n\nIn the above, 'bar' remains an alias--another name for--the\nobject referred to by 'foo', which the second 'de' request\nreplaces. Alternatively, imagine that the 'de' request\ndereferences its argument before replacing it. Either way, the\nresult of calling 'bar' is a recursive loop that finally leads to\nan error. *Note Writing Macros::.\n\nTo remove an alias, call 'rm' on its name. The object itself is\nnot destroyed until it has no more names.\n\nWhen a request, macro, string, or diversion is aliased,\nredefinitions and appendments \"write through\" alias names. To\nreplace an alias with a separately defined object, you must use the\n'rm' request on its name first.\n", "subsections": [] }, "File: groff.info, Node: Conditionals and Loops, Next: Writing Macros, Prev: Strings, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.23 Conditionals and Loops", "content": "'groff' has 'if' and 'while' control structures like other languages." } ] }, "However, the syntax for grouping multiple input lines in the branches or": { "content": "bodies of these structures is unusual.\n\n* Menu:\n\n* Operators in Conditionals::\n* if-then::\n* if-else::\n* Conditional Blocks::\n* while::\n", "subsections": [] }, "File: groff.info, Node: Operators in Conditionals, Next: if-then, Prev: Conditionals and Loops, Up: Conditionals and Loops": { "content": "", "subsections": [] }, "In 'if', 'ie', and 'while' requests, in addition to the numeric": { "content": "expressions described in *note Numeric Expressions::, several Boolean\noperators are available; the members of this expanded class are termed\n\"conditional expressions\".\n\n'c GLYPH'\nTrue if GLYPH is available, where GLYPH is an ordinary character, a\nspecial character '\\(XX' or '\\[XXX]', '\\N'XXX'', or has been\ndefined by any of the 'char', 'fchar', 'fschar', or 'schar'\nrequests.\n\n'd NAME'\nTrue if a string, macro, diversion, or request called NAME exists.\n\n'e'\nTrue if the current page is even-numbered.\n\n'F FONT'\nTrue if FONT exists. FONT is handled as if it were opened with the\n'ft' request (that is, font translation and styles are applied),\nwithout actually mounting it.\n\n'm COLOR'\nTrue if COLOR is defined.\n\n'n'\nTrue if the document is being processed in 'nroff' mode. *Note\ntroff and nroff Modes::.\n\n'o'\nTrue if the current page is odd-numbered.\n\n'r REGISTER'\nTrue if REGISTER exists.\n\n'S STYLE'\nTrue if STYLE is available for the current font family. Font\ntranslation is applied.\n\n't'\nTrue if the document is being processed in 'troff' mode. *Note\ntroff and nroff Modes::.\n\n'v'\nAlways false. This condition is recognized only for compatibility\nwith certain other 'troff' implementations.(1) (*note Operators in\nConditionals-Footnote-1::)\n\nIf the first argument to an 'if', 'ie', or 'while' request begins\nwith a non-alphanumeric character apart from '!' (see below); it\nperforms an output comparison test. (2) (*note Operators in", "subsections": [] }, "Conditionals-Footnote-2::)": { "content": "''XXX'YYY''\nTrue if formatting the comparands XXX and YYY produces the same\noutput commands. The delimiter need not be a neutral apostrophe:\nthe output comparison operator accepts the same delimiters as most\nescape sequences; see *note Delimiters::. This \"output comparison\noperator\" formats XXX and YYY in separate environments; after the\ncomparison, the resulting data are discarded.\n\n.ie \"|\"\\fR|\\fP\" true\n.el false\n=> true\n\nThe resulting glyph properties, including font family, style, size,\nand slant, must match, but not necessarily the requests and/or\nescape sequences used to obtain them. In the previous example, '|'\nand '\\fR|\\fP' result in '|' glyphs in the same typefaces at the\nsame positions, so the comparands are equal. If '.ft I' had been\nadded before the '.ie', they would differ: the first '|' would\nproduce an italic '|', not a roman one. Motions must match in\norientation and magnitude to within the applicable horizontal and\nvertical motion quanta of the device, after rounding. '.if\n\"\\u\\d\"\\v'0'\"' is false even though both comparands result in zero\nnet motion, because motions are not interpreted or optimized but\nsent as-is to the output.(3) (*note Operators in\nConditionals-Footnote-3::) On the other hand, '.if \"\\d\"\\v'0.5m'\"'\nis true, because '\\d' is defined as a downward motion of one-half\nem.(4) (*note Operators in Conditionals-Footnote-4::)\n\nSurround the comparands with '\\?' to avoid formatting them; this\ncauses them to be compared character by character, as with string\ncomparisons in other programming languages.\n\n.ie \"\\?|\\?\"\\?\\fR|\\fP\\?\" true\n.el false\n=> false\n\nSince comparands protected with '\\?' are read in copy mode (*note\nCopy Mode::), they need not even be valid 'groff' syntax. The\nescape character is still lexically recognized, however, and\nconsumes the next character.\n\n.ds a \\[\n.ds b \\[\n.if '\\?\\*a\\?'\\?\\*b\\?' a and b equivalent\n.if '\\?\\\\?'\\?\\\\?' backslashes equivalent\n=> a and b equivalent\n\nThe above operators can't be combined with most others, but a leading\n'!', not followed immediately by spaces or tabs, complements an\nexpression.\n\n.nr x 1\n.ie !r x register x is not defined\n.el register x is defined\n=> register x is defined\n\nSpaces and tabs are optional immediately after the 'c', 'd', 'F',\n'm', 'r', and 'S' operators, but right after '!', they end the predicate\nand the conditional evaluates true.(5) (*note Operators in", "subsections": [] }, "Conditionals-Footnote-5::)": { "content": ".nr x 1\n.ie ! r x register x is not defined\n.el register x is defined\n=> r x register x is not defined\n", "subsections": [] }, "The unexpected 'r x' in the output is a clue that our conditional was": { "content": "not interpreted as we planned, but matters may not always be so obvious.\n", "subsections": [] }, "File: groff.info, Node: if-then, Next: if-else, Prev: Operators in Conditionals, Up: Conditionals and Loops": { "content": "-- Request: .if cond-expr anything\nEvaluate the conditional expression COND-EXPR, and if it evaluates\ntrue (or to a positive value), interpret the remainder of the line\nANYTHING as if it were an input line. Recall from *note Invoking\nRequests:: that any quantity of spaces between arguments to\nrequests serves only to separate them; leading spaces in ANYTHING\nare thus not seen. ANYTHING effectively cannot be omitted; if\nCOND-EXPR is true and ANYTHING is empty, the newline at the end of\nthe control line is interpreted as a blank input line (and\ntherefore a blank text line).\n\nsuper\\c\ntanker\n.nr force-word-break 1\nsuper\\c\n.if ((\\n[force-word-break] = 1) & \\n[.int])\ntanker\n=> supertanker super tanker\n\n-- Request: .nop anything\nInterpret ANYTHING as if it were an input line. This is similar to\n'.if 1'. 'nop' is not really \"no operation\"; its argument is\nprocessed--unconditionally. It can be used to cause text lines to\nshare indentation with surrounding control lines.\n\n.als real-MAC MAC\n.de wrapped-MAC\n. tm MAC: called with arguments \\\\$@\n. nop \\\\*[real-MAC]\\\\\n..\n.als MAC wrapped-MAC\n\\# Later...\n.als MAC real-MAC\n\nIn the above, we've used aliasing, 'nop', and the interpolation of\na macro as a string to interpose a wrapper around the macro 'MAC'\n(perhaps to debug it).\n", "subsections": [] }, "File: groff.info, Node: if-else, Next: while, Prev: Operators in Conditionals, Up: Conditionals and Loops": { "content": "-- Request: .ie cond-expr anything\n-- Request: .el anything\nUse the 'ie' and 'el' requests to write an if-then-else. The first\nrequest is the \"if\" part and the latter is the \"else\" part.\nUnusually among programming languages, any number of\nnon-conditional requests may be interposed between the 'ie' branch\nand the 'el' branch.\n\n.nr a 0\n.ie \\na a is non-zero.\n.nr a +1\n.el a was not positive but is now \\na.\n=> a was not positive but is now 1.\n\nAnother way in which 'el' is an ordinary request is that it does\nnot lexically \"bind\" more tightly to its 'ie' counterpart than it\ndoes to any other request. This fact can surprise C programmers.\n\n.nr a 1\n.nr z 0\n.ie \\nz \\\n. ie \\na a is true\n. el a is false\n.el z is false\nerror-> warning: unbalanced 'el' request\n=> a is false\n\nTo conveniently nest conditionals, keep reading.\n", "subsections": [] }, "File: groff.info, Node: Conditional Blocks, Next: while, Prev: Operators in Conditionals, Up: Conditionals and Loops": { "content": "", "subsections": [] }, "It is frequently desirable for a control structure to govern more than": { "content": "one request, macro call, text line, or a combination of the foregoing.\nThe opening and closing brace escape sequences '\\{' and '\\}' define such\ngroups. These \"conditional blocks\" can furthermore be nested.\n\n-- Escape sequence: \\{\n-- Escape sequence: \\}\n'\\{' begins a conditional block; it must appear (after optional\nspaces and tabs) immediately subsequent to the conditional\nexpression of an 'if', 'ie', or 'while' request,(1) (*note\nConditional Blocks-Footnote-1::) or as the argument to an 'el'\nrequest.\n\n'\\}' ends a condition block and should appear on a line with other\noccurrences of itself as necessary to match '\\{' sequences. It can\nbe preceded by a control character, spaces, and tabs. Input after\nany quantity of '\\}' sequences on the same line is processed only\nif all of the preceding conditions to which they correspond are\ntrue. Furthermore, a '\\}' closing the body of a 'while' request\nmust be the last such escape sequence on an input line.\n\nBrace escape sequences outside of control structures have no\nmeaning and produce no output.\n\n*Caution:* Input lines using '\\{' often end with '\\RET', especially\nin macros that consist primarily of control lines. Forgetting to\nuse '\\RET' on an input line after '\\{' is a common source of error.\n\nWe might write the following in a page header macro. If we delete\n'\\RET', the header will carry an unwanted extra empty line (except on\npage 1).\n\n.if (\\\\n[%] != 1) \\{\\\n. ie ((\\\\n[%] % 2) = 0) .tl \\\\*[even-numbered-page-title]\n. el .tl \\\\*[odd-numbered-page-title]\n.\\}\n\nLet us take a closer look at how conditional blocks nest.\n\nA\n.if 0 \\{ B\nC\nD\n\\}E\nF\n=> A F\n\nN\n.if 1 \\{ O\n. if 0 \\{ P\nQ\nR\\} S\\} T\nU\n=> N O U\n\nThe above behavior may challenge the intuition; it was implemented to\nretain compatibility with AT&T 'troff'. For clarity, it is idiomatic to\nend input lines with '\\{' (followed by '\\' if appropriate), and to\nprecede '\\}' on an input line with nothing more than a control\ncharacter, spaces, tabs, and other instances of itself.\n\nWe can use 'ie', 'el', and conditional blocks to simulate the\nmulti-way \"switch\" or \"case\" control structures of other languages. The\nfollowing example is adapted from the 'groff' 'man' package.\nIndentation is used to clarify the logic.\n\n.\\\" Simulate switch/case in roff.\n. ie '\\\\$2'1' .ds title General Commands\\\"\n.el \\{.ie '\\\\$2'2' .ds title System Calls\\\"\n.el \\{.ie '\\\\$2'3' .ds title Library Functions\\\"\n.el \\{.ie '\\\\$2'4' .ds title Kernel Interfaces\\\"\n.el \\{.ie '\\\\$2'5' .ds title File Formats\\\"\n.el \\{.ie '\\\\$2'6' .ds title Games\\\"\n.el \\{.ie '\\\\$2'7' .ds title Miscellaneous Information\\\"\n.el \\{.ie '\\\\$2'8' .ds title System Management\\\"\n.el \\{.ie '\\\\$2'9' .ds title Kernel Development\\\"\n.el .ds title \\\" empty\n.\\}\\}\\}\\}\\}\\}\\}\\}\n", "subsections": [] }, "File: groff.info, Node: while, Prev: if-else, Up: Conditionals and Loops": { "content": "'groff' provides a looping construct: the 'while' request. Its syntax\nmatches the 'if' request.\n\n-- Request: .while cond-expr anything\nEvaluate the conditional expression COND-EXPR, and repeatedly\nexecute ANYTHING unless and until COND-EXPR evaluates false.\nANYTHING, which is often a conditional block, is referred to as the\n'while' request's \"body\".\n\n.nr a 0 1\n.while (\\na < 9) \\{\\\n\\n+a,\n.\\}\n\\n+a\n=> 1, 2, 3, 4, 5, 6, 7, 8, 9, 10\n\nGNU 'troff' treats the body of a 'while' request similarly to that\nof a 'de' request (albeit one not read in copy mode(1) (*note\nwhile-Footnote-1::)), but stores it under an internal name and\ndeletes it when the loop finishes. The operation of a macro\ncontaining a 'while' request can slow significantly if the 'while'\nbody is large. Each time the macro is executed, the 'while' body\nis parsed and stored again.\n\n.de xxx\n. nr num 10\n. while (\\\\n[num] > 0) \\{\\\n. \\\" many lines of code\n. nr num -1\n. \\}\n..\n\nAn often better solution--and one that is more portable, since AT&T\n'troff' lacked the 'while' request--is to instead write a recursive\nmacro. It will be parsed only once.(2) (*note while-Footnote-2::)\n\n.de yyy\n. if (\\\\n[num] > 0) \\{\\\n. \\\" many lines of code\n. nr num -1\n. yyy\n. \\}\n..\n.\n.de xxx\n. nr num 10\n. yyy\n..\n\nTo prevent infinite loops, the default number of available\nrecursion levels is 1,000 or somewhat less.(3) (*note\nwhile-Footnote-3::) You can disable this protective measure, or\nraise the limit, by setting the 'slimit' register. *Note\nDebugging::.\n\nAs noted above, if a 'while' body begins with a conditional block,\nits closing brace must end an input line.\n\n.if 1 \\{\\\n. nr a 0 1\n. while (\\n[a] < 10) \\{\\\n. nop \\n+[a]\n.\\}\\}\nerror-> unbalanced brace escape sequences\n\n-- Request: .break\nExit a 'while' loop. Do not confuse this request with a\ntypographical break or the 'br' request.\n\n-- Request: .continue\nSkip the remainder of a 'while' loop's body, immediately starting\nthe next iteration.\n", "subsections": [] }, "File: groff.info, Node: Writing Macros, Next: Page Motions, Prev: Conditionals and Loops, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.24 Writing Macros", "content": "A \"macro\" is a stored collection of text and control lines that can be\ninterpolated multiple times. Use macros to define common operations." } ] }, "Macros are called in the same way that requests are invoked. While": { "content": "requests exist for the purpose of creating macros, simply calling an\nundefined macro, or interpolating it as a string, will cause it to be\ndefined as empty. *Note Identifiers::.\n\n-- Request: .de name [end]\nDefine a macro NAME, replacing the definition of any existing\nrequest, macro, string, or diversion called NAME. If NAME already\nexists as an alias, the target of the alias is redefined; recall\n*note Strings::. GNU 'troff' enters copy mode,(1) (*note Writing\nMacros-Footnote-1::) storing subsequent input lines as the macro\ndefinition. If the optional second argument is not specified, the\ndefinition ends with the control line '..' (two dots).\nAlternatively, END identifies a macro whose call syntax at the\nstart of a control line ends the definition of NAME; END is then\ncalled normally. A macro definition must end in the same\nconditional block (if any) in which it began (*note Conditional\nBlocks::). Spaces or tabs are permitted after the control\ncharacter in the line containing this ending token (either '.' or\n'END'), but a tab immediately after the token prevents its\nrecognition as the end of a macro definition. The macro END can be\ncalled with arguments.(2) (*note Writing Macros-Footnote-2::)\n\nHere is a small example macro called 'P' that causes a break and\ninserts some vertical space. It could be used to separate\nparagraphs.\n\n.de P\n. br\n. sp .8v\n..\n\nWe can define one macro within another. Attempting to nest '..'\nna?vely will end the outer definition because the inner definition\nisn't interpreted as such until the outer macro is later\ninterpolated. We can use an end macro instead. Each level of\nnesting should use a unique end macro.\n\nAn end macro need not be defined until it is called. This fact\nenables a nested macro definition to begin inside one macro and end\ninside another. Consider the following example.(3) (*note Writing\nMacros-Footnote-3::)\n\n.de m1\n. de m2 m3\nyou\n..\n.de m3\nHello,\nJoe.\n..\n.de m4\ndo\n..\n.m1\nknow?\n. m3\nWhat\n.m4\n.m2\n=> Hello, Joe. What do you know?\n\nA nested macro definition can be terminated with '..' and nested\nmacros can reuse end macros, but these control lines must be\nescaped multiple times for each level of nesting. The necessity of\nthis escaping and the utility of nested macro definitions will\nbecome clearer when we employ macro parameters and consider the\nbehavior of copy mode in detail.\n\n'de' defines a macro that inherits the compatibility mode enablement\nstatus of its context (*note Implementation Differences::). Often it is\ndesirable to make a macro that uses 'groff' features callable from\ncontexts where compatibility mode is on; for instance, when writing\nextensions to a historical macro package. To achieve this,\ncompatibility mode needs to be switched off while such a macro is\ninterpreted--without disturbing that state when it is finished.\n\n-- Request: .de1 name [end]\nThe 'de1' request defines a macro to be interpreted with\ncompatibility mode disabled. When NAME is called, compatibility\nmode enablement status is saved; it is restored when the call\ncompletes. Observe the extra backlash before the interpolation of\nregister 'xxx'; we'll explore this subject in *note Copy Mode::.\n\n.nr xxx 12345\n.de aa\nThe value of xxx is \\\\n[xxx].\n. br\n..\n.de1 bb\nThe value of xxx is \\\\n[xxx].\n..\n.cp 1\n.aa\nerror-> warning: register '[' not defined\n=> The value of xxx is 0xxx].\n.bb\n=> The value of xxx is 12345.\n\n-- Request: .dei name [end]\n-- Request: .dei1 name [end]\nThe 'dei' request defines a macro with its name and end macro\nindirected through strings. That is, it interpolates strings named\nNAME and END before performing the definition.\n\nThe following examples are equivalent.\n\n.ds xx aa\n.ds yy bb\n.dei xx yy\n\n.de aa bb\n\nThe 'dei1' request bears the same relationship to 'dei' as 'de1'\ndoes to 'de'; it temporarily turns compatibility mode off when NAME\nis called.\n\n-- Request: .am name [end]\n-- Request: .am1 name [end]\n-- Request: .ami name [end]\n-- Request: .ami1 name [end]\n'am' appends subsequent input lines to macro NAME, extending its\ndefinition, and otherwise working as 'de' does.\n\nTo make the previously defined 'P' macro set indented instead of\nblock paragraphs, add the necessary code to the existing macro.\n\n.am P\n.ti +5n\n..\n\nThe other requests are analogous to their 'de' counterparts. The\n'am1' request turns off compatibility mode during interpretation of\nthe appendment. The 'ami' request appends indirectly, meaning that\nstrings NAME and END are interpolated with the resulting names used\nbefore appending. The 'ami1' request is similar to 'ami',\ndisabling compatibility mode during interpretation of the appended\nlines.\n\nUsing 'trace.tmac', you can trace calls to 'de', 'de1', 'am', and\n'am1'. You can also use the 'backtrace' request at any point desired to\ntroubleshoot tricky spots (*note Debugging::).\n\n*Note Strings::, for the 'als', 'rm', and 'rn' requests to create an\nalias of, remove, and rename a macro, respectively.\n\nMacro identifiers share their name space with requests, strings, and\ndiversions; see *note Identifiers::. The 'am', 'as', 'da', 'de', 'di',\nand 'ds' requests (together with their variants) create a new object\nonly if the name of the macro, diversion, or string is currently\nundefined or if it is defined as a request; normally, they modify the\nvalue of an existing object. *Note the description of the 'als'\nrequest: als, for pitfalls when redefining a macro that is aliased.\n\n-- Request: .return [anything]\nExit a macro, immediately returning to the caller. If called with\nan argument ANYTHING, exit twice--the current macro and the macro\none level higher. This is used to define a wrapper macro for\n'return' in 'trace.tmac'.\n\n* Menu:\n\n* Parameters::\n* Copy Mode::\n", "subsections": [] }, "File: groff.info, Node: Parameters, Next: Copy Mode, Prev: Writing Macros, Up: Writing Macros": { "content": "", "subsections": [] }, "Macro calls and string interpolations optionally accept a list of": { "content": "arguments; recall *note Calling Macros::. At the time such an\ninterpolation takes place, these \"parameters\" can be examined using a\nregister and a variety of escape sequences starting with '\\$'. All such\nescape sequences are interpreted even in copy mode, a fact we shall\nmotivate and explain below (*note Copy Mode::).\n\n-- Register: \\n[.$]\nThe count of parameters available to a macro or string is kept in\nthis read-only register. The 'shift' request can change its value.\n\nAny individual parameter can be accessed by its position in the list\nof arguments to the macro call, numbered from left to right starting at\n1, with one of the following escape sequences.\n\n-- Escape sequence: \\$n\n-- Escape sequence: \\$(nn\n-- Escape sequence: \\$[nnn]\nInterpolate the Nth, NNth, or NNNth parameter. The first form\nexpects only a single digit (1<=N<=9)), the second two digits\n(01<=NN<=99)), and the third any positive integer NNN. Macros and\nstrings accept an unlimited number of parameters.\n\n-- Request: .shift [n]\nShift the parameters N places (1 by default). This is a \"left\nshift\": what was parameter I becomes parameter I-N. The parameters\nformerly in positions 1 to N are no longer available. Shifting by\na non-positive amount performs no operation. The register '.$' is\nadjusted accordingly.\n\nIn practice, parameter interpolations are usually seen prefixed with\nan extra escape character. This is because the '\\$' family of escape\nsequences is interpreted even in copy mode.(1) (*note", "subsections": [] }, "Parameters-Footnote-1::)": { "content": "-- Escape sequence: \\$*\n-- Escape sequence: \\$@\n-- Escape sequence: \\$^\nIn some cases it is convenient to interpolate all of the parameters\nat once (to pass them to a request, for instance). The '\\$*'\nescape concatenates the parameters, separating them with spaces.\n'\\$@' is similar, concatenating the parameters, surrounding each\nwith double quotes and separating them with spaces. If not in\ncompatibility mode, the interpolation depth of double quotes is\npreserved (*note Calling Macros::). '\\$^' interpolates all\nparameters as if they were arguments to the 'ds' request.\n\n.de foo\n. tm $1='\\\\$1'\n. tm $2='\\\\$2'\n. tm $*='\\\\$*'\n. tm $@='\\\\$@'\n. tm $^='\\\\$^'\n..\n.foo \" This is a \"test\"\nerror-> $1=' This is a '\nerror-> $2='test\"'\nerror-> $*=' This is a test\"'\nerror-> $@='\" This is a \" \"test\"\"'\nerror-> $^='\" This is a \"test\"'\n\n'\\$*' is useful when writing a macro that doesn't need to\ndistinguish its arguments, or even to not interpret them; examples\ninclude macros that produce diagnostic messages by wrapping the\n'tm' or 'ab' requests. Use '\\$@' when writing a macro that may\nneed to shift its parameters and/or wrap a macro or request that\nfinds the count significant. If in doubt, prefer '\\$@' to '\\$*'.\nAn application of '\\$^' is seen in 'trace.tmac', which redefines\nsome requests and macros for debugging purposes.\n\n-- Escape sequence: \\$0\nInterpolate the name by which the macro being interpreted was\ncalled. The 'als' request can cause a macro to have more than one\nname. Applying string interpolation to a macro does not change\nthis name.\n\n.de foo\n. tm \\\\$0\n..\n.als bar foo\n.\n.de aaa\n. foo\n..\n.de bbb\n. bar\n..\n.de ccc\n\\\\*[foo]\\\\\n..\n.de ddd\n\\\\*[bar]\\\\\n..\n.\n.aaa\nerror-> foo\n.bbb\nerror-> bar\n.ccc\nerror-> ccc\n.ddd\nerror-> ddd\n", "subsections": [] }, "File: groff.info, Node: Copy Mode, Prev: Parameters, Up: Writing Macros": { "content": "", "subsections": [] }, "When GNU 'troff' processes certain requests, most importantly those": { "content": "which define or append to a macro or string, it does so in \"copy mode\":\nit copies the characters of the definition into a dedicated storage\nregion, interpolating the escape sequences '\\n', '\\g', '\\$', '\\*', '\\V',\nand '\\?' normally; interpreting '\\' immediately; discarding\ncomments '\\\"' and '\\#'; interpolating the current leader, escape, or tab\ncharacter with '\\a', '\\e', and '\\t', respectively; and storing all other\nescape sequences in an encoded form.\n\nThe complement of copy mode--a 'roff' formatter's behavior when not\ndefining or appending to a macro, string, or diversion--where all macros\nare interpolated, requests invoked, and valid escape sequences processed\nimmediately upon recognition, can be termed \"interpretation mode\".\n\n-- Escape sequence: \\\\\nThe escape character, '\\' by default, can escape itself. This\nenables you to control whether a given '\\n', '\\g', '\\$', '\\*',\n'\\V', or '\\?' escape sequence is interpreted at the time the macro\ncontaining it is defined, or later when the macro is called.(1)\n(*note Copy Mode-Footnote-1::)\n\n.nr x 20\n.de y\n.nr x 10\n\\&\\nx\n\\&\\\\nx\n..\n.y\n=> 20 10\n\nYou can think of '\\\\' as a \"delayed\" backslash; it is the escape\ncharacter followed by a backslash from which the escape character\nhas removed its special meaning. Consequently, '\\\\' is not an\nescape sequence in the usual sense. In any escape sequence '\\X'\nthat GNU 'troff' does not recognize, the escape character is\nignored and X is output. An unrecognized escape sequence causes a\nwarning in category 'escape', with two exceptions--'\\\\' is the\nfirst.\n\n-- Escape sequence: \\.\n'\\.' escapes the control character. It is similar to '\\\\' in that\nit isn't a true escape sequence. It is used to permit nested macro\ndefinitions to end without a named macro call to conclude them.\nWithout a syntax for escaping the control character, this would not\nbe possible.\n\n.de m1\nfoo\n.\n. de m2\nbar\n\\\\..\n.\n..\n.m1\n.m2\n=> foo bar\n\nThe first backslash is consumed while the macro is read, and the\nsecond is interpreted when macro 'm1' is called.\n\n'roff' documents should not use the '\\\\' or '\\.' character sequences\noutside of copy mode; they serve only to obfuscate the input. Use '\\e'\nto represent the escape character, '\\[rs]' to obtain a backslash glyph,\nand '\\&' before '.' and ''' where GNU 'troff' expects them as control\ncharacters if you mean to use them literally (recall *note Requests and\nMacros::).\n\nMacro definitions can be nested to arbitrary depth. The mechanics of\nparsing the escape character have significant consequences for this\npractice.\n\n.de M1\n\\\\$1\n. de M2\n\\\\\\\\$1\n. de M3\n\\\\\\\\\\\\\\\\$1\n\\\\\\\\..\n. M3 hand.\n\\\\..\n. M2 of\n..\nThis understeer is getting\n.M1 out\n=> This understeer is getting out of hand.\n\nEach escape character is interpreted twice--once in copy mode, when\nthe macro is defined, and once in interpretation mode, when the macro is\ncalled. As seen above, this fact leads to exponential growth in the\nquantity of escape characters required to delay interpolation of '\\n',\n'\\g', '\\$', '\\*', '\\V', and '\\?' at each nesting level, which can be\ndaunting. GNU 'troff' offers a solution.\n\n-- Escape sequence: \\E\n'\\E' represents an escape character that is not interpreted in copy\nmode. You can use it to ease the writing of nested macro\ndefinitions.\n\n.de M1\n. nop \\E$1\n. de M2\n. nop \\E$1\n. de M3\n. nop \\E$1\n\\\\\\\\..\n. M3 better.\n\\\\..\n. M2 bit\n..\nThis vehicle handles\n.M1 a\n=> This vehicle handles a bit better.\n\nObserve that because '\\.' is not a true escape sequence, we can't\nuse '\\E' to keep '..' from ending a macro definition prematurely.\nIf the multiplicity of backslashes complicates maintenance, use end\nmacros.\n\n'\\E' is also convenient to define strings containing escape\nsequences that need to work when used in copy mode (for example, as\nmacro arguments), or which will be interpolated at varying macro\nnesting depths. We might define strings to begin and end\nsuperscripting as follows.(2) (*note Copy Mode-Footnote-2::)\n\n.ds { \\v'-.9m\\s'\\En[.s]*7u/10u'+.7m'\n.ds } \\v'-.7m\\s0+.9m'\n\nWhen the 'ec' request is used to redefine the escape character,\n'\\E' also makes it easier to distinguish the semantics of an escape\ncharacter from the other meaning(s) its character might have.\nConsider the use of an unusual escape character, '-'.\n\n.nr a 1\n.ec -\n.de xx\n--na\n..\n.xx\n=> -na\n\nThis result may surprise you; some people expect '1' to be output\nsince register 'a' has clearly been defined with that value. What\nhas happened? The robotic replacement of '\\' with '-' has led us\nastray. You might recognize the sequence '--' more readily with\nthe default escape character as '\\-', the special character escape\nsequence for the minus sign glyph.\n\n.nr a 1\n.ec -\n.de xx\n-Ena\n..\n.xx\n=> 1\n", "subsections": [] }, "File: groff.info, Node: Page Motions, Next: Drawing Geometric Objects, Prev: Writing Macros, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.25 Page Motions", "content": "*Note Manipulating Spacing::, for a discussion of the most commonly used\nrequest for vertical motion, 'sp', which spaces downward by one vee.\n\n-- Request: .mk [reg]\n-- Request: .rt [dist]\nYou can \"mark\" a location on a page for subsequent \"return\". 'mk'\ntakes an argument, a register name in which to store the current\npage location. If given no argument, it stores the location in an\ninternal register. This location can be used later by the 'rt' or\nthe 'sp' requests (or the '\\v' escape).\n\nThe 'rt' request returns upward to the location marked with the\nlast 'mk' request. If used with an argument, it returns to a\nvertical position DIST from the top of the page (no previous call\nto 'mk' is necessary in this case). The default scaling unit is\n'v'.\n\nIf a page break occurs between a 'mk' request and its matching 'rt'\nrequest, the 'rt' request is silently ignored.\n\nA simple implementation of a macro to set text in two columns\nfollows.\n\n.nr column-length 1.5i\n.nr column-gap 4m\n.nr bottom-margin 1m\n.\n.de 2c\n. br\n. mk\n. ll \\\\n[column-length]u\n. wh -\\\\n[bottom-margin]u 2c-trap\n. nr right-side 0\n..\n.\n.de 2c-trap\n. ie \\\\n[right-side] \\{\\\n. nr right-side 0\n. po -(\\\\n[column-length]u + \\\\n[column-gap]u)\n. \\\" remove trap\n. wh -\\\\n[bottom-margin]u\n. \\}\n. el \\{\\\n. \\\" switch to right side\n. nr right-side 1\n. po +(\\\\n[column-length]u + \\\\n[column-gap]u)\n. rt\n. \\}\n..\n\nNow let us apply our two-column macro.\n\n.pl 1.5i\n.ll 4i\nThis is a small test that shows how the\nrt request works in combination with mk.\n\n.2c\nStarting here, text is typeset in two columns.\nNote that this implementation isn't robust\nand thus not suited for a real two-column\nmacro.\n=> This is a small test that shows how the\n=> rt request works in combination with mk.\n=>\n=> Starting here, isn't robust\n=> text is typeset and thus not\n=> in two columns. suited for a\n=> Note that this real two-column\n=> implementation macro.\n\nSeveral escape sequences enable fine control of movement about the\npage.\n\n-- Escape sequence: \\v'expr'\nVertically move the drawing position. EXPR indicates the magnitude\nof motion: positive is downward and and negative upward. The\ndefault scaling unit is 'v'. The motion is relative to the current\ndrawing position unless EXPR begins with the boundary-relative\nmotion operator '|'. *Note Numeric Expressions::.\n\nText processing continues at the new drawing position; usually,\nvertical motions should be in balanced pairs to avoid a confusing\npage layout.\n\n'\\v' will not spring a vertical position trap. This can be useful;\nfor example, consider a page bottom trap macro that prints a marker\nin the margin to indicate continuation of a footnote. *Note\nTraps::.\n\nA few escape sequences that produce vertical motion are unusual.\nThey are thought to originate early in AT&T 'nroff' history to achieve\nsuper- and subscripting by half-line motions on line printers and\nteletypewriters before the phototypesetter made more precise positioning\navailable. They are reckoned in ems--not vees--to maintain continuity\nwith their original purpose of moving relative to the size of the type\nrather than the distance between text baselines (vees).(1) (*note Page" } ] }, "Motions-Footnote-1::)": { "content": "-- Escape sequence: \\r\n-- Escape sequence: \\u\n-- Escape sequence: \\d\nMove upward 1m, upward .5m, and downward .5m, respectively.\n\nLet us see these escape sequences in use.\n\nObtain 100 cm\\u3\\d of \\ka\\d\\092\\h'|\\nau'\\r233\\dU.\n\nIn the foregoing we have paired '\\u' and '\\d' to typeset a\nsuperscript, and later a full em negative (\"reverse\") motion to place a\nsuperscript above a subscript. A numeral-width horizontal motion escape\nsequence aligns the proton and nucleon numbers, while '\\k' marks a\nhorizontal position to which '\\h' returns so that we could stack them.\n(We shall discuss these horizontal motion escape sequences presently.)", "subsections": [] }, "In serious applications, we often want to alter the type size of the": { "content": "-scripts and to fine-tune the vertical motions, as the 'groff' 'ms'\npackage does with its super- and subscripting string definitions.\n\n-- Escape sequence: \\h'expr'\nHorizontally move the drawing position. EXPR indicates the\nmagnitude of motion: positive is rightward and negative leftward.\nThe default scaling unit is 'm'. The motion is relative to the\ncurrent drawing position unless EXPR begins with the\nboundary-relative motion operator '|'. *Note Numeric\nExpressions::.\n\nThe following string definition sets the TeX logo.(2) (*note Page", "subsections": [] }, "Motions-Footnote-2::)": { "content": ".ds TeX T\\h'-.1667m'\\v'.224m'E\\v'-.224m'\\h'-.125m'X\\\"\n\nThere are a number of special-case escape sequences for horizontal\nmotion.\n\n-- Escape sequence: \\\nMove right one word space. (The input is a backslash followed by a\nspace.) This escape sequence can be thought of as a\nnon-adjustable, unbreakable space. Usually you want '\\~' instead;\nsee *note Manipulating Filling and Adjustment::.\n\n-- Escape sequence: \\|\nMove one-sixth em to the right on typesetting output devices. If a\nglyph named '\\|' is defined in the current font, its width is used\ninstead, even on terminal output devices.\n\n-- Escape sequence: \\^\nMove one-twelfth em to the right on typesetting output devices. If\na glyph named '\\^' is defined in the current font, its width is\nused instead, even on terminal output devices.\n\n-- Escape sequence: \\0\nMove right by the width of a numeral in the current font.\n\nHorizontal motions are not discarded at the end of an output line as\nword spaces are. *Note Breaking::.\n\n-- Escape sequence: \\w'anything'\n-- Register: \\n[st]\n-- Register: \\n[sb]\n-- Register: \\n[rst]\n-- Register: \\n[rsb]\n-- Register: \\n[ct]\n-- Register: \\n[ssc]\n-- Register: \\n[skw]\nInterpolate the width of ANYTHING in basic units. This escape\nsequence allows several properties of formatted output to be\nmeasured without writing it out.\n\nThe length of the string 'abc' is \\w'abc'u.\n=> The length of the string 'abc' is 72u.\n\nANYTHING is processed in a dummy environment: this means that font\nand type size changes, for example, may occur within it without\naffecting subsequent output.\n\nAfter each use, '\\w' sets several registers.\n\n'st'\n'sb'\nThe maximum vertical displacements of the text baseline above\nand below, respectively. The sign convention is opposite that\nof relative vertical motions; that is, depth below the\n(original) baseline is negative. These registers are\nincorrectly documented in the AT&T 'troff' manual as \"the\nhighest and lowest extent of [the argument to '\\w'] relative\nto the baseline\".\n\n'rst'\n'rsb'\nLike 'st' and 'sb', but taking account of the heights and\ndepths of glyphs. In other words, these registers store the\nhighest and lowest vertical positions attained by ANYTHING,\ndoing what AT&T 'troff' documented 'st' and 'sb' as doing.\n\n'ct'\nCharacterizes the geometry of glyphs occurring in ANYTHING.\n\n0\nonly short glyphs, no descenders or tall glyphs\n\n1\nat least one descender\n\n2\nat least one tall glyph\n\n3\nat least one each of a descender and a tall glyph\n\n'ssc'\nThe amount of horizontal space (possibly negative) that should\nbe added to the last glyph before a subscript.\n\n'skw'\nHow far to right of the center of the last glyph in the '\\w'\nargument, the center of an accent from a roman font should be\nplaced over that glyph.\n\n-- Escape sequence: \\kp\n-- Escape sequence: \\k(ps\n-- Escape sequence: \\k[position]\nStore the current horizontal position in the input line in a\nregister with the name POSITION (one-character name P,\ntwo-character name PS). Use this, for example, to return to the\nbeginning of a string for highlighting or other decoration.\n\n-- Register: \\n[hp]\nThe current horizontal position at the input line.\n\n-- Register: \\n[.k]\nA read-only register containing the current horizontal output\nposition (relative to the current indentation).\n\n-- Escape sequence: \\o'abc...'\nOverstrike the glyphs of characters A, B, C, ...; the glyphs are\ncentered, written, and the drawing position advanced by the widest\nof the glyphs.\n\n-- Escape sequence: \\zc\nFormat the character C with zero width; that is, without advancing\nthe drawing position. Use '\\z' to overstrike glyphs aligned to\ntheir left edges, in contrast to '\\o''s centering.\n\n-- Escape sequence: \\Z'anything'\nSave the drawing position, format ANYTHING, then restore it. Tabs\nand leaders in the argument are ignored with an error diagnostic.\n\nWe might implement a strike-through macro thus.\n\n.de ST\n.nr width \\w'\\\\$1'\n\\Z@\\v'-.25m'\\l'\\\\n[width]u'@\\\\$1\n..\n.\nThis is\n.ST \"a test\"\nan actual emergency!\n", "subsections": [] }, "File: groff.info, Node: Drawing Geometric Objects, Next: Traps, Prev: Page Motions, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.26 Drawing Geometric Objects", "content": "A few of the formatter's escape sequences draw lines and other geometric\nobjects. Combined with each other and with page motion commands (*note" } ] }, "Page Motions::), a wide variety of figures is possible. For complex": { "content": "drawings, these operations can be cumbersome; the preprocessors 'gpic'\nor 'ggrn' are typically used instead.\n\nThe '\\l' and '\\L' escape sequences draw horizontal and vertical\nsequences of glyphs, respectively. Even the simplest of output devices\nsupports them.\n\n-- Escape sequence: \\l'l'\n-- Escape sequence: \\l'lc'\nDraw a horizontal line of length L from the drawing position.\nRightward motion is positive. Afterward, the drawing position is\nat the right end of the line. The default scaling unit is 'm'.\n\nThe optional second parameter C is a character with which to draw\nthe line. The default is the baseline rule special character,\n'\\[ru]'.\n\nIf C is a valid scaling unit, put '\\&' after L to disambiguate the\ninput.\n\n.de textbox\n\\[br]\\\\$*\\[br]\\l'|0\\[rn]'\\l'|0\\[ul]'\n..\n\nThe foregoing outputs a box rule (a vertical line), the text\nargument(s), and another box rule. We employ the boundary-relative\nmotion operator '|'. Finally, the line-drawing escape sequences\ndraw a radical extender (a form of overline) and an underline from\nthe drawing position to the position coresponding to beginning of\nthe input line. The drawing position returns to just after the\nright-hand box rule because the lengths of the drawn lines are\nnegative, as noted above.\n\n-- Escape sequence: \\L'l'\n-- Escape sequence: \\L'lc'\nDraw a vertical line of length L from the drawing position.\nDownward motion is positive. The default scaling unit is 'v'. The\ndefault character is the box rule, '\\[br]'. As with vertical\nmotion escape sequences, text processing continues where the line\nends. '\\L' is otherwise similar to '\\l'.\n\n$ nroff < This is a\n=> |\n=> |\n=> |test.\n\nWhen writing text, the drawing position is at the text baseline;\nrecall *note Page Geometry::.\n\nThe '\\D' escape sequence provides \"drawing commands\" that direct the\noutput device to render geometrical objects rather than glyphs.", "subsections": [] }, "Specific devices may support only a subset, or may feature additional": { "content": "ones; consult the man page for the output driver in use. Terminal\ndevices in particular implement almost none. *Note Graphics Commands::.\n\nRendering starts at the drawing position; when finished, the drawing\nposition is left at the rightmost point of the object, even for closed\nfigures, except where noted. GNU 'troff' draws stroked (outlined)\nobjects with the stroke color, and shades filled ones with the fill\ncolor. *Note Colors::. Coordinates H and V are horizontal and vertical\nmotions relative to the drawing position or previous point in the\ncommand. The default scaling unit for horizontal measurements (and\ndiameters of circles) is 'm'; for vertical ones, 'v'.\n\nCircles, ellipses, and polygons can be drawn filled or stroked.", "subsections": [] }, "These are independent properties; if you want a filled, stroked figure,": { "content": "you must draw the same figure twice using each drawing command. A\nfilled figure is always smaller than an outlined one because the former\nis drawn only within its defined area, whereas strokes have a line\nthickness (set with '\\D't'').\n\n\\h'1i'\\v'1i'\\\n\\# increase line thickness\n\\Z'\\D't 5p''\\\n\\# draw stroked (unfilled) polygon\n\\Z'\\D'p 3 3 -6 0''\\\n\\# draw filled (solid) polygon\n\\Z'\\D'P 3 3 -6 0''\n\n-- Escape sequence: \\D'command argument ...'\nDrawing command escape sequence parameters begin with an ordinary\ncharacter, COMMAND, selecting the type of object to be drawn,\nfollowed by ARGUMENTs whose meaning is determined by COMMAND.\n\n'\\D'~ H1 V1 ... HN VN''\nDraw a B-spline to each point in sequence, leaving the drawing\nposition at (HN, VN).\n\n'\\D'a HC VC H V''\nDraw a circular arc centered at (HC, VC) counterclockwise from\nthe drawing position to a point (H, V) relative to the center.\n(1) (*note Drawing Geometric Objects-Footnote-1::)\n\n'\\D'c D''\nDraw a circle of diameter D with its leftmost point at the\ndrawing position.\n\n'\\D'C D''\nAs '\\D'C ...'', but the circle is filled.\n\n'\\D'e H V''\nDraw an ellipse of width H and height V with its leftmost\npoint at the drawing position.\n\n'\\D'E X Y''\nAs '\\D'e ...'', but the ellipse is filled.\n\n'\\D'l DX DY''\nDraw line from the drawing position to (H, V).\n\nThe following is a macro for drawing a box around a text\nargument; for simplicity, the box margin is a fixed at 0.2m.\n\n.de TEXTBOX\n. nr @wd \\w'\\\\$1'\n\\h'.2m'\\\n\\h'-.2m'\\v'(.2m - \\\\n[rsb]u)'\\\n\\D'l 0 -(\\\\n[rst]u - \\\\n[rsb]u + .4m)'\\\n\\D'l (\\\\n[@wd]u + .4m) 0'\\\n\\D'l 0 (\\\\n[rst]u - \\\\n[rsb]u + .4m)'\\\n\\D'l -(\\\\n[@wd]u + .4m) 0'\\\n\\h'.2m'\\v'-(.2m - \\\\n[rsb]u)'\\\n\\\\$1\\\n\\h'.2m'\n..\n\nThe argument is measured with the '\\w' escape sequence. Its\nwidth is stored in register '@wd'. '\\w' also sets the\nregisters 'rst' and 'rsb'; these contain its maximum vertical\nextents of the argument. Then, four lines are drawn to form a\nbox, offset by the box margin.\n\n'\\D'p H1 V1 ... HN VN''\nDraw polygon with vertices at drawing position and each point\nin sequence. GNU 'troff' closes the polygon by drawing a line\nfrom (HN, VN) back to the initial drawing position.\nAfterward, the drawing position is left at (HN, VN).\n\n'\\D'P DX1 DY1 DX2 DY2 ...''\nAs '\\D'P ...'', but the polygon is filled.\n\nThe following macro is like the '\\D'l'' example, but shades\nthe box. We draw the box before writing the text because\ncolors in GNU 'troff' have no transparency; in othe opposite\norder, the filled polygon would occlude the text.\n\n.de TEXTBOX\n. nr @wd \\w'\\\\$1'\n\\h'.2m'\\\n\\h'-.2m'\\v'(.2m - \\\\n[rsb]u)'\\\n\\M[lightcyan]\\\n\\D'P 0 -(\\\\n[rst]u - \\\\n[rsb]u + .4m) \\\n(\\\\n[@wd]u + .4m) 0 \\\n0 (\\\\n[rst]u - \\\\n[rsb]u + .4m) \\\n-(\\\\n[@wd]u + .4m) 0'\\\n\\h'.2m'\\v'-(.2m - \\\\n[rsb]u)'\\\n\\M[]\\\n\\\\$1\\\n\\h'.2m'\n..\n\n'\\D't N''\nSet the stroke thickness of geometric objects to N basic\nunits. A zero N selects the minimal supported thickness. A\nnegative N selects a thickness proportional to the type size;\nthis is the default.\n\nIn a hazy penumbra between text rendering and drawing commands we\nlocate the bracket-building escape sequence, '\\b'. It can assemble\napparently large glyphs by vertically stacking ordinary ones.\n\n-- Escape sequence: \\b'contents'\nPile and center a sequence of glyphs vertically on the output line.\n\"Piling\" stacks glyphs corresponding to each character in CONTENTS,\nread from left to right, and placed from top to bottom. GNU\n'troff' separates the glyphs vertically by 1m, and the pile itself\nis centered 0.5m above the text baseline. The horizontal drawing\nposition is then advanced by the width of the widest glyph in the\npile.\n\nThis rather inflexible positioning algorithm doesn't work with the\n'dvi' output device since its bracket pieces vary in height.\nInstead, use the 'geqn' preprocessor.\n\n*note Manipulating Spacing:: describes how to adjust the vertical\nspacing of the output line with the '\\x' escape sequence.\n\nThe application of '\\b' that lends its name is construction of\nbrackets, braces, and parentheses when typesetting mathematics. We\nmight construct a large opening (left) brace as follows.\n\n\\b'\\[lt]\\[bv]\\[lk]\\[bv]\\[lb]'\n\nSee 'groffchar(7)' for a list of special character identifiers.\n", "subsections": [] }, "File: groff.info, Node: Deferring Output, Next: Traps, Prev: Drawing Geometric Objects, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.27 Deferring Output", "content": "A few 'roff' language elements are generally not used in simple\ndocuments, but arise as page layouts become more sophisticated and\ndemanding. \"Environments\" collect formatting parameters like line\nlength and typeface. A \"diversion\" stores formatted output for later\nuse. A \"trap\" is a condition on the input or output, tested\nautomatically by the formatter, that is associated with a macro, causing\nit to be called when that condition is fulfilled.\n\nFootnote support often exercises all three of the foregoing features.\nA simple implementation might work as follows. A pair of macros is\ndefined: one starts a footnote and the other ends it. The author calls\nthe first macro where a footnote marker is desired. The macro\nestablishes a diversion so that the footnote text is collected at the\nplace in the body text where its corresponding marker appears. An\nenvironment is created for the footnote so that it is set at a smaller\ntypeface. The footnote text is formatted in the diversion using that\nenvironment, but it does not yet appear in the output. The document\nauthor calls the footnote end macro, which returns to the previous\nenvironment and ends the diversion. Later, after much more body text in\nthe document, a trap, set a small distance above the page bottom, is\nsprung. The macro called by the trap draws a line across the page and\nemits the stored diversion. Thus, the footnote is rendered.\n\nDiversions and traps make the text formatting process non-linear." } ] }, "Let us imagine a set of text lines or paragraphs labelled 'A', 'B', and": { "content": "so on. If we set up a trap that produces text 'T' (as a page footer,\nsay), and we also use a diversion to store the formatted text 'D', then\na document with input text in the order 'A B C D E F' might render as 'A\nB C E T F'. The diversion 'D' will never be output if we do not call\nfor it.\n\nEnvironments of themselves are not a source of non-linearity in\ndocument formatting: environment switches have immediate effect. One\ncould always write a macro to change as many formatting parameters as\ndesired with a single convenient call. But because diversions can be\nnested and macros called by traps that are sprung by other trap-called\nmacros, they may be called upon in varying contexts. For example,\nconsider a page header that is always to be set in Helvetica. A\ndocument that uses Times for most of its body text, but Courier for\ndisplayed code examples, poses a challenge if a page break occurs in the\nmiddle of a code display; if the header trap assumes that the \"previous\nfont\" is always Times, the rest of the example will be formatted in the\nwrong typeface. One could carefully save all formatting parameters upon\nentering the trap and restore them upon leaving it, but this is verbose,\nerror-prone, and not future-proof as the 'groff' language develops.\nEnvironments save us considerable effort.\n", "subsections": [] }, "File: groff.info, Node: Traps, Next: Diversions, Prev: Deferring Output, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.28 Traps", "content": "\"Traps\" are locations in the output or conditions on the input that,\nwhen reached or fulfilled, call a specified macro. These traps can\noccur at a given location on the page, at a given location in the\ncurrent diversion (together, these are known as vertical position\ntraps), at a blank line, at a line with leading space characters, after\na quantity of input lines, or at the end of input. Macros called by\ntraps are passed no arguments. Setting a trap is also called \"planting\"\none. It is said that a trap is \"sprung\" if its condition is fulfilled.\n\n* Menu:\n\n* Vertical Position Traps::\n* Diversion Traps::\n* Input Line Traps::\n* Blank Line Traps::\n* Leading Space Traps::\n* End-of-input Traps::\n" } ] }, "File: groff.info, Node: Vertical Position Traps, Next: Page Location Traps, Prev: Traps, Up: Traps": { "content": "A \"vertical position trap\" calls a macro when the formatter's vertical\ndrawing position reaches or passes, in the downward direction, a certain\nlocation on the output page or in a diversion. Its applications include\nsetting page headers and footers, body text in multiple columns, and\nfootnotes.\n\n-- Request: .vpt [flag]\n-- Register: \\n[.vpt]\nEnable vertical position traps if FLAG is non-zero or absent;\ndisable them otherwise. Vertical position traps are those set by\nthe 'wh' request or by 'dt' within a diversion. The parameter that\ncontrols whether vertical position traps are enabled is global.\nInitially, vertical position traps are enabled. The current value\nis stored in the '.vpt' read-only register.\n\nA page can't be ejected if 'vpt' is set to zero; see *note The\nImplicit Page Trap::.\n\n* Menu:\n\n* Page Location Traps::\n* The Implicit Page Trap::\n* Diversion Traps::\n", "subsections": [] }, "File: groff.info, Node: Page Location Traps, Next: The Implicit Page Trap, Prev: Vertical Position Traps, Up: Vertical Position Traps": { "content": "5.28.1.1 Page Location Traps\n............................\n\nA \"page location trap\" is a vertical position trap that applies to the\npage; that is, to undiverted output. Many can be present; manage them\nwith the 'wh' and 'ch' requests.\n\n-- Request: .wh dist [name]\nPlant macro NAME as page location trap at DIST. The default\nscaling unit is 'v'. Non-negative values for DIST set the trap\nrelative to the top of the page; negative values set the trap\nrelative to the bottom of the page. It is not possible to plant a\ntrap less than one basic unit from the page bottom: a DIST of '-0'\nis interpreted as '0', the top of the page.(1) (*note Page\nLocation Traps-Footnote-1::) An existing visible trap (see below)\nat DIST is removed; this is 'wh''s sole function if NAME is\nmissing.\n\nA trap is sprung only if it is \"visible\", meaning that its location\nis reachable on the page(2) (*note Page Location\nTraps-Footnote-2::) and it is not hidden by another trap at the\nsame location already planted there.\n\nA macro package might set headers and footers as follows; this\nexample configures vertical margins of one inch to the body text,\nand one half-inch to the titles. Observe the use of the no-break\ncontrol character with 'sp' request to position our text baselines,\nand the page number character '%' used with the 'tl' request.\n\n.\\\" hdfo.roff\n.de hd \\\" page header\n' sp .5i\n' tl '\\\\*(Ti''\\\\*(Da' \\\" title and date strings\n' sp .5i\n..\n.de fo \\\" page footer\n' sp .5i\n. tl ''%''\n. bp\n..\n.wh 0 hd \\\" trap at top of the page\n.wh -1i fo \\\" trap 1 inch from bottom\n\nTo use these traps, copy the above (or load it from a file with the\n'so' or 'mso' requests), then set up the strings it uses.\n\n.so hdfo.roff\n.ds Ti Final Report\\\"\n.ds Da 21 May 2023\\\"\n.ti\nOn 5 August of last year,\nthis committee tasked me with the investigation of the\nCFIT (controlled flight into terrain) incident of\n.\\\" ...and so on...\n\nA trap above the top or at or below the bottom of the page can be\nmade visible by either moving it into the page area or increasing\nthe page length so that the trap is on the page. Negative trap\nvalues always use the current page length; they are not converted\nto an absolute vertical position. We can use the 'ptr' request to\ndump our page location traps to the standard error stream (*note\nDebugging::). Their positions are reported in basic units; an\n'nroff' device example follows.\n\n.pl 5i\n.wh -1i xx\n.ptr\nerror-> xx -240\n.pl 100i\n.ptr\nerror-> xx -240\n\nIt is possible to have more than one trap at the same location\n(although only one at a time can be visible); to achieve this, the\ntraps must be defined at different locations, then moved to the\nsame place with the 'ch' request. In the following example, the\nmany empty lines caused by the 'bp' request are not shown in the\noutput.\n\n.de a\n. nop a\n..\n.de b\n. nop b\n..\n.de c\n. nop c\n..\n.\n.wh 1i a\n.wh 2i b\n.wh 3i c\n.bp\n=> a b c\n.ch b 1i\n.ch c 1i\n.bp\n=> a\n.ch a 0.5i\n.bp\n=> a b\n\n-- Register: \\n[.t]\nThe read-only register '.t' holds the distance to the next vertical\nposition trap. If there are no traps between the current position\nand the bottom of the page, it contains the distance to the page\nbottom. Within a diversion, in the absence of a diversion trap,\nthis distance is the largest representable integer in basic\nunits--effectively infinite.\n\n-- Request: .ch name [dist]\nChange the location of a trap by moving macro NAME to new location\nDIST, or by unplanting it altogether if DIST is absent. The\ndefault scaling unit is 'v'. Parameters to 'ch' are specified in\nthe opposite order from 'wh'. If NAME is the earliest planted\nmacro of multiple traps at the same location, (re)moving it from\nthat location exposes the macro next least recently planted at the\nsame place.(3) (*note Page Location Traps-Footnote-3::)\n\nChanging a trap's location is useful for building up footnotes in a\ndiversion to allow more space at the bottom of the page for them.\n\nThe same macro can be installed simultaneously at multiple locations;\nhowever, only the earliest-planted instance--that has not yet been\ndeleted with 'wh'--will be moved by 'ch'. The following example (using\nan 'nroff' device) illustrates this behavior. Blank lines have been\nelided from the output.\n\n.de T\nTrap sprung at \\\\n(nlu.\n.br\n..\n.wh 1i T\n.wh 2i T\nfoo\n.sp 11i\n.bp\n.ch T 4i\nbar\n.sp 11i\n.bp\n.ch T 5i\nbaz\n.sp 11i\n.bp\n.wh 5i\n.ch T 6i\nqux\n.sp 11i\n=> foo\n=> Trap sprung at 240u.\n=> Trap sprung at 480u.\n=> bar\n=> Trap sprung at 480u.\n=> Trap sprung at 960u.\n=> baz\n=> Trap sprung at 480u.\n=> Trap sprung at 1200u.\n=> qux\n=> Trap sprung at 1440u.\n\n-- Register: \\n[.ne]\nThe read-only register '.ne' contains the amount of space that was\nneeded in the last 'ne' request that caused a trap to be sprung; it\nis useful in conjunction with the '.trunc' register. *Note Page\nControl::. Since the '.ne' register is set only by traps, it\ndoesn't make sense to interpolate it outside of macros called by\ntraps.\n\n-- Register: \\n[.trunc]\nA read-only register containing the amount of vertical space\ntruncated from an 'sp' request by the most recently sprung vertical\nposition trap, or, if the trap was sprung by an 'ne' request, minus\nthe amount of vertical motion produced by the 'ne' request. In\nother words, at the point a trap is sprung, it represents the\ndifference of what the vertical position would have been but for\nthe trap, and what the vertical position actually is. Since the\n'.trunc' register is set only by traps, it doesn't make sense to\ninterpolate it outside of macros called by traps.\n\n-- Register: \\n[.pe]\nThis Boolean-valued, read-only register interpolates 1 while a page\nis being ejected, and 0 otherwise.\n\nIn the following example, we plant the same trap at the top and the\nbottom of the page. We also make the trap report its name and the\nvertical drawing position.\n\n.de T\n.tm \\\\$0: page \\\\n%, nl=\\\\n[nl] .pe=\\\\n[.pe]\n..\n.ll 46n\n.wh 0 T\n.wh -1v T\nThose who can make you believe absurdities can make you\ncommit atrocities. \\[em] Voltaire\nerror-> T: page 1, nl=0 .pe=0\nerror-> T: page 1, nl=2600 .pe=1\n=> Those who can make you believe absurdities can\n=> make you commit atrocities. -- Voltaire\n\nWhen designing macros, keep in mind that diversions and traps do\nnormally interact. For example, if a trap calls a header macro (while\noutputting a diversion) that tries to change the font on the current\npage, the effect is not visible before the diversion has completely been\nprinted (except for input protected with '\\!' or '\\?') since the data in\nthe diversion is already formatted. In most cases, this is not the\nexpected behaviour.\n", "subsections": [] }, "File: groff.info, Node: The Implicit Page Trap, Next: Diversion Traps, Prev: Page Location Traps, Up: Vertical Position Traps": { "content": "5.28.1.2 The Implicit Page Trap\n...............................\n", "subsections": [] }, "If, after starting GNU 'troff' without loading a macro package, you use": { "content": "the 'ptr' request to dump a list of the active traps to the standard\nerror stream,(1) (*note The Implicit Page Trap-Footnote-1::) nothing is\nreported. Yet the '.t' register will report a steadily decreasing value\nwith every output line your document produces, and once the value of\n'.t' gets to within '.V' of zero, you will notice that something\ntrap-like happens--the page is ejected, a new one begins, and the value\nof '.t' becomes large once more.\n\nThis \"implicit page trap\" always exists in the top-level\ndiversion;(2) (*note The Implicit Page Trap-Footnote-2::) it works like\na trap in some ways but not others. Its purpose is to eject the current\npage and start the next one. It has no name, so it cannot be moved or\ndeleted with 'wh' or 'ch' requests. You cannot hide it by placing\nanother trap at its location, and can move it only by redefining the\npage length with 'pl'. Its operation is suppressed when vertical page\ntraps are disabled with GNU 'troff''s 'vpt' request.\n", "subsections": [] }, "File: groff.info, Node: Diversion Traps, Next: Input Line Traps, Prev: The Implicit Page Trap, Up: Vertical Position Traps": { "content": "5.28.1.3 Diversion Traps\n........................\n\nA diversion is not formatted in the context of a page, so it lacks page\nlocation traps; instead it can have a \"diversion trap\". There can exist\nat most one such vertical position trap per diversion.\n\n-- Request: .dt [dist name]\nSet a trap within a diversion at location DIST, which is\ninterpreted relative to diversion rather than page boundaries. If\ninvoked with fewer than two arguments, any diversion trap in the\ncurrent diversion is removed. The register '.t' works within\ndiversions. It is an error to invoke 'dt' in the top-level\ndiversion. *Note Diversions::.\n", "subsections": [] }, "File: groff.info, Node: Input Line Traps, Next: Blank Line Traps, Prev: Diversion Traps, Up: Traps": { "content": "-- Request: .it [n name]\n-- Request: .itc [n name]\nSet an input line trap, calling macro NAME after processing the\nnext N productive input lines (recall *note Manipulating Filling\nand Adjustment::). Any existing input line trap in the environment\nis replaced. Without arguments, 'it' and 'itc' clear any input\nline trap that has not yet sprung.\n\nConsider a macro '.ST S N' which sets the next N input lines in the\nfont style S.\n\n.de ST \\\" Use style $1 for next $2 text lines.\n. it \\\\$2 ES\n. ft \\\\$1\n..\n.de ES \\\" end ST\n. ft R\n..\n.ST I 1\noblique\nface\n.ST I 1\noblique\\c\nface\n=> oblique face obliqueface (second \"face\" upright)\n\nUnlike the 'ce' and 'rj' requests, 'it' counts lines interrupted\nwith the '\\c' escape sequence separately (*note Line\nContinuation::); 'itc' does not. To see the difference, let's\nchange the previous example to use 'itc' instead.\n\n...\n. itc \\\\$2 ES\n...\n=> oblique face obliqueface (second \"face\" oblique)\n\nYou can think of the 'ce' and 'rj' requests as implicitly creating\nan input line trap with 'itc' that schedules a break when the trap\nis sprung.\n\n.de BR\n. br\n. internal: disable centering-without-filling\n..\n.\n.de ce\n. if \\\\n[.br] .br\n. itc \\\\$1 BR\n. internal: enable centering-without-filling\n..\n\nLet us consider in more detail the sorts of input lines that are or\nare not \"productive\".\n\n.de Trap\nTRAP SPRUNG\n..\n.de Mac\n.if r a \\l'5n'\n..\n.it 2 Trap\n.\nfoo\n.Mac\nbar\nbaz\n.it 1 Trap\n.sp \\\" moves, but does not write or draw\nqux\n.itc 1 Trap\n\\h'5n'\\c \\\" moves, but does not write or draw\njat\n\nWhen 'Trap' gets called depends on whether the 'a' register is\ndefined; the control line with the 'if' request may or may not\nproduce written output. We also see that the spacing request 'sp',\nwhile certainly affecting the output, does not spring the input\nline trap. Similarly, the horizontal motion escape sequence '\\h'\nalso affected the output, but was not \"written\". Observe that we\nhad to follow it with '\\c' and use 'itc' to prevent the newline at\nthe end of the text line from causing a word break, which, like an\nordinary space character, counts as written output.\n\n$ groff -Tascii input-trap-example.groff\n=> foo bar TRAP SPRUNG baz\n=>\n=> qux TRAP SPRUNG jat TRAP SPRUNG\n$ groff -Tascii -ra1 input-trap-example.groff\n=> foo TRAP SPRUNG bar baz\n=>\n=> qux TRAP SPRUNG jat TRAP SPRUNG\n\nInput line traps are associated with the environment (*note", "subsections": [] }, "Environments::); switching to another environment suspends the current": { "content": "input line trap, and going back resumes it, restoring the count of\nqualifying lines enumerated in that environment.\n", "subsections": [] }, "File: groff.info, Node: Blank Line Traps, Next: Leading Space Traps, Prev: Input Line Traps, Up: Traps": { "content": "-- Request: .blm [name]\nSet a blank line trap, calling the macro NAME when GNU 'troff'\nencounters a blank line in an input file, instead of the usual\nbehavior (*note Breaking::). A line consisting only of spaces is\nalso treated as blank and subject to this trap. If no argument is\nsupplied, the default blank line behavior is (re-)established.\n", "subsections": [] }, "File: groff.info, Node: Leading Space Traps, Next: End-of-input Traps, Prev: Blank Line Traps, Up: Traps": { "content": "-- Request: .lsm [name]\n-- Register: \\n[lsn]\n-- Register: \\n[lss]\nSet a leading space trap, calling the macro NAME when GNU 'troff'\nencounters leading spaces in an input line; the implicit line break\nthat normally happens in this case is suppressed. If no argument\nis supplied, the default leading space behavior is (re-)established\n(*note Breaking::).\n\nThe count of leading spaces on an input line is stored in register\n'lsn', and the amount of corresponding horizontal motion in\nregister 'lss', irrespective of whether a leading space trap is\nset. When it is, the leading spaces are removed from the input\nline, and no motion is produced before calling NAME.\n", "subsections": [] }, "File: groff.info, Node: End-of-input Traps, Prev: Leading Space Traps, Up: Traps": { "content": "-- Request: .em [name]\nSet a trap at the end of input, calling macro NAME after the last\nline of the last input file has been processed. If no argument is\ngiven, any existing end-of-input trap is removed.\n\nFor example, if the document had to have a section at the bottom of\nthe last page for someone to approve it, the 'em' request could be\nused.\n\n.de approval\n\\c\n. ne 3v\n. sp (\\\\n[.t]u - 3v)\n. in +4i\n. lc\n. br\nApproved:\\t\\a\n. sp\nDate:\\t\\t\\a\n..\n.\n.em approval\n\nThe '\\c' in the above example needs explanation. For historical\nreasons (compatibility with AT&T 'troff'), the end-of-input macro\nexits as soon as it causes a page break if no partially collected\nline remains.(1) (*note End-of-input Traps-Footnote-1::)\n\nLet us assume that there is no '\\c' in the above 'approval' macro,\nthat the page is full, and last output line has been broken with,\nsay, a 'br' request. Because there is no more room, a 'ne' request\nat this point causes a page ejection, which in turn makes 'troff'\nexit immediately as just described. In most situations, this is\nnot desired; people generally want to format the input after 'ne'.\n\nTo force processing of the whole end-of-input macro independently\nof this behavior, it is thus advisable to (invisibly) ensure the\nexistence of a partially collected line ('\\c') whenever there is a\nchance that a page break can happen. In the above example,\ninvoking the 'ne' request ensures that there is room for the\nsubsequent formatted output on the same page, so we need insert\n'\\c' only once.\n\nThe next example shows how to append three lines, then start a new\npage unconditionally. Since '.ne 1' doesn't give the desired\neffect--there is always one line available or we are already at the\nbeginning of the next page--we temporarily increase the page length\nby one line so that we can use '.ne 2'.\n\n.de EM\n.pl +1v\n\\c\n.ne 2\nline one\n.br\n\\c\n.ne 2\nline two\n.br\n\\c\n.ne 2\nline three\n.br\n.pl -1v\n\\c\n'bp\n..\n.em EM\n\nThis specific feature affects only the first potential page break\ncaused by the end-of-input macro; further page breaks emitted by\nthe macro are handled normally.\n\nAnother possible use of the 'em' request is to make GNU 'troff'\nemit a single large page instead of multiple pages. For example,\none may want to produce a long plain text file for reading in a\nterminal or emulator without page footers and headers interrupting\nthe body of the document. One approach is to set the page length\nat the beginning of the document to a very large value to hold all\nthe text,(2) (*note End-of-input Traps-Footnote-2::) and\nautomatically adjust it to the exact height of the document after\nthe text has been output.\n\n.de adjust-page-length\n. br\n. pl \\\\n[nl]u \\\" \\n[nl]: current vertical position\n..\n.\n.de single-page-mode\n. pl 99999\n. em adjust-page-length\n..\n.\n.\\\" Activate the above code if configured.\n.if \\n[do-continuous-rendering] \\\n. single-page-mode\n\nSince only one end-of-input trap exists and another macro package\nmay already use it, care must be taken not to break the mechanism.\nA simple solution would be to append the above macro to the macro\npackage's end-of-input macro using the 'am' request.\n", "subsections": [] }, "File: groff.info, Node: Diversions, Next: Punning Names, Prev: Traps, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.29 Diversions", "content": "" } ] }, "In 'roff' systems it is possible to format text as if for output, but": { "content": "instead of writing it immediately, one can \"divert\" the formatted text\ninto a named storage area. It is retrieved later by specifying its name\nafter a control character. The same name space is used for such\ndiversions as for strings and macros; see *note Identifiers::. Such\ntext is sometimes said to be \"stored in a macro\", but this coinage\nobscures the important distinction between macros and strings on one\nhand and diversions on the other; the former store unformatted input\ntext, and the latter capture formatted output. Diversions also do not\ninterpret arguments. Applications of diversions include \"keeps\"\n(preventing a page break from occurring at an inconvenient place by\nforcing a set of output lines to be set as a group), footnotes, tables\nof contents, and indices. For orthogonality it is said that GNU 'troff'\nis in the \"top-level diversion\" if no diversion is active (that is,\nformatted output is being \"diverted\" immediately to the output device).\n\nDereferencing an undefined diversion will create an empty one of that\nname and cause a warning in category 'mac' to be emitted. *Note", "subsections": [] }, "Warnings::, for information about the enablement and suppression of": { "content": "warnings. A diversion does not exist for the purpose of testing with\nthe 'd' conditional operator until its initial definition ends (*note", "subsections": [] }, "Operators in Conditionals::). The following requests are used to create": { "content": "and alter diversions.\n\n-- Request: .di [name]\n-- Request: .da [name]\nStart collecting formatted output in a diversion called NAME. The\n'da' request appends to a diversion called NAME, creating it if\nnecessary. If NAME already exists as an alias, the target of the\nalias is replaced or appended to; recall *note Strings::. The\npending output line is diverted as well. Switching to another\nenvironment (with the 'ev' request) before invoking 'di' or 'da'\navoids including any pending output line in the diversion; see\n*note Environments::.\n\nInvoking 'di' or 'da' without an argument stops diverting output to\nthe diversion named by the most recent corresponding request. If\n'di' or 'da' is called without an argument when there is no current\ndiversion, a warning in category 'di' is produced. *Note\nWarnings::, for information about the enablement and suppression of\nwarnings.\n\nBefore the diversion.\n.di yyy\nIn the diversion.\n.br\n.di\nAfter the diversion.\n.br\n=> After the diversion.\n.yyy\n=> Before the diversion. In the diversion.\n\nGNU 'troff' supports \"box\" requests to exclude a partially collected\nline from a diversion, as this is often desirable.\n\n-- Request: .box [name]\n-- Request: .boxa [name]\nDivert (or append) output to NAME, similarly to the 'di' and 'da'\nrequests, respectively. Any pending output line is not included\nin the diversion. Without an argument, stop diverting output; any\npending output line inside the diversion is discarded.\n\nBefore the box.\n.box xxx\nIn the box.\n.br\nHidden treasure.\n.box\nAfter the box.\n.br\n=> Before the box. After the box.\n.xxx\n=> In the box.\n\nApart from pending output line inclusion and the request names that\npopulate them, boxes are handled exactly as diversions are. All of the\nfollowing 'groff' language elements can be used with them\ninterchangeably.\n\n-- Register: \\n[.z]\n-- Register: \\n[.d]\nDiversions may be nested. The read-only string-valued register\n'.z' contains the name of the current diversion. The read-only\nregister '.d' contains the current vertical place in the diversion.\nIf the input text is not being diverted, '.d' reports the same\nlocation as the register 'nl'.\n\n-- Register: \\n[.h]\nThe read-only register '.h' stores the \"high-water mark\" on the\ncurrent page or in the current diversion. It corresponds to the\ntext baseline of the lowest line on the page.(1) (*note\nDiversions-Footnote-1::)\n\n.tm .h==\\n[.h], nl==\\n[nl]\n=> .h==0, nl==-1\nThis is a test.\n.br\n.sp 2\n.tm .h==\\n[.h], nl==\\n[nl]\n=> .h==40, nl==120\n\nAs implied by the example, vertical motion does not produce text\nbaselines and thus does not increase the value interpolated by\n'\\n[.h]'.\n\n-- Register: \\n[dn]\n-- Register: \\n[dl]\nAfter completing a diversion, the writable registers 'dn' and 'dl'\ncontain its vertical and horizontal sizes. Only the lines just\nprocessed are counted: for the computation of 'dn' and 'dl', the\nrequests 'da' and 'boxa' are handled as if 'di' and 'box' had been\nused, respectively--lines that have been already stored in the\ndiversion (box) are not taken into account.\n\n.\\\" Center text both horizontally and vertically.\n.\\\" Macro .(c starts centering mode; .)c terminates it.\n.\n.\\\" Disable the escape character with .eo so that we\n.\\\" don't have to double backslashes on the \"\\n\"s.\n.eo\n.de (c\n. br\n. ev (c\n. evc 0\n. in 0\n. nf\n. di @c\n..\n.de )c\n. br\n. ev\n. di\n. nr @s (((\\n[.t]u - \\n[dn]u) / 2u) - 1v)\n. sp \\n[@s]u\n. ce 1000\n. @c\n. ce 0\n. sp \\n[@s]u\n. br\n. fi\n. rr @s\n. rm @c\n..\n.ec\n\n-- Escape sequence: \\!anything\n-- Escape sequence: \\?anything\\?\n\"Transparently\" embed ANYTHING into the current diversion,\npreventing requests, macro calls, and escape sequences from being\ninterpreted when read into a diversion. This is useful for\npreventing them from taking effect until the diverted text is\nactually output. The '\\!' escape sequence transparently embeds\ninput up to and including the end of the line. The '\\?' escape\nsequence transparently embeds input until its own next occurrence.\n\nANYTHING may not contain newlines; use '\\!' by itself to embed\nnewlines in a diversion. The escape sequence '\\?' is also\nrecognized in copy mode and turned into a single internal code; it\nis this code that terminates ANYTHING. Thus the following example\nprints 4.\n\n.nr x 1\n.nf\n.di d\n\\?\\\\?\\\\\\\\?\\\\\\\\\\\\\\\\nx\\\\\\\\?\\\\?\\?\n.di\n.nr x 2\n.di e\n.d\n.di\n.nr x 3\n.di f\n.e\n.di\n.nr x 4\n.f\n\nBoth escape sequences read the data in copy mode.\n\nIf '\\!' is used in the top-level diversion, its argument is\ndirectly embedded into GNU 'troff''s intermediate output. This can\nbe used, for example, to control a postprocessor that processes the\ndata before it is sent to an output driver.\n\nThe '\\?' escape used in the top-level diversion produces no output\nat all; its argument is simply ignored.\n\n-- Request: .output contents\nEmit CONTENTS directly to GNU 'troff''s intermediate output\n(subject to copy mode interpretation); this is similar to '\\!' used\nat the top level. An initial neutral double quote in CONTENTS is\nstripped to allow embedding of leading spaces.\n\nThis request can't be used before the first page has started--if\nyou get an error, simply insert '.br' before the 'output' request.\n\nUse with caution! It is normally only needed for mark-up used by a\npostprocessor that does something with the output before sending it\nto the output device, filtering out CONTENTS again.\n\n-- Request: .asciify div\n\"Unformat\" the diversion DIV in a way such that Unicode basic Latin\n(ASCII) characters, characters translated with the 'trin' request,\nspace characters, and some escape sequences, that were formatted\nand diverted into DIV are treated like ordinary input characters\nwhen DIV is reread. Doing so can be useful in conjunction with the\n'writem' request. 'asciify' can be also used for gross hacks; for\nexample, the following sets register 'n' to 1.\n\n.tr @.\n.di x\n@nr n 1\n.br\n.di\n.tr @@\n.asciify x\n.x\n\n'asciify' cannot return all items in a diversion to their source\nequivalent: nodes such as those produced by the '\\N' escape\nsequence will remain nodes, so the result cannot be guaranteed to\nbe a pure string. *Note Copy Mode::. Glyph parameters such as the\ntype face and size are not preserved; use 'unformat' to achieve\nthat.\n\n-- Request: .unformat div\nLike 'asciify', unformat the diversion DIV. However, 'unformat'\nhandles only tabs and spaces between words, the latter usually\narising from spaces or newlines in the input. Tabs are treated as\ninput tokens, and spaces become adjustable again. The vertical\nsizes of lines are not preserved, but glyph information (font, type\nsize, space width, and so on) is retained.\n", "subsections": [] }, "File: groff.info, Node: Punning Names, Next: Environments, Prev: Diversions, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.30 Punning Names", "content": "Macros, strings, and diversions share a name space; recall *note\nIdentifiers::. Internally, the same mechanism is used to store them." } ] }, "You can thus call a macro with string interpolation syntax and vice": { "content": "versa.\n\n.de subject\nTypesetting\n..\n.de predicate\nrewards attention to detail\n..\n\\*[subject] \\*[predicate].\nTruly.\n=> Typesetting\n=> rewards attention to detail Truly.\n\nWhat went wrong? Strings don't contain newlines, but macros do. String\ninterpolation placed a newline at the end of '\\*[subject]', and the next\nthing on the input was a space. Then when '\\*[predicate]' was\ninterpolated, it was followed by the empty request '.' on a line by\nitself. If we want to use macros as strings, we must take interpolation\nbehavior into account.\n\n.de subject\nTypesetting\\\\\n..\n.de predicate\nrewards attention to detail\\\\\n..\n\\*[subject] \\*[predicate].\nTruly.\n=> Typesetting rewards attention to detail. Truly.\n\nBy ending each text line of the macros with an escaped '\\', we get\nthe desired effect (*note Line Continuation::).(1) (*note Punning", "subsections": [] }, "Names-Footnote-1::) What would have happened if we had used only one": { "content": "backslash at a time instead?\n\nInterpolating a string does not hide existing macro arguments. We\ncan also place the escaped newline outside the string interpolation\ninstead of within the string definition. Thus, in a macro, a more\nefficient way of doing\n\n.xx \\\\$@\n\nis\n\n\\\\*[xx]\\\\\n\nThe latter calling syntax doesn't change the value of '\\$0', which is\nthen inherited from the calling macro (*note Parameters::).\n\nDiversions can be also called with string syntax. It is sometimes\nconvenient to copy one-line diversions to a string.\n\n.di xx\nthe\n.ft I\ninterpolation system\n.ft\n.br\n.di\n.ds yy This is a test of \\*(xx\\c\n\\*(yy.\n=> This is a test of the interpolation system.\n", "subsections": [] }, "As the previous example shows, it is possible to store formatted output": { "content": "in strings. The '\\c' escape sequence prevents the subsequent newline\nfrom being interpreted as a break (again, *note Line Continuation::).\n\nCopying multi-output line diversions produces unexpected results.\n\n.di xxx\na funny\n.br\ntest\n.br\n.di\n.ds yyy This is \\*[xxx]\\c\n\\*[yyy].\n=> test This is a funny.\n\nUsually, it is not predictable whether a diversion contains one or\nmore output lines, so this mechanism should be avoided. With AT&T\n'troff', this was the only solution to strip off a final newline from a\ndiversion. Another disadvantage is that the spaces in the copied string\nare already formatted, preventing their adjustment. This can cause ugly\nresults.\n\nA clean solution to this problem is available in GNU 'troff', using\nthe requests 'chop' to remove the final newline of a diversion, and\n'unformat' to make the horizontal spaces adjustable again.\n\n.box xxx\na funny\n.br\ntest\n.br\n.box\n.chop xxx\n.unformat xxx\nThis is \\*[xxx].\n=> This is a funny test.\n\n*Note Gtroff Internals::.\n", "subsections": [] }, "File: groff.info, Node: Environments, Next: Suppressing Output, Prev: Diversions, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.31 Environments", "content": "As discussed in *note Deferring Output::, environments store most of the\nparameters that determine the appearance of text. A default environment\nnamed '0' exists when GNU 'troff' starts up; it is modified by\nformatting-related requests and escape sequences.\n\nYou can create new environments and switch among them. Only one is\ncurrent at any given time. Active environments are managed using a\n\"stack\", a data structure supporting \"push\" and \"pop\" operations. The\ncurrent environment is at the top of the stack. The same environment\nname can be pushed onto the stack multiple times, possibly interleaved\nwith others. Popping the environment stack does not destroy the current\nenvironment; it remains accessible by name and can be made current again\nby pushing it at any time. Environments cannot be renamed or deleted,\nand can only be modified when current. To inspect the environment\nstack, use the 'pev' request; see *note Debugging::.\n\nEnvironments store the following information.\n\n* a partially collected line, if any\n\n* data about the most recently output glyph and line (registers\n'.cdp', '.cht', '.csk', '.n', '.w')\n\n* typeface parameters (size, family, style, height and slant,\ninter-word and inter-sentence space sizes)\n\n* page parameters (line length, title length, vertical spacing, line\nspacing, indentation, line numbering, centering, right-alignment,\nunderlining, hyphenation parameters)\n\n* filling enablement; adjustment enablement and mode\n\n* tab stops; tab, leader, escape, control, no-break control,\nhyphenation, and margin characters\n\n* input line traps\n\n* stroke and fill colors\n\n-- Request: .ev [ident]\n-- Register: \\n[.ev]\nEnter the environment IDENT, which is created if it does not\nalready exist, using the same parameters as for the default\nenvironment used at startup. With no argument, GNU 'troff'\nswitches to the previous environment.\n\nInvoking 'ev' with an argument puts environment IDENT onto the top\nof the environment stack. (If it isn't already present in the\nstack, this is a proper push.) Without an argument, 'ev' pops the\nenvironment stack, making the previous environment current. It is\nan error to pop the environment stack with no previous environment\navailable. The read-only string-valued register '.ev' contains the\nname of the current environment--the one at the top of the stack.\n\n.ev footnote-env\n.fam N\n.ps 6\n.vs 8\n.ll -.5i\n.ev\n\n...\n\n.ev footnote-env\n\\[dg] Observe the smaller text and vertical spacing.\n.ev\n\nWe can familiarize ourselves with stack behavior by wrapping the\n'ev' request with a macro that reports the contents of the '.ev'\nregister to the standard error stream.\n\n.de EV\n. ev \\\\$1\n. tm environment is now \\\\n[.ev]\n..\n.\n.EV foo\n.EV bar\n.EV\n.EV baz\n.EV\n.EV\n.EV\n\nerror-> environment is now foo\nerror-> environment is now bar\nerror-> environment is now foo\nerror-> environment is now baz\nerror-> environment is now foo\nerror-> environment is now 0\nerror-> error: environment stack underflow\nerror-> environment is now 0\n\n-- Request: .evc environment\nCopy the contents of ENVIRONMENT to the current environment.\n\nThe following environment data are not copied.\n\n* a partially collected line, if present;\n\n* the interruption status of the previous input line (due to use\nof the '\\c' escape sequence);\n\n* the count of remaining lines to center, to right-justify, or\nto underline (with or without underlined spaces)--these are\nset to zero;\n\n* the activation status of temporary indentation;\n\n* input line traps and their associated data;\n\n* the activation status of line numbering (which can be\nreactivated with '.nm +0'); and\n\n* the count of consecutive hyphenated lines (set to zero).\n\n-- Register: \\n[.w]\n-- Register: \\n[.cht]\n-- Register: \\n[.cdp]\n-- Register: \\n[.csk]\nThe '\\n[.w]' register contains the width of the last glyph\nformatted in the environment.\n\nThe '\\n[.cht]' register contains the height of the last glyph\nformatted in the environment.\n\nThe '\\n[.cdp]' register contains the depth of the last glyph\nformatted in the environment. It is positive for glyphs extending\nbelow the baseline.\n\nThe '\\n[.csk]' register contains the \"skew\" (how far to the right\nof the glyph's center that GNU 'troff' should place an accent) of\nthe last glyph formatted in the environment.\n\n-- Register: \\n[.n]\nThe '\\n[.n]' register contains the length of the previous output\nline emitted in the environment.\n" } ] }, "File: groff.info, Node: Suppressing Output, Next: Colors, Prev: Environments, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.32 Suppressing Output", "content": "-- Escape sequence: \\O[num]\nSuppress GNU 'troff' output of glyphs and geometric objects. The\nsequences '\\O2', '\\O3', '\\O4', and '\\O5' are intended for internal\nuse by 'grohtml'.\n\n'\\O0'\nDisable the emission of glyphs and geometric objects to the\noutput driver, provided that this sequence occurs at the\noutermost suppression level (see '\\O3' and '\\04' below).\nHorizontal motions corresponding to non-overstruck glyph\nwidths still occur.\n\n'\\O1'\nEnable the emission of glyphs and geometric objects to the\noutput driver, provided that this sequence occurs at the\noutermost suppression level.\n\n'\\O0' and '\\O1' also reset the four registers 'opminx', 'opminy',\n'opmaxx', and 'opmaxy' to -1. These four registers mark the top\nleft and bottom right hand corners of a box encompassing all\nwritten or drawn output.\n\n'\\O2'\nAt the outermost suppression level, enable emission of glyphs\nand geometric objects, and write to the standard error stream\nthe page number and values of the four aforementioned\nregisters encompassing glyphs written since the last\ninterpolation of a '\\O' sequence, as well as the page offset,\nline length, image file name (if any), horizontal and vertical\ndevice motion quanta, and input file name. Numeric values are\nin basic units.\n\n'\\O3'\nBegin a nested suppression level. 'grohtml' uses this\nmechanism to create images of output preprocessed with 'gpic',\n'geqn', and 'gtbl'. At startup, GNU 'troff' is at the\noutermost suppression level. 'pre-grohtml' generates these\nsequences when processing the document, using GNU 'troff' with\nthe 'ps' output device, Ghostscript, and the PNM tools to\nproduce images in PNG format. They start a new page if the\ndevice is not 'html' or 'xhtml', to reduce the number of\nimages crossing a page boundary.\n\n'\\O4'\nEnd a nested suppression level.\n\n'\\O[5PFILE]'\nAt the outermost suppression level, write the name 'file' to\nthe standard error stream at position P, which must be one of\n'l', 'r', 'c', or 'i', corresponding to left, right, centered,\nand inline alignments within the document, respectively. FILE\nis a name associated with the production of the next image.\n\n-- Register: \\n[.O]\nOutput suppression nesting level applied by '\\O3' and '\\O4' escape\nsequences.\n" } ] }, "File: groff.info, Node: I/O, Next: Postprocessor Access, Prev: Suppressing Output, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.33 I/O", "content": "'gtroff' has several requests for including files:\n\n-- Request: .so file\n-- Request: .soquiet file\nReplace the 'so' request's control line with the contents of the\nfile named by the argument, \"sourcing\" it. FILE is sought in the\ndirectories specified by '-I' command-line option. If FILE does\nnot exist, a warning in category 'file' is produced and the request\nhas no further effect. *Note Warnings::, for information about the\nenablement and suppression of warnings.\n\n'so' can be useful for large documents; e.g., allowing each chapter\nof a book to be kept in a separate file. However, files\ninterpolated with 'so' are not preprocessed; to overcome this\nlimitation, see the 'gsoelim(1)' man page.\n\nSince GNU 'troff' replaces the entire control line with the\ncontents of a file, it matters whether 'file' is terminated with a\nnewline or not. Assume that file 'xxx' contains only the word\n'foo' without a trailing newline.\n\n$ printf 'foo' > xxx\n\nThe situation is\n.so xxx\nbar.\n=> The situation is foobar.\n\n'soquiet' works the same way, except that no warning diagnostic is\nissued if FILE does not exist.\n\n-- Request: .pso command\nRead the standard output from the specified COMMAND and include it\nin place of the 'pso' request.\n\nIt is an error to use this request in safer mode, which is the\ndefault. Invoke GNU 'troff' or a front end with the '-U' option to\nenable unsafe mode.\n\nThe comment regarding a final newline for the 'so' request is valid\nfor 'pso' also.\n\n-- Request: .mso file\n-- Request: .msoquiet file\nIdentical to the 'so' and 'soquiet' requests, respectively, except\nthat 'gtroff' searches for the specified FILE in the same\ndirectories as macro files for the '-m' command-line option. If\nthe file name to be included has the form 'NAME.tmac' and it isn't\nfound, these requests try to include 'tmac.NAME' and vice versa.\n\n-- Request: .trf file\n-- Request: .cf file\nTransparently output the contents of FILE. Each line is output as\nif it were preceded by '\\!'; however, the lines are not subject\nto copy mode interpretation. If the file does not end with a\nnewline, 'trf' adds one. Both requests cause a break.\n\nWhen used in a diversion, these requests embed a node (*note Gtroff\nInternals::) in it that, when reread, causes the contents of FILE\nto be transparently copied to the output. In AT&T 'troff', the\ncontents of FILE are immediately copied to the output regardless of\nwhether there is a current diversion; this behaviour is so\nanomalous that it must be considered a bug.\n\nWhile 'cf' copies the contents of FILE completely unprocessed,\n'trf' disallows characters such as NUL that are not valid 'gtroff'\ninput characters (*note Identifiers::).\n\nFor 'cf', within a diversion, \"completely unprocessed\" means that\neach line of a file to be inserted is handled as if it were\npreceded by '\\!\\\\!'.\n\nTo define a macro 'x' containing the contents of file 'f', use\n\n.ev 1\n.di x\n.trf f\n.di\n.ev\n\nThe calls to 'ev' prevent the partially collected output line from\nbecoming part of the diversion (*note Diversions::).\n\n-- Request: .nx [file]\nForce 'gtroff' to continue processing of the file specified as an\nargument. If no argument is given, immediately jump to the end of\nfile.\n\n-- Request: .rd [prompt [arg1 arg2 ...]]\nRead from standard input, and include what is read as though it\nwere part of the input file. Text is read until a blank line is\nencountered.\n\nIf standard input is a TTY input device (keyboard), write PROMPT to\nstandard error, followed by a colon (or send BEL for a beep if no\nargument is given).\n\nArguments after PROMPT are available for the input. For example,\nthe line\n\n.rd data foo bar\n\nwith the input 'This is \\$2.' prints\n\nThis is bar.\n\nUsing the 'nx' and 'rd' requests, it is easy to set up form letters." } ] }, "The form letter template is constructed like this, putting the following": { "content": "lines into a file called 'repeat.let':\n\n.ce\n\\*(td\n.sp 2\n.nf\n.rd\n.sp\n.rd\n.fi\nBody of letter.\n.bp\n.nx repeat.let\n", "subsections": [] }, "When this is run, a file containing the following lines should be": { "content": "redirected in. Requests included in this file are executed as though\nthey were part of the form letter. The last block of input is the 'ex'\nrequest, which tells GNU 'troff' to stop processing. If this were not\nthere, 'troff' would not know when to stop.\n\nTrent A. Fisher\n708 NW 19th Av., #202\nPortland, OR 97209\n\nDear Trent,\n\nLen Adollar\n4315 Sierra Vista\nSan Diego, CA 92103\n\nDear Mr. Adollar,\n\n.ex\n\n-- Request: .pi pipe\nPipe the output of 'gtroff' to the shell command(s) specified by\nPIPE. This request must occur before 'gtroff' has a chance to\nprint anything.\n\nIt is an error to use this request in safer mode, which is the\ndefault. Invoke GNU 'troff' or a front end with the '-U' option to\nenable unsafe mode.\n\nMultiple calls to 'pi' are allowed, acting as a chain. For\nexample,\n\n.pi foo\n.pi bar\n...\n\nis the same as '.pi foo | bar'.\n\nThe intermediate output format of GNU 'troff' is piped to the\nspecified commands. Consequently, calling 'groff' without the '-Z'\noption normally causes a fatal error.\n\n-- Request: .sy cmds\n-- Register: \\n[systat]\nExecute the shell command(s) specified by CMDS. The output is not\nsaved anywhere, so it is up to the user to do so.\n\nIt is an error to use this request in safer mode; this is the\ndefault. Give GNU 'troff' or a front end program the '-U' option\nto enable unsafe mode.\n\nThe following code fragment introduces the current time into a\ndocument.\n\n.sy perl -e 'printf \".nr H %d\\\\n.nr M %d\\\\n.nr S %d\\\\n\",\\\n(localtime(time))[2,1,0]' > /tmp/x\\n[$$]\n.so /tmp/x\\n[$$]\n.sy rm /tmp/x\\n[$$]\n\\nH:\\nM:\\nS\n\nThis works by having the Perl script (run by 'sy') write 'nr'\nrequests that set the registers 'H', 'M', and 'S' to a temporary\nfile. The 'roff' document then reads the temporary file using the\n'so' request.\n\nThe registers 'seconds', 'minutes', and 'hours', initialized at\nstartup of GNU 'troff', should satisfy most requirements. Use the\n'af' request to format their values for output.\n\n.af hours 00\n.af minutes 00\n.af seconds 00\n\\n[hours]:\\n[minutes]:\\n[seconds]\n=> 02:17:54\n\nThe writable register 'systat' contains the return value of the\n'system()' function executed by the last 'sy' request.\n\n-- Request: .open stream file\n-- Request: .opena stream file\nOpen the specified FILE for writing and associates the specified\nSTREAM with it.\n\nThe 'opena' request is like 'open', but if the file exists, append\nto it instead of truncating it.\n\nIt is an error to use these requests in safer mode; this is the\ndefault. Give GNU 'troff' or a front end program the '-U' option\nto enable unsafe mode.\n\n-- Request: .write stream data\n-- Request: .writec stream data\nWrite to the file associated with the specified STREAM. The stream\nmust previously have been the subject of an open request. The\nremainder of the line is interpreted as the 'ds' request reads its\nsecond argument: an initial neutral double quote in CONTENTS is\nstripped to allow embedding of leading spaces, and it is read in\ncopy mode.\n\nThe 'writec' request is like 'write', but only 'write' appends a\nnewline to the data.\n\n-- Request: .writem stream xx\nWrite the contents of the macro or string XX to the file associated\nwith the specified STREAM.\n\nXX is read in copy mode, i.e., already formatted elements are\nignored. Consequently, diversions must be unformatted with the\n'asciify' request before calling 'writem'. Usually, this means a\nloss of information.\n\n-- Request: .close stream\nClose the specified STREAM; the stream is no longer an acceptable\nargument to the 'write' request.\n\nHere a simple macro to write an index entry.\n\n.open idx test.idx\n.\n.de IX\n. write idx \\\\n[%] \\\\$*\n..\n.\n.IX test entry\n.\n.close idx\n\n-- Escape sequence: \\Ve\n-- Escape sequence: \\V(ev\n-- Escape sequence: \\V[env]\nInterpolate the contents of the specified environment variable ENV\n(one-character name E, two-character name EV) as returned by the\nfunction 'getenv(3)'. '\\V' is interpreted even in copy mode (*note\nCopy Mode::).\n", "subsections": [] }, "File: groff.info, Node: Postprocessor Access, Next: Miscellaneous, Prev: I/O, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.34 Postprocessor Access", "content": "" } ] }, "Two escape sequences and two requests enable documents to pass": { "content": "information directly to a postprocessor. These are useful for\nexercising device-specific capabilities that the 'groff' language does\nnot abstract or generalize; examples include the embedding of hyperlinks\nand image files. Device-specific functions are documented in each\noutput driver's man page, such as 'gropdf(1)', 'grops(1)', or\n'grotty(1)'.\n\n-- Request: .device xxx ...\n-- Escape sequence: \\X'xxx ...'\nEmbed all XXX arguments into GNU 'troff' output as parameters to a\ndevice control command 'x X'. The meaning and interpretation of\nsuch parameters is determined by the output driver or other\npostprocessor.\n\nThe 'device' request processes its arguments in copy mode (*note\nCopy Mode::). An initial neutral double quote in CONTENTS is\nstripped to allow embedding of leading spaces. By contrast, within\n'\\X' arguments, the escape sequences '\\&', '\\)', '\\%', and '\\:' are\nignored; '\\' and '\\~' are converted to single space characters;\nand '\\\\' has its escape character stripped. So that the basic\nLatin subset of the Unicode character set(1) (*note Postprocessor\nAccess-Footnote-1::) can be reliably encoded in device control\ncommands, seven special character escape sequences ('\\-', '\\[aq]',\n'\\[dq]', '\\[ga]', '\\[ha]', '\\[rs]', and '\\[ti]',) are mapped to\nbasic Latin characters; see the 'groffchar(7)' man page. For this\ntransformation, character translations and special character\ndefinitions are ignored.(2) (*note Postprocessor\nAccess-Footnote-2::) The use of any other escape sequence in '\\X'\nparameters is normally an error.\n\nIf the 'usecharnamesinspecial' directive appears in the output\ndevice's 'DESC' file, the use of special character escape sequences\nis not an error; they are simply output verbatim (with the\nexception of the seven mapped to Unicode basic Latin characters,\ndiscussed above). 'usecharnamesinspecial' is currently employed\nonly by 'grohtml'.\n\n-- Request: .devicem name\n-- Escape sequence: \\Yn\n-- Escape sequence: \\Y(nm\n-- Escape sequence: \\Y[name]\nThis is approximately equivalent to '\\X'\\*[NAME]'' (one-character\nname N, two-character name NM). However, the contents of the\nstring or macro NAME are not interpreted; also it is permitted for\nNAME to have been defined as a macro and thus contain newlines (it\nis not permitted for the argument to '\\X' to contain newlines).\nThe inclusion of newlines requires an extension to the AT&T 'troff'\noutput format, and confuses drivers that do not know about this\nextension (*note Device Control Commands::).\n\n-- Request: .tag name\n-- Request: .taga name\nReserved for internal use.\n", "subsections": [] }, "File: groff.info, Node: Miscellaneous, Next: Gtroff Internals, Prev: Postprocessor Access, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.35 Miscellaneous", "content": "We document here GNU 'troff' features that fit poorly elsewhere.\n\n-- Request: .nm [start [increment [space [indentation]]]]\n-- Register: \\n[ln]\n-- Register: \\n[.nm]\nBegin (or, with no arguments, cease) numbering output lines. START\nassigns the number of the next output line. Only line numbers\ndivisible by INCREMENT are marked (default: '1'). SPACE configures\nthe horizontal spacing between the number and the text (default:\n'1'). Any given INDENTATION is applied to the numbers (default:\n'0'). The third and fourth arguments are reckoned in numeral\nwidths ('\\0'). START must be non-negative and INCREMENT positive.\n\nThe formatter aligns the number to the right in a width of three\nnumeral spaces plus INDENTATION, then catenates SPACE and the\noutput line. The line length is not reduced. Depending on the\nvalue of the page offset,(1) (*note Miscellaneous-Footnote-1::)\nnumbers wider than the allocated space protrude into the left\nmargin, or shift the output line to the right.\n\nLine numbering parameters corresponding to missing arguments are\nnot altered. After numbering is disabled, '.nm +0' resumes it\nusing the previously active parameters.\n\nThe parameters of 'nm' are associated with the environment (*note\nEnvironments::).\n\nWhile numbering is enabled, the output line number register 'ln' is\nupdated as each line is output, even if no line number is formatted\nwith it because it is being skipped (it is not a multiple of\nINCREMENT) or because numbering is suppressed (see the 'nn' request\nbelow).\n\nThe '.nm' register tracks the enablement status of numbering.\nTemporary suspension of numbering with the 'nn' request does not\nalter its value.\n\n.po 5n\n.ll 44n\nProgramming,\nwhen stripped of all its circumstantial irrelevancies,\n.nm 999 1 1 -4\nboils down to no more and no less than\n.nm +0 3\nvery effective thinking so as to avoid unmastered\n.nn 2\ncomplexity,\nto very vigorous separation of your many\ndifferent concerns.\n.br\n\\(em Edsger Dijkstra\n.sp\n.nm 1 1 1\nThis guy's arrogance takes your breath away.\n.br\n\\(em John Backus\n=> Programming, when stripped of all its cir-\n=> 999 cumstantial irrelevancies, boils down to no\n=> more and no less than very effective think-\n=> ing so as to avoid unmastered complexity, to\n=> very vigorous separation of your many dif-\n=> ferent concerns.\n=> 1002 -- Edsger Dijkstra\n=>\n=> 1 This guy's arrogance takes your breath away.\n=> 2 -- John Backus\n\n-- Request: .nn [skip]\n-- Register: \\n[.nn]\nSuppress numbering of the next SKIP output lines that would\notherwise be numbered. The default is 1. 'nn' can be invoked when\nline numbering is not active; suppression of numbering will take\neffect for SKIP lines once 'nm' enables it.\n\nThe '.nn' register stores the count of output lines still to have\ntheir numbering suppressed.\n\nThis count is associated with the environment (*note\nEnvironments::).\n\nTo test whether the current output line will be numbered, you must\ncheck both the '.nm' and '.nn' registers.\n\n.de is-numbered\n. nop This line\n. ie (\\\\n[.nm] & (1-\\\\n[.nn])) IS\n. el ISN'T\n. nop numbered.\n. br\n..\nTest line numbering.\n.is-numbered\n.nm 1\n.nn 1\n.is-numbered\n.is-numbered\n.nm\n.is-numbered\n=> Test line numbering. This line ISN'T numbered.\n=> This line ISN'T numbered.\n=> 1 This line IS numbered.\n=> This line ISN'T numbered.\n\n-- Request: .mc [margin-character [distance]\nBegin (or, with no arguments, cease) writing a \"margin-character\"\nto the right of each output line. The DISTANCE argument separates\nMARGIN-CHARACTER from the right margin. If absent, the most recent\nvalue is used; the default is 10 points. If an output line exceeds\nthe line length, the margin character is appended to it. No margin\ncharacter is written on lines produced by the 'tl' request.\n\nThe margin character is a property of the output line; the margin\ncharacter last configured when the line is output controls. If the\nmargin character is disabled before an output line breaks, none is\noutput (but see below).\n\nThe margin character is associated with the environment (*note\nEnvironments::).\n\n.ll 5i\n.nf\n.mc \\[br]\nThis paragraph is marked with a margin character.\n.sp\nAs seen above, vertical space isn't thus marked.\n\\&\nAn output line that is present, but empty, is.\n=> This paragraph is marked with a margin character. |\n=>\n=> As seen above, vertical space isn't thus marked. |\n=> |\n=> An output line that is present, but empty, is. |\n\nFor compatibility with AT&T 'troff', a call to 'mc' to set the margin\ncharacter can't be undone immediately; at least one line gets a margin\ncharacter.\n\n.ll 10n\n.nf\n.mc |\n.mc *\n.mc\nfoo\nbar\n=> foo *\n=> bar\n\nThe margin character mechanism is commonly used to annotate changes\nin documents. The 'groff' distribution ships a program, 'gdiffmk', to\nassist with this task.(2) (*note Miscellaneous-Footnote-2::)\n\n-- Request: .psbb file\n-- Register: \\n[llx]\n-- Register: \\n[lly]\n-- Register: \\n[urx]\n-- Register: \\n[ury]\nRetrieve the bounding box of the PostScript image found in FILE,\nwhich must conform to Adobe's \"Document Structuring Conventions\"\n(DSC), locate a '%%BoundingBox' comment, and store the (upper-,\nlower-, -left, -right) values into the registers 'llx', 'lly',\n'urx', and 'ury'. If an error occurs (for example, if no\n'%%BoundingBox' comment is present), the formatter sets these\nregisters to 0.\n\nThe search path for FILE can be controlled with the '-I'\ncommand-line option.\n" } ] }, "File: groff.info, Node: Gtroff Internals, Next: Debugging, Prev: Miscellaneous, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.36 'gtroff' Internals", "content": "'gtroff' processes input in three steps. One or more input characters\nare converted to an \"input token\".(1) (*note Gtroff" } ] }, "Internals-Footnote-1::) Then, one or more input tokens are converted to": { "content": "an \"output node\". Finally, output nodes are converted to the\nintermediate output language understood by all output devices.\n\nActually, before step one happens, 'gtroff' converts certain escape\nsequences into reserved input characters (not accessible by the user);\nsuch reserved characters are used for other internal processing also -\nthis is the very reason why not all characters are valid input. *Note\nIdentifiers::, for more on this topic.\n\nFor example, the input string 'fi\\[:u]' is converted into a character\ntoken 'f', a character token 'i', and a special token ':u' (representing\nu umlaut). Later on, the character tokens 'f' and 'i' are merged to a\nsingle output node representing the ligature glyph 'fi' (provided the\ncurrent font has a glyph for this ligature); the same happens with ':u'.", "subsections": [] }, "All output glyph nodes are 'processed', which means that they are": { "content": "invariably associated with a given font, font size, advance width, etc.", "subsections": [] }, "During the formatting process, 'gtroff' itself adds various nodes to": { "content": "control the data flow.\n\nMacros, diversions, and strings collect elements in two chained\nlists: a list of input tokens that have been passed unprocessed, and a\nlist of output nodes. Consider the following diversion.\n\n.di xxx\na\n\\!b\nc\n.br\n.di\n\nIt contains these elements.\n\nnode list token list element number\n\nline start node -- 1\nglyph node 'a' -- 2\nword space node -- 3\n-- 'b' 4\n-- '\\n' 5\nglyph node 'c' -- 6\nvertical size node -- 7\nvertical size node -- 8\n-- '\\n' 9\n", "subsections": [] }, "Elements 1, 7, and 8 are inserted by 'gtroff'; the latter two (which are": { "content": "always present) specify the vertical extent of the last line, possibly\nmodified by '\\x'. The 'br' request finishes the pending output line,\ninserting a newline input token, which is subsequently converted to a\nspace when the diversion is reread. Note that the word space node has a\nfixed width that isn't adjustable anymore. To convert horizontal space\nnodes back to input tokens, use the 'unformat' request.\n\nMacros only contain elements in the token list (and the node list is\nempty); diversions and strings can contain elements in both lists.\n\nThe 'chop' request simply reduces the number of elements in a macro,\nstring, or diversion by one. Exceptions are \"compatibility save\" and\n\"compatibility ignore\" input tokens, which are ignored. The 'substring'\nrequest also ignores those input tokens.\n\nSome requests like 'tr' or 'cflags' work on glyph identifiers only;\nthis means that the associated glyph can be changed without destroying\nthis association. This can be very helpful for substituting glyphs. In\nthe following example, we assume that glyph 'foo' isn't available by\ndefault, so we provide a substitution using the 'fchar' request and map\nit to input character 'x'.\n\n.fchar \\[foo] foo\n.tr x \\[foo]\n", "subsections": [] }, "Now let us assume that we install an additional special font 'bar' that": { "content": "has glyph 'foo'.\n\n.special bar\n.rchar \\[foo]\n", "subsections": [] }, "Since glyphs defined with 'fchar' are searched before glyphs in special": { "content": "fonts, we must call 'rchar' to remove the definition of the fallback\nglyph. Anyway, the translation is still active; 'x' now maps to the\nreal glyph 'foo'.\n\nMacro and request arguments preserve compatibility mode enablement.\n\n.cp 1 \\\" switch to compatibility mode\n.de xx\n\\\\$1\n..\n.cp 0 \\\" switch compatibility mode off\n.xx caf\\['e]\n=> cafe'\n", "subsections": [] }, "Since compatibility mode is enabled while 'de' is invoked, the macro": { "content": "'xx' enables compatibility mode when it is called. Argument '$1' can\nstill be handled properly because it inherits the compatibility mode\nenablement status that was active at the point where 'xx' was called.\n\nAfter interpolation of the parameters, the compatibility save and\nrestore tokens are removed.\n", "subsections": [] }, "File: groff.info, Node: Debugging, Next: Implementation Differences, Prev: Gtroff Internals, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.37 Debugging", "content": "Standard troff voodoo, just put a power of two backslashes in\nfront of it until it works and if you still have problems add a \\c.\n-- Ron Natalie\n\nGNU 'troff' is not the easiest language to debug, in part thanks to\nits design features of recursive interpolation and the use of\nmulti-stage pipeline processing in the surrounding system. Nevertheless\nthere exist several features useful for troubleshooting.\n\nPreprocessors use the 'lf' request to preserve the identity of the\nline numbers and names of input files. GNU 'troff' emits a variety of\nerror diagnostics and supports several categories of warning; the output\nof these can be selectively suppressed. A trace of the formatter's\ninput processing stack can be emitted when errors or warnings occur by\nmeans of GNU 'troff''s '-b' option, or produced on demand with the\n'backtrace' request. The 'tm' and related requests can be used to emit\ncustomized diagnostic messages or for instrumentation while\ntroubleshooting. The 'ex' and 'ab' requests cause early termination\nwith successful and error exit codes respectively, to halt further\nprocessing when continuing would be fruitless. Examine the state of the\nformatter with requests that write lists of defined names (macros,\nstrings, and diversions), environments, registers, and page location\ntraps to the standard error stream.\n\n-- Request: .lf line [file]\nSet the input line number (and, optionally, the file name) GNU\n'troff' shall use for error and warning messages. LINE is the\ninput line number of the next line. Without an argument, the\nrequest is ignored.\n\n'lf''s primary purpose is to aid the debugging of documents that\nundergo preprocessing. Programs like 'tbl' that transform input in\ntheir own languages into 'roff' requests use it so that any\ndiagnostic messages emitted by 'troff' correspond to the source\ndocument.\n\n-- Request: .tm message\n-- Request: .tm1 message\n-- Request: .tmc message\nSend MESSAGE, which consumes the remainder of the input line and\ncannot contain special characters, to the standard error stream,\nfollowed by a newline. Leading spaces in MESSAGE are ignored.\n\n'tm1' is similar, but recognizes and strips a leading neutral\ndouble quote from MESSAGE to allow the embedding of leading spaces.\n\n'tmc' works as 'tm1', but does not append a newline.\n\n-- Request: .ab [message]\nWrite any MESSAGE to the standard error stream (like 'tm') and then\nabort GNU 'troff'; that is, stop processing and terminate with a\nfailure status.\n\n-- Request: .ex\nExit GNU 'troff'; that is, stop processing and terminate with a\nsuccessful status. To stop processing only the current file, use\nthe 'nx' request; see *note I/O::.\n\nWhen doing something involved, it is useful to leave the debugging\nstatements in the code and have them turned on by a command-line flag.\n\n.if \\n[DB] .tm debugging output\n\nTo activate such statements, use the '-r' option to set the register.\n\ngroff -rDB=1 file\n\nIf it is known in advance that there are many errors and no useful\noutput, GNU 'troff' can be forced to suppress formatted output with the\n'-z' option.\n\n-- Request: .pev\nReport the state of the current environment followed by that of all\nother environments to the standard error stream.\n\n-- Request: .pm\nReport, to the standard error stream, the names of all defined\nmacros, strings, and diversions with their sizes in bytes.\n\n-- Request: .pnr\nReport the names and contents of all currently defined registers to\nthe standard error stream.\n\n-- Request: .ptr\nReport the names and positions of all page location traps to the\nstandard error stream. Empty slots in the list, where a trap has\nbeen planted but subsequently (re)moved, are printed as well.\n\n-- Request: .fl\nInstruct 'gtroff' to flush its output immediately. The intent is\nfor interactive use, but this behaviour is currently not\nimplemented in 'gtroff'. Contrary to Unix 'troff', TTY output is\nsent to a device driver also ('grotty'), making it non-trivial to\ncommunicate interactively.\n\nThis request causes a line break.\n\n-- Request: .backtrace\nWrite the state of the input stack to the standard error stream.\n\nConsider the following in a file 'test'.\n\n.de xxx\n. backtrace\n..\n.de yyy\n. xxx\n..\n.\n.yyy\nerror-> troff: backtrace: 'test':2: macro 'xxx'\nerror-> troff: backtrace: 'test':5: macro 'yyy'\nerror-> troff: backtrace: file 'test':8\n\nThe '-b' option of GNU 'troff' causes a backtrace to be generated\non each error or warning. Some warnings have to be enabled; *Note\nWarnings::.\n\n-- Register: \\n[slimit]\nIf greater than 0, sets the maximum quantity of objects on GNU\n'troff''s internal input stack. If less than or equal to 0, there\nis no limit: recursion can continue until program memory is\nexhausted. The default is 1,000.\n\n-- Request: .warnscale su\nSet the scaling unit used in certain warnings to SU, which can take\nthe values 'u', 'i', 'c', 'p', and 'P'. The default is 'i'.\n\n-- Request: .spreadwarn [limit]\nEmit a 'break' warning if the additional space inserted for each\nspace between words in an output line adjusted to both margins with\n'.ad b' is larger than or equal to LIMIT. A negative value is\ntreated as zero; an absent argument toggles the warning on and off\nwithout changing LIMIT. The default scaling unit is 'm'. At\nstartup, 'spreadwarn' is inactive and LIMIT is 3m.\n\nFor example,\n\n.spreadwarn 0.2m\n\ncauses a warning if 'break' warnings are not suppressed and\n'gtroff' must add 0.2m or more for each inter-word space in a line.\n*Note Warnings::.\n\nGNU 'troff' has command-line options for reporting warnings ('-w')\nand backtraces ('-b') when a warning or an error occurs.\n\n-- Request: .warn [n]\n-- Register: \\n[.warn]\nSelect the categories, or \"types\", of reported warnings. N is the\nsum of the numeric codes associated with each warning category that\nis to be enabled; all other categories are disabled. The\ncategories and their associated codes are listed in *note\nWarnings::. For example, '.warn 0' disables all warnings, and\n'.warn 1' disables all warnings except those about missing glyphs.\nIf no argument is given, all warning categories are enabled.\n\nThe read-only register '.warn' contains the sum of the numeric\ncodes of enabled warning categories.\n\n* Menu:\n\n* Warnings::\n" } ] }, "File: groff.info, Node: Warnings, Prev: Debugging, Up: Debugging": { "content": "", "subsections": [] }, "Warning diagnostics emitted by GNU 'troff' are divided into named,": { "content": "numbered categories. The name associated with each warning category is\nused by the '-w' and '-W' options. Each category is also assigned a\npower of two; the sum of enabled category values is used by the 'warn'\nrequest and the '.warn' register.\n\nWarnings of each category are produced under the following\ncircumstances.\n\n'char'\n'1'\nNo mounted font defines a glyph for the requested character. This\ncategory is enabled by default.\n\n'number'\n'2'\nAn invalid numeric expression was encountered. This category is\nenabled by default. *Note Numeric Expressions::.\n\n'break'\n'4'\nA filled output line could not be broken such that its length was\nless than the output line length '\\n[.l]'. This category is\nenabled by default.\n\n'delim'\n'8'\nThe closing delimiter in an escape sequence was missing or\nmismatched.\n\n'el'\n'16'\nThe 'el' request was encountered with no prior corresponding 'ie'\nrequest. *Note if-else::.\n\n'scale'\n'32'\nA scaling unit inappropriate to its context was used in a numeric\nexpression.\n\n'range'\n'64'\nA numeric expression was out of range for its context.\n\n'syntax'\n'128'\nA self-contradictory hyphenation mode was requested; an empty or\nincomplete numeric expression was encountered; an operand to a\nnumeric operator was missing; an attempt was made to define a\nrecursive, empty, or nonsensical character class; or a 'groff'\nextension conditional expression operator was used while in\ncompatibility mode.\n\n'di'\n'256'\nA 'di', 'da', 'box', or 'boxa' request was invoked without an\nargument when there was no current diversion.\n\n'mac'\n'512'\nAn undefined string, macro, or diversion was used. When such an\nobject is dereferenced, an empty one of that name is automatically\ncreated. So, unless it is later deleted, at most one warning is\ngiven for each.\n\nThis warning is also emitted upon an attempt to move an unplanted\ntrap macro (*note Page Location Traps::). In such cases, the\nunplanted macro is not dereferenced, so it is not created if it\ndoes not exist.\n\n'reg'\n'1024'\nAn undefined register was used. When an undefined register is\ndereferenced, it is automatically defined with a value of 0. So,\nunless it is later deleted, at most one warning is given for each.\n\n'tab'\n'2048'\nA tab character was encountered where a number was expected, or\nappeared in an unquoted macro argument.\n\n'right-brace'\n'4096'\nA right brace escape sequence '\\}' was encountered where a number\nwas expected.\n\n'missing'\n'8192'\nA request was invoked with a mandatory argument absent.\n\n'input'\n'16384'\nAn invalid character occurred on the input stream.\n\n'escape'\n'32768'\nAn unsupported escape sequence was encountered.\n\n'space'\n'65536'\nA space was missing between a request or macro and its argument.\nThis warning is produced when an undefined name longer than two\ncharacters is encountered and the first two characters of the name\nconstitute a defined name. No request is invoked, no macro called,\nand an empty macro is not defined. This category is enabled by\ndefault. It never occurs in compatibility mode.\n\n'font'\n'131072'\nA non-existent font was selected, or the selection was ignored\nbecause a font selection escape sequence was used after the output\nline continuation escape sequence on an input line. This category\nis enabled by default.\n\n'ig'\n'262144'\nAn invalid escape sequence occurred in input ignored using the 'ig'\nrequest. This warning category diagnoses a condition that is an\nerror when it occurs in non-ignored input.\n\n'color'\n'524288'\nAn undefined color was selected, an attempt was made to define a\ncolor using an unrecognized color space, an invalid component in a\ncolor definition was encountered, or an attempt was made to\nredefine a default color.\n\n'file'\n'1048576'\nAn attempt was made to load a file that does not exist. This\ncategory is enabled by default.\n\nTwo warning names group other warning categories for convenience.\n\n'all'\nAll warning categories except 'di', 'mac' and 'reg'. This\nshorthand is intended to produce all warnings that are useful with\nmacro packages written for AT&T 'troff' and its descendants, which\nhave less fastidious diagnostics than GNU 'troff'.\n\n'w'\nAll warning categories. Authors of documents and macro packages\ntargeting 'groff' are encouraged to use this setting.\n", "subsections": [] }, "File: groff.info, Node: Implementation Differences, Next: Safer Mode, Prev: Debugging, Up: GNU troff Reference": { "content": "", "subsections": [ { "name": "5.38 Implementation Differences", "content": "GNU 'troff' has a number of features that cause incompatibilities with\ndocuments written for other versions of 'troff'. Some GNU extensions to\n'troff' have become supported by other implementations.\n\n* Menu:\n\n* Safer Mode::\n* Compatibility Mode::\n* Other Differences::\n" } ] }, "File: groff.info, Node: Safer Mode, Next: Compatibility Mode, Prev: Implementation Differences, Up: Implementation Differences": { "content": "The formatter operates in \"safer\" mode by default; to mitigate risks\nfrom untrusted input documents, the 'pi' and 'sy' requests are disabled.\nGNU 'troff''s '-U' option enables \"unsafe mode\", restoring their\nfunction and enabling additional 'groff' extension requests, 'open',\n'opena', and 'pso'. *Note I/O::.\n", "subsections": [] }, "File: groff.info, Node: Compatibility Mode, Next: Safer Mode, Prev: Other Differences, Up: Implementation Differences": { "content": "Long identifier names may be GNU 'troff''s most obvious innovation.\nAT&T 'troff' interprets '.dsabcd' as defining a string 'ab' with\ncontents 'cd'. Normally, GNU 'troff' interprets this as a call of a\nmacro named 'dsabcd'. AT&T 'troff' also interprets '\\*[' and '\\n[' as\nan interpolation of a string or register, respectively, named '['. In\nGNU 'troff', however, the '[' is normally interpreted as delimiting a\nlong name. In compatibility mode, GNU 'troff' interprets names in the\ntraditional way; they thus can be two characters long at most.\n\n-- Request: .cp [n]\n-- Register: \\n[.C]\nIf N is missing or non-zero, turn on compatibility mode; otherwise,\nturn it off.\n\nThe read-only register '.C' is 1 if compatibility mode is on,\n0 otherwise.\n\nCompatibility mode can be also turned on with the '-C' command-line\noption.\n\n-- Request: .do name\n-- Register: \\n[.cp]\nThe 'do' request interprets the string, request, diversion, or\nmacro NAME (along with any further arguments) with compatibility\nmode disabled. Compatibility mode is restored (only if it was\nactive) when the expansion of NAME is interpreted; that is, the\nrestored compatibility state applies to the contents of the macro,\nstring, or diversion NAME as well as data read from files or pipes\nif NAME is any of the 'so', 'soquiet', 'mso', 'msoquiet', or 'pso'\nrequests.\n\nThe following example illustrates several aspects of 'do' behavior.\n\n.de mac1\nFOO\n..\n.de1 mac2\ngroff\n.mac1\n..\n.de mac3\ncompatibility\n.mac1\n..\n.de ma\n\\\\$1\n..\n.cp 1\n.do mac1\n.do mac2 \\\" mac2, defined with .de1, calls \"mac1\"\n.do mac3 \\\" mac3 calls \"ma\" with argument \"c1\"\n.do mac3 \\[ti] \\\" groff syntax accepted in .do arguments\n=> FOO groff FOO compatibility c1 ~\n\nThe read-only register '.cp', meaningful only when dereferenced\nfrom a 'do' request, is 1 if compatibility mode was on when the\n'do' request was encountered, and 0 if it was not. This register\nis specialized and may require a statement of rationale.\n\nWhen writing macro packages or documents that use GNU 'troff'\nfeatures and which may be mixed with other packages or documents\nthat do not--common scenarios include serial processing of man\npages or use of the 'so' or 'mso' requests--you may desire correct\noperation regardless of compatibility mode enablement in the\nsurrounding context. It may occur to you to save the existing\nvalue of '\\n(.C' into a register, say, 'C', at the beginning of\nyour file, turn compatibility mode off with '.cp 0', then restore\nit from that register at the end with '.cp \\n(C'. At the same\ntime, a modular design of a document or macro package may lead you\nto multiple layers of inclusion. You cannot use the same register\nname everywhere lest you \"clobber\" the value from a preceding or\nenclosing context. The two-character register name space of AT&T\n'troff' is confining and mnemonically challenging; you may wish to\nuse the more capacious name space of GNU 'troff'. However,\nattempting '.nr mysavedC \\n(.C' will not work in compatibility\nmode; the register name is too long. \"This is exactly what 'do' is\nfor,\" you think, '.do nr mysavedC \\n(.C'. The foregoing will\nalways save zero to your register, because 'do' turns compatibility\nmode off while it interprets its argument list.\n\nTo robustly save compatibility mode before switching it off, use\n\n.do nr mysavedC \\n[.cp]\n.cp 0\n\nat the beginning of your file, followed by\n\n.cp \\n[mysavedC]\n.do rr mysavedC\n\nat the end. As in the C language, we all have to share one big\nname space, so choose a register name that is unlikely to collide\nwith other uses.\n\nNormally, GNU 'troff' preserves the interpolation depth in delimited\narguments, but not in compatibility mode.\n\n.ds xx '\n\\w'abc\\*(xxdef'\n=> 168 (normal mode on a terminal device)\n=> 72def' (compatibility mode on a terminal device)\n\nFurthermore, the escape sequences '\\f', '\\H', '\\m', '\\M', '\\R', '\\s',\nand '\\S' are transparent for the purpose of recognizing a control\ncharacter at the beginning of a line only in compatibility mode. For\nexample, this code produces bold output in both cases, but the text\ndiffers.\n\n.de xx\nHello!\n..\n\\fB.xx\\fP\n=> .xx (normal mode)\n=> Hello! (compatibility mode)\n\nNormally, the syntax form '\\s'N accepts only a single character (a\ndigit) for N, consistently with other forms that originated in AT&T\n'troff', like '\\*', '\\$', '\\f', '\\g', '\\k', '\\n', and '\\z'. In\ncompatibility mode only, a non-zero N must be in the range 4-39. Legacy\ndocuments relying upon this quirk of parsing(1) (*note Compatibility\nMode-Footnote-1::) should be migrated to another '\\s' form.\n", "subsections": [] }, "File: groff.info, Node: Other Differences, Prev: Compatibility Mode, Up: Implementation Differences": { "content": "'groff' request names unrecognized by other 'troff' implementations will\nlikely be ignored by them; escape sequences that are 'groff' extensions\nare liable to be interpreted as if the escape character were not\npresent. For example, the adjustable, non-breaking escape sequence '\\~'\nis also supported by Heirloom Doctools 'troff' 050915 (September 2005),\n'mandoc' 1.9.5 (2009-09-21), 'neatroff' (commit 1c6ab0f6e, 2016-09-13),\nand Plan 9 from User Space 'troff' (commit 93f8143600, 2022-08-12), but\nnot by Solaris or Documenter's Workbench 'troff's. *Note Manipulating\nFilling and Adjustment::.\n\nGNU 'troff' does not allow the use of the escape sequences '\\|',\n'\\^', '\\&', '\\{', '\\}', '\\', '\\'', '\\`', '\\-', '\\', '\\!', '\\%', and\n'\\c' in identifiers; AT&T 'troff' does. The '\\A' escape sequence (*note", "subsections": [] }, "Identifiers::) may be helpful in avoiding use of these escape sequences": { "content": "in names.\n\nWhen adjusting to both margins, AT&T 'troff' at first adjusts spaces\nstarting from the right; GNU 'troff' begins from the left. Both\nimplementations adjust spaces from opposite ends on alternating output\nlines in this adjustment mode to prevent \"rivers\" in the text.\n\nGNU 'troff' does not always hyphenate words as AT&T 'troff' does.\nThe AT&T implementation uses a set of hard-coded rules specific to", "subsections": [] }, "English, while GNU 'troff' uses language-specific hyphenation pattern": { "content": "files derived from TeX. Furthermore, in old versions of 'troff' there\nwas a limited amount of space to store hyphenation exceptions (arguments\nto the 'hw' request); GNU 'troff' has no such restriction.\n\nGNU 'troff' predefines a string '.T' containing the argument given to\nthe '-T' command-line option, namely the current output device (for\nexample, 'pdf' or 'utf8'). The existence of this string is a common\nfeature of post-CSTR #54 'troff's(1) (*note Other", "subsections": [] }, "Differences-Footnote-1::) but valid values are specific to each": { "content": "implementation.\n\nAT&T 'troff' ignored attempts to remove read-only registers; GNU\n'troff' honors such requests. *Note Built-in Registers::.\n\nThe (read-only) register '.T' interpolates 1 if GNU 'troff' is called\nwith the '-T' command-line option, and 0 otherwise. This behavior\ndiffers from AT&T 'troff', which interpolated 1 only if 'nroff' was the\nformatter and was called with '-T'.\n\nAT&T 'troff' and other implementations handle the 'lf' request\ndifferently. For them, its LINE argument changes the line number of the\ncurrent line.\n\nAT&T 'troff' had only environments named '0', '1', and '2'. In GNU\n'troff', any number of environments may exist, using any valid\nidentifiers for their names (*note Identifiers::.)\n\nFractional type sizes cause one noteworthy incompatibility. In AT&T\n'troff' the 'ps' request ignores scaling units and thus '.ps 10u' sets\nthe type size to 10 points, whereas in GNU 'troff' it sets the type size\nto 10 scaled points. *Note Using Fractional Type Sizes::.\n\nThe 'ab' request differs from AT&T 'troff': GNU 'troff' writes no\nmessage to the standard error stream if no arguments are given, and it\nexits with a failure status instead of a successful one.\n\nThe 'bp' request differs from AT&T 'troff': GNU 'troff' does not\naccept a scaling unit on the argument, a page number; the former\n(somewhat uselessly) does.\n\nThe 'pm' request differs from AT&T 'troff': GNU 'troff' reports the\nsizes of macros, strings, and diversions in bytes and ignores an\nargument to report only the sum of the sizes.\n\nUnlike AT&T 'troff', GNU 'troff' does not ignore the 'ss' request if\nthe output is a terminal device; instead, the values of minimal\ninter-word and additional inter-sentence space are each rounded down to\nthe nearest multiple of 12.\n\nIn GNU 'troff' there is a fundamental difference between\n(unformatted) characters and (formatted) glyphs. Everything that\naffects how a glyph is output is stored with the glyph node; once a\nglyph node has been constructed, it is unaffected by any subsequent\nrequests that are executed, including 'bd', 'cs', 'tkf', 'tr', or 'fp'\nrequests. Normally, glyphs are constructed from characters immediately\nbefore the glyph is added to an output line. Macros, diversions, and\nstrings are all, in fact, the same type of object; they contain a\nsequence of intermixed character and glyph nodes. Special characters\ntransform from one to the other: before being added to the output, they\nbehave as characters; afterward, they are glyphs. A glyph node does not\nbehave like a character node when it is processed by a macro: it does\nnot inherit any of the special properties that the character from which\nit was constructed might have had. For example, the input\n\n.di x\n\\\\\\\\\n.br\n.di\n.x\n\nproduces '\\\\' in GNU 'troff'. Each pair of backslashes becomes one\nbackslash glyph; the resulting backslashes are thus not interpreted as\nescape characters when they are reread as the diversion is output.\nAT&T 'troff' would interpret them as escape characters when rereading\nthem and end up printing one '\\'.\n\nOne correct way to obtain a printable backslash in most documents is\nto use the '\\e' escape sequence; this always prints a single instance of\nthe current escape character,(2) (*note Other Differences-Footnote-2::)\nregardless of whether or not it is used in a diversion; it also works in\nboth GNU 'troff' and AT&T 'troff'.\n\nThe other correct way, appropriate in contexts independent of the\nbackslash's common use as a 'troff' escape character--perhaps in\ndiscussion of character sets or other programming languages--is the\ncharacter escape '\\(rs' or '\\[rs]', for \"reverse solidus\", from its name\nin the ECMA-6 (ISO/IEC 646) standard.(3) (*note Other", "subsections": [] }, "Differences-Footnote-3::)": { "content": "To store an escape sequence in a diversion that is interpreted when\nthe diversion is reread, either use the traditional '\\!' transparent\noutput facility, or, if this is unsuitable, the new '\\?' escape\nsequence. *Note Diversions:: and *note Gtroff Internals::.\n\nIn the somewhat pathological case where a diversion exists containing\na partially collected line and a partially collected line at the\ntop-level diversion has never existed, AT&T 'troff' will output the\npartially collected line at the end of input; GNU 'troff' will not.\n", "subsections": [] }, "File: groff.info, Node: File Formats, Next: Copying This Manual, Prev: GNU troff Reference, Up: Top": { "content": "", "subsections": [] }, "6 File Formats": { "content": "", "subsections": [] }, "All files read and written by 'gtroff' are text files. The following": { "content": "two sections describe their format.\n\n* Menu:\n\n* gtroff Output::\n* Device and Font Description Files::\n", "subsections": [] }, "File: groff.info, Node: gtroff Output, Next: Device and Font Description Files, Prev: File Formats, Up: File Formats": { "content": "", "subsections": [ { "name": "6.1 'gtroff' Output", "content": "" } ] }, "This section describes the 'groff' intermediate output format produced": { "content": "by GNU 'troff'.\n\nAs 'groff' is a wrapper program around GNU 'troff' and automatically\ncalls an output driver (or \"postprocessor\"), this output does not show\nup normally. This is why it is called intermediate. 'groff' provides\nthe option '-Z' to inhibit postprocessing such that the produced\nintermediate output is sent to standard output just as it is when\ncalling GNU 'troff' directly.\n\nHere, the term \"troff output\" describes what is output by GNU\n'troff', while \"intermediate output\" refers to the language that is\naccepted by the parser that prepares this output for the output drivers.\nThis parser handles whitespace more flexibly than AT&T's implementation\nand implements obsolete elements for compatibility; otherwise, both\nformats are the same.(1) (*note gtroff Output-Footnote-1::)\n\nThe main purpose of the intermediate output concept is to facilitate\nthe development of postprocessors by providing a common programming\ninterface for all devices. It has a language of its own that is\ncompletely different from the 'gtroff' language. While the 'gtroff'\nlanguage is a high-level programming language for text processing, the\nintermediate output language is a kind of low-level assembler language\nby specifying all positions on the page for writing and drawing.\n\nThe intermediate output produced by 'gtroff' is fairly readable,\nwhile output from AT&T 'troff' is rather hard to understand because of\nstrange habits that are still supported, but not used any longer by\n'gtroff'.\n\n* Menu:\n\n* Language Concepts::\n* Command Reference::\n* Intermediate Output Examples::\n* Output Language Compatibility::\n", "subsections": [] }, "File: groff.info, Node: Language Concepts, Next: Command Reference, Prev: gtroff Output, Up: gtroff Output": { "content": "", "subsections": [] }, "The fundamental operation of the GNU 'troff' formatter is the": { "content": "translation of the 'groff' input language into a device-independent form\nprimarily concerned with what has to be written or drawn at specific\npositions on the output device. This language is simple and imperative.\nIn the following discussion, the term \"command\" always refers to this\nintermediate output language, and never to the 'groff' language intended\nfor direct use by document authors. Intermediate output commands\ncomprise several categories: glyph output; font, color, and text size\nselection; motion of the printing position; page advancement; drawing of\ngeometric objects; and device control commands, a catch-all for\noperations not easily classified as any of the foregoing, such as\ndirectives to start and stop output, identify the intended output\ndevice, or place URL hyperlinks in supported output formats.\n\n* Menu:\n\n* Separation::\n* Argument Units::\n* Document Parts::\n", "subsections": [] }, "File: groff.info, Node: Separation, Next: Argument Units, Prev: Language Concepts, Up: Language Concepts": { "content": "6.1.1.1 Separation\n..................\n\nAT&T 'troff' output has strange requirements regarding whitespace. The\n'gtroff' output parser, however, is more tolerant, making whitespace\nmaximally optional. Such characters, i.e., the tab, space, and newline,\nalways have a syntactical meaning. They are never printable because\nspacing within the output is always done by positioning commands.\n\nAny sequence of space or tab characters is treated as a single\n\"syntactical space\". It separates commands and arguments, but is only\nrequired when there would occur a clashing between the command code and\nthe arguments without the space. Most often, this happens when\nvariable-length command names, arguments, argument lists, or command\nclusters meet. Commands and arguments with a known, fixed length need\nnot be separated by syntactical space.\n\nA line break is a syntactical element, too. Every command argument\ncan be followed by whitespace, a comment, or a newline character. Thus\na \"syntactical line break\" is defined to consist of optional syntactical\nspace that is optionally followed by a comment, and a newline character.\n\nThe normal commands, those for positioning and text, consist of a\nsingle letter taking a fixed number of arguments. For historical\nreasons, the parser allows stacking of such commands on the same line,\nbut fortunately, in 'gtroff''s intermediate output, every command with\nat least one argument is followed by a line break, thus providing\nexcellent readability.\n\nThe other commands--those for drawing and device controlling--have a\nmore complicated structure; some recognize long command names, and some\ntake a variable number of arguments. So all 'D' and 'x' commands were\ndesigned to request a syntactical line break after their last argument.", "subsections": [] }, "Only one command, 'x X', has an argument that can span several input": { "content": "lines; all other commands must have all of their arguments on the same\nline as the command, i.e., the arguments may not be split by a line\nbreak.\n\nEmpty lines (these are lines containing only space and/or a comment),\ncan occur everywhere. They are just ignored.\n", "subsections": [] }, "File: groff.info, Node: Argument Units, Next: Document Parts, Prev: Separation, Up: Language Concepts": { "content": "6.1.1.2 Argument Units\n......................\n", "subsections": [] }, "Some commands take integer arguments that are assumed to represent": { "content": "values in a measurement unit, but the letter for the corresponding\nscaling unit is not written with the output command arguments. Most\ncommands assume the scaling unit 'u', the basic unit of the device, some\nuse 'z', the scaled point unit of the device, while others, such as the\ncolor commands, expect plain integers.\n\nSingle characters can have the eighth bit set, as can the names of\nfonts and special characters. The names of characters and fonts can be\nof arbitrary length. A character that is to be printed is always in the\ncurrent font.\n\nA string argument is always terminated by the next whitespace\ncharacter (space, tab, or newline); an embedded '#' character is\nregarded as part of the argument, not as the beginning of a comment\ncommand. An integer argument is already terminated by the next\nnon-digit character, which then is regarded as the first character of\nthe next argument or command.\n", "subsections": [] }, "File: groff.info, Node: Document Parts, Prev: Argument Units, Up: Language Concepts": { "content": "6.1.1.3 Document Parts\n......................\n\nA correct intermediate output document consists of two parts, the\n\"prologue\" and the \"body\".\n\nThe task of the prologue is to set the general device parameters\nusing three exactly specified commands. 'gtroff''s prologue is\nguaranteed to consist of the following three lines (in that order):\n\nx T DEVICE\nx res N H V\nx init\n\nwith the arguments set as outlined in *note Device Control Commands::.", "subsections": [] }, "The parser for the intermediate output format is able to interpret": { "content": "additional whitespace and comments as well even in the prologue.\n\nThe body is the main section for processing the document data.", "subsections": [] }, "Syntactically, it is a sequence of any commands different from the ones": { "content": "used in the prologue. Processing is terminated as soon as the first\n'x stop' command is encountered; the last line of any 'gtroff'\nintermediate output always contains such a command.\n\nSemantically, the body is page oriented. A new page is started by a\n'p' command. Positioning, writing, and drawing commands are always done\nwithin the current page, so they cannot occur before the first 'p'\ncommand. Absolute positioning (by the 'H' and 'V' commands) is done\nrelative to the current page; all other positioning is done relative to\nthe current location within this page.\n", "subsections": [] }, "File: groff.info, Node: Command Reference, Next: Intermediate Output Examples, Prev: Language Concepts, Up: gtroff Output": { "content": "This section describes all intermediate output commands, both from AT&T\n'troff' as well as the 'gtroff' extensions.\n\n* Menu:\n\n* Comment Command::\n* Simple Commands::\n* Graphics Commands::\n* Device Control Commands::\n* Obsolete Command::\n", "subsections": [] }, "File: groff.info, Node: Comment Command, Next: Simple Commands, Prev: Command Reference, Up: Command Reference": { "content": "6.1.2.1 Comment Command\n.......................\n\n'#ANYTHING'\nA comment. Ignore any characters from the '#' character up to the\nnext newline character.\n\nThis command is the only possibility for commenting in the\nintermediate output. Each comment can be preceded by arbitrary\nsyntactical space; every command can be terminated by a comment.\n", "subsections": [] }, "File: groff.info, Node: Simple Commands, Next: Graphics Commands, Prev: Comment Command, Up: Command Reference": { "content": "6.1.2.2 Simple Commands\n.......................\n", "subsections": [] }, "The commands in this subsection have a command code consisting of a": { "content": "single character, taking a fixed number of arguments. Most of them are\ncommands for positioning and text writing. These commands are tolerant\nof whitespace. Optionally, syntactical space can be inserted before,\nafter, and between the command letter and its arguments. All of these\ncommands are stackable; i.e., they can be preceded by other simple\ncommands or followed by arbitrary other commands on the same line. A\nseparating syntactical space is necessary only when two integer\narguments would clash or if the preceding argument ends with a string\nargument.\n\n'C ID'\nTypeset the glyph of the special character ID. Trailing\nsyntactical space is necessary to allow special character names of\narbitrary length. The drawing position is not advanced.\n\n'c G'\nTypeset the glyph of the ordinary character C. The drawing\nposition is not advanced.\n\n'f N'\nSelect the font mounted at position N. N cannot be negative.\n\n'H N'\nHorizontally move the drawing position to N basic units from the\nleft edge of the page. N cannot be negative.\n\n'h N'\nMove the drawing position right N basic units. AT&T 'troff'\nallowed negative N; GNU 'troff' does not produce such values, but\n'groff''s output driver library handles them.\n\n'm COLOR-SCHEME [COMPONENT ...]'\nSelect the stroke color using the COMPONENTs in the color space\nSCHEME. Each COMPONENT is an integer between 0 and 65535. The\nquantity of components and their meanings vary with each SCHEME.\nThis command is a 'groff' extension.\n\n'mc CYAN MAGENTA YELLOW'\nUse the CMY color scheme with components cyan, magenta, and\nyellow.\n\n'md'\nUse the default color (no components; black in most cases).\n\n'mg GRAY'\nUse a grayscale color scheme with a component ranging between\n0 (black) and 65535 (white).\n\n'mk CYAN MAGENTA YELLOW BLACK'\nUse the CMYK color scheme with components cyan, magenta,\nyellow, and black.\n\n'mr RED GREEN BLUE'\nUse the RGB color scheme with components red, green, and blue.\n\n'N N'\nTypeset the glyph with index N in the current font. N is normally\na non-negative integer. The drawing position is not advanced. The\n'html' and 'xhtml' devices use this command with negative N to\nproduce unbreakable space; the absolute value of N is taken and\ninterpreted in basic units.\n\n'n B A'\nIndicate a break. No action is performed; the command is present\nto make the output more easily parsed. The integers B and A\ndescribe the vertical space amounts before and after the break,\nrespectively. GNU 'troff' issues this command but 'groff''s output\ndriver library ignores it. See 'v' and 'V' below.\n\n'p N'\nBegin a new page, setting its number to N. Each page is\nindependent, even from those using the same number. The vertical\ndrawing position is set to 0. All positioning, writing, and\ndrawing commands are interpreted in the context of a page, so a\n'p' command must precede them.\n\n's N'\nSet type size to N scaled points (unit 'z' in GNU 'troff'. AT&T\n'troff' used unscaled points 'p' instead; see *note Output Language\nCompatibility::.\n\n't XYZ'\n't XYZ DUMMY-ARG'\nTypeset a word XYZ; that is, set a sequence of ordinary glyphs\nnamed X, Y, Z, ..., terminated by a space character or a line\nbreak; an optional second integer argument is ignored (this allows\nthe formatter to generate an even number of arguments). Each glyph\nis set at the current drawing position, and the position is then\nadvanced horizontally by the glyph's width. A glyph's width is\nread from its metrics in the font description file, scaled to the\ncurrent type size, and rounded to a multiple of the horizontal\nmotion quantum. Use the 'C' command to emplace glyphs of special\ncharacters. The 't' command is a 'groff' extension and is output\nonly for devices whose 'DESC' file contains the 'tcommand'\ndirective; see *note DESC File Format::.\n\n'u N XYZ'\nTypeset word XYZ with track kerning. As 't', but after placing\neach glyph, the drawing position is further advanced horizontally\nby N basic units ('u'). The 'u' command is a 'groff' extension and\nis output only for devices whose 'DESC' file contains the\n'tcommand' directive; see *note DESC File Format::.\n\n'V N'\nVertically move the drawing position to N basic units from the top\nedge of the page. N cannot be negative.\n\n'v N'\nMove the drawing position down N basic units. AT&T 'troff' allowed\nnegative N; GNU 'troff' does not produce such values, but 'groff''s\noutput driver library handles them.\n\n'w'\nIndicate an inter-word space. No action is performed; the command\nis present to make the output more easily parsed. Only adjustable,\nbreakable inter-word spaces are thus described; those resulting\nfrom '\\~' or horizontal motion escape sequences are not. GNU\n'troff' issues this command but 'groff''s output driver library\nignores it. See 'h' and 'H' above.\n", "subsections": [] }, "File: groff.info, Node: Graphics Commands, Next: Device Control Commands, Prev: Simple Commands, Up: Command Reference": { "content": "6.1.2.3 Graphics Commands\n.........................\n", "subsections": [] }, "Each graphics or drawing command in the intermediate output starts with": { "content": "the letter 'D', followed by one or two characters that specify a\nsubcommand; this is followed by a fixed or variable number of integer\narguments that are separated by a single space character. A 'D' command\nmay not be followed by another command on the same line (apart from a\ncomment), so each 'D' command is terminated by a syntactical line break.\n\n'gtroff' output follows the classical spacing rules (no space between\ncommand and subcommand, all arguments are preceded by a single space\ncharacter), but the parser allows optional space between the command\nletters and makes the space before the first argument optional. As\nusual, each space can be any sequence of tab and space characters.\n\nSome graphics commands can take a variable number of arguments. In\nthis case, they are integers representing a size measured in basic units\n'u'. The arguments called H1, H2, ..., HN stand for horizontal\ndistances where positive means right, negative left. The arguments\ncalled V1, V2, ..., VN stand for vertical distances where positive means\ndown, negative up. All these distances are offsets relative to the\ncurrent location.\n\nEach graphics command directly corresponds to a similar 'gtroff' '\\D'\nescape sequence. *Note Drawing Geometric Objects::.\n\nUnknown 'D' commands are assumed to be device-specific. Its\narguments are parsed as strings; the whole information is then sent to\nthe postprocessor.\n\nIn the following command reference, the syntax element \nmeans a syntactical line break as defined above.\n\n'D~ H1 V1 H2 V2 ... HN VN'\nDraw B-spline from current position to offset (H1,V1), then to\noffset (H2,V2), if given, etc., up to (HN,VN). This command takes\na variable number of argument pairs; the current position is moved\nto the terminal point of the drawn curve.\n\n'Da H1 V1 H2 V2'\nDraw arc from current position to (H1,V1)+(H2,V2) with center at\n(H1,V1); then move the current position to the final point of the\narc.\n\n'DC D'\n'DC D DUMMY-ARG'\nDraw a solid circle using the current fill color with diameter D\n(integer in basic units 'u') with leftmost point at the current\nposition; then move the current position to the rightmost point of\nthe circle. An optional second integer argument is ignored (this\nallows the formatter to generate an even number of arguments).\nThis command is a 'gtroff' extension.\n\n'Dc D'\nDraw circle line with diameter D (integer in basic units 'u') with\nleftmost point at the current position; then move the current\nposition to the rightmost point of the circle.\n\n'DE H V'\nDraw a solid ellipse in the current fill color with a horizontal\ndiameter of H and a vertical diameter of V (both integers in basic\nunits 'u') with the leftmost point at the current position; then\nmove to the rightmost point of the ellipse. This command is a\n'gtroff' extension.\n\n'De H V'\nDraw an outlined ellipse with a horizontal diameter of H and a\nvertical diameter of V (both integers in basic units 'u') with the\nleftmost point at current position; then move to the rightmost\npoint of the ellipse.\n\n'DF COLOR-SCHEME [COMPONENT ...]'\nSet fill color for solid drawing objects using different color\nschemes; the analogous command for setting the color of text, line\ngraphics, and the outline of graphic objects is 'm'. The color\ncomponents are specified as integer arguments between 0 and 65535.\nThe number of color components and their meaning vary for the\ndifferent color schemes. These commands are generated by\n'gtroff''s escape sequences '\\D'F ...'' and '\\M' (with no other\ncorresponding graphics commands). No position changing. This\ncommand is a 'gtroff' extension.\n\n'DFc CYAN MAGENTA YELLOW'\nSet fill color for solid drawing objects using the CMY color\nscheme, having the 3 color components CYAN, MAGENTA, and\nYELLOW.\n\n'DFd'\nSet fill color for solid drawing objects to the default fill\ncolor value (black in most cases). No component arguments.\n\n'DFg GRAY'\nSet fill color for solid drawing objects to the shade of gray\ngiven by the argument, an integer between 0 (black) and 65535\n(white).\n\n'DFk CYAN MAGENTA YELLOW BLACK'\nSet fill color for solid drawing objects using the CMYK color\nscheme, having the 4 color components CYAN, MAGENTA, YELLOW,\nand BLACK.\n\n'DFr RED GREEN BLUE'\nSet fill color for solid drawing objects using the RGB color\nscheme, having the 3 color components RED, GREEN, and BLUE.\n\n'Df N'\nThe argument N must be an integer in the range -32767 to 32767.\n\n0 <= N <= 1000\nSet the color for filling solid drawing objects to a shade of\ngray, where 0 corresponds to solid white, 1000 (the default)\nto solid black, and values in between to intermediate shades\nof gray; this is obsoleted by command 'DFg'.\n\nN < 0 or N > 1000\nSet the filling color to the color that is currently being\nused for the text and the outline, see command 'm'. For\nexample, the command sequence\n\nmg 0 0 65535\nDf -1\n\nsets all colors to blue.\n\nNo position changing. This command is a 'gtroff' extension.\n\n'Dl H V'\nDraw line from current position to offset (H,V) (integers in basic\nunits 'u'); then set current position to the end of the drawn line.\n\n'Dp H1 V1 H2 V2 ... HN VN'\nDraw a polygon line from current position to offset (H1,V1), from\nthere to offset (H2,V2), etc., up to offset (HN,VN), and from there\nback to the starting position. For historical reasons, the\nposition is changed by adding the sum of all arguments with odd\nindex to the actual horizontal position and the even ones to the\nvertical position. Although this doesn't make sense it is kept for\ncompatibility. This command is a 'gtroff' extension.\n\n'DP H1 V1 H2 V2 ... HN VN'\nDraw a solid polygon in the current fill color rather than an\noutlined polygon, using the same arguments and positioning as the\ncorresponding 'Dp' command. This command is a 'gtroff' extension.\n\n'Dt N'\nSet the current line thickness to N (an integer in basic units 'u')\nif N>0; if N=0 select the smallest available line thickness; if N<0\nset the line thickness proportional to the type size (this is the\ndefault before the first 'Dt' command was specified). For\nhistorical reasons, the horizontal position is changed by adding\nthe argument to the actual horizontal position, while the vertical\nposition is not changed. Although this doesn't make sense it is\nkept for compatibility. This command is a 'gtroff' extension.\n", "subsections": [] }, "File: groff.info, Node: Device Control Commands, Next: Obsolete Command, Prev: Graphics Commands, Up: Command Reference": { "content": "6.1.2.4 Device Control Commands\n...............................\n", "subsections": [] }, "Each device control command starts with the letter 'x', followed by a": { "content": "space character (optional or arbitrary space or tab in 'gtroff') and a\nsubcommand letter or word; each argument (if any) must be preceded by a\nsyntactical space. All 'x' commands are terminated by a syntactical\nline break; no device control command can be followed by another command\non the same line (except a comment).\n\nThe subcommand is basically a single letter, but to increase\nreadability, it can be written as a word, i.e., an arbitrary sequence of\ncharacters terminated by the next tab, space, or newline character. All\ncharacters of the subcommand word but the first are simply ignored. For\nexample, 'gtroff' outputs the initialization command 'x i' as 'x init'\nand the resolution command 'x r' as 'x res'.\n\nIn the following, the syntax element means a syntactical\nline break (*note Separation::).\n\n'xF NAME'\nThe 'F' stands for FILENAME.\n\nUse NAME as the intended name for the current file in error\nreports. This is useful for remembering the original file name\nwhen 'gtroff' uses an internal piping mechanism. The input file is\nnot changed by this command. This command is a 'gtroff' extension.\n\n'xf N S'\nThe 'f' stands for FONT.\n\nMount font position N (a non-negative integer) with font named S (a\ntext word). *Note Font Positions::.\n\n'xH N'\nThe 'H' stands for HEIGHT.\n\nSet glyph height to N (a positive integer in scaled points 'z').\nAT&T 'troff' uses the unit points ('p') instead. *Note Output\nLanguage Compatibility::.\n\n'xi'\nThe 'i' stands for INIT.\n\nInitialize device. This is the third command of the prologue.\n\n'xp'\nThe 'p' stands for PAUSE.\n\nParsed but ignored. The AT&T 'troff' manual documents this command\nas\n\npause device, can be restarted\n\nbut GNU 'troff' output drivers do nothing with this command.\n\n'xr N H V'\nThe 'r' stands for RESOLUTION.\n\nResolution is N, while H is the minimal horizontal motion, and V\nthe minimal vertical motion possible with this device; all\narguments are positive integers in basic units 'u' per inch. This\nis the second command of the prologue.\n\n'xS N'\nThe 'S' stands for SLANT.\n\nSet slant to N (an integer in basic units 'u').\n\n'xs'\nThe 's' stands for STOP.\n\nTerminates the processing of the current file; issued as the last\ncommand of any intermediate 'troff' output.\n\n'xt'\nThe 't' stands for TRAILER.\n\nGenerate trailer information, if any. In GNU 'troff', this is\nignored.\n\n'xT XXX'\nThe 'T' stands for TYPESETTER.\n\nSet the name of the output driver to XXX, a sequence of\nnon-whitespace characters terminated by whitespace. The possible\nnames correspond to those of 'groff''s '-T' option. This is the\nfirst command of the prologue.\n\n'xu N'\nThe 'u' stands for UNDERLINE.\n\nConfigure underlining of spaces. If N is 1, start underlining of\nspaces; if N is 0, stop underlining of spaces. This is needed for\nthe 'cu' request in 'nroff' mode and is ignored otherwise. This\ncommand is a 'gtroff' extension.\n\n'xX ANYTHING'\nThe 'x' stands for X-ESCAPE.\n\nSend string ANYTHING uninterpreted to the device. If the line\nfollowing this command starts with a '+' character this line is\ninterpreted as a continuation line in the following sense. The '+'\nis ignored, but a newline character is sent instead to the device,\nthe rest of the line is sent uninterpreted. The same applies to\nall following lines until the first character of a line is not a\n'+' character. This command is generated by the 'gtroff' escape\nsequence '\\X'. The line-continuing feature is a 'gtroff'\nextension.\n", "subsections": [] }, "File: groff.info, Node: Obsolete Command, Prev: Device Control Commands, Up: Command Reference": { "content": "6.1.2.5 Obsolete Command\n........................\n\nIn AT&T 'troff' output, the writing of a single glyph is mostly done by\na very strange command that combines a horizontal move and a single\ncharacter giving the glyph name. It doesn't have a command code, but is\nrepresented by a 3-character argument consisting of exactly 2 digits and\na character.\n", "subsections": [] }, "DDG": { "content": "Move right DD (exactly two decimal digits) basic units 'u', then\nprint glyph G (represented as a single character).\n\nIn GNU 'troff', arbitrary syntactical space around and within this\ncommand is allowed. Only when a preceding command on the same line\nends with an argument of variable length is a separating space\nobligatory. In AT&T 'troff', large clusters of these and other\ncommands are used, mostly without spaces; this made such output\nalmost unreadable.\n\nFor modern high-resolution devices, this command does not make sense\nbecause the width of the glyphs can become much larger than two decimal\ndigits. In 'gtroff', this is only used for the devices 'X75', 'X75-12',\n'X100', and 'X100-12'. For other devices, the commands 't' and 'u'\nprovide a better functionality.\n", "subsections": [] }, "File: groff.info, Node: Intermediate Output Examples, Next: Output Language Compatibility, Prev: Command Reference, Up: gtroff Output": { "content": "", "subsections": [] }, "This section presents the intermediate output generated from the same": { "content": "input for three different devices. The input is the sentence 'hell\nworld' fed into 'gtroff' on the command line.\n", "subsections": [] }, "High-resolution device 'ps'": { "content": "This is the standard output of 'gtroff' if no '-T' option is given.\n\nshell> echo \"hell world\" | groff -Z -T ps\n\nx T ps\nx res 72000 1 1\nx init\np1\nx font 5 TR\nf5\ns10000\nV12000\nH72000\nthell\nwh2500\ntw\nH96620\ntorld\nn12000 0\nx trailer\nV792000\nx stop\n\nThis output can be fed into 'grops' to get its representation as a\nPostScript file.\n", "subsections": [] }, "Low-resolution device 'latin1'": { "content": "This is similar to the high-resolution device except that the\npositioning is done at a minor scale. Some comments (lines\nstarting with '#') were added for clarification; they were not\ngenerated by the formatter.\n\nshell> echo \"hell world\" | groff -Z -T latin1\n\n# prologue\nx T latin1\nx res 240 24 40\nx init\n# begin a new page\np1\n# font setup\nx font 1 R\nf1\ns10\n# initial positioning on the page\nV40\nH0\n# write text 'hell'\nthell\n# inform about space, and issue a horizontal jump\nwh24\n# write text 'world'\ntworld\n# announce line break, but do nothing because...\nn40 0\n# ...the end of the document has been reached\nx trailer\nV2640\nx stop\n\nThis output can be fed into 'grotty' to get a formatted text\ndocument.\n\nAT&T 'troff' output\nSince a computer monitor has a much lower resolution than modern\nprinters, the intermediate output for X11 devices can use the\njump-and-write command with its 2-digit displacements.\n\nshell> echo \"hell world\" | groff -Z -T X100\n\nx T X100\nx res 100 1 1\nx init\np1\nx font 5 TR\nf5\ns10\nV16\nH100\n# write text with jump-and-write commands\nch07e07l03lw06w11o07r05l03dh7\nn16 0\nx trailer\nV1100\nx stop\n\nThis output can be fed into 'xditview' or 'gxditview' for\ndisplaying in X.\n\nDue to the obsolete jump-and-write command, the text clusters in\nthe AT&T 'troff' output are almost unreadable.\n", "subsections": [] }, "File: groff.info, Node: Output Language Compatibility, Prev: Intermediate Output Examples, Up: gtroff Output": { "content": "The intermediate output language of AT&T 'troff' was first documented in\n'A Typesetter-independent TROFF', by Brian Kernighan, and by 1992 the\nAT&T 'troff' manual was updated to incorprate a description of it.\n\nThe GNU 'troff' intermediate output format is compatible with this\nspecification except for the following features.\n\n* The classical quasi-device independence is not yet implemented.\n\n* The old hardware was very different from what we use today. So the\n'groff' devices are also fundamentally different from the ones in\nAT&T 'troff'. For example, the AT&T PostScript device is called\n'post' and has a resolution of only 720 units per inch, suitable\nfor printers 20 years ago, while 'groff''s 'ps' device has a\nresolution of 72000 units per inch. Maybe, by implementing some\nrescaling mechanism similar to the classical quasi-device\nindependence, 'groff' could emulate AT&T's 'post' device.\n\n* The B-spline command 'D~' is correctly handled by the intermediate\noutput parser, but the drawing routines aren't implemented in some\nof the postprocessor programs.\n\n* The argument of the commands 's' and 'x H' has the implicit unit\nscaled point 'z' in 'gtroff', while AT&T 'troff' has point ('p').\nThis isn't an incompatibility but a compatible extension, for both\nunits coincide for all devices without a 'sizescale' parameter in\nthe 'DESC' file, including all postprocessors from AT&T and\n'groff''s text devices. The few 'groff' devices with a 'sizescale'\nparameter either do not exist for AT&T 'troff', have a different\nname, or seem to have a different resolution. So conflicts are\nvery unlikely.\n\n* The position changing after the commands 'Dp', 'DP', and 'Dt' is\nillogical, but as old versions of 'gtroff' used this feature it is\nkept for compatibility reasons.\n", "subsections": [] }, "File: groff.info, Node: Device and Font Description Files, Prev: gtroff Output, Up: File Formats": { "content": "", "subsections": [ { "name": "6.2 Device and Font Description Files", "content": "" } ] }, "The 'groff' font and output device description formats are slight": { "content": "extensions of those used by AT&T device-independent 'troff'. In\ndistinction to the AT&T implementation, 'groff' lacks a binary format;\nall files are text files.(1) (*note Device and Font Description", "subsections": [] }, "Files-Footnote-1::) The device and font description files for a device": { "content": "NAME are stored in a 'devNAME' directory. The device description file\nis called 'DESC', and, for each font supported by the device, a font\ndescription file is called 'F', where F is usually an abbreviation of a\nfont's name and/or style. For example, the 'ps' (PostScript) device has\n'groff' font description files for Times roman ('TR') and Zapf Chancery", "subsections": [] }, "Medium italic ('ZCMI'), among many others, while the 'utf8' device (for": { "content": "terminal emulators) has only font descriptions for the roman, italic,\nbold, and bold-italic styles ('R', 'I', 'B', and 'BI', respectively).\n\nDevice and font description files are read both by the formatter, GNU\n'troff', and by output drivers. The programs delegate these files'\nprocessing to an internal library, 'libgroff', ensuring their consistent\ninterpretation.\n\n* Menu:\n\n* DESC File Format::\n* Font Description File Format::\n", "subsections": [] }, "File: groff.info, Node: DESC File Format, Next: Font Description File Format, Prev: Device and Font Description Files, Up: Device and Font Description Files": { "content": "The 'DESC' file contains a series of directives; each begins a line.", "subsections": [] }, "Their order is not important, with two exceptions: (1) the 'res'": { "content": "directive must precede any 'papersize' directive; and (2) the 'charset'\ndirective must come last (if at all). If a directive name is repeated,\nlater entries in the file override previous ones (except that the paper\ndimensions are computed based on the 'res' directive last seen when\n'papersize' is encountered). Spaces and/or tabs separate words and are\nignored at line boundaries. Comments start with the '#' character and\nextend to the end of a line. Empty lines are ignored.\n\n'family FAM'\nThe default font family is FAM.\n\n'fonts N F1 ... FN'\nFonts F1, ..., FN are mounted at font positions M+1, ..., M+N where\nM is the number of 'styles' (see below). This directive may extend\nover more than one line. A font name of '0' causes no font to be\nmounted at the corresponding position.\n\n'hor N'\nThe horizontal motion quantum is N basic units. All horizontal\nquantities are rounded to multiples of N.\n\n'imagegenerator PROGRAM'\nUse PROGRAM to generate PNG images from PostScript input. Under\nGNU/Linux, this is usually 'gs', but under other systems (notably\nCygwin) it might be set to another name. The 'grohtml' driver uses\nthis directive.\n\n'paperlength N'\nThe vertical dimension of the output medium is N basic units\n(deprecated: use 'papersize' instead).\n\n'papersize FORMAT-OR-DIMENSION-PAIR-OR-FILE-NAME ...'\nThe dimensions of the output medium are as according to the\nargument, which is either a standard paper format, a pair of\ndimensions, or the name of a plain text file containing either of\nthe foregoing.\n\nRecognized paper formats are the ISO and DIN formats 'A0'-'A7',\n'B0'-'B7', 'C0'-'C7', 'D0'-'D7'; the U.S. paper types 'letter',\n'legal', 'tabloid', 'ledger', 'statement', and 'executive'; and the\nenvelope formats 'com10', 'monarch', and 'DL'. Matching is\nperformed without regard for lettercase.\n\nAlternatively, the argument can be a custom paper format in the\nformat 'LENGTH,WIDTH' (with no spaces before or after the comma).\nBoth LENGTH and WIDTH must have a unit appended; valid units are\n'i' for inches, 'c' for centimeters, 'p' for points, and 'P' for\npicas. Example: '12c,235p'. An argument that starts with a digit\nis always treated as a custom paper format.\n\nFinally, the argument can be a file name (e.g., '/etc/papersize');\nif the file can be opened, the first line is read and a match\nattempted against each of the other forms. No comment syntax is\nsupported.\n\nMore than one argument can be specified; each is scanned in turn\nand the first valid paper specification used.\n\n'paperwidth N'\nThe horizontal dimension of the output medium is N basic units\n(deprecated: use 'papersize' instead).\n\n'passfilenames'\nDirect GNU 'troff' to emit the name of the source file being\nprocessed. This is achieved with the intermediate output command\n'x F', which 'grohtml' interprets.\n\n'postpro PROGRAM'\nUse PROGRAM as the postprocessor.\n\n'prepro PROGRAM'\nUse PROGRAM as a preprocessor. The 'html' and 'xhtml' output\ndevices use this directive.\n\n'print PROGRAM'\nUse PROGRAM as a spooler program for printing. If omitted, the\n'-l' and '-L' options of 'groff' are ignored.\n\n'res N'\nThe device resolution is N basic units per inch.\n\n'sizes S1 ... SN 0'\nThe device has fonts at S1, ..., SN scaled points (see below). The\nlist of sizes must be terminated by '0'. Each SI can also be a\nrange of sizes M-N. The list can extend over more than one line.\n\n'sizescale N'\nA typographical point is subdivided into N scaled points. The\ndefault is '1'. *Note Using Fractional Type Sizes::.\n\n'styles S1 ... SM'\nThe first M mounting positions are associated with styles S1, ...,\nSM.\n\n'tcommand'\nThe postprocessor can handle the 't' and 'u' intermediate output\ncommands.\n\n'unicode'\nThe output device supports the complete Unicode repertoire. This\ndirective is useful only for devices that produce character\nentities instead of glyphs.\n\nIf 'unicode' is present, no 'charset' section is required in the\nfont description files since the Unicode handling built into\n'groff' is used. However, if there are entries in a font\ndescription file's 'charset' section, they either override the\ndefault mappings for those particular characters or add new\nmappings (normally for composite characters).\n\nThe 'utf8', 'html', and 'xhtml' output devices use this directive.\n\n'unitwidth N'\nQuantities in the font description files are in basic units for\nfonts whose type size is N scaled points.\n\n'unscaledcharwidths'\nMake the font handling module always return unscaled character\nwidths. The 'grohtml' driver uses this directive.\n\n'usecharnamesinspecial'\nGNU 'troff' should encode special characters inside device control\ncommands; see *note Postprocessor Access::. The 'grohtml' driver\nuses this directive.\n\n'vert N'\nThe vertical motion quantum is N basic units. All vertical\nquantities are rounded to multiples of N.\n\n'charset'\nThis line and everything following it in the file are ignored. It\nis recognized for compatibility with other 'troff' implementations.\nIn GNU 'troff', character set repertoire is described on a per-font\nbasis.\n\nGNU 'troff' recognizes but ignores the directives 'spare1', 'spare2',\nand 'biggestfont'.\n\nThe 'res', 'unitwidth', 'fonts', and 'sizes' lines are mandatory.", "subsections": [] }, "Directives not listed above are ignored by GNU 'troff' but may be used": { "content": "by postprocessors to obtain further information about the device.\n", "subsections": [] }, "File: groff.info, Node: Font Description File Format, Prev: DESC File Format, Up: Device and Font Description Files": { "content": "", "subsections": [] }, "On typesetting output devices, each font is typically available at": { "content": "multiple sizes. While paper measurements in the device description file\nare in absolute units, measurements applicable to fonts must be\nproportional to the type size. 'groff' achieves this using the\nprecedent set by AT&T device-independent 'troff': one font size is\nchosen as a norm, and all others are scaled linearly relative to that\nbasis. The \"unit width\" is the number of basic units per point when the\nfont is rendered at this nominal size.\n\nFor instance, 'groff''s 'lbp' device uses a 'unitwidth' of 800. Its", "subsections": [] }, "Times roman font 'TR' has a 'spacewidth' of 833; this is also the width": { "content": "of its comma, period, centered period, and mathematical asterisk, while\nits 'M' is 2,963 basic units. Thus, an 'M' on the 'lbp' device is 2,963\nbasic units wide at a notional type size of 800 points.(1) (*note Font", "subsections": [] }, "Description File Format-Footnote-1::)": { "content": "A font description file has two sections. The first is a sequence of\ndirectives, and is parsed similarly to the 'DESC' file described above.", "subsections": [] }, "Except for the directive names that begin the second section, their": { "content": "ordering is immaterial. Later directives of the same name override\nearlier ones, spaces and tabs are handled in the same way, and the same\ncomment syntax is supported. Empty lines are ignored throughout.\n\n'name F'\nThe name of the font is F. 'DESC' is an invalid font name. Simple\nintegers are valid, but their use is discouraged.(2) (*note Font\nDescription File Format-Footnote-2::)\n\n'spacewidth N'\nThe width of an unadjusted inter-word space is N basic units.\n\nThe directives above must appear in the first section; those below\nare optional.\n\n'slant N'\nThe font's glyphs have a slant of N degrees; a positive N slants in\nthe direction of text flow.\n\n'ligatures LIG1 ... LIGN [0]'\nGlyphs LIG1, ..., LIGN are ligatures; possible ligatures are 'ff',\n'fi', 'fl', 'ffi' and 'ffl'. For compatibility with other 'troff'\nimplementations, the list of ligatures may be terminated with\na '0'. The list of ligatures must not extend over more than one\nline.\n\n'special'\nThe font is \"special\": when a glyph is requested that is not\npresent in the current font, it is sought in any mounted fonts that\nbear this property.\n\nOther directives in this section are ignored by GNU 'troff', but may\nbe used by postprocessors to obtain further information about the font.\n\nThe second section contains one or two subsections. These can appear\nin either order; the first one encountered commences the second section.", "subsections": [] }, "Each starts with a directive on a line by itself. A 'charset'": { "content": "subsection is mandatory unless the associated 'DESC' file contains the\n'unicode' directive. Another subsection, 'kernpairs', is optional.\n\nThe directive 'charset' starts the character set subsection.(3)\n(*note Font Description File Format-Footnote-3::) It precedes a series\nof glyph descriptions, one per line. Each such glyph description\ncomprises a set of fields separated by spaces or tabs and organized as\nfollows.\n\nNAME METRICS TYPE CODE [ENTITY-NAME] ['--' COMMENT]\n\nNAME identifies the glyph: if NAME is a printable character C, it\ncorresponds to the 'troff' ordinary character C. If NAME is a\nmulti-character sequence not beginning with '\\', it corresponds to the\nGNU 'troff' special character escape sequence '\\[NAME]'. A name\nconsisting of three minus signs, '---', is special and indicates that\nthe glyph is unnamed: such glyphs can be accessed only by the '\\N'\nescape sequence in 'troff'. A special character named '---' can still\nbe defined using 'char' and similar requests. The NAME '\\-' defines the\nminus sign glyph. Finally, NAME can be the unbreakable one-sixth and\none-twelfth space escape sequences, '\\|' and '\\^' (\"thin\" and \"hair\"\nspaces, respectively), in which case only the width metric described\nbelow is interpreted; a font can thus customize the widths of these\nspaces.\n\nThe form of the METRICS field is as follows.\n\nWIDTH[','[HEIGHT[','[DEPTH[','[ITALIC-CORRECTION\n[','[LEFT-ITALIC-CORRECTION[','[SUBSCRIPT-CORRECTION]]]]]]]]]]\n", "subsections": [] }, "There must not be any spaces, tabs, or newlines between these": { "content": "\"subfields\" (which have been split here into two lines only for better\nlegibility). The subfields are in basic units expressed as decimal\nintegers. Unspecified subfields default to '0'. Since there is no\nassociated binary format, these values are not required to fit into the\nC language data type 'char' as they are in AT&T device-independent\n'troff'.\n\nThe WIDTH subfield gives the width of the glyph. The HEIGHT subfield\ngives the height of the glyph (upward is positive); if a glyph does not\nextend above the baseline, it should be given a zero height, rather than\na negative height. The DEPTH subfield gives the depth of the glyph,\nthat is, the distance below the baseline to which the glyph extends\n(downward is positive); if a glyph does not extend below the baseline,\nit should be given a zero depth, rather than a negative depth. Italic\ncorrections are relevant to glyphs in italic or oblique styles. The\nITALIC-CORRECTION is the amount of space that should be added after an\noblique glyph to be followed immediately by an upright glyph. The\nLEFT-ITALIC-CORRECTION is the amount of space that should be added\nbefore an oblique glyph to be preceded immediately by an upright glyph.", "subsections": [] }, "The SUBSCRIPT-CORRECTION is the amount of space that should be added": { "content": "after an oblique glyph to be followed by a subscript; it should be less\nthan the italic correction.\n\nFor fonts used with typesetting devices, the TYPE field gives a\nfeatural description of the glyph: it is a bit mask recording whether\nthe glyph is an ascender, descender, both, or neither. When a '\\w'\nescape sequence is interpolated, these values are bitwise or-ed together\nfor each glyph and stored in the 'nr' register. In font descriptions\nfor terminal devices, all glyphs might have a type of zero, regardless\nof their appearance.\n\n'0'\nmeans the glyph lies entirely between the baseline and a horizontal\nline at the \"x-height\" of the font; typical examples are 'a', 'c',\nand 'x';\n\n'1'\nmeans the glyph descends below the baseline, like 'p';\n\n'2'\nmeans the glyph ascends above the font's x-height, like 'A' or 'b';\nand\n\n'3'\nmeans the glyph is both an ascender and a descender--this is true\nof parentheses in some fonts.\n\nThe CODE field gives a numeric identifier that the postprocessor uses\nto render the glyph. The glyph can be specified to 'troff' using this\ncode by means of the '\\N' escape sequence. CODE can be any integer.(4)\n(*note Font Description File Format-Footnote-4::)\n\nThe ENTITY-NAME field defines an identifier for the glyph that the\npostprocessor uses to print the GNU 'troff' glyph NAME. This field is\noptional; it was introduced so that the 'grohtml' output driver could\nencode its character set. For example, the glyph '\\[Po]' is represented\nby '£' in HTML 4.0. For efficiency, these data are now compiled\ndirectly into 'grohtml'. 'grops' uses the field to build sub-encoding\narrays for PostScript fonts containing more than 256 glyphs. Anything\non the line after the ENTITY-NAME field or '--' is ignored.\n\nA line in the 'charset' section can also have the form\n\nNAME \"\n\nidentifying NAME as another name for the glyph mentioned in the\npreceding line. Such aliases can be chained.\n\nThe directive 'kernpairs' starts a list of kerning adjustments to be\nmade to adjacent glyph pairs from this font. It contains a sequence of\nlines formatted as follows.\n\nG1 G2 N\n", "subsections": [] }, "The foregoing means that when glyph G1 is typeset immediately before G2,": { "content": "the space between them should be increased by N. Most kerning pairs\nshould have a negative value for N.\n", "subsections": [] }, "File: groff.info, Node: Copying This Manual, Next: Request Index, Prev: Font Description File Format, Up: Top": { "content": "", "subsections": [] }, "Appendix A Copying This Manual": { "content": "Version 1.3, 3 November 2008\n\nCopyright (C) 2000-2018 Free Software Foundation, Inc.\n\n\nEveryone is permitted to copy and distribute verbatim copies\nof this license document, but changing it is not allowed.\n\n0. PREAMBLE\n\nThe purpose of this License is to make a manual, textbook, or other\nfunctional and useful document \"free\" in the sense of freedom: to\nassure everyone the effective freedom to copy and redistribute it,\nwith or without modifying it, either commercially or\nnoncommercially. Secondarily, this License preserves for the\nauthor and publisher a way to get credit for their work, while not\nbeing considered responsible for modifications made by others.\n\nThis License is a kind of \"copyleft\", which means that derivative\nworks of the document must themselves be free in the same sense.\nIt complements the GNU General Public License, which is a copyleft\nlicense designed for free software.\n\nWe have designed this License in order to use it for manuals for\nfree software, because free software needs free documentation: a\nfree program should come with manuals providing the same freedoms\nthat the software does. But this License is not limited to\nsoftware manuals; it can be used for any textual work, regardless\nof subject matter or whether it is published as a printed book. We\nrecommend this License principally for works whose purpose is\ninstruction or reference.\n\n1. APPLICABILITY AND DEFINITIONS\n\nThis License applies to any manual or other work, in any medium,\nthat contains a notice placed by the copyright holder saying it can\nbe distributed under the terms of this License. Such a notice\ngrants a world-wide, royalty-free license, unlimited in duration,\nto use that work under the conditions stated herein. The\n\"Document\", below, refers to any such manual or work. Any member\nof the public is a licensee, and is addressed as \"you\". You accept\nthe license if you copy, modify or distribute the work in a way\nrequiring permission under copyright law.\n\nA \"Modified Version\" of the Document means any work containing the\nDocument or a portion of it, either copied verbatim, or with\nmodifications and/or translated into another language.\n\nA \"Secondary Section\" is a named appendix or a front-matter section\nof the Document that deals exclusively with the relationship of the\npublishers or authors of the Document to the Document's overall\nsubject (or to related matters) and contains nothing that could\nfall directly within that overall subject. (Thus, if the Document\nis in part a textbook of mathematics, a Secondary Section may not\nexplain any mathematics.) The relationship could be a matter of\nhistorical connection with the subject or with related matters, or\nof legal, commercial, philosophical, ethical or political position\nregarding them.\n\nThe \"Invariant Sections\" are certain Secondary Sections whose\ntitles are designated, as being those of Invariant Sections, in the\nnotice that says that the Document is released under this License.\nIf a section does not fit the above definition of Secondary then it\nis not allowed to be designated as Invariant. The Document may\ncontain zero Invariant Sections. If the Document does not identify\nany Invariant Sections then there are none.\n\nThe \"Cover Texts\" are certain short passages of text that are\nlisted, as Front-Cover Texts or Back-Cover Texts, in the notice\nthat says that the Document is released under this License. A\nFront-Cover Text may be at most 5 words, and a Back-Cover Text may\nbe at most 25 words.\n\nA \"Transparent\" copy of the Document means a machine-readable copy,\nrepresented in a format whose specification is available to the\ngeneral public, that is suitable for revising the document\nstraightforwardly with generic text editors or (for images composed\nof pixels) generic paint programs or (for drawings) some widely\navailable drawing editor, and that is suitable for input to text\nformatters or for automatic translation to a variety of formats\nsuitable for input to text formatters. A copy made in an otherwise\nTransparent file format whose markup, or absence of markup, has\nbeen arranged to thwart or discourage subsequent modification by\nreaders is not Transparent. An image format is not Transparent if\nused for any substantial amount of text. A copy that is not\n\"Transparent\" is called \"Opaque\".\n\nExamples of suitable formats for Transparent copies include plain\nASCII without markup, Texinfo input format, LaTeX input format,\nSGML or XML using a publicly available DTD, and standard-conforming\nsimple HTML, PostScript or PDF designed for human modification.\nExamples of transparent image formats include PNG, XCF and JPG.\nOpaque formats include proprietary formats that can be read and\nedited only by proprietary word processors, SGML or XML for which\nthe DTD and/or processing tools are not generally available, and\nthe machine-generated HTML, PostScript or PDF produced by some word\nprocessors for output purposes only.\n\nThe \"Title Page\" means, for a printed book, the title page itself,\nplus such following pages as are needed to hold, legibly, the\nmaterial this License requires to appear in the title page. For\nworks in formats which do not have any title page as such, \"Title\nPage\" means the text near the most prominent appearance of the\nwork's title, preceding the beginning of the body of the text.\n\nThe \"publisher\" means any person or entity that distributes copies\nof the Document to the public.\n\nA section \"Entitled XYZ\" means a named subunit of the Document\nwhose title either is precisely XYZ or contains XYZ in parentheses\nfollowing text that translates XYZ in another language. (Here XYZ\nstands for a specific section name mentioned below, such as\n\"Acknowledgements\", \"Dedications\", \"Endorsements\", or \"History\".)\nTo \"Preserve the Title\" of such a section when you modify the\nDocument means that it remains a section \"Entitled XYZ\" according\nto this definition.\n\nThe Document may include Warranty Disclaimers next to the notice\nwhich states that this License applies to the Document. These\nWarranty Disclaimers are considered to be included by reference in\nthis License, but only as regards disclaiming warranties: any other\nimplication that these Warranty Disclaimers may have is void and\nhas no effect on the meaning of this License.\n\n2. VERBATIM COPYING\n\nYou may copy and distribute the Document in any medium, either\ncommercially or noncommercially, provided that this License, the\ncopyright notices, and the license notice saying this License\napplies to the Document are reproduced in all copies, and that you\nadd no other conditions whatsoever to those of this License. You\nmay not use technical measures to obstruct or control the reading\nor further copying of the copies you make or distribute. However,\nyou may accept compensation in exchange for copies. If you\ndistribute a large enough number of copies you must also follow the\nconditions in section 3.\n\nYou may also lend copies, under the same conditions stated above,\nand you may publicly display copies.\n\n3. COPYING IN QUANTITY\n\nIf you publish printed copies (or copies in media that commonly\nhave printed covers) of the Document, numbering more than 100, and\nthe Document's license notice requires Cover Texts, you must\nenclose the copies in covers that carry, clearly and legibly, all\nthese Cover Texts: Front-Cover Texts on the front cover, and\nBack-Cover Texts on the back cover. Both covers must also clearly\nand legibly identify you as the publisher of these copies. The\nfront cover must present the full title with all words of the title\nequally prominent and visible. You may add other material on the\ncovers in addition. Copying with changes limited to the covers, as\nlong as they preserve the title of the Document and satisfy these\nconditions, can be treated as verbatim copying in other respects.\n\nIf the required texts for either cover are too voluminous to fit\nlegibly, you should put the first ones listed (as many as fit\nreasonably) on the actual cover, and continue the rest onto\nadjacent pages.\n\nIf you publish or distribute Opaque copies of the Document\nnumbering more than 100, you must either include a machine-readable\nTransparent copy along with each Opaque copy, or state in or with\neach Opaque copy a computer-network location from which the general\nnetwork-using public has access to download using public-standard\nnetwork protocols a complete Transparent copy of the Document, free\nof added material. If you use the latter option, you must take\nreasonably prudent steps, when you begin distribution of Opaque\ncopies in quantity, to ensure that this Transparent copy will\nremain thus accessible at the stated location until at least one\nyear after the last time you distribute an Opaque copy (directly or\nthrough your agents or retailers) of that edition to the public.\n\nIt is requested, but not required, that you contact the authors of\nthe Document well before redistributing any large number of copies,\nto give them a chance to provide you with an updated version of the\nDocument.\n\n4. MODIFICATIONS\n\nYou may copy and distribute a Modified Version of the Document\nunder the conditions of sections 2 and 3 above, provided that you\nrelease the Modified Version under precisely this License, with the\nModified Version filling the role of the Document, thus licensing\ndistribution and modification of the Modified Version to whoever\npossesses a copy of it. In addition, you must do these things in\nthe Modified Version:\n\nA. Use in the Title Page (and on the covers, if any) a title\ndistinct from that of the Document, and from those of previous\nversions (which should, if there were any, be listed in the\nHistory section of the Document). You may use the same title\nas a previous version if the original publisher of that\nversion gives permission.\n\nB. List on the Title Page, as authors, one or more persons or\nentities responsible for authorship of the modifications in\nthe Modified Version, together with at least five of the\nprincipal authors of the Document (all of its principal\nauthors, if it has fewer than five), unless they release you\nfrom this requirement.\n\nC. State on the Title page the name of the publisher of the\nModified Version, as the publisher.\n\nD. Preserve all the copyright notices of the Document.\n\nE. Add an appropriate copyright notice for your modifications\nadjacent to the other copyright notices.\n\nF. Include, immediately after the copyright notices, a license\nnotice giving the public permission to use the Modified\nVersion under the terms of this License, in the form shown in\nthe Addendum below.\n\nG. Preserve in that license notice the full lists of Invariant\nSections and required Cover Texts given in the Document's\nlicense notice.\n\nH. Include an unaltered copy of this License.\n\nI. Preserve the section Entitled \"History\", Preserve its Title,\nand add to it an item stating at least the title, year, new\nauthors, and publisher of the Modified Version as given on the\nTitle Page. If there is no section Entitled \"History\" in the\nDocument, create one stating the title, year, authors, and\npublisher of the Document as given on its Title Page, then add\nan item describing the Modified Version as stated in the\nprevious sentence.\n\nJ. Preserve the network location, if any, given in the Document\nfor public access to a Transparent copy of the Document, and\nlikewise the network locations given in the Document for\nprevious versions it was based on. These may be placed in the\n\"History\" section. You may omit a network location for a work\nthat was published at least four years before the Document\nitself, or if the original publisher of the version it refers\nto gives permission.\n\nK. For any section Entitled \"Acknowledgements\" or \"Dedications\",\nPreserve the Title of the section, and preserve in the section\nall the substance and tone of each of the contributor\nacknowledgements and/or dedications given therein.\n\nL. Preserve all the Invariant Sections of the Document, unaltered\nin their text and in their titles. Section numbers or the\nequivalent are not considered part of the section titles.\n\nM. Delete any section Entitled \"Endorsements\". Such a section\nmay not be included in the Modified Version.\n\nN. Do not retitle any existing section to be Entitled\n\"Endorsements\" or to conflict in title with any Invariant\nSection.\n\nO. Preserve any Warranty Disclaimers.\n\nIf the Modified Version includes new front-matter sections or\nappendices that qualify as Secondary Sections and contain no\nmaterial copied from the Document, you may at your option designate\nsome or all of these sections as invariant. To do this, add their\ntitles to the list of Invariant Sections in the Modified Version's\nlicense notice. These titles must be distinct from any other\nsection titles.\n\nYou may add a section Entitled \"Endorsements\", provided it contains\nnothing but endorsements of your Modified Version by various\nparties--for example, statements of peer review or that the text\nhas been approved by an organization as the authoritative\ndefinition of a standard.\n\nYou may add a passage of up to five words as a Front-Cover Text,\nand a passage of up to 25 words as a Back-Cover Text, to the end of\nthe list of Cover Texts in the Modified Version. Only one passage\nof Front-Cover Text and one of Back-Cover Text may be added by (or\nthrough arrangements made by) any one entity. If the Document\nalready includes a cover text for the same cover, previously added\nby you or by arrangement made by the same entity you are acting on\nbehalf of, you may not add another; but you may replace the old\none, on explicit permission from the previous publisher that added\nthe old one.\n\nThe author(s) and publisher(s) of the Document do not by this\nLicense give permission to use their names for publicity for or to\nassert or imply endorsement of any Modified Version.\n\n5. COMBINING DOCUMENTS\n\nYou may combine the Document with other documents released under\nthis License, under the terms defined in section 4 above for\nmodified versions, provided that you include in the combination all\nof the Invariant Sections of all of the original documents,\nunmodified, and list them all as Invariant Sections of your\ncombined work in its license notice, and that you preserve all\ntheir Warranty Disclaimers.\n\nThe combined work need only contain one copy of this License, and\nmultiple identical Invariant Sections may be replaced with a single\ncopy. If there are multiple Invariant Sections with the same name\nbut different contents, make the title of each such section unique\nby adding at the end of it, in parentheses, the name of the\noriginal author or publisher of that section if known, or else a\nunique number. Make the same adjustment to the section titles in\nthe list of Invariant Sections in the license notice of the\ncombined work.\n\nIn the combination, you must combine any sections Entitled\n\"History\" in the various original documents, forming one section\nEntitled \"History\"; likewise combine any sections Entitled\n\"Acknowledgements\", and any sections Entitled \"Dedications\". You\nmust delete all sections Entitled \"Endorsements.\"\n\n6. COLLECTIONS OF DOCUMENTS\n\nYou may make a collection consisting of the Document and other\ndocuments released under this License, and replace the individual\ncopies of this License in the various documents with a single copy\nthat is included in the collection, provided that you follow the\nrules of this License for verbatim copying of each of the documents\nin all other respects.\n\nYou may extract a single document from such a collection, and\ndistribute it individually under this License, provided you insert\na copy of this License into the extracted document, and follow this\nLicense in all other respects regarding verbatim copying of that\ndocument.\n\n7. AGGREGATION WITH INDEPENDENT WORKS\n\nA compilation of the Document or its derivatives with other\nseparate and independent documents or works, in or on a volume of a\nstorage or distribution medium, is called an \"aggregate\" if the\ncopyright resulting from the compilation is not used to limit the\nlegal rights of the compilation's users beyond what the individual\nworks permit. When the Document is included in an aggregate, this\nLicense does not apply to the other works in the aggregate which\nare not themselves derivative works of the Document.\n\nIf the Cover Text requirement of section 3 is applicable to these\ncopies of the Document, then if the Document is less than one half\nof the entire aggregate, the Document's Cover Texts may be placed\non covers that bracket the Document within the aggregate, or the\nelectronic equivalent of covers if the Document is in electronic\nform. Otherwise they must appear on printed covers that bracket\nthe whole aggregate.\n\n8. TRANSLATION\n\nTranslation is considered a kind of modification, so you may\ndistribute translations of the Document under the terms of section\n4. Replacing Invariant Sections with translations requires special\npermission from their copyright holders, but you may include\ntranslations of some or all Invariant Sections in addition to the\noriginal versions of these Invariant Sections. You may include a\ntranslation of this License, and all the license notices in the\nDocument, and any Warranty Disclaimers, provided that you also\ninclude the original English version of this License and the\noriginal versions of those notices and disclaimers. In case of a\ndisagreement between the translation and the original version of\nthis License or a notice or disclaimer, the original version will\nprevail.\n\nIf a section in the Document is Entitled \"Acknowledgements\",\n\"Dedications\", or \"History\", the requirement (section 4) to\nPreserve its Title (section 1) will typically require changing the\nactual title.\n\n9. TERMINATION\n\nYou may not copy, modify, sublicense, or distribute the Document\nexcept as expressly provided under this License. Any attempt\notherwise to copy, modify, sublicense, or distribute it is void,\nand will automatically terminate your rights under this License.\n\nHowever, if you cease all violation of this License, then your\nlicense from a particular copyright holder is reinstated (a)\nprovisionally, unless and until the copyright holder explicitly and\nfinally terminates your license, and (b) permanently, if the\ncopyright holder fails to notify you of the violation by some\nreasonable means prior to 60 days after the cessation.\n\nMoreover, your license from a particular copyright holder is\nreinstated permanently if the copyright holder notifies you of the\nviolation by some reasonable means, this is the first time you have\nreceived notice of violation of this License (for any work) from\nthat copyright holder, and you cure the violation prior to 30 days\nafter your receipt of the notice.\n\nTermination of your rights under this section does not terminate\nthe licenses of parties who have received copies or rights from you\nunder this License. If your rights have been terminated and not\npermanently reinstated, receipt of a copy of some or all of the\nsame material does not give you any rights to use it.\n\n10. FUTURE REVISIONS OF THIS LICENSE\n\nThe Free Software Foundation may publish new, revised versions of\nthe GNU Free Documentation License from time to time. Such new\nversions will be similar in spirit to the present version, but may\ndiffer in detail to address new problems or concerns. See\n.\n\nEach version of the License is given a distinguishing version\nnumber. If the Document specifies that a particular numbered\nversion of this License \"or any later version\" applies to it, you\nhave the option of following the terms and conditions either of\nthat specified version or of any later version that has been\npublished (not as a draft) by the Free Software Foundation. If the\nDocument does not specify a version number of this License, you may\nchoose any version ever published (not as a draft) by the Free\nSoftware Foundation. If the Document specifies that a proxy can\ndecide which future versions of this License can be used, that\nproxy's public statement of acceptance of a version permanently\nauthorizes you to choose that version for the Document.\n\n11. RELICENSING\n\n\"Massive Multiauthor Collaboration Site\" (or \"MMC Site\") means any\nWorld Wide Web server that publishes copyrightable works and also\nprovides prominent facilities for anybody to edit those works. A\npublic wiki that anybody can edit is an example of such a server.\nA \"Massive Multiauthor Collaboration\" (or \"MMC\") contained in the\nsite means any set of copyrightable works thus published on the MMC\nsite.\n\n\"CC-BY-SA\" means the Creative Commons Attribution-Share Alike 3.0\nlicense published by Creative Commons Corporation, a not-for-profit\ncorporation with a principal place of business in San Francisco,\nCalifornia, as well as future copyleft versions of that license\npublished by that same organization.\n\n\"Incorporate\" means to publish or republish a Document, in whole or\nin part, as part of another Document.\n\nAn MMC is \"eligible for relicensing\" if it is licensed under this\nLicense, and if all works that were first published under this\nLicense somewhere other than this MMC, and subsequently\nincorporated in whole or in part into the MMC, (1) had no cover\ntexts or invariant sections, and (2) were thus incorporated prior\nto November 1, 2008.\n\nThe operator of an MMC Site may republish an MMC contained in the\nsite under CC-BY-SA on the same site at any time before August 1,\n2009, provided the MMC is eligible for relicensing.\n", "subsections": [ { "name": "ADDENDUM: How to use this License for your documents", "content": "" } ] }, "To use this License in a document you have written, include a copy of": { "content": "the License in the document and put the following copyright and license\nnotices just after the title page:\n\nCopyright (C) YEAR YOUR NAME.\nPermission is granted to copy, distribute and/or modify this document\nunder the terms of the GNU Free Documentation License, Version 1.3\nor any later version published by the Free Software Foundation;\nwith no Invariant Sections, no Front-Cover Texts, and no Back-Cover\nTexts. A copy of the license is included in the section entitled ``GNU\nFree Documentation License''.\n\nIf you have Invariant Sections, Front-Cover Texts and Back-Cover\nTexts, replace the \"with...Texts.\" line with this:\n\nwith the Invariant Sections being LIST THEIR TITLES, with\nthe Front-Cover Texts being LIST, and with the Back-Cover Texts\nbeing LIST.\n\nIf you have Invariant Sections without Cover Texts, or some other\ncombination of the three, merge those two alternatives to suit the\nsituation.\n\nIf your document contains nontrivial examples of program code, we\nrecommend releasing these examples in parallel under your choice of free\nsoftware license, such as the GNU General Public License, to permit\ntheir use in free software.\n", "subsections": [] }, "File: groff.info, Node: Request Index, Next: Escape Sequence Index, Prev: Copying This Manual, Up: Top": { "content": "", "subsections": [] }, "Appendix B Request Index": { "content": "", "subsections": [] }, "Request names appear without a leading control character; the defaults": { "content": "are '.' for the regular control character and ''' for the no-break\ncontrol character.\n\n\n* Menu:\n\n* ab: Debugging. (line 55)\n* ad: Manipulating Filling and Adjustment.\n(line 83)\n* af: Assigning Register Formats.\n(line 12)\n* aln: Setting Registers. (line 110)\n* als: Strings. (line 198)\n* am: Writing Macros. (line 126)\n* am1: Writing Macros. (line 127)\n* ami: Writing Macros. (line 128)\n* ami1: Writing Macros. (line 129)\n* as: Strings. (line 114)\n* as1: Strings. (line 115)\n* asciify: Diversions. (line 208)\n* backtrace: Debugging. (line 104)\n* bd: Artificial Fonts. (line 95)\n* blm: Blank Line Traps. (line 7)\n* box: Diversions. (line 63)\n* boxa: Diversions. (line 64)\n* bp: Page Control. (line 11)\n* br: Manipulating Filling and Adjustment.\n(line 39)\n* break: while. (line 72)\n* brp: Manipulating Filling and Adjustment.\n(line 156)\n* c2: Control Characters. (line 29)\n* cc: Control Characters. (line 23)\n* ce: Manipulating Filling and Adjustment.\n(line 208)\n* cf: I/O. (line 58)\n* cflags: Using Symbols. (line 252)\n* ch: Page Location Traps. (line 114)\n* char: Using Symbols. (line 351)\n* chop: Strings. (line 145)\n* class: Character Classes. (line 12)\n* close: I/O. (line 240)\n* color: Colors. (line 15)\n* composite: Using Symbols. (line 208)\n* continue: while. (line 76)\n* cp: Compatibility Mode. (line 16)\n* cs: Artificial Fonts. (line 125)\n* cu: Artificial Fonts. (line 86)\n* da: Diversions. (line 32)\n* de: Writing Macros. (line 14)\n* de1: Writing Macros. (line 86)\n* defcolor: Colors. (line 27)\n* dei: Writing Macros. (line 108)\n* dei1: Writing Macros. (line 109)\n* device: Postprocessor Access.\n(line 15)\n* devicem: Postprocessor Access.\n(line 45)\n* di: Diversions. (line 31)\n* do: Compatibility Mode. (line 27)\n* ds: ms Document Control Settings.\n(line 15)\n* ds <1>: Strings. (line 24)\n* ds1: Strings. (line 25)\n* dt: Diversion Traps. (line 11)\n* ec: Using Escape Sequences.\n(line 76)\n* ecr: Using Escape Sequences.\n(line 102)\n* ecs: Using Escape Sequences.\n(line 101)\n* el: if-else. (line 8)\n* em: End-of-input Traps. (line 7)\n* eo: Using Escape Sequences.\n(line 71)\n* ev: Environments. (line 46)\n* evc: Environments. (line 100)\n* ex: Debugging. (line 60)\n* fam: Font Families. (line 21)\n* fc: Fields. (line 18)\n* fchar: Using Symbols. (line 352)\n* fcolor: Colors. (line 85)\n* fi: Manipulating Filling and Adjustment.\n(line 66)\n* fl: Debugging. (line 95)\n* fp: Font Positions. (line 16)\n* fschar: Using Symbols. (line 353)\n* fspecial: Special Fonts. (line 18)\n* ft: Selecting Fonts. (line 11)\n* ftr: Selecting Fonts. (line 69)\n* fzoom: Selecting Fonts. (line 83)\n* gcolor: Colors. (line 57)\n* hc: Manipulating Hyphenation.\n(line 88)\n* hcode: Manipulating Hyphenation.\n(line 293)\n* hla: Manipulating Hyphenation.\n(line 327)\n* hlm: Manipulating Hyphenation.\n(line 340)\n* hpf: Manipulating Hyphenation.\n(line 233)\n* hpfa: Manipulating Hyphenation.\n(line 234)\n* hpfcode: Manipulating Hyphenation.\n(line 235)\n* hw: Manipulating Hyphenation.\n(line 22)\n* hy: Manipulating Hyphenation.\n(line 120)\n* hym: Manipulating Hyphenation.\n(line 354)\n* hys: Manipulating Hyphenation.\n(line 369)\n* ie: if-else. (line 7)\n* if: if-then. (line 7)\n* ig: Comments. (line 54)\n* in: Line Layout. (line 86)\n* it: Input Line Traps. (line 7)\n* itc: Input Line Traps. (line 8)\n* kern: Ligatures and Kerning.\n(line 41)\n* lc: Leaders. (line 22)\n* length: Strings. (line 135)\n* lf: Debugging. (line 31)\n* lg: Ligatures and Kerning.\n(line 23)\n* linetabs: Tabs and Fields. (line 139)\n* ll: Line Layout. (line 138)\n* ls: Manipulating Spacing.\n(line 57)\n* lsm: Leading Space Traps. (line 7)\n* lt: Page Layout. (line 53)\n* mc: Miscellaneous. (line 110)\n* mk: Page Motions. (line 10)\n* mso: I/O. (line 49)\n* msoquiet: I/O. (line 50)\n* na: Manipulating Filling and Adjustment.\n(line 150)\n* ne: Page Control. (line 31)\n* nf: Manipulating Filling and Adjustment.\n(line 74)\n* nh: Manipulating Hyphenation.\n(line 228)\n* nm: Miscellaneous. (line 9)\n* nn: Miscellaneous. (line 74)\n* nop: if-then. (line 26)\n* nr: ms Document Control Settings.\n(line 11)\n* nr <1>: Setting Registers. (line 10)\n* nr <2>: Setting Registers. (line 64)\n* nr <3>: Auto-increment. (line 14)\n* nroff: troff and nroff Modes.\n(line 33)\n* ns: Manipulating Spacing.\n(line 116)\n* nx: I/O. (line 90)\n* open: I/O. (line 207)\n* opena: I/O. (line 208)\n* os: Page Control. (line 66)\n* output: Diversions. (line 195)\n* pc: Page Layout. (line 68)\n* pev: Debugging. (line 78)\n* pi: I/O. (line 149)\n* pl: Page Layout. (line 9)\n* pm: Debugging. (line 82)\n* pn: Page Layout. (line 23)\n* pnr: Debugging. (line 86)\n* po: Line Layout. (line 60)\n* ps: Changing the Type Size.\n(line 7)\n* psbb: Miscellaneous. (line 158)\n* pso: I/O. (line 38)\n* ptr: Debugging. (line 90)\n* pvs: Changing the Vertical Spacing.\n(line 48)\n* rchar: Using Symbols. (line 410)\n* rd: I/O. (line 95)\n* return: Writing Macros. (line 163)\n* rfschar: Using Symbols. (line 411)\n* rj: Manipulating Filling and Adjustment.\n(line 247)\n* rm: Strings. (line 193)\n* rn: Strings. (line 190)\n* rnn: Setting Registers. (line 105)\n* rr: Setting Registers. (line 99)\n* rs: Manipulating Spacing.\n(line 117)\n* rt: Page Motions. (line 11)\n* schar: Using Symbols. (line 354)\n* shc: Manipulating Hyphenation.\n(line 97)\n* shift: Parameters. (line 30)\n* sizes: Changing the Type Size.\n(line 71)\n* so: I/O. (line 9)\n* soquiet: I/O. (line 10)\n* sp: Manipulating Spacing.\n(line 10)\n* special: Special Fonts. (line 17)\n* spreadwarn: Debugging. (line 135)\n* ss: Manipulating Filling and Adjustment.\n(line 267)\n* stringdown: Strings. (line 170)\n* stringup: Strings. (line 171)\n* sty: Font Families. (line 62)\n* substring: Strings. (line 153)\n* sv: Page Control. (line 65)\n* sy: I/O. (line 171)\n* ta: Tabs and Fields. (line 13)\n* tag: Postprocessor Access.\n(line 58)\n* taga: Postprocessor Access.\n(line 59)\n* tc: Tabs and Fields. (line 127)\n* ti: Line Layout. (line 110)\n* tkf: Ligatures and Kerning.\n(line 60)\n* tl: Page Layout. (line 39)\n* tm: Debugging. (line 43)\n* tm1: Debugging. (line 44)\n* tmc: Debugging. (line 45)\n* tr: Character Translations.\n(line 13)\n* trf: I/O. (line 57)\n* trin: Character Translations.\n(line 14)\n* trnt: Character Translations.\n(line 79)\n* troff: troff and nroff Modes.\n(line 25)\n* uf: Artificial Fonts. (line 90)\n* ul: Artificial Fonts. (line 64)\n* unformat: Diversions. (line 233)\n* vpt: Vertical Position Traps.\n(line 13)\n* vs: Changing the Vertical Spacing.\n(line 7)\n* warn: Debugging. (line 154)\n* warnscale: Debugging. (line 131)\n* wh: Page Location Traps. (line 11)\n* while: while. (line 10)\n* write: I/O. (line 219)\n* writec: I/O. (line 220)\n* writem: I/O. (line 231)\n", "subsections": [] }, "File: groff.info, Node: Escape Sequence Index, Next: Operator Index, Prev: Request Index, Up: Top": { "content": "", "subsections": [] }, "Appendix C Escape Sequence Index": { "content": "The escape character, '\\' by default, is always followed by at least one\nmore input character, making an escape sequence. Any input token '\\X'\nwith X not in the list below emits a warning and interpolates glyph X.\nNote the entries for '\\.', which may be obscured by the leader dots, and\nfor '\\' and '\\', which are sorted alphabetically, not by code\npoint order.\n\n\n* Menu:\n\n* \\: Using Escape Sequences.\n(line 8)\n* \\ <1>: Using Symbols. (line 137)\n* \\: Using Symbols. (line 247)\n* \\-: Using Symbols. (line 244)\n* \\,: Italic Corrections. (line 20)\n* \\:: Manipulating Hyphenation.\n(line 57)\n* \\!: Diversions. (line 153)\n* \\?: Diversions. (line 154)\n* \\.: Copy Mode. (line 46)\n* \\': Using Symbols. (line 237)\n* \\\": Comments. (line 10)\n* \\(: Using Symbols. (line 139)\n* \\): Dummy Characters. (line 63)\n* \\[: Using Symbols. (line 139)\n* \\{: Conditional Blocks. (line 12)\n* \\{ <1>: Conditional Blocks. (line 13)\n* \\}: Conditional Blocks. (line 13)\n* \\*: Strings. (line 26)\n* \\/: Italic Corrections. (line 10)\n* \\\\: Copy Mode. (line 21)\n* \\&: Dummy Characters. (line 13)\n* \\#: Comments. (line 44)\n* \\%: Manipulating Hyphenation.\n(line 56)\n* \\`: Using Symbols. (line 241)\n* \\^: Page Motions. (line 152)\n* \\|: Page Motions. (line 147)\n* \\~: Manipulating Filling and Adjustment.\n(line 53)\n* \\$: Parameters. (line 22)\n* \\$@: Parameters. (line 43)\n* \\$*: Parameters. (line 42)\n* \\$^: Parameters. (line 44)\n* \\$0: Parameters. (line 77)\n* \\0: Page Motions. (line 157)\n* \\A: Identifiers. (line 60)\n* \\a: Leaders. (line 19)\n* \\B: Numeric Expressions. (line 180)\n* \\b: Drawing Geometric Objects.\n(line 184)\n* \\c: Line Continuation. (line 39)\n* \\C: Using Symbols. (line 199)\n* \\d: Page Motions. (line 108)\n* \\D: Drawing Geometric Objects.\n(line 92)\n* \\e: Using Escape Sequences.\n(line 64)\n* \\E: Copy Mode. (line 101)\n* \\f: Selecting Fonts. (line 12)\n* \\F: Font Families. (line 23)\n* \\g: Assigning Register Formats.\n(line 70)\n* \\H: Artificial Fonts. (line 13)\n* \\h: Page Motions. (line 125)\n* \\k: Page Motions. (line 225)\n* \\l: Drawing Geometric Objects.\n(line 17)\n* \\L: Drawing Geometric Objects.\n(line 43)\n* \\m: Colors. (line 58)\n* \\M: Colors. (line 86)\n* \\n: Interpolating Registers.\n(line 9)\n* \\n <1>: Auto-increment. (line 23)\n* \\N: Using Symbols. (line 216)\n* \\newline: Line Continuation. (line 11)\n* \\o: Page Motions. (line 240)\n* \\O: Suppressing Output. (line 7)\n* \\p: Manipulating Filling and Adjustment.\n(line 157)\n* \\R: Setting Registers. (line 11)\n* \\R <1>: Setting Registers. (line 66)\n* \\r: Page Motions. (line 106)\n* \\: Line Continuation. (line 11)\n* \\S: Artificial Fonts. (line 44)\n* \\s: Changing the Type Size.\n(line 10)\n* \\: Page Motions. (line 141)\n* \\space: Page Motions. (line 141)\n* \\t: Tabs and Fields. (line 10)\n* \\u: Page Motions. (line 107)\n* \\v: Page Motions. (line 81)\n* \\V: I/O. (line 256)\n* \\w: Page Motions. (line 163)\n* \\x: Manipulating Spacing.\n(line 69)\n* \\X: Postprocessor Access.\n(line 16)\n* \\Y: Postprocessor Access.\n(line 46)\n* \\z: Page Motions. (line 245)\n* \\Z: Page Motions. (line 250)\n", "subsections": [] }, "File: groff.info, Node: Operator Index, Next: Register Index, Prev: Escape Sequence Index, Up: Top": { "content": "", "subsections": [] }, "Appendix D Operator Index": { "content": "* Menu:\n\n* -: Numeric Expressions. (line 17)\n* - <1>: Numeric Expressions. (line 23)\n* - (unary): Numeric Expressions. (line 115)\n* ;: Numeric Expressions. (line 48)\n* !: Numeric Expressions. (line 84)\n* (: Numeric Expressions. (line 104)\n* ): Numeric Expressions. (line 104)\n* *: Numeric Expressions. (line 17)\n* /: Numeric Expressions. (line 17)\n* &: Numeric Expressions. (line 80)\n* %: Numeric Expressions. (line 17)\n* +: Numeric Expressions. (line 17)\n* + <1>: Numeric Expressions. (line 23)\n* + (unary): Numeric Expressions. (line 115)\n* <: Numeric Expressions. (line 74)\n* : Numeric Expressions. (line 80)\n* =: Numeric Expressions. (line 74)\n* ==: Numeric Expressions. (line 74)\n* >: Numeric Expressions. (line 74)\n* >?: Numeric Expressions. (line 65)\n* >=: Numeric Expressions. (line 74)\n* |: Numeric Expressions. (line 129)\n", "subsections": [] }, "File: groff.info, Node: Register Index, Next: Macro Index, Prev: Operator Index, Up: Top": { "content": "", "subsections": [] }, "Appendix E Register Index": { "content": "", "subsections": [] }, "The macro package or program a specific register belongs to is appended": { "content": "in brackets.\n\nA register name 'x' consisting of exactly one character can be\naccessed as '\\nx'. A register name 'xx' consisting of exactly two\ncharacters can be accessed as '\\n(xx'. Register names 'xxx' of any\nlength can be accessed as '\\n[xxx]'.\n\n\n* Menu:\n\n* .$: Parameters. (line 14)\n* .A: Built-in Registers. (line 25)\n* .a: Manipulating Spacing.\n(line 70)\n* .b: Artificial Fonts. (line 97)\n* .br: Control Characters. (line 39)\n* .c: Built-in Registers. (line 29)\n* .C: Compatibility Mode. (line 17)\n* .cdp: Environments. (line 125)\n* .ce: Manipulating Filling and Adjustment.\n(line 209)\n* .cht: Environments. (line 124)\n* .color: Colors. (line 16)\n* .cp: Compatibility Mode. (line 28)\n* .csk: Environments. (line 126)\n* .d: Diversions. (line 88)\n* .ev: Environments. (line 47)\n* .F: Built-in Registers. (line 34)\n* .f: Font Positions. (line 17)\n* .fam: Font Families. (line 22)\n* .fn: Selecting Fonts. (line 15)\n* .fp: Font Positions. (line 18)\n* .g: Built-in Registers. (line 37)\n* .H: Motion Quanta. (line 14)\n* .h: Diversions. (line 95)\n* .height: Artificial Fonts. (line 16)\n* .hla: Manipulating Hyphenation.\n(line 328)\n* .hlc: Manipulating Hyphenation.\n(line 342)\n* .hlm: Manipulating Hyphenation.\n(line 341)\n* .hy: Manipulating Hyphenation.\n(line 121)\n* .hym: Manipulating Hyphenation.\n(line 355)\n* .hys: Manipulating Hyphenation.\n(line 370)\n* .i: Line Layout. (line 89)\n* .in: Line Layout. (line 113)\n* .int: Line Continuation. (line 40)\n* .j: Manipulating Filling and Adjustment.\n(line 84)\n* .k: Page Motions. (line 236)\n* .kern: Ligatures and Kerning.\n(line 42)\n* .L: Manipulating Spacing.\n(line 58)\n* .l: Line Layout. (line 141)\n* .lg: Ligatures and Kerning.\n(line 24)\n* .linetabs: Tabs and Fields. (line 140)\n* .ll: Line Layout. (line 142)\n* .lt: Page Layout. (line 56)\n* .m: Colors. (line 61)\n* .M: Colors. (line 89)\n* .n: Environments. (line 141)\n* .ne: Page Location Traps. (line 165)\n* .nm: Miscellaneous. (line 11)\n* .nn: Miscellaneous. (line 75)\n* .ns: Manipulating Spacing.\n(line 118)\n* .o: Line Layout. (line 63)\n* .O: Suppressing Output. (line 60)\n* .P: Built-in Registers. (line 41)\n* .p: Page Layout. (line 12)\n* .pe: Page Location Traps. (line 184)\n* .pn: Page Layout. (line 26)\n* .ps: Using Fractional Type Sizes.\n(line 31)\n* .psr: Using Fractional Type Sizes.\n(line 46)\n* .pvs: Changing the Vertical Spacing.\n(line 51)\n* .R: Built-in Registers. (line 45)\n* .rj: Manipulating Filling and Adjustment.\n(line 248)\n* .s: Changing the Type Size.\n(line 11)\n* .slant: Artificial Fonts. (line 45)\n* .sr: Using Fractional Type Sizes.\n(line 47)\n* .ss: Manipulating Filling and Adjustment.\n(line 268)\n* .sss: Manipulating Filling and Adjustment.\n(line 269)\n* .sty: Font Families. (line 63)\n* .T: Built-in Registers. (line 49)\n* .t: Page Location Traps. (line 106)\n* .tabs: Tabs and Fields. (line 14)\n* .trunc: Page Location Traps. (line 173)\n* .U: Built-in Registers. (line 53)\n* .u: Manipulating Filling and Adjustment.\n(line 67)\n* .V: Motion Quanta. (line 15)\n* .v: Changing the Vertical Spacing.\n(line 10)\n* .vpt: Vertical Position Traps.\n(line 14)\n* .w: Environments. (line 123)\n* .warn: Debugging. (line 155)\n* .x: Built-in Registers. (line 57)\n* .y: Built-in Registers. (line 61)\n* .Y: Built-in Registers. (line 65)\n* .z: Diversions. (line 87)\n* .zoom: Selecting Fonts. (line 84)\n* %: Page Layout. (line 68)\n* % <1>: Page Control. (line 14)\n* $$: Built-in Registers. (line 69)\n* c.: Built-in Registers. (line 30)\n* ct: Page Motions. (line 168)\n* DD [ms]: ms Document Control Settings.\n(line 301)\n* DI [ms]: ms Document Control Settings.\n(line 310)\n* dl: Diversions. (line 114)\n* dn: Diversions. (line 113)\n* dw: Built-in Registers. (line 87)\n* dy: Built-in Registers. (line 90)\n* FF [ms]: ms Document Control Settings.\n(line 241)\n* FI [ms]: ms Document Control Settings.\n(line 234)\n* FM [ms]: ms Document Control Settings.\n(line 60)\n* FPD [ms]: ms Document Control Settings.\n(line 282)\n* FPS [ms]: ms Document Control Settings.\n(line 268)\n* FVS [ms]: ms Document Control Settings.\n(line 275)\n* GROWPS [ms]: ms Document Control Settings.\n(line 199)\n* GS [ms]: Differences from AT&T ms.\n(line 90)\n* HM [ms]: ms Document Control Settings.\n(line 53)\n* HORPHANS [ms]: ms Document Control Settings.\n(line 210)\n* hours: Built-in Registers. (line 84)\n* hp: Page Motions. (line 233)\n* HY [ms]: ms Document Control Settings.\n(line 129)\n* LL [ms]: ms Document Control Settings.\n(line 34)\n* llx: Miscellaneous. (line 159)\n* lly: Miscellaneous. (line 160)\n* ln: Miscellaneous. (line 10)\n* lsn: Leading Space Traps. (line 8)\n* lss: Leading Space Traps. (line 9)\n* LT [ms]: ms Document Control Settings.\n(line 43)\n* MINGW [ms]: ms Document Control Settings.\n(line 323)\n* minutes: Built-in Registers. (line 81)\n* mo: Built-in Registers. (line 93)\n* nl: Page Control. (line 76)\n* opmaxx: Suppressing Output. (line 23)\n* opmaxy: Suppressing Output. (line 23)\n* opminx: Suppressing Output. (line 23)\n* opminy: Suppressing Output. (line 23)\n* PD [ms]: ms Document Control Settings.\n(line 158)\n* PI [ms]: ms Document Control Settings.\n(line 150)\n* PO [ms]: ms Document Control Settings.\n(line 25)\n* PORPHANS [ms]: ms Document Control Settings.\n(line 173)\n* PS [ms]: ms Document Control Settings.\n(line 115)\n* PSINCR [ms]: ms Document Control Settings.\n(line 188)\n* QI [ms]: ms Document Control Settings.\n(line 165)\n* rsb: Page Motions. (line 167)\n* rst: Page Motions. (line 166)\n* sb: Page Motions. (line 165)\n* seconds: Built-in Registers. (line 78)\n* skw: Page Motions. (line 170)\n* slimit: Debugging. (line 125)\n* ssc: Page Motions. (line 169)\n* st: Page Motions. (line 164)\n* systat: I/O. (line 172)\n* TC-MARGIN [ms]: ms Document Control Settings.\n(line 331)\n* urx: Miscellaneous. (line 161)\n* ury: Miscellaneous. (line 162)\n* VS [ms]: ms Document Control Settings.\n(line 122)\n* year: Built-in Registers. (line 96)\n* yr: Built-in Registers. (line 99)\n", "subsections": [] }, "File: groff.info, Node: Macro Index, Next: String Index, Prev: Register Index, Up: Top": { "content": "", "subsections": [] }, "Appendix F Macro Index": { "content": "The macro package a specific macro belongs to is appended in brackets.\nThey appear without the leading control character (normally '.').\n\n\n* Menu:\n\n* [ [ms]: ms Insertions. (line 38)\n* ] [ms]: ms Insertions. (line 39)\n* 1C [ms]: ms Multiple Columns. (line 14)\n* 2C [ms]: ms Multiple Columns. (line 17)\n* AB [ms]: ms Document Description Macros.\n(line 61)\n* AE [ms]: ms Document Description Macros.\n(line 68)\n* AI [ms]: ms Document Description Macros.\n(line 44)\n* AM [ms]: ms Legacy Features. (line 44)\n* AU [ms]: ms Document Description Macros.\n(line 38)\n* B [ms]: Typeface and decoration.\n(line 12)\n* B1 [ms]: ms keeps and displays.\n(line 37)\n* B2 [ms]: ms keeps and displays.\n(line 38)\n* BD [ms]: ms keeps and displays.\n(line 78)\n* BI [ms]: Typeface and decoration.\n(line 25)\n* BT [man]: Optional man extensions.\n(line 21)\n* BX [ms]: Typeface and decoration.\n(line 33)\n* CD [ms]: ms keeps and displays.\n(line 84)\n* CT [man]: Optional man extensions.\n(line 36)\n* CW [man]: Optional man extensions.\n(line 39)\n* CW [ms]: Typeface and decoration.\n(line 29)\n* DA [ms]: ms Document Description Macros.\n(line 51)\n* De [man]: Optional man extensions.\n(line 46)\n* DE [ms]: ms keeps and displays.\n(line 93)\n* Ds [man]: Optional man extensions.\n(line 43)\n* DS [ms]: ms keeps and displays.\n(line 68)\n* DS [ms] <1>: ms keeps and displays.\n(line 72)\n* DS [ms] <2>: ms keeps and displays.\n(line 77)\n* DS [ms] <3>: ms keeps and displays.\n(line 83)\n* DS [ms] <4>: ms keeps and displays.\n(line 88)\n* EE [man]: Optional man extensions.\n(line 53)\n* EF [ms]: ms Headers and Footers.\n(line 23)\n* EH [ms]: ms Headers and Footers.\n(line 21)\n* EN [ms]: ms Insertions. (line 31)\n* EQ [ms]: ms Insertions. (line 30)\n* EX [man]: Optional man extensions.\n(line 49)\n* FE [ms]: ms Footnotes. (line 21)\n* FS [ms]: ms Footnotes. (line 20)\n* G [man]: Optional man extensions.\n(line 56)\n* GL [man]: Optional man extensions.\n(line 61)\n* HB [man]: Optional man extensions.\n(line 66)\n* I [ms]: Typeface and decoration.\n(line 22)\n* ID [ms]: ms keeps and displays.\n(line 73)\n* IP [ms]: Paragraphs in ms. (line 23)\n* KE [ms]: ms keeps and displays.\n(line 25)\n* KF [ms]: ms keeps and displays.\n(line 24)\n* KS [ms]: ms keeps and displays.\n(line 23)\n* LD [ms]: ms keeps and displays.\n(line 69)\n* LG [ms]: Typeface and decoration.\n(line 43)\n* LP [ms]: Paragraphs in ms. (line 16)\n* MC [ms]: ms Multiple Columns. (line 20)\n* MS [man]: Optional man extensions.\n(line 74)\n* ND [ms]: ms Document Description Macros.\n(line 56)\n* NE [man]: Optional man extensions.\n(line 86)\n* NH [ms]: Headings in ms. (line 15)\n* NL [ms]: Typeface and decoration.\n(line 55)\n* NT [man]: Optional man extensions.\n(line 79)\n* OF [ms]: ms Headers and Footers.\n(line 22)\n* OH [ms]: ms Headers and Footers.\n(line 20)\n* P1 [ms]: ms Headers and Footers.\n(line 32)\n* PE [ms]: ms Insertions. (line 23)\n* PF [ms]: ms Insertions. (line 24)\n* PN [man]: Optional man extensions.\n(line 89)\n* Pn [man]: Optional man extensions.\n(line 93)\n* PP [ms]: Paragraphs in ms. (line 19)\n* PS [ms]: ms Insertions. (line 22)\n* PT [man]: Optional man extensions.\n(line 16)\n* PX [ms]: ms TOC. (line 48)\n* QE [ms]: Paragraphs in ms. (line 36)\n* QP [ms]: Paragraphs in ms. (line 31)\n* QS [ms]: Paragraphs in ms. (line 35)\n* R [man]: Optional man extensions.\n(line 99)\n* R [ms]: Typeface and decoration.\n(line 18)\n* RD [ms]: ms keeps and displays.\n(line 89)\n* RE [ms]: Indented regions in ms.\n(line 15)\n* RN [man]: Optional man extensions.\n(line 102)\n* RP [ms]: ms Document Description Macros.\n(line 19)\n* RS [ms]: Indented regions in ms.\n(line 11)\n* SH [ms]: Headings in ms. (line 85)\n* SM [ms]: Typeface and decoration.\n(line 49)\n* TA [ms]: Tab Stops in ms. (line 10)\n* TB [man]: Optional man extensions.\n(line 71)\n* TC [ms]: ms TOC. (line 53)\n* TE [ms]: ms Insertions. (line 14)\n* TL [ms]: ms Document Description Macros.\n(line 33)\n* TS [ms]: ms Insertions. (line 13)\n* UL [ms]: Typeface and decoration.\n(line 39)\n* VE [man]: Optional man extensions.\n(line 109)\n* VS [man]: Optional man extensions.\n(line 105)\n* XA [ms]: ms TOC. (line 37)\n* XE [ms]: ms TOC. (line 38)\n* XH [ms]: ms TOC. (line 89)\n* XH-REPLACEMENT [ms]: ms TOC. (line 98)\n* XH-UPDATE-TOC [ms]: ms TOC. (line 103)\n* XN [ms]: ms TOC. (line 88)\n* XN-INIT [ms]: ms TOC. (line 102)\n* XN-REPLACEMENT [ms]: ms TOC. (line 97)\n* XP [ms]: Paragraphs in ms. (line 42)\n* XS [ms]: ms TOC. (line 36)\n", "subsections": [] }, "File: groff.info, Node: String Index, Next: File Keyword Index, Prev: Macro Index, Up: Top": { "content": "", "subsections": [] }, "Appendix G String Index": { "content": "", "subsections": [] }, "The macro package or program a that defines or uses each string is": { "content": "appended in brackets. (Only one string, '.T', is defined by the 'troff'\nformatter itself.) *Note Strings::.\n\n\n* Menu:\n\n* [ms]: ms Legacy Features. (line 71)\n* - [ms]: Typographical symbols in ms.\n(line 11)\n* , [ms]: ms Legacy Features. (line 34)\n* , [ms] <1>: ms Legacy Features. (line 62)\n* : [ms]: ms Legacy Features. (line 22)\n* : [ms] <1>: ms Legacy Features. (line 53)\n* ! [ms]: ms Legacy Features. (line 83)\n* ? [ms]: ms Legacy Features. (line 80)\n* . [ms]: ms Legacy Features. (line 74)\n* .T: Strings. (line 13)\n* .T <1>: Strings. (line 13)\n* ' [ms]: ms Legacy Features. (line 16)\n* ' [ms] <1>: ms Legacy Features. (line 47)\n* { [ms]: Typeface and decoration.\n(line 85)\n* } [ms]: Typeface and decoration.\n(line 86)\n* * [ms]: ms Footnotes. (line 11)\n* / [ms]: ms Legacy Features. (line 65)\n* ` [ms]: ms Legacy Features. (line 19)\n* ` [ms] <1>: ms Legacy Features. (line 50)\n* ^ [ms]: ms Legacy Features. (line 25)\n* ^ [ms] <1>: ms Legacy Features. (line 56)\n* < [ms]: Typeface and decoration.\n(line 89)\n* > [ms]: Typeface and decoration.\n(line 90)\n* ~ [ms]: ms Legacy Features. (line 28)\n* ~ [ms] <1>: ms Legacy Features. (line 59)\n* 3 [ms]: ms Legacy Features. (line 92)\n* 8 [ms]: ms Legacy Features. (line 86)\n* ABSTRACT [ms]: ms language and localization.\n(line 22)\n* ae [ms]: ms Legacy Features. (line 107)\n* Ae [ms]: ms Legacy Features. (line 110)\n* C [ms]: ms Legacy Features. (line 31)\n* CF [ms]: ms Document Control Settings.\n(line 98)\n* CH [ms]: ms Document Control Settings.\n(line 77)\n* d- [ms]: ms Legacy Features. (line 95)\n* D- [ms]: ms Legacy Features. (line 98)\n* FAM [ms]: ms Document Control Settings.\n(line 138)\n* FR [ms]: ms Document Control Settings.\n(line 289)\n* LF [ms]: ms Document Control Settings.\n(line 91)\n* LH [ms]: ms Document Control Settings.\n(line 70)\n* MONTH1 [ms]: ms language and localization.\n(line 31)\n* MONTH10 [ms]: ms language and localization.\n(line 40)\n* MONTH11 [ms]: ms language and localization.\n(line 41)\n* MONTH12 [ms]: ms language and localization.\n(line 42)\n* MONTH2 [ms]: ms language and localization.\n(line 32)\n* MONTH3 [ms]: ms language and localization.\n(line 33)\n* MONTH4 [ms]: ms language and localization.\n(line 34)\n* MONTH5 [ms]: ms language and localization.\n(line 35)\n* MONTH6 [ms]: ms language and localization.\n(line 36)\n* MONTH7 [ms]: ms language and localization.\n(line 37)\n* MONTH8 [ms]: ms language and localization.\n(line 38)\n* MONTH9 [ms]: ms language and localization.\n(line 39)\n* o [ms]: ms Legacy Features. (line 77)\n* oe [ms]: ms Legacy Features. (line 113)\n* OE [ms]: ms Legacy Features. (line 116)\n* Q [ms]: Typographical symbols in ms.\n(line 14)\n* q [ms]: ms Legacy Features. (line 89)\n* REFERENCES [ms]: ms language and localization.\n(line 17)\n* RF [ms]: ms Document Control Settings.\n(line 105)\n* RH [ms]: ms Document Control Settings.\n(line 84)\n* SN [ms]: Headings in ms. (line 64)\n* SN-DOT [ms]: Headings in ms. (line 62)\n* SN-NO-DOT [ms]: Headings in ms. (line 63)\n* SN-STYLE [ms]: ms Document Control Settings.\n(line 223)\n* SN-STYLE [ms] <1>: Headings in ms. (line 61)\n* th [ms]: ms Legacy Features. (line 101)\n* Th [ms]: ms Legacy Features. (line 104)\n* TOC [ms]: ms language and localization.\n(line 27)\n* U [ms]: Typographical symbols in ms.\n(line 15)\n* v [ms]: ms Legacy Features. (line 68)\n", "subsections": [] }, "File: groff.info, Node: File Keyword Index, Next: Program and File Index, Prev: String Index, Up: Top": { "content": "", "subsections": [] }, "Appendix H File Keyword Index": { "content": "* Menu:\n\n* ---: Font Description File Format.\n(line 73)\n* #: DESC File Format. (line 13)\n* # <1>: Font Description File Format.\n(line 26)\n* biggestfont: DESC File Format. (line 143)\n* charset: DESC File Format. (line 138)\n* charset <1>: Font Description File Format.\n(line 65)\n* family: Selecting Fonts. (line 15)\n* family <1>: DESC File Format. (line 17)\n* fonts: Using Symbols. (line 18)\n* fonts <1>: Special Fonts. (line 18)\n* fonts <2>: DESC File Format. (line 20)\n* hor: DESC File Format. (line 26)\n* imagegenerator: DESC File Format. (line 30)\n* kernpairs: Font Description File Format.\n(line 161)\n* ligatures: Font Description File Format.\n(line 45)\n* name: Font Description File Format.\n(line 30)\n* paperlength: DESC File Format. (line 36)\n* papersize: DESC File Format. (line 40)\n* paperwidth: DESC File Format. (line 67)\n* passfilenames: DESC File Format. (line 71)\n* postpro: DESC File Format. (line 76)\n* prepro: DESC File Format. (line 79)\n* print: DESC File Format. (line 83)\n* res: DESC File Format. (line 87)\n* sizes: DESC File Format. (line 90)\n* sizescale: DESC File Format. (line 95)\n* slant: Font Description File Format.\n(line 41)\n* spacewidth: Font Description File Format.\n(line 35)\n* spare1: DESC File Format. (line 143)\n* spare2: DESC File Format. (line 143)\n* special: Artificial Fonts. (line 114)\n* special <1>: Font Description File Format.\n(line 52)\n* styles: Selecting Fonts. (line 15)\n* styles <1>: Font Families. (line 69)\n* styles <2>: DESC File Format. (line 99)\n* tcommand: DESC File Format. (line 103)\n* unicode: DESC File Format. (line 107)\n* unitwidth: DESC File Format. (line 121)\n* unscaledcharwidths: DESC File Format. (line 125)\n* usecharnamesinspecial: Postprocessor Access.\n(line 37)\n* usecharnamesinspecial <1>: DESC File Format. (line 129)\n* vert: DESC File Format. (line 134)\n", "subsections": [] }, "File: groff.info, Node: Program and File Index, Next: Concept Index, Prev: File Keyword Index, Up: Top": { "content": "", "subsections": [] }, "Appendix I Program and File Index": { "content": "* Menu:\n\n* an.tmac: man. (line 6)\n* changebar: Miscellaneous. (line 153)\n* composite.tmac: Using Symbols. (line 208)\n* cp1047.tmac: Input Encodings. (line 12)\n* cs.tmac: Manipulating Hyphenation.\n(line 280)\n* de.tmac: Manipulating Hyphenation.\n(line 280)\n* DESC: Selecting Fonts. (line 15)\n* DESC <1>: Font Families. (line 69)\n* DESC <2>: Using Symbols. (line 18)\n* DESC <3>: Using Symbols. (line 226)\n* DESC <4>: Special Fonts. (line 18)\n* diffmk: Miscellaneous. (line 153)\n* ec.tmac: Input Encodings. (line 53)\n* en.tmac: Manipulating Hyphenation.\n(line 280)\n* eqn: ms Insertions. (line 7)\n* fr.tmac: Manipulating Hyphenation.\n(line 280)\n* freeeuro.pfa: Input Encodings. (line 53)\n* gchem: Groff Options. (line 6)\n* gdiffmk: Miscellaneous. (line 153)\n* geqn: Groff Options. (line 6)\n* ggrn: Groff Options. (line 6)\n* gpic: Groff Options. (line 6)\n* grap: Groff Options. (line 6)\n* grefer: Groff Options. (line 6)\n* groff: Groff Options. (line 6)\n* gsoelim: Groff Options. (line 6)\n* gtbl: Groff Options. (line 6)\n* gtroff: Groff Options. (line 6)\n* it.tmac: Manipulating Hyphenation.\n(line 280)\n* ja.tmac: Manipulating Hyphenation.\n(line 280)\n* latin1.tmac: Input Encodings. (line 17)\n* latin2.tmac: Input Encodings. (line 30)\n* latin5.tmac: Input Encodings. (line 36)\n* latin9.tmac: Input Encodings. (line 41)\n* makeindex: Indexing. (line 6)\n* man.local: Optional man extensions.\n(line 6)\n* man.tmac: man. (line 6)\n* man.ultrix: Optional man extensions.\n(line 30)\n* nrchbar: Miscellaneous. (line 153)\n* papersize.tmac: Paper Format. (line 9)\n* perl: I/O. (line 182)\n* pic: ms Insertions. (line 7)\n* post-grohtml: Groff Options. (line 294)\n* pre-grohtml: Groff Options. (line 294)\n* preconv: Groff Options. (line 6)\n* refer: ms Insertions. (line 7)\n* soelim: Debugging. (line 31)\n* sv.tmac: Manipulating Hyphenation.\n(line 280)\n* tbl: ms Insertions. (line 7)\n* trace.tmac: Writing Macros. (line 147)\n* troffrc: Groff Options. (line 227)\n* troffrc <1>: Paper Format. (line 9)\n* troffrc <2>: Manipulating Hyphenation.\n(line 280)\n* troffrc <3>: Manipulating Hyphenation.\n(line 328)\n* troffrc <4>: troff and nroff Modes.\n(line 25)\n* troffrc-end: Groff Options. (line 227)\n* troffrc-end <1>: Manipulating Hyphenation.\n(line 328)\n* troffrc-end <2>: troff and nroff Modes.\n(line 25)\n* tty.tmac: troff and nroff Modes.\n(line 33)\n* tty.tmac <1>: Line Layout. (line 63)\n* vtroff: Operators in Conditionals.\n(line 49)\n* zh.tmac: Manipulating Hyphenation.\n(line 280)\n", "subsections": [] }, "File: groff.info, Node: Concept Index, Prev: Program and File Index, Up: Top": { "content": "", "subsections": [] }, "Appendix J Concept Index": { "content": "* Menu:\n\n* -, and page motion: Numeric Expressions. (line 115)\n* -, as delimiter: Delimiters. (line 38)\n* ., as delimiter: Delimiters. (line 36)\n* .h register, difference from nl: Diversions. (line 108)\n* .ps register, in comparison with .psr: Using Fractional Type Sizes.\n(line 47)\n* .s register, in comparison with .sr: Using Fractional Type Sizes.\n(line 47)\n* .S register, Plan 9 alias for .tabs: Tabs and Fields. (line 118)\n* .t register, and diversions: Diversion Traps. (line 11)\n* .tabs register, Plan 9 alias (.S): Tabs and Fields. (line 118)\n* .V register, and vs: Changing the Vertical Spacing.\n(line 13)\n* ', as a comment: Comments. (line 38)\n* ', as delimiter: Delimiters. (line 6)\n* ', at end of sentence: Sentences. (line 62)\n* ', at end of sentence <1>: Using Symbols. (line 298)\n* \", as delimiter: Delimiters. (line 6)\n* \", at end of sentence: Sentences. (line 62)\n* \", at end of sentence <1>: Using Symbols. (line 298)\n* \", embedding in a macro argument: Calling Macros. (line 30)\n* (, as delimiter: Delimiters. (line 38)\n* ), as delimiter: Delimiters. (line 38)\n* ), at end of sentence: Sentences. (line 62)\n* ), at end of sentence <1>: Using Symbols. (line 298)\n* [, macro names starting with, and refer: Identifiers. (line 55)\n* ], as part of an identifier: Identifiers. (line 48)\n* ], at end of sentence: Sentences. (line 62)\n* ], at end of sentence <1>: Using Symbols. (line 298)\n* ], macro names starting with, and refer: Identifiers. (line 55)\n* *, as delimiter: Delimiters. (line 38)\n* *, at end of sentence: Sentences. (line 62)\n* *, at end of sentence <1>: Using Symbols. (line 298)\n* /, as delimiter: Delimiters. (line 38)\n* \\, and translations: Character Translations.\n(line 25)\n* \\, as delimiter: Delimiters. (line 15)\n* \\, as delimiter <1>: Delimiters. (line 42)\n* \\, incompatibilities with AT&T troff: Other Differences. (line 16)\n* \\- glyph, and cflags: Using Symbols. (line 281)\n* \\-, and translations: Character Translations.\n(line 25)\n* \\-, as delimiter: Delimiters. (line 15)\n* \\-, as delimiter <1>: Delimiters. (line 42)\n* \\-, incompatibilities with AT&T troff: Other Differences. (line 16)\n* \\, disabling (eo): Using Escape Sequences.\n(line 71)\n* \\, embedding in a macro argument: Calling Macros. (line 30)\n* \\,, as delimiter: Delimiters. (line 15)\n* \\:, as delimiter: Delimiters. (line 15)\n* \\:, as delimiter <1>: Delimiters. (line 42)\n* \\!, and copy mode: Diversions. (line 162)\n* \\!, and output request: Diversions. (line 194)\n* \\!, and trnt: Character Translations.\n(line 79)\n* \\!, as delimiter: Delimiters. (line 15)\n* \\!, as delimiter <1>: Delimiters. (line 42)\n* \\!, in top-level diversion: Diversions. (line 186)\n* \\!, incompatibilities with AT&T troff: Other Differences. (line 16)\n* \\!, incompatibilities with AT&T troff <1>: Other Differences.\n(line 106)\n* \\?, and copy mode: Operators in Conditionals.\n(line 95)\n* \\?, and copy mode <1>: Diversions. (line 162)\n* \\?, as delimiter: Delimiters. (line 15)\n* \\?, in top-level diversion: Diversions. (line 191)\n* \\?, incompatibilities with AT&T troff: Other Differences. (line 106)\n* \\', and translations: Character Translations.\n(line 25)\n* \\', as delimiter: Delimiters. (line 15)\n* \\', as delimiter <1>: Delimiters. (line 42)\n* \\', incompatibilities with AT&T troff: Other Differences. (line 16)\n* \\(, and translations: Character Translations.\n(line 25)\n* \\), as delimiter: Delimiters. (line 15)\n* \\), in \\X: Postprocessor Access.\n(line 23)\n* \\[, and translations: Character Translations.\n(line 25)\n* \\{, as delimiter: Delimiters. (line 15)\n* \\{, as delimiter <1>: Delimiters. (line 42)\n* \\{, incompatibilities with AT&T troff: Other Differences. (line 16)\n* \\}, and warnings: Warnings. (line 89)\n* \\}, as delimiter: Delimiters. (line 15)\n* \\}, as delimiter <1>: Delimiters. (line 42)\n* \\}, incompatibilities with AT&T troff: Other Differences. (line 16)\n* \\*, and warnings: Warnings. (line 66)\n* \\*, incompatibilities with AT&T troff: Compatibility Mode. (line 6)\n* \\*, when reading text for a macro: Copy Mode. (line 6)\n* \\/, as delimiter: Delimiters. (line 15)\n* \\/, as delimiter <1>: Delimiters. (line 42)\n* \\\\, when reading text for a macro: Copy Mode. (line 45)\n* \\&, and glyph definitions: Using Symbols. (line 354)\n* \\&, and translations: Character Translations.\n(line 42)\n* \\&, as delimiter: Delimiters. (line 15)\n* \\&, at end of sentence: Sentences. (line 46)\n* \\&, in \\X: Postprocessor Access.\n(line 23)\n* \\&, incompatibilities with AT&T troff: Other Differences. (line 16)\n* \\%, and translations: Character Translations.\n(line 31)\n* \\%, as delimiter: Delimiters. (line 15)\n* \\%, as delimiter <1>: Delimiters. (line 42)\n* \\%, following \\X or \\Y: Manipulating Hyphenation.\n(line 66)\n* \\%, in \\X: Postprocessor Access.\n(line 23)\n* \\%, incompatibilities with AT&T troff: Other Differences. (line 16)\n* \\`, and translations: Character Translations.\n(line 25)\n* \\`, as delimiter: Delimiters. (line 15)\n* \\`, as delimiter <1>: Delimiters. (line 42)\n* \\`, incompatibilities with AT&T troff: Other Differences. (line 16)\n* \\^, as delimiter: Delimiters. (line 15)\n* \\^, incompatibilities with AT&T troff: Other Differences. (line 16)\n* \\, in \\X: Postprocessor Access.\n(line 23)\n* \\|, as delimiter: Delimiters. (line 15)\n* \\|, incompatibilities with AT&T troff: Other Differences. (line 16)\n* \\~, and translations: Character Translations.\n(line 31)\n* \\~, as delimiter: Delimiters. (line 15)\n* \\~, difference from \\: Calling Macros. (line 22)\n* \\~, incompatibilities with AT&T troff: Other Differences. (line 9)\n* \\$, when reading text for a macro: Copy Mode. (line 6)\n* \\0, as delimiter: Delimiters. (line 15)\n* \\a, and copy mode: Leaders. (line 19)\n* \\a, and translations: Character Translations.\n(line 35)\n* \\a, as delimiter: Delimiters. (line 15)\n* \\A, delimiters allowed by: Delimiters. (line 22)\n* \\A, incompatibilities with AT&T troff: Other Differences. (line 16)\n* \\b, delimiters allowed by: Delimiters. (line 22)\n* \\b, limitations of: Drawing Geometric Objects.\n(line 192)\n* \\C, and translations: Character Translations.\n(line 25)\n* \\c, as delimiter: Delimiters. (line 15)\n* \\c, as delimiter <1>: Delimiters. (line 42)\n* \\c, incompatibilities with AT&T troff: Other Differences. (line 16)\n* \\c, when filling disabled: Line Continuation. (line 54)\n* \\c, when filling enabled: Line Continuation. (line 46)\n* \\d, as delimiter: Delimiters. (line 15)\n* \\D, delimiters allowed by: Delimiters. (line 33)\n* \\e, and glyph definitions: Using Symbols. (line 354)\n* \\e, and translations: Character Translations.\n(line 29)\n* \\e, as delimiter: Delimiters. (line 15)\n* \\E, as delimiter: Delimiters. (line 15)\n* \\e, as delimiter <1>: Delimiters. (line 42)\n* \\e, incompatibilities with AT&T troff: Other Differences. (line 106)\n* \\F, and changing fonts: Selecting Fonts. (line 15)\n* \\f, and font translations: Selecting Fonts. (line 69)\n* \\f, incompatibilities with AT&T troff: Compatibility Mode. (line 108)\n* \\h, delimiters allowed by: Delimiters. (line 33)\n* \\H, delimiters allowed by: Delimiters. (line 33)\n* \\H, incompatibilities with AT&T troff: Compatibility Mode. (line 108)\n* \\H, using + and - with: Numeric Expressions. (line 121)\n* \\H, with fractional type sizes: Using Fractional Type Sizes.\n(line 13)\n* \\l, and glyph definitions: Using Symbols. (line 354)\n* \\L, and glyph definitions: Using Symbols. (line 354)\n* \\l, delimiters allowed by: Delimiters. (line 33)\n* \\L, delimiters allowed by: Delimiters. (line 33)\n* \\N, and translations: Character Translations.\n(line 25)\n* \\n, and warnings: Warnings. (line 78)\n* \\N, delimiters allowed by: Delimiters. (line 33)\n* \\n, incompatibilities with AT&T troff: Compatibility Mode. (line 6)\n* \\n, when reading text for a macro: Copy Mode. (line 6)\n* \\o, delimiters allowed by: Delimiters. (line 22)\n* \\p, as delimiter: Delimiters. (line 15)\n* \\p, as delimiter <1>: Delimiters. (line 42)\n* \\R, after \\c: Line Continuation. (line 40)\n* \\R, and warnings: Warnings. (line 78)\n* \\r, as delimiter: Delimiters. (line 15)\n* \\R, delimiters allowed by: Delimiters. (line 33)\n* \\R, difference from nr: Auto-increment. (line 14)\n* \\R, using + and - with: Numeric Expressions. (line 121)\n* \\, when reading text for a macro: Copy Mode. (line 6)\n* \\s, delimiters allowed by: Delimiters. (line 33)\n* \\S, delimiters allowed by: Delimiters. (line 33)\n* \\s, incompatibilities with AT&T troff: Compatibility Mode. (line 108)\n* \\S, incompatibilities with AT&T troff: Compatibility Mode. (line 108)\n* \\s, incompatibilities with AT&T troff <1>: Compatibility Mode.\n(line 121)\n* \\s, using + and - with: Numeric Expressions. (line 121)\n* \\s, with fractional type sizes: Using Fractional Type Sizes.\n(line 13)\n* \\, as delimiter: Delimiters. (line 15)\n* \\, difference from \\~: Calling Macros. (line 22)\n* \\, incompatibilities with AT&T troff: Other Differences.\n(line 16)\n* \\t, and copy mode: Tabs and Fields. (line 10)\n* \\t, and translations: Character Translations.\n(line 35)\n* \\t, and warnings: Warnings. (line 84)\n* \\t, as delimiter: Delimiters. (line 15)\n* \\u, as delimiter: Delimiters. (line 15)\n* \\V, and copy mode: I/O. (line 258)\n* \\v, delimiters allowed by: Delimiters. (line 33)\n* \\v, internal representation: Gtroff Internals. (line 53)\n* \\w, delimiters allowed by: Delimiters. (line 22)\n* \\X, and special characters: Postprocessor Access.\n(line 37)\n* \\X, delimiters allowed by: Delimiters. (line 22)\n* \\x, delimiters allowed by: Delimiters. (line 33)\n* \\X, followed by \\%: Manipulating Hyphenation.\n(line 66)\n* \\Y, followed by \\%: Manipulating Hyphenation.\n(line 66)\n* \\Z, delimiters allowed by: Delimiters. (line 22)\n* &, as delimiter: Delimiters. (line 38)\n* %, as delimiter: Delimiters. (line 38)\n* +, and page motion: Numeric Expressions. (line 115)\n* +, as delimiter: Delimiters. (line 38)\n* <, as delimiter: Delimiters. (line 38)\n* , as delimiter: Delimiters. (line 38)\n* =, as delimiter: Delimiters. (line 38)\n* >, as delimiter: Delimiters. (line 38)\n* |, and page motion: Numeric Expressions. (line 129)\n* 8-bit input: Font Description File Format.\n(line 73)\n* ab request, incompatibilities with AT&T troff: Other Differences.\n(line 62)\n* aborting (ab): Debugging. (line 55)\n* absolute (sic) position operator (|): Numeric Expressions. (line 129)\n* abstract font style: Using Fonts. (line 28)\n* abstract font style, setting up (sty): Font Families. (line 63)\n* accent marks [ms]: ms Legacy Features. (line 6)\n* access to postprocessor: Postprocessor Access.\n(line 6)\n* accessing unnamed glyphs with \\N: Font Description File Format.\n(line 73)\n* activating kerning (kern): Ligatures and Kerning.\n(line 42)\n* activating ligatures (lg): Ligatures and Kerning.\n(line 24)\n* activating track kerning (tkf): Ligatures and Kerning.\n(line 60)\n* ad request, and hyphenation margin: Manipulating Hyphenation.\n(line 355)\n* ad request, and hyphenation space: Manipulating Hyphenation.\n(line 370)\n* addition: Numeric Expressions. (line 17)\n* additional inter-sentence space: Manipulating Filling and Adjustment.\n(line 275)\n* adjustment and filling, manipulating: Manipulating Filling and Adjustment.\n(line 6)\n* adjustment mode register (.j): Manipulating Filling and Adjustment.\n(line 113)\n* adjustment to both margins, difference from AT&T troff: Other Differences.\n(line 22)\n* Adobe Glyph List (AGL): Using Symbols. (line 94)\n* alias, diversion, creating (als): Strings. (line 198)\n* alias, diversion, removing (rm): Strings. (line 233)\n* alias, macro, creating (als): Strings. (line 198)\n* alias, macro, removing (rm): Strings. (line 233)\n* alias, register, creating (aln): Setting Registers. (line 110)\n* alias, register, removing (rr): Setting Registers. (line 116)\n* alias, string, creating (als): Strings. (line 198)\n* alias, string, removing (rm): Strings. (line 233)\n* aliasing fonts with third argument to fp request: Font Positions.\n(line 27)\n* als request, and \\$0: Parameters. (line 77)\n* am, am1, ami requests, and warnings: Warnings. (line 66)\n* appending to a diversion (da, boxa): Diversions. (line 32)\n* appending to a file (opena): I/O. (line 208)\n* appending to a macro (am): Writing Macros. (line 129)\n* appending to a string (as): Strings. (line 115)\n* approximation output register (.A): Built-in Registers. (line 25)\n* arc, drawing (\\D'a ...'): Drawing Geometric Objects.\n(line 101)\n* argument: Requests and Macros. (line 23)\n* arguments to macros: Calling Macros. (line 6)\n* arguments to macros, and tabs: Invoking Requests. (line 14)\n* arguments to requests: Invoking Requests. (line 14)\n* arguments to requests, and tabs: Invoking Requests. (line 14)\n* arguments, and compatibility mode: Gtroff Internals. (line 90)\n* arguments, to escape sequences, delimiting: Delimiters. (line 6)\n* arguments, to strings: Strings. (line 28)\n* arithmetic operators: Numeric Expressions. (line 17)\n* artificial fonts: Artificial Fonts. (line 6)\n* as, as1 requests, and comments: Comments. (line 13)\n* as, as1 requests, and warnings: Warnings. (line 66)\n* ASCII output encoding: Groff Options. (line 271)\n* asciify request, and writem: I/O. (line 231)\n* assertion (arithmetic operator): Numeric Expressions. (line 23)\n* assign number format to register (af): Assigning Register Formats.\n(line 6)\n* assignments, indirect: Interpolating Registers.\n(line 11)\n* assignments, nested: Interpolating Registers.\n(line 11)\n* AT&T ms, macro package differences: Differences from AT&T ms.\n(line 6)\n* attributes, character cell: Using Fonts. (line 49)\n* auto-incrementation of a register: Auto-increment. (line 6)\n* automatic font mounting: Selecting Fonts. (line 28)\n* automatic hyphenation: Manipulating Hyphenation.\n(line 6)\n* automatic hyphenation parameters: Manipulating Hyphenation.\n(line 107)\n* auxiliary macro package: Major Macro Packages.\n(line 20)\n* available glyphs, list of (groffchar(7) man page): Using Symbols.\n(line 81)\n* background: Background. (line 6)\n* background color name register (.M): Colors. (line 93)\n* backslash glyph, formatting (\\[rs]): Using Escape Sequences.\n(line 66)\n* backslash, embedding in a macro argument: Calling Macros. (line 30)\n* backslash, printing (\\\\, \\e, \\E, \\[rs]): Other Differences. (line 106)\n* backspace character, and translations: Character Translations.\n(line 35)\n* backtrace of input stack (backtrace): Debugging. (line 104)\n* baseline rule special character(\\[ru]): Drawing Geometric Objects.\n(line 22)\n* baseline, text: Page Geometry. (line 28)\n* baseline, text <1>: Manipulating Type Size and Vertical Spacing.\n(line 6)\n* basic scaling unit (u): Measurements. (line 19)\n* basic units: Page Geometry. (line 13)\n* basic units, conversion to: Measurements. (line 13)\n* basics of macro package usage: Basics. (line 6)\n* bd request, and font styles: Font Families. (line 63)\n* bd request, and font translations: Selecting Fonts. (line 69)\n* bd request, incompatibilities with AT&T troff: Other Differences.\n(line 79)\n* beginning diversion (di, box): Diversions. (line 32)\n* beginning of conditional block (\\{): Conditional Blocks. (line 13)\n* blank line: Breaking. (line 30)\n* blank line macro (blm): Breaking. (line 30)\n* blank line macro (blm) <1>: Invoking Requests. (line 45)\n* blank line macro (blm) <2>: Blank Line Traps. (line 7)\n* blank line trap (blm): Invoking Requests. (line 45)\n* blank line traps: Blank Line Traps. (line 6)\n* blank lines, disabling: Manipulating Spacing.\n(line 118)\n* block, conditional, beginning (\\{): Conditional Blocks. (line 13)\n* block, conditional, end (\\}): Conditional Blocks. (line 13)\n* blocks, conditional: Conditional Blocks. (line 6)\n* body, of a while request: while. (line 9)\n* boldface, imitating (bd): Artificial Fonts. (line 97)\n* bottom margin: Page Location Traps. (line 26)\n* boundary-relative motion operator (|): Numeric Expressions. (line 129)\n* bounding box: Miscellaneous. (line 162)\n* box (diversion operation): Diversions. (line 59)\n* box request, and warnings: Warnings. (line 61)\n* box rule glyph (\\[br]): Drawing Geometric Objects.\n(line 44)\n* box, boxa requests, and warnings: Warnings. (line 66)\n* boxa request, and dn (dl): Diversions. (line 114)\n* boxa request, and warnings: Warnings. (line 61)\n* boxes [ms]: ms keeps and displays.\n(line 34)\n* bp request, and top-level diversion: Page Control. (line 19)\n* bp request, and traps (.pe): Page Location Traps. (line 184)\n* bp request, causing implicit break: Manipulating Filling and Adjustment.\n(line 6)\n* bp request, incompatibilities with AT&T troff: Other Differences.\n(line 66)\n* bp request, using + and - with: Numeric Expressions. (line 121)\n* br glyph, and cflags: Using Symbols. (line 293)\n* brace escape sequence, closing (\\}): Conditional Blocks. (line 13)\n* brace escape sequence, opening (\\}): Conditional Blocks. (line 13)\n* brace escape sequences (\\{, \\}): Conditional Blocks. (line 13)\n* break: Breaking. (line 6)\n* break <1>: Manipulating Filling and Adjustment.\n(line 6)\n* break (introduction): Basics. (line 136)\n* break request, in a while loop: while. (line 72)\n* break, page: Page Geometry. (line 52)\n* break, page <1>: Page Control. (line 6)\n* break, page <2>: The Implicit Page Trap.\n(line 6)\n* break, page (introduction): Basics. (line 133)\n* break, page, final: End-of-input Traps. (line 34)\n* break, page, prevented by vpt: Vertical Position Traps.\n(line 21)\n* breaking file names (\\:): Manipulating Hyphenation.\n(line 73)\n* breaking URLs (\\:): Manipulating Hyphenation.\n(line 73)\n* breaking without hyphens (\\:): Manipulating Hyphenation.\n(line 73)\n* built-in register, removing: Built-in Registers. (line 11)\n* built-in registers: Built-in Registers. (line 6)\n* bulleted list, example markup [ms]: Lists in ms. (line 14)\n* c scaling unit: Measurements. (line 26)\n* calling a macro: Requests and Macros. (line 34)\n* calling macros: Calling Macros. (line 6)\n* capabilities of groff: groff Capabilities. (line 6)\n* case-transforming a string (stringdown, stringup): Strings. (line 171)\n* categories, warning: Warnings. (line 15)\n* CCSID 1047 output encoding (EBCDIC): Groff Options. (line 283)\n* ce request, causing implicit break: Manipulating Filling and Adjustment.\n(line 6)\n* ce request, difference from .ad c: Manipulating Filling and Adjustment.\n(line 218)\n* cell, character, attributes: Using Fonts. (line 49)\n* centered text (filled): Manipulating Filling and Adjustment.\n(line 98)\n* centered text (unfilled): Manipulating Filling and Adjustment.\n(line 209)\n* centering lines (ce): Manipulating Filling and Adjustment.\n(line 209)\n* centering lines (introduction): Basics. (line 118)\n* centimeter scaling unit (c): Measurements. (line 26)\n* cf request, and copy mode: I/O. (line 58)\n* cf request, causing implicit break: Manipulating Filling and Adjustment.\n(line 6)\n* changing control characters: Control Characters. (line 6)\n* changing font family (fam, \\F): Font Families. (line 25)\n* changing fonts (ft, \\f): Selecting Fonts. (line 15)\n* changing format, and read-only registers: Assigning Register Formats.\n(line 65)\n* changing the font height (\\H): Artificial Fonts. (line 16)\n* changing the font slant (\\S): Artificial Fonts. (line 45)\n* changing the page number character (pc): Page Layout. (line 68)\n* changing trap location (ch): Page Location Traps. (line 114)\n* changing type sizes (ps, \\s): Changing the Type Size.\n(line 11)\n* changing vertical line spacing (vs): Changing the Vertical Spacing.\n(line 10)\n* char request, and soft hyphen character: Manipulating Hyphenation.\n(line 97)\n* char request, and translations: Character Translations.\n(line 25)\n* char request, used with \\N: Using Symbols. (line 216)\n* character: Using Symbols. (line 6)\n* character cell attributes: Using Fonts. (line 49)\n* character class (class): Character Classes. (line 12)\n* character classes: Character Classes. (line 6)\n* character properties (cflags): Using Symbols. (line 252)\n* character translations: Character Translations.\n(line 6)\n* character, backspace, and translations: Character Translations.\n(line 35)\n* character, control (.): Requests and Macros. (line 7)\n* character, control, changing (cc): Control Characters. (line 18)\n* character, defining (char): Using Symbols. (line 354)\n* character, defining fallback (fchar, fschar, schar): Using Symbols.\n(line 354)\n* character, distinguished from glyph: Using Symbols. (line 6)\n* character, dummy (\\&): Dummy Characters. (line 13)\n* character, dummy (\\&), as control character suppressor: Requests and Macros.\n(line 14)\n* character, dummy (\\&), effect on \\l escape sequence: Drawing Geometric Objects.\n(line 26)\n* character, dummy (\\&), effect on kerning: Ligatures and Kerning.\n(line 47)\n* character, escape, changing (ec): Using Escape Sequences.\n(line 76)\n* character, escape, while defining glyph: Using Symbols. (line 354)\n* character, field delimiting (fc): Fields. (line 6)\n* character, field padding (fc): Fields. (line 6)\n* character, horizontal tab: Tabs and Leaders. (line 6)\n* character, hyphenation (\\%): Manipulating Hyphenation.\n(line 57)\n* character, leader: Tabs and Leaders. (line 6)\n* character, leader repetition (lc): Leaders. (line 22)\n* character, leader, and translations: Character Translations.\n(line 35)\n* character, leader, non-interpreted (\\a): Leaders. (line 19)\n* character, named (\\C): Using Symbols. (line 199)\n* character, newline, and translations: Character Translations.\n(line 35)\n* character, no-break control ('): Requests and Macros. (line 7)\n* character, no-break control, changing (c2): Control Characters.\n(line 18)\n* character, ordinary: Identifiers. (line 9)\n* character, soft hyphen, setting (shc): Manipulating Hyphenation.\n(line 97)\n* character, special: Character Translations.\n(line 25)\n* character, tab repetition (tc): Tabs and Fields. (line 127)\n* character, tab, and translations: Character Translations.\n(line 35)\n* character, tab, non-interpreted (\\t): Tabs and Fields. (line 10)\n* character, transparent: Using Symbols. (line 298)\n* character, transparent dummy (\\)): Dummy Characters. (line 63)\n* characters, end-of-sentence: Using Symbols. (line 269)\n* characters, end-of-sentence transparent: Sentences. (line 62)\n* characters, hyphenation: Using Symbols. (line 274)\n* characters, input, and output glyphs, compatibility with AT&T troff: Other Differences.\n(line 79)\n* characters, invalid for trf request: I/O. (line 70)\n* characters, invalid input: Identifiers. (line 13)\n* characters, overlapping: Using Symbols. (line 288)\n* characters, special: Sentences. (line 62)\n* characters, special, list of (groffchar(7) man page): Using Symbols.\n(line 81)\n* characters, unnamed, accessing with \\N: Font Description File Format.\n(line 73)\n* circle, filled, drawing (\\D'C ...'): Drawing Geometric Objects.\n(line 110)\n* circle, outlined, drawing (\\D'c ...'): Drawing Geometric Objects.\n(line 106)\n* circle, solid, drawing (\\D'C ...'): Drawing Geometric Objects.\n(line 110)\n* circle, stroked, drawing (\\D'c ...'): Drawing Geometric Objects.\n(line 106)\n* class of characters (class): Character Classes. (line 12)\n* classes, character: Character Classes. (line 6)\n* clearing input line trap (it, itc): Input Line Traps. (line 8)\n* closing brace escape sequence (\\}): Conditional Blocks. (line 13)\n* closing file (close): I/O. (line 240)\n* code page 1047 output encoding: Groff Options. (line 283)\n* code page 1047, input encoding: Input Encodings. (line 12)\n* code, hyphenation (hcode): Manipulating Hyphenation.\n(line 293)\n* color name, background, register (.M): Colors. (line 93)\n* color name, fill, register (.M): Colors. (line 93)\n* color name, stroke, register (.m): Colors. (line 72)\n* color, default: Colors. (line 48)\n* color, fill: Colors. (line 6)\n* color, stroke: Colors. (line 6)\n* colors: Colors. (line 6)\n* command prefix: Environment. (line 14)\n* command-line options: Groff Options. (line 48)\n* comments: Comments. (line 6)\n* comments in device description files: DESC File Format. (line 13)\n* comments in font description files: Font Description File Format.\n(line 26)\n* comments, lining up with tabs: Comments. (line 19)\n* comments, with ds: Strings. (line 49)\n* common features: Common Features. (line 6)\n* common name space of macros, diversions, and strings: Identifiers.\n(line 100)\n* comparison of strings: Operators in Conditionals.\n(line 87)\n* comparison operators: Numeric Expressions. (line 74)\n* compatibility mode: Warnings. (line 106)\n* compatibility mode <1>: Compatibility Mode. (line 6)\n* compatibility mode, and parameters: Gtroff Internals. (line 90)\n* complementation, logical: Numeric Expressions. (line 84)\n* composite glyph names: Using Symbols. (line 94)\n* conditional block, beginning (\\{): Conditional Blocks. (line 13)\n* conditional block, end (\\}): Conditional Blocks. (line 13)\n* conditional blocks: Conditional Blocks. (line 6)\n* conditional expressions: Operators in Conditionals.\n(line 6)\n* conditional output for terminal (TTY): Operators in Conditionals.\n(line 32)\n* conditional page break (ne): Page Control. (line 31)\n* conditionals and loops: Conditionals and Loops.\n(line 6)\n* configuring control characters: Control Characters. (line 6)\n* configuring the page length (pl): Page Layout. (line 12)\n* consecutive hyphenated lines (hlm): Manipulating Hyphenation.\n(line 342)\n* constant glyph space mode (cs): Artificial Fonts. (line 125)\n* contents, table of: Table of Contents. (line 6)\n* contents, table of <1>: Leaders. (line 32)\n* continuation, input line (\\): Line Continuation. (line 11)\n* continuation, output line (\\c): Line Continuation. (line 40)\n* continue request, in a while loop: while. (line 72)\n* continued output line register (.int): Line Continuation. (line 65)\n* continuous underlining (cu): Artificial Fonts. (line 86)\n* control character (.): Requests and Macros. (line 7)\n* control character, changing (cc): Control Characters. (line 18)\n* control character, no-break ('): Requests and Macros. (line 7)\n* control character, no-break, changing (c2): Control Characters.\n(line 18)\n* control characters: Control Characters. (line 6)\n* control line: Requests and Macros. (line 19)\n* control, line: Line Continuation. (line 6)\n* control, page: Page Control. (line 6)\n* conventions for input: Input Conventions. (line 6)\n* conversion to basic units: Measurements. (line 13)\n* copy mode: Copy Mode. (line 6)\n* copy mode <1>: Copy Mode. (line 6)\n* copy mode, and \\!: Diversions. (line 162)\n* copy mode, and \\?: Operators in Conditionals.\n(line 95)\n* copy mode, and \\? <1>: Diversions. (line 162)\n* copy mode, and \\a: Leaders. (line 19)\n* copy mode, and \\t: Tabs and Fields. (line 10)\n* copy mode, and \\V: I/O. (line 258)\n* copy mode, and cf request: I/O. (line 58)\n* copy mode, and device request: Postprocessor Access.\n(line 21)\n* copy mode, and length request: Strings. (line 135)\n* copy mode, and macro parameters: Parameters. (line 36)\n* copy mode, and output request: Diversions. (line 194)\n* copy mode, and trf request: I/O. (line 58)\n* copy mode, and write request: I/O. (line 220)\n* copy mode, and writec request: I/O. (line 220)\n* copy mode, and writem request: I/O. (line 234)\n* copying environment (evc): Environments. (line 100)\n* correction between oblique and upright glyph (\\/, \\,): Italic Corrections.\n(line 10)\n* correction between upright and oblique glyph (\\/, \\,): Italic Corrections.\n(line 20)\n* correction, italic (\\/): Italic Corrections. (line 10)\n* correction, left italic (\\,): Italic Corrections. (line 20)\n* cover page in [ms], example markup: ms Document Description Macros.\n(line 70)\n* cp request, and glyph definitions: Using Symbols. (line 354)\n* cq glyph, at end of sentence: Sentences. (line 62)\n* cq glyph, at end of sentence <1>: Using Symbols. (line 298)\n* creating alias for register (aln): Setting Registers. (line 110)\n* creating alias, for diversion (als): Strings. (line 198)\n* creating alias, for macro (als): Strings. (line 198)\n* creating alias, for string (als): Strings. (line 198)\n* creating new characters (char): Using Symbols. (line 354)\n* credits: Credits. (line 6)\n* cs request, and font styles: Font Families. (line 63)\n* cs request, and font translations: Selecting Fonts. (line 69)\n* cs request, incompatibilities with AT&T troff: Other Differences.\n(line 79)\n* cs request, with fractional type sizes: Using Fractional Type Sizes.\n(line 13)\n* CSTR #54 errata: Built-in Registers. (line 98)\n* CSTR #54 errata <1>: Line Layout. (line 71)\n* CSTR #54 errata <2>: Page Control. (line 21)\n* CSTR #54 errata <3>: Artificial Fonts. (line 60)\n* CSTR #54 errata <4>: Changing the Type Size.\n(line 20)\n* CSTR #54 errata <5>: Page Motions. (line 183)\n* CSTR #54 erratum, \\S escape: Artificial Fonts. (line 60)\n* CSTR #54 erratum, \\s escape sequence: Changing the Type Size.\n(line 20)\n* CSTR #54 erratum, bp request: Page Control. (line 21)\n* CSTR #54 erratum, po request: Line Layout. (line 71)\n* CSTR #54 erratum, ps request: Changing the Type Size.\n(line 20)\n* CSTR #54 erratum, sb register: Page Motions. (line 183)\n* CSTR #54 erratum, st register: Page Motions. (line 183)\n* CSTR #54 erratum, yr register: Built-in Registers. (line 98)\n* current directory: Macro Directories. (line 18)\n* current input file name register (.F): Built-in Registers. (line 34)\n* current page number (%): Page Control. (line 24)\n* current time, hours (hours): Built-in Registers. (line 84)\n* current time, minutes (minutes): Built-in Registers. (line 81)\n* current time, seconds (seconds): Built-in Registers. (line 78)\n* da request, and dn (dl): Diversions. (line 114)\n* da request, and warnings: Warnings. (line 61)\n* da request, and warnings <1>: Warnings. (line 66)\n* date, day of the month register (dy): Built-in Registers. (line 90)\n* date, day of the week register (dw): Built-in Registers. (line 87)\n* date, month of the year register (mo): Built-in Registers. (line 93)\n* date, year register (year, yr): Built-in Registers. (line 96)\n* day of the month register (dy): Built-in Registers. (line 90)\n* day of the week register (dw): Built-in Registers. (line 87)\n* dd glyph, at end of sentence: Sentences. (line 62)\n* dd glyph, at end of sentence <1>: Using Symbols. (line 298)\n* de request, and while: while. (line 22)\n* de, de1, dei requests, and warnings: Warnings. (line 66)\n* debugging: Debugging. (line 6)\n* debugging page location traps: Page Location Traps. (line 62)\n* decimal point, as delimiter: Delimiters. (line 36)\n* decrementation, automatic, of a register: Auto-increment. (line 6)\n* default color: Colors. (line 48)\n* default tab stops: Tabs and Fields. (line 18)\n* default units: Default Units. (line 6)\n* deferred output: Deferring Output. (line 6)\n* defining character (char): Using Symbols. (line 354)\n* defining character class (class): Character Classes. (line 12)\n* defining fallback character (fchar, fschar, schar): Using Symbols.\n(line 354)\n* defining glyph (char): Using Symbols. (line 354)\n* defining symbol (char): Using Symbols. (line 354)\n* delimited arguments, incompatibilities with AT&T troff: Compatibility Mode.\n(line 100)\n* delimiters, for escape sequence arguments: Delimiters. (line 6)\n* delimiting character, for fields (fc): Fields. (line 6)\n* delimiting escape sequence arguments: Delimiters. (line 6)\n* depth, interpolation: Calling Macros. (line 84)\n* depth, of last glyph (.cdp): Environments. (line 126)\n* DESC file format: DESC File Format. (line 6)\n* DESC file, and font mounting: Font Positions. (line 56)\n* DESC file, and usecharnamesinspecial keyword: Postprocessor Access.\n(line 37)\n* description file, font: Using Fonts. (line 21)\n* device description files, comments: DESC File Format. (line 13)\n* device request, and copy mode: Postprocessor Access.\n(line 21)\n* device resolution: Page Geometry. (line 13)\n* device resolution <1>: DESC File Format. (line 87)\n* device resolution, obtaining in the formatter: Measurements.\n(line 14)\n* devices for output: Output Device Intro. (line 6)\n* dg glyph, at end of sentence: Sentences. (line 62)\n* dg glyph, at end of sentence <1>: Using Symbols. (line 298)\n* di request, and warnings: Warnings. (line 61)\n* di request, and warnings <1>: Warnings. (line 66)\n* differences in implementation: Implementation Differences.\n(line 6)\n* digit-width space (\\0): Page Motions. (line 157)\n* digits, as delimiters: Delimiters. (line 36)\n* dimensions, line: Line Layout. (line 6)\n* directories for fonts: Font Directories. (line 6)\n* directories for macros: Macro Directories. (line 6)\n* directory, current: Macro Directories. (line 18)\n* directory, for tmac files: Macro Directories. (line 8)\n* directory, home: Macro Directories. (line 21)\n* directory, platform-specific: Macro Directories. (line 23)\n* directory, site-local: Macro Directories. (line 23)\n* directory, site-local <1>: Font Directories. (line 29)\n* disabling \\ (eo): Using Escape Sequences.\n(line 71)\n* disabling hyphenation (\\%): Manipulating Hyphenation.\n(line 57)\n* discardable horizontal space: Manipulating Filling and Adjustment.\n(line 296)\n* displays: Displays and Keeps. (line 6)\n* displays [ms]: ms keeps and displays.\n(line 60)\n* displays, and footnotes [ms]: ms Footnotes. (line 44)\n* distance to next vertical position trap register (.t): Page Location Traps.\n(line 106)\n* diversion: Deferring Output. (line 6)\n* diversion name register (.z): Diversions. (line 88)\n* diversion trap, setting (dt): Diversion Traps. (line 11)\n* diversion traps: Diversion Traps. (line 6)\n* diversion, appending to (da, boxa): Diversions. (line 32)\n* diversion, beginning (di, box): Diversions. (line 32)\n* diversion, creating alias for (als): Strings. (line 198)\n* diversion, ending (di, box): Diversions. (line 32)\n* diversion, nested: Diversions. (line 88)\n* diversion, removing (rm): Strings. (line 193)\n* diversion, removing alias for (rm): Strings. (line 233)\n* diversion, renaming (rn): Strings. (line 190)\n* diversion, stripping final newline: Punning Names. (line 95)\n* diversion, top-level: Diversions. (line 18)\n* diversion, top-level, and \\!: Diversions. (line 186)\n* diversion, top-level, and \\?: Diversions. (line 191)\n* diversion, top-level, and bp: Page Control. (line 19)\n* diversion, unformatting (asciify): Diversions. (line 208)\n* diversion, vertical position in, register (.d): Diversions. (line 88)\n* diversions: Diversions. (line 6)\n* diversions <1>: Punning Names. (line 6)\n* diversions, and traps: Page Location Traps. (line 204)\n* diversions, shared name space with macros and strings: Identifiers.\n(line 100)\n* division, truncating: Numeric Expressions. (line 17)\n* dl register, and da (boxa): Diversions. (line 114)\n* dn register, and da (boxa): Diversions. (line 114)\n* document description macros, [ms]: ms Document Description Macros.\n(line 6)\n* document formats: Document Formats. (line 6)\n* documents, multi-file: Debugging. (line 31)\n* documents, structuring the source of: Invoking Requests. (line 28)\n* dot, as delimiter: Delimiters. (line 36)\n* double quote, embedding in a macro argument: Calling Macros.\n(line 30)\n* double quotes, trailing, in strings: Strings. (line 70)\n* double-spacing (ls): Manipulating Spacing.\n(line 58)\n* double-spacing (vs, pvs): Changing the Vertical Spacing.\n(line 42)\n* down-casing a string (stringdown): Strings. (line 171)\n* drawing a filled circle (\\D'C ...'): Drawing Geometric Objects.\n(line 110)\n* drawing a filled ellipse (\\D'E ...'): Drawing Geometric Objects.\n(line 117)\n* drawing a filled polygon (\\D'P ...'): Drawing Geometric Objects.\n(line 151)\n* drawing a line (\\D'l ...'): Drawing Geometric Objects.\n(line 120)\n* drawing a solid circle (\\D'C ...'): Drawing Geometric Objects.\n(line 110)\n* drawing a solid ellipse (\\D'E ...'): Drawing Geometric Objects.\n(line 117)\n* drawing a solid polygon (\\D'P ...'): Drawing Geometric Objects.\n(line 151)\n* drawing a spline (\\D'~ ...'): Drawing Geometric Objects.\n(line 97)\n* drawing a stroked circle (\\D'c ...'): Drawing Geometric Objects.\n(line 106)\n* drawing a stroked ellipse (\\D'e ...'): Drawing Geometric Objects.\n(line 113)\n* drawing a stroked polygon (\\D'p ...'): Drawing Geometric Objects.\n(line 145)\n* drawing an arc (\\D'a ...'): Drawing Geometric Objects.\n(line 101)\n* drawing an outlined circle (\\D'c ...'): Drawing Geometric Objects.\n(line 106)\n* drawing an outlined ellipse (\\D'e ...'): Drawing Geometric Objects.\n(line 113)\n* drawing an outlined polygon (\\D'p ...'): Drawing Geometric Objects.\n(line 145)\n* drawing horizontal lines (\\l): Drawing Geometric Objects.\n(line 18)\n* drawing position: Page Geometry. (line 25)\n* drawing position, vertical (nl): Page Control. (line 76)\n* drawing requests: Drawing Geometric Objects.\n(line 6)\n* drawing vertical lines (\\L): Drawing Geometric Objects.\n(line 44)\n* ds request, and comments: Strings. (line 49)\n* ds request, and double quotes: Strings. (line 70)\n* ds request, and leading spaces: Strings. (line 70)\n* ds, ds1 requests, and comments: Comments. (line 13)\n* ds, ds1 requests, and warnings: Warnings. (line 66)\n* dummy character (\\&): Dummy Characters. (line 13)\n* dummy character (\\&), as control character suppressor: Requests and Macros.\n(line 14)\n* dummy character (\\&), effect on \\l escape sequence: Drawing Geometric Objects.\n(line 26)\n* dummy character (\\&), effect on kerning: Ligatures and Kerning.\n(line 47)\n* dummy character, transparent (\\)): Dummy Characters. (line 63)\n* dummy environment, used by \\w escape sequence: Page Motions.\n(line 177)\n* dumping environments (pev): Debugging. (line 78)\n* dumping page location traps (ptr): Debugging. (line 90)\n* dumping registers (pnr): Debugging. (line 86)\n* dumping symbol table (pm): Debugging. (line 82)\n* EBCDIC output encoding: Groff Options. (line 283)\n* EBCDIC, input encoding: Input Encodings. (line 12)\n* ejection, page: Page Geometry. (line 52)\n* ejection, page <1>: Page Control. (line 6)\n* ejection, page <2>: The Implicit Page Trap.\n(line 6)\n* ejection, page, of final page: End-of-input Traps. (line 34)\n* ejection, page, prevented by vpt: Vertical Position Traps.\n(line 21)\n* el request, and warnings: Warnings. (line 38)\n* ellipse, filled, drawing (\\D'E ...'): Drawing Geometric Objects.\n(line 117)\n* ellipse, outlined, drawing (\\D'e ...'): Drawing Geometric Objects.\n(line 113)\n* ellipse, solid, drawing (\\D'E ...'): Drawing Geometric Objects.\n(line 117)\n* ellipse, stroked, drawing (\\D'e ...'): Drawing Geometric Objects.\n(line 113)\n* em glyph, and cflags: Using Symbols. (line 281)\n* em scaling unit (m): Measurements. (line 51)\n* embolding of special fonts: Artificial Fonts. (line 114)\n* empty line: Breaking. (line 30)\n* en scaling unit (n): Measurements. (line 55)\n* enabling vertical position traps (vpt): Vertical Position Traps.\n(line 14)\n* encoding, input, code page 1047: Input Encodings. (line 12)\n* encoding, input, EBCDIC: Input Encodings. (line 12)\n* encoding, input, Latin-1 (ISO 8859-1): Input Encodings. (line 17)\n* encoding, input, Latin-2 (ISO 8859-2): Input Encodings. (line 30)\n* encoding, input, Latin-5 (ISO 8859-9): Input Encodings. (line 36)\n* encoding, input, Latin-9 (ISO 8859-15): Input Encodings. (line 41)\n* encoding, output, ASCII: Groff Options. (line 271)\n* encoding, output, code page 1047: Groff Options. (line 283)\n* encoding, output, EBCDIC: Groff Options. (line 283)\n* encoding, output, ISO 646: Groff Options. (line 271)\n* encoding, output, Latin-1 (ISO 8859-1): Groff Options. (line 275)\n* encoding, output, UTF-8: Groff Options. (line 279)\n* end of conditional block (\\}): Conditional Blocks. (line 13)\n* end-of-input macro (em): End-of-input Traps. (line 7)\n* end-of-input trap, setting (em): End-of-input Traps. (line 7)\n* end-of-input traps: End-of-input Traps. (line 6)\n* end-of-sentence characters: Sentences. (line 18)\n* end-of-sentence characters <1>: Using Symbols. (line 269)\n* end-of-sentence transparent characters: Sentences. (line 62)\n* ending diversion (di, box): Diversions. (line 32)\n* endnotes: Footnotes and Endnotes.\n(line 6)\n* environment: Deferring Output. (line 6)\n* environment availability and naming, incompatibilities with: Other Differences.\n(line 53)\n* environment number/name register (.ev): Environments. (line 47)\n* environment variables: Environment. (line 6)\n* environment, copying (evc): Environments. (line 100)\n* environment, dimensions of last glyph (.w, .cht, .cdp, .csk): Environments.\n(line 126)\n* environment, dummy, used by \\w escape sequence: Page Motions.\n(line 177)\n* environment, previous line length (.n): Environments. (line 141)\n* environment, switching (ev): Environments. (line 47)\n* environments: Environments. (line 6)\n* environments, dumping (pev): Debugging. (line 78)\n* equality operator: Numeric Expressions. (line 74)\n* equation example [ms]: ms Insertions. (line 65)\n* equations [ms]: ms Insertions. (line 6)\n* escape character, changing (ec): Using Escape Sequences.\n(line 76)\n* escape character, formatting (\\e): Using Escape Sequences.\n(line 63)\n* escape character, while defining glyph: Using Symbols. (line 354)\n* escape sequence: Formatter Instructions.\n(line 17)\n* escape sequence argument delimiters: Delimiters. (line 6)\n* escape sequences: Using Escape Sequences.\n(line 6)\n* escape sequences, brace (\\{, \\}): Conditional Blocks. (line 13)\n* escaping newline characters, in strings: Strings. (line 79)\n* ex request, use in debugging: Debugging. (line 60)\n* ex request, used with nx and rd: I/O. (line 128)\n* example markup, bulleted list [ms]: Lists in ms. (line 14)\n* example markup, cover page in [ms]: ms Document Description Macros.\n(line 70)\n* example markup, glossary-style list [ms]: Lists in ms. (line 61)\n* example markup, numbered list [ms]: Lists in ms. (line 33)\n* examples of invocation: Invocation Examples. (line 6)\n* exiting (ex): Debugging. (line 60)\n* expansion of strings (\\*): Strings. (line 28)\n* explicit hyphen (\\%): Manipulating Hyphenation.\n(line 342)\n* explicit hyphenation: Manipulating Hyphenation.\n(line 13)\n* expression, limitation of logical not in: Numeric Expressions.\n(line 84)\n* expression, order of evaluation: Numeric Expressions. (line 104)\n* expressions, and register format: Assigning Register Formats.\n(line 77)\n* expressions, and space characters: Numeric Expressions. (line 196)\n* expressions, conditional: Operators in Conditionals.\n(line 6)\n* expressions, numeric: Numeric Expressions. (line 6)\n* extra post-vertical line space (\\x): Changing the Vertical Spacing.\n(line 35)\n* extra post-vertical line space register (.a): Manipulating Spacing.\n(line 82)\n* extra pre-vertical line space (\\x): Changing the Vertical Spacing.\n(line 27)\n* extra spaces between words: Adjustment. (line 6)\n* extreme values representable with Roman numerals: Assigning Register Formats.\n(line 58)\n* extremum operators (>?, : Page Location Traps. (line 26)\n* footers [ms]: ms Headers and Footers.\n(line 6)\n* footnote marker [ms]: ms Footnotes. (line 6)\n* footnotes: Footnotes and Endnotes.\n(line 6)\n* footnotes [ms]: ms Footnotes. (line 6)\n* footnotes, and displays [ms]: ms Footnotes. (line 44)\n* footnotes, and keeps [ms]: ms Footnotes. (line 44)\n* form letters: I/O. (line 112)\n* format of font description file: DESC File Format. (line 6)\n* format of font description files: Font Description File Format.\n(line 6)\n* format of font files: Font Description File Format.\n(line 6)\n* format of register (\\g): Assigning Register Formats.\n(line 72)\n* format, paper: Paper Format. (line 6)\n* formats, file: File Formats. (line 6)\n* formatter instructions: Formatter Instructions.\n(line 6)\n* formatting a backslash glyph (\\[rs]): Using Escape Sequences.\n(line 66)\n* formatting a title line (tl): Page Layout. (line 39)\n* formatting the escape character (\\e): Using Escape Sequences.\n(line 63)\n* formatting the time: I/O. (line 193)\n* fp request, and font translations: Selecting Fonts. (line 69)\n* fp request, incompatibilities with AT&T troff: Other Differences.\n(line 79)\n* fractional point sizes: Using Fractional Type Sizes.\n(line 6)\n* fractional point sizes <1>: Other Differences. (line 57)\n* fractional type sizes: Using Fractional Type Sizes.\n(line 6)\n* fractional type sizes <1>: Other Differences. (line 57)\n* fractional type sizes in ms macros: Differences from AT&T ms.\n(line 45)\n* French spacing: Sentences. (line 18)\n* fspecial request, and font styles: Font Families. (line 63)\n* fspecial request, and font translations: Selecting Fonts. (line 69)\n* fspecial request, and glyph search order: Using Symbols. (line 18)\n* fspecial request, and imitating bold: Artificial Fonts. (line 114)\n* ft request, and font translations: Selecting Fonts. (line 69)\n* full-service macro package: Major Macro Packages.\n(line 9)\n* geometry, page: Page Geometry. (line 6)\n* GGL (groff glyph list): Using Symbols. (line 94)\n* GGL (groff glyph list) <1>: Character Classes. (line 33)\n* glossary-style list, example markup [ms]: Lists in ms. (line 61)\n* glyph: Using Symbols. (line 6)\n* glyph for line drawing: Drawing Geometric Objects.\n(line 44)\n* glyph names, composite: Using Symbols. (line 94)\n* glyph pile (\\b): Drawing Geometric Objects.\n(line 184)\n* glyph properties (cflags): Using Symbols. (line 252)\n* glyph, box rule (\\[br]): Drawing Geometric Objects.\n(line 44)\n* glyph, constant space: Artificial Fonts. (line 125)\n* glyph, defining (char): Using Symbols. (line 354)\n* glyph, distinguished from character: Using Symbols. (line 6)\n* glyph, for line drawing: Drawing Geometric Objects.\n(line 22)\n* glyph, for margins (mc): Miscellaneous. (line 110)\n* glyph, last, dimensions (.w, .cht, .cdp, .csk): Environments.\n(line 126)\n* glyph, leader repetition (lc): Leaders. (line 22)\n* glyph, numbered (\\N): Character Translations.\n(line 25)\n* glyph, numbered (\\N) <1>: Using Symbols. (line 216)\n* glyph, removing definition (rchar, rfschar): Using Symbols. (line 411)\n* glyph, soft hyphen (hy): Manipulating Hyphenation.\n(line 97)\n* glyph, tab repetition (tc): Tabs and Fields. (line 127)\n* glyph, underscore (\\[ru]): Drawing Geometric Objects.\n(line 22)\n* glyphs, available, list of (groffchar(7) man page): Using Symbols.\n(line 81)\n* glyphs, output, and input characters, compatibility with AT&T troff: Other Differences.\n(line 79)\n* glyphs, overstriking (\\o): Page Motions. (line 240)\n* glyphs, unnamed: Using Symbols. (line 226)\n* glyphs, unnamed, accessing with \\N: Font Description File Format.\n(line 73)\n* GNU troff, identification register (.g): Built-in Registers.\n(line 37)\n* GNU troff, PID register ($$): Built-in Registers. (line 69)\n* GNU troff, process ID register ($$): Built-in Registers. (line 69)\n* GNU-specific register (.g): Built-in Registers. (line 37)\n* graphic renditions: Using Fonts. (line 49)\n* greater than (or equal to) operator: Numeric Expressions. (line 74)\n* groff capabilities: groff Capabilities. (line 6)\n* groff glyph list (GGL): Using Symbols. (line 94)\n* groff glyph list (GGL) <1>: Character Classes. (line 33)\n* groff invocation: Invoking groff. (line 6)\n* GROFFBINPATH, environment variable: Environment. (line 10)\n* GROFFCOMMANDPREFIX, environment variable: Environment. (line 14)\n* GROFFENCODING, environment variable: Environment. (line 25)\n* GROFFFONTPATH, environment variable: Environment. (line 34)\n* GROFFFONTPATH, environment variable <1>: Font Directories.\n(line 27)\n* GROFFTMACPATH, environment variable: Environment. (line 41)\n* GROFFTMACPATH, environment variable <1>: Macro Directories.\n(line 16)\n* GROFFTMPDIR, environment variable: Environment. (line 48)\n* GROFFTYPESETTER, environment variable: Environment. (line 56)\n* groff--what is it?: What Is groff?. (line 6)\n* groff, and pi request: I/O. (line 166)\n* grohtml, the program: Groff Options. (line 294)\n* gtroff, interactive use: Debugging. (line 95)\n* gtroff, output: gtroff Output. (line 6)\n* gtroff, reference: GNU troff Reference. (line 6)\n* hair space (\\^): Page Motions. (line 151)\n* hcode request, and glyph definitions: Using Symbols. (line 354)\n* headers: Page Layout. (line 34)\n* headers <1>: Page Location Traps. (line 26)\n* headers [ms]: ms Headers and Footers.\n(line 6)\n* height, font, changing (\\H): Artificial Fonts. (line 16)\n* height, of last glyph (.cht): Environments. (line 126)\n* high-water mark register (.h): Diversions. (line 95)\n* home directory: Macro Directories. (line 21)\n* horizontal discardable space: Manipulating Filling and Adjustment.\n(line 296)\n* horizontal input line position register (hp): Page Motions. (line 233)\n* horizontal input line position, saving (\\k): Page Motions. (line 227)\n* horizontal line, drawing (\\l): Drawing Geometric Objects.\n(line 18)\n* horizontal motion (\\h): Page Motions. (line 125)\n* horizontal motion quantum: DESC File Format. (line 26)\n* horizontal motion quantum register (.H): Motion Quanta. (line 13)\n* horizontal output line position register (.k): Page Motions.\n(line 236)\n* horizontal resolution: DESC File Format. (line 26)\n* horizontal resolution register (.H): Motion Quanta. (line 13)\n* horizontal space (\\h): Page Motions. (line 125)\n* horizontal space, unformatting: Punning Names. (line 95)\n* horizontal tab character: Tabs and Leaders. (line 6)\n* hours, current time (hours): Built-in Registers. (line 84)\n* hpf request, and hyphenation language: Manipulating Hyphenation.\n(line 328)\n* hw request, and hy restrictions: Manipulating Hyphenation.\n(line 35)\n* hw request, and hyphenation language: Manipulating Hyphenation.\n(line 328)\n* hy glyph, and cflags: Using Symbols. (line 281)\n* hyphen, explicit (\\%): Manipulating Hyphenation.\n(line 342)\n* hyphenated lines, consecutive (hlm): Manipulating Hyphenation.\n(line 342)\n* hyphenating characters: Using Symbols. (line 274)\n* hyphenation: Hyphenation. (line 6)\n* hyphenation character (\\%): Manipulating Hyphenation.\n(line 57)\n* hyphenation code (hcode): Manipulating Hyphenation.\n(line 293)\n* hyphenation consecutive line count register (.hlc): Manipulating Hyphenation.\n(line 349)\n* hyphenation consecutive line limit register (.hlm): Manipulating Hyphenation.\n(line 349)\n* hyphenation exceptions: Manipulating Hyphenation.\n(line 21)\n* hyphenation language register (.hla): Manipulating Hyphenation.\n(line 335)\n* hyphenation margin (hym): Manipulating Hyphenation.\n(line 355)\n* hyphenation margin register (.hym): Manipulating Hyphenation.\n(line 365)\n* hyphenation mode register (.hy): Manipulating Hyphenation.\n(line 119)\n* hyphenation parameters, automatic: Manipulating Hyphenation.\n(line 107)\n* hyphenation pattern files: Manipulating Hyphenation.\n(line 181)\n* hyphenation patterns (hpf): Manipulating Hyphenation.\n(line 235)\n* hyphenation space (hys): Manipulating Hyphenation.\n(line 370)\n* hyphenation space adjustment threshold: Manipulating Hyphenation.\n(line 370)\n* hyphenation space adjustment threshold register (.hys): Manipulating Hyphenation.\n(line 381)\n* hyphenation, automatic: Manipulating Hyphenation.\n(line 6)\n* hyphenation, disabling (\\%): Manipulating Hyphenation.\n(line 57)\n* hyphenation, explicit: Manipulating Hyphenation.\n(line 13)\n* hyphenation, incompatibilities with AT&T troff: Other Differences.\n(line 27)\n* hyphenation, manipulating: Manipulating Hyphenation.\n(line 6)\n* hyphenation, manual: Manipulating Hyphenation.\n(line 13)\n* i scaling unit: Measurements. (line 23)\n* i/o: I/O. (line 6)\n* IBM code page 1047 input encoding: Input Encodings. (line 12)\n* IBM code page 1047 output encoding: Groff Options. (line 283)\n* identifiers: Identifiers. (line 6)\n* identifiers, undefined: Identifiers. (line 88)\n* ie request, and font translations: Selecting Fonts. (line 69)\n* ie request, and warnings: Warnings. (line 38)\n* ie request, operators to use with: Operators in Conditionals.\n(line 6)\n* if request, and font translations: Selecting Fonts. (line 69)\n* if request, and the ! operator: Numeric Expressions. (line 23)\n* if request, operators to use with: Operators in Conditionals.\n(line 6)\n* if-else: if-else. (line 6)\n* if-then: if-then. (line 6)\n* imitating boldface (bd): Artificial Fonts. (line 97)\n* implementation differences: Implementation Differences.\n(line 6)\n* implicit line break: Breaking. (line 6)\n* implicit trap: The Implicit Page Trap.\n(line 6)\n* in request, causing implicit break: Manipulating Filling and Adjustment.\n(line 6)\n* in request, using + and - with: Numeric Expressions. (line 121)\n* inch scaling unit (i): Measurements. (line 23)\n* including a file (so): I/O. (line 10)\n* incompatibilities with AT&T troff: Implementation Differences.\n(line 6)\n* increment value without changing the register: Auto-increment.\n(line 45)\n* incrementation, automatic, of a register: Auto-increment. (line 6)\n* indentation (in): Line Layout. (line 25)\n* indentation, of roff source code: Invoking Requests. (line 28)\n* index, in macro package: Indexing. (line 6)\n* indicator, scaling: Measurements. (line 6)\n* indirect assignments: Interpolating Registers.\n(line 11)\n* input and output requests: I/O. (line 6)\n* input characters and output glyphs, compatibility with AT&T troff: Other Differences.\n(line 79)\n* input characters, invalid: Identifiers. (line 13)\n* input conventions: Input Conventions. (line 6)\n* input encoding, code page 1047: Input Encodings. (line 12)\n* input encoding, EBCDIC: Input Encodings. (line 12)\n* input encoding, Latin-1 (ISO 8859-1): Input Encodings. (line 17)\n* input encoding, Latin-2 (ISO 8859-2): Input Encodings. (line 30)\n* input encoding, Latin-5 (ISO 8859-9): Input Encodings. (line 36)\n* input encoding, Latin-9 (ISO 8859-15): Input Encodings. (line 41)\n* input file name, current, register (.F): Built-in Registers.\n(line 34)\n* input level: Calling Macros. (line 84)\n* input level in delimited arguments: Compatibility Mode. (line 100)\n* input line continuation (\\): Line Continuation. (line 11)\n* input line number register (.c, c.): Built-in Registers. (line 30)\n* input line number, setting (lf): Debugging. (line 31)\n* input line position, horizontal, saving (\\k): Page Motions. (line 227)\n* input line trap, clearing (it, itc): Input Line Traps. (line 8)\n* input line trap, setting (it, itc): Input Line Traps. (line 8)\n* input line traps: Input Line Traps. (line 6)\n* input line traps and interrupted lines (itc): Input Line Traps.\n(line 32)\n* input line, horizontal position, register (hp): Page Motions.\n(line 233)\n* input line, productive: Manipulating Filling and Adjustment.\n(line 179)\n* input stack, backtrace (backtrace): Debugging. (line 104)\n* input stack, setting limit: Debugging. (line 125)\n* input token: Gtroff Internals. (line 6)\n* input, 8-bit: Font Description File Format.\n(line 73)\n* input, standard, reading from (rd): I/O. (line 95)\n* inserting horizontal space (\\h): Page Motions. (line 125)\n* installation: Installation. (line 6)\n* instructing the formatter: Formatter Instructions.\n(line 6)\n* inter-sentence space size register (.sss): Manipulating Filling and Adjustment.\n(line 269)\n* inter-sentence space, additional: Manipulating Filling and Adjustment.\n(line 275)\n* inter-word spacing, minimal: Manipulating Filling and Adjustment.\n(line 273)\n* interactive use of gtroff: Debugging. (line 95)\n* intercepting requests: Control Characters. (line 45)\n* intermediate output: gtroff Output. (line 16)\n* interpolating registers (\\n): Interpolating Registers.\n(line 6)\n* interpolation: Requests and Macros. (line 34)\n* interpolation depth: Calling Macros. (line 84)\n* interpolation depth in delimited arguments: Compatibility Mode.\n(line 100)\n* interpolation of strings (\\*): Strings. (line 28)\n* interpretation mode: Copy Mode. (line 15)\n* interrupted line: Line Continuation. (line 40)\n* interrupted line register (.int): Line Continuation. (line 65)\n* interrupted lines and input line traps (itc): Input Line Traps.\n(line 32)\n* introduction: Introduction. (line 6)\n* invalid characters for trf request: I/O. (line 70)\n* invalid input characters: Identifiers. (line 13)\n* invocation examples: Invocation Examples. (line 6)\n* invoking groff: Invoking groff. (line 6)\n* invoking requests: Invoking Requests. (line 6)\n* ISO 646 output encoding: Groff Options. (line 271)\n* ISO 8859-1 (Latin-1) output encoding: Groff Options. (line 275)\n* ISO 8859-1 (Latin-1), input encoding: Input Encodings. (line 17)\n* ISO 8859-15 (Latin-9), input encoding: Input Encodings. (line 41)\n* ISO 8859-2 (Latin-2), input encoding: Input Encodings. (line 30)\n* ISO 8859-9 (Latin-5), input encoding: Input Encodings. (line 36)\n* italic correction (\\/): Italic Corrections. (line 10)\n* justifying text: Manipulating Filling and Adjustment.\n(line 6)\n* justifying text (rj): Manipulating Filling and Adjustment.\n(line 248)\n* keep, floating: Displays and Keeps. (line 17)\n* keeps (introduction): Displays and Keeps. (line 13)\n* keeps [ms]: ms keeps and displays.\n(line 6)\n* keeps, and footnotes [ms]: ms Footnotes. (line 44)\n* kerning and ligatures: Ligatures and Kerning.\n(line 6)\n* kerning enabled register (.kern): Ligatures and Kerning.\n(line 42)\n* kerning, activating (kern): Ligatures and Kerning.\n(line 42)\n* kerning, track: Ligatures and Kerning.\n(line 53)\n* landscape page orientation: Paper Format. (line 6)\n* language [ms]: ms language and localization.\n(line 6)\n* last glyph, dimensions (.w, .cht, .cdp, .csk): Environments.\n(line 126)\n* last-requested point size registers (.psr, .sr): Using Fractional Type Sizes.\n(line 47)\n* last-requested type size registers (.psr, .sr): Using Fractional Type Sizes.\n(line 47)\n* Latin-1 (ISO 8859-1) output encoding: Groff Options. (line 275)\n* Latin-1 (ISO 8859-1), input encoding: Input Encodings. (line 17)\n* Latin-2 (ISO 8859-2), input encoding: Input Encodings. (line 30)\n* Latin-5 (ISO 8859-9), input encoding: Input Encodings. (line 36)\n* Latin-9 (ISO 8859-15), input encoding: Input Encodings. (line 41)\n* layout, line: Line Layout. (line 6)\n* layout, page: Page Layout. (line 6)\n* lc request, and glyph definitions: Using Symbols. (line 354)\n* leader character: Tabs and Leaders. (line 6)\n* leader character <1>: Leaders. (line 13)\n* leader character, and translations: Character Translations.\n(line 35)\n* leader character, non-interpreted (\\a): Leaders. (line 19)\n* leader repetition character (lc): Leaders. (line 22)\n* leaders: Leaders. (line 6)\n* leading: Manipulating Type Size and Vertical Spacing.\n(line 12)\n* leading space macro (lsm): Breaking. (line 38)\n* leading space traps: Leading Space Traps. (line 6)\n* leading spaces: Breaking. (line 38)\n* leading spaces macro (lsm): Leading Space Traps. (line 9)\n* leading spaces with ds: Strings. (line 70)\n* left italic correction (\\,): Italic Corrections. (line 20)\n* left margin (po): Line Layout. (line 21)\n* length of a string (length): Strings. (line 135)\n* length of line (ll): Line Layout. (line 29)\n* length of previous line (.n): Environments. (line 141)\n* length of the page, configuring (pl): Page Layout. (line 12)\n* length of title line, configuring (lt): Page Layout. (line 56)\n* length request, and copy mode: Strings. (line 135)\n* less than (or equal to) operator: Numeric Expressions. (line 74)\n* letters, form: I/O. (line 112)\n* level, input: Calling Macros. (line 84)\n* level, suppression nesting, register: Suppressing Output. (line 60)\n* lf request, incompatibilities with AT&T troff: Other Differences.\n(line 49)\n* ligature: Using Symbols. (line 6)\n* ligatures and kerning: Ligatures and Kerning.\n(line 6)\n* ligatures enabled register (.lg): Ligatures and Kerning.\n(line 24)\n* ligatures, activating (lg): Ligatures and Kerning.\n(line 24)\n* limitations of \\b escape sequence: Drawing Geometric Objects.\n(line 192)\n* line break: Manipulating Filling and Adjustment.\n(line 6)\n* line break (introduction): Basics. (line 136)\n* line break, output: Breaking. (line 6)\n* line control: Line Continuation. (line 6)\n* line dimensions: Line Layout. (line 6)\n* line drawing glyph: Drawing Geometric Objects.\n(line 22)\n* line drawing glyph <1>: Drawing Geometric Objects.\n(line 44)\n* line indentation (in): Line Layout. (line 25)\n* line layout: Line Layout. (line 6)\n* line length (ll): Line Layout. (line 29)\n* line length register (.l): Line Layout. (line 154)\n* line length, previous (.n): Environments. (line 141)\n* line number, input, register (.c, c.): Built-in Registers. (line 30)\n* line number, output, register (ln): Miscellaneous. (line 33)\n* line numbers, printing (nm): Miscellaneous. (line 11)\n* line space, extra post-vertical (\\x): Changing the Vertical Spacing.\n(line 35)\n* line space, extra pre-vertical (\\x): Changing the Vertical Spacing.\n(line 27)\n* line spacing register (.L): Manipulating Spacing.\n(line 62)\n* line spacing, post-vertical (pvs): Changing the Vertical Spacing.\n(line 39)\n* line thickness (\\D't ...'): Drawing Geometric Objects.\n(line 174)\n* line-tabs mode: Tabs and Fields. (line 140)\n* line, blank: Breaking. (line 30)\n* line, drawing (\\D'l ...'): Drawing Geometric Objects.\n(line 120)\n* line, horizontal, drawing (\\l): Drawing Geometric Objects.\n(line 18)\n* line, input, continuation (\\): Line Continuation. (line 11)\n* line, input, horizontal position, register (hp): Page Motions.\n(line 233)\n* line, input, horizontal position, saving (\\k): Page Motions.\n(line 227)\n* line, interrupted: Line Continuation. (line 40)\n* line, output, continuation (\\c): Line Continuation. (line 40)\n* line, output, horizontal position, register (.k): Page Motions.\n(line 236)\n* line, productive input: Manipulating Filling and Adjustment.\n(line 179)\n* line, vertical, drawing (\\L): Drawing Geometric Objects.\n(line 44)\n* lines, blank, disabling: Manipulating Spacing.\n(line 118)\n* lines, centering (ce): Manipulating Filling and Adjustment.\n(line 209)\n* lines, centering (introduction): Basics. (line 118)\n* lines, consecutive hyphenated (hlm): Manipulating Hyphenation.\n(line 342)\n* lines, interrupted, and input line traps (itc): Input Line Traps.\n(line 32)\n* lines, right-aligning (introduction): Basics. (line 130)\n* lines, right-justifying (introduction): Basics. (line 130)\n* list of special characters (groffchar(7) man page): Using Symbols.\n(line 81)\n* listing page location traps (ptr): Debugging. (line 90)\n* lists: Paragraphs. (line 14)\n* ll request, using + and - with: Numeric Expressions. (line 121)\n* localization: Manipulating Hyphenation.\n(line 280)\n* localization [ms]: ms language and localization.\n(line 6)\n* locating macro files: Macro Directories. (line 8)\n* locating macro packages: Macro Directories. (line 8)\n* location, vertical, page, marking (mk): Page Motions. (line 11)\n* location, vertical, page, returning to marked (rt): Page Motions.\n(line 11)\n* logical \"and\" operator: Numeric Expressions. (line 80)\n* logical \"or\" operator: Numeric Expressions. (line 80)\n* logical complementation operator: Numeric Expressions. (line 84)\n* logical conjunction operator: Numeric Expressions. (line 80)\n* logical disjunction operator: Numeric Expressions. (line 80)\n* logical not, limitation in expression: Numeric Expressions. (line 84)\n* logical operators: Numeric Expressions. (line 80)\n* long names: Compatibility Mode. (line 6)\n* loops and conditionals: Conditionals and Loops.\n(line 6)\n* lowercasing a string (stringdown): Strings. (line 171)\n* ls request, alternative to (pvs): Changing the Vertical Spacing.\n(line 51)\n* lt request, using + and - with: Numeric Expressions. (line 121)\n* m scaling unit: Measurements. (line 51)\n* M scaling unit: Measurements. (line 61)\n* machine units: Page Geometry. (line 13)\n* macro: Requests and Macros. (line 34)\n* macro arguments: Calling Macros. (line 6)\n* macro arguments, and compatibility mode: Gtroff Internals. (line 90)\n* macro arguments, and tabs: Invoking Requests. (line 14)\n* macro directories: Macro Directories. (line 6)\n* macro file search path: Macro Directories. (line 8)\n* macro name register (\\$0): Parameters. (line 77)\n* macro names, starting with [ or ], and refer: Identifiers. (line 55)\n* macro package: Macro Packages. (line 6)\n* macro package search path: Macro Directories. (line 8)\n* macro package usage, basics of: Basics. (line 6)\n* macro package, auxiliary: Major Macro Packages.\n(line 20)\n* macro package, full-service: Major Macro Packages.\n(line 9)\n* macro package, introduction: Macro Package Intro. (line 6)\n* macro package, major: Major Macro Packages.\n(line 6)\n* macro package, minor: Major Macro Packages.\n(line 20)\n* macro package, structuring the source of: Invoking Requests.\n(line 28)\n* macro, appending to (am): Writing Macros. (line 129)\n* macro, creating alias for (als): Strings. (line 198)\n* macro, end-of-input (em): End-of-input Traps. (line 7)\n* macro, parameters (\\$): Parameters. (line 36)\n* macro, removing (rm): Strings. (line 193)\n* macro, removing alias for (rm): Strings. (line 233)\n* macro, renaming (rn): Strings. (line 190)\n* macros, recursive: while. (line 38)\n* macros, searching: Macro Directories. (line 6)\n* macros, shared name space with strings and diversions: Identifiers.\n(line 100)\n* macros, tutorial for users: Tutorial for Macro Users.\n(line 6)\n* macros, writing: Writing Macros. (line 6)\n* magnification of a font (fzoom): Selecting Fonts. (line 84)\n* major macro package: Major Macro Packages.\n(line 6)\n* major version number register (.x): Built-in Registers. (line 57)\n* man macros, custom headers and footers: Optional man extensions.\n(line 12)\n* man macros, Ultrix-specific: Optional man extensions.\n(line 30)\n* man pages: man. (line 6)\n* manipulating filling and adjustment: Manipulating Filling and Adjustment.\n(line 6)\n* manipulating hyphenation: Manipulating Hyphenation.\n(line 6)\n* manipulating spacing: Manipulating Spacing.\n(line 6)\n* manipulating type size and vertical spacing: Manipulating Type Size and Vertical Spacing.\n(line 6)\n* manual hyphenation: Manipulating Hyphenation.\n(line 13)\n* manual pages: man. (line 6)\n* margin for hyphenation (hym): Manipulating Hyphenation.\n(line 355)\n* margin glyph (mc): Miscellaneous. (line 110)\n* margin, bottom: Page Location Traps. (line 26)\n* margin, left (po): Line Layout. (line 21)\n* margin, right: Line Layout. (line 32)\n* margin, top: Page Location Traps. (line 26)\n* mark, high-water, register (.h): Diversions. (line 95)\n* marker, footnote [ms]: ms Footnotes. (line 6)\n* marking vertical page location (mk): Page Motions. (line 11)\n* maximum operator: Numeric Expressions. (line 65)\n* maximum value representable with Roman numerals: Assigning Register Formats.\n(line 58)\n* mdoc macros: mdoc. (line 6)\n* me macro package: me. (line 6)\n* measurement units: Measurements. (line 6)\n* measurements: Measurements. (line 6)\n* measurements, specifying safely: Default Units. (line 29)\n* metrics, font: Using Fonts. (line 21)\n* minimal inter-word spacing: Manipulating Filling and Adjustment.\n(line 273)\n* minimum operator: Numeric Expressions. (line 65)\n* minimum value representable with Roman numerals: Assigning Register Formats.\n(line 58)\n* minor macro package: Major Macro Packages.\n(line 20)\n* minor version number register (.y): Built-in Registers. (line 61)\n* minutes, current time (minutes): Built-in Registers. (line 81)\n* mm macro package: mm. (line 6)\n* mode for constant glyph space (cs): Artificial Fonts. (line 125)\n* mode, compatibility: Compatibility Mode. (line 6)\n* mode, compatibility, and parameters: Gtroff Internals. (line 90)\n* mode, copy: Copy Mode. (line 6)\n* mode, copy <1>: Copy Mode. (line 6)\n* mode, copy, and \\!: Diversions. (line 162)\n* mode, copy, and \\?: Operators in Conditionals.\n(line 95)\n* mode, copy, and \\? <1>: Diversions. (line 162)\n* mode, copy, and \\a: Leaders. (line 19)\n* mode, copy, and \\t: Tabs and Fields. (line 10)\n* mode, copy, and \\V: I/O. (line 258)\n* mode, copy, and cf request: I/O. (line 58)\n* mode, copy, and device request: Postprocessor Access.\n(line 21)\n* mode, copy, and length request: Strings. (line 135)\n* mode, copy, and macro parameters: Parameters. (line 36)\n* mode, copy, and output request: Diversions. (line 194)\n* mode, copy, and trf request: I/O. (line 58)\n* mode, copy, and write request: I/O. (line 220)\n* mode, copy, and writec request: I/O. (line 220)\n* mode, copy, and writem request: I/O. (line 234)\n* mode, fill (fi), enabling: Manipulating Filling and Adjustment.\n(line 67)\n* mode, fill, and \\c: Line Continuation. (line 46)\n* mode, fill, and break warnings: Warnings. (line 27)\n* mode, fill, and inter-sentence space: Manipulating Filling and Adjustment.\n(line 280)\n* mode, fill, disabling: Manipulating Filling and Adjustment.\n(line 74)\n* mode, interpretation: Copy Mode. (line 15)\n* mode, line-tabs: Tabs and Fields. (line 140)\n* mode, no-fill: Manipulating Filling and Adjustment.\n(line 74)\n* mode, no-fill, and \\c: Line Continuation. (line 54)\n* mode, no-space (ns): Manipulating Spacing.\n(line 118)\n* mode, nroff: troff and nroff Modes.\n(line 6)\n* mode, safer: Groff Options. (line 235)\n* mode, safer <1>: Macro Directories. (line 18)\n* mode, safer <2>: Built-in Registers. (line 53)\n* mode, safer <3>: I/O. (line 41)\n* mode, safer <4>: I/O. (line 153)\n* mode, safer <5>: I/O. (line 175)\n* mode, safer <6>: I/O. (line 214)\n* mode, safer <7>: Safer Mode. (line 6)\n* mode, troff: troff and nroff Modes.\n(line 6)\n* mode, unsafe: Groff Options. (line 311)\n* mode, unsafe <1>: Macro Directories. (line 18)\n* mode, unsafe <2>: Built-in Registers. (line 53)\n* mode, unsafe <3>: I/O. (line 41)\n* mode, unsafe <4>: I/O. (line 153)\n* mode, unsafe <5>: I/O. (line 175)\n* mode, unsafe <6>: I/O. (line 214)\n* modifying requests: Control Characters. (line 45)\n* modulus: Numeric Expressions. (line 17)\n* mom macro package: mom. (line 6)\n* month of the year register (mo): Built-in Registers. (line 93)\n* motion operators: Numeric Expressions. (line 115)\n* motion quanta: Motion Quanta. (line 6)\n* motion quantum, horizontal: DESC File Format. (line 26)\n* motion quantum, horizontal, register (.H): Motion Quanta. (line 13)\n* motion quantum, vertical: DESC File Format. (line 134)\n* motion, horizontal (\\h): Page Motions. (line 125)\n* motion, vertical (\\v): Page Motions. (line 81)\n* motions, page: Page Motions. (line 6)\n* mounting a font (fp): Font Positions. (line 18)\n* mounting position: Using Fonts. (line 21)\n* mounting position <1>: Using Fonts. (line 21)\n* mounting, font, automatic: Selecting Fonts. (line 28)\n* ms macros: ms. (line 6)\n* ms macros, accent marks: ms Legacy Features. (line 6)\n* ms macros, body text: ms Body Text. (line 6)\n* ms macros, creating table of contents: ms TOC. (line 6)\n* ms macros, displays: ms keeps and displays.\n(line 6)\n* ms macros, document control settings: ms Document Control Settings.\n(line 6)\n* ms macros, document description: ms Document Description Macros.\n(line 6)\n* ms macros, equations: ms Insertions. (line 6)\n* ms macros, figures: ms Insertions. (line 6)\n* ms macros, footers: ms Headers and Footers.\n(line 6)\n* ms macros, footnotes: ms Footnotes. (line 6)\n* ms macros, fractional type sizes in: Differences from AT&T ms.\n(line 45)\n* ms macros, general structure: ms Document Structure.\n(line 6)\n* ms macros, groff differences from AT&T: Differences from AT&T ms.\n(line 6)\n* ms macros, headers: ms Headers and Footers.\n(line 6)\n* ms macros, headings: Headings in ms. (line 6)\n* ms macros, keeps: ms keeps and displays.\n(line 6)\n* ms macros, language: ms language and localization.\n(line 6)\n* ms macros, lists: Lists in ms. (line 6)\n* ms macros, localization: ms language and localization.\n(line 6)\n* ms macros, margins: ms Margins. (line 6)\n* ms macros, multiple columns: ms Multiple Columns. (line 6)\n* ms macros, naming conventions: ms Naming Conventions.\n(line 6)\n* ms macros, nested lists: Indented regions in ms.\n(line 18)\n* ms macros, obtaining typographical symbols: Typographical symbols in ms.\n(line 6)\n* ms macros, page layout: ms Page Layout. (line 6)\n* ms macros, paragraph handling: Paragraphs in ms. (line 6)\n* ms macros, references: ms Insertions. (line 6)\n* ms macros, special characters: ms Legacy Features. (line 6)\n* ms macros, strings: ms Legacy Features. (line 6)\n* ms macros, tables: ms Insertions. (line 6)\n* ms macros, text settings: Text settings in ms. (line 6)\n* multi-file documents: Debugging. (line 31)\n* multi-line strings: Strings. (line 79)\n* multi-page table example [ms]: ms Insertions. (line 48)\n* multiple columns [ms]: ms Multiple Columns. (line 6)\n* multiplication: Numeric Expressions. (line 17)\n* n scaling unit: Measurements. (line 55)\n* name space, common, of macros, diversions, and strings: Identifiers.\n(line 100)\n* name, background color, register (.M): Colors. (line 93)\n* name, fill color, register (.M): Colors. (line 93)\n* name, stroke color, register (.m): Colors. (line 72)\n* named character (\\C): Using Symbols. (line 199)\n* names, long: Compatibility Mode. (line 6)\n* naming conventions, ms macros: ms Naming Conventions.\n(line 6)\n* ne request, and the .trunc register: Page Location Traps. (line 173)\n* ne request, comparison with sv: Page Control. (line 66)\n* negating register values: Setting Registers. (line 76)\n* negation: Numeric Expressions. (line 23)\n* nested assignments: Interpolating Registers.\n(line 11)\n* nested diversions: Diversions. (line 88)\n* nested lists [ms]: Indented regions in ms.\n(line 18)\n* nesting level, suppression, register: Suppressing Output. (line 60)\n* new page (bp): Page Control. (line 14)\n* newline character, and translations: Character Translations.\n(line 35)\n* newline character, in strings, escaping: Strings. (line 79)\n* newline, as delimiter: Delimiters. (line 22)\n* newline, final, stripping in diversions: Punning Names. (line 95)\n* next file, processing (nx): I/O. (line 90)\n* next free font position register (.fp): Font Positions. (line 55)\n* next page number register (.pn): Page Layout. (line 31)\n* next page number, configuring (pn): Page Layout. (line 26)\n* nf request, causing implicit break: Manipulating Filling and Adjustment.\n(line 6)\n* nl register, and .d: Diversions. (line 88)\n* nl register, difference from .h: Diversions. (line 108)\n* nm request, using + and - with: Numeric Expressions. (line 121)\n* no-break control character ('): Requests and Macros. (line 7)\n* no-break control character, changing (c2): Control Characters.\n(line 18)\n* no-fill mode: Manipulating Filling and Adjustment.\n(line 74)\n* no-fill mode, and \\c: Line Continuation. (line 54)\n* no-space mode (ns): Manipulating Spacing.\n(line 118)\n* node, output: Gtroff Internals. (line 6)\n* non-printing break point (\\:): Manipulating Hyphenation.\n(line 73)\n* nr request, and warnings: Warnings. (line 78)\n* nr request, using + and - with: Numeric Expressions. (line 121)\n* nroff mode: troff and nroff Modes.\n(line 6)\n* number formats, assigning to register (af): Assigning Register Formats.\n(line 6)\n* number of registers register (.R): Built-in Registers. (line 45)\n* number, input line, setting (lf): Debugging. (line 31)\n* number, page, next, configuring (pn): Page Layout. (line 26)\n* numbered glyph (\\N): Character Translations.\n(line 25)\n* numbered glyph (\\N) <1>: Using Symbols. (line 216)\n* numbered list, example markup [ms]: Lists in ms. (line 33)\n* numbers, line, printing (nm): Miscellaneous. (line 11)\n* numeral-width space (\\0): Page Motions. (line 157)\n* numerals, as delimiters: Delimiters. (line 36)\n* numerals, Roman: Assigning Register Formats.\n(line 26)\n* numeric expression, valid: Numeric Expressions. (line 180)\n* numeric expressions: Numeric Expressions. (line 6)\n* object creation: Writing Macros. (line 154)\n* offset, page: Page Geometry. (line 37)\n* offset, page (po): Line Layout. (line 21)\n* open request, and safer mode: Groff Options. (line 235)\n* opena request, and safer mode: Groff Options. (line 235)\n* opening brace escape sequence (\\}): Conditional Blocks. (line 13)\n* opening file (open): I/O. (line 208)\n* operator, scaling: Numeric Expressions. (line 48)\n* operators, arithmetic: Numeric Expressions. (line 17)\n* operators, as delimiters: Delimiters. (line 38)\n* operators, comparison: Numeric Expressions. (line 74)\n* operators, extremum (>?, : Strings. (line 13)\n* output device name string (.T), in other implementations: Other Differences.\n(line 34)\n* output device usage register (.T): Groff Options. (line 300)\n* output device usage register (.T), incompatibility with AT&T troff: Other Differences.\n(line 44)\n* output devices: Output Device Intro. (line 6)\n* output encoding, ASCII: Groff Options. (line 271)\n* output encoding, code page 1047: Groff Options. (line 283)\n* output encoding, EBCDIC: Groff Options. (line 283)\n* output encoding, ISO 646: Groff Options. (line 271)\n* output encoding, Latin-1 (ISO 8859-1): Groff Options. (line 275)\n* output encoding, UTF-8: Groff Options. (line 279)\n* output glyphs, and input characters, compatibility with AT&T troff: Other Differences.\n(line 79)\n* output line break: Breaking. (line 6)\n* output line number register (ln): Miscellaneous. (line 33)\n* output line properties: Manipulating Filling and Adjustment.\n(line 26)\n* output line, continuation (\\c): Line Continuation. (line 40)\n* output line, horizontal position, register (.k): Page Motions.\n(line 236)\n* output node: Gtroff Internals. (line 6)\n* output request, and \\!: Diversions. (line 194)\n* output request, and copy mode: Diversions. (line 194)\n* output, filling, disablement of (nf): Manipulating Filling and Adjustment.\n(line 74)\n* output, filling, enablement of (fi): Manipulating Filling and Adjustment.\n(line 67)\n* output, flush (fl): Debugging. (line 95)\n* output, gtroff: gtroff Output. (line 6)\n* output, intermediate: gtroff Output. (line 16)\n* output, suppressing (\\O): Suppressing Output. (line 7)\n* output, transparent (\\!, \\?): Diversions. (line 154)\n* output, transparent (cf, trf): I/O. (line 58)\n* output, transparent, incompatibilities with AT&T troff: Other Differences.\n(line 106)\n* output, troff: gtroff Output. (line 16)\n* overlapping characters: Using Symbols. (line 288)\n* overstriking glyphs (\\o): Page Motions. (line 240)\n* p scaling unit: Measurements. (line 29)\n* P scaling unit: Measurements. (line 33)\n* package, macro: Macro Packages. (line 6)\n* package, macro, auxiliary: Major Macro Packages.\n(line 20)\n* package, macro, full-service: Major Macro Packages.\n(line 9)\n* package, macro, introduction: Macro Package Intro. (line 6)\n* package, macro, major: Major Macro Packages.\n(line 6)\n* package, macro, minor: Major Macro Packages.\n(line 20)\n* package, macro, search path: Macro Directories. (line 8)\n* package, package, structuring the source of: Invoking Requests.\n(line 28)\n* padding character, for fields (fc): Fields. (line 6)\n* page: Page Geometry. (line 19)\n* page break: Page Geometry. (line 52)\n* page break <1>: Page Control. (line 6)\n* page break <2>: The Implicit Page Trap.\n(line 6)\n* page break (introduction): Basics. (line 133)\n* page break, conditional (ne): Page Control. (line 31)\n* page break, final: End-of-input Traps. (line 34)\n* page break, prevented by vpt: Vertical Position Traps.\n(line 21)\n* page control: Page Control. (line 6)\n* page ejection: Page Geometry. (line 52)\n* page ejection <1>: Page Control. (line 6)\n* page ejection <2>: The Implicit Page Trap.\n(line 6)\n* page ejection status register (.pe): Page Location Traps. (line 184)\n* page ejection, of final page: End-of-input Traps. (line 34)\n* page ejection, prevented by vpt: Vertical Position Traps.\n(line 21)\n* page footers: Page Location Traps. (line 26)\n* page headers: Page Location Traps. (line 26)\n* page layout: Page Layout. (line 6)\n* page layout [ms]: ms Page Layout. (line 6)\n* page length register (.p): Page Layout. (line 20)\n* page length, configuring (pl): Page Layout. (line 12)\n* page location traps: Page Location Traps. (line 6)\n* page location traps, debugging: Page Location Traps. (line 62)\n* page location, vertical, marking (mk): Page Motions. (line 11)\n* page location, vertical, returning to marked (rt): Page Motions.\n(line 11)\n* page motions: Page Motions. (line 6)\n* page number character (%): Page Layout. (line 39)\n* page number character, changing (pc): Page Layout. (line 68)\n* page number register (%): Page Control. (line 24)\n* page number, configuring next (pn): Page Layout. (line 26)\n* page number, next, register (.pn): Page Layout. (line 31)\n* page offset: Page Geometry. (line 37)\n* page offset (po): Line Layout. (line 21)\n* page orientation, landscape: Paper Format. (line 6)\n* page, geometry of: Page Geometry. (line 6)\n* page, new (bp): Page Control. (line 14)\n* paper format: Paper Format. (line 6)\n* paper size: Paper Format. (line 6)\n* paragraphs: Paragraphs. (line 6)\n* parameter count register (.$): Parameters. (line 14)\n* parameters: Parameters. (line 6)\n* parameters, and compatibility mode: Gtroff Internals. (line 90)\n* parameters, macro (\\$): Parameters. (line 36)\n* parentheses: Numeric Expressions. (line 104)\n* partially collected line: Manipulating Filling and Adjustment.\n(line 26)\n* path, for font files: Font Directories. (line 14)\n* path, for tmac files: Macro Directories. (line 8)\n* pattern files, for hyphenation: Manipulating Hyphenation.\n(line 181)\n* patterns for hyphenation (hpf): Manipulating Hyphenation.\n(line 235)\n* pending output line: Manipulating Filling and Adjustment.\n(line 26)\n* pi request, and groff: I/O. (line 166)\n* pi request, and safer mode: Groff Options. (line 235)\n* pi request, disabled by default: Safer Mode. (line 6)\n* pica scaling unit (P): Measurements. (line 33)\n* PID of GNU troff register ($$): Built-in Registers. (line 69)\n* pile, glyph (\\b): Drawing Geometric Objects.\n(line 184)\n* pl request, using + and - with: Numeric Expressions. (line 121)\n* plain text approximation output register (.A): Groff Options.\n(line 49)\n* plain text approximation output register (.A) <1>: Built-in Registers.\n(line 25)\n* planting a trap: Traps. (line 12)\n* platform-specific directory: Macro Directories. (line 23)\n* pm request, incompatibilities with AT&T troff: Other Differences.\n(line 70)\n* pn request, using + and - with: Numeric Expressions. (line 121)\n* PNG image generation from PostScript: DESC File Format. (line 30)\n* po request, using + and - with: Numeric Expressions. (line 121)\n* point scaling unit (p): Measurements. (line 29)\n* point size registers (.s, .ps): Changing the Type Size.\n(line 25)\n* point size registers, last-requested (.psr, .sr): Using Fractional Type Sizes.\n(line 47)\n* point sizes, changing (ps, \\s): Changing the Type Size.\n(line 11)\n* point sizes, fractional: Using Fractional Type Sizes.\n(line 6)\n* point sizes, fractional <1>: Other Differences. (line 57)\n* polygon, filled, drawing (\\D'P ...'): Drawing Geometric Objects.\n(line 151)\n* polygon, outlined, drawing (\\D'p ...'): Drawing Geometric Objects.\n(line 145)\n* polygon, solid, drawing (\\D'P ...'): Drawing Geometric Objects.\n(line 151)\n* polygon, stroked, drawing (\\D'p ...'): Drawing Geometric Objects.\n(line 145)\n* position of lowest text line (.h): Diversions. (line 95)\n* position, absolute (sic) operator (|): Numeric Expressions. (line 129)\n* position, drawing: Page Geometry. (line 25)\n* position, horizontal input line, saving (\\k): Page Motions. (line 227)\n* position, horizontal, in input line, register (hp): Page Motions.\n(line 233)\n* position, horizontal, in output line, register (.k): Page Motions.\n(line 236)\n* position, mounting: Using Fonts. (line 21)\n* position, vertical, in diversion, register (.d): Diversions.\n(line 88)\n* positions, font: Font Positions. (line 6)\n* post-vertical line spacing: Changing the Vertical Spacing.\n(line 39)\n* post-vertical line spacing register (.pvs): Changing the Vertical Spacing.\n(line 51)\n* post-vertical line spacing, changing (pvs): Changing the Vertical Spacing.\n(line 51)\n* postprocessor access: Postprocessor Access.\n(line 6)\n* postprocessors: Output Device Intro. (line 6)\n* PostScript, bounding box: Miscellaneous. (line 162)\n* PostScript, PNG image generation: DESC File Format. (line 30)\n* prefix, for commands: Environment. (line 14)\n* preprocessors: Preprocessor Intro. (line 6)\n* previous font, selecting (\\f[], \\fP): Selecting Fonts. (line 41)\n* previous font, selecting (ft): Selecting Fonts. (line 15)\n* previous line length (.n): Environments. (line 141)\n* print current page register (.P): Groff Options. (line 198)\n* printing backslash (\\\\, \\e, \\E, \\[rs]): Other Differences. (line 106)\n* printing line numbers (nm): Miscellaneous. (line 11)\n* printing to stderr (tm, tm1, tmc): Debugging. (line 45)\n* printing, zero-width (\\z, \\Z): Page Motions. (line 245)\n* printing, zero-width (\\z, \\Z) <1>: Page Motions. (line 250)\n* process ID of GNU troff register ($$): Built-in Registers. (line 69)\n* processing next file (nx): I/O. (line 90)\n* productive input line: Manipulating Filling and Adjustment.\n(line 179)\n* properties of characters (cflags): Using Symbols. (line 252)\n* properties of glyphs (cflags): Using Symbols. (line 252)\n* properties of output lines: Manipulating Filling and Adjustment.\n(line 26)\n* ps request, and constant glyph space mode: Artificial Fonts.\n(line 125)\n* ps request, incompatibilities with AT&T troff: Other Differences.\n(line 57)\n* ps request, using + and - with: Numeric Expressions. (line 121)\n* ps request, with fractional type sizes: Using Fractional Type Sizes.\n(line 13)\n* pso request, and safer mode: Groff Options. (line 235)\n* pvs request, using + and - with: Numeric Expressions. (line 121)\n* quanta, motion: Motion Quanta. (line 6)\n* quantum, horizontal motion: DESC File Format. (line 26)\n* quantum, vertical motion: DESC File Format. (line 134)\n* radicalex glyph, and cflags: Using Symbols. (line 288)\n* ragged-left text: Manipulating Filling and Adjustment.\n(line 105)\n* ragged-right text: Manipulating Filling and Adjustment.\n(line 102)\n* rc request, and glyph definitions: Using Symbols. (line 354)\n* read-only register removal, incompatibility with AT&T troff: Other Differences.\n(line 41)\n* read-only register, changing format: Assigning Register Formats.\n(line 65)\n* reading from standard input (rd): I/O. (line 95)\n* recursive macros: while. (line 38)\n* refer, and macro names starting with [ or ]: Identifiers. (line 55)\n* reference, gtroff: GNU troff Reference. (line 6)\n* references [ms]: ms Insertions. (line 6)\n* register format, in expressions: Assigning Register Formats.\n(line 77)\n* register, assigning number format to (af): Assigning Register Formats.\n(line 6)\n* register, built-in, removing: Built-in Registers. (line 11)\n* register, creating alias for (aln): Setting Registers. (line 110)\n* register, format (\\g): Assigning Register Formats.\n(line 72)\n* register, read-only, removal, incompatibility with AT&T troff: Other Differences.\n(line 41)\n* register, removing (rr): Setting Registers. (line 99)\n* register, removing alias for (rr): Setting Registers. (line 116)\n* register, renaming (rnn): Setting Registers. (line 105)\n* registers: Registers. (line 6)\n* registers, built-in: Built-in Registers. (line 6)\n* registers, dumping (pnr): Debugging. (line 86)\n* registers, interpolating (\\n): Interpolating Registers.\n(line 6)\n* registers, number of, register (.R): Built-in Registers. (line 45)\n* registers, setting (nr, \\R): Setting Registers. (line 6)\n* removal of read-only registers, incompatibility with AT&T troff: Other Differences.\n(line 41)\n* removing a built-in register: Built-in Registers. (line 11)\n* removing a register (rr): Setting Registers. (line 99)\n* removing alias for register (rr): Setting Registers. (line 116)\n* removing alias, for diversion (rm): Strings. (line 233)\n* removing alias, for macro (rm): Strings. (line 233)\n* removing alias, for string (rm): Strings. (line 233)\n* removing diversion (rm): Strings. (line 193)\n* removing glyph definition (rchar, rfschar): Using Symbols. (line 411)\n* removing macro (rm): Strings. (line 193)\n* removing request (rm): Strings. (line 193)\n* removing string (rm): Strings. (line 193)\n* renaming a register (rnn): Setting Registers. (line 105)\n* renaming diversion (rn): Strings. (line 190)\n* renaming macro (rn): Strings. (line 190)\n* renaming request (rn): Strings. (line 190)\n* renaming string (rn): Strings. (line 190)\n* renditions, graphic: Using Fonts. (line 49)\n* request: Requests and Macros. (line 7)\n* request <1>: Formatter Instructions.\n(line 11)\n* request arguments: Invoking Requests. (line 14)\n* request arguments, and compatibility mode: Gtroff Internals.\n(line 90)\n* request arguments, and tabs: Invoking Requests. (line 14)\n* request, removing (rm): Strings. (line 193)\n* request, renaming (rn): Strings. (line 190)\n* request, undefined: Comments. (line 24)\n* requests for drawing: Drawing Geometric Objects.\n(line 6)\n* requests for input and output: I/O. (line 6)\n* requests, intercepting: Control Characters. (line 45)\n* requests, invoking: Invoking Requests. (line 6)\n* requests, modifying: Control Characters. (line 45)\n* resolution, device: Page Geometry. (line 13)\n* resolution, device <1>: DESC File Format. (line 87)\n* resolution, device, obtaining in the formatter: Measurements.\n(line 14)\n* resolution, horizontal: DESC File Format. (line 26)\n* resolution, horizontal, register (.H): Motion Quanta. (line 13)\n* resolution, vertical: DESC File Format. (line 134)\n* returning to marked vertical page location (rt): Page Motions.\n(line 11)\n* revision number register (.Y): Built-in Registers. (line 65)\n* right margin: Line Layout. (line 32)\n* right-aligning lines (introduction): Basics. (line 130)\n* right-justifying (rj): Manipulating Filling and Adjustment.\n(line 248)\n* right-justifying lines (introduction): Basics. (line 130)\n* rivers: Other Differences. (line 22)\n* rj request, causing implicit break: Manipulating Filling and Adjustment.\n(line 6)\n* rn glyph, and cflags: Using Symbols. (line 288)\n* roman glyph, correction after italic glyph (\\/): Italic Corrections.\n(line 10)\n* roman glyph, correction before italic glyph (\\,): Italic Corrections.\n(line 20)\n* Roman numerals: Assigning Register Formats.\n(line 26)\n* Roman numerals, extrema (maximum and minimum): Assigning Register Formats.\n(line 58)\n* rq glyph, at end of sentence: Sentences. (line 62)\n* rq glyph, at end of sentence <1>: Using Symbols. (line 298)\n* rt request, using + and - with: Numeric Expressions. (line 121)\n* ru glyph, and cflags: Using Symbols. (line 288)\n* running system commands: I/O. (line 170)\n* s scaling unit: Using Fractional Type Sizes.\n(line 13)\n* safer mode: Groff Options. (line 235)\n* safer mode <1>: Macro Directories. (line 18)\n* safer mode <2>: Built-in Registers. (line 53)\n* safer mode <3>: I/O. (line 41)\n* safer mode <4>: I/O. (line 153)\n* safer mode <5>: I/O. (line 175)\n* safer mode <6>: I/O. (line 214)\n* safer mode <7>: Safer Mode. (line 6)\n* saving horizontal input line position (\\k): Page Motions. (line 227)\n* scaling indicator: Measurements. (line 6)\n* scaling operator: Numeric Expressions. (line 48)\n* scaling unit c: Measurements. (line 26)\n* scaling unit f: Colors. (line 40)\n* scaling unit i: Measurements. (line 23)\n* scaling unit m: Measurements. (line 51)\n* scaling unit M: Measurements. (line 61)\n* scaling unit n: Measurements. (line 55)\n* scaling unit p: Measurements. (line 29)\n* scaling unit P: Measurements. (line 33)\n* scaling unit s: Using Fractional Type Sizes.\n(line 13)\n* scaling unit u: Measurements. (line 19)\n* scaling unit v: Measurements. (line 58)\n* scaling unit z: Using Fractional Type Sizes.\n(line 13)\n* searching fonts: Font Directories. (line 6)\n* searching macros: Macro Directories. (line 6)\n* seconds, current time (seconds): Built-in Registers. (line 78)\n* selecting the previous font (ft): Selecting Fonts. (line 15)\n* sentence space: Sentences. (line 18)\n* sentence space size register (.sss): Manipulating Filling and Adjustment.\n(line 269)\n* sentences: Sentences. (line 6)\n* sequence, escape: Formatter Instructions.\n(line 17)\n* setting diversion trap (dt): Diversion Traps. (line 11)\n* setting end-of-input trap (em): End-of-input Traps. (line 7)\n* setting input line number (lf): Debugging. (line 31)\n* setting input line trap (it, itc): Input Line Traps. (line 8)\n* setting registers (nr, \\R): Setting Registers. (line 6)\n* setting the page length (pl): Page Layout. (line 12)\n* setting up an abstract font style (sty): Font Families. (line 63)\n* shc request, and translations: Character Translations.\n(line 39)\n* site-local directory: Macro Directories. (line 23)\n* site-local directory <1>: Font Directories. (line 29)\n* size of sentence space register (.sss): Manipulating Filling and Adjustment.\n(line 269)\n* size of word space register (.ss): Manipulating Filling and Adjustment.\n(line 269)\n* size, optical, of a font: Selecting Fonts. (line 84)\n* size, paper: Paper Format. (line 6)\n* size, size: Manipulating Type Size and Vertical Spacing.\n(line 6)\n* sizes, fractional: Other Differences. (line 57)\n* sizes, fractional type: Using Fractional Type Sizes.\n(line 6)\n* skew, of last glyph (.csk): Environments. (line 126)\n* slant, font, changing (\\S): Artificial Fonts. (line 45)\n* soft hyphen character, setting (shc): Manipulating Hyphenation.\n(line 97)\n* soft hyphen glyph (hy): Manipulating Hyphenation.\n(line 97)\n* solid circle, drawing (\\D'C ...'): Drawing Geometric Objects.\n(line 110)\n* solid ellipse, drawing (\\D'E ...'): Drawing Geometric Objects.\n(line 117)\n* solid polygon, drawing (\\D'P ...'): Drawing Geometric Objects.\n(line 151)\n* SOURCEDATEEPOCH, environment variable: Environment. (line 61)\n* sp request, and no-space mode: Manipulating Spacing.\n(line 118)\n* sp request, causing implicit break: Manipulating Filling and Adjustment.\n(line 6)\n* space between sentences: Sentences. (line 18)\n* space between sentences register (.sss): Manipulating Filling and Adjustment.\n(line 269)\n* space between words register (.ss): Manipulating Filling and Adjustment.\n(line 269)\n* space character, as delimiter: Delimiters. (line 40)\n* space characters, in expressions: Numeric Expressions. (line 196)\n* space, between sentences: Manipulating Filling and Adjustment.\n(line 275)\n* space, between words: Manipulating Filling and Adjustment.\n(line 273)\n* space, discardable, horizontal: Manipulating Filling and Adjustment.\n(line 296)\n* space, hair (\\^): Page Motions. (line 151)\n* space, horizontal (\\h): Page Motions. (line 125)\n* space, horizontal, unformatting: Punning Names. (line 95)\n* space, thin (\\|): Page Motions. (line 146)\n* space, unbreakable (\\~): Manipulating Filling and Adjustment.\n(line 53)\n* space, unbreakable and unadjustable (\\): Page Motions. (line 141)\n* space, vertical, unit (v): Measurements. (line 58)\n* space, width of a digit (numeral) (\\0): Page Motions. (line 157)\n* spaces with ds: Strings. (line 70)\n* spaces, in a macro argument: Calling Macros. (line 11)\n* spaces, leading and trailing: Breaking. (line 38)\n* spacing (introduction): Basics. (line 98)\n* spacing, manipulating: Manipulating Spacing.\n(line 6)\n* spacing, vertical: Page Geometry. (line 46)\n* spacing, vertical <1>: Manipulating Type Size and Vertical Spacing.\n(line 6)\n* spacing, vertical (introduction): Basics. (line 84)\n* special characters: Sentences. (line 62)\n* special characters <1>: Character Translations.\n(line 25)\n* special characters [ms]: ms Legacy Features. (line 6)\n* special characters, list of (groffchar(7) man page): Using Symbols.\n(line 81)\n* special font: Using Fonts. (line 6)\n* special fonts: Using Symbols. (line 18)\n* special fonts <1>: Special Fonts. (line 6)\n* special fonts <2>: Font Description File Format.\n(line 52)\n* special fonts, emboldening: Artificial Fonts. (line 114)\n* special request, and font translations: Selecting Fonts. (line 69)\n* special request, and glyph search order: Using Symbols. (line 18)\n* spline, drawing (\\D'~ ...'): Drawing Geometric Objects.\n(line 97)\n* springing a trap: Traps. (line 13)\n* sqrtex glyph, and cflags: Using Symbols. (line 288)\n* ss request, incompatibilities with AT&T troff: Other Differences.\n(line 74)\n* stack: Environments. (line 11)\n* stacking glyphs (\\b): Drawing Geometric Objects.\n(line 184)\n* standard input, reading from (rd): I/O. (line 95)\n* stderr, printing to (tm, tm1, tmc): Debugging. (line 45)\n* stops, tab: Tabs and Leaders. (line 6)\n* string arguments: Strings. (line 28)\n* string comparison: Operators in Conditionals.\n(line 87)\n* string expansion (\\*): Strings. (line 28)\n* string interpolation (\\*): Strings. (line 28)\n* string, appending (as): Strings. (line 115)\n* string, creating alias for (als): Strings. (line 198)\n* string, length of (length): Strings. (line 135)\n* string, removing (rm): Strings. (line 193)\n* string, removing alias for (rm): Strings. (line 233)\n* string, renaming (rn): Strings. (line 190)\n* strings: Strings. (line 6)\n* strings [ms]: ms Legacy Features. (line 6)\n* strings, multi-line: Strings. (line 79)\n* strings, shared name space with macros and diversions: Identifiers.\n(line 100)\n* stripping final newline in diversions: Punning Names. (line 95)\n* stroke color: Colors. (line 6)\n* stroke color name register (.m): Colors. (line 72)\n* stroked circle, drawing (\\D'c ...'): Drawing Geometric Objects.\n(line 106)\n* stroked ellipse, drawing (\\D'e ...'): Drawing Geometric Objects.\n(line 113)\n* stroked polygon, drawing (\\D'p ...'): Drawing Geometric Objects.\n(line 145)\n* structuring source code of documents or macro packages: Invoking Requests.\n(line 28)\n* sty request, and changing fonts: Selecting Fonts. (line 15)\n* sty request, and font translations: Selecting Fonts. (line 69)\n* style, font: Using Fonts. (line 6)\n* style, font, abstract: Using Fonts. (line 28)\n* style, font, abstract, setting up (sty): Font Families. (line 63)\n* styles, font: Font Families. (line 6)\n* substring (substring): Strings. (line 153)\n* subtraction: Numeric Expressions. (line 17)\n* suppressing output (\\O): Suppressing Output. (line 7)\n* suppression nesting level register: Suppressing Output. (line 60)\n* sv request, and no-space mode: Page Control. (line 69)\n* switching environments (ev): Environments. (line 47)\n* sy request, and safer mode: Groff Options. (line 235)\n* sy request, disabled by default: Safer Mode. (line 6)\n* symbol: Using Symbols. (line 18)\n* symbol table, dumping (pm): Debugging. (line 82)\n* symbol, defining (char): Using Symbols. (line 354)\n* symbols, using: Using Symbols. (line 6)\n* system commands, running: I/O. (line 170)\n* system() return value register (systat): I/O. (line 203)\n* tab character: Tabs and Leaders. (line 6)\n* tab character encoding: Tabs and Fields. (line 6)\n* tab character, and translations: Character Translations.\n(line 35)\n* tab character, as delimiter: Delimiters. (line 40)\n* tab character, non-interpreted (\\t): Tabs and Fields. (line 10)\n* tab repetition character (tc): Tabs and Fields. (line 127)\n* tab stop settings register (.tabs): Tabs and Fields. (line 118)\n* tab stops: Tabs and Leaders. (line 6)\n* tab stops, default: Tabs and Fields. (line 18)\n* tab, line-tabs mode: Tabs and Fields. (line 140)\n* table of contents: Table of Contents. (line 6)\n* table of contents <1>: Leaders. (line 32)\n* table of contents, creating [ms]: ms TOC. (line 6)\n* table, multi-page, example [ms]: ms Insertions. (line 48)\n* tables [ms]: ms Insertions. (line 6)\n* tabs, and fields: Tabs and Fields. (line 6)\n* tabs, and macro arguments: Invoking Requests. (line 14)\n* tabs, and request arguments: Invoking Requests. (line 14)\n* tabs, before comments: Comments. (line 19)\n* tagged paragraphs: Paragraphs. (line 14)\n* tags, paragraph: Paragraphs. (line 14)\n* terminal, conditional output for: Operators in Conditionals.\n(line 32)\n* text baseline: Page Geometry. (line 28)\n* text baseline <1>: Manipulating Type Size and Vertical Spacing.\n(line 6)\n* text font: Using Fonts. (line 6)\n* text line: Requests and Macros. (line 20)\n* text line, position of lowest (.h): Diversions. (line 95)\n* text, GNU troff processing: Text. (line 6)\n* text, justifying: Manipulating Filling and Adjustment.\n(line 6)\n* text, justifying (rj): Manipulating Filling and Adjustment.\n(line 248)\n* thickness of lines (\\D't ...'): Drawing Geometric Objects.\n(line 174)\n* thin space (\\|): Page Motions. (line 146)\n* three-part title (tl): Page Layout. (line 39)\n* ti request, causing implicit break: Manipulating Filling and Adjustment.\n(line 6)\n* ti request, using + and - with: Numeric Expressions. (line 121)\n* time, current, hours (hours): Built-in Registers. (line 84)\n* time, current, minutes (minutes): Built-in Registers. (line 81)\n* time, current, seconds (seconds): Built-in Registers. (line 78)\n* time, formatting: I/O. (line 193)\n* title length, configuring (lt): Page Layout. (line 56)\n* title line length register (.lt): Page Layout. (line 65)\n* title line, formatting (tl): Page Layout. (line 39)\n* titles: Page Layout. (line 34)\n* tkf request, and font styles: Font Families. (line 63)\n* tkf request, and font translations: Selecting Fonts. (line 69)\n* tkf request, with fractional type sizes: Using Fractional Type Sizes.\n(line 13)\n* tl request, and mc: Miscellaneous. (line 114)\n* tmac, directory: Macro Directories. (line 8)\n* tmac, path: Macro Directories. (line 8)\n* TMPDIR, environment variable: Environment. (line 48)\n* token, input: Gtroff Internals. (line 6)\n* top margin: Page Location Traps. (line 26)\n* top-level diversion: Diversions. (line 18)\n* top-level diversion, and \\!: Diversions. (line 186)\n* top-level diversion, and \\?: Diversions. (line 191)\n* top-level diversion, and bp: Page Control. (line 19)\n* tr request, and glyph definitions: Using Symbols. (line 354)\n* tr request, and soft hyphen character: Manipulating Hyphenation.\n(line 97)\n* tr request, incompatibilities with AT&T troff: Other Differences.\n(line 79)\n* track kerning: Ligatures and Kerning.\n(line 53)\n* track kerning, activating (tkf): Ligatures and Kerning.\n(line 60)\n* trailing double quotes in strings: Strings. (line 70)\n* trailing spaces in string definitions and appendments: Strings.\n(line 49)\n* trailing spaces on text lines: Breaking. (line 38)\n* translations of characters: Character Translations.\n(line 6)\n* transparent characters: Using Symbols. (line 298)\n* transparent dummy character (\\)): Dummy Characters. (line 63)\n* transparent output (\\!, \\?): Diversions. (line 154)\n* transparent output (cf, trf): I/O. (line 58)\n* transparent output, incompatibilities with AT&T troff: Other Differences.\n(line 106)\n* trap: Deferring Output. (line 6)\n* trap, changing location (ch): Page Location Traps. (line 114)\n* trap, distance to next vertical position, register (.t): Page Location Traps.\n(line 106)\n* trap, diversion, setting (dt): Diversion Traps. (line 11)\n* trap, end-of-input, setting (em): End-of-input Traps. (line 7)\n* trap, implicit: The Implicit Page Trap.\n(line 6)\n* trap, input line, clearing (it, itc): Input Line Traps. (line 8)\n* trap, input line, setting (it, itc): Input Line Traps. (line 8)\n* trap, planting: Traps. (line 12)\n* trap, springing: Traps. (line 13)\n* traps: Traps. (line 6)\n* traps, and diversions: Page Location Traps. (line 204)\n* traps, blank line: Blank Line Traps. (line 6)\n* traps, diversion: Diversion Traps. (line 6)\n* traps, end-of-input: End-of-input Traps. (line 6)\n* traps, input line: Input Line Traps. (line 6)\n* traps, input line, and interrupted lines (itc): Input Line Traps.\n(line 32)\n* traps, leading space: Leading Space Traps. (line 6)\n* traps, page location: Page Location Traps. (line 6)\n* traps, page location, dumping (ptr): Debugging. (line 90)\n* traps, page location, listing (ptr): Debugging. (line 90)\n* traps, sprung by bp request (.pe): Page Location Traps. (line 184)\n* traps, vertical position: Vertical Position Traps.\n(line 6)\n* trf request, and copy mode: I/O. (line 58)\n* trf request, and invalid characters: I/O. (line 70)\n* trf request, causing implicit break: Manipulating Filling and Adjustment.\n(line 6)\n* trin request, and asciify: Diversions. (line 208)\n* troff mode: troff and nroff Modes.\n(line 6)\n* troff output: gtroff Output. (line 16)\n* truncated vertical space register (.trunc): Page Location Traps.\n(line 173)\n* truncating division: Numeric Expressions. (line 17)\n* TTY, conditional output for: Operators in Conditionals.\n(line 32)\n* tutorial for macro users: Tutorial for Macro Users.\n(line 6)\n* type size: Manipulating Type Size and Vertical Spacing.\n(line 6)\n* type size registers (.s, .ps): Changing the Type Size.\n(line 25)\n* type size registers, last-requested (.psr, .sr): Using Fractional Type Sizes.\n(line 47)\n* type sizes, changing (ps, \\s): Changing the Type Size.\n(line 11)\n* type sizes, fractional: Using Fractional Type Sizes.\n(line 6)\n* type sizes, fractional <1>: Other Differences. (line 57)\n* typeface: Using Fonts. (line 6)\n* TZ, environment variable: Environment. (line 69)\n* u scaling unit: Measurements. (line 19)\n* uf request, and font styles: Font Families. (line 63)\n* ul glyph, and cflags: Using Symbols. (line 288)\n* ul request, and font translations: Selecting Fonts. (line 69)\n* Ultrix-specific man macros: Optional man extensions.\n(line 30)\n* unadjustable and unbreakable space (\\): Page Motions. (line 141)\n* unary arithmetic operators: Numeric Expressions. (line 23)\n* unbreakable and unadjustable space (\\): Page Motions. (line 141)\n* unbreakable space (\\~): Manipulating Filling and Adjustment.\n(line 53)\n* undefined identifiers: Identifiers. (line 88)\n* undefined request: Comments. (line 24)\n* underline font (uf): Artificial Fonts. (line 90)\n* underlining (ul): Artificial Fonts. (line 64)\n* underlining, continuous (cu): Artificial Fonts. (line 86)\n* unformatting diversions (asciify): Diversions. (line 208)\n* unformatting horizontal space: Punning Names. (line 95)\n* Unicode: Identifiers. (line 13)\n* Unicode <1>: Using Symbols. (line 216)\n* unit, scaling, c: Measurements. (line 26)\n* unit, scaling, f: Colors. (line 40)\n* unit, scaling, i: Measurements. (line 23)\n* unit, scaling, m: Measurements. (line 51)\n* unit, scaling, M: Measurements. (line 61)\n* unit, scaling, n: Measurements. (line 55)\n* unit, scaling, p: Measurements. (line 29)\n* unit, scaling, P: Measurements. (line 33)\n* unit, scaling, s: Using Fractional Type Sizes.\n(line 13)\n* unit, scaling, u: Measurements. (line 19)\n* unit, scaling, v: Measurements. (line 58)\n* unit, scaling, z: Using Fractional Type Sizes.\n(line 13)\n* units of measurement: Measurements. (line 6)\n* units, basic: Page Geometry. (line 13)\n* units, basic, conversion to: Measurements. (line 13)\n* units, default: Default Units. (line 6)\n* units, machine: Page Geometry. (line 13)\n* unnamed glyphs: Using Symbols. (line 226)\n* unnamed glyphs, accessing with \\N: Font Description File Format.\n(line 73)\n* unsafe mode: Groff Options. (line 311)\n* unsafe mode <1>: Macro Directories. (line 18)\n* unsafe mode <2>: Built-in Registers. (line 53)\n* unsafe mode <3>: I/O. (line 41)\n* unsafe mode <4>: I/O. (line 153)\n* unsafe mode <5>: I/O. (line 175)\n* unsafe mode <6>: I/O. (line 214)\n* unstyled font: Using Fonts. (line 6)\n* up-casing a string (stringup): Strings. (line 171)\n* uppercasing a string (stringup): Strings. (line 171)\n* upright glyph, correction after oblique glyph (\\/): Italic Corrections.\n(line 10)\n* upright glyph, correction before oblique glyph (\\,): Italic Corrections.\n(line 20)\n* URLs, breaking (\\:): Manipulating Hyphenation.\n(line 73)\n* user's macro tutorial: Tutorial for Macro Users.\n(line 6)\n* user's tutorial for macros: Tutorial for Macro Users.\n(line 6)\n* using escape sequences: Using Escape Sequences.\n(line 6)\n* using symbols: Using Symbols. (line 6)\n* UTF-8 output encoding: Groff Options. (line 279)\n* v scaling unit: Measurements. (line 58)\n* valid numeric expression: Numeric Expressions. (line 180)\n* value, incrementing without changing the register: Auto-increment.\n(line 45)\n* variables in environment: Environment. (line 6)\n* vee: Page Geometry. (line 46)\n* vee scaling unit (v): Measurements. (line 58)\n* version number, major, register (.x): Built-in Registers. (line 57)\n* version number, minor, register (.y): Built-in Registers. (line 61)\n* vertical drawing position (nl): Page Control. (line 76)\n* vertical line drawing (\\L): Drawing Geometric Objects.\n(line 44)\n* vertical line spacing register (.v): Changing the Vertical Spacing.\n(line 10)\n* vertical line spacing, changing (vs): Changing the Vertical Spacing.\n(line 10)\n* vertical line spacing, effective value: Changing the Vertical Spacing.\n(line 25)\n* vertical motion (\\v): Page Motions. (line 81)\n* vertical motion quantum: DESC File Format. (line 134)\n* vertical page location, marking (mk): Page Motions. (line 11)\n* vertical page location, returning to marked (rt): Page Motions.\n(line 11)\n* vertical position in diversion register (.d): Diversions. (line 88)\n* vertical position trap enable register (.vpt): Vertical Position Traps.\n(line 14)\n* vertical position traps: Vertical Position Traps.\n(line 6)\n* vertical position traps, enabling (vpt): Vertical Position Traps.\n(line 14)\n* vertical position, drawing (nl): Page Control. (line 76)\n* vertical resolution: DESC File Format. (line 134)\n* vertical space unit (v): Measurements. (line 58)\n* vertical spacing: Page Geometry. (line 46)\n* vertical spacing <1>: Manipulating Type Size and Vertical Spacing.\n(line 6)\n* vertical spacing (introduction): Basics. (line 84)\n* warning categories: Warnings. (line 15)\n* warning level (warn): Debugging. (line 155)\n* warnings: Debugging. (line 150)\n* warnings <1>: Warnings. (line 6)\n* what is groff?: What Is groff?. (line 6)\n* while: while. (line 6)\n* while request, and font translations: Selecting Fonts. (line 69)\n* while request, and the ! operator: Numeric Expressions. (line 23)\n* while request, confusing with br: while. (line 72)\n* while request, operators to use with: Operators in Conditionals.\n(line 6)\n* widow: Page Control. (line 39)\n* widow <1>: Page Control. (line 58)\n* width escape (\\w): Page Motions. (line 170)\n* width, of last glyph (.w): Environments. (line 126)\n* word space size register (.ss): Manipulating Filling and Adjustment.\n(line 269)\n* word, definition of: Filling. (line 11)\n* write request, and copy mode: I/O. (line 220)\n* writec request, and copy mode: I/O. (line 220)\n* writem request, and copy mode: I/O. (line 234)\n* writing macros: Writing Macros. (line 6)\n* writing to file (write, writec): I/O. (line 220)\n* year, current, register (year, yr): Built-in Registers. (line 96)\n* z scaling unit: Using Fractional Type Sizes.\n(line 13)\n* zero-width printing (\\z, \\Z): Page Motions. (line 245)\n* zero-width printing (\\z, \\Z) <1>: Page Motions. (line 250)\n* zoom factor of a font (fzoom): Selecting Fonts. (line 84)\n", "subsections": [] } }, "flags": [], "examples": [], "see_also": [] }