summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/luatex/base/luatex-fonts.tex
blob: 400550a96dd5ee48607a56abedcbb19b6b7ffa64 (plain)
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
% language=uk

\environment luatex-style

\startcomponent luatex-fonts

\startchapter[reference=fonts,title={Font structure}]

\startsection[title={The font tables}]

\topicindex {fonts}
\topicindex {fonts+tables}

All \TEX\ fonts are represented to \LUA\ code as tables, and internally as
\CCODE~structures. All keys in the table below are saved in the internal font
structure if they are present in the table returned by the \cbk {define_font}
callback, or if they result from the normal \TFM|/|\VF\ reading routines if there
is no \cbk {define_font} callback defined.

The column \quote {\VF} means that this key will be created by the \type
{font.read_vf()} routine, \quote {\TFM} means that the key will be created by the
\type {font.read_tfm()} routine, and \quote {used} means whether or not the
\LUATEX\ engine itself will do something with the key. The top|-|level keys in
the table are as follows:

\starttabulate[|l|c|c|c|l|pl|]
\DB key                     \BC vf  \BC tfm \BC used \BC value type \BC description \NC \NR
\TB
\NC \type{name}             \NC yes \NC yes \NC yes  \NC string     \NC metric (file) name \NC \NR
\NC \type{area}             \NC no  \NC yes \NC yes  \NC string     \NC (directory) location, typically empty \NC \NR
\NC \type{used}             \NC no  \NC yes \NC yes  \NC boolean    \NC indicates usage (initial: false) \NC \NR
\NC \type{characters}       \NC yes \NC yes \NC yes  \NC table      \NC the defined glyphs of this font \NC \NR
\NC \type{checksum}         \NC yes \NC yes \NC no   \NC number     \NC default: 0 \NC \NR
\NC \type{designsize}       \NC no  \NC yes \NC yes  \NC number     \NC expected size (default: 655360 == 10pt) \NC \NR
\NC \type{direction}        \NC no  \NC yes \NC yes  \NC number     \NC default: 0 \NC \NR
\NC \type{encodingbytes}    \NC no  \NC no  \NC yes  \NC number     \NC default: depends on \type {format} \NC \NR
\NC \type{encodingname}     \NC no  \NC no  \NC yes  \NC string     \NC encoding name \NC \NR
\NC \type{fonts}            \NC yes \NC no  \NC yes  \NC table      \NC locally used fonts \NC \NR
\NC \type{psname}           \NC no  \NC no  \NC yes  \NC string     \NC This is the \POSTSCRIPT\ fontname in the incoming font
                                                                        source, and it's used as fontname identifier in the \PDF\
                                                                        output. This has to be a valid string, e.g.\ no spaces
                                                                        and such, as the backend will not do a cleanup. This gives
                                                                        complete control to the loader. \NC \NR
\NC \type{fullname}         \NC no  \NC no  \NC yes  \NC string     \NC output font name, used as a fallback in the \PDF\ output
                                                                        if the \type {psname} is not set \NC \NR
\NC \type{subfont}          \NC no  \NC no  \NC yes  \NC number     \NC default: 0, index in (\type {ttc}) font with multiple fonts \NC \NR
\NC \type{header}           \NC yes \NC no  \NC no   \NC string     \NC header comments, if any \NC \NR
\NC \type{hyphenchar}       \NC no  \NC no  \NC yes  \NC number     \NC default: \TEX's \prm {hyphenchar} \NC \NR
\NC \type{parameters}       \NC no  \NC yes \NC yes  \NC hash       \NC default: 7 parameters, all zero \NC \NR
\NC \type{size}             \NC no  \NC yes \NC yes  \NC number     \NC the required scaling (by default the same as designsize) \NC \NR
\NC \type{skewchar}         \NC no  \NC no  \NC yes  \NC number     \NC default: \TEX's \prm {skewchar} \NC \NR
\NC \type{type}             \NC yes \NC no  \NC yes  \NC string     \NC basic type of this font \NC \NR
\NC \type{format}           \NC no  \NC no  \NC yes  \NC string     \NC disk format type \NC \NR
\NC \type{embedding}        \NC no  \NC no  \NC yes  \NC string     \NC \PDF\ inclusion  \NC \NR
\NC \type{filename}         \NC no  \NC no  \NC yes  \NC string     \NC the name of the font on disk \NC \NR
\NC \type{tounicode}        \NC no  \NC yes \NC yes  \NC number     \NC When this is set to~1 \LUATEX\ assumes per|-|glyph
                                                                        tounicode entries are present in the font. \NC \NR
\NC \type{stretch}          \NC no  \NC no  \NC yes  \NC number     \NC the \quote {stretch} value from \lpr {expandglyphsinfont} \NC \NR
\NC \type{shrink}           \NC no  \NC no  \NC yes  \NC number     \NC the \quote {shrink} value from \lpr {expandglyphsinfont} \NC \NR
\NC \type{step}             \NC no  \NC no  \NC yes  \NC number     \NC the \quote {step} value from \lpr {expandglyphsinfont} \NC \NR
\NC \type{expansion_factor} \NC no  \NC no  \NC no   \NC number     \NC the actual expansion factor of an expanded font \NC \NR
\NC \type{attributes}       \NC no  \NC no  \NC yes  \NC string     \NC the \orm {pdffontattr} \NC \NR
\NC \type{cache}            \NC no  \NC no  \NC yes  \NC string     \NC This key controls caching of the \LUA\ table on the
                                                                        \TEX\ end where \type {yes} means: use a reference to
                                                                        the table that is passed to \LUATEX\ (this is the
                                                                        default), and \type {no} means: don't store the
                                                                        table reference, don't cache any \LUA\ data for this
                                                                        font while \type {renew} means: don't store the table
                                                                        reference, but save a reference to the table that is
                                                                        created at the first access to one of its fields in the
                                                                        font. \NC \NR
\NC \type{nomath}           \NC no  \NC no  \NC yes  \NC boolean    \NC This key allows a minor speedup for text fonts. If it
                                                                        is present and true, then \LUATEX\ will not check the
                                                                        character entries for math|-|specific keys. \NC \NR
\NC \type{oldmath}          \NC no  \NC no  \NC yes  \NC boolean    \NC This key flags a font as representing an old school \TEX\
                                                                        math font and disables the \OPENTYPE\ code path. \NC \NR
\NC \type{slant}            \NC no  \NC no  \NC yes  \NC number     \NC This parameter will tilt the font and
                                                                        does the same as \type {SlantFont} in the map file for
                                                                        \TYPEONE\ fonts. \NC \NR
\NC \type{extend}           \NC no  \NC no  \NC yes  \NC number     \NC This parameter will scale the font horizontally and
                                                                        does the same as \type {ExtendFont} in the map file for
                                                                        \TYPEONE\ fonts. \NC \NR
\NC \type{squeeze}          \NC no  \NC no  \NC yes  \NC number     \NC This parameter will scale the font vertically and has
                                                                        no equivalent in the map file. \NC \NR
\NC \type{width}            \NC no  \NC no  \NC yes  \NC number     \NC The backend will inject \PDF\ operators that set the
                                                                        penwidth. The value is (as usual in \TEX) divided by 1000.
                                                                        It works with the \type {mode} file. \NC \NR
\NC \type{mode}             \NC no  \NC no  \NC yes  \NC number     \NC The backend will inject \PDF\ operators that relate to the
                                                                        drawing mode with 0~being a fill, 1~being an outline,
                                                                        2~both draw and fill and 3~no painting at all. \NC \NR
\LL
\stoptabulate

The saved reference in the \type {cache} option is thread|-|local, so be careful
when you are using coroutines: an error will be thrown if the table has been
cached in one thread, but you reference it from another thread.

The key \type {name} is always required. The keys \type {stretch}, \type
{shrink}, \type {step} only have meaning when used together: they can be used to
replace a post|-|loading \lpr {expandglyphsinfont} command. The \type
{auto_expand} option is not supported in \LUATEX. In fact, the primitives that
create expanded or protruding copies are probably only useful when used with
traditional fonts because all these extra \OPENTYPE\ properties are kept out of
the picture. The \type {expansion_factor} is value that can be present inside a
font in \type {font.fonts}. It is the actual expansion factor (a value between
\type {-shrink} and \type {stretch}, with step \type {step}) of a font that was
automatically generated by the font expansion algorithm.

The \type {subfont} parameter can be used to specify the subfont in a \type {ttc}
font. When given, it is used instead of the \type {psname} and \type {fullname}
combination. The first subfont has number~1. A zero value signals using the names
as lookup.

Because we store the actual state of expansion with each glyph and don't have
special font instances, we can change some font related parameters before lines
are constructed, like:

\starttyping
font.setexpansion(font.current(),100,100,20)
\stoptyping

This is mostly meant for experiments (or an optimizing routing written in \LUA)
so there is no primitive.

The key \type {attributes} can be used to set font attributes in the \PDF\ file.
The key \type {used} is set by the engine when a font is actively in use, this
makes sure that the font's definition is written to the output file (\DVI\ or
\PDF). The \TFM\ reader sets it to false. The \type {direction} is a number
signalling the \quote {normal} direction for this font. There are sixteen
possibilities:

\starttabulate[|Tc|c|Tc|c|Tc|c|Tc|c|]
\DB \# \BC dir \BC \# \BC dir \BC \# \BC dir \BC \# \BC dir \NC \NR
\TB
\NC  0 \NC LT  \NC  4 \NC RT  \NC  8 \NC TT  \NC 12 \NC BT  \NC \NR
\NC  1 \NC LL  \NC  5 \NC RL  \NC  9 \NC TL  \NC 13 \NC BL  \NC \NR
\NC  2 \NC LB  \NC  6 \NC RB  \NC 10 \NC TB  \NC 14 \NC BB  \NC \NR
\NC  3 \NC LR  \NC  7 \NC RR  \NC 11 \NC TR  \NC 15 \NC BR  \NC \NR
\LL
\stoptabulate

These are \OMEGA|-|style direction abbreviations: the first character indicates
the \quote {first} edge of the character glyphs (the edge that is seen first in
the writing direction), the second the \quote {top} side. Keep in mind that
\LUATEX\ has a bit different directional model so these values are not used for
anything.

The \type {parameters} is a hash with mixed key types. There are seven possible
string keys, as well as a number of integer indices (these start from 8 up). The
seven strings are actually used instead of the bottom seven indices, because that
gives a nicer user interface.

The names and their internal remapping are:

\starttabulate[|l|c|]
\DB name                  \BC remapping \NC \NR
\TB
\NC \type {slant}         \NC 1 \NC \NR
\NC \type {space}         \NC 2 \NC \NR
\NC \type {space_stretch} \NC 3 \NC \NR
\NC \type {space_shrink}  \NC 4 \NC \NR
\NC \type {x_height}      \NC 5 \NC \NR
\NC \type {quad}          \NC 6 \NC \NR
\NC \type {extra_space}   \NC 7 \NC \NR
\LL
\stoptabulate

The keys \type {type}, \type {format}, \type {embedding}, \type {fullname} and
\type {filename} are used to embed \OPENTYPE\ fonts in the result \PDF.

The \type {characters} table is a list of character hashes indexed by an integer
number. The number is the \quote {internal code} \TEX\ knows this character by.

Two very special string indexes can be used also: \type {left_boundary} is a
virtual character whose ligatures and kerns are used to handle word boundary
processing. \type {right_boundary} is similar but not actually used for anything
(yet).

Each character hash itself is a hash. For example, here is the character \quote
{f} (decimal 102) in the font \type {cmr10 at 10pt}. The numbers that represent
dimensions are in scaled points.

\starttyping
[102] = {
    ["width"]  = 200250,
    ["height"] = 455111,
    ["depth"]  = 0,
    ["italic"] = 50973,
    ["kerns"]  = {
        [63] = 50973,
        [93] = 50973,
        [39] = 50973,
        [33] = 50973,
        [41] = 50973
    },
    ["ligatures"] = {
        [102] = { ["char"] = 11, ["type"] = 0 },
        [108] = { ["char"] = 13, ["type"] = 0 },
        [105] = { ["char"] = 12, ["type"] = 0 }
    }
}
\stoptyping

The following top|-|level keys can be present inside a character hash:

\starttabulate[|l|c|c|c|l|p|]
\DB key                     \BC vf  \BC tfm \BC used  \BC type    \BC description \NC\NR
\TB
\NC \type{width}            \NC yes \NC yes \NC yes   \NC number  \NC character's width, in sp (default 0) \NC\NR
\NC \type{height}           \NC no  \NC yes \NC yes   \NC number  \NC character's height, in sp (default 0) \NC\NR
\NC \type{depth}            \NC no  \NC yes \NC yes   \NC number  \NC character's depth, in sp (default 0) \NC\NR
\NC \type{italic}           \NC no  \NC yes \NC yes   \NC number  \NC character's italic correction, in sp (default zero) \NC\NR
\NC \type{top_accent}       \NC no  \NC no  \NC maybe \NC number  \NC character's top accent alignment place, in sp (default zero) \NC\NR
\NC \type{bot_accent}       \NC no  \NC no  \NC maybe \NC number  \NC character's bottom accent alignment place, in sp (default zero) \NC\NR
\NC \type{left_protruding}  \NC no  \NC no  \NC maybe \NC number  \NC character's \lpr {lpcode} \NC\NR
\NC \type{right_protruding} \NC no  \NC no  \NC maybe \NC number  \NC character's \lpr {rpcode} \NC\NR
\NC \type{expansion_factor} \NC no  \NC no  \NC maybe \NC number  \NC character's \lpr {efcode} \NC\NR
\NC \type{tounicode}        \NC no  \NC no  \NC maybe \NC string  \NC character's \UNICODE\ equivalent(s), in \UTF|-|16BE hexadecimal format \NC\NR
\NC \type{next}             \NC no  \NC yes \NC yes   \NC number  \NC the \quote {next larger} character index \NC\NR
\NC \type{extensible}       \NC no  \NC yes \NC yes   \NC table   \NC the constituent parts of an extensible recipe \NC\NR
\NC \type{vert_variants}    \NC no  \NC no  \NC yes   \NC table   \NC constituent parts of a vertical variant set \NC \NR
\NC \type{horiz_variants}   \NC no  \NC no  \NC yes   \NC table   \NC constituent parts of a horizontal variant set \NC \NR
\NC \type{kerns}            \NC no  \NC yes \NC yes   \NC table   \NC kerning information \NC\NR
\NC \type{ligatures}        \NC no  \NC yes \NC yes   \NC table   \NC ligaturing information \NC\NR
\NC \type{commands}         \NC yes \NC no  \NC yes   \NC array   \NC virtual font commands \NC\NR
\NC \type{name}             \NC no  \NC no  \NC no    \NC string  \NC the character (\POSTSCRIPT) name \NC\NR
\NC \type{index}            \NC no  \NC no  \NC yes   \NC number  \NC the (\OPENTYPE\ or \TRUETYPE) font glyph index \NC\NR
\NC \type{used}             \NC no  \NC yes \NC yes   \NC boolean \NC typeset already (default: false) \NC\NR
\NC \type{mathkern}         \NC no  \NC no  \NC yes   \NC table   \NC math cut-in specifications \NC\NR
\LL
\stoptabulate

