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
|
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: Line Control, Next: Page Layout, Prev: Line Layout, Up: gtroff Reference
Line Control
============
It is important to understand how `gtroff' handles input and output
lines.
Many escapes use positioning relative to the input line. For
example, this
This is a \h'|1.2i'test.
This is a
\h'|1.2i'test.
produces
This is a test.
This is a test.
The main usage of this feature is to define macros which act exactly
at the place where called.
.\" A simple macro to underline a word
.de underline
. nop \\$1\l'|0\[ul]'
..
In the above example, `|0' specifies a negative distance from the
current position (at the end of the just emitted argument `\$1') back
to the beginning of the input line. Thus, the `\l' escape draws a line
from right to left.
`gtroff' makes a difference between input and output line
continuation; the latter is also called "interrupting" a line.
- Escape: \<RET>
- Escape: \c
- Register: \n[.int]
Continue a line. `\<RET>' (this is a backslash at the end of a
line immediately followed by a newline) works on the input level,
suppressing the effects of the following newline in the input.
This is a \
.test
=> This is a .test
The `|' operator is also affected.
`\c' works on the output level. Anything after this escape on the
same line is ignored, except `\R' which works as usual. Anything
before `\c' on the same line will be appended to the current
partial output line. The next non-command line after an
interrupted line counts as a new input line.
The visual results depend on whether no-fill mode is active.
* If no-fill mode is active (using the `nf' request), the next
input text line after `\c' will be handled as a continuation
of the same input text line.
.nf
This is a \c
test.
=> This is a test.
* If fill mode is active (using the `fi' request), a word
interrupted with `\c' will be continued with the text on the
next input text line, without an intervening space.
This is a te\c
st.
=> This is a test.
Note that an intervening control line which causes a break is
stronger than `\c', flushing out the current partial line in the
usual way.
The `.int' register contains a positive value if the last output
line was interrupted with `\c'; this is associated with the
current environment (*note Environments::).
File: groff, Node: Page Layout, Next: Page Control, Prev: Line Control, Up: gtroff Reference
Page Layout
===========
`gtroff' provides some very primitive operations for controlling
page layout.
- Request: .pl [length]
- Request: .pl +length
- Request: .pl -length
- Register: \n[.p]
Set the "page length" to LENGTH (or increment or decrement the
current value by LENGTH). This is the length of the physical
output page. The default scaling indicator is `v'.
The current setting can be found in the read-only number register
`.p'.
Note that this only specifies the size of the page, not the top and
bottom margins. Those are not set by `gtroff' directly. *Note
Traps::, for further information on how to do this.
Negative `pl' values are possible also, but not very useful: No
trap is sprung, and each line is output on a single page (thus
suppressing all vertical spacing).
If no argument or an invalid argument is given, `pl' sets the page
length to 11i.
`gtroff' provides several operations which help in setting up top
and bottom titles (or headers and footers).
- Request: .tl 'left'center'right'
Print a "title line". It consists of three parts: a left
justified portion, a centered portion, and a right justified
portion. The argument separator `'' can be replaced with any
character not occurring in the title line. The `%' character is
replaced with the current page number. This character can be
changed with the `pc' request (see below).
Without argument, `tl' is ignored.
Some notes:
* A title line is not restricted to the top or bottom of a page.
* `tl' prints the title line immediately, ignoring a partially
filled line (which stays untouched).
* It is not an error to omit closing delimiters. For example,
`.tl /foo' is equivalent to `.tl /foo///': It prints a title
line with the left justified word `foo'; the centered and
right justfied parts are empty.
* `tl' accepts the same parameter delimiting characters as the
`\A' escape; see *Note Escapes::.
- Request: .lt [length]
- Request: .lt +length
- Request: .lt -length
- Register: \n[.lt]
The title line is printed using its own line length, which is
specified (or incremented or decremented) with the `lt' request.
Initially, the title line length is set to 6.5i. If a negative
line length is specified (which is not allowed), `gtroff' emits a
warning of type `range' and sets the title line length to zero.
The default scaling indicator is `m'. If `lt' is called without
an argument, the title length is reset to the previous value
before the last call to `lt'.
The current setting of this is available in the `.lt' read-only
number register; it is associated with the current environment
(*note Environments::).
- Request: .pn page
- Request: .pn +page
- Request: .pn -page
- Register: \n[.pn]
Change (increase or decrease) the page number of the _next_ page.
The only argument is the page number; the request is ignored
without a parameter.
The read-only number register `.pn' contains the number of the next
page: either the value set by a `pn' request, or the number of the
current page plus 1.
- Register: \n[%]
A read-write register holding the current page number.
- Request: .pc [char]
Change the page number character (used by the `tl' request) to a
different character. With no argument, this mechanism is disabled.
Note that this doesn't affect the number register `%'.
*Note Traps::.
File: groff, Node: Page Control, Next: Fonts and Symbols, Prev: Page Layout, Up: gtroff Reference
Page Control
============
- Request: .bp [page]
- Request: .bp +page
- Request: .bp -page
Stop processing the current page and move to the next page. This
request causes a break. It can also take an argument to set
(increase, decrease) the page number of the next page. The only
difference between `bp' and `pn' is that `pn' does not cause a
break or actually eject a page.
.de newpage \" define macro
'bp \" begin page
'sp .5i \" vertical space
.tl 'left top'center top'right top' \" title
'sp .3i \" vertical space
.. \" end macro
`bp' has no effect if not called within the top-level diversion
(*note Diversions::).
The number register `.pe' is set to 1 while `bp' is active. *Note
Page Location Traps::.
- Request: .ne [space]
It is often necessary to force a certain amount of space before a
new page occurs. This is most useful to make sure that there is
not a single "orphan" line left at the bottom of a page. The `ne'
request ensures that there is a certain distance, specified by the
first argument, before the next page is triggered (see *Note
Traps::, for further information). The default scaling indicator
for `ne' is `v'; the default value of SPACE is 1v if no argument
is given.
For example, to make sure that no fewer than 2 lines get orphaned,
do the following before each paragraph:
.ne 2
text text text
`ne' will then automatically cause a page break if there is space
for one line only.
- Request: .sv [space]
- Request: .os
`sv' is similar to the `ne' request; it reserves the specified
amount of vertical space. If the desired amount of space exists
before the next trap (or the bottom page boundary if no trap is
set), the space is output immediately (ignoring a partially filled
line which stays untouched). If there is not enough space, it is
stored for later output via the `os' request. The default value
is 1v if no argument is given; the default scaling indicator is
`v'.
Both `sv' and `os' ignore no-space mode. While the `sv' request
allows negative values for SPACE, `os' will ignore them.
- Register: \n[nl]
This register contains the current vertical position. If the
vertical position is zero and the top of page transition hasn't
happened yet, `nl' is set to negative value. `gtroff' itself does
this at the very beginning of a document before anything has been
printed, but the main usage is to plant a header trap on a page if
this page has already started.
Consider the following:
.de xxx
. sp
. tl ''Header''
. sp
..
.
First page.
.bp
.wh 0 xxx
.nr nl (-1)
Second page.
Result:
First page.
...
Header
Second page.
...
Without resetting `nl' to a negative value, the just planted trap
would be active beginning with the _next_ page, not the current
one.
*Note Diversions::, for a comparison with the `.h' and `.d'
registers.
File: groff, Node: Fonts and Symbols, Next: Sizes, Prev: Page Control, Up: gtroff Reference
Fonts and Symbols
=================
`gtroff' can switch fonts at any point in the text.
The basic set of fonts is `R', `I', `B', and `BI'. These are Times
Roman, Italic, Bold, and Bold Italic. For non-TTY devices, there is
also at least one symbol font which contains various special symbols
(Greek, mathematics).
* Menu:
* Changing Fonts::
* Font Families::
* Font Positions::
* Using Symbols::
* Special Fonts::
* Artificial Fonts::
* Ligatures and Kerning::
File: groff, Node: Changing Fonts, Next: Font Families, Prev: Fonts and Symbols, Up: Fonts and Symbols
Changing Fonts
--------------
- Request: .ft [font]
- Escape: \ff
- Escape: \f(fn
- Escape: \f[font]
The `ft' request and the `\f' escape change the current font to
FONT (one-character name F, two-character name FN).
If FONT is a style name (as set with the `sty' request or with the
`styles' command in the `DESC' file), use it within the current
font family (as set with the `fam' request, `\F' escape, or with
the `family' command in the `DESC' file).
With no argument or using `P' as an argument, `.ft' switches to
the previous font. Use `\f[]' to do this with the escape. The
old syntax forms `\fP' or `\f[P]' are also supported.
Fonts are generally specified as upper-case strings, which are
usually 1 to 4 characters representing an abbreviation or acronym
of the font name. This is no limitation, just a convention.
The example below produces two identical lines.
eggs, bacon,
.ft B
spam
.ft
and sausage.
eggs, bacon, \fBspam\fP and sausage.
Note that `\f' doesn't produce an input token in `gtroff'. As a
consequence, it can be used in requests like `mc' (which expects a
single character as an argument) to change the font on the fly:
.mc \f[I]x\f[]
*Note Font Positions::, for an alternative syntax.
- Request: .ftr f [g]
Translate font F to font G. Whenever a font named F is referred
to in a `\f' escape sequence, or in the `ft', `ul', `bd', `cs',
`tkf', `special', `fspecial', `fp', or `sty' requests, font G is
used. If G is missing or equal to F the translation is undone.
File: groff, Node: Font Families, Next: Font Positions, Prev: Changing Fonts, Up: Fonts and Symbols
Font Families
-------------
Due to the variety of fonts available, `gtroff' has added the
concept of "font families" and "font styles". The fonts are specified
as the concatenation of the font family and style. Specifying a font
without the family part causes `gtroff' to use that style of the
current family.
Currently, fonts for the devices `-Tps', `-Tdvi', and `-Tlbp' are
set up to this mechanism. By default, `gtroff' uses the Times family
with the four styles `R', `I', `B', and `BI'.
This way, it is possible to use the basic four fonts and to select a
different font family on the command line (*note Groff Options::).
- Request: .fam [family]
- Register: \n[.fam]
- Escape: \Ff
- Escape: \F(fm
- Escape: \F[family]
- Register: \n[.fn]
Switch font family to FAMILY (one-character name F, two-character
name FM). If no argument is given, switch back to the previous
font family. Use `\F[]' to do this with the escape. Note that
`\FP' doesn't work; it selects font family `P' instead.
The value at start-up is `T'. The current font family is
available in the read-only number register `.fam' (this is a
string-valued register); it is associated with the current
environment.
spam,
.fam H \" helvetica family
spam, \" used font is family H + style R = HR
.ft B \" family H + style B = font HB
spam,
.fam T \" times family
spam, \" used font is family T + style B = TB
.ft AR \" font AR (not a style)
baked beans,
.ft R \" family T + style R = font TR
and spam.
Note that `\F' doesn't produce an input token in `gtroff'. As a
consequence, it can be used in requests like `mc' (which expects a
single character as an argument) to change the font family on the
fly:
.mc \F[P]x\F[]
The `.fn' register contains the current "real font name" of the
current font. This is a string-valued register. If the current
font is a style, the value of `\n[.fn]' is the proper
concatenation of family and style name.
- Request: .sty n style
Associate STYLE with font position N. A font position can be
associated either with a font or with a style. The current font
is the index of a font position and so is also either a font or a
style. If it is a style, the font that is actually used is the
font which name is the concatenation of the name of the current
family and the name of the current style. For example, if the
current font is 1 and font position 1 is associated with style `R'
and the current font family is `T', then font `TR' will be used.
If the current font is not a style, then the current family is
ignored. If the requests `cs', `bd', `tkf', `uf', or `fspecial'
are applied to a style, they will instead be applied to the member
of the current family corresponding to that style.
N must be a non-negative integer value.
The default family can be set with the `-f' option (*note Groff
Options::). The `styles' command in the `DESC' file controls
which font positions (if any) are initially associated with styles
rather than fonts. For example, the default setting for
POSTSCRIPT fonts
styles R I B BI
is equivalent to
.sty 1 R
.sty 2 I
.sty 3 B
.sty 4 BI
`fam' and `\F' always check whether the current font position is
valid; this can give surprising results if the current font
position is associated with a style.
In the following example, we want to access the POSTSCRIPT font
`FooBar' from the font family `Foo':
.sty \n[.fp] Bar
.fam Foo
=> warning: can't find font `FooR'
The default font position at start-up is 1; for the POSTSCRIPT
device, this is associated with style `R', so `gtroff' tries to
open `FooR'.
A solution to this problem is to use a dummy font like the
following:
.fp 0 dummy TR \" set up dummy font at position 0
.sty \n[.fp] Bar \" register style `Bar'
.ft 0 \" switch to font at position 0
.fam Foo \" activate family `Foo'
.ft Bar \" switch to font `FooBar'
*Note Font Positions::.
File: groff, Node: Font Positions, Next: Using Symbols, Prev: Font Families, Up: Fonts and Symbols
Font Positions
--------------
For the sake of old phototypesetters and compatibility with old
versions of `troff', `gtroff' has the concept of font "positions", on
which various fonts are mounted.
- Request: .fp pos font [external-name]
- Register: \n[.f]
- Register: \n[.fp]
Mount font FONT at position POS (which must be a non-negative
integer). This numeric position can then be referred to with font
changing commands. When `gtroff' starts it is using font
position 1 (which must exist; position 0 is unused usually at
start-up).
The current font in use, as a font position, is available in the
read-only number register `.f'. This can be useful to remember the
current font for later recall. It is associated with the current
environment (*note Environments::).
.nr save-font \n[.f]
.ft B
... text text text ...
.ft \n[save-font]
The number of the next free font position is available in the
read-only number register `.fp'. This is useful when mounting a
new font, like so:
.fp \n[.fp] NEATOFONT
Fonts not listed in the `DESC' file are automatically mounted on
the next available font position when they are referenced. If a
font is to be mounted explicitly with the `fp' request on an unused
font position, it should be mounted on the first unused font
position, which can be found in the `.fp' register. Although
`gtroff' does not enforce this strictly, it is not allowed to
mount a font at a position whose number is much greater (approx.
1000 positions) than that of any currently used position.
The `fp' request has an optional third argument. This argument
gives the external name of the font, which is used for finding the
font description file. The second argument gives the internal
name of the font which is used to refer to the font in `gtroff'
after it has been mounted. If there is no third argument then the
internal name is used as the external name. This feature makes it
possible to use fonts with long names in compatibility mode.
Both the `ft' request and the `\f' escape have alternative syntax
forms to access font positions.
- Request: .ft nnn
- Escape: \fn
- Escape: \f(nn
- Escape: \f[nnn]
Change the current font position to NNN (one-digit position N,
two-digit position NN), which must be a non-negative integer.
If NNN is associated with a style (as set with the `sty' request
or with the `styles' command in the `DESC' file), use it within
the current font family (as set with the `fam' request, the `\F'
escape, or with the `family' command in the `DESC' file).
this is font 1
.ft 2
this is font 2
.ft \" switch back to font 1
.ft 3
this is font 3
.ft
this is font 1 again
*Note Changing Fonts::, for the standard syntax form.
File: groff, Node: Using Symbols, Next: Special Fonts, Prev: Font Positions, Up: Fonts and Symbols
Using Symbols
-------------
A "glyph" is a graphical representation of a "character". While a
character is an abstract entity containing semantic information, a
glyph is something which can be actually seen on screen or paper. It
is possible that a character has multiple glyph representation forms
(for example, the character `A' can be either written in a roman or an
italic font, yielding two different glyphs); sometimes more than one
character maps to a single glyph (this is a "ligature" - the most
common is `fi').
A "symbol" is simply a named glyph. Within `gtroff', all glyph
names of a particular font are defined in its font file. If the user
requests a glyph not available in this font, `gtroff' looks up an
ordered list of "special fonts". By default, the POSTSCRIPT output
device supports the two special fonts `SS' (slanted symbols) and `S'
(symbols) (the former is looked up before the latter). Other output
devices use different names for special fonts. Fonts mounted with the
`fonts' keyword in the `DESC' file are globally available. To install
additional special fonts locally (i.e. for a particular font), use the
`fspecial' request.
Here the exact rules how `gtroff' searches a given symbol:
* If the symbol has been defined with the `char' request, use it.
This hides a symbol with the same name in the current font.
* Check the current font.
* If the symbol has been defined with the `fchar' request, use it.
* Check whether the current font has a font-specific list of special
fonts; test all fonts in the order of appearance in the last
`fspecial' call if appropriate.
* If the symbol has been defined with the `fschar' request for the
current font, use it.
* Check all fonts in the order of appearance in the last `special'
call.
* If the symbol has been defined with the `schar' request, use it.
* As a last resort, consult all fonts loaded up to now for special
fonts and check them, starting with the lowest font number. Note
that this can sometimes lead to surprising results since the
`fonts' line in the `DESC' file often contains empty positions
which are filled later on. For example, consider the following:
fonts 3 0 0 FOO
This mounts font `foo' at font position 3. We assume that `FOO'
is a special font, containing glyph `foo', and that no font has
been loaded yet. The line
.fspecial BAR BAZ
makes font `BAZ' special only if font `BAR' is active. We further
assume that `BAZ' is really a special font, i.e., the font
description file contains the `special' keyword, and that it also
contains glyph `foo' with a special shape fitting to font `BAR'.
After executing `fspecial', font `BAR' is loaded at font
position 1, and `BAZ' at position 2.
We now switch to a new font `XXX', trying to access glyph `foo'
which is assumed to be missing. There are neither font-specific
special fonts for `XXX' nor any other fonts made special with the
`special' request, so `gtroff' starts the search for special fonts
in the list of already mounted fonts, with increasing font
positions. Consequently, it finds `BAZ' before `FOO' even for
`XXX' which is not the intended behaviour.
*Note Font Files::, and *Note Special Fonts::, for more details.
The list of available symbols is device dependent; see the
`groff_char(7)' man page for a complete list of all glyphs. For
example, say
man -Tdvi groff_char > groff_char.dvi
for a list using the default DVI fonts (not all versions of the `man'
program support the `-T' option). If you want to use an additional
macro package to change the used fonts, `groff' must be called directly:
groff -Tdvi -mec -man groff_char.7 > groff_char.dvi
Glyph names not listed in groff_char(7) are derived algorithmically,
using a simplified version of the Adobe Glyph List (AGL) algorithm
described in
`http://partners.adobe.com/asn/developer/typeforum/unicodegn.html'.
The (frozen) set of glyph names which can't be derived algorithmically
is called "groff glyph list (GGL)".
* A glyph for Unicode character U+XXXX[X[X]] which is not a
composite character will be named `uXXXX[X[X]]'. X must be an
uppercase hexadecimal digit. Examples: `u1234', `u008E',
`u12DB8'. The largest Unicode value is 0x10FFFF. There must be at
least four `X' digits; if necessary, add leading zeroes (after the
`u'). No zero padding is allowed for character codes greater than
0xFFFF. Surrogates (i.e., Unicode values greater than 0xFFFF
represented with character codes from the surrogate area
U+D800-U+DFFF) are not allowed too.
* A glyph representing more than a single input character will be
named
`u' COMPONENT1 `_' COMPONENT2 `_' COMPONENT3 ...
Example: `u0045_0302_0301'.
For simplicity, all Unicode characters which are composites must be
decomposed maximally (this is normalization form D in the Unicode
standard); for example, `u00CA_0301' is not a valid glyph name
since U+00CA (LATIN CAPITAL LETTER E WITH CIRCUMFLEX) can be
further decomposed into U+0045 (LATIN CAPITAL LETTER E) and U+0302
(COMBINING CIRCUMFLEX ACCENT). `u0045_0302_0301' is thus the
glyph name for U+1EBE, LATIN CAPITAL LETTER E WITH CIRCUMFLEX AND
ACUTE.
* groff maintains a table to decompose all algorithmically derived
glyph names which are composites itself. For example, `u0100'
(LATIN LETTER A WITH MACRON) will be automatically decomposed into
`u0041_0304'. Additionally, a glyph name of the GGL is preferred
to an algorithmically derived glyph name; groff also automatically
does the mapping. Example: The glyph `u0045_0302' will be mapped
to `^E'.
* glyph names of the GGL can't be used in composite glyph names; for
example, `^E_u0301' is invalid.
- Escape: \(nm
- Escape: \[name]
- Escape: \[component1 component2 ...]
Insert a symbol NAME (two-character name NM) or a composite glyph
with component glyphs COMPONENT1, COMPONENT2, .... There is no
special syntax for one-character names - the natural form `\N'
would collide with escapes.(1) (*note Using Symbols-Footnote-1::)
If NAME is undefined, a warning of type `char' is generated, and
the escape is ignored. *Note Debugging::, for information about
warnings.
groff resolves `\[...]' with more than a single component as
follows:
* Any component which is found in the GGL will be converted to
the `uXXXX' form.
* Any component `uXXXX' which is found in the list of
decomposable glyphs will be decomposed.
* The resulting elements are then concatenated with `_'
inbetween, dropping the leading `u' in all elements but the
first.
No check for the existence of any component (similar to `tr'
request) will be done.
Examples:
`\[A ho]'
`A' maps to `u0041', `ho' maps to `u02DB', thus the final
glyph name would be `u0041_02DB'. Note this is not the
expected result: The ogonek glyph `ho' is a spacing ogonek,
but for a proper composite a non-spacing ogonek (U+0328) is
necessary. Looking into the file `composite.tmac' one can
find `.composite ho u0328' which changes the mapping of `ho'
while a composite glyph name is constructed, causing the
final glyph name to be `u0041_0328'.
`\[^E u0301]'
`\[^E aa]'
`\[E a^ aa]'
`\[E ^ ']'
`^E' maps to `u0045_0302', thus the final glyph name is
`u0045_0302_0301' in all forms (assuming proper calls of the
`composite' request).
It is not possible to define glyphs with names like `A ho' within
a groff font file. This is not really a limitation; instead, you
have to define `u0041_0328'.
- Escape: \C'xxx'
Typeset the glyph named XXX.(2) (*note Using Symbols-Footnote-2::)
Normally it is more convenient to use `\[XXX]', but `\C' has the
advantage that it is compatible with newer versions of AT&T
`troff' and is available in compatibility mode.
- Request: .composite from to
Map glyph name FROM to glyph name TO if it is used in `\[...]'
with more than one component. See above for examples.
This mapping is based on glyph names only; no check for the
existence of either glyph is done.
A set of default mappings for many accents can be found in the file
`composite.tmac' which is loaded at start-up.
- Escape: \N'n'
Typeset the glyph with code N in the current font (`n' is *not*
the input character code). The number N can be any non-negative
decimal integer. Most devices only have glyphs with codes between
0 and 255; the Unicode output device uses codes in the range
0-65535. If the current font does not contain a glyph with that
code, special fonts are _not_ searched. The `\N' escape sequence
can be conveniently used in conjunction with the `char' request:
.char \[phone] \f[ZD]\N'37'
The code of each glyph is given in the fourth column in the font
description file after the `charset' command. It is possible to
include unnamed glyphs in the font description file by using a
name of `---'; the `\N' escape sequence is the only way to use
these.
No kerning is applied to glyphs accessed with `\N'.
Some escape sequences directly map onto special glyphs.
- Escape: \'
This is a backslash followed by the apostrophe character, ASCII
character `0x27' (EBCDIC character `0x7D'). The same as `\[aa]',
the acute accent.
- Escape: \`
This is a backslash followed by ASCII character `0x60' (EBCDIC
character `0x79' usually). The same as `\[ga]', the grave accent.
- Escape: \-
This is the same as `\[-]', the minus sign in the current font.
- Request: .cflags n c1 c2 ...
Input characters and symbols have certain properties associated
with it.(3) (*note Using Symbols-Footnote-3::) These properties
can be modified with the `cflags' request. The first argument is
the sum of the desired flags and the remaining arguments are the
characters or symbols to have those properties. It is possible to
omit the spaces between the characters or symbols.
`1'
The character ends sentences (initially characters `.?!' have
this property).
`2'
Lines can be broken before the character (initially no
characters have this property).
`4'
Lines can be broken after the character (initially the
character `-' and the symbols `\[hy]' and `\[em]' have this
property).
`8'
The character overlaps horizontally (initially the symbols
`\[ul]', `\[rn]', `\[ru]', `\[radicalex', and `\[sqrtex]'
have this property).
`16'
The character overlaps vertically (initially symbol `\[br]'
has this property).
`32'
An end-of-sentence character followed by any number of
characters with this property is treated as the end of a
sentence if followed by a newline or two spaces; in other
words the character is "transparent" for the purposes of
end-of-sentence recognition - this is the same as having a
zero space factor in TeX (initially characters `"')]*' and
the symbols `\[dg]' and `\[rq]' have this property).
- Request: .char g [string]
- Request: .fchar g [string]
- Request: .fschar f g [string]
- Request: .schar g [string]
Define a new glyph G to be STRING (which can be empty).(4) (*note
Using Symbols-Footnote-4::) Every time glyph G needs to be
printed, STRING is processed in a temporary environment and the
result is wrapped up into a single object. Compatibility mode is
turned off and the escape character is set to `\' while STRING is
being processed. Any emboldening, constant spacing or track
kerning is applied to this object rather than to individual
characters in STRING.
A glyph defined by these requests can be used just like a normal
glyph provided by the output device. In particular, other
characters can be translated to it with the `tr' or `trin'
requests; it can be made the leader character by the `lc' request;
repeated patterns can be drawn with the glyph using the `\l' and
`\L' escape sequences; words containing the glyph can be
hyphenated correctly if the `hcode' request is used to give the
glyph's symbol a hyphenation code.
There is a special anti-recursion feature: Use of `g' within the
glyph's definition is handled like normal characters and symbols
not defined with `char'.
Note that the `tr' and `trin' requests take precedence if `char'
accesses the same symbol.
.tr XY
X
=> Y
.char X Z
X
=> Y
.tr XX
X
=> Z
The `fchar' request defines a fallback glyph: `gtroff' only checks
for glyphs defined with `fchar' if it cannot find the glyph in the
current font. `gtroff' carries out this test before checking
special fonts.
`fschar' defines a fallback glyph for font F: `gtroff' checks for
glyphs defined with `fschar' after the list of fonts declared as
font-specific special fonts with the `fspecial' request, but
before the list of fonts declared as global special fonts with the
`special' request.
Finally, the `schar' request defines a global fallback glyph:
`gtroff' checks for glyphs defined with `schar' after the list of
fonts declared as global special fonts with the `special' request,
but before the already mounted special fonts.
*Note Using Symbols::, for a detailed description of the glyph
searching mechanism in `gtroff'.
- Request: .rchar c1 c2 ...
- Request: .rfschar f c1 c2 ...
Remove the definitions of glyphs C1, C2, .... This undoes the
effect of a `char', `fchar', or `schar' request.
It is possible to omit the whitespace between arguments.
The request `rfschar' removes glyph definitions defined with
`fschar' for glyph f.
*Note Special Characters::.
File: groff, Node: Using Symbols-Footnotes, Up: Using Symbols
(1) Note that a one-character symbol is not the same as an input
character, i.e., the character `a' is not the same as `\[a]'. By
default, `groff' defines only a single one-character symbol, `\[-]'; it
is usually accessed as `\-'. On the other hand, `gtroff' has the
special feature that `\[charXXX]' is the same as the input character
with character code XXX. For example, `\[char97]' is identical to the
letter `a' if ASCII encoding is active.
(2) `\C' is actually a misnomer since it accesses an output glyph.
(3) Note that the output glyphs themselves don't have such
properties. For `gtroff', a glyph is a numbered box with a given
width, depth, and height, nothing else. All manipulations with the
`cflags' request work on the input level.
(4) `char' is a misnomer since an output glyph is defined.
File: groff, Node: Special Fonts, Next: Artificial Fonts, Prev: Using Symbols, Up: Fonts and Symbols
Special Fonts
-------------
Special fonts are those that `gtroff' searches when it cannot find
the requested glyph in the current font. The Symbol font is usually a
special font.
`gtroff' provides the following two requests to add more special
fonts. *Note Using Symbols::, for a detailed description of the glyph
searching mechanism in `gtroff'.
Usually, only non-TTY devices have special fonts.
- Request: .special [s1 s2 ...]
- Request: .fspecial f [s1 s2 ...]
Use the `special' request to define special fonts. Initially, this
list is empty.
Use the `fspecial' request to designate special fonts only when
font F is active. Initially, this list is empty.
Previous calls to `special' or `fspecial' are overwritten; without
arguments, the particular list of special fonts is set to empty.
Special fonts are searched in the order they appear as arguments.
All fonts which appear in a call to `special' or `fspecial' are
loaded.
*Note Using Symbols::, for the exact search order of glyphs.
File: groff, Node: Artificial Fonts, Next: Ligatures and Kerning, Prev: Special Fonts, Up: Fonts and Symbols
Artificial Fonts
----------------
There are a number of requests and escapes for artificially creating
fonts. These are largely vestiges of the days when output devices did
not have a wide variety of fonts, and when `nroff' and `troff' were
separate programs. Most of them are no longer necessary in GNU
`troff'. Nevertheless, they are supported.
- Escape: \H'height'
- Escape: \H'+height'
- Escape: \H'-height'
- Register: \n[.height]
Change (increment, decrement) the height of the current font, but
not the width. If HEIGHT is zero, restore the original height.
Default scaling indicator is `z'.
The read-only number register `.height' contains the font height as
set by `\H'.
Currently, only the `-Tps' device supports this feature.
Note that `\H' doesn't produce an input token in `gtroff'. As a
consequence, it can be used in requests like `mc' (which expects a
single character as an argument) to change the font on the fly:
.mc \H'+5z'x\H'0'
In compatibility mode, `gtroff' behaves differently: If an
increment or decrement is used, it is always taken relative to the
current point size and not relative to the previously selected font
height. Thus,
.cp 1
\H'+5'test \H'+5'test
prints the word `test' twice with the same font height (five
points larger than the current font size).
- Escape: \S'slant'
- Register: \n[.slant]
Slant the current font by SLANT degrees. Positive values slant to
the right. Only integer values are possible.
The read-only number register `.slant' contains the font slant as
set by `\S'.
Currently, only the `-Tps' device supports this feature.
Note that `\S' doesn't produce an input token in `gtroff'. As a
consequence, it can be used in requests like `mc' (which expects a
single character as an argument) to change the font on the fly:
.mc \S'20'x\S'0'
This request is incorrectly documented in the original UNIX troff
manual; the slant is always set to an absolute value.
- Request: .ul [lines]
The `ul' request normally underlines subsequent lines if a TTY
output device is used. Otherwise, the lines are printed in italics
(only the term `underlined' is used in the following). The single
argument is the number of input lines to be underlined; with no
argument, the next line is underlined. If LINES is zero or
negative, stop the effects of `ul' (if it was active). Requests
and empty lines do not count for computing the number of underlined
input lines, even if they produce some output like `tl'. Lines
inserted by macros (e.g. invoked by a trap) do count.
At the beginning of `ul', the current font is stored and the
underline font is activated. Within the span of a `ul' request,
it is possible to change fonts, but after the last line affected by
`ul' the saved font is restored.
This number of lines still to be underlined is associated with the
current environment (*note Environments::). The underline font
can be changed with the `uf' request.
The `ul' request does not underline spaces.
- Request: .cu [lines]
The `cu' request is similar to `ul' but underlines spaces as well
(if a TTY output device is used).
- Request: .uf font
Set the underline font (globally) used by `ul' and `cu'. By
default, this is the font at position 2. FONT can be either a
non-negative font position or the name of a font.
- Request: .bd font [offset]
- Request: .bd font1 font2 [offset]
- Register: \n[.b]
Artificially create a bold font by printing each glyph twice,
slightly offset.
Two syntax forms are available.
* Imitate a bold font unconditionally. The first argument
specifies the font to embolden, and the second is the number
of basic units, minus one, by which the two glyphs are
offset. If the second argument is missing, emboldening is
turned off.
FONT can be either a non-negative font position or the name
of a font.
OFFSET is available in the `.b' read-only register if a
special font is active; in the `bd' request, its default unit
is `u'.
* Imitate a bold form conditionally. Embolden FONT1 by OFFSET
only if font FONT2 is the current font. This command can be
issued repeatedly to set up different emboldening values for
different current fonts. If the second argument is missing,
emboldening is turned off for this particular current font.
This affects special fonts only (either set up with the
`special' command in font files or with the `fspecial'
request).
- Request: .cs font [width [em-size]]
Switch to and from "constant glyph space mode". If activated, the
width of every glyph is WIDTH/36 ems. The em size is given
absolutely by EM-SIZE; if this argument is missing, the em value
is taken from the current font size (as set with the `ps' request)
when the font is effectively in use. Without second and third
argument, constant glyph space mode is deactivated.
Default scaling indicator for EM-SIZE is `z'; WIDTH is an integer.
File: groff, Node: Ligatures and Kerning, Prev: Artificial Fonts, Up: Fonts and Symbols
Ligatures and Kerning
---------------------
Ligatures are groups of characters that are run together, i.e,
producing a single glyph. For example, the letters `f' and `i' can
form a ligature `fi' as in the word `file'. This produces a cleaner
look (albeit subtle) to the printed output. Usually, ligatures are not
available in fonts for TTY output devices.
Most POSTSCRIPT fonts support the fi and fl ligatures. The C/A/T
typesetter that was the target of AT&T `troff' also supported `ff',
`ffi', and `ffl' ligatures. Advanced typesetters or `expert' fonts may
include ligatures for `ft' and `ct', although GNU `troff' does not
support these (yet).
Only the current font is checked for ligatures and kerns; neither
special fonts nor entities defined with the `char' request (and its
siblings) are taken into account.
- Request: .lg [flag]
- Register: \n[.lg]
Switch the ligature mechanism on or off; if the parameter is
non-zero or missing, ligatures are enabled, otherwise disabled.
Default is on. The current ligature mode can be found in the
read-only number register `.lg' (set to 1 or 2 if ligatures are
enabled, 0 otherwise).
Setting the ligature mode to 2 enables the two-character ligatures
(fi, fl, and ff) and disables the three-character ligatures (ffi
and ffl).
"Pairwise kerning" is another subtle typesetting mechanism that
modifies the distance between a glyph pair to improve readability. In
most cases (but not always) the distance is decreased. Typewriter-like
fonts and fonts for terminals where all glyphs have the same width
don't use kerning.
- Request: .kern [flag]
- Register: \n[.kern]
Switch kerning on or off. If the parameter is non-zero or missing,
enable pairwise kerning, otherwise disable it. The read-only
number register `.kern' is set to 1 if pairwise kerning is enabled,
0 otherwise.
If the font description file contains pairwise kerning information,
glyphs from that font are kerned. Kerning between two glyphs can
be inhibited by placing `\&' between them: `V\&A'.
*Note Font File Format::.
"Track kerning" expands or reduces the space between glyphs. This
can be handy, for example, if you need to squeeze a long word onto a
single line or spread some text to fill a narrow column. It must be
used with great care since it is usually considered bad typography if
the reader notices the effect.
- Request: .tkf f s1 n1 s2 n2
Enable track kerning for font F. If the current font is F the
width of every glyph is increased by an amount between N1 and N2
(N1, N2 can be negative); if the current point size is less than
or equal to S1 the width is increased by N1; if it is greater than
or equal to S2 the width is increased by N2; if the point size is
greater than or equal to S1 and less than or equal to S2 the
increase in width is a linear function of the point size.
The default scaling indicator is `z' for S1 and S2, `p' for N1 and
N2.
Note that the track kerning amount is added even to the rightmost
glyph in a line; for large values it is thus recommended to
increase the line length by the same amount to compensate it.
Sometimes, when typesetting letters of different fonts, more or less
space at such boundaries are needed. There are two escapes to help
with this.
- Escape: \/
Increase the width of the preceding glyph so that the spacing
between that glyph and the following glyph is correct if the
following glyph is a roman glyph. For example, if an italic `f'
is immediately followed by a roman right parenthesis, then in many
fonts the top right portion of the `f' overlaps the top left of
the right parenthesis. Use this escape sequence whenever an
italic glyph is immediately followed by a roman glyph without any
intervening space. This small amount of space is also called
"italic correction".
- Escape: \,
Modify the spacing of the following glyph so that the spacing
between that glyph and the preceding glyph is correct if the
preceding glyph is a roman glyph. Use this escape sequence
whenever a roman glyph is immediately followed by an italic glyph
without any intervening space. In analogy to above, this space
could be called "left italic correction", but this term isn't used
widely.
- Escape: \&
Insert a zero-width character, which is invisible. Its intended
use is to stop interaction of a character with its surrounding.
* It prevents the insertion of extra space after an
end-of-sentence character.
Test.
Test.
=> Test. Test.
Test.\&
Test.
=> Test. Test.
* It prevents interpretation of a control character at the
beginning of an input line.
.Test
=> warning: `Test' not defined
\&.Test
=> .Test
* It prevents kerning between two glyphs.
* It is needed to map an arbitrary character to nothing in the
`tr' request (*note Character Translations::).
- Escape: \)
This escape is similar to `\&' except that it behaves like a
character declared with the `cflags' request to be transparent for
the purposes of an end-of-sentence character.
Its main usage is in macro definitions to protect against arguments
starting with a control character.
.de xxx
\)\\$1
..
.de yyy
\&\\$1
..
This is a test.\c
.xxx '
This is a test.
=>This is a test.' This is a test.
This is a test.\c
.yyy '
This is a test.
=>This is a test.' This is a test.
File: groff, Node: Sizes, Next: Strings, Prev: Fonts and Symbols, Up: gtroff Reference
Sizes
=====
`gtroff' uses two dimensions with each line of text, type size and
vertical spacing. The "type size" is approximately the height of the
tallest glyph.(1) (*note Sizes-Footnote-1::) "Vertical spacing" is the
amount of space `gtroff' allows for a line of text; normally, this is
about 20% larger than the current type size. Ratios smaller than this
can result in hard-to-read text; larger than this, it spreads the text
out more vertically (useful for term papers). By default, `gtroff'
uses 10 point type on 12 point spacing.
The difference between type size and vertical spacing is known, by
typesetters, as "leading" (this is pronounced `ledding').
* Menu:
* Changing Type Sizes::
* Fractional Type Sizes::
File: groff, Node: Sizes-Footnotes, Up: Sizes
(1) This is usually the parenthesis. Note that in most cases the
real dimensions of the glyphs in a font are _not_ related to its type
size! For example, the standard POSTSCRIPT font families `Times
Roman', `Helvetica', and `Courier' can't be used together at 10pt; to
get acceptable output, the size of `Helvetica' has to be reduced by one
point, and the size of `Courier' must be increased by one point.
|