| blob | 73c91889987a618bad38274d324e7df71fe93e50 |
1 .\" st -*- nroff -*-
2 .ig
3 groff.7
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.
20 ..
21 .
22 .\" --------------------------------------------------------------------
23 .\" Setup
24 .\" --------------------------------------------------------------------
25 .
26 .if n \{\
27 . mso tmac.tty-char
28 . ftr CR R
29 . ftr CI I
30 . ftr CB B
31 .\}
32 .
33 .if '\*[.T]'dvi' \{\
34 . ftr CB CW
35 .\}
36 .
37 .\" a comment macro which does nothing
38 .de c
39 ..
40 .
41 .\" a tab string
42 .ds t "\t
43 .
44 .eo
45 .
46 .c text lines in macro definitions or bracketed sections \{...\}
47 .de text
48 . if 1 \&\$*\&
49 ..
50 .
51 .de option
52 . ds @tmp@ \f(CB\$1\fP
53 . shift 1
54 . text \*[@tmp@]\$*
55 . rm @tmp@
56 ..
57 .
58 .als shellcommand option
59 .
60 .c --------- characters ---------
61 .
62 .de character
63 . ds @tmp@ \f(CB\$1\fP
64 . shift
65 . text \*[@tmp@]\$*
66 . rm @tmp@
67 ..
68 .
69 .de 'char
70 . ds @tmp@ \(oq\f(CB\$1\fP\(cq
71 . shift
72 . text \*[@tmp@]\$*
73 . rm @tmp@
74 ..
75 .
76 .de ''char
77 . ds @tmp@ \(lq\f(CB\$1\fP\(rq
78 . shift
79 . text \*[@tmp@]\$*
80 . rm @tmp@
81 ..
82 .
83 .c --------- requests ---------
84 .
85 .c request synopsis
86 .de REQ
87 . ds @tmp@ \&\$1
88 . shift 1
89 . IP "\f(CB\&\*[@tmp@] \fP\f(CI\&\$*\fP" 10n
90 . rm @tmp@
91 ..
92 .
93 .de request
94 . ds @tmp@ \f(CB\$1\fP
95 . shift 1
96 . text \*[@tmp@]\$*
97 . rm @tmp@
98 ..
99 .
100 .c --------- macro or function arguments ---------
101 .
102 .de argument
103 . ds @tmp@ \f(CI\$1\fP
104 . shift 1
105 . while (\n[.$] >= 2) \{\
106 . as @tmp@ \/\f(CR\$1\fP\f(CI\,\$2\fP
107 . shift 2
108 . \}
109 . if \n[.$] .as @tmp@ \/\f(CR\$1\fP
110 . text \*[@tmp@]
111 . rm @tmp@
112 ..
113 .
114 .c argument followed by a numerical expression
115 .de argterm
116 . ds @tmp@ \f(CI\$1\fP\|\f(CR\$2\fP
117 . shift 2
118 . text \*[@tmp@]\$*
119 . rm @tmp@
120 ..
121 .
122 .c --------- numerical elements ---------
123 .
124 .de number
125 . ds @tmp@ \f(CR\$1\fP
126 . shift 1
127 . text \*[@tmp@]\$*
128 . rm @tmp@
129 ..
130 .
131 .de prefixednumber
132 . ds @tmp@ \&\$1\ \f(CR\$2\fP
133 . shift 2
134 . text \*[@tmp@]\$*
135 . rm @tmp@
136 ..
137 .
138 .als scaleindicator request
139 .
140 .de scalednumber
141 . ds @tmp@ \f(CR\$1\fP\f(CB\$2\fP
142 . shift 2
143 . text \*[@tmp@]\$*
144 . rm @tmp@
145 ..
146 .
147 .de operator
148 . ds @tmp@ \(oq\f(CB\$1\fP\(cq
149 . shift
150 . text \*[@tmp@]\$*
151 . rm @tmp@
152 ..
153 .
154 .c --------- escape sequences ---------
155 .
156 .de esc[arg]
157 . ds @tmp@ \f(CB\(rs\$1[\fP\f(CI\$2\fP\f(CB]\fP
158 . shift 2
159 . text \*[@tmp@]\$*
160 . rm @tmp@
161 ..
162 .
163 .de esc(arg
164 . ds @tmp@ \f(CB\(rs\$1(\fP\f(CI\$2\fP
165 . shift 2
166 . text \*[@tmp@]\$*
167 . rm @tmp@
168 ..
169 .
170 .de escarg
171 . ds @tmp@ \f(CB\(rs\$1\fP\f(CI\$2\fP
172 . shift 2
173 . text \*[@tmp@]\$*
174 . rm @tmp@
175 ..
176 .
177 .de esc[]
178 . ds @tmp@ \f(CB\(rs[\fP\f(CI\$1\fP\f(CB]\fP
179 . shift
180 . text \*[@tmp@]\$*
181 . rm @tmp@
182 ..
183 .
184 .de esc(
185 . ds @tmp@ \f(CB\(rs(\fP\f(CI\$1\fP
186 . shift
187 . text \*[@tmp@]\$*
188 . rm @tmp@
189 ..
190 .
191 .de esc
192 . ds @tmp@ \f(CB\(rs\$1\fP
193 . shift
194 . text \*[@tmp@]\$*
195 . rm @tmp@
196 ..
197 .
198 .de (esc
199 . ds @tmp@ \f(CB\(rs(\$1\fP
200 . shift
201 . text \*[@tmp@]\$*
202 . rm @tmp@
203 ..
204 .
205 .de [esc]
206 . ds @tmp@ \f(CB\(rs[\$1]\fP
207 . shift
208 . text \*[@tmp@]\$*
209 . rm @tmp@
210 ..
211 .
212 .c escape sequence synopsis
213 .de ESC
214 . ds @tmp@ \&\$1
215 . shift 1
216 . IP "\f(CB\(rs\&\*[@tmp@]\fP\f(CI\&\$*\fP"
217 . rm @tmp@
218 ..
219 .
220 .c synopsis for escape sequences with a long name
221 .de ESC[]
222 . ds @arg1@ \&\$1
223 . ds @arg2@ \&\$2
224 . shift 2
225 . IP "\f(CB\(rs\&\*[@arg1@][\fP\f(CI\&\*[@arg2@]\fP\f(CB]\&\$*\fP"
226 . rm @arg1@
227 . rm @arg2@
228 ..
229 .
230 .c synopsis escape sequence with quoted argument
231 . de ESCq
232 . ds @tmp@ \&\$1
233 . shift 1
234 . IP "\f(CB\(rs\&\*[@tmp@]\(cq\fP\f(CI\h'-0.2m'\$*\/\fP\f(CB\(cq\fP"
235 . rm @tmp@
236 ..
237 .
238 .c synopsis for 2-escapes (special characters)
239 .de ESc
240 . ds @tmp@ \$1
241 . TP 14n
242 . text \f(CB\(rs(\&\*[@tmp@]\ \ \ \fP\fR\(\*[@tmp@]\fP
243 . shift 1
244 . text \$*.
245 . rm @tmp@
246 ..
247 .
248 .c --------- registers ---------
249 .
250 .c synopsis for registers
251 .de REG
252 . TP 10n
253 . text \&\f(CR\(rsn[\fP\f(CB\$1\fP\f(CR]\fP
254 . shift 1
255 .if \n[.$] \&\$*
256 ..
257 .
258 .als register request
259 .
260 .c --------- warnings ---------
261 .
262 .als warning request
263 .
264 .c description of warnings
265 .de Warning
266 . ne (2v + 1)
267 . TP 12n
268 . text \f(CB\$1\fP
269 . text \f(CI\$2\fP
270 . br
271 ..
272 .
273 .ec
274 .
275 .\" --------------------------------------------------------------------
276 .\" Title
277 .\" --------------------------------------------------------------------
278 .
279 .TH GROFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
280 .SH NAME
281 groff \- a short reference for the GNU roff language
282 .
283 .\" --------------------------------------------------------------------
284 .SH DESCRIPTION
285 .\" --------------------------------------------------------------------
286 .I groff
287 stands for
288 .I GNU roff
289 and is the free implementation of the roff type-setting system.
290 See
291 .BR roff (@MAN7EXT@)
292 for a survey and the background of the groff system.
293 .LP
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.
297 .LP
298 Historically, the
299 .I roff language
300 was called
301 .IR troff .
302 .I groff
303 is compatible with the classical system and provides proper extensions.
304 So in GNU, the terms
305 .IR roff ,
306 .IR troff ,
307 and
308 .I groff language
309 could be used as synonyms.
310 However
311 .I troff
312 slightly tends to refer more to the classical aspects, whereas
313 .I groff
314 emphasizes the GNU extensions, and
315 .I roff
316 is the general term for the language.
317 .LP
318 This file is only a short version of the complete documentation that is
319 found in the
320 .I groff
321 .BR info (1)
322 file, which contains more detailed, actual, and concise information.
323 .LP
324 The general syntax for writing groff documents is relatively easy, but
325 writing extensions to the roff language can be a bit harder.
326 .LP
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
330 .''char .
331 or a single quote
332 .''char ' ;
333 all other lines are text lines.
334 .LP
335 .B Control 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,
341 .RS
342 .LP
343 \&\.command_name arg1 arg2
344 .RE
345 .LP
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.
349 .LP
350 .B Text lines
351 represent the parts that will be printed.
352 They can be modified by escape sequences, which are recognized by a
353 leading backslash
354 .'char \(rs .
355 These are in-line or even in-word formatting elements or functions.
356 Some of these take arguments separated by single quotes
357 .''char ' ,
358 others are regulated by a length encoding introduced by an open
359 parenthesis
360 .'char (
361 or enclosed in brackets
362 .'char [
363 and
364 .'char ] .
365 .LP
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
370 .BR "copy mode" .
371 .LP
372 The copy mode behavior can be quite tricky, but there are some rules
373 that ensure a safe usage.
374 .IP 1.
375 Printable backslashes must be denoted as
376 .esc e .
377 To be more precise,
378 .esc e
379 represents the current escape character.
380 To get a backslash glyph, use
381 .esc (rs .
382 .IP 2.
383 Double all backslashes.
384 .IP 3.
385 Begin all text lines with the special non-spacing character
386 .esc & .
387 .LP
388 This does not produce the most efficient code, but it should work as a
389 first measure.
390 For better strategies, see the groff info file and
391 .BR groff_tmac (@MAN5EXT@).
392 .LP
393 Reading roff source files is easier, just reduce all double backslashes
394 to a single one in all macro definitions.
395 .
396 .\" --------------------------------------------------------------------
397 .SH "GROFF ELEMENTS"
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.
402 .LP
403 There are two kinds of roff commands, possibly with arguments.
404 .B Requests
405 are written on a line of their own starting with a dot
406 .'char .
407 or a
408 .''char ' ,
409 whereas
410 .B Escape sequences
411 are in-line functions and in-word formatting elements starting with a
412 backslash
413 .'char \(rs .
414 .LP
415 The user can define her own formatting commands using the
416 .request .de
417 request. These commands are called
418 .BR macros ,
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.
423 .LP
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
427 variables as well.
428 .LP
429 .B String
430 variables store character sequences.
431 They are set with the
432 .request .ds
433 request and retrieved by the
434 .esc *
435 escape sequences.
436 .LP
437 .B Register
438 variables can store numerical values, numbers with a scale unit, and
439 occasionally string-like objects.
440 They are set with the
441 .request .nr
442 request and retrieved by the
443 .esc n
444 escape sequences.
445 .LP
446 .B Environments
447 allow the user to temporarily store global formatting parameters like
448 line length, font size, etc. for later reuse.
449 This is done by the
450 .request .ev
451 request.
452 .LP
453 .B Fonts
454 are identified either by a name or by an internal number.
455 The current font is chosen by the
456 .request .ft
457 request or by the
458 .esc f
459 escape sequences.
460 Each device has special fonts, but the following fonts are available for
461 all devices.
462 .B R
463 is the standard font Roman.
464 .B B
465 is its
466 .B bold
467 counterpart.
468 The
469 .I italic
470 font is called
471 .B I
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
475 these font,
476 .BR CR ,
477 .BR CI ,
478 and
479 .BR CB .
480 On text devices, all characters have a constant width anyway.
481 .LP
482 Moreover, there are some advanced roff elements.
483 A
484 .B diversion
485 stores information into a macro for later usage.
486 A
487 .B trap
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
491 is met.
492 .LP
493 More detailed information can be found in the groff info file.
494 .
495 .\" --------------------------------------------------------------------
496 .SH "CONTROL CHARACTERS"
497 .\" --------------------------------------------------------------------
498 There is a small set of characters that have a special controlling task
499 in certain conditions.
500 .TP
501 .character .
502 A dot is only special at the beginning of a line or after the
503 condition in the requests
504 .request .if ,
505 .request .ie ,
506 .request .el ,
507 and
508 .request .while .
509 There it is the control character that introduces a request (or macro).
510 The special behavior can be delayed by using the
511 .esc .
512 escape.
513 By using the
514 .request .cc
515 request, the control character can be set to a different character,
516 making the dot
517 .'char .
518 a non-special character.
519 .IP ""
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
522 of its own.
523 .TP
524 .character '
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
527 character.
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.
530 By using the
531 .request .c2
532 request, the non-break control character can be set to a different
533 character.
534 .IP ""
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
539 character.
540 Groff provides a printable representation with the
541 .esc (cq
542 escape sequence.
543 .TP
544 .character \(dq
545 The double quote is used to enclose arguments in requests and macros.
546 The escaped double quote
547 .esc \(dq
548 introduces a comment.
549 Otherwise, it is not special.
550 Groff provides a printable representation with the
551 .esc (dq
552 escape sequence.
553 .TP
554 .character \(rs
555 The backslash usually introduces an escape sequence (this can be
556 changed with the
557 .request ec
558 request).
559 A printed version of the escape character is the
560 .esc e
561 escape; a backslash glyph can be obtained by
562 .esc (rs .
563 .TP
564 .character (
565 The open parenthesis is only special in escape sequences when
566 introducing an escape name or argument consisting of exactly two
567 characters.
568 In groff, this behavior can be replaced by the \f(CB[]\fP construct.
569 .TP
570 .character [
571 The opening bracket is only special in groff escape sequences; there it
572 is used to introduce a long escape name or long escape argument.
573 Otherwise, it is non-special, e.g. in macro calls.
574 .TP
575 .character ]
576 The closing bracket is only special in groff escape sequences; there it
577 terminates a long escape name or long escape argument.
578 Otherwise, it is non-special.
579 .TP
580 \f(CIspace\fP
581 Space characters are only functional characters. They separate the
582 arguments in requests or macros, and the words in text lines.
583 They are subject to groff's horizontal spacing calculations.
584 To get a defined space width, escape sequences like
585 .'char "\(rs\ "
586 (this is the escape character followed by a space),
587 .esc | ,
588 .esc ^ ,
589 or
590 .esc h
591 should be used.
592 .IP \f(CInewline\fP
593 In text paragraphs, newlines mostly behave like space characters.
594 Continuation lines can be specified by an escaped newline, i.e., by
595 specifying a backslash
596 .'char \(rs
597 as the last character of a line.
598 .IP \f(CItab\fP
599 If a tab character occurs during text the interpreter makes a horizontal
600 jump to the next pre-defined tab position.
601 There is a sophisticated interface for handling tab positions.
602 .
603 .\" --------------------------------------------------------------------
604 .SH "NUMERICAL EXPRESSIONS"
605 .\" --------------------------------------------------------------------
606 A
607 .B numerical value
608 is a signed or unsigned integer or float with or without an appended
609 scale indicator.
610 A
611 .B scale indicator
612 is a one-character abbreviation for a unit of measurement.
613 A number followed by a scale indicator signifies a size value.
614 By default, numerical values do not have a scale indicator, i.e., they are
615 normal numbers.
616 .LP
617 The roff language defines the following scale indicators.
618 .LP
619 .na
620 .nh
621 .TS
622 center, tab(@);
623 LfCB Lw(4i).
624 c@Centimeter
625 i@Inch
626 P@Pica\ \(eq\ 1/6\ inch
627 p@Point\ \(eq\ 1/72\ inch
628 m@T{
629 Em\ \(eq\ \fRthe font size in points (width of letter `\f(CRm\fR')
630 T}
631 M@100th \fRof an \f(CREm
632 n@En\ \(eq\ Em/2
633 u@\fRBasic unit for actual output device
634 v@\fRVertical line space in basic units
635 z@T{
636 scaled point\ \(eq\ 1/\f(CIsizescale\fR of a point (defined in
637 font \fIDESC\fP file)
638 T}
639 .TE
640 .LP
641 .ad
642 .hy
643 .B Numerical expressions
644 are combinations of the numerical values defined above with
645 the arithmetical operators
646 .operator + ,
647 .operator \- ,
648 .operator * ,
649 .operator / ,
650 .operator %
651 .RI ( modulo ),
652 the comparative operators
653 .operator ==
654 (this is the same as
655 .operator = ),
656 .operator <= ,
657 .operator >= ,
658 .operator < ,
659 .operator > ,
660 the logical operators
661 .operator &
662 .RI ( and ),
663 .operator :
664 .RI ( or ),
665 .operator !
666 .RI ( not ),
667 and the parentheses
668 .operator (
669 and
670 .operator ) .
671 .LP
672 Moreover,
673 .I groff
674 added the following operators for numerical expressions:
675 .LP
676 .na
677 .nh
678 .TS
679 center, tab(@);
680 LfCB Lw(4i).
681 e1\f(CB>?\fPe2@The maximum of \f(CIe1\fP and \f(CIe2\fP.
682 e1\f(CB<?\fPe2@The minimum of \f(CIe1\fP and \f(CIe2\fP.
683 \f(CB(\fPc\f(CB;\fPe\f(CB)@T{
684 Evaluate \f(CIe\fP using \f(CIc\fP as the default scaling
685 indicator.
686 T}
687 .TE
688 .LP
689 .ad
690 .hy
691 For details see the groff info file.
692 .
693 .\" --------------------------------------------------------------------
694 .SH CONDITIONS
695 .\" --------------------------------------------------------------------
696 .B Conditions
697 occur in tests raised by the
698 .request .if ,
699 .request .ie ,
700 and the
701 .request .while
702 requests.
703 The following table characterizes the different types of conditions.
704 .LP
705 .na
706 .nh
707 .TS
708 center, tab(@);
709 LfCB Lw(4i).
710 \f(CIN\fP@T{
711 A numerical expression \f(CIN\fP yields true if its value
712 is\ \f(CR>0\fP.
713 T}
714 !\f(CIN\fP@T{
715 True if the value of \f(CIN\fP is\ \f(CR\(<=0\fP.
716 T}
717 \&'\f(CIs1\fP'\f(CIs2\fP'@T{
718 True if string\ \f(CIs1\fP is identical to string\ \f(CIs2\fP.
719 T}
720 !'\f(CIs1\fP'\f(CIs2\fP'@T{
721 True if string\ \f(CIs1\fP is not identical to string\ \f(CIs2\fP.
722 T}
723 c\f(CIch@T{
724 True if there is a character\ \f(CIch\fP available.
725 T}
726 d\f(CIname@T{
727 True if there is a string, macro, diversion, or request
728 called \f(CIname\fP.
729 T}
730 e@Current page number is even.
731 o@Current page number is odd.
732 n@Formatter is \fBnroff\fP.
733 r\f(CIreg@T{
734 True if there is a register named \f(CIreg\fP.
735 T}
736 t@Formatter is \fBtroff\fR.
737 .TE
738 .LP
739 .ad
740 .hy
741 .
742 .\" --------------------------------------------------------------------
743 .SH REQUESTS
744 .\" --------------------------------------------------------------------
745 This section provides a short reference for the predefined requests.
746 In groff, request and macro names can be arbitrarily long.
747 No bracketing or marking of long names is needed.
748 .LP
749 Most requests take one or more arguments.
750 The arguments are separated by space characters (no tabs!); there is no
751 inherent limit for their length or number.
752 An argument can be enclosed by a pair of double quotes: This is very handy
753 if an argument contains space characters, e.g.,
754 .argument "\(dqarg\ with\ space\(dq"
755 denotes a single argument.
756 .LP
757 Some requests have optional arguments with a different behaviour.
758 Not all of these details are outlined here.
759 Refer to the groff info file for all details.
760 .LP
761 In the following request specifications, most argument names were chosen
762 to be descriptive.
763 Only the following denotations need clarification.
764 .LP
765 .na
766 .nh
767 .TS
768 center, tab(@);
769 LfCI Lw(4i).
770 c@denotes a single character.
771 font@T{
772 a font either specified as a font name or a font number.
773 T}
774 anything@T{
775 all characters up to the end of the line or within \f(CB\(rs{\fP
776 and \f(CB\(rs}\fP.
777 T}
778 n@T{
779 is a numerical expression that evaluates to an integer value.
780 T}
781 N@T{
782 is an arbitrary numerical expression, signed or unsigned.
783 T}
784 \(+-N@T{
785 has three meanings depending on its sign, described below.
786 T}
787 .TE
788 .LP
789 .ad
790 .hy
791 If an expression defined as
792 .argument \(+-N
793 starts with a
794 .operator +
795 sign the resulting value of the expression will be added to an already
796 existing value inherent to the related request, e.g. adding to a number
797 register.
798 If the expression starts with a
799 .operator -
800 the value of the expression will be subtracted from the request value.
801 .LP
802 Without a sign,
803 .argument N
804 replaces the existing value directly.
805 To assign a negative number either prepend\ \c
806 .number 0
807 or enclose the negative number in parentheses.
808 .
809 .\" --------------------------------------------------------------------
810 .SS "REQUEST SHORT REFERENCE"
811 .\" --------------------------------------------------------------------
812 .PD 0
813 .
814 .REQ .
815 Empty line, ignored. Useful for structuring documents.
816 .
817 .REQ .\(rs\(dq anything
818 Complete line is a comment.
819 .
820 .REQ .ab string
821 Print
822 .argument string
823 on standard error, exit program.
824 .
825 .REQ .ad
826 Begin line adjustment for output lines in current adjust mode.
827 .
828 .REQ .ad c
829 Start line adjustment in mode
830 .argument c
831 (\f(CIc\fP\f(CR\|\^\(eq\|l,r,b,n\fP).
832 .
833 .REQ .af register c
834 Assign format
835 .argument c
836 to
837 .argument register
838 (\f(CIc\fP\f(CR\|\^\(eq\|l,i,I,a,A\fP).
839 .
840 .REQ .aln alias register
841 Create alias name for
842 .argument register .
843 .
844 .REQ .als alias object
845 Create alias name for request, string, macro, or diversion
846 .argument object .
847 .
848 .REQ .am macro
849 Append to
850 .argument macro
851 until
852 .request ..
853 is called.
854 .
855 .REQ .am macro end
856 Append to
857 .argument macro
858 until
859 .request .end
860 is called.
861 .
862 .REQ .as stringvar anything
863 Append
864 .argument anything
865 to
866 .argument stringvar .
867 .
868 .REQ .asciify diversion
869 Unformat special ASCII characters in
870 .argument diversion .
871 .
872 .REQ .backtrace
873 Print a backtrace of the input on stderr.
874 .
875 .REQ .bd font N
876 Embolden
877 .argument font
878 by
879 .argterm N -1
880 units.
881 .
882 .REQ .bd S font N
883 Embolden Special Font
884 .argument S
885 when current font is
886 .argument font .
887 .
888 .REQ .bp
889 Eject current page and begin new page.
890 .
891 .REQ .bp \(+-N
892 Eject current page; next page number
893 .argument \(+-N .
894 .
895 .REQ .blm macro
896 Set the blank line macro to
897 .argument macro .
898 .
899 .REQ .br
900 Line break.
901 .
902 .REQ .break
903 Break out of a while loop.
904 .
905 .REQ .c2
906 Reset no-break control character to
907 .''char ' .
908 .
909 .REQ .c2 c
910 Set no-break control character to
911 .argument c .
912 .
913 .REQ .cc
914 Reset control character to
915 .'char . .
916 .
917 .REQ .cc c
918 Set control character to
919 .argument c .
920 .
921 .REQ .ce
922 Center the next input line.
923 .
924 .REQ .ce N
925 Center following
926 .argument N
927 input lines.
928 .
929 .REQ .cf filename
930 Copy contents of file
931 .argument filename
932 unprocessed to stdout or to the diversion.
933 .
934 .REQ .cflags mode c1 c2 ...
935 Treat characters
936 .argument c1 ,
937 .argument c2 ,
938 .argument ...
939 according to
940 .argument mode
941 number.
942 .
943 .REQ .ch trap N
944 Change
945 .argument trap
946 location
947 to
948 .argument N .
949 .
950 .REQ .char c anything
951 Define character
952 .argument c
953 to string
954 .argument anything .
955 .
956 .REQ .chop object
957 Chop the last character off macro, string, or diversion
958 .argument object .
959 .
960 .REQ .close stream
961 Close the
962 .argument stream .
963 .
964 .REQ .continue
965 Finish the current iteration of a while loop.
966 .
967 .REQ .cp
968 Enable compatibility mode.
969 .
970 .REQ .cp N
971 If
972 .I N
973 is zero disable compatibility mode, otherwise enable it.
974 .
975 .REQ .cs font N M
976 Set constant character width mode for
977 .argument font
978 to
979 .argterm N /36
980 ems with em
981 .argument M .
982 .
983 .REQ .cu N
984 Continuous underline in nroff, like
985 .request .ul
986 in troff.
987 .
988 .REQ .da macro
989 Divert and append to
990 .argument macro .
991 .
992 .REQ .de macro
993 Define or redefine
994 .argument macro
995 until
996 .request ..
997 is called.
998 .
999 .REQ .de macro end
1000 Define or redefine
1001 .argument macro
1002 until
1003 .request .end
1004 is called.
1005 .
1006 .REQ .di
1007 End current diversion.
1008 .
1009 .REQ .di macro
1010 Divert to
1011 .argument macro .
1012 .
1013 .REQ .do name
1014 Interpret
1015 .request .name
1016 with compatibility mode enabled.
1017 .
1018 .REQ .ds stringvar anything
1019 Set
1020 .argument stringvar
1021 to
1022 .argument anything .
1023 .
1024 .REQ .dt N trap
1025 Set diversion trap to position
1026 .argument N
1027 (default scale indicator\ \c
1028 .scaleindicator v ).
1029 .
1030 .REQ .ec
1031 Reset escape character to
1032 .'char \(rs .
1033 .
1034 .REQ .ec c
1035 Set escape character to
1036 .argument c .
1037 .
1038 .REQ .el anything
1039 Else part for if-else (\c
1040 .argument .ie )
1041 request.
1042 .
1043 .REQ .em macro
1044 The
1045 .argument macro
1046 will be run after the end of input.
1047 .
1048 .REQ .eo
1049 Turn off escape character mechanism.
1050 .
1051 .REQ .ev
1052 Switch to previous environment.
1053 .
1054 .REQ .ev env
1055 Push down environment number or name
1056 .argument env
1057 and switch to it.
1058 .
1059 .REQ .evc env
1060 Copy the contents of environment
1061 .argument env
1062 to the current environment.
1063 No pushing or popping.
1064 .
1065 .REQ .ex
1066 Exit from roff processing.
1067 .
1068 .REQ .fam name
1069 Set the current font family to
1070 .argument name .
1071 .
1072 .REQ .fc
1073 Disable field mechanism.
1074 .
1075 .REQ .fc a
1076 Set field delimiter to
1077 .argument a
1078 and pad character to space.
1079 .REQ .fc a b
1080 Set field delimiter to
1081 .argument a
1082 and pad character to
1083 .argument b .
1084 .
1085 .REQ .fi
1086 Fill output lines.
1087 .
1088 .REQ .fl
1089 Flush output buffer.
1090 .
1091 .REQ .fp n font
1092 Mount
1093 .argument font
1094 on position
1095 .argument n .
1096 .
1097 .REQ .fp n internal external
1098 Mount font with long
1099 .argument external
1100 name to short
1101 .argument internal
1102 name on position
1103 .argument n .
1104 .
1105 .REQ .fspecial font s1 s2...
1106 When the current font is
1107 .argument font ,
1108 then the fonts
1109 .argument s1 ,
1110 .argument s2 ,
1111 .argument ...
1112 will be special.
1113 .
1114 .REQ .ft
1115 Return to previous font.
1116 Same as
1117 .request \(rsfP .
1118 .REQ .ft font
1119 Change to font name or number
1120 .argument font ;
1121 same as
1122 .esc[arg] f font
1123 escape sequence.
1124 .
1125 .REQ .ftr font1 font2
1126 Translate
1127 .argument font1
1128 to
1129 .argument font2 .
1130 .
1131 .REQ .hc
1132 Remove additional hyphenation indicator character.
1133 .
1134 .REQ .hc c
1135 Set up additional hyphenation indicator character\ \c
1136 .argument c .
1137 .
1138 .REQ .hcode c1 code1 c2 code2 ...
1139 Set the hyphenation code of character
1140 .argument c1
1141 to
1142 .argument code1 ,
1143 that of
1144 .argument c2
1145 to
1146 .argument code2 ,
1147 etc.
1148 .
1149 .REQ .hla lang
1150 Set the current hyphenation language to
1151 .argument lang .
1152 .
1153 .REQ .hlm n
1154 Set the maximum number of consecutive hyphenated lines to
1155 .argument n .
1156 .
1157 .REQ .hpf file
1158 Read hyphenation patterns from
1159 .argument file .
1160 .
1161 .REQ .hw words
1162 List of
1163 .argument words
1164 with exceptional hyphenation.
1165 .
1166 .REQ .hy N
1167 Switch to hyphenation mode
1168 .argument N .
1169 .
1170 .REQ .hym n
1171 Set the hyphenation margin to
1172 .argument n
1173 (default scale indicator\ \c
1174 .scaleindicator m ).
1175 .
1176 .REQ .hys n
1177 Set the hyphenation space to
1178 .argument n .
1179 .
1180 .REQ .ie cond anything
1181 If
1182 .argument cond
1183 then
1184 .argument anything
1185 else goto
1186 .request .el .
1187 .
1188 .REQ .if cond anything
1189 If
1190 .argument cond
1191 then
1192 .argument anything ;
1193 otherwise do nothing.
1194 .
1195 .REQ .ig
1196 Ignore text until
1197 .request ..
1198 is called.
1199 .
1200 .REQ .ig end
1201 Ignore text until
1202 .request .end .
1203 .
1204 .REQ .in
1205 Change to previous indent value.
1206 .
1207 .REQ .in \(+-N
1208 Change indent according to
1209 .argument \(+-N
1210 (default scale indicator\ \c
1211 .scaleindicator m ).
1212 .
1213 .REQ .it N trap
1214 Set an input-line count trap at position
1215 .argument N .
1216 .
1217 .REQ .kern
1218 Enable pairwise kerning.
1219 .
1220 .REQ .kern n
1221 If
1222 .argument n
1223 is zero, disable pairwise kerning, otherwise enable it.
1224 .
1225 .REQ .lc
1226 Remove leader repetition character.
1227 .
1228 .REQ .lc c
1229 Set leader repetition character to\ \c
1230 .argument c .
1231 .
1232 .REQ .length register anything
1233 Write the length of the string
1234 .argument anything
1235 in
1236 .argument register .
1237 .
1238 .REQ .lf N file
1239 Set input line number to
1240 .argument N
1241 and filename to
1242 .argument file .
1243 .
1244 .REQ .lg N
1245 Ligature mode on if
1246 .argterm N >0 .
1247 .
1248 .REQ .ll
1249 Change to previous line length.
1250 .
1251 .REQ .ll \(+-N
1252 Set line length according to
1253 .argument \(+-N
1254 (default size
1255 .scalednumber 6.5 i ,
1256 default scale indicator\ \c
1257 .scaleindicator m ).
1258 .
1259 .REQ .ls
1260 Change to the previous value of additional intra-line skip.
1261 .
1262 .REQ .ls N
1263 Set additional intra-line skip value to
1264 .argument N ,
1265 i.e.,
1266 .argterm N -1
1267 blank lines are inserted after each text output line.
1268 .
1269 .REQ .lt \(+-N
1270 Length of title (default scale indicator\ \c
1271 .scaleindicator m ).
1272 .
1273 .REQ .mc
1274 Margin character off.
1275 .
1276 .REQ .mc c
1277 Print character
1278 .argument c
1279 after each text line at actual distance from right margin.
1280 .
1281 .REQ .mc c N
1282 Set margin character to
1283 .argument c
1284 and distance to
1285 .argument N
1286 from right margin (default scale indicator\ \c
1287 .scaleindicator m ).
1288 .
1289 .REQ .mk register
1290 Mark current vertical position in
1291 .argument register .
1292 .
1293 .REQ .mso file
1294 The same as the .so request except that
1295 .I file
1296 is also searched in the tmac directories.
1297 .
1298 .REQ .na
1299 No output-line adjusting.
1300 .
1301 .REQ .ne
1302 Need a one-line vertical space.
1303 .
1304 .REQ .ne N
1305 Need
1306 .argument N
1307 vertical space (default scale indicator\ \c
1308 .scaleindicator v ).
1309 .
1310 .REQ .nf
1311 No filling or adjusting of output-lines.
1312 .
1313 .REQ .nh
1314 No hyphenation.
1315 .
1316 .REQ .nm
1317 Number mode off.
1318 .
1319 .REQ .nm \(+-N M S I
1320 In line number mode, set number, multiple, spacing, and indent.
1321 .
1322 .REQ .nn
1323 Do not number next line.
1324 .
1325 .REQ .nn N
1326 Do not number next
1327 .argument N
1328 lines.
1329 .
1330 .REQ .nr register \(+-N M
1331 Define or modify
1332 .argument register
1333 using
1334 .argument \(+-N
1335 with auto-increment
1336 .argument M .
1337 .
1338 .REQ .nroff
1339 Make the built-in condition
1340 .B n
1341 true and
1342 .B t
1343 false.
1344 .
1345 .REQ .ns
1346 Turn no-space mode on.
1347 .
1348 .REQ .nx filename
1349 Next file.
1350 .
1351 .REQ .open stream filename
1352 Open
1353 .register filename
1354 for writing and associate the stream named
1355 .register stream
1356 with it.
1357 .
1358 .REQ .opena stream filename
1359 Like
1360 .request .open
1361 but append to it.
1362 .
1363 .REQ .os
1364 Output vertical distance that was saved by the
1365 .request .sv
1366 request.
1367 .
1368 .REQ .pc
1369 Reset page number character to\ \c
1370 .'char % .
1371 .
1372 .REQ .pc c
1373 Page number character.
1374 .
1375 .REQ .pi program
1376 Pipe output to
1377 .argument program
1378 (nroff only).
1379 .
1380 .REQ .pl
1381 Set page length to default
1382 .scalednumber 11 i .
1383 The current page length is stored in
1384 .register .p .
1385 .
1386 .REQ .pl \(+-N
1387 Change page length to
1388 .argument \(+-N
1389 (default scale indicator\ \c
1390 .scaleindicator v ).
1391 .
1392 .REQ .pm
1393 Print macro names and sizes (number of blocks of 128 bytes).
1394 .
1395 .REQ ".pm t"
1396 Print only total of sizes of macros (number of 128 bytes blocks).
1397 .
1398 .REQ .pn \(+-N
1399 Next page number
1400 .argument N .
1401 .
1402 .REQ .pnr
1403 Print the names and contents of all currently defined number registers
1404 on stderr.
1405 .
1406 .REQ .po
1407 Change to previous page offset. The current page offset is available in
1408 .register .o .
1409 .
1410 .REQ .po \(+-N
1411 Page offset
1412 .argument N .
1413 .
1414 .REQ .ps
1415 Return to previous point-size.
1416 .REQ .ps \(+-N
1417 Point size; same as
1418 .esc[arg] s \(+-N .
1419 .
1420 .REQ .psbb filename
1421 Get the bounding box of a PostScript image
1422 .argument filename .
1423 .
1424 .REQ .pso command
1425 This behaves like the
1426 .request .so
1427 request except that input comes from the standard output of
1428 .argument command .
1429 .
1430 .REQ .ptr
1431 Print the names and positions of all traps (not including input line
1432 traps and diversion traps) on stderr.
1433 .
1434 .REQ .rchar c1 c2...
1435 Remove the definitions of characters
1436 .argument c1 ,
1437 .argument c2 ,
1438 .argument ...
1439 .
1440 .REQ .rd prompt
1441 Read insertion.
1442 .
1443 .REQ .rj n
1444 Right justify the next
1445 .argument n
1446 input lines.
1447 .
1448 .REQ .rm name
1449 Remove request, macro, or string
1450 .argument name .
1451 .
1452 .REQ .rn old new
1453 Rename request, macro, or string
1454 .argument old
1455 to
1456 .argument new .
1457 .
1458 .REQ .rnn reg1 reg2
1459 Rename register
1460 .argument reg1
1461 to
1462 .argument reg2 .
1463 .
1464 .REQ .rr register
1465 Remove
1466 .argument register .
1467 .
1468 .REQ .rs
1469 Restore spacing; turn no-space mode off.
1470 .
1471 .REQ .rt \(+-N
1472 Return
1473 .I (upward only)
1474 to marked vertical place (default scale indicator\ \c
1475 .scaleindicator v ).
1476 .
1477 .REQ .shc
1478 Reset soft hyphen character to
1479 .esc (hy .
1480 .
1481 .REQ .shc c
1482 Set the soft hyphen character to
1483 .argument c .
1484 .
1485 .REQ .shift n
1486 In a macro, shift the arguments by
1487 .argument n \ \c
1488 positions.
1489 .
1490 .REQ .so filename
1491 Include source file.
1492 .
1493 .REQ .sp
1494 Skip one line vertically.
1495 .
1496 .REQ .sp N
1497 Space vertical distance
1498 .argument N
1499 up or down according to sign of
1500 .argument N
1501 (default scaling indicator\ \c
1502 .scaleindicator v ).
1503 .
1504 .REQ .special s1 s2 ...
1505 Fonts
1506 .argument s1 ,
1507 .argument s2 ,
1508 etc. are special and will be searched for characters not in the current font.
1509 .
1510 .REQ .ss N
1511 Space-character size set to
1512 .argument N /12
1513 of the spacewidth in the current font.
1514 .
1515 .REQ .ss N M
1516 Space-character size set to
1517 .argterm N /12
1518 and sentence space size set to
1519 .argterm M /12
1520 of the spacewidth in the current font (\f(CR\(eq1/3 em\fP).
1521 .
1522 .REQ .sty n style
1523 Associate
1524 .argument style
1525 with font position
1526 .argument n .
1527 .
1528 .REQ .substring register n1 n2
1529 Replace the string in
1530 .argument register
1531 with the substring defined by the indices
1532 .argument n1
1533 and
1534 .argument n2 .
1535 .
1536 .REQ .sv
1537 Save
1538 .scalednumber 1 v
1539 of vertical space.
1540 .
1541 .REQ .sv N
1542 Save the vertical distance
1543 .argument N
1544 for later output with
1545 .request .os
1546 request.
1547 .
1548 .REQ .sy command-line
1549 Execute program
1550 .argument command-line .
1551 .
1552 .REQ ".ta T" N
1553 Set tabs after every position that is a multiple of
1554 .argument N
1555 (default scaling indicator\ \c
1556 .scaleindicator m ).
1557 .REQ .ta n1 n2 ... nn \f(CBT\fP r1 r2 ... rn
1558 Set tabs at positions
1559 .argument n1 ,
1560 .argument n2 ,
1561 \&...,
1562 .argument nn ,
1563 then set tabs at
1564 .argument nn + r1 ,
1565 .argument nn + r2 ,
1566 \&...,
1567 .argument nn + rn ,
1568 then at
1569 .argument nn + rn + r1 ,
1570 .argument nn + rn + r2 ,
1571 \&...,
1572 .argument nn + rn + rn ,
1573 and so on.
1574 .
1575 .\".REQ .tar
1576 .\"Restore internally saved tab positions.
1577 .\".
1578 .\".REQ .tas
1579 .\"Save tab positions internally.
1580 .
1581 .REQ .tc
1582 Remove tab repition character.
1583 .REQ .tc c
1584 Set tab repetition character to\ \c
1585 .argument c .
1586 .
1587 .REQ .ti \(+-N
1588 Temporary indent next line (default scaling indicator\ \c
1589 .scaleindicator m ).
1590 .
1591 .REQ .tkf font s1 n1 s2 n2
1592 Enable track kerning for
1593 .argument font .
1594 .
1595 .REQ .tl \f(CB\(cq\fPleft\f(CB\(cq\fPcenter\f(CB\(cq\fPright\f(CB\(cq\fP
1596 Three-part title.
1597 .
1598 .REQ .trf filename
1599 Transparently output the contents of file
1600 .argument filename .
1601 .
1602 .REQ .tm anything
1603 Print
1604 .argument anything
1605 on terminal (UNIX standard message output).
1606 .
1607 .REQ .tr abcd....
1608 Translate
1609 .argument a
1610 to
1611 .argument b ,
1612 .argument c
1613 to
1614 .argument d ,
1615 etc. on output.
1616 .
1617 .REQ .trnt abcd....
1618 This is the same as the
1619 .request .tr
1620 request except that the translations do not apply to text that is
1621 transparently throughput into a diversion with
1622 .esc ! .
1623 .
1624 .REQ .troff
1625 Make the built-in condition
1626 .B t
1627 true and
1628 .B n
1629 false.
1630 .
1631 .REQ .uf font
1632 Underline font set to
1633 .argument font
1634 (to be switched to by
1635 .request .ul ).
1636 .
1637 .REQ .ul N
1638 Underline (italicize in troff)
1639 .argument N
1640 input lines.
1641 .
1642 .REQ .vpt n
1643 Enable vertical position traps if
1644 .argument n
1645 is non-zero, disable them otherwise.
1646 .
1647 .REQ .vs
1648 Change to previous vertical base line spacing.
1649 .
1650 .REQ .vs N
1651 Set vertical base line spacing to
1652 .argument N .
1653 Default value is
1654 .scalednumber 12 p .
1655 .
1656 .REQ .warn n
1657 Set warnings code to
1658 .argument n .
1659 .
1660 .REQ .wh N trap
1661 Set location trap; negative means from page bottom.
1662 .
1663 .REQ .while cond anything
1664 While condition
1665 .argument cond
1666 is true, accept
1667 .argument anything
1668 as input.
1669 .
1670 .REQ .write stream anything
1671 Write
1672 .argument anything
1673 to the stream named
1674 .argument stream .
1675 .
1676 .PD
1677 .LP
1678 Besides these standard groff requests, there might be further macro
1679 calls.
1680 They can originate from a macro package (see
1681 .BR roff (@MAN7EXT@)
1682 for an overview) or from a preprocessor.
1683 .LP
1684 Preprocessor macros are easy to be recognized. They enclose their code
1685 into a pair of characteristic macros.
1686 .LP
1687 .TS
1688 box, center, tab (@);
1689 c | c | c
1690 CfCB | CfCB | CfCB.
1691 preprocessor@start macro@ end macro
1692 =
1693 eqn@.PS@.PE
1694 grap@.G1@.G2
1695 grn@.GS@.GE
1696 pic@.PS@.PE
1697 refer@.R1@.R2
1698 soelim@\fInone@\fInone
1699 tbl@.TS@.TE
1700 .TE
1701 .LP
1702 .
1703 .\" --------------------------------------------------------------------
1704 .SH "ESCAPE SEQUENCES"
1705 .\" --------------------------------------------------------------------
1706 .
1707 Escape sequences are in-line language elements usually introduced by
1708 a backslash
1709 .'char \(rs
1710 and followed by an escape name and sometimes by a required argument.
1711 Input processing is continued directly after the escaped character or
1712 the argument resp. without an intervening separation character.
1713 So there must be a way to determine the end of the escape name and the end
1714 of the argument.
1715 .LP
1716 This is done by enclosing names (escape name and arguments consisting of
1717 a variable name) by a pair of brackets
1718 .esc[] name
1719 and constant arguments (number expressions and characters) by apostrophes
1720 (ASCII 0x27) like
1721 .IR \(cqconstant\(cq .
1722 .LP
1723 There are abbreviations for short names.
1724 Two character escape names can be specified by an opening parenthesis like
1725 .esc( xy
1726 without a closing counterpart.
1727 And all one-character names different from the special characters
1728 .'char [
1729 and
1730 .'char (
1731 can even be specified without a marker in the form
1732 .esc \fP\f(CIc .
1733 .LP
1734 Constant arguments of length
1735 .number 1
1736 can omit the marker apostrophes, too, but there is no two-character
1737 analogue.
1738 .LP
1739 While 1-character escape sequences are mainly used for in-line functions
1740 and system related tasks, the 2-letter names following the
1741 .esc( ""
1742 construct are used for special characters predefined by the roff system.
1743 Names with more than two characters
1744 .esc[] name
1745 mostly denote user defined named characters (see the
1746 .request .char
1747 request).
1748 .
1749 .\" --------------------------------------------------------------------
1750 .SS "SINGLE CHARACTER ESCAPES"
1751 .\" --------------------------------------------------------------------
1752 .
1753 .PD 0
1754 .
1755 .\" --------- comments ---------
1756 .
1757 .ESC \(dq
1758 Beginning of a comment.
1759 Everything up to the end of the line is ignored.
1760 .
1761 .ESC #
1762 Everything up to and including the next newline is ignored.
1763 This is interpreted in copy mode.
1764 This is like
1765 .esc \(dq
1766 except the ignoring of the terminating newline.
1767 .
1768 .\" --------- strings ---------
1769 .
1770 .ESC * s
1771 The string stored in the string variable with 1-character name
1772 .argument s .
1773 .
1774 .ESC *( st
1775 The string stored in the string variable with 2-character name
1776 .argument st .
1777 .
1778 .ESC[] * stringvar
1779 The string stored in the string variable with arbitrary length name
1780 .argument stringvar .
1781 .
1782 .\" --------- macro arguments ---------
1783 .
1784 .ESC $0
1785 The name by which the current macro was invoked. The
1786 .request .als
1787 request can make a macro have more than one name.
1788 .
1789 .ESC $ x
1790 Macro argument with 1-place number
1791 .argument x ,
1792 where
1793 .argument x
1794 is a digit between 1 and 9.
1795 .
1796 .ESC $( xy
1797 Macro argument with 2-digit number
1798 .argument xy .
1799 .
1800 .ESC[] $ nexp
1801 Macro argument with number
1802 .argument nexp ,
1803 where
1804 .argument nexp
1805 is a numerical expression evaluating to an integer \(>=1.
1806 .
1807 .ESC $*
1808 In a macro, the concatenation of all the arguments separated by spaces.
1809 .
1810 .ESC $@
1811 In a macro, the concatenation of all the arguments with each surrounded
1812 by double quotes, and separated by spaces.
1813 .
1814 .\" --------- escaped characters ---------
1815 .
1816 .ESC \(rs
1817 reduces to a single backslash; useful to delay its interpretation as
1818 escape character in copy mode.
1819 For a printable backslash, use
1820 .esc e .
1821 .
1822 .ESC \(cq
1823 The acute accent \(aa; same as
1824 .esc( aa .
1825 Unescaped: apostrophe, right quotation mark, single quote (ASCII 0x27).
1826 .
1827 .ESC `
1828 The grave accent \(ga; same as
1829 .esc( ga .
1830 Unescaped: left quote, backquote (ASCII 0x60).
1831 .
1832 .ESC \-
1833 The \- sign in the current font.
1834 .
1835 .ESC .
1836 An uninterpreted dot (period), even at start of line.
1837 .
1838 .ESC %
1839 Default optional hyphenation character.
1840 .
1841 .ESC !
1842 Transparent line indicator.
1843 .
1844 .ESC ? anything\fB?\fP
1845 In a diversion, this will transparently embed
1846 .argument anything
1847 in the diversion.
1848 .argument anything
1849 is read in copy mode.
1850 See also the escape sequences
1851 .esc !
1852 and
1853 .esc ? .
1854 .
1855 .
1856 .\" --------- spacing ---------
1857 .
1858 .ESC \& space
1859 Unpaddable space-size space character (no line break).
1860 .
1861 .ESC 0
1862 Digit width.
1863 .
1864 .ESC |
1865 1/6\ em narrow space character; zero width in nroff.
1866 .
1867 .ESC ^
1868 1/12\ em half-narrow space character; zero width in nroff.
1869 .
1870 .ESC &
1871 Non-printable, zero width character.
1872 .
1873 .ESC )
1874 Like
1875 .esc &
1876 except that it behaves like a character declared with the cflags
1877 request to be transparent for the purposes of end of sentence
1878 recognition.
1879 .
1880 .ESC /
1881 Increases the width of the preceding character so that the spacing
1882 between that character and the following character will be correct if
1883 the following character is a roman character.
1884 .
1885 .ESC ,
1886 Modifies the spacing of the following character so that the spacing
1887 between that character and the preceding character will correct if the
1888 preceding character is a roman character.
1889 .
1890 .ESC ~
1891 Unbreakable space that stretches like a normal inter-word space when a
1892 line is adjusted.
1893 .
1894 .ESC \& newline
1895 Ignored newline, for continuation lines.
1896 .
1897 .\" --------- structuring ---------
1898 .
1899 .ESC {
1900 Begin conditional input.
1901 .
1902 .ESC }
1903 End conditional input.
1904 .
1905 .\" --------- longer escape names ---------
1906 .
1907 .ESC ( st
1908 The special character with 2-character name
1909 .argument st ,
1910 see section
1911 .BR "SPECIAL CHARACTERS" .
1912 .
1913 .ESC[] \& name
1914 The named character with arbitrary length name
1915 .argument name .
1916 .
1917 .\" --------- alphabetical escapes ---------
1918 .
1919 .ESC a
1920 Non-interpreted leader character.
1921 .
1922 .ESCq A anything
1923 If
1924 .argument anything
1925 acceptable as name of a string, macro, diversion, register,
1926 environment or font it is
1927 .number 1
1928 otherwise
1929 .number 0 .
1930 .
1931 .ESCq b abc...
1932 Bracket building function.
1933 .
1934 .ESC c
1935 Interrupt text processing.
1936 .
1937 .ESCq C char
1938 The character called
1939 .argument char ;
1940 same as
1941 .esc[] char ,
1942 but compatible to other roff versions.
1943 .
1944 .ESC d
1945 Forward (down) 1/2 em vertical unit (1/2 line in nroff).
1946 .
1947 .ESCq D charseq
1948 Draw a graphical element defined by the characters in
1949 .argument charseq ;
1950 see groff info file for details.
1951 .
1952 .ESC e
1953 Printable version of the current escape character.
1954 .
1955 .ESC E
1956 Equivalent to an escape character, but is not interpreted in copy-mode.
1957 .
1958 .ESC f F
1959 Change to font with 1-character name or 1-digit number
1960 .argument F .
1961 .
1962 .ESC f( fo
1963 Change to font with 2-characer name or 2-digit number
1964 .argument fo .
1965 .
1966 .ESC[] f font
1967 Change to font with arbitrary length name or number expression
1968 .argument font .
1969 .
1970 .ESC[] g reg
1971 Return format of register with name
1972 .argument reg
1973 suitable for
1974 .request .af .
1975 Alternative forms
1976 .esc(arg g xy
1977 and
1978 .escarg g x .
1979 .
1980 .ESCq h N
1981 Local horizontal motion; move right
1982 .argument N
1983 (left if negative).
1984 .
1985 .ESCq H N
1986 Set height of current font to
1987 .argument N .
1988 .
1989 .ESC[] k reg
1990 Mark horizontal input place in register with arbitrary length name
1991 .argument reg .
1992 Alternative forms
1993 .esc(arg k xy
1994 and
1995 .escarg k x .
1996 .
1997 .ESCq l Nc
1998 Horizontal line drawing function (optionally using character
1999 .argument c ).
2000 .
2001 .ESCq L Nc
2002 Vertical line drawing function (optionally using character
2003 .argument c ).
2004 .
2005 .ESC n r
2006 The numerical value stored in the register variable with the 1-character
2007 name
2008 .argument r .
2009 .
2010 .ESC n( re
2011 The numerical value stored in the register variable with the 2-character
2012 name
2013 .argument re .
2014 .
2015 .ESC[] n reg
2016 The numerical value stored in the register variable with arbitrary
2017 lenght name
2018 .argument reg .
2019 .
2020 .ESCq N n
2021 Typeset the character with code
2022 .argument n
2023 in the current font, no special fonts are searched. Useful for adding
2024 characters to a font using the
2025 .request .char
2026 request.
2027 .
2028 .ESCq o abc...
2029 Overstrike characters
2030 .argument a ,
2031 .argument b ,
2032 .argument c ,
2033 etc.
2034 .
2035 .ESC p
2036 Break and spread output line.
2037 .
2038 .ESC r
2039 Reverse 1\ em vertical motion (reverse line in nroff).
2040 .
2041 .ESCq R name \(+-n
2042 The same as
2043 .request .nr
2044 .argument name
2045 .argument \(+-n .
2046 .
2047 .ESC[] s \(+-N
2048 Set the point size to
2049 .I N
2050 scaled points. Note the alternative forms
2051 .BI \(rss \(+- [ N ]\c
2052 ,
2053 .BI \(rss' \(+-N '\c
2054 ,
2055 .BI \(rss \(+- ' N '\c
2056 ,
2057 .esc(arg s \(+-xy ,
2058 .BI \(rss \(+- ( xy\c
2059 ,
2060 .escarg s \(+-x .
2061 Same as
2062 .request .ps
2063 request.
2064 .
2065 .ESCq S N
2066 Slant output
2067 .argument N
2068 degrees.
2069 .
2070 .ESC t
2071 Non-interpreted horizontal tab.
2072 .
2073 .ESC u
2074 Reverse (up) 1/2 em vertical motion (1/2 line in nroff).
2075 .
2076 .ESCq v N
2077 Local vertical motion; move down
2078 .argument N
2079 (up if negative).
2080 .
2081 .ESC[] V env
2082 The contents of the environment variable
2083 .argument env .
2084 Alternative forms
2085 .esc(arg V xy
2086 and
2087 .escarg V x .
2088 .
2089 .ESCq w string
2090 The width of the character sequence
2091 .argument string .
2092 .
2093 .ESCq x N
2094 Extra line-space function (negative before, positive after).
2095 .
2096 .ESCq X string
2097 Output
2098 .argument string
2099 as device control function.
2100 .
2101 .ESC[] Y name
2102 Output string variable or macro
2103 .argument name
2104 uninterpreted as device control function.
2105 Alternative forms
2106 .esc(arg Y xy
2107 and
2108 .escarg Y x .
2109 .
2110 .ESC z c
2111 Print
2112 .argument c
2113 with zero width (without spacing).
2114 .
2115 .ESCq Z anything
2116 Print
2117 .argument anything
2118 and then restore the horizontal and vertical position;
2119 .argument anything
2120 may not contain tabs or leaders.
2121 .PD
2122 .LP
2123 The escape sequences
2124 .esc e ,
2125 .esc . ,
2126 .esc \(dq ,
2127 .esc $ ,
2128 .esc * ,
2129 .esc a ,
2130 .esc n ,
2131 .esc t ,
2132 .esc g ,
2133 and
2134 .escarg \& newline
2135 are interpreted in copy mode.
2136 .LP
2137 Escape sequences starting with
2138 .esc (
2139 or
2140 .esc [
2141 do not represent single character escape sequences, but introduce escape
2142 names with two or more characters.
2143 .LP
2144 If a backslash is followed by a character that does not constitute a
2145 defined escape sequence the backslash is silently ignored and the
2146 character maps to itself.
2147 .
2148 .\" --------------------------------------------------------------------
2149 .SS "SPECIAL CHARACTERS"
2150 .\" --------------------------------------------------------------------
2151 Common special characters are predefined by escape sequences of the form
2152 .(esc \fP\f(CIxy
2153 with characters
2154 .argument x
2155 and
2156 .argument y .
2157 Some of these exist in the usual font while most of them are only
2158 available in the special font. Below you'll find a selection of the most
2159 important glyphs; a complete list can be found in
2160 .BR groff_char (@MAN7EXT@).
2161 .RS
2162 .LP
2163 .PD 0
2164 .
2165 .ESc bu Bullet sign
2166 .ESc co Copyright
2167 .ESc ct Cent
2168 .ESc dd Double dagger
2169 .ESc de Degree
2170 .ESc dg Dagger
2171 .ESc em Em-dash
2172 .ESc hy Hyphen
2173 .ESc rg Registered sign
2174 .ESc sc Section sign
2175 .ESc ul Underline character
2176 .ESc == Identical
2177 .ESc >= Larger or equal
2178 .ESc <= Less or equal
2179 .ESc != Not equal
2180 .ESc -> Right arrow
2181 .ESc <- Left arrow
2182 .ESc +- Plus-minus sign
2183 .PD
2184 .RE
2185 .
2186 .\" --------------------------------------------------------------------
2187 .SH REGISTERS
2188 .\" --------------------------------------------------------------------
2189 Registers are variables that store a value.
2190 In groff, most registers store numerical values (see section
2191 .B NUMERICAL EXPRESSIONS
2192 above), but some can also hold a string value.
2193 .LP
2194 Each register is given a name.
2195 Arbitrary registers can be defined and set with the request
2196 .request .nr
2197 .argument register .
2198 .LP
2199 The value stored in a register can be retrieved by the escape sequences
2200 introduced by
2201 .esc n .
2202 .LP
2203 Most useful are predefined registers.
2204 In the following the notation
2205 .argument name
2206 is used to refer to a register called
2207 .register name
2208 to make clear that we speak about registers.
2209 Please keep in mind that the
2210 .esc en[]
2211 decoration is not part of the register name.
2212 .
2213 .\" --------------------------------------------------------------------
2214 .SS "READ-ONLY REGISTERS"
2215 .\" --------------------------------------------------------------------
2216 The following registers have predefined values that should not be
2217 modified by the user (usually, registers starting with a dot a read-only).
2218 Mostly, they provide information on the current settings or store results
2219 from request calls.
2220 .LP
2221 .PD 0
2222 .REG .$ Number of arguments in the current macro.
2223 .REG .A
2224 Set to
2225 .number 1
2226 in
2227 .B troff
2228 if option
2229 .B \-A
2230 is used; always
2231 .number 1
2232 in
2233 .BR nroff .
2234 .REG .H Available horizontal resolution in basic units.
2235 .REG .T
2236 Set to
2237 .number 1
2238 if option
2239 .B \-T
2240 is used.
2241 .REG .V Available vertical resolution in basic units.
2242 .REG .a
2243 Post-line extra line-space most recently utilized using
2244 .escarg x 'N' .
2245 .REG .C 1 if compatibility mode is in effect, 0 otherwise.
2246 .REG .c Current input line number.
2247 .REG .cdp
2248 The depth of the last character added to the current environment.
2249 It is positive if the character extends below the baseline.
2250 .REG .ce
2251 The number of lines remaining to be centered, as set by the
2252 .request .ce
2253 request.
2254 .REG .cht
2255 The height of the last character added to the current environment.
2256 It is positive if the character extends above the baseline.
2257 .REG .csk
2258 The skew of the last character added to the current environment.
2259 The skew of a character is how far to the right of the center of a character
2260 the center of an accent over that character should be placed.
2261 .REG .d
2262 Current vertical place in current diversion; equal to register
2263 .register nl .
2264 .REG .ev The name or number of the current environment (string-valued).
2265 .REG .f Current font number.
2266 .REG .fam The current font family (string-valued).
2267 .REG .fp The number of the next free font position.
2268 .REG .g
2269 Always 1 in GNU troff.
2270 Macros should use it to test if running under groff.
2271 .REG .h Text base-line high-water mark on current page or diversion.
2272 .REG .hla
2273 The current hyphenation language as set by the
2274 .B .hla
2275 request.
2276 .REG .hlc
2277 The number of immediately preceding consecutive hyphenated lines.
2278 .REG .hlm
2279 The maximum allowed number of consecutive hyphenated lines, as set by
2280 the
2281 .request .hlm
2282 request.
2283 .REG .hy
2284 The current hyphenation flags (as set by the
2285 .request .hy
2286 request).
2287 .REG .hym
2288 The current hyphenation margin (as set by the
2289 .request .hym
2290 request).
2291 .REG .hys
2292 The current hyphenation space (as set by the
2293 .request .hys
2294 request).
2295 .REG .i Current ident.
2296 .REG .in The indent that applies to the current output line.
2297 .REG .kern
2298 .number 1
2299 if pairwise kerning is enabled,
2300 .number 0
2301 otherwise.
2302 .REG .l Current line length.
2303 .REG .lg
2304 The current ligature mode (as set by the
2305 .request .lg
2306 request).
2307 .REG .ll The line length that applies to the current output line.
2308 .REG .lt
2309 The title length (as set by the
2310 .request .lt
2311 request).
2312 .REG .n Length of text portion on previous output line.
2313 .REG .ne
2314 The amount of space that was needed in the last
2315 .request .ne
2316 request that caused a trap to be sprung.
2317 Useful in conjunction with
2318 .register .trunc .
2319 .REG .o Current page offset.
2320 .REG .p Current page length.
2321 .REG .pn
2322 The number of the next page: either the value set by a
2323 .request .pn
2324 request, or the number of the current page plus\ 1.
2325 .REG .ps The current pointsize in scaled points.
2326 .REG .psr The last-requested pointsize in scaled points.
2327 .REG .rj
2328 The number of lines to be right-justified as set by the rj request.
2329 .REG .s Current point size as a decimal fraction.
2330 .REG .sr
2331 The last requested pointsize in points as a decimal fraction
2332 (string-valued).
2333 .REG .t Distance to the next trap.
2334 .REG .tabs
2335 A string representation of the current tab settings suitable for use as
2336 an argument to the
2337 .request .ta
2338 request.
2339 .REG .trunc
2340 The amount of vertical space truncated by the most recently sprung
2341 vertical position trap, or, if the trap was sprung by a
2342 .request .ne
2343 request, minus the amount of vertical motion produced by
2344 .request .ne .
2345 request.
2346 In other words, at the point a trap is sprung, it represents the difference
2347 of what the vertical position would have been but for the trap, and what the
2348 vertical position actually is.
2349 Useful in conjunction with the
2350 .register .ne
2351 register.
2352 .REG .ss
2353 The value of the parameters set by the first argument of the
2354 .request .ss
2355 request.
2356 .REG .sss
2357 The value of the parameters set by the second argument of the
2358 .request .ss
2359 request.
2360 .REG .u Equal to 1 bin fill mode and 0 in nofill mode.
2361 .REG .v Current vertical line spacing.
2362 .REG .vpt
2363 .number 1
2364 if vertical position traps are enabled,
2365 .number 0
2366 otherwise.
2367 .REG .w Width of previous character.
2368 .REG .warn
2369 The sum of the number codes of the currently enabled warnings.
2370 .REG .x The major version number.
2371 .REG .y The minor version number.
2372 .REG .Y The revision number of groff.
2373 .REG .z Name of current diversion.
2374 .REG llx
2375 Lower left x-coordinate (in PostScript units) of a given PostScript
2376 image (set by
2377 .request .psbb ).
2378 .REG lly
2379 Lower left y-coordinate (in PostScript units) of a given PostScript
2380 image (set by
2381 .request .psbb ).
2382 .REG rsb Like
2383 .register sb ,
2384 but takes account of the heights and depths of characters.
2385 .REG rst
2386 Like
2387 .register st ,
2388 but takes account of the heights and depths of characters.
2389 .REG sb
2390 Depth of string below base line (generated by width function
2391 .esc w ).
2392 .REG skw
2393 Right skip width from the center of the last character in the
2394 .esc w
2395 argument.
2396 .REG ssc
2397 The amount of horizontal space (possibly negative) that should be added
2398 to the last character before a subscript (generated by width function
2399 .esc w ).
2400 .REG st
2401 Height of string above base line (generated by width function
2402 .esc w ).
2403 .REG urx
2404 Upper right x-coordinate (in PostScript units) of a given PostScript
2405 image (set by
2406 .request .psbb ).
2407 .REG ury
2408 Upper right y-coordinate (in PostScript units) of a given PostScript
2409 image (set by
2410 .request .psbb ).
2411 .PD
2412 .
2413 .\" --------------------------------------------------------------------
2414 .SS "WRITABLE REGISTERS"
2415 .\" --------------------------------------------------------------------
2416 The following registers can be read and written by the user.
2417 They have predefined default values, but these can be modified for
2418 customizing a document.
2419 .LP
2420 .PD 0
2421 .REG % Current page number.
2422 .REG c. Current input line number.
2423 .REG ct Character type (set by width function
2424 .esc w ).
2425 .REG dl Maximal width of last completed diversion.
2426 .REG dw Current day of week (1-7).
2427 .REG dy Current day of month (1-31).
2428 .REG hp Current horizontal position at input line.
2429 .REG ln Output line number.
2430 .REG mo Current month (1-12).
2431 .REG nl Vertical position of last printed text base-line.
2432 .REG slimit
2433 If greater than 0, the maximum number of objects on the input stack.
2434 If \(<=0 there is no limit, i.e., recursion can continue until virtual
2435 memory is exhausted.
2436 .REG systat
2437 The return value of the
2438 .I system()
2439 function executed by the last
2440 .request .sy
2441 request.
2442 .REG year The current year (year 2000 compliant).
2443 .REG yr
2444 Current year minus 1900. For Y2K compliance use register
2445 .register year
2446 instead.
2447 .PD
2448 .
2449 .\" --------------------------------------------------------------------
2450 .SH WARNINGS
2451 .\" --------------------------------------------------------------------
2452 Each warning generated by groff is identified by a name and a code
2453 number. The codes are powers of 2 to allow bit-encoding with a single
2454 integer. There are also names that can be used to refer to groups of
2455 warnings.
2456 .LP
2457 The name associated with a warning is used by the
2458 .option \-w
2459 and
2460 .option \-W
2461 options;
2462 the number code is used by the
2463 .request .warn
2464 request and by the
2465 .esc[arg] n warn
2466 register.
2467 .LP
2468 .PD 0
2469 .Warning all group
2470 All warnings except
2471 .warning di ,
2472 .warning mac
2473 and
2474 .warning reg .
2475 Intended to cover all warnings with traditional macro packages.
2476 .Warning break 4
2477 In fill mode, lines which could not be broken so that their length was
2478 less than the line length. This is enabled by default.
2479 .Warning char 1
2480 Non-existent characters. This is enabled by default.
2481 .Warning delim 8
2482 Missing or mismatched closing delimiters.
2483 .Warning di 256
2484 Use of
2485 .request .di
2486 or
2487 .request .da
2488 without an argument when there is no current diversion.
2489 .Warning el 16
2490 Use of the
2491 .request .el
2492 request with no matching
2493 .request .ie
2494 request.
2495 .Warning escape 32768
2496 Unrecognized escape sequence. Then the escape character is ignored.
2497 .Warning font 131072
2498 Non-existent fonts. This is enabled by default.
2499 .Warning ig 262144
2500 Illegal escapes in text ignored with the
2501 .request \.ig
2502 request. These are conditions that are errors when they occur outside
2503 of ignored text.
2504 .Warning mac 512
2505 Use of undefined strings, macros, and diversions. Automatically handled
2506 as empty. Usually, only one warning per name.
2507 .Warning missing 8192
2508 Request that is missing non-optional arguments.
2509 .Warning input 16384
2510 Illegal input character.
2511 .Warning number 2
2512 Invalid numeric expressions. This is enabled by default.
2513 .Warning range 64
2514 Out of range arguments.
2515 .Warning reg 1024
2516 Use of undefined number register. Automatically defined as having
2517 value 0. Usually, only one warning per name.
2518 .Warning right-brace 4096
2519 Use of
2520 .esc }
2521 where a number was expected.
2522 .Warning scale 32
2523 Meaningless scaling indicators.
2524 .Warning space 65536
2525 Missing space between a request or macro and its argument. Then no
2526 macro is automatically defined. This is enabled by default. This
2527 warning will never occur in compatibility mode.
2528 .Warning syntax 128
2529 Dubious syntax in numeric expressions.
2530 .Warning tab 2048
2531 Inappropriate use of a tab character (either in an unquoted macro
2532 argument or where a number was expected).
2533 .Warning w group
2534 All warnings.
2535 .PD
2536 .LP
2537 .TS
2538 tab(@), box, expand;
2539 c c c | c c c | c c c
2540 R RI CB | R RI CB | R RI CB.
2541 Bit@Code@Warning@Bit@Code@Warning@Bit@Code@Warning
2542 _
2543 0@1@char@8@256@di@16@65536@space
2544 1@2@number@9@512@mac@17@131072@font
2545 2@4@break@10@1024@reg@18@262144@ig
2546 3@8@delim@11@2048@tab
2547 4@16@el@12@4096@right-brace
2548 5@32@scale@13@8192@missing
2549 6@64@range@14@16384@input
2550 7@128@syntax@15@32768@escape
2551 .TE
2552 .LP
2553 .
2554 .\" --------------------------------------------------------------------
2555 .SH COMPATIBILITY
2556 .\" --------------------------------------------------------------------
2557 .I groff
2558 provides a
2559 .B compatibility mode
2560 that allows to process roff code written for classical
2561 .troff
2562 or for other implementations of roff in a consistent way.
2563 .LP
2564 Compatibility mode can be turned on with the
2565 .option \-C
2566 command line option, and turned on or off with the
2567 .request .cp
2568 request. The number register
2569 .esc(arg n .C
2570 is
2571 .number 1
2572 if compatibility mode is on,
2573 .number 0
2574 otherwise.
2575 .LP
2576 This became necessary because the GNU concept for long names causes some
2577 incompatibilities.
2578 .I Classical troff
2579 will interpret
2580 .IP
2581 .B
2582 \&.dsabcd
2583 .LP
2584 as defining a string
2585 .B ab
2586 with contents
2587 .BR cd .
2588 Normally,
2589 .I groff
2590 will interpret this as a call of a macro named
2591 .request dsabcd .
2592 .LP
2593 Also
2594 .I classical troff
2595 will interpret
2596 .esc *[
2597 or
2598 .esc n[
2599 as references to a string or number register called
2600 .register [ .
2601 In
2602 .I GNU native
2603 .IR mode ,
2604 however, this will normally be interpreted as the start of a long name.
2605 .LP
2606 In
2607 .I compatibility
2608 .IR mode ,
2609 groff will interpret these things in the traditional way, but long names
2610 are not recognized.
2611 .LP
2612 On the other hand, groff in
2613 .I GNU native mode
2614 does not allow to use the escape sequences
2615 .esc e ,
2616 .esc | ,
2617 .esc ^ ,
2618 .esc & ,
2619 .esc } ,
2620 .esc { ,
2621 .esc "\ " (space),
2622 .esc ' ,
2623 .esc ` ,
2624 .esc - ,
2625 .esc _ ,
2626 .esc ! ,
2627 .esc % ,
2628 and
2629 .esc c
2630 in names of strings, macros, diversions, number registers, fonts or
2631 environments, whereas
2632 .I classical troff
2633 does. The
2634 .esc A
2635 escape sequence can be helpful in avoiding these escape sequences in
2636 names.
2637 .LP
2638 Fractional pointsizes cause one noteworthy incompatibility.
2639 In
2640 .I classical
2641 .IR troff ,
2642 the
2643 .request .ps
2644 request ignores scale indicators and so
2645 .RS
2646 .LP
2647 .B .ps\ 10u
2648 .RE
2649 .LP
2650 will set the pointsize to 10 points, whereas in groff native mode the
2651 pointsize will be set to 10 scaled points.
2652 .LP
2653 In
2654 .I groff
2655 mode, there is a fundamental difference between unformatted input
2656 characters, and formatted output characters.
2657 Everything that affects how an output character will be output is stored
2658 with the character; once an output character has been constructed it is
2659 unaffected by any subsequent requests that are executed, including the
2660 .request .bd ,
2661 .request .cs ,
2662 .request .tkf ,
2663 .request .tr ,
2664 or
2665 .request .fp
2666 requests.
2667 .LP
2668 Normally output characters are constructed from input characters at the
2669 moment immediately before the character is added to the current output
2670 line.
2671 Macros, diversions and strings are all, in fact, the same type of object;
2672 they contain lists of input characters and output characters in any
2673 combination.
2674 .LP
2675 An output character does not behave like an input character for the
2676 purposes of macro processing; it does not inherit any of the special
2677 properties that the input character from which it was constructed might
2678 have had.
2679 The following example will make things clearer.
2680 .LP
2681 .RS
2682 .nf
2683 .ft B
2684 \&.di x
2685 \(rs\(rs\(rs\(rs
2686 \&.br
2687 \&.di
2688 \&.x
2689 .ft
2690 .fi
2691 .RE
2692 .LP
2693 In
2694 .I GNU mode
2695 this will be printed as
2696 .esc \(rs .
2697 So each pair of input backslashes
2698 .'char \(rs\(rs
2699 is turned into a single output backslash
2700 .'char \(rs
2701 and the resulting output backslashes are not interpreted as escape
2702 characters when they are reread.
2703 .LP
2704 .I Classical troff
2705 would interpret them as escape characters when they were reread and
2706 would end up printing a single backslash
2707 .'char \(rs .
2708 .LP
2709 The correct way to get a printable
2710 .'char \(rs
2711 is to use the
2712 .esc e
2713 escape sequence. This will always print a single instance of the
2714 current escape character, regardless of whether or not it is used in a
2715 diversion. It will also work in both GNU mode and compatibility mode.
2716 .LP
2717 To store an escape sequence in a diversion that will be interpreted when
2718 the diversion is reread, either the traditional
2719 .esc !
2720 transparent output facility or the
2721 new
2722 .esc ?
2723 escape sequence can be used.
2724 .
2725 .\" --------------------------------------------------------------------
2726 .SH BUGS
2727 .\" --------------------------------------------------------------------
2728 At the moment, the documentation of the groff system is in a state of
2729 change and evolution. It is possible that there are small
2730 inconsistencies between different documents temporarily.
2731 .LP
2732 The
2733 .B WARNINGS
2734 section belongs to
2735 .BR troff (@MAN1EXT@).
2736 .
2737 .\" --------------------------------------------------------------------
2738 .SH AUTHOR
2739 .\" --------------------------------------------------------------------
2740 This document is part of groff, the GNU roff distribution. It was
2741 written by Bernd Warken <bwarken@mayn.de>.
2742 .LP
2743 It is distributed under the terms of the FDL (GNU Free Documentation
2744 License) version 1.1 or later. You should have received a copy of the
2745 FDL on your system, it is also available on-line under
2746 .RS
2747 .LP
2748 .IR http://www.gnu.org/copyleft/fdl.html .
2749 .RE
2750 .LP
2751 Formerly, the extensions of the groff language were kept in the manual
2752 page
2753 .BR troff (@MAN1EXT@).
2754 This document contains the essential parts of that documentation, but
2755 the gory details are found in the groff info file.
2756 .
2757 .\" --------------------------------------------------------------------
2758 .SH "SEE ALSO"
2759 .\" --------------------------------------------------------------------
2760 The main source of information for the groff language is the
2761 .B groff
2762 .BR info (1)
2763 file.
2764 .LP
2765 For a survey of roff and the groff system and further documentation
2766 pointers see
2767 .BR roff (@MAN7EXT@).
2768 .LP
2769 The formatter programs are described in
2770 .BR groff (@MAN1EXT@)
2771 and
2772 .BR troff (@MAN1EXT@);
2773 a complete of all predefined glyph names can be found in
2774 .BR groff_char (@MAN7EXT@).
2775 .LP
2776 The classical
2777 .I troff
2778 documentation is available on-line at
2779 .RS
2780 .LP
2781 .I http://cm.bell-labs.com/cm/cs/cstr.html
2782 .RE
2783 and
2784 .RS
2785 .IR http://www.kohala.com/start/troff/ .