diff options
Diffstat (limited to '')
| -rw-r--r-- | man/groff.7.man | 8055 | ||||
| -rw-r--r-- | man/groff_char.7.man | 2282 | ||||
| -rw-r--r-- | man/groff_diff.7.man | 6188 | ||||
| -rw-r--r-- | man/groff_font.5.man | 1114 | ||||
| -rw-r--r-- | man/groff_out.5.man | 1963 | ||||
| -rw-r--r-- | man/groff_tmac.5.man | 1474 | ||||
| -rw-r--r-- | man/man.am | 46 | ||||
| -rw-r--r-- | man/roff.7.man | 2613 |
8 files changed, 23735 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: diff --git a/man/groff_char.7.man b/man/groff_char.7.man new file mode 100644 index 0000000..b3ddb49 --- /dev/null +++ b/man/groff_char.7.man @@ -0,0 +1,2282 @@ +'\" t +.TH groff_char @MAN7EXT@ "@MDATE@" "groff @VERSION@" +.SH Name +groff_char \- GNU +.I roff +special character and glyph repertoire +. +. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 1989-2023 Free Software Foundation, Inc. +.\" +.\" This file is part of groff (GNU roff), which is a free software +.\" project. +.\" +.\" You can redistribute it and/or modify it under the terms of the GNU +.\" General Public License as published by the Free Software Foundation, +.\" either version 2 of the License, or (at your option) any later +.\" version. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with this program. +.\" +.\" If not, see <http://www.gnu.org/licenses/gpl-2.0.html>. +. +. +.\" Save and disable compatibility mode (for, e.g., Solaris 10/11). +.do nr *groff_groff_char_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 +. +. +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +The GNU +.I roff +typesetting system has a large glyph repertoire suitable for production +of varied literary, +professional, +technical, +and mathematical documents. +. +.I groff +works with +.I characters; +an output device renders +.I glyphs. +. +.IR groff 's +input character set is restricted to that defined by the standards +ISO Latin-1 +(ISO 8859-1) +and CCSID \[lq]code page\[rq] 1047 +(an EBCDIC arrangement of Latin-1). +. +For ease of document maintenance in UTF-8 environments, +it is advisable to use only the Unicode basic Latin code points, +a subset of all of the foregoing historically referred to as \%US-ASCII, +.\" Yes, a subset, albeit a permutation as well in the cp1047 case. +which has only 94 visible, +printable code points. +.\" In groff, 0x20 SP is mapped to a space node, not a glyph node, and +.\" all kinds of special behavior attaches to such nodes, so we count +.\" only to 94 and not 95 as is often done in other ASCII contexts. +In +.I groff, +these are termed +.I "ordinary characters." +. +Often, +many more are desired in output. +. +. +.P +AT&T +.I troff +in the 1970s faced a similar problem: +the available typesetter's glyph repertoire differed from that of the +computers that controlled it. +. +.IR troff 's \" AT&T +solution was a form of escape sequence known as a +.I special character +to access several dozen additional glyphs available in the fonts +prepared for mounting in the phototypesetter. +. +These glyphs were mapped onto a two-character name space for a degree +of mnemonic convenience; +for example, +the escape sequence +.B \e(aa +encoded an acute accent and +.B \e(sc +a section sign. +. +. +.P +.I groff +has lifted historical +.I roff +limitations on special character name lengths, +but recognizes and retains compatibility with the historical names. +. +.I groff +expands the lexicon of glyphs available by name and permits users to +define their own special character escape sequences with the +.B char +request. +. +Special character names are +.I groff +identifiers; +see section \[lq]Identifiers\[rq] in +.MR groff @MAN7EXT@ . +. +Our discussion uses the terms \[lq]glyph name\[rq] and \[lq]special +character name\[rq] interchangeably; +we assume no character translations or redefinitions. +. +. +.P +This document lists all of the glyph names predefined by +.IR groff 's +font description files and presents the systematic notation by which it +enables access to arbitrary Unicode code points and construction of +composite glyphs. +. +Glyphs listed may be unavailable, +or may vary in appearance, +depending on the output device and font chosen when the page was +formatted. +. +This page was rendered for device +.B \*[.T] +using font +.BR \n[.fn] . +. +. +.P +A few escape sequences that are not +.I groff +special characters also produce glyphs; +these exist for syntactical or historical reasons. +. +.BR \e\[aq] , +.BR \e\[ga] , +.BR \e\- , +and +.B \e_ +are translated on input to the special character escape sequences +.BR \e[aa] , +.BR \e[ga] , +.BR \e[\-] , +and +.BR \e[ul] , +respectively. +. +Others include +.BR \e\e , +.B \e.\& +(backslash-dot), +and +.BR \ee ; +see +.MR groff @MAN7EXT@ . +. +A small number of special characters represent glyphs that are not +encoded in Unicode; +examples include the baseline rule +.B \e[ru] +and the Bell System logo +.B \e[bs]. +. +. +.P +In +.IR groff , +you can test output device support for any character +(ordinary or special) +with the conditional expression operator +.RB \[lq] c \[rq]. +. +.RS +.\" https://www.bell-labs.com/usr/dmr/www/ ("In 1984, ...") +.EX +\&.ie c \e[bs] \e{Welcome to the \e[bs] Bell System; +did you get the Wehrmacht helmet or the Death Star?\e} +\&.el No Bell System logo. +.EE +.RE +. +. +.P +For brevity in the remainder of this document, +we shall refer to systems conforming to the +ISO 646:1991 IRV, +ISO 8859, +or +ISO 10646 (\[lq]Unicode\[rq]) +character encoding standards as \[lq]ISO\[rq] systems, +and those employing IBM code page 1047 as \[lq]EBCDIC\[rq] systems. +. +That said, +EBCDIC systems that support +.I groff +are known to also support UTF-8. +. +. +.P +While +.I groff +accepts eight-bit encoded input, +not all such code points are valid as input. +. +.\" src/libs/libgroff/invalid.cpp +On ISO platforms, +character codes +0, +11, +13\[en]31, +and +128\[en]159 +are invalid. +. +(This is all C0 and C1 controls except for +SOH through LF +[Control+A to Control+J], +and FF +[Control+L].) +. +On EBCDIC platforms, +0, +8\[en]9, +11, +13\[en]20, +23\[en]31, +and +48\[en]63 +are invalid. +. +Some of these code points are used by +.I groff +for internal purposes, +which is one reason it does not support UTF-8 natively. +. +. +.\" ==================================================================== +.SS "Fundamental character set" +.\" ==================================================================== +. +The ordinary characters catalogued above, +plus the space, +tab, +newline, +and leader (Control+A), +form the fundamental character +set for +.I groff +input; +anything in the language, +even over one million code points in Unicode, +can be expressed using it. +. +On ISO systems, +code points in the range 33\[en]126 comprise a common set of +printable glyphs in all of the aforementioned ISO character encoding +standards. +. +It is this character set and +(with some noteworthy exceptions) +the corresponding glyph repertoire for which AT&T +.I troff +was implemented. +. +On EBCDIC systems, +printable characters are in the range 66\[en]201 and 203\[en]254; +those without counterparts in the ISO range 33\[en]126 are discussed +in the next subsection. +.\" From this point, do not talk about numerical character assignments. +. +. +.P +All of the following characters map to glyphs as you would expect. +. +.TS +center box; +Lf(CR). +! # $ % & ( ) * + , . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ? @ +A B C D E F G H I J K L M N O P Q R S T U V W X Y Z [ ] _ +a b c d e f g h i j k l m n o p q r s t u v w x y z { | } +.TE +.\" The bottom border of that box is practically kissin' the tittles. +.if t .sp 0.2v +. +The remaining ordinary characters surprise computing professionals and +others intimately familiar with the ISO character encodings. +. +The developers of AT&T +.I troff +chose mappings for them that would be useful for typesetting technical +literature in a broad range of scientific disciplines: +Bell Labs used the system for preparation of AT&T's patent filings with +the U.S.\& government. +. +Further, +the prevailing character encoding standard in the 1970s, +USAS X3.4-1968 (\[lq]ASCII\[rq]), +deliberately supported semantic ambiguity at some code points, +and outright substitution at several others, +to suit the localization demands of various national standards bodies. +. +. +.P +The table below presents the seven exceptional code points +with their typical keycap engravings, +their glyph mappings and semantics in +.I roff +systems, +and the escape sequences producing the Unicode basic Latin character +they replace. +. +The first, +the neutral double quote, +is a partial exception because it does represent itself, +but since the +.I roff +language also uses it to quote macro arguments, +.I groff +supports a special character escape sequence as an alternative form so +that the glyph can be easily included in macro arguments without +requiring the user to master the quoting rules that AT&T +.I troff +required in that context. +. +(Some requests, +like +.BR ds , +also treat +.B \[dq] +non-literally.) +. +Furthermore, +not all of the special character escape sequences are portable to AT&T +.I troff +and all of its descendants; +these +.I groff +extensions are presented using its special character form +.BR \[rs][] , +whereas portable special character escape sequences are shown in the +traditional +.B \[rs]( +form. +. +.B \[rs]\- +and +.B \[rs]e +are portable to all known +.IR troff s. +. +.B \[rs]e +means \[lq]the glyph of the current escape character\[rq]; +it therefore can produce unexpected output if the +.B ec +request is used. +. +On devices with a limited glyph repertoire, +glyphs in the \[lq]keycap\[rq] and \[lq]appearance\[rq] columns on the +same row of the table may look identical; +except for the neutral double quote, +this will +.I not +be the case on more-capable devices. +. +Review your document using as many different output devices as possible. +. +. +.P +.TS +center box; +L L L. +Keycap Appearance and meaning Special character and meaning +_ +" " neutral double quote \f[CR]\[rs][dq]\f[] neutral double quote +\[aq] \[cq] closing single quote \f[CR]\[rs][aq]\f[] neutral apostrophe +\- - hyphen \f[CR]\[rs]\-\f[] or \f[CR]\[rs][\-]\f[] minus sign/Unix dash +\[rs] (escape character) \f[CR]\[rs]e\f[] or \f[CR]\[rs][rs]\f[] reverse solidus +\[ha] \[u02C6] modifier circumflex \f[CR]\[rs](ha\f[] circumflex/caret/\[lq]hat\[rq] +\[ga] \[oq] opening single quote \f[CR]\[rs](ga\f[] grave accent +\[ti] \[u02DC] modifier tilde \f[CR]\[rs](ti\f[] tilde +.TE +. +. +.P +The hyphen-minus is a particularly unfortunate case of overloading. +. +Its awkward name in ISO 8859 and later standards reflects the many +distinguishable purposes to which it had already been put by the 1980s, +including +a hyphen, +a minus sign, +and +(alone or in repetition) +dashes of varying widths. +. +For best results in +.I roff +systems, +use the +.RB \[lq] \- \[rq] +character in input outside an escape sequence +.I only +to mean a hyphen, +as in the phrase \[lq]long-term\[rq]. +. +For a minus sign in running text or a Unix command-line option dash, +use +.B \[rs]\- +(or +.B \[rs][\-] +in +.I groff +if you find it helps the clarity of the source document). +. +(Another minus sign, +for use in mathematical equations, +is available as +.BR \[rs][mi] ). +. +AT&T +.I troff +supported em-dashes as +.BR \[rs](em , +as does +.IR groff . +. +. +.P +The special character escape sequence for the apostrophe as a neutral +single quote is typically needed only in technical content; +typing words like \[lq]can't\[rq] and \[lq]Anne's\[rq] in a natural way +will render correctly, +because in ordinary prose an apostrophe is typeset either as a closing +single quotation mark or as a neutral single quote, +depending on the capabilities of the output device. +. +By contrast, +special character escape sequences should be used for quotation marks +unless portability to limited or historical +.I troff +implementations is necessary; +on those systems, +the input convention is to pair the grave accent with the apostrophe for +single quotes, +and to double both characters for double quotes. +. +AT&T +.I troff +defined no special characters for quotation marks or the apostrophe. +. +Repeated single quotes +(\[oq]\[oq]thus\[cq]\[cq]) +will be visually distinguishable from double quotes +(\[lq]thus\[rq]) +on terminal devices, +and perhaps on others +(depending on the font selected). +. +.TS +tab(@) center box; +L L. +AT&T \f[I]troff\f[] input@recommended \f[I]groff\f[] input +_ +.T& +Lf(CR) Lf(CR). +A Winter\[aq]s Tale@A Winter\[aq]s Tale +\[ga]U.K.\& outer quotes\[aq]@\[rs][oq]U.K.\& outer quotes\[rs][cq] +\[ga]U.K.\& \[ga]\[ga]inner\[aq]\[aq] quotes\[aq]\ +@\[rs][oq]U.K.\& \[rs][lq]inner\[rs][rq] quotes\[rs][cq] +\[ga]\[ga]U.S.\& outer quotes\[aq]\[aq]\ +@\[rs][lq]U.S.\& outer quotes\[rs][rq] +\[ga]\[ga]U.S.\& \[ga]inner\[aq] quotes\[aq]\[aq]\ +@\[rs][lq]U.S.\& \[rs][oq]inner\[rs][cq] quotes\[rs][rq] +.TE +.\" Keep bottom border of box from sitting on the ascenders below. +.if t .sp 0.2v +. +If you frequently require quotation marks in your document, +see if the macro package you're using supplies strings or macros to +facilitate quotation, +or define them yourself +(except in man pages). +. +. +.P +Using Unicode basic Latin characters to compose boxes and lines is +ill-advised. +. +.I roff +systems have special characters for drawing horizontal and vertical +lines; +see subsection \[lq]Rules and lines\[rq] below. +. +Preprocessors like +.MR @g@tbl @MAN1EXT@ +and +.MR @g@pic @MAN1EXT@ +draw boxes and will produce the best possible output for the device, +falling back to basic Latin glyphs only when necessary. +. +. +.\" ==================================================================== +.SS "Eight-bit encodings and Latin-1 supplement" +.\" ==================================================================== +. +ISO 646 is a seven-bit code encoding 128 code points; +eight-bit codes are twice the size. +. +ISO 8859-1 and code page 1047 allocated the additional space to what +Unicode calls \[lq]C1 controls\[rq] +(control characters) +and the \[lq]Latin-1 supplement\[rq]. +. +The C1 controls are neither printable nor usable as +.I groff +input. +. +. +.P +Two Latin-1 supplement characters are handled specially on input. +. +.I @g@troff +never produces them as output. +. +. +.TP +NBSP +encodes a no-break space; +it is mapped to +.BR \[rs]\[ti] , +the adjustable non-breaking space escape sequence. +. +. +.TP +SHY +encodes a soft hyphen; +it is mapped to +.BR \[rs]% , +the hyphenation control escape sequence. +. +. +.P +The remaining characters in the Latin-1 supplement represent +themselves. +. +Although they can be specified directly with the keyboard on systems +configured to use Latin-1 as the character encoding, +it is more portable, +both to other +.I roff +systems and to UTF-8 environments, +to use their special character escape sequences, +shown below. +. +The glyph descriptions we use are non-standard in some cases, +for brevity. +. +. +.P +.TS +L2 Lf(CR)1 L L2 Lf(CR)1 L. +\[r!] \e[r!] inverted exclamation mark \[~N] \e[\[ti]N] N tilde +\[ct] \e[ct] cent sign \[`O] \e[\[ga]O] O grave +\[Po] \e[Po] pound sign \['O] \e[\[aq]O] O acute +\[Cs] \e[Cs] currency sign \[^O] \e[\[ha]O] O circumflex +\[Ye] \e[Ye] yen sign \[~O] \e[\[ti]O] O tilde +\[bb] \e[bb] broken bar \[:O] \e[:O] O dieresis +\[sc] \e[sc] section sign \[mu] \e[mu] multiplication sign +\[ad] \e[ad] dieresis accent \[/O] \e[/O] O slash +\[co] \e[co] copyright sign \[`U] \e[\[ga]U] U grave +\[Of] \e[Of] feminine ordinal indicator \['U] \e[\[aq]U] U acute +\[Fo] \e[Fo] left double chevron \[^U] \e[\[ha]U] U circumflex +\[no] \e[no] logical not \[:U] \e[:U] U dieresis +\[rg] \e[rg] registered sign \['Y] \e[\[aq]Y] Y acute +\[a-] \e[a\-] macron accent \[TP] \e[TP] uppercase thorn +\[de] \e[de] degree sign \[ss] \e[ss] lowercase sharp s +\[+-] \e[+\-] plus-minus \[`a] \e[\[ga]a] a grave +\[S2] \e[S2] superscript two \['a] \e[\[aq]a] a acute +\[S3] \e[S3] superscript three \[^a] \e[\[ha]a] a circumflex +\[aa] \e[aa] acute accent \[~a] \e[\[ti]a] a tilde +\[mc] \e[mc] micro sign \[:a] \e[:a] a dieresis +\[ps] \e[ps] pilcrow sign \[oa] \e[oa] a ring +\[pc] \e[pc] centered period \[ae] \e[ae] ae ligature +\[ac] \e[ac] cedilla accent \[,c] \e[,c] c cedilla +\[S1] \e[S1] superscript one \[`e] \e[\[ga]e] e grave +\[Om] \e[Om] masculine ordinal indicator \['e] \e[\[aq]e] e acute +\[Fc] \e[Fc] right double chevron \[^e] \e[\[ha]e] e circumflex +\[14] \e[14] one quarter symbol \[:e] \e[:e] e dieresis +\[12] \e[12] one half symbol \[`i] \e[\[ga]i] i grave +\[34] \e[34] three quarters symbol \['i] \e[\[aq]i] e acute +\[r?] \e[r?] inverted question mark \[^i] \e[\[ha]i] i circumflex +\[`A] \e[\[ga]A] A grave \[:i] \e[:i] i dieresis +\['A] \e[\[aq]A] A acute \[Sd] \e[Sd] lowercase eth +\[^A] \e[\[ha]A] A circumflex \[~n] \e[\[ti]n] n tilde +\[~A] \e[\[ti]A] A tilde \[`o] \e[\[ga]o] o grave +\[:A] \e[:A] A dieresis \['o] \e[\[aq]o] o acute +\[oA] \e[oA] A ring \[^o] \e[\[ha]o] o circumflex +\[AE] \e[AE] AE ligature \[~o] \e[\[ti]o] o tilde +\[,C] \e[,C] C cedilla \[:o] \e[:o] o dieresis +\[`E] \e[\[ga]E] E grave \[di] \e[di] division sign +\['E] \e[\[aq]E] E acute \[/o] \e[/o] o slash +\[^E] \e[\[ha]E] E circumflex \[`u] \e[\[ga]u] u grave +\[:E] \e[:E] E dieresis \['u] \e[\[aq]u] u acute +\[`I] \e[\[ga]I] I grave \[^u] \e[\[ha]u] u circumflex +\['I] \e[\[aq]I] I acute \[:u] \e[:u] u dieresis +\[^I] \e[\[ha]I] I circumflex \['y] \e[\[aq]y] y acute +\[:I] \e[:I] I dieresis \[Tp] \e[Tp] lowercase thorn +\[-D] \e[\-D] uppercase eth \[:y] \e[:y] y dieresis +.TE +. +. +.\" ==================================================================== +.SS "Special character escape forms" +.\" ==================================================================== +. +Glyphs that lack a character code in the basic Latin repertoire to +directly represent them are entered by one of several special character +escape forms. +. +Such glyphs can be simple or composite, +and accessed either by name or numerically by code point. +. +Code points and combining properties are determined by character +encoding standards, +whereas glyph names as used here originated in AT&T +.I troff \" AT&T +special character escape sequences. +. +Predefined glyph names use only characters in the basic Latin +repertoire. +. +. +.TP +.BI \[rs]( gl +is a special character escape sequence for the glyph with the +two-character name +.IR gl . +. +This is the original syntax form supported by AT&T +.IR troff . +. +The acute accent, +.BR \[rs](aa , +is an example. +. +. +.TP +.BI \[rs]C\[aq] glyph-name \[aq] +is a special character escape sequence for +.IR glyph-name , +which can be of arbitrary length. +. +The delimiter, +shown here as a neutral apostrophe, +can be any character not occurring in +.IR glyph-name . +. +This syntax form was introduced in later versions of AT&T +device-independent +.IR troff . \" AT&T +. +The foregoing acute accent example can be expressed +as +.BR \[rs]C\[aq]aa\[aq] . +. +. +.TP +.BI \[rs][ glyph-name ] +is a special character escape sequence for +.IR glyph-name , +which can be of arbitrary length but must not contain a closing square +bracket +.RB \[lq] ] \[rq]. +. +(No glyph names predefined by +.I groff +employ +.RB \[lq] ] \[rq].) +. +The foregoing acute accent example can be expressed in +.I groff +as +.BR \[rs][aa] . +. +. +.P +.BI \[rs]C\[aq] c \[aq] +and +.BI \[rs][ c ] +are not synonyms for the ordinary character +.RI \[lq] c \[rq], +but request the special character named +.RB \[lq] \[rs] \c +.IR c \[rq]. +. +For example, +.RB \[lq] \[rs][a] \[rq] +is not \[lq]a\[rq], +but rather a special character with the internal glyph name +(used in font description files and diagnostic messages) +.BR \[rs]a , +which is typically undefined. +. +The only such glyph name +.I groff +predefines is the minus sign, +which can therefore be accessed as +.B \[rs]C\[aq]\-\[aq] +or +.BR \[rs][\-] . +. +. +.TP +.BI \[rs][ "base-char composite-1 composite-2"\~\c +\&.\|.\|.\~\c +.IB composite-n ] +is a composite glyph. +. +Glyphs like a lowercase \[lq]e\[rq] with an acute accent, +as in the word \[lq]caf\[e aa]\[rq], +can be expressed as +.BR "\[rs][e aa]" . +. +See subsection \[lq]Accents\[rq] below for a table of combining glyph +names. +. +. +.P +Unicode encodes far more characters than +.I groff +has glyph names for; +special character escape forms based on numerical code points enable +access to any of them. +. +Frequently used glyphs or glyph combinations can be stored in strings, +and new glyph names can be created +.I "ad hoc" +with the +.B char +request; +see +.MR groff @MAN7EXT@ . +. +. +.TP +.BI \[rs][u nnnn\c +.RI [ n\c +.RI [ n ]]\c +.B ] +is a Unicode numeric special character escape sequence. +. +Any Unicode code point can be accessed with four to six hexadecimal +digits, +with hexadecimal letters accepted in uppercase form only. +. +Thus, +.B \[rs][u02DA] +accesses the (spacing) ring accent, +producing \[lq]\[u02DA]\[rq]. +. +. +.\" Use "GNU troff" in this paragraph because the contrast with AT&T +.\" troff, which antedated Unicode, is important, and that contrast is +.\" obscured with the default empty command prefix on "troff". +.P +Unicode code points can be composed as well; +when they are, +GNU +.I troff \" GNU +requires NFD +(Normalization Form D), +where all Unicode glyphs are maximally decomposed. +. +(Exception: +precomposed characters in the Latin-1 supplement described above are +also accepted. +. +Do not count on this exception remaining in a future +GNU +.I troff \" GNU +that accepts UTF-8 input directly.) +. +. +Thus, +GNU +.I troff \" GNU +accepts +.RB \[lq]caf \[rs][\[aq]e] \[rq], +.RB \[lq]caf \[rs][e\~aa] \[rq], +and +.RB \[lq]caf \[rs][u0065_0301] \[rq], +as ways to input \[lq]caf\['e]\[rq]. +. +(Due to its legacy 8-bit encoding compatibility, +at present it also accepts +.RB \[lq]caf \[rs][u00E9] \[rq] +on ISO Latin-1 systems.) +. +. +.TP +.BI \[rs][u base-char\c +[\c +.BI _ combining-component\c +].\|.\|.] +constructs a composite glyph from Unicode numeric special character +escape sequences. +. +The code points of the base glyph and the combining components are each +expressed in hexadecimal, +with an underscore +.RB ( _ ) +separating each component. +. +Thus, +.B \[rs][u006E_0303] +produces \[lq]\[u006E_0303]\[rq]. +. +. +.TP +.BI \[rs][char nnn ] +expresses an eight-bit code point where +.I nnn +is the code point of the character, +a decimal number between 0 and\~255 +without leading zeroes. +. +This legacy numeric special character escape sequence is used to map +characters onto glyphs via the +.B trin +request in macro files loaded by +.MR grotty @MAN1EXT@ . +. +. +.\" ==================================================================== +.SH "Glyph tables" +.\" ==================================================================== +. +In this section, +.IR groff 's +glyph name repertoire is presented in tabular form. +. +The meanings of the columns are as follows. +. +. +.TP 8n +.B Output +shows the glyph as it appears on the device used to render this +document; +although it can have a notably different shape on other devices +(and is subject to user-directed translation and replacement), +.I groff +attempts reasonable equivalency on all output devices. +. +. +.TP +.B Input +shows the +.I groff +character +(ordinary or special) +that normally produces the glyph. +. +Some code points have multiple glyph names. +. +. +.TP +.B Unicode +is the code point notation for the glyph or combining glyph sequence as +described in subsection \[lq]Special character escape forms\[rq] above. +. +It corresponds to the standard notation for Unicode short identifiers +such that +.IR groff 's +.BI u nnnn +is equivalent to Unicode's +.RI U+ nnnn . +.\" And thereby hangs a tale... +.\" https://unicode.org/mail-arch/unicode-ml/y2005-m11/0060.html +. +. +.TP +.B Notes +describes the glyph, +elucidating the mnemonic value of the glyph name where possible. +. +. +.IP +A plus sign \[lq]+\[rq] indicates that the glyph name appears in the +AT&T +.I troff +user's manual, +CSTR\~#54 +(1992 revision). +. +When using the AT&T special character syntax +.BI \[rs]( xx\c +, widespread portability can be expected from such names. +. +. +.IP +Entries marked with \[lq]***\[rq] denote glyphs used for mathematical +purposes. +. +On typesetting devices, +such glyphs are typically drawn from a +.I special +font +(see +.MR groff_font @MAN5EXT@ ). +. +Often, +such glyphs lack bold or italic style forms or have metrics that look +incongruous in ordinary prose. +. +A few which are not uncommon in running text have \[lq]text +variants\[rq], +which should work better in that context. +. +Conversely, +a handful of glyphs that are normally drawn from a text font may be +required in mathematical equations. +. +Both sets of exceptions are noted in the tables where they appear +(\[lq]Logical symbols\[rq] and \[lq]Mathematical symbols\[rq]). +. +. +.\" ==================================================================== +.SS "Basic Latin" +.\" ==================================================================== +. +Apart from basic Latin characters with special mappings, +described in subsection \[lq]Fundamental character set\[rq] above, +a few others in that range have special character glyph names. +. +.\" XXX: I surmise that... +These were defined for ease of input on non-U.S.\& keyboards lacking +keycaps for them, +or for symmetry with other special character glyph names serving a +similar purpose. +. +. +.P +The vertical bar is overloaded; +the +.B \[rs][ba] +and +.B \[rs][or] +escape sequences may render differently. +. +See subsection \[lq]Mathematical symbols\[rq] below for special variants +of the plus, +minus, +and equals +signs normally drawn from this range. +. +. +.P +.TS +L L L Lx. +Output Input Unicode Notes +_ +.T& +L Lf(CR) L Lx. +\[dq] \e[dq] u0022 neutral double quote +\[sh] \e[sh] u0023 number sign +\[Do] \e[Do] u0024 dollar sign +\[aq] \e[aq] u0027 apostrophe, neutral single quote +\[sl] \e[sl] u002F slash, solidus + +\[at] \e[at] u0040 at sign +\[lB] \e[lB] u005B left square bracket +\[rs] \e[rs] u005C reverse solidus +\[rB] \e[rB] u005D right square bracket +\[ha] \e[ha] u005E circumflex, caret, \[lq]hat\[rq] +\[lC] \e[lC] u007B left brace +| | u007C bar +\[ba] \e[ba] u007C bar +\[or] \e[or] u007C bitwise or + +\[rC] \e[rC] u007D right brace +\[ti] \e[ti] u007E tilde +.TE +. +. +.\" ==================================================================== +.SS "Supplementary Latin letters" +.\" ==================================================================== +. +Historically, +.B \[rs][ss] +could be considered a ligature of \[lq]sz\[rq]. +. +An uppercase form is available as +.BR \[rs][u1E9E] , +but in the German language it is of specialized use; +\[ss] does +.I not +normally uppercase-transform to it, +but rather to \[lq]SS\[rq]. +. +\[lq]Lowercase f with hook\[rq] is also used as a function symbol; +see subsection \[lq]Mathematical symbols\[rq] below. +. +. +.P +.if t .ne 2v +.if n .ne 3v \" account for horizontal rule +.TS +L L L Lx. +Output Input Unicode Notes +_ +.T& +L Lf(CR) L Lx. +\[-D] \e[\-D] u00D0 uppercase eth +\[Sd] \e[Sd] u00F0 lowercase eth +\[TP] \e[TP] u00DE uppercase thorn +\[Tp] \e[Tp] u00FE lowercase thorn +\[ss] \e[ss] u00DF lowercase sharp s +\[.i] \e[.i] u0131 i without tittle +\[.j] \e[.j] u0237 j without tittle +\[Fn] \e[Fn] u0192 lowercase f with hook, function +\[/L] \e[/L] u0141 L with stroke +\[/l] \e[/l] u0142 l with stroke +\[/O] \e[/O] u00D8 O with stroke +\[/o] \e[/o] u00F8 o with stroke +.TE +. +. +.br +.if t .ne 4v +.if n .ne 5v \" account for horizontal rule +.\" ==================================================================== +.SS "Ligatures and digraphs" +.\" ==================================================================== +. +.TS +L L L Lx. +Output Input Unicode Notes +_ +.T& +L Lf(CR) L Lx. +\[ff] \e[ff] u0066_0066 ff ligature + +\[fi] \e[fi] u0066_0069 fi ligature + +\[fl] \e[fl] u0066_006C fl ligature + +\[Fi] \e[Fi] u0066_0066_0069 ffi ligature + +\[Fl] \e[Fl] u0066_0066_006C ffl ligature + +\[AE] \e[AE] u00C6 AE ligature +\[ae] \e[ae] u00E6 ae ligature +\[OE] \e[OE] u0152 OE ligature +\[oe] \e[oe] u0153 oe ligature +\[IJ] \e[IJ] u0132 IJ digraph +\[ij] \e[ij] u0133 ij digraph +.TE +. +. +.\" ==================================================================== +.SS Accents +.\" ==================================================================== +. +Normally, +the formatting of a special character advances the drawing position as +an ordinary character does. +. +.IR groff 's +.B composite +request designates a special character as combining. +. +The +.I composite.tmac +macro file, +loaded automatically by the default +.IR troffrc , +maps the following special characters to the combining characters shown +below. +. +The non-combining code point in parentheses is used when the special +character occurs in isolation +(compare +.RB \[lq] "caf\[rs][e aa]" \[rq] +and +.RB \[lq] "caf\[rs][aa]e" \[rq]). +. +. +.P +.if t .ne 3v +.if n .ne 4v \" account for horizontal rule +.TS +L L L Lx. +Output Input Unicode Notes +_ +.T& +L Lf(CR) L Lx. +\[a"] \e[a"] u030B (u02DD) double acute accent +\[a-] \e[a\-] u0304 (u00AF) macron accent +\[a.] \e[a.] u0307 (u02D9) dot accent +\[a^] \e[a\[ha]] u0302 (u005E) circumflex accent +\[aa] \e[aa] u0301 (u00B4) acute accent + +\[ga] \e[ga] u0300 (u0060) grave accent + +\[ab] \e[ab] u0306 (u02D8) breve accent +\[ac] \e[ac] u0327 (u00B8) cedilla accent +\[ad] \e[ad] u0308 (u00A8) dieresis accent +\[ah] \e[ah] u030C (u02C7) caron accent +\[ao] \e[ao] u030A (u02DA) ring accent +\[a~] \e[a\[ti]] u0303 (u007E) tilde accent +\[ho] \e[ho] u0328 (u02DB) hook accent +.TE +. +. +.\" ==================================================================== +.SS "Accented characters" +.\" ==================================================================== +. +All of these glyphs can be composed using combining glyph names as +described in subsection \[lq]Special character escape forms\[rq] above; +the names below are short aliases for convenience. +. +. +.P +.if t .ne 2v +.if n .ne 3v \" account for horizontal rule +.TS +L L L Lx. +Output Input Unicode Notes +_ +.T& +L Lf(CR) L Lx. +\['A] \e[\[aq]A] u0041_0301 A acute +\['C] \e[\[aq]C] u0043_0301 C acute +\['E] \e[\[aq]E] u0045_0301 E acute +\['I] \e[\[aq]I] u0049_0301 I acute +\['O] \e[\[aq]O] u004F_0301 O acute +\['U] \e[\[aq]U] u0055_0301 U acute +\['Y] \e[\[aq]Y] u0059_0301 Y acute +\['a] \e[\[aq]a] u0061_0301 a acute +\['c] \e[\[aq]c] u0063_0301 c acute +\['e] \e[\[aq]e] u0065_0301 e acute +\['i] \e[\[aq]i] u0069_0301 i acute +\['o] \e[\[aq]o] u006F_0301 o acute +\['u] \e[\[aq]u] u0075_0301 u acute +\['y] \e[\[aq]y] u0079_0301 y acute + +\[:A] \e[:A] u0041_0308 A dieresis +\[:E] \e[:E] u0045_0308 E dieresis +\[:I] \e[:I] u0049_0308 I dieresis +\[:O] \e[:O] u004F_0308 O dieresis +\[:U] \e[:U] u0055_0308 U dieresis +\[:Y] \e[:Y] u0059_0308 Y dieresis +\[:a] \e[:a] u0061_0308 a dieresis +\[:e] \e[:e] u0065_0308 e dieresis +\[:i] \e[:i] u0069_0308 i dieresis +\[:o] \e[:o] u006F_0308 o dieresis +\[:u] \e[:u] u0075_0308 u dieresis +\[:y] \e[:y] u0079_0308 y dieresis + +\[^A] \e[\[ha]A] u0041_0302 A circumflex +\[^E] \e[\[ha]E] u0045_0302 E circumflex +\[^I] \e[\[ha]I] u0049_0302 I circumflex +\[^O] \e[\[ha]O] u004F_0302 O circumflex +\[^U] \e[\[ha]U] u0055_0302 U circumflex +\[^a] \e[\[ha]a] u0061_0302 a circumflex +\[^e] \e[\[ha]e] u0065_0302 e circumflex +\[^i] \e[\[ha]i] u0069_0302 i circumflex +\[^o] \e[\[ha]o] u006F_0302 o circumflex +\[^u] \e[\[ha]u] u0075_0302 u circumflex + +\[`A] \e[\[ga]A] u0041_0300 A grave +\[`E] \e[\[ga]E] u0045_0300 E grave +\[`I] \e[\[ga]I] u0049_0300 I grave +\[`O] \e[\[ga]O] u004F_0300 O grave +\[`U] \e[\[ga]U] u0055_0300 U grave +\[`a] \e[\[ga]a] u0061_0300 a grave +\[`e] \e[\[ga]e] u0065_0300 e grave +\[`i] \e[\[ga]i] u0069_0300 i grave +\[`o] \e[\[ga]o] u006F_0300 o grave +\[`u] \e[\[ga]u] u0075_0300 u grave + +\[~A] \e[\[ti]A] u0041_0303 A tilde +\[~N] \e[\[ti]N] u004E_0303 N tilde +\[~O] \e[\[ti]O] u004F_0303 O tilde +\[~a] \e[\[ti]a] u0061_0303 a tilde +\[~n] \e[\[ti]n] u006E_0303 n tilde +\[~o] \e[\[ti]o] u006F_0303 o tilde + +\[vS] \e[vS] u0053_030C S caron +\[vs] \e[vs] u0073_030C s caron +\[vZ] \e[vZ] u005A_030C Z caron +\[vz] \e[vz] u007A_030C z caron + +\[,C] \e[,C] u0043_0327 C cedilla +\[,c] \e[,c] u0063_0327 c cedilla + +\[oA] \e[oA] u0041_030A A ring +\[oa] \e[oa] u0061_030A a ring +.TE +. +. +.\" ==================================================================== +.SS "Quotation marks" +.\" ==================================================================== +. +The neutral double quote, +often useful when documenting programming languages, +is also available as a special character for convenient embedding in +macro arguments; +see subsection \[lq]Fundamental character set\[rq] above. +. +. +.P +.if t .ne 2v +.if n .ne 3v \" account for horizontal rule +.TS +L L L Lx. +Output Input Unicode Notes +_ +.T& +L Lf(CR) L Lx. +\[Bq] \e[Bq] u201E low double comma quote +\[bq] \e[bq] u201A low single comma quote +\[lq] \e[lq] u201C left double quote +\[rq] \e[rq] u201D right double quote +\[oq] \e[oq] u2018 single opening (left) quote +\[cq] \e[cq] u2019 single closing (right) quote +\[aq] \e[aq] u0027 apostrophe, neutral single quote +\[dq] " u0022 neutral double quote +\[dq] \e[dq] u0022 neutral double quote +\[Fo] \e[Fo] u00AB left double chevron +\[Fc] \e[Fc] u00BB right double chevron +\[fo] \e[fo] u2039 left single chevron +\[fc] \e[fc] u203A right single chevron +.TE +. +. +.\" ==================================================================== +.SS Punctuation +.\" ==================================================================== +. +The Unicode name for U+00B7 is \[lq]middle dot\[rq], +which is unfortunately confusable with the +.I groff +mnemonic for the visually similar but semantically distinct +multiplication dot; +see subsection \[lq]Mathematical symbols\[rq] below. +. +. +.P +.if t .ne 2v +.if n .ne 3v \" account for horizontal rule +.TS +L L L Lx. +Output Input Unicode Notes +_ +.T& +L Lf(CR) L Lx. +\[r!] \e[r!] u00A1 inverted exclamation mark +\[r?] \e[r?] u00BF inverted question mark +\[pc] \e[pc] u00B7 centered period +\[em] \e[em] u2014 em-dash + +\[en] \e[en] u2013 en-dash +\[hy] \e[hy] u2010 hyphen + +.TE +. +. +.\" ==================================================================== +.SS Brackets +.\" ==================================================================== +. +On typesetting devices, +the bracket extensions are font-invariant glyphs; +that is, +they are rendered the same way regardless of font +(with a drawing escape sequence). +. +On terminals, +they are +.I not +font-invariant; +.I groff +maps them rather arbitrarily to U+23AA +(\[lq]curly bracket extension\[rq]). +. +In AT&T +.IR troff , +only one glyph was available to vertically extend +brackets, +braces, +and +parentheses: +.BR \[rs](bv . +. +. +. +.P +Not all devices supply bracket pieces that can be piled up with +.B \[rs]b +due to the restrictions of the escape's piling algorithm. +. +A general solution to build brackets out of pieces is the following +macro: +. +. +.RS +.EX +\&.\e" Make a pile centered vertically 0.5em above the baseline. +\&.\e" The first argument is placed at the top. +\&.\e" The pile is returned in string \[aq]pile\[aq]. +\&.eo +\&.de pile\-make +\&.\& nr pile\-wd 0 +\&.\& nr pile\-ht 0 +\&.\& ds pile\-args +\&.\& +\&.\& nr pile\-# \en[.$] +\&.\& while \en[pile\-#] \e{\e +\&.\& nr pile\-wd (\en[pile\-wd] >? \ew\[aq]\e$[\en[pile\-#]]\[aq]) +\&.\& nr pile\-ht +(\en[rst] \- \en[rsb]) +\&.\& as pile\-args \ev\[aq]\en[rsb]u\[aq]\e" +\&.\& as pile\-args \eZ\[aq]\e$[\en[pile\-#]]\[aq]\e" +\&.\& as pile\-args \ev\[aq]\-\en[rst]u\[aq]\e" +\&.\& nr pile\-# \-1 +\&.\& \e} +\&.\& +\&.\& ds pile \ev\[aq](\-0.5m + (\en[pile\-ht]u / 2u))\[aq]\e" +\&.\& as pile \e*[pile\-args]\e" +\&.\& as pile \ev\[aq]((\en[pile\-ht]u / 2u) + 0.5m)\[aq]\e" +\&.\& as pile \eh\[aq]\en[pile\-wd]u\[aq]\e" +\&.. +\&.ec +.EE +.RE +. +. +.P +Another complication is the fact that some glyphs which represent +bracket pieces in AT&T +.I troff +can be used for other mathematical symbols as well, +for example +.B \[rs](lf +and +.BR \[rs](rf , +which provide the floor operator. +. +Some output devices, +such as +.BR dvi , +don't unify such glyphs. +. +For this reason, +the glyphs +.BR \[rs][lf] , +.BR \[rs][rf] , +.BR \[rs][lc] , +and +.B \[rs][rc] +are not unified with similar-looking bracket pieces. +. +In +.IR groff , +only glyphs with long names are guaranteed to pile up correctly for all +devices\[em]provided those glyphs are available. +. +. +.P +.if t .ne 2v +.if n .ne 3v \" account for horizontal rule +.TS +L L L Lx. +Output Input Unicode Notes +_ +.T& +L Lf(CR) L Lx. +\[lB] [ u005B left square bracket +\[lB] \e[lB] u005B left square bracket +\[rB] ] u005D right square bracket +\[rB] \e[rB] u005D right square bracket +\[lC] { u007B left brace +\[lC] \e[lC] u007B left brace +\[rC] } u007D right brace +\[rC] \e[rC] u007D right brace +\[la] \e[la] u27E8 left angle bracket +\[ra] \e[ra] u27E9 right angle bracket +\[bv] \e[bv] u23AA brace vertical extension + *** +\[braceex] \e[braceex] u23AA brace vertical extension + +\[bracketlefttp] \e[bracketlefttp] u23A1 left square bracket top +\[bracketleftex] \e[bracketleftex] u23A2 left square bracket extension +\[bracketleftbt] \e[bracketleftbt] u23A3 left square bracket bottom + +\[bracketrighttp] \e[bracketrighttp] u23A4 right square bracket top +\[bracketrightex] \e[bracketrightex] u23A5 right square bracket extension +\[bracketrightbt] \e[bracketrightbt] u23A6 right square bracket bottom + +\[lt] \e[lt] u23A7 left brace top + +\[lk] \e[lk] u23A8 left brace middle + +\[lb] \e[lb] u23A9 left brace bottom + +\[bracelefttp] \e[bracelefttp] u23A7 left brace top +\[braceleftmid] \e[braceleftmid] u23A8 left brace middle +\[braceleftbt] \e[braceleftbt] u23A9 left brace bottom +\[braceleftex] \e[braceleftex] u23AA left brace extension + +\[rt] \e[rt] u23AB right brace top + +\[rk] \e[rk] u23AC right brace middle + +\[rb] \e[rb] u23AD right brace bottom + +\[bracerighttp] \e[bracerighttp] u23AB right brace top +\[bracerightmid] \e[bracerightmid] u23AC right brace middle +\[bracerightbt] \e[bracerightbt] u23AD right brace bottom +\[bracerightex] \e[bracerightex] u23AA right brace extension + +\[parenlefttp] \e[parenlefttp] u239B left parenthesis top +\[parenleftex] \e[parenleftex] u239C left parenthesis extension +\[parenleftbt] \e[parenleftbt] u239D left parenthesis bottom +\[parenrighttp] \e[parenrighttp] u239E right parenthesis top +\[parenrightex] \e[parenrightex] u239F right parenthesis extension +\[parenrightbt] \e[parenrightbt] u23A0 right parenthesis bottom +.TE +. +. +.br +.if t .ne 4v +.if n .ne 5v \" account for horizontal rule +.\" ==================================================================== +.SS Arrows +.\" ==================================================================== +. +.TS +L L L Lx. +Output Input Unicode Notes +_ +.T& +L Lf(CR) L Lx. +\[<-] \e[<\-] u2190 horizontal arrow left + +\[->] \e[\->] u2192 horizontal arrow right + +\[<>] \e[<>] u2194 bidirectional horizontal arrow +\[da] \e[da] u2193 vertical arrow down + +\[ua] \e[ua] u2191 vertical arrow up + +\[va] \e[va] u2195 bidirectional vertical arrow +\[lA] \e[lA] u21D0 horizontal double arrow left +\[rA] \e[rA] u21D2 horizontal double arrow right +\[hA] \e[hA] u21D4 bidirectional horizontal double arrow +\[dA] \e[dA] u21D3 vertical double arrow down +\[uA] \e[uA] u21D1 vertical double arrow up +\[vA] \e[vA] u21D5 bidirectional vertical double arrow +\[an] \e[an] u23AF horizontal arrow extension +.TE +. +. +.\" ==================================================================== +.SS "Rules and lines" +.\" ==================================================================== +. +On typesetting devices, +the font-invariant glyphs +(see subsection \[lq]Brackets\[rq] above) +.BR \[rs][br] , +.BR \[rs][ul] , +and +.B \[rs][rn] +form corners when adjacent; +they can be used to build boxes. +. +On terminal devices, +they are mapped as shown in the table. +. +The Unicode-derived names of these three glyphs are approximations. +. +. +.P +The input character +.B _ +always accesses the underscore glyph in a font; +.\" unless one isn't available, but this seems to be only a theoretical +.\" concern--what font doesn't support every ASCII codepoint these days? +.BR \[rs][ul] , +by contrast, +may be font-invariant on typesetting devices. +. +. +.P +The baseline rule +.B \[rs][ru] +is a font-invariant glyph, +namely a rule of one-half em. +. +. +.P +In AT&T +.IR troff , \" AT&T +.B \[rs][rn] +also served as a one\~en extension of the square root symbol. +. +.I groff +favors +.B \[rs][radicalex] +for this purpose; +see subsection \[lq]Mathematical symbols\[rq] below. +. +. +.P +.if t .ne 2v +.if n .ne 3v \" account for horizontal rule +.TS +L L L Lx. +Output Input Unicode Notes +_ +.T& +L Lf(CR) L Lx. +| | u007C bar +\[ba] \e[ba] u007C bar +\[br] \e[br] u2502 box rule + +\&_ \&_ u005F underscore, low line + +\[ul] \e[ul] --- underrule + +\[rn] \e[rn] u203E overline + +\[ru] \e[ru] --- baseline rule + +\[bb] \e[bb] u00A6 broken bar +\[sl] / u002F slash, solidus + +\[sl] \e[sl] u002F slash, solidus + +\[rs] \e[rs] u005C reverse solidus +.TE +. +. +.br +.if t .ne 4v +.if n .ne 5v \" account for horizontal rule +.\" ==================================================================== +.SS "Text markers" +.\" ==================================================================== +. +.TS +L L L Lx. +Output Input Unicode Notes +_ +.T& +L Lf(CR) L Lx. +\[ci] \e[ci] u25CB circle + +\[bu] \e[bu] u2022 bullet + +\[dg] \e[dg] u2020 dagger + +\[dd] \e[dd] u2021 double dagger + +\[lz] \e[lz] u25CA lozenge, diamond +\[sq] \e[sq] u25A1 square + +\[ps] \e[ps] u00B6 pilcrow sign +\[sc] \e[sc] u00A7 section sign + +\[lh] \e[lh] u261C hand pointing left + +\[rh] \e[rh] u261E hand pointing right + +\[at] @ u0040 at sign +\[at] \e[at] u0040 at sign +\[sh] # u0023 number sign +\[sh] \e[sh] u0023 number sign +\[CR] \e[CR] u21B5 carriage return +\[OK] \e[OK] u2713 check mark +.TE +. +.\" ==================================================================== +.SS "Legal symbols" +.\" ==================================================================== +. +The Bell System logo is not supported in +.IR groff . +. +. +.P +.if t .ne 2v +.if n .ne 3v \" account for horizontal rule +.TS +L L L Lx. +Output Input Unicode Notes +_ +.T& +L Lf(CR) L Lx. +\[co] \e[co] u00A9 copyright sign + +\[rg] \e[rg] u00AE registered sign + +\[tm] \e[tm] u2122 trade mark sign +\[bs] \e[bs] --- Bell System logo + +.TE +. +. +.br +.if t .ne 4v +.if n .ne 5v \" account for horizontal rule +.\" ==================================================================== +.SS "Currency symbols" +.\" ==================================================================== +. +.TS +L L L Lx. +Output Input Unicode Notes +_ +.T& +L Lf(CR) L Lx. +\[Do] $ u0024 dollar sign +\[Do] \e[Do] u0024 dollar sign +\[ct] \e[ct] u00A2 cent sign + +\[eu] \e[eu] u20AC Euro sign +\[Eu] \e[Eu] u20AC variant Euro sign +\[Ye] \e[Ye] u00A5 yen sign +\[Po] \e[Po] u00A3 pound sign +\[Cs] \e[Cs] u00A4 currency sign +.TE +. +. +.br +.if t .ne 4v +.if n .ne 5v \" account for horizontal rule +.\" ==================================================================== +.SS Units +.\" ==================================================================== +. +.TS +L L L Lx. +Output Input Unicode Notes +_ +.T& +L Lf(CR) L Lx. +\[de] \e[de] u00B0 degree sign + +\[%0] \e[%0] u2030 per thousand, per mille sign +\[fm] \e[fm] u2032 arc minute sign, foot mark + +\[sd] \e[sd] u2033 arc second sign +\[mc] \e[mc] u00B5 micro sign +\[Of] \e[Of] u00AA feminine ordinal indicator +\[Om] \e[Om] u00BA masculine ordinal indicator +.TE +. +. +.\" ==================================================================== +.SS "Logical symbols" +.\" ==================================================================== +. +The variants of the not sign may differ in appearance or spacing +depending on the device and font selected. +. +Unicode does not encode a discrete \[lq]bitwise or\[rq] sign: +on typesetting devices, +it is drawn shorter than the bar, +about the same height as a capital letter. +. +Terminal devices unify +.B \[rs][ba] +and +.BR \[rs][or] . +. +. +.P +.if t .ne 2v +.if n .ne 3v \" account for horizontal rule +.TS +L L L Lx. +Output Input Unicode Notes +_ +.T& +L Lf(CR) L Lx. +\[AN] \e[AN] u2227 logical and +\[OR] \e[OR] u2228 logical or +\[no] \e[no] u00AC logical not + *** +\[tno] \e[tno] u00AC text variant of \f[B]\e[no]\f[] +\[te] \e[te] u2203 there exists +\[fa] \e[fa] u2200 for all +\[st] \e[st] u220B such that +\[3d] \e[3d] u2234 therefore +\[tf] \e[tf] u2234 therefore +| | u007C bar +\[or] \e[or] u007C bitwise or + +.TE +. +. +.\" ==================================================================== +.SS "Mathematical symbols" +.\" ==================================================================== +. +.B \[rs][Fn] +also appears in subsection \[lq]Supplementary Latin letters\[rq] above. +. +Observe the two varieties of the +plus-minus, +multiplication, +and division signs; +.BR \[rs][+\-] , +.BR \[rs][mu] , +and +.B \[rs][di] +are normally drawn from the special font, +but have text font variants. +. +Also be aware of three glyphs available in special font variants that +are normally drawn from text fonts: +the plus, +minus, +and equals signs. +. +These variants may differ in appearance or spacing depending on the +device and font selected. +. +. +.P +In AT&T +.IR troff , +.B \[rs](rn +(\[lq]root en extender\[rq]) +served as the horizontal extension of the radical +(square root) +sign, +.BR \[rs](sr , +and was drawn at the maximum height of the typeface's bounding box; +this enabled the special character to double as an overline +(see subsection \[lq]Rules and lines\[rq] above). +. +A contemporary font's radical sign might not ascend to such an extreme. +. +In +.IR groff , +you can instead use +.B \[rs][radicalex] +to continue the radical sign +.BR \[rs][sr] ; +these special characters are intended for use with text fonts. +. +.B \[rs][sqrt] +and +.B \[rs][sqrtex] +are their counterparts with mathematical spacing. +. +. +.P +.if t .ne 2v +.if n .ne 3v \" account for horizontal rule +.TS +L L L Lx. +Output Input Unicode Notes +_ +.T& +L Lf(CR) L Lx. +\[12] \e[12] u00BD one half symbol + +\[14] \e[14] u00BC one quarter symbol + +\[34] \e[34] u00BE three quarters symbol + +\[18] \e[18] u215B one eighth symbol +\[38] \e[38] u215C three eighths symbol +\[58] \e[58] u215D five eighths symbol +\[78] \e[78] u215E seven eighths symbol +\[S1] \e[S1] u00B9 superscript one +\[S2] \e[S2] u00B2 superscript two +\[S3] \e[S3] u00B3 superscript three + ++ + u002B plus +\[pl] \e[pl] u002B special variant of plus + *** +\- \e[\-] u002D minus +\[mi] \e[mi] u2212 special variant of minus + *** +\[-+] \e[\-+] u2213 minus-plus +\[+-] \e[+\-] u00B1 plus-minus + *** +\[t+-] \e[t+\-] u00B1 text variant of \f[B]\e[+\-]\f[] +\[md] \e[md] u22C5 multiplication dot +\[mu] \e[mu] u00D7 multiplication sign + *** +\[tmu] \e[tmu] u00D7 text variant of \f[B]\e[mu]\f[] +\[c*] \e[c*] u2297 circled times +\[c+] \e[c+] u2295 circled plus +\[di] \e[di] u00F7 division sign + *** +\[tdi] \e[tdi] u00F7 text variant of \f[B]\e[di]\f[] +\[f/] \e[f/] u2044 fraction slash +* * u002A asterisk +\[**] \e[**] u2217 mathematical asterisk + + +\[<=] \e[<=] u2264 less than or equal to + +\[>=] \e[>=] u2265 greater than or equal to + +\[<<] \e[<<] u226A much less than +\[>>] \e[>>] u226B much greater than +\&= \&= u003D equals +\[eq] \e[eq] u003D special variant of equals + *** +\[!=] \e[!=] u003D_0338 not equals + +\[==] \e[==] u2261 equivalent + +\[ne] \e[ne] u2261_0338 not equivalent +\[=~] \e[=\[ti]] u2245 approximately equal to +\[|=] \e[|=] u2243 asymptotically equal to + +\[ti] \e[ti] u007E tilde + +\[ap] \e[ap] u223C similar to, tilde operator + +\[~~] \e[\[ti]\[ti]] u2248 almost equal to +\[~=] \e[\[ti]=] u2248 almost equal to +\[pt] \e[pt] u221D proportional to + + +\[es] \e[es] u2205 empty set + +\[mo] \e[mo] u2208 element of a set + +\[nm] \e[nm] u2208_0338 not element of set +\[sb] \e[sb] u2282 proper subset + +\[nb] \e[nb] u2282_0338 not subset +\[sp] \e[sp] u2283 proper superset + +\[nc] \e[nc] u2283_0338 not superset +\[ib] \e[ib] u2286 subset or equal + +\[ip] \e[ip] u2287 superset or equal + +\[ca] \e[ca] u2229 intersection, cap + +\[cu] \e[cu] u222A union, cup + + +\[/_] \e[/_] u2220 angle +\[pp] \e[pp] u22A5 perpendicular +\[is] \e[is] u222B integral + +\[integral] \e[integral] u222B integral *** +\[sum] \e[sum] u2211 summation *** +\[product] \e[product] u220F product *** +\[coproduct] \e[coproduct] u2210 coproduct *** +\[gr] \e[gr] u2207 gradient + +\[sr] \e[sr] u221A radical sign, square root + +\[rn] \e[rn] u203E overline + +\[radicalex] \e[radicalex] --- radical extension +\[sqrt] \e[sqrt] u221A radical sign, square root *** +\[sqrtex] \e[sqrtex] --- radical extension *** + +\[lc] \e[lc] u2308 left ceiling + +\[rc] \e[rc] u2309 right ceiling + +\[lf] \e[lf] u230A left floor + +\[rf] \e[rf] u230B right floor + + +\[if] \e[if] u221E infinity + +\[Ah] \e[Ah] u2135 aleph symbol +\[Fn] \e[Fn] u0192 lowercase f with hook, function +\[Im] \e[Im] u2111 blackletter I, imaginary part +\[Re] \e[Re] u211C blackletter R, real part +\[wp] \e[wp] u2118 Weierstrass p +\[pd] \e[pd] u2202 partial differential +\[-h] \e[\-h] u210F h bar +\[hbar] \e[hbar] u210F h bar +.TE +. +. +.\" ==================================================================== +.SS "Greek glyphs" +.\" ==================================================================== +. +These glyphs are intended for technical use, +not for typesetting Greek language text; +normally, +the uppercase letters have upright shape, +and the lowercase ones are slanted. +. +. +.P +.if t .ne 2v +.if n .ne 3v \" account for horizontal rule +.TS +L L L Lx. +Output Input Unicode Notes +_ +.T& +L Lf(CR) L Lx. +\[*A] \e[*A] u0391 uppercase alpha + +\[*B] \e[*B] u0392 uppercase beta + +\[*G] \e[*G] u0393 uppercase gamma + +\[*D] \e[*D] u0394 uppercase delta + +\[*E] \e[*E] u0395 uppercase epsilon + +\[*Z] \e[*Z] u0396 uppercase zeta + +\[*Y] \e[*Y] u0397 uppercase eta + +\[*H] \e[*H] u0398 uppercase theta + +\[*I] \e[*I] u0399 uppercase iota + +\[*K] \e[*K] u039A uppercase kappa + +\[*L] \e[*L] u039B uppercase lambda + +\[*M] \e[*M] u039C uppercase mu + +\[*N] \e[*N] u039D uppercase nu + +\[*C] \e[*C] u039E uppercase xi + +\[*O] \e[*O] u039F uppercase omicron + +\[*P] \e[*P] u03A0 uppercase pi + +\[*R] \e[*R] u03A1 uppercase rho + +\[*S] \e[*S] u03A3 uppercase sigma + +\[*T] \e[*T] u03A4 uppercase tau + +\[*U] \e[*U] u03A5 uppercase upsilon + +\[*F] \e[*F] u03A6 uppercase phi + +\[*X] \e[*X] u03A7 uppercase chi + +\[*Q] \e[*Q] u03A8 uppercase psi + +\[*W] \e[*W] u03A9 uppercase omega + + +\[*a] \e[*a] u03B1 lowercase alpha + +\[*b] \e[*b] u03B2 lowercase beta + +\[*g] \e[*g] u03B3 lowercase gamma + +\[*d] \e[*d] u03B4 lowercase delta + +\[*e] \e[*e] u03B5 lowercase epsilon + +\[*z] \e[*z] u03B6 lowercase zeta + +\[*y] \e[*y] u03B7 lowercase eta + +\[*h] \e[*h] u03B8 lowercase theta + +\[*i] \e[*i] u03B9 lowercase iota + +\[*k] \e[*k] u03BA lowercase kappa + +\[*l] \e[*l] u03BB lowercase lambda + +\[*m] \e[*m] u03BC lowercase mu + +\[*n] \e[*n] u03BD lowercase nu + +\[*c] \e[*c] u03BE lowercase xi + +\[*o] \e[*o] u03BF lowercase omicron + +\[*p] \e[*p] u03C0 lowercase pi + +\[*r] \e[*r] u03C1 lowercase rho + +\[*s] \e[*s] u03C3 lowercase sigma + +\[*t] \e[*t] u03C4 lowercase tau + +\[*u] \e[*u] u03C5 lowercase upsilon + +\[*f] \e[*f] u03D5 lowercase phi + +\[*x] \e[*x] u03C7 lowercase chi + +\[*q] \e[*q] u03C8 lowercase psi + +\[*w] \e[*w] u03C9 lowercase omega + + +\[+e] \e[+e] u03F5 variant epsilon (lunate) +\[+h] \e[+h] u03D1 variant theta (cursive form) +\[+p] \e[+p] u03D6 variant pi (similar to omega) +\[+f] \e[+f] u03C6 variant phi (curly shape) +\[ts] \e[ts] u03C2 terminal lowercase sigma + +.TE +. +. +.br +.if t .ne 4v +.if n .ne 5v \" account for horizontal rule +.\" ==================================================================== +.SS "Playing card symbols" +.\" ==================================================================== +. +.TS +L L L Lx. +Output Input Unicode Notes +_ +.T& +L Lf(CR) L Lx. +\[CL] \e[CL] u2663 solid club suit +\[SP] \e[SP] u2660 solid spade suit +\[HE] \e[HE] u2665 solid heart suit +\[DI] \e[DI] u2666 solid diamond suit +.TE +. +. +.\" ==================================================================== +.SH History +.\" ==================================================================== +. +A consideration of the typefaces originally available to AT&T +.I nroff \" AT&T +and +.I troff \" AT&T +illuminates many conventions that one might regard as idiosyncratic +fifty years afterward. +. +(See section \[lq]History\[rq] of +.MR roff @MAN7EXT@ +for more context.) +. +The face used by the Teletype Model\~37 terminals of the Murray Hill +Unix Room was based on ASCII, +but assigned multiple meanings to several code points, +as suggested by that standard. +. +Decimal 34 +.RB ( \[dq] ) +served as a dieresis accent and neutral double quotation mark; +decimal 39 +.RB ( \[aq] ) +as an acute accent, +apostrophe, +and closing (right) single quotation mark; +decimal 45 +.RB ( \[-] ) +as a hyphen and a minus sign; +decimal 94 +.RB ( \[ha] ) +as a circumflex accent and caret; +decimal 96 +.RB ( \[ga] ) +as a grave accent and opening (left) single quotation mark; +and decimal 126 +.RB ( \[ti] ) +as a tilde accent and +(with a half-line motion) +swung dash. +. +The Model\~37 bore an optional extended character set offering upright +Greek letters and several mathematical symbols; +these were documented as early as the +.IR kbd (VII) +man page of the +(First Edition) +.I Unix Programmer's Manual. +. +. +.br +.ne 2v +.P +At the time Graphic Systems delivered the C/A/T phototypesetter to AT&T, +the ASCII character set was not considered a standard basis for a glyph +repertoire by traditional typographers. +. +In the stock Times roman, +italic, +and bold styles available, +several ASCII characters were not present at all, +nor was most of the Teletype's extended character set. +. +AT&T commissioned a \[lq]special\[rq] font to ensure no loss of +repertoire. +. +. +.br +.ne 2v +.P +A representation of the coverage of the C/A/T's text fonts follows. +. +The glyph resembling an underscore is a baseline rule, +and that resembling a vertical line is a box rule. +. +In italics, +the box rule was not slanted. +. +We also observe that the hyphen and minus sign were already +\[lq]de-unified\[rq] by the fonts provided; +a decision whither to map an input \[lq]\-\[rq] therefore had to be +taken. +. +. +.br +.if t .ne 5v +.if t .ne 7v \" account for box border +.P +.TS +center box; +Lf(R). +A B C D E F G H I J K L M N O P Q R S T U V W X Y Z +a b c d e f g h i j k l m n o p q r s t u v w x y z +0 1 2 3 4 5 6 7 8 9 \[fi] \[fl] \[Fi] \[Fl] +! $ % & ( ) \[oq] \[cq] * + \- . , / : ; = ? [ ] \[br] +\[bu] \[sq] \[em] \[hy] \[ru] \[14] \[12] \[34] \ +\[de] \[dg] \[fm] \[ct] \[rg] \[co] +.TE +. +. +.P +The special font supplied the missing ASCII and Teletype extended +glyphs, +among several others. +. +The plus, +minus, +and equals signs appeared in the special font despite availability in +text fonts \[lq]to insulate the appearance of equations from the choice +of standard [read: text] fonts\[rq]\[em]a priority since +.I troff \" AT&T +was turned to the task of mathematical typesetting as soon as it was +developed. +. +. +.P +We note that AT&T took the opportunity to de-unify the apostrophe/right +single quotation mark from the acute accent +(a choice ISO later duplicated in its 8859 series of standards). +. +A slash intended to be mirror-symmetric with the backslash was also +included, +as was the Bell System logo; +we do not attempt to depict the latter. +. +. +.br +.if t .ne 5v +.if t .ne 7v \" account for box border +.P +.TS +center box; +Lf(I),Lf(R). +\[*a] \[*b] \[*g] \[*d] \[*e] \[*z] \[*y] \[*h] \[*i] \[*k] \[*l] \ +\[*m] \[*n] \[*c] \[*o] \[*p] \[*r] \[*s] \[ts] \[*t] \[*u] \[*f] \ +\[*x] \[*q] \[*w] +\[*G] \[*D] \[*H] \[*L] \[*C] \[*P] \[*S] \[*U] \[*F] \[*Q] \[*W] +\[dq] \[aa] \[rs] \[ha] \[ul] \[ga] \[ti] \[sl] < > { } # @ \ +\[pl] \[mi] \[eq] \[**] +.\" We use \[radicalex] instead of \[rn] for more reliable simulation of +.\" the typeface shown in Table I of CSTR #54 (1976); see subsection +.\" "Mathematical symbols" above. +\[>=] \[<=] \[==] \[~=] \[ap] \[!=] \ +\[ua] \[da] \[<-] \[->] \[mu] \[di] \[+-] \ +\[if] \[pd] \[gr] \[no] \[is] \[pt] \[sr] \[radicalex] \ +\[cu] \[ca] \[sb] \[sp] \[ib] \[ip] \[es] \[mo] +\[sc] \[dd] \[lh] \[rh] \[or] \[ci] \ +\[lt] \[lb] \[rt] \[rb] \[lk] \[rk] \[bv] \[lf] \[rf] \[lc] \[rc] +.TE +. +. +.P +One ASCII character as rendered by the Model 37 was apparently +abandoned. +. +That device printed decimal 124 (\[or]) as a broken vertical line, +like Unicode U+00A6 (\[bb]). +. +No equivalent was available on the C/A/T; +the box rule +.BR \[rs][br] , +brace vertical extension +.\" CSTR #54 (1976 edition) called this the "bold vertical", probably +.\" because it was thicker than the box rule and matched the thickness +.\" of the bracket pieces \(lt, \(lb, \(rt, \(rb, \(lk, \(rk, and so on. +.\" Saying "bold" could be misleading because it appeared only in the +.\" special font, not a bold text font. +.BR \[rs][bv] , +and \[lq]or\[rq] operator +.B \[rs][or] +were used as contextually appropriate. +. +. +.P +.\" In the Holt, Reinhart, Winston edition of the _Unix Programmer's +.\" Manual_, Revised and Expanded Version, Volume 2 (1983), the square +.\" \(sq in Times bold is _not_ shown as filled on page 226. +.\" +.\" ...but in the AT&T USG Unix 4.0 manual (ca. 1981), typeset on the +.\" Autologic APS-5, the Times bold \(sq _is_ filled. +.\" +.\" https://www.tuhs.org/Archive/Documentation/Manuals/Unix_4.0/ +.\" Volume_1/00_Annotated_Table_of_Contents.pdf +.\" Volume_1/C.1.2_NROFF_TROFF_Users_Manual.pdf +.\" -- GBR +Devices supported by AT&T device-independent +.I troff +exhibited some differences in glyph detail. +. +For example, +on the Autologic APS-5 phototypesetter, +the square +.B \[rs](sq +became filled in the Times bold face. +. +. +.\" ==================================================================== +.SH Files +.\" ==================================================================== +. +The files below are loaded automatically by the default +.IR troffrc . +. +. +.TP +.I @MACRODIR@/\:\%composite\:.tmac +assigns alternate mappings for identifiers after the first in a +composite special character escape sequence. +. +See subsection \[lq]Accents\[rq] above. +. +. +.TP +.I @MACRODIR@/\:\%fallbacks\:.tmac +defines fallback mappings for Unicode code points such as the increment +sign (U+2206) and upper- and lowercase Roman numerals. +. +. +.\" ==================================================================== +.SH Authors +.\" ==================================================================== +. +This document was written by +.MT jjc@\:jclark\:.com +James Clark +.ME , +with additions by +.MT wl@\:gnu\:.org +Werner Lemberg +.ME +and +.MT groff\-bernd\:.warken\-72@\:web\:.de +Bernd Warken +.ME , +revised to use +.MR @g@tbl @MAN1EXT@ +by +.MT esr@\:thyrsus\:.com +Eric S.\& Raymond +.ME , +and largely rewritten by +.MT g.branden\:.robinson@\:gmail\:.com +G.\& Branden Robinson +.ME . +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +.IR "Groff: The GNU Implementation of troff" , +by Trent A.\& Fisher and Werner Lemberg, +is the primary +.I groff +manual. +. +Section \[lq]Using Symbols\[rq] may be of particular note. +. +You can browse it interactively with \[lq]info \[aq](groff) Using +Symbols\[aq]\[rq]. +. +. +.P +\[lq]An extension to the +.I troff +character set for Europe\[rq], +E.G.\& Keizer, +K.J.\& Simonsen, +J.\& Akkerhuis; +EUUG Newsletter, +Volume 9, +No.\& 2, +Summer 1989 +. +. +.P +.UR http://\:www\:.unicode\:.org +The Unicode Standard +.UE +. +. +.br +.ne 2v +.P +.UR https://\:www\:.aivosto\:.com/\:articles/\:charsets\-7bit\:.html +\[lq]7-bit Character Sets\[rq] +.UE +by Tuomas Salste documents the inherent ambiguity and configurable code +points of the ASCII encoding standard. +. +. +.P +\[lq]Nroff/Troff User's Manual\[rq] +by Joseph F.\& Ossanna, +1976, +AT&T Bell Laboratories Computing Science Technical Report No.\& 54, +features two tables that throw light on the glyph repertoire available +to \[lq]typesetter +.IR roff \[rq] +when it was first written. +. +Be careful of re-typeset versions of this document that can be found on +the Internet. +. +Some do not accurately represent the original document: +several glyphs are obviously missing. +. +More subtly, +lowercase Greek letters are rendered upright, +not slanted as they appeared in the C/A/T's special font and as expected +by +.I troff \" AT&T +users. +. +. +.P +.MR groff_rfc1345 @MAN7EXT@ +describes an alternative set of special character glyph names, +which extends and in some cases overrides the definitions listed above. +. +. +.P +.MR groff @MAN1EXT@ , +.MR troff @MAN1EXT@ , +.MR groff @MAN7EXT@ +. +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_groff_char_7_man_C] +.do rr *groff_groff_char_7_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" tab-width: 20 +.\" End: +.\" vim: set filetype=groff tabstop=20 textwidth=72: diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man new file mode 100644 index 0000000..0d25cb6 --- /dev/null +++ b/man/groff_diff.7.man @@ -0,0 +1,6188 @@ +'\" e +.TH groff_diff @MAN7EXT@ "@MDATE@" "groff @VERSION@" +.SH Name +groff_diff \- differences between GNU +.I roff +and AT&T +.I troff +. +. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 1989-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_diff_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 +. +. +.\" ==================================================================== +.\" Local definitions +.\" ==================================================================== +. +.\" define a string tx for the TeX logo +.ie t .ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X +.el .ds tx TeX +. +. +.\" from old groff_out.man +.ie \n(.g \ +. ds ic \/ +.el \ +. ds ic \^ +. +. +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +The GNU +.I roff +text processing system, +.IR groff , +is an extension of AT&T +.IR troff , \" AT&T +the typesetting system originating in Unix systems of the 1970s. +. +.I groff +removes many arbitrary limitations and adds features, +both to the input language and to the page description language output +by the +.I troff \" generic +formatter. +. +Differences arising from +.IR groff 's +implementation of AT&T +.I troff \" AT&T +features are also noted. +. +See +.MR roff @MAN7EXT@ +for background. +. +. +.\" ==================================================================== +.SH Language +.\" ==================================================================== +. +GNU +.I troff \" GNU +features identifiers of arbitrary length; +supports color output, +non-integral type sizes, +and user-defined characters; +adds more conditional expression operators; +recognizes additional scaling units and numeric operators; +enables general file I/O +(in \[lq]unsafe mode\[rq] only); +and exposes more formatter state. +. +. +.\" ==================================================================== +.SS "Long names" +.\" ==================================================================== +. +GNU +.I troff \" GNU +introduces many new requests; +with three exceptions +.RB ( cp , +.BR do , +.BR rj ), +they have names longer than two characters. +. +The names of registers, +fonts, +strings/\:macros/\:diversions, +environments, +special characters, +streams, +and colors can be of any length. +. +Anywhere AT&T +.I troff \" AT&T +supports a parameterized escape sequence that uses an opening +parenthesis \[lq](\[rq] to introduce a two-character argument, +.I groff +supports a square-bracketed form \[lq][]\[rq] where the argument +within can be of arbitrary length. +. +. +.\" ==================================================================== +.SS "Font families, abstract styles, and translation" +.\" ==================================================================== +. +GNU +.I troff \" GNU +can group text typefaces into +.I families +containing each of the styles +.RB \[lq] R \[rq], +.RB \[lq] I \[rq], +.RB \[lq] B \[rq], +and +.RB \[lq] BI \[rq]. +. +So that a document need not be coupled to a specific font family, +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." +. +A document can +.I translate, +or remap, +fonts with the +.B ftr +request. +. +. +.P +Applying the requests +.BR cs , +.BR bd , +.BR tkf , +.BR uf , +or +.B \%fspecial +to an abstract style affects the member of the default family +corresponding to that style. +. +The default family can be set with the +.B fam +request or +.B \-f +command-line option. +. +The +.B styles +directive in the output device's +.I DESC +file controls which mounting positions +(if any) +are initially associated with abstract styles rather than fonts, +and the +.B sty +request can update this association. +. +. +.\" ==================================================================== +.SS 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 figures are drawn, +and the +.I fill color, +which paints the interior of filled geometric figures. +. +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. +. +. +.\" ==================================================================== +.SS "Fractional type sizes and new scaling units" +.\" ==================================================================== +. +.\" BEGIN Keep (roughly) parallel with groff.texi node "Using Fractional +.\" Type Sizes". +AT&T +.I troff \" AT&T +interpreted all type size measurements in points. +. +Combined with integer arithmetic, +this design choice made it impossible to support, +for instance, +ten and a half-point type. +. +In GNU +.IR troff , \" GNU +an output device can select a scaling factor that subdivides a point +into \[lq]scaled points\[rq]. +. +A type size expressed in scaled points can thus represent a non-integral +type size. +. +. +.P +A +.I scaled point +is equal to +.RI 1/ sizescale +points, +where +.I sizescale +is specified in the device description file, +.IR DESC , +and defaults to\~1; +see +.MR groff_font @MAN5EXT@ . +. +Requests and escape sequences in GNU +.I troff \" GNU +interpret arguments that represent a type size in points, +which the formatter multiplies by +.I sizescale +and converts to an integer. +. +Arguments treated in this way comprise those to the escape sequences +.B \[rs]H +and +.BR \[rs]s , +to the request +.BR ps , +the third argument to the +.B cs +request, +and the second and fourth arguments to the +.B tkf +request. +. +Scaled points may be specified explicitly with the +.B z +scaling unit. +. +In GNU +.IR troff , \" GNU +the register +.B \[rs]n[.s] +can interpolate a non-integral type size. +. +The register +.B \[rs]n[.ps] +interpolates the type size in scaled points. +. +. +.P +For example, +if +.I sizescale +is\~1000, +then a scaled point is one thousandth of a point. +. +Consequently, +.RB \[lq] ".ps 10.5" \[rq] +is synonymous with +.RB \[lq] ".ps 10.5z" \[rq]; +both set the type size to 10,500\~scaled points, +or 10.5\~points. +. +. +.P +It makes no sense to use the +.RB \[lq] z \[rq]\~scaling +unit in a numeric expression whose default scaling unit is neither +.RB \[lq] u \[rq] +.RB nor\~\[lq] z \[rq], +so GNU +.I troff \" GNU +disallows this. +. +Similarly, +it is nonsensical to use a scaling unit other +.RB than\~\[lq] z \[rq] +.RB or\~\[lq] u \[rq] +in a numeric expression whose default scaling unit +.RB is\~\[lq] z \[rq], +so GNU +.I troff +disallows this as well. +. +. +.br +.ne 2v +.P +Another new scaling unit, +.RB \[lq] s \[rq], +multiplies by the number of basic units in a scaled point. +. +Thus, +.RB \[lq]\^ \[rs]n[.ps]s \[rq] +is equal to +.RB \[lq] 1m \[rq] +by definition. +. +Do not confuse the +.RB \[lq] s \[rq] +and +.RB \[lq] z \[rq] +scaling units. +. +. +.br +.ne 2v +.P +Output devices may be limited in the type sizes they can employ. +. +The +.B .s +and +.B .ps +registers represent the type size as selected by the output driver as it +understands a device's capability. +. +The last +.I requested +type size is interpolated in scaled points by the read-only register +.B .psr +and in points as a decimal fraction by the read-only string-valued +register +.BR .sr . +. +Both are associated with the environment. +. +For example, +if a type size of 10.95\~points is requested, +and the nearest size permitted by a +.B sizes +request +(or by the +.B sizes +or +.B \%sizescale +directives in the device's +.I DESC +file) +is 11\~points, +the output driver uses the latter value. +.\" END Keep (roughly) parallel with groff.texi node "Using Fractional +.\" Type Sizes". +. +. +.P +A further two new measurement units available in +.I groff +are +.RB \[lq] M \[rq], +which indicates hundredths of an em, +and +.RB \[lq] f \^\[rq], +which multiplies by 65,536. +. +The latter provides convenient fractions for color definitions with the +.B \%defcolor +request. +. +For example, +0.5f equals 32768u. +. +. +.\" ==================================================================== +.SS "Numeric expressions" +.\" ==================================================================== +. +GNU +.I troff \" GNU +permits spaces in a numeric expression within parentheses, +and offers three new operators. +. +. +.TP +.IB e1 >? e2 +Interpolate the greater of +.I e1 +and +.IR e2 . +. +. +.TP +.IB e1 <? e2 +Interpolate the lesser of +.I e1 +and +.IR e2 . +. +. +.TP +.BI ( c ; e ) +Evaluate +.I e +using +.I c +as the default scaling unit, +ignoring scaling units in +.I e +if +.I c +is empty. +. +. +.\" ==================================================================== +.SS "Conditional expressions" +.\" ==================================================================== +. +More conditions can be tested with the +.RB \[lq]\| if \|\[rq] +and +.B ie +requests, +as well as the new +.RB \[lq] while \[rq] +request. +. +. +.TP +.BI c\~ chr +True if a character +.I chr +is available, +where +.I chr +is an ordinary character +(Unicode basic Latin excluding control characters and the space), +a special character, +or +.BI \[rs]N\[aq] index\c +.BR \[aq] . +. +. +.TP +.BI d\~ nam +True if a string, +macro, +diversion, +or request +.I nam +is defined. +. +. +.TP +.BI F\~ fnt +True if a font +.I fnt +is available; +.I fnt +can be an abstract style +or a font name. +. +.I fnt +is handled as if it +were accessed with the +.B ft +request +(that is, +abstract styles and font translation are applied), +but +.I fnt +cannot be a mounting position, +and no font is mounted. +. +. +.TP +.BI m\~ col +True if a color +.I col +is defined. +. +. +.TP +.BI r\~ reg +True if a register +.I reg +is defined. +. +. +.TP +.BI S\~ sty +True if a style +.I sty +is registered. +. +Font translation applies. +. +. +.TP +.B v +Always false. +. +This condition is for compatibility with certain other +.I troff +implementations only. +. +(This refers to +.IR vtroff , +a translator that would convert the C/A/T output from early-vintage AT&T +.I troff \" AT&T +to a form suitable for Versatec and Benson-Varian plotters.) +. +. +.\" ==================================================================== +.SS "Drawing commands" +.\" ==================================================================== +. +GNU +.I troff \" GNU +offers drawing commands to create filled +circles and ellipses, +and polygons. +.\" CSTR #54 did not countenance polygons, but DWB 3.3 had outlined ones +.\" as \D'p' as we do. Filled polygons appear to be a GNU innovation. +. +Stroked (outlined) objects are drawn with the stroke color and +filled (solid) ones shaded with the fill color. +. +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 a stroked one because the former +is drawn only within its defined area, +whereas strokes have a line thickness +(set with another new drawing command, +.BR \[rs]D\[aq]t\[aq] ). +. +. +.\" ==================================================================== +.SS "Escape sequences" +.\" ==================================================================== +. +.\" TODO: Some of the synopses here and in "New requests" get pretty +.\" discursive. It would be better to lift the introduction of new +.\" concepts in groff programming to new subsections above. Examples +.\" include: string parameterization, user-definable characters, +.\" character properties (cflags), character classes; the hyphenation +.\" language, code, and pattern file system; file stream manipulation... +.\" +.\" _Maybe_ output suppression. It's a big enough concept, but only +.\" well understood by retired contributors, only used by the grohtml +.\" output driver (still beta after 20 years), and we have some Savannah +.\" tickets that point the way to radically simplifying its design, +.\" eliminating its need to groff before you groff. +.I groff +introduces several new escape sequences +and extends the syntax of a few AT&T +.I troff \" AT&T +escape sequences +(namely, +.BR \[rs]D , +.BR \[rs]f , +.BR \[rs]k , +.BR \[rs]n , +.BR \[rs]s , +.BR \[rs]$ , +and +.BR \[rs]* ). +. +In the following list, +escape sequences are collated alphabetically at first, +and then by symbol roughly in Unicode code point order. +.\" Exceptions are made to group closely-related escape sequences in an +.\" order more agreeable to the development of a topic. +. +. +.TP 7.5 \" sinfully obtain better pagination on typesetters +.BI \[rs]A\[aq] anything \[aq] +Interpolate 1 if +.I anything +is a valid identifier, +and\~0 otherwise. +. +Because invalid input characters are removed, +invalid identifiers are empty or contain spaces, +tabs, +or newlines. +. +You can employ +.B \[rs]A +to validate a macro argument before using it to construct another escape +sequence or identifier. +. +.TP +.BI \[rs]B\[aq] anything \[aq] +Interpolate 1 if +.I anything +is a valid numeric expression, +and\~0 otherwise. +. +You might use +.B \[rs]B +along with the +.RB \[lq]\| if \|\[rq] +request to filter out invalid macro arguments. +. +. +.TP +.BI \[rs]D\[aq]C\~ "d" \[aq] +Draw filled circle of diameter +.I d +with its leftmost point at the drawing position. +. +. +.TP +.BI \[rs]D\[aq]E\~ "h v" \[aq] +Draw filled ellipse with +.I h +and +.I v +as the axes and the leftmost point at the drawing position. +. +. +.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; +DWB and Heirloom +.IR troff s \" DWB, Heirloom +do not. +. +.\" 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 line 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. +. +. +.TP +.B \[rs]E +Embed an escape character that is not interpreted in copy mode +(compare with +.B \[rs]a +and +.BR \[rs]t ). +. +You can use it to ease the writing of nested macro definitions. +. +It is also convenient to define strings containing escape sequences that +need to work when used in copy mode +(for example, +as macro arguments), +or which will be interpolated at varying macro nesting depths. +. +. +.TP +.BI \[rs]f[ font ] +Select +.IR font , +which may be a mounting position, +abstract style, +or font name, +to choose the typeface. +. +.B \[rs]f[] +and +.B \[rs]fP +are synonyms; +we recommend the former. +. +. +.TP +.BI \[rs]F f +.TQ +.BI \[rs]F( fm +.TQ +.BI \[rs]F[ family ] +Select default font family. +. +.B \[rs]F[] +makes the previous font family the default. +. +.B \[rs]FP +is unlike +.BR \[rs]fP ; +it selects font family \[lq]P\[rq] as the default. +. +See the +.B fam +request below. +. +. +.TP +.BI \[rs]k( rg +.TQ +.BI \[rs]k[ reg ] +Mark horizontal drawing position in +two-character register +.RI name\~ rg +or arbitrary register +.RI name\~ reg . +. +. +.TP +.BI \[rs]m c +.TQ +.BI \[rs]m( cl +.TQ +.BI \[rs]m[ col ] +Set the stroke color. +. +.B \[rs]m[] +restores the previous stroke color, +or the default if there is none. +. +. +.TP +.BI \[rs]M c +.TQ +.BI \[rs]M( cl +.TQ +.BI \[rs]M[ col ] +Set the fill color. +. +.B \[rs]M[] +restores the previous fill color, +or the default if there is none. +. +. +.TP +.BI \[rs]n[ reg ] +Interpolate register +.IR reg . +. +. +.TP +.BI \[rs]O n +.TQ +.BI \[rs]O[ n ] +Suppress +.I @g@troff +output of glyphs and geometric objects. +. +The sequences +.BR \[rs]O2 , +.BR \[rs]O3 , +.BR \[rs]O4 , +and +.B \[rs]O5 +are intended for internal use by +.MR grohtml @MAN1EXT@ . +. +. +.RS +.TP +.B \[rs]O0 +.TQ +.B \[rs]O1 +Disable and enable, +respectively, +the emission of glyphs and geometric objects to the output driver, +provided that this sequence occurs at the outermost suppression level +(see +.B \[rs]O3 +and +.BR \[rs]O4 ). +. +Horizontal motions corresponding to non-overstruck glyph widths still +occur. +. +These sequences also reset the registers +.BR opminx , +.BR opminy , +.BR opmaxx , +and +.B opmaxy +to\~\-1. +. +These four registers mark the top left and bottom right hand corners of +a box encompassing all written or drawn output. +. +. +.TP +.B \[rs]O2 +At the outermost suppression level, +enable emission of glyphs and geometric objects, +and write to the standard error stream the page number and values of the +four aforementioned registers encompassing glyphs written since the last +interpolation of a +.B \[rs]O +sequence, +as well as the page offset, +line length, +image file name +(if any), +horizontal and vertical device motion quanta, +and input file name. +. +Numeric values are in basic units. +. +. +.TP +.B \[rs]O3 +.TQ +.B \[rs]O4 +Begin and end a nested suppression level, +respectively. +. +.I \%grohtml +uses this mechanism to create images of output preprocessed with +.IR @g@pic , +.IR @g@eqn , +and +.IR @g@tbl . +. +At startup, +.I @g@troff +is at the outermost suppression level. +. +.I \%pre\-grohtml +generates these sequences when processing the document, +using +.I @g@troff +with the +.B ps +output device, +Ghostscript, +and the PNM tools to produce images in PNG format. +. +These sequences start a new page if the device is not +.B html +or +.BR xhtml , +to reduce the number of images crossing a page boundary. +. +. +.TP +.BI \[rs]O5[ Pfile ] +At the outermost suppression level, +write the name +.I file +to the standard error stream at position +.IR P , +which must be one of +.BR l , +.BR r , +.BR c , +or +.BR i , +corresponding to +left, +right, +centered, +and inline alignments within the document, +respectively. +. +.I file +is is a name associated with the production of the next image. +.RE +. +. +.TP +.BI \[rs]R\[aq] name\~\[+-]n \[aq] +Synonymous with +.RB \[lq] .nr +.IR name\~\[+-]n \[rq]. +. +. +.TP +.BI \[rs]s[ \[+-]n ] +.TQ +.BI \[rs]s \[+-] [ n ] +.TQ +.BI \[rs]s\[aq] \[+-]n \[aq] +.TQ +.BI \[rs]s \[+-] \[aq] n \[aq] +Set the type size to, +or increment or decrement it by, +.I n +scaled points. +. +. +.br +.ne 5v +.TP +.BI \[rs]V e +.TQ +.BI \[rs]V( ev +.TQ +.BI \[rs]V[ env ] +Interpolate contents of the environment variable +.IR env , +as returned by +.MR getenv 3 . +. +.B \[rs]V +is interpreted even in copy mode. +. +. +.TP +.BI \[rs]X\[aq] anything \[aq] +Within +.B \[rs]X +arguments, +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] +is reduced to +.BR \[rs] . +. +So that the basic Latin subset of the Unicode character set +(that is, +ISO\~646:1991-IRV or, +popularly, +\[lq]US-ASCII\[rq]) +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 definitions are ignored. +. +Other escape sequences are not supported. +. +. +.IP +If the +.B \%use_charnames_in_special +directive appears in the output device's +.I DESC +file, +the use of special character escape sequences is +.I not +an error; +they are simply output verbatim +(with the exception of the seven mapped to Unicode basic Latin +characters, +discussed above). +. +.B \%use_charnames_in_special +is currently employed only by +.MR grohtml @MAN1EXT@ . +. +. +.TP +.BI \[rs]Y m +.TQ +.BI \[rs]Y( ma +.TQ +.BI \[rs]Y[ mac ] +Interpolate a macro as a device control command. +. +This is similar to +.BI \[rs]X\[aq]\[rs]*[ mac ]\[aq]\f[R], +except the contents of +.I mac +are not interpreted, +and +.I mac +can be a macro and thus contain newlines, +whereas the argument to +.B \[rs]X +cannot. +. +This inclusion of newlines requires an extension to the AT&T +.I troff \" AT&T +output format, +and will confuse postprocessors that do not know about it. +. +. +.TP +.BI \[rs]Z\[aq] anything \[aq] +Save the drawing position, +format +.IR anything , +then restore it. +. +Tabs and leaders in the argument are ignored with an error diagnostic. +. +. +.TP +.B \[rs]# +Everything up to and including the next newline is ignored. +. +This escape sequence is interpreted even in copy mode. +. +.B \[rs]# +is like +.BR \[rs]" , +except that +.B \[rs]" +does not ignore a newline; +the latter therefore cannot be used by itself for a whole-line +comment\[em]it leaves a blank line on the input stream. +. +. +.\" Keep \$0 before \$( in spite of collation. +.TP +.B \[rs]$0 +Interpolate the name by which the macro being interpreted was called. +. +In GNU +.I troff \" GNU +this name can vary; +see the +.B als +request. +. +. +.TP +.BI \[rs]$( nn +.TQ +.BI \[rs]$[ nnn ] +In a macro or string definition, +interpolate +the +.IR nn th +or +.IR nnn th +argument. +. +Macros and strings can have an unlimited number of arguments. +. +. +.TP +.B \[rs]$* +In a macro or string definition, +interpolate the catenation of all arguments, +separated by spaces. +. +. +.TP +.B \[rs]$@ +In a macro or string definition, +interpolate the catenation of all arguments, +with each surrounded by double quotes and separated by spaces. +. +. +.TP +.B \[rs]$\[ha] +In a macro or string definition, +interpolate the catenation of all arguments +constructed in a form suitable for passage to the +.B ds +request. +. +. +.TP +.B \[rs]) +Interpolate a +.I transparent +dummy character\[em]one that is ignored by end-of-sentence detection. +. +It behaves as +.BR \[rs]& , +except that +.B \[rs]& +is treated as letters and numerals normally are after +\[lq].\[rq], +\[lq]?\[rq], +and +\[lq]!\[rq]; +.B \[rs]& +cancels end-of-sentence detection, +and +.B \[rs]) +does not. +. +. +.TP +.BI \[rs]*[ "string\~\c +.RI [ arg \~.\|.\|.]\c +.B ] +Interpolate +.I string, +passing it +.I arg +\&.\|.\|.\& +as arguments. +. +. +.\" Keep \/ before \, in spite of collation. +.TP +.B \[rs]/ +Apply an +.IR "italic correction" : +modify the spacing of the preceding glyph so that the distance between +it and the following glyph is correct if the latter is of upright shape. +. +For example, +if an italic\~\[lq]f\^\[rq] is followed immediately by a roman right +parenthesis, +then in many fonts the top right portion of the\~\[lq]f\^\[rq] overlaps +the top left of the right parenthesis, +.if t producing \f[I]f\f[R]), +which is ugly. +. +Inserting +.B \[rs]\^/ +between them +.if t \{\ +. nop produces +. ie \n(.g \f[I]f\/\f[R]) +. el \f[I]f\|\f[R]) +. nop and +.\} +avoids this problem. +. +Use this escape sequence whenever an oblique glyph is immediately +followed by an upright glyph without any intervening space. +. +. +.TP +.B \[rs], +Apply a +.IR "left italic correction" : +modify the spacing of the following glyph so that the distance between +it and the preceding glyph is correct if the latter is of upright shape. +. +For example, +if a roman left parenthesis is immediately followed by an +italic\~\[lq]f\^\[rq], +then in many fonts the bottom left portion of the\~\[lq]f\^\[rq] +overlaps the bottom of the left parenthesis, +.if t producing \f[R](\f[I]f\f[R], +which is ugly. +. +Inserting +.B \[rs], +between them +.if t \{\ +. nop produces +. ie \n(.g \f[R](\,\f[I]f\f[R] +. el \f[R](\^\f[I]f\f[R] +. nop and +.\} +avoids this problem. +. +Use this escape sequence whenever an upright glyph is followed +immediately by an oblique glyph without any intervening space. +. +. +.TP +.B \[rs]: +Insert a non-printing break point. +. +That is, +a word can break there, +but the soft hyphen character does not mark the break point if it does +(in contrast to +.RB \[lq]\^ \[rs]% \[rq]). +. +This escape sequence is an input word boundary, +so the remainder of the word is subject to hyphenation as normal. +. +. +.TP +.BI \[rs]? anything \[rs]? +When used in a diversion, +this transparently embeds +.I anything +in the diversion. +.I anything +is read in copy mode. +. +When the diversion is reread, +.I anything +is interpreted. +.I anything +may not contain newlines; +use +.B \[rs]!\& +if you want to embed newlines in a diversion. +. +The escape sequence +.B \[rs]?\& +is also recognized in copy mode and becomes an internal code; +it is this code that terminates +.IR anything . +Thus +. +. +.RS +.IP +.EX +.ne 14v+\n(.Vu +\&.nr x 1 +\&.nf +\&.di d +\&\[rs]?\[rs]\[rs]?\[rs]\[rs]\[rs]\[rs]?\[rs]\[rs]\[rs]\[rs]\[rs]\[rs]\ +\[rs]\c +\&\[rs]nx\[rs]\[rs]\[rs]\[rs]?\[rs]\[rs]?\[rs]? +\&.di +\&.nr x 2 +\&.di e +\&.d +\&.di +\&.nr x 3 +\&.di f +\&.e +\&.di +\&.nr x 4 +\&.f +.EE +.RE +. +. +.IP +prints\~\c +.BR 4 . +. +. +.TP +.BI \[rs][ char ] +Typeset the special character +.IR char . +. +. +.TP +.BI \[rs][ "base-char combining-component\~"\c +.RB .\|.\|. ] +Typeset a composite glyph consisting of +.I base-char +overlaid with one or more +.IR combining-component s. +. +For example, +.RB \[lq]\| \[rs][A\~ho] \^\[rq] +is a capital letter \[lq]A\[rq] with a \[lq]hook accent\[rq] (ogonek). +. +See the +.B \%composite +request below; +.IR "Groff: The GNU Implementation of troff" , +the +.I groff +Texinfo manual, +for details of composite glyph name construction; +and +.MR groff_char @MAN7EXT@ +for a list of components used in composite glyph names. +. +. +.TP +.B \[rs]\[ti] +Insert an unbreakable space that is adjustable like an ordinary space. +. +It is discarded from the end of an output line if a break is forced. +. +. +.\" ==================================================================== +.SS "Restricted requests" +.\" ==================================================================== +. +To mitigate risks from untrusted input documents, +the +.B pi +and +.B sy +requests are disabled by default. +. +.MR @g@troff @MAN1EXT@ 's +.B \-U +option enables the formatter's \[lq]unsafe mode\[rq], +restoring their function +(and enabling additional +.I groff +extension requests, +.BR open , +.BR opena , +and +.BR pso ). +. +. +.\" ==================================================================== +.SS "New requests" +.\" ==================================================================== +. +.TP +.BI .aln\~ "new old" +Create alias +.I new +for existing register named +.IR old , +causing the names to refer to the same stored value. +. +If +.I old +is undefined, +a warning in category +.RB \[lq] reg \[rq] +is generated and the request is ignored. +. +To remove a register alias, +invoke +.B rr +on its name. +. +A register's contents do not become inaccessible until it has no more +names. +. +. +.TP +.BI .als\~ "new old" +Create alias +.I new +for existing request, +string, +macro, +or diversion named +.IR old , +causing the names to refer to the same stored object. +. +If +.I old +is undefined, +a warning in category +.RB \[lq] mac \[rq] +is produced, +and the request is ignored. +. +The +.RB \[lq] am \[rq], +.RB \[lq] as \[rq], +.BR da , +.BR de , +.BR di , +and +.B ds +requests +(together with their variants) +create a new object only if the name of the macro, +diversion, +or string is currently undefined +or if it is defined as a request; +normally, +they modify the value of an existing object. +. +To remove an alias, +invoke +.B rm +on its name. +. +The object itself is not destroyed until it has no more names. +. +. +.IP +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. +. +. +.TP +.BI .am1\~ name\~\c +.RI [ end-name ] +As +.RB \[lq] am \[rq], +but compatibility mode is disabled while the appendment to +.I name +is interpreted: +a \[lq]compatibility save\[rq] token is inserted at its beginning, +and a \[lq]compatibility restore\[rq] token at its end. +. +As a consequence, +the requests +.RB \[lq] am \[rq], +.BR am1 , +.BR de , +and +.B de1 +can be intermixed freely since the compatibility save/\:restore tokens +affect only the parts of the macro populated by +.B am1 +and +.BR de1 . +. +. +.TP +.BI .ami\~ name\~\c +.RI [ end-name ] +Append to macro indirectly. +. +See +.B dei +below. +. +. +.TP +.BI .ami1\~ name\~\c +.RI [ end-name ] +As +.BR ami , +but compatibility mode is disabled during interpretation of the +appendment. +. +. +.TP +.BI .as1\~ name\~\c +.RI [ contents ] +As +.RB \[lq] as \[rq], +but compatibility mode is disabled while the appendment to +.I name +is interpreted: +a \[lq]compatibility save\[rq] token is inserted at the beginning of +.IR contents , +and a \[lq]compatibility restore\[rq] token after it. +. +As a consequence, +the requests +.RB \[lq] as \[rq], +.BR as1 , +.BR ds , +and +.B ds1 +can be intermixed freely since the compatibility save/\:restore tokens +affect only the portions of the strings populated by +.B as1 +and +.BR ds1 . +. +. +.TP +.BI .asciify\~ div +.I Unformat +the diversion +.I div +in a way such that Unicode basic Latin (ASCII) characters, +characters translated with the +.B trin +request, +space characters, +and some escape sequences, +that were formatted in the diversion +.I div +are treated like ordinary input characters when +.I div +is reread. +. +Doing so can be useful in conjunction with the +.B writem +request. +. +.B asciify +can be also used for gross hacks; +for example, +the following sets +.RB register\~ n +to\~1. +. +. +.RS +.IP +.EX +.ne 8v+\n(.Vu +\&.tr @. +\&.di x +\&@nr n 1 +\&.br +\&.di +\&.tr @@ +\&.asciify x +\&.x +.EE +.RE +. +. +.IP +.B asciify +cannot return all items in a diversion to their source equivalent: +nodes such as those produced by +.BR \[rs]N[ .\|.\|.\& ] +will remain nodes, +so the result cannot be guaranteed to be a pure string. +. +See section \[lq]Copy mode\[rq] in +.MR groff @MAN7EXT@ . +. +Glyph parameters such as the type face and size are not preserved; +use +.B unformat +to achieve that. +. +. +.TP +.B .backtrace +Write backtrace of input stack to the standard error stream. +. +See the +.B \-b +option of +.MR @g@troff @MAN1EXT@ . +. +. +.TP +.BR .blm\~ [\c +.IR name ] +Set a blank line macro (trap). +. +If a blank line macro is thus defined, +.I groff +executes +.I macro +when a blank line is encountered in the input file, +instead of the usual behavior. +. +A line consisting only of spaces is also treated as blank and subject to +this trap. +. +If no argument is supplied, +the default blank line behavior is (re-)established. +. +. +.TP +.BR .box\~ [\c +.IR name ] +.TQ +.BR .boxa\~ [\c +.IR name ] +Divert +(or append) +output to +.I name, +similarly to the +.B di +and +.B da +requests, +respectively. +. +Any pending output line is +.I not +included in the diversion. +. +Without an argument, +stop diverting output; +any pending output line inside the diversion is discarded. +. +. +.TP +.B .break +Exit a +.RB \[lq] while \[rq] +loop. +. +Do not confuse this request with a typographical break or the +.B br +request. +. +See +.RB \[lq] continue \[rq]. +. +. +.TP +.B .brp +Break and adjust line; +this is the AT&T +.I troff \" AT&T +escape sequence +.B \[rs]p +in request form. +. +. +.TP +.BI .cflags\~ "n c1 c2\~"\c +\&.\|.\|. +Assign properties encoded by the number +.I n +to characters +.IR c1 , +.IR c2 , +and so on. +. +Ordinary and special characters have certain associated properties. +. +(Glyphs don't: +to GNU +.IR troff , \" GNU +like AT&T device-independent +.IR troff , \" AT&T +a glyph is an identifier corresponding to a rectangle with some metrics; +see +.MR groff_font @MAN5EXT@ .) +. +The first argument is the sum of the desired flags and the remaining +arguments are the characters to be assigned those properties. +. +Spaces between the +.I cn +arguments are optional. +. +Any argument +.I cn +can be a character class defined with the +.B class +request rather than an individual character. +. +. +.IP +The non-negative integer +.I n +is the sum of any of the following. +. +Some combinations are nonsensical, +such as +.RB \[lq] 33 \[rq] +(1 + 32). +. +. +.RS +.IP 1 +Recognize the character as ending a sentence if followed by a newline +or two spaces. +. +Initially, +characters +.RB \[lq] .?! \[rq] +have this property. +. +. +.IP 2 +Enable breaks before the character. +. +A line is not broken at a character with this property unless the +characters on each side both have non-zero hyphenation codes. +. +This exception can be overridden by adding 64. +. +Initially, +no characters have this property. +. +. +.IP 4 +Enable breaks after the character. +. +A line is not broken at a character with this property unless the +characters on each side both have non-zero hyphenation codes. +. +This exception can be overridden by adding 64. +. +Initially, +characters +.RB \[lq] \-\[rs][hy]\[rs][em] \^\[rq] +have this property. +. +. +.IP 8 +Mark the glyph associated with this character as overlapping other +instances of itself horizontally. +. +Initially, +characters +.RB \[lq]\^ \[rs][ul]\[rs][rn]\[rs][ru]\[rs][radicalex]\[rs][sqrtex]\ +\& \^\[rq] +have this property. +. +. +.IP 16 +Mark the glyph associated with this character as overlapping other +instances of itself vertically. +. +Initially, +the character +.RB \[lq]\^ \[rs][br] \^\[rq] +has this property. +. +. +.IP 32 +Mark the character as transparent for the purpose of end-of-sentence +recognition. +. +In other words, +an end-of-sentence character followed by any number of characters with +this property is treated as the end of a sentence if followed by a +newline or two spaces. +. +This is the same as having a zero space factor in \*[tx]. +. +Initially, +characters +.\" The following is ordered with the apostrophe and (single) closing +.\" quote on the ends so they are more easily visually distinguished +.\" from the double quotation marks in roman. +.RB \[lq]\| \[aq]\|"\|)]*\[rs][dg]\[rs][dd]\[rs][rq]\[rs]\^[cq] \|\[rq] +have this property. +. +. +.IP 64 +Ignore hyphenation codes of the surrounding characters. +. +Use this value in combination with values 2 and\~4. +. +Initially, +no characters have this property. +. +. +.IP +For example, +if you need an automatic break point after +the en-dash in numeric ranges like \[lq]3000\[en]5000\[rq], +insert +.RS +.RS +.EX +\&.cflags 68 \[rs][en] +.EE +.RE +into your document. +. +However, +this can lead to bad layout if done without thinking; +in most situations, +a better solution than +changing the +.B cflags +value is inserting +.RB \[lq] \[rs]: \[rq] +right after the hyphen at the places that really need a break point. +.RE +. +. +.P +The remaining values were implemented for East Asian language support; +those who use alphabetic scripts exclusively can disregard them. +. +. +.IP 128 +Prohibit a break before the character, +but allow a break after the character. +. +This works only in combination with values 256 and 512 and has no effect +otherwise. +. +Initially, +no characters have this property. +. +. +.IP 256 +Prohibit a break after the character, +but allow a break before the character. +. +This works only in combination with values 128 and 512 and has no effect +otherwise. +. +Initially, +no characters have this property. +. +. +.IP 512 +Allow a break before or after the character. +. +This works only in combination with values 128 and 256 and has no effect +otherwise. +. +Initially, +no characters have this property. +.RE +. +. +.IP +In contrast to values 2 and\~4, +the values 128, +256, +and 512 work +pairwise. +. +If, +for example, +the left character has value 512, +and the right character 128, +no break will be automatically inserted between them. +. +If we use value\~6 instead for the left character, +a break after the character can't be suppressed since the neighboring +character on the right doesn't get examined. +. +. +.TP +.BI .char\~ "c contents" +Define the ordinary or special +.RI character\~ c +as +.IR contents , +which can be empty. +. +More precisely, +.B char +defines a +.I groff +object +(or redefines an existing one) +that is accessed with the +.RI name\~ c +on input, +and produces +.I contents +on output. +. +Every time +.I c +is to be formatted, +.I contents +is processed in a temporary environment and the result is wrapped up +into a single object. +. +Compatibility mode is turned off and the escape character is +set +.RB to\~ \[rs] +while +.I contents +is processed. +. +Any emboldening, +constant spacing, +or track kerning is applied to this object as a whole, +not to each character in +.IR contents . +. +. +.IP +An object defined by this request can be used just like a glyph +provided by the output device. +. +In particular, +other characters can be translated to it with the +.B tr +request; +it can be made the tab or leader fill character with the +.B tc +and +.B lc +requests; +sequences of it can be drawn with the +.B \[rs]l +and +.B \[rs]L +escape sequences; +and, +if the +.B hcode +request is used on +.IR c , +it is subject to automatic hyphenation. +. +. +.IP +To prevent infinite recursion, +occurrences of +.I c +within its own definition are treated normally +(as if it were not being defined with +.BR char ). +. +The +.B tr +and +.B trin +requests take precedence if +.B char +both apply +.RI to\~ c . +. +A character definition can be removed with the +.B rchar +request. +. +. +.TP +.BI .chop\~ object +Remove the last character from the macro, +string, +or diversion +.IR object . +. +This is useful for removing the newline from the end of a diversion that +is to be interpolated as a string. +. +This request can be used repeatedly on the same +.IR object ; +see section \[lq]gtroff Internals\[rq] in +.IR "Groff: The GNU Implementation of troff" , +the +.I groff +Texinfo manual, +for discussion of nodes inserted by +.IR groff . +. +. +.TP +.BI .class\~ "name c1 c2\~"\c +\&.\|.\|. +Define a character class +(or simply \[lq]class\[rq]) +.I name +comprising the characters or range expressions +.IR c1 , +.IR c2 , +and so on. +. +. +.IP +A class thus defined can then be referred to in lieu of listing all the +characters within it. +. +Currently, +only the +.B cflags +request can handle references to character classes. +. +. +.IP +In the request's simplest form, +each +.I cn +is a character +(or special character). +. +.RS +.RS +.EX +\&.class [quotes] \[aq] \[rs][aq] \[rs][dq] \[rs][oq] \[rs][cq] \ +\[rs][lq] \[rs][rq] +.EE +.RE +.RE +. +. +.IP +Since class and special character names share the same name space, +we recommend starting and ending the class name with +.RB \[lq] [ \[rq] +and +.RB \[lq] ] \[rq], +respectively, +to avoid collisions with existing character names defined by +.I groff +or the user +(with +.B char +and related requests). +. +This practice applies the presence of +.RB \[lq] ] \[rq] +in the class name to prevent the usage of the special character escape +form +.RB \[lq] \[rs][ .\|.\|. ] \[rq], +thus you must use the +.B \[rs]C +escape to access a class with such a name. +. +. +.IP +You can also use a character range expression consisting of a start +character followed by +.RB \[lq] \- \[rq] +and then an end character. +. +Internally, +GNU +.I troff \" GNU +converts these two character names to Unicode code points +(according to the +.I groff +glyph list [GGL]), +which determine the start and end values of the range. +. +If that fails, +the class definition is skipped. +. +Furthermore, +classes can be nested. +. +.RS +.RS +.EX +\&.class [prepunct] , : ; > } +\&.class [prepunctx] \[rs]C\[aq][prepunct]\[aq] \ +\[rs][u2013]\-\[rs][u2016] +.EE +.RE +The class +.RB \[lq] [prepunctx] \[rq] +thus contains the contents of the class +.RB \[lq] [prepunct] \[rq] +and characters in the range U+2013\[en]U+2016. +.RE +. +. +.IP +If you want to include +.RB \[lq] \- \[rq] +in a class, +it must be the first character value in the argument list, +otherwise it gets misinterpreted as part of the range syntax. +. +. +.IP +It is not possible to use class names as end points of range +definitions. +. +. +.IP +A typical use of the +.B class +request is to control line-breaking and hyphenation rules as defined by +the +.B cflags +request. +. +For example, +to inhibit line breaks before the characters belonging to the +.RB \[lq] [prepunctx] \[rq] +class defined in the previous example, +you can write the following. +. +.RS +.RS +.EX +\&.cflags 2 \[rs]C\[aq][prepunctx]\[aq] +.EE +.RE +.RE +. +. +.TP +.BI .close\~ stream +Close the stream named +.IR stream , +invalidating it as an argument to the +.B write +request. +. +See +.BR open . +. +. +.TP +.BI .composite\~ c1\~c2 +Map character name +.I c1 +to character name +.I c2 +when +.I c1 +is a combining component in a composite glyph. +. +Typically, +this remaps a spacing glyph to a combining one. +. +. +.TP +.B .continue +Skip the remainder of a +.RB \[lq] while \[rq] +loop's body, +immediately starting the next iteration. +. +See +.BR break . +. +. +.TP +.BI .color\~ n +If +.I n +is non-zero or missing, +enable colors +(the default), +otherwise disable them. +. +. +.TP +.BI .cp\~ n +If +.I n +is non-zero or missing, +enable compatibility mode, +otherwise disable it. +. +In compatibility mode, +long names are not recognized, +and the incompatibilities they cause do not arise. +. +. +.TP +.BI .defcolor\~ "ident scheme color-component\~\c" +\&.\|.\|. +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 components), +.RB \[lq] cmyk \[rq] +(four components), +or +.RB \[lq] gray \[rq] +(one component). +. +.RB \[lq] grey \[rq] +is accepted as a synonym of +.RB \[lq] gray \[rq]. +. +The color components can be encoded as a 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]65535 (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). +. +. +.IP +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. +. +. +.TP +.BI .de1\~ name\~\c +.RI [ end-name ] +Define a macro to be interpreted with compatibility mode disabled. +. +When +.I name +is called, +compatibility mode enablement status is saved; +it is restored when the call completes. +. +. +.TP +.BI .dei\~ name\~\c +.RI [ end-name ] +Define macro indirectly, +with the name of the macro to be defined in string +.I name +and the name of the end macro terminating its definition in string +.IR end-name . +. +. +.TP +.BI .dei1\~ name\~\c +.RI [ end-name ] +As +.BR dei , +but compatibility mode is disabled while the definition of the macro +named in string +.I name +is interpreted. +. +. +.TP +.BI .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 the embedding of +leading spaces. +. +. +.TP +.BI .devicem\~ name +Write contents of macro or string +.I name +to +.I @g@troff +output as a device control command. +. +. +.TP +.BI .do\~ name\~\c +.RI [ arg \~.\|.\|.] +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; +that is, +the restored compatibility state applies to the contents of the macro, +string, +or diversion +.I name +as well as data read from files or pipes if +.I name +is any of the +.BR so , +.BR soquiet , +.BR mso , +.BR msoquiet , +or +.B pso +requests. +. +. +.IP +For example, +.RS +.RS \" one "extra" RS to get us inboard of this indented paragraph +.EX +\&.de mac1 +FOO +\&.. +\&.de1 mac2 +groff +\&.mac1 +\&.. +\&.de mac3 +compatibility +\&.mac1 +\&.. +\&.de ma +\[rs]\[rs]$1 +\&.. +\&.cp 1 +\&.do mac1 +\&.do mac2 \[rs]" mac2, defined with .de1, calls "mac1" +\&.do mac3 \[rs]" mac3 calls "ma" with argument "c1" +\&.do mac3 \[rs][ti] \[rs]" groff syntax accepted in .do arguments +.EE +.RE +results in +.RS +.EX +FOO groff FOO compatibility c1 \[ti] +.EE +.RE +as output. +.RE \" this "extra" RE avoids indentation of the remaining paragraphs +. +. +.TP +.BI .ds1\~ "name contents" +As +.BR ds , +but compatibility mode is disabled while +.I name +is interpreted: +a \[lq]compatibility save\[rq] token is inserted at the beginning of +.IR contents , +and a \[lq]compatibility restore\[rq] token after it. +. +. +.TP +.B .ecr +Restore the escape character saved with +.BR ecs , +or set escape character to +.RB \[lq]\| \[rs] \[rq] +if none has been saved. +. +. +.TP +.B .ecs +Save the current escape character. +. +. +.TP +.BI .evc\~ env +Copy the properties of environment +.I env +to the current environment, +except for the following data. +. +. +.RS +.IP \[bu] 2n +a partially collected line, +if present; +. +. +.IP \[bu] +the interruption status of the previous input line +(due to use of the +.B \[rs]c +escape sequence); +. +. +.IP \[bu] +the count of remaining lines to center, +to right-justify, +or to underline +(with or without underlined spaces)\[em]these are set to zero; +. +. +.IP \[bu] +the activation status of temporary indentation; +. +. +.IP \[bu] +input traps and their associated data; +. +. +.IP \[bu] +the activation status of line numbering +(which can be reactivated with +.RB \[lq] .nm\~+0 \[rq]); +and +. +. +.IP \[bu] +the count of consecutive hyphenated lines +(set to zero). +.RE +. +. +.TP +.BR .fam\~ [\c +.IR family ] +Set default font family to +.IR family . +. +If no argument is given, +the previous font family is selected, +or the formatter's default family if there is none. +. +The formatter's default font family is \[lq]T\[rq] (Times), +but it can be overridden by the output device\[em]see +.MR groff_font @MAN5EXT@ . +. +The default font family is associated with the environment. +. +See +.BR \[rs]F . +. +. +.TP +.BI .fchar\~ c\~contents +Define fallback +.RI character\~ c +as +.IR contents . +. +The syntax of this request is the same as the +.B char +request; +the difference is that a character defined with +.B char +hides a glyph with the same name in the selected font, +whereas characters defined with +.B fchar +are checked only if +.I c +isn't found in the selected font. +. +This test happens before special fonts are searched. +. +. +.TP +.BI .fcolor\~ color +Set the fill color to +.IR color . +. +Without an argument, +the previous fill color is selected. +. +. +.TP +.BI .fschar\~ f\~c\~contents +Define fallback special +.RI character\~ c +for font\~\c +.I f +as +.IR contents . +. +A character defined by +.B fschar +is located after the list of fonts declared with +.B \%fspecial +is searched but before those declared with the +.RB \%\[lq] special \[rq] +request. +. +.TP +.BI .fspecial\~ "f s1 s2\~"\c +\&.\|.\|. +When +.RI font\~ f +is selected, +fonts +.IR s1 , +.IR s2 , +\&.\|.\|.\& +are treated as special; +that is, +they are searched for glyphs not found in +.IR f . +. +Any fonts specified in the +.RB \%\[lq] special \[rq] +request are searched after +.IR s1 , +.IR s2 , +and so on. +. +Without +.I s +arguments, +.B \%fspecial +clears the list of fonts treated as special when +.I f +is selected. +. +. +.TP +.BI .ftr\~ f\~g +Translate +.RI font\~ f +.RI to\~ g . +. +Whenever a font +.RI named\~ f +is referred to in an +.B \[rs]f +escape sequence, +in the +.B F +and +.B S +conditional expression operators, +or in the +.BR ft , +.BR ul , +.BR bd , +.BR cs , +.BR tkf , +.BR \%special , +.BR \%fspecial , +.BR fp , +or +.B sty +requests, +.RI font\~ g +is used. +If +.I g +is missing or identical +.RI to\~ f , +then +.RI font\~ f +is not translated. +. +. +.TP +.BI .fzoom\~ f\~zoom +Set zoom factor +.I zoom +for font\~\c +.IR f . +.I zoom +must a non-negative integer multiple of 1/1000th. +. +If it is missing or is equal to zero, +it means the same as 1000, +namely no magnification. +. +.IR f \~\c +must be a resolved font name, +not an abstract style. +.\" XXX: What about a mounting position? It's not rejected... +. +. +.TP +.BI .gcolor\~ color +Set the stroke color to +.IR color . +. +Without an argument, +the previous stroke color is selected. +. +. +.TP +.BI .hcode\~ "c1 code1\~"\c +.RI [ "c2 code2" "] .\|.\|." +Set the hyphenation code of character +.I c1 +to +.IR code1 , +that of +.I c2 +to +.IR code2 , +and so on. +. +A hyphenation code must be an ordinary character +(not a special character escape sequence) +other than a digit. +. +The request is ignored if given no arguments. +. +. +.IP +For hyphenation to work, +hyphenation codes must be set up. +. +At startup, +.I groff +assigns hyphenation codes to the letters \[lq]a\[en]z\[rq] +(mapped to themselves), +to the letters \[lq]A\[en]Z\[rq] +(mapped to \[lq]a\[en]z\[rq]), +and zero to all other characters. +. +Normally, +hyphenation patterns contain only lowercase letters which should be +applied regardless of case. +. +In other words, +they assume that the words \[lq]ABBOT\[rq] and \[lq]Abbot\[rq] should be +hyphenated exactly as \[lq]abbot\[rq] is. +. +.B hcode +extends this principle to letters outside the Unicode basic Latin +alphabet; +without it, +words containing such letters won't be hyphenated properly even if the +corresponding hyphenation patterns contain them. +. +. +.TP +.BI .hla\~ lang +Set the hyphenation language to +.IR lang . +. +Hyphenation exceptions specified with the +.B hw +request and hyphenation patterns and exceptions specified with the +.B hpf +and +.B hpfa +requests are associated with the hyphenation language. +. +The +.B hla +request is usually invoked by a localization file, +which is in turn loaded by the +.I troffrc +or +.I troffrc\-end +file; +see the +.B hpf +request below. +. +The hyphenation language is associated with the environment. +. +. +.TP +.BR .hlm\~ [\c +.IR n ] +Set the maximum number of consecutive hyphenated lines +.RI to\~ n . +. +If +.I n +is negative, +there is no maximum. +. +If omitted, +.I n +is\~\-1. +. +This value is associated with the environment. +. +Only lines output from a given environment count towards the maximum +associated with that environment. +. +Hyphens resulting from +.B \[rs]% +are counted; +explicit hyphens are not. +. +. +.TP +.BI .hpf\~ pattern-file +Read hyphenation patterns from +.IR pattern-file . +. +This file is sought in the same way that macro files are with the +.B mso +request or the +.BI \-m name +command-line option to +.MR groff @MAN1EXT@ +and +.MR @g@troff @MAN1EXT@ . +. +. +.IP +The +.I pattern-file +should have the same format as (simple) \*[tx] pattern files. +. +The following scanning rules are implemented. +. +. +.RS +.IP \[bu] 2n +A percent sign starts a comment +(up to the end of the line) +even if preceded by a backslash. +. +. +.IP \[bu] +\[lq]Digraphs\[rq] like +.B \[rs]$ +are not supported. +. +. +.IP \[bu] +.RB \[lq] \[ha]\[ha]\c +.IR xx \[rq] +(where each +.I x +is 0\[en]9 or a\[en]f) and +.BI \[ha]\[ha] c +.RI (character\~ c +in the code point range 0\[en]127 decimal) +are recognized; +other uses +.RB of\~ \[ha] +cause an error. +. +. +.IP \[bu] +No macro expansion is performed. +. +. +.IP \[bu] +.B hpf +checks for the expression +.BR \[rs]patterns{ .\|.\|. } +(possibly with whitespace before or after the braces). +. +Everything between the braces is taken as hyphenation patterns. +. +Consequently, +.RB \[lq] { \[rq] +and +.RB \[lq] } \[rq] +are not allowed in patterns. +. +. +.IP \[bu] +Similarly, +.BR \[rs]hyphenation{ .\|.\|. } +gives a list of hyphenation exceptions. +. +. +.IP \[bu] +.B \[rs]endinput +is recognized also. +. +. +.IP \[bu] +For backwards compatibility, +if +.B \[rs]patterns +is missing, +the whole file is treated as a list of hyphenation patterns +(but the +.RB \[lq] % \[rq] +character is still recognized as the start of a comment). +.RE +. +. +.IP +Use the +.B hpfcode +request +(see below) +to map the encoding used in hyphenation pattern files to +.IR groff 's +input encoding. +. +. +.IP +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. +. +By default, +.I troffrc +loads the localization file for English. +. +(As of +.I groff +1.23.0, +localization files for Czech +.RI ( cs ), +German +.RI ( de ), +English +.RI ( en ), +French +.RI ( fr ), +Japanese +.RI ( ja ), +Swedish +.RI ( sv ), +and Chinese +.RI ( zh ) +exist.) +. +For Western languages, +the localization file sets the hyphenation mode and loads hyphenation +patterns and exceptions. +. +. +.IP +A second call to +.B hpf +(for the same language) +replaces the old patterns with the new ones. +. +. +.IP +Invoking +.B hpf +causes an error if there is no hyphenation language. +. +. +.IP +If no +.B hpf +request is specified +(either in the document, +in a file loaded at startup, +or in a macro package), +GNU +.I troff \" GNU +won't automatically hyphenate at all. +. +. +.TP +.BI .hpfa\~ pattern-file +As +.BR hpf , +except that the hyphenation patterns and exceptions from +.I pattern-file +are appended to the patterns already applied to the hyphenation language +of the environment. +. +. +.TP +.BI .hpfcode\~ "a b"\c +.RI \~[ "c d" "] .\|.\|." +Define mapping values for character codes in pattern files. +. +This is an older mechanism no longer used by +.IR groff 's +own macro files; +for its successor, +see +.B hcode +above. +. +.B hpf +or +.B hpfa +apply the mapping +after reading or appending to the active list of patterns. +. +Its arguments are pairs of character codes\[em]integers from 0 to\~255. +. +The request maps character +.RI code\~ a +to +.RI code\~ b , +.RI code\~ c +to +.RI code\~ d , +and so on. +. +Character codes that would otherwise be invalid in +.I groff +can be used. +. +By default, +every code maps to itself except those for letters \[lq]A\[rq] to +\[lq]Z\[rq], +which map to those for \[lq]a\[rq] to \[lq]z\[rq]. +. +. +.TP +.BR .hym\~ [\c +.IR length ] +Set the (right) hyphenation margin +.RI to\~ length . +. +If the adjustment mode is not +.RB \[lq] b \[rq] +or +.RB \[lq] n \[rq], +the line is not hyphenated if it is shorter than +.IR length . +. +Without an argument, +the default hyphenation margin is reset to its default value, +0. +. +The default scaling unit +.RB is\~\[lq] m \[rq]. +. +The hyphenation margin is associated with the environment. +. +A negative argument resets the hyphenation margin to zero, +emitting a warning in category +.RB \[lq] range \[rq]. +. +. +.TP +.BR .hys\~ [\c +.IR hyphenation-space ] +Suppress hyphenation of the line in adjustment modes +.RB \[lq] b \[rq] +or +.RB \[lq] n \[rq], +if it can be justified by adding no more than +.I hyphenation-space +extra space to each inter-word space. +. +Without an argument, +the hyphenation space adjustment threshold is set to its default value, +0. +. +The default scaling unit +.RB is\~\[lq] m \[rq]. +. +The hyphenation space adjustment threshold is associated with the +current environment. +. +A negative argument resets the hyphenation space adjustment threshold to +zero, +emitting a warning in category +.RB \[lq] range \[rq]. +. +. +.TP +.BI .itc\~ n\~name +As +.RB \[lq] it \[rq], +but lines interrupted with the +.B \[rs]c +escape sequence are not applied to the line count. +. +. +.TP +.BI .kern\~ n +If +.I n +is non-zero or missing, +enable pairwise kerning +(the default), +otherwise disable it. +. +. +.TP +.BI .length\~ "reg anything" +Compute the number of characters in +.I anything +and return the count in the register +.IR reg . +. +If +.I reg +doesn't exist, +it is created. +. +.I anything +is read in copy mode. +. +. +.RS +.IP +.EX +.B .ds xxx abcd\eh\[aq]3i\[aq]efgh +.B .length yyy \e*[xxx] +.B \en[yyy] +14 +.EE +.RE +. +. +.TP +.BI .linetabs\~ n +.RS +If +.I n +is non-zero or missing, +enable line-tabs mode, +otherwise disable it +(the default). +. +In this mode, +tab stops are computed relative to the start of the pending output line, +instead of the drawing position corresponding to the start of the input +line. +. +Line-tabs mode is a property of the environment. +. +. +.P +For example, +the following +. +. +.RS +.P +.ne 6v+\n(.Vu +.EX +\&.ds x a\[rs]t\[rs]c +\&.ds y b\[rs]t\[rs]c +\&.ds z c +\&.ta 1i 3i +\&\[rs]*x +\&\[rs]*y +\&\[rs]*z +.EE +.RE +. +yields +. +.RS +.EX +a b c +.EE +.RE +. +whereas in line-tabs mode, +the same input gives +. +.RS +.EX +a b c +.EE +.RE +. +instead. +.RE +. +. +.TP +.BR .lsm\~ [\c +.IR name ] +Set the leading space macro (trap) to +.IR name . +. +If there are leading space characters on an input line, +.I name +is invoked in lieu of the usual +.I roff +behavior; +the leading spaces are removed. +. +The count of leading spaces on an input line is stored in +.BR \[rs]n[lsn] , +and the amount of corresponding horizontal motion in +.BR \[rs]n[lss] , +irrespective of whether a leading space trap is set. +. +When it is, +the leading spaces are removed from the input line, +and no motion is produced before calling +.IR name . +. +If no argument is supplied, +the default leading space behavior is (re-)established. +. +. +.TP +.BI .mso\~ file +As +.RB \[lq] so \[rq], +except that +.I file +is sought in the same directories as arguments to the +.MR groff @MAN1EXT@ +and +.MR @g@troff @MAN1EXT@ +.B \-m +command-line option are +(the \[lq]tmac path\[rq]). +. +If the file name to be interpolated has the form +.IB name .tmac +and it isn't found, +.B mso +tries to include +.BI tmac. name +instead and vice versa. +. +If +.I file +does not exist, +a warning in category +.RB \[lq] file \[rq] +is emitted +and the request has no other effect. +. +. +.TP +.BI .msoquiet\~ file +As +.BR mso , +but no warning is emitted if +.I file +does not exist. +. +. +.TP +.BI .nop \~anything +Interpret +.I anything +as if it were an input line. +. +.B nop +resembles +.RB \[lq] ".if 1" \[rq]; +it puts a break on the output if +.I anything +is empty. +. +Unlike +.RB \[lq]\| if \|\[rq], +it cannot govern conditional blocks. +. +Its application is to maintain consistent indentation within macro +definitions even when producing text lines. +. +. +.TP +.B .nroff +Make the +.B n +conditional expression evaluate true and +.B t +false. +. +See +.BR troff . +. +. +.TP +.BI .open\~ "stream file" +Open +.I file +for writing and associate +.I stream +with it. +. +See +.B write +and +.BR close . +. +. +.TP +.BI .opena\~ "stream file" +As +.BR open , +but if +.I file +exists, +append to it instead of truncating it. +. +. +.TP +.BI .output\~ contents +Emit +.IR contents , +which are read in copy mode, +to the formatter output; +this is similar to +.B \[rs]!\& +used in the top-level diversion. +. +An initial neutral double quote in +.I contents +is stripped to allow the embedding of leading spaces. +.\" XXX: useless request warning if no argument? +. +. +.TP +.B .pev +Report the state of the current environment followed by that of all +other environments to the standard error stream. +. +. +.TP +.B .pnr +Write the names and values of all currently defined registers to the +standard error stream. +. +. +.TP +.BI .psbb \~file +Get the bounding box of a PostScript image +.IR file . +. +This file must conform to Adobe's Document Structuring Conventions; +the request attempts to extract the bounding box values from a +.B \%%%BoundingBox +comment. +. +After invocation, +the +.I x +and +.I y +coordinates +(in PostScript units) +of the lower left and upper right corners can be found in the registers +.BR \[rs]n[llx] , +.BR \[rs]n[lly] , +.BR \[rs]n[urx] , +and +.BR \[rs]n[ury] , +respectively. +. +If an error occurs, +these four registers are set to zero. +. +. +.TP +.BI .pso \~command +As +.RB \[lq] so \[rq], +except that input comes from the standard output stream of +.IR command . +. +. +.TP +.B .ptr +Report the names and vertical positions of all page location traps +to the standard error stream. +. +Empty slots in the list are shown as well, +because they can affect the visibility of subsequently planted traps. +. +. +.TP +.BI .pvs \~\[+-]n +Set the post-vertical line spacing +.RI to\~ n ; +default scaling unit +.RB is\~\[lq] p \[rq]. +. +With no argument, +the post-vertical line space is set to its previous value. +. +. +.IP +In GNU +.IR troff , \" GNU +the distance between text baselines consists of the extra pre-vertical +line spacing set by the most negative +.B \[rs]x +argument on the pending output line, +the vertical spacing +.RB ( vs ), +the extra post-vertical line spacing set by the most positive +.B \[rs]x +argument on the pending output line, +and the post-vertical line spacing set by this request. +. +. +.TP +.BI .rchar\~ c\~\c +\&.\|.\|. +Remove definition of each ordinary or special character +.IR c , +undoing the effect of a +.BR char , +.BR fchar , +or +.B schar +request. +. +Glyphs, +which are defined by font description files, +cannot be removed. +. +Spaces and tabs may separate +.I c +arguments. +. +. +.TP +.B .return +Within a macro, +return immediately. +. +If called with an argument, +return twice, +namely from the current macro and from the macro one level higher. +. +No effect otherwise. +.\" XXX: useless request warning? +. +. +.TP +.BI .rfschar\~ "f c\~"\c +\&.\|.\|. +Remove each fallback special +.RI character\~ c +for font +.IR f . +. +Spaces and tabs may separate +.I c +arguments. +. +See +.BR fschar . +. +. +.TP +.BR .rj\~ [\c +.IR n ] +Right-align the +.RI next\~ n +input lines. +. +Without an argument, +right-align the next input line. +. +.B rj +implies +.RB \[lq] ".ce 0" \[rq], +and +.B ce +implies +.RB \[lq] ".rj 0" \[rq]. +. +. +.TP +.BI .rnn \~r1\~r2 +Rename register +.I r1 +to +.IR r2 . +. +If +.I r1 +doesn't exist, +the request is ignored. +. +. +.TP +.BI .schar\~ c\~contents +Define global fallback character +.I c +as +.IR contents . +. +See +.BR char ; +the distinction is that a character defined with +.B schar +is located after the list of fonts declared with the +.B \%special +request but before any mounted special fonts. +. +. +.TP +.BR .shc \~\c +.RI [ c ] +Set the soft hyphen character, +inserted when a word is hyphenated automatically or at a hyphenation +character, +.RI to\~ c . +. +If +.I c +is omitted, +the soft hyphen character is set to the default, +.BR \[rs][hy] . +. +If the selected glyph does not exist in the font in use at a potential +hyphenation point, +then the line is not broken at that point. +. +Neither character definitions +.RB ( char +and similar) +nor translations +.RB ( tr +and similar) +are considered when assigning the soft hyphen character. +. +. +.TP +.BI .shift\~ n +In a macro, +shift the arguments by +.I n +positions: +.RI argument\~ i +becomes argument +.IR i \|\-\| n ; +arguments 1 +.RI to\~ n +are no longer available. +. +.RI If\~ n +is missing, +arguments are shifted by\~1. +. +No effect otherwise. +.\" XXX: useless request warning? +. +. +.TP +.BI .sizes\~ "s1 s2\~"\c +.RI .\|.\|.\~ sn\~\c +.RB [ 0 ] +Set the available type sizes to +.IR s1 , +.IR s2 , +\&.\|.\|.\& +.I sn +scaled points. +. +The list of sizes can be terminated by an +.RB optional\~\[lq] 0 \[rq]. +. +Each +.I si +can also be a range +.IR m \(en n . +. +In contrast to the device description file directive of the same name +(see +.MR groff_font @MAN5EXT@ ), +the argument list can't extend over more than one line. +. +. +.TP +.BI .soquiet\~ file +As +.RB \[lq] so \[rq], +but no warning is emitted if +.I file +does not exist. +. +. +.TP +.BI .special\~ f\~\c +\&.\|.\|. +Declare each font +.I f +as special, +searching it for glyphs not found in the selected font. +. +Without arguments, +this list of special fonts is made empty. +. +. +.TP +.BR .spreadwarn\~ [\c +.IR limit ] +Emit a +.B break +warning if the additional space inserted for each space between words in +an output line adjusted to both margins with +.RB \[lq] .ad\~b \[rq] +is larger than or equal to +.IR limit . +. +A negative value is treated as zero; +an absent argument toggles the warning on and off without changing +.IR limit . +. +The default scaling unit is +.BR m . +. +At startup, +.B spreadwarn +is inactive and +.I limit +is 3\~m. +. +. +.IP +For example, +.RB \[lq] ".spreadwarn 0.2m" \[rq] +causes a warning if +.B break +warnings are not suppressed and +.I @g@troff +must add 0.2\~m or more for each inter-word space in a line. +. +. +.TP +.BI .stringdown \~str +.TQ +.BI .stringup \~str +Alter the string named +.I str +by replacing each of its bytes with its +lowercase +.RB ( down ) +or uppercase +.RB ( up ) +version +(if one exists). +. +Special characters +(see +.MR groff_char @MAN7EXT@ ) +will often transform in the expected way due to the regular naming +convention for accented characters. +. +When they do not, +use substrings and/or catenation. +. +. +.IP +.RS +.RS +.EX +.B .ds resume R\e[\[aq]e]sum\e[\[aq]e]\e" +.B \e*[resume] +.B .stringdown resume +.B \e*[resume] +.B .stringup resume +.B \e*[resume] +R\['e]sum\['e] r\['e]sum\['e] R\['E]SUM\['E] +.EE +.RE +.RE +. +. +.TP +.BI .sty\~ n\~s +Associate abstract +.RI style\~ s +with font mounting +.RI position\~ n . +. +. +.TP +.BI .substring\~ "string start\~"\c +.RI [ end ] +Replace the string named +.I string +with its substring bounded by the indices +.I start +and +.IR end , +inclusively. +. +The first character in the string has index\~0. +. +If +.I end +is omitted, +it is implicitly set to the largest valid value +(the string length minus one). +. +Negative indices count backwards from the end of the string: +the last character has index\~\-1, +the character before the last has index\~\-2, +and so on. +. +. +.RS +.IP +.EX +.B .ds xxx abcdefgh +.B .substring xxx 1 \-4 +.B \e*[xxx] +bcde +.B .substring xxx 2 +.B \e*[xxx] +de +.EE +.RE +. +. +.TP +.BI .tkf\~ f\~s1\~n1\~s2\~n2 +Enable track kerning for font\~\c +.IR f . +When the current font is\~\c +.I f +the width of every glyph is increased by an amount between +.I n1 +and +.IR n2 ; +when the current type size is less than or equal to +.I s1 +the width is increased by +.IR n1 ; +when it is greater than or equal to +.I s2 +the width is increased by +.IR n2 ; +when the type size is greater than or equal to +.I s1 +and less than or equal to +.I s2 +the increase in width is a linear function of the type size. +. +. +.TP +.BI .tm1\~ message +As +.B tm +request, +but strips a leading neutral double quote from +.I message +to allow the embedding of leading spaces. +. +. +.TP +.BI .tmc\~ message +As +.B tm1 +request, +but does not append a newline. +. +. +.TP +.BI .trf\~ file +Transparently output the contents of file +.IR file . +. +Each line is output as if preceded by +.BR \[rs]! ; +however, +the lines are not subject to copy-mode interpretation. +. +If the file does not end with a newline, +then a newline is added. +. +Unlike +.BR cf , +.I file +cannot contain characters +that are invalid as input to GNU +.IR troff . \" GNU +. +. +.IP +For example, +you can define a macro\~\c +.I x +containing the contents of file\~\c +.IR f , +using +. +. +.RS +.IP +.ne 2v+\n(.Vu +.EX +\&.di x +\&.trf f +\&.di +.EE +.RE +. +. +.TP +.BI .trin\~ abcd +This is the same as the +.B tr +request except that the +.B asciify +request uses the character code +(if any) +before the character translation. +. +Example: +. +. +.RS +.IP +.EX +\&.trin ax +\&.di xxx +\&a +\&.br +\&.di +\&.xxx +\&.trin aa +\&.asciify xxx +\&.xxx +.EE +.RE +. +. +.IP +The result is \[lq]x\~a\[rq]. +. +Using +.BR tr , +the result would be \[lq]x\~x\[rq]. +. +. +.TP +.BI .trnt\~ abcd +This is the same as the +.B tr +request except that the translations do not apply to text that is +transparently throughput into a diversion with +.BR \[rs]! . +For example, +. +. +.RS +.IP +.EX +\&.tr ab +\&.di x +\&\[rs]!.tm a +\&.di +\&.x +.EE +.RE +. +. +.IP +prints\~\c +.BR b ; +if +.B trnt +is used instead of +.B tr +it prints\~\c +.BR a . +. +. +.TP +.B .troff +Make the +.B t +conditional expression evaluate true and +.B n +false. +. +See +.BR nroff . +. +. +.TP +.BI .unformat\~ div +Unformat the diversion +.IR div . +. +Unlike +.BR asciify , +.B unformat +handles only tabs and spaces between words, +the latter usually arising from spaces or newlines in the input. +. +Tabs are treated as input tokens, +and spaces become adjustable again. +. +The vertical sizes of lines are not preserved, +but glyph information +(font, +type size, +space width, +and so on) +is retained. +. +. +.TP +.BI .vpt\~ n +If +.I n +is non-zero or missing, +enable vertical position traps +(the default), +otherwise disable them. +. +Vertical position traps are those set by the +.BR ch , +.BR wh , +and +.B dt +requests. +. +. +.TP +.BR .warn\~ [\c +.IR n ] +Select the categories, +or \[lq]types\[rq], +of reported warnings. +. +.IR n \~is +the sum of the numeric codes associated with each warning category that +is to be enabled; +all other categories are disabled. +. +The categories and their associated codes are listed in section +\[lq]Warnings\[rq] of +.MR @g@troff @MAN1EXT@ . +.\" TODO: Maybe move that table to groff(7). +. +For example, +.RB \[lq] ".warn 0" \[rq] +disables all warnings, +and +.RB \[lq] ".warn 1" \[rq] +disables all warnings except those about missing glyphs. +. +If no argument is given, +all warning categories are enabled. +. +. +.TP +.BI .warnscale\~ si +Set the scaling unit used in warnings to +.IR si . +. +Valid values for +.I si +are +.BR u , +.B i +(the default), +.BR c , +.BR p , +.RB and\~ P . +. +. +.TP +.BI .while \~cond-expr\~anything +Evaluate the conditional expression +.IR cond-expr , +and repeatedly execute +.I anything +unless and until +.I cond-expr +evaluates false. +. +.I anything, +which is often a conditional block, +is referred to as the +.B while +request's +.I body. +. +. +.IP +.I @g@troff +treats the body of a +.B while +request similarly to that of a +.B de +request +(albeit one not read in copy mode), +but stores it under an internal name and deletes it when the loop +finishes. +. +The operation of a macro containing a +.B while +request can slow significantly if the +.B while +body is large. +. +Each time the macro is executed, +the +.B while +body is parsed and stored again. +. +An often better solution\[em]and one that is more portable, +since AT&T +.I troff \" AT&T +lacked the +.B while +request\[em]is to instead write a recursive macro. +. +It will be parsed only once (unless you redefine it). +. +To prevent infinite loops, +the default number of available recursion levels is 1,000 or somewhat +less (because things other than macro calls can be on the input stack). +. +You can disable this protective measure, +or raise the limit, +by setting the +.B slimit +register. +. +See section \[lq]Debugging\[rq] below. +. +. +.IP +If a +.B while +body begins with a conditional block, +its closing brace must end an input line. +. +. +.IP +The +.B break +and +.B continue +requests alter a +.B while +loop's flow of control. +. +. +.TP +.BI .write\~ stream\~anything +Write +.I anything +to +.IR stream , +which must previously have been the subject of an +.B open +request, +followed by a newline. +. +.I anything +is read in copy mode. +. +An initial neutral double quote in +.I anything +is stripped to allow the embedding of leading spaces. +. +. +.TP +.BI .writec\~ stream\~anything +As +.BR write , +but without a trailing newline. +. +. +.TP +.BI .writem\~ "stream name" +Write the contents of the macro or string +.I name +to +.IR stream , +which must previously have been the subject of an +.B open +request. +. +.I name +is read in copy mode. +. +. +.br +.ne 6v +.\" ==================================================================== +.SS "Extended requests" +.\" ==================================================================== +. +.\" XXX: .cf might better belong in "Implementation differences". +.TP +.BI .cf\~ file +In a diversion, +embed an object which, +when reread, +will cause the contents of +.I file +to be copied verbatim to the output. +. +In AT&T +.IR troff , +the contents of +.I file +are immediately copied to the output regardless of whether a diversion +is being written to; +this behavior is so anomalous that it must be considered a bug. +. +. +.TP +.BI .de\~ name\~\c +.RI [ end-name ] +.TQ +.BI .am\~ name\~\c +.RI [ end-name ] +.TQ +.BI .ds\~ name\~\c +.RI [ contents ] +.TQ +.BI .as\~ name\~\c +.RI [ contents ] +In compatibility mode, +these requests behave similarly to +.BR de1 , +.BR am1 , +.BR ds1 , +and +.BR as1 , +respectively: +a \[lq]compatibility save\[rq] token is inserted at the beginning, +and a \[lq]compatibility restore\[rq] token at the end, +with compatibility mode switched on during execution. +. +. +.TP +.BI .hy\~ n +New values 16 and\~32 are available; +the former enables hyphenation before the last character in a word, +and the latter enables hyphenation after the first character in a word. +. +. +.TP +.BI .ss\~ word-space-size\~\c +.RI [ additional-sentence-space-size ] +A second argument sets the amount of additional space separating +sentences on the same output line. +. +If omitted, +this amount is set to +.IR word-space-size . +. +Both arguments are in twelfths of current font's space width +(typically one-fourth to one-third em for Western scripts; +see +.MR groff_font @MAN5EXT@ ). +. +The default for both parameters is\~12. +. +Negative values are erroneous. +. +. +.TP +.BR .ta\~ [[\c +.IR "n1 n2\~" .\|.\|.\~ nn \~]\c +.BR T \~\c \" space in roman because we must use 2-font macro with \c +.IR "r1 r2\~" .\|.\|.\~ rn ] +.I groff +supports an extended syntax to specify repeating tab stops after +the +.RB \[lq] T \[rq] +mark. +. +These values are always taken as relative distances from the previous +tab stop. +. +This is the idiomatic way to specify tab stops at equal intervals in +.IR groff . +. +. +.IP +The syntax summary above instructs +.I groff +to set tabs at positions +.IR n1 , +.IR n2 , +\&.\|.\|.\|, +.IR nn , +then at +.IR nn \|+\| r1 , +.IR nn \|+\| r2 , +\&.\|.\|.\|, +.IR nn \|+\| rn , +then at +.IR nn \|+\| rn \|+\| r1 , +.IR nn \|+\| rn \|+\| r2 , +\&.\|.\|.\|, +.IR nn \|+\| rn \|+\| rn , +and so on. +. +. +.\" ==================================================================== +.SS "New registers" +.\" ==================================================================== +. +GNU +.I troff \" GNU +exposes more formatter state via many new read-only registers. +. +Their names often correspond to the requests that affect them. +. +. +.TP 12n +.B \[rs]n[.br] +Within a macro call, +interpolate\~1 +if the macro is called with the \[lq]normal\[rq] control character +(\[lq].\[rq] by default), +and\~0 otherwise. +. +This facility allows the reliable modification of requests. +. +Using this register outside of a macro definition makes no sense. +. +. +.RS +.IP +.ne 6v+\n(.Vu +.EX +\&.als bp*orig bp +\&.de bp +\&.tm before bp +\&.ie \[rs]\[rs]n[.br] .bp*orig +\&.el \[aq]bp*orig +\&.tm after bp +\&.. +.EE +.RE +. +. +.TP +.B \[rs]n[.C] +Interpolate 1\~if compatibility mode is in effect, +0\~otherwise. +. +See +.BR cp . +. +. +.TP +.B \[rs]n[.cdp] +Interpolate depth of last glyph added to the environment. +. +It is positive if the glyph extends below the baseline. +. +. +.TP +.B \[rs]n[.ce] +Interpolate number of input lines remaining to be centered. +. +. +.TP +.B \[rs]n[.cht] +Interpolate height of last glyph added to the environment. +. +It is positive if the glyph extends above the baseline. +. +. +.TP +.B \[rs]n[.color] +Interpolate 1\~if colors are enabled, +0\~otherwise. +. +. +.TP +.B \[rs]n[.cp] +Within a +.RB \[lq] do \[rq] +request, +interpolate the saved value of compatibility mode +(see +.B \[rs]n[.C] +above). +. +. +.TP +.B \[rs]n[.csk] +Interpolate skew of last glyph added to the environment. +. +The +.I skew +of a glyph is how far to the right of the center of a glyph the center +of an accent over that glyph should be placed. +. +. +.TP +.B \[rs]n[.ev] +Interpolate name of current environment. +. +This is a string-valued register. +. +. +.TP +.B \[rs]n[.fam] +Interpolate name of default font family. +. +This is a string-valued register. +. +. +.TP +.B \[rs]n[.fn] +Interpolate resolved name of the selected font. +. +This is a string-valued register. +. +. +.TP +.B \[rs]n[.fp] +Interpolate next free font mounting position. +. +. +.TP +.B \[rs]n[.g] +Interpolate\~1. +. +Test with +.RB \[lq]\| if \|\[rq] +or +.B ie +to check whether GNU +.I troff \" GNU +is the formatter. +. +. +.TP +.B \[rs]n[.height] +Interpolate font height. +. +See +.BR \[rs]H . +. +. +.TP +.B \[rs]n[.hla] +Interpolate hyphenation language of the environment. +. +This is a string-valued register. +. +. +.TP +.B \[rs]n[.hlc] +Interpolate count of immediately preceding consecutive hyphenated lines +in the environment. +. +. +.TP +.B \[rs]n[.hlm] +Interpolate maximum number of consecutive hyphenated lines allowed in +the environment. +. +. +.TP +.B \[rs]n[.hy] +Interpolate hyphenation mode of the environment. +. +. +.TP +.B \[rs]n[.hym] +Inteprolate hyphenation margin of the environment. +. +. +.TP +.B \[rs]n[.hys] +Interpolate hyphenation space adjustment threshold of the environment. +. +. +.TP +.B \[rs]n[.in] +Interpolate indentation amount applicable to the pending output line. +. +. +.TP +.B \[rs]n[.int] +Interpolate\~1 if the previous output line was interrupted +(ended with +.BR \[rs]c ), +0\~otherwise. +. +. +.TP +.B \[rs]n[.kern] +Interpolate\~1 if pairwise kerning is enabled, +0\~otherwise. +. +. +.TP +.B \[rs]n[.lg] +Interpolate ligature mode. +. +. +.TP +.B \[rs]n[.linetabs] +Interpolate\~1 if line-tabs mode is enabled, +0\~otherwise. +. +. +.TP +.B \[rs]n[.ll] +Interpolate line length applicable to the pending output line. +. +. +.TP +.B \[rs]n[.lt] +Interpolate title line length. +. +. +.TP +.B \[rs]n[.m] +Interpolate name of the selected stroke color. +. +This is a string-valued register. +. +. +.TP +.B \[rs]n[.M] +Interpolate name of the selected fill color. +. +This is a string-valued register. +. +. +.TP +.B \[rs]n[.ne] +Interpolate amount of space demanded by the most recent +.B ne +request that caused a page location trap to be sprung. +. +See +.BR \[rs]n[.trunc] . +. +. +.TP +.B \[rs]n[.nm] +Interpolate\~1 if output line numbering is enabled +(even if temporarily suppressed), +0\~otherwise. +. +. +.TP +.B \[rs]n[.ns] +Interpolate\~1 if no-space mode is enabled, +0\~otherwise. +. +. +.TP +.B \[rs]n[.O] +Interpolate output suppression level. +. +See +.BR \[rs]O . +. +. +.TP +.B \[rs]n[.P] +Interpolate\~1 if the current page is selected for output. +. +See +.B \-o +command-line option to +.MR @g@troff @MAN1EXT@ . +. +. +.TP +.B \[rs]n[.pe] +Interpolate\~1 during page ejection, +0\~otherwise. +. +. +.TP +.B \[rs]n[.pn] +Interpolate next page number +(either that set by +.BR pn , +or that of the current page plus\~1). +. +. +.TP +.B \[rs]n[.ps] +Interpolate type size in scaled points. +. +. +.TP +.B \[rs]n[.psr] +Interpolate most recently requested type size in scaled points. +. +. +.TP +.B \[rs]n[.pvs] +Interpolate post-vertical line spacing amount. +. +. +.TP +.B \[rs]n[.rj] +Interpolate number of input lines remaining to be right-aligned. +. +. +.TP +.B \[rs]n[.slant] +Interpolate font slant. +. +See +.BR \[rs]S . +. +. +.TP +.B \[rs]n[.sr] +Interpolate most recently requested type size in points as a decimal +fraction. +. +This is a string-valued register. +. +. +.TP +.B \[rs]n[.ss] +.TQ +.B \[rs]n[.sss] +Interpolate values of minimal inter-word space and additional +inter-sentence space, +respectively, +in twelfths of the space width of the selected font. +. +. +.TP +.B \[rs]n[.sty] +Interpolate selected abstract font style, +if any. +. +This is a string-valued register. +. +. +.TP +.B \[rs]n[.tabs] +Interpolate representation of the tab stop settings in a form suitable +for passage to the +.B ta +request. +. +. +.TP +.B \[rs]n[.trunc] +Interpolate amount of vertical space truncated by the most recently +sprung page location trap, +or, +if the trap was sprung by an +.B ne +request, +minus the amount of vertical motion produced by the +.B ne +request. +. +In other words, +at the point a trap is sprung, +.B \[rs]n[.trunc] +represents the difference of what the vertical position would have +been but for the trap, +and what the vertical position actually is. +. +See +.BR \[rs]n[.ne] . +. +. +.TP +.B \[rs]n[.U] +Interpolate\~1 if in unsafe mode, +0\~otherwise. +. +See +.B \-U +command-line option to +.MR @g@troff @MAN1EXT@ . +. +. +.TP +.B \[rs]n[.vpt] +Interpolate\~1 if vertical position traps are enabled, +0\~otherwise. +. +. +.TP +.B \[rs]n[.warn] +Interpolate warning mode. +. +See section \[lq]Warnings\[rq] of +.MR @g@troff @MAN1EXT@ . +.\" TODO: Maybe move that table to groff(7). +. +. +.TP +.B \[rs]n[.x] +Interpolate major version number of the running +.I @g@troff +formatter. +. +For example, +if the version number is 1.23.0, +then +.B \[rs]n[.x] +contains\~1. +. +. +.TP +.B \[rs]n[.y] +Interpolate minor version number of the running +.I @g@troff +formatter. +. +For example, +if the version number is 1.23.0, +then +.B \[rs]n[.y] +contains\~23. +. +. +.TP +.B \[rs]n[.Y] +Interpolate revision number of the running +.I @g@troff +formatter. +. +For example, +if the version number is 1.23.0, +then +.B \[rs]n[.Y] +contains\~0. +. +. +.TP +.B \[rs]n[.zoom] +Interpolate magnification of font, +in thousandths, +or\~0 if magnification unused. +. +See +.BR fzoom . +. +. +.P +The following (writable) registers are set by the +.B psbb +request. +. +. +.TP +.B \[rs]n[llx] +.TQ +.B \[rs]n[lly] +.TQ +.B \[rs]n[urx] +.TQ +.B \[rs]n[ury] +Interpolate the +(upper, +lower, +left, +right) +bounding box values +(in PostScript units) of the most recently processed PostScript image. +. +. +.P +The following (writable) registers are set by the +.B \[rs]w +escape sequence. +. +. +.TP 8n +.B \[rs]n[rst] +.TQ +.B \[rs]n[rsb] +Like +.B \[rs]n[st] +and +.BR \[rs]n[sb] , +but taking account of the heights and depths of glyphs. +. +In other words, +these registers store the highest and lowest vertical positions attained +by the argument formatted by the +.B \[rs]w +escape sequence, +doing what AT&T +.I troff \" AT&T +documented +.B \[rs]n[st] +and +.B \[rs]n[sb] +as doing. +. +. +.TP +.B \[rs]n[ssc] +The amount of horizontal space (possibly negative) that should be +added to the last glyph before a subscript. +. +. +.TP +.B \[rs]n[skw] +How far to right of the center of the last glyph in the +.B \[rs]w +argument, +the center of an accent from a roman font should be placed +over that glyph. +. +. +.P +Other writable registers are as follows. +. +Those relating to date and time are initialized using +.MR localtime 3 +at formatter startup. +. +. +.\" The `c.` register was documented in the January 1981 "Addendum to +.\" the Nroff/Troff User's Manual" (presumably by Kernighan), and is +.\" widely supported by descendants of his device-independent troff, but +.\" appears to have been overlooked in his 1992 revision of CSTR #54. +.TP 12n +.B \[rs]n[c.] +Interpolate input line number. +. +.B \[rs]n[.c] +is a read-only alias of this register. +. +. +.TP +.B \[rs]n[hours] +Interpolate number of hours elapsed since midnight. +. +. +.TP +.B \[rs]n[hp] +Interpolate horizontal position relative to that at the start of the +input line. +. +. +.br +.ne 3v +.TP +.B \[rs]n[lsn] +.TQ +.B \[rs]n[lss] +Interpolate count of leading spaces on input line and amount of +corresponding horizontal motion, +respectively. +. +. +.TP +.B \[rs]n[minutes] +Interpolate number of minutes elapsed in the hour. +. +. +.TP +.B \[rs]n[seconds] +Interpolate number of seconds elapsed in the minute. +. +. +.TP +.B \[rs]n[systat] +Interpolate return value of +.MR system 3 +function executed by most recent +.B sy +request. +. +. +.TP +.B \[rs]n[slimit] +Interpolates maximum quantity of objects on +.IR @g@troff 's +internal input stack +(default: 1000). +. +If non-positive, +there is no limit: +recursion can continue until program memory is exhausted. +. +. +.TP +.B \[rs]n[year] +Interpolate Gregorian year. +. +AT&T +.IR troff 's \" AT&T +.B \[rs][yr] +interpolates the Gregorian year minus 1900. +. +. +.\" ==================================================================== +.SS Miscellaneous +.\" ==================================================================== +. +GNU +.I troff \" GNU +predefines one string, +.BR .T , +containing the argument given to the +.B \-T +command-line option, +namely the output device +(for example, +.B pdf +or +.BR utf8 ). +. +The (read-only) +.I register +.B .T +interpolates\~1 if GNU +.I troff \" GNU +is run with the +.B \-T +command-line option, +and 0\~otherwise. +. +. +.P +A font not listed in the output device's +.I DESC +file's +.B fonts +directive is automatically mounted at the next available font position +when it is selected. +. +If you mount a font explicitly with the +.B fp +request, +you should do so on the first unused position, +which can be found in the +.B .fp +register. +. +. +.P +Unparameterized string interpolation does not conceal the arguments to a +macro being interpreted. +. +Thus, +in a macro definition, +the call of another macro with the existing argument list, +. +.RS +.EX +.BI . xx\~ \[rs]\[rs]$@ +.EE +.RE +. +is more efficiently done with +. +.RS +.EX +.BI \[rs]\[rs]*[ xx ]\[rs]\[rs] +.EE +.RE +. +(that is, +with string interpolation). +. +The trailing backslashes prevent the final newline in the macro +definition from being interpolated, +potentially putting an unwanted blank line on the output. +. +See section \[lq]Punning Names\[rq] in +.MR groff @MAN7EXT@ . +. +. +.\" XXX: Is this really not an AT&T troff feature? +.P +If a font description file contains pairwise kerning information, +glyphs from that font are kerned. +. +Kerning between two glyphs can be inhibited by placing a dummy character +.B \[rs]& +between them. +. +. +.P +GNU +.I troff \" GNU +keeps track of the nesting depth of escape sequence +interpolations and other uses of delimiters, +as in the +.B tl +request and the output comparison operator +(that is, +input like +.B \[aq]foo\[aq]bar\[aq] +as a conditional expression), +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. +. +Use visible characters as delimiters in GNU +.IR troff , \" GNU +not \[lq]ASCII\[rq] controls like BEL (Control+G). +. +The implementation of +.B \[rs]$@ +ensures that the double quotes surrounding an argument appear at an +interpolation depth different from that of the arguments themselves. +. +Similarly, +in bracket-form escape sequences like +.B \[rs]f[ZCMI], +a right bracket +.B ] +does not end the sequence unless it occurs at the same interpolation +depth as the +.RB opening\~ [ , +so input like +. +.RS +.EX +\[rs]f[\[rs]*[my-family]\[rs]*[my-style]] +.EE +.RE +. +works as desired. +. +In compatibility mode, +no attention is paid to the interpolation depth. +. +. +.P +In +GNU +.IR troff , \" GNU +the +.B tr +request can map characters to the unbreakable space escape sequence +.B \[rs]\[ti] +as a special case +.RB ( tr +normally operates only on +.IR characters ). +. +This feature replaces the odd-parity +.B tr +mapping trick used in AT&T +.I troff \" AT&T +documents, +where a character, +often +.BR \[ti] , +was \[lq]sacrificed\[rq] by mapping it to \[lq]nothing\[rq], +drafting it into use as an unadjustable, +unbreakable space. +. +(This feature was gratuitous even in early AT&T +.I troff, \" AT&T +which supported the +.BI \[rs] space +escape sequence by 1976.) \" see CSTR #54 of that year +. +Often, +it makes more sense to use +GNU +.IR troff 's \" GNU +.B \[rs]\[ti] +escape sequence instead, +which has been adopted by every other active +.I troff +implementation except that of Illumos, +as well as by the +.RI non -troff +.IR mandoc . +. +Translation of a character to +.B \[rs]\[ti] +is unnecessary. +. +. +.P +GNU +.I troff \" GNU +permits tabs and spaces after the first dot on a control line that ends +a macro definition. +. +.RS +.ne 5v+\n(.Vu +.EX +\&.if t \[rs]{\[rs] +\&.\& de bar +\&.\& nop Hello, I\[aq]m \[aq]bar\[aq]. +\&.\& . +\&.\[rs]} +.EE +.RS +. +. +.\" ==================================================================== +.SH "Formatter output" +.\" ==================================================================== +. +The page description language output by GNU +.I troff \" GNU +is modeled after that used by AT&T +.I troff \" AT&T +once the latter adopted a device-independent approach in the early +1980s. +. +Only the differences are documented here. +. +For a fuller discussion, +see +.MR groff_out @MAN5EXT@ . +.\" +.\" +.\" XXX: This feature is unused and documenting it gives a valuable +.\" hostage to fortune. +.\".P +.\"Note that single characters can have the eighth bit set, as can the +.\"names of fonts and special characters. +. +. +.P +Glyph and font names can be of arbitrary length; +postprocessors should not assume that they are at most two characters. +. +A glyph to be formatted is always drawn from the current font; +in contrast to AT&T device-independent +.IR troff , \" AT&T +drivers need not search special fonts to find a glyph. +. +. +.\" ==================================================================== +.SS Units +.\" ==================================================================== +. +The argument to the +.BR s \~command +is in scaled points +(units of +.RI points/ n , +where +.I n +is the argument to the +.B sizescale +command in the +.I DESC +file). +. +The argument to the +.RB \[lq] "x H" \[rq] +command is also in scaled points. +. +. +.\" ==================================================================== +.SS "Simple commands" +.\" ==================================================================== +. +.\" BEGIN Keep in sync with relevant portions of section "Simple +.\" commands" from groff_out(5). +.P +If the +.B tcommand +directive is present in the output device's +.I DESC +file, +GNU +.I troff \" GNU +employs the following two commands. +. +. +.TP +.BI t\~ xyz\c +\&.\|.\|. +Typeset word +.IR xyz ; +that is, +set a sequence of ordinary glyphs named +.IR x , +.IR y , +.IR z , +\&.\|.\|.\|, +terminated by a space or newline; +an optional second integer argument is ignored +(this allows the formatter to generate an even number of arguments). +.\" XXX: Why? +. +Each glyph is set at the current drawing position, +and the position is then advanced horizontally by the glyph's width. +. +A glyph's width is read from its metrics in the font description file, +scaled to the current type size, +and rounded to a multiple of the horizontal motion quantum. +. +Use the +.B C +command to emplace glyphs of special characters. +. +. +.TP +.BI u\~ "n xyz"\c +\&.\|.\|. +Typeset word +.I xyz +with track kerning. +. +As +.BR t , +but after placing each glyph, +the drawing position is further advanced horizontally +.RI by\~ n +basic units. +.\" END Keep in sync with relevant portions of section "Simple commands" +.\" from groff_out(5). +. +. +.P +New commands implement color support. +. +. +.TP +.BI mc\~ "cyan magenta yellow" +.TQ +.B md +.TQ +.BI mg\~ gray +.TQ +.BI mk\~ "cyan magenta yellow black" +.TQ +.BI mr\~ "red green blue" +Set the components of the stroke color with respect to various color +spaces. +. +.B md +resets the stroke color to the default value. +. +The arguments are integers in the range 0 to 65535. +. +. +.P +A new device control subcommand is available. +. +. +.TP +.BI "x u\~" n +If +.I n +is\~1, +start underlining of spaces. +. +If +.I n +is\~0, +stop underlining of spaces. +. +This facility is needed for the +.B cu +request in +.I nroff \" mode +mode and is ignored otherwise. +. +. +.\" ==================================================================== +.SS "Extended drawing commands" +.\" ==================================================================== +. +GNU +.I pic \" GNU +does not produce +.I @g@troff +escape sequences employing these extensions if its +.B \-n +option is given. +. +. +.TP +.BI Df\~ n +Set the shade of gray used to fill geometric objects to +.IR n , +which must be an integer. +. +0 corresponds to white and 1000 to black. +. +A grayscale ramp spans the two. +. +A value outside this range uses the stroke color as the fill color. +. +The fill color is opaque. +. +Normally the default is black, +but some drivers may provide a way of changing this. +. +.B Df +is obsolete since 2002, \" commit ea5a42d080, 2002-01-24 +superseded by +.B DFg +below. +. +. +.IP +The corresponding +.B \[rs]D\[aq]f\^\[aq] +escape sequence should not be used: +its argument is rounded to an integer multiple of the horizontal motion +quantum, +which can limit the precision +.RI of\~ n . +. +. +.TP +.BI DC\~ d +Draw a filled circle of diameter +.I d +with its leftmost point at the drawing position. +. +. +.TP +.BI DE\~ "h v" +Draw a filled ellipse, +of horizontal axis +.I h +and vertical axis +.IR v , +with its leftmost point at the drawing position. +. +. +.br +.ne 4v +.EQ +delim $$ +.EN +.TP +.\" `BR`, not `BI`, here, because eqn will take care of font changes. +.BR Dp\~ "$dx sub 1 ~ dy sub 1 ~ ldots ~ dx sub n ~ dy sub n$" +Draw a polygon with, +for $i = 1 , ldots , n + 1$, +its +.IR i th +vertex at the drawing position +. +$+ sum from { j = 1 } to { i - 1 } ( dx sub j , dy sub j )$. +. +.\" The following is implied by the math above, but let's be kind. +.I groff +output drivers automatically close polygons, +drawing a line from $( dx sub n , dy sub n )$ back to +$( dx sub 1 , dy sub 1 )$. +. +The drawing position is left at the last +.I specified +vertex, +but this may change in a future version of GNU +.IR troff . \" GNU +. +Heirloom Doctools +.IR troff , \" Heirloom +like DWB +.IR troff , \" DWB +by default does not close the polygon. +. +In its +.I groff +compatibility mode, +Heirloom closes the polygon but leaves the drawing position +.IR unchanged \[em]that +is, +at the polygon's +.I initial +drawing position. +. +. +.IP +At the moment, +GNU +.I pic \" GNU +uses this command only to generate triangles and rectangles. +. +. +.TP +.BR DP\~ "$dx sub 1 ~ dy sub 1 ~ ldots ~ dx sub n ~ dy sub n$" +As +.BR Dp , +but draw a filled rather than a stroked polygon. +. +. +.TP +.BI Dt\~ n +Set the line thickness to +.IR n \~\c +basic units. +. +AT&T +.I troff \" AT&T +output drivers use a thickness proportional to the type size; +this is the GNU +.I troff \" GNU +default. +. +A +.RI negative\~ n +requests this explicitly. +. +.RI An\~ n +of zero selects the smallest available line thickness. +. +. +.P +A difficulty arises in how the drawing position should be changed after +the execution of these commands. +. +This has little importance to most users, +since the output of GNU +.I grn \" GNU +and +.I pic \" GNU +does not depend on it. +. +Given a drawing command of the form +.BI D z +$x sub 1 ~ y sub 1 ~ ldots ~ x sub n ~ y sub n$, +where +.I z +is not +.B c +or +.BR e , +AT&T +.I troff \" AT&T +treats each $x sub i$ as a horizontal motion, +each $y sub i$ as a vertical one, +and therefore assumes that the width of the drawn object is +$sum from { i = 1 } to n x sub i$, +and its height is $sum from { i = 1 } to n y sub i$. +. +(Verify its assumption about height by examining the +.B st +and +.B sb +registers after using such a drawing command in a +.B \[rs]w +escape sequence). +. +For the sake of compatibility, +GNU +.I troff \" GNU +also follows this rule, +even though it frustrates extensions to the +.B D +command that set drawing parameters rather than rendering objects, +producing ugly results in the case of +.B Dt +and +.BR Df , +or otherwise don't parameterize objects as a series of vertices, +as with +GNU +.IR troff 's \" GNU +filled ellipse, +.BR DE . +. +Thus after executing a +.BR D \~command +of the form +.BI D z +$x sub 1 ~ y sub 1 ~ ldots ~ x sub n ~ y sub n$, +the drawing position should be increased by +. +$( sum from { i = 1 } to n x sub i , sum from { i = 1 } to n y sub i )$. +.EQ +delim off +.EN +. +In a future release, +GNU +.I troff \" GNU +and its output drivers may abandon the application of this assumption to +drawing commands not explicitly specified in the AT&T \[lq]Troff User's +Manual\[rq]. +. +. +.P +Fill color selection is implemented with another set of extensions. +. +. +.TP +.BI DFc\~ "cyan magenta yellow" +.TQ +.B DFd +.TQ +.BI DFg\~ gray +.TQ +.BI DFk\~ "cyan magenta yellow black" +.TQ +.BI DFr\~ "red green blue" +Set the components of the fill color as described under the +.B \[rs]M +escape sequence above. +. +.B DFd +restores the device's default fill color. +. +The drawing position is not updated, +in contrast to +.BR Df . +. +. +.\" ==================================================================== +.SS "Device control syntax extension" +.\" ==================================================================== +. +GNU +.I troff \" GNU +introduces a line continuation convention, +permitting the argument to the +.B x X +command to contain newlines. +. +A newline in the input is transformed to the sequence +.RI \[lq] newline\c +.BR + \[rq]. +. +When interpreting an +.B x X +command, +a postprocessor should therefore be prepared for a plus sign after a +newline; +if it occurs, +preserve the newline, +discard the plus sign, +and continue to collect the input into the argument of the +.B x X +command. +. +A newline +.I not +followed by a plus sign terminates the +.B x X +command. +. +An application of this feature is the embedding of PostScript or PDF +language command streams into +.I troff \" +output. +. +. +.P +GNU +.I troff \" GNU +guarantees that the first three output commands it emits are as follows. +. +. +.P +.RS +.EX +.RI x\~T\~ device +.RI x\~res\~ n\~h\~v +x init +.EE +.RE +. +. +.br +.ne 4v +.\" ==================================================================== +.SH Debugging +.\" ==================================================================== +. +In addition to AT&T +.IR troff 's \" AT&T +debugging features, +GNU +.I troff \" GNU +emits more error diagnostics when syntactical or semantic nonsense is +encountered and supports several warning categories; +the output of these can be selected with +.BR warn . +. +Also see the +.BR \-E , +.BR \-w , +and +.B \-W +options of +.MR @g@troff @MAN1EXT@ . +. +Backtraces can be automatically produced when errors or warnings occur +(the +.B \-b +option of +.MR @g@troff @MAN1EXT@ ) +or generated on demand +.RB ( backtrace ). +. +. +.P +.I groff +also adds more flexible diagnostic output requests +.RB ( tmc +and +.BR tm1 ). +. +More aspects of formatter state can be examined with requests that write +lists of +defined registers +.RB ( pnr ), +environments +.RB ( pev ), +and page location traps +.RB ( ptr ) +to the standard error stream. +. +. +.\" ==================================================================== +.SH "Implementation differences" +.\" ==================================================================== +. +.\" TODO: Resync with the node of this name in our Texinfo manual. +GNU +.IR troff 's \" GNU +features sometimes cause incompatibilities with documents written +assuming old implementations of +.IR troff . \" generic +. +Some GNU extensions to +.I troff \" generic +are supported by other implementations. +. +. +.P +When adjusting to both margins, +AT&T +.I troff \" AT&T +at first adjusts spaces starting from the right; +GNU +.I troff \" GNU +begins from the left. +. +Both implementations adjust spaces from opposite ends on alternating +output lines to prevent \[lq]rivers\[rq] in the text. +. +. +.P +GNU +.I troff \" GNU +does not always hyphenate words as AT&T +.I troff \" AT&T +does. +. +The AT&T implementation uses a set of hard-coded rules specific to +U.S.\& English, +while GNU +.I troff \" GNU +uses language-specific hyphenation pattern files derived from \*[tx]. +. +In some versions of +.I troff \" generic +there was limited space to store hyphenation exceptions +(arguments to the +.B hw +request); +GNU +.I troff \" GNU +has no such restriction. +. +. +.P +Long names may be GNU +.IR troff 's \" GNU +most obvious innovation. +. +AT&T +.I troff \" AT&T +interprets +.RB \[lq] .dsabcd \[rq] +as defining a string +.RB \[lq] ab \[rq] +with contents +.RB \[lq] cd \[rq]. +. +Normally, +GNU +.I troff \" GNU +interprets this as a call of a macro named +.RB \[lq] dsabcd \[rq]. +. +AT&T +.I troff \" AT&T +also interprets +.B \[rs]*[ +and +.B \[rs]n[ +as an interpolation of a string or register, +respectively, +called +.RB \[lq] [ \[rq]. +. +In GNU +.IR troff , \" GNU +however, +the +.RB \[lq] [ \[rq] +is normally interpreted as beginning the enclosure of a long identifier. +. +In compatibility mode, +GNU +.I troff \" GNU +interprets names in the traditional way, +which means that they are limited to one or two characters. +. +See the +.B \-C +option in +.MR @g@troff @MAN1EXT@ +and, +above, +the +.B .C +and +.B .cp +registers, +and +.B cp +and +.RB \[lq] do \[rq] +requests, +for more on compatibility mode. +. +. +.P +The register +.B \[rs]n[.cp] +is specialized and may require a statement of rationale. +. +When writing macro packages or documents that use GNU +.I troff \" GNU +features and which may be mixed with other packages or documents that do +not\[em]common scenarios include serial processing of man pages or use +of the +.RB \[lq] so \[rq] +or +.B mso +requests\[em]you may desire correct operation regardless of +compatibility mode enablement in the surrounding context. +. +It may occur to you to save the existing value of +.B \[rs]n(.C +into a register, +say, +.BR _C , +at the beginning of your file, +turn compatibility mode off with +.RB \[lq] .cp\~0 \[rq], +then restore it from that register at the end with +.RB \[lq] .cp\~\[rs]n(_C \[rq]. +. +At the same time, +a modular design of a document or macro package may lead you to multiple +layers of inclusion. +. +You cannot use the same register name everywhere lest you +\[lq]clobber\[rq] the value from a preceding or enclosing context. +. +The two-character register name space of AT&T +.I troff \" AT&T +is confining and mnemonically challenging; +you may wish to use +GNU +.IR troff 's \" GNU +more capacious name space. +. +However, +attempting +.RB \[lq] ".nr _my_saved_C \[rs]n(.C" \[rq] +will not work in compatibility mode; +the register name is too long. +. +\[lq]This is exactly what +.B .do +is for,\[rq] you think, +.RB \[lq] ".do nr _my_saved_C \[rs]n(.C" \[rq]. +. +The foregoing will always save zero to your register, +because +.RB \[lq] do \[rq] +turns compatibility mode +.I off +while it interprets its argument list. +. +What you need is: +. +.RS +.EX +\&.do nr _my_saved_C \[rs]n[.cp] +\&.cp 0 +.EE +.RE +. +at the beginning of your file, +followed by +.RS +.EX +\&.cp \[rs]n[_my_saved_C] +\&.do rr _my_saved_C +.EE +.RE +at the end. +. +As in the C language, +we all have to share one big name space, +so choose a register name that is unlikely to collide with other uses. +. +. +.P +The existence of the +.B .T +string is a common feature of post-CSTR\~#54 +.IR troff s\[em]DWB\~3.3, \" others +Solaris, +Heirloom Doctools, +and Plan\~9 +.I troff \" foreign +all support it\[em]but valid values are specific to each implementation. +. +The behavior of the +.B .T +register in GNU +.I troff \" GNU +differs from AT&T +.IR troff , \" AT&T +which interpolated\~1 only if +.I nroff \" AT&T +was the formatter and was called with +.BR \-T . +. +. +.P +The +.B lf +request sets the number of the +.I current +input line in AT&T +.IR troff ,\" AT&T +and the +.I next +in GNU +.IR troff .\" GNU +. +. +.br +.ne 2v +.P +AT&T +.I troff +had only environments named +.RB \[lq] 0 \[rq], +.RB \[lq] 1 \[rq], +and +.RB \[lq] 2 \[rq]. +. +In GNU +.IR troff , +any number of environments may exist, +using any valid identifiers for their names. +. +. +.P +GNU +.I troff \" GNU +normally tracks the interpolation depth of escape sequence parameters +and other delimited structures, +but not in compatibility mode. +. +See section \[lq]Miscellaneous\[rq] above. +. +. +.P +In compatibility mode, +the escape sequences +.BR \[rs]f , +.BR \[rs]H , +.BR \[rs]m , +.BR \[rs]M , +.BR \[rs]R , +.BR \[rs]s , +and +.B \[rs]S +are transparent at the beginning of an input line for the purpose of +recognizing a control character, +because they modify formatter state +.RB ( \[rs]R ) +or properties of the environment +(the rest) +and therefore do not create output nodes. +. +For example, +this code produces bold output in both cases, +but the text differs, +. +.RS +.EX +\&.de xx \[aq] +Hello! +\&.. +\&\[rs]fB.xx\[rs]fP +.EE +.RE +. +formatting \[lq].xx\[rq] normally and \[lq]Hello!\[rq] in compatibility +mode. +. +. +.P +GNU +.I troff \" GNU +request names unrecognized by other +.I troff \" generic +implementations will likely be ignored; +escape sequences that are GNU +.I troff \" GNU +extensions are liable to format their function selector character. +. +For example, +the adjustable, +non-breaking space escape sequence +.B \[rs]\[ti] +.\" BEGIN Keep in sync with groff.texi node "Other Differences" and +.\" groff_man_style(7). +is also supported by Heirloom Doctools +.I troff \" Heirloom +050915 (September 2005), +.I mandoc +1.9.5 (2009-09-21), +.I neatroff +(commit 1c6ab0f6e, +2016-09-13), +and Plan\~9 from User Space +.I troff \" Plan 9 +(commit 93f8143600, +2022-08-12), +but not by Solaris/Illumos +.IR troff s, \" Solaris/Illumos +which will render it as +.BR \[ti] . +.\" as of this writing, 2022-08-13 +.\" END Keep in sync with groff.texi node "Other Differences" and +.\" groff_man_style(7). +. +. +.P +GNU +.I troff \" GNU +does not allow the use of the escape sequences +.BR \[rs]| , +.BR \[rs]\[ha] , +.BR \[rs]& , +.BR \[rs]{ , +.BR \[rs]} , +.BI \[rs] space\c +, +.BR \[rs]\[aq] , +.BR \[rs]\[ga] , +.BR \[rs]\- , +.BR \[rs]_ , +.BR \[rs]! , +.BR \[rs]% , +or +.B \[rs]c +in identifiers; +AT&T +.I troff \" AT&T +does. +. +The +.B \[rs]A +escape sequence +(see subsection \[lq]Escape sequences\[rq] above) +may be helpful in avoiding their use. +. +. +.P +Normally, +the syntax form +.BI \[rs]s n +accepts only a single character +(a digit) +for +.IR n , +consistently with other forms that originated in AT&T +.IR troff , \" AT&T +like +.BR \[rs]* , +.BR \[rs]$ , +.BR \[rs]f , +.BR \[rs]g , +.BR \[rs]k , +.BR \[rs]n , +and +.BR \[rs]z . +. +In compatibility mode only, +a +.RI non-zero\~ n +must be in the range 4\[en]39. +. +Legacy documents relying upon this quirk of parsing should be migrated +to another +.B \[rs]s +form. +. +[Background: +The Graphic Systems C/A/T phototypesetter +(the original device target for AT&T +.IR troff ) \" AT&T +supported only a few discrete type sizes in the range 6\[en]36 points, +so Ossanna contrived a special case in the parser to do what the user +must have meant. +. +Kernighan warned of this in the 1992 revision of CSTR\~#54 (\[sc]2.3), +and more recently, +McIlroy referred to it as a \[lq]living fossil\[rq].] +. +. +.P +Fractional type sizes cause one noteworthy incompatibility. +. +In AT&T +.I troff \" AT&T +the +.B ps +request ignores scaling units and thus +.RB \[lq] .ps\~10u \[rq] +sets the type size to 10\~points, +whereas in GNU +.I troff \" GNU +it sets the type size to +.RI 10\~ scaled +points, +which may be a much smaller measurement. +. +See subsection \[lq]Fractional type sizes and new scaling units\[rq] +above. +. +. +.P +The +.B ab +request differs from AT&T +.IR troff : \" AT&T +GNU +.I troff \" GNU +writes no message to the standard error stream if no arguments are +given, +and it exits with a failure status instead of a successful one. +. +. +.P +The +.B bp +request differs from AT&T +.IR troff : \" AT&T +GNU +.I troff \" GNU +does not accept a scaling unit on the argument, +a page number; +the former +(somewhat uselessly) +does. +. +. +.P +In AT&T +.I troff \" AT&T +the +.B pm +request reports +macro, +string, +and +diversion +sizes in units of 128-byte blocks, +and an argument reduces the report to a sum of the above in the same +units. +. +GNU +.I troff \" GNU +ignores any arguments and reports the sizes in bytes. +. +. +.P +Unlike AT&T +.IR troff , \" AT&T +GNU +.I troff \" GNU +does not ignore the +.B ss +request if the output is a terminal device; +instead, +the values of minimum inter-word and additional inter-sentence space are +each rounded down to the nearest multiple of\~12. +. +. +.P +In GNU +.I troff \" GNU +there is a fundamental difference between (unformatted) characters and +(formatted) glyphs. +. +Everything that affects how a glyph is output is stored with the glyph +node; +once a glyph node has been constructed, +it is unaffected by any subsequent requests that are executed, +including +.BR bd , +.BR cs , +.BR tkf , +.BR tr , +or +.B fp +requests. +. +Normally, +glyphs are constructed from characters immediately before the glyph is +added to an output line. +. +Macros, +diversions, +and strings are all, +in fact, +the same type of object; +they contain a sequence of intermixed character and glyph nodes. +. +Special characters transform from one to the other: +before being added to the output, +they behave as characters; +afterward, +they are glyphs. +. +A glyph node does not behave like a character node when it is processed +by a macro: +it does not inherit any of the special properties that the character +from which it was constructed might have had. +. +For example, +the input +. +.br +.ne 5v +.RS +.EX +\&.di x +\[rs]\[rs]\[rs]\[rs] +\&.br +\&.di +\&.x +.EE +.RE +. +produces +.RB \[lq]\^ \[rs]\[rs] \[rq] +in GNU +.IR troff . \" GNU +Each pair of backslashes becomes one backslash +.I glyph; +the resulting backslashes are thus not interpreted as escape +.I characters +when they are reread as the diversion is output. +. +AT&T +.I troff \" AT&T +.I would +interpret them as escape characters when rereading them and end up +printing one +.RB \[lq] \[rs] \[rq]. +. +. +.P +One way to format a backslash in most documents is with the +.B \[rs]e +escape sequence; +this formats the glyph of the current escape character, +regardless of whether it is used in a diversion; +it also works in both GNU +.I troff \" GNU +and AT&T +.IR troff . \" AT&T +. +(Naturally, +if you've changed the escape character, +you need to prefix the +.RB \[lq] e \[rq] +with whatever it is\[em]and you'll likely get something other than a +backslash in the output.) +. +. +.P +The other correct way, +appropriate in contexts independent of the backslash's common use as a +.I roff +escape character\[em]perhaps in discussion of character sets or other +programming languages\[em]is the character escape +.B \[rs](rs +or +.BR \[rs][rs] , +for \[lq]reverse solidus\[rq], +from its name in the ECMA-6 (ISO/IEC\~646) standard. +. +[This escape sequence is not portable to AT&T +.IR troff , \" AT&T +but is to its lineal descendant, +Heirloom Doctools +.IR troff , +as of its 060716 release (July 2006).] +. +. +.P +To store an escape sequence in a diversion that is interpreted when the +diversion is reread, +either use the traditional +.B \[rs]!\& +transparent output facility, +or, +if this is unsuitable, +the new +.B \[rs]?\& +escape sequence. +. +See subsection \[lq]Escape sequences\[rq] above and sections +\[lq]Diversions\[rq] and \[lq]gtroff Internals\[rq] in +.IR "Groff: The GNU Implementation of troff" , +the +.I groff +Texinfo manual. +. +. +.P +In the somewhat pathological case where a diversion exists containing a +partially collected line and a partially collected line at the top-level +diversion has never existed, +AT&T +.I troff +will output the partially collected line at the end of input; +GNU +.I troff \" GNU +will not. +. +. +.\" ==================================================================== +.SS "Formatter output incompatibilities" +.\" ==================================================================== +. +Its extensions notwithstanding, +the +.I groff +intermediate output format has some incompatibilities +with that of AT&T +.IR troff , \" AT&T +but better compatibility is sought; +problem reports and patches are welcome. +. +The following incompatibilities are known. +. +. +.IP \[bu] 2n +The drawing position after rendering polygons is inconsistent with AT&T +.I troff \" AT&T +practice. +. +Other implementations have diverged on this point as well. +. +. +.IP \[bu] +The output cannot be easily rescaled to other devices as AT&T +.IR troff 's \" AT&T +could. +.\" XXX: Why? What's the problem? sizescale? That could be written +.\" into the output as a comment or x command. --GBR +. +. +.\" ==================================================================== +.SH Authors +.\" ==================================================================== +. +This document was written by +.MT jjc@\:jclark\:.com +James Clark +.ME , +.MT wl@\:gnu\:.org +Werner Lemberg +.ME , +.MT groff\-bernd\:.warken\-72@\:web\:.de +Bernd Warken +.ME , +and +.MT g.branden\:.robinson@\:gmail\:.com +G.\& Branden Robinson +.ME . +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +.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 output format +referred to collectively in +.I groff +documentation as AT&T +.IR troff . \" AT&T +. +. +.P +\[lq]A Typesetter-independent TROFF\[rq] +by Brian W.\& Kernighan, +1982, +AT&T Bell Laboratories Computing Science Technical Report No.\& 97, +provides additional insights into the +device and font description file formats +and output format. +. +. +.P +.MR groff @MAN1EXT@ , +.MR groff @MAN7EXT@ , +.MR roff @MAN7EXT@ +. +. +.\" Clean up. +.rm tx +.rm ic +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_groff_diff_7_man_C] +.do rr *groff_groff_diff_7_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff textwidth=72: diff --git a/man/groff_font.5.man b/man/groff_font.5.man new file mode 100644 index 0000000..0ee1d9a --- /dev/null +++ b/man/groff_font.5.man @@ -0,0 +1,1114 @@ +.TH groff_font @MAN5EXT@ "@MDATE@" "groff @VERSION@" +.SH Name +groff_font \- GNU +.I roff +device and font description files +. +. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 1989-2021 Free Software Foundation, Inc. +.\" +.\" This file is part of groff (GNU roff), which is a free software +.\" project. +.\" +.\" You can redistribute it and/or modify it under the terms of the GNU +.\" General Public License as published by the Free Software Foundation, +.\" either version 2 of the License, or (at your option) any later +.\" version. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with this program. If not, see +.\" <http://www.gnu.org/licenses/gpl-2.0.html>. +. +. +.\" Save and disable compatibility mode (for, e.g., Solaris 10/11). +.do nr *groff_groff_font_5_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 +. +. +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +.\" BEGIN Keep parallel with groff.texi node "Device and Font Files". +The +.I groff +font and output device description formats are slight +extensions of those used by AT&T device-independent +.IR troff . \" AT&T +. +In distinction to the AT&T implementation, +.I groff +lacks a binary format; +all files are text files. +. +(Plan\~9 +.I troff \" Plan 9 +has also abandoned the binary format.) +. +The device and font description files for a device +.I name +are stored in a +.IR dev name +directory. +. +The device description file is called +.IR DESC , +and, +for each font supported by the device, +a font description file is +.RI called\~ f, +where +.IR f \~is +usually an abbreviation of a font's name and/or style. +. +For example, +the +.B ps +(PostScript) +device has +.I groff +font description files for Times roman +.RB ( TR ) +and Zapf Chancery Medium italic +.RB ( ZCMI ), +among many others, +while the +.B utf8 +device +(for terminal emulators) +has only font descriptions for the roman, +italic, +bold, +and bold-italic styles +.RB ( R , +.BR I , +.BR B , +and +.BR BI , +respectively). +. +. +.P +Device and font description files are read by the formatter, +.IR @g@troff , +and by output drivers. +. +The programs typically delegate these files' processing to an internal +library, +.IR libgroff , +ensuring their consistent interpretation. +. +. +.\" ==================================================================== +.SH "\f[I]DESC\f[] file format" +.\" ==================================================================== +. +The +.I DESC +file contains a series of directives; +each begins a line. +. +Their order is not important, +with two exceptions: +(1) the +.B res +directive must precede any +.B \%papersize +directive; +and +(2) the +.B charset +directive must come last +(if at all). +. +If a directive name is repeated, +later entries in the file override previous ones +(except that the paper dimensions are computed based on the +.B res +directive last seen when +.B \%papersize +is encountered). +. +Spaces and/or tabs separate words and are ignored at line boundaries. +. +Comments start with the +.RB \[lq] # \[rq] +character and extend to the end of a line. +. +Empty lines are ignored. +. +. +.TP +.BI family\~ fam +The default font family is +.IR fam . +. +. +.TP +.BI fonts\~ "n F1"\~\c +.RI .\|.\|.\&\~ Fn +Fonts +.IR F1 ", \|.\|.\|.\|, " Fn +are mounted at font positions +.IR m "\|+\|1, \|.\|.\|., " m \|+\| n +where +.I m +is the number of +.B styles +(see below). +. +This directive may extend over more than one line. +. +A font name +.RB of\~ 0 +causes no font to be mounted at the corresponding position. +. +. +.TP +.BI hor\~ n +The horizontal motion quantum is +.IR n \~basic +units. +. +Horizontal quantities are rounded to multiples +.RI of\~ n. +. +. +.TP +.BI image_generator\~ program +Use +.I program +to generate PNG images from PostScript input. +. +Under GNU/Linux, +this is usually +.MR gs 1 , +but under other systems +(notably Cygwin) +it might be set to another name. +. +The +.MR grohtml @MAN1EXT@ +driver uses this directive. +. +. +.TP +.BI paperlength\~ n +The vertical dimension of the output medium is +.IR n \~basic +units +(deprecated: +use +.B \%papersize +instead). +. +. +.TP +.BI papersize\~ format-or-dimension-pair-or-file-name\c +\~.\|.\|. +The dimensions of the output medium are as according to the +argument, +which is either +a standard paper format, +a pair of dimensions, +or the name of a plain text file containing either of the foregoing. +. +Recognized paper formats are the ISO and DIN formats +.BR A0 \[en] A7 , +.BR B0 \[en] B7 , +.BR C0 \[en] C7 , +and +.BR D0 \[en] D7 ; +.\" XXX: tmac/papersize.tmac does not support [ABCD]7. +the U.S.\& formats +.BR letter , +.BR legal , +.BR tabloid , +.BR ledger , +.BR statement , +and +.BR executive ; +and the envelope formats +.BR com10 , +.BR monarch , +and +.BR DL . +. +Matching is performed without regard for lettercase. +. +. +.IP +Alternatively, +the argument can be a custom paper format +.IB length , width +(with no spaces before or after the comma). +. +Both +.I length +and +.I width +must have a unit appended; +valid units are +.RB \[lq] i \[rq] +for inches, +.RB \[lq] c \[rq] +for centimeters, +.RB \[lq] p \[rq] +for points, +and +.RB \[lq] P \[rq] +for picas. +. +Example: +.RB \[lq] 12c,235p \[rq]. +. +An argument that starts with a digit is always treated as a custom paper +format. +. +. +.IP +Finally, +the argument can be a file name +(e.g., +.IR /etc/papersize ); +if the file can be opened, +the first line is read and a match attempted against each other form. +. +No comment syntax is supported. +. +. +.IP +More than one argument can be specified; +each is scanned in turn and the first valid paper specification used. +. +. +.TP +.BI paperwidth\~ n +The horizontal dimension of the output medium is +.IR n \~basic +units +(deprecated: +use +.B \%papersize +instead). +. +. +.TP +.B pass_filenames +Direct +.I @g@troff +to emit the name of the source file being processed. +. +This is achieved with the intermediate output command +.RB \[lq] "x F" \[rq], +which +.I \%grohtml +interprets. +. +. +.TP +.BI postpro\~ program +Use +.I program +as the postprocessor. +. +. +.TP +.BI prepro\~ program +Use +.I program +as a preprocessor. +. +The +.B html +and +.B xhtml +output devices use this directive. +. +. +.TP +.BI print\~ program +Use +.I program +as the print spooler. +. +If omitted, +.IR groff 's +.B \-l +and +.B \-L +options are ignored. +. +. +.TP +.BI res\~ n +The device resolution is +.I n +basic units per inch. +. +. +.TP +.BI sizes\~ s1\~\c +.RI .\|.\|.\&\~ sn\~\c +.B 0 +The device has fonts at +.IR s1 , +\&.\|.\|., +.I sn +scaled points +(see below). +. +The list of sizes must be terminated by +.RB a\~ 0 . +. +Each +.I si +can also be a range of sizes +.IR m \[en] n . +. +The list can extend over more than one line. +. +. +.TP +.BI sizescale\~ n +A typographical point +is subdivided into +.IR n \~scaled +points. +. +The default +.RB is\~ 1 . +. +. +.TP +.BI styles\~ S1\~\c +.RI .\|.\|.\&\~ Sm +The +.RI first\~ m +font mounting positions are associated with styles +.IR S1 , +\&.\|.\|., +.IR Sm . +. +. +.TP +.B tcommand +The postprocessor can handle the +.B t +.RB and\~ u +intermediate output commands. +. +. +.TP +.B unicode +The output device supports the complete Unicode repertoire. +. +This directive is useful only for devices which produce character +entities instead of glyphs. +. +. +.IP +If +.B unicode +is present, +no +.B charset +section is required in the font description files since the Unicode +handling built into +.I groff +is used. +. +However, +if there are entries in a font description file's +.B charset +section, +they either override the default mappings for those particular +characters or add new mappings +(normally for composite characters). +. +. +.IP +The +.BR utf8 , +.BR html , +and +.B xhtml +output devices use this directive. +. +. +.TP +.BI unitwidth\~ n +Quantities in the font description files are in basic units for fonts +whose type size is +.IR n \~scaled +points. +. +. +.TP +.B unscaled_charwidths +Make the font handling module always return unscaled glyph widths. +. +The +.I \%grohtml +driver uses this directive. +. +. +.TP +.B use_charnames_in_special +.I @g@troff +should encode named glyphs inside device control commands. +. +The +.I \%grohtml +driver uses this directive. +. +. +.TP +.BI vert\~ n +The vertical motion quantum is +.IR n \~basic +units. +. +Vertical quantities are rounded to multiples +.RI of\~ n. +. +. +.TP +.B charset +This directive and the rest of the file are ignored. +. +It is recognized for compatibility with other +.I troff \" generic +implementations. +. +In GNU +.IR troff , \" GNU +character set repertoire is described on a per-font basis. +. +. +.P +.I @g@troff +recognizes but ignores the directives +.BR spare1 , +.BR spare2 , +and +.BR biggestfont . +. +. +.P +The +.BR res , +.BR unitwidth , +.BR fonts , +and +.B sizes +lines are mandatory. +. +Directives not listed above are ignored by +.I @g@troff +but may be used by postprocessors to obtain further information about +the device. +. +. +.\" ==================================================================== +.SH "Font description file format" +.\" ==================================================================== +. +On typesetting output devices, +each font is typically available at multiple sizes. +. +While paper measurements in the device description file are in absolute +units, +measurements applicable to fonts must be proportional to the type size. +. +.I groff +achieves this using the precedent set by AT&T device-independent +.IR troff : \" AT&T +one font size is chosen as a norm, +and all others are scaled linearly relative to that basis. +. +The \[lq]unit width\[rq] is the number of basic units per point when the +font is rendered at this nominal size. +. +. +.P +For instance, +.IR groff 's +.B lbp +device uses a +.B unitwidth +of\~800. +. +Its Times roman font +.RB (\[lq] TR \[rq]) +has a +.B spacewidth +of\~833; +this is also the width of its comma, +period, +centered period, +and mathematical asterisk, +while its \[lq]M\[rq] is 2,963 basic units. +. +Thus, +an \[lq]M\[rq] on the +.B lbp +device is 2,963 basic units wide at a notional type size of 800\~points. +. +(800-point type is not practical for most purposes, +but using it enables the quantities in the font description files to be +expressed as integers.) +. +. +.P +A font description file has two sections. +. +The first is a sequence of directives, +and is parsed similarly to the +.I DESC +file described above. +. +Except for the directive names that begin the second section, +their ordering is immaterial. +. +Later directives of the same name override earlier ones, +spaces and tabs are handled in the same way, +and the same comment syntax is supported. +. +Empty lines are ignored throughout. +. +. +.TP +.BI name\~ F +The name of the font +.RI is\~ F . +. +.RB \[lq] DESC \[rq] +is an invalid font name. +. +Simple integers are valid, +but their use is discouraged. +. +.RI ( groff +requests and escape sequences interpret non-negative font names as +mounting positions instead. +. +Further, +a font named +.RB \[lq] 0 \[rq] +cannot be automatically mounted by the +.B fonts +directive of a +.I DESC +file.) +. +. +.TP +.BI spacewidth\~ n +The width of an unadjusted inter-word space is +.IR n \~basic +units. +. +. +.P +The directives above must appear in the first section; +those below are optional. +. +. +.TP +.BI slant\~ n +The font's glyphs have a slant of +.IR n \~degrees; +a positive +.I n +slants in the direction of text flow. +. +. +.TP +.BI ligatures\~ lig1\~\c +.RI .\|.\|.\&\~ lign\~\c +.RB [ 0 ] +Glyphs +.IR lig1 , +\&.\|.\|., +.I lign +are ligatures; +possible ligatures are +.BR ff , +.BR fi , +.BR fl , +.BR ffi , +and +.BR ffl . +. +For compatibility with other +.I troff +implementations, +the list of ligatures may be terminated with +.RB a\~ 0 . +. +The list of ligatures must not extend over more than one line. +. +. +.TP +.B special +The font is +.IR special : +when a glyph is requested that is not present in the current font, +it is sought in any mounted fonts that bear this property. +. +. +.P +Other directives in this section are ignored by +.IR @g@troff , +but may be used by postprocessors to obtain further information about +the font. +. +. +.P +The second section contains one or two subsections. +. +These can appear in either order; +the first one encountered commences the second section. +. +Each starts with a directive on a line by itself. +. +A +.B charset +subsection is mandatory unless the associated +.I DESC +file contains the +.B unicode +directive. +. +Another subsection, +.BR \%kernpairs , +is optional. +. +. +.P +The directive +.B charset +starts the character set subsection. +. +(For typesetter devices, +this directive is misnamed since it starts a list of glyphs, +not characters.) +. +It precedes a series of glyph descriptions, +one per line. +. +Each such glyph description comprises a set of fields separated by +spaces or tabs and organized as follows. +. +. +.IP +.I name metrics type code +.RI [ entity-name ] +.RB [ \-\- +.IR comment ] +. +. +.P +.I name +identifies the glyph: +if +.I name +is a printable +.RI character\~ c , +it corresponds to the +.I troff \" generic +ordinary +.RI character\~ c . +. +If +.I name +is a multi-character sequence not beginning with +.BR \[rs] , +it corresponds to the GNU +.I troff \" GNU +special character escape sequence +\[lq]\c +.BI \[rs][ name ]\c +\[rq]. +. +A name consisting of three minus signs, +.RB \[lq] \-\-\- \[rq], +indicates that the glyph is unnamed: +such glyphs can be accessed only by the +.B \[rs]N +escape sequence in +.IR troff . \" generic; \N is portable +. +A special character named +.RB \[lq] \-\-\- \[rq] +can still be defined using +.B .char +and similar requests. +. +The +.I name +.RB \[lq] \[rs]\- \[rq] +defines the minus sign glyph. +. +.\" TODO: Withdraw support for this. No one seems to use it. +Finally, +.I name +can be the horizontal motion escape sequences, +.B \[rs]| +and +.B \[rs]\[ha] +(\[lq]thin\[rq] and \[lq]hair\[rq] spaces, +respectively), +in which case only the width metric described below is applied; +a font can thus customize the widths of these spaces. +.\" XXX: For exhaustivity purposes...you can define "\whatever", which +.\" has to be accessed with \C'\\whatever' or \[\\whatever], but the +.\" parser matches predefined escape sequences before looking up special +.\" characters. Most such definitions are inaccessible from the +.\" language, because nearly every '\x', where 'x' is a Unicode basic +.\" Latin character, is a predefined groff escape sequence. +. +. +.br +.ne 4v \" Keep next paragraph together with (possibly 2-line) synopsis. +.P +The form of the +.I metrics +field is as follows +(on one line; +it may be broken here for readability). +. +. +.IP +.\" XXX: Turning off adjustment is ugly; thanks to meter-long specimens +.\" like this, we need an escape sequence that selectively disables +.\" adjustment at the end of a word. +.na +.I width\/\c +.RI [\fB,\fP[ \:height\/\c +.RI [\fB,\fP[ \:depth\/\c +.RI [\fB,\fP[ \:\%italic-correction\/\c +.RI [\fB,\fP[ \:\%left-italic-correction\/\c +.RI [\fB,\fP[ \:\%subscript-correction ]]]]]]]]]] +.ad \*[AD] +. +. +.P +There must not be any spaces, +tabs, +or newlines between these +.I subfields, +. +which are in basic units expressed as decimal integers. +. +Unspecified subfields default +.RB to\~ 0 . +. +Since there is no associated binary format, +these values are not required to fit into the C language data type +.B char +as they are in AT&T device-independent +.IR troff . \" AT&T +. +. +.P +The +.I width +subfield gives the width of the glyph. +. +The +.I height +subfield gives the height of the glyph +(upwards is positive); +if a glyph does not extend above the baseline, +it should be given a zero height, +rather than a negative height. +. +The +.I depth +subfield gives the depth of the glyph, +that is, +the distance below the baseline to which the glyph extends +(downwards is positive); +if a glyph does not extend below the baseline, +it should be given a zero depth, +rather than a negative depth. +. +Italic corrections are relevant to glyphs in italic or oblique styles. +. +The +.I italic-correction +is the amount of space that should be added after an oblique glyph to be +followed immediately by an upright glyph. +. +The +.I left-italic-correction +is the amount of space that should be added before an oblique glyph to +be preceded immediately by an upright glyph. +. +The +.I +subscript-correction +is the amount of space that should be added after an oblique glyph to be +followed by a subscript; +it should be less than the italic correction. +. +. +.P +For fonts used with typesetting devices, +the +.I type +field gives a featural description of the glyph: +it is a bit mask recording whether the glyph is an ascender, +descender, +both, +or neither. +. +When a +.B \[rs]w +escape sequence is interpolated, +these values are bitwise or-ed together +for each glyph +and stored in the +.B ct +register. +. +In font descriptions for terminal devices, +all glyphs might have a type of zero, +regardless of their appearance. +. +. +.TP +0 +means the glyph lies entirely between the baseline and +a horizontal line at the \[lq]x-height\[rq] of the font, +as with \[lq]a\[rq], +\[lq]c\[rq], +and +\[lq]x\[rq]; +. +. +.TP +1 +means the glyph descends below the baseline, +like \[lq]p\[rq]; +. +. +.TP +2 +means the glyph ascends above the font's x-height, +like \[lq]A\[rq] or +\[lq]b\[rq]); +and +. +. +.TP +3 +means the glyph is both an ascender and a descender\[em]this is true of +parentheses in some fonts. +. +. +.P +The +.I code +field gives a numeric identifier that the postprocessor uses to render +the glyph. +. +The glyph can be specified to +.I troff \" generic +using this code by means of the +.B \[rs]N +escape sequence. +. +The code can be any integer +(that is, +any integer parsable by the C standard library's +.MR strtol 3 +function). +. +. +.P +The +.I entity-name +field defines an identifier for the glyph that the postprocessor +uses to print the +.I @g@troff +glyph +.IR name . +. +This field is optional; +it was introduced so that the +.I \%grohtml +output driver could encode its character set. +. +For example, +the glyph +.B \[rs][Po] +is represented by +.RB \[lq] £ \[rq] +in HTML 4.0. +. +For efficiency, +these data are now compiled directly into +.IR \%grohtml . +. +.I grops +uses the field to build sub-encoding arrays for PostScript fonts +containing more than 256 glyphs. +. +Anything on the line after the +.I entity-name +field or +.RB \[lq] \-\- \[rq] +is ignored. +. +. +.P +A line in the +.B charset +section can also have the form +. +.RS +.IB name\~ \[dq] +.RE +. +identifying +.I name +as another name for the glyph mentioned in the preceding line. +. +Such aliases can be chained. +. +. +.P +The directive +.B \%kernpairs +starts a list of kerning adjustments to be made to adjacent glyph pairs +from this font. +. +It contains a sequence of lines formatted as follows. +. +.RS +.I g1 g2 n +.RE +. +The foregoing means that when glyph +.I g1 +is typeset immediately before +.IR g2 , +the space between them should be increased +.RI by\~ n . +. +Most kerning pairs should have a negative value +.RI for\~ n . +.\" END Keep parallel with groff.texi node "Device and Font Files". +. +. +.br +.ne 4v +.\" ==================================================================== +.SH Files +.\" ==================================================================== +. +.TP +.IR @FONTDIR@/\:\%dev name /\:DESC +describes the output device +.IR name . +. +. +.TP +.IR @FONTDIR@/\:\%dev name / F +describes the font known +.RI as\~ F +on device +.IR name . +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +.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]. +. +. +.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]. +. +. +.P +\[lq]A Typesetter-independent TROFF\[rq] +by Brian W.\& Kernighan, +1982, +AT&T Bell Laboratories Computing Science Technical Report No.\& 97, +provides additional insights into the +device and font description file formats +and device-independent output format. +. +. +.P +.MR groff @MAN1EXT@ , +subsection \[lq]Utilities\[rq], +lists programs available for describing fonts in a variety of formats +such that +.I groff +output drivers can use them. +. +. +.P +.MR @g@troff @MAN1EXT@ +documents the default device and font description file search path. +. +. +.P +.MR groff_out @MAN5EXT@ , +.MR addftinfo @MAN1EXT@ +. +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_groff_font_5_man_C] +.do rr *groff_groff_font_5_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff textwidth=72: diff --git a/man/groff_out.5.man b/man/groff_out.5.man new file mode 100644 index 0000000..9c1534e --- /dev/null +++ b/man/groff_out.5.man @@ -0,0 +1,1963 @@ +.TH groff_out @MAN5EXT@ "@MDATE@" "groff @VERSION@" +.SH Name +groff_out \- GNU +.I roff +intermediate output format +. +. +.\" XXX: This page needs review and editing. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 1989-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_out_5_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 +.\" ==================================================================== +. +.\" ================= Document configuration +. +.\" Number register to decide whether the commands '{' and '}' are used +.\" 0: disable (current default); 1: enable +.nr @USE_ENV_STACK 0 +. +.ig +Unfortunately, old versions of groff used an illogical position change +after some D\~commands (Dp, DP, Dt). If the register +@STUPID_DRAWING_POSITIONING is 1 (current default) then change position +after these commands, otherwise the position is not changed. +.. +.nr @STUPID_DRAWING_POSITIONING 1 +. +.\" ================= Semantical definitions +. +.nr @maxcolor 65536 +.ds @backslash \[rs]\" +.ds @linebreak \fR\[la]line-break\[ra]\fP\" +. +.\" Begin of macro definitions +. +.de offset +.RI ( \,\\$1\/ ,\ \,\\$2\/ )\\$3 +.. +.de indexed_offset +.offset \fI\\$1\/\fP\d\s-3\\$2\s+3\u\x'\n[.v]/4' \fI\\$3\/\fP\ +\d\s-3\\$4\s+3\u\x'\n[.v]/4' \\$5\x'\n[.v]/4' +.. +.\" format: .command <name> "<arguments>" <punctuation> +.de command +\fB\\$1\fP\ \fI\,\\$2\/\fP\\$3 +.. +.\" format: .D-command <subcommand> "<arguments>" +.de D-command +\fBD\\$1\fP\ \fI\,\\$2\/\fP\|\*[@linebreak] +.. +. +.\" We set these as troff micromotions rather than eqn because \d and \u +.\" can be lifted to XML subscript/superscript tags. Don't change +.\" these to a parameterized string, man2html won't handle that. +.ds hv1 \fIh\d\s-3\&1\s+3\u\~v\d\s-3\&1\s+3\u\fP\x'\n[.v]/4' +.ds hv2 \fIh\d\s-3\&2\s+3\u\~v\d\s-3\&2\s+3\u\fP\x'\n[.v]/4' +.ds hvn \fIh\d\s-3\&n\s+3\u\~v\d\s-3\&n\s+3\u\fP\x'\n[.v]/4' +. +.de Da-command +\fBDa\fP\ \*[hv1] \*[hv2]\|\*[@linebreak] +.. +.\" graphics command .D with a variable number of arguments +.\" format: .D-multiarg <subcommand> +.de D-multiarg +\fBD\\$1\fP\ \*[hv1] \*[hv2] \&.\|.\|.\& \*[hvn]\|\*[@linebreak] +.. +.\" format: .x-command <subname> "<arguments>" +.de x-command +\fBx\\$1\fP\ \fI\\$2\fP\|\*[@linebreak] +.. +.de xsub +.RI "(" "\\$1" " control command)" +.br +.. +.\" End of macro definitions +. +. +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +The fundamental operation of the +.MR @g@troff @MAN1EXT@ +formatter is the translation of the +.MR groff @MAN7EXT@ +input language into a series of instructions concerned primarily with +placing glyphs or geometric objects at specific positions on a +rectangular page. +. +In the following discussion, +the term +.I command +refers to this intermediate output language, +never to the +.MR groff @MAN7EXT@ +language intended for use by document authors. +. +Intermediate output commands comprise several categories: +glyph output; +font, +color, +and text size selection; +motion of the printing position; +page advancement; +drawing of geometric primitives; +and device control commands, +a catch-all for other operations. +. +The last includes directives to start and stop output, +identify the intended output device, +and embed URL hyperlinks in supported output formats. +. +. +.P +Because the front-end command +.MR groff @MAN1EXT@ +is a wrapper that normally runs the +.I @g@troff +formatter to generate intermediate output +and an output driver (\[lq]postprocessor\[rq]) to consume it, +users normally do not encounter this language. +. +The +.I groff +program's +.B \-Z +option inhibits postprocessing such that this intermediate output is +sent to the standard output stream as when +.I @g@troff +is run manually. +. +. +.P +.IR groff 's +intermediate output facilitates the development of output drivers and +other postprocessors by offering a common programming interface. +. +It is an extension of the page description language developed by Brian +Kernighan for AT&T device-independent +.I troff \" AT&T +circa 1980. +. +Where a distinction is necessary, +we will say +.RI \[lq] @g@troff +output\[rq] to describe the output of GNU +.IR troff , \" GNU +and \[lq]intermediate output\[rq] to denote the language accepted by +the parser implemented in +.IR groff 's +internal C++ library used by most of its output drivers. +.\" XXX GBR leaves off here. +. +. +.\" ==================================================================== +.SH "Language concepts" +.\" ==================================================================== +. +During the run of +.IR @g@troff , +the +.I roff +input is cracked down to the information on what has to be printed at +what position on the intended device. +. +So the language of the +.I intermediate output +format can be quite small. +. +Its only elements are commands with or without arguments. +. +In this document, the term \[lq]command\[rq] always refers to the +.I intermediate output +language, never to the +.I roff +language used for document formatting. +. +There are commands for positioning and text writing, for drawing, and +for device controlling. +. +. +.\" ==================================================================== +.SS Separation +.\" ==================================================================== +. +.I Classical troff output +had strange requirements on whitespace. +. +The +.I groff +output parser, however, is smart about whitespace by making it +maximally optional. +. +The whitespace characters, i.e., the +.IR tab , +.IR space , +and +.I newline +characters, always have a syntactical meaning. +. +They are never printable because spacing within the output is always +done by positioning commands. +. +. +.P +Any sequence of +.I space +or +.I tab +characters is treated as a single +.I syntactical +.IR space . +. +It separates commands and arguments, but is only required when there +would occur a clashing between the command code and the arguments +without the space. +. +Most often, this happens when variable length command names, +arguments, argument lists, or command clusters meet. +. +Commands and arguments with a known, fixed length need not be +separated by +.I syntactical +.IR space . +. +. +.P +A line break is a syntactical element, too. +. +Every command argument can be followed by whitespace, a comment, or a +newline character. +. +Thus a +.I syntactical line break +is defined to consist of optional +.I syntactical space +that is optionally followed by a comment, and a newline character. +. +. +.P +The normal commands, those for positioning and text, consist of a +single letter taking a fixed number of arguments. +. +For historical reasons, the parser allows stacking of such commands on +the same line, but fortunately, in +.I groff intermediate +.IR output , +every command with at least one argument is followed by a line break, +thus providing excellent readability. +. +.P +The other commands \[em] those for drawing and device controlling \[em] +have a more complicated structure; some recognize long command names, +and some take a variable number of arguments. +. +So all +.B D +and +.B x +commands were designed to request a +.I syntactical line break +after their last argument. +. +Only one command, +.RB \[oq] x\ X \[cq] +has an argument that can stretch over several lines, all other +commands must have all of their arguments on the same line as the +command, i.e., the arguments may not be split by a line break. +. +.P +Lines containing only spaces and/or a comment are treated as empty and +ignored. +. +. +.\" ==================================================================== +.SS "Argument units" +.\" ==================================================================== +. +Some commands accept integer arguments that represent measurements, +but the scaling units of the formatter's language are never used. +. +Most commands assume a scaling unit +.RB of\~\[lq] u \[rq] +(basic units), +and others +.RB use\~\[lq] z \[rq] +(scaled points); +. +These are defined by the parameters specified in the device's +.I DESC +file; +see +.MR groff_font @MAN5EXT@ +and, +for more on scaling units, +.MR groff @MAN7EXT@ +and +.IR "Groff: The GNU Implementation of troff" , +the +.I groff +Texinfo manual. +. +Color-related commands use dimensionless integers. +. +. +.P +Note that single characters can have the eighth bit set, as can the +names of fonts and special characters (this is, glyphs). +. +The names of glyphs and fonts can be of arbitrary length. +. +A glyph that is to be printed will always be in the current font. +. +. +.P +A string argument is always terminated by the next whitespace +character (space, tab, or newline); an embedded +.B # +character is regarded as part of the argument, not as the beginning of +a comment command. +. +An integer argument is already terminated by the next non-digit +character, which then is regarded as the first character of the next +argument or command. +. +. +.\" ==================================================================== +.SS "Document parts" +.\" ==================================================================== +. +A correct +.I intermediate output +document consists of two parts, the +.I prologue +and the +.IR body . +. +.P +The task of the +.I prologue +is to set the general device parameters using three exactly specified +commands. +. +The +.I groff prologue +is guaranteed to consist of the following three lines (in that order): +.RS +.P +.B x\ T +.I device +.br +.B x\ res +.I n\ h\ v +.br +.B x init +.RE +.P +with the arguments set as outlined in subsection \[lq]Device Control +Commands\[rq] below. +. +However, the parser for the +.I intermediate output +format is able to swallow additional whitespace and comments as well. +. +. +.P +The +.I body +is the main section for processing the document data. +. +Syntactically, it is a sequence of any commands different from the +ones used in the +.IR prologue . +. +Processing is terminated as soon as the first +.B x\ stop +command is encountered; the last line of any +.I groff intermediate output +always contains such a command. +. +. +.P +Semantically, the +.I body +is page oriented. +. +A new page is started by a +.BR p \~command. +. +Positioning, writing, and drawing commands are always done within the +current page, so they cannot occur before the first +.BR p \~command. +. +Absolute positioning (by the +.B H +and +.BR V \~commands) +is done relative to the current page, all other positioning +is done relative to the current location within this page. +. +. +.\" ==================================================================== +.SH "Command reference" +.\" ==================================================================== +. +This section describes all +.I intermediate output +commands, the classical commands as well as the +.I groff +extensions. +. +. +.\" ==================================================================== +.SS "Comment command" +.\" ==================================================================== +. +.TP +.BI # anything\c +\[la]line-break\[ra] +A comment. +. +Ignore any characters from the +.BR # \~character +up to the next newline. +. +Each comment can be preceded by arbitrary +.I syntactical +.IR space ; +every command can be terminated by a comment. +. +. +.\" ==================================================================== +.SS "Simple commands" +.\" ==================================================================== +. +The commands in this subsection have a command code consisting of a +single character, taking a fixed number of arguments. +. +Most of them are commands for positioning and text writing. +. +These commands are smart about whitespace. +. +Optionally, +.I syntactical space +can be inserted before, after, and between the command letter and its +arguments. +. +All of these commands are stackable, i.e., they can be preceded by +other simple commands or followed by arbitrary other commands on the +same line. +. +A separating +.I syntactical space +is necessary only when two integer arguments would clash or if the +preceding argument ends with a string argument. +. +. +.if \n[@USE_ENV_STACK]=1 \{\ +.TP +.command { +Open a new environment by copying the current device configuration data +to the environment stack. +. +The current environment is setup by the device specification and +manipulated by the setting commands. +. +. +.TP +.command } +Close the current environment +(opened by a preceding +.BR { \~command) +and restore the previous environment from the environment +stack as the current device configuration data. +. +.\} \" endif @USE_ENV_STACK +. +. +.TP +.command C id \[la]white-space\[ra] +Typeset the glyph of the special character +.IR id . +. +Trailing syntactical space is necessary to allow special character names +of arbitrary length. +. +The drawing position is not advanced. +.\" XXX: Why does it matter that we read its size if we don't advance +.\" the drawing position? +.\" its size is read from the font description file. +. +. +.TP +.command c c +Typeset the glyph of the ordinary character +.RI character\~ c . +. +The drawing position is not advanced. +.\" XXX: Why does it matter that we read its size if we don't advance +.\" the drawing position? +.\" its size is read from the font description file. +. +. +.TP +.command f n +Select the font mounted at +.RI position\~ n . +. +.IR n\~ cannot +be negative. +. +. +.TP +.command H n +Horizontally move the drawing position to +.IR n\~ basic +units from the left edge of the page. +. +.IR n\~ cannot +be negative. +. +. +.TP +.command h n +Move the drawing position right +.I n +basic units. +. +AT&T +.I troff \" AT&T +allowed negative +.I n; +GNU +.I troff \" GNU +does not produce such values, +but +.IR groff 's +output driver library handles them. +. +. +.TP +.command m "scheme \f[R][\f[]component\f[R] .\|.\|.]" +Select the stroke color using the +.IR component s +in the color space +.IR scheme . +. +Each +.I component +is an integer between 0 and \n[@maxcolor]. +. +The quantity of components and their meanings vary with each +.IR scheme . +. +This command is a +.I groff +extension. +. +. +.RS +.TP +.command mc "cyan magenta yellow" +Use the CMY color scheme with components +cyan, +magenta, +and yellow. +. +. +.TP +.command md +Use the default color +(no components; +black in most cases). +. +. +.TP +.command mg gray +Use a grayscale color scheme with a component ranging +between 0 (black) and \n[@maxcolor] (white). +. +. +.TP +.command mk "cyan magenta yellow black" +Use the CMYK color scheme with components +cyan, +magenta, +yellow, +and black. +. +. +.TP +.command mr "red green blue" +Use the RGB color scheme with components +red, +green, +and blue. +.RE +. +. +.TP +.command N n +Typeset the glyph with +.RI index\~ n +in the current font. +. +.IR n\~ is +normally a non-negative integer. +. +The drawing position is not advanced. +. +The +.B html +and +.B xhtml +devices use this command with +.RI negative\~ n +to produce unbreakable space; +the absolute value of +.I n +is taken and interpreted in basic units. +. +. +.TP +.command n b\~a +Indicate a break. +. +No action is performed; +the command is present to make the output more easily parsed. +. +The integers +.I b +.RI and\~ a +describe the vertical space amounts before and after the break, +respectively. +. +GNU +.I troff \" GNU +issues this command but +.IR groff 's +output driver library ignores it. +. +See +.B v +and +.BR V . +. +. +.TP +.command p n +Begin a new page, +setting its number +.RI to\~ n . +. +Each page is independent, +even from those using the same number. +. +The vertical drawing position is set to\~0. +. +All positioning, +writing, +and drawing commands are interpreted in the context of a page, +so a +.BR p \~command +must precede them. +. +. +.TP +.command s n +Set type size to +.I n +scaled points +.RB (unit\~ z +in GNU +.IR troff ). \" GNU +. +AT&T +.I troff \" AT&T +used unscaled points +.RB ( p ) +instead; +see section \[lq]Compatibility\[rq] below. +. +. +.TP +.command t xyz\f[R]\|.\|.\|.\& \f[R]\[la]white-space\[ra] +.TQ +.command t "xyz\f[R]\|.\|.\|.\&\f[] dummy-arg" \[la]white-space\[ra] +Typeset word +.IR xyz ; +that is, +set a sequence of ordinary glyphs named +.IR x , +.IR y , +.IR z , +\&.\|.\|.\|, +terminated by a space or newline; +an optional second integer argument is ignored +(this allows the formatter to generate an even number of arguments). +.\" XXX: Why? +. +Each glyph is set at the current drawing position, +and the position is then advanced horizontally by the glyph's width. +. +A glyph's width is read from its metrics in the font description file, +scaled to the current type size, +and rounded to a multiple of the horizontal motion quantum. +. +Use the +.B C +command to emplace glyphs of special characters. +. +The +.BR t \~command +is a +.I groff +extension and is output only for devices whose +.I DESC +file contains the +.B tcommand +directive; +see +.MR groff_font @MAN5EXT@ . +. +. +.TP +.command u "n xyz"\f[R]\|.\|.\|.\& \f[R]\[la]white-space\[ra] +.TQ +.command u "xyz\f[R]\|.\|.\|.\&\f[] dummy-arg" \[la]white-space\[ra] +Typeset word +.I xyz +with track kerning. +. +As +.BR t , +but after placing each glyph, +the drawing position is further advanced horizontally +.RI by\~ n +basic units. +. +The +.BR u \~command +is a +.I groff +extension and is output only for devices whose +.I DESC +file contains the +.B tcommand +directive; +see +.MR groff_font @MAN5EXT@ . +. +. +.TP +.command V n +Vertically move the drawing position to +.IR n\~ basic +units from the top edge of the page. +. +.IR n\~ cannot +be negative. +. +. +.TP +.command v n +Move the drawing position down +.I n +basic units. +. +AT&T +.I troff \" AT&T +allowed negative +.I n; +GNU +.I troff \" GNU +does not produce such values, +but +.IR groff 's +output driver library handles them. +. +. +.TP +.command w +Indicate an inter-word space. +. +No action is performed; +the command is present to make the output more easily parsed. +. +Only adjustable, +breakable inter-word spaces are thus described; +those resulting from +.B \[rs]\[ti] +or horizontal motion escape sequences are not. +. +GNU +.I troff \" GNU +issues this command but +.IR groff 's +output driver library ignores it. +. +See +.B h +and +.BR H . +. +. +.\" ==================================================================== +.SS "Graphics commands" +.\" ==================================================================== +. +Each graphics or drawing command in the +.I intermediate output +starts with the letter\~\c +.B D +followed by one or two characters that specify a subcommand; this +is followed by a fixed or variable number of integer arguments that +are separated by a single space character. +. +A +.BR D \~command +may not be followed by another command on the same line (apart from a +comment), so each +.BR D \~command +is terminated by a +.I syntactical line +.IR break . +. +. +.P +.I @g@troff +output follows the classical spacing rules (no space between command +and subcommand, all arguments are preceded by a single space +character), but the parser allows optional space between the command +letters and makes the space before the first argument optional. +. +As usual, each space can be any sequence of tab and space characters. +. +. +.P +Some graphics commands can take a variable number of arguments. +. +In this case, they are integers representing a size measured in basic +units\~\c +.BR u . +. +The +.I h +arguments +stand for horizontal distances where positive means right, negative +left. +. +The +.I v +arguments +stand for vertical distances where positive means down, negative up. +. +All these distances are offsets relative to the current location. +. +. +.P +Unless indicated otherwise, each graphics command directly corresponds +to a similar +.I groff +.B \*[@backslash]D +escape sequence; see +.MR groff @MAN7EXT@ . +. +. +.P +Unknown +.BR D \~commands +are assumed to be device-specific. +. +Its arguments are parsed as strings; the whole information is then +sent to the postprocessor. +. +. +.P +In the following command reference, the syntax element +.I \[la]line-break\[ra] +means a +.I syntactical line break +as defined in subsection \[lq]Separation\[rq] above. +. +. +.TP +.D-multiarg \[ti] +Draw B-spline from current position to offset +.indexed_offset h 1 v 1 , +then to offset +.indexed_offset h 2 v 2 +if given, etc., up to +.indexed_offset h n v n . +This command takes a variable number of argument pairs; the current +position is moved to the terminal point of the drawn curve. +. +. +.TP +.Da-command +Draw arc from current position to +.indexed_offset h 1 v 1 \|+\|\c +.indexed_offset h 2 v 2 +with center at +.indexed_offset h 1 v 1 ; +then move the current position to the final point of the arc. +. +. +.TP +.D-command C d +.TQ +.D-command C "d dummy-arg" +Draw a solid circle using the current fill color with diameter\~\c +.I d +(integer in basic units\~\c +.BR u ) +with leftmost point at the current position; then move the current +position to the rightmost point of the circle. +. +An optional second integer argument is ignored (this allows the +formatter to generate an even number of arguments). +. +This command is a +.I groff +extension. +. +. +.TP +.D-command c d +Draw circle line with diameter\~\c +.I d +(integer in basic units\~\c +.BR u ) +with leftmost point at the current position; then move the current +position to the rightmost point of the circle. +. +. +.TP +.D-command E "h v" +Draw a solid ellipse in the current fill color with a horizontal +diameter of\~\c +.I h +and a vertical diameter of\~\c +.I v +(both integers in basic units\~\c +.BR u ) +with the leftmost point at the current position; then move to the +rightmost point of the ellipse. +. +This command is a +.I groff +extension. +. +. +.TP +.D-command e "h v" +Draw an outlined ellipse with a horizontal diameter of\~\c +.I h +and a vertical diameter of\~\c +.I v +(both integers in basic units\~\c +.BR u ) +with the leftmost point at current position; then move to the +rightmost point of the ellipse. +. +. +.TP +.D-command F "color-scheme \fR[\fPcomponent\fR .\|.\|.]\fP" +Set fill color for solid drawing objects using different color +schemes; the analogous command for setting the color of text, line +graphics, and the outline of graphic objects is +.BR m . +. +The color components are specified as integer arguments between 0 and +\n[@maxcolor]. +. +The number of color components and their meaning vary for the +different color schemes. +. +These commands are generated by the +.I groff +escape sequences +.BR \*[@backslash]D\[aq]F\ .\|.\|. ' +and +.B \*[@backslash]M +(with no other corresponding graphics commands). +. +This command is a +.I groff +extension. +. +. +.RS +. +.TP +.D-command Fc "cyan magenta yellow" +Set fill color for solid drawing objects using the CMY color scheme, +having the 3\~color components cyan, magenta, and yellow. +. +. +.TP +.D-command Fd +Set fill color for solid drawing objects to the default fill color value +(black in most cases). +. +No component arguments. +. +. +.TP +.D-command Fg "gray" +Set fill color for solid drawing objects to the shade of gray given by +the argument, an integer between 0 (black) and \n[@maxcolor] (white). +. +. +.TP +.D-command Fk "cyan magenta yellow black" +Set fill color for solid drawing objects using the CMYK color scheme, +having the 4\~color components cyan, magenta, yellow, and black. +. +.TP +.D-command Fr "red green blue" +Set fill color for solid drawing objects using the RGB color scheme, +having the 3\~color components red, green, and blue. +. +.RE +. +. +.TP +.D-command f n +The argument +.I n +must be an integer in the range \-32767 to 32767. +. +.RS +.TP +.RI 0\|\[<=]\| n \|\[<=]\|1000 +Set the color for filling solid drawing objects to a shade of gray, +where 0 corresponds to solid white, 1000 (the default) to solid black, +and values in between to intermediate shades of gray; this is +obsoleted by command +.BR DFg . +. +.TP +.IR n "\|<\|0 or " n \|>\|1000 +Set the filling color to the color that is currently being used for +the text and the outline, see command +.BR m . +For example, the command sequence +. +.RS +.IP +.EX +mg 0 0 \n[@maxcolor] +Df \-1 +.EE +.RE +. +.IP +sets all colors to blue. +. +.P +This command is a +.I groff +extension. +. +.RE +. +. +.TP +.D-command l "h v" +Draw line from current position to offset +.offset h v +(integers in basic units\~\c +.BR u ); +then set current position to the end of the drawn line. +. +. +.TP +.D-multiarg p +Draw a polygon line from current position to offset +.indexed_offset h 1 v 1 , +from there to offset +.indexed_offset h 2 v 2 , +etc., up to offset +.indexed_offset h n v n , +and from there back to the starting position. +. +.ie \n[@STUPID_DRAWING_POSITIONING]=1 \{\ +For historical reasons, the position is changed by adding the sum of +all arguments with odd index to the current horizontal position and the +even ones to the vertical position. +. +Although this doesn't make sense it is kept for compatibility. +. +.\} +.el \{\ +As the polygon is closed, the end of drawing is the starting point, so +the position doesn't change. +.\} +. +This command is a +.I groff +extension. +. +. +.TP +.D-multiarg P +The same macro as the corresponding +.B Dp +command with the same arguments, but draws a solid polygon in the +current fill color rather than an outlined polygon. +. +.if \n[@STUPID_DRAWING_POSITIONING]=1 \{\ +The position is changed in the same way as with +.BR Dp . +.\} +. +This command is a +.I groff +extension. +. +. +.TP +.D-command t n +Set the current line thickness +.RI to\~ n +(an integer in basic +.RB units\~ u ) +if +.IR n \|>\|0; +if +.IR n \|=\|0 +select the smallest available line thickness; +otherwise, +the line thickness is made proportional to the type size, +which is the default. +. +.if \n[@STUPID_DRAWING_POSITIONING]=1 \{\ +For historical reasons, +the horizontal position is changed by adding the argument to the current +horizontal position, +while the vertical position is not changed. +. +Although this doesn't make sense, +it is kept for compatibility. +.\} +. +This command is a +.I groff +extension. +. +. +.\" ==================================================================== +.SS "Device control commands" +.\" ==================================================================== +. +Each device control command starts with the letter +.B x +followed by a space character (optional or arbitrary space/\:tab in +.IR groff ) +and a subcommand letter or word; each argument (if any) must be +preceded by a +.I syntactical +.IR space . +. +All +.B x +commands are terminated by a +.IR "syntactical line break" ; +no device control command can be followed by another command on the same +line (except a comment). +. +.P +The subcommand is basically a single letter, but to increase +readability, it can be written as a word, i.e., an arbitrary sequence +of characters terminated by the next tab, space, or newline character. +. +All characters of the subcommand word but the first are simply ignored. +. +For example, +.I @g@troff +outputs the initialization command +.B x\ i +as +.B x\ init +and the resolution command +.B x\ r +as +.BR "x\ res" . +. +But writings like +.B x\ i_like_groff +and +.B x\ roff_is_groff +are accepted as well to mean the same commands. +. +.P +In the following, the syntax element +.I \[la]line-break\[ra] +means a +.I syntactical line break +as defined in subsection \[lq]Separation\[rq] above. +. +.TP +.x-command F name +.xsub Filename +Use +.I name +as the intended name for the current file in error reports. +. +This is useful for remembering the original file name when +.I groff +uses an internal piping mechanism. +. +The input file is not changed by this command. +. +This command is a +.I groff +extension. +. +. +.TP +.x-command f "n\ s" +.xsub font +Mount font position\~\c +.I n +(a non-negative integer) with font named\~\c +.I s +(a text word); +see +.MR groff_font @MAN5EXT@ . +. +. +.TP +.x-command H n +.xsub Height +Set character height to\~\c +.I n +(a positive integer in scaled points\~\c +.BR z ). +. +.I Classical troff +used the unit points (\c +.BR p ) +instead; +see section \[lq]Compatibility\[rq] below. +. +. +.TP +.x-command i +.xsub init +Initialize device. +. +This is the third command of the +.IR prologue . +. +. +.TP +.x-command p +.xsub pause +Parsed but ignored. +. +The classical documentation reads +.I pause device, can be +.IR restarted . +. +. +.TP +.x-command r "n\ h\ v" +.xsub resolution +Resolution is\~\c +.IR n , +while +.I h +is the minimal horizontal motion, and +.I v +the minimal vertical motion possible with this device; all arguments +are positive integers in basic units\~\c +.B u +per inch. +. +This is the second command of the +.IR prologue . +. +. +.TP +.x-command S n +.xsub Slant +Set slant to\~\c +.I n +degrees (an integer in basic units\~\c +.BR u ). +. +. +.TP +.x-command s +.xsub stop +Terminates the processing of the current file; issued as the last +command of any +.I intermediate @g@troff +.IR output . +. +. +.TP +.x-command t +.xsub trailer +Generate trailer information, if any. +. +In +.BR groff , +this is currently ignored. +. +. +.TP +.x-command T xxx +.xsub Typesetter +. +Set the name of the output driver to +.IR xxx , +a sequence of non-whitespace characters terminated by whitespace. +. +The possible names correspond to those of +.IR groff 's +.B \-T +option. +. +This is the first command of the prologue. +. +. +.TP +.x-command u n +.xsub underline +Configure underlining of spaces. +. +If +.I n +is\~1, start underlining of spaces; +if +.I n +is\~0, stop underlining of spaces. +. +This is needed for the +.B cu +request in +.B @g@nroff +mode and is ignored otherwise. +. +This command is a +.I groff +extension. +. +. +.TP +.x-command X anything +.xsub X-escape +Send string +.I anything +uninterpreted to the device. +. +If the line following this command starts with a +.B + +character this line is interpreted as a continuation line in the +following sense. +. +The +.B + +is ignored, but a newline character is sent instead to the device, the +rest of the line is sent uninterpreted. +. +The same applies to all following lines until the first character of a +line is not a +.B + +character. +. +This command is generated by the +.I groff +escape sequence +.BR \*[@backslash]X . +. +The line-continuing feature is a +.I groff +extension. +. +. +.\" ==================================================================== +.SS "Obsolete command" +.\" ==================================================================== +. +In +.I classical troff +output, emitting a single glyph was mostly done by a very +strange command that combined a horizontal move and the printing of a +glyph. +. +It didn't have a command code, but is represented by a 3-character +argument consisting of exactly 2\~digits and a character. +. +.TP +.I ddc +Move right +.I dd +(exactly two decimal digits) basic units\~\c +.BR u , +then print glyph with single-letter name\~\c +.IR c . +. +. +.RS +.P +In +.IR groff , +arbitrary +.I syntactical space +around and within this command is allowed to be added. +. +Only when a preceding command on the same line ends with an argument +of variable length a separating space is obligatory. +. +In +.I classical +.IR troff , +large clusters of these and other commands were used, mostly without +spaces; this made such output almost unreadable. +. +.RE +. +. +.P +For modern high-resolution devices, this command does not make sense +because the width of the glyphs can become much larger than two +decimal digits. +. +In +.IR groff , +it is used only for output to the +.BR X75 , +.BR X75\-12 , +.BR X100 , +and +.B X100\-12 +devices. +. +For others, +the commands +.B t +.RB and\~ u +provide greater functionality and superior troubleshooting capacity. +. +. +.\" ==================================================================== +.SH Postprocessing +.\" ==================================================================== +. +The +.I roff +postprocessors are programs that have the task to translate the +.I intermediate output +into actions that are sent to a device. +. +A device can be some piece of hardware such as a printer, or a software +file format suitable for graphical or text processing. +. +The +.I groff +system provides powerful means that make the programming of such +postprocessors an easy task. +.P +There is a library function that parses the +.I intermediate output +and sends the information obtained to the device via methods of a +class with a common interface for each device. +. +So a +.I groff +postprocessor must only redefine the methods of this class. +. +For details, +see the reference in section \[lq]Files\[rq] below. +. +. +.\" ==================================================================== +.SH Example +.\" ==================================================================== +. +This section presents the +.I intermediate output +generated from the same input for three different devices. +. +The input is the sentence +.I hell world +fed into +.I groff +on the command line. +. +. +.IP \[bu] 2m +High-resolution device +.I ps +. +. +.RS +.P +.EX +.RB "shell>\~" "echo \[dq]hell world\[dq] | groff \-Z \-T ps" +.EE +. +. +.P +.EX +x T ps +x res 72000 1 1 +x init +p1 +x font 5 TR +f5 +s10000 +V12000 +H72000 +thell +wh2500 +tw +H96620 +torld +n12000 0 +x trailer +V792000 +x stop +.EE +.RE +. +. +.P +This output can be fed into the postprocessor +.MR grops @MAN1EXT@ +to get its representation as a PostScript file, or +.MR gropdf @MAN1EXT@ +to output directly to PDF. +. +. +.IP \[bu] 2m +Low-resolution device +.I latin1 +. +. +.RS +.P +This is similar to the high-resolution device except that the +positioning is done at a minor scale. +. +Some comments (lines starting with +.IR # ) +were added for clarification; they were not generated by the +formatter. +. +. +.P +.EX +\fBshell>\fP "hell world" | groff \-Z \-T latin1 +.EE +. +. +.P +.EX +.I # prologue +x T latin1 +x res 240 24 40 +x init +.I # begin a new page +p1 +.I # font setup +x font 1 R +f1 +s10 +.I # initial positioning on the page +V40 +H0 +.I # write text \[aq]hell\[aq] +thell +.I # inform about a space, and do it by a horizontal jump +wh24 +.I # write text \[aq]world\[aq] +tworld +.I # announce line break, but do nothing because ... +n40 0 +.I # ... the end of the document has been reached +x trailer +V2640 +x stop +.EE +.RE +. +. +.P +This output can be fed into the postprocessor +.MR grotty @MAN1EXT@ +to get a formatted text document. +. +. +.IP \[bu] 2m +Classical style output +. +. +.RS +.P +As a computer monitor has a very low resolution compared to modern +printers the +.I intermediate output +for the X\~devices can use the jump-and-write command with its 2-digit +displacements. +. +. +.P +.EX +\fBshell>\fP "hell world" | groff \-Z \-T X100 +.EE +. +. +.P +.EX +x T X100 +x res 100 1 1 +x init +p1 +x font 5 TR +f5 +s10 +V16 +H100 +.I # write text with old-style jump-and-write command +ch07e07l03lw06w11o07r05l03dh7 +n16 0 +x trailer +V1100 +x stop +.EE +.RE +. +. +.P +This output can be fed into the postprocessor +.MR xditview 1x +or +.MR gxditview @MAN1EXT@ +for displaying in\~X. +. +. +.P +Due to the obsolete jump-and-write command, the text clusters in the +classical output are almost unreadable. +. +. +.\" ==================================================================== +.SH Compatibility +.\" ==================================================================== +. +The +.I intermediate output +language of the +.I classical troff +was first documented in +[CSTR\~#97]. +. +The +.I groff intermediate output +format is compatible with this specification except for the following +features. +. +. +.IP \[bu] 2m +The classical quasi device independence is not yet implemented. +. +. +.IP \[bu] 2m +The old hardware was very different from what we use today. +. +So the +.I groff +devices are also fundamentally different from the ones in +.I classical +.IR troff . +. +For example, the classical PostScript device was called +.I post +and had a resolution of 720 units per inch, +while +.IR groff 's +.I ps +device has a resolution of 72000 units per inch. +. +Maybe, by implementing some rescaling mechanism similar to the +classical quasi device independence, these could be integrated into +modern +.IR groff . +. +. +.IP \[bu] 2m +The B-spline command +.B D\[ti] +is correctly handled by the +.I intermediate output +parser, but the drawing routines aren't implemented in some of the +postprocessor programs. +. +. +.IP \[bu] 2m +The argument of the commands +.B s +and +.B x H +has the implicit unit scaled point\~\c +.B z +in +.IR groff , +while +.I classical troff +had point (\c +.BR p ). +. +This isn't an incompatibility, but a compatible extension, for both +units coincide for all devices without a +.I sizescale +parameter, including all classical and the +.I groff +text devices. +. +The few +.I groff +devices with a sizescale parameter either did not exist, had a +different name, or seem to have had a different resolution. +. +So conflicts with classical devices are very unlikely. +. +. +.ie \n[@STUPID_DRAWING_POSITIONING]=1 \{\ +.IP \[bu] 2m +The position changing after the commands +.BR Dp , +.BR DP , +and +.B Dt +is illogical, but as old versions of groff used this feature it is +kept for compatibility reasons. +.\} \" @STUPID_DRAWING_POSITIONING +.el \{\ +.IP \[bu] 2m +Temporarily, there existed some confusion on the positioning after the +.B D +commands that are +.I groff +extensions. +. +This has been clarified by establishing the classical rule for all +groff drawing commands: +. +. +.RS +.P +.ft I +The position after a graphic object has been drawn is at its end; +for circles and ellipses, the "end" is at the right side. +.ft +.RE +. +. +.P +From this, the positionings specified for the drawing commands above +follow quite naturally. +.\} \" @STUPID_DRAWING_POSITIONING +. +.P +The differences between +.I groff +and +.I classical troff +are documented in +.MR groff_diff @MAN7EXT@ . +. +. +.\" ==================================================================== +.SH Files +.\" ==================================================================== +. +.TP +.IR @FONTDIR@/\:\%dev name /\:DESC +describes the output device +.IR name . +. +. +.br +.ne 4v +.\" ==================================================================== +.SH Authors +.\" ==================================================================== +. +James Clark wrote an early version of this document, +which described only the differences between AT&T +device-independent +.IR troff 's +output format and that of GNU +.IR roff . +. +The present version was completely rewritten in 2001 by +.MT groff\-bernd\:.warken\-72@\:web\:.de +Bernd Warken +.ME . +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +.P +.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]. +. +. +.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]. +. +. +.P +\[lq]A Typesetter-independent TROFF\[rq] +by Brian W.\& Kernighan, +1982, +AT&T Bell Laboratories Computing Science Technical Report No.\& 97, +provides additional insights into the +device and font description file formats +and device-independent output format. +. +. +.TP +.MR groff @MAN1EXT@ +documents the +.B \-Z +option and contains pointers to further +.I groff +documentation. +. +. +.TP +.MR groff @MAN7EXT@ +describes the +.I groff +language, +including its escape sequences and system of units. +. +. +.TP +.MR groff_font @MAN5EXT@ +details the device scaling parameters of device +.I DESC +files. +. +. +.TP +.MR @g@troff @MAN1EXT@ +generates the device-independent intermediate output documented here. +. +. +.TP +.MR roff @MAN7EXT@ +presents historical aspects and the general structure of +.I roff +systems. +. +. +.TP +.MR groff_diff @MAN7EXT@ +enumerates differences between the intermediate output produced by AT&T +.I troff \" AT&T +and that of +.IR groff . +. +. +.TP +.MR gxditview @MAN1EXT@ +is a viewer for intermediate output. +. +. +.TP +.UR https://\:github.com/\:Alhadis/\:Roff\:.js/ +.I Roff.js +.UE +is a viewer for intermediate output written in JavaScript. +. +. +.P +.MR grodvi @MAN1EXT@ , +.MR grohtml @MAN1EXT@ , +.MR grolbp @MAN1EXT@ , +.MR grolj4 @MAN1EXT@ , +.MR gropdf @MAN1EXT@ , +.MR grops @MAN1EXT@ , +and +.MR grotty @MAN1EXT@ +are +.I groff +postprocessors. +. +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_groff_out_5_man_C] +.do rr *groff_groff_out_5_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff textwidth=72: diff --git a/man/groff_tmac.5.man b/man/groff_tmac.5.man new file mode 100644 index 0000000..fac78f5 --- /dev/null +++ b/man/groff_tmac.5.man @@ -0,0 +1,1474 @@ +.TH groff_tmac @MAN5EXT@ "@MDATE@" "groff @VERSION@" +.SH Name +groff_tmac \- macro files in the GNU +.I roff +typesetting system +. +. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 2000-2022 Free Software Foundation, Inc. +.\" +.\" This file is part of groff, the GNU roff typesetting 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_tmac_5_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 +. +. +.\" TODO: Consider parallelizing with our Texinfo node "Macro Packages". +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +Definitions of macros, +strings, +and registers for use in a +.MR roff @MAN7EXT@ +document can be collected into +.IR "macro files" , +.I roff +input files designed to produce no output themselves but instead ease +the preparation of other +.I roff +documents. +. +There is no syntactical difference between a macro file and any other +.I roff +document; +only its purpose distinguishes it. +. +When a macro file is installed at a standard location, +named according to a certain convention, +and suitable for use by a general audience, +it is termed a +.IR "macro package" . +. +Macro packages can be loaded by supplying the +.B \-m +option to +.MR @g@troff @MAN1EXT@ +or a +.I groff +front end. +. +. +.P +Each macro package stores its macro, +string, +and register definitions in one or more +.I tmac +files. +. +This name originated in early Unix culture as an abbreviation of +.RI \[lq] troff \" generic +macros\[rq]. +. +. +.P +A macro file must have a name in the form +.RI name .tmac +(or +.IR tmac. name) +and be placed in a +.RI \[lq] tmac +directory\[rq] to be loadable with the +.BI \-m name +option. +. +Section \[lq]Environment\[rq] of +.MR @g@troff @MAN1EXT@ +lists these directories. +. +Alternatively, +a +.I groff +document requiring a macro file can load it with the +.B mso +(\[lq]macro source\[rq]) request. +. +. +.P +Like any other +.I roff +document, +a macro file can use the +.RB \[lq] so \[rq] +request (\[lq]source\[rq]) to load further files relative to its own +location. +. +. +.P +Macro files are named for their most noteworthy application, +but a macro file need not define any macros. +. +It can restrict itself to defining registers and strings or invoking +other +.I groff +requests. +. +It can even be empty. +. +. +.\" ==================================================================== +.SH "Macro packages" +.\" ==================================================================== +. +Macro packages come in two varieties; +those which assume responsibility for page layout and other critical +functions +(\[lq]major\[rq] or \[lq]full-service\[rq]) +and those which do not +(\[lq]supplemental\[rq] or \[lq]auxiliary\[rq]). +. +GNU +.I roff +provides most major macro packages found in AT&T and BSD Unix systems, +an additional full-service package, +and many supplemental packages. +. +Multiple full-service macro packages cannot be used by the same +document. +. +Auxiliary packages can generally be freely combined, +though attention to their use of the +.I groff +language name spaces for identifiers +(particularly registers, +macros, +strings, +and diversions) +should be paid. +. +Name space management was a significant challenge in AT&T +.IR troff ; +.IR groff 's +support for arbitrarily long identifiers affords few excuses for name +collisions, +apart from attempts at compatibility with the demands of historical +documents. +. +. +.\" ==================================================================== +.SS "Man pages" +.\" ==================================================================== +. +.TP +.I an +.TQ +.I man +.I an +is used to compose man pages in the format originating in Version\~7 +Unix (1979). +. +It has a small macro interface and is widely used; +see +.MR groff_man @MAN7EXT@ . +. +. +.TP +.I doc +.TQ +.I mdoc +.I doc +is used to compose man pages in the format originating in 4.3BSD-Reno +(1990). +. +It provides many more features than +.IR an , +but is also larger, +more complex, +and not as widely adopted; +see +.MR groff_mdoc @MAN7EXT@ . +. +. +.P +Because readers of man pages often do not know in advance which macros +are used to format a given document, +a wrapper is available. +. +. +.TP +.I \%andoc +.TQ +.I mandoc +This macro file, +specific to +.IR groff , +recognizes whether a document uses +.I man +or +.I mdoc +format and loads the corresponding macro package. +. +Multiple man pages, +in either format, +can be handled; +.I \%andoc +reloads each macro package as necessary. +. +. +.\" ==================================================================== +.SS "Full-service packages" +.\" ==================================================================== +. +The packages in this section provide a complete set of macros for +writing documents of any kind, up to whole books. +. +They are similar in functionality; it is a matter of taste which one +to use. +. +. +.TP +.I me +The classical +.I me +macro package; see +.MR groff_me @MAN7EXT@ . +. +. +.TP +.I mm +The semi-classical +.I mm +macro package; see +.MR groff_mm @MAN7EXT@ . +. +. +.TP +.I mom +The +.I mom +macro package, only available in groff. +. +As this was not based on other packages, it was freely designed as +quite a nice, modern macro package. +. +See +.MR groff_mom @MAN7EXT@ . +. +. +.TP +.I ms +The classical +.I ms +macro package; see +.MR groff_ms @MAN7EXT@ . +. +. +.\" ==================================================================== +.SS "Localization packages" +.\" ==================================================================== +. +For Western languages, +the localization file sets the hyphenation mode and loads hyphenation +patterns and exceptions. +. +Localization files can also adjust the date format and provide +translations of strings used by some of the full-service macro packages; +alter the input encoding +(see the next section); +and change the amount of additional inter-sentence space. +. +For Eastern languages, +the localization file defines character classes and sets flags on them. +. +By default, +.I troffrc +loads the localization file for English. +. +. +.TP +.I trans +loads localized strings used by various macro packages after their +localized forms have been prepared by a localization macro file. +. +. +.P +.I groff +provides the following localization files. +. +. +.TP +.I cs +Czech; +localizes +.IR man , +.IR me , +.IR mm , +.IR mom , +and +.IR ms . +. +Sets the input encoding to Latin-2 by loading +.IR latin2.tmac . +. +. +.TP +.I de +.TQ +.I den +German; +localizes +.IR man , +.IR me , +.IR mm , +.IR mom , +and +.IR ms . +. +Sets the input encoding to Latin-1 by loading +.IR latin1.tmac . +. +. +.IP +.I de.tmac +selects hyphenation patterns for traditional orthography, +and +.I den.tmac +does the same for the new orthography +(\[lq]Recht\%schreib\%reform\[rq]). +. +. +.TP +.I en +English. +. +. +.TP +.I fr +French; +localizes +.IR man , +.IR me , +.IR mm , +.IR mom , +and +.IR ms . +. +Sets the input encoding to Latin-9 by loading +.IR latin9.tmac . +. +. +.TP +.I it +Italian; +localizes +.IR man , +.IR me , +.IR mm , +.IR mom , +and +.IR ms . +. +. +.TP +.I ja +Japanese. +. +. +.TP +.I sv +Swedish; +localizes +.IR man , +.IR me , +.IR mm , +.IR mom , +and +.IR ms . +. +Sets the input encoding to Latin-1 by loading +.IR latin1.tmac . +. +Some of the localization of the +.I mm +package is handled separately; +see +.MR groff_mmse @MAN7EXT@ . +. +. +.TP +.I zh +Chinese. +. +. +.\" ==================================================================== +.SS "Input encodings" +.\" ==================================================================== +. +.TP +.I latin1 +.TQ +.I latin2 +.TQ +.I latin5 +.TQ +.I latin9 +are various ISO\~8859 input encodings supported by +.IR groff . +. +On systems using ISO character encodings, +.I groff +loads +.I latin1.tmac +automatically at startup. +. +A document that uses Latin-2, +Latin-5, +or Latin-9 +can specify one of these alternative encodings. +. +. +.TP +.I cp1047 +provides support for EBCDIC-based systems. +. +On those platforms, +.I groff +loads +.I cp1047.tmac +automatically at startup. +. +. +.P +Because different input character codes constitute valid GNU +.I troff \" GNU +input on ISO and EBCDIC systems, +the +.I latin +macro files cannot be used on EBCDIC systems, +and +.I cp1047 +cannot be used on ISO systems. +. +. +.\" ==================================================================== +.SS "Auxiliary packages" +.\" ==================================================================== +. +The macro packages in this section are not intended for stand-alone +use, +but can add functionality to any other macro package or to plain +(\[lq]raw\[rq]) +.I groff +documents. +. +. +.\" TODO: +.\" a4 +.\" devtag +.\" doc-old +.\" europs +.\" psatk +.\" psfig +.TP +.I 62bit +provides macros for addition, +multiplication, +and division of 62-bit integers +(allowing safe multiplication of signed 31-bit integers, +for example). +. +. +.TP +.I hdtbl +allows the generation of tables using a syntax similar to the HTML table +model. +. +This Heidelberger table macro package is not a preprocessor, +which can be useful if the contents of table entries are determined by +macro calls or string interpolations. +. +Compare to +.MR @g@tbl @MAN1EXT@ . +. +It works only with the +.B ps +and +.B pdf +output devices. +. +See +.MR groff_hdtbl @MAN7EXT@ . +. +. +.TP +.I papersize +enables the paper format to be set on the command line by giving a +.RB \[lq] \-d +.BI \%paper= format\c +\[rq] +option to +.IR @g@troff . +. +Possible values for +.I format +are the ISO and DIN formats +.RB \[lq] A0 \[en] A6 \[rq], +.RB \[lq] B0 \[en] B6 \[rq], +.RB \[lq] C0 \[en] C6 \[rq], +and +.RB \[lq] D0 \[en] D6 \[rq]; +.\" XXX: src/libs/libgroff/paper.cpp also supports [ABCD]7. +the U.S.\& formats +.RB \%\[lq] letter \[rq], +.RB \%\[lq] legal \[rq], +.RB \%\[lq] tabloid \[rq], +.RB \%\[lq] ledger \[rq], +.RB \%\[lq] statement \[rq], +and +.RB \%\[lq] executive \[rq]; +and the envelope formats +.RB \%\[lq] com10 \[rq], +.RB \%\[lq] monarch \[rq], +and +.RB \%\[lq] DL \[rq]. +. +All formats, +even those for envelopes, +are in portrait orientation: +the length measurement is vertical. +. +Appending \[lq]l\[rq] (ell) to any of these denotes landscape +orientation instead. +. +This macro file assumes one-inch horizontal margins, +and sets registers recognized by the +.I groff +.IR man , +.IR mdoc , +.IR mm , +.IR mom , +and +.I ms +packages to configure them accordingly. +. +If you want different margins, +you will need to use those packages' facilities, +or +.I @g@troff +.B ll +and/or +.B po +requests to adjust them. +. +An output device typically requires command-line options +.B \-p +and +.B \-l +to override the paper dimensions and orientation, +respectively, +defined in its +.I DESC +file; +see subsection \[lq]Paper format\[rq] +of +.MR groff @MAN1EXT@ . +. +This macro file is normally loaded at startup by the +.I troffrc +file when formatting for a typesetting device +(but not a terminal). +. +. +.TP +.I pdfpic +provides a single macro, +.BR PDFPIC , +to include a PDF graphic in a document using features of the +.B pdf +output driver. +. +For other output devices, +.B PDFPIC +calls +.BR PSPIC , +with which it shares an interface +(see below). +. +This macro file is normally loaded at startup by the +.I troffrc +file. +. +. +.TP +.I pic +supplies definitions of the macros +.BR PS , +.BR PE , +and +.BR PF , +usable with the +.MR @g@pic @MAN1EXT@ +preprocessor. +. +They center each picture. +. +Use it if your document does not use a full-service macro package, +or that package does not supply working +.I pic +macro definitions. +. +Except for +.I man +and +.IR mdoc , +those provided with +.I groff +already do so +(exception: +.I mm +employs the name +.B PF +for a different purpose). +. +. +.TP +.I pspic +provides a macro, +.BR PSPIC , +that includes a PostScript graphic in a document. +. +The +.BR ps , +.BR dvi , +.BR html , +and +.B xhtml +output devices support such inclusions; +for all other drivers, +the image is replaced with a rectangular border of the same size. +. +.I pspic.tmac +is loaded at startup by the +.I troffrc +file. +. +. +.IP +Its syntax is as follows. +.RS +.IP +\&\fB.PSPIC\fP \ +[\fB\-L\fP\|\ +|\|\fB\-R\fP\|\ +|\|\fB\-C\fP\|\ +|\|\fB\-I\fP\~\fIn\fP] \ +\fI\|file\fP [\fIwidth\fP [\,\fIheight\/\fP]] +.RE +. +. +.IP +.I file +is the name of the PostScript file; +.I width +and +.I height +give the desired width and height of the image. +. +If neither a +.I width +nor a +.I height +argument is specified, +the image's natural width +(as given in the file's bounding box) +or the current line length is used as the width, +whatever is smaller. +. +The +.I width +and +.I height +arguments may have scaling units attached; +the default scaling unit +.RB is\~ i . +. +.B PSPIC +scales the graphic uniformly in the horizontal and vertical directions +so that it is no more than +.I width +wide +and +.I height +high. +. +Option +.B \-C +centers the graphic horizontally; +this is the default. +. +.B \-L +and +.B \-R +left- and right-align the graphic, +respectively. +. +.B \-I +indents the graphic +.RI by\~ n +(with a default scaling unit +.RB of\~ m ). +. +. +.IP +To use +.B PSPIC +within a diversion, +we recommend extending it with the following code, +assuring that the diversion's width completely covers the image's width. +. +. +.RS +.IP +.EX +\&.am PSPIC +\&.\~\~vpt 0 +\&\[rs]h\[aq](\[rs]\[rs]n[ps\-offset]u + \[rs]\[rs]n[ps\-deswid]u)\[aq] +\&.\~\~sp \-1 +\&.\~\~vpt 1 +\&.. +.EE +.RE +. +. +.IP +Failure to load +.BR PSPIC 's +image argument is not an error. +. +(The +.B psbb +request does issue an error diagnostic.) +. +To make such a failure fatal, +append to the +.B pspic*error\-hook +macro. +. +. +.RS +.IP +.EX +\&.am pspic*error\-hook +\&.\~\~ab +\&.. +.EE +.RE +. +. +.TP +.I ptx +provides a macro, +.BR xx , +to format permuted index entries as produced by the GNU +.MR ptx 1 +program. +. +If your formatting needs differ, +copy the macro into your document and adapt it to your needs. +. +. +.TP +.I rfc1345 +defines special character escape sequences named for the glyph mnemonics +specified in RFC\~1345 and the digraph table of the Vim text editor. +. +See +.MR groff_rfc1345 @MAN7EXT@ . +. +. +.TP +.I sboxes +offers an interface to the +.RB \[lq] "pdf: background" \[rq] +device control command supported by +.MR gropdf @MAN1EXT@ . +. +Using this package, +.I groff ms +documents can draw colored rectangles beneath any output. +. +.RS +.TP +.BI \%.BOXSTART\~SHADED\~ color\~\c +.BI \%OUTLINED\~ color\~\c +.BI \%INDENT\~ size\~\c +.BI \%WEIGHT\~ size +begins a box, +where the argument after +.B \%SHADED +gives the fill color and that after +.B \%OUTLINED +the border color. +. +Omit the former to get a borderless filled box and the latter for a +border with no fill. +. +The specified +.B \%WEIGHT +is used if the box is +.BR \%OUTLINED . +. +. +.IP +.B \%INDENT +precedes a value which leaves a gap between the border and the contents +inside the box. +. +. +.IP +Each +.I color +must be a defined +.I groff +color name, +and each +.I size +a valid +.I groff +numeric expression. +. +The keyword/value pairs can be specified in any order. +.RE +. +. +.IP +Boxes can be stacked, +so you can start a box within another box; +usually the later boxes would be smaller than the containing box, +but this is not enforced. +. +When using +.BR \%BOXSTART , +the left position is the current indent minus the +.B \%INDENT +in the command, +and the right position is the left position +(calculated above) +plus the current line length and twice the indent. +. +. +.RS +.TP +.B \%.BOXSTOP +takes no parameters. +. +It closes the most recently started box at the current vertical position +after adding its +.B \%INDENT +spacing. +.RE +. +. +.IP +Your +.I groff +documents can conditionally exercise the +.I sboxes +macros. +. +The register +.B \%GSBOX +is defined if the package is loaded, +and interpolates a true value if the +.B pdf +output device is in use. +. +. +.IP +.I sboxes +furthermore hooks into the +.MR groff_ms @MAN7EXT@ +package to receive notifications when footnotes are growing, +so that it can close boxes on a page before footnotes are printed. +. +When that condition obtains, +.I sboxes +will close open boxes two points +above the footnote separator and re-open them on the next page. +. +(This amount probably will not match the box's +.BR \%INDENT .) +. +. +.IP +See +.UR file://@DOCDIR@/\:\%msboxes\:.pdf +\[lq]Using PDF boxes with +.I groff +and the +.I ms +macros\[rq] +.UE +for a demonstration. +. +. +.TP +.I trace +aids the debugging of +.I groff +documents by tracing macro calls. +. +See +.MR groff_trace @MAN7EXT@ . +. +. +.TP +.I www +defines macros corresponding to HTML elements. +. +See +.MR groff_www @MAN7EXT@ . +. +. +.\" ==================================================================== +.SH Naming +.\" ==================================================================== +. +AT&T +.I nroff \" AT&T +and +.I troff \" AT&T +were implemented before the conventions of the modern C +.MR getopt 3 +call evolved, +and used a naming scheme for macro packages that looks odd to modern +eyes. +. +Macro packages were typically loaded using the +.B \-m +option to the formatter; +when directly followed by its argument without an intervening space, +this looked like a long option preceded by a single minus\[em]a +sensation in the computer stone age. +. +Macro packages therefore came to be known by names that started with the +letter \[lq]m\[rq], +which was omitted from the name of the macro file as stored on disk. +. +For example, +the manuscript macro package was stored as +.I tmac.s +and loaded with the option +.BR \-ms . +. +. +.P +.I groff +commands permit space between an option and its argument. +. +The syntax +.RB \[lq] "groff \-m s" \[rq] +makes the macro file name more clear but may surprise users familiar +with the original convention, +unaware that the package's \[lq]real\[rq] name was \[lq]s\[rq] all +along. +. +For such packages of long pedigree, +.I groff +accommodates different users' expectations by supplying wrapper macro +files that load the desired file with +.B mso +requests. +. +Thus, +all of +.RB \[lq] "groff \-m s" \[rq], +.RB \[lq] "groff \-m ms" \[rq], +.RB \[lq] "groff \-ms" \[rq], +and +.RB \[lq] "groff \-mms" \[rq] +serve to load the manuscript macros. +. +. +.P +Wrappers are not provided for packages of more recent vintage, +like +.IR www.tmac . +. +. +.P +As noted in passing above, +AT&T +.I troff \" AT&T +named macro files in the form +.IR tmac. name. +. +It has since become conventional in operating systems to use a suffixed +file name extension to suggest a file type or format. +. +. +.\" ==================================================================== +.SH Inclusion +.\" ==================================================================== +. +The traditional method of employing a macro package is to specify the +.B \-m +.I package +option to the formatter, +which then reads +.IR package 's +macro file prior to any input files. +. +Historically, +.I package +was sought in a file named +.IR tmac. package +(that is, +with a +.RB \[lq] tmac.\& \[rq] +prefix). +. +GNU +.I troff \" GNU +searches for +.RI package .tmac +in the macro path; +if not found, +it looks for +.IR tmac. package +instead, +and vice versa. +. +. +.P +Alternatively, +one could include a macro file by using the request +.RB \[lq] .so +.IR file-name \[rq] +in the document; +.I file-name +is resolved relative to the location of the input document. +. +GNU +.I troff \" GNU +offers an improved feature in the similar request +.RB \[lq] mso +.IR package-file-name \[rq], +which searches the macro path for +.IR package-file-name . +. +Because its argument is a file name, +its +.RB \[lq] .tmac \[rq] +component must be included for the file to be found; +however, +as a convenience, +if opening it fails, +.B mso +strips any such suffix and tries again with a +.RB \[lq] tmac.\& \[rq] +prefix, +and vice versa. +. +. +.P +If a sourced file requires preprocessing, +for example if it includes +.I tbl \" generic +tables +or +.I eqn \" generic +equations, +the preprocessor +.MR @g@soelim @MAN1EXT@ +must be used. +. +This can be achieved with a pipeline or, +in +.IR groff , +by specifying +the +.B \-s +option to the formatter +(or front end). +. +.MR man 1 +librarian programs generally call +.I @g@soelim +automatically. +. +(Macro packages themselves generally do not require preprocessing.) +. +. +.ig +.\" ==================================================================== +.SH Convention +.\" ==================================================================== +. +.\" This section does not fit into the framework of this document. +. +There is a convention that is supported by many modern roff +typesetters and +.MR man 1 +programs, the +.I preprocessor word +described in the following. +. +.P +If the first line in a document is a comment, the first word (after the +comment characters and a blank) constitutes the +.B preprocessor +.BR word . +That means that the letters of this word are interpreted as +abbreviations for those preprocessor commands that should be run +when formatting the document. +. +Mostly, only the letters corresponding to the options for the +preprocessors are recognized, +\[oq]e\[cq] +(for +.IR eqn ), +.\" \[oq]G\[cq], +.\" \[oq]g\[cq], +\[oq]p\[cq] +(for +.IR pic ), +\[oq]R\[cq] +(for +.IR refer ), +\[oq]s\[cq] +(for +.IR soelim ), +and +\[oq]t\[cq] +(for +.IR tbl ). +(see +.MR roff @MAN7EXT@ ). +. +. +.P +Besides being a good reminder for the user, some formatters (like the +.MR man 1 +program) are even able to automatically start the preprocessors +specified in the preprocessor word, but do not bet on this. +. +. +.P +The +.I man +program handles some preprocessors automatically, such that in +man\~pages only the following characters should be used: +\[oq]e\[cq], \[oq]p\[cq], and \[oq]t\[cq]. +. +. +.. +.\" ==================================================================== +.SH "Writing macros" +.\" ==================================================================== +. +A +.MR roff @MAN7EXT@ +document is a text file that is enriched by predefined formatting +constructs, such as requests, escape sequences, strings, numeric +registers, and macros from a macro package. +. +These elements are described in +.MR roff @MAN7EXT@ . +. +. +.P +To give a document a personal style, it is most useful to extend the +existing elements by defining some macros for repeating tasks; the best +place for this is near the beginning of the document or in a separate +file. +. +. +.P +Macros without arguments are just like strings. +. +But the full power of macros occurs when arguments are passed with a +macro call. +. +Within the macro definition, the arguments are available as the escape +sequences +.BR \[rs]$1 , +\&.\|.\|., +.BR \[rs]$9 , +.BR \[rs]$[ .\|.\|. ] , +.BR \[rs]$* , +and +.BR \[rs]$@ , +the name under which the macro was called is in +.BR \[rs]$0 , +and the number of arguments is in register +.BR \[rs]n[.$] ; +see +.MR groff @MAN7EXT@ . +. +. +.\" ==================================================================== +.SS "Draft mode" +.\" ==================================================================== +. +Writing groff macros is easy when the escaping mechanism is temporarily +disabled. +. +In groff, this is done by enclosing the macro definition(s) within a +pair of +.B .eo +and +.B .ec +requests. +. +Then the body in the macro definition is just like a normal part of +the document \[em] text enhanced by calls of requests, macros, +strings, registers, etc. +. +For example, the code above can be written in a simpler way by +. +. +.IP +.ds @1 \[rs]f[I]\[rs]$0\[rs]f[]\" +.ds @2 arguments:\" +.EX +\&.eo +\&.ds midpart was called with the following +\&.de print_args +\&\*[@1]\ \[rs]*[midpart]\ \[rs]n[.$]\ \*[@2] +\&\[rs]$* +\&.. +\&.ec +.EE +.rm @1 +.rm @2 +. +. +.P +Unfortunately, draft mode cannot be used universally. +. +Although it is good enough for defining normal macros, draft mode +fails with advanced applications, such as indirectly defined +strings, registers, etc. +. +An optimal way is to define and test all macros in draft mode and then +do the backslash doubling as a final step; do not forget to remove the +.I .eo +request. +. +. +.\" ==================================================================== +.SS "Tips for macro definitions" +.\" ==================================================================== +. +.IP \(bu +Start every line with a dot, for example, by using the groff request +.B .nop +for text lines, or write your own macro that handles also text lines +with a leading dot. +. +.RS +.IP +.EX +\&.de Text +\&.\ \ if (\[rs]\[rs]n[.$] == 0)\ \[rs] +\&.\ \ \ \ return +\&.\ \ nop\ \[rs])\[rs]\[rs]$*\[rs]) +\&.. +.EE +.RE +. +.IP \(bu +Write a comment macro that works both for copy and draft modes; +since the escape character is off in draft mode, +trouble might occur when comment escape sequences are used. +. +For example, the following macro just ignores its arguments, so it +acts like a comment line: +. +.RS +.IP +.EX +\&.de\ c +\&.. +\&.c\ This\ is\ like\ a\ comment\ line. +.EE +.RE +. +.IP \(bu +In long macro definitions, make ample use of comment lines or +almost-empty lines (this is, lines which have a leading dot +and nothing else) for a better structuring. +. +.IP \(bu +To increase readability, use groff's indentation facility for +requests and macro calls (arbitrary whitespace after the leading dot). +. +. +.\" ==================================================================== +.SS Diversions +.\" ==================================================================== +. +Diversions can be used to implement quite advanced programming +constructs. +. +They are comparable to pointers to large data structures in the +C\~programming language, but their usage is quite different. +. +. +.P +In their simplest form, diversions are multi-line strings, but +diversions get their power when used dynamically within macros. +. +The (formatted) information stored in a diversion can be retrieved by +calling the diversion just like a macro. +. +. +.P +Most of the problems arising with diversions can be avoided if you +remember that diversions always store complete lines. +. +Using diversions when the line buffer has not been flushed produces +strange results; not knowing this, many people get desperate about +diversions. +. +To ensure that a diversion works, add line breaks at the right +places. +. +To be safe, enclose everything that has to do with diversions within +a pair of line breaks; for example, by explicitly using +.B .br +requests. +. +This rule should be applied to diversion definition, both inside and +outside, and to all calls of diversions. +. +This is a bit of overkill, but it works nicely. +. +. +.P +(If you really need diversions which should ignore the current partial +line, use environments to save the current partial line and/\:or use the +.B .box +request.) +. +. +.P +The most powerful feature using diversions is to start a diversion +within a macro definition and end it within another macro. +. +Then everything between each call of this macro pair is stored within +the diversion and can be manipulated from within the macros. +. +. +.\" ==================================================================== +.SH Authors +.\" ==================================================================== +. +This document was written by +.MT groff\-bernd\:.warken\-72@\:web\:.de +Bernd Warken +.ME , +.MT wl@\:gnu\:.org +Werner Lemberg +.ME , +and +.MT g.branden\:.robinson@\:gmail\:.com +G.\& Branden Robinson +.ME . +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +.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]. +. +. +.LP +The +.UR https://\:wiki\:.linuxfoundation\:.org/\:lsb/\:fhs +Filesystem Hierarchy Standard +.UE +is maintained by the Linux Foundation. +. +. +.TP +.MR groff @MAN1EXT@ +is an overview of the +.I groff +system. +. +. +.TP +.MR groff_man @MAN7EXT@ , +.TQ +.MR groff_mdoc @MAN7EXT@ , +.TQ +.MR groff_me @MAN7EXT@ , +.TQ +.MR groff_mm @MAN7EXT@ , +.TQ +.MR groff_mom @MAN7EXT@ , +.TQ +.MR groff_ms @MAN7EXT@ , +.TQ +.MR groff_rfc1345 @MAN7EXT@ , +.TQ +.MR groff_trace @MAN7EXT@ , +\~and +.TQ +.MR groff_www @MAN7EXT@ +are +.I groff +macro packages. +. +. +.TP +.MR groff @MAN7EXT@ +summarizes the language recognized by GNU +.IR troff . \" GNU +. +. +.TP +.MR troff @MAN1EXT@ +documents the default macro file search path. +. +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_groff_tmac_5_man_C] +.do rr *groff_groff_tmac_5_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff textwidth=72: diff --git a/man/man.am b/man/man.am new file mode 100644 index 0000000..f37e906 --- /dev/null +++ b/man/man.am @@ -0,0 +1,46 @@ +# Copyright (C) 2014-2020 Free Software Foundation, Inc. +# +# This file is part of 'groff'. +# +# 'groff' is free software; you can redistribute it and/or modify it +# under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# 'groff' is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +# General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see <http://www.gnu.org/licenses/>. + +man5_MANS += \ + man/groff_font.5 \ + man/groff_out.5 \ + man/groff_tmac.5 +man7_MANS += \ + man/groff_char.7 \ + man/groff_diff.7 \ + man/groff.7 \ + man/roff.7 +EXTRA_DIST += \ + man/groff_font.5.man \ + man/groff_out.5.man \ + man/groff_tmac.5.man \ + man/groff_char.7.man \ + man/groff_diff.7.man \ + man/groff.7.man \ + man/roff.7.man + +# Case of out-of-source build: we must create the 'man' directory. +BUILT_SOURCES += man +man: + $(MKDIR_P) $(top_builddir)/man + + +# Local Variables: +# mode: makefile-automake +# fill-column: 72 +# End: +# vim: set autoindent filetype=automake textwidth=72: diff --git a/man/roff.7.man b/man/roff.7.man new file mode 100644 index 0000000..2468a4b --- /dev/null +++ b/man/roff.7.man @@ -0,0 +1,2613 @@ +'\" t +.TH roff @MAN7EXT@ "@MDATE@" "groff @VERSION@" +.SH Name +roff \- concepts and history of +.I roff +typesetting +. +. +.\" TODO: Synchronize this material with introductory section(s) of our +.\" Texinfo manual, and then keep it that way. +. +.\" ==================================================================== +.\" 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_roff_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 +. +. +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +The term +.I roff +denotes a family of document formatting systems known by names like +.IR troff , +.IR nroff , +and +.IR ditroff . +. +A +.I roff +system consists of an interpreter for an extensible text formatting +language and a set of programs for preparing output for various devices +and file formats. +. +Unix-like operating systems often distribute a +.I roff +system. +. +The manual pages on Unix systems +(\[lq]man\~pages\[rq]) +and bestselling books on software engineering, +including Brian Kernighan and Dennis Ritchie's +.I The C Programming Language +and W.\& Richard Stevens's +.I Advanced Programming in the Unix Environment +have been written using +.I roff +systems. +. +GNU +.IR roff \[em] groff \[em]is +arguably the most widespread +.I roff +implementation. +. +. +.P +Below we present +typographical concepts that form the background of all +.I roff +implementations, +narrate the development history of some +.I roff +systems, +detail the command pipeline managed by +.MR groff @MAN1EXT@ , +survey the formatting language, +suggest tips for editing +.I roff +input, +and recommend further reading materials. +. +. +.\" ==================================================================== +.SH Concepts +.\" ==================================================================== +. +.\" BEGIN Keep roughly parallel with groff.texi nodes "Text" through +.\" "Tab Stops". +.I roff +input files contain text interspersed with instructions to control the +formatter. +. +Even in the absence of such instructions, +a +.I roff +formatter still processes its input in several ways, +by filling, +hyphenating, +breaking, +and adjusting it, +and supplementing it with inter-sentence space. +. +These processes are basic to typesetting, +and can be controlled at the input document's discretion. +. +. +.P +When a device-independent +.I roff +formatter starts up, +it obtains information about the device for which it is preparing +output from the latter's description file +(see +.MR groff_font @MAN5EXT@ ). +. +An essential property is the length of the output line, +such as \[lq]6.5 inches\[rq]. +. +. +.P +The formatter interprets plain text files employing the Unix line-ending +convention. +. +It reads input a character at a time, +collecting words as it goes, +and fits as many words together on an output line as it can\[em]this +is known as +.I filling. +. +To a +.I roff +system, +a +.I word +is any sequence of one or more characters that aren't spaces or +newlines. +. +The exceptions separate words. +. +. +.P +A +.I roff +formatter attempts to detect boundaries between sentences, +and supplies additional inter-sentence space between them. +. +It flags certain characters +(normally +.RB \[lq] !\& \[rq], +.RB \[lq] ?\& \[rq], +and +.RB \[lq] .\& \[rq]) +as potentially ending a sentence. +. +When the formatter encounters one of these +.I end-of-sentence characters +at the end of an input line, +or one of them is followed by two (unescaped) spaces on the same input +line, +it appends an inter-word space +followed by an inter-sentence space in the output. +. +The dummy character escape sequence +.B \[rs]& +can be used after an end-of-sentence character to defeat end-of-sentence +detection on a per-instance basis. +. +Normally, +the occurrence of a visible non-end-of-sentence character +(as opposed to a space or tab) +immediately after an end-of-sentence +character cancels detection of the end of a sentence. +. +However, +several characters are treated +.I transparently +after the occurrence of an end-of-sentence character. +. +That is, +a +.I roff +does not cancel end-of-sentence detection when it processes them. +. +This is because such characters are often used as footnote markers or to +close quotations and parentheticals. +. +The default set is +.BR \[dq] , +.BR \[aq] , +.BR ) , +.BR ] , +.BR * , +.BR \[rs][dg] , +.BR \[rs][dd] , +.BR \[rs][rq] , +and +.BR \[rs][cq] . +. +The last four are examples of +.I special characters, +escape sequences whose purpose is to obtain glyphs that are not easily +typed at the keyboard, +or which have special meaning to the formatter +(like +.BR \[rs] ). +.\" slack wording: itself). +. +. +.P +When an output line is nearly full, +it is uncommon for the next word collected from the input to exactly +fill it\[em]typically, +there is room left over only for part of the next word. +. +The process of splitting a word so that it appears partially on one line +(with a hyphen to indicate to the reader that the word has been broken) +with its remainder on the next is +.I hyphenation. +. +Hyphenation points can be manually specified; +.I groff +also uses a hyphenation algorithm and language-specific pattern files to +decide which words can be hyphenated and where. +. +Hyphenation does not always occur even when the hyphenation rules for a +word allow it; +it can be disabled, +and when not disabled there are several parameters that can prevent it +in certain circumstances. +. +. +.P +Once an output line is full, +the next word +(or remainder of a hyphenated one) +is placed on a different output line; +this is called a +.I break. +. +In this document and in +.I roff +discussions generally, +a \[lq]break\[rq] if not further qualified always refers to the +termination of an output line. +. +When the formatter is filling text, +it introduces breaks automatically to keep output lines from exceeding +the configured line length. +. +After an automatic break, +a +.I roff +formatter +.I adjusts +the line if applicable +(see below), +and then resumes collecting and filling text on the next output line. +. +. +.br +.ne 2v +.P +Sometimes, +a line cannot be broken automatically. +. +This usually does not happen with natural language text unless the +output line length has been manipulated to be extremely short, +but it can with specialized text like program source code. +. +.I groff +provides a means of telling the formatter where the line may be broken +without hyphens. +. +This is done with the non-printing break point escape sequence +.BR \[rs]: . +. +. +.P +.\" What if the document author wants to stop filling lines temporarily, +.\" for instance to start a new paragraph? There are several solutions. +There are several ways to cause a break at a predictable location. +. +A blank input line not only causes a break, +but by default it also outputs a one-line vertical space +(effectively a blank output line). +. +Macro packages may discourage or disable this \[lq]blank line +method\[rq] of paragraphing in favor of their own macros. +. +A line that begins with one or more spaces causes a break. +. +The spaces are output at the beginning of the next line without being +.I adjusted +(see below). +. +Again, +macro packages may provide other methods of producing indented +paragraphs. +. +Trailing spaces on +.I text lines +(see below) +are discarded. +. +The end of input causes a break. +. +. +.P +After the formatter performs an automatic break, +it may then +.I adjust +the line, +widening inter-word spaces until the text reaches the right margin. +. +Extra spaces between words are preserved. +. +Leading and trailing spaces are handled as noted above. +. +Text can be aligned to the left or right margin only, +or centered, +using +.I requests. +. +. +.P +A +.I roff +formatter translates horizontal tab characters, +also called simply \[lq]tabs\[rq], +in the input into movements to the next tab stop. +. +These tab stops are by default located every half inch measured from the +current position on the input line. +. +With them, +simple tables can be made. +. +However, +this method can be deceptive, +as the appearance +(and width) +of the text in an editor and the results from the formatter can vary +greatly, +particularly when proportional typefaces are used. +. +A tab character does not cause a break and therefore does not interrupt +filling. +. +The formatter provides facilities for sophisticated table composition; +there are many details to track +when using the \[lq]tab\[rq] and \[lq]field\[rq] low-level features, +so most users turn to the +.MR @g@tbl @MAN1EXT@ +preprocessor to lay out tables. +.\" END Keep roughly parallel with groff.texi nodes "Text" through "Tab +.\" Stops". +. +. +.\" ==================================================================== +.SS "Requests and macros" +.\" ==================================================================== +. +.\" BEGIN Keep roughly parallel with groff.texi node "Requests and +.\" Macros". +.\" We have now encountered almost all of the syntax there is in the +.\" @code{roff} language, with an exception already noted in passing. +A +.I request +is an instruction to the formatter that occurs after a +.I control character, +which is recognized at the beginning of an input line. +. +The regular control character is a dot +.RB \[lq] .\& \[rq]. +. +Its counterpart, +the +.I no-break control character, +a neutral apostrophe +.RB \[lq] \|\[aq]\| \[rq], +suppresses the break +.\" slack wording: that is +implied by some requests. +. +These characters were chosen because it is uncommon for lines of text in +natural languages to begin with them. +. +If you require a formatted period or apostrophe +(closing single quotation mark) +where +.\" GNU @code{troff} +the formatter is expecting a control character, +prefix the dot or neutral apostrophe with the dummy character escape +sequence, +.RB \[lq] \[rs]& \[rq]. +. +. +.P +An input line beginning with a control character is called a +.I control line. +. +Every line of input that is not a control line is a +.I text line. +. +. +.P +Requests often take +.I arguments, +words +(separated from the request name and each other by spaces) +that specify details of the action +.\" GNU @code{troff} +the formatter is expected to perform. +. +If a request is meaningless without arguments, +it is typically ignored. +. +.\" TODO: roff(7): We haven't introduced escape sequences yet. +.\" GNU @code{troff}'s requests and escape sequences comprise the +.\" control language of the formatter. +. +Of key importance are the requests that define macros. +. +Macros are invoked like requests, +enabling the request repertoire to be extended or overridden. +.\" @footnote{Argument handling in macros is more flexible but also more +.\" complex. @xref{Calling Macros}.} +. +. +.P +A +.I macro +can be thought of as an abbreviation you can define for a +collection of control and text lines. +. +When the macro is +.I called +by giving its name after a control character, +it is replaced with what it stands for. +. +The process of textual replacement is known as +.I interpolation. +.\" @footnote{Some escape sequences undergo interpolation as well.} +Interpolations are handled as soon as they are recognized, +and once performed, +a +.I roff +formatter scans the replacement for further requests, +macro calls, +and escape sequences. +. +. +.P +In +.I roff +systems, +the +.RB \[lq] de \[rq] +request defines a macro. +.\" @footnote{GNU @code{troff} offers additional ones. @xref{Writing +.\" Macros}.} +.\" END Keep roughly parallel with groff.texi node "Requests and +.\" Macros". +. +. +.\" ==================================================================== +.SS "Page geometry" +.\" ==================================================================== +. +.\" BEGIN Keep parallel with groff.texi node "Page Geometry". +.I roff +systems format text under certain assumptions about the size of the +output medium, +or page. +. +For the formatter to correctly break a line it is filling, +it must know the line length, +which it derives from the page width. +.\" (@pxref{Line Layout}). +. +For it to decide whether to write an output line to the current page or +wait until the next one, +it must know the page length. +.\" (@pxref{Page Layout}). +. +. +A device's +.I resolution +converts practical units like inches or centimeters to +.I basic units, +a convenient length measure for the output device or file format. +. +The formatter and output driver use basic units to reckon page +measurements. +. +The device description file defines its resolution and page dimensions +(see +.MR groff_font @MAN5EXT@ ). +.\" (@pxref{DESC File Format}). +. +. +.P +A +.I page +is a two-dimensional structure upon which a +.I roff +system imposes a rectangular coordinate system with its upper left +corner as the origin. +. +Coordinate values are in basic units and increase down and to the right. +Useful ones are therefore always positive and within numeric ranges +corresponding to the page boundaries. +. +. +.P +While the formatter +(and, +later, +output driver) +is processing a page, +it keeps track of its +.I drawing position, +which is the location at which the next glyph will be written, +from which the next motion will be measured, +or where a geometric object will commence rendering. +. +Notionally, +glyphs are drawn from the text baseline upward and to the right. +.RI ( groff +does not yet support right-to-left scripts.) +. +The +.I text baseline +is a +(usually invisible) +line upon which the glyphs of a typeface are aligned. +. +A glyph therefore \[lq]starts\[rq] at its bottom-left corner. +. +If drawn at the origin, +a typical letter glyph would lie partially or wholly off the page, +depending on whether, +like \[lq]g\[rq], +it features a descender below the baseline. +. +. +.P +Such a situation is nearly always undesirable. +. +It is furthermore conventional not to write or draw at the extreme edges +of the page. +. +Therefore the initial drawing position of a +.I roff +formatter is not at the origin, +but below and to the right of it. +. +This rightward shift +from the left edge is known as the +.I page offset. +. +.RI ( groff 's +terminal output devices have page offsets of zero.) +. +The downward shift leaves room for a text output line. +. +. +.P +Text is arranged on a one-dimensional lattice of text baselines from +the top to the bottom of the page. +. +.I Vertical spacing +is the distance between adjacent text baselines. +. +Typographic tradition sets this quantity to 120% of the type size. +. +The initial vertical drawing position is one unit of vertical spacing +below the page top. +. +Typographers term this unit a +.I vee. +. +. +.P +Vertical spacing has an impact on page-breaking decisions. +. +Generally, +when a break occurs, +the formatter moves the drawing position to the next text baseline +automatically. +. +If the formatter were already writing to the last line that would fit on +the page, +advancing by one vee would place the next text baseline off the page. +. +Rather than let that happen, +.I roff +formatters instruct the output driver to eject the page, +start a new one, +and again set the drawing position to one vee below the page top; +this is a +.I page break. +. +. +.P +When the last line of input text corresponds to the last output line +that fits on the page, +the break caused by the end of input will also break the page, +producing a useless blank one. +. +Macro packages keep users from having +to confront this difficulty by setting \[lq]traps\[rq]; +.\" (@pxref{Traps}); +moreover, +all but the simplest page layouts tend to have headers and footers, +or at least bear vertical margins larger than one vee. +.\" END Keep parallel with groff.texi node "Page Geometry". +. +. +.\" ==================================================================== +.SS "Other language elements" +.\" ==================================================================== +. +.I Escape sequences +start with the +.I escape character, +a backslash +.BR \[rs] , +and are followed by at least one additional character. +. +They can appear anywhere in the input. +. +. +.P +With requests, +the escape and control characters can be changed; +further, +escape sequence recognition can be turned off and back on. +. +. +.P +.I Strings +store character sequences. +. +In +.IR groff , +they can be parameterized as macros can. +. +. +.P +.I Registers +store numerical values, +including measurements. +. +The latter are generally in basic units; +.I scaling units +can be appended to numeric expressions to clarify their meaning when +stored or interpolated. +. +Some read-only predefined registers interpolate text. +. +. +.P +.I Fonts +are identified either by a name or by a mounting position +(a non-negative number). +. +Four styles are available on all devices. +. +.B R +is \[lq]roman\[rq]: +normal, +upright text. +. +.B B +is +.BR bold , +an upright typeface with a heavier weight. +. +.B I +is +.IR italic , +a face that is oblique on typesetter output devices and usually +underlined instead on terminal devices. +. +.B BI +is \f[BI]bold-italic\f[]\/, \" indulging a bit of man(7) evil here +combining both of the foregoing style variations. +. +Typesetting devices group these four styles into +.I families +of text fonts; +they also typically offer one or more +.I special +fonts that provide unstyled glyphs; +see +.MR groff_char @MAN7EXT@ . +. +. +.P +.I groff +supports named +.I colors +for glyph rendering and drawing of geometric objects. +. +Stroke and fill colors are distinct; +the stroke color is used for glyphs. +. +. +.P +.I Glyphs +are visual representation forms of +.I characters. +. +In +.I groff, +the distinction between those two elements is not always obvious +(and a full discussion is beyond our scope). +. +In brief, +\[lq]A\[rq] is a character when we consider it in the abstract: +to make it a glyph, +we must select a typeface with which to render it, +and determine its type size and color. +. +The formatting process turns input characters into output glyphs. +. +A few characters commonly seen on keyboards are treated +specially by the +.I roff +language and may not look correct in output if used unthinkingly; +they are +the (double) quotation mark +.RB ( \|\[dq]\| ), +the neutral apostrophe +.RB ( \|\[aq]\| ), +the minus sign +.RB ( \- ), +the backslash +.RB ( \|\[rs]\| ), +the caret or circumflex accent +.RB ( \[ha] ), +the grave accent +.RB ( \|\[ga]\| ), +and the tilde +.RB ( \[ti] ). +. +All of these and more can be produced with +.I special character +escape sequences; +see +.MR groff_char @MAN7EXT@ . +. +. +.P +.I groff +offers +.IR streams , +identifiers for writable files, +but for security reasons this feature is disabled by default. +. +. +.\" BEGIN Keep roughly parallel with first paragraphs of groff.texi node +.\" "Deferring Output". +.P +A further few language elements arise as page layouts become more +sophisticated and demanding. +. +.I Environments +collect formatting parameters like line length and typeface. +. +A +.I diversion +stores formatted output for later use. +. +A +.I trap +is a condition on the input or output, +tested automatically by the formatter, +that is associated with a macro, +calling it when that condition is fulfilled. +. +. +.P +Footnote support often exercises all three of the foregoing features. +. +A simple implementation might work as follows. +. +A pair of macros is defined: +one starts a footnote and the other ends it. +. +The author calls the first macro where a footnote marker is desired. +. +The macro establishes a diversion so that the footnote text is collected +at the place in the body text where its corresponding marker appears. +. +An environment is created for the footnote so that it is set at a +smaller typeface. +. +The footnote text is formatted in the diversion using that environment, +but it does not yet appear in the output. +. +The document author calls the footnote end macro, +which returns to the previous environment and ends the diversion. +. +Later, +after much more body text in the document, +a trap, +set a small distance above the page bottom, +is sprung. +. +The macro called by the trap draws a line across the page and emits the +stored diversion. +. +Thus, +the footnote is rendered. +.\" END Keep roughly parallel with first paragraphs of groff.texi node +.\" "Deferring Output". +. +. +.\" ==================================================================== +.SH History +.\" ==================================================================== +. +Computer-driven document formatting dates back to the 1960s. +.\" John Labovitz points out that Peter Samson's TJ-2 dates to 1963, +.\" but since this is a *roff man page, we do not begin our story there. +.\" https://johnlabovitz.com/publications/\ +.\" The-electric-typesetter--The-origins-of-computing-in-typography.pdf +. +The +.I roff +system is intimately connected with Unix, +but its origins lie with the earlier operating systems CTSS, +GECOS, +and Multics. +. +. +.\" ==================================================================== +.SS "The predecessor\[em]\f[I]RUNOFF\f[]" +.\" ==================================================================== +. +.IR roff 's +ancestor +.I RUNOFF +was written in the MAD language by Jerry Saltzer +to prepare his Ph.D.\& thesis on the Compatible Time Sharing System +(CTSS), +a project of the Massachusetts Institute of Technology (MIT). +. +This program is referred to in full capitals, +both to distinguish it from its many descendants, +and because bits were expensive in those days; +five- and six-bit character encodings were still in widespread usage, +and mixed-case alphabetics in file names seen as a luxury. +. +.I RUNOFF +introduced a syntax of inlining formatting directives amid document +text, +by beginning a line with a period +(an unlikely occurrence in human-readable material) +followed by a \[lq]control word\[rq]. +. +Control words with obvious meaning like \[lq].line length +.IR n \[rq] +were supported as well as an abbreviation system; +the latter came to overwhelm the former in popular usage and later +derivatives of the program. +. +A sample of control words from a +.UR http://\:web\:.mit\:.edu/\:Saltzer/\:www/\:publications/\:ctss/\:AH\ +\:.9\:.01\:.html +.I RUNOFF +manual of December 1966 +.UE +was documented as follows +(with the parameter notation slightly altered). +. +The abbreviations will be familiar to +.I roff +veterans. +. +. +.P +.ne 10v +.TS +center; +r l +rB l. +Abbreviation Control word +\&.ad .adjust +\&.bp .begin page +\&.br .break +\&.ce .center +\&.in .indent \f[I]n\f[] +\&.ll .line length \f[I]n\f[] +\&.nf .nofill +\&.pl .paper length \f[I]n\f[] +\&.sp .space [\f[I]n\f[]] +.TE +. +. +.P +In 1965, +MIT's Project MAC teamed with Bell Telephone Laboratories and General +Electric (GE) to inaugurate the +.UR http://\:www\:.multicians\:.org +Multics +.UE +project. +. +After a few years, +Bell Labs discontinued its participation in Multics, +famously prompting the development of Unix. +. +Meanwhile, +Saltzer's +.I RUNOFF +proved influential, +seeing many ports and derivations elsewhere. +. +. +.\" "Morris did one port and called it roff. I did the BCPL one, adding +.\" registers, but not macros. Molly Wagner contributed a hyphenation +.\" algorithm. Ken and/or Dennis redid roff in PDP-11 assembler. Joe +.\" started afresh for the grander nroff, including macros. Then Joe +.\" bought a phototypesetter ..." +.\" -- https://minnie.tuhs.org/pipermail/tuhs/2018-November/017052.html +.P +In 1969, +Doug McIlroy wrote one such reimplementation, +adding extensions, +in the BCPL language for a GE 645 running GECOS at the Bell Labs +location in Murray Hill, +New Jersey. +. +In its manual, +the control commands were termed \[lq]requests\[rq], +their two-letter names were canonical, +and the control character was configurable with a +.B .cc +request. +. +Other familiar requests emerged at this time; +no-adjust +.RB ( .na ), +need +.RB ( .ne ), +page offset +.RB ( .po ), +tab configuration +.RB ( .ta , +though it worked differently), +temporary indent +.RB ( .ti ), +character translation +.RB ( .tr ), +and automatic underlining +.RB ( .ul ; +on +.I RUNOFF +you had to backspace and underscore in the input yourself). +.B .fi +to enable filling of output lines got the name it retains to this day. +. +McIlroy's program also featured a heuristic system for automatically +placing hyphenation points, +designed and implemented by Molly Wagner. +. +It furthermore introduced numeric variables, +termed registers. +. +By 1971, +this program had been ported to Multics and was known as +.IR roff , +a name McIlroy attributes to Bob Morris, +to distinguish it from CTSS +.IR RUNOFF . +. +.\" GBR can't find a source for this claim (of Bernd's). +.\"Multics +.\".I runoff +.\"added features such as the ability to do two-pass formatting; +.\"it became the main system for Multics documentation and text +.\"processing. +. +. +.\" ==================================================================== +.SS "Unix and \f[I]roff\f[]" +.\" ==================================================================== +. +McIlroy's +.I roff +was one of the first Unix programs. +. +In Ritchie's term, +it was \[lq]transliterated\[rq] from BCPL to DEC PDP-7 assembly language +.\" see "The Evolution of the Unix Time-Sharing System", Ritchie, 1984 +for the fledgling Unix operating system. +. +Automatic hyphenation was managed with +.B .hc +and +.B .hy +requests, +line spacing control was generalized with the +.B .ls +request, +and what later +.IR roff s +would call diversions were available via \[lq]footnote\[rq] requests. +.\" The foregoing features may have been in McIlroy's Multics roff, but +.\" he no longer has documentation for that--only the GECOS version. +.\" GBR's guess is that they were, if we take Ritchie's choice of the +.\" term "transliterated" seriously. GBR further speculates that there +.\" is no reason to suppose that McIlroy's roff was stagnant from +.\" 1969-1971, whereas we have no record of any significant +.\" post-transliteration development of Unix roff. Its request list did +.\" not appear until the 3rd edition manual, and did not change +.\" thereafter. In 7th edition, roff was characterized as "utterly +.\" frozen". +. +This +.I roff +indirectly funded operating systems research at Murray Hill; +AT&T prepared patent applications to the U.S.\& government with it. +. +This arrangement enabled the group to acquire a PDP-11; +.I roff +promptly proved equal to the task of formatting the manual for what +would become known as \[lq]First Edition Unix\[rq], +dated November 1971. +. +. +.P +Output from all of the foregoing programs was limited to line printers +and paper terminals such as the IBM 2471 +(based on the Selectric line of typewriters) +and the Teletype Corporation Model 37. +. +Proportionally spaced type was unavailable. +. +. +.\" ==================================================================== +.SS "New \f[I]roff\f[] and Typesetter \f[I]roff\f[]" +.\" ==================================================================== +. +The first years of Unix were spent in rapid evolution. +. +The practicalities of preparing standardized documents like patent +applications +(and Unix manual pages), +combined with McIlroy's enthusiasm for macro languages, +perhaps created an irresistible pressure to make +.I roff +extensible. +. +Joe Ossanna's +.IR nroff , +literally a \[lq]new roff\[rq], +was the outlet for this pressure. +. +.\" nroff is listed in the table of contents of the Version 2 manual, +.\" but no man page is present. +By the time of Unix Version\~3 +(February 1973)\[em]and still in PDP-11 assembly language\[em]it sported +a swath of features now considered essential to +.I roff +systems: +. +definition of macros +.RB ( .de ), +diversion of text thither +.RB ( .di ), +and removal thereof +.RB ( .rm ); +. +trap planting +.RB ( .wh ; +\[lq]when\[rq]) +and relocation +.RB ( .ch ; +\[lq]change\[rq]); +. +conditional processing +.RB ( .if ); +. +and environments +.RB ( .ev ). +. +Incremental improvements included +. +assignment of the next page number +.RB ( .pn ); +. +no-space mode +.RB ( .ns ) +and restoration of vertical spacing +.RB ( .rs ); +. +the saving +.RB ( .sv ) +and output +.RB ( .os ) +of vertical space; +. +specification of replacement characters for tabs +.RB ( .tc ) +and leaders +.RB ( .lc ); +. +configuration of the no-break control character +.RB ( .c2 ); +. +shorthand to disable automatic hyphenation +.RB ( .nh ); +. +a condensation of what were formerly six different requests for +configuration of page \[lq]titles\[rq] +(headers and footers) +into one +.RB ( .tl ) +with a length controlled separately from the line length +.RB ( .lt ); +. +automatic line numbering +.RB ( .nm ); +. +interactive input +.RB ( .rd ), +which necessitated buffer-flushing +.RB ( .fl ), +and was made convenient with early program cessation +.RB ( .ex ); +. +source file inclusion in its modern form +.RB ( .so ; +though +.I RUNOFF +had an \[lq].append\[rq] control word for a similar purpose) +and early advance to the next file argument +.RB ( .nx ); +. +ignorable content +.RB ( .ig ); +. +and programmable abort +.RB ( .ab ). +. +. +.P +Third Edition Unix also brought the +.MR pipe 2 +system call, +the explosive growth of a componentized system based around it, +and a \[lq]filter model\[rq] that remains perceptible today. +. +Equally importantly, +the Bell Labs site in Murray Hill acquired a Graphic Systems C/A/T +phototypesetter, +and with it came the necessity of expanding the capabilities of a +.I roff +system to cope with a variety of proportionally spaced typefaces at +multiple sizes. +. +Ossanna wrote a parallel implementation of +.I nroff +for the C/A/T, +dubbing it +.I troff +(for \[lq]typesetter roff\[rq]). +. +Unfortunately, +surviving documentation does not illustrate what requests were +implemented at this time for C/A/T support; +the +.MR troff 1 \" AT&T +man page in Fourth Edition Unix +(November 1973) +does not feature a request list, \" nor does Unix V6 troff(1) (1975) +unlike +.MR nroff 1 . \" AT&T +. +Apart from typesetter-driven features, +Unix Version\~4 +.IR roff s +added string definitions +.RB ( .ds ); +made the escape character configurable +.RB ( .ec ); +and enabled the user to write diagnostics to the standard error stream +.RB ( .tm ). +. +Around 1974, +empowered with multiple type sizes, +italics, +and a symbol font specially commissioned by Bell Labs from +Graphic Systems, +Kernighan and Lorinda Cherry implemented +.I eqn \" AT&T +for typesetting mathematics. +. +. +In the same year, +for Fifth Edition Unix, +Ossanna combined and reimplemented the two +.IR roff s +in C, +using that language's preprocessor to generate both from a single source +tree. +. +. +.P +Ossanna documented the syntax of the input language to the +.I nroff +and +.I troff +programs in the \[lq]Troff User's Manual\[rq], +first published in 1976, +with further revisions as late as 1992 by Kernighan. +. +(The original version was entitled +\[lq]Nroff/Troff User's Manual\[rq], +which may partially explain why +.I roff +practitioners have tended to refer to it by its AT&T document +identifier, +\[lq]CSTR #54\[rq].) +. +Its final revision serves as the +.I de facto +specification of AT&T +.IR troff , \" AT&T +and all subsequent implementors of +.I roff +systems have done so in its shadow. +. +. +.P +A small and simple set of +.I roff +macros was first used for the manual pages of Unix Version\~4 and +persisted for two further releases, +but the first macro package to be formally described and installed was +.I ms +by Michael Lesk in Version\~6. +. +He also wrote a manual, +\[lq]Typing Documents on the Unix System\[rq], +describing +.I ms +and basic +.IR nroff / troff +usage, +updating it as the package accrued features. +. +Sixth Edition additionally saw the debut of the +.I tbl \" AT&T +preprocessor for formatting tables, +also by Lesk. +. +. +.P +For Unix Version\~7 +(January 1979), +McIlroy designed, +implemented, +and documented the +.I man +macro package, +introducing most of the macros described in +.MR groff_man 7 +today, +and edited volume 1 of the Version 7 manual using it. +. +Documents composed using +.I ms +featured in volume 2, +edited by Kernighan. +. +. +.\" Thanks to Clem Cole for the following account. +.\" https://minnie.tuhs.org/pipermail/tuhs/2022-January/025143.html +.P +Meanwhile, +.I troff +proved popular even at Unix sites that lacked a C/A/T device. +. +Tom Ferrin of the University of California at San Francisco combined it +with Allen Hershey's popular vector fonts to produce +.IR vtroff , +which translated +.IR troff 's +output to the command language used by Versatec and Benson-Varian +plotters. +. +. +.P +Ossanna had passed away unexpectedly in 1977, +and after the release of Version 7, +with the C/A/T typesetter becoming supplanted by alternative devices +such as the Mergenthaler Linotron 202, +Kernighan undertook a revision and rewrite of +.I troff +to generalize its design. +. +To implement this revised architecture, +he developed the font and device description file formats and the +page description language that remain in use today. +. +He described these novelties in the article +\[lq]A Typesetter-independent TROFF\[rq], +last revised in 1982, +and like the +.I troff +manual itself, +it is widely known by a shorthand, +\[lq]CSTR #97\[rq]. +.\" Further entertaining reading can be found at: +.\" <https://www.cs.princeton.edu/~bwk/202/summer.reconstructed.pdf>. +. +. +.P +Kernighan's innovations prepared +.I troff +well for the introduction of the Adobe PostScript language in 1982 and a +vibrant market in laser printers with built-in interpreters for it. +. +An output driver for PostScript, +.IR dpost , +was swiftly developed. +. +However, +AT&T's software licensing practices kept +Ossanna's +.IR troff , +with its tight coupling to the C/A/T's capabilities, +in parallel distribution with device-independent +.I troff +throughout the 1980s. +. +Today, +however, +all actively maintained +.IR troff s +follow Kernighan's device-independent design. +. +. +.\" ==================================================================== +.SS "\f[I]groff\f[]\[em]a free \f[I]roff\f[] from GNU" +.\" ==================================================================== +. +The most important free +.I roff +project historically has been +.IR groff , +the GNU implementation of +.IR troff , +developed by James Clark starting in 1989 and distributed under +.UR http://\:www\:.gnu\:.org/\:copyleft +copyleft +.UE +licenses, +ensuring to all the availability of source code and the freedom to +modify and redistribute it, +properties unprecedented in +.I roff +systems to that point. +. +.I groff +rapidly attracted contributors, +and has served as a replacement for almost all applications of AT&T +.I troff +(exceptions include +.IR mv , +a macro package for preparation of viewgraphs and slides, +and the +.I ideal +preprocessor, +which produces diagrams from mathematical constraints). +. +Beyond that, +it has added numerous features; +see +.MR groff_diff @MAN7EXT@ . +. +Since its inception and for at least the following three decades, +it has been used by practically all GNU/Linux and BSD operating systems. +. +. +.P +.I groff +continues to be developed, +is available for almost all operating systems in common use +(along with several obscure ones), +and is free. +. +These factors make +.I groff +the +.I de facto +.I roff +standard today. +. +. +.\" ==================================================================== +.SS "Other free \f[I]roff\f[]s" +.\" ==================================================================== +. +In 2007, \" TODO: verify +Caldera/SCO and Sun Microsystems, +having acquired rights to AT&T Documenter's Workbench (DWB) +.I troff +(a descendant of the Bell Labs code), +released it under a free but GPL-incompatible license. +. +.UR https://\:github\:.com/\:n\-t\-roff/\:DWB3.3 +This implementation +.UE +was made portable to modern POSIX systems, +and adopted and enhanced first by Gunnar Ritter and then Carsten Kunze +to produce +.UR https://github.com/n-t-roff/heirloom-doctools +Heirloom Doctools +.I troff +.UE . +. +. +.P +.\" https://lists.gnu.org/archive/html/groff/2013-07/msg00001.html +In July 2013, +Ali Gholami Rudi announced +.UR https://\:github\:.com/\:aligrudi/\:neatroff +.I neatroff +.UE , +a permissively licensed new implementation. +. +. +.P +Another descendant of DWB +.I troff \" DWB +is part of +.UR https://\:9fans\:.github\:.io/\:plan9port/ +Plan\~9 from User Space +.UE . +. +Since 2021, +this +.I troff \" Plan 9 from User Space +has been available under permissive terms. +. +. +.\" ==================================================================== +.SH "Using \f[I]roff\f[]" +.\" ==================================================================== +. +When you read a man page, +often a +.I roff +is the program rendering it. +. +Some +.I roff +implementations provide wrapper programs that make it easy to use the +.I roff +system from the shell's command line. +. +These can be specific to a macro package, +like +.MR mmroff @MAN1EXT@ , +or more general. +. +.MR groff @MAN1EXT@ +provides command-line options sparing the user from constructing the +long, +order-dependent pipelines familiar to AT&T +.I troff +users. +. +Further, +a heuristic program, +.MR grog @MAN1EXT@ , +is available to infer from a document's contents which +.I groff +arguments should be used to process it. +. +. +.\" ==================================================================== +.SS "The \f[I]roff\f[] pipeline" +.\" ==================================================================== +. +A typical +.I roff +document is prepared by running one or more processors in series, +followed by a a formatter program and then an output driver +(or \[lq]device postprocessor\[rq]). +. +Commonly, +these programs are structured into a pipeline; +that is, +each is run in sequence such that the output of one is +taken as the input +to the next, +without passing through secondary storage. +. +(On non-Unix systems, +pipelines may have to be simulated with temporary files.) +. +. +.RS +.PP +.EX +.RI $\~ preproc1 \~\c +.BI <\~ input-file \~|\~ preproc2 \~|\~\c +.RB .\|.\|.\&\~ "| troff\~"\c +.RI [ option ]\~\c +.RB .\|.\|.\&\~ \[rs] +.BI " |\~" output-driver \" 4 leading spaces +.EE +.RE +. +. +.P +Once all preprocessors have run, +they deliver pure +.I roff +language input to the formatter, +which in turn generates a document in a page description language that +is then interpreted by a postprocessor for viewing, +printing, +or further processing. +. +. +.P +Each program interprets input in a language that is independent of the +others; +some are purely descriptive, +as with +.MR @g@tbl @MAN1EXT@ +and +.I roff +output, +and some permit the definition of macros, +as with +.MR @g@eqn @MAN1EXT@ +and +.I roff +input. +. +. +Most +.I roff +input files employ the macros of a document formatting package, +intermixed with instructions for one or more preprocessors, +and seasoned with escape sequences and requests from the +.I roff +language. +. +Some documents are simpler still, +since their formatting packages discourage direct use of +.I roff +requests; +man pages are a prominent example. +. +Many features of the +.I roff +language are seldom needed by users; +only authors of macro packages require a substantial command of them. +. +. +.\" ==================================================================== +.SS Preprocessors +.\" ==================================================================== +. +A +.I roff +preprocessor is a program that, +directly or ultimately, +generates output in the +.I roff +language. +. +Typically, \" preconv is an exception. +each preprocessor defines a language of its own that transforms its +input into that for +.I roff +or another preprocessor. +. +As an example of the latter, +.I chem \" generic +produces +.I pic \" generic +input. +. +Preprocessors must consequently be run in an appropriate order; +.MR groff @MAN1EXT@ +handles this automatically for all preprocessors supplied by the GNU +.I roff +system. +. +. +.P +Portions of the document written in preprocessor languages are usually +.\" preconv is the exception again. +bracketed by tokens that look like +.I roff +macro calls. +. +.I roff +preprocessor programs transform only the regions of the document +intended for them. +.\" In preconv's case, that's the whole document. +. +When a preprocessor language is used by a document, +its corresponding program must process it before the input is seen by +the formatter, +or incorrect rendering is almost guaranteed. +. +. +.P +GNU +.I roff +provides several preprocessors, +including +.IR @g@eqn , +.IR @g@grn , +.IR @g@pic , +.IR @g@tbl , +.IR @g@refer , +and +.IR @g@soelim . +. +See +.MR groff @MAN1EXT@ +for a complete list. +. +Other preprocessors for +.I roff +systems are known. +. +. +.P +.RS +.TS +tab (@); +Li L. +dformat@depicts data structures; +grap@constructs statistical charts; and +ideal@draws diagrams using a constraint-based language. +.TE +.RE +. +. +.\" ==================================================================== +.SS "Formatter programs" +.\" ==================================================================== +. +A +.I roff +formatter transforms +.I roff +language input into a single file in a page description language, +described in +.MR groff_out @MAN5EXT@ , +intended for processing by a selected device. +. +This page description language is specialized in its parameters, +but not its syntax, +for the selected device; +the format is +.RI device- independent , +but not +.RI device- agnostic . +. +The parameters the formatter uses to arrange the document are stored in +.I device +and +.IR "font description files" ; +see +.MR groff_font @MAN5EXT@ . +. +. +.P +AT&T Unix +had two formatters\[em]\c +.I nroff +for terminals, +and +.I troff +for typesetters. +. +Often, +the name +.I troff +is used loosely to refer to both. +. +When generalizing thus, +.I groff +documentation prefers the term +.RI \[lq] roff \[rq]. +. +In GNU +.IR roff , +the formatter program is always +.MR @g@troff @MAN1EXT@ . +. +. +.\" ==================================================================== +.SS "Devices and output drivers" +.\" ==================================================================== +. +To a +.I roff +system, +a +.I device +is a hardware interface like a printer, +a text or graphical terminal, +or a standardized file format that unrelated software can interpret. +. +An +.I output driver +is a program that parses the output of +.I troff \" generic +and produces instructions specific to the device or file format it +supports. +. +An output driver might support multiple devices, +particularly if they are similar. +. +. +.P +The names of the devices and their driver programs are not standardized. +. +Technological fashions evolve; +the devices used for document preparation when AT&T +.I troff \" AT&T +was first written in the 1970s are no longer used in production +environments. +. +Device capabilities have tended to increase, +improving resolution and font repertoire, +and adding color output and hyperlinking. +. +Further, +to reduce file size and processing time, +AT&T +.IR troff 's \" AT&T +page description language placed low limits on the magnitudes of some +quantities it could represent. +. +Its PostScript output driver, +.MR dpost 1 , +had a resolution of 720 units per inch; +.IR groff 's +.MR grops @MAN1EXT@ +uses 72,000. +. +. +.\".P +.\"Today the operating systems provide device drivers for most +.\"printer-like hardware, so it isn't necessary to write a special +.\"hardware postprocessor for each printer. +.\" XXX? No they don't. Instead printers interpret PS or PDF directly. +.\" With a TCP/IP protocol stack and an HTTP server to accept POSTed +.\" documents for printing. +. +. +.\" ==================================================================== +.SH "\f[I]roff\f[] programming" +.\" ==================================================================== +. +Documents using +.I roff +are normal text files interleaved with +.I roff +formatting elements. +. +The +.I roff +language is powerful enough to support arbitrary computation and +it supplies facilities that encourage extension. +. +The primary such facility is macro definition; +with this feature, +macro packages have been developed that are tailored for particular +applications. +. +. +.\" ==================================================================== +.SS "Macro packages" +.\" ==================================================================== +. +Macro packages can have a much smaller vocabulary than +.I roff +itself; +this trait combined with their domain-specific nature can make them easy +to acquire and master. +. +The macro definitions of a package are typically kept in a file called +.IB name .tmac +(historically, +.BI tmac. name\/\c\" Italic correction comes before \c ! +). +. +Find details on the naming and placement of macro packages in +.MR groff_tmac @MAN5EXT@ . +. +. +.P +A macro package anticipated for use in a document can be declared to +the formatter by the command-line option +.BR \-m ; +see +.MR @g@troff @MAN1EXT@ . +. +It can alternatively be specified within a document using the +.B mso +request of the +.I groff +language; +see +.MR groff @MAN7EXT@ . +. +. +.P +Well-known macro packages include +.I man +for traditional man pages and +.I mdoc +for BSD-style manual pages. +. +Macro packages for typesetting books, +articles, +and letters include +.I ms +(from \[lq]manuscript macros\[rq]), +.I me +(named by a system administrator from the first name of its creator, +Eric Allman), +.I mm +(from \[lq]memorandum macros\[rq]), +and +.IR mom , +a punningly named package exercising many +.I groff +extensions. +. +See +.MR groff_tmac @MAN5EXT@ +for more. +. +. +.\" ==================================================================== +.SS "The \f[I]roff\f[] formatting language" +.\" ==================================================================== +. +.\" TODO: Integrate this subsection with subsection "Other language +.\" elements". +The +.I roff +language provides requests, +escape sequences, +macro definition facilities, +string variables, +registers for storage of numbers or dimensions, +and control of execution flow. +. +The theoretically minded will observe that a +.I roff +is not a mere markup language, +but Turing-complete. +. +It has storage +(registers), +it can perform tests +(as in conditional expressions like +.RB \[lq] "(\[rs]n[i] >= 1)" \[rq]), +its +.\" Kerning between bold "i" and "f" and roman \[lq], \[rq] is tight. +.RB \[lq] \|if\| \[rq] +and related requests alter the flow of control, +and macro definition permits unbounded recursion. +. +. +.P +.I Requests +and +.I escape sequences +are instructions, +predefined parts of the language, +that perform formatting operations, +interpolate stored material, +or otherwise change the state of the parser. +. +The user can define their own request-like elements by composing +together text, +requests, +and escape sequences +.I "ad libitum." +. +. +A document writer will not (usually) note any difference in usage for +requests or macros; +both are found on control lines. +. +However, +there is a distinction; +requests take either a fixed number of arguments +(sometimes zero), +silently ignoring any excess, +or consume the rest of the input line, +whereas macros can take a variable number of arguments. +. +Since arguments are separated by spaces, +macros require a means of embedding a space in an argument; +in other words, +of quoting it. +. +This then demands a mechanism of embedding the quoting character itself, +in case +.I it +is needed literally in a macro argument. +. +AT&T +.I troff +had complex rules involving the placement and repetition of the double +quote to achieve both aims. +. +.I groff +cuts this knot by supporting a special character escape sequence for the +neutral double quote, +.\" The kerning between a roman \[lq] and a bold backslash is tight. +.RB \[lq] \|\[rs][dq] \[rq], +which never performs quoting in the typesetting language, +but is simply a glyph, +.RB \[oq] \[dq] \[cq]. +. +. +.P +.I Escape sequences +start with a backslash, +.RB \[lq] \|\[rs] \[rq]. +. +They can appear almost anywhere, +even in the midst of text on a line, +and implement various features, +including the insertion of special characters with +.RB \[lq] \|\[rs](\f[BI]xx\f[] \[rq] +or +.RB \[lq] \|\[rs][\f[BI]xxx\f[]] \[rq], +break suppression at input line endings with +.RB \[lq] \|\[rs]c \[rq], +font changes with +.RB \[lq] \|\[rs]f\| \[rq], +type size changes with +.RB \[lq] \|\[rs]s \[rq], +in-line comments with +.RB \[lq] \|\[rs]\[dq] \[rq], +and many others. +. +. +.P +.I Strings +store text. +. +They are populated with the +.B ds +request and interpolated using the +.B \[rs]* +escape sequence. +. +. +.P +.I Registers +store numbers and measurements. +. +A register can be set with the request +.B nr +and its value can be retrieved by the escape sequence +.BR "\[rs]n" . +. +. +.\" ==================================================================== +.SH "File naming conventions" +.\" ==================================================================== +. +The structure or content of a file name, +beyond its location in the file system, +is not significant to +.I roff +tools. +. +.I roff +documents employing \[lq]full-service\[rq] macro packages +(see +.MR groff_tmac @MAN5EXT@ ) +tend to be named with a suffix identifying the package; +we thus see file names ending in +.IR .man , +.IR .ms , +.IR .me , +.IR .mm , +and +.IR .mom , +for instance. +. +When installed, +man pages tend to be named with the manual's section number as the +suffix. +. +For example, +the file name for this document is +.IR roff.7 . +. +Practice for +\[lq]raw\[rq] +.I roff +documents is less consistent; +they +are sometimes seen with a +.I .t +suffix. +. +. +.\" BEGIN Keep parallel with groff.texi node "Input Conventions". +.\" ==================================================================== +.SH "Input conventions" +.\" ==================================================================== +. +Since +.I @g@troff +fills text automatically, +it is common practice in the +.I roff +language to avoid visual composition of text in input files: +the esthetic appeal of the formatted output is what matters. +. +Therefore, +.I roff +input should be arranged such that it is easy for authors and +maintainers to compose and develop the document, +understand the syntax of +.I roff +requests, +macro calls, +and preprocessor languages used, +and predict the behavior of the +formatter. +. +Several traditions have accrued in service of these goals. +. +. +.IP \[bu] 2n +Follow sentence endings in the input with newlines to ease their +recognition. +.\" Texinfo: (@pxref{Sentences}). +It is frequently convenient to end text lines after colons and +semicolons as well, +as these typically precede independent clauses. +. +Consider doing so after commas; +they often occur in lists that become easy to scan when itemized by +line, +or constitute supplements to the sentence that are added, +deleted, +or updated to clarify it. +. +Parenthetical and quoted phrases are also good candidates for placement +on text lines by themselves. +. +. +.IP \[bu] +Set your text editor's line length to 72 characters or fewer; +see the subsections below. +.\" Texinfo: +.\" @footnote{Emacs: @code{fill-column: 72}; Vim: @code{textwidth=72}} +. +This limit, +combined with the previous item of advice, +makes it less common that an input line will wrap in your text editor, +and thus will help you perceive excessively long constructions in your +text. +. +Recall that natural languages originate in speech, +not writing, +and that punctuation is correlated with pauses for breathing and changes +in prosody. +. +. +.IP \[bu] +Use +.B \[rs]& +after +.RB \[lq] !\& \[rq], +.RB \[lq] ?\& \[rq], +and +.RB \[lq] .\& \[rq] +if they are followed by space, +tab, +or newline characters and don't end a sentence. +. +. +.IP \[bu] +In filled text lines, +use +.B \[rs]& +before +.RB \[lq] .\& \[rq] +and +.RB \[lq] \[aq] \[rq] +if they are preceded by space, +so that reflowing the input doesn't turn them into control lines. +. +. +.IP \[bu] +Do not use spaces to perform indentation or align columns of a table. +Leading spaces are reliable when text is not being filled. +. +. +.IP \[bu] +Comment your document. +. +It is never too soon to apply comments to record information of use to +future document maintainers +(including your future self). +.\" Texinfo: We thus introduce another escape sequence, @code{\"}, which +The +.B \[rs]\[dq] +escape sequence +causes +.I @g@troff +to ignore the remainder of the input line. +. +. +.IP \[bu] +Use the empty request\[em]a control character followed immediately by a +newline\[em]to visually manage separation of material in input files. +. +Many of the +.I groff +project's own documents use an empty request between sentences, +after macro definitions, +and where a break is expected, +and two empty requests between paragraphs or other requests or macro +calls that will introduce vertical space into the document. +. +You can combine the empty request with the comment escape sequence to +include whole-line comments in your document, +and even \[lq]comment out\[rq] sections of it. +. +. +.P +.\" Texinfo: We conclude this section with an example +An example sufficiently long to illustrate most of the above suggestions +in practice follows. +. +.\" Texinfo: For the purpose of fitting the example between the margins +.\" of this manual with the font used for its typeset version, +.\" we have shortened the input line length to 56 +.\" columns. +.\" Texinfo: As before, +. +An arrow \[->] indicates a tab character. +. +. +.P +.RS +.EX +\&.\[rs]" nroff this_file.roff | less +\&.\[rs]" groff \-T ps this_file.roff > this_file.ps +\[->]The theory of relativity is intimately connected with +the theory of space and time. +\&. +I shall therefore begin with a brief investigation of +the origin of our ideas of space and time, +although in doing so I know that I introduce a +controversial subject.\& \[rs]" remainder of paragraph elided +\&. +.ne 3v \" Don't let a page break hide the blank line from the reader. +\&. +\& +\[->]The experiences of an individual appear to us arranged +in a series of events; +in this series the single events which we remember +appear to be ordered according to the criterion of +\[rs][lq]earlier\[rs][rq] and \[rs][lq]later\[rs][rq], \[rs]" punct \ +swapped +which cannot be analysed further. +\&. +There exists, +therefore, +for the individual, +an I\-time, +or subjective time. +\&. +This itself is not measurable. +\&. +I can, +indeed, +associate numbers with the events, +in such a way that the greater number is associated with +the later event than with an earlier one; +but the nature of this association may be quite +arbitrary. +\&. +This association I can define by means of a clock by +comparing the order of events furnished by the clock +with the order of a given series of events. +\&. +We understand by a clock something which provides a +series of events which can be counted, +and which has other properties of which we shall speak +later. +\&.\[rs]" Albert Einstein, _The Meaning of Relativity_, 1922 +.EE +.RE +.\" END Keep parallel with groff.texi node "Input Conventions". +. +. +.\" ==================================================================== +.SS "Editing with Emacs" +.\" ==================================================================== +. +Official GNU doctrine holds that the best program for editing a +.I roff +document is Emacs; see +.MR emacs 1 . +. +It provides an +.I nroff +major mode that is suitable for all kinds of +.I roff +dialects. +. +This mode can be activated by the following methods. +. +. +.P +When editing a file within Emacs the mode can be changed by typing +.RI \[lq] M-x +.BR nroff\-mode \[rq], +where +.I M-x +means to hold down the meta key +(often labelled \[lq]Alt\[rq]) +while pressing and releasing the \[lq]x\[rq] key. +.\" Why is this sort of thing not in intro(1)? +. +. +.P +It is also possible to have the mode automatically selected when a +.I roff +file is loaded into the editor. +. +. +.IP \(bu 2n +The most general method is to include file-local variables at the end of +the file; +we can also configure the fill column this way. +. +. +.RS +.IP +.EX +\&.\[rs]" Local Variables: +\&.\[rs]" fill\-column: 72 +\&.\[rs]" mode: nroff +\&.\[rs]" End: +.EE +.RE +. +.IP \(bu +Certain file name extensions, +such as those commonly used by man pages, +trigger the automatic activation of the +.I nroff +mode. +. +. +.br +.ne 3v +.IP \(bu +Technically, +having the sequence +. +. +.RS +.IP +.EX +\&.\[rs]" \%\-*\- nroff \-*\- +.EE +.RE +. +. +.IP +in the first line of a file will cause Emacs to enter the +.I nroff +major mode when it is loaded into the buffer. +. +Unfortunately, +some implementations of the +.MR man 1 +program are confused by this practice, +so we discourage it. +. +. +.\" ==================================================================== +.SS "Editing with Vim" +.\" ==================================================================== +. +.\" TODO: elvis, vile. Nvi does not support highlighting at all, and +.\" gedit does but has no rules for roff yet. Other editors TBD. +Other editors provide support for +.IR roff -style +files too, +such as +.MR vim 1 , +an extension of the +.MR vi 1 +program. +. +Vim's highlighting can be made to recognize +.I roff +files by setting the +.B filetype +option in a Vim +.IR modeline . +. +For this feature to work, +your copy of +.I vim +must be built with support for, +and configured to enable, +several features; +consult the editor's online help topics +\[lq]auto\-setting\[rq], +\[lq]filetype\[rq], +and \[lq]syntax\[rq]. +. +Then put the following at the end of your +.I roff +files, +after any Emacs configuration: +.\" ...because Emacs pattern-matches against 3000 bytes from the end of +.\" the buffer [or until hitting a 0x0C (FF, form-feed control)] for +.\" "Local Variables:", but Vim only checks as many lines as its +.\" 'modelines' variable tells it to. A common default is "5", but +.\" Emacs settings can be longer than that. +. +. +.RS +.IP +.EX +\&.\[rs]" vim: set filetype=groff textwidth=72: +.EE +.RE +. +. +.P +Replace \[lq]groff\[rq] in the above with \[lq]nroff\[rq] if you want +highlighting that does +.I not +recognize many of the GNU extensions to +.IR roff , +such as request, +register, +and string names longer than two characters. +. +. +.\" ==================================================================== +.SH Authors +.\" ==================================================================== +. +This document was written by +.MT groff\-bernd\:.warken\-72@\:web\:.de +Bernd Warken +.ME +and +.MT g.branden\:.robinson@\:gmail\:.com +G.\& Branden Robinson +.ME . +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +Much +.I roff +documentation is available. +. +The Bell Labs papers describing AT&T +.I troff +remain available, +and +.I groff +is documented comprehensively. \" ...one hopes. +. +. +.\" ==================================================================== +.SS "Internet sites" +.\" ==================================================================== +. +.P +.UR https://\:github\:.com/\:larrykollar/\:Unix\-Text\-Processing +.I Unix Text Processing +.UE , +by Dale Dougherty and Tim O'Reilly, +1987, +Hayden Books. +. +This well-regarded text brings the reader from a state of no knowledge +of Unix or text editing +(if necessary) +to sophisticated computer-aided typesetting. +. +It has been placed under a free software license by its authors and +updated by a team of +.I groff +contributors and enthusiasts. +. +. +.P +.UR http://\:manpages\:.bsd\:.lv/\:history\:.html +\[lq]History of Unix Manpages\[rq] +.UE , +an online article maintained by the mdocml project, +provides an overview of +.I roff +development from Saltzer's +.I RUNOFF +to 2008, +with links to original documentation and recollections of the authors +and their contemporaries. +. +. +.P +.UR http://\:www\:.troff\:.org/ +troff.org +.UE , +Ralph Corderoy's +.I troff +site, +provides an overview and pointers to much historical +.I roff +information. +. +. +.P +.UR http://\:www\:.multicians\:.org/ +Multicians +.UE , +a site by Multics enthusiasts, +contains a lot of information on the MIT projects CTSS and Multics, +including +.IR RUNOFF ; +it is especially useful for its glossary and the many links to +historical documents. +. +. +.P +.UR http://\:www\:.tuhs\:.org/\:Archive/ +The Unix Archive +.UE , +curated by the Unix Heritage Society, +provides the source code and some binaries of historical Unices +(including the source code of some versions of +.I troff +and its documentation) +contributed by their copyright holders. +. +. +.P +.UR http://\:web\:.mit\:.edu/\:Saltzer/\:www/\:publications/\ +\:pubs\:.html +Jerry Saltzer's home page +.UE +stores some documents using the original +.I RUNOFF +formatting language. +. +. +.P +.UR http://\:www\:.gnu\:.org/\:software/\:groff +.I groff +.UE , +GNU +.IR roff 's +web site, +provides convenient access to +.IR groff 's +source code repository, +bug tracker, +and mailing lists +(including archives and the subscription interface). +. +. +.\" ==================================================================== +.SS "Historical \f[I]roff\f[] documentation" +.\" ==================================================================== +. +Many AT&T +.I troff +documents are available online, +and can be found at Ralph Corderoy's site +(see above) +or via Internet search. +. +. +.P +Of foremost significance are two mentioned in section \[lq]History\[rq] +above, +describing the language and its device-independent implementation, +respectively. +. +. +.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. +. +. +.P +\[lq]A Typesetter-independent TROFF\[rq] +by Brian W.\& Kernighan, +1982, +AT&T Bell Laboratories Computing Science Technical Report No.\& 97. +. +. +.P +You can obtain many relevant Bell Labs papers in PDF from +.UR https://\:github\:.com/\:bwarken/\:roff_classical\:.git +Bernd Warken's +\[lq]roff classical\[rq] +GitHub repository +.UE . +. +. +.\" ==================================================================== +.SS "Manual pages" +.\" ==================================================================== +. +As a system of multiple components, +a +.I roff +system potentially has many man pages, +each describing an aspect of it. +. +Unfortunately, +there is no consistent naming scheme for these pages among the different +.I roff +implementations. +. +. +.P +For GNU +.IR roff , +the +.MR groff @MAN1EXT@ +man page enumerates all man pages distributed with the system, +and individual pages frequently refer to external resources as well as +manuals distributed with +.I groff +on a variety of topics. +. +. +.P +With other +.IR roff s, +you are on your own, +but +.MR troff 1 \" foreign troff +might be a good starting point. +. +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_roff_7_man_C] +.do rr *groff_roff_7_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff textwidth=72: |