2 Copyright (C) 1989-2000, 2001 Free Software Foundation, Inc.
4 Permission is granted to make and distribute verbatim copies of
5 this manual provided the copyright notice and this permission notice
6 are preserved on all copies.
8 Permission is granted to copy and distribute modified versions of this
9 manual under the conditions for verbatim copying, provided that the
10 entire resulting derived work is distributed under the terms of a
11 permission notice identical to this one.
13 Permission is granted to copy and distribute translations of this
14 manual into another language, under the above conditions for modified
15 versions, except that this permission notice may be included in
16 translations approved by the Free Software Foundation instead of in
20 .\" define a string tx for the TeX logo
21 .ie t .ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
30 .\" Like TP, but if specified indent is more than half
31 .\" the current line-length - indent, use the default indent.
33 .ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP
37 .\" The BSD man macros can't handle " in arguments to font change macros,
38 .\" so use \(ts instead of ".
42 .TH TROFF 1 "27 June 2001" "Groff Version 1.17.2"
48 troff \- format documents
61 .ie \\n(.$-1 .RI "[\ \fB\\$1\fP" "\\$2" "\ ]"
62 .el .RB "[\ " "\\$1" "\ ]"
76 .RI "[\ " files\|.\|.\|. "\ ]"
80 It is possible to have whitespace between a command line option and its
87 This manual page describes the GNU version of
89 which is part of the groff document formatting system.
90 It is highly compatible with UNIX troff.
91 Usually it should be invoked using the groff command, which will
92 also run preprocessors and postprocessors in the appropriate
93 order and with the appropriate options.
103 approximation of the typeset output.
106 Print a backtrace with each warning or error message. This backtrace
107 should help track down the cause of the error. The line numbers given
108 in the backtrace may not always be correct:
118 Read the standard input after all the named input files have been
122 Print the version number.
127 Available warnings are described in
128 the Warnings subsection below.
141 Inhibit all error messages.
144 Suppress formatted output.
147 Enable compatibility mode.
159 must be a one letter name.
164 as the default font family.
169 If it isn't found, try
172 It will be first searched for in directories given with the
174 command line option, then in directories given
177 environment variable, then in the current directory (only if in unsafe
178 mode), the home directory, /usr/lib/groff/site-tmac, /usr/share/groff/site-tmac, and
179 /usr/share/groff/1.17.2/tmac.
183 This will enable the following requests:
190 For security reasons, these potentially dangerous requests are disabled
191 otherwise. It will also add the current directory to the macro search path.
200 Number the first page
206 which is a comma-separated list of page ranges;
211 means print every page between
216 means print every page up to
219 means print every page from
222 will exit after printing the last page in the list.
234 must be a one character name;
236 can be any troff numeric expression.
239 Prepare output for device
241 rather than the default
245 Search in directory (or directory path)
250 is the name of the device) and there for the
254 is scanned before all other font directories.
257 Search directory (or directory path)
260 This is scanned before all other macro directories.
266 Only the features not in UNIX troff are described here.
270 The names of number registers, fonts, strings/macros/diversions,
271 special characters can be of any length. In escape sequences, where
274 for a two character name, you can use
276 for a name of arbitrary length:
279 Print the special character called
291 Interpolate number register
294 .SS Fractional pointsizes
299 is equal to 1/sizescale
301 sizescale is specified in the
304 There is a new scale indicator
306 which has the effect of multiplying by sizescale.
307 Requests and escape sequences in troff
308 interpret arguments that represent a pointsize as being in units
309 of scaled points, but they evaluate each such argument
310 using a default scale indicator of
312 Arguments treated in this way are
316 the third argument to the
319 the second and fourth arguments to the
325 and those variants of the
327 escape sequence that take a numeric expression as their argument.
329 For example, suppose sizescale is 1000;
330 then a scaled point will be equivalent to a millipoint;
335 and so sets the pointsize to 10250 scaled points,
336 which is equal to 10.25 points.
340 returns the pointsize in points as decimal fraction.
341 There is also a new number register
343 that returns the pointsize in scaled points.
345 It would make no sense to use the
347 scale indicator in a numeric expression
348 whose default scale indicator was neither
355 Similarly it would make no sense to use a scaling indicator
360 in a numeric expression whose default scale indicator was
364 disallows this as well.
366 There is also new scale indicator
368 which multiplies by the number of units in a scaled point.
373 Be sure not to confuse the
379 .SS Numeric expressions
382 Spaces are permitted in a number expression within parentheses.
385 indicates a scale of 100ths of an em.
404 as the default scaling indicator.
407 is missing, ignore scaling indicators in the evaluation of
410 .SS New escape sequences
420 is or is not acceptable as the name of a string, macro, diversion,
421 number register, environment or font.
427 This is useful if you want to lookup user input in some sort of
437 is or is not a valid numeric expression.
445 Typeset character named
447 Normally it is more convenient to use
451 has the advantage that it is compatible with recent versions of
453 and is available in compatibility mode.
456 This is equivalent to an escape character,
457 but it's not interpreted in copy-mode.
458 For example, strings to start and end superscripting could be defined
462 \&.ds { \ev'\-.3m'\es'\eEn[.s]*6u/10u'
468 ensures that these definitions will work even if
470 gets interpreted in copy-mode
471 (for example, by being used in a macro argument).
475 Typeset the character with code
480 Most devices only have characters with codes between 0 and 255.
481 If the current font does not contain a character with that code,
487 escape sequence can be conveniently used on conjunction with the
493 \&.char \e[phone] \ef(ZD\eN'37'
496 The code of each character is given in the fourth column in the font
497 description file after the
500 It is possible to include unnamed characters in the font description
501 file by using a name of
505 escape sequence is the only way to use these.
507 .BI \eR' name\ \(+-n '
508 This has the same effect as
517 Set the point size to
521 must be exactly two digits.
530 Set the point size to
534 is a numeric expression with a default scale indicator of
542 Interpolate the contents of the environment variable
547 is interpreted in copy-mode.
554 This is approximately equivalent to
555 .BI \eX'\e*[ xxx ]'\fR.
556 However the contents of the string or macro
559 also it is permitted for
561 to have been defined as a macro and thus contain newlines
562 (it is not permitted for the argument to
564 to contain newlines).
565 The inclusion of newlines requires an extension to the UNIX troff output
566 format, and will confuse drivers that do not know about this
570 Print anything and then restore the horizontal and vertical
573 may not contain tabs or leaders.
576 The name by which the current macro was invoked.
579 request can make a macro have more than one name.
582 In a macro, the concatenation of all the arguments separated by spaces.
585 In a macro, the concatenation of all the arguments with each surrounded by
586 double quotes, and separated by spaces.
591 In a macro, this gives the
596 Macros can have an unlimited number of arguments.
599 When used in a diversion, this will transparently embed
603 is read in copy mode.
604 When the diversion is reread,
608 may not contain newlines; use
610 if you want to embed newlines in a diversion.
613 is also recognised in copy mode and turned into a single internal
614 code; it is this code that terminates
625 \e?\e\e?\e\e\e\e?\e\e\e\e\e\e\e\enx\e\e\e\e?\e\e?\e?
646 This increases the width of the preceding character so that
647 the spacing between that character and the following character
648 will be correct if the following character is a roman character.
649 For example, if an italic f is immediately followed by a roman
650 right parenthesis, then in many fonts the top right portion of the f
651 will overlap the top left of the right parenthesis producing \fIf\fR)\fR,
656 .ie \n(.g \fIf\/\fR)\fR
658 and avoids this problem.
659 It is a good idea to use this escape sequence whenever an
660 italic character is immediately followed by a roman character without any
664 This modifies the spacing of the following character so that the spacing
665 between that character and the preceding character will correct if
666 the preceding character is a roman character.
667 For example, inserting
669 between the parenthesis and the f changes
671 .ie \n(.g \fR(\,\fIf\fR.
673 It is a good idea to use this escape sequence whenever a
674 roman character is immediately followed by an italic character without any
680 except that it behaves like a character declared with the
682 request to be transparent for the purposes of end of sentence recognition.
685 This produces an unbreakable space that stretches like a normal inter-word
686 space when a line is adjusted.
689 This causes the insertion of a zero-width break point.
692 but without insertion of a soft hyphen character.
695 Everything up to and including the next newline is ignored.
696 This is interpreted in copy mode.
701 does not ignore the terminating newline.
709 for number register object named
711 The new name and the old name will be exactly equivalent.
714 is undefined, a warning of type
716 will be generated, and the request will be ignored.
721 for request, string, macro, or diversion object named
723 The new name and the old name will be exactly equivalent (it is similar to a
724 hard rather than a soft link).
727 is undefined, a warning of type
729 will be generated, and the request will be ignored.
738 requests only create a new object if the name of the macro, diversion
739 or string diversion is currently undefined or if it is defined to be a
740 request; normally they modify the value of an existing object.
745 but compatibility mode is switched off during execution.
746 On entry, the current compatibility mode is saved and restored at exit.
749 This request `unformats' the diversion
753 and space characters (and some escape sequences) that were formatted and
756 will be treated like ordinary input characters when
759 Useful for diversions in conjunction with the
762 It can be also used for gross hacks; for example, this
782 Note that glyph information (font, font size, etc.) is not preserved; use
787 Print a backtrace of the input stack on stderr.
790 Set the blank line macro to
792 If there is a blank line macro,
793 it will be invoked when a blank line is encountered instead of the usual
799 These requests are similar to the
803 requests with the exception that a partially filled line will not become
804 part of the diversion (i.e., the diversion always starts with a new line)
805 but restored after ending the diversion, discarding the partially filled
806 line which possibly comes from the diversion.
809 Break out of a while loop.
815 Be sure not to confuse this with the
823 .BI .cflags\ n\ c1\ c2\|.\|.\|.
827 have properties determined by
829 which is ORed from the following:
833 the character ends sentences
834 (initially characters
839 lines can be broken before the character
840 (initially no characters have this property);
841 a line will not be broken at a character with this property
842 unless the characters on each side both have non-zero
846 lines can be broken after the character
847 (initially characters
850 a line will not be broken at a character with this property
851 unless the characters on each side both have non-zero
855 the character overlaps horizontally
856 (initially characters
861 the character overlaps vertically
867 an end of sentence character followed by any number of characters
868 with this property will be treated
869 as the end of a sentence if followed by a newline or two spaces;
871 the character is transparent for the purposes of end of sentence
873 this is the same as having a zero space factor in \*(tx
874 (initially characters
875 .B \(ts')]*\e(dg\e(rq
888 will be processed in a temporary environment and the result
889 will be wrapped up into a single object.
890 Compatibility mode will be turned off
891 and the escape character will be set to
896 Any emboldening, constant spacing or track kerning will be applied
897 to this object rather than to individual characters in
899 A character defined by this request can be used just like
900 a normal character provided by the output device.
901 In particular other characters can be translated to it
905 it can be made the leader character by the
908 repeated patterns can be drawn with the character using the
913 words containing the character can be hyphenated
916 request is used to give the character a hyphenation code.
917 There is a special anti-recursion feature:
918 use of character within the character's definition
919 will be handled like normal characters not defined with
921 A character definition can be removed with the
926 Chop the last character off macro, string, or diversion
928 This is useful for removing the newline from the end of diversions
929 that are to be interpolated as strings.
932 Close the stream named
935 will no longer be an acceptable argument to the
943 Finish the current iteration of a while loop.
953 is non-zero or missing, enable compatibility mode, otherwise
955 In compatibility mode, long names are not recognised, and the
956 incompatibilities caused by long names do not arise.
959 Define macro indirectly.
960 The following example
982 but compatibility mode is switched off during execution.
983 On entry, the current compatibility mode is saved and restored at exit.
988 with compatibility mode disabled.
995 would have the same effect as
1000 except that it would work even if compatibility mode had been enabled.
1001 Note that the previous compatibility mode is restored before any files
1008 Save current escape character.
1011 Restore escape character saved with
1013 Without a previous call to
1016 will be the new escape character.
1019 Copy the contents of environment
1021 to the current environment.
1022 No pushing or popping of environents will be done.
1025 Set the current font family to
1027 The current font family is part of the current environment.
1030 is missing, switch back to previous font family.
1031 See the description of the
1033 request for more information on font families.
1035 .BI .fspecial\ f\ s1\ s2\|.\|.\|.
1036 When the current font is
1041 will be special, that is, they will searched for characters not in
1043 Any fonts specified in the
1045 request will be searched after fonts specified in the
1054 Whenever a font named
1081 will not be translated.
1083 .BI .hcode \ c1\ code1\ c2\ code2\|.\|.\|.
1084 Set the hyphenation code of character
1092 A hyphenation code must be a single input
1093 character (not a special character) other than a digit or a space.
1094 Initially each lower-case letter has a hyphenation code, which
1095 is itself, and each upper-case letter has a hyphenation code
1096 which is the lower case version of itself.
1102 Set the current hyphenation language to
1104 Hyphenation exceptions specified with the
1106 request and hyphenation patterns specified with the
1108 request are both associated with the current hyphenation language.
1111 request is usually invoked by the
1116 Set the maximum number of consecutive hyphenated lines to
1120 is negative, there is no maximum.
1121 The default value is \-1.
1122 This value is associated with the current environment.
1123 Only lines output from an environment count towards the maximum associated
1124 with that environment.
1125 Hyphens resulting from
1127 are counted; explicit hyphens are not.
1130 Read hyphenation patterns from
1132 this will be searched for in the same way that
1134 is searched for when the
1136 option is specified.
1137 It should have the same format as the argument to
1138 the \epatterns primitive in \*(tx;
1139 the letters appearing in this file are interpreted as hyphenation
1143 character in the patterns file introduces a comment that continues
1144 to the end of the line.
1145 The set of hyphenation patterns is associated with the current language
1152 is usually invoked by the
1158 .I hyphenation margin
1161 when the current adjustment mode is not
1163 the line will not be hyphenated if the line is no more than
1166 The default hyphenation margin is 0.
1167 The default scaling indicator for this request is
1169 The hyphenation margin is associated with the current environment.
1170 The current hyphenation margin is available in the
1176 .I hyphenation space
1179 when the current adjustment mode is
1181 don't hyphenate the line if the line can be justified by adding no more than
1183 extra space to each word space.
1184 The default hyphenation space is 0.
1185 The default scaling indicator for this request is
1187 The hyphenation space is associated with the current environment.
1188 The current hyphenation space is available in the
1195 is non-zero or missing, enable pairwise kerning, otherwise disable it.
1197 .BI .length\ xx\ string
1198 Compute the length of
1200 and return it in the number register
1202 (which is not necessarily defined before).
1207 is non-zero or missing, enable line-tabs mode, otherwise disable it (which
1209 In line-tabs mode, tab distances are computed relative to the (current)
1211 Otherwise they are taken relative to the input line.
1212 For example, the following
1234 In line-tabs mode, the same code gives
1240 Line-tabs mode is associated with the current environment; the read-only
1243 is set to\~1 if in line-tabs mode, and 0 otherwise.
1250 is searched for in the same directories as macro files for the
1253 command line option.
1254 If the file name to be included
1261 instead and vice versa.
1266 This is similar to `.if\ 1'.
1271 built-in condition true
1274 built-in condition false.
1275 This can be reversed using the
1279 .BI .open\ stream\ filename
1282 for writing and associate the stream named
1291 .BI .opena\ stream\ filename
1296 exists, append to it instead of truncating it.
1299 Print the names and contents of all currently defined number registers
1302 .BI .psbb \ filename
1303 Get the bounding box of a PostScript image
1305 This file must conform to Adobe's Document Structuring Conventions; the
1308 comment to extract the bounding box values.
1309 After a successful call, the coordinates (in PostScript units) of the lower
1310 left and upper right corner can be found in the registers
1317 If some error has occurred, the four registers are set to zero.
1320 This behaves like the
1322 request except that input comes from the standard output of
1326 Print the names and positions of all traps (not including input line
1327 traps and diversion traps) on stderr. Empty slots in the page trap
1328 list are printed as well, because they can affect the priority of
1329 subsequently planted traps.
1331 .BI .rchar\ c1\ c2\|.\|.\|.
1332 Remove the definitions of characters
1335 This undoes the effect of a
1340 Within a macro, return immediately.
1341 No effect otherwise.
1346 Right justify the next
1349 Without an argument right justify the next input line.
1350 The number of lines to be right justified is available in the
1353 This implicitly does
1357 request implicitly does
1361 Rename number register
1367 Set the soft hyphen character to
1372 the soft hyphen character will be set to the default
1374 The soft hyphen character is the character which will be inserted
1375 when a word is hyphenated at a line break.
1376 If the soft hyphen character does not exist in the font of the character
1377 immediately preceding a potential break point,
1378 then the line will not be broken at that point.
1379 Neither definitions (specified with the
1382 nor translations (specified with the
1385 are considered when finding the soft hyphen character.
1388 In a macro, shift the arguments by
1397 will no longer be available.
1401 arguments will be shifted by 1.
1402 Shifting by negative amounts is currently undefined.
1404 .BI .special\ s1\ s2\|.\|.\|.
1408 are special and will be searched for characters not in the
1416 A font position can be associated either with a font or
1418 The current font is the index of a font position and so is also
1419 either a font or a style.
1420 When it is a style, the font that is actually used is the font the
1421 name of which is the concatenation of the name of the current family
1422 and the name of the current style.
1423 For example, if the current font is 1 and font position 1 is
1424 associated with style
1432 If the current font is not a style, then the current family is ignored.
1440 are applied to a style,
1441 then they will instead be applied to the member of the
1442 current family corresponding to that style.
1443 The default family can be set with the
1446 The styles command in the
1448 file controls which font positions
1449 (if any) are initially associated with styles rather than fonts.
1451 .BI .substring\ xx\ n1\ [ n2 ]
1452 Replace the string in register
1454 with the substring defined by the indices
1458 The first character in the string has index one.
1461 is omitted, it is taken to be equal to the string's length. If the
1466 is negative or zero, it will be counted from the end of the string,
1467 going backwards: The last character has index 0, the character before
1468 the last character has index -1, etc.
1470 .BI .tkf\ f\ s1\ n1\ s2\ n2
1471 Enable track kerning for font
1473 When the current font is
1475 the width of every character will be increased by an amount
1480 when the current point size is less than or equal to
1482 the width will be increased by
1484 when it is greater than or equal to
1486 the width will be increased by
1488 when the point size is greater than or equal to
1490 and less than or equal to
1492 the increase in width is a linear function of the point size.
1499 is read in copy mode and written on the standard error, but an initial
1502 is stripped off to allow initial blanks.
1507 but without writing a final newline.
1510 Transparently output the contents of file
1512 Each line is output as it would be were it preceded by
1514 however, the lines are not subject to copy-mode interpretation.
1515 If the file does not end with a newline, then a newline will
1517 For example, you can define a macro
1519 containing the contents of file
1533 the file cannot contain characters such as
1535 that are not legal troff input characters.
1539 This is the same as the
1541 request except that the translations do not apply to text that is
1542 transparently throughput into a diversion with
1570 built-in condition false,
1573 built-in condition true.
1574 This undoes the effect of the
1579 This request `unformats' the diversion
1583 request, which tries to convert formatted elements of the diversion back
1584 to input tokens as much as possible,
1586 will only handle tabs and spaces between words (usually caused by spaces
1587 or newlines in the input) specially.
1588 The former are treated as if they were input tokens, and the latter are
1590 Note that the vertical size of lines is not preserved.
1591 Glyph information (font, font size, space width, etc.) is retained.
1592 Useful in conjunction with the
1599 Enable vertical position traps if
1601 is non-zero, disable them otherwise.
1602 Vertical position traps are traps set by the
1609 request are not vertical position traps.
1610 The parameter that controls whether vertical position traps are enabled
1612 Initially vertical position traps are enabled.
1617 is the sum of the numbers associated with each warning that is to be enabled;
1618 all other warnings will be disabled.
1619 The number associated with each warning is listed in the `Warnings' section.
1622 will disable all warnings, and
1624 will disable all warnings except that about missing characters.
1628 all warnings will be enabled.
1630 .BI .while \ c\ anything
1637 can be any condition acceptable to an
1641 can comprise multiple lines if the first line starts with
1643 and the last line ends with
1651 .BI .write\ stream\ anything
1657 must previously have been the subject of an
1661 is read in copy mode;
1666 .BI .writem\ stream\ xx
1667 Write the contents of the macro or string
1672 must previously have been the subject of an
1676 is read in copy mode.
1678 .SS Extended requests
1682 When used in a diversion, this will embed in the diversion an object which,
1683 when reread, will cause the contents of
1685 to be transparently copied through to the output.
1689 is immediately copied through to the output regardless of whether
1690 there is a current diversion; this behaviour is so anomalous that it
1691 must be considered a bug.
1696 is not a number, this will switch to a named environment called
1698 The environment should be popped with a matching
1700 request without any arguments, just as for numbered environments.
1701 There is no limit on the number of named environments; they will be
1702 created the first time that they are referenced.
1707 request has an optional third argument.
1708 This argument gives the external name of the font,
1709 which is used for finding the font description file.
1710 The second argument gives the internal name of the font
1711 which is used to refer to the font in troff after it has been mounted.
1712 If there is no third argument then the internal name will be used
1713 as the external name.
1714 This feature allows you to use fonts with long names in compatibility mode.
1717 When two arguments are given to the
1719 request, the second argument gives the
1720 .IR "sentence space size" .
1721 If the second argument is not given, the sentence space size
1722 will be the same as the word space size.
1723 Like the word space size, the sentence space is in units of
1724 one twelfth of the spacewidth parameter for the current font.
1725 Initially both the word space size and the sentence
1727 Contrary to UNIX troff, GNU troff handles this request in nroff mode
1728 also; a given value is then rounded down to the nearest multiple of\~12.
1729 The sentence space size is used in two circumstances:
1730 if the end of a sentence occurs at the end of a line in fill mode, then
1731 both an inter-word space and a sentence space will be added;
1732 if two spaces follow the end of a sentence in the middle of a line,
1733 then the second space will be a sentence space.
1734 Note that the behaviour of UNIX troff will be exactly
1735 that exhibited by GNU troff if a second argument is never given to the
1738 In GNU troff, as in UNIX troff, you should always
1739 follow a sentence with either a newline or two spaces.
1741 .BI .ta\ n1\ n2\|.\|.\|.nn \ T\ r1\ r2\|.\|.\|.\|rn
1742 Set tabs at positions
1744 .IR n2 ,\|.\|.\|.\|,
1746 and then set tabs at
1748 .IR nn + r2 ,\|.\|.\|.\|.\|,
1752 .IR nn + rn + r2 ,\|.\|.\|.\|,
1761 will set tabs every half an inch.
1764 .SS New number registers
1766 The following read-only registers are available:
1769 1 if compatibility mode is in effect, 0 otherwise.
1772 The depth of the last character added to the current environment.
1773 It is positive if the character extends below the baseline.
1776 The number of lines remaining to be centered, as set by the
1781 The height of the last character added to the current environment.
1782 It is positive if the character extends above the baseline.
1785 The skew of the last character added to the current environment.
1788 of a character is how far to the right of the center of a character
1789 the center of an accent over that character should be placed.
1792 The name or number of the current environment.
1793 This is a string-valued register.
1796 The current font family.
1797 This is a string-valued register.
1800 The number of the next free font position.
1804 Macros should use this to determine whether they are running
1808 The current hyphenation language as set by the
1813 The number of immediately preceding consecutive hyphenated lines.
1816 The maximum allowed number of consecutive hyphenated lines, as set by the
1821 The current hyphenation flags (as set by the
1826 The current hyphenation margin (as set by the
1831 The current hyphenation space (as set by the
1836 The indent that applies to the current output line.
1839 Set to a positive value if last output line is interrupted (i.e., if it
1845 if pairwise kerning is enabled,
1850 The current ligature mode (as set by the
1855 The current line-tabs mode (as set by the
1860 The line length that applies to the current output line.
1863 The title length as set by the
1868 The amount of space that was needed in the last
1870 request that caused a trap to be sprung.
1871 Useful in conjunction with the
1877 if no-space mode is active,
1882 The number of the next page:
1883 either the value set by a
1885 request, or the number of the current page plus 1.
1888 The current pointsize in scaled points.
1891 The last-requested pointsize in scaled points.
1894 The number of lines to be right-justified as set by the
1899 The last requested pointsize in points as a decimal fraction.
1900 This is a string-valued register.
1903 A string representation of the current tab settings suitable for use as
1909 The amount of vertical space truncated by the most recently sprung
1910 vertical position trap, or,
1911 if the trap was sprung by a
1914 minus the amount of vertical motion produced by the
1917 In other words, at the point a trap is sprung, it represents the difference
1918 of what the vertical position would have been but for the trap,
1919 and what the vertical position actually is.
1920 Useful in conjunction with the
1927 These give the values of the parameters set by the
1928 first and second arguments of the
1933 1 if vertical position traps are enabled, 0 otherwise.
1936 The sum of the numbers associated with each of the currently enabled
1938 The number associated with each warning is listed in the `Warnings'
1942 The major version number.
1943 For example, if the version number is
1951 The minor version number.
1952 For example, if the version number is
1960 The revision number of groff.
1969 These four registers are set by the
1971 request and contain the bounding box values (in PostScript units) of a given
1974 The following read/write registers are set by the
1985 registers, but takes account of the heights and depths of characters.
1988 The amount of horizontal space (possibly negative) that should
1989 be added to the last character before a subscript.
1992 How far to right of the center of the last character
1996 the center of an accent from a roman font should be placed over that character.
1998 Other available read/write number registers are:
2001 The current input line number.
2003 is a read-only alias to this register.
2006 The current horizontal position at input line.
2009 The return value of the system() function executed by the last
2014 If greater than 0, the maximum number of objects on the input stack.
2015 If less than or equal to 0, there is no limit on the number of objects
2016 on the input stack. With no limit, recursion can continue until
2017 virtual memory is exhausted.
2021 Note that the traditional
2025 is the current year minus 1900.
2030 predefines a single (read/write) string-based register,
2032 which contains the argument given to the
2034 command line option, namely the current output device (for example,
2038 Note that this is not the same as the (read-only) number register
2040 which is defined to be\ 1 if
2044 command line option, and zero otherwise. This behaviour is different to
2047 Fonts not listed in the
2049 file are automatically mounted on the next available font position
2050 when they are referenced.
2051 If a font is to be mounted explicitly with the
2053 request on an unused font position,
2054 it should be mounted on the first unused font position,
2055 which can be found in the
2060 does not enforce this strictly,
2061 it will not allow a font to be mounted at a position whose number is much
2062 greater than that of any currently used position.
2064 Interpolating a string does not hide existing macro arguments.
2065 Thus in a macro, a more efficient way of doing
2073 If the font description file contains pairwise kerning information,
2074 characters from that font will be kerned.
2075 Kerning between two characters can be inhibited by placing a
2079 In a string comparison in a condition,
2080 characters that appear at different input levels
2081 to the first delimiter character will not be recognised
2082 as the second or third delimiters.
2083 This applies also to the
2089 a character that appears at a different input level to
2090 the starting delimiter character will not be recognised
2091 as the closing delimiter character.
2092 When decoding a macro argument that is delimited
2093 by double quotes, a character that appears at a different
2094 input level to the starting delimiter character will not
2095 be recognised as the closing delimiter character.
2096 The implementation of
2098 ensures that the double quotes surrounding an argument
2099 will appear the same input level, which will be different
2100 to the input level of the argument itself.
2101 In a long escape name
2103 will not be recognized as a closing delimiter except
2104 when it occurs at the same input level as the opening
2106 In compatibility mode, no attention is paid to the input-level.
2108 There are some new types of condition:
2111 True if there is a number register named
2115 True if there is a string, macro, diversion, or request named
2119 True if there is a character
2126 or a special character
2130 the condition will also be true if
2132 has been defined by the
2138 request can now map characters onto
2143 The warnings that can be given by
2145 are divided into the following categories.
2146 The name associated with each warning is used by the
2151 the number is used by the
2156 .nr x \w'\fBright-brace'+1n+\w'0000'u
2160 Non-existent characters.
2161 This is enabled by default.
2164 Invalid numeric expressions.
2165 This is enabled by default.
2168 In fill mode, lines which could not be broken so that their length was
2169 less than the line length.
2170 This is enabled by default.
2173 Missing or mismatched closing delimiters.
2178 request with no matching
2183 Meaningless scaling indicators.
2186 Out of range arguments.
2189 Dubious syntax in numeric expressions.
2196 without an argument when there is no current diversion.
2199 Use of undefined strings, macros and diversions.
2200 When an undefined string, macro or diversion is used,
2201 that string is automatically defined as empty.
2202 So, in most cases, at most one warning will be given for
2206 Use of undefined number registers.
2207 When an undefined number register is used,
2208 that register is automatically defined to have a value of 0.
2209 a definition is automatically made with a value of 0.
2210 So, in most cases, at most one warning will be given for
2211 use of a particular name.
2214 Inappropriate use of a tab character.
2215 Either use of a tab character where a number was expected,
2216 or use of tab character in an unquoted macro argument.
2218 .BR right-brace \t4096
2221 where a number was expected.
2224 Requests that are missing non-optional arguments.
2227 Illegal input characters.
2230 Unrecognized escape sequences.
2231 When an unrecognized escape sequence is encountered,
2232 the escape character is ignored.
2235 Missing space between a request or macro and its argument.
2236 This warning will be given
2237 when an undefined name longer than two characters is encountered,
2238 and the first two characters of the name make a defined name.
2239 The request or macro will not be invoked.
2240 When this warning is given, no macro is automatically defined.
2241 This is enabled by default.
2242 This warning will never occur in compatibility mode.
2246 This is enabled by default.
2249 Illegal escapes in text ignored with the
2252 These are conditions that are errors when they do not occur
2255 There are also names that can be used to refer to groups of warnings:
2263 It is intended that this covers all warnings
2264 that are useful with traditional macro packages.
2269 .SS Incompatibilities
2272 Long names cause some incompatibilities.
2273 UNIX troff will interpret
2278 as defining a string
2282 Normally, GNU troff will interpret this as a call of a macro named
2284 Also UNIX troff will interpret
2288 as references to a string or number register called
2290 In GNU troff, however, this will normally be interpreted as the start
2293 .I compatibility mode
2294 GNU troff will interpret these things in the traditional way.
2295 In compatibility mode, however, long names are not recognised.
2296 Compatibility mode can be turned on with the
2298 command line option, and turned on or off with the
2303 is 1 if compatibility mode is on, 0 otherwise.
2306 does not allow the use of the escape sequences
2307 .BR \\e\e|\e^\e&\e}\e{\e (space) \e'\e`\e-\e_\e!\e%\ec
2308 in names of strings, macros, diversions, number registers,
2309 fonts or environments; UNIX troff does.
2312 escape sequence may be helpful in avoiding use of these
2313 escape sequences in names.
2315 Fractional pointsizes cause one noteworthy incompatibility.
2318 request ignores scale indicators and so
2322 will set the pointsize to 10 points, whereas in
2323 GNU troff it will set the pointsize to 10 scaled points.
2325 In GNU troff there is a fundamental difference between unformatted,
2326 input characters, and formatted, output characters.
2327 Everything that affects how an output character
2328 will be output is stored with the character; once an output
2329 character has been constructed it is unaffected by any subsequent
2330 requests that are executed, including
2338 Normally output characters are constructed from input
2339 characters at the moment immediately before the character
2340 is added to the current output line.
2341 Macros, diversions and strings are all, in fact, the same type
2342 of object; they contain lists of input characters and output
2343 characters in any combination.
2344 An output character does not behave like an input character
2345 for the purposes of macro processing; it does not inherit any
2346 of the special properties that the input character from which it
2347 was constructed might have had.
2365 is turned into one output
2367 and the resulting output
2369 are not interpreted as escape characters when they are reread.
2370 UNIX troff would interpret them as escape characters
2371 when they were reread and would end up printing one
2373 The correct way to obtain a printable
2377 escape sequence: this will always print a single instance of the
2378 current escape character, regardless of whether or not it is used in a
2379 diversion; it will also work in both GNU troff and UNIX troff.
2380 If you wish for some reason to store in a diversion an escape
2381 sequence that will be interpreted when the diversion is reread,
2382 you can either use the traditional
2384 transparent output facility, or, if this is unsuitable, the new
2395 A colon separated list of directories in which to search for
2398 will scan directories given in
2401 option before these, and in standard directories (current directory if in
2402 unsafe mode, home directory,
2403 .BR /usr/share/groff/site-tmac ,
2404 .BR /usr/lib/groff/site-tmac ,
2405 .BR /usr/share/groff/1.17.2/tmac )
2414 A colon separated list of directories in which to search for the
2418 will scan directories given in the
2420 option before these, and in standard directories
2421 .RB ( /usr/share/groff/1.17.2/font:/usr/lib/font )
2428 .Tp \w'/usr/share/groff/1.17.2/font/devname/DESC'u+3n
2429 .B /usr/share/groff/1.17.2/tmac/troffrc
2430 Initialization file (called before any other macro package).
2432 .B /usr/share/groff/1.17.2/tmac/troffrc-end
2433 Initialization file (called after any other macro package).
2435 .BI /usr/share/groff/1.17.2/tmac/ name .tmac
2437 .BI /usr/share/groff/1.17.2/tmac/tmac. name
2440 .BI /usr/share/groff/1.17.2/font/dev name /DESC
2441 Device description file for device
2444 .BI /usr/share/groff/1.17.2/font/dev name / F
2454 are neither searched in the current nor in the home directory by default for
2455 security reasons (even if the
2460 command line option or the
2462 environment variable to add these directories to the search path if
2470 -- This is a short but complete reference of all requests, registers, and
2489 .\" Local Variables: