Debian Codegraph @

upstream/debian-trixie/man7/groff.7

raw
1 '\" t
2 .TH groff 7 "3 June 2025" "groff 1.23.0"
3 .SH Name
4 groff \- GNU
5 .I roff
6 language reference
7 .
8 .
9 .\" ====================================================================
10 .\" Legal Terms
11 .\" ====================================================================
12 .\"
13 .\" Copyright (C) 2000-2023 Free Software Foundation, Inc.
14 .\"
15 .\" This file is part of groff, the GNU roff type-setting system.
16 .\"
17 .\" Permission is granted to copy, distribute and/or modify this
18 .\" document under the terms of the GNU Free Documentation License,
19 .\" Version 1.3 or any later version published by the Free Software
20 .\" Foundation; with no Invariant Sections, with no Front-Cover Texts,
21 .\" and with no Back-Cover Texts.
22 .\"
23 .\" A copy of the Free Documentation License is included as a file
24 .\" called FDL in the main directory of the groff source package.
25 .\"
26 .\" A copy of the GNU Free Documentation License is also available in this
27 .\" Debian package as /usr/share/doc/groff/copyright.
28 .
29 .
30 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
31 .do nr *groff_groff_7_man_C \n[.cp]
32 .cp 0
33 .
34 .\" Define fallback for groff 1.23's MR macro if the system lacks it.
35 .nr do-fallback 0
36 .if !\n(.f .nr do-fallback 1 \" mandoc
37 .if \n(.g .if !d MR .nr do-fallback 1 \" older groff
38 .if !\n(.g .nr do-fallback 1 \" non-groff *roff
39 .if \n[do-fallback] \{\
40 . de MR
41 . ie \\n(.$=1 \
42 . I \%\\$1
43 . el \
44 . IR \%\\$1 (\\$2)\\$3
45 . .
46 .\}
47 .rr do-fallback
48 .
49 .
50 .\" ====================================================================
51 .\" Setup
52 .\" ====================================================================
53 .
54 .\" Man pages should not define page-local macros. Most of these were
55 .\" written long ago; someday we'll revise the page without them.
56 .
57 .\" ====================================================================
58 .\" start a macro, escape sequence, or register definition
59 .
60 .de TPx
61 . TP 10n
62 ..
63 .\" ====================================================================
64 .\" .Text anything ...
65 .\"
66 .\" All arguments are printed as text.
67 .\"
68 .de Text
69 . nop \)\\$*
70 ..
71 .
72 .\" ========= characters =========
73 .
74 .de squoted_char
75 . Text \[oq]\f[CB]\\$1\f[]\[cq]\\$2
76 ..
77 .de dquoted_char
78 . Text \[lq]\f[CB]\\$1\f[]\[rq]\\$2
79 ..
80 .\" ========= requests =========
81 .
82 .\" synopsis of a request
83 .de REQ
84 . ie \\n[.$]=1 \{\
85 . Text \f[CB]\\$1\f[]
86 . \}
87 . el \{\
88 . Text \f[CB]\\$1\~\f[]\f[I]\\$2\f[]
89 . \}
90 ..
91 .
92 .\" reference of a request
93 .de request
94 . ie (\\n[.$] < 2) \
95 . B \\$*
96 . el \
97 . BR \\$*
98 ..
99 .
100 .\" ========= numeric elements =========
101 .
102 .\" number with a trailing unit
103 .de scalednumber
104 . Text \\$1\^\f[CB]\\$2\f[]\\$3\f[R]
105 . ft P
106 ..
107 .
108 .\" representation of units within the text
109 .de scaleindicator
110 . Text \f[CB]\\$1\f[]\\$2\f[R]
111 . ft P
112 ..
113 .
114 .\" representation of mathematical operators within the text
115 .de operator
116 . squoted_char \\$@
117 ..
118 .
119 .
120 .\" ========= escape sequences =========
121 .
122 .\" ====================================================================
123 .\" .ESC name [arg]
124 .\"
125 .\" Synopsis of an escape sequence, optionally with argument
126 .\" Args : 1 or 2; 'name' obligatory, 'arg' optional
127 .\" name : suitable name for an escape sequence (c, (xy, [long])
128 .\" arg : arbitrary word
129 .\" Result : prints \namearg, where 'name' is in CB, 'arg' in I
130 .\"
131 .de ESC
132 . Text "\f[CB]\e\\$1\,\f[I]\\$2\/\fR"
133 ..
134 .\" ====================================================================
135 .\" .ESC[] name arg
136 .\"
137 .\" Synopsis for escape sequence with a bracketed long argument
138 .\" Args : 2 obligatory
139 .\" name : suitable name for an escape sequence (c, (xy, [long])
140 .\" arg : arbitrary text
141 .\" Result : prints \name[arg], where 'name' is in CB, 'arg' in I
142 .\"
143 .de ESC[]
144 . Text "\f[CB]\e\\$1\[lB]\f[]\,\f[I]\\$2\/\f[]\f[CB]\[rB]\f[]"
145 ..
146 .\" ====================================================================
147 .\" .ESCq name arg
148 .\"
149 .\" Synopsis for escape sequence with a bracketed long argument
150 .\" Args : 2 obligatory
151 .\" name : suitable name for an escape sequence (c, (xy, [long])
152 .\" arg : arbitrary text
153 .\" Result : prints \name'arg', where 'name' is in CB, 'arg' in I
154 .\"
155 .de ESCq
156 . Text "\f[CB]\e\\$1\[aq]\f[]\,\f[I]\\$2\/\f[]\f[CB]\[aq]\f[]"
157 ..
158 .\" ====================================================================
159 .\" .ESC? arg
160 .\"
161 .\" Synopsis for escape sequence with a bracketed long argument
162 .\" Args : 1 obligatory
163 .\" arg : arbitrary text
164 .\" Result : prints '\?arg\?', where the '\?' are in CB, 'arg' in I
165 .\"
166 .de ESC?
167 . Text "\f[CB]\e?\,\f[I]\\$1\/\f[CB]\[rs]?\f[R]"
168 ..
169 .\" ====================================================================
170 .\" .esc name [punct]
171 .\"
172 .\" Reference of an escape sequence (no args), possibly punctuation
173 .\" Args : 1 obligatory
174 .\" name : suitable name for an escape sequence (c, (xy, [long])
175 .\" punct : arbitrary
176 .\" Result : prints \name, where 'name' is in B, 'punct' in R
177 .\"
178 .de esc
179 . ie (\\n[.$] < 2) \
180 . B "\e\\$1"
181 . el \
182 . BR "\e\\$1" \\$2
183 ..
184 .\" ====================================================================
185 .\" .escarg name arg [punct]
186 .\"
187 .\" Reference of an escape sequence (no args)
188 .\" Args : 1 obligatory, 1 optional
189 .\" name : suitable name for an escape sequence (c, (xy, [long])
190 .\" arg : arbitrary word
191 .\" Result : prints \namearg, where
192 .\" 'name' is in B, 'arg' in I
193 .\"
194 .de escarg
195 . Text \f[B]\e\\$1\f[]\,\f[I]\\$2\/\f[]\\$3
196 ..
197 .\" ====================================================================
198 .\" .esc[] name arg [punct]
199 .\"
200 .\" Reference for escape sequence with a bracketed long argument
201 .\" Args : 2 obligatory
202 .\" name : suitable name for an escape sequence (c, (xy, [long])
203 .\" arg : arbitrary text
204 .\" Result : prints \name[arg], where 'name' is in CB, 'arg' in CI
205 .\"
206 .de esc[]
207 . Text \f[CB]\e\\$1\[lB]\f[]\,\f[CI]\\$2\/\f[]\f[CB]\[rB]\f[]\\$3
208 ..
209 .
210 .\" ========= strings =========
211 .
212 .\" synopsis for string, with \*[]
213 .de STRING
214 . Text \[rs]*[\f[CB]\\$1\f[]] \\$2
215 ..
216 .\" synopsis for a long string
217 .de string
218 . if \n[.$]=0 \
219 . return
220 . Text \f[CB]\[rs]*\[lB]\\$1\[rB]\f[]\\$2
221 ..
222 .
223 .\" ========= registers =========
224 .
225 .\" synopsis for registers, with \n[]
226 .de REG
227 . Text \[rs]n[\f[CB]\\$1\f[]]
228 ..
229 .\" reference of a register, without decoration
230 .de register
231 . Text register
232 . ie (\\n[.$] < 2) \
233 . B \\$*
234 . el \
235 . BR \\$*
236 ..
237 .
238 .\" begin list [piloting a possible extension to man(7)]
239 .de LS
240 . nr saved-PD \\n[PD]
241 . nr PD 0
242 ..
243 .
244 .\" end list [piloting a possible extension to man(7)]
245 .de LE
246 . nr PD \\n[saved-PD]
247 ..
248 .
249 .
250 .\" end of macro definitions
251 .
252 .
253 .\" ====================================================================
254 .SH Description
255 .\" ====================================================================
256 .
257 .I groff
258 is short for GNU
259 .IR roff ,
260 a free reimplementation of the AT&T device-independent
261 .I troff \" AT&T
262 typesetting system.
263 .
264 See
265 .MR roff 7
266 for a survey of and background on
267 .I roff
268 systems.
269 .
270 .
271 .P
272 This document is intended as a reference.
273 .
274 The primary
275 .I groff
276 manual,
277 .IR "Groff: The GNU Implementation of troff" ,
278 by Trent A.\& Fisher and Werner Lemberg,
279 is a better resource for learners,
280 containing many examples and much discussion.
281 .
282 It is written in Texinfo;
283 you can browse it interactively with \[lq]info groff\[rq].
284 .
285 Additional formats,
286 including plain text,
287 HTML,
288 DVI,
289 and PDF,
290 may be available in
291 .IR /usr/\:\%share/\:\%doc/\:\%groff\-base .
292 .
293 .
294 .P
295 .I groff
296 is also a name for an extended dialect of the
297 .I roff
298 language.
299 .
300 We use \[lq]roff\[rq] to denote features that are universal,
301 or nearly so,
302 among implementations of this family.
303 .
304 We apply the term \[lq]groff\[rq] to the language documented here,
305 the GNU implementation of the overall system,
306 the project that develops that system,
307 and the command of that name.
308 .
309 .
310 .P
311 GNU
312 .IR troff , \" GNU
313 installed on this system as
314 .MR \%troff 1 ,
315 is the
316 .I formatter:
317 a program that reads device and font descriptions
318 (\c
319 .MR groff_font 5 ),
320 interprets the
321 .I groff
322 language expressed in text input files,
323 and translates that input into a device-independent output format
324 (\c
325 .MR groff_out 5 )
326 that is usually then post-processed by an output driver to produce
327 PostScript,
328 PDF,
329 HTML,
330 DVI,
331 or terminal output.
332 .
333 .
334 .\" ====================================================================
335 .SH "Input format"
336 .\" ====================================================================
337 .
338 Input to GNU
339 .I troff \" GNU
340 is organized into lines separated by the Unix newline character
341 (U+000A),
342 and must be in one of two character encodings it can recognize:
343 IBM code page 1047 on EBCDIC systems,
344 and ISO\~Latin-1 (8859-1) otherwise.
345 .
346 Use of ISO\~646-1991:IRV (\[lq]US-ASCII\[rq]) or (equivalently) the
347 \[lq]Basic Latin\[rq]
348 subset of ISO\~10646 (\[lq]Unicode\[rq]) is recommended;
349 see
350 .MR groff_char 7 .
351 .
352 The
353 .MR preconv 1
354 preprocessor transforms other encodings,
355 including UTF-8,
356 to satisfy
357 .IR \%troff 's
358 requirements.
359 .
360 .
361 .\" ====================================================================
362 .SH "Syntax characters"
363 .\" ====================================================================
364 .
365 Several input characters are syntactically significant to
366 .IR groff .
367 .
368 .
369 .IP . 4n
370 A dot at the beginning of an input line marks it as a
371 .I control line.
372 .
373 It can also follow the
374 .request .el
375 and
376 .request .nop
377 requests,
378 and the condition in
379 .request .if ,
380 .request .ie ,
381 and
382 .request .while
383 requests.
384 .
385 The control character invokes requests and calls macros by the name that
386 follows it.
387 .
388 The
389 .request .cc
390 request can change the control character.
391 .
392 .
393 .IP \[aq]
394 The neutral apostrophe is the
395 .I "no-break control character,"
396 recognized where the control character is.
397 .
398 It suppresses the (first) break implied by the
399 .request .bp ,
400 .request .cf ,
401 .request .fi ,
402 .request .fl ,
403 .request .in ,
404 .request .nf ,
405 .request .rj ,
406 .request .sp ,
407 .request .ti ,
408 and
409 .request .trf
410 requests.
411 .
412 The requested operation takes effect at the next break.
413 .
414 It makes
415 .request .br
416 nilpotent.
417 .
418 The no-break control character can be changed with the
419 .request .c2
420 request.
421 .
422 When formatted,
423 .RB \[lq] \[aq] \[rq]
424 may be typeset as a typographical quotation mark;
425 use the
426 .esc [aq]
427 special character escape sequence to format a neutral apostrophe glyph.
428 .
429 .
430 .IP \[dq]
431 The neutral double quote can be used to enclose arguments to macros and
432 strings,
433 and is required if those arguments contain space or tab characters.
434 .
435 In the
436 .request .ds ,
437 .request .ds1 ,
438 .request .as ,
439 and
440 .request .as1
441 requests,
442 an initial neutral double quote in the second argument is stripped off
443 to allow embedding of leading spaces.
444 .
445 To include a double quote inside a quoted argument,
446 use the
447 .esc [dq]
448 special character escape sequence
449 (which also serves to typeset the glyph in text).
450 .
451 .
452 .IP \[rs]
453 A backslash introduces an escape sequence.
454 .
455 The escape character can be changed with the
456 .request .ec
457 request;
458 .request .eo
459 disables escape sequence recognition.
460 .
461 Use the
462 .esc [rs]
463 special character escape sequence to format a backslash glyph,
464 and
465 .esc e
466 to typeset the glyph of the current escape character.
467 .
468 .
469 .IP (
470 An opening parenthesis is special only in certain escape sequences;
471 when recognized,
472 it introduces an argument of exactly two characters.
473 .
474 .I groff
475 offers the more flexible square bracket syntax.
476 .
477 .
478 .IP [
479 An opening bracket is special only in certain escape sequences;
480 when recognized,
481 it introduces an argument (list) of any length,
482 not including a closing bracket.
483 .
484 .
485 .IP ]
486 A closing bracket is special only when an escape sequence using an
487 opening bracket as an argument delimiter is being interpreted.
488 .
489 It ends the argument (list).
490 .
491 .
492 .P
493 Additionally,
494 the Control+A character (U+0001) in text is interpreted as a
495 .I leader
496 (see below).
497 .
498 .
499 .P
500 Horizontal white space characters are significant to
501 .I groff,
502 but trailing spaces on text lines are ignored.
503 .\" slack text for widow/orphan control: trailing tabs are not
504 .
505 .
506 .TP 8n
507 .I space
508 Space characters separate arguments in request invocations,
509 macro calls,
510 and string interpolations.
511 .
512 In text,
513 they separate words.
514 .
515 Multiple adjacent space characters in text cause
516 .I groff
517 to attempt end-of-sentence detection on the preceding word
518 (and trailing punctuation).
519 .
520 The amount of space between words and sentences is controlled by the
521 .request .ss
522 request.
523 .
524 When filling is enabled
525 (the default),
526 a line may be broken at a space.
527 .
528 When adjustment is enabled
529 (the default),
530 inter-word spaces are expanded until the output line reaches the
531 configured length.
532 .
533 An adjustable but non-breaking space is available with
534 .esc \[ti] .
535 .
536 To get a space of fixed width,
537 use one of the escape sequences
538 .squoted_char "\[rs]\~"
539 (the escape character followed by a space),
540 .esc 0 ,
541 .esc | ,
542 .esc \[ha] ,
543 or
544 .esc h ;
545 see section \[lq]Escape sequences\[rq] below.
546 .
547 .
548 .TP
549 .I newline
550 In text,
551 a newline puts an inter-word space onto the output and,
552 if filling is enabled,
553 triggers end-of-sentence recognition on the preceding text.
554 .
555 See section \[lq]Line continuation\[rq] below.
556 .
557 .
558 .TP
559 .I tab
560 A tab character in text causes the drawing position to advance to the
561 next defined tab stop.
562 .
563 .
564 .\" ====================================================================
565 .SH "Tabs and leaders"
566 .\" ====================================================================
567 .
568 .\" BEGIN Keep (roughly) parallel with groff.texi node "Tabs and
569 .\" Leaders".
570 The formatter interprets input horizontal tab characters
571 (\[lq]tabs\[rq]) and Control+A characters (\[lq]leaders\[rq]) into
572 movements to the next tab stop.
573 .
574 Tabs simply move to the next tab stop;
575 leaders place enough periods to fill the space.
576 .
577 Tab stops are by default located every half inch measured from the
578 drawing position corresponding to the beginning of the input line;
579 see section \[lq]Page geometry\[rq] of
580 .MR roff 7 .
581 .
582 Tabs and leaders do not cause breaks and therefore do not interrupt
583 filling.
584 .
585 Tab stops can be configured with the
586 .B ta
587 request,
588 and tab and leader glyphs with the
589 .B tc
590 and
591 .B lc
592 requests,
593 respectively.
594 .\" END Keep (roughly) parallel with groff.texi node "Tabs and Leaders".
595 .
596 .
597 .\" ====================================================================
598 .SH "Line continuation"
599 .\" ====================================================================
600 .
601 When filling is enabled,
602 input and output line breaks generally do not correspond.
603 .
604 The
605 .I roff
606 language therefore distinguishes input and output line continuation.
607 .
608 .
609 .P
610 A backslash
611 .B \[rs]
612 immediately followed by a newline,
613 sometimes discussed as
614 .BI \[rs] newline\c
615 ,
616 suppresses the effects of that newline
617 on the input.
618 .
619 The next input line thus retains the classification of its predecessor
620 as a control or text line.
621 .
622 .BI \[rs] newline
623 is useful for managing line lengths in the input during document
624 maintenance;
625 you can break an input line in the middle of a request invocation,
626 macro call,
627 or escape sequence.
628 .
629 Input line continuation is invisible to the formatter,
630 with two exceptions:
631 the
632 .B \[or]
633 operator recognizes the new input line,
634 and the input line counter register
635 .B .c
636 is incremented.
637 .
638 .
639 .P
640 The
641 .esc c
642 escape sequence continues an
643 .I output
644 line.
645 .
646 Nothing on the input line after it is formatted.
647 .
648 In contrast to
649 .BI \[rs] newline\c
650 ,
651 a line after
652 .esc c
653 is treated as a new input line,
654 so a control character is recognized at its beginning.
655 .
656 The visual results depend on whether filling is enabled.
657 .
658 An intervening control line that causes a break overrides
659 .esc c ,
660 flushing out the pending output line in the usual way.
661 .
662 The
663 .register .int
664 contains a positive value if the last output line was continued with
665 .esc c ;
666 this datum is associated with the
667 environment.
668 .
669 .
670 .\" ====================================================================
671 .SH Colors
672 .\" ====================================================================
673 .
674 .\" BEGIN Keep (roughly) parallel with groff.texi node "Colors".
675 .I groff
676 supports color output with a variety of color spaces and up to 16 bits
677 per channel.
678 .
679 Some devices,
680 particularly terminals,
681 may be more limited.
682 .
683 When color support is enabled,
684 two colors are current at any given time:
685 the
686 .I stroke color,
687 with which glyphs,
688 rules (lines),
689 and geometric objects like circles and polygons are drawn,
690 and the
691 .I fill color,
692 which can be used to paint the interior of a closed geometric figure.
693 .
694 The
695 .BR color ,
696 .BR defcolor ,
697 .BR gcolor ,
698 and
699 .B fcolor
700 requests;
701 .B \[rs]m
702 and
703 .B \[rs]M
704 escape sequences;
705 and
706 .BR .color ,
707 .BR .m ,
708 and
709 .B .M
710 registers exercise color support.
711 .
712 .
713 .P
714 Each output device has a color named
715 .RB \[lq] default \[rq],
716 which cannot be redefined.
717 .
718 A device's default stroke and fill colors are not necessarily the same.
719 .
720 For the
721 .BR dvi ,
722 .BR html ,
723 .BR pdf ,
724 .BR ps ,
725 and
726 .B xhtml
727 output devices,
728 .I \%troff
729 automatically loads a macro file defining many color names at startup.
730 .
731 By the same mechanism,
732 the devices supported by
733 .MR grotty 1
734 recognize the eight standard ISO\~6429/ECMA-48 color names
735 (also known vulgarly as \[lq]ANSI colors\[rq]).
736 .\" END Keep (roughly) parallel with groff.texi node "Colors".
737 .
738 .
739 .br
740 .ne 3v
741 .\" ====================================================================
742 .SH Measurements
743 .\" ====================================================================
744 .
745 .\" BEGIN Keep (roughly) parallel with groff.texi node "Measurements".
746 Numeric parameters that specify measurements are expressed as
747 integers or decimal fractions with an optional
748 .I scaling unit
749 suffixed.
750 .
751 A scaling unit is a letter that immediately follows the last digit of a
752 number.
753 .
754 Digits after the decimal point are optional.
755 .
756 .
757 .P
758 Measurements are scaled by the scaling unit and stored internally
759 (with any fractional part discarded)
760 in basic units.
761 .
762 The device resolution can therefore be obtained by storing a value of
763 .RB \[lq] 1i \[rq]
764 to a register.
765 .
766 The only constraint on the basic unit is that it is at least as small as
767 any other unit.
768 .\" That's a fib. A device resolution of around 2^31 would surely also
769 .\" cause problems. But nobody does that.
770 .
771 .
772 .P
773 .LS
774 .TP
775 .B u
776 Basic unit.
777 .
778 .TP
779 .B i
780 Inch;
781 defined as 2.54\~centimeters.
782 .
783 .TP
784 .B c
785 Centimeter.
786 .
787 .TP
788 .B p
789 Point;
790 a typesetter's unit used for measuring type size.
791 .
792 There are 72\~points to an inch.
793 .
794 .TP
795 .B P
796 Pica;
797 another typesetter's unit.
798 .
799 There are 6\~picas to an inch and 12\~points to a pica.
800 .
801 .TP
802 .BR s ,\~ z
803 Scaled points and multiplication by the output device's
804 .I sizescale
805 parameter,
806 respectively.
807 .
808 .TP
809 .B f
810 Multiplication by 65,536;
811 .
812 scales decimal fractions in the interval [0, 1] to 16-bit unsigned
813 integers.
814 .LE
815 .
816 .
817 .P
818 The magnitudes of other scaling units depend on the text formatting
819 parameters in effect.
820 .
821 .
822 .P
823 .LS
824 .TP
825 .B m
826 Em;
827 an em is equal to the current type size in points.
828 .
829 .TP
830 .B n
831 En;
832 an en is one-half em.
833 .
834 .TP
835 .B v
836 Vee;
837 distance between text baselines.
838 .
839 .TP
840 .B M
841 Hundredth of an em.
842 .LE
843 .\" END Keep (roughly) parallel with groff.texi node "Measurements".
844 .
845 .
846 .\" ====================================================================
847 .SS "Motion quanta"
848 .\" ====================================================================
849 .
850 .\" BEGIN Keep (roughly) parallel with groff.texi node "Motion Quanta".
851 An output device's basic unit
852 .B u
853 is not necessarily its smallest addressable length;
854 .B u
855 can be smaller to avoid problems with integer roundoff.
856 .
857 The minimum distances that a device can work with in the horizontal and
858 vertical directions are termed its
859 .I "motion quanta,"
860 stored in the
861 .B .H
862 and
863 .B .V
864 registers,
865 respectively.
866 .
867 Measurements are rounded to applicable motion quanta.
868 .
869 Half-quantum fractions round toward zero.
870 .\" END Keep (roughly) parallel with groff.texi node "Motion Quanta".
871 .
872 .
873 .\" ====================================================================
874 .SS "Default units"
875 .\" ====================================================================
876 .
877 .\" BEGIN Keep (roughly) parallel with groff.texi node "Default Units".
878 A general-purpose register
879 (one created or updated with the
880 .B nr
881 request;
882 see section \[lq]Registers\[rq] below)
883 is implicitly dimensionless,
884 or reckoned in basic units if interpreted in a measurement context.
885 .
886 But it is convenient for many requests and escape sequences to infer a
887 scaling unit for an argument if none is specified.
888 .
889 An explicit scaling unit
890 (not after a closing parenthesis)
891 can override an undesirable default.
892 .
893 Effectively,
894 the default unit is suffixed to the expression if a scaling unit is not
895 already present.
896 .
897 GNU
898 .IR troff 's \" GNU
899 use of integer arithmetic should also be kept in mind;
900 see below.
901 .\" END Keep (roughly) parallel with groff.texi node "Default Units".
902 .
903 .
904 .\" ====================================================================
905 .SH "Numeric expressions"
906 .\" ====================================================================
907 .
908 .\" BEGIN Keep (roughly) parallel with groff.texi node "Numeric
909 .\" expressions".
910 A
911 .I numeric expression
912 evaluates to an integer.
913 .
914 The following operators are recognized.
915 .\"evaluates to an integer:
916 .\"it can be as simple as a literal
917 .\".RB \[lq] 0 \[rq]
918 .\"or it can be a complex sequence of register and string interpolations
919 .\"interleaved with measurement operators.
920 .
921 .
922 .P
923 .TS
924 Rf(CR) L.
925 + addition
926 \- subtraction
927 * multiplication
928 / truncating division
929 % modulus
930 _
931 \f[R]unary\f[] + assertion, motion, incrementation
932 \f[R]unary\f[] \- negation, motion, decrementation
933 _
934 ; scaling
935 >? maximum
936 <? minimum
937 _
938 < less than
939 > greater than
940 <= less than or equal
941 >= greater than or equal
942 \&= equal
943 == equal
944 _
945 & logical conjunction (\[lq]and\[rq])
946 : logical disjunction (\[lq]or\[rq])
947 ! logical complementation (\[lq]not\[rq])
948 _
949 ( ) precedence
950 _
951 | boundary-relative motion
952 .TE
953 .
954 .
955 .P
956 .I \%troff
957 provides a set of mathematical and logical operators familiar to
958 programmers\[em]as well as some unusual ones\[em]but supports only
959 integer arithmetic.
960 .
961 (Provision is made for interpreting and
962 reporting decimal fractions in certain cases.)
963 .
964 The internal data type used for computing results is usually a 32-bit
965 signed integer,
966 which suffices to represent magnitudes within a range of \[+-]2
967 billion.
968 .
969 (If that's not enough, see
970 .MR groff_tmac 5
971 for the
972 .I 62bit.tmac
973 macro package.)
974 .
975 .
976 .P
977 Arithmetic infix operators perform a function on the numeric expressions
978 to their left and right;
979 they are
980 .B +
981 (addition),
982 .B \-
983 (subtraction),
984 .B *
985 (multiplication),
986 .B /
987 (truncating division),
988 and
989 .B %
990 (modulus).
991 .
992 .I Truncating division
993 rounds to the integer nearer to zero,
994 no matter how large the fractional portion.
995 .
996 Overflow and division
997 (or modulus)
998 by zero are errors and abort evaluation of a numeric expression.
999 .
1000 .
1001 .P
1002 Arithmetic unary operators operate on the numeric expression to their
1003 right;
1004 they are
1005 .B \-
1006 (negation)
1007 and
1008 .B +
1009 (assertion\[em]for completeness;
1010 it does nothing).
1011 .
1012 The unary minus must often be used with parentheses to avoid confusion
1013 with the decrementation operator,
1014 discussed below.
1015 .
1016 .
1017 .P
1018 The sign of the modulus of operands of mixed signs is determined by the
1019 sign of the first.
1020 .
1021 Division and modulus operators satisfy the following property:
1022 given a
1023 .RI dividend\~ a
1024 and a
1025 .RI divisor\~ b ,
1026 a
1027 .RI quotient\~ q
1028 formed by
1029 .RB \[lq] "(a / b)" \[rq]
1030 and a
1031 .RI remainder\~ r
1032 by
1033 .RB \[lq] "(a % b)" \[rq],
1034 then
1035 .IR qb \~+\~ r \~=\~ a .
1036 .
1037 .
1038 .P
1039 GNU
1040 .IR troff 's \" GNU
1041 scaling operator,
1042 used with parentheses as
1043 .BI ( c ; e )\c
1044 ,
1045 evaluates a numeric
1046 .RI expression\~ e
1047 .RI using\~ c
1048 as the default scaling unit.
1049 .
1050 If
1051 .I c
1052 is omitted,
1053 scaling units are ignored in the evaluation
1054 .RI of\~ e .
1055 .
1056 GNU
1057 .I troff \" GNU
1058 also provides a pair of operators to compute the extrema of two
1059 operands:
1060 .B >?\&
1061 (maximum)
1062 and
1063 .B <?\&
1064 (minimum).
1065 .
1066 .
1067 .P
1068 Comparison operators comprise
1069 .B <
1070 (less than),
1071 .B >
1072 (greater than),
1073 .B <=
1074 (less than or equal),
1075 .B >=
1076 (greater than or equal),
1077 and
1078 .B =
1079 (equal).
1080 .
1081 .B ==
1082 is a synonym for
1083 .BR = .
1084 .
1085 When evaluated,
1086 a comparison is replaced with
1087 .RB \[lq] 0 \[rq]
1088 if it is false and
1089 .RB \[lq] 1 \[rq]
1090 if true.
1091 .
1092 In the
1093 .I roff
1094 language,
1095 positive values are true,
1096 others false.
1097 .
1098 .
1099 .P
1100 We can operate on truth values with the logical operators
1101 .B &
1102 (logical conjunction or \[lq]and\[rq])
1103 and
1104 .B :
1105 (logical disjunction or \[lq]or\[rq]).
1106 .
1107 They evaluate as comparison operators do.
1108 .
1109 A logical complementation (\[lq]not\[rq]) operator,
1110 .B !\&,
1111 works only within
1112 .RB \[lq] if \[rq],
1113 .RB \[lq] ie \[rq],
1114 and
1115 .RB \[lq] while \[rq]
1116 requests.
1117 .
1118 .\" This is worded to avoid implying that the operator doesn't apply to
1119 .\" conditional expressions in general, albeit without mentioning them
1120 .\" because they're out of scope.
1121 Furthermore,
1122 .B !\&
1123 is recognized only at the beginning of a numeric expression not
1124 contained by another numeric expression.
1125 .
1126 In other words,
1127 it must be the \[lq]outermost\[rq] operator.
1128 .
1129 Including it elsewhere in the expression produces a warning in the
1130 .RB \%\[lq] number \[rq]
1131 category
1132 (see
1133 .MR \%troff 1 ),
1134 and its expression evaluates false.
1135 .
1136 This unfortunate limitation maintains compatibility with AT&T
1137 .IR troff .\" AT&T
1138 .
1139 Test a numeric expression for falsity by comparing it to a false value.
1140 .
1141 .
1142 .P
1143 The
1144 .I roff
1145 language has no operator precedence:
1146 expressions are evaluated strictly from left to right,
1147 in contrast to schoolhouse arithmetic.
1148 .
1149 Use parentheses
1150 .B ( )
1151 to impose a desired precedence upon subexpressions.
1152 .
1153 .
1154 .P
1155 For many requests and escape sequences that cause motion on the page,
1156 the unary operators
1157 .B +
1158 and
1159 .B \-
1160 work differently when leading a numeric expression.
1161 .
1162 They then indicate a motion relative to the drawing position:
1163 positive is down in vertical contexts,
1164 right in horizontal ones.
1165 .
1166 .
1167 .P
1168 .B +
1169 and
1170 .B \-
1171 are also treated differently by the following requests and escape
1172 sequences:
1173 .BR bp ,
1174 .BR in ,
1175 .BR ll ,
1176 .BR pl ,
1177 .BR pn ,
1178 .BR po ,
1179 .BR ps ,
1180 .BR pvs ,
1181 .BR rt ,
1182 .BR ti ,
1183 .BR \[rs]H ,
1184 .BR \[rs]R ,
1185 and
1186 .BR \[rs]s .
1187 .
1188 Here,
1189 leading plus and minus signs serve as incrementation and decrementation
1190 operators,
1191 respectively.
1192 .
1193 To negate an expression,
1194 subtract it from zero
1195 or include the unary minus in parentheses with its argument.
1196 .\" @xref{Setting Registers}, for examples.
1197 .
1198 .
1199 .P
1200 A leading
1201 .B \[or]
1202 operator indicates a motion relative not to the drawing position but to
1203 a boundary.
1204 .
1205 For horizontal motions,
1206 the measurement specifies a distance relative to a drawing position
1207 corresponding to the beginning of the
1208 .I input
1209 line.
1210 .
1211 By default,
1212 tab stops reckon movements in this way.
1213 Most escape sequences do not;
1214 .\" XXX: Which ones do?
1215 .B \[or]
1216 tells them to do so.
1217 .
1218 For vertical motions,
1219 the
1220 .B \[or]
1221 operator specifies a distance from the first text baseline on the page
1222 or in the current diversion,
1223 using the current vertical spacing.
1224 .
1225 .
1226 .P
1227 The
1228 .B \[rs]B
1229 escape sequence tests its argument for validity as a numeric expression.
1230 .
1231 .
1232 .br
1233 .ne 2v
1234 .P
1235 A register interpolated as an operand in a numeric expression must have
1236 an Arabic format;
1237 luckily,
1238 this is the default.\" @xref{Assigning Register Formats}.
1239 .
1240 .
1241 .P
1242 Due to the way arguments are parsed,
1243 spaces are not allowed in numeric expressions unless the (sub)expression
1244 containing them is surrounded by parentheses.
1245 .\"@xref{Request and Macro Arguments}, and @ref{Conditionals and Loops}.
1246 .\" END Keep (roughly) parallel with groff.texi node "Numeric
1247 .\" expressions".
1248 .
1249 .
1250 .\" ====================================================================
1251 .SH Identifiers
1252 .\" ====================================================================
1253 .
1254 .\" BEGIN Keep (roughly) parallel with groff.texi node "Identifiers".
1255 An
1256 .I identifier
1257 labels a GNU
1258 .I troff \" GNU
1259 datum such as a register,
1260 name
1261 (macro,
1262 string,
1263 or diversion),
1264 typeface,
1265 color,
1266 special character,
1267 character class,
1268 environment,
1269 or stream.
1270 .
1271 Valid identifiers consist of one or more ordinary characters.
1272 .
1273 An
1274 .I ordinary character
1275 is an input character that is not the escape character,
1276 a leader,
1277 tab,
1278 newline,
1279 or invalid as GNU
1280 .I troff \" GNU
1281 input.
1282 .
1283 .
1284 .\" XXX: We might move this discussion earlier since it is applicable to
1285 .\" troff input in general, and include a reference to the `trin`
1286 .\" request.
1287 .P
1288 Invalid input characters are subset of control characters
1289 (from the sets \[lq]C0 Controls\[rq] and \[lq]C1 Controls\[rq] as
1290 Unicode describes them).
1291 .
1292 When
1293 .I \%troff
1294 encounters one in an identifier,
1295 it produces a warning in category
1296 .RB \%\[lq] input \[rq]
1297 (see section \[lq]Warnings\[rq] in
1298 .MR \%troff 1 ).
1299 .
1300 They are removed during interpretation:
1301 an identifier \[lq]foo\[rq],
1302 followed by an invalid
1303 character and then \[lq]bar\[rq],
1304 is processed as \[lq]foobar\[rq].
1305 .
1306 .
1307 .P
1308 On a machine using the ISO 646,
1309 8859,
1310 or 10646 character encodings,
1311 invalid input characters are
1312 .BR 0x00 ,
1313 .BR 0x08 ,
1314 .BR 0x0B ,
1315 .BR 0x0D \[en] 0x1F ,
1316 and
1317 .BR 0x80 \[en] 0x9F .
1318 .
1319 On an EBCDIC host,
1320 they are
1321 .BR 0x00 \[en] 0x01 ,
1322 .BR 0x08 ,
1323 .BR 0x09 ,
1324 .BR 0x0B ,
1325 .BR 0x0D \[en] 0x14 ,
1326 .BR 0x17 \[en] 0x1F ,
1327 and
1328 .BR 0x30 \[en] 0x3F .
1329 .
1330 Some of these code points are used by
1331 .I \%troff
1332 internally,
1333 making it non-trivial to extend the program to accept UTF-8 or other
1334 encodings that use characters from these ranges.
1335 .
1336 .
1337 .P
1338 An identifier with a closing bracket (\[lq]]\[rq]) in its name can't be
1339 accessed with bracket-form escape sequences that expect an identifier as
1340 a parameter.
1341 .
1342 Similarly,
1343 the
1344 identifier \[lq](\[rq] can't be interpolated
1345 .I except
1346 with bracket forms.
1347 .
1348 .
1349 .P
1350 If you begin a macro,
1351 string,
1352 or diversion name with either of the characters \[lq][\[rq] or
1353 \[lq]]\[rq],
1354 you foreclose use of the
1355 .MR \%refer 1
1356 preprocessor,
1357 which recognizes \[lq].[\[rq] and \[lq].]\[rq] as bibliographic
1358 reference delimiters.
1359 .
1360 .
1361 .P
1362 The escape sequence
1363 .B \[rs]A
1364 tests its argument for validity as an identifier.
1365 .
1366 .
1367 .P
1368 How GNU
1369 .I troff \" GNU
1370 handles the interpretation of an undefined identifier depends on the
1371 context.
1372 .
1373 There is no way to invoke an undefined request;
1374 such syntax is interpreted as a macro call instead.
1375 .
1376 If the identifier is interpreted as a string,
1377 macro,
1378 or diversion,
1379 .I \%troff
1380 emits a warning in category
1381 .RB \[lq] mac \[rq],
1382 defines it as empty,
1383 and interpolates nothing.
1384 .
1385 If the identifier is interpreted as a register,
1386 .I \%troff
1387 emits a warning in category
1388 .RB \[lq] reg \[rq],
1389 initializes it to zero,
1390 and interpolates that value.
1391 .
1392 See section \[lq]Warnings\[rq] in
1393 .MR \%troff 1 ,
1394 and subsection \[lq]Interpolating registers\[rq] and section
1395 \[lq]Strings\[rq] below.
1396 .
1397 Attempting to use an undefined
1398 typeface,
1399 style,
1400 special character,
1401 color,
1402 character class,
1403 environment,
1404 or stream generally provokes an error diagnostic.
1405 .
1406 .
1407 .P
1408 Identifiers for requests,
1409 macros,
1410 strings,
1411 and diversions share one name
1412 space;
1413 special characters and character classes another.
1414 .
1415 No other object types do.
1416 .\" END Keep (roughly) parallel with groff.texi node "Identifiers".
1417 .
1418 .
1419 .\" ====================================================================
1420 .SH "Control characters"
1421 .\" ====================================================================
1422 .
1423 .\" BEGIN Keep (roughly) parallel with groff.texi node "Control
1424 .\" Characters".
1425 .\" The mechanism of using @code{roff}'s control characters to invoke
1426 .\" requests and call macros was introduced in @ref{Requests and Macros}.
1427 Control characters are recognized only at the beginning of an input
1428 line,
1429 or at the beginning of the branch of a control structure request;
1430 .\" see @ref{Conditionals and Loops}.
1431 see section \[lq]Control structures\[rq] below.
1432 .
1433 .
1434 .P
1435 A few requests cause a break implicitly;
1436 use the no-break control character to prevent the break.
1437 .
1438 Break suppression is its sole behavioral distinction.
1439 .
1440 Employing the no-break control character to invoke requests that don't
1441 cause breaks is harmless but poor style.
1442 .
1443 .
1444 .P
1445 The control character
1446 .RB \[lq] .\& \[rq]
1447 and the no-break control character
1448 .RB \[lq] \|\[aq]\| \[rq]
1449 can be changed with the
1450 .B cc
1451 and
1452 .B c2
1453 requests,
1454 respectively.
1455 .
1456 Within a macro definition,
1457 .\" you might wish to know
1458 register
1459 .B .br
1460 indicates the control character used to call it.
1461 .\" END Keep (roughly) parallel with groff.texi node "Control
1462 .\" Characters".
1463 .
1464 .
1465 .\" ====================================================================
1466 .SH "Invoking requests"
1467 .\" ====================================================================
1468 .
1469 .\" BEGIN Keep (roughly) parallel with groff.texi node "Invoking
1470 .\" Requests".
1471 A control character is optionally followed by tabs and/or spaces and
1472 then an identifier naming a request or macro.
1473 .
1474 The invocation of an unrecognized request is interpreted as a macro
1475 call.
1476 .
1477 Defining a macro with the same name as a request replaces the request.
1478 .
1479 Deleting a request name with the
1480 .B rm
1481 request makes it unavailable.
1482 .
1483 The
1484 .B als
1485 request can alias requests,
1486 permitting them to be wrapped or non-destructively replaced.
1487 .
1488 See section \[lq]Strings\[rq] below.
1489 .
1490 .
1491 .br
1492 .ne 4v
1493 .P
1494 There is no inherent limit on argument length or quantity.
1495 .
1496 Most requests take one or more arguments,
1497 and ignore any they do not expect.
1498 .
1499 A request may be separated from its arguments by tabs or spaces,
1500 but only spaces can separate an argument from its successor.
1501 .
1502 Only one between arguments is necessary;
1503 any excess is ignored.
1504 .
1505 GNU
1506 .I troff \" GNU
1507 does not allow tabs for argument separation.
1508 .\" @footnote{In compatibility mode, a space is not necessary after a
1509 .\" request or macro name of two characters' length. Also, Plan@tie{}9
1510 .\" @code{troff} allows tabs to separate arguments.}
1511 .
1512 .
1513 .br
1514 .ne 3v
1515 .P
1516 Generally,
1517 a space
1518 .I within
1519 a request argument is not relevant,
1520 not meaningful,
1521 or is supported by bespoke provisions,
1522 as with the
1523 .B tl
1524 request's delimiters.
1525 .
1526 Some requests,
1527 like
1528 .BR ds ,
1529 interpret the remainder of the control line as a single argument.
1530 .
1531 See section \[lq]Strings\[rq] below.
1532 .
1533 .
1534 .P
1535 Spaces and tabs immediately after a control character are ignored.
1536 .
1537 Commonly,
1538 authors structure the source of documents or macro files with them.
1539 .\" END Keep (roughly) parallel with groff.texi node "Requests".
1540 .
1541 .
1542 .\" ====================================================================
1543 .SH "Calling macros"
1544 .\" ====================================================================
1545 .
1546 .\" BEGIN Keep (roughly) parallel with groff.texi node "Calling Macros".
1547 If a macro of the desired name does not exist when called,
1548 it is created,
1549 assigned an empty definition,
1550 and a warning in category
1551 .RB \[lq] mac \[rq]
1552 is emitted.
1553 .
1554 Calling an undefined macro
1555 .I does
1556 end a macro definition naming it as its end macro
1557 (see section \[lq]Writing macros\[rq] below).
1558 .
1559 .
1560 .P
1561 To embed spaces
1562 .I within
1563 a macro argument,
1564 enclose the argument in neutral double quotes
1565 .RB \[oq] \|\[dq]\| \[cq].
1566 .
1567 Horizontal motion escape sequences are sometimes a better choice for
1568 arguments to be formatted as text.
1569 .
1570 .
1571 .P
1572 The foregoing raises the question of how to embed neutral double quotes
1573 or backslashes in macro arguments when
1574 .I those
1575 characters are desired as literals.
1576 .
1577 In GNU
1578 .IR troff , \" GNU
1579 the special character escape sequence
1580 .B \[rs][rs]
1581 produces a backslash and
1582 .B \[rs][dq]
1583 a neutral double quote.
1584 .
1585 .
1586 .P
1587 In GNU
1588 .IR troff 's \" GNU
1589 AT&T compatibility mode,
1590 these characters remain available as
1591 .B \[rs](rs
1592 and
1593 .BR \[rs](dq ,
1594 respectively.
1595 .
1596 AT&T
1597 .I troff \" AT&T
1598 did not consistently define these special characters,
1599 .\" It seems that AT&T troff never recognized \(rs, though DWB 3.3
1600 .\" defined \(bs as an alias of "\" on its "Latin1" device, in
1601 .\" deliberate(?) collision with the Bell System logo identifier. It
1602 .\" also defined \(dq for several devices (pcl, Latin1, nroff, ...)
1603 .\" along with \(aq.
1604 but its descendants can be made to support them.
1605 .
1606 See
1607 .MR groff_font 5 .
1608 .
1609 If even that is not feasible,
1610 .\" Nope nope nope--if you're this much of a masochist, go read Texinfo.
1611 see the \[lq]Calling Macros\[rq] section of the
1612 .I groff
1613 Texinfo manual for the complex macro argument quoting rules of AT&T
1614 .IR troff . \" AT&T
1615 .\" END Keep (roughly) parallel with groff.texi node "Calling Macros".
1616 .
1617 .
1618 .\" ====================================================================
1619 .SH "Using escape sequences"
1620 .\" ====================================================================
1621 .
1622 .\" BEGIN Keep (roughly) parallel with groff.texi node "Using Escape
1623 .\" Sequences".
1624 Whereas requests must occur on control lines,
1625 escape sequences can occur intermixed with text and may appear in
1626 arguments to requests,
1627 macros,
1628 and other escape sequences.
1629 .
1630 An escape sequence is introduced by the escape character,
1631 a backslash
1632 .BR \[rs] .
1633 .\" (but see the @code{ec} request below)
1634 .
1635 The next character selects the escape's function.
1636 .
1637 .
1638 .P
1639 Escape sequences vary in length.
1640 .
1641 Some take an argument,
1642 and of those,
1643 some have different syntactical forms for a one-character,
1644 two-character,
1645 or arbitrary-length argument.
1646 .
1647 Others accept
1648 .I only
1649 an arbitrary-length argument.
1650 .
1651 In the former scheme,
1652 a one-character argument follows the function character immediately,
1653 an opening parenthesis
1654 .RB \[lq] ( \[rq]
1655 introduces a two-character argument
1656 (no closing parenthesis is used),
1657 and an argument of arbitrary length is enclosed in brackets
1658 .RB \[lq] [] \[rq].
1659 .
1660 In the latter scheme,
1661 the user selects a delimiter character.
1662 .
1663 A few escape sequences are idiosyncratic,
1664 and support both of the foregoing conventions
1665 .RB ( \|\[rs]s ),
1666 designate their own termination sequence
1667 .RB ( \|\[rs]? ),
1668 consume input until the next newline
1669 .RB ( \|\[rs]! ,
1670 .BR \|\[rs]" ,
1671 .BR \|\[rs]# ),
1672 or support an additional modifier character
1673 .RB ( \|\[rs]s
1674 again,
1675 and
1676 .BR \|\[rs]n ).
1677 .\" As with requests, use of some escape sequences in source documents
1678 .\" may interact poorly with a macro package you use; consult its
1679 .\" documentation to learn of ``safe'' sequences or alternative
1680 .\" facilities it provides to achieve the desired result.
1681 .
1682 .
1683 .P
1684 If an escape character is followed by a character that does not
1685 identify a defined operation,
1686 the escape character is ignored
1687 (producing
1688 a diagnostic of the
1689 .RB \[lq] escape \[rq]
1690 warning category,
1691 which is not enabled by default)
1692 and the following character is processed normally.
1693 .
1694 .
1695 .P
1696 Escape sequence interpolation is of higher precedence than escape
1697 sequence argument interpretation.
1698 .
1699 This rule affords flexibility in using escape sequences to construct
1700 parameters to other escape sequences.
1701 .
1702 .
1703 .P
1704 The escape character can be interpolated
1705 .RB ( \[rs]e ).
1706 .
1707 Requests permit the escape mechanism to be deactivated
1708 .RB ( eo )
1709 and restored,
1710 or the escape character changed
1711 .RB ( ec ),
1712 and to save and restore it
1713 .RB ( ecs
1714 and
1715 .BR ecr ).
1716 .\" END Keep (roughly) parallel with groff.texi node "Using Escape
1717 .\" Sequences".
1718 .
1719 .
1720 .\" ====================================================================
1721 .SH Delimiters
1722 .\" ====================================================================
1723 .
1724 .\" BEGIN Keep (roughly) parallel with groff.texi node "Delimiters".
1725 Some escape sequences that require parameters use delimiters.
1726 .
1727 The neutral apostrophe
1728 .B \[aq]
1729 is a popular choice and shown in this document.
1730 .
1731 The neutral double quote
1732 .B \[dq]
1733 is also commonly seen.
1734 .
1735 Letters,
1736 numerals,
1737 and leaders can be used.
1738 .
1739 Punctuation characters are likely better choices,
1740 except for those defined as infix operators in numeric expressions;
1741 see below.
1742 .
1743 .
1744 .br
1745 .ne 2v
1746 .P
1747 The following escape sequences don't take arguments and thus are allowed
1748 as delimiters:
1749 .BI \[rs] space\c
1750 ,
1751 .BR \[rs]% ,
1752 .BR \[rs]| ,
1753 .BR \[rs]\[ha] ,
1754 .BR \[rs]{ ,
1755 .BR \[rs]} ,
1756 .BR \[rs]\[aq] ,
1757 .BR \[rs]\[ga] ,
1758 .BR \[rs]\- ,
1759 .BR \[rs]_ ,
1760 .BR \[rs]! ,
1761 .BR \[rs]? ,
1762 .BR \[rs]) ,
1763 .BR \[rs]/ ,
1764 .BR \[rs], ,
1765 .BR \[rs]& ,
1766 .BR \[rs]: ,
1767 .BR \[rs]\[ti] ,
1768 .BR \[rs]0 ,
1769 .BR \[rs]a ,
1770 .BR \[rs]c ,
1771 .BR \[rs]d ,
1772 .BR \[rs]e ,
1773 .BR \[rs]E ,
1774 .BR \[rs]p ,
1775 .BR \[rs]r ,
1776 .BR \[rs]t ,
1777 and
1778 .BR \[rs]u .
1779 .
1780 However,
1781 using them this way is discouraged;
1782 they can make the input confusing to read.
1783 .
1784 .
1785 .P
1786 A few escape sequences,
1787 .BR \[rs]A ,
1788 .BR \[rs]b ,
1789 .BR \[rs]o ,
1790 .BR \[rs]w ,
1791 .BR \[rs]X ,
1792 and
1793 .BR \[rs]Z ,
1794 accept a newline as a delimiter.
1795 .
1796 Newlines that serve as delimiters continue to be recognized as input
1797 line terminators.
1798 .
1799 Use of newlines as delimiters in escape sequences is also discouraged.
1800 .
1801 .
1802 .br
1803 .ne 2v
1804 .P
1805 Finally,
1806 the escape sequences
1807 .BR \[rs]D ,
1808 .BR \[rs]h ,
1809 .BR \[rs]H ,
1810 .BR \[rs]l ,
1811 .BR \[rs]L ,
1812 .BR \[rs]N ,
1813 .BR \[rs]R ,
1814 .BR \[rs]s ,
1815 .BR \[rs]S ,
1816 .BR \[rs]v ,
1817 and
1818 .B \[rs]x
1819 prohibit many delimiters.
1820 .
1821 .
1822 .RS
1823 .IP \[bu] 2n
1824 the numerals 0\[en]9 and the decimal point
1825 .RB \[lq] . \[rq]
1826 .
1827 .
1828 .IP \[bu]
1829 the (single-character) operators
1830 .B +\-/*%<>=&:()
1831 .
1832 .
1833 .IP \[bu]
1834 any escape sequences other than
1835 .BR \[rs]% ,
1836 .BR \[rs]: ,
1837 .BR \[rs]{ ,
1838 .BR \[rs]} ,
1839 .BR \[rs]\[aq] ,
1840 .BR \[rs]\[ga] ,
1841 .BR \[rs]\- ,
1842 .BR \[rs]_ ,
1843 .BR \[rs]! ,
1844 .BR \[rs]/ ,
1845 .BR \[rs]c ,
1846 .BR \[rs]e ,
1847 and
1848 .B \[rs]p
1849 .RE
1850 .
1851 .
1852 .P
1853 Delimiter syntax is complex and flexible primarily for historical
1854 reasons;
1855 the foregoing restrictions need be kept in mind mainly when using
1856 .I groff
1857 in AT&T compatibility mode.
1858 .
1859 GNU
1860 .I troff \" GNU
1861 keeps track of the nesting depth of escape sequence interpolations,
1862 so the only characters you need to avoid using as delimiters are those
1863 that appear in the arguments you input,
1864 not any that result from interpolation.
1865 .
1866 Typically,
1867 .B \[aq]
1868 works fine.
1869 .
1870 See section \[lq]Implementation differences\[rq] in
1871 .MR groff_diff 7 .
1872 .\" END Keep (roughly) parallel with groff.texi node "Delimiters".
1873 .
1874 .
1875 .\" ====================================================================
1876 .SH "Dummy characters"
1877 .\" ====================================================================
1878 .
1879 .\" BEGIN Keep (roughly) parallel with groff.texi node "Dummy
1880 .\" Characters".
1881 As discussed in
1882 .MR roff 7 ,
1883 the first character on an input line is treated specially.
1884 .
1885 Further,
1886 formatting a glyph has many
1887 consequences on formatter state
1888 (see section \[lq]Environments\[rq] below).
1889 .
1890 Occasionally,
1891 we want to escape this context or embrace some of those consequences
1892 without actually rendering a glyph to the output.
1893 .
1894 .B \[rs]&
1895 interpolates a dummy character,
1896 which is constitutive of output but invisible.
1897 .
1898 Its presence alters the interpretation context of a subsequent input
1899 character,
1900 and enjoys several applications:
1901 preventing the insertion of extra space after an end-of-sentence
1902 character,
1903 preventing interpretation of a control character at the beginning of an
1904 input line,
1905 preventing kerning between two glyphs,
1906 and permitting the
1907 .B tr
1908 request to remap a character to \[lq]nothing\[rq].
1909 .
1910 .B \[rs])
1911 works as
1912 .B \[rs]&
1913 does,
1914 except that it does not cancel a pending end-of-sentence state.
1915 .\" END Keep (roughly) parallel with groff.texi node "Dummy Characters".
1916 .
1917 .
1918 .\" ====================================================================
1919 .SH "Control structures"
1920 .\" ====================================================================
1921 .
1922 .I groff
1923 has \[lq]if\[rq] and \[lq]while\[rq] control structures like other
1924 languages.
1925 .
1926 However,
1927 the syntax for grouping multiple input lines in the branches or bodies
1928 of these structures is unusual.
1929 .
1930 .
1931 .P
1932 They have a common form:
1933 the request name is
1934 (except for
1935 .request .el
1936 \[lq]else\[rq])
1937 followed by a conditional expression
1938 .IR cond-expr ;
1939 the remainder of the line,
1940 .IR anything ,
1941 is interpreted as if it were an input line.
1942 .
1943 Any quantity of spaces between arguments to requests serves only to
1944 separate them;
1945 leading spaces in
1946 .I anything
1947 are therefore not seen.
1948 .
1949 .I anything
1950 effectively
1951 .I cannot
1952 be omitted;
1953 if
1954 .I cond-expr
1955 is true and
1956 .I anything
1957 is empty,
1958 the newline at the end of the control line is interpreted as a blank
1959 line
1960 (and therefore a blank text line).
1961 .
1962 .
1963 .P
1964 It is frequently desirable for a control structure to govern more than
1965 one request,
1966 macro call,
1967 or text line,
1968 or a combination of the foregoing.
1969 .
1970 The opening and closing brace escape sequences
1971 .esc {
1972 and
1973 .esc }
1974 perform such grouping.
1975 .
1976 Brace escape sequences outside of control structures have no meaning and
1977 produce no output.
1978 .
1979 .
1980 .P
1981 .esc {
1982 should appear
1983 (after optional spaces and tabs)
1984 immediately subsequent to the request's conditional expression.
1985 .
1986 .esc }
1987 should appear on a line with other occurrences of itself as necessary to
1988 match
1989 .esc {
1990 sequences.
1991 .
1992 It can be preceded by a control character,
1993 spaces,
1994 and tabs.
1995 .
1996 Input after any quantity of
1997 .esc }
1998 sequences on the same line is processed only if all the preceding
1999 conditions to which they correspond are true.
2000 .
2001 Furthermore,
2002 a
2003 .esc }
2004 closing the body of a
2005 .request .while
2006 request must be the last such escape sequence on an input line.
2007 .
2008 .
2009 .\" ====================================================================
2010 .SS "Conditional expressions"
2011 .\" ====================================================================
2012 .
2013 .\" BEGIN Keep (roughly) parallel with groff.texi node "Operators in
2014 .\" Conditionals".
2015 The
2016 .request .if ,
2017 .request .ie ,
2018 and
2019 .request .while
2020 requests test the truth values of numeric expressions.
2021 .
2022 They also support several additional Boolean operators;
2023 the members of this expanded class are termed
2024 .IR "conditional expressions" ;
2025 their truth values are as shown below.
2026 .
2027 .
2028 .br
2029 .ne 3v
2030 .P
2031 .TS
2032 rf(BI) lB
2033 rB lx.
2034 cond-expr\f[R].\|.\|. .\|.\|.is true if.\|.\|.
2035 _
2036 T{
2037 .BI \[aq] s1 \[aq] s2 \[aq]
2038 T} T{
2039 .I s1
2040 produces the same formatted output as
2041 .IR s2 .
2042 T}
2043 T{
2044 .BI c\~ g
2045 T} T{
2046 a glyph
2047 .I g
2048 is available.
2049 T}
2050 T{
2051 .BI d\~ m
2052 T} T{
2053 a string,
2054 macro,
2055 diversion,
2056 or request
2057 .I m
2058 is defined.
2059 T}
2060 e T{
2061 the current page number is even.
2062 T}
2063 T{
2064 .BI F\~ f
2065 T} T{
2066 a font named
2067 .I f
2068 is available.
2069 T}
2070 T{
2071 .BI m\~ c
2072 T} T{
2073 a color named
2074 .I c
2075 is defined.
2076 T}
2077 n T{
2078 the formatter is in
2079 .I nroff
2080 mode.
2081 T}
2082 o T{
2083 the current page number is odd.
2084 T}
2085 T{
2086 .BI r\~ n
2087 T} T{
2088 a register named
2089 .I n
2090 is defined.
2091 T}
2092 T{
2093 .BI S\~ s
2094 T} T{
2095 a font style named
2096 .I s
2097 is available.
2098 T}
2099 t T{
2100 the formatter is in
2101 .I troff
2102 mode.
2103 T}
2104 v T{
2105 n/a
2106 (historical artifact;
2107 always false).
2108 T}
2109 .TE
2110 .
2111 .
2112 .br
2113 .ne 2v
2114 .P
2115 If the first argument to an
2116 .BR .if ,
2117 .BR .ie ,
2118 or
2119 .B .while
2120 request begins with a non-alphanumeric character apart from
2121 .B !\&
2122 (see below);
2123 it performs an
2124 .I output comparison test.
2125 .
2126 Shown first in the table above,
2127 the
2128 .I output comparison operator
2129 interpolates a true value if formatting its comparands
2130 .I s1
2131 and
2132 .I s2
2133 produces the same output commands.
2134 .
2135 Other delimiters can be used in place of the neutral apostrophes.
2136 .
2137 .I \%troff
2138 formats
2139 .I s1
2140 and
2141 .I s2
2142 in separate environments;
2143 after the comparison,
2144 the resulting data are discarded.
2145 .
2146 The resulting glyph properties,
2147 including font family,
2148 style,
2149 size,
2150 and
2151 slant,
2152 must match,
2153 but not necessarily the requests and/or escape sequences used to obtain
2154 them.
2155 .
2156 Motions must match in orientation and magnitude to within the applicable
2157 horizontal or vertical motion quantum of the device,
2158 after rounding.
2159 .
2160 .\" TODO: Uncomment and add forward reference when we add a "GNU troff
2161 .\" internals" subsection to this page.
2162 .\"(All of this is to say that the lists of output nodes created by
2163 .\"formatting
2164 .\".I s1
2165 .\"and
2166 .\".I s2
2167 .\"must be identical.)
2168 .
2169 .
2170 .P
2171 Surround the comparands with
2172 .B \[rs]?\&
2173 to avoid formatting them;
2174 this causes them to be compared character by character,
2175 as with string comparisons in other programming languages.
2176 .
2177 Since comparands protected with
2178 .B \[rs]?\&
2179 are read in copy mode,
2180 they need not even be valid
2181 .I groff
2182 syntax.
2183 .
2184 The escape character is still lexically recognized,
2185 however,
2186 and consumes the next character.
2187 .
2188 .
2189 .P
2190 The above operators can't be combined with most others,
2191 but a leading
2192 .RB \[lq] !\& \[rq],
2193 not followed immediately by spaces or tabs,
2194 complements an expression.
2195 .
2196 Spaces and tabs are optional immediately after the
2197 .RB \[lq] c \[rq],
2198 .RB \[lq] d \[rq],
2199 .RB \[lq] F \[rq],
2200 .RB \[lq] m \[rq],
2201 .RB \[lq] r \[rq],
2202 and
2203 .RB \[lq] S \[rq]
2204 operators,
2205 but right after
2206 .RB \[lq] !\& \[rq],
2207 they end the predicate and the conditional evaluates true.
2208 .
2209 (This bizarre behavior maintains compatibility with AT&T
2210 .IR troff .)
2211 .\" END Keep (roughly) parallel with groff.texi node "Operators in
2212 .\" Conditionals".
2213 .
2214 .
2215 .\" ====================================================================
2216 .SH "Syntax reference conventions"
2217 .\" ====================================================================
2218 .
2219 In the following request and escape sequence specifications,
2220 most argument names were chosen to be descriptive.
2221 .
2222 A few denotations may require introduction.
2223 .
2224 .
2225 .P
2226 .LS
2227 .RS
2228 .
2229 .TPx
2230 .I c
2231 denotes a single input character.
2232 .
2233 .TPx
2234 .I font
2235 a font either specified as a font name or a numeric mounting position.
2236 .
2237 .TPx
2238 .I anything
2239 all characters up to the end of the line,
2240 to the ending delimiter for the escape sequence,
2241 or within
2242 .esc {
2243 and
2244 .esc } .
2245 .
2246 Escape sequences may generally be used freely in
2247 .IR anything ,
2248 except when it is read in copy mode.
2249 .
2250 .TPx
2251 .I message
2252 is a character sequence to be emitted on the standard error stream.
2253 .
2254 Special character escape sequences are
2255 .I not
2256 interpreted.
2257 .
2258 .TPx
2259 .I n
2260 is a numeric expression that evaluates to a non-negative integer.
2261 .
2262 .TPx
2263 .I npl
2264 is a numeric expression constituting a count of subsequent
2265 .I productive
2266 input lines;
2267 that is,
2268 those that directly produce formatted output.
2269 .
2270 Text lines produce output,
2271 as do control lines containing requests like
2272 .request .tl
2273 or escape sequences like
2274 .esc D .
2275 .
2276 Macro calls are not themselves productive,
2277 but their interpolated contents can be.
2278 .
2279 .TPx
2280 .I \[+-]N
2281 is a numeric expression with a meaning dependent on its sign.
2282 .RE
2283 .LE
2284 .
2285 .
2286 .P
2287 If a numeric expression presented as
2288 .I \[+-]N
2289 starts with a
2290 .squoted_char +
2291 sign,
2292 an increment in the amount of
2293 .RI of\~ N
2294 is applied to the value applicable to the request or escape sequence.
2295 .
2296 If it starts with a
2297 .squoted_char \-
2298 sign,
2299 a decrement of magnitude
2300 .I N
2301 is applied instead.
2302 .
2303 Without a sign,
2304 .I N
2305 replaces any existing value.
2306 .
2307 A leading minus sign
2308 .RI in\~ N
2309 is always interpreted as a decrementation operator,
2310 not an algebraic sign.
2311 .
2312 To assign a register a negative value or the negated value of another
2313 register,
2314 enclose it with its operand in
2315 parentheses or subtract it from zero.
2316 .
2317 If a prior value does not exist
2318 (the register was undefined),
2319 an increment or decrement is applied as if to\~0.
2320 .
2321 .
2322 .\" ====================================================================
2323 .SH "Request short reference"
2324 .\" ====================================================================
2325 .
2326 Not all details of request behavior are outlined here.
2327 .
2328 See the
2329 .I groff
2330 Texinfo manual or,
2331 for features new to GNU
2332 .IR troff , \" GNU
2333 .MR groff_diff 7 .
2334 .
2335 .
2336 .P
2337 .LS
2338 .
2339 .TPx
2340 .REQ .ab
2341 Abort processing;
2342 exit with failure status.
2343 .
2344 .TPx
2345 .REQ .ab message
2346 Abort processing;
2347 write
2348 .I message
2349 to the standard error stream and exit with failure status.
2350 .
2351 .
2352 .TPx
2353 .REQ .ad
2354 Enable output line alignment and adjustment using the mode stored in
2355 .BR \[rs]n[.j] .
2356 .
2357 .
2358 .TPx
2359 .REQ .ad c
2360 Enable output line alignment and adjustment in mode
2361 .I c
2362 .RI ( c =\c
2363 .BR b , c , l , n , r ).
2364 .
2365 Sets
2366 .BR \[rs]n[.j] .
2367 .
2368 .
2369 .TPx
2370 .REQ .af "register c"
2371 Assign format
2372 .I c
2373 to
2374 .IR register ,
2375 where
2376 .I c
2377 is
2378 .RB \[lq] i \[rq],
2379 .RB \[lq] I \[rq],
2380 .RB \[lq] a \[rq],
2381 .RB \[lq] A \[rq],
2382 or a sequence of decimal digits whose quantity denotes the minimum width
2383 in digits to be used when the register is interpolated.
2384 .
2385 .RB \[lq] i \[rq]
2386 and
2387 .RB \[lq] a \[rq]
2388 indicate Roman numerals and basic Latin alphabetics,
2389 respectively,
2390 in the lettercase specified.
2391 .
2392 The default is
2393 .BR 0 .
2394 .
2395 .TPx
2396 .REQ .aln "new old"
2397 Create alias
2398 (additional name)
2399 .I new
2400 for existing register named
2401 .IR old .
2402 .
2403 .TPx
2404 .REQ .als "new old"
2405 Create alias
2406 (additional name)
2407 .I new
2408 for existing request,
2409 string,
2410 macro,
2411 or diversion
2412 .IR old .
2413 .
2414 .TPx
2415 .REQ .am "macro"
2416 Append to
2417 .I macro
2418 until
2419 .B ..\&
2420 is encountered.
2421 .
2422 .TPx
2423 .REQ .am "macro end"
2424 Append to
2425 .I macro
2426 until
2427 .BI . end
2428 is called.
2429 .
2430 .TPx
2431 .REQ .am1 "macro"
2432 Same as
2433 .request .am
2434 but with compatibility mode switched off during macro expansion.
2435 .
2436 .TPx
2437 .REQ .am1 "macro end"
2438 Same as
2439 .request .am
2440 but with compatibility mode switched off during macro expansion.
2441 .
2442 .TPx
2443 .REQ .ami "macro"
2444 Append to a macro whose name is contained in the string
2445 .I macro
2446 until
2447 .B ..\&
2448 is encountered.
2449 .
2450 .TPx
2451 .REQ .ami "macro end"
2452 Append to a macro indirectly.
2453 .I macro
2454 and
2455 .I end
2456 are strings whose contents are interpolated for the macro name and the
2457 end macro,
2458 respectively.
2459 .
2460 .TPx
2461 .REQ .ami1 "macro"
2462 Same as
2463 .request .ami
2464 but with compatibility mode switched off during macro expansion.
2465 .
2466 .TPx
2467 .REQ .ami1 "macro end"
2468 Same as
2469 .request .ami
2470 but with compatibility mode switched off during macro expansion.
2471 .
2472 .TPx
2473 .REQ .as name
2474 Create string
2475 .I name
2476 with empty contents;
2477 no operation if
2478 .I name
2479 already exists.
2480 .
2481 .TPx
2482 .REQ .as "name contents"
2483 Append
2484 .I contents
2485 to string
2486 .IR name .
2487 .
2488 .TPx
2489 .REQ .as1 string
2490 .TQ
2491 .REQ .as1 "string contents"
2492 As
2493 .request .as ,
2494 but with compatibility mode disabled when
2495 .I contents
2496 interpolated.
2497 .
2498 .TPx
2499 .REQ .asciify "diversion"
2500 Unformat ASCII characters, spaces, and some escape sequences in
2501 .IR diversion .
2502 .
2503 .TPx
2504 .REQ .backtrace
2505 Write the state of the input stack to the standard error stream.
2506 .
2507 See the
2508 .B \-b
2509 option of
2510 .MR groff 1 .
2511 .
2512 .TPx
2513 .REQ .bd font
2514 Stop emboldening font
2515 .I font.
2516 .
2517 .TPx
2518 .REQ .bd "font n"
2519 Embolden
2520 .I font
2521 by overstriking its glyphs offset by
2522 .IR n \-1
2523 units.
2524 .
2525 See
2526 .register .b .
2527 .\" XXX: negative values accepted; check AT&T troff
2528 .
2529 .TPx
2530 .REQ .bd "special-font font"
2531 Stop emboldening
2532 .I special-font
2533 when
2534 .I font
2535 is selected.
2536 .
2537 .TPx
2538 .REQ .bd "special-font font n"
2539 Embolden
2540 .I special-font,
2541 overstriking its glyphs offset by
2542 .IR n \-1
2543 units when
2544 .I font
2545 is selected.
2546 .
2547 See
2548 .register .b .
2549 .
2550 .TPx
2551 .REQ .blm
2552 Unset blank line macro (trap).
2553 .
2554 Restore default handling of blank lines.
2555 .
2556 .
2557 .TPx
2558 .REQ .blm name
2559 Set blank line macro (trap) to
2560 .IR name .
2561 .
2562 .
2563 .TPx
2564 .REQ .box
2565 Stop directing output to current diversion;
2566 any pending output line is discarded.
2567 .
2568 .
2569 .TPx
2570 .REQ .box name
2571 Direct output to diversion
2572 .IR name ,
2573 omitting a partially collected line.
2574 .
2575 .
2576 .TPx
2577 .REQ .boxa
2578 Stop appending output to current diversion;
2579 any pending output line is discarded.
2580 .
2581 .
2582 .TPx
2583 .REQ .boxa name
2584 Append output to diversion
2585 .IR name ,
2586 omitting a partially collected line.
2587 .
2588 .
2589 .TPx
2590 .REQ .bp
2591 Break page and start a new one.
2592 .
2593 .TPx
2594 .REQ .bp "\[+-]N"
2595 Break page,
2596 starting a new one numbered
2597 .IR \[+-]N .
2598 .
2599 .TPx
2600 .REQ .br
2601 Break output line.
2602 .
2603 .TPx
2604 .REQ .brp
2605 Break output line;
2606 adjust if applicable.
2607 .
2608 .TPx
2609 .REQ .break
2610 Break out of a while loop.
2611 .
2612 .TPx
2613 .REQ .c2
2614 Reset no-break control character to
2615 .dquoted_char \[aq] .
2616 .
2617 .TPx
2618 .REQ .c2 "o"
2619 Recognize ordinary character
2620 .I o
2621 as no-break control character.
2622 .
2623 .TPx
2624 .REQ .cc
2625 Reset control character to
2626 .squoted_char . .
2627 .
2628 .TPx
2629 .REQ .cc "o"
2630 Recognize ordinary character
2631 .I o
2632 as the control character.
2633 .
2634 .TPx
2635 .REQ .ce
2636 Break,
2637 center the output of the next productive input line without filling,
2638 and break again.
2639 .
2640 .TPx
2641 .REQ .ce npl
2642 Break,
2643 center the output of the next
2644 .I npl
2645 productive input lines without filling,
2646 then break again.
2647 .
2648 If
2649 .I npl
2650 \[<=] 0,
2651 stop centering.
2652 .
2653 .TPx
2654 .REQ .cf file
2655 Copy contents of
2656 .I file
2657 without formatting to the (top-level) diversion.
2658 .
2659 .TPx
2660 .REQ .cflags "n c1 c2 \fR\&.\|.\|.\&\fP"
2661 Assign properties encoded
2662 .RI by\~ n
2663 to characters
2664 .IR c1 ,
2665 .IR c2 ,
2666 and so on.
2667 .
2668 .
2669 .TPx
2670 .REQ .ch name
2671 Unplant page location trap
2672 .IR name .
2673 .
2674 .
2675 .TPx
2676 .REQ .ch "name vpos"
2677 Change page location trap
2678 .I name
2679 planted by
2680 .request .wh
2681 by moving its location to
2682 .I vpos
2683 (default scaling unit\~\c
2684 .scaleindicator v ).
2685 .
2686 .
2687 .TPx
2688 .REQ .char "c contents"
2689 Define ordinary or special character
2690 .I c
2691 as
2692 .IR contents .
2693 .
2694 .TPx
2695 .REQ .chop object
2696 Remove the last character from the macro,
2697 string,
2698 or diversion
2699 named
2700 .IR object .
2701 .
2702 .TPx
2703 .REQ .class "name c1 c2 \fR\&.\|.\|.\&\fP"
2704 Define a (character) class
2705 .I name
2706 comprising the characters or range expressions
2707 .IR c1 ,
2708 .IR c2 ,
2709 and so on.
2710 .
2711 .TPx
2712 .REQ .close "stream"
2713 Close the
2714 .IR stream .
2715 .
2716 .
2717 .TPx
2718 .REQ .color
2719 Enable output of color-related device-independent output commands.
2720 .
2721 .
2722 .TPx
2723 .REQ .color n
2724 If
2725 .I n
2726 is zero,
2727 disable output of color-related device-independent output commands;
2728 otherwise,
2729 enable them.
2730 .\" XXX: Should probably interpret negative values as false.
2731 .
2732 .
2733 .TPx
2734 .REQ .composite "from to"
2735 Map glyph name
2736 .I from
2737 to glyph name
2738 .I to
2739 while constructing a composite glyph name.
2740 .
2741 .TPx
2742 .REQ .continue
2743 Finish the current iteration of a while loop.
2744 .
2745 .TPx
2746 .REQ .cp
2747 Enable compatibility mode.
2748 .
2749 .TPx
2750 .REQ .cp n
2751 If
2752 .I n
2753 is zero,
2754 disable compatibility mode,
2755 otherwise enable it.
2756 .
2757 .TPx
2758 .REQ .cs "font n m"
2759 Set constant character width mode for
2760 .I font
2761 to
2762 .IR n /36
2763 ems with em
2764 .IR m .
2765 .\" XXX: m parameter needs more explanation.
2766 .
2767 .
2768 .TPx
2769 .REQ .cu
2770 Continuously underline the output of the next productive input line.
2771 .
2772 .
2773 .TPx
2774 .REQ .cu npl
2775 Continuously underline the output of the next
2776 .I npl
2777 productive input lines.
2778 .
2779 If
2780 .IR npl =0,
2781 stop continuously underlining.
2782 .
2783 .
2784 .TPx
2785 .REQ .da
2786 Stop appending output to current diversion.
2787 .
2788 .
2789 .TPx
2790 .REQ .da name
2791 Append output to diversion
2792 .IR name .
2793 .
2794 .
2795 .TPx
2796 .REQ .de macro
2797 Define or redefine
2798 .I macro
2799 until
2800 .RB \[lq] ..\& \[rq]
2801 occurs at the start of a control line in the current conditional block.
2802 .
2803 .
2804 .TPx
2805 .REQ .de "macro end"
2806 Define or redefine
2807 .I macro
2808 until
2809 .I end
2810 is invoked or called at the start of a control line in the current
2811 conditional block.
2812 .
2813 .
2814 .TPx
2815 .REQ .de1 "macro"
2816 As
2817 .request .de ,
2818 but disable compatibility mode during macro expansion.
2819 .
2820 .TPx
2821 .REQ .de1 "macro end"
2822 As
2823 .RB \[lq] .de
2824 .IR "macro end" \[rq],
2825 but disable compatibility mode during macro expansion.
2826 .
2827 .
2828 .TPx
2829 .REQ .defcolor "ident scheme color-component \f[R].\|.\|."
2830 Define a color named
2831 .I ident.
2832 .
2833 .I scheme
2834 identifies a color space and determines the number of required
2835 .IR color-component s;
2836 it must be one of
2837 .RB \[lq] rgb \[rq]
2838 (three components),
2839 .RB \[lq] cmy \[rq]
2840 (three),
2841 .RB \[lq] cmyk \[rq]
2842 (four),
2843 or
2844 .RB \[lq] gray \[rq]
2845 (one).
2846 .
2847 .RB \[lq] grey \[rq]
2848 is accepted as a synonym of
2849 .RB \[lq] gray \[rq].
2850 .
2851 The color components can be encoded as a single hexadecimal value
2852 starting with
2853 .B #
2854 or
2855 .BR ## .
2856 .
2857 The former indicates that each component is in the range 0\[en]255
2858 (0\[en]FF),
2859 the latter the range 0\[en]65,535 (0\[en]FFFF).
2860 .
2861 Alternatively,
2862 each color component can be specified as a decimal fraction in the range
2863 0\[en]1,
2864 interpreted using a default scaling unit
2865 .RB of\~\[lq] f \[rq],
2866 which multiplies its value by 65,536
2867 (but clamps it at 65,535).
2868 .
2869 Each output device has a color named
2870 .RB \[lq] default \[rq],
2871 which cannot be redefined.
2872 .
2873 A device's default stroke and fill colors are not necessarily the same.
2874 .
2875 .
2876 .TPx
2877 .REQ .dei "macro"
2878 Define macro indirectly.
2879 .
2880 As
2881 .request .de ,
2882 but use interpolation of string
2883 .I macro
2884 as the name of the defined macro.
2885 .
2886 .
2887 .TPx
2888 .REQ .dei "macro end"
2889 Define macro indirectly.
2890 .
2891 As
2892 .request .de ,
2893 but use interpolations of strings
2894 .I macro
2895 and
2896 .I end
2897 as the names of the defined and end macros.
2898 .
2899 .
2900 .TPx
2901 .REQ .dei1 "macro"
2902 As
2903 .request .dei ,
2904 but disable compatibility mode during macro expansion.
2905 .
2906 .
2907 .TPx
2908 .REQ .dei1 "macro end"
2909 As
2910 .request ".dei\~\f[I]macro\~end\f[]" ,
2911 but disable compatibility mode during macro expansion.
2912 .
2913 .TPx
2914 .REQ .device "anything"
2915 Write
2916 .IR anything ,
2917 read in copy mode,
2918 to
2919 .I \%troff
2920 output as a device control command.
2921 .
2922 An initial neutral double quote is stripped to allow embedding of
2923 leading spaces.
2924 .
2925 .TPx
2926 .REQ .devicem "name"
2927 Write contents of macro or string
2928 .I name
2929 to
2930 .I \%troff
2931 output as a device control command.
2932 .
2933 .TPx
2934 .REQ .di
2935 Stop directing output to current diversion.
2936 .
2937 .
2938 .TPx
2939 .REQ .di name
2940 Direct output to diversion
2941 .IR name .
2942 .
2943 .TPx
2944 .REQ .do "name \fR\&.\|.\|.\&\fP"
2945 Interpret the string,
2946 request,
2947 diversion,
2948 or macro
2949 .I name
2950 (along with any arguments)
2951 with compatibility mode disabled.
2952 .
2953 Compatibility mode is restored
2954 (only if it was active)
2955 when the
2956 .I expansion
2957 of
2958 .I name
2959 is interpreted.
2960 .
2961 .TPx
2962 .REQ .ds name
2963 Create empty string
2964 .IR name .
2965 .
2966 .TPx
2967 .REQ .ds "name contents"
2968 Create a string
2969 .I name
2970 containing
2971 .IR contents .
2972 .
2973 .TPx
2974 .REQ .ds1 name
2975 .TQ
2976 .REQ .ds1 "name contents"
2977 As
2978 .request .ds ,
2979 but with compatibility mode disabled when
2980 .I contents
2981 interpolated.
2982 .
2983 .TPx
2984 .REQ .dt
2985 Clear diversion trap.
2986 .
2987 .
2988 .TPx
2989 .REQ .dt "vertical-position name"
2990 Set the diversion trap to macro
2991 .I name
2992 at
2993 .I vertical-position
2994 (default scaling unit\~\c
2995 .scaleindicator v ).
2996 .
2997 .
2998 .TPx
2999 .REQ .ec
3000 Recognize
3001 .B \[rs]
3002 as the escape character.
3003 .
3004 .
3005 .TPx
3006 .REQ .ec "o"
3007 Recognize ordinary character
3008 .I o
3009 as the escape character.
3010 .
3011 .
3012 .TPx
3013 .REQ .ecr
3014 Restore escape character saved with
3015 .request .ecs .
3016 .
3017 .
3018 .TPx
3019 .REQ .ecs
3020 Save the escape character.
3021 .
3022 .
3023 .TPx
3024 .REQ .el "anything"
3025 Interpret
3026 .I anything
3027 as if it were an input line if the conditional expression of the
3028 corresponding
3029 .request .ie
3030 request was false.
3031 .
3032 .
3033 .TPx
3034 .REQ .em name
3035 Call macro
3036 .I name
3037 after the end of input.
3038 .
3039 .
3040 .TPx
3041 .REQ .eo
3042 Disable the escape mechanism in interpretation mode.
3043 .
3044 .
3045 .TPx
3046 .REQ .ev
3047 Pop environment stack,
3048 returning to previous one.
3049 .
3050 .
3051 .TPx
3052 .REQ .ev "env"
3053 Push current environment onto stack and switch to
3054 .IR env .
3055 .
3056 .
3057 .TPx
3058 .REQ .evc "env"
3059 Copy environment
3060 .I env
3061 to the current one.
3062 .
3063 .
3064 .TPx
3065 .REQ .ex
3066 Exit with successful status.
3067 .
3068 .
3069 .TPx
3070 .REQ .fam
3071 Set default font family to previous value.
3072 .
3073 .TPx
3074 .REQ .fam "name"
3075 Set default font family to
3076 .IR name .
3077 .
3078 .TPx
3079 .REQ .fc
3080 Disable field mechanism.
3081 .
3082 .TPx
3083 .REQ .fc "a"
3084 Set field delimiter to\~\c
3085 .I a
3086 and pad glyph to space.
3087 .
3088 .TPx
3089 .REQ .fc "a b"
3090 Set field delimiter to\~\c
3091 .I a
3092 and pad glyph to\~\c
3093 .IR b .
3094 .
3095 .TPx
3096 .REQ .fchar "c contents"
3097 Define fallback character (or glyph)
3098 .I c
3099 as
3100 .IR contents .
3101 .
3102 .
3103 .TPx
3104 .REQ .fcolor
3105 Restore previous fill color.
3106 .
3107 .
3108 .TPx
3109 .REQ .fcolor "c"
3110 Set fill color to
3111 .IR c .
3112 .
3113 .
3114 .TPx
3115 .REQ .fi
3116 Enable filling of output lines;
3117 a pending output line is broken.
3118 .
3119 Sets
3120 .BR \[rs]n[.u] .
3121 .
3122 .
3123 .TPx
3124 .REQ .fl
3125 Flush output buffer.
3126 .
3127 .TPx
3128 .REQ .fp "pos id"
3129 Mount font with font description file name
3130 .I id
3131 at non-negative
3132 .RI position\~ n .
3133 .
3134 .TPx
3135 .REQ .fp "pos id font-description-file-name"
3136 Mount font with
3137 .I font-description-file-name
3138 as name
3139 .I id
3140 at non-negative
3141 .RI position\~ n .
3142 .
3143 .TPx
3144 .REQ .fschar "f c anything"
3145 Define fallback character (or glyph)
3146 .I c
3147 for font
3148 .I f
3149 as string
3150 .IR anything .
3151 .
3152 .TPx
3153 .REQ .fspecial "font"
3154 Reset list of special fonts for
3155 .I font
3156 to be empty.
3157 .
3158 .TPx
3159 .REQ .fspecial "font s1 s2 \fR\&.\|.\|.\&\fP"
3160 When the current font is
3161 .IR font ,
3162 then the fonts
3163 .IR s1 ,
3164 .IR s2 ,
3165 \&.\|.\|.\&
3166 are special.
3167 .
3168 .TPx
3169 .REQ .ft
3170 .TQ
3171 .REQ ".ft P"
3172 Select previous font mounting position
3173 (abstract style or font);
3174 same as
3175 .esc f[]
3176 or
3177 .esc fP .
3178 .
3179 .TPx
3180 .REQ .ft "font"
3181 Select typeface
3182 .I font,
3183 which can be a
3184 mounting position,
3185 abstract style,
3186 or font name;
3187 same as
3188 .esc[] f font
3189 escape sequence.
3190 .
3191 .I font
3192 cannot be
3193 .BR P .
3194 .
3195 .TPx
3196 .REQ .ftr "font1 font2"
3197 Translate
3198 .I font1
3199 to
3200 .IR font2 .
3201 .
3202 .TPx
3203 .REQ .fzoom font
3204 .TQ
3205 .REQ .fzoom font\~\f[CB]0\f[]
3206 Stop magnifying
3207 .IR font .
3208 .
3209 .TPx
3210 .REQ .fzoom "font z"
3211 Set zoom factor for
3212 .I font
3213 .RI to\~ z
3214 (in thousandths;
3215 default:
3216 1000).
3217 .
3218 .TPx
3219 .REQ .gcolor
3220 Restore previous stroke color.
3221 .
3222 .
3223 .TPx
3224 .REQ .gcolor "c"
3225 Set stroke color to
3226 .IR c .
3227 .
3228 .
3229 .TPx
3230 .REQ .hc
3231 Reset the hyphenation character
3232 .RB to\~ \[rs]%
3233 (the default).
3234 .
3235 .TPx
3236 .REQ .hc char
3237 Change the hyphenation character
3238 .RI to\~ char .
3239 .
3240 .TPx
3241 .REQ .hcode "c1 code1 \fR[\fPc2 code2\fR] .\|.\|.\fP"
3242 Set the hyphenation code of character
3243 .I c1
3244 to
3245 .IR code1 ,
3246 that of
3247 .I c2
3248 to
3249 .IR code2 ,
3250 and so on.
3251 .
3252 .TPx
3253 .REQ .hla lang
3254 Set the hyphenation language to
3255 .IR lang .
3256 .
3257 .TPx
3258 .REQ .hlm n
3259 Set the maximum quantity of consecutive hyphenated lines to
3260 .IR n .
3261 .
3262 .TPx
3263 .REQ .hpf pattern-file
3264 Read hyphenation patterns from
3265 .IR pattern-file .
3266 .
3267 .TPx
3268 .REQ .hpfa pattern-file
3269 Append hyphenation patterns from
3270 .IR pattern-file .
3271 .
3272 .TPx
3273 .REQ .hpfcode "a b \fR[\fPc d\fR] .\|.\|.\fP"
3274 Define mappings for character codes in hyphenation pattern files read
3275 with
3276 .request .hpf
3277 and
3278 .request .hpfa .
3279 .
3280 .TPx
3281 .REQ .hw "word \fR.\|.\|.\fP"
3282 Define hyphenation overrides for each
3283 .I word;
3284 a hyphen
3285 .RB \[lq] \- \[rq]
3286 indicates a hyphenation point.
3287 .
3288 .
3289 .TPx
3290 .REQ .hy
3291 Set automatic hyphenation mode to
3292 .BR 1 .
3293 .
3294 .
3295 .TPx
3296 .REQ .hy\~0
3297 Disable automatic hyphenation;
3298 same as
3299 .BR .nh .
3300 .
3301 .
3302 .TPx
3303 .REQ .hy mode
3304 Set automatic hyphenation mode to
3305 .IR mode ;
3306 see section \[lq]Hyphenation\[rq] below.
3307 .
3308 .
3309 .TPx
3310 .REQ .hym
3311 Set the (right) hyphenation margin to
3312 .B 0
3313 (the default).
3314 .
3315 .TPx
3316 .REQ .hym length
3317 Set the (right) hyphenation margin to
3318 .I length
3319 (default scaling unit\~\c
3320 .scaleindicator m ).
3321 .
3322 .TPx
3323 .REQ .hys
3324 Set the hyphenation space to
3325 .B 0
3326 (the default).
3327 .
3328 .TPx
3329 .REQ .hys hyphenation-space
3330 Suppress automatic hyphenation in adjustment modes
3331 .RB \[lq] b \[rq]
3332 or
3333 .RB \[lq] n \[rq]
3334 if the line can be justified with the addition of up to
3335 .I hyphenation-space
3336 to each inter-word space
3337 (default scaling unit\~\c
3338 .scaleindicator m ).
3339 .
3340 .
3341 .TPx
3342 .REQ .ie "cond-expr anything"
3343 If
3344 .I cond-expr
3345 is true,
3346 interpret
3347 .I anything
3348 as if it were an input line,
3349 otherwise skip to a corresponding
3350 .request .el
3351 request.
3352 .
3353 .
3354 .TPx
3355 .REQ .if "cond-expr anything"
3356 If
3357 .I cond-expr
3358 is true,
3359 then interpret
3360 .I anything
3361 as if it were an input line.
3362 .
3363 .
3364 .TPx
3365 .REQ .ig
3366 Ignore input
3367 (except for side effects of
3368 .B \[rs]R
3369 on auto-incrementing registers)
3370 until
3371 .RB \[lq] ..\& \[rq]
3372 occurs at the start of a control line in the current conditional block.
3373 .
3374 .
3375 .TPx
3376 .REQ .ig "end"
3377 Ignore input
3378 (except for side effects of
3379 .B \[rs]R
3380 on auto-incrementing registers)
3381 until
3382 .BI . end
3383 is called at the start of a control line in the current conditional
3384 block.
3385 .
3386 .TPx
3387 .REQ .in
3388 Set indentation amount to previous value.
3389 .
3390 .TPx
3391 .REQ .in "\[+-]N"
3392 Set indentation to
3393 .I \[+-]N
3394 (default scaling unit\~\c
3395 .scaleindicator m ).
3396 .
3397 .TPx
3398 .REQ .it
3399 Cancel any pending input line trap.
3400 .
3401 .TPx
3402 .REQ .it "npl name"
3403 Set
3404 (or replace)
3405 an input line trap in the environment,
3406 calling macro
3407 .IR name ,
3408 after the next
3409 .I npl
3410 productive input lines have been read.
3411 .
3412 Lines interrupted with the
3413 .B \[rs]c
3414 escape sequence are counted separately.
3415 .
3416 .TPx
3417 .REQ .itc
3418 Cancel any pending input line trap.
3419 .
3420 .TPx
3421 .REQ .itc "npl name"
3422 As
3423 .request .it ,
3424 except that input lines interrupted with the
3425 .B \[rs]c
3426 escape sequence are not counted.
3427 .
3428 .TPx
3429 .REQ .kern
3430 Enable pairwise kerning.
3431 .
3432 .TPx
3433 .REQ .kern n
3434 If
3435 .I n
3436 is zero,
3437 disable pairwise kerning,
3438 otherwise enable it.
3439 .
3440 .TPx
3441 .REQ .lc
3442 Unset leader repetition character.
3443 .
3444 .TPx
3445 .REQ .lc "c"
3446 Set leader repetition character
3447 .RI to\~ c
3448 (default:
3449 .RB \[lq] . \[rq]).
3450 .
3451 .TPx
3452 .REQ .length "reg anything"
3453 Compute the number of characters of
3454 .I anything
3455 and store the count
3456 in the register
3457 .IR reg .
3458 .
3459 .
3460 .TPx
3461 .REQ .linetabs
3462 Enable line-tabs mode
3463 (calculate tab positions relative to beginning of output line).
3464 .
3465 .
3466 .TPx
3467 .REQ .linetabs\~0
3468 Disable line-tabs mode.
3469 .
3470 .
3471 .TPx
3472 .REQ .lf n
3473 Set number of next input line to
3474 .IR n .
3475 .\" XXX: negative values accepted; check AT&T troff
3476 .
3477 .TPx
3478 .REQ .lf "n file"
3479 Set number of next input line to
3480 .I n
3481 and input file name to
3482 .IR file .
3483 .
3484 .TPx
3485 .REQ .lg m
3486 Set ligature mode to
3487 .I m
3488 .RB ( 0
3489 = disable,
3490 .B 1
3491 = enable,
3492 .B 2
3493 = enable for two-letter ligatures only).
3494 .\" XXX: negative values accepted (mapped to 1); check AT&T troff
3495 .
3496 .TPx
3497 .REQ .ll
3498 Set line length to previous value.
3499 .
3500 Does not affect a pending output line.
3501 .
3502 .TPx
3503 .REQ .ll "\[+-]N"
3504 Set line length to
3505 .I \[+-]N
3506 (default length
3507 .scalednumber 6.5 i ,
3508 default scaling unit\~\c
3509 .scaleindicator m ).
3510 .
3511 Does not affect a pending output line.
3512 .
3513 .TPx
3514 .REQ .lsm
3515 Unset the leading space macro (trap).
3516 .
3517 Restore default handling of lines with leading spaces.
3518 .
3519 .TPx
3520 .REQ .lsm name
3521 Set the leading space macro (trap) to
3522 .IR name .
3523 .
3524 .TPx
3525 .REQ .ls
3526 Change to the previous value of additional intra-line skip.
3527 .
3528 .TPx
3529 .REQ .ls n
3530 Set additional intra-line skip value to
3531 .IR n ,
3532 i.e.,
3533 .IR n \-1
3534 blank lines are inserted after each text output line.
3535 .\" XXX: negative values accepted; check AT&T troff
3536 .
3537 .TPx
3538 .REQ .lt
3539 Set length of title lines to previous value.
3540 .
3541 .TPx
3542 .REQ .lt "\[+-]N"
3543 Set length of title lines
3544 (default length
3545 .scalednumber 6.5 i ,
3546 default scaling unit\~\c
3547 .scaleindicator m ).
3548 .
3549 .TPx
3550 .REQ .mc
3551 Cease writing margin character.
3552 .
3553 .TPx
3554 .REQ .mc c
3555 Begin writing margin
3556 .RI character\~ c
3557 to the right of each output line.
3558 .
3559 .TPx
3560 .REQ .mc "c d"
3561 Begin writing margin
3562 .RI character\~ c
3563 on each output line at
3564 .RI distance\~ d
3565 to the right of the right margin
3566 (default distance
3567 .scalednumber 10 p ,
3568 default scaling unit\~\c
3569 .scaleindicator m ).
3570 .
3571 .TPx
3572 .REQ .mk
3573 Mark vertical drawing position in an internal register;
3574 see
3575 .BR .rt .
3576 .
3577 .TPx
3578 .REQ .mk register
3579 Mark vertical drawing position in
3580 .IR register .
3581 .
3582 .TPx
3583 .REQ .mso "file"
3584 As
3585 .request .so ,
3586 except that
3587 .I file
3588 is sought in the
3589 .I tmac
3590 directories.
3591 .
3592 .
3593 .TPx
3594 .REQ .msoquiet "file"
3595 As
3596 .request .mso ,
3597 but no warning is emitted if
3598 .I file
3599 does not exist.
3600 .
3601 .
3602 .TPx
3603 .REQ .na
3604 Disable output line adjustment.
3605 .
3606 .
3607 .TPx
3608 .REQ .ne
3609 Break page if distance to next page location trap is less than one vee.
3610 .
3611 .TPx
3612 .REQ .ne d
3613 Break page if distance to next page location trap is less than distance
3614 .I d
3615 (default scaling unit\~\c
3616 .scaleindicator v ).
3617 .
3618 .
3619 .TPx
3620 .REQ .nf
3621 Disable filling of output lines;
3622 a pending output line is broken.
3623 .
3624 Clears
3625 .BR \[rs]n[.u] .
3626 .
3627 .
3628 .TPx
3629 .REQ .nh
3630 Disable automatic hyphenation;
3631 same as
3632 .RB \[lq] ".hy 0" \[rq].
3633 .
3634 .TPx
3635 .REQ .nm
3636 Deactivate output line numbering.
3637 .
3638 .TPx
3639 .REQ .nm \[+-]N
3640 .TQ
3641 .REQ .nm "\[+-]N m"
3642 .TQ
3643 .REQ .nm "\[+-]N m s"
3644 .TQ
3645 .REQ .nm "\[+-]N m s i"
3646 Activate output line numbering:
3647 number the next output line
3648 .I \[+-]N,
3649 writing numbers every
3650 .I m
3651 lines,
3652 with
3653 .I s
3654 numeral widths
3655 .RB ( \[rs]0 )
3656 between the line number and the output
3657 (default 1),
3658 and indenting the line number by
3659 .I i
3660 numeral widths
3661 (default 0).
3662 .
3663 .TPx
3664 .REQ .nn
3665 Suppress numbering of the next output line to be numbered with
3666 .BR nm .
3667 .
3668 .TPx
3669 .REQ .nn n
3670 Suppress numbering of the next
3671 .I n
3672 output lines to be numbered with
3673 .BR nm .
3674 .
3675 If
3676 .IR n =0,
3677 cancel suppression.
3678 .\" XXX: negative values accepted; check AT&T troff
3679 .
3680 .
3681 .TPx
3682 .REQ .nop "anything"
3683 Interpret
3684 .I anything
3685 as if it were an input line.
3686 .
3687 .TPx
3688 .REQ .nr "reg \[+-]N"
3689 Define or update register
3690 .I reg
3691 with value
3692 .IR N .
3693 .
3694 .TPx
3695 .REQ .nr "reg \[+-]N I"
3696 Define or update register
3697 .I reg
3698 with value
3699 .I N
3700 and auto-increment
3701 .IR I .
3702 .
3703 .TPx
3704 .REQ .nroff
3705 Make the conditional expressions
3706 .B n
3707 true and
3708 .B t
3709 false.
3710 .
3711 .TPx
3712 .REQ .ns
3713 Enable
3714 .IR "no-space mode" ,
3715 ignoring
3716 .B .sp
3717 requests until a glyph or
3718 .B \[rs]D
3719 primitive is output.
3720 .
3721 See
3722 .BR .rs .
3723 .
3724 .TPx
3725 .REQ .nx
3726 Immediately jump to end of current file.
3727 .
3728 .TPx
3729 .REQ .nx file
3730 Stop formatting current file and begin reading
3731 .I file.
3732 .
3733 .TPx
3734 .REQ .open "stream file"
3735 Open
3736 .I file
3737 for writing and associate the stream named
3738 .I stream
3739 with it.
3740 .
3741 Unsafe request;
3742 disabled by default.
3743 .
3744 .TPx
3745 .REQ .opena "stream file"
3746 As
3747 .request .open ,
3748 but append to
3749 .I file.
3750 .
3751 Unsafe request;
3752 disabled by default.
3753 .
3754 .TPx
3755 .REQ .os
3756 Output vertical distance that was saved by the
3757 .request .sv
3758 request.
3759 .
3760 .TPx
3761 .REQ .output contents
3762 Emit
3763 .I contents
3764 directly to intermediate output,
3765 allowing leading whitespace if
3766 .I string
3767 starts with
3768 \&\f[CB]\[dq]\f[]
3769 (which is stripped off).
3770 .
3771 .TPx
3772 .REQ .pc
3773 Reset page number character to\~\c
3774 .squoted_char % .
3775 .
3776 .TPx
3777 .REQ .pc "c"
3778 Page number character.
3779 .
3780 .
3781 .TPx
3782 .REQ .pev
3783 Report the state of the current environment followed by that of all
3784 other environments to the standard error stream.
3785 .
3786 .TPx
3787 .REQ .pi "program"
3788 Pipe output to
3789 .I program
3790 .RI ( nroff
3791 only).
3792 .
3793 Unsafe request;
3794 disabled by default.
3795 .
3796 .TPx
3797 .REQ .pl
3798 Set page length to default
3799 .scalednumber 11 i .
3800 The current page length is stored in register
3801 .BR .p .
3802 .
3803 .TPx
3804 .REQ .pl "\[+-]N"
3805 Change page length to
3806 .I \[+-]N
3807 (default scaling unit\~\c
3808 .scaleindicator v ).
3809 .
3810 .TPx
3811 .REQ .pm
3812 Report,
3813 to the standard error stream,
3814 the names and sizes in bytes of
3815 defined
3816 macros,
3817 strings,
3818 and
3819 diversions.
3820 .
3821 .TPx
3822 .REQ .pn "\[+-]N"
3823 Next page number
3824 .IR N .
3825 .
3826 .TPx
3827 .REQ .pnr
3828 Write the names and contents of all defined registers to the standard
3829 error stream.
3830 .
3831 .TPx
3832 .REQ .po
3833 Change to previous page offset.
3834 .
3835 The current page offset is available in register
3836 .BR .o .
3837 .
3838 .TPx
3839 .REQ .po "\[+-]N"
3840 Page offset
3841 .IR N .
3842 .
3843 .
3844 .TPx
3845 .REQ .ps
3846 Return to previous type size.
3847 .TPx
3848 .
3849 .
3850 .REQ .ps "\[+-]N"
3851 Set/increase/decrease the type size to/by
3852 .I N
3853 scaled points
3854 (a non-positive resulting type size is set to 1\~u);
3855 also see
3856 .esc[] s \[+-]N .
3857 .
3858 .TPx
3859 .REQ .psbb file
3860 Retrieve the bounding box of the PostScript image found in
3861 .I file,
3862 which must conform to Adobe's Document Structuring Conventions (DSC).
3863 .
3864 See registers
3865 .BR llx ,
3866 .BR lly ,
3867 .BR urx ,
3868 .BR ury .
3869 .
3870 .TPx
3871 .REQ .pso "command-line"
3872 Execute
3873 .I command-line
3874 with
3875 .MR popen 3
3876 and interpolate its output.
3877 .
3878 Unsafe request;
3879 disabled by default.
3880 .
3881 .TPx
3882 .REQ .ptr
3883 Report names and positions of all page location traps to the standard
3884 error stream.
3885 .
3886 .
3887 .TPx
3888 .REQ .pvs
3889 Change to previous post-vertical line spacing.
3890 .
3891 .TPx
3892 .REQ .pvs "\[+-]N"
3893 Change post-vertical line spacing according to
3894 .I \[+-]N
3895 (default scaling unit\~\c
3896 .scaleindicator p ).
3897 .
3898 .TPx
3899 .REQ .rchar "c1 c2 \fR.\|.\|.\&\fP"
3900 Remove definition of each ordinary or special character
3901 .IR c1 ,
3902 .IR c2 ,
3903 \&.\|.\|.\& defined by a
3904 .request .char ,
3905 .request .fchar ,
3906 or
3907 .request .schar
3908 request.
3909 .
3910 .TPx
3911 .REQ .rd "prompt"
3912 Read insertion.
3913 .
3914 .TPx
3915 .REQ .return
3916 Return from a macro.
3917 .
3918 .TPx
3919 .REQ .return "anything"
3920 Return twice, namely from the macro at the current level and from the
3921 macro one level higher.
3922 .
3923 .TPx
3924 .REQ .rfschar "f c1 c2 \fR\&.\|.\|.\&\fP"
3925 Remove the font-specific definitions of glyphs
3926 .IR c1 ,
3927 .IR c2 ,
3928 \&.\|.\|.\& for
3929 .RI font\~ f .
3930 .
3931 .TPx
3932 .REQ .rj npl
3933 Break,
3934 right-align the output of the next productive input line without
3935 filling,
3936 then break again.
3937 .
3938 .TPx
3939 .REQ .rj npl
3940 Break,
3941 right-align the output of the next
3942 .I npl
3943 productive input lines without filling,
3944 then break again.
3945 .
3946 If
3947 .I npl
3948 \[<=] 0,
3949 stop right-aligning.
3950 .
3951 .TPx
3952 .REQ .rm "name"
3953 Remove request, macro, diversion, or string
3954 .IR name .
3955 .
3956 .TPx
3957 .REQ .rn "old new"
3958 Rename request, macro, diversion, or string
3959 .I old
3960 to
3961 .IR new .
3962 .
3963 .TPx
3964 .REQ .rnn "reg1 reg2"
3965 Rename register
3966 .I reg1
3967 to
3968 .IR reg2 .
3969 .
3970 .
3971 .TPx
3972 .REQ .rr ident
3973 Remove register
3974 .IR ident .
3975 .
3976 .
3977 .TPx
3978 .REQ .rs
3979 Restore spacing;
3980 disable no-space mode.
3981 .
3982 See
3983 .BR .ns .
3984 .
3985 .TPx
3986 .REQ .rt
3987 Return
3988 .I (upward only)
3989 to vertical position marked by
3990 .B .mk
3991 on the current page.
3992 .
3993 .TPx
3994 .REQ .rt N
3995 Return
3996 .I (upward only)
3997 to vertical position
3998 .I N
3999 (default scaling
4000 unit\~\c
4001 .scaleindicator v ).
4002 .\" XXX: negative values accepted; check AT&T troff
4003 .
4004 .TPx
4005 .REQ .schar "c contents"
4006 Define global fallback character (or glyph)\~\c
4007 .I c
4008 as
4009 .IR contents .
4010 .
4011 .
4012 .TPx
4013 .REQ .shc
4014 Reset the soft hyphen character to
4015 .esc [hy] .
4016 .
4017 .
4018 .TPx
4019 .REQ .shc c
4020 Set the soft hyphen character
4021 .RI to\~ c .
4022 .
4023 .
4024 .TPx
4025 .REQ .shift n
4026 In a macro definition,
4027 left-shift arguments by
4028 .IR n \~\c
4029 positions.
4030 .
4031 .TPx
4032 .REQ .sizes "s1 s2 \f[R].\|.\|.\&\f[] sn \f[R][\f[CB]0\f[]]"
4033 Set available type sizes similarly to the
4034 .B sizes
4035 directive in a
4036 .I DESC
4037 file.
4038 .
4039 Each
4040 .IR s i
4041 is interpreted in units of scaled points (\c
4042 .scaleindicator z ).
4043 .
4044 .
4045 .TPx
4046 .REQ .so file
4047 Replace the request's control line with the contents of
4048 .IR file ,
4049 \[lq]sourcing\[rq] it.
4050 .
4051 .
4052 .TPx
4053 .REQ .soquiet file
4054 As
4055 .request .so ,
4056 but no warning is emitted if
4057 .I file
4058 does not exist.
4059 .
4060 .
4061 .TPx
4062 .REQ .sp
4063 Break and move the next text baseline down by one vee,
4064 or until springing a page location trap.
4065 .
4066 .
4067 .TPx
4068 .REQ .sp dist
4069 Break and move the next text baseline down by
4070 .IR dist ,
4071 or until springing a page location trap
4072 (default scaling unit\~\c
4073 .scaleindicator v ).
4074 .
4075 A negative
4076 .I dist
4077 will not reduce the position of the text baseline below zero.
4078 .
4079 Prefixing
4080 .I dist
4081 with the
4082 .B \[or]
4083 operator moves to a position relative to the page top for positive
4084 .IR N ,
4085 and the bottom if
4086 .I N
4087 is negative;
4088 in all cases,
4089 one line height (vee) is added
4090 .RI to\~ dist .
4091 .
4092 .I dist
4093 is ignored inside a diversion.
4094 .
4095 .
4096 .TPx
4097 .REQ .special
4098 Reset global list of special fonts to be empty.
4099 .
4100 .TPx
4101 .REQ .special "s1 s2 \fR\&.\|.\|.\&\fR"
4102 Fonts
4103 .IR s1 ,
4104 .IR s2 ,
4105 etc.\& are special and are searched for glyphs not in the
4106 current font.
4107 .
4108 .TPx
4109 .REQ .spreadwarn
4110 Toggle the spread warning on and off (the default) without changing its
4111 value.
4112 .
4113 .TPx
4114 .REQ .spreadwarn N
4115 Emit a
4116 .B break
4117 warning if the additional space inserted for each space between words in
4118 an adjusted output line is greater than or equal to
4119 .IR N .
4120 .
4121 A negative
4122 .I N
4123 is treated as 0.
4124 .
4125 The default scaling unit is\~\c
4126 .scaleindicator m .
4127 .
4128 At startup,
4129 .request .spreadwarn
4130 is inactive and
4131 .I N
4132 is
4133 .scalednumber "3 m" .
4134 .\" XXX: negative values accepted; retain for future space-squeezing
4135 .
4136 .TPx
4137 .REQ .ss n
4138 Set minimal inter-word spacing to
4139 .IR n \~12ths
4140 of current font's space width.
4141 .
4142 .TPx
4143 .REQ .ss "n m"
4144 As
4145 .RB \[lq] .ss\~\c
4146 .IR n \[rq],
4147 and set additional inter-sentence space to
4148 .IR m \~12ths
4149 of current font's space width.
4150 .
4151 .TPx
4152 .REQ .stringdown stringvar
4153 Replace each byte in the string named
4154 .I stringvar
4155 with its lowercase version.
4156 .
4157 .TPx
4158 .REQ .stringup stringvar
4159 Replace each byte in the string named
4160 .I stringvar
4161 with its uppercase version.
4162 .
4163 .TPx
4164 .REQ .sty "n style"
4165 Associate abstract
4166 .I style
4167 with font position
4168 .IR n .
4169 .
4170 .TPx
4171 .REQ .substring "str start \fR[\fPend\fR]\fP"
4172 Replace the string named
4173 .I str
4174 with its substring bounded by the indices
4175 .I start
4176 and
4177 .IR end ,
4178 inclusive.
4179 .
4180 Negative indices count backwards from the end of the string.
4181 .
4182 .TPx
4183 .REQ .sv
4184 As
4185 .request .ne ,
4186 but save
4187 .scalednumber "1 v"
4188 for output with
4189 .request .os
4190 request.
4191 .
4192 .TPx
4193 .REQ .sv d
4194 As
4195 .request .ne ,
4196 but save distance
4197 .I d
4198 for later output with
4199 .request .os
4200 request
4201 (default scaling unit\~\c
4202 .scaleindicator v ).
4203 .\" XXX: negative values accepted; check AT&T troff
4204 .
4205 .TPx
4206 .REQ .sy "command-line"
4207 Execute
4208 .I command-line
4209 with
4210 .MR system 3 .
4211 .
4212 Unsafe request;
4213 disabled by default.
4214 .
4215 .TPx
4216 .REQ .ta "n1 n2 \fR\&.\|.\|.\&\fP n\fRn\fP \f[CB]T\f[] r1 r2 \
4217 \fR\&.\|.\|.\&\fP r\fRn\fP"
4218 Set tabs at positions
4219 .IR n1 ,
4220 .IR n2 ,
4221 \&.\|.\|.\&,
4222 .IR n n,
4223 then set tabs at
4224 .IR n n+ m \[tmu] r n+ r1
4225 through
4226 .IR n n+ m \[tmu] r n+ r n,
4227 where
4228 .I m
4229 increments from 0,
4230 1,
4231 2,
4232 \&.\|.\|.\& to the output line length.
4233 .
4234 Each
4235 .IR n \~argument
4236 can be prefixed with
4237 .RB a\~\[lq] + \[rq]
4238 to place the tab stop
4239 .I ni
4240 at a distance relative to the previous,
4241 .IR n ( i \-1).
4242 .
4243 Each argument
4244 .IR ni \~or\~ ri
4245 can be suffixed with a letter to align text within the tab column
4246 bounded by tab stops
4247 .IR i \~and\~ i +1;
4248 .RB \[lq] L \[rq]
4249 for left-aligned
4250 (the default),
4251 .RB \[lq] C \[rq]
4252 for centered,
4253 and
4254 .RB \[lq] R \[rq]
4255 for right-aligned.
4256 .
4257 .br
4258 .ne 4v \" XXX: should need only 2v
4259 .TPx
4260 .REQ .tag
4261 .TQ
4262 .REQ .taga
4263 Reserved for internal use.
4264 .
4265 .TPx
4266 .REQ .tc
4267 Unset tab repetition character.
4268 .
4269 .TPx
4270 .REQ .tc "c"
4271 Set tab repetition character
4272 .RI to\~ c
4273 (default: none).
4274 .
4275 .TPx
4276 .REQ .ti "\[+-]N"
4277 Temporarily indent next output line
4278 (default scaling unit\~\c
4279 .scaleindicator m ).
4280 .
4281 .TPx
4282 .REQ .tkf "font s1 n1 s2 n2"
4283 Enable track kerning for
4284 .IR font .
4285 .
4286 .TPx
4287 .REQ .tl "\f[CB]\[aq]\f[]left\f[CB]\[aq]\f[]center\f[CB]\[aq]\f[]right\
4288 \f[CB]\[aq]\f[]"
4289 Format three-part title.
4290 .
4291 .TPx
4292 .REQ .tm message
4293 Write
4294 .I message,
4295 followed by a newline,
4296 to the standard error stream.
4297 .
4298 .TPx
4299 .REQ .tm1 message
4300 As
4301 .request .tm ,
4302 but an initial neutral double quote in
4303 .I message
4304 is removed,
4305 allowing it to contain leading spaces.
4306 .
4307 .TPx
4308 .REQ .tmc message
4309 As
4310 .request .tm1 ,
4311 without emitting a newline.
4312 .
4313 .TPx
4314 .REQ .tr "abcd\fR\&.\|.\|.\&\fP"
4315 Translate ordinary or special characters
4316 .I a
4317 to
4318 .IR b ,
4319 .I c
4320 to
4321 .IR d ,
4322 and so on prior to output.
4323 .
4324 .TPx
4325 .REQ .trf file
4326 Transparently output the contents of
4327 .I file.
4328 .
4329 Unlike
4330 .request .cf ,
4331 invalid input characters in
4332 .I file
4333 are rejected.
4334 .
4335 .TPx
4336 .REQ .trin "abcd\fR\&.\|.\|.\&\fP"
4337 As
4338 .request .tr ,
4339 except that
4340 .request .asciify
4341 ignores the translation when a diversion is interpolated.
4342 .
4343 .TPx
4344 .REQ .trnt "abcd\fR\&.\|.\|.\&\fP"
4345 As
4346 .request .tr ,
4347 except that translations are suppressed in the argument to
4348 .esc ! .
4349 .
4350 .TPx
4351 .REQ .troff
4352 Make the conditional expressions
4353 .B t
4354 true and
4355 .B n
4356 false.
4357 .
4358 .TPx
4359 .REQ .uf font
4360 Set underline font used by
4361 .request .ul
4362 to
4363 .I font.
4364 .
4365 .
4366 .TPx
4367 .REQ .ul
4368 Underline
4369 (italicize in
4370 .I troff
4371 mode)
4372 the output of the next productive input line.
4373 .
4374 .
4375 .TPx
4376 .REQ .ul npl
4377 Underline
4378 (italicize in
4379 .I troff
4380 mode)
4381 the output of the next
4382 .I npl
4383 productive input line.
4384 .
4385 If
4386 .IR npl =0,
4387 stop underlining.
4388 .
4389 .
4390 .TPx
4391 .REQ .unformat "diversion"
4392 Unformat space characters and tabs in
4393 .IR diversion ,
4394 preserving font information.
4395 .
4396 .
4397 .TPx
4398 .REQ .vpt
4399 Enable vertical position traps.
4400 .
4401 .
4402 .TPx
4403 .REQ .vpt\~0
4404 Disable vertical position traps.
4405 .
4406 .
4407 .TPx
4408 .REQ .vs
4409 Change to previous vertical spacing.
4410 .
4411 .TPx
4412 .REQ .vs "\[+-]N"
4413 Set vertical spacing to
4414 .I \[+-]N
4415 (default scaling unit\~\c
4416 .scaleindicator p ).
4417 .
4418 .
4419 .TPx
4420 .REQ .warn
4421 Enable all warning categories.
4422 .
4423 .
4424 .TPx
4425 .REQ .warn\~0
4426 Disable all warning categories.
4427 .
4428 .
4429 .TPx
4430 .REQ .warn n
4431 Enable warnings in categories whose codes sum
4432 .RI to\~ n ;
4433 .\" TODO: Move that table here, perhaps.
4434 see
4435 .MR \%troff 1 .
4436 .
4437 .
4438 .TPx
4439 .REQ .warnscale "su"
4440 Set scaling unit used in certain warnings \" `output_warning()`
4441 to
4442 .I su
4443 (one of
4444 .BR u ,
4445 .BR i ,
4446 .BR c ,
4447 .BR p ,
4448 or
4449 .BR P ;
4450 default:
4451 .BR i ).
4452 .
4453 .
4454 .TPx
4455 .REQ .wh vpos
4456 Remove visible page location trap at
4457 .I vpos
4458 (default scaling unit\~\c
4459 .scaleindicator v ).
4460 .
4461 .
4462 .TPx
4463 .REQ .wh "vpos name"
4464 Plant macro
4465 .I name
4466 as page location trap at
4467 .I vpos
4468 (default scaling unit\~\c
4469 .scaleindicator v ),
4470 removing any visible trap already there.
4471 .
4472 .
4473 .TPx
4474 .REQ .while "cond-expr anything"
4475 Repeatedly execute
4476 .I anything
4477 unless and until
4478 .I cond-expr
4479 evaluates false.
4480 .
4481 .
4482 .TPx
4483 .REQ .write "stream anything"
4484 Write
4485 .I anything
4486 to the stream named
4487 .IR stream .
4488 .
4489 .TPx
4490 .REQ .writec "stream anything"
4491 Similar to
4492 .request .write
4493 without emitting a final newline.
4494 .
4495 .TPx
4496 .REQ .writem "stream xx"
4497 Write contents of macro or string
4498 .I xx
4499 to the stream named
4500 .IR stream .
4501 .
4502 .LE
4503 .
4504 .
4505 .\" ====================================================================
4506 .SH "Escape sequence short reference"
4507 .\" ====================================================================
4508 .
4509 The escape sequences
4510 .esc \[dq] ,
4511 .esc # ,
4512 .esc $ ,
4513 .esc * ,
4514 .esc ? ,
4515 .esc a ,
4516 .esc e ,
4517 .esc n ,
4518 .esc t ,
4519 .esc g ,
4520 .esc V ,
4521 and
4522 .escarg \& newline
4523 are interpreted even in copy mode.
4524 .
4525 .
4526 .P
4527 .LS
4528 .
4529 .\" ========= comments =========
4530 .
4531 .TP
4532 .ESC \[dq]
4533 Comment.
4534 .
4535 Everything up to the end of the line is ignored.
4536 .
4537 .
4538 .TP
4539 .ESC #
4540 Comment.
4541 .
4542 Everything up to and including the next newline is ignored.
4543 .
4544 .
4545 .\" ========= strings =========
4546 .
4547 .TP
4548 .ESC * s
4549 Interpolate string with one-character
4550 .RI name\~ s .
4551 .
4552 .
4553 .TP
4554 .ESC *( st
4555 Interpolate string with two-character
4556 .RI name\~ st .
4557 .
4558 .
4559 .TP
4560 .ESC[] * string
4561 Interpolate string with name
4562 .I string
4563 (of arbitrary length).
4564 .
4565 .
4566 .TP
4567 .ESC[] * "string arg \fR\&.\|.\|.\fP"
4568 Interpolate string with name
4569 .I string
4570 (of arbitrary length),
4571 taking
4572 .I arg
4573 \&.\|.\|.\&
4574 as arguments.
4575 .
4576 .
4577 .\" ========= macro arguments =========
4578 .
4579 .TP
4580 .ESC $0
4581 Interpolate name by which currently executing macro was invoked.
4582 .
4583 .
4584 .TP
4585 .ESC $ n
4586 Interpolate macro or string parameter
4587 .RI numbered\~ n
4588 .RI (1\|\[<=]\| n \|\[<=]\|9).
4589 .
4590 .
4591 .TP
4592 .ESC $( nn
4593 Interpolate macro or string parameter
4594 .RI numbered\~ nn
4595 .RI (01\|\[<=]\| nn \|\[<=]\|99).
4596 .
4597 .TP
4598 .ESC[] $ nnn
4599 Interpolate macro or string parameter
4600 .RI numbered\~ nnn
4601 .RI ( nnn \|\[>=]\|1).
4602 .
4603 .
4604 .TP
4605 .ESC $*
4606 Interpolate concatenation of all macro or string parameters,
4607 separated by spaces.
4608 .
4609 .
4610 .TP
4611 .ESC $@
4612 Interpolate concatenation of all macro or string parameters,
4613 with each surrounded by double quotes and separated by spaces.
4614 .
4615 .
4616 .TP
4617 .ESC $\[ha]
4618 Interpolate concatenation of all macro or string parameters
4619 as if they were arguments to the
4620 .request .ds
4621 request.
4622 .
4623 .
4624 .\" ========= escaped characters =========
4625 .
4626 .
4627 .TP
4628 .ESC \[aq]
4629 is a synonym for
4630 .esc [aa] ,
4631 the acute accent special character.
4632 .
4633 .
4634 .TP
4635 .ESC \[ga]
4636 is a synonym for
4637 .esc [ga] ,
4638 the grave accent special character.
4639 .
4640 .
4641 .TP
4642 .ESC \-
4643 is a synonym for
4644 .esc [\-] ,
4645 the minus sign special character.
4646 .
4647 .
4648 .TP
4649 .ESC _
4650 is a synonym for
4651 .esc [ul] ,
4652 the underrule special character.
4653 .
4654 .
4655 .TP
4656 .ESC %
4657 Control hyphenation.
4658 .
4659 .
4660 .TP
4661 .ESC !
4662 Transparent line.
4663 .
4664 The remainder of the input line is interpreted
4665 (1) when the current diversion is read;
4666 or
4667 (2) if in the top-level diversion,
4668 by the postprocessor
4669 (if any).
4670 .
4671 .
4672 .TP
4673 .ESC? anything
4674 Transparently embed
4675 .IR anything ,
4676 read in copy mode,
4677 in a diversion,
4678 or unformatted as an output comparand in a conditional expression.
4679 .
4680 .
4681 .\" ========= spaces and fixed-width horizontal motions =========
4682 .
4683 .TP
4684 .ESC \f[I]space
4685 Move right one word space.
4686 .
4687 .
4688 .TP
4689 .ESC \[ti]
4690 Insert an unbreakable,
4691 adjustable space.
4692 .
4693 .
4694 .TP
4695 .ESC 0
4696 Move right by the width of a numeral in the current font.
4697 .
4698 .
4699 .TP
4700 .ESC |
4701 Move one-sixth em to the right on typesetters.
4702 .
4703 .
4704 .TP
4705 .ESC \[ha]
4706 Move one-twelfth em to the right on typesetters.
4707 .
4708 .
4709 .TP
4710 .ESC &
4711 Interpolate a dummy character.
4712 .
4713 .
4714 .TP
4715 .ESC )
4716 Interpolate a dummy character that is transparent to end-of-sentence
4717 recognition.
4718 .
4719 .
4720 .TP
4721 .ESC /
4722 Apply italic correction.
4723 .
4724 Use between an immediately adjacent oblique glyph on the left and an
4725 upright glyph on the right.
4726 .
4727 .
4728 .TP
4729 .ESC ,
4730 Apply left italic correction.
4731 .
4732 Use between an immediately adjacent upright glyph on the left and an
4733 oblique glyph on the right.
4734 .
4735 .
4736 .TP
4737 .ESC :
4738 Non-printing break point
4739 (similar to
4740 .esc % ,
4741 but never produces a hyphen glyph).
4742 .
4743 .
4744 .TP
4745 .ESC "" newline
4746 Continue current input line on the next.
4747 .
4748 .
4749 .\" ========= structuring =========
4750 .
4751 .TP
4752 .ESC {
4753 Begin conditional input.
4754 .
4755 .TP
4756 .ESC }
4757 End conditional input.
4758 .
4759 .\" ========= longer escape names =========
4760 .
4761 .TP
4762 .ESC ( gl
4763 Interpolate glyph with two-character name
4764 .IR gl .
4765 .
4766 .
4767 .TP
4768 .ESC[] "" glyph
4769 Interpolate glyph with name
4770 .I glyph
4771 (of arbitrary length).
4772 .
4773 .
4774 .TP
4775 .ESC[] "" "base-char comp \fR\&.\|.\|."
4776 Interpolate composite glyph constructed from
4777 .I base-char
4778 and each component
4779 .IR comp .
4780 .
4781 .
4782 .TP
4783 .ESC[] "" "\f[CB]char\f[]nnn"
4784 Interpolate glyph of eight-bit encoded character
4785 .IR nnn ,
4786 where
4787 .RI 0\|\[<=]\| nnn \|\[<=]\|255.
4788 .
4789 .
4790 .TP
4791 .ESC[] "" "\f[CB]u\f[]nnnn\f[R][\f[]n\f[R][\f[]n\f[R]]]"
4792 Interpolate glyph of Unicode character with code point
4793 .IR nnnn [ n [ n ]]
4794 in uppercase hexadecimal.
4795 .
4796 .
4797 .TP
4798 .ESC[] "" "\f[CB]u\f[]base-char\f[R][\f[]\f[CB]_\f[]\
4799 combining-component\f[R]].\|.\|."
4800 Interpolate composite glyph from Unicode character
4801 .I base-char
4802 and
4803 .IR combining-components .
4804 .
4805 .
4806 .\" ========= alphabetical escape sequences =========
4807 .
4808 .TP
4809 .ESC a
4810 Interpolate a leader in copy mode.
4811 .
4812 .TP
4813 .ESCq A anything
4814 Interpolate 1 if
4815 .I anything
4816 is a valid identifier,
4817 and\~0 otherwise.
4818 .
4819 .TP
4820 .ESCq b string
4821 Build bracket:
4822 pile a sequence of glyphs corresponding to each character in
4823 .I string
4824 vertically,
4825 and center it vertically on the output line.
4826 .
4827 .TP
4828 .ESCq B anything
4829 Interpolate 1 if
4830 .I anything
4831 is a valid numeric expression,
4832 and\~0 otherwise.
4833 .
4834 .
4835 .TP
4836 .ESC c
4837 Continue output line at next input line.
4838 .
4839 .
4840 .TP
4841 .ESCq C glyph
4842 As
4843 .esc[] "" glyph ,
4844 but compatible with other
4845 .I troff \" generic
4846 implementations.
4847 .
4848 .
4849 .TP
4850 .ESC d
4851 Move downward \[12]\~em on typesetters.
4852 .\" XXX: No current groff nroff-mode output driver supports half-line
4853 .\" motions.
4854 .\" (\[12]\~line in
4855 .\" .I nroff
4856 .\" contingent on device support).
4857 .
4858 .
4859 .TP
4860 .ESCq D drawing-command
4861 See subsection \[lq]Drawing commands\[rq] below.
4862 .
4863 .
4864 .TP
4865 .ESC e
4866 Interpolate the escape character.
4867 .
4868 .
4869 .TP
4870 .ESC E
4871 As
4872 .esc e ,
4873 but not interpreted in copy mode.
4874 .
4875 .TP
4876 .ESC fP
4877 Select previous font mounting position
4878 (abstract style or font);
4879 same as
4880 .RB \[lq] .ft \[rq]
4881 or
4882 .RB \[lq] .ft\~P \[rq].
4883 .
4884 .TP
4885 .ESC f F
4886 Select font mounting position,
4887 abstract style,
4888 or font with one-character name or one-digit
4889 .RI position\~ F .
4890 .
4891 .IR F \~cannot
4892 be
4893 .BR P .
4894 .
4895 .TP
4896 .ESC f( ft
4897 Select font mounting position,
4898 abstract style,
4899 or font with two-character name or two-digit
4900 .RI position\~ ft .
4901 .
4902 .TP
4903 .ESC[] f font
4904 Select font mounting position,
4905 abstract style,
4906 or font with arbitrarily long name or position
4907 .IR font .
4908 .
4909 .I font
4910 cannot be
4911 .BR P .
4912 .
4913 .TP
4914 .ESC[] f ""
4915 Select previous font mounting position
4916 (abstract style or font).
4917 .
4918 .TP
4919 .ESC F f
4920 Set default font family to that with one-character
4921 .RI name\~ f .
4922 .
4923 .TP
4924 .ESC F( fm
4925 Set default font family to that with two-character
4926 .RI name\~ fm .
4927 .
4928 .TP
4929 .ESC[] F fam
4930 Set default font family to that with arbitrarily long name
4931 .IR fam .
4932 .
4933 .TP
4934 .ESC[] F ""
4935 Set default font family to previous value.
4936 .
4937 .TP
4938 .ESC g r
4939 Interpolate format of register with one-character
4940 .RI name\~ r .
4941 .
4942 .
4943 .TP
4944 .ESC g( rg
4945 Interpolate format of register with two-character
4946 .RI name\~ rg .
4947 .
4948 .
4949 .TP
4950 .ESC[] g reg
4951 Interpolate format of register with arbitrarily long name
4952 .IR reg .
4953 .
4954 .
4955 .TP
4956 .ESCq h N
4957 Horizontally move the drawing position by
4958 .IR N \~ems
4959 (or specified units);
4960 .B \[or]
4961 may be used.
4962 .
4963 Positive motion is rightward.
4964 .
4965 .
4966 .TP
4967 .ESCq H N
4968 Set height of current font to
4969 .IR N \~scaled
4970 points
4971 (or specified units).
4972 .
4973 .
4974 .TP
4975 .ESC k r
4976 Mark horizontal position in one-character register
4977 .RI name\~ r .
4978 .
4979 .TP
4980 .ESC k( rg
4981 Mark horizontal position in two-character register
4982 .RI name\~ rg .
4983 .
4984 .
4985 .TP
4986 .ESC[] k reg
4987 Mark horizontal position in register with arbitrarily long
4988 .RI name\~ reg .
4989 .
4990 .
4991 .TP
4992 .ESCq l N\/\f[R][\f[]c\f[R]]
4993 Draw horizontal line of length
4994 .I N
4995 with character
4996 .B c
4997 (default:
4998 .BR \[rs][ru] ;
4999 default scaling unit\~\c
5000 .scaleindicator m ).
5001 .
5002 .
5003 .
5004 .TP
5005 .ESCq L N\/\f[R][\f[]c\f[R]]
5006 Draw vertical line of length
5007 .I N
5008 with character
5009 .B c
5010 (default:
5011 .BR \[rs][br] ;
5012 default scaling unit\~\c
5013 .scaleindicator v ).
5014 .
5015 .
5016 .TP
5017 .ESC m c
5018 Set stroke color to that with one-character
5019 .RI name\~ c .
5020 .
5021 .
5022 .TP
5023 .ESC m( cl
5024 Set stroke color to that with two-character
5025 .RI name\~ cl .
5026 .
5027 .
5028 .TP
5029 .ESC[] m color
5030 Set stroke color to that with arbitrarily long
5031 .RI name\~ color .
5032 .
5033 .
5034 .TP
5035 .ESC[] m ""
5036 Restore previous stroke color.
5037 .
5038 .
5039 .TP
5040 .ESC M c
5041 Set fill color to that with one-character
5042 .RI name\~ c .
5043 .
5044 .
5045 .TP
5046 .ESC M( cl
5047 Set fill color to that with two-character
5048 .RI name\~ cl .
5049 .
5050 .
5051 .TP
5052 .ESC[] M color
5053 Set fill color to that with arbitrarily long
5054 .RI name\~ color .
5055 .
5056 .
5057 .TP
5058 .ESC[] M ""
5059 Restore previous fill color.
5060 .
5061 .
5062 .br
5063 .ne 4v \" XXX: why not 3v?
5064 .TP
5065 .ESC n r
5066 Interpolate contents of register with one-character
5067 .RI name\~ r .
5068 .
5069 .
5070 .TP
5071 .ESC n( rg
5072 Interpolate contents of register with two-character
5073 .RI name\~ rg .
5074 .
5075 .
5076 .TP
5077 .ESC[] n reg
5078 Interpolate contents of register with arbitrarily long
5079 .RI name\~ reg .
5080 .
5081 .
5082 .TP
5083 .ESCq N n
5084 Interpolate glyph with
5085 .RI index\~ n
5086 in the current font.
5087 .
5088 .TP
5089 .ESCq o abc\f[R].\|.\|.\f[]
5090 Overstrike centered glyphs of characters
5091 .IR a ,
5092 .IR b ,
5093 .IR c ,
5094 and so on.
5095 .
5096 .TP
5097 .ESC O0
5098 At the outermost suppression level,
5099 disable emission of glyphs and geometric objects to the output
5100 driver.
5101 .
5102 .
5103 .TP
5104 .ESC O1
5105 At the outermost suppression level,
5106 enable emission of glyphs and geometric objects to the output driver.
5107 .
5108 .
5109 .TP
5110 .ESC O2
5111 At the outermost suppression level,
5112 enable glyph and geometric primitive emission to the output driver and
5113 write to the standard error stream the page number,
5114 four bounding box registers enclosing glyphs written since the previous
5115 .B \[rs]O
5116 escape sequence,
5117 the page offset,
5118 line length,
5119 image file name
5120 (if any),
5121 horizontal and vertical device motion quanta,
5122 and input file name.
5123 .
5124 .
5125 .TP
5126 .ESC O3
5127 Begin a nested suppression level.
5128 .
5129 .
5130 .TP
5131 .ESC O4
5132 End a nested suppression level.
5133 .
5134 .
5135 .TP
5136 .ESC[] O "\f[CB]5\f[]Pfile"
5137 At the outermost suppression level,
5138 write the name
5139 .I file
5140 to the standard error stream at
5141 .RI position\~ P ,
5142 which must be one of
5143 .BR l ,
5144 .BR r ,
5145 .BR c ,
5146 or
5147 .BR i .
5148 .
5149 .
5150 .TP
5151 .ESC p
5152 Break output line at next word boundary;
5153 adjust if applicable.
5154 .
5155 .
5156 .TP
5157 .ESC r
5158 Move \[lq]in reverse\[rq] (upward) 1\~em.
5159 .
5160 .
5161 .TP
5162 .ESCq R "name\~\[+-]N"
5163 Set,
5164 increment,
5165 or decrement register
5166 .I name
5167 .RI by\~ N .
5168 .
5169 .
5170 .TP
5171 .ESC s \[+-]N
5172 Set/increase/decrease the type size to/by
5173 .I N
5174 scaled points.
5175 .
5176 .I N
5177 must be a single digit;
5178 0 restores the previous type size.
5179 .
5180 (In compatibility mode only,
5181 a non-zero
5182 .I N
5183 must be in the range 4\[en]39.)
5184 .
5185 Otherwise,
5186 as
5187 .request .ps
5188 request.
5189 .
5190 .
5191 .TP
5192 .ESC s( \[+-]N
5193 .TQ
5194 .fam C
5195 .BI \es \[+-] ( N
5196 .fam
5197 Set/increase/decrease the type size to/by
5198 .I N
5199 scaled points;
5200 .I N
5201 is a two-digit number \[>=]1.
5202 .
5203 As
5204 .request .ps
5205 request.
5206 .
5207 .
5208 .TP
5209 .ESC[] s \[+-]N
5210 .TQ
5211 .fam C
5212 .BI \es \[+-] [ N ]
5213 .fam
5214 .TQ
5215 .ESCq s \[+-]N
5216 .TQ
5217 .fam C
5218 .BI \es \[+-] \[aq] N \[aq]
5219 .fam
5220 Set/increase/decrease the type size to/by
5221 .I N
5222 scaled points.
5223 .
5224 As
5225 .request .ps
5226 request.
5227 .
5228 .
5229 .TP
5230 .ESCq S N
5231 Slant output glyphs by
5232 .I N
5233 degrees;
5234 the direction of text flow is positive.
5235 .
5236 .
5237 .TP
5238 .ESC t
5239 Interpolate a tab in copy mode.
5240 .
5241 .
5242 .TP
5243 .ESC u
5244 Move upward \[12]\~em on typesetters.
5245 .\" XXX: No current groff nroff-mode output driver supports half-line
5246 .\" motions.
5247 .\" (\[12]\~line in
5248 .\" .I nroff
5249 .\" contingent on device support).
5250 .
5251 .
5252 .TP
5253 .ESCq v N
5254 Vertically move the drawing position by
5255 .IR N \~vees
5256 (or specified units);
5257 .B \[or]
5258 may be used.
5259 .
5260 Positive motion is downward.
5261 .
5262 .
5263 .TP
5264 .ESC V e
5265 Interpolate contents of environment variable with one-character
5266 .RI name\~ e .
5267 .
5268 .
5269 .TP
5270 .ESC V( ev
5271 Interpolate contents of environment variable with two-character
5272 .RI name\~ ev .
5273 .
5274 .
5275 .TP
5276 .ESC[] V env
5277 Interpolate contents of environment variable with arbitrarily long
5278 .RI name\~ env .
5279 .
5280 .
5281 .TP
5282 .ESCq w anything
5283 Interpolate width of
5284 .IR anything ,
5285 formatted in a dummy environment.
5286 .
5287 .
5288 .TP
5289 .ESCq x N
5290 Increase vertical spacing of pending output line by
5291 .IR N \~vees
5292 (or specified units;
5293 negative before,
5294 positive after).
5295 .
5296 .TP
5297 .ESCq X anything
5298 Write
5299 .I anything
5300 to
5301 .I \%troff
5302 output as a device control command.
5303 .
5304 Within
5305 .IR anything ,
5306 the escape sequences
5307 .BR \[rs]& ,
5308 .BR \[rs]) ,
5309 .BR \[rs]% ,
5310 and
5311 .B \[rs]:
5312 are ignored;
5313 .BI \[rs] space
5314 and
5315 .B \[rs]\[ti]
5316 are converted to single space characters;
5317 and
5318 .B \[rs]\[rs]
5319 has its escape character stripped.
5320 .
5321 So that the basic Latin subset of the Unicode character
5322 set can be reliably encoded in
5323 .I anything,
5324 the special character escape sequences
5325 .BR \[rs]\- ,
5326 .BR \[rs][aq] ,
5327 .BR \[rs][dq] ,
5328 .BR \[rs][ga] ,
5329 .BR \[rs][ha] ,
5330 .BR \[rs][rs] ,
5331 and
5332 .B \[rs][ti]
5333 are mapped to basic Latin characters;
5334 see
5335 .MR groff_char 7 .
5336 .
5337 For this transformation,
5338 character translations and special character definitions are ignored.
5339 .
5340 .TP
5341 .ESC Y n
5342 Write contents of macro or string
5343 .I n
5344 to
5345 .I \%troff
5346 output as a device control command.
5347 .
5348 .TP
5349 .ESC Y( nm
5350 Write contents of macro or string
5351 .I nm
5352 to
5353 .I \%troff
5354 output as a device control command.
5355 .
5356 .TP
5357 .ESC[] Y name
5358 Write contents of macro or string
5359 .I name
5360 to
5361 .I \%troff
5362 output as a device control command.
5363 .
5364 .TP
5365 .ESC z c
5366 Format character
5367 .I c
5368 with zero width\[em]without advancing the drawing position.
5369 .
5370 .TP
5371 .ESCq Z anything
5372 Save the drawing position,
5373 format
5374 .IR anything ,
5375 then restore it.
5376 .LE
5377 .
5378 .
5379 .\" ====================================================================
5380 .SS "Drawing commands"
5381 .\" ====================================================================
5382 .
5383 .\" BEGIN Keep (roughly) parallel with groff.texi node "Drawing
5384 .\" commands".
5385 Drawing commands direct the output device to render geometrical objects
5386 rather than glyphs.
5387 .
5388 Specific devices may support only a subset,
5389 or may feature additional ones;
5390 consult the man page for the output driver in use.
5391 .
5392 Terminal devices in particular implement almost none.
5393 .
5394 .
5395 .P
5396 Rendering starts at the drawing position;
5397 when finished,
5398 the drawing position is left at the rightmost point of the object,
5399 even for closed figures,
5400 except where noted.
5401 .
5402 GNU
5403 .I troff \" GNU
5404 draws stroked (outlined) objects with the stroke color,
5405 and shades filled ones with the fill color.
5406 .
5407 See section \[lq]Colors\[rq] above.
5408 .
5409 Coordinates
5410 .I h
5411 and
5412 .I v
5413 are horizontal and vertical motions relative to the drawing position
5414 or previous point in the command.
5415 .
5416 The default scaling unit for horizontal measurements
5417 (and diameters of circles)
5418 .RB is\~ m ;
5419 for vertical ones,
5420 .BR v .
5421 .
5422 .
5423 .P
5424 Circles,
5425 ellipses,
5426 and polygons can be drawn stroked or filled.
5427 .
5428 These are independent properties;
5429 if you want a filled,
5430 stroked figure,
5431 you must draw the same figure twice using each drawing command.
5432 .
5433 A filled figure is always smaller than an outlined one because the
5434 former is drawn only within its defined area,
5435 whereas strokes have a line thickness
5436 (set with
5437 .BR \[rs]D\[aq]t\[aq] ).
5438 .
5439 .
5440 .P
5441 .LS
5442 .TP
5443 .BI \[rs]D\[aq]\[ti]\~ "h1 v1"\~\c
5444 .RI .\|.\|.\~ "hn vn"\c
5445 .B \[aq]
5446 Draw B-spline to each point in sequence,
5447 leaving drawing position at
5448 .RI ( hn ,\~ vn ).
5449 .
5450 .\" XXX: This is one case where a valid coordinate pair could be off the
5451 .\" page (even negative) and we need to discuss this frankly.
5452 .TP
5453 .BI \[rs]D\[aq]a\~ "hc vc h v" \[aq]
5454 Draw circular arc centered at
5455 .RI ( hc ,\~ vc )
5456 counterclockwise from the drawing position to a point
5457 .RI ( h ,\~ v )
5458 relative to the center.
5459 .
5460 .RI ( hc ,\~ vc )
5461 is adjusted to the point nearest the perpendicular bisector of the arc's
5462 chord.
5463 .
5464 .TP
5465 .BI \[rs]D\[aq]c\~ "d" \[aq]
5466 Draw circle of diameter
5467 .I d
5468 with its leftmost point at the drawing position.
5469 .
5470 .TP
5471 .BI \[rs]D\[aq]C\~ "d" \[aq]
5472 As
5473 .BR \[rs]D\[aq]C\[aq] ,
5474 but the circle is filled.
5475 .
5476 .TP
5477 .BI \[rs]D\[aq]e\~ "h v" \[aq]
5478 Draw ellipse of width
5479 .I h
5480 and height
5481 .I v
5482 with its leftmost point at the drawing position.
5483 .
5484 .\" How do we draw an ellipse with rotated axes?
5485 .TP
5486 .BI \[rs]D\[aq]E\~ "h v" \[aq]
5487 As
5488 .BR \[rs]D\[aq]e\[aq] ,
5489 but the ellipse is filled.
5490 .
5491 .\" XXX: Df and dF are taken care of by \M and .defcolor.
5492 .TP
5493 .BI \[rs]D\[aq]l\~ "h v" \[aq]
5494 Draw line from the drawing position to
5495 .RI ( h ,\~ v ).
5496 .
5497 .TP
5498 .BI \[rs]D\[aq]p\~ "h1 v1"\~\c
5499 .RI .\|.\|.\~ "hn vn"\c
5500 .B \[aq]
5501 Draw polygon with vertices at drawing position and each point
5502 in sequence.
5503 .
5504 GNU
5505 .I troff \" GNU
5506 closes the polygon by drawing a line from
5507 .RI ( hn ,\~ vn )
5508 back to the initial drawing position.
5509 .
5510 .\" XXX: This would be the "STUPID_DRAWING_POSITIONING" complained of in
5511 .\" src/libs/libdriver/input.cpp. It is neither the rightmost point
5512 .\" of the figure nor the initial drawing position that GNU troff
5513 .\" automatically returned to to close the figure.
5514 Afterward,
5515 the drawing position is left at
5516 .RI ( hn ,\~ vn ).
5517 .
5518 .TP
5519 .BI \[rs]D\[aq]P\~ "h1 v1"\~\c
5520 .RI .\|.\|.\~ "hn vn"\c
5521 .B \[aq]
5522 As
5523 .BR \[rs]D\[aq]p\[aq] ,
5524 but the polygon is filled.
5525 .
5526 .TP
5527 .BI \[rs]D\[aq]t\~ "n" \[aq]
5528 Set stroke thickness of geometric objects to
5529 .RI to\~ n
5530 basic units.
5531 .
5532 A zero
5533 .I n
5534 selects the minimal supported thickness.
5535 .
5536 A negative
5537 .I n
5538 selects a thickness proportional to the type size;
5539 this is the default.
5540 .LE
5541 .\" END Keep (roughly) parallel with groff.texi node "Drawing
5542 .\" commands".
5543 .
5544 .
5545 .\" ====================================================================
5546 .SS "Device control commands"
5547 .\" ====================================================================
5548 .
5549 The
5550 .B .device
5551 and
5552 .B .devicem
5553 requests,
5554 and
5555 .B \[rs]X
5556 and
5557 .B \[rs]Y
5558 escape sequences,
5559 enable documents to pass information directly to a postprocessor.
5560 .
5561 These are useful for
5562 exercising device-specific capabilities that the
5563 .I groff
5564 language does not abstract or generalize;
5565 such functions include the embedding of hyperlinks and image files.
5566 .
5567 Device-specific functions are documented in
5568 each output driver's man page.
5569 .
5570 .
5571 .\" ====================================================================
5572 .SH Strings
5573 .\" ====================================================================
5574 .
5575 .\" BEGIN Keep (roughly) parallel with groff.texi node "Strings".
5576 .I groff
5577 supports strings primarily for user convenience.
5578 .
5579 Conventionally,
5580 if one would define a macro only to interpolate a small amount of text,
5581 without invoking requests or calling any other macros,
5582 one defines a string instead.
5583 .
5584 Only one string is predefined by the language.
5585 .
5586 .
5587 .TPx
5588 .STRING .T
5589 Contains the name of the output device
5590 (for example,
5591 .RB \[lq] utf8 \[rq]
5592 or
5593 .RB \[lq] pdf \[rq] ).
5594 .
5595 .
5596 .P
5597 The
5598 .request .ds
5599 request creates a string with a specified name and contents.
5600 .
5601 If the identifier named by
5602 .request .ds
5603 already exists as an alias,
5604 the target of the alias is redefined.
5605 .
5606 If
5607 .request .ds
5608 is called with only one argument,
5609 the named string becomes empty.
5610 .
5611 Otherwise,
5612 .I \%troff
5613 stores the remainder of the control line in copy mode;
5614 see subsection \[lq]Copy mode\[rq] below.
5615 .
5616 .
5617 .P
5618 The
5619 .esc *
5620 escape sequence dereferences a string's name,
5621 interpolating its contents.
5622 .
5623 If the name does not exist,
5624 it is defined as empty,
5625 nothing is interpolated,
5626 and a warning in category
5627 .RB \%\[lq] mac \[rq]
5628 is emitted.
5629 .
5630 See section \[lq]Warnings\[rq] in
5631 .MR \%troff 1 .
5632 .
5633 The bracketed interpolation form accepts arguments that are handled as
5634 macro arguments are;
5635 see section \[lq]Calling macros\[rq] above.
5636 .
5637 In contrast to macro calls,
5638 however,
5639 if a closing bracket
5640 .B ]
5641 occurs in a string argument,
5642 that argument must be enclosed in double quotes.
5643 .
5644 .B \[rs]*
5645 is interpreted even in copy mode.
5646 .
5647 When defining strings,
5648 argument interpolations must be escaped if they are to reference
5649 parameters from the calling context;
5650 see section \[lq]Parameters\[rq] below.
5651 .
5652 .
5653 .P
5654 An initial neutral double quote
5655 .B \[dq]
5656 in the string contents is stripped to allow embedding of leading spaces.
5657 .
5658 Any other
5659 .B \[dq]
5660 is interpreted literally,
5661 but it is wise to use the special character escape sequence
5662 .B \[rs][dq]
5663 instead if the string might be interpolated as part of a macro argument;
5664 see section \[lq]Calling macros\[rq] above.
5665 .
5666 Strings are not limited to a single input line of text.
5667 .BI \[rs] newline
5668 works just as it does elsewhere.
5669 .
5670 The resulting string is stored
5671 .I without
5672 the newlines.
5673 .
5674 Care is therefore required when interpolating strings while filling is
5675 disabled.
5676 .
5677 It is not possible to embed a newline in a string that will be
5678 interpreted as such when the string is interpolated.
5679 .
5680 To achieve that effect,
5681 use
5682 .B \[rs]*
5683 to interpolate a macro instead.\" see @ref{Punning Names}.
5684 .
5685 .
5686 .P
5687 The
5688 .request .as
5689 request is similar to
5690 .request .ds
5691 but appends to a string instead of redefining it.
5692 .
5693 If
5694 .request .as
5695 is called with only one argument,
5696 no operation is performed
5697 (beyond dereferencing the string).
5698 .
5699 .
5700 .P
5701 Because strings are similar to macros,
5702 they too can be defined to suppress AT&T
5703 .I troff \" AT&T
5704 compatibility mode enablement when interpolated;
5705 see section \[lq]Compatibility mode\[rq] below.
5706 .
5707 The
5708 .request .ds1
5709 request defines a string that suspends compatibility mode when the
5710 string is later interpolated.
5711 .
5712 .request .as1
5713 is likewise similar to
5714 .BR .as ,
5715 with compatibility mode suspended when the appended portion of the
5716 string is later interpolated.
5717 .
5718 .
5719 .P
5720 .B Caution:
5721 Unlike other requests,
5722 the second argument to these requests consumes the remainder of the
5723 input line,
5724 including trailing spaces.
5725 .
5726 Ending string definitions
5727 (and appendments)
5728 with a comment,
5729 even an empty one,
5730 prevents unwanted space from creeping into them during source document
5731 maintenance.
5732 .
5733 .
5734 .br
5735 .ne 3v
5736 .P
5737 Several requests exist to perform rudimentary string operations.
5738 .
5739 Strings can be queried
5740 (\c
5741 .request .length )
5742 and modified
5743 (\c
5744 .request .chop ,
5745 .request .substring ,
5746 .request .stringup ,
5747 .request .stringdown ),
5748 and their names can be manipulated through renaming,
5749 removal,
5750 and aliasing
5751 (\c
5752 .request .rn ,
5753 .request .rm ,
5754 .request .als).
5755 .
5756 .
5757 .P
5758 When a request,
5759 macro,
5760 string,
5761 or diversion is aliased,
5762 redefinitions and appendments \[lq]write through\[rq] alias names.
5763 .
5764 To replace an alias with a separately defined object,
5765 you must use the
5766 .B rm
5767 request on its name first.
5768 .\" END Keep (roughly) parallel with groff.texi node "Strings".
5769 .
5770 .
5771 .\" ====================================================================
5772 .SH Registers
5773 .\" ====================================================================
5774 .
5775 .\" BEGIN Keep (roughly) parallel with groff.texi node "Registers".
5776 In the
5777 .I roff
5778 language,
5779 numbers can be stored in
5780 .I registers.
5781 .
5782 Many built-in registers exist,
5783 supplying anything from the date to details of formatting parameters.
5784 .
5785 You can also define your own.
5786 .
5787 See section \[lq]Identifiers\[rq] above for information on constructing
5788 a valid name for a register.
5789 .
5790 .
5791 .P
5792 Define registers and update their values with the
5793 .B nr
5794 request or the
5795 .B \[rs]R
5796 escape sequence.
5797 .
5798 .
5799 .P
5800 Registers can also be incremented or decremented by a configured amount
5801 at the time they are interpolated.
5802 .
5803 The value of the increment is specified with a third argument to the
5804 .request .nr
5805 request,
5806 and a special interpolation syntax,
5807 .BI \[rs]n \[+-]
5808 is used to alter and then retrieve
5809 the register's value.
5810 .
5811 Together,
5812 these features are called
5813 .IR auto-increment .
5814 .
5815 (A negative auto-increment can be
5816 considered an \[lq]auto-decrement\[rq].)
5817 .
5818 .
5819 .P
5820 Many predefined registers are available.
5821 .
5822 In the following presentation,
5823 the register interpolation syntax
5824 .BI \[rs]n[ name ]
5825 is used to refer to a register
5826 .I name
5827 to clearly distinguish it from a string or request
5828 .IR name .
5829 .
5830 The register name space is separate from that used for requests,
5831 macros,
5832 strings,
5833 and diversions.
5834 .
5835 Bear in mind that the symbols
5836 .B \[rs]n[]
5837 are
5838 .I not
5839 part of the register name.
5840 .\" END Keep (roughly) parallel with groff.texi node "Registers".
5841 .
5842 .
5843 .\" ====================================================================
5844 .SS "Read-only registers"
5845 .\" ====================================================================
5846 .
5847 Predefined registers whose identifiers start with a dot are read-only.
5848 .
5849 Many are Boolean-valued.
5850 .
5851 Some are string-valued,
5852 meaning that they interpolate text.
5853 .
5854 A register name
5855 (without the dot)
5856 is often associated with a request of the same name;
5857 exceptions are noted.
5858 .
5859 .
5860 .P
5861 .LS
5862 .
5863 .TP 15n
5864 .REG .$
5865 Count of arguments passed to currently interpolated macro or string.
5866 .
5867 .TP
5868 .REG .a
5869 Amount of extra post-vertical line space;
5870 see
5871 .esc x .
5872 .
5873 .TP
5874 .REG .A
5875 Approximate output is being formatted (Boolean-valued);
5876 see
5877 .I \%troff
5878 .B \-a
5879 option.
5880 .
5881 .TP
5882 .REG .b
5883 Font emboldening offset;
5884 see
5885 .request .bd .
5886 .
5887 .TP
5888 .REG .br
5889 The normal control character was used to call the currently interpolated
5890 macro (Boolean-valued).
5891 .
5892 .TP
5893 .REG .c
5894 Input line number;
5895 see
5896 .request .lf
5897 and
5898 .register \f[R]\[lq]\f[]c.\f[R]\[rq]\f[] .
5899 .
5900 .TP
5901 .REG .C
5902 Compatibility mode is enabled (Boolean-valued);
5903 see
5904 .request .cp .
5905 .
5906 Always false when processing
5907 .request .do ;
5908 see
5909 .register .cp .
5910 .
5911 .TP
5912 .REG .cdp
5913 Depth of last glyph formatted in the environment;
5914 .\" TODO: Give page a discussion of glyph properties and move this.
5915 positive if glyph extends below the baseline.
5916 .
5917 .TP
5918 .REG .ce
5919 Count of output lines remaining to be centered.
5920 .
5921 .TP
5922 .REG .cht
5923 Height of last glyph formatted in the environment;
5924 .\" TODO: Give page a discussion of glyph properties and move this.
5925 positive if glyph extends above the baseline.
5926 .
5927 .TP
5928 .REG .color
5929 Color output is enabled (Boolean-valued).
5930 .
5931 .TP
5932 .REG .cp
5933 Within
5934 .request .do ,
5935 the saved value of compatibility mode;
5936 see
5937 .register .C .
5938 .
5939 .TP
5940 .REG .csk
5941 Skew of the last glyph formatted in the environment;
5942 .\" TODO: Give page a discussion of glyph properties and move this.
5943 skew is how far to the right of the center of a glyph the center of an
5944 accent over that glyph should be placed.
5945 .
5946 .TP
5947 .REG .d
5948 Vertical drawing position in diversion.
5949 .
5950 .TP
5951 .REG .ev
5952 Name of environment (string-valued).
5953 .
5954 .TP
5955 .REG .f
5956 Mounting position of selected font;
5957 see
5958 .request .ft
5959 and
5960 .esc f .
5961 .
5962 .TP
5963 .REG .F
5964 Name of input file (string-valued);
5965 see
5966 .request .lf .
5967 .
5968 .TP
5969 .REG .fam
5970 Name of default font family (string-valued).
5971 .
5972 .TP
5973 .REG .fn
5974 Resolved name of selected font (string-valued);
5975 see
5976 .request .ft
5977 and
5978 .esc f .
5979 .
5980 .TP
5981 .REG .fp
5982 Next non-zero free font mounting position index.
5983 .
5984 .TP
5985 .REG .g
5986 Always true in GNU
5987 .I troff \" GNU
5988 (Boolean-valued).
5989 .
5990 .TP
5991 .REG .h
5992 Text baseline high-water mark on page or in diversion.
5993 .
5994 .TP
5995 .REG .H
5996 Horizontal motion quantum of output device in basic units.
5997 .
5998 .TP
5999 .REG .height
6000 Font height;
6001 see
6002 .esc H .
6003 .
6004 .TP
6005 .REG .hla
6006 Hyphenation language in environment (string-valued).
6007 .
6008 .TP
6009 .REG .hlc
6010 Count of immediately preceding consecutive hyphenated lines in
6011 environment.
6012 .
6013 .TP
6014 .REG .hlm
6015 Maximum quantity of consecutive hyphenated lines allowed in environment.
6016 .
6017 .TP
6018 .REG .hy
6019 Automatic hyphenation mode in environment.
6020 .
6021 .TP
6022 .REG .hym
6023 Hyphenation margin in environment.
6024 .
6025 .TP
6026 .REG .hys
6027 Hyphenation space adjustment threshold in environment.
6028 .
6029 .TP
6030 .REG .i
6031 Indentation amount;
6032 see
6033 .request .in .
6034 .
6035 .TP
6036 .REG .in
6037 Indentation amount applicable to the pending output line;
6038 see
6039 .request .ti .
6040 .
6041 .TP
6042 .REG .int
6043 Previous output line was \[lq]interrupted\[rq] or continued with
6044 .esc c
6045 (Boolean-valued).
6046 .
6047 .TP
6048 .REG .j
6049 Adjustment mode encoded as an integer;
6050 see
6051 .request .ad
6052 and
6053 .request .na .
6054 .
6055 Do not interpret or perform arithmetic on its value.
6056 .
6057 .TP
6058 .REG .k
6059 Horizontal drawing position relative to indentation.
6060 .
6061 .TP
6062 .REG .kern
6063 Pairwise kerning is enabled (Boolean-valued).
6064 .
6065 .TP
6066 .REG .l
6067 Line length;
6068 see
6069 .request .ll .
6070 .
6071 .TP
6072 .REG .L
6073 Line spacing;
6074 see
6075 .request .ls .
6076 .
6077 .TP
6078 .REG .lg
6079 Ligature mode.
6080 .
6081 .TP
6082 .REG .linetabs
6083 Line-tabs mode is enabled (Boolean-valued).
6084 .
6085 .TP
6086 .REG .ll
6087 Line length applicable to the pending output line.
6088 .
6089 .TP
6090 .REG .lt
6091 Title length.
6092 .
6093 .TP
6094 .REG .m
6095 Stroke color (string-valued);
6096 see
6097 .request .gcolor
6098 and
6099 .esc m .
6100 .
6101 Empty if the stroke color is the default.
6102 .
6103 .TP
6104 .REG .M
6105 Fill color (string-valued);
6106 see
6107 .request .fcolor
6108 and
6109 .esc M .
6110 .
6111 Empty if the fill color is the default.
6112 .
6113 .TP
6114 .REG .n
6115 Length of formatted output on previous output line.
6116 .
6117 .TP
6118 .REG .ne
6119 Amount of vertical space required by last
6120 .request .ne
6121 that caused a trap to be sprung;
6122 also see
6123 .register .trunc .
6124 .
6125 .TP
6126 .REG .nm
6127 Output line numbering is enabled (Boolean-valued).
6128 .
6129 .TP
6130 .REG .nn
6131 Count of output lines remaining to have numbering suppressed.
6132 .
6133 .TP
6134 .REG .ns
6135 No-space mode is enabled (Boolean-valued).
6136 .
6137 .TP
6138 .REG .o
6139 Page offset;
6140 see
6141 .request .po .
6142 .
6143 .TP
6144 .REG .O
6145 Output suppression nesting level;
6146 see
6147 .esc O .
6148 .
6149 .TP
6150 .REG .p
6151 Page length;
6152 see
6153 .request .pl .
6154 .
6155 .TP
6156 .REG .P
6157 The page is selected for output (Boolean-valued);
6158 see
6159 .I \%troff
6160 .B \-o
6161 option.
6162 .
6163 .TP
6164 .REG .pe
6165 Page ejection is in progress (Boolean-valued).
6166 .
6167 .TP
6168 .REG .pn
6169 Number of the next page.
6170 .
6171 .TP
6172 .REG .ps
6173 Type size in scaled points.
6174 .
6175 .TP
6176 .REG .psr
6177 Most recently requested type size in scaled points;
6178 see
6179 .request .ps
6180 and
6181 .esc s .
6182 .
6183 .TP
6184 .REG .pvs
6185 Post-vertical line spacing.
6186 .
6187 .TP
6188 .REG .R
6189 Count of available unused registers;
6190 always 10,000 in GNU
6191 .IR troff . \" GNU
6192 .
6193 .TP
6194 .REG .rj
6195 Count of lines remaining to be right-aligned.
6196 .
6197 .TP
6198 .REG .s
6199 Type size in points as a decimal fraction (string-valued);
6200 see
6201 .request .ps
6202 and
6203 .esc s .
6204 .
6205 .TP
6206 .REG .slant
6207 Slant of font in degrees;
6208 see
6209 .esc S .
6210 .
6211 .TP
6212 .REG .sr
6213 Most recently requested type size in points as a decimal fraction
6214 (string-valued);
6215 see
6216 .request .ps
6217 and
6218 .esc s .
6219 .
6220 .TP
6221 .REG .ss
6222 Size of minimal inter-word space in twelfths of the space width of the
6223 selected font.
6224 .
6225 .TP
6226 .REG .sss
6227 Size of additional inter-sentence space in twelfths of the space width
6228 of the selected font.
6229 .
6230 .TP
6231 .REG .sty
6232 Selected abstract style (string-valued);
6233 see
6234 .request .ft
6235 and
6236 .esc f .
6237 .
6238 .TP
6239 .REG .t
6240 Distance to next vertical position trap;
6241 see
6242 .request .wh
6243 and
6244 .request .ch .
6245 .
6246 .TP
6247 .REG .T
6248 An output device was explicitly selected (Boolean-valued);
6249 see
6250 .I \%troff
6251 .B \-T
6252 option.
6253 .
6254 .TP
6255 .REG .tabs
6256 Representation of tab settings suitable for use as argument to
6257 .request .ta
6258 (string-valued).
6259 .
6260 .TP
6261 .REG .trunc
6262 Amount of vertical space truncated by the most recently sprung
6263 vertical position trap,
6264 or,
6265 if the trap was sprung by an
6266 .request .ne ,
6267 minus the amount of vertical motion produced by
6268 .request .ne ;
6269 also see
6270 .register .ne .
6271 .
6272 .TP
6273 .REG .u
6274 Filling is enabled (Boolean-valued);
6275 see
6276 .request .fi
6277 and
6278 .request .nf .
6279 .
6280 .TP
6281 .REG .U
6282 Unsafe mode is enabled (Boolean-valued);
6283 see
6284 .I \%troff
6285 .B \-U
6286 option.
6287 .
6288 .TP
6289 .REG .v
6290 Vertical line spacing;
6291 see
6292 .request .vs .
6293 .
6294 .TP
6295 .REG .V
6296 Vertical motion quantum of the output device in basic units.
6297 .
6298 .TP
6299 .REG .vpt
6300 Vertical position traps are enabled (Boolean-valued).
6301 .
6302 .TP
6303 .REG .w
6304 Width of previous glyph formatted in the environment.
6305 .
6306 .TP
6307 .REG .warn
6308 Sum of the numeric codes of enabled warning categories.
6309 .
6310 .TP
6311 .REG .x
6312 Major version number of the running
6313 .I \%troff
6314 formatter.
6315 .
6316 .TP
6317 .REG .y
6318 Minor version number of the running
6319 .I \%troff
6320 formatter.
6321 .
6322 .TP
6323 .REG .Y
6324 Revision number of the running
6325 .I \%troff
6326 formatter.
6327 .
6328 .TP
6329 .REG .z
6330 Name of diversion (string-valued).
6331 .
6332 Empty if output is directed to the top-level diversion.
6333 .
6334 .TP
6335 .REG .zoom
6336 Zoom multiplier of current font
6337 (in thousandths;
6338 zero if no magnification);
6339 see
6340 .request .fzoom .
6341 .LE
6342 .
6343 .
6344 .\" ====================================================================
6345 .SS "Writable predefined registers"
6346 .\" ====================================================================
6347 .
6348 Several registers are predefined but also modifiable;
6349 some are updated upon interpretation of certain requests or escape
6350 sequences.
6351 .
6352 Date- and time-related registers are set to the local time as determined
6353 by
6354 .MR localtime 3
6355 when the formatter launches.
6356 .
6357 This initialization can be overridden by
6358 .I \%SOURCE_DATE_EPOCH
6359 and
6360 .IR TZ ;
6361 see section \[lq]Environment\[rq] of
6362 .MR groff 1 .
6363 .
6364 .
6365 .P
6366 .LS
6367 .
6368 .TP 15n
6369 .REG $$
6370 Process ID of
6371 .IR \%troff .
6372 .
6373 .TP
6374 .REG %
6375 Page number.
6376 .
6377 .TP
6378 .REG c.
6379 Input line number.
6380 .
6381 .TP
6382 .REG ct
6383 Union of character types of each glyph rendered into dummy environment
6384 by
6385 .esc w .
6386 .
6387 .TP
6388 .REG dl
6389 Width of last closed diversion.
6390 .
6391 .TP
6392 .REG dn
6393 Height of last closed diversion.
6394 .
6395 .TP
6396 .REG dw
6397 Day of the week (1\[en]7;
6398 1 is Sunday).
6399 .
6400 .TP
6401 .REG dy
6402 Day of the month (1\[en]31).
6403 .
6404 .TP
6405 .REG hours
6406 Count of hours elapsed since midnight (0\[en]23).
6407 .
6408 .TP
6409 .REG hp
6410 Horizontal drawing position relative to start of input line.
6411 .
6412 .TP
6413 .REG llx
6414 Lower-left
6415 .I x
6416 coordinate
6417 (in PostScript units)
6418 of PostScript image;
6419 see
6420 .request .psbb .
6421 .
6422 .TP
6423 .REG lly
6424 Lower-left
6425 .I y
6426 coordinate
6427 (in PostScript units)
6428 of PostScript image;
6429 see
6430 .request .psbb .
6431 .
6432 .TP
6433 .REG ln
6434 Output line number;
6435 see
6436 .request .nm .
6437 .
6438 .TP
6439 .REG lsn
6440 Count of leading spaces on input line.
6441 .
6442 .TP
6443 .REG lss
6444 Amount of horizontal space corresponding to leading spaces on input
6445 line.
6446 .
6447 .TP
6448 .REG minutes
6449 Count of minutes elapsed in the hour (0\[en]59).
6450 .
6451 .TP
6452 .REG mo
6453 Month of the year (1\[en]12).
6454 .
6455 .TP
6456 .REG nl
6457 Vertical drawing position.
6458 .
6459 .TP
6460 .REG opmaxx
6461 .TP
6462 .REG opmaxy
6463 .TP
6464 .REG opminx
6465 .TP
6466 .REG opminy
6467 These four registers mark the top left- and bottom right-hand corners of
6468 a rectangle encompassing all formatted output on the page.
6469 .
6470 They are reset to \-1 by
6471 .B \[rs]O0
6472 or
6473 .BR \[rs]O1 .
6474 .
6475 .TP
6476 .REG rsb
6477 As
6478 .register sb ,
6479 adding maximum glyph height to measurement.
6480 .
6481 .TP
6482 .REG rst
6483 As
6484 .register st ,
6485 adding maximum glyph depth to measurement.
6486 .
6487 .TP
6488 .REG sb
6489 Maximum displacement of text baseline below its original position
6490 after rendering into dummy environment by
6491 .esc w .
6492 .
6493 .TP
6494 .REG seconds
6495 Count of seconds elapsed in the minute (0\[en]60). \" not 59; see POSIX
6496 .
6497 .TP
6498 .REG skw
6499 Skew of last glyph rendered into dummy environment by
6500 .esc w .
6501 .
6502 .TP
6503 .REG slimit
6504 The maximum depth of
6505 .IR \%troff 's
6506 internal input stack.
6507 .
6508 If \[<=]0,
6509 there is no limit:
6510 recursion can continue until available memory is exhausted.
6511 .
6512 The default is 1,000.
6513 .
6514 .TP
6515 .REG ssc
6516 Subscript correction of last glyph rendered into dummy environment by
6517 .esc w .
6518 .
6519 .TP
6520 .REG st
6521 Maximum displacement of text baseline above its original position
6522 after rendering into dummy environment by
6523 .esc w .
6524 .
6525 .TP
6526 .REG systat
6527 Return value of
6528 .I system()
6529 function; see
6530 .request .sy .
6531 .
6532 .TP
6533 .REG urx
6534 Upper-right
6535 .I x
6536 coordinate
6537 (in PostScript units)
6538 of PostScript image;
6539 see
6540 .request .psbb .
6541 .
6542 .TP
6543 .REG ury
6544 Upper-right
6545 .I y
6546 coordinate
6547 (in PostScript units)
6548 of PostScript image;
6549 see
6550 .request .psbb .
6551 .
6552 .TP
6553 .REG year
6554 Gregorian year.
6555 .
6556 .TP
6557 .REG yr
6558 Gregorian year minus 1900.
6559 .LE
6560 .
6561 .
6562 .\" ====================================================================
6563 .SH "Using fonts"
6564 .\" ====================================================================
6565 .
6566 .\" BEGIN Keep (roughly) parallel with groff.texi node "Using Fonts".
6567 In digital typography,
6568 a
6569 .I font
6570 is a collection of characters in a specific typeface that a device can
6571 render as glyphs at a desired size.
6572 .
6573 (Terminals and some output devices have fonts that render at only one or
6574 two sizes.
6575 .
6576 As examples of the latter,
6577 take the
6578 .I groff
6579 .B lj4
6580 device's
6581 Lineprinter,
6582 and
6583 .BR lbp 's
6584 Courier and Elite faces.)
6585 .
6586 .
6587 A
6588 .I roff
6589 formatter can change typefaces at any point in the text.
6590 .
6591 The basic faces are a set of
6592 .I styles
6593 combining upright and slanted shapes with normal and heavy stroke
6594 weights:
6595 .RB \[lq] R \[rq],
6596 .RB \[lq] I \[rq],
6597 .RB \[lq] B \[rq],
6598 and
6599 .RB \[lq] BI \[rq]\[em]\c
6600 these stand for
6601 .I roman,
6602 .I bold,
6603 .I italic,
6604 and
6605 .I bold-italic.
6606 .
6607 For linguistic text,
6608 GNU
6609 .I troff \" GNU
6610 groups typefaces into
6611 .I families
6612 containing each of these styles.
6613 .
6614 (Font designers prepare families such that the styles share esthetic
6615 properties.)
6616 .
6617 A
6618 .I "text font"
6619 is thus often a family combined with a style,
6620 but it need not be:
6621 consider the
6622 .B ps
6623 and
6624 .B pdf
6625 devices'
6626 .B ZCMI
6627 (Zapf Chancery Medium italic)\[em]\c
6628 often,
6629 no other style of Zapf Chancery Medium is provided.
6630 .
6631 On typesetting devices,
6632 at least one
6633 .I "special font"
6634 is available,
6635 comprising
6636 .I unstyled
6637 glyphs for mathematical operators and other purposes.
6638 .
6639 .
6640 .P
6641 Like AT&T
6642 .I troff, \" AT&T
6643 GNU
6644 .I troff \" GNU
6645 does not itself load or manipulate a digital font file;
6646 .\" @footnote{Historically, the fonts @code{troff}s dealt with were not
6647 .\" Free Software or, as with the Graphic Systems C/A/T, did not even
6648 .\" exist in the digital domain.}
6649 instead it
6650 works with a
6651 .I font description file
6652 that characterizes it,
6653 including its glyph repertoire and the
6654 .I metrics
6655 (dimensions) of each glyph.
6656 .
6657 This information permits the formatter to accurately place glyphs with
6658 respect to each other.
6659 .
6660 Before using a font description,
6661 the formatter associates it with a
6662 .I "mounting position,"
6663 a place in an ordered list of available typefaces.
6664 .
6665 So that a document need not be strongly coupled to a specific font
6666 family,
6667 in GNU
6668 .I troff \" GNU
6669 an output device can associate a style in the abstract sense with a
6670 mounting position.
6671 .
6672 Thus the default family can be combined with a style dynamically,
6673 producing a
6674 .I "resolved font name."
6675 .
6676 .
6677 .P
6678 Fonts often have trademarked names,
6679 and even Free Software fonts can require renaming upon modification.
6680 .
6681 .I groff
6682 maintains a convention that a device's serif font family is given the
6683 name
6684 .B T
6685 (\[lq]Times\[rq]),
6686 its sans-serif family
6687 .B H
6688 (\[lq]Helvetica\[rq]),
6689 and its
6690 monospaced family
6691 .B C
6692 (\[lq]Courier\[rq]).
6693 .
6694 Historical inertia has driven
6695 .IR groff 's
6696 font identifiers to short uppercase abbreviations of font names,
6697 as with
6698 .BR TR ,
6699 .BR TB ,
6700 .BR TI ,
6701 .BR TBI ,
6702 and a special font
6703 .BR S .
6704 .
6705 .
6706 .P
6707 The default family used with abstract styles can be changed at any time;
6708 initially,
6709 it
6710 .RB is\~ T .
6711 .
6712 Typically,
6713 abstract styles are arranged in the first four mounting positions in the
6714 order shown above.
6715 .
6716 The default mounting position,
6717 and therefore style,
6718 is always
6719 .B 1
6720 .RB ( R ).
6721 .
6722 By issuing appropriate formatter instructions,
6723 you can override these defaults before your document writes its first
6724 glyph.
6725 .
6726 .
6727 .P
6728 Terminal output devices cannot change font families and lack special
6729 fonts.
6730 .
6731 They support style changes by overstriking,
6732 or by altering ISO\~6429/\:ECMA-48
6733 .I "graphic renditions"
6734 (character cell attributes).
6735 .\" END Keep (roughly) parallel with groff.texi node "Using Fonts".
6736 .
6737 .
6738 .\" ====================================================================
6739 .SH Hyphenation
6740 .\" ====================================================================
6741 .
6742 When filling,
6743 .I groff
6744 hyphenates words as needed at user-specified and automatically
6745 determined hyphenation points.
6746 .
6747 Explicitly hyphenated words such as \[lq]mother-in-law\[rq] are always
6748 eligible for breaking after each of their hyphens.
6749 .
6750 The hyphenation
6751 .RB character\~ \[rs]%
6752 and non-printing break
6753 .RB point\~ \[rs]:
6754 escape sequences may be used to control the hyphenation and breaking of
6755 individual words.
6756 .
6757 The
6758 .B .hw
6759 request sets user-defined hyphenation points for specified words at any
6760 subsequent occurrence.
6761 .
6762 Otherwise,
6763 .I groff
6764 determines hyphenation points automatically by default.
6765 .
6766 .
6767 .P
6768 Several requests influence automatic hyphenation.
6769 .
6770 Because conventions vary,
6771 a variety of hyphenation modes is available to the
6772 .B .hy
6773 request;
6774 these determine whether hyphenation will apply to a word prior to
6775 breaking a line at the end of a page
6776 (more or less;
6777 see below for details),
6778 and at which positions within that word automatically determined
6779 hyphenation points are permissible.
6780 .
6781 The default is
6782 .RB \[lq] 1 \[rq]
6783 for historical reasons,
6784 but this is not an appropriate value for the English hyphenation
6785 patterns used by
6786 .IR groff ;
6787 localization macro files loaded by
6788 .I troffrc
6789 and macro packages often override it.
6790 .
6791 .
6792 .TP
6793 .B 0
6794 disables hyphenation.
6795 .
6796 .
6797 .TP
6798 .B 1
6799 enables hyphenation except after the first and before the last character
6800 of a word.
6801 .
6802 .
6803 .P
6804 The remaining values \[lq]imply\[rq]
6805 .BR 1 ;
6806 that is,
6807 they enable hyphenation under the same conditions as
6808 .RB \[lq] ".hy 1" \[rq],
6809 and then apply or lift restrictions relative to that basis.
6810 .
6811 .
6812 .TP
6813 .B 2
6814 disables hyphenation of the last word on a page.
6815 .
6816 (Hyphenation is prevented if the next page location trap is closer to
6817 the vertical drawing position than the next text baseline would be.
6818 .
6819 See section \[lq]Traps\[rq] below.)
6820 .
6821 .
6822 .TP
6823 .B 4
6824 disables hyphenation before the last two characters of a word.
6825 .
6826 .
6827 .TP
6828 .B 8
6829 disables hyphenation after the first two characters of a word.
6830 .
6831 .
6832 .TP
6833 .B 16
6834 enables hyphenation before the last character of a word.
6835 .
6836 .
6837 .TP
6838 .B 32
6839 enables hyphenation after the first character of a word.
6840 .
6841 .
6842 .P
6843 Apart from value\~2,
6844 restrictions imposed by the hyphenation mode are
6845 .I not
6846 respected for words whose hyphenations have been specified with the
6847 hyphenation character
6848 .RB (\[lq] \|\[rs]% \[rq]
6849 by default)
6850 or the
6851 .B .hw
6852 request.
6853 .
6854 .
6855 .P
6856 Nonzero values are additive.
6857 .
6858 For example,
6859 mode\~12 causes
6860 .I groff
6861 to hyphenate neither the last two nor the first two characters of a
6862 word.
6863 .
6864 Some values cannot be used together because they contradict;
6865 for instance,
6866 values 4 and\~16,
6867 and values 8 and\~32.
6868 .
6869 As noted,
6870 it is superfluous to add\~1 to any non-zero even mode.
6871 .
6872 .
6873 .br
6874 .ne 2v
6875 .P
6876 The places within a word that are eligible for hyphenation are
6877 determined by language-specific data
6878 .RB ( .hla ,
6879 .BR .hpf ,
6880 and
6881 .BR .hpfa )
6882 and lettercase relationships
6883 .RB ( .hcode
6884 and
6885 .BR .hpfcode ).
6886 .
6887 Furthermore,
6888 hyphenation of a word might be suppressed due to a limit on
6889 consecutive hyphenated lines
6890 .RB ( .hlm ),
6891 a minimum line length threshold
6892 .RB ( .hym ),
6893 or because the line can instead be adjusted with additional inter-word
6894 space
6895 .RB ( .hys ).
6896 .
6897 .
6898 .\" ====================================================================
6899 .SH Localization
6900 .\" ====================================================================
6901 .
6902 The set of hyphenation patterns is associated with the hyphenation
6903 language set by the
6904 .B .hla
6905 request.
6906 .
6907 The
6908 .B .hpf
6909 request is usually invoked by a localization file loaded by the
6910 .I troffrc
6911 file.
6912 .
6913 .I groff
6914 provides localization files for several languages;
6915 see
6916 .MR groff_tmac 5 .
6917 .
6918 .
6919 .\" ====================================================================
6920 .SH "Writing macros"
6921 .\" ====================================================================
6922 .
6923 The
6924 .B .de
6925 request defines a macro named for its argument.
6926 .
6927 If that name already exists as an alias,
6928 the target of the alias is redefined;
6929 see section \[lq]Strings\[rq] above.
6930 .
6931 .I \%troff
6932 enters \[lq]copy mode\[rq]
6933 (see below),
6934 storing subsequent input lines as the definition.
6935 .
6936 If the optional second argument is not specified,
6937 the definition ends with the control line
6938 .RB \[lq] .. \[rq]\&
6939 (two dots).
6940 .
6941 Alternatively,
6942 a second argument names a macro whose call syntax ends the definition;
6943 this \[lq]end macro\[rq] is then called normally.
6944 .
6945 Spaces or tabs are permitted after the first control character in the
6946 line containing this ending token,
6947 but a tab immediately after the token prevents its recognition as the
6948 end of a macro definition.
6949 .
6950 Macro definitions can be nested if they use distinct end macros or if
6951 their ending tokens are sufficiently escaped.
6952 .
6953 An end macro need not be defined until it is called.
6954 .
6955 This fact enables a nested macro definition to begin inside one macro
6956 and end inside another.
6957 .
6958 .
6959 .P
6960 Variants of
6961 .B .de
6962 disable compatibility mode and/or indirect the names of the macros
6963 specified for definition or termination:
6964 these are
6965 .BR .de1 ,
6966 .BR .dei ,
6967 and
6968 .BR .dei1 .
6969 .
6970 Append to macro definitions with
6971 .BR .am ,
6972 .BR .am1 ,
6973 .BR .ami ,
6974 and
6975 .BR .ami1 .
6976 .
6977 The
6978 .BR .als ,
6979 .BR .rm ,
6980 and
6981 .B .rn
6982 requests create an alias of,
6983 remove,
6984 and rename a macro,
6985 respectively.
6986 .
6987 .B .return
6988 stops the execution of a macro immediately,
6989 returning to the enclosing context.
6990 .
6991 .
6992 .\" ====================================================================
6993 .SS Parameters
6994 .\" ====================================================================
6995 .
6996 Macro call and string interpolation parameters can be accessed using
6997 escape sequences starting with
6998 .RB \[lq] \|\[rs]$ \[rq].
6999 .
7000 The
7001 .B \[rs]n[.$]
7002 read-only register stores the count of parameters available to a macro
7003 or string;
7004 its value can be changed by the
7005 .B .shift
7006 request,
7007 which dequeues parameters from the current list.
7008 .
7009 The
7010 .B \[rs]$0
7011 escape sequence interpolates the name by which a macro was called.
7012 .
7013 Applying string interpolation to a macro does not change this name.
7014 .
7015 .
7016 .\" ====================================================================
7017 .SS "Copy mode"
7018 .\" ====================================================================
7019 .
7020 When
7021 .I \%troff
7022 processes certain requests,
7023 most importantly those which define or append to a macro or string,
7024 it does so in
7025 .IR "copy mode" :
7026 it copies the characters of the definition into a dedicated storage
7027 region,
7028 interpolating the escape sequences
7029 .BR \[rs]n ,
7030 .BR \[rs]g ,
7031 .BR \[rs]$ ,
7032 .BR \[rs]* ,
7033 .BR \[rs]V ,
7034 and
7035 .B \[rs]?\&
7036 normally;
7037 interpreting
7038 .BI \[rs] newline
7039 immediately;
7040 discarding comments
7041 .B \[rs]"
7042 and
7043 .BR \[rs]# ;
7044 interpolating the current leader,
7045 escape,
7046 or tab character with
7047 .BR \[rs]a ,
7048 .BR \[rs]e ,
7049 and
7050 .BR \[rs]t ,
7051 respectively;
7052 and storing all other escape sequences in an encoded form.
7053 .
7054 The complement of copy mode\[em]a
7055 .I roff
7056 formatter's behavior when not defining or appending to a macro,
7057 string,
7058 or diversion\[em]where all macros are interpolated,
7059 requests invoked,
7060 and valid escape sequences processed immediately upon recognition,
7061 can be termed
7062 .IR "interpretation mode" .
7063 .
7064 .
7065 .P
7066 The escape character,
7067 .B \[rs]
7068 by default,
7069 can escape itself.
7070 .
7071 This enables you to control whether a given
7072 .BR \[rs]n ,
7073 .BR \[rs]g ,
7074 .BR \[rs]$ ,
7075 .BR \[rs]* ,
7076 .BR \[rs]V ,
7077 or
7078 .B \[rs]?\&
7079 escape sequence is interpreted at the time the macro containing it is
7080 defined,
7081 or later when the macro is called.
7082 .
7083 .
7084 .P
7085 You can think of
7086 .B \[rs]\[rs]
7087 as a \[lq]delayed\[rq] backslash;
7088 it is the escape character followed by a backslash from which the escape
7089 character has removed its special meaning.
7090 .
7091 Consequently,
7092 .B \[rs]\[rs]
7093 is not an escape sequence in the usual sense.
7094 .
7095 In any escape sequence
7096 .BI \[rs] X
7097 that
7098 .I \%troff
7099 does not recognize,
7100 the escape character is ignored and
7101 .IR X \~is
7102 output.
7103 .
7104 An unrecognized escape sequence causes a warning in category
7105 .RB \%\[lq] escape \[rq],
7106 with two exceptions,
7107 .B \[rs]\[rs]
7108 being one.
7109 .
7110 The other is
7111 .BR \[rs]. ,
7112 which escapes the control character.
7113 .
7114 It is used to permit nested macro definitions to end without a named
7115 macro call to conclude them.
7116 .
7117 Without a syntax for escaping the control character,
7118 this would not be possible.
7119 .
7120 .I roff
7121 documents should not use the
7122 .B \[rs]\[rs]
7123 or
7124 .B \[rs].\&
7125 character sequences outside of copy mode;
7126 they serve only to obfuscate the input.
7127 .
7128 Use
7129 .B \[rs]e
7130 to represent the escape character,
7131 .B \[rs][rs]
7132 to obtain a backslash glyph,
7133 and
7134 .B \[rs]&
7135 before
7136 .B .\&
7137 and
7138 .B \[aq]
7139 where
7140 .I \%troff
7141 expects them as control characters if you mean to use them literally.
7142 .
7143 .
7144 .br
7145 .ne 2v
7146 .P
7147 Macro definitions can be nested to arbitrary depth.
7148 .
7149 In
7150 .RB \[lq] \|\[rs]\[rs] \[rq],
7151 each escape character is interpreted twice\[em]once in copy mode,
7152 when the macro is defined,
7153 and once in interpretation mode,
7154 when the macro is called.
7155 .
7156 This fact leads to exponential growth in the quantity of escape
7157 characters required to delay interpolation of
7158 .BR \[rs]n ,
7159 .BR \[rs]g ,
7160 .BR \[rs]$ ,
7161 .BR \[rs]* ,
7162 .BR \[rs]V ,
7163 and
7164 .B \[rs]?\&
7165 at each nesting level.
7166 .
7167 An alternative is to use
7168 .BR \[rs]E ,
7169 which represents an escape character that is not interpreted in copy
7170 mode.
7171 .
7172 Because
7173 .B \[rs].\&
7174 is not a true escape sequence,
7175 we can't use
7176 .B \[rs]E
7177 to keep
7178 .RB \[lq] ..\& \[rq]
7179 from ending a macro definition prematurely.
7180 .
7181 If the multiplicity of backslashes complicates maintenance,
7182 use end macros.
7183 .
7184 .
7185 .\" ====================================================================
7186 .SH Traps
7187 .\" ====================================================================
7188 .
7189 .\" BEGIN Keep (roughly) parallel with groff.texi node "Traps".
7190 .I Traps
7191 are locations in the output,
7192 or conditions on the input that,
7193 when reached or fulfilled,
7194 call a specified macro.
7195 .
7196 A
7197 .I "vertical position trap"
7198 calls a macro when the formatter's vertical drawing position reaches or
7199 passes,
7200 in the downward direction,
7201 a certain location on the output page or in a diversion.
7202 .
7203 Its applications include setting page headers and footers,
7204 body text in multiple columns,
7205 and footnotes.
7206 .
7207 These traps can occur at a given location on the page
7208 .RB ( .wh ,\~ .ch );
7209 at a given location in the current diversion
7210 .RB ( .dt )\[em]together,
7211 these are known as
7212 vertical position traps,
7213 which can be disabled and re-enabled
7214 .RB ( .vpt ).
7215 .
7216 .
7217 .P
7218 A diversion is not formatted in the context of a page,
7219 so it lacks page location traps;
7220 instead it can have a
7221 .I "diversion trap."
7222 .
7223 There can exist at most one such vertical position trap per diversion.
7224 .
7225 .
7226 .P
7227 Other kinds of trap can be planted
7228 at a blank line
7229 .RB ( .blm );
7230 at a line with leading space characters
7231 .RB ( .lsm );
7232 after a certain number of productive input lines
7233 .RB ( .it ,\~ .itc );
7234 or at the end of input
7235 .RB ( .em ).
7236 .
7237 Macros called by traps are passed no arguments.
7238 .
7239 Setting a trap is also called
7240 .I planting
7241 one.
7242 .
7243 It is said that a trap is
7244 .I sprung
7245 if its condition is fulfilled.
7246 .\" END Keep (roughly) parallel with groff.texi node "Traps".
7247 .
7248 .
7249 .br
7250 .ne 5v
7251 .P
7252 Registers associated with trap management include
7253 vertical position trap enablement status
7254 .RB ( \[rs]n[.vpt] ),
7255 distance to the next trap
7256 .RB ( \[rs]n[.t] ),
7257 amount of needed
7258 .RB ( .ne -requested)
7259 space that caused the most recent vertical position trap to be sprung
7260 .RB ( \[rs]n[.ne] ),
7261 amount of needed space truncated from the amount requested
7262 .RB ( \[rs]n[.trunc] ),
7263 page ejection status
7264 .RB ( \[rs]n[.pe] ),
7265 and
7266 leading space count
7267 .RB ( \[rs]n[.lsn] )
7268 with its corresponding amount of motion
7269 .RB ( \[rs]n[.lss] ).
7270 .
7271 .
7272 .\" ====================================================================
7273 .SS "Page location traps"
7274 .\" ====================================================================
7275 .
7276 A
7277 .I "page location trap"
7278 is a vertical position trap that applies to
7279 the page;
7280 that is,
7281 to undiverted output.
7282 .
7283 Many can be present;
7284 manage them with
7285 the
7286 .B wh
7287 and
7288 .B ch
7289 requests.
7290 .
7291 Non-negative page locations given to these requests set the trap
7292 relative to the top of the page;
7293 negative values set the trap relative to the bottom of the page.
7294 .
7295 It is not possible to plant a trap less than one basic unit from the
7296 page bottom:
7297 a location of \[lq]\-0\[rq] is interpreted as \[lq]0\[rq],
7298 the top of the page.
7299 .
7300 An existing
7301 .I visible
7302 trap
7303 (see below)
7304 at the same location is removed;
7305 this is
7306 .BR .wh 's
7307 sole function if its second argument is missing.
7308 .
7309 .
7310 .P
7311 A trap is sprung only if it is
7312 .I visible,
7313 meaning that its location is reachable on the page and it is not hidden
7314 by another trap at the same location already planted there.
7315 .
7316 (A trap planted at \[lq]20i\[rq] or \[lq]\-30i\[rq] will not be sprung
7317 on a page of length \[lq]11i\[rq].)
7318 .
7319 .
7320 .P
7321 A trap above the top or at or below the bottom of the page can be made
7322 visible by either moving it into the page area or increasing the page
7323 length so that the trap is on the page.
7324 .
7325 Negative trap values always use the
7326 .I current
7327 page length;
7328 they are not converted to an absolute vertical position.
7329 .
7330 Use
7331 .B .ptr
7332 to dump page location traps to the standard error stream;
7333 their positions are reported in basic units.
7334 .
7335 .
7336 .br
7337 .ne 6v
7338 .\" ====================================================================
7339 .SS "The implicit page trap"
7340 .\" ====================================================================
7341 .
7342 An
7343 .I implicit page trap
7344 always exists in the top-level diversion;
7345 it works like a trap in some ways but not others.
7346 .
7347 Its purpose is to eject the current page and start the next one.
7348 .
7349 It has no name,
7350 so it cannot be moved or deleted with
7351 .B wh
7352 or
7353 .B ch
7354 requests.
7355 .
7356 You cannot hide it by placing another trap at its location,
7357 and can move it only by redefining the page length with
7358 .BR .pl .
7359 .
7360 Its operation is suppressed when vertical page traps are disabled with
7361 the
7362 .B vpt
7363 request.
7364 .
7365 .
7366 .\" ====================================================================
7367 .SH Diversions
7368 .\" ====================================================================
7369 .
7370 .\" BEGIN Keep (roughly) parallel with groff.texi node "Diversions".
7371 In
7372 .I roff
7373 systems it is possible to format text as if for output,
7374 but instead of writing it immediately,
7375 one can
7376 .I divert
7377 the formatted text into a named storage area.
7378 .
7379 It is retrieved later by specifying its name after a control character.
7380 .
7381 The same name space is used for such
7382 .I diversions
7383 as for strings and macros;
7384 see section \[lq]Identifiers\[rq] above.
7385 .
7386 Such text is sometimes said to be \[lq]stored in a macro\[rq],
7387 but this coinage obscures the important distinction between macros and
7388 strings on one hand and diversions on the other;
7389 the former store
7390 .I unformatted
7391 input text,
7392 and the latter capture
7393 .I formatted
7394 output.
7395 .
7396 Diversions also do not interpret arguments.
7397 .
7398 Applications of diversions include \[lq]keeps\[rq]
7399 (preventing a page break from occurring at an inconvenient place by
7400 forcing a set of output lines to be set as a group),
7401 footnotes,
7402 tables of contents,
7403 and indices.
7404 .
7405 For orthogonality it is said that GNU
7406 .I troff \" GNU
7407 is in the
7408 .I top-level diversion
7409 if no diversion is active
7410 (that is,
7411 formatted output is being \[lq]diverted\[rq] immediately to the output
7412 device.
7413 .
7414 .
7415 .P
7416 Dereferencing an undefined diversion will create an empty one of that
7417 name and cause a warning in category
7418 .B mac
7419 to be emitted.
7420 (see section \[lq]Warnings\[rq] in
7421 .MR \%troff 1 ).
7422 .
7423 A diversion does not exist for the purpose of testing with the
7424 .B d
7425 conditional operator until its initial definition ends
7426 (see subsection \[lq]Conditional expressions\[rq] above).
7427 .\" The following requests are used to create and alter diversions.
7428 .\" END Keep (roughly) parallel with groff.texi node "Diversions".
7429 .
7430 .
7431 .P
7432 The
7433 .B di
7434 request creates a diversion,
7435 including any partially collected line.
7436 .
7437 .B da
7438 appends to a diversion,
7439 creating one if it does not already exist.
7440 .
7441 If the diversion's name already exists as an alias,
7442 the target of the alias is replaced or appended to;
7443 see section \[lq]Strings\[rq] above.
7444 .
7445 .B box
7446 and
7447 .B boxa
7448 works similarly,
7449 but ignore partially collected lines.
7450 .
7451 Call any of these macros again without an argument to end the diversion.
7452 .
7453 .
7454 .br
7455 .ne 2v
7456 .P
7457 Diversions can be nested.
7458 .
7459 The registers
7460 .BR .d ,
7461 .BR .z ,
7462 .BR dn ,
7463 and
7464 .B dl
7465 report information about the current
7466 (or last closed)
7467 diversion.
7468 .
7469 .B .h
7470 is meaningful in diversions,
7471 including the top level.
7472 .
7473 .
7474 .P
7475 The
7476 .B \[rs]!\%
7477 and
7478 .B \[rs]?\%
7479 escape sequences and
7480 .B output
7481 request escape from a diversion,
7482 the first two to the enclosing level and the last to the top level.
7483 .
7484 This facility is termed
7485 .IR "transparent embedding" .
7486 .
7487 .
7488 .P
7489 The
7490 .B asciify
7491 and
7492 .B unformat
7493 requests reprocess diversions.
7494 .\" XXX: That's a weak statement. What we need is a `for` request and
7495 .\" a new conditional operator that tests whether an item in a node list
7496 .\" is an (otherwise unrepresentable) node. See Savannah #62264.
7497 .
7498 .
7499 .\" ====================================================================
7500 .SH "Punning names"
7501 .\" ====================================================================
7502 .
7503 .\" BEGIN Keep (roughly) parallel with groff.texi node "Punning names".
7504 Macros,
7505 strings,
7506 and diversions share a name space;
7507 see section \[lq]Identifiers\[rq] above.
7508 .
7509 Internally,
7510 the same mechanism is used to store them.
7511 .
7512 You can thus call a macro with string interpolation syntax and vice
7513 versa.
7514 .
7515 Interpolating a string does not hide existing macro arguments.
7516 .
7517 The sequence
7518 .B \[rs]\[rs]
7519 can be placed at the end of a line in a macro definition or,
7520 within a macro definition,
7521 immediately after the interpolation of a macro as a string to suppress
7522 the effect of a newline.
7523 .\" END Keep (roughly) parallel with groff.texi node "Punning names".
7524 .
7525 .
7526 .\" ====================================================================
7527 .SH Environments
7528 .\" ====================================================================
7529 .
7530 .\" BEGIN Keep (roughly) parallel with groff.texi node "Environments".
7531 Environments store most of the parameters that control text processing.
7532 .
7533 A default environment named
7534 .RB \[lq] 0 \[rq]
7535 exists when
7536 .I \%troff
7537 starts up;
7538 it is modified by formatting-related requests and escape sequences.
7539 .
7540 .
7541 .P
7542 You can create new environments and switch among them.
7543 .
7544 Only one is current at any given time.
7545 .
7546 Active environments are managed using a
7547 .I stack,
7548 a data structure supporting \[lq]push\[rq] and \[lq]pop\[rq] operations.
7549 .
7550 The current environment is at the top of the stack.
7551 .
7552 The same environment name can be pushed onto the stack multiple times,
7553 possibly interleaved with others.
7554 .
7555 Popping the environment stack does not destroy the current environment;
7556 it remains accessible by name and can be made current again by pushing
7557 it at any time.
7558 .
7559 Environments cannot be renamed or deleted,
7560 and can only be modified when current.
7561 .
7562 To inspect the environment stack,
7563 use the
7564 .B pev
7565 request;
7566 see section \[lq]Debugging\[rq] below.
7567 .
7568 .
7569 .P
7570 Environments store the following information.
7571 .
7572 .
7573 .IP \[bu] 2n
7574 a partially collected line, if any
7575 .
7576 .
7577 .IP \[bu]
7578 data about the most recently output glyph and line
7579 (registers
7580 .BR .cdp ,
7581 .BR .cht ,
7582 .BR .csk ,
7583 .BR .n ,
7584 .BR .w )
7585 .
7586 .
7587 .IP \[bu]
7588 typeface parameters
7589 (size,
7590 family,
7591 style,
7592 height and slant,
7593 inter-word and inter-sentence space sizes)
7594 .
7595 .
7596 .IP \[bu]
7597 page parameters
7598 (line length,
7599 title length,
7600 vertical spacing,
7601 line spacing,
7602 indentation,
7603 line numbering,
7604 centering,
7605 right-alignment,
7606 underlining,
7607 hyphenation parameters)
7608 .
7609 .
7610 .IP \[bu]
7611 filling enablement;
7612 adjustment enablement and mode
7613 .
7614 .
7615 .IP \[bu]
7616 tab stops;
7617 tab,
7618 leader,
7619 escape,
7620 control,
7621 no-break control,
7622 hyphenation,
7623 and
7624 margin characters
7625 .
7626 .
7627 .IP \[bu]
7628 input line traps
7629 .
7630 .
7631 .IP \[bu]
7632 stroke and fill colors
7633 .
7634 .
7635 .P
7636 The
7637 .B ev
7638 request pushes to and pops from the environment stack,
7639 while
7640 .B evc
7641 copies a named environment's contents to the current one.
7642 .\" END Keep (roughly) parallel with groff.texi node "Environments".
7643 .
7644 .
7645 .\" ====================================================================
7646 .SH Underlining
7647 .\" ====================================================================
7648 .
7649 In
7650 .I RUNOFF
7651 (see
7652 .MR roff 7 ),
7653 underlining,
7654 even of lengthy passages,
7655 was straightforward because only fixed-pitch printing devices were
7656 targeted.
7657 .
7658 Typesetter output posed a greater challenge.
7659 .
7660 There exists a
7661 .I groff
7662 request
7663 .B .ul
7664 (see above)
7665 that underlines subsequent source lines on terminal devices,
7666 but on typesetters,
7667 it selects an italic font style instead.
7668 .
7669 .
7670 The
7671 .I ms
7672 macro package
7673 (see
7674 .MR groff_ms 7 )
7675 offers a macro
7676 .BR .UL ,
7677 but it too produces the desired effect only on typesetters,
7678 and has other limitations.
7679 .
7680 .
7681 .P
7682 One could adapt
7683 .IR ms 's
7684 approach to the construction of a macro as follows.
7685 .
7686 .RS
7687 .EX
7688 \&.de UNDERLINE
7689 \&. ie n \[rs]\[rs]$1\[rs]f[I]\[rs]\[rs]$2\[rs]f[P]\[rs]\[rs]$3
7690 \&. el \[rs]\[rs]$1\[rs]Z\[aq]\[rs]\[rs]$2\[aq]\[rs]v\[aq].25m\[aq]\
7691 \[rs]D\[aq]l \[rs]w\[aq]\[rs]\[rs]$2\[aq]u 0\[aq]\[rs]v\[aq]\-.25m\
7692 \[aq]\[rs]\[rs]$3
7693 \&..
7694 .EE
7695 .RE
7696 .
7697 If
7698 .MR doclifter 1
7699 makes trouble, change the macro name
7700 .B UNDERLINE
7701 into some 2-letter word, like
7702 .BR Ul .
7703 .
7704 Moreover,
7705 change the form of the font selection escape sequence from
7706 .B \[rs]f[P]
7707 to
7708 .BR \[rs]fP .
7709 .
7710 .
7711 .\" ====================================================================
7712 .SS "Underlining without macro definitions"
7713 .\" ====================================================================
7714 .
7715 If one does not want to use macro definitions,
7716 e.g.,
7717 when
7718 .I doclifter
7719 gets lost,
7720 use the following.
7721 .
7722 .RS
7723 .EX
7724 \&.ds u1 before
7725 \&.ds u2 in
7726 \&.ds u3 after
7727 \&.ie n \[rs]*[u1]\[rs]f[I]\[rs]*[u2]\[rs]f[P]\[rs]*[u3]
7728 \&.el \[rs]*[u1]\[rs]Z\[aq]\[rs]*[u2]\[aq]\[rs]v\[aq].25m\[aq]\[rs]D\
7729 \[aq]l \[rs]w\[aq]\[rs]*[u2]\[aq]u 0\[aq]\[rs]v\[aq]\-.25m\[aq]\[rs]*\
7730 [u3]
7731 .EE
7732 .RE
7733 .
7734 .ne 2v
7735 When using
7736 .IR doclifter ,
7737 it might be necessary to change syntax forms such as
7738 .B \e[xy]
7739 and
7740 .B \e*[xy]
7741 to those supported by AT&T
7742 .IR troff :
7743 .B \e*(xy
7744 and
7745 .BR \e(xy ,
7746 and so on.
7747 .
7748 .
7749 .P
7750 Then these lines could look like
7751 .RS
7752 .EX
7753 \&.ds u1 before
7754 \&.ds u2 in
7755 \&.ds u3 after
7756 \&.ie n \[rs]*[u1]\[rs]fI\[rs]*(u2\[rs]fP\[rs]*(u3
7757 \&.el \[rs]*(u1\[rs]Z\[aq]\[rs]*(u2\[aq]\[rs]v\[aq].25m\[aq]\[rs]D\
7758 \[aq]l \[rs]w\[aq]\[rs]*(u2\[aq]u 0\[aq]\[rs]v\[aq]\-.25m\[aq]\[rs]*(u3
7759 .EE
7760 .RE
7761 .
7762 .
7763 .P
7764 The result looks like
7765 .RS
7766 .ft CR
7767 before
7768 \z\[ul]i\
7769 \z\[ul]n
7770 after
7771 .ft R
7772 .RE
7773 .
7774 .
7775 .\" ====================================================================
7776 .SS "Underlining by overstriking with \e(ul"
7777 .\" ====================================================================
7778 .
7779 The
7780 .B \[rs]z
7781 escape sequence writes a glyph without advancing the
7782 drawing position,
7783 enabling overstriking.
7784 .
7785 Thus,
7786 .BI \[rs]z c \[rs](ul
7787 formats
7788 .I c
7789 with an underrule glyph on top of it.
7790 .
7791 Video terminals implement the underrule by setting a character cell's
7792 underline attribute,
7793 so this technique works in both
7794 .I nroff \" mode
7795 and
7796 .I troff \" mode
7797 modes.
7798 .
7799 .
7800 .P
7801 Long words may then look intimidating in the input;
7802 a clarifying approach might be to use the input line continuation escape
7803 sequence
7804 .BI \[rs] newline
7805 to place each underlined character on its own input line.
7806 .
7807 Thus,
7808 .
7809 .RS
7810 .EX
7811 \&.nf
7812 \[rs]&\[rs]fB: ${\[rs]fIvar\[rs]fR\[rs]c
7813 \[rs]zo\[rs](ul\[rs]
7814 \[rs]zp\[rs](ul\[rs]c
7815 \[rs]&\[rs]fIvalue\[rs]fB}
7816 \&.fi
7817 .EE
7818 .RE
7819 .
7820 produces
7821 .
7822 .RS
7823 .EX
7824 .BI ": ${" var \c
7825 \zo\(ul\
7826 \zp\(ul\c
7827 .IB value }
7828 .EE
7829 .RE
7830 .
7831 as output.
7832 .
7833 .
7834 .\" ====================================================================
7835 .SH "Compatibility mode"
7836 .\" ====================================================================
7837 .
7838 The differences between the
7839 .I roff
7840 language recognized by GNU
7841 .I troff \" GNU
7842 and that of AT&T
7843 .IR troff , \" AT&T
7844 as well as the device,
7845 font,
7846 and device-independent intermediate output formats described by
7847 CSTR\~#54 are documented in
7848 .MR groff_diff 7 .
7849 .
7850 .I groff
7851 provides an AT&T compatibility mode.
7852 .
7853 The
7854 .request .cp
7855 request and registers
7856 .B .C
7857 and
7858 .B .cp
7859 set and test the enablement of this mode.
7860 .
7861 .
7862 .\" ====================================================================
7863 .SH Debugging
7864 .\" ====================================================================
7865 .
7866 .\" BEGIN Keep (roughly) parallel with groff.texi node "Debugging".
7867 Preprocessors use the
7868 .B .lf
7869 request to preserve the identities of line numbers and names of input
7870 files.
7871 .
7872 .I groff
7873 emits a variety of error diagnostics and supports several categories of
7874 warning;
7875 the output of these can be selectively suppressed with
7876 .B .warn
7877 (and see the
7878 .BR \-E ,
7879 .BR \-w ,
7880 and
7881 .B \-W
7882 options of
7883 .MR \%troff 1 ).
7884 .
7885 A trace of the formatter's input processing stack can be emitted when
7886 errors or warnings occur by means of
7887 .MR \%troff 1 's
7888 .B \-b
7889 option,
7890 or produced on demand with the
7891 .request .backtrace
7892 request.
7893 .
7894 .BR .tm ,
7895 .BR .tmc ,
7896 and
7897 .B .tm1
7898 can be used to emit customized diagnostic messages or for
7899 instrumentation while troubleshooting.
7900 .
7901 .B .ex
7902 and
7903 .B .ab
7904 cause early termination with successful and error exit codes
7905 respectively,
7906 to halt further processing when continuing would be fruitless.
7907 .
7908 Examine the state of the formatter with requests that write lists of
7909 defined names\[em]macros,
7910 strings,
7911 and
7912 .RB diversions\[em]( .pm );
7913 environments
7914 .RB ( .pev ),
7915 registers
7916 .RB ( .pnr ),
7917 and page location traps
7918 .RB ( .ptr )
7919 to the standard error stream.
7920 .\" END Keep (roughly) parallel with groff.texi node "Debugging".
7921 .
7922 .
7923 .\" ====================================================================
7924 .SH Authors
7925 .\" ====================================================================
7926 .
7927 This document was written by
7928 by Trent A.\& Fisher,
7929 Werner Lemberg,
7930 and
7931 .MT g.branden\:.robinson@\:gmail\:.com
7932 G.\& Branden Robinson
7933 .ME .
7934 .
7935 Section \[lq]Underlining\[rq] was primarily written by
7936 .MT groff\-bernd\:.warken\-72@\:web\:.de
7937 Bernd Warken
7938 .ME .
7939 .
7940 .
7941 .\" ====================================================================
7942 .SH "See also"
7943 .\" ====================================================================
7944 .
7945 .ne 2v
7946 .IR "Groff: The GNU Implementation of troff" ,
7947 by Trent A.\& Fisher and Werner Lemberg,
7948 is the primary
7949 .I groff
7950 manual.
7951 .
7952 You can browse it interactively with \[lq]info groff\[rq].
7953 .
7954 .
7955 .br
7956 .ne 4v
7957 .P
7958 \[lq]Troff User's Manual\[rq]
7959 by Joseph F.\& Ossanna,
7960 1976
7961 (revised by Brian W.\& Kernighan,
7962 1992),
7963 AT&T Bell Laboratories Computing Science Technical Report No.\& 54,
7964 widely called simply \[lq]CSTR\~#54\[rq],
7965 documents the language,
7966 device and font description file formats,
7967 and device-independent output format
7968 referred to collectively in
7969 .I groff
7970 documentation as
7971 .RI \[lq]AT&T\~ troff \[rq].
7972 .
7973 .
7974 .br
7975 .ne 3v
7976 .P
7977 \[lq]A Typesetter-independent TROFF\[rq]
7978 by Brian W.\& Kernighan,
7979 1982,
7980 AT&T Bell Laboratories Computing Science Technical Report No.\& 97
7981 (CSTR\~#97),
7982 provides additional insights into the
7983 device and font description file formats
7984 and device-independent output format.
7985 .
7986 .
7987 .TP
7988 .MR groff 1
7989 is the preferred interface to the
7990 .I groff
7991 system;
7992 it manages the pipeline that carries a source document through
7993 preprocessors,
7994 the
7995 .I \%troff
7996 formatter,
7997 and an output driver to viewable or printable form.
7998 .
7999 It also exhaustively lists the man pages provided with the GNU
8000 .I roff
8001 system.
8002 .
8003 .
8004 .TP
8005 .MR groff_char 7
8006 discusses character encoding issues,
8007 escape sequences that produce glyphs,
8008 and enumerates
8009 .IR groff 's
8010 predefined special character escape sequences.
8011 .
8012 .
8013 .TP
8014 .MR groff_diff 7
8015 covers differences between the
8016 GNU
8017 .I troff \" GNU
8018 formatter,
8019 its device and font description file formats,
8020 its device-independent output format,
8021 and those of AT&T
8022 .IR troff ,\" AT&T
8023 whose design it reimplements.
8024 .
8025 .
8026 .TP
8027 .MR groff_font 5
8028 describes the formats of the files that describe devices
8029 .RI ( DESC )
8030 and fonts.
8031 .
8032 .
8033 .TP
8034 .MR groff_tmac 5
8035 surveys macro packages provided with
8036 .IR groff ,
8037 describes how documents can take advantage of them,
8038 offers guidance on writing macro packages and using diversions,
8039 and includes historical information on macro package naming conventions.
8040 .
8041 .
8042 .TP
8043 .MR roff 7
8044 presents a detailed history of
8045 .I roff
8046 systems and summarizes concepts common to them.
8047 .
8048 .
8049 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
8050 .cp \n[*groff_groff_7_man_C]
8051 .do rr *groff_groff_7_man_C
8052 .
8053 .
8054 .\" Local Variables:
8055 .\" fill-column: 72
8056 .\" mode: nroff
8057 .\" End:
8058 .\" vim: set filetype=groff textwidth=72: