1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
|
This is groff, produced by makeinfo version 4.3d from ./groff.texinfo.
This manual documents GNU `troff' version 1.19.
Copyright (C) 1994-2000, 2001, 2002, 2003 Free Software Foundation,
Inc.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.1 or any later version published by the Free Software
Foundation; with no Invariant Sections, with the Front-Cover texts
being `A GNU Manual," and with the Back-Cover Texts as in (a)
below. A copy of the license is included in the section entitled
`GNU Free Documentation License."
(a) The FSF's Back-Cover Text is: `You have freedom to copy and
modify this GNU Manual, like GNU software. Copies published by
the Free Software Foundation raise funds for GNU development."
INFO-DIR-SECTION Typesetting
START-INFO-DIR-ENTRY
* Groff: (groff). The GNU troff document formatting system.
END-INFO-DIR-ENTRY
File: groff, Node: Warnings, Prev: Debugging, Up: Debugging
Warnings
--------
The warnings that can be given to `gtroff' are divided into the
following categories. The name associated with each warning is used by
the `-w' and `-W' options; the number is used by the `warn' request and
by the `.warn' register.
`char'
`1'
Non-existent glyphs.(1) (*note Warnings-Footnote-1::) This is
enabled by default.
`number'
`2'
Invalid numeric expressions. This is enabled by default. *Note
Expressions::.
`break'
`4'
In fill mode, lines which could not be broken so that their length
was less than the line length. This is enabled by default.
`delim'
`8'
Missing or mismatched closing delimiters.
`el'
`16'
Use of the `el' request with no matching `ie' request. *Note
if-else::.
`scale'
`32'
Meaningless scaling indicators.
`range'
`64'
Out of range arguments.
`syntax'
`128'
Dubious syntax in numeric expressions.
`di'
`256'
Use of `di' or `da' without an argument when there is no current
diversion.
`mac'
`512'
Use of undefined strings, macros and diversions. When an undefined
string, macro, or diversion is used, that string is automatically
defined as empty. So, in most cases, at most one warning is given
for each name.
`reg'
`1024'
Use of undefined number registers. When an undefined number
register is used, that register is automatically defined to have a
value of 0. So, in most cases, at most one warning is given for
use of a particular name.
`tab'
`2048'
Use of a tab character where a number was expected.
`right-brace'
`4096'
Use of `\}' where a number was expected.
`missing'
`8192'
Requests that are missing non-optional arguments.
`input'
`16384'
Invalid input characters.
`escape'
`32768'
Unrecognized escape sequences. When an unrecognized escape
sequence `\X' is encountered, the escape character is ignored, and
X is printed.
`space'
`65536'
Missing space between a request or macro and its argument. This
warning is given when an undefined name longer than two characters
is encountered, and the first two characters of the name make a
defined name. The request or macro is not invoked. When this
warning is given, no macro is automatically defined. This is
enabled by default. This warning never occurs in compatibility
mode.
`font'
`131072'
Non-existent fonts. This is enabled by default.
`ig'
`262144'
Invalid escapes in text ignored with the `ig' request. These are
conditions that are errors when they do not occur in ignored text.
`color'
`524288'
Color related warnings.
`all'
All warnings except `di', `mac' and `reg'. It is intended that
this covers all warnings that are useful with traditional macro
packages.
`w'
All warnings.
File: groff, Node: Warnings-Footnotes, Up: Warnings
(1) `char' is a misnomer since it reports missing glyphs - there
aren't missing input characters, only invalid ones.
File: groff, Node: Implementation Differences, Prev: Debugging, Up: gtroff Reference
Implementation Differences
==========================
GNU `troff' has a number of features which cause incompatibilities
with documents written with old versions of `troff'.
Long names cause some incompatibilities. UNIX `troff' interprets
.dsabcd
as defining a string `ab' with contents `cd'. Normally, GNU `troff'
interprets this as a call of a macro named `dsabcd'. Also UNIX `troff'
interprets `\*[' or `\n[' as references to a string or number register
called `['. In GNU `troff', however, this is normally interpreted as
the start of a long name. In compatibility mode GNU `troff' interprets
long names in the traditional way (which means that they are not
recognized as names).
- Request: .cp [n]
- Request: .do cmd
- Register: \n[.C]
If N is missing or non-zero, turn on compatibility mode;
otherwise, turn it off.
The read-only number register `.C' is 1 if compatibility mode is
on, 0 otherwise.
Compatibility mode can be also turned on with the `-C' command line
option.
The `do' request turns off compatibility mode while executing its
arguments as a `gtroff' command.
.do fam T
executes the `fam' request when compatibility mode is enabled.
`gtroff' restores the previous compatibility setting before
interpreting any files sourced by the CMD.
Two other features are controlled by `-C'. If not in compatibility
mode, GNU `troff' preserves the input level in delimited arguments:
.ds xx '
\w'abc\*(xxdef'
In compatibility mode, the string `72def'' is returned; without `-C'
the resulting string is `168' (assuming a TTY output device).
Finally, the escapes `\f', `\H', `\m', `\M', `\R', `\s', and `\S'
are transparent for recognizing the beginning of a line only in
compatibility mode (this is a rather obscure feature). For example,
the code
.de xx
Hallo!
..
\fB.xx\fP
prints `Hallo!' in bold face if in compatibility mode, and `.xx' in
bold face otherwise.
GNU `troff' does not allow the use of the escape sequences `\|',
`\^', `\&', `\{', `\}', `\<SP>', `\'', `\`', `\-', `\_', `\!', `\%',
and `\c' in names of strings, macros, diversions, number registers,
fonts or environments; UNIX `troff' does. The `\A' escape sequence
(*note Identifiers::) may be helpful in avoiding use of these escape
sequences in names.
Fractional point sizes cause one noteworthy incompatibility. In
UNIX `troff' the `ps' request ignores scale indicators and thus
.ps 10u
sets the point size to 10 points, whereas in GNU `troff' it sets the
point size to 10 scaled points. *Note Fractional Type Sizes::, for
more information.
In GNU `troff' there is a fundamental difference between
(unformatted) input characters and (formatted) output glyphs.
Everything that affects how a glyph is output is stored with the glyph
node; once a glyph node has been constructed it is unaffected by any
subsequent requests that are executed, including `bd', `cs', `tkf',
`tr', or `fp' requests. Normally glyphs are constructed from input
characters at the moment immediately before the glyph is added to the
current output line. Macros, diversions and strings are all, in fact,
the same type of object; they contain lists of input characters and
glyph nodes in any combination. A glyph node does not behave like an
input character for the purposes of macro processing; it does not
inherit any of the special properties that the input character from
which it was constructed might have had. For example,
.di x
\\\\
.br
.di
.x
prints `\\' in GNU `troff'; each pair of input backslashes is turned
into one output backslash and the resulting output backslashes are not
interpreted as escape characters when they are reread. UNIX `troff'
would interpret them as escape characters when they were reread and
would end up printing one `\'. The correct way to obtain a printable
backslash is to use the `\e' escape sequence: This always prints a
single instance of the current escape character, regardless of whether
or not it is used in a diversion; it also works in both GNU `troff' and
UNIX `troff'.(1) (*note Implementation Differences-Footnote-1::) To
store, for some reason, an escape sequence in a diversion that will be
interpreted when the diversion is reread, either use the traditional
`\!' transparent output facility, or, if this is unsuitable, the new
`\?' escape sequence.
*Note Diversions::, and *Note Gtroff Internals::, for more
information.
File: groff, Node: Implementation Differences-Footnotes, Up: Implementation Differences
(1) To be completely independent of the current escape character,
use `\(rs' which represents a reverse solidus (backslash) glyph.
File: groff, Node: Preprocessors, Next: Output Devices, Prev: gtroff Reference, Up: Top
Preprocessors
*************
This chapter describes all preprocessors that come with `groff' or
which are freely available.
* Menu:
* geqn::
* gtbl::
* gpic::
* ggrn::
* grap::
* grefer::
* gsoelim::
File: groff, Node: geqn, Next: gtbl, Prev: Preprocessors, Up: Preprocessors
`geqn'
======
* Menu:
* Invoking geqn::
File: groff, Node: Invoking geqn, Prev: geqn, Up: geqn
Invoking `geqn'
---------------
File: groff, Node: gtbl, Next: gpic, Prev: geqn, Up: Preprocessors
`gtbl'
======
* Menu:
* Invoking gtbl::
File: groff, Node: Invoking gtbl, Prev: gtbl, Up: gtbl
Invoking `gtbl'
---------------
File: groff, Node: gpic, Next: ggrn, Prev: gtbl, Up: Preprocessors
`gpic'
======
* Menu:
* Invoking gpic::
File: groff, Node: Invoking gpic, Prev: gpic, Up: gpic
Invoking `gpic'
---------------
File: groff, Node: ggrn, Next: grap, Prev: gpic, Up: Preprocessors
`ggrn'
======
* Menu:
* Invoking ggrn::
File: groff, Node: Invoking ggrn, Prev: ggrn, Up: ggrn
Invoking `ggrn'
---------------
File: groff, Node: grap, Next: grefer, Prev: ggrn, Up: Preprocessors
`grap'
======
A free implementation of `grap', written by Ted Faber, is available
as an extra package from the following address:
`http://www.lunabase.org/~faber/Vault/software/grap/'
File: groff, Node: grefer, Next: gsoelim, Prev: grap, Up: Preprocessors
`grefer'
========
* Menu:
* Invoking grefer::
File: groff, Node: Invoking grefer, Prev: grefer, Up: grefer
Invoking `grefer'
-----------------
File: groff, Node: gsoelim, Prev: grefer, Up: Preprocessors
`gsoelim'
=========
* Menu:
* Invoking gsoelim::
File: groff, Node: Invoking gsoelim, Prev: gsoelim, Up: gsoelim
Invoking `gsoelim'
------------------
File: groff, Node: Output Devices, Next: File formats, Prev: Preprocessors, Up: Top
Output Devices
**************
* Menu:
* Special Characters::
* grotty::
* grops::
* grodvi::
* grolj4::
* grolbp::
* grohtml::
* gxditview::
File: groff, Node: Special Characters, Next: grotty, Prev: Output Devices, Up: Output Devices
Special Characters
==================
*Note Font Files::.
File: groff, Node: grotty, Next: grops, Prev: Special Characters, Up: Output Devices
`grotty'
========
* Menu:
* Invoking grotty::
File: groff, Node: Invoking grotty, Prev: grotty, Up: grotty
Invoking `grotty'
-----------------
File: groff, Node: grops, Next: grodvi, Prev: grotty, Up: Output Devices
`grops'
=======
* Menu:
* Invoking grops::
* Embedding PostScript::
File: groff, Node: Invoking grops, Next: Embedding PostScript, Prev: grops, Up: grops
Invoking `grops'
----------------
File: groff, Node: Embedding PostScript, Prev: Invoking grops, Up: grops
Embedding POSTSCRIPT
--------------------
File: groff, Node: grodvi, Next: grolj4, Prev: grops, Up: Output Devices
`grodvi'
========
* Menu:
* Invoking grodvi::
File: groff, Node: Invoking grodvi, Prev: grodvi, Up: grodvi
Invoking `grodvi'
-----------------
File: groff, Node: grolj4, Next: grolbp, Prev: grodvi, Up: Output Devices
`grolj4'
========
* Menu:
* Invoking grolj4::
File: groff, Node: Invoking grolj4, Prev: grolj4, Up: grolj4
Invoking `grolj4'
-----------------
File: groff, Node: grolbp, Next: grohtml, Prev: grolj4, Up: Output Devices
`grolbp'
========
* Menu:
* Invoking grolbp::
File: groff, Node: Invoking grolbp, Prev: grolbp, Up: grolbp
Invoking `grolbp'
-----------------
File: groff, Node: grohtml, Next: gxditview, Prev: grolbp, Up: Output Devices
`grohtml'
=========
* Menu:
* Invoking grohtml::
* grohtml specific registers and strings::
File: groff, Node: Invoking grohtml, Next: grohtml specific registers and strings, Prev: grohtml, Up: grohtml
Invoking `grohtml'
------------------
File: groff, Node: grohtml specific registers and strings, Prev: Invoking grohtml, Up: grohtml
`grohtml' specific registers and strings
----------------------------------------
- Register: \n[ps4html]
- String: \*[www-image-template]
The registers `ps4html' and `www-image-template' are defined by
the `pre-grohtml' preprocessor. `pre-grohtml' reads in the
`troff' input, marks up the inline equations and passes the result
firstly to
troff -Tps -rps4html=1 -dwww-image-template=TEMPLATE
and secondly to
troff -Thtml
The PostScript device is used to create all the image files, and
the register `ps4html' enables the macro sets to ignore floating
keeps, footers, and headings.
The register `www-image-template' is set to the user specified
template name or the default name.
File: groff, Node: gxditview, Prev: grohtml, Up: Output Devices
`gxditview'
===========
* Menu:
* Invoking gxditview::
File: groff, Node: Invoking gxditview, Prev: gxditview, Up: gxditview
Invoking `gxditview'
--------------------
File: groff, Node: File formats, Next: Installation, Prev: Output Devices, Up: Top
File formats
************
All files read and written by `gtroff' are text files. The
following two sections describe their format.
* Menu:
* gtroff Output::
* Font Files::
File: groff, Node: gtroff Output, Next: Font Files, Prev: File formats, Up: File formats
`gtroff' Output
===============
This section describes the intermediate output format of GNU
`troff'. This output is produced by a run of `gtroff' before it is fed
into a device postprocessor program.
As `groff' is a wrapper program around `gtroff' that automatically
calls a postprocessor, this output does not show up normally. This is
why it is called "intermediate". `groff' provides the option `-Z' to
inhibit postprocessing, such that the produced intermediate output is
sent to standard output just like calling `gtroff' manually.
Here, the term "troff output" describes what is output by `gtroff',
while "intermediate output" refers to the language that is accepted by
the parser that prepares this output for the postprocessors. This
parser is smarter on whitespace and implements obsolete elements for
compatibility, otherwise both formats are the same.(1) (*note gtroff
Output-Footnote-1::)
The main purpose of the intermediate output concept is to facilitate
the development of postprocessors by providing a common programming
interface for all devices. It has a language of its own that is
completely different from the `gtroff' language. While the `gtroff'
language is a high-level programming language for text processing, the
intermediate output language is a kind of low-level assembler language
by specifying all positions on the page for writing and drawing.
The intermediate output produced by `gtroff' is fairly readable,
while output from AT&T `troff' is rather hard to understand because of
strange habits that are still supported, but not used any longer by
`gtroff'.
* Menu:
* Language Concepts::
* Command Reference::
* Intermediate Output Examples::
* Output Language Compatibility::
File: groff, Node: gtroff Output-Footnotes, Up: gtroff Output
(1) The parser and postprocessor for intermediate output can be
found in the file
`GROFF-SOURCE-DIR/src/libs/libdriver/input.cpp'.
File: groff, Node: Language Concepts, Next: Command Reference, Prev: gtroff Output, Up: gtroff Output
Language Concepts
-----------------
During the run of `gtroff', the input data is cracked down to the
information on what has to be printed at what position on the intended
device. So the language of the intermediate output format can be quite
small. Its only elements are commands with and without arguments. In
this section, the term "command" always refers to the intermediate
output language, and never to the `gtroff' language used for document
formatting. There are commands for positioning and text writing, for
drawing, and for device controlling.
* Menu:
* Separation::
* Argument Units::
* Document Parts::
File: groff, Node: Separation, Next: Argument Units, Prev: Language Concepts, Up: Language Concepts
Separation
..........
AT&T `troff' output has strange requirements on whitespace. The
`gtroff' output parser, however, is smart about whitespace by making it
maximally optional. The whitespace characters, i.e., the tab, space,
and newline characters, always have a syntactical meaning. They are
never printable because spacing within the output is always done by
positioning commands.
Any sequence of space or tab characters is treated as a single
"syntactical space". It separates commands and arguments, but is only
required when there would occur a clashing between the command code and
the arguments without the space. Most often, this happens when
variable-length command names, arguments, argument lists, or command
clusters meet. Commands and arguments with a known, fixed length need
not be separated by syntactical space.
A line break is a syntactical element, too. Every command argument
can be followed by whitespace, a comment, or a newline character. Thus
a "syntactical line break" is defined to consist of optional
syntactical space that is optionally followed by a comment, and a
newline character.
The normal commands, those for positioning and text, consist of a
single letter taking a fixed number of arguments. For historical
reasons, the parser allows to stack such commands on the same line, but
fortunately, in `gtroff''s intermediate output, every command with at
least one argument is followed by a line break, thus providing
excellent readability.
The other commands - those for drawing and device controlling - have
a more complicated structure; some recognize long command names, and
some take a variable number of arguments. So all `D' and `x' commands
were designed to request a syntactical line break after their last
argument. Only one command, `x X', has an argument that can stretch
over several lines; all other commands must have all of their arguments
on the same line as the command, i.e., the arguments may not be
splitted by a line break.
Empty lines (these are lines containing only space and/or a
comment), can occur everywhere. They are just ignored.
File: groff, Node: Argument Units, Next: Document Parts, Prev: Separation, Up: Language Concepts
Argument Units
..............
Some commands take integer arguments that are assumed to represent
values in a measurement unit, but the letter for the corresponding
scale indicator is not written with the output command arguments. Most
commands assume the scale indicator `u', the basic unit of the device,
some use `z', the scaled point unit of the device, while others, such
as the color commands, expect plain integers.
Note that single characters can have the eighth bit set, as can the
names of fonts and special characters. The names of characters and
fonts can be of arbitrary length. A character that is to be printed
will always be in the current font.
A string argument is always terminated by the next whitespace
character (space, tab, or newline); an embedded `#' character is
regarded as part of the argument, not as the beginning of a comment
command. An integer argument is already terminated by the next
non-digit character, which then is regarded as the first character of
the next argument or command.
File: groff, Node: Document Parts, Prev: Argument Units, Up: Language Concepts
Document Parts
..............
A correct intermediate output document consists of two parts, the
"prologue" and the "body".
The task of the prologue is to set the general device parameters
using three exactly specified commands. `gtroff''s prologue is
guaranteed to consist of the following three lines (in that order):
x T DEVICE
x res N H V
x init
with the arguments set as outlined in *Note Device Control Commands::.
Note that the parser for the intermediate output format is able to
swallow additional whitespace and comments as well even in the prologue.
The body is the main section for processing the document data.
Syntactically, it is a sequence of any commands different from the ones
used in the prologue. Processing is terminated as soon as the first
`x stop' command is encountered; the last line of any `gtroff'
intermediate output always contains such a command.
Semantically, the body is page oriented. A new page is started by a
`p' command. Positioning, writing, and drawing commands are always
done within the current page, so they cannot occur before the first `p'
command. Absolute positioning (by the `H' and `V' commands) is done
relative to the current page; all other positioning is done relative to
the current location within this page.
File: groff, Node: Command Reference, Next: Intermediate Output Examples, Prev: Language Concepts, Up: gtroff Output
Command Reference
-----------------
This section describes all intermediate output commands, both from
AT&T `troff' as well as the `gtroff' extensions.
* Menu:
* Comment Command::
* Simple Commands::
* Graphics Commands::
* Device Control Commands::
* Obsolete Command::
File: groff, Node: Comment Command, Next: Simple Commands, Prev: Command Reference, Up: Command Reference
Comment Command
...............
`#ANYTHING<end of line>'
A comment. Ignore any characters from the `#' character up to the
next newline character.
This command is the only possibility for commenting in the
intermediate output. Each comment can be preceded by arbitrary
syntactical space; every command can be terminated by a comment.
File: groff, Node: Simple Commands, Next: Graphics Commands, Prev: Comment Command, Up: Command Reference
Simple Commands
...............
The commands in this subsection have a command code consisting of a
single character, taking a fixed number of arguments. Most of them are
commands for positioning and text writing. These commands are smart
about whitespace. Optionally, syntactical space can be inserted
before, after, and between the command letter and its arguments. All
of these commands are stackable, i.e., they can be preceded by other
simple commands or followed by arbitrary other commands on the same
line. A separating syntactical space is only necessary when two
integer arguments would clash or if the preceding argument ends with a
string argument.
`C XXX<whitespace>'
Print a special character named XXX. The trailing syntactical
space or line break is necessary to allow glyph names of arbitrary
length. The glyph is printed at the current print position; the
glyph's size is read from the font file. The print position is
not changed.
`c G'
Print glyph G at the current print position;(1) (*note Simple
Commands-Footnote-1::) the glyph's size is read from the font
file. The print position is not changed.
`f N'
Set font to font number N (a non-negative integer).
`H N'
Move right to the absolute vertical position N (a non-negative
integer in basic units `u' relative to left edge of current page.
`h N'
Move N (a non-negative integer) basic units `u' horizontally to
the right. The original UNIX troff manual allows negative values
for N also, but `gtroff' doesn't use this.
`m COLOR-SCHEME [COMPONENT ...]'
Set the color for text (glyphs), line drawing, and the outline of
graphic objects using different color schemes; the analoguous
command for the filling color of graphic objects is `DF'. The
color components are specified as integer arguments between 0 and
65536. The number of color components and their meaning vary for
the different color schemes. These commands are generated by
`gtroff''s escape sequence `\m'. No position changing. These
commands are a `gtroff' extension.
`mc CYAN MAGENTA YELLOW'
Set color using the CMY color scheme, having the 3 color
components CYAN, MAGENTA, and YELLOW.
`md'
Set color to the default color value (black in most cases).
No component arguments.
`mg GRAY'
Set color to the shade of gray given by the argument, an
integer between 0 (black) and 65536 (white).
`mk CYAN MAGENTA YELLOW BLACK'
Set color using the CMYK color scheme, having the 4 color
components CYAN, MAGENTA, YELLOW, and BLACK.
`mr RED GREEN BLUE'
Set color using the RGB color scheme, having the 3 color
components RED, GREEN, and BLUE.
`N N'
Print glyph with index N (a non-negative integer) of the current
font. This command is a `gtroff' extension.
`n B A'
Inform the device about a line break, but no positioning is done by
this command. In AT&T `troff', the integer arguments B and A
informed about the space before and after the current line to make
the intermediate output more human readable without performing any
action. In `groff', they are just ignored, but they must be
provided for compatibility reasons.
`p N'
Begin a new page in the outprint. The page number is set to N.
This page is completely independent of pages formerly processed
even if those have the same page number. The vertical position on
the outprint is automatically set to 0. All positioning, writing,
and drawing is always done relative to a page, so a `p' command
must be issued before any of these commands.
`s N'
Set point size to N scaled points (this is unit `z'). AT&T
`troff' used the unit points (`p') instead. *Note Output Language
Compatibility::.
`t XXX<whitespace>'
`t XXX DUMMY-ARG<whitespace>'
Print a word, i.e., a sequence of characters XXX representing
output glyphs which names are single characters, terminated by a
space character or a line break; an optional second integer
argument is ignored (this allows the formatter to generate an even
number of arguments). The first glyph should be printed at the
current position, the current horizontal position should then be
increased by the width of the first glyph, and so on for each
glyph. The widths of the glyphs are read from the font file,
scaled for the current point size, and rounded to a multiple of
the horizontal resolution. Special characters cannot be printed
using this command (use the `C' command for special characters).
This command is a `gtroff' extension; it is only used for devices
whose `DESC' file contains the `tcommand' keyword (*note DESC File
Format::).
`u N XXX<whitespace>'
Print word with track kerning. This is the same as the `t'
command except that after printing each glyph, the current
horizontal position is increased by the sum of the width of that
glyph and N (an integer in basic units `u'). This command is a
`gtroff' extension; it is only used for devices whose `DESC' file
contains the `tcommand' keyword (*note DESC File Format::).
`V N'
Move down to the absolute vertical position N (a non-negative
integer in basic units `u') relative to upper edge of current page.
`v N'
Move N basic units `u' down (N is a non-negative integer). The
original UNIX troff manual allows negative values for N also, but
`gtroff' doesn't use this.
`w'
Informs about a paddable white space to increase readability. The
spacing itself must be performed explicitly by a move command.
File: groff, Node: Simple Commands-Footnotes, Up: Simple Commands
(1) `c' is actually a misnomer since it outputs a glyph.
File: groff, Node: Graphics Commands, Next: Device Control Commands, Prev: Simple Commands, Up: Command Reference
Graphics Commands
.................
Each graphics or drawing command in the intermediate output starts
with the letter `D', followed by one or two characters that specify a
subcommand; this is followed by a fixed or variable number of integer
arguments that are separated by a single space character. A `D'
command may not be followed by another command on the same line (apart
from a comment), so each `D' command is terminated by a syntactical
line break.
`gtroff' output follows the classical spacing rules (no space
between command and subcommand, all arguments are preceded by a single
space character), but the parser allows optional space between the
command letters and makes the space before the first argument optional.
As usual, each space can be any sequence of tab and space characters.
Some graphics commands can take a variable number of arguments. In
this case, they are integers representing a size measured in basic
units `u'. The arguments called H1, H2, ..., HN stand for horizontal
distances where positive means right, negative left. The arguments
called V1, V2, ..., VN stand for vertical distances where positive
means down, negative up. All these distances are offsets relative to
the current location.
Each graphics command directly corresponds to a similar `gtroff'
`\D' escape sequence. *Note Drawing Requests::.
Unknown `D' commands are assumed to be device-specific. Its
arguments are parsed as strings; the whole information is then sent to
the postprocessor.
In the following command reference, the syntax element <line break>
means a syntactical line break as defined above.
`D~ H1 V1 H2 V2 ... HN VN<line break>'
Draw B-spline from current position to offset (H1,V1), then to
offset (H2,V2), if given, etc. up to (HN,VN). This command takes
a variable number of argument pairs; the current position is moved
to the terminal point of the drawn curve.
`Da H1 V1 H2 V2<line break>'
Draw arc from current position to (H1,V1)+(H2,V2) with center at
(H1,V1); then move the current position to the final point of the
arc.
`DC D<line break>'
`DC D DUMMY-ARG<line break>'
Draw a solid circle using the current fill color with diameter D
(integer in basic units `u') with leftmost point at the current
position; then move the current position to the rightmost point of
the circle. An optional second integer argument is ignored (this
allows the formatter to generate an even number of arguments).
This command is a `gtroff' extension.
`Dc D<line break>'
Draw circle line with diameter D (integer in basic units `u') with
leftmost point at the current position; then move the current
position to the rightmost point of the circle.
`DE H V<line break>'
Draw a solid ellipse in the current fill color with a horizontal
diameter of H and a vertical diameter of V (both integers in basic
units `u') with the leftmost point at the current position; then
move to the rightmost point of the ellipse. This command is a
`gtroff' extension.
`De H V<line break>'
Draw an outlined ellipse with a horizontal diameter of H and a
vertical diameter of V (both integers in basic units `u') with the
leftmost point at current position; then move to the rightmost
point of the ellipse.
`DF COLOR-SCHEME [COMPONENT ...]<line break>'
Set fill color for solid drawing objects using different color
schemes; the analoguous command for setting the color of text, line
graphics, and the outline of graphic objects is `m'. The color
components are specified as integer arguments between 0 and 65536.
The number of color components and their meaning vary for the
different color schemes. These commands are generated by
`gtroff''s escape sequences `\D'F ...'' and `\M' (with no other
corresponding graphics commands). No position changing. This
command is a `gtroff' extension.
`DFc CYAN MAGENTA YELLOW<line break>'
Set fill color for solid drawing objects using the CMY color
scheme, having the 3 color components CYAN, MAGENTA, and
YELLOW.
`DFd<line break>'
Set fill color for solid drawing objects to the default fill
color value (black in most cases). No component arguments.
`DFg GRAY<line break>'
Set fill color for solid drawing objects to the shade of gray
given by the argument, an integer between 0 (black) and 65536
(white).
`DFk CYAN MAGENTA YELLOW BLACK<line break>'
Set fill color for solid drawing objects using the CMYK color
scheme, having the 4 color components CYAN, MAGENTA, YELLOW,
and BLACK.
`DFr RED GREEN BLUE<line break>'
Set fill color for solid drawing objects using the RGB color
scheme, having the 3 color components RED, GREEN, and BLUE.
`Df N<line break>'
The argument N must be an integer in the range -32767 to 32767.
0 <= N <= 1000
Set the color for filling solid drawing objects to a shade of
gray, where 0 corresponds to solid white, 1000 (the default)
to solid black, and values in between to intermediate shades
of gray; this is obsoleted by command `DFg'.
N < 0 or N > 1000
Set the filling color to the color that is currently being
used for the text and the outline, see command `m'. For
example, the command sequence
mg 0 0 65536
Df -1
sets all colors to blue.
No position changing. This command is a `gtroff' extension.
`Dl H V<line break>'
Draw line from current position to offset (H,V) (integers in basic
units `u'); then set current position to the end of the drawn line.
`Dp H1 V1 H2 V2 ... HN VN<line break>'
Draw a polygon line from current position to offset (H1,V1), from
there to offset (H2,V2), etc. up to offset (HN,VN), and from there
back to the starting position. For historical reasons, the
position is changed by adding the sum of all arguments with odd
index to the actual horizontal position and the even ones to the
vertical position. Although this doesn't make sense it is kept
for compatibility. This command is a `gtroff' extension.
`Dp H1 V1 H2 V2 ... HN VN<line break>'
Draw a solid polygon in the current fill color rather than an
outlined polygon, using the same arguments and positioning as the
corresponding `Dp' command. This command is a `gtroff' extension.
`Dt N<line break>'
Set the current line thickness to N (an integer in basic units
`u') if N>0; if N=0 select the smallest available line thickness;
if N<0 set the line thickness proportional to the point size (this
is the default before the first `Dt' command was specified). For
historical reasons, the horizontal position is changed by adding
the argument to the actual horizontal position, while the vertical
position is not changed. Although this doesn't make sense it is
kept for compatibility. This command is a `gtroff' extension.
File: groff, Node: Device Control Commands, Next: Obsolete Command, Prev: Graphics Commands, Up: Command Reference
Device Control Commands
.......................
Each device control command starts with the letter `x', followed by
a space character (optional or arbitrary space or tab in `gtroff') and
a subcommand letter or word; each argument (if any) must be preceded by
a syntactical space. All `x' commands are terminated by a syntactical
line break; no device control command can be followed by another
command on the same line (except a comment).
The subcommand is basically a single letter, but to increase
readability, it can be written as a word, i.e., an arbitrary sequence
of characters terminated by the next tab, space, or newline character.
All characters of the subcommand word but the first are simply ignored.
For example, `gtroff' outputs the initialization command `x i' as
`x init' and the resolution command `x r' as `x res'.
In the following, the syntax element <line break> means a
syntactical line break (*note Separation::).
`xF NAME<line break>'
The `F' stands for FILENAME.
Use NAME as the intended name for the current file in error
reports. This is useful for remembering the original file name
when `gtroff' uses an internal piping mechanism. The input file is
not changed by this command. This command is a `gtroff' extension.
`xf N S<line break>'
The `f' stands for FONT.
Mount font position N (a non-negative integer) with font named S
(a text word). *Note Font Positions::.
`xH N<line break>'
The `H' stands for HEIGHT.
Set glyph height to N (a positive integer in scaled points `z').
AT&T `troff' uses the unit points (`p') instead. *Note Output
Language Compatibility::.
`xi<line break>'
The `i' stands for INIT.
Initialize device. This is the third command of the prologue.
`xp<line break>'
The `p' stands for PAUSE.
Parsed but ignored. The original UNIX troff manual writes
pause device, can be restarted
`xr N H V<line break>'
The `r' stands for RESOLUTION.
Resolution is N, while H is the minimal horizontal motion, and V
the minimal vertical motion possible with this device; all
arguments are positive integers in basic units `u' per inch. This
is the second command of the prologue.
`xS N<line break>'
The `S' stands for SLANT.
Set slant to N (an integer in basic units `u').
`xs<line break>'
The `s' stands for STOP.
Terminates the processing of the current file; issued as the last
command of any intermediate troff output.
`xt<line break>'
The `t' stands for TRAILER.
Generate trailer information, if any. In GTROFF, this is actually
just ignored.
`xT XXX<line break>'
The `T' stands for TYPESETTER.
Set name of device to word XXX, a sequence of characters ended by
the next white space character. The possible device names coincide
with those from the `groff' `-T' option. This is the first
command of the prologue.
`xu N<line break>'
The `u' stands for UNDERLINE.
Configure underlining of spaces. If N is 1, start underlining of
spaces; if N is 0, stop underlining of spaces. This is needed for
the `cu' request in nroff mode and is ignored otherwise. This
command is a `gtroff' extension.
`xX ANYTHING<line break>'
The `x' stands for X-ESCAPE.
Send string ANYTHING uninterpreted to the device. If the line
following this command starts with a `+' character this line is
interpreted as a continuation line in the following sense. The
`+' is ignored, but a newline character is sent instead to the
device, the rest of the line is sent uninterpreted. The same
applies to all following lines until the first character of a line
is not a `+' character. This command is generated by the `gtroff'
escape sequence `\X'. The line-continuing feature is a `gtroff'
extension.
File: groff, Node: Obsolete Command, Prev: Device Control Commands, Up: Command Reference
Obsolete Command
................
In AT&T `troff' output, the writing of a single glyph is mostly done
by a very strange command that combines a horizontal move and a single
character giving the glyph name. It doesn't have a command code, but
is represented by a 3-character argument consisting of exactly 2 digits
and a character.
DDG
Move right DD (exactly two decimal digits) basic units `u', then
print glyph G (represented as a single character).
In `gtroff', arbitrary syntactical space around and within this
command is allowed to be added. Only when a preceding command on
the same line ends with an argument of variable length a
separating space is obligatory. In AT&T `troff', large clusters
of these and other commands are used, mostly without spaces; this
made such output almost unreadable.
For modern high-resolution devices, this command does not make sense
because the width of the glyphs can become much larger than two decimal
digits. In `gtroff', this is only used for the devices `X75',
`X75-12', `X100', and `X100-12'. For other devices, the commands `t'
and `u' provide a better functionality.
File: groff, Node: Intermediate Output Examples, Next: Output Language Compatibility, Prev: Command Reference, Up: gtroff Output
Intermediate Output Examples
----------------------------
This section presents the intermediate output generated from the same
input for three different devices. The input is the sentence `hell
world' fed into `gtroff' on the command line.
High-resolution device `ps'
This is the standard output of `gtroff' if no `-T' option is given.
shell> echo "hell world" | groff -Z -T ps
x T ps
x res 72000 1 1
x init
p1
x font 5 TR
f5
s10000
V12000
H72000
thell
wh2500
tw
H96620
torld
n12000 0
x trailer
V792000
x stop
This output can be fed into `grops' to get its representation as a
PostScript file.
Low-resolution device `latin1'
This is similar to the high-resolution device except that the
positioning is done at a minor scale. Some comments (lines
starting with `#') were added for clarification; they were not
generated by the formatter.
shell> echo "hell world" | groff -Z -T latin1
# prologue
x T latin1
x res 240 24 40
x init
# begin a new page
p1
# font setup
x font 1 R
f1
s10
# initial positioning on the page
V40
H0
# write text `hell'
thell
# inform about space, and issue a horizontal jump
wh24
# write text `world'
tworld
# announce line break, but do nothing because ...
n40 0
# ... the end of the document has been reached
x trailer
V2640
x stop
This output can be fed into `grotty' to get a formatted text
document.
AT&T `troff' output
Since a computer monitor has a very low resolution compared to
modern printers the intermediate output for the X Window devices
can use the jump-and-write command with its 2-digit displacements.
shell> echo "hell world" | groff -Z -T X100
x T X100
x res 100 1 1
x init
p1
x font 5 TR
f5
s10
V16
H100
# write text with jump-and-write commands
ch07e07l03lw06w11o07r05l03dh7
n16 0
x trailer
V1100
x stop
This output can be fed into `xditview' or `gxditview' for
displaying in X.
Due to the obsolete jump-and-write command, the text clusters in
the AT&T `troff' output are almost unreadable.
File: groff, Node: Output Language Compatibility, Prev: Intermediate Output Examples, Up: gtroff Output
Output Language Compatibility
-----------------------------
The intermediate output language of AT&T `troff' was first
documented in the UNIX troff manual, with later additions documented in
`A Typesetter-indenpendent TROFF', written by Brian Kernighan.
The `gtroff' intermediate output format is compatible with this
specification except for the following features.
* The classical quasi device independence is not yet implemented.
* The old hardware was very different from what we use today. So the
`groff' devices are also fundamentally different from the ones in
AT&T `troff'. For example, the AT&T PostScript device is called
`post' and has a resolution of only 720 units per inch, suitable
for printers 20 years ago, while `groff''s `ps' device has a
resolution of 72000 units per inch. Maybe, by implementing some
rescaling mechanism similar to the classical quasi device
independence, `groff' could emulate AT&T's `post' device.
* The B-spline command `D~' is correctly handled by the intermediate
output parser, but the drawing routines aren't implemented in some
of the postprocessor programs.
* The argument of the commands `s' and `x H' has the implicit unit
scaled point `z' in `gtroff', while AT&T `troff' has point (`p').
This isn't an incompatibility but a compatible extension, for both
units coincide for all devices without a `sizescale' parameter in
the `DESC' file, including all postprocessors from AT&T and
`groff''s text devices. The few `groff' devices with a
`sizescale' parameter either do not exist for AT&T `troff', have a
different name, or seem to have a different resolution. So
conflicts are very unlikely.
* The position changing after the commands `Dp', `DP', and `Dt' is
illogical, but as old versions of `gtroff' used this feature it is
kept for compatibility reasons.
File: groff, Node: Font Files, Prev: gtroff Output, Up: File formats
Font Files
==========
The `gtroff' font format is roughly a superset of the `ditroff' font
format (as used in later versions of AT&T `troff' and its descendants).
Unlike the `ditroff' font format, there is no associated binary
format; all files are text files.(1) (*note Font Files-Footnote-1::)
The font files for device NAME are stored in a directory `devNAME'.
There are two types of file: a device description file called `DESC'
and for each font F a font file called `F'.
* Menu:
* DESC File Format::
* Font File Format::
File: groff, Node: Font Files-Footnotes, Up: Font Files
(1) Plan 9 `troff' has also abandoned the binary format.
|