Debian Codegraph @

upstream/fedora-44/man7/groff.7

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