Debian Codegraph @

upstream/debian-unstable/man7/groff_diff.7

raw
1 '\" e
2 .TH groff_diff 7 "2026-04-22" "groff 1.24.1"
3 .SH Name
4 groff_diff \- differences between GNU
5 .I roff
6 and AT&T
7 .I troff
8 .
9 .
10 .\" ====================================================================
11 .\" Legal Terms
12 .\" ====================================================================
13 .\"
14 .\" Copyright 1989-2024 Free Software Foundation, Inc.
15 .\" 2019-2025 G. Branden Robinson
16 .\"
17 .\" This file is part of groff, the GNU roff typesetting system.
18 .\"
19 .\" Permission is granted to copy, distribute and/or modify this
20 .\" document under the terms of the GNU Free Documentation License,
21 .\" Version 1.3 or any later version published by the Free Software
22 .\" Foundation; with no Invariant Sections, with no Front-Cover Texts,
23 .\" and with no Back-Cover Texts.
24 .\"
25 .\" A copy of the Free Documentation License is included as a file
26 .\" called FDL in the main directory of the groff source package.
27 .\"
28 .\" A copy of the GNU Free Documentation License is also available in this
29 .\" Debian package as /usr/share/doc/groff/copyright.
30 .
31 .
32 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
33 .do nr *groff_groff_diff_7_man_C \n[.cp]
34 .cp 0
35 .
36 .\" Define fallback for groff 1.23's MR macro if the system lacks it.
37 .nr do-fallback 0
38 .if !\n(.f .nr do-fallback 1 \" mandoc
39 .if \n(.g .if !d MR .nr do-fallback 1 \" older groff
40 .if !\n(.g .nr do-fallback 1 \" non-groff *roff
41 .if \n[do-fallback] \{\
42 . de MR
43 . ie \\n(.$=1 \
44 . I \%\\$1
45 . el \
46 . IR \%\\$1 (\\$2)\\$3
47 . .
48 .\}
49 .rr do-fallback
50 .
51 .
52 .\" ====================================================================
53 .\" Local definitions
54 .\" ====================================================================
55 .
56 .\" define a string tx for the TeX logo
57 .ie t .ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
58 .el .ds tx TeX
59 .
60 .
61 .\" from old groff_out.man
62 .ie \n(.g \
63 . ds ic \/
64 .el \
65 . ds ic \^
66 .
67 .
68 .\" ====================================================================
69 .SH Description
70 .\" ====================================================================
71 .
72 The GNU
73 .I roff
74 text processing system,
75 .IR groff ,
76 is a reimplementation and extension of AT&T
77 .IR troff , \" AT&T
78 the typesetting system originating in Unix systems of the 1970s.
79 .
80 .I groff
81 removes many arbitrary limitations and adds features,
82 both to the input language and to the page description language output
83 by the
84 .I troff \" generic
85 formatter.
86 .
87 We also note here differences arising from
88 .IR groff 's
89 implementation of AT&T
90 .I troff \" AT&T
91 features.
92 .
93 The following discussion assumes familiarity with those features;
94 see
95 .MR roff 7
96 for background.
97 .
98 GNU
99 .I troff \" GNU
100 can operate in a manner that increases support
101 for documents written for AT&T
102 .IR troff ; \" AT&T
103 see section \[lq]Compatibility mode\[rq] below.
104 .
105 .
106 .\" ====================================================================
107 .SH Language
108 .\" ====================================================================
109 .
110 GNU
111 .I troff \" GNU
112 features identifiers of arbitrary length;
113 supports color output,
114 non-integral type sizes,
115 user-defined characters,
116 and automatic hyphenation in languages other than English;
117 adds more conditional expression operators;
118 recognizes additional scaling units and arithmetic operators;
119 enables general file I/O
120 (in \[lq]unsafe mode\[rq] only);
121 and exposes more formatter state.
122 .
123 .
124 .\" ====================================================================
125 .SS "Long names"
126 .\" ====================================================================
127 .
128 GNU
129 .I troff \" GNU
130 introduces many new requests;
131 with three exceptions
132 .RB ( cp ,
133 .BR do ,
134 .BR rj ),
135 they have names longer than two characters.
136 .
137 The names of registers,
138 fonts,
139 strings/\:macros/\:diversions,
140 environments,
141 special characters,
142 character classes,
143 streams,
144 hyphenation language codes,
145 and colors can be of any length.
146 .
147 Anywhere AT&T
148 .I troff \" AT&T
149 supports a parameterized escape sequence that uses an opening
150 parenthesis \[lq](\[rq] to introduce a two-character argument,
151 .I groff
152 supports a square-bracketed form \[lq][]\[rq] where the argument
153 within can be of arbitrary length.
154 .
155 .
156 .\" ====================================================================
157 .SS "Font families, abstract styles, and translation"
158 .\" ====================================================================
159 .
160 GNU
161 .I troff \" GNU
162 can group text typefaces into
163 .I families.
164 For example,
165 .I groff
166 ships with support for families containing each of the styles
167 .RB \[lq] R \[rq],
168 .RB \[lq] I \[rq],
169 .RB \[lq] B \[rq],
170 and
171 .RB \[lq] BI \[rq]
172 (roman [upright],
173 bold,
174 italic [slanted],
175 and bold-italic).
176 .
177 So that a document need not be coupled to a specific font family,
178 an output device can associate a style in the abstract sense with a
179 mounting position.
180 .
181 Thus the default family can combine with a style dynamically,
182 producing a
183 .I "resolved font name."
184 .
185 A document can
186 .I translate,
187 or remap,
188 font names with the
189 .B ftr
190 request.
191 .
192 .
193 .P
194 .\" BEGIN Keep parallel with node "Font Families" in our Texinfo manual.
195 Applying the requests
196 .BR cs ,
197 .BR bd ,
198 .BR tkf ,
199 .BR uf ,
200 or
201 .B \%fspecial
202 to an abstract style affects the member of the default family
203 corresponding to that style.
204 .\" END Keep parallel with node "Font Families" in our Texinfo manual.
205 .
206 The default family can be set with the
207 .B fam
208 request or
209 .B \-f
210 command-line option.
211 .
212 The
213 .B styles
214 directive in the output device's
215 .I DESC
216 file controls which mounting positions
217 (if any)
218 are initially associated with abstract styles rather than fonts,
219 and the
220 .B sty
221 request can update this association.
222 .
223 .
224 .\" ====================================================================
225 .SS Colors
226 .\" ====================================================================
227 .
228 .I groff
229 supports color output with a variety of color spaces and up to 16 bits
230 per channel.
231 .
232 Some devices,
233 particularly terminals,
234 may be more limited.
235 .
236 When color support is enabled,
237 two colors are current at any given time:
238 the
239 .I stroke color,
240 with which glyphs,
241 rules (lines),
242 and geometric figures are drawn,
243 and the
244 .I fill color,
245 which paints the interior of filled geometric figures.
246 .
247 The
248 .BR color ,
249 .BR \%defcolor ,
250 .BR gcolor ,
251 and
252 .B fcolor
253 requests;
254 .B \[rs]m
255 and
256 .B \[rs]M
257 escape sequences;
258 and
259 .BR .color ,
260 .BR .m ,
261 and
262 .B .M
263 registers exercise color support.
264 .
265 .
266 .\" ====================================================================
267 .SS Hyphenation
268 .\" ====================================================================
269 .
270 GNU
271 .I troff \" GNU
272 uses a hyphenation algorithm and language-specific pattern files
273 (based on \*[tx]'s)
274 to decide which words can be hyphenated and where.
275 .
276 AT&T
277 .IR troff 's \" AT&T
278 hyphenation system (\[lq]suftab\[rq]) was specific to English.
279 .
280 .
281 .P
282 New requests permit finer control over hyphenation breaking;
283 hyphenation of a word might be suppressed due to a limit on consecutive
284 hyphenated lines
285 .RB ( hlm ),
286 a minimum line length threshold
287 .RB ( hym ),
288 or because the line can instead be adjusted with additional inter-word
289 space
290 .RB ( hys ).
291 .
292 The
293 .B hla
294 request selects a hyphenation language,
295 whereas
296 .B hpf
297 and
298 .B hpfa
299 respectively
300 load and append to the language's hyphenation patterns.
301 .
302 If no hyphenation language is set or no patterns are loaded,
303 GNU
304 .I troff \" GNU
305 does not perform automatic hyphenation.
306 .
307 .
308 .\" BEGIN Keep (roughly) parallel with groff.texi node "Manipulating
309 .\" Hyphenation".
310 .P
311 For automatic hyphenation to work,
312 the formatter must know which letters are equivalent.
313 .
314 For example,
315 the letter \[lq]E\[rq] behaves like \[lq]e\[rq];
316 only the latter typically appears in hyphenation pattern files.
317 .
318 GNU
319 .I troff \" GNU
320 expects characters
321 that participate in automatic hyphenation
322 to be assigned
323 .I "hyphenation codes"
324 that define these equivalence classes.
325 .
326 At startup,
327 GNU
328 .I troff \" GNU
329 assigns hyphenation codes to the letters \[lq]a\[rq]\[en]\[lq]z\[rq],
330 applies the same codes to \[lq]A\[rq]\[en]\[lq]Z\[rq]
331 in one-to-one correspondence,
332 and assigns a code of zero to all other characters.
333 .
334 .
335 .br
336 .ne 2v
337 .P
338 The
339 .B hcode
340 request enables application of hyphenation codes
341 to characters outside the Unicode basic Latin set;
342 without doing so,
343 words containing such letters
344 won't hyphenate properly
345 even if the corresponding hyphenation patterns contain them.
346 .
347 Localization files for the input character set and language
348 configure hyphenation codes;
349 see
350 .MR groff_tmac 5 .
351 .\" END Keep (roughly) parallel with groff.texi node "Manipulating
352 .\" Hyphenation".
353 .
354 .
355 .P
356 GNU
357 .IR troff 's \" GNU
358 .B \[rs]:
359 escape sequence works like
360 .B \[rs]%
361 but produces no hyphen if the word breaks at that location.
362 .
363 .
364 .\" ====================================================================
365 .SS "Fractional type sizes and new scaling units"
366 .\" ====================================================================
367 .
368 .\" BEGIN Keep (roughly) parallel with groff.texi node "Using Fractional
369 .\" Type Sizes".
370 When configuring the type size,
371 AT&T
372 .I troff \" AT&T
373 ignored scaling units and interpreted all measurements in points.
374 Combined with integer arithmetic,
375 this design choice made it impossible to support,
376 for instance,
377 ten-and-a-half-point type.
378 .
379 In GNU
380 .I troff \" GNU
381 an output device can select a scaling factor
382 that subdivides a point into \[lq]scaled points\[rq].
383 A type size expressed in scaled points
384 can thus represent a non-integral size in points.
385 .
386 .
387 .P
388 A
389 .I "scaled point,"
390 scaling unit
391 .BR s ,
392 is equal to
393 .RI 1/ sizescale
394 points,
395 where the device description file,
396 .IR DESC ,
397 specifies
398 .I sizescale
399 and otherwise defaults to\~1;
400 see
401 .MR groff_font 5 .
402 .
403 GNU
404 .I troff \" GNU
405 also defines the
406 .I "typographical point,"
407 scaling unit
408 .BR z ,
409 which explicitly specifies a type size of potentially
410 non-integral measure.
411 The program multiplies typographical points by
412 .I sizescale
413 and converts the value to an integer.
414 .
415 Arguments GNU
416 .I troff \" GNU
417 interprets in
418 .B z
419 units by default comprise those to the escape sequences
420 .B \[rs]H
421 and
422 .BR \[rs]s ,
423 .\" Legacy forms of the `\s` escape sequence don't accept numerical
424 .\" expressions--only integers.
425 to the request
426 .BR ps ,
427 the third argument to the
428 .B cs
429 request,
430 and the second and fourth arguments to the
431 .B tkf
432 request.
433 .
434 In GNU
435 .IR troff , \" GNU
436 the register
437 .B \[rs]n[.s]
438 interpolates the type size in typographical points
439 .RB ( z ),
440 whereas the register
441 .B \[rs]n[.ps]
442 interpolates it in scaled points
443 .RB ( s ).
444 .
445 .RB \[lq] \[rs]n[.ps]s \[rq],
446 .RB \[lq] \[rs]n[.s]z \[rq],
447 and
448 .RB \[lq] 1m \[rq]
449 are co-equal by definition.
450 .
451 .
452 .P
453 For example,
454 if
455 .I sizescale
456 is\~1000,
457 then a scaled point is one thousandth of a point.
458 .
459 Consequently,
460 .RB \[lq] ".ps 10.5" \[rq]
461 is synonymous with
462 .RB \[lq] ".ps 10.5z" \[rq];
463 both set the type size to 10,500\~scaled points
464 or 10.5\~typographical points.
465 .
466 .
467 .P
468 It makes no sense to use the
469 .RB \[lq] z \[rq]\~scaling
470 unit in a numeric expression whose default scaling unit is neither
471 .RB \[lq] u \[rq]
472 .RB nor\~\[lq] z \[rq],
473 so GNU
474 .I troff \" GNU
475 disallows this.
476 .
477 Similarly,
478 it is nonsensical to use scaling units other than
479 .RB \[lq] p \[rq],
480 .RB \[lq] s \[rq],
481 .RB \[lq] z \[rq],
482 or
483 .RB \[lq] u \[rq],
484 in a numeric expression whose default scaling unit
485 .RB is\~\[lq] z \[rq],
486 and so GNU
487 .I troff \" GNU
488 disallows those as well.
489 .
490 .
491 .br
492 .ne 2v
493 .P
494 Output devices may be limited in the type sizes they can employ.
495 .
496 The
497 .B .s
498 and
499 .B .ps
500 registers represent the type size selected by the formatter
501 as it understands a device's capability.
502 .
503 the read-only registers
504 .B .psr
505 and
506 (string-valued)
507 .B .sr
508 interpolate the last
509 .I requested
510 in scaled points
511 and in points as a decimal fraction,
512 respectively.
513 .
514 Like the actual current and previous type size,
515 the requested ones are properties of an environment.
516 .
517 .
518 .P
519 For example,
520 if a document requests a type size of 10.95\~points,
521 and the nearest size permitted by a
522 .B sizes
523 request
524 (or by the
525 .B sizes
526 or
527 .B \%sizescale
528 directives in the device's
529 .I DESC
530 file)
531 is 11\~points,
532 .I groff
533 uses the latter value.
534 .\" END Keep (roughly) parallel with groff.texi node "Using Fractional
535 .\" Type Sizes".
536 .
537 .
538 .P
539 A further two new measurement units available in
540 .I groff
541 are
542 .RB \[lq] M \[rq],
543 which indicates hundredths of an em,
544 and
545 .RB \[lq] f \^\[rq],
546 which multiplies by 65,536.
547 .
548 The latter provides convenient fractions for color definitions with the
549 .B \%defcolor
550 request.
551 .
552 For example,
553 0.5f equals 32768u.
554 .
555 .
556 .\" ====================================================================
557 .SS "Special fonts"
558 .\" ====================================================================
559 .
560 .\" BEGIN Keep (roughly) parallel with groff.texi node "Special Fonts".
561 .\" (the second paragraph thereof; the first covers "portable" concepts)
562 GNU
563 .IR troff 's \" GNU
564 .RB \%\[lq] special \[rq]
565 and
566 .B \%fspecial
567 requests permit a document
568 to supplement the set of fonts the device configures
569 for glyph search
570 without having to use
571 the
572 .B fp
573 request to manipulate the list of mounting positions,
574 which can be tedious\[em]by default,
575 GNU
576 .I troff \" GNU
577 mounts 40 fonts at startup
578 when using the
579 .B ps
580 device.
581 .\" END Keep (roughly) parallel with groff.texi node "Special Fonts".
582 .
583 .
584 .\" ====================================================================
585 .SS "Numeric expressions"
586 .\" ====================================================================
587 .
588 GNU
589 .I troff \" GNU
590 permits spaces in a numeric expression within parentheses,
591 and offers three new operators.
592 .
593 .
594 .TP 8n \" "e1>?e2" +2n
595 .IB e1 >? e2
596 Interpolate the greater of expressions
597 .I e1
598 and
599 .IR e2 .
600 .
601 .
602 .TP
603 .IB e1 <? e2
604 Interpolate the lesser of expressions
605 .I e1
606 and
607 .IR e2 .
608 .
609 .
610 .TP
611 .BI ( c ; e )
612 Interpolate expression
613 .I e
614 using
615 .I c
616 as the default scaling unit,
617 ignoring scaling units in
618 .I e
619 if
620 .I c
621 is empty.
622 .
623 .
624 .P
625 Arithmetic in GNU
626 .I troff \" troff
627 saturates instead of wrapping.
628 .
629 .
630 .\" ====================================================================
631 .SS "Conditional expressions"
632 .\" ====================================================================
633 .
634 More conditions can be tested with the
635 .RB \[lq]\| if \|\[rq]
636 and
637 .B ie
638 requests,
639 as well as the new
640 .RB \[lq] while \[rq]
641 request.
642 .
643 .
644 .TP
645 .BI c\~ chr
646 True if a character
647 .I chr
648 is available;
649 .I chr
650 is an
651 ordinary,
652 special,
653 or
654 indexed
655 character,
656 whether defined by a font description file or a request.
657 .
658 .
659 .TP
660 .BI d\~ nam
661 True if a string,
662 macro,
663 diversion,
664 or request
665 .I nam
666 is defined.
667 .
668 .
669 .TP
670 .BI F\~ fnt
671 True if a font
672 .I fnt
673 is available;
674 .I fnt
675 can be an abstract style
676 or a font name.
677 .
678 .I fnt
679 is handled as if it were an argument to the
680 .B ft
681 request
682 (that is,
683 the default family is combined with an abstract style and font
684 translation is applied),
685 but
686 .I fnt
687 cannot be a mounting position,
688 and no font is mounted.
689 .
690 .
691 .TP
692 .BI m\~ col
693 True if a color
694 .I col
695 is defined.
696 .
697 .
698 .TP
699 .BI r\~ reg
700 True if a register
701 .I reg
702 is defined.
703 .
704 .
705 .TP
706 .BI S\~ sty
707 True if an abstract style
708 .I sty
709 is registered.
710 .
711 Font translations apply.
712 .
713 .
714 .TP
715 .B v
716 Always false.
717 .
718 This condition exists for compatibility with certain other
719 .I troff
720 implementations.
721 .
722 (We refer to
723 .IR vtroff ,
724 a translator that converted the C/A/T command stream
725 produced by early-vintage AT&T
726 .I troff \" AT&T
727 to a form suitable for Versatec and Benson-Varian plotters.)
728 .
729 .
730 .br
731 .ne 6v
732 .\" ====================================================================
733 .SS "Drawing commands"
734 .\" ====================================================================
735 .
736 GNU
737 .I troff \" GNU
738 extends the
739 .B \[rs]D
740 escape sequence
741 with drawing commands to create filled
742 circles and ellipses,
743 and polygons.
744 .\" CSTR #54 did not countenance polygons, but DWB 3.3 had outlined ones
745 .\" as \D'p' as we do. Filled polygons appear to be a GNU innovation.
746 .
747 Stroked (outlined) objects are drawn with the stroke color and
748 filled (solid) ones shaded with the fill color.
749 .
750 These are independent properties;
751 if you want a filled,
752 stroked figure,
753 you must draw the same figure twice using each command.
754 .
755 A filled figure is smaller
756 than a stroked one using the same parameters
757 because the former is drawn only within its defined area,
758 whereas strokes have a line thickness,
759 set with another new drawing command.
760 .
761 .
762 .\" ====================================================================
763 .SS "Notational conventions"
764 .\" ====================================================================
765 .
766 In the request and escape sequence descriptions below,
767 GNU
768 .I troff \" GNU
769 reads arguments named
770 .I character-sequence,
771 .I command,
772 .I contents,
773 .I file,
774 and
775 .I message
776 in copy mode
777 until the end of the input line.
778 .
779 A
780 .I character-sequence
781 comprises one or more ordinary,
782 special,
783 or indexed characters;
784 spaces;
785 or escape sequences that interpolate only these.
786 .\" XXX: or tabs, leaders, backspace, and delete characters
787 .
788 We name the remaining arguments for clarity;
789 they are also
790 .I character-sequences.
791 .
792 A neutral double quote
793 .RB \[oq] \[dq] \[cq] \" single quotes around double quote
794 can optionally prefix a
795 .I character-sequence;
796 the formatter discards one if present,
797 permitting initial embedded spaces in the argument.
798 .
799 .
800 .P
801 .I input
802 refers to arbitrary character sequences
803 (up to a newline or delimiter)
804 that
805 GNU
806 .I troff \" GNU
807 fully interprets,
808 in contrast to copy mode.
809 .
810 .
811 .\" ====================================================================
812 .SS "Escape sequences"
813 .\" ====================================================================
814 .
815 .\" TODO: Some of the synopses here and in "New requests" get pretty
816 .\" discursive. It would be better to lift the introduction of new
817 .\" concepts in groff programming to new subsections above. Examples
818 .\" include: string parameterization, user-definable characters,
819 .\" character properties (cflags), character classes; the hyphenation
820 .\" language, code, and pattern file system; file stream manipulation...
821 .\"
822 .\" _Maybe_ output suppression. It's a big enough concept, but only
823 .\" well understood by retired contributors, only used by the grohtml
824 .\" output driver (still beta after 20 years), and we have some Savannah
825 .\" tickets that point the way to radically simplifying its design,
826 .\" eliminating its need to groff before you groff.
827 .I groff
828 introduces several new escape sequences,
829 extends the syntax of the AT&T
830 .I troff \" AT&T
831 escape sequences
832 .BR \[rs]D ,
833 .BR \[rs]f ,
834 .BR \[rs]k ,
835 .BR \[rs]n ,
836 .BR \[rs]s ,
837 .BR \[rs]$ ,
838 and
839 .BR \[rs]* ,
840 and alters the behavior of
841 .BR \[rs]X .
842 .
843 The following list collates
844 escape sequences alphabetically at first,
845 and then by symbol roughly in Unicode code point order.
846 .\" Exceptions are made to group closely-related escape sequences in an
847 .\" order more agreeable to the development of a topic.
848 .
849 Neutral apostrophes
850 .B \[aq]
851 illustrate escape sequences with a user-selectable delimiter.
852 .
853 Many others are available;
854 see subsection \[lq]Miscellaneous\[rq]
855 and section \[lq]Compatibility Mode\[rq] below.
856 .
857 .
858 .TP 10n \" "\D'E h v'" + 2n + hand-tuned for PDF
859 .BI \[rs]A\[aq] input \[aq]
860 Interpolate 1 if
861 .I input
862 is a valid identifier,
863 and\~0 otherwise.
864 .
865 Because GNU
866 .I troff \" GNU
867 ignores any input character with an invalid code when reading it,
868 invalid identifiers are empty or contain spaces,
869 tabs,
870 newlines,
871 or escape sequences that interpolate something other than a sequence of
872 ordinary characters.
873 .
874 You can employ
875 .B \[rs]A
876 to validate a macro argument before using it to construct another escape
877 sequence or identifier.
878 .
879 .TP
880 .BI \[rs]B\[aq] input \[aq]
881 Interpolate 1 if
882 .I input
883 is a valid numeric expression,
884 and\~0 otherwise.
885 .
886 You might use
887 .B \[rs]B
888 along with the
889 .RB \[lq]\| if \|\[rq]
890 request to filter out invalid macro arguments.
891 .
892 .
893 .TP
894 .BI \[rs]D\[aq]C\~ "d" \[aq]
895 Draw filled circle of diameter
896 .I d
897 with its leftmost point at the drawing position.
898 .
899 .
900 .TP
901 .BI \[rs]D\[aq]E\~ "h v" \[aq]
902 Draw filled ellipse of axis lengths
903 .I h
904 and
905 .IR v ,
906 with its leftmost point at the drawing position.
907 .
908 .
909 .TP
910 .BI \[rs]D\[aq]p\~ "h1 v1"\~\c
911 .RI .\|.\|.\~ "hn vn"\c
912 .B \[aq]
913 Draw polygon with vertices at the drawing position
914 and each point in sequence.
915 .
916 GNU
917 .I troff \" GNU
918 closes the polygon by drawing a line from
919 .RI ( hn ,\~ vn )
920 back to the initial drawing position;
921 DWB and Heirloom
922 .IR troff s \" DWB, Heirloom
923 do not.
924 .
925 .\" XXX: This would be the "STUPID_DRAWING_POSITIONING" complained of in
926 .\" src/libs/libdriver/input.cpp. It is neither the rightmost point
927 .\" of the figure nor the initial drawing position that GNU troff
928 .\" automatically returned to close the figure.
929 Afterward,
930 the drawing position is left at
931 .RI ( hn ,\~ vn ).
932 .
933 .
934 .TP
935 .BI \[rs]D\[aq]P\~ "h1 v1"\~\c
936 .RI .\|.\|.\~ "hn vn"\c
937 .B \[aq]
938 As
939 .BR \[rs]D\[aq]p\[aq] ,
940 but the polygon is filled.
941 .
942 .I groff
943 does not specify how the output device must fill concave or
944 self-intersecting polygons.
945 .
946 .
947 .TP
948 .BI \[rs]D\[aq]t\~ "n" \[aq]
949 Set line thickness of geometric objects
950 .RI to\~ n
951 basic units.
952 .
953 A zero
954 .I n
955 selects the minimum supported thickness.
956 .
957 A negative
958 .I n
959 (the default)
960 selects a thickness proportional to the type size.
961 .
962 .
963 .TP
964 .B \[rs]E
965 Embed an escape character that is not interpreted in copy mode
966 (compare with
967 .B \[rs]a
968 and
969 .BR \[rs]t ).
970 .
971 You can use it to ease the writing of nested macro definitions.
972 .
973 It is also convenient to define strings containing escape sequences that
974 need to work when used in copy mode
975 (for example,
976 as macro arguments),
977 or that will be interpolated at varying macro nesting depths.
978 .
979 .
980 .TP
981 .BI \[rs]f\^[ fnt ]
982 Select typeface
983 .IR fnt ,
984 which may be a mounting position,
985 abstract style,
986 or font name.
987 .
988 .BR \[rs]f\^[] ,
989 .BR \[rs]f\^[P] ,
990 and
991 .B \[rs]f\^P
992 are synonyms;
993 we recommend the first.
994 .
995 .
996 .br
997 .ne 4v
998 .TP
999 .BI \[rs]F f
1000 .TQ
1001 .BI \[rs]F( fm
1002 .TQ
1003 .BI \[rs]F[ fml ]
1004 Select default font family.
1005 .
1006 .B \[rs]F[]
1007 makes the previous font family the default.
1008 .
1009 .B \[rs]FP
1010 is unlike
1011 .BR \[rs]f\^P ;
1012 it selects font family \[lq]P\[rq] as the default.
1013 .
1014 See the
1015 .B fam
1016 request below.
1017 .
1018 .
1019 .br
1020 .ne 3v
1021 .TP
1022 .BI \[rs]k( rg
1023 .TQ
1024 .BI \[rs]k[ reg ]
1025 Store the horizontal drawing position,
1026 relative to that corresponding to the start of the input line
1027 (ignoring page offset and indentation),
1028 in two-character register
1029 .RI name\~ rg
1030 or arbitrary register
1031 .RI name\~ reg .
1032 .
1033 .
1034 .TP
1035 .BI \[rs]m c
1036 .TQ
1037 .BI \[rs]m( cl
1038 .TQ
1039 .BI \[rs]m[ col ]
1040 Set stroke color to
1041 .IR col .
1042 .
1043 .B \[rs]m[]
1044 restores the previous stroke color,
1045 or the default if there is none.
1046 .
1047 .
1048 .TP
1049 .BI \[rs]M c
1050 .TQ
1051 .BI \[rs]M( cl
1052 .TQ
1053 .BI \[rs]M[ col ]
1054 Set fill color to
1055 .IR col .
1056 .
1057 .B \[rs]M[]
1058 restores the previous fill color,
1059 or the default if there is none.
1060 .
1061 .
1062 .TP
1063 .BI \[rs]n[ reg ]
1064 Interpolate register
1065 .IR reg .
1066 .
1067 .
1068 .TP
1069 .BI \[rs]O n
1070 .TQ
1071 .BI \[rs]O[ n ]
1072 Suppress
1073 .I \%troff
1074 output of glyphs and geometric objects.
1075 .
1076 The sequences
1077 .BR \[rs]O2 ,
1078 .BR \[rs]O3 ,
1079 .BR \[rs]O4 ,
1080 and
1081 .B \[rs]O5
1082 are intended for internal use by
1083 .MR grohtml 1 .
1084 .
1085 .
1086 .RS
1087 .TP
1088 .B \[rs]O0
1089 .TQ
1090 .B \[rs]O1
1091 Disable and enable,
1092 respectively,
1093 the emission of glyphs and geometric objects to the output driver,
1094 provided that this sequence occurs at the outermost suppression level
1095 (see
1096 .B \[rs]O3
1097 and
1098 .BR \[rs]O4 ).
1099 .
1100 Horizontal motions corresponding to non-overstruck glyph widths still
1101 occur.
1102 .
1103 These sequences also reset the registers
1104 .BR opminx ,
1105 .BR opminy ,
1106 .BR opmaxx ,
1107 and
1108 .B opmaxy
1109 to\~\-1.
1110 .
1111 These four registers mark the top left and bottom right hand corners of
1112 a box encompassing all written or drawn output.
1113 .
1114 .
1115 .TP
1116 .B \[rs]O2
1117 At the outermost suppression level,
1118 enable emission of glyphs and geometric objects,
1119 and write to the standard error stream the page number and values of the
1120 four aforementioned registers encompassing glyphs written since the last
1121 interpolation of a
1122 .B \[rs]O
1123 sequence,
1124 as well as the page offset,
1125 line length,
1126 image file name
1127 (if any),
1128 horizontal and vertical device motion quanta,
1129 and input file name.
1130 .
1131 Numeric values are in basic units.
1132 .
1133 .
1134 .TP
1135 .B \[rs]O3
1136 .TQ
1137 .B \[rs]O4
1138 Begin and end a nested suppression level,
1139 respectively.
1140 .
1141 .I \%grohtml
1142 uses this mechanism to create images of output preprocessed with
1143 .IR \%pic ,
1144 .IR \%eqn ,
1145 and
1146 .IR \%tbl .
1147 .
1148 At startup,
1149 .I \%troff
1150 is at the outermost suppression level.
1151 .
1152 .I \%pre\-grohtml
1153 generates these sequences when processing the document,
1154 using
1155 .I \%troff
1156 with the
1157 .B ps
1158 output device,
1159 Ghostscript,
1160 and the PNM tools to produce images in PNG format.
1161 .
1162 These sequences start a new page if the device is not
1163 .B html
1164 or
1165 .BR xhtml ,
1166 to reduce the number of images crossing a page boundary.
1167 .
1168 .
1169 .TP
1170 .BI \[rs]O5[ Pfile ]
1171 At the outermost suppression level,
1172 write the name
1173 .I file
1174 to the standard error stream at position
1175 .IR P ,
1176 which must be one of
1177 .BR l ,
1178 .BR r ,
1179 .BR c ,
1180 or
1181 .BR i ,
1182 corresponding to
1183 left,
1184 right,
1185 centered,
1186 and inline alignments within the document,
1187 respectively.
1188 .
1189 .I file
1190 is a name associated with the production of the next image.
1191 .RE
1192 .
1193 .
1194 .TP
1195 .BI \[rs]R\[aq] name\~\[+-]n \[aq]
1196 Synonymous with
1197 .RB \[lq] .nr
1198 .IR name\~\[+-]n \[rq].
1199 .
1200 .TP
1201 .B \[rs]s[0]
1202 .TQ
1203 .B \[rs]s\[aq]0\[aq]
1204 Restore the previous type size;
1205 no operation if there is none.
1206 .
1207 .TP
1208 .BI \[rs]s[ \[+-]n ]
1209 .TQ
1210 .BI \[rs]s \[+-] [ n ]
1211 .TQ
1212 .BI \[rs]s\[aq] \[+-]n \[aq]
1213 .TQ
1214 .BI \[rs]s \[+-] \[aq] n \[aq]
1215 Set the type size to,
1216 or increment or decrement it by,
1217 .IR n \~typographical
1218 points.
1219 .
1220 .
1221 .br
1222 .ne 5v
1223 .TP
1224 .BI \[rs]V e
1225 .TQ
1226 .BI \[rs]V( ev
1227 .TQ
1228 .BI \[rs]V[ env ]
1229 Interpolate contents of the system environment variable
1230 .I env
1231 (one-character
1232 .RI name\~ e ,
1233 two-character
1234 .RI name\~ ev)
1235 as returned by
1236 .MR getenv 3 .
1237 .
1238 .B \[rs]V
1239 is interpreted even in copy mode.
1240 .
1241 .
1242 .\" TODO: When we get this giant headache generalized and adapted to the
1243 .\" `device` request, move this discussion into a dedicated subsection
1244 .\" above.
1245 .TP
1246 .BI \[rs]X\[aq] character-sequence \[aq]
1247 Unlike AT&T
1248 .IR troff , \" AT&T
1249 GNU
1250 .I troff \"
1251 performs some limited processing of the sequence of ordinary characters,
1252 special characters,
1253 and spaces in
1254 .IR character-sequence .
1255 .
1256 .
1257 .\" XXX: Force paragraph spacing here. I know--it's terrible. And
1258 .\" unnecessary once we get this giant discussion moved to its own
1259 .\" (sub)section.
1260 .sp \n[PD]u
1261 .\"IP
1262 The formatter's special character repertoire is unknown
1263 to output drivers outside of glyphs named in a device's fonts,
1264 and even then they may not possess complete coverage of the names
1265 documented in
1266 .MR groff_char 7 .
1267 .
1268 Further,
1269 escape sequences that produce horizontal or vertical motions,
1270 hyphenation breaks,
1271 or that are dummy characters may appear in strings
1272 or be converted to nodes,
1273 particularly in diversions. \" (@pxref{GNU troff Internals})
1274 .
1275 When they occur in a device extension command,
1276 they produce warnings in category
1277 .RB \[lq] char \[rq].
1278 .
1279 These are not representable when interpolated directly into
1280 device-independent output,
1281 as might be done when writing out tag names for PDF bookmarks,
1282 which can appear in a viewer's navigation pane.
1283 .
1284 This is also the case for a small number of special characters,
1285 such as
1286 .BR \[rs][ru] ,
1287 the baseline rule,
1288 that lack a Unicode definition.
1289 .
1290 .
1291 .sp \n[PD]u
1292 .\"IP
1293 So that any Unicode code point can be represented in device extension
1294 commands,
1295 for example in an author's name in document metadata
1296 or as a usefully named bookmark or hyperlink anchor,
1297 GNU
1298 .I troff \" GNU
1299 transforms its argument to represent characters
1300 outside the Unicode Basic Latin range
1301 as Unicode code points expressed in
1302 .IR groff 's
1303 notation for these,
1304 \[lq]\|\c
1305 .BI \[rs][u XXXX ]\c
1306 \|\[rq];
1307 see
1308 .MR groff_char 7 .
1309 .
1310 For these transformations,
1311 the formatter ignores character translations and definitions.
1312 .
1313 .
1314 .sp \n[PD]u
1315 .\"IP
1316 GNU
1317 .I troff \" GNU
1318 converts several ordinary characters that typeset as non-basic Latin
1319 code points to code points outside that range so that they are used
1320 consistently whether they are formatted as glyphs or used in a device
1321 extension command argument.
1322 .
1323 These ordinary characters are
1324 .RB \[lq]\| \[aq] \|\[rq],
1325 .RB \[lq]\| \- \|\[rq],
1326 .RB \[lq]\| \[ha] \|\[rq],
1327 .RB \[lq]\| \[ga] \|\[rq],
1328 and
1329 .RB \[lq]\| \[ti] \|\[rq];
1330 others are written as-is.
1331 .
1332 Thus,
1333 .RB \[lq]\| \[aq] \|\[rq]
1334 transforms to
1335 .RB \[lq]\| \[rs][u2019] \|\[rq].
1336 .
1337 .
1338 .sp \n[PD]u
1339 .\"IP
1340 Contrariwise,
1341 GNU
1342 .I troff \" GNU
1343 translates special characters that typeset
1344 as Unicode basic Latin characters
1345 to basic Latin characters accordingly.
1346 .
1347 Thus,
1348 .RB \[lq]\| \[rs][ga] \|\[rq]
1349 transforms to
1350 .RB \[lq]\| \[ga] \|\[rq],
1351 .RB \[lq]\| \[rs][Do] \|\[rq]
1352 to
1353 .RB \[lq]\| $ \|\[rq],
1354 and so on.
1355 .
1356 .
1357 .br
1358 .ne 5v
1359 .TP
1360 .BI \[rs]Y m
1361 .TQ
1362 .BI \[rs]Y( ma
1363 .TQ
1364 .BI \[rs]Y[ mac ]
1365 Interpolate a macro or string as a device extension command.
1366 .
1367 As
1368 .BI \[rs]X\[aq]\[rs]*[ mac ]\[aq]\c
1369 ,
1370 except that GNU
1371 .I troff \" GNU
1372 does not interpret the contents of
1373 .IR mac ;
1374 further,
1375 .I mac
1376 can be a macro and thus contain newlines,
1377 unlike the argument to
1378 .B \[rs]X .
1379 .
1380 This inclusion of newlines requires an extension to the AT&T
1381 .I troff \" AT&T
1382 device-independent page description language,
1383 and their presence confuses drivers that do not know about it
1384 (see subsection \[lq]Device control commands\[rq] of
1385 .MR groff_out 5 ).
1386 .
1387 .
1388 .TP
1389 .BI \[rs]Z\[aq] input \[aq]
1390 Save the drawing position,
1391 format
1392 .IR input ,
1393 then restore it.
1394 .
1395 GNU
1396 .I troff \" GNU
1397 ignores tabs and leaders in
1398 .I input
1399 with an error diagnostic.
1400 .
1401 .
1402 .TP
1403 .B \[rs]#
1404 Read everything up to and including the next newline in copy mode and
1405 discard it.
1406 .
1407 .B \[rs]#
1408 is like
1409 .BR \[rs]" ,
1410 except that
1411 .B \[rs]"
1412 does not ignore a newline;
1413 the latter therefore cannot be used by itself for a whole-line
1414 comment\[em]it leaves a blank line on the input stream.
1415 .
1416 .
1417 .\" Keep \$0 before \$( in spite of collation.
1418 .TP
1419 .B \[rs]$0
1420 Interpolate the name by which the macro being interpreted was called.
1421 .
1422 In GNU
1423 .I troff \" GNU
1424 this name can vary;
1425 see the
1426 .B als
1427 request.
1428 .
1429 .
1430 .TP
1431 .BI \[rs]$( nn
1432 .TQ
1433 .BI \[rs]$[ nnn ]
1434 In a macro or string definition,
1435 interpolate
1436 the
1437 .IR nn th
1438 or
1439 .IR nnn th
1440 argument.
1441 .
1442 In GNU
1443 .IR troff , \" GNU
1444 macros and strings can have an unlimited number of arguments.
1445 .
1446 .
1447 .TP
1448 .B \[rs]$*
1449 In a macro or string definition,
1450 interpolate the catenation of all arguments,
1451 separated by spaces.
1452 .
1453 .
1454 .TP
1455 .B \[rs]$@
1456 In a macro or string definition,
1457 interpolate the catenation of all arguments,
1458 with each surrounded by double quotes and separated by spaces.
1459 .
1460 .
1461 .TP
1462 .B \[rs]$\[ha]
1463 In a macro or string definition,
1464 interpolate the catenation of all arguments
1465 constructed in a form suitable for passage to the
1466 .B ds
1467 request.
1468 .
1469 .
1470 .TP
1471 .B \[rs])
1472 Interpolate a
1473 .I transparent
1474 dummy character\[em]one that is ignored by end-of-sentence detection.
1475 .
1476 It behaves as
1477 .BR \[rs]& ,
1478 except that
1479 .B \[rs]&
1480 is treated as letters and numerals normally are after
1481 \[lq].\[rq],
1482 \[lq]?\[rq],
1483 and
1484 \[lq]!\[rq];
1485 .B \[rs]&
1486 cancels end-of-sentence detection,
1487 and
1488 .B \[rs])
1489 does not.
1490 .
1491 .
1492 .TP
1493 .BI \[rs]*[ "string\~\c
1494 .RI [ arg \~.\|.\|.]\c
1495 .B ]
1496 Interpolate
1497 .I string,
1498 passing it
1499 .I arg
1500 \&.\|.\|.\&
1501 as arguments.
1502 .
1503 .
1504 .\" Keep \/ before \, in spite of collation.
1505 .TP
1506 .B \[rs]\|/
1507 Apply an
1508 .IR "italic correction" :
1509 modify the spacing of the preceding glyph
1510 so that the distance between it and the following glyph
1511 is correct if the latter is of upright shape.
1512 .
1513 For example,
1514 if an italic\~\[lq]f\^\[rq] is followed immediately
1515 by a roman right parenthesis,
1516 then in many fonts the top right portion of the\~\[lq]f\^\[rq]
1517 overlaps the top of the right parenthesis,
1518 .if t producing \f[I]f\f[R]),
1519 which is ugly.
1520 .
1521 Inserting
1522 .B \[rs]\^/
1523 between them
1524 .if t \{\
1525 . nop produces
1526 . ie \n(.g \f[I]f\/\f[R])
1527 . el \f[I]f\|\f[R])
1528 . nop and
1529 .\}
1530 avoids this problem.
1531 .
1532 Consider using
1533 .B \[rs]\^/
1534 whenever a slanted glyph
1535 is immediately followed by an upright glyph
1536 without any intervening space.
1537 .
1538 .
1539 .TP
1540 .B \[rs],
1541 Apply a
1542 .IR "left italic correction" :
1543 modify the spacing of the following glyph
1544 so that the distance between it and the preceding glyph
1545 is correct if the latter is of upright shape.
1546 .
1547 For example,
1548 if a roman left parenthesis is immediately followed
1549 by an italic\~\[lq]f\^\[rq],
1550 then in many fonts the bottom left portion of the\~\[lq]f\^\[rq]
1551 overlaps the bottom of the left parenthesis,
1552 .if t producing \f[R](\f[I]f\f[R],
1553 which is ugly.
1554 .
1555 Inserting
1556 .B \[rs]\^,
1557 between them
1558 .if t \{\
1559 . nop produces
1560 . ie \n(.g \f[R](\,\f[I]f\f[R]
1561 . el \f[R](\^\f[I]f\f[R]
1562 . nop and
1563 .\}
1564 avoids this problem.
1565 .
1566 Consider using
1567 .B \[rs]\^,
1568 whenever an upright glyph
1569 is followed immediately by a slanted glyph
1570 without any intervening space.
1571 .
1572 .
1573 .TP
1574 .B \[rs]:
1575 Insert a non-printing break point.
1576 .
1577 That is,
1578 a word can break there,
1579 but the soft hyphen character does not mark the break point if it does
1580 (in contrast to
1581 .RB \[lq]\^ \[rs]% \[rq]).
1582 .
1583 The remainder of the word is subject to hyphenation as normal.
1584 .
1585 .
1586 .TP
1587 .BI \[rs]? character-sequence \[rs]?
1588 Suppress formatting of
1589 .I character-sequence.
1590 .
1591 This feature has two applications.
1592 .
1593 .
1594 .IP
1595 Surround operands to the output comparison operator
1596 with
1597 .B \[rs]?\&
1598 to compare them
1599 by character rather than as formatted output.
1600 .
1601 Since
1602 GNU
1603 .I troff \" GNU
1604 reads comparands protected with
1605 .B \[rs]?\&
1606 in copy mode,
1607 they need not even be valid
1608 .I groff
1609 syntax.
1610 .
1611 The escape character is still lexically recognized,
1612 however,
1613 and consumes the next character.
1614 .
1615 .
1616 .IP
1617 When used in a diversion,
1618 .B \[rs]?\&
1619 transparently embeds input,
1620 read in copy mode,
1621 until its own next occurrence on the input line.
1622 .
1623 Use
1624 .B \[rs]!\&
1625 if you want to embed newlines in a diversion.
1626 .
1627 Unlike
1628 .BR \[rs]! ,
1629 .B \[rs]?\&
1630 is interpreted even in copy mode,
1631 and a
1632 .I character-sequence
1633 in the top-level diversion
1634 is not sent to device-independent output.
1635 .
1636 .
1637 .TP
1638 .BI \[rs][ char ]
1639 Typeset the special character
1640 .IR char .
1641 .
1642 See
1643 .MR groff_char 7 .
1644 .
1645 .
1646 .TP
1647 .BI \[rs][ "base-char combining-component\~"\c
1648 .RB .\|.\|. ]
1649 Typeset a composite glyph consisting of
1650 .I base-char
1651 overlaid with one or more
1652 .IR combining-component s.
1653 .
1654 For example,
1655 .RB \[lq]\| \[rs][A\~ho] \^\[rq]
1656 is a capital letter \[lq]A\[rq] with a \[lq]hook accent\[rq] (ogonek).
1657 .
1658 See the
1659 .B \%composite
1660 request below;
1661 .IR "Groff: The GNU Implementation of troff" ,
1662 the
1663 .I groff
1664 Texinfo manual,
1665 for details of composite glyph name construction;
1666 and
1667 .MR groff_char 7
1668 for a list of components used in composite glyph names.
1669 .
1670 .
1671 .TP
1672 .B \[rs]\[ti]
1673 Insert an adjustable,
1674 unbreakable space.
1675 .
1676 As with ordinary spaces,
1677 GNU
1678 .I troff \" GNU
1679 discards any sequence of these at the end of an output line
1680 if a break occurs.
1681 .
1682 .
1683 .\" ====================================================================
1684 .SS "Restricted requests"
1685 .\" ====================================================================
1686 .
1687 To mitigate risks from untrusted input documents,
1688 GNU
1689 .I troff \" GNU
1690 disables the
1691 .BR cf ,
1692 .BR pi ,
1693 and
1694 .B sy
1695 requests by default.
1696 .
1697 Its
1698 .B \-U
1699 option enables \[lq]unsafe mode\[rq],
1700 restoring their function
1701 (and enabling additional
1702 .I groff
1703 extension requests,
1704 .RB \[lq] open \[rq],
1705 .BR opena ,
1706 and
1707 .BR pso ).
1708 .
1709 .
1710 .br
1711 .ne 6v
1712 .\" ====================================================================
1713 .SS "Altered requests"
1714 .\" ====================================================================
1715 .
1716 .TP
1717 .BI .bd\~ "special-font font"
1718 Stop emboldening
1719 .I special-font
1720 when
1721 .I font
1722 is selected.
1723 .
1724 .\" XXX:
1725 .\" Possibly allow prefixing an integer with `\&` to force
1726 .\" interpretation of this form.
1727 .I special-font
1728 must be a font name,
1729 not a mounting position.
1730 .
1731 .TP
1732 .BR .cf\~ [ \[dq] ]\c
1733 .I file
1734 Break and copy the contents of
1735 .I file
1736 as \[lq]throughput\[rq] to
1737 GNU
1738 .IR troff 's \" GNU
1739 output.
1740 .
1741 If a diversion is in use,
1742 GNU
1743 .I troff \" GNU
1744 performs the copy only when the diversion is emitted.
1745 .
1746 In AT&T
1747 .IR troff , \" AT&T
1748 the contents of
1749 .I file
1750 are immediately copied to the output regardless of whether a diversion
1751 is being written to;
1752 this behavior is so anomalous that it must be considered a bug.
1753 .
1754 .
1755 .IP
1756 GNU
1757 .I troff \" GNU
1758 removes a leading neutral double quote
1759 .RB \[oq] \[dq] \[cq]
1760 from the argument,
1761 permitting initial embedded spaces in it,
1762 and reads it to the end of the input line in copy mode.
1763 .
1764 If
1765 .I file
1766 does not exist or is not readable,
1767 a warning in category
1768 .RB \[lq] file \[rq]
1769 is emitted
1770 and the request has no other effect.
1771 .
1772 .
1773 .\" BEGIN Keep in sync with groff.texi node "Compatibility Mode".
1774 .br
1775 .ne 6v
1776 .TP
1777 .BI .de\~ name\~\c
1778 .RI [ end-name ]
1779 .TQ
1780 .BI .am\~ name\~\c
1781 .RI [ end-name ]
1782 .TQ
1783 .BI .ds\~ name\~\c
1784 .RB [[ \[dq] ]\c
1785 .IR contents ]
1786 .TQ
1787 .BI .as\~ name\~\c
1788 .RB [[ \[dq] ]\c
1789 .IR contents ]
1790 In compatibility mode,
1791 these requests behave as
1792 .BR de1 ,
1793 .BR am1 ,
1794 .BR ds1 ,
1795 and
1796 .BR as1 ,
1797 respectively:
1798 GNU
1799 .I troff \" GNU
1800 inserts a
1801 .I "compatibility save"
1802 token at the beginning of the macro,
1803 string,
1804 or appendment thereto as applicable
1805 and a
1806 .I "compatibility restore"
1807 token at its end,
1808 enabling compatibility mode during its interpolation.
1809 .
1810 Thus they work as expected
1811 even if the interpolation context disables compatibility mode.
1812 .\" END Keep in sync with groff.texi node "Compatibility Mode".
1813 .
1814 .
1815 .TP
1816 .BI .hy\~ n
1817 New values 16 and\~32 are available;
1818 the former enables hyphenation before the last character in a word,
1819 and the latter enables hyphenation after the first character in a word.
1820 .
1821 If invoked without an argument,
1822 the mode configured by the
1823 .B hydefault
1824 request is selected.
1825 .
1826 .
1827 .TP
1828 .BI .lf\~ input-line-number\~\c
1829 .RB [[ \[dq] ]\c
1830 .IR file-identifier ]
1831 In GNU
1832 .I troff \" GNU
1833 the first argument becomes the input line number of the
1834 .I next
1835 line the formatter reads.
1836 It also
1837 removes a leading neutral double quote
1838 .RB \[oq] \[dq] \[cq]
1839 from
1840 .I file-identifier,
1841 permitting initial embedded spaces in it,
1842 and reads it to the end of the input line in copy mode.
1843 .
1844 .
1845 .TP
1846 .BR .nx\~ [[ \[dq] ]\c
1847 .IR file ]
1848 GNU
1849 .I troff \" GNU
1850 removes a leading neutral double quote
1851 .RB \[oq] \[dq] \[cq]
1852 from
1853 .IR file ,
1854 permitting initial embedded spaces in it,
1855 and reads it to the end of the input line in copy mode.
1856 .
1857 .
1858 .TP
1859 .BR .pi\~ [ \[dq] ]\c
1860 .I command
1861 GNU
1862 .I troff \" GNU
1863 strips a leading neutral double quote from the argument,
1864 permitting initial embedded spaces in it.
1865 .
1866 .
1867 .TP
1868 .BI .pm\~ name\~\c
1869 \&.\|.\|.
1870 GNU
1871 .I troff \" GNU
1872 reports,
1873 to the standard error stream,
1874 the JSON-encoded name and contents of each macro,
1875 string,
1876 or diversion
1877 .IR name .
1878 .
1879 .
1880 .TP
1881 .BR .so\~ [ \[dq] ]\c
1882 .I file
1883 GNU
1884 .I troff \" GNU
1885 removes a leading neutral double quote
1886 .RB \[oq] \[dq] \[cq]
1887 from
1888 .IR file ,
1889 permitting initial embedded spaces in it,
1890 and reads it to the end of the input line in copy mode.
1891 .
1892 GNU
1893 .I troff \" GNU
1894 searches for
1895 .I file
1896 in any directories specified by
1897 .B \-I
1898 command-line options,
1899 followed by the current working directory.
1900 .
1901 If
1902 .I file
1903 does not exist or is not readable,
1904 GNU
1905 .I troff \" GNU
1906 emits a warning in category
1907 .RB \[lq] file \[rq].
1908 .
1909 .
1910 .TP
1911 .BI .ss\~ word-space-size\~\c
1912 .RI [ additional-sentence-space-size ]
1913 A second argument sets the amount of additional space separating
1914 sentences on the same output line.
1915 .
1916 If omitted,
1917 this amount is set to
1918 .IR word-space-size .
1919 .
1920 Both arguments are in twelfths of current font's space width
1921 (typically one-fourth to one-third em for Western scripts;
1922 see
1923 .MR groff_font 5 ).
1924 .
1925 The default for both parameters is\~12.
1926 .
1927 Negative values are erroneous.
1928 .
1929 .
1930 .TP
1931 .BR .sy\~ [ \[dq] ]\c
1932 .I command
1933 GNU
1934 .I troff \" GNU
1935 strips a leading neutral double quote from the argument,
1936 permitting initial embedded spaces in it.
1937 .
1938 .
1939 .TP
1940 .BR .ta\~ [[\c
1941 .IR "n1 n2\~" .\|.\|.\~ nn \~]\c
1942 .BR T \~\c \" space in roman because we must use 2-font macro with \c
1943 .IR "r1 r2\~" .\|.\|.\~ rn ]
1944 GNU
1945 .I troff \" GNU
1946 supports an extended syntax to specify repeating tab stops after
1947 the
1948 .RB \[lq] T \[rq]
1949 mark.
1950 .
1951 These values are always taken as relative distances from the previous
1952 tab stop.
1953 .
1954 This is the idiomatic way to specify tab stops at equal intervals in
1955 .IR groff .
1956 .
1957 GNU
1958 .IR troff 's \" GNU
1959 startup value is
1960 .RB \[lq] "T 0.5i" \[rq].
1961 .
1962 .
1963 .IP
1964 The syntax summary above instructs
1965 .I groff
1966 to set tabs at positions
1967 .IR n1 ,
1968 .IR n2 ,
1969 \&.\|.\|.\|,
1970 .IR nn ,
1971 then at
1972 .IR nn \|+\| r1 ,
1973 .IR nn \|+\| r2 ,
1974 \&.\|.\|.\|,
1975 .IR nn \|+\| rn ,
1976 then at
1977 .IR nn \|+\| rn \|+\| r1 ,
1978 .IR nn \|+\| rn \|+\| r2 ,
1979 \&.\|.\|.\|,
1980 .IR nn \|+\| rn \|+\| rn ,
1981 and so on.
1982 .
1983 .
1984 .\" ====================================================================
1985 .SS "New requests"
1986 .\" ====================================================================
1987 .
1988 Several GNU
1989 .I troff \" GNU
1990 requests work like AT&T
1991 .IR troff 's \" AT&T
1992 .RB \[lq] as \[rq]
1993 and
1994 .B ds
1995 requests,
1996 accepting an optional leading neutral double quote,
1997 notated
1998 .\" Use single quotes here for quotation to avoid the perversity of an
1999 .\" output device lacking directional double quotes rendering the
2000 .\" following as `"["]"`.
2001 .RB \[oq][ \[dq] ]\[cq],
2002 in an argument that the formatter reads
2003 in copy mode to the end of the input line,
2004 permitting inclusion of leading spaces.
2005 .
2006 .
2007 .TP 8n \" ".break" + 2n
2008 .BI .aln\~ "new-register existing-register"
2009 Create alias
2010 (additional name)
2011 .I new-register
2012 of
2013 .IR existing-register ,
2014 causing the names to refer to the same stored object.
2015 .
2016 If
2017 .I existing-register
2018 is undefined,
2019 the formatter ignores the request.
2020 GNU
2021 .I troff \" GNU
2022 produces a warning in category
2023 .RB \[lq] reg \[rq].
2024 .
2025 See section \[lq]Warnings\[rq] of
2026 .MR \%troff 1
2027 regarding the enablement and suppression of warnings.
2028 .
2029 To remove a register alias,
2030 invoke
2031 .B rr
2032 on its name.
2033 .
2034 A register's contents do not become inaccessible until it has no more
2035 names.
2036 .
2037 .
2038 .TP
2039 .BI .als\~ "new-name existing-name"
2040 Create alias
2041 (additional name)
2042 .I new-name
2043 of request,
2044 string,
2045 macro,
2046 or diversion
2047 .IR existing-name ,
2048 causing the names to refer to the same stored object.
2049 .
2050 If
2051 .I existing-name
2052 is undefined,
2053 the formatter ignores the request.
2054 GNU
2055 .I troff \" GNU
2056 produces a warning in category
2057 .RB \[lq] mac \[rq].
2058 .
2059 If
2060 .I new-name
2061 already exists,
2062 its contents are lost unless already aliased.
2063 .
2064 See section \[lq]Warnings\[rq] of
2065 .MR \%troff 1
2066 regarding the enablement and suppression of warnings.
2067 .
2068 To remove an alias,
2069 invoke
2070 .B rm
2071 on its name.
2072 .
2073 The object itself is not destroyed until it has no more names.
2074 .
2075 .
2076 .IP
2077 When a request,
2078 macro,
2079 string,
2080 or diversion is aliased,
2081 redefinitions and appendments \[lq]write through\[rq] alias names.
2082 .
2083 To replace an alias with a separately defined object,
2084 remove its name first.
2085 .
2086 .
2087 .TP
2088 .BI .am1\~ name\~\c
2089 .RI [ end-name ]
2090 As
2091 .RB \[lq] am \[rq],
2092 but
2093 GNU
2094 .I troff \" GNU
2095 disables compatibility mode while interpreting the appendment to
2096 .I name:
2097 it inserts a
2098 .I "compatibility save"
2099 token at the beginning of the appendment,
2100 and a
2101 .I "compatibility restore"
2102 token at its end.
2103 .
2104 The requests
2105 .RB \[lq] am \[rq],
2106 .BR am1 ,
2107 .BR de ,
2108 and
2109 .B de1
2110 can thus be intermixed freely
2111 since the compatibility save/\:restore tokens
2112 affect only the parts of the macro populated by
2113 .B am1
2114 and
2115 .BR de1 .
2116 .
2117 .
2118 .TP
2119 .BI .ami\~ name\~\c
2120 .RI [ end-name ]
2121 Append to macro indirectly.
2122 .
2123 See
2124 .B dei
2125 below.
2126 .
2127 .
2128 .TP
2129 .BI .ami1\~ name\~\c
2130 .RI [ end-name ]
2131 As
2132 .BR ami ,
2133 but
2134 GNU
2135 .I troff \" GNU
2136 disables compatibility mode
2137 while interpreting the appendment to the macro
2138 named by the contents of string
2139 .I name;
2140 see
2141 .B am1
2142 above.
2143 .
2144 .
2145 .TP
2146 .BI .as1\~ name\~\c
2147 .RB [[ \[dq] ]\c
2148 .IR contents ]
2149 As
2150 .RB \[lq] as \[rq],
2151 but
2152 GNU
2153 .I troff \" GNU
2154 disables compatibility mode
2155 while interpreting the appendment to the string
2156 .I name:
2157 it inserts a
2158 .I "compatibility save"
2159 token at the beginning of the appendment,
2160 and a
2161 .I "compatibility restore"
2162 token at its end.
2163 .
2164 The requests
2165 .RB \[lq] as \[rq],
2166 .BR as1 ,
2167 .BR ds ,
2168 and
2169 .B ds1
2170 can thus be intermixed freely
2171 since the compatibility save/\:restore tokens
2172 affect only the portions of the string populated by
2173 .B as1
2174 and
2175 .BR ds1 .
2176 .
2177 .
2178 .TP
2179 .BI .asciify\~ div
2180 .I Unformat
2181 the diversion
2182 .I div
2183 in a way such that Unicode basic Latin (US-ASCII) characters,
2184 characters translated with the
2185 .B trin
2186 request,
2187 space characters,
2188 and some escape sequences
2189 that were formatted in the diversion
2190 .I div
2191 are treated like ordinary input characters when
2192 .I div
2193 is interpolated.
2194 .
2195 Doing so can be useful in conjunction with the
2196 .B writem
2197 request.
2198 .
2199 .
2200 .IP
2201 When transforming a glyph node back into an input sequence
2202 that demands expression as a special character escape sequence,
2203 GNU
2204 .I troff
2205 uses the default escape character.
2206 .
2207 .
2208 .IP
2209 .B \%asciify
2210 cannot return all nodes in a diversion to their source equivalents:
2211 those produced by indexed characters
2212 .RB ( \[rs]N ),
2213 for example,
2214 remain nodes,
2215 so the result cannot be guaranteed to be a character sequence
2216 as a macro or string is.
2217 .\" TODO: We _could_ store the integer argument to the `\N` escape
2218 .\" sequence in the node data, enabling such reversal.
2219 .
2220 Give the diversion name as an argument to the
2221 .B pm
2222 request to inspect its contents and node list.
2223 .
2224 Glyph parameters such as the type face and size are not preserved;
2225 use
2226 .RB \%\[lq] unformat \[rq]
2227 to achieve that.
2228 .
2229 .
2230 .TP
2231 .B .backtrace
2232 Write backtrace of input stack to the standard error stream.
2233 .
2234 See the
2235 .B \-b
2236 option of
2237 .MR \%troff 1 .
2238 .
2239 .
2240 .TP
2241 .BR .blm\~ [\c
2242 .IR name ]
2243 Set a blank line macro (trap).
2244 .
2245 If a blank line macro is thus defined,
2246 .I groff
2247 executes
2248 .I name
2249 when a blank line is encountered in the input,
2250 instead of the usual behavior.
2251 .
2252 A line consisting only of spaces is also treated as blank and subject to
2253 this trap.
2254 .
2255 If no argument is supplied,
2256 the default blank line behavior is (re-)established.
2257 .
2258 .
2259 .br
2260 .ne 4v
2261 .TP
2262 .BR .box\~ [\c
2263 .IR name ]
2264 .TQ
2265 .BR .boxa\~ [\c
2266 .IR name ]
2267 Divert
2268 (or append)
2269 output to
2270 .I name,
2271 similarly to the
2272 .B di
2273 and
2274 .B da
2275 requests,
2276 respectively.
2277 .
2278 Any pending output line is
2279 .I not
2280 included in the diversion.
2281 .
2282 Without an argument,
2283 stop diverting output;
2284 any pending output line inside the diversion is discarded.
2285 .
2286 .
2287 .TP
2288 .B .break
2289 Exit a
2290 .RB \[lq] while \[rq]
2291 loop.
2292 .
2293 Do not confuse this request with a typographical break or the
2294 .B br
2295 request.
2296 .
2297 See
2298 .RB \[lq] continue \[rq].
2299 .
2300 .
2301 .TP
2302 .B .brp
2303 Break and force adjustment of the output line
2304 per the current adjustment mode.
2305 .
2306 Like
2307 .BR br ,
2308 it does nothing if invoked with the no-break control character.
2309 .
2310 .
2311 .TP
2312 .BI .cflags\~ "n c"\c
2313 \&.\|.\|.
2314 Assign properties encoded by non-negative integer
2315 .I n
2316 to each character or class
2317 .IR c .
2318 .
2319 Spaces need not separate
2320 .I c
2321 arguments.
2322 .
2323 .
2324 .\" TODO: Bust discussion of character flags into its own subsection?
2325 .IP
2326 .I n
2327 is the sum of any of the following.
2328 .
2329 Some combinations are nonsensical,
2330 such as
2331 .RB \[lq] 33 \[rq]
2332 (1 + 32).
2333 .
2334 .
2335 .RS
2336 .IP 1
2337 Recognize the character as ending a sentence if followed by a newline
2338 or two spaces.
2339 .
2340 Initially,
2341 characters
2342 .RB \[lq] .?!\& \[rq]
2343 have this property.
2344 .
2345 .
2346 .IP 2
2347 Enable breaks before the character.
2348 .
2349 A line is not broken at a character with this property unless the
2350 characters on each side both have non-zero hyphenation codes.
2351 .
2352 This exception can be overridden by adding 64.
2353 .
2354 Initially,
2355 no characters have this property.
2356 .
2357 .
2358 .IP 4
2359 Enable breaks after the character.
2360 .
2361 A line is not broken at a character with this property unless the
2362 characters on each side both have non-zero hyphenation codes.
2363 .
2364 This exception can be overridden by adding 64.
2365 .
2366 Initially,
2367 characters
2368 .RB \[lq] \-\[rs][hy]\[rs][em] \^\[rq]
2369 have this property.
2370 .
2371 .
2372 .IP 8
2373 Mark the glyph associated with this character as overlapping other
2374 instances of itself horizontally.
2375 .
2376 Initially,
2377 characters
2378 .RB \[lq]\^ \[rs][ul]\[rs][rn]\[rs][ru]\[rs][radicalex]\[rs][sqrtex]\
2379 \& \^\[rq]
2380 have this property.
2381 .
2382 .
2383 .IP 16
2384 Mark the glyph associated with this character as overlapping other
2385 instances of itself vertically.
2386 .
2387 Initially,
2388 the character
2389 .RB \[lq]\^ \[rs][br] \^\[rq]
2390 has this property.
2391 .
2392 .
2393 .IP 32
2394 Mark the character as transparent for the purpose of end-of-sentence
2395 recognition.
2396 .
2397 In other words,
2398 an end-of-sentence character followed by any number of characters with
2399 this property is treated as the end of a sentence if followed by a
2400 newline or two spaces.
2401 .
2402 This is the same as having a zero space factor in \*[tx].
2403 .
2404 Initially,
2405 characters
2406 .\" The following is ordered with the apostrophe and (single) closing
2407 .\" quote on the ends so they are more easily visually distinguished
2408 .\" from the double quotation marks in roman.
2409 .RB \[lq]\| \[aq]\|"\|)]*\[rs][dg]\[rs][dd]\[rs][rq]\[rs]\^[cq] \|\[rq]
2410 have this property.
2411 .
2412 .
2413 .IP 64
2414 Ignore hyphenation codes of the surrounding characters.
2415 .
2416 Use this value in combination with values 2 and\~4.
2417 .
2418 Initially,
2419 no characters have this property.
2420 .
2421 .
2422 .P
2423 The remaining values were implemented for East Asian language support;
2424 those who use alphabetic scripts exclusively can disregard them.
2425 .
2426 .
2427 .IP 128
2428 Prohibit a break before the character,
2429 but allow a break after the character.
2430 .
2431 This works only in combination with values 256 and 512 and has no effect
2432 otherwise.
2433 .
2434 Initially,
2435 no characters have this property.
2436 .
2437 .
2438 .IP 256
2439 Prohibit a break after the character,
2440 but allow a break before the character.
2441 .
2442 This works only in combination with values 128 and 512 and has no effect
2443 otherwise.
2444 .
2445 Initially,
2446 no characters have this property.
2447 .
2448 .
2449 .IP 512
2450 Allow a break before or after the character.
2451 .
2452 This works only in combination with values 128 and 256 and has no effect
2453 otherwise.
2454 .
2455 Initially,
2456 no characters have this property.
2457 .RE
2458 .
2459 .
2460 .IP
2461 In contrast to values 2 and\~4,
2462 the values 128,
2463 256,
2464 and 512 work
2465 pairwise.
2466 .
2467 If,
2468 for example,
2469 the left character has value 512,
2470 and the right character 128,
2471 no break will be automatically inserted between them.
2472 .
2473 If we use value\~6 instead for the left character,
2474 a break after the character can't be suppressed since the neighboring
2475 character on the right doesn't get examined.
2476 .
2477 .
2478 .TP
2479 .BI .char\~ c\~\c
2480 .RB [[ \[dq] ]\c
2481 .IR contents ]
2482 Define an
2483 ordinary,
2484 special,
2485 or
2486 indexed
2487 character
2488 .I c
2489 as
2490 .I contents.
2491 .
2492 Omitting
2493 .I contents
2494 gives
2495 .I c
2496 an empty definition.
2497 .
2498 .
2499 .IP
2500 Defining
2501 (or redefining)
2502 a
2503 .RI character\~ c
2504 creates a formatter object
2505 that
2506 GNU
2507 .I troff \" GNU
2508 recognizes like any other ordinary,
2509 special,
2510 or indexed character on input,
2511 and produces
2512 .I contents
2513 on output.
2514 .
2515 When
2516 formatting
2517 .IR c ,
2518 GNU
2519 .I troff \" GNU
2520 processes
2521 .I contents
2522 in a temporary environment and encapsulates the result
2523 in a node
2524 (see section \[lq]GNU troff Internals\[rq] in
2525 .IR "Groff: The GNU Implementation of troff" ,
2526 the
2527 .I groff
2528 Texinfo manual);
2529 disabling compatibility mode
2530 and setting the escape character to
2531 .RB to\~ \[rs]
2532 while interpreting
2533 .I contents.
2534 .
2535 Any emboldening,
2536 constant spacing,
2537 or track kerning applies to this object
2538 rather than to individual glyphs resulting from the formatting of
2539 .I contents.
2540 .
2541 .
2542 .IP
2543 A character defined by
2544 .B char
2545 can be used just like a glyph provided by the output device.
2546 .
2547 In particular,
2548 other characters can be translated to it with the
2549 .B tr
2550 request;
2551 it can be made the tab or leader fill character with the
2552 .B tc
2553 and
2554 .B lc
2555 requests;
2556 sequences of it can be drawn with the
2557 .B \[rs]l
2558 and
2559 .B \[rs]L
2560 escape sequences;
2561 and,
2562 if the
2563 .B hcode
2564 request is used on
2565 .IR c ,
2566 it is subject to automatic hyphenation.
2567 .
2568 .
2569 .IP
2570 However,
2571 a user-defined character
2572 .I c
2573 does not participate at its boundaries
2574 in kerning adjustments or italic corrections.
2575 .
2576 .
2577 .IP
2578 The formatter prevents infinite recursion
2579 by treating an occurrence
2580 of a character in its own definition
2581 as if it were undefined;
2582 when interpolating such a character,
2583 GNU
2584 .I troff \" GNU
2585 emits a warning in category
2586 .RB \[lq] char \[rq].
2587 (Mutually recursive character definitions are handled similarly.)
2588 .
2589 .
2590 .IP
2591 The
2592 .B tr
2593 and
2594 .B trin
2595 requests take precedence if
2596 .B char
2597 also applies
2598 .RI to\~ c .
2599 .
2600 The
2601 .B rchar
2602 request removes character definitions.
2603 .
2604 .
2605 .TP
2606 .BI .chop\~ name
2607 Remove the last character from the macro,
2608 string,
2609 or diversion
2610 .IR name .
2611 .
2612 This is useful for removing the newline from the end of a diversion that
2613 is to be interpolated as a string.
2614 .
2615 This request can be used repeatedly on the same
2616 .IR name ;
2617 see section \[lq]GNU troff Internals\[rq] in
2618 .IR "Groff: The GNU Implementation of troff" ,
2619 the
2620 .I groff
2621 Texinfo manual,
2622 for discussion of nodes inserted by
2623 .IR groff .
2624 .
2625 .
2626 .TP
2627 .BI .class\~ ident\~c\~\c
2628 \&.\|.\|.
2629 Define a character class
2630 (or simply \[lq]class\[rq])
2631 .I ident
2632 comprising the members
2633 .IR c \&.\|.\|.,
2634 where each
2635 .I c
2636 is an
2637 ordinary,
2638 special,
2639 or
2640 indexed
2641 character;
2642 or a
2643 .I "range expression."
2644 .
2645 A class thus defined can then be referred to
2646 in a
2647 .B \%cflags
2648 request in lieu of listing all the characters within it.
2649 .
2650 .
2651 .IP
2652 Since class and special character names share the same name space,
2653 we recommend starting and ending the class name with
2654 .RB \[lq] [ \[rq]
2655 and
2656 .RB \[lq] ] \[rq],
2657 respectively,
2658 to avoid collisions with existing special character names defined by
2659 GNU
2660 .I troff \" GNU
2661 or the user
2662 (with
2663 .B char
2664 and related requests).
2665 .
2666 This practice applies the presence of
2667 .RB \[lq] ] \[rq]
2668 in the class name to prevent the usage of the special character escape
2669 form
2670 .RB \[lq] \[rs][ .\|.\|. ] \[rq],
2671 you must therefore access a class thus named via the
2672 .B \[rs]C
2673 escape sequence.
2674 .
2675 .
2676 .IP
2677 An argument
2678 .I c
2679 can alternatively be a
2680 .I "range expression"
2681 consisting of a start character followed by
2682 .RB \[lq] \- \[rq]
2683 and then an end character.
2684 .
2685 Internally,
2686 GNU
2687 .I troff \" GNU
2688 converts these two character names to Unicode code points
2689 (according to the
2690 .I groff
2691 glyph list [GGL]),
2692 which determine the start and end values of the range.
2693 .
2694 If that conversion fails,
2695 GNU
2696 .I troff \" GNU
2697 skips the range expression and any remaining arguments.
2698 .\" .
2699 .\" Furthermore,
2700 .\" classes can be nested.
2701 .
2702 .
2703 .TP
2704 .BI .close\~ stream
2705 Close the named
2706 .IR stream ,
2707 invalidating it as an argument to the
2708 .RB \[lq] write \[rq]
2709 request.
2710 .
2711 See
2712 .RB \[lq] open \[rq].
2713 .
2714 .
2715 .TP
2716 .BI .composite\~ c1\~c2
2717 Map ordinary or special character
2718 .I c1
2719 to
2720 .I c2
2721 when
2722 .I c1
2723 is a combining component in a composite character.
2724 .
2725 Typically,
2726 .B composite
2727 is used to map a spacing character to a combining one.
2728 .
2729 See
2730 .MR groff_char 7 .
2731 .
2732 .
2733 .TP
2734 .B .continue
2735 Skip the remainder of a
2736 .RB \[lq] while \[rq]
2737 loop's body,
2738 immediately retesting its conditional expression.
2739 .
2740 See
2741 .RB \[lq] break \[rq]
2742 above.
2743 .
2744 .
2745 .TP
2746 .BR .color\~ [\c
2747 .IR b ]
2748 Enable or disable output of color-related device-independent output
2749 commands per Boolean expression
2750 .IR b .
2751 .
2752 It is enabled by default,
2753 and if
2754 .I b
2755 is omitted.
2756 .
2757 .
2758 .TP
2759 .BR .cp\~ [\c
2760 .IR b ]
2761 Enable or disable AT&T
2762 .I troff \" AT&T
2763 compatibility mode per Boolean expression
2764 .IR b .
2765 .
2766 It is disabled by default,
2767 and enabled if
2768 .I b
2769 is omitted.
2770 .
2771 In compatibility mode,
2772 long names are not recognized,
2773 and the incompatibilities they cause do not arise.
2774 .
2775 .
2776 .TP
2777 .BI .defcolor\~ "ident scheme color-component\~\c"
2778 \&.\|.\|.
2779 Define a color named
2780 .I ident.
2781 .
2782 .I scheme
2783 identifies a color space and determines the number of required
2784 .IR color-component s;
2785 it must be one of
2786 .RB \[lq] rgb \[rq]
2787 (three components),
2788 .RB \[lq] cmy \[rq]
2789 (three components),
2790 .RB \[lq] cmyk \[rq]
2791 (four components),
2792 or
2793 .RB \[lq] gray \[rq]
2794 (one component).
2795 .
2796 .RB \[lq] grey \[rq]
2797 is accepted as a synonym of
2798 .RB \[lq] gray \[rq].
2799 .
2800 Each color component can be encoded as a hexadecimal value starting
2801 with
2802 .B #
2803 or
2804 .BR ## .
2805 .
2806 The former indicates that each component is in the range 0\[en]255
2807 (0\[en]FF),
2808 the latter the range 0\[en]65535 (0\[en]FFFF).
2809 .
2810 Alternatively,
2811 a component can be specified as a decimal fraction in the range 0\[en]1,
2812 interpreted using a default scaling unit
2813 .RB of\~\[lq] f \^\[rq],
2814 which multiplies its value by 65,536
2815 (but clamps it at 65,535).
2816 .
2817 .
2818 .IP
2819 Each output device has a color named
2820 .RB \[lq] default \[rq],
2821 which cannot be redefined.
2822 .
2823 A device's default stroke and fill colors are not necessarily the same.
2824 .
2825 .
2826 .TP
2827 .BI .de1\~ ident\~\c
2828 .RI [ end-name ]
2829 As
2830 .RB \[lq] de \[rq],
2831 but
2832 GNU
2833 .I troff \" GNU
2834 disables compatibility mode while interpreting
2835 .I name:
2836 it inserts a
2837 .I "compatibility save"
2838 token at the beginning of the macro definition,
2839 and a
2840 .I "compatibility restore"
2841 token at its end.
2842 .
2843 See
2844 .B .am1
2845 above.
2846 .
2847 .
2848 .TP
2849 .BI .dei\~ name\~\c
2850 .RI [ end-name ]
2851 Define macro indirectly,
2852 with the name of the macro to be defined in string
2853 .I name
2854 and the name of the end macro terminating its definition in string
2855 .IR end-name .
2856 .
2857 .
2858 .TP
2859 .BI .dei1\~ name\~\c
2860 .RI [ end-name ]
2861 As
2862 .BR dei ,
2863 but
2864 GNU
2865 .I troff \" GNU
2866 disables compatibility mode
2867 while interpreting the macro
2868 named by the contents of string
2869 .I name.
2870 .
2871 See
2872 .B am1
2873 and
2874 .B de1
2875 above.
2876 .
2877 .
2878 .TP
2879 .BR .device\~ [\c
2880 .RB [ \[dq] ]\c
2881 .IR character-sequence ]
2882 Embed
2883 .I character-sequence
2884 into
2885 GNU
2886 .I troff \" GNU
2887 output as parameters to an
2888 .RB \[lq]x X\[rq]
2889 device extension command;
2890 see
2891 .MR groff_out 5 .
2892 .
2893 The output driver or other postprocessor interprets
2894 .I character-sequence
2895 as it sees fit.
2896 .
2897 .
2898 .TP
2899 .BI .devicem\~ name
2900 Write contents of macro or string
2901 .I name
2902 to
2903 .I \%troff
2904 output as the argument to a device extension command.
2905 .
2906 .
2907 .TP
2908 .BI .do\~ name\~\c
2909 .RI [ argument \~.\|.\|.]
2910 Interpret the string,
2911 request,
2912 diversion,
2913 or macro
2914 .I name
2915 (along with any further arguments)
2916 with compatibility mode disabled.
2917 .
2918 Compatibility mode is restored
2919 (only if it was active)
2920 when the interpolation of
2921 .I name
2922 is interpreted;
2923 that is,
2924 the restored compatibility state applies to the request or
2925 contents of the macro,
2926 string,
2927 or diversion
2928 .IR name ,
2929 its arguments,
2930 and data read from files or pipes if
2931 .I name
2932 is the
2933 .RB \[lq] so \[rq],
2934 .BR soquiet ,
2935 .BR mso ,
2936 .BR msoquiet ,
2937 or
2938 .B pso
2939 request.
2940 .
2941 .
2942 .TP
2943 .BI .ds1\~ name\~\c
2944 .RB [[ \[dq] ]\c
2945 .IR contents ]
2946 As
2947 .BR ds ,
2948 but GNU
2949 .I troff \" GNU
2950 disables AT&T compatibility mode while interpreting
2951 .IR name :
2952 it inserts a \[lq]compatibility save\[rq] token at the beginning of
2953 .IR contents ,
2954 and a \[lq]compatibility restore\[rq] token after it.
2955 .
2956 .
2957 .TP
2958 .B .ecr
2959 Restore the escape character saved with
2960 .BR ecs ,
2961 or set escape character to
2962 .RB \[lq]\| \[rs] \[rq]
2963 if none has been saved.
2964 .
2965 .
2966 .TP
2967 .B .ecs
2968 Save the current escape character.
2969 .
2970 .
2971 .br
2972 .ne 5v
2973 .TP
2974 .BI .evc\~ env
2975 Copy the properties of environment
2976 .I env
2977 to the current environment,
2978 except for:
2979 .
2980 .
2981 .RS
2982 .IP \[bu] 3n
2983 a partially collected line,
2984 if present;
2985 .
2986 .
2987 .IP \[bu]
2988 the interruption status of the previous input line
2989 (due to use of the
2990 .B \[rs]c
2991 escape sequence);
2992 .
2993 .
2994 .IP \[bu]
2995 the count of remaining lines to center,
2996 to right-align,
2997 or to underline
2998 (with or without underlined spaces)\[em]these are set to zero;
2999 .
3000 .
3001 .IP \[bu]
3002 the activation status of temporary indentation;
3003 .
3004 .
3005 .IP \[bu]
3006 input traps and their associated data;
3007 .
3008 .
3009 .br
3010 .ne 4v
3011 .IP \[bu]
3012 the activation status of line numbering
3013 (which can be reactivated with
3014 .RB \[lq] .nm\~+0 \[rq]);
3015 and
3016 .
3017 .
3018 .IP \[bu]
3019 the count of consecutive hyphenated lines
3020 (set to zero).
3021 .RE
3022 .
3023 .
3024 .IP
3025 Copying an environment to itself discards the foregoing data.
3026 .
3027 .
3028 .TP
3029 .BR .fam\~ [\c
3030 .IR fml ]
3031 Set default font family to
3032 .IR fml .
3033 .
3034 With no argument,
3035 the previous font family is selected,
3036 and if none,
3037 the formatter's default family.
3038 .
3039 This default is \[lq]T\[rq] (Times),
3040 but can be overridden by the output device\[em]see
3041 .MR groff_font 5 .
3042 .
3043 The default font family is associated with the environment.
3044 .
3045 See
3046 .BR \[rs]F .
3047 .
3048 .
3049 .TP
3050 .BI .fchar\~ c\~\c
3051 .RB [[ \[dq] ]\c
3052 .IR contents ]
3053 Define fallback
3054 .RI character\~ c
3055 as
3056 .IR contents .
3057 .
3058 As
3059 .BR char ,
3060 but while that request hides a glyph with the same name in the selected
3061 font,
3062 .B fchar
3063 definitions are used only if the font
3064 lacks a glyph for
3065 .IR c .
3066 .
3067 GNU
3068 .I troff \" GNU
3069 performs this test before searching special fonts.
3070 .
3071 .
3072 .TP
3073 .BR .fcolor\~ [\c
3074 .IR col ]
3075 Select
3076 .I col
3077 as the environment's fill color,
3078 or,
3079 without an argument,
3080 restore the previous fill color,
3081 or the default if there is none.
3082 .
3083 .
3084 .TP
3085 .BI .fschar\~ f\~c\~\c
3086 .RB [[ \[dq] ]\c
3087 .IR contents ]
3088 Define fallback special
3089 .RI character\~ c
3090 for font\~\c
3091 .I f
3092 as
3093 .IR contents .
3094 .
3095 As
3096 .BR char ,
3097 but GNU
3098 .I troff \" GNU
3099 locates a character defined by
3100 .B fschar
3101 after any fonts named as arguments to the
3102 .B \%fspecial
3103 are searched and before those named as arguments to the
3104 .RB \%\[lq] special \[rq]
3105 request.
3106 .
3107 .TP
3108 .BI .fspecial\~ f\~\c
3109 .RI [ s\~ .\|.\|.]
3110 Declare each font
3111 .I s
3112 as special only when
3113 .RB font\~ f
3114 is selected.
3115 .
3116 Initially,
3117 a font
3118 .IR f 's
3119 list of associated special fonts is empty for all
3120 .I f.
3121 .
3122 .\" TODO: Move this sentence to a new (sub)section describing the glyph
3123 .\" resolution procedure.
3124 GNU
3125 .I troff \" GNU
3126 searches fonts specified as arguments to the
3127 .RB \%\[lq] special \[rq]
3128 request after those given as arguments to the
3129 .B \%fspecial
3130 request.
3131 .
3132 See
3133 .RB \%\[lq] special \[rq].
3134 .
3135 .
3136 .TP
3137 .BI .ftr\~ f\~\c
3138 .RI [ g ]
3139 Translate
3140 .RI font\~ f
3141 .RI to\~ g .
3142 .
3143 Whenever a font
3144 .RI named\~ f
3145 is referred to in an
3146 .B \[rs]f
3147 escape sequence,
3148 in the
3149 .B F
3150 and
3151 .B S
3152 conditional expression operators,
3153 or in the
3154 .BR ft ,
3155 .BR ul ,
3156 .BR bd ,
3157 .BR cs ,
3158 .BR tkf ,
3159 .RB \%\[lq] special \[rq],
3160 .BR \%fspecial ,
3161 .BR fp ,
3162 or
3163 .B sty
3164 requests,
3165 .RI font\~ g
3166 is used.
3167 If
3168 .I g
3169 is missing or identical
3170 .RI to\~ f ,
3171 then
3172 .RI font\~ f
3173 is not translated.
3174 .
3175 .
3176 .TP
3177 .BI .fzoom\~ f\~\c
3178 .RI [ zoom ]
3179 Set zoom factor
3180 .I zoom
3181 for font\~\c
3182 .IR f .
3183 .I zoom
3184 must be a non-negative integer;
3185 it scales the magnification by thousandths with 1000 as a basis.
3186 If
3187 .I zoom
3188 is missing or equal to zero or 1000,
3189 .RI font\~ f
3190 is not magnified.
3191 .
3192 .IR f \~\c
3193 must be a resolved font name,
3194 not an abstract style or mounting position.
3195 .
3196 .
3197 .TP
3198 .BR .gcolor\~ [\c
3199 .IR col ]
3200 Select
3201 .I col
3202 as the environment's stroke color,
3203 or,
3204 without an argument,
3205 restore the previous stroke color,
3206 or the default if there is none.
3207 .
3208 .
3209 .TP
3210 .BI .hcode\~ "dst1 src1\~"\c
3211 .RI [ "dst2 src2" "] .\|.\|."
3212 Set the hyphenation code of character
3213 .I dst1
3214 to that of
3215 .IR src1 ,
3216 and so on.
3217 .
3218 .I dst1
3219 must be an ordinary character
3220 (other than a numeral)
3221 or a special character,
3222 and
3223 .I src1
3224 must be an ordinary character
3225 (other than a numeral)
3226 or a special character
3227 to which a hyphenation code has already been applied.
3228 .
3229 Assigning the code of an ordinary character to itself
3230 effectively creates a unique hyphenation code
3231 (which can then be copied to others).
3232 .
3233 .B hcode
3234 ignores spaces between arguments.
3235 .
3236 If any argument is invalid,
3237 .B hcode
3238 reports an error and stops reading them.
3239 .
3240 .
3241 .TP
3242 .BR .hla\~ [\c
3243 .IR lang ]
3244 Set the hyphenation language to
3245 .IR lang ,
3246 or clear it if there is no argument.
3247 .
3248 Hyphenation exceptions specified with the
3249 .B hw
3250 request and hyphenation patterns and exceptions specified with the
3251 .B hpf
3252 and
3253 .B hpfa
3254 requests are associated with the hyphenation language.
3255 .
3256 The
3257 .B hla
3258 request is usually invoked by a localization file,
3259 which is in turn loaded by the
3260 .I troffrc
3261 or
3262 .I troffrc\-end
3263 file;
3264 see the
3265 .B hpf
3266 request below.
3267 .
3268 .\" XXX: Not true today, but see Savannah #66387.
3269 .\" The hyphenation language is associated with the environment.
3270 .
3271 .
3272 .TP
3273 .BR .hlm\~ [\c
3274 .IR n ]
3275 Set the consecutive automatically hyphenated line limit to
3276 .I n.
3277 .
3278 A negative value means \[lq]no limit\[rq].
3279 .
3280 Omitting
3281 .I n
3282 implies a limit of
3283 .BR \-1 .
3284 .
3285 This value is associated with the environment.
3286 .
3287 Only lines output from a given environment count toward the maximum
3288 associated with that environment.
3289 .
3290 Hyphens resulting from
3291 .B \[rs]%
3292 are counted;
3293 explicit hyphens are not.
3294 .
3295 .
3296 .TP
3297 .BR .hpf\~ [ \[dq] ]\c
3298 .I pattern-file
3299 Read hyphenation patterns from
3300 .IR pattern-file .
3301 .
3302 This file is sought in the same way that macro files are with the
3303 .B mso
3304 request.
3305 .
3306 .
3307 .IP
3308 The
3309 .I pattern-file
3310 should have the same format as (simple) \*[tx] pattern files.
3311 .
3312 The following scanning rules are implemented.
3313 .
3314 .
3315 .RS
3316 .IP \[bu] 3n
3317 A percent sign starts a comment
3318 (up to the end of the line)
3319 even if preceded by a backslash.
3320 .
3321 .
3322 .IP \[bu]
3323 \[lq]Digraphs\[rq] like
3324 .B \[rs]$
3325 are not supported.
3326 .
3327 .
3328 .IP \[bu]
3329 .RB \[lq] \[ha]\[ha]\c
3330 .IR xx \[rq]
3331 (where each
3332 .I x
3333 is 0\[en]9 or a\[en]f) and
3334 .BI \[ha]\[ha] c
3335 .RI (character\~ c
3336 in the code point range 0\[en]127 decimal)
3337 are recognized;
3338 other uses
3339 .RB of\~ \[ha]
3340 cause an error.
3341 .
3342 .
3343 .IP \[bu]
3344 No macro expansion is performed.
3345 .
3346 .
3347 .IP \[bu]
3348 .B hpf
3349 checks for the expression
3350 .BR \[rs]patterns{ .\|.\|. }
3351 (possibly with whitespace before or after the braces).
3352 .
3353 Everything between the braces is taken as hyphenation patterns.
3354 .
3355 Consequently,
3356 .RB \[lq] { \[rq]
3357 and
3358 .RB \[lq] } \[rq]
3359 are not allowed in patterns.
3360 .
3361 .
3362 .IP \[bu]
3363 Similarly,
3364 .BR \[rs]hyphenation{ .\|.\|. }
3365 gives a list of hyphenation exceptions.
3366 .
3367 .
3368 .IP \[bu]
3369 .B \[rs]endinput
3370 is recognized also.
3371 .
3372 .
3373 .IP \[bu]
3374 For backward compatibility,
3375 if
3376 .B \[rs]patterns
3377 is missing,
3378 the whole file is treated as a list of hyphenation patterns
3379 (but the
3380 .RB \[lq] % \[rq]
3381 character is still recognized as the start of a comment).
3382 .RE
3383 .
3384 .
3385 .IP
3386 Use the
3387 .B hcode
3388 request
3389 (see above)
3390 to map the encoding used in hyphenation pattern files to
3391 .IR groff 's
3392 input encoding.
3393 .
3394 .
3395 .IP
3396 GNU
3397 .I troff \" GNU
3398 ties the set of hyphenation patterns
3399 to the hyphenation language code
3400 selected by the
3401 .B hla
3402 request.
3403 .
3404 The
3405 .B hpf
3406 request is usually invoked by a localization file loaded by the
3407 .I troffrc
3408 file.
3409 .
3410 .I groff
3411 provides localization files for several languages;
3412 See subsection \[lq]Localization packages\[rq] of
3413 .MR groff_tmac 5 .
3414 .
3415 For Western languages,
3416 the localization file
3417 sets the default hyphenation mode
3418 and loads hyphenation patterns and exceptions.
3419 .
3420 By default,
3421 .I troffrc
3422 loads the localization file for English.
3423 .
3424 .
3425 .IP
3426 A second call to
3427 .B hpf
3428 (for the same language)
3429 replaces the old patterns with the new ones.
3430 .
3431 .
3432 .IP
3433 Invoking
3434 .B hpf
3435 causes an error if there is no hyphenation language.
3436 .
3437 .
3438 .IP
3439 If no
3440 .B hpf
3441 request is specified
3442 (either in the document,
3443 in a file loaded at startup,
3444 or in a macro package),
3445 GNU
3446 .I troff \" GNU
3447 won't automatically hyphenate at all.
3448 .
3449 .
3450 .TP
3451 .BR .hpfa\~ [ \[dq] ]\c
3452 .I pattern-file
3453 As
3454 .BR hpf ,
3455 except that the hyphenation patterns and exceptions from
3456 .I pattern-file
3457 are appended to the patterns already applied to the hyphenation language
3458 of the environment.
3459 .
3460 .
3461 .TP
3462 .BI .hpfcode\~ "a b"\c
3463 .RI \~[ "c d" "] .\|.\|."
3464 .I Caution:
3465 This request will be withdrawn in a future
3466 .I groff
3467 release.
3468 .
3469 Use
3470 .B hcode
3471 instead.
3472 .
3473 .
3474 .IP
3475 Define mapping values for character codes in pattern files.
3476 .
3477 .B hpf
3478 or
3479 .B hpfa
3480 apply the mapping
3481 after reading or appending to the active list of patterns.
3482 .
3483 Its arguments are pairs of character codes\[em]integers from 0 to\~255.
3484 .
3485 The request maps character
3486 .RI code\~ a
3487 to
3488 .RI code\~ b ,
3489 .RI code\~ c
3490 to
3491 .RI code\~ d ,
3492 and so on.
3493 .
3494 Character codes that would otherwise be invalid in GNU
3495 .I troff \" GNU
3496 can be used.
3497 .
3498 By default,
3499 every code maps to itself except those for letters \[lq]A\[rq] to
3500 \[lq]Z\[rq],
3501 which map to those for \[lq]a\[rq] to \[lq]z\[rq].
3502 .
3503 .
3504 .TP
3505 .BI .hydefault\~ mode
3506 Set hyphenation mode default to
3507 .I mode.
3508 .
3509 When the
3510 .B hy
3511 request is invoked without an argument,
3512 this mode is selected.
3513 .
3514 The hyphenation mode default is associated with the environment.
3515 .
3516 The formatter's default is
3517 .B 1
3518 for AT&T
3519 .I troff \" AT&T
3520 compatibility.
3521 .
3522 .I groff
3523 locale files generally set a more appropriate one;
3524 see
3525 .MR groff_tmac 5 .
3526 .
3527 .
3528 .TP
3529 .BR .hym\~ [\c
3530 .IR length ]
3531 Set the (right) hyphenation margin
3532 .RI to\~ length .
3533 .
3534 If the adjustment mode is not
3535 .RB \[lq] b \[rq]
3536 or
3537 .RB \[lq] n \[rq],
3538 the line is not hyphenated if it is shorter than
3539 .IR length .
3540 .
3541 Without an argument,
3542 the default hyphenation margin is reset to its default value,
3543 0.
3544 .
3545 The default scaling unit
3546 .RB is\~\[lq] m \[rq].
3547 .
3548 The hyphenation margin is associated with the environment.
3549 .
3550 A negative argument resets the hyphenation margin to zero,
3551 emitting a warning in category
3552 .RB \[lq] range \[rq].
3553 .
3554 .
3555 .TP
3556 .BR .hys\~ [\c
3557 .IR hyphenation-space ]
3558 Suppress hyphenation of the line in adjustment modes
3559 .RB \[lq] b \[rq]
3560 or
3561 .RB \[lq] n \[rq],
3562 if that adjustment can be achieved by adding no more than
3563 .I hyphenation-space
3564 extra space to each inter-word space.
3565 .
3566 Without an argument,
3567 the hyphenation space adjustment threshold is set to its default value,
3568 0.
3569 .
3570 The default scaling unit
3571 .RB is\~\[lq] m \[rq].
3572 .
3573 The hyphenation space adjustment threshold is associated with the
3574 environment.
3575 .
3576 A negative argument resets the hyphenation space adjustment threshold to
3577 zero,
3578 emitting a warning in category
3579 .RB \[lq] range \[rq].
3580 .
3581 .
3582 .TP
3583 .BR .itc\~ n\~\c\" TODO: borrow "npl" notation from groff(7)?
3584 .RI [ mac ]
3585 As
3586 .RB \[lq] it \[rq],
3587 but lines interrupted with the
3588 .B \[rs]c
3589 escape sequence do not apply to the line count.
3590 .
3591 .
3592 .TP
3593 .BR .kern\~ [\c
3594 .IR b ]
3595 Enable or disable pairwise kerning of glyphs in the environment per
3596 Boolean expression
3597 .IR b .
3598 .
3599 It is enabled by default,
3600 and if
3601 .I b
3602 is omitted.
3603 .
3604 .
3605 .TP
3606 .BI .length\~ reg\~\c
3607 .RB [[ \[dq] ]\c
3608 .IR contents ]
3609 Compute the number of characters in
3610 .I contents
3611 and store the count in the register
3612 .IR reg .
3613 .
3614 If
3615 .I reg
3616 doesn't exist,
3617 GNU
3618 .I troff \" GNU
3619 creates it.
3620 .
3621 .
3622 .IP
3623 .I Caution:
3624 If you interpolate a macro or diversion in
3625 .I contents
3626 (see section \[lq]Punning Names\[rq] in
3627 .MR groff 7 ),
3628 the
3629 .B length
3630 request counts characters
3631 (or nodes)
3632 only up to the first newline,
3633 and leaves the rest on the input stream.
3634 .
3635 In conventional circumstances,
3636 that means the remainder is interpreted,
3637 and may be formatted.
3638 .
3639 To discover the length of any
3640 string,
3641 macro,
3642 or diversion,
3643 use the
3644 .B pm
3645 request.
3646 .
3647 See section \[lq]Debugging\[rq] below.
3648 .
3649 .
3650 .TP
3651 .BR .linetabs\~ [\c
3652 .IR b ]
3653 Activate or deactivate line-tabs in the environment per Boolean
3654 expression
3655 .IR b .
3656 .
3657 They are inactive by default,
3658 and activated if
3659 .I b
3660 is omitted.
3661 .
3662 When line-tabs are active,
3663 tab stops are computed relative to the start of the pending output line
3664 instead of the drawing position corresponding to the start of the input
3665 line.
3666 .
3667 .
3668 .TP
3669 .BR .lsm\~ [\c
3670 .IR name ]
3671 Set a leading space trap,
3672 calling the macro
3673 .I name
3674 when GNU
3675 .I troff \" GNU
3676 encounters leading spaces on a text line;
3677 the implicit line break that normally happens in this case
3678 is suppressed.
3679 .
3680 The formatter stores the count of leading spaces on the text line
3681 in register
3682 .BR lsn ,
3683 and the amount of corresponding horizontal motion
3684 in register
3685 .BR lss ,
3686 irrespective of whether a leading space trap is set.
3687 .
3688 When it is,
3689 GNU
3690 .I troff \" GNU
3691 removes the leading spaces from the input line
3692 and produces no motion before calling
3693 .IR name .
3694 .
3695 .
3696 .IP
3697 If no argument is supplied,
3698 GNU
3699 .I troff \" GNU
3700 re\[e ad]stablishes the default handling of leading spaces on text lines
3701 (breaking the line when filling,
3702 and formatting a horizontal motion of
3703 .B \[rs]n[lsn]
3704 word spaces).
3705 .
3706 .
3707 .TP
3708 .BR .mso\~ [ \[dq] ]\c
3709 .I file
3710 As
3711 .RB \[lq] so \[rq],
3712 except that GNU
3713 .I troff \" GNU
3714 searches for the specified
3715 .I file
3716 in the same directories as macro files;
3717 see
3718 .I GROFF_TMAC_PATH
3719 in section \[lq]Environment\[rq] of
3720 .MR groff 1
3721 and
3722 .B \-m
3723 in section \[lq]Options\[rq]
3724 of the same page.
3725 .
3726 If
3727 .I file
3728 does not exist or is not readable,
3729 a warning in category
3730 .RB \[lq] file \[rq]
3731 is emitted
3732 and the request has no other effect.
3733 .
3734 .
3735 .TP
3736 .BR .msoquiet\~ [ \[dq] ]\c
3737 .I file
3738 As
3739 .BR mso ,
3740 but no warning is emitted if
3741 .I file
3742 does not exist.
3743 .
3744 .
3745 .TP
3746 .BR .nop \~[\c
3747 .IR input ]
3748 Interpret
3749 .I input
3750 as if it were an input line.
3751 .
3752 .B nop
3753 resembles
3754 .RB \[lq] ".if 1" \[rq];
3755 it puts a break on the output if
3756 .I input
3757 is empty.
3758 .
3759 Unlike
3760 .RB \[lq]\| if \|\[rq],
3761 it cannot govern conditional blocks.
3762 .
3763 Its application is to maintain consistent indentation within macro
3764 definitions even when formatting output.
3765 .
3766 .
3767 .TP
3768 .B .nroff
3769 Make the
3770 .B n
3771 conditional expression evaluate true and
3772 .B t
3773 false.
3774 .
3775 See
3776 .BR troff .
3777 .
3778 .
3779 .TP
3780 .BI .open\~ "ident\~\c
3781 .RB [ \[dq] ]\c
3782 .I file
3783 Open
3784 .I file
3785 for writing and associate a stream named
3786 .I ident
3787 with it,
3788 making it available for
3789 .RB \[lq] write \[rq]
3790 requests.
3791 .
3792 Unsafe request;
3793 disabled by default.
3794 .
3795 Also see
3796 .B writec
3797 and
3798 .RB \[lq] close \[rq].
3799 .
3800 .TP
3801 .BI .opena\~ "ident\~\c
3802 .RB [ \[dq] ]\c
3803 .I file
3804 As
3805 .RB \[lq] open \[rq],
3806 but appends to
3807 .I file
3808 if it already exists instead of overwriting it.
3809 .
3810 .
3811 .TP
3812 .BR .output \~[ \[dq] ]\c
3813 .I character-sequence
3814 Emit
3815 .IR character-sequence ,
3816 transparently to
3817 GNU
3818 .I troff \" GNU
3819 output;
3820 this usage is similar to that of
3821 .B \[rs]!\&
3822 when it occurs in the top-level diversion.
3823 .
3824 .
3825 .TP
3826 .BI .pchar\~ c\~\c
3827 \&.\|.\|.
3828 Report,
3829 to the standard error stream,
3830 information about each character
3831 (be it
3832 ordinary,
3833 special,
3834 or indexed)
3835 .RI "or character class\~" c .
3836 .
3837 A character defined by a request
3838 .RB ( char ,
3839 .BR \%fchar ,
3840 .BR \%fschar ,
3841 or
3842 .BR \%schar )
3843 reports its contents as a JSON-encoded string,
3844 but the output is not otherwise in JSON format.
3845 .
3846 .
3847 .TP
3848 .BR .pcolor \~[\c
3849 .IR col \~\&.\|.\|.]
3850 Report,
3851 to the standard error stream,
3852 each defined color named
3853 .IR col ,
3854 its color space identifier,
3855 and channel value assignments,
3856 or,
3857 without arguments,
3858 those of all defined colors.
3859 .
3860 A device's default stroke and/or fill colors,
3861 \[lq]default\[rq],
3862 are not listed since they are immutable and their details unknown to the
3863 formatter.
3864 .
3865 .
3866 .TP
3867 .B .pcomposite
3868 Report,
3869 to the standard error stream,
3870 the list of configured composite character mappings.
3871 .
3872 See
3873 .RB \%\[lq] composite \[rq]
3874 above.
3875 .
3876 The \[lq]from\[rq] code point is listed first,
3877 followed by its \[lq]to\[rq] mapping.
3878 .
3879 .
3880 .TP
3881 .B .pev
3882 Report the state of the current environment followed by that of all
3883 other environments to the standard error stream.
3884 .
3885 .
3886 .TP
3887 .B .pfp
3888 Report,
3889 to the standard error stream,
3890 the list of occupied font mounting positions.
3891 .\" Recall the @code{fp} request description in @ref{Selecting Fonts}.
3892 .
3893 Occupied mounting positions are listed,
3894 one per line,
3895 in increasing order,
3896 followed by the typeface name;
3897 if the name corresponds to an abstract style,
3898 the entry ends there.
3899 .
3900 Otherwise,
3901 the name of the font description file
3902 and the font's \[lq]internal name\[rq] datum,
3903 the meaning of which varies by output device,
3904 follow.
3905 .
3906 .
3907 .TP
3908 .B .pftr
3909 Report,
3910 to the standard error stream,
3911 the list of font translations.
3912 .
3913 See
3914 .B pftr
3915 above.
3916 .
3917 The \[lq]from\[rq] font identifier is listed first,
3918 followed by its \[lq]to\[rq] translation.
3919 .
3920 .
3921 .TP
3922 .B .phw
3923 Report,
3924 to the standard error stream,
3925 the list of hyphenation exception words
3926 associated with the hyphenation language
3927 selected by the
3928 .B hla
3929 request.
3930 .
3931 A
3932 .RB \[lq] \- \[rq]
3933 marks each hyphenation point.
3934 .
3935 A word prefixed with
3936 .RB \[lq] \- \[rq]
3937 is not hyphenated at all.
3938 .
3939 The report suffixes words
3940 to which automatic hyphenation applies
3941 (meaning those defined in a hyphenation pattern file
3942 rather than with the
3943 .B hw
3944 request)
3945 with a tab and asterisk
3946 .RB \[lq] * \[rq].
3947 .
3948 .
3949 .TP
3950 .B .pline
3951 Report,
3952 in JSON syntax to the standard error stream,
3953 the list of output nodes corresponding to the pending output line.
3954 .
3955 In JSON,
3956 a pair of empty brackets
3957 .RB \[lq] "[ ]" \[rq]
3958 represents an empty list.
3959 .
3960 A
3961 .I pending
3962 output line has not yet undergone adjustment,
3963 and lacks a line number and margin character
3964 (all as applicable).
3965 .
3966 .
3967 .TP
3968 .BR .pnr \~[\c
3969 .IR reg \~.\|.\|.]
3970 Report the name and value and,
3971 if its type is numeric,
3972 the autoincrement amount and assigned format of each register
3973 .IR reg ,
3974 or,
3975 without arguments,
3976 those of all defined registers,
3977 to the standard error stream.
3978 .
3979 .
3980 .TP
3981 .BI .psbb \~file
3982 Get the bounding box of a PostScript image
3983 .IR file .
3984 .
3985 This file must conform to Adobe's Document Structuring Conventions;
3986 the request attempts to extract the bounding box values from a
3987 .B \%%%BoundingBox
3988 comment.
3989 .
3990 After invocation,
3991 the
3992 .I x
3993 and
3994 .I y
3995 coordinates
3996 (in PostScript units)
3997 of the lower left and upper right corners can be found in the registers
3998 .BR \[rs]n[llx] ,
3999 .BR \[rs]n[lly] ,
4000 .BR \[rs]n[urx] ,
4001 and
4002 .BR \[rs]n[ury] ,
4003 respectively.
4004 .
4005 If an error occurs,
4006 these four registers are set to zero.
4007 .
4008 .
4009 .TP
4010 .BR .pso\~ [ \[dq] ]\c
4011 .I command
4012 As
4013 .RB \[lq] so \[rq],
4014 except that input comes from the standard output stream of
4015 .IR command ,
4016 which is passed to
4017 .MR popen 3 .
4018 .
4019 .
4020 .TP
4021 .B .pstream
4022 Report,
4023 in
4024 JSON
4025 syntax to the standard error stream,
4026 the list of open streams,
4027 including the name of each open stream,
4028 the name of the file backing it,
4029 and its mode
4030 (writing or appending).
4031 .
4032 .
4033 .TP
4034 .B .pwh
4035 Report the names and vertical positions,
4036 in basic units,
4037 of all page location traps
4038 to the standard error stream.
4039 .
4040 GNU
4041 .I troff \" GNU
4042 reports empty slots in the list,
4043 where a trap had been planted
4044 but subsequently (re)moved,
4045 because they can affect the visibility of subsequently planted traps.
4046 .
4047 .
4048 .TP
4049 .BI .pvs \~\[+-]n
4050 Set the post-vertical line spacing
4051 .RI to\~ n ;
4052 default scaling unit
4053 .RB is\~\[lq] p \[rq].
4054 .
4055 With no argument,
4056 the post-vertical line space is set to its previous value.
4057 .
4058 .
4059 .IP
4060 In GNU
4061 .IR troff , \" GNU
4062 the distance between text baselines consists of the extra pre-vertical
4063 line spacing set by the most negative
4064 .B \[rs]x
4065 argument on the pending output line,
4066 the vertical spacing
4067 .RB ( vs ),
4068 the extra post-vertical line spacing set by the most positive
4069 .B \[rs]x
4070 argument on the pending output line,
4071 and the post-vertical line spacing set by this request.
4072 .
4073 .
4074 .TP
4075 .BI .rchar\~ c\c
4076 \&.\|.\|.
4077 Remove definition of each
4078 ordinary,
4079 special,
4080 or
4081 indexed
4082 character
4083 .IR c ,
4084 undoing the effect of a
4085 .BR char ,
4086 .BR \%fchar ,
4087 or
4088 .B \%schar
4089 request.
4090 .
4091 Spaces need not separate
4092 .I c
4093 arguments.
4094 .\" XXX: Removal of a class is unspecified.
4095 .
4096 The character definition removed
4097 (if any)
4098 is the first encountered in the resolution process documented
4099 in section \[lq]Using Symbols\[rq] of
4100 .IR "Groff: The GNU Implementation of troff" .
4101 .\" TODO: Get that information into this man page!
4102 .
4103 Glyphs,
4104 which are defined by font description files,
4105 cannot be removed.
4106 .
4107 .
4108 .TP
4109 .BR .return\~ [\c
4110 .IR input ]
4111 .\" XXX: useless request warning if not interpreting a macro?
4112 Stop interpreting an interpolated macro,
4113 skipping to the end of its definition.
4114 .
4115 Do not confuse
4116 .RB \[lq] return \[rq]
4117 with
4118 .BR rt .
4119 .
4120 If called with an argument
4121 .I input,
4122 GNU
4123 .I troff \" GNU
4124 performs the skip twice\[em]once within the macro being interpreted
4125 and once in an enclosing macro,
4126 permitting a macro to wrap the request
4127 (as
4128 .I trace\:.tmac
4129 does).
4130 .
4131 .
4132 .
4133 .TP
4134 .BI .rfschar\~ "f c\~"\c
4135 \&.\|.\|.
4136 Remove each fallback special
4137 .RI character\~ c
4138 for font
4139 .IR f .
4140 .
4141 Spaces need not separate
4142 .I c
4143 arguments.
4144 .
4145 See
4146 .BR fschar .
4147 .
4148 .
4149 .TP
4150 .BR .rj\~ [\c
4151 .IR n ]
4152 Break,
4153 right-align the
4154 .RI next\~ n
4155 (default: 1)
4156 input lines,
4157 then break again.
4158 .
4159 .B rj
4160 implies
4161 .RB \[lq] ".ce 0" \[rq],
4162 and
4163 .B ce
4164 implies
4165 .RB \[lq] ".rj 0" \[rq].
4166 .
4167 Invoking the request
4168 with the no-break control character
4169 suppresses the first break.
4170 .
4171 .
4172 .TP
4173 .BI .rnn \~r1\~r2
4174 Rename register
4175 .I r1
4176 to
4177 .IR r2 .
4178 .
4179 If
4180 .I r1
4181 doesn't exist,
4182 the request is ignored.
4183 .
4184 .
4185 .TP
4186 .BI .schar\~ c\~\c
4187 .RB [[ \[dq] ]\c
4188 .IR contents ]
4189 Define global fallback character
4190 .I c
4191 as
4192 .IR contents .
4193 .
4194 As
4195 .BR char ,
4196 but GNU
4197 .I troff \" GNU
4198 locates a character defined with
4199 .B schar
4200 after any fonts named as arguments to the
4201 .RB \%\[lq] special \[rq]
4202 request and before any mounted special fonts.
4203 .
4204 .
4205 .TP
4206 .BR .shc \~\c
4207 .RI [ c ]
4208 Set the soft hyphen character,
4209 inserted when a word is hyphenated automatically or at a hyphenation
4210 character,
4211 .RI to\~ c .
4212 .
4213 If
4214 .I c
4215 is omitted,
4216 the soft hyphen character is set to the default,
4217 .BR \[rs][hy] .
4218 .
4219 If the selected glyph does not exist in the font in use at a potential
4220 hyphenation point,
4221 then the line is not broken at that point.
4222 .
4223 Neither character definitions
4224 .RB ( char
4225 and similar)
4226 nor translations
4227 .RB ( tr
4228 and similar)
4229 are considered when assigning the soft hyphen character.
4230 .
4231 .
4232 .TP
4233 .BR .shift\~ [\c
4234 .IR n ]
4235 .\" XXX: useless request warning if not interpreting a macro or string?
4236 Shift macro or string parameters
4237 .I n
4238 places
4239 (by\~1 if
4240 .I n
4241 omitted):
4242 .RI argument\~ i
4243 becomes argument
4244 .IR i \|\-\| n ;
4245 arguments 1
4246 .RI to\~ n
4247 become unavailable.
4248 .
4249 Shifting by a non-positive amount,
4250 or outside of a macro or string definition,
4251 performs no operation.
4252 .
4253 The register
4254 .B .$
4255 adjusts its value accordingly.
4256 .
4257 .
4258 .TP
4259 .BI .sizes\~ "s1 s2\~"\c
4260 .RI .\|.\|.\~ sn\~\c
4261 .RB [ 0 ]
4262 Set the available type sizes to
4263 .IR s1 ,
4264 .IR s2 ,
4265 \&.\|.\|.\&
4266 .I sn
4267 scaled points.
4268 .
4269 The list of sizes can be terminated by an
4270 .RB optional\~\[lq] 0 \[rq].
4271 .
4272 Each
4273 .I si
4274 can also be a range
4275 .IR m \(en n .
4276 .
4277 In contrast to the device description file directive of the same name
4278 (see
4279 .MR groff_font 5 ),
4280 the argument list can't extend over more than one line.
4281 .
4282 .
4283 .TP
4284 .BR .soquiet\~ [ \[dq] ]\c
4285 .I file
4286 As
4287 .RB \[lq] so \[rq],
4288 but no warning is emitted if
4289 .I file
4290 does not exist.
4291 .
4292 .
4293 .TP
4294 .BR .special\~ [\c
4295 .IR s\~ .\|.\|.]
4296 Declare each font
4297 .I s
4298 as special,
4299 irrespective of its description file,
4300 populating a list that
4301 GNU
4302 .I troff \" GNU
4303 searches,
4304 in order,
4305 to find the glyph demanded.
4306 .
4307 GNU
4308 .I troff \" GNU
4309 mounts each font
4310 .I s.
4311 .
4312 Invoking
4313 .B \%special
4314 without arguments empties the list.
4315 .
4316 A font is not automatically unmounted
4317 if a subsequent
4318 .B \%special
4319 request removes it from the list.
4320 .
4321 Initially,
4322 the list is empty.
4323 .
4324 .\" TODO: Move this sentence to a new section description the glyph
4325 .\" resolution procedure.
4326 GNU
4327 .I troff \" GNU
4328 searches fonts specified as arguments to the
4329 .RB \%\[lq] special \[rq]
4330 request after those given as arguments to the
4331 .B \%fspecial
4332 request.
4333 .
4334 .
4335 .TP
4336 .BR .spreadwarn\~ [\c
4337 .IR limit ]
4338 Emit a
4339 .RB \[lq] break \[rq]
4340 warning if the additional space inserted for each space between words in
4341 an output line adjusted to both margins with
4342 .RB \[lq] .ad\~b \[rq]
4343 is larger than or equal to
4344 .IR limit .
4345 .
4346 A negative value is treated as zero;
4347 an absent argument toggles the warning on and off without changing
4348 .IR limit .
4349 .
4350 The default scaling unit is
4351 .BR m .
4352 .
4353 At startup,
4354 .B spreadwarn
4355 is inactive and
4356 .I limit
4357 is 3\~m.
4358 .
4359 .
4360 .IP
4361 For example,
4362 .RB \[lq] ".spreadwarn 0.2m" \[rq]
4363 warns if
4364 .I \%troff
4365 must add 0.2\~m or more to each inter-word space in a line.
4366 .
4367 .
4368 .TP
4369 .BI .stringdown \~str
4370 .TQ
4371 .BI .stringup \~str
4372 Alter the string named
4373 .I str
4374 by replacing each of its bytes with its
4375 lowercase
4376 .RB ( down )
4377 or uppercase
4378 .RB ( up )
4379 version
4380 (if one exists).
4381 .
4382 Special characters
4383 (see
4384 .MR groff_char 7 )
4385 will often transform in the expected way due to the regular naming
4386 convention for accented characters.
4387 .
4388 When they do not,
4389 use substrings and/or catenation.
4390 .
4391 .
4392 .TP
4393 .BI .sty\~ "pos style"
4394 Associate abstract
4395 .I style
4396 with non-negative font mounting
4397 .RI position\~ pos .
4398 .
4399 .
4400 .TP
4401 .BI .substring\~ "str start\~"\c
4402 .RI [ end ]
4403 Replace the string named
4404 .I str
4405 with its substring bounded by the indices
4406 .I start
4407 and
4408 .IR end ,
4409 inclusively.
4410 .
4411 The first character in the string has index\~0.
4412 .
4413 Negative indices count backward from the end of the string:
4414 the last character has index\~\-1,
4415 the character before the last has index\~\-2,
4416 and so on.
4417 .
4418 If
4419 .I end
4420 is omitted,
4421 .B \-1
4422 is implied.
4423 .
4424 .
4425 .TP
4426 .BI .tkf\~ f\~s1\~n1\~s2\~n2
4427 Enable track kerning for font\~\c
4428 .IR f .
4429 When the current font is\~\c
4430 .IR f ,
4431 the width of every glyph is increased by an amount between
4432 .I n1
4433 and
4434 .IR n2 ;
4435 when the current type size is less than or equal to
4436 .IR s1 ,
4437 the width is increased by
4438 .IR n1 ;
4439 when it is greater than or equal to
4440 .IR s2 ,
4441 the width is increased by
4442 .IR n2 ;
4443 when the type size is greater than or equal to
4444 .I s1
4445 and less than or equal to
4446 .IR s2 ,
4447 the increase in width is a linear function of the type size.
4448 .
4449 .
4450 .TP
4451 .BR .tm1 \~[[ \[dq] ]\c
4452 .IR message ]
4453 As
4454 .BR tm ,
4455 but
4456 removes a leading neutral double quote
4457 .RB \[oq] \[dq] \[cq]
4458 from
4459 .IR message ,
4460 permitting initial embedded spaces in it.
4461 .
4462 .
4463 .TP
4464 .BR .tmc \~[[ \[dq] ]\c
4465 .IR message ]
4466 As
4467 .BR tm1 ,
4468 but does not append a newline.
4469 .
4470 .
4471 .TP
4472 .BI .trf\~ file
4473 Break and copy
4474 .I file
4475 as \[lq]throughput\[rq] to GNU
4476 .I troff \" GNU
4477 output,
4478 discarding characters that are invalid as input;
4479 contrast with
4480 .BR cf .
4481 .
4482 Each line of
4483 .I file
4484 is output as if preceded by
4485 .BR \[rs]! ,
4486 but is not interpreted by the formatter.
4487 .
4488 If
4489 .I file
4490 does not end with a newline,
4491 .B trf
4492 appends one.
4493 .
4494 Invoking the request
4495 with the no-break control character
4496 suppresses the break.
4497 .
4498 .
4499 .TP
4500 .BI .trin\~ abcd
4501 As the
4502 .B tr
4503 request,
4504 but the
4505 .B \%asciify
4506 request uses the character code
4507 (if any)
4508 before the character translation.
4509 .
4510 .
4511 .TP
4512 .BI .trnt\~ abcd
4513 As the
4514 .B tr
4515 request,
4516 but the translations do not apply to text that is
4517 transparently throughput into a diversion with
4518 .BR \[rs]! .
4519 .
4520 .
4521 .TP
4522 .B .troff
4523 Make the
4524 .B t
4525 conditional expression evaluate true and
4526 .B n
4527 false.
4528 .
4529 See
4530 .BR nroff .
4531 .
4532 .
4533 .br
4534 .ne 5v
4535 .TP
4536 .BI .unformat\~ div
4537 Unformat the diversion
4538 .IR div .
4539 .
4540 Unlike
4541 .BR \%asciify ,
4542 .RB \%\[lq] unformat \[rq]
4543 handles only tabs and spaces between words,
4544 the latter usually arising from spaces or newlines in the input.
4545 .
4546 Tabs are treated as input tokens,
4547 and spaces become adjustable again.
4548 .
4549 The vertical sizes of lines are not preserved,
4550 but glyph information
4551 (font,
4552 type size,
4553 space width,
4554 and so on)
4555 is retained.
4556 .
4557 .
4558 .TP
4559 .BR .vpt\~ [\c
4560 .IR b ]
4561 Enable or disable vertical position traps per Boolean expression
4562 .IR b .
4563 .
4564 They are enabled by default,
4565 and if
4566 .I b
4567 is omitted.
4568 .
4569 Vertical position traps are those set by the
4570 .BR ch ,
4571 .BR wh ,
4572 and
4573 .B dt
4574 requests.
4575 .
4576 Vertical position trap enablement is global.
4577 .
4578 .
4579 .TP
4580 .BR .warn\~ [\c
4581 .IR n ]
4582 Select categories of warnings to be reported.
4583 .
4584 .IR n \~is
4585 the sum of the numeric codes associated with each warning category that
4586 is to be enabled;
4587 all other categories are disabled.
4588 .
4589 The categories and their associated codes are listed in section
4590 \[lq]Warnings\[rq] of
4591 .MR \%troff 1 .
4592 .\" TODO: Maybe move that table to groff(7).
4593 .
4594 For example,
4595 .RB \[lq] ".warn 0" \[rq]
4596 disables all warnings,
4597 and
4598 .RB \[lq] ".warn 1" \[rq]
4599 disables all warnings except those about missing glyphs.
4600 .
4601 If no argument is given,
4602 all warning categories are enabled.
4603 .
4604 .
4605 .TP
4606 .BI .warnscale\~ scaling-unit
4607 Select scaling unit used in certain warnings \" `output_warning()`
4608 (one of
4609 .BR u ,
4610 .BR i ,
4611 .BR c ,
4612 .BR p ,
4613 or
4614 .BR P ;
4615 default:
4616 .BR i ).
4617 .
4618 Ignored on
4619 .IR nroff -mode
4620 output devices,
4621 for which these diagnostics report the vertical page location in lines,
4622 and the horizontal page location in ens.
4623 .
4624 .
4625 .TP
4626 .BI .while \~cond-expr\~input
4627 Evaluate the conditional expression
4628 .IR cond-expr ,
4629 and repeatedly execute
4630 .I input
4631 unless and until
4632 .I cond-expr
4633 evaluates false.
4634 .
4635 .I input,
4636 which is often a conditional block,
4637 is referred to as the
4638 .RB \[lq] while \[rq]
4639 request's
4640 .I body.
4641 .
4642 .
4643 .IP
4644 GNU
4645 .I troff \" GNU
4646 treats the body of a
4647 .RB \[lq] while \[rq]
4648 request similarly to that of a
4649 .B de
4650 request
4651 (albeit one not read in copy mode),
4652 but stores it under an internal name
4653 and deletes it when the loop finishes.
4654 .
4655 The operation of a macro containing a
4656 .RB \[lq] while \[rq]
4657 request can slow significantly if its
4658 body is large.
4659 .
4660 Each time
4661 GNU
4662 .I troff \" GNU
4663 interpolates the macro,
4664 it parses and stores the
4665 .RB \[lq] while \[rq]
4666 body again.
4667 .
4668 An often better solution\[em]and one that is more portable,
4669 since AT&T
4670 .I troff \" AT&T
4671 lacked the
4672 .RB \[lq] while \[rq]
4673 request\[em]is to instead write a recursive macro,
4674 which is parsed only once
4675 (unless you redefine it).
4676 .
4677 To prevent infinite loops,
4678 GNU
4679 .I troff \" GNU
4680 limits the default number of available recursion levels
4681 to 1,000 or somewhat less
4682 (because things other than macro calls can be on the input stack).
4683 .
4684 You can disable this protective measure,
4685 or alter the limit,
4686 by setting the
4687 .B slimit
4688 register.
4689 .
4690 See section \[lq]Debugging\[rq] below.
4691 .
4692 .
4693 .IP
4694 If a
4695 .RB \[lq] while \[rq]
4696 body begins with a conditional block,
4697 its closing brace must end an input line.
4698 .
4699 .
4700 .IP
4701 The
4702 .RB \[lq] break \[rq]
4703 and
4704 .RB \[lq] continue \[rq]
4705 requests alter a
4706 .RB \[lq] while \[rq]
4707 loop's flow of control.
4708 .
4709 .
4710 .TP
4711 .BI .write\~ stream\~\c
4712 .RB [[ \[dq] ]\c
4713 .IR character-sequence ]
4714 Write
4715 .IR character-sequence ,
4716 a sequence of ordinary characters,
4717 spaces,
4718 or tabs
4719 .\" ...or, technically, backspace and delete characters, but let's not
4720 .\" dwell on that.
4721 read in copy mode,
4722 to
4723 .IR stream ,
4724 which must previously have been the subject of an
4725 .RB \[lq] open \[rq]
4726 (or
4727 .BR opena )
4728 request,
4729 followed by a newline.
4730 .
4731 GNU
4732 .I troff \" GNU
4733 flushes the stream after writing to it.
4734 .
4735 .
4736 .TP
4737 .BI .writec\~ stream\~\c
4738 .RB [[ \[dq] ]\c
4739 .IR character-sequence ]
4740 As
4741 .RB \[lq] write \[rq],
4742 but does not append a newline to
4743 .IR contents .
4744 .
4745 .
4746 .TP
4747 .BI .writem\~ "stream name"
4748 Write the contents of the macro or string
4749 .I name
4750 to
4751 .IR stream ,
4752 which must previously have been the subject of an
4753 .RB \[lq] open \[rq]
4754 (or
4755 .BR opena )
4756 request.
4757 .
4758 GNU
4759 .I troff \" GNU
4760 reads the contents of
4761 .I name
4762 in copy mode.
4763 .
4764 .
4765 .br
4766 .ne 4v
4767 .\" ====================================================================
4768 .SS "Altered registers"
4769 .\" ====================================================================
4770 .
4771 GNU
4772 .I troff \" GNU
4773 alters the semantics of two
4774 AT&T
4775 .I troff \" AT&T
4776 registers
4777 and imparts semantics to two others
4778 that CSTR\~#54 documented as \[lq]reserved\[rq].
4779 .
4780 .
4781 .TP
4782 .B \[rs]n[.R]
4783 Because GNU
4784 .I troff \" GNU
4785 dynamically manages register storage,
4786 it repurposes the
4787 .B .R
4788 register
4789 to interpolate the maximum integer representable in the formatter.
4790 .
4791 Favor its use over numeric literals with many zeroes or nines
4792 to indicate an arbitrary large quantity.
4793 .
4794 .
4795 .TP
4796 .B \[rs]n[.s]
4797 In GNU
4798 .IR troff , \" GNU
4799 the
4800 .B .s
4801 register is string-valued;
4802 it interpolates the type size in typographical points,
4803 which can be represented as a decimal fraction.
4804 .
4805 .
4806 .TP
4807 .B \[rs]n[.x]
4808 Interpolate major version number of the running
4809 .I \%troff
4810 formatter.
4811 .
4812 For example,
4813 if the version number is 1.23.0,
4814 then
4815 .B \[rs]n[.x]
4816 contains\~1.
4817 .
4818 .
4819 .TP
4820 .B \[rs]n[.y]
4821 Interpolate minor version number of the running
4822 .I \%troff
4823 formatter.
4824 .
4825 For example,
4826 if the version number is 1.23.0,
4827 then
4828 .B \[rs]n[.y]
4829 contains\~23.
4830 .
4831 Also see
4832 .B \[rs]n[.Y]
4833 below.
4834 .
4835 .
4836 .\" ====================================================================
4837 .SS "New registers"
4838 .\" ====================================================================
4839 .
4840 GNU
4841 .I troff \" GNU
4842 exposes more formatter state via many new read-only registers.
4843 .
4844 Their names often correspond to the requests that affect them.
4845 .
4846 .
4847 .TP 14n \" "\n[.hydefault]" + 2n
4848 .B \[rs]n[.br]
4849 Within a macro definition,
4850 interpolate\~1
4851 if the macro is called with the \[lq]normal\[rq] control character
4852 (\[lq].\[rq] by default),
4853 and\~0 otherwise.
4854 .
4855 This facility allows requests to be reliably wrapped by a macro.
4856 .
4857 Interpolating the
4858 .B .br
4859 register outside of a macro definition makes no sense.
4860 .
4861 .
4862 .TP
4863 .B \[rs]n[.C]
4864 Interpolate 1\~if AT&T
4865 .I troff \" AT&T
4866 compatibility mode is in effect,
4867 0\~otherwise.
4868 .
4869 See
4870 .BR cp .
4871 .
4872 .
4873 .TP
4874 .B \[rs]n[.cdp]
4875 Interpolate depth of last glyph added to the environment.
4876 .
4877 It is positive if the glyph extends below the baseline.
4878 .
4879 .
4880 .TP
4881 .B \[rs]n[.ce]
4882 Interpolate count of input lines remaining to be centered
4883 in the environment.
4884 .
4885 .
4886 .TP
4887 .B \[rs]n[.cht]
4888 Interpolate height of last glyph added to the environment.
4889 .
4890 It is positive if the glyph extends above the baseline.
4891 .
4892 .
4893 .TP
4894 .B \[rs]n[.color]
4895 Interpolate 1\~if color output is enabled,
4896 0\~otherwise.
4897 .
4898 .
4899 .TP
4900 .B \[rs]n[.cp]
4901 Within a
4902 .RB \[lq] do \[rq]
4903 request,
4904 interpolate the saved value of compatibility mode
4905 (see
4906 .B \[rs]n[.C]
4907 above).
4908 .
4909 .
4910 .TP
4911 .B \[rs]n[.csk]
4912 Interpolate skew of last glyph added to the environment.
4913 .
4914 The
4915 .I skew
4916 of a glyph is how far to the right of the center of a glyph the center
4917 of an accent over that glyph is to be placed.
4918 .
4919 .
4920 .TP
4921 .B \[rs]n[.ev]
4922 Interpolate name of current environment.
4923 .
4924 This is a string-valued register.
4925 .
4926 .
4927 .TP
4928 .B \[rs]n[.fam]
4929 Interpolate name of the environment's default font family.
4930 .
4931 This is a string-valued register.
4932 .
4933 .
4934 .TP
4935 .B \[rs]n[.fn]
4936 Interpolate resolved name of the font selected in the environment.
4937 .
4938 This is a string-valued register.
4939 .
4940 .
4941 .TP
4942 .B \[rs]n[.fp]
4943 Interpolate next free non-zero font mounting position.
4944 .
4945 .
4946 .TP
4947 .B \[rs]n[.g]
4948 Interpolate\~1.
4949 .
4950 Test with
4951 .RB \[lq]\| if \|\[rq]
4952 or
4953 .B ie
4954 to check whether GNU
4955 .I troff \" GNU
4956 is the formatter.
4957 .
4958 .
4959 .TP
4960 .B \[rs]n[.height]
4961 Interpolate the rescaled height
4962 of the environment's selected font,
4963 in scaled points.
4964 .
4965 It is zero if the font height is not rescaled.
4966 .
4967 See
4968 .BR \[rs]H .
4969 .
4970 .
4971 .TP
4972 .B \[rs]n[.hla]
4973 Interpolate hyphenation language of the environment.
4974 .
4975 This is a string-valued register.
4976 .
4977 .
4978 .TP
4979 .B \[rs]n[.hlc]
4980 Interpolate count of immediately preceding consecutive hyphenated lines
4981 in the environment.
4982 .
4983 .
4984 .TP
4985 .B \[rs]n[.hlm]
4986 Interpolate maximum number of consecutive hyphenated lines allowed in
4987 the environment.
4988 .
4989 .
4990 .TP
4991 .B \[rs]n[.hy]
4992 Interpolate automatic hyphenation mode of the environment.
4993 .
4994 .
4995 .TP
4996 .B \[rs]n[.hydefault]
4997 Interpolate hyphenation mode default of the environment.
4998 .
4999 .
5000 .TP
5001 .B \[rs]n[.hym]
5002 Inteprolate hyphenation margin of the environment.
5003 .
5004 .
5005 .TP
5006 .B \[rs]n[.hys]
5007 Interpolate hyphenation space adjustment threshold of the environment.
5008 .
5009 .
5010 .TP
5011 .B \[rs]n[.in]
5012 Interpolate indentation amount applicable to the output line pending
5013 in the environment.
5014 .
5015 .
5016 .TP
5017 .B \[rs]n[.int]
5018 Interpolate\~1 if the text most recently formatted in the environment
5019 was \[lq]interrupted\[rq] or continued with
5020 .BR \[rs]c ,
5021 0\~otherwise.
5022 .
5023 .
5024 .TP
5025 .B \[rs]n[.it]
5026 Interpolate count of input lines remaining
5027 in the environment's pending input trap.
5028 .
5029 .
5030 .TP
5031 .B \[rs]n[.itc]
5032 Interpolate\~1 if the environment's pending input trap honors
5033 the output line continuation escape sequence
5034 .RB ( \[rs]c ),
5035 0\~otherwise.
5036 .
5037 .
5038 .TP
5039 .B \[rs]n[.itm]
5040 Interpolate the name of the macro associated with the environment's
5041 pending input trap.
5042 .
5043 This is a string-valued register.
5044 .
5045 .
5046 .TP
5047 .B \[rs]n[.kern]
5048 Interpolate\~1 if pairwise kerning is enabled,
5049 0\~otherwise.
5050 .
5051 .
5052 .TP
5053 .B \[rs]n[.lg]
5054 Interpolate ligature mode.
5055 .
5056 .
5057 .TP
5058 .B \[rs]n[.linetabs]
5059 Interpolate\~1 if line-tabs mode is enabled in the environment,
5060 0\~otherwise.
5061 .
5062 .
5063 .TP
5064 .B \[rs]n[.ll]
5065 Interpolate line length applicable to the environment's
5066 pending output line.
5067 .
5068 .
5069 .TP
5070 .B \[rs]n[.lt]
5071 Interpolate the environment's title line length.
5072 .
5073 .
5074 .TP
5075 .B \[rs]n[.m]
5076 Interpolate name of the environment's selected stroke color.
5077 .
5078 This is a string-valued register.
5079 .
5080 .
5081 .TP
5082 .B \[rs]n[.M]
5083 Interpolate name of the environment's selected fill color.
5084 .
5085 This is a string-valued register.
5086 .
5087 .
5088 .TP
5089 .B \[rs]n[.ne]
5090 Interpolate amount of space demanded by the most recent
5091 .B ne
5092 request that sprang a page location trap.
5093 .
5094 See
5095 .BR \[rs]n[.trunc] .
5096 .
5097 .
5098 .TP
5099 .B \[rs]n[.nm]
5100 Interpolate\~1 if output line numbering is enabled in the environment
5101 (even if temporarily suppressed),
5102 0\~otherwise.
5103 .
5104 .
5105 .TP
5106 .B \[rs]n[.nn]
5107 Interpolate count of lines remaining in the environment
5108 for which numbering is suppressed
5109 while output line numbering is enabled.
5110 .
5111 .
5112 .TP
5113 .B \[rs]n[.ns]
5114 Interpolate\~1 if no-space mode is enabled,
5115 0\~otherwise.
5116 .
5117 .
5118 .TP
5119 .B \[rs]n[.O]
5120 Interpolate output suppression level.
5121 .
5122 See
5123 .BR \[rs]O .
5124 .
5125 .
5126 .TP
5127 .B \[rs]n[.P]
5128 Interpolate\~1 if the current page is selected for output,
5129 0\~otherwise.
5130 .
5131 See
5132 .B \-o
5133 command-line option to
5134 .MR \%troff 1 .
5135 .
5136 .
5137 .TP
5138 .B \[rs]n[.pe]
5139 Interpolate\~1 during page ejection,
5140 0\~otherwise.
5141 .
5142 .
5143 .TP
5144 .B \[rs]n[.pn]
5145 Interpolate next page number
5146 (either that set by
5147 .BR pn ,
5148 or that of the current page plus\~1).
5149 .
5150 .
5151 .TP
5152 .B \[rs]n[.ps]
5153 Interpolate the environment's type size in scaled points.
5154 .
5155 .
5156 .TP
5157 .B \[rs]n[.psr]
5158 Interpolate the environment's most recently requested type size
5159 in scaled points.
5160 .
5161 .
5162 .TP
5163 .B \[rs]n[.pvs]
5164 Interpolate the environment's post-vertical line spacing amount.
5165 .
5166 .
5167 .TP
5168 .B \[rs]n[.rj]
5169 Interpolate count of input lines remaining to be right-aligned
5170 in the environment.
5171 .
5172 .
5173 .TP
5174 .B \[rs]n[.slant]
5175 Interpolate slant in degrees of the environment's selected font.
5176 .
5177 See
5178 .BR \[rs]S .
5179 .
5180 .
5181 .TP
5182 .B \[rs]n[.sr]
5183 Interpolate the environment's most recently requested type size
5184 in typographical points.
5185 .
5186 This is a string-valued register.
5187 .
5188 .
5189 .TP
5190 .B \[rs]n[.ss]
5191 .TQ
5192 .B \[rs]n[.sss]
5193 Interpolate values of the environment's minimum inter-word space
5194 and supplemental inter-sentence space,
5195 respectively,
5196 in twelfths of the space width of the selected font.
5197 .
5198 .
5199 .TP
5200 .B \[rs]n[.sty]
5201 Interpolate the environment's selected abstract font style,
5202 if any.
5203 .
5204 This is a string-valued register.
5205 .
5206 .
5207 .TP
5208 .B \[rs]n[.tabs]
5209 Interpolate the environment's tab stop settings
5210 (if any)
5211 in a form suitable for passage to the
5212 .B ta
5213 request.
5214 .
5215 This is a string-valued register.
5216 .
5217 .
5218 .TP
5219 .B \[rs]n[.trap]
5220 Interpolate the name of the next vertical position trap
5221 after the vertical drawing position.
5222 .
5223 This is a string-valued register.
5224 .
5225 .
5226 .TP
5227 .B \[rs]n[.trunc]
5228 Interpolate amount of vertical space truncated by the most recently
5229 sprung page location trap,
5230 or,
5231 if the trap was sprung by an
5232 .B ne
5233 request,
5234 minus the amount of vertical motion produced by the
5235 .B ne
5236 request.
5237 .
5238 In other words,
5239 at the point a trap is sprung,
5240 .B \[rs]n[.trunc]
5241 represents the difference of what the vertical position would have
5242 been but for the trap,
5243 and what the vertical position actually is.
5244 .
5245 See
5246 .BR \[rs]n[.ne] .
5247 .
5248 .
5249 .TP
5250 .B \[rs]n[.U]
5251 Interpolate\~1 if in unsafe mode,
5252 0\~otherwise.
5253 .
5254 See
5255 .B \-U
5256 command-line option to
5257 .MR \%troff 1 .
5258 .
5259 .
5260 .TP
5261 .B \[rs]n[.vpt]
5262 Interpolate\~1 if vertical position traps are enabled,
5263 0\~otherwise.
5264 .
5265 .
5266 .TP
5267 .B \[rs]n[.warn]
5268 Interpolate warning mask.
5269 .
5270 See section \[lq]Warnings\[rq] of
5271 .MR \%troff 1 .
5272 .\" TODO: Maybe move that table to groff(7).
5273 .
5274 .
5275 .TP
5276 .B \[rs]n[.Y]
5277 Interpolate revision number of the running
5278 .I \%troff
5279 formatter.
5280 .
5281 For example,
5282 if the version number is 1.23.0,
5283 then
5284 .B \[rs]n[.Y]
5285 contains\~0.
5286 .
5287 Also see
5288 .B \[rs]n[.x]
5289 and
5290 .B \[rs]n[.y]
5291 above.
5292 .
5293 .
5294 .TP
5295 .B \[rs]n[.zoom]
5296 Interpolate magnification of the environment's selected font,
5297 in thousandths,
5298 or\~0 if magnification unused.
5299 .
5300 See
5301 .BR fzoom .
5302 .
5303 .
5304 .P
5305 The following (writable) registers are set by the
5306 .B psbb
5307 request.
5308 .
5309 .
5310 .TP 9n \" "\n[ury]" + 2n
5311 .B \[rs]n[llx]
5312 .TQ
5313 .B \[rs]n[lly]
5314 .TQ
5315 .B \[rs]n[urx]
5316 .TQ
5317 .B \[rs]n[ury]
5318 Interpolate the
5319 (upper,
5320 lower,
5321 left,
5322 right)
5323 bounding box values
5324 (in PostScript units) of the most recently processed PostScript image.
5325 .
5326 .
5327 .P
5328 The following (writable) registers are set by the
5329 .B \[rs]w
5330 escape sequence.
5331 .
5332 .
5333 .TP 9n \" "\n[ury]" + 2n
5334 .B \[rs]n[rst]
5335 .TQ
5336 .B \[rs]n[rsb]
5337 Like
5338 .B \[rs]n[st]
5339 and
5340 .BR \[rs]n[sb] ,
5341 but taking account of the heights and depths of glyphs.
5342 .
5343 In other words,
5344 these registers store the highest and lowest vertical positions attained
5345 by the argument formatted by the
5346 .B \[rs]w
5347 escape sequence,
5348 doing what AT&T
5349 .I troff \" AT&T
5350 documented
5351 .B \[rs]n[st]
5352 and
5353 .B \[rs]n[sb]
5354 as doing.
5355 .
5356 .
5357 .TP
5358 .B \[rs]n[ssc]
5359 The amount of
5360 (possibly negative)
5361 horizontal space to add to the last glyph before a subscript.
5362 .
5363 .
5364 .TP
5365 .B \[rs]n[skw]
5366 How far to right of the center of the last glyph in the
5367 .B \[rs]w
5368 argument,
5369 to place the center of an accent from a roman font over that glyph.
5370 .
5371 .
5372 .P
5373 Other writable registers are as follows.
5374 .
5375 Those relating to date and time are initialized using
5376 .MR localtime 3
5377 at formatter startup.
5378 .
5379 .
5380 .\" The `c.` register was documented in the January 1981 "Addendum to
5381 .\" the Nroff/Troff User's Manual" (presumably by Kernighan), and is
5382 .\" widely supported by descendants of his device-independent troff, but
5383 .\" appears to have been overlooked in his 1992 revision of CSTR #54.
5384 .TP 12n
5385 .B \[rs]n[c.]
5386 Interpolate input line number.
5387 .
5388 .B \[rs]n[.c]
5389 is a read-only alias of this register.
5390 .
5391 .
5392 .TP
5393 .B \[rs]n[hours]
5394 Interpolate number of hours elapsed since midnight.
5395 .
5396 .
5397 .TP
5398 .\" The `hp` register was documented in the original 1976 Ossanna troff
5399 .\" "Nroff/Troff User's Manual" and in the January 1981 "Addendum to
5400 .\" the Nroff/Troff User's Manual" (presumably by Kernighan), and is
5401 .\" widely supported by descendants of his device-independent troff, but
5402 .\" appears to have been overlooked in his 1992 revision of CSTR #54.
5403 .B \[rs]n[hp]
5404 Interpolate horizontal position relative to that at the start of the
5405 input line.
5406 .
5407 .
5408 .br
5409 .ne 3v
5410 .TP
5411 .B \[rs]n[lsn]
5412 .TQ
5413 .B \[rs]n[lss]
5414 Interpolate count of leading spaces on input line and amount of
5415 corresponding horizontal motion,
5416 respectively.
5417 .
5418 .
5419 .TP
5420 .B \[rs]n[minutes]
5421 Interpolate number of minutes elapsed in the hour.
5422 .
5423 .
5424 .TP
5425 .B \[rs]n[seconds]
5426 Interpolate number of seconds elapsed in the minute.
5427 .
5428 .
5429 .TP
5430 .B \[rs]n[systat]
5431 Interpolate return value of
5432 .MR system 3
5433 function executed by most recent
5434 .B sy
5435 request.
5436 .
5437 .
5438 .TP
5439 .B \[rs]n[slimit]
5440 Interpolates maximum quantity of objects on
5441 .IR \%troff 's
5442 internal input stack
5443 (default: 1000).
5444 .
5445 If non-positive,
5446 there is no limit:
5447 recursion can continue until program memory is exhausted.
5448 .
5449 .
5450 .TP
5451 .B \[rs]n[year]
5452 Interpolate Gregorian year.
5453 .
5454 AT&T
5455 .IR troff 's \" AT&T
5456 .B \[rs]n[yr]
5457 interpolates the Gregorian year minus 1900.
5458 .
5459 .
5460 .\" ====================================================================
5461 .SS Delimiters
5462 .\" ====================================================================
5463 .\" BEGIN Keep (roughly) parallel with relevant material from groff.texi
5464 .\" node "Compatibility Mode".
5465 AT&T
5466 .I troff \" AT&T
5467 recognized slightly varying sets of delimiters when expecting
5468 numerical expressions
5469 (as with the
5470 .B \[rs]h
5471 escape sequence),
5472 string expressions
5473 (as with the
5474 .B \[rs]w
5475 escape sequence
5476 and
5477 .B tl
5478 request),
5479 and output comparisons
5480 (as in
5481 .RB \[lq] ".if #foo#bar# .tm match" \[rq]).
5482 GNU
5483 .IR troff , \" GNU
5484 when not in compatibility mode,
5485 recognizes a single consistent set of delimiters.
5486 .
5487 Compatibility mode
5488 emulates
5489 AT&T
5490 .I troff \" AT&T
5491 only up to a point.
5492 GNU
5493 .I troff \" GNU
5494 accepts leaders and tabs as delimiters,
5495 as well as
5496 Control+D
5497 (EOT or EOF),
5498 Control+H
5499 (BS or backspace),
5500 and
5501 Control+L
5502 (FF or form feed),
5503 all of which,
5504 when used as delimiters,
5505 cause
5506 AT&T
5507 .I troff \" AT&T
5508 to behave in ways difficult to predict.
5509 .\" END Keep (roughly) parallel with relevant material from groff.texi
5510 .\" node "Compatibility Mode".
5511 .
5512 .
5513 .\" ====================================================================
5514 .SS Miscellaneous
5515 .\" ====================================================================
5516 .
5517 A font not listed in the output device's
5518 .I DESC
5519 file's
5520 .B fonts
5521 directive is automatically mounted at the next available font position
5522 when it is selected.
5523 .
5524 If you mount a font explicitly with the
5525 .B fp
5526 request,
5527 you should do so on the first unused position,
5528 which can be found in the
5529 .B .fp
5530 register.
5531 .
5532 .
5533 .P
5534 Unparameterized string interpolation does not conceal the arguments to a
5535 macro being interpreted.
5536 .
5537 Thus,
5538 in a macro definition,
5539 the call of another macro with the existing argument list,
5540 .
5541 .RS
5542 .EX
5543 .BI . xx\~ \[rs]\[rs]$@
5544 .EE
5545 .RE
5546 .
5547 is more efficiently done with
5548 .
5549 .RS
5550 .EX
5551 .BI \[rs]\[rs]*[ xx ]\[rs]\[rs]
5552 .EE
5553 .RE
5554 .
5555 (that is,
5556 with string interpolation).
5557 .
5558 The trailing backslashes prevent the final newline in the macro
5559 definition from being interpolated,
5560 potentially putting an unwanted blank line on the output.
5561 .
5562 See section \[lq]Punning Names\[rq] in
5563 .MR groff 7 .
5564 .
5565 .
5566 .\" XXX: Is this really not an AT&T troff feature?
5567 .br
5568 .ne 2v
5569 .P
5570 If a font description file contains pairwise kerning information,
5571 glyphs from that font are kerned.
5572 .
5573 Kerning between two glyphs can be inhibited by placing a dummy character
5574 .B \[rs]&
5575 between them.
5576 .
5577 .
5578 .P
5579 GNU
5580 .I troff \" GNU
5581 keeps track of the nesting depth of escape sequence
5582 interpolations and other uses of delimiters,
5583 as in the
5584 .B tl
5585 request and the output comparison operator
5586 (that is,
5587 input like
5588 .B \[aq]foo\[aq]bar\[aq]
5589 as a conditional expression),
5590 so the only characters you need to avoid using as
5591 delimiters are those that appear in the arguments you input,
5592 not any that result from interpolation.
5593 .
5594 Typically,
5595 .B \[aq]
5596 works fine.
5597 .
5598 Use visible characters as delimiters in GNU
5599 .IR troff , \" GNU
5600 not US-ASCII controls like BEL (Control+G).
5601 .
5602 The implementation of
5603 .B \[rs]$@
5604 ensures that the double quotes surrounding an argument appear at an
5605 interpolation depth different from that of the arguments themselves.
5606 .
5607 Similarly,
5608 in bracket-form escape sequences like
5609 .B \[rs]f\^[ZCMI],
5610 a right bracket
5611 .B ]
5612 does not end the sequence unless it occurs at the same interpolation
5613 depth as the
5614 .RB opening\~ [ .
5615 .
5616 In compatibility mode,
5617 no attention is paid to the interpolation depth.
5618 .
5619 .
5620 .P
5621 In
5622 GNU
5623 .IR troff , \" GNU
5624 the
5625 .B tr
5626 request can map characters to the unbreakable space escape sequence
5627 .B \[rs]\[ti]
5628 as a special case
5629 .RB ( tr
5630 normally operates only on
5631 .IR characters ).
5632 .
5633 This feature replaces the odd-parity
5634 .B tr
5635 mapping trick used in AT&T
5636 .I troff \" AT&T
5637 documents,
5638 where a character,
5639 often
5640 .BR \[ti] ,
5641 was \[lq]sacrificed\[rq] by mapping it to \[lq]nothing\[rq],
5642 drafting it into use as an unadjustable,
5643 unbreakable space.
5644 .
5645 (This feature was gratuitous even in early AT&T
5646 .I troff, \" AT&T
5647 which supported the
5648 .BI \[rs] space
5649 escape sequence by 1976.) \" see CSTR #54 of that year
5650 .
5651 Often,
5652 it makes more sense to use
5653 GNU
5654 .IR troff 's \" GNU
5655 .B \[rs]\[ti]
5656 escape sequence instead,
5657 which has been adopted by every other active
5658 .I troff
5659 implementation except that of Illumos,
5660 as well as by the
5661 .RI non -troff
5662 .IR mandoc .
5663 .
5664 Translation of a character to
5665 .B \[rs]\[ti]
5666 is generally unnecessary,
5667 but might be employed to obtain an unbreakable space when the escape
5668 character will subsequently be disabled.
5669 .
5670 .
5671 .P
5672 GNU
5673 .I troff \" GNU
5674 permits tabs and spaces after the first dot on a control line that ends
5675 a macro definition.
5676 .
5677 .
5678 .\" ====================================================================
5679 .SH "Formatter output"
5680 .\" ====================================================================
5681 .
5682 The page description language output by GNU
5683 .I troff \" GNU
5684 is modeled after that used by AT&T
5685 .I troff \" AT&T
5686 once the latter adopted a device-independent approach in the early
5687 1980s.
5688 .
5689 Only the differences are documented here.
5690 .
5691 For a fuller discussion,
5692 see
5693 .MR groff_out 5 .
5694 .\"
5695 .\"
5696 .\" XXX: This feature is unused and documenting it gives a valuable
5697 .\" hostage to fortune.
5698 .\".P
5699 .\"Note that single characters can have the eighth bit set, as can the
5700 .\"names of fonts and special characters.
5701 .
5702 .
5703 .br
5704 .ne 3v
5705 .P
5706 Glyph and font names can be of arbitrary length;
5707 postprocessors should not assume that they are at most two characters.
5708 .
5709 A glyph to be formatted is always drawn from the current font;
5710 in contrast to AT&T device-independent
5711 .IR troff , \" AT&T
5712 drivers need not search special fonts to find a glyph.
5713 .
5714 .
5715 .\" ====================================================================
5716 .SS Units
5717 .\" ====================================================================
5718 .
5719 The argument to the
5720 .BR s \~command
5721 is in scaled points
5722 (units of
5723 .RI points/ n ,
5724 where
5725 .I n
5726 is the argument to the
5727 .B sizescale
5728 command in the
5729 .I DESC
5730 file).
5731 .
5732 The argument to the
5733 .RB \[lq] "x H" \[rq]
5734 command is also in scaled points.
5735 .
5736 .
5737 .\" ====================================================================
5738 .SS "Simple commands"
5739 .\" ====================================================================
5740 .
5741 .\" BEGIN Keep in sync with relevant portions of section "Simple
5742 .\" commands" from groff_out(5).
5743 .P
5744 If the
5745 .B tcommand
5746 directive is present in the output device's
5747 .I DESC
5748 file,
5749 GNU
5750 .I troff \" GNU
5751 employs the following two commands.
5752 .
5753 .
5754 .TP
5755 .BI t\~ xyz\c
5756 \&.\|.\|.
5757 Typeset word
5758 .IR xyz ;
5759 that is,
5760 set a sequence of ordinary glyphs named
5761 .IR x ,
5762 .IR y ,
5763 .IR z ,
5764 \&.\|.\|.\|,
5765 terminated by a space or newline;
5766 an optional second integer argument is ignored
5767 (this allows the formatter to generate an even number of arguments).
5768 .\" XXX: Why?
5769 .
5770 Each glyph is set at the current drawing position,
5771 and the position is then advanced horizontally by the glyph's width.
5772 .
5773 A glyph's width is read from its metrics in the font description file,
5774 scaled to the current type size,
5775 and rounded to a multiple of the horizontal motion quantum.
5776 .
5777 Use the
5778 .B C
5779 command to emplace glyphs of special characters.
5780 .
5781 .
5782 .TP
5783 .BI u\~ "n xyz"\c
5784 \&.\|.\|.
5785 Typeset word
5786 .I xyz
5787 with track kerning.
5788 .
5789 As
5790 .BR t ,
5791 but after placing each glyph,
5792 the drawing position is further advanced horizontally
5793 .RI by\~ n
5794 basic units.
5795 .\" END Keep in sync with relevant portions of section "Simple commands"
5796 .\" from groff_out(5).
5797 .
5798 .
5799 .P
5800 New commands implement color support.
5801 .
5802 .
5803 .TP
5804 .BI mc\~ "cyan magenta yellow"
5805 .TQ
5806 .B md
5807 .TQ
5808 .BI mg\~ gray
5809 .TQ
5810 .BI mk\~ "cyan magenta yellow black"
5811 .TQ
5812 .BI mr\~ "red green blue"
5813 Set the components of the stroke color with respect to various color
5814 spaces.
5815 .
5816 .B md
5817 resets the stroke color to the default value.
5818 .
5819 The arguments are integers in the range 0 to 65535.
5820 .
5821 .
5822 .P
5823 A new device control subcommand is available.
5824 .
5825 .
5826 .TP
5827 .BI "x u\~" n
5828 If
5829 .I n
5830 is\~1,
5831 start underlining of spaces.
5832 .
5833 If
5834 .I n
5835 is\~0,
5836 stop underlining of spaces.
5837 .
5838 This facility is needed for the
5839 .B cu
5840 request in
5841 .I nroff \" mode
5842 mode and is ignored otherwise.
5843 .
5844 .
5845 .\" ====================================================================
5846 .SS "Extended drawing commands"
5847 .\" ====================================================================
5848 .
5849 GNU
5850 .I pic \" GNU
5851 does not produce
5852 .I \%troff
5853 escape sequences employing these extensions if its
5854 .B \-n
5855 option is given.
5856 .
5857 .
5858 .TP 8n \" "DE h v" + 2n
5859 .BI Df\~ n
5860 Set the shade of gray used to fill geometric objects to
5861 .IR n ,
5862 which must be an integer.
5863 .
5864 0 corresponds to white and 1000 to black.
5865 .
5866 A grayscale ramp spans the two.
5867 .
5868 A value outside this range uses the stroke color as the fill color.
5869 .
5870 The fill color is opaque.
5871 .
5872 Normally the default is black,
5873 but some drivers may provide a way of changing this.
5874 .
5875 .B Df
5876 is obsolete since 2002, \" commit ea5a42d080, 2002-01-24
5877 superseded by
5878 .B DFg
5879 below.
5880 .
5881 .
5882 .IP
5883 The corresponding
5884 .B \[rs]D\[aq]f\^\[aq]
5885 escape sequence should not be used:
5886 its argument is rounded to an integer multiple of the horizontal motion
5887 quantum,
5888 which can limit the precision
5889 .RI of\~ n .
5890 .
5891 .
5892 .TP
5893 .BI DC\~ d
5894 Draw a filled circle of diameter
5895 .I d
5896 with its leftmost point at the drawing position.
5897 .
5898 .
5899 .TP
5900 .BI DE\~ "h v"
5901 Draw a filled ellipse,
5902 of horizontal axis
5903 .I h
5904 and vertical axis
5905 .IR v ,
5906 with its leftmost point at the drawing position.
5907 .
5908 .
5909 .br
5910 .ne 4v
5911 .EQ
5912 delim $$
5913 .EN
5914 .TP
5915 .\" `BR`, not `BI`, here, because eqn will take care of font changes.
5916 .BR Dp\~ "$dx sub 1 ~ dy sub 1 ~ ldots ~ dx sub n ~ dy sub n$"
5917 Draw a polygon with,
5918 for $i = 1 , ldots , n + 1$,
5919 its
5920 .IR i th
5921 vertex at the drawing position
5922 .
5923 $+ sum from { j = 1 } to { i - 1 } ( dx sub j , dy sub j )$.
5924 .
5925 .\" The following is implied by the math above, but let's be kind.
5926 .I groff
5927 output drivers automatically close polygons,
5928 drawing a line from $( dx sub n , dy sub n )$ back to
5929 $( dx sub 1 , dy sub 1 )$.
5930 .
5931 The drawing position is left at the last
5932 .I specified
5933 vertex,
5934 but this may change in a future version of GNU
5935 .IR troff . \" GNU
5936 .
5937 Heirloom Doctools
5938 .IR troff , \" Heirloom
5939 like DWB
5940 .IR troff , \" DWB
5941 by default does not close the polygon.
5942 .
5943 In its
5944 .I groff
5945 compatibility mode,
5946 Heirloom closes the polygon but leaves the drawing position
5947 .IR unchanged \[em]that
5948 is,
5949 at the polygon's
5950 .I initial
5951 drawing position.
5952 .
5953 .
5954 .TP
5955 .BR DP\~ "$dx sub 1 ~ dy sub 1 ~ ldots ~ dx sub n ~ dy sub n$"
5956 As
5957 .BR Dp ,
5958 but draw a filled rather than a stroked polygon.
5959 .
5960 .
5961 .TP
5962 .BI Dt\~ n
5963 Set the line thickness to
5964 .IR n \~\c
5965 basic units.
5966 .
5967 AT&T
5968 .I troff \" AT&T
5969 output drivers use a thickness proportional to the type size;
5970 this is the GNU
5971 .I troff \" GNU
5972 default.
5973 .
5974 A
5975 .RI negative\~ n
5976 requests this explicitly.
5977 .
5978 .RI An\~ n
5979 of zero selects the smallest available line thickness.
5980 .
5981 .
5982 .P
5983 A difficulty arises in how the drawing position should be changed after
5984 the execution of these commands.
5985 .
5986 This has little importance to most users,
5987 since the output of GNU
5988 .I grn \" GNU
5989 and
5990 .I pic \" GNU
5991 does not depend on it.
5992 .
5993 Given a drawing command of the form
5994 .BI D z
5995 $x sub 1 ~ y sub 1 ~ ldots ~ x sub n ~ y sub n$,
5996 where
5997 .I z
5998 is not
5999 .B c
6000 or
6001 .BR e ,
6002 AT&T
6003 .I troff \" AT&T
6004 treats each $x sub i$ as a horizontal motion,
6005 each $y sub i$ as a vertical one,
6006 and therefore assumes that the width of the drawn object is
6007 $sum from { i = 1 } to n x sub i$,
6008 and its height is $sum from { i = 1 } to n y sub i$.
6009 .
6010 (Verify its assumption about height by examining the
6011 .B st
6012 and
6013 .B sb
6014 registers after using such a drawing command in a
6015 .B \[rs]w
6016 escape sequence).
6017 .
6018 Thus after executing a
6019 .BR D \~command
6020 of the form
6021 .BI D z
6022 $x sub 1 ~ y sub 1 ~ ldots ~ x sub n ~ y sub n$,
6023 the drawing position increases by
6024 .
6025 $( sum from { i = 1 } to n x sub i , sum from { i = 1 } to n y sub i )$.
6026 .EQ
6027 delim off
6028 .EN
6029 .
6030 For the sake of compatibility,
6031 GNU
6032 .I troff \" GNU
6033 follows this rule,
6034 even though it frustrates extensions to the
6035 .B D
6036 command that set drawing parameters rather than rendering objects,
6037 producing ugly results in the case of
6038 .B Dt
6039 and
6040 .BR Df ,
6041 or otherwise don't parameterize objects as a series of vertices,
6042 as with
6043 GNU
6044 .IR troff 's \" GNU
6045 filled ellipse,
6046 .BR DE .
6047 .
6048 In a future release,
6049 GNU
6050 .I troff \" GNU
6051 and its output drivers may abandon the application of this assumption to
6052 drawing commands not explicitly specified in the AT&T \[lq]Troff User's
6053 Manual\[rq].
6054 .
6055 You can ensure predictable output by enclosing drawing commands
6056 in the zero-motion escape sequence
6057 .BR \[rs]Z .
6058 .
6059 .
6060 .P
6061 GNU
6062 .I troff \" GNU
6063 implements fill color selection with another set of extensions.
6064 .
6065 .
6066 .TP
6067 .BI DFc\~ "cyan magenta yellow"
6068 .TQ
6069 .B DFd
6070 .TQ
6071 .BI DFg\~ gray
6072 .TQ
6073 .BI DFk\~ "cyan magenta yellow black"
6074 .TQ
6075 .BI DFr\~ "red green blue"
6076 Set the components of the fill color as described under the
6077 .B \[rs]M
6078 escape sequence above.
6079 .
6080 .B DFd
6081 restores the device's default fill color.
6082 .
6083 The drawing position is not updated,
6084 in contrast to
6085 .BR Df .
6086 .
6087 .
6088 .\" ====================================================================
6089 .SS "Device control syntax extension"
6090 .\" ====================================================================
6091 .
6092 GNU
6093 .I troff \" GNU
6094 introduces a line continuation convention,
6095 permitting the argument to the
6096 .B x X
6097 command to contain newlines.
6098 .
6099 A newline in the input is transformed to the sequence
6100 .RI \[lq] newline\c
6101 .BR + \[rq].
6102 .
6103 When interpreting an
6104 .B x X
6105 command,
6106 a postprocessor should therefore be prepared for a plus sign after a
6107 newline;
6108 if it occurs,
6109 preserve the newline,
6110 discard the plus sign,
6111 and continue to collect the input into the argument of the
6112 .B x X
6113 command.
6114 .
6115 A newline
6116 .I not
6117 followed by a plus sign terminates the
6118 .B x X
6119 command.
6120 .
6121 An application of this feature is the embedding of PostScript or PDF
6122 language command streams into
6123 .I troff \"
6124 output.
6125 .
6126 .
6127 .P
6128 GNU
6129 .I troff \" GNU
6130 guarantees that the first three output commands it emits are as follows.
6131 .
6132 .
6133 .P
6134 .RS
6135 .EX
6136 .RI x\~T\~ device
6137 .RI x\~res\~ n\~h\~v
6138 x init
6139 .EE
6140 .RE
6141 .
6142 .
6143 .br
6144 .ne 4v
6145 .\" ====================================================================
6146 .SH Debugging
6147 .\" ====================================================================
6148 .
6149 In addition to AT&T
6150 .IR troff 's \" AT&T
6151 debugging features,
6152 GNU
6153 .I troff \" GNU
6154 emits more error diagnostics when syntactical or semantic nonsense is
6155 encountered and supports several warning categories;
6156 the output of these can be selected with
6157 .RB \[lq] warn \[rq].
6158 .
6159 Also see the
6160 .BR \-E ,
6161 .BR \-w ,
6162 and
6163 .B \-W
6164 options of
6165 .MR \%troff 1 .
6166 .
6167 .
6168 .\" BEGIN Keep (roughly) parallel with relevant material from groff.texi
6169 .\" node "Debugging".
6170 .P
6171 A trace of the formatter's input processing stack
6172 can be emitted when errors or warnings occur
6173 by means of
6174 GNU
6175 .I troff \" GNU
6176 .B \-b
6177 option,
6178 or produced on demand with the
6179 .B \%backtrace
6180 request.
6181 .\" END Keep (roughly) parallel with relevant material from groff.texi
6182 .\" node "Debugging".
6183 .
6184 .
6185 .br
6186 .ne 2v
6187 .P
6188 .I groff
6189 also adds more flexible diagnostic output requests
6190 .RB ( tmc
6191 and
6192 .BR tm1 ).
6193 .
6194 .\" BEGIN Keep (roughly) parallel with relevant material from groff.texi
6195 .\" node "Debugging".
6196 Examine the state of the formatter with requests that write lists of
6197 .\" Deliberate desync with Texinfo: this is groff_diff(7); AT&T troff
6198 .\" already had `pm`.
6199 defined \" names---macros, strings, and diversions---
6200 colors
6201 .RB ( pcolor ),
6202 composite character mappings
6203 .RB ( pcomposite ),
6204 environments
6205 .RB ( pev ),
6206 font translations
6207 .RB ( pftr ),
6208 automatic hyphenation codes
6209 .RB ( pchar )
6210 and exceptions
6211 .RB ( phw ),
6212 registers
6213 .RB ( pnr ),
6214 open streams
6215 .RB ( pstream ),
6216 and
6217 page location traps
6218 .RB ( pwh ).
6219 .
6220 Requests can also disclose
6221 to the standard error stream
6222 the internal properties and representations of
6223 characters and classes
6224 .RB ( pchar ),
6225 macros
6226 (and strings and diversions)
6227 .RB ( pm ),
6228 and the list of output nodes corresponding to the pending input line
6229 .RB ( pline ).
6230 .\" END Keep (roughly) parallel with relevant material from groff.texi
6231 .\" node "Debugging".
6232 .
6233 .
6234 .\" ====================================================================
6235 .SH "Compatibility mode"
6236 .\" ====================================================================
6237 .
6238 Some syntactical and behavioral differences between AT&T and GNU
6239 .IR troff s \" generic
6240 are thought too important to neglect;
6241 GNU
6242 .I troff \" GNU
6243 therefore makes available a
6244 .I "compatibility mode"
6245 in an effort to keep documents prepared for AT&T
6246 .I troff \" AT&T
6247 rendering well.
6248 .
6249 .
6250 .P
6251 Identifiers of arbitrary length may be
6252 GNU
6253 .IR troff 's \" GNU
6254 most obvious innovation.
6255 .
6256 AT&T
6257 .I troff \" AT&T
6258 interprets
6259 .RB \[lq] .dsabcd \[rq]
6260 as defining a string
6261 .RB \[lq] ab \[rq]
6262 with contents
6263 .RB \[lq] cd \[rq].
6264 .
6265 Normally,
6266 GNU
6267 .I troff \" GNU
6268 interprets this input as calling a macro named
6269 .RB \[lq] dsabcd \[rq].
6270 .
6271 AT&T
6272 .I troff \" AT&T
6273 also interprets
6274 .B \[rs]*[
6275 and
6276 .B \[rs]n[
6277 as interpolating a string or register,
6278 respectively,
6279 named
6280 .RB \[lq] [ \[rq].
6281 .
6282 GNU
6283 .IR troff , \" GNU
6284 however,
6285 normally interprets
6286 .RB \[lq] [ \[rq]
6287 as bracketing a long name
6288 (with
6289 .RB \[lq] ] \[rq]
6290 at the distal end).
6291 .
6292 In compatibility mode,
6293 GNU
6294 .I troff \" GNU
6295 interprets names in the traditional way,
6296 they thus can be two characters long at most.
6297 .
6298 See the
6299 .B \-C
6300 option in
6301 .MR \%troff 1
6302 and,
6303 above,
6304 the
6305 .B .C
6306 and
6307 .B .cp
6308 registers,
6309 and
6310 .B cp
6311 and
6312 .RB \[lq] do \[rq]
6313 requests,
6314 for more on compatibility mode.
6315 .
6316 .
6317 .br
6318 .ne 2v
6319 .P
6320 The register
6321 .B \[rs]n[.cp]
6322 is specialized and may require a statement of rationale.
6323 .
6324 When writing macro packages or documents that use GNU
6325 .I troff \" GNU
6326 features and which may be mixed with other packages or documents that do
6327 not\[em]common scenarios include serial processing of man pages or use
6328 of the
6329 .RB \[lq] so \[rq]
6330 or
6331 .B mso
6332 requests\[em]you may desire correct operation regardless of
6333 compatibility mode enablement in the surrounding context.
6334 .
6335 It may occur to you to save the existing value of
6336 .B \[rs]n(.C
6337 into a register,
6338 say,
6339 .BR _C ,
6340 at the beginning of your file,
6341 turn compatibility mode off with
6342 .RB \[lq] .cp\~0 \[rq],
6343 then restore it from that register at the end with
6344 .RB \[lq] .cp\~\[rs]n(_C \[rq].
6345 .
6346 At the same time,
6347 a modular design of a document or macro package may lead you to multiple
6348 layers of inclusion.
6349 .
6350 You cannot use the same register name everywhere lest you
6351 \[lq]clobber\[rq] the value from a preceding or enclosing context.
6352 .
6353 The two-character register name space of AT&T
6354 .I troff \" AT&T
6355 is confining,
6356 but employing
6357 GNU
6358 .IR troff 's \" GNU
6359 more capacious one,
6360 as with
6361 .RB \[lq] ".nr _my_saved_C \[rs]n(.C" \[rq]
6362 does not work in compatibility mode;
6363 the register name is too long.
6364 .
6365 Employing the
6366 .RB \[lq] do \[rq]
6367 request is no help:
6368 .RB \[lq] ".do nr _my_saved_C \[rs]n(.C" \[rq]
6369 always saves zero to the register,
6370 because
6371 .RB \[lq] do \[rq]
6372 turns compatibility mode
6373 .I off
6374 while it interprets its argument list.
6375 .
6376 .
6377 .P
6378 GNU
6379 .I troff \" GNU
6380 normally tracks the interpolation depth of escape sequence parameters
6381 and other delimited structures,
6382 but not in compatibility mode.
6383 .
6384 See section \[lq]Miscellaneous\[rq] above.
6385 .
6386 .
6387 .P
6388 The escape sequences
6389 .BR \[rs]f ,
6390 .BR \[rs]H ,
6391 .BR \[rs]m ,
6392 .BR \[rs]M ,
6393 .BR \[rs]R ,
6394 .BR \[rs]s ,
6395 and
6396 .B \[rs]S
6397 are transparent to control character recognition
6398 at the beginning of an input line,
6399 or after the conditional expression of an
6400 .RB \[lq] if \^\[rq]
6401 or
6402 .B ie
6403 request,
6404 only in compatibility mode.
6405 .
6406 That is,
6407 upon interpreting them,
6408 GNU
6409 .I troff \" GNU
6410 normally no longer recognizes a control character on the input line;
6411 but in compatibility mode,
6412 it does,
6413 just like AT&T
6414 .I troff. \" AT&T
6415 .
6416 .
6417 .P
6418 Normally,
6419 the syntax form
6420 .BI \[rs]s n
6421 accepts only a single character
6422 (a digit)
6423 for
6424 .IR n ,
6425 consistently with other forms that originated in AT&T
6426 .IR troff , \" AT&T
6427 like
6428 .BR \[rs]* ,
6429 .BR \[rs]$ ,
6430 .BR \[rs]f ,
6431 .BR \[rs]g ,
6432 .BR \[rs]k ,
6433 .BR \[rs]n ,
6434 and
6435 .BR \[rs]z .
6436 .
6437 In compatibility mode only,
6438 a
6439 .RI non-zero\~ n
6440 must be in the range 4\[en]39.
6441 .
6442 Legacy documents relying upon this quirk of parsing should migrate
6443 to another
6444 .B \[rs]s
6445 form.
6446 .
6447 [Background:
6448 The Graphic Systems C/A/T phototypesetter
6449 (the original device target for AT&T
6450 .IR troff ) \" AT&T
6451 supported only a few discrete type sizes in the range 6\[en]36 points,
6452 so Ossanna contrived a special case in the parser to do what the user
6453 must have meant.
6454 .
6455 Kernighan warned of this in the 1992 revision of CSTR\~#54 (\[sc]2.3),
6456 and more recently,
6457 McIlroy referred to it as a \[lq]living fossil\[rq].]
6458 .
6459 .
6460 .\" ====================================================================
6461 .SH "Other differences"
6462 .\" ====================================================================
6463 .
6464 .\" BEGIN Keep in sync with groff.texi node "Other Differences".
6465 GNU
6466 .I troff \" GNU
6467 does not emit output if it has nothing to format.
6468 .
6469 For example,
6470 it treats an input document consisting solely of
6471 .B nr
6472 and
6473 .B tm
6474 requests as empty,
6475 and produces nothing on its standard output stream.
6476 .
6477 AT&T
6478 .I troff \" AT&T
6479 does,
6480 creating a blank page.
6481 .
6482 .
6483 .P
6484 Use of C0 control characters in identifiers is not portable;
6485 Solaris,
6486 Plan\~9,
6487 and Heirloom Doctools
6488 .IR troff s \" Solaris, Plan 9, Heirloom
6489 accept
6490 Control+B,
6491 Control+C,
6492 Control+E,
6493 Control+F,
6494 and
6495 Control+G (only);
6496 DWB\~3.3
6497 .I troff \" DWB
6498 does not.
6499 .
6500 GNU
6501 .I troff \" GNU
6502 rejects C0 controls in identifiers with an error diagnostic.
6503 .
6504 .
6505 .P
6506 Formatters that don't implement
6507 GNU
6508 .I troff \" GNU
6509 extension request names
6510 tend to ignore them,
6511 and if they don't support a
6512 GNU
6513 .I troff \" GNU
6514 extension escape sequence,
6515 they are liable to format its function selector character as text.
6516 .
6517 For example,
6518 .\" NESTED BEGIN Keep in sync with groff_man_style(7).
6519 the adjustable,
6520 non-breaking space escape sequence
6521 .B \[rs]\[ti]
6522 is also supported by Heirloom Doctools
6523 .I troff \" Heirloom
6524 050915 (September 2005),
6525 .I mandoc
6526 1.9.5 (2009-09-21),
6527 .I neatroff
6528 (commit 1c6ab0f6e,
6529 2016-09-13),
6530 and Plan\~9 from User Space
6531 .I troff \" Plan 9
6532 (commit 93f8143600,
6533 2022-08-12),
6534 but not by Solaris
6535 or Documenter's Workbench
6536 .IR troff s, \" DWB, Solaris
6537 which both render it as
6538 .RB \[lq] \[ti] \[rq].
6539 .\" as of this writing, 2022-08-13
6540 .\" NESTED END Keep in sync with groff_man_style(7).
6541 .
6542 The
6543 .B \[rs]A
6544 escape sequence
6545 (see subsection \[lq]Escape sequences\[rq] above)
6546 may be helpful in avoiding their use.
6547 .
6548 .
6549 .P
6550 AT&T
6551 .I troff \" AT&T
6552 discards trailing spaces from input lines,
6553 like GNU
6554 .IR troff , \" GNU
6555 but when it does so,
6556 AT&T
6557 .I troff \" AT&T
6558 also cancels end-of-sentence detection.
6559 .
6560 Use of the dummy character escape sequence
6561 .B \[rs]&
6562 is more portable.
6563 .
6564 .
6565 .P
6566 When adjusting output lines to both margins,
6567 AT&T
6568 .I troff \" AT&T
6569 at first adjusts spaces starting from the right;
6570 GNU
6571 .I troff \" GNU
6572 begins from the left.
6573 .
6574 Both implementations adjust spaces
6575 from opposite ends on alternating output lines
6576 in this adjustment mode
6577 to prevent \[lq]rivers\[rq] in the text.
6578 .
6579 .
6580 .br
6581 .ne 2v
6582 .P
6583 GNU
6584 .I troff \" GNU
6585 does not always hyphenate words as AT&T
6586 .I troff \" AT&T
6587 does.
6588 .
6589 The AT&T implementation uses a set of hard-coded rules
6590 specific to U.S.\& English,
6591 while GNU
6592 .I troff \" GNU
6593 uses language-specific hyphenation pattern files derived from \*[tx].
6594 .
6595 Some versions of
6596 .I troff \" generic
6597 reserved meager storage for hyphenation exception words
6598 (arguments to the
6599 .B hw
6600 request);
6601 GNU
6602 .I troff \" GNU
6603 has no such restriction.
6604 .
6605 When the
6606 .B hy
6607 request is invoked without an argument,
6608 GNU
6609 .I troff \" GNU
6610 sets the automatic hyphenation mode to the value of the
6611 .B \%.hydefault
6612 register;
6613 the AT&T implementation sets it to
6614 .RB \[lq] 1 \[rq],
6615 which is not suitable in GNU
6616 .I troff \" GNU
6617 for some languages,
6618 including English.
6619 .
6620 .
6621 .P
6622 Unlike
6623 GNU
6624 .IR troff , \" GNU
6625 AT&T
6626 .I troff \" AT&T
6627 does not recognize an occurrence of
6628 .B \[rs]%
6629 at the beginning of a word as suppressing its hyphenation;
6630 instead,
6631 it (uselessly) marks the start of the word
6632 as a potential hyphenation point,
6633 permitting output lines to end with hyphens
6634 that are not interior to a word.
6635 .
6636 .
6637 .P
6638 GNU
6639 .I troff \" GNU
6640 handles the dummy character
6641 .B \[rs]&
6642 differently from AT&T
6643 .I troff \" AT&T
6644 when it is followed by the hyphenation control escape sequence
6645 .B \[rs]%
6646 at the beginning of a word.
6647 .
6648 GNU
6649 .I troff \" GNU
6650 does not regard the dummy character as \[lq]starting\[rq] the word;
6651 AT&T
6652 .I troff \" AT&T
6653 does.
6654 .
6655 Further,
6656 Heirloom Doctools
6657 .I troff \" Heirloom
6658 does not honor an explicit hyphenation point marked with
6659 .B \[rs]%
6660 after a word-initial one.
6661 .\" The foregoing observations may have the same cause.
6662 .
6663 .
6664 .P
6665 GNU
6666 .I troff \" GNU
6667 interprets request arguments representing file names
6668 and system commands
6669 in the same way it does the
6670 .I contents
6671 argument to the
6672 .B ds
6673 and
6674 .RB \[lq] as \[rq]
6675 requests:
6676 it removes a leading neutral double quote
6677 .RB \[oq] \[dq] \[cq]
6678 from the argument to the
6679 .BR cf ,
6680 .BR nx ,
6681 .BR pi ,
6682 .RB \[lq] so \[rq],
6683 and
6684 .B sy
6685 requests,
6686 and the second argument
6687 (if present)
6688 to the
6689 .B lf
6690 request,
6691 permitting initial embedded spaces in it,
6692 and reads it to the end of the input line in copy mode.
6693 This difference permits the formatter to handle files
6694 with spaces in their names,
6695 but requires more care with trailing comments,
6696 and doubling of an initial neutral double quote
6697 .RB \[lq] \[dq] \[rq]
6698 if the file name has one.
6699 .
6700 .
6701 .P
6702 The existence of the
6703 .B .T
6704 string is a common feature of device-independent
6705 .IR troff s\[em]DWB\~3.3, \" others
6706 Solaris,
6707 Heirloom Doctools,
6708 and Plan\~9
6709 .I troff \" foreign
6710 all support it\[em]but valid values are specific to each implementation.
6711 .
6712 .
6713 .P
6714 The (read-only) register
6715 .B .T
6716 interpolates\~1
6717 if GNU
6718 .I troff \" GNU
6719 is run with the
6720 .B \-T
6721 option,
6722 and\~0 otherwise.
6723 In contrast,
6724 AT&T
6725 .I troff \" AT&T
6726 interpolated\~1 only if
6727 .I nroff \" AT&T
6728 was the formatter and was run with
6729 .BR \-T .
6730 .
6731 .
6732 .P
6733 AT&T
6734 .I troff \" AT&T
6735 ignored attempts to remove read-only registers;
6736 GNU
6737 .I troff \" GNU
6738 honors such requests.
6739 .
6740 .
6741 .P
6742 The
6743 .B lf
6744 request sets the number of the
6745 .I current
6746 input line in AT&T
6747 .IR troff ,\" AT&T
6748 and the
6749 .I next
6750 in GNU
6751 .IR troff .\" GNU
6752 .
6753 .
6754 .br
6755 .ne 2v
6756 .P
6757 AT&T
6758 .I troff
6759 had only environments named
6760 .RB \[lq] 0 \[rq],
6761 .RB \[lq] 1 \[rq],
6762 and
6763 .RB \[lq] 2 \[rq].
6764 .
6765 In GNU
6766 .IR troff ,
6767 any number of environments may exist,
6768 using any valid identifiers for their names.
6769 .
6770 .
6771 .P
6772 As noted above in \[lq]Fractional type sizes and new scaling units\[rq],
6773 AT&T
6774 .IR troff 's \" AT&T
6775 .B ps
6776 request ignores scaling units
6777 and thus
6778 .RB \[lq] .ps\~10u \[rq]
6779 sets the type size to 10\~points,
6780 whereas in GNU
6781 .I troff \" GNU
6782 it sets the type size to
6783 .RI 10\~ scaled
6784 points,
6785 possibly a much smaller measurement.
6786 .
6787 AT&T's behavior also means that
6788 .RB \[lq] .ps\~10p \[rq]
6789 and
6790 .RB \[lq] .ps\~10z \[rq]
6791 are portable.
6792 .
6793 .
6794 .P
6795 The
6796 .B ab
6797 request differs from AT&T
6798 .IR troff : \" AT&T
6799 GNU
6800 .I troff \" GNU
6801 writes no message to the standard error stream if no arguments are
6802 given,
6803 and it exits with a failure status instead of a successful one.
6804 .
6805 .
6806 .P
6807 The
6808 .B bp
6809 request differs from AT&T
6810 .IR troff : \" AT&T
6811 GNU
6812 .I troff \" GNU
6813 does not accept a scaling unit on the argument,
6814 a page number;
6815 the former does (uselessly).
6816 .
6817 .
6818 .P
6819 In AT&T
6820 .I troff \" AT&T
6821 the
6822 .B pm
6823 request reports
6824 macro,
6825 string,
6826 and
6827 diversion
6828 sizes in units of 128-byte blocks,
6829 and an argument reduces the report to a sum of the above in the same
6830 units.
6831 .
6832 GNU
6833 .I troff \" GNU
6834 reports their lengths in characters or nodes if given no arguments,
6835 and otherwise dumps
6836 the JSON-encoded name,
6837 contents,
6838 and other properties of each named argument.
6839 .
6840 .
6841 .P
6842 AT&T
6843 .I troff \" AT&T
6844 ignores the
6845 .B ss
6846 request if the output is a terminal device;
6847 GNU
6848 .I troff \" GNU
6849 rounds down the values of minimum inter-word and additional
6850 inter-sentence space each to the nearest multiple of\~12.
6851 .
6852 .
6853 .\" TODO: A lot of this discussion should move to "Using Symbols" and
6854 .\" "GNU troff Internals" (or whatever those sections get named once
6855 .\" ported to this man page).
6856 .P
6857 GNU
6858 .I troff \" GNU
6859 distinguishes characters from glyphs.
6860 .
6861 Characters can be ordinary,
6862 special,
6863 or indexed,
6864 and populate strings and macros.
6865 .
6866 Characters
6867 .I "per se"
6868 have not (yet) been formatted.
6869 .
6870 Glyphs represent graphemes
6871 (supplied by the output device)
6872 and populate diversions.
6873 .\" (recall @ref{Diversions}).
6874 .
6875 Formatting converts characters into
6876 (sequences of)
6877 glyphs.
6878 .
6879 GNU
6880 .I troff \" GNU
6881 stores properties of the environment
6882 that affect how a glyph is rendered with the glyph node's data.
6883 .
6884 Thus,
6885 subsequent formatting operations do not affect it,
6886 including
6887 .BR bd ,
6888 .BR cs ,
6889 .BR tkf ,
6890 .BR tr ,
6891 and
6892 .B fp
6893 requests.
6894 .
6895 Normally,
6896 a macro or string
6897 contains only a list of characters
6898 and a diversion
6899 contains only a list of nodes.
6900 However,
6901 applying the
6902 .B \%asciify
6903 or
6904 .B \%unformat
6905 requests to a diversion converts some of its nodes back into characters.
6906 .
6907 Where the formatter cannot recover the character representation
6908 of a node,
6909 it stores a null character in the character list
6910 corresponding to a single node in the node list.
6911 .
6912 Consequently,
6913 a glyph node does not behave as a character does
6914 in macro interpolation:
6915 it does not inherit special properties
6916 that the character from which it was constructed might have had.
6917 .
6918 .
6919 .P
6920 One way to format a backslash in most documents is with the
6921 .B \[rs]e
6922 escape sequence;
6923 this formats the glyph of the current escape character,
6924 regardless of whether it is used in a diversion;
6925 it also works in both GNU
6926 .I troff \" GNU
6927 and AT&T
6928 .IR troff . \" AT&T
6929 .
6930 (Naturally,
6931 if you've changed the escape character,
6932 you need to prefix the
6933 .RB \[lq] e \[rq]
6934 with whatever it is\[em]and you'll likely get something other than a
6935 backslash in the output.)
6936 .
6937 .
6938 .P
6939 The other correct way,
6940 appropriate in contexts independent of the backslash's common use as a
6941 .I roff
6942 escape character\[em]perhaps in discussion of character sets or other
6943 programming languages\[em]is the special character escape sequence
6944 .B \[rs](rs
6945 or
6946 .BR \[rs][rs] ,
6947 for \[lq]reverse solidus\[rq],
6948 from its name in the ECMA-6 and ISO\~10646 standards.
6949 .
6950 [AT&T
6951 .I troff 's \" AT&T
6952 font description files
6953 did not define the
6954 .B rs
6955 special character,
6956 but those of
6957 its descendant Heirloom Doctools
6958 .I troff \" Heirloom
6959 do,
6960 as of its 060716 release (July 2006).]
6961 .\" The foregoing once said "lineal" descendant; that appears not to be
6962 .\" true. Heirloom Doctools troff is based on Open Solaris troff, which
6963 .\" descends from DWB 2.0 troff (effectively a fork). "Lineal"
6964 .\" descendants of DWB 2.0 troff would be DWB 3.3 and, possibly, Plan 9
6965 .\" troff. (The accuracy of this last claim depends on the degree of
6966 .\" resemblance between Research Unix troff--the version maintained by
6967 .\" Kernighan--and DWB troff, of which 3.4 was the final release.)
6968 .
6969 .
6970 .P
6971 To store an escape sequence in a diversion that is interpreted when the
6972 diversion is interpolated,
6973 either use the traditional
6974 .B \[rs]!\&
6975 transparent output facility,
6976 or,
6977 if this is unsuitable,
6978 the new
6979 .B \[rs]?\&
6980 escape sequence.
6981 .
6982 See subsection \[lq]Escape sequences\[rq] above and sections
6983 \[lq]Diversions\[rq] and \[lq]GNU troff Internals\[rq] in
6984 .IR "Groff: The GNU Implementation of troff" ,
6985 the
6986 .I groff
6987 Texinfo manual.
6988 .
6989 .
6990 .P
6991 Like
6992 AT&T
6993 .I troff, \" AT&T
6994 GNU
6995 .I troff \" GNU
6996 maintains a buffer of device-independent output commands,
6997 populating the buffer as formatted output accumulates.
6998 GNU
6999 .I troff \" GNU
7000 always flushes this buffer when processing a break;
7001 AT&T
7002 .I troff \" AT&T
7003 does so according to no obvious schedule
7004 (perhaps,
7005 if the buffer is of fixed size,
7006 the formatter performs the flush when the buffer runs out of room).
7007 .
7008 .
7009 .P
7010 In the somewhat pathological case where a diversion exists
7011 containing a partially collected line
7012 and a partially collected line at the top-level diversion
7013 has never existed,
7014 AT&T
7015 .I troff \" AT&T
7016 outputs a partially collected but otherwise empty line
7017 (as if
7018 .RB \[lq] \[rs]c \[rq]
7019 were in the top-level diversion)
7020 at the end of input;
7021 GNU
7022 .I troff \" GNU
7023 does not.
7024 .\" END Keep in sync with groff.texi node "Other Differences".
7025 .
7026 .
7027 .\" ====================================================================
7028 .SS "Formatter output incompatibilities"
7029 .\" ====================================================================
7030 .
7031 Its extensions notwithstanding,
7032 GNU
7033 .IR troff 's \" GNU
7034 page description language
7035 has some incompatibilities with that of AT&T
7036 .IR troff , \" AT&T
7037 but better compatibility is sought;
7038 problem reports and patches are welcome.
7039 .
7040 The following incompatibilities are known.
7041 .
7042 .
7043 .IP \[bu] 3n
7044 The drawing position after rendering polygons is inconsistent with AT&T
7045 .I troff \" AT&T
7046 practice.
7047 .
7048 Other implementations have diverged on this point as well.
7049 .
7050 .
7051 .IP \[bu]
7052 The output cannot be easily rescaled to other devices as AT&T
7053 .IR troff 's \" AT&T
7054 could.
7055 .\" XXX: Why? What's the problem? sizescale? That could be written
7056 .\" into the output as a comment or x command. --GBR
7057 .
7058 .
7059 .\" ====================================================================
7060 .SH Authors
7061 .\" ====================================================================
7062 .
7063 This document was written by
7064 .MT jjc@\:jclark\:.com
7065 James Clark
7066 .ME ,
7067 .MT wl@\:gnu\:.org
7068 Werner Lemberg
7069 .ME ,
7070 .MT groff\-bernd\:.warken\-72@\:web\:.de
7071 Bernd Warken
7072 .ME ,
7073 and
7074 .MT g.branden\:.robinson@\:gmail\:.com
7075 G.\& Branden Robinson
7076 .ME .
7077 .
7078 .
7079 .\" ====================================================================
7080 .SH "See also"
7081 .\" ====================================================================
7082 .
7083 .IR "Groff: The GNU Implementation of troff" ,
7084 by Trent A.\& Fisher and Werner Lemberg,
7085 is the primary
7086 .I groff
7087 manual.
7088 .
7089 You can browse it interactively with \[lq]info groff\[rq].
7090 .
7091 .
7092 .br
7093 .ne 4v
7094 .P
7095 \[lq]Troff User's Manual\[rq]
7096 by Joseph F.\& Ossanna,
7097 1976
7098 (revised by Brian W.\& Kernighan,
7099 1992),
7100 AT&T Bell Laboratories Computing Science Technical Report No.\& 54,
7101 widely called simply \[lq]CSTR\~#54\[rq],
7102 documents the language,
7103 device and font description file formats,
7104 and page description language
7105 referred to collectively in
7106 .I groff
7107 documentation as AT&T
7108 .IR troff . \" AT&T
7109 .
7110 .
7111 .P
7112 \[lq]A Typesetter-independent TROFF\[rq]
7113 by Brian W.\& Kernighan,
7114 1982,
7115 AT&T Bell Laboratories Computing Science Technical Report No.\& 97,
7116 provides additional insights into the
7117 device and font description file formats
7118 and page description language.
7119 .
7120 .
7121 .P
7122 .MR groff 1 ,
7123 .MR groff 7 ,
7124 .MR roff 7
7125 .
7126 .
7127 .\" Clean up.
7128 .rm tx
7129 .rm ic
7130 .
7131 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
7132 .cp \n[*groff_groff_diff_7_man_C]
7133 .do rr *groff_groff_diff_7_man_C
7134 .
7135 .
7136 .\" Local Variables:
7137 .\" fill-column: 72
7138 .\" mode: nroff
7139 .\" End:
7140 .\" vim: set filetype=groff textwidth=72: