Penguin
Annotated edit history of groff(7) version 4, including all changes. View license author blame.
Rev Author # Line
1 perry 1 GROFF
2 !!!GROFF
3 NAME
4 DESCRIPTION
5 GROFF ELEMENTS
6 CONTROL CHARACTERS
7 NUMERICAL EXPRESSIONS
8 CONDITIONS
9 REQUESTS
10 ESCAPE SEQUENCES
11 REGISTERS
12 WARNINGS
13 COMPATIBILITY
14 BUGS
15 AUTHOR
16 SEE ALSO
17 ----
18 !!NAME
19
20
21 groff - a short reference for the GNU roff language
22 !!DESCRIPTION
23
24
25 ''groff'' stands for ''GNU roff'' and is the free
26 implementation of the roff type-setting system. See
27 roff(7) for a survey and the background of the groff
28 system.
29
30
31 This document gives only short descriptions of the
32 predefined roff language elements as used in groff. Both the
33 classical features and the groff extensions are
34 provided.
35
36
37 Historically, the ''roff language'' was called
38 ''troff''. ''groff'' is compatible with the classical
39 system and provides proper extensions. So in GNU, the terms
40 ''roff'', ''troff'', and ''groff language'' could
41 be used as synonyms. However ''troff'' slightly tends to
42 refer more to the classical aspects, whereas ''groff''
43 emphasizes the GNU extensions, and ''roff'' is the
44 general term for the language.
45
46
47 This file is only a short version of the complete
48 documentation that is found in the ''groff''
49 info(1) file, which contains more detailed, actual,
50 and concise information.
51
52
53 The general syntax for writing groff documents is relatively
54 easy, but writing extensions to the roff language can be a
55 bit harder.
56
57
58 The roff language is line-oriented. There are only two kinds
59 of lines, control lines and text lines. The control lines
60 start with a control character, by default a period ``.'' or
61 a single quote ``'''; all other lines are text
62 lines.
63
64
65 __Control lines__ represent commands, optionally with
66 arguments. They have the following syntax. The leading
67 control character can be followed by a command name;
68 arguments, if any, are separated by blanks from the command
69 name and among themselves, for example,
70
71
72 .command_name arg1 arg2
73
74
75 For indentation, any number of space or tab characters can
76 be inserted between the leading control character and the
77 command name, but the control character must be on the first
78 position of the line.
79
80
81 __Text lines__ represent the parts that will be printed.
82 They can be modified by escape sequences, which are
83 recognized by a leading backslash . These are in-line or
84 even in-word formatting elements or functions. Some of these
85 take arguments separated by single quotes ``''', others are
86 regulated by a length encoding introduced by an open
87 parenthesis ( or enclosed in brackets [[ and ].
88
89
90 The roff language provides flexible instruments for writing
91 language extension, such as macros. When interpreting macro
92 definitions, the roff system enters a special operating
93 mode, called the __copy mode__.
94
95
96 The copy mode behavior can be quite tricky, but there are
97 some rules that ensure a safe usage.
98
99
100 1.
101
102
103 Printable backslashes must be denoted as e. To be more
104 precise, e represents the current escape character. To get a
105 backslash glyph, use
106
107
108 2.
109
110
111 Double all backslashes.
112
113
114 3.
115
116
117 Begin all text lines with the special non-spacing character
118
119
120 This does not produce the most efficient code, but it should
121 work as a first measure. For better strategies, see the
4 perry 122 groff info file and groff_tmac(5).
1 perry 123
124
125 Reading roff source files is easier, just reduce all double
126 backslashes to a single one in all macro
127 definitions.
128 !!GROFF ELEMENTS
129
130
131 The roff language elements add formatting information to a
132 text file. The fundamental elements are predefined commands
133 and variables that make roff a full-blown programming
134 language.
135
136
137 There are two kinds of roff commands, possibly with
138 arguments. __Requests__ are written on a line of their
139 own starting with a dot . or a ``''', whereas __Escape
140 sequences__ are in-line functions and in-word formatting
141 elements starting with a backslash .
142
143
144 The user can define her own formatting commands using the
145 .de request. These commands are called __macros__, but
146 they are used exactly like requests. Macro packages are
147 pre-defined sets of macros written in the groff language. A
148 user's possibilities to create escape sequences herself is
149 very limited, only special characters can be
150 mapped.
151
152
153 The groff language provides several kinds of variables with
154 different interfaces. There are pre-defined variables, but
155 the user can define her own variables as well.
156
157
158 __String__ variables store character sequences. They are
159 set with the .ds request and retrieved by the * escape
160 sequences.
161
162
163 __Register__ variables can store numerical values,
164 numbers with a scale unit, and occasionally string-like
165 objects. They are set with the .nr request and retrieved by
166 the n escape sequences.
167
168
169 __Environments__ allow the user to temporarily store
170 global formatting parameters like line length, font size,
171 etc. for later reuse. This is done by the .ev
172 request.
173
174
175 __Fonts__ are identified either by a name or by an
176 internal number. The current font is chosen by the .ft
177 request or by the f escape sequences. Each device has
178 special fonts, but the following fonts are available for all
179 devices. __R__ is the standard font Roman. __B__ is
180 its __bold__ counterpart. The ''italic'' font is
181 called __I__ is everywhere available, but on text
182 devices, it is displayed as an underlined Roman font. For
183 the graphical output devices, there exist constant-width
184 pendants of these font, __CR__, __CI__, and __CB__.
185 On text devices, all characters have a constant width
186 anyway.
187
188
189 Moreover, there are some advanced roff elements. A
190 __diversion__ stores information into a macro for later
191 usage. A __trap__ is a positional condition like a
192 certain number of lines from page top or in a diversion or
193 in the input. Some action can be prescribed to be run
194 automatically when the condition is met.
195
196
197 More detailed information can be found in the groff info
198 file.
199 !!CONTROL CHARACTERS
200
201
202 There is a small set of characters that have a special
203 controlling task in certain conditions.
204
205
206 .
207
208
209 A dot is only special at the beginning of a line or after
210 the condition in the requests .if, .ie, .el, and .while.
211 There it is the control character that introduces a request
212 (or macro). The special behavior can be delayed by using the
213 . escape. By using the .cc request, the control character
214 can be set to a different character, making the dot . a
215 non-special character.
216
217
218 In all other positions, it just means a dot character. In
219 text paragraphs, it is advantageous to start each sentence
220 at a line of its own.
221
222
223 '
224
225
226 The single quote has two controlling tasks. At the beginning
227 of a line and in the conditional requests it is the
228 non-breaking control character. That means that it
229 introduces a request like the dot, but with the additional
230 property that this request doesn't cause a linebreak. By
231 using the .c2 request, the non-break control character can
232 be set to a different character.
233
234
235 As a second task, it is the most commonly used argument
236 separator in some functional escape sequences (but any pair
237 of characters not part of the argument will work). In all
238 other positions, it denotes the single quote or apostrophe
239 character. Groff provides a printable representation with
240 the escape sequence.
241
242
243
244
245 The double quote is used to enclose arguments in requests
246 and macros. In the .ds and .as requests, a leading double
247 quote in the argument will be stripped off, making
248 everything else afterwards the string to be defined
249 (enabling leading whitespace). The escaped double quote
250 \(
251
252
253 \
254
255
256 The backslash usually introduces an escape sequence (this
257 can be changed with the ec request). A printed version of
258 the escape character is the e escape; a backslash glyph can
259 be obtained by
260
261
262 (
263
264
265 The open parenthesis is only special in escape sequences
266 when introducing an escape name or argument consisting of
267 exactly two characters. In groff, this behavior can be
268 replaced by the [[] construct.
269
270
271 [[
272
273
274 The opening bracket is only special in groff escape
275 sequences; there it is used to introduce a long escape name
276 or long escape argument. Otherwise, it is non-special, e.g.
277 in macro calls.
278
279
280 ]
281
282
283 The closing bracket is only special in groff escape
284 sequences; there it terminates a long escape name or long
285 escape argument. Otherwise, it is non-special.
286
287
288 space
289
290
291 Space characters are only functional characters. They
292 separate the arguments in requests or macros, and the words
293 in text lines. They are subject to groff's horizontal
294 spacing calculations. To get a defined space width, escape
295 sequences like \ (this is the escape character followed by a
296 space), |, ^, or h should be used.
297
298
299 newline
300
301
302 In text paragraphs, newlines mostly behave like space
303 characters. Continuation lines can be specified by an
304 escaped newline, i.e., by specifying a backslash \ as the
305 last character of a line.
306
307
308 tab
309
310
311 If a tab character occurs during text the interpreter makes
312 a horizontal jump to the next pre-defined tab position.
313 There is a sophisticated interface for handling tab
314 positions.
315 !!NUMERICAL EXPRESSIONS
316
317
318 A __numerical value__ is a signed or unsigned integer or
319 float with or without an appended scale indicator. A
320 __scale indicator__ is a one-character abbreviation for a
321 unit of measurement. A number followed by a scale indicator
322 signifies a size value. By default, numerical values do not
323 have a scale indicator, i.e., they are normal
324 numbers.
325
326
327 The roff language defines the following scale
328 indicators.
329
330
331 __Numerical expressions__ are combinations of the numerical values defined above with the arithmetical operators +, -, *, /, % (''modulo''), the comparative operators == (this is the same as =), ''and''), : (''or''), ! (''not''), and the parentheses ( and ).
332
333
334 Moreover, ''groff'' added the following operators for
335 numeri- cal expressions:
336
337
338 For details see the groff info file.
339 !!CONDITIONS
340
341
342 __Conditions__ occur in tests raised by the .if, .ie, and
343 the .while requests. The following table characterizes the
344 different types of conditions.
345 !!REQUESTS
346
347
348 This section provides a short reference for the predefined requests. In groff, request and macro names can be arbi- trarily long. No bracketing or marking of long names is needed.
349
350
351 Most requests take one or more arguments. The arguments are
352 separated by space characters (no tabs!); there is no
353 inherent limit for their length or number. An argument can
354 be enclosed by a pair of double quotes: This is very handy
355 if an argument contains space characters, e.g., arg with
356 space denotes a single argument.
357
358
359 Some requests have optional arguments with a different be-
360 haviour. Not all of these details are outlined here. Re- fer
361 to the groff info file for all details.
362
363
364 In the following request specifications, most argument names
365 were chosen to be descriptive. Only the following
366 denotations need clarification.
367
368
369 If an expression defined as N starts with a + sign the resulting value of the expression will be added to an al- ready existing value inherent to the related request, e.g. adding to a number register. If the expression starts with a - the value of the expression will be subtracted from the request value.
370
371
372 Without a sign, N replaces the existing value directly. To
373 assign a negative number either prepend 0 or
374 enclose the negative number in parentheses.
375
376
377 __REQUEST SHORT REFERENCE__
378
379
380 . Empty line, ignored. Useful for structuring
381 documents.
382
383
384 .\(
385
386
387 Complete line is a comment.
388
389
390 .ab string
391
392
393 Print string on standard error, exit program.
394
395
396 .ad
397
398
399 Begin line adjustment for output lines in cur- rent adjust
400 mode.
401
402
403 .ad c
404
405
406 Start line adjustment in mode c
407 (c=l,r,b,n).
408
409
410 .af register c
411
412
413 Assign format c to register
414 (c=l,i,I,a,A).
415
416
417 .aln alias register
418
419
420 Create alias name for register.
421
422
423 .als alias object
424
425
426 Create alias name for request, string, macro, or diversion
427 object.
428
429
430 .am macro
431
432
433 Append to macro until .. is called.
434
435
436 .am macro end
437
438
439 Append to macro until .end is called.
440
441
442 .am1 macro
443
444
445 Same as .am but with compatibility mode switched off during
446 macro expansion.
447
448
449 .am1 macro end
450
451
452 Same as .am but with compatibility mode switched off during
453 macro expansion.
454
455
456 .as stringvar anything
457
458
459 Append anything to stringvar.
460
461
462 .asciify diversion
463
464
465 Unformat ASCII characters, spaces, and some es- cape
466 sequences in diversion.
467
468
469 .backtrace
470
471
472 Print a backtrace of the input on stderr.
473
474
475 .bd font N
476
477
478 Embolden font by N-1 units.
479
480
481 .bd S font N
482
483
484 Embolden Special Font S when current font is
485 font.
486
487
488 .blm
489
490
491 Unset the blank line macro.
492
493
494 .blm macro
495
496
497 Set the blank line macro to macro.
498
499
500 .box
501
502
503 End current diversion.
504
505
506 .box macro
507
508
509 Divert to macro, omitting a partially filled
510 line.
511
512
513 .boxa
514
515
516 End current diversion.
517
518
519 .boxa macro
520
521
522 Divert and append to macro, omitting a partially
523 filled line.
524
525
526 .bp
527
528
529 Eject current page and begin new page.
530
531
532 .bp N
533
534
535 Eject current page; next page number
536 N.
537
538
539 .br
540
541
542 Line break.
543
544
545 .brp
546
547
548 Break and spread output line. Same as p.
549
550
551 .break
552
553
554 Break out of a while loop.
555
556
557 .c2
558
559
560 Reset no-break control character to ``'''.
561
562
563 .c2 c
564
565
566 Set no-break control character to c.
567
568
569 .cc
570
571
572 Reset control character to ..
573
574
575 .cc c
576
577
578 Set control character to c.
579
580
581 .ce
582
583
584 Center the next input line.
585
586
587 .ce N
588
589
590 Center following N input lines.
591
592
593 .cf filename
594
595
596 Copy contents of file filename unprocessed to stdout or to
597 the diversion.
598
599
600 .cflags mode c1 c2 ...
601
602
603 Treat characters c1, c2, ... according to
604 mode number.
605
606
607 .ch trap N
608
609
610 Change trap location to N.
611
612
613 .char c anything
614
615
616 Define character c to string anything.
617
618
619 .chop object
620
621
622 Chop the last character off macro, string, or diversion
623 object.
624
625
626 .close stream
627
628
629 Close the stream.
630
631
632 .continue
633
634
635 Finish the current iteration of a while loop.
636
637
638 .cp
639
640
641 Enable compatibility mode.
642
643
644 .cp N
645
646
647 If ''N'' is zero disable compatibility mode, other- wise
648 enable it.
649
650
651 .cs font N M
652
653
654 Set constant character width mode for font to N/36
655 ems with em M.
656
657
658 .cu N
659
660
661 Continuous underline in nroff, like .ul in
662 troff.
663
664
665 .da
666
667
668 End current diversion.
669
670
671 .da macro
672
673
674 Divert and append to macro.
675
676
677 .de macro
678
679
680 Define or redefine macro until .. is called.
681
682
683 .de macro end
684
685
686 Define or redefine macro until .end is called.
687
688
689 .de1 macro
690
691
692 Same as .de but with compatibility mode switched off during
693 macro expansion.
694
695
696 .de1 macro end
697
698
699 Same as .de but with compatibility mode switched off during
700 macro expansion.
701
702
703 .dei macro
704
705
706 Define or redefine a macro whose name is con- tained in the
707 string register macro until .. is called.
708
709
710 .dei macro end
711
712
713 Define or redefine a macro indirectly. macro and end are
714 string registers whose contents are interpolated for the
715 macro name and the end macro, respectively.
716
717
718 .di
719
720
721 End current diversion.
722
723
724 .di macro
725
726
727 Divert to macro.
728
729
730 .do name
731
732
733 Interpret .name with compatibility mode dis-
734 abled.
735
736
737 .ds stringvar anything
738
739
740 Set stringvar to anything.
741
742
743 .dt N trap
744
745
746 Set diversion trap to position N (default scale indicator
747 v).
748
749
750 .ec
751
752
753 Reset escape character to .
754
755
756 .ec c
757
758
759 Set escape character to c.
760
761
762 .ecr
763
764
765 Restore escape character saved with .ecs.
766
767
768 .ecs
769
770
771 Save current escape character.
772
773
774 .el anything
775
776
777 Else part for if-else (.ie) request.
778
779
780 .em macro
781
782
783 The macro will be run after the end of input.
784
785
786 .eo
787
788
789 Turn off escape character mechanism.
790
791
792 .ev
793
794
795 Switch to previous environment.
796
797
798 .ev env
799
800
801 Push down environment number or name env and switch to
802 it.
803
804
805 .evc env
806
807
808 Copy the contents of environment env to the cur- rent
809 environment. No pushing or popping.
810
811
812 .ex
813
814
815 Exit from roff processing.
816
817
818 .fam
819
820
821 Return to previous font family.
822
823
824 .fam name
825
826
827 Set the current font family to name.
828
829
830 .fc
831
832
833 Disable field mechanism.
834
835
836 .fc a
837
838
839 Set field delimiter to a and pad character to
840 space.
841
842
843 .fc a b
844
845
846 Set field delimiter to a and pad character to
847 b.
848
849
850 .fi
851
852
853 Fill output lines.
854
855
856 .fl
857
858
859 Flush output buffer.
860
861
862 .fp n font
863
864
865 Mount font on position n.
866
867
868 .fp n internal external
869
870
871 Mount font with long external name to short in- ternal name
872 on position n.
873
874
875 .fspecial font s1 s2...
876
877
878 When the current font is font, then the fonts
879 s1, s2, ... will be special.
880
881
882 .ft
883
884
885 Return to previous font. Same as fP.
886
887
888 .ft font
889
890
891 Change to font name or number font; same as f[[font]
892 escape sequence.
893
894
895 .ftr font1 font2
896
897
898 Translate font1 to font2.
899
900
901 .hc
902
903
904 Remove additional hyphenation indicator charac-
905 ter.
906
907
908 .hc c
909
910
911 Set up additional hyphenation indicator charac- ter
912 c.
913
914
915 .hcode c1 code1 c2 code2 ...
916
917
918 Set the hyphenation code of character c1 to code1,
919 that of c2 to code2, etc.
920
921
922 .hla lang
923
924
925 Set the current hyphenation language to
926 lang.
927
928
929 .hlm n
930
931
932 Set the maximum number of consecutive hyphenated lines to
933 n.
934
935
936 .hpf file
937
938
939 Read hyphenation patterns from file.
940
941
942 .hw words
943
944
945 List of words with exceptional hyphenation.
946
947
948 .hy N
949
950
951 Switch to hyphenation mode N.
952
953
954 .hym n
955
956
957 Set the hyphenation margin to n (default scale indicator
958 m).
959
960
961 .hys n
962
963
964 Set the hyphenation space to n.
965
966
967 .ie cond anything
968
969
970 If cond then anything else goto .el.
971
972
973 .if cond anything
974
975
976 If cond then anything; otherwise do
977 nothing.
978
979
980 .ig
981
982
983 Ignore text until .. is called.
984
985
986 .ig end
987
988
989 Ignore text until .end.
990
991
992 .in
993
994
995 Change to previous indent value.
996
997
998 .in N
999
1000
1001 Change indent according to N (default scale in- dicator
1002 m).
1003
1004
1005 .it N trap
1006
1007
1008 Set an input-line count trap at position
1009 N.
1010
1011
1012 .kern
1013
1014
1015 Enable pairwise kerning.
1016
1017
1018 .kern n
1019
1020
1021 If n is zero, disable pairwise kerning, other- wise enable
1022 it.
1023
1024
1025 .lc
1026
1027
1028 Remove leader repetition character.
1029
1030
1031 .lc c
1032
1033
1034 Set leader repetition character to c.
1035
1036
1037 .length register anything
1038
1039
1040 Write the length of the string anything in reg-
1041 ister.
1042
1043
1044 .linetabs
1045
1046
1047 Enable line-tabs mode (i.e., calculate tab posi- tions
1048 relative to output line).
1049
1050
1051 .linetabs n
1052
1053
1054 If n is zero, disable line-tabs mode, otherwise enable
1055 it.
1056
1057
1058 .lf N file
1059
1060
1061 Set input line number to N and filename to
1062 file.
1063
1064
1065 .lg N
1066
1067
1068 Ligature mode on if N.
1069
1070
1071 .ll
1072
1073
1074 Change to previous line length.
1075
1076
1077 .ll N
1078
1079
1080 Set line length according to N (default size 6.5i,
1081 default scale indicator m).
1082
1083
1084 .ls
1085
1086
1087 Change to the previous value of additional in- tra-line
1088 skip.
1089
1090
1091 .ls N
1092
1093
1094 Set additional intra-line skip value to N, i.e.,
1095 N-1 blank lines are inserted after each text output
1096 line.
1097
1098
1099 .lt N
1100
1101
1102 Length of title (default scale indicator m).
1103
1104
1105 .mc
1106
1107
1108 Margin character off.
1109
1110
1111 .mc c
1112
1113
1114 Print character c after each text line at actual distance
1115 from right margin.
1116
1117
1118 .mc c N
1119
1120
1121 Set margin character to c and distance to N from right
1122 margin (default scale indicator m).
1123
1124
1125 .mk register
1126
1127
1128 Mark current vertical position in
1129 register.
1130
1131
1132 .mso file
1133
1134
1135 The same as the .so request except that ''file'' is
1136 searched in the tmac directories.
1137
1138
1139 .na
1140
1141
1142 No output-line adjusting.
1143
1144
1145 .ne
1146
1147
1148 Need a one-line vertical space.
1149
1150
1151 .ne N
1152
1153
1154 Need N vertical space (default scale indica- tor
1155 v).
1156
1157
1158 .nf
1159
1160
1161 No filling or adjusting of output-lines.
1162
1163
1164 .nh
1165
1166
1167 No hyphenation.
1168
1169
1170 .nm
1171
1172
1173 Number mode off.
1174
1175
1176 .nm N M S I
1177
1178
1179 In line number mode, set number, multiple, spac- ing, and
1180 indent.
1181
1182
1183 .nn
1184
1185
1186 Do not number next line.
1187
1188
1189 .nn N
1190
1191
1192 Do not number next N lines.
1193
1194
1195 .nop anything
1196
1197
1198 Always execute anything.
1199
1200
1201 .nr register N M
1202
1203
1204 Define or modify register using N with auto-in- crement
1205 M.
1206
1207
1208 .nroff
1209
1210
1211 Make the built-in condition __n__ true and __t__
1212 false.
1213
1214
1215 .ns
1216
1217
1218 Turn no-space mode on.
1219
1220
1221 .nx filename
1222
1223
1224 Next file.
1225
1226
1227 .open stream filename
1228
1229
1230 Open filename for writing and associate the stream named
1231 stream with it.
1232
1233
1234 .opena stream filename
1235
1236
1237 Like .open but append to it.
1238
1239
1240 .os
1241
1242
1243 Output vertical distance that was saved by the .sv
1244 request.
1245
1246
1247 .pc
1248
1249
1250 Reset page number character to %.
1251
1252
1253 .pc c
1254
1255
1256 Page number character.
1257
1258
1259 .pi program
1260
1261
1262 Pipe output to program (nroff only).
1263
1264
1265 .pl
1266
1267
1268 Set page length to default 11i. The current page
1269 length is stored in .p.
1270
1271
1272 .pl N
1273
1274
1275 Change page length to N (default scale indica- tor
1276 v).
1277
1278
1279 .pm
1280
1281
1282 Print macro names and sizes (number of blocks of 128
1283 bytes).
1284
1285
1286 .pm t
1287
1288
1289 Print only total of sizes of macros (number of 128 bytes
1290 blocks).
1291
1292
1293 .pn N
1294
1295
1296 Next page number N.
1297
1298
1299 .pnr
1300
1301
1302 Print the names and contents of all currently defined number
1303 registers on stderr.
1304
1305
1306 .po
1307
1308
1309 Change to previous page offset. The current page offset is
1310 available in .o.
1311
1312
1313 .po N
1314
1315
1316 Page offset N.
1317
1318
1319 .ps
1320
1321
1322 Return to previous point-size.
1323
1324
1325 .ps N
1326
1327
1328 Point size; same as s[[N].
1329
1330
1331 .psbb filename
1332
1333
3 perry 1334 Get the bounding box of a !PostScript image file-
1 perry 1335 name.
1336
1337
1338 .pso command
1339
1340
1341 This behaves like the .so request except that input comes
1342 from the standard output of command.
1343
1344
1345 .ptr
1346
1347
1348 Print the names and positions of all traps (not including
1349 input line traps and diversion traps) on
1350 stderr.
1351
1352
1353 .rchar c1 c2...
1354
1355
1356 Remove the definitions of characters c1,
1357 c2, ...
1358
1359
1360 .rd prompt
1361
1362
1363 Read insertion.
1364
1365
1366 .return
1367
1368
1369 Return from a macro.
1370
1371
1372 .rj n
1373
1374
1375 Right justify the next n input lines.
1376
1377
1378 .rm name
1379
1380
1381 Remove request, macro, or string name.
1382
1383
1384 .rn old new
1385
1386
1387 Rename request, macro, or string old to
1388 new.
1389
1390
1391 .rnn reg1 reg2
1392
1393
1394 Rename register reg1 to reg2.
1395
1396
1397 .rr register
1398
1399
1400 Remove register.
1401
1402
1403 .rs
1404
1405
1406 Restore spacing; turn no-space mode off.
1407
1408
1409 .rt N
1410
1411
1412 Return ''(upward only)'' to marked vertical place
1413 (default scale indicator v).
1414
1415
1416 .shc
1417
1418
1419 Reset soft hyphen character to
1420
1421
1422 .shc c
1423
1424
1425 Set the soft hyphen character to c.
1426
1427
1428 .shift n
1429
1430
1431 In a macro, shift the arguments by n
1432 positions.
1433
1434
1435 .so filename
1436
1437
1438 Include source file.
1439
1440
1441 .sp
1442
1443
1444 Skip one line vertically.
1445
1446
1447 .sp N
1448
1449
1450 Space vertical distance N up or down according to sign of N
1451 (default scaling indicator v).
1452
1453
1454 .special s1 s2 ...
1455
1456
1457 Fonts s1, s2, etc. are special and will be
1458 searched for characters not in the current
1459 font.
1460
1461
1462 .ss N
1463
1464
1465 Space-character size set to N/12 of the spacewidth
1466 in the current font.
1467
1468
1469 .ss N M
1470
1471
1472 Space-character size set to N/12 and sentence space
1473 size set to M/12 of the spacewidth in the current
1474 font (=1/3 em).
1475
1476
1477 .sty n style
1478
1479
1480 Associate style with font position n.
1481
1482
1483 .substring register n1 n2
1484
1485
1486 Replace the string in register with the sub- string defined
1487 by the indices n1 and n2.
1488
1489
1490 .sv
1491
1492
1493 Save 1v of vertical space.
1494
1495
1496 .sv N
1497
1498
1499 Save the vertical distance N for later output with .os
1500 request.
1501
1502
1503 .sy command-line
1504
1505
1506 Execute program command-line.
1507
1508
1509 .ta T N
1510
1511
1512 Set tabs after every position that is a multiple of N
1513 (default scaling indicator m).
1514
1515
1516 .ta n1 n2 ... nn T r1 r2 ... rn
1517
1518
1519 Set tabs at positions n1, n2, ...,
1520 nn, then set tabs at nn+r1,
1521 nn+r2, ..., nn+rn, then
1522 at nn+rn+r1,
1523 nn+rn+r2, ...,
1524 nn+rn+rn, and so on.
1525
1526
1527 .tc
1528
1529
1530 Remove tab repition character.
1531
1532
1533 .tc c
1534
1535
1536 Set tab repetition character to c.
1537
1538
1539 .ti N
1540
1541
1542 Temporary indent next line (default scaling in- dicator
1543 m).
1544
1545
1546 .tkf font s1 n1 s2 n2
1547
1548
1549 Enable track kerning for font.
1550
1551
1552 .tl leftcenterright
1553
1554
1555 Three-part title.
1556
1557
1558 .tm anything
1559
1560
1561 Print anything on terminal (UNIX standard mes- sage
1562 output).
1563
1564
1565 .tm1 anything
1566
1567
1568 Print anything on terminal (UNIX standard mes- sage output),
1569 allowing leading whitespace if anything starts with (which
1570 will be stripped off).
1571
1572
1573 .tmc anything
1574
1575
1576 Similar to .tm1 without emitting a final new-
1577 line.
1578
1579
1580 .tr abcd....
1581
1582
1583 Translate a to b, c to d, etc. on
1584 output.
1585
1586
1587 .trf filename
1588
1589
1590 Transparently output the contents of file file-
1591 name.
1592
1593
1594 .trnt abcd....
1595
1596
1597 This is the same as the .tr request except that the
1598 translations do not apply to text that is transparently
1599 throughput into a diversion with !.
1600
1601
1602 .troff
1603
1604
1605 Make the built-in condition __t__ true and __n__
1606 false.
1607
1608
1609 .uf font
1610
1611
1612 Underline font set to font (to be switched to by
1613 .ul).
1614
1615
1616 .ul N
1617
1618
1619 Underline (italicize in troff) N input lines.
1620
1621
1622 .unformat diversion
1623
1624
1625 Unformat space characters and tabs, preserving font
1626 information in diversion.
1627
1628
1629 .vpt n
1630
1631
1632 Enable vertical position traps if n is non-zero, disable
1633 them otherwise.
1634
1635
1636 .vs
1637
1638
1639 Change to previous vertical base line spacing.
1640
1641
1642 .vs N
1643
1644
1645 Set vertical base line spacing to N. Default value
1646 is 12p.
1647
1648
1649 .warn n
1650
1651
1652 Set warnings code to n.
1653
1654
1655 .wh N trap
1656
1657
1658 Set location trap; negative means from page bot-
1659 tom.
1660
1661
1662 .while cond anything
1663
1664
1665 While condition cond is true, accept anything as
1666 input.
1667
1668
1669 .write stream anything
1670
1671
1672 Write anything to the stream named
1673 stream.
1674
1675
1676 Besides these standard groff requests, there might be fur-
1677 ther macro calls. They can originate from a macro package
1678 (see roff(7) for an overview) or from a
1679 preprocessor.
1680
1681
1682 Preprocessor macros are easy to be recognized. They en-
1683 close their code into a pair of characteristic
1684 macros.
1685 !!ESCAPE SEQUENCES
1686
1687
1688 Escape sequences are in-line language elements usually in- troduced by a backslash \ and followed by an escape name and sometimes by a required argument. Input processing is continued directly after the escaped character or the ar- gument resp. without an intervening separation character. So there must be a way to determine the end of the escape name and the end of the argument.
1689
1690
1691 This is done by enclosing names (escape name and arguments
1692 consisting of a variable name) by a pair of brackets [[name]
1693 and constant arguments (number expressions and characters)
1694 by apostrophes (ASCII 0x27) like
1695 ''constant''.
1696
1697
1698 There are abbreviations for short names. Two character
1699 escape names can be specified by an opening parenthesis like
1700 without a closing counterpart. And all one-character names
1701 different from the special characters [[ and ( can even be
1702 specified without a marker in the form c.
1703
1704
1705 Constant arguments of length 1 can omit the marker
1706 apos- trophes, too, but there is no two-character
1707 analogue.
1708
1709
1710 While 1-character escape sequences are mainly used for
1711 in-line functions and system related tasks, the 2-letter
1712 names following the construct are used for special
1713 characters predefined by the roff system. Names with more
1714 than two characters [[name] mostly denote user defined named
1715 characters (see the .char request).
1716
1717
1718 __SINGLE CHARACTER ESCAPES__
1719
1720
1721 \(
1722
1723
1724 Beginning of a comment. Everything up to the end of the line
1725 is ignored.
1726
1727
1728 #
1729
1730
1731 Everything up to and including the next newline is ignored.
1732 This is interpreted in copy mode. This is like \(
1733
1734
1735 *s
1736
1737
1738 The string stored in the string variable with 1-character
1739 name s.
1740
1741
1742 *(st
1743
1744
1745 The string stored in the string variable with 2-character
1746 name st.
1747
1748
1749 *[[stringvar]
1750
1751
1752 The string stored in the string variable with arbi- trary
1753 length name stringvar.
1754
1755
1756 $0
1757
1758
1759 The name by which the current macro was invoked. The .als
1760 request can make a macro have more than one
1761 name.
1762
1763
1764 $x
1765
1766
1767 Macro argument with 1-place number x, where x is a
1768 digit between 1 and 9.
1769
1770
1771 $(xy
1772
1773
1774 Macro argument with 2-digit number xy.
1775
1776
1777 $[[nexp]
1778
1779
1780 Macro argument with number nexp, where nexp is a
1781 numerical expression evaluating to an integer
1782 1.
1783
1784
1785 $*
1786
1787
1788 In a macro, the concatenation of all the arguments separated
1789 by spaces.
1790
1791
1792 $@
1793
1794
1795 In a macro, the concatenation of all the arguments with each
1796 surrounded by double quotes, and separat- ed by
1797 spaces.
1798
1799
1800 \
1801
1802
1803 reduces to a single backslash; useful to delay its
1804 interpretation as escape character in copy mode. For a
1805 printable backslash, use e.
1806
1807
1808 \
1809
1810
1811 The acute accent ; same as Unescaped: apos- trophe, right
1812 quotation mark, single quote (ASCII 0x27).
1813
1814
1815 `
1816
1817
1818 The grave accent ; same as Unescaped: left quote, backquote
1819 (ASCII 0x60).
1820
1821
1822 -
1823
1824
1825 The - sign in the current font.
1826
1827
1828 .
1829
1830
1831 An uninterpreted dot (period), even at start of
1832 line.
1833
1834
1835 %
1836
1837
1838 Default optional hyphenation character.
1839
1840
1841 !
1842
1843
1844 Transparent line indicator.
1845
1846
1847 ?anything__?__
1848
1849
1850 In a diversion, this will transparently embed any- thing in
1851 the diversion. anything is read in copy mode. See also the
1852 escape sequences ! and ?.
1853
1854
1855 space
1856
1857
1858 Unpaddable space-size space character (no line
1859 break).
1860
1861
1862 0
1863
1864
1865 Digit width.
1866
1867
1868 |
1869
1870
1871 1/6 em narrow space character; zero width in
1872 nroff.
1873
1874
1875 ^
1876
1877
1878 1/12 em half-narrow space character; zero width in
1879 nroff.
1880
1881
1882
1883
1884 Non-printable, zero width character.
1885
1886
1887 )
1888
1889
1890 Like
1891
1892
1893 /
1894
1895
1896 Increases the width of the preceding character so that the
1897 spacing between that character and the following character
1898 will be correct if the follow- ing character is a roman
1899 character.
1900
1901
1902 ,
1903
1904
1905 Modifies the spacing of the following character so that the
1906 spacing between that character and the preceding character
1907 will correct if the preceding character is a roman
1908 character.
1909
1910
1911 ~
1912
1913
1914 Unbreakable space that stretches like a normal in- ter-word
1915 space when a line is adjusted.
1916
1917
1918 :
1919
1920
1921 Inserts a zero-width break point (similar to % but without a
1922 soft hyphen character).
1923
1924
1925 newline
1926
1927
1928 Ignored newline, for continuation lines.
1929
1930
1931 {
1932
1933
1934 Begin conditional input.
1935
1936
1937 }
1938
1939
1940 End conditional input.
1941
1942
1943
1944
1945 The special character with 2-character name st, see
1946 section __SPECIAL CHARACTERS__.
1947
1948
1949 [[name]
1950
1951
1952 The named character with arbitrary length name
1953 name.
1954
1955
1956 a
1957
1958
1959 Non-interpreted leader character.
1960
1961
1962 Aanything
1963
1964
1965 If anything is acceptable as a name of a string, macro,
1966 diversion, register, environment or font it expands to
1967 1, and 0 otherwise.
1968
1969
1970 babc...
1971
1972
1973 Bracket building function.
1974
1975
1976 Banything
1977
1978
1979 If anything is acceptable as a valid numeric ex- pression it
1980 expands to 1, and 0
1981 otherwise.
1982
1983
1984 c
1985
1986
1987 Interrupt text processing.
1988
1989
1990 Cchar
1991
1992
1993 The character called char; same as [[char], but
1994 compatible to other roff versions.
1995
1996
1997 d
1998
1999
2000 Forward (down) 1/2 em vertical unit (1/2 line in
2001 nroff).
2002
2003
2004 Dcharseq
2005
2006
2007 Draw a graphical element defined by the characters in
2008 charseq; see groff info file for
2009 details.
2010
2011
2012 e
2013
2014
2015 Printable version of the current escape
2016 character.
2017
2018
2019 E
2020
2021
2022 Equivalent to an escape character, but is not in- terpreted
2023 in copy-mode.
2024
2025
2026 fF
2027
2028
2029 Change to font with 1-character name or 1-digit number
2030 F.
2031
2032
2033 f(fo
2034
2035
2036 Change to font with 2-characer name or 2-digit num- ber
2037 fo.
2038
2039
2040 f[[font]
2041
2042
2043 Change to font with arbitrary length name or number
2044 expression font.
2045
2046
2047 g[[reg]
2048
2049
2050 Return format of register with name reg suitable for .af.
2051 Alternative forms g(xy and gx.
2052
2053
2054 hN
2055
2056
2057 Local horizontal motion; move right N (left if neg-
2058 ative).
2059
2060
2061 HN
2062
2063
2064 Set height of current font to N.
2065
2066
2067 k[[reg]
2068
2069
2070 Mark horizontal input place in register with arbi- trary
2071 length name reg. Alternative forms k(xy and
2072 kx.
2073
2074
2075 lNc
2076
2077
2078 Horizontal line drawing function (optionally using character
2079 c).
2080
2081
2082 LNc
2083
2084
2085 Vertical line drawing function (optionally using character
2086 c).
2087
2088
2089 nr
2090
2091
2092 The numerical value stored in the register variable with the
2093 1-character name r.
2094
2095
2096 n(re
2097
2098
2099 The numerical value stored in the register variable with the
2100 2-character name re.
2101
2102
2103 n[[reg]
2104
2105
2106 The numerical value stored in the register variable with
2107 arbitrary lenght name reg.
2108
2109
2110 Nn
2111
2112
2113 Typeset the character with code n in the current font, no
2114 special fonts are searched. Useful for adding characters to
2115 a font using the .char re- quest.
2116
2117
2118 oabc...
2119
2120
2121 Overstrike characters a, b, c,
2122 etc.
2123
2124
2125 p
2126
2127
2128 Break and spread output line.
2129
2130
2131 r
2132
2133
2134 Reverse 1 em vertical motion (reverse line in
2135 nroff).
2136
2137
2138 Rname n
2139
2140
2141 The same as .nr name n.
2142
2143
2144 s[[N]
2145
2146
2147 Set the point size to ''N'' scaled points. Note the
2148 alternative forms __s__''''__[[__''N''__]__,
2149 __s'__''N''__'__,
2150 __s__''''__'__''N''__'__, s(xy,
2151 __s__''''__(__''xy'', sx. Same as .ps
2152 request.
2153
2154
2155 SN
2156
2157
2158 Slant output N degrees.
2159
2160
2161 t
2162
2163
2164 Non-interpreted horizontal tab.
2165
2166
2167 u
2168
2169
2170 Reverse (up) 1/2 em vertical motion (1/2 line in
2171 nroff).
2172
2173
2174 vN
2175
2176
2177 Local vertical motion; move down N (up if nega-
2178 tive).
2179
2180
2181 V[[env]
2182
2183
2184 The contents of the environment variable env. Al-
2185 ternative forms V(xy and Vx.
2186
2187
2188 wstring
2189
2190
2191 The width of the character sequence
2192 string.
2193
2194
2195 xN
2196
2197
2198 Extra line-space function (negative before, posi- tive
2199 after).
2200
2201
2202 Xstring
2203
2204
2205 Output string as device control function.
2206
2207
2208 Y[[name]
2209
2210
2211 Output string variable or macro name uninterpreted as device
2212 control function. Alternative forms Y(xy and
2213 Yx.
2214
2215
2216 zc
2217
2218
2219 Print c with zero width (without spacing).
2220
2221
2222 Zanything
2223
2224
2225 Print anything and then restore the horizontal and vertical
2226 position; anything may not contain tabs or
2227 leaders.
2228
2229
2230 The escape sequences e, ., \(
2231
2232
2233 Escape sequences starting with or [[ do not represent single
2234 character escape sequences, but introduce escape names with
2235 two or more characters.
2236
2237
2238 If a backslash is followed by a character that does not
2239 constitute a defined escape sequence the backslash is
2240 silently ignored and the character maps to
2241 itself.
2242
2243
2244 __SPECIAL CHARACTERS__
2245
2246
2247 Common special characters are predefined by escape se-
2248 quences of the form with characters x and y. Some
2249 of these exist in the usual font while most of them are only
2250 available in the special font. Below you'll find a selec-
2251 tion of the most important glyphs; a complete list can be
4 perry 2252 found in groff_char(7).
1 perry 2253
2254
2255
2256
2257 Bullet sign.
2258
2259
2260
2261
2262 Copyright.
2263
2264
2265
2266
2267 Cent.
2268
2269
2270
2271
2272 Double dagger.
2273
2274
2275
2276
2277 Degree.
2278
2279
2280
2281
2282 Dagger.
2283
2284
2285 --
2286
2287
2288 Em-dash.
2289
2290
2291 - -
2292
2293
2294 Hyphen.
2295
2296
2297
2298
2299 Registered sign.
2300
2301
2302
2303
2304 Section sign.
2305
2306
2307 _ _
2308
2309
2310 Underline character.
2311
2312
2313
2314
2315 Identical.
2316
2317
2318
2319
2320 Larger or equal.
2321
2322
2323
2324
2325 Less or equal.
2326
2327
2328
2329
2330 Not equal.
2331
2332
2333
2334
2335 Right arrow.
2336
2337
2338
2339
2340 Left arrow.
2341
2342
2343
2344
2345 Plus-minus sign.
2346 !!REGISTERS
2347
2348
2349 Registers are variables that store a value. In groff, most
2350 registers store numerical values (see section __NUMERI- CAL
2351 EXPRESSIONS__ above), but some can also hold a string
2352 value.
2353
2354
2355 Each register is given a name. Arbitrary registers can be
2356 defined and set with the request .nr
2357 register.
2358
2359
2360 The value stored in a register can be retrieved by the es-
2361 cape sequences introduced by n.
2362
2363
2364 Most useful are predefined registers. In the following the
2365 notation name is used to refer to a register called name to
2366 make clear that we speak about registers. Please keep in
2367 mind that the en[[] decoration is not part of the register
2368 name.
2369
2370
2371 __READ-ONLY REGISTERS__
2372
2373
2374 The following registers have predefined values that should
2375 not be modified by the user (usually, registers starting
2376 with a dot a read-only). Mostly, they provide information on
2377 the current settings or store results from request
2378 calls.
2379
2380
2381 n[[.$]
2382
2383
2384 Number of arguments in the current macro.
2385
2386
2387 n[[.a]
2388
2389
2390 Post-line extra line-space most recently uti- lized using
2391 x'N'.
2392
2393
2394 n[[.A]
2395
2396
2397 Set to 1 in __troff__ if option __-A__ is
2398 used; always 1 in __nroff__.
2399
2400
2401 n[[.c]
2402
2403
2404 Current input line number.
2405
2406
2407 n[[.C]
2408
2409
2410 1 if compatibility mode is in effect, 0 other-
2411 wise.
2412
2413
2414 n[[.cdp]
2415
2416
2417 The depth of the last character added to the current
2418 environment. It is positive if the character extends below
2419 the baseline.
2420
2421
2422 n[[.ce]
2423
2424
2425 The number of lines remaining to be centered, as set by the
2426 .ce request.
2427
2428
2429 n[[.cht]
2430
2431
2432 The height of the last character added to the current
2433 environment. It is positive if the character extends above
2434 the baseline.
2435
2436
2437 n[[.csk]
2438
2439
2440 The skew of the last character added to the cur- rent
2441 environment. The skew of a character is how far to the right
2442 of the center of a charac- ter the center of an accent over
2443 that character should be placed.
2444
2445
2446 n[[.d]
2447
2448
2449 Current vertical place in current diversion; equal to
2450 register nl.
2451
2452
2453 n[[.ev]
2454
2455
2456 The name or number of the current environment
2457 (string-valued).
2458
2459
2460 n[[.f]
2461
2462
2463 Current font number.
2464
2465
2466 n[[.fam]
2467
2468
2469 The current font family (string-valued).
2470
2471
2472 n[[.fp]
2473
2474
2475 The number of the next free font position.
2476
2477
2478 n[[.g]
2479
2480
2481 Always 1 in GNU troff. Macros should use it to test if
2482 running under groff.
2483
2484
2485 n[[.h]
2486
2487
2488 Text base-line high-water mark on current page or
2489 diversion.
2490
2491
2492 n[[.H]
2493
2494
2495 Available horizontal resolution in basic units.
2496
2497
2498 n[[.hla]
2499
2500
2501 The current hyphenation language as set by the __.hla__
2502 request.
2503
2504
2505 n[[.hlc]
2506
2507
2508 The number of immediately preceding consecutive hyphenated
2509 lines.
2510
2511
2512 n[[.hlm]
2513
2514
2515 The maximum allowed number of consecutive hy- phenated
2516 lines, as set by the .hlm request.
2517
2518
2519 n[[.hy]
2520
2521
2522 The current hyphenation flags (as set by the .hy
2523 request).
2524
2525
2526 n[[.hym]
2527
2528
2529 The current hyphenation margin (as set by the .hym
2530 request).
2531
2532
2533 n[[.hys]
2534
2535
2536 The current hyphenation space (as set by the .hys
2537 request).
2538
2539
2540 n[[.i]
2541
2542
2543 Current ident.
2544
2545
2546 n[[.in]
2547
2548
2549 The indent that applies to the current output
2550 line.
2551
2552
2553 n[[.int]
2554
2555
2556 Positive if last output line contains c.
2557
2558
2559 n[[.kern]
2560
2561
2562 1 if pairwise kerning is enabled, 0
2563 otherwise.
2564
2565
2566 n[[.l]
2567
2568
2569 Current line length.
2570
2571
2572 n[[.lg]
2573
2574
2575 The current ligature mode (as set by the .lg re-
2576 quest).
2577
2578
2579 n[[.linetabs]
2580
2581
2582 The current line-tabs mode (as set by the .linetabs
2583 request).
2584
2585
2586 n[[.ll]
2587
2588
2589 The line length that applies to the current out- put
2590 line.
2591
2592
2593 n[[.lt]
2594
2595
2596 The title length (as set by the .lt request).
2597
2598
2599 n[[.n]
2600
2601
2602 Length of text portion on previous output line.
2603
2604
2605 n[[.ne]
2606
2607
2608 The amount of space that was needed in the last .ne request
2609 that caused a trap to be sprung. Useful in conjunction with
2610 .trunc.
2611
2612
2613 n[[.ns]
2614
2615
2616 1 if in no-space mode, 0
2617 otherwise.
2618
2619
2620 n[[.o]
2621
2622
2623 Current page offset.
2624
2625
2626 n[[.p]
2627
2628
2629 Current page length.
2630
2631
2632 n[[.pn]
2633
2634
2635 The number of the next page: either the value set by a .pn
2636 request, or the number of the cur- rent page plus
2637 1.
2638
2639
2640 n[[.ps]
2641
2642
2643 The current pointsize in scaled points.
2644
2645
2646 n[[.psr]
2647
2648
2649 The last-requested pointsize in scaled points.
2650
2651
2652 n[[.rj]
2653
2654
2655 The number of lines to be right-justified as set by the rj
2656 request.
2657
2658
2659 n[[.s]
2660
2661
2662 Current point size as a decimal fraction.
2663
2664
2665 n[[.sr]
2666
2667
2668 The last requested pointsize in points as a dec- imal
2669 fraction (string-valued).
2670
2671
2672 n[[.t]
2673
2674
2675 Distance to the next trap.
2676
2677
2678 n[[.T]
2679
2680
2681 Set to 1 if option __-T__ is used.
2682
2683
2684 n[[.tabs]
2685
2686
2687 A string representation of the current tab set- tings
2688 suitable for use as an argument to the .ta
2689 request.
2690
2691
2692 n[[.trunc]
2693
2694
2695 The amount of vertical space truncated by the most recently
2696 sprung vertical position trap, or, if the trap was sprung by
2697 a .ne request, minus the amount of vertical motion produced
2698 by .ne. request. In other words, at the point a trap is
2699 sprung, it represents the difference of what the vertical
2700 position would have been but for the trap, and what the
2701 vertical position actually is. Useful in conjunction with
2702 the .ne regis- ter.
2703
2704
2705 n[[.ss]
2706
2707
2708 The value of the parameters set by the first ar- gument of
2709 the .ss request.
2710
2711
2712 n[[.sss]
2713
2714
2715 The value of the parameters set by the second argument of
2716 the .ss request.
2717
2718
2719 n[[.u]
2720
2721
2722 Equal to 1 bin fill mode and 0 in nofill mode.
2723
2724
2725 n[[.v]
2726
2727
2728 Current vertical line spacing.
2729
2730
2731 n[[.V]
2732
2733
2734 Available vertical resolution in basic units.
2735
2736
2737 n[[.vpt]
2738
2739
2740 1 if vertical position traps are enabled,
2741 0 oth- erwise.
2742
2743
2744 n[[.w]
2745
2746
2747 Width of previous character.
2748
2749
2750 n[[.warn]
2751
2752
2753 The sum of the number codes of the currently en- abled
2754 warnings.
2755
2756
2757 n[[.x]
2758
2759
2760 The major version number.
2761
2762
2763 n[[.y]
2764
2765
2766 The minor version number.
2767
2768
2769 n[[.Y]
2770
2771
2772 The revision number of groff.
2773
2774
2775 n[[.z]
2776
2777
2778 Name of current diversion.
2779
2780
2781 __WRITABLE REGISTERS__
2782
2783
2784 The following registers can be read and written by the us-
2785 er. They have predefined default values, but these can be
2786 modified for customizing a document.
2787
2788
2789 n[[%]
2790
2791
2792 Current page number.
2793
2794
2795 n[[c.]
2796
2797
2798 Current input line number.
2799
2800
2801 n[[ct]
2802
2803
2804 Character type (set by width function w).
2805
2806
2807 n[[dl]
2808
2809
2810 Maximal width of last completed diversion.
2811
2812
2813 n[[dn]
2814
2815
2816 Height of last completed diversion.
2817
2818
2819 n[[dw]
2820
2821
2822 Current day of week (1-7).
2823
2824
2825 n[[dy]
2826
2827
2828 Current day of month (1-31).
2829
2830
2831 n[[hp]
2832
2833
2834 Current horizontal position at input line.
2835
2836
2837 n[[llx]
2838
2839
3 perry 2840 Lower left x-coordinate (in !PostScript units) of a given
2841 !PostScript image (set by .psbb).
1 perry 2842
2843
2844 n[[lly]
2845
2846
3 perry 2847 Lower left y-coordinate (in !PostScript units) of a given
2848 !PostScript image (set by .psbb).
1 perry 2849
2850
2851 n[[ln]
2852
2853
2854 Output line number.
2855
2856
2857 n[[mo]
2858
2859
2860 Current month (1-12).
2861
2862
2863 n[[nl]
2864
2865
2866 Vertical position of last printed text
2867 base-line.
2868
2869
2870 n[[rsb]
2871
2872
2873 Like sb, but takes account of the heights and depths of
2874 characters.
2875
2876
2877 n[[rst]
2878
2879
2880 Like st, but takes account of the heights and depths of
2881 characters.
2882
2883
2884 n[[sb]
2885
2886
2887 Depth of string below base line (generated by width function
2888 w).
2889
2890
2891 n[[skw]
2892
2893
2894 Right skip width from the center of the last character in
2895 the w argument.
2896
2897
2898 n[[slimit]
2899
2900
2901 If greater than 0, the maximum number of objects on the
2902 input stack. If 0 there is no limit, i.e., recursion can
2903 continue until virtual memo- ry is exhausted.
2904
2905
2906 n[[ssc]
2907
2908
2909 The amount of horizontal space (possibly nega- tive) that
2910 should be added to the last character before a subscript
2911 (generated by width function w).
2912
2913
2914 n[[st]
2915
2916
2917 Height of string above base line (generated by width
2918 function w).
2919
2920
2921 n[[systat]
2922
2923
2924 The return value of the ''system()'' function exe- cuted
2925 by the last .sy request.
2926
2927
2928 n[[urx]
2929
2930
3 perry 2931 Upper right x-coordinate (in !PostScript units) of a given
2932 !PostScript image (set by .psbb).
1 perry 2933
2934
2935 n[[ury]
2936
2937
3 perry 2938 Upper right y-coordinate (in !PostScript units) of a given
2939 !PostScript image (set by .psbb).
1 perry 2940
2941
2942 n[[year]
2943
2944
2945 The current year (year 2000 compliant).
2946
2947
2948 n[[yr]
2949
2950
2951 Current year minus 1900. For Y2K compliance use register
2952 year instead.
2953 !!WARNINGS
2954
2955
2956 Each warning generated by groff is identified by a name and
2957 a code number. The codes are powers of 2 to allow
2958 bit-encoding with a single integer. There are also names
2959 that can be used to refer to groups of
2960 warnings.
2961
2962
2963 The name associated with a warning is used by the -w and -W
2964 options; the number code is used by the .warn request and by
2965 the n[[warn] register.
2966
2967
2968 all group
2969
2970
2971 All warnings except di, mac and reg. Intended to cover all
2972 warnings with traditional macro packages.
2973
2974
2975 break
2976
2977
2978 4
2979 In fill mode, lines which could not be broken so that their
2980 length was less than the line length. This is enabled by
2981 default.
2982
2983
2984 char 1
2985
2986
2987 Non-existent characters. This is enabled by
2988 default.
2989
2990
2991 delim
2992
2993
2994 8
2995 Missing or mismatched closing delimiters.
2996
2997
2998 di 256
2999
3000
3001 Use of .di or .da without an argument when there is no
3002 current diversion.
3003
3004
3005 el 16
3006
3007
3008 Use of the .el request with no matching .ie
3009 request.
3010
3011
3012 escape
3013
3014
3015 32768
3016 Unrecognized escape sequence. Then the escape character is
3017 ignored.
3018
3019
3020 font 131072
3021
3022
3023 Non-existent fonts. This is enabled by de-
3024 fault.
3025
3026
3027 ig 262144
3028
3029
3030 Illegal escapes in text ignored with the .ig request. These
3031 are conditions that are errors when they occur outside of
3032 ignored text.
3033
3034
3035 mac 512
3036
3037
3038 Use of undefined strings, macros, and diver- sions.
3039 Automatically handled as empty. Usu- ally, only one warning
3040 per name.
3041
3042
3043 missing
3044
3045
3046 8192
3047 Request that is missing non-optional argu-
3048 ments.
3049
3050
3051 input
3052
3053
3054 16384
3055 Illegal input character.
3056
3057
3058 number
3059
3060
3061 2
3062 Invalid numeric expressions. This is enabled by
3063 default.
3064
3065
3066 range
3067
3068
3069 64
3070 Out of range arguments.
3071
3072
3073 reg 1024
3074
3075
3076 Use of undefined number register. Automati- cally defined as
3077 having value 0. Usually, on- ly one warning per
3078 name.
3079
3080
3081 right-brace
3082
3083
3084 4096
3085 Use of } where a number was expected.
3086
3087
3088 scale
3089
3090
3091 32
3092 Meaningless scaling indicators.
3093
3094
3095 space
3096
3097
3098 65536
3099 Missing space between a request or macro and its argument.
3100 Then no macro is automatically defined. This is enabled by
3101 default. This warning will never occur in compatibility
3102 mode.
3103
3104
3105 syntax
3106
3107
3108 128
3109 Dubious syntax in numeric expressions.
3110
3111
3112 tab 2048
3113
3114
3115 Inappropriate use of a tab character (either in an unquoted
3116 macro argument or where a num- ber was
3117 expected).
3118
3119
3120 w group
3121
3122
3123 All warnings.
3124 !!COMPATIBILITY
3125
3126
3127 ''groff'' provides a __compatibility mode__ that allows to process roff code written for classical or for other implementa- tions of roff in a consistent way.
3128
3129
3130 Compatibility mode can be turned on with the -C command line
3131 option, and turned on or off with the .cp request. The
3132 number register n(.C is 1 if compatibility mode is
3133 on, 0 otherwise.
3134
3135
3136 This became necessary because the GNU concept for long names
3137 causes some incompatibilities. ''Classical troff'' will
3138 interpret
3139
3140
3141 __.dsabcd__
3142
3143
3144 as defining a string __ab__ with contents __cd__.
3145 Normally, ''groff'' will interpret this as a call of a
3146 macro named dsabcd.
3147
3148
3149 Also ''classical troff'' will interpret *[[ or n[[ as
3150 refer- ences to a string or number register called [[. In
3151 ''GNU na- tive mode'', however, this will normally be
3152 interpreted as the start of a long name.
3153
3154
3155 In ''compatibility mode'', groff will interpret these
3156 things in the traditional way, but long names are not
3157 recognized.
3158
3159
3160 On the other hand, groff in ''GNU native mode'' does not
3161 allow to use the escape sequences e, |, ^,
3162 ''classical troff'' does. The A escape sequence
3163 can be helpful in avoiding these escape sequences in
3164 names.
3165
3166
3167 Fractional pointsizes cause one noteworthy incompatibili-
3168 ty. In ''classical troff'', the .ps request ignores scale
3169 in- dicators and so
3170
3171
3172 __.ps 10u__
3173
3174
3175 will set the pointsize to 10 points, whereas in groff na-
3176 tive mode the pointsize will be set to 10 scaled
3177 points.
3178
3179
3180 In ''groff'' mode, there is a fundamental difference
3181 between unformatted input characters, and formatted output
3182 charac- ters. Everything that affects how an output
3183 character will be output is stored with the character; once
3184 an out- put character has been constructed it is unaffected
3185 by any subsequent requests that are executed, including the
3186 .bd, .cs, .tkf, .tr, or .fp requests.
3187
3188
3189 Normally output characters are constructed from input
3190 characters at the moment immediately before the character is
3191 added to the current output line. Macros, diversions and
3192 strings are all, in fact, the same type of object; they
3193 contain lists of input characters and output charac- ters in
3194 any combination.
3195
3196
3197 An output character does not behave like an input charac-
3198 ter for the purposes of macro processing; it does not in-
3199 herit any of the special properties that the input charac-
3200 ter from which it was constructed might have had. The
3201 following example will make things clearer.
3202
3203
3204 __.di x
3205 \\
3206 .br
3207 .di
3208 .x
3209 __
3210
3211
3212 In ''GNU mode'' this will be printed as \. So each pair
3213 of input backslashes \ is turned into a single output back-
3214 slash \ and the resulting output backslashes are not in-
3215 terpreted as escape characters when they are
3216 reread.
3217
3218
3219 ''Classical troff'' would interpret them as escape
3220 characters when they were reread and would end up printing a
3221 single backslash .
3222
3223
3224 The correct way to get a printable \ is to use the e es-
3225 cape sequence. This will always print a single instance of
3226 the current escape character, regardless of whether or not
3227 it is used in a diversion. It will also work in both GNU
3228 mode and compatibility mode.
3229
3230
3231 To store an escape sequence in a diversion that will be
3232 interpreted when the diversion is reread, either the tra-
3233 ditional ! transparent output facility or the new ? es- cape
3234 sequence can be used.
3235 !!BUGS
3236
3237
3238 At the moment, the documentation of the groff system is in a
3239 state of change and evolution. It is possible that there are
3240 small inconsistencies between different docu- ments
3241 temporarily.
3242
3243
3244 The __WARNINGS__ section belongs to
3245 troff(1).
3246 !!AUTHOR
3247
3248
3249 This document is part of groff, the GNU roff distribution.
3250 It was written by Bernd Warken
3251
3252
3253 It is distributed under the terms of the FDL (GNU Free
3254 Documentation License) version 1.1 or later. You should have
3255 received a copy of the FDL on your system, it is also
3256 available on-line under
3257
3258
3259 ''http://www.gnu.org/copyleft/fdl.html''.
3260
3261
3262 Formerly, the extensions of the groff language were kept in
3263 the manual page troff(1). This document contains the
3264 essential parts of that documentation, but the gory de-
3265 tails are found in the groff info file.
3266 !!SEE ALSO
3267
3268
3269 The main source of information for the groff language is the
3270 __groff info__(1) file.
3271
3272
3273 For a survey of roff and the groff system and further doc-
3274 umentation pointers see roff(7).
3275
3276
3277 The formatter programs are described in groff(1) and
3278 troff(1); a complete of all predefined glyph names
4 perry 3279 can be found in groff_char(7).
1 perry 3280
3281
3282 The classical ''troff'' documentation is available
3283 on-line at
3284
3285
3286 ''http://cm.bell-labs.com/cm/cs/cstr.html''
3287
3288
3289 and
3290
3291
3292 ''http://www.kohala.com/start/troff/''.
3293 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.