diff options
Diffstat (limited to 'doc/groff.info-1')
| -rw-r--r-- | doc/groff.info-1 | 7824 |
1 files changed, 7824 insertions, 0 deletions
diff --git a/doc/groff.info-1 b/doc/groff.info-1 new file mode 100644 index 0000000..e2db4ec --- /dev/null +++ b/doc/groff.info-1 @@ -0,0 +1,7824 @@ +This is groff.info, produced by makeinfo version 7.0.3 from groff.texi. + +This manual documents GNU 'troff' version 1.23.0. + + Copyright © 1994-2023 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.3 or any later version published by the Free Software + Foundation; with no Invariant Sections, no Front-Cover Texts, and + no Back-Cover Texts. A copy of the license is included in the + section entitled "GNU Free Documentation License". +INFO-DIR-SECTION Typesetting +START-INFO-DIR-ENTRY +* Groff: (groff). The GNU roff document formatting system. +END-INFO-DIR-ENTRY + + +File: groff.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) + +GNU 'troff' +*********** + +* Menu: + +* Introduction:: +* Invoking groff:: +* Tutorial for Macro Users:: +* Major Macro Packages:: +* GNU troff Reference:: +* File Formats:: +* Copying This Manual:: +* Request Index:: +* Escape Sequence Index:: +* Operator Index:: +* Register Index:: +* Macro Index:: +* String Index:: +* File Keyword Index:: +* Program and File Index:: +* Concept Index:: + +This manual documents GNU 'troff' version 1.23.0. + + Copyright © 1994-2023 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.3 or any later version published by the Free Software + Foundation; with no Invariant Sections, no Front-Cover Texts, and + no Back-Cover Texts. A copy of the license is included in the + section entitled "GNU Free Documentation License". + + +File: groff.info, Node: Introduction, Next: Invoking groff, Prev: Top, Up: Top + +1 Introduction +************** + +GNU 'roff' (or 'groff') is a programming system for typesetting +documents. It is highly flexible and has been used extensively for over +thirty years. + +* Menu: + +* Background:: +* What Is groff?:: +* groff Capabilities:: +* Macro Package Intro:: +* Preprocessor Intro:: +* Output Device Intro:: +* Conventions Used in This Manual:: +* Installation:: +* Credits:: + + +File: groff.info, Node: Background, Next: What Is groff?, Prev: Introduction, Up: Introduction + +1.1 Background +============== + +M. Douglas McIlroy, formerly of AT&T Bell Laboratories and present at +the creation of the Unix operating system, offers an authoritative +historical summary. + + The prime reason for Unix was the desire of Ken [Thompson], Dennis + [Ritchie], and Joe Ossanna to have a pleasant environment for + software development. The fig leaf that got the nod from ... + management was that an early use would be to develop a + "stand-alone" word-processing system for use in typing pools and + secretarial offices. Perhaps they had in mind "dedicated", as + distinct from "stand-alone"; that's what eventuated in various + cases, most notably in the legal/patent department and in the AT&T + CEO's office. + + Both those systems were targets of opportunity, not foreseen from + the start. When Unix was up and running on the PDP-11, Joe got + wind of the legal department having installed a commercial word + processor. He went to pitch Unix as an alternative and clinched a + trial by promising to make 'roff' able to number lines by tomorrow + in order to fulfill a patent-office requirement that the commercial + system did not support. + + Modems were installed so legal-department secretaries could try the + Research machine. They liked it and Joe's superb customer service. + Soon the legal department got a system of their own. Joe went on + to create 'nroff' and 'troff'. Document preparation became a + widespread use of Unix, but no stand-alone word-processing system + was ever undertaken. + + A history relating 'groff' to its predecessors 'roff', 'nroff', and +'troff' is available in the 'roff(7)' man page. + + +File: groff.info, Node: What Is groff?, Next: groff Capabilities, Prev: Introduction, Up: Introduction + +1.2 What Is 'groff'? +==================== + +'groff' (GNU 'roff') is a typesetting system that reads plain text input +files that include formatting commands to produce output in PostScript, +PDF, HTML, DVI, or other formats, or for display to a terminal. +Formatting commands can be low-level typesetting primitives, macros from +a supplied package, or user-defined macros. All three approaches can be +combined. + + A reimplementation and extension of the typesetter from AT&T Unix, +'groff' is present on most POSIX systems owing to its long association +with Unix manuals (including man pages). It and its predecessor are +notable for their production of several best-selling software +engineering texts. 'groff' is capable of producing typographically +sophisticated documents while consuming minimal system resources. + + +File: groff.info, Node: groff Capabilities, Next: Macro Package Intro, Prev: What Is groff?, Up: Introduction + +1.3 'groff' Capabilities +======================== + +GNU 'troff' is a typesetting document formatter; it provides a wide +range of low-level text and page operations within the framework of a +programming language. These operations compose to generate footnotes, +tables of contents, mathematical equations, diagrams, multi-column text, +and other elements of typeset works. Here is a survey of formatter +features; all are under precise user control. + + * text filling, breaking, alignment to the left or right margin; + centering + + * adjustment of inter-word space size to justify text, and of + inter-sentence space size to suit local style conventions + + * automatic and manual determination of hyphenation break points + + * pagination + + * selection of any font available to the output device + + * adjustment of type size and vertical spacing (or "leading") + + * configuration of line length and indentation amounts; columnation + + * drawing of geometric primitives (lines, arcs, polygons, circles, + ...) + + * setup of stroke and fill colors (where supported by the output + device) + + * embedding of hyperlinks, images, document metadata, and other + inclusions (where supported by the output device) + + +File: groff.info, Node: Macro Package Intro, Next: Preprocessor Intro, Prev: groff Capabilities, Up: Introduction + +1.4 Macro Packages +================== + +Elemental typesetting functions can be be challenging to use directly +with complex documents. A "macro" facility specifies how certain +routine operations, such as starting paragraphs, or printing headers and +footers, should be performed in terms of those low-level instructions. +Macros can be specific to one document or collected together into a +"macro package" for use by many. Several macro packages available; the +most widely used are provided with 'groff'. They are 'man', 'mdoc', +'me', 'mm', 'mom', and 'ms'. + + +File: groff.info, Node: Preprocessor Intro, Next: Output Device Intro, Prev: Macro Package Intro, Up: Introduction + +1.5 Preprocessors +================= + +An alternative approach to complexity management, particularly when +constructing tables, setting mathematics, or drawing diagrams, lies in +preprocessing. A "preprocessor" employs a domian-specific language to +ease the generation of tables, equations, and so forth in terms that are +convenient for human entry. Each preprocessor reads a document and +translates the parts of it that apply to it into GNU 'troff' input. +Command-line options to 'groff' tell it which preprocessors to use. + + 'groff' provides preprocessors for laying out tables ('gtbl'), +typesetting equations ('geqn'), drawing diagrams ('gpic' and 'ggrn'), +inserting bibliographic references ('grefer'), and drawing chemical +structures ('gchem'). An associated program that is useful when dealing +with preprocessors is 'gsoelim'.(1) (*note Preprocessor +Intro-Footnote-1::) + + 'groff' also supports 'grap', a preprocessor for drawing graphs. A +free implementation of it can be obtained separately. + + Unique to 'groff' is the 'preconv' preprocessor that enables 'groff' +to handle documents in a variety of input encodings. + + Other preprocessors exist, but no free implementations are known. An +example is 'ideal', which draws diagrams using a mathematical constraint +language. + + +File: groff.info, Node: Preprocessor Intro-Footnotes, Up: Preprocessor Intro + + (1) The 'g' prefix is not used on all systems; see *note Invoking +groff::. + + +File: groff.info, Node: Output Device Intro, Next: Installation, Prev: Preprocessor Intro, Up: Introduction + +1.6 Output Devices +================== + +GNU 'troff''s output is in a device-independent page description +language, which is then read by an "output driver" that translates this +language into a file format or byte stream that a piece of (possibly +emulated) hardware understands. 'groff' features output drivers for +PostScript devices, terminal emulators (and other simple typewriter-like +machines), X11 (for previewing), TeX DVI, HP LaserJet 4/PCL5 and Canon +LBP printers (which use CaPSL), HTML, XHTML, and PDF. + + +File: groff.info, Node: Installation, Next: Conventions Used in This Manual, Prev: Output Device Intro, Up: Introduction + +1.7 Installation +================ + +Locate installation instructions in the files 'INSTALL', +'INSTALL.extra', and 'INSTALL.REPO' in the 'groff' source distribution. +Being a GNU project, 'groff' supports the familiar './configure && make' +command sequence. + + +File: groff.info, Node: Conventions Used in This Manual, Next: Credits, Prev: Installation, Up: Introduction + +1.8 Conventions Used in This Manual +=================================== + +We apply the term "groff" to the language documented here, the GNU +implementation of the overall system, the project that develops that +system, and the command of that name. In the first sense, 'groff' is an +extended dialect of the 'roff' language, for which many similar +implementations exist. + + The 'roff' language features several major categories for which many +items are predefined. Presentations of these items feature the form in +which the item is most commonly used on the left, and, aligned to the +right margin, the name of the category in brackets. + + -- Register: \n[example] + The register 'example' is one that that 'groff' _doesn't_ + predefine. You can create it yourself, though; see *note Setting + Registers::. + + To make this document useful as a reference and not merely amiable +bedtime reading, we tend to present these syntax items in exhaustive +detail when they arise. References to topics discussed later in the +text are frequent; skip material you don't understand yet. + + We use Texinfo's "result" (=>) and error-> notations to present +output written to the standard output and standard error streams, +respectively. Diagnostic messages from the GNU 'troff' formatter and +other programs are examples of the latter, but the formatter can also be +directed to write user-specified messages to the standard error stream. +The notation then serves to identify the output stream and does not +necessarily mean that an error has occurred.(1) (*note Conventions Used +in This Manual-Footnote-1::) + + $ echo "Twelve o'clock and" | groff -Tascii | sed '/^$/d' + => Twelve o'clock and + $ echo '.tm all is well.' | groff > /dev/null + error-> all is well. + + Sometimes we use => somewhat abstractly to represent formatted text +that you will need to use a PostScript or PDF viewer program (or a +printer) to observe. While arguably an abuse of notation, we think this +preferable to requiring the reader to understand the syntax of these +page description languages. + + We also present diagnostic messages in an abbreviated form, often +omitting the name of the program issuing them, the input file name, and +line number or other positional information when such data do not serve +to illuminate the topic under discussion. + + Most examples are of 'roff' language input that would be placed in a +text file. Occasionally, we start an example with a '$' character to +indicate a shell prompt, as seen above. + + You are encouraged to try the examples yourself, and to alter them to +better learn 'groff''s behavior. Our examples frequently need to direct +the formatter to set a line length (with '.ll') that will fit within the +page margins of this manual. We mention this so that you know why it is +there before we discuss the 'll' request formally.(2) (*note +Conventions Used in This Manual-Footnote-2::) + + +File: groff.info, Node: Conventions Used in This Manual-Footnotes, Up: Conventions Used in This Manual + + (1) Unix and related operating systems distinguish standard output +and standard error streams _because_ of 'troff': +<https://minnie.tuhs.org/pipermail/tuhs/2013-December/006113.html>. + + (2) *Note Line Layout::. + + +File: groff.info, Node: Credits, Prev: Conventions Used in This Manual, Up: Introduction + +1.9 Credits +=========== + +We adapted portions of this manual from existing documents. James +Clark's man pages were an essential resource; we have updated them in +parallel with the development of this manual. We based the tutorial for +macro users on Eric Allman's introduction to his 'me' macro package +(which we also provide, little altered from 4.4BSD). Larry Kollar +contributed much of the material on the 'ms' macro package. + + +File: groff.info, Node: Invoking groff, Next: Tutorial for Macro Users, Prev: Introduction, Up: Top + +2 Invoking 'groff' +****************** + +This chapter focuses on how to invoke the 'groff' front end. This front +end takes care of the details of constructing the pipeline among the +preprocessors, 'gtroff' and the postprocessor. + + It has become a tradition that GNU programs get the prefix 'g' to +distinguish them from their original counterparts provided by the host +(*note Environment::). Thus, for example, 'geqn' is GNU 'eqn'. On +operating systems like GNU/Linux or the Hurd, which don't contain +proprietary versions of 'troff', and on MS-DOS/MS-Windows, where 'troff' +and associated programs are not available at all, this prefix is omitted +since GNU 'troff' is the only incarnation of 'troff' used. Exception: +'groff' is never replaced by 'roff'. + + In this document, we consequently say 'gtroff' when talking about the +GNU 'troff' program. All other implementations of 'troff' are called +AT&T 'troff', which is the common origin of almost all 'troff' +implementations(1) (*note Invoking groff-Footnote-1::) (with more or +less compatible changes). Similarly, we say 'gpic', 'geqn', and so on. + +* Menu: + +* Groff Options:: +* Environment:: +* Macro Directories:: +* Font Directories:: +* Paper Format:: +* Invocation Examples:: + + +File: groff.info, Node: Invoking groff-Footnotes, Up: Invoking groff + + (1) Besides 'groff', 'neatroff' is an exception. + + +File: groff.info, Node: Groff Options, Next: Environment, Prev: Invoking groff, Up: Invoking groff + +2.1 Options +=========== + +'groff' normally runs the 'gtroff' program and a postprocessor +appropriate for the selected device. The default device is 'ps' (but it +can be changed when 'groff' is configured and built). It can optionally +preprocess with any of 'gpic', 'geqn', 'gtbl', 'ggrn', 'grap', 'gchem', +'grefer', 'gsoelim', or 'preconv'. + + This section documents only options to the 'groff' front end. Many +of the arguments to 'groff' are passed on to 'gtroff'; therefore, those +are also included. Arguments to preprocessors and output drivers can be +found in the man pages 'gpic(1)', 'geqn(1)', 'gtbl(1)', 'ggrn(1)', +'grefer(1)', 'gchem(1)', 'gsoelim(1)', 'preconv(1)', 'grotty(1)', +'grops(1)', 'gropdf(1)', 'grohtml(1)', 'grodvi(1)', 'grolj4(1)', +'grolbp(1)', and 'gxditview(1)'. + + The command-line format for 'groff' is: + + groff [ -abceghijklpstvzCEGNRSUVXZ ] [ -dCS ] [ -DARG ] + [ -fFAM ] [ -FDIR ] [ -IDIR ] [ -KARG ] + [ -LARG ] [ -mNAME ] [ -MDIR ] [ -nNUM ] + [ -oLIST ] [ -PARG ] [ -rCN ] [ -TDEV ] + [ -wNAME ] [ -WNAME ] [ FILES... ] + + The command-line format for 'gtroff' is as follows. + + gtroff [ -abcivzCERU ] [ -dCS ] [ -fFAM ] [ -FDIR ] + [ -mNAME ] [ -MDIR ] [ -nNUM ] [ -oLIST ] + [ -rCN ] [ -TNAME ] [ -wNAME ] [ -WNAME ] + [ FILES... ] + +Obviously, many of the options to 'groff' are actually passed on to +'gtroff'. + + Options without an argument can be grouped behind a single '-'. A +filename of '-' denotes the standard input. Whitespace is permitted +between an option and its argument. + + The 'grog' command can be used to guess the correct 'groff' command +to format a file. See its man page 'grog(1)'; type 'man grog' at the +command line to view it. + + 'groff''s command-line options are as follows. + +'-a' + Generate a plain text approximation of the typeset output. The + read-only register '.A' is set to 1. *Note Built-in Registers::. + This option produces a sort of abstract preview of the formatted + output. + + * Page breaks are marked by a phrase in angle brackets; for + example, '<beginning of page>'. + + * Lines are broken where they would be in the formatted output. + + * A horizontal motion of any size is represented as one space. + Adjacent horizontal motions are not combined. Inter-sentence + space nodes (those arising from the second argument to the + 'ss' request) are not represented. + + * Vertical motions are not represented. + + * Special characters are rendered in angle brackets; for + example, the default soft hyphen character appears as '<hy>'. + + The above description should not be considered a specification; the + details of '-a' output are subject to change. + +'-b' + Write a backtrace reporting the state of 'gtroff''s input parser to + the standard error stream with each diagnostic message. The line + numbers given in the backtrace might not always be correct, because + 'gtroff''s idea of line numbers can be confused by requests that + append to macros. + +'-c' + Start with color output disabled. + +'-C' + Enable AT&T 'troff' compatibility mode; implies '-c'. *Note + Implementation Differences::, for the list of incompatibilities + between 'groff' and AT&T 'troff'. + +'-dCTEXT' +'-dSTRING=TEXT' + Define 'roff' string C or STRING as T or TEXT. C must be one + character; STRING can be of arbitrary length. Such string + assignments happen before any macro file is loaded, including the + startup file. Due to 'getopt_long' limitations, C cannot be, and + STRING cannot contain, an equals sign, even though that is a valid + character in a 'roff' identifier. + +'-DENC' + Set fallback input encoding used by 'preconv' to ENC; implies '-k'. + +'-e' + Run 'geqn' preprocessor. + +'-E' + Inhibit 'gtroff' error messages. This option does _not_ suppress + messages sent to the standard error stream by documents or macro + packages using 'tm' or related requests. + +'-fFAM' + Use FAM as the default font family. *Note Font Families::. + +'-FDIR' + Search in directory 'DIR' for the selected output device's + directory of device and font description files. See the + description of 'GROFF_FONT_PATH' in *note Environment:: below for + the default search locations and ordering. + +'-g' + Run 'ggrn' preprocessor. + +'-G' + Run 'grap' preprocessor; implies '-p'. + +'-h' + Display a usage message and exit. + +'-i' + Read the standard input after all the named input files have been + processed. + +'-IDIR' + Search the directory DIR for files named in several contexts; + implies '-g' and '-s'. + + * 'gsoelim' replaces 'so' requests with the contents of their + file name arguments. + + * 'gtroff' searches for files named as operands in its command + line and as arguments to 'psbb', 'so', and 'soquiet' requests. + + * Output drivers may search for files; for instance, 'grops' + looks for files named in '\X'ps: import ...'', '\X'ps: file + ...'', and '\X'pdf: pdfpic ...'' device control escape + sequences. + + This option may be specified more than once; the directories are + searched in the order specified. If you want to search the current + directory before others, add '-I .' at the desired place. The + current working directory is otherwise searched last. '-I' works + similarly to, and is named for, the "include" option of Unix C + compilers. + + '-I' options are passed to 'gsoelim', 'gtroff', and output drivers; + with the flag letter changed to '-M', they are also passed to + 'ggrn'. + +'-j' + Run 'gchem' preprocessor. Implies '-p'. + +'-k' + Run 'preconv' preprocessor. Refer to its man page for its behavior + if neither of 'groff''s '-K' or '-D' options is also specified. + +'-KENC' + Set input encoding used by 'preconv' to ENC; implies '-k'. + +'-l' + Send the output to a spooler for printing. The 'print' directive + in the device description file specifies the default command to be + used; see *note Device and Font Description Files::. See options + '-L' and '-X'. + +'-LARG' + Pass ARG to the print spooler program. If multiple ARGs are + required, pass each with a separate '-L' option. 'groff' does not + prefix an option dash to ARG before passing it to the spooler + program. + +'-mNAME' + Process the file 'NAME.tmac' prior to any input files. If not + found, 'tmac.NAME' is attempted. NAME (in both arrangements) is + presumed to be a macro file; see the description of + 'GROFF_TMAC_PATH' in *note Environment:: below for the default + search locations and ordering. This option and its argument are + also passed to 'geqn', 'grap', and 'ggrn'. + +'-MDIR' + Search directory 'DIR' for macro files; see the description of + 'GROFF_TMAC_PATH' in *note Environment:: below for the default + search locations and ordering. This option and its argument are + also passed to 'geqn', 'grap', and 'ggrn'. + +'-nNUM' + Number the first page NUM. + +'-N' + Prohibit newlines between 'eqn' delimiters: pass '-N' to 'geqn'. + +'-oLIST' + Output only pages in LIST, which is a comma-separated list of page + ranges; 'N' means page N, 'M-N' means every page between M and N, + '-N' means every page up to N, 'N-' means every page from N on. + 'gtroff' stops processing and exits after formatting the last page + enumerated in LIST. + +'-p' + Run 'gpic' preprocessor. + +'-PARG' + Pass ARG to the postprocessor. If multiple ARGs are required, pass + each with a separate '-P' option. 'groff' does not prefix an + option dash to ARG before passing it to the postprocessor. + +'-rCNUMERIC-EXPRESSION' +'-rREGISTER=EXPR' + Set 'roff' register C or REGISTER to the value NUMERIC-EXPRESSION + (*note Numeric Expressions::). C must be one character; REGISTER + can be of arbitrary length. Such register assignments happen + before any macro file is loaded, including the startup file. Due + to 'getopt_long' limitations, C cannot be, and REGISTER cannot + contain, an equals sign, even though that is a valid character in a + 'roff' identifier. + +'-R' + Run 'grefer' preprocessor. No mechanism is provided for passing + arguments to 'grefer' because most 'grefer' options have equivalent + language elements that can be specified within the document. + + 'gtroff' also accepts a '-R' option, which is not accessible via + 'groff'. This option prevents the loading of the 'troffrc' and + 'troffrc-end' files. + +'-s' + Run 'gsoelim' preprocessor. + +'-S' + Operate in "safer" mode; see '-U' below for its opposite. For + security reasons, safer mode is enabled by default. + +'-t' + Run 'gtbl' preprocessor. + +'-TDEV' + Direct 'gtroff' to format the input for the output device DEV. + 'groff' then calls an output driver to convert 'gtroff''s output to + a form appropriate for DEV. The following output devices are + available. + + 'ps' + For PostScript printers and previewers. + + 'pdf' + For PDF viewers or printers. + + 'dvi' + For TeX DVI format. + + 'X75' + For a 75dpi X11 previewer. + + 'X75-12' + For a 75dpi X11 previewer with a 12-point base font in the + document. + + 'X100' + For a 100dpi X11 previewer. + + 'X100-12' + For a 100dpi X11 previewer with a 12-point base font in the + document. + + 'ascii' + For typewriter-like devices using the (7-bit) ASCII (ISO 646) + character set. + + 'latin1' + For typewriter-like devices that support the Latin-1 + (ISO 8859-1) character set. + + 'utf8' + For typewriter-like devices that use the Unicode (ISO 10646) + character set with UTF-8 encoding. + + 'cp1047' + For typewriter-like devices that use the EBCDIC encoding IBM + code page 1047. + + 'lj4' + For HP LaserJet4-compatible (or other PCL5-compatible) + printers. + + 'lbp' + For Canon CaPSL printers (LBP-4 and LBP-8 series laser + printers). + + 'html' + 'xhtml' + To produce HTML and XHTML output, respectively. This driver + consists of two parts, a preprocessor ('pre-grohtml') and a + postprocessor ('post-grohtml'). + + The predefined GNU 'troff' string '.T' contains the name of the + output device; the read-only register '.T' is set to 1 if this + option is used (which is always true if 'groff' is used to call GNU + 'troff'). *Note Built-in Registers::. + + The postprocessor to be used for a device is specified by the + 'postpro' command in the device description file. (*Note Device + and Font Description Files::.) This can be overridden with the + '-X' option. + +'-U' + Operate in "unsafe mode", which enables the 'open', 'opena', 'pi', + 'pso', and 'sy' requests. These requests are disabled by default + because they allow an untrusted input document to write to + arbitrary file names and run arbitrary commands. This option also + adds the current directory to the macro package search path; see + the '-m' option above. '-U' is passed to 'gpic' and 'gtroff'. + +'-v' + Write version information for 'groff' and all programs run by it to + the standard output stream; that is, the given command line is + processed in the usual way, passing '-v' to the formatter and any + pre- or postprocessors invoked. + +'-V' + Output the pipeline that would be run by 'groff' (as a wrapper + program) to the standard output stream, but do not execute it. If + given more than once, the pipeline is both written to the standard + error stream and run. + +'-wCATEGORY' + Enable warnings in CATEGORY. Categories are listed in *note + Warnings::. + +'-WCATEGORY' + Inhibit warnings in CATEGORY. Categories are listed in *note + Warnings::. + +'-X' + Use 'gxditview' instead of the usual postprocessor to (pre)view a + document on an X11 display. Combining this option with '-Tps' uses + the font metrics of the PostScript device, whereas the '-TX75' and + '-TX100' options use the metrics of X11 fonts. + +'-z' + Suppress formatted output from 'gtroff'. + +'-Z' + Disable postprocessing. 'gtroff' output will appear on the + standard output stream (unless suppressed with '-z'; see *note + gtroff Output:: for a description of this format. + + +File: groff.info, Node: Environment, Next: Macro Directories, Prev: Groff Options, Up: Invoking groff + +2.2 Environment +=============== + +There are also several environment variables (of the operating system, +not within 'gtroff') that can modify the behavior of 'groff'. + +'GROFF_BIN_PATH' + This search path, followed by 'PATH', is used for commands executed + by 'groff'. + +'GROFF_COMMAND_PREFIX' + If this is set to X, then 'groff' runs 'Xtroff' instead of + 'gtroff'. This also applies to 'tbl', 'pic', 'eqn', 'grn', 'chem', + 'refer', and 'soelim'. It does not apply to 'grops', 'grodvi', + 'grotty', 'pre-grohtml', 'post-grohtml', 'preconv', 'grolj4', + 'gropdf', and 'gxditview'. + + The default command prefix is determined during the installation + process. If a non-GNU 'troff' system is found, prefix 'g' is used, + none otherwise. + +'GROFF_ENCODING' + The value of this variable is passed to the 'preconv' + preprocessor's '-e' option to select the character encoding of + input files. This variable's existence implies the 'groff' option + '-k'. If set but empty, 'groff' calls 'preconv' without an '-e' + option. 'groff''s '-K' option overrides 'GROFF_ENCODING'. See the + 'preconv(7)' man page; type 'man preconv' at the command line to + view it. + +'GROFF_FONT_PATH' + A list of directories in which to seek the selected output device's + directory of device and font description files. GNU 'troff' will + search directories given as arguments to any specified '-F' options + before these, and a built-in list of directories after them. *Note + Font Directories:: and the 'troff(1)' or 'gtroff(1)' man pages. + +'GROFF_TMAC_PATH' + A list of directories in which to seek macro files. GNU 'troff' + will search directories given as arguments to any specified '-M' + options before these, and a built-in list of directories after + them. *Note Macro Directories:: and the 'troff(1)' or 'gtroff(1)' + man pages. + +'GROFF_TMPDIR' + The directory in which 'groff' creates temporary files. If this is + not set and 'TMPDIR' is set, temporary files are created in that + directory. Otherwise temporary files are created in a + system-dependent default directory (on Unix and GNU/Linux systems, + this is usually '/tmp'). 'grops', 'grefer', 'pre-grohtml', and + 'post-grohtml' can create temporary files in this directory. + +'GROFF_TYPESETTER' + Sets the default output device. If empty or not set, a build-time + default (often 'ps') is used. The '-TDEV' option overrides + 'GROFF_TYPESETTER'. + +'SOURCE_DATE_EPOCH' + A timestamp (expressed as seconds since the Unix epoch) to use as + the output creation timestamp in place of the current time. The + time is converted to human-readable form using 'localtime(3)' when + the formatter starts up and stored in registers usable by documents + and macro packages (*note Built-in Registers::). + +'TZ' + The time zone to use when converting the current time (or value of + 'SOURCE_DATE_EPOCH') to human-readable form; see 'tzset(3)'. + + MS-DOS and MS-Windows ports of 'groff' use semicolons, rather than +colons, to separate the directories in the lists described above. + + +File: groff.info, Node: Macro Directories, Next: Font Directories, Prev: Environment, Up: Invoking groff + +2.3 Macro Directories +===================== + +A macro file must have a name in the form 'NAME.tmac' or 'tmac.NAME' and +be placed in a "tmac directory" to be found by the '-mNAME' command-line +option.(1) (*note Macro Directories-Footnote-1::) Together, these +directories constitute the "tmac path". Each directory is searched in +the following order until the desired macro file is found or the list is +exhausted. + + * Directories specified with GNU 'troff''s or 'groff''s '-M' + command-line option. + + * Directories listed in the 'GROFF_TMAC_PATH' environment variable. + + * The current working directory (only if in unsafe mode using the + '-U' command-line option). + + * The user's home directory, 'HOME'. + + * A platform-dependent directory, a site-local (platform-independent) + directory, and the main tmac directory. The locations + corresponding to your installation are listed in section + "Environment" of 'gtroff(1)'. If not otherwise configured, they + are as follows. + + /usr/local/lib/groff/site-tmac + /usr/local/share/groff/site-tmac + /usr/local/share/groff/1.23.0/tmac + + The foregoing assumes that the version of 'groff' is 1.23.0, and + that the installation prefix was '/usr/local'. It is possible to + fine-tune these locations during the source configuration process. + + +File: groff.info, Node: Macro Directories-Footnotes, Up: Macro Directories + + (1) The 'mso' request does not have these limitations. *Note I/O::. + + +File: groff.info, Node: Font Directories, Next: Paper Format, Prev: Macro Directories, Up: Invoking groff + +2.4 Font Directories +==================== + +'groff' enforces few restrictions on how font description files are +named. For its family/style mechanism to work (*note Font Families::), +the names of fonts within a family should start with the family name, +followed by the style. For example, the Times family uses 'T' for the +family name and 'R', 'B', 'I', and 'BI' to indicate the styles 'roman', +'bold', 'italic', and 'bold italic', respectively. Thus the final font +names are 'TR', 'TB', 'TI', and 'TBI'. + + Font description files are kept in "font directories", which together +constitute the "font path". The search procedure always appends the +directory 'dev'NAME, where NAME is the name of the output device. +Assuming TeX DVI output, and '/foo/bar' as a font directory, the font +description files for 'grodvi' must be in '/foo/bar/devdvi'. Each +directory in the font path is searched in the following order until the +desired font description file is found or the list is exhausted. + + * Directories specified with GNU 'troff''s or 'groff''s '-f' + command-line option. All output drivers (and some preprocessors) + support this option as well, because they require information about + the glyphs to be rendered in the document. + + * Directories listed in the 'GROFF_FONT_PATH' environment variable. + + * A site-local directory and the main font description directory. + The locations corresponding to your installation are listed in + section "Environment" of 'gtroff(1)'. If not otherwise configured, + they are as follows. + + /usr/local/share/groff/site-font + /usr/local/share/groff/1.23.0/font + + The foregoing assumes that the version of 'groff' is 1.23.0, and + that the installation prefix was '/usr/local'. It is possible to + fine-tune these locations during the source configuration process. + + +File: groff.info, Node: Paper Format, Next: Invocation Examples, Prev: Font Directories, Up: Invoking groff + +2.5 Paper Format +================ + +In 'groff', the page dimensions for the formatter GNU 'troff' and for +output devices are handled separately. *Note Page Layout::, for +vertical manipulation of the page size, and *Note Line Layout::, for +horizontal changes. The 'papersize' macro package, normally loaded by +'troffrc' at startup, provides an interface for configuring page +dimensions by convenient names, like 'letter' or 'a4'; see +'groff_tmac(5)'. The default used by the formatter depends on its build +configuration, but is usually one of the foregoing, as geographically +appropriate. + + It is up to each macro package to respect the page dimensions +configured in this way. + + For each output device, the size of the output medium can be set in +its 'DESC' file. Most output drivers also recognize a command-line +option '-p' to override the default dimensions and an option '-l' to use +landscape orientation. *Note DESC File Format::, for a description of +the 'papersize' keyword, which takes an argument of the same form as +'-p'. The output driver's man page, such as 'grops(1)', may also be +helpful. + + 'groff' uses the command-line option '-P' to pass options to +postprocessors; for example, use the following for PostScript output on +A4 paper in landscape orientation. + + groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps + + +File: groff.info, Node: Invocation Examples, Prev: Paper Format, Up: Invoking groff + +2.6 Invocation Examples +======================= + +'roff' systems are best known for formatting man pages. Once a 'man' +librarian program has located a man page, it may execute a 'groff' +command much like the following. + + groff -t -man -Tutf8 /usr/share/man/man1/groff.1 + + The librarian will also pipe the output through a pager, which might +not interpret the SGR terminal escape sequences 'groff' emits for +boldface, underlining, or italics; see the 'grotty(1)' man page for a +discussion. + + To process a 'roff' input file using the preprocessors 'gtbl' and +'gpic' and the 'me' macro package in the way to which AT&T 'troff' users +were accustomed, one would type (or script) a pipeline. + + gpic foo.me | gtbl | gtroff -me -Tutf8 | grotty + + Using 'groff', this pipe can be shortened to an equivalent command. + + groff -p -t -me -T utf8 foo.me + + An even easier way to do this is to use 'grog' to guess the +preprocessor and macro options and execute the result by using the +command substitution feature of the shell. + + $(grog -Tutf8 foo.me) + + Each command-line option to a postprocessor must be specified with +any required leading dashes '-' because 'groff' passes the arguments +as-is to the postprocessor; this permits arbitrary arguments to be +transmitted. For example, to pass a title to the 'gxditview' +postprocessor, the shell commands + + groff -X -P -title -P 'trial run' mydoc.t + +and + + groff -X -Z mydoc.t | gxditview -title 'trial run' - + +are equivalent. + + +File: groff.info, Node: Tutorial for Macro Users, Next: Major Macro Packages, Prev: Invoking groff, Up: Top + +3 Tutorial for Macro Users +************************** + +Most users of the 'roff' language employ a macro package to format their +documents. Successful macro packages ease the composition process; +their users need not have mastered the full formatting language, nor +understand features like diversions, traps, and environments. This +chapter aims to familiarize you with basic concepts and mechanisms +common to many macro packages (like "displays"). If you prefer a +meticulous and comprehensive presentation, try *note GNU troff +Reference:: instead. + +* Menu: + +* Basics:: +* Common Features:: + + +File: groff.info, Node: Basics, Next: Common Features, Prev: Tutorial for Macro Users, Up: Tutorial for Macro Users + +3.1 Basics +========== + +Let us first survey some basic concepts necessary to use a macro package +fruitfully.(1) (*note Basics-Footnote-1::) References are made +throughout to more detailed information. + + GNU 'troff' reads an input file prepared by the user and outputs a +formatted document suitable for publication or framing. The input +consists of text, or words to be printed, and embedded commands +(requests and escape sequences), which tell GNU 'troff' how to format +the output. *Note Formatter Instructions::. + + The word argument is used in this chapter to mean a word or number +that appears on the same line as a request, and which modifies the +meaning of that request. For example, the request + + .sp + +spaces one line, but + + .sp 4 + +spaces four lines. The number 4 is an argument to the 'sp' request, +which says to space four lines instead of one. Arguments are separated +from the request and from each other by spaces (_not_ tabs). *Note +Invoking Requests::. + + The primary function of GNU 'troff' is to collect words from input +lines, fill output lines with those words, adjust the line to the +right-hand margin by widening spaces, and output the result. For +example, the input: + + Now is the time + for all good men + to come to the aid + of their party. + Four score and seven + years ago, etc. + +is read, packed onto output lines, and justified to produce: + + => Now is the time for all good men to come to the aid of + => their party. Four score and seven years ago, etc. + + Sometimes a new output line should be started even though the current +line is not yet full--for example, at the end of a paragraph. To do +this it is possible to force a break, starting a new output line. Some +requests cause a break automatically, as do (normally) blank input lines +and input lines beginning with a space or tab. + + Not all input lines are text lines--words to be formatted. Some are +control lines that tell a macro package (or GNU 'troff' directly) how to +format the text. Control lines start with a dot ('.') or an apostrophe +(''') as the first character, and can be followed by a macro call. + + The formatter also does more complex things, such as automatically +numbering pages, skipping over page boundaries, putting footnotes in the +correct place, and so forth. + + Here are a few hints for preparing text for input to GNU 'troff'. + + * First, keep the input lines short. Short input lines are easier to + edit, and GNU 'troff' packs words onto longer lines anyhow. + + * In keeping with this, it is helpful to begin a new line after every + comma or phrase, since common corrections are to add or delete + sentences or phrases. + + * End each sentence with two spaces--or better, start each sentence + on a new line. GNU 'troff' recognizes characters that usually end + a sentence, and inserts inter-sentence space accordingly. + + * Do not hyphenate words at the end of lines--GNU 'troff' is smart + enough to hyphenate words as needed, but is not smart enough to + take hyphens out and join a word back together. Also, words such + as "mother-in-law" should not be broken over a line, since then a + space can occur where not wanted, such as "mother- in-law". + + We offer further advice in *note Input Conventions::. + + GNU 'troff' permits alteration of the distance between lines of text. +This is termed vertical spacing and is expressed in the same units as +the type size--the point. The default is 10-point type on 12-point +spacing. To get double-spaced text you would set the vertical spacing +to 24 points. Some, but not all, macro packages expose a macro or +register to configure the vertical spacing. + + A number of requests allow you to change the way the output is +arranged on the page, sometimes called the layout of the output page. +Most macro packages don't supply macros for performing these (at least +not without performing other actions besides), as they are such basic +operations. The macro packages for writing man pages, 'man' and 'mdoc', +don't encourage explicit use of these requests at all. + + The request '.sp N' leaves N lines of blank space. N can be omitted +(skipping a single line) or can be of the form Ni (for N inches) or Nc +(for N centimeters). For example, the input: + + .sp 1.5i + My thoughts on the subject + .sp + +leaves one and a half inches of space, followed by the line "My thoughts +on the subject", followed by a single blank line (more measurement units +are available; see *note Measurements::). + + If you seek precision in spacing, be advised when using a macro +package that it might not honor 'sp' requests as you expect; it can use +a formatter feature called no-space mode to prevent excess space from +accumulating. Macro packages typically offer registers to control +spacing between paragraphs, before section headings, and around displays +(discussed below); use these facilities preferentially. *Note +Manipulating Spacing::. + + Text lines can be centered by using the 'ce' request. The line after +'ce' is centered (horizontally) on the page. To center more than one +line, use '.ce N' (where N is the number of lines to center), followed +by the N lines. To center many lines without counting them, type: + + .ce 1000 + lines to center + .ce 0 + +The '.ce 0' request tells GNU 'troff' to center zero more lines, in +other words, stop centering. + + GNU 'troff' also offers the 'rj' request for right-aligning text. It +works analogously to 'ce' and is convenient for setting epigraphs. + + The 'bp' request starts a new page; this necessarily implies an +ordinary (line) break. + + All of these requests cause a break; that is, they always start a new +line. To start a new line without performing any other action, use +'br'. If you invoke them with the apostrophe ''', the no-break control +character, the (initial) break they normally perform is suppressed. +''br' does nothing. + + +File: groff.info, Node: Basics-Footnotes, Up: Basics + + (1) The remainder of this chapter is based on 'Writing Papers with +nroff using -me' by Eric P. Allman, which is distributed with 'groff' as +'meintro.me'. + + +File: groff.info, Node: Common Features, Prev: Basics, Up: Tutorial for Macro Users + +3.2 Common Features +=================== + +GNU 'troff' provides low-level operations for formatting a document. +Many routine operations are undertaken in nearly all documents that +require a series of such primitive operations to be performed. These +common tasks are grouped into macros, which are then collected into a +macro package. + + Macro packages come in two varieties: "major" or "full-service" ones +that manage page layout, and "minor" or "auxiliary" ones that do not, +instead fulfilling narrow, specific tasks. Find a list in the +'groff_tmac(5)' man page. Type 'man groff_tmac' at the command line to +view it. + + We survey several capabilities of full-service macro package below. +Each package employs its own macros to exercise them. For details, +consult its man page or, for 'ms', see *note ms::. + +* Menu: + +* Paragraphs:: +* Sections and Chapters:: +* Headers and Footers:: +* Page Layout Adjustment:: +* Displays and Keeps:: +* Footnotes and Endnotes:: +* Table of Contents:: +* Indexing:: +* Document Formats:: +* Columnation:: +* Font and Size Changes:: +* Predefined Text:: +* Preprocessor Support:: +* Configuration and Customization:: + + +File: groff.info, Node: Paragraphs, Next: Sections and Chapters, Prev: Common Features, Up: Common Features + +3.2.1 Paragraphs +---------------- + +Paragraphs can be separated and indented in various ways. Some start +with a blank line and have a first-line indentation, like most of the +ones in this manual. Block paragraphs omit the indentation. + + => Some men look at constitutions with sanctimonious + => reverence, and deem them like the ark of the + => covenant, too sacred to be touched. + +We also frequently encounter tagged paragraphs, which begin with a tag +or label at the left margin and indent the remaining text. + + => one This is the first paragraph. Notice how the + => first line of the resulting paragraph lines + => up with the other lines in the paragraph. + +If the tag is too wide for the indentation, the line is broken. + + => longlabel + => The label does not align with the subsequent + => lines, but they align with each other. + +A variation of the tagged paragraph is the itemized or enumerated +paragraph, which might use punctuation or a digit for a tag, +respectively. These are frequently used to construct lists. + + => o This list item starts with a bullet. When + => producing output for a device using the ASCII + => character set, an 'o' is formatted instead. + +Often, use of the same macro without a tag continues such a discussion. + + => -xyz This option is recognized but ignored. + => + => It had a security hole that we don't discuss. + + +File: groff.info, Node: Sections and Chapters, Next: Headers and Footers, Prev: Paragraphs, Up: Common Features + +3.2.2 Sections and Chapters +--------------------------- + +The simplest kind of section heading is unnumbered, set in a bold or +italic style, and occupies a line by itself. Others possess +automatically numbered multi-level headings and/or different typeface +styles or sizes at different levels. More sophisticated macro packages +supply macros for designating chapters and appendices. + + +File: groff.info, Node: Headers and Footers, Next: Page Layout Adjustment, Prev: Sections and Chapters, Up: Common Features + +3.2.3 Headers and Footers +------------------------- + +Headers and footers occupy the top and bottom of each page, +respectively, and contain data like the page number and the article or +chapter title. Their appearance is not affected by the running text. +Some packages allow for different titles on even- and odd-numbered pages +(for printed, bound material). + + Headers and footers are together called titles, and comprise three +parts: left-aligned, centered, and right-aligned. A '%' character +appearing anywhere in a title is automatically replaced by the page +number. *Note Page Layout::. + + +File: groff.info, Node: Page Layout Adjustment, Next: Displays and Keeps, Prev: Headers and Footers, Up: Common Features + +3.2.4 Page Layout +----------------- + +Most macro packages let the user specify the size of the page margins. +The top and bottom margins are typically handled differently than the +left and right margins; the latter two are derived from the page offset, +indentation, and line length. *Note Line Layout::. Commonly, packages +support registers to tune these values. + + +File: groff.info, Node: Displays and Keeps, Next: Footnotes and Endnotes, Prev: Page Layout Adjustment, Up: Common Features + +3.2.5 Displays and Keeps +------------------------ + +Displays are sections of text set off from the surrounding material +(typically paragraphs), often differing in indentation, and/or spacing. +Tables, block quotations, and figures are displayed. Equations and code +examples, when not much shorter than an output line, often are. Lists +may or may not be. Packages for setting man pages support example +displays but not keeps. + + A keep is a group of output lines, often a display, that is formatted +on a single page if possible; it causes a page break to happen early so +as to not interrupt the kept material. + + Floating keeps can move, or "float", relative to the text around them +in the input. They are useful for displays that are captioned and +referred to by name, as with "See figure 3". Depending on the package, +a floating keep appears at the bottom of the current page if it fits, +and at the top of the next otherwise. Alternatively, floating keeps +might be deferred to the end of a section. Using a floating keep can +avoid the large vertical spaces that may precede a tall keep of the +ordinary sort when it won't fit on the page. + + +File: groff.info, Node: Footnotes and Endnotes, Next: Table of Contents, Prev: Displays and Keeps, Up: Common Features + +3.2.6 Footnotes and Endnotes +---------------------------- + +Footnotes and endnotes are forms of delayed formatting. They are +recorded at their points of relevance in the input, but not formatted +there. Instead, a mark cues the reader to check the "foot", or bottom, +of the current page, or in the case of endnotes, an annotation list +later in the document. Macro packages that support these features also +supply a means of automatically numbering either type of annotation. + + +File: groff.info, Node: Table of Contents, Next: Indexing, Prev: Footnotes and Endnotes, Up: Common Features + +3.2.7 Table of Contents +----------------------- + +A package may handle a table of contents by directing section heading +macros to save section heading text and the page number where it occurs +for use in a later entry for a table of contents. It writes the +collected entries at the end of the document, once all are known, upon +request. A row of dots (a leader) bridges the text on the left with its +location on the right. Other collections might work in this manner, +providing lists of figures or tables. + + A table of contents is often found at the end of a GNU 'troff' +document because the formatter processes the document in a single pass. +The 'gropdf' output driver supports a PDF feature that relocates pages +at the time the document is rendered; see the 'gropdf(1)' man page. +Type 'man gropdf' at the command line to view it. + + +File: groff.info, Node: Indexing, Next: Document Formats, Prev: Table of Contents, Up: Common Features + +3.2.8 Indexing +-------------- + +An index is similar to a table of contents, in that entry labels and +locations must be collected, but poses a greater challenge because it +needs to be sorted before it is output. Here, processing the document +in multiple passes is inescapable, and tools like the 'makeindex' +program are necessary. + + +File: groff.info, Node: Document Formats, Next: Columnation, Prev: Indexing, Up: Common Features + +3.2.9 Document Formats +---------------------- + +Some macro packages supply stock configurations of certain documents, +like business letters and memoranda. These often also have provision +for a cover sheet, which may be rigid in its format. With these +features, it is even more important to use the package's macros in +preference to the formatter requests presented earlier, where possible. + + +File: groff.info, Node: Columnation, Next: Font and Size Changes, Prev: Document Formats, Up: Common Features + +3.2.10 Columnation +------------------ + +Macro packages apart from 'man' and 'mdoc' for man page formatting offer +a facility for setting multiple columns on the page. + + +File: groff.info, Node: Font and Size Changes, Next: Predefined Text, Prev: Columnation, Up: Common Features + +3.2.11 Font and Size Changes +---------------------------- + +The formatter's requests and escape sequences for setting the typeface +and size are not always intuitive, so all macro packages provide macros +to make these operations simpler. They also make it more convenient to +change typefaces in the middle of a word and can handle italic +corrections automatically. *Note Italic Corrections::. + + +File: groff.info, Node: Predefined Text, Next: Preprocessor Support, Prev: Font and Size Changes, Up: Common Features + +3.2.12 Predefined Text +---------------------- + +Most macro packages supply predefined strings to set prepared text like +the date, or to perform operations like super- and subscripting. + + +File: groff.info, Node: Preprocessor Support, Next: Configuration and Customization, Prev: Predefined Text, Up: Common Features + +3.2.13 Preprocessor Support +--------------------------- + +All macro packages provide support for various preprocessors and may +extend their functionality by defining macros to set their contents in +displays. Examples include 'TS' and 'TE' for 'gtbl', 'EQ' and 'EN' for +'geqn', and 'PS' and 'PE' for 'gpic'. + + +File: groff.info, Node: Configuration and Customization, Prev: Preprocessor Support, Up: Common Features + +3.2.14 Configuration and Customization +-------------------------------------- + +Packages provide means of customizing many of the details of how the +package behaves. These range from setting the default type size to +changing the appearance of section headers. + + +File: groff.info, Node: Major Macro Packages, Next: GNU troff Reference, Prev: Tutorial for Macro Users, Up: Top + +4 Macro Packages +**************** + +This chapter surveys the "major" macro packages that come with 'groff'. +One, 'ms', is presented in detail. + + Major macro packages are also sometimes described as "full-service" +due to the breadth of features they provide and because more than one +cannot be used by the same document; for example + + groff -m man foo.man -m ms bar.doc + +doesn't work. Option arguments are processed before non-option +arguments; the above (failing) sample is thus reordered to + + groff -m man -m ms foo.man bar.doc + + Many auxiliary, or "minor", macro packages are also available. They +may in general be used with any full-service macro package and handle a +variety of tasks from character encoding selection, to language +localization, to inlining of raster images. See the 'groff_tmac(5)' man +page for a list. Type 'man groff_tmac' at the command line to view it. + +* Menu: + +* man:: +* mdoc:: +* me:: +* mm:: +* mom:: +* ms:: + + +File: groff.info, Node: man, Next: mdoc, Prev: Major Macro Packages, Up: Major Macro Packages + +4.1 'man' +========= + +The 'man' macro package is the most widely used and probably the most +important ever developed for 'troff'. It is easy to use, and a vast +majority of manual pages ("man pages") are written in it. + + 'groff''s implementation is documented in the 'groff_man(7)' man +page. Type 'man groff_man' at the command line to view it. + +* Menu: + +* Optional man extensions:: + + +File: groff.info, Node: Optional man extensions, Up: man + +4.1.1 Optional 'man' extensions +------------------------------- + +Use the file 'man.local' for local extensions to the 'man' macros or for +style changes. + +Custom headers and footers +.......................... + +In 'groff' versions 1.18.2 and later, you can specify custom headers and +footers by redefining the following macros in 'man.local'. + + -- Macro: .PT + Control the content of the headers. Normally, the header prints + the command name and section number on either side, and the + optional fifth argument to 'TH' in the center. + + -- Macro: .BT + Control the content of the footers. Normally, the footer prints + the page number and the third and fourth arguments to 'TH'. + + Use the 'FT' register to specify the footer position. The default + is -0.5i. + +Ultrix-specific man macros +.......................... + +The 'groff' source distribution includes a file named 'man.ultrix', +containing macros compatible with the Ultrix variant of 'man'. Copy +this file into 'man.local' (or use the 'mso' request to load it) to +enable the following macros. + + -- Macro: .CT key + Print '<CTRL/KEY>'. + + -- Macro: .CW + Print subsequent text using a "constant-width" (monospaced) + typeface (Courier roman). + + -- Macro: .Ds + Begin a non-filled display. + + -- Macro: .De + End a non-filled display started with 'Ds'. + + -- Macro: .EX [indent] + Begin a non-filled display using a monospaced typeface (Courier + roman). Use the optional INDENT argument to indent the display. + + -- Macro: .EE + End a non-filled display started with 'EX'. + + -- Macro: .G [text] + Set TEXT in Helvetica. If no text is present on the line where the + macro is called, then the text of the next line appears in + Helvetica. + + -- Macro: .GL [text] + Set TEXT in Helvetica oblique. If no text is present on the line + where the macro is called, then the text of the next line appears + in Helvetica Oblique. + + -- Macro: .HB [text] + Set TEXT in Helvetica bold. If no text is present on the line + where the macro is called, then all text up to the next 'HB' + appears in Helvetica bold. + + -- Macro: .TB [text] + Identical to 'HB'. + + -- Macro: .MS title sect [punct] + Set a man page reference in Ultrix format. The TITLE is in Courier + instead of italic. Optional punctuation follows the section number + without an intervening space. + + -- Macro: .NT [C] [title] + Begin a note. Print the optional title, or the word "Note", + centered on the page. Text following the macro makes up the body + of the note, and is indented on both sides. If the first argument + is 'C', the body of the note is printed centered (the second + argument replaces the word "Note" if specified). + + -- Macro: .NE + End a note begun with 'NT'. + + -- Macro: .PN path [punct] + Set the path name in a monospaced typeface (Courier roman), + followed by optional punctuation. + + -- Macro: .Pn [punct] path [punct] + If called with two arguments, identical to 'PN'. If called with + three arguments, set the second argument in a monospaced typeface + (Courier roman), bracketed by the first and third arguments in the + current font. + + -- Macro: .R + Switch to roman font and turn off any underlining in effect. + + -- Macro: .RN + Print the string '<RETURN>'. + + -- Macro: .VS [4] + Start printing a change bar in the margin if the number '4' is + specified. Otherwise, this macro does nothing. + + -- Macro: .VE + End printing the change bar begun by 'VS'. + +Simple example +.............. + +The following example 'man.local' file alters the 'SH' macro to add some +extra vertical space before printing the heading. Headings are printed +in Helvetica bold. + + .\" Make the heading fonts Helvetica + .ds HF HB + . + .\" Put more space in front of headings. + .rn SH SH-orig + .de SH + . if t .sp (u;\\n[PD]*2) + . SH-orig \\$* + .. + + +File: groff.info, Node: mdoc, Next: me, Prev: man, Up: Major Macro Packages + +4.2 'mdoc' +========== + +'groff''s implementation of the BSD 'doc' package for man pages is +documented in the 'groff_mdoc(7)' man page. Type 'man groff_mdoc' at +the command line to view it. + + +File: groff.info, Node: me, Next: mm, Prev: mdoc, Up: Major Macro Packages + +4.3 'me' +======== + +'groff''s implementation of the BSD 'me' macro package is documented +using itself. A tutorial, 'meintro.me', and reference, 'meref.me', are +available in 'groff''s documentation directory. A 'groff_me(7)' man +page is also available and identifies the installation path for these +documents. Type 'man groff_me' at the command line to view it. + + A French translation of the tutorial is available as 'meintro_fr.me' +and installed parallel to the English version. + + +File: groff.info, Node: mm, Next: mom, Prev: me, Up: Major Macro Packages + +4.4 'mm' +======== + +'groff''s implementation of the AT&T memorandum macro package is +documented in the 'groff_mm(7)' man page. Type 'man groff_mm' at the +command line) to view it. + + A Swedish localization of 'mm' is also available; see +'groff_mmse(7)'. + + +File: groff.info, Node: mom, Next: ms, Prev: mm, Up: Major Macro Packages + +4.5 'mom' +========= + +The main documentation files for the 'mom' macros are in HTML format. +Additional, useful documentation is in PDF format. See the 'groff(1)' +man page, section "Installation Directories", for their location. + + * 'toc.html' Entry point to the full mom manual. + + * 'macrolist.html' Hyperlinked index of macros with brief + descriptions, arranged by category. + + * 'mom-pdf.pdf' PDF features and usage. + + The mom macros are in active development between 'groff' releases. +The most recent version, along with up-to-date documentation, is +available at <http://www.schaffter.ca/mom/mom-05.html>. + + The 'groff_mom(7)' man page (type 'man groff_mom' at the command +line) contains a partial list of available macros, however their usage +is best understood by consulting the HTML documentation. + + +File: groff.info, Node: ms, Prev: mom, Up: Major Macro Packages + +4.6 'ms' +======== + +The 'ms' ("manuscript") package is suitable for the preparation of +letters, memoranda, reports, and books. These 'groff' macros feature +cover page and table of contents generation, automatically numbered +headings, several paragraph styles, a variety of text styling options, +footnotes, and multi-column page layouts. 'ms' supports the 'tbl', +'eqn', 'pic', and 'refer' preprocessors for inclusion of tables, +mathematical equations, diagrams, and standardized bibliographic +citations. This implementation is mostly compatible with the documented +interface and behavior of AT&T Unix Version 7 'ms'. Many extensions +from 4.2BSD (Berkeley) and Tenth Edition Research Unix have been +recreated. + +* Menu: + +* ms Introduction:: +* ms Document Structure:: +* ms Document Control Settings:: +* ms Document Description Macros:: +* ms Body Text:: +* ms Page Layout:: +* Differences from AT&T ms:: +* ms Legacy Features:: +* ms Naming Conventions:: + + +File: groff.info, Node: ms Introduction, Next: ms Document Structure, Prev: ms, Up: ms + +4.6.1 Introduction +------------------ + +The 'ms' macros are the oldest surviving package for 'roff' systems.(1) +(*note ms Introduction-Footnote-1::) While the 'man' package was +designed for brief reference documents, the 'ms' macros are also +suitable for longer works intended for printing and possible +publication. + +* Menu: + +* ms basic information:: + + +File: groff.info, Node: ms Introduction-Footnotes, Up: ms Introduction + + (1) While manual _pages_ are older, early ones used macros supplanted +by the 'man' package of Seventh Edition Unix (1979). 'ms' shipped with +Sixth Edition (1975) and was documented by Mike Lesk in a Bell Labs +internal memorandum. + + +File: groff.info, Node: ms basic information, Next: ms Document Structure, Prev: ms Introduction, Up: ms Introduction + +4.6.1.1 Basic information +......................... + +'ms' documents are plain text files; prepare them with your preferred +text editor. If you're in a hurry to start, know that 'ms' needs one of +its macros called at the beginning of a document so that it can +initialize. A "macro" is a formatting instruction to 'ms'. Put a macro +call on a line by itself. Use '.PP' if you want your paragraph's first +line to be indented, or '.LP' if you don't. + + After that, start typing normally. It is a good practice to start +each sentence on a new line, or to put two spaces after sentence-ending +punctuation, so that the formatter knows where the sentence boundaries +are. You can separate paragraphs with further paragraphing macros, or +with blank lines, and you can indent with tabs. When you need one of +the features mentioned earlier (*note ms::), return to this part of the +manual. + + Format the document with the 'groff' command. 'nroff' can be useful +for previewing. + + $ editor radical.ms + $ nroff -ww -z -ms radical.ms # check for errors + $ nroff -ms radical.ms | less -R + $ groff -T ps -ms radical.ms > radical.ps + $ see radical.ps + + Our 'radical.ms' document might look like this. + + .LP + Radical novelties are so disturbing that they tend to be + suppressed or ignored, to the extent that even the + possibility of their existence in general is more often + denied than admitted. + + ->That's what Dijkstra said, anyway. + + 'ms' exposes many aspects of document layout to user control via +'groff''s "registers" and "strings", which store numbers and text, +respectively. Measurements in 'groff' are expressed with a suffix +called a "scaling unit". + +'i' + inches + +'c' + centimeters + +'p' + points (1/72 inch) + +'P' + picas (1/6 inch) + +'v' + vees; current vertical spacing + +'m' + ems; width of an "M" in the current font + +'n' + ens; one-half em + + Set registers with the 'nr' request and strings with the 'ds' +request. "Requests" are like macro calls; they go on lines by +themselves and start with the "control character", a dot ('.'). The +difference is that they directly instruct the formatter program, rather +than the macro package. We'll discuss a few as applicable. It is wise +to specify a scaling unit when setting any register that represents a +length, size, or distance. + + .nr PS 10.5p \" Use 10.5-point type. + .ds FAM P \" Use Palatino font family. + +In the foregoing, we see that '\"' begins a comment. This is an example +of an "escape sequence", the other kind of formatting instruction. +Escape sequences can appear anywhere. They begin with the escape +character ('\') and are followed by at least one more character. 'ms' +documents tend to use only a few of 'groff''s many requests and escape +sequences; see *note Request Index:: and *note Escape Sequence Index:: +or the 'groff(7)' man page for complete lists. + +'\"' + Begin comment; ignore remainder of line. + +'\n[REG]' + Interpolate value of register REG. + +'\*[STR]' + Interpolate contents of string STR. + +'\*S' + abbreviation of '\*[S]'; the name S must be only one character + +'\[CHAR]' + Interpolate glyph of special character named CHAR. + +'\&' + dummy character + +'\~' + Insert an unbreakable space that is adjustable like a normal space. + +'\|' + Move horizontally by one-sixth em ("thin space"). + + Prefix any words that start with a dot '.' or neutral apostrophe ''' +with '\&' if they are at the beginning of an input line (or might become +that way in editing) to prevent them from being interpreted as macro +calls or requests. Suffix '.', '?', and '!' with '\&' when needed to +cancel end-of-sentence detection. + + My exposure was \&.5 to \&.6 Sv of neutrons, said Dr.\& + Wallace after the criticality incident. + + +File: groff.info, Node: ms Document Structure, Next: ms Document Control Settings, Prev: ms Introduction, Up: ms + +4.6.2 Document Structure +------------------------ + +The 'ms' macro package expects a certain amount of structure: a +well-formed document contains at least one paragraphing or heading macro +call. Longer documents have a structure as follows. + +*Document type* + Calling the 'RP' macro at the beginning of your document puts the + document description (see below) on a cover page. Otherwise, 'ms' + places the information (if any) on the first page, followed + immediately by the body text. Some document types found in other + 'ms' implementations are specific to AT&T or Berkeley, and are not + supported by 'groff' 'ms'. + +*Format and layout* + By setting registers and strings, you can configure your document's + typeface, margins, spacing, headers and footers, and footnote + arrangement. *Note ms Document Control Settings::. + +*Document description* + A document description consists of any of: a title, one or more + authors' names and affiliated institutions, an abstract, and a date + or other identifier. *Note ms Document Description Macros::. + +*Body text* + The main matter of your document follows its description (if any). + 'ms' supports highly structured text consisting of paragraphs + interspersed with multi-level headings (chapters, sections, + subsections, and so forth) and augmented by lists, footnotes, + tables, diagrams, and similar material. *Note ms Body Text::. + +*Tables of contents* + Macros enable the collection of entries for a table of contents (or + index) as the material they discuss appears in the document. You + then call a macro to emit the table of contents at the end of your + document. The table of contents must necessarily follow the rest + of the text since GNU 'troff' is a single-pass formatter; it thus + cannot determine the page number of a division of the text until it + has been set and output. Since 'ms' was designed for the + production of hard copy, the traditional procedure was to manually + relocate the pages containing the table of contents between the + cover page and the body text. Today, page resequencing is more + often done in the digital domain. An index works similarly, but + because it typically needs to be sorted after collection, its + preparation requires separate processing. + + +File: groff.info, Node: ms Document Control Settings, Next: ms Document Description Macros, Prev: ms Document Structure, Up: ms + +4.6.3 Document Control Settings +------------------------------- + +'ms' exposes many aspects of document layout to user control via 'groff' +requests. To use them, you must understand how to define registers and +strings. + + -- Request: .nr reg value + Set register REG to VALUE. If REG doesn't exist, GNU 'troff' + creates it. + + -- Request: .ds name contents + Set string NAME to CONTENTS. + + A list of document control registers and strings follows. For any +parameter whose default is unsatisfactory, define its register or string +before calling any 'ms' macro other than 'RP'. + +Margin settings +............... + + -- Register: \n[PO] + Defines the page offset (i.e., the left margin). + + Effective: next page. + + Default: Varies by output device and paper format; 1i is used for + typesetters using U.S. letter paper, and zero for terminals. *Note + Paper Format::. + + -- Register: \n[LL] + Defines the line length (i.e., the width of the body text). + + Effective: next paragraph. + + Default: Varies by output device and paper format; 6.5i is used for + typesetters using U.S. letter paper (*note Paper Format::) and 65n + on terminals. + + -- Register: \n[LT] + Defines the title line length (i.e., the header and footer width). + This is usually the same as 'LL', but need not be. + + Effective: next paragraph. + + Default: Varies by output device and paper format; 6.5i is used for + typesetters using U.S. letter paper (*note Paper Format::) and 65n + on terminals. + + -- Register: \n[HM] + Defines the header margin height at the top of the page. + + Effective: next page. + + Default: 1i. + + -- Register: \n[FM] + Defines the footer margin height at the bottom of the page. + + Effective: next page. + + Default: 1i. + +Titles (headers, footers) +......................... + + -- String: \*[LH] + Defines the text displayed in the left header position. + + Effective: next header. + + Default: empty. + + -- String: \*[CH] + Defines the text displayed in the center header position. + + Effective: next header. + + Default: '-\n[%]-'. + + -- String: \*[RH] + Defines the text displayed in the right header position. + + Effective: next header. + + Default: empty. + + -- String: \*[LF] + Defines the text displayed in the left footer position. + + Effective: next footer. + + Default: empty. + + -- String: \*[CF] + Defines the text displayed in the center footer position. + + Effective: next footer. + + Default: empty. + + -- String: \*[RF] + Defines the text displayed in the right footer position. + + Effective: next footer. + + Default: empty. + +Text settings +............. + + -- Register: \n[PS] + Defines the type size of the body text. + + Effective: next paragraph. + + Default: 10p. + + -- Register: \n[VS] + Defines the vertical spacing (type size plus leading). + + Effective: next paragraph. + + Default: 12p. + + -- Register: \n[HY] + Defines the automatic hyphenation mode used with the 'hy' request. + Setting 'HY' to 0 is equivalent to using the 'nh' request. This is + a Tenth Edition Research Unix extension. + + Effective: next paragraph. + + Default: 6. + + -- String: \*[FAM] + Defines the font family used to typeset the document. This is a + GNU extension. + + Effective: next paragraph. + + Default: defined by the output device; often 'T' (*note ms Body + Text::) + +Paragraph settings +.................. + + -- Register: \n[PI] + Defines the indentation amount used by the 'PP', 'IP' (unless + overridden by an optional argument), 'XP', and 'RS' macros. + + Effective: next paragraph. + + Default: 5n. + + -- Register: \n[PD] + Defines the space between paragraphs. + + Effective: next paragraph. + + Default: 0.3v (1v on low-resolution devices). + + -- Register: \n[QI] + Defines the indentation amount used on both sides of a paragraph + set with the 'QP' or between the 'QS' and 'QE' macros. + + Effective: next paragraph. + + Default: 5n. + + -- Register: \n[PORPHANS] + Defines the minimum number of initial lines of any paragraph that + must be kept together to avoid isolated lines at the bottom of a + page. If a new paragraph is started close to the bottom of a page, + and there is insufficient space to accommodate 'PORPHANS' lines + before an automatic page break, then a page break is forced before + the start of the paragraph. This is a GNU extension. + + Effective: next paragraph. + + Default: 1. + +Heading settings +................ + + -- Register: \n[PSINCR] + Defines an increment in type size to be applied to a heading at a + lesser depth than that specified in 'GROWPS'. The value of + 'PSINCR' should be specified in points with the p scaling unit and + may include a fractional component; for example, '.nr PSINCR 1.5p' + sets a type size increment of 1.5p. This is a GNU extension. + + Effective: next heading. + + Default: 1p. + + -- Register: \n[GROWPS] + Defines the heading depth above which the type size increment set + by 'PSINCR' becomes effective. For each heading depth less than + the value of 'GROWPS', the type size is increased by 'PSINCR'. + Setting 'GROWPS' to any value less than 2 disables the incremental + heading size feature. This is a GNU extension. + + Effective: next heading. + + Default: 0. + + -- Register: \n[HORPHANS] + Defines the minimum number of lines of an immediately succeeding + paragraph that should be kept together with any heading introduced + by the 'NH' or 'SH' macros. If a heading is placed close to the + bottom of a page, and there is insufficient space to accommodate + both the heading and at least 'HORPHANS' lines of the following + paragraph, before an automatic page break, then the page break is + forced before the heading. This is a GNU extension. + + Effective: next paragraph. + + Default: 1. + + -- String: \*[SN-STYLE] + Defines the style used to print numbered headings. *Note Headings + in ms::. This is a GNU extension. + + Effective: next heading. + + Default: alias of 'SN-DOT' + +Footnote settings +................. + + -- Register: \n[FI] + Defines the footnote indentation. This is a Berkeley extension. + + Effective: next footnote. + + Default: 2n. + + -- Register: \n[FF] + Defines the format of automatically numbered footnotes, and those + for which the 'FS' request is given a marker argument, at the + bottom of a column or page. This is a Berkeley extension. + '0' + Set an automatic number(1) (*note ms Document Control + Settings-Footnote-1::) as a superscript (on typesetter + devices) or surrounded by square brackets (on terminals). The + footnote paragraph is indented as with 'PP' if there is an + 'FS' argument or an automatic number, and as with 'LP' + otherwise. This is the default. + + '1' + As '0', but set the marker as regular text and follow an + automatic number with a period. + + '2' + As '1', but without indentation (like 'LP'). + + '3' + As '1', but set the footnote paragraph with the marker hanging + (like 'IP'). + + Effective: next footnote. + + Default: 0. + + -- Register: \n[FPS] + Defines the footnote type size. + + Effective: next footnote. + + Default: '\n[PS] - 2p'. + + -- Register: \n[FVS] + Defines the footnote vertical spacing. + + Effective: next footnote. + + Default: '\n[FPS] + 2p'. + + -- Register: \n[FPD] + Defines the footnote paragraph spacing. This is a GNU extension. + + Effective: next footnote. + + Default: '\n[PD] / 2'. + + -- String: \*[FR] + Defines the ratio of the footnote line length to the current line + length. This is a GNU extension. + + Effective: next footnote in single-column arrangements, next page + otherwise. + + Default: '11/12'. + +Display settings +................ + + -- Register: \n[DD] + Sets the display distance--the vertical spacing before and after a + display, a 'tbl' table, an 'eqn' equation, or a 'pic' image. This + is a Berkeley extension. + + Effective: next display boundary. + + Default: 0.5v (1v on low-resolution devices). + + -- Register: \n[DI] + Sets the default amount by which to indent a display started with + 'DS' and 'ID' without arguments, to '.DS I' without an indentation + argument, and to equations set with '.EQ I'. This is a GNU + extension. + + Effective: next indented display. + + Default: 0.5i. + +Other settings +.............. + + -- Register: \n[MINGW] + Defines the default minimum width between columns in a multi-column + document. This is a GNU extension. + + Effective: next page. + + Default: 2n. + + -- Register: \n[TC-MARGIN] + Defines the width of the field in which page numbers are set in a + table of contents entry; the right margin thus moves inboard by + this amount. This is a GNU extension. + + Effective: next 'PX' call. + + Default: '\w'000'' + + +File: groff.info, Node: ms Document Control Settings-Footnotes, Up: ms Document Control Settings + + (1) defined in *note ms Footnotes:: + + +File: groff.info, Node: ms Document Description Macros, Next: ms Body Text, Prev: ms Document Control Settings, Up: ms + +4.6.4 Document Description Macros +--------------------------------- + +Only the simplest document lacks a title.(1) (*note ms Document +Description Macros-Footnote-1::) As its level of sophistication (or +complexity) increases, it tends to acquire a date of revision, +explicitly identified authors, sponsoring institutions for authors, and, +at the rarefied heights, an abstract of its content. Define these data +by calling the macros below in the order shown; 'DA' or 'ND' can be +called to set the document date (or other identifier) at any time before +(a) the abstract, if present, or (b) its information is required in a +header or footer. Use of these macros is optional, except that 'TL' is +mandatory if any of 'RP', 'AU', 'AI', or 'AB' is called, and 'AE' is +mandatory if 'AB' is called. + + -- Macro: .RP [no-repeat-info] [no-renumber] + Use the "report" (AT&T: "released paper") format for your document, + creating a separate cover page. The default arrangement is to + place most of the document description (title, author names and + institutions, and abstract, but not the date) at the top of the + first page. If the optional 'no-repeat-info' argument is given, + 'ms' produces a cover page but does not repeat any of its + information subsequently (but see the 'DA' macro below regarding + the date). Normally, 'RP' sets the page number following the cover + page to 1. Specifying the optional 'no-renumber' argument + suppresses this alteration. Optional arguments can occur in any + order. 'no' is recognized as a synonym of 'no-repeat-info' for + 'AT&T' compatibility. + + -- Macro: .TL + Specify the document title. 'ms' collects text on input lines + following this call into the title until reaching 'AU', 'AB', or a + heading or paragraphing macro call. + + -- Macro: .AU + Specify an author's name. 'ms' collects text on input lines + following this call into the author's name until reaching 'AI', + 'AB', another 'AU', or a heading or paragraphing macro call. Call + it repeatedly to specify multiple authors. + + -- Macro: .AI + Specify the preceding author's institution. An 'AU' call is + usefully followed by at most one 'AI' call; if there are more, the + last 'AI' call controls. 'ms' collects text on input lines + following this call into the author's institution until reaching + 'AU', 'AB', or a heading or paragraphing macro call. + + -- Macro: .DA [x ...] + Typeset the current date, or any arguments X, in the center footer, + and, if 'RP' is also called, left-aligned at the end of the + description information on the cover page. + + -- Macro: .ND [x ...] + Typeset the current date, or any arguments X, if 'RP' is also + called, left-aligned at the end of the document description on the + cover page. This is 'groff' 'ms''s default. + + -- Macro: .AB [no] + Begin the abstract. 'ms' collects text on input lines following + this call into the abstract until reaching an 'AE' call. By + default, 'ms' places the word "ABSTRACT" centered and in italics + above the text of the abstract. The optional argument 'no' + suppresses this heading. + + -- Macro: .AE + End the abstract. + + An example document description, using a cover page, follows. + + .RP + .TL + The Inevitability of Code Bloat + in Commercial and Free Software + .AU + J.\& Random Luser + .AI + University of West Bumblefuzz + .AB + This report examines the long-term growth of the code + bases in two large, + popular software packages; + the free Emacs and the commercial Microsoft Word. + While differences appear in the type or order of + features added, + due to the different methodologies used, + the results are the same in the end. + .PP + The free software approach is shown to be superior in + that while free software can become as bloated as + commercial offerings, + free software tends to have fewer serious bugs and the + added features are more in line with user demand. + .AE + + ...the rest of the paper... + + +File: groff.info, Node: ms Document Description Macros-Footnotes, Up: ms Document Description Macros + + (1) Distinguish a document title from "titles", which are what 'roff' +systems call headers and footers collectively. + + +File: groff.info, Node: ms Body Text, Next: ms Page Layout, Prev: ms Document Description Macros, Up: ms + +4.6.5 Body Text +--------------- + +A variety of macros, registers, and strings can be used to structure and +style the body of your document. They organize your text into +paragraphs, headings, footnotes, and inclusions of material such as +tables and figures. + +* Menu: + +* Text settings in ms:: +* Typographical symbols in ms:: +* Paragraphs in ms:: +* Headings in ms:: +* Typeface and decoration:: +* Lists in ms:: +* Indented regions in ms:: +* ms keeps and displays:: +* ms Insertions:: +* ms Footnotes:: +* ms language and localization:: + + +File: groff.info, Node: Text settings in ms, Next: Typographical symbols in ms, Prev: ms Body Text, Up: ms Body Text + +4.6.5.1 Text settings +..................... + +The 'FAM' string, a GNU extension, sets the font family for body text; +the default is 'T'. The 'PS' and 'VS' registers set the type size and +vertical spacing (distance between text baselines), respectively. The +font family and type size are ignored on terminal devices. Setting +these parameters before the first call of a heading, paragraphing, or +(non-date) document description macro also applies them to headers, +footers, and (for 'FAM') footnotes. + + Which font families are available depends on the output device; as a +convention, 'T' selects a serif family ("Times"), 'H' a sans-serif +family ("Helvetica"), and 'C' a monospaced family ("Courier"). The man +page for the output driver documents its font repertoire. Consult the +'groff(1)' man page for lists of available output devices and their +drivers. + + The hyphenation mode (as used by the 'hy' request) is set from the +'HY' register. Setting 'HY' to '0' is equivalent to using the 'nh' +request. This is a Tenth Edition Research Unix extension. + + +File: groff.info, Node: Typographical symbols in ms, Next: Paragraphs in ms, Prev: Text settings in ms, Up: ms Body Text + +4.6.5.2 Typographical symbols +............................. + +'ms' provides a few strings to obtain typographical symbols not easily +entered with the keyboard. These and many others are available as +special character escape sequences--see the 'groff_char(7)' man page. + + -- String: \*[-] + Interpolate an em dash. + + -- String: \*[Q] + -- String: \*[U] + Interpolate typographer's quotation marks where available, and + neutral double quotes otherwise. '\*Q' is the left quote and '\*U' + the right. + + +File: groff.info, Node: Paragraphs in ms, Next: Headings in ms, Prev: Typographical symbols in ms, Up: ms Body Text + +4.6.5.3 Paragraphs +.................. + +Paragraphing macros "break", or terminate, any pending output line so +that a new paragraph can begin. Several paragraph types are available, +differing in how indentation applies to them: to left, right, or both +margins; to the first output line of the paragraph, all output lines, or +all but the first. All paragraphing macro calls cause the insertion of +vertical space in the amount stored in the 'PD' register, except at page +or column breaks. Alternatively, a blank input line breaks the output +line and vertically spaces by one vee. + + -- Macro: .LP + Set a paragraph without any (additional) indentation. + + -- Macro: .PP + Set a paragraph with a first-line left indentation in the amount + stored in the 'PI' register. + + -- Macro: .IP [marker [width]] + Set a paragraph with a left indentation. The optional MARKER is + not indented and is empty by default. It has several applications; + see *note Lists in ms::. WIDTH overrides the indentation amount + stored in the 'PI' register; its default unit is 'n'. Once + specified, WIDTH applies to further 'IP' calls until specified + again or a heading or different paragraphing macro is called. + + -- Macro: .QP + Set a paragraph indented from both left and right margins by the + amount stored in the 'QI' register. + + -- Macro: .QS + -- Macro: .QE + Begin ('QS') and end ('QE') a region where each paragraph is + indented from both margins by the amount stored in the 'QI' + register. The text between 'QS' and 'QE' can be structured further + by use of other paragraphing macros. + + -- Macro: .XP + Set an "exdented" paragraph--one with a left indentation in the + amount stored in the 'PI' register on every line _except_ the first + (also known as a hanging indent). This is a Berkeley extension. + + The following example illustrates the use of paragraphing macros. + + .NH 2 + Cases used in the 2001 study + .LP + Two software releases were considered for this report. + .PP + The first is commercial software; + the second is free. + .IP \[bu] + Microsoft Word for Windows, + starting with version 1.0 through the current version + (Word 2000). + .IP \[bu] + GNU Emacs, + from its first appearance as a standalone editor through + the current version (v20). + See [Bloggs 2002] for details. + .QP + Franklin's Law applied to software: + software expands to outgrow both RAM and disk space over + time. + .SH + Bibliography + .XP + Bloggs, Joseph R., + .I "Everyone's a Critic" , + Underground Press, March 2002. + A definitive work that answers all questions and + criticisms about the quality and usability of free + software. + + +File: groff.info, Node: Headings in ms, Next: Typeface and decoration, Prev: Paragraphs in ms, Up: ms Body Text + +4.6.5.4 Headings +................ + +Use headings to create a sequential or hierarchical structure for your +document. The 'ms' macros print headings in *bold* using the same font +family and, by default, type size as the body text. Headings are +available with and without automatic numbering. Text on input lines +following the macro call becomes the heading's title. Call a +paragraphing macro to end the heading text and start the section's +content. + + -- Macro: .NH [depth] + -- Macro: .NH S heading-depth-index ... + Set an automatically numbered heading. + + 'ms' produces a numbered heading the form A.B.C..., to any depth + desired, with the numbering of each depth increasing automatically + and being reset to zero when a more significant level is increased. + "1" is the most significant or coarsest division of the document. + Only non-zero values are output. If DEPTH is omitted, it is taken + to be '1'. + + If you specify DEPTH such that an ascending gap occurs relative to + the previous 'NH' call--that is, you "skip a depth", as by '.NH 1' + and then '.NH 3'--'groff' 'ms' emits a warning on the standard + error stream. + + Alternatively, you can give 'NH' a first argument of 'S', followed + by integers to number the heading depths explicitly. Further + automatic numbering, if used, resumes using the specified indices + as their predecessors. This feature is a Berkeley extension. + + An example may be illustrative. + + .NH 1 + Animalia + .NH 2 + Arthropoda + .NH 3 + Crustacea + .NH 2 + Chordata + .NH S 6 6 6 + Daimonia + .NH 1 + Plantae + + The above results in numbering as follows; the vertical space that +normally precedes each heading is omitted. + + 1. Animalia + 1.1. Arthropoda + 1.1.1. Crustacea + 1.2. Chordata + 6.6.6. Daimonia + 7. Plantae + + -- String: \*[SN-STYLE] + -- String: \*[SN-DOT] + -- String: \*[SN-NO-DOT] + -- String: \*[SN] + After 'NH' is called, the assigned number is made available in the + strings 'SN-DOT' (as it appears in a printed heading with default + formatting, followed by a terminating period) and 'SN-NO-DOT' (with + the terminating period omitted). These are GNU extensions. + + You can control the style used to print numbered headings by + defining an appropriate alias for the string 'SN-STYLE'. By + default, 'SN-STYLE' is aliased to 'SN-DOT'. If you prefer to omit + the terminating period from numbers appearing in numbered headings, + you may define the alias as follows. + + .als SN-STYLE SN-NO-DOT + + Any such change in numbering style becomes effective from the next + use of 'NH' following redefinition of the alias for 'SN-STYLE'. + The formatted number of the current heading is available in the + 'SN' string (a feature first documented by Berkeley), which + facilitates its inclusion in, for example, table captions, equation + labels, and 'XS'/'XA'/'XE' table of contents entries. + + -- Macro: .SH [depth] + Set an unnumbered heading. + + The optional DEPTH argument is a GNU extension indicating the + heading depth corresponding to the DEPTH argument of 'NH'. It + matches the type size at which the heading is set to that of a + numbered heading at the same depth when the 'GROWPS' and 'PSINCR' + heading size adjustment mechanism is in effect. + + If the 'GROWPS' register is set to a value greater than the LEVEL +argument to 'NH' or 'SH', the type size of a heading produced by these +macros increases by 'PSINCR' units over the size specified by 'PS' +multiplied by the difference of 'GROWPS' and LEVEL. The value stored in +'PSINCR' is interpreted in 'groff' basic units; the 'p' scaling unit +should be employed when assigning a value specified in points. For +example, the sequence + + .nr PS 10 + .nr GROWPS 3 + .nr PSINCR 1.5p + .NH 1 + Carnivora + .NH 2 + Felinae + .NH 3 + Felis catus + .SH 2 + Machairodontinae + +will cause "1. Carnivora" to be printed in 13-point text, followed by +"1.1. Felinae" in 11.5-point text, while "1.1.1. Felis catus" and all +more deeply nested heading levels will remain in the 10-point text +specified by the 'PS' register. "Machairodontinae" is printed at 11.5 +points, since it corresponds to heading level 2. + + The 'HORPHANS' register operates in conjunction with the 'NH' and +'SH' macros to inhibit the printing of isolated headings at the bottom +of a page; it specifies the minimum number of lines of an immediately +subsequent paragraph that must be kept on the same page as the heading. +If insufficient space remains on the current page to accommodate the +heading and this number of lines of paragraph text, a page break is +forced before the heading is printed. Any display macro call or 'tbl', +'pic', or 'eqn' region between the heading and the subsequent paragraph +suppresses this grouping. *Note ms keeps and displays:: and *note ms +Insertions::. + + +File: groff.info, Node: Typeface and decoration, Next: Lists in ms, Prev: Headings in ms, Up: ms Body Text + +4.6.5.5 Typeface and decoration +............................... + +The 'ms' macros provide a variety of ways to style text. Attend closely +to the ordering of arguments labeled PRE and POST, which is not +intuitive. Support for PRE arguments is a GNU extension.(1) (*note +Typeface and decoration-Footnote-1::) + + -- Macro: .B [text [post [pre]]] + Style TEXT in bold, followed by POST in the previous font style + without intervening space, and preceded by PRE similarly. Without + arguments, 'ms' styles subsequent text in bold until the next + paragraphing, heading, or no-argument typeface macro call. + + -- Macro: .R [text [post [pre]]] + As 'B', but use the roman style (upright text of normal weight) + instead of bold. Argument recognition is a GNU extension. + + -- Macro: .I [text [post [pre]]] + As 'B', but use an italic or oblique style instead of bold. + + -- Macro: .BI [text [post [pre]]] + As 'B', but use a bold italic or bold oblique style instead of + upright bold. This is a Tenth Edition Research Unix extension. + + -- Macro: .CW [text [post [pre]]] + As 'B', but use a constant-width (monospaced) roman typeface + instead of bold. This is a Tenth Edition Research Unix extension. + + -- Macro: .BX [text] + Typeset TEXT and draw a box around it. On terminal devices, + reverse video is used instead. If you want TEXT to contain space, + use unbreakable space or horizontal motion escape sequences ('\~', + '\<SP>', '\^', '\|', '\0' or '\h'). + + -- Macro: .UL [text [post]] + Typeset TEXT with an underline. POST, if present, is set after + TEXT with no intervening space. + + -- Macro: .LG + Set subsequent text in larger type (two points larger than the + current size) until the next type size, paragraphing, or heading + macro call. You can specify this macro multiple times to enlarge + the type size as needed. + + -- Macro: .SM + Set subsequent text in smaller type (two points smaller than the + current size) until the next type size, paragraphing, or heading + macro call. You can specify this macro multiple times to reduce + the type size as needed. + + -- Macro: .NL + Set subsequent text at the normal type size (the amount in the 'PS' + register). + + PRE and POST arguments are typically used to simplify the attachment +of punctuation to styled words. When PRE is used, a hyphenation control +escape sequence '\%' that would ordinarily start TEXT must start PRE +instead to have the desired effect. + + The CS course's students found one C language keyword + .CW static ) \%( + most troublesome. + + The foregoing example produces output as follows. + + The CS course's students found one C language keyword (static) + most troublesome. + + You can use the output line continuation escape sequence '\c' to +achieve the same result (*note Line Continuation::). It is also +portable to older 'ms' implementations. + + The CS course's students found one C language keyword + \%(\c + .CW \%static ) + most troublesome. + + 'groff' 'ms' also offers strings to begin and end super- and +subscripting. These are GNU extensions. + + -- String: \*[{] + -- String: \*[}] + Begin and end superscripting, respectively. + + -- String: \*[<] + -- String: \*[>] + Begin and end subscripting, respectively. + + Rather than calling the 'CW' macro, in 'groff' 'ms' you might prefer +to change the font family to Courier by setting the 'FAM' string to 'C'. +You can then use all four style macros above, returning to the default +family (Times) with '.ds FAM T'. Because changes to 'FAM' take effect +only at the next paragraph, 'CW' remains useful to "inline" a change to +the font family, similarly to the practice of this document in noting +syntactical elements of 'ms' and 'groff'. + + +File: groff.info, Node: Typeface and decoration-Footnotes, Up: Typeface and decoration + + (1) This idiosyncrasy arose through feature accretion; for example, +the 'B' macro in Version 6 Unix 'ms' (1975) accepted only one argument, +the text to be set in boldface. By Version 7 (1979) it recognized a +second argument; in 1990, 'groff' 'ms' added a "pre" argument, placing +it third to avoid breaking support for older documents. + + +File: groff.info, Node: Lists in ms, Next: Indented regions in ms, Prev: Typeface and decoration, Up: ms Body Text + +4.6.5.6 Lists +............. + +The MARKER argument to the 'IP' macro can be employed to present a +variety of lists; for instance, you can use a bullet glyph ('\[bu]') for +unordered lists, a number (or auto-incrementing register) for numbered +lists, or a word or phrase for glossary-style or definition lists. If +you set the paragraph indentation register 'PI' before calling 'IP', you +can later reorder the items in the list without having to ensure that a +WIDTH argument remains affixed to the first call. + + The following is an example of a bulleted list. + + .nr PI 2n + A bulleted list: + .IP \[bu] + lawyers + .IP \[bu] + guns + .IP \[bu] + money + + A bulleted list: + + * lawyers + + * guns + + * money + + The following is an example of a numbered list. + + .nr step 0 1 + .nr PI 3n + A numbered list: + .IP \n+[step] + lawyers + .IP \n+[step] + guns + .IP \n+[step] + money + + A numbered list: + + 1. lawyers + + 2. guns + + 3. money + + Here we have employed the 'nr' request to create a register of our +own, 'step'. We initialized it to zero and assigned it an +auto-increment of 1. Each time we use the escape sequence '\n+[PI]' +(note the plus sign), the formatter applies the increment just before +interpolating the register's value. Preparing the 'PI' register as well +enables us to rearrange the list without the tedium of updating macro +calls. + + The next example illustrates a glossary-style list. + + A glossary-style list: + .IP lawyers 0.4i + Two or more attorneys. + .IP guns + Firearms, + preferably large-caliber. + .IP money + Gotta pay for those + lawyers and guns! + + A glossary-style list: + + lawyers + Two or more attorneys. + + guns Firearms, preferably large-caliber. + + money + Gotta pay for those lawyers and guns! + + In the previous example, observe how the 'IP' macro places the +definition on the same line as the term if it has enough space. If this +is not what you want, there are a few workarounds we will illustrate by +modifying the example. First, you can use a 'br' request to force a +break after printing the term or label. + + .IP guns + .br + Firearms, + + Second, you could apply the '\p' escape sequence to force a break. +The space following the escape sequence is important; if you omit it, +'groff' prints the first word of the paragraph text on the same line as +the term or label (if it fits) _then_ breaks the line. + + .IP guns + \p Firearms, + + Finally, you may append a horizontal motion to the marker with the +'\h' escape sequence; using the same amount as the indentation will +ensure that the marker is too wide for 'groff' to treat it as "fitting" +on the same line as the paragraph text. + + .IP guns\h'0.4i' + Firearms, + + In each case, the result is the same. + + A glossary-style list: + + lawyers + Two or more attorneys. + + guns + Firearms, preferably large-caliber. + + money + Gotta pay for those lawyers and guns! + + +File: groff.info, Node: Indented regions in ms, Next: ms keeps and displays, Prev: Lists in ms, Up: ms Body Text + +4.6.5.7 Indented regions +........................ + +You may need to indent a region of text while otherwise formatting it +normally. Indented regions can be nested; you can change '\n[PI]' +before each call to vary the amount of inset. + + -- Macro: .RS + Begin a region where headings, paragraphs, and displays are + indented (further) by the amount stored in the 'PI' register. + + -- Macro: .RE + End the (next) most recent indented region. + + This feature enables you to easily line up text under hanging and +indented paragraphs. For example, you may wish to structure lists +hierarchically. + + .IP \[bu] 2 + Lawyers: + .RS + .IP \[bu] + Dewey, + .IP \[bu] + Cheatham, + and + .IP \[bu] + and Howe. + .RE + .IP \[bu] + Guns + + * Lawyers: + + * Dewey, + + * Cheatham, and + + * Howe. + + * Guns + + +File: groff.info, Node: ms keeps and displays, Next: ms Insertions, Prev: Indented regions in ms, Up: ms Body Text + +4.6.5.8 Keeps, boxed keeps, and displays +........................................ + +On occasion, you may want to "keep" several lines of text, or a region +of a document, together on a single page, preventing an automatic page +break within certain boundaries. This can cause a page break to occur +earlier than it normally would. For example, you may want to keep two +paragraphs together, or a paragraph that refers to a table, list, or +figure adjacent to the item it discusses. 'ms' provides the 'KS' and +'KE' macros for this purpose. + + You can alternatively specify a "floating keep": if a keep cannot fit +on the current page, 'ms' holds its contents and allows material +following the keep (in the source document) to fill the remainder of the +current page. When the page breaks, whether by reaching the end or 'bp' +request, 'ms' puts the floating keep at the beginning of the next page. +This is useful for placing large graphics or tables that do not need to +appear exactly where they occur in the source document. + + -- Macro: .KS + -- Macro: .KF + -- Macro: .KE + 'KS' begins a keep, 'KF' a floating keep, and 'KE' ends a keep of + either kind. + + As an alternative to the keep mechanism, the 'ne' request forces a +page break if there is not at least the amount of vertical space +specified in its argument remaining on the page (*note Page Control::). +One application of 'ne' is to reserve space on the page for a figure or +illustration to be included later. + + A "boxed keep" has a frame drawn around it. + + -- Macro: .B1 + -- Macro: .B2 + 'B1' begins a keep with a box drawn around it. 'B2' ends a boxed + keep. + + Boxed keep macros cause breaks; if you need to box a word or phrase +within a line, see the 'BX' macro in *note Typeface and decoration::. +Box lines are drawn as close as possible to the text they enclose so +that they are usable within paragraphs. If you wish to box one or more +paragraphs, you may improve the appearance by calling 'B1' after the +first paragraphing macro, and by adding a small amount of vertical space +before calling 'B2'. + + .LP + .B1 + .I Warning: + Happy Fun Ball may suddenly accelerate to dangerous + speeds. + .sp \n[PD]/2 \" space by half the inter-paragraph distance + .B2 + + If you want a boxed keep to float, you will need to enclose the 'B1' +and 'B2' calls within a pair of 'KF' and 'KE' calls. + + "Displays" turn off filling; lines of verse or program code are shown +with their lines broken as in the source document without requiring 'br' +requests between lines. Displays can be kept on a single page or +allowed to break across pages. The 'DS' macro begins a kept display of +the layout specified in its first argument; non-kept displays are begun +with dedicated macros corresponding to their layout. + + -- Macro: .DS L + -- Macro: .LD + Begin ('DS': kept) left-aligned display. + + -- Macro: .DS [I [indent]] + -- Macro: .ID [indent] + Begin ('DS': kept) display indented by INDENT if specified, and by + the amount of the 'DI' register otherwise. + + -- Macro: .DS B + -- Macro: .BD + Begin a ('DS': kept) a block display: the entire display is + left-aligned, but indented such that the longest line in the + display is centered on the page. + + -- Macro: .DS C + -- Macro: .CD + Begin a ('DS': kept) centered display: each line in the display is + centered. + + -- Macro: .DS R + -- Macro: .RD + Begin a ('DS': kept) right-aligned display. This is a GNU + extension. + + -- Macro: .DE + End any display. + + The distance stored in the 'DD' register is inserted before and after +each pair of display macros; this is a Berkeley extension. In 'groff' +'ms', this distance replaces any adjacent inter-paragraph distance or +subsequent spacing prior to a section heading. The 'DI' register is a +GNU extension; its value is an indentation applied to displays created +with '.DS' and '.ID' without arguments, to '.DS I' without an +indentation argument, and to indented equations set with '.EQ'. Changes +to either register take effect at the next display boundary. + + +File: groff.info, Node: ms Insertions, Next: ms Footnotes, Prev: ms keeps and displays, Up: ms Body Text + +4.6.5.9 Tables, figures, equations, and references +.................................................. + +The 'ms' package is often used with the 'tbl', 'pic', 'eqn', and 'refer' +preprocessors. Mark text meant for preprocessors by enclosing it in +pairs of tokens as follows, with nothing between the dot and the macro +name. The preprocessors match these tokens only at the start of an +input line. + + -- Macro: .TS [H] + -- Macro: .TE + Demarcate a table to be processed by the 'tbl' preprocessor. The + optional argument 'H' to 'TS' instructs 'ms' to repeat table rows + (often column headings) at the top of each new page the table + spans, if applicable; calling the 'TH' macro marks the end of such + rows. The GNU 'tbl(1)' man page provides a comprehensive reference + to the preprocessor and offers examples of its use. + + -- Macro: .PS + -- Macro: .PE + -- Macro: .PF + 'PS' begins a picture to be processed by the 'gpic' preprocessor; + either of 'PE' or 'PF' ends it, the latter with "flyback" to the + vertical position at its top. You can create 'pic' input manually + or with a program such as 'xfig'. + + -- Macro: .EQ [align [label]] + -- Macro: .EN + Demarcate an equation to be processed by the 'eqn' preprocessor. + The equation is centered by default; ALIGN can be 'C', 'L', or 'I' + to (explicitly) center, left-align, or indent it by the amount + stored in the 'DI' register, respectively. If specified, LABEL is + set right-aligned. + + -- Macro: .[ + -- Macro: .] + Demarcate a bibliographic citation to be processed by the 'refer' + preprocessor. The GNU 'refer(1)' man page provides a comprehensive + reference to the preprocessor and the format of its bibliographic + database. Type 'man refer' at the command line to view it. + + When 'refer' emits collected references (as might be done on a "Works +Cited" page), it interpolates the 'REFERENCES' string as an unnumbered +heading ('SH'). + + The following is an example of how to set up a table that may print +across two or more pages. + + .TS H + allbox; + Cb | Cb . + Part->Description + _ + .TH + .T& + GH-1978->Fribulating gonkulator + ...the rest of the table follows... + .TE + +Attempting to place a multi-page table inside a keep can lead to +unpleasant results, particularly if the 'tbl' 'allbox' option is used. + + Mathematics can be typeset using the language of the 'eqn' +preprocessor. + + .EQ C (\*[SN-NO-DOT]a) + p ~ = ~ q sqrt { ( 1 + ~ ( x / q sup 2 ) } + .EN + +This input formats a labelled equation. We used the 'SN-NO-DOT' string +to base the equation label on the current heading number, giving us more +flexibility to reorganize the document. + + Use 'groff' options to run preprocessors on the input: '-e' for +'geqn', '-p' for 'gpic', '-R' for 'grefer', and '-t' for 'gtbl'. + + +File: groff.info, Node: ms Footnotes, Prev: ms Insertions, Up: ms Body Text + +4.6.5.10 Footnotes +.................. + +A footnote is typically anchored to a place in the text with a "marker", +which is a small integer, a symbol such as a dagger, or arbitrary +user-specified text. + + -- String: \*[*] + Place an "automatic number", an automatically generated numeric + footnote marker, in the text. Each time this string is + interpolated, the number it produces increments by one. Automatic + numbers start at 1. This is a Berkeley extension. + + Enclose the footnote text in 'FS' and 'FE' macro calls to set it at +the nearest available "foot", or bottom, of a text column or page. + + -- Macro: .FS [marker] + -- Macro: .FE + Begin ('FS') and end ('FE') a footnote. 'FS' calls 'FS-MARK' with + any supplied MARKER argument, which is then also placed at the + beginning of the footnote text. If MARKER is omitted, the next + pending automatic footnote number enqueued by interpolation of the + '*' string is used, and if none exists, nothing is prefixed. + + You may not desire automatically numbered footnotes in spite of their +convenience. You can indicate a footnote with a symbol or other text by +specifying its marker at the appropriate place (for example, by using +'\[dg]' for the dagger glyph) _and_ as an argument to the 'FS' macro. +Such manual marks should be repeated as arguments to 'FS' or as part of +the footnote text to disambiguate their correspondence. You may wish to +use '\*{' and '\*}' to superscript the marker at the anchor point, in +the footnote text, or both. + + 'groff' 'ms' provides a hook macro, 'FS-MARK', for user-determined +operations to be performed when the 'FS' macro is called. It is passed +the same arguments as 'FS' itself. An application of 'FS-MARK' is +anchor placement for a hyperlink reference, so that a footnote can link +back to its referential context.(1) (*note ms Footnotes-Footnote-1::) +By default, this macro has an empty definition. 'FS-MARK' is a GNU +extension. + + Footnotes can be safely used within keeps and displays, but you +should avoid using automatically numbered footnotes within floating +keeps. You can place a second '\**' interpolation between a '\**' and +its corresponding 'FS' call as long as each 'FS' call occurs _after_ the +corresponding '\**' and occurrences of 'FS' are in the same order as +corresponding occurrences of '\**'. + + Footnote text is formatted as paragraphs are, using analogous +parameters. The registers 'FI', 'FPD', 'FPS', and 'FVS' correspond to +'PI', 'PD', 'PS', and 'CS', respectively; 'FPD', 'FPS', and 'FVS' are +GNU extensions. + + The 'FF' register controls the formatting of automatically numbered +footnote paragraphs and those for which 'FS' is given a marker argument. +*Note ms Document Control Settings::. + + The default footnote line length is 11/12ths of the normal line +length for compatibility with the expectations of historical 'ms' +documents; you may wish to set the 'FR' string to '1' to align with +contemporary typesetting practices. In the past,(2) (*note ms +Footnotes-Footnote-2::) an 'FL' register was used for the line length in +footnotes; however, setting this register at document initialization +time had no effect on the footnote line length in multi-column +arrangements.(3) (*note ms Footnotes-Footnote-3::) + + 'FR' should be used in preference to the old 'FL' register in +contemporary documents. The footnote line length is effectively +computed as 'column-width * \*[FR]'. If an absolute footnote line +length is required, recall that arithmetic expressions in 'roff' input +are evaluated strictly from left to right, with no operator precedence +(parentheses are honored). + + .ds FR 0+3i \" Set footnote line length to 3 inches. + + +File: groff.info, Node: ms Footnotes-Footnotes, Up: ms Footnotes + + (1) "Portable Document Format Publishing with GNU Troff", +'pdfmark.ms' in the 'groff' distribution, uses this technique. + + (2) Unix Version 7 'ms', its descendants, and GNU 'ms' prior to +'groff' version 1.23.0 + + (3) You could reset it after each call to '.1C', '.2C', or '.MC'. + + +File: groff.info, Node: ms language and localization, Next: ms Page Layout, Prev: ms Footnotes, Up: ms Body Text + +4.6.5.11 Language and localization +.................................. + +'groff' 'ms' provides several strings that you can customize for your +own purposes, or redefine to adapt the macro package to languages other +than English. It is already localized for Czech, German, French, +Italian, and Swedish. Load the desired localization macro package after +'ms'; see the 'groff_tmac(5)' man page. + + $ groff -ms -mfr bienvenue.ms + + The following strings are available. + + -- String: \*[REFERENCES] + Contains the string printed at the beginning of a references + (bibliography) page produced with GNU 'refer(1)'. The default is + 'References'. + + -- String: \*[ABSTRACT] + Contains the string printed at the beginning of the abstract. The + default is '\f[I]ABSTRACT\f[]'; it includes font selection escape + sequences to set the word in italics. + + -- String: \*[TOC] + Contains the string printed at the beginning of the table of + contents. The default is 'Table of Contents'. + + -- String: \*[MONTH1] + -- String: \*[MONTH2] + -- String: \*[MONTH3] + -- String: \*[MONTH4] + -- String: \*[MONTH5] + -- String: \*[MONTH6] + -- String: \*[MONTH7] + -- String: \*[MONTH8] + -- String: \*[MONTH9] + -- String: \*[MONTH10] + -- String: \*[MONTH11] + -- String: \*[MONTH12] + Contain the full names of the calendar months. The defaults are in + English: 'January', 'February', and so on. + + +File: groff.info, Node: ms Page Layout, Next: Differences from AT&T ms, Prev: ms Body Text, Up: ms + +4.6.6 Page layout +----------------- + +'ms''s default page layout arranges text in a single column with the +page number between hyphens centered in a header on each page except the +first, and produces no footers. You can customize this arrangement. + +* Menu: + +* ms Headers and Footers:: +* Tab Stops in ms:: +* ms Margins:: +* ms Multiple Columns:: +* ms TOC:: + + +File: groff.info, Node: ms Headers and Footers, Next: Tab Stops in ms, Prev: ms Page Layout, Up: ms Page Layout + +4.6.6.1 Headers and footers +........................... + +There are multiple ways to produce headers and footers. One is to +define the strings 'LH', 'CH', and 'RH' to set the left, center, and +right headers, respectively; and 'LF', 'CF', and 'RF' to set the left, +center, and right footers. This approach suffices for documents that do +not distinguish odd- and even-numbered pages. + + Another method is to call macros that set headers or footers for odd- +or even-numbered pages. Each such macro takes a delimited argument +separating the left, center, and right header or footer texts from each +other. You can replace the neutral apostrophes (''') shown below with +any character not appearing in the header or footer text. These macros +are Berkeley extensions. + + -- Macro: .OH 'left'center'right' + -- Macro: .EH 'left'center'right' + -- Macro: .OF 'left'center'right' + -- Macro: .EF 'left'center'right' + The 'OH' and 'EH' macros define headers for odd- (recto) and + even-numbered (verso) pages, respectively; the 'OF' and 'EF' macros + define footers for them. + + With either method, a percent sign '%' in header or footer text is +replaced by the current page number. By default, 'ms' places no header +on a page numbered "1" (regardless of its number format). + + -- Macro: .P1 + Typeset the header even on page 1. To be effective, this macro + must be called before the header trap is sprung on any page + numbered "1"; in practice, unless your page numbering is unusual, + this means that you should call it early, before 'TL' or any + heading or paragraphing macro. This is a Berkeley extension. + + For even greater flexibility, 'ms' is designed to permit the +redefinition of the macros that are called when the 'groff' traps that +ordinarily cause the headers and footers to be output are sprung. 'PT' +("page trap") is called by 'ms' when the header is to be written, and +'BT' ("bottom trap") when the footer is to be. The 'groff' page +location trap that 'ms' sets up to format the header also calls the +(normally undefined) 'HD' macro after 'PT'; you can define 'HD' if you +need additional processing after setting the header (for example, to +draw a line below it). The 'HD' hook is a Berkeley extension. Any such +macros you (re)define must implement any desired specialization for +odd-, even-, or first numbered pages. + + +File: groff.info, Node: Tab Stops in ms, Next: ms Margins, Prev: ms Headers and Footers, Up: ms Page Layout + +4.6.6.2 Tab stops +................. + +Use the 'ta' request to define tab stops as needed. *Note Tabs and +Fields::. + + -- Macro: .TA + Reset the tab stops to the 'ms' default (every 5 ens). Redefine + this macro to create a different set of default tab stops. + + +File: groff.info, Node: ms Margins, Next: ms Multiple Columns, Prev: Tab Stops in ms, Up: ms Page Layout + +4.6.6.3 Margins +............... + +Control margins using the registers summarized in "Margin settings" in +*note ms Document Control Settings:: above. There is no setting for the +right margin; the combination of page offset '\n[PO]' and line length +'\n[LL]' determines it. + + +File: groff.info, Node: ms Multiple Columns, Next: ms TOC, Prev: ms Margins, Up: ms Page Layout + +4.6.6.4 Multiple columns +........................ + +'ms' can set text in as many columns as reasonably fit on the page. The +following macros force a page break if a multi-column layout is active +when they are called. The 'MINGW' register stores the default minimum +gutter width; it is a GNU extension. When multiple columns are in use, +keeps and the 'HORPHANS' and 'PORPHANS' registers work with respect to +column breaks instead of page breaks. + + -- Macro: .1C + Arrange page text in a single column (the default). + + -- Macro: .2C + Arrange page text in two columns. + + -- Macro: .MC [column-width [gutter-width]] + Arrange page text in multiple columns. If you specify no + arguments, it is equivalent to the '2C' macro. Otherwise, + COLUMN-WIDTH is the width of each column and GUTTER-WIDTH is the + minimum distance between columns. + + +File: groff.info, Node: ms TOC, Next: Differences from AT&T ms, Prev: ms Multiple Columns, Up: ms Page Layout + +4.6.6.5 Creating a table of contents +.................................... + +Because 'roff' formatters process their input in a single pass, material +on page 50, for example, cannot influence what appears on page 1--this +poses a challenge for a table of contents at its traditional location in +front matter, if you wish to avoid manually maintaining it. 'ms' +enables the collection of material to be presented in the table of +contents as it appears, saving its page number along with it, and then +emitting the collected contents on demand toward the end of the +document. The table of contents can then be resequenced to its desired +location by physically rearranging the pages of a printed document, or +as part of post-processing--with a 'sed(1)' script to reorder the pages +in 'troff''s output, with 'pdfjam(1)', or with 'gropdf(1)''s +'.pdfswitchtopage' feature, for example. + + Define an entry to appear in the table of contents by bracketing its +text between calls to the 'XS' and 'XE' macros. A typical application +is to call them immediately after 'NH' or 'SH' and repeat the heading +text within them. The 'XA' macro, used within '.XS'/'.XE' pairs, +supplements an entry--for instance, when it requires multiple output +lines, whether because a heading is too long to fit or because style +dictates that page numbers not be repeated. You may wish to indent the +text thus wrapped to correspond to its heading depth; this can be done +in the entry text by prefixing it with tabs or horizontal motion escape +sequences, or by providing a second argument to the 'XA' macro. 'XS' +and 'XA' automatically associate the page number where they are called +with the text following them, but they accept arguments to override this +behavior. At the end of the document, call 'TC' or 'PX' to emit the +table of contents; 'TC' resets the page number to 'i' (Roman numeral +one), and then calls 'PX'. All of these macros are Berkeley extensions. + + -- Macro: .XS [page-number] + -- Macro: .XA [page-number [indentation]] + -- Macro: .XE + Begin, supplement, and end a table of contents entry. Each entry + is associated with PAGE-NUMBER (otherwise the current page number); + a PAGE-NUMBER of 'no' prevents a leader and page number from being + emitted for that entry. Use of 'XA' within 'XS'/'XE' is optional; + it can be repeated. If INDENTATION is present, a supplemental + entry is indented by that amount; ens are assumed if no unit is + indicated. Text on input lines between 'XS' and 'XE' is stored for + later recall by 'PX'. + + -- Macro: .PX [no] + Switch to single-column layout. Unless 'no' is specified, center + and interpolate the 'TOC' string in bold and two points larger than + the body text. Emit the table of contents entries. + + -- Macro: .TC [no] + Set the page number to 1, the page number format to lowercase Roman + numerals, and call 'PX' (with a 'no' argument, if present). + + Here's an example of typical 'ms' table of contents preparation. We +employ horizontal escape sequences '\h' to indent the entries by +sectioning depth. + + .NH 1 + Introduction + .XS + Introduction + .XE + ... + .NH 2 + Methodology + .XS + \h'2n'Methodology + .XA + \h'4n'Fassbinder's Approach + \h'4n'Kahiu's Approach + .XE + ... + .NH 1 + Findings + .XS + Findings + .XE + ... + .TC + + The remaining features in this subsubsection are GNU extensions. +'groff' 'ms' obviates the need to repeat heading text after 'XS' calls. +Call 'XN' and 'XH' after 'NH' and 'SH', respectively. + + -- Macro: .XN heading-text + -- Macro: .XH depth heading-text + Format HEADING-TEXT and create a corresponding table of contents + entry. 'XN' computes the indentation from the depth of the + preceding 'NH' call; 'XH' requires a DEPTH argument to do so. + + 'groff' 'ms' encourages customization of table of contents entry +production. + + -- Macro: .XN-REPLACEMENT heading-text + -- Macro: .XH-REPLACEMENT depth heading-text + These hook macros implement 'XN' and 'XH', respectively. They call + 'XN-INIT' and pass their HEADING-TEXT arguments to 'XH-UPDATE-TOC'. + + -- Macro: .XN-INIT + -- Macro: .XH-UPDATE-TOC depth heading-text + The 'XN-INIT' hook macro does nothing by default. 'XH-UPDATE-TOC' + brackets HEADING-TEXT with 'XS' and 'XE' calls, indenting it by 2 + ens per level of DEPTH beyond the first. + + We could therefore produce a table of contents similar to that in the +previous example with fewer macro calls. (The difference is that this +input follows the "Approach" entries with leaders and page numbers.) + + .NH 1 + .XN Introduction + ... + .NH 2 + .XN Methodology + .XH 3 "Fassbinder's Approach" + .XH 3 "Kahiu's Approach" + ... + .NH 1 + .XN Findings + ... + + To get the section number of the numbered headings into the table of +contents entries, we might define 'XN-REPLACEMENT' as follows. (We +obtain the heading depth from 'groff' 'ms''s internal register 'nh*hl'.) + + .de XN-REPLACEMENT + .XN-INIT + .XH-UPDATE-TOC \\n[nh*hl] \\$@ + \&\\*[SN] \\$* + .. + + You can change the style of the leader that bridges each table of +contents entry with its page number; define the 'TC-LEADER' special +character by using the 'char' request. A typical leader combines the +dot glyph '.' with a horizontal motion escape sequence to spread the +dots. The width of the page number field is stored in the 'TC-MARGIN' +register. + + +File: groff.info, Node: Differences from AT&T ms, Next: ms Naming Conventions, Prev: ms Page Layout, Up: ms + +4.6.7 Differences from AT&T 'ms' +-------------------------------- + +The 'groff' 'ms' macros are an independent reimplementation, using no +AT&T code. Since they take advantage of the extended features of +'groff', they cannot be used with AT&T 'troff'. 'groff' 'ms' supports +features described above as Berkeley and Tenth Edition Research Unix +extensions, and adds several of its own. + + * The internals of 'groff' 'ms' differ from the internals of AT&T + 'ms'. Documents that depend upon implementation details of AT&T + 'ms' may not format properly with 'groff' 'ms'. Such details + include macros whose function was not documented in the AT&T 'ms' + manual.(1) (*note Differences from AT&T ms-Footnote-1::) + + * The error-handling policy of 'groff' 'ms' is to detect and report + errors, rather than to ignore them silently. + + * Tenth Edition Research Unix supported 'P1'/'P2' macros to bracket + code examples; 'groff' 'ms' does not. + + * 'groff' 'ms' does not work in GNU 'troff''s AT&T compatibility + mode. If loaded when that mode is enabled, it aborts processing + with a diagnostic message. + + * Multiple line spacing is not supported. Use a larger vertical + spacing instead. + + * 'groff' 'ms' uses the same header and footer defaults in both + 'nroff' and 'troff' modes as AT&T 'ms' does in 'troff' mode; AT&T's + default in 'nroff' mode is to put the date, in U.S. traditional + format (e.g., "January 1, 2021"), in the center footer (the 'CF' + string). + + * Many 'groff' 'ms' macros, including those for paragraphs, headings, + and displays, cause a reset of paragraph rendering parameters, and + may change the indentation; they do so not by incrementing or + decrementing it, but by setting it absolutely. This can cause + problems for documents that define additional macros of their own + that try to manipulate indentation. Use the 'ms' 'RS' and 'RE' + macros instead of the 'in' request. + + * AT&T 'ms' interpreted the values of the registers 'PS' and 'VS' in + points, and did not support the use of scaling units with them. + 'groff' 'ms' interprets values of the registers 'PS', 'VS', 'FPS', + and 'FVS' equal to or larger than 1,000 (one thousand) as decimal + fractions multiplied by 1,000.(2) (*note Differences from AT&T + ms-Footnote-2::) This threshold makes use of a scaling unit with + these parameters practical for high-resolution devices while + preserving backward compatibility. It also permits expression of + non-integral type sizes. For example, 'groff -rPS=10.5p' at the + shell prompt is equivalent to placing '.nr PS 10.5p' at the + beginning of the document. + + * AT&T 'ms''s 'AU' macro supported arguments used with some document + types; 'groff' 'ms' does not. + + * Right-aligned displays are available. The AT&T 'ms' manual + observes that "it is tempting to assume that '.DS R' will right + adjust lines, but it doesn't work". In 'groff' 'ms', it does. + + * To make 'groff' 'ms' use the default page offset (which also + specifies the left margin), the 'PO' register must stay undefined + until the first 'ms' macro is called. + + This implies that '\n[PO]' should not be used early in the + document, unless it is changed also: accessing an undefined + register automatically defines it. + + * 'groff' 'ms' supports the 'PN' register, but it is not necessary; + you can access the page number via the usual '%' register and + invoke the 'af' request to assign a different format to it if + desired.(3) (*note Differences from AT&T ms-Footnote-3::) + + * The AT&T 'ms' manual documents registers 'CW' and 'GW' as setting + the default column width and "intercolumn gap", respectively, and + which applied when 'MC' was called with fewer than two arguments. + 'groff' 'ms' instead treats 'MC' without arguments as synonymous + with '2C'; there is thus no occasion for a default column width + register. Further, the 'MINGW' register and the second argument to + 'MC' specify a _minimum_ space between columns, not the fixed + gutter width of AT&T 'ms'. + + * The AT&T 'ms' manual did not document the 'QI' register; Berkeley + and 'groff' 'ms' do. + + -- Register: \n[GS] + The register 'GS' is set to 1 by the 'groff' 'ms' macros, but is + not used by the AT&T 'ms' package. Documents that need to + determine whether they are being formatted with 'groff' 'ms' or + another implementation should test this register. + +* Menu: + +* Missing Unix Version 7 ms Macros:: + + +File: groff.info, Node: Differences from AT&T ms-Footnotes, Up: Differences from AT&T ms + + (1) 'Typing Documents on the UNIX System: Using the -ms Macros with +Troff and Nroff', M. E. Lesk, Bell Laboratories, 1978 + + (2) Register values are converted to and stored as basic units. +*Note Measurements::. + + (3) If you redefine the 'ms' 'PT' macro and desire special treatment +of certain page numbers (like '1'), you may need to handle a non-Arabic +page number format, as 'groff' 'ms''s 'PT' does; see the macro package +source. 'groff' 'ms' aliases the 'PN' register to '%'. + + +File: groff.info, Node: Missing Unix Version 7 ms Macros, Prev: Differences from AT&T ms, Up: Differences from AT&T ms + +4.6.7.1 Unix Version 7 'ms' macros not implemented by 'groff' 'ms' +.................................................................. + +Several macros described in the Unix Version 7 'ms' documentation are +unimplemented by 'groff' 'ms' because they are specific to the +requirements of documents produced internally by Bell Laboratories, some +of which also require a glyph for the Bell System logo that 'groff' does +not support. These macros implemented several document type formats +('EG', 'IM', 'MF', 'MR', 'TM', 'TR'), were meaningful only in +conjunction with the use of certain document types ('AT', 'CS', 'CT', +'OK', 'SG'), stored the postal addresses of Bell Labs sites ('HO', 'IH', +'MH', 'PY', 'WH'), or lacked a stable definition over time ('UX'). To +compatibly render historical 'ms' documents using these macros, we +advise your documents to invoke the 'rm' request to remove any such +macros it uses and then define replacements with an authentically +typeset original at hand.(1) (*note Missing Unix Version 7 ms +Macros-Footnote-1::) For informal purposes, a simple definition of 'UX' +should maintain the readability of the document's substance. + + .rm UX + .ds UX Unix\" + + +File: groff.info, Node: Missing Unix Version 7 ms Macros-Footnotes, Up: Missing Unix Version 7 ms Macros + + (1) The removal beforehand is necessary because 'groff' 'ms' aliases +these macros to a diagnostic macro, and you want to redefine the aliased +name, not its target. + + +File: groff.info, Node: ms Legacy Features, Next: ms Naming Conventions, Prev: Differences from AT&T ms, Up: ms + +4.6.8 Legacy Features +--------------------- + +'groff' 'ms' retains some legacy features solely to support formatting +of historical documents; contemporary ones should not use them because +they can render poorly. See the 'groff_char(7)' man page. + +AT&T accent mark strings +........................ + +AT&T 'ms' defined accent mark strings as follows. + + -- String: \*['] + Apply acute accent to subsequent glyph. + + -- String: \*[`] + Apply grave accent to subsequent glyph. + + -- String: \*[:] + Apply dieresis (umlaut) to subsequent glyph. + + -- String: \*[^] + Apply circumflex accent to subsequent glyph. + + -- String: \*[~] + Apply tilde accent to subsequent glyph. + + -- String: \*[C] + Apply caron to subsequent glyph. + + -- String: \*[,] + Apply cedilla to subsequent glyph. + +Berkeley accent mark and glyph strings +...................................... + +Berkeley 'ms' offered an 'AM' macro; calling it redefined the AT&T +accent mark strings (except for '\*C'), applied them to the _preceding_ +glyph, and defined additional strings, some for spacing glyphs. + + -- Macro: .AM + Enable alternative accent mark and glyph-producing strings. + + -- String: \*['] + Apply acute accent to preceding glyph. + + -- String: \*[`] + Apply grave accent to preceding glyph. + + -- String: \*[:] + Apply dieresis (umlaut) to preceding glyph. + + -- String: \*[^] + Apply circumflex accent to preceding glyph. + + -- String: \*[~] + Apply tilde accent to preceding glyph. + + -- String: \*[,] + Apply cedilla to preceding glyph. + + -- String: \*[/] + Apply stroke (slash) to preceding glyph. + + -- String: \*[v] + Apply caron to preceding glyph. + + -- String: \*[_] + Apply macron to preceding glyph. + + -- String: \*[.] + Apply underdot to preceding glyph. + + -- String: \*[o] + Apply ring accent to preceding glyph. + + -- String: \*[?] + Interpolate inverted question mark. + + -- String: \*[!] + Interpolate inverted exclamation mark. + + -- String: \*[8] + Interpolate small letter sharp s. + + -- String: \*[q] + Interpolate small letter o with hook accent (ogonek). + + -- String: \*[3] + Interpolate small letter yogh. + + -- String: \*[d-] + Interpolate small letter eth. + + -- String: \*[D-] + Interpolate capital letter eth. + + -- String: \*[th] + Interpolate small letter thorn. + + -- String: \*[Th] + Interpolate capital letter thorn. + + -- String: \*[ae] + Interpolate small æ ligature. + + -- String: \*[Ae] + Interpolate capital Æ ligature. + + -- String: \*[oe] + Interpolate small oe ligature. + + -- String: \*[OE] + Interpolate capital OE ligature. + + +File: groff.info, Node: ms Naming Conventions, Prev: ms Legacy Features, Up: ms + +4.6.9 Naming Conventions +------------------------ + +The following conventions are used for names of macros, strings, and +registers. External names available to documents that use the 'groff' +'ms' macros contain only uppercase letters and digits. + + Internally, the macros are divided into modules. Conventions for +identifier names are as follows. + + * Names used only within one module are of the form MODULE'*'NAME. + + * Names used outside the module in which they are defined are of the + form MODULE'@'NAME. + + * Names associated with a particular environment are of the form + ENVIRONMENT':'NAME; these are used only within the 'par' module. + + * NAME does not have a module prefix. + + * Constructed names used to implement arrays are of the form + ARRAY'!'INDEX. + + Thus the 'groff' 'ms' macros reserve the following names. + + * Names containing the characters '*', '@', and ':'. + + * Names containing only uppercase letters and digits. + + +File: groff.info, Node: GNU troff Reference, Next: File Formats, Prev: Major Macro Packages, Up: Top + +5 GNU 'troff' Reference +*********************** + +This chapter covers _all_ of the facilities of the GNU 'troff' +formatting engine. Users of macro packages may skip it if not +interested in details. + +* Menu: + +* Text:: +* Page Geometry:: +* Measurements:: +* Numeric Expressions:: +* Identifiers:: +* Formatter Instructions:: +* Comments:: +* Registers:: +* Manipulating Filling and Adjustment:: +* Manipulating Hyphenation:: +* Manipulating Spacing:: +* Tabs and Fields:: +* Character Translations:: +* troff and nroff Modes:: +* Line Layout:: +* Line Continuation:: +* Page Layout:: +* Page Control:: +* Using Fonts:: +* Manipulating Type Size and Vertical Spacing:: +* Colors:: +* Strings:: +* Conditionals and Loops:: +* Writing Macros:: +* Page Motions:: +* Drawing Geometric Objects:: +* Deferring Output:: +* Traps:: +* Diversions:: +* Punning Names:: +* Environments:: +* Suppressing Output:: +* I/O:: +* Postprocessor Access:: +* Miscellaneous:: +* Gtroff Internals:: +* Debugging:: +* Implementation Differences:: + + +File: groff.info, Node: Text, Next: Measurements, Prev: GNU troff Reference, Up: GNU troff Reference + +5.1 Text +======== + +AT&T 'troff' was designed to take input as it would be composed on a +typewriter, including the teletypewriters used as early computer +terminals, and relieve the user drafting a document of concern with +details like line length, hyphenation breaking, and the achievement of +straight margins. Early in its development, the program gained the +ability to prepare output for a phototypesetter; a document could then +be prepared for output to either a teletypewriter, a phototypesetter, or +both. GNU 'troff' continues this tradition of permitting an author to +compose a single master version of a document which can then be rendered +for a variety of output formats or devices. + + 'roff' input files contain text interspersed with instructions to +control the formatter. Even in the absence of such instructions, GNU +'troff' still processes its input in several ways, by filling, +hyphenating, breaking, and adjusting it, and supplementing it with +inter-sentence space. + +* Menu: + +* Filling:: +* Hyphenation:: +* Sentences:: +* Breaking:: +* Adjustment:: +* Tabs and Leaders:: +* Requests and Macros:: +* Macro Packages:: +* Input Encodings:: +* Input Conventions:: + + +File: groff.info, Node: Filling, Next: Sentences, Prev: Text, Up: Text + +5.1.1 Filling +------------- + +When GNU 'troff' starts up, it obtains information about the device for +which it is preparing output.(1) (*note Filling-Footnote-1::) An +essential property is the length of the output line, such as "6.5 +inches". + + GNU 'troff' interprets plain text files employing the Unix +line-ending convention. It reads input a character at a time, +collecting words as it goes, and fits as many words together on an +output line as it can--this is known as "filling". To GNU 'troff', a +"word" is any sequence of one or more characters that aren't spaces or +newlines. The exceptions separate words.(2) (*note +Filling-Footnote-2::) To disable filling, see *note Manipulating Filling +and Adjustment::. + + It is a truth universally acknowledged + that a single man in possession of a + good fortune must be in want of a wife. + => It is a truth universally acknowledged that a + => single man in possession of a good fortune must + => be in want of a wife. + + +File: groff.info, Node: Filling-Footnotes, Up: Filling + + (1) *Note Device and Font Description Files::. + + (2) Tabs and leaders also separate words. Escape sequences can +function as word characters, word separators, or neither--the last +simply have no effect on GNU 'troff''s idea of whether an input +character is within a word. We'll discuss all of these in due course. + + +File: groff.info, Node: Sentences, Next: Hyphenation, Prev: Filling, Up: Text + +5.1.2 Sentences +--------------- + +A passionate debate has raged for decades among writers of the English +language over whether more space should appear between adjacent +sentences than between words within a sentence, and if so, how much, and +what other circumstances should influence this spacing.(1) (*note +Sentences-Footnote-1::) GNU 'troff' follows the example of AT&T 'troff'; +it attempts to detect the boundaries between sentences, and supplies +additional inter-sentence space between them. + + Hello, world! + Welcome to groff. + => Hello, world! Welcome to groff. + + GNU 'troff' flags certain characters (normally '!', '?', and '.') as +potentially ending a sentence. When GNU 'troff' encounters one of these +"end-of-sentence characters" at the end of an input line, or one of them +is followed by two (unescaped) spaces on the same input line, it appends +an inter-word space followed by an inter-sentence space in the output. + + R. Harper subscribes to a maxim of P. T. Barnum. + => R. Harper subscribes to a maxim of P. T. Barnum. + + In the above example, inter-sentence space is not added after 'P.' or +'T.' because the periods do not occur at the end of an input line, nor +are they followed by two or more spaces. Let's imagine that we've heard +something about defamation from Mr. Harper's attorney, recast the +sentence, and reflowed it in our text editor. + + I submit that R. Harper subscribes to a maxim of P. T. + Barnum. + => I submit that R. Harper subscribes to a maxim of + => P. T. Barnum. + + "Barnum" doesn't begin a sentence! What to do? Let us meet our +first "escape sequence", a series of input characters that give +instructions to GNU 'troff' instead of being used to construct output +device glyphs.(2) (*note Sentences-Footnote-2::) An escape sequence +begins with the backslash character '\' by default, an uncommon +character in natural language text, and is _always_ followed by at least +one other character, hence the term "sequence". + + The dummy character escape sequence '\&' can be used after an +end-of-sentence character to defeat end-of-sentence detection on a +per-instance basis. We can therefore rewrite our input more +defensively. + + I submit that R.\& Harper subscribes to a maxim of P.\& + T.\& Barnum. + => I submit that R. Harper subscribes to a maxim of + => P. T. Barnum. + + Adding text caused our input to wrap; now, we don't need '\&' after +'T.' but we do after 'P.'. Consistent use of the escape sequence +ensures that potential sentence boundaries are robust to editing +activities. Further advice along these lines will follow in *note Input +Conventions::. + + Normally, the occurrence of a visible non-end-of-sentence character +(as opposed to a space or tab) immediately after an end-of-sentence +character cancels detection of the end of a sentence. For example, it +would be incorrect for GNU 'troff' to infer the end of a sentence after +the dot in '3.14159'. However, several characters are treated +_transparently_ after the occurrence of an end-of-sentence character. +That is, GNU 'troff' does not cancel end-of-sentence detection when it +processes them. This is because such characters are often used as +footnote markers or to close quotations and parentheticals. The default +set is '"', ''', ')', ']', '*', '\[dg]', '\[dd]', '\[rq]', and '\[cq]'. +The last four are examples of "special characters", escape sequences +whose purpose is to obtain glyphs that are not easily typed at the +keyboard, or which have special meaning to GNU 'troff' (like '\' +itself).(3) (*note Sentences-Footnote-3::) + + \[lq]The idea that the poor should have leisure has always + been shocking to the rich.\[rq] + (Bertrand Russell, 1935) + => "The idea that the poor should have + => leisure has always been shocking to + => the rich." (Bertrand Russell, 1935) + + The sets of characters that potentially end sentences or are +transparent to sentence endings are configurable. See the 'cflags' +request in *note Using Symbols::. To change the additional +inter-sentence space amount--even to remove it entirely--see *note +Manipulating Filling and Adjustment::. + + +File: groff.info, Node: Sentences-Footnotes, Up: Sentences + + (1) A well-researched jeremiad appreciated by 'groff' contributors on +both sides of the sentence-spacing debate can be found at +<https://web.archive.org/web/20171217060354/http://www.heracliteanriver.com/?p=324>. + + (2) This statement oversimplifies; there are escape sequences whose +purpose is precisely to produce glyphs on the output device, and input +characters that _aren't_ part of escape sequences can undergo a great +deal of processing before getting to the output. + + (3) The mnemonics for the special characters shown here are "dagger", +"double dagger", "right (double) quote", and "closing (single) quote". +See the 'groff_char(7)' man page. + + +File: groff.info, Node: Hyphenation, Next: Breaking, Prev: Sentences, Up: Text + +5.1.3 Hyphenation +----------------- + +When an output line is nearly full, it is uncommon for the next word +collected from the input to exactly fill it--typically, there is room +left over only for part of the next word. The process of splitting a +word so that it appears partially on one line (with a hyphen to indicate +to the reader that the word has been broken) with its remainder on the +next is "hyphenation". Hyphenation points can be manually specified; +GNU 'troff' also uses a hyphenation algorithm and language-specific +pattern files (based on those used in TeX) to decide which words can be +hyphenated and where. + + Hyphenation does not always occur even when the hyphenation rules for +a word allow it; it can be disabled, and when not disabled there are +several parameters that can prevent it in certain circumstances. *Note +Manipulating Hyphenation::. + + +File: groff.info, Node: Breaking, Next: Adjustment, Prev: Hyphenation, Up: Text + +5.1.4 Breaking +-------------- + +Once an output line is full, the next word (or remainder of a hyphenated +one) is placed on a different output line; this is called a "break". In +this manual and in 'roff' discussions generally, a "break" if not +further qualified always refers to the termination of an output line. +When the formatter is filling text, it introduces breaks automatically +to keep output lines from exceeding the configured line length. After +an automatic break, GNU 'troff' adjusts the line if applicable (see +below), and then resumes collecting and filling text on the next output +line. + + Sometimes, a line cannot be broken automatically. This usually does +not happen with natural language text unless the output line length has +been manipulated to be extremely short, but it can with specialized text +like program source code. We can use 'perl' at the shell prompt to +contrive an example of failure to break the line. We also employ the +'-z' option to suppress normal output. + + $ perl -e 'print "#" x 80, "\n";' | nroff -z + error-> warning: cannot break line + + The remedy for these cases is to tell GNU 'troff' where the line may +be broken without hyphens. This is done with the non-printing break +point escape sequence '\:'; see *note Manipulating Hyphenation::. + + What if the document author wants to stop filling lines temporarily, +for instance to start a new paragraph? There are several solutions. A +blank input line not only causes a break, but by default it also outputs +a one-line vertical space (effectively a blank output line). This +behavior can be modified; see *note Blank Line Traps::. Macro packages +may discourage or disable the blank line method of paragraphing in favor +of their own macros. + + A line that begins with one or more spaces causes a break. The +spaces are output at the beginning of the next line without being +_adjusted_ (see below); however, this behavior can be modified (*note +Leading Space Traps::). Again, macro packages may provide other methods +of producing indented paragraphs. Trailing spaces on text lines are +discarded.(1) (*note Breaking-Footnote-1::) + + What if the file ends before enough words have been collected to fill +an output line? Or the output line is exactly full but not yet broken, +and there is no more input? GNU 'troff' interprets the end of input as +a break. Certain requests also cause breaks, implicitly or explicitly. +This is discussed in *note Manipulating Filling and Adjustment::. + + +File: groff.info, Node: Breaking-Footnotes, Up: Breaking + + (1) "Text lines" are defined in *note Requests and Macros::. + + +File: groff.info, Node: Adjustment, Next: Tabs and Leaders, Prev: Breaking, Up: Text + +5.1.5 Adjustment +---------------- + +After GNU 'troff' performs an automatic break, it may then "adjust" the +line, widening inter-word spaces until the text reaches the right +margin. Extra spaces between words are preserved. Leading and trailing +spaces are handled as noted above. Text can be aligned to the left or +right margin only, or centered; see *note Manipulating Filling and +Adjustment::. + + +File: groff.info, Node: Tabs and Leaders, Next: Input Conventions, Prev: Adjustment, Up: Text + +5.1.6 Tabs and Leaders +---------------------- + +GNU 'troff' translates input horizontal tab characters ("tabs") and +<Control+A> characters ("leaders") into movements to the next tab stop. +Tabs simply move to the next tab stop; leaders place enough periods to +fill the space. Tab stops are by default located every half inch +measured from the drawing position corresponding to the beginning of the +input line; see *note Page Geometry::. Tabs and leaders do not cause +breaks and therefore do not interrupt filling. Below, we use arrows -> +and bullets * to indicate input tabs and leaders, respectively. + + 1 + -> 2 -> 3 * 4 + -> * 5 + => 1 2 3.......4 ........5 + + Tabs and leaders lend themselves to table construction.(1) (*note +Tabs and Leaders-Footnote-1::) The tab and leader glyphs can be +configured, and further facilities for sophisticated table composition +are available; see *note Tabs and Fields::. There are many details to +track when using such low-level features, so most users turn to the +'tbl(1)' preprocessor to lay out tables. + + +File: groff.info, Node: Tabs and Leaders-Footnotes, Up: Tabs and Leaders + + (1) "Tab" is short for "tabulation", revealing the term's origin as a +spacing mechanism for table arrangement. + + +File: groff.info, Node: Requests and Macros, Next: Macro Packages, Prev: Tabs and Leaders, Up: Text + +5.1.7 Requests and Macros +------------------------- + +We have now encountered almost all of the syntax there is in the 'roff' +language, with an exception already noted in passing. A "request" is an +instruction to the formatter that occurs after a "control character", +which is recognized at the beginning of an input line. The regular +control character is a dot ('.'). Its counterpart, the "no-break +control character", a neutral apostrophe ('''), suppresses the break +that is implied by some requests. These characters were chosen because +it is uncommon for lines of text in natural languages to begin with +them. If you require a formatted period or apostrophe (closing single +quotation mark) where GNU 'troff' is expecting a control character, +prefix the dot or neutral apostrophe with the dummy character escape +sequence, '\&'. + + An input line beginning with a control character is called a "control +line". Every line of input that is not a control line is a "text +line".(1) (*note Requests and Macros-Footnote-1::) + + Requests often take "arguments", words (separated from the request +name and each other by spaces) that specify details of the action GNU +'troff' is expected to perform. If a request is meaningless without +arguments, it is typically ignored. + + GNU 'troff''s requests and escape sequences comprise the control +language of the formatter. Of key importance are the requests that +define macros. Macros are invoked like requests, enabling the request +repertoire to be extended or overridden.(2) (*note Requests and +Macros-Footnote-2::) + + A "macro" can be thought of as an abbreviation you can define for a +collection of control and text lines. When the macro is "called" by +giving its name after a control character, it is replaced with what it +stands for. The process of textual replacement is known as +"interpolation".(3) (*note Requests and Macros-Footnote-3::) +Interpolations are handled as soon as they are recognized, and once +performed, a 'roff' formatter scans the replacement for further +requests, macro calls, and escape sequences. + + In 'roff' systems, the 'de' request defines a macro.(4) (*note +Requests and Macros-Footnote-4::) + + .de DATE + 2020-11-14 + .. + +The foregoing input produces no output by itself; all we have done is +store some information. Observe the pair of dots that ends the macro +definition. This is a default; you can specify your own terminator for +the macro definition as the second argument to the 'de' request. + + .de NAME ENDNAME + Heywood Jabuzzoff + .ENDNAME + + In fact, the ending marker is itself the name of a macro to be +called, or a request to be invoked, if it is defined at the time its +control line is read. + + .de END + Big Rip + .. + .de START END + Big Bang + .END + .START + => Big Rip Big Bang + +In the foregoing example, "Big Rip" printed before "Big Bang" because +its macro was _called_ first. Consider what would happen if we dropped +'END' from the '.de START' line and added '..' after '.END'. Would the +order change? + + Let us consider a more elaborate example. + + .de DATE + 2020-10-05 + .. + . + .de BOSS + D.\& Kruger, + J.\& Peterman + .. + . + .de NOTICE + Approved: + .DATE + by + .BOSS + .. + . + Insert tedious regulatory compliance paragraph here. + + .NOTICE + + Insert tedious liability disclaimer paragraph here. + + .NOTICE + => Insert tedious regulatory compliance paragraph here. + => + => Approved: 2020-10-05 by D. Kruger, J. Peterman + => + => Insert tedious liability disclaimer paragraph here. + => + => Approved: 2020-10-05 by D. Kruger, J. Peterman + +The above document started with a series of control lines. Three macros +were defined, with a 'de' request declaring each macro's name, and the +"body" of the macro starting on the next line and continuing until a +line with two dots ''..'' marked its end. The text proper began only +after the macros were defined; this is a common pattern. Only the +'NOTICE' macro was called "directly" by the document; 'DATE' and 'BOSS' +were called only by 'NOTICE' itself. Escape sequences were used in +'BOSS', two levels of macro interpolation deep. + + The advantage in typing and maintenance economy may not be obvious +from such a short example, but imagine a much longer document with +dozens of such paragraphs, each requiring a notice of managerial +approval. Consider what must happen if you are in charge of generating +a new version of such a document with a different date, for a different +boss. With well-chosen macros, you only have to change each datum in +one place. + + In practice, we would probably use strings (*note Strings::) instead +of macros for such simple interpolations; what is important here is to +glimpse the potential of macros and the power of recursive +interpolation. + + We could have defined 'DATE' and 'BOSS' in the opposite order; +perhaps less obviously, we could also have defined them _after_ +'NOTICE'. "Forward references" like this are acceptable because the +body of a macro definition is not (completely) interpreted, but stored +instead (*note Copy Mode::). While a macro is being defined (or +appended to), requests are not interpreted and macros not interpolated, +whereas some commonly used escape sequences _are_ interpreted. 'roff' +systems also support recursive macro calls, as long as you have a way to +break the recursion (*note Conditionals and Loops::). Maintainable +'roff' documents tend to arrange macro definitions to minimize forward +references. + + +File: groff.info, Node: Requests and Macros-Footnotes, Up: Requests and Macros + + (1) The '\<RET>' escape sequence can alter how an input line is +classified; see *note Line Continuation::. + + (2) Argument handling in macros is more flexible but also more +complex. *Note Calling Macros::. + + (3) Some escape sequences undergo interpolation as well. + + (4) GNU 'troff' offers additional ones. *Note Writing Macros::. + + +File: groff.info, Node: Macro Packages, Next: Input Encodings, Prev: Requests and Macros, Up: Text + +5.1.8 Macro Packages +-------------------- + +Macro definitions can be collected into "macro files", 'roff' input +files designed to produce no output themselves but instead ease the +preparation of other 'roff' documents. There is no syntactical +difference between a macro file and any other 'roff' document; only its +purpose distinguishes it. When a macro file is installed at a standard +location and suitable for use by a general audience, it is often termed +a "macro package".(1) (*note Macro Packages-Footnote-1::) Macro +packages can be loaded by supplying the '-m' option to GNU 'troff' or a +'groff' front end. Alternatively, a document requiring a macro package +can load it with the 'mso' ("macro source") request. + + +File: groff.info, Node: Macro Packages-Footnotes, Up: Macro Packages + + (1) Macro files and packages frequently define registers and strings +as well. + + +File: groff.info, Node: Input Encodings, Next: Input Conventions, Prev: Macro Packages, Up: Text + +5.1.9 Input Encodings +--------------------- + +The 'groff' command's '-k' option calls the 'preconv' preprocessor to +perform input character encoding conversions. Input to the GNU 'troff' +formatter itself, on the other hand, must be in one of two encodings it +can recognize. + +'cp1047' + The code page 1047 input encoding works only on EBCDIC platforms + (and conversely, the other input encodings don't work with EBCDIC); + the file 'cp1047.tmac' is loaded at startup. + +'latin1' + ISO Latin-1, an encoding for Western European languages, is the + default input encoding on non-EBCDIC platforms; the file + 'latin1.tmac' is loaded at startup. + +Any document that is encoded in ISO 646:1991 (a descendant of USAS +X3.4-1968 or "US-ASCII"), or, equivalently, uses only code points from +the "C0 Controls" and "Basic Latin" parts of the Unicode character set +is also a valid ISO Latin-1 document; the standards are interchangeable +in their first 128 code points.(1) (*note Input Encodings-Footnote-1::) + + Other encodings are supported by means of macro packages. + +'latin2' + To use ISO Latin-2, an encoding for Central and Eastern European + languages, invoke '.mso latin2.tmac' at the beginning of your + document or supply '-mlatin2' as a command-line argument to + 'groff'. + +'latin5' + To use ISO Latin-5, an encoding for the Turkish language, invoke + '.mso latin5.tmac' at the beginning of your document or supply + '-mlatin5' as a command-line argument to 'groff'. + +'latin9' + ISO Latin-9 succeeds Latin-1; it includes a Euro sign and better + glyph coverage for French. To use this encoding, invoke + '.mso latin9.tmac' at the beginning of your document or supply + '-mlatin9' as a command-line argument to 'groff'. + + Some characters from an input encoding may not be available with a +particular output driver, or their glyphs may not have representation in +the font used. For terminal devices, fallbacks are defined, like 'EUR' +for the Euro sign and '(C)' for the copyright sign. For typesetter +devices, you may need to "mount" fonts that support glyphs required by +the document. *Note Font Positions::. + + Because a Euro glyph was not historically defined in PostScript +fonts, 'groff' comes with a font called 'freeeuro.pfa' that provides the +Euro in several styles. Standard PostScript fonts contain the glyphs +from Latin-5 and Latin-9 that Latin-1 lacks, so these encodings are +supported for the 'ps' and 'pdf' output devices as 'groff' ships, while +Latin-2 is not. + + Unicode supports characters from all other input encodings; the +'utf8' output driver for terminals therefore does as well. The DVI +output driver supports the Latin-2 and Latin-9 encodings if the +command-line option '-mec' is used as well. (2) (*note Input +Encodings-Footnote-2::) + + +File: groff.info, Node: Input Encodings-Footnotes, Up: Input Encodings + + (1) The _semantics_ of certain punctuation code points have gotten +stricter with the successive standards, a cause of some frustration +among man page writers; see the 'groff_char(7)' man page. + + (2) The DVI output device defaults to using the Computer Modern (CM) +fonts; 'ec.tmac' loads the EC fonts instead, which provide Euro '\[Eu]' +and per mille '\[%0]' glyphs. + + +File: groff.info, Node: Input Conventions, Prev: Input Encodings, Up: Text + +5.1.10 Input Conventions +------------------------ + +Since GNU 'troff' fills text automatically, it is common practice in the +'roff' language to avoid visual composition of text in input files: the +esthetic appeal of the formatted output is what matters. Therefore, +'roff' input should be arranged such that it is easy for authors and +maintainers to compose and develop the document, understand the syntax +of 'roff' requests, macro calls, and preprocessor languages used, and +predict the behavior of the formatter. Several traditions have accrued +in service of these goals. + + * Follow sentence endings in the input with newlines to ease their + recognition (*note Sentences::). It is frequently convenient to + end text lines after colons and semicolons as well, as these + typically precede independent clauses. Consider doing so after + commas; they often occur in lists that become easy to scan when + itemized by line, or constitute supplements to the sentence that + are added, deleted, or updated to clarify it. Parenthetical and + quoted phrases are also good candidates for placement on text lines + by themselves. + + * Set your text editor's line length to 72 characters or fewer.(1) + (*note Input Conventions-Footnote-1::) This limit, combined with + the previous item of advice, makes it less common that an input + line will wrap in your text editor, and thus will help you perceive + excessively long constructions in your text. Recall that natural + languages originate in speech, not writing, and that punctuation is + correlated with pauses for breathing and changes in prosody. + + * Use '\&' after '!', '?', and '.' if they are followed by space, + tab, or newline characters and don't end a sentence. + + * In filled text lines, use '\&' before '.' and ''' if they are + preceded by space, so that reflowing the input doesn't turn them + into control lines. + + * Do not use spaces to perform indentation or align columns of a + table. Leading spaces are reliable when text is not being filled. + + * Comment your document. It is never too soon to apply comments to + record information of use to future document maintainers (including + your future self). We thus introduce another escape sequence, + '\"', which causes GNU 'troff' to ignore the remainder of the input + line. + + * Use the empty request--a control character followed immediately by + a newline--to visually manage separation of material in input + files. Many of the 'groff' project's own documents use an empty + request between sentences, after macro definitions, and where a + break is expected, and two empty requests between paragraphs or + other requests or macro calls that will introduce vertical space + into the document. + + You can combine the empty request with the comment escape sequence + to include whole-line comments in your document, and even "comment + out" sections of it. + + We conclude this section with an example sufficiently long to +illustrate most of the above suggestions in practice. For the purpose +of fitting the example between the margins of this manual with the font +used for its typeset version, we have shortened the input line length to +56 columns. As before, an arrow -> indicates a tab character. + + .\" nroff this_file.roff | less + .\" groff -T ps this_file.roff > this_file.ps + ->The theory of relativity is intimately connected with + the theory of space and time. + . + I shall therefore begin with a brief investigation of + the origin of our ideas of space and time, + although in doing so I know that I introduce a + controversial subject. \" remainder of paragraph elided + . + . + + ->The experiences of an individual appear to us arranged + in a series of events; + in this series the single events which we remember + appear to be ordered according to the criterion of + \[lq]earlier\[rq] and \[lq]later\[rq], \" punct swapped + which cannot be analysed further. + . + There exists, + therefore, + for the individual, + an I-time, + or subjective time. + . + This itself is not measurable. + . + I can, + indeed, + associate numbers with the events, + in such a way that the greater number is associated with + the later event than with an earlier one; + but the nature of this association may be quite + arbitrary. + . + This association I can define by means of a clock by + comparing the order of events furnished by the clock + with the order of a given series of events. + . + We understand by a clock something which provides a + series of events which can be counted, + and which has other properties of which we shall speak + later. + .\" Albert Einstein, _The Meaning of Relativity_, 1922 + + +File: groff.info, Node: Input Conventions-Footnotes, Up: Input Conventions + + (1) Emacs: 'fill-column: 72'; Vim: 'textwidth=72' + + +File: groff.info, Node: Page Geometry, Next: Measurements, Prev: Text, Up: GNU troff Reference + +5.2 Page Geometry +================= + +'roff' systems format text under certain assumptions about the size of +the output medium, or page. For the formatter to correctly break a line +it is filling, it must know the line length, which it derives from the +page width (*note Line Layout::). For it to decide whether to write an +output line to the current page or wait until the next one, it must know +the page length (*note Page Layout::). + + A device's "resolution" converts practical units like inches or +centimeters to "basic units", a convenient length measure for the output +device or file format. The formatter and output driver use basic units +to reckon page measurements. The device description file defines its +resolution and page dimensions (*note DESC File Format::). + + A "page" is a two-dimensional structure upon which a 'roff' system +imposes a rectangular coordinate system with its upper left corner as +the origin. Coordinate values are in basic units and increase down and +to the right. Useful ones are therefore always positive and within +numeric ranges corresponding to the page boundaries. + + While the formatter (and, later, output driver) is processing a page, +it keeps track of its "drawing position", which is the location at which +the next glyph will be written, from which the next motion will be +measured, or where a geometric object will commence rendering. +Notionally, glyphs are drawn from the text baseline upward and to the +right.(1) (*note Page Geometry-Footnote-1::) The "text baseline" is a +(usually invisible) line upon which the glyphs of a typeface are +aligned. A glyph therefore "starts" at its bottom-left corner. If +drawn at the origin, a typical letter glyph would lie partially or +wholly off the page, depending on whether, like "g", it features a +descender below the baseline. + + Such a situation is nearly always undesirable. It is furthermore +conventional not to write or draw at the extreme edges of the page. +Therefore the initial drawing position of a 'roff' formatter is not at +the origin, but below and to the right of it. This rightward shift from +the left edge is known as the "page offset".(2) (*note Page +Geometry-Footnote-2::) The downward shift leaves room for a text output +line. + + Text is arranged on a one-dimensional lattice of text baselines from +the top to the bottom of the page. "Vertical spacing" is the distance +between adjacent text baselines. Typographic tradition sets this +quantity to 120% of the type size. The initial drawing position is one +unit of vertical spacing below the page top. Typographers term this +unit a vee. + + Vertical spacing has an impact on page-breaking decisions. +Generally, when a break occurs, the formatter moves the drawing position +to the next text baseline automatically. If the formatter were already +writing to the last line that would fit on the page, advancing by one +vee would place the next text baseline off the page. Rather than let +that happen, 'roff' formatters instruct the output driver to eject the +page, start a new one, and again set the drawing position to one vee +below the page top; this is a "page break". + + When the last line of input text corresponds to the last output line +that fits on the page, the break caused by the end of input will also +break the page, producing a useless blank one. Macro packages keep +users from having to confront this difficulty by setting "traps" (*note +Traps::); moreover, all but the simplest page layouts tend to have +headers and footers, or at least bear vertical margins larger than one +vee. + + +File: groff.info, Node: Page Geometry-Footnotes, Up: Page Geometry + + (1) 'groff' does not yet support right-to-left scripts. + + (2) 'groff''s terminal output devices have page offsets of zero. + + +File: groff.info, Node: Measurements, Next: Numeric Expressions, Prev: Text, Up: GNU troff Reference + +5.3 Measurements +================ + +The formatter sometimes requires the input of numeric parameters to +specify measurements. These are specified as integers or decimal +fractions with an optional "scaling unit" suffixed. A scaling unit is a +letter that immediately follows the last digit of a number. Digits +after the decimal point are optional. Measurement expressions include +'10.5p', '11i', and '3.c'. + + Measurements are scaled by the scaling unit and stored internally +(with any fractional part discarded) in basic units. The device +resolution can therefore be obtained by storing a value of '1i' to a +register. The only constraint on the basic unit is that it is at least +as small as any other unit. + +'u' + Basic unit. + +'i' + Inch; defined as 2.54 centimeters. + +'c' + Centimeter; a centimeter is about 0.3937 inches. + +'p' + Point; a typesetter's unit used for measuring type size. There are + 72 points to an inch. + +'P' + Pica; another typesetter's unit. There are 6 picas to an inch and + 12 points to a pica. + +'s' +'z' + *Note Using Fractional Type Sizes::, for a discussion of these + units. + +'f' + GNU 'troff' defines this unit to scale decimal fractions in the + interval [0, 1] to 16-bit unsigned integers. It multiplies a + quantity by 65,536. *Note Colors::, for usage. + + The magnitudes of other scaling units depend on the text formatting +parameters in effect. These are useful when specifying measurements +that need to scale with the typeface or vertical spacing. + +'m' + Em; an em is equal to the current type size in points. It is named + thus because it is approximately the width of the letter 'M'. + +'n' + En; an en is one-half em. + +'v' + Vee; recall *note Page Geometry::. + +'M' + Hundredth of an em. + +* Menu: + +* Motion Quanta:: +* Default Units:: + + +File: groff.info, Node: Motion Quanta, Next: Default Units, Prev: Measurements, Up: Measurements + +5.3.1 Motion Quanta +------------------- + +An output device's basic unit 'u' is not necessarily its smallest +addressable length; 'u' can be smaller to avoid problems with integer +roundoff. The minimum distances that a device can work with in the +horizontal and vertical directions are termed its "motion quanta". +Measurements are rounded to applicable motion quanta. Half-quantum +fractions round toward zero. + + -- Register: \n[.H] + -- Register: \n[.V] + These read-only registers interpolate the horizontal and vertical + motion quanta, respectively, of the output device in basic units. + + For example, we might draw short baseline rules on a terminal device +as follows. *Note Drawing Geometric Objects::. + + .tm \n[.H] + error-> 24 + .nf + \l'36u' 36u + \l'37u' 37u + => _ 36u + => __ 37u + + +File: groff.info, Node: Default Units, Prev: Motion Quanta, Up: Measurements + +5.3.2 Default Units +------------------- + +A general-purpose register (one created or updated with the 'nr' +request; see *note Registers::) is implicitly dimensionless, or reckoned +in basic units if interpreted in a measurement context. But it is +convenient for many requests and escape sequences to infer a scaling +unit for an argument if none is specified. An explicit scaling unit +(not after a closing parenthesis) can override an undesirable default. +Effectively, the default unit is suffixed to the expression if a scaling +unit is not already present. GNU 'troff''s use of integer arithmetic +should also be kept in mind (*note Numeric Expressions::). + + The 'll' request interprets its argument in ems by default. Consider +several attempts to set a line length of 3.5 inches when the type size +is 10 points on a terminal device with a resolution of 240 basic units +and horizontal motion quantum of 24. Some expressions become zero; the +request clamps them to that quantum. + + .ll 3.5i \" 3.5i (= 840u) + .ll 7/2 \" 7u/2u -> 3u -> 3m -> 0, clamped to 24u + .ll (7 / 2)u \" 7u/2u -> as above + .ll 7/2i \" 7u/2i -> 7u/480u -> 0 -> as above + .ll 7i/2 \" 7i/2u -> 1680u/2m -> 1680u/24u -> 35u + .ll 7i/2u \" 3.5i (= 840u) + +The safest way to specify measurements is to attach a scaling unit. To +multiply or divide by a dimensionless quantity, use 'u' as its scaling +unit. + + +File: groff.info, Node: Numeric Expressions, Next: Identifiers, Prev: Measurements, Up: GNU troff Reference + +5.4 Numeric Expressions +======================= + +A "numeric expression" evaluates to an integer: it can be as simple as a +literal '0' or it can be a complex sequence of register and string +interpolations interleaved with measurements and operators. + + GNU 'troff' provides a set of mathematical and logical operators +familiar to programmers--as well as some unusual ones--but supports only +integer arithmetic.(1) (*note Numeric Expressions-Footnote-1::) The +internal data type used for computing results is usually a 32-bit signed +integer, which suffices to represent magnitudes within a range of ±2 +billion.(2) (*note Numeric Expressions-Footnote-2::) + + Arithmetic infix operators perform a function on the numeric +expressions to their left and right; they are '+' (addition), '-' +(subtraction), '*' (multiplication), '/' (truncating division), and '%' +(modulus). "Truncating division" rounds to the integer nearer to zero, +no matter how large the fractional portion. Overflow and division (or +modulus) by zero are errors and abort evaluation of a numeric +expression. + + Arithmetic unary operators operate on the numeric expression to their +right; they are '-' (negation) and '+' (assertion--for completeness; it +does nothing). The unary minus must often be used with parentheses to +avoid confusion with the decrementation operator, discussed below. + + Observe the rounding behavior and effect of negative operands on the +modulus and truncating division operators. + + .nr T 199/100 + .nr U 5/2 + .nr V (-5)/2 + .nr W 5/-2 + .nr X 5%2 + .nr Y (-5)%2 + .nr Z 5%-2 + T=\n[T] U=\n[U] V=\n[V] W=\n[W] X=\n[X] Y=\n[Y] Z=\n[Z] + => T=1 U=2 V=-2 W=-2 X=1 Y=-1 Z=1 + +The sign of the modulus of operands of mixed signs is determined by the +sign of the first. Division and modulus operators satisfy the following +property: given a dividend A and a divisor B, a quotient Q formed by '(a +/ b)' and a remainder R by '(a % b)', then qb + r = a. + + GNU 'troff''s scaling operator, used with parentheses as '(C;E)', +evaluates a numeric expression E using C as the default scaling unit. +If C is omitted, scaling units are ignored in the evaluation of E. This +operator can save typing by avoiding the attachment of scaling units to +every operand out of caution. Your macros can select a sensible default +unit in case the user neglects to supply one. + + .\" Indent by amount given in first argument; assume ens. + .de Indent + . in (n;\\$1) + .. + +Without the scaling operator, the foregoing macro would, if called with +a unitless argument, cause indentation by the 'in' request's default +scaling unit (ems). The result would be twice as much indentation as +expected. + + GNU 'troff' also provides a pair of operators to compute the extrema +of two operands: '>?' (maximum) and '<?' (minimum). + + .nr slots 5 + .nr candidates 3 + .nr salaries (\n[slots] <? \n[candidates]) + Looks like we'll end up paying \n[salaries] salaries. + => Looks like we'll end up paying 3 salaries. + + Comparison operators comprise '<' (less than), '>' (greater than), +'<=' (less than or equal), '>=' (greater than or equal), and '=' +(equal). '==' is a synonym for '='. When evaluated, a comparison is +replaced with '0' if it is false and '1' if true. In the 'roff' +language, positive values are true, others false. + + We can operate on truth values with the logical operators '&' +(logical conjunction or "and") and ':' (logical disjunction or "or"). +They evaluate as comparison operators do. + + A logical complementation ("not") operator, '!', works only within +'if', 'ie', and 'while' requests. Furthermore, '!' is recognized only +at the beginning of a numeric expression not contained by another +numeric expression. In other words, it must be the "outermost" +operator. Including it elsewhere in the expression produces a warning +in the 'number' category (*note Warnings::), and its expression +evaluates false. This unfortunate limitation maintains compatibility +with AT&T 'troff'. Test a numeric expression for falsity by comparing +it to a false value.(3) (*note Numeric Expressions-Footnote-3::) + + .nr X 1 + .nr Y 0 + .\" This does not work as expected. + .if (\n[X])&(!\n[Y]) .nop A: X is true, Y is false + . + .\" Use this construct instead. + .if (\n[X])&(\n[Y]<=0) .nop B: X is true, Y is false + error-> warning: expected numeric expression, got '!' + => B: X is true, Y is false + + The 'roff' language has no operator precedence: expressions are +evaluated strictly from left to right, in contrast to schoolhouse +arithmetic. Use parentheses '(' ')' to impose a desired precedence upon +subexpressions. + + .nr X 3+5*4 + .nr Y (3+5)*4 + .nr Z 3+(5*4) + X=\n[X] Y=\n[Y] Z=\n[Z] + => X=32 Y=32 Z=23 + + For many requests and escape sequences that cause motion on the page, +the unary operators '+' and '-' work differently when leading a numeric +expression. They then indicate a motion relative to the drawing +position: positive is down in vertical contexts, right in horizontal +ones. + + '+' and '-' are also treated differently by the following requests +and escape sequences: 'bp', 'in', 'll', 'lt', 'nm', 'nr', 'pl', 'pn', +'po', 'ps', 'pvs', 'rt', 'ti', '\H', '\R', and '\s'. Here, leading plus +and minus signs serve as incrementation and decrementation operators, +respectively. To negate an expression, subtract it from zero or include +the unary minus in parentheses with its argument. *Note Setting +Registers::, for examples. + + A leading '|' operator indicates a motion relative not to the drawing +position but to a boundary. For horizontal motions, the measurement +specifies a distance relative to a drawing position corresponding to the +beginning of the _input_ line. By default, tab stops reckon movements +in this way. Most escape sequences do not; '|' tells them to do so. + + Mind the \h'1.2i'gap. + .br + Mind the \h'|1.2i'gap. + .br + Mind the + \h'|1.2i'gap. + => Mind the gap. + => Mind the gap. + => Mind the gap. + + One use of this feature is to define macros whose scope is limited to +the output they format. + + .\" underline word $1 with trailing punctuation $2 + .de Underline + . nop \\$1\l'|0\[ul]'\\$2 + .. + Typographical emphasis is best used + .Underline sparingly . + +In the above example, '|0' specifies a negative motion from the current +position (at the end of the argument just emitted, '\$1') to the +beginning of the input line. Thus, the '\l' escape sequence in this +case draws a line from right to left. A macro call occurs at the +beginning of an input line;(4) (*note Numeric Expressions-Footnote-4::) +if the '|' operator were omitted, then the underline would be drawn at +zero distance from the current position, producing device-dependent, and +likely undesirable, results. On the 'ps' output device, it underlines +the period. + + For vertical motions, the '|' operator specifies a distance from the +first text baseline on the page or in the current diversion,(5) (*note +Numeric Expressions-Footnote-5::) using the current vertical spacing. + + A + .br + B \Z'C'\v'|0'D + => A D + => B C + + In the foregoing example, we've used the '\Z' escape sequence (*note +Page Motions::) to restore the drawing position after formatting 'C', +then moved vertically to the first text baseline on the page. + + -- Escape sequence: \B'anything' + Interpolate 1 if ANYTHING is a valid numeric expression, and 0 + otherwise. The delimiter need not be a neutral apostrophe; see + *note Delimiters::. + + You might use '\B' along with the 'if' request to filter out invalid +macro or string arguments. *Note Conditionals and Loops::. + + .\" Indent by amount given in first argument; assume ens. + .de Indent + . if \B'\\$1' .in (n;\\$1) + .. + + A register interpolated as an operand in a numeric expression must +have an Arabic format; luckily, this is the default. *Note Assigning +Register Formats::. + + Because spaces separate arguments to requests, spaces are not allowed +in numeric expressions unless the (sub)expression containing them is +surrounded by parentheses. *Note Invoking Requests::, and *note +Conditionals and Loops::. + + .nf + .nr a 1+2 + 2+1 + \na + error-> expected numeric expression, got a space + => 3 + .nr a 1+(2 + 2)+1 + \na + => 6 + + The 'nr' request (*note Setting Registers::) expects its second and +optional third arguments to be numeric expressions; a bare '+' does not +qualify, so our first attempt got a warning. + + +File: groff.info, Node: Numeric Expressions-Footnotes, Up: Numeric Expressions + + (1) Provision is made for interpreting and reporting decimal +fractions in certain cases. + + (2) If that's not enough, see the 'groff_tmac(5)' man page for the +'62bit.tmac' macro package. + + (3) *Note Conditionals and Loops::. + + (4) Control structure syntax creates an exception to this rule, but +is designed to remain useful: recalling our example, '.if 1 .Underline +this' would underline only "this", precisely. *Note Conditionals and +Loops::. + + (5) *Note Diversions::. + + +File: groff.info, Node: Identifiers, Next: Formatter Instructions, Prev: Numeric Expressions, Up: GNU troff Reference + +5.5 Identifiers +=============== + +An "identifier" labels a GNU 'troff' datum such as a register, name +(macro, string, or diversion), typeface, color, special character, +character class, environment, or stream. Valid identifiers consist of +one or more ordinary characters. An ordinary character is an input +character that is not the escape character, a leader, tab, newline, or +invalid as GNU 'troff' input. + + Invalid input characters are a subset of control characters (from the +sets "C0 Controls" and "C1 Controls" as Unicode describes them). When +GNU 'troff' encounters one in an identifier, it produces a warning in +category 'input' (*note Warnings::). They are removed during +interpretation: an identifier 'foo', followed by an invalid character +and then 'bar', is processed as 'foobar'. + + On a machine using the ISO 646, 8859, or 10646 character encodings, +invalid input characters are '0x00', '0x08', '0x0B', '0x0D'-'0x1F', and +'0x80'-'0x9F'. On an EBCDIC host, they are '0x00'-'0x01', '0x08', +'0x09', '0x0B', '0x0D'-'0x14', '0x17'-'0x1F', and '0x30'-'0x3F'.(1) +(*note Identifiers-Footnote-1::) Some of these code points are used by +GNU 'troff' internally, making it non-trivial to extend the program to +accept UTF-8 or other encodings that use characters from these +ranges.(2) (*note Identifiers-Footnote-2::) + + Thus, the identifiers 'br', 'PP', 'end-list', 'ref*normal-print', +'|', '@_', and '!"#$%'()*+,-./' are all valid. Discretion should be +exercised to prevent confusion. Identifiers starting with '(' or '[' +require care. + + .nr x 9 + .nr y 1 + .nr (x 2 + .nr [y 3 + .nr sum1 (\n(x + \n[y]) + error-> a space character is not allowed in an escape + error-> sequence parameter + A:2+3=\n[sum1] + .nr sum2 (\n((x + \n[[y]) + B:2+3=\n[sum2] + .nr sum3 (\n[(x] + \n([y) + C:2+3=\n[sum3] + => A:2+3=1 B:2+3=5 C:2+3=5 + +An identifier with a closing bracket (']') in its name can't be accessed +with bracket-form escape sequences that expect an identifier as a +parameter. For example, '\[foo]]' accesses the glyph 'foo', followed by +']' in whatever the surrounding context is, whereas '\C'foo]'' formats a +glyph named 'foo]'. Similarly, the identifier '(' can't be interpolated +_except_ with bracket forms. + + If you begin a macro, string, or diversion name with either of the +characters '[' or ']', you foreclose use of the 'grefer' preprocessor, +which recognizes '.[' and '.]' as bibliographic reference delimiters. + + -- Escape sequence: \A'anything' + Interpolate 1 if ANYTHING is a valid identifier, and 0 otherwise. + The delimiter need not be a neutral apostrophe; see *note + Delimiters::. Because invalid input characters are removed (see + above), invalid identifiers are empty or contain spaces, tabs, or + newlines. + + You can employ '\A' to validate a macro argument before using it to + construct another escape sequence or identifier. + + .\" usage: .init-coordinate-pair name val1 val2 + .\" Create a coordinate pair where name!x=val1 and + .\" name!y=val2. + .de init-coordinate-pair + . if \A'\\$1' \{\ + . if \B'\\$2' .nr \\$1!x \\$2 + . if \B'\\$3' .nr \\$1!y \\$3 + . \} + .. + .init-coordinate-pair center 5 10 + The center is at (\n[center!x], \n[center!y]). + .init-coordinate-pair "poi->nt" trash garbage \" ignored + .init-coordinate-pair point trash garbage \" ignored + => The center is at (5, 10). + + In this example, we also validated the numeric arguments; the + registers 'point!x' and 'point!y' remain undefined. *Note Numeric + Expressions:: for the '\B' escape sequence. + + How GNU 'troff' handles the interpretation of an undefined identifier +depends on the context. There is no way to invoke an undefined request; +such syntax is interpreted as a macro call instead. If the identifier +is interpreted as a string, macro, or diversion, GNU 'troff' emits a +warning in category 'mac', defines it as empty, and interpolates +nothing. If the identifier is interpreted as a register, GNU 'troff' +emits a warning in category 'reg', initializes it to zero, and +interpolates that value. *Note Warnings::, *note Interpolating +Registers::, and *note Strings::. Attempting to use an undefined +typeface, special character, color, character class, environment, or +stream generally provokes an error diagnostic. + + Identifiers for requests, macros, strings, and diversions share one +name space; special characters and character classes another. No other +object types do. + + .de xxx + . nop foo + .. + .di xxx + bar + .br + .di + . + .xxx + => bar + +The foregoing example shows that GNU 'troff' reuses the identifier +'xxx', changing it from a macro to a diversion. No warning is emitted, +and the previous contents of 'xxx' are lost. + + +File: groff.info, Node: Identifiers-Footnotes, Up: Identifiers + + (1) Historically, control characters like ASCII STX, ETX, and BEL +(<Control+B>, <Control+C>, and <Control+G>) have been observed in 'roff' +documents, particularly in macro packages employing them as delimiters +with the output comparison operator to try to avoid collisions with the +content of arbitrary user-supplied parameters (*note Operators in +Conditionals::). We discourage this expedient; in GNU 'troff' it is +unnecessary (outside of compatibility mode) because delimited arguments +are parsed at a different input level than the surrounding context. +*Note Implementation Differences::. + + (2) Consider what happens when a C1 control '0x80'-'0x9F' is +necessary as a continuation byte in a UTF-8 sequence. + + +File: groff.info, Node: Formatter Instructions, Next: Registers, Prev: Identifiers, Up: GNU troff Reference + +5.6 Formatter Instructions +========================== + +To support documents that require more than filling, automatic line +breaking and hyphenation, adjustment, and supplemental inter-sentence +space, the 'roff' language offers two means of embedding instructions to +the formatter. + + One is a "request", which begins with a control character and takes +up the remainder of the input line. Requests often perform relatively +large-scale operations such as setting the page length, breaking the +line, or starting a new page. They also conduct internal operations +like defining macros. + + The other is an "escape sequence", which begins with the escape +character and can be embedded anywhere in the input, even in arguments +to requests and other escape sequences. Escape sequences interpolate +special characters, strings, or registers, and handle comparatively +minor formatting tasks like sub- and superscripting. + + Some operations, such as font selection and type size alteration, are +available via both requests and escape sequences. + +* Menu: + +* Control Characters:: +* Invoking Requests:: +* Calling Macros:: +* Using Escape Sequences:: +* Delimiters:: + + +File: groff.info, Node: Control Characters, Next: Invoking Requests, Prev: Formatter Instructions, Up: Formatter Instructions + +5.6.1 Control Characters +------------------------ + +The mechanism of using 'roff''s control characters to invoke requests +and call macros was introduced in *note Requests and Macros::. Control +characters are recognized only at the beginning of an input line, or at +the beginning of the branch of a control structure request; see *note +Conditionals and Loops::. + + A few requests cause a break implicitly; use the no-break control +character to prevent the break. Break suppression is its sole +behavioral distinction. Employing the no-break control character to +invoke requests that don't cause breaks is harmless but poor style. +*Note Manipulating Filling and Adjustment::. + + The control '.' and no-break control ''' characters can each be +changed to any ordinary character(1) (*note Control +Characters-Footnote-1::) with the 'cc' and 'c2' requests, respectively. + + -- Request: .cc [o] + Recognize the ordinary character O as the control character. If O + is absent or invalid, the default control character '.' is + selected. The identity of the control character is associated with + the environment (*note Environments::). + + -- Request: .c2 [o] + Recognize the ordinary character O as the no-break control + character. If O is absent or invalid, the default no-break control + character ''' is selected. The identity of the no-break control + character is associated with the environment (*note + Environments::). + + When writing a macro, you might wish to know which control character +was used to call it. + + -- Register: \n[.br] + This read-only register interpolates 1 if the currently executing + macro was called using the normal control character and 0 + otherwise. If a macro is interpolated as a string, the '.br' + register's value is inherited from the context of the string + interpolation. *Note Strings::. + + Use this register to reliably intercept requests that imply breaks. + + .als bp*orig bp + .de bp + . ie \\n[.br] .bp*orig + . el 'bp*orig + .. + + Testing the '.br' register outside of a macro definition makes no + sense. + + +File: groff.info, Node: Control Characters-Footnotes, Up: Control Characters + + (1) Recall *note Identifiers::. + + +File: groff.info, Node: Invoking Requests, Next: Calling Macros, Prev: Control Characters, Up: Formatter Instructions + +5.6.2 Invoking Requests +----------------------- + +A control character is optionally followed by tabs and/or spaces and +then an identifier naming a request or macro. The invocation of an +unrecognized request is interpreted as a macro call. Defining a macro +with the same name as a request replaces the request. Deleting a +request name with the 'rm' request makes it unavailable. The 'als' +request can alias requests, permitting them to be wrapped or +non-destructively replaced. *Note Strings::. + + There is no inherent limit on argument length or quantity. Most +requests take one or more arguments, and ignore any they do not expect. +A request may be separated from its arguments by tabs or spaces, but +only spaces can separate an argument from its successor. Only one +between arguments is necessary; any excess is ignored. GNU 'troff' does +not allow tabs for argument separation.(1) (*note Invoking +Requests-Footnote-1::) + + Generally, a space _within_ a request argument is not relevant, not +meaningful, or is supported by bespoke provisions, as with the 'tl' +request's delimiters (*note Page Layout::). Some requests, like 'ds', +interpret the remainder of the control line as a single argument. *Note +Strings::. + + Spaces and tabs immediately after a control character are ignored. +Commonly, authors structure the source of documents or macro files with +them. + + .de center + . if \\n[.br] \ + . br + . ce \\$1 + .. + . + . + .de right-align + .->if \\n[.br] \ + .->->br + .->rj \\$1 + .. + + If you assign an empty blank line trap, you can separate macro +definitions (or any input lines) with blank lines. + + .de do-nothing + .. + .blm do-nothing \" activate blank line trap + + .de center + . if \\n[.br] \ + . br + . ce \\$1 + .. + + + .de right-align + .->if \\n[.br] \ + .->->br + .->rj \\$1 + .. + + .blm \" deactivate blank line trap + + *Note Blank Line Traps::. + + +File: groff.info, Node: Invoking Requests-Footnotes, Up: Invoking Requests + + (1) In compatibility mode, a space is not necessary after a request +or macro name of two characters' length. Also, Plan 9 'troff' allows +tabs to separate arguments. + + +File: groff.info, Node: Calling Macros, Next: Using Escape Sequences, Prev: Invoking Requests, Up: Formatter Instructions + +5.6.3 Calling Macros +-------------------- + +If a macro of the desired name does not exist when called, it is +created, assigned an empty definition, and a warning in category 'mac' +is emitted. Calling an undefined macro _does_ end a macro definition +naming it as its end macro (*note Writing Macros::). + + To embed spaces _within_ a macro argument, enclose the argument in +neutral double quotes '"'. Horizontal motion escape sequences are +sometimes a better choice for arguments to be formatted as text. + + Consider calls to a hypothetical section heading macro 'uh'. + + .uh The Mouse Problem + .uh "The Mouse Problem" + .uh The\~Mouse\~Problem + .uh The\ Mouse\ Problem + +The first line calls 'uh' with three arguments: 'The', 'Mouse', and +'Problem'. The remainder call the 'uh' macro with one argument, 'The +Mouse Problem'. The last solution, using escaped spaces, can be found +in documents prepared for AT&T 'troff'. It can cause surprise when text +is adjusted, because '\<SP>' inserts a _fixed-width_, non-breaking +space. GNU 'troff''s '\~' escape sequence inserts an adjustable, +non-breaking space.(1) (*note Calling Macros-Footnote-1::) + + The foregoing raises the question of how to embed neutral double +quotes or backslashes in macro arguments when _those_ characters are +desired as literals. In GNU 'troff', the special character escape +sequence '\[rs]' produces a backslash and '\[dq]' a neutral double +quote. + + In GNU 'troff''s AT&T compatibility mode, these characters remain +available as '\(rs' and '\(dq', respectively. AT&T 'troff' did not +consistently define these special characters, but its descendants can be +made to support them. *Note Device and Font Description Files::. + + If even that is not feasible, options remain. To obtain a literal +escape character in a macro argument, you can simply type it if you +change or disable the escape character first. *Note Using Escape +Sequences::. Otherwise, you must escape the escape character repeatedly +to a context-dependent extent. *Note Copy Mode::. + + For the (neutral) double quote, you have recourse to an obscure +syntactical feature of AT&T 'troff'. Because a double quote can begin a +macro argument, the formatter keeps track of whether the current +argument was started thus, and doesn't require a space after the double +quote that ends it.(2) (*note Calling Macros-Footnote-2::) In the +argument list to a macro, a double quote that _isn't_ preceded by a +space _doesn't_ start a macro argument. If not preceded by a double +quote that began an argument, this double quote becomes part of the +argument. Furthermore, within a quoted argument, a pair of adjacent +double quotes becomes a literal double quote. + + .de eq + . tm arg1:\\$1 arg2:\\$2 arg3:\\$3 + . tm arg4:\\$4 arg5:\\$5 arg6:\\$6 + .. \" 4 backslashes on the next line + .eq a" "b c" "de"f\\\\g" h""i "j""k" + error-> arg1:a" arg2:b c arg3:de + error-> arg4:f\g" arg5:h""i arg6:j"k + + Apart from the complexity of the rules, this traditional solution has +the disadvantage that double quotes don't survive repeated argument +expansion in AT&T 'troff' or GNU 'troff''s compatibility mode. This can +frustrate efforts to pass such arguments intact through multiple macro +calls. + + .cp 1 + .de eq + . tm arg1:\\$1 arg2:\\$2 arg3:\\$3 + . tm arg4:\\$4 arg5:\\$5 arg6:\\$6 + .. + .de xe + . eq \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 + .. \" 8 backslashes on the next line + .xe a" "b c" "de"f\\\\\\\\g" h""i "j""k" + error-> arg1:a" arg2:b arg3:c + error-> arg4:de arg5:f\g" arg6:h""i + + Outside of compatibility mode, GNU 'troff' doesn't exhibit this +problem because it tracks the nesting depth of interpolations. *Note +Implementation Differences::. + + +File: groff.info, Node: Calling Macros-Footnotes, Up: Calling Macros + + (1) '\~' is fairly portable; see *note Other Differences::. + + (2) Strictly, you can neglect to close the last quoted macro +argument, relying on the end of the control line to do so. We consider +this lethargic practice poor style. + + +File: groff.info, Node: Using Escape Sequences, Next: Delimiters, Prev: Calling Macros, Up: Formatter Instructions + +5.6.4 Using Escape Sequences +---------------------------- + +Whereas requests must occur on control lines, escape sequences can occur +intermixed with text and may appear in arguments to requests, macros, +and other escape sequences. An escape sequence is introduced by the +escape character, a backslash '\' (but see the 'ec' request below). The +next character selects the escape's function. + + Escape sequences vary in length. Some take an argument, and of +those, some have different syntactical forms for a one-character, +two-character, or arbitrary-length argument. Others accept _only_ an +arbitrary-length argument. In the former scheme, a one-character +argument follows the function character immediately, an opening +parenthesis '(' introduces a two-character argument (no closing +parenthesis is used), and an argument of arbitrary length is enclosed in +brackets '[]'. In the latter scheme, the user selects a delimiter +character. A few escape sequences are idiosyncratic, and support both +of the foregoing conventions ('\s'), designate their own termination +sequence ('\?'), consume input until the next newline ('\!', '\"', +'\#'), or support an additional modifier character ('\s' again, and +'\n'). As with requests, use of some escape sequences in source +documents may interact poorly with a macro package you use; consult its +documentation to learn of "safe" sequences or alternative facilities it +provides to achieve the desired result. + + If an escape character is followed by a character that does not +identify a defined operation, the escape character is ignored (producing +a diagnostic of the 'escape' warning category, which is not enabled by +default) and the following character is processed normally. + + $ groff -Tps -ww + .nr N 12 + .ds co white + .ds animal elephant + I have \fI\nN \*(co \*[animal]s,\f[] + said \P.\&\~Pseudo Pachyderm. + error-> warning: escape character ignored before 'P' + => I have 12 white elephants, said P. Pseudo Pachyderm. + + Escape sequence interpolation is of higher precedence than escape +sequence argument interpretation. This rule affords flexibility in +using escape sequences to construct parameters to other escape +sequences. + + .ds family C\" Courier + .ds style I\" oblique + Choice a typeface \f(\*[family]\*[style]wisely. + => Choose a typeface wisely. + +In the above, the syntax form '\f(' accepts only two characters for an +argument; the example works because the subsequent escape sequences are +interpolated before the selection escape sequence argument is processed, +and strings 'family' and 'style' interpolate one character each.(1) +(*note Using Escape Sequences-Footnote-1::) + + The escape character is nearly always interpreted when encountered; +it is therefore desirable to have a way to interpolate it, disable it, +or change it. + + -- Escape sequence: \e + Interpolate the escape character. + + The '\[rs]' special character escape sequence formats a backslash +glyph. In macro and string definitions, the input sequences '\\' and +'\E' defer interpretation of escape sequences. *Note Copy Mode::. + + -- Request: .eo + Disable the escape mechanism except in copy mode. Once this + request is invoked, no input character is recognized as starting an + escape sequence in interpretation mode. + + -- Request: .ec [o] + Recognize the ordinary character O as the escape character. If O + is absent or invalid, the default escape character '\' is selected. + + Switching escape sequence interpretation off to define a macro and +back on afterward can obviate the need to double the escape character +within the definition. *Note Writing Macros::. This technique is not +available if your macro needs to interpolate values at the time it is +_defined_--but many do not. + + .\" simplified `BR` macro from the man(7) macro package + .eo + .de BR + . ds result \& + . while (\n[.$] >= 2) \{\ + . as result \fB\$1\fR\$2\" + . shift 2 + . \} + . if \n[.$] .as result \fB\$1\" + \*[result] + . rm result + . ft R + .. + .ec + + -- Request: .ecs + -- Request: .ecr + The 'ecs' request stores the escape character for recall with + 'ecr'. 'ecr' sets the escape character to '\' if none has been + saved. + + Use these requests together to temporarily change the escape + character. + + Using a different escape character, or disabling it, when calling +macros not under your control will likely cause errors, since GNU +'troff' has no mechanism to "intern" macros--that is, to convert a macro +definition into a form independent of its representation.(2) (*note +Using Escape Sequences-Footnote-2::) When a macro is called, its +contents are interpreted literally. + + +File: groff.info, Node: Using Escape Sequences-Footnotes, Up: Using Escape Sequences + + (1) The omission of spaces before the comment escape sequences is +necessary; see *note Strings::. + + (2) TeX does have such a mechanism. + + +File: groff.info, Node: Delimiters, Prev: Using Escape Sequences, Up: Formatter Instructions + +5.6.5 Delimiters +---------------- + +Some escape sequences that require parameters use delimiters. The +neutral apostrophe ''' is a popular choice and shown in this document. +The neutral double quote '"' is also commonly seen. Letters, numerals, +and leaders can be used. Punctuation characters are likely better +choices, except for those defined as infix operators in numeric +expressions; see below. + + \l'1.5i\[bu]' \" draw 1.5 inches of bullet glyphs + + The following escape sequences don't take arguments and thus are +allowed as delimiters: '\<SP>', '\%', '\|', '\^', '\{', '\}', '\'', +'\`', '\-', '\_', '\!', '\?', '\)', '\/', '\,', '\&', '\:', '\~', '\0', +'\a', '\c', '\d', '\e', '\E', '\p', '\r', '\t', and '\u'. However, +using them this way is discouraged; they can make the input confusing to +read. + + A few escape sequences, '\A', '\b', '\o', '\w', '\X', and '\Z', +accept a newline as a delimiter. Newlines that serve as delimiters +continue to be recognized as input line terminators. + + A caf\o + e\(aa + in Paris + => A café in Paris + +Use of newlines as delimiters in escape sequences is also discouraged. + + Finally, the escape sequences '\D', '\h', '\H', '\l', '\L', '\N', +'\R', '\s', '\S', '\v', and '\x' prohibit many delimiters. + + * the numerals '0'-'9' and the decimal point '.' + + * the (single-character) operators '+-/*%<>=&:()' + + * the space and tab characters + + * any escape sequences other than '\%', '\:', '\{', '\}', '\'', '\`', + '\-', '\_', '\!', '\/', '\c', '\e', and '\p' + + Delimiter syntax is complex and flexible primarily for historical +reasons; the foregoing restrictions need be kept in mind mainly when +using 'groff' in AT&T compatibility mode. GNU 'troff' keeps track of +the nesting depth of escape sequence interpolations, so the only +characters you need to avoid using as delimiters are those that appear +in the arguments you input, not any that result from interpolation. +Typically, ''' works fine. *Note Implementation Differences::. + + $ groff -Tps + .de Mw + . nr wd \w'\\$1' + . tm "\\$1" is \\n(wd units wide. + .. + .Mw Wet'suwet'en + .Mw Wet+200i + .cp 1 \" turn on compatibility mode + .Mw Wet'suwet'en + .Mw Wet' + .Mw Wet+200i + error-> "Wet'suwet'en" is 54740 units wide. + error-> "Wet'+200i" is 42610 units wide. + error-> "Wet'suwet'en" is 15860 units wide. + error-> "Wet'" is 15860 units wide. + error-> "Wet'+200i" is 14415860 units wide. + + We see here that in compatibility mode, the part of the argument +after the ''' delimiter escapes from its context and, if nefariously +crafted, influences the computation of the WD register's value in a +surprising way. + + +File: groff.info, Node: Comments, Next: Registers, Prev: Formatter Instructions, Up: GNU troff Reference + +5.7 Comments +============ + +One of the most common forms of escape sequence is the comment.(1) +(*note Comments-Footnote-1::) + + -- Escape sequence: \" + Start a comment. Everything up to the next newline is ignored. + + This may sound simple, but it can be tricky to keep the comments + from interfering with the appearance of the output. If the escape + sequence is to the right of some text or a request, that portion of + the line is ignored, but spaces preceding it are processed normally + by GNU 'troff'. This affects only the 'ds' and 'as' requests and + their variants. + + One possibly irritating idiosyncrasy is that tabs should not be + used to vertically align comments in the source document. Tab + characters are not treated as separators between a request name and + its first argument, nor between arguments. + + A comment on a line by itself is treated as a blank line, because + after eliminating the comment, that is all that remains. + + Test + \" comment + Test + => Test + => + => Test + + To avoid this, it is common to combine the empty request with the + comment escape sequence as '.\"', causing the input line to be + ignored. + + Another commenting scheme sometimes seen is three consecutive + single quotes (''''') at the beginning of a line. This works, but + GNU 'troff' emits a warning diagnostic (if enabled) about an + undefined macro (namely ''''). + + -- Escape sequence: \# + Start a comment; everything up to and including the next newline is + ignored. This 'groff' extension was introduced to avoid the + problems described above. + + Test + \# comment + Test + => Test Test + + -- Request: .ig [end] + Ignore input until, in the current conditional block (if any),(2) + (*note Comments-Footnote-2::) the macro END is called at the start + of a control line, or the control line '..' is encountered if END + is not specified. 'ig' is parsed as if it were a macro definition, + but its contents are discarded, not stored.(3) (*note + Comments-Footnote-3::) + + hand\c + .de TX + fasting + .. + .ig TX + This is part of a large block of input that has been + temporarily(?) commented out. + We can restore it simply by removing the .ig request and + the call of its end macro. + .TX + => handfasting + + +File: groff.info, Node: Comments-Footnotes, Up: Comments + + (1) This claim may be more aspirational than descriptive. + + (2) *Note Conditional Blocks::. + + (3) Exception: auto-incrementing registers defined outside the +ignored region _will_ be modified if interpolated with '\n±' inside it. +*Note Auto-increment::. + + +File: groff.info, Node: Registers, Next: Manipulating Filling and Adjustment, Prev: Formatter Instructions, Up: GNU troff Reference + +5.8 Registers +============= + +In the 'roff' language, numbers can be stored in "registers". Many +built-in registers exist, supplying anything from the date to details of +formatting parameters. You can also define your own. *Note +Identifiers::, for information on constructing a valid name for a +register. + +* Menu: + +* Setting Registers:: +* Interpolating Registers:: +* Auto-increment:: +* Assigning Register Formats:: +* Built-in Registers:: + + +File: groff.info, Node: Setting Registers, Next: Interpolating Registers, Prev: Registers, Up: Registers + +5.8.1 Setting Registers +----------------------- + +Define registers and update their values with the 'nr' request or the +'\R' escape sequence. + + -- Request: .nr ident value + -- Escape sequence: \R'ident value' + Set register IDENT to VALUE. If IDENT doesn't exist, GNU 'troff' + creates it. In the '\R' escape sequence, the delimiter need not be + a neutral apostrophe; see *note Delimiters::. It also does not + produce an input token in GNU 'troff'. *Note Gtroff Internals::. + + .nr a (((17 + (3 * 4))) % 4) + \n[a] + .\R'a (((17 + (3 * 4))) % 4)' + \n[a] + => 1 1 + + (Later, we will discuss additional forms of 'nr' and '\R' that can + change a register's value after it is dereferenced but before it is + interpolated. *Note Auto-increment::.) + + The complete transparency of '\R' can cause surprising effects if + you use registers like '.k', which get evaluated at the time they + are accessed. + + .ll 1.6i + . + aaa bbb ccc ddd eee fff ggg hhh\R':k \n[.k]' + .tm :k == \n[:k] + => :k == 126950 + . + .br + . + aaa bbb ccc ddd eee fff ggg hhh\h'0'\R':k \n[.k]' + .tm :k == \n[:k] + => :k == 15000 + + If you process this with the PostScript device ('-Tps'), there will + be a line break eventually after 'ggg' in both input lines. + However, after processing the space after 'ggg', the partially + collected line is not overfull yet, so GNU 'troff' continues to + collect input until it sees the space (or in this case, the + newline) after 'hhh'. At this point, the line is longer than the + line length, and the line gets broken. + + In the first input line, since the '\R' escape sequence leaves no + traces, the check for the overfull line hasn't been done yet at the + point where '\R' gets handled, and you get a value for the '.k' + register that is even greater than the current line length. + + In the second input line, the insertion of '\h'0'' to cause a + zero-width motion forces GNU 'troff' to check the line length, + which in turn causes the start of a new output line. Now '.k' + returns the expected value. + + 'nr' and '\R' each have two additional special forms to increment or +decrement a register. + + -- Request: .nr ident +value + -- Request: .nr ident -value + -- Escape sequence: \R'ident +value' + -- Escape sequence: \R'ident -value' + Increment (decrement) register IDENT by VALUE. In the '\R' escape + sequence, the delimiter need not be a neutral apostrophe; see *note + Delimiters::. + + .nr a 1 + .nr a +1 + \na + => 2 + + A leading minus sign in VALUE is always interpreted as a + decrementation operator, not an algebraic sign. To assign a + register a negative value or the negated value of another register, + you can force GNU 'troff' to interpret '-' as a negation or minus, + rather than decrementation, operator: enclose it with its operand + in parentheses or subtract it from zero. + + .nr a 7 + .nr b 3 + .nr a -\nb + \na + => 4 + .nr a (-\nb) + \na + => -3 + .nr a 0-\nb + \na + => -3 + + If a register's prior value does not exist (the register was + undefined), an increment or decrement is applied as if to 0. + + -- Request: .rr ident + Remove register IDENT. If IDENT doesn't exist, the request is + ignored. Technically, only the name is removed; the register's + contents are still accessible under aliases created with 'aln', if + any. + + -- Request: .rnn ident1 ident2 + Rename register IDENT1 to IDENT2. If IDENT1 doesn't exist, the + request is ignored. Renaming a built-in register does not + otherwise alter its properties. + + -- Request: .aln new old + Create an alias NEW for an existing register OLD, causing the names + to refer to the same stored object. If OLD is undefined, a warning + in category 'reg' is produced and the request is ignored. *Note + Warnings::, for information about the enablement and suppression of + warnings. + + To remove a register alias, invoke 'rr' on its name. A register's + contents do not become inaccessible until it has no more names. + + +File: groff.info, Node: Interpolating Registers, Next: Auto-increment, Prev: Setting Registers, Up: Registers + +5.8.2 Interpolating Registers +----------------------------- + +Register contents are interpolated with the '\n' escape sequence. + + -- Escape sequence: \ni + -- Escape sequence: \n(id + -- Escape sequence: \n[ident] + Interpolate register with name IDENT (one-character name I, + two-character name ID). '\n' is interpreted even in copy mode + (*note Copy Mode::). If the register is undefined, it is created + and assigned a value of '0', that value is interpolated, and a + warning in category 'reg' is emitted. *Note Warnings::, for + information about the enablement and suppression of warnings. + + .nr a 5 + .nr as \na+\na + \n(as + => 10 + + .nr a1 5 + .nr ab 6 + .ds str b + .ds num 1 + \n[a\n[num]] + => 5 + \n[a\*[str]] + => 6 + + +File: groff.info, Node: Auto-increment, Next: Assigning Register Formats, Prev: Interpolating Registers, Up: Registers + +5.8.3 Auto-increment +-------------------- + +Registers can also be incremented or decremented by a configured amount +at the time they are interpolated. The value of the increment is +specified with a third argument to the 'nr' request, and a special +interpolation syntax is used to alter and then retrieve the register's +value. Together, these features are called "auto-increment".(1) (*note +Auto-increment-Footnote-1::) + + -- Request: .nr ident value incr + Set register IDENT to VALUE and its auto-incrementation amount to + to INCR. The '\R' escape sequence doesn't support an INCR + argument. + + Auto-incrementation is not _completely_ automatic; the '\n' escape +sequence in its basic form never alters the value of a register. To +apply auto-incrementation to a register, interpolate it with '\n±'. + + -- Escape sequence: \n+i + -- Escape sequence: \n-i + -- Escape sequence: \n+(id + -- Escape sequence: \n-(id + -- Escape sequence: \n+[ident] + -- Escape sequence: \n-[ident] + Increment or decrement IDENT (one-character name I, two-character + name ID) by the register's auto-incrementation value and then + interpolate the new register value. If IDENT has no + auto-incrementation value, interpolate as with '\n'. + + .nr a 0 1 + .nr xx 0 5 + .nr foo 0 -2 + \n+a, \n+a, \n+a, \n+a, \n+a + .br + \n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx + .br + \n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo] + => 1, 2, 3, 4, 5 + => -5, -10, -15, -20, -25 + => -2, -4, -6, -8, -10 + + To change the increment value without changing the value of a +register, assign the register's value to itself by interpolating it, and +specify the desired increment normally. Apply an increment of '0' to +disable auto-incrementation of the register. + + +File: groff.info, Node: Auto-increment-Footnotes, Up: Auto-increment + + (1) A negative auto-increment can be considered an "auto-decrement". + + +File: groff.info, Node: Assigning Register Formats, Next: Built-in Registers, Prev: Auto-increment, Up: Registers + +5.8.4 Assigning Register Formats +-------------------------------- + +A writable register's value can be interpolated in several number +formats. By default, conventional Arabic numerals are used. Other +formats see use in sectioning and outlining schemes and alternative page +numbering arrangements. + + -- Request: .af reg fmt + Use number format FMT when interpolating register REG. Valid + number formats are as follows. + + '0...' + Arabic numerals 0, 1, 2, and so on. Any decimal digit is + equivalent to '0'; the formatter merely counts the digits + specified. Multiple Arabic numerals in FMT cause + interpolations to be zero-padded on the left if necessary to + at least as many digits as specified (interpolations never + truncate a register value). A register with format '00' + interpolates values 1, 2, 3 as '01', '02', '03'. The default + format for all writable registers is '0'. + + 'I' + Uppercase Roman numerals: 0, I, II, III, IV, ... + + 'i' + Lowercase Roman numerals: 0, i, ii, iii, iv, ... + + 'A' + Uppercase letters: 0, A, B, C, ..., Z, AA, AB, ... + + 'a' + Lowercase letters: 0, a, b, c, ..., z, aa, ab, ... + + Omitting FMT causes a warning in category 'missing'. *Note + Warnings::, for information about the enablement and suppression of + warnings. Specifying an unrecognized format is an error. + + Zero values are interpolated as '0' in non-Arabic formats. + Negative quantities are prefixed with '-' irrespective of format. + In Arabic formats, the sign supplements the field width. If REG + doesn't exist, it is created with a zero value. + + .nr a 10 + .af a 0 \" the default format + \na, + .af a I + \na, + .af a 321 + .nr a (-\na) + \na, + .af a a + \na + => 10, X, -010, -j + + The representable extrema in the 'i' and 'I' formats correspond to + Arabic ±39,999. GNU 'troff' uses 'w' and 'z' to represent 5,000 + and 10,000 in Roman numerals, respectively, following the + convention of AT&T 'troff'--currently, the correct glyphs for Roman + numerals five thousand ('U+2181') and ten thousand ('U+2182') are + not used. + + Assigning the format of a read-only register is an error. Instead, + copy the read-only register's value to, and assign the format of, a + writable register. + + -- Escape sequence: \gr + -- Escape sequence: \g(rg + -- Escape sequence: \g[reg] + Interpolate the format of the register REG (one-character name R, + two-character name RG). Zeroes represent Arabic formats. If REG + is not defined, REG is not created and nothing is interpolated. + '\g' is interpreted even in copy mode (*note Copy Mode::). + + GNU 'troff' interprets only Arabic numerals. The Roman numeral or +alphabetic formats cannot be used as operands to arithmetic operators in +expressions (*note Numeric Expressions::). For instance, it may be +desirable to test the page number independently of its format. + + .af % i \" front matter + .de header-trap + . \" To test the page number, we need it in Arabic. + . ds saved-page-number-format \\g%\" + . af % 0 + . nr page-number-in-decimal \\n% + . af % \\*[saved-page-number-format] + . ie \\n[page-number-in-decimal]=1 .do-first-page-stuff + . el \{\ + . ie o .do-odd-numbered-page-stuff + . el .do-even-numbered-page-stuff + . \} + . rm saved-page-number-format + .. + .wh 0 header-trap + + +File: groff.info, Node: Built-in Registers, Prev: Assigning Register Formats, Up: Registers + +5.8.5 Built-in Registers +------------------------ + +Predefined registers whose identifiers start with a dot are read-only. +Many are Boolean-valued, interpolating a true or false value testable +with the 'if', 'ie', or 'while' requests. Some read-only registers are +string-valued, meaning that they interpolate text. + + *Caution:* Built-in registers are subject to removal like others; +once removed, they can be recreated only as normal writable registers +and will not reflect formatter state. + + A register name (without the dot) is often associated with a request +of the same name. A complete listing of all built-in registers can be +found in *note Register Index::. + + We present here a few built-in registers that are not described +elsewhere in this manual; they have to do with invariant properties of +GNU 'troff', or obtain information about the formatter's command-line +options, processing progress, or the operating environment. + +'\n[.A]' + Approximate output is being formatted (Boolean-valued); see 'groff' + '-a' option (*note Groff Options::). + +'\n[.c]' +'\n[c.]' + Input line number. 'c.' is a writable synonym, affecting + subsequent interpolations of both '.c' and 'c.'. + +'\n[.F]' + Name of input file (string-valued). + +'\n[.g]' + Always true in GNU 'troff' (Boolean-valued). Documents can use + this to ask the formatter if it claims 'groff' compatibility. + +'\n[.P]' + Output page selection status (Boolean-valued); see 'groff' '-o' + option (*note Groff Options::). + +'\n[.R]' + Count of available unused registers; always 10,000 in GNU + 'troff'.(1) (*note Built-in Registers-Footnote-1::) + +'\n[.T]' + Indicator of output device selection (Boolean-valued); see 'groff' + '-T' option (*note Groff Options::). + +'\n[.U]' + Unsafe mode enablement status (Boolean-valued); see 'groff' '-U' + option (*note Groff Options::). + +'\n[.x]' + Major version number of the running GNU 'troff' formatter. For + example, if the version number is 1.23.0, then '.x' contains '1'. + +'\n[.y]' + Minor version number of the running GNU 'troff' formatter. For + example, if the version number is 1.23.0, then '.y' contains '23'. + +'\n[.Y]' + Revision number of the running GNU 'troff' formatter. For example, + if the version number is 1.23.0, then '.Y' contains '0'. + +'\n[$$]' + Process identifier (PID) of the GNU 'troff' program in its + operating environment. + + Date- and time-related registers are set per the local time as +determined by 'localtime(3)' when the formatter launches. This +initialization can be overridden by 'SOURCE_DATE_EPOCH' and 'TZ'; see +*note Environment::. + +'\n[seconds]' + Count of seconds elapsed in the minute (0-60). + +'\n[minutes]' + Count of minutes elapsed in the hour (0-59). + +'\n[hours]' + Count of hours elapsed since midnight (0-23). + +'\n[dw]' + Day of the week (1-7; 1 is Sunday). + +'\n[dy]' + Day of the month (1-31). + +'\n[mo]' + Month of the year (1-12). + +'\n[year]' + Gregorian year. + +'\n[yr]' + Gregorian year minus 1900. This register is incorrectly documented + in the AT&T 'troff' manual as storing the last two digits of the + current year. That claim stopped being true in 2000. Old 'troff' + input that looks like: + + '\" The year number is a surprise after 1999. + This document was formatted in 19\n(yr. + + can be corrected to: + + This document was formatted in \n[year]. + + or, for portability across many 'roff' programs, to the following. + + .nr y4 1900+\n(yr + This document was formatted in \n(y4. + + +File: groff.info, Node: Built-in Registers-Footnotes, Up: Built-in Registers + + (1) GNU 'troff' dynamically allocates memory for as many registers as +required. + + +File: groff.info, Node: Manipulating Filling and Adjustment, Next: Manipulating Hyphenation, Prev: Registers, Up: GNU troff Reference + +5.9 Manipulating Filling and Adjustment +======================================= + +When an output line is pending (see below), a break moves the drawing +position to the beginning of the next text baseline, interrupting +filling. Various ways of causing breaks were shown in *note Breaking::. +The 'br' request likewise causes a break. Several other requests imply +breaks: 'bp', 'ce', 'cf', 'fi', 'fl', 'in', 'nf', 'rj', 'sp', 'ti', and +'trf'. If the no-break control character is used with any of these +requests, GNU 'troff' suppresses the break; instead the requested +operation takes effect at the next break. ''br' does nothing. + + .ll 55n + This line is normally filled and adjusted. + .br + A line's alignment is decided + 'ce \" Center the next input line (no break). + when it is output. + This line returns to normal filling and adjustment. + => This line is normally filled and adjusted. + => A line's alignment is decided when it is output. + => This line returns to normal filling and adjustment. + +Output line properties like page offset, indentation, adjustment, and +even the location of its text baseline, are not determined until the +line has been broken. An output line is said to be "pending" if some +input has been collected but an output line corresponding to it has not +yet been written; such an output line is also termed "partially +collected". If no output line is pending, it is as if a break has +already happened; additional breaks, whether explicit or implicit, have +no effect. If the vertical drawing position is negative--as it is when +the formatter starts up--a break starts a new page (even if no output +line is pending) unless an end-of-input macro is being interpreted. +*Note End-of-input Traps::. + + -- Request: .br + Break the line: emit any pending output line without adjustment. + + foo bar + .br + baz + 'br + qux + => foo bar + => baz qux + + Sometimes you want to prevent a break within a phrase or between a +quantity and its units. + + -- Escape sequence: \~ + Insert an unbreakable space that is adjustable like an ordinary + space. It is discarded from the end of an output line if a break + is forced. + + Set the output speed to\~1. + There are 1,024\~bytes in 1\~KiB. + J.\~F.\~Ossanna wrote the original CSTR\~#54. + + By default, GNU 'troff' fills text and adjusts it to reach the output +line length. The 'nf' request disables filling; the 'fi' request +reënables it. + + -- Request: .fi + -- Register: \n[.u] + Enable filling of output lines; a pending output line is broken. + The read-only register '.u' is set to 1. The filling enablement + status, sometimes called "fill mode", is associated with the + environment (*note Environments::). *Note Line Continuation::, for + interaction with the '\c' escape sequence. + + -- Request: .nf + Disable filling of output lines: the output line length (*note Line + Layout::) is ignored and output lines are broken where the input + lines are. A pending output line is broken and adjustment is + suppressed. The read-only register '.u' is set to 0. The filling + enablement status is associated with the environment (*note + Environments::). See *note Line Continuation::, for interaction + with the '\c' escape sequence. + + -- Request: .ad [mode] + -- Register: \n[.j] + Enable output line adjustment in MODE, taking effect when the + pending (or next) output line is broken. Adjustment is suppressed + when filling is. MODE can have one of the following values. + + 'b' + 'n' + Adjust "normally": if the output line does not consume the + distance between the indentation and the configured output + line length, GNU 'troff' stretches adjustable spaces within + the line until that length is reached. When the indentation + is zero, this mode spreads the line to both the left and right + margins. This is the GNU 'troff' default. + + 'c' + Center filled text. Contrast with the 'ce' request, which + centers text _without_ filling it. + + 'l' + Align text to the left without adjusting it. + + 'r' + Align text to the right without adjusting it. + + MODE can also be a value previously stored in the '.j' register. + Using 'ad' without an argument is the same as '.ad \n[.j]'; unless + filling is disabled, GNU 'troff' resumes adjusting lines in the + same way it did before adjustment was disabled by invocation of the + 'na' request. + + The adjustment mode and enablement status are encoded in the + read-only register '.j'. These parameters are associated with the + environment (*note Environments::). + + The value of '.j' for any adjustment mode is an implementation + detail and should not be relied upon as a programmer's interface. + Do not write logic to interpret or perform arithmetic on it. + + .ll 48n + .de AD + . br + . ad \\$1 + .. + .de NA + . br + . na + .. + left + .AD r + .nr ad \n(.j + right + .AD c + center + .NA + left + .AD + center + .AD \n(ad + right + => left + => right + => center + => left + => center + => right + + -- Request: .na + Disable output line adjustment. This produces the same output as + left-alignment, but the value of the adjustment mode register '.j' + is altered differently. The adjustment mode and enablement status + are associated with the environment (*note Environments::). + + -- Request: .brp + -- Escape sequence: \p + Break, adjusting the line per the current adjustment mode. '\p' + schedules a break with adjustment at the next word boundary. The + escape sequence is itself neither a break nor a space of any kind; + it can thus be placed in the middle of a word to cause a break at + the end of that word. + + Breaking with immediate adjustment can produce ugly results since + GNU 'troff' doesn't have a sophisticated paragraph-building + algorithm, as TeX has, for example. Instead, GNU 'troff' fills and + adjusts a paragraph line by line. + + .ll 4.5i + This is an uninteresting sentence. + This is an uninteresting sentence.\p + This is an uninteresting sentence. + + is formatted as follows. + + This is an uninteresting sentence. This is + an uninteresting sentence. + This is an uninteresting sentence. + + To clearly present the next couple of requests, we must introduce the +concept of "productive" input lines. A "productive input line" is one +that directly produces formatted output. Text lines produce output,(1) +(*note Manipulating Filling and Adjustment-Footnote-1::) as do control +lines containing requests like 'tl' or escape sequences like '\D'. +Macro calls are not _directly_ productive, and thus not counted, but +their interpolated contents can be. Empty requests, and requests and +escape sequences that define registers or strings or alter the +formatting environment (as with changes to the size, face, height, +slant, or color of the type) are not productive. We will also preview +the output line continuation escape sequence, '\c', which "connects" two +input lines that would otherwise be counted separately. (2) (*note +Manipulating Filling and Adjustment-Footnote-2::) + + .de hello + Hello, world! + .. + .ce \" center output of next productive input line + . + .nr junk-reg 1 + .ft I + Chorus: \c + .ft + .hello + Went the day well? + => Chorus: Hello, world! + => Went the day well? + + -- Request: .ce [n] + -- Register: \n[.ce] + Break (unless the no-break control character is used), center the + output of the next N productive input lines with respect to the + line length and indentation without filling, then break again + regardless of the invoking control character. If the argument is + not positive, centering is disabled. Omitting the argument implies + an N of '1'. The count of lines remaining to be centered is stored + in the read-only register '.ce' and is associated with the + environment (*note Environments::). + + While the '.ad c' request also centers text, it fills the text as + well. + + .de FR + This is a small text fragment that shows the differences + between the `.ce' and the `.ad c' requests. + .. + .ll 4i + .ce 1000 + .FR + .ce 0 + + .ad c + .FR + => This is a small text fragment that shows + => the differences + => between the `.ce' and the `.ad c' requests. + => + => This is a small text fragment that shows + => the differences between the `.ce' and + => the `.ad c' requests. + + The previous example illustrates a common idiom of turning + centering on for a quantity of lines far in excess of what is + required, and off again after the text to be centered. This + technique relieves humans of counting lines for requests that take + a count of input lines as an argument. + + -- Request: .rj [n] + -- Register: \n[.rj] + Break (unless the no-break control character is used), align the + output of the next N productive input lines to the right margin + without filling, then break again regardless of the control + character. If the argument is not positive, right-alignment is + disabled. Omitting the argument implies an N of '1'. The count of + lines remaining to be right-aligned is stored in the read-only + register '.rj' and is associated with the environment (*note + Environments::). + + .ll 49n + .rj 3 + At first I hoped that such a technically unsound + project would collapse but I soon realized it was + doomed to success. \[em] C. A. R. Hoare + => At first I hoped that such a technically unsound + => project would collapse but I soon realized it was + => doomed to success. -- C. A. R. Hoare + + -- Request: .ss word-space-size [additional-sentence-space-size] + -- Register: \n[.ss] + -- Register: \n[.sss] + Set the sizes of spaces between words and sentences(3) (*note + Manipulating Filling and Adjustment-Footnote-3::) in twelfths of + font's space width (typically one-fourth to one-third em for + Western scripts). The default for both parameters is 12. Negative + values are erroneous. The first argument is a minimum; if an + output line undergoes adjustment, such spaces may increase in + width. The optional second argument sets the amount of additional + space separating sentences on the same output line. If omitted, + this amount is set to WORD-SPACE-SIZE. The request is ignored if + there are no parameters. + + Additional inter-sentence space is used only if the output line is + not full when the end of a sentence occurs in the input. If a + sentence ends at the end of an input line, then both an inter-word + space and an inter-sentence space are added to the output; if two + spaces follow the end of a sentence in the middle of an input line, + then the second space becomes an inter-sentence space in the + output. Additional inter-sentence space is not adjusted, but the + inter-word space that always precedes it may be. Further input + spaces after the second, if present, are adjusted as normal. + + The read-only registers '.ss' and '.sss' hold the minimal + inter-word space and additional inter-sentence space amounts, + respectively. These parameters are part of the environment (*note + Environments::), and rounded down to the nearest multiple of 12 on + terminals. + + The 'ss' request can insert discardable horizontal space; that is, + space that is discarded at a break. For example, some footnote + styles collect the notes into a single paragraph with large gaps + between each note. + + .ll 48n + 1.\~J. Fict. Ch. Soc. 6 (2020), 3\[en]14. + .ss 12 48 \" applies to next sentence ending + Reprints no longer available through FCS. + .ss 12 \" go back to normal + 2.\~Better known for other work. + => 1. J. Fict. Ch. Soc. 6 (2020), 3-14. Reprints + => no longer available through FCS. 2. Better + => known for other work. + + If _undiscardable_ space is required, use the '\h' escape sequence. + + +File: groff.info, Node: Manipulating Filling and Adjustment-Footnotes, Up: Manipulating Filling and Adjustment + + (1) unless diverted; see *note Diversions:: + + (2) *Note Line Continuation::. + + (3) Recall *note Filling:: and *note Sentences:: for the definitions +of word and sentence boundaries, respectively. + + +File: groff.info, Node: Manipulating Hyphenation, Next: Manipulating Spacing, Prev: Manipulating Filling and Adjustment, Up: GNU troff Reference + +5.10 Manipulating Hyphenation +============================= + +When filling, GNU 'troff' hyphenates words as needed at user-specified +and automatically determined hyphenation points. The machine-driven +determination of hyphenation points in words requires algorithms and +data, and is susceptible to conventions and preferences. Before +tackling such "automatic hyphenation", let us consider how hyphenation +points can be set explicitly. + + Explicitly hyphenated words such as "mother-in-law" are eligible for +breaking after each of their hyphens. Relatively few words in a +language offer such obvious break points, however, and automatic +detection of syllabic (or phonetic) boundaries for hyphenation is not +perfect,(1) (*note Manipulating Hyphenation-Footnote-1::) particularly +for unusual words found in technical literature. We can instruct GNU +'troff' how to hyphenate specific words if the need arises. + + -- Request: .hw word ... + Define each "hyphenation exception" WORD with each hyphen '-' in + the word indicating a hyphenation point. For example, the request + + .hw in-sa-lub-rious alpha + + marks potential hyphenation points in "insalubrious", and prevents + "alpha" from being hyphenated at all. + + Besides the space character, any character whose hyphenation code + is zero can be used to separate the arguments of 'hw' (see the + 'hcode' request below). In addition, this request can be used more + than once. + + Hyphenation points specified with 'hw' are not subject to the + within-word placement restrictions imposed by the 'hy' request (see + below). + + Hyphenation exceptions specified with the 'hw' request are + associated with the hyphenation language (see the 'hla' request + below) and environment (*note Environments::); invoking the 'hw' + request in the absence of a hyphenation language is an error. + + The request is ignored if there are no parameters. + + These are known as hyphenation exceptions in the expectation that +most users will avail themselves of automatic hyphenation; these +exceptions override any rules that would normally apply to a word +matching a hyphenation exception defined with 'hw'. + + Situations also arise when only a specific occurrence of a word needs +its hyphenation altered or suppressed, or when a URL or similar string +needs to be breakable in sensible places without hyphenation. + + -- Escape sequence: \% + -- Escape sequence: \: + To tell GNU 'troff' how to hyphenate words as they occur in input, + use the '\%' escape sequence; it is the default "hyphenation + character". Each instance within a word indicates to GNU 'troff' + that the word may be hyphenated at that point, while prefixing a + word with this escape sequence prevents it from being otherwise + hyphenated. This mechanism affects only that occurrence of the + word; to change the hyphenation of a word for the remainder of + input processing, use the 'hw' request. + + GNU 'troff' regards the escape sequences '\X' and '\Y' as starting + a word; that is, the '\%' escape sequence in, say, + '\X'...'\%foobar' or '\Y'...'\%foobar' no longer prevents + hyphenation of 'foobar' but inserts a hyphenation point just prior + to it; most likely this isn't what you want. *Note Postprocessor + Access::. + + '\:' inserts a non-printing break point; that is, a word can break + there, but the soft hyphen glyph (see below) is not written to the + output if it does. This escape sequence is an input word boundary, + so the remainder of the word is subject to hyphenation as normal. + + You can combine '\:' and '\%' to control breaking of a file name or + URL, or to permit hyphenation only after certain explicit hyphens + within a word. + + The \%Lethbridge-Stewart-\:\%Sackville-Baggins divorce + was, in retrospect, inevitable once the contents of + \%/var/log/\:\%httpd/\:\%access_log on the family web + server came to light, revealing visitors from Hogwarts. + + -- Request: .hc [char] + Change the hyphenation character to CHAR. This character then + works as the '\%' escape sequence normally does, and thus no longer + appears in the output.(2) (*note Manipulating + Hyphenation-Footnote-2::) Without an argument, 'hc' resets the + hyphenation character to '\%' (the default). The hyphenation + character is associated with the environment (*note + Environments::). + + -- Request: .shc [c] + Set the "soft hyphen character", inserted when a word is hyphenated + automatically or at a hyphenation character, to the ordinary or + special character C.(3) (*note Manipulating + Hyphenation-Footnote-3::) If the argument is omitted, the soft + hyphen character is set to the default, '\[hy]'. If no glyph for C + exists in the font in use at a potential hyphenation point, then + the line is not broken there. Neither character definitions + (specified with the 'char' and similar requests) nor translations + (specified with the 'tr' request) are applied to C. + + Several requests influence automatic hyphenation. Because +conventions vary, a variety of hyphenation modes is available to the +'hy' request; these determine whether hyphenation will apply to a word +prior to breaking a line at the end of a page (more or less; see below +for details), and at which positions within that word automatically +determined hyphenation points are permissible. The places within a word +that are eligible for hyphenation are determined by language-specific +data and lettercase relationships. Furthermore, hyphenation of a word +might be suppressed due to a limit on consecutive hyphenated lines +('hlm'), a minimum line length threshold ('hym'), or because the line +can instead be adjusted with additional inter-word space ('hys'). + + -- Request: .hy [mode] + -- Register: \n[.hy] + Set automatic hyphenation mode to MODE, an integer encoding + conditions for hyphenation; if omitted, '1' is implied. The + hyphenation mode is available in the read-only register '.hy'; it + is associated with the environment (*note Environments::). The + default hyphenation mode depends on the localization file loaded + when GNU 'troff' starts up; see the 'hpf' request below. + + Typesetting practice generally does not avail itself of every + opportunity for hyphenation, but the details differ by language and + site mandates. The hyphenation modes of AT&T 'troff' were + implemented with English-language publishing practices of the 1970s + in mind, not a scrupulous enumeration of conceivable parameters. + GNU 'troff' extends those modes such that finer-grained control is + possible, favoring compatibility with older implementations over a + more intuitive arrangement. The means of hyphenation mode control + is a set of numbers that can be added up to encode the behavior + sought.(4) (*note Manipulating Hyphenation-Footnote-4::) The + entries in the following table are termed "values"; the sum of the + desired values is the "mode". + + '0' + disables hyphenation. + + '1' + enables hyphenation except after the first and before the last + character of a word. + + The remaining values "imply" 1; that is, they enable hyphenation + under the same conditions as '.hy 1', and then apply or lift + restrictions relative to that basis. + + '2' + disables hyphenation of the last word on a page,(5) (*note + Manipulating Hyphenation-Footnote-5::) even for explicitly + hyphenated words. + + '4' + disables hyphenation before the last two characters of a word. + + '8' + disables hyphenation after the first two characters of a word. + + '16' + enables hyphenation before the last character of a word. + + '32' + enables hyphenation after the first character of a word. + + Apart from value 2, restrictions imposed by the hyphenation mode + are _not_ respected for words whose hyphenations have been + specified with the hyphenation character ('\%' by default) or the + 'hw' request. + + Nonzero values in the previous table are additive. For example, + mode 12 causes GNU 'troff' to hyphenate neither the last two nor + the first two characters of a word. Some values cannot be used + together because they contradict; for instance, values 4 and 16, + and values 8 and 32. As noted, it is superfluous to add 1 to any + non-zero even mode. + + The automatic placement of hyphens in words is determined by + "pattern files", which are derived from TeX and available for + several languages. The number of characters at the beginning of a + word after which the first hyphenation point should be inserted is + determined by the patterns themselves; it can't be reduced further + without introducing additional, invalid hyphenation points + (unfortunately, this information is not part of a pattern file--you + have to know it in advance). The same is true for the number of + characters at the end of a word before the last hyphenation point + should be inserted. For example, you can supply the following + input to 'echo $(nroff)'. + + .ll 1 + .hy 48 + splitting + + You will get + + s- plit- t- in- g + + instead of the correct 'split- ting'. English patterns as + distributed with GNU 'troff' need two characters at the beginning + and three characters at the end; this means that value 4 of 'hy' is + mandatory. Value 8 is possible as an additional restriction, but + values 16 and 32 should be avoided, as should mode 1. Modes 4 + and 6 are typical. + + A table of left and right minimum character counts for hyphenation + as needed by the patterns distributed with GNU 'troff' follows; see + the 'groff_tmac(5)' man page for more information on GNU 'troff''s + language macro files. + + language pattern name left min right min + ----------------------------------------------------------- + Czech cs 2 2 + English en 2 3 + French fr 2 3 + German traditional det 2 2 + German reformed den 2 2 + Italian it 2 2 + Swedish sv 1 2 + + Hyphenation exceptions within pattern files (i.e., the words within + a TeX '\hyphenation' group) obey the hyphenation restrictions given + by 'hy'. + + -- Request: .nh + Disable automatic hyphenation; i.e., set the hyphenation mode to 0 + (see above). The hyphenation mode of the last call to 'hy' is not + remembered. + + -- Request: .hpf pattern-file + -- Request: .hpfa pattern-file + -- Request: .hpfcode a b [c d] ... + Read hyphenation patterns from PATTERN-FILE, which is sought in the + same way that macro files are with the 'mso' request or the + '-mNAME' command-line option to 'groff'. The PATTERN-FILE should + have the same format as (simple) TeX pattern files. More + specifically, the following scanning rules are implemented. + + * A percent sign starts a comment (up to the end of the line) + even if preceded by a backslash. + + * "Digraphs" like '\$' are not supported. + + * '^^XX' (where each X is 0-9 or a-f) and '^^C' (character C in + the code point range 0-127 decimal) are recognized; other uses + of '^' cause an error. + + * No macro expansion is performed. + + * 'hpf' checks for the expression '\patterns{...}' (possibly + with whitespace before or after the braces). Everything + between the braces is taken as hyphenation patterns. + Consequently, '{' and '}' are not allowed in patterns. + + * Similarly, '\hyphenation{...}' gives a list of hyphenation + exceptions. + + * '\endinput' is recognized also. + + * For backward compatibility, if '\patterns' is missing, the + whole file is treated as a list of hyphenation patterns + (except that the '%' character is recognized as the start of a + comment). + + The 'hpfa' request appends a file of patterns to the current list. + + The 'hpfcode' request defines mapping values for character codes in + pattern files. It is an older mechanism no longer used by GNU + 'troff''s own macro files; for its successor, see 'hcode' below. + 'hpf' or 'hpfa' apply the mapping after reading the patterns but + before replacing or appending to the active list of patterns. Its + arguments are pairs of character codes--integers from 0 to 255. + The request maps character code A to code B, code C to code D, and + so on. Character codes that would otherwise be invalid in GNU + 'troff' can be used. By default, every code maps to itself except + those for letters 'A' to 'Z', which map to those for 'a' to 'z'. + + The set of hyphenation patterns is associated with the language set + by the 'hla' request (see below). The 'hpf' request is usually + invoked by a localization file loaded by the 'troffrc' file.(6) + (*note Manipulating Hyphenation-Footnote-6::) + + A second call to 'hpf' (for the same language) replaces the + hyphenation patterns with the new ones. Invoking 'hpf' or 'hpfa' + causes an error if there is no hyphenation language. If no 'hpf' + request is specified (either in the document, in a file loaded at + startup, or in a macro package), GNU 'troff' won't automatically + hyphenate at all. + + -- Request: .hcode c1 code1 [c2 code2] ... + Set the hyphenation code of character C1 to CODE1, that of C2 to + CODE2, and so on. A hyphenation code must be an ordinary character + (not a special character escape sequence) other than a digit or a + space. The request is ignored if given no arguments. + + For hyphenation to work, hyphenation codes must be set up. At + startup, GNU 'troff' assigns hyphenation codes to the letters + 'a'-'z' (mapped to themselves), to the letters 'A'-'Z' (mapped to + 'a'-'z'), and zero to all other characters. Normally, hyphenation + patterns contain only lowercase letters which should be applied + regardless of case. In other words, they assume that the words + 'FOO' and 'Foo' should be hyphenated exactly as 'foo' is. The + 'hcode' request extends this principle to letters outside the + Unicode basic Latin alphabet; without it, words containing such + letters won't be hyphenated properly even if the corresponding + hyphenation patterns contain them. + + For example, the following 'hcode' requests are necessary to assign + hyphenation codes to the letters 'ÄäÖöÜüß', needed for German. + + .hcode ä ä Ä ä + .hcode ö ö Ö ö + .hcode ü ü Ü ü + .hcode ß ß + + Without these assignments, GNU 'troff' treats the German word + 'Kindergärten' (the plural form of 'kindergarten') as two words + 'kinderg' and 'rten' because the hyphenation code of the umlaut a + is zero by default, just like a space. There is a German + hyphenation pattern that covers 'kinder', so GNU 'troff' finds the + hyphenation 'kin-der'. The other two hyphenation points + ('kin-der-gär-ten') are missed. + + -- Request: .hla lang + -- Register: \n[.hla] + Set the hyphenation language to LANG. Hyphenation exceptions + specified with the 'hw' request and hyphenation patterns and + exceptions specified with the 'hpf' and 'hpfa' requests are + associated with the hyphenation language. The 'hla' request is + usually invoked by a localization file, which is turn loaded by the + 'troffrc' or 'troffrc-end' file; see the 'hpf' request above. + + The hyphenation language is available in the read-only + string-valued register '.hla'; it is associated with the + environment (*note Environments::). + + -- Request: .hlm [n] + -- Register: \n[.hlm] + -- Register: \n[.hlc] + Set the maximum quantity of consecutive hyphenated lines to N. If + N is negative, there is no maximum. If omitted, N is -1. This + value is associated with the environment (*note Environments::). + Only lines output from a given environment count toward the maximum + associated with that environment. Hyphens resulting from '\%' are + counted; explicit hyphens are not. + + The '.hlm' read-only register stores this maximum. The count of + immediately preceding consecutive hyphenated lines is available in + the read-only register '.hlc'. + + -- Request: .hym [length] + -- Register: \n[.hym] + Set the (right) hyphenation margin to LENGTH. If the adjustment + mode is not 'b' or 'n', the line is not hyphenated if it is shorter + than LENGTH. Without an argument, the hyphenation margin is reset + to its default value, 0. The default scaling unit is 'm'. The + hyphenation margin is associated with the environment (*note + Environments::). + + A negative argument resets the hyphenation margin to zero, emitting + a warning in category 'range'. + + The hyphenation margin is available in the '.hym' read-only + register. + + -- Request: .hys [hyphenation-space] + -- Register: \n[.hys] + Suppress hyphenation of the line in adjustment modes 'b' or 'n' if + it can be justified by adding no more than HYPHENATION-SPACE extra + space to each inter-word space. Without an argument, the + hyphenation space adjustment threshold is set to its default value, + 0. The default scaling unit is 'm'. The hyphenation space + adjustment threshold is associated with the environment (*note + Environments::). + + A negative argument resets the hyphenation space adjustment + threshold to zero, emitting a warning in category 'range'. + + The hyphenation space adjustment threshold is available in the + '.hys' read-only register. + + +File: groff.info, Node: Manipulating Hyphenation-Footnotes, Up: Manipulating Hyphenation + + (1) Whether a perfect algorithm for this application is even possible +is an unsolved problem in computer science: +<https://tug.org/docs/liang/liang-thesis.pdf>. + + (2) '\%' itself stops marking hyphenation points but still produces +no output glyph. + + (3) "Soft" because it appears in output only where a hyphenation +break is performed; a "hard" hyphen, as in "long-term", always appears. + + (4) The mode is a vector of Booleans encoded as an integer. To a +programmer, this fact is easily deduced from the exclusive use of powers +of two for the configuration parameters; they are computationally easy +to "mask off" and compare to zero. To almost everyone else, the +arrangement seems recondite and unfriendly. + + (5) Hyphenation is prevented if the next page location trap is closer +to the vertical drawing position than the next text baseline would be. +*Note Page Location Traps::. + + (6) For more on localization, see the 'groff_tmac(5)' man page. + + +File: groff.info, Node: Manipulating Spacing, Next: Tabs and Fields, Prev: Manipulating Hyphenation, Up: GNU troff Reference + +5.11 Manipulating Spacing +========================= + +A break causes the formatter to update the vertical drawing position at +which the new text baseline is aligned. You can alter this location. + + -- Request: .sp [distance] + Break and move the next text baseline down by DISTANCE, or until + springing a page location trap.(1) (*note Manipulating + Spacing-Footnote-1::) If invoked with the no-break control + character, 'sp' moves the pending output line's text baseline by + DISTANCE. A negative DISTANCE will not reduce the position of the + text baseline below zero. Inside a diversion, any DISTANCE + argument is ignored. The default scaling unit is 'v'. If DISTANCE + is not specified, '1v' is assumed. + + .pl 5v \" Set page length to 5 vees. + .de xx + \-\-\- + . br + .. + .wh 0 xx \" Set a trap at the top of the page. + foo on page \n% + .sp 2v + bar on page \n% + .sp 50v \" This will cause a page break. + baz on page \n% + .pl \n(nlu \" Truncate page to current position. + => --- + => foo on page 1 + => + => + => bar on page 1 + => --- + => baz on page 2 + + You might use the following macros to set the baseline of the next + output text at a given distance from the top or the bottom of the + page. We subtract one line height ('\n[.v]') because the '|' + operator moves to one vee below the page top (recall *note Numeric + Expressions::). + + .de y-from-top-down + . sp |\\$1-\\n[.v]u + .. + . + .de y-from-bot-up + . sp |\\n[.p]u-\\$1-\\n[.v]u + .. + + A call to '.y-from-bot-up 10c' means that the next text baseline + will be 10 cm from the bottom edge of the paper. + + -- Request: .ls [count] + -- Register: \n[.L] + Set the line spacing; add COUNT-1 blank lines after each line of + text. With no argument, GNU 'troff' uses the previous value before + the last 'ls' call. The default is '1'. + + The read-only register '.L' contains the current line spacing; it + is associated with the environment (*note Environments::). + + The 'ls' request is a coarse mechanism. *Note Changing the Type +Size::, for the requests 'vs' and 'pvs' as alternatives to 'ls'. + + -- Escape sequence: \x'spacing' + -- Register: \n[.a] + Sometimes, an output line requires additional vertical spacing, for + instance to allow room for a tall construct like an inline equation + with exponents or subscripts (particularly if they are iterated). + The '\x' escape sequence takes a delimited measurement (like + '\x'3p'') to increase the vertical spacing of the pending output + line. The default scaling unit is 'v'. If the measurement is + positive, extra vertical space is inserted below the current line; + a negative measurement adds space above. If '\x' is applied to the + pending output line multiple times, the maxima of the positive and + negative adjustments are separately applied. The delimiter need + not be a neutral apostrophe; see *note Delimiters::. + + The '.a' read-only register contains the extra vertical spacing + _after_ the text baseline of the most recently emitted output line. + (In other words, it is the largest positive argument to '\x' + encountered on that line.) This quantity is exposed via a register + because if an output line requires this "extra post-vertical line + spacing", and the subsequent output line requires "extra + pre-vertical line spacing" (a negative argument to '\x'), then + applying both can lead to excessive spacing between the output + lines. Text that is piling high on line N might not require (as + much) extra pre-vertical line spacing if line N-1 carries extra + post-vertical line spacing. + + Use of '\x' can be necessary in combination with the + bracket-building escape sequence '\b',(2) (*note Manipulating + Spacing-Footnote-2::) as the following example shows. + + .nf + This is a test of \[rs]b (1). + This is a test of \[rs]b (2). + This is a test of \b'xyz'\x'-1m'\x'1m' (3). + This is a test of \[rs]b (4). + This is a test of \[rs]b (5). + => This is a test of \b (1). + => This is a test of \b (2). + => x + => This is a test of y (3). + => z + => This is a test of \b (4). + => This is a test of \b (5). + +Without '\x', the backslashes on the lines marked '(2)' and '(4)' would +be overprinted. + + -- Request: .ns + -- Request: .rs + -- Register: \n[.ns] + Enable "no-space mode". Vertical spacing, whether by 'sp' requests + or blank input lines, is disabled. The 'bp' request to advance to + the next page is also disabled, unless it is accompanied by a page + number (*note Page Control::). No-space mode ends automatically + when text(3) (*note Manipulating Spacing-Footnote-3::) is formatted + for output (4) (*note Manipulating Spacing-Footnote-4::) or the + 'rs' request is invoked, which ends no-space mode. The read-only + register '.ns' interpolates a Boolean value indicating the + enablement of no-space mode. + + A paragraphing macro might ordinarily insert vertical space to + separate paragraphs. A section heading macro could invoke 'ns' to + suppress this spacing for the first paragraph in a section. + + +File: groff.info, Node: Manipulating Spacing-Footnotes, Up: Manipulating Spacing + + (1) *Note Page Location Traps::. + + (2) *Note Drawing Geometric Objects::. + + (3) or geometric objects; see *note Drawing Geometric Objects:: + + (4) to the top-level diversion; see *note Diversions:: + + +File: groff.info, Node: Tabs and Fields, Next: Character Translations, Prev: Manipulating Spacing, Up: GNU troff Reference + +5.12 Tabs and Fields +==================== + +A tab character (ISO code point 9, EBCDIC code point 5) causes a +horizontal movement to the next tab stop, if any. + + -- Escape sequence: \t + Interpolate a tab in copy mode; see *note Copy Mode::. + + -- Request: .ta [[n1 n2 ... nn ]T r1 r2 ... rn] + -- Register: \n[.tabs] + Change tab stop positions. This request takes a series of tab + specifiers as arguments (optionally divided into two groups with + the letter 'T') that indicate where each tab stop is to be, + overriding any previous settings. The default scaling unit is 'm'. + Invoking 'ta' without an argument removes all tab stops. GNU + 'troff''s startup value is 'T 0.5i'. + + Tab stops can be specified absolutely--as distances from the left + margin. The following example sets six tab stops, one every inch. + + .ta 1i 2i 3i 4i 5i 6i + + Tab stops can also be specified using a leading '+', which means + that the specified tab stop is set relative to the previous tab + stop. For example, the following is equivalent to the previous + example. + + .ta 1i +1i +1i +1i +1i +1i + + GNU 'troff' supports an extended syntax to specify repeating tab + stops. These stops appear after a 'T' argument. Their values are + always taken as distances relative to the previous tab stop. This + is the idiomatic way to specify tab stops at equal intervals in + 'groff'. The following is, yet again, the same as the previous + examples. It does more, in fact, since it defines an infinite + number of tab stops at one-inch intervals. + + .ta T 1i + + Now we are ready to interpret the full syntax given above. The + 'ta' request sets tabs at positions N1, N2, ..., NN, then at NN+R1, + NN+R2, ..., NN+RN, then at NN+RN+R1, NN+RN+R2, ..., NN+RN+RN, and + so on. + + For example, '4c +6c T 3c 5c 2c' is equivalent to '4c 10c 13c 18c + 20c 23c 28c 30c ...'. + + Text written to a tab column (i.e., between two tab stops, or + between a tab stop and an output line boundary) may be aligned to + the right or left, or centered in the column. This alignment is + determined by appending 'R', 'L', or 'C' to the tab specifier. The + default is 'L'. + + .ta 1i 2iC 3iR + + The beginning of an output line is not a tab stop; the text that + begins an output line is placed according to the configured + alignment and indentation; see *note Manipulating Filling and + Adjustment:: and *note Line Layout::. + + A tab stop is converted into a non-breakable horizontal movement + that cannot be adjusted. + + .ll 2i + .ds foo a\tb\tc + .ta T 1i + \*[foo] + error-> warning: cannot break line + => a b c + + The above creates a single output line that is a bit longer than + two inches (we use a string to show exactly where the tab stops + are). Now consider the following. + + .ll 2i + .ds bar a\tb c\td + .ta T 1i + \*[bar] + error-> warning: cannot adjust line + => a b + => c d + + GNU 'troff' first converts the line's tab stops into unbreakable + horizontal movements, then breaks after 'b'. This usually isn't + what you want. + + Superfluous tab characters--those that do not correspond to a tab + stop--are ignored except for the first, which delimits the + characters belonging to the last tab stop for right-alignment or + centering. + + .ds Z foo\tbar\tbaz + .ds ZZ foo\tbar\tbazqux + .ds ZZZ foo\tbar\tbaz\tqux + .ta 2i 4iR + \*[Z] + .br + \*[ZZ] + .br + \*[ZZZ] + .br + => foo bar baz + => foo bar bazqux + => foo bar bazqux + + The first line right-aligns "baz" within the second tab stop. The + second line right-aligns "bazqux" within it. The third line + right-aligns only "baz" because of the additional tab character, + which marks the end of the text occupying the last tab stop + defined. + + Tab stops are associated with the environment (*note + Environments::). + + The read-only register '.tabs' contains a string representation of + the current tab settings suitable for use as an argument to the + 'ta' request.(1) (*note Tabs and Fields-Footnote-1::) + + .ds tab-string \n[.tabs] + \*[tab-string] + => T120u + + -- Request: .tc [c] + Set the tab repetition character to the ordinary or special + character C; normally, no glyph is written when moving to a tab + stop (and some output devices may output space characters to + achieve this motion). A "tab repetition character" causes the + formatter to write as many instances of C as are necessary to + occupy the interval from the horizontal drawing position to the + next tab stop. With no argument, GNU 'troff' reverts to the + default behavior. The tab repetition character is associated with + the environment (*note Environments::). Only a single character of + C is recognized; any excess is ignored. + + -- Request: .linetabs n + -- Register: \n[.linetabs] + If N is missing or non-zero, activate "line-tabs"; deactivate it + otherwise (the default). Active line-tabs cause GNU 'troff' to + compute tab distances relative to the start of the output line + instead of the input line. + + .de Tabs + . ds x a\t\c + . ds y b\t\c + . ds z c + . ta 1i 3i + \\*x + \\*y + \\*z + .. + .Tabs + .br + .linetabs + .Tabs + => a b c + => a b c + + Line-tabs activation is associated with the environment (*note + Environments::). The read-only register '.linetabs' interpolates 1 + if line-tabs are active, and 0 otherwise. + +* Menu: + +* Leaders:: +* Fields:: + + +File: groff.info, Node: Tabs and Fields-Footnotes, Up: Tabs and Fields + + (1) Plan 9 'troff' uses the register '.S' for this purpose. + + +File: groff.info, Node: Leaders, Next: Fields, Prev: Tabs and Fields, Up: Tabs and Fields + +5.12.1 Leaders +-------------- + +Sometimes it is desirable to fill a tab stop with a given glyph, but +also use tab stops normally on the same output line. An example is a +table of contents entry that uses dots to bridge the entry name with its +page number, which is itself aligned between tab stops. The 'roff' +language provides "leaders" for this purpose.(1) (*note +Leaders-Footnote-1::) + + A leader character (ISO and EBCDIC code point 1, also known as SOH or +"start of heading"), behaves similarly to a tab character: it moves to +the next tab stop. The difference is that for this movement, the +default fill character is a period '.'. + + -- Escape sequence: \a + Interpolate a leader in copy mode; see *note Copy Mode::. + + -- Request: .lc [c] + Set the leader repetition character to the ordinary or special + character C. Recall *note Tabs and Leaders::: when encountering a + leader character in the input, the formatter writes as many dots + '.' as are necessary until reaching the next tab stop; this is the + "leader definition character". Omitting C unsets the leader + character. With no argument, GNU 'troff' treats leaders the same + as tabs. The leader repetition character is associated with the + environment (*note Environments::). Only a single C is recognized; + any excess is ignored. + + A table of contents, for example, may define tab stops after a +section number, a title, and a gap to be filled with leader dots. The +page number follows the leader, after a right-aligned final tab stop +wide enough to house the largest page number occurring in the document. + + .ds entry1 19.\tThe Prophet\a\t98 + .ds entry2 20.\tAll Astir\a\t101 + .ta .5i 4.5i +.5iR + .nf + \*[entry1] + \*[entry2] + => 19. The Prophet............................. 98 + => 20. All Astir............................... 101 + + +File: groff.info, Node: Leaders-Footnotes, Up: Leaders + + (1) This is pronounced to rhyme with "feeder", and refers to how the +glyphs "lead" the eye across the page to the corresponding page number +or other datum. + + +File: groff.info, Node: Fields, Prev: Leaders, Up: Tabs and Fields + +5.12.2 Fields +------------- + +"Fields" are a more general way of laying out tabular data. A field is +defined as the data between a pair of "delimiting characters". It +contains substrings that are separated by "padding characters". The +width of a field is the distance on the _input_ line from the position +where the field starts to the next tab stop. A padding character +inserts an adjustable space similar to TeX's '\hss' command (thus it can +even be negative) to make the sum of all substring lengths plus the +adjustable space equal to the field width. If more than one padding +character is inserted, the available space is evenly distributed among +them. + + -- Request: .fc [delim-char [padding-char]] + Define a delimiting and a padding character for fields. If the + latter is missing, the padding character defaults to a space + character. If there is no argument at all, the field mechanism is + disabled (which is the default). In contrast to, e.g., the tab + repetition character, delimiting and padding characters are _not_ + associated with the environment (*note Environments::). + + .fc # ^ + .ta T 3i + #foo^bar^smurf# + .br + #foo^^bar^smurf# + => foo bar smurf + => foo bar smurf + + +File: groff.info, Node: Character Translations, Next: troff and nroff Modes, Prev: Tabs and Fields, Up: GNU troff Reference + +5.13 Character Translations +=========================== + +A "translation" is a mapping of an input character to an output glyph. +The mapping occurs at output time, i.e., the input character gets +assigned the metric information of the mapped output character right +before input tokens are converted to nodes (*note Gtroff Internals::, +for more on this process). + + -- Request: .tr abcd... + -- Request: .trin abcd... + Translate character A to glyph B, character C to glyph D, and so + on. If there is an odd number of characters in the argument, the + last one is translated to a fixed-width space (the same one + obtained by the '\<SP>' escape sequence). + + The 'trin' request is identical to 'tr', but when you unformat a + diversion with 'asciify' it ignores the translation. *Note + Diversions::, for details about the 'asciify' request. + + Some notes: + + * Special characters ('\(XX', '\[XXX]', '\C'XXX'', '\'', '\`', + '\-', '\_'), glyphs defined with the 'char' request, and + numbered glyphs ('\N'XXX'') can be translated also. + + * The '\e' escape can be translated also. + + * Characters can be mapped onto the '\%' and '\~' escape + sequences (but '\%' and '\~' can't be mapped onto another + glyph). + + * The following characters can't be translated: space (with one + exception, see below), backspace, newline, leader (and '\a'), + tab (and '\t'). + + * Translations are not considered for finding the soft hyphen + character set with the 'shc' request. + + * The pair 'C\&' (an arbitrary character C followed by the dummy + character) maps this character to "nothing". + + .tr a\& + foo bar + => foo br + + Even the space character can be mapped to the dummy character. + + .tr aa \& + foo bar + => foobar + + As shown in the example, the space character can't be the + first character/glyph pair as an argument of 'tr'. + Additionally, it is not possible to map the space character to + any other glyph; requests like '.tr aa x' undo '.tr aa \&' + instead. + + If justification is active, lines are justified in spite of + the 'empty' space character (but there is no minimal distance, + i.e., the space character, between words). + + * After an output glyph has been constructed (this happens at + the moment immediately before the glyph is appended to an + output glyph list, either by direct output, in a macro, + diversion, or string), it is no longer affected by 'tr'. + + * Translating character to glyphs where one of them or both are + undefined is possible also; 'tr' does not check whether the + elements of its argument exist. + + *Note Gtroff Internals::. + + * Without an argument, the 'tr' request is ignored. + + -- Request: .trnt abcd... + 'trnt' is the same as the 'tr' request except that the translations + do not apply to text that is transparently throughput into a + diversion with '\!'. *Note Diversions::. + + For example, + + .tr ab + .di x + \!.tm a + .di + .x + + prints 'b' to the standard error stream; if 'trnt' is used instead + of 'tr' it prints 'a'. + + +File: groff.info, Node: troff and nroff Modes, Next: Line Layout, Prev: Character Translations, Up: GNU troff Reference + +5.14 'troff' and 'nroff' Modes +============================== + +Historically, 'nroff' and 'troff' were two separate programs; the former +for terminal output, the latter for typesetters. GNU 'troff' merges +both functions into one executable(1) (*note troff and nroff +Modes-Footnote-1::) that sends its output to a device driver ('grotty' +for terminal devices, 'grops' for PostScript, and so on) which +interprets this intermediate output format. When discussing AT&T +'troff', it makes sense to talk about "'nroff' mode" and "'troff' mode" +since the differences are hard-coded. GNU 'troff' takes information +from device and font description files without handling requests +specially if a terminal output device is used, so such a strong +distinction is unnecessary. + + Usually, a macro package can be used with all output devices. +Nevertheless, it is sometimes necessary to make a distinction between +terminal and non-terminal devices: GNU 'troff' provides two built-in +conditions 'n' and 't' for the 'if', 'ie', and 'while' requests to +decide whether GNU 'troff' shall behave like 'nroff' or like 'troff'. + + -- Request: .troff + Make the 't' built-in condition true (and the 'n' built-in + condition false) for 'if', 'ie', and 'while' conditional requests. + This is the default if GNU 'troff' (_not_ 'groff') is started with + the '-R' switch to avoid loading of the startup files 'troffrc' and + 'troffrc-end'. Without '-R', GNU 'troff' stays in 'troff' mode if + the output device is not a terminal (e.g., 'ps'). + + -- Request: .nroff + Make the 'n' built-in condition true (and the 't' built-in + condition false) for 'if', 'ie', and 'while' conditional requests. + This is the default if GNU 'troff' uses a terminal output device; + the code for switching to 'nroff' mode is in the file 'tty.tmac', + which is loaded by the startup file 'troffrc'. + + *Note Conditionals and Loops::, for more details on built-in +conditions. + + +File: groff.info, Node: troff and nroff Modes-Footnotes, Up: troff and nroff Modes + + (1) A GNU 'nroff' program is available for convenience; it calls GNU +'troff' to perform the formatting. + + +File: groff.info, Node: Line Layout, Next: Line Continuation, Prev: troff and nroff Modes, Up: GNU troff Reference + +5.15 Line Layout +================ + +The following drawing shows the dimensions that 'gtroff' uses for +placing a line of output onto the page. They are labeled with the +request that manipulates each dimension. + + -->| in |<-- + |<-----------ll------------>| + +----+----+----------------------+----+ + | : : : | + +----+----+----------------------+----+ + -->| po |<-- + |<--------paper width---------------->| + +These dimensions are: + +'po' + "Page offset"--this is the leftmost position of text on the final + output, defining the "left margin". + +'in' + "Indentation"--this is the distance from the left margin where text + is printed. + +'ll' + "Line length"--this is the distance from the left margin to right + margin. + + The right margin is not explicitly configured; the combination of +page offset and line length provides the information necessary to derive +it. + + A simple demonstration: + + .ll 3i + This is text without indentation. + The line length has been set to 3\~inches. + .in +.5i + .ll -.5i + Now the left and right margins are both increased. + .in + .ll + Calling .in and .ll without parameters restores + the previous values. + + => This is text without indenta- + => tion. The line length has + => been set to 3 inches. + => Now the left and + => right margins are + => both increased. + => Calling .in and .ll without + => parameters restores the previ- + => ous values. + + -- Request: .po [offset] + -- Request: .po +offset + -- Request: .po -offset + -- Register: \n[.o] + Set page offset to OFFSET (or increment or decrement its current + value by OFFSET). If invoked without an argument, the page offset + is restored to the value before the previous 'po' request. This + request does not cause a break; the page offset in effect when an + output line is broken prevails (*note Manipulating Filling and + Adjustment::). The initial value is 1i and the default scaling + unit is 'm'. On terminal devices, the page offset is set to zero + by a driver-specific macro file, 'tty.tmac'. The current page + offset can be found in the read-only register '.o'. This request + is incorrectly documented in the AT&T 'troff' manual as using a + default scaling unit of 'v'. + + .po 3i + \n[.o] + => 720 + .po -1i + \n[.o] + => 480 + .po + \n[.o] + => 720 + + -- Request: .in [indent] + -- Request: .in +indent + -- Request: .in -indent + -- Register: \n[.i] + Set indentation to INDENT (or increment or decrement the current + value by INDENT). This request causes a break. Initially, there + is no indentation. + + If 'in' is called without an argument, the indentation is reset to + the previous value before the last call to 'in'. The default + scaling unit is 'm'. + + If a negative indentation value is specified (which is not + allowed), 'gtroff' emits a warning in category 'range' and sets the + indentation to zero. + + The effect of 'in' is delayed until a partially collected line (if + it exists) is output. A temporary indentation value is reset to + zero also. + + The current indentation (as set by 'in') can be found in the + read-only register '.i'. The indentation is associated with the + environment (*note Environments::). + + -- Request: .ti offset + -- Request: .ti +offset + -- Request: .ti -offset + -- Register: \n[.in] + Temporarily indent the next output line by OFFSET. If an increment + or decrement value is specified, adjust the temporary indentation + relative to the value set by the 'in' request. + + This request causes a break; its value is associated with the + environment (*note Environments::). The default scaling unit is + 'm'. A call of 'ti' without an argument is ignored. + + If the total indentation value is negative (which is not allowed), + 'gtroff' emits a warning in category 'range' and sets the temporary + indentation to zero. 'Total indentation' is either OFFSET if + specified as an absolute value, or the temporary plus normal + indentation, if OFFSET is given as a relative value. + + The effect of 'ti' is delayed until a partially collected line (if + it exists) is output. + + The read-only register '.in' is the indentation that applies to the + current output line. + + The difference between '.i' and '.in' is that the latter takes into + account whether a partially collected line still uses the old + indentation value or a temporary indentation value is active. + + -- Request: .ll [length] + -- Request: .ll +length + -- Request: .ll -length + -- Register: \n[.l] + -- Register: \n[.ll] + Set the line length to LENGTH (or increment or decrement the + current value by LENGTH). Initially, the line length is set to + 6.5i. The effect of 'll' is delayed until a partially collected + line (if it exists) is output. The default scaling unit is 'm'. + + If 'll' is called without an argument, the line length is reset to + the previous value before the last call to 'll'. If a negative + line length is specified (which is not allowed), 'gtroff' emits a + warning in category 'range' and sets the line length to zero. The + line length is associated with the environment (*note + Environments::). + + The current line length (as set by 'll') can be found in the + read-only register '.l'. The read-only register '.ll' is the line + length that applies to the current output line. + + Similar to '.i' and '.in', the difference between '.l' and '.ll' is + that the latter takes into account whether a partially collected + line still uses the old line length value. + + +File: groff.info, Node: Line Continuation, Next: Page Layout, Prev: Line Layout, Up: GNU troff Reference + +5.16 Line Continuation +====================== + +When filling is enabled, input and output line breaks generally do not +correspond. The 'roff' language therefore distinguishes input and +output line continuation. + + -- Escape sequence: \<RET> + '\<RET>' (a backslash immediately followed by a newline) suppresses + the effects of that newline in the input. The next input line thus + retains the classification of its predecessor as a control or text + line. '\<RET>' is useful for managing line lengths in the input + during document maintenance; you can break an input line in the + middle of a request invocation, macro call, or escape sequence. + Input line continuation is invisible to the formatter, with two + exceptions: the '|' operator recognizes the new input line (*note + Numeric Expressions::), and the input line counter register '.c' is + incremented. + + .ll 50n + .de I + . ft I + . nop \\$* + . ft + .. + Our film class watched + .I The Effect of Gamma Rays on Man-in-the-Moon + Marigolds. \" whoops, the input line wrapped + .br + .I My own opus begins on line \n[.c] \ + and ends on line \n[.c]. + => Our film class watched The Effect of Gamma Rays on + => Man-in-the-Moon Marigolds. + => My own opus begins on line 11 and ends on line 12. + + -- Escape sequence: \c + -- Register: \n[.int] + '\c' continues an output line. Nothing after it on the input line + is formatted. In contrast to '\<RET>', a line after '\c' remains a + new input line, so a control character is recognized at its + beginning. The visual results depend on whether filling is + enabled; see *note Manipulating Filling and Adjustment::. + + * If filling is enabled, a word interrupted with '\c' is + continued with the text on the next input text line, without + an intervening space. + + This is a te\c + st. + => This is a test. + + * If filling is disabled, the next input text line after '\c' is + handled as a continuation of the same input text line. + + .nf + This is a \c + test. + => This is a test. + + An intervening control line that causes a break overrides '\c', + flushing out the pending output line in the usual way. + + The '.int' register contains a positive value if the last output + line was continued with '\c'; this datum is associated with the + environment (*note Environments::).(1) (*note Line + Continuation-Footnote-1::) + + +File: groff.info, Node: Line Continuation-Footnotes, Up: Line Continuation + + (1) Historically, the '\c' escape sequence has proven challenging to +characterize. Some sources say it "connects the next input text" (to +the input line on which it appears); others describe it as +"interrupting" text, on the grounds that a text line is interrupted +without breaking, perhaps to inject a request invocation or macro call. + + +File: groff.info, Node: Page Layout, Next: Page Control, Prev: Line Continuation, Up: GNU troff Reference + +5.17 Page Layout +================ + +The formatter permits configuration of the page length and page number. + + -- Request: .pl [length] + -- Request: .pl +length + -- Request: .pl -length + -- Register: \n[.p] + Change (increase or decrease) the page length per the numeric + expression LENGTH. The default scaling unit is 'v'. A negative + LENGTH is valid, but an uncommon application: it prevents page + location traps from being sprung,(1) (*note Page + Layout-Footnote-1::) and each output line is placed on a new page. + If LENGTH is invalid, GNU 'troff' emits a warning in category + 'number'. If LENGTH is absent or invalid, '11i' is assumed. + + The read-only register '.p' interpolates the current page length. + + -- Request: .pn num + -- Request: .pn +num + -- Request: .pn -num + -- Register: \n[.pn] + Change (increase or decrease) the page number of the _next_ page + per the numeric expression NUM. If NUM is invalid, GNU 'troff' + emits a warning in category 'number' and ignores the request. + Without an argument, 'pn' is ignored. + + The read-only register '.pn' interpolates NUM if set by 'pn' on the + current page, or the current page number plus 1. + + The formatter offers special support for typesetting headers and +footers, collectively termed "titles". Titles have an independent line +length, and their placement on the page is not restricted. + + -- Request: .tl 'left'center'right' + Format an output line as a title consisting of LEFT, CENTER, and + RIGHT, each aligned accordingly. The delimiter need not be a + neutral apostrophe: 'tl' accepts the same delimiters as most escape + sequences; see *note Delimiters::. If not used as the delimiter, + any "page number character" character is replaced with the current + page number; the default is '%'; see the the 'pc' request below. + Without an argument, 'tl' is ignored. 'tl' writes the title line + immediately, ignoring any partially collected line. + + It is not an error to omit delimiters after the first. For + example, '.tl /Thesis' is interpreted as '.tl /Thesis///': it sets + a title line comprising only the left-aligned word 'Thesis'. + + -- Request: .lt [length] + -- Request: .lt +length + -- Request: .lt -length + -- Register: \n[.lt] + Change (increase or decrease) the line length used by titles per + the numeric expression LENGTH. The default scaling unit is 'm'. + If LENGTH is negative, GNU emits a warning in category 'range' and + treats LENGTH as '0'. If LENGTH is invalid, GNU 'troff' emits a + warning in category 'number' and ignores the request. The + formatter's default title length is '6.5i'. With no argument, the + title length is restored to the previous value. The title length + is is associated with the environment (*note Environments::). + + The read-only register '.lt' interpolates the title line length. + + -- Request: .pc [char] + Set the page number character to CHAR. With no argument, the page + number character is disabled. 'pc' does not affect the + register '%'. + + The following example exercises title features. + + .lt 50n + This is my partially collected + .tl 'Isomers 2023'%'Dextrose Edition' + line. + => Isomers 2023 1 Dextrose Edition + => This is my partially collected line. + + We most often see titles used in page header and footer traps. *Note +Traps::. + + +File: groff.info, Node: Page Layout-Footnotes, Up: Page Layout + + (1) *Note Traps::. + + +File: groff.info, Node: Page Control, Next: Using Fonts, Prev: Page Layout, Up: GNU troff Reference + +5.18 Page Control +================= + +Discretionary page breaks can prevent the unwanted separation of +content. A new page number takes effect during page ejection; see *note +The Implicit Page Trap::. + + -- Request: .bp [page-number] + -- Request: .bp +page-number + -- Request: .bp -page-number + -- Register: \n[%] + Break the page and change (increase or decrease) the next page + number per the numeric expression PAGE-NUMBER. If PAGE-NUMBER is + invalid, GNU 'troff' emits a warning in category 'number' and + ignores the argument. This request causes a break. A page break + advances the vertical drawing position to the bottom of the page, + springing traps. *Note Page Location Traps::. 'bp' has effect + only if invoked within the top-level diversion.(1) (*note Page + Control-Footnote-1::) This request is incorrectly documented in the + AT&T 'troff' manual as having a default scaling unit of 'v'. + + The register '%' interpolates the current page number. + + .de BP + ' bp \" schedule page break once current line is output + .. + + -- Request: .ne [space] + Force a page break if insufficient vertical space is available + (assert "needed" space). 'ne' tests the distance to the next page + location trap; see *note Page Location Traps::, and breaks the page + if that amount is less than SPACE. The default scaling unit is + 'v'. If SPACE is invalid, GNU 'troff' emits a warning in category + 'number' and ignores the argument. If SPACE is not specified, '1v' + is assumed. + + We can require space for at least the first two output lines of a + paragraph, preventing its first line from being widowed at the page + bottom. + + .ne 2v + Considering how common illness is, + how tremendous the spiritual change that it brings, + how astonishing, + when the lights of health go down, + the undiscovered countries that are then disclosed, + what wastes and deserts of the soul a slight attack + of influenza brings to view, + + This method is reliable only if no output line is pending when 'ne' + is invoked. When macro packages are used, this is often not the + case: their paragraphing macros perform the break. You may need to + experiment with placing the 'ne' after the paragraphing macro, or + 'br' and 'ne' before it. + + 'ne' is also useful to force grouping of section headings with + their subsequent paragraphs, or tables with their captions and/or + explanations. Macro packages often use 'ne' with diversions to + implement keeps and displays; see *note Diversions::. They may + also offer parameters for widow and orphan management. + + -- Request: .sv [space] + -- Request: .os + Require vertical space as 'ne' does, but also save it for later + output by the 'os' request. If SPACE is available before the next + page location trap, it is output immediately. Both requests ignore + a partially collected line, taking effect at the next break. 'sv' + and 'os' ignore no-space mode (recall *note Manipulating + Spacing::). While the 'sv' request allows negative values for + SPACE, 'os' ignores them. The default scaling unit is 'v'. If + SPACE is not specified, '1v' is assumed. + + -- Register: \n[nl] + 'nl' interpolates or sets the vertical drawing position. When the + formatter starts, the first page transition hasn't happened yet, + and 'nl' is negative. If a header trap has been planted on the + page (typically at vertical position '0'), you can assign a + negative value to 'nl' to spring it if that page has already + started (*note Page Location Traps::). + + .de HD + . sp + . tl ''Goldbach Solution'' + . sp + .. + . + First page. + .bp + .wh 0 HD \" plant header trap at top of page + .nr nl (-1) + Second page. + => First page. + => + => (blank lines elided) + => + => Goldbach Solution + => + => (blank lines elided) + => + => Second page. + + Without resetting 'nl' to a negative value, the trap just planted + would be active beginning with the _next_ page, not the current + one. + + *Note Diversions::, for a comparison of 'nl' with the '.h' and '.d' + registers. + + +File: groff.info, Node: Page Control-Footnotes, Up: Page Control + + (1) *Note Diversions::. + + +File: groff.info, Node: Using Fonts, Next: Manipulating Type Size and Vertical Spacing, Prev: Page Control, Up: GNU troff Reference + +5.19 Using Fonts +================ + +In digital typography, a "font" is a collection of characters in a +specific typeface that a device can render as glyphs at a desired +size.(1) (*note Using Fonts-Footnote-1::) A 'roff' formatter can change +typefaces at any point in the text. The basic faces are a set of +"styles" combining upright and slanted shapes with normal and heavy +stroke weights: 'R', 'I', 'B', and 'BI'--these stand for roman, italic, +bold, and bold-italic. For linguistic text, GNU 'troff' groups +typefaces into "families" containing each of these styles.(2) (*note +Using Fonts-Footnote-2::) A "text font" is thus often a family combined +with a style, but it need not be: consider the 'ps' and 'pdf' devices' +'ZCMI' (Zapf Chancery Medium italic)--often, no other style of Zapf +Chancery Medium is provided. On typesetting devices, at least one +"special font" is available, comprising "unstyled" glyphs for +mathematical operators and other purposes. + + Like AT&T 'troff', GNU 'troff' does not itself load or manipulate a +digital font file;(3) (*note Using Fonts-Footnote-3::) instead it works +with a "font description file" that characterizes it, including its +glyph repertoire and the "metrics" (dimensions) of each glyph.(4) +(*note Using Fonts-Footnote-4::) This information permits the formatter +to accurately place glyphs with respect to each other. Before using a +font description, the formatter associates it with a "mounting +position", a place in an ordered list of available typefaces. So that a +document need not be strongly coupled to a specific font family, in GNU +'troff' an output device can associate a style in the abstract sense +with a mounting position. Thus the default family can be combined with +a style dynamically, producing a "resolved font name". + + Fonts often have trademarked names, and even Free Software fonts can +require renaming upon modification. 'groff' maintains a convention that +a device's serif font family is given the name 'T' ("Times"), its +sans-serif family 'H' ("Helvetica"), and its monospaced family 'C' +("Courier"). Historical inertia has driven 'groff''s font identifiers +to short uppercase abbreviations of font names, as with 'TR', 'TI', +'TB', 'TBI', and a special font 'S'. + + The default family used with abstract styles can be changed at any +time; initially, it is 'T'. Typically, abstract styles are arranged in +the first four mounting positions in the order shown above. The default +mounting position, and therefore style, is always '1' ('R'). By issuing +appropriate formatter instructions, you can override these defaults +before your document writes its first glyph. + + Terminal output devices cannot change font families and lack special +fonts. They support style changes by overstriking, or by altering +ISO 6429/ECMA-48 "graphic renditions" (character cell attributes). + +* Menu: + +* Selecting Fonts:: +* Font Families:: +* Font Positions:: +* Using Symbols:: +* Character Classes:: +* Special Fonts:: +* Artificial Fonts:: +* Ligatures and Kerning:: +* Italic Corrections:: +* Dummy Characters:: + + +File: groff.info, Node: Using Fonts-Footnotes, Up: Using Fonts + + (1) Terminals and some output devices have fonts that render at only +one or two sizes. As examples of the latter, take the 'groff' 'lj4' +device's Lineprinter, and 'lbp''s Courier and Elite faces. + + (2) Font designers prepare families such that the styles share +esthetic properties. + + (3) Historically, the fonts 'troff's dealt with were not Free +Software or, as with the Graphic Systems C/A/T, did not even exist in +the digital domain. + + (4) *Note Font Description File Format::. + |