2 .\" The above line should force the use of eqn as a preprocessor
6 Last update : 26 Oct 2006
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, 2003, 2004, 2006
12 Free Software Foundation, Inc.
13 written by James Clark
15 modified by Werner Lemberg <wl@gnu.org>
16 Bernd Warken <bwarken@mayn.de>
18 Permission is granted to copy, distribute and/or modify this document
19 under the terms of the GNU Free Documentation License, Version 1.1 or
20 any later version published by the Free Software Foundation; with the
21 Invariant Sections being this .ig-section and AUTHORS, with no
22 Front-Cover Texts, and with no Back-Cover Texts.
24 A copy of the Free Documentation License is included as a file called
25 FDL in the main directory of the groff source package.
28 .\" --------------------------------------------------------------------
30 .\" --------------------------------------------------------------------
32 .do nr groff_diff_C \n[.C]
47 .\" define a string tx for the TeX logo
48 .ie t .ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
52 .\" --------------------------------------------------------------------
53 .\" start of macro definitions
75 .\" Text \[oq]\f[CB]\*[@arg1]\f[]\[cq]\$*
76 . Text \[oq]\f[B]\*[@arg1]\f[]\[cq]\$*
79 .c A shell command line
82 . IR "shell#" "\h'1m'\f[CB]\$*\f[]\/"
84 .c reference of a request or macro
88 .\" Text \f[CB]\*[@arg1]\f[]\$*
89 . Text \f[B]\*[@arg1]\f[]\$*
94 .c representation of an escape sequence
98 .\" Text \f[CB]\[rs]\*[@arg1]\f[]\$*
99 . Text \f[B]\[rs]\*[@arg1]\&\f[]\$*
103 .\" end of macro definitions
105 .\" from old groff_out.man
112 .\" --------------------------------------------------------------------
114 .\" --------------------------------------------------------------------
116 .TH GROFF_DIFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
118 groff_diff \- differences between GNU troff and classical troff
121 .\" --------------------------------------------------------------------
123 .\" --------------------------------------------------------------------
125 This manual page describes the language differences between
129 text processing system and the classical
131 formatter of the freely available Unix\~7 of the 1970s, documented in
133 .I Troff User's Manual
138 This inludes the roff language as well as the intermediate output
139 format (troff output).
144 gives pointers to both the classical
151 .\" --------------------------------------------------------------------
153 .\" --------------------------------------------------------------------
155 In this section, all additional features of
157 compared to the classical Unix\~7
159 are described in detail.
162 .\" --------------------------------------------------------------------
164 .\" --------------------------------------------------------------------
166 The names of number registers, fonts, strings/\:macros/\:diversions,
167 special characters (glyphs), and colors can be of any length.
169 In escape sequences, additionally to the classical
171 construction for a two-character name, you can use
173 for a name of arbitrary length.
177 Print the special character (glyph) called
181 .BI \[rs][ "comp1 comp2 .\|.\|." ]
182 Print composite glyph consisting of multiple components.
184 Example: `\[rs][A\~ho]' is capital letter A with ogonek which finally maps
185 to glyph name `u0041_0328'.
189 for details how a glyph name for a composite glyph is constructed, and
190 .BR groff_char (@MAN7EXT@)
191 for list of glyph name components used composite glyph names.
200 is a new syntax equal to
202 i.e., to return to the previous font.
205 .BI \[rs]*[ "xxx arg1 arg2 .\|.\|." ]
216 Interpolate number register
220 .\" --------------------------------------------------------------------
221 .SS "Fractional pointsizes"
222 .\" --------------------------------------------------------------------
234 There is a new scale indicator
236 that has the effect of multiplying by sizescale.
238 Requests and escape sequences in troff interpret arguments that
239 represent a pointsize as being in units of scaled points, but they
240 evaluate each such argument using a default scale indicator of
242 Arguments treated in this way are the argument to the
244 request, the third argument to the
246 request, the second and fourth arguments to the
248 request, the argument to the
250 escape sequence, and those variants of the
252 escape sequence that take a numeric expression as their argument.
255 For example, suppose sizescale is 1000; then a scaled point is
256 equivalent to a millipoint; the call
260 and so sets the pointsize to 10250 scaled points, which is equal to
266 returns the pointsize in points as decimal fraction.
268 There is also a new number register
270 that returns the pointsize in scaled points.
273 It would make no sense to use the
275 scale indicator in a numeric expression whose default scale indicator
284 Similarly it would make no sense to use a scaling indicator other than
288 in a numeric expression whose default scale indicator was
292 disallows this as well.
295 There is also new scale indicator\~\c
297 which multiplies by the number of units in a scaled point.
303 Be sure not to confuse the
310 .\" --------------------------------------------------------------------
311 .SS "Numeric expressions"
312 .\" --------------------------------------------------------------------
314 Spaces are permitted in a number expression within parentheses.
318 indicates a scale of 100ths of an em.
320 indicates a scale of 65536 units, providing fractions for color
325 For example, 0.5f = 32768u.
347 as the default scaling indicator.
351 is missing, ignore scaling indicators in the evaluation of
355 .\" --------------------------------------------------------------------
356 .SS "New escape sequences"
357 .\" --------------------------------------------------------------------
360 .BI \[rs]A' anything '
365 resp., depending on whether
367 is or is not acceptable as the name of a string, macro, diversion, number
368 register, environment, font, or color.
375 This is useful if you want to lookup user input in some sort of
379 .BI \[rs]B' anything '
384 resp., depending on whether
386 is or is not a valid numeric expression.
398 Normally it is more convenient to use
399 .BI \[rs][ xxx ]\f[R].
402 has the advantage that it is compatible with recent versions of
404 and is available in compatibility mode.
408 This is equivalent to an escape character, but it is not interpreted in
411 For example, strings to start and end superscripting could be defined
417 .Text .ds { \[rs]v'\-.3m'\[rs]s'\[rs]En[.s]*6u/10u'
419 .Text .ds } \[rs]s0\[rs]v'.3m'
425 ensures that these definitions work even if
427 gets interpreted in copy-mode (for example, by being used in a macro
439 This is the same as the
444 switches back to the previous color (note that
446 won't work; it selects font family `P' instead).
456 switches back to the previous color.
464 Set background color for filled objects drawn with the
465 .BI \[rs]D' .\|.\|. '
468 switches back to the previous color.
472 Typeset the glyph with index
478 Most devices only have glyphs with indices between 0 and 255.
480 If the current font does not contain a glyph with that code,
487 escape sequence can be conveniently used in conjunction with the
494 .Text .char \[rs][phone] \[rs]f(ZD\[rs]N'37'
499 The index of each glyph is given in the fourth column in the font
500 description file after the
504 It is possible to include unnamed glyphs in the font description
505 file by using a name of
509 escape sequence is the only way to use these.
515 Suppressing troff output.
523 are intended for internal use by
529 Disable any ditroff glyphs from being emitted to the device driver,
530 provided that the escape occurs at the outer level (see
537 Enable output of glyphs, provided that the escape occurs at the outer
543 also reset the registers
551 These four registers mark the top left and bottom right hand corners
552 of a box which encompasses all written glyphs.
556 Provided that the escape occurs at the outer level, enable output of
557 glyphs and also write out to stderr the page number and four registers
558 encompassing the glyphs previously written since the last call to
563 Begin a nesting level.
569 This is really an internal mechanism for
571 while producing images.
573 They are generated by running the troff source through
575 to the postscript device and
577 to produce images in PNG format.
581 escape starts a new page if the device is not html (to reduce the
582 possibility of images crossing a page boundary).
589 .BI \[rs]O5[ Pfilename ]
594 Provided that this escape occurs at the outer nesting level, write
598 The position of the image,
600 must be specified and must be one of l, r, c, or i (left, right,
604 is associated with the production of the next inline image.
608 .BI \[rs]R' name\ \[+-]n '
609 This has the same effect as
613 .BI .nr\ name\ \[+-]n
620 Set the point size to
624 must be exactly two digits.
634 Set the point size to
638 is a numeric expression with a default scale indicator of\~\c
647 Interpolate the contents of the environment variable
652 is interpreted in copy-mode.
660 This is approximately equivalent to
661 .BI \[rs]X'\[rs]*[ xxx ]'\f[R].
662 However the contents of the string or macro
664 are not interpreted; also it is permitted for
666 to have been defined as a macro and thus contain newlines (it is not
667 permitted for the argument to
669 to contain newlines).
671 The inclusion of newlines requires an extension to the UNIX troff
672 output format, and confuses drivers that do not know about this
676 .BI \[rs]Z' anything '
677 Print anything and then restore the horizontal and vertical position;
679 may not contain tabs or leaders.
683 The name by which the current macro was invoked.
687 request can make a macro have more than one name.
691 In a macro or string, the concatenation of all the arguments separated
696 In a macro or string, the concatenation of all the arguments with each
697 surrounded by double quotes, and separated by spaces.
701 In a macro, the representation of all parameters as if they were an
710 In a macro or string, this gives the
716 Macros and strings can have an unlimited number of arguments.
719 .BI \[rs]? anything \[rs]?
720 When used in a diversion, this transparently embeds
724 is read in copy mode.
726 When the diversion is reread,
730 may not contain newlines; use
732 if you want to embed newlines in a diversion.
736 is also recognised in copy mode and turned into a single internal
737 code; it is this code that terminates
749 .Text \[rs]?\[rs]\[rs]?\[rs]\[rs]\[rs]\[rs]?\[rs]\[rs]\[rs]\[rs]\[rs]\[rs]\[rs]\c
750 .Text \[rs]nx\[rs]\[rs]\[rs]\[rs]?\[rs]\[rs]?\[rs]?
772 This increases the width of the preceding glyph so that the
773 spacing between that glyph and the following glyph is
774 correct if the following glyph is a roman glyph.
777 . nop For example, if an italic f is immediately followed by a roman
778 . nop right parenthesis, then in many fonts the top right portion of
779 . nop the f overlaps the top left of the right parenthesis
780 . nop producing \f[I]f\f[R])\f[R], which is ugly.
784 . ie \n(.g \f[I]f\/\f[R])\f[R]
785 . el \f[I]f\|\f[R])\f[R]
786 . nop and avoids this problem.
788 It is a good idea to use this escape sequence whenever an italic
789 glyph is immediately followed by a roman glyph without any
794 This modifies the spacing of the following glyph so that the
795 spacing between that glyph and the preceding glyph is
796 correct if the preceding glyph is a roman glyph.
799 . nop For example, inserting
801 . nop between the parenthesis and the f changes
802 . nop \f[R](\f[I]f\f[R] to
803 . ie \n(.g \f[R](\,\f[I]f\f[R].
804 . el \f[R](\^\f[I]f\f[R].
806 It is a good idea to use this escape sequence whenever a roman
807 glyph is immediately followed by an italic glyph without any
814 except that it behaves like a character declared with the
816 request to be transparent for the purposes of end-of-sentence
821 This produces an unbreakable space that stretches like a normal
822 inter-word space when a line is adjusted.
826 This causes the insertion of a zero-width break point.
830 within a word but without insertion of a soft hyphen character.
834 Everything up to and including the next newline is ignored.
836 This is interpreted in copy mode.
842 does not ignore the terminating newline.
845 .\" --------------------------------------------------------------------
847 .\" --------------------------------------------------------------------
853 for number register object named
855 The new name and the old name are exactly equivalent.
859 is undefined, a warning of type
861 is generated, and the request is ignored.
867 for request, string, macro, or diversion object named
870 The new name and the old name are exactly equivalent (it is
871 similar to a hard rather than a soft link).
875 is undefined, a warning of type
877 is generated, and the request is ignored.
887 requests only create a new object if the name of the macro, diversion
888 or string diversion is currently undefined or if it is defined to be a
889 request; normally they modify the value of an existing object.
895 but compatibility mode is switched off during execution.
897 To be more precise, a `compatibility save' token is inserted at the
898 beginning of the macro addition, and a `compatibility restore' token at
901 As a consequence, the requests
907 can be intermixed freely since the compatibility save/\:restore tokens
908 only affect the macro parts defined by
915 Append to macro indirectly.
919 request below for more information.
925 request but compatibility mode is switched off during execution.
931 but compatibility mode is switched off during expansion.
933 To be more precise, a `compatibility save' token is inserted at the
934 beginning of the string, and a `compatibility restore' token at the end.
936 As a consequence, the requests
942 can be intermixed freely since the compatibility save/\:restore tokens
943 only affect the (sub)strings defined by
950 This request `unformats' the diversion
954 and space characters (and some escape sequences) that were formatted
957 are treated like ordinary input characters when
960 Useful for diversions in conjunction with the
964 It can be also used for gross hacks; for example, this
988 Note that glyph information (font, font size, etc.) is not preserved;
995 Print a backtrace of the input stack on stderr.
999 Set the blank line macro to
1001 If there is a blank line macro, it is invoked when a blank line
1002 is encountered instead of the usual troff behaviour.
1008 These requests are similar to the
1012 requests with the exception that a partially filled line does not
1013 become part of the diversion (i.e., the diversion always starts with a
1014 new line) but restored after ending the diversion, discarding the
1015 partially filled line which possibly comes from the diversion.
1019 Break out of a while loop.
1027 Be sure not to confuse this with the
1037 .BI .cflags\ n\ c1\ c2\|.\|.\|.\&
1041 have properties determined by
1043 which is ORed from the following:
1047 The character ends sentences (initially characters
1049 have this property).
1052 Lines can be broken before the character (initially no characters have
1053 this property); a line is not broken at a character with this
1054 property unless the characters on each side both have non-zero
1056 This can be overridden with value 64.
1059 Lines can be broken after the character (initially characters
1060 .B \-\[rs][hy]\[rs][em]
1061 have this property); a line is not broken at a character with
1062 this property unless the characters on each side both have non-zero
1064 This can be overridden with value 64.
1067 The character overlaps horizontally (initially characters
1068 .B \[rs][ul]\[rs][rn]\[rs][ru]\[rs][radicalex]\[rs][sqrtex]
1069 have this property).
1072 The character overlaps vertically (initially character
1077 An end-of-sentence character followed by any number of characters with
1078 this property is treated as the end of a sentence if followed by
1079 a newline or two spaces; in other words the character is transparent
1080 for the purposes of end-of-sentence recognition; this is the same as
1081 having a zero space factor in \*[tx] (initially characters
1082 .B \[dq]')]*\[rs](dg\[rs](rq
1083 have this property).
1086 Ignore hyphenation code values of the surrounding characters.
1087 Use this in combination with values 2 and\~4 (initially no characters have
1092 .BI .char\ c\ string
1099 needs to be printed,
1101 is processed in a temporary environment and the result is
1102 wrapped up into a single object.
1104 Compatibility mode is turned off and the escape character is
1111 Any emboldening, constant spacing or track kerning is applied to
1112 this object rather than to individual glyphs in
1116 A glyph defined by this request can be used just like a normal
1117 glyph provided by the output device.
1119 In particular other characters can be translated to it with the
1121 request; it can be made the leader character by the
1123 request; repeated patterns can be drawn with the character using the
1127 escape sequences; words containing the character can be hyphenated
1130 request is used to give the character a hyphenation code.
1133 There is a special anti-recursion feature: Use of glyph within the
1134 glyph's definition is handled like normal glyphs not
1138 A glyph definition can be removed with the
1144 Chop the last element off macro, string, or diversion
1146 This is useful for removing the newline from the end of diversions
1147 that are to be interpolated as strings.
1151 Close the stream named
1154 will no longer be an acceptable argument to the
1163 .BI .composite\ glyph1\ glyph2
1170 with more than one component.
1174 Finish the current iteration of a while loop.
1186 is non-zero or missing, enable colors (this is the default), otherwise
1193 is non-zero or missing, enable compatibility mode, otherwise disable
1196 In compatibility mode, long names are not recognised, and the
1197 incompatibilities caused by long names do not arise.
1200 .BI .defcolor\ xxx\ scheme\ color_components
1203 can be one of the following values:
1209 (four components), and
1215 Color components can be given either as a hexadecimal string or as
1216 positive decimal integers in the range 0-65535.
1218 A hexadecimal string contains all color components concatenated; it
1219 must start with either
1223 The former specifies hex values in the range 0-255 (which are
1224 internally multiplied by\~257), the latter in the range 0-65535.
1226 Examples: #FFC0CB (pink), ##ffff0000ffff (magenta).
1228 A new scaling indicator\~\c
1230 has been introduced which multiplies its value by\~65536; this makes
1231 it convenient to specify color components as fractions in the range 0
1239 .Text .defcolor darkgreen rgb 0.1f 0.5f 0.2f
1247 is the default scaling indicator for the
1249 request, thus the above statement is equivalent to
1254 .Text .defcolor darkgreen rgb 0.1 0.5 0.2
1262 (which is device-specific) can't be redefined.
1264 It is possible that the default color for
1274 but compatibility mode is switched off during execution.
1276 On entry, the current compatibility mode is saved and restored at exit.
1280 Define macro indirectly.
1282 The following example
1311 request but compatibility mode is switched off during execution.
1314 .BI .device\ anything
1315 This is (almost) the same as the
1319 is read in copy mode; a leading\~\c
1325 This is the same as the
1327 escape (to embed the contents of a macro into the intermediate
1328 output preceded with `x\~X').
1334 with compatibility mode disabled.
1347 would have the same effect as
1356 except that it would work even if compatibility mode had been enabled.
1358 Note that the previous compatibility mode is restored before any files
1369 but compatibility mode is switched off during expansion.
1371 To be more precise, a `compatibility save' token is inserted at the
1372 beginning of the string, and a `compatibility restore' token at the end.
1376 Save current escape character.
1380 Restore escape character saved with
1382 Without a previous call to
1385 will be the new escape character.
1389 Copy the contents of environment
1391 to the current environment.
1393 No pushing or popping of environments is done.
1397 Set the current font family to
1399 The current font family is part of the current environment.
1402 is missing, switch back to previous font family.
1404 The value at start-up is `T'.
1406 See the description of the
1408 request for more information on font families.
1411 .BI .fchar\ c\ string
1412 Define fallback glyph
1417 The syntax of this request is the same as the
1419 request; the only difference is that a glyph defined with
1421 hides the glyph with the same name in the current font, whereas a
1424 is checked only if the particular glyph isn't found in the current font.
1426 This test happens before checking special fonts.
1430 Set the fill color to
1435 switch to the previous fill color.
1438 .BI .fschar\ f\ c\ string
1439 Define fallback glyph
1446 The syntax of this request is the same as the
1448 request (with an additional argument to specify the font); a glyph
1451 is searched after the list of fonts declared with the
1453 request but before the list of fonts declared with
1457 .BI .fspecial\ f\ s1\ s2\|.\|.\|.\&
1458 When the current font is
1463 are special, that is, they are searched for glyphs not in
1466 Any fonts specified in the
1468 request are searched after fonts specified in the
1472 Without argument, reset the list of global special fonts to be empty.
1480 Whenever a font named
1482 is referred to in an
1484 escape sequence, in the
1488 conditional operators, or in the
1504 is missing, or equal to
1517 must a non-negative integer multiple of 1/1000th.
1518 If it is missing or is equal to zero, it means the same as 1000, namely no
1521 \~must be a real font name, not a style.
1525 Set the glyph color to
1530 switch to the previous glyph color.
1533 .BI .hcode \ c1\ code1\ c2\ code2\|.\|.\|.\&
1534 Set the hyphenation code of character
1542 A hyphenation code must be a single input character (not a special
1543 character) other than a digit or a space.
1545 Initially each lower-case letter \%a-z has a hyphenation code, which is
1546 itself, and each upper-case letter \%A-Z has a hyphenation code which is
1547 the lower-case version of itself.
1555 Set the current hyphenation language to
1557 Hyphenation exceptions specified with the
1559 request and hyphenation patterns specified with the
1561 request are both associated with the current hyphenation language.
1565 request is usually invoked by the
1571 Set the maximum number of consecutive hyphenated lines to\~\c
1575 is negative, there is no maximum.
1577 The default value is\~\-1.
1579 This value is associated with the current environment.
1581 Only lines output from an environment count towards the maximum
1582 associated with that environment.
1584 Hyphens resulting from
1586 are counted; explicit hyphens are not.
1590 Read hyphenation patterns from
1592 this is searched for in the same way that
1594 is searched for when the
1596 option is specified.
1598 It should have the same format as (simple) \*[tx] patterns files.
1600 More specifically, the following scanning rules are implemented.
1604 A percent sign starts a comment (up to the end of the line) even if
1605 preceded by a backslash.
1608 No support for `digraphs' like
1616 (character code of\~\c
1618 in the range 0-127) are recognized; other use of
1627 checks for the expression
1628 .B \[rs]patterns{.\|.\|.}
1629 (possibly with whitespace before and after the braces).
1631 Everything between the braces is taken as hyphenation patterns.
1637 are not allowed in patterns.
1641 .B \[rs]hyphenation{.\|.\|.}
1642 gives a list of hyphenation exceptions.
1649 For backwards compatibility, if
1651 is missing, the whole file is treated as a list of hyphenation patterns
1652 (only recognizing the
1654 character as the start of a comment).
1660 request to map the encoding used in hyphenation patterns files to
1664 The set of hyphenation patterns is associated with the current language
1671 request is usually invoked by the
1673 file; a second call replaces the old patterns with the new ones.
1679 except that the hyphenation patterns from
1681 are appended to the patterns already loaded in the current language.
1684 .BI .hpfcode\ a\ b\ c\ d\ .\|.\|.
1685 After reading a hyphenation patterns file with the
1689 request, convert all characters with character code\~\c
1691 in the recently read patterns to character code\~\c
1699 Initially, all character codes map to themselves.
1703 must be integers in the range 0 to\~255.
1705 Note that it is even possible to use character codes which are invalid in
1712 .I hyphenation margin
1715 when the current adjustment mode is not\~\c
1717 the line is not hyphenated if the line is no more than
1721 The default hyphenation margin is\~0.
1723 The default scaling indicator for this request is\~\c
1725 The hyphenation margin is associated with the current environment.
1727 The current hyphenation margin is available in the
1734 .I hyphenation space
1737 when the current adjustment mode is\~\c
1739 don't hyphenate the line if the line can be justified by adding no
1742 extra space to each word space.
1744 The default hyphenation space is\~0.
1746 The default scaling indicator for this request is\~\c
1748 The hyphenation space is associated with the current environment.
1750 The current hyphenation space is available in the
1758 for which a line interrupted with
1760 counts as one input line.
1766 is non-zero or missing, enable pairwise kerning, otherwise disable it.
1769 .BI .length\ xx\ string
1770 Compute the length of
1772 and return it in the number register
1774 (which is not necessarily defined before).
1780 is non-zero or missing, enable line-tabs mode, otherwise disable it
1781 (which is the default).
1783 In line-tabs mode, tab distances are computed relative to the
1784 (current) output line.
1786 Otherwise they are taken relative to the input line.
1788 For example, the following
1795 .Text .ds x a\[rs]t\[rs]c
1796 .Text .ds y b\[rs]t\[rs]c
1815 In line-tabs mode, the same code gives
1823 Line-tabs mode is associated with the current environment; the
1824 read-only number register
1825 .B \\[rs]n[.linetabs]
1826 is set to\~1 if in line-tabs mode, and 0 otherwise.
1834 is searched for in the same directories as macro files for the the
1836 command line option.
1838 If the file name to be included has the form
1844 instead and vice versa.
1850 This is similar to `.if\ 1'.
1856 built-in condition true and the
1858 built-in condition false.
1860 This can be reversed using the
1865 .BI .open\ stream\ filename
1868 for writing and associate the stream named
1879 .BI .opena\ stream\ filename
1884 exists, append to it instead of truncating it.
1890 directly to the intermediate output (subject to copy-mode interpretation);
1893 used at the top level.
1895 An initial double quote in
1897 is stripped off to allow initial blanks.
1901 Print the current environment and each defined environment state on
1906 Print the names and contents of all currently defined number registers
1910 .BI .psbb \ filename
1911 Get the bounding box of a PostScript image
1913 This file must conform to Adobe's Document Structuring Conventions;
1914 the command looks for a
1916 comment to extract the bounding box values.
1918 After a successful call, the coordinates (in PostScript units) of the
1919 lower left and upper right corner can be found in the registers
1927 If some error has occurred, the four registers are set to zero.
1931 This behaves like the
1933 request except that input comes from the standard output of
1938 Print the names and positions of all traps (not including input line
1939 traps and diversion traps) on stderr.
1941 Empty slots in the page trap list are printed as well, because they
1942 can affect the priority of subsequently planted traps.
1946 Set the post-vertical line space to
1948 default scale indicator is\~\c
1951 This value is added to each line after it has been output.
1953 With no argument, the post-vertical line space is set to its previous
1957 The total vertical line spacing consists of four components:
1961 with a negative value which are applied before the line is output, and
1965 with a positive value which are applied after the line is output.
1968 .BI .rchar\ c1\ c2\|.\|.\|.\&
1969 Remove the definitions of glyphs
1972 This undoes the effect of a
1978 Within a macro, return immediately.
1980 If called with an argument, return twice, namely from the current macro and
1981 from the macro one level higher.
1983 No effect otherwise.
1986 .BI .rfschar\ c1\ c2\|.\|.\|.\&
1987 Remove the font-specific definitions of glyphs
1990 This undoes the effect of a
1998 Right justify the next
2002 Without an argument right justify the next input line.
2004 The number of lines to be right justified is available in the
2008 This implicitly does
2012 request implicitly does
2017 Rename number register
2023 .BI .schar\ c\ string
2024 Define global fallback glyph
2029 The syntax of this request is the same as the
2031 request; a glyph defined with
2033 is searched after the list of fonts declared with the
2035 request but before the mounted special fonts.
2039 Set the soft hyphen character to
2043 is omitted, the soft hyphen character is set to the default
2045 The soft hyphen character is the glyph which is inserted when
2046 a word is hyphenated at a line break.
2048 If the soft hyphen character does not exist in the font of the
2049 glyph immediately preceding a potential break point, then the line
2050 is not broken at that point.
2052 Neither definitions (specified with the
2054 request) nor translations (specified with the
2056 request) are considered when finding the soft hyphen character.
2060 In a macro, shift the arguments by
2062 positions: argument\~\c
2068 are no longer available.
2072 is missing, arguments are shifted by\~1.
2074 Shifting by negative amounts is currently undefined.
2077 .BI .sizes\ s1\ s2\|.\|.\|.\|sn\ [0]
2078 This command is similar to the
2084 It sets the available font sizes for the current font to
2086 .IR s2 ,\|.\|.\|.\|,\~ sn
2089 The list of sizes can be terminated by an optional\~\c
2094 can also be a range of sizes
2097 Contrary to the font file command, the list can't extend over more
2101 .BI .special\ s1\ s2\|.\|.\|.\&
2105 are special and are searched for glyphs not in the current
2108 Without arguments, reset the list of special fonts to be empty.
2111 .BI .spreadwarn\ limit
2114 emit a warning if the additional space inserted for each space between
2115 words in an output line is larger or equal to
2118 A negative value is changed to zero; no argument toggles the warning on
2119 and off without changing
2122 The default scaling indicator is\~\c
2132 .B .spreadwarn\ 0.2m
2135 must add 0.2m or more for each interword space in a line.
2137 This request is active only if text is justified to both margins (using
2144 with font position\~\c
2146 A font position can be associated either with a font or with a style.
2148 The current font is the index of a font position and so is also either
2151 When it is a style, the font that is actually used is the font the
2152 name of which is the concatenation of the name of the current family
2153 and the name of the current style.
2155 For example, if the current font is\~1 and font position\~1 is
2156 associated with style\~\c
2158 and the current font family is\~\c
2164 If the current font is not a style, then the current family is ignored.
2173 are applied to a style, then they are applied instead to the
2174 member of the current family corresponding to that style.
2176 The default family can be set with the
2184 file controls which font positions (if any) are initially associated
2185 with styles rather than fonts.
2188 .BI .substring\ xx\ n1\ [ n2 ]
2189 Replace the string named
2191 with the substring defined by the indices
2195 The first character in the string has index\~0.
2199 is omitted, it is taken to be equal to the string's length.
2205 is negative, it is counted from the end of the string,
2208 The last character has index\~-1, the character before the last
2209 character has index\~-2, etc.
2212 .BI .tkf\ f\ s1\ n1\ s2\ n2
2213 Enable track kerning for font
2215 When the current font is
2217 the width of every glyph is increased by an amount between
2221 when the current point size is less than or equal to
2223 the width is increased by
2225 when it is greater than or equal to
2227 the width is increased by
2229 when the point size is greater than or equal to
2231 and less than or equal to
2233 the increase in width is a linear function of the point size.
2241 is read in copy mode and written on the standard error, but an initial
2244 is stripped off to allow initial blanks.
2250 but without writing a final newline.
2254 Transparently output the contents of file
2256 Each line is output as if preceded by
2258 however, the lines are not subject to copy-mode interpretation.
2260 If the file does not end with a newline, then a newline is added.
2262 For example, you can define a macro\~\c
2264 containing the contents of file\~\c
2283 request, the file cannot contain characters such as
2285 that are not valid troff input characters.
2289 This is the same as the
2291 request except that the
2293 request uses the character code (if any) before the character
2326 This is the same as the
2328 request except that the translations do not apply to text that is
2329 transparently throughput into a diversion with
2361 built-in condition false, and the
2363 built-in condition true.
2365 This undoes the effect of the
2371 This request `unformats' the diversion
2375 request, which tries to convert formatted elements of the diversion
2376 back to input tokens as much as possible,
2378 only handles tabs and spaces between words (usually caused by
2379 spaces or newlines in the input) specially.
2381 The former are treated as if they were input tokens, and the latter
2382 are stretchable again.
2384 Note that the vertical size of lines is not preserved.
2386 Glyph information (font, font size, space width, etc.) is retained.
2388 Useful in conjunction with the
2396 Enable vertical position traps if
2398 is non-zero, disable them otherwise.
2400 Vertical position traps are traps set by the
2408 request are not vertical position traps.
2410 The parameter that controls whether vertical position traps are
2413 Initially vertical position traps are enabled.
2419 is the sum of the numbers associated with each warning that is to be
2420 enabled; all other warnings are disabled.
2422 The number associated with each warning is listed in
2423 .BR @g@troff (@MAN1EXT@).
2427 disables all warnings, and
2429 disables all warnings except that about missing glyphs.
2433 is not given, all warnings are enabled.
2437 Set the scaling indicator used in warnings to
2450 At startup, it is set to\~\c
2454 .BI .while \ c\ anything
2461 can be any condition acceptable to an
2465 can comprise multiple lines if the first line starts with
2467 and the last line ends with
2476 .BI .write\ stream\ anything
2482 must previously have been the subject of an
2486 is read in copy mode;
2492 .BI .writec\ stream\ anything
2495 but without writing a final newline.
2498 .BI .writem\ stream\ xx
2499 Write the contents of the macro or string
2504 must previously have been the subject of an
2508 is read in copy mode.
2511 .\" --------------------------------------------------------------------
2512 .SS "Extended escape sequences"
2513 .\" --------------------------------------------------------------------
2516 .BI \[rs]D' .\|.\|. '
2517 All drawing commands of groff's intermediate output are accepted.
2520 .B "Drawing Commands"
2521 below for more information.
2524 .\" --------------------------------------------------------------------
2525 .SS "Extended requests"
2526 .\" --------------------------------------------------------------------
2530 When used in a diversion, this embeds in the diversion an object
2531 which, when reread, will cause the contents of
2533 to be transparently copied through to the output.
2535 In UNIX troff, the contents of
2537 is immediately copied through to the output regardless of whether
2538 there is a current diversion; this behaviour is so anomalous that it
2539 must be considered a bug.
2549 In compatibility mode, these requests behaves similar to
2555 respectively: A `compatibility save' token is inserted at the
2556 beginning, and a `compatibility restore' token at the end, with
2557 compatibility mode switched on during execution.
2563 is not a number, this switches to a named environment called
2565 The environment should be popped with a matching
2567 request without any arguments, just as for numbered environments.
2569 There is no limit on the number of named environments; they are
2570 created the first time that they are referenced.
2574 When two arguments are given to the
2576 request, the second argument gives the
2577 .IR "sentence space size" .
2578 If the second argument is not given, the sentence space size
2579 is the same as the word space size.
2581 Like the word space size, the sentence space is in units of
2582 one twelfth of the spacewidth parameter for the current font.
2584 Initially both the word space size and the sentence
2587 Contrary to UNIX troff, GNU troff handles this request in nroff mode
2588 also; a given value is then rounded down to the nearest multiple
2591 The sentence space size is used in two circumstances.
2593 If the end of a sentence occurs at the end of a line in fill mode,
2594 then both an inter-word space and a sentence space are added; if
2595 two spaces follow the end of a sentence in the middle of a line, then
2596 the second space is a sentence space.
2598 Note that the behaviour of UNIX troff are exactly that exhibited
2599 by GNU troff if a second argument is never given to the
2603 In GNU troff, as in UNIX troff, you should always follow a sentence
2604 with either a newline or two spaces.
2607 .BI .ta\ n1\ n2\|.\|.\|.nn \ T\ r1\ r2\|.\|.\|.\|rn
2608 Set tabs at positions
2610 .IR n2 ,\|.\|.\|.\|,
2612 and then set tabs at
2614 .IR nn + r2 ,\|.\|.\|.\|,
2618 .IR nn + rn + r2 ,\|.\|.\|.\|,
2631 sets tabs every half an inch.
2635 .\" --------------------------------------------------------------------
2636 .SS "New number registers"
2637 .\" --------------------------------------------------------------------
2639 The following read-only registers are available:
2643 Within a macro call, it is set to\~1 if the macro is called with the
2644 `normal' control character (`.' by default), and set to\~0 otherwise.
2645 This allows to reliably modify requests.
2652 .Text .als bp*orig bp
2655 .Text .ie \[rs]\[rs]n[.br] .bp*orig
2663 Using this register outside of a macro makes no sense (it always returns
2664 zero in such cases).
2668 1\~if compatibility mode is in effect, 0\~otherwise.
2672 The depth of the last glyph added to the current environment.
2674 It is positive if the glyph extends below the baseline.
2678 The number of lines remaining to be centered, as set by the
2684 The height of the last glyph added to the current environment.
2686 It is positive if the glyph extends above the baseline.
2690 1\~if colors are enabled, 0\~otherwise.
2694 The skew of the last glyph added to the current environment.
2698 of a glyph is how far to the right of the center of a glyph
2699 the center of an accent over that glyph should be placed.
2703 The name or number of the current environment.
2705 This is a string-valued register.
2709 The current font family.
2711 This is a string-valued register.
2715 The current (internal) real font name.
2717 This is a string-valued register.
2719 If the current font is a style, the value of
2721 is the proper concatenation of family and style name.
2725 The number of the next free font position.
2731 Macros should use this to determine whether they are running under GNU
2736 The current height of the font as set with
2741 The current hyphenation language as set by the
2747 The number of immediately preceding consecutive hyphenated lines.
2751 The maximum allowed number of consecutive hyphenated lines, as set by
2758 The current hyphenation flags (as set by the
2764 The current hyphenation margin (as set by the
2770 The current hyphenation space (as set by the
2776 The indent that applies to the current output line.
2780 Set to a positive value if last output line is interrupted (i.e., if
2786 1\~if pairwise kerning is enabled, 0\~otherwise.
2790 The current ligature mode (as set by the
2795 .B \[rs]n[.linetabs]
2796 The current line-tabs mode (as set by the
2802 The line length that applies to the current output line.
2806 The title length as set by the
2812 The name of the current drawing color.
2814 This is a string-valued register.
2818 The name of the current background color.
2820 This is a string-valued register.
2824 The amount of space that was needed in the last
2826 request that caused a trap to be sprung.
2828 Useful in conjunction with the
2834 1\~if no-space mode is active, 0\~otherwise.
2838 1\~during a page ejection caused by the
2840 request, 0\~otherwise.
2844 The number of the next page, either the value set by a
2846 request, or the number of the current page plus\~1.
2850 The current pointsize in scaled points.
2854 The last-requested pointsize in scaled points.
2858 The current post-vertical line space as set with the
2864 The number of lines to be right-justified as set by the
2870 The slant of the current font as set with
2875 The last requested pointsize in points as a decimal fraction.
2877 This is a string-valued register.
2883 These give the values of the parameters set by the first and second
2890 The current font style.
2892 This is a string-valued register.
2896 A string representation of the current tab settings suitable for use
2897 as an argument to the
2903 The amount of vertical space truncated by the most recently sprung
2904 vertical position trap, or, if the trap was sprung by a
2906 request, minus the amount of vertical motion produced by the
2910 In other words, at the point a trap is sprung, it represents the
2911 difference of what the vertical position would have been but for the
2912 trap, and what the vertical position actually is.
2914 Useful in conjunction with the
2920 Set to 1 if in safer mode and to 0 if in unsafe mode (as given with the
2922 command line option).
2926 1\~if vertical position traps are enabled, 0\~otherwise.
2930 The sum of the numbers associated with each of the currently enabled
2933 The number associated with each warning is listed in
2934 .BR @g@troff (@MAN1EXT@).
2938 The major version number.
2940 For example, if the version number is 1.03, then
2946 The minor version number.
2948 For example, if the version number is 1.03, then
2954 The revision number of groff.
2958 The zoom value of the current font, in multiples of 1/1000th.
2959 Zero if no magnification.
2969 These four registers are set by the
2971 request and contain the bounding box values (in PostScript units) of a
2972 given PostScript image.
2975 The following read/write registers are set by the
2987 registers, but take account of the heights and depths of glyphs.
2991 The amount of horizontal space (possibly negative) that should be
2992 added to the last glyph before a subscript.
2996 How far to right of the center of the last glyph in the
2998 argument, the center of an accent from a roman font should be placed
3002 Other available read/write number registers are:
3006 The current input line number.
3008 is a read-only alias to this register.
3012 The number of hours past midnight.
3014 Initialized at start-up.
3018 The current horizontal position at input line.
3022 The number of minutes after the hour.
3024 Initialized at start-up.
3028 The number of seconds after the minute.
3030 Initialized at start-up.
3034 The return value of the system() function executed by the last
3040 If greater than\~0, the maximum number of objects on the input stack.
3042 If less than or equal to\~0, there is no limit on the number of
3043 objects on the input stack.
3045 With no limit, recursion can continue until virtual memory is
3052 Note that the traditional
3056 is the current year minus 1900.
3059 .\" --------------------------------------------------------------------
3061 .\" --------------------------------------------------------------------
3064 predefines a single (read/write) string-based register,
3066 which contains the argument given to the
3068 command line option, namely the current output device (for example,
3072 Note that this is not the same as the (read-only) number register
3074 which is defined to be\~1 if
3078 command line option, and zero otherwise.
3080 This behaviour is different to UNIX troff.
3083 Fonts not listed in the
3085 file are automatically mounted on the next available font position
3086 when they are referenced.
3088 If a font is to be mounted explicitly with the
3090 request on an unused font position, it should be mounted on the first
3091 unused font position, which can be found in the
3095 does not enforce this strictly, it does not allow a font to be mounted
3096 at a position whose number is much greater than that of any currently
3100 Interpolating a string does not hide existing macro arguments.
3102 Thus in a macro, a more efficient way of doing
3105 .BI . xx\ \[rs]\[rs]$@
3110 .BI \[rs]\[rs]*[ xx ]\[rs]\[rs]
3113 If the font description file contains pairwise kerning information,
3114 glyphs from that font are kerned.
3116 Kerning between two glyphs can be inhibited by placing a
3121 In a string comparison in a condition, characters that appear at
3122 different input levels to the first delimiter character are not
3123 recognised as the second or third delimiters.
3125 This applies also to the
3131 escape sequence, a character that appears at a different input level
3132 to the starting delimiter character is not recognised as the
3133 closing delimiter character.
3135 The same is true for
3147 When decoding a macro or string argument that is delimited by double
3148 quotes, a character that appears at a different input level to the starting
3149 delimiter character is not recognised as the closing delimiter
3152 The implementation of
3154 ensures that the double quotes surrounding an argument appear at the
3155 same input level, which is different to the input level of the
3158 In a long escape name
3160 is not recognized as a closing delimiter except when it occurs at
3161 the same input level as the opening
3164 In compatibility mode, no attention is paid to the input-level.
3167 There are some new types of condition:
3171 True if there is a number register named
3176 True if there is a string, macro, diversion, or request named
3181 True if there is a color named
3186 True if there is a glyph
3192 character or a glyph (special character)
3193 .BI \[rs]N' xxx '\f[R],
3196 .BI \[rs][ xxx ]\f[R];
3197 the condition is also true if
3199 has been defined by the
3210 is handled as if it was opened with the
3212 request (this is, font translation and styles are applied), without
3213 actually mounting it.
3219 has been registered.
3221 Font translation is applied.
3226 request can now map characters onto
3230 It is now possible to have whitespace between the first and second dot
3231 (or the name of the ending macro) to end a macro definition.
3239 .Text .if t \[rs]{\[rs]
3241 .Text . nop Hello, I'm `bar'.
3247 .\" --------------------------------------------------------------------
3248 .SH "INTERMEDIATE OUTPUT FORMAT"
3249 .\" --------------------------------------------------------------------
3251 This section describes the format output by GNU troff.
3253 The output format used by GNU troff is very similar to that used
3254 by Unix device-independent troff.
3256 Only the differences are documented here.
3259 .\" --------------------------------------------------------------------
3261 .\" --------------------------------------------------------------------
3265 command is in scaled points (units of
3269 is the argument to the
3271 command in the DESC file).
3275 command is also in scaled points.
3278 .\" --------------------------------------------------------------------
3280 .\" --------------------------------------------------------------------
3284 Print glyph with index\~\c
3286 (a non-negative integer) of the current font.
3291 line is present in the DESC file, troff uses the following two
3297 is any sequence of characters terminated by a space or a newline (to
3298 be more precise, it is a sequence of glyphs which are accessed with
3299 the corresponding characters); the first character should be printed at
3300 the current position, the current horizontal position should be increased
3301 by the width of the first character, and so on for each character.
3303 The width of the glyph is that given in the font file,
3304 appropriately scaled for the current point size, and rounded so that
3305 it is a multiple of the horizontal resolution.
3307 Special characters cannot be printed using this command.
3313 command except that after printing each character, the current
3314 horizontal position is increased by the sum of the width of that
3319 Note that single characters can have the eighth bit set, as can the
3320 names of fonts and special characters.
3323 The names of glyphs and fonts can be of arbitrary length; drivers
3324 should not assume that they are only two characters long.
3327 When a glyph is to be printed, that glyph is always
3328 in the current font.
3330 Unlike device-independent troff, it is not necessary for drivers to
3331 search special fonts to find a glyph.
3334 For color support, some new commands have been added:
3337 .Text \f[B]mc \f[I]cyan magenta yellow\f[R]
3341 .Text \f[B]mg \f[I]gray\f[R]
3343 .Text \f[B]mk \f[I]cyan magenta yellow black\f[R]
3345 .Text \f[B]mr \f[I]red green blue\f[R]
3346 Set the color components of the current drawing color, using various
3350 resets the drawing color to the default value.
3352 The arguments are integers in the range 0 to 65536.
3357 device control command has been extended.
3360 .Text \f[B]x u \f[I]n\f[R]
3363 is\~1, start underlining of spaces.
3367 is\~0, stop underlining of spaces.
3369 This is needed for the
3371 request in nroff mode and is ignored otherwise.
3374 .\" --------------------------------------------------------------------
3375 .SS "Drawing Commands"
3376 .\" --------------------------------------------------------------------
3380 drawing command has been extended.
3382 These extensions are not used by GNU pic if the
3387 .Text \f[B]Df \f[I]n\f[R]\*[ic]\[rs]n
3388 Set the shade of gray to be used for filling solid objects to
3391 must be an integer between 0 and 1000, where 0 corresponds solid white
3392 and 1000 to solid black, and values in between correspond to
3393 intermediate shades of gray.
3395 This applies only to solid circles, solid ellipses and solid
3398 By default, a level of 1000 is used.
3400 Whatever color a solid object has, it should completely obscure
3401 everything beneath it.
3403 A value greater than 1000 or less than 0 can also be used: this means
3404 fill with the shade of gray that is currently being used for lines and
3407 Normally this is black, but some drivers may provide a way of
3412 .BI \[rs]D'f .\|.\|. '
3413 command shouldn't be used since its argument is always rounded to an
3414 integer multiple of the horizontal resolution which can lead to
3418 .Text \f[B]DC \f[I]d\f[R]\*[ic]\[rs]n
3419 Draw a solid circle with a diameter of
3421 with the leftmost point at the current position.
3424 .Text \f[B]DE \f[I]dx dy\f[R]\*[ic]\[rs]n
3425 Draw a solid ellipse with a horizontal diameter of
3427 and a vertical diameter of
3429 with the leftmost point at the current position.
3435 .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
3436 Draw a polygon with, for $i = 1 ,..., n+1$, the
3438 vertex at the current position
3440 $+ sum from j=1 to i-1 ( dx sub j , dy sub j )$.
3442 At the moment, GNU pic only uses this command to generate triangles
3446 .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
3450 but draw a solid rather than outlined polygon.
3453 .Text \f[B]Dt \f[I]n\f[R]\*[ic]\[rs]n
3454 Set the current line thickness to
3458 Traditionally Unix troff drivers use a line thickness proportional to
3459 the current point size; drivers should continue to do this if no
3461 command has been given, or if a
3463 command has been given with a negative value of
3467 selects the smallest available line thickness.
3470 A difficulty arises in how the current position should be changed after
3471 the execution of these commands.
3473 This is not of great importance since the code generated by GNU pic
3474 does not depend on this.
3476 Given a drawing command of the form
3478 \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]
3490 Unix troff treats each of the $x sub i$ as a horizontal quantity,
3491 and each of the $y sub i$ as a vertical quantity and assumes that
3492 the width of the drawn object is $sum from i=1 to n x sub i$,
3493 and that the height is $sum from i=1 to n y sub i$.
3495 (The assumption about the height can be seen by examining the
3499 registers after using such a
3501 command in a \[rs]w escape sequence).
3503 This rule also holds for all the original drawing commands with the
3506 For the sake of compatibility GNU troff also follows this rule, even
3507 though it produces an ugly result in the case of the
3511 and, to a lesser extent,
3515 Thus after executing a
3519 \f[B]D\f[I]c\f[R] $x sub 1$ $y sub 1$ $x sub 2$ $y sub 2$ $...$ \c
3520 $x sub n$ $y sub n$\[rs]n
3523 the current position should be increased by
3525 $( sum from i=1 to n x sub i , sum from i=1 to n y sub i )$.
3528 Another set of extensions is
3531 .Text \f[B]DFc \f[I]cyan magenta yellow\f[R]\*[ic]\[rs]n
3533 .Text \f[B]DFd\f[R]\*[ic]\[rs]n
3535 .Text \f[B]DFg \f[I]gray\f[R]\*[ic]\[rs]n
3537 .Text \f[B]DFk \f[I]cyan magenta yellow black\f[R]\*[ic]\[rs]n
3539 .Text \f[B]DFr \f[I]red green blue\f[R]\*[ic]\[rs]n
3540 Set the color components of the filling color similar to the
3545 The current position isn't changed by those colour commands (contrary to
3549 .\" --------------------------------------------------------------------
3550 .SS "Device Control Commands"
3551 .\" --------------------------------------------------------------------
3553 There is a continuation convention which permits the argument to the
3555 command to contain newlines: when outputting the argument to the
3557 command, GNU troff follows each newline in the argument with a
3559 character (as usual, it terminates the entire argument with a
3560 newline); thus if the line after the line containing the
3564 then the newline ending the line containing the
3566 command should be treated as part of the argument to the
3570 should be ignored, and the part of the line following the
3572 should be treated like the part of the line following the
3577 The first three output commands are guaranteed to be:
3586 .\" --------------------------------------------------------------------
3587 .SH INCOMPATIBILITIES
3588 .\" --------------------------------------------------------------------
3590 In spite of the many extensions, groff has retained compatibility to
3591 classical troff to a large degree.
3593 For the cases where the extensions lead to collisions, a special
3594 compatibility mode with the restricted, old functionality was created
3598 .\" --------------------------------------------------------------------
3599 .SS "Groff Language"
3600 .\" --------------------------------------------------------------------
3604 .B compatibility mode
3605 that allows to process roff code written for classical
3607 or for other implementations of roff in a consistent way.
3610 Compatibility mode can be turned on with the
3612 command line option, and turned on or off with the
3618 is\~1 if compatibility mode is on, 0\~otherwise.
3621 This became necessary because the GNU concept for long names causes
3622 some incompatibilities.
3629 as defining a string
3635 mode, this is considered as a call of a macro named
3645 as references to a string or number register called
3649 takes this as the start of a long name.
3653 .IR "compatibility mode" ,
3654 groff interprets these things in the traditional way; so long
3655 names are not recognized.
3658 On the other hand, groff in
3660 does not allow to use the single-character escapes
3689 (character c) in names of strings, macros, diversions, number
3690 registers, fonts or environments, whereas
3697 escape sequence can be helpful in avoiding these escape sequences in
3701 Fractional pointsizes cause one noteworthy incompatibility.
3708 request ignores scale indicators and so
3715 sets the pointsize to 10\~points, whereas in groff native mode the
3716 pointsize is set to 10\~scaled points.
3721 there is a fundamental difference between unformatted input
3722 characters, and formatted output characters (glyphs).
3724 Everything that affects how a glyph is output is
3725 stored with the glyph; once a glyph has been
3726 constructed it is unaffected by any subsequent requests that are
3727 executed, including the
3737 Normally glyphs are constructed from input characters at
3738 the moment immediately before the glyph is added to the current
3741 Macros, diversions and strings are all, in fact, the same type of
3742 object; they contain lists of input characters and glyphs
3746 Special characters can be both; before being added to the output, they
3747 act as input entities, afterwards they denote glyphs.
3750 A glyph does not behave like an input character for the
3751 purposes of macro processing; it does not inherit any of the special
3752 properties that the input character from which it was constructed
3755 The following example makes things clearer.
3762 .Text \[rs]\[rs]\[rs]\[rs]
3775 So each pair of input backslashes
3777 is turned into a single output backslash glyph
3779 and the resulting output backslashes are not interpreted as escape
3780 characters when they are reread.
3784 would interpret them as escape characters when they were reread and
3785 would end up printing a single backslash
3789 In GNU, the correct way to get a printable version of the backslash
3794 escape sequence, but classical troff does not provide a clean feature
3795 for getting a non-syntactical backslash.
3797 A close method is the printable version of the current escape
3800 escape sequence; this works if the current escape character is not
3803 It works in both GNU mode and compatibility mode, while dirty tricks
3804 like specifying a sequence of multiple backslashes do not work
3805 reliably; for the different handling in diversions, macro definitions,
3806 or text mode quickly leads to a confusion about the necessary number of
3810 To store an escape sequence in a diversion that is interpreted
3811 when the diversion is reread, either the traditional
3813 transparent output facility or the
3816 escape sequence can be used.
3819 .\" --------------------------------------------------------------------
3820 .SS "Intermediate Output"
3821 .\" --------------------------------------------------------------------
3823 The groff intermediate output format is in a state of evolution.
3825 So far it has some incompatibilities, but it is intended to establish
3826 a full compatibility to the classical troff output format.
3828 Actually the following incompatibilities exist:
3831 The positioning after the drawing of the polygons conflicts with the
3832 classical definition.
3835 The intermediate output cannot be rescaled to other devices as
3836 classical "device-independent" troff did.
3839 .\" --------------------------------------------------------------------
3841 .\" --------------------------------------------------------------------
3843 Copyright (C) 1989, 2001, 2002, 2003, 2004, 2006
3844 Free Software Foundation, Inc.
3847 This document is distributed under the terms of the FDL (GNU Free
3848 Documentation License) version 1.1 or later.
3850 You should have received a copy of the FDL on your system, it is also
3851 available on-line at the
3852 .URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" .
3854 This document was written by James Clark, with modifications by
3855 .MTO wl@gnu.org "Werner Lemberg"
3857 .MTO bwarken@mayn.de "Bernd Warken" .
3860 This document is part of
3862 the GNU roff distribution.
3864 Formerly, the contents of this document was kept in the manual
3866 .BR @g@troff (@MAN1EXT@).
3867 Only the parts dealing with the language aspects of the different
3869 systems were carried over into this document.
3873 command line options and warnings are still documented in
3874 .BR @g@troff (@MAN1EXT@).
3876 .\" --------------------------------------------------------------------
3878 .\" --------------------------------------------------------------------
3885 presents all groff documentation within a single document.
3888 .BR groff (@MAN1EXT@)
3889 A list of all documentation around
3893 .BR groff (@MAN7EXT@)
3894 A description of the
3896 language, including a short, but complete reference of all predefined
3897 requests, registers, and escapes of plain
3899 From the command line, this is called using
3902 .ShellCommand man\~7\~groff
3905 .BR roff (@MAN7EXT@)
3908 systems, including pointers to further historical documentation.
3913 .I Nroff/\:Troff User's Manual
3916 of 1976 in the revision of
3919 .URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:54.ps.gz \
3920 "classical troff documentation" .
3922 .cp \n[groff_diff_C]
3924 .\" --------------------------------------------------------------------
3926 .\" --------------------------------------------------------------------
3928 .\" Local Variables: