5 This file is part of groff, the GNU roff type-setting system.
7 Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
8 Free Software Foundation, Inc.
9 written by Bernd Warken <bwarken@mayn.de>
10 maintained by Werner Lemberg <wl@gnu.org>
12 Permission is granted to copy, distribute and/or modify this document
13 under the terms of the GNU Free Documentation License, Version 1.1 or
14 any later version published by the Free Software Foundation; with the
15 Invariant Sections being this .ig-section and AUTHORS, with no
16 Front-Cover Texts, and with no Back-Cover Texts.
18 A copy of the Free Documentation License is included as a file called
19 FDL in the main directory of the groff source package.
22 .\" --------------------------------------------------------------------
24 .\" --------------------------------------------------------------------
29 .\" --------------------------------------------------------------------
30 .\" start of macro definitions
35 .\" ---------------------------------------------------------------------
36 .\" .Text anything ...
38 .\" All arguments are printed as text.
44 .\" --------- command line option ---------
51 .\" --------- characters ---------
54 . Text \[oq]\f[CB]\\$1\f[]\[cq]\\$2
57 . Text \[lq]\f[CB]\\$1\f[]\[rq]\\$2
59 .\" --------- requests ---------
61 .\" synopsis of a request
67 . Text \f[CB]\\$1\~\f[]\f[I]\\$2\f[]
71 .\" reference of a request
76 .\" --------- numerical elements ---------
78 .\" number with a trailing unit
80 . Text \\$1\^\f[CB]\\$2\f[]\\$3\f[R]
84 .\" representation of units within the text
86 . Text \f[CB]\\$1\f[]\\$2\f[R]
90 .\" representation of mathematical operators within the text
96 .\" --------- escape sequences ---------
98 .\" ---------------------------------------------------------------------
101 .\" Synopsis of an escape sequence, optionally with argument
102 .\" Args : 1 or 2; `name' obligatory, `arg' optional
103 .\" name : suitable name for an escape sequence (c, (xy, [long])
104 .\" arg : arbitrary word
105 .\" Result : prints \namearg, where `name' is in CB, `arg' in I
108 . Text "\f[CB]\[rs]\\$1\,\f[I]\\$2\/\fR"
110 .\" ---------------------------------------------------------------------
113 .\" Synopsis for escape sequence with a bracketed long argument
114 .\" Args : 2 obligatory
115 .\" name : suitable name for an escape sequence (c, (xy, [long])
116 .\" arg : arbitrary text
117 .\" Result : prints \name[arg], where `name' is in CB, `arg' in I
120 . Text "\f[CB]\[rs]\\$1\[lB]\f[]\f[I]\\$2\f[]\f[CB]\[rB]\f[]"
122 .\" ---------------------------------------------------------------------
125 .\" Synopsis for escape sequence with a bracketed long argument
126 .\" Args : 2 obligatory
127 .\" name : suitable name for an escape sequence (c, (xy, [long])
128 .\" arg : arbitrary text
129 .\" Result : prints \name'arg', where `name' is in CB, `arg' in I
132 . Text "\f[CB]\[rs]\\$1\[cq]\f[]\f[I]\\$2\f[]\f[CB]\[cq]\f[]"
134 .\" ---------------------------------------------------------------------
137 .\" Synopsis for escape sequence with a bracketed long argument
138 .\" Args : 1 obligatory
139 .\" arg : arbitrary text
140 .\" Result : prints `\?arg?', where the `?' are in CB, `arg' in I
143 . Text "\f[CB]\[rs]?\f[I]\\$1\f[CB]?\f[R]"
145 .\" ---------------------------------------------------------------------
146 .\" .esc name [punct]
148 .\" Reference of an escape sequence (no args), possibly punctuation
149 .\" Args : 1 obligatory
150 .\" name : suitable name for an escape sequence (c, (xy, [long])
151 .\" punct : arbitrary
152 .\" Result : prints \name, where `name' is in B, `punct' in R
155 . BR "\[rs]\\$1" \\$2
157 .\" ---------------------------------------------------------------------
158 .\" .escarg name arg [punct]
160 .\" Reference of an escape sequence (no args)
161 .\" Args : 1 obligatory, 1 optional
162 .\" name : suitable name for an escape sequence (c, (xy, [long])
163 .\" arg : arbitrary word
164 .\" Result : prints \namearg, where
165 .\" `name' is in B, `arg' in I
168 . Text \f[B]\[rs]\\$1\f[]\f[I]\\$2\f[]\\$3
170 .\" ---------------------------------------------------------------------
171 .\" .esc[] name arg [punct]
173 .\" Reference for escape sequence with a bracketed long argument
174 .\" Args : 2 obligatory
175 .\" name : suitable name for an escape sequence (c, (xy, [long])
176 .\" arg : arbitrary text
177 .\" Result : prints \name[arg], where `name' is in CB, `arg' in CI
180 . Text \f[B]\[rs]\\$1\[lB]\f[]\f[I]\\$2\f[]\f[B]\[rB]\f[]\\$3
183 .\" ---------------------------------------------------------------------
186 .\" Reference for escape sequence with a bracketed long argument
187 .\" Args : 2 obligatory
188 .\" name : suitable name for an escape sequence (c, (xy, [long])
189 .\" arg : arbitrary text
190 .\" Result : prints \name'arg', where `name' is in CB, `arg' in CI
193 . Text \f[B]\[rs]\\$1\[cq]\f[]\f[I]\\$2\f[]\f[B]\[cq]\f[]\\$3
196 .\" --------- strings ---------
198 .\" synopsis for string, with \*[]
200 . Text \[rs]*[\f[CB]\\$1\f[]] \\$2
202 .\" synopsis for a long string
206 . Text \f[CB]\[rs]*\[lB]\\$1\[rB]\f[]\\$2
209 .\" --------- registers ---------
211 .\" synopsis for registers, with \n[]
213 . Text \[rs]n[\f[CB]\\$1\f[]]
215 .\" reference of a register, without decoration
221 .\" end of macro definitions
224 .\" --------------------------------------------------------------------
226 .\" --------------------------------------------------------------------
228 .TH GROFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
230 groff \- a short reference for the GNU roff language
233 .\" --------------------------------------------------------------------
235 .\" --------------------------------------------------------------------
241 and is the free implementation of the roff type-setting system.
245 for a survey and the background of the groff system.
248 This document gives only short descriptions of the predefined roff
249 language elements as used in groff.
251 Both the classical features and the groff extensions are provided.
259 is compatible with the classical system and provides proper
267 could be used as synonyms.
271 slightly tends to refer more to the classical aspects, whereas
273 emphasizes the GNU extensions, and
275 is the general term for the language.
278 This file is only a short version of the complete documentation that
282 file, which contains more detailed, actual, and concise information.
285 The general syntax for writing groff documents is relatively easy, but
286 writing extensions to the roff language can be a bit harder.
289 The roff language is line-oriented.
291 There are only two kinds of lines, control lines and text lines.
293 The control lines start with a control character, by default a period
297 all other lines are text lines.
301 represent commands, optionally with arguments.
303 They have the following syntax.
305 The leading control character can be followed by a command name;
306 arguments, if any, are separated by spaces (but not tab characters)
307 from the command name and among themselves, for example,
311 .Text .command_name arg1 arg2
315 For indentation, any number of space or tab characters can be inserted
316 between the leading control character and the command name, but the
317 control character must be on the first position of the line.
321 represent the parts that is printed.
322 They can be modified by escape sequences, which are recognized by a
324 .squoted_char \[rs] .
325 These are in-line or even in-word formatting elements or functions.
327 Some of these take arguments separated by single quotes
329 others are regulated by a length encoding introduced by an open
332 or enclosed in brackets
338 The roff language provides flexible instruments for writing language
339 extension, such as macros.
341 When interpreting macro definitions, the roff system enters a special
342 operating mode, called the
346 The copy mode behavior can be quite tricky, but there are some rules
347 that ensure a safe usage.
350 Printable backslashes must be denoted as
354 represents the current escape character.
356 To get a backslash glyph, use
361 Double all backslashes.
363 Begin all text lines with the special non-spacing character
367 This does not produce the most efficient code, but it should work as a
370 For better strategies, see the groff info file and
371 .BR groff_tmac (@MAN5EXT@).
374 Reading roff source files is easier, just reduce all double backslashes
375 to a single one in all macro definitions.
378 .\" --------------------------------------------------------------------
380 .\" --------------------------------------------------------------------
382 The roff language elements add formatting information to a text file.
384 The fundamental elements are predefined commands and variables that
385 make roff a full-blown programming language.
388 There are two kinds of roff commands, possibly with arguments.
390 are written on a line of their own starting with a dot
396 are in-line functions and in-word formatting elements starting with a
398 .squoted_char \[rs] .
401 The user can define her own formatting commands using the
405 These commands are called
407 but they are used exactly like requests.
409 Macro packages are pre-defined sets of macros written in the groff
412 A user's possibilities to create escape sequences herself is very
413 limited, only special characters can be mapped.
416 The groff language provides several kinds of variables with
417 different interfaces.
419 There are pre-defined variables, but the user can define her own
424 variables store character sequences.
426 They are set with the
428 request and retrieved by the
432 Strings can have variables.
436 variables can store numerical values, numbers with a scale unit, and
437 occasionally string-like objects.
439 They are set with the
441 request and retrieved by the
447 allow the user to temporarily store global formatting parameters like
448 line length, font size, etc.\& for later reuse.
456 are identified either by a name or by an internal number.
458 The current font is chosen by the
464 Each device has special fonts, but the following fonts are available
467 is the standard font Roman.
477 and is available everywhere, but on text devices it is displayed as an
478 underlined Roman font.
480 For the graphical output devices, there exist constant-width pendants
486 On text devices, all glyphs have a constant width anyway.
490 are visual representation forms of
492 In groff, the distinction between those two elements is not always
493 obvious (and a full discussion is beyond the scope of this man page).
495 A first approximation is that glyphs have a specific size and
496 colour and are taken from a specific font; they can't be modified any
497 more \[en] characters are the input, and glyphs are the output.
499 As soon as an output line has been generated, it no longer contains
500 characters but glyphs.
502 In this man page, we use either `glyph' or `character', whatever is
506 Moreover, there are some advanced roff elements.
510 stores (formatted) information into a macro for later usage.
514 is a positional condition like a certain number of lines from page top
515 or in a diversion or in the input.
517 Some action can be prescribed to be run automatically when the
521 More detailed information and examples can be found in the groff info
525 .\" --------------------------------------------------------------------
526 .SH "CONTROL CHARACTERS"
527 .\" --------------------------------------------------------------------
529 There is a small set of characters that have a special controlling
530 task in certain conditions.
534 A dot is only special at the beginning of a line or after the
535 condition in the requests
541 There it is the control character that introduces a request (or macro).
543 The special behavior can be delayed by using the
549 request, the control character can be set to a different character,
552 a non-special character.
554 In all other positions, it just means a dot character.
556 In text paragraphs, it is advantageous to start each sentence at a
561 The single quote has two controlling tasks.
563 At the beginning of a line and in the conditional requests it is the
564 non-breaking control character.
566 That means that it introduces a request like the dot, but with the
567 additional property that this request doesn't cause a linebreak.
571 request, the non-break control character can be set to a different
575 As a second task, it is the most commonly used argument separator in
576 some functional escape sequences (but any pair of characters not part
577 of the argument do work).
579 In all other positions, it denotes the single quote or apostrophe
582 Groff provides a printable representation with the
588 The double quote is used to enclose arguments in macros (but not in
589 requests and strings).
595 requests, a leading double quote in the argument is stripped off,
596 making everything else afterwards the string to be defined (enabling
599 The escaped double quote
601 introduces a comment.
603 Otherwise, it is not special.
605 Groff provides a printable representation with the
611 The backslash usually introduces an escape sequence (this can be
616 A printed version of the escape character is the
618 escape; a backslash glyph can be obtained by
622 The open parenthesis is only special in escape sequences when
623 introducing an escape name or argument consisting of exactly two
626 In groff, this behavior can be replaced by the \f[CB][]\f[] construct.
629 The opening bracket is only special in groff escape sequences; there
630 it is used to introduce a long escape name or long escape argument.
632 Otherwise, it is non-special, e.g.\& in macro calls.
635 The closing bracket is only special in groff escape sequences; there
636 it terminates a long escape name or long escape argument.
638 Otherwise, it is non-special.
641 Space characters are only functional characters.
643 They separate the arguments in requests, macros, and strings, and the words
646 They are subject to groff's horizontal spacing calculations.
648 To get a defined space width, escape sequences like
649 .squoted_char "\[rs]\ "
650 (this is the escape character followed by a space),
657 .IP \f[CI]newline\f[]
658 In text paragraphs, newlines mostly behave like space characters.
660 Continuation lines can be specified by an escaped newline, i.e., by
661 specifying a backslash
663 as the last character of a line.
665 If a tab character occurs during text the interpreter makes a
666 horizontal jump to the next pre-defined tab position.
668 There is a sophisticated interface for handling tab positions.
671 .\" --------------------------------------------------------------------
672 .SH "NUMERICAL EXPRESSIONS"
673 .\" --------------------------------------------------------------------
677 is a signed or unsigned integer or float with or without an appended
682 is a one-character abbreviation for a unit of measurement.
684 A number followed by a scaling indicator signifies a size value.
686 By default, numerical values do not have a scaling indicator, i.e., they
692 language defines the following scaling indicators.
709 Pica\ \[eq]\ 1/6\ inch
713 Point\ \[eq]\ 1/72\ inch
717 Em\ \[eq]\ \f[R]the font size in points (approx.\& width of letter
722 100\^th \f[R]of an \f[CR]Em
730 Basic unit for actual output device
734 Vertical line space in basic units
735 scaled point\ \[eq]\ 1/\f[CI]sizescale\f[R] of a point (defined in
736 font \f[I]DESC\f[] file)
745 .B Numerical expressions
746 are combinations of the numerical values defined above with the
747 following arithmetical operators already defined in classical troff.
811 Grouping of expressions
815 Close current grouping
823 added the following operators for numerical expressions:
830 \f[I]e1\f[CB]>?\f[I]e2\f[R]
837 \f[I]e1\f[CB]<?\f[I]e2\f[R]
844 \f[CB](\f[I]c\f[CB];\f[I]e\f[CB])\f[R]
849 as the default scaling indicator.
855 For details see the groff info file.
858 .\" --------------------------------------------------------------------
860 .\" --------------------------------------------------------------------
863 occur in tests raised by the
870 The following table characterizes the different types of conditions.
878 A numerical expression
880 yields true if its value is greater than\~0.
892 is identical to string\~\c
899 is not identical to string\~\c
904 True if there is a glyph\~\c
910 True if there is a string, macro, diversion, or request called
915 Current page number is even.
919 Current page number is odd.
923 True if there is a color called
933 True if there is a register named
943 True if there exists a font named
948 True if a style named
956 .\" --------------------------------------------------------------------
958 .\" --------------------------------------------------------------------
960 This section provides a short reference for the predefined requests.
962 In groff, request, macro, and string names can be arbitrarily long.
964 No bracketing or marking of long names is needed.
967 Most requests take one or more arguments.
969 The arguments are separated by space characters (no tabs!); there is
970 no inherent limit for their length or number.
973 Some requests have optional arguments with a different behaviour.
975 Not all of these details are outlined here.
977 Refer to the groff info file and
978 .BR groff_diff (@MAN7EXT@)
982 In the following request specifications, most argument names were
983 chosen to be descriptive.
985 Only the following denotations need clarification.
993 denotes a single character.
997 a font either specified as a font name or a font number.
1001 all characters up to the end of the line or within
1008 is a numerical expression that evaluates to an integer value.
1012 is an arbitrary numerical expression, signed or unsigned.
1016 has three meanings depending on its sign, described below.
1022 If an expression defined as
1026 sign the resulting value of the expression is added to an already
1027 existing value inherent to the related request, e.g.\& adding to a number
1030 If the expression starts with a
1032 the value of the expression is subtracted from the request value.
1037 replaces the existing value directly.
1039 To assign a negative number either prepend\~0 or enclose the negative
1040 number in parentheses.
1043 .\" --------------------------------------------------------------------
1044 .SS "Request Short Reference"
1045 .\" --------------------------------------------------------------------
1051 Empty line, ignored.
1053 Useful for structuring documents.
1056 .REQ .\[rs]\[dq] "anything"
1057 Complete line is a comment.
1063 on standard error, exit program.
1067 Begin line adjustment for output lines in current adjust mode.
1071 Start line adjustment in mode
1073 (\f[CI]c\f[]\f[CR]\|\^\[eq]\|l,r,b,n\f[]).
1076 .REQ .af "register c"
1081 (\f[CI]c\f[]\f[CR]\|\^\[eq]\|l,i,I,a,A\f[]).
1084 .REQ .aln "alias register"
1085 Create alias name for
1089 .REQ .als "alias object"
1090 Create alias name for request, string, macro, or diversion
1102 .REQ .am "macro end"
1113 but with compatibility mode switched off during macro expansion.
1116 .REQ .am1 "macro end"
1119 but with compatibility mode switched off during macro expansion.
1123 Append to a macro whose name is contained in the string register
1130 .REQ .ami "macro end"
1131 Append to a macro indirectly.
1135 are string registers whose contents are interpolated for the macro name
1136 and the end macro, respectively.
1142 but with compatibility mode switched off during macro expansion.
1145 .REQ .ami1 "macro end"
1148 but with compatibility mode switched off during macro expansion.
1151 .REQ .as "stringvar anything"
1158 .REQ .as1 "stringvar anything"
1161 but with compatibility mode switched off during string expansion.
1164 .REQ .asciify "diversion"
1165 Unformat ASCII characters, spaces, and some escape sequences in
1170 Print a backtrace of the input on stderr.
1182 Embolden Special Font
1184 when current font is
1189 Unset the blank line macro.
1193 Set the blank line macro to
1198 End current diversion.
1204 omitting a partially filled line.
1208 End current diversion.
1212 Divert and append to
1214 omitting a partially filled line.
1218 Eject current page and begin new page.
1222 Eject current page; next page number
1231 Break and spread output line.
1237 Break out of a while loop.
1241 Reset no-break control character to
1246 Set no-break control character to
1251 Reset control character to
1256 Set control character to
1261 Center the next input line.
1271 Copy contents of file
1273 unprocessed to stdout or to the diversion.
1276 .REQ .cflags "mode c1 c2 .\|.\|.\&"
1294 .REQ .char "c anything"
1302 Chop the last character off macro, string, or diversion
1306 .REQ .close "stream"
1318 is zero disable colors, otherwise enable them.
1321 .REQ .composite "from to"
1326 while constructing a composite glyph name.
1330 Finish the current iteration of a while loop.
1334 Enable compatibility mode.
1340 is zero disable compatibility mode, otherwise enable it.
1344 Set constant character width mode for
1353 Continuous underline in nroff, like
1359 End current diversion.
1363 Divert and append to
1375 .REQ .de "macro end"
1386 but with compatibility mode switched off during macro expansion.
1389 .REQ .de1 "macro end"
1392 but with compatibility mode switched off during macro expansion.
1395 .REQ .defcolor "color scheme component"
1396 Define or redefine a color with name
1407 can be single components specified as fractions in the range 0 to 1
1408 (default scaling indicator\~\c
1409 .scaleindicator f ),
1410 as a string of two-digit hexadecimal color components with a leading
1412 or as a string of four-digit hexadecimal components with two leading
1420 Define or redefine a macro whose name is contained in the string register
1427 .REQ .dei "macro end"
1428 Define or redefine a macro indirectly.
1432 are string registers whose contents are interpolated for the macro name
1433 and the end macro, respectively.
1439 but with compatibility mode switched off during macro expansion.
1442 .REQ .dei1 "macro end"
1445 but with compatibility mode switched off during macro expansion.
1448 .REQ .device "anything"
1451 to the intermediate output as a device control function.
1454 .REQ .devicem "name"
1455 Write contents of macro or string
1457 uninterpreted to the intermediate output as a device control function.
1461 End current diversion.
1472 with compatibility mode disabled.
1475 .REQ .ds "stringvar anything"
1482 .REQ .ds1 "stringvar anything"
1485 but with compatibility mode switched off during string expansion.
1489 Set diversion trap to position
1491 (default scaling indicator\~\c
1492 .scaleindicator v ).
1496 Reset escape character to
1497 .squoted_char \[rs] .
1501 Set escape character to
1506 Restore escape character saved with
1511 Save current escape character.
1515 Else part for if-else (\c
1523 is run after the end of input.
1527 Turn off escape character mechanism.
1531 Switch to previous environment and pop it off the stack.
1535 Push down environment number or name
1537 to the stack and switch to it.
1541 Copy the contents of environment
1543 to the current environment.
1544 No pushing or popping.
1548 Exit from roff processing.
1552 Return to previous font family.
1556 Set the current font family to
1561 Disable field mechanism.
1565 Set field delimiter to\~\c
1567 and pad glyph to space.
1571 Set field delimiter to\~\c
1573 and pad glyph to\~\c
1577 .REQ .fchar "c anything"
1578 Define fallback character (or glyph)
1585 Set fill color to previous fill color.
1598 Flush output buffer.
1608 .REQ .fp "n internal external"
1609 Mount font with long
1617 .REQ .fschar "f c anything"
1618 Define fallback character (or glyph)
1626 .REQ .fspecial "font"
1627 Reset list of special fonts for
1632 .REQ .fspecial "font s1 s2 .\|.\|.\&"
1633 When the current font is
1643 Return to previous font.
1651 Change to font name or number
1658 .REQ .ftr "font1 font2"
1670 .REQ .fzoom "font zoom"
1673 (in multiples of 1/1000th).
1677 Set glyph color to previous glyph color.
1686 Remove additional hyphenation indicator character.
1690 Set up additional hyphenation indicator character\~\c
1694 .REQ .hcode "c1 code1 c2 code2 .\|.\|.\&"
1695 Set the hyphenation code of character
1707 Set the current hyphenation language to
1712 Set the maximum number of consecutive hyphenated lines to
1717 Read hyphenation patterns from
1722 Append hyphenation patterns from
1726 .REQ .hpfcode "a b c d .\|.\|.\&"
1727 Set input mapping for
1734 with exceptional hyphenation.
1738 Switch to hyphenation mode
1743 Set the hyphenation margin to
1745 (default scaling indicator\~\c
1746 .scaleindicator m ).
1750 Set the hyphenation space to
1754 .REQ .ie "cond anything"
1763 .REQ .if "cond anything"
1768 otherwise do nothing.
1784 Change to previous indentation value.
1788 Change indentation according to
1790 (default scaling indicator\~\c
1791 .scaleindicator m ).
1795 Set an input-line count trap for the next
1803 but count lines interrupted with
1809 Enable pairwise kerning.
1815 is zero, disable pairwise kerning, otherwise enable it.
1819 Remove leader repetition glyph.
1823 Set leader repetition glyph to\~\c
1827 .REQ .length "register anything"
1828 Write the length of the string
1835 Enable line-tabs mode (i.e., calculate tab positions relative to output
1842 is zero, disable line-tabs mode, otherwise enable it.
1846 Set input line number to
1851 Set input line number to
1863 Change to previous line length.
1867 Set line length according to
1870 .scalednumber 6.5 i ,
1871 default scaling indicator\~\c
1872 .scaleindicator m ).
1876 Change to the previous value of additional intra-line skip.
1880 Set additional intra-line skip value to
1884 blank lines are inserted after each text output line.
1888 Length of title (default scaling indicator\~\c
1889 .scaleindicator m ).
1899 after each text line at actual distance from right margin.
1903 Set margin glyph to\~\c
1907 from right margin (default scaling indicator\~\c
1908 .scaleindicator m ).
1912 Mark current vertical position in
1921 is searched in the tmac directories.
1925 No output-line adjusting.
1929 Need a one-line vertical space.
1935 vertical space (default scaling indicator\~\c
1936 .scaleindicator v ).
1940 No filling or adjusting of output-lines.
1951 .REQ .nm "\[+-]N \fR[\fPM \fR[\fPS \fR[\fPI\fR]]]\fP"
1952 In line number mode, set number, multiple, spacing, and indentation.
1956 Do not number next line.
1965 .REQ .nop "anything"
1970 .REQ .nr "register \[+-]N \fR[\fPM\fR]\fP"
1980 Make the built-in conditions
1988 Turn on no-space mode.
1992 Immediately jump to end of current file.
1996 Immediately continue processing with file
2000 .REQ .open "stream filename"
2003 for writing and associate the stream named
2008 .REQ .opena "stream filename"
2015 Output vertical distance that was saved by the
2020 .REQ .output "string"
2023 directly to intermediate output, allowing leading whitespace if
2027 (which is stripped off).
2031 Reset page number character to\~\c
2036 Page number character.
2040 Print the current environment and each defined environment
2051 Set page length to default
2052 .scalednumber 11 i .
2053 The current page length is stored in
2058 Change page length to
2060 (default scaling indicator\~\c
2061 .scaleindicator v ).
2065 Print macro names and sizes (number of blocks of 128 bytes).
2069 Print only total of sizes of macros (number of 128 bytes blocks).
2078 Print the names and contents of all currently defined number registers
2083 Change to previous page offset.
2085 The current page offset is available in
2095 Return to previous point size.
2102 .REQ .psbb "filename"
2103 Get the bounding box of a PostScript image
2108 This behaves like the
2110 request except that input comes from the standard output of
2115 Print the names and positions of all traps (not including input line
2116 traps and diversion traps) on stderr.
2120 Change to previous post-vertical line spacing.
2124 Change post-vertical line spacing according to
2126 (default scaling indicator\~\c
2127 .scaleindicator p ).
2130 .REQ .rchar "c1 c2 .\|.\|.\&"
2131 Remove the definitions of entities
2142 Return from a macro.
2145 .REQ .return "anything"
2146 Return twice, namely from the macro at the current level and from the macro
2150 .REQ .rfschar "f c1 c2 .\|.\|.\&"
2151 Remove the definitions of entities
2160 Right justify the next
2166 Remove request, macro, or string
2171 Rename request, macro, or string
2177 .REQ .rnn "reg1 reg2"
2190 Restore spacing; turn no-space mode off.
2196 to marked vertical place (default scaling indicator\~\c
2197 .scaleindicator v ).
2200 .REQ .schar "c anything"
2201 Define global fallback character (or glyph)\~\c
2208 Reset soft hyphen glyph to
2213 Set the soft hyphen glyph to\~\c
2218 In a macro, shift the arguments by
2223 .REQ .sizes "s1 s2 .\|.\|.\& sn \fB[0]\fP"
2224 Set available font sizes similar to the
2232 Include source file.
2236 Skip one line vertically.
2240 Space vertical distance
2242 up or down according to sign of
2244 (default scaling indicator\~\c
2245 .scaleindicator v ).
2249 Reset global list of special fonts to be empty.
2252 .REQ .special "s1 s2 .\|.\|.\&"
2256 etc.\& are special and are searched for glyphs not in the
2261 Toggle the spread warning on and off without changing its value.
2264 .REQ .spreadwarn "limit"
2265 Emit a warning if each space in an output line is widened by
2267 or more (default scaling indicator\~\c
2268 .scaleindicator m ).
2272 Set space glyph size to
2274 of the space width in the current font.
2278 Set space glyph size to
2280 and sentence space size set to
2282 of the space width in the current font.
2292 .REQ .substring "xx n1 n2"
2293 Replace the string named
2295 with the substring defined by the indices
2307 Save the vertical distance
2309 for later output with
2311 request (default scaling indicator\~\c
2312 .scaleindicator v ).
2315 .REQ .sy "command-line"
2321 Set tabs after every position that is a multiple of
2323 (default scaling indicator\~\c
2324 .scaleindicator m ).
2326 .REQ .ta "n1 n2 .\|.\|.\& nn \f[CB]T\f[] r1 r2 .\|.\|.\& rn"
2327 Set tabs at positions
2346 .\"Restore internally saved tab positions.
2350 .\"Save tab positions internally.
2354 Remove tab repetition glyph.
2357 Set tab repetition glyph to\~\c
2362 Temporary indent next line (default scaling indicator\~\c
2363 .scaleindicator m ).
2366 .REQ .tkf "font s1 n1 s2 n2"
2367 Enable track kerning for
2371 .REQ .tl "\f[CB]\[cq]\f[]left\f[CB]\[cq]\f[]center\f[CB]\[cq]\f[]right\f[CB]\[cq]\f[]"
2381 .REQ .tm1 "anything"
2384 on stdout, allowing leading whitespace if
2388 (which is stripped off).
2391 .REQ .tmc "anything"
2394 without emitting a final newline.
2397 .REQ .tr "abcd.\|.\|.\&"
2408 .REQ .trf "filename"
2409 Transparently output the contents of file
2413 .REQ .trin "abcd.\|.\|.\&"
2414 This is the same as the
2416 request except that the
2418 request uses the character code (if any) before the character
2422 .REQ .trnt "abcd.\|.\|.\&"
2423 This is the same as the
2425 request except that the translations do not apply to text that is
2426 transparently throughput into a diversion with
2431 Make the built-in conditions
2439 Set underline font to
2441 (to be switched to by
2446 Underline (italicize in troff)
2451 .REQ .unformat "diversion"
2452 Unformat space characters and tabs in
2454 preserving font information.
2457 Enable vertical position traps if
2459 is non-zero, disable them otherwise.
2463 Change to previous vertical base line spacing.
2467 Set vertical base line spacing to
2469 (default scaling indicator\~\c
2470 .scaleindicator p ).
2474 Set warnings code to
2478 .REQ .warnscale "si"
2479 Set scaling indicator used in warnings to
2484 Remove (first) trap at position
2489 Set location trap; negative means from page bottom.
2492 .REQ .while "cond anything"
2500 .REQ .write "stream anything"
2507 .REQ .writec "stream anything"
2510 without emitting a final newline.
2513 .REQ .writem "stream xx"
2514 Write contents of macro or string
2522 Besides these standard groff requests, there might be further macro
2524 They can originate from a macro package (see
2525 .BR roff (@MAN7EXT@)
2526 for an overview) or from a preprocessor.
2529 Preprocessor macros are easy to be recognized.
2531 They enclose their code into a pair of characteristic macros.
2535 box, center, tab (@);
2538 preprocessor@start macro@ end macro
2545 soelim@\f[I]none@\f[I]none
2551 .\" --------------------------------------------------------------------
2552 .SH "ESCAPE SEQUENCES"
2553 .\" --------------------------------------------------------------------
2555 Escape sequences are in-line language elements usually introduced by a
2558 and followed by an escape name and sometimes by a required argument.
2560 Input processing is continued directly after the escaped character or
2561 the argument (without an intervening separation character).
2563 So there must be a way to determine the end of the escape name and the
2564 end of the argument.
2567 This is done by enclosing names (escape name and arguments consisting
2568 of a variable name) by a pair of brackets
2569 .BI \[lB] name \[rB]
2570 and constant arguments (number expressions and characters) by
2571 apostrophes (ASCII 0x27) like
2572 .BI \[cq] constant \[cq] \f[R].
2575 There are abbreviations for short names.
2577 Two-character escape names can be specified by an opening parenthesis
2582 without a closing counterpart.
2584 And all one-character names different from the special characters
2588 can even be specified without a marker, for example
2594 Constant arguments of length\~1 can omit the marker apostrophes, too,
2595 but there is no two-character analogue.
2598 While one-character escape sequences are mainly used for in-line
2599 functions and system related tasks, the two-letter names following the
2601 construct are glyphs predefined by the roff system; these are called
2602 `Special Characters' in the classical documentation.
2604 Escapes sequences of the form
2609 .\" --------------------------------------------------------------------
2610 .SS "Single-Character Escapes"
2611 .\" --------------------------------------------------------------------
2615 .\" --------- comments ---------
2621 Everything up to the end of the line is ignored.
2625 Everything up to and including the next newline is ignored.
2627 This is interpreted in copy mode.
2631 except that the terminating newline is ignored as well.
2633 .\" --------- strings ---------
2637 The string stored in the string variable with one-character name\~\c
2642 The string stored in the string variable with two-character name
2647 The string stored in the string variable with name
2649 (with arbitrary length).
2652 .ESC[] * "stringvar arg1 arg2 .\|.\|."
2653 The string stored in the string variable with arbitrarily long name
2661 .\" --------- macro arguments ---------
2665 The name by which the current macro was invoked.
2669 request can make a macro have more than one name.
2673 Macro or string argument with one-digit number\~\c
2675 in the range 1 to\~9.
2679 Macro or string argument with two-digit number
2685 Macro or string argument with number
2689 is a numerical expression evaluating to an integer \[>=]1.
2693 In a macro or string, the concatenation of all the arguments separated
2698 In a macro or string, the concatenation of all the arguments with each
2699 surrounded by double quotes, and separated by spaces.
2703 In a macro, the representation of all parameters as if they were an
2708 .\" --------- escaped characters ---------
2712 reduces to a single backslash; useful to delay its interpretation as
2713 escape character in copy mode.
2715 For a printable backslash, use
2719 to be independent from the current escape character.
2723 The acute accent \[aa]; same as
2725 Unescaped: apostrophe, right quotation mark, single quote (ASCII 0x27).
2729 The grave accent \[ga]; same as
2731 Unescaped: left quote, backquote (ASCII 0x60).
2735 The \- (minus) sign in the current font.
2741 the underline character.
2745 An uninterpreted dot (period), even at start of line.
2749 Default optional hyphenation character.
2753 Transparent line indicator.
2757 In a diversion, this transparently embeds
2761 is read in copy mode.
2763 See also the escape sequences
2769 .\" --------- spacing ---------
2773 Unpaddable space size space glyph (no line break).
2781 1/6\ em narrow space glyph; zero width in nroff.
2785 1/12\ em half-narrow space glyph; zero width in nroff.
2789 Non-printable, zero-width glyph.
2795 except that it behaves like a glyph declared with the
2797 request to be transparent for the purposes of end-of-sentence
2802 Increases the width of the preceding glyph so that the spacing
2803 between that glyph and the following glyph is correct if
2804 the following glyph is a roman glyph.
2808 Modifies the spacing of the following glyph so that the spacing
2809 between that glyph and the preceding glyph is correct if the
2810 preceding glyph is a roman glyph.
2814 Unbreakable space that stretches like a normal inter-word space when a
2819 Inserts a zero-width break point (similar to
2821 but without a soft hyphen character).
2825 Ignored newline, for continuation lines.
2827 .\" --------- structuring ---------
2831 Begin conditional input.
2835 End conditional input.
2837 .\" --------- longer escape names ---------
2841 A glyph with two-character name
2844 .BR "Special Characters" .
2850 (of arbitrary length).
2853 .ESC[] "" "comp1 comp2 .\|.\|."
2854 A composite glyph with components
2859 .\" --------- alphabetical escapes ---------
2863 Non-interpreted leader character.
2869 is acceptable as a name of a string, macro, diversion, register,
2870 environment or font it expands to\~1, and to\~0 otherwise.
2873 .ESCq b abc.\|.\|.\&
2874 Bracket building function.
2880 is acceptable as a valid numeric expression it expands to\~1, and
2885 Interrupt text processing.
2893 but compatible to other roff versions.
2897 Forward (down) 1/2 em (1/2 line in nroff).
2901 Draw a graphical element defined by the characters in
2903 see the groff info file for details.
2907 Printable version of the current escape character.
2911 Equivalent to an escape character, but is not interpreted in copy mode.
2915 Change to font with one-character name or one-digit number\~\c
2920 Switch back to previous font.
2924 Change to font with two-character name or two-digit number
2929 Change to font with arbitrarily long name or number expression
2934 Switch back to previous font.
2938 Change to font family with one-character name\~\c
2943 Change to font family with two-character name
2948 Change to font family with arbitrarily long name
2953 Switch back to previous font family.
2957 Return format of register with one-character name\~\c
2965 Return format of register with two-character name
2973 Return format of register with arbitrarily long name
2981 Local horizontal motion; move right
2987 Set height of current font to
2992 Mark horizontal input place in one-character register\~\c
2997 Mark horizontal input place in two-character register
3002 Mark horizontal input place in register with arbitrarily long name
3007 Horizontal line drawing function (optionally using character
3012 Vertical line drawing function (optionally using character
3017 Change to color with one-character name\~\c
3022 Change to color with two-character name
3027 Change to color with arbitrarily long name
3032 Switch back to previous color.
3036 Change filling color for closed drawn objects to color with
3037 one-character name\~\c
3042 Change filling color for closed drawn objects to color with
3048 Change filling color for closed drawn objects to color with
3049 arbitrarily long name
3054 Switch to previous fill color.
3058 The numerical value stored in the register variable with the
3059 one-character name\~\c
3064 The numerical value stored in the register variable with the
3070 The numerical value stored in the register variable with arbitrarily
3076 Typeset the glyph with index\~\c
3078 in the current font.
3080 No special fonts are searched.
3082 Useful for adding (named) entities to a document using the
3084 request and friends.
3087 .ESCq o abc.\|.\|.\&
3096 Disable glyph output.
3098 Mainly for internal use.
3102 Enable glyph output.
3104 Mainly for internal use.
3108 Break and spread output line.
3112 Reverse 1\ em vertical motion (reverse line in nroff).
3115 .ESCq R "name\~\[+-]n"
3123 Set/increase/decrease the point size to/by
3127 is a one-digit number in the range 1 to\~9.
3137 Set/increase/decrease the point size to/by
3141 is a two-digit number \[>=]1.
3155 Set/increase/decrease the point size to/by
3171 Non-interpreted horizontal tab.
3175 Reverse (up) 1/2 em vertical motion (1/2 line in nroff).
3179 Local vertical motion; move down
3185 The contents of the environment variable with one-character
3191 The contents of the environment variable with two-character name
3196 The contents of the environment variable with arbitrarily long name
3201 The width of the glyph sequence
3206 Extra line-space function (negative before, positive after).
3212 as device control function.
3216 Output string variable or macro with one-character name\~\c
3218 uninterpreted as device control function.
3222 Output string variable or macro with two-character name
3224 uninterpreted as device control function.
3228 Output string variable or macro with arbitrarily long name
3230 uninterpreted as device control function.
3236 with zero width (without spacing).
3242 and then restore the horizontal and vertical position;
3244 may not contain tabs or leaders.
3248 The escape sequences
3260 are interpreted in copy mode.
3263 Escape sequences starting with
3267 do not represent single character escape sequences, but introduce escape
3268 names with two or more characters.
3271 If a backslash is followed by a character that does not constitute a
3272 defined escape sequence, the backslash is silently ignored and the
3273 character maps to itself.
3276 .\" --------------------------------------------------------------------
3277 .SS "Special Characters"
3278 .\" --------------------------------------------------------------------
3280 [Note: `Special Characters' is a misnomer; those entities are (output)
3281 glyphs, not (input) characters.]
3284 Common special characters are predefined by escape sequences of the
3292 Some of these exist in the usual font while most of them are only
3293 available in the special font.
3295 Below you can find a selection of the most important glyphs; a complete
3296 list can be found in
3297 .BR groff_char (@MAN7EXT@).
3322 Printable double quote
3334 Printable backslash character
3366 .\" --------------------------------------------------------------------
3368 .\" --------------------------------------------------------------------
3370 Strings are defined by the
3372 request and can be retrieved by the
3377 Strings share their name space with macros.
3379 So strings and macros without arguments are roughly equivalent; it is
3380 possible to call a string like a macro and vice-versa, but this often
3381 leads to unpredictable results.
3383 The following string is the only one predefined in groff.
3387 The name of the current output device as specified by the
3389 command line option.
3392 .\" --------------------------------------------------------------------
3394 .\" --------------------------------------------------------------------
3396 Registers are variables that store a value.
3397 In groff, most registers store numerical values (see section
3398 .B NUMERICAL EXPRESSIONS
3399 above), but some can also hold a string value.
3402 Each register is given a name.
3403 Arbitrary registers can be defined and set with the
3408 The value stored in a register can be retrieved by the escape sequences
3413 Most useful are predefined registers.
3415 In the following the notation
3419 to make clear that we speak about registers.
3421 Please keep in mind that the
3423 decoration is not part of the register name.
3426 .\" --------------------------------------------------------------------
3427 .SS "Read-only Registers"
3428 .\" --------------------------------------------------------------------
3430 The following registers have predefined values that should not be
3431 modified by the user (usually, registers starting with a dot a
3434 Mostly, they provide information on the current settings or store
3435 results from request calls.
3442 Number of arguments in the current macro or string.
3446 Post-line extra line-space most recently utilized using
3455 is used; always\~1 in
3460 Within a macro, set to\~1 if macro called with the `normal' control
3461 character, and to\~0 otherwise.
3465 Current input line number.
3469 1\~if compatibility mode is in effect, 0\~otherwise.
3473 The depth of the last glyph added to the current environment.
3475 It is positive if the glyph extends below the baseline.
3479 The number of lines remaining to be centered, as set by the
3485 The height of the last glyph added to the current environment.
3487 It is positive if the glyph extends above the baseline.
3491 1\~if colors are enabled, 0\~otherwise.
3495 The skew of the last glyph added to the current environment.
3497 The skew of a glyph is how far to the right of the center of a glyph
3498 the center of an accent over that glyph should be placed.
3502 Current vertical place in current diversion; equal to
3507 The name or number of the current environment (string-valued).
3511 Current font number.
3515 The current font family (string-valued).
3519 The current (internal) real font name (string-valued).
3523 The number of the next free font position.
3527 Always 1 in GNU troff.
3529 Macros should use it to test if running under groff.
3533 Text base-line high-water mark on current page or diversion.
3537 Available horizontal resolution in basic units.
3541 The current font height as set with
3546 The current hyphenation language as set by the
3552 The number of immediately preceding consecutive hyphenated lines.
3556 The maximum allowed number of consecutive hyphenated lines, as set by
3563 The current hyphenation flags (as set by the
3569 The current hyphenation margin (as set by the
3575 The current hyphenation space (as set by the
3581 Current indentation.
3585 The indentation that applies to the current output line.
3589 Positive if last output line contains
3594 1\~if pairwise kerning is enabled, 0\~otherwise.
3598 Current line length.
3602 The current ligature mode (as set by the
3608 The current line-tabs mode (as set by the
3614 The line length that applies to the current output line.
3618 The title length (as set by the
3624 The current drawing color (string-valued).
3628 The current background color (string-valued).
3632 Length of text portion on previous output line.
3636 The amount of space that was needed in the last
3638 request that caused a trap to be sprung.
3640 Useful in conjunction with
3645 1\~if in no-space mode, 0\~otherwise.
3649 Current page offset.
3653 Current page length.
3657 1\~during page ejection, 0\~otherwise.
3661 The number of the next page: either the value set by a
3663 request, or the number of the current page plus\ 1.
3667 The current point size in scaled points.
3671 The last-requested point size in scaled points.
3675 The current post-vertical line spacing.
3679 The number of lines to be right-justified as set by the
3685 Current point size as a decimal fraction.
3689 The slant of the current font as set with
3694 The last requested point size in points as a decimal fraction
3699 The value of the parameters set by the first argument of the
3705 The value of the parameters set by the second argument of the
3711 The current font style (string-valued).
3715 Vertical distance to the next trap.
3726 A string representation of the current tab settings suitable for use
3727 as an argument to the
3733 The amount of vertical space truncated by the most recently sprung
3734 vertical position trap, or, if the trap was sprung by a
3736 request, minus the amount of vertical motion produced by
3739 Useful in conjunction with the
3744 Equal to 1 in fill mode and 0 in no-fill mode.
3748 Equal to 1 in safer mode and 0 in unsafe mode.
3752 Current vertical line spacing.
3756 Available vertical resolution in basic units.
3760 1\~if vertical position traps are enabled, 0\~otherwise.
3764 Width of previous glyph.
3768 The sum of the number codes of the currently enabled warnings.
3772 The major version number.
3776 The minor version number.
3780 The revision number of groff.
3784 Name of current diversion.
3788 Zoom factor for current font (in multiples of 1/1000th; zero if no
3793 .\" --------------------------------------------------------------------
3794 .SS "Writable Registers"
3795 .\" --------------------------------------------------------------------
3797 The following registers can be read and written by the user.
3798 They have predefined default values, but these can be modified for
3799 customizing a document.
3805 Current page number.
3809 Current input line number.
3813 Character type (set by width function
3818 Maximal width of last completed diversion.
3822 Height of last completed diversion.
3826 Current day of week (1-7).
3830 Current day of month (1-31).
3834 The number of hours past midnight.
3836 Initialized at start-up.
3840 Current horizontal position at input line.
3844 Lower left x-coordinate (in PostScript units) of a given PostScript
3850 Lower left y-coordinate (in PostScript units) of a given PostScript
3860 The number of minutes after the hour.
3862 Initialized at start-up.
3866 Current month (1-12).
3870 Vertical position of last printed text base-line.
3876 but takes account of the heights and depths of glyphs.
3882 but takes account of the heights and depths of glyphs.
3886 Depth of string below base line (generated by width function
3891 The number of seconds after the minute.
3893 Initialized at start-up.
3897 Right skip width from the center of the last glyph in the
3903 If greater than 0, the maximum number of objects on the input stack.
3905 If \[<=]0 there is no limit, i.e., recursion can continue until virtual
3906 memory is exhausted.
3910 The amount of horizontal space (possibly negative) that should be
3911 added to the last glyph before a subscript (generated by width
3917 Height of string above base line (generated by width function
3922 The return value of the
3924 function executed by the last
3930 Upper right x-coordinate (in PostScript units) of a given PostScript
3936 Upper right y-coordinate (in PostScript units) of a given PostScript
3942 The current year (year 2000 compliant).
3946 Current year minus 1900.
3948 For Y2K compliance use
3955 .\" --------------------------------------------------------------------
3957 .\" --------------------------------------------------------------------
3959 The differences of the groff language in comparison to classical troff
3963 .BR groff_diff (@MAN7EXT@).
3966 The groff system provides a compatibility mode, see
3967 .BR groff (@MAN1EXT@)
3968 on how to invoke this.
3971 .\" --------------------------------------------------------------------
3973 .\" --------------------------------------------------------------------
3976 .MT bug-groff@gnu.org
3977 groff bug mailing list
3979 Include a complete, self-contained example that will allow the bug to
3980 be reproduced, and say which version of groff you are using.
3983 .\" --------------------------------------------------------------------
3985 .\" --------------------------------------------------------------------
3987 Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
3988 Free Software Foundation, Inc.
3991 This document is distributed under the terms of the FDL (GNU Free
3992 Documentation License) version 1.1 or later.
3994 You should have received a copy of the FDL on your system, it is also
3995 available on-line at the
3996 .UR http://\:www.gnu.org/\:copyleft/\:fdl.html
4001 This document is part of
4003 the GNU roff distribution.
4015 .\" --------------------------------------------------------------------
4017 .\" --------------------------------------------------------------------
4020 The main source of information for the groff language is the
4025 Besides the gory details, it contains many examples.
4028 .BR groff (@MAN1EXT@)
4029 the usage of the groff program and pointers to the documentation and
4030 availability of the groff system.
4033 .BR groff_diff (@MAN7EXT@)
4034 the differences of the groff language as compared to classical roff.
4036 This is the authoritative document for the predefined language
4037 elements that are specific to groff.
4040 .BR groff_char (@MAN7EXT@)
4041 the predefined groff special characters (glyphs).
4044 .BR groff_font (@MAN5EXT@)
4045 the specification of fonts and the DESC file.
4048 .BR roff (@MAN7EXT@)
4049 the history of roff, the common parts shared by all roff systems, and
4050 pointers to further documentation.
4054 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:54.ps.gz
4055 Nroff/\:Troff User's Manual by Ossanna & Kernighan
4057 \[em] the bible for classical troff.
4061 .\" --------------------------------------------------------------------
4063 .\" --------------------------------------------------------------------
4065 .\" Local Variables: