5 Last update: 23 Jul 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 .\" --------------------------------------------------------------------
44 .\" --------------------------------------------------------------------
45 .\" start of macro definitions
54 .c ---------------------------------------------------------------------
57 .c All arguments are printed as text.
62 .c ---------------------------------------------------------------------
63 .c .ExecFF macro font1 font2 text1 text2 text1 text2 ...
65 .c Concat text arguments using alternating fonts and feed into macro.
66 .c For a trailing punctuation, terminate the call with \c.
81 . as @s \f[\*[@f1]]\*[@a]\f[]\"
86 . as @s \f[\*[@f2]]\*[@a]\f[]\"
89 . \*[@m] "\*[@s]\f[R]"
90 . ft P \" to make \c happy
98 .c --------- command line option ---------
105 .c --------- characters ---------
108 . ExecFF Text CB R \$*
113 . ExecFF Text R CB \[oq] \*[@1] "\[cq]\$*"
119 . ExecFF Text R CB \[lq] \*[@1] "\[rq]\$*"
122 .c --------- requests ---------
124 .c synopsis of a request
130 . ie (\n[.$] = 0) \{\
132 . Text \f[CB]\*[@1]\f[]
136 . Text \f[CB]\*[@1]\~\f[]\f[I]\$*\f[]
140 .c reference of a request
145 .c --------- numerical elements ---------
147 .c number with a trailing unit
149 . Text \$1\^\f[CB]\$2\f[]\$3\f[R]
153 .c representation of units within the text
155 . Text \f[CB]\$1\f[]\$2\f[R]
159 .c representation of mathematical operators within the text
165 .c --------- escape sequences ---------
167 .c ---------------------------------------------------------------------
170 .c Synopsis of an escape sequence, optionally with argument
171 .c Args : 1 or 2; `name' obligatory, `arg' optional
172 .c name : suitable name for an escape sequence (c, (xy, [long])
173 .c arg : arbitrary word
174 .c Result : prints \namearg, where `name' is in CB, `arg' in I
178 . ab .ESC needs 1 or 2 arguments.
179 . ExecFF IP CB I "\[rs]\$1" "\,\$2\/"
181 .c ---------------------------------------------------------------------
184 .c Synopsis for escape sequence with a bracketed long argument
185 .c Args : 2 obligatory
186 .c name : suitable name for an escape sequence (c, (xy, [long])
187 .c arg : arbitrary text
188 .c Result : prints \name[arg], where `name' is in CB, `arg' in I
192 . ab .ESC[] needs exactly 2 arguments.
193 . ExecFF IP CB I "\[rs]\$1\[lB]" "\h'-0.2m'\$2\h'-0.15m'" \[rB]
195 .c ---------------------------------------------------------------------
198 .c Synopsis for escape sequence with a bracketed long argument
199 .c Args : 2 obligatory
200 .c name : suitable name for an escape sequence (c, (xy, [long])
201 .c arg : arbitrary text
202 .c Result : prints \name'arg', where `name' is in CB, `arg' in I
206 . ab .ESCq needs exactly 2 argument.
207 . ExecFF IP CB I "\[rs]\$1\[cq]" "\h'-0.3m'\$2" \[cq]
209 .c ---------------------------------------------------------------------
212 .c Synopsis for escape sequence with a bracketed long argument
213 .c Args : 1 obligatory
214 .c arg : arbitrary text
215 .c Result : prints `\?arg?', where the `?' are in CB, `arg' in I
219 . ab .ESC? needs exactly 1 arguments.
220 . ExecFF IP CB I \[rs]? "\$1" ?
222 .c ---------------------------------------------------------------------
225 .c Reference of an escape sequence (no args), possibly punctuation
226 .c Args : 1 obligatory
227 .c name : suitable name for an escape sequence (c, (xy, [long])
229 .c Result : prints \name, where `name' is in B, `punct' in R
233 . ab .esc needs 1 or 2 arguments.
236 .c ---------------------------------------------------------------------
237 .c .escarg name arg [punct]
239 .c Reference of an escape sequence (no args)
240 .c Args : 1 obligatory, 1 optional
241 .c name : suitable name for an escape sequence (c, (xy, [long])
242 .c arg : arbitrary word
243 .c Result : prints \namearg, where
244 .c `name' is in B, `arg' in I
248 . ab .esc needs 2 or 3 arguments.
249 . Text \f[B]\[rs]\$1\f[]\f[I]\$2\f[]\$3
251 .c ---------------------------------------------------------------------
252 .c .esc[] name arg [punct]
254 .c Reference for escape sequence with a bracketed long argument
255 .c Args : 2 obligatory
256 .c name : suitable name for an escape sequence (c, (xy, [long])
257 .c arg : arbitrary text
258 .c Result : prints \name[arg], where `name' is in CB, `arg' in CI
262 . ab .esc[] needs 2 or 3 arguments.
263 . Text \f[B]\[rs]\$1\[lB]\f[]\f[I]\$2\f[]\f[B]\[rB]\f[]\$3
266 .c ---------------------------------------------------------------------
269 .c Reference for escape sequence with a bracketed long argument
270 .c Args : 2 obligatory
271 .c name : suitable name for an escape sequence (c, (xy, [long])
272 .c arg : arbitrary text
273 .c Result : prints \name'arg', where `name' is in CB, `arg' in CI
277 . ab .escq needs 2 arguments.
278 . Text \f[B]\[rs]\$1\[cq]\f[]\f[I]\$2\f[]\f[B]\[cq]\f[]\$3
281 .c --------- strings ---------
283 .c synopsis for string, with \*[]
288 . ExecFF Text R CB \[rs]*[ \*[@1]\f[]\f[R]] \$*
291 .c synopsis for a long string
295 . Text \f[CB]\[rs]*\[lB]\$1\[rB]\f[]\$2
299 .c --------- registers ---------
301 .c synopsis for registers, with \n[]
306 . ExecFF Text R CB \[rs]n[ \*[@1]\f[]\f[R]] \$*
309 .c reference of a register, without decoration
316 .\" end of macro definitions
319 .\" --------------------------------------------------------------------
321 .\" --------------------------------------------------------------------
323 .TH GROFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
325 groff \- a short reference for the GNU roff language
328 .\" --------------------------------------------------------------------
330 .\" --------------------------------------------------------------------
336 and is the free implementation of the roff type-setting system.
340 for a survey and the background of the groff system.
343 This document gives only short descriptions of the predefined roff
344 language elements as used in groff.
346 Both the classical features and the groff extensions are provided.
354 is compatible with the classical system and provides proper
362 could be used as synonyms.
366 slightly tends to refer more to the classical aspects, whereas
368 emphasizes the GNU extensions, and
370 is the general term for the language.
373 This file is only a short version of the complete documentation that
377 file, which contains more detailed, actual, and concise information.
380 The general syntax for writing groff documents is relatively easy, but
381 writing extensions to the roff language can be a bit harder.
384 The roff language is line-oriented.
386 There are only two kinds of lines, control lines and text lines.
388 The control lines start with a control character, by default a period
392 all other lines are text lines.
396 represent commands, optionally with arguments.
398 They have the following syntax.
400 The leading control character can be followed by a command name;
401 arguments, if any, are separated by blanks from the command name and
402 among themselves, for example,
406 .Text .command_name arg1 arg2
410 For indentation, any number of space or tab characters can be inserted
411 between the leading control character and the command name, but the
412 control character must be on the first position of the line.
416 represent the parts that will be printed.
417 They can be modified by escape sequences, which are recognized by a
419 .squoted_char \[rs] .
420 These are in-line or even in-word formatting elements or functions.
422 Some of these take arguments separated by single quotes
424 others are regulated by a length encoding introduced by an open
427 or enclosed in brackets
433 The roff language provides flexible instruments for writing language
434 extension, such as macros.
436 When interpreting macro definitions, the roff system enters a special
437 operating mode, called the
441 The copy mode behavior can be quite tricky, but there are some rules
442 that ensure a safe usage.
445 Printable backslashes must be denoted as
449 represents the current escape character.
451 To get a backslash glyph, use
456 Double all backslashes.
458 Begin all text lines with the special non-spacing character
462 This does not produce the most efficient code, but it should work as a
465 For better strategies, see the groff info file and
466 .BR groff_tmac (@MAN5EXT@).
469 Reading roff source files is easier, just reduce all double backslashes
470 to a single one in all macro definitions.
473 .\" --------------------------------------------------------------------
475 .\" --------------------------------------------------------------------
477 The roff language elements add formatting information to a text file.
479 The fundamental elements are predefined commands and variables that
480 make roff a full-blown programming language.
483 There are two kinds of roff commands, possibly with arguments.
485 are written on a line of their own starting with a dot
491 are in-line functions and in-word formatting elements starting with a
493 .squoted_char \[rs] .
496 The user can define her own formatting commands using the
500 These commands are called
502 but they are used exactly like requests.
504 Macro packages are pre-defined sets of macros written in the groff
507 A user's possibilities to create escape sequences herself is very
508 limited, only special characters can be mapped.
511 The groff language provides several kinds of variables with
512 different interfaces.
514 There are pre-defined variables, but the user can define her own
519 variables store character sequences.
521 They are set with the
523 request and retrieved by the
527 Strings can have variables.
531 variables can store numerical values, numbers with a scale unit, and
532 occasionally string-like objects.
534 They are set with the
536 request and retrieved by the
542 allow the user to temporarily store global formatting parameters like
543 line length, font size, etc.\& for later reuse.
551 are identified either by a name or by an internal number.
553 The current font is chosen by the
559 Each device has special fonts, but the following fonts are available
562 is the standard font Roman.
572 and is available everywhere, but on text devices it is displayed as an
573 underlined Roman font.
575 For the graphical output devices, there exist constant-width pendants
581 On text devices, all characters have a constant width anyway.
584 Moreover, there are some advanced roff elements.
588 stores information into a macro for later usage.
592 is a positional condition like a certain number of lines from page top
593 or in a diversion or in the input.
595 Some action can be prescribed to be run automatically when the
599 More detailed information and examples can be found in the groff info
603 .\" --------------------------------------------------------------------
604 .SH "CONTROL CHARACTERS"
605 .\" --------------------------------------------------------------------
607 There is a small set of characters that have a special controlling
608 task in certain conditions.
612 A dot is only special at the beginning of a line or after the
613 condition in the requests
619 There it is the control character that introduces a request (or macro).
621 The special behavior can be delayed by using the
627 request, the control character can be set to a different character,
630 a non-special character.
632 In all other positions, it just means a dot character.
634 In text paragraphs, it is advantageous to start each sentence at a
639 The single quote has two controlling tasks.
641 At the beginning of a line and in the conditional requests it is the
642 non-breaking control character.
644 That means that it introduces a request like the dot, but with the
645 additional property that this request doesn't cause a linebreak.
649 request, the non-break control character can be set to a different
653 As a second task, it is the most commonly used argument separator in
654 some functional escape sequences (but any pair of characters not part
655 of the argument will work).
657 In all other positions, it denotes the single quote or apostrophe
660 Groff provides a printable representation with the
666 The double quote is used to enclose arguments in requests, macros, and
673 requests, a leading double quote in the argument will be stripped off,
674 making everything else afterwards the string to be defined (enabling
677 The escaped double quote
679 introduces a comment.
681 Otherwise, it is not special.
683 Groff provides a printable representation with the
689 The backslash usually introduces an escape sequence (this can be
694 A printed version of the escape character is the
696 escape; a backslash glyph can be obtained by
700 The open parenthesis is only special in escape sequences when
701 introducing an escape name or argument consisting of exactly two
704 In groff, this behavior can be replaced by the \f[CB][]\f[] construct.
707 The opening bracket is only special in groff escape sequences; there
708 it is used to introduce a long escape name or long escape argument.
710 Otherwise, it is non-special, e.g.\& in macro calls.
713 The closing bracket is only special in groff escape sequences; there
714 it terminates a long escape name or long escape argument.
716 Otherwise, it is non-special.
719 Space characters are only functional characters.
721 They separate the arguments in requests, macros, and strings, and the words
724 They are subject to groff's horizontal spacing calculations.
726 To get a defined space width, escape sequences like
727 .squoted_char "\[rs]\ "
728 (this is the escape character followed by a space),
735 .IP \f[CI]newline\f[]
736 In text paragraphs, newlines mostly behave like space characters.
738 Continuation lines can be specified by an escaped newline, i.e., by
739 specifying a backslash
741 as the last character of a line.
743 If a tab character occurs during text the interpreter makes a
744 horizontal jump to the next pre-defined tab position.
746 There is a sophisticated interface for handling tab positions.
749 .\" --------------------------------------------------------------------
750 .SH "NUMERICAL EXPRESSIONS"
751 .\" --------------------------------------------------------------------
755 is a signed or unsigned integer or float with or without an appended
760 is a one-character abbreviation for a unit of measurement.
762 A number followed by a scaling indicator signifies a size value.
764 By default, numerical values do not have a scaling indicator, i.e., they
770 language defines the following scaling indicators.
787 Pica\ \[eq]\ 1/6\ inch
791 Point\ \[eq]\ 1/72\ inch
795 Em\ \[eq]\ \f[R]the font size in points (width of letter `\f[CR]m\f[R]')
799 100\^th \f[R]of an \f[CR]Em
807 Basic unit for actual output device
811 Vertical line space in basic units
812 scaled point\ \[eq]\ 1/\f[CI]sizescale\f[R] of a point (defined in
813 font \f[I]DESC\f[] file)
822 .B Numerical expressions
823 are combinations of the numerical values defined above with the
824 following arithmetical operators already defined in classical troff.
888 Grouping of expressions
892 Close current grouping
900 added the following operators for numerical expressions:
907 .ExecFF Text I CB e1 >? e2
914 .ExecFF Text I CB e1 <? e2
921 .ExecFF Text CB I ( c ; e )
926 as the default scaling indicator.
932 For details see the groff info file.
935 .\" --------------------------------------------------------------------
937 .\" --------------------------------------------------------------------
940 occur in tests raised by the
947 The following table characterizes the different types of conditions.
955 A numerical expression
957 yields true if its value is greater than\~0.
969 is identical to string\~\c
976 is not identical to string\~\c
981 True if there is a character\~\c
987 True if there is a string, macro, diversion, or request called
992 Current page number is even.
996 Current page number is odd.
1000 True if there is a color called
1010 True if there is a register named
1022 .\" --------------------------------------------------------------------
1024 .\" --------------------------------------------------------------------
1026 This section provides a short reference for the predefined requests.
1028 In groff, request and macro names can be arbitrarily long.
1030 No bracketing or marking of long names is needed.
1033 Most requests take one or more arguments.
1035 The arguments are separated by space characters (no tabs!); there is
1036 no inherent limit for their length or number.
1038 An argument can be enclosed by a pair of double quotes.
1040 This is very handy if an argument contains space characters, e.g.,
1041 .RI \[dq] "arg with space" \[dq]
1042 denotes a single argument.
1045 Some requests have optional arguments with a different behaviour.
1047 Not all of these details are outlined here.
1049 Refer to the groff info file and
1050 .BR groff_diff (@MAN7EXT@)
1054 In the following request specifications, most argument names were
1055 chosen to be descriptive.
1057 Only the following denotations need clarification.
1065 denotes a single character.
1069 a font either specified as a font name or a font number.
1073 all characters up to the end of the line or within
1080 is a numerical expression that evaluates to an integer value.
1084 is an arbitrary numerical expression, signed or unsigned.
1088 has three meanings depending on its sign, described below.
1094 If an expression defined as
1098 sign the resulting value of the expression will be added to an already
1099 existing value inherent to the related request, e.g.\& adding to a number
1102 If the expression starts with a
1104 the value of the expression will be subtracted from the request value.
1109 replaces the existing value directly.
1111 To assign a negative number either prepend\~0 or enclose the negative
1112 number in parentheses.
1115 .\" --------------------------------------------------------------------
1116 .SS "Request Short Reference"
1117 .\" --------------------------------------------------------------------
1122 Empty line, ignored.
1124 Useful for structuring documents.
1126 .REQ .\[rs]\[dq] anything
1127 Complete line is a comment.
1132 on standard error, exit program.
1135 Begin line adjustment for output lines in current adjust mode.
1138 Start line adjustment in mode
1140 (\f[CI]c\f[]\f[CR]\|\^\[eq]\|l,r,b,n\f[]).
1147 (\f[CI]c\f[]\f[CR]\|\^\[eq]\|l,i,I,a,A\f[]).
1149 .REQ .aln alias register
1150 Create alias name for
1153 .REQ .als alias object
1154 Create alias name for request, string, macro, or diversion
1174 but with compatibility mode switched off during macro expansion.
1179 but with compatibility mode switched off during macro expansion.
1182 Append to a macro whose name is contained in the string register
1189 Append to a macro indirectly.
1193 are string registers whose contents are interpolated for the macro name
1194 and the end macro, respectively.
1199 but with compatibility mode switched off during macro expansion.
1201 .REQ .ami1 macro end
1204 but with compatibility mode switched off during macro expansion.
1206 .REQ .as stringvar anything
1212 .REQ .as1 stringvar anything
1215 but with compatibility mode switched off during string expansion.
1217 .REQ .asciify diversion
1218 Unformat ASCII characters, spaces, and some escape sequences in
1222 Print a backtrace of the input on stderr.
1232 Embolden Special Font
1234 when current font is
1238 Unset the blank line macro.
1241 Set the blank line macro to
1245 End current diversion.
1250 omitting a partially filled line.
1253 End current diversion.
1256 Divert and append to
1258 omitting a partially filled line.
1261 Eject current page and begin new page.
1264 Eject current page; next page number
1271 Break and spread output line.
1276 Break out of a while loop.
1279 Reset no-break control character to
1283 Set no-break control character to
1287 Reset control character to
1291 Set control character to
1295 Center the next input line.
1303 Copy contents of file
1305 unprocessed to stdout or to the diversion.
1307 .REQ .cflags mode c1 c2 .\|.\|.\&
1323 .REQ .char c anything
1330 Chop the last character off macro, string, or diversion
1343 is zero disable colors, otherwise enable them.
1345 .REQ .composite from to
1350 while constructing a composite glyph name.
1353 Finish the current iteration of a while loop.
1356 Enable compatibility mode.
1361 is zero disable compatibility mode, otherwise enable it.
1364 Set constant character width mode for
1372 Continuous underline in nroff, like
1377 End current diversion.
1380 Divert and append to
1400 but with compatibility mode switched off during macro expansion.
1405 but with compatibility mode switched off during macro expansion.
1407 .REQ .defcolor color scheme component
1408 Define or redefine a color with name
1419 can be single components specified as fractions in the range 0 to 1
1420 (default scaling indicator\~\c
1421 .scaleindicator f ),
1422 as a string of two-digit hexadecimal color components with a leading
1424 or as a string of four-digit hexadecimal components with two leading
1431 Define or redefine a macro whose name is contained in the string register
1438 Define or redefine a macro indirectly.
1442 are string registers whose contents are interpolated for the macro name
1443 and the end macro, respectively.
1448 but with compatibility mode switched off during macro expansion.
1450 .REQ .dei1 macro end
1453 but with compatibility mode switched off during macro expansion.
1456 End current diversion.
1465 with compatibility mode disabled.
1467 .REQ .ds stringvar anything
1473 .REQ .ds1 stringvar anything
1476 but with compatibility mode switched off during string expansion.
1479 Set diversion trap to position
1481 (default scaling indicator\~\c
1482 .scaleindicator v ).
1485 Reset escape character to
1486 .squoted_char \[rs] .
1489 Set escape character to
1493 Restore escape character saved with
1497 Save current escape character.
1500 Else part for if-else (\c
1507 will be run after the end of input.
1510 Turn off escape character mechanism.
1513 Switch to previous environment.
1516 Push down environment number or name
1521 Copy the contents of environment
1523 to the current environment.
1524 No pushing or popping.
1527 Exit from roff processing.
1530 Return to previous font family.
1533 Set the current font family to
1537 Disable field mechanism.
1540 Set field delimiter to
1542 and pad character to space.
1545 Set field delimiter to
1547 and pad character to
1550 .REQ .fchar c anything
1551 Define fallback character
1560 Flush output buffer.
1568 .REQ .fp n internal external
1569 Mount font with long
1576 .REQ .fschar f c anything
1577 Define fallback character
1585 Reset list of special fonts for
1589 .REQ .fspecial font s1 s2 .\|.\|.\&
1590 When the current font is
1599 Return to previous font.
1606 Change to font name or number
1612 .REQ .ftr font1 font2
1619 Remove additional hyphenation indicator character.
1622 Set up additional hyphenation indicator character\~\c
1625 .REQ .hcode c1 code1 c2 code2 .\|.\|.\&
1626 Set the hyphenation code of character
1637 Set the current hyphenation language to
1641 Set the maximum number of consecutive hyphenated lines to
1645 Read hyphenation patterns from
1649 Append hyphenation patterns from
1653 Set input mapping for
1659 with exceptional hyphenation.
1662 Switch to hyphenation mode
1666 Set the hyphenation margin to
1668 (default scaling indicator\~\c
1669 .scaleindicator m ).
1672 Set the hyphenation space to
1675 .REQ .ie cond anything
1683 .REQ .if cond anything
1688 otherwise do nothing.
1700 Change to previous indent value.
1703 Change indent according to
1705 (default scaling indicator\~\c
1706 .scaleindicator m ).
1709 Set an input-line count trap for the next
1716 but count lines interrupted with
1721 Enable pairwise kerning.
1726 is zero, disable pairwise kerning, otherwise enable it.
1729 Remove leader repetition character.
1732 Set leader repetition character to\~\c
1735 .REQ .length register anything
1736 Write the length of the string
1742 Enable line-tabs mode (i.e., calculate tab positions relative to output
1748 is zero, disable line-tabs mode, otherwise enable it.
1751 Set input line number to
1755 Set input line number to
1765 Change to previous line length.
1768 Set line length according to
1771 .scalednumber 6.5 i ,
1772 default scaling indicator\~\c
1773 .scaleindicator m ).
1776 Change to the previous value of additional intra-line skip.
1779 Set additional intra-line skip value to
1783 blank lines are inserted after each text output line.
1786 Length of title (default scaling indicator\~\c
1787 .scaleindicator m ).
1790 Margin character off.
1795 after each text line at actual distance from right margin.
1798 Set margin character to
1802 from right margin (default scaling indicator\~\c
1803 .scaleindicator m ).
1806 Mark current vertical position in
1810 The same as the .so request except that
1812 is searched in the tmac directories.
1815 No output-line adjusting.
1818 Need a one-line vertical space.
1823 vertical space (default scaling indicator\~\c
1824 .scaleindicator v ).
1827 No filling or adjusting of output-lines.
1835 .REQ .nm \[+-]N \fR[\fPM \fR[\fPS \fR[\fPI\fR]]]\fP
1836 In line number mode, set number, multiple, spacing, and indent.
1839 Do not number next line.
1850 .REQ .nr register \[+-]N M
1859 Make the built-in condition
1866 Turn no-space mode on.
1869 Immediately jump to end of current file.
1874 .REQ .open stream filename
1877 for writing and associate the stream named
1881 .REQ .opena stream filename
1887 Output vertical distance that was saved by the
1894 directly to intermediate output, allowing leading whitespace if
1898 (which will be stripped off).
1901 Reset page number character to\~\c
1905 Page number character.
1913 Set page length to default
1914 .scalednumber 11 i .
1915 The current page length is stored in
1919 Change page length to
1921 (default scaling indicator\~\c
1922 .scaleindicator v ).
1925 Print macro names and sizes (number of blocks of 128 bytes).
1928 Print only total of sizes of macros (number of 128 bytes blocks).
1935 Print the names and contents of all currently defined number registers
1939 Change to previous page offset.
1941 The current page offset is available in
1949 Return to previous point-size.
1955 Get the bounding box of a PostScript image
1959 This behaves like the
1961 request except that input comes from the standard output of
1965 Print the names and positions of all traps (not including input line
1966 traps and diversion traps) on stderr.
1969 Change to previous post-vertical line spacing.
1972 Change post-vertical line spacing according to
1974 (default scaling indicator\~\c
1975 .scaleindicator p ).
1977 .REQ .rchar c1 c2 .\|.\|.\&
1978 Remove the definitions of characters
1987 Return from a macro.
1989 .REQ .return anything
1990 Return twice, namely from the macro at the current level and from the macro
1993 .REQ .rfschar f c1 c2 .\|.\|.\&
1994 Remove the definitions of characters
2002 Right justify the next
2007 Remove request, macro, or string
2011 Rename request, macro, or string
2027 Restore spacing; turn no-space mode off.
2032 to marked vertical place (default scaling indicator\~\c
2033 .scaleindicator v ).
2035 .REQ .schar c anything
2036 Define global fallback character
2042 Reset soft hyphen character to
2046 Set the soft hyphen character to
2050 In a macro, shift the arguments by
2054 .REQ .sizes s1 s2 .\|.\|.\& sn \fB[0]\fP
2055 Set available font sizes similar to the
2062 Include source file.
2065 Skip one line vertically.
2068 Space vertical distance
2070 up or down according to sign of
2072 (default scaling indicator\~\c
2073 .scaleindicator v ).
2076 Reset global list of special fonts to be empty.
2078 .REQ .special s1 s2 .\|.\|.\&
2082 etc.\& are special and will be searched for characters not in the
2086 Toggle the spread warning on and off without changing its value.
2088 .REQ .spreadwarn limit
2089 Emit a warning if each space in an output line is widened by
2091 or more (default scaling indicator\~\c
2092 .scaleindicator m ).
2095 Space-character size set to
2097 of the spacewidth in the current font.
2100 Space-character size set to
2102 and sentence space size set to
2104 of the spacewidth in the current font (\f[CR]\[eq]1/3 em\f[]).
2112 .REQ .substring xx n1 n2
2113 Replace the string named
2115 with the substring defined by the indices
2126 Save the vertical distance
2128 for later output with
2132 .REQ .sy command-line
2137 Set tabs after every position that is a multiple of
2139 (default scaling indicator\~\c
2140 .scaleindicator m ).
2141 .REQ .ta n1 n2 .\|.\|.\& nn \f[CB]T\f[] r1 r2 .\|.\|.\& rn
2142 Set tabs at positions
2160 .\"Restore internally saved tab positions.
2163 .\"Save tab positions internally.
2166 Remove tab repition character.
2168 Set tab repetition character to\~\c
2172 Temporary indent next line (default scaling indicator\~\c
2173 .scaleindicator m ).
2175 .REQ .tkf font s1 n1 s2 n2
2176 Enable track kerning for
2179 .REQ .tl \f[CB]\[cq]\f[]left\f[CB]\[cq]\f[]center\f[CB]\[cq]\f[]right\f[CB]\[cq]\f[]
2185 on terminal (UNIX standard message output).
2190 on terminal (UNIX standard message output), allowing leading
2195 (which will be stripped off).
2200 without emitting a final newline.
2202 .REQ .tr abcd.\|.\|.\&
2213 Transparently output the contents of file
2216 .REQ .trin abcd.\|.\|.\&
2217 This is the same as the
2219 request except that the
2221 request will use the character code (if any) before the character
2224 .REQ .trnt abcd.\|.\|.\&
2225 This is the same as the
2227 request except that the translations do not apply to text that is
2228 transparently throughput into a diversion with
2232 Make the built-in condition
2239 Underline font set to
2241 (to be switched to by
2245 Underline (italicize in troff)
2249 .REQ .unformat diversion
2250 Unformat space characters and tabs, preserving font information in
2253 Enable vertical position traps if
2255 is non-zero, disable them otherwise.
2258 Change to previous vertical base line spacing.
2261 Set vertical base line spacing according to
2263 (default scaling indicator\~\c
2264 .scaleindicator p ).
2266 .scalednumber 12 p .
2269 Set warnings code to
2273 Set scaling indicator used in warnings to
2277 Remove (first) trap at position
2281 Set location trap; negative means from page bottom.
2283 .REQ .while cond anything
2290 .REQ .write stream anything
2296 .REQ .writec stream anything
2299 without emitting a final newline.
2301 .REQ .writem stream xx
2302 Write contents of macro or string
2310 Besides these standard groff requests, there might be further macro
2312 They can originate from a macro package (see
2313 .BR roff (@MAN7EXT@)
2314 for an overview) or from a preprocessor.
2317 Preprocessor macros are easy to be recognized.
2319 They enclose their code into a pair of characteristic macros.
2323 box, center, tab (@);
2326 preprocessor@start macro@ end macro
2333 soelim@\f[I]none@\f[I]none
2339 .\" --------------------------------------------------------------------
2340 .SH "ESCAPE SEQUENCES"
2341 .\" --------------------------------------------------------------------
2343 Escape sequences are in-line language elements usually introduced by a
2346 and followed by an escape name and sometimes by a required argument.
2348 Input processing is continued directly after the escaped character or
2349 the argument resp.\& without an intervening separation character.
2351 So there must be a way to determine the end of the escape name and the
2352 end of the argument.
2355 This is done by enclosing names (escape name and arguments consisting
2356 of a variable name) by a pair of brackets
2357 .BI \[lB] name \[rB]
2358 and constant arguments (number expressions and characters) by
2359 apostrophes (ASCII 0x27) like
2360 .BI \[cq] constant \[cq] \f[R].
2363 There are abbreviations for short names.
2365 Two character escape names can be specified by an opening parenthesis
2368 without a closing counterpart.
2370 And all one-character names different from the special characters
2374 can even be specified without a marker in the form
2378 Constant arguments of length\~1 can omit the marker apostrophes, too,
2379 but there is no two-character analogue.
2382 While 1-character escape sequences are mainly used for in-line
2383 functions and system related tasks, the 2-letter names following the
2385 construct are used for special characters predefined by the roff system.
2387 Escapes sequences with names of more than two characters
2389 denote user defined named characters (see the
2394 .\" --------------------------------------------------------------------
2395 .SS "Single Character Escapes"
2396 .\" --------------------------------------------------------------------
2400 .\" --------- comments ---------
2403 Beginning of a comment.
2405 Everything up to the end of the line is ignored.
2408 Everything up to and including the next newline is ignored.
2410 This is interpreted in copy mode.
2414 except that the terminating newline is ignored as well.
2416 .\" --------- strings ---------
2419 The string stored in the string variable with 1-character name
2423 The string stored in the string variable with 2-character name
2426 .ESC[] * "stringvar arg1 arg2 .\|.\|."
2427 The string stored in the string variable with arbitrary length name
2435 .\" --------- macro arguments ---------
2438 The name by which the current macro was invoked.
2442 request can make a macro have more than one name.
2445 Macro or string argument with 1-place number
2449 is a digit between 1 and 9.
2452 Macro or string argument with 2-digit number
2456 Macro or string argument with number
2460 is a numerical expression evaluating to an integer \[>=]1.
2463 In a macro or string, the concatenation of all the arguments separated
2467 In a macro or string, the concatenation of all the arguments with each
2468 surrounded by double quotes, and separated by spaces.
2470 .\" --------- escaped characters ---------
2473 reduces to a single backslash; useful to delay its interpretation as
2474 escape character in copy mode.
2476 For a printable backslash, use
2480 to be independent from the current escape character.
2483 The acute accent \[aa]; same as
2485 Unescaped: apostrophe, right quotation mark, single quote (ASCII 0x27).
2488 The grave accent \[ga]; same as
2490 Unescaped: left quote, backquote (ASCII 0x60).
2493 The \- sign in the current font.
2496 An uninterpreted dot (period), even at start of line.
2499 Default optional hyphenation character.
2502 Transparent line indicator.
2505 In a diversion, this will transparently embed
2509 is read in copy mode.
2511 See also the escape sequences
2517 .\" --------- spacing ---------
2520 Unpaddable space-size space character (no line break).
2526 1/6\ em narrow space character; zero width in nroff.
2529 1/12\ em half-narrow space character; zero width in nroff.
2532 Non-printable, zero width character.
2537 except that it behaves like a character declared with the cflags
2538 request to be transparent for the purposes of end of sentence
2542 Increases the width of the preceding character so that the spacing
2543 between that character and the following character will be correct if
2544 the following character is a roman character.
2547 Modifies the spacing of the following character so that the spacing
2548 between that character and the preceding character will correct if the
2549 preceding character is a roman character.
2552 Unbreakable space that stretches like a normal inter-word space when a
2556 Inserts a zero-width break point (similar to
2558 but without a soft hyphen character).
2561 Ignored newline, for continuation lines.
2563 .\" --------- structuring ---------
2566 Begin conditional input.
2569 End conditional input.
2571 .\" --------- longer escape names ---------
2574 The special character with 2-character name
2577 .BR "Special Characters" .
2580 The named character (or rather glyph) with arbitrary length name
2583 .ESC[] "" "comp1 comp2 .\|.\|."
2584 A composite glyph with components
2589 .\" --------- alphabetical escapes ---------
2592 Non-interpreted leader character.
2597 is acceptable as a name of a string, macro, diversion, register,
2598 environment or font it expands to\~1, and to\~0 otherwise.
2600 .ESCq b abc.\|.\|.\&
2601 Bracket building function.
2606 is acceptable as a valid numeric expression it expands to\~1, and
2610 Interrupt text processing.
2613 The character called
2617 but compatible to other roff versions.
2620 Forward (down) 1/2 em vertical unit (1/2 line in nroff).
2623 Draw a graphical element defined by the characters in
2625 see groff info file for details.
2628 Printable version of the current escape character.
2631 Equivalent to an escape character, but is not interpreted in copy-mode.
2634 Change to font with 1-character name or 1-digit number
2638 Switch back to previous font.
2641 Change to font with 2-character name or 2-digit number
2645 Change to font with arbitrary length name or number expression
2649 Switch back to previous font.
2652 Change to font family with 1-character name
2656 Change to font family with 2-character name
2660 Change to font family with arbitrary length name
2664 Switch back to previous font family.
2667 Return format of register with name
2678 Local horizontal motion; move right
2683 Set height of current font to
2687 Mark horizontal input place in register with arbitrary length name
2695 Horizontal line drawing function (optionally using character
2699 Vertical line drawing function (optionally using character
2712 Switch back to previous color.
2715 Change filling color for closed drawn objects to color
2724 Switch to previous fill color.
2727 The numerical value stored in the register variable with the
2732 The numerical value stored in the register variable with the
2737 The numerical value stored in the register variable with arbitrary
2742 Typeset the character with code
2744 in the current font, no special fonts are searched.
2746 Useful for adding characters to a font using the
2750 .ESCq o abc.\|.\|.\&
2751 Overstrike characters
2758 Disable glyph output.
2760 Mainly for internal use.
2763 Enable glyph output.
2765 Mainly for internal use.
2768 Break and spread output line.
2771 Reverse 1\ em vertical motion (reverse line in nroff).
2773 .ESCq R "name\~\[+-]n"
2780 Set the point size to
2784 Note the alternative forms
2785 .BI \[rs]s \[+-] [ N ]\c
2787 .BI \[rs]s' \[+-]N '\c
2789 .BI \[rs]s \[+-] ' N '\c
2791 .escarg s( \[+-]xy\c
2793 .BI \[rs]s \[+-] ( xy\c
2806 Non-interpreted horizontal tab.
2809 Reverse (up) 1/2 em vertical motion (1/2 line in nroff).
2812 Local vertical motion; move down
2817 The contents of the environment variable
2826 The width of the character sequence
2830 Extra line-space function (negative before, positive after).
2835 as device control function.
2838 Output string variable or macro
2840 uninterpreted as device control function.
2850 with zero width (without spacing).
2855 and then restore the horizontal and vertical position;
2857 may not contain tabs or leaders.
2861 The escape sequences
2873 are interpreted in copy mode.
2876 Escape sequences starting with
2880 do not represent single character escape sequences, but introduce escape
2881 names with two or more characters.
2884 If a backslash is followed by a character that does not constitute a
2885 defined escape sequence the backslash is silently ignored and the
2886 character maps to itself.
2889 .\" --------------------------------------------------------------------
2890 .SS "Special Characters"
2891 .\" --------------------------------------------------------------------
2893 Common special characters are predefined by escape sequences of the
2901 Some of these exist in the usual font while most of them are only
2902 available in the special font.
2904 Below you'll find a selection of the most important glyphs; a complete
2905 list can be found in
2906 .BR groff_char (@MAN7EXT@).
2924 Printable double quote
2932 Printable backslash character
2955 .\" --------------------------------------------------------------------
2957 .\" --------------------------------------------------------------------
2959 Strings are defined by the
2961 request and can be retrieved by the
2966 Strings share their name space with macros.
2968 So strings and macros without arguments are roughly equivalent; it is
2969 possible to call a string like a macro and vice-versa, but this often
2970 leads to unpredictable results.
2972 The following strings are predefined in groff.
2975 The name of the current output device as specified by the
2977 command line option.
2980 .\" --------------------------------------------------------------------
2982 .\" --------------------------------------------------------------------
2984 Registers are variables that store a value.
2985 In groff, most registers store numerical values (see section
2986 .B NUMERICAL EXPRESSIONS
2987 above), but some can also hold a string value.
2990 Each register is given a name.
2991 Arbitrary registers can be defined and set with the request
2996 The value stored in a register can be retrieved by the escape sequences
3001 Most useful are predefined registers.
3003 In the following the notation
3005 is used to refer to a register called
3007 to make clear that we speak about registers.
3009 Please keep in mind that the
3011 decoration is not part of the register name.
3014 .\" --------------------------------------------------------------------
3015 .SS "Read-only Registers"
3016 .\" --------------------------------------------------------------------
3018 The following registers have predefined values that should not be
3019 modified by the user (usually, registers starting with a dot a
3022 Mostly, they provide information on the current settings or store
3023 results from request calls.
3029 Number of arguments in the current macro or string.
3032 Post-line extra line-space most recently utilized using
3040 is used; always\~1 in
3044 Current input line number.
3047 1\~if compatibility mode is in effect, 0\~otherwise.
3050 The depth of the last character added to the current environment.
3051 It is positive if the character extends below the baseline.
3054 The number of lines remaining to be centered, as set by the
3059 The height of the last character added to the current environment.
3060 It is positive if the character extends above the baseline.
3063 1\~if colors are enabled, 0\~otherwise.
3066 The skew of the last character added to the current environment.
3067 The skew of a character is how far to the right of the center of a character
3068 the center of an accent over that character should be placed.
3071 Current vertical place in current diversion; equal to register
3075 The name or number of the current environment (string-valued).
3078 Current font number.
3081 The current font family (string-valued).
3084 The current (internal) real font name (string-valued).
3087 The number of the next free font position.
3090 Always 1 in GNU troff.
3092 Macros should use it to test if running under groff.
3095 Text base-line high-water mark on current page or diversion.
3098 Available horizontal resolution in basic units.
3101 The current font height as set with
3105 The current hyphenation language as set by the
3110 The number of immediately preceding consecutive hyphenated lines.
3113 The maximum allowed number of consecutive hyphenated lines, as set by
3119 The current hyphenation flags (as set by the
3124 The current hyphenation margin (as set by the
3129 The current hyphenation space (as set by the
3137 The indent that applies to the current output line.
3140 Positive if last output line contains
3144 1\~if pairwise kerning is enabled, 0\~otherwise.
3147 Current line length.
3150 The current ligature mode (as set by the
3155 The current line-tabs mode (as set by the
3160 The line length that applies to the current output line.
3163 The title length (as set by the
3168 Length of text portion on previous output line.
3171 The amount of space that was needed in the last
3173 request that caused a trap to be sprung.
3175 Useful in conjunction with
3179 1\~if in no-space mode, 0\~otherwise.
3182 Current page offset.
3185 Current page length.
3188 1\~during page ejection, 0\~otherwise.
3191 The number of the next page: either the value set by a
3193 request, or the number of the current page plus\ 1.
3196 The current pointsize in scaled points.
3199 The last-requested pointsize in scaled points.
3202 The current post-vertical line spacing.
3205 The number of lines to be right-justified as set by the rj request.
3208 Current point size as a decimal fraction.
3211 The slant of the current font as set with
3215 The last requested pointsize in points as a decimal fraction
3219 Distance to the next trap.
3228 A string representation of the current tab settings suitable for use
3229 as an argument to the
3234 The amount of vertical space truncated by the most recently sprung
3235 vertical position trap, or, if the trap was sprung by a
3237 request, minus the amount of vertical motion produced by
3240 In other words, at the point a trap is sprung, it represents
3241 the difference of what the vertical position would have been but for
3242 the trap, and what the vertical position actually is.
3244 Useful in conjunction with the
3249 The value of the parameters set by the first argument of the
3254 The value of the parameters set by the second argument of the
3259 Equal to 1 bin fill mode and 0 in nofill mode.
3262 Current vertical line spacing.
3265 Available vertical resolution in basic units.
3268 1\~ if vertical position traps are enabled, 0\~otherwise.
3271 Width of previous character.
3274 The sum of the number codes of the currently enabled warnings.
3277 The major version number.
3280 The minor version number.
3283 The revision number of groff.
3286 Name of current diversion.
3290 .\" --------------------------------------------------------------------
3291 .SS "Writable Registers"
3292 .\" --------------------------------------------------------------------
3294 The following registers can be read and written by the user.
3295 They have predefined default values, but these can be modified for
3296 customizing a document.
3301 Current page number.
3304 Current input line number.
3307 Character type (set by width function
3311 Maximal width of last completed diversion.
3314 Height of last completed diversion.
3317 Current day of week (1-7).
3320 Current day of month (1-31).
3323 The number of hours past midnight.
3325 Initialized at start-up.
3328 Current horizontal position at input line.
3331 Lower left x-coordinate (in PostScript units) of a given PostScript
3336 Lower left y-coordinate (in PostScript units) of a given PostScript
3344 The number of minutes after the hour.
3346 Initialized at start-up.
3349 Current month (1-12).
3352 Vertical position of last printed text base-line.
3357 but takes account of the heights and depths of characters.
3362 but takes account of the heights and depths of characters.
3365 Depth of string below base line (generated by width function
3369 The number of seconds after the minute.
3371 Initialized at start-up.
3374 Right skip width from the center of the last character in the
3379 If greater than 0, the maximum number of objects on the input stack.
3381 If \[<=]0 there is no limit, i.e., recursion can continue until virtual
3382 memory is exhausted.
3385 The amount of horizontal space (possibly negative) that should be
3386 added to the last character before a subscript (generated by width
3391 Height of string above base line (generated by width function
3395 The return value of the
3397 function executed by the last
3402 Upper right x-coordinate (in PostScript units) of a given PostScript
3407 Upper right y-coordinate (in PostScript units) of a given PostScript
3412 The current year (year 2000 compliant).
3415 Current year minus 1900.
3417 For Y2K compliance use register
3424 .\" --------------------------------------------------------------------
3426 .\" --------------------------------------------------------------------
3428 The differences of the groff language in comparison to classical troff
3432 .BR groff_diff (@MAN7EXT@).
3435 The groff system provides a compatibility mode, see
3436 .BR groff (@MAN1EXT@)
3437 on how to invoke this.
3440 .\" --------------------------------------------------------------------
3442 .\" --------------------------------------------------------------------
3445 .MTO bug-groff@gnu.org "groff bug mailing list" .
3446 Include a complete, self-contained example that will allow the bug to
3447 be reproduced, and say which version of groff you are using.
3450 .\" --------------------------------------------------------------------
3452 .\" --------------------------------------------------------------------
3454 Copyright (C) 2000, 2001, 2002, 2003 Free Software Foundation, Inc.
3457 This document is distributed under the terms of the FDL (GNU Free
3458 Documentation License) version 1.1 or later.
3460 You should have received a copy of the FDL on your system, it is also
3461 available on-line at the
3462 .URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" .
3465 This document is part of
3467 the GNU roff distribution.
3470 .MTO bwarken@mayn.de "Bernd Warken" ;
3472 .MTO wl@gnu.org "Werner Lemberg" .
3475 .\" --------------------------------------------------------------------
3477 .\" --------------------------------------------------------------------
3480 The main source of information for the groff language is the
3485 Besides the gory details, it contains many examples.
3488 .BR groff (@MAN1EXT@)
3489 the usage of the groff program and pointers to the documentation and
3490 availability of the groff system.
3493 .BR groff_diff (@MAN7EXT@)
3494 the differences of the groff language as compared to classical roff.
3496 This is the authoritative document for the predefined language
3497 elements that are specific to groff.
3500 .BR groff_char (@MAN7EXT@)
3501 the predefined groff characters (glyphs).
3504 .BR groff_font (@MAN5EXT@)
3505 the specification of fonts and the DESC file.
3508 .BR roff (@MAN7EXT@)
3509 the history of roff, the common parts shared by all roff systems, and
3510 pointers to further documentation.
3514 .URL http://\:cm.bell-labs.com/\:cm/\:cs/\:54.ps \
3515 "Nroff/\:Troff User's Manual by Osanna & Kernighan"
3516 \[em] the bible for classical troff.
3520 .\" --------------------------------------------------------------------
3522 .\" --------------------------------------------------------------------
3524 .\" Local Variables: