Debian Codegraph @

upstream/debian-unstable/man7/groff.7

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