| blob | 23660e5ff743df617175ac0a99963792fa8d8966 |
1 .\" st -*- nroff -*-
2 .ig
3 groff.7
5 This file is part of groff, the GNU roff type-setting system.
7 Copyright (C) 2000 Free Software Foundation, Inc.
8 written by Bernd Warken <bwarken@mayn.de>
10 Last update: 29 Apr 2000
12 Permission is granted to copy, distribute and/or modify this document
13 under the terms of the GNU Free Documentation License, Version 1.1 or
14 any later version published by the Free Software Foundation; with the
15 Invariant Sections being AUTHOR, with no Front-Cover Texts, and with no
16 Back-Cover Texts.
18 A copy of the Free Documentation License is included as a file called
19 fdl.txt in the main directory of the groff source package.
20 ..
21 .
22 .\" --------------------------------------------------------------------
23 .\" Setup
24 .\" --------------------------------------------------------------------
25 .
26 .if n .mso tmac.tty-char
27 .
28 .\" for formatting of single quotes in documenting code
29 .ds q \(fm
30 .\" for formatting of double quotes, twice because of Emacs highlighting
31 .ds dquote "
32 .ds dquote "
33 .
34 .de BIP
35 . ie (\\n[.$] <= 2) \
36 . BI $@
37 . el \{\
38 . ds @tmp@ \\fB\\$1\\fP\\fI\\$2\\fP
39 . shift 2
40 \&\\*[@tmp@]\\$*
41 . rm @tmp@
42 . \}
43 ..
44 .
45 .de regname
46 . ds @tmp@ \&\\en[\\fB\\$1\\fP]
47 . shift 1
48 \&\\*[@tmp@]\\$*
49 . rm @tmp@
50 ..
51 .
52 .\" request synopsis
53 .de REQ
54 . ds @tmp@ \&\\$1
55 . shift 1
56 . IP "\\fB\&\\*[@tmp@]\\fP \\fI\&\\$*\\fP" 10n
57 . rm @tmp@
58 ..
59 .
60 .\" escape sequence synopsis
61 .de ESC
62 . ds @tmp@ \&\\$1
63 . shift 1
64 . IP "\\fB\\e\&\\*[@tmp@]\\fP\\fI\&\\$*\\fP"
65 . rm @tmp@
66 ..
67 .
68 .\" escape sequence synopsis
69 .de ESC[]
70 . ds @arg1@ \&\\$1
71 . ds @arg2@ \&\\$2
72 . shift 2
73 . IP "\\fB\\e\&\\*[@arg1@][\\fP\\fI\&\\*[@arg2@]\\fP\\fB]\&\\$*\\fP"
74 . rm @arg1@
75 . rm @arg2@
76 ..
77 .
78 .\" escape sequence with quoted argument
79 . de ESCq
80 . ds @tmp@ \&\\$1
81 . shift 1
82 . IP "\\fB\\e\&\\*[@tmp@]\\fP\\fI\\*q\&\\$*\\*q\\fP"
83 . rm @tmp@
84 ..
85 .
86 .\" 2-escapes (special characters)
87 .de ESc
88 . ds @tmp@ \\$1
89 . TP 14n
90 . BR \\e(\&\\*[@tmp@] \ \ \ \\(\\*[@tmp@]
91 . shift 1
92 \\$*.
93 . rm @tmp@
94 ..
95 .
96 .\" 2-escapes (special characters) with extra argument
97 .de EScx
98 . ds @tmp@ \\$1
99 . TP 14n
100 . BR \\e(\&\\*[@tmp@] \ \ \ \\$2
101 . shift 2
102 \\$*.
103 . rm @tmp@
104 ..
105 .
106 .\" Greek characters
107 .de GREEK
108 . ds OLDT@BS \\n[.tabs]
109 . br
110 . ie t \{\
111 . ta 6n 9n 30n T 6n 9n
112 \\fB\\e(*\\$1\\fP\t\\fI\\(*\\$1\\fP\t\\$2\t\
113 \\fB\\e(*\\$3\\fP\t\\fI\\(*\\$3\\fP\t\\$4
114 . \}
115 . el \{\
116 . ta 6n 30n T 6n
117 \\fB\\e(*\\$1\\fP\t\\$2\t\
118 \\fB\\e(*\\$3\\fP\t\\$4
119 . \}
120 . ta \\*[OLDT@BS]
121 . rm OLDT@BS
122 ..
123 .
124 .\" synopsis for registers
125 .de REG
126 . TP 10n
127 \&\\en[\\fB\\$1\\fP]
128 . shift 1
129 .if \\n[.$] \&\\$*
130 ..
131 .
132 .\" description of warnings
133 .de Warning
134 . ne (2v + 1)
135 . TP 12n
136 \&\\fB\\$1\\fP
137 \&\\fI\\$2\\fP
138 . br
139 ..
140 .
141 .\" --------------------------------------------------------------------
142 .\" Title
143 .\" --------------------------------------------------------------------
144 .TH GROFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
145 .SH NAME
146 groff \- a short reference for the GNU roff language
147 .\" --------------------------------------------------------------------
148 .SH DESCRIPTION
149 .\" --------------------------------------------------------------------
150 .I groff
151 stands for
152 .I GNU roff
153 and is the free implementation of the roff type-setting system.
154 See
155 .BR roff (@MAN7EXT@)
156 for a survey and the background of the groff system.
157 .LP
158 This document gives only short descriptions of the predefined roff
159 language elements as used in groff.
160 Both the classical features and the groff extensions are provided.
161 .LP
162 Historically, the
163 .I roff language
164 was called
165 .IR troff .
166 .I groff
167 is compatible sith the classical system and provides proper extensions.
168 So in GNU, the terms
169 .IR roff ,
170 .IR troff ,
171 and
172 .I groff language
173 could be used as synonyms. However
174 .I troff
175 slightly tends to refer more to the classical aspects, whereas
176 .I groff
177 emphasizes the GNU extensions, and
178 .I roff
179 is the general term for the language.
180 .LP
181 This file is not maintained, so it might already be out of date.
182 The full documentation with more detailed, actual, and concise information
183 is found in the
184 .I groff
185 .BR info (1)
186 file.
187 .\" --------------------------------------------------------------------
188 .SH "ELEMENTS"
189 .\" --------------------------------------------------------------------
190 The roff language elements add formatting information to a text file.
191 The fundamental elements are predefined commands and variables that make
192 roff a full-blown programming language.
193 .LP
194 There are two kinds of commands, possibly with arguments.
195 .B Requests
196 are written on a line of their own starting with a dot `.', whereas
197 .B escape sequences
198 are in-line formatting elements starting with a backslash `\e'.
199 User-defined formatting commands are called
200 .B macros
201 and are used exactly like requests.
202 .LP
203 The roff language provides two kinds of variables.
204 .B Strings
205 are used to store character sequences, whereas
206 .B registers
207 can store numerical values.
208 .\" --------------------------------------------------------------------
209 .SH "NUMERICAL EXPRESSIONS"
210 .\" --------------------------------------------------------------------
211 A
212 .B numerical value
213 is a signed or unsigned integer or float with or without an appended
214 scale indicator.
215 A
216 .B scale indicator
217 is a one-character abbreviation for a unit of measurement.
218 A number followed by a scale indicator signifies a size value.
219 By default, numerical values do not have a scale indicator, i.e., they are
220 normal numbers.
221 .LP
222 The roff language defines the following scale indicators.
223 .LP
224 .TS
225 tab (@);
226 A L.
227 c@Centimeter
228 i@Inch
229 P@Pica \(eq 1/6 inch
230 p@Point \(eq 1/72 inch
231 m@Em \(eq the font size in points (width of letter `m')
232 M@100th of an Em
233 n@En \(eq Em/2
234 u@Basic unit for actual output device
235 v@Vertical line space in basic units
236 z@T{
237 scaled point \(eq 1/\fIsizescale\fP of a point
238 (defined in font DESC)
239 T}
240 .TE
241 .LP
242 .B Numerical expressions
243 are the common combinations of the numerical values defined above with
244 the arithmetical operators `+', `-', `*', `/', `%' (mod), the
245 comparative operators `==' (same as `='), `>', `<', `>=', `<=', the
246 logical operators `&' (and), `:' (or), `!' (not), and parentheses `(' and
247 `)'.
248 .LP
249 Moreover,
250 .I groff
251 added the following operators for numerical expressions:
252 .TP
253 .PD 0
254 .IB e1 >? e2
255 The maximum of
256 .I e1
257 and
258 .IR e2 .
259 .TP
260 .IB e1 <? e2
261 The minimum of
262 .I e1
263 and
264 .IR e2 .
265 .TP
266 .BI ( c ; e )
267 Evaluate
268 .I e
269 using
270 .I c
271 as the default scaling indicator.
272 .PD
273 .LP
274 For details see the groff info file.
275 .\" --------------------------------------------------------------------
276 .SH CONDITIONS
277 .\" --------------------------------------------------------------------
278 .B Conditions
279 occur in tests raised by the
280 .B .if
281 and the
282 .B .ie
283 requests.
284 There are many different types of conditions.
285 .TP
286 .PD 0
287 .I N
288 A numerical expression
289 .I N
290 tests true if its value is\ >0.
291 .TP
292 .I !N
293 True if the value of
294 .I N
295 is\ <=0.
296 .TP
297 .I \*qs1\*qs2\*q
298 True if string
299 .I s1
300 is identical to string
301 .IR s2 .
302 .TP
303 .I !\*qs1\*qs2\*q
304 True if string
305 .I s1
306 is not identical to string
307 .IR s2 .
308 .PD
309 .LP
310 There is a small set of letters that can be used to denote conditional
311 tests.
312 .LP
313 .TS
314 tab (@);
315 LB LR.
316 c\fIch@True if there is a character \fIch\fP available.
317 d\fIname@T{
318 True if there is a string, macro, diversion, or request named
319 .IR \fIname\fP .
320 T}
321 e@Current page number is even.
322 o@Current page number is odd.
323 n@Formatter is \fBnroff\fR.
324 r\fIreg@True if there is a register named \fIreg\fP.
325 t@Formatter is \fBtroff\fR.
326 .TE
327 .\" --------------------------------------------------------------------
328 .SH REQUESTS
329 .\" --------------------------------------------------------------------
330 This section provides a short reference for the predefined requests.
331 In groff, request and macro names can be arbitrarily long.
332 No bracketing or marking of long names is needed.
333 .LP
334 Most requests take one or more arguments.
335 The arguments are separated by space characters; there is no inherent limit
336 for their length or number.
337 An argument can be enclosed by a pair of double quotes, this is very handy
338 if an argument contains space characters, e.g., "arg\ with\ space"
339 denotes a single argument.
340 .LP
341 Some requests have optional arguments with a different behaviour.
342 Not all of these details are outlined here.
343 Refer to the groff info file for the whole truth.
344 .LP
345 In the following request specifications, most argument names were chosen
346 be descriptive.
347 Only the following denotations need clarification.
348 .TP
349 .PD 0
350 .I c
351 denotes a single character.
352 .TP
353 .I N
354 is an arbitrary numerical expression, signed or unsigned.
355 .TP
356 .I n
357 is a numerical expression that evaluates to an integer value.
358 .TP
359 .I \(+-N
360 has three meanings depending on its sign.
361 Without a sign, it means to replace
362 .I N
363 directly.
364 If preceded by a negative sign
365 .I \-
366 the value of the numerical expression
367 .I N
368 must be subtracted from an already existing value inherent to the
369 request.
370 If the sign is positive
371 .I +
372 it must be added.
373 To make a negative number an unsigned expression it can be preceded by a
374 .IR 0 .
375 .TP
376 .I font
377 A font may be specified as a font name or a font number.
378 .TP
379 .I anything
380 means all characters up to the end of the line or within a
381 .B \e{...\e}
382 construct is interpreted.
383 .PD
384 .\" --------------------------------------------------------------------
385 .SS "REQUEST SHORT REFERENCE"
386 .\" --------------------------------------------------------------------
387 .PD 0
388 .REQ .\e" "anything
389 Complete line is a comment.
390 .REQ .ab string
391 Print
392 .I string
393 on standard error, exit program.
394 .\"
395 .REQ .ad
396 Begin line adjustment for output lines in current adjust mode.
397 .\"
398 .REQ .ad c
399 Start line adjustment in mode mode
400 .I c
401 .RI ( c \(eq\fCl,r,b,n\fP).
402 .\"
403 .REQ .af register c
404 Assign format
405 .I c
406 to
407 .I register
408 .RI ( c \(eq\fC1,i,I,a,A\fP).
409 .\"
410 .REQ .aln alias register
411 Create alias name for
412 .IR register .
413 .\"
414 .REQ .als alias object
415 Create alias name for request, string, macro, or diversion
416 .IR object .
417 .\"
418 .REQ .am macro
419 Append to
420 .I macro
421 until
422 .I ..
423 is called.
424 .\"
425 .REQ .am macro end
426 Append to
427 .I macro
428 until
429 .I .end
430 is called.
431 .\"
432 .REQ .as stringvar anything
433 Append
434 .I anything
435 to
436 .IR stringvar .
437 .\"
438 .REQ .asciify diversion
439 Unformat special ASCII characters in
440 .IR diversion .
441 .\"
442 .REQ .backtrace
443 Print a backtrace of the input on stderr.
444 .\"
445 .REQ .bd font N
446 Embolden
447 .I font
448 by
449 .IR N -1
450 units.
451 .\"
452 .REQ .bd S font N
453 Embolden Special Font
454 .I S
455 when current font is
456 .IR font .
457 .\"
458 .REQ .bp
459 Eject current page and begin new page.
460 .\"
461 .REQ .bp \(+-N
462 Eject current page; next page number
463 .I \(+-N
464 (default scale indicator
465 .BR v ).
466 .\"
467 .REQ .blm macro
468 Set the blank line macro to
469 .IR macro .
470 .\"
471 .REQ .br
472 Break.
473 .\"
474 .REQ .break
475 Break out of a while loop.
476 .\"
477 .REQ .c2 c
478 Set nobreak control character to
479 .IR c .
480 .\"
481 .REQ .cc c
482 Set control character to
483 .IR c .
484 .\"
485 .REQ .ce
486 Center the next input line.
487 .\"
488 .REQ .ce N
489 Center following
490 .I N
491 input lines.
492 .\"
493 .REQ .cf filename
494 Copy contents of file
495 .I filename
496 unprocessed to stdout or to the diversion.
497 .\"
498 .REQ .cflags mode c1 c2 ...
499 Treat characters
500 .IR c1 ,
501 .IR c2 ,
502 .I ...
503 according to
504 .I mode
505 number.
506 .\"
507 .REQ .ch trap N
508 Change
509 .I trap
510 location
511 to
512 .IR N .
513 .\"
514 .REQ .char c anything
515 Define character
516 .I c
517 to string
518 .IR anything .
519 .\"
520 .REQ .chop object
521 Chop the last character off macro, string, or diversion
522 .IR object .
523 .\"
524 .REQ .close stream
525 Close the
526 .IR stream .
527 .\"
528 .REQ .continue
529 Finish the current iteration of a while loop.
530 .\"
531 .REQ .cp
532 Enable compatibility mode.
533 .\"
534 .REQ .cp N
535 If
536 .I N
537 is zero disable compatibility mode, otherwise enable it.
538 .\"
539 .REQ .cs font N M
540 Set constant character width mode for
541 .I font
542 to
543 .IR N /36
544 ems with em
545 .IR M .
546 .\"
547 .REQ .cu N
548 Continuous underline in nroff, like
549 .B .ul
550 in troff.
551 .\"
552 .REQ .da macro
553 Divert and append to
554 .IR macro .
555 .\"
556 .REQ .de macro
557 Define or redefine
558 .I macro
559 until
560 .I ..
561 is called.
562 .\"
563 .REQ .de macro end
564 Define or redefine
565 .I macro
566 until
567 .I .end
568 is called.
569 .\"
570 .REQ .di macro
571 Divert to
572 .IR macro .
573 .\"
574 .REQ .do name
575 Interpret
576 .I .name
577 with compatibility enabled.
578 .\"
579 .REQ .ds stringvar anything
580 Set
581 .I stringvar
582 to
583 .IR anything .
584 .\"
585 .REQ .dt N trap
586 Set diversion trap to position
587 .I N
588 (default scale indicator
589 .BR v ).
590 .\"
591 .REQ .ec c
592 Set escape character to
593 .IR c .
594 .\"
595 .REQ .el anything
596 Else part for if-else
597 .IR .ie .
598 .\"
599 .REQ .em macro
600 The
601 .I macro
602 will be run after the end of input.
603 .\"
604 .REQ .eo
605 Turn off escape character mechanism.
606 .\"
607 .REQ .ev
608 Switch to previous environment.
609 .\"
610 .REQ .ev env
611 Push down environment number or name
612 .I env
613 and switch to it.
614 .\"
615 .REQ .evc env
616 Copy the contents of environment
617 .I env
618 to the current environment. No pushing or popping.
619 .\"
620 .REQ .ex
621 Exit from roff processing.
622 .\"
623 .REQ .fam name
624 Set the current font family to
625 .IR name .
626 .\"
627 .REQ .fc a b
628 Set field delimiter
629 .I a
630 and pad character
631 .IR b .
632 .\"
633 .REQ .fi
634 Fill output lines.
635 .\"
636 .REQ .fl
637 Flush output buffer.
638 .\"
639 .REQ .fp n font
640 Mount
641 .I font
642 on position
643 .IR n .
644 .\"
645 .REQ .fp n internal external
646 Mount font with long
647 .I external
648 name to short
649 .I internal
650 name on position
651 .IR n .
652 .\"
653 .REQ .fspecial font s1 s2...
654 When the current font is
655 .IR font,
656 fonts
657 .IR s1 ,
658 .IR s2 ,
659 .I ...
660 will be special.
661 .\"
662 .REQ .ft
663 Return to previous font.
664 Same as
665 .BR \efP .
666 .REQ .ft font
667 Change to font name or number
668 .IR font ;
669 same as
670 .BI \ef[ font ]
671 escape sequence.
672 .\"
673 .REQ .ftr font1 font2
674 Translate
675 .I font1
676 to
677 .IR font2 .
678 .\"
679 .REQ .hc c
680 Set hyphenation indicator character to
681 .IR c .
682 .\"
683 .REQ .hcode c1 code1 c2 code2 ...
684 Set the hyphenation code of character
685 .I c1
686 to
687 .IR code1 ,
688 that of
689 .I c2
690 to
691 .IR code2 ,
692 etc.
693 .\"
694 .REQ .hla lang
695 Set the current hyphenation language to
696 .IR lang .
697 .\"
698 .REQ .hlm n
699 Set the maximum number of consecutive hyphenated lines to
700 .IR n .
701 .\"
702 .REQ .hpf file
703 Read hyphenation patterns from
704 .IR file .
705 .\"
706 .REQ .hw words
707 List of
708 .I words
709 with exceptional hyphenation.
710 .\"
711 .REQ .hy N
712 Switch to hyphenation mode
713 .IR N .
714 .\"
715 .REQ .hym n
716 Set the hyphenation margin to
717 .IR n .
718 .\"
719 .REQ .hys n
720 Set the hyphenation space to
721 .IR n .
722 .\"
723 .REQ .ie cond anything
724 If
725 .I cond
726 then
727 .I anything
728 else goto
729 .IR .el .
730 .\"
731 .REQ .if cond anything
732 If
733 .I cond
734 then
735 .IR anything ;
736 otherwise do nothing.
737 .\"
738 .REQ .ig
739 Ignore text until
740 .I ..
741 is called.
742 .\"
743 .REQ .ig end
744 Ignore text until
745 .IR .end .
746 .\"
747 .REQ .in
748 Change to previous indent value.
749 .\"
750 .REQ .in \(+-N
751 Change indent according to
752 .I \(+-N
753 (default scale indicator
754 .BR m ).
755 .\"
756 .REQ .it N trap
757 Set an input-line count trap
758 at position
759 .IR N .
760 .\"
761 .REQ .kern n
762 If
763 .I n
764 is non-zero or missing, enable pairwise kerning, otherwise disable it.
765 .\"
766 .REQ .lc c
767 Leader repetition character.
768 .\"
769 .REQ .length register anything
770 Write the length of the string
771 .I anything
772 in
773 .IR register .
774 .\"
775 .REQ .lf N file
776 Set input line number to
777 .I N
778 and filename to
779 .IR file .
780 .\"
781 .REQ .lg N
782 Ligature mode on if
783 .IR N >0.
784 .\"
785 .REQ .ll
786 Change to previous line length.
787 .\"
788 .REQ .ll \(+-N
789 Set line length according to
790 .I \(+-N
791 (default size
792 .BR 6.5i ,
793 default scale indicator
794 .BR m ).
795 .\"
796 .REQ .ls
797 Change to the previous value of additional intra-line skip.
798 .\"
799 .REQ .ls N
800 Set additional intra-line skip value to
801 .IR N ,
802 i.e.,
803 .IR N -1
804 vertical units (scale indicator
805 .BR v )
806 are skipped after each text output line.
807 .\"
808 .REQ .lt \(+-N
809 Length of title.
810 .\"
811 .REQ .mc
812 Margin character off.
813 .\"
814 .REQ .mc c
815 Print character
816 .I c
817 after each text line at actual distance from right margin.
818 .\"
819 .REQ .mc c N
820 Set margin character to
821 .I c
822 and distance to
823 .I N
824 from right margin.
825 .\"
826 .REQ .mk register
827 Mark current vertical position in
828 .IR register .
829 .\"
830 .REQ .mso file
831 The same as the .so request except that
832 .I file
833 is also searched in the tmac directories.
834 .\"
835 .REQ .na
836 No output-line adjusting.
837 .\"
838 .REQ .ne
839 Need
840 .B 1v
841 vertical space.
842 .\"
843 .REQ .ne N
844 Need
845 .I N
846 vertical space.
847 .\"
848 .REQ .nf
849 No filling or adjusting of output-lines.
850 .\"
851 .REQ .nh
852 No hyphenation.
853 .\"
854 .REQ .nm
855 Number mode off.
856 .\"
857 .REQ .nm \(+-N M S I
858 In line number mode, set number, multiple, spacing, and indent.
859 .\"
860 .REQ .nn
861 Do not number next line.
862 .\"
863 .REQ .nn N
864 Do not number next
865 .I N
866 lines.
867 .\"
868 .REQ .nr register \(+-N M
869 Define or modify
870 .I register
871 using
872 .I \(+-N
873 with auto-increment
874 .IR M .
875 .\"
876 .REQ .nroff
877 Make the built-in condition
878 .B n
879 true and
880 .B t
881 false.
882 .\"
883 .REQ .ns
884 Turn no-space mode on.
885 .\"
886 .REQ .nx filename
887 Next file.
888 .\"
889 .REQ .open stream filename
890 Open
891 .I filename
892 for writing and associate the stream named
893 .I stream
894 with it.
895 .\"
896 .REQ .opena stream filename
897 Like
898 .B .open
899 but append to it.
900 .\"
901 .REQ .os
902 Output vertical distance that was saved by the
903 .B .sv
904 request.
905 .\"
906 .REQ .pc c
907 Page number character.
908 .\"
909 .REQ .pi program
910 Pipe output to
911 .I program
912 (nroff only).
913 .\"
914 .REQ .pl
915 Set page length to default
916 .BR 11i .
917 The current page length is stored in
918 .regname .p .
919 .\"
920 .REQ .pl \(+-N
921 Change page length to
922 .IR \(+-N
923 (default scale indicator
924 .BR v ).
925 .\"
926 .REQ .pm
927 Print macro names and sizes (number of blocks of 128 bytes).
928 .\"
929 .REQ ".pm t"
930 Print only total of sizes of macros (number of 128 bytes blocks).
931 .\"
932 .REQ .pn \(+-N
933 Next page number
934 .IR N .
935 .\"
936 .REQ .pnr
937 Print the names and contents of all currently defined number registers
938 on stderr.
939 .\"
940 .REQ .po
941 Change to previous page offset. The current page offset is available in
942 .regname .o .
943 .\"
944 .REQ .po \(+-N
945 Page offset
946 .IR N .
947 .\"
948 .REQ .ps
949 Return to previous point-size.
950 .REQ .ps \(+-N
951 Point size; same as
952 .BIP \es \(+-N .
953 .\"
954 .REQ .psbb filename
955 Get the bounding box of a PostScript image
956 .IR filename .
957 .\"
958 .REQ .pso command
959 This behaves like the
960 .B .so
961 request except that input comes from the standard output of
962 .IR command .
963 .\"
964 .REQ .ptr
965 Print the names and positions of all traps (not including input line
966 traps and diversion traps) on stderr.
967 .\"
968 .REQ .rchar c1 c2...
969 Remove the definitions of characters
970 .IR c1 ,
971 .IR c2 ,
972 .I ...
973 .\"
974 .REQ .rd prompt
975 Read insertion.
976 .\"
977 .REQ .rj n
978 Right justify the next
979 .I n
980 input lines.
981 .\"
982 .REQ .rm name
983 Remove request, macro, or string
984 .IR name .
985 .\"
986 .REQ .rn old new
987 Rename request, macro, or string
988 .I old
989 to
990 .IR new .
991 .\"
992 .REQ .rnn reg1 reg2
993 Rename register
994 .I reg1
995 to
996 .IR reg2 .
997 .\"
998 .REQ .rr register
999 Remove
1000 .IR register .
1001 .\"
1002 .REQ .rs
1003 Restore spacing; turn no-space mode off.
1004 .\"
1005 .REQ .rt \(+-N
1006 Return
1007 .I (upward only)
1008 to marked vertical place.
1009 .\"
1010 .REQ .shc c
1011 Set the soft hyphen character to
1012 .IR c .
1013 .\"
1014 .REQ .shift n
1015 In a macro, shift the arguments by
1016 .I n
1017 positions.
1018 .\"
1019 .REQ .so filename
1020 Include source file.
1021 .\"
1022 .REQ .sp
1023 Skip
1024 .B 1v
1025 vertically.
1026 .\"
1027 .REQ .sp N
1028 Space vertical distance
1029 .I N
1030 up or down according to sign of
1031 .IR N .
1032 .\"
1033 .REQ .special s1 s2 ...
1034 Fonts
1035 .IR s1 ,
1036 .IR s2 ,
1037 etc. are special and will be searched for characters not in the current font.
1038 .\"
1039 .REQ .ss N
1040 Space-character size set to
1041 .IR N /12
1042 of the spacewidth in the current font.
1043 .\"
1044 .REQ .ss N M
1045 Space-character size set to
1046 .IR N /12
1047 and sentence space size set to
1048 .IR M /12
1049 of the spacewidth in the current font (\(eq1/3 em).
1050 .\"
1051 .REQ .sty n style
1052 Associate
1053 .I style
1054 with font position
1055 .IR n .
1056 .\"
1057 .REQ .substring register n1 n2
1058 Replace the string in
1059 .I register
1060 with the substring defined by the indices
1061 .I n1
1062 and
1063 .IR n2 .
1064 .\"
1065 .REQ .sv
1066 Save
1067 .B 1v
1068 of vertical space.
1069 .\"
1070 .REQ .sv N
1071 Save the vertical distance
1072 .I N
1073 for later output with
1074 .B .os
1075 request.
1076 .\"
1077 .REQ .sy command-line
1078 Execute program
1079 .IR command-line .
1080 .\"
1081 .REQ ".ta T" N
1082 Set tabs after every position that is a multiple of
1083 .IR N .
1084 .REQ .ta n1 n2 ... nn \fBT\fP r1 r2 ... rn
1085 Set tabs at positions
1086 .IR n1 ,
1087 .IR n2 ,
1088 .IR ... ,
1089 .IR nn ,
1090 then set tabs at
1091 .IR nn + r1 ,
1092 .IR nn + r2 ,
1093 .IR ... ,
1094 .IR nn + rn ,
1095 then at
1096 .IR nn + rn + r1 ,
1097 .IR nn + rn + r2 ,
1098 .IR ... ,
1099 .IR nn + rn + rn ,
1100 and so on.
1101 .\"
1102 .REQ .tc c
1103 Tab repetition character.
1104 .\"
1105 .REQ .ti \(+-N
1106 Temporary indent.
1107 .\"
1108 .REQ .tkf font s1 n1 s2 n2
1109 Enable track kerning for
1110 .IR font .
1111 .\"
1112 .REQ .tl \*qleft\*qcenter\*qright\*q
1113 Three-part title.
1114 .\"
1115 .REQ .trf filename
1116 Transparently output the contents of file
1117 .IR filename .
1118 .\"
1119 .REQ .tm anything
1120 Print
1121 .I anything
1122 on terminal (UNIX standard message output).
1123 .\"
1124 .REQ .tr abcd....
1125 Translate
1126 .I a
1127 to
1128 .IR b ,
1129 .I c
1130 to
1131 .IR d ,
1132 etc. on output.
1133 .\"
1134 .REQ .trnt abcd....
1135 This is the same as the .tr request except that the translations do not
1136 apply to text that is transparently throughput into a diversion with
1137 .BR \e! .
1138 .\"
1139 .REQ .troff
1140 Make the built-in condition
1141 .B t
1142 true and
1143 .B n
1144 false.
1145 .\"
1146 .REQ .uf font
1147 Underline font set to
1148 .I font
1149 (to be switched to by
1150 .BR ul ).
1151 .\"
1152 .REQ .ul N
1153 Underline (italicize in troff)
1154 .I N
1155 input lines.
1156 .\"
1157 .REQ .vpt n
1158 Enable vertical position traps if
1159 .I n
1160 is non-zero, disable them otherwise.
1161 .\"
1162 .REQ .vs
1163 Change to previous vertical base line spacing.
1164 .\"
1165 .REQ .vs N
1166 Set vertical base line spacing to
1167 .IR N .
1168 Default value is
1169 .BR 12p .
1170 .\"
1171 .REQ .warn n
1172 Set warnings code to
1173 .IR n .
1174 .\"
1175 .REQ .wh N trap
1176 Set location trap; negative means from page bottom.
1177 .\"
1178 .REQ .while cond anything
1179 While condition
1180 .I cond
1181 is true, accept
1182 .I anything
1183 as input.
1184 .\"
1185 .REQ .write stream anything
1186 Write
1187 .I anything
1188 to the stream named
1189 .IR stream .
1190 .PD
1191 .\" --------------------------------------------------------------------
1192 .SH "ESCAPE SEQUENCES"
1193 .\" --------------------------------------------------------------------
1194 Escape sequences are in-line language elements introduced by a backslash
1195 .B \e
1196 and followed by an escape name and sometimes by a required argument.
1197 Input processing is continued directly after the escaped character or
1198 the argument resp. without an intervening separation character.
1199 So there must be a way to determine the end of the escape name and the end
1200 of the argument.
1201 .LP
1202 This is done by enclosing names (escape name and arguments consisting of
1203 a variable name) by a pair of brackets
1204 .BR \e[ name ]
1205 and constant arguments (number expressions and characters) by apostrophes
1206 (ASCII 0x27) like
1207 .IR \*qconstant\*q .
1208 .LP
1209 There are abbreviations for short names.
1210 Two character escape names can be specified by an opening parenthesis like
1211 .BI \e( xy
1212 without a closing counterpart.
1213 And all one-character names different from the special characters
1214 .B [
1215 and
1216 .B (
1217 can even be specified without a marker in the form
1218 .BIP \e c .
1219 .LP
1220 Constant arguments of length\ 1 can omit the marker apostrophes, too, but
1221 there is no two-character analogue.
1222 .LP
1223 While 1-character escape sequences are mainly used for in-line functions
1224 and system related tasks, the 2-letter names following the
1225 .B \e(
1226 construct are used for special characters predefined by the roff system.
1227 Even longer names
1228 .BI \e[ name ]
1229 mostly denote user defined named characters (see the
1230 .B .char
1231 request).
1232 .\" --------------------------------------------------------------------
1233 .SS "SINGLE CHARACTER ESCAPES"
1234 .\" --------------------------------------------------------------------
1235 .PD 0
1236 .ESC \e
1237 reduces to a single backslash, useful to delay its interpretation as
1238 escape character in copy mode.
1239 For a printable backslash, use
1240 .BR \ee .
1241 .ESC \*q
1242 The acute accent \(aa; same as
1243 .BR \e(aa .
1244 Unescaped: apostrophe, right quotation mark, single quote (ASCII 0x27).
1245 .ESC `
1246 The grave accent \(ga; same as
1247 .BR \e(ga .
1248 Unescaped: left quote, backquote (ASCII 0x60).
1249 .ESC \-
1250 The \- sign in the current font.
1251 .ESC .
1252 An uninterpreted dot (period), even at start of line.
1253 .ESC \& space
1254 Unpaddable space-size space character (no line break).
1255 .ESC 0
1256 Digit width.
1257 .ESC |
1258 1/6 em narrow space character; zero width in nroff.
1259 .ESC ^
1260 1/12 em half-narrow space character; zero width in nroff.
1261 .ESC &
1262 Non-printable, zero width character.
1263 .ESC !
1264 Transparent line indicator.
1265 .ESC \&\*[dquote]
1266 Beginning of comment.
1267 .ESC %
1268 Default optional hyphenation character.
1269 .ESC * s
1270 The string stored in the string variable with 1-character name
1271 .IR s .
1272 .ESC *( st
1273 The string stored in the string variable with 2-character name
1274 .IR st .
1275 .ESC[] * stringvar
1276 The string stored in the string variable with arbitrary length name
1277 .IR stringvar .
1278 .ESC $0
1279 The name by which the current macro was invoked. The
1280 .B .als
1281 request can make a macro have more than one name.
1282 .ESC $ x
1283 Macro argument with 1-place number
1284 .IR x ,
1285 where
1286 .I x
1287 is a digit between 1 and 9.
1288 .ESC $( xy
1289 Macro argument with 2-digit number
1290 .IR xy .
1291 .ESC[] $ nexp
1292 Macro argument with number
1293 .IR nexp ,
1294 where
1295 .I nexp
1296 is a numerical expression evaluating to an integer >=1.
1297 .ESC $*
1298 In a macro, the concatenation of all the arguments separated by spaces.
1299 .ESC $@
1300 In a macro, the concatenation of all the arguments with each surrounded
1301 by double quotes, and separated by spaces.
1302 .ESC ? anything\fB?\fP
1303 In a diversion, this will transparently embed
1304 .I anything
1305 in the diversion.
1306 .I anything
1307 is read in copy mode.
1308 .ESC /
1309 Increases the width of the preceding character so that the spacing
1310 between that character and the following character will be correct if
1311 the following character is a roman character.
1312 .ESC ,
1313 Modifies the spacing of the following character so that the spacing
1314 between that character and the preceding character will correct if the
1315 preceding character is a roman character.
1316 .ESC )
1317 Like
1318 .B \e&
1319 except that it behaves like a character declared with the cflags
1320 request to be transparent for the purposes of end of sentence
1321 recognition.
1322 .ESC ~
1323 Unbreakable space that stretches like a normal inter-word space when a
1324 line is adjusted.
1325 .ESC #
1326 Everything up to and including the next newline is ignored. This is
1327 interpreted in copy mode. This is like
1328 .B \e\*[dquote]
1329 except the ignoring of the terminating newline.
1330 .ESC {
1331 Begin conditional input.
1332 .ESC }
1333 End conditional input.
1334 .ESC \& newline
1335 Ignored newline, for continuation lines.
1336 .ESC ( st
1337 The special character with 2-character name
1338 .IR st ,
1339 see section
1340 .BR "SPECIAL CHARACTERS" .
1341 .ESC[] \& name
1342 The named character with arbitrary length name
1343 .IR name .
1344 .ESC a
1345 Non-interpreted leader character.
1346 .ESCq A anything
1347 If
1348 .I anything
1349 acceptable as name of a string, macro, diversion, register,
1350 environment or font it is
1351 .B 1
1352 otherwise
1353 .BR 0 .
1354 .ESCq b abc...
1355 Bracket building function.
1356 .ESC c
1357 Interrupt text processing.
1358 .ESCq C char
1359 The character called
1360 .IR char ;
1361 same as
1362 .BI \e[ char ]\fR,
1363 but compatible to other roff versions.
1364 .ESC d
1365 Forward (down) 1/2 em vertical unit (1/2 line in nroff).
1366 .ESCq D charseq
1367 Draw a graphical element defined by the characters in
1368 .IR charseq ;
1369 see groff info file for details.
1370 .ESC e
1371 Printable version of the current escape character.
1372 .ESC E
1373 Equivalent to an escape character, but is not interpreted in copy-mode.
1374 .ESC f F
1375 Change to font with 1-character name or 1-digit number
1376 .IR F .
1377 .ESC f( fo
1378 Change to font with 2-characer name or 2-digit number
1379 .IR fo .
1380 .ESC[] f font
1381 Change to font with arbitrary length name or number expression
1382 .IR font .
1383 .ESC[] g reg
1384 Return format of register with name
1385 .I reg
1386 suitable for
1387 .BR .af .
1388 Alternative forms
1389 .BI \eg( xy
1390 and
1391 .BIP \eg x .
1392 .ESCq h N
1393 Local horizontal motion; move right
1394 .I N
1395 (left if negative).
1396 .ESCq H N
1397 Set height of current font to
1398 .IR N .
1399 .ESC[] k reg
1400 Mark horizontal input place in register with arbitrary length name
1401 .IR reg .
1402 Alternative forms
1403 .BI \ek( xy
1404 and
1405 .BIP \ek x .
1406 .ESCq l Nc
1407 Horizontal line drawing function (optionally using character
1408 .IR c ).
1409 .ESCq L Nc
1410 Vertical line drawing function (optionally using character
1411 .IR c ).
1412 .ESC n r
1413 The numerical value stored in the register variable with the 1-character
1414 name
1415 .IR r .
1416 .ESC n( re
1417 The numerical value stored in the register variable with the 2-character
1418 name
1419 .IR re .
1420 .ESC[] n reg
1421 The numerical value stored in the register variable with arbitrary
1422 lenght name
1423 .IR reg .
1424 .ESCq N n
1425 Typeset the character with code
1426 .I n
1427 in the current font,
1428 .RI 0<= n <=255.
1429 No special fonts searched.
1430 .ESCq o abc...
1431 Overstrike characters
1432 .IR a ,
1433 .IR b ,
1434 .IR c ,
1435 etc.
1436 .ESC p
1437 Break and spread output line.
1438 .ESC r
1439 Reverse 1 em vertical motion (reverse line in nroff).
1440 .ESCq R name ±n
1441 The same as
1442 .B .nr
1443 .I name
1444 .IR \(+-n .
1445 .ESC[] s \(+-N
1446 Set the point size to
1447 .I N
1448 scaled points. Note the alternative forms
1449 .BIP \es \(+-[N] ,
1450 .BIP \es \*q\(+-N\*q ,
1451 .BIP \es \(+-\*qN\*q ,
1452 .BIP \es (xy ,
1453 .BIP \es \(+-(xy ,
1454 .BIP \es \(+-x .
1455 Same as
1456 .B .ps
1457 request.
1458 .ESCq S N
1459 Slant output
1460 .I N
1461 degrees.
1462 .ESC t
1463 Non-interpreted horizontal tab.
1464 .ESC u
1465 Reverse (up) 1/2 em vertical motion (1/2 line in nroff).
1466 .ESCq v N
1467 Local vertical motion; move down
1468 .I N
1469 (up if negative).
1470 .ESC[] V env
1471 The contents of the environment variable
1472 .IR env .
1473 Alternative forms
1474 .BI \eV( xy
1475 and
1476 .BIP \eV x .
1477 .ESCq w string
1478 The width of the character sequence
1479 .IR string .
1480 .ESCq x N
1481 Extra line-space function (negative before, positive after).
1482 .ESCq X string
1483 Output
1484 .I string
1485 as device control function.
1486 .ESC[] Y name
1487 Output string variable or macro
1488 .I name
1489 uninterpreted as device control function.
1490 Alternative forms
1491 .BI \eY( xy
1492 and
1493 .BIP \eY x .
1494 .ESC z c
1495 Print
1496 .I z
1497 with zero width (without spacing).
1498 .ESCq Z anything
1499 Print
1500 .I anything
1501 and then restore the horizontal and vertical position;
1502 .I anything
1503 may not contain tabs or leaders.
1504 .PD
1505 .LP
1506 The escape sequences
1507 .BR \e\e ,
1508 .BR \e. ,
1509 .BR \e\*[dquote] ,
1510 .BR \e$ ,
1511 .BR \e* ,
1512 .BR \ea ,
1513 .BR \en ,
1514 .BR \et ,
1515 .BR \eg ,
1516 and
1517 .BI \e newline
1518 are interpreted in copy mode.
1519 .LP
1520 Escape sequences starting with
1521 .B \e(
1522 or
1523 .B \e[
1524 do not represent single character escape sequences, but introduce escape
1525 names with two or more characters.
1526 .LP
1527 If a backslash is followed by a character that does not constitute a
1528 defined escape sequence the backslash is silently ignored and the
1529 character maps to itself.
1530 .\" --------------------------------------------------------------------
1531 .SS "SPECIAL CHARACTERS"
1532 .\" --------------------------------------------------------------------
1533 Common special characters are predefined by escape sequences of the form
1534 .BI \e( xy
1535 with characters
1536 .I x
1537 and
1538 .IR y .
1539 Some of these exist in the usual font while most of them are only
1540 available in the special font.
1541 .LP
1542 .PD 0
1543 .ESc aa Acute accent
1544 .ESc ap Approximately
1545 .ESc br ? Bar
1546 .TP 14n
1547 .B \e(bs
1548 Bell sign, former AT&T copyright mark, not implemented in groff.
1549 .ESc bu Bullet sign
1550 .ESc bv ? Vertical bar
1551 .ESc ca Cap operator
1552 .ESc ci Circle
1553 .ESc co Copyright
1554 .ESc ct Cent
1555 .ESc cu Cup operator
1556 .ESc da Down arrow
1557 .ESc di Division sign
1558 .ESc dd Double dagger
1559 .ESc de Degree
1560 .ESc dg Dagger
1561 .ESc em Em-dash
1562 .ESc eq Equals
1563 .ESc es Empty set
1564 .ESc ff Ligature
1565 .ESc fi Ligature
1566 .ESc Fi Ligature
1567 .ESc fl Ligature
1568 .ESc Fl Ligature
1569 .ESc fm ? Kind of prime
1570 .ESc ga Grave accent
1571 .ESc gr ? Nabla operator
1572 .ESc hy Hyphen
1573 .ESc ib Identical or subset
1574 .ESc if Infinity
1575 .ESc ip Identical or superset
1576 .ESc is Integral sign
1577 .ESc lb Left bottom
1578 .ESc lc Left ceiling
1579 .ESc lf Left floor
1580 .ESc lh Left hand
1581 .ESc lk ? Left (k)urley
1582 .ESc lt Left top
1583 .ESc mi Minus sign; same as \e\-
1584 .ESc mo Member of
1585 .ESc mu Multiplication sign
1586 .ESc no Logical NOT sign
1587 .ESc or Logical OR sign
1588 .ESc pd Partial differential
1589 .ESc pl Plus sign
1590 .ESc pt Proportional
1591 .ESc rb Right bottom
1592 .ESc rc Right ceiling
1593 .ESc rf Right floor
1594 .ESc rg Registered
1595 .ESc rh Right hand
1596 .ESc rn ? Upper bar
1597 .ESc rk ? Right (k)urley
1598 .ESc rt Right top
1599 .ESc ru Ruler character
1600 .ESc sb Subset
1601 .ESc sc Section sign
1602 .ESc sl Slash
1603 .ESc sp Superset
1604 .ESc sq Square
1605 .ESc sr Square root
1606 .ESc ts Terminal sigma
1607 .ESc ua Up arrow
1608 .ESc ul Underline character
1609 .ESc 12 A half
1610 .ESc 14 A quarter
1611 .ESc 34 Three quarter
1612 .ESc == Identical
1613 .ESc >= Larger or equal
1614 .ESc <= Less or equal
1615 .ESc != Not equal
1616 .EScx \-> \(-> Right arrow
1617 .EScx <\- \(<- Left arrow
1618 .ESc ** Asterisk
1619 .EScx +\- \(+- Plus-minus sign
1620 .ESc ~= Approximately equal
1621 .PD
1622 .LP
1623 Greek letters are defined by appending the corresponding roman character
1624 to the initial sequence
1625 .B \e(*
1626 being a 2-letter sequence with an asterisk as its first letter.
1627 For example, Greek
1628 .I alpha
1629 is defined as \fC\e(*a\fP.
1630 .LP
1631 .GREEK a alpha A Alpha
1632 .GREEK b beta B Beta
1633 .GREEK c xi C Xi
1634 .GREEK d delta D Delta
1635 .GREEK e epsilon E Epsilon
1636 .GREEK f phi F Phi
1637 .GREEK g gamma G Gamma
1638 .GREEK h theta H Theta
1639 .GREEK i iota I Iota
1640 .GREEK k kappa K Kappa
1641 .GREEK l lambda L Lambda
1642 .GREEK m mu M Mu
1643 .GREEK n nu N nu
1644 .GREEK o omikron O Omikron
1645 .GREEK p pi P Pi
1646 .GREEK q psi Q Psi
1647 .GREEK r rho R Rho
1648 .GREEK s sigma S Sigma
1649 .GREEK t tau T Tau
1650 .GREEK u ypsilon U Ypsilon
1651 .GREEK w omega W Omega
1652 .GREEK x chi X Chi
1653 .GREEK y eta Y eta
1654 .GREEK z zeta Z Zeta
1655 .if t \{\
1656 .ds OLDT@BS \n[.tabs]
1657 . ta T 0.6c
1658 . LP
1659 In the order of the Greek alphabet this looks like
1660 . LP
1661 . ne 2v+1u
1662 \(*a \(*b \(*g \(*d \(*e \(*z \(*g \(*y \
1663 \(*h \(*i \(*k \(*l \(*m \(*n \(*c \(*o \
1664 \(*p \(*r \(*s \(*t \(*u \(*f \(*x \(*q \(*z
1665 . br
1666 a b g d e z g y \
1667 h i k l m n c o \
1668 p r s t u f x q z
1669 . LP
1670 . ne 2v+1u
1671 \(*A \(*B \(*G \(*D \(*E \(*Z \(*G \(*Y \
1672 \(*H \(*I \(*K \(*L \(*M \(*N \(*C \(*O \
1673 \(*P \(*R \(*S \(*T \(*U \(*F \(*X \(*Q \(*Z
1674 . br
1675 A B G D E Z G Y \
1676 H I K L M N C O \
1677 P R S T U F X Q Z
1678 . ta \*[OLDT@BS]
1679 . rm OLDT@BS
1680 .\}
1681 .\" --------------------------------------------------------------------
1682 .SH REGISTERS
1683 .\" --------------------------------------------------------------------
1684 Registers are variables that store a value.
1685 In groff, most registers store numerical values (see section
1686 .B NUMERICAL EXPRESSIONS
1687 above), but some can also hold a string value.
1688 .LP
1689 Each register is given a name.
1690 Arbitrary registers can be defined and set with the request
1691 .B .nr
1692 .IR regname .
1693 .LP
1694 The value stored in a register can be retrieved by the escape sequences
1695 introduced by
1696 .BR \en .
1697 .LP
1698 Most useful are predefined registers.
1699 In the following the notation
1700 .regname name
1701 is used to refer to a register called
1702 .B name
1703 to make clear that we speak about registers.
1704 Please keep in mind that the
1705 .B \en[]
1706 decoration is not part of the register name.
1707 .\" --------------------------------------------------------------------
1708 .SS "READ-ONLY REGISTERS"
1709 .\" --------------------------------------------------------------------
1710 The following registers have predefined values that should not be
1711 modified by the user (usually, registers starting with a dot a read-only).
1712 Mostly, they provide information on the current settings or store results
1713 from request calls.
1714 .LP
1715 .PD 0
1716 .REG .$ Number of arguments in the current macro.
1717 .REG .A
1718 Set to\ 1 in
1719 .B troff
1720 if option
1721 .B \-A
1722 is used; always\ 1 in
1723 .BR nroff .
1724 .REG .H Available horizontal resolution in basic units.
1725 .REG .T
1726 Set to\ 1 in
1727 .B nroff
1728 if option
1729 .B \-T
1730 is used; always\ 0 in
1731 .BR troff .
1732 .REG .V Available vertical resolution in basic units.
1733 .REG .a
1734 Post-line extra line-space most recently utilized using
1735 .BIP \ex 'N' .
1736 .REG .C 1 if compatibility mode is in effect, 0 otherwise.
1737 .REG .c Number of lines read from current input file.
1738 .REG .cdp
1739 The depth of the last character added to the current environment.
1740 It is positive if the character extends below the baseline.
1741 .REG .ce
1742 The number of lines remaining to be centered, as set by the
1743 .B .ce
1744 request.
1745 .REG .cht
1746 The height of the last character added to the current environment.
1747 It is positive if the character extends above the baseline.
1748 .REG .csk
1749 The skew of the last character added to the current environment.
1750 The skew of a character is how far to the right of the center of a character
1751 the center of an accent over that character should be placed.
1752 .REG .d
1753 Current vertical place in current diversion; equal to register
1754 .regname nl .
1755 .REG .ev The name or number of the current environment (string-valued).
1756 .REG .f Current font number.
1757 .REG .fam The current font family (string-valued).
1758 .REG .fp The number of the next free font position.
1759 .REG .g
1760 Always 1 in GNU troff.
1761 Macros should use it to test if running under
1762 .BR groff .
1763 .REG .h Text base-line high-water mark on current page or diversion.
1764 .REG .hla
1765 The current hyphenation language as set by the
1766 .B .hla
1767 request.
1768 .REG .hlc
1769 The number of immediately preceding consecutive hyphenated lines.
1770 .REG .hlm
1771 The maximum allowed number of consecutive hyphenated lines, as set by
1772 the
1773 .B .hlm
1774 request.
1775 .REG .hy
1776 The current hyphenation flags (as set by the
1777 .B .hy
1778 request).
1779 .REG .hym
1780 The current hyphenation margin (as set by the
1781 .B .hym
1782 request).
1783 .REG .hys
1784 The current hyphenation space (as set by the
1785 .B .hys
1786 request).
1787 .REG .i Current ident.
1788 .REG .in The indent that applies to the current output line.
1789 .REG .kern
1790 .B 1
1791 if pairwise kerning is enabled,
1792 .BR 0 otherwise.
1793 .REG .l Current line length.
1794 .REG .lg
1795 The current ligature mode (as set by the
1796 .B .lg
1797 request).
1798 .REG ll The line length that applies to the current output line.
1799 .REG .lt
1800 The title length (as set by the
1801 .B .lt
1802 request).
1803 .REG .n Length of text portion on previous output line.
1804 .REG .ne
1805 The amount of space that was needed in the last
1806 .B .ne
1807 request that caused a trap to be sprung.
1808 Useful in conjunction with
1809 .regname .trunc .
1810 .REG .o Current page offset.
1811 .REG .p Current page length.
1812 .REG .pn
1813 The number of the next page: either the value set by a
1814 .B .pn
1815 request, or the number of the current page plus\ 1.
1816 .REG .ps The current pointsize in scaled points.
1817 .REG .psr The last-requested pointsize in scaled points.
1818 .REG .rj
1819 The number of lines to be right-justified as set by the rj request.
1820 .REG .s Current point size.
1821 .REG .sr
1822 The last requested pointsize in points as a decimal fraction
1823 (string-valued).
1824 .REG .t Distance to the next trap.
1825 .REG .tabs
1826 A string representation of the current tab settings suitable for use as
1827 an argument to the
1828 .B .ta
1829 request.
1830 .REG .trunc
1831 The amount of vertical space truncated by the most recently sprung
1832 vertical position trap, or, if the trap was sprung by a
1833 .B .ne
1834 request, minus the amount of vertical motion produced by
1835 .BR .ne .
1836 request.
1837 In other words, at the point a trap is sprung, it represents the difference
1838 of what the vertical position would have been but for the trap, and what the
1839 vertical position actually is.
1840 Useful in conjunction with the
1841 .regname .ne
1842 register.
1843 .REG .ss
1844 The value of the parameters set by the first argument of the
1845 .B .ss
1846 request.
1847 .REG .sss
1848 The value of the parameters set by the second argument of the
1849 .B .ss
1850 request.
1851 .REG .u Equal to 1 bin fill mode and 0 in nofill mode.
1852 .REG .v Current vertical line spacing.
1853 .REG .vpt
1854 .B 1
1855 if vertical position traps are enabled,
1856 .B 0
1857 otherwise.
1858 .REG .w Width of previous character.
1859 .REG .warn
1860 The sum of the number codes of the currently enabled warnings.
1861 .REG .x The major version number.
1862 .REG .y The minor version number.
1863 .REG .Y The revision number of groff.
1864 .REG .z Name of current diversion.
1865 .REG llx
1866 Lower left x-coordinate (in PostScript units) of a given PostScript
1867 image (set by
1868 .BR .psbb ).
1869 .REG lly
1870 Lower left y-coordinate (in PostScript units) of a given PostScript
1871 image (set by
1872 .BR .psbb ).
1873 .REG rsb Like
1874 .regname sb ,
1875 but takes account of the heights and depths of characters.
1876 .REG rst
1877 Like
1878 .regname st ,
1879 but takes account of the heights and depths of characters.
1880 .REG sb
1881 Depth of string below base line (generated by width function
1882 .BR \ew ).
1883 .REG skw
1884 Right skip width from the center of the last character in the
1885 .B \ew
1886 argument.
1887 .REG ssc
1888 The amount of horizontal space (possibly negative) that should be added
1889 to the last character before a subscript.
1890 .REG st
1891 Height of string above base line (generated by width function
1892 .BR \ew ).
1893 .REG urx
1894 Upper right x-coordinate (in PostScript units) of a given PostScript
1895 image (set by
1896 .BR .psbb ).
1897 .REG ury
1898 Upper right y-coordinate (in PostScript units) of a given PostScript
1899 image (set by
1900 .BR .psbb ).
1901 .PD
1902 .\" --------------------------------------------------------------------
1903 .SS "WRITABLE REGISTERS"
1904 .\" --------------------------------------------------------------------
1905 The following registers can be read and written by the user.
1906 They have predefined default values, but these can be modified for
1907 customizing a document.
1908 .LP
1909 .PD 0
1910 .REG % Current page number.
1911 .REG ct Character type (set by width function
1912 .BR \ew ).
1913 .REG dl Maximal width of last completed diversion.
1914 .REG dw Current day of week (1-7).
1915 .REG dy Current day of month (1-31).
1916 .REG hp Current horizontal position at input line.
1917 .REG ln Output line number.
1918 .REG mo Current month (1-12).
1919 .REG nl Vertical position of last printed text base-line.
1920 .REG slimit
1921 If greater than 0, the maximum number of objects on the input stack.
1922 If <=0 there is no limit, i.e., recursion can continue until virtual memory
1923 is exhausted.
1924 .REG systat
1925 The return value of the
1926 .I system()
1927 function executed by the last
1928 .B .sy
1929 request.
1930 .REG year The current year (year 2000 compliant).
1931 .REG yr
1932 Current year minus 1900. For Y2K compliance use register
1933 .regname year
1934 instead.
1935 .PD
1936 .\" --------------------------------------------------------------------
1937 .SH WARNINGS
1938 .\" --------------------------------------------------------------------
1939 Each warning generated by groff is identified by a name and a code
1940 number. The codes are powers of 2 to allow bit-encoding with a single
1941 integer. There are also names that can be used to refer to groups of
1942 warnings.
1943 .LP
1944 The name associated with a warning is used by the
1945 .B \-w
1946 and
1947 .B \-W
1948 options;
1949 the number code is used by the
1950 .B .warn
1951 request and by the
1952 .B \en[warn]
1953 register.
1954 .LP
1955 .PD 0
1956 .Warning all group
1957 All warnings except
1958 .BR di ,
1959 .B mac
1960 and
1961 .BR reg .
1962 Intended to cover all warnings with traditional macro packages.
1963 .Warning break 4
1964 In fill mode, lines which could not be broken so that their length was
1965 less than the line length. This is enabled by default.
1966 .Warning char 1
1967 Non-existent characters. This is enabled by default.
1968 .Warning delim 8
1969 Missing or mismatched closing delimiters.
1970 .Warning di 256
1971 Use of
1972 .B \&.di
1973 or
1974 .B \&.da
1975 without an argument when there is no current diversion.
1976 .Warning el 16
1977 Use of the
1978 .B \.el
1979 request with no matching
1980 .B \.ie
1981 request.
1982 .Warning escape 32768
1983 Unrecognized escape sequence. Then the escape character is ignored.
1984 .Warning font 131072
1985 Non-existent fonts. This is enabled by default.
1986 .Warning ig 262144
1987 Illegal escapes in text ignored with the
1988 .B \.ig
1989 request. These are conditions that are errors when they occur outside
1990 of ignored text.
1991 .Warning mac 512
1992 Use of undefined strings, macros, and diversions. Automatically handled
1993 as empty. Usually, only one warning per name.
1994 .Warning missing 8192
1995 Request that is missing non-optional arguments.
1996 .Warning input 16384
1997 Illegal input character.
1998 .Warning number 2
1999 Invalid numeric expressions. This is enabled by default.
2000 .Warning range 64
2001 Out of range arguments.
2002 .Warning reg 1024
2003 Use of undefined number register. Automatically defined as having
2004 value 0. Usually, only one warning per name.
2005 .Warning right-brace 4096
2006 Use of
2007 .B \e}
2008 where a number was expected.
2009 .Warning scale 32
2010 Meaningless scaling indicators.
2011 .Warning space 65536
2012 Missing space between a request or macro and its argument. Then no
2013 macro is automatically defined. This is enabled by default. This
2014 warning will never occur in compatibility mode.
2015 .Warning syntax 128
2016 Dubious syntax in numeric expressions.
2017 .Warning tab 2048
2018 Inappropriate use of a tab character (either in an unquoted macro
2019 argument or where a number was expected).
2020 .Warning w group
2021 All warnings.
2022 .PD
2023 .LP
2024 .TS
2025 tab (@), box, expand;
2026 c c c | c c c | c c c
2027 R RI CB | R RI CB | R RI CB.
2028 Bit@Code@Warning@Bit@Code@Warning@Bit@Code@Warning
2029 _
2030 0@1@char@8@256@di@16@65536@space
2031 1@2@number@9@512@mac@17@131072@font
2032 2@4@break@10@1024@reg@18@262144@ig
2033 3@8@delim@11@2048@tab
2034 4@16@el@12@4096@right-brace
2035 5@32@scale@13@8192@missing
2036 6@64@range@14@16384@input
2037 7@128@syntax@15@32768@escape
2038 .TE
2039 .LP
2040 .\" --------------------------------------------------------------------
2041 .SH COMPATIBILITY
2042 .\" --------------------------------------------------------------------
2043 .I groff
2044 provides a
2045 .B compatibility mode
2046 that allows to process roff code written for classical
2047 .troff
2048 or for other implementations of roff in a consistent way.
2049 .LP
2050 Compatibility mode can be turned on with the
2051 .B \-C
2052 command line option, and turned on or off with the
2053 .B .cp
2054 request. The number register
2055 .B \en(.C
2056 is 1 if compatibility mode is on, 0 otherwise.
2057 .LP
2058 This became necessary because the GNU concept for long names causes some
2059 incompatibilities.
2060 .I Classical troff
2061 will interpret
2062 .IP
2063 .B
2064 \&.dsabcd
2065 .LP
2066 as defining a string
2067 .B ab
2068 with contents
2069 .BR cd .
2070 Normally,
2071 .I groff
2072 will interpret this as a call of a macro named
2073 .BR dsabcd .
2074 .LP
2075 Also
2076 .I classical troff
2077 will interpret
2078 .B \e*[
2079 or
2080 .B \en[
2081 as references to a string or number register called
2082 .BR [ .
2083 In
2084 .I GNU native
2085 .IR mode ,
2086 however, this will normally be interpreted as the start of a long name.
2087 .LP
2088 In
2089 .I compatibility
2090 .IR mode ,
2091 groff will interpret these things in the traditional way, but long names
2092 are not recognized.
2093 .LP
2094 On the other hand, groff in
2095 .I GNU native mode
2096 does not allow to use the escape sequences
2097 .BR \ee ,
2098 .BR \e| ,
2099 .BR \e^ ,
2100 .BR \e& ,
2101 .BR \e} ,
2102 .BR \e{ ,
2103 .BR \e (space),
2104 .BR \e' ,
2105 .BR \e` ,
2106 .BR \e- ,
2107 .BR \e_ ,
2108 .BR \e! ,
2109 .BR \e% ,
2110 and
2111 .B \ec
2112 in names of strings, macros, diversions, number registers, fonts or
2113 environments, whereas
2114 .I classical troff
2115 does. The
2116 .B \eA
2117 escape sequence can be helpful in avoiding these escape sequences in
2118 names.
2119 .LP
2120 Fractional pointsizes cause one noteworthy incompatibility.
2121 In
2122 .I classical
2123 .IR troff ,
2124 the
2125 .B .ps
2126 request ignores scale indicators and so
2127 .RS
2128 .LP
2129 .B .ps\ 10u
2130 .RE
2131 .LP
2132 will set the pointsize to 10 points, whereas in groff native mode the
2133 pointsize will be set to 10 scaled points.
2134 .LP
2135 In
2136 .I groff
2137 mode, there is a fundamental difference between unformatted input
2138 characters, and formatted output characters.
2139 Everything that affects how an output character will be output is stored
2140 with the character; once an output character has been constructed it is
2141 unaffected by any subsequent requests that are executed, including the
2142 .BR .bd ,
2143 .BR .cs ,
2144 .BR .tkf ,
2145 .BR .tr ,
2146 or
2147 .B .fp
2148 requests.
2149 .LP
2150 Normally output characters are constructed from input characters at the
2151 moment immediately before the character is added to the current output
2152 line.
2153 Macros, diversions and strings are all, in fact, the same type of object;
2154 they contain lists of input characters and output characters in any
2155 combination.
2156 .LP
2157 An output character does not behave like an input character for the
2158 purposes of macro processing; it does not inherit any of the special
2159 properties that the input character from which it was constructed might
2160 have had.
2161 The following example will make things clearer.
2162 .LP
2163 .RS
2164 .nf
2165 .ft B
2166 \&.di x
2167 \e\e\e\e
2168 \&.br
2169 \&.di
2170 \&.x
2171 .ft
2172 .fi
2173 .RE
2174 .LP
2175 In
2176 .I GNU mode
2177 this will be printed as
2178 .BR \e\e .
2179 So each pair of input backslashes
2180 .B \e\e
2181 is turned into a single output backslash
2182 .B \e
2183 and the resulting output backslashes are not interpreted as escape
2184 characters when they are reread.
2185 .LP
2186 .I Classical troff
2187 would interpret them as escape characters when they were reread and
2188 would end up printing a single backslash
2189 .BR \e .
2190 .LP
2191 The correct way to get a printable
2192 .B \e
2193 is to use the
2194 .B \ee
2195 escape sequence. This will always print a single instance of the
2196 current escape character, regardless of whether or not it is used in a
2197 diversion. It will also work in both GNU mode and compatibility mode.
2198 .LP
2199 To store an escape sequence in a diversion that will be interpreted when
2200 the diversion is reread, either the traditional
2201 .B \e!
2202 transparent output facility or the
2203 new
2204 .B \e?
2205 escape sequence can be used.
2206 .\" --------------------------------------------------------------------
2207 .SH BUGS
2208 .\" --------------------------------------------------------------------
2209 At the moment, the documentation of the groff system is in a state of
2210 change and evolution. It is possible that there are small
2211 inconsistencies between different documents temporarily.
2212 .\" --------------------------------------------------------------------
2213 .SH AUTHOR
2214 .\" --------------------------------------------------------------------
2215 This document is part of the GNU roff distribution. It was written by
2216 Bernd Warken <bwarken@mayn.de>.
2217 .LP
2218 It is distributed under the terms of the GFDL (GNU Free Documentation
2219 License) version 1.1 or later. You should have received a copy of the
2220 GFDL on your system, it is also available on-line under
2221 .IR <http://www.gnu.org/copyright/fdl.html> .
2222 .LP
2223 Formerly, the extensions of the groff language were kept in the manual
2224 page
2225 .BR troff (@MAN1EXT@).
2226 This document contains the essential parts of that documentation, but
2227 the gory details were left for the groff info file.
2228 .\" --------------------------------------------------------------------
2229 .SH "SEE ALSO"
2230 .\" --------------------------------------------------------------------
2231 The main source of information for the groff language is the
2232 .B groff
2233 .BR info (1)
2234 file.
2235 .LP
2236 For a survey of the groff system and further documentation pointers see
2237 .BR roff (@MAN7EXT@).
2238 .LP
2239 The formatter programs are described in
2240 .BR groff (@MAN1EXT@)
2241 and
2242 .BR troff (@MAN1EXT@).
2243 .LP
2244 The classical
2245 .I troff
2246 documentation is available on-line at
2247 .I http://cm.bell-labs.com/cm/cs/cstr.html
2248 and
2249 .IR http://www.kohala.com/start/troff/ .