| blob | bfa0420e6d40b1c193d4f3c28f4b1cda09a06ada |
1 '\" t
2 .ig
3 groff.man
5 Last update: 11 May 2002
7 This file is part of groff, the GNU roff type-setting system.
9 Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc.
10 written by Bernd Warken <bwarken@mayn.de>
11 maintained by Werner Lemberg <wl@gnu.org>
13 Permission is granted to copy, distribute and/or modify this document
14 under the terms of the GNU Free Documentation License, Version 1.1 or
15 any later version published by the Free Software Foundation; with the
16 Invariant Sections being this .ig-section and AUTHORS, with no
17 Front-Cover Texts, and with no Back-Cover Texts.
19 A copy of the Free Documentation License is included as a file called
20 FDL in the main directory of the groff source package.
21 ..
22 .
23 .\" --------------------------------------------------------------------
24 .\" Setup
25 .\" --------------------------------------------------------------------
26 .
27 .mso www.tmac
28 .
29 .if n \{\
30 . mso tty-char.tmac
31 . ftr CR R
32 . ftr CI I
33 . ftr CB B
34 .\}
35 .
36 .if '\*[.T]'dvi' \{\
37 . ftr CB CW
38 .\}
39 .
40 .
41 .\" --------------------------------------------------------------------
42 .\" start of macro definitions
43 .eo
44 .
45 .de c
46 ..
47 .
48 .de TPx
49 . TP 10n
50 ..
51 .c ---------------------------------------------------------------------
52 .c .Text anything ...
53 .c
54 .c All arguments are printed as text.
55 .c
56 .de Text
57 . nop \)\$*
58 ..
59 .c ---------------------------------------------------------------------
60 .c .ExecFF macro font1 font2 text1 text2 text1 text2 ...
61 .c
62 .c Concat text arguments using alternating fonts and feed into macro.
63 .c For a trailing punctuation, terminate the call with \c.
64 .c
65 .de ExecFF
66 . if (\n[.$] < 4) \
67 . return
68 . ds @a\"
69 . ds @m \$1\"
70 . ds @f1 \$2\"
71 . ds @f2 \$3\"
72 . shift 3
73 . ds @s\"
74 . while 1 \{\
75 . if (\n[.$] = 0) \
76 . break
77 . ds @a \$1\"
78 . as @s \f[\*[@f1]]\*[@a]\f[]\"
79 . shift
80 . if (\n[.$] = 0) \
81 . break
82 . ds @a \$1\"
83 . as @s \f[\*[@f2]]\*[@a]\f[]\"
84 . shift
85 . \}
86 . \*[@m] \*[@s]\f[R]
87 . ft P \" to make \c happy
88 . rm @m
89 . rm @s
90 . rm @a
91 . rm @f1
92 . rm @f2
93 ..
94 .
95 .c --------- command line option ---------
96 .
97 .de option
98 . Text \f[CB]\$*
99 . ft P
100 ..
101 .
102 .c --------- characters ---------
103 .
104 .de character
105 . ExecFF Text CB R \$*
106 ..
107 .de squoted_char
108 . ds @1 \$1\"
109 . shift
110 . ExecFF Text R CB \[oq] \*[@1] "\[cq]\$*"
111 . rm @1
112 ..
113 .de dquoted_char
114 . ds @1 \$1\"
115 . shift
116 . ExecFF Text R CB \[lq] \*[@1] "\[rq]\$*"
117 . rm @1
118 ..
119 .c --------- requests ---------
120 .
121 .c synopsis of a request
122 .de REQ
123 . if (\n[.$] = 0) \
124 . return
125 . ds @1 \$1\"
126 . shift 1
127 . ie (\n[.$] = 0) \{\
128 . TP 10n
129 . Text \f[CB]\*[@1]\f[]
130 . \}
131 . el \{\
132 . TP 10n
133 . Text \f[CB]\*[@1]\~\f[]\f[I]\$*\f[]
134 . \}
135 . rm @1
136 ..
137 .c reference of a request
138 .de request
139 . BR \$*
140 ..
141 .
142 .c --------- numerical elements ---------
143 .
144 .c number with a trailing unit
145 .de scalednumber
146 . Text \$1\^\f[CB]\$2\f[]\$3\f[R]
147 . ft P
148 ..
149 .
150 .c representation of units within the text
151 .de scaleindicator
152 . Text \f[CB]\$1\f[]\$2\f[R]
153 . ft P
154 ..
155 .
156 .c representation of mathematical operators within the text
157 .de operator
158 . squoted_char \$@
159 ..
160 .
161 .
162 .c --------- escape sequences ---------
163 .
164 .c ---------------------------------------------------------------------
165 .c .ESC name [arg]
166 .c
167 .c Synopsis of an escape sequence, optionally with argument
168 .c Args : 1 or 2; `name' obligatory, `arg' optional
169 .c name : suitable name for an escape sequence (c, (xy, [long])
170 .c arg : arbitrary word
171 .c Result : prints \namearg, where `name' is in CB, `arg' in I
172 .c
173 .de ESC
174 . if (\n[.$] < 1)
175 . ab .ESC needs 1 or 2 arguments.
176 . ExecFF IP CB I "\[rs]\$1" "\,\$2\/"
177 ..
178 .c ---------------------------------------------------------------------
179 .c .ESC[] name arg
180 .c
181 .c Synopsis for escape sequence with a bracketed long argument
182 .c Args : 2 obligatory
183 .c name : suitable name for an escape sequence (c, (xy, [long])
184 .c arg : arbitrary text
185 .c Result : prints \name[arg], where `name' is in CB, `arg' in I
186 .c
187 .de ESC[]
188 . if !(\n[.$] = 2) \
189 . ab .ESC[] needs exactly 2 arguments.
190 . ExecFF IP CB I "\[rs]\$1\[lB]" "\h'-0.2m'\$2\h'-0.15m'" \[rB]
191 ..
192 .c ---------------------------------------------------------------------
193 .c .ESCq name arg
194 .c
195 .c Synopsis for escape sequence with a bracketed long argument
196 .c Args : 2 obligatory
197 .c name : suitable name for an escape sequence (c, (xy, [long])
198 .c arg : arbitrary text
199 .c Result : prints \name'arg', where `name' is in CB, `arg' in I
200 .c
201 .de ESCq
202 . if !(\n[.$] = 2) \
203 . ab .ESCq needs exactly 2 argument.
204 . ExecFF IP CB I "\[rs]\$1\[cq]" "\h'-0.3m'\$2" \[cq]
205 ..
206 .c ---------------------------------------------------------------------
207 .c .ESC? arg
208 .c
209 .c Synopsis for escape sequence with a bracketed long argument
210 .c Args : 1 obligatory
211 .c arg : arbitrary text
212 .c Result : prints `\?arg?', where the `?' are in CB, `arg' in I
213 .c
214 .de ESC?
215 . if !(\n[.$] = 1) \
216 . ab .ESC? needs exactly 1 arguments.
217 . ExecFF IP CB I \[rs]? "\$1" ?
218 ..
219 .c ---------------------------------------------------------------------
220 .c .esc name [punct]
221 .c
222 .c Reference of an escape sequence (no args), possibly punctuation
223 .c Args : 1 obligatory
224 .c name : suitable name for an escape sequence (c, (xy, [long])
225 .c punct : arbitrary
226 .c Result : prints \name, where `name' is in B, `punct' in R
227 .c
228 .de esc
229 . if (\n[.$] < 1) \
230 . ab .esc needs 1 or 2 arguments.
231 . BR "\[rs]\$1" \$2
232 ..
233 .c ---------------------------------------------------------------------
234 .c .escarg name arg [punct]
235 .c
236 .c Reference of an escape sequence (no args)
237 .c Args : 1 obligatory, 1 optional
238 .c name : suitable name for an escape sequence (c, (xy, [long])
239 .c arg : arbitrary word
240 .c Result : prints \namearg, where
241 .c `name' is in B, `arg' in I
242 .c
243 .de escarg
244 . if (\n[.$] < 2) \
245 . ab .esc needs 2 or 3 arguments.
246 . Text \f[B]\[rs]\$1\f[]\f[I]\$2\f[]\$3
247 ..
248 .c ---------------------------------------------------------------------
249 .c .esc[] name arg [punct]
250 .c
251 .c Reference for escape sequence with a bracketed long argument
252 .c Args : 2 obligatory
253 .c name : suitable name for an escape sequence (c, (xy, [long])
254 .c arg : arbitrary text
255 .c Result : prints \name[arg], where `name' is in CB, `arg' in CI
256 .c
257 .de esc[]
258 . if (\n[.$] < 2) \
259 . ab .esc[] needs 2 or 3 arguments.
260 . Text \f[B]\[rs]\$1\[lB]\f[]\f[I]\$2\f[]\f[B]\[rB]\f[]\$3
261 ..
262 .
263 .c ---------------------------------------------------------------------
264 .c .escq name arg
265 .c
266 .c Reference for escape sequence with a bracketed long argument
267 .c Args : 2 obligatory
268 .c name : suitable name for an escape sequence (c, (xy, [long])
269 .c arg : arbitrary text
270 .c Result : prints \name'arg', where `name' is in CB, `arg' in CI
271 .c
272 .de escq
273 . if (\n[.$] < 2) \
274 . ab .escq needs 2 arguments.
275 . Text \f[B]\[rs]\$1\[cq]\f[]\f[I]\$2\f[]\f[B]\[cq]\f[]\$3
276 ..
277 .
278 .c --------- strings ---------
279 .
280 .c synopsis for string, with \*[]
281 .de STRING
282 . ds @1 \$1\"
283 . shift 1
284 . TP 10n
285 . ExecFF Text R CB \[rs]*[ \*[@1]\f[]\f[R]] \$*
286 . rm @1
287 ..
288 .c synopsis for a long string
289 .de string
290 . if (\n[.$] = 0) \
291 . return
292 . Text \f[CB]\[rs]*\[lB]\$1\[rB]\f[]\$2
293 ..
294 .
295 .
296 .c --------- registers ---------
297 .
298 .c synopsis for registers, with \n[]
299 .de REG
300 . ds @1 \$1\"
301 . shift 1
302 . TP 10n
303 . ExecFF Text R CB \[rs]n[ \*[@1]\f[]\f[R]] \$*
304 . rm @1
305 ..
306 .c reference of a register, without decoration
307 .de register
308 . Text register
309 . BR \$*
310 ..
311 .
312 .ec
313 .\" end of macro definitions
314 .
315 .
316 .\" --------------------------------------------------------------------
317 .\" Title
318 .\" --------------------------------------------------------------------
319 .
320 .TH GROFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
321 .SH NAME
322 groff \- a short reference for the GNU roff language
323 .
324 .
325 .\" --------------------------------------------------------------------
326 .SH DESCRIPTION
327 .\" --------------------------------------------------------------------
328 .
329 The name
330 .I groff
331 stands for
332 .I GNU roff
333 and is the free implementation of the roff type-setting system.
334 .
335 See
336 .BR roff (@MAN7EXT@)
337 for a survey and the background of the groff system.
338 .
339 .P
340 This document gives only short descriptions of the predefined roff
341 language elements as used in groff.
342 .
343 Both the classical features and the groff extensions are provided.
344 .
345 .P
346 Historically, the
347 .I roff language
348 was called
349 .IR troff .
350 .I groff
351 is compatible with the classical system and provides proper
352 extensions.
353 .
354 So in GNU, the terms
355 .IR roff ,
356 .IR troff ,
357 and
358 .I groff language
359 could be used as synonyms.
360 .
361 However
362 .I troff
363 slightly tends to refer more to the classical aspects, whereas
364 .I groff
365 emphasizes the GNU extensions, and
366 .I roff
367 is the general term for the language.
368 .
369 .P
370 This file is only a short version of the complete documentation that
371 is found in the
372 .I groff
373 .BR info (1)
374 file, which contains more detailed, actual, and concise information.
375 .
376 .P
377 The general syntax for writing groff documents is relatively easy, but
378 writing extensions to the roff language can be a bit harder.
379 .
380 .P
381 The roff language is line-oriented.
382 .
383 There are only two kinds of lines, control lines and text lines.
384 .
385 The control lines start with a control character, by default a period
386 .dquoted_char .
387 or a single quote
388 .dquoted_char ' ;
389 all other lines are text lines.
390 .
391 .P
392 .B Control lines
393 represent commands, optionally with arguments.
394 .
395 They have the following syntax.
396 .
397 The leading control character can be followed by a command name;
398 arguments, if any, are separated by blanks from the command name and
399 among themselves, for example,
400 .RS
401 .
402 .P
403 .Text .command_name arg1 arg2
404 .RE
405 .
406 .P
407 For indentation, any number of space or tab characters can be inserted
408 between the leading control character and the command name, but the
409 control character must be on the first position of the line.
410 .
411 .P
412 .B Text lines
413 represent the parts that will be printed.
414 They can be modified by escape sequences, which are recognized by a
415 leading backslash
416 .squoted_char \[rs] .
417 These are in-line or even in-word formatting elements or functions.
418 .
419 Some of these take arguments separated by single quotes
420 .dquoted_char ' ,
421 others are regulated by a length encoding introduced by an open
422 parenthesis
423 .squoted_char (
424 or enclosed in brackets
425 .squoted_char [
426 and
427 .squoted_char ] .
428 .
429 .P
430 The roff language provides flexible instruments for writing language
431 extension, such as macros.
432 .
433 When interpreting macro definitions, the roff system enters a special
434 operating mode, called the
435 .BR "copy mode" .
436 .
437 .P
438 The copy mode behavior can be quite tricky, but there are some rules
439 that ensure a safe usage.
440 .
441 .IP 1.
442 Printable backslashes must be denoted as
443 .esc e .
444 To be more precise,
445 .esc e
446 represents the current escape character.
447 .
448 To get a backslash glyph, use
449 .esc (rs
450 or
451 .esc [rs] .
452 .IP 2.
453 Double all backslashes.
454 .IP 3.
455 Begin all text lines with the special non-spacing character
456 .esc & .
457 .
458 .P
459 This does not produce the most efficient code, but it should work as a
460 first measure.
461 .
462 For better strategies, see the groff info file and
463 .BR groff_tmac (@MAN5EXT@).
464 .
465 .P
466 Reading roff source files is easier, just reduce all double backslashes
467 to a single one in all macro definitions.
468 .
469 .
470 .\" --------------------------------------------------------------------
471 .SH "GROFF ELEMENTS"
472 .\" --------------------------------------------------------------------
473 .
474 The roff language elements add formatting information to a text file.
475 .
476 The fundamental elements are predefined commands and variables that
477 make roff a full-blown programming language.
478 .
479 .P
480 There are two kinds of roff commands, possibly with arguments.
481 .B Requests
482 are written on a line of their own starting with a dot
483 .squoted_char .
484 or a
485 .dquoted_char ' ,
486 whereas
487 .B Escape sequences
488 are in-line functions and in-word formatting elements starting with a
489 backslash
490 .squoted_char \[rs] .
491 .
492 .P
493 The user can define her own formatting commands using the
494 .request de
495 request.
496 .
497 These commands are called
498 .BR macros ,
499 but they are used exactly like requests.
500 .
501 Macro packages are pre-defined sets of macros written in the groff
502 language.
503 .
504 A user's possibilities to create escape sequences herself is very
505 limited, only special characters can be mapped.
506 .
507 .P
508 The groff language provides several kinds of variables with
509 different interfaces.
510 .
511 There are pre-defined variables, but the user can define her own
512 variables as well.
513 .
514 .P
515 .B String
516 variables store character sequences.
517 .
518 They are set with the
519 .request ds
520 request and retrieved by the
521 .esc *
522 escape sequences.
523 .
524 .P
525 .B Register
526 variables can store numerical values, numbers with a scale unit, and
527 occasionally string-like objects.
528 .
529 They are set with the
530 .request nr
531 request and retrieved by the
532 .esc n
533 escape sequences.
534 .
535 .P
536 .B Environments
537 allow the user to temporarily store global formatting parameters like
538 line length, font size, etc.\& for later reuse.
539 .
540 This is done by the
541 .request ev
542 request.
543 .
544 .P
545 .B Fonts
546 are identified either by a name or by an internal number.
547 .
548 The current font is chosen by the
549 .request ft
550 request or by the
551 .esc f
552 escape sequences.
553 .
554 Each device has special fonts, but the following fonts are available
555 for all devices.
556 .B R
557 is the standard font Roman.
558 .B B
559 is its
560 .B bold
561 counterpart.
562 .
563 The
564 .I italic
565 font is called
566 .B I
567 is everywhere available, but on text devices, it is displayed as an
568 underlined Roman font.
569 .
570 For the graphical output devices, there exist constant-width pendants
571 of these fonts,
572 .BR CR ,
573 .BR CI ,
574 and
575 .BR CB .
576 On text devices, all characters have a constant width anyway.
577 .
578 .P
579 Moreover, there are some advanced roff elements.
580 .
581 A
582 .B diversion
583 stores information into a macro for later usage.
584 .
585 A
586 .B trap
587 is a positional condition like a certain number of lines from page top
588 or in a diversion or in the input.
589 .
590 Some action can be prescribed to be run automatically when the
591 condition is met.
592 .
593 .P
594 More detailed information and examples can be found in the groff info
595 file.
596 .
597 .
598 .\" --------------------------------------------------------------------
599 .SH "CONTROL CHARACTERS"
600 .\" --------------------------------------------------------------------
601 .
602 There is a small set of characters that have a special controlling
603 task in certain conditions.
604 .
605 .TP
606 .character .
607 A dot is only special at the beginning of a line or after the
608 condition in the requests
609 .request if ,
610 .request ie ,
611 .request el ,
612 and
613 .request while .
614 There it is the control character that introduces a request (or macro).
615 .
616 The special behavior can be delayed by using the
617 .esc .
618 escape.
619 .
620 By using the
621 .request cc
622 request, the control character can be set to a different character,
623 making the dot
624 .squoted_char .
625 a non-special character.
626 .IP ""
627 In all other positions, it just means a dot character.
628 .
629 In text paragraphs, it is advantageous to start each sentence at a
630 line of its own.
631 .
632 .TP
633 .character '
634 The single quote has two controlling tasks.
635 .
636 At the beginning of a line and in the conditional requests it is the
637 non-breaking control character.
638 .
639 That means that it introduces a request like the dot, but with the
640 additional property that this request doesn't cause a linebreak.
641 .
642 By using the
643 .request c2
644 request, the non-break control character can be set to a different
645 character.
646 .
647 .IP ""
648 As a second task, it is the most commonly used argument separator in
649 some functional escape sequences (but any pair of characters not part
650 of the argument will work).
651 .
652 In all other positions, it denotes the single quote or apostrophe
653 character.
654 .
655 Groff provides a printable representation with the
656 .esc (cq
657 escape sequence.
658 .
659 .TP
660 .character \[dq]
661 The double quote is used to enclose arguments in requests and macros.
662 In the
663 .request ds
664 and
665 .request as
666 requests, a leading double quote in the argument will be stripped off,
667 making everything else afterwards the string to be defined (enabling
668 leading whitespace).
669 .
670 The escaped double quote
671 .esc \[dq]
672 introduces a comment.
673 .
674 Otherwise, it is not special.
675 .
676 Groff provides a printable representation with the
677 .esc (dq
678 escape sequence.
679 .
680 .TP
681 .character \[rs]
682 The backslash usually introduces an escape sequence (this can be
683 changed with the
684 .request ec
685 request).
686 .
687 A printed version of the escape character is the
688 .esc e
689 escape; a backslash glyph can be obtained by
690 .esc (rs .
691 .TP
692 .character (
693 The open parenthesis is only special in escape sequences when
694 introducing an escape name or argument consisting of exactly two
695 characters.
696 .
697 In groff, this behavior can be replaced by the \f[CB][]\f[] construct.
698 .TP
699 .character [
700 The opening bracket is only special in groff escape sequences; there
701 it is used to introduce a long escape name or long escape argument.
702 .
703 Otherwise, it is non-special, e.g.\& in macro calls.
704 .TP
705 .character ]
706 The closing bracket is only special in groff escape sequences; there
707 it terminates a long escape name or long escape argument.
708 .
709 Otherwise, it is non-special.
710 .TP
711 \f[CI]space\f[]
712 Space characters are only functional characters.
713 .
714 They separate the arguments in requests or macros, and the words in
715 text lines.
716 .
717 They are subject to groff's horizontal spacing calculations.
718 .
719 To get a defined space width, escape sequences like
720 .squoted_char "\[rs]\ "
721 (this is the escape character followed by a space),
722 .esc | ,
723 .esc ^ ,
724 or
725 .esc h
726 should be used.
727 .
728 .IP \f[CI]newline\f[]
729 In text paragraphs, newlines mostly behave like space characters.
730 .
731 Continuation lines can be specified by an escaped newline, i.e., by
732 specifying a backslash
733 .squoted_char \[rs]
734 as the last character of a line.
735 .IP \f[CI]tab\f[]
736 If a tab character occurs during text the interpreter makes a
737 horizontal jump to the next pre-defined tab position.
738 .
739 There is a sophisticated interface for handling tab positions.
740 .
741 .
742 .\" --------------------------------------------------------------------
743 .SH "NUMERICAL EXPRESSIONS"
744 .\" --------------------------------------------------------------------
745 .
746 A
747 .B numerical value
748 is a signed or unsigned integer or float with or without an appended
749 scaling indicator.
750 .
751 A
752 .B scaling indicator
753 is a one-character abbreviation for a unit of measurement.
754 .
755 A number followed by a scaling indicator signifies a size value.
756 .
757 By default, numerical values do not have a scaling indicator, i.e., they
758 are normal numbers.
759 .
760 .P
761 The
762 .I roff
763 language defines the following scaling indicators.
764 .
765 .
766 .P
767 .PD 0
768 .RS
769 .
770 .TPx
771 .B c
772 Centimeter
773 .
774 .TPx
775 .B i
776 Inch
777 .
778 .TPx
779 .B P
780 Pica\ \[eq]\ 1/6\ inch
781 .
782 .TPx
783 .B p
784 Point\ \[eq]\ 1/72\ inch
785 .
786 .TPx
787 .B m
788 Em\ \[eq]\ \f[R]the font size in points (width of letter `\f[CR]m\f[R]')
789 .
790 .TPx
791 .B M
792 100\^th \f[R]of an \f[CR]Em
793 .
794 .TPx
795 .B n
796 En\ \[eq]\ Em/2
797 .
798 .TPx
799 .B u
800 Basic unit for actual output device
801 .
802 .TPx
803 .B v
804 Vertical line space in basic units
805 scaled point\ \[eq]\ 1/\f[CI]sizescale\f[R] of a point (defined in
806 font \f[I]DESC\f[] file)
807 .
808 .TPx
809 .B f
810 Scale by 65536.
811 .RE
812 .PD
813 .
814 .P
815 .B Numerical expressions
816 are combinations of the numerical values defined above with the
817 following arithmetical operators already defined in classical troff.
818 .
819 .P
820 .PD 0
821 .RS
822 .
823 .TPx
824 .B +
825 Addition
826 .
827 .TPx
828 .B \-
829 Subtraction
830 .
831 .TPx
832 .B *
833 Multiplication
834 .
835 .TPx
836 .B /
837 Division
838 .
839 .TPx
840 .B %
841 Modulo
842 .
843 .TPx
844 .B =
845 Equals
846 .
847 .TPx
848 .B ==
849 Equals
850 .
851 .TPx
852 .B <
853 Less than
854 .
855 .TPx
856 .B >
857 Greater than
858 .
859 .TPx
860 .B <=
861 Less or equal
862 .
863 .TPx
864 .B >=
865 Greater or equal
866 .
867 .TPx
868 .B &
869 Logical and
870 .
871 .TPx
872 .B :
873 Logical or
874 .
875 .TPx
876 .B !
877 Logical not
878 .
879 .TPx
880 .B (
881 Grouping of expressions
882 .
883 .TPx
884 .B )
885 Close current grouping
886 .
887 .RE
888 .PD
889 .
890 .P
891 Moreover,
892 .I groff
893 added the following operators for numerical expressions:
894 .
895 .P
896 .PD 0
897 .RS
898 .
899 .TPx
900 .ExecFF Text I CB e1 >? e2
901 The maximum of
902 .I e1
903 and
904 .IR e2 .
905 .
906 .TPx
907 .ExecFF Text I CB e1 <? e2
908 The minimum of
909 .I e1
910 and
911 .IR e2 .
912 .
913 .TPx
914 .ExecFF Text CB I ( c ; e )
915 Evaluate
916 .I e
917 using
918 .I c
919 as the default scaling indicator.
920 .
921 .RE
922 .PD
923 .
924 .P
925 For details see the groff info file.
926 .
927 .
928 .\" --------------------------------------------------------------------
929 .SH CONDITIONS
930 .\" --------------------------------------------------------------------
931 .
932 .B Conditions
933 occur in tests raised by the
934 .request if ,
935 .request ie ,
936 and the
937 .request while
938 requests.
939 .
940 The following table characterizes the different types of conditions.
941 .
942 .P
943 .PD 0
944 .RS
945 .
946 .TPx
947 .I N
948 A numerical expression
949 .I N
950 yields true if its value is greater than\~0.
951 .
952 .TPx
953 .BI ! N
954 True if the value of
955 .I I
956 is\~0.
957 .
958 .TPx
959 .BI ' s1 ' s2 '
960 True if string\~\c
961 .I s1
962 is identical to string\~\c
963 .IR s2 .
964 .
965 .TPx
966 .BI !' s1 ' s2 '
967 True if string\~\c
968 .I s1
969 is not identical to string\~\c
970 .IR s2 .
971 .
972 .TPx
973 .BI c ch
974 True if there is a character\~\c
975 .I ch
976 available.
977 .
978 .TPx
979 .BI d name
980 True if there is a string, macro, diversion, or request called
981 .IR name .
982 .
983 .TPx
984 .B e
985 Current page number is even.
986 .
987 .TPx
988 .B o
989 Current page number is odd.
990 .
991 .TPx
992 .BI m name
993 True if there is a color called
994 .IR name .
995 .
996 .TPx
997 .B n
998 Formatter is
999 .BR nroff .
1000 .
1001 .TPx
1002 .BI r reg
1003 True if there is a register named
1004 .IR reg .
1005 .
1006 .TPx
1007 .B t
1008 Formatter is
1009 .BR troff .
1010 .
1011 .RE
1012 .PD
1013 .
1014 .
1015 .\" --------------------------------------------------------------------
1016 .SH REQUESTS
1017 .\" --------------------------------------------------------------------
1018 .
1019 This section provides a short reference for the predefined requests.
1020 .
1021 In groff, request and macro names can be arbitrarily long.
1022 .
1023 No bracketing or marking of long names is needed.
1024 .
1025 .P
1026 Most requests take one or more arguments.
1027 .
1028 The arguments are separated by space characters (no tabs!); there is
1029 no inherent limit for their length or number.
1030 .
1031 An argument can be enclosed by a pair of double quotes.
1032 .
1033 This is very handy if an argument contains space characters, e.g.,
1034 .RI \[dq] "arg with space" \[dq]
1035 denotes a single argument.
1036 .
1037 .P
1038 Some requests have optional arguments with a different behaviour.
1039 .
1040 Not all of these details are outlined here.
1041 .
1042 Refer to the groff info file and
1043 .BR groff_diff (@MAN7EXT@)
1044 for all details.
1045 .
1046 .P
1047 In the following request specifications, most argument names were
1048 chosen to be descriptive.
1049 .
1050 Only the following denotations need clarification.
1051 .
1052 .P
1053 .PD 0
1054 .RS
1055 .
1056 .TPx
1057 .I c
1058 denotes a single character.
1059 .
1060 .TPx
1061 .I font
1062 a font either specified as a font name or a font number.
1063 .
1064 .TPx
1065 .I anything
1066 all characters up to the end of the line or within
1067 .esc {
1068 and
1069 .esc } .
1070 .
1071 .TPx
1072 .I n
1073 is a numerical expression that evaluates to an integer value.
1074 .
1075 .TPx
1076 .I N
1077 is an arbitrary numerical expression, signed or unsigned.
1078 .
1079 .TPx
1080 .I \[+-]N
1081 has three meanings depending on its sign, described below.
1082 .
1083 .RE
1084 .PD
1085 .
1086 .P
1087 If an expression defined as
1088 .I \[+-]N
1089 starts with a
1090 .squoted_char +
1091 sign the resulting value of the expression will be added to an already
1092 existing value inherent to the related request, e.g.\& adding to a number
1093 register.
1094 .
1095 If the expression starts with a
1096 .squoted_char -
1097 the value of the expression will be subtracted from the request value.
1098 .
1099 .P
1100 Without a sign,
1101 .I N
1102 replaces the existing value directly.
1103 .
1104 To assign a negative number either prepend\~0 or enclose the negative
1105 number in parentheses.
1106 .
1107 .
1108 .\" --------------------------------------------------------------------
1109 .SS "Request Short Reference"
1110 .\" --------------------------------------------------------------------
1111 .
1112 .PD 0
1113 .
1114 .REQ .
1115 Empty line, ignored.
1116 .
1117 Useful for structuring documents.
1118 .
1119 .REQ .\[rs]\[dq] anything
1120 Complete line is a comment.
1121 .
1122 .REQ .ab string
1123 Print
1124 .I string
1125 on standard error, exit program.
1126 .
1127 .REQ .ad
1128 Begin line adjustment for output lines in current adjust mode.
1129 .
1130 .REQ .ad c
1131 Start line adjustment in mode
1132 .I c
1133 (\f[CI]c\f[]\f[CR]\|\^\[eq]\|l,r,b,n\f[]).
1134 .
1135 .REQ .af register c
1136 Assign format
1137 .I c
1138 to
1139 .I register
1140 (\f[CI]c\f[]\f[CR]\|\^\[eq]\|l,i,I,a,A\f[]).
1141 .
1142 .REQ .aln alias register
1143 Create alias name for
1144 .IR register .
1145 .
1146 .REQ .als alias object
1147 Create alias name for request, string, macro, or diversion
1148 .IR object .
1149 .
1150 .REQ .am macro
1151 Append to
1152 .I macro
1153 until
1154 .B ..\&
1155 is encountered.
1156 .
1157 .REQ .am macro end
1158 Append to
1159 .I macro
1160 until
1161 .request .end
1162 is called.
1163 .
1164 .REQ .ami macro
1165 Append to a macro whose name is contained in the string register
1166 .I macro
1167 until
1168 .B ..\&
1169 is encountered.
1170 .
1171 .REQ .ami macro end
1172 Append to a macro indirectly.
1173 .I macro
1174 and
1175 .I end
1176 are string registers whose contents are interpolated for the macro name
1177 and the end macro, respectively.
1178 .
1179 .REQ .am1 macro
1180 Same as
1181 .request .am
1182 but with compatibility mode switched off during macro expansion.
1183 .
1184 .REQ .am1 macro end
1185 Same as
1186 .request .am
1187 but with compatibility mode switched off during macro expansion.
1188 .
1189 .REQ .as stringvar anything
1190 Append
1191 .I anything
1192 to
1193 .IR stringvar .
1194 .
1195 .REQ .asciify diversion
1196 Unformat ASCII characters, spaces, and some escape sequences in
1197 .IR diversion .
1198 .
1199 .REQ .as1 stringvar anything
1200 Same as
1201 .request .as
1202 but with compatibility mode switched off during string expansion.
1203 .
1204 .REQ .backtrace
1205 Print a backtrace of the input on stderr.
1206 .
1207 .REQ .bd font N
1208 Embolden
1209 .I font
1210 by
1211 .IR N -1
1212 units.
1213 .
1214 .REQ .bd S font N
1215 Embolden Special Font
1216 .I S
1217 when current font is
1218 .IR font .
1219 .
1220 .REQ .blm
1221 Unset the blank line macro.
1222 .
1223 .REQ .blm macro
1224 Set the blank line macro to
1225 .IR macro .
1226 .
1227 .REQ .box
1228 End current diversion.
1229 .
1230 .REQ .box macro
1231 Divert to
1232 .IR macro ,
1233 omitting a partially filled line.
1234 .
1235 .REQ .boxa
1236 End current diversion.
1237 .
1238 .REQ .boxa macro
1239 Divert and append to
1240 .IR macro ,
1241 omitting a partially filled line.
1242 .
1243 .REQ .bp
1244 Eject current page and begin new page.
1245 .
1246 .REQ .bp \[+-]N
1247 Eject current page; next page number
1248 .IR \[+-]N .
1249 .
1250 .REQ .br
1251 Line break.
1252 .
1253 .REQ .brp
1254 Break and spread output line.
1255 Same as
1256 .esc p .
1257 .
1258 .REQ .break
1259 Break out of a while loop.
1260 .
1261 .REQ .c2
1262 Reset no-break control character to
1263 .dquoted_char ' .
1264 .
1265 .REQ .c2 c
1266 Set no-break control character to
1267 .IR c .
1268 .
1269 .REQ .cc
1270 Reset control character to
1271 .squoted_char . .
1272 .
1273 .REQ .cc c
1274 Set control character to
1275 .IR c .
1276 .
1277 .REQ .ce
1278 Center the next input line.
1279 .
1280 .REQ .ce N
1281 Center following
1282 .I N
1283 input lines.
1284 .
1285 .REQ .cf filename
1286 Copy contents of file
1287 .I filename
1288 unprocessed to stdout or to the diversion.
1289 .
1290 .REQ .cflags mode c1 c2 .\|.\|.\&
1291 Treat characters
1292 .IR c1 ,
1293 .IR c2 ,
1294 .I .\|.\|.\&
1295 according to
1296 .I mode
1297 number.
1298 .
1299 .REQ .ch trap N
1300 Change
1301 .I trap
1302 location
1303 to
1304 .I N .
1305 .
1306 .REQ .char c anything
1307 Define character
1308 .I c
1309 as string
1310 .IR anything .
1311 .
1312 .REQ .chop object
1313 Chop the last character off macro, string, or diversion
1314 .IR object .
1315 .
1316 .REQ .close stream
1317 Close the
1318 .IR stream .
1319 .
1320 .REQ .continue
1321 Finish the current iteration of a while loop.
1322 .
1323 .REQ .cp
1324 Enable compatibility mode.
1325 .
1326 .REQ .cp N
1327 If
1328 .I N
1329 is zero disable compatibility mode, otherwise enable it.
1330 .
1331 .REQ .cs font N M
1332 Set constant character width mode for
1333 .I font
1334 to
1335 .IR N /36
1336 ems with em
1337 .IR M .
1338 .
1339 .REQ .cu N
1340 Continuous underline in nroff, like
1341 .request .ul
1342 in troff.
1343 .
1344 .REQ .da
1345 End current diversion.
1346 .
1347 .REQ .da macro
1348 Divert and append to
1349 .IR macro .
1350 .
1351 .REQ .de macro
1352 Define or redefine
1353 .I macro
1354 until
1355 .B ..\&
1356 is encountered.
1357 .
1358 .REQ .de macro end
1359 Define or redefine
1360 .I macro
1361 until
1362 .request .end
1363 is called.
1364 .
1365 .REQ .de1 macro
1366 Same as
1367 .request .de
1368 but with compatibility mode switched off during macro expansion.
1369 .
1370 .REQ .de1 macro end
1371 Same as
1372 .request .de
1373 but with compatibility mode switched off during macro expansion.
1374 .
1375 .REQ .defcolor color scheme component
1376 Define or redefine a color with name
1377 .IR color .
1378 .I scheme
1379 can be
1380 .BR rgb ,
1381 .BR cym ,
1382 .BR cymk ,
1383 .BR gray ,
1384 or
1385 .BR grey .
1386 .I component
1387 can be single components specified as fractions in the range 0 to 1
1388 (default scaling indicator\~\c
1389 .scaleindicator f ),
1390 as a string of two-digit hexadecimal color components with a leading
1391 .BR # ,
1392 or as a string of four-digit hexadecimal components with two leading
1393 .BR # .
1394 The color
1395 .B default
1396 can't be redefined.
1397 .
1398 .REQ .dei macro
1399 Define or redefine a macro whose name is contained in the string register
1400 .I macro
1401 until
1402 .B ..\&
1403 is encountered.
1404 .
1405 .REQ .dei macro end
1406 Define or redefine a macro indirectly.
1407 .I macro
1408 and
1409 .I end
1410 are string registers whose contents are interpolated for the macro name
1411 and the end macro, respectively.
1412 .
1413 .REQ .di
1414 End current diversion.
1415 .
1416 .REQ .di macro
1417 Divert to
1418 .I macro .
1419 .
1420 .REQ .do name
1421 Interpret
1422 .request .name
1423 with compatibility mode disabled.
1424 .
1425 .REQ .ds stringvar anything
1426 Set
1427 .I stringvar
1428 to
1429 .IR anything .
1430 .
1431 .REQ .ds1 stringvar anything
1432 Same as
1433 .request .ds
1434 but with compatibility mode switched off during string expansion.
1435 .
1436 .REQ .dt N trap
1437 Set diversion trap to position
1438 .I N
1439 (default scaling indicator\~\c
1440 .scaleindicator v ).
1441 .
1442 .REQ .ec
1443 Reset escape character to
1444 .squoted_char \[rs] .
1445 .
1446 .REQ .ec c
1447 Set escape character to
1448 .IR c .
1449 .
1450 .REQ .ecr
1451 Restore escape character saved with
1452 .request .ecs .
1453 .
1454 .REQ .ecs
1455 Save current escape character.
1456 .
1457 .REQ .el anything
1458 Else part for if-else (\c
1459 .request ie )
1460 request.
1461 .
1462 .REQ .em macro
1463 The
1464 .I macro
1465 will be run after the end of input.
1466 .
1467 .REQ .eo
1468 Turn off escape character mechanism.
1469 .
1470 .REQ .ev
1471 Switch to previous environment.
1472 .
1473 .REQ .ev env
1474 Push down environment number or name
1475 .I env
1476 and switch to it.
1477 .
1478 .REQ .evc env
1479 Copy the contents of environment
1480 .I env
1481 to the current environment.
1482 No pushing or popping.
1483 .
1484 .REQ .ex
1485 Exit from roff processing.
1486 .
1487 .REQ .fam
1488 Return to previous font family.
1489 .
1490 .REQ .fam name
1491 Set the current font family to
1492 .IR name .
1493 .
1494 .REQ .fc
1495 Disable field mechanism.
1496 .
1497 .REQ .fc a
1498 Set field delimiter to
1499 .I a
1500 and pad character to space.
1501 .
1502 .REQ .fc a b
1503 Set field delimiter to
1504 .I a
1505 and pad character to
1506 .IR b .
1507 .
1508 .REQ .fchar c anything
1509 Define fallback character
1510 .I c
1511 as string
1512 .IR anything .
1513 .
1514 .REQ .fi
1515 Fill output lines.
1516 .
1517 .REQ .fl
1518 Flush output buffer.
1519 .
1520 .REQ .fp n font
1521 Mount
1522 .I font
1523 on position
1524 .IR n .
1525 .
1526 .REQ .fp n internal external
1527 Mount font with long
1528 .I external
1529 name to short
1530 .I internal
1531 name on position
1532 .IR n .
1533 .
1534 .REQ .fspecial font s1 s2 .\|.\|.\&
1535 When the current font is
1536 .IR font ,
1537 then the fonts
1538 .IR s1 ,
1539 .IR s2 ,
1540 .I .\|.\|.\&
1541 will be special.
1542 .
1543 .REQ .ft
1544 Return to previous font.
1545 Same as
1546 .request \[rs]f[]
1547 or
1548 .request \[rs]fP .
1549 .
1550 .REQ .ft font
1551 Change to font name or number
1552 .IR font ;
1553 same as
1554 .esc[] f font
1555 escape sequence.
1556 .
1557 .REQ .ftr font1 font2
1558 Translate
1559 .I font1
1560 to
1561 .IR font2 .
1562 .
1563 .REQ .hc
1564 Remove additional hyphenation indicator character.
1565 .
1566 .REQ .hc c
1567 Set up additional hyphenation indicator character\~\c
1568 .IR c .
1569 .
1570 .REQ .hcode c1 code1 c2 code2 .\|.\|.\&
1571 Set the hyphenation code of character
1572 .I c1
1573 to
1574 .IR code1 ,
1575 that of
1576 .I c2
1577 to
1578 .IR code2 ,
1579 etc.
1580 .
1581 .REQ .hla lang
1582 Set the current hyphenation language to
1583 .IR lang .
1584 .
1585 .REQ .hlm n
1586 Set the maximum number of consecutive hyphenated lines to
1587 .IR n .
1588 .
1589 .REQ .hpf file
1590 Read hyphenation patterns from
1591 .IR file .
1592 .
1593 .REQ .hpfa file
1594 Append hyphenation patterns from
1595 .IR file .
1596 .
1597 .REQ .hpfcode file
1598 Set input mapping for
1599 .request .hpf .
1600 .
1601 .REQ .hw words
1602 List of
1603 .I words
1604 with exceptional hyphenation.
1605 .
1606 .REQ .hy N
1607 Switch to hyphenation mode
1608 .IR N .
1609 .
1610 .REQ .hym n
1611 Set the hyphenation margin to
1612 .I n
1613 (default scaling indicator\~\c
1614 .scaleindicator m ).
1615 .
1616 .REQ .hys n
1617 Set the hyphenation space to
1618 .IR n .
1619 .
1620 .REQ .ie cond anything
1621 If
1622 .I cond
1623 then
1624 .I anything
1625 else goto
1626 .request .el .
1627 .
1628 .REQ .if cond anything
1629 If
1630 .I cond
1631 then
1632 .IR anything ;
1633 otherwise do nothing.
1634 .
1635 .REQ .ig
1636 Ignore text until
1637 .B ..\&
1638 is encountered.
1639 .
1640 .REQ .ig end
1641 Ignore text until
1642 .request .end .
1643 .
1644 .REQ .in
1645 Change to previous indent value.
1646 .
1647 .REQ .in \[+-]N
1648 Change indent according to
1649 .I \[+-]N
1650 (default scaling indicator\~\c
1651 .scaleindicator m ).
1652 .
1653 .REQ .it N trap
1654 Set an input-line count trap for the next
1655 .I N
1656 lines.
1657 .
1658 .REQ .itc N trap
1659 Same as
1660 .request .it
1661 but count lines interrupted with
1662 .esc c
1663 as one line.
1664 .
1665 .REQ .kern
1666 Enable pairwise kerning.
1667 .
1668 .REQ .kern n
1669 If
1670 .I n
1671 is zero, disable pairwise kerning, otherwise enable it.
1672 .
1673 .REQ .lc
1674 Remove leader repetition character.
1675 .
1676 .REQ .lc c
1677 Set leader repetition character to\~\c
1678 .IR c .
1679 .
1680 .REQ .length register anything
1681 Write the length of the string
1682 .I anything
1683 in
1684 .IR register .
1685 .
1686 .REQ .linetabs
1687 Enable line-tabs mode (i.e., calculate tab positions relative to output
1688 line).
1689 .
1690 .REQ .linetabs n
1691 If
1692 .I n
1693 is zero, disable line-tabs mode, otherwise enable it.
1694 .
1695 .REQ .lf N file
1696 Set input line number to
1697 .I N
1698 and filename to
1699 .IR file .
1700 .
1701 .REQ .lg N
1702 Ligature mode on if
1703 .IR N >0.
1704 .
1705 .REQ .ll
1706 Change to previous line length.
1707 .
1708 .REQ .ll \[+-]N
1709 Set line length according to
1710 .I \[+-]N
1711 (default size
1712 .scalednumber 6.5 i ,
1713 default scaling indicator\~\c
1714 .scaleindicator m ).
1715 .
1716 .REQ .ls
1717 Change to the previous value of additional intra-line skip.
1718 .
1719 .REQ .ls N
1720 Set additional intra-line skip value to
1721 .IR N ,
1722 i.e.,
1723 .IR N -1
1724 blank lines are inserted after each text output line.
1725 .
1726 .REQ .lt \[+-]N
1727 Length of title (default scaling indicator\~\c
1728 .scaleindicator m ).
1729 .
1730 .REQ .mc
1731 Margin character off.
1732 .
1733 .REQ .mc c
1734 Print character
1735 .I c
1736 after each text line at actual distance from right margin.
1737 .
1738 .REQ .mc c N
1739 Set margin character to
1740 .I c
1741 and distance to
1742 .I N
1743 from right margin (default scaling indicator\~\c
1744 .scaleindicator m ).
1745 .
1746 .REQ .mk register
1747 Mark current vertical position in
1748 .IR register .
1749 .
1750 .REQ .mso file
1751 The same as the .so request except that
1752 .I file
1753 is searched in the tmac directories.
1754 .
1755 .REQ .na
1756 No output-line adjusting.
1757 .
1758 .REQ .ne
1759 Need a one-line vertical space.
1760 .
1761 .REQ .ne N
1762 Need
1763 .I N
1764 vertical space (default scaling indicator\~\c
1765 .scaleindicator v ).
1766 .
1767 .REQ .nf
1768 No filling or adjusting of output-lines.
1769 .
1770 .REQ .nh
1771 No hyphenation.
1772 .
1773 .REQ .nm
1774 Number mode off.
1775 .
1776 .REQ .nm \[+-]N \fR[\fPM \fR[\fPS \fR[\fPI\fR]]]\fP
1777 In line number mode, set number, multiple, spacing, and indent.
1778 .
1779 .REQ .nn
1780 Do not number next line.
1781 .
1782 .REQ .nn N
1783 Do not number next
1784 .I N
1785 lines.
1786 .
1787 .REQ .nop anything
1788 Always execute
1789 .IR anything .
1790 .
1791 .REQ .nr register \[+-]N M
1792 Define or modify
1793 .I register
1794 using
1795 .I \[+-]N
1796 with auto-increment
1797 .IR M .
1798 .
1799 .REQ .nroff
1800 Make the built-in condition
1801 .B n
1802 true and
1803 .B t
1804 false.
1805 .
1806 .REQ .ns
1807 Turn no-space mode on.
1808 .
1809 .REQ .nx
1810 Immediately jump to end of current file.
1811 .
1812 .REQ .nx filename
1813 Next file.
1814 .
1815 .REQ .open stream filename
1816 Open
1817 .register filename
1818 for writing and associate the stream named
1819 .register stream
1820 with it.
1821 .
1822 .REQ .opena stream filename
1823 Like
1824 .request .open
1825 but append to it.
1826 .
1827 .REQ .os
1828 Output vertical distance that was saved by the
1829 .request sv
1830 request.
1831 .
1832 .REQ .pc
1833 Reset page number character to\~\c
1834 .squoted_char % .
1835 .
1836 .REQ .pc c
1837 Page number character.
1838 .
1839 .REQ .pi program
1840 Pipe output to
1841 .I program
1842 (nroff only).
1843 .
1844 .REQ .pl
1845 Set page length to default
1846 .scalednumber 11 i .
1847 The current page length is stored in
1848 .register .p .
1849 .
1850 .REQ .pl \[+-]N
1851 Change page length to
1852 .I \[+-]N
1853 (default scaling indicator\~\c
1854 .scaleindicator v ).
1855 .
1856 .REQ .pm
1857 Print macro names and sizes (number of blocks of 128 bytes).
1858 .
1859 .REQ ".pm t"
1860 Print only total of sizes of macros (number of 128 bytes blocks).
1861 .
1862 .REQ .pn \[+-]N
1863 Next page number
1864 .IR N .
1865 .
1866 .REQ .pnr
1867 Print the names and contents of all currently defined number registers
1868 on stderr.
1869 .
1870 .REQ .po
1871 Change to previous page offset.
1872 .
1873 The current page offset is available in
1874 .register .o .
1875 .
1876 .REQ .po \[+-]N
1877 Page offset
1878 .IR N .
1879 .
1880 .REQ .ps
1881 Return to previous point-size.
1882 .REQ .ps \[+-]N
1883 Point size; same as
1884 .esc[] s \[+-]N .
1885 .
1886 .REQ .psbb filename
1887 Get the bounding box of a PostScript image
1888 .IR filename .
1889 .
1890 .REQ .pso command
1891 This behaves like the
1892 .request so
1893 request except that input comes from the standard output of
1894 .IR command .
1895 .
1896 .REQ .ptr
1897 Print the names and positions of all traps (not including input line
1898 traps and diversion traps) on stderr.
1899 .
1900 .REQ .pvs
1901 Change to previous post-vertical line spacing.
1902 .
1903 .REQ .pvs \[+-]N
1904 Change post-vertical line spacing according to
1905 .I \[+-]N
1906 (default scaling indicator\~\c
1907 .scaleindicator p ).
1908 .
1909 .REQ .rchar c1 c2 .\|.\|.\&
1910 Remove the definitions of characters
1911 .IR c1 ,
1912 .IR c2 ,
1913 .I .\|.\|.\&
1914 .
1915 .REQ .rd prompt
1916 Read insertion.
1917 .
1918 .REQ .return
1919 Return from a macro.
1920 .
1921 .REQ .rj n
1922 Right justify the next
1923 .I n
1924 input lines.
1925 .
1926 .REQ .rm name
1927 Remove request, macro, or string
1928 .IR name .
1929 .
1930 .REQ .rn old new
1931 Rename request, macro, or string
1932 .I old
1933 to
1934 .IR new .
1935 .
1936 .REQ .rnn reg1 reg2
1937 Rename register
1938 .I reg1
1939 to
1940 .IR reg2 .
1941 .
1942 .REQ .rr register
1943 Remove
1944 .IR register .
1945 .
1946 .REQ .rs
1947 Restore spacing; turn no-space mode off.
1948 .
1949 .REQ .rt \[+-]N
1950 Return
1951 .I (upward only)
1952 to marked vertical place (default scaling indicator\~\c
1953 .scaleindicator v ).
1954 .
1955 .REQ .shc
1956 Reset soft hyphen character to
1957 .esc (hy .
1958 .
1959 .REQ .shc c
1960 Set the soft hyphen character to
1961 .IR c .
1962 .
1963 .REQ .shift n
1964 In a macro, shift the arguments by
1965 .IR n \~\c
1966 positions.
1967 .
1968 .REQ .sizes s1 s2 .\|.\|.\& sn \fB[0]\fP
1969 Set available font sizes similar to the
1970 .B sizes
1971 command in a
1972 .B DESC
1973 file.
1974 .
1975 .REQ .so filename
1976 Include source file.
1977 .
1978 .REQ .sp
1979 Skip one line vertically.
1980 .
1981 .REQ .sp N
1982 Space vertical distance
1983 .I N
1984 up or down according to sign of
1985 .I N
1986 (default scaling indicator\~\c
1987 .scaleindicator v ).
1988 .
1989 .REQ .special s1 s2 .\|.\|.\&
1990 Fonts
1991 .IR s1 ,
1992 .IR s2 ,
1993 etc.\& are special and will be searched for characters not in the
1994 current font.
1995 .
1996 .REQ .spreadwarn
1997 Toggle the spread warning on and off without changing its value.
1998 .
1999 .REQ .spreadwarn limit
2000 Emit a warning if each space in an output line is widened by
2001 .I limit
2002 or more (default scaling indicator\~\c
2003 .scaleindicator m ).
2004 .
2005 .REQ .ss N
2006 Space-character size set to
2007 .IR N /12
2008 of the spacewidth in the current font.
2009 .
2010 .REQ .ss N M
2011 Space-character size set to
2012 .IR N /12
2013 and sentence space size set to
2014 .IR M /12
2015 of the spacewidth in the current font (\f[CR]\[eq]1/3 em\f[]).
2016 .
2017 .REQ .sty n style
2018 Associate
2019 .I style
2020 with font position
2021 .IR n .
2022 .
2023 .REQ .substring register n1 n2
2024 Replace the string in
2025 .I register
2026 with the substring defined by the indices
2027 .I n1
2028 and
2029 .IR n2 .
2030 .
2031 .REQ .sv
2032 Save
2033 .scalednumber 1 v
2034 of vertical space.
2035 .
2036 .REQ .sv N
2037 Save the vertical distance
2038 .I N
2039 for later output with
2040 .request os
2041 request.
2042 .
2043 .REQ .sy command-line
2044 Execute program
2045 .IR command-line .
2046 .
2047 .REQ ".ta T" N
2048 Set tabs after every position that is a multiple of
2049 .I N
2050 (default scaling indicator\~\c
2051 .scaleindicator m ).
2052 .REQ .ta n1 n2 .\|.\|.\& nn \f[CB]T\f[] r1 r2 .\|.\|.\& rn
2053 Set tabs at positions
2054 .IR n1 ,
2055 .IR n2 ,
2056 .Text .\|.\|.,
2057 .IR nn ,
2058 then set tabs at
2059 .IR nn + r1 ,
2060 .IR nn + r2 ,
2061 .Text .\|.\|.,
2062 .IR nn + rn ,
2063 then at
2064 .IR nn + rn + r1 ,
2065 .IR nn + rn + r2 ,
2066 .Text .\|.\|.,
2067 .IR nn + rn + rn ,
2068 and so on.
2069 .
2070 .\".REQ .tar
2071 .\"Restore internally saved tab positions.
2072 .\".
2073 .\".REQ .tas
2074 .\"Save tab positions internally.
2075 .
2076 .REQ .tc
2077 Remove tab repition character.
2078 .REQ .tc c
2079 Set tab repetition character to\~\c
2080 .IR c .
2081 .
2082 .REQ .ti \[+-]N
2083 Temporary indent next line (default scaling indicator\~\c
2084 .scaleindicator m ).
2085 .
2086 .REQ .tkf font s1 n1 s2 n2
2087 Enable track kerning for
2088 .IR font .
2089 .
2090 .REQ .tl \f[CB]\[cq]\f[]left\f[CB]\[cq]\f[]center\f[CB]\[cq]\f[]right\f[CB]\[cq]\f[]
2091 Three-part title.
2092 .
2093 .REQ .tm anything
2094 Print
2095 .I anything
2096 on terminal (UNIX standard message output).
2097 .
2098 .REQ .tm1 anything
2099 Print
2100 .I anything
2101 on terminal (UNIX standard message output), allowing leading
2102 whitespace if
2103 .I anything
2104 starts with
2105 .character \[dq]
2106 (which will be stripped off).
2107 .
2108 .REQ .tmc anything
2109 Similar to
2110 .request .tm1
2111 without emitting a final newline.
2112 .
2113 .REQ .tr abcd.\|.\|.\&
2114 Translate
2115 .I a
2116 to
2117 .IR b ,
2118 .I c
2119 to
2120 .IR d ,
2121 etc.\& on output.
2122 .
2123 .REQ .trf filename
2124 Transparently output the contents of file
2125 .IR filename .
2126 .
2127 .REQ .trin abcd.\|.\|.\&
2128 This is the same as the
2129 .request tr
2130 request except that the
2131 .B asciify
2132 request will use the character code (if any) before the character
2133 translation.
2134 .
2135 .REQ .trnt abcd.\|.\|.\&
2136 This is the same as the
2137 .request tr
2138 request except that the translations do not apply to text that is
2139 transparently throughput into a diversion with
2140 .esc ! .
2141 .
2142 .REQ .troff
2143 Make the built-in condition
2144 .B t
2145 true and
2146 .B n
2147 false.
2148 .
2149 .REQ .uf font
2150 Underline font set to
2151 .I font
2152 (to be switched to by
2153 .request .ul ).
2154 .
2155 .REQ .ul N
2156 Underline (italicize in troff)
2157 .I N
2158 input lines.
2159 .
2160 .REQ .unformat diversion
2161 Unformat space characters and tabs, preserving font information in
2162 .IR diversion .
2163 .REQ .vpt n
2164 Enable vertical position traps if
2165 .I n
2166 is non-zero, disable them otherwise.
2167 .
2168 .REQ .vs
2169 Change to previous vertical base line spacing.
2170 .
2171 .REQ .vs \[+-]N
2172 Set vertical base line spacing according to
2173 .I \[+-]N
2174 (default scaling indicator\~\c
2175 .scaleindicator p ).
2176 Default value is
2177 .scalednumber 12 p .
2178 .
2179 .REQ .warn n
2180 Set warnings code to
2181 .IR n .
2182 .
2183 .REQ .warnscale si
2184 Set scaling indicator used in warnings to
2185 .IR si .
2186 .
2187 .REQ .wh N
2188 Remove (first) trap at position
2189 .IR N .
2190 .
2191 .REQ .wh N trap
2192 Set location trap; negative means from page bottom.
2193 .
2194 .REQ .while cond anything
2195 While condition
2196 .I cond
2197 is true, accept
2198 .I anything
2199 as input.
2200 .
2201 .REQ .write stream anything
2202 Write
2203 .I anything
2204 to the stream named
2205 .IR stream .
2206 .
2207 .REQ .writec stream anything
2208 Similar to
2209 .request .write
2210 without emitting a final newline.
2211 .
2212 .REQ .writem stream xx
2213 Write contents of macro or string
2214 .I xx
2215 to the stream named
2216 .IR stream .
2217 .
2218 .PD
2219 .
2220 .P
2221 Besides these standard groff requests, there might be further macro
2222 calls.
2223 They can originate from a macro package (see
2224 .BR roff (@MAN7EXT@)
2225 for an overview) or from a preprocessor.
2226 .
2227 .P
2228 Preprocessor macros are easy to be recognized.
2229 .
2230 They enclose their code into a pair of characteristic macros.
2231 .
2232 .P
2233 .TS
2234 box, center, tab (@);
2235 c | c | c
2236 CfCB | CfCB | CfCB.
2237 preprocessor@start macro@ end macro
2238 =
2239 eqn@.PS@.PE
2240 grap@.G1@.G2
2241 grn@.GS@.GE
2242 pic@.PS@.PE
2243 refer@.R1@.R2
2244 soelim@\f[I]none@\f[I]none
2245 tbl@.TS@.TE
2246 .TE
2247 .P
2248 .
2249 .
2250 .\" --------------------------------------------------------------------
2251 .SH "ESCAPE SEQUENCES"
2252 .\" --------------------------------------------------------------------
2253 .
2254 Escape sequences are in-line language elements usually introduced by a
2255 backslash
2256 .squoted_char \[rs]
2257 and followed by an escape name and sometimes by a required argument.
2258 .
2259 Input processing is continued directly after the escaped character or
2260 the argument resp.\& without an intervening separation character.
2261 .
2262 So there must be a way to determine the end of the escape name and the
2263 end of the argument.
2264 .
2265 .P
2266 This is done by enclosing names (escape name and arguments consisting
2267 of a variable name) by a pair of brackets
2268 .BI \[lB] name \[rB]
2269 and constant arguments (number expressions and characters) by
2270 apostrophes (ASCII 0x27) like
2271 .BI \[cq] constant \[cq] \f[R].
2272 .
2273 .P
2274 There are abbreviations for short names.
2275 .
2276 Two character escape names can be specified by an opening parenthesis
2277 like
2278 .esc ( xy
2279 without a closing counterpart.
2280 .
2281 And all one-character names different from the special characters
2282 .squoted_char [
2283 and
2284 .squoted_char (
2285 can even be specified without a marker in the form
2286 .esc c .
2287 .
2288 .P
2289 Constant arguments of length\~1 can omit the marker apostrophes, too,
2290 but there is no two-character analogue.
2291 .
2292 .P
2293 While 1-character escape sequences are mainly used for in-line
2294 functions and system related tasks, the 2-letter names following the
2295 .esc (
2296 construct are used for special characters predefined by the roff system.
2297 .
2298 Escapes sequences with names of more than two characters
2299 .esc[] "" name
2300 denote user defined named characters (see the
2301 .request char
2302 request).
2303 .
2304 .
2305 .\" --------------------------------------------------------------------
2306 .SS "Single Character Escapes"
2307 .\" --------------------------------------------------------------------
2308 .
2309 .PD 0
2310 .
2311 .\" --------- comments ---------
2312 .
2313 .ESC \[dq]
2314 Beginning of a comment.
2315 .
2316 Everything up to the end of the line is ignored.
2317 .
2318 .ESC #
2319 Everything up to and including the next newline is ignored.
2320 .
2321 This is interpreted in copy mode.
2322 .
2323 This is like
2324 .esc \[dq]
2325 except that the terminating newline is ignored as well.
2326 .
2327 .\" --------- strings ---------
2328 .
2329 .ESC *\f[I]s\f[]
2330 The string stored in the string variable with 1-character name
2331 .IR s .
2332 .
2333 .ESC *(\f[I]st\f[]
2334 The string stored in the string variable with 2-character name
2335 .IR st .
2336 .
2337 .ESC[] * stringvar
2338 The string stored in the string variable with arbitrary length name
2339 .IR stringvar .
2340 .
2341 .\" --------- macro arguments ---------
2342 .
2343 .ESC $0
2344 The name by which the current macro was invoked.
2345 .
2346 The
2347 .request als
2348 request can make a macro have more than one name.
2349 .
2350 .ESC $ x
2351 Macro argument with 1-place number
2352 .IR x ,
2353 where
2354 .I x
2355 is a digit between 1 and 9.
2356 .
2357 .ESC $( xy
2358 Macro argument with 2-digit number
2359 .IR xy .
2360 .
2361 .ESC[] $ nexp
2362 Macro argument with number
2363 .IR nexp ,
2364 where
2365 .I nexp
2366 is a numerical expression evaluating to an integer \[>=]1.
2367 .
2368 .ESC $*
2369 In a macro, the concatenation of all the arguments separated by spaces.
2370 .
2371 .ESC $@
2372 In a macro, the concatenation of all the arguments with each surrounded
2373 by double quotes, and separated by spaces.
2374 .
2375 .\" --------- escaped characters ---------
2376 .
2377 .ESC \[rs]
2378 reduces to a single backslash; useful to delay its interpretation as
2379 escape character in copy mode.
2380 .
2381 For a printable backslash, use
2382 .esc e ,
2383 or even better
2384 .esc [rs] ,
2385 to be independent from the current escape character.
2386 .
2387 .ESC \[cq]
2388 The acute accent \[aa]; same as
2389 .esc (aa .
2390 Unescaped: apostrophe, right quotation mark, single quote (ASCII 0x27).
2391 .
2392 .ESC `
2393 The grave accent \[ga]; same as
2394 .esc (ga .
2395 Unescaped: left quote, backquote (ASCII 0x60).
2396 .
2397 .ESC \-
2398 The \- sign in the current font.
2399 .
2400 .ESC .
2401 An uninterpreted dot (period), even at start of line.
2402 .
2403 .ESC %
2404 Default optional hyphenation character.
2405 .
2406 .ESC !
2407 Transparent line indicator.
2408 .
2409 .ESC? anything
2410 In a diversion, this will transparently embed
2411 .I anything
2412 in the diversion.
2413 .I anything
2414 is read in copy mode.
2415 .
2416 See also the escape sequences
2417 .esc !
2418 and
2419 .esc ? .
2420 .
2421 .
2422 .\" --------- spacing ---------
2423 .
2424 .ESC \& space
2425 Unpaddable space-size space character (no line break).
2426 .
2427 .ESC 0
2428 Digit width.
2429 .
2430 .ESC |
2431 1/6\ em narrow space character; zero width in nroff.
2432 .
2433 .ESC ^
2434 1/12\ em half-narrow space character; zero width in nroff.
2435 .
2436 .ESC &
2437 Non-printable, zero width character.
2438 .
2439 .ESC )
2440 Like
2441 .esc &
2442 except that it behaves like a character declared with the cflags
2443 request to be transparent for the purposes of end of sentence
2444 recognition.
2445 .
2446 .ESC /
2447 Increases the width of the preceding character so that the spacing
2448 between that character and the following character will be correct if
2449 the following character is a roman character.
2450 .
2451 .ESC ,
2452 Modifies the spacing of the following character so that the spacing
2453 between that character and the preceding character will correct if the
2454 preceding character is a roman character.
2455 .
2456 .ESC ~
2457 Unbreakable space that stretches like a normal inter-word space when a
2458 line is adjusted.
2459 .
2460 .ESC :
2461 Inserts a zero-width break point (similar to
2462 .esc %
2463 but without a soft hyphen character).
2464 .
2465 .ESC "" newline
2466 Ignored newline, for continuation lines.
2467 .
2468 .\" --------- structuring ---------
2469 .
2470 .ESC {
2471 Begin conditional input.
2472 .
2473 .ESC }
2474 End conditional input.
2475 .
2476 .\" --------- longer escape names ---------
2477 .
2478 .ESC ( sc
2479 The special character with 2-character name
2480 .IR sc ,
2481 see section
2482 .BR "Special Characters" .
2483 .
2484 .ESC[] "" name
2485 The named character with arbitrary length name
2486 .IR name .
2487 .
2488 .\" --------- alphabetical escapes ---------
2489 .
2490 .ESC a
2491 Non-interpreted leader character.
2492 .
2493 .ESCq A anything
2494 If
2495 .I anything
2496 is acceptable as a name of a string, macro, diversion, register,
2497 environment or font it expands to\~1, and to\~0 otherwise.
2498 .
2499 .ESCq b abc.\|.\|.\&
2500 Bracket building function.
2501 .
2502 .ESCq B anything
2503 If
2504 .I anything
2505 is acceptable as a valid numeric expression it expands to\~1, and
2506 to\~0 otherwise.
2507 .
2508 .ESC c
2509 Interrupt text processing.
2510 .
2511 .ESCq C char
2512 The character called
2513 .IR char ;
2514 same as
2515 .esc[] "" char ,
2516 but compatible to other roff versions.
2517 .
2518 .ESC d
2519 Forward (down) 1/2 em vertical unit (1/2 line in nroff).
2520 .
2521 .ESCq D charseq
2522 Draw a graphical element defined by the characters in
2523 .IR charseq ;
2524 see groff info file for details.
2525 .
2526 .ESC e
2527 Printable version of the current escape character.
2528 .
2529 .ESC E
2530 Equivalent to an escape character, but is not interpreted in copy-mode.
2531 .
2532 .ESC f F
2533 Change to font with 1-character name or 1-digit number
2534 .IR F .
2535 .
2536 .ESC fP
2537 Switch back to previous font.
2538 .
2539 .ESC f( fo
2540 Change to font with 2-character name or 2-digit number
2541 .IR fo .
2542 .
2543 .ESC[] f font
2544 Change to font with arbitrary length name or number expression
2545 .IR font .
2546 .
2547 .ESC[] f ""
2548 Switch back to previous font.
2549 .
2550 .ESC F f
2551 Change to font family with 1-character name
2552 .IR f .
2553 .
2554 .ESC F( fm
2555 Change to font family with 2-character name
2556 .IR fm .
2557 .
2558 .ESC[] F fam
2559 Change to font family with arbitrary length name
2560 .IR fam .
2561 .
2562 .ESC[] F ""
2563 Switch back to previous font family.
2564 .
2565 .ESC[] g reg
2566 Return format of register with name
2567 .I reg
2568 suitable for
2569 .request .af .
2570 .
2571 Alternative forms
2572 .escarg g( xy
2573 and
2574 .escarg g x .
2575 .
2576 .ESCq h N
2577 Local horizontal motion; move right
2578 .I N
2579 (left if negative).
2580 .
2581 .ESCq H N
2582 Set height of current font to
2583 .IR N .
2584 .
2585 .ESC[] k reg
2586 Mark horizontal input place in register with arbitrary length name
2587 .IR reg .
2588 Alternative forms
2589 .escarg k( xy
2590 and
2591 .escarg k x .
2592 .
2593 .ESCq l Nc
2594 Horizontal line drawing function (optionally using character
2595 .IR c ).
2596 .
2597 .ESCq L Nc
2598 Vertical line drawing function (optionally using character
2599 .IR c ).
2600 .
2601 .ESC[] m color
2602 Change to color
2603 .IR color .
2604 .
2605 Alternative forms
2606 .escarg m( co
2607 and
2608 .escarg m c .
2609 .
2610 .ESC[] m ""
2611 Switch back to previous color.
2612 .
2613 .ESC[] M color
2614 Change filling color for closed drawn objects to color
2615 .IR color .
2616 .
2617 Alternative forms
2618 .escarg M( co
2619 and
2620 .escarg M c .
2621 .
2622 .ESC[] M ""
2623 Switch to previous fill color.
2624 .
2625 .ESC n r
2626 The numerical value stored in the register variable with the
2627 1-character name
2628 .IR r .
2629 .
2630 .ESC n( re
2631 The numerical value stored in the register variable with the
2632 2-character name
2633 .IR re .
2634 .
2635 .ESC[] n reg
2636 The numerical value stored in the register variable with arbitrary
2637 length name
2638 .IR reg .
2639 .
2640 .ESCq N n
2641 Typeset the character with code
2642 .I n
2643 in the current font, no special fonts are searched.
2644 .
2645 Useful for adding characters to a font using the
2646 .request char
2647 request.
2648 .
2649 .ESCq o abc.\|.\|.\&
2650 Overstrike characters
2651 .IR a ,
2652 .IR b ,
2653 .IR c ,
2654 etc.
2655 .
2656 .ESC O 0
2657 Disable glyph output.
2658 .
2659 Mainly for internal use.
2660 .
2661 .ESC O 1
2662 Enable glyph output.
2663 .
2664 Mainly for internal use.
2665 .
2666 .ESC p
2667 Break and spread output line.
2668 .
2669 .ESC r
2670 Reverse 1\ em vertical motion (reverse line in nroff).
2671 .
2672 .ESCq R "name\~\[+-]n"
2673 The same as
2674 .request .nr
2675 .I name
2676 .IR \[+-]n .
2677 .
2678 .ESC[] s \[+-]N
2679 Set the point size to
2680 .I N
2681 scaled points.
2682 .
2683 Note the alternative forms
2684 .BI \[rs]s \[+-] [ N ]\c
2685 ,
2686 .BI \[rs]s' \[+-]N '\c
2687 .Text ,
2688 .BI \[rs]s \[+-] ' N '\c
2689 .Text ,
2690 .escarg s( \[+-]xy\c
2691 .Text ,
2692 .BI \[rs]s \[+-] ( xy\c
2693 .Text ,
2694 .escarg s \[+-]x .
2695 Same as
2696 .request ps
2697 request.
2698 .
2699 .ESCq S N
2700 Slant output
2701 .I N
2702 degrees.
2703 .
2704 .ESC t
2705 Non-interpreted horizontal tab.
2706 .
2707 .ESC u
2708 Reverse (up) 1/2 em vertical motion (1/2 line in nroff).
2709 .
2710 .ESCq v N
2711 Local vertical motion; move down
2712 .I N
2713 (up if negative).
2714 .
2715 .ESC[] V env
2716 The contents of the environment variable
2717 .IR env .
2718 .
2719 Alternative forms
2720 .escarg V( xy
2721 and
2722 .escarg V x .
2723 .
2724 .ESCq w string
2725 The width of the character sequence
2726 .IR string .
2727 .
2728 .ESCq x N
2729 Extra line-space function (negative before, positive after).
2730 .
2731 .ESCq X string
2732 Output
2733 .I string
2734 as device control function.
2735 .
2736 .ESC[] Y name
2737 Output string variable or macro
2738 .I name
2739 uninterpreted as device control function.
2740 .
2741 Alternative forms
2742 .escarg Y( xy
2743 and
2744 .escarg Y x .
2745 .
2746 .ESC z c
2747 Print
2748 .I c
2749 with zero width (without spacing).
2750 .
2751 .ESCq Z anything
2752 Print
2753 .I anything
2754 and then restore the horizontal and vertical position;
2755 .I anything
2756 may not contain tabs or leaders.
2757 .
2758 .PD
2759 .P
2760 The escape sequences
2761 .esc e ,
2762 .esc . ,
2763 .esc \[dq] ,
2764 .esc $ ,
2765 .esc * ,
2766 .esc a ,
2767 .esc n ,
2768 .esc t ,
2769 .esc g ,
2770 and
2771 .escarg \& newline
2772 are interpreted in copy mode.
2773 .
2774 .P
2775 Escape sequences starting with
2776 .esc (
2777 or
2778 .esc [
2779 do not represent single character escape sequences, but introduce escape
2780 names with two or more characters.
2781 .
2782 .P
2783 If a backslash is followed by a character that does not constitute a
2784 defined escape sequence the backslash is silently ignored and the
2785 character maps to itself.
2786 .
2787 .
2788 .\" --------------------------------------------------------------------
2789 .SS "Special Characters"
2790 .\" --------------------------------------------------------------------
2791 .
2792 Common special characters are predefined by escape sequences of the
2793 form
2794 .BI \[rs]( xy
2795 with characters
2796 .I x
2797 and
2798 .IR y .
2799 .
2800 Some of these exist in the usual font while most of them are only
2801 available in the special font.
2802 .
2803 Below you'll find a selection of the most important glyphs; a complete
2804 list can be found in
2805 .BR groff_char (@MAN7EXT@).
2806 .RS
2807 .P
2808 .PD 0
2809 .
2810 .ESC (bu
2811 Bullet sign
2812 .ESC (co
2813 Copyright
2814 .ESC (ct
2815 Cent
2816 .ESC (dd
2817 Double dagger
2818 .ESC (de
2819 Degree
2820 .ESC (dg
2821 Dagger
2822 .ESC (rs
2823 Printable double quote
2824 .ESC (em
2825 Em-dash
2826 .ESC (hy
2827 Hyphen
2828 .ESC (rg
2829 Registered sign
2830 .ESC (rs
2831 Printable backslash character
2832 .ESC (sc
2833 Section sign
2834 .ESC (ul
2835 Underline character
2836 .ESC (==
2837 Identical
2838 .ESC (>=
2839 Larger or equal
2840 .ESC (<=
2841 Less or equal
2842 .ESC (!=
2843 Not equal
2844 .ESC (->
2845 Right arrow
2846 .ESC (<-
2847 Left arrow
2848 .ESC (+-
2849 Plus-minus sign
2850 .PD
2851 .RE
2852 .
2853 .
2854 .\" --------------------------------------------------------------------
2855 .SS "Strings"
2856 .\" --------------------------------------------------------------------
2857 .
2858 Strings are defined by the
2859 .request ds
2860 request and can be retrieved by the
2861 .esc *
2862 escape sequence.
2863 .
2864 .P
2865 Strings share their name space with macros.
2866 .
2867 So strings and macros without arguments are roughly equivalent, though
2868 calling a string like a macro and vice-versa is not stably implemented
2869 so far.
2870 .
2871 The following strings are predefined in groff.
2872 .
2873 .STRING .T
2874 The name of the current output device as specified by the
2875 .option -T
2876 command line option.
2877 .
2878 .
2879 .\" --------------------------------------------------------------------
2880 .SH REGISTERS
2881 .\" --------------------------------------------------------------------
2882 .
2883 Registers are variables that store a value.
2884 In groff, most registers store numerical values (see section
2885 .B NUMERICAL EXPRESSIONS
2886 above), but some can also hold a string value.
2887 .
2888 .P
2889 Each register is given a name.
2890 Arbitrary registers can be defined and set with the request
2891 .request nr
2892 .IR register .
2893 .
2894 .P
2895 The value stored in a register can be retrieved by the escape sequences
2896 introduced by
2897 .esc n .
2898 .
2899 .P
2900 Most useful are predefined registers.
2901 .
2902 In the following the notation
2903 .I name
2904 is used to refer to a register called
2905 .register name
2906 to make clear that we speak about registers.
2907 .
2908 Please keep in mind that the
2909 .esc[] n ""
2910 decoration is not part of the register name.
2911 .
2912 .
2913 .\" --------------------------------------------------------------------
2914 .SS "Read-only Registers"
2915 .\" --------------------------------------------------------------------
2916 .
2917 The following registers have predefined values that should not be
2918 modified by the user (usually, registers starting with a dot a
2919 read-only).
2920 .
2921 Mostly, they provide information on the current settings or store
2922 results from request calls.
2923 .
2924 .P
2925 .PD 0
2926 .
2927 .REG .$
2928 Number of arguments in the current macro.
2929 .
2930 .REG .a
2931 Post-line extra line-space most recently utilized using
2932 .escq x N .
2933 .
2934 .REG .A
2935 Set to\~1 in
2936 .B troff
2937 if option
2938 .B \-A
2939 is used; always\~1 in
2940 .BR nroff .
2941 .
2942 .REG .c
2943 Current input line number.
2944 .
2945 .REG .C
2946 1\~if compatibility mode is in effect, 0\~otherwise.
2947 .
2948 .REG .cdp
2949 The depth of the last character added to the current environment.
2950 It is positive if the character extends below the baseline.
2951 .
2952 .REG .ce
2953 The number of lines remaining to be centered, as set by the
2954 .request ce
2955 request.
2956 .
2957 .REG .cht
2958 The height of the last character added to the current environment.
2959 It is positive if the character extends above the baseline.
2960 .
2961 .REG .csk
2962 The skew of the last character added to the current environment.
2963 The skew of a character is how far to the right of the center of a character
2964 the center of an accent over that character should be placed.
2965 .
2966 .REG .d
2967 Current vertical place in current diversion; equal to register
2968 .register nl .
2969 .
2970 .REG .ev
2971 The name or number of the current environment (string-valued).
2972 .
2973 .REG .f
2974 Current font number.
2975 .
2976 .REG .fam
2977 The current font family (string-valued).
2978 .
2979 .REG .fn
2980 The current (internal) real font name (string-valued).
2981 .
2982 .REG .fp
2983 The number of the next free font position.
2984 .
2985 .REG .g
2986 Always 1 in GNU troff.
2987 .
2988 Macros should use it to test if running under groff.
2989 .
2990 .REG .h
2991 Text base-line high-water mark on current page or diversion.
2992 .
2993 .REG .H
2994 Available horizontal resolution in basic units.
2995 .
2996 .REG .hla
2997 The current hyphenation language as set by the
2998 .B .hla
2999 request.
3000 .
3001 .REG .hlc
3002 The number of immediately preceding consecutive hyphenated lines.
3003 .
3004 .REG .hlm
3005 The maximum allowed number of consecutive hyphenated lines, as set by
3006 the
3007 .request hlm
3008 request.
3009 .
3010 .REG .hy
3011 The current hyphenation flags (as set by the
3012 .request hy
3013 request).
3014 .
3015 .REG .hym
3016 The current hyphenation margin (as set by the
3017 .request hym
3018 request).
3019 .
3020 .REG .hys
3021 The current hyphenation space (as set by the
3022 .request hys
3023 request).
3024 .
3025 .REG .i
3026 Current ident.
3027 .
3028 .REG .in
3029 The indent that applies to the current output line.
3030 .
3031 .REG .int
3032 Positive if last output line contains
3033 .esc c .
3034 .
3035 .REG .kern
3036 1\~if pairwise kerning is enabled, 0\~otherwise.
3037 .
3038 .REG .l
3039 Current line length.
3040 .
3041 .REG .lg
3042 The current ligature mode (as set by the
3043 .request lg
3044 request).
3045 .
3046 .REG .linetabs
3047 The current line-tabs mode (as set by the
3048 .request linetabs
3049 request).
3050 .
3051 .REG .ll
3052 The line length that applies to the current output line.
3053 .
3054 .REG .lt
3055 The title length (as set by the
3056 .request lt
3057 request).
3058 .
3059 .REG .n
3060 Length of text portion on previous output line.
3061 .
3062 .REG .ne
3063 The amount of space that was needed in the last
3064 .request ne
3065 request that caused a trap to be sprung.
3066 .
3067 Useful in conjunction with
3068 .register .trunc .
3069 .
3070 .REG .ns
3071 1\~if in no-space mode, 0\~otherwise.
3072 .
3073 .REG .o
3074 Current page offset.
3075 .
3076 .REG .p
3077 Current page length.
3078 .
3079 .REG .pn
3080 The number of the next page: either the value set by a
3081 .request pn
3082 request, or the number of the current page plus\ 1.
3083 .
3084 .REG .ps
3085 The current pointsize in scaled points.
3086 .
3087 .REG .psr
3088 The last-requested pointsize in scaled points.
3089 .
3090 .REG .pvs
3091 The current post-vertical line spacing.
3092 .
3093 .REG .rj
3094 The number of lines to be right-justified as set by the rj request.
3095 .
3096 .REG .s
3097 Current point size as a decimal fraction.
3098 .
3099 .REG .sr
3100 The last requested pointsize in points as a decimal fraction
3101 (string-valued).
3102 .
3103 .REG .t
3104 Distance to the next trap.
3105 .
3106 .REG .T
3107 Set to\~1
3108 if option
3109 .B \-T
3110 is used.
3111 .
3112 .REG .tabs
3113 A string representation of the current tab settings suitable for use
3114 as an argument to the
3115 .request ta
3116 request.
3117 .
3118 .REG .trunc
3119 The amount of vertical space truncated by the most recently sprung
3120 vertical position trap, or, if the trap was sprung by a
3121 .request ne
3122 request, minus the amount of vertical motion produced by
3123 .request .ne .
3124 .
3125 In other words, at the point a trap is sprung, it represents
3126 the difference of what the vertical position would have been but for
3127 the trap, and what the vertical position actually is.
3128 .
3129 Useful in conjunction with the
3130 .register .ne
3131 register.
3132 .
3133 .REG .ss
3134 The value of the parameters set by the first argument of the
3135 .request ss
3136 request.
3137 .
3138 .REG .sss
3139 The value of the parameters set by the second argument of the
3140 .request ss
3141 request.
3142 .
3143 .REG .u
3144 Equal to 1 bin fill mode and 0 in nofill mode.
3145 .
3146 .REG .v
3147 Current vertical line spacing.
3148 .
3149 .REG .V
3150 Available vertical resolution in basic units.
3151 .
3152 .REG .vpt
3153 1\~ if vertical position traps are enabled, 0\~otherwise.
3154 .
3155 .REG .w
3156 Width of previous character.
3157 .
3158 .REG .warn
3159 The sum of the number codes of the currently enabled warnings.
3160 .
3161 .REG .x
3162 The major version number.
3163 .
3164 .REG .y
3165 The minor version number.
3166 .
3167 .REG .Y
3168 The revision number of groff.
3169 .
3170 .REG .z
3171 Name of current diversion.
3172 .PD
3173 .
3174 .
3175 .\" --------------------------------------------------------------------
3176 .SS "Writable Registers"
3177 .\" --------------------------------------------------------------------
3178 .
3179 The following registers can be read and written by the user.
3180 They have predefined default values, but these can be modified for
3181 customizing a document.
3182 .
3183 .P
3184 .PD 0
3185 .REG %
3186 Current page number.
3187 .
3188 .REG c.
3189 Current input line number.
3190 .
3191 .REG ct
3192 Character type (set by width function
3193 .esc w ).
3194 .
3195 .REG dl
3196 Maximal width of last completed diversion.
3197 .
3198 .REG dn
3199 Height of last completed diversion.
3200 .
3201 .REG dw
3202 Current day of week (1-7).
3203 .
3204 .REG dy
3205 Current day of month (1-31).
3206 .
3207 .REG hp
3208 Current horizontal position at input line.
3209 .
3210 .REG llx
3211 Lower left x-coordinate (in PostScript units) of a given PostScript
3212 image (set by
3213 .request .psbb ).
3214 .
3215 .REG lly
3216 Lower left y-coordinate (in PostScript units) of a given PostScript
3217 image (set by
3218 .request .psbb ).
3219 .
3220 .REG ln
3221 Output line number.
3222 .
3223 .REG mo
3224 Current month (1-12).
3225 .
3226 .REG nl
3227 Vertical position of last printed text base-line.
3228 .
3229 .REG rsb
3230 Like
3231 .register sb ,
3232 but takes account of the heights and depths of characters.
3233 .
3234 .REG rst
3235 Like
3236 .register st ,
3237 but takes account of the heights and depths of characters.
3238 .
3239 .REG sb
3240 Depth of string below base line (generated by width function
3241 .esc w ).
3242 .
3243 .REG skw
3244 Right skip width from the center of the last character in the
3245 .esc w
3246 argument.
3247 .
3248 .REG slimit
3249 If greater than 0, the maximum number of objects on the input stack.
3250 .
3251 If \[<=]0 there is no limit, i.e., recursion can continue until virtual
3252 memory is exhausted.
3253 .
3254 .REG ssc
3255 The amount of horizontal space (possibly negative) that should be
3256 added to the last character before a subscript (generated by width
3257 function
3258 .esc w ).
3259 .
3260 .REG st
3261 Height of string above base line (generated by width function
3262 .esc w ).
3263 .
3264 .REG systat
3265 The return value of the
3266 .I system()
3267 function executed by the last
3268 .request sy
3269 request.
3270 .
3271 .REG urx
3272 Upper right x-coordinate (in PostScript units) of a given PostScript
3273 image (set by
3274 .request .psbb ).
3275 .
3276 .REG ury
3277 Upper right y-coordinate (in PostScript units) of a given PostScript
3278 image (set by
3279 .request .psbb ).
3280 .
3281 .REG year
3282 The current year (year 2000 compliant).
3283 .
3284 .REG yr
3285 Current year minus 1900.
3286 .
3287 For Y2K compliance use register
3288 .register year
3289 instead.
3290 .
3291 .PD
3292 .
3293 .
3294 .\" --------------------------------------------------------------------
3295 .SH COMPATIBILITY
3296 .\" --------------------------------------------------------------------
3297 .
3298 The differences of the groff language in comparison to classical troff
3299 as defined by
3300 .I [CSTR\~#54]
3301 are documented in
3302 .BR groff_diff (@MAN7EXT@).
3303 .
3304 .P
3305 The groff system provides a compatibility mode, see
3306 .BR groff (@MAN1EXT@)
3307 on how to invoke this.
3308 .
3309 .
3310 .\" --------------------------------------------------------------------
3311 .SH BUGS
3312 .\" --------------------------------------------------------------------
3313 .
3314 Report bugs to the
3315 .MTO bug-groff@gnu.org "groff bug mailing list" .
3316 Include a complete, self-contained example that will allow the bug to
3317 be reproduced, and say which version of groff you are using.
3318 .
3319 .
3320 .\" --------------------------------------------------------------------
3321 .SH AUTHORS
3322 .\" --------------------------------------------------------------------
3323 .
3324 Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc.
3325 .
3326 .P
3327 This document is distributed under the terms of the FDL (GNU Free
3328 Documentation License) version 1.1 or later.
3329 .
3330 You should have received a copy of the FDL on your system, it is also
3331 available on-line at the
3332 .URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" .
3333 .
3334 .P
3335 This document is part of
3336 .IR groff ,
3337 the GNU roff distribution.
3338 .
3339 It was written by
3340 .MTO bwarken@mayn.de "Bernd Warken" ;
3341 it is maintained by
3342 .MTO wl@gnu.org "Werner Lemberg" .
3343 .
3344 .
3345 .\" --------------------------------------------------------------------
3346 .SH "SEE ALSO"
3347 .\" --------------------------------------------------------------------
3348 .
3349 .P
3350 The main source of information for the groff language is the
3351 .B groff
3352 .BR info (1)
3353 file.
3354 .
3355 Besides the gory details, it contains many examples.
3356 .
3357 .TP
3358 .BR groff (@MAN1EXT@)
3359 the usage of the groff program and pointers to the documentation and
3360 availability of the groff system.
3361 .
3362 .TP
3363 .BR groff_diff (@MAN7EXT@)
3364 the differences of the groff language as compared to classical roff.
3365 .
3366 This is the authoritative document for the predefined language
3367 elements that are specific to groff.
3368 .
3369 .TP
3370 .BR groff_char (@MAN7EXT@)
3371 the predefined groff characters (glyphs).
3372 .
3373 .TP
3374 .BR groff_font (@MAN5EXT@)
3375 the specification of fonts and the DESC file.
3376 .
3377 .TP
3378 .BR roff (@MAN7EXT@)
3379 the history of roff, the common parts shared by all roff systems, and
3380 pointers to further documentation.
3381 .
3382 .TP
3383 .I [CSTR\~#54]
3384 .URL http://\:cm.bell-labs.com/\:cm/\:cs/\:54.ps \
3385 "Nroff/\:Troff User's Manual by Osanna & Kernighan"
3386 \[em] the bible for classical troff.
3387 .
3388 .
3389 .\" --------------------------------------------------------------------
3390 .\" Emacs Setup
3391 .\" --------------------------------------------------------------------
3392 .
3393 .\" Local Variables:
3394 .\" mode: nroff
3395 .\" End: