Debian Codegraph @

upstream/mageia-cauldron/man7/groff_diff.7

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