The values of \type {top_accent}, \type {bot_accent} and \type {mathkern} are
used only for math accent and superscript placement, see \at {page} [math] in
this manual for details. The values of \type {left_protruding} and \type
{right_protruding} are used only when \lpr {protrudechars} is non-zero. Whether
or not \type {expansion_factor} is used depends on the font's global expansion
settings, as well as on the value of \lpr {adjustspacing}.

The usage of \type {tounicode} is this: if this font specifies a \type
{tounicode=1} at the top level, then \LUATEX\ will construct a \type {/ToUnicode}
entry for the \PDF\ font (or font subset) based on the character|-|level \type
{tounicode} strings, where they are available. If a character does not have a
sensible \UNICODE\ equivalent, do not provide a string either (no empty strings).

If the font level \type {tounicode} is not set, then \LUATEX\ will build up \type
{/ToUnicode} based on the \TEX\ code points you used, and any character-level
\type {tounicodes} will be ignored. The string format is exactly the format that
is expected by Adobe \CMAP\ files (\UTF-16BE in hexadecimal encoding), minus the
enclosing angle brackets. For instance the \type {tounicode} for a \type {fi}
ligature would be \type {00660069}. When you pass a number the conversion will be
done for you.

A math character can have a \type {next} field that points to a next larger
shape. However, the presence of \type {extensible} will overrule \type {next}, if
that is also present. The \type {extensible} field in turn can be overruled by
\type {vert_variants}, the \OPENTYPE\ version. The \type {extensible} table is
very simple:

\starttabulate[|l|l|p|]
\DB key        \BC type   \BC description                \NC\NR
\TB
\NC \type{top} \NC number \NC top character index        \NC\NR
\NC \type{mid} \NC number \NC middle character index     \NC\NR
\NC \type{bot} \NC number \NC bottom character index     \NC\NR
\NC \type{rep} \NC number \NC repeatable character index \NC\NR
\LL
\stoptabulate

The \type {horiz_variants} and \type {vert_variants} are arrays of components.
Each of those components is itself a hash of up to five keys:

\starttabulate[|l|l|p|]
\DB key             \BC type   \BC explanation \NC \NR
\TB
\NC \type{glyph}    \NC number \NC The character index. Note that this is an encoding number, not a name. \NC \NR
\NC \type{extender} \NC number \NC One (1) if this part is repeatable, zero (0) otherwise. \NC \NR
\NC \type{start}    \NC number \NC The maximum overlap at the starting side (in scaled points). \NC \NR
\NC \type{end}      \NC number \NC The maximum overlap at the ending side (in scaled points). \NC \NR
\NC \type{advance}  \NC number \NC The total advance width of this item. It can be zero or missing,
                                   then the natural size of the glyph for character \type {component}
                                   is used. \NC \NR
\LL
\stoptabulate

The \type {kerns} table is a hash indexed by character index (and \quote
{character index} is defined as either a non|-|negative integer or the string
value \type {right_boundary}), with the values of the kerning to be applied, in
scaled points.

The \type {ligatures} table is a hash indexed by character index (and \quote
{character index} is defined as either a non|-|negative integer or the string
value \type {right_boundary}), with the values being yet another small hash, with
two fields:

\starttabulate[|l|l|p|]
\DB key         \BC type   \BC description \NC \NR
\TB
\NC \type{type} \NC number \NC the type of this ligature command, default 0 \NC \NR
\NC \type{char} \NC number \NC the character index of the resultant ligature \NC \NR
\LL
\stoptabulate

The \type {char} field in a ligature is required. The \type {type} field inside a
ligature is the numerical or string value of one of the eight possible ligature
types supported by \TEX. When \TEX\ inserts a new ligature, it puts the new glyph
in the middle of the left and right glyphs. The original left and right glyphs
can optionally be retained, and when at least one of them is kept, it is also
possible to move the new \quote {insertion point} forward one or two places. The
glyph that ends up to the right of the insertion point will become the next
\quote {left}.

\starttabulate[|l|c|l|l|]
\DB textual (Knuth)       \BC number \BC string        \BC result      \NC\NR
\TB
\NC \type{l + r =: n}     \NC 0      \NC \type{=:}     \NC \type{|n}   \NC\NR
\NC \type{l + r =:| n}    \NC 1      \NC \type{=:|}    \NC \type{|nr}  \NC\NR
\NC \type{l + r |=: n}    \NC 2      \NC \type{|=:}    \NC \type{|ln}  \NC\NR
\NC \type{l + r |=:| n}   \NC 3      \NC \type{|=:|}   \NC \type{|lnr} \NC\NR
\NC \type{l + r  =:|> n}  \NC 5      \NC \type{=:|>}   \NC \type{n|r}  \NC\NR
\NC \type{l + r |=:> n}   \NC 6      \NC \type{|=:>}   \NC \type{l|n}  \NC\NR
\NC \type{l + r |=:|> n}  \NC 7      \NC \type{|=:|>}  \NC \type{l|nr} \NC\NR
\NC \type{l + r |=:|>> n} \NC 11     \NC \type{|=:|>>} \NC \type{ln|r} \NC\NR
\LL
\stoptabulate

