4 Copyright (c) 2014 - 2017 Steffen (Daode) Nurpmeso <steffen@sdaoden.eu>.
6 Copyright (C) 2000 - 2008
7 Free Software Foundation, Inc.
8 written by Bernd Warken <bwarken@mayn.de>
10 Permission is granted to copy, distribute and/or modify this document
11 under the terms of the GNU Free Documentation License, Version 1.1 or
12 any later version published by the Free Software Foundation; with the
13 Invariant Sections being this .ig-section and AUTHORS, with no
14 Front-Cover Texts, and with no Back-Cover Texts.
16 You should have received a copy of the Free Documentation License
17 as part of the file COPYING; also located in the main directory of the
18 source package of this program.
29 .\" start of macro definitions
35 .\" .Text anything ...
37 .\" All arguments are printed as text.
43 .\" --------- command line option ---------
50 .\" --------- characters ---------
53 . Text \[oq]\f[CB]\\$1\f[]\[cq]\\$2
56 . Text \[lq]\f[CB]\\$1\f[]\[rq]\\$2
58 .\" --------- requests ---------
60 .\" synopsis of a request
66 . Text \f[CB]\\$1\~\f[]\f[I]\\$2\f[]
70 .\" reference of a request
75 .\" --------- numerical elements ---------
77 .\" number with a trailing unit
79 . Text \\$1\^\f[CB]\\$2\f[]\\$3\f[R]
83 .\" representation of units within the text
85 . Text \f[CB]\\$1\f[]\\$2\f[R]
89 .\" representation of mathematical operators within the text
95 .\" --------- escape sequences ---------
100 .\" Synopsis of an escape sequence, optionally with argument
101 .\" Args : 1 or 2; `name' obligatory, `arg' optional
102 .\" name : suitable name for an escape sequence (c, (xy, [long])
103 .\" arg : arbitrary word
104 .\" Result : prints \namearg, where `name' is in CB, `arg' in I
107 . Text "\f[CB]\[rs]\\$1\,\f[I]\\$2\/\fR"
112 .\" Synopsis for escape sequence with a bracketed long argument
113 .\" Args : 2 obligatory
114 .\" name : suitable name for an escape sequence (c, (xy, [long])
115 .\" arg : arbitrary text
116 .\" Result : prints \name[arg], where `name' is in CB, `arg' in I
119 . Text "\f[CB]\[rs]\\$1\[lB]\f[]\f[I]\\$2\f[]\f[CB]\[rB]\f[]"
124 .\" Synopsis for escape sequence with a bracketed long argument
125 .\" Args : 2 obligatory
126 .\" name : suitable name for an escape sequence (c, (xy, [long])
127 .\" arg : arbitrary text
128 .\" Result : prints \name'arg', where `name' is in CB, `arg' in I
131 . Text "\f[CB]\[rs]\\$1\[cq]\f[]\f[I]\\$2\f[]\f[CB]\[cq]\f[]"
136 .\" Synopsis for escape sequence with a bracketed long argument
137 .\" Args : 1 obligatory
138 .\" arg : arbitrary text
139 .\" Result : prints `\?arg?', where the `?' are in CB, `arg' in I
142 . Text "\f[CB]\[rs]?\f[I]\\$1\f[CB]?\f[R]"
145 .\" .esc name [punct]
147 .\" Reference of an escape sequence (no args), possibly punctuation
148 .\" Args : 1 obligatory
149 .\" name : suitable name for an escape sequence (c, (xy, [long])
150 .\" punct : arbitrary
151 .\" Result : prints \name, where `name' is in B, `punct' in R
154 . BR "\[rs]\\$1" \\$2
157 .\" .escarg name arg [punct]
159 .\" Reference of an escape sequence (no args)
160 .\" Args : 1 obligatory, 1 optional
161 .\" name : suitable name for an escape sequence (c, (xy, [long])
162 .\" arg : arbitrary word
163 .\" Result : prints \namearg, where
164 .\" `name' is in B, `arg' in I
167 . Text \f[B]\[rs]\\$1\f[]\f[I]\\$2\f[]\\$3
170 .\" .esc[] name arg [punct]
172 .\" Reference for escape sequence with a bracketed long argument
173 .\" Args : 2 obligatory
174 .\" name : suitable name for an escape sequence (c, (xy, [long])
175 .\" arg : arbitrary text
176 .\" Result : prints \name[arg], where `name' is in CB, `arg' in CI
179 . Text \f[B]\[rs]\\$1\[lB]\f[]\f[I]\\$2\f[]\f[B]\[rB]\f[]\\$3
185 .\" Reference for escape sequence with a bracketed long argument
186 .\" Args : 2 obligatory
187 .\" name : suitable name for an escape sequence (c, (xy, [long])
188 .\" arg : arbitrary text
189 .\" Result : prints \name'arg', where `name' is in CB, `arg' in CI
192 . Text \f[B]\[rs]\\$1\[cq]\f[]\f[I]\\$2\f[]\f[B]\[cq]\f[]\\$3
195 .\" --------- strings ---------
197 .\" synopsis for string, with \*[]
199 . Text \[rs]*[\f[CB]\\$1\f[]] \\$2
201 .\" synopsis for a long string
205 . Text \f[CB]\[rs]*\[lB]\\$1\[rB]\f[]\\$2
208 .\" --------- registers ---------
210 .\" synopsis for registers, with \n[]
212 . Text \[rs]n[\f[CB]\\$1\f[]]
214 .\" reference of a register, without decoration
220 .\" end of macro definitions
227 .TH @U_ROFF@ @MAN7EXT@ "@MDATE@" "@T_ROFF@ v@VERSION@"
229 @L_ROFF@ \- a short reference for the roff language
237 is a free implementation of the roff type-setting system.
240 .BR @L_ROFF@-history (@MAN7EXT@)
241 for a survey and the background of the @T_ROFF@ system.
244 This document gives only short descriptions of the predefined roff
245 language elements as used in @L_ROFF@.
247 Classical features, GNU troff and @T_ROFF@ extensions are provided.
255 is compatible with the classical system and provides proper
263 language could be used as synonyms.
267 slightly tends to refer more to the classical aspects, whereas
269 emphasizes the extensions, and
271 is the general term for the language.
274 The general syntax for writing roff documents is relatively easy, but
275 writing extensions to the roff language can be a bit harder.
278 The roff language is line-oriented.
280 There are only two kinds of lines, control lines and text lines.
282 The control lines start with a control character, by default a period
286 all other lines are text lines.
290 represent commands, optionally with arguments.
292 They have the following syntax.
294 The leading control character can be followed by a command name;
295 arguments, if any, are separated by spaces (but not tab characters)
296 from the command name and among themselves, for example,
300 .Text .command_name arg1 arg2
304 For indentation, any number of space or tab characters can be inserted
305 between the leading control character and the command name, but the
306 control character must be on the first position of the line.
310 represent the parts that is printed.
311 They can be modified by escape sequences, which are recognized by a
313 .squoted_char \[rs] .
314 These are in-line or even in-word formatting elements or functions.
316 Some of these take arguments separated by single quotes
318 others are regulated by a length encoding introduced by an open
321 or enclosed in brackets
327 The roff language provides flexible instruments for writing language
328 extension, such as macros.
330 When interpreting macro definitions, the roff system enters a special
331 operating mode, called the
335 The copy mode behavior can be quite tricky, but there are some rules
336 that ensure a safe usage.
339 Printable backslashes must be denoted as
343 represents the current escape character.
345 To get a backslash glyph, use
350 Double all backslashes.
352 Begin all text lines with the special non-spacing character
356 This does not produce the most efficient code, but it should work as a
359 Predefined macro packages may give a better user experience: see
360 .BR @L_ROFF@-tmac (@MAN5EXT@).
363 Reading roff source files is easier, just reduce all double backslashes
364 to a single one in all macro definitions.
371 The roff language elements add formatting information to a text file.
373 The fundamental elements are predefined commands and variables that
374 make roff a full-blown programming language.
377 There are two kinds of roff commands, possibly with arguments.
379 are written on a line of their own starting with a dot
385 are in-line functions and in-word formatting elements starting with a
387 .squoted_char \[rs] .
390 The user can define her own formatting commands using the
394 These commands are called
396 but they are used exactly like requests.
398 Macro packages are pre-defined sets of macros written in the roff
401 A user's possibilities to create escape sequences herself is very
402 limited, only special characters can be mapped.
405 The roff language provides several kinds of variables with
406 different interfaces.
408 There are pre-defined variables, but the user can define her own
413 variables store character sequences.
415 They are set with the
417 request and retrieved by the
421 Strings can have variables.
425 variables can store numerical values, numbers with a scale unit, and
426 occasionally string-like objects.
428 They are set with the
430 request and retrieved by the
436 allow the user to temporarily store global formatting parameters like
437 line length, font size, etc.\& for later reuse.
445 are identified either by a name or by an internal number.
447 The current font is chosen by the
453 Each device has special fonts, but the following fonts are available
456 is the standard font Roman.
466 and is available everywhere, but on text devices it is displayed as an
467 underlined Roman font.
469 For the graphical output devices, there exist constant-width pendants
475 On text devices, all glyphs have a constant width anyway.
479 are visual representation forms of
481 In roff, the distinction between those two elements is not always
482 obvious (and a full discussion is beyond the scope of this man page).
484 A first approximation is that glyphs have a specific size and
485 colour and are taken from a specific font; they can't be modified any
486 more \[en] characters are the input, and glyphs are the output.
488 As soon as an output line has been generated, it no longer contains
489 characters but glyphs.
491 In this man page, we use either `glyph' or `character', whatever is
495 Moreover, there are some advanced roff elements.
499 stores (formatted) information into a macro for later usage.
503 is a positional condition like a certain number of lines from page top
504 or in a diversion or in the input.
506 Some action can be prescribed to be run automatically when the
510 .SH "CONTROL CHARACTERS"
513 There is a small set of characters that have a special controlling
514 task in certain conditions.
518 A dot is only special at the beginning of a line or after the
519 condition in the requests
525 There it is the control character that introduces a request (or macro).
527 The special behavior can be delayed by using the
533 request, the control character can be set to a different character,
536 a non-special character.
538 In all other positions, it just means a dot character.
540 In text paragraphs, it is advantageous to start each sentence at a
545 The single quote has two controlling tasks.
547 At the beginning of a line and in the conditional requests it is the
548 non-breaking control character.
550 That means that it introduces a request like the dot, but with the
551 additional property that this request doesn't cause a linebreak.
555 request, the non-break control character can be set to a different
559 As a second task, it is the most commonly used argument separator in
560 some functional escape sequences (but any pair of characters not part
561 of the argument do work).
563 In all other positions, it denotes the single quote or apostrophe
566 Roff provides a printable representation with the
572 The double quote is used to enclose arguments in macros (but not in
573 requests and strings).
579 requests, a leading double quote in the argument is stripped off,
580 making everything else afterwards the string to be defined (enabling
583 The escaped double quote
585 introduces a comment.
587 Otherwise, it is not special.
589 Roff provides a printable representation with the
595 The backslash usually introduces an escape sequence (this can be
600 A printed version of the escape character is the
602 escape; a backslash glyph can be obtained by
606 The open parenthesis is only special in escape sequences when
607 introducing an escape name or argument consisting of exactly two
610 In @T_ROFF@, this behavior can be replaced by the \f[CB][]\f[] construct.
613 The opening bracket is only special in roff escape sequences; there
614 it is used to introduce a long escape name or long escape argument.
616 Otherwise, it is non-special, e.g.\& in macro calls.
619 The closing bracket is only special in roff escape sequences; there
620 it terminates a long escape name or long escape argument.
622 Otherwise, it is non-special.
625 Space characters are only functional characters.
627 They separate the arguments in requests, macros, and strings, and the words
630 They are subject to roff's horizontal spacing calculations.
632 To get a defined space width, escape sequences like
633 .squoted_char "\[rs]\ "
634 (this is the escape character followed by a space),
641 .IP \f[CI]newline\f[]
642 In text paragraphs, newlines mostly behave like space characters.
644 Continuation lines can be specified by an escaped newline, i.e., by
645 specifying a backslash
647 as the last character of a line.
649 If a tab character occurs during text the interpreter makes a
650 horizontal jump to the next pre-defined tab position.
652 There is a sophisticated interface for handling tab positions.
656 .SH "NUMERICAL EXPRESSIONS"
661 is a signed or unsigned integer or float with or without an appended
666 is a one-character abbreviation for a unit of measurement.
668 A number followed by a scaling indicator signifies a size value.
670 By default, numerical values do not have a scaling indicator, i.e., they
676 language defines the following scaling indicators.
693 Pica\ \[eq]\ 1/6\ inch
697 Point\ \[eq]\ 1/72\ inch
701 Em\ \[eq]\ \f[R]the font size in points (approx.\& width of letter
706 100\^th \f[R]of an \f[CR]Em
714 Basic unit for actual output device
718 Vertical line space in basic units
719 scaled point\ \[eq]\ 1/\f[CI]sizescale\f[R] of a point (defined in
720 font \f[I]DESC\f[] file)
729 .B Numerical expressions
730 are combinations of the numerical values defined above with the
731 following arithmetical operators already defined in classical troff.
795 Grouping of expressions
799 Close current grouping
807 adds the following operators for numerical expressions:
814 \f[I]e1\f[CB]>?\f[I]e2\f[R]
821 \f[I]e1\f[CB]<?\f[I]e2\f[R]
828 \f[CB](\f[I]c\f[CB];\f[I]e\f[CB])\f[R]
833 as the default scaling indicator.
843 occur in tests raised by the
850 The following table characterizes the different types of conditions.
858 A numerical expression
860 yields true if its value is greater than\~0.
872 is identical to string\~\c
879 is not identical to string\~\c
884 True if there is a glyph\~\c
890 True if there is a string, macro, diversion, or request called
895 Current page number is even.
899 Current page number is odd.
903 True if there is a color called
913 True if there is a register named
923 True if there exists a font named
928 True if a style named
940 This section provides a short reference for the predefined requests.
942 In @T_ROFF@, request, macro, and string names can be arbitrarily long.
944 No bracketing or marking of long names is needed.
947 Most requests take one or more arguments.
949 The arguments are separated by space characters (no tabs!); there is
950 no inherent limit for their length or number.
953 Some requests have optional arguments with a different behaviour.
955 Not all of these details are outlined here.
958 .BR @L_ROFF@-diff (@MAN7EXT@)
962 In the following request specifications, most argument names were
963 chosen to be descriptive.
965 Only the following denotations need clarification.
973 denotes a single character.
977 a font either specified as a font name or a font number.
981 all characters up to the end of the line or within
988 is a numerical expression that evaluates to an integer value.
992 is an arbitrary numerical expression, signed or unsigned.
996 has three meanings depending on its sign, described below.
1002 If an expression defined as
1006 sign the resulting value of the expression is added to an already
1007 existing value inherent to the related request, e.g.\& adding to a number
1010 If the expression starts with a
1012 the value of the expression is subtracted from the request value.
1017 replaces the existing value directly.
1019 To assign a negative number either prepend\~0 or enclose the negative
1020 number in parentheses.
1024 .SS "Request Short Reference"
1031 Empty line, ignored.
1033 Useful for structuring documents.
1036 .REQ .\[rs]\[dq] "anything"
1037 Complete line is a comment.
1043 on standard error, exit program.
1047 Begin line adjustment for output lines in current adjust mode.
1051 Start line adjustment in mode
1053 (\f[CI]c\f[]\f[CR]\|\^\[eq]\|l,r,b,n\f[]).
1056 .REQ .af "register c"
1061 (\f[CI]c\f[]\f[CR]\|\^\[eq]\|l,i,I,a,A\f[]).
1064 .REQ .aln "alias register"
1065 Create alias name for
1069 .REQ .als "alias object"
1070 Create alias name for request, string, macro, or diversion
1082 .REQ .am "macro end"
1093 but with compatibility mode switched off during macro expansion.
1096 .REQ .am1 "macro end"
1099 but with compatibility mode switched off during macro expansion.
1103 Append to a macro whose name is contained in the string register
1110 .REQ .ami "macro end"
1111 Append to a macro indirectly.
1115 are string registers whose contents are interpolated for the macro name
1116 and the end macro, respectively.
1122 but with compatibility mode switched off during macro expansion.
1125 .REQ .ami1 "macro end"
1128 but with compatibility mode switched off during macro expansion.
1131 .REQ .as "stringvar anything"
1138 .REQ .as1 "stringvar anything"
1141 but with compatibility mode switched off during string expansion.
1144 .REQ .asciify "diversion"
1145 Unformat ASCII characters, spaces, and some escape sequences in
1150 Print a backtrace of the input on stderr.
1162 Embolden Special Font
1164 when current font is
1169 Unset the blank line macro.
1173 Set the blank line macro to
1178 End current diversion.
1184 omitting a partially filled line.
1188 End current diversion.
1192 Divert and append to
1194 omitting a partially filled line.
1198 Eject current page and begin new page.
1202 Eject current page; next page number
1211 Break and spread output line.
1217 Break out of a while loop.
1221 Reset no-break control character to
1226 Set no-break control character to
1231 Reset control character to
1236 Set control character to
1241 Center the next input line.
1251 Copy contents of file
1253 unprocessed to stdout or to the diversion.
1256 .REQ .cflags "mode c1 c2 .\|.\|.\&"
1274 .REQ .char "c anything"
1282 Chop the last character off macro, string, or diversion
1286 .REQ .close "stream"
1298 is zero disable colors, otherwise enable them.
1301 .REQ .composite "from to"
1306 while constructing a composite glyph name.
1310 Finish the current iteration of a while loop.
1314 Enable compatibility mode.
1320 is zero disable compatibility mode, otherwise enable it.
1324 Set constant character width mode for
1333 Continuous underline in nroff, like
1339 End current diversion.
1343 Divert and append to
1355 .REQ .de "macro end"
1366 but with compatibility mode switched off during macro expansion.
1369 .REQ .de1 "macro end"
1372 but with compatibility mode switched off during macro expansion.
1375 .REQ .defcolor "color scheme component"
1376 Define or redefine a color with name
1387 can be single components specified as fractions in the range 0 to 1
1388 (default scaling indicator\~\c
1389 .scaleindicator f ),
1390 as a string of two-digit hexadecimal color components with a leading
1392 or as a string of four-digit hexadecimal components with two leading
1400 Define or redefine a macro whose name is contained in the string register
1407 .REQ .dei "macro end"
1408 Define or redefine a macro indirectly.
1412 are string registers whose contents are interpolated for the macro name
1413 and the end macro, respectively.
1419 but with compatibility mode switched off during macro expansion.
1422 .REQ .dei1 "macro end"
1425 but with compatibility mode switched off during macro expansion.
1428 .REQ .device "anything"
1431 to the intermediate output as a device control function.
1434 .REQ .devicem "name"
1435 Write contents of macro or string
1437 uninterpreted to the intermediate output as a device control function.
1441 End current diversion.
1452 with compatibility mode disabled.
1455 .REQ .ds "stringvar anything"
1462 .REQ .ds1 "stringvar anything"
1465 but with compatibility mode switched off during string expansion.
1469 Set diversion trap to position
1471 (default scaling indicator\~\c
1472 .scaleindicator v ).
1476 Reset escape character to
1477 .squoted_char \[rs] .
1481 Set escape character to
1486 Restore escape character saved with
1491 Save current escape character.
1495 Else part for if-else (\c
1503 is run after the end of input.
1507 Turn off escape character mechanism.
1511 Switch to previous environment and pop it off the stack.
1515 Push down environment number or name
1517 to the stack and switch to it.
1521 Copy the contents of environment
1523 to the current environment.
1524 No pushing or popping.
1528 Exit from roff processing.
1532 Return to previous font family.
1536 Set the current font family to
1541 Disable field mechanism.
1545 Set field delimiter to\~\c
1547 and pad glyph to space.
1551 Set field delimiter to\~\c
1553 and pad glyph to\~\c
1557 .REQ .fchar "c anything"
1558 Define fallback character (or glyph)
1565 Set fill color to previous fill color.
1578 Flush output buffer.
1588 .REQ .fp "n internal external"
1589 Mount font with long
1597 .REQ .fschar "f c anything"
1598 Define fallback character (or glyph)
1606 .REQ .fspecial "font"
1607 Reset list of special fonts for
1612 .REQ .fspecial "font s1 s2 .\|.\|.\&"
1613 When the current font is
1623 Return to previous font.
1631 Change to font name or number
1638 .REQ .ftr "font1 font2"
1650 .REQ .fzoom "font zoom"
1653 (in multiples of 1/1000th).
1657 Set glyph color to previous glyph color.
1666 Remove additional hyphenation indicator character.
1670 Set up additional hyphenation indicator character\~\c
1674 .REQ .hcode "c1 code1 c2 code2 .\|.\|.\&"
1675 Set the hyphenation code of character
1687 Set the current hyphenation language to
1692 Set the maximum number of consecutive hyphenated lines to
1697 Read hyphenation patterns from
1702 Append hyphenation patterns from
1706 .REQ .hpfcode "a b c d .\|.\|.\&"
1707 Set input mapping for
1714 with exceptional hyphenation.
1718 Switch to hyphenation mode
1723 Set the hyphenation margin to
1725 (default scaling indicator\~\c
1726 .scaleindicator m ).
1730 Set the hyphenation space to
1734 .REQ .ie "cond anything"
1743 .REQ .if "cond anything"
1748 otherwise do nothing.
1764 Change to previous indentation value.
1768 Change indentation according to
1770 (default scaling indicator\~\c
1771 .scaleindicator m ).
1775 Set an input-line count trap for the next
1783 but count lines interrupted with
1789 Enable pairwise kerning.
1795 is zero, disable pairwise kerning, otherwise enable it.
1799 Remove leader repetition glyph.
1803 Set leader repetition glyph to\~\c
1807 .REQ .length "register anything"
1808 Write the length of the string
1815 Enable line-tabs mode (i.e., calculate tab positions relative to output
1822 is zero, disable line-tabs mode, otherwise enable it.
1826 Set input line number to
1831 Set input line number to
1843 Change to previous line length.
1847 Set line length according to
1850 .scalednumber 6.5 i ,
1851 default scaling indicator\~\c
1852 .scaleindicator m ).
1856 Change to the previous value of additional intra-line skip.
1860 Set additional intra-line skip value to
1864 blank lines are inserted after each text output line.
1868 Length of title (default scaling indicator\~\c
1869 .scaleindicator m ).
1879 after each text line at actual distance from right margin.
1883 Set margin glyph to\~\c
1887 from right margin (default scaling indicator\~\c
1888 .scaleindicator m ).
1892 Mark current vertical position in
1901 is searched in the tmac directories.
1905 No output-line adjusting.
1909 Need a one-line vertical space.
1915 vertical space (default scaling indicator\~\c
1916 .scaleindicator v ).
1920 No filling or adjusting of output-lines.
1931 .REQ .nm "\[+-]N \fR[\fPM \fR[\fPS \fR[\fPI\fR]]]\fP"
1932 In line number mode, set number, multiple, spacing, and indentation.
1936 Do not number next line.
1945 .REQ .nop "anything"
1950 .REQ .nr "register \[+-]N \fR[\fPM\fR]\fP"
1960 Make the built-in conditions
1968 Turn on no-space mode.
1972 Immediately jump to end of current file.
1976 Immediately continue processing with file
1980 .REQ .open "stream filename"
1983 for writing and associate the stream named
1988 .REQ .opena "stream filename"
1995 Output vertical distance that was saved by the
2000 .REQ .output "string"
2003 directly to intermediate output, allowing leading whitespace if
2007 (which is stripped off).
2011 Reset page number character to\~\c
2016 Page number character.
2020 Print the current environment and each defined environment
2031 Set page length to default
2032 .scalednumber 11 i .
2033 The current page length is stored in
2038 Change page length to
2040 (default scaling indicator\~\c
2041 .scaleindicator v ).
2045 Print macro names and sizes (number of blocks of 128 bytes).
2049 Print only total of sizes of macros (number of 128 bytes blocks).
2058 Print the names and contents of all currently defined number registers
2063 Change to previous page offset.
2065 The current page offset is available in
2075 Return to previous point size.
2082 .REQ .psbb "filename"
2083 Get the bounding box of a PostScript image
2088 This behaves like the
2090 request except that input comes from the standard output of
2095 Print the names and positions of all traps (not including input line
2096 traps and diversion traps) on stderr.
2100 Change to previous post-vertical line spacing.
2104 Change post-vertical line spacing according to
2106 (default scaling indicator\~\c
2107 .scaleindicator p ).
2110 .REQ .rchar "c1 c2 .\|.\|.\&"
2111 Remove the definitions of entities
2122 Return from a macro.
2125 .REQ .return "anything"
2126 Return twice, namely from the macro at the current level and from the macro
2130 .REQ .rfschar "f c1 c2 .\|.\|.\&"
2131 Remove the definitions of entities
2140 Right justify the next
2146 Remove request, macro, or string
2151 Rename request, macro, or string
2157 .REQ .rnn "reg1 reg2"
2170 Restore spacing; turn no-space mode off.
2176 to marked vertical place (default scaling indicator\~\c
2177 .scaleindicator v ).
2180 .REQ .schar "c anything"
2181 Define global fallback character (or glyph)\~\c
2188 Reset soft hyphen glyph to
2193 Set the soft hyphen glyph to\~\c
2198 In a macro, shift the arguments by
2203 .REQ .sizes "s1 s2 .\|.\|.\& sn \fB[0]\fP"
2204 Set available font sizes similar to the
2212 Include source file.
2216 Skip one line vertically.
2220 Space vertical distance
2222 up or down according to sign of
2224 (default scaling indicator\~\c
2225 .scaleindicator v ).
2229 Reset global list of special fonts to be empty.
2232 .REQ .special "s1 s2 .\|.\|.\&"
2236 etc.\& are special and are searched for glyphs not in the
2241 Toggle the spread warning on and off without changing its value.
2244 .REQ .spreadwarn "limit"
2245 Emit a warning if each space in an output line is widened by
2247 or more (default scaling indicator\~\c
2248 .scaleindicator m ).
2252 Set space glyph size to
2254 of the space width in the current font.
2258 Set space glyph size to
2260 and sentence space size set to
2262 of the space width in the current font.
2272 .REQ .substring "xx n1 n2"
2273 Replace the string named
2275 with the substring defined by the indices
2287 Save the vertical distance
2289 for later output with
2291 request (default scaling indicator\~\c
2292 .scaleindicator v ).
2295 .REQ .sy "command-line"
2301 Set tabs after every position that is a multiple of
2303 (default scaling indicator\~\c
2304 .scaleindicator m ).
2306 .REQ .ta "n1 n2 .\|.\|.\& nn \f[CB]T\f[] r1 r2 .\|.\|.\& rn"
2307 Set tabs at positions
2326 .\"Restore internally saved tab positions.
2330 .\"Save tab positions internally.
2334 Remove tab repetition glyph.
2337 Set tab repetition glyph to\~\c
2342 Temporary indent next line (default scaling indicator\~\c
2343 .scaleindicator m ).
2346 .REQ .tkf "font s1 n1 s2 n2"
2347 Enable track kerning for
2351 .REQ .tl "\f[CB]\[cq]\f[]left\f[CB]\[cq]\f[]center\f[CB]\[cq]\f[]right\f[CB]\[cq]\f[]"
2358 on standard error output.
2361 .REQ .tm1 "anything"
2364 on standard error output, allowing leading whitespace if
2368 (which is stripped off).
2371 .REQ .tmc "anything"
2374 without emitting a final newline.
2377 .REQ .tr "abcd.\|.\|.\&"
2388 .REQ .trf "filename"
2389 Transparently output the contents of file
2393 .REQ .trin "abcd.\|.\|.\&"
2394 This is the same as the
2396 request except that the
2398 request uses the character code (if any) before the character
2402 .REQ .trnt "abcd.\|.\|.\&"
2403 This is the same as the
2405 request except that the translations do not apply to text that is
2406 transparently throughput into a diversion with
2411 Make the built-in conditions
2419 Set underline font to
2421 (to be switched to by
2426 Underline (italicize in troff)
2431 .REQ .unformat "diversion"
2432 Unformat space characters and tabs in
2434 preserving font information.
2437 Enable vertical position traps if
2439 is non-zero, disable them otherwise.
2443 Change to previous vertical base line spacing.
2447 Set vertical base line spacing to
2449 (default scaling indicator\~\c
2450 .scaleindicator p ).
2454 Set warnings code to
2458 .REQ .warnscale "si"
2459 Set scaling indicator used in warnings to
2464 Remove (first) trap at position
2469 Set location trap; negative means from page bottom.
2472 .REQ .while "cond anything"
2480 .REQ .write "stream anything"
2487 .REQ .writec "stream anything"
2490 without emitting a final newline.
2493 .REQ .writem "stream xx"
2494 Write contents of macro or string
2502 Besides these standard roff requests, there might be further macro
2504 They can originate from a macro package (see
2505 .BR @L_ROFF@-history (@MAN7EXT@)
2506 for an overview) or from a preprocessor.
2509 Preprocessor macros are easy to be recognized.
2511 They enclose their code into a pair of characteristic macros.
2515 box, center, tab (@);
2518 preprocessor@start macro@ end macro
2525 soelim@\f[I]none@\f[I]none
2532 .SH "ESCAPE SEQUENCES"
2535 Escape sequences are in-line language elements usually introduced by a
2538 and followed by an escape name and sometimes by a required argument.
2540 Input processing is continued directly after the escaped character or
2541 the argument (without an intervening separation character).
2543 So there must be a way to determine the end of the escape name and the
2544 end of the argument.
2547 This is done by enclosing names (escape name and arguments consisting
2548 of a variable name) by a pair of brackets
2549 .BI \[lB] name \[rB]
2550 and constant arguments (number expressions and characters) by
2551 apostrophes (ASCII 0x27) like
2552 .BI \[cq] constant \[cq] \f[R].
2555 There are abbreviations for short names.
2557 Two-character escape names can be specified by an opening parenthesis
2562 without a closing counterpart.
2564 And all one-character names different from the special characters
2568 can even be specified without a marker, for example
2574 Constant arguments of length\~1 can omit the marker apostrophes, too,
2575 but there is no two-character analogue.
2578 While one-character escape sequences are mainly used for in-line
2579 functions and system related tasks, the two-letter names following the
2581 construct are glyphs predefined by the roff system; these are called
2582 `Special Characters' in the classical documentation.
2584 Escapes sequences of the form
2590 .SS "Single-Character Escapes"
2595 .\" --------- comments ---------
2601 Everything up to the end of the line is ignored.
2605 Everything up to and including the next newline is ignored.
2607 This is interpreted in copy mode.
2611 except that the terminating newline is ignored as well.
2613 .\" --------- strings ---------
2617 The string stored in the string variable with one-character name\~\c
2622 The string stored in the string variable with two-character name
2627 The string stored in the string variable with name
2629 (with arbitrary length).
2632 .ESC[] * "stringvar arg1 arg2 .\|.\|."
2633 The string stored in the string variable with arbitrarily long name
2641 .\" --------- macro arguments ---------
2645 The name by which the current macro was invoked.
2649 request can make a macro have more than one name.
2653 Macro or string argument with one-digit number\~\c
2655 in the range 1 to\~9.
2659 Macro or string argument with two-digit number
2665 Macro or string argument with number
2669 is a numerical expression evaluating to an integer \[>=]1.
2673 In a macro or string, the concatenation of all the arguments separated
2678 In a macro or string, the concatenation of all the arguments with each
2679 surrounded by double quotes, and separated by spaces.
2683 In a macro, the representation of all parameters as if they were an
2688 .\" --------- escaped characters ---------
2692 reduces to a single backslash; useful to delay its interpretation as
2693 escape character in copy mode.
2695 For a printable backslash, use
2699 to be independent from the current escape character.
2703 The acute accent \[aa]; same as
2705 Unescaped: apostrophe, right quotation mark, single quote (ASCII 0x27).
2709 The grave accent \[ga]; same as
2711 Unescaped: left quote, backquote (ASCII 0x60).
2715 The \- (minus) sign in the current font.
2721 the underline character.
2725 An uninterpreted dot (period), even at start of line.
2729 Default optional hyphenation character.
2733 Transparent line indicator.
2737 In a diversion, this transparently embeds
2741 is read in copy mode.
2743 See also the escape sequences
2749 .\" --------- spacing ---------
2753 Unpaddable space size space glyph (no line break).
2761 1/6\ em narrow space glyph; zero width in nroff.
2765 1/12\ em half-narrow space glyph; zero width in nroff.
2769 Non-printable, zero-width glyph.
2775 except that it behaves like a glyph declared with the
2777 request to be transparent for the purposes of end-of-sentence
2782 Increases the width of the preceding glyph so that the spacing
2783 between that glyph and the following glyph is correct if
2784 the following glyph is a roman glyph.
2788 Modifies the spacing of the following glyph so that the spacing
2789 between that glyph and the preceding glyph is correct if the
2790 preceding glyph is a roman glyph.
2794 Unbreakable space that stretches like a normal inter-word space when a
2799 Inserts a zero-width break point (similar to
2801 but without a soft hyphen character).
2805 Ignored newline, for continuation lines.
2807 .\" --------- structuring ---------
2811 Begin conditional input.
2815 End conditional input.
2817 .\" --------- longer escape names ---------
2821 A glyph with two-character name
2824 .BR "Special Characters" .
2830 (of arbitrary length).
2833 .ESC[] "" "comp1 comp2 .\|.\|."
2834 A composite glyph with components
2839 .\" --------- alphabetical escapes ---------
2843 Non-interpreted leader character.
2849 is acceptable as a name of a string, macro, diversion, register,
2850 environment or font it expands to\~1, and to\~0 otherwise.
2853 .ESCq b abc.\|.\|.\&
2854 Bracket building function.
2860 is acceptable as a valid numeric expression it expands to\~1, and
2865 Interrupt text processing.
2873 but compatible to other roff versions.
2877 Forward (down) 1/2 em (1/2 line in nroff).
2881 Draw a graphical element defined by the characters in
2886 Printable version of the current escape character.
2890 Equivalent to an escape character, but is not interpreted in copy mode.
2894 Change to font with one-character name or one-digit number\~\c
2899 Switch back to previous font.
2903 Change to font with two-character name or two-digit number
2908 Change to font with arbitrarily long name or number expression
2913 Switch back to previous font.
2917 Change to font family with one-character name\~\c
2922 Change to font family with two-character name
2927 Change to font family with arbitrarily long name
2932 Switch back to previous font family.
2936 Return format of register with one-character name\~\c
2944 Return format of register with two-character name
2952 Return format of register with arbitrarily long name
2960 Local horizontal motion; move right
2966 Set height of current font to
2971 Mark horizontal input place in one-character register\~\c
2976 Mark horizontal input place in two-character register
2981 Mark horizontal input place in register with arbitrarily long name
2986 Horizontal line drawing function (optionally using character
2991 Vertical line drawing function (optionally using character
2996 Change to color with one-character name\~\c
3001 Change to color with two-character name
3006 Change to color with arbitrarily long name
3011 Switch back to previous color.
3015 Change filling color for closed drawn objects to color with
3016 one-character name\~\c
3021 Change filling color for closed drawn objects to color with
3027 Change filling color for closed drawn objects to color with
3028 arbitrarily long name
3033 Switch to previous fill color.
3037 The numerical value stored in the register variable with the
3038 one-character name\~\c
3043 The numerical value stored in the register variable with the
3049 The numerical value stored in the register variable with arbitrarily
3055 Typeset the glyph with index\~\c
3057 in the current font.
3059 No special fonts are searched.
3061 Useful for adding (named) entities to a document using the
3063 request and friends.
3066 .ESCq o abc.\|.\|.\&
3075 Disable glyph output.
3077 Mainly for internal use.
3081 Enable glyph output.
3083 Mainly for internal use.
3087 Break and spread output line.
3091 Reverse 1\ em vertical motion (reverse line in nroff).
3094 .ESCq R "name\~\[+-]n"
3102 Set/increase/decrease the point size to/by
3106 is a one-digit number in the range 1 to\~9.
3116 Set/increase/decrease the point size to/by
3120 is a two-digit number \[>=]1.
3134 Set/increase/decrease the point size to/by
3150 Non-interpreted horizontal tab.
3154 Reverse (up) 1/2 em vertical motion (1/2 line in nroff).
3158 Local vertical motion; move down
3164 The contents of the environment variable with one-character
3170 The contents of the environment variable with two-character name
3175 The contents of the environment variable with arbitrarily long name
3180 The width of the glyph sequence
3185 Extra line-space function (negative before, positive after).
3191 as device control function.
3195 Output string variable or macro with one-character name\~\c
3197 uninterpreted as device control function.
3201 Output string variable or macro with two-character name
3203 uninterpreted as device control function.
3207 Output string variable or macro with arbitrarily long name
3209 uninterpreted as device control function.
3215 with zero width (without spacing).
3221 and then restore the horizontal and vertical position;
3223 may not contain tabs or leaders.
3227 The escape sequences
3239 are interpreted in copy mode.
3242 Escape sequences starting with
3246 do not represent single character escape sequences, but introduce escape
3247 names with two or more characters.
3250 If a backslash is followed by a character that does not constitute a
3251 defined escape sequence, the backslash is silently ignored and the
3252 character maps to itself.
3256 .SS "Special Characters"
3259 [Note: `Special Characters' is a misnomer; those entities are (output)
3260 glyphs, not (input) characters.]
3263 Common special characters are predefined by escape sequences of the
3271 Some of these exist in the usual font while most of them are only
3272 available in the special font.
3274 Below you can find a selection of the most important glyphs; a complete
3275 list can be found in
3276 .BR @L_ROFF@-char (@MAN7EXT@).
3301 Printable double quote
3313 Printable backslash character
3345 .SS "Unicode Characters"
3347 Via the special escape
3349 it is possible to include Unicode codepoints and even complete graphem
3350 clusters into a document.
3353 denotes the escape and
3355 is the hexadecimal Unicode codepoint to include; to specify a graphem
3356 cluster specify multiple codepoints separated by underscores, as in
3357 .BI \e[u HEX1 _ HEX2 _ HEX3 ]\c
3366 The availability of Unicode characters depends on the used output device
3372 Strings are defined by the
3374 request and can be retrieved by the
3379 Strings share their name space with macros.
3381 So strings and macros without arguments are roughly equivalent; it is
3382 possible to call a string like a macro and vice-versa, but this often
3383 leads to unpredictable results.
3385 The following string is the only one predefined in @T_ROFF@.
3389 The name of the current output device as specified by the
3391 command line option.
3398 Registers are variables that store a value.
3399 In @T_ROFF@, most registers store numerical values (see section
3400 .B NUMERICAL EXPRESSIONS
3401 above), but some can also hold a string value.
3404 Each register is given a name.
3405 Arbitrary registers can be defined and set with the
3410 The value stored in a register can be retrieved by the escape sequences
3415 Most useful are predefined registers.
3417 In the following the notation
3421 to make clear that we speak about registers.
3423 Please keep in mind that the
3425 decoration is not part of the register name.
3429 .SS "Read-only Registers"
3432 The following registers have predefined values that should not be
3433 modified by the user (usually, registers starting with a dot a
3436 Mostly, they provide information on the current settings or store
3437 results from request calls.
3449 Number of arguments in the current macro or string.
3453 Post-line extra line-space most recently utilized using
3462 is used; always\~1 in
3467 The emboldening offset while
3473 Within a macro, set to\~1 if macro called with the `normal' control
3474 character, and to\~0 otherwise.
3478 Current input line number.
3482 1\~if compatibility mode is in effect, 0\~otherwise.
3486 The depth of the last glyph added to the current environment.
3488 It is positive if the glyph extends below the baseline.
3492 The number of lines remaining to be centered, as set by the
3498 The height of the last glyph added to the current environment.
3500 It is positive if the glyph extends above the baseline.
3504 1\~if colors are enabled, 0\~otherwise.
3508 The skew of the last glyph added to the current environment.
3510 The skew of a glyph is how far to the right of the center of a glyph
3511 the center of an accent over that glyph should be placed.
3515 Current vertical place in current diversion; equal to
3520 The name or number of the current environment (string-valued).
3524 Current font number.
3528 The name of the current input file (string-valued).
3532 The current font family (string-valued).
3536 The current (internal) real font name (string-valued).
3540 The number of the next free font position.
3544 Always 1 in GNU troff and @T_ROFF@.
3546 Macros should use it to test if running under @T_ROFF@.
3550 Text base-line high-water mark on current page or diversion.
3554 Available horizontal resolution in basic units.
3558 The current font height as set with
3563 The current hyphenation language as set by the
3569 The number of immediately preceding consecutive hyphenated lines.
3573 The maximum allowed number of consecutive hyphenated lines, as set by
3580 The current hyphenation flags (as set by the
3586 The current hyphenation margin (as set by the
3592 The current hyphenation space (as set by the
3598 Current indentation.
3602 The indentation that applies to the current output line.
3606 Positive if last output line contains
3611 The current adjustment mode.
3612 It can be stored and used to set adjustment.
3613 (n=1, b=1, l=0, r=5, c=3).
3617 The current horizontal output position (relative to the current indentation).
3621 1\~if pairwise kerning is enabled, 0\~otherwise.
3625 Current line length.
3629 The current line spacing setting as set by
3634 The current ligature mode (as set by the
3640 The current line-tabs mode (as set by the
3646 The line length that applies to the current output line.
3650 The title length (as set by the
3656 The current drawing color (string-valued).
3660 The current background color (string-valued).
3664 Length of text portion on previous output line.
3668 The amount of space that was needed in the last
3670 request that caused a trap to be sprung.
3672 Useful in conjunction with
3677 1\~if in no-space mode, 0\~otherwise.
3681 Current page offset.
3685 The suppression nesting level (see
3690 Current page length.
3694 1\~if the current page is being printed, 0\~otherwise (as determined by the
3696 command line option).
3700 1\~during page ejection, 0\~otherwise.
3704 The number of the next page: either the value set by a
3706 request, or the number of the current page plus\ 1.
3710 The current point size in scaled points.
3714 The last-requested point size in scaled points.
3718 The current post-vertical line spacing.
3722 The number of lines to be right-justified as set by the
3728 Current point size as a decimal fraction.
3732 The slant of the current font as set with
3737 The last requested point size in points as a decimal fraction
3742 The value of the parameters set by the first argument of the
3748 The value of the parameters set by the second argument of the
3754 The current font style (string-valued).
3758 Vertical distance to the next trap.
3769 A string representation of the current tab settings suitable for use
3770 as an argument to the
3776 The amount of vertical space truncated by the most recently sprung
3777 vertical position trap, or, if the trap was sprung by a
3779 request, minus the amount of vertical motion produced by
3782 Useful in conjunction with the
3787 Equal to 1 in fill mode and 0 in no-fill mode.
3791 Equal to 1 in safer mode and 0 in unsafe mode.
3795 Current vertical line spacing.
3799 Available vertical resolution in basic units.
3803 1\~if vertical position traps are enabled, 0\~otherwise.
3807 Width of previous glyph.
3811 The sum of the number codes of the currently enabled warnings.
3815 The major version number.
3819 The minor version number.
3823 The revision number of @T_ROFF@.
3827 Name of current diversion.
3831 Zoom factor for current font (in multiples of 1/1000th; zero if no
3837 .SS "Writable Registers"
3840 The following registers can be read and written by the user.
3841 They have predefined default values, but these can be modified for
3842 customizing a document.
3848 Current page number.
3852 Current input line number.
3856 Character type (set by width function
3861 Maximal width of last completed diversion.
3865 Height of last completed diversion.
3869 Current day of week (1-7).
3873 Current day of month (1-31).
3877 The number of hours past midnight.
3879 Initialized at start-up.
3883 Current horizontal position at input line.
3887 Lower left x-coordinate (in PostScript units) of a given PostScript
3893 Lower left y-coordinate (in PostScript units) of a given PostScript
3904 The number of minutes after the hour.
3906 Initialized at start-up.
3910 Current month (1-12).
3914 Vertical position of last printed text base-line.
3924 These four registers mark the top left and bottom right hand corners of a box
3925 which encompasses all written glyphs.
3926 They are reset to \-1 by
3935 but takes account of the heights and depths of glyphs.
3941 but takes account of the heights and depths of glyphs.
3945 Depth of string below base line (generated by width function
3950 The number of seconds after the minute.
3952 Initialized at start-up.
3956 Right skip width from the center of the last glyph in the
3962 If greater than 0, the maximum number of objects on the input stack.
3964 If \[<=]0 there is no limit, i.e., recursion can continue until virtual
3965 memory is exhausted.
3969 The amount of horizontal space (possibly negative) that should be
3970 added to the last glyph before a subscript (generated by width
3976 Height of string above base line (generated by width function
3981 The return value of the
3983 function executed by the last
3989 Upper right x-coordinate (in PostScript units) of a given PostScript
3995 Upper right y-coordinate (in PostScript units) of a given PostScript
4001 The current year (year 2000 compliant).
4005 Current year minus 1900.
4007 For Y2K compliance use
4018 The differences of the @T_ROFF@ language in comparison to classical
4022 .BR @L_ROFF@-diff (@MAN7EXT@).
4025 The @T_ROFF@ system provides a compatibility mode, see
4026 .BR @L_ROFF@ (@MAN1EXT@)
4027 on how to invoke this.
4037 Include a complete, self-contained example that will allow the bug to
4038 be reproduced, and say which version of groff you are using.
4044 Copyright (c) 2014 - 2017 Steffen (Daode) Nurpmeso <steffen@sdaoden.eu>.
4046 Copyright (C) 2000 - 2008
4047 Free Software Foundation, Inc.
4050 This document is distributed under the terms of the FDL (GNU Free
4051 Documentation License) version 1.1 or later.
4053 You should have received a copy of the FDL on your system, it is also
4054 available on-line at the
4055 .UR http://\:www.gnu.org/\:copyleft/\:fdl.html
4060 This document was written by
4070 .BR @L_ROFF@ (@MAN1EXT@)
4071 the usage of the @L_ROFF@ program and pointers to the documentation
4072 and availability of the @T_ROFF@ system.
4075 .BR @L_ROFF@-diff (@MAN7EXT@)
4076 the differences of the @T_ROFF@ language as compared to classical roff.
4078 This is the authoritative document for the predefined language
4079 elements that are specific to @T_ROFF@.
4082 .BR @L_ROFF@-char (@MAN7EXT@)
4083 the predefined @T_ROFF@ special characters (glyphs).
4086 .BR @L_ROFF@-font (@MAN5EXT@)
4087 the specification of fonts and the DESC file.
4090 .BR @L_ROFF@-history (@MAN7EXT@)
4091 the history of roff, the common parts shared by all roff systems, and
4092 pointers to further documentation.
4096 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:54.ps.gz
4097 Nroff/\:Troff User's Manual by Ossanna & Kernighan
4099 \[em] the bible for classical troff.