Debian Codegraph @

upstream/debian-trixie/man7/groff_diff.7

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