The default value is~0, and can be left out. That signifies a \quote {normal}
ligature where the ligature replaces both original glyphs. In this table the~\type {|}
indicates the final insertion point.

The \type {commands} array is explained below.

\stopsection

\startsection[title={Real fonts}]

\topicindex {fonts+real}
\topicindex {fonts+virtual}

Whether or not a \TEX\ font is a \quote {real} font that should be written to the
\PDF\ document is decided by the \type {type} value in the top|-|level font
structure. If the value is \type {real}, then this is a proper font, and the
inclusion mechanism will attempt to add the needed font object definitions to the
\PDF. Values for \type {type} are:

\starttabulate[|l|p|]
\DB value          \BC description            \NC\NR
\TB
\NC \type{real}    \NC this is a base font    \NC\NR
\NC \type{virtual} \NC this is a virtual font \NC\NR
\LL
\stoptabulate

The actions to be taken depend on a number of different variables:

\startitemize[packed]
\startitem
    Whether the used font fits in an 8-bit encoding scheme or not. This is true for
    traditional \TEX\ fonts that communicate via \TFM\ files.
\stopitem
\startitem
    The type of the disk font file, for instance a bitmap file or an outline
    \TYPEONE, \TRUETYPE\ or \OPENTYPE\ font.
\stopitem
\startitem
    The level of embedding requested, although in most cases a subset of
    characters is embedded. The times when nothing got embedded are (in our
    opinion at least) basically gone.
\stopitem
\stopitemize

A font that uses anything other than an 8-bit encoding vector has to be written
to the \PDF\ in a different way. When the font table has \type {encodingbytes}
set to~2, then it is a wide font, in all other cases it isn't. The value~2 is the
default for \OPENTYPE\ and \TRUETYPE\ fonts loaded via \LUA. For \TYPEONE\ fonts,
you have to set \type {encodingbytes} to~2 explicitly. For \PK\ bitmap fonts,
wide font encoding is not supported at all.

If no special care is needed, \LUATEX\ falls back to the mapfile|-|based solution
used by \PDFTEX\ and \DVIPS, so that legacy fonts are supported transparently. If
a \quote {wide} font is used, the new subsystem kicks in, and some extra fields
have to be present in the font structure. In this case, \LUATEX\ does not use a
map file at all. These extra fields are: \type {format}, \type {embedding}, \type
{fullname}, \type {cidinfo} (as explained above), \type {filename}, and the \type
{index} key in the separate characters.

The \type {format} variable can have the following values. \type {type3} fonts
are provided for backward compatibility only, and do not support the new wide
encoding options.

\starttabulate[|l|p|]
\DB value           \BC description                                               \NC \NR
\TB
\NC \type{type1}    \NC this is a \POSTSCRIPT\ \TYPEONE\ font                     \NC \NR
\NC \type{type3}    \NC this is a bitmapped (\PK) font                            \NC \NR
\NC \type{truetype} \NC this is a \TRUETYPE\ or \TRUETYPE|-|based \OPENTYPE\ font \NC \NR
\NC \type{opentype} \NC this is a \POSTSCRIPT|-|based \OPENTYPE\ font             \NC \NR
\LL
\stoptabulate

Valid values for the \type {embedding} variable are:

\starttabulate[|l|p|]
\DB value         \BC description                             \NC \NR
\TB
\NC \type{no}     \NC don't embed the font at all             \NC \NR
\NC \type{subset} \NC include and atttempt to subset the font \NC \NR
\NC \type{full}   \NC include this font in its entirety       \NC \NR
\LL
\stoptabulate

The other fields are used as follows. The \type {fullname} will be the
\POSTSCRIPT|/|\PDF\ font name. The \type {cidinfo} will be used as the character
set: the CID \type {/Ordering} and \type {/Registry} keys. The \type {filename}
points to the actual font file. If you include the full path in the \type
{filename} or if the file is in the local directory, \LUATEX\ will run a little
bit more efficient because it will not have to re|-|run the \type {find_*_file}
callback in that case.

Be careful: when mixing old and new fonts in one document, it is possible to
create \POSTSCRIPT\ name clashes that can result in printing errors. When this
happens, you have to change the \type {fullname} of the font to a more unique
one.

Typeset strings are written out in a wide format using 2~bytes per glyph, using
the \type {index} key in the character information as value. The overall effect
is like having an encoding based on numbers instead of traditional (\POSTSCRIPT)
name|-|based reencoding. One way to get the correct \type {index} numbers for
\TYPEONE\ fonts is by loading the font via \type {fontloader.open} and use the
table indices as \type {index} fields.

