2 .\" The above line should force the use of eqn as a preprocessor
3 .TH GROFF_DIFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
5 groff_diff \- differences between GNU troff and classical troff
8 .\" Source file position: <groff_source>/man/groff_diff.man
9 .\" Installed position: <prefix>/share/man/man7/groff_diff.7
13 Copyright \[co] 1989-2014 Free Software Foundation, Inc.
16 This file is part of groff, the GNU roff type-setting system.
18 It is the source of the man-page groff_diff(7).
20 Permission is granted to copy, distribute and/or modify this document
21 under the terms of the GNU Free Documentation License, Version 1.3 or
22 any later version published by the Free Software Foundation; with no
23 Front-Cover Texts, and with no Back-Cover Texts.
25 A copy of the Free Documentation License is included as a file called
26 FDL in the main directory of the groff source package, it is also
27 available in the internet at
28 .UR http://\:www.gnu.org/\:copyleft/\:fdl.html
34 This document was written by
43 .MT groff-bernd.warken-72@web.de
49 .\" --------------------------------------------------------------------
51 .\" --------------------------------------------------------------------
53 .\" define a string tx for the TeX logo
54 .ie t .ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
58 .\" from old groff_out.man
65 .ds ellipsis \&.\|.\|.\&
68 .\" --------------------------------------------------------------------
70 .\" --------------------------------------------------------------------
72 This manual page describes the language differences between
76 text processing system, and the classical
78 formatter of the freely available Unix\~7 of the 1970s, documented in
80 .I Troff User\[aq]s Manual
86 This includes the roff language as well as the intermediate output
87 format (troff output).
93 gives pointers to both the classical
100 .\" --------------------------------------------------------------------
102 .\" --------------------------------------------------------------------
104 In this section, all additional features of
106 compared to the classical Unix\~7
108 are described in detail.
111 .\" --------------------------------------------------------------------
113 .\" --------------------------------------------------------------------
115 The names of number registers, fonts, strings/\:macros/\:diversions,
116 special characters (glyphs), and colors can be of any length.
118 In escape sequences, additionally to the classical
119 \[oq]\fB(\fP\fIxx\fP\[cq] construction for a two-character glyph name,
120 you can use \[oq]\fB[\fP\,\fIxxx\/\fP\fB]\fP\[cq] for a name of
125 Print the special character (glyph) called
129 .BI \[rs][ "comp1 comp2 \*[ellipsis]" ]
130 Print composite glyph consisting of multiple components.
132 Example: \[oq]\[rs][A\~ho]\[cq] is capital letter A with ogonek which
133 finally maps to glyph name \[oq]u0041_0328\[cq].
137 for details how a glyph name for a composite glyph is constructed, and
138 .BR groff_char (@MAN7EXT@)
139 for a list of glyph name components used in composite glyph names.
148 is a new syntax form equal to
150 i.e., to return to the previous font.
153 .BI \[rs]*[ "xxx arg1 arg2 \*[ellipsis]" ]
164 Interpolate number register
168 .\" --------------------------------------------------------------------
169 .SS "Fractional point sizes"
170 .\" --------------------------------------------------------------------
182 There is a new scale indicator\~\c
184 that has the effect of multiplying by sizescale.
186 Requests and escape sequences in troff interpret arguments that
187 represent a point size as being in units of scaled points, but they
188 evaluate each such argument using a default scale indicator of\~\c
190 Arguments treated in this way are the argument to the
192 request, the third argument to the
194 request, the second and fourth arguments to the
196 request, the argument to the
198 escape sequence, and those variants of the
200 escape sequence that take a numeric expression as their argument.
204 For example, suppose sizescale is 1000; then a scaled point is
205 equivalent to a millipoint; the call
209 and so sets the point size to 10250 scaled points, which is equal to
216 returns the point size in points as decimal fraction.
218 There is also a new number register
220 that returns the point size in scaled points.
224 It would make no sense to use the
226 scale indicator in a numeric expression whose default scale indicator
235 Similarly it would make no sense to use a scaling indicator other than
239 in a numeric expression whose default scale indicator was\~\c
243 disallows this as well.
246 There is also new scale indicator\~\c
248 which multiplies by the number of units in a scaled point.
254 Be sure not to confuse the
261 .\" --------------------------------------------------------------------
262 .SS "Numeric expressions"
263 .\" --------------------------------------------------------------------
265 Spaces are permitted in a number expression within parentheses.
270 indicates a scale of 100ths of an em.
272 indicates a scale of 65536 units, providing fractions for color
277 For example, 0.5f = 32768u.
299 as the default scaling indicator.
303 is missing, ignore scaling indicators in the evaluation of\~\c
307 .\" --------------------------------------------------------------------
308 .SS "New escape sequences"
309 .\" --------------------------------------------------------------------
312 .BI \[rs]A' anything '
319 is or is not acceptable as the name of a string, macro, diversion, number
320 register, environment, font, or color.
328 This is useful if you want to look up user input in some sort of
332 .BI \[rs]B' anything '
339 is or is not a valid numeric expression.
351 Normally it is more convenient to use
352 .BI \[rs][ xxx ]\f[R].
355 has the advantage that it is compatible with recent versions of
357 and is available in compatibility mode.
361 This is equivalent to an escape character, but it is not interpreted in
364 For example, strings to start and end superscripting could be defined
370 \&.ds { \[rs]v'\-.3m'\[rs]s'\[rs]En[.s]*6u/10u'
371 \&.ds } \[rs]s0\[rs]v'.3m'
378 ensures that these definitions work even if
380 gets interpreted in copy mode (for example, by being used in a macro
392 This is the same as the
397 switches back to the previous font family (note that
399 won\[aq]t work; it selects font family \[oq]P\[cq] instead).
409 switches back to the previous color.
417 Set background color for filled objects drawn with the
418 .BI \[rs]D' \*[ellipsis] '
421 switches back to the previous color.
425 Typeset the glyph with index\~\c
431 Most devices only have glyphs with indices between 0 and 255.
433 If the current font does not contain a glyph with that code,
440 escape sequence can be conveniently used in conjunction with the
447 \&.char \[rs][phone] \[rs]f(ZD\[rs]N'37'
452 The index of each glyph is given in the fourth column in the font
453 description file after the
457 It is possible to include unnamed glyphs in the font description
458 file by using a name of
462 escape sequence is the only way to use these.
468 Suppress troff output.
476 are intended for internal use by
482 Disable any ditroff glyphs from being emitted to the device driver,
483 provided that the escape occurs at the outer level (see
490 Enable output of glyphs, provided that the escape occurs at the outer
496 also reset the registers
504 These four registers mark the top left and bottom right hand corners
505 of a box which encompasses all written glyphs.
509 Provided that the escape occurs at the outer level, enable output of
510 glyphs and also write out to stderr the page number and four registers
511 encompassing the glyphs previously written since the last call to
516 Begin a nesting level.
522 This is really an internal mechanism for
524 while producing images.
526 They are generated by running the troff source through
528 to the postscript device and
530 to produce images in PNG format.
534 escape starts a new page if the device is not html (to reduce the
535 possibility of images crossing a page boundary).
542 .BI \[rs]O5[ Pfilename ]
547 Provided that this escape occurs at the outer nesting level, write
551 The position of the image,
553 must be specified and must be one of
559 (left, right, centered, inline).
562 is associated with the production of the next inline image.
566 .BI \[rs]R' name\ \[+-]n '
567 This has the same effect as
571 .BI .nr\ name\ \[+-]n
578 Set the point size to
582 must be exactly two digits.
592 Set the point size to
596 is a numeric expression with a default scale indicator of\~\c
605 Interpolate the contents of the environment variable
610 is interpreted in copy mode.
618 This is approximately equivalent to
619 .BI \[rs]X'\[rs]*[ xxx ]'\f[R].
620 However the contents of the string or macro
622 are not interpreted; also it is permitted for
624 to have been defined as a macro and thus contain newlines (it is not
625 permitted for the argument to
627 to contain newlines).
629 The inclusion of newlines requires an extension to the UNIX troff
630 output format, and confuses drivers that do not know about this
634 .BI \[rs]Z' anything '
635 Print anything and then restore the horizontal and vertical position;
637 may not contain tabs or leaders.
641 The name by which the current macro was invoked.
645 request can make a macro have more than one name.
649 In a macro or string, the concatenation of all the arguments separated
654 In a macro or string, the concatenation of all the arguments with each
655 surrounded by double quotes, and separated by spaces.
659 In a macro, the representation of all parameters as if they were an
668 In a macro or string, this gives the
674 Macros and strings can have an unlimited number of arguments.
677 .BI \[rs]? anything \[rs]?
678 When used in a diversion, this transparently embeds
682 is read in copy mode.
684 When the diversion is reread,
688 may not contain newlines; use
690 if you want to embed newlines in a diversion.
694 is also recognized in copy mode and turned into a single internal
695 code; it is this code that terminates
706 \&\[rs]?\[rs]\[rs]?\[rs]\[rs]\[rs]\[rs]?\[rs]\[rs]\[rs]\[rs]\[rs]\[rs]\[rs]\c
707 \&\[rs]nx\[rs]\[rs]\[rs]\[rs]?\[rs]\[rs]?\[rs]?
728 This increases the width of the preceding glyph so that the
729 spacing between that glyph and the following glyph is
730 correct if the following glyph is a roman glyph.
733 . nop For example, if an italic\~f is immediately followed by a roman
734 . nop right parenthesis, then in many fonts the top right portion of
735 . nop the\~f overlaps the top left of the right parenthesis
736 . nop producing \f[I]f\f[R]), which is ugly.
740 . ie \n(.g \f[I]f\/\f[R])
742 . nop and avoids this problem.
744 It is a good idea to use this escape sequence whenever an italic
745 glyph is immediately followed by a roman glyph without any
750 This modifies the spacing of the following glyph so that the
751 spacing between that glyph and the preceding glyph is
752 correct if the preceding glyph is a roman glyph.
755 . nop For example, inserting
757 . nop between the parenthesis and the\~f changes
758 . nop \f[R](\f[I]f\f[R] to
759 . ie \n(.g \f[R](\,\f[I]f\f[R].
760 . el \f[R](\^\f[I]f\f[R].
762 It is a good idea to use this escape sequence whenever a roman
763 glyph is immediately followed by an italic glyph without any
770 except that it behaves like a character declared with the
772 request to be transparent for the purposes of end-of-sentence
777 This produces an unbreakable space that stretches like a normal
778 inter-word space when a line is adjusted.
782 This causes the insertion of a zero-width break point.
786 within a word but without insertion of a soft hyphen glyph.
790 Everything up to and including the next newline is ignored.
792 This is interpreted in copy mode.
798 does not ignore the terminating newline.
801 .\" --------------------------------------------------------------------
803 .\" --------------------------------------------------------------------
809 for number register object named
811 The new name and the old name are exactly equivalent.
815 is undefined, a warning of type
817 is generated, and the request is ignored.
823 for request, string, macro, or diversion object named
826 The new name and the old name are exactly equivalent (it is
827 similar to a hard rather than a soft link).
831 is undefined, a warning of type
833 is generated, and the request is ignored.
843 requests only create a new object if the name of the macro, diversion
844 or string is currently undefined or if it is defined to be a
845 request; normally they modify the value of an existing object.
851 but compatibility mode is switched off during execution.
853 To be more precise, a \[oq]compatibility save\[cq] token is inserted
854 at the beginning of the macro addition, and a \[oq]compatibility
855 restore\[cq] token at the end.
857 As a consequence, the requests
863 can be intermixed freely since the compatibility save/\:restore tokens
864 only affect the macro parts defined by
871 Append to macro indirectly.
875 request below for more information.
881 request but compatibility mode is switched off during execution.
887 but compatibility mode is switched off during expansion.
889 To be more precise, a \[oq]compatibility save\[cq] token is inserted
890 at the beginning of the string, and a \[oq]compatibility restore\[cq]
893 As a consequence, the requests
899 can be intermixed freely since the compatibility save/\:restore tokens
900 only affect the (sub)strings defined by
907 This request \[oq]unformats\[cq] the diversion
911 and space characters (and some escape sequences) that were formatted
914 are treated like ordinary input characters when
917 Useful for diversions in conjunction with the
921 It can be also used for gross hacks; for example, this
943 Note that glyph information (font, font size, etc.\&) is not preserved;
950 Print a backtrace of the input stack on stderr.
954 Set the blank line macro to
956 If there is a blank line macro, it is invoked when a blank line
957 is encountered instead of the usual troff behaviour.
963 These requests are similar to the
967 requests with the exception that a partially filled line does not
968 become part of the diversion (i.e., the diversion always starts with a
969 new line) but is restored after ending the diversion, discarding the
970 partially filled line which possibly comes from the diversion.
974 Break out of a while loop.
982 Be sure not to confuse this with the
992 .BI .cflags\ "n c1 c2 \*[ellipsis]"
997 have properties determined by
999 which is ORed from the following:
1003 The character ends sentences (initially characters
1005 have this property).
1008 Lines can be broken before the character (initially no characters have
1009 this property); a line is not broken at a character with this property
1010 unless the characters on each side both have non-zero hyphenation
1012 This can be overridden with value 64.
1015 Lines can be broken after the character (initially characters
1016 .B \-\[rs][hy]\[rs][em]
1017 have this property); a line is not broken at a character with this
1018 property unless the characters on each side both have non-zero
1020 This can be overridden with value 64.
1023 The glyph associated with this character overlaps horizontally
1024 (initially characters
1025 .B \[rs][ul]\[rs][rn]\[rs][ru]\[rs][radicalex]\[rs][sqrtex]
1026 have this property).
1029 The glyph associated with this character overlaps vertically
1035 An end-of-sentence character followed by any number of characters with
1036 this property is treated as the end of a sentence if followed by a
1037 newline or two spaces; in other words the character is transparent for
1038 the purposes of end-of-sentence recognition; this is the same as having
1039 a zero space factor in \*[tx] (initially characters
1040 .B \[dq]')]*\[rs][dg]\[rs][rq]\[rs][cq]
1041 have this property).
1044 Ignore hyphenation code values of the surrounding characters.
1045 Use this in combination with values 2 and\~4 (initially no characters
1046 have this property).
1049 Prohibit a line break before the character, but allow a line break after the
1051 This works only in combination with flags 256 and 512 and has no effect
1055 Prohibit a line break after the character, but allow a line break before
1057 This works only in combination with flags 128 and 512 and has no effect
1061 Allow line break before or after the character.
1062 This works only in combination with flags 128 and 256 and has no effect
1067 Contrary to flag values 2 and\~4, the flags 128, 256, and 512 work
1070 If, for example, the left character has value 512, and the right
1071 character 128, no line break gets inserted. If we use value\~6
1072 instead for the left character, a line break after the character
1073 can\[aq]t be suppressed since the right neighbour character
1074 doesn\[aq]t get examined.
1077 .BI .char\ c\ string
1078 [This request can both define characters and glyphs.]
1086 To be more precise, define (or even override) a groff entity which
1087 can be accessed with name\~\c
1089 on the input side, and which uses
1093 Every time glyph\~\c
1095 needs to be printed,
1097 is processed in a temporary environment and the result is
1098 wrapped up into a single object.
1100 Compatibility mode is turned off and the escape character is
1107 Any emboldening, constant spacing or track kerning is applied to
1108 this object rather than to individual glyphs in
1112 A groff object defined by this request can be used just like a
1113 normal glyph provided by the output device.
1115 In particular other characters can be translated to it with the
1117 request; it can be made the leader glyph by the
1119 request; repeated patterns can be drawn with the glyph using the
1123 escape sequences; words containing\~\c
1125 can be hyphenated correctly, if the
1127 request is used to give the object a hyphenation code.
1130 There is a special anti-recursion feature: Use of glyph within the
1131 glyph\[aq]s definition is handled like normal glyphs not defined with
1134 A glyph definition can be removed with the
1140 Chop the last element off macro, string, or diversion
1142 This is useful for removing the newline from the end of diversions
1143 that are to be interpolated as strings.
1146 .BI .class\ "name c1 c2 \*[ellipsis]"
1149 to a set of characters
1153 so that they can be referred to from other requests easily (currently
1157 Character ranges (indicated by an intermediate \[oq]\-\[cq]) and
1158 nested classes are possible also.
1160 This is useful to assign properties to a large set of characters.
1164 Close the stream named
1167 will no longer be an acceptable argument to the
1176 .BI .composite\ glyph1\ glyph2
1182 .BI \[rs][ \*[ellipsis] ]
1183 with more than one component.
1187 Finish the current iteration of a while loop.
1199 is non-zero or missing, enable colors (this is the default), otherwise
1206 is non-zero or missing, enable compatibility mode, otherwise disable
1209 In compatibility mode, long names are not recognized, and the
1210 incompatibilities caused by long names do not arise.
1213 .BI .defcolor\ xxx\ scheme\ color_components
1217 can be one of the following values:
1223 (four components), and
1229 Color components can be given either as a hexadecimal string or as
1230 positive decimal integers in the range 0\[en]65535.
1232 A hexadecimal string contains all color components concatenated; it
1233 must start with either
1237 The former specifies hex values in the range 0\[en]255 (which are
1238 internally multiplied by\~257), the latter in the range 0\[en]65535.
1240 Examples: #FFC0CB (pink), ##ffff0000ffff (magenta).
1242 A new scaling indicator\~\c
1244 has been introduced which multiplies its value by\~65536; this makes
1245 it convenient to specify color components as fractions in the range 0
1253 \&.defcolor darkgreen rgb 0.1f 0.5f 0.2f
1260 is the default scaling indicator for the
1262 request, thus the above statement is equivalent to
1267 \&.defcolor darkgreen rgb 0.1 0.5 0.2
1274 (which is device-specific) can\[aq]t be redefined.
1276 It is possible that the default color for
1286 but compatibility mode is switched off during execution.
1288 On entry, the current compatibility mode is saved and restored at exit.
1292 Define macro indirectly.
1294 The following example
1320 request but compatibility mode is switched off during execution.
1323 .BI .device\ anything
1324 This is (almost) the same as the
1328 is read in copy mode; a leading\~\c
1334 This is the same as the
1336 escape (to embed the contents of a macro into the intermediate
1337 output preceded with \[oq]x\~X\[cq]).
1343 with compatibility mode disabled.
1355 would have the same effect as
1363 except that it would work even if compatibility mode had been enabled.
1365 Note that the previous compatibility mode is restored before any files
1376 but compatibility mode is switched off during expansion.
1378 To be more precise, a \[oq]compatibility save\[cq] token is inserted
1379 at the beginning of the string, and a \[oq]compatibility restore\[cq]
1384 Save current escape character.
1388 Restore escape character saved with
1390 Without a previous call to
1392 .RB \[oq] \[rs] \[cq]
1393 will be the new escape character.
1397 Copy the contents of environment
1399 to the current environment.
1401 No pushing or popping of environments is done.
1405 Set the current font family to
1407 The current font family is part of the current environment.
1410 is missing, switch back to previous font family.
1412 The value at start-up is \[oq]T\[cq].
1414 See the description of the
1416 request for more information on font families.
1419 .BI .fchar\ c\ string
1420 Define fallback character (or glyph)\~\c
1425 The syntax of this request is the same as the
1427 request; the only difference is that a glyph defined with
1429 hides the glyph with the same name in the current font, whereas a
1432 is checked only if the particular glyph isn\[aq]t found in the current
1435 This test happens before checking special fonts.
1439 Set the fill color to\~\c
1444 switch to the previous fill color.
1447 .BI .fschar\ f\ c\ string
1448 Define fallback character (or glyph)\~\c
1455 The syntax of this request is the same as the
1457 request (with an additional argument to specify the font); a glyph
1460 is searched after the list of fonts declared with the
1462 request but before the list of fonts declared with
1466 .BI .fspecial\ "f s1 s2 \*[ellipsis]"
1467 When the current font is\~\c
1473 are special, that is, they are searched for glyphs not in
1476 Any fonts specified in the
1478 request are searched after fonts specified in the
1482 Without argument, reset the list of global special fonts to be empty.
1490 Whenever a font named\~\c
1492 is referred to in an
1494 escape sequence, in the
1498 conditional operators, or in the
1514 is missing, or equal to\~\c
1527 must a non-negative integer multiple of 1/1000th.
1528 If it is missing or is equal to zero, it means the same as 1000, namely no
1531 must be a real font name, not a style.
1535 Set the glyph color to\~\c
1540 switch to the previous glyph color.
1543 .BI .hcode\ "c1 code1 c2 code2 \*[ellipsis]"
1544 Set the hyphenation code of character
1553 A hyphenation code must be a single input character (not a special
1554 character) other than a digit or a space.
1556 Initially each lower-case letter \%a\[en]z has a hyphenation code, which is
1557 itself, and each upper-case letter \%A\[en]Z has a hyphenation code which is
1558 the lower-case version of itself.
1566 Set the current hyphenation language to
1568 Hyphenation exceptions specified with the
1570 request and hyphenation patterns specified with the
1572 request are both associated with the current hyphenation language.
1576 request is usually invoked by the
1578 file to set up a default language.
1582 Set the maximum number of consecutive hyphenated lines to\~\c
1586 is negative, there is no maximum.
1588 The default value is\~\-1.
1590 This value is associated with the current environment.
1592 Only lines output from an environment count towards the maximum
1593 associated with that environment.
1595 Hyphens resulting from
1597 are counted; explicit hyphens are not.
1601 Read hyphenation patterns from
1603 this is searched for in the same way that
1605 is searched for when the
1607 option is specified.
1609 It should have the same format as (simple) \*[tx] patterns files.
1611 More specifically, the following scanning rules are implemented.
1615 A percent sign starts a comment (up to the end of the line) even if
1616 preceded by a backslash.
1619 No support for \[oq]digraphs\[cq] like
1625 is 0\[en]9 or a\[en]f) and
1627 (character code of\~\c
1629 in the range 0\[en]127) are recognized; other use of\~\c
1638 checks for the expression
1639 .BR \[rs]patterns{ \*[ellipsis] }
1640 (possibly with whitespace before and after the braces).
1642 Everything between the braces is taken as hyphenation patterns.
1648 are not allowed in patterns.
1652 .BR \[rs]hyphenation{ \*[ellipsis] }
1653 gives a list of hyphenation exceptions.
1660 For backwards compatibility, if
1662 is missing, the whole file is treated as a list of hyphenation patterns
1663 (only recognizing the
1665 character as the start of a comment).
1671 request to map the encoding used in hyphenation patterns files to
1675 By default, everything maps to itself except letters \[oq]A\[cq] to
1676 \[oq]Z\[cq] which map to \[oq]a\[cq] to \[oq]z\[cq].
1679 The set of hyphenation patterns is associated with the current language
1686 request is usually invoked by the
1688 file; a second call replaces the old patterns with the new ones.
1694 except that the hyphenation patterns from
1696 are appended to the patterns already loaded in the current language.
1699 .BI .hpfcode\ "a b c d \*[ellipsis]"
1700 After reading a hyphenation patterns file with the
1704 request, convert all characters with character code\~\c
1706 in the recently read patterns to character code\~\c
1714 Initially, all character codes map to themselves.
1718 must be integers in the range 0 to\~255.
1720 Note that it is even possible to use character codes which are invalid in
1727 .I hyphenation margin
1730 when the current adjustment mode is not\~\c
1732 the line is not hyphenated if the line is no more than
1736 The default hyphenation margin is\~0.
1738 The default scaling indicator for this request is\~\c
1740 The hyphenation margin is associated with the current environment.
1742 The current hyphenation margin is available in the
1749 .I hyphenation space
1752 When the current adjustment mode is\~\c
1754 don\[aq]t hyphenate the line if the line can be justified by adding no
1757 extra space to each word space.
1759 The default hyphenation space is\~0.
1761 The default scaling indicator for this request is\~\c
1763 The hyphenation space is associated with the current environment.
1765 The current hyphenation space is available in the
1773 for which a line interrupted with
1775 counts as one input line.
1781 is non-zero or missing, enable pairwise kerning, otherwise disable it.
1784 .BI .length\ xx\ string
1785 Compute the length of
1787 and return it in the number register
1789 (which is not necessarily defined before).
1795 is non-zero or missing, enable line-tabs mode, otherwise disable it
1796 (which is the default).
1798 In line-tabs mode, tab distances are computed relative to the
1799 (current) output line.
1801 Otherwise they are taken relative to the input line.
1803 For example, the following
1809 \&.ds x a\[rs]t\[rs]c
1810 \&.ds y b\[rs]t\[rs]c
1830 In line-tabs mode, the same code gives
1840 Line-tabs mode is associated with the current environment; the
1841 read-only number register
1842 .B \[rs]n[.linetabs]
1843 is set to\~1 if in line-tabs mode, and 0 otherwise.
1847 Set the leading spaces macro to
1849 If there are leading spaces in an input line, it is invoked instead of
1850 the usual troff behaviour; the leading spaces are removed.
1855 hold the number of removed leading spaces and the corresponding
1856 horizontal space, respectively.
1864 is searched for in the same directories as macro files for the the
1866 command line option.
1868 If the file name to be included has the form
1870 and it isn\[aq]t found,
1874 instead and vice versa.
1880 can\[aq]t be loaded, and the request is ignored.
1886 This is similar to \[oq].if\ 1\[cq].
1892 built-in condition true and the
1894 built-in condition false.
1896 This can be reversed using the
1901 .BI .open\ stream\ filename
1904 for writing and associate the stream named
1915 .BI .opena\ stream\ filename
1920 exists, append to it instead of truncating it.
1926 directly to the intermediate output (subject to copy-mode interpretation);
1929 used at the top level.
1931 An initial double quote in
1933 is stripped off to allow initial blanks.
1937 Print the current environment and each defined environment state on
1942 Print the names and contents of all currently defined number registers
1946 .BI .psbb \ filename
1947 Get the bounding box of a PostScript image
1950 This file must conform to Adobe\[aq]s Document Structuring
1951 Conventions; the command looks for a
1953 comment to extract the bounding box values.
1955 After a successful call, the coordinates (in PostScript units) of the
1956 lower left and upper right corner can be found in the registers
1964 If some error has occurred, the four registers are set to zero.
1968 This behaves like the
1970 request except that input comes from the standard output of
1975 Print the names and positions of all traps (not including input line
1976 traps and diversion traps) on stderr.
1978 Empty slots in the page trap list are printed as well, because they
1979 can affect the priority of subsequently planted traps.
1983 Set the post-vertical line space to\~\c
1985 default scale indicator is\~\c
1988 This value is added to each line after it has been output.
1990 With no argument, the post-vertical line space is set to its previous
1994 The total vertical line spacing consists of four components:
1998 with a negative value which are applied before the line is output, and
2002 with a positive value which are applied after the line is output.
2005 .BI .rchar\ "c1 c2 \*[ellipsis]"
2006 Remove the definitions of glyphs
2010 This undoes the effect of a
2016 Within a macro, return immediately.
2018 If called with an argument, return twice, namely from the current macro and
2019 from the macro one level higher.
2021 No effect otherwise.
2024 .BI .rfschar\ "c1 c2 \*[ellipsis]"
2025 Remove the font-specific definitions of glyphs
2029 This undoes the effect of a
2037 Right justify the next
2041 Without an argument right justify the next input line.
2043 The number of lines to be right justified is available in the
2047 This implicitly does
2051 request implicitly does
2056 Rename number register
2062 .BI .schar\ c\ string
2063 Define global fallback character (or glyph)\~\c
2068 The syntax of this request is the same as the
2070 request; a glyph defined with
2072 is searched after the list of fonts declared with the
2074 request but before the mounted special fonts.
2078 Set the soft hyphen character to\~\c
2082 is omitted, the soft hyphen character is set to the default
2084 The soft hyphen character is the glyph which is inserted when
2085 a word is hyphenated at a line break.
2087 If the soft hyphen character does not exist in the font of the
2088 glyph immediately preceding a potential break point, then the line
2089 is not broken at that point.
2091 Neither definitions (specified with the
2093 request) nor translations (specified with the
2095 request) are considered when finding the soft hyphen character.
2099 In a macro, shift the arguments by
2101 positions: argument\~\c
2107 are no longer available.
2111 is missing, arguments are shifted by\~1.
2113 Shifting by negative amounts is currently undefined.
2116 .BI .sizes\ s1\ s2\ \*[ellipsis]\ sn\ [0]
2117 This command is similar to the
2123 It sets the available font sizes for the current font to
2126 .IR \*[ellipsis]\| ,\~ sn
2129 The list of sizes can be terminated by an optional\~\c
2134 can also be a range of sizes
2137 Contrary to the font file command, the list can\[aq]t extend over more
2141 .BI .special\ "s1 s2 \*[ellipsis]"
2146 are special and are searched for glyphs not in the current
2149 Without arguments, reset the list of special fonts to be empty.
2152 .BI .spreadwarn\ limit
2155 emit a warning if the additional space inserted for each space between
2156 words in an output line is larger or equal to
2159 A negative value is changed to zero; no argument toggles the warning on
2160 and off without changing
2163 The default scaling indicator is\~\c
2173 .B .spreadwarn\ 0.2m
2176 must add 0.2m or more for each interword space in a line.
2178 This request is active only if text is justified to both margins (using
2185 with font position\~\c
2187 A font position can be associated either with a font or with a style.
2189 The current font is the index of a font position and so is also either
2192 When it is a style, the font that is actually used is the font the
2193 name of which is the concatenation of the name of the current family
2194 and the name of the current style.
2196 For example, if the current font is\~1 and font position\~1 is
2197 associated with style\~\c
2199 and the current font family is\~\c
2205 If the current font is not a style, then the current family is ignored.
2214 are applied to a style, then they are applied instead to the
2215 member of the current family corresponding to that style.
2217 The default family can be set with the
2219 command line option.
2225 file controls which font positions (if any) are initially associated
2226 with styles rather than fonts.
2229 .BI .substring\ xx\ n1\ [ n2 ]
2230 Replace the string named
2232 with the substring defined by the indices
2236 The first character in the string has index\~0.
2240 is omitted, it is taken to be equal to the string\[aq]s length.
2246 is negative, it is counted from the end of the string,
2249 The last character has index\~\-1, the character before the last
2250 character has index\~\-2, etc.
2253 .BI .tkf\ f\ s1\ n1\ s2\ n2
2254 Enable track kerning for font\~\c
2256 When the current font is\~\c
2258 the width of every glyph is increased by an amount between
2262 when the current point size is less than or equal to
2264 the width is increased by
2266 when it is greater than or equal to
2268 the width is increased by
2270 when the point size is greater than or equal to
2272 and less than or equal to
2274 the increase in width is a linear function of the point size.
2282 is read in copy mode and written on the standard error, but an initial
2285 is stripped off to allow initial blanks.
2291 but without writing a final newline.
2295 Transparently output the contents of file
2297 Each line is output as if preceded by
2299 however, the lines are not subject to copy-mode interpretation.
2301 If the file does not end with a newline, then a newline is added.
2303 For example, you can define a macro\~\c
2305 containing the contents of file\~\c
2322 request, the file cannot contain characters such as
2324 that are not valid troff input characters.
2328 This is the same as the
2330 request except that the
2332 request uses the character code (if any) before the character
2363 This is the same as the
2365 request except that the translations do not apply to text that is
2366 transparently throughput into a diversion with
2396 built-in condition false, and the
2398 built-in condition true.
2400 This undoes the effect of the
2406 This request \[oq]unformats\[cq] the diversion
2411 request, which tries to convert formatted elements of the diversion
2412 back to input tokens as much as possible,
2414 only handles tabs and spaces between words (usually caused by spaces
2415 or newlines in the input) specially.
2417 The former are treated as if they were input tokens, and the latter
2418 are stretchable again.
2420 Note that the vertical size of lines is not preserved.
2422 Glyph information (font, font size, space width, etc.\&) is retained.
2424 Useful in conjunction with the
2432 Enable vertical position traps if
2434 is non-zero, disable them otherwise.
2436 Vertical position traps are traps set by the
2444 request are not vertical position traps.
2446 The parameter that controls whether vertical position traps are
2449 Initially vertical position traps are enabled.
2455 is the sum of the numbers associated with each warning that is to be
2456 enabled; all other warnings are disabled.
2458 The number associated with each warning is listed in
2459 .BR @g@troff (@MAN1EXT@).
2463 disables all warnings, and
2465 disables all warnings except that about missing glyphs.
2469 is not given, all warnings are enabled.
2473 Set the scaling indicator used in warnings to
2486 At startup, it is set to\~\c
2490 .BI .while \ c\ anything
2497 can be any condition acceptable to an
2501 can comprise multiple lines if the first line starts with
2503 and the last line ends with
2512 .BI .write\ stream\ anything
2518 must previously have been the subject of an
2522 is read in copy mode;
2528 .BI .writec\ stream\ anything
2531 but without writing a final newline.
2534 .BI .writem\ stream\ xx
2535 Write the contents of the macro or string
2540 must previously have been the subject of an
2544 is read in copy mode.
2547 .\" --------------------------------------------------------------------
2548 .SS "Extended escape sequences"
2549 .\" --------------------------------------------------------------------
2552 .BR \[rs]D' \*[ellipsis] '
2553 All drawing commands of groff\[aq]s intermediate output are accepted.
2556 .B "Drawing Commands"
2557 below for more information.
2560 .\" --------------------------------------------------------------------
2561 .SS "Extended requests"
2562 .\" --------------------------------------------------------------------
2566 When used in a diversion, this embeds in the diversion an object
2567 which, when reread, will cause the contents of
2569 to be transparently copied through to the output.
2571 In UNIX troff, the contents of
2573 is immediately copied through to the output regardless of whether
2574 there is a current diversion; this behaviour is so anomalous that it
2575 must be considered a bug.
2585 In compatibility mode, these requests behaves similar to
2591 respectively: A \[oq]compatibility save\[cq] token is inserted at the
2592 beginning, and a \[oq]compatibility restore\[cq] token at the end,
2593 with compatibility mode switched on during execution.
2599 is not a number, this switches to a named environment called
2601 The environment should be popped with a matching
2603 request without any arguments, just as for numbered environments.
2605 There is no limit on the number of named environments; they are
2606 created the first time that they are referenced.
2610 When two arguments are given to the
2612 request, the second argument gives the
2613 .IR "sentence space size" .
2614 If the second argument is not given, the sentence space size
2615 is the same as the word space size.
2617 Like the word space size, the sentence space is in units of
2618 one twelfth of the spacewidth parameter for the current font.
2620 Initially both the word space size and the sentence
2623 Contrary to UNIX troff, GNU troff handles this request in nroff mode
2624 also; a given value is then rounded down to the nearest multiple
2627 The sentence space size is used in two circumstances.
2629 If the end of a sentence occurs at the end of a line in fill mode,
2630 then both an inter-word space and a sentence space are added; if
2631 two spaces follow the end of a sentence in the middle of a line, then
2632 the second space is a sentence space.
2634 Note that the behaviour of UNIX troff are exactly that exhibited
2635 by GNU troff if a second argument is never given to the
2639 In GNU troff, as in UNIX troff, you should always follow a sentence
2640 with either a newline or two spaces.
2643 .BI .ta\ "n1 n2 \*[ellipsis] nn " "T " "r1 r2 \*[ellipsis] rn"
2644 Set tabs at positions
2649 and then set tabs at
2655 .IR nn \|+\| rn \|+\| r1 ,
2656 .IR nn \|+\| rn \|+\| r2 ,
2658 .IR nn \|+\| rn \|+\| rn ,
2669 sets tabs every half an inch.
2673 .\" --------------------------------------------------------------------
2674 .SS "New number registers"
2675 .\" --------------------------------------------------------------------
2677 The following read-only registers are available:
2681 Within a macro call, it is set to\~1 if the macro is called with the
2682 \[oq]normal\[cq] control character (\[oq].\[cq] by default), and set
2685 This allows to reliably modify requests.
2694 \&.ie \[rs]\[rs]n[.br] .bp*orig
2702 Using this register outside of a macro makes no sense (it always returns
2703 zero in such cases).
2707 1\~if compatibility mode is in effect, 0\~otherwise.
2711 The depth of the last glyph added to the current environment.
2713 It is positive if the glyph extends below the baseline.
2717 The number of lines remaining to be centered, as set by the
2723 The height of the last glyph added to the current environment.
2725 It is positive if the glyph extends above the baseline.
2729 1\~if colors are enabled, 0\~otherwise.
2733 The skew of the last glyph added to the current environment.
2737 of a glyph is how far to the right of the center of a glyph
2738 the center of an accent over that glyph should be placed.
2742 The name or number of the current environment.
2744 This is a string-valued register.
2748 The current font family.
2750 This is a string-valued register.
2754 The current (internal) real font name.
2756 This is a string-valued register.
2758 If the current font is a style, the value of
2760 is the proper concatenation of family and style name.
2764 The number of the next free font position.
2770 Macros should use this to determine whether they are running under GNU
2775 The current height of the font as set with
2780 The current hyphenation language as set by the
2786 The number of immediately preceding consecutive hyphenated lines.
2790 The maximum allowed number of consecutive hyphenated lines, as set by
2797 The current hyphenation flags (as set by the
2803 The current hyphenation margin (as set by the
2809 The current hyphenation space (as set by the
2815 The indentation that applies to the current output line.
2819 Set to a positive value if last output line is interrupted (i.e., if
2825 1\~if pairwise kerning is enabled, 0\~otherwise.
2829 The current ligature mode (as set by the
2834 .B \[rs]n[.linetabs]
2835 The current line-tabs mode (as set by the
2841 The line length that applies to the current output line.
2845 The title length as set by the
2851 The name of the current drawing color.
2853 This is a string-valued register.
2857 The name of the current background color.
2859 This is a string-valued register.
2863 The amount of space that was needed in the last
2865 request that caused a trap to be sprung.
2867 Useful in conjunction with the
2873 1\~if no-space mode is active, 0\~otherwise.
2877 The current output level as set with
2882 1\~if the current page is in the output list set with
2887 1\~during a page ejection caused by the
2889 request, 0\~otherwise.
2893 The number of the next page, either the value set by a
2895 request, or the number of the current page plus\~1.
2899 The current point size in scaled points.
2903 The last-requested point size in scaled points.
2907 The current post-vertical line space as set with the
2913 The number of lines to be right-justified as set by the
2919 The slant of the current font as set with
2924 The last requested point size in points as a decimal fraction.
2926 This is a string-valued register.
2932 These give the values of the parameters set by the first and second
2939 The current font style.
2941 This is a string-valued register.
2945 A string representation of the current tab settings suitable for use
2946 as an argument to the
2952 The amount of vertical space truncated by the most recently sprung
2953 vertical position trap, or, if the trap was sprung by a
2955 request, minus the amount of vertical motion produced by the
2959 In other words, at the point a trap is sprung, it represents the
2960 difference of what the vertical position would have been but for the
2961 trap, and what the vertical position actually is.
2963 Useful in conjunction with the
2969 Set to\~1 if in safer mode and to\~0 if in unsafe mode (as given with
2972 command line option).
2976 1\~if vertical position traps are enabled, 0\~otherwise.
2980 The sum of the numbers associated with each of the currently enabled
2983 The number associated with each warning is listed in
2984 .BR @g@troff (@MAN1EXT@).
2988 The major version number.
2990 For example, if the version number is 1.03, then
2996 The minor version number.
2998 For example, if the version number is 1.03, then
3004 The revision number of groff.
3008 The zoom value of the current font, in multiples of 1/1000th.
3009 Zero if no magnification.
3019 These four read/\:write registers are set by the
3021 request and contain the bounding box values (in PostScript units) of a
3022 given PostScript image.
3025 The following read/\:write registers are set by the
3037 registers, but take account of the heights and depths of glyphs.
3041 The amount of horizontal space (possibly negative) that should be
3042 added to the last glyph before a subscript.
3046 How far to right of the center of the last glyph in the
3048 argument, the center of an accent from a roman font should be placed
3052 Other available read/write number registers are:
3056 The current input line number.
3058 is a read-only alias to this register.
3062 The number of hours past midnight.
3064 Initialized at start-up.
3068 The current horizontal position at input line.
3074 If there are leading spaces in an input line, these registers
3075 hold the number of leading spaces and the corresponding
3076 horizontal space, respectively.
3080 The number of minutes after the hour.
3082 Initialized at start-up.
3086 The number of seconds after the minute.
3088 Initialized at start-up.
3092 The return value of the system() function executed by the last
3098 If greater than\~0, the maximum number of objects on the input stack.
3100 If less than or equal to\~0, there is no limit on the number of
3101 objects on the input stack.
3103 With no limit, recursion can continue until virtual memory is
3110 Note that the traditional
3114 is the current year minus 1900.
3117 .\" --------------------------------------------------------------------
3119 .\" --------------------------------------------------------------------
3122 predefines a single (read/write) string-based register,
3124 which contains the argument given to the
3126 command line option, namely the current output device (for example,
3130 Note that this is not the same as the (read-only) number register
3132 which is defined to be\~1 if
3136 command line option, and zero otherwise.
3138 This behaviour is different to UNIX troff.
3141 Fonts not listed in the
3143 file are automatically mounted on the next available font position
3144 when they are referenced.
3146 If a font is to be mounted explicitly with the
3148 request on an unused font position, it should be mounted on the first
3149 unused font position, which can be found in the
3153 does not enforce this strictly, it does not allow a font to be mounted
3154 at a position whose number is much greater than that of any currently
3158 Interpolating a string does not hide existing macro arguments.
3160 Thus in a macro, a more efficient way of doing
3163 .BI . xx\ \[rs]\[rs]$@
3168 .BI \[rs]\[rs]*[ xx ]\[rs]\[rs]
3171 If the font description file contains pairwise kerning information,
3172 glyphs from that font are kerned.
3174 Kerning between two glyphs can be inhibited by placing a
3179 In a string comparison in a condition, characters that appear at
3180 different input levels to the first delimiter character are not
3181 recognized as the second or third delimiters.
3183 This applies also to the
3189 escape sequence, a character that appears at a different input level
3190 to the starting delimiter character is not recognized as the
3191 closing delimiter character.
3193 The same is true for
3205 When decoding a macro or string argument that is delimited by double
3206 quotes, a character that appears at a different input level to the starting
3207 delimiter character is not recognized as the closing delimiter
3210 The implementation of
3212 ensures that the double quotes surrounding an argument appear at the
3213 same input level, which is different to the input level of the
3216 In a long escape name
3218 is not recognized as a closing delimiter except when it occurs at
3219 the same input level as the opening\~\c
3222 In compatibility mode, no attention is paid to the input-level.
3225 There are some new types of condition:
3229 True if there is a number register named
3234 True if there is a string, macro, diversion, or request named
3239 True if there is a color named
3244 True if there is a character (or glyph)
3250 character or a glyph (special character)
3251 .BI \[rs]N' xxx '\f[R],
3254 .BI \[rs][ xxx ]\f[R];
3255 the condition is also true if
3257 has been defined by the
3268 is handled as if it was opened with the
3270 request (this is, font translation and styles are applied), without
3271 actually mounting it.
3277 has been registered.
3279 Font translation is applied.
3284 request can now map characters onto
3288 The space width emitted by the
3292 escape sequences can be controlled on a per-font basis.
3293 If there is a glyph named
3297 respectively (note the leading backslash), defined in the current font file,
3298 use this glyph\[aq]s width instead of the default value.
3301 It is now possible to have whitespace between the first and second dot
3302 (or the name of the ending macro) to end a macro definition.
3311 \&. nop Hello, I\[aq]m \[oq]bar\[cq].
3317 .\" --------------------------------------------------------------------
3318 .SH "INTERMEDIATE OUTPUT FORMAT"
3319 .\" --------------------------------------------------------------------
3321 This section describes the format output by GNU troff.
3323 The output format used by GNU troff is very similar to that used
3324 by Unix device-independent troff.
3326 Only the differences are documented here.
3329 .\" --------------------------------------------------------------------
3331 .\" --------------------------------------------------------------------
3335 command is in scaled points (units of
3339 is the argument to the
3341 command in the DESC file).
3345 command is also in scaled points.
3348 .\" --------------------------------------------------------------------
3350 .\" --------------------------------------------------------------------
3354 Print glyph with index\~\c
3356 (a non-negative integer) of the current font.
3361 line is present in the DESC file, troff uses the following two
3367 is any sequence of characters terminated by a space or a newline (to
3368 be more precise, it is a sequence of glyphs which are accessed with
3369 the corresponding characters); the first character should be printed at
3370 the current position, the current horizontal position should be increased
3371 by the width of the first character, and so on for each character.
3373 The width of the glyph is that given in the font file,
3374 appropriately scaled for the current point size, and rounded so that
3375 it is a multiple of the horizontal resolution.
3377 Special characters cannot be printed using this command.
3383 command except that after printing each character, the current
3384 horizontal position is increased by the sum of the width of that
3389 Note that single characters can have the eighth bit set, as can the
3390 names of fonts and special characters.
3393 The names of glyphs and fonts can be of arbitrary length; drivers
3394 should not assume that they are only two characters long.
3397 When a glyph is to be printed, that glyph is always
3398 in the current font.
3400 Unlike device-independent troff, it is not necessary for drivers to
3401 search special fonts to find a glyph.
3404 For color support, some new commands have been added:
3407 \f[B]mc \f[I]cyan magenta yellow\f[R]
3411 \f[B]mg \f[I]gray\f[R]
3413 \f[B]mk \f[I]cyan magenta yellow black\f[R]
3415 \f[B]mr \f[I]red green blue\f[R]
3416 Set the color components of the current drawing color, using various
3420 resets the drawing color to the default value.
3422 The arguments are integers in the range 0 to 65536.
3427 device control command has been extended.
3430 \f[B]x u \f[I]n\f[R]
3433 is\~1, start underlining of spaces.
3437 is\~0, stop underlining of spaces.
3439 This is needed for the
3441 request in nroff mode and is ignored otherwise.
3444 .\" --------------------------------------------------------------------
3445 .SS "Drawing Commands"
3446 .\" --------------------------------------------------------------------
3450 drawing command has been extended.
3452 These extensions are not used by GNU pic if the
3457 \f[B]Df \f[I]n\/\f[R]\*[ic]\[rs]n
3458 Set the shade of gray to be used for filling solid objects to
3461 must be an integer between 0 and 1000, where 0 corresponds solid white
3462 and 1000 to solid black, and values in between correspond to
3463 intermediate shades of gray.
3465 This applies only to solid circles, solid ellipses and solid
3468 By default, a level of 1000 is used.
3470 Whatever color a solid object has, it should completely obscure
3471 everything beneath it.
3473 A value greater than 1000 or less than\~0 can also be used: this means
3474 fill with the shade of gray that is currently being used for lines and
3477 Normally this is black, but some drivers may provide a way of
3482 .BI \[rs]D'f \*[ellipsis] '
3483 command shouldn\[aq]t be used since its argument is always rounded to an
3484 integer multiple of the horizontal resolution which can lead to
3488 \f[B]DC \f[I]\/d\f[R]\*[ic]\[rs]n
3489 Draw a solid circle with a diameter of
3491 with the leftmost point at the current position.
3494 \f[B]DE \f[I]dx dy\/\f[R]\*[ic]\[rs]n
3495 Draw a solid ellipse with a horizontal diameter of
3497 and a vertical diameter of
3499 with the leftmost point at the current position.
3505 \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
3506 Draw a polygon with, for $i = 1 ,..., n+1$, the
3508 vertex at the current position
3510 $+ sum from j=1 to i-1 ( dx sub j , dy sub j )$.
3512 At the moment, GNU pic only uses this command to generate triangles
3516 \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
3520 but draw a solid rather than outlined polygon.
3523 \f[B]Dt \f[I]n\/\f[R]\*[ic]\[rs]n
3524 Set the current line thickness to
3528 Traditionally Unix troff drivers use a line thickness proportional to
3529 the current point size; drivers should continue to do this if no
3531 command has been given, or if a
3533 command has been given with a negative value of\~\c
3537 selects the smallest available line thickness.
3540 A difficulty arises in how the current position should be changed after
3541 the execution of these commands.
3543 This is not of great importance since the code generated by GNU pic
3544 does not depend on this.
3546 Given a drawing command of the form
3548 \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]
3560 Unix troff treats each of the $x sub i$ as a horizontal quantity,
3561 and each of the $y sub i$ as a vertical quantity and assumes that
3562 the width of the drawn object is $sum from i=1 to n x sub i$,
3563 and that the height is $sum from i=1 to n y sub i$.
3565 (The assumption about the height can be seen by examining the
3569 registers after using such a
3575 This rule also holds for all the original drawing commands with the
3578 For the sake of compatibility GNU troff also follows this rule, even
3579 though it produces an ugly result in the case of the
3583 and, to a lesser extent,
3587 Thus after executing a
3591 \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
3594 the current position should be increased by
3596 $( sum from i=1 to n x sub i , sum from i=1 to n y sub i )$.
3599 Another set of extensions is
3602 \f[B]DFc \f[I]cyan magenta yellow\f[R]\*[ic]\[rs]n
3604 \f[B]DFd\f[R]\*[ic]\[rs]n
3606 \f[B]DFg \f[I]gray\/\f[R]\*[ic]\[rs]n
3608 \f[B]DFk \f[I]cyan magenta yellow black\f[R]\*[ic]\[rs]n
3610 \f[B]DFr \f[I]red green blue\f[R]\*[ic]\[rs]n
3611 Set the color components of the filling color similar to the
3616 The current position isn\[aq]t changed by those colour commands
3621 .\" --------------------------------------------------------------------
3622 .SS "Device Control Commands"
3623 .\" --------------------------------------------------------------------
3625 There is a continuation convention which permits the argument to the
3627 command to contain newlines: when outputting the argument to the
3629 command, GNU troff follows each newline in the argument with a
3631 character (as usual, it terminates the entire argument with a
3632 newline); thus if the line after the line containing the
3636 then the newline ending the line containing the
3638 command should be treated as part of the argument to the
3642 should be ignored, and the part of the line following the
3644 should be treated like the part of the line following the
3649 The first three output commands are guaranteed to be:
3658 .\" --------------------------------------------------------------------
3659 .SH INCOMPATIBILITIES
3660 .\" --------------------------------------------------------------------
3662 In spite of the many extensions, groff has retained compatibility to
3663 classical troff to a large degree.
3665 For the cases where the extensions lead to collisions, a special
3666 compatibility mode with the restricted, old functionality was created
3670 .\" --------------------------------------------------------------------
3671 .SS "Groff Language"
3672 .\" --------------------------------------------------------------------
3676 .B compatibility mode
3677 that allows to process roff code written for classical
3679 or for other implementations of roff in a consistent way.
3682 Compatibility mode can be turned on with the
3684 command line option, and turned on or off with the
3690 is\~1 if compatibility mode is on, 0\~otherwise.
3693 This became necessary because the GNU concept for long names causes
3694 some incompatibilities.
3701 as defining a string
3707 mode, this is considered as a call of a macro named
3717 as references to a string or number register called\~\c
3721 takes this as the start of a long name.
3725 .IR "compatibility mode" ,
3726 groff interprets these things in the traditional way; so long
3727 names are not recognized.
3730 On the other hand, groff in
3732 does not allow to use the single-character escapes
3745 .RB \[oq] \[rs]\ \[cq]
3761 (character\~c) in names of strings, macros, diversions, number
3762 registers, fonts or environments, whereas
3769 escape sequence can be helpful in avoiding these escape sequences in
3773 Fractional point sizes cause one noteworthy incompatibility.
3780 request ignores scale indicators and so
3787 sets the point size to 10\~points, whereas in groff native mode the
3788 point size is set to 10\~scaled points.
3793 there is a fundamental difference between unformatted input
3794 characters, and formatted output characters (glyphs).
3796 Everything that affects how a glyph is output is
3797 stored with the glyph; once a glyph has been
3798 constructed it is unaffected by any subsequent requests that are
3799 executed, including the
3809 Normally glyphs are constructed from input characters at
3810 the moment immediately before the glyph is added to the current
3813 Macros, diversions and strings are all, in fact, the same type of
3814 object; they contain lists of input characters and glyphs
3818 Special characters can be both; before being added to the output, they
3819 act as input entities, afterwards they denote glyphs.
3822 A glyph does not behave like an input character for the
3823 purposes of macro processing; it does not inherit any of the special
3824 properties that the input character from which it was constructed
3827 The following example makes things clearer.
3833 \[rs]\[rs]\[rs]\[rs]
3845 So each pair of input backslashes \&\[oq]\[rs]\[rs]\[cq] is turned
3846 into a single output backslash glyph \&\[oq]\[rs]\[cq] and the
3847 resulting output backslashes are not interpreted as escape characters
3848 when they are reread.
3852 would interpret them as escape characters when they were reread and
3853 would end up printing a single backslash \[oq]\[rs]\[cq].
3856 In GNU, the correct way to get a printable version of the backslash
3857 character \[cq]\[rs]\[cq]
3860 escape sequence, but classical troff does not provide a clean feature
3861 for getting a non-syntactical backslash.
3863 A close method is the printable version of the current escape
3866 escape sequence; this works if the current escape character is not
3869 It works in both GNU mode and compatibility mode, while dirty tricks
3870 like specifying a sequence of multiple backslashes do not work
3871 reliably; for the different handling in diversions, macro definitions,
3872 or text mode quickly leads to a confusion about the necessary number of
3876 To store an escape sequence in a diversion that is interpreted
3877 when the diversion is reread, either the traditional
3879 transparent output facility or the
3882 escape sequence can be used.
3885 .\" --------------------------------------------------------------------
3886 .SS "Intermediate Output"
3887 .\" --------------------------------------------------------------------
3889 The groff intermediate output format is in a state of evolution.
3891 So far it has some incompatibilities, but it is intended to establish
3892 a full compatibility to the classical troff output format.
3894 Actually the following incompatibilities exist:
3897 The positioning after the drawing of the polygons conflicts with the
3898 classical definition.
3901 The intermediate output cannot be rescaled to other devices as
3902 classical \[oq]device-independent\[cq] troff did.
3905 .\" --------------------------------------------------------------------
3907 .\" --------------------------------------------------------------------
3914 presents all groff documentation within a single document.
3917 .BR groff (@MAN1EXT@)
3918 A list of all documentation around
3922 .BR groff (@MAN7EXT@)
3923 A description of the
3925 language, including a short, but complete reference of all predefined
3926 requests, registers, and escapes of plain
3928 From the command line, this is called using
3938 .BR roff (@MAN7EXT@)
3941 systems, including pointers to further historical documentation.
3946 .I Nroff/\:Troff User\[aq]s Manual
3948 .I J.\& F.\& Ossanna
3949 of 1976 in the revision of
3952 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:54.ps.gz
3953 classical troff documentation
3957 .\" --------------------------------------------------------------------
3959 .\" --------------------------------------------------------------------
3961 .\" --------------------------------------------------------------------
3963 .\" --------------------------------------------------------------------
3967 .\" --------------------------------------------------------------------
3969 .\" --------------------------------------------------------------------
3971 .\" Local Variables:
projects / platform / upstream / groff.git / blob