diff options
Diffstat (limited to 'contrib/groff/src/roff/troff/troff.man')
| -rw-r--r-- | contrib/groff/src/roff/troff/troff.man | 2595 |
1 files changed, 395 insertions, 2200 deletions
diff --git a/contrib/groff/src/roff/troff/troff.man b/contrib/groff/src/roff/troff/troff.man index ac746dc..19bb624 100644 --- a/contrib/groff/src/roff/troff/troff.man +++ b/contrib/groff/src/roff/troff/troff.man @@ -1,25 +1,44 @@ +'\" t .ig -Copyright (C) 1989-2000, 2001 Free Software Foundation, Inc. +troff.man -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. +Last update : 9 Jan 2002 -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. +This file is part of groff, the GNU roff type-setting system. -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. +Copyright (C) 1989, 2000, 2001, 2002 Free Software Foundation, Inc. + +written by James Clark + +modified by Werner Lemberg <wl@gnu.org> + Bernd Warken <bwarken@mayn.de> + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation; with the +Invariant Sections being this .ig-section and AUTHOR, 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. .. . -.\" 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 +. +.\" -------------------------------------------------------------------- +.\" Setup +.\" -------------------------------------------------------------------- +. +.mso www.tmac +. +.if n \{\ +. mso tty-char.tmac +. ftr CR R +. ftr CI I +. ftr CB B +.\} +. +.if '\*[.T]'dvi' \ +. ftr CB CW . .de TQ .br @@ -34,22 +53,19 @@ the original English. .el .TP "\\$1" .. . -.\" The BSD man macros can't handle " in arguments to font change macros, -.\" so use \(ts instead of ". -.tr \(ts" . +.\" -------------------------------------------------------------------- +.\" Title +.\" -------------------------------------------------------------------- . .TH @G@TROFF @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@" -. -. .SH NAME +@g@troff \- the troff processor of the groff text formatting system . . -@g@troff \- format documents -. -. +.\" -------------------------------------------------------------------- .SH SYNOPSIS -. +.\" -------------------------------------------------------------------- . .nr a \n(.j .ad l @@ -61,90 +77,75 @@ the original English. .ie \\n(.$-1 .RI "[\ \fB\\$1\fP" "\\$2" "\ ]" .el .RB "[\ " "\\$1" "\ ]" .. -.OP \-abivzCERU -.OP \-w name -.OP \-W name +.OP \-abcivzCERU .OP \-d cs .OP \-f fam +.OP \-F dir .OP \-m name +.OP \-M dir .OP \-n num .OP \-o list .OP \-r cn .OP \-T name -.OP \-F dir -.OP \-M dir +.OP \-w name +.OP \-W name .RI "[\ " files\|.\|.\|. "\ ]" .br .ad \na -.PP -It is possible to have whitespace between a command line option and its -parameter. +.P +It is possible to have whitespace between a command line option and +its parameter. . . +.\" -------------------------------------------------------------------- .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. +.BR troff . +It is part of the groff document formatting system. . +It is functionally compatible with UNIX troff, but has many extensions, +see +.BR \%groff_diff (@MAN7EXT@). +Usually it should be invoked using the +.BR groff (@MAN1EXT@) +command which will also run preprocessors and postprocessors in the +appropriate order and with the appropriate options. . -.SH 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 be correct: -.BR troff 's -idea of line numbers -gets confused by +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 be correct, for +.BR @g@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. +.B \-c +Disable color output (always disabled in compatibility mode). +. .TP .B \-C Enable compatibility mode. +. .TP .BI \-d cs .TQ @@ -157,11 +158,42 @@ to be a string .IR s ; .I c must be a one letter name. +. +.TP +.B \-E +Inhibit all error messages of +.BR @g@troff . +Note that this doesn't affect messages output to standard error by macro +packages using the +.B tm +or +.B tm1 +requests. +. .TP .BI \-f fam Use .I fam as the default font family. +. +.TP +.BI \-F dir +Search in directory (or directory path) +.I dir +for subdirectories +.BI dev name +.RI ( name +is the name of the device) and there for the +.B DESC +file and font files. +.I dir +is scanned before all other font directories. +. +.TP +.B \-i +Read the standard input after all the named input files have been +processed. +. .TP .BI \-m name Read in the file @@ -169,36 +201,28 @@ Read in the file If it isn't found, try .BI tmac. name instead. +. It will be first searched for in directories given with the .B \-M -command line option, then in directories given -in the +command line option, then in directories given in the .B GROFF_TMAC_PATH environment variable, then in the current directory (only if in unsafe mode), the home directory, @SYSTEMMACRODIR@, @LOCALMACRODIR@, and @MACRODIR@. +. .TP -.B \-U -Unsafe mode. -This will enable the following requests: -.BR .open , -.BR .opena , -.BR .pso , -.BR .sy , -and -.BR .pi . -For security reasons, these potentially dangerous requests are disabled -otherwise. It will also add the current directory to the macro search path. -.TP -.B \-R -Don't load -.B troffrc -and -.BR troffrc-end . +.BI \-M dir +Search directory (or directory path) +.I dir +for macro files. +. +This is scanned before all other macro directories. +. .TP .BI \-n num Number the first page .IR num . +. .TP .BI \-o list Output only pages in @@ -218,8 +242,9 @@ means print every page up to .IB n \- means print every page from .IR n . -.B Troff +.B @g@troff will exit after printing the last page in the list. +. .TP .BI \-r cn .TQ @@ -234,2227 +259,339 @@ to must be a one character name; .I n can be any troff numeric expression. +. +.TP +.B \-R +Don't load +.B troffrc +and +.BR troffrc-end . +. .TP .BI \-T name Prepare output for device .IR name , rather than the default .BR @DEVICE@ . -.TP -.BI \-F dir -Search in directory (or directory path) -.I dir -for subdirectories -.BI dev name -.RI ( name -is the name of the device) and there for the -.B DESC -file and font files. -.I dir -is scanned before all other font directories. -.TP -.BI \-M dir -Search directory (or directory path) -.I dir -for macro files. -This is scanned before all other macro directories. -. -. -.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 +.B \-U +Unsafe mode. . -.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 +This will enable the following requests: +.BR open , +.BR opena , +.BR pso , +.BR sy , 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 . +.BR pi . +For security reasons, these potentially dangerous requests are disabled +otherwise. . -.SS New escape sequences +It will also add the current directory to the macro search path. . .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 \eB' anything ' -This expands to -.B 1 -or -.B 0 -according as -.I anything -is or is not a valid numeric expression. -It will return -.B 0 -if -.I anything -is empty. -.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 -.IR 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 an 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: -This causes the insertion of a zero-width break point. -It is equal to -.B \e% -but without insertion of a soft hyphen character. -.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 +.B \-v +Print the version number. . .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 .am1\ xx\ yy -Similar to -.BR .am , -but compatibility mode is switched off during execution. -On entry, the current compatibility mode is saved and restored at exit. -.TP -.BI .asciify\ xx -This request `unformats' the diversion -.I xx -in such a way that -.SM ASCII -and space characters (and some escape sequences) that were formatted and -diverted into -.I xx -will be treated like ordinary input characters when -.I xx -is reread. -Useful for diversions in conjunction with the -.B .writem -request. -It can be also used for gross hacks; for example, this -.RS -.IP -.ne 7v+\n(.Vu -.ft B -.nf -\&.tr @. -\&.di x -\&@nr n 1 -\&.br -\&.di -\&.tr @@ -\&.asciify x -\&.x -.fi -.RE -.IP -will set register -.B n -to 1. -Note that glyph information (font, font size, etc.) is not preserved; use -.B .unformat -instead. -.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 -.BI .box\ xx -.TQ -.BI .boxa\ xx -These requests are similar to the -.B di -and -.B da -requests with the exception that a partially filled line will not become -part of the diversion (i.e., the diversion always starts with a new line) -but restored after ending the diversion, discarding the partially filled -line which possibly comes from the diversion. -.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 -.B .brp -This is the same as -.BR \ep . -.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 .dei\ xx\ yy -Define macro indirectly. -The following example -.RS -.IP -.ne 2v+\n(.Vu -.ft B -.nf -\&.ds xx aa -\&.ds yy bb -\&.dei xx yy -.fi -.RE -.IP -is equivalent to -.RS -.IP -.B -\&.de aa bb -.RE -.TP -.BI .de1\ xx\ yy -Similar to -.BR .de , -but compatibility mode is switched off during execution. -On entry, the current compatibility mode is saved and restored at exit. -.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 -.B .ecs -Save current escape character. -.TP -.B .ecr -Restore escape character saved with -.BR ecs . -Without a previous call to -.BR ecs , -.RB ` \e ' -will be the new escape character. -.TP -.BI .evc\ xx -Copy the contents of environment -.I xx -to the current environment. -No pushing or popping of environents will be done. -.TP -.BI .fam\ xx -Set the current font family to -.IR xx . -The current font family is part of the current environment. -If -.I xx -is missing, switch back to previous font family. -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 -.IB name .tmac -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 .length\ xx\ string -Compute the length of -.I string -and return it in the number register -.I xx -(which is not necessarily defined before). -.TP -.BI .linetabs\ n -If -.I n -is non-zero or missing, enable line-tabs mode, otherwise disable it (which -is the default). -In line-tabs mode, tab distances are computed relative to the (current) -output line. -Otherwise they are taken relative to the input line. -For example, the following -.RS -.IP -.ne 6v+\n(.Vu -.ft B -.nf -\&.ds x a\et\ec -\&.ds y b\et\ec -\&.ds z c -\&.ta 1i 3i -\e*x -\e*y -\e*z -.fi -.RE -.IP -yields -.RS -.IP -a b c -.RE -.IP -In line-tabs mode, the same code gives -.RS -.IP -a b c -.RE -.IP -Line-tabs mode is associated with the current environment; the read-only -number register -.B \\en[.linetabs] -is set to\~1 if in line-tabs mode, and 0 otherwise. -.TP -.BI .mso\ file -The same as the -.B so -request except that -.I file -is searched for in the same directories as macro files for the -the -.B \-m -command line option. -If the file name to be included -has the form -.IB name .tmac -and it isn't found, -.B mso -tries to include -.BI tmac. name -instead and vice versa. -.TP -.BI .nop \ anything -Execute -.IR anything . -This is similar to `.if\ 1'. -.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 .psbb \ filename -Get the bounding box of a PostScript image -.IR filename . -This file must conform to Adobe's Document Structuring Conventions; the -command looks for a -.B %%BoundingBox -comment to extract the bounding box values. -After a successful call, the coordinates (in PostScript units) of the lower -left and upper right corner can be found in the registers -.BR \en[llx] , -.BR \en[lly] , -.BR \en[urx] , -and -.BR \en[ury] , -respectively. -If some error has occurred, the four registers are set to zero. -.TP -.BI .pso \ command -This 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 .return -Within a macro, return immediately. -No effect otherwise. -.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 .substring\ xx\ n1\ [ n2 ] -Replace the string in register -.I xx -with the substring defined by the indices -.I n1 -and -.IR n2 . -The first character in the string has index one. -If -.I n2 -is omitted, it is taken to be equal to the string's length. If the -index value -.I n1 -or -.I n2 -is negative or zero, it will be counted from the end of the string, -going backwards: The last character has index 0, the character before -the last character has index -1, etc. -.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 .tm1\ string -Similar to the -.B tm -request, -.I string -is read in copy mode and written on the standard error, but an initial -double quote in -.I string -is stripped off to allow initial blanks. -.TP -.BI .tmc\ string -Similar to -.BR tm1 -but without writing a final newline. -.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 -.IP -.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 .unformat\ xx -This request `unformats' the diversion -.IR xx . -Contrary to the -.B .asciify -request, which tries to convert formatted elements of the diversion back -to input tokens as much as possible, -.B .unformat -will only handle tabs and spaces between words (usually caused by spaces -or newlines in the input) specially. -The former are treated as if they were input tokens, and the latter are -stretchable again. -Note that the vertical size of lines is not preserved. -Glyph information (font, font size, space width, etc.) is retained. -Useful in conjunction with the -.B .box -and -.B .boxa -requests. -.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. -.TP -.BI .writem\ stream\ xx -Write the contents of the macro or string -.I xx -to the stream named -.IR stream . -.I stream -must previously have been the subject of an -.B open -request. -.I xx -is read in copy mode. +.BI \-w name +Enable warning +.IR name . +Available warnings are described in the section +.I WARNINGS +below. . -.SS Extended requests +For example, to enable all warnings, use +.B \-w +.BR all . +Multiple +.B \-w +options are allowed. . .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. -Contrary to UNIX troff, GNU troff handles this request in nroff mode -also; a given value is then rounded down to the nearest multiple of\~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 +.BI \-W name +Inhibit warning +.IR name . +Multiple +.B \-W +options are allowed. . -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[.int] -Set to a positive value if last output line is interrupted (i.e., if it -contains -.IR \ec ). -.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[.linetabs] -The current line-tabs mode (as set by the -.B linetabs -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[.ns] -.B 1 -if no-space mode is active, -.B 0 -otherwise. -.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 . -.TP -.B \en[.Y] -The revision number of groff. -.TP -.B \en[llx] -.TQ -.B \en[lly] -.TQ -.B \en[urx] -.TQ -.B \en[ury] -These four registers are set by the -.B \&.psbb -request and contain the bounding box values (in PostScript units) of a given -PostScript image. -.LP -The following read/write 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 -Other available read/write number registers are: -.TP -.B \en[c.] -The current input line number. -.B \en[.c] -is a read-only alias to this register. .TP -.B \en[hp] -The current horizontal position at input line. -.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. -.TP -.B \en[year] -The current year. -Note that the traditional -.B troff -number register -.B \en[yr] -is the current year minus 1900. -. -.SS Miscellaneous +.B \-z +Suppress formatted output. . -.B @g@troff -predefines a single (read/write) string-based register, -.BR \e*(.T , -which contains the argument given to the -.B -T -command line option, namely the current output device (for example, -.I latin1 -or -.IR ascii ). -Note that this is not the same as the (read-only) number register -.B \en[.T] -which is defined to be\ 1 if -.B troff -is called with the -.B -T -command line option, and zero otherwise. This behaviour is different to -UNIX troff. -.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. -.LP -The -.B tr -request can now map characters onto -.BR \e~ . . -.SS Warnings +.\" -------------------------------------------------------------------- +.SH WARNINGS +.\" -------------------------------------------------------------------- . The warnings that can be given by -.B troff +.B @g@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 +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 +register; it is always a power of 2 to allow bitwise composition. +. +.P +.TS +tab(@), center, box; +c c c | c c c +r rI lB | r rI lB. +Bit@Code@Warning@Bit@Code@Warning +_ +0@1@char@10@1024@reg +1@2@number@11@2048@tab +2@4@break@12@4096@right-brace +3@8@delim@13@8192@missing +4@16@el@14@16384@input +5@32@scale@15@32768@escape +6@64@range@16@65536@space +7@128@syntax@17@131072@font +8@256@di@18@262144@ig +9@512@mac@19@524288@color +.TE +. +.P +.nr x \w'\fBright-brace'+1n+\w'00000'u .ta \nxuR +. .TP \nxu+3n -.BR char \t1 -Non-existent characters. +.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 number \t2 -Invalid numeric expressions. +.BR char "\t1" +Non-existent characters. +. 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. +.BR color "\t524288" +Color related warnings. +. .TP -.BR delim \t8 +.BR delim "\t8" Missing or mismatched closing delimiters. +. +.TP +.BR di "\t256" +Use of +.B di +or +.B da +without an argument when there is no current diversion. +. .TP -.BR el \t16 +.BR el "\t16" Use of the .B el request with no matching .B ie request. +. .TP -.BR scale \t32 -Meaningless scaling indicators. +.BR escape "\t32768" +Unrecognized escape sequences. +. +When an unrecognized escape sequence is encountered, the escape +character is ignored. +. .TP -.BR range \t64 -Out of range arguments. +.BR font "\t131072" +Non-existent fonts. +. +This is enabled by default. +. .TP -.BR syntax \t128 -Dubious syntax in numeric expressions. +.BR ig "\t262144" +Invalid escapes in text ignored with the +.B ig +request. +. +These are conditions that are errors when they do not occur in ignored +text. +. .TP -.BR di \t256 -Use of -.B di -or -.B da -without an argument when there is no current diversion. +.BR input "\t16384" +Invalid input characters. +. .TP -.BR mac \t512 +.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. +. +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. +.BR missing "\t8192" +Requests that are missing non-optional arguments. +. .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. +.BR number "\t2" +Invalid numeric expressions. +. +This is enabled by default. +. .TP -.BR right-brace \t4096 -Use of -.B \e} -where a number was expected. +.BR range "\t64" +Out of range arguments. +. .TP -.BR missing \t8192 -Requests that are missing non-optional arguments. +.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. +. +So, in most cases, at most one warning will be given for use of a +particular name. +. .TP -.BR input \t16384 -Illegal input characters. +.BR right-brace "\t4096" +Use of +.B \[rs]} +where a number was expected. +. .TP -.BR escape \t32768 -Unrecognized escape sequences. -When an unrecognized escape sequence is encountered, -the escape character is ignored. +.BR scale "\t32" +Meaningless scaling indicators. +. .TP -.BR space \t65536 +.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. +. +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. +.BR syntax "\t128" +Dubious syntax in numeric expressions. +. .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 +.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. +. +.P There are also names that can be used to refer to groups of warnings: +. .TP .B all All warnings except .BR di , -.B mac +.BR mac , and .BR reg . -It is intended that this covers all warnings -that are useful with traditional macro packages. +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. -.B troff -will scan directories given in -the +.B @g@troff +will scan directories given in the .B \-M -option before these, and in standard directories (current directory if in -unsafe mode, home directory, -.BR @LOCALMACRODIR@ , +option before these, and in standard directories (current directory if +in unsafe mode, home directory, .BR @SYSTEMMACRODIR@ , +.BR @LOCALMACRODIR@ , .BR @MACRODIR@ ) after these. +. .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 +.B @g@troff will scan directories given in the .B \-F option before these, and in standard directories -.RB ( @FONTPATH@ ) +.RB ( @LOCALFONTDIR@ , +.BR @FONTDIR@ , +.BR @LEGACYFONTDIR@ ) after these. . . +.\" -------------------------------------------------------------------- .SH FILES -. +.\" -------------------------------------------------------------------- . .Tp \w'@FONTDIR@/devname/DESC'u+3n .B @MACRODIR@/troffrc Initialization file (called before any other macro package). +. .TP .B @MACRODIR@/troffrc-end Initialization file (called after any other macro package). +. .TP .BI @MACRODIR@/ name .tmac .TQ .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 . -.LP +.P Note that .B troffrc and .B troffrc-end -are neither searched in the current nor in the home directory by default for -security reasons (even if the +are neither searched in the current nor in the home directory by +default for security reasons (even if the .B \-U option is given). +. Use the .B \-M command line option or the @@ -2463,28 +600,86 @@ environment variable to add these directories to the search path if necessary. . . +.\" -------------------------------------------------------------------- +.SH AUTHOR +.\" -------------------------------------------------------------------- +. +Copyright (C) 1989, 2001, 2002 Free Software Foundation, Inc. +. +.P +This document is distributed under the terms of the FDL (GNU Free +Documentation License) version 1.1 or later. +. +You should have received a copy of the FDL on your system, it is also +available on-line at the +.URL http://www.gnu.org/copyleft/fdl.html "GNU copyleft site" . +This document was written by James Clark, with modifications from +.MTO wl@gnu.org "Werner Lemberg" +and +.MTO bwarken@mayn.de "Bernd Warken" +. +.P +This document is part of +.IR groff , +the GNU roff distribution. +. +. +.\" -------------------------------------------------------------------- .SH "SEE ALSO" +.\" -------------------------------------------------------------------- . +.TP +.BR groff (@MAN1EXT@) +The main program of the +.I groff +system, a wrapper around +.IR @g@troff . . +.TP .BR groff (@MAN7EXT@) --- This is a short but complete reference of all requests, registers, and -escapes. -.PP -.BR groff (@MAN1EXT@), -.BR @g@tbl (@MAN1EXT@), -.BR @g@pic (@MAN1EXT@), -.BR @g@eqn (@MAN1EXT@), -.BR @g@refer (@MAN1EXT@), -.BR @g@soelim (@MAN1EXT@), -.BR @g@grn (@MAN1EXT@), -.BR grops (@MAN1EXT@), -.BR grodvi (@MAN1EXT@), -.BR grotty (@MAN1EXT@), -.BR grohtml (@MAN1EXT@), -.BR grolj4 (@MAN1EXT@), -.BR groff_font (@MAN5EXT@), -.BR groff_out (@MAN5EXT@), -.BR groff_char (@MAN7EXT@) +A description of the +.I groff +language, including a short but complete reference of all predefined +requests, registers, and escapes of plain +.IR groff . +From the command line, this is called by +.RS +.IP +.B man 7 groff +.RE +. +.TP +.BR \%groff_diff (@MAN7EXT@) +The differences of the +.I groff +language and the +.I classical troff +language. +. +Currently, this is the most actual document of the +.I groff +system. +. +.TP +.BR roff (@MAN7EXT@) +An overview over +.I groff +and other +.I roff +systems, including pointers to further related documentation. +. +.P +The +.I groff info +.IR file , +cf.\& +.BR info (@MAN1EXT@), +presents all groff documentation within a single document. +. +. +.\" -------------------------------------------------------------------- +.\" Emacs variables +.\" -------------------------------------------------------------------- . .\" Local Variables: .\" mode: nroff |