In order to make sure that cut and paste of the final document works okay you can
best make sure that there is a \type {tounicode} vector enforced. Not all \PDF\
viewers handle this right so take \ACROBAT\ as reference.

\stopsection

\startsection[reference=virtualfonts,title={Virtual fonts}]

\subsection{The structure}

\topicindex {fonts+virtual}

You have to take the following steps if you want \LUATEX\ to treat the returned
table from \cbk {define_font} as a virtual font:

\startitemize[packed]
\startitem
    Set the top|-|level key \type {type} to \type {virtual}. In most cases it's
    optional because we look at the \type {commands} entry anyway.
\stopitem
\startitem
    Make sure there is at least one valid entry in \type {fonts} (see below),
    although recent versions of \LUATEX\ add a default entry when this table is
    missing.
\stopitem
\startitem
    Add a \type {commands} array to those characters that matter. A virtual
    character can itself point to virtual characters but be careful with nesting
    as you can create loops and overflow the stack (which often indicates an
    error anyway).
\stopitem
\stopitemize

The presence of the toplevel \type {type} key with the specific value \type
{virtual} will trigger handling of the rest of the special virtual font fields in
the table, but the mere existence of 'type' is enough to prevent \LUATEX\ from
looking for a virtual font on its own. This also works \quote {in reverse}: if
you are absolutely certain that a font is not a virtual font, assigning the value
\type {real} to \type {type} will inhibit \LUATEX\ from looking for a virtual
font file, thereby saving you a disk search. This only matters when we load a
\TFM\ file.

The \type {fonts} is an (indexed) \LUA\ table. The values are one- or two|-|key
hashes themselves, each entry indicating one of the base fonts in a virtual font.
In case your font is referring to itself, you can use the \type {font.nextid()}
function which returns the index of the next to be defined font which is probably
the currently defined one. So, a table looks like this:

\starttyping
fonts = {
  { name = "ptmr8a", size = 655360 },
  { name = "psyr", size = 600000 },
  { id = 38 }
}
\stoptyping

The first referenced font (at index~1) in this virtual font is \type {ptrmr8a}
loaded at 10pt, and the second is \type {psyr} loaded at a little over 9pt. The
third one is a previously defined font that is known to \LUATEX\ as font id~38.
The array index numbers are used by the character command definitions that are
part of each character.

The \type {commands} array is a hash where each item is another small array,
with the first entry representing a command and the extra items being the
parameters to that command. The allowed commands and their arguments are:

\starttabulate[|l|l|l|p|]
\DB command        \BC arguments \BC type      \BC description \NC \NR
\TB
\NC \type{font}    \NC 1         \NC number    \NC select a new font from the local \type {fonts} table \NC \NR
\NC \type{char}    \NC 1         \NC number    \NC typeset this character number from the current font,
                                                   and move right by the character's width \NC \NR
\NC \type{node}    \NC 1         \NC node      \NC output this node (list), and move right
                                                   by the width of this list\NC \NR
\NC \type{slot}    \NC 2         \NC 2 numbers \NC a shortcut for the combination of a font and char command\NC \NR
\NC \type{push}    \NC 0         \NC           \NC save current position\NC \NR
\NC \type{nop}     \NC 0         \NC           \NC do nothing \NC \NR
\NC \type{pop}     \NC 0         \NC           \NC pop position \NC \NR
\NC \type{rule}    \NC 2         \NC 2 numbers \NC output a rule $ht*wd$, and move right. \NC \NR
\NC \type{down}    \NC 1         \NC number    \NC move down on the page \NC \NR
\NC \type{right}   \NC 1         \NC number    \NC move right on the page \NC \NR
\NC \type{special} \NC 1         \NC string    \NC output a \prm {special} command \NC \NR
\NC \type{pdf}     \NC 2         \NC 2 strings \NC output a \PDF\ literal, the first string is one of \type {origin},
                                                   \type {page}, \type {text}, \type {font}, \type {direct} or \type {raw}; if you
                                                   have one string only \type {origin} is assumed \NC \NR
\NC \type{lua}     \NC 1         \NC string,
                                     function  \NC execute a \LUA\ script when the glyph is embedded; in case of a
                                                   function it gets the font id and character code passed \NC \NR
\NC \type{image}   \NC 1         \NC image     \NC output an image (the argument can be either an \type {<image>} variable or an \type {image_spec} table) \NC \NR
\NC \type{comment} \NC any       \NC any       \NC the arguments of this command are ignored \NC \NR
\LL
\stoptabulate

When a font id is set to~0 then it will be replaced by the currently assigned
font id. This prevents the need for hackery with future id's. Normally one could
use \type {font.nextid} but when more complex fonts are built in the meantime
other instances could have been loaded.

The \type {pdf} option also accepts a \type {mode} keyword in which case the
third argument sets the mode. That option will change the mode in an efficient
way (passing an empty string would result in an extra empty lines in the \PDF\
file. This option only makes sense for virtual fonts. The \type {font} mode only
makes sense in virtual fonts. Modes are somewhat fuzzy and partially inherited
from \PDFTEX.

\starttabulate[|l|p|]
\DB mode           \BC description \NC \NR
\TB
\NC \type {origin} \NC enter page mode and set the position \NC \NR
\NC \type {page}   \NC enter page mode \NC \NR
\NC \type {text}   \NC enter text mode \NC \NR
\NC \type {font}   \NC enter font mode (kind of text mode, only in virtual fonts) \NC \NR
\NC \type {always} \NC finish the current string and force a transform if needed \NC \NR
\NC \type {raw}    \NC finish the current string \NC \NR
\LL
\stoptabulate

You always need to check what \PDF\ code is generated because there can be all
kind of interferences with optimization in the backend and fonts are complicated
anyway. Here is a rather elaborate glyph commands example using such keys:

\starttyping
...
commands = {
    { "push" },                     -- remember where we are
    { "right", 5000 },              -- move right about 0.08pt
    { "font", 3 },                  -- select the fonts[3] entry
    { "char", 97 },                 -- place character 97 (ASCII 'a')
 -- { "slot", 2, 97 },              -- an alternative for the previous two
    { "pop" },                      -- go all the way back
    { "down", -200000 },            -- move upwards by about 3pt
    { "special", "pdf: 1 0 0 rg" }  -- switch to red color
 -- { "pdf", "origin", "1 0 0 rg" } -- switch to red color (alternative)
    { "rule", 500000, 20000 }       -- draw a bar
    { "special", "pdf: 0 g" }       -- back to black
 -- { "pdf", "origin", "0 g" }      -- back to black (alternative)
}
...
\stoptyping

The default value for \type {font} is always~1 at the start of the
\type {commands} array. Therefore, if the virtual font is essentially only a
re|-|encoding, then you do usually not have created an explicit \quote {font}
command in the array.

Rules inside of \type {commands} arrays are built up using only two dimensions:
they do not have depth. For correct vertical placement, an extra \type {down}
command may be needed.

Regardless of the amount of movement you create within the \type {commands}, the
output pointer will always move by exactly the width that was given in the \type
{width} key of the character hash. Any movements that take place inside the \type
{commands} array are ignored on the upper level.

The special can have a \type {pdf:}, \type {pdf:origin:},  \type {pdf:page:},
\type {pdf:direct:} or  \type {pdf:raw:} prefix. When you have to concatenate
strings using the \type {pdf} command might be more efficient.

\subsection{Artificial fonts}

Even in a \quote {real} font, there can be virtual characters. When \LUATEX\
encounters a \type {commands} field inside a character when it becomes time to
typeset the character, it will interpret the commands, just like for a true
virtual character. In this case, if you have created no \quote {fonts} array,
then the default (and only) \quote {base} font is taken to be the current font
itself. In practice, this means that you can create virtual duplicates of
existing characters which is useful if you want to create composite characters.

Note: this feature does {\it not\/} work the other way around. There can not be
\quote {real} characters in a virtual font! You cannot use this technique for
font re-encoding either; you need a truly virtual font for that (because
characters that are already present cannot be altered).

\subsection{Example virtual font}

\topicindex {fonts+virtual}

Finally, here is a plain \TEX\ input file with a virtual font demonstration:

\startbuffer
\directlua {
  callback.register('define_font',
    function (name,size)
      if name == 'cmr10-red' then
        local f = font.read_tfm('cmr10',size)
        f.name  = 'cmr10-red'
        f.type  = 'virtual'
        f.fonts = {
          { name = 'cmr10', size = size }
        }
        for i,v in pairs(f.characters) do
          if string.char(i):find('[tacohanshartmut]') then
             v.commands = {
               { "special", "pdf: 1 0 0 rg" },
               { "char", i },
               { "special", "pdf: 0 g" },
              }
          end
        end
        return f
      else
        return font.read_tfm(name,size)
      end
    end
  )
}

\font\myfont  = cmr10-red at 10pt \myfont  This is a line of text \par
\font\myfontx = cmr10     at 10pt \myfontx Here is another line of text \par
\stopbuffer

\typebuffer

\stopsection

\startsection[title={The \type {vf} library}]

The \type {vf} library can be used when \LUA\ code, as defined in the \type
{commands} of the font, is executed. The functions provided are similar as the
commands: \type {char}, \type {down}, \type {fontid}, \type {image}, \type
{node}, \type {nop}, \type {pop}, \type {push}, \type {right}, \nod {rule}, \type
{special} and \type {pdf}. This library has been present for a while but not been
advertised and tested much, if only because it's easy to define an invalid font
(or mess up the \PDF\ stream). Keep in mind that the \LUA\ snippets are executed
each time when a character is output.

\stopsection

\startsection[title={The \type {font} library}]

\topicindex {fonts+library}

The font library provides the interface into the internals of the font system,
and it also contains helper functions to load traditional \TEX\ font metrics
formats. Other font loading functionality is provided by the \type {fontloader}
library that will be discussed in the next section.

\subsection{Loading a \TFM\ file}

\topicindex {fonts+tfm}

The behaviour documented in this subsection is considered stable in the sense that
there will not be backward|-|incompatible changes any more.

\startfunctioncall
<table> fnt =
    font.read_tfm(<string> name, <number> s)
\stopfunctioncall

The number is a bit special:

\startitemize
\startitem
    If it is positive, it specifies an \quote {at size} in scaled points.
\stopitem
\startitem
    If it is negative, its absolute value represents a \quote {scaled}
    setting relative to the designsize of the font.
\stopitem
\stopitemize

\subsection{Loading a \VF\ file}

\topicindex {fonts+vf}

The behavior documented in this subsection is considered stable in the sense that
there will not be backward-incompatible changes any more.

\startfunctioncall
<table> vf_fnt =
    font.read_vf(<string> name, <number> s)
\stopfunctioncall

The meaning of the number \type {s} and the format of the returned table are
similar to the ones in the \type {read_tfm} function.

\subsection{The fonts array}

\topicindex {fonts+virtual}

The whole table of \TEX\ fonts is accessible from \LUA\ using a virtual array.

\starttyping
font.fonts[n] = { ... }
<table> f = font.fonts[n]
\stoptyping

Because this is a virtual array, you cannot call \type {pairs} on it, but see
below for the \type {font.each} iterator.

The two metatable functions implementing the virtual array are:

\startfunctioncall
<table> f = font.getfont(<number> n)
font.setfont(<number> n, <table> f)
\stopfunctioncall

Note that at the moment, each access to the \type {font.fonts} or call to \type
{font.getfont} creates a \LUA\ table for the whole font unless you cached it.
If you want a copy of the internal data you can use \type {font.copyfont}:

\startfunctioncall
<table> f = font.copyfont(<number> n)
\stopfunctioncall

This one will return a table of the parameters as known to \TEX. These can be
different from the ones in the cached table:

\startfunctioncall
<table> p = font.getparameters(<number> n)
\stopfunctioncall

Also note the following: assignments can only be made to fonts that have already
been defined in \TEX, but have not been accessed {\it at all\/} since that
definition. This limits the usability of the write access to \type {font.fonts}
quite a lot, a less stringent ruleset will likely be implemented later.

\subsection{Checking a font's status}

You can test for the status of a font by calling this function:

\startfunctioncall
<boolean> f =
    font.frozen(<number> n)
\stopfunctioncall

The return value is one of \type {true} (unassignable), \type {false} (can be
changed) or \type {nil} (not a valid font at all).

\subsection{Defining a font directly}

\topicindex {fonts+define}

You can define your own font into \type {font.fonts} by calling this function:

\startfunctioncall
<number> i =
    font.define(<table> f)
\stopfunctioncall

The return value is the internal id number of the defined font (the index into
\type {font.fonts}). If the font creation fails, an error is raised. The table is
a font structure. An alternative call is:

\startfunctioncall
<number> i =
    font.define(<number> n, <table> f)
\stopfunctioncall

Where the first argument is a reserved font id (see below).

\subsection{Extending a font}

\topicindex {fonts+extend}

Within reasonable bounds you can extend a font after it has been defined. Because
some properties are best left unchanged this is limited to adding characters.

\startfunctioncall
font.addcharacters(<number n>, <table> f)
\stopfunctioncall

The table passed can have the fields \type {characters} which is a (sub)table
like the one used in define, and for virtual fonts a \type {fonts} table can be
added. The characters defined in the \type {characters} table are added (when not
yet present) or replace an existing entry. Keep in mind that replacing can have
side effects because a character already can have been used. Instead of posing
restrictions we expect the user to be careful. (The \type {setfont} helper is
a more drastic replacer.)

\subsection{Projected next font id}

\topicindex {fonts+id}

\startfunctioncall
<number> i =
    font.nextid()
\stopfunctioncall

This returns the font id number that would be returned by a \type {font.define}
call if it was executed at this spot in the code flow. This is useful for virtual
fonts that need to reference themselves. If you pass \type {true} as argument,
the id gets reserved and you can pass to \type {font.define} as first argument.
This can be handy when you create complex virtual fonts.

\startfunctioncall
<number> i =
    font.nextid(true)
\stopfunctioncall

\subsection{Font ids}

\topicindex {fonts+id}
\topicindex {fonts+current}

\startfunctioncall
<number> i =
    font.id(<string> csname)
\stopfunctioncall

This returns the font id associated with \type {csname}, or $-1$ if \type
{csname} is not defined.

\startfunctioncall
<number> i =
    font.max()
\stopfunctioncall

This is the largest used index in \type {font.fonts}.

\startfunctioncall
<number> i = font.current()
font.current(<number> i)
\stopfunctioncall

This gets or sets the currently used font number.

\subsection{Iterating over all fonts}

\topicindex {fonts+iterate}

\startfunctioncall
for i,v in font.each() do
  ...
end
\stopfunctioncall

This is an iterator over each of the defined \TEX\ fonts. The first returned
value is the index in \type {font.fonts}, the second the font itself, as a \LUA\
table. The indices are listed incrementally, but they do not always form an array
of consecutive numbers: in some cases there can be holes in the sequence.

\stopsection

\stopchapter

\stopcomponent