5 This file is part of groff, the GNU roff type-setting system.
7 Copyright (C) 2000, 2001 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 AUTHOR, with no
14 Front-Cover Texts, and with no Back-Cover Texts.
16 A copy of the Free Documentation License is included as a file called
17 FDL in the main directory of the groff source package.
20 .\" --------------------------------------------------------------------
22 .\" --------------------------------------------------------------------
35 .\" a comment macro which does nothing
44 .c text lines in macro definitions or bracketed sections \{...\}
50 . ds @tmp@ \f(CB\$1\fP
56 .als shellcommand option
58 .c --------- characters ---------
61 . ds @tmp@ \f(CB\$1\fP
68 . ds @tmp@ \(oq\f(CB\$1\fP\(cq
75 . ds @tmp@ \(lq\f(CB\$1\fP\(rq
81 .c --------- requests ---------
87 . IP "\f(CB\&\*[@tmp@] \fP\f(CI\&\$*\fP" 10n
92 . ds @tmp@ \f(CB\$1\fP
98 .c --------- macro or function arguments ---------
101 . ds @tmp@ \f(CI\$1\fP
103 . while (\n[.$] >= 2) \{\
104 . as @tmp@ \/\f(CR\$1\fP\f(CI\,\$2\fP
107 . if \n[.$] .as @tmp@ \/\f(CR\$1\fP
112 .c argument followed by a numerical expression
114 . ds @tmp@ \f(CI\$1\fP\|\f(CR\$2\fP
120 .c --------- numerical elements ---------
123 . ds @tmp@ \f(CR\$1\fP
130 . ds @tmp@ \&\$1\ \f(CR\$2\fP
136 .als scaleindicator request
139 . ds @tmp@ \f(CR\$1\fP\f(CB\$2\fP
146 . ds @tmp@ \(oq\f(CB\$1\fP\(cq
152 .c --------- escape sequences ---------
155 . ds @tmp@ \f(CB\(rs\$1[\fP\f(CI\$2\fP\f(CB]\fP
162 . ds @tmp@ \f(CB\(rs\$1(\fP\f(CI\$2\fP
169 . ds @tmp@ \f(CB\(rs\$1\fP\f(CI\$2\fP
176 . ds @tmp@ \f(CB\(rs[\fP\f(CI\$1\fP\f(CB]\fP
183 . ds @tmp@ \f(CB\(rs(\fP\f(CI\$1\fP
190 . ds @tmp@ \f(CB\(rs\$1\fP
197 . ds @tmp@ \f(CB\(rs(\$1\fP
204 . ds @tmp@ \f(CB\(rs[\$1]\fP
210 .c escape sequence synopsis
214 . IP "\f(CB\(rs\&\*[@tmp@]\fP\f(CI\&\$*\fP"
218 .c synopsis for escape sequences with a long name
223 . IP "\f(CB\(rs\&\*[@arg1@][\fP\f(CI\&\*[@arg2@]\fP\f(CB]\&\$*\fP"
228 .c synopsis escape sequence with quoted argument
232 . IP "\f(CB\(rs\&\*[@tmp@]\(cq\fP\f(CI\h'-0.2m'\$*\/\fP\f(CB\(cq\fP"
236 .c synopsis for 2-escapes (special characters)
240 . text \f(CB\(rs(\&\*[@tmp@]\ \ \ \fP\fR\(\*[@tmp@]\fP
246 .c --------- registers ---------
248 .c synopsis for registers
251 . text \&\f(CR\(rsn[\fP\f(CB\$1\fP\f(CR]\fP
256 .als register request
258 .c --------- warnings ---------
262 .c description of warnings
273 .\" --------------------------------------------------------------------
275 .\" --------------------------------------------------------------------
277 .TH GROFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
279 groff \- a short reference for the GNU roff language
281 .\" --------------------------------------------------------------------
283 .\" --------------------------------------------------------------------
287 and is the free implementation of the roff type-setting system.
290 for a survey and the background of the groff system.
292 This document gives only short descriptions of the predefined roff
293 language elements as used in groff.
294 Both the classical features and the groff extensions are provided.
301 is compatible with the classical system and provides proper extensions.
307 could be used as synonyms.
310 slightly tends to refer more to the classical aspects, whereas
312 emphasizes the GNU extensions, and
314 is the general term for the language.
316 This file is only a short version of the complete documentation that is
320 file, which contains more detailed, actual, and concise information.
322 The general syntax for writing groff documents is relatively easy, but
323 writing extensions to the roff language can be a bit harder.
325 The roff language is line-oriented.
326 There are only two kinds of lines, control lines and text lines.
327 The control lines start with a control character, by default a period
331 all other lines are text lines.
334 represent commands, optionally with arguments.
335 They have the following syntax.
336 The leading control character can be followed by a command name;
337 arguments, if any, are separated by blanks from the command name and
338 among themselves, for example,
341 \&\.command_name arg1 arg2
344 For indentation, any number of space or tab characters can be inserted
345 between the leading control character and the command name, but the control
346 character must be on the first position of the line.
349 represent the parts that will be printed.
350 They can be modified by escape sequences, which are recognized by a
353 These are in-line or even in-word formatting elements or functions.
354 Some of these take arguments separated by single quotes
356 others are regulated by a length encoding introduced by an open
359 or enclosed in brackets
364 The roff language provides flexible instruments for writing language
365 extension, such as macros.
366 When interpreting macro definitions, the roff system enters a special
367 operating mode, called the
370 The copy mode behavior can be quite tricky, but there are some rules
371 that ensure a safe usage.
373 Printable backslashes must be denoted as
377 represents the current escape character.
378 To get a backslash glyph, use
381 Double all backslashes.
383 Begin all text lines with the special non-spacing character
386 This does not produce the most efficient code, but it should work as a
388 For better strategies, see the groff info file and
389 .BR groff_tmac (@MAN5EXT@).
391 Reading roff source files is easier, just reduce all double backslashes
392 to a single one in all macro definitions.
394 .\" --------------------------------------------------------------------
396 .\" --------------------------------------------------------------------
397 The roff language elements add formatting information to a text file.
398 The fundamental elements are predefined commands and variables that make
399 roff a full-blown programming language.
401 There are two kinds of roff commands, possibly with arguments.
403 are written on a line of their own starting with a dot
409 are in-line functions and in-word formatting elements starting with a
413 The user can define her own formatting commands using the
415 request. These commands are called
417 but they are used exactly like requests. Macro packages are pre-defined
418 sets of macros written in the groff language.
419 A user's possibilities to create escape sequences herself is very
420 limited, only special characters can be mapped.
422 The groff language provides several kinds of variables with
423 different interfaces.
424 There are pre-defined variables, but the user can define her own
428 variables store character sequences.
429 They are set with the
431 request and retrieved by the
436 variables can store numerical values, numbers with a scale unit, and
437 occasionally string-like objects.
438 They are set with the
440 request and retrieved by the
445 allow the user to temporarily store global formatting parameters like
446 line length, font size, etc. for later reuse.
452 are identified either by a name or by an internal number.
453 The current font is chosen by the
458 Each device has special fonts, but the following fonts are available for
461 is the standard font Roman.
470 is everywhere available, but on text devices, it is displayed as an
471 underlined Roman font.
472 For the graphical output devices, there exist constant-width pendants of
478 On text devices, all characters have a constant width anyway.
480 Moreover, there are some advanced roff elements.
483 stores information into a macro for later usage.
486 is a positional condition like a certain number of lines from page top
487 or in a diversion or in the input.
488 Some action can be prescribed to be run automatically when the condition
491 More detailed information can be found in the groff info file.
493 .\" --------------------------------------------------------------------
494 .SH "CONTROL CHARACTERS"
495 .\" --------------------------------------------------------------------
496 There is a small set of characters that have a special controlling task
497 in certain conditions.
500 A dot is only special at the beginning of a line or after the
501 condition in the requests
507 There it is the control character that introduces a request (or macro).
508 The special behavior can be delayed by using the
513 request, the control character can be set to a different character,
516 a non-special character.
518 In all other positions, it just means a dot character.
519 In text paragraphs, it is advantageous to start each sentence at a line
523 The single quote has two controlling tasks. At the beginning of a line
524 and in the conditional requests it is the non-breaking control
526 That means that it introduces a request like the dot, but with the
527 additional property that this request doesn't cause a linebreak.
530 request, the non-break control character can be set to a different
533 As a second task, it is the most commonly used argument separator in
534 some functional escape sequences (but any pair of characters not part
535 of the argument will work).
536 In all other positions, it denotes the single quote or apostrophe
538 Groff provides a printable representation with the
543 The double quote is used to enclose arguments in requests and macros. In
548 requests, a leading double quote in the argument will be stripped off,
549 making everything else afterwards the string to be defined (enabling leading
551 The escaped double quote
553 introduces a comment.
554 Otherwise, it is not special.
555 Groff provides a printable representation with the
560 The backslash usually introduces an escape sequence (this can be
564 A printed version of the escape character is the
566 escape; a backslash glyph can be obtained by
570 The open parenthesis is only special in escape sequences when
571 introducing an escape name or argument consisting of exactly two
573 In groff, this behavior can be replaced by the \f(CB[]\fP construct.
576 The opening bracket is only special in groff escape sequences; there it
577 is used to introduce a long escape name or long escape argument.
578 Otherwise, it is non-special, e.g. in macro calls.
581 The closing bracket is only special in groff escape sequences; there it
582 terminates a long escape name or long escape argument.
583 Otherwise, it is non-special.
586 Space characters are only functional characters. They separate the
587 arguments in requests or macros, and the words in text lines.
588 They are subject to groff's horizontal spacing calculations.
589 To get a defined space width, escape sequences like
591 (this is the escape character followed by a space),
598 In text paragraphs, newlines mostly behave like space characters.
599 Continuation lines can be specified by an escaped newline, i.e., by
600 specifying a backslash
602 as the last character of a line.
604 If a tab character occurs during text the interpreter makes a horizontal
605 jump to the next pre-defined tab position.
606 There is a sophisticated interface for handling tab positions.
608 .\" --------------------------------------------------------------------
609 .SH "NUMERICAL EXPRESSIONS"
610 .\" --------------------------------------------------------------------
613 is a signed or unsigned integer or float with or without an appended
617 is a one-character abbreviation for a unit of measurement.
618 A number followed by a scale indicator signifies a size value.
619 By default, numerical values do not have a scale indicator, i.e., they are
622 The roff language defines the following scale indicators.
631 P@Pica\ \(eq\ 1/6\ inch
632 p@Point\ \(eq\ 1/72\ inch
634 Em\ \(eq\ \fRthe font size in points (width of letter `\f(CRm\fR')
636 M@100th \fRof an \f(CREm
638 u@\fRBasic unit for actual output device
639 v@\fRVertical line space in basic units
641 scaled point\ \(eq\ 1/\f(CIsizescale\fR of a point (defined in
642 font \fIDESC\fP file)
648 .B Numerical expressions
649 are combinations of the numerical values defined above with
650 the arithmetical operators
657 the comparative operators
665 the logical operators
679 added the following operators for numerical expressions:
686 e1\f(CB>?\fPe2@The maximum of \f(CIe1\fP and \f(CIe2\fP.
687 e1\f(CB<?\fPe2@The minimum of \f(CIe1\fP and \f(CIe2\fP.
688 \f(CB(\fPc\f(CB;\fPe\f(CB)@T{
689 Evaluate \f(CIe\fP using \f(CIc\fP as the default scaling
696 For details see the groff info file.
698 .\" --------------------------------------------------------------------
700 .\" --------------------------------------------------------------------
702 occur in tests raised by the
708 The following table characterizes the different types of conditions.
716 A numerical expression \f(CIN\fP yields true if its value
720 True if the value of \f(CIN\fP is\ \f(CR\(<=0\fP.
722 \&'\f(CIs1\fP'\f(CIs2\fP'@T{
723 True if string\ \f(CIs1\fP is identical to string\ \f(CIs2\fP.
725 !'\f(CIs1\fP'\f(CIs2\fP'@T{
726 True if string\ \f(CIs1\fP is not identical to string\ \f(CIs2\fP.
729 True if there is a character\ \f(CIch\fP available.
732 True if there is a string, macro, diversion, or request
735 e@Current page number is even.
736 o@Current page number is odd.
737 n@Formatter is \fBnroff\fP.
739 True if there is a register named \f(CIreg\fP.
741 t@Formatter is \fBtroff\fR.
747 .\" --------------------------------------------------------------------
749 .\" --------------------------------------------------------------------
750 This section provides a short reference for the predefined requests.
751 In groff, request and macro names can be arbitrarily long.
752 No bracketing or marking of long names is needed.
754 Most requests take one or more arguments.
755 The arguments are separated by space characters (no tabs!); there is no
756 inherent limit for their length or number.
757 An argument can be enclosed by a pair of double quotes: This is very handy
758 if an argument contains space characters, e.g.,
759 .argument "\(dqarg\ with\ space\(dq"
760 denotes a single argument.
762 Some requests have optional arguments with a different behaviour.
763 Not all of these details are outlined here.
764 Refer to the groff info file for all details.
766 In the following request specifications, most argument names were chosen
768 Only the following denotations need clarification.
775 c@denotes a single character.
777 a font either specified as a font name or a font number.
780 all characters up to the end of the line or within \f(CB\(rs{\fP
784 is a numerical expression that evaluates to an integer value.
787 is an arbitrary numerical expression, signed or unsigned.
790 has three meanings depending on its sign, described below.
796 If an expression defined as
800 sign the resulting value of the expression will be added to an already
801 existing value inherent to the related request, e.g. adding to a number
803 If the expression starts with a
805 the value of the expression will be subtracted from the request value.
809 replaces the existing value directly.
810 To assign a negative number either prepend\ \c
812 or enclose the negative number in parentheses.
814 .\" --------------------------------------------------------------------
815 .SS "REQUEST SHORT REFERENCE"
816 .\" --------------------------------------------------------------------
820 Empty line, ignored. Useful for structuring documents.
822 .REQ .\(rs\(dq anything
823 Complete line is a comment.
828 on standard error, exit program.
831 Begin line adjustment for output lines in current adjust mode.
834 Start line adjustment in mode
836 (\f(CIc\fP\f(CR\|\^\(eq\|l,r,b,n\fP).
843 (\f(CIc\fP\f(CR\|\^\(eq\|l,i,I,a,A\fP).
845 .REQ .aln alias register
846 Create alias name for
849 .REQ .als alias object
850 Create alias name for request, string, macro, or diversion
870 but with compatibility mode switched off during macro expansion.
875 but with compatibility mode switched off during macro expansion.
877 .REQ .as stringvar anything
881 .argument stringvar .
883 .REQ .asciify diversion
884 Unformat ASCII characters, spaces, and some escape sequences in
885 .argument diversion .
888 Print a backtrace of the input on stderr.
898 Embolden Special Font
904 Unset the blank line macro.
907 Set the blank line macro to
911 End current diversion.
916 omitting a partially filled line.
919 End current diversion.
924 omitting a partially filled line.
927 Eject current page and begin new page.
930 Eject current page; next page number
937 Break and spread output line.
942 Break out of a while loop.
945 Reset no-break control character to
949 Set no-break control character to
953 Reset control character to
957 Set control character to
961 Center the next input line.
969 Copy contents of file
971 unprocessed to stdout or to the diversion.
973 .REQ .cflags mode c1 c2 ...
989 .REQ .char c anything
996 Chop the last character off macro, string, or diversion
1004 Finish the current iteration of a while loop.
1007 Enable compatibility mode.
1012 is zero disable compatibility mode, otherwise enable it.
1015 Set constant character width mode for
1023 Continuous underline in nroff, like
1028 End current diversion.
1031 Divert and append to
1051 but with compatibility mode switched off during macro expansion.
1056 but with compatibility mode switched off during macro expansion.
1059 Define or redefine a macro whose name is contained in the string register
1066 Define or redefine a macro indirectly.
1070 are string registers whose contents are interpolated for the macro name
1071 and the end macro, respectively.
1074 End current diversion.
1083 with compatibility mode disabled.
1085 .REQ .ds stringvar anything
1089 .argument anything .
1092 Set diversion trap to position
1094 (default scale indicator\ \c
1095 .scaleindicator v ).
1098 Reset escape character to
1102 Set escape character to
1106 Restore escape character saved with
1110 Save current escape character.
1113 Else part for if-else (\c
1120 will be run after the end of input.
1123 Turn off escape character mechanism.
1126 Switch to previous environment.
1129 Push down environment number or name
1134 Copy the contents of environment
1136 to the current environment.
1137 No pushing or popping.
1140 Exit from roff processing.
1143 Return to previous font family.
1146 Set the current font family to
1150 Disable field mechanism.
1153 Set field delimiter to
1155 and pad character to space.
1157 Set field delimiter to
1159 and pad character to
1166 Flush output buffer.
1174 .REQ .fp n internal external
1175 Mount font with long
1182 .REQ .fspecial font s1 s2...
1183 When the current font is
1192 Return to previous font.
1196 Change to font name or number
1202 .REQ .ftr font1 font2
1209 Remove additional hyphenation indicator character.
1212 Set up additional hyphenation indicator character\ \c
1215 .REQ .hcode c1 code1 c2 code2 ...
1216 Set the hyphenation code of character
1227 Set the current hyphenation language to
1231 Set the maximum number of consecutive hyphenated lines to
1235 Read hyphenation patterns from
1241 with exceptional hyphenation.
1244 Switch to hyphenation mode
1248 Set the hyphenation margin to
1250 (default scale indicator\ \c
1251 .scaleindicator m ).
1254 Set the hyphenation space to
1257 .REQ .ie cond anything
1265 .REQ .if cond anything
1269 .argument anything ;
1270 otherwise do nothing.
1282 Change to previous indent value.
1285 Change indent according to
1287 (default scale indicator\ \c
1288 .scaleindicator m ).
1291 Set an input-line count trap at position
1295 Enable pairwise kerning.
1300 is zero, disable pairwise kerning, otherwise enable it.
1303 Remove leader repetition character.
1306 Set leader repetition character to\ \c
1309 .REQ .length register anything
1310 Write the length of the string
1313 .argument register .
1316 Enable line-tabs mode (i.e., calculate tab positions relative to output
1322 is zero, disable line-tabs mode, otherwise enable it.
1325 Set input line number to
1335 Change to previous line length.
1338 Set line length according to
1341 .scalednumber 6.5 i ,
1342 default scale indicator\ \c
1343 .scaleindicator m ).
1346 Change to the previous value of additional intra-line skip.
1349 Set additional intra-line skip value to
1353 blank lines are inserted after each text output line.
1356 Length of title (default scale indicator\ \c
1357 .scaleindicator m ).
1360 Margin character off.
1365 after each text line at actual distance from right margin.
1368 Set margin character to
1372 from right margin (default scale indicator\ \c
1373 .scaleindicator m ).
1376 Mark current vertical position in
1377 .argument register .
1380 The same as the .so request except that
1382 is searched in the tmac directories.
1385 No output-line adjusting.
1388 Need a one-line vertical space.
1393 vertical space (default scale indicator\ \c
1394 .scaleindicator v ).
1397 No filling or adjusting of output-lines.
1405 .REQ .nm \(+-N M S I
1406 In line number mode, set number, multiple, spacing, and indent.
1409 Do not number next line.
1418 .argument anything .
1420 .REQ .nr register \(+-N M
1429 Make the built-in condition
1436 Turn no-space mode on.
1441 .REQ .open stream filename
1444 for writing and associate the stream named
1448 .REQ .opena stream filename
1454 Output vertical distance that was saved by the
1459 Reset page number character to\ \c
1463 Page number character.
1471 Set page length to default
1472 .scalednumber 11 i .
1473 The current page length is stored in
1477 Change page length to
1479 (default scale indicator\ \c
1480 .scaleindicator v ).
1483 Print macro names and sizes (number of blocks of 128 bytes).
1486 Print only total of sizes of macros (number of 128 bytes blocks).
1493 Print the names and contents of all currently defined number registers
1497 Change to previous page offset. The current page offset is available in
1505 Return to previous point-size.
1511 Get the bounding box of a PostScript image
1512 .argument filename .
1515 This behaves like the
1517 request except that input comes from the standard output of
1521 Print the names and positions of all traps (not including input line
1522 traps and diversion traps) on stderr.
1524 .REQ .rchar c1 c2...
1525 Remove the definitions of characters
1534 Return from a macro.
1537 Right justify the next
1542 Remove request, macro, or string
1546 Rename request, macro, or string
1559 .argument register .
1562 Restore spacing; turn no-space mode off.
1567 to marked vertical place (default scale indicator\ \c
1568 .scaleindicator v ).
1571 Reset soft hyphen character to
1575 Set the soft hyphen character to
1579 In a macro, shift the arguments by
1584 Include source file.
1587 Skip one line vertically.
1590 Space vertical distance
1592 up or down according to sign of
1594 (default scaling indicator\ \c
1595 .scaleindicator v ).
1597 .REQ .special s1 s2 ...
1601 etc. are special and will be searched for characters not in the current font.
1604 Space-character size set to
1606 of the spacewidth in the current font.
1609 Space-character size set to
1611 and sentence space size set to
1613 of the spacewidth in the current font (\f(CR\(eq1/3 em\fP).
1621 .REQ .substring register n1 n2
1622 Replace the string in
1624 with the substring defined by the indices
1635 Save the vertical distance
1637 for later output with
1641 .REQ .sy command-line
1643 .argument command-line .
1646 Set tabs after every position that is a multiple of
1648 (default scaling indicator\ \c
1649 .scaleindicator m ).
1650 .REQ .ta n1 n2 ... nn \f(CBT\fP r1 r2 ... rn
1651 Set tabs at positions
1662 .argument nn + rn + r1 ,
1663 .argument nn + rn + r2 ,
1665 .argument nn + rn + rn ,
1669 .\"Restore internally saved tab positions.
1672 .\"Save tab positions internally.
1675 Remove tab repition character.
1677 Set tab repetition character to\ \c
1681 Temporary indent next line (default scaling indicator\ \c
1682 .scaleindicator m ).
1684 .REQ .tkf font s1 n1 s2 n2
1685 Enable track kerning for
1688 .REQ .tl \f(CB\(cq\fPleft\f(CB\(cq\fPcenter\f(CB\(cq\fPright\f(CB\(cq\fP
1694 on terminal (UNIX standard message output).
1699 on terminal (UNIX standard message output), allowing leading whitespace if
1703 (which will be stripped off).
1708 without emitting a final newline.
1721 Transparently output the contents of file
1722 .argument filename .
1725 This is the same as the
1727 request except that the translations do not apply to text that is
1728 transparently throughput into a diversion with
1732 Make the built-in condition
1739 Underline font set to
1741 (to be switched to by
1745 Underline (italicize in troff)
1749 .REQ .unformat diversion
1750 Unformat space characters and tabs, preserving font information in
1751 .argument diversion .
1753 Enable vertical position traps if
1755 is non-zero, disable them otherwise.
1758 Change to previous vertical base line spacing.
1761 Set vertical base line spacing to
1764 .scalednumber 12 p .
1767 Set warnings code to
1771 Set location trap; negative means from page bottom.
1773 .REQ .while cond anything
1780 .REQ .write stream anything
1788 Besides these standard groff requests, there might be further macro
1790 They can originate from a macro package (see
1791 .BR roff (@MAN7EXT@)
1792 for an overview) or from a preprocessor.
1794 Preprocessor macros are easy to be recognized. They enclose their code
1795 into a pair of characteristic macros.
1798 box, center, tab (@);
1801 preprocessor@start macro@ end macro
1808 soelim@\fInone@\fInone
1813 .\" --------------------------------------------------------------------
1814 .SH "ESCAPE SEQUENCES"
1815 .\" --------------------------------------------------------------------
1817 Escape sequences are in-line language elements usually introduced by
1820 and followed by an escape name and sometimes by a required argument.
1821 Input processing is continued directly after the escaped character or
1822 the argument resp. without an intervening separation character.
1823 So there must be a way to determine the end of the escape name and the end
1826 This is done by enclosing names (escape name and arguments consisting of
1827 a variable name) by a pair of brackets
1829 and constant arguments (number expressions and characters) by apostrophes
1831 .IR \(cqconstant\(cq .
1833 There are abbreviations for short names.
1834 Two character escape names can be specified by an opening parenthesis like
1836 without a closing counterpart.
1837 And all one-character names different from the special characters
1841 can even be specified without a marker in the form
1844 Constant arguments of length
1846 can omit the marker apostrophes, too, but there is no two-character
1849 While 1-character escape sequences are mainly used for in-line functions
1850 and system related tasks, the 2-letter names following the
1852 construct are used for special characters predefined by the roff system.
1853 Names with more than two characters
1855 mostly denote user defined named characters (see the
1859 .\" --------------------------------------------------------------------
1860 .SS "SINGLE CHARACTER ESCAPES"
1861 .\" --------------------------------------------------------------------
1865 .\" --------- comments ---------
1868 Beginning of a comment.
1869 Everything up to the end of the line is ignored.
1872 Everything up to and including the next newline is ignored.
1873 This is interpreted in copy mode.
1876 except the ignoring of the terminating newline.
1878 .\" --------- strings ---------
1881 The string stored in the string variable with 1-character name
1885 The string stored in the string variable with 2-character name
1889 The string stored in the string variable with arbitrary length name
1890 .argument stringvar .
1892 .\" --------- macro arguments ---------
1895 The name by which the current macro was invoked. The
1897 request can make a macro have more than one name.
1900 Macro argument with 1-place number
1904 is a digit between 1 and 9.
1907 Macro argument with 2-digit number
1911 Macro argument with number
1915 is a numerical expression evaluating to an integer \(>=1.
1918 In a macro, the concatenation of all the arguments separated by spaces.
1921 In a macro, the concatenation of all the arguments with each surrounded
1922 by double quotes, and separated by spaces.
1924 .\" --------- escaped characters ---------
1927 reduces to a single backslash; useful to delay its interpretation as
1928 escape character in copy mode.
1929 For a printable backslash, use
1933 The acute accent \(aa; same as
1935 Unescaped: apostrophe, right quotation mark, single quote (ASCII 0x27).
1938 The grave accent \(ga; same as
1940 Unescaped: left quote, backquote (ASCII 0x60).
1943 The \- sign in the current font.
1946 An uninterpreted dot (period), even at start of line.
1949 Default optional hyphenation character.
1952 Transparent line indicator.
1954 .ESC ? anything\fB?\fP
1955 In a diversion, this will transparently embed
1959 is read in copy mode.
1960 See also the escape sequences
1966 .\" --------- spacing ---------
1969 Unpaddable space-size space character (no line break).
1975 1/6\ em narrow space character; zero width in nroff.
1978 1/12\ em half-narrow space character; zero width in nroff.
1981 Non-printable, zero width character.
1986 except that it behaves like a character declared with the cflags
1987 request to be transparent for the purposes of end of sentence
1991 Increases the width of the preceding character so that the spacing
1992 between that character and the following character will be correct if
1993 the following character is a roman character.
1996 Modifies the spacing of the following character so that the spacing
1997 between that character and the preceding character will correct if the
1998 preceding character is a roman character.
2001 Unbreakable space that stretches like a normal inter-word space when a
2005 Inserts a zero-width break point (similar to
2007 but without a soft hyphen character).
2010 Ignored newline, for continuation lines.
2012 .\" --------- structuring ---------
2015 Begin conditional input.
2018 End conditional input.
2020 .\" --------- longer escape names ---------
2023 The special character with 2-character name
2026 .BR "SPECIAL CHARACTERS" .
2029 The named character with arbitrary length name
2032 .\" --------- alphabetical escapes ---------
2035 Non-interpreted leader character.
2040 is acceptable as a name of a string, macro, diversion, register,
2041 environment or font it expands to
2048 Bracket building function.
2053 is acceptable as a valid numeric expression it expands to
2060 Interrupt text processing.
2063 The character called
2067 but compatible to other roff versions.
2070 Forward (down) 1/2 em vertical unit (1/2 line in nroff).
2073 Draw a graphical element defined by the characters in
2075 see groff info file for details.
2078 Printable version of the current escape character.
2081 Equivalent to an escape character, but is not interpreted in copy-mode.
2084 Change to font with 1-character name or 1-digit number
2088 Change to font with 2-characer name or 2-digit number
2092 Change to font with arbitrary length name or number expression
2096 Return format of register with name
2106 Local horizontal motion; move right
2111 Set height of current font to
2115 Mark horizontal input place in register with arbitrary length name
2123 Horizontal line drawing function (optionally using character
2127 Vertical line drawing function (optionally using character
2131 The numerical value stored in the register variable with the 1-character
2136 The numerical value stored in the register variable with the 2-character
2141 The numerical value stored in the register variable with arbitrary
2146 Typeset the character with code
2148 in the current font, no special fonts are searched. Useful for adding
2149 characters to a font using the
2154 Overstrike characters
2161 Break and spread output line.
2164 Reverse 1\ em vertical motion (reverse line in nroff).
2173 Set the point size to
2175 scaled points. Note the alternative forms
2176 .BI \(rss \(+- [ N ]\c
2178 .BI \(rss' \(+-N '\c
2180 .BI \(rss \(+- ' N '\c
2183 .BI \(rss \(+- ( xy\c
2196 Non-interpreted horizontal tab.
2199 Reverse (up) 1/2 em vertical motion (1/2 line in nroff).
2202 Local vertical motion; move down
2207 The contents of the environment variable
2215 The width of the character sequence
2219 Extra line-space function (negative before, positive after).
2224 as device control function.
2227 Output string variable or macro
2229 uninterpreted as device control function.
2238 with zero width (without spacing).
2243 and then restore the horizontal and vertical position;
2245 may not contain tabs or leaders.
2248 The escape sequences
2260 are interpreted in copy mode.
2262 Escape sequences starting with
2266 do not represent single character escape sequences, but introduce escape
2267 names with two or more characters.
2269 If a backslash is followed by a character that does not constitute a
2270 defined escape sequence the backslash is silently ignored and the
2271 character maps to itself.
2273 .\" --------------------------------------------------------------------
2274 .SS "SPECIAL CHARACTERS"
2275 .\" --------------------------------------------------------------------
2276 Common special characters are predefined by escape sequences of the form
2282 Some of these exist in the usual font while most of them are only
2283 available in the special font. Below you'll find a selection of the most
2284 important glyphs; a complete list can be found in
2285 .BR groff_char (@MAN7EXT@).
2293 .ESc dd Double dagger
2298 .ESc rg Registered sign
2299 .ESc sc Section sign
2300 .ESc ul Underline character
2302 .ESc >= Larger or equal
2303 .ESc <= Less or equal
2307 .ESc +- Plus-minus sign
2311 .\" --------------------------------------------------------------------
2313 .\" --------------------------------------------------------------------
2314 Registers are variables that store a value.
2315 In groff, most registers store numerical values (see section
2316 .B NUMERICAL EXPRESSIONS
2317 above), but some can also hold a string value.
2319 Each register is given a name.
2320 Arbitrary registers can be defined and set with the request
2322 .argument register .
2324 The value stored in a register can be retrieved by the escape sequences
2328 Most useful are predefined registers.
2329 In the following the notation
2331 is used to refer to a register called
2333 to make clear that we speak about registers.
2334 Please keep in mind that the
2336 decoration is not part of the register name.
2338 .\" --------------------------------------------------------------------
2339 .SS "READ-ONLY REGISTERS"
2340 .\" --------------------------------------------------------------------
2341 The following registers have predefined values that should not be
2342 modified by the user (usually, registers starting with a dot a read-only).
2343 Mostly, they provide information on the current settings or store results
2347 .REG .$ Number of arguments in the current macro.
2349 Post-line extra line-space most recently utilized using
2362 .REG .c Current input line number.
2363 .REG .C 1 if compatibility mode is in effect, 0 otherwise.
2365 The depth of the last character added to the current environment.
2366 It is positive if the character extends below the baseline.
2368 The number of lines remaining to be centered, as set by the
2372 The height of the last character added to the current environment.
2373 It is positive if the character extends above the baseline.
2375 The skew of the last character added to the current environment.
2376 The skew of a character is how far to the right of the center of a character
2377 the center of an accent over that character should be placed.
2379 Current vertical place in current diversion; equal to register
2381 .REG .ev The name or number of the current environment (string-valued).
2382 .REG .f Current font number.
2383 .REG .fam The current font family (string-valued).
2384 .REG .fp The number of the next free font position.
2386 Always 1 in GNU troff.
2387 Macros should use it to test if running under groff.
2388 .REG .h Text base-line high-water mark on current page or diversion.
2389 .REG .H Available horizontal resolution in basic units.
2391 The current hyphenation language as set by the
2395 The number of immediately preceding consecutive hyphenated lines.
2397 The maximum allowed number of consecutive hyphenated lines, as set by
2402 The current hyphenation flags (as set by the
2406 The current hyphenation margin (as set by the
2410 The current hyphenation space (as set by the
2413 .REG .i Current ident.
2414 .REG .in The indent that applies to the current output line.
2416 Positive if last output line contains
2420 if pairwise kerning is enabled,
2423 .REG .l Current line length.
2425 The current ligature mode (as set by the
2429 The current line-tabs mode (as set by the
2432 .REG .ll The line length that applies to the current output line.
2434 The title length (as set by the
2437 .REG .n Length of text portion on previous output line.
2439 The amount of space that was needed in the last
2441 request that caused a trap to be sprung.
2442 Useful in conjunction with
2446 if in no-space mode,
2449 .REG .o Current page offset.
2450 .REG .p Current page length.
2452 The number of the next page: either the value set by a
2454 request, or the number of the current page plus\ 1.
2455 .REG .ps The current pointsize in scaled points.
2456 .REG .psr The last-requested pointsize in scaled points.
2458 The number of lines to be right-justified as set by the rj request.
2459 .REG .s Current point size as a decimal fraction.
2461 The last requested pointsize in points as a decimal fraction
2463 .REG .t Distance to the next trap.
2471 A string representation of the current tab settings suitable for use as
2476 The amount of vertical space truncated by the most recently sprung
2477 vertical position trap, or, if the trap was sprung by a
2479 request, minus the amount of vertical motion produced by
2482 In other words, at the point a trap is sprung, it represents the difference
2483 of what the vertical position would have been but for the trap, and what the
2484 vertical position actually is.
2485 Useful in conjunction with the
2489 The value of the parameters set by the first argument of the
2493 The value of the parameters set by the second argument of the
2496 .REG .u Equal to 1 bin fill mode and 0 in nofill mode.
2497 .REG .v Current vertical line spacing.
2498 .REG .V Available vertical resolution in basic units.
2501 if vertical position traps are enabled,
2504 .REG .w Width of previous character.
2506 The sum of the number codes of the currently enabled warnings.
2507 .REG .x The major version number.
2508 .REG .y The minor version number.
2509 .REG .Y The revision number of groff.
2510 .REG .z Name of current diversion.
2513 .\" --------------------------------------------------------------------
2514 .SS "WRITABLE REGISTERS"
2515 .\" --------------------------------------------------------------------
2516 The following registers can be read and written by the user.
2517 They have predefined default values, but these can be modified for
2518 customizing a document.
2521 .REG % Current page number.
2522 .REG c. Current input line number.
2523 .REG ct Character type (set by width function
2525 .REG dl Maximal width of last completed diversion.
2526 .REG dn Height of last completed diversion.
2527 .REG dw Current day of week (1-7).
2528 .REG dy Current day of month (1-31).
2529 .REG hp Current horizontal position at input line.
2531 Lower left x-coordinate (in PostScript units) of a given PostScript
2535 Lower left y-coordinate (in PostScript units) of a given PostScript
2538 .REG ln Output line number.
2539 .REG mo Current month (1-12).
2540 .REG nl Vertical position of last printed text base-line.
2543 but takes account of the heights and depths of characters.
2547 but takes account of the heights and depths of characters.
2549 Depth of string below base line (generated by width function
2552 Right skip width from the center of the last character in the
2556 If greater than 0, the maximum number of objects on the input stack.
2557 If \(<=0 there is no limit, i.e., recursion can continue until virtual
2558 memory is exhausted.
2560 The amount of horizontal space (possibly negative) that should be added
2561 to the last character before a subscript (generated by width function
2564 Height of string above base line (generated by width function
2567 The return value of the
2569 function executed by the last
2573 Upper right x-coordinate (in PostScript units) of a given PostScript
2577 Upper right y-coordinate (in PostScript units) of a given PostScript
2580 .REG year The current year (year 2000 compliant).
2582 Current year minus 1900. For Y2K compliance use register
2587 .\" --------------------------------------------------------------------
2589 .\" --------------------------------------------------------------------
2590 Each warning generated by groff is identified by a name and a code
2591 number. The codes are powers of 2 to allow bit-encoding with a single
2592 integer. There are also names that can be used to refer to groups of
2595 The name associated with a warning is used by the
2600 the number code is used by the
2613 Intended to cover all warnings with traditional macro packages.
2615 In fill mode, lines which could not be broken so that their length was
2616 less than the line length. This is enabled by default.
2618 Non-existent characters. This is enabled by default.
2620 Missing or mismatched closing delimiters.
2626 without an argument when there is no current diversion.
2630 request with no matching
2633 .Warning escape 32768
2634 Unrecognized escape sequence. Then the escape character is ignored.
2635 .Warning font 131072
2636 Non-existent fonts. This is enabled by default.
2638 Illegal escapes in text ignored with the
2640 request. These are conditions that are errors when they occur outside
2643 Use of undefined strings, macros, and diversions. Automatically handled
2644 as empty. Usually, only one warning per name.
2645 .Warning missing 8192
2646 Request that is missing non-optional arguments.
2647 .Warning input 16384
2648 Illegal input character.
2650 Invalid numeric expressions. This is enabled by default.
2652 Out of range arguments.
2654 Use of undefined number register. Automatically defined as having
2655 value 0. Usually, only one warning per name.
2656 .Warning right-brace 4096
2659 where a number was expected.
2661 Meaningless scaling indicators.
2662 .Warning space 65536
2663 Missing space between a request or macro and its argument. Then no
2664 macro is automatically defined. This is enabled by default. This
2665 warning will never occur in compatibility mode.
2667 Dubious syntax in numeric expressions.
2669 Inappropriate use of a tab character (either in an unquoted macro
2670 argument or where a number was expected).
2676 tab(@), box, expand;
2677 c c c | c c c | c c c
2678 R RI CB | R RI CB | R RI CB.
2679 Bit@Code@Warning@Bit@Code@Warning@Bit@Code@Warning
2681 0@1@char@8@256@di@16@65536@space
2682 1@2@number@9@512@mac@17@131072@font
2683 2@4@break@10@1024@reg@18@262144@ig
2684 3@8@delim@11@2048@tab
2685 4@16@el@12@4096@right-brace
2686 5@32@scale@13@8192@missing
2687 6@64@range@14@16384@input
2688 7@128@syntax@15@32768@escape
2692 .\" --------------------------------------------------------------------
2694 .\" --------------------------------------------------------------------
2697 .B compatibility mode
2698 that allows to process roff code written for classical
2700 or for other implementations of roff in a consistent way.
2702 Compatibility mode can be turned on with the
2704 command line option, and turned on or off with the
2706 request. The number register
2710 if compatibility mode is on,
2714 This became necessary because the GNU concept for long names causes some
2722 as defining a string
2728 will interpret this as a call of a macro named
2737 as references to a string or number register called
2742 however, this will normally be interpreted as the start of a long name.
2747 groff will interpret these things in the traditional way, but long names
2750 On the other hand, groff in
2752 does not allow to use the escape sequences
2768 in names of strings, macros, diversions, number registers, fonts or
2769 environments, whereas
2773 escape sequence can be helpful in avoiding these escape sequences in
2776 Fractional pointsizes cause one noteworthy incompatibility.
2782 request ignores scale indicators and so
2788 will set the pointsize to 10 points, whereas in groff native mode the
2789 pointsize will be set to 10 scaled points.
2793 mode, there is a fundamental difference between unformatted input
2794 characters, and formatted output characters.
2795 Everything that affects how an output character will be output is stored
2796 with the character; once an output character has been constructed it is
2797 unaffected by any subsequent requests that are executed, including the
2806 Normally output characters are constructed from input characters at the
2807 moment immediately before the character is added to the current output
2809 Macros, diversions and strings are all, in fact, the same type of object;
2810 they contain lists of input characters and output characters in any
2813 An output character does not behave like an input character for the
2814 purposes of macro processing; it does not inherit any of the special
2815 properties that the input character from which it was constructed might
2817 The following example will make things clearer.
2833 this will be printed as
2835 So each pair of input backslashes
2837 is turned into a single output backslash
2839 and the resulting output backslashes are not interpreted as escape
2840 characters when they are reread.
2843 would interpret them as escape characters when they were reread and
2844 would end up printing a single backslash
2847 The correct way to get a printable
2851 escape sequence. This will always print a single instance of the
2852 current escape character, regardless of whether or not it is used in a
2853 diversion. It will also work in both GNU mode and compatibility mode.
2855 To store an escape sequence in a diversion that will be interpreted when
2856 the diversion is reread, either the traditional
2858 transparent output facility or the
2861 escape sequence can be used.
2863 .\" --------------------------------------------------------------------
2865 .\" --------------------------------------------------------------------
2866 At the moment, the documentation of the groff system is in a state of
2867 change and evolution. It is possible that there are small
2868 inconsistencies between different documents temporarily.
2873 .BR troff (@MAN1EXT@).
2875 .\" --------------------------------------------------------------------
2877 .\" --------------------------------------------------------------------
2878 This document is part of groff, the GNU roff distribution. It was
2879 written by Bernd Warken <bwarken@mayn.de>.
2881 It is distributed under the terms of the FDL (GNU Free Documentation
2882 License) version 1.1 or later. You should have received a copy of the
2883 FDL on your system, it is also available on-line under
2886 .IR http://www.gnu.org/copyleft/fdl.html .
2889 Formerly, the extensions of the groff language were kept in the manual
2891 .BR troff (@MAN1EXT@).
2892 This document contains the essential parts of that documentation, but
2893 the gory details are found in the groff info file.
2895 .\" --------------------------------------------------------------------
2897 .\" --------------------------------------------------------------------
2898 The main source of information for the groff language is the
2903 For a survey of roff and the groff system and further documentation
2905 .BR roff (@MAN7EXT@).
2907 The formatter programs are described in
2908 .BR groff (@MAN1EXT@)
2910 .BR troff (@MAN1EXT@);
2911 a complete of all predefined glyph names can be found in
2912 .BR groff_char (@MAN7EXT@).
2916 documentation is available on-line at
2919 .I http://cm.bell-labs.com/cm/cs/cstr.html
2923 .IR http://www.kohala.com/start/troff/ .
2925 .\" Local Variables:
projects / FreeBSD / FreeBSD.git / blob