diff options
Diffstat (limited to 'man/groff.7.man')
| -rw-r--r-- | man/groff.7.man | 8055 |
1 files changed, 8055 insertions, 0 deletions
diff --git a/man/groff.7.man b/man/groff.7.man new file mode 100644 index 0000000..3d4cad1 --- /dev/null +++ b/man/groff.7.man @@ -0,0 +1,8055 @@ +'\" t +.TH groff @MAN7EXT@ "@MDATE@" "groff @VERSION@" +.SH Name +groff \- GNU +.I roff +language reference +. +. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 2000-2023 Free Software Foundation, Inc. +.\" +.\" This file is part of groff, the GNU roff type-setting system. +.\" +.\" 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, with no Front-Cover Texts, +.\" and with no Back-Cover Texts. +.\" +.\" A copy of the Free Documentation License is included as a file +.\" called FDL in the main directory of the groff source package. +. +. +.\" Save and disable compatibility mode (for, e.g., Solaris 10/11). +.do nr *groff_groff_7_man_C \n[.cp] +.cp 0 +. +.\" Define fallback for groff 1.23's MR macro if the system lacks it. +.nr do-fallback 0 +.if !\n(.f .nr do-fallback 1 \" mandoc +.if \n(.g .if !d MR .nr do-fallback 1 \" older groff +.if !\n(.g .nr do-fallback 1 \" non-groff *roff +.if \n[do-fallback] \{\ +. de MR +. ie \\n(.$=1 \ +. I \%\\$1 +. el \ +. IR \%\\$1 (\\$2)\\$3 +. . +.\} +.rr do-fallback +. +. +.\" ==================================================================== +.\" Setup +.\" ==================================================================== +. +.\" Man pages should not define page-local macros. Most of these were +.\" written long ago; someday we'll revise the page without them. +. +.\" ==================================================================== +.\" start a macro, escape sequence, or register definition +. +.de TPx +. TP 10n +.. +.\" ==================================================================== +.\" .Text anything ... +.\" +.\" All arguments are printed as text. +.\" +.de Text +. nop \)\\$* +.. +. +.\" ========= characters ========= +. +.de squoted_char +. Text \[oq]\f[CB]\\$1\f[]\[cq]\\$2 +.. +.de dquoted_char +. Text \[lq]\f[CB]\\$1\f[]\[rq]\\$2 +.. +.\" ========= requests ========= +. +.\" synopsis of a request +.de REQ +. ie \\n[.$]=1 \{\ +. Text \f[CB]\\$1\f[] +. \} +. el \{\ +. Text \f[CB]\\$1\~\f[]\f[I]\\$2\f[] +. \} +.. +. +.\" reference of a request +.de request +. ie (\\n[.$] < 2) \ +. B \\$* +. el \ +. BR \\$* +.. +. +.\" ========= numeric elements ========= +. +.\" number with a trailing unit +.de scalednumber +. Text \\$1\^\f[CB]\\$2\f[]\\$3\f[R] +. ft P +.. +. +.\" representation of units within the text +.de scaleindicator +. Text \f[CB]\\$1\f[]\\$2\f[R] +. ft P +.. +. +.\" representation of mathematical operators within the text +.de operator +. squoted_char \\$@ +.. +. +. +.\" ========= escape sequences ========= +. +.\" ==================================================================== +.\" .ESC name [arg] +.\" +.\" Synopsis of an escape sequence, optionally with argument +.\" Args : 1 or 2; 'name' obligatory, 'arg' optional +.\" name : suitable name for an escape sequence (c, (xy, [long]) +.\" arg : arbitrary word +.\" Result : prints \namearg, where 'name' is in CB, 'arg' in I +.\" +.de ESC +. Text "\f[CB]\e\\$1\,\f[I]\\$2\/\fR" +.. +.\" ==================================================================== +.\" .ESC[] name arg +.\" +.\" Synopsis for escape sequence with a bracketed long argument +.\" Args : 2 obligatory +.\" name : suitable name for an escape sequence (c, (xy, [long]) +.\" arg : arbitrary text +.\" Result : prints \name[arg], where 'name' is in CB, 'arg' in I +.\" +.de ESC[] +. Text "\f[CB]\e\\$1\[lB]\f[]\,\f[I]\\$2\/\f[]\f[CB]\[rB]\f[]" +.. +.\" ==================================================================== +.\" .ESCq name arg +.\" +.\" Synopsis for escape sequence with a bracketed long argument +.\" Args : 2 obligatory +.\" name : suitable name for an escape sequence (c, (xy, [long]) +.\" arg : arbitrary text +.\" Result : prints \name'arg', where 'name' is in CB, 'arg' in I +.\" +.de ESCq +. Text "\f[CB]\e\\$1\[aq]\f[]\,\f[I]\\$2\/\f[]\f[CB]\[aq]\f[]" +.. +.\" ==================================================================== +.\" .ESC? arg +.\" +.\" Synopsis for escape sequence with a bracketed long argument +.\" Args : 1 obligatory +.\" arg : arbitrary text +.\" Result : prints '\?arg\?', where the '\?' are in CB, 'arg' in I +.\" +.de ESC? +. Text "\f[CB]\e?\,\f[I]\\$1\/\f[CB]\[rs]?\f[R]" +.. +.\" ==================================================================== +.\" .esc name [punct] +.\" +.\" Reference of an escape sequence (no args), possibly punctuation +.\" Args : 1 obligatory +.\" name : suitable name for an escape sequence (c, (xy, [long]) +.\" punct : arbitrary +.\" Result : prints \name, where 'name' is in B, 'punct' in R +.\" +.de esc +. ie (\\n[.$] < 2) \ +. B "\e\\$1" +. el \ +. BR "\e\\$1" \\$2 +.. +.\" ==================================================================== +.\" .escarg name arg [punct] +.\" +.\" Reference of an escape sequence (no args) +.\" Args : 1 obligatory, 1 optional +.\" name : suitable name for an escape sequence (c, (xy, [long]) +.\" arg : arbitrary word +.\" Result : prints \namearg, where +.\" 'name' is in B, 'arg' in I +.\" +.de escarg +. Text \f[B]\e\\$1\f[]\,\f[I]\\$2\/\f[]\\$3 +.. +.\" ==================================================================== +.\" .esc[] name arg [punct] +.\" +.\" Reference for escape sequence with a bracketed long argument +.\" Args : 2 obligatory +.\" name : suitable name for an escape sequence (c, (xy, [long]) +.\" arg : arbitrary text +.\" Result : prints \name[arg], where 'name' is in CB, 'arg' in CI +.\" +.de esc[] +. Text \f[CB]\e\\$1\[lB]\f[]\,\f[CI]\\$2\/\f[]\f[CB]\[rB]\f[]\\$3 +.. +. +.\" ========= strings ========= +. +.\" synopsis for string, with \*[] +.de STRING +. Text \[rs]*[\f[CB]\\$1\f[]] \\$2 +.. +.\" synopsis for a long string +.de string +. if \n[.$]=0 \ +. return +. Text \f[CB]\[rs]*\[lB]\\$1\[rB]\f[]\\$2 +.. +. +.\" ========= registers ========= +. +.\" synopsis for registers, with \n[] +.de REG +. Text \[rs]n[\f[CB]\\$1\f[]] +.. +.\" reference of a register, without decoration +.de register +. Text register +. ie (\\n[.$] < 2) \ +. B \\$* +. el \ +. BR \\$* +.. +. +.\" begin list [piloting a possible extension to man(7)] +.de LS +. nr saved-PD \\n[PD] +. nr PD 0 +.. +. +.\" end list [piloting a possible extension to man(7)] +.de LE +. nr PD \\n[saved-PD] +.. +. +. +.\" end of macro definitions +. +. +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +.I groff +is short for GNU +.IR roff , +a free reimplementation of the AT&T device-independent +.I troff \" AT&T +typesetting system. +. +See +.MR roff @MAN7EXT@ +for a survey of and background on +.I roff +systems. +. +. +.P +This document is intended as a reference. +. +The primary +.I groff +manual, +.IR "Groff: The GNU Implementation of troff" , +by Trent A.\& Fisher and Werner Lemberg, +is a better resource for learners, +containing many examples and much discussion. +. +It is written in Texinfo; +you can browse it interactively with \[lq]info groff\[rq]. +. +Additional formats, +including plain text, +HTML, +DVI, +and PDF, +may be available in +.IR @DOCDIR@ . +. +. +.P +.I groff +is also a name for an extended dialect of the +.I roff +language. +. +We use \[lq]roff\[rq] to denote features that are universal, +or nearly so, +among implementations of this family. +. +We apply the term \[lq]groff\[rq] to the language documented here, +the GNU implementation of the overall system, +the project that develops that system, +and the command of that name. +. +. +.P +GNU +.IR troff , \" GNU +installed on this system as +.MR @g@troff @MAN1EXT@ , +is the +.I formatter: +a program that reads device and font descriptions +(\c +.MR groff_font @MAN5EXT@ ), +interprets the +.I groff +language expressed in text input files, +and translates that input into a device-independent output format +(\c +.MR groff_out @MAN5EXT@ ) +that is usually then post-processed by an output driver to produce +PostScript, +PDF, +HTML, +DVI, +or terminal output. +. +. +.\" ==================================================================== +.SH "Input format" +.\" ==================================================================== +. +Input to GNU +.I troff \" GNU +is organized into lines separated by the Unix newline character +(U+000A), +and must be in one of two character encodings it can recognize: +IBM code page 1047 on EBCDIC systems, +and ISO\~Latin-1 (8859-1) otherwise. +. +Use of ISO\~646-1991:IRV (\[lq]US-ASCII\[rq]) or (equivalently) the +\[lq]Basic Latin\[rq] +subset of ISO\~10646 (\[lq]Unicode\[rq]) is recommended; +see +.MR groff_char @MAN7EXT@ . +. +The +.MR preconv @MAN1EXT@ +preprocessor transforms other encodings, +including UTF-8, +to satisfy +.IR @g@troff 's +requirements. +. +. +.\" ==================================================================== +.SH "Syntax characters" +.\" ==================================================================== +. +Several input characters are syntactically significant to +.IR groff . +. +. +.IP . 4n +A dot at the beginning of an input line marks it as a +.I control line. +. +It can also follow the +.request .el +and +.request .nop +requests, +and the condition in +.request .if , +.request .ie , +and +.request .while +requests. +. +The control character invokes requests and calls macros by the name that +follows it. +. +The +.request .cc +request can change the control character. +. +. +.IP \[aq] +The neutral apostrophe is the +.I "no-break control character," +recognized where the control character is. +. +It suppresses the (first) break implied by the +.request .bp , +.request .cf , +.request .fi , +.request .fl , +.request .in , +.request .nf , +.request .rj , +.request .sp , +.request .ti , +and +.request .trf +requests. +. +The requested operation takes effect at the next break. +. +It makes +.request .br +nilpotent. +. +The no-break control character can be changed with the +.request .c2 +request. +. +When formatted, +.RB \[lq] \[aq] \[rq] +may be typeset as a typographical quotation mark; +use the +.esc [aq] +special character escape sequence to format a neutral apostrophe glyph. +. +. +.IP \[dq] +The neutral double quote can be used to enclose arguments to macros and +strings, +and is required if those arguments contain space or tab characters. +. +In the +.request .ds , +.request .ds1 , +.request .as , +and +.request .as1 +requests, +an initial neutral double quote in the second argument is stripped off +to allow embedding of leading spaces. +. +To include a double quote inside a quoted argument, +use the +.esc [dq] +special character escape sequence +(which also serves to typeset the glyph in text). +. +. +.IP \[rs] +A backslash introduces an escape sequence. +. +The escape character can be changed with the +.request .ec +request; +.request .eo +disables escape sequence recognition. +. +Use the +.esc [rs] +special character escape sequence to format a backslash glyph, +and +.esc e +to typeset the glyph of the current escape character. +. +. +.IP ( +An opening parenthesis is special only in certain escape sequences; +when recognized, +it introduces an argument of exactly two characters. +. +.I groff +offers the more flexible square bracket syntax. +. +. +.IP [ +An opening bracket is special only in certain escape sequences; +when recognized, +it introduces an argument (list) of any length, +not including a closing bracket. +. +. +.IP ] +A closing bracket is special only when an escape sequence using an +opening bracket as an argument delimiter is being interpreted. +. +It ends the argument (list). +. +. +.P +Additionally, +the Control+A character (U+0001) in text is interpreted as a +.I leader +(see below). +. +. +.P +Horizontal white space characters are significant to +.I groff, +but trailing spaces on text lines are ignored. +.\" slack text for widow/orphan control: trailing tabs are not +. +. +.TP 8n +.I space +Space characters separate arguments in request invocations, +macro calls, +and string interpolations. +. +In text, +they separate words. +. +Multiple adjacent space characters in text cause +.I groff +to attempt end-of-sentence detection on the preceding word +(and trailing punctuation). +. +The amount of space between words and sentences is controlled by the +.request .ss +request. +. +When filling is enabled +(the default), +a line may be broken at a space. +. +When adjustment is enabled +(the default), +inter-word spaces are expanded until the output line reaches the +configured length. +. +An adjustable but non-breaking space is available with +.esc \[ti] . +. +To get a space of fixed width, +use one of the escape sequences +.squoted_char "\[rs]\~" +(the escape character followed by a space), +.esc 0 , +.esc | , +.esc \[ha] , +or +.esc h ; +see section \[lq]Escape sequences\[rq] below. +. +. +.TP +.I newline +In text, +a newline puts an inter-word space onto the output and, +if filling is enabled, +triggers end-of-sentence recognition on the preceding text. +. +See section \[lq]Line continuation\[rq] below. +. +. +.TP +.I tab +A tab character in text causes the drawing position to advance to the +next defined tab stop. +. +. +.\" ==================================================================== +.SH "Tabs and leaders" +.\" ==================================================================== +. +.\" BEGIN Keep (roughly) parallel with groff.texi node "Tabs and +.\" Leaders". +The formatter interprets input horizontal tab characters +(\[lq]tabs\[rq]) and Control+A characters (\[lq]leaders\[rq]) 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 section \[lq]Page geometry\[rq] of +.MR roff 7 . +. +Tabs and leaders do not cause breaks and therefore do not interrupt +filling. +. +Tab stops can be configured with the +.B ta +request, +and tab and leader glyphs with the +.B tc +and +.B lc +requests, +respectively. +.\" END Keep (roughly) parallel with groff.texi node "Tabs and Leaders". +. +. +.\" ==================================================================== +.SH "Line continuation" +.\" ==================================================================== +. +When filling is enabled, +input and output line breaks generally do not correspond. +. +The +.I roff +language therefore distinguishes input and output line continuation. +. +. +.P +A backslash +.B \[rs] +immediately followed by a newline, +sometimes discussed as +.BI \[rs] newline\c +, +suppresses the effects of that newline +on the input. +. +The next input line thus retains the classification of its predecessor +as a control or text line. +. +.BI \[rs] newline +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 +.B \[or] +operator recognizes the new input line, +and the input line counter register +.B .c +is incremented. +. +. +.P +The +.esc c +escape sequence continues an +.I output +line. +. +Nothing on the input line after it is formatted. +. +In contrast to +.BI \[rs] newline\c +, +a line after +.esc c +is treated as a new input line, +so a control character is recognized at its beginning. +. +The visual results depend on whether filling is enabled. +. +An intervening control line that causes a break overrides +.esc c , +flushing out the pending output line in the usual way. +. +The +.register .int +contains a positive value if the last output line was continued with +.esc c ; +this datum is associated with the +environment. +. +. +.\" ==================================================================== +.SH Colors +.\" ==================================================================== +. +.\" BEGIN Keep (roughly) parallel with groff.texi node "Colors". +.I groff +supports color output with a variety of color spaces and up to 16 bits +per channel. +. +Some devices, +particularly terminals, +may be more limited. +. +When color support is enabled, +two colors are current at any given time: +the +.I stroke color, +with which glyphs, +rules (lines), +and geometric objects like circles and polygons are drawn, +and the +.I fill color, +which can be used to paint the interior of a closed geometric figure. +. +The +.BR color , +.BR defcolor , +.BR gcolor , +and +.B fcolor +requests; +.B \[rs]m +and +.B \[rs]M +escape sequences; +and +.BR .color , +.BR .m , +and +.B .M +registers exercise color support. +. +. +.P +Each output device has a color named +.RB \[lq] default \[rq], +which cannot be redefined. +. +A device's default stroke and fill colors are not necessarily the same. +. +For the +.BR dvi , +.BR html , +.BR pdf , +.BR ps , +and +.B xhtml +output devices, +.I @g@troff +automatically loads a macro file defining many color names at startup. +. +By the same mechanism, +the devices supported by +.MR grotty @MAN1EXT@ +recognize the eight standard ISO\~6429/ECMA-48 color names +(also known vulgarly as \[lq]ANSI colors\[rq]). +.\" END Keep (roughly) parallel with groff.texi node "Colors". +. +. +.br +.ne 3v +.\" ==================================================================== +.SH Measurements +.\" ==================================================================== +. +.\" BEGIN Keep (roughly) parallel with groff.texi node "Measurements". +Numeric parameters that specify measurements are expressed as +integers or decimal fractions with an optional +.I 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. +. +. +.P +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 +.RB \[lq] 1i \[rq] +to a register. +. +The only constraint on the basic unit is that it is at least as small as +any other unit. +.\" That's a fib. A device resolution of around 2^31 would surely also +.\" cause problems. But nobody does that. +. +. +.P +.LS +.TP +.B u +Basic unit. +. +.TP +.B i +Inch; +defined as 2.54\~centimeters. +. +.TP +.B c +Centimeter. +. +.TP +.B p +Point; +a typesetter's unit used for measuring type size. +. +There are 72\~points to an inch. +. +.TP +.B P +Pica; +another typesetter's unit. +. +There are 6\~picas to an inch and 12\~points to a pica. +. +.TP +.BR s ,\~ z +Scaled points and multiplication by the output device's +.I sizescale +parameter, +respectively. +. +.TP +.B f +Multiplication by 65,536; +. +scales decimal fractions in the interval [0, 1] to 16-bit unsigned +integers. +.LE +. +. +.P +The magnitudes of other scaling units depend on the text formatting +parameters in effect. +. +. +.P +.LS +.TP +.B m +Em; +an em is equal to the current type size in points. +. +.TP +.B n +En; +an en is one-half em. +. +.TP +.B v +Vee; +distance between text baselines. +. +.TP +.B M +Hundredth of an em. +.LE +.\" END Keep (roughly) parallel with groff.texi node "Measurements". +. +. +.\" ==================================================================== +.SS "Motion quanta" +.\" ==================================================================== +. +.\" BEGIN Keep (roughly) parallel with groff.texi node "Motion Quanta". +An output device's basic unit +.B u +is not necessarily its smallest addressable length; +.B 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 +.I "motion quanta," +stored in the +.B .H +and +.B .V +registers, +respectively. +. +Measurements are rounded to applicable motion quanta. +. +Half-quantum fractions round toward zero. +.\" END Keep (roughly) parallel with groff.texi node "Motion Quanta". +. +. +.\" ==================================================================== +.SS "Default units" +.\" ==================================================================== +. +.\" BEGIN Keep (roughly) parallel with groff.texi node "Default Units". +A general-purpose register +(one created or updated with the +.B nr +request; +see section \[lq]Registers\[rq] below) +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 +.IR troff 's \" GNU +use of integer arithmetic should also be kept in mind; +see below. +.\" END Keep (roughly) parallel with groff.texi node "Default Units". +. +. +.\" ==================================================================== +.SH "Numeric expressions" +.\" ==================================================================== +. +.\" BEGIN Keep (roughly) parallel with groff.texi node "Numeric +.\" expressions". +A +.I numeric expression +evaluates to an integer. +. +The following operators are recognized. +.\"evaluates to an integer: +.\"it can be as simple as a literal +.\".RB \[lq] 0 \[rq] +.\"or it can be a complex sequence of register and string interpolations +.\"interleaved with measurement operators. +. +. +.P +.TS +Rf(CR) L. ++ addition +\- subtraction +* multiplication +/ truncating division +% modulus +_ +\f[R]unary\f[] + assertion, motion, incrementation +\f[R]unary\f[] \- negation, motion, decrementation +_ +; scaling +>? maximum +<? minimum +_ +< less than +> greater than +<= less than or equal +>= greater than or equal +\&= equal +== equal +_ +& logical conjunction (\[lq]and\[rq]) +: logical disjunction (\[lq]or\[rq]) +! logical complementation (\[lq]not\[rq]) +_ +( ) precedence +_ +| boundary-relative motion +.TE +. +. +.P +.I @g@troff +provides a set of mathematical and logical operators familiar to +programmers\[em]as well as some unusual ones\[em]but supports only +integer arithmetic. +. +(Provision is made for interpreting and +reporting decimal fractions in certain cases.) +. +The internal data type used for computing results is usually a 32-bit +signed integer, +which suffices to represent magnitudes within a range of \[+-]2 +billion. +. +(If that's not enough, see +.MR groff_tmac @MAN5EXT@ +for the +.I 62bit.tmac +macro package.) +. +. +.P +Arithmetic infix operators perform a function on the numeric expressions +to their left and right; +they are +.B + +(addition), +.B \- +(subtraction), +.B * +(multiplication), +.B / +(truncating division), +and +.B % +(modulus). +. +.I 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. +. +. +.P +Arithmetic unary operators operate on the numeric expression to their +right; +they are +.B \- +(negation) +and +.B + +(assertion\[em]for completeness; +it does nothing). +. +The unary minus must often be used with parentheses to avoid confusion +with the decrementation operator, +discussed below. +. +. +.P +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 +.RI dividend\~ a +and a +.RI divisor\~ b , +a +.RI quotient\~ q +formed by +.RB \[lq] "(a / b)" \[rq] +and a +.RI remainder\~ r +by +.RB \[lq] "(a % b)" \[rq], +then +.IR qb \~+\~ r \~=\~ a . +. +. +.P +GNU +.IR troff 's \" GNU +scaling operator, +used with parentheses as +.BI ( c ; e )\c +, +evaluates a numeric +.RI expression\~ e +.RI using\~ c +as the default scaling unit. +. +If +.I c +is omitted, +scaling units are ignored in the evaluation +.RI of\~ e . +. +GNU +.I troff \" GNU +also provides a pair of operators to compute the extrema of two +operands: +.B >?\& +(maximum) +and +.B <?\& +(minimum). +. +. +.P +Comparison operators comprise +.B < +(less than), +.B > +(greater than), +.B <= +(less than or equal), +.B >= +(greater than or equal), +and +.B = +(equal). +. +.B == +is a synonym for +.BR = . +. +When evaluated, +a comparison is replaced with +.RB \[lq] 0 \[rq] +if it is false and +.RB \[lq] 1 \[rq] +if true. +. +In the +.I roff +language, +positive values are true, +others false. +. +. +.P +We can operate on truth values with the logical operators +.B & +(logical conjunction or \[lq]and\[rq]) +and +.B : +(logical disjunction or \[lq]or\[rq]). +. +They evaluate as comparison operators do. +. +A logical complementation (\[lq]not\[rq]) operator, +.B !\&, +works only within +.RB \[lq] if \[rq], +.RB \[lq] ie \[rq], +and +.RB \[lq] while \[rq] +requests. +. +.\" This is worded to avoid implying that the operator doesn't apply to +.\" conditional expressions in general, albeit without mentioning them +.\" because they're out of scope. +Furthermore, +.B !\& +is recognized only at the beginning of a numeric expression not +contained by another numeric expression. +. +In other words, +it must be the \[lq]outermost\[rq] operator. +. +Including it elsewhere in the expression produces a warning in the +.RB \%\[lq] number \[rq] +category +(see +.MR @g@troff @MAN1EXT@ ), +and its expression evaluates false. +. +This unfortunate limitation maintains compatibility with AT&T +.IR troff .\" AT&T +. +Test a numeric expression for falsity by comparing it to a false value. +. +. +.P +The +.I roff +language has no operator precedence: +expressions are evaluated strictly from left to right, +in contrast to schoolhouse arithmetic. +. +Use parentheses +.B ( ) +to impose a desired precedence upon subexpressions. +. +. +.P +For many requests and escape sequences that cause motion on the page, +the unary operators +.B + +and +.B \- +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. +. +. +.P +.B + +and +.B \- +are also treated differently by the following requests and escape +sequences: +.BR bp , +.BR in , +.BR ll , +.BR pl , +.BR pn , +.BR po , +.BR ps , +.BR pvs , +.BR rt , +.BR ti , +.BR \[rs]H , +.BR \[rs]R , +and +.BR \[rs]s . +. +Here, +leading plus and minus signs serve as incrementation and decrementation +operators, +respectively. +. +To negate an expression, +subtract it from zero +or include the unary minus in parentheses with its argument. +.\" @xref{Setting Registers}, for examples. +. +. +.P +A leading +.B \[or] +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 +.I input +line. +. +By default, +tab stops reckon movements in this way. +Most escape sequences do not; +.\" XXX: Which ones do? +.B \[or] +tells them to do so. +. +For vertical motions, +the +.B \[or] +operator specifies a distance from the first text baseline on the page +or in the current diversion, +using the current vertical spacing. +. +. +.P +The +.B \[rs]B +escape sequence tests its argument for validity as a numeric expression. +. +. +.br +.ne 2v +.P +A register interpolated as an operand in a numeric expression must have +an Arabic format; +luckily, +this is the default.\" @xref{Assigning Register Formats}. +. +. +.P +Due to the way arguments are parsed, +spaces are not allowed in numeric expressions unless the (sub)expression +containing them is surrounded by parentheses. +.\"@xref{Request and Macro Arguments}, and @ref{Conditionals and Loops}. +.\" END Keep (roughly) parallel with groff.texi node "Numeric +.\" expressions". +. +. +.\" ==================================================================== +.SH Identifiers +.\" ==================================================================== +. +.\" BEGIN Keep (roughly) parallel with groff.texi node "Identifiers". +An +.I identifier +labels a GNU +.I troff \" GNU +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 +.I ordinary character +is an input character that is not the escape character, +a leader, +tab, +newline, +or invalid as GNU +.I troff \" GNU +input. +. +. +.\" XXX: We might move this discussion earlier since it is applicable to +.\" troff input in general, and include a reference to the `trin` +.\" request. +.P +Invalid input characters are subset of control characters +(from the sets \[lq]C0 Controls\[rq] and \[lq]C1 Controls\[rq] as +Unicode describes them). +. +When +.I @g@troff +encounters one in an identifier, +it produces a warning in category +.RB \%\[lq] input \[rq] +(see section \[lq]Warnings\[rq] in +.MR @g@troff @MAN1EXT@ ). +. +They are removed during interpretation: +an identifier \[lq]foo\[rq], +followed by an invalid +character and then \[lq]bar\[rq], +is processed as \[lq]foobar\[rq]. +. +. +.P +On a machine using the ISO 646, +8859, +or 10646 character encodings, +invalid input characters are +.BR 0x00 , +.BR 0x08 , +.BR 0x0B , +.BR 0x0D \[en] 0x1F , +and +.BR 0x80 \[en] 0x9F . +. +On an EBCDIC host, +they are +.BR 0x00 \[en] 0x01 , +.BR 0x08 , +.BR 0x09 , +.BR 0x0B , +.BR 0x0D \[en] 0x14 , +.BR 0x17 \[en] 0x1F , +and +.BR 0x30 \[en] 0x3F . +. +Some of these code points are used by +.I @g@troff +internally, +making it non-trivial to extend the program to accept UTF-8 or other +encodings that use characters from these ranges. +. +. +.P +An identifier with a closing bracket (\[lq]]\[rq]) in its name can't be +accessed with bracket-form escape sequences that expect an identifier as +a parameter. +. +Similarly, +the +identifier \[lq](\[rq] can't be interpolated +.I except +with bracket forms. +. +. +.P +If you begin a macro, +string, +or diversion name with either of the characters \[lq][\[rq] or +\[lq]]\[rq], +you foreclose use of the +.MR @g@refer @MAN1EXT@ +preprocessor, +which recognizes \[lq].[\[rq] and \[lq].]\[rq] as bibliographic +reference delimiters. +. +. +.P +The escape sequence +.B \[rs]A +tests its argument for validity as an identifier. +. +. +.P +How GNU +.I troff \" GNU +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, +.I @g@troff +emits a warning in category +.RB \[lq] mac \[rq], +defines it as empty, +and interpolates nothing. +. +If the identifier is interpreted as a register, +.I @g@troff +emits a warning in category +.RB \[lq] reg \[rq], +initializes it to zero, +and interpolates that value. +. +See section \[lq]Warnings\[rq] in +.MR @g@troff @MAN1EXT@ , +and subsection \[lq]Interpolating registers\[rq] and section +\[lq]Strings\[rq] below. +. +Attempting to use an undefined +typeface, +style, +special character, +color, +character class, +environment, +or stream generally provokes an error diagnostic. +. +. +.P +Identifiers for requests, +macros, +strings, +and diversions share one name +space; +special characters and character classes another. +. +No other object types do. +.\" END Keep (roughly) parallel with groff.texi node "Identifiers". +. +. +.\" ==================================================================== +.SH "Control characters" +.\" ==================================================================== +. +.\" BEGIN Keep (roughly) parallel with groff.texi node "Control +.\" Characters". +.\" The mechanism of using @code{roff}'s control characters to invoke +.\" requests and call macros was introduced in @ref{Requests and Macros}. +Control characters are recognized only at the beginning of an input +line, +or at the beginning of the branch of a control structure request; +.\" see @ref{Conditionals and Loops}. +see section \[lq]Control structures\[rq] below. +. +. +.P +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. +. +. +.P +The control character +.RB \[lq] .\& \[rq] +and the no-break control character +.RB \[lq] \|\[aq]\| \[rq] +can be changed with the +.B cc +and +.B c2 +requests, +respectively. +. +Within a macro definition, +.\" you might wish to know +register +.B .br +indicates the control character used to call it. +.\" END Keep (roughly) parallel with groff.texi node "Control +.\" Characters". +. +. +.\" ==================================================================== +.SH "Invoking requests" +.\" ==================================================================== +. +.\" BEGIN Keep (roughly) parallel with groff.texi node "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 +.B rm +request makes it unavailable. +. +The +.B als +request can alias requests, +permitting them to be wrapped or non-destructively replaced. +. +See section \[lq]Strings\[rq] below. +. +. +.br +.ne 4v +.P +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 +.I troff \" GNU +does not allow tabs for argument separation. +.\" @footnote{In compatibility mode, a space is not necessary after a +.\" request or macro name of two characters' length. Also, Plan@tie{}9 +.\" @code{troff} allows tabs to separate arguments.} +. +. +.br +.ne 3v +.P +Generally, +a space +.I within +a request argument is not relevant, +not meaningful, +or is supported by bespoke provisions, +as with the +.B tl +request's delimiters. +. +Some requests, +like +.BR ds , +interpret the remainder of the control line as a single argument. +. +See section \[lq]Strings\[rq] below. +. +. +.P +Spaces and tabs immediately after a control character are ignored. +. +Commonly, +authors structure the source of documents or macro files with them. +.\" END Keep (roughly) parallel with groff.texi node "Requests". +. +. +.\" ==================================================================== +.SH "Calling macros" +.\" ==================================================================== +. +.\" BEGIN Keep (roughly) parallel with groff.texi node "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 +.RB \[lq] mac \[rq] +is emitted. +. +Calling an undefined macro +.I does +end a macro definition naming it as its end macro +(see section \[lq]Writing macros\[rq] below). +. +. +.P +To embed spaces +.I within +a macro argument, +enclose the argument in neutral double quotes +.RB \[oq] \|\[dq]\| \[cq]. +. +Horizontal motion escape sequences are sometimes a better choice for +arguments to be formatted as text. +. +. +.P +The foregoing raises the question of how to embed neutral double quotes +or backslashes in macro arguments when +.I those +characters are desired as literals. +. +In GNU +.IR troff , \" GNU +the special character escape sequence +.B \[rs][rs] +produces a backslash and +.B \[rs][dq] +a neutral double quote. +. +. +.P +In GNU +.IR troff 's \" GNU +AT&T compatibility mode, +these characters remain available as +.B \[rs](rs +and +.BR \[rs](dq , +respectively. +. +AT&T +.I troff \" AT&T +did not consistently define these special characters, +.\" It seems that AT&T troff never recognized \(rs, though DWB 3.3 +.\" defined \(bs as an alias of "\" on its "Latin1" device, in +.\" deliberate(?) collision with the Bell System logo identifier. It +.\" also defined \(dq for several devices (pcl, Latin1, nroff, ...) +.\" along with \(aq. +but its descendants can be made to support them. +. +See +.MR groff_font @MAN5EXT@ . +. +If even that is not feasible, +.\" Nope nope nope--if you're this much of a masochist, go read Texinfo. +see the \[lq]Calling Macros\[rq] section of the +.I groff +Texinfo manual for the complex macro argument quoting rules of AT&T +.IR troff . \" AT&T +.\" END Keep (roughly) parallel with groff.texi node "Calling Macros". +. +. +.\" ==================================================================== +.SH "Using escape sequences" +.\" ==================================================================== +. +.\" BEGIN Keep (roughly) parallel with groff.texi node "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 +.BR \[rs] . +.\" (but see the @code{ec} request below) +. +The next character selects the escape's function. +. +. +.P +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 +.I only +an arbitrary-length argument. +. +In the former scheme, +a one-character argument follows the function character immediately, +an opening parenthesis +.RB \[lq] ( \[rq] +introduces a two-character argument +(no closing parenthesis is used), +and an argument of arbitrary length is enclosed in brackets +.RB \[lq] [] \[rq]. +. +In the latter scheme, +the user selects a delimiter character. +. +A few escape sequences are idiosyncratic, +and support both of the foregoing conventions +.RB ( \|\[rs]s ), +designate their own termination sequence +.RB ( \|\[rs]? ), +consume input until the next newline +.RB ( \|\[rs]! , +.BR \|\[rs]" , +.BR \|\[rs]# ), +or support an additional modifier character +.RB ( \|\[rs]s +again, +and +.BR \|\[rs]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. +. +. +.P +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 +.RB \[lq] escape \[rq] +warning category, +which is not enabled by default) +and the following character is processed normally. +. +. +.P +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. +. +. +.P +The escape character can be interpolated +.RB ( \[rs]e ). +. +Requests permit the escape mechanism to be deactivated +.RB ( eo ) +and restored, +or the escape character changed +.RB ( ec ), +and to save and restore it +.RB ( ecs +and +.BR ecr ). +.\" END Keep (roughly) parallel with groff.texi node "Using Escape +.\" Sequences". +. +. +.\" ==================================================================== +.SH Delimiters +.\" ==================================================================== +. +.\" BEGIN Keep (roughly) parallel with groff.texi node "Delimiters". +Some escape sequences that require parameters use delimiters. +. +The neutral apostrophe +.B \[aq] +is a popular choice and shown in this document. +. +The neutral double quote +.B \[dq] +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. +. +. +.br +.ne 2v +.P +The following escape sequences don't take arguments and thus are allowed +as delimiters: +.BI \[rs] space\c +, +.BR \[rs]% , +.BR \[rs]| , +.BR \[rs]\[ha] , +.BR \[rs]{ , +.BR \[rs]} , +.BR \[rs]\[aq] , +.BR \[rs]\[ga] , +.BR \[rs]\- , +.BR \[rs]_ , +.BR \[rs]! , +.BR \[rs]? , +.BR \[rs]) , +.BR \[rs]/ , +.BR \[rs], , +.BR \[rs]& , +.BR \[rs]: , +.BR \[rs]\[ti] , +.BR \[rs]0 , +.BR \[rs]a , +.BR \[rs]c , +.BR \[rs]d , +.BR \[rs]e , +.BR \[rs]E , +.BR \[rs]p , +.BR \[rs]r , +.BR \[rs]t , +and +.BR \[rs]u . +. +However, +using them this way is discouraged; +they can make the input confusing to read. +. +. +.P +A few escape sequences, +.BR \[rs]A , +.BR \[rs]b , +.BR \[rs]o , +.BR \[rs]w , +.BR \[rs]X , +and +.BR \[rs]Z , +accept a newline as a delimiter. +. +Newlines that serve as delimiters continue to be recognized as input +line terminators. +. +Use of newlines as delimiters in escape sequences is also discouraged. +. +. +.br +.ne 2v +.P +Finally, +the escape sequences +.BR \[rs]D , +.BR \[rs]h , +.BR \[rs]H , +.BR \[rs]l , +.BR \[rs]L , +.BR \[rs]N , +.BR \[rs]R , +.BR \[rs]s , +.BR \[rs]S , +.BR \[rs]v , +and +.B \[rs]x +prohibit many delimiters. +. +. +.RS +.IP \[bu] 2n +the numerals 0\[en]9 and the decimal point +.RB \[lq] . \[rq] +. +. +.IP \[bu] +the (single-character) operators +.B +\-/*%<>=&:() +. +. +.IP \[bu] +any escape sequences other than +.BR \[rs]% , +.BR \[rs]: , +.BR \[rs]{ , +.BR \[rs]} , +.BR \[rs]\[aq] , +.BR \[rs]\[ga] , +.BR \[rs]\- , +.BR \[rs]_ , +.BR \[rs]! , +.BR \[rs]/ , +.BR \[rs]c , +.BR \[rs]e , +and +.B \[rs]p +.RE +. +. +.P +Delimiter syntax is complex and flexible primarily for historical +reasons; +the foregoing restrictions need be kept in mind mainly when using +.I groff +in AT&T compatibility mode. +. +GNU +.I troff \" GNU +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, +.B \[aq] +works fine. +. +See section \[lq]Implementation differences\[rq] in +.MR groff_diff @MAN7EXT@ . +.\" END Keep (roughly) parallel with groff.texi node "Delimiters". +. +. +.\" ==================================================================== +.SH "Dummy characters" +.\" ==================================================================== +. +.\" BEGIN Keep (roughly) parallel with groff.texi node "Dummy +.\" Characters". +As discussed in +.MR roff @MAN7EXT@ , +the first character on an input line is treated specially. +. +Further, +formatting a glyph has many +consequences on formatter state +(see section \[lq]Environments\[rq] below). +. +Occasionally, +we want to escape this context or embrace some of those consequences +without actually rendering a glyph to the output. +. +.B \[rs]& +interpolates a dummy character, +which is constitutive of output but invisible. +. +Its presence alters the interpretation context of a subsequent input +character, +and enjoys several applications: +preventing the insertion of extra space after an end-of-sentence +character, +preventing interpretation of a control character at the beginning of an +input line, +preventing kerning between two glyphs, +and permitting the +.B tr +request to remap a character to \[lq]nothing\[rq]. +. +.B \[rs]) +works as +.B \[rs]& +does, +except that it does not cancel a pending end-of-sentence state. +.\" END Keep (roughly) parallel with groff.texi node "Dummy Characters". +. +. +.\" ==================================================================== +.SH "Control structures" +.\" ==================================================================== +. +.I groff +has \[lq]if\[rq] and \[lq]while\[rq] control structures like other +languages. +. +However, +the syntax for grouping multiple input lines in the branches or bodies +of these structures is unusual. +. +. +.P +They have a common form: +the request name is +(except for +.request .el +\[lq]else\[rq]) +followed by a conditional expression +.IR cond-expr ; +the remainder of the line, +.IR anything , +is interpreted as if it were an input line. +. +Any quantity of spaces between arguments to requests serves only to +separate them; +leading spaces in +.I anything +are therefore not seen. +. +.I anything +effectively +.I cannot +be omitted; +if +.I cond-expr +is true and +.I anything +is empty, +the newline at the end of the control line is interpreted as a blank +line +(and therefore a blank text line). +. +. +.P +It is frequently desirable for a control structure to govern more than +one request, +macro call, +or text line, +or a combination of the foregoing. +. +The opening and closing brace escape sequences +.esc { +and +.esc } +perform such grouping. +. +Brace escape sequences outside of control structures have no meaning and +produce no output. +. +. +.P +.esc { +should appear +(after optional spaces and tabs) +immediately subsequent to the request's conditional expression. +. +.esc } +should appear on a line with other occurrences of itself as necessary to +match +.esc { +sequences. +. +It can be preceded by a control character, +spaces, +and tabs. +. +Input after any quantity of +.esc } +sequences on the same line is processed only if all the preceding +conditions to which they correspond are true. +. +Furthermore, +a +.esc } +closing the body of a +.request .while +request must be the last such escape sequence on an input line. +. +. +.\" ==================================================================== +.SS "Conditional expressions" +.\" ==================================================================== +. +.\" BEGIN Keep (roughly) parallel with groff.texi node "Operators in +.\" Conditionals". +The +.request .if , +.request .ie , +and +.request .while +requests test the truth values of numeric expressions. +. +They also support several additional Boolean operators; +the members of this expanded class are termed +.IR "conditional expressions" ; +their truth values are as shown below. +. +. +.br +.ne 3v +.P +.TS +rf(BI) lB +rB lx. +cond-expr\f[R].\|.\|. .\|.\|.is true if.\|.\|. +_ +T{ +.BI \[aq] s1 \[aq] s2 \[aq] +T} T{ +.I s1 +produces the same formatted output as +.IR s2 . +T} +T{ +.BI c\~ g +T} T{ +a glyph +.I g +is available. +T} +T{ +.BI d\~ m +T} T{ +a string, +macro, +diversion, +or request +.I m +is defined. +T} +e T{ +the current page number is even. +T} +T{ +.BI F\~ f +T} T{ +a font named +.I f +is available. +T} +T{ +.BI m\~ c +T} T{ +a color named +.I c +is defined. +T} +n T{ +the formatter is in +.I nroff +mode. +T} +o T{ +the current page number is odd. +T} +T{ +.BI r\~ n +T} T{ +a register named +.I n +is defined. +T} +T{ +.BI S\~ s +T} T{ +a font style named +.I s +is available. +T} +t T{ +the formatter is in +.I troff +mode. +T} +v T{ +n/a +(historical artifact; +always false). +T} +.TE +. +. +.br +.ne 2v +.P +If the first argument to an +.BR .if , +.BR .ie , +or +.B .while +request begins with a non-alphanumeric character apart from +.B !\& +(see below); +it performs an +.I output comparison test. +. +Shown first in the table above, +the +.I output comparison operator +interpolates a true value if formatting its comparands +.I s1 +and +.I s2 +produces the same output commands. +. +Other delimiters can be used in place of the neutral apostrophes. +. +.I @g@troff +formats +.I s1 +and +.I s2 +in separate environments; +after the comparison, +the resulting data are discarded. +. +The resulting glyph properties, +including font family, +style, +size, +and +slant, +must match, +but not necessarily the requests and/or escape sequences used to obtain +them. +. +Motions must match in orientation and magnitude to within the applicable +horizontal or vertical motion quantum of the device, +after rounding. +. +.\" TODO: Uncomment and add forward reference when we add a "GNU troff +.\" internals" subsection to this page. +.\"(All of this is to say that the lists of output nodes created by +.\"formatting +.\".I s1 +.\"and +.\".I s2 +.\"must be identical.) +. +. +.P +Surround the comparands with +.B \[rs]?\& +to avoid formatting them; +this causes them to be compared character by character, +as with string comparisons in other programming languages. +. +Since comparands protected with +.B \[rs]?\& +are read in copy mode, +they need not even be valid +.I groff +syntax. +. +The escape character is still lexically recognized, +however, +and consumes the next character. +. +. +.P +The above operators can't be combined with most others, +but a leading +.RB \[lq] !\& \[rq], +not followed immediately by spaces or tabs, +complements an expression. +. +Spaces and tabs are optional immediately after the +.RB \[lq] c \[rq], +.RB \[lq] d \[rq], +.RB \[lq] F \[rq], +.RB \[lq] m \[rq], +.RB \[lq] r \[rq], +and +.RB \[lq] S \[rq] +operators, +but right after +.RB \[lq] !\& \[rq], +they end the predicate and the conditional evaluates true. +. +(This bizarre behavior maintains compatibility with AT&T +.IR troff .) +.\" END Keep (roughly) parallel with groff.texi node "Operators in +.\" Conditionals". +. +. +.\" ==================================================================== +.SH "Syntax reference conventions" +.\" ==================================================================== +. +In the following request and escape sequence specifications, +most argument names were chosen to be descriptive. +. +A few denotations may require introduction. +. +. +.P +.LS +.RS +. +.TPx +.I c +denotes a single input character. +. +.TPx +.I font +a font either specified as a font name or a numeric mounting position. +. +.TPx +.I anything +all characters up to the end of the line, +to the ending delimiter for the escape sequence, +or within +.esc { +and +.esc } . +. +Escape sequences may generally be used freely in +.IR anything , +except when it is read in copy mode. +. +.TPx +.I message +is a character sequence to be emitted on the standard error stream. +. +Special character escape sequences are +.I not +interpreted. +. +.TPx +.I n +is a numeric expression that evaluates to a non-negative integer. +. +.TPx +.I npl +is a numeric expression constituting a count of subsequent +.I productive +input lines; +that is, +those that directly produce formatted output. +. +Text lines produce output, +as do control lines containing requests like +.request .tl +or escape sequences like +.esc D . +. +Macro calls are not themselves productive, +but their interpolated contents can be. +. +.TPx +.I \[+-]N +is a numeric expression with a meaning dependent on its sign. +.RE +.LE +. +. +.P +If a numeric expression presented as +.I \[+-]N +starts with a +.squoted_char + +sign, +an increment in the amount of +.RI of\~ N +is applied to the value applicable to the request or escape sequence. +. +If it starts with a +.squoted_char \- +sign, +a decrement of magnitude +.I N +is applied instead. +. +Without a sign, +.I N +replaces any existing value. +. +A leading minus sign +.RI in\~ N +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, +enclose it with its operand in +parentheses or subtract it from zero. +. +If a prior value does not exist +(the register was undefined), +an increment or decrement is applied as if to\~0. +. +. +.\" ==================================================================== +.SH "Request short reference" +.\" ==================================================================== +. +Not all details of request behavior are outlined here. +. +See the +.I groff +Texinfo manual or, +for features new to GNU +.IR troff , \" GNU +.MR groff_diff @MAN7EXT@ . +. +. +.P +.LS +. +.TPx +.REQ .ab +Abort processing; +exit with failure status. +. +.TPx +.REQ .ab message +Abort processing; +write +.I message +to the standard error stream and exit with failure status. +. +. +.TPx +.REQ .ad +Enable output line alignment and adjustment using the mode stored in +.BR \[rs]n[.j] . +. +. +.TPx +.REQ .ad c +Enable output line alignment and adjustment in mode +.I c +.RI ( c =\c +.BR b , c , l , n , r ). +. +Sets +.BR \[rs]n[.j] . +. +. +.TPx +.REQ .af "register c" +Assign format +.I c +to +.IR register , +where +.I c +is +.RB \[lq] i \[rq], +.RB \[lq] I \[rq], +.RB \[lq] a \[rq], +.RB \[lq] A \[rq], +or a sequence of decimal digits whose quantity denotes the minimum width +in digits to be used when the register is interpolated. +. +.RB \[lq] i \[rq] +and +.RB \[lq] a \[rq] +indicate Roman numerals and basic Latin alphabetics, +respectively, +in the lettercase specified. +. +The default is +.BR 0 . +. +.TPx +.REQ .aln "new old" +Create alias +(additional name) +.I new +for existing register named +.IR old . +. +.TPx +.REQ .als "new old" +Create alias +(additional name) +.I new +for existing request, +string, +macro, +or diversion +.IR old . +. +.TPx +.REQ .am "macro" +Append to +.I macro +until +.B ..\& +is encountered. +. +.TPx +.REQ .am "macro end" +Append to +.I macro +until +.BI . end +is called. +. +.TPx +.REQ .am1 "macro" +Same as +.request .am +but with compatibility mode switched off during macro expansion. +. +.TPx +.REQ .am1 "macro end" +Same as +.request .am +but with compatibility mode switched off during macro expansion. +. +.TPx +.REQ .ami "macro" +Append to a macro whose name is contained in the string +.I macro +until +.B ..\& +is encountered. +. +.TPx +.REQ .ami "macro end" +Append to a macro indirectly. +.I macro +and +.I end +are strings whose contents are interpolated for the macro name and the +end macro, +respectively. +. +.TPx +.REQ .ami1 "macro" +Same as +.request .ami +but with compatibility mode switched off during macro expansion. +. +.TPx +.REQ .ami1 "macro end" +Same as +.request .ami +but with compatibility mode switched off during macro expansion. +. +.TPx +.REQ .as name +Create string +.I name +with empty contents; +no operation if +.I name +already exists. +. +.TPx +.REQ .as "name contents" +Append +.I contents +to string +.IR name . +. +.TPx +.REQ .as1 string +.TQ +.REQ .as1 "string contents" +As +.request .as , +but with compatibility mode disabled when +.I contents +interpolated. +. +.TPx +.REQ .asciify "diversion" +Unformat ASCII characters, spaces, and some escape sequences in +.IR diversion . +. +.TPx +.REQ .backtrace +Write the state of the input stack to the standard error stream. +. +See the +.B \-b +option of +.MR groff @MAN1EXT@ . +. +.TPx +.REQ .bd font +Stop emboldening font +.I font. +. +.TPx +.REQ .bd "font n" +Embolden +.I font +by overstriking its glyphs offset by +.IR n \-1 +units. +. +See +.register .b . +.\" XXX: negative values accepted; check AT&T troff +. +.TPx +.REQ .bd "special-font font" +Stop emboldening +.I special-font +when +.I font +is selected. +. +.TPx +.REQ .bd "special-font font n" +Embolden +.I special-font, +overstriking its glyphs offset by +.IR n \-1 +units when +.I font +is selected. +. +See +.register .b . +. +.TPx +.REQ .blm +Unset blank line macro (trap). +. +Restore default handling of blank lines. +. +. +.TPx +.REQ .blm name +Set blank line macro (trap) to +.IR name . +. +. +.TPx +.REQ .box +Stop directing output to current diversion; +any pending output line is discarded. +. +. +.TPx +.REQ .box name +Direct output to diversion +.IR name , +omitting a partially collected line. +. +. +.TPx +.REQ .boxa +Stop appending output to current diversion; +any pending output line is discarded. +. +. +.TPx +.REQ .boxa name +Append output to diversion +.IR name , +omitting a partially collected line. +. +. +.TPx +.REQ .bp +Break page and start a new one. +. +.TPx +.REQ .bp "\[+-]N" +Break page, +starting a new one numbered +.IR \[+-]N . +. +.TPx +.REQ .br +Break output line. +. +.TPx +.REQ .brp +Break output line; +adjust if applicable. +. +.TPx +.REQ .break +Break out of a while loop. +. +.TPx +.REQ .c2 +Reset no-break control character to +.dquoted_char \[aq] . +. +.TPx +.REQ .c2 "o" +Recognize ordinary character +.I o +as no-break control character. +. +.TPx +.REQ .cc +Reset control character to +.squoted_char . . +. +.TPx +.REQ .cc "o" +Recognize ordinary character +.I o +as the control character. +. +.TPx +.REQ .ce +Break, +center the output of the next productive input line without filling, +and break again. +. +.TPx +.REQ .ce npl +Break, +center the output of the next +.I npl +productive input lines without filling, +then break again. +. +If +.I npl +\[<=] 0, +stop centering. +. +.TPx +.REQ .cf file +Copy contents of +.I file +without formatting to the (top-level) diversion. +. +.TPx +.REQ .cflags "n c1 c2 \fR\&.\|.\|.\&\fP" +Assign properties encoded +.RI by\~ n +to characters +.IR c1 , +.IR c2 , +and so on. +. +. +.TPx +.REQ .ch name +Unplant page location trap +.IR name . +. +. +.TPx +.REQ .ch "name vpos" +Change page location trap +.I name +planted by +.request .wh +by moving its location to +.I vpos +(default scaling unit\~\c +.scaleindicator v ). +. +. +.TPx +.REQ .char "c contents" +Define ordinary or special character +.I c +as +.IR contents . +. +.TPx +.REQ .chop object +Remove the last character from the macro, +string, +or diversion +named +.IR object . +. +.TPx +.REQ .class "name c1 c2 \fR\&.\|.\|.\&\fP" +Define a (character) class +.I name +comprising the characters or range expressions +.IR c1 , +.IR c2 , +and so on. +. +.TPx +.REQ .close "stream" +Close the +.IR stream . +. +. +.TPx +.REQ .color +Enable output of color-related device-independent output commands. +. +. +.TPx +.REQ .color n +If +.I n +is zero, +disable output of color-related device-independent output commands; +otherwise, +enable them. +.\" XXX: Should probably interpret negative values as false. +. +. +.TPx +.REQ .composite "from to" +Map glyph name +.I from +to glyph name +.I to +while constructing a composite glyph name. +. +.TPx +.REQ .continue +Finish the current iteration of a while loop. +. +.TPx +.REQ .cp +Enable compatibility mode. +. +.TPx +.REQ .cp n +If +.I n +is zero, +disable compatibility mode, +otherwise enable it. +. +.TPx +.REQ .cs "font n m" +Set constant character width mode for +.I font +to +.IR n /36 +ems with em +.IR m . +.\" XXX: m parameter needs more explanation. +. +. +.TPx +.REQ .cu +Continuously underline the output of the next productive input line. +. +. +.TPx +.REQ .cu npl +Continuously underline the output of the next +.I npl +productive input lines. +. +If +.IR npl =0, +stop continuously underlining. +. +. +.TPx +.REQ .da +Stop appending output to current diversion. +. +. +.TPx +.REQ .da name +Append output to diversion +.IR name . +. +. +.TPx +.REQ .de macro +Define or redefine +.I macro +until +.RB \[lq] ..\& \[rq] +occurs at the start of a control line in the current conditional block. +. +. +.TPx +.REQ .de "macro end" +Define or redefine +.I macro +until +.I end +is invoked or called at the start of a control line in the current +conditional block. +. +. +.TPx +.REQ .de1 "macro" +As +.request .de , +but disable compatibility mode during macro expansion. +. +.TPx +.REQ .de1 "macro end" +As +.RB \[lq] .de +.IR "macro end" \[rq], +but disable compatibility mode during macro expansion. +. +. +.TPx +.REQ .defcolor "ident scheme color-component \f[R].\|.\|." +Define a color named +.I ident. +. +.I scheme +identifies a color space and determines the number of required +.IR color-component s; +it must be one of +.RB \[lq] rgb \[rq] +(three components), +.RB \[lq] cmy \[rq] +(three), +.RB \[lq] cmyk \[rq] +(four), +or +.RB \[lq] gray \[rq] +(one). +. +.RB \[lq] grey \[rq] +is accepted as a synonym of +.RB \[lq] gray \[rq]. +. +The color components can be encoded as a single hexadecimal value +starting with +.B # +or +.BR ## . +. +The former indicates that each component is in the range 0\[en]255 +(0\[en]FF), +the latter the range 0\[en]65,535 (0\[en]FFFF). +. +Alternatively, +each color component can be specified as a decimal fraction in the range +0\[en]1, +interpreted using a default scaling unit +.RB of\~\[lq] f \[rq], +which multiplies its value by 65,536 +(but clamps it at 65,535). +. +Each output device has a color named +.RB \[lq] default \[rq], +which cannot be redefined. +. +A device's default stroke and fill colors are not necessarily the same. +. +. +.TPx +.REQ .dei "macro" +Define macro indirectly. +. +As +.request .de , +but use interpolation of string +.I macro +as the name of the defined macro. +. +. +.TPx +.REQ .dei "macro end" +Define macro indirectly. +. +As +.request .de , +but use interpolations of strings +.I macro +and +.I end +as the names of the defined and end macros. +. +. +.TPx +.REQ .dei1 "macro" +As +.request .dei , +but disable compatibility mode during macro expansion. +. +. +.TPx +.REQ .dei1 "macro end" +As +.request ".dei\~\f[I]macro\~end\f[]" , +but disable compatibility mode during macro expansion. +. +.TPx +.REQ .device "anything" +Write +.IR anything , +read in copy mode, +to +.I @g@troff +output as a device control command. +. +An initial neutral double quote is stripped to allow embedding of +leading spaces. +. +.TPx +.REQ .devicem "name" +Write contents of macro or string +.I name +to +.I @g@troff +output as a device control command. +. +.TPx +.REQ .di +Stop directing output to current diversion. +. +. +.TPx +.REQ .di name +Direct output to diversion +.IR name . +. +.TPx +.REQ .do "name \fR\&.\|.\|.\&\fP" +Interpret the string, +request, +diversion, +or macro +.I name +(along with any arguments) +with compatibility mode disabled. +. +Compatibility mode is restored +(only if it was active) +when the +.I expansion +of +.I name +is interpreted. +. +.TPx +.REQ .ds name +Create empty string +.IR name . +. +.TPx +.REQ .ds "name contents" +Create a string +.I name +containing +.IR contents . +. +.TPx +.REQ .ds1 name +.TQ +.REQ .ds1 "name contents" +As +.request .ds , +but with compatibility mode disabled when +.I contents +interpolated. +. +.TPx +.REQ .dt +Clear diversion trap. +. +. +.TPx +.REQ .dt "vertical-position name" +Set the diversion trap to macro +.I name +at +.I vertical-position +(default scaling unit\~\c +.scaleindicator v ). +. +. +.TPx +.REQ .ec +Recognize +.B \[rs] +as the escape character. +. +. +.TPx +.REQ .ec "o" +Recognize ordinary character +.I o +as the escape character. +. +. +.TPx +.REQ .ecr +Restore escape character saved with +.request .ecs . +. +. +.TPx +.REQ .ecs +Save the escape character. +. +. +.TPx +.REQ .el "anything" +Interpret +.I anything +as if it were an input line if the conditional expression of the +corresponding +.request .ie +request was false. +. +. +.TPx +.REQ .em name +Call macro +.I name +after the end of input. +. +. +.TPx +.REQ .eo +Disable the escape mechanism in interpretation mode. +. +. +.TPx +.REQ .ev +Pop environment stack, +returning to previous one. +. +. +.TPx +.REQ .ev "env" +Push current environment onto stack and switch to +.IR env . +. +. +.TPx +.REQ .evc "env" +Copy environment +.I env +to the current one. +. +. +.TPx +.REQ .ex +Exit with successful status. +. +. +.TPx +.REQ .fam +Set default font family to previous value. +. +.TPx +.REQ .fam "name" +Set default font family to +.IR name . +. +.TPx +.REQ .fc +Disable field mechanism. +. +.TPx +.REQ .fc "a" +Set field delimiter to\~\c +.I a +and pad glyph to space. +. +.TPx +.REQ .fc "a b" +Set field delimiter to\~\c +.I a +and pad glyph to\~\c +.IR b . +. +.TPx +.REQ .fchar "c contents" +Define fallback character (or glyph) +.I c +as +.IR contents . +. +. +.TPx +.REQ .fcolor +Restore previous fill color. +. +. +.TPx +.REQ .fcolor "c" +Set fill color to +.IR c . +. +. +.TPx +.REQ .fi +Enable filling of output lines; +a pending output line is broken. +. +Sets +.BR \[rs]n[.u] . +. +. +.TPx +.REQ .fl +Flush output buffer. +. +.TPx +.REQ .fp "pos id" +Mount font with font description file name +.I id +at non-negative +.RI position\~ n . +. +.TPx +.REQ .fp "pos id font-description-file-name" +Mount font with +.I font-description-file-name +as name +.I id +at non-negative +.RI position\~ n . +. +.TPx +.REQ .fschar "f c anything" +Define fallback character (or glyph) +.I c +for font +.I f +as string +.IR anything . +. +.TPx +.REQ .fspecial "font" +Reset list of special fonts for +.I font +to be empty. +. +.TPx +.REQ .fspecial "font s1 s2 \fR\&.\|.\|.\&\fP" +When the current font is +.IR font , +then the fonts +.IR s1 , +.IR s2 , +\&.\|.\|.\& +are special. +. +.TPx +.REQ .ft +.TQ +.REQ ".ft P" +Select previous font mounting position +(abstract style or font); +same as +.esc f[] +or +.esc fP . +. +.TPx +.REQ .ft "font" +Select typeface +.I font, +which can be a +mounting position, +abstract style, +or font name; +same as +.esc[] f font +escape sequence. +. +.I font +cannot be +.BR P . +. +.TPx +.REQ .ftr "font1 font2" +Translate +.I font1 +to +.IR font2 . +. +.TPx +.REQ .fzoom font +.TQ +.REQ .fzoom font\~\f[CB]0\f[] +Stop magnifying +.IR font . +. +.TPx +.REQ .fzoom "font z" +Set zoom factor for +.I font +.RI to\~ z +(in thousandths; +default: +1000). +. +.TPx +.REQ .gcolor +Restore previous stroke color. +. +. +.TPx +.REQ .gcolor "c" +Set stroke color to +.IR c . +. +. +.TPx +.REQ .hc +Reset the hyphenation character +.RB to\~ \[rs]% +(the default). +. +.TPx +.REQ .hc char +Change the hyphenation character +.RI to\~ char . +. +.TPx +.REQ .hcode "c1 code1 \fR[\fPc2 code2\fR] .\|.\|.\fP" +Set the hyphenation code of character +.I c1 +to +.IR code1 , +that of +.I c2 +to +.IR code2 , +and so on. +. +.TPx +.REQ .hla lang +Set the hyphenation language to +.IR lang . +. +.TPx +.REQ .hlm n +Set the maximum quantity of consecutive hyphenated lines to +.IR n . +. +.TPx +.REQ .hpf pattern-file +Read hyphenation patterns from +.IR pattern-file . +. +.TPx +.REQ .hpfa pattern-file +Append hyphenation patterns from +.IR pattern-file . +. +.TPx +.REQ .hpfcode "a b \fR[\fPc d\fR] .\|.\|.\fP" +Define mappings for character codes in hyphenation pattern files read +with +.request .hpf +and +.request .hpfa . +. +.TPx +.REQ .hw "word \fR.\|.\|.\fP" +Define hyphenation overrides for each +.I word; +a hyphen +.RB \[lq] \- \[rq] +indicates a hyphenation point. +. +. +.TPx +.REQ .hy +Set automatic hyphenation mode to +.BR 1 . +. +. +.TPx +.REQ .hy\~0 +Disable automatic hyphenation; +same as +.BR .nh . +. +. +.TPx +.REQ .hy mode +Set automatic hyphenation mode to +.IR mode ; +see section \[lq]Hyphenation\[rq] below. +. +. +.TPx +.REQ .hym +Set the (right) hyphenation margin to +.B 0 +(the default). +. +.TPx +.REQ .hym length +Set the (right) hyphenation margin to +.I length +(default scaling unit\~\c +.scaleindicator m ). +. +.TPx +.REQ .hys +Set the hyphenation space to +.B 0 +(the default). +. +.TPx +.REQ .hys hyphenation-space +Suppress automatic hyphenation in adjustment modes +.RB \[lq] b \[rq] +or +.RB \[lq] n \[rq] +if the line can be justified with the addition of up to +.I hyphenation-space +to each inter-word space +(default scaling unit\~\c +.scaleindicator m ). +. +. +.TPx +.REQ .ie "cond-expr anything" +If +.I cond-expr +is true, +interpret +.I anything +as if it were an input line, +otherwise skip to a corresponding +.request .el +request. +. +. +.TPx +.REQ .if "cond-expr anything" +If +.I cond-expr +is true, +then interpret +.I anything +as if it were an input line. +. +. +.TPx +.REQ .ig +Ignore input +(except for side effects of +.B \[rs]R +on auto-incrementing registers) +until +.RB \[lq] ..\& \[rq] +occurs at the start of a control line in the current conditional block. +. +. +.TPx +.REQ .ig "end" +Ignore input +(except for side effects of +.B \[rs]R +on auto-incrementing registers) +until +.BI . end +is called at the start of a control line in the current conditional +block. +. +.TPx +.REQ .in +Set indentation amount to previous value. +. +.TPx +.REQ .in "\[+-]N" +Set indentation to +.I \[+-]N +(default scaling unit\~\c +.scaleindicator m ). +. +.TPx +.REQ .it +Cancel any pending input line trap. +. +.TPx +.REQ .it "npl name" +Set +(or replace) +an input line trap in the environment, +calling macro +.IR name , +after the next +.I npl +productive input lines have been read. +. +Lines interrupted with the +.B \[rs]c +escape sequence are counted separately. +. +.TPx +.REQ .itc +Cancel any pending input line trap. +. +.TPx +.REQ .itc "npl name" +As +.request .it , +except that input lines interrupted with the +.B \[rs]c +escape sequence are not counted. +. +.TPx +.REQ .kern +Enable pairwise kerning. +. +.TPx +.REQ .kern n +If +.I n +is zero, +disable pairwise kerning, +otherwise enable it. +. +.TPx +.REQ .lc +Unset leader repetition character. +. +.TPx +.REQ .lc "c" +Set leader repetition character +.RI to\~ c +(default: +.RB \[lq] . \[rq]). +. +.TPx +.REQ .length "reg anything" +Compute the number of characters of +.I anything +and store the count +in the register +.IR reg . +. +. +.TPx +.REQ .linetabs +Enable line-tabs mode +(calculate tab positions relative to beginning of output line). +. +. +.TPx +.REQ .linetabs\~0 +Disable line-tabs mode. +. +. +.TPx +.REQ .lf n +Set number of next input line to +.IR n . +.\" XXX: negative values accepted; check AT&T troff +. +.TPx +.REQ .lf "n file" +Set number of next input line to +.I n +and input file name to +.IR file . +. +.TPx +.REQ .lg m +Set ligature mode to +.I m +.RB ( 0 += disable, +.B 1 += enable, +.B 2 += enable for two-letter ligatures only). +.\" XXX: negative values accepted (mapped to 1); check AT&T troff +. +.TPx +.REQ .ll +Set line length to previous value. +. +Does not affect a pending output line. +. +.TPx +.REQ .ll "\[+-]N" +Set line length to +.I \[+-]N +(default length +.scalednumber 6.5 i , +default scaling unit\~\c +.scaleindicator m ). +. +Does not affect a pending output line. +. +.TPx +.REQ .lsm +Unset the leading space macro (trap). +. +Restore default handling of lines with leading spaces. +. +.TPx +.REQ .lsm name +Set the leading space macro (trap) to +.IR name . +. +.TPx +.REQ .ls +Change to the previous value of additional intra-line skip. +. +.TPx +.REQ .ls n +Set additional intra-line skip value to +.IR n , +i.e., +.IR n \-1 +blank lines are inserted after each text output line. +.\" XXX: negative values accepted; check AT&T troff +. +.TPx +.REQ .lt +Set length of title lines to previous value. +. +.TPx +.REQ .lt "\[+-]N" +Set length of title lines +(default length +.scalednumber 6.5 i , +default scaling unit\~\c +.scaleindicator m ). +. +.TPx +.REQ .mc +Cease writing margin character. +. +.TPx +.REQ .mc c +Begin writing margin +.RI character\~ c +to the right of each output line. +. +.TPx +.REQ .mc "c d" +Begin writing margin +.RI character\~ c +on each output line at +.RI distance\~ d +to the right of the right margin +(default distance +.scalednumber 10 p , +default scaling unit\~\c +.scaleindicator m ). +. +.TPx +.REQ .mk +Mark vertical drawing position in an internal register; +see +.BR .rt . +. +.TPx +.REQ .mk register +Mark vertical drawing position in +.IR register . +. +.TPx +.REQ .mso "file" +As +.request .so , +except that +.I file +is sought in the +.I tmac +directories. +. +. +.TPx +.REQ .msoquiet "file" +As +.request .mso , +but no warning is emitted if +.I file +does not exist. +. +. +.TPx +.REQ .na +Disable output line adjustment. +. +. +.TPx +.REQ .ne +Break page if distance to next page location trap is less than one vee. +. +.TPx +.REQ .ne d +Break page if distance to next page location trap is less than distance +.I d +(default scaling unit\~\c +.scaleindicator v ). +. +. +.TPx +.REQ .nf +Disable filling of output lines; +a pending output line is broken. +. +Clears +.BR \[rs]n[.u] . +. +. +.TPx +.REQ .nh +Disable automatic hyphenation; +same as +.RB \[lq] ".hy 0" \[rq]. +. +.TPx +.REQ .nm +Deactivate output line numbering. +. +.TPx +.REQ .nm \[+-]N +.TQ +.REQ .nm "\[+-]N m" +.TQ +.REQ .nm "\[+-]N m s" +.TQ +.REQ .nm "\[+-]N m s i" +Activate output line numbering: +number the next output line +.I \[+-]N, +writing numbers every +.I m +lines, +with +.I s +numeral widths +.RB ( \[rs]0 ) +between the line number and the output +(default 1), +and indenting the line number by +.I i +numeral widths +(default 0). +. +.TPx +.REQ .nn +Suppress numbering of the next output line to be numbered with +.BR nm . +. +.TPx +.REQ .nn n +Suppress numbering of the next +.I n +output lines to be numbered with +.BR nm . +. +If +.IR n =0, +cancel suppression. +.\" XXX: negative values accepted; check AT&T troff +. +. +.TPx +.REQ .nop "anything" +Interpret +.I anything +as if it were an input line. +. +.TPx +.REQ .nr "reg \[+-]N" +Define or update register +.I reg +with value +.IR N . +. +.TPx +.REQ .nr "reg \[+-]N I" +Define or update register +.I reg +with value +.I N +and auto-increment +.IR I . +. +.TPx +.REQ .nroff +Make the conditional expressions +.B n +true and +.B t +false. +. +.TPx +.REQ .ns +Enable +.IR "no-space mode" , +ignoring +.B .sp +requests until a glyph or +.B \[rs]D +primitive is output. +. +See +.BR .rs . +. +.TPx +.REQ .nx +Immediately jump to end of current file. +. +.TPx +.REQ .nx file +Stop formatting current file and begin reading +.I file. +. +.TPx +.REQ .open "stream file" +Open +.I file +for writing and associate the stream named +.I stream +with it. +. +Unsafe request; +disabled by default. +. +.TPx +.REQ .opena "stream file" +As +.request .open , +but append to +.I file. +. +Unsafe request; +disabled by default. +. +.TPx +.REQ .os +Output vertical distance that was saved by the +.request .sv +request. +. +.TPx +.REQ .output contents +Emit +.I contents +directly to intermediate output, +allowing leading whitespace if +.I string +starts with +\&\f[CB]\[dq]\f[] +(which is stripped off). +. +.TPx +.REQ .pc +Reset page number character to\~\c +.squoted_char % . +. +.TPx +.REQ .pc "c" +Page number character. +. +. +.TPx +.REQ .pev +Report the state of the current environment followed by that of all +other environments to the standard error stream. +. +.TPx +.REQ .pi "program" +Pipe output to +.I program +.RI ( nroff +only). +. +Unsafe request; +disabled by default. +. +.TPx +.REQ .pl +Set page length to default +.scalednumber 11 i . +The current page length is stored in register +.BR .p . +. +.TPx +.REQ .pl "\[+-]N" +Change page length to +.I \[+-]N +(default scaling unit\~\c +.scaleindicator v ). +. +.TPx +.REQ .pm +Report, +to the standard error stream, +the names and sizes in bytes of +defined +macros, +strings, +and +diversions. +. +.TPx +.REQ .pn "\[+-]N" +Next page number +.IR N . +. +.TPx +.REQ .pnr +Write the names and contents of all defined registers to the standard +error stream. +. +.TPx +.REQ .po +Change to previous page offset. +. +The current page offset is available in register +.BR .o . +. +.TPx +.REQ .po "\[+-]N" +Page offset +.IR N . +. +. +.TPx +.REQ .ps +Return to previous type size. +.TPx +. +. +.REQ .ps "\[+-]N" +Set/increase/decrease the type size to/by +.I N +scaled points +(a non-positive resulting type size is set to 1\~u); +also see +.esc[] s \[+-]N . +. +.TPx +.REQ .psbb file +Retrieve the bounding box of the PostScript image found in +.I file, +which must conform to Adobe's Document Structuring Conventions (DSC). +. +See registers +.BR llx , +.BR lly , +.BR urx , +.BR ury . +. +.TPx +.REQ .pso "command-line" +Execute +.I command-line +with +.MR popen 3 +and interpolate its output. +. +Unsafe request; +disabled by default. +. +.TPx +.REQ .ptr +Report names and positions of all page location traps to the standard +error stream. +. +. +.TPx +.REQ .pvs +Change to previous post-vertical line spacing. +. +.TPx +.REQ .pvs "\[+-]N" +Change post-vertical line spacing according to +.I \[+-]N +(default scaling unit\~\c +.scaleindicator p ). +. +.TPx +.REQ .rchar "c1 c2 \fR.\|.\|.\&\fP" +Remove definition of each ordinary or special character +.IR c1 , +.IR c2 , +\&.\|.\|.\& defined by a +.request .char , +.request .fchar , +or +.request .schar +request. +. +.TPx +.REQ .rd "prompt" +Read insertion. +. +.TPx +.REQ .return +Return from a macro. +. +.TPx +.REQ .return "anything" +Return twice, namely from the macro at the current level and from the +macro one level higher. +. +.TPx +.REQ .rfschar "f c1 c2 \fR\&.\|.\|.\&\fP" +Remove the font-specific definitions of glyphs +.IR c1 , +.IR c2 , +\&.\|.\|.\& for +.RI font\~ f . +. +.TPx +.REQ .rj npl +Break, +right-align the output of the next productive input line without +filling, +then break again. +. +.TPx +.REQ .rj npl +Break, +right-align the output of the next +.I npl +productive input lines without filling, +then break again. +. +If +.I npl +\[<=] 0, +stop right-aligning. +. +.TPx +.REQ .rm "name" +Remove request, macro, diversion, or string +.IR name . +. +.TPx +.REQ .rn "old new" +Rename request, macro, diversion, or string +.I old +to +.IR new . +. +.TPx +.REQ .rnn "reg1 reg2" +Rename register +.I reg1 +to +.IR reg2 . +. +. +.TPx +.REQ .rr ident +Remove register +.IR ident . +. +. +.TPx +.REQ .rs +Restore spacing; +disable no-space mode. +. +See +.BR .ns . +. +.TPx +.REQ .rt +Return +.I (upward only) +to vertical position marked by +.B .mk +on the current page. +. +.TPx +.REQ .rt N +Return +.I (upward only) +to vertical position +.I N +(default scaling +unit\~\c +.scaleindicator v ). +.\" XXX: negative values accepted; check AT&T troff +. +.TPx +.REQ .schar "c contents" +Define global fallback character (or glyph)\~\c +.I c +as +.IR contents . +. +. +.TPx +.REQ .shc +Reset the soft hyphen character to +.esc [hy] . +. +. +.TPx +.REQ .shc c +Set the soft hyphen character +.RI to\~ c . +. +. +.TPx +.REQ .shift n +In a macro definition, +left-shift arguments by +.IR n \~\c +positions. +. +.TPx +.REQ .sizes "s1 s2 \f[R].\|.\|.\&\f[] sn \f[R][\f[CB]0\f[]]" +Set available type sizes similarly to the +.B sizes +directive in a +.I DESC +file. +. +Each +.IR s i +is interpreted in units of scaled points (\c +.scaleindicator z ). +. +. +.TPx +.REQ .so file +Replace the request's control line with the contents of +.IR file , +\[lq]sourcing\[rq] it. +. +. +.TPx +.REQ .soquiet file +As +.request .so , +but no warning is emitted if +.I file +does not exist. +. +. +.TPx +.REQ .sp +Break and move the next text baseline down by one vee, +or until springing a page location trap. +. +. +.TPx +.REQ .sp dist +Break and move the next text baseline down by +.IR dist , +or until springing a page location trap +(default scaling unit\~\c +.scaleindicator v ). +. +A negative +.I dist +will not reduce the position of the text baseline below zero. +. +Prefixing +.I dist +with the +.B \[or] +operator moves to a position relative to the page top for positive +.IR N , +and the bottom if +.I N +is negative; +in all cases, +one line height (vee) is added +.RI to\~ dist . +. +.I dist +is ignored inside a diversion. +. +. +.TPx +.REQ .special +Reset global list of special fonts to be empty. +. +.TPx +.REQ .special "s1 s2 \fR\&.\|.\|.\&\fR" +Fonts +.IR s1 , +.IR s2 , +etc.\& are special and are searched for glyphs not in the +current font. +. +.TPx +.REQ .spreadwarn +Toggle the spread warning on and off (the default) without changing its +value. +. +.TPx +.REQ .spreadwarn N +Emit a +.B break +warning if the additional space inserted for each space between words in +an adjusted output line is greater than or equal to +.IR N . +. +A negative +.I N +is treated as 0. +. +The default scaling unit is\~\c +.scaleindicator m . +. +At startup, +.request .spreadwarn +is inactive and +.I N +is +.scalednumber "3 m" . +.\" XXX: negative values accepted; retain for future space-squeezing +. +.TPx +.REQ .ss n +Set minimal inter-word spacing to +.IR n \~12ths +of current font's space width. +. +.TPx +.REQ .ss "n m" +As +.RB \[lq] .ss\~\c +.IR n \[rq], +and set additional inter-sentence space to +.IR m \~12ths +of current font's space width. +. +.TPx +.REQ .stringdown stringvar +Replace each byte in the string named +.I stringvar +with its lowercase version. +. +.TPx +.REQ .stringup stringvar +Replace each byte in the string named +.I stringvar +with its uppercase version. +. +.TPx +.REQ .sty "n style" +Associate abstract +.I style +with font position +.IR n . +. +.TPx +.REQ .substring "str start \fR[\fPend\fR]\fP" +Replace the string named +.I str +with its substring bounded by the indices +.I start +and +.IR end , +inclusive. +. +Negative indices count backwards from the end of the string. +. +.TPx +.REQ .sv +As +.request .ne , +but save +.scalednumber "1 v" +for output with +.request .os +request. +. +.TPx +.REQ .sv d +As +.request .ne , +but save distance +.I d +for later output with +.request .os +request +(default scaling unit\~\c +.scaleindicator v ). +.\" XXX: negative values accepted; check AT&T troff +. +.TPx +.REQ .sy "command-line" +Execute +.I command-line +with +.MR system 3 . +. +Unsafe request; +disabled by default. +. +.TPx +.REQ .ta "n1 n2 \fR\&.\|.\|.\&\fP n\fRn\fP \f[CB]T\f[] r1 r2 \ +\fR\&.\|.\|.\&\fP r\fRn\fP" +Set tabs at positions +.IR n1 , +.IR n2 , +\&.\|.\|.\&, +.IR n n, +then set tabs at +.IR n n+ m \[tmu] r n+ r1 +through +.IR n n+ m \[tmu] r n+ r n, +where +.I m +increments from 0, +1, +2, +\&.\|.\|.\& to the output line length. +. +Each +.IR n \~argument +can be prefixed with +.RB a\~\[lq] + \[rq] +to place the tab stop +.I ni +at a distance relative to the previous, +.IR n ( i \-1). +. +Each argument +.IR ni \~or\~ ri +can be suffixed with a letter to align text within the tab column +bounded by tab stops +.IR i \~and\~ i +1; +.RB \[lq] L \[rq] +for left-aligned +(the default), +.RB \[lq] C \[rq] +for centered, +and +.RB \[lq] R \[rq] +for right-aligned. +. +.br +.ne 4v \" XXX: should need only 2v +.TPx +.REQ .tag +.TQ +.REQ .taga +Reserved for internal use. +. +.TPx +.REQ .tc +Unset tab repetition character. +. +.TPx +.REQ .tc "c" +Set tab repetition character +.RI to\~ c +(default: none). +. +.TPx +.REQ .ti "\[+-]N" +Temporarily indent next output line +(default scaling unit\~\c +.scaleindicator m ). +. +.TPx +.REQ .tkf "font s1 n1 s2 n2" +Enable track kerning for +.IR font . +. +.TPx +.REQ .tl "\f[CB]\[aq]\f[]left\f[CB]\[aq]\f[]center\f[CB]\[aq]\f[]right\ +\f[CB]\[aq]\f[]" +Format three-part title. +. +.TPx +.REQ .tm message +Write +.I message, +followed by a newline, +to the standard error stream. +. +.TPx +.REQ .tm1 message +As +.request .tm , +but an initial neutral double quote in +.I message +is removed, +allowing it to contain leading spaces. +. +.TPx +.REQ .tmc message +As +.request .tm1 , +without emitting a newline. +. +.TPx +.REQ .tr "abcd\fR\&.\|.\|.\&\fP" +Translate ordinary or special characters +.I a +to +.IR b , +.I c +to +.IR d , +and so on prior to output. +. +.TPx +.REQ .trf file +Transparently output the contents of +.I file. +. +Unlike +.request .cf , +invalid input characters in +.I file +are rejected. +. +.TPx +.REQ .trin "abcd\fR\&.\|.\|.\&\fP" +As +.request .tr , +except that +.request .asciify +ignores the translation when a diversion is interpolated. +. +.TPx +.REQ .trnt "abcd\fR\&.\|.\|.\&\fP" +As +.request .tr , +except that translations are suppressed in the argument to +.esc ! . +. +.TPx +.REQ .troff +Make the conditional expressions +.B t +true and +.B n +false. +. +.TPx +.REQ .uf font +Set underline font used by +.request .ul +to +.I font. +. +. +.TPx +.REQ .ul +Underline +(italicize in +.I troff +mode) +the output of the next productive input line. +. +. +.TPx +.REQ .ul npl +Underline +(italicize in +.I troff +mode) +the output of the next +.I npl +productive input line. +. +If +.IR npl =0, +stop underlining. +. +. +.TPx +.REQ .unformat "diversion" +Unformat space characters and tabs in +.IR diversion , +preserving font information. +. +. +.TPx +.REQ .vpt +Enable vertical position traps. +. +. +.TPx +.REQ .vpt\~0 +Disable vertical position traps. +. +. +.TPx +.REQ .vs +Change to previous vertical spacing. +. +.TPx +.REQ .vs "\[+-]N" +Set vertical spacing to +.I \[+-]N +(default scaling unit\~\c +.scaleindicator p ). +. +. +.TPx +.REQ .warn +Enable all warning categories. +. +. +.TPx +.REQ .warn\~0 +Disable all warning categories. +. +. +.TPx +.REQ .warn n +Enable warnings in categories whose codes sum +.RI to\~ n ; +.\" TODO: Move that table here, perhaps. +see +.MR @g@troff @MAN1EXT@ . +. +. +.TPx +.REQ .warnscale "su" +Set scaling unit used in certain warnings \" `output_warning()` +to +.I su +(one of +.BR u , +.BR i , +.BR c , +.BR p , +or +.BR P ; +default: +.BR i ). +. +. +.TPx +.REQ .wh vpos +Remove visible page location trap at +.I vpos +(default scaling unit\~\c +.scaleindicator v ). +. +. +.TPx +.REQ .wh "vpos name" +Plant macro +.I name +as page location trap at +.I vpos +(default scaling unit\~\c +.scaleindicator v ), +removing any visible trap already there. +. +. +.TPx +.REQ .while "cond-expr anything" +Repeatedly execute +.I anything +unless and until +.I cond-expr +evaluates false. +. +. +.TPx +.REQ .write "stream anything" +Write +.I anything +to the stream named +.IR stream . +. +.TPx +.REQ .writec "stream anything" +Similar to +.request .write +without emitting a final newline. +. +.TPx +.REQ .writem "stream xx" +Write contents of macro or string +.I xx +to the stream named +.IR stream . +. +.LE +. +. +.\" ==================================================================== +.SH "Escape sequence short reference" +.\" ==================================================================== +. +The escape sequences +.esc \[dq] , +.esc # , +.esc $ , +.esc * , +.esc ? , +.esc a , +.esc e , +.esc n , +.esc t , +.esc g , +.esc V , +and +.escarg \& newline +are interpreted even in copy mode. +. +. +.P +.LS +. +.\" ========= comments ========= +. +.TP +.ESC \[dq] +Comment. +. +Everything up to the end of the line is ignored. +. +. +.TP +.ESC # +Comment. +. +Everything up to and including the next newline is ignored. +. +. +.\" ========= strings ========= +. +.TP +.ESC * s +Interpolate string with one-character +.RI name\~ s . +. +. +.TP +.ESC *( st +Interpolate string with two-character +.RI name\~ st . +. +. +.TP +.ESC[] * string +Interpolate string with name +.I string +(of arbitrary length). +. +. +.TP +.ESC[] * "string arg \fR\&.\|.\|.\fP" +Interpolate string with name +.I string +(of arbitrary length), +taking +.I arg +\&.\|.\|.\& +as arguments. +. +. +.\" ========= macro arguments ========= +. +.TP +.ESC $0 +Interpolate name by which currently executing macro was invoked. +. +. +.TP +.ESC $ n +Interpolate macro or string parameter +.RI numbered\~ n +.RI (1\|\[<=]\| n \|\[<=]\|9). +. +. +.TP +.ESC $( nn +Interpolate macro or string parameter +.RI numbered\~ nn +.RI (01\|\[<=]\| nn \|\[<=]\|99). +. +.TP +.ESC[] $ nnn +Interpolate macro or string parameter +.RI numbered\~ nnn +.RI ( nnn \|\[>=]\|1). +. +. +.TP +.ESC $* +Interpolate concatenation of all macro or string parameters, +separated by spaces. +. +. +.TP +.ESC $@ +Interpolate concatenation of all macro or string parameters, +with each surrounded by double quotes and separated by spaces. +. +. +.TP +.ESC $\[ha] +Interpolate concatenation of all macro or string parameters +as if they were arguments to the +.request .ds +request. +. +. +.\" ========= escaped characters ========= +. +. +.TP +.ESC \[aq] +is a synonym for +.esc [aa] , +the acute accent special character. +. +. +.TP +.ESC \[ga] +is a synonym for +.esc [ga] , +the grave accent special character. +. +. +.TP +.ESC \- +is a synonym for +.esc [\-] , +the minus sign special character. +. +. +.TP +.ESC _ +is a synonym for +.esc [ul] , +the underrule special character. +. +. +.TP +.ESC % +Control hyphenation. +. +. +.TP +.ESC ! +Transparent line. +. +The remainder of the input line is interpreted +(1) when the current diversion is read; +or +(2) if in the top-level diversion, +by the postprocessor +(if any). +. +. +.TP +.ESC? anything +Transparently embed +.IR anything , +read in copy mode, +in a diversion, +or unformatted as an output comparand in a conditional expression. +. +. +.\" ========= spaces and fixed-width horizontal motions ========= +. +.TP +.ESC \f[I]space +Move right one word space. +. +. +.TP +.ESC \[ti] +Insert an unbreakable, +adjustable space. +. +. +.TP +.ESC 0 +Move right by the width of a numeral in the current font. +. +. +.TP +.ESC | +Move one-sixth em to the right on typesetters. +. +. +.TP +.ESC \[ha] +Move one-twelfth em to the right on typesetters. +. +. +.TP +.ESC & +Interpolate a dummy character. +. +. +.TP +.ESC ) +Interpolate a dummy character that is transparent to end-of-sentence +recognition. +. +. +.TP +.ESC / +Apply italic correction. +. +Use between an immediately adjacent oblique glyph on the left and an +upright glyph on the right. +. +. +.TP +.ESC , +Apply left italic correction. +. +Use between an immediately adjacent upright glyph on the left and an +oblique glyph on the right. +. +. +.TP +.ESC : +Non-printing break point +(similar to +.esc % , +but never produces a hyphen glyph). +. +. +.TP +.ESC "" newline +Continue current input line on the next. +. +. +.\" ========= structuring ========= +. +.TP +.ESC { +Begin conditional input. +. +.TP +.ESC } +End conditional input. +. +.\" ========= longer escape names ========= +. +.TP +.ESC ( gl +Interpolate glyph with two-character name +.IR gl . +. +. +.TP +.ESC[] "" glyph +Interpolate glyph with name +.I glyph +(of arbitrary length). +. +. +.TP +.ESC[] "" "base-char comp \fR\&.\|.\|." +Interpolate composite glyph constructed from +.I base-char +and each component +.IR comp . +. +. +.TP +.ESC[] "" "\f[CB]char\f[]nnn" +Interpolate glyph of eight-bit encoded character +.IR nnn , +where +.RI 0\|\[<=]\| nnn \|\[<=]\|255. +. +. +.TP +.ESC[] "" "\f[CB]u\f[]nnnn\f[R][\f[]n\f[R][\f[]n\f[R]]]" +Interpolate glyph of Unicode character with code point +.IR nnnn [ n [ n ]] +in uppercase hexadecimal. +. +. +.TP +.ESC[] "" "\f[CB]u\f[]base-char\f[R][\f[]\f[CB]_\f[]\ +combining-component\f[R]].\|.\|." +Interpolate composite glyph from Unicode character +.I base-char +and +.IR combining-components . +. +. +.\" ========= alphabetical escape sequences ========= +. +.TP +.ESC a +Interpolate a leader in copy mode. +. +.TP +.ESCq A anything +Interpolate 1 if +.I anything +is a valid identifier, +and\~0 otherwise. +. +.TP +.ESCq b string +Build bracket: +pile a sequence of glyphs corresponding to each character in +.I string +vertically, +and center it vertically on the output line. +. +.TP +.ESCq B anything +Interpolate 1 if +.I anything +is a valid numeric expression, +and\~0 otherwise. +. +. +.TP +.ESC c +Continue output line at next input line. +. +. +.TP +.ESCq C glyph +As +.esc[] "" glyph , +but compatible with other +.I troff \" generic +implementations. +. +. +.TP +.ESC d +Move downward \[12]\~em on typesetters. +.\" XXX: No current groff nroff-mode output driver supports half-line +.\" motions. +.\" (\[12]\~line in +.\" .I nroff +.\" contingent on device support). +. +. +.TP +.ESCq D drawing-command +See subsection \[lq]Drawing commands\[rq] below. +. +. +.TP +.ESC e +Interpolate the escape character. +. +. +.TP +.ESC E +As +.esc e , +but not interpreted in copy mode. +. +.TP +.ESC fP +Select previous font mounting position +(abstract style or font); +same as +.RB \[lq] .ft \[rq] +or +.RB \[lq] .ft\~P \[rq]. +. +.TP +.ESC f F +Select font mounting position, +abstract style, +or font with one-character name or one-digit +.RI position\~ F . +. +.IR F \~cannot +be +.BR P . +. +.TP +.ESC f( ft +Select font mounting position, +abstract style, +or font with two-character name or two-digit +.RI position\~ ft . +. +.TP +.ESC[] f font +Select font mounting position, +abstract style, +or font with arbitrarily long name or position +.IR font . +. +.I font +cannot be +.BR P . +. +.TP +.ESC[] f "" +Select previous font mounting position +(abstract style or font). +. +.TP +.ESC F f +Set default font family to that with one-character +.RI name\~ f . +. +.TP +.ESC F( fm +Set default font family to that with two-character +.RI name\~ fm . +. +.TP +.ESC[] F fam +Set default font family to that with arbitrarily long name +.IR fam . +. +.TP +.ESC[] F "" +Set default font family to previous value. +. +.TP +.ESC g r +Interpolate format of register with one-character +.RI name\~ r . +. +. +.TP +.ESC g( rg +Interpolate format of register with two-character +.RI name\~ rg . +. +. +.TP +.ESC[] g reg +Interpolate format of register with arbitrarily long name +.IR reg . +. +. +.TP +.ESCq h N +Horizontally move the drawing position by +.IR N \~ems +(or specified units); +.B \[or] +may be used. +. +Positive motion is rightward. +. +. +.TP +.ESCq H N +Set height of current font to +.IR N \~scaled +points +(or specified units). +. +. +.TP +.ESC k r +Mark horizontal position in one-character register +.RI name\~ r . +. +.TP +.ESC k( rg +Mark horizontal position in two-character register +.RI name\~ rg . +. +. +.TP +.ESC[] k reg +Mark horizontal position in register with arbitrarily long +.RI name\~ reg . +. +. +.TP +.ESCq l N\/\f[R][\f[]c\f[R]] +Draw horizontal line of length +.I N +with character +.B c +(default: +.BR \[rs][ru] ; +default scaling unit\~\c +.scaleindicator m ). +. +. +. +.TP +.ESCq L N\/\f[R][\f[]c\f[R]] +Draw vertical line of length +.I N +with character +.B c +(default: +.BR \[rs][br] ; +default scaling unit\~\c +.scaleindicator v ). +. +. +.TP +.ESC m c +Set stroke color to that with one-character +.RI name\~ c . +. +. +.TP +.ESC m( cl +Set stroke color to that with two-character +.RI name\~ cl . +. +. +.TP +.ESC[] m color +Set stroke color to that with arbitrarily long +.RI name\~ color . +. +. +.TP +.ESC[] m "" +Restore previous stroke color. +. +. +.TP +.ESC M c +Set fill color to that with one-character +.RI name\~ c . +. +. +.TP +.ESC M( cl +Set fill color to that with two-character +.RI name\~ cl . +. +. +.TP +.ESC[] M color +Set fill color to that with arbitrarily long +.RI name\~ color . +. +. +.TP +.ESC[] M "" +Restore previous fill color. +. +. +.br +.ne 4v \" XXX: why not 3v? +.TP +.ESC n r +Interpolate contents of register with one-character +.RI name\~ r . +. +. +.TP +.ESC n( rg +Interpolate contents of register with two-character +.RI name\~ rg . +. +. +.TP +.ESC[] n reg +Interpolate contents of register with arbitrarily long +.RI name\~ reg . +. +. +.TP +.ESCq N n +Interpolate glyph with +.RI index\~ n +in the current font. +. +.TP +.ESCq o abc\f[R].\|.\|.\f[] +Overstrike centered glyphs of characters +.IR a , +.IR b , +.IR c , +and so on. +. +.TP +.ESC O0 +At the outermost suppression level, +disable emission of glyphs and geometric objects to the output +driver. +. +. +.TP +.ESC O1 +At the outermost suppression level, +enable emission of glyphs and geometric objects to the output driver. +. +. +.TP +.ESC O2 +At the outermost suppression level, +enable glyph and geometric primitive emission to the output driver and +write to the standard error stream the page number, +four bounding box registers enclosing glyphs written since the previous +.B \[rs]O +escape sequence, +the page offset, +line length, +image file name +(if any), +horizontal and vertical device motion quanta, +and input file name. +. +. +.TP +.ESC O3 +Begin a nested suppression level. +. +. +.TP +.ESC O4 +End a nested suppression level. +. +. +.TP +.ESC[] O "\f[CB]5\f[]Pfile" +At the outermost suppression level, +write the name +.I file +to the standard error stream at +.RI position\~ P , +which must be one of +.BR l , +.BR r , +.BR c , +or +.BR i . +. +. +.TP +.ESC p +Break output line at next word boundary; +adjust if applicable. +. +. +.TP +.ESC r +Move \[lq]in reverse\[rq] (upward) 1\~em. +. +. +.TP +.ESCq R "name\~\[+-]N" +Set, +increment, +or decrement register +.I name +.RI by\~ N . +. +. +.TP +.ESC s \[+-]N +Set/increase/decrease the type size to/by +.I N +scaled points. +. +.I N +must be a single digit; +0 restores the previous type size. +. +(In compatibility mode only, +a non-zero +.I N +must be in the range 4\[en]39.) +. +Otherwise, +as +.request .ps +request. +. +. +.TP +.ESC s( \[+-]N +.TQ +.fam C +.BI \es \[+-] ( N +.fam +Set/increase/decrease the type size to/by +.I N +scaled points; +.I N +is a two-digit number \[>=]1. +. +As +.request .ps +request. +. +. +.TP +.ESC[] s \[+-]N +.TQ +.fam C +.BI \es \[+-] [ N ] +.fam +.TQ +.ESCq s \[+-]N +.TQ +.fam C +.BI \es \[+-] \[aq] N \[aq] +.fam +Set/increase/decrease the type size to/by +.I N +scaled points. +. +As +.request .ps +request. +. +. +.TP +.ESCq S N +Slant output glyphs by +.I N +degrees; +the direction of text flow is positive. +. +. +.TP +.ESC t +Interpolate a tab in copy mode. +. +. +.TP +.ESC u +Move upward \[12]\~em on typesetters. +.\" XXX: No current groff nroff-mode output driver supports half-line +.\" motions. +.\" (\[12]\~line in +.\" .I nroff +.\" contingent on device support). +. +. +.TP +.ESCq v N +Vertically move the drawing position by +.IR N \~vees +(or specified units); +.B \[or] +may be used. +. +Positive motion is downward. +. +. +.TP +.ESC V e +Interpolate contents of environment variable with one-character +.RI name\~ e . +. +. +.TP +.ESC V( ev +Interpolate contents of environment variable with two-character +.RI name\~ ev . +. +. +.TP +.ESC[] V env +Interpolate contents of environment variable with arbitrarily long +.RI name\~ env . +. +. +.TP +.ESCq w anything +Interpolate width of +.IR anything , +formatted in a dummy environment. +. +. +.TP +.ESCq x N +Increase vertical spacing of pending output line by +.IR N \~vees +(or specified units; +negative before, +positive after). +. +.TP +.ESCq X anything +Write +.I anything +to +.I @g@troff +output as a device control command. +. +Within +.IR anything , +the escape sequences +.BR \[rs]& , +.BR \[rs]) , +.BR \[rs]% , +and +.B \[rs]: +are ignored; +.BI \[rs] space +and +.B \[rs]\[ti] +are converted to single space characters; +and +.B \[rs]\[rs] +has its escape character stripped. +. +So that the basic Latin subset of the Unicode character +set can be reliably encoded in +.I anything, +the special character escape sequences +.BR \[rs]\- , +.BR \[rs][aq] , +.BR \[rs][dq] , +.BR \[rs][ga] , +.BR \[rs][ha] , +.BR \[rs][rs] , +and +.B \[rs][ti] +are mapped to basic Latin characters; +see +.MR groff_char @MAN7EXT@ . +. +For this transformation, +character translations and special character definitions are ignored. +. +.TP +.ESC Y n +Write contents of macro or string +.I n +to +.I @g@troff +output as a device control command. +. +.TP +.ESC Y( nm +Write contents of macro or string +.I nm +to +.I @g@troff +output as a device control command. +. +.TP +.ESC[] Y name +Write contents of macro or string +.I name +to +.I @g@troff +output as a device control command. +. +.TP +.ESC z c +Format character +.I c +with zero width\[em]without advancing the drawing position. +. +.TP +.ESCq Z anything +Save the drawing position, +format +.IR anything , +then restore it. +.LE +. +. +.\" ==================================================================== +.SS "Drawing commands" +.\" ==================================================================== +. +.\" BEGIN Keep (roughly) parallel with groff.texi node "Drawing +.\" commands". +Drawing commands direct the output device to render geometrical objects +rather than glyphs. +. +Specific devices may support only a subset, +or may feature additional ones; +consult the man page for the output driver in use. +. +Terminal devices in particular implement almost none. +. +. +.P +Rendering starts at the drawing position; +when finished, +the drawing position is left at the rightmost point of the object, +even for closed figures, +except where noted. +. +GNU +.I troff \" GNU +draws stroked (outlined) objects with the stroke color, +and shades filled ones with the fill color. +. +See section \[lq]Colors\[rq] above. +. +Coordinates +.I h +and +.I v +are horizontal and vertical motions relative to the drawing position +or previous point in the command. +. +The default scaling unit for horizontal measurements +(and diameters of circles) +.RB is\~ m ; +for vertical ones, +.BR v . +. +. +.P +Circles, +ellipses, +and polygons can be drawn stroked or filled. +. +These are independent properties; +if you want a filled, +stroked figure, +you must draw the same figure twice using each drawing command. +. +A filled figure is always smaller than an outlined one because the +former is drawn only within its defined area, +whereas strokes have a line thickness +(set with +.BR \[rs]D\[aq]t\[aq] ). +. +. +.P +.LS +.TP +.BI \[rs]D\[aq]\[ti]\~ "h1 v1"\~\c +.RI .\|.\|.\~ "hn vn"\c +.B \[aq] +Draw B-spline to each point in sequence, +leaving drawing position at +.RI ( hn ,\~ vn ). +. +.\" XXX: This is one case where a valid coordinate pair could be off the +.\" page (even negative) and we need to discuss this frankly. +.TP +.BI \[rs]D\[aq]a\~ "hc vc h v" \[aq] +Draw circular arc centered at +.RI ( hc ,\~ vc ) +counterclockwise from the drawing position to a point +.RI ( h ,\~ v ) +relative to the center. +. +.RI ( hc ,\~ vc ) +is adjusted to the point nearest the perpendicular bisector of the arc's +chord. +. +.TP +.BI \[rs]D\[aq]c\~ "d" \[aq] +Draw circle of diameter +.I d +with its leftmost point at the drawing position. +. +.TP +.BI \[rs]D\[aq]C\~ "d" \[aq] +As +.BR \[rs]D\[aq]C\[aq] , +but the circle is filled. +. +.TP +.BI \[rs]D\[aq]e\~ "h v" \[aq] +Draw ellipse of width +.I h +and height +.I v +with its leftmost point at the drawing position. +. +.\" How do we draw an ellipse with rotated axes? +.TP +.BI \[rs]D\[aq]E\~ "h v" \[aq] +As +.BR \[rs]D\[aq]e\[aq] , +but the ellipse is filled. +. +.\" XXX: Df and dF are taken care of by \M and .defcolor. +.TP +.BI \[rs]D\[aq]l\~ "h v" \[aq] +Draw line from the drawing position to +.RI ( h ,\~ v ). +. +.TP +.BI \[rs]D\[aq]p\~ "h1 v1"\~\c +.RI .\|.\|.\~ "hn vn"\c +.B \[aq] +Draw polygon with vertices at drawing position and each point +in sequence. +. +GNU +.I troff \" GNU +closes the polygon by drawing a line from +.RI ( hn ,\~ vn ) +back to the initial drawing position. +. +.\" XXX: This would be the "STUPID_DRAWING_POSITIONING" complained of in +.\" src/libs/libdriver/input.cpp. It is neither the rightmost point +.\" of the figure nor the initial drawing position that GNU troff +.\" automatically returned to to close the figure. +Afterward, +the drawing position is left at +.RI ( hn ,\~ vn ). +. +.TP +.BI \[rs]D\[aq]P\~ "h1 v1"\~\c +.RI .\|.\|.\~ "hn vn"\c +.B \[aq] +As +.BR \[rs]D\[aq]p\[aq] , +but the polygon is filled. +. +.TP +.BI \[rs]D\[aq]t\~ "n" \[aq] +Set stroke thickness of geometric objects to +.RI to\~ n +basic units. +. +A zero +.I n +selects the minimal supported thickness. +. +A negative +.I n +selects a thickness proportional to the type size; +this is the default. +.LE +.\" END Keep (roughly) parallel with groff.texi node "Drawing +.\" commands". +. +. +.\" ==================================================================== +.SS "Device control commands" +.\" ==================================================================== +. +The +.B .device +and +.B .devicem +requests, +and +.B \[rs]X +and +.B \[rs]Y +escape sequences, +enable documents to pass information directly to a postprocessor. +. +These are useful for +exercising device-specific capabilities that the +.I groff +language does not abstract or generalize; +such functions include the embedding of hyperlinks and image files. +. +Device-specific functions are documented in +each output driver's man page. +. +. +.\" ==================================================================== +.SH Strings +.\" ==================================================================== +. +.\" BEGIN Keep (roughly) parallel with groff.texi node "Strings". +.I groff +supports strings primarily for user convenience. +. +Conventionally, +if one would define a macro only to interpolate a small amount of text, +without invoking requests or calling any other macros, +one defines a string instead. +. +Only one string is predefined by the language. +. +. +.TPx +.STRING .T +Contains the name of the output device +(for example, +.RB \[lq] utf8 \[rq] +or +.RB \[lq] pdf \[rq] ). +. +. +.P +The +.request .ds +request creates a string with a specified name and contents. +. +If the identifier named by +.request .ds +already exists as an alias, +the target of the alias is redefined. +. +If +.request .ds +is called with only one argument, +the named string becomes empty. +. +Otherwise, +.I @g@troff +stores the remainder of the control line in copy mode; +see subsection \[lq]Copy mode\[rq] below. +. +. +.P +The +.esc * +escape sequence dereferences a string's name, +interpolating its contents. +. +If the name does not exist, +it is defined as empty, +nothing is interpolated, +and a warning in category +.RB \%\[lq] mac \[rq] +is emitted. +. +See section \[lq]Warnings\[rq] in +.MR @g@troff 1 . +. +The bracketed interpolation form accepts arguments that are handled as +macro arguments are; +see section \[lq]Calling macros\[rq] above. +. +In contrast to macro calls, +however, +if a closing bracket +.B ] +occurs in a string argument, +that argument must be enclosed in double quotes. +. +.B \[rs]* +is interpreted even in copy mode. +. +When defining strings, +argument interpolations must be escaped if they are to reference +parameters from the calling context; +see section \[lq]Parameters\[rq] below. +. +. +.P +An initial neutral double quote +.B \[dq] +in the string contents is stripped to allow embedding of leading spaces. +. +Any other +.B \[dq] +is interpreted literally, +but it is wise to use the special character escape sequence +.B \[rs][dq] +instead if the string might be interpolated as part of a macro argument; +see section \[lq]Calling macros\[rq] above. +. +Strings are not limited to a single input line of text. +.BI \[rs] newline +works just as it does elsewhere. +. +The resulting string is stored +.I without +the newlines. +. +Care is therefore required when interpolating strings while filling is +disabled. +. +It is not possible to embed a newline in a string that will be +interpreted as such when the string is interpolated. +. +To achieve that effect, +use +.B \[rs]* +to interpolate a macro instead.\" see @ref{Punning Names}. +. +. +.P +The +.request .as +request is similar to +.request .ds +but appends to a string instead of redefining it. +. +If +.request .as +is called with only one argument, +no operation is performed +(beyond dereferencing the string). +. +. +.P +Because strings are similar to macros, +they too can be defined to suppress AT&T +.I troff \" AT&T +compatibility mode enablement when interpolated; +see section \[lq]Compatibility mode\[rq] below. +. +The +.request .ds1 +request defines a string that suspends compatibility mode when the +string is later interpolated. +. +.request .as1 +is likewise similar to +.BR .as , +with compatibility mode suspended when the appended portion of the +string is later interpolated. +. +. +.P +.B Caution: +Unlike other requests, +the second argument to these requests consumes the remainder of the +input line, +including trailing spaces. +. +Ending string definitions +(and appendments) +with a comment, +even an empty one, +prevents unwanted space from creeping into them during source document +maintenance. +. +. +.br +.ne 3v +.P +Several requests exist to perform rudimentary string operations. +. +Strings can be queried +(\c +.request .length ) +and modified +(\c +.request .chop , +.request .substring , +.request .stringup , +.request .stringdown ), +and their names can be manipulated through renaming, +removal, +and aliasing +(\c +.request .rn , +.request .rm , +.request .als). +. +. +.P +When a request, +macro, +string, +or diversion is aliased, +redefinitions and appendments \[lq]write through\[rq] alias names. +. +To replace an alias with a separately defined object, +you must use the +.B rm +request on its name first. +.\" END Keep (roughly) parallel with groff.texi node "Strings". +. +. +.\" ==================================================================== +.SH Registers +.\" ==================================================================== +. +.\" BEGIN Keep (roughly) parallel with groff.texi node "Registers". +In the +.I roff +language, +numbers can be stored in +.I registers. +. +Many built-in registers exist, +supplying anything from the date to details of formatting parameters. +. +You can also define your own. +. +See section \[lq]Identifiers\[rq] above for information on constructing +a valid name for a register. +. +. +.P +Define registers and update their values with the +.B nr +request or the +.B \[rs]R +escape sequence. +. +. +.P +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 +.request .nr +request, +and a special interpolation syntax, +.BI \[rs]n \[+-] +is used to alter and then retrieve +the register's value. +. +Together, +these features are called +.IR auto-increment . +. +(A negative auto-increment can be +considered an \[lq]auto-decrement\[rq].) +. +. +.P +Many predefined registers are available. +. +In the following presentation, +the register interpolation syntax +.BI \[rs]n[ name ] +is used to refer to a register +.I name +to clearly distinguish it from a string or request +.IR name . +. +The register name space is separate from that used for requests, +macros, +strings, +and diversions. +. +Bear in mind that the symbols +.B \[rs]n[] +are +.I not +part of the register name. +.\" END Keep (roughly) parallel with groff.texi node "Registers". +. +. +.\" ==================================================================== +.SS "Read-only registers" +.\" ==================================================================== +. +Predefined registers whose identifiers start with a dot are read-only. +. +Many are Boolean-valued. +. +Some are string-valued, +meaning that they interpolate text. +. +A register name +(without the dot) +is often associated with a request of the same name; +exceptions are noted. +. +. +.P +.LS +. +.TP 15n +.REG .$ +Count of arguments passed to currently interpolated macro or string. +. +.TP +.REG .a +Amount of extra post-vertical line space; +see +.esc x . +. +.TP +.REG .A +Approximate output is being formatted (Boolean-valued); +see +.I @g@troff +.B \-a +option. +. +.TP +.REG .b +Font emboldening offset; +see +.request .bd . +. +.TP +.REG .br +The normal control character was used to call the currently interpolated +macro (Boolean-valued). +. +.TP +.REG .c +Input line number; +see +.request .lf +and +.register \f[R]\[lq]\f[]c.\f[R]\[rq]\f[] . +. +.TP +.REG .C +Compatibility mode is enabled (Boolean-valued); +see +.request .cp . +. +Always false when processing +.request .do ; +see +.register .cp . +. +.TP +.REG .cdp +Depth of last glyph formatted in the environment; +.\" TODO: Give page a discussion of glyph properties and move this. +positive if glyph extends below the baseline. +. +.TP +.REG .ce +Count of output lines remaining to be centered. +. +.TP +.REG .cht +Height of last glyph formatted in the environment; +.\" TODO: Give page a discussion of glyph properties and move this. +positive if glyph extends above the baseline. +. +.TP +.REG .color +Color output is enabled (Boolean-valued). +. +.TP +.REG .cp +Within +.request .do , +the saved value of compatibility mode; +see +.register .C . +. +.TP +.REG .csk +Skew of the last glyph formatted in the environment; +.\" TODO: Give page a discussion of glyph properties and move this. +skew is how far to the right of the center of a glyph the center of an +accent over that glyph should be placed. +. +.TP +.REG .d +Vertical drawing position in diversion. +. +.TP +.REG .ev +Name of environment (string-valued). +. +.TP +.REG .f +Mounting position of selected font; +see +.request .ft +and +.esc f . +. +.TP +.REG .F +Name of input file (string-valued); +see +.request .lf . +. +.TP +.REG .fam +Name of default font family (string-valued). +. +.TP +.REG .fn +Resolved name of selected font (string-valued); +see +.request .ft +and +.esc f . +. +.TP +.REG .fp +Next non-zero free font mounting position index. +. +.TP +.REG .g +Always true in GNU +.I troff \" GNU +(Boolean-valued). +. +.TP +.REG .h +Text baseline high-water mark on page or in diversion. +. +.TP +.REG .H +Horizontal motion quantum of output device in basic units. +. +.TP +.REG .height +Font height; +see +.esc H . +. +.TP +.REG .hla +Hyphenation language in environment (string-valued). +. +.TP +.REG .hlc +Count of immediately preceding consecutive hyphenated lines in +environment. +. +.TP +.REG .hlm +Maximum quantity of consecutive hyphenated lines allowed in environment. +. +.TP +.REG .hy +Automatic hyphenation mode in environment. +. +.TP +.REG .hym +Hyphenation margin in environment. +. +.TP +.REG .hys +Hyphenation space adjustment threshold in environment. +. +.TP +.REG .i +Indentation amount; +see +.request .in . +. +.TP +.REG .in +Indentation amount applicable to the pending output line; +see +.request .ti . +. +.TP +.REG .int +Previous output line was \[lq]interrupted\[rq] or continued with +.esc c +(Boolean-valued). +. +.TP +.REG .j +Adjustment mode encoded as an integer; +see +.request .ad +and +.request .na . +. +Do not interpret or perform arithmetic on its value. +. +.TP +.REG .k +Horizontal drawing position relative to indentation. +. +.TP +.REG .kern +Pairwise kerning is enabled (Boolean-valued). +. +.TP +.REG .l +Line length; +see +.request .ll . +. +.TP +.REG .L +Line spacing; +see +.request .ls . +. +.TP +.REG .lg +Ligature mode. +. +.TP +.REG .linetabs +Line-tabs mode is enabled (Boolean-valued). +. +.TP +.REG .ll +Line length applicable to the pending output line. +. +.TP +.REG .lt +Title length. +. +.TP +.REG .m +Stroke color (string-valued); +see +.request .gcolor +and +.esc m . +. +Empty if the stroke color is the default. +. +.TP +.REG .M +Fill color (string-valued); +see +.request .fcolor +and +.esc M . +. +Empty if the fill color is the default. +. +.TP +.REG .n +Length of formatted output on previous output line. +. +.TP +.REG .ne +Amount of vertical space required by last +.request .ne +that caused a trap to be sprung; +also see +.register .trunc . +. +.TP +.REG .nm +Output line numbering is enabled (Boolean-valued). +. +.TP +.REG .nn +Count of output lines remaining to have numbering suppressed. +. +.TP +.REG .ns +No-space mode is enabled (Boolean-valued). +. +.TP +.REG .o +Page offset; +see +.request .po . +. +.TP +.REG .O +Output suppression nesting level; +see +.esc O . +. +.TP +.REG .p +Page length; +see +.request .pl . +. +.TP +.REG .P +The page is selected for output (Boolean-valued); +see +.I @g@troff +.B \-o +option. +. +.TP +.REG .pe +Page ejection is in progress (Boolean-valued). +. +.TP +.REG .pn +Number of the next page. +. +.TP +.REG .ps +Type size in scaled points. +. +.TP +.REG .psr +Most recently requested type size in scaled points; +see +.request .ps +and +.esc s . +. +.TP +.REG .pvs +Post-vertical line spacing. +. +.TP +.REG .R +Count of available unused registers; +always 10,000 in GNU +.IR troff . \" GNU +. +.TP +.REG .rj +Count of lines remaining to be right-aligned. +. +.TP +.REG .s +Type size in points as a decimal fraction (string-valued); +see +.request .ps +and +.esc s . +. +.TP +.REG .slant +Slant of font in degrees; +see +.esc S . +. +.TP +.REG .sr +Most recently requested type size in points as a decimal fraction +(string-valued); +see +.request .ps +and +.esc s . +. +.TP +.REG .ss +Size of minimal inter-word space in twelfths of the space width of the +selected font. +. +.TP +.REG .sss +Size of additional inter-sentence space in twelfths of the space width +of the selected font. +. +.TP +.REG .sty +Selected abstract style (string-valued); +see +.request .ft +and +.esc f . +. +.TP +.REG .t +Distance to next vertical position trap; +see +.request .wh +and +.request .ch . +. +.TP +.REG .T +An output device was explicitly selected (Boolean-valued); +see +.I @g@troff +.B \-T +option. +. +.TP +.REG .tabs +Representation of tab settings suitable for use as argument to +.request .ta +(string-valued). +. +.TP +.REG .trunc +Amount of vertical space truncated by the most recently sprung +vertical position trap, +or, +if the trap was sprung by an +.request .ne , +minus the amount of vertical motion produced by +.request .ne ; +also see +.register .ne . +. +.TP +.REG .u +Filling is enabled (Boolean-valued); +see +.request .fi +and +.request .nf . +. +.TP +.REG .U +Unsafe mode is enabled (Boolean-valued); +see +.I @g@troff +.B \-U +option. +. +.TP +.REG .v +Vertical line spacing; +see +.request .vs . +. +.TP +.REG .V +Vertical motion quantum of the output device in basic units. +. +.TP +.REG .vpt +Vertical position traps are enabled (Boolean-valued). +. +.TP +.REG .w +Width of previous glyph formatted in the environment. +. +.TP +.REG .warn +Sum of the numeric codes of enabled warning categories. +. +.TP +.REG .x +Major version number of the running +.I @g@troff +formatter. +. +.TP +.REG .y +Minor version number of the running +.I @g@troff +formatter. +. +.TP +.REG .Y +Revision number of the running +.I @g@troff +formatter. +. +.TP +.REG .z +Name of diversion (string-valued). +. +Empty if output is directed to the top-level diversion. +. +.TP +.REG .zoom +Zoom multiplier of current font +(in thousandths; +zero if no magnification); +see +.request .fzoom . +.LE +. +. +.\" ==================================================================== +.SS "Writable predefined registers" +.\" ==================================================================== +. +Several registers are predefined but also modifiable; +some are updated upon interpretation of certain requests or escape +sequences. +. +Date- and time-related registers are set to the local time as determined +by +.MR localtime 3 +when the formatter launches. +. +This initialization can be overridden by +.I \%SOURCE_DATE_EPOCH +and +.IR TZ ; +see section \[lq]Environment\[rq] of +.MR groff @MAN1EXT@ . +. +. +.P +.LS +. +.TP 15n +.REG $$ +Process ID of +.IR @g@troff . +. +.TP +.REG % +Page number. +. +.TP +.REG c. +Input line number. +. +.TP +.REG ct +Union of character types of each glyph rendered into dummy environment +by +.esc w . +. +.TP +.REG dl +Width of last closed diversion. +. +.TP +.REG dn +Height of last closed diversion. +. +.TP +.REG dw +Day of the week (1\[en]7; +1 is Sunday). +. +.TP +.REG dy +Day of the month (1\[en]31). +. +.TP +.REG hours +Count of hours elapsed since midnight (0\[en]23). +. +.TP +.REG hp +Horizontal drawing position relative to start of input line. +. +.TP +.REG llx +Lower-left +.I x +coordinate +(in PostScript units) +of PostScript image; +see +.request .psbb . +. +.TP +.REG lly +Lower-left +.I y +coordinate +(in PostScript units) +of PostScript image; +see +.request .psbb . +. +.TP +.REG ln +Output line number; +see +.request .nm . +. +.TP +.REG lsn +Count of leading spaces on input line. +. +.TP +.REG lss +Amount of horizontal space corresponding to leading spaces on input +line. +. +.TP +.REG minutes +Count of minutes elapsed in the hour (0\[en]59). +. +.TP +.REG mo +Month of the year (1\[en]12). +. +.TP +.REG nl +Vertical drawing position. +. +.TP +.REG opmaxx +.TP +.REG opmaxy +.TP +.REG opminx +.TP +.REG opminy +These four registers mark the top left- and bottom right-hand corners of +a rectangle encompassing all formatted output on the page. +. +They are reset to \-1 by +.B \[rs]O0 +or +.BR \[rs]O1 . +. +.TP +.REG rsb +As +.register sb , +adding maximum glyph height to measurement. +. +.TP +.REG rst +As +.register st , +adding maximum glyph depth to measurement. +. +.TP +.REG sb +Maximum displacement of text baseline below its original position +after rendering into dummy environment by +.esc w . +. +.TP +.REG seconds +Count of seconds elapsed in the minute (0\[en]60). \" not 59; see POSIX +. +.TP +.REG skw +Skew of last glyph rendered into dummy environment by +.esc w . +. +.TP +.REG slimit +The maximum depth of +.IR @g@troff 's +internal input stack. +. +If \[<=]0, +there is no limit: +recursion can continue until available memory is exhausted. +. +The default is 1,000. +. +.TP +.REG ssc +Subscript correction of last glyph rendered into dummy environment by +.esc w . +. +.TP +.REG st +Maximum displacement of text baseline above its original position +after rendering into dummy environment by +.esc w . +. +.TP +.REG systat +Return value of +.I system() +function; see +.request .sy . +. +.TP +.REG urx +Upper-right +.I x +coordinate +(in PostScript units) +of PostScript image; +see +.request .psbb . +. +.TP +.REG ury +Upper-right +.I y +coordinate +(in PostScript units) +of PostScript image; +see +.request .psbb . +. +.TP +.REG year +Gregorian year. +. +.TP +.REG yr +Gregorian year minus 1900. +.LE +. +. +.\" ==================================================================== +.SH "Using fonts" +.\" ==================================================================== +. +.\" BEGIN Keep (roughly) parallel with groff.texi node "Using Fonts". +In digital typography, +a +.I font +is a collection of characters in a specific typeface that a device can +render as glyphs at a desired size. +. +(Terminals and some output devices have fonts that render at only one or +two sizes. +. +As examples of the latter, +take the +.I groff +.B lj4 +device's +Lineprinter, +and +.BR lbp 's +Courier and Elite faces.) +. +. +A +.I roff +formatter can change typefaces at any point in the text. +. +The basic faces are a set of +.I styles +combining upright and slanted shapes with normal and heavy stroke +weights: +.RB \[lq] R \[rq], +.RB \[lq] I \[rq], +.RB \[lq] B \[rq], +and +.RB \[lq] BI \[rq]\[em]\c +these stand for +.I roman, +.I bold, +.I italic, +and +.I bold-italic. +. +For linguistic text, +GNU +.I troff \" GNU +groups typefaces into +.I families +containing each of these styles. +. +(Font designers prepare families such that the styles share esthetic +properties.) +. +A +.I "text font" +is thus often a family combined with a style, +but it need not be: +consider the +.B ps +and +.B pdf +devices' +.B ZCMI +(Zapf Chancery Medium italic)\[em]\c +often, +no other style of Zapf Chancery Medium is provided. +. +On typesetting devices, +at least one +.I "special font" +is available, +comprising +.I unstyled +glyphs for mathematical operators and other purposes. +. +. +.P +Like AT&T +.I troff, \" AT&T +GNU +.I troff \" GNU +does not itself load or manipulate a digital font file; +.\" @footnote{Historically, the fonts @code{troff}s dealt with were not +.\" Free Software or, as with the Graphic Systems C/A/T, did not even +.\" exist in the digital domain.} +instead it +works with a +.I font description file +that characterizes it, +including its glyph repertoire and the +.I metrics +(dimensions) of each glyph. +. +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 +.I "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 +.I troff \" GNU +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 +.I "resolved font name." +. +. +.P +Fonts often have trademarked names, +and even Free Software fonts can require renaming upon modification. +. +.I groff +maintains a convention that a device's serif font family is given the +name +.B T +(\[lq]Times\[rq]), +its sans-serif family +.B H +(\[lq]Helvetica\[rq]), +and its +monospaced family +.B C +(\[lq]Courier\[rq]). +. +Historical inertia has driven +.IR groff 's +font identifiers to short uppercase abbreviations of font names, +as with +.BR TR , +.BR TB , +.BR TI , +.BR TBI , +and a special font +.BR S . +. +. +.P +The default family used with abstract styles can be changed at any time; +initially, +it +.RB 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 +.B 1 +.RB ( R ). +. +By issuing appropriate formatter instructions, +you can override these defaults before your document writes its first +glyph. +. +. +.P +Terminal output devices cannot change font families and lack special +fonts. +. +They support style changes by overstriking, +or by altering ISO\~6429/\:ECMA-48 +.I "graphic renditions" +(character cell attributes). +.\" END Keep (roughly) parallel with groff.texi node "Using Fonts". +. +. +.\" ==================================================================== +.SH Hyphenation +.\" ==================================================================== +. +When filling, +.I groff +hyphenates words as needed at user-specified and automatically +determined hyphenation points. +. +Explicitly hyphenated words such as \[lq]mother-in-law\[rq] are always +eligible for breaking after each of their hyphens. +. +The hyphenation +.RB character\~ \[rs]% +and non-printing break +.RB point\~ \[rs]: +escape sequences may be used to control the hyphenation and breaking of +individual words. +. +The +.B .hw +request sets user-defined hyphenation points for specified words at any +subsequent occurrence. +. +Otherwise, +.I groff +determines hyphenation points automatically by default. +. +. +.P +Several requests influence automatic hyphenation. +. +Because conventions vary, +a variety of hyphenation modes is available to the +.B .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 default is +.RB \[lq] 1 \[rq] +for historical reasons, +but this is not an appropriate value for the English hyphenation +patterns used by +.IR groff ; +localization macro files loaded by +.I troffrc +and macro packages often override it. +. +. +.TP +.B 0 +disables hyphenation. +. +. +.TP +.B 1 +enables hyphenation except after the first and before the last character +of a word. +. +. +.P +The remaining values \[lq]imply\[rq] +.BR 1 ; +that is, +they enable hyphenation under the same conditions as +.RB \[lq] ".hy 1" \[rq], +and then apply or lift restrictions relative to that basis. +. +. +.TP +.B 2 +disables hyphenation of the last word on a page. +. +(Hyphenation is prevented if the next page location trap is closer to +the vertical drawing position than the next text baseline would be. +. +See section \[lq]Traps\[rq] below.) +. +. +.TP +.B 4 +disables hyphenation before the last two characters of a word. +. +. +.TP +.B 8 +disables hyphenation after the first two characters of a word. +. +. +.TP +.B 16 +enables hyphenation before the last character of a word. +. +. +.TP +.B 32 +enables hyphenation after the first character of a word. +. +. +.P +Apart from value\~2, +restrictions imposed by the hyphenation mode are +.I not +respected for words whose hyphenations have been specified with the +hyphenation character +.RB (\[lq] \|\[rs]% \[rq] +by default) +or the +.B .hw +request. +. +. +.P +Nonzero values are additive. +. +For example, +mode\~12 causes +.I groff +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. +. +. +.br +.ne 2v +.P +The places within a word that are eligible for hyphenation are +determined by language-specific data +.RB ( .hla , +.BR .hpf , +and +.BR .hpfa ) +and lettercase relationships +.RB ( .hcode +and +.BR .hpfcode ). +. +Furthermore, +hyphenation of a word might be suppressed due to a limit on +consecutive hyphenated lines +.RB ( .hlm ), +a minimum line length threshold +.RB ( .hym ), +or because the line can instead be adjusted with additional inter-word +space +.RB ( .hys ). +. +. +.\" ==================================================================== +.SH Localization +.\" ==================================================================== +. +The set of hyphenation patterns is associated with the hyphenation +language set by the +.B .hla +request. +. +The +.B .hpf +request is usually invoked by a localization file loaded by the +.I troffrc +file. +. +.I groff +provides localization files for several languages; +see +.MR groff_tmac @MAN5EXT@ . +. +. +.\" ==================================================================== +.SH "Writing macros" +.\" ==================================================================== +. +The +.B .de +request defines a macro named for its argument. +. +If that name already exists as an alias, +the target of the alias is redefined; +see section \[lq]Strings\[rq] above. +. +.I @g@troff +enters \[lq]copy mode\[rq] +(see below), +storing subsequent input lines as the definition. +. +If the optional second argument is not specified, +the definition ends with the control line +.RB \[lq] .. \[rq]\& +(two dots). +. +Alternatively, +a second argument names a macro whose call syntax ends the definition; +this \[lq]end macro\[rq] is then called normally. +. +Spaces or tabs are permitted after the first control character in the +line containing this ending token, +but a tab immediately after the token prevents its recognition as the +end of a macro definition. +. +Macro definitions can be nested if they use distinct end macros or if +their ending tokens are sufficiently escaped. +. +An end macro need not be defined until it is called. +. +This fact enables a nested macro definition to begin inside one macro +and end inside another. +. +. +.P +Variants of +.B .de +disable compatibility mode and/or indirect the names of the macros +specified for definition or termination: +these are +.BR .de1 , +.BR .dei , +and +.BR .dei1 . +. +Append to macro definitions with +.BR .am , +.BR .am1 , +.BR .ami , +and +.BR .ami1 . +. +The +.BR .als , +.BR .rm , +and +.B .rn +requests create an alias of, +remove, +and rename a macro, +respectively. +. +.B .return +stops the execution of a macro immediately, +returning to the enclosing context. +. +. +.\" ==================================================================== +.SS Parameters +.\" ==================================================================== +. +Macro call and string interpolation parameters can be accessed using +escape sequences starting with +.RB \[lq] \|\[rs]$ \[rq]. +. +The +.B \[rs]n[.$] +read-only register stores the count of parameters available to a macro +or string; +its value can be changed by the +.B .shift +request, +which dequeues parameters from the current list. +. +The +.B \[rs]$0 +escape sequence interpolates the name by which a macro was called. +. +Applying string interpolation to a macro does not change this name. +. +. +.\" ==================================================================== +.SS "Copy mode" +.\" ==================================================================== +. +When +.I @g@troff +processes certain requests, +most importantly those which define or append to a macro or string, +it does so in +.IR "copy mode" : +it copies the characters of the definition into a dedicated storage +region, +interpolating the escape sequences +.BR \[rs]n , +.BR \[rs]g , +.BR \[rs]$ , +.BR \[rs]* , +.BR \[rs]V , +and +.B \[rs]?\& +normally; +interpreting +.BI \[rs] newline +immediately; +discarding comments +.B \[rs]" +and +.BR \[rs]# ; +interpolating the current leader, +escape, +or tab character with +.BR \[rs]a , +.BR \[rs]e , +and +.BR \[rs]t , +respectively; +and storing all other escape sequences in an encoded form. +. +The complement of copy mode\[em]a +.I roff +formatter's behavior when not defining or appending to a macro, +string, +or diversion\[em]where all macros are interpolated, +requests invoked, +and valid escape sequences processed immediately upon recognition, +can be termed +.IR "interpretation mode" . +. +. +.P +The escape character, +.B \[rs] +by default, +can escape itself. +. +This enables you to control whether a given +.BR \[rs]n , +.BR \[rs]g , +.BR \[rs]$ , +.BR \[rs]* , +.BR \[rs]V , +or +.B \[rs]?\& +escape sequence is interpreted at the time the macro containing it is +defined, +or later when the macro is called. +. +. +.P +You can think of +.B \[rs]\[rs] +as a \[lq]delayed\[rq] backslash; +it is the escape character followed by a backslash from which the escape +character has removed its special meaning. +. +Consequently, +.B \[rs]\[rs] +is not an escape sequence in the usual sense. +. +In any escape sequence +.BI \[rs] X +that +.I @g@troff +does not recognize, +the escape character is ignored and +.IR X \~is +output. +. +An unrecognized escape sequence causes a warning in category +.RB \%\[lq] escape \[rq], +with two exceptions, +.B \[rs]\[rs] +being one. +. +The other is +.BR \[rs]. , +which escapes the control character. +. +It is used to permit nested macro definitions to end without a named +macro call to conclude them. +. +Without a syntax for escaping the control character, +this would not be possible. +. +.I roff +documents should not use the +.B \[rs]\[rs] +or +.B \[rs].\& +character sequences outside of copy mode; +they serve only to obfuscate the input. +. +Use +.B \[rs]e +to represent the escape character, +.B \[rs][rs] +to obtain a backslash glyph, +and +.B \[rs]& +before +.B .\& +and +.B \[aq] +where +.I @g@troff +expects them as control characters if you mean to use them literally. +. +. +.br +.ne 2v +.P +Macro definitions can be nested to arbitrary depth. +. +In +.RB \[lq] \|\[rs]\[rs] \[rq], +each escape character is interpreted twice\[em]once in copy mode, +when the macro is defined, +and once in interpretation mode, +when the macro is called. +. +This fact leads to exponential growth in the quantity of escape +characters required to delay interpolation of +.BR \[rs]n , +.BR \[rs]g , +.BR \[rs]$ , +.BR \[rs]* , +.BR \[rs]V , +and +.B \[rs]?\& +at each nesting level. +. +An alternative is to use +.BR \[rs]E , +which represents an escape character that is not interpreted in copy +mode. +. +Because +.B \[rs].\& +is not a true escape sequence, +we can't use +.B \[rs]E +to keep +.RB \[lq] ..\& \[rq] +from ending a macro definition prematurely. +. +If the multiplicity of backslashes complicates maintenance, +use end macros. +. +. +.\" ==================================================================== +.SH Traps +.\" ==================================================================== +. +.\" BEGIN Keep (roughly) parallel with groff.texi node "Traps". +.I Traps +are locations in the output, +or conditions on the input that, +when reached or fulfilled, +call a specified macro. +. +A +.I "vertical position trap" +calls a macro when the formatter's vertical drawing position reaches or +passes, +in the downward direction, +a certain location on the output page or in a diversion. +. +Its applications include setting page headers and footers, +body text in multiple columns, +and footnotes. +. +These traps can occur at a given location on the page +.RB ( .wh ,\~ .ch ); +at a given location in the current diversion +.RB ( .dt )\[em]together, +these are known as +vertical position traps, +which can be disabled and re-enabled +.RB ( .vpt ). +. +. +.P +A diversion is not formatted in the context of a page, +so it lacks page location traps; +instead it can have a +.I "diversion trap." +. +There can exist at most one such vertical position trap per diversion. +. +. +.P +Other kinds of trap can be planted +at a blank line +.RB ( .blm ); +at a line with leading space characters +.RB ( .lsm ); +after a certain number of productive input lines +.RB ( .it ,\~ .itc ); +or at the end of input +.RB ( .em ). +. +Macros called by traps are passed no arguments. +. +Setting a trap is also called +.I planting +one. +. +It is said that a trap is +.I sprung +if its condition is fulfilled. +.\" END Keep (roughly) parallel with groff.texi node "Traps". +. +. +.br +.ne 5v +.P +Registers associated with trap management include +vertical position trap enablement status +.RB ( \[rs]n[.vpt] ), +distance to the next trap +.RB ( \[rs]n[.t] ), +amount of needed +.RB ( .ne -requested) +space that caused the most recent vertical position trap to be sprung +.RB ( \[rs]n[.ne] ), +amount of needed space truncated from the amount requested +.RB ( \[rs]n[.trunc] ), +page ejection status +.RB ( \[rs]n[.pe] ), +and +leading space count +.RB ( \[rs]n[.lsn] ) +with its corresponding amount of motion +.RB ( \[rs]n[.lss] ). +. +. +.\" ==================================================================== +.SS "Page location traps" +.\" ==================================================================== +. +A +.I "page location trap" +is a vertical position trap that applies to +the page; +that is, +to undiverted output. +. +Many can be present; +manage them with +the +.B wh +and +.B ch +requests. +. +Non-negative page locations given to these requests set the trap +relative to the top of the page; +negative values set the trap relative to the bottom of the page. +. +It is not possible to plant a trap less than one basic unit from the +page bottom: +a location of \[lq]\-0\[rq] is interpreted as \[lq]0\[rq], +the top of the page. +. +An existing +.I visible +trap +(see below) +at the same location is removed; +this is +.BR .wh 's +sole function if its second argument is missing. +. +. +.P +A trap is sprung only if it is +.I visible, +meaning that its location is reachable on the page and it is not hidden +by another trap at the same location already planted there. +. +(A trap planted at \[lq]20i\[rq] or \[lq]\-30i\[rq] will not be sprung +on a page of length \[lq]11i\[rq].) +. +. +.P +A trap above the top or at or below the bottom of the page can be made +visible by either moving it into the page area or increasing the page +length so that the trap is on the page. +. +Negative trap values always use the +.I current +page length; +they are not converted to an absolute vertical position. +. +Use +.B .ptr +to dump page location traps to the standard error stream; +their positions are reported in basic units. +. +. +.br +.ne 6v +.\" ==================================================================== +.SS "The implicit page trap" +.\" ==================================================================== +. +An +.I implicit page trap +always exists in the top-level diversion; +it works like a trap in some ways but not others. +. +Its purpose is to eject the current page and start the next one. +. +It has no name, +so it cannot be moved or deleted with +.B wh +or +.B ch +requests. +. +You cannot hide it by placing another trap at its location, +and can move it only by redefining the page length with +.BR .pl . +. +Its operation is suppressed when vertical page traps are disabled with +the +.B vpt +request. +. +. +.\" ==================================================================== +.SH Diversions +.\" ==================================================================== +. +.\" BEGIN Keep (roughly) parallel with groff.texi node "Diversions". +In +.I roff +systems it is possible to format text as if for output, +but instead of writing it immediately, +one can +.I divert +the formatted text into a named storage area. +. +It is retrieved later by specifying its name after a control character. +. +The same name space is used for such +.I diversions +as for strings and macros; +see section \[lq]Identifiers\[rq] above. +. +Such text is sometimes said to be \[lq]stored in a macro\[rq], +but this coinage obscures the important distinction between macros and +strings on one hand and diversions on the other; +the former store +.I unformatted +input text, +and the latter capture +.I formatted +output. +. +Diversions also do not interpret arguments. +. +Applications of diversions include \[lq]keeps\[rq] +(preventing a page break from occurring at an inconvenient place by +forcing a set of output lines to be set as a group), +footnotes, +tables of contents, +and indices. +. +For orthogonality it is said that GNU +.I troff \" GNU +is in the +.I top-level diversion +if no diversion is active +(that is, +formatted output is being \[lq]diverted\[rq] immediately to the output +device. +. +. +.P +Dereferencing an undefined diversion will create an empty one of that +name and cause a warning in category +.B mac +to be emitted. +(see section \[lq]Warnings\[rq] in +.MR @g@troff @MAN1EXT@ ). +. +A diversion does not exist for the purpose of testing with the +.B d +conditional operator until its initial definition ends +(see subsection \[lq]Conditional expressions\[rq] above). +.\" The following requests are used to create and alter diversions. +.\" END Keep (roughly) parallel with groff.texi node "Diversions". +. +. +.P +The +.B di +request creates a diversion, +including any partially collected line. +. +.B da +appends to a diversion, +creating one if it does not already exist. +. +If the diversion's name already exists as an alias, +the target of the alias is replaced or appended to; +see section \[lq]Strings\[rq] above. +. +.B box +and +.B boxa +works similarly, +but ignore partially collected lines. +. +Call any of these macros again without an argument to end the diversion. +. +. +.br +.ne 2v +.P +Diversions can be nested. +. +The registers +.BR .d , +.BR .z , +.BR dn , +and +.B dl +report information about the current +(or last closed) +diversion. +. +.B .h +is meaningful in diversions, +including the top level. +. +. +.P +The +.B \[rs]!\% +and +.B \[rs]?\% +escape sequences and +.B output +request escape from a diversion, +the first two to the enclosing level and the last to the top level. +. +This facility is termed +.IR "transparent embedding" . +. +. +.P +The +.B asciify +and +.B unformat +requests reprocess diversions. +.\" XXX: That's a weak statement. What we need is a `for` request and +.\" a new conditional operator that tests whether an item in a node list +.\" is an (otherwise unrepresentable) node. See Savannah #62264. +. +. +.\" ==================================================================== +.SH "Punning names" +.\" ==================================================================== +. +.\" BEGIN Keep (roughly) parallel with groff.texi node "Punning names". +Macros, +strings, +and diversions share a name space; +see section \[lq]Identifiers\[rq] above. +. +Internally, +the same mechanism is used to store them. +. +You can thus call a macro with string interpolation syntax and vice +versa. +. +Interpolating a string does not hide existing macro arguments. +. +The sequence +.B \[rs]\[rs] +can be placed at the end of a line in a macro definition or, +within a macro definition, +immediately after the interpolation of a macro as a string to suppress +the effect of a newline. +.\" END Keep (roughly) parallel with groff.texi node "Punning names". +. +. +.\" ==================================================================== +.SH Environments +.\" ==================================================================== +. +.\" BEGIN Keep (roughly) parallel with groff.texi node "Environments". +Environments store most of the parameters that control text processing. +. +A default environment named +.RB \[lq] 0 \[rq] +exists when +.I @g@troff +starts up; +it is modified by formatting-related requests and escape sequences. +. +. +.P +You can create new environments and switch among them. +. +Only one is current at any given time. +. +Active environments are managed using a +.I stack, +a data structure supporting \[lq]push\[rq] and \[lq]pop\[rq] operations. +. +The current environment is at the top of the stack. +. +The same environment name can be pushed onto the stack multiple times, +possibly interleaved with others. +. +Popping the environment stack does not destroy the current environment; +it remains accessible by name and can be made current again by pushing +it at any time. +. +Environments cannot be renamed or deleted, +and can only be modified when current. +. +To inspect the environment stack, +use the +.B pev +request; +see section \[lq]Debugging\[rq] below. +. +. +.P +Environments store the following information. +. +. +.IP \[bu] 2n +a partially collected line, if any +. +. +.IP \[bu] +data about the most recently output glyph and line +(registers +.BR .cdp , +.BR .cht , +.BR .csk , +.BR .n , +.BR .w ) +. +. +.IP \[bu] +typeface parameters +(size, +family, +style, +height and slant, +inter-word and inter-sentence space sizes) +. +. +.IP \[bu] +page parameters +(line length, +title length, +vertical spacing, +line spacing, +indentation, +line numbering, +centering, +right-alignment, +underlining, +hyphenation parameters) +. +. +.IP \[bu] +filling enablement; +adjustment enablement and mode +. +. +.IP \[bu] +tab stops; +tab, +leader, +escape, +control, +no-break control, +hyphenation, +and +margin characters +. +. +.IP \[bu] +input line traps +. +. +.IP \[bu] +stroke and fill colors +. +. +.P +The +.B ev +request pushes to and pops from the environment stack, +while +.B evc +copies a named environment's contents to the current one. +.\" END Keep (roughly) parallel with groff.texi node "Environments". +. +. +.\" ==================================================================== +.SH Underlining +.\" ==================================================================== +. +In +.I RUNOFF +(see +.MR roff @MAN7EXT@ ), +underlining, +even of lengthy passages, +was straightforward because only fixed-pitch printing devices were +targeted. +. +Typesetter output posed a greater challenge. +. +There exists a +.I groff +request +.B .ul +(see above) +that underlines subsequent source lines on terminal devices, +but on typesetters, +it selects an italic font style instead. +. +. +The +.I ms +macro package +(see +.MR groff_ms @MAN7EXT@ ) +offers a macro +.BR .UL , +but it too produces the desired effect only on typesetters, +and has other limitations. +. +. +.P +One could adapt +.IR ms 's +approach to the construction of a macro as follows. +. +.RS +.EX +\&.de UNDERLINE +\&. ie n \[rs]\[rs]$1\[rs]f[I]\[rs]\[rs]$2\[rs]f[P]\[rs]\[rs]$3 +\&. el \[rs]\[rs]$1\[rs]Z\[aq]\[rs]\[rs]$2\[aq]\[rs]v\[aq].25m\[aq]\ +\[rs]D\[aq]l \[rs]w\[aq]\[rs]\[rs]$2\[aq]u 0\[aq]\[rs]v\[aq]\-.25m\ +\[aq]\[rs]\[rs]$3 +\&.. +.EE +.RE +. +If +.MR doclifter 1 +makes trouble, change the macro name +.B UNDERLINE +into some 2-letter word, like +.BR Ul . +. +Moreover, +change the form of the font selection escape sequence from +.B \[rs]f[P] +to +.BR \[rs]fP . +. +. +.\" ==================================================================== +.SS "Underlining without macro definitions" +.\" ==================================================================== +. +If one does not want to use macro definitions, +e.g., +when +.I doclifter +gets lost, +use the following. +. +.RS +.EX +\&.ds u1 before +\&.ds u2 in +\&.ds u3 after +\&.ie n \[rs]*[u1]\[rs]f[I]\[rs]*[u2]\[rs]f[P]\[rs]*[u3] +\&.el \[rs]*[u1]\[rs]Z\[aq]\[rs]*[u2]\[aq]\[rs]v\[aq].25m\[aq]\[rs]D\ +\[aq]l \[rs]w\[aq]\[rs]*[u2]\[aq]u 0\[aq]\[rs]v\[aq]\-.25m\[aq]\[rs]*\ +[u3] +.EE +.RE +. +.ne 2v +When using +.IR doclifter , +it might be necessary to change syntax forms such as +.B \e[xy] +and +.B \e*[xy] +to those supported by AT&T +.IR troff : +.B \e*(xy +and +.BR \e(xy , +and so on. +. +. +.P +Then these lines could look like +.RS +.EX +\&.ds u1 before +\&.ds u2 in +\&.ds u3 after +\&.ie n \[rs]*[u1]\[rs]fI\[rs]*(u2\[rs]fP\[rs]*(u3 +\&.el \[rs]*(u1\[rs]Z\[aq]\[rs]*(u2\[aq]\[rs]v\[aq].25m\[aq]\[rs]D\ +\[aq]l \[rs]w\[aq]\[rs]*(u2\[aq]u 0\[aq]\[rs]v\[aq]\-.25m\[aq]\[rs]*(u3 +.EE +.RE +. +. +.P +The result looks like +.RS +.ft CR +before +\z\[ul]i\ +\z\[ul]n +after +.ft R +.RE +. +. +.\" ==================================================================== +.SS "Underlining by overstriking with \e(ul" +.\" ==================================================================== +. +The +.B \[rs]z +escape sequence writes a glyph without advancing the +drawing position, +enabling overstriking. +. +Thus, +.BI \[rs]z c \[rs](ul +formats +.I c +with an underrule glyph on top of it. +. +Video terminals implement the underrule by setting a character cell's +underline attribute, +so this technique works in both +.I nroff \" mode +and +.I troff \" mode +modes. +. +. +.P +Long words may then look intimidating in the input; +a clarifying approach might be to use the input line continuation escape +sequence +.BI \[rs] newline +to place each underlined character on its own input line. +. +Thus, +. +.RS +.EX +\&.nf +\[rs]&\[rs]fB: ${\[rs]fIvar\[rs]fR\[rs]c +\[rs]zo\[rs](ul\[rs] +\[rs]zp\[rs](ul\[rs]c +\[rs]&\[rs]fIvalue\[rs]fB} +\&.fi +.EE +.RE +. +produces +. +.RS +.EX +.BI ": ${" var \c +\zo\(ul\ +\zp\(ul\c +.IB value } +.EE +.RE +. +as output. +. +. +.\" ==================================================================== +.SH "Compatibility mode" +.\" ==================================================================== +. +The differences between the +.I roff +language recognized by GNU +.I troff \" GNU +and that of AT&T +.IR troff , \" AT&T +as well as the device, +font, +and device-independent intermediate output formats described by +CSTR\~#54 are documented in +.MR groff_diff @MAN7EXT@ . +. +.I groff +provides an AT&T compatibility mode. +. +The +.request .cp +request and registers +.B .C +and +.B .cp +set and test the enablement of this mode. +. +. +.\" ==================================================================== +.SH Debugging +.\" ==================================================================== +. +.\" BEGIN Keep (roughly) parallel with groff.texi node "Debugging". +Preprocessors use the +.B .lf +request to preserve the identities of line numbers and names of input +files. +. +.I groff +emits a variety of error diagnostics and supports several categories of +warning; +the output of these can be selectively suppressed with +.B .warn +(and see the +.BR \-E , +.BR \-w , +and +.B \-W +options of +.MR @g@troff @MAN1EXT@ ). +. +A trace of the formatter's input processing stack can be emitted when +errors or warnings occur by means of +.MR @g@troff @MAN1EXT@ 's +.B \-b +option, +or produced on demand with the +.request .backtrace +request. +. +.BR .tm , +.BR .tmc , +and +.B .tm1 +can be used to emit customized diagnostic messages or for +instrumentation while troubleshooting. +. +.B .ex +and +.B .ab +cause early termination with successful and error exit codes +respectively, +to halt further processing when continuing would be fruitless. +. +Examine the state of the formatter with requests that write lists of +defined names\[em]macros, +strings, +and +.RB diversions\[em]( .pm ); +environments +.RB ( .pev ), +registers +.RB ( .pnr ), +and page location traps +.RB ( .ptr ) +to the standard error stream. +.\" END Keep (roughly) parallel with groff.texi node "Debugging". +. +. +.\" ==================================================================== +.SH Authors +.\" ==================================================================== +. +This document was written by +by Trent A.\& Fisher, +Werner Lemberg, +and +.MT g.branden\:.robinson@\:gmail\:.com +G.\& Branden Robinson +.ME . +. +Section \[lq]Underlining\[rq] was primarily written by +.MT groff\-bernd\:.warken\-72@\:web\:.de +Bernd Warken +.ME . +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +.ne 2v +.IR "Groff: The GNU Implementation of troff" , +by Trent A.\& Fisher and Werner Lemberg, +is the primary +.I groff +manual. +. +You can browse it interactively with \[lq]info groff\[rq]. +. +. +.br +.ne 4v +.P +\[lq]Troff User's Manual\[rq] +by Joseph F.\& Ossanna, +1976 +(revised by Brian W.\& Kernighan, +1992), +AT&T Bell Laboratories Computing Science Technical Report No.\& 54, +widely called simply \[lq]CSTR\~#54\[rq], +documents the language, +device and font description file formats, +and device-independent output format +referred to collectively in +.I groff +documentation as +.RI \[lq]AT&T\~ troff \[rq]. +. +. +.br +.ne 3v +.P +\[lq]A Typesetter-independent TROFF\[rq] +by Brian W.\& Kernighan, +1982, +AT&T Bell Laboratories Computing Science Technical Report No.\& 97 +(CSTR\~#97), +provides additional insights into the +device and font description file formats +and device-independent output format. +. +. +.TP +.MR groff @MAN1EXT@ +is the preferred interface to the +.I groff +system; +it manages the pipeline that carries a source document through +preprocessors, +the +.I @g@troff +formatter, +and an output driver to viewable or printable form. +. +It also exhaustively lists the man pages provided with the GNU +.I roff +system. +. +. +.TP +.MR groff_char @MAN7EXT@ +discusses character encoding issues, +escape sequences that produce glyphs, +and enumerates +.IR groff 's +predefined special character escape sequences. +. +. +.TP +.MR groff_diff @MAN7EXT@ +covers differences between the +GNU +.I troff \" GNU +formatter, +its device and font description file formats, +its device-independent output format, +and those of AT&T +.IR troff ,\" AT&T +whose design it reimplements. +. +. +.TP +.MR groff_font @MAN5EXT@ +describes the formats of the files that describe devices +.RI ( DESC ) +and fonts. +. +. +.TP +.MR groff_tmac @MAN5EXT@ +surveys macro packages provided with +.IR groff , +describes how documents can take advantage of them, +offers guidance on writing macro packages and using diversions, +and includes historical information on macro package naming conventions. +. +. +.TP +.MR roff @MAN7EXT@ +presents a detailed history of +.I roff +systems and summarizes concepts common to them. +. +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_groff_7_man_C] +.do rr *groff_groff_7_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff textwidth=72: |