5 Last update: 13 Feb 2003
7 This file is part of groff, the GNU roff type-setting system.
9 Copyright (C) 2000, 2001, 2002, 2003 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[]\"
86 . \*[@m] "\*[@s]\f[R]"
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
524 Strings can have variables.
528 variables can store numerical values, numbers with a scale unit, and
529 occasionally string-like objects.
531 They are set with the
533 request and retrieved by the
539 allow the user to temporarily store global formatting parameters like
540 line length, font size, etc.\& for later reuse.
548 are identified either by a name or by an internal number.
550 The current font is chosen by the
556 Each device has special fonts, but the following fonts are available
559 is the standard font Roman.
569 and is available everywhere, but on text devices it is displayed as an
570 underlined Roman font.
572 For the graphical output devices, there exist constant-width pendants
578 On text devices, all characters have a constant width anyway.
581 Moreover, there are some advanced roff elements.
585 stores information into a macro for later usage.
589 is a positional condition like a certain number of lines from page top
590 or in a diversion or in the input.
592 Some action can be prescribed to be run automatically when the
596 More detailed information and examples can be found in the groff info
600 .\" --------------------------------------------------------------------
601 .SH "CONTROL CHARACTERS"
602 .\" --------------------------------------------------------------------
604 There is a small set of characters that have a special controlling
605 task in certain conditions.
609 A dot is only special at the beginning of a line or after the
610 condition in the requests
616 There it is the control character that introduces a request (or macro).
618 The special behavior can be delayed by using the
624 request, the control character can be set to a different character,
627 a non-special character.
629 In all other positions, it just means a dot character.
631 In text paragraphs, it is advantageous to start each sentence at a
636 The single quote has two controlling tasks.
638 At the beginning of a line and in the conditional requests it is the
639 non-breaking control character.
641 That means that it introduces a request like the dot, but with the
642 additional property that this request doesn't cause a linebreak.
646 request, the non-break control character can be set to a different
650 As a second task, it is the most commonly used argument separator in
651 some functional escape sequences (but any pair of characters not part
652 of the argument will work).
654 In all other positions, it denotes the single quote or apostrophe
657 Groff provides a printable representation with the
663 The double quote is used to enclose arguments in requests, macros, and
670 requests, a leading double quote in the argument will be stripped off,
671 making everything else afterwards the string to be defined (enabling
674 The escaped double quote
676 introduces a comment.
678 Otherwise, it is not special.
680 Groff provides a printable representation with the
686 The backslash usually introduces an escape sequence (this can be
691 A printed version of the escape character is the
693 escape; a backslash glyph can be obtained by
697 The open parenthesis is only special in escape sequences when
698 introducing an escape name or argument consisting of exactly two
701 In groff, this behavior can be replaced by the \f[CB][]\f[] construct.
704 The opening bracket is only special in groff escape sequences; there
705 it is used to introduce a long escape name or long escape argument.
707 Otherwise, it is non-special, e.g.\& in macro calls.
710 The closing bracket is only special in groff escape sequences; there
711 it terminates a long escape name or long escape argument.
713 Otherwise, it is non-special.
716 Space characters are only functional characters.
718 They separate the arguments in requests, macros, and strings, and the words
721 They are subject to groff's horizontal spacing calculations.
723 To get a defined space width, escape sequences like
724 .squoted_char "\[rs]\ "
725 (this is the escape character followed by a space),
732 .IP \f[CI]newline\f[]
733 In text paragraphs, newlines mostly behave like space characters.
735 Continuation lines can be specified by an escaped newline, i.e., by
736 specifying a backslash
738 as the last character of a line.
740 If a tab character occurs during text the interpreter makes a
741 horizontal jump to the next pre-defined tab position.
743 There is a sophisticated interface for handling tab positions.
746 .\" --------------------------------------------------------------------
747 .SH "NUMERICAL EXPRESSIONS"
748 .\" --------------------------------------------------------------------
752 is a signed or unsigned integer or float with or without an appended
757 is a one-character abbreviation for a unit of measurement.
759 A number followed by a scaling indicator signifies a size value.
761 By default, numerical values do not have a scaling indicator, i.e., they
767 language defines the following scaling indicators.
784 Pica\ \[eq]\ 1/6\ inch
788 Point\ \[eq]\ 1/72\ inch
792 Em\ \[eq]\ \f[R]the font size in points (width of letter `\f[CR]m\f[R]')
796 100\^th \f[R]of an \f[CR]Em
804 Basic unit for actual output device
808 Vertical line space in basic units
809 scaled point\ \[eq]\ 1/\f[CI]sizescale\f[R] of a point (defined in
810 font \f[I]DESC\f[] file)
819 .B Numerical expressions
820 are combinations of the numerical values defined above with the
821 following arithmetical operators already defined in classical troff.
885 Grouping of expressions
889 Close current grouping
897 added the following operators for numerical expressions:
904 .ExecFF Text I CB e1 >? e2
911 .ExecFF Text I CB e1 <? e2
918 .ExecFF Text CB I ( c ; e )
923 as the default scaling indicator.
929 For details see the groff info file.
932 .\" --------------------------------------------------------------------
934 .\" --------------------------------------------------------------------
937 occur in tests raised by the
944 The following table characterizes the different types of conditions.
952 A numerical expression
954 yields true if its value is greater than\~0.
966 is identical to string\~\c
973 is not identical to string\~\c
978 True if there is a character\~\c
984 True if there is a string, macro, diversion, or request called
989 Current page number is even.
993 Current page number is odd.
997 True if there is a color called
1007 True if there is a register named
1019 .\" --------------------------------------------------------------------
1021 .\" --------------------------------------------------------------------
1023 This section provides a short reference for the predefined requests.
1025 In groff, request and macro names can be arbitrarily long.
1027 No bracketing or marking of long names is needed.
1030 Most requests take one or more arguments.
1032 The arguments are separated by space characters (no tabs!); there is
1033 no inherent limit for their length or number.
1035 An argument can be enclosed by a pair of double quotes.
1037 This is very handy if an argument contains space characters, e.g.,
1038 .RI \[dq] "arg with space" \[dq]
1039 denotes a single argument.
1042 Some requests have optional arguments with a different behaviour.
1044 Not all of these details are outlined here.
1046 Refer to the groff info file and
1047 .BR groff_diff (@MAN7EXT@)
1051 In the following request specifications, most argument names were
1052 chosen to be descriptive.
1054 Only the following denotations need clarification.
1062 denotes a single character.
1066 a font either specified as a font name or a font number.
1070 all characters up to the end of the line or within
1077 is a numerical expression that evaluates to an integer value.
1081 is an arbitrary numerical expression, signed or unsigned.
1085 has three meanings depending on its sign, described below.
1091 If an expression defined as
1095 sign the resulting value of the expression will be added to an already
1096 existing value inherent to the related request, e.g.\& adding to a number
1099 If the expression starts with a
1101 the value of the expression will be subtracted from the request value.
1106 replaces the existing value directly.
1108 To assign a negative number either prepend\~0 or enclose the negative
1109 number in parentheses.
1112 .\" --------------------------------------------------------------------
1113 .SS "Request Short Reference"
1114 .\" --------------------------------------------------------------------
1119 Empty line, ignored.
1121 Useful for structuring documents.
1123 .REQ .\[rs]\[dq] anything
1124 Complete line is a comment.
1129 on standard error, exit program.
1132 Begin line adjustment for output lines in current adjust mode.
1135 Start line adjustment in mode
1137 (\f[CI]c\f[]\f[CR]\|\^\[eq]\|l,r,b,n\f[]).
1144 (\f[CI]c\f[]\f[CR]\|\^\[eq]\|l,i,I,a,A\f[]).
1146 .REQ .aln alias register
1147 Create alias name for
1150 .REQ .als alias object
1151 Create alias name for request, string, macro, or diversion
1169 Append to a macro whose name is contained in the string register
1176 Append to a macro indirectly.
1180 are string registers whose contents are interpolated for the macro name
1181 and the end macro, respectively.
1186 but with compatibility mode switched off during macro expansion.
1191 but with compatibility mode switched off during macro expansion.
1193 .REQ .as stringvar anything
1199 .REQ .asciify diversion
1200 Unformat ASCII characters, spaces, and some escape sequences in
1203 .REQ .as1 stringvar anything
1206 but with compatibility mode switched off during string expansion.
1209 Print a backtrace of the input on stderr.
1219 Embolden Special Font
1221 when current font is
1225 Unset the blank line macro.
1228 Set the blank line macro to
1232 End current diversion.
1237 omitting a partially filled line.
1240 End current diversion.
1243 Divert and append to
1245 omitting a partially filled line.
1248 Eject current page and begin new page.
1251 Eject current page; next page number
1258 Break and spread output line.
1263 Break out of a while loop.
1266 Reset no-break control character to
1270 Set no-break control character to
1274 Reset control character to
1278 Set control character to
1282 Center the next input line.
1290 Copy contents of file
1292 unprocessed to stdout or to the diversion.
1294 .REQ .cflags mode c1 c2 .\|.\|.\&
1310 .REQ .char c anything
1317 Chop the last character off macro, string, or diversion
1330 is zero disable colors, otherwise enable them.
1332 .REQ .composite from to
1337 while constructing a composite glyph name.
1340 Finish the current iteration of a while loop.
1343 Enable compatibility mode.
1348 is zero disable compatibility mode, otherwise enable it.
1351 Set constant character width mode for
1359 Continuous underline in nroff, like
1364 End current diversion.
1367 Divert and append to
1387 but with compatibility mode switched off during macro expansion.
1392 but with compatibility mode switched off during macro expansion.
1394 .REQ .defcolor color scheme component
1395 Define or redefine a color with name
1406 can be single components specified as fractions in the range 0 to 1
1407 (default scaling indicator\~\c
1408 .scaleindicator f ),
1409 as a string of two-digit hexadecimal color components with a leading
1411 or as a string of four-digit hexadecimal components with two leading
1418 Define or redefine a macro whose name is contained in the string register
1425 Define or redefine a macro indirectly.
1429 are string registers whose contents are interpolated for the macro name
1430 and the end macro, respectively.
1433 End current diversion.
1442 with compatibility mode disabled.
1444 .REQ .ds stringvar anything
1450 .REQ .ds1 stringvar anything
1453 but with compatibility mode switched off during string expansion.
1456 Set diversion trap to position
1458 (default scaling indicator\~\c
1459 .scaleindicator v ).
1462 Reset escape character to
1463 .squoted_char \[rs] .
1466 Set escape character to
1470 Restore escape character saved with
1474 Save current escape character.
1477 Else part for if-else (\c
1484 will be run after the end of input.
1487 Turn off escape character mechanism.
1490 Switch to previous environment.
1493 Push down environment number or name
1498 Copy the contents of environment
1500 to the current environment.
1501 No pushing or popping.
1504 Exit from roff processing.
1507 Return to previous font family.
1510 Set the current font family to
1514 Disable field mechanism.
1517 Set field delimiter to
1519 and pad character to space.
1522 Set field delimiter to
1524 and pad character to
1527 .REQ .fchar c anything
1528 Define fallback character
1537 Flush output buffer.
1545 .REQ .fp n internal external
1546 Mount font with long
1553 .REQ .fschar f c anything
1554 Define fallback character
1562 Reset list of special fonts for
1566 .REQ .fspecial font s1 s2 .\|.\|.\&
1567 When the current font is
1576 Return to previous font.
1583 Change to font name or number
1589 .REQ .ftr font1 font2
1596 Remove additional hyphenation indicator character.
1599 Set up additional hyphenation indicator character\~\c
1602 .REQ .hcode c1 code1 c2 code2 .\|.\|.\&
1603 Set the hyphenation code of character
1614 Set the current hyphenation language to
1618 Set the maximum number of consecutive hyphenated lines to
1622 Read hyphenation patterns from
1626 Append hyphenation patterns from
1630 Set input mapping for
1636 with exceptional hyphenation.
1639 Switch to hyphenation mode
1643 Set the hyphenation margin to
1645 (default scaling indicator\~\c
1646 .scaleindicator m ).
1649 Set the hyphenation space to
1652 .REQ .ie cond anything
1660 .REQ .if cond anything
1665 otherwise do nothing.
1677 Change to previous indent value.
1680 Change indent according to
1682 (default scaling indicator\~\c
1683 .scaleindicator m ).
1686 Set an input-line count trap for the next
1693 but count lines interrupted with
1698 Enable pairwise kerning.
1703 is zero, disable pairwise kerning, otherwise enable it.
1706 Remove leader repetition character.
1709 Set leader repetition character to\~\c
1712 .REQ .length register anything
1713 Write the length of the string
1719 Enable line-tabs mode (i.e., calculate tab positions relative to output
1725 is zero, disable line-tabs mode, otherwise enable it.
1728 Set input line number to
1732 Set input line number to
1742 Change to previous line length.
1745 Set line length according to
1748 .scalednumber 6.5 i ,
1749 default scaling indicator\~\c
1750 .scaleindicator m ).
1753 Change to the previous value of additional intra-line skip.
1756 Set additional intra-line skip value to
1760 blank lines are inserted after each text output line.
1763 Length of title (default scaling indicator\~\c
1764 .scaleindicator m ).
1767 Margin character off.
1772 after each text line at actual distance from right margin.
1775 Set margin character to
1779 from right margin (default scaling indicator\~\c
1780 .scaleindicator m ).
1783 Mark current vertical position in
1787 The same as the .so request except that
1789 is searched in the tmac directories.
1792 No output-line adjusting.
1795 Need a one-line vertical space.
1800 vertical space (default scaling indicator\~\c
1801 .scaleindicator v ).
1804 No filling or adjusting of output-lines.
1812 .REQ .nm \[+-]N \fR[\fPM \fR[\fPS \fR[\fPI\fR]]]\fP
1813 In line number mode, set number, multiple, spacing, and indent.
1816 Do not number next line.
1827 .REQ .nr register \[+-]N M
1836 Make the built-in condition
1843 Turn no-space mode on.
1846 Immediately jump to end of current file.
1851 .REQ .open stream filename
1854 for writing and associate the stream named
1858 .REQ .opena stream filename
1864 Output vertical distance that was saved by the
1871 directly to intermediate output, allowing leading whitespace if
1875 (which will be stripped off).
1878 Reset page number character to\~\c
1882 Page number character.
1890 Set page length to default
1891 .scalednumber 11 i .
1892 The current page length is stored in
1896 Change page length to
1898 (default scaling indicator\~\c
1899 .scaleindicator v ).
1902 Print macro names and sizes (number of blocks of 128 bytes).
1905 Print only total of sizes of macros (number of 128 bytes blocks).
1912 Print the names and contents of all currently defined number registers
1916 Change to previous page offset.
1918 The current page offset is available in
1926 Return to previous point-size.
1932 Get the bounding box of a PostScript image
1936 This behaves like the
1938 request except that input comes from the standard output of
1942 Print the names and positions of all traps (not including input line
1943 traps and diversion traps) on stderr.
1946 Change to previous post-vertical line spacing.
1949 Change post-vertical line spacing according to
1951 (default scaling indicator\~\c
1952 .scaleindicator p ).
1954 .REQ .rchar c1 c2 .\|.\|.\&
1955 Remove the definitions of characters
1964 Return from a macro.
1966 .REQ .rfschar f c1 c2 .\|.\|.\&
1967 Remove the definitions of characters
1975 Right justify the next
1980 Remove request, macro, or string
1984 Rename request, macro, or string
2000 Restore spacing; turn no-space mode off.
2005 to marked vertical place (default scaling indicator\~\c
2006 .scaleindicator v ).
2008 .REQ .schar c anything
2009 Define global fallback character
2015 Reset soft hyphen character to
2019 Set the soft hyphen character to
2023 In a macro, shift the arguments by
2027 .REQ .sizes s1 s2 .\|.\|.\& sn \fB[0]\fP
2028 Set available font sizes similar to the
2035 Include source file.
2038 Skip one line vertically.
2041 Space vertical distance
2043 up or down according to sign of
2045 (default scaling indicator\~\c
2046 .scaleindicator v ).
2049 Reset global list of special fonts to be empty.
2051 .REQ .special s1 s2 .\|.\|.\&
2055 etc.\& are special and will be searched for characters not in the
2059 Toggle the spread warning on and off without changing its value.
2061 .REQ .spreadwarn limit
2062 Emit a warning if each space in an output line is widened by
2064 or more (default scaling indicator\~\c
2065 .scaleindicator m ).
2068 Space-character size set to
2070 of the spacewidth in the current font.
2073 Space-character size set to
2075 and sentence space size set to
2077 of the spacewidth in the current font (\f[CR]\[eq]1/3 em\f[]).
2085 .REQ .substring xx n1 n2
2086 Replace the string named
2088 with the substring defined by the indices
2099 Save the vertical distance
2101 for later output with
2105 .REQ .sy command-line
2110 Set tabs after every position that is a multiple of
2112 (default scaling indicator\~\c
2113 .scaleindicator m ).
2114 .REQ .ta n1 n2 .\|.\|.\& nn \f[CB]T\f[] r1 r2 .\|.\|.\& rn
2115 Set tabs at positions
2133 .\"Restore internally saved tab positions.
2136 .\"Save tab positions internally.
2139 Remove tab repition character.
2141 Set tab repetition character to\~\c
2145 Temporary indent next line (default scaling indicator\~\c
2146 .scaleindicator m ).
2148 .REQ .tkf font s1 n1 s2 n2
2149 Enable track kerning for
2152 .REQ .tl \f[CB]\[cq]\f[]left\f[CB]\[cq]\f[]center\f[CB]\[cq]\f[]right\f[CB]\[cq]\f[]
2158 on terminal (UNIX standard message output).
2163 on terminal (UNIX standard message output), allowing leading
2168 (which will be stripped off).
2173 without emitting a final newline.
2175 .REQ .tr abcd.\|.\|.\&
2186 Transparently output the contents of file
2189 .REQ .trin abcd.\|.\|.\&
2190 This is the same as the
2192 request except that the
2194 request will use the character code (if any) before the character
2197 .REQ .trnt abcd.\|.\|.\&
2198 This is the same as the
2200 request except that the translations do not apply to text that is
2201 transparently throughput into a diversion with
2205 Make the built-in condition
2212 Underline font set to
2214 (to be switched to by
2218 Underline (italicize in troff)
2222 .REQ .unformat diversion
2223 Unformat space characters and tabs, preserving font information in
2226 Enable vertical position traps if
2228 is non-zero, disable them otherwise.
2231 Change to previous vertical base line spacing.
2234 Set vertical base line spacing according to
2236 (default scaling indicator\~\c
2237 .scaleindicator p ).
2239 .scalednumber 12 p .
2242 Set warnings code to
2246 Set scaling indicator used in warnings to
2250 Remove (first) trap at position
2254 Set location trap; negative means from page bottom.
2256 .REQ .while cond anything
2263 .REQ .write stream anything
2269 .REQ .writec stream anything
2272 without emitting a final newline.
2274 .REQ .writem stream xx
2275 Write contents of macro or string
2283 Besides these standard groff requests, there might be further macro
2285 They can originate from a macro package (see
2286 .BR roff (@MAN7EXT@)
2287 for an overview) or from a preprocessor.
2290 Preprocessor macros are easy to be recognized.
2292 They enclose their code into a pair of characteristic macros.
2296 box, center, tab (@);
2299 preprocessor@start macro@ end macro
2306 soelim@\f[I]none@\f[I]none
2312 .\" --------------------------------------------------------------------
2313 .SH "ESCAPE SEQUENCES"
2314 .\" --------------------------------------------------------------------
2316 Escape sequences are in-line language elements usually introduced by a
2319 and followed by an escape name and sometimes by a required argument.
2321 Input processing is continued directly after the escaped character or
2322 the argument resp.\& without an intervening separation character.
2324 So there must be a way to determine the end of the escape name and the
2325 end of the argument.
2328 This is done by enclosing names (escape name and arguments consisting
2329 of a variable name) by a pair of brackets
2330 .BI \[lB] name \[rB]
2331 and constant arguments (number expressions and characters) by
2332 apostrophes (ASCII 0x27) like
2333 .BI \[cq] constant \[cq] \f[R].
2336 There are abbreviations for short names.
2338 Two character escape names can be specified by an opening parenthesis
2341 without a closing counterpart.
2343 And all one-character names different from the special characters
2347 can even be specified without a marker in the form
2351 Constant arguments of length\~1 can omit the marker apostrophes, too,
2352 but there is no two-character analogue.
2355 While 1-character escape sequences are mainly used for in-line
2356 functions and system related tasks, the 2-letter names following the
2358 construct are used for special characters predefined by the roff system.
2360 Escapes sequences with names of more than two characters
2362 denote user defined named characters (see the
2367 .\" --------------------------------------------------------------------
2368 .SS "Single Character Escapes"
2369 .\" --------------------------------------------------------------------
2373 .\" --------- comments ---------
2376 Beginning of a comment.
2378 Everything up to the end of the line is ignored.
2381 Everything up to and including the next newline is ignored.
2383 This is interpreted in copy mode.
2387 except that the terminating newline is ignored as well.
2389 .\" --------- strings ---------
2392 The string stored in the string variable with 1-character name
2396 The string stored in the string variable with 2-character name
2399 .ESC[] * "stringvar arg1 arg2 .\|.\|."
2400 The string stored in the string variable with arbitrary length name
2408 .\" --------- macro arguments ---------
2411 The name by which the current macro was invoked.
2415 request can make a macro have more than one name.
2418 Macro or string argument with 1-place number
2422 is a digit between 1 and 9.
2425 Macro or string argument with 2-digit number
2429 Macro or string argument with number
2433 is a numerical expression evaluating to an integer \[>=]1.
2436 In a macro or string, the concatenation of all the arguments separated
2440 In a macro or string, the concatenation of all the arguments with each
2441 surrounded by double quotes, and separated by spaces.
2443 .\" --------- escaped characters ---------
2446 reduces to a single backslash; useful to delay its interpretation as
2447 escape character in copy mode.
2449 For a printable backslash, use
2453 to be independent from the current escape character.
2456 The acute accent \[aa]; same as
2458 Unescaped: apostrophe, right quotation mark, single quote (ASCII 0x27).
2461 The grave accent \[ga]; same as
2463 Unescaped: left quote, backquote (ASCII 0x60).
2466 The \- sign in the current font.
2469 An uninterpreted dot (period), even at start of line.
2472 Default optional hyphenation character.
2475 Transparent line indicator.
2478 In a diversion, this will transparently embed
2482 is read in copy mode.
2484 See also the escape sequences
2490 .\" --------- spacing ---------
2493 Unpaddable space-size space character (no line break).
2499 1/6\ em narrow space character; zero width in nroff.
2502 1/12\ em half-narrow space character; zero width in nroff.
2505 Non-printable, zero width character.
2510 except that it behaves like a character declared with the cflags
2511 request to be transparent for the purposes of end of sentence
2515 Increases the width of the preceding character so that the spacing
2516 between that character and the following character will be correct if
2517 the following character is a roman character.
2520 Modifies the spacing of the following character so that the spacing
2521 between that character and the preceding character will correct if the
2522 preceding character is a roman character.
2525 Unbreakable space that stretches like a normal inter-word space when a
2529 Inserts a zero-width break point (similar to
2531 but without a soft hyphen character).
2534 Ignored newline, for continuation lines.
2536 .\" --------- structuring ---------
2539 Begin conditional input.
2542 End conditional input.
2544 .\" --------- longer escape names ---------
2547 The special character with 2-character name
2550 .BR "Special Characters" .
2553 The named character (or rather glyph) with arbitrary length name
2556 .ESC[] "" "comp1 comp2 .\|.\|."
2557 A composite glyph with components
2562 .\" --------- alphabetical escapes ---------
2565 Non-interpreted leader character.
2570 is acceptable as a name of a string, macro, diversion, register,
2571 environment or font it expands to\~1, and to\~0 otherwise.
2573 .ESCq b abc.\|.\|.\&
2574 Bracket building function.
2579 is acceptable as a valid numeric expression it expands to\~1, and
2583 Interrupt text processing.
2586 The character called
2590 but compatible to other roff versions.
2593 Forward (down) 1/2 em vertical unit (1/2 line in nroff).
2596 Draw a graphical element defined by the characters in
2598 see groff info file for details.
2601 Printable version of the current escape character.
2604 Equivalent to an escape character, but is not interpreted in copy-mode.
2607 Change to font with 1-character name or 1-digit number
2611 Switch back to previous font.
2614 Change to font with 2-character name or 2-digit number
2618 Change to font with arbitrary length name or number expression
2622 Switch back to previous font.
2625 Change to font family with 1-character name
2629 Change to font family with 2-character name
2633 Change to font family with arbitrary length name
2637 Switch back to previous font family.
2640 Return format of register with name
2651 Local horizontal motion; move right
2656 Set height of current font to
2660 Mark horizontal input place in register with arbitrary length name
2668 Horizontal line drawing function (optionally using character
2672 Vertical line drawing function (optionally using character
2685 Switch back to previous color.
2688 Change filling color for closed drawn objects to color
2697 Switch to previous fill color.
2700 The numerical value stored in the register variable with the
2705 The numerical value stored in the register variable with the
2710 The numerical value stored in the register variable with arbitrary
2715 Typeset the character with code
2717 in the current font, no special fonts are searched.
2719 Useful for adding characters to a font using the
2723 .ESCq o abc.\|.\|.\&
2724 Overstrike characters
2731 Disable glyph output.
2733 Mainly for internal use.
2736 Enable glyph output.
2738 Mainly for internal use.
2741 Break and spread output line.
2744 Reverse 1\ em vertical motion (reverse line in nroff).
2746 .ESCq R "name\~\[+-]n"
2753 Set the point size to
2757 Note the alternative forms
2758 .BI \[rs]s \[+-] [ N ]\c
2760 .BI \[rs]s' \[+-]N '\c
2762 .BI \[rs]s \[+-] ' N '\c
2764 .escarg s( \[+-]xy\c
2766 .BI \[rs]s \[+-] ( xy\c
2779 Non-interpreted horizontal tab.
2782 Reverse (up) 1/2 em vertical motion (1/2 line in nroff).
2785 Local vertical motion; move down
2790 The contents of the environment variable
2799 The width of the character sequence
2803 Extra line-space function (negative before, positive after).
2808 as device control function.
2811 Output string variable or macro
2813 uninterpreted as device control function.
2823 with zero width (without spacing).
2828 and then restore the horizontal and vertical position;
2830 may not contain tabs or leaders.
2834 The escape sequences
2846 are interpreted in copy mode.
2849 Escape sequences starting with
2853 do not represent single character escape sequences, but introduce escape
2854 names with two or more characters.
2857 If a backslash is followed by a character that does not constitute a
2858 defined escape sequence the backslash is silently ignored and the
2859 character maps to itself.
2862 .\" --------------------------------------------------------------------
2863 .SS "Special Characters"
2864 .\" --------------------------------------------------------------------
2866 Common special characters are predefined by escape sequences of the
2874 Some of these exist in the usual font while most of them are only
2875 available in the special font.
2877 Below you'll find a selection of the most important glyphs; a complete
2878 list can be found in
2879 .BR groff_char (@MAN7EXT@).
2897 Printable double quote
2905 Printable backslash character
2928 .\" --------------------------------------------------------------------
2930 .\" --------------------------------------------------------------------
2932 Strings are defined by the
2934 request and can be retrieved by the
2939 Strings share their name space with macros.
2941 So strings and macros without arguments are roughly equivalent; it is
2942 possible to call a string like a macro and vice-versa, but this often
2943 leads to unpredictable results.
2945 The following strings are predefined in groff.
2948 The name of the current output device as specified by the
2950 command line option.
2953 .\" --------------------------------------------------------------------
2955 .\" --------------------------------------------------------------------
2957 Registers are variables that store a value.
2958 In groff, most registers store numerical values (see section
2959 .B NUMERICAL EXPRESSIONS
2960 above), but some can also hold a string value.
2963 Each register is given a name.
2964 Arbitrary registers can be defined and set with the request
2969 The value stored in a register can be retrieved by the escape sequences
2974 Most useful are predefined registers.
2976 In the following the notation
2978 is used to refer to a register called
2980 to make clear that we speak about registers.
2982 Please keep in mind that the
2984 decoration is not part of the register name.
2987 .\" --------------------------------------------------------------------
2988 .SS "Read-only Registers"
2989 .\" --------------------------------------------------------------------
2991 The following registers have predefined values that should not be
2992 modified by the user (usually, registers starting with a dot a
2995 Mostly, they provide information on the current settings or store
2996 results from request calls.
3002 Number of arguments in the current macro or string.
3005 Post-line extra line-space most recently utilized using
3013 is used; always\~1 in
3017 Current input line number.
3020 1\~if compatibility mode is in effect, 0\~otherwise.
3023 The depth of the last character added to the current environment.
3024 It is positive if the character extends below the baseline.
3027 The number of lines remaining to be centered, as set by the
3032 The height of the last character added to the current environment.
3033 It is positive if the character extends above the baseline.
3036 1\~if colors are enabled, 0\~otherwise.
3039 The skew of the last character added to the current environment.
3040 The skew of a character is how far to the right of the center of a character
3041 the center of an accent over that character should be placed.
3044 Current vertical place in current diversion; equal to register
3048 The name or number of the current environment (string-valued).
3051 Current font number.
3054 The current font family (string-valued).
3057 The current (internal) real font name (string-valued).
3060 The number of the next free font position.
3063 Always 1 in GNU troff.
3065 Macros should use it to test if running under groff.
3068 Text base-line high-water mark on current page or diversion.
3071 Available horizontal resolution in basic units.
3074 The current hyphenation language as set by the
3079 The number of immediately preceding consecutive hyphenated lines.
3082 The maximum allowed number of consecutive hyphenated lines, as set by
3088 The current hyphenation flags (as set by the
3093 The current hyphenation margin (as set by the
3098 The current hyphenation space (as set by the
3106 The indent that applies to the current output line.
3109 Positive if last output line contains
3113 1\~if pairwise kerning is enabled, 0\~otherwise.
3116 Current line length.
3119 The current ligature mode (as set by the
3124 The current line-tabs mode (as set by the
3129 The line length that applies to the current output line.
3132 The title length (as set by the
3137 Length of text portion on previous output line.
3140 The amount of space that was needed in the last
3142 request that caused a trap to be sprung.
3144 Useful in conjunction with
3148 1\~if in no-space mode, 0\~otherwise.
3151 Current page offset.
3154 Current page length.
3157 1\~during page ejection, 0\~otherwise.
3160 The number of the next page: either the value set by a
3162 request, or the number of the current page plus\ 1.
3165 The current pointsize in scaled points.
3168 The last-requested pointsize in scaled points.
3171 The current post-vertical line spacing.
3174 The number of lines to be right-justified as set by the rj request.
3177 Current point size as a decimal fraction.
3180 The last requested pointsize in points as a decimal fraction
3184 Distance to the next trap.
3193 A string representation of the current tab settings suitable for use
3194 as an argument to the
3199 The amount of vertical space truncated by the most recently sprung
3200 vertical position trap, or, if the trap was sprung by a
3202 request, minus the amount of vertical motion produced by
3205 In other words, at the point a trap is sprung, it represents
3206 the difference of what the vertical position would have been but for
3207 the trap, and what the vertical position actually is.
3209 Useful in conjunction with the
3214 The value of the parameters set by the first argument of the
3219 The value of the parameters set by the second argument of the
3224 Equal to 1 bin fill mode and 0 in nofill mode.
3227 Current vertical line spacing.
3230 Available vertical resolution in basic units.
3233 1\~ if vertical position traps are enabled, 0\~otherwise.
3236 Width of previous character.
3239 The sum of the number codes of the currently enabled warnings.
3242 The major version number.
3245 The minor version number.
3248 The revision number of groff.
3251 Name of current diversion.
3255 .\" --------------------------------------------------------------------
3256 .SS "Writable Registers"
3257 .\" --------------------------------------------------------------------
3259 The following registers can be read and written by the user.
3260 They have predefined default values, but these can be modified for
3261 customizing a document.
3266 Current page number.
3269 Current input line number.
3272 Character type (set by width function
3276 Maximal width of last completed diversion.
3279 Height of last completed diversion.
3282 Current day of week (1-7).
3285 Current day of month (1-31).
3288 The number of hours past midnight.
3290 Initialized at start-up.
3293 Current horizontal position at input line.
3296 Lower left x-coordinate (in PostScript units) of a given PostScript
3301 Lower left y-coordinate (in PostScript units) of a given PostScript
3309 The number of minutes after the hour.
3311 Initialized at start-up.
3314 Current month (1-12).
3317 Vertical position of last printed text base-line.
3322 but takes account of the heights and depths of characters.
3327 but takes account of the heights and depths of characters.
3330 Depth of string below base line (generated by width function
3334 The number of seconds after the minute.
3336 Initialized at start-up.
3339 Right skip width from the center of the last character in the
3344 If greater than 0, the maximum number of objects on the input stack.
3346 If \[<=]0 there is no limit, i.e., recursion can continue until virtual
3347 memory is exhausted.
3350 The amount of horizontal space (possibly negative) that should be
3351 added to the last character before a subscript (generated by width
3356 Height of string above base line (generated by width function
3360 The return value of the
3362 function executed by the last
3367 Upper right x-coordinate (in PostScript units) of a given PostScript
3372 Upper right y-coordinate (in PostScript units) of a given PostScript
3377 The current year (year 2000 compliant).
3380 Current year minus 1900.
3382 For Y2K compliance use register
3389 .\" --------------------------------------------------------------------
3391 .\" --------------------------------------------------------------------
3393 The differences of the groff language in comparison to classical troff
3397 .BR groff_diff (@MAN7EXT@).
3400 The groff system provides a compatibility mode, see
3401 .BR groff (@MAN1EXT@)
3402 on how to invoke this.
3405 .\" --------------------------------------------------------------------
3407 .\" --------------------------------------------------------------------
3410 .MTO bug-groff@gnu.org "groff bug mailing list" .
3411 Include a complete, self-contained example that will allow the bug to
3412 be reproduced, and say which version of groff you are using.
3415 .\" --------------------------------------------------------------------
3417 .\" --------------------------------------------------------------------
3419 Copyright (C) 2000, 2001, 2002, 2003 Free Software Foundation, Inc.
3422 This document is distributed under the terms of the FDL (GNU Free
3423 Documentation License) version 1.1 or later.
3425 You should have received a copy of the FDL on your system, it is also
3426 available on-line at the
3427 .URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" .
3430 This document is part of
3432 the GNU roff distribution.
3435 .MTO bwarken@mayn.de "Bernd Warken" ;
3437 .MTO wl@gnu.org "Werner Lemberg" .
3440 .\" --------------------------------------------------------------------
3442 .\" --------------------------------------------------------------------
3445 The main source of information for the groff language is the
3450 Besides the gory details, it contains many examples.
3453 .BR groff (@MAN1EXT@)
3454 the usage of the groff program and pointers to the documentation and
3455 availability of the groff system.
3458 .BR groff_diff (@MAN7EXT@)
3459 the differences of the groff language as compared to classical roff.
3461 This is the authoritative document for the predefined language
3462 elements that are specific to groff.
3465 .BR groff_char (@MAN7EXT@)
3466 the predefined groff characters (glyphs).
3469 .BR groff_font (@MAN5EXT@)
3470 the specification of fonts and the DESC file.
3473 .BR roff (@MAN7EXT@)
3474 the history of roff, the common parts shared by all roff systems, and
3475 pointers to further documentation.
3479 .URL http://\:cm.bell-labs.com/\:cm/\:cs/\:54.ps \
3480 "Nroff/\:Troff User's Manual by Osanna & Kernighan"
3481 \[em] the bible for classical troff.
3484 .\" --------------------------------------------------------------------
3486 .\" --------------------------------------------------------------------
3488 .\" Local Variables: