2 .\" The above line should force the use of eqn as a preprocessor
6 Last update : 6 Jan 2002
8 This file is part of groff, the GNU roff type-setting system.
9 It is the source of the man-page groff_diff(7).
11 Copyright (C) 1989, 2001, 2002 Free Software Foundation, Inc.
12 written by James Clark
14 modified by Werner Lemberg <wl@gnu.org>
15 Bernd Warken <bwarken@mayn.de>
17 Permission is granted to copy, distribute and/or modify this document
18 under the terms of the GNU Free Documentation License, Version 1.1 or
19 any later version published by the Free Software Foundation; with the
20 Invariant Sections being this .ig-section and AUTHORS, with no
21 Front-Cover Texts, and with no Back-Cover Texts.
23 A copy of the Free Documentation License is included as a file called
24 FDL in the main directory of the groff source package.
27 .\" --------------------------------------------------------------------
29 .\" --------------------------------------------------------------------
43 .\" define a string tx for the TeX logo
44 .ie t .ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
48 .\" --------------------------------------------------------------------
49 .\" start of macro definitions
57 .\" Don't use .ne for TTY devices
72 .\" Text \[oq]\f[CB]\*[@arg1]\f[P]\[cq]\$*
73 . Text \[oq]\f[B]\*[@arg1]\f[P]\[cq]\$*
76 .\" A shell command line
79 . IR "shell#" "\h'1m'\f[CB]\$*\f[P]\/"
81 .\" reference of a request or macro
85 .\" Text \f[CB]\*[@arg1]\f[P]\$*
86 . Text \f[B]\*[@arg1]\f[P]\$*
91 .\" representation of an escape sequence
95 .\" Text \f[CB]\[rs]\*[@arg1]\f[P]\$*
96 . Text \f[B]\[rs]\*[@arg1]\f[P]\$*
100 .\" end of macro definitions
102 .\" from old groff_out.man
109 .\" --------------------------------------------------------------------
111 .\" --------------------------------------------------------------------
113 .TH GROFF_DIFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
115 groff_diff \- differences between GNU troff and classical troff
118 .\" --------------------------------------------------------------------
120 .\" --------------------------------------------------------------------
122 This manual page describes the language differences between
126 text processing system and the classical
128 formatter of the freely available Unix\~7 of the 1970s, documented in
130 .I Troff User's Manual
135 This inludes the roff language as well as the intermediate output
136 format (troff output).
141 gives pointers to both the classical
148 At the moment, this document is the place of the most actual
149 documentation within the
153 This might change in the future.
155 Actually, all novelties of the groff language are first described here
156 and will pervade into the other documents only at a later stage.
159 .\" --------------------------------------------------------------------
161 .\" --------------------------------------------------------------------
163 In this section, all additional features of
165 compared to the classical Unix\~7
167 are described in detail.
170 .\" --------------------------------------------------------------------
172 .\" --------------------------------------------------------------------
174 The names of number registers, fonts, strings/\:macros/\:diversions,
175 special characters, and colors can be of any length.
177 In escape sequences, additionally to the classical
179 construction for a two character name, you can use
181 for a name of arbitrary length, for example in
183 .TP \w'\[rs]f[xxx]'u+3n
185 Print the special character called
200 Interpolate number register
204 .\" --------------------------------------------------------------------
205 .SS "Fractional pointsizes"
206 .\" --------------------------------------------------------------------
218 There is a new scale indicator
220 that has the effect of multiplying by sizescale.
222 Requests and escape sequences in troff interpret arguments that
223 represent a pointsize as being in units of scaled points, but they
224 evaluate each such argument using a default scale indicator of
226 Arguments treated in this way are the argument to the
228 request, the third argument to the
230 request, the second and fourth arguments to the
232 request, the argument to the
234 escape sequence, and those variants of the
236 escape sequence that take a numeric expression as their argument.
239 For example, suppose sizescale is 1000; then a scaled point will be
240 equivalent to a millipoint; the call
244 and so sets the pointsize to 10250 scaled points, which is equal to
250 returns the pointsize in points as decimal fraction.
252 There is also a new number register
254 that returns the pointsize in scaled points.
257 It would make no sense to use the
259 scale indicator in a numeric expression whose default scale indicator
268 Similarly it would make no sense to use a scaling indicator other than
272 in a numeric expression whose default scale indicator was
276 disallows this as well.
279 There is also new scale indicator\~\c
281 which multiplies by the number of units in a scaled point.
287 Be sure not to confuse the
294 .\" --------------------------------------------------------------------
295 .SS "Numeric expressions"
296 .\" --------------------------------------------------------------------
298 Spaces are permitted in a number expression within parentheses.
302 indicates a scale of 100ths of an em.
304 indicates a scale of 65536 units, providing fractions for color
309 For example, 0.5f = 32768u.
331 as the default scaling indicator.
335 is missing, ignore scaling indicators in the evaluation of
339 .\" --------------------------------------------------------------------
340 .SS "New escape sequences"
341 .\" --------------------------------------------------------------------
344 .BI \[rs]A' anything '
349 resp., depending on whether
351 is or is not acceptable as the name of a string, macro, diversion, number
352 register, environment, font, or color.
359 This is useful if you want to lookup user input in some sort of
363 .BI \[rs]B' anything '
368 resp., depending on whether
370 is or is not a valid numeric expression.
380 Typeset character named
382 Normally it is more convenient to use
383 .BI \[rs][ xxx ]\f[R].
386 has the advantage that it is compatible with recent versions of
388 and is available in compatibility mode.
392 This is equivalent to an escape character, but it is not interpreted in
395 For example, strings to start and end superscripting could be defined
401 .Text .ds { \[rs]v'\-.3m'\[rs]s'\[rs]En[.s]*6u/10u'
403 .Text .ds } \[rs]s0\[rs]v'.3m'
409 ensures that these definitions will work even if
411 gets interpreted in copy-mode (for example, by being used in a macro
423 switches back to the previous color.
431 Set background color for filled objects drawn with the
432 .BI \[rs]D' .\|.\|. '
435 switches back to the previous color.
439 Typeset the character with code
445 Most devices only have characters with codes between 0 and 255.
447 If the current font does not contain a character with that code,
454 escape sequence can be conveniently used in conjunction with the
461 .Text .char \[rs][phone] \[rs]f(ZD\[rs]N'37'
466 The code of each character is given in the fourth column in the font
467 description file after the
471 It is possible to include unnamed characters in the font description
472 file by using a name of
476 escape sequence is the only way to use these.
480 Suppressing troff output.
488 are intended for internal use by
494 Disable any ditroff glyphs from being emitted to the device driver,
495 provided that the escape occurs at the outer level (see
502 Enable output of glyphs, provided that the escape occurs at the outer
508 also reset the registers
516 These four registers mark the top left and bottom right hand corners
517 of a box which encompasses all written glyphs.
521 Provided that the escape occurs at the outer level, enable output of
522 glyphs and also write out to stderr the page number and four registers
523 encompassing the glyphs previously written since the last call to
528 Begin a nesting level.
530 This is really an internal mechanism for
532 while producing images.
534 They are generated by running the troff source through troff to the
535 postscript device and ghostscript to produce images in PNG format.
538 escape will start a new page if the device is not html (to reduce the
539 possibility of images crossing a page boundary).
545 .BI \[rs]O5[ Pfilename ]
550 Provided that this escape occurs at the outer nesting level, write
554 The position of the image,
556 must be specified and must be one of l, r, c or i (left, right,
559 will be associated with the production of the next inline image.
563 .BI \[rs]R' name\ \[+-]n '
564 This has the same effect as
568 .BI .nr\ name\ \[+-]n
575 Set the point size to
579 must be exactly two digits.
589 Set the point size to
593 is a numeric expression with a default scale indicator of\~\c
602 Interpolate the contents of the environment variable
607 is interpreted in copy-mode.
615 This is approximately equivalent to
616 .BI \[rs]X'\[rs]*[ xxx ]'\f[R].
617 However the contents of the string or macro
619 are not interpreted; also it is permitted for
621 to have been defined as a macro and thus contain newlines (it is not
622 permitted for the argument to
624 to contain newlines).
626 The inclusion of newlines requires an extension to the UNIX troff
627 output format, and will confuse drivers that do not know about this
631 .BI \[rs]Z' anything '
632 Print anything and then restore the horizontal and vertical position;
634 may not contain tabs or leaders.
638 The name by which the current macro was invoked.
642 request can make a macro have more than one name.
646 In a macro, the concatenation of all the arguments separated by spaces.
650 In a macro, the concatenation of all the arguments with each
651 surrounded by double quotes, and separated by spaces.
657 In a macro, this gives the
663 Macros can have an unlimited number of arguments.
666 .BI \[rs]? anything \[rs]?
667 When used in a diversion, this will transparently embed
671 is read in copy mode.
673 When the diversion is reread,
677 may not contain newlines; use
679 if you want to embed newlines in a diversion.
683 is also recognised in copy mode and turned into a single internal
684 code; it is this code that terminates
696 .Text \[rs]?\[rs]\[rs]?\[rs]\[rs]\[rs]\[rs]?\[rs]\[rs]\[rs]\[rs]\[rs]\[rs]\[rs]\c
697 .Text \[rs]nx\[rs]\[rs]\[rs]\[rs]?\[rs]\[rs]?\[rs]?
719 This increases the width of the preceding character so that the
720 spacing between that character and the following character will be
721 correct if the following character is a roman character.
724 . nop For example, if an italic f is immediately followed by a roman
725 . nop right parenthesis, then in many fonts the top right portion of
726 . nop the f will overlap the top left of the right parenthesis
727 . nop producing \f[I]f\f[R])\f[R], which is ugly.
731 . ie \n(.g \f[I]f\/\f[R])\f[R]
732 . el \f[I]f\|\f[R])\f[R]
733 . nop and avoids this problem.
735 It is a good idea to use this escape sequence whenever an italic
736 character is immediately followed by a roman character without any
741 This modifies the spacing of the following character so that the
742 spacing between that character and the preceding character will
743 correct if the preceding character is a roman character.
746 . nop For example, inserting
748 . nop between the parenthesis and the f changes
749 . nop \f[R](\f[I]f\f[R] to
750 . ie \n(.g \f[R](\,\f[I]f\f[R].
751 . el \f[R](\^\f[I]f\f[R].
753 It is a good idea to use this escape sequence whenever a roman
754 character is immediately followed by an italic character without any
761 except that it behaves like a character declared with the
763 request to be transparent for the purposes of end-of-sentence
768 This produces an unbreakable space that stretches like a normal
769 inter-word space when a line is adjusted.
773 This causes the insertion of a zero-width break point.
777 within a word but without insertion of a soft hyphen character.
781 Everything up to and including the next newline is ignored.
783 This is interpreted in copy mode.
789 does not ignore the terminating newline.
792 .\" --------------------------------------------------------------------
794 .\" --------------------------------------------------------------------
800 for number register object named
802 The new name and the old name will be exactly equivalent.
806 is undefined, a warning of type
808 will be generated, and the request will be ignored.
814 for request, string, macro, or diversion object named
817 The new name and the old name will be exactly equivalent (it is
818 similar to a hard rather than a soft link).
822 is undefined, a warning of type
824 will be generated, and the request will be ignored.
834 requests only create a new object if the name of the macro, diversion
835 or string diversion is currently undefined or if it is defined to be a
836 request; normally they modify the value of an existing object.
840 Append to macro indirectly.
844 request below for more information.
850 but compatibility mode is switched off during execution.
852 To be more precise, a `compatibility save' token is inserted at the
853 beginning of the macro addition, and a `compatibility restore' token at
856 As a consequence, the requests
862 can be intermixed freely since the compatibility save/\:restore tokens
863 only affect the macro parts defined by
870 This request `unformats' the diversion
874 and space characters (and some escape sequences) that were formatted
877 will be treated like ordinary input characters when
880 Useful for diversions in conjunction with the
884 It can be also used for gross hacks; for example, this
904 will set register\~\c
908 Note that glyph information (font, font size, etc.) is not preserved;
917 but compatibility mode is switched off during expansion.
919 To be more precise, a `compatibility save' token is inserted at the
920 beginning of the string, and a `compatibility restore' token at the end.
922 As a consequence, the requests
928 can be intermixed freely since the compatibility save/\:restore tokens
929 only affect the (sub)strings defined by
936 Print a backtrace of the input stack on stderr.
940 Set the blank line macro to
942 If there is a blank line macro, it will be invoked when a blank line
943 is encountered instead of the usual troff behaviour.
949 These requests are similar to the
953 requests with the exception that a partially filled line will not
954 become part of the diversion (i.e., the diversion always starts with a
955 new line) but restored after ending the diversion, discarding the
956 partially filled line which possibly comes from the diversion.
960 Break out of a while loop.
968 Be sure not to confuse this with the
978 .BI .cflags\ n\ c1\ c2\|.\|.\|.\&
982 have properties determined by
984 which is ORed from the following:
988 The character ends sentences (initially characters
993 Lines can be broken before the character (initially no characters have
994 this property); a line will not be broken at a character with this
995 property unless the characters on each side both have non-zero
999 Lines can be broken after the character (initially characters
1000 .B \-\[rs](hy\[rs](em
1001 have this property); a line will not be broken at a character with
1002 this property unless the characters on each side both have non-zero
1006 The character overlaps horizontally (initially characters
1007 .B \[rs](ul\[rs](rn\[rs](ru
1008 have this property).
1011 The character overlaps vertically (initially character
1016 An end-of-sentence character followed by any number of characters with
1017 this property will be treated as the end of a sentence if followed by
1018 a newline or two spaces; in other words the character is transparent
1019 for the purposes of end-of-sentence recognition; this is the same as
1020 having a zero space factor in \*[tx] (initially characters
1021 .B \[dq]')]*\[rs](dg\[rs](rq
1022 have this property).
1026 .BI .char\ c\ string
1031 Every time character
1033 needs to be printed,
1035 will be processed in a temporary environment and the result will be
1036 wrapped up into a single object.
1038 Compatibility mode will be turned off and the escape character will be
1045 Any emboldening, constant spacing or track kerning will be applied to
1046 this object rather than to individual characters in
1049 A character defined by this request can be used just like a normal
1050 character provided by the output device.
1052 In particular other characters can be translated to it with the
1054 request; it can be made the leader character by the
1056 request; repeated patterns can be drawn with the character using the
1060 escape sequences; words containing the character can be hyphenated
1063 request is used to give the character a hyphenation code.
1065 There is a special anti-recursion feature: use of character within the
1066 character's definition will be handled like normal characters not
1069 A character definition can be removed with the
1075 Chop the last character off macro, string, or diversion
1077 This is useful for removing the newline from the end of diversions
1078 that are to be interpolated as strings.
1082 Close the stream named
1085 will no longer be an acceptable argument to the
1095 Finish the current iteration of a while loop.
1107 is non-zero or missing, enable compatibility mode, otherwise disable
1110 In compatibility mode, long names are not recognised, and the
1111 incompatibilities caused by long names do not arise.
1114 .BI .defcolor\ xxx\ scheme\ color_components
1117 can be one of the following values:
1123 (four components), and
1129 Color components can be given either as a hexadecimal string or as
1130 positive decimal integers in the range 0-65535.
1132 A hexadecimal string contains all color components concatenated; it
1133 must start with either
1137 The former specifies hex values in the range 0-255 (which are
1138 internally multiplied by\~257), the latter in the range 0-65535.
1140 Examples: #FFC0CB (pink), ##ffff0000ffff (magenta).
1142 A new scaling indicator\~\c
1144 has been introduced which multiplies its value by\~65536; this makes
1145 it convenient to specify color components as fractions in the range 0
1153 .Text .defcolor darkgreen rgb 0.1f 0.5f 0.2f
1161 is the default scaling indicator for the
1163 request, thus the above statement is equivalent to
1168 .Text .defcolor darkgreen rgb 0.1 0.5 0.2
1176 (which is device-specific) can't be redefined.
1178 It is possible that the default color for
1186 Define macro indirectly.
1188 The following example
1217 but compatibility mode is switched off during execution.
1219 On entry, the current compatibility mode is saved and restored at exit.
1225 with compatibility mode disabled.
1238 would have the same effect as
1247 except that it would work even if compatibility mode had been enabled.
1249 Note that the previous compatibility mode is restored before any files
1260 but compatibility mode is switched off during expansion.
1262 To be more precise, a `compatibility save' token is inserted at the
1263 beginning of the string, and a `compatibility restore' token at the end.
1267 Save current escape character.
1271 Restore escape character saved with
1273 Without a previous call to
1276 will be the new escape character.
1280 Copy the contents of environment
1282 to the current environment.
1284 No pushing or popping of environments will be done.
1288 Set the current font family to
1290 The current font family is part of the current environment.
1293 is missing, switch back to previous font family.
1295 The value at start-up is `T'.
1297 See the description of the
1299 request for more information on font families.
1302 .BI .fchar\ c\ string
1303 Define fallback character
1307 The syntax of this request is the same as the
1309 request; the only difference is that a character defined with
1311 hides the glyph with the same name in the current font, whereas a
1312 character defined with
1314 is checked only if the particular glyph isn't found in the current font.
1316 This test happens before checking special fonts.
1319 .BI .fspecial\ f\ s1\ s2\|.\|.\|.\&
1320 When the current font is
1325 will be special, that is, they will searched for characters not in
1328 Any fonts specified in the
1330 request will be searched after fonts specified in the
1340 Whenever a font named
1342 is referred to in an
1344 escape sequence, or in the
1360 is missing, or equal to
1364 will not be translated.
1367 .BI .hcode \ c1\ code1\ c2\ code2\|.\|.\|.\&
1368 Set the hyphenation code of character
1376 A hyphenation code must be a single input character (not a special
1377 character) other than a digit or a space.
1379 Initially each lower-case letter has a hyphenation code, which is
1380 itself, and each upper-case letter has a hyphenation code which is the
1381 lower-case version of itself.
1389 Set the current hyphenation language to
1391 Hyphenation exceptions specified with the
1393 request and hyphenation patterns specified with the
1395 request are both associated with the current hyphenation language.
1399 request is usually invoked by the
1405 Set the maximum number of consecutive hyphenated lines to\~\c
1409 is negative, there is no maximum.
1411 The default value is\~\-1.
1413 This value is associated with the current environment.
1415 Only lines output from an environment count towards the maximum
1416 associated with that environment.
1418 Hyphens resulting from
1420 are counted; explicit hyphens are not.
1424 Read hyphenation patterns from
1426 this will be searched for in the same way that
1428 is searched for when the
1430 option is specified.
1432 It should have the same format as the argument to the \[rs]patterns
1433 primitive in \*[tx]; the letters appearing in this file are interpreted
1434 as hyphenation codes.
1438 character in the patterns file introduces a comment that continues
1439 to the end of the line.
1441 The set of hyphenation patterns is associated with the current language
1448 request is usually invoked by the
1455 .I hyphenation margin
1458 when the current adjustment mode is not\~\c
1460 the line will not be hyphenated if the line is no more than
1464 The default hyphenation margin is\~0.
1466 The default scaling indicator for this request is\~\c
1468 The hyphenation margin is associated with the current environment.
1470 The current hyphenation margin is available in the
1477 .I hyphenation space
1480 when the current adjustment mode is\~\c
1482 don't hyphenate the line if the line can be justified by adding no
1485 extra space to each word space.
1487 The default hyphenation space is\~0.
1489 The default scaling indicator for this request is\~\c
1491 The hyphenation space is associated with the current environment.
1493 The current hyphenation space is available in the
1501 for which a line interrupted with
1503 counts as one input line.
1509 is non-zero or missing, enable pairwise kerning, otherwise disable it.
1512 .BI .length\ xx\ string
1513 Compute the length of
1515 and return it in the number register
1517 (which is not necessarily defined before).
1523 is non-zero or missing, enable line-tabs mode, otherwise disable it
1524 (which is the default).
1526 In line-tabs mode, tab distances are computed relative to the
1527 (current) output line.
1529 Otherwise they are taken relative to the input line.
1531 For example, the following
1538 .Text .ds x a\[rs]t\[rs]c
1539 .Text .ds y b\[rs]t\[rs]c
1558 In line-tabs mode, the same code gives
1566 Line-tabs mode is associated with the current environment; the
1567 read-only number register
1568 .B \\[rs]n[.linetabs]
1569 is set to\~1 if in line-tabs mode, and 0 otherwise.
1577 is searched for in the same directories as macro files for the the
1579 command line option.
1581 If the file name to be included has the form
1587 instead and vice versa.
1593 This is similar to `.if\ 1'.
1599 built-in condition true and the
1601 built-in condition false.
1603 This can be reversed using the
1608 .BI .open\ stream\ filename
1611 for writing and associate the stream named
1622 .BI .opena\ stream\ filename
1627 exists, append to it instead of truncating it.
1631 Print the names and contents of all currently defined number registers
1635 .BI .psbb \ filename
1636 Get the bounding box of a PostScript image
1638 This file must conform to Adobe's Document Structuring Conventions;
1639 the command looks for a
1641 comment to extract the bounding box values.
1643 After a successful call, the coordinates (in PostScript units) of the
1644 lower left and upper right corner can be found in the registers
1652 If some error has occurred, the four registers are set to zero.
1656 This behaves like the
1658 request except that input comes from the standard output of
1663 Print the names and positions of all traps (not including input line
1664 traps and diversion traps) on stderr.
1666 Empty slots in the page trap list are printed as well, because they
1667 can affect the priority of subsequently planted traps.
1670 .BI .rchar\ c1\ c2\|.\|.\|.\&
1671 Remove the definitions of characters
1674 This undoes the effect of a
1680 Within a macro, return immediately.
1682 No effect otherwise.
1688 Right justify the next
1692 Without an argument right justify the next input line.
1694 The number of lines to be right justified is available in the
1698 This implicitly does
1702 request implicitly does
1707 Rename number register
1714 Set the soft hyphen character to
1718 is omitted, the soft hyphen character will be set to the default
1720 The soft hyphen character is the character which will be inserted when
1721 a word is hyphenated at a line break.
1723 If the soft hyphen character does not exist in the font of the
1724 character immediately preceding a potential break point, then the line
1725 will not be broken at that point.
1727 Neither definitions (specified with the
1729 request) nor translations (specified with the
1731 request) are considered when finding the soft hyphen character.
1735 In a macro, shift the arguments by
1737 positions: argument\~\c
1743 will no longer be available.
1747 is missing, arguments will be shifted by\~1.
1749 Shifting by negative amounts is currently undefined.
1752 .BI .special\ s1\ s2\|.\|.\|.\&
1756 are special and will be searched for characters not in the current
1763 with font position\~\c
1765 A font position can be associated either with a font or with a style.
1767 The current font is the index of a font position and so is also either
1770 When it is a style, the font that is actually used is the font the
1771 name of which is the concatenation of the name of the current family
1772 and the name of the current style.
1774 For example, if the current font is\~1 and font position\~1 is
1775 associated with style\~\c
1777 and the current font family is\~\c
1783 If the current font is not a style, then the current family is ignored.
1792 are applied to a style, then they will instead be applied to the
1793 member of the current family corresponding to that style.
1795 The default family can be set with the
1803 file controls which font positions (if any) are initially associated
1804 with styles rather than fonts.
1807 .BI .substring\ xx\ n1\ [ n2 ]
1808 Replace the string in register
1810 with the substring defined by the indices
1814 The first character in the string has index one.
1818 is omitted, it is taken to be equal to the string's length.
1824 is negative or zero, it will be counted from the end of the string,
1827 The last character has index\~0, the character before the last
1828 character has index\~-1, etc.
1831 .BI .tkf\ f\ s1\ n1\ s2\ n2
1832 Enable track kerning for font
1834 When the current font is
1836 the width of every character will be increased by an amount between
1840 when the current point size is less than or equal to
1842 the width will be increased by
1844 when it is greater than or equal to
1846 the width will be increased by
1848 when the point size is greater than or equal to
1850 and less than or equal to
1852 the increase in width is a linear function of the point size.
1860 is read in copy mode and written on the standard error, but an initial
1863 is stripped off to allow initial blanks.
1869 but without writing a final newline.
1873 Transparently output the contents of file
1875 Each line is output as if preceded by
1877 however, the lines are not subject to copy-mode interpretation.
1879 If the file does not end with a newline, then a newline will be added.
1881 For example, you can define a macro\~\c
1883 containing the contents of file\~\c
1902 request, the file cannot contain characters such as
1904 that are not legal troff input characters.
1908 This is the same as the
1910 request except that the translations do not apply to text that is
1911 transparently throughput into a diversion with
1943 built-in condition false, and the
1945 built-in condition true.
1947 This undoes the effect of the
1953 This request `unformats' the diversion
1957 request, which tries to convert formatted elements of the diversion
1958 back to input tokens as much as possible,
1960 will only handle tabs and spaces between words (usually caused by
1961 spaces or newlines in the input) specially.
1963 The former are treated as if they were input tokens, and the latter
1964 are stretchable again.
1966 Note that the vertical size of lines is not preserved.
1968 Glyph information (font, font size, space width, etc.) is retained.
1970 Useful in conjunction with the
1978 Enable vertical position traps if
1980 is non-zero, disable them otherwise.
1982 Vertical position traps are traps set by the
1990 request are not vertical position traps.
1992 The parameter that controls whether vertical position traps are
1995 Initially vertical position traps are enabled.
2001 is the sum of the numbers associated with each warning that is to be
2002 enabled; all other warnings will be disabled.
2004 The number associated with each warning is listed in
2005 .BR @g@troff (@MAN1EXT@).
2009 will disable all warnings, and
2011 will disable all warnings except that about missing characters.
2015 is not given, all warnings will be enabled.
2018 .BI .while \ c\ anything
2025 can be any condition acceptable to an
2029 can comprise multiple lines if the first line starts with
2031 and the last line ends with
2040 .BI .write\ stream\ anything
2046 must previously have been the subject of an
2050 is read in copy mode;
2056 .BI .writem\ stream\ xx
2057 Write the contents of the macro or string
2062 must previously have been the subject of an
2066 is read in copy mode.
2069 .\" --------------------------------------------------------------------
2070 .SS "Extended requests"
2071 .\" --------------------------------------------------------------------
2075 When used in a diversion, this will embed in the diversion an object
2076 which, when reread, will cause the contents of
2078 to be transparently copied through to the output.
2080 In UNIX troff, the contents of
2082 is immediately copied through to the output regardless of whether
2083 there is a current diversion; this behaviour is so anomalous that it
2084 must be considered a bug.
2090 is not a number, this will switch to a named environment called
2092 The environment should be popped with a matching
2094 request without any arguments, just as for numbered environments.
2096 There is no limit on the number of named environments; they will be
2097 created the first time that they are referenced.
2101 When two arguments are given to the
2103 request, the second argument gives the
2104 .IR "sentence space size" .
2105 If the second argument is not given, the sentence space size
2106 will be the same as the word space size.
2108 Like the word space size, the sentence space is in units of
2109 one twelfth of the spacewidth parameter for the current font.
2111 Initially both the word space size and the sentence
2114 Contrary to UNIX troff, GNU troff handles this request in nroff mode
2115 also; a given value is then rounded down to the nearest multiple
2118 The sentence space size is used in two circumstances.
2120 If the end of a sentence occurs at the end of a line in fill mode,
2121 then both an inter-word space and a sentence space will be added; if
2122 two spaces follow the end of a sentence in the middle of a line, then
2123 the second space will be a sentence space.
2125 Note that the behaviour of UNIX troff will be exactly that exhibited
2126 by GNU troff if a second argument is never given to the
2130 In GNU troff, as in UNIX troff, you should always follow a sentence
2131 with either a newline or two spaces.
2134 .BI .ta\ n1\ n2\|.\|.\|.nn \ T\ r1\ r2\|.\|.\|.\|rn
2135 Set tabs at positions
2137 .IR n2 ,\|.\|.\|.\|,
2139 and then set tabs at
2141 .IR nn + r2 ,\|.\|.\|.\|,
2145 .IR nn + rn + r2 ,\|.\|.\|.\|,
2158 will set tabs every half an inch.
2162 .\" --------------------------------------------------------------------
2163 .SS "New number registers"
2164 .\" --------------------------------------------------------------------
2166 The following read-only registers are available:
2170 1\~if compatibility mode is in effect, 0\~otherwise.
2174 The depth of the last character added to the current environment.
2176 It is positive if the character extends below the baseline.
2180 The number of lines remaining to be centered, as set by the
2186 The height of the last character added to the current environment.
2188 It is positive if the character extends above the baseline.
2192 The skew of the last character added to the current environment.
2196 of a character is how far to the right of the center of a character
2197 the center of an accent over that character should be placed.
2201 The name or number of the current environment.
2203 This is a string-valued register.
2207 The current font family.
2209 This is a string-valued register.
2213 The current (internal) real font name.
2215 This is a string-valued register.
2217 If the current font is a style, the value of
2219 is the proper concatenation of family and style name.
2223 The number of the next free font position.
2229 Macros should use this to determine whether they are running under GNU
2234 The current hyphenation language as set by the
2240 The number of immediately preceding consecutive hyphenated lines.
2244 The maximum allowed number of consecutive hyphenated lines, as set by
2251 The current hyphenation flags (as set by the
2257 The current hyphenation margin (as set by the
2263 The current hyphenation space (as set by the
2269 The indent that applies to the current output line.
2273 Set to a positive value if last output line is interrupted (i.e., if
2279 1\~if pairwise kerning is enabled, 0\~otherwise.
2283 The current ligature mode (as set by the
2288 .B \[rs]n[.linetabs]
2289 The current line-tabs mode (as set by the
2295 The line length that applies to the current output line.
2299 The title length as set by the
2305 The amount of space that was needed in the last
2307 request that caused a trap to be sprung.
2309 Useful in conjunction with the
2315 1\~if no-space mode is active, 0\~otherwise.
2319 The number of the next page, either the value set by a
2321 request, or the number of the current page plus\~1.
2325 The current pointsize in scaled points.
2329 The last-requested pointsize in scaled points.
2333 The number of lines to be right-justified as set by the
2339 The last requested pointsize in points as a decimal fraction.
2341 This is a string-valued register.
2347 These give the values of the parameters set by the first and second
2354 A string representation of the current tab settings suitable for use
2355 as an argument to the
2361 The amount of vertical space truncated by the most recently sprung
2362 vertical position trap, or, if the trap was sprung by a
2364 request, minus the amount of vertical motion produced by the
2368 In other words, at the point a trap is sprung, it represents the
2369 difference of what the vertical position would have been but for the
2370 trap, and what the vertical position actually is.
2372 Useful in conjunction with the
2378 1\~if vertical position traps are enabled, 0\~otherwise.
2382 The sum of the numbers associated with each of the currently enabled
2385 The number associated with each warning is listed in
2386 .BR @g@troff (@MAN1EXT@).
2390 The major version number.
2392 For example, if the version number is 1.03, then
2398 The minor version number.
2400 For example, if the version number is 1.03, then
2406 The revision number of groff.
2416 These four registers are set by the
2418 request and contain the bounding box values (in PostScript units) of a
2419 given PostScript image.
2422 The following read/write registers are set by the
2434 registers, but take account of the heights and depths of characters.
2438 The amount of horizontal space (possibly negative) that should be
2439 added to the last character before a subscript.
2443 How far to right of the center of the last character in the
2445 argument, the center of an accent from a roman font should be placed
2446 over that character.
2449 Other available read/write number registers are:
2453 The current input line number.
2455 is a read-only alias to this register.
2459 The current horizontal position at input line.
2463 The return value of the system() function executed by the last
2469 If greater than\~0, the maximum number of objects on the input stack.
2471 If less than or equal to\~0, there is no limit on the number of
2472 objects on the input stack.
2474 With no limit, recursion can continue until virtual memory is
2481 Note that the traditional
2485 is the current year minus 1900.
2488 .\" --------------------------------------------------------------------
2490 .\" --------------------------------------------------------------------
2493 predefines a single (read/write) string-based register,
2495 which contains the argument given to the
2497 command line option, namely the current output device (for example,
2501 Note that this is not the same as the (read-only) number register
2503 which is defined to be\~1 if
2507 command line option, and zero otherwise.
2509 This behaviour is different to UNIX troff.
2512 Fonts not listed in the
2514 file are automatically mounted on the next available font position
2515 when they are referenced.
2517 If a font is to be mounted explicitly with the
2519 request on an unused font position, it should be mounted on the first
2520 unused font position, which can be found in the
2524 does not enforce this strictly, it will not allow a font to be mounted
2525 at a position whose number is much greater than that of any currently
2529 Interpolating a string does not hide existing macro arguments.
2531 Thus in a macro, a more efficient way of doing
2534 .BI . xx\ \[rs]\[rs]$@
2539 .BI \[rs]\[rs]*[ xx ]\[rs]\[rs]
2542 If the font description file contains pairwise kerning information,
2543 characters from that font will be kerned.
2545 Kerning between two characters can be inhibited by placing a
2550 In a string comparison in a condition, characters that appear at
2551 different input levels to the first delimiter character will not be
2552 recognised as the second or third delimiters.
2554 This applies also to the
2560 escape sequence, a character that appears at a different input level
2561 to the starting delimiter character will not be recognised as the
2562 closing delimiter character.
2564 The same is true for
2576 When decoding a macro argument that is delimited by double quotes, a
2577 character that appears at a different input level to the starting
2578 delimiter character will not be recognised as the closing delimiter
2581 The implementation of
2583 ensures that the double quotes surrounding an argument will appear the
2584 same input level, which will be different to the input level of the
2587 In a long escape name
2589 will not be recognized as a closing delimiter except when it occurs at
2590 the same input level as the opening
2593 In compatibility mode, no attention is paid to the input-level.
2596 There are some new types of condition:
2600 True if there is a number register named
2605 True if there is a string, macro, diversion, or request named
2610 True if there is a color named
2615 True if there is a character
2621 character or a special character
2624 .BI \[rs][ xxx ]\f[R];
2625 the condition will also be true if
2627 has been defined by the
2634 request can now map characters onto
2638 It is now possible to have whitespace between the first and second dot
2639 (or the name of the ending macro) to end a macro definition.
2648 .Text . nop Hello, I'm `foo'.
2649 .Text . nop I will now define `bar'.
2651 .Text . nop Hello, I'm `bar'.
2660 .\" --------------------------------------------------------------------
2661 .SH "INTERMEDIATE OUTPUT FORMAT"
2662 .\" --------------------------------------------------------------------
2664 This section describes the format output by GNU troff.
2666 The output format used by GNU troff is very similar to that used
2667 by Unix device-independent troff.
2669 Only the differences are documented here.
2672 .\" --------------------------------------------------------------------
2674 .\" --------------------------------------------------------------------
2678 command is in scaled points (units of
2682 is the argument to the
2684 command in the DESC file).
2688 command is also in scaled points.
2691 .\" --------------------------------------------------------------------
2693 .\" --------------------------------------------------------------------
2697 Print character with index\~\c
2699 (a non-negative integer) of the current font.
2704 line is present in the DESC file, troff will use the following two
2710 is any sequence of characters terminated by a space or a newline; the
2711 first character should be printed at the current position, the current
2712 horizontal position should be increased by the width of the first
2713 character, and so on for each character.
2715 The width of the character is that given in the font file,
2716 appropriately scaled for the current point size, and rounded so that
2717 it is a multiple of the horizontal resolution.
2719 Special characters cannot be printed using this command.
2725 command except that after printing each character, the current
2726 horizontal position is increased by the sum of the width of that
2731 Note that single characters can have the eighth bit set, as can the
2732 names of fonts and special characters.
2735 The names of characters and fonts can be of arbitrary length; drivers
2736 should not assume that they will be only two characters long.
2739 When a character is to be printed, that character will always be
2740 in the current font.
2742 Unlike device-independent troff, it is not necessary for drivers to
2743 search special fonts to find a character.
2746 For color support, some new commands have been added:
2749 .Text \f[B]mc \f[I]cyan magenta yellow\f[R]
2753 .Text \f[B]mg \f[I]gray\f[R]
2755 .Text \f[B]mk \f[I]cyan magenta yellow black\f[R]
2757 .Text \f[B]mr \f[I]red green blue\f[R]
2758 Set the color components of the current drawing color, using various
2762 resets the drawing color to the default value.
2764 The arguments are integers in the range 0 to 65536.
2769 device control command has been extended.
2772 .Text \f[B]x u \f[I]n\f[R]
2775 is\~1, start underlining of spaces.
2779 is\~0, stop underlining of spaces.
2781 This is needed for the
2783 request in nroff mode and is ignored otherwise.
2786 .\" --------------------------------------------------------------------
2787 .SS "Drawing Commands"
2788 .\" --------------------------------------------------------------------
2792 drawing command has been extended.
2794 These extensions will not be used by GNU pic if the
2799 .Text \f[B]Df \f[I]n\f[R]\*[ic]\[rs]n
2800 Set the shade of gray to be used for filling solid objects to
2803 must be an integer between 0 and 1000, where 0 corresponds solid white
2804 and 1000 to solid black, and values in between correspond to
2805 intermediate shades of gray.
2807 This applies only to solid circles, solid ellipses and solid
2810 By default, a level of 1000 will be used.
2812 Whatever color a solid object has, it should completely obscure
2813 everything beneath it.
2815 A value greater than 1000 or less than 0 can also be used: this means
2816 fill with the shade of gray that is currently being used for lines and
2819 Normally this will be black, but some drivers may provide a way of
2823 .Text \f[B]DC \f[I]d\f[R]\*[ic]\[rs]n
2824 Draw a solid circle with a diameter of
2826 with the leftmost point at the current position.
2829 .Text \f[B]DE \f[I]dx dy\f[R]\*[ic]\[rs]n
2830 Draw a solid ellipse with a horizontal diameter of
2832 and a vertical diameter of
2834 with the leftmost point at the current position.
2840 .Text \f[B]Dp\f[R] $dx sub 1$ $dy sub 1$ $dx sub 2$ $dy sub 2$ $...$ $dx sub n$ $dy sub n$\[rs]n
2841 Draw a polygon with, for $i = 1 ,..., n+1$, the
2843 vertex at the current position
2845 $+ sum from j=1 to i-1 ( dx sub j , dy sub j )$.
2847 At the moment, GNU pic only uses this command to generate triangles
2851 .Text \f[B]DP\f[R] $dx sub 1$ $dy sub 1$ $dx sub 2$ $dy sub 2$ $...$ $dx sub n$ $dy sub n$\[rs]n
2855 but draw a solid rather than outlined polygon.
2858 .Text \f[B]Dt \f[I]n\f[R]\*[ic]\[rs]n
2859 Set the current line thickness to
2863 Traditionally Unix troff drivers use a line thickness proportional to
2864 the current point size; drivers should continue to do this if no
2866 command has been given, or if a
2868 command has been given with a negative value of
2872 selects the smallest available line thickness.
2875 A difficulty arises in how the current position should be changed after
2876 the execution of these commands.
2878 This is not of great importance since the code generated by GNU pic
2879 does not depend on this.
2881 Given a drawing command of the form
2883 \f[B]\[rs]D\[fm]\f[I]c\f[R] $x sub 1$ $y sub 1$ $x sub 2$ $y sub 2$ $...$ $x sub n$ $y sub n$\[fm]
2895 Unix troff will treat each of the $x sub i$ as a horizontal quantity,
2896 and each of the $y sub i$ as a vertical quantity and will assume that
2897 the width of the drawn object is $sum from i=1 to n x sub i$,
2898 and that the height is $sum from i=1 to n y sub i$.
2900 (The assumption about the height can be seen by examining the
2904 registers after using such a
2906 command in a \[rs]w escape sequence).
2908 This rule also holds for all the original drawing commands with the
2911 For the sake of compatibility GNU troff also follows this rule, even
2912 though it produces an ugly result in the case of the
2914 and, to a lesser extent,
2918 Thus after executing a
2922 \f[B]D\f[I]c\f[R] $x sub 1$ $y sub 1$ $x sub 2$ $y sub 2$ $...$ \c
2923 $x sub n$ $y sub n$\[rs]n
2926 the current position should be increased by
2928 $( sum from i=1 to n x sub i , sum from i=1 to n y sub i )$.
2931 Another set of extensions is
2934 .Text \f[B]DFc \f[I]cyan magenta yellow\f[R]\*[ic]\[rs]n
2936 .Text \f[B]DFd\f[R]\*[ic]\[rs]n
2938 .Text \f[B]DFg \f[I]gray\f[R]\*[ic]\[rs]n
2940 .Text \f[B]DFk \f[I]cyan magenta yellow black\f[R]\*[ic]\[rs]n
2942 .Text \f[B]DFr \f[I]red green blue\f[R]\*[ic]\[rs]n
2943 Set the color components of the filling color similar to the
2952 The current position isn't changed by those colour commands.
2955 .\" --------------------------------------------------------------------
2956 .SS "Device Control Commands"
2957 .\" --------------------------------------------------------------------
2959 There is a continuation convention which permits the argument to the
2961 command to contain newlines: when outputting the argument to the
2963 command, GNU troff will follow each newline in the argument with a
2965 character (as usual, it will terminate the entire argument with a
2966 newline); thus if the line after the line containing the
2970 then the newline ending the line containing the
2972 command should be treated as part of the argument to the
2976 should be ignored, and the part of the line following the
2978 should be treated like the part of the line following the
2983 The first three output commands are guaranteed to be:
2992 .\" --------------------------------------------------------------------
2993 .SH INCOMPATIBILITIES
2994 .\" --------------------------------------------------------------------
2996 In spite of the many extensions, groff has retained compatibility to
2997 classical troff to a large degree.
2999 For the cases where the extensions lead to collisions, a special
3000 compatibility mode with the restricted, old functionality was created
3004 .\" --------------------------------------------------------------------
3005 .SS "Groff Language"
3006 .\" --------------------------------------------------------------------
3010 .B compatibility mode
3011 that allows to process roff code written for classical
3013 or for other implementations of roff in a consistent way.
3016 Compatibility mode can be turned on with the
3018 command line option, and turned on or off with the
3024 is\~1 if compatibility mode is on, 0\~otherwise.
3027 This became necessary because the GNU concept for long names causes
3028 some incompatibilities.
3035 as defining a string
3041 mode, this will be considered as a call of a macro named
3051 as references to a string or number register called
3055 takes this as the start of a long name.
3059 .IR "compatibility mode" ,
3060 groff interprets these things in the traditional way; so long
3061 names are not recognized.
3064 On the other hand, groff in
3066 does not allow to use the single-character escapes
3095 (character c) in names of strings, macros, diversions, number
3096 registers, fonts or environments, whereas
3103 escape sequence can be helpful in avoiding these escape sequences in
3107 Fractional pointsizes cause one noteworthy incompatibility.
3114 request ignores scale indicators and so
3121 will set the pointsize to 10\~points, whereas in groff native mode the
3122 pointsize will be set to 10\~scaled points.
3127 mode, there is a fundamental difference between unformatted input
3128 characters, and formatted output characters.
3130 Everything that affects how an output character will be output is
3131 stored with the character; once an output character has been
3132 constructed it is unaffected by any subsequent requests that are
3133 executed, including the
3143 Normally output characters are constructed from input characters at
3144 the moment immediately before the character is added to the current
3147 Macros, diversions and strings are all, in fact, the same type of
3148 object; they contain lists of input characters and output characters
3152 An output character does not behave like an input character for the
3153 purposes of macro processing; it does not inherit any of the special
3154 properties that the input character from which it was constructed
3157 The following example will make things clearer.
3164 .Text \[rs]\[rs]\[rs]\[rs]
3175 this will be printed as
3177 So each pair of input backslashes
3179 is turned into a single output backslash
3181 and the resulting output backslashes are not interpreted as escape
3182 characters when they are reread.
3186 would interpret them as escape characters when they were reread and
3187 would end up printing a single backslash
3191 In GNU, the correct way to get a printable version of the backslash
3196 escape sequence, but classical troff does not provide a clean feature
3197 for getting a non-syntactical backslash.
3199 A close method is the printable version of the current escape
3202 escape sequence; this works if the current escape character is not
3205 It works in both GNU mode and compatibility mode, while dirty tricks
3206 like specifying a sequence of multiple backslashes do not work
3207 reliably; for the different handling in diversions, macro definitions,
3208 or text mode quickly leads to a confusion about the necessary number of
3212 To store an escape sequence in a diversion that will be interpreted
3213 when the diversion is reread, either the traditional
3215 transparent output facility or the
3218 escape sequence can be used.
3221 .\" --------------------------------------------------------------------
3222 .SS "Intermediate Output"
3223 .\" --------------------------------------------------------------------
3225 The groff intermediate output format is in a state of evolution.
3227 So far it has some incompatibilities, but it is intended to establish
3228 a full compatibility to the classical troff output format.
3230 Actually the following incompatibilities exist:
3233 The positioning after the drawing of the polygons conflicts with the
3234 classical definition.
3237 The intermediate output cannot be rescaled to other devices as
3238 classical "device-independent" troff did.
3241 .\" --------------------------------------------------------------------
3243 .\" --------------------------------------------------------------------
3245 Copyright (C) 1989, 2001, 2002 Free Software Foundation, Inc.
3248 This document is distributed under the terms of the FDL (GNU Free
3249 Documentation License) version 1.1 or later.
3251 You should have received a copy of the FDL on your system, it is also
3252 available on-line at the
3253 .URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" .
3255 This document was written by James Clark, with modifications by
3256 .MTO wl@gnu.org "Werner Lemberg"
3258 .MTO bwarken@mayn.de "Bernd Warken" .
3261 This document is part of
3263 the GNU roff distribution.
3265 Formerly, the contents of this document was kept in the manual
3267 .BR @g@troff (@MAN1EXT@).
3268 Only the parts dealing with the language aspects of the different
3270 systems were carried over into this document.
3274 command line options and warnings are still documented in
3275 .BR @g@troff (@MAN1EXT@).
3277 .\" --------------------------------------------------------------------
3279 .\" --------------------------------------------------------------------
3286 presents all groff documentation within a single document.
3289 .BR groff (@MAN1EXT@)
3290 A list of all documentation around
3294 .BR groff (@MAN7EXT@)
3295 A description of the
3297 language, including a short, but complete reference of all predefined
3298 requests, registers, and escapes of plain
3300 From the command line, this is called using
3303 .ShellCommand man\~7\~groff
3306 .BR roff (@MAN7EXT@)
3309 systems, including pointers to further historical documentation.
3314 .I Nroff/\:Troff User's Manual
3317 of 1976 in the revision of
3320 .URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:54.ps.gz \
3321 "classical troff documentation" .
3324 .\" --------------------------------------------------------------------
3326 .\" --------------------------------------------------------------------
3328 .\" Local Variables: