2 .\" The above line should force the use of eqn as a preprocessor
6 This file is part of groff, the GNU roff type-setting system.
7 It is the source of the man-page groff_diff(7).
9 Copyright (C) 1989, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009
10 Free Software Foundation, Inc.
11 written by James Clark
13 modified by Werner Lemberg <wl@gnu.org>
14 Bernd Warken <bwarken@mayn.de>
16 Permission is granted to copy, distribute and/or modify this document
17 under the terms of the GNU Free Documentation License, Version 1.3 or
18 any later version published by the Free Software Foundation; with the
19 Invariant Sections being this .ig-section and AUTHORS, with no
20 Front-Cover Texts, and with no Back-Cover Texts.
22 A copy of the Free Documentation License is included as a file called
23 FDL in the main directory of the groff source package.
27 .\" --------------------------------------------------------------------
29 .\" --------------------------------------------------------------------
31 .\" define a string tx for the TeX logo
32 .ie t .ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
36 .\" from old groff_out.man
43 .\" --------------------------------------------------------------------
45 .\" --------------------------------------------------------------------
47 .TH GROFF_DIFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
49 groff_diff \- differences between GNU troff and classical troff
52 .\" --------------------------------------------------------------------
54 .\" --------------------------------------------------------------------
56 This manual page describes the language differences between
60 text processing system, and the classical
62 formatter of the freely available Unix\~7 of the 1970s, documented in
64 .I Troff User's Manual
69 This inludes the roff language as well as the intermediate output
70 format (troff output).
75 gives pointers to both the classical
82 .\" --------------------------------------------------------------------
84 .\" --------------------------------------------------------------------
86 In this section, all additional features of
88 compared to the classical Unix\~7
90 are described in detail.
93 .\" --------------------------------------------------------------------
95 .\" --------------------------------------------------------------------
97 The names of number registers, fonts, strings/\:macros/\:diversions,
98 special characters (glyphs), and colors can be of any length.
100 In escape sequences, additionally to the classical `\fB(\fP\fIxx\fP'
101 construction for a two-character glyph name, you can use
102 `\fB[\fP\fIxxx\fP\fB]\fP' for a name of arbitrary length.
106 Print the special character (glyph) called
110 .BI \[rs][ "comp1 comp2 .\|.\|." ]
111 Print composite glyph consisting of multiple components.
113 Example: `\[rs][A\~ho]' is capital letter A with ogonek which finally maps
114 to glyph name `u0041_0328'.
118 for details how a glyph name for a composite glyph is constructed, and
119 .BR groff_char (@MAN7EXT@)
120 for a list of glyph name components used in composite glyph names.
129 is a new syntax form equal to
131 i.e., to return to the previous font.
134 .BI \[rs]*[ "xxx arg1 arg2 .\|.\|." ]
145 Interpolate number register
149 .\" --------------------------------------------------------------------
150 .SS "Fractional point sizes"
151 .\" --------------------------------------------------------------------
163 There is a new scale indicator\~\c
165 that has the effect of multiplying by sizescale.
167 Requests and escape sequences in troff interpret arguments that
168 represent a point size as being in units of scaled points, but they
169 evaluate each such argument using a default scale indicator of\~\c
171 Arguments treated in this way are the argument to the
173 request, the third argument to the
175 request, the second and fourth arguments to the
177 request, the argument to the
179 escape sequence, and those variants of the
181 escape sequence that take a numeric expression as their argument.
184 For example, suppose sizescale is 1000; then a scaled point is
185 equivalent to a millipoint; the call
189 and so sets the point size to 10250 scaled points, which is equal to
195 returns the point size in points as decimal fraction.
197 There is also a new number register
199 that returns the point size in scaled points.
202 It would make no sense to use the
204 scale indicator in a numeric expression whose default scale indicator
213 Similarly it would make no sense to use a scaling indicator other than
217 in a numeric expression whose default scale indicator was\~\c
221 disallows this as well.
224 There is also new scale indicator\~\c
226 which multiplies by the number of units in a scaled point.
232 Be sure not to confuse the
239 .\" --------------------------------------------------------------------
240 .SS "Numeric expressions"
241 .\" --------------------------------------------------------------------
243 Spaces are permitted in a number expression within parentheses.
247 indicates a scale of 100ths of an em.
249 indicates a scale of 65536 units, providing fractions for color
254 For example, 0.5f = 32768u.
276 as the default scaling indicator.
280 is missing, ignore scaling indicators in the evaluation of\~\c
284 .\" --------------------------------------------------------------------
285 .SS "New escape sequences"
286 .\" --------------------------------------------------------------------
289 .BI \[rs]A' anything '
296 is or is not acceptable as the name of a string, macro, diversion, number
297 register, environment, font, or color.
304 This is useful if you want to look up user input in some sort of
308 .BI \[rs]B' anything '
315 is or is not a valid numeric expression.
327 Normally it is more convenient to use
328 .BI \[rs][ xxx ]\f[R].
331 has the advantage that it is compatible with recent versions of
333 and is available in compatibility mode.
337 This is equivalent to an escape character, but it is not interpreted in
340 For example, strings to start and end superscripting could be defined
346 \&.ds { \[rs]v'\-.3m'\[rs]s'\[rs]En[.s]*6u/10u'
347 \&.ds } \[rs]s0\[rs]v'.3m'
354 ensures that these definitions work even if
356 gets interpreted in copy mode (for example, by being used in a macro
368 This is the same as the
373 switches back to the previous color (note that
375 won't work; it selects font family `P' instead).
385 switches back to the previous color.
393 Set background color for filled objects drawn with the
394 .BI \[rs]D' .\|.\|. '
397 switches back to the previous color.
401 Typeset the glyph with index\~\c
407 Most devices only have glyphs with indices between 0 and 255.
409 If the current font does not contain a glyph with that code,
416 escape sequence can be conveniently used in conjunction with the
423 \&.char \[rs][phone] \[rs]f(ZD\[rs]N'37'
428 The index of each glyph is given in the fourth column in the font
429 description file after the
433 It is possible to include unnamed glyphs in the font description
434 file by using a name of
438 escape sequence is the only way to use these.
444 Suppress troff output.
452 are intended for internal use by
458 Disable any ditroff glyphs from being emitted to the device driver,
459 provided that the escape occurs at the outer level (see
466 Enable output of glyphs, provided that the escape occurs at the outer
472 also reset the registers
480 These four registers mark the top left and bottom right hand corners
481 of a box which encompasses all written glyphs.
485 Provided that the escape occurs at the outer level, enable output of
486 glyphs and also write out to stderr the page number and four registers
487 encompassing the glyphs previously written since the last call to
492 Begin a nesting level.
498 This is really an internal mechanism for
500 while producing images.
502 They are generated by running the troff source through
504 to the postscript device and
506 to produce images in PNG format.
510 escape starts a new page if the device is not html (to reduce the
511 possibility of images crossing a page boundary).
518 .BI \[rs]O5[ Pfilename ]
523 Provided that this escape occurs at the outer nesting level, write
527 The position of the image,
529 must be specified and must be one of
535 (left, right, centered, inline).
538 is associated with the production of the next inline image.
542 .BI \[rs]R' name\ \[+-]n '
543 This has the same effect as
547 .BI .nr\ name\ \[+-]n
554 Set the point size to
558 must be exactly two digits.
568 Set the point size to
572 is a numeric expression with a default scale indicator of\~\c
581 Interpolate the contents of the environment variable
586 is interpreted in copy mode.
594 This is approximately equivalent to
595 .BI \[rs]X'\[rs]*[ xxx ]'\f[R].
596 However the contents of the string or macro
598 are not interpreted; also it is permitted for
600 to have been defined as a macro and thus contain newlines (it is not
601 permitted for the argument to
603 to contain newlines).
605 The inclusion of newlines requires an extension to the UNIX troff
606 output format, and confuses drivers that do not know about this
610 .BI \[rs]Z' anything '
611 Print anything and then restore the horizontal and vertical position;
613 may not contain tabs or leaders.
617 The name by which the current macro was invoked.
621 request can make a macro have more than one name.
625 In a macro or string, the concatenation of all the arguments separated
630 In a macro or string, the concatenation of all the arguments with each
631 surrounded by double quotes, and separated by spaces.
635 In a macro, the representation of all parameters as if they were an
644 In a macro or string, this gives the
650 Macros and strings can have an unlimited number of arguments.
653 .BI \[rs]? anything \[rs]?
654 When used in a diversion, this transparently embeds
658 is read in copy mode.
660 When the diversion is reread,
664 may not contain newlines; use
666 if you want to embed newlines in a diversion.
670 is also recognized in copy mode and turned into a single internal
671 code; it is this code that terminates
682 \&\[rs]?\[rs]\[rs]?\[rs]\[rs]\[rs]\[rs]?\[rs]\[rs]\[rs]\[rs]\[rs]\[rs]\[rs]\c
683 \&\[rs]nx\[rs]\[rs]\[rs]\[rs]?\[rs]\[rs]?\[rs]?
704 This increases the width of the preceding glyph so that the
705 spacing between that glyph and the following glyph is
706 correct if the following glyph is a roman glyph.
709 . nop For example, if an italic\~f is immediately followed by a roman
710 . nop right parenthesis, then in many fonts the top right portion of
711 . nop the\~f overlaps the top left of the right parenthesis
712 . nop producing \f[I]f\f[R])\f[R], which is ugly.
716 . ie \n(.g \f[I]f\/\f[R])\f[R]
717 . el \f[I]f\|\f[R])\f[R]
718 . nop and avoids this problem.
720 It is a good idea to use this escape sequence whenever an italic
721 glyph is immediately followed by a roman glyph without any
726 This modifies the spacing of the following glyph so that the
727 spacing between that glyph and the preceding glyph is
728 correct if the preceding glyph is a roman glyph.
731 . nop For example, inserting
733 . nop between the parenthesis and the\~f changes
734 . nop \f[R](\f[I]f\f[R] to
735 . ie \n(.g \f[R](\,\f[I]f\f[R].
736 . el \f[R](\^\f[I]f\f[R].
738 It is a good idea to use this escape sequence whenever a roman
739 glyph is immediately followed by an italic glyph without any
746 except that it behaves like a character declared with the
748 request to be transparent for the purposes of end-of-sentence
753 This produces an unbreakable space that stretches like a normal
754 inter-word space when a line is adjusted.
758 This causes the insertion of a zero-width break point.
762 within a word but without insertion of a soft hyphen glyph.
766 Everything up to and including the next newline is ignored.
768 This is interpreted in copy mode.
774 does not ignore the terminating newline.
777 .\" --------------------------------------------------------------------
779 .\" --------------------------------------------------------------------
785 for number register object named
787 The new name and the old name are exactly equivalent.
791 is undefined, a warning of type
793 is generated, and the request is ignored.
799 for request, string, macro, or diversion object named
802 The new name and the old name are exactly equivalent (it is
803 similar to a hard rather than a soft link).
807 is undefined, a warning of type
809 is generated, and the request is ignored.
819 requests only create a new object if the name of the macro, diversion
820 or string is currently undefined or if it is defined to be a
821 request; normally they modify the value of an existing object.
827 but compatibility mode is switched off during execution.
829 To be more precise, a `compatibility save' token is inserted at the
830 beginning of the macro addition, and a `compatibility restore' token at
833 As a consequence, the requests
839 can be intermixed freely since the compatibility save/\:restore tokens
840 only affect the macro parts defined by
847 Append to macro indirectly.
851 request below for more information.
857 request but compatibility mode is switched off during execution.
863 but compatibility mode is switched off during expansion.
865 To be more precise, a `compatibility save' token is inserted at the
866 beginning of the string, and a `compatibility restore' token at the end.
868 As a consequence, the requests
874 can be intermixed freely since the compatibility save/\:restore tokens
875 only affect the (sub)strings defined by
882 This request `unformats' the diversion
886 and space characters (and some escape sequences) that were formatted
889 are treated like ordinary input characters when
892 Useful for diversions in conjunction with the
896 It can be also used for gross hacks; for example, this
918 Note that glyph information (font, font size, etc.) is not preserved;
925 Print a backtrace of the input stack on stderr.
929 Set the blank line macro to
931 If there is a blank line macro, it is invoked when a blank line
932 is encountered instead of the usual troff behaviour.
938 These requests are similar to the
942 requests with the exception that a partially filled line does not
943 become part of the diversion (i.e., the diversion always starts with a
944 new line) but is restored after ending the diversion, discarding the
945 partially filled line which possibly comes from the diversion.
949 Break out of a while loop.
957 Be sure not to confuse this with the
967 .BI .cflags\ n\ c1\ c2\|.\|.\|.\&
971 have properties determined by
973 which is ORed from the following:
977 The character ends sentences (initially characters
982 Lines can be broken before the character (initially no characters have
983 this property); a line is not broken at a character with this property
984 unless the characters on each side both have non-zero hyphenation
986 This can be overridden with value 64.
989 Lines can be broken after the character (initially characters
990 .B \-\[rs][hy]\[rs][em]
991 have this property); a line is not broken at a character with this
992 property unless the characters on each side both have non-zero
995 This can be overridden with value 64.
998 The glyph associated with this character overlaps horizontally
999 (initially characters
1000 .B \[rs][ul]\[rs][rn]\[rs][ru]\[rs][radicalex]\[rs][sqrtex]
1001 have this property).
1004 The glyph associated with this character overlaps vertically
1010 An end-of-sentence character followed by any number of characters with
1011 this property is treated as the end of a sentence if followed by a
1012 newline or two spaces; in other words the character is transparent for
1013 the purposes of end-of-sentence recognition; this is the same as having
1014 a zero space factor in \*[tx] (initially characters
1015 .B \[dq]')]*\[rs][dg]\[rs][rq]
1016 have this property).
1019 Ignore hyphenation code values of the surrounding characters.
1020 Use this in combination with values 2 and\~4 (initially no characters
1021 have this property).
1025 .BI .char\ c\ string
1026 [This request can both define characters and glyphs.]
1034 To be more precise, define (or even override) a groff entity which
1035 can be accessed with name\~\c
1037 on the input side, and which uses
1041 Every time glyph\~\c
1043 needs to be printed,
1045 is processed in a temporary environment and the result is
1046 wrapped up into a single object.
1048 Compatibility mode is turned off and the escape character is
1055 Any emboldening, constant spacing or track kerning is applied to
1056 this object rather than to individual glyphs in
1060 A groff object defined by this request can be used just like a
1061 normal glyph provided by the output device.
1063 In particular other characters can be translated to it with the
1065 request; it can be made the leader glyph by the
1067 request; repeated patterns can be drawn with the glyph using the
1071 escape sequences; words containing\~\c
1073 can be hyphenated correctly, if the
1075 request is used to give the object a hyphenation code.
1078 There is a special anti-recursion feature: Use of glyph within the
1079 glyph's definition is handled like normal glyphs not
1083 A glyph definition can be removed with the
1089 Chop the last element off macro, string, or diversion
1091 This is useful for removing the newline from the end of diversions
1092 that are to be interpolated as strings.
1096 Close the stream named
1099 will no longer be an acceptable argument to the
1108 .BI .composite\ glyph1\ glyph2
1114 .BI \[rs][ .\|.\|. ]
1115 with more than one component.
1119 Finish the current iteration of a while loop.
1131 is non-zero or missing, enable colors (this is the default), otherwise
1138 is non-zero or missing, enable compatibility mode, otherwise disable
1141 In compatibility mode, long names are not recognized, and the
1142 incompatibilities caused by long names do not arise.
1145 .BI .defcolor\ xxx\ scheme\ color_components
1149 can be one of the following values:
1155 (four components), and
1161 Color components can be given either as a hexadecimal string or as
1162 positive decimal integers in the range 0-65535.
1164 A hexadecimal string contains all color components concatenated; it
1165 must start with either
1169 The former specifies hex values in the range 0-255 (which are
1170 internally multiplied by\~257), the latter in the range 0-65535.
1172 Examples: #FFC0CB (pink), ##ffff0000ffff (magenta).
1174 A new scaling indicator\~\c
1176 has been introduced which multiplies its value by\~65536; this makes
1177 it convenient to specify color components as fractions in the range 0
1185 \&.defcolor darkgreen rgb 0.1f 0.5f 0.2f
1192 is the default scaling indicator for the
1194 request, thus the above statement is equivalent to
1199 \&.defcolor darkgreen rgb 0.1 0.5 0.2
1206 (which is device-specific) can't be redefined.
1208 It is possible that the default color for
1218 but compatibility mode is switched off during execution.
1220 On entry, the current compatibility mode is saved and restored at exit.
1224 Define macro indirectly.
1226 The following example
1252 request but compatibility mode is switched off during execution.
1255 .BI .device\ anything
1256 This is (almost) the same as the
1260 is read in copy mode; a leading\~\c
1266 This is the same as the
1268 escape (to embed the contents of a macro into the intermediate
1269 output preceded with `x\~X').
1275 with compatibility mode disabled.
1287 would have the same effect as
1295 except that it would work even if compatibility mode had been enabled.
1297 Note that the previous compatibility mode is restored before any files
1308 but compatibility mode is switched off during expansion.
1310 To be more precise, a `compatibility save' token is inserted at the
1311 beginning of the string, and a `compatibility restore' token at the end.
1315 Save current escape character.
1319 Restore escape character saved with
1321 Without a previous call to
1324 will be the new escape character.
1328 Copy the contents of environment
1330 to the current environment.
1332 No pushing or popping of environments is done.
1336 Set the current font family to
1338 The current font family is part of the current environment.
1341 is missing, switch back to previous font family.
1343 The value at start-up is `T'.
1345 See the description of the
1347 request for more information on font families.
1350 .BI .fchar\ c\ string
1351 Define fallback character (or glyph)\~\c
1356 The syntax of this request is the same as the
1358 request; the only difference is that a glyph defined with
1360 hides the glyph with the same name in the current font, whereas a
1363 is checked only if the particular glyph isn't found in the current font.
1365 This test happens before checking special fonts.
1369 Set the fill color to\~\c
1374 switch to the previous fill color.
1377 .BI .fschar\ f\ c\ string
1378 Define fallback character (or glyph)\~\c
1385 The syntax of this request is the same as the
1387 request (with an additional argument to specify the font); a glyph
1390 is searched after the list of fonts declared with the
1392 request but before the list of fonts declared with
1396 .BI .fspecial\ f\ s1\ s2\|.\|.\|.\&
1397 When the current font is\~\c
1402 are special, that is, they are searched for glyphs not in
1405 Any fonts specified in the
1407 request are searched after fonts specified in the
1411 Without argument, reset the list of global special fonts to be empty.
1419 Whenever a font named\~\c
1421 is referred to in an
1423 escape sequence, in the
1427 conditional operators, or in the
1443 is missing, or equal to\~\c
1456 must a non-negative integer multiple of 1/1000th.
1457 If it is missing or is equal to zero, it means the same as 1000, namely no
1460 must be a real font name, not a style.
1464 Set the glyph color to\~\c
1469 switch to the previous glyph color.
1472 .BI .hcode \ c1\ code1\ c2\ code2\|.\|.\|.\&
1473 Set the hyphenation code of character
1481 A hyphenation code must be a single input character (not a special
1482 character) other than a digit or a space.
1484 Initially each lower-case letter \%a-z has a hyphenation code, which is
1485 itself, and each upper-case letter \%A-Z has a hyphenation code which is
1486 the lower-case version of itself.
1494 Set the current hyphenation language to
1496 Hyphenation exceptions specified with the
1498 request and hyphenation patterns specified with the
1500 request are both associated with the current hyphenation language.
1504 request is usually invoked by the
1506 file to set up a default language.
1510 Set the maximum number of consecutive hyphenated lines to\~\c
1514 is negative, there is no maximum.
1516 The default value is\~\-1.
1518 This value is associated with the current environment.
1520 Only lines output from an environment count towards the maximum
1521 associated with that environment.
1523 Hyphens resulting from
1525 are counted; explicit hyphens are not.
1529 Read hyphenation patterns from
1531 this is searched for in the same way that
1533 is searched for when the
1535 option is specified.
1537 It should have the same format as (simple) \*[tx] patterns files.
1539 More specifically, the following scanning rules are implemented.
1543 A percent sign starts a comment (up to the end of the line) even if
1544 preceded by a backslash.
1547 No support for `digraphs' like
1555 (character code of\~\c
1557 in the range 0-127) are recognized; other use of\~\c
1566 checks for the expression
1567 .BR \[rs]patterns{ .\|.\|. }
1568 (possibly with whitespace before and after the braces).
1570 Everything between the braces is taken as hyphenation patterns.
1576 are not allowed in patterns.
1580 .BR \[rs]hyphenation{ .\|.\|. }
1581 gives a list of hyphenation exceptions.
1588 For backwards compatibility, if
1590 is missing, the whole file is treated as a list of hyphenation patterns
1591 (only recognizing the
1593 character as the start of a comment).
1599 request to map the encoding used in hyphenation patterns files to
1603 The set of hyphenation patterns is associated with the current language
1610 request is usually invoked by the
1612 file; a second call replaces the old patterns with the new ones.
1618 except that the hyphenation patterns from
1620 are appended to the patterns already loaded in the current language.
1623 .BI .hpfcode\ a\ b\ c\ d\ .\|.\|.
1624 After reading a hyphenation patterns file with the
1628 request, convert all characters with character code\~\c
1630 in the recently read patterns to character code\~\c
1638 Initially, all character codes map to themselves.
1642 must be integers in the range 0 to\~255.
1644 Note that it is even possible to use character codes which are invalid in
1651 .I hyphenation margin
1654 when the current adjustment mode is not\~\c
1656 the line is not hyphenated if the line is no more than
1660 The default hyphenation margin is\~0.
1662 The default scaling indicator for this request is\~\c
1664 The hyphenation margin is associated with the current environment.
1666 The current hyphenation margin is available in the
1673 .I hyphenation space
1676 When the current adjustment mode is\~\c
1678 don't hyphenate the line if the line can be justified by adding no
1681 extra space to each word space.
1683 The default hyphenation space is\~0.
1685 The default scaling indicator for this request is\~\c
1687 The hyphenation space is associated with the current environment.
1689 The current hyphenation space is available in the
1697 for which a line interrupted with
1699 counts as one input line.
1705 is non-zero or missing, enable pairwise kerning, otherwise disable it.
1708 .BI .length\ xx\ string
1709 Compute the length of
1711 and return it in the number register
1713 (which is not necessarily defined before).
1719 is non-zero or missing, enable line-tabs mode, otherwise disable it
1720 (which is the default).
1722 In line-tabs mode, tab distances are computed relative to the
1723 (current) output line.
1725 Otherwise they are taken relative to the input line.
1727 For example, the following
1733 \&.ds x a\[rs]t\[rs]c
1734 \&.ds y b\[rs]t\[rs]c
1754 In line-tabs mode, the same code gives
1764 Line-tabs mode is associated with the current environment; the
1765 read-only number register
1766 .B \[rs]n[.linetabs]
1767 is set to\~1 if in line-tabs mode, and 0 otherwise.
1775 is searched for in the same directories as macro files for the the
1777 command line option.
1779 If the file name to be included has the form
1785 instead and vice versa.
1791 This is similar to `.if\ 1'.
1797 built-in condition true and the
1799 built-in condition false.
1801 This can be reversed using the
1806 .BI .open\ stream\ filename
1809 for writing and associate the stream named
1820 .BI .opena\ stream\ filename
1825 exists, append to it instead of truncating it.
1831 directly to the intermediate output (subject to copy-mode interpretation);
1834 used at the top level.
1836 An initial double quote in
1838 is stripped off to allow initial blanks.
1842 Print the current environment and each defined environment state on
1847 Print the names and contents of all currently defined number registers
1851 .BI .psbb \ filename
1852 Get the bounding box of a PostScript image
1854 This file must conform to Adobe's Document Structuring Conventions;
1855 the command looks for a
1857 comment to extract the bounding box values.
1859 After a successful call, the coordinates (in PostScript units) of the
1860 lower left and upper right corner can be found in the registers
1868 If some error has occurred, the four registers are set to zero.
1872 This behaves like the
1874 request except that input comes from the standard output of
1879 Print the names and positions of all traps (not including input line
1880 traps and diversion traps) on stderr.
1882 Empty slots in the page trap list are printed as well, because they
1883 can affect the priority of subsequently planted traps.
1887 Set the post-vertical line space to\~\c
1889 default scale indicator is\~\c
1892 This value is added to each line after it has been output.
1894 With no argument, the post-vertical line space is set to its previous
1898 The total vertical line spacing consists of four components:
1902 with a negative value which are applied before the line is output, and
1906 with a positive value which are applied after the line is output.
1909 .BI .rchar\ c1\ c2\|.\|.\|.\&
1910 Remove the definitions of glyphs
1913 This undoes the effect of a
1919 Within a macro, return immediately.
1921 If called with an argument, return twice, namely from the current macro and
1922 from the macro one level higher.
1924 No effect otherwise.
1927 .BI .rfschar\ c1\ c2\|.\|.\|.\&
1928 Remove the font-specific definitions of glyphs
1931 This undoes the effect of a
1939 Right justify the next
1943 Without an argument right justify the next input line.
1945 The number of lines to be right justified is available in the
1949 This implicitly does
1953 request implicitly does
1958 Rename number register
1964 .BI .schar\ c\ string
1965 Define global fallback character (or glyph)\~\c
1970 The syntax of this request is the same as the
1972 request; a glyph defined with
1974 is searched after the list of fonts declared with the
1976 request but before the mounted special fonts.
1980 Set the soft hyphen character to\~\c
1984 is omitted, the soft hyphen character is set to the default
1986 The soft hyphen character is the glyph which is inserted when
1987 a word is hyphenated at a line break.
1989 If the soft hyphen character does not exist in the font of the
1990 glyph immediately preceding a potential break point, then the line
1991 is not broken at that point.
1993 Neither definitions (specified with the
1995 request) nor translations (specified with the
1997 request) are considered when finding the soft hyphen character.
2001 In a macro, shift the arguments by
2003 positions: argument\~\c
2009 are no longer available.
2013 is missing, arguments are shifted by\~1.
2015 Shifting by negative amounts is currently undefined.
2018 .BI .sizes\ s1\ s2\|.\|.\|.\|sn\ [0]
2019 This command is similar to the
2025 It sets the available font sizes for the current font to
2027 .IR s2 ,\|.\|.\|.\|,\~ sn
2030 The list of sizes can be terminated by an optional\~\c
2035 can also be a range of sizes
2038 Contrary to the font file command, the list can't extend over more
2042 .BI .special\ s1\ s2\|.\|.\|.\&
2046 are special and are searched for glyphs not in the current
2049 Without arguments, reset the list of special fonts to be empty.
2052 .BI .spreadwarn\ limit
2055 emit a warning if the additional space inserted for each space between
2056 words in an output line is larger or equal to
2059 A negative value is changed to zero; no argument toggles the warning on
2060 and off without changing
2063 The default scaling indicator is\~\c
2073 .B .spreadwarn\ 0.2m
2076 must add 0.2m or more for each interword space in a line.
2078 This request is active only if text is justified to both margins (using
2085 with font position\~\c
2087 A font position can be associated either with a font or with a style.
2089 The current font is the index of a font position and so is also either
2092 When it is a style, the font that is actually used is the font the
2093 name of which is the concatenation of the name of the current family
2094 and the name of the current style.
2096 For example, if the current font is\~1 and font position\~1 is
2097 associated with style\~\c
2099 and the current font family is\~\c
2105 If the current font is not a style, then the current family is ignored.
2114 are applied to a style, then they are applied instead to the
2115 member of the current family corresponding to that style.
2117 The default family can be set with the
2119 command line option.
2125 file controls which font positions (if any) are initially associated
2126 with styles rather than fonts.
2129 .BI .substring\ xx\ n1\ [ n2 ]
2130 Replace the string named
2132 with the substring defined by the indices
2136 The first character in the string has index\~0.
2140 is omitted, it is taken to be equal to the string's length.
2146 is negative, it is counted from the end of the string,
2149 The last character has index\~\-1, the character before the last
2150 character has index\~\-2, etc.
2153 .BI .tkf\ f\ s1\ n1\ s2\ n2
2154 Enable track kerning for font\~\c
2156 When the current font is\~\c
2158 the width of every glyph is increased by an amount between
2162 when the current point size is less than or equal to
2164 the width is increased by
2166 when it is greater than or equal to
2168 the width is increased by
2170 when the point size is greater than or equal to
2172 and less than or equal to
2174 the increase in width is a linear function of the point size.
2182 is read in copy mode and written on the standard error, but an initial
2185 is stripped off to allow initial blanks.
2191 but without writing a final newline.
2195 Transparently output the contents of file
2197 Each line is output as if preceded by
2199 however, the lines are not subject to copy-mode interpretation.
2201 If the file does not end with a newline, then a newline is added.
2203 For example, you can define a macro\~\c
2205 containing the contents of file\~\c
2222 request, the file cannot contain characters such as
2224 that are not valid troff input characters.
2228 This is the same as the
2230 request except that the
2232 request uses the character code (if any) before the character
2263 This is the same as the
2265 request except that the translations do not apply to text that is
2266 transparently throughput into a diversion with
2296 built-in condition false, and the
2298 built-in condition true.
2300 This undoes the effect of the
2306 This request `unformats' the diversion
2310 request, which tries to convert formatted elements of the diversion
2311 back to input tokens as much as possible,
2313 only handles tabs and spaces between words (usually caused by
2314 spaces or newlines in the input) specially.
2316 The former are treated as if they were input tokens, and the latter
2317 are stretchable again.
2319 Note that the vertical size of lines is not preserved.
2321 Glyph information (font, font size, space width, etc.) is retained.
2323 Useful in conjunction with the
2331 Enable vertical position traps if
2333 is non-zero, disable them otherwise.
2335 Vertical position traps are traps set by the
2343 request are not vertical position traps.
2345 The parameter that controls whether vertical position traps are
2348 Initially vertical position traps are enabled.
2354 is the sum of the numbers associated with each warning that is to be
2355 enabled; all other warnings are disabled.
2357 The number associated with each warning is listed in
2358 .BR @g@troff (@MAN1EXT@).
2362 disables all warnings, and
2364 disables all warnings except that about missing glyphs.
2368 is not given, all warnings are enabled.
2372 Set the scaling indicator used in warnings to
2385 At startup, it is set to\~\c
2389 .BI .while \ c\ anything
2396 can be any condition acceptable to an
2400 can comprise multiple lines if the first line starts with
2402 and the last line ends with
2411 .BI .write\ stream\ anything
2417 must previously have been the subject of an
2421 is read in copy mode;
2427 .BI .writec\ stream\ anything
2430 but without writing a final newline.
2433 .BI .writem\ stream\ xx
2434 Write the contents of the macro or string
2439 must previously have been the subject of an
2443 is read in copy mode.
2446 .\" --------------------------------------------------------------------
2447 .SS "Extended escape sequences"
2448 .\" --------------------------------------------------------------------
2451 .BR \[rs]D' .\|.\|. '
2452 All drawing commands of groff's intermediate output are accepted.
2455 .B "Drawing Commands"
2456 below for more information.
2459 .\" --------------------------------------------------------------------
2460 .SS "Extended requests"
2461 .\" --------------------------------------------------------------------
2465 When used in a diversion, this embeds in the diversion an object
2466 which, when reread, will cause the contents of
2468 to be transparently copied through to the output.
2470 In UNIX troff, the contents of
2472 is immediately copied through to the output regardless of whether
2473 there is a current diversion; this behaviour is so anomalous that it
2474 must be considered a bug.
2484 In compatibility mode, these requests behaves similar to
2490 respectively: A `compatibility save' token is inserted at the
2491 beginning, and a `compatibility restore' token at the end, with
2492 compatibility mode switched on during execution.
2498 is not a number, this switches to a named environment called
2500 The environment should be popped with a matching
2502 request without any arguments, just as for numbered environments.
2504 There is no limit on the number of named environments; they are
2505 created the first time that they are referenced.
2509 When two arguments are given to the
2511 request, the second argument gives the
2512 .IR "sentence space size" .
2513 If the second argument is not given, the sentence space size
2514 is the same as the word space size.
2516 Like the word space size, the sentence space is in units of
2517 one twelfth of the spacewidth parameter for the current font.
2519 Initially both the word space size and the sentence
2522 Contrary to UNIX troff, GNU troff handles this request in nroff mode
2523 also; a given value is then rounded down to the nearest multiple
2526 The sentence space size is used in two circumstances.
2528 If the end of a sentence occurs at the end of a line in fill mode,
2529 then both an inter-word space and a sentence space are added; if
2530 two spaces follow the end of a sentence in the middle of a line, then
2531 the second space is a sentence space.
2533 Note that the behaviour of UNIX troff are exactly that exhibited
2534 by GNU troff if a second argument is never given to the
2538 In GNU troff, as in UNIX troff, you should always follow a sentence
2539 with either a newline or two spaces.
2542 .BI .ta\ n1\ n2\|.\|.\|.nn \ T\ r1\ r2\|.\|.\|.\|rn
2543 Set tabs at positions
2545 .IR n2 ,\|.\|.\|.\|,
2547 and then set tabs at
2549 .IR nn \|+\| r2 ,\|.\|.\|.\|,
2552 .IR nn \|+\| rn \|+\| r1 ,
2553 .IR nn \|+\| rn \|+\| r2 ,\|.\|.\|.\|,
2554 .IR nn \|+\| rn \|+\| rn ,
2565 sets tabs every half an inch.
2569 .\" --------------------------------------------------------------------
2570 .SS "New number registers"
2571 .\" --------------------------------------------------------------------
2573 The following read-only registers are available:
2577 Within a macro call, it is set to\~1 if the macro is called with the
2578 `normal' control character (`.' by default), and set to\~0 otherwise.
2579 This allows to reliably modify requests.
2588 \&.ie \[rs]\[rs]n[.br] .bp*orig
2596 Using this register outside of a macro makes no sense (it always returns
2597 zero in such cases).
2601 1\~if compatibility mode is in effect, 0\~otherwise.
2605 The depth of the last glyph added to the current environment.
2607 It is positive if the glyph extends below the baseline.
2611 The number of lines remaining to be centered, as set by the
2617 The height of the last glyph added to the current environment.
2619 It is positive if the glyph extends above the baseline.
2623 1\~if colors are enabled, 0\~otherwise.
2627 The skew of the last glyph added to the current environment.
2631 of a glyph is how far to the right of the center of a glyph
2632 the center of an accent over that glyph should be placed.
2636 The name or number of the current environment.
2638 This is a string-valued register.
2642 The current font family.
2644 This is a string-valued register.
2648 The current (internal) real font name.
2650 This is a string-valued register.
2652 If the current font is a style, the value of
2654 is the proper concatenation of family and style name.
2658 The number of the next free font position.
2664 Macros should use this to determine whether they are running under GNU
2669 The current height of the font as set with
2674 The current hyphenation language as set by the
2680 The number of immediately preceding consecutive hyphenated lines.
2684 The maximum allowed number of consecutive hyphenated lines, as set by
2691 The current hyphenation flags (as set by the
2697 The current hyphenation margin (as set by the
2703 The current hyphenation space (as set by the
2709 The indentation that applies to the current output line.
2713 Set to a positive value if last output line is interrupted (i.e., if
2719 1\~if pairwise kerning is enabled, 0\~otherwise.
2723 The current ligature mode (as set by the
2728 .B \[rs]n[.linetabs]
2729 The current line-tabs mode (as set by the
2735 The line length that applies to the current output line.
2739 The title length as set by the
2745 The name of the current drawing color.
2747 This is a string-valued register.
2751 The name of the current background color.
2753 This is a string-valued register.
2757 The amount of space that was needed in the last
2759 request that caused a trap to be sprung.
2761 Useful in conjunction with the
2767 1\~if no-space mode is active, 0\~otherwise.
2771 1\~during a page ejection caused by the
2773 request, 0\~otherwise.
2777 The number of the next page, either the value set by a
2779 request, or the number of the current page plus\~1.
2783 The current point size in scaled points.
2787 The last-requested point size in scaled points.
2791 The current post-vertical line space as set with the
2797 The number of lines to be right-justified as set by the
2803 The slant of the current font as set with
2808 The last requested point size in points as a decimal fraction.
2810 This is a string-valued register.
2816 These give the values of the parameters set by the first and second
2823 The current font style.
2825 This is a string-valued register.
2829 A string representation of the current tab settings suitable for use
2830 as an argument to the
2836 The amount of vertical space truncated by the most recently sprung
2837 vertical position trap, or, if the trap was sprung by a
2839 request, minus the amount of vertical motion produced by the
2843 In other words, at the point a trap is sprung, it represents the
2844 difference of what the vertical position would have been but for the
2845 trap, and what the vertical position actually is.
2847 Useful in conjunction with the
2853 Set to\~1 if in safer mode and to\~0 if in unsafe mode (as given with
2856 command line option).
2860 1\~if vertical position traps are enabled, 0\~otherwise.
2864 The sum of the numbers associated with each of the currently enabled
2867 The number associated with each warning is listed in
2868 .BR @g@troff (@MAN1EXT@).
2872 The major version number.
2874 For example, if the version number is 1.03, then
2880 The minor version number.
2882 For example, if the version number is 1.03, then
2888 The revision number of groff.
2892 The zoom value of the current font, in multiples of 1/1000th.
2893 Zero if no magnification.
2903 These four registers are set by the
2905 request and contain the bounding box values (in PostScript units) of a
2906 given PostScript image.
2909 The following read/\:write registers are set by the
2921 registers, but take account of the heights and depths of glyphs.
2925 The amount of horizontal space (possibly negative) that should be
2926 added to the last glyph before a subscript.
2930 How far to right of the center of the last glyph in the
2932 argument, the center of an accent from a roman font should be placed
2936 Other available read/write number registers are:
2940 The current input line number.
2942 is a read-only alias to this register.
2946 The number of hours past midnight.
2948 Initialized at start-up.
2952 The current horizontal position at input line.
2956 The number of minutes after the hour.
2958 Initialized at start-up.
2962 The number of seconds after the minute.
2964 Initialized at start-up.
2968 The return value of the system() function executed by the last
2974 If greater than\~0, the maximum number of objects on the input stack.
2976 If less than or equal to\~0, there is no limit on the number of
2977 objects on the input stack.
2979 With no limit, recursion can continue until virtual memory is
2986 Note that the traditional
2990 is the current year minus 1900.
2993 .\" --------------------------------------------------------------------
2995 .\" --------------------------------------------------------------------
2998 predefines a single (read/write) string-based register,
3000 which contains the argument given to the
3002 command line option, namely the current output device (for example,
3006 Note that this is not the same as the (read-only) number register
3008 which is defined to be\~1 if
3012 command line option, and zero otherwise.
3014 This behaviour is different to UNIX troff.
3017 Fonts not listed in the
3019 file are automatically mounted on the next available font position
3020 when they are referenced.
3022 If a font is to be mounted explicitly with the
3024 request on an unused font position, it should be mounted on the first
3025 unused font position, which can be found in the
3029 does not enforce this strictly, it does not allow a font to be mounted
3030 at a position whose number is much greater than that of any currently
3034 Interpolating a string does not hide existing macro arguments.
3036 Thus in a macro, a more efficient way of doing
3039 .BI . xx\ \[rs]\[rs]$@
3044 .BI \[rs]\[rs]*[ xx ]\[rs]\[rs]
3047 If the font description file contains pairwise kerning information,
3048 glyphs from that font are kerned.
3050 Kerning between two glyphs can be inhibited by placing a
3055 In a string comparison in a condition, characters that appear at
3056 different input levels to the first delimiter character are not
3057 recognized as the second or third delimiters.
3059 This applies also to the
3065 escape sequence, a character that appears at a different input level
3066 to the starting delimiter character is not recognized as the
3067 closing delimiter character.
3069 The same is true for
3081 When decoding a macro or string argument that is delimited by double
3082 quotes, a character that appears at a different input level to the starting
3083 delimiter character is not recognized as the closing delimiter
3086 The implementation of
3088 ensures that the double quotes surrounding an argument appear at the
3089 same input level, which is different to the input level of the
3092 In a long escape name
3094 is not recognized as a closing delimiter except when it occurs at
3095 the same input level as the opening\~\c
3098 In compatibility mode, no attention is paid to the input-level.
3101 There are some new types of condition:
3105 True if there is a number register named
3110 True if there is a string, macro, diversion, or request named
3115 True if there is a color named
3120 True if there is a character (or glyph)
3126 character or a glyph (special character)
3127 .BI \[rs]N' xxx '\f[R],
3130 .BI \[rs][ xxx ]\f[R];
3131 the condition is also true if
3133 has been defined by the
3144 is handled as if it was opened with the
3146 request (this is, font translation and styles are applied), without
3147 actually mounting it.
3153 has been registered.
3155 Font translation is applied.
3160 request can now map characters onto
3164 The space width emitted by the
3168 escape sequences can be controlled on a per-font basis.
3169 If there is a glyph named
3173 respectively (note the leading backslash), defined in the current font file,
3174 use this glyph's width instead of the default value.
3177 It is now possible to have whitespace between the first and second dot
3178 (or the name of the ending macro) to end a macro definition.
3187 \&. nop Hello, I'm `bar'.
3193 .\" --------------------------------------------------------------------
3194 .SH "INTERMEDIATE OUTPUT FORMAT"
3195 .\" --------------------------------------------------------------------
3197 This section describes the format output by GNU troff.
3199 The output format used by GNU troff is very similar to that used
3200 by Unix device-independent troff.
3202 Only the differences are documented here.
3205 .\" --------------------------------------------------------------------
3207 .\" --------------------------------------------------------------------
3211 command is in scaled points (units of
3215 is the argument to the
3217 command in the DESC file).
3221 command is also in scaled points.
3224 .\" --------------------------------------------------------------------
3226 .\" --------------------------------------------------------------------
3230 Print glyph with index\~\c
3232 (a non-negative integer) of the current font.
3237 line is present in the DESC file, troff uses the following two
3243 is any sequence of characters terminated by a space or a newline (to
3244 be more precise, it is a sequence of glyphs which are accessed with
3245 the corresponding characters); the first character should be printed at
3246 the current position, the current horizontal position should be increased
3247 by the width of the first character, and so on for each character.
3249 The width of the glyph is that given in the font file,
3250 appropriately scaled for the current point size, and rounded so that
3251 it is a multiple of the horizontal resolution.
3253 Special characters cannot be printed using this command.
3259 command except that after printing each character, the current
3260 horizontal position is increased by the sum of the width of that
3265 Note that single characters can have the eighth bit set, as can the
3266 names of fonts and special characters.
3269 The names of glyphs and fonts can be of arbitrary length; drivers
3270 should not assume that they are only two characters long.
3273 When a glyph is to be printed, that glyph is always
3274 in the current font.
3276 Unlike device-independent troff, it is not necessary for drivers to
3277 search special fonts to find a glyph.
3280 For color support, some new commands have been added:
3283 \f[B]mc \f[I]cyan magenta yellow\f[R]
3287 \f[B]mg \f[I]gray\f[R]
3289 \f[B]mk \f[I]cyan magenta yellow black\f[R]
3291 \f[B]mr \f[I]red green blue\f[R]
3292 Set the color components of the current drawing color, using various
3296 resets the drawing color to the default value.
3298 The arguments are integers in the range 0 to 65536.
3303 device control command has been extended.
3306 \f[B]x u \f[I]n\f[R]
3309 is\~1, start underlining of spaces.
3313 is\~0, stop underlining of spaces.
3315 This is needed for the
3317 request in nroff mode and is ignored otherwise.
3320 .\" --------------------------------------------------------------------
3321 .SS "Drawing Commands"
3322 .\" --------------------------------------------------------------------
3326 drawing command has been extended.
3328 These extensions are not used by GNU pic if the
3333 \f[B]Df \f[I]n\f[R]\*[ic]\[rs]n
3334 Set the shade of gray to be used for filling solid objects to
3337 must be an integer between 0 and 1000, where 0 corresponds solid white
3338 and 1000 to solid black, and values in between correspond to
3339 intermediate shades of gray.
3341 This applies only to solid circles, solid ellipses and solid
3344 By default, a level of 1000 is used.
3346 Whatever color a solid object has, it should completely obscure
3347 everything beneath it.
3349 A value greater than 1000 or less than\~0 can also be used: this means
3350 fill with the shade of gray that is currently being used for lines and
3353 Normally this is black, but some drivers may provide a way of
3358 .BI \[rs]D'f .\|.\|. '
3359 command shouldn't be used since its argument is always rounded to an
3360 integer multiple of the horizontal resolution which can lead to
3364 \f[B]DC \f[I]d\f[R]\*[ic]\[rs]n
3365 Draw a solid circle with a diameter of
3367 with the leftmost point at the current position.
3370 \f[B]DE \f[I]dx dy\f[R]\*[ic]\[rs]n
3371 Draw a solid ellipse with a horizontal diameter of
3373 and a vertical diameter of
3375 with the leftmost point at the current position.
3381 \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
3382 Draw a polygon with, for $i = 1 ,..., n+1$, the
3384 vertex at the current position
3386 $+ sum from j=1 to i-1 ( dx sub j , dy sub j )$.
3388 At the moment, GNU pic only uses this command to generate triangles
3392 \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
3396 but draw a solid rather than outlined polygon.
3399 \f[B]Dt \f[I]n\f[R]\*[ic]\[rs]n
3400 Set the current line thickness to
3404 Traditionally Unix troff drivers use a line thickness proportional to
3405 the current point size; drivers should continue to do this if no
3407 command has been given, or if a
3409 command has been given with a negative value of\~\c
3413 selects the smallest available line thickness.
3416 A difficulty arises in how the current position should be changed after
3417 the execution of these commands.
3419 This is not of great importance since the code generated by GNU pic
3420 does not depend on this.
3422 Given a drawing command of the form
3424 \f[B]\[rs]D'\f[I]c\f[R] $x sub 1$ $y sub 1$ $x sub 2$ $y sub 2$ $...$ $x sub n$ $y sub n$\f[B]'\f[R]
3436 Unix troff treats each of the $x sub i$ as a horizontal quantity,
3437 and each of the $y sub i$ as a vertical quantity and assumes that
3438 the width of the drawn object is $sum from i=1 to n x sub i$,
3439 and that the height is $sum from i=1 to n y sub i$.
3441 (The assumption about the height can be seen by examining the
3445 registers after using such a
3451 This rule also holds for all the original drawing commands with the
3454 For the sake of compatibility GNU troff also follows this rule, even
3455 though it produces an ugly result in the case of the
3459 and, to a lesser extent,
3463 Thus after executing a
3467 \f[B]D\f[I]c\f[R] $x sub 1$ $y sub 1$ $x sub 2$ $y sub 2$ $...$ $x sub n$ $y sub n$\[rs]n
3470 the current position should be increased by
3472 $( sum from i=1 to n x sub i , sum from i=1 to n y sub i )$.
3475 Another set of extensions is
3478 \f[B]DFc \f[I]cyan magenta yellow\f[R]\*[ic]\[rs]n
3480 \f[B]DFd\f[R]\*[ic]\[rs]n
3482 \f[B]DFg \f[I]gray\f[R]\*[ic]\[rs]n
3484 \f[B]DFk \f[I]cyan magenta yellow black\f[R]\*[ic]\[rs]n
3486 \f[B]DFr \f[I]red green blue\f[R]\*[ic]\[rs]n
3487 Set the color components of the filling color similar to the
3492 The current position isn't changed by those colour commands (contrary to
3496 .\" --------------------------------------------------------------------
3497 .SS "Device Control Commands"
3498 .\" --------------------------------------------------------------------
3500 There is a continuation convention which permits the argument to the
3502 command to contain newlines: when outputting the argument to the
3504 command, GNU troff follows each newline in the argument with a
3506 character (as usual, it terminates the entire argument with a
3507 newline); thus if the line after the line containing the
3511 then the newline ending the line containing the
3513 command should be treated as part of the argument to the
3517 should be ignored, and the part of the line following the
3519 should be treated like the part of the line following the
3524 The first three output commands are guaranteed to be:
3533 .\" --------------------------------------------------------------------
3534 .SH INCOMPATIBILITIES
3535 .\" --------------------------------------------------------------------
3537 In spite of the many extensions, groff has retained compatibility to
3538 classical troff to a large degree.
3540 For the cases where the extensions lead to collisions, a special
3541 compatibility mode with the restricted, old functionality was created
3545 .\" --------------------------------------------------------------------
3546 .SS "Groff Language"
3547 .\" --------------------------------------------------------------------
3551 .B compatibility mode
3552 that allows to process roff code written for classical
3554 or for other implementations of roff in a consistent way.
3557 Compatibility mode can be turned on with the
3559 command line option, and turned on or off with the
3565 is\~1 if compatibility mode is on, 0\~otherwise.
3568 This became necessary because the GNU concept for long names causes
3569 some incompatibilities.
3576 as defining a string
3582 mode, this is considered as a call of a macro named
3592 as references to a string or number register called\~\c
3596 takes this as the start of a long name.
3600 .IR "compatibility mode" ,
3601 groff interprets these things in the traditional way; so long
3602 names are not recognized.
3605 On the other hand, groff in
3607 does not allow to use the single-character escapes
3636 (character\~c) in names of strings, macros, diversions, number
3637 registers, fonts or environments, whereas
3644 escape sequence can be helpful in avoiding these escape sequences in
3648 Fractional point sizes cause one noteworthy incompatibility.
3655 request ignores scale indicators and so
3662 sets the point size to 10\~points, whereas in groff native mode the
3663 point size is set to 10\~scaled points.
3668 there is a fundamental difference between unformatted input
3669 characters, and formatted output characters (glyphs).
3671 Everything that affects how a glyph is output is
3672 stored with the glyph; once a glyph has been
3673 constructed it is unaffected by any subsequent requests that are
3674 executed, including the
3684 Normally glyphs are constructed from input characters at
3685 the moment immediately before the glyph is added to the current
3688 Macros, diversions and strings are all, in fact, the same type of
3689 object; they contain lists of input characters and glyphs
3693 Special characters can be both; before being added to the output, they
3694 act as input entities, afterwards they denote glyphs.
3697 A glyph does not behave like an input character for the
3698 purposes of macro processing; it does not inherit any of the special
3699 properties that the input character from which it was constructed
3702 The following example makes things clearer.
3708 \[rs]\[rs]\[rs]\[rs]
3720 So each pair of input backslashes
3722 is turned into a single output backslash glyph
3724 and the resulting output backslashes are not interpreted as escape
3725 characters when they are reread.
3729 would interpret them as escape characters when they were reread and
3730 would end up printing a single backslash `\[rs]'.
3733 In GNU, the correct way to get a printable version of the backslash
3737 escape sequence, but classical troff does not provide a clean feature
3738 for getting a non-syntactical backslash.
3740 A close method is the printable version of the current escape
3743 escape sequence; this works if the current escape character is not
3746 It works in both GNU mode and compatibility mode, while dirty tricks
3747 like specifying a sequence of multiple backslashes do not work
3748 reliably; for the different handling in diversions, macro definitions,
3749 or text mode quickly leads to a confusion about the necessary number of
3753 To store an escape sequence in a diversion that is interpreted
3754 when the diversion is reread, either the traditional
3756 transparent output facility or the
3759 escape sequence can be used.
3762 .\" --------------------------------------------------------------------
3763 .SS "Intermediate Output"
3764 .\" --------------------------------------------------------------------
3766 The groff intermediate output format is in a state of evolution.
3768 So far it has some incompatibilities, but it is intended to establish
3769 a full compatibility to the classical troff output format.
3771 Actually the following incompatibilities exist:
3774 The positioning after the drawing of the polygons conflicts with the
3775 classical definition.
3778 The intermediate output cannot be rescaled to other devices as
3779 classical `device-independent' troff did.
3782 .\" --------------------------------------------------------------------
3784 .\" --------------------------------------------------------------------
3786 Copyright (C) 1989, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009
3787 Free Software Foundation, Inc.
3790 This document is distributed under the terms of the FDL (GNU Free
3791 Documentation License) version 1.3 or later.
3793 You should have received a copy of the FDL on your system, it is also
3794 available on-line at the
3795 .UR http://\:www.gnu.org/\:copyleft/\:fdl.html
3799 This document was written by James Clark, with modifications by
3809 This document is part of
3811 the GNU roff distribution.
3813 Formerly, the contents of this document was kept in the manual
3815 .BR @g@troff (@MAN1EXT@).
3816 Only the parts dealing with the language aspects of the different
3818 systems were carried over into this document.
3822 command line options and warnings are still documented in
3823 .BR @g@troff (@MAN1EXT@).
3825 .\" --------------------------------------------------------------------
3827 .\" --------------------------------------------------------------------
3834 presents all groff documentation within a single document.
3837 .BR groff (@MAN1EXT@)
3838 A list of all documentation around
3842 .BR groff (@MAN7EXT@)
3843 A description of the
3845 language, including a short, but complete reference of all predefined
3846 requests, registers, and escapes of plain
3848 From the command line, this is called using
3858 .BR roff (@MAN7EXT@)
3861 systems, including pointers to further historical documentation.
3866 .I Nroff/\:Troff User's Manual
3868 .I J.\& F.\& Ossanna
3869 of 1976 in the revision of
3872 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:54.ps.gz
3873 classical troff documentation
3876 .\" --------------------------------------------------------------------
3878 .\" --------------------------------------------------------------------
3880 .\" Local Variables: