5 This file is part of groff, the GNU roff type-setting system.
7 Copyright (C) 2000 Free Software Foundation, Inc.
8 written by Bernd Warken <bwarken@mayn.de>
10 Last update: 17 May 2000
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 AUTHOR, 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 .\" --------------------------------------------------------------------
37 .\" a comment macro which does nothing
46 .c text lines in macro definitions or bracketed sections \{...\}
52 . ds @tmp@ \f(CB\$1\fP
58 .als shellcommand option
60 .c --------- characters ---------
63 . ds @tmp@ \f(CB\$1\fP
70 . ds @tmp@ \(oq\f(CB\$1\fP\(cq
77 . ds @tmp@ \(lq\f(CB\$1\fP\(rq
83 .c --------- requests ---------
89 . IP "\f(CB\&\*[@tmp@] \fP\f(CI\&\$*\fP" 10n
94 . ds @tmp@ \f(CB\$1\fP
100 .c --------- macro or function arguments ---------
103 . ds @tmp@ \f(CI\$1\fP
105 . while (\n[.$] >= 2) \{\
106 . as @tmp@ \/\f(CR\$1\fP\f(CI\,\$2\fP
109 . if \n[.$] .as @tmp@ \/\f(CR\$1\fP
114 .c argument followed by a numerical expression
116 . ds @tmp@ \f(CI\$1\fP\|\f(CR\$2\fP
122 .c --------- numerical elements ---------
125 . ds @tmp@ \f(CR\$1\fP
132 . ds @tmp@ \&\$1\ \f(CR\$2\fP
138 .als scaleindicator request
141 . ds @tmp@ \f(CR\$1\fP\f(CB\$2\fP
148 . ds @tmp@ \(oq\f(CB\$1\fP\(cq
154 .c --------- escape sequences ---------
157 . ds @tmp@ \f(CB\(rs\$1[\fP\f(CI\$2\fP\f(CB]\fP
164 . ds @tmp@ \f(CB\(rs\$1(\fP\f(CI\$2\fP
171 . ds @tmp@ \f(CB\(rs\$1\fP\f(CI\$2\fP
178 . ds @tmp@ \f(CB\(rs[\fP\f(CI\$1\fP\f(CB]\fP
185 . ds @tmp@ \f(CB\(rs(\fP\f(CI\$1\fP
192 . ds @tmp@ \f(CB\(rs\$1\fP
199 . ds @tmp@ \f(CB\(rs(\$1\fP
206 . ds @tmp@ \f(CB\(rs[\$1]\fP
212 .c escape sequence synopsis
216 . IP "\f(CB\(rs\&\*[@tmp@]\fP\f(CI\&\$*\fP"
220 .c synopsis for escape sequences with a long name
225 . IP "\f(CB\(rs\&\*[@arg1@][\fP\f(CI\&\*[@arg2@]\fP\f(CB]\&\$*\fP"
230 .c synopsis escape sequence with quoted argument
234 . IP "\f(CB\(rs\&\*[@tmp@]\(cq\fP\f(CI\h'-0.2m'\$*\/\fP\f(CB\(cq\fP"
238 .c synopsis for 2-escapes (special characters)
242 . text \f(CB\(rs(\&\*[@tmp@]\ \ \ \fP\fR\(\*[@tmp@]\fP
248 .c --------- registers ---------
250 .c synopsis for registers
253 . text \&\f(CR\(rsn[\fP\f(CB\$1\fP\f(CR]\fP
258 .als register request
260 .c --------- warnings ---------
264 .c description of warnings
275 .\" --------------------------------------------------------------------
277 .\" --------------------------------------------------------------------
279 .TH GROFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
281 groff \- a short reference for the GNU roff language
283 .\" --------------------------------------------------------------------
285 .\" --------------------------------------------------------------------
289 and is the free implementation of the roff type-setting system.
292 for a survey and the background of the groff system.
294 This document gives only short descriptions of the predefined roff
295 language elements as used in groff.
296 Both the classical features and the groff extensions are provided.
303 is compatible with the classical system and provides proper extensions.
309 could be used as synonyms.
312 slightly tends to refer more to the classical aspects, whereas
314 emphasizes the GNU extensions, and
316 is the general term for the language.
318 This file is only a short version of the complete documentation that is
322 file, which contains more detailed, actual, and concise information.
324 The general syntax for writing groff documents is relatively easy, but
325 writing extensions to the roff language can be a bit harder.
327 The roff language is line-oriented.
328 There are only two kinds of lines, control lines and text lines.
329 The control lines start with a control character, by default a period
333 all other lines are text lines.
336 represent commands, optionally with arguments.
337 They have the following syntax.
338 The leading control character can be followed by a command name;
339 arguments, if any, are separated by blanks from the command name and
340 among themselves, for example,
343 \&\.command_name arg1 arg2
346 For indentation, any number of space or tab characters can be inserted
347 between the leading control character and the command name, but the control
348 character must be on the first position of the line.
351 represent the parts that will be printed.
352 They can be modified by escape sequences, which are recognized by a
355 These are in-line or even in-word formatting elements or functions.
356 Some of these take arguments separated by single quotes
358 others are regulated by a length encoding introduced by an open
361 or enclosed in brackets
366 The roff language provides flexible instruments for writing language
367 extension, such as macros.
368 When interpreting macro definitions, the roff system enters a special
369 operating mode, called the
372 The copy mode behavior can be quite tricky, but there are some rules
373 that ensure a safe usage.
375 Printable backslashes must be denoted as
379 represents the current escape character.
380 To get a backslash glyph, use
383 Double all backslashes.
385 Begin all text lines with the special non-spacing character
388 This does not produce the most efficient code, but it should work as a
390 For better strategies, see the groff info file and
391 .BR groff_tmac (@MAN5EXT@).
393 Reading roff source files is easier, just reduce all double backslashes
394 to a single one in all macro definitions.
396 .\" --------------------------------------------------------------------
398 .\" --------------------------------------------------------------------
399 The roff language elements add formatting information to a text file.
400 The fundamental elements are predefined commands and variables that make
401 roff a full-blown programming language.
403 There are two kinds of roff commands, possibly with arguments.
405 are written on a line of their own starting with a dot
411 are in-line functions and in-word formatting elements starting with a
415 The user can define her own formatting commands using the
417 request. These commands are called
419 but they are used exactly like requests. Macro packages are pre-defined
420 sets of macros written in the groff language.
421 A user's possibilities to create escape sequences herself is very
422 limited, only special characters can be mapped.
424 The groff language provides several kinds of variables with
425 different interfaces.
426 There are pre-defined variables, but the user can define her own
430 variables store character sequences.
431 They are set with the
433 request and retrieved by the
438 variables can store numerical values, numbers with a scale unit, and
439 occasionally string-like objects.
440 They are set with the
442 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.
454 are identified either by a name or by an internal number.
455 The current font is chosen by the
460 Each device has special fonts, but the following fonts are available for
463 is the standard font Roman.
472 is everywhere available, but on text devices, it is displayed as an
473 underlined Roman font.
474 For the graphical output devices, there exist constant-width pendants of
480 On text devices, all characters have a constant width anyway.
482 Moreover, there are some advanced roff elements.
485 stores information into a macro for later usage.
488 is a positional condition like a certain number of lines from page top
489 or in a diversion or in the input.
490 Some action can be prescribed to be run automatically when the condition
493 More detailed information can be found in the groff info file.
495 .\" --------------------------------------------------------------------
496 .SH "CONTROL CHARACTERS"
497 .\" --------------------------------------------------------------------
498 There is a small set of characters that have a special controlling task
499 in certain conditions.
502 A dot is only special at the beginning of a line or after the
503 condition in the requests
509 There it is the control character that introduces a request (or macro).
510 The special behavior can be delayed by using the
515 request, the control character can be set to a different character,
518 a non-special character.
520 In all other positions, it just means a dot character.
521 In text paragraphs, it is advantageous to start each sentence at a line
525 The single quote has two controlling tasks. At the beginning of a line
526 and in the conditional requests it is the non-breaking control
528 That means that it introduces a request like the dot, but with the
529 additional property that this request doesn't cause a linebreak.
532 request, the non-break control character can be set to a different
535 As a second task, it is the most commonly used argument separator in
536 some functional escape sequences (but any pair of characters not part
537 of the argument will work).
538 In all other positions, it denotes the single quote or apostrophe
540 Groff provides a printable representation with the
545 The double quote is used to enclose arguments in requests and macros. In
550 requests, a leading double quote in the argument will be stripped off,
551 making everything else afterwards the string to be defined (enabling leading
553 The escaped double quote
555 introduces a comment.
556 Otherwise, it is not special.
557 Groff provides a printable representation with the
562 The backslash usually introduces an escape sequence (this can be
566 A printed version of the escape character is the
568 escape; a backslash glyph can be obtained by
572 The open parenthesis is only special in escape sequences when
573 introducing an escape name or argument consisting of exactly two
575 In groff, this behavior can be replaced by the \f(CB[]\fP construct.
578 The opening bracket is only special in groff escape sequences; there it
579 is used to introduce a long escape name or long escape argument.
580 Otherwise, it is non-special, e.g. in macro calls.
583 The closing bracket is only special in groff escape sequences; there it
584 terminates a long escape name or long escape argument.
585 Otherwise, it is non-special.
588 Space characters are only functional characters. They separate the
589 arguments in requests or macros, and the words in text lines.
590 They are subject to groff's horizontal spacing calculations.
591 To get a defined space width, escape sequences like
593 (this is the escape character followed by a space),
600 In text paragraphs, newlines mostly behave like space characters.
601 Continuation lines can be specified by an escaped newline, i.e., by
602 specifying a backslash
604 as the last character of a line.
606 If a tab character occurs during text the interpreter makes a horizontal
607 jump to the next pre-defined tab position.
608 There is a sophisticated interface for handling tab positions.
610 .\" --------------------------------------------------------------------
611 .SH "NUMERICAL EXPRESSIONS"
612 .\" --------------------------------------------------------------------
615 is a signed or unsigned integer or float with or without an appended
619 is a one-character abbreviation for a unit of measurement.
620 A number followed by a scale indicator signifies a size value.
621 By default, numerical values do not have a scale indicator, i.e., they are
624 The roff language defines the following scale indicators.
633 P@Pica\ \(eq\ 1/6\ inch
634 p@Point\ \(eq\ 1/72\ inch
636 Em\ \(eq\ \fRthe font size in points (width of letter `\f(CRm\fR')
638 M@100th \fRof an \f(CREm
640 u@\fRBasic unit for actual output device
641 v@\fRVertical line space in basic units
643 scaled point\ \(eq\ 1/\f(CIsizescale\fR of a point (defined in
644 font \fIDESC\fP file)
650 .B Numerical expressions
651 are combinations of the numerical values defined above with
652 the arithmetical operators
659 the comparative operators
667 the logical operators
681 added the following operators for numerical expressions:
688 e1\f(CB>?\fPe2@The maximum of \f(CIe1\fP and \f(CIe2\fP.
689 e1\f(CB<?\fPe2@The minimum of \f(CIe1\fP and \f(CIe2\fP.
690 \f(CB(\fPc\f(CB;\fPe\f(CB)@T{
691 Evaluate \f(CIe\fP using \f(CIc\fP as the default scaling
698 For details see the groff info file.
700 .\" --------------------------------------------------------------------
702 .\" --------------------------------------------------------------------
704 occur in tests raised by the
710 The following table characterizes the different types of conditions.
718 A numerical expression \f(CIN\fP yields true if its value
722 True if the value of \f(CIN\fP is\ \f(CR\(<=0\fP.
724 \&'\f(CIs1\fP'\f(CIs2\fP'@T{
725 True if string\ \f(CIs1\fP is identical to string\ \f(CIs2\fP.
727 !'\f(CIs1\fP'\f(CIs2\fP'@T{
728 True if string\ \f(CIs1\fP is not identical to string\ \f(CIs2\fP.
731 True if there is a character\ \f(CIch\fP available.
734 True if there is a string, macro, diversion, or request
737 e@Current page number is even.
738 o@Current page number is odd.
739 n@Formatter is \fBnroff\fP.
741 True if there is a register named \f(CIreg\fP.
743 t@Formatter is \fBtroff\fR.
749 .\" --------------------------------------------------------------------
751 .\" --------------------------------------------------------------------
752 This section provides a short reference for the predefined requests.
753 In groff, request and macro names can be arbitrarily long.
754 No bracketing or marking of long names is needed.
756 Most requests take one or more arguments.
757 The arguments are separated by space characters (no tabs!); there is no
758 inherent limit for their length or number.
759 An argument can be enclosed by a pair of double quotes: This is very handy
760 if an argument contains space characters, e.g.,
761 .argument "\(dqarg\ with\ space\(dq"
762 denotes a single argument.
764 Some requests have optional arguments with a different behaviour.
765 Not all of these details are outlined here.
766 Refer to the groff info file for all details.
768 In the following request specifications, most argument names were chosen
770 Only the following denotations need clarification.
777 c@denotes a single character.
779 a font either specified as a font name or a font number.
782 all characters up to the end of the line or within \f(CB\(rs{\fP
786 is a numerical expression that evaluates to an integer value.
789 is an arbitrary numerical expression, signed or unsigned.
792 has three meanings depending on its sign, described below.
798 If an expression defined as
802 sign the resulting value of the expression will be added to an already
803 existing value inherent to the related request, e.g. adding to a number
805 If the expression starts with a
807 the value of the expression will be subtracted from the request value.
811 replaces the existing value directly.
812 To assign a negative number either prepend\ \c
814 or enclose the negative number in parentheses.
816 .\" --------------------------------------------------------------------
817 .SS "REQUEST SHORT REFERENCE"
818 .\" --------------------------------------------------------------------
822 Empty line, ignored. Useful for structuring documents.
824 .REQ .\(rs\(dq anything
825 Complete line is a comment.
830 on standard error, exit program.
833 Begin line adjustment for output lines in current adjust mode.
836 Start line adjustment in mode
838 (\f(CIc\fP\f(CR\|\^\(eq\|l,r,b,n\fP).
845 (\f(CIc\fP\f(CR\|\^\(eq\|l,i,I,a,A\fP).
847 .REQ .aln alias register
848 Create alias name for
851 .REQ .als alias object
852 Create alias name for request, string, macro, or diversion
869 .REQ .as stringvar anything
873 .argument stringvar .
875 .REQ .asciify diversion
876 Unformat ASCII characters, spaces, and some escape sequences in
877 .argument diversion .
880 Print a backtrace of the input on stderr.
890 Embolden Special Font
896 End current diversion.
901 omitting a partially filled line.
904 End current diversion.
909 omitting a partially filled line.
911 Eject current page and begin new page.
914 Eject current page; next page number
918 Set the blank line macro to
925 Break out of a while loop.
928 Reset no-break control character to
932 Set no-break control character to
936 Reset control character to
940 Set control character to
944 Center the next input line.
952 Copy contents of file
954 unprocessed to stdout or to the diversion.
956 .REQ .cflags mode c1 c2 ...
972 .REQ .char c anything
979 Chop the last character off macro, string, or diversion
987 Finish the current iteration of a while loop.
990 Enable compatibility mode.
995 is zero disable compatibility mode, otherwise enable it.
998 Set constant character width mode for
1006 Continuous underline in nroff, like
1011 End current diversion.
1014 Divert and append to
1032 Define or redefine a macro whose name is contained in the string register
1039 Define or redefine a macro indirectly.
1043 are string registers whose contents are interpolated for the macro name
1044 and the end macro, respectively.
1047 End current diversion.
1056 with compatibility mode enabled.
1058 .REQ .ds stringvar anything
1062 .argument anything .
1065 Set diversion trap to position
1067 (default scale indicator\ \c
1068 .scaleindicator v ).
1071 Reset escape character to
1075 Set escape character to
1079 Restore escape character saved with
1083 Save current escape character.
1086 Else part for if-else (\c
1093 will be run after the end of input.
1096 Turn off escape character mechanism.
1099 Switch to previous environment.
1102 Push down environment number or name
1107 Copy the contents of environment
1109 to the current environment.
1110 No pushing or popping.
1113 Exit from roff processing.
1116 Return to previous font family.
1119 Set the current font family to
1123 Disable field mechanism.
1126 Set field delimiter to
1128 and pad character to space.
1130 Set field delimiter to
1132 and pad character to
1139 Flush output buffer.
1147 .REQ .fp n internal external
1148 Mount font with long
1155 .REQ .fspecial font s1 s2...
1156 When the current font is
1165 Return to previous font.
1169 Change to font name or number
1175 .REQ .ftr font1 font2
1182 Remove additional hyphenation indicator character.
1185 Set up additional hyphenation indicator character\ \c
1188 .REQ .hcode c1 code1 c2 code2 ...
1189 Set the hyphenation code of character
1200 Set the current hyphenation language to
1204 Set the maximum number of consecutive hyphenated lines to
1208 Read hyphenation patterns from
1214 with exceptional hyphenation.
1217 Switch to hyphenation mode
1221 Set the hyphenation margin to
1223 (default scale indicator\ \c
1224 .scaleindicator m ).
1227 Set the hyphenation space to
1230 .REQ .ie cond anything
1238 .REQ .if cond anything
1242 .argument anything ;
1243 otherwise do nothing.
1255 Change to previous indent value.
1258 Change indent according to
1260 (default scale indicator\ \c
1261 .scaleindicator m ).
1264 Set an input-line count trap at position
1268 Enable pairwise kerning.
1273 is zero, disable pairwise kerning, otherwise enable it.
1276 Remove leader repetition character.
1279 Set leader repetition character to\ \c
1282 .REQ .length register anything
1283 Write the length of the string
1286 .argument register .
1289 Enable line-tabs mode (i.e., calculate tab positions relative to output
1295 is zero, disable line-tabs mode, otherwise enable it.
1298 Set input line number to
1308 Change to previous line length.
1311 Set line length according to
1314 .scalednumber 6.5 i ,
1315 default scale indicator\ \c
1316 .scaleindicator m ).
1319 Change to the previous value of additional intra-line skip.
1322 Set additional intra-line skip value to
1326 blank lines are inserted after each text output line.
1329 Length of title (default scale indicator\ \c
1330 .scaleindicator m ).
1333 Margin character off.
1338 after each text line at actual distance from right margin.
1341 Set margin character to
1345 from right margin (default scale indicator\ \c
1346 .scaleindicator m ).
1349 Mark current vertical position in
1350 .argument register .
1353 The same as the .so request except that
1355 is searched in the tmac directories.
1358 No output-line adjusting.
1361 Need a one-line vertical space.
1366 vertical space (default scale indicator\ \c
1367 .scaleindicator v ).
1370 No filling or adjusting of output-lines.
1378 .REQ .nm \(+-N M S I
1379 In line number mode, set number, multiple, spacing, and indent.
1382 Do not number next line.
1391 .argument anything .
1393 .REQ .nr register \(+-N M
1402 Make the built-in condition
1409 Turn no-space mode on.
1414 .REQ .open stream filename
1417 for writing and associate the stream named
1421 .REQ .opena stream filename
1427 Output vertical distance that was saved by the
1432 Reset page number character to\ \c
1436 Page number character.
1444 Set page length to default
1445 .scalednumber 11 i .
1446 The current page length is stored in
1450 Change page length to
1452 (default scale indicator\ \c
1453 .scaleindicator v ).
1456 Print macro names and sizes (number of blocks of 128 bytes).
1459 Print only total of sizes of macros (number of 128 bytes blocks).
1466 Print the names and contents of all currently defined number registers
1470 Change to previous page offset. The current page offset is available in
1478 Return to previous point-size.
1484 Get the bounding box of a PostScript image
1485 .argument filename .
1488 This behaves like the
1490 request except that input comes from the standard output of
1494 Print the names and positions of all traps (not including input line
1495 traps and diversion traps) on stderr.
1497 .REQ .rchar c1 c2...
1498 Remove the definitions of characters
1507 Return from a macro.
1510 Right justify the next
1515 Remove request, macro, or string
1519 Rename request, macro, or string
1532 .argument register .
1535 Restore spacing; turn no-space mode off.
1540 to marked vertical place (default scale indicator\ \c
1541 .scaleindicator v ).
1544 Reset soft hyphen character to
1548 Set the soft hyphen character to
1552 In a macro, shift the arguments by
1557 Include source file.
1560 Skip one line vertically.
1563 Space vertical distance
1565 up or down according to sign of
1567 (default scaling indicator\ \c
1568 .scaleindicator v ).
1570 .REQ .special s1 s2 ...
1574 etc. are special and will be searched for characters not in the current font.
1577 Space-character size set to
1579 of the spacewidth in the current font.
1582 Space-character size set to
1584 and sentence space size set to
1586 of the spacewidth in the current font (\f(CR\(eq1/3 em\fP).
1594 .REQ .substring register n1 n2
1595 Replace the string in
1597 with the substring defined by the indices
1608 Save the vertical distance
1610 for later output with
1614 .REQ .sy command-line
1616 .argument command-line .
1619 Set tabs after every position that is a multiple of
1621 (default scaling indicator\ \c
1622 .scaleindicator m ).
1623 .REQ .ta n1 n2 ... nn \f(CBT\fP r1 r2 ... rn
1624 Set tabs at positions
1635 .argument nn + rn + r1 ,
1636 .argument nn + rn + r2 ,
1638 .argument nn + rn + rn ,
1642 .\"Restore internally saved tab positions.
1645 .\"Save tab positions internally.
1648 Remove tab repition character.
1650 Set tab repetition character to\ \c
1654 Temporary indent next line (default scaling indicator\ \c
1655 .scaleindicator m ).
1657 .REQ .tkf font s1 n1 s2 n2
1658 Enable track kerning for
1661 .REQ .tl \f(CB\(cq\fPleft\f(CB\(cq\fPcenter\f(CB\(cq\fPright\f(CB\(cq\fP
1667 on terminal (UNIX standard message output).
1672 on terminal (UNIX standard message output), allowing leading whitespace if
1676 (which will be stripped off).
1681 without emitting a final newline.
1694 Transparently output the contents of file
1695 .argument filename .
1698 This is the same as the
1700 request except that the translations do not apply to text that is
1701 transparently throughput into a diversion with
1705 Make the built-in condition
1712 Underline font set to
1714 (to be switched to by
1718 Underline (italicize in troff)
1722 .REQ .unformat diversion
1723 Unformat space characters and tabs, preserving font information in
1724 .argument diversion .
1726 Enable vertical position traps if
1728 is non-zero, disable them otherwise.
1731 Change to previous vertical base line spacing.
1734 Set vertical base line spacing to
1737 .scalednumber 12 p .
1740 Set warnings code to
1744 Set location trap; negative means from page bottom.
1746 .REQ .while cond anything
1753 .REQ .write stream anything
1761 Besides these standard groff requests, there might be further macro
1763 They can originate from a macro package (see
1764 .BR roff (@MAN7EXT@)
1765 for an overview) or from a preprocessor.
1767 Preprocessor macros are easy to be recognized. They enclose their code
1768 into a pair of characteristic macros.
1771 box, center, tab (@);
1774 preprocessor@start macro@ end macro
1781 soelim@\fInone@\fInone
1786 .\" --------------------------------------------------------------------
1787 .SH "ESCAPE SEQUENCES"
1788 .\" --------------------------------------------------------------------
1790 Escape sequences are in-line language elements usually introduced by
1793 and followed by an escape name and sometimes by a required argument.
1794 Input processing is continued directly after the escaped character or
1795 the argument resp. without an intervening separation character.
1796 So there must be a way to determine the end of the escape name and the end
1799 This is done by enclosing names (escape name and arguments consisting of
1800 a variable name) by a pair of brackets
1802 and constant arguments (number expressions and characters) by apostrophes
1804 .IR \(cqconstant\(cq .
1806 There are abbreviations for short names.
1807 Two character escape names can be specified by an opening parenthesis like
1809 without a closing counterpart.
1810 And all one-character names different from the special characters
1814 can even be specified without a marker in the form
1817 Constant arguments of length
1819 can omit the marker apostrophes, too, but there is no two-character
1822 While 1-character escape sequences are mainly used for in-line functions
1823 and system related tasks, the 2-letter names following the
1825 construct are used for special characters predefined by the roff system.
1826 Names with more than two characters
1828 mostly denote user defined named characters (see the
1832 .\" --------------------------------------------------------------------
1833 .SS "SINGLE CHARACTER ESCAPES"
1834 .\" --------------------------------------------------------------------
1838 .\" --------- comments ---------
1841 Beginning of a comment.
1842 Everything up to the end of the line is ignored.
1845 Everything up to and including the next newline is ignored.
1846 This is interpreted in copy mode.
1849 except the ignoring of the terminating newline.
1851 .\" --------- strings ---------
1854 The string stored in the string variable with 1-character name
1858 The string stored in the string variable with 2-character name
1862 The string stored in the string variable with arbitrary length name
1863 .argument stringvar .
1865 .\" --------- macro arguments ---------
1868 The name by which the current macro was invoked. The
1870 request can make a macro have more than one name.
1873 Macro argument with 1-place number
1877 is a digit between 1 and 9.
1880 Macro argument with 2-digit number
1884 Macro argument with number
1888 is a numerical expression evaluating to an integer \(>=1.
1891 In a macro, the concatenation of all the arguments separated by spaces.
1894 In a macro, the concatenation of all the arguments with each surrounded
1895 by double quotes, and separated by spaces.
1897 .\" --------- escaped characters ---------
1900 reduces to a single backslash; useful to delay its interpretation as
1901 escape character in copy mode.
1902 For a printable backslash, use
1906 The acute accent \(aa; same as
1908 Unescaped: apostrophe, right quotation mark, single quote (ASCII 0x27).
1911 The grave accent \(ga; same as
1913 Unescaped: left quote, backquote (ASCII 0x60).
1916 The \- sign in the current font.
1919 An uninterpreted dot (period), even at start of line.
1922 Default optional hyphenation character.
1925 Transparent line indicator.
1927 .ESC ? anything\fB?\fP
1928 In a diversion, this will transparently embed
1932 is read in copy mode.
1933 See also the escape sequences
1939 .\" --------- spacing ---------
1942 Unpaddable space-size space character (no line break).
1948 1/6\ em narrow space character; zero width in nroff.
1951 1/12\ em half-narrow space character; zero width in nroff.
1954 Non-printable, zero width character.
1959 except that it behaves like a character declared with the cflags
1960 request to be transparent for the purposes of end of sentence
1964 Increases the width of the preceding character so that the spacing
1965 between that character and the following character will be correct if
1966 the following character is a roman character.
1969 Modifies the spacing of the following character so that the spacing
1970 between that character and the preceding character will correct if the
1971 preceding character is a roman character.
1974 Unbreakable space that stretches like a normal inter-word space when a
1978 Inserts a zero-width break point (similar to
1980 but without a soft hyphen character).
1983 Ignored newline, for continuation lines.
1985 .\" --------- structuring ---------
1988 Begin conditional input.
1991 End conditional input.
1993 .\" --------- longer escape names ---------
1996 The special character with 2-character name
1999 .BR "SPECIAL CHARACTERS" .
2002 The named character with arbitrary length name
2005 .\" --------- alphabetical escapes ---------
2008 Non-interpreted leader character.
2013 is acceptable as a name of a string, macro, diversion, register,
2014 environment or font it expands to
2021 Bracket building function.
2026 is acceptable as a valid numeric expression it expands to
2033 Interrupt text processing.
2036 The character called
2040 but compatible to other roff versions.
2043 Forward (down) 1/2 em vertical unit (1/2 line in nroff).
2046 Draw a graphical element defined by the characters in
2048 see groff info file for details.
2051 Printable version of the current escape character.
2054 Equivalent to an escape character, but is not interpreted in copy-mode.
2057 Change to font with 1-character name or 1-digit number
2061 Change to font with 2-characer name or 2-digit number
2065 Change to font with arbitrary length name or number expression
2069 Return format of register with name
2079 Local horizontal motion; move right
2084 Set height of current font to
2088 Mark horizontal input place in register with arbitrary length name
2096 Horizontal line drawing function (optionally using character
2100 Vertical line drawing function (optionally using character
2104 The numerical value stored in the register variable with the 1-character
2109 The numerical value stored in the register variable with the 2-character
2114 The numerical value stored in the register variable with arbitrary
2119 Typeset the character with code
2121 in the current font, no special fonts are searched. Useful for adding
2122 characters to a font using the
2127 Overstrike characters
2134 Break and spread output line.
2137 Reverse 1\ em vertical motion (reverse line in nroff).
2146 Set the point size to
2148 scaled points. Note the alternative forms
2149 .BI \(rss \(+- [ N ]\c
2151 .BI \(rss' \(+-N '\c
2153 .BI \(rss \(+- ' N '\c
2156 .BI \(rss \(+- ( xy\c
2169 Non-interpreted horizontal tab.
2172 Reverse (up) 1/2 em vertical motion (1/2 line in nroff).
2175 Local vertical motion; move down
2180 The contents of the environment variable
2188 The width of the character sequence
2192 Extra line-space function (negative before, positive after).
2197 as device control function.
2200 Output string variable or macro
2202 uninterpreted as device control function.
2211 with zero width (without spacing).
2216 and then restore the horizontal and vertical position;
2218 may not contain tabs or leaders.
2221 The escape sequences
2233 are interpreted in copy mode.
2235 Escape sequences starting with
2239 do not represent single character escape sequences, but introduce escape
2240 names with two or more characters.
2242 If a backslash is followed by a character that does not constitute a
2243 defined escape sequence the backslash is silently ignored and the
2244 character maps to itself.
2246 .\" --------------------------------------------------------------------
2247 .SS "SPECIAL CHARACTERS"
2248 .\" --------------------------------------------------------------------
2249 Common special characters are predefined by escape sequences of the form
2255 Some of these exist in the usual font while most of them are only
2256 available in the special font. Below you'll find a selection of the most
2257 important glyphs; a complete list can be found in
2258 .BR groff_char (@MAN7EXT@).
2266 .ESc dd Double dagger
2271 .ESc rg Registered sign
2272 .ESc sc Section sign
2273 .ESc ul Underline character
2275 .ESc >= Larger or equal
2276 .ESc <= Less or equal
2280 .ESc +- Plus-minus sign
2284 .\" --------------------------------------------------------------------
2286 .\" --------------------------------------------------------------------
2287 Registers are variables that store a value.
2288 In groff, most registers store numerical values (see section
2289 .B NUMERICAL EXPRESSIONS
2290 above), but some can also hold a string value.
2292 Each register is given a name.
2293 Arbitrary registers can be defined and set with the request
2295 .argument register .
2297 The value stored in a register can be retrieved by the escape sequences
2301 Most useful are predefined registers.
2302 In the following the notation
2304 is used to refer to a register called
2306 to make clear that we speak about registers.
2307 Please keep in mind that the
2309 decoration is not part of the register name.
2311 .\" --------------------------------------------------------------------
2312 .SS "READ-ONLY REGISTERS"
2313 .\" --------------------------------------------------------------------
2314 The following registers have predefined values that should not be
2315 modified by the user (usually, registers starting with a dot a read-only).
2316 Mostly, they provide information on the current settings or store results
2320 .REG .$ Number of arguments in the current macro.
2322 Post-line extra line-space most recently utilized using
2335 .REG .c Current input line number.
2336 .REG .C 1 if compatibility mode is in effect, 0 otherwise.
2338 The depth of the last character added to the current environment.
2339 It is positive if the character extends below the baseline.
2341 The number of lines remaining to be centered, as set by the
2345 The height of the last character added to the current environment.
2346 It is positive if the character extends above the baseline.
2348 The skew of the last character added to the current environment.
2349 The skew of a character is how far to the right of the center of a character
2350 the center of an accent over that character should be placed.
2352 Current vertical place in current diversion; equal to register
2354 .REG .ev The name or number of the current environment (string-valued).
2355 .REG .f Current font number.
2356 .REG .fam The current font family (string-valued).
2357 .REG .fp The number of the next free font position.
2359 Always 1 in GNU troff.
2360 Macros should use it to test if running under groff.
2361 .REG .h Text base-line high-water mark on current page or diversion.
2362 .REG .H Available horizontal resolution in basic units.
2364 The current hyphenation language as set by the
2368 The number of immediately preceding consecutive hyphenated lines.
2370 The maximum allowed number of consecutive hyphenated lines, as set by
2375 The current hyphenation flags (as set by the
2379 The current hyphenation margin (as set by the
2383 The current hyphenation space (as set by the
2386 .REG .i Current ident.
2387 .REG .in The indent that applies to the current output line.
2389 Positive if last output line contains
2393 if pairwise kerning is enabled,
2396 .REG .l Current line length.
2398 The current ligature mode (as set by the
2402 The current line-tabs mode (as set by the
2405 .REG .ll The line length that applies to the current output line.
2407 The title length (as set by the
2410 .REG .n Length of text portion on previous output line.
2412 The amount of space that was needed in the last
2414 request that caused a trap to be sprung.
2415 Useful in conjunction with
2417 .REG .o Current page offset.
2418 .REG .p Current page length.
2420 The number of the next page: either the value set by a
2422 request, or the number of the current page plus\ 1.
2423 .REG .ps The current pointsize in scaled points.
2424 .REG .psr The last-requested pointsize in scaled points.
2426 The number of lines to be right-justified as set by the rj request.
2427 .REG .s Current point size as a decimal fraction.
2429 The last requested pointsize in points as a decimal fraction
2431 .REG .t Distance to the next trap.
2439 A string representation of the current tab settings suitable for use as
2444 The amount of vertical space truncated by the most recently sprung
2445 vertical position trap, or, if the trap was sprung by a
2447 request, minus the amount of vertical motion produced by
2450 In other words, at the point a trap is sprung, it represents the difference
2451 of what the vertical position would have been but for the trap, and what the
2452 vertical position actually is.
2453 Useful in conjunction with the
2457 The value of the parameters set by the first argument of the
2461 The value of the parameters set by the second argument of the
2464 .REG .u Equal to 1 bin fill mode and 0 in nofill mode.
2465 .REG .v Current vertical line spacing.
2466 .REG .V Available vertical resolution in basic units.
2469 if vertical position traps are enabled,
2472 .REG .w Width of previous character.
2474 The sum of the number codes of the currently enabled warnings.
2475 .REG .x The major version number.
2476 .REG .y The minor version number.
2477 .REG .Y The revision number of groff.
2478 .REG .z Name of current diversion.
2481 .\" --------------------------------------------------------------------
2482 .SS "WRITABLE REGISTERS"
2483 .\" --------------------------------------------------------------------
2484 The following registers can be read and written by the user.
2485 They have predefined default values, but these can be modified for
2486 customizing a document.
2489 .REG % Current page number.
2490 .REG c. Current input line number.
2491 .REG ct Character type (set by width function
2493 .REG dl Maximal width of last completed diversion.
2494 .REG dn Height of last completed diversion.
2495 .REG dw Current day of week (1-7).
2496 .REG dy Current day of month (1-31).
2497 .REG hp Current horizontal position at input line.
2499 Lower left x-coordinate (in PostScript units) of a given PostScript
2503 Lower left y-coordinate (in PostScript units) of a given PostScript
2506 .REG ln Output line number.
2507 .REG mo Current month (1-12).
2508 .REG nl Vertical position of last printed text base-line.
2511 but takes account of the heights and depths of characters.
2515 but takes account of the heights and depths of characters.
2517 Depth of string below base line (generated by width function
2520 Right skip width from the center of the last character in the
2524 If greater than 0, the maximum number of objects on the input stack.
2525 If \(<=0 there is no limit, i.e., recursion can continue until virtual
2526 memory is exhausted.
2528 The amount of horizontal space (possibly negative) that should be added
2529 to the last character before a subscript (generated by width function
2532 Height of string above base line (generated by width function
2535 The return value of the
2537 function executed by the last
2541 Upper right x-coordinate (in PostScript units) of a given PostScript
2545 Upper right y-coordinate (in PostScript units) of a given PostScript
2548 .REG year The current year (year 2000 compliant).
2550 Current year minus 1900. For Y2K compliance use register
2555 .\" --------------------------------------------------------------------
2557 .\" --------------------------------------------------------------------
2558 Each warning generated by groff is identified by a name and a code
2559 number. The codes are powers of 2 to allow bit-encoding with a single
2560 integer. There are also names that can be used to refer to groups of
2563 The name associated with a warning is used by the
2568 the number code is used by the
2581 Intended to cover all warnings with traditional macro packages.
2583 In fill mode, lines which could not be broken so that their length was
2584 less than the line length. This is enabled by default.
2586 Non-existent characters. This is enabled by default.
2588 Missing or mismatched closing delimiters.
2594 without an argument when there is no current diversion.
2598 request with no matching
2601 .Warning escape 32768
2602 Unrecognized escape sequence. Then the escape character is ignored.
2603 .Warning font 131072
2604 Non-existent fonts. This is enabled by default.
2606 Illegal escapes in text ignored with the
2608 request. These are conditions that are errors when they occur outside
2611 Use of undefined strings, macros, and diversions. Automatically handled
2612 as empty. Usually, only one warning per name.
2613 .Warning missing 8192
2614 Request that is missing non-optional arguments.
2615 .Warning input 16384
2616 Illegal input character.
2618 Invalid numeric expressions. This is enabled by default.
2620 Out of range arguments.
2622 Use of undefined number register. Automatically defined as having
2623 value 0. Usually, only one warning per name.
2624 .Warning right-brace 4096
2627 where a number was expected.
2629 Meaningless scaling indicators.
2630 .Warning space 65536
2631 Missing space between a request or macro and its argument. Then no
2632 macro is automatically defined. This is enabled by default. This
2633 warning will never occur in compatibility mode.
2635 Dubious syntax in numeric expressions.
2637 Inappropriate use of a tab character (either in an unquoted macro
2638 argument or where a number was expected).
2644 tab(@), box, expand;
2645 c c c | c c c | c c c
2646 R RI CB | R RI CB | R RI CB.
2647 Bit@Code@Warning@Bit@Code@Warning@Bit@Code@Warning
2649 0@1@char@8@256@di@16@65536@space
2650 1@2@number@9@512@mac@17@131072@font
2651 2@4@break@10@1024@reg@18@262144@ig
2652 3@8@delim@11@2048@tab
2653 4@16@el@12@4096@right-brace
2654 5@32@scale@13@8192@missing
2655 6@64@range@14@16384@input
2656 7@128@syntax@15@32768@escape
2660 .\" --------------------------------------------------------------------
2662 .\" --------------------------------------------------------------------
2665 .B compatibility mode
2666 that allows to process roff code written for classical
2668 or for other implementations of roff in a consistent way.
2670 Compatibility mode can be turned on with the
2672 command line option, and turned on or off with the
2674 request. The number register
2678 if compatibility mode is on,
2682 This became necessary because the GNU concept for long names causes some
2690 as defining a string
2696 will interpret this as a call of a macro named
2705 as references to a string or number register called
2710 however, this will normally be interpreted as the start of a long name.
2715 groff will interpret these things in the traditional way, but long names
2718 On the other hand, groff in
2720 does not allow to use the escape sequences
2736 in names of strings, macros, diversions, number registers, fonts or
2737 environments, whereas
2741 escape sequence can be helpful in avoiding these escape sequences in
2744 Fractional pointsizes cause one noteworthy incompatibility.
2750 request ignores scale indicators and so
2756 will set the pointsize to 10 points, whereas in groff native mode the
2757 pointsize will be set to 10 scaled points.
2761 mode, there is a fundamental difference between unformatted input
2762 characters, and formatted output characters.
2763 Everything that affects how an output character will be output is stored
2764 with the character; once an output character has been constructed it is
2765 unaffected by any subsequent requests that are executed, including the
2774 Normally output characters are constructed from input characters at the
2775 moment immediately before the character is added to the current output
2777 Macros, diversions and strings are all, in fact, the same type of object;
2778 they contain lists of input characters and output characters in any
2781 An output character does not behave like an input character for the
2782 purposes of macro processing; it does not inherit any of the special
2783 properties that the input character from which it was constructed might
2785 The following example will make things clearer.
2801 this will be printed as
2803 So each pair of input backslashes
2805 is turned into a single output backslash
2807 and the resulting output backslashes are not interpreted as escape
2808 characters when they are reread.
2811 would interpret them as escape characters when they were reread and
2812 would end up printing a single backslash
2815 The correct way to get a printable
2819 escape sequence. This will always print a single instance of the
2820 current escape character, regardless of whether or not it is used in a
2821 diversion. It will also work in both GNU mode and compatibility mode.
2823 To store an escape sequence in a diversion that will be interpreted when
2824 the diversion is reread, either the traditional
2826 transparent output facility or the
2829 escape sequence can be used.
2831 .\" --------------------------------------------------------------------
2833 .\" --------------------------------------------------------------------
2834 At the moment, the documentation of the groff system is in a state of
2835 change and evolution. It is possible that there are small
2836 inconsistencies between different documents temporarily.
2841 .BR troff (@MAN1EXT@).
2843 .\" --------------------------------------------------------------------
2845 .\" --------------------------------------------------------------------
2846 This document is part of groff, the GNU roff distribution. It was
2847 written by Bernd Warken <bwarken@mayn.de>.
2849 It is distributed under the terms of the FDL (GNU Free Documentation
2850 License) version 1.1 or later. You should have received a copy of the
2851 FDL on your system, it is also available on-line under
2854 .IR http://www.gnu.org/copyleft/fdl.html .
2857 Formerly, the extensions of the groff language were kept in the manual
2859 .BR troff (@MAN1EXT@).
2860 This document contains the essential parts of that documentation, but
2861 the gory details are found in the groff info file.
2863 .\" --------------------------------------------------------------------
2865 .\" --------------------------------------------------------------------
2866 The main source of information for the groff language is the
2871 For a survey of roff and the groff system and further documentation
2873 .BR roff (@MAN7EXT@).
2875 The formatter programs are described in
2876 .BR groff (@MAN1EXT@)
2878 .BR troff (@MAN1EXT@);
2879 a complete of all predefined glyph names can be found in
2880 .BR groff_char (@MAN7EXT@).
2884 documentation is available on-line at
2887 .I http://cm.bell-labs.com/cm/cs/cstr.html
2891 .IR http://www.kohala.com/start/troff/ .