5 Last update: 15 Apr 2002
7 This file is part of groff, the GNU roff type-setting system.
9 Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc.
10 written by Bernd Warken <bwarken@mayn.de>
11 maintained by Werner Lemberg <wl@gnu.org>
13 Permission is granted to copy, distribute and/or modify this document
14 under the terms of the GNU Free Documentation License, Version 1.1 or
15 any later version published by the Free Software Foundation; with the
16 Invariant Sections being this .ig-section and AUTHORS, with no
17 Front-Cover Texts, and with no Back-Cover Texts.
19 A copy of the Free Documentation License is included as a file called
20 FDL in the main directory of the groff source package.
23 .\" --------------------------------------------------------------------
25 .\" --------------------------------------------------------------------
41 .\" --------------------------------------------------------------------
42 .\" start of macro definitions
51 .c ---------------------------------------------------------------------
54 .c All arguments are printed as text.
59 .c ---------------------------------------------------------------------
60 .c .ExecFF macro font1 font2 text1 text2 text1 text2 ...
62 .c Concat text arguments using alternating fonts and feed into macro.
63 .c For a trailing punctuation, terminate the call with \c.
78 . as @s \f[\*[@f1]]\*[@a]\f[]\"
83 . as @s \f[\*[@f2]]\*[@a]\f[]\"
87 . ft P \" to make \c happy
95 .c --------- command line option ---------
102 .c --------- characters ---------
105 . ExecFF Text CB R \$*
110 . ExecFF Text R CB \[oq] \*[@1] "\[cq]\$*"
116 . ExecFF Text R CB \[lq] \*[@1] "\[rq]\$*"
119 .c --------- requests ---------
121 .c synopsis of a request
127 . ie (\n[.$] = 0) \{\
129 . Text \f[CB]\*[@1]\f[]
133 . Text \f[CB]\*[@1]\~\f[]\f[I]\$*\f[]
137 .c reference of a request
142 .c --------- numerical elements ---------
144 .c number with a trailing unit
146 . Text \$1\^\f[CB]\$2\f[]\$3\f[R]
150 .c representation of units within the text
152 . Text \f[CB]\$1\f[]\$2\f[R]
156 .c representation of mathematical operators within the text
162 .c --------- escape sequences ---------
164 .c ---------------------------------------------------------------------
167 .c Synopsis of an escape sequence, optionally with argument
168 .c Args : 1 or 2; `name' obligatory, `arg' optional
169 .c name : suitable name for an escape sequence (c, (xy, [long])
170 .c arg : arbitrary word
171 .c Result : prints \namearg, where `name' is in CB, `arg' in I
175 . ab .ESC needs 1 or 2 arguments.
176 . ExecFF IP CB I "\[rs]\$1" "\,\$2\/"
178 .c ---------------------------------------------------------------------
181 .c Synopsis for escape sequence with a bracketed long argument
182 .c Args : 2 obligatory
183 .c name : suitable name for an escape sequence (c, (xy, [long])
184 .c arg : arbitrary text
185 .c Result : prints \name[arg], where `name' is in CB, `arg' in I
189 . ab .ESC[] needs exactly 2 arguments.
190 . ExecFF IP CB I "\[rs]\$1\[lB]" "\h'-0.2m'\$2\h'-0.15m'" \[rB]
192 .c ---------------------------------------------------------------------
195 .c Synopsis for escape sequence with a bracketed long argument
196 .c Args : 2 obligatory
197 .c name : suitable name for an escape sequence (c, (xy, [long])
198 .c arg : arbitrary text
199 .c Result : prints \name'arg', where `name' is in CB, `arg' in I
203 . ab .ESCq needs exactly 2 argument.
204 . ExecFF IP CB I "\[rs]\$1\[cq]" "\h'-0.3m'\$2" \[cq]
206 .c ---------------------------------------------------------------------
209 .c Synopsis for escape sequence with a bracketed long argument
210 .c Args : 1 obligatory
211 .c arg : arbitrary text
212 .c Result : prints `\?arg?', where the `?' are in CB, `arg' in I
216 . ab .ESC? needs exactly 1 arguments.
217 . ExecFF IP CB I \[rs]? "\$1" ?
219 .c ---------------------------------------------------------------------
222 .c Reference of an escape sequence (no args), possibly punctuation
223 .c Args : 1 obligatory
224 .c name : suitable name for an escape sequence (c, (xy, [long])
226 .c Result : prints \name, where `name' is in B, `punct' in R
230 . ab .esc needs 1 or 2 arguments.
233 .c ---------------------------------------------------------------------
234 .c .escarg name arg [punct]
236 .c Reference of an escape sequence (no args)
237 .c Args : 1 obligatory, 1 optional
238 .c name : suitable name for an escape sequence (c, (xy, [long])
239 .c arg : arbitrary word
240 .c Result : prints \namearg, where
241 .c `name' is in B, `arg' in I
245 . ab .esc needs 2 or 3 arguments.
246 . Text \f[B]\[rs]\$1\f[]\f[I]\$2\f[]\$3
248 .c ---------------------------------------------------------------------
249 .c .esc[] name arg [punct]
251 .c Reference for escape sequence with a bracketed long argument
252 .c Args : 2 obligatory
253 .c name : suitable name for an escape sequence (c, (xy, [long])
254 .c arg : arbitrary text
255 .c Result : prints \name[arg], where `name' is in CB, `arg' in CI
259 . ab .esc[] needs 2 or 3 arguments.
260 . Text \f[B]\[rs]\$1\[lB]\f[]\f[I]\$2\f[]\f[B]\[rB]\f[]\$3
263 .c ---------------------------------------------------------------------
266 .c Reference for escape sequence with a bracketed long argument
267 .c Args : 2 obligatory
268 .c name : suitable name for an escape sequence (c, (xy, [long])
269 .c arg : arbitrary text
270 .c Result : prints \name'arg', where `name' is in CB, `arg' in CI
274 . ab .escq needs 2 arguments.
275 . Text \f[B]\[rs]\$1\[cq]\f[]\f[I]\$2\f[]\f[B]\[cq]\f[]\$3
278 .c --------- strings ---------
280 .c synopsis for string, with \*[]
285 . ExecFF Text R CB \[rs]*[ \*[@1]\f[]\f[R]] \$*
288 .c synopsis for a long string
292 . Text \f[CB]\[rs]*\[lB]\$1\[rB]\f[]\$2
296 .c --------- registers ---------
298 .c synopsis for registers, with \n[]
303 . ExecFF Text R CB \[rs]n[ \*[@1]\f[]\f[R]] \$*
306 .c reference of a register, without decoration
313 .\" end of macro definitions
316 .\" --------------------------------------------------------------------
318 .\" --------------------------------------------------------------------
320 .TH GROFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
322 groff \- a short reference for the GNU roff language
325 .\" --------------------------------------------------------------------
327 .\" --------------------------------------------------------------------
333 and is the free implementation of the roff type-setting system.
337 for a survey and the background of the groff system.
340 This document gives only short descriptions of the predefined roff
341 language elements as used in groff.
343 Both the classical features and the groff extensions are provided.
351 is compatible with the classical system and provides proper
359 could be used as synonyms.
363 slightly tends to refer more to the classical aspects, whereas
365 emphasizes the GNU extensions, and
367 is the general term for the language.
370 This file is only a short version of the complete documentation that
374 file, which contains more detailed, actual, and concise information.
377 The general syntax for writing groff documents is relatively easy, but
378 writing extensions to the roff language can be a bit harder.
381 The roff language is line-oriented.
383 There are only two kinds of lines, control lines and text lines.
385 The control lines start with a control character, by default a period
389 all other lines are text lines.
393 represent commands, optionally with arguments.
395 They have the following syntax.
397 The leading control character can be followed by a command name;
398 arguments, if any, are separated by blanks from the command name and
399 among themselves, for example,
403 .Text .command_name arg1 arg2
407 For indentation, any number of space or tab characters can be inserted
408 between the leading control character and the command name, but the
409 control character must be on the first position of the line.
413 represent the parts that will be printed.
414 They can be modified by escape sequences, which are recognized by a
416 .squoted_char \[rs] .
417 These are in-line or even in-word formatting elements or functions.
419 Some of these take arguments separated by single quotes
421 others are regulated by a length encoding introduced by an open
424 or enclosed in brackets
430 The roff language provides flexible instruments for writing language
431 extension, such as macros.
433 When interpreting macro definitions, the roff system enters a special
434 operating mode, called the
438 The copy mode behavior can be quite tricky, but there are some rules
439 that ensure a safe usage.
442 Printable backslashes must be denoted as
446 represents the current escape character.
448 To get a backslash glyph, use
453 Double all backslashes.
455 Begin all text lines with the special non-spacing character
459 This does not produce the most efficient code, but it should work as a
462 For better strategies, see the groff info file and
463 .BR groff_tmac (@MAN5EXT@).
466 Reading roff source files is easier, just reduce all double backslashes
467 to a single one in all macro definitions.
470 .\" --------------------------------------------------------------------
472 .\" --------------------------------------------------------------------
474 The roff language elements add formatting information to a text file.
476 The fundamental elements are predefined commands and variables that
477 make roff a full-blown programming language.
480 There are two kinds of roff commands, possibly with arguments.
482 are written on a line of their own starting with a dot
488 are in-line functions and in-word formatting elements starting with a
490 .squoted_char \[rs] .
493 The user can define her own formatting commands using the
497 These commands are called
499 but they are used exactly like requests.
501 Macro packages are pre-defined sets of macros written in the groff
504 A user's possibilities to create escape sequences herself is very
505 limited, only special characters can be mapped.
508 The groff language provides several kinds of variables with
509 different interfaces.
511 There are pre-defined variables, but the user can define her own
516 variables store character sequences.
518 They are set with the
520 request and retrieved by the
526 variables can store numerical values, numbers with a scale unit, and
527 occasionally string-like objects.
529 They are set with the
531 request and retrieved by the
537 allow the user to temporarily store global formatting parameters like
538 line length, font size, etc.\& for later reuse.
546 are identified either by a name or by an internal number.
548 The current font is chosen by the
554 Each device has special fonts, but the following fonts are available
557 is the standard font Roman.
567 is everywhere available, but on text devices, it is displayed as an
568 underlined Roman font.
570 For the graphical output devices, there exist constant-width pendants
576 On text devices, all characters have a constant width anyway.
579 Moreover, there are some advanced roff elements.
583 stores information into a macro for later usage.
587 is a positional condition like a certain number of lines from page top
588 or in a diversion or in the input.
590 Some action can be prescribed to be run automatically when the
594 More detailed information and examples can be found in the groff info
598 .\" --------------------------------------------------------------------
599 .SH "CONTROL CHARACTERS"
600 .\" --------------------------------------------------------------------
602 There is a small set of characters that have a special controlling
603 task in certain conditions.
607 A dot is only special at the beginning of a line or after the
608 condition in the requests
614 There it is the control character that introduces a request (or macro).
616 The special behavior can be delayed by using the
622 request, the control character can be set to a different character,
625 a non-special character.
627 In all other positions, it just means a dot character.
629 In text paragraphs, it is advantageous to start each sentence at a
634 The single quote has two controlling tasks.
636 At the beginning of a line and in the conditional requests it is the
637 non-breaking control character.
639 That means that it introduces a request like the dot, but with the
640 additional property that this request doesn't cause a linebreak.
644 request, the non-break control character can be set to a different
648 As a second task, it is the most commonly used argument separator in
649 some functional escape sequences (but any pair of characters not part
650 of the argument will work).
652 In all other positions, it denotes the single quote or apostrophe
655 Groff provides a printable representation with the
661 The double quote is used to enclose arguments in requests and macros.
666 requests, a leading double quote in the argument will be stripped off,
667 making everything else afterwards the string to be defined (enabling
670 The escaped double quote
672 introduces a comment.
674 Otherwise, it is not special.
676 Groff provides a printable representation with the
682 The backslash usually introduces an escape sequence (this can be
687 A printed version of the escape character is the
689 escape; a backslash glyph can be obtained by
693 The open parenthesis is only special in escape sequences when
694 introducing an escape name or argument consisting of exactly two
697 In groff, this behavior can be replaced by the \f[CB][]\f[] construct.
700 The opening bracket is only special in groff escape sequences; there
701 it is used to introduce a long escape name or long escape argument.
703 Otherwise, it is non-special, e.g.\& in macro calls.
706 The closing bracket is only special in groff escape sequences; there
707 it terminates a long escape name or long escape argument.
709 Otherwise, it is non-special.
712 Space characters are only functional characters.
714 They separate the arguments in requests or macros, and the words in
717 They are subject to groff's horizontal spacing calculations.
719 To get a defined space width, escape sequences like
720 .squoted_char "\[rs]\ "
721 (this is the escape character followed by a space),
728 .IP \f[CI]newline\f[]
729 In text paragraphs, newlines mostly behave like space characters.
731 Continuation lines can be specified by an escaped newline, i.e., by
732 specifying a backslash
734 as the last character of a line.
736 If a tab character occurs during text the interpreter makes a
737 horizontal jump to the next pre-defined tab position.
739 There is a sophisticated interface for handling tab positions.
742 .\" --------------------------------------------------------------------
743 .SH "NUMERICAL EXPRESSIONS"
744 .\" --------------------------------------------------------------------
748 is a signed or unsigned integer or float with or without an appended
753 is a one-character abbreviation for a unit of measurement.
755 A number followed by a scale indicator signifies a size value.
757 By default, numerical values do not have a scale indicator, i.e., they
763 language defines the following scale indicators.
780 Pica\ \[eq]\ 1/6\ inch
784 Point\ \[eq]\ 1/72\ inch
788 Em\ \[eq]\ \f[R]the font size in points (width of letter `\f[CR]m\f[R]')
792 100\^th \f[R]of an \f[CR]Em
800 Basic unit for actual output device
804 Vertical line space in basic units
805 scaled point\ \[eq]\ 1/\f[CI]sizescale\f[R] of a point (defined in
806 font \f[I]DESC\f[] file)
815 .B Numerical expressions
816 are combinations of the numerical values defined above with the
817 following arithmetical operators already defined in classical troff.
881 Grouping of expressions
885 Close current grouping
893 added the following operators for numerical expressions:
900 .ExecFF Text I CB e1 >? e2
907 .ExecFF Text I CB e1 <? e2
914 .ExecFF Text CB I ( c ; e )
919 as the default scaling indicator.
925 For details see the groff info file.
928 .\" --------------------------------------------------------------------
930 .\" --------------------------------------------------------------------
933 occur in tests raised by the
940 The following table characterizes the different types of conditions.
948 A numerical expression
950 yields true if its value is greater than\~0.
962 is identical to string\~\c
969 is not identical to string\~\c
974 True if there is a character\~\c
980 True if there is a string, macro, diversion, or request called
985 Current page number is even.
989 Current page number is odd.
993 True if there is a color called
1003 True if there is a register named
1015 .\" --------------------------------------------------------------------
1017 .\" --------------------------------------------------------------------
1019 This section provides a short reference for the predefined requests.
1021 In groff, request and macro names can be arbitrarily long.
1023 No bracketing or marking of long names is needed.
1026 Most requests take one or more arguments.
1028 The arguments are separated by space characters (no tabs!); there is
1029 no inherent limit for their length or number.
1031 An argument can be enclosed by a pair of double quotes.
1033 This is very handy if an argument contains space characters, e.g.,
1034 .RI \[dq] "arg with space" \[dq]
1035 denotes a single argument.
1038 Some requests have optional arguments with a different behaviour.
1040 Not all of these details are outlined here.
1042 Refer to the groff info file and
1043 .BR groff_diff (@MAN7EXT@)
1047 In the following request specifications, most argument names were
1048 chosen to be descriptive.
1050 Only the following denotations need clarification.
1058 denotes a single character.
1062 a font either specified as a font name or a font number.
1066 all characters up to the end of the line or within
1073 is a numerical expression that evaluates to an integer value.
1077 is an arbitrary numerical expression, signed or unsigned.
1081 has three meanings depending on its sign, described below.
1087 If an expression defined as
1091 sign the resulting value of the expression will be added to an already
1092 existing value inherent to the related request, e.g.\& adding to a number
1095 If the expression starts with a
1097 the value of the expression will be subtracted from the request value.
1102 replaces the existing value directly.
1104 To assign a negative number either prepend\~0 or enclose the negative
1105 number in parentheses.
1108 .\" --------------------------------------------------------------------
1109 .SS "Request Short Reference"
1110 .\" --------------------------------------------------------------------
1115 Empty line, ignored.
1117 Useful for structuring documents.
1119 .REQ .\[rs]\[dq] anything
1120 Complete line is a comment.
1125 on standard error, exit program.
1128 Begin line adjustment for output lines in current adjust mode.
1131 Start line adjustment in mode
1133 (\f[CI]c\f[]\f[CR]\|\^\[eq]\|l,r,b,n\f[]).
1140 (\f[CI]c\f[]\f[CR]\|\^\[eq]\|l,i,I,a,A\f[]).
1142 .REQ .aln alias register
1143 Create alias name for
1146 .REQ .als alias object
1147 Create alias name for request, string, macro, or diversion
1165 Append to a macro whose name is contained in the string register
1172 Append to a macro indirectly.
1176 are string registers whose contents are interpolated for the macro name
1177 and the end macro, respectively.
1182 but with compatibility mode switched off during macro expansion.
1187 but with compatibility mode switched off during macro expansion.
1189 .REQ .as stringvar anything
1195 .REQ .asciify diversion
1196 Unformat ASCII characters, spaces, and some escape sequences in
1199 .REQ .as1 stringvar anything
1202 but with compatibility mode switched off during string expansion.
1205 Print a backtrace of the input on stderr.
1215 Embolden Special Font
1217 when current font is
1221 Unset the blank line macro.
1224 Set the blank line macro to
1228 End current diversion.
1233 omitting a partially filled line.
1236 End current diversion.
1239 Divert and append to
1241 omitting a partially filled line.
1244 Eject current page and begin new page.
1247 Eject current page; next page number
1254 Break and spread output line.
1259 Break out of a while loop.
1262 Reset no-break control character to
1266 Set no-break control character to
1270 Reset control character to
1274 Set control character to
1278 Center the next input line.
1286 Copy contents of file
1288 unprocessed to stdout or to the diversion.
1290 .REQ .cflags mode c1 c2 .\|.\|.\&
1306 .REQ .char c anything
1313 Chop the last character off macro, string, or diversion
1321 Finish the current iteration of a while loop.
1324 Enable compatibility mode.
1329 is zero disable compatibility mode, otherwise enable it.
1332 Set constant character width mode for
1340 Continuous underline in nroff, like
1345 End current diversion.
1348 Divert and append to
1368 but with compatibility mode switched off during macro expansion.
1373 but with compatibility mode switched off during macro expansion.
1375 .REQ .defcolor color scheme component
1376 Define or redefine a color with name
1387 can be single components specified as fractions in the range 0 to 1
1388 (default scale indicator\~\c
1389 .scaleindicator f ),
1390 as a string of two-digit hexadecimal color components with a leading
1392 or as a string of four-digit hexadecimal components with two leading
1399 Define or redefine a macro whose name is contained in the string register
1406 Define or redefine a macro indirectly.
1410 are string registers whose contents are interpolated for the macro name
1411 and the end macro, respectively.
1414 End current diversion.
1423 with compatibility mode disabled.
1425 .REQ .ds stringvar anything
1431 .REQ .ds1 stringvar anything
1434 but with compatibility mode switched off during string expansion.
1437 Set diversion trap to position
1439 (default scale indicator\~\c
1440 .scaleindicator v ).
1443 Reset escape character to
1444 .squoted_char \[rs] .
1447 Set escape character to
1451 Restore escape character saved with
1455 Save current escape character.
1458 Else part for if-else (\c
1465 will be run after the end of input.
1468 Turn off escape character mechanism.
1471 Switch to previous environment.
1474 Push down environment number or name
1479 Copy the contents of environment
1481 to the current environment.
1482 No pushing or popping.
1485 Exit from roff processing.
1488 Return to previous font family.
1491 Set the current font family to
1495 Disable field mechanism.
1498 Set field delimiter to
1500 and pad character to space.
1503 Set field delimiter to
1505 and pad character to
1508 .REQ .fchar c anything
1509 Define fallback character
1518 Flush output buffer.
1526 .REQ .fp n internal external
1527 Mount font with long
1534 .REQ .fspecial font s1 s2 .\|.\|.\&
1535 When the current font is
1544 Return to previous font.
1551 Change to font name or number
1557 .REQ .ftr font1 font2
1564 Remove additional hyphenation indicator character.
1567 Set up additional hyphenation indicator character\~\c
1570 .REQ .hcode c1 code1 c2 code2 .\|.\|.\&
1571 Set the hyphenation code of character
1582 Set the current hyphenation language to
1586 Set the maximum number of consecutive hyphenated lines to
1590 Read hyphenation patterns from
1594 Append hyphenation patterns from
1598 Set input mapping for
1604 with exceptional hyphenation.
1607 Switch to hyphenation mode
1611 Set the hyphenation margin to
1613 (default scale indicator\~\c
1614 .scaleindicator m ).
1617 Set the hyphenation space to
1620 .REQ .ie cond anything
1628 .REQ .if cond anything
1633 otherwise do nothing.
1645 Change to previous indent value.
1648 Change indent according to
1650 (default scale indicator\~\c
1651 .scaleindicator m ).
1654 Set an input-line count trap for the next
1661 but count lines interrupted with
1666 Enable pairwise kerning.
1671 is zero, disable pairwise kerning, otherwise enable it.
1674 Remove leader repetition character.
1677 Set leader repetition character to\~\c
1680 .REQ .length register anything
1681 Write the length of the string
1687 Enable line-tabs mode (i.e., calculate tab positions relative to output
1693 is zero, disable line-tabs mode, otherwise enable it.
1696 Set input line number to
1706 Change to previous line length.
1709 Set line length according to
1712 .scalednumber 6.5 i ,
1713 default scale indicator\~\c
1714 .scaleindicator m ).
1717 Change to the previous value of additional intra-line skip.
1720 Set additional intra-line skip value to
1724 blank lines are inserted after each text output line.
1727 Length of title (default scale indicator\~\c
1728 .scaleindicator m ).
1731 Margin character off.
1736 after each text line at actual distance from right margin.
1739 Set margin character to
1743 from right margin (default scale indicator\~\c
1744 .scaleindicator m ).
1747 Mark current vertical position in
1751 The same as the .so request except that
1753 is searched in the tmac directories.
1756 No output-line adjusting.
1759 Need a one-line vertical space.
1764 vertical space (default scale indicator\~\c
1765 .scaleindicator v ).
1768 No filling or adjusting of output-lines.
1776 .REQ .nm \[+-]N \fR[\fPM \fR[\fPS \fR[\fPI\fR]]]\fP
1777 In line number mode, set number, multiple, spacing, and indent.
1780 Do not number next line.
1791 .REQ .nr register \[+-]N M
1800 Make the built-in condition
1807 Turn no-space mode on.
1810 Immediately jump to end of current file.
1815 .REQ .open stream filename
1818 for writing and associate the stream named
1822 .REQ .opena stream filename
1828 Output vertical distance that was saved by the
1833 Reset page number character to\~\c
1837 Page number character.
1845 Set page length to default
1846 .scalednumber 11 i .
1847 The current page length is stored in
1851 Change page length to
1853 (default scale indicator\~\c
1854 .scaleindicator v ).
1857 Print macro names and sizes (number of blocks of 128 bytes).
1860 Print only total of sizes of macros (number of 128 bytes blocks).
1867 Print the names and contents of all currently defined number registers
1871 Change to previous page offset.
1873 The current page offset is available in
1881 Return to previous point-size.
1887 Get the bounding box of a PostScript image
1891 This behaves like the
1893 request except that input comes from the standard output of
1897 Print the names and positions of all traps (not including input line
1898 traps and diversion traps) on stderr.
1901 Change to previous post-vertical line spacing.
1904 Change post-vertical line spacing according to
1906 (default scale indicator\~\c
1907 .scaleindicator p ).
1909 .REQ .rchar c1 c2 .\|.\|.\&
1910 Remove the definitions of characters
1919 Return from a macro.
1922 Right justify the next
1927 Remove request, macro, or string
1931 Rename request, macro, or string
1947 Restore spacing; turn no-space mode off.
1952 to marked vertical place (default scale indicator\~\c
1953 .scaleindicator v ).
1956 Reset soft hyphen character to
1960 Set the soft hyphen character to
1964 In a macro, shift the arguments by
1968 .REQ .sizes s1 s2 .\|.\|.\& sn \fB[0]\fP
1969 Set available font sizes similar to the
1976 Include source file.
1979 Skip one line vertically.
1982 Space vertical distance
1984 up or down according to sign of
1986 (default scaling indicator\~\c
1987 .scaleindicator v ).
1989 .REQ .special s1 s2 .\|.\|.\&
1993 etc.\& are special and will be searched for characters not in the
1997 Space-character size set to
1999 of the spacewidth in the current font.
2002 Space-character size set to
2004 and sentence space size set to
2006 of the spacewidth in the current font (\f[CR]\[eq]1/3 em\f[]).
2014 .REQ .substring register n1 n2
2015 Replace the string in
2017 with the substring defined by the indices
2028 Save the vertical distance
2030 for later output with
2034 .REQ .sy command-line
2039 Set tabs after every position that is a multiple of
2041 (default scaling indicator\~\c
2042 .scaleindicator m ).
2043 .REQ .ta n1 n2 .\|.\|.\& nn \f[CB]T\f[] r1 r2 .\|.\|.\& rn
2044 Set tabs at positions
2062 .\"Restore internally saved tab positions.
2065 .\"Save tab positions internally.
2068 Remove tab repition character.
2070 Set tab repetition character to\~\c
2074 Temporary indent next line (default scaling indicator\~\c
2075 .scaleindicator m ).
2077 .REQ .tkf font s1 n1 s2 n2
2078 Enable track kerning for
2081 .REQ .tl \f[CB]\[cq]\f[]left\f[CB]\[cq]\f[]center\f[CB]\[cq]\f[]right\f[CB]\[cq]\f[]
2087 on terminal (UNIX standard message output).
2092 on terminal (UNIX standard message output), allowing leading
2097 (which will be stripped off).
2102 without emitting a final newline.
2104 .REQ .tr abcd.\|.\|.\&
2115 Transparently output the contents of file
2118 .REQ .trin abcd.\|.\|.\&
2119 This is the same as the
2121 request except that the
2123 request will use the character code (if any) before the character
2126 .REQ .trnt abcd.\|.\|.\&
2127 This is the same as the
2129 request except that the translations do not apply to text that is
2130 transparently throughput into a diversion with
2134 Make the built-in condition
2141 Underline font set to
2143 (to be switched to by
2147 Underline (italicize in troff)
2151 .REQ .unformat diversion
2152 Unformat space characters and tabs, preserving font information in
2155 Enable vertical position traps if
2157 is non-zero, disable them otherwise.
2160 Change to previous vertical base line spacing.
2163 Set vertical base line spacing according to
2165 (default scale indicator\~\c
2166 .scaleindicator p ).
2168 .scalednumber 12 p .
2171 Set warnings code to
2175 Set location trap; negative means from page bottom.
2177 .REQ .while cond anything
2184 .REQ .write stream anything
2190 .REQ .writec stream anything
2193 without emitting a final newline.
2195 .REQ .writem stream xx
2196 Write contents of macro or string
2204 Besides these standard groff requests, there might be further macro
2206 They can originate from a macro package (see
2207 .BR roff (@MAN7EXT@)
2208 for an overview) or from a preprocessor.
2211 Preprocessor macros are easy to be recognized.
2213 They enclose their code into a pair of characteristic macros.
2217 box, center, tab (@);
2220 preprocessor@start macro@ end macro
2227 soelim@\f[I]none@\f[I]none
2233 .\" --------------------------------------------------------------------
2234 .SH "ESCAPE SEQUENCES"
2235 .\" --------------------------------------------------------------------
2237 Escape sequences are in-line language elements usually introduced by a
2240 and followed by an escape name and sometimes by a required argument.
2242 Input processing is continued directly after the escaped character or
2243 the argument resp.\& without an intervening separation character.
2245 So there must be a way to determine the end of the escape name and the
2246 end of the argument.
2249 This is done by enclosing names (escape name and arguments consisting
2250 of a variable name) by a pair of brackets
2251 .BI \[lB] name \[rB]
2252 and constant arguments (number expressions and characters) by
2253 apostrophes (ASCII 0x27) like
2254 .BI \[cq] constant \[cq] \f[R].
2257 There are abbreviations for short names.
2259 Two character escape names can be specified by an opening parenthesis
2262 without a closing counterpart.
2264 And all one-character names different from the special characters
2268 can even be specified without a marker in the form
2272 Constant arguments of length\~1 can omit the marker apostrophes, too,
2273 but there is no two-character analogue.
2276 While 1-character escape sequences are mainly used for in-line
2277 functions and system related tasks, the 2-letter names following the
2279 construct are used for special characters predefined by the roff system.
2281 Escapes sequences with names of more than two characters
2283 denote user defined named characters (see the
2288 .\" --------------------------------------------------------------------
2289 .SS "Single Character Escapes"
2290 .\" --------------------------------------------------------------------
2294 .\" --------- comments ---------
2297 Beginning of a comment.
2299 Everything up to the end of the line is ignored.
2302 Everything up to and including the next newline is ignored.
2304 This is interpreted in copy mode.
2308 except that the terminating newline is ignored as well.
2310 .\" --------- strings ---------
2313 The string stored in the string variable with 1-character name
2317 The string stored in the string variable with 2-character name
2321 The string stored in the string variable with arbitrary length name
2324 .\" --------- macro arguments ---------
2327 The name by which the current macro was invoked.
2331 request can make a macro have more than one name.
2334 Macro argument with 1-place number
2338 is a digit between 1 and 9.
2341 Macro argument with 2-digit number
2345 Macro argument with number
2349 is a numerical expression evaluating to an integer \[>=]1.
2352 In a macro, the concatenation of all the arguments separated by spaces.
2355 In a macro, the concatenation of all the arguments with each surrounded
2356 by double quotes, and separated by spaces.
2358 .\" --------- escaped characters ---------
2361 reduces to a single backslash; useful to delay its interpretation as
2362 escape character in copy mode.
2364 For a printable backslash, use
2368 to be independent from the current escape character.
2371 The acute accent \[aa]; same as
2373 Unescaped: apostrophe, right quotation mark, single quote (ASCII 0x27).
2376 The grave accent \[ga]; same as
2378 Unescaped: left quote, backquote (ASCII 0x60).
2381 The \- sign in the current font.
2384 An uninterpreted dot (period), even at start of line.
2387 Default optional hyphenation character.
2390 Transparent line indicator.
2393 In a diversion, this will transparently embed
2397 is read in copy mode.
2399 See also the escape sequences
2405 .\" --------- spacing ---------
2408 Unpaddable space-size space character (no line break).
2414 1/6\ em narrow space character; zero width in nroff.
2417 1/12\ em half-narrow space character; zero width in nroff.
2420 Non-printable, zero width character.
2425 except that it behaves like a character declared with the cflags
2426 request to be transparent for the purposes of end of sentence
2430 Increases the width of the preceding character so that the spacing
2431 between that character and the following character will be correct if
2432 the following character is a roman character.
2435 Modifies the spacing of the following character so that the spacing
2436 between that character and the preceding character will correct if the
2437 preceding character is a roman character.
2440 Unbreakable space that stretches like a normal inter-word space when a
2444 Inserts a zero-width break point (similar to
2446 but without a soft hyphen character).
2449 Ignored newline, for continuation lines.
2451 .\" --------- structuring ---------
2454 Begin conditional input.
2457 End conditional input.
2459 .\" --------- longer escape names ---------
2462 The special character with 2-character name
2465 .BR "Special Characters" .
2468 The named character with arbitrary length name
2471 .\" --------- alphabetical escapes ---------
2474 Non-interpreted leader character.
2479 is acceptable as a name of a string, macro, diversion, register,
2480 environment or font it expands to\~1, and to\~0 otherwise.
2482 .ESCq b abc.\|.\|.\&
2483 Bracket building function.
2488 is acceptable as a valid numeric expression it expands to\~1, and
2492 Interrupt text processing.
2495 The character called
2499 but compatible to other roff versions.
2502 Forward (down) 1/2 em vertical unit (1/2 line in nroff).
2505 Draw a graphical element defined by the characters in
2507 see groff info file for details.
2510 Printable version of the current escape character.
2513 Equivalent to an escape character, but is not interpreted in copy-mode.
2516 Change to font with 1-character name or 1-digit number
2520 Switch back to previous font.
2523 Change to font with 2-character name or 2-digit number
2527 Change to font with arbitrary length name or number expression
2531 Switch back to previous font.
2534 Change to font family with 1-character name
2538 Change to font family with 2-character name
2542 Change to font family with arbitrary length name
2546 Switch back to previous font family.
2549 Return format of register with name
2560 Local horizontal motion; move right
2565 Set height of current font to
2569 Mark horizontal input place in register with arbitrary length name
2577 Horizontal line drawing function (optionally using character
2581 Vertical line drawing function (optionally using character
2594 Switch back to previous color.
2597 Change filling color for closed drawn objects to color
2606 Switch to previous fill color.
2609 The numerical value stored in the register variable with the
2614 The numerical value stored in the register variable with the
2619 The numerical value stored in the register variable with arbitrary
2624 Typeset the character with code
2626 in the current font, no special fonts are searched.
2628 Useful for adding characters to a font using the
2632 .ESCq o abc.\|.\|.\&
2633 Overstrike characters
2640 Disable glyph output.
2642 Mainly for internal use.
2645 Enable glyph output.
2647 Mainly for internal use.
2650 Break and spread output line.
2653 Reverse 1\ em vertical motion (reverse line in nroff).
2655 .ESCq R "name\~\[+-]n"
2662 Set the point size to
2666 Note the alternative forms
2667 .BI \[rs]s \[+-] [ N ]\c
2669 .BI \[rs]s' \[+-]N '\c
2671 .BI \[rs]s \[+-] ' N '\c
2673 .escarg s( \[+-]xy\c
2675 .BI \[rs]s \[+-] ( xy\c
2688 Non-interpreted horizontal tab.
2691 Reverse (up) 1/2 em vertical motion (1/2 line in nroff).
2694 Local vertical motion; move down
2699 The contents of the environment variable
2708 The width of the character sequence
2712 Extra line-space function (negative before, positive after).
2717 as device control function.
2720 Output string variable or macro
2722 uninterpreted as device control function.
2732 with zero width (without spacing).
2737 and then restore the horizontal and vertical position;
2739 may not contain tabs or leaders.
2743 The escape sequences
2755 are interpreted in copy mode.
2758 Escape sequences starting with
2762 do not represent single character escape sequences, but introduce escape
2763 names with two or more characters.
2766 If a backslash is followed by a character that does not constitute a
2767 defined escape sequence the backslash is silently ignored and the
2768 character maps to itself.
2771 .\" --------------------------------------------------------------------
2772 .SS "Special Characters"
2773 .\" --------------------------------------------------------------------
2775 Common special characters are predefined by escape sequences of the
2783 Some of these exist in the usual font while most of them are only
2784 available in the special font.
2786 Below you'll find a selection of the most important glyphs; a complete
2787 list can be found in
2788 .BR groff_char (@MAN7EXT@).
2806 Printable double quote
2814 Printable backslash character
2837 .\" --------------------------------------------------------------------
2839 .\" --------------------------------------------------------------------
2841 Strings are defined by the
2843 request and can be retrieved by the
2848 Strings share their name space with macros.
2850 So strings and macros without arguments are roughly equivalent, though
2851 calling a string like a macro and vice-versa is not stably implemented
2854 The following strings are predefined in groff.
2857 The name of the current output device as specified by the
2859 command line option.
2862 .\" --------------------------------------------------------------------
2864 .\" --------------------------------------------------------------------
2866 Registers are variables that store a value.
2867 In groff, most registers store numerical values (see section
2868 .B NUMERICAL EXPRESSIONS
2869 above), but some can also hold a string value.
2872 Each register is given a name.
2873 Arbitrary registers can be defined and set with the request
2878 The value stored in a register can be retrieved by the escape sequences
2883 Most useful are predefined registers.
2885 In the following the notation
2887 is used to refer to a register called
2889 to make clear that we speak about registers.
2891 Please keep in mind that the
2893 decoration is not part of the register name.
2896 .\" --------------------------------------------------------------------
2897 .SS "Read-only Registers"
2898 .\" --------------------------------------------------------------------
2900 The following registers have predefined values that should not be
2901 modified by the user (usually, registers starting with a dot a
2904 Mostly, they provide information on the current settings or store
2905 results from request calls.
2911 Number of arguments in the current macro.
2914 Post-line extra line-space most recently utilized using
2922 is used; always\~1 in
2926 Current input line number.
2929 1\~if compatibility mode is in effect, 0\~otherwise.
2932 The depth of the last character added to the current environment.
2933 It is positive if the character extends below the baseline.
2936 The number of lines remaining to be centered, as set by the
2941 The height of the last character added to the current environment.
2942 It is positive if the character extends above the baseline.
2945 The skew of the last character added to the current environment.
2946 The skew of a character is how far to the right of the center of a character
2947 the center of an accent over that character should be placed.
2950 Current vertical place in current diversion; equal to register
2954 The name or number of the current environment (string-valued).
2957 Current font number.
2960 The current font family (string-valued).
2963 The current (internal) real font name (string-valued).
2966 The number of the next free font position.
2969 Always 1 in GNU troff.
2971 Macros should use it to test if running under groff.
2974 Text base-line high-water mark on current page or diversion.
2977 Available horizontal resolution in basic units.
2980 The current hyphenation language as set by the
2985 The number of immediately preceding consecutive hyphenated lines.
2988 The maximum allowed number of consecutive hyphenated lines, as set by
2994 The current hyphenation flags (as set by the
2999 The current hyphenation margin (as set by the
3004 The current hyphenation space (as set by the
3012 The indent that applies to the current output line.
3015 Positive if last output line contains
3019 1\~if pairwise kerning is enabled, 0\~otherwise.
3022 Current line length.
3025 The current ligature mode (as set by the
3030 The current line-tabs mode (as set by the
3035 The line length that applies to the current output line.
3038 The title length (as set by the
3043 Length of text portion on previous output line.
3046 The amount of space that was needed in the last
3048 request that caused a trap to be sprung.
3050 Useful in conjunction with
3054 1\~if in no-space mode, 0\~otherwise.
3057 Current page offset.
3060 Current page length.
3063 The number of the next page: either the value set by a
3065 request, or the number of the current page plus\ 1.
3068 The current pointsize in scaled points.
3071 The last-requested pointsize in scaled points.
3074 The current post-vertical line spacing.
3077 The number of lines to be right-justified as set by the rj request.
3080 Current point size as a decimal fraction.
3083 The last requested pointsize in points as a decimal fraction
3087 Distance to the next trap.
3096 A string representation of the current tab settings suitable for use
3097 as an argument to the
3102 The amount of vertical space truncated by the most recently sprung
3103 vertical position trap, or, if the trap was sprung by a
3105 request, minus the amount of vertical motion produced by
3108 In other words, at the point a trap is sprung, it represents
3109 the difference of what the vertical position would have been but for
3110 the trap, and what the vertical position actually is.
3112 Useful in conjunction with the
3117 The value of the parameters set by the first argument of the
3122 The value of the parameters set by the second argument of the
3127 Equal to 1 bin fill mode and 0 in nofill mode.
3130 Current vertical line spacing.
3133 Available vertical resolution in basic units.
3136 1\~ if vertical position traps are enabled, 0\~otherwise.
3139 Width of previous character.
3142 The sum of the number codes of the currently enabled warnings.
3145 The major version number.
3148 The minor version number.
3151 The revision number of groff.
3154 Name of current diversion.
3158 .\" --------------------------------------------------------------------
3159 .SS "Writable Registers"
3160 .\" --------------------------------------------------------------------
3162 The following registers can be read and written by the user.
3163 They have predefined default values, but these can be modified for
3164 customizing a document.
3169 Current page number.
3172 Current input line number.
3175 Character type (set by width function
3179 Maximal width of last completed diversion.
3182 Height of last completed diversion.
3185 Current day of week (1-7).
3188 Current day of month (1-31).
3191 Current horizontal position at input line.
3194 Lower left x-coordinate (in PostScript units) of a given PostScript
3199 Lower left y-coordinate (in PostScript units) of a given PostScript
3207 Current month (1-12).
3210 Vertical position of last printed text base-line.
3215 but takes account of the heights and depths of characters.
3220 but takes account of the heights and depths of characters.
3223 Depth of string below base line (generated by width function
3227 Right skip width from the center of the last character in the
3232 If greater than 0, the maximum number of objects on the input stack.
3234 If \[<=]0 there is no limit, i.e., recursion can continue until virtual
3235 memory is exhausted.
3238 The amount of horizontal space (possibly negative) that should be
3239 added to the last character before a subscript (generated by width
3244 Height of string above base line (generated by width function
3248 The return value of the
3250 function executed by the last
3255 Upper right x-coordinate (in PostScript units) of a given PostScript
3260 Upper right y-coordinate (in PostScript units) of a given PostScript
3265 The current year (year 2000 compliant).
3268 Current year minus 1900.
3270 For Y2K compliance use register
3277 .\" --------------------------------------------------------------------
3279 .\" --------------------------------------------------------------------
3281 The differences of the groff language in comparison to classical troff
3285 .BR groff_diff (@MAN7EXT@).
3288 The groff system provides a compatibility mode, see
3289 .BR groff (@MAN1EXT@)
3290 on how to invoke this.
3293 .\" --------------------------------------------------------------------
3295 .\" --------------------------------------------------------------------
3298 .MTO bug-groff@gnu.org "groff bug mailing list" .
3299 Include a complete, self-contained example that will allow the bug to
3300 be reproduced, and say which version of groff you are using.
3303 .\" --------------------------------------------------------------------
3305 .\" --------------------------------------------------------------------
3307 Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc.
3310 This document is distributed under the terms of the FDL (GNU Free
3311 Documentation License) version 1.1 or later.
3313 You should have received a copy of the FDL on your system, it is also
3314 available on-line at the
3315 .URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" .
3318 This document is part of
3320 the GNU roff distribution.
3323 .MTO bwarken@mayn.de "Bernd Warken" ;
3325 .MTO wl@gnu.org "Werner Lemberg" .
3328 .\" --------------------------------------------------------------------
3330 .\" --------------------------------------------------------------------
3333 The main source of information for the groff language is the
3338 Besides the gory details, it contains many examples.
3341 .BR groff (@MAN1EXT@)
3342 the usage of the groff program and pointers to the documentation and
3343 availability of the groff system.
3346 .BR groff_diff (@MAN7EXT@)
3347 the differences of the groff language as compared to classical roff.
3349 This is the authoritative document for the predefined language
3350 elements that are specific to groff.
3353 .BR groff_char (@MAN7EXT@)
3354 the predefined groff characters (glyphs).
3357 .BR groff_font (@MAN5EXT@)
3358 the specification of fonts and the DESC file.
3361 .BR roff (@MAN7EXT@)
3362 the history of roff, the common parts shared by all roff systems, and
3363 pointers to further documentation.
3367 .URL http://\:cm.bell-labs.com/\:cm/\:cs/\:54.ps \
3368 "Nroff/\:Troff User's Manual by Osanna & Kernighan"
3369 \[em] the bible for classical troff.
3372 .\" --------------------------------------------------------------------
3374 .\" --------------------------------------------------------------------
3376 .\" Local Variables: