diff options
Diffstat (limited to 'contrib/groff/troff/troff.man')
| -rw-r--r-- | contrib/groff/troff/troff.man | 2051 |
1 files changed, 2051 insertions, 0 deletions
diff --git a/contrib/groff/troff/troff.man b/contrib/groff/troff/troff.man new file mode 100644 index 0000000..46bf011 --- /dev/null +++ b/contrib/groff/troff/troff.man @@ -0,0 +1,2051 @@ +.ig \"-*- nroff -*- +Copyright (C) 1989-1995 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be included in +translations approved by the Free Software Foundation instead of in +the original English. +.. +.\" 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 +.de TQ +.br +.ns +.TP \\$1 +.. +.\" Like TP, but if specified indent is more than half +.\" the current line-length - indent, use the default indent. +.de Tp +.ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP +.el .TP "\\$1" +.. +.\" The BSD man macros can't handle " in arguments to font change macros, +.\" so use \(ts instead of ". +.tr \(ts" +.TH @G@TROFF 1 "@MDATE@" "Groff Version @VERSION@" +.SH NAME +@g@troff \- format documents +.SH SYNOPSIS +.nr a \n(.j +.ad l +.nr i \n(.i +.in +\w'\fB@g@troff 'u +.ti \niu +.B @g@troff +.de OP +.ie \\n(.$-1 .RI "[\ \fB\\$1\fP" "\\$2" "\ ]" +.el .RB "[\ " "\\$1" "\ ]" +.. +.OP \-abivzCER +.OP \-w name +.OP \-W name +.OP \-d cs +.OP \-f fam +.OP \-m name +.OP \-n num +.OP \-o list +.OP \-r cn +.OP \-T name +.OP \-F dir +.OP \-M dir +.RI "[\ " files\|.\|.\|. "\ ]" +.br +.ad \na +.SH DESCRIPTION +This manual page describes the GNU version of +.BR troff , +which is part of the groff document formatting system. +It is highly compatible with Unix troff. +Usually it should be invoked using the groff command, which will +also run preprocessors and postprocessors in the appropriate +order and with the appropriate options. +.SH OPTIONS +.TP \w'\-dname=s'u+2n +.B \-a +Generate an +.SM ASCII +approximation of the typeset output. +.TP +.B \-b +Print a backtrace with each warning or error message. This backtrace +should help track down the cause of the error. The line numbers given +in the backtrace may not always correct: troff's idea of line numbers +gets confused by +.B as +or +.B am +requests. +.TP +.B \-i +Read the standard input after all the named input files have been +processed. +.TP +.B \-v +Print the version number. +.TP +.BI \-w name +Enable warning +.IR name . +Available warnings are described in +the Warnings subsection below. +Multiple +.B \-w +options are allowed. +.TP +.BI \-W name +Inhibit warning +.IR name . +Multiple +.B \-W +options are allowed. +.TP +.B \-E +Inhibit all error messages. +.TP +.B \-z +Suppress formatted output. +.TP +.B \-C +Enable compatibility mode. +.TP +.BI \-d cs +.TQ +.BI \-d name = s +Define +.I c +or +.I name +to be a string +.IR s ; +.I c +must be a one letter name. +.TP +.BI \-f fam +Use +.I fam +as the default font family. +.TP +.BI \-m name +Read in the file +.BI tmac. name\fR. +Normally this will be searched for in @MACRODIR@. +.TP +.B \-R +Don't load +.BR troffrc . +.TP +.BI \-n num +Number the first page +.IR num . +.TP +.BI \-o list +Output only pages in +.IR list , +which is a comma-separated list of page ranges; +.I n +means print page +.IR n , +.IB m \- n +means print every page between +.I m +and +.IR n , +.BI \- n +means print every page up to +.IR n , +.IB n \- +means print every page from +.IR n . +.B Troff +will exit after printing the last page in the list. +.TP +.BI \-r cn +.TQ +.BI \-r name = n +Set number register +.I c +or +.I name +to +.IR n ; +.I c +must be a one character name; +.I n +can be any troff numeric expression. +.TP +.BI \-T name +Prepare output for device +.IR name , +rather than the default +.BR @DEVICE@ . +.TP +.BI \-F dir +Search +.I dir +for subdirectories +.BI dev name +.RI ( name +is the name of the device) +for the +.B DESC +file and font files before the normal +.BR @FONTDIR@ . +.TP +.BI \-M dir +Search directory +.I dir +for macro files before the normal +.BR @MACRODIR@ . +.SH USAGE +Only the features not in Unix troff are described here. +.SS Long names +The names of number registers, fonts, strings/macros/diversions, +special characters can be of any length. In escape sequences, where +you can use +.BI ( xx +for a two character name, you can use +.BI [ xxx ] +for a name of arbitrary length: +.TP +.BI \e[ xxx ] +Print the special character called +.IR xxx . +.TP +.BI \ef[ xxx ] +Set font +.IR xxx . +.TP +.BI \e*[ xxx ] +Interpolate string +.IR xxx . +.TP +.BI \en[ xxx ] +Interpolate number register +.IR xxx . +.SS Fractional pointsizes +A +.I +scaled point +is equal to 1/sizescale +points, where +sizescale is specified in the +.B DESC +file (1 by default.) +There is a new scale indicator +.B z +which has the effect of multiplying by sizescale. +Requests and escape sequences in troff +interpret arguments that represent a pointsize as being in units +of scaled points, but they evaluate each such argument +using a default scale indicator of +.BR z . +Arguments treated in this way are +the argument to the +.B ps +request, +the third argument to the +.B cs +request, +the second and fourth arguments to the +.B tkf +request, +the argument to the +.B \eH +escape sequence, +and those variants of the +.B \es +escape sequence that take a numeric expression as their argument. +.LP +For example, suppose sizescale is 1000; +then a scaled point will be equivalent to a millipoint; +the request +.B .ps 10.25 +is equivalent to +.B .ps 10.25z +and so sets the pointsize to 10250 scaled points, +which is equal to 10.25 points. +.LP +The number register +.B \en(.s +returns the pointsize in points as decimal fraction. +There is also a new number register +.B \en[.ps] +that returns the pointsize in scaled points. +.LP +It would make no sense to use the +.B z +scale indicator in a numeric expression +whose default scale indicator was neither +.B u +nor +.BR z , +and so +.B troff +disallows this. +Similarly it would make no sense to use a scaling indicator +other than +.B z +or +.B u +in a numeric expression whose default scale indicator was +.BR z , +and so +.B troff +disallows this as well. +.LP +There is also new scale indicator +.B s +which multiplies by the number of units in a scaled point. +So, for example, +.B \en[.ps]s +is equal to +.BR 1m . +Be sure not to confuse the +.B s +and +.B z +scale indicators. +.SS Numeric expressions +.LP +Spaces are permitted in a number expression within parentheses. +.LP +.B M +indicates a scale of 100ths of an em. +.TP +.IB e1 >? e2 +The maximum of +.I e1 +and +.IR e2 . +.TP +.IB e1 <? e2 +The minimum of +.I e1 +and +.IR e2 . +.TP +.BI ( c ; e ) +Evaluate +.I e +using +.I c +as the default scaling indicator. +If +.I c +is missing, ignore scaling indicators in the evaluation of +.IR e . +.SS New escape sequences +.TP +.BI \eA' anything ' +This expands to +.B 1 +or +.B 0 +according as +.I anything +is or is not acceptable as the name of a string, macro, diversion, +number register, environment or font. +It will return +.B 0 +if +.I anything +is empty. +This is useful if you want to lookup user input in some sort of +associative table. +.TP +.BI \eC' xxx ' +Typeset character named +.IR xxx . +Normally it is more convenient to use +.BI \e[ xxx ]\fR. +But +.B \eC +has the advantage that it is compatible with recent versions of +.SM UNIX +and is available in compatibility mode. +.TP +.B \eE +This is equivalent to an escape character, +but it's not interpreted in copy-mode. +For example, strings to start and end superscripting could be defined +like this: +.RS +.IP +\&.ds { \ev'\-.3m'\es'\eEn[.s]*6u/10u' +.br +\&.ds } \es0\ev'.3m' +.LP +The use of +.B \eE +ensures that these definitions will work even if +.B \e*{ +gets interpreted in copy-mode +(for example, by being used in a macro argument.) +.RE +.TP +.BI \eN' n ' +Typeset the character with code +.I n +in the current font. +.I n +can be any integer. +Most devices only have characters with codes between 0 and 255. +If the current font does not contain a character with that code, +special fonts will +.I not +be searched. +The +.B \eN +escape sequence can be conveniently used on conjunction with the +.B char +request: +.RS +.IP +.B +\&.char \e[phone] \ef(ZD\eN'37' +.RE +.IP +The code of each character is given in the fourth column in the font +description file after the +.B charset +command. +It is possible to include unnamed characters in the font description +file by using a name of +.BR \-\-\- ; +the +.B \eN +escape sequence is the only way to use these. +.TP +.BI \eR' name\ \(+-n ' +This has the same effect as +.RS +.IP +.BI .nr\ name\ \(+-n +.RE +.TP +.BI \es( nn +.TQ +.BI \es\(+-( nn +Set the point size to +.I nn +points; +.I nn +must be exactly two digits. +.TP +.BI \es[\(+- n ] +.TQ +.BI \es\(+-[ n ] +.TQ +.BI \es'\(+- n ' +.TQ +.BI \es\(+-' n ' +Set the point size to +.I n +scaled points; +.I n +is a numeric expression with a default scale indicator of +.BR z . +.TP +.BI \eV x +.TQ +.BI \eV( xx +.TQ +.BI \eV[ xxx ] +Interpolate the contents of the environment variable +.I xxx , +as returned by +.BR getenv (3). +.B \eV +is interpreted in copy-mode. +.TP +.BI \eY x +.TQ +.BI \eY( xx +.TQ +.BI \eY[ xxx ] +This is approximately equivalent to +.BI \eX'\e*[ xxx ]'\fR. +However the contents of the string or macro +.I xxx +are not interpreted; +also it is permitted for +.I xxx +to have been defined as a macro and thus contain newlines +(it is not permitted for the argument to +.B \eX +to contain newlines). +The inclusion of newlines requires an extension to the Unix troff output +format, and will confuse drivers that do not know about this +extension. +.TP +.BI \eZ' anything ' +Print anything and then restore the horizontal and vertical +position; +.I anything +may not contain tabs or leaders. +.TP +.B \e$0 +The name by which the current macro was invoked. +The +.B als +request can make a macro have more than one name. +.TP +.B \e$* +In a macro, the concatenation of all the arguments separated by spaces. +.TP +.B \e$@ +In a macro, the concatenation of all the arguments with each surrounded by +double quotes, and separated by spaces. +.TP +.BI \e$( nn +.TQ +.BI \e$[ nnn ] +In a macro, this gives the +.IR nn -th +or +.IR nnn -th +argument. +Macros can have a unlimited number of arguments. +.TP +.BI \e? anything \e? +When used in a diversion, this will transparently embed +.I anything +in the diversion. +.I anything +is read in copy mode. +When the diversion is reread, +.I anything +will be interpreted. +.I anything +may not contain newlines; use +.B \e! +if you want to embed newlines in a diversion. +The escape sequence +.B \e? +is also recognised in copy mode and turned into a single internal +code; it is this code that terminates +.IR anything . +Thus +.RS +.RS +.ft B +.nf +.ne 15 +\&.nr x 1 +\&.nf +\&.di d +\e?\e\e?\e\e\e\e?\e\e\e\e\e\e\e\enx\e\e\e\e?\e\e?\e? +\&.di +\&.nr x 2 +\&.di e +\&.d +\&.di +\&.nr x 3 +\&.di f +\&.e +\&.di +\&.nr x 4 +\&.f +.fi +.ft +.RE +.RE +.IP +will print +.BR 4 . +.TP +.B \e/ +This increases the width of the preceding character so that +the spacing between that character and the following character +will be correct if the following character is a roman character. +For example, if an italic f is immediately followed by a roman +right parenthesis, then in many fonts the top right portion of the f +will overlap the top left of the right parenthesis producing \fIf\fR)\fR, +which is ugly. +Inserting +.B \e/ +produces +.ie \n(.g \fIf\/\fR)\fR +.el \fIf\|\fR)\fR +and avoids this problem. +It is a good idea to use this escape sequence whenever an +italic character is immediately followed by a roman character without any +intervening space. +.TP +.B \e, +This modifies the spacing of the following character so that the spacing +between that character and the preceding character will correct if +the preceding character is a roman character. +For example, inserting +.B \e, +between the parenthesis and the f changes +\fR(\fIf\fR to +.ie \n(.g \fR(\,\fIf\fR. +.el \fR(\^\fIf\fR. +It is a good idea to use this escape sequence whenever a +roman character is immediately followed by an italic character without any +intervening space. +.TP +.B \e) +Like +.B \e& +except that it behaves like a character declared with the +.B cflags +request to be transparent for the purposes of end of sentence recognition. +.TP +.B \e~ +This produces an unbreakable space that stretches like a normal inter-word +space when a line is adjusted. +.TP +.B \e# +Everything up to and including the next newline is ignored. +This is interpreted in copy mode. +This is like +.B \e" +except that +.B \e" +does not ignore the terminating newline. +.SS New requests +.TP +.BI .aln\ xx\ yy +Create an alias +.I xx +for number register object named +.IR yy . +The new name and the old name will be exactly equivalent. +If +.I yy +is undefined, a warning of type +.B reg +will be generated, and the request will be ignored. +.TP +.BI .als\ xx\ yy +Create an alias +.I xx +for request, string, macro, or diversion object named +.IR yy . +The new name and the old name will be exactly equivalent (it is similar to a +hard rather than a soft link). +If +.I yy +is undefined, a warning of type +.B mac +will be generated, and the request will be ignored. +The +.BR de , +.BR am , +.BR di , +.BR da , +.BR ds , +and +.B as +requests only create a new object if the name of the macro, diversion +or string diversion is currently undefined or if it is defined to be a +request; normally they modify the value of an existing object. +.TP +.BI .asciify\ xx +This request only exists in order to make it possible +to make certain gross hacks work with GNU troff. +It `unformats' the diversion +.I xx +in such a way that +.SM ASCII +characters that were formatted and diverted into +.I xx +will be treated like ordinary input characters when +.I xx +is reread. +For example, this +.RS +.IP +.ne 7v+\n(.Vu +.ft B +.nf +.ss 24 +\&.tr @. +\&.di x +\&@nr\e n\e 1 +\&.br +\&.di +\&.tr @@ +\&.asciify x +\&.x +.ss 12 +.fi +.RE +.IP +will set register +.B n +to 1. +.TP +.B .backtrace +Print a backtrace of the input stack on stderr. +.TP +.BI .blm\ xx +Set the blank line macro to +.IR xx . +If there is a blank line macro, +it will be invoked when a blank line is encountered instead of the usual +troff behaviour. +.TP +.B .break +Break out of a while loop. +See also the +.B while +and +.B continue +requests. +Be sure not to confuse this with the +.B br +request. +.TP +.BI .cflags\ n\ c1\ c2\|.\|.\|. +Characters +.IR c1 , +.IR c2 ,\|.\|.\|. +have properties determined by +.IR n , +which is ORed from the following: +.RS +.TP +1 +the character ends sentences +(initially characters +.B .?! +have this property); +.TP +2 +lines can be broken before the character +(initially no characters have this property); +a line will not be broken at a character with this property +unless the characters on each side both have non-zero +hyphenation codes. +.TP +4 +lines can be broken after the character +(initially characters +.B \-\e(hy\e(em +have this property); +a line will not be broken at a character with this property +unless the characters on each side both have non-zero +hyphenation codes. +.TP +8 +the character overlaps horizontally +(initially characters +.B \e(ul\e(rn\e(ru +have this property); +.TP +16 +the character overlaps vertically +(initially character +.B \e(br +has this property); +.TP +32 +an end of sentence character followed by any number of characters +with this property will be treated +as the end of a sentence if followed by a newline or two spaces; +in other words +the character is transparent for the purposes of end of sentence +recognition; +this is the same as having a zero space factor in \*(tx +(initially characters +.B \(ts')]*\e(dg\e(rq +have this property). +.RE +.TP +.BI .char\ c\ string +Define character +.I c +to be +.IR string . +Every time character +.I c +needs to be printed, +.I string +will be processed in a temporary environment and the result +will be wrapped up into a single object. +Compatibility mode will be turned off +and the escape character will be set to +.B \e +while +.I string +is being processed. +Any emboldening, constant spacing or track kerning will be applied +to this object rather than to individual characters in +.IR string . +A character defined by this request can be used just like +a normal character provided by the output device. +In particular other characters can be translated to it +with the +.B tr +request; +it can be made the leader character by the +.B lc +request; +repeated patterns can be drawn with the character using the +.B \el +and +.B \eL +escape sequences; +words containing the character can be hyphenated +correctly, if the +.B hcode +request is used to give the character a hyphenation code. +There is a special anti-recursion feature: +use of character within the character's definition +will be handled like normal characters not defined with +.BR char . +A character definition can be removed with the +.B rchar +request. +.TP +.BI .chop\ xx +Chop the last character off macro, string, or diversion +.IR xx . +This is useful for removing the newline from the end of diversions +that are to be interpolated as strings. +.TP +.BI .close\ stream +Close the stream named +.IR stream ; +.I stream +will no longer be an acceptable argument to the +.B write +request. +See the +.B open +request. +.TP +.B .continue +Finish the current iteration of a while loop. +See also the +.B while +and +.B break +requests. +.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 recognised, and the +incompatibilities caused by long names do not arise. +.TP +.BI .do\ xxx +Interpret +.I .xxx +with compatibility mode disabled. +For example, +.RS +.IP +.B +\&.do fam T +.LP +would have the same effect as +.IP +.B +\&.fam T +.LP +except that it would work even if compatibility mode had been enabled. +Note that the previous compatibility mode is restored before any files +sourced by +.I xxx +are interpreted. +.RE +.TP +.BI .fam\ xx +Set the current font family to +.IR xx . +The current font family is part of the current environment. +See the description of the +.B sty +request for more information on font families. +.TP +.BI .fspecial\ f\ s1\ s2\|.\|.\|. +When the current font is +.IR f , +fonts +.IR s1 , +.IR s2 ,\|.\|.\|. +will be special, that is, they will searched for characters not in +the current font. +Any fonts specified in the +.B special +request will be searched after fonts specified in the +.B fspecial +request. +.TP +.BI .ftr\ f\ g +Translate font +.I f +to +.IR g . +Whenever a font named +.I f +is referred to in +.B \ef +escape sequence, +or in the +.BR ft , +.BR ul , +.BR bd , +.BR cs , +.BR tkf , +.BR special , +.BR fspecial , +.BR fp , +or +.BR sty +requests, +font +.I g +will be used. +If +.I g +is missing, +or equal to +.I f +then font +.I f +will not be translated. +.TP +.BI .hcode \ c1\ code1\ c2\ code2\|.\|.\|. +Set the hyphenation code of character +.I c1 +to +.I code1 +and that of +.I c2 +to +.IR code2 . +A hyphenation code must be a single input +character (not a special character) other than a digit or a space. +Initially each lower-case letter has a hyphenation code, which +is itself, and each upper-case letter has a hyphenation code +which is the lower case version of itself. +See also the +.B hpf +request. +.TP +.BI .hla\ lang +Set the current hyphenation language to +.IR lang . +Hyphenation exceptions specified with the +.B hw +request and hyphenation patterns specified with the +.B hpf +request are both associated with the current hyphenation language. +The +.B hla +request is usually invoked by the +.B troffrc +file. +.TP +.BI .hlm\ n +Set the maximum number of consecutive hyphenated lines to +.IR n . +If +.I n +is negative, there is no maximum. +The default value is \-1. +This value is associated with the current environment. +Only lines output from an environment count towards the maximum associated +with that environment. +Hyphens resulting from +.B \e% +are counted; explicit hyphens are not. +.TP +.BI .hpf\ file +Read hyphenation patterns from +.IR file ; +this will be searched for in the same way that +.BI tmac. name +is searched for when the +.BI \-m name +option is specified. +It should have the same format as the argument to +the \epatterns primitive in \*(tx; +the letters appearing in this file are interpreted as hyphenation +codes. +A +.B % +character in the patterns file introduces a comment that continues +to the end of the line. +The set of hyphenation patterns is associated with the current language +set by the +.B hla +request. +The +.B hpf +request +is usually invoked by the +.B troffrc +file. +.TP +.BI .hym\ n +Set the +.I hyphenation margin +to +.IR n : +when the current adjustment mode is not +.BR b , +the line will not be hyphenated if the line is no more than +.I n +short. +The default hyphenation margin is 0. +The default scaling indicator for this request is +.IR m . +The hyphenation margin is associated with the current environment. +The current hyphenation margin is available in the +.B \en[.hym] +register. +.TP +.BI .hys\ n +Set the +.I hyphenation space +to +.IR n : +when the current adjustment mode is +.B b +don't hyphenate the line if the line can be justified by adding no more than +.I n +extra space to each word space. +The default hyphenation space is 0. +The default scaling indicator for this request is +.BR m . +The hyphenation space is associated with the current environment. +The current hyphenation space is available in the +.B \en[.hys] +register. +.TP +.BI .kern\ n +If +.I n +is non-zero or missing, enable pairwise kerning, otherwise disable it. +.TP +.BI .mso\ file +The same as the +.B so +request except that +.I file +is searched for in the same way that +.BI tmac. name +is searched for when the +.BI \-m name +option is specified. +.TP +.B .nroff +Make the +.B n +built-in condition true +and the +.B t +built-in condition false. +This can be reversed using the +.B troff +request. +.TP +.BI .open\ stream\ filename +Open +.I filename +for writing and associate the stream named +.I stream +with it. +See also the +.B close +and +.B write +requests. +.TP +.BI .opena\ stream\ filename +Like +.BR open , +but if +.I filename +exists, append to it instead of truncating it. +.TP +.B .pnr +Print the names and contents of all currently defined number registers +on stderr. +.TP +.BI .pso \ command +This is behaves like the +.B so +request except that input comes from the standard output of +.IR command . +.TP +.B .ptr +Print the names and positions of all traps (not including input line +traps and diversion traps) on stderr. Empty slots in the page trap +list are printed as well, because they can affect the priority of +subsequently planted traps. +.TP +.BI .rchar\ c1\ c2\|.\|.\|. +Remove the definitions of characters +.IR c1 , +.IR c2 ,\|.\|.\|. +This undoes the effect of a +.B char +request. +.TP +.B .rj +.TQ +.BI .rj\ n +Right justify the next +.I n +input lines. +Without an argument right justify the next input line. +The number of lines to be right justified is available in the +.B \en[.rj] +register. +This implicitly does +.BR .ce\ 0 . +The +.B ce +request implicitly does +.BR .rj\ 0 . +.TP +.BI .rnn \ xx\ yy +Rename number register +.I xx +to +.IR yy . +.TP +.BI .shc\ c +Set the soft hyphen character to +.IR c . +If +.I c +is omitted, +the soft hyphen character will be set to the default +.BR \e(hy . +The soft hyphen character is the character which will be inserted +when a word is hyphenated at a line break. +If the soft hyphen character does not exist in the font of the character +immediately preceding a potential break point, +then the line will not be broken at that point. +Neither definitions (specified with the +.B char +request) +nor translations (specified with the +.B tr +request) +are considered when finding the soft hyphen character. +.TP +.BI .shift\ n +In a macro, shift the arguments by +.I n +positions: +argument +.I i +becomes argument +.IR i \- n ; +arguments 1 to +.I n +will no longer be available. +If +.I n +is missing, +arguments will be shifted by 1. +Shifting by negative amounts is currently undefined. +.TP +.BI .special\ s1\ s2\|.\|.\|. +Fonts +.IR s1 , +.IR s2 , +are special and will be searched for characters not in the +current font. +.TP +.BI .sty\ n\ f +Associate style +.I f +with font position +.IR n . +A font position can be associated either with a font or +with a style. +The current font is the index of a font position and so is also +either a font or a style. +When it is a style, the font that is actually used is the font the +name of which is the concatenation of the name of the current family +and the name of the current style. +For example, if the current font is 1 and font position 1 is +associated with style +.B R +and the current +font family is +.BR T , +then font +.BR TR +will be used. +If the current font is not a style, then the current family is ignored. +When the requests +.BR cs , +.BR bd , +.BR tkf , +.BR uf , +or +.B fspecial +are applied to a style, +then they will instead be applied to the member of the +current family corresponding to that style. +The default family can be set with the +.B \-f +option. +The styles command in the +.SM DESC +file controls which font positions +(if any) are initially associated with styles rather than fonts. +.TP +.BI .tkf\ f\ s1\ n1\ s2\ n2 +Enable track kerning for font +.IR f . +When the current font is +.I f +the width of every character will be increased by an amount +between +.I n1 +and +.IR n2 ; +when the current point size is less than or equal to +.I s1 +the width will be increased by +.IR n1 ; +when it is greater than or equal to +.I s2 +the width will be increased by +.IR n2 ; +when the point 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 point size. +.TP +.BI .trf\ filename +Transparently output the contents of file +.IR filename . +Each line is output as it would be were it preceded by +.BR \e! ; +however, the lines are not subject to copy-mode interpretation. +If the file does not end with a newline, then a newline will +be added. +For example, you can define a macro +.I x +containing the contents of file +.IR f , +using +.RS +.IP +.BI .di\ x +.br +.BI .trf\ f +.br +.B .di +.LP +Unlike with the +.B cf +request, +the file cannot contain characters such as +.SM NUL +that are not legal troff input characters. +.RE +.TP +.B .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 \e! . +For example, +.RS +.LP +.nf +.ft B +\&.tr ab +\&.di x +\e!.tm a +\&.di +\&.x +.fi +.ft +.LP +will print +.BR b ; +if +.B trnt +is used instead of +.B tr +it will print +.BR a . +.RE +.TP +.B .troff +Make the +.B n +built-in condition false, +and the +.B t +built-in condition true. +This undoes the effect of the +.B nroff +request. +.TP +.BI .vpt\ n +Enable vertical position traps if +.I n +is non-zero, disable them otherwise. +Vertical position traps are traps set by the +.B wh +or +.B dt +requests. +Traps set by the +.B it +request are not vertical position traps. +The parameter that controls whether vertical position traps are enabled +is global. +Initially vertical position traps are enabled. +.TP +.BI .warn\ n +Control warnings. +.I n +is the sum of the numbers associated with each warning that is to be enabled; +all other warnings will be disabled. +The number associated with each warning is listed in the `Warnings' section. +For example, +.B .warn 0 +will disable all warnings, and +.B .warn 1 +will disable all warnings except that about missing characters. +If +.I n +is not given, +all warnings will be enabled. +.TP +.BI .while \ c\ anything +While condition +.I c +is true, accept +.I anything +as input; +.I c +can be any condition acceptable to an +.B if +request; +.I anything +can comprise multiple lines if the first line starts with +.B \e{ +and the last line ends with +.BR \e} . +See also the +.B break +and +.B continue +requests. +.TP +.BI .write\ stream\ anything +Write +.I anything +to the stream named +.IR stream . +.I stream +must previously have been the subject of an +.B open +request. +.I anything +is read in copy mode; +a leading +.B \(ts +will be stripped. +.SS Extended requests +.TP +.BI .cf\ filename +When used in a diversion, this will embed in the diversion an object which, +when reread, will cause the contents of +.I filename +to be transparently copied through to the output. +In Unix troff, the +contents of +.I filename +is immediately copied through to the output regardless of whether +there is a current diversion; this behaviour is so anomalous that it +must be considered a bug. +.TP +.BI .ev\ xx +If +.I xx +is not a number, this will switch to a named environment called +.IR xx . +The environment should be popped with a matching +.B ev +request without any arguments, just as for numbered environments. +There is no limit on the number of named environments; they will be +created the first time that they are referenced. +.TP +.BI .fp\ n\ f1\ f2 +The +.B fp +request has an optional third argument. +This argument gives the external name of the font, +which is used for finding the font description file. +The second argument gives the internal name of the font +which is used to refer to the font in troff after it has been mounted. +If there is no third argument then the internal name will be used +as the external name. +This feature allows you to use fonts with long names in compatibility mode. +.TP +.BI .ss\ m\ n +When two arguments are given to the +.B ss +request, the second argument gives the +.IR "sentence space size" . +If the second argument is not given, the sentence space size +will be the same as the word space size. +Like the word space size, the sentence space is in units of +one twelfth of the spacewidth parameter for the current font. +Initially both the word space size and the sentence +space size are 12. +The sentence space size is used in two circumstances: +if the end of a sentence occurs at the end of a line in fill mode, then +both an inter-word space and a sentence space will be added; +if two spaces follow the end of a sentence in the middle of a line, +then the second space will be a sentence space. +Note that the behaviour of Unix troff will be exactly +that exhibited by GNU troff if a second argument is never given to the +.B ss +request. +In GNU troff, as in Unix troff, you should always +follow a sentence with either a newline or two spaces. +.TP +.BI .ta\ n1\ n2\|.\|.\|.nn \ T\ r1\ r2\|.\|.\|.\|rn +Set tabs at positions +.IR n1 , +.IR n2 ,\|.\|.\|.\|, +.I nn +and then set tabs at +.IR nn + r1 , +.IR nn + r2 ,\|.\|.\|.\|.\|, +.IR nn + rn +and then at +.IR nn + rn + r1 , +.IR nn + rn + r2 ,\|.\|.\|.\|, +.IR nn + rn + rn , +and so on. +For example, +.RS +.IP +.B +\&.ta T .5i +.LP +will set tabs every half an inch. +.RE +.SS New number registers +The following read-only registers are available: +.TP +.B \en[.C] +1 if compatibility mode is in effect, 0 otherwise. +.TP +.B \en[.cdp] +The depth of the last character added to the current environment. +It is positive if the character extends below the baseline. +.TP +.B \en[.ce] +The number of lines remaining to be centered, as set by the +.B ce +request. +.TP +.B \en[.cht] +The height of the last character added to the current environment. +It is positive if the character extends above the baseline. +.TP +.B \en[.csk] +The skew of the last character added to the current environment. +The +.I skew +of a character is how far to the right of the center of a character +the center of an accent over that character should be placed. +.TP +.B \en[.ev] +The name or number of the current environment. +This is a string-valued register. +.TP +.B \en[.fam] +The current font family. +This is a string-valued register. +.TP +.B \en[.fp] +The number of the next free font position. +.TP +.B \en[.g] +Always 1. +Macros should use this to determine whether they are running +under GNU troff. +.TP +.B \en[.hla] +The current hyphenation language as set by the +.B hla +request. +.TP +.B \en[.hlc] +The number of immediately preceding consecutive hyphenated lines. +.TP +.B \en[.hlm] +The maximum allowed number of consecutive hyphenated lines, as set by the +.B hlm +request. +.TP +.B \en[.hy] +The current hyphenation flags (as set by the +.B hy +request.) +.TP +.B \en[.hym] +The current hyphenation margin (as set by the +.B hym +request.) +.TP +.B \en[.hys] +The current hyphenation space (as set by the +.B hys +request.) +.TP +.B \en[.in] +The indent that applies to the current output line. +.TP +.B \en[.kern] +.B 1 +if pairwise kerning is enabled, +.B 0 +otherwise. +.TP +.B \en[.lg] +The current ligature mode (as set by the +.B lg +request.) +.TP +.B \en[.ll] +The line length that applies to the current output line. +.TP +.B \en[.lt] +The title length as set by the +.B lt +request. +.TP +.B \en[.ne] +The amount of space that was needed in the last +.B ne +request that caused a trap to be sprung. +Useful in conjunction with the +.B \en[.trunc] +register. +.TP +.B \en[.pn] +The number of the next page: +either the value set by a +.B pn +request, or the number of the current page plus 1. +.TP +.B \en[.ps] +The current pointsize in scaled points. +.TP +.B \en[.psr] +The last-requested pointsize in scaled points. +.TP +.B \en[.rj] +The number of lines to be right-justified as set by the +.B rj +request. +.TP +.B \en[.sr] +The last requested pointsize in points as a decimal fraction. +This is a string-valued register. +.TP +.B \en[.tabs] +A string representation of the current tab settings suitable for use as +an argument to the +.B ta +request. +.TP +.B \en[.trunc] +The amount of vertical space truncated by the most recently sprung +vertical position trap, or, +if the trap was sprung by a +.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, it represents the difference +of what the vertical position would have been but for the trap, +and what the vertical position actually is. +Useful in conjunction with the +.B \en[.ne] +register. +.TP +.B \en[.ss] +.TQ +.B \en[.sss] +These give the values of the parameters set by the +first and second arguments of the +.B ss +request. +.TP +.B \en[.vpt] +1 if vertical position traps are enabled, 0 otherwise. +.TP +.B \en[.warn] +The sum of the numbers associated with each of the currently enabled +warnings. +The number associated with each warning is listed in the `Warnings' +subsection. +.TP +.B \en(.x +The major version number. +For example, if the version number is +.B 1.03 +then +.B \en(.x +will contain +.BR 1 . +.TP +.B \en(.y +The minor version number. +For example, if the version number is +.B 1.03 +then +.B \en(.y +will contain +.BR 03 . +.LP +The following registers are set by the +.B \ew +escape sequence: +.TP +.B \en[rst] +.TQ +.B \en[rsb] +Like the +.B st +and +.B sb +registers, but takes account of the heights and depths of characters. +.TP +.B \en[ssc] +The amount of horizontal space (possibly negative) that should +be added to the last character before a subscript. +.TP +.B \en[skw] +How far to right of the center of the last character +in the +.B \ew +argument, +the center of an accent from a roman font should be placed over that character. +.LP +The following read/write number registers are available: +.TP +.B \en[systat] +The return value of the system() function executed by the last +.B sy +request. +.TP +.B \en[slimit] +If greater than 0, the maximum number of objects on the input stack. +If less than or equal to 0, there is no limit on the number of objects +on the input stack. With no limit, recursion can continue until +virtual memory is exhausted. +.SS Miscellaneous +.LP +Fonts not listed in the +.SM DESC +file are automatically mounted on the next available font position +when they are referenced. +If a font is to be mounted explicitly with the +.B fp +request on an unused font position, +it should be mounted on the first unused font position, +which can be found in the +.B \en[.fp] +register; +although +.B troff +does not enforce this strictly, +it will not allow a font to be mounted at a position whose number is much +greater than that of any currently used position. +.LP +Interpolating a string does not hide existing macro arguments. +Thus in a macro, a more efficient way of doing +.IP +.BI . xx\ \e\e$@ +.LP +is +.IP +.BI \e\e*[ xx ]\e\e +.LP +If the font description file contains pairwise kerning information, +characters from that font will be kerned. +Kerning between two characters can be inhibited by placing a +.B \e& +between them. +.LP +In a string comparison in a condition, +characters that appear at different input levels +to the first delimiter character will not be recognised +as the second or third delimiters. +This applies also to the +.B tl +request. +In a +.B \ew +escape sequence, +a character that appears at a different input level to +the starting delimiter character will not be recognised +as the closing delimiter character. +When decoding a macro argument that is delimited +by double quotes, a character that appears at a different +input level to the starting delimiter character will not +be recognised as the closing delimiter character. +The implementation of +.B \e$@ +ensures that the double quotes surrounding an argument +will appear the same input level, which will be different +to the input level of the argument itself. +In a long escape name +.B ] +will not be recognized as a closing delimiter except +when it occurs at the same input level as the opening +.BR ] . +In compatibility mode, no attention is paid to the input-level. +.LP +There are some new types of condition: +.TP +.BI .if\ r xxx +True if there is a number register named +.IR xxx . +.TP +.BI .if\ d xxx +True if there is a string, macro, diversion, or request named +.IR xxx . +.TP +.BI .if\ c ch +True if there is a character +.IR ch +available; +.I ch +is either an +.SM ASCII +character +or a special character +.BI \e( xx +or +.BI \e[ xxx ]\fR; +the condition will also be true if +.I ch +has been defined by the +.B char +request. +.SS Warnings +The warnings that can be given by +.B troff +are divided into the following categories. +The name associated with each warning is used by the +.B \-w +and +.B \-W +options; +the number is used by the +.B warn +request, and by the +.B .warn +register. +.nr x \w'\fBright-brace'+1n+\w'0000'u +.ta \nxuR +.TP \nxu+3n +.BR char \t1 +Non-existent characters. +This is enabled by default. +.TP +.BR number \t2 +Invalid numeric expressions. +This is enabled by default. +.TP +.BR break \t4 +In fill mode, lines which could not be broken so that their length was +less than the line length. +This is enabled by default. +.TP +.BR delim \t8 +Missing or mismatched closing delimiters. +.TP +.BR el \t16 +Use of the +.B el +request with no matching +.B ie +request. +.TP +.BR scale \t32 +Meaningless scaling indicators. +.TP +.BR range \t64 +Out of range arguments. +.TP +.BR syntax \t128 +Dubious syntax in numeric expressions. +.TP +.BR di \t256 +Use of +.B di +or +.B da +without an argument when there is no current diversion. +.TP +.BR mac \t512 +Use of undefined strings, macros and diversions. +When an undefined string, macro or diversion is used, +that string is automatically defined as empty. +So, in most cases, at most one warning will be given for +each name. +.TP +.BR reg \t1024 +Use of undefined number registers. +When an undefined number register is used, +that register is automatically defined to have a value of 0. +a definition is automatically made with a value of 0. +So, in most cases, at most one warning will be given for +use of a particular name. +.TP +.BR tab \t2048 +Inappropriate use of a tab character. +Either use of a tab character where a number was expected, +or use of tab character in an unquoted macro argument. +.TP +.BR right-brace \t4096 +Use of +.B \e} +where a number was expected. +.TP +.BR missing \t8192 +Requests that are missing non-optional arguments. +.TP +.BR input \t16384 +Illegal input characters. +.TP +.BR escape \t32768 +Unrecognized escape sequences. +When an unrecognized escape sequence is encountered, +the escape character is ignored. +.TP +.BR space \t65536 +Missing space between a request or macro and its argument. +This warning will be given +when an undefined name longer than two characters is encountered, +and the first two characters of the name make a defined name. +The request or macro will not be invoked. +When this warning is given, no macro is automatically defined. +This is enabled by default. +This warning will never occur in compatibility mode. +.TP +.BR font \t131072 +Non-existent fonts. +This is enabled by default. +.TP +.BR ig \t262144 +Illegal escapes in text ignored with the +.B ig +request. +These are conditions that are errors when they do not occur +in ignored text. +.LP +There are also names that can be used to refer to groups of warnings: +.TP +.B all +All warnings except +.BR di , +.B mac +and +.BR reg . +It is intended that this covers all warnings +that are useful with traditional macro packages. +.TP +.B w +All warnings. +.SS Incompatibilities +.LP +Long names cause some incompatibilities. +Unix troff will interpret +.IP +.B +\&.dsabcd +.LP +as defining a string +.B ab +with contents +.BR cd . +Normally, GNU troff will interpret this as a call of a macro named +.BR dsabcd . +Also Unix troff will interpret +.B \e*[ +or +.B \en[ +as references to a string or number register called +.BR [ . +In GNU troff, however, this will normally be interpreted as the start +of a long name. +In +.I compatibility mode +GNU troff will interpret these things in the traditional way. +In compatibility mode, however, long names are not recognised. +Compatibility mode can be turned on with the +.B \-C +command line option, and turned on or off with the +.B cp +request. +The number register +.B \en(.C +is 1 if compatibility mode is on, 0 otherwise. +.LP +GNU troff +does not allow the use of the escape sequences +.BR \\e\e|\e^\e&\e}\e{\e (space) \e'\e`\e-\e_\e!\e%\ec +in names of strings, macros, diversions, number registers, +fonts or environments; Unix troff does. +The +.B \eA +escape sequence may be helpful in avoiding use of these +escape sequences in names. +.LP +Fractional pointsizes cause one noteworthy incompatibility. +In Unix troff the +.B ps +request ignores scale indicators and so +.IP +.B .ps\ 10u +.LP +will set the pointsize to 10 points, whereas in +GNU troff it will set the pointsize to 10 scaled points. +.LP +In GNU troff there is a fundamental difference between unformatted, +input characters, and formatted, output characters. +Everything that affects how an output character +will be output is stored with the character; once an output +character 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 output characters are constructed from input +characters at the moment immediately before the character +is added to the current output line. +Macros, diversions and strings are all, in fact, the same type +of object; they contain lists of input characters and output +characters in any combination. +An output character does not behave like an input character +for the purposes of macro processing; it does not inherit any +of the special properties that the input character from which it +was constructed might have had. +For example, +.IP +.nf +.ft B +\&.di x +\e\e\e\e +\&.br +\&.di +\&.x +.ft +.fi +.LP +will print +.B \e\e +in GNU troff; +each pair of input +.BR \e s +is turned into one output +.B \e +and the resulting output +.BR \e s +are not interpreted as escape characters when they are reread. +Unix troff would interpret them as escape characters +when they were reread and would end up printing one +.BR \e . +The correct way to obtain a printable +.B \e +is to use the +.B \ee +escape sequence: this will always print a single instance of the +current escape character, regardless of whether or not it is used in a +diversion; it will also work in both GNU troff and Unix troff. +If you wish for some reason to store in a diversion an escape +sequence that will be interpreted when the diversion is reread, +you can either use the traditional +.B \e! +transparent output facility, or, if this is unsuitable, the new +.B \e? +escape sequence. +.SH ENVIRONMENT +.TP +.SM +.B GROFF_TMAC_PATH +A colon separated list of directories in which to search for +macro files. +.TP +.SM +.B GROFF_TYPESETTER +Default device. +.TP +.SM +.B GROFF_FONT_PATH +A colon separated list of directories in which to search for the +.BI dev name +directory. +.B troff +will search in directories given in the +.B \-F +option before these, and in standard directories +.RB ( @FONTPATH@ ) +after these. +.SH FILES +.Tp \w'@FONTDIR@/devname/DESC'u+3n +.B @MACRODIR@/troffrc +Initialization file +.TP +.BI @MACRODIR@/tmac. name +Macro files +.TP +.BI @FONTDIR@/dev name /DESC +Device description file for device +.IR name . +.TP +.BI @FONTDIR@/dev name / F +Font file for font +.I F +of device +.IR name . +.SH "SEE ALSO" +.BR groff (@MAN1EXT@) +.BR @g@tbl (@MAN1EXT@), +.BR @g@pic (@MAN1EXT@), +.BR @g@eqn (@MAN1EXT@), +.BR grops (@MAN1EXT@), +.BR grodvi (@MAN1EXT@), +.BR grotty (@MAN1EXT@), +.BR groff_font (@MAN5EXT@), +.BR groff_out (@MAN5EXT@), +.BR groff_char (@MAN7EXT@) |
