luatex-fonts.tex /size: 42 Kb    last modification: 2023-12-21 09:43
1% language=us engine=luatex runpath=texruns:manuals/luatex
2
3\environment luatex-style
4
5\startcomponent luatex-fonts
6
7\startchapter[reference=fonts,title={Font structure}]
8
9\startsection[title={The font tables}]
10
11\topicindex {fonts}
12\topicindex {fonts+tables}
13
14All \TEX\ fonts are represented to \LUA\ code as tables, and internally as
15\CCODE~structures. All keys in the table below are saved in the internal font
16structure if they are present in the table returned by the \cbk {define_font}
17callback, or if they result from the normal \TFM|/|\VF\ reading routines if there
18is no \cbk {define_font} callback defined.
19
20The column \quote {\VF} means that this key will be created by the \type
21{font.read_vf()} routine, \quote {\TFM} means that the key will be created by the
22\type {font.read_tfm()} routine, and \quote {used} means whether or not the
23\LUATEX\ engine itself will do something with the key. The top|-|level keys in
24the table are as follows:
25
26\starttabulate[|l|c|c|c|l|pl|]
27\DB key                     \BC vf  \BC tfm \BC used \BC value type \BC description \NC \NR
28\TB
29\NC \type{name}             \NC yes \NC yes \NC yes  \NC string     \NC metric (file) name \NC \NR
30\NC \type{area}             \NC no  \NC yes \NC yes  \NC string     \NC (directory) location, typically empty \NC \NR
31\NC \type{used}             \NC no  \NC yes \NC yes  \NC boolean    \NC indicates usage (initial: false) \NC \NR
32\NC \type{characters}       \NC yes \NC yes \NC yes  \NC table      \NC the defined glyphs of this font \NC \NR
33\NC \type{checksum}         \NC yes \NC yes \NC no   \NC number     \NC default: 0 \NC \NR
34\NC \type{designsize}       \NC no  \NC yes \NC yes  \NC number     \NC expected size (default: 655360 == 10pt) \NC \NR
35\NC \type{direction}        \NC no  \NC yes \NC yes  \NC number     \NC default: 0 \NC \NR
36\NC \type{encodingbytes}    \NC no  \NC no  \NC yes  \NC number     \NC default: depends on \type {format} \NC \NR
37\NC \type{encodingname}     \NC no  \NC no  \NC yes  \NC string     \NC encoding name \NC \NR
38\NC \type{fonts}            \NC yes \NC no  \NC yes  \NC table      \NC locally used fonts \NC \NR
39\NC \type{psname}           \NC no  \NC no  \NC yes  \NC string     \NC This is the \POSTSCRIPT\ fontname in the incoming font
40                                                                        source, and it's used as fontname identifier in the \PDF\
41                                                                        output. This has to be a valid string, e.g.\ no spaces
42                                                                        and such, as the backend will not do a cleanup. This gives
43                                                                        complete control to the loader. \NC \NR
44\NC \type{fullname}         \NC no  \NC no  \NC yes  \NC string     \NC output font name, used as a fallback in the \PDF\ output
45                                                                        if the \type {psname} is not set \NC \NR
46\NC \type{subfont}          \NC no  \NC no  \NC yes  \NC number     \NC default: 0, index in (\type {ttc}) font with multiple fonts \NC \NR
47\NC \type{header}           \NC yes \NC no  \NC no   \NC string     \NC header comments, if any \NC \NR
48\NC \type{hyphenchar}       \NC no  \NC no  \NC yes  \NC number     \NC default: \TEX's \prm {hyphenchar} \NC \NR
49\NC \type{parameters}       \NC no  \NC yes \NC yes  \NC hash       \NC default: 7 parameters, all zero \NC \NR
50\NC \type{size}             \NC no  \NC yes \NC yes  \NC number     \NC the required scaling (by default the same as designsize) \NC \NR
51\NC \type{skewchar}         \NC no  \NC no  \NC yes  \NC number     \NC default: \TEX's \prm {skewchar} \NC \NR
52\NC \type{type}             \NC yes \NC no  \NC yes  \NC string     \NC basic type of this font \NC \NR
53\NC \type{format}           \NC no  \NC no  \NC yes  \NC string     \NC disk format type \NC \NR
54\NC \type{embedding}        \NC no  \NC no  \NC yes  \NC string     \NC \PDF\ inclusion  \NC \NR
55\NC \type{filename}         \NC no  \NC no  \NC yes  \NC string     \NC the name of the font on disk \NC \NR
56\NC \type{tounicode}        \NC no  \NC yes \NC yes  \NC number     \NC When this is set to~1 \LUATEX\ assumes per|-|glyph
57                                                                        tounicode entries are present in the font. \NC \NR
58\NC \type{stretch}          \NC no  \NC no  \NC yes  \NC number     \NC the \quote {stretch} value from \lpr {expandglyphsinfont} \NC \NR
59\NC \type{shrink}           \NC no  \NC no  \NC yes  \NC number     \NC the \quote {shrink} value from \lpr {expandglyphsinfont} \NC \NR
60\NC \type{step}             \NC no  \NC no  \NC yes  \NC number     \NC the \quote {step} value from \lpr {expandglyphsinfont} \NC \NR
61\NC \type{expansion_factor} \NC no  \NC no  \NC no   \NC number     \NC the actual expansion factor of an expanded font \NC \NR
62\NC \type{attributes}       \NC no  \NC no  \NC yes  \NC string     \NC the \orm {pdffontattr} \NC \NR
63\NC \type{cache}            \NC no  \NC no  \NC yes  \NC string     \NC This key controls caching of the \LUA\ table on the
64                                                                        \TEX\ end where \type {yes} means: use a reference to
65                                                                        the table that is passed to \LUATEX\ (this is the
66                                                                        default), and \type {no} means: don't store the
67                                                                        table reference, don't cache any \LUA\ data for this
68                                                                        font while \type {renew} means: don't store the table
69                                                                        reference, but save a reference to the table that is
70                                                                        created at the first access to one of its fields in the
71                                                                        font. \NC \NR
72\NC \type{nomath}           \NC no  \NC no  \NC yes  \NC boolean    \NC This key allows a minor speedup for text fonts. If it
73                                                                        is present and true, then \LUATEX\ will not check the
74                                                                        character entries for math|-|specific keys. \NC \NR
75\NC \type{oldmath}          \NC no  \NC no  \NC yes  \NC boolean    \NC This key flags a font as representing an old school \TEX\
76                                                                        math font and disables the \OPENTYPE\ code path. \NC \NR
77\NC \type{slant}            \NC no  \NC no  \NC yes  \NC number     \NC This parameter will tilt the font and
78                                                                        does the same as \type {SlantFont} in the map file for
79                                                                        \TYPEONE\ fonts. \NC \NR
80\NC \type{extend}           \NC no  \NC no  \NC yes  \NC number     \NC This parameter will scale the font horizontally and
81                                                                        does the same as \type {ExtendFont} in the map file for
82                                                                        \TYPEONE\ fonts. \NC \NR
83\NC \type{squeeze}          \NC no  \NC no  \NC yes  \NC number     \NC This parameter will scale the font vertically and has
84                                                                        no equivalent in the map file. \NC \NR
85\NC \type{width}            \NC no  \NC no  \NC yes  \NC number     \NC The backend will inject \PDF\ operators that set the
86                                                                        penwidth. The value is (as usual in \TEX) divided by 1000.
87                                                                        It works with the \type {mode} file. \NC \NR
88\NC \type{mode}             \NC no  \NC no  \NC yes  \NC number     \NC The backend will inject \PDF\ operators that relate to the
89                                                                        drawing mode with 0~being a fill, 1~being an outline,
90                                                                        2~both draw and fill and 3~no painting at all. \NC \NR
91\LL
92\stoptabulate
93
94The saved reference in the \type {cache} option is thread|-|local, so be careful
95when you are using coroutines: an error will be thrown if the table has been
96cached in one thread, but you reference it from another thread.
97
98The key \type {name} is always required. The keys \type {stretch}, \type
99{shrink}, \type {step} only have meaning when used together: they can be used to
100replace a post|-|loading \lpr {expandglyphsinfont} command. The \type
101{auto_expand} option is not supported in \LUATEX. In fact, the primitives that
102create expanded or protruding copies are probably only useful when used with
103traditional fonts because all these extra \OPENTYPE\ properties are kept out of
104the picture. The \type {expansion_factor} is value that can be present inside a
105font in \type {font.fonts}. It is the actual expansion factor (a value between
106\type {-shrink} and \type {stretch}, with step \type {step}) of a font that was
107automatically generated by the font expansion algorithm.
108
109The \type {subfont} parameter can be used to specify the subfont in a \type {ttc}
110font. When given, it is used instead of the \type {psname} and \type {fullname}
111combination. The first subfont has number~1. A zero value signals using the names
112as lookup.
113
114Because we store the actual state of expansion with each glyph and don't have
115special font instances, we can change some font related parameters before lines
116are constructed, like:
117
118\starttyping
119font.setexpansion(font.current(),100,100,20)
120\stoptyping
121
122This is mostly meant for experiments (or an optimizing routing written in \LUA)
123so there is no primitive.
124
125The key \type {attributes} can be used to set font attributes in the \PDF\ file.
126The key \type {used} is set by the engine when a font is actively in use, this
127makes sure that the font's definition is written to the output file (\DVI\ or
128\PDF). The \TFM\ reader sets it to false. The \type {direction} is a number
129signalling the \quote {normal} direction for this font. There are sixteen
130possibilities:
131
132\starttabulate[|Tc|c|Tc|c|Tc|c|Tc|c|]
133\DB \# \BC dir \BC \# \BC dir \BC \# \BC dir \BC \# \BC dir \NC \NR
134\TB
135\NC  0 \NC LT  \NC  4 \NC RT  \NC  8 \NC TT  \NC 12 \NC BT  \NC \NR
136\NC  1 \NC LL  \NC  5 \NC RL  \NC  9 \NC TL  \NC 13 \NC BL  \NC \NR
137\NC  2 \NC LB  \NC  6 \NC RB  \NC 10 \NC TB  \NC 14 \NC BB  \NC \NR
138\NC  3 \NC LR  \NC  7 \NC RR  \NC 11 \NC TR  \NC 15 \NC BR  \NC \NR
139\LL
140\stoptabulate
141
142These are \OMEGA|-|style direction abbreviations: the first character indicates
143the \quote {first} edge of the character glyphs (the edge that is seen first in
144the writing direction), the second the \quote {top} side. Keep in mind that
145\LUATEX\ has a bit different directional model so these values are not used for
146anything.
147
148The \type {parameters} is a hash with mixed key types. There are seven possible
149string keys, as well as a number of integer indices (these start from 8 up). The
150seven strings are actually used instead of the bottom seven indices, because that
151gives a nicer user interface.
152
153The names and their internal remapping are:
154
155\starttabulate[|l|c|]
156\DB name                  \BC remapping \NC \NR
157\TB
158\NC \type {slant}         \NC 1 \NC \NR
159\NC \type {space}         \NC 2 \NC \NR
160\NC \type {space_stretch} \NC 3 \NC \NR
161\NC \type {space_shrink}  \NC 4 \NC \NR
162\NC \type {x_height}      \NC 5 \NC \NR
163\NC \type {quad}          \NC 6 \NC \NR
164\NC \type {extra_space}   \NC 7 \NC \NR
165\LL
166\stoptabulate
167
168The keys \type {type}, \type {format}, \type {embedding}, \type {fullname} and
169\type {filename} are used to embed \OPENTYPE\ fonts in the result \PDF.
170
171The \type {characters} table is a list of character hashes indexed by an integer
172number. The number is the \quote {internal code} \TEX\ knows this character by.
173
174Two very special string indexes can be used also: \type {left_boundary} is a
175virtual character whose ligatures and kerns are used to handle word boundary
176processing. \type {right_boundary} is similar but not actually used for anything
177(yet).
178
179Each character hash itself is a hash. For example, here is the character \quote
180{f} (decimal 102) in the font \type {cmr10 at 10pt}. The numbers that represent
181dimensions are in scaled points.
182
183\starttyping
184[102] = {
185    ["width"]  = 200250,
186    ["height"] = 455111,
187    ["depth"]  = 0,
188    ["italic"] = 50973,
189    ["kerns"]  = {
190        [63] = 50973,
191        [93] = 50973,
192        [39] = 50973,
193        [33] = 50973,
194        [41] = 50973
195    },
196    ["ligatures"] = {
197        [102] = { ["char"] = 11, ["type"] = 0 },
198        [108] = { ["char"] = 13, ["type"] = 0 },
199        [105] = { ["char"] = 12, ["type"] = 0 }
200    }
201}
202\stoptyping
203
204The following top|-|level keys can be present inside a character hash:
205
206\starttabulate[|l|c|c|c|l|p|]
207\DB key                     \BC vf  \BC tfm \BC used  \BC type    \BC description \NC\NR
208\TB
209\NC \type{width}            \NC yes \NC yes \NC yes   \NC number  \NC character's width, in sp (default 0) \NC\NR
210\NC \type{height}           \NC no  \NC yes \NC yes   \NC number  \NC character's height, in sp (default 0) \NC\NR
211\NC \type{depth}            \NC no  \NC yes \NC yes   \NC number  \NC character's depth, in sp (default 0) \NC\NR
212\NC \type{italic}           \NC no  \NC yes \NC yes   \NC number  \NC character's italic correction, in sp (default zero) \NC\NR
213\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
214\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
215\NC \type{left_protruding}  \NC no  \NC no  \NC maybe \NC number  \NC character's \lpr {lpcode} \NC\NR
216\NC \type{right_protruding} \NC no  \NC no  \NC maybe \NC number  \NC character's \lpr {rpcode} \NC\NR
217\NC \type{expansion_factor} \NC no  \NC no  \NC maybe \NC number  \NC character's \lpr {efcode} \NC\NR
218\NC \type{tounicode}        \NC no  \NC no  \NC maybe \NC string  \NC character's \UNICODE\ equivalent(s), in \UTF|-|16BE hexadecimal format \NC\NR
219\NC \type{next}             \NC no  \NC yes \NC yes   \NC number  \NC the \quote {next larger} character index \NC\NR
220\NC \type{extensible}       \NC no  \NC yes \NC yes   \NC table   \NC the constituent parts of an extensible recipe \NC\NR
221\NC \type{vert_variants}    \NC no  \NC no  \NC yes   \NC table   \NC constituent parts of a vertical variant set \NC \NR
222\NC \type{horiz_variants}   \NC no  \NC no  \NC yes   \NC table   \NC constituent parts of a horizontal variant set \NC \NR
223\NC \type{kerns}            \NC no  \NC yes \NC yes   \NC table   \NC kerning information \NC\NR
224\NC \type{ligatures}        \NC no  \NC yes \NC yes   \NC table   \NC ligaturing information \NC\NR
225\NC \type{commands}         \NC yes \NC no  \NC yes   \NC array   \NC virtual font commands \NC\NR
226\NC \type{name}             \NC no  \NC no  \NC no    \NC string  \NC the character (\POSTSCRIPT) name \NC\NR
227\NC \type{index}            \NC no  \NC no  \NC yes   \NC number  \NC the (\OPENTYPE\ or \TRUETYPE) font glyph index \NC\NR
228\NC \type{used}             \NC no  \NC yes \NC yes   \NC boolean \NC typeset already (default: false) \NC\NR
229\NC \type{mathkern}         \NC no  \NC no  \NC yes   \NC table   \NC math cut-in specifications \NC\NR
230\LL
231\stoptabulate
232
233The values of \type {top_accent}, \type {bot_accent} and \type {mathkern} are
234used only for math accent and superscript placement, see \at {page} [math] in
235this manual for details. The values of \type {left_protruding} and \type
236{right_protruding} are used only when \lpr {protrudechars} is non-zero. Whether
237or not \type {expansion_factor} is used depends on the font's global expansion
238settings, as well as on the value of \lpr {adjustspacing}.
239
240The usage of \type {tounicode} is this: if this font specifies a \type
241{tounicode=1} at the top level, then \LUATEX\ will construct a \type {/ToUnicode}
242entry for the \PDF\ font (or font subset) based on the character|-|level \type
243{tounicode} strings, where they are available. If a character does not have a
244sensible \UNICODE\ equivalent, do not provide a string either (no empty strings).
245
246If the font level \type {tounicode} is not set, then \LUATEX\ will build up \type
247{/ToUnicode} based on the \TEX\ code points you used, and any character-level
248\type {tounicodes} will be ignored. The string format is exactly the format that
249is expected by Adobe \CMAP\ files (\UTF-16BE in hexadecimal encoding), minus the
250enclosing angle brackets. For instance the \type {tounicode} for a \type {fi}
251ligature would be \type {00660069}. When you pass a number the conversion will be
252done for you.
253
254A math character can have a \type {next} field that points to a next larger
255shape. However, the presence of \type {extensible} will overrule \type {next}, if
256that is also present. The \type {extensible} field in turn can be overruled by
257\type {vert_variants}, the \OPENTYPE\ version. The \type {extensible} table is
258very simple:
259
260\starttabulate[|l|l|p|]
261\DB key        \BC type   \BC description                \NC\NR
262\TB
263\NC \type{top} \NC number \NC top character index        \NC\NR
264\NC \type{mid} \NC number \NC middle character index     \NC\NR
265\NC \type{bot} \NC number \NC bottom character index     \NC\NR
266\NC \type{rep} \NC number \NC repeatable character index \NC\NR
267\LL
268\stoptabulate
269
270The \type {horiz_variants} and \type {vert_variants} are arrays of components.
271Each of those components is itself a hash of up to five keys:
272
273\starttabulate[|l|l|p|]
274\DB key             \BC type   \BC explanation \NC \NR
275\TB
276\NC \type{glyph}    \NC number \NC The character index. Note that this is an encoding number, not a name. \NC \NR
277\NC \type{extender} \NC number \NC One (1) if this part is repeatable, zero (0) otherwise. \NC \NR
278\NC \type{start}    \NC number \NC The maximum overlap at the starting side (in scaled points). \NC \NR
279\NC \type{end}      \NC number \NC The maximum overlap at the ending side (in scaled points). \NC \NR
280\NC \type{advance}  \NC number \NC The total advance width of this item. It can be zero or missing,
281                                   then the natural size of the glyph for character \type {component}
282                                   is used. \NC \NR
283\LL
284\stoptabulate
285
286The \type {kerns} table is a hash indexed by character index (and \quote
287{character index} is defined as either a non|-|negative integer or the string
288value \type {right_boundary}), with the values of the kerning to be applied, in
289scaled points.
290
291The \type {ligatures} table is a hash indexed by character index (and \quote
292{character index} is defined as either a non|-|negative integer or the string
293value \type {right_boundary}), with the values being yet another small hash, with
294two fields:
295
296\starttabulate[|l|l|p|]
297\DB key         \BC type   \BC description \NC \NR
298\TB
299\NC \type{type} \NC number \NC the type of this ligature command, default 0 \NC \NR
300\NC \type{char} \NC number \NC the character index of the resultant ligature \NC \NR
301\LL
302\stoptabulate
303
304The \type {char} field in a ligature is required. The \type {type} field inside a
305ligature is the numerical or string value of one of the eight possible ligature
306types supported by \TEX. When \TEX\ inserts a new ligature, it puts the new glyph
307in the middle of the left and right glyphs. The original left and right glyphs
308can optionally be retained, and when at least one of them is kept, it is also
309possible to move the new \quote {insertion point} forward one or two places. The
310glyph that ends up to the right of the insertion point will become the next
311\quote {left}.
312
313\starttabulate[|l|c|l|l|]
314\DB textual (Knuth)       \BC number \BC string        \BC result      \NC\NR
315\TB
316\NC \type{l + r =: n}     \NC 0      \NC \type{=:}     \NC \type{|n}   \NC\NR
317\NC \type{l + r =:| n}    \NC 1      \NC \type{=:|}    \NC \type{|nr}  \NC\NR
318\NC \type{l + r |=: n}    \NC 2      \NC \type{|=:}    \NC \type{|ln}  \NC\NR
319\NC \type{l + r |=:| n}   \NC 3      \NC \type{|=:|}   \NC \type{|lnr} \NC\NR
320\NC \type{l + r  =:|> n}  \NC 5      \NC \type{=:|>}   \NC \type{n|r}  \NC\NR
321\NC \type{l + r |=:> n}   \NC 6      \NC \type{|=:>}   \NC \type{l|n}  \NC\NR
322\NC \type{l + r |=:|> n}  \NC 7      \NC \type{|=:|>}  \NC \type{l|nr} \NC\NR
323\NC \type{l + r |=:|>> n} \NC 11     \NC \type{|=:|>>} \NC \type{ln|r} \NC\NR
324\LL
325\stoptabulate
326
327The default value is~0, and can be left out. That signifies a \quote {normal}
328ligature where the ligature replaces both original glyphs. In this table the~\type {|}
329indicates the final insertion point.
330
331The \type {commands} array is explained below.
332
333\stopsection
334
335\startsection[title={Real fonts}]
336
337\topicindex {fonts+real}
338\topicindex {fonts+virtual}
339
340Whether or not a \TEX\ font is a \quote {real} font that should be written to the
341\PDF\ document is decided by the \type {type} value in the top|-|level font
342structure. If the value is \type {real}, then this is a proper font, and the
343inclusion mechanism will attempt to add the needed font object definitions to the
344\PDF. Values for \type {type} are:
345
346\starttabulate[|l|p|]
347\DB value          \BC description            \NC\NR
348\TB
349\NC \type{real}    \NC this is a base font    \NC\NR
350\NC \type{virtual} \NC this is a virtual font \NC\NR
351\LL
352\stoptabulate
353
354The actions to be taken depend on a number of different variables:
355
356\startitemize[packed]
357\startitem
358    Whether the used font fits in an 8-bit encoding scheme or not. This is true for
359    traditional \TEX\ fonts that communicate via \TFM\ files.
360\stopitem
361\startitem
362    The type of the disk font file, for instance a bitmap file or an outline
363    \TYPEONE, \TRUETYPE\ or \OPENTYPE\ font.
364\stopitem
365\startitem
366    The level of embedding requested, although in most cases a subset of
367    characters is embedded. The times when nothing got embedded are (in our
368    opinion at least) basically gone.
369\stopitem
370\stopitemize
371
372A font that uses anything other than an 8-bit encoding vector has to be written
373to the \PDF\ in a different way. When the font table has \type {encodingbytes}
374set to~2, then it is a wide font, in all other cases it isn't. The value~2 is the
375default for \OPENTYPE\ and \TRUETYPE\ fonts loaded via \LUA. For \TYPEONE\ fonts,
376you have to set \type {encodingbytes} to~2 explicitly. For \PK\ bitmap fonts,
377wide font encoding is not supported at all.
378
379If no special care is needed, \LUATEX\ falls back to the mapfile|-|based solution
380used by \PDFTEX\ and \DVIPS, so that legacy fonts are supported transparently. If
381a \quote {wide} font is used, the new subsystem kicks in, and some extra fields
382have to be present in the font structure. In this case, \LUATEX\ does not use a
383map file at all. These extra fields are: \type {format}, \type {embedding}, \type
384{fullname}, \type {cidinfo} (as explained above), \type {filename}, and the \type
385{index} key in the separate characters.
386
387The \type {format} variable can have the following values. \type {type3} fonts
388are provided for backward compatibility only, and do not support the new wide
389encoding options.
390
391\starttabulate[|l|p|]
392\DB value           \BC description                                               \NC \NR
393\TB
394\NC \type{type1}    \NC this is a \POSTSCRIPT\ \TYPEONE\ font                     \NC \NR
395\NC \type{type3}    \NC this is a bitmapped (\PK) font                            \NC \NR
396\NC \type{truetype} \NC this is a \TRUETYPE\ or \TRUETYPE|-|based \OPENTYPE\ font \NC \NR
397\NC \type{opentype} \NC this is a \POSTSCRIPT|-|based \OPENTYPE\ font             \NC \NR
398\LL
399\stoptabulate
400
401Valid values for the \type {embedding} variable are:
402
403\starttabulate[|l|p|]
404\DB value         \BC description                             \NC \NR
405\TB
406\NC \type{no}     \NC don't embed the font at all             \NC \NR
407\NC \type{subset} \NC include and atttempt to subset the font \NC \NR
408\NC \type{full}   \NC include this font in its entirety       \NC \NR
409\LL
410\stoptabulate
411
412The other fields are used as follows. The \type {fullname} will be the
413\POSTSCRIPT|/|\PDF\ font name. The \type {cidinfo} will be used as the character
414set: the CID \type {/Ordering} and \type {/Registry} keys. The \type {filename}
415points to the actual font file. If you include the full path in the \type
416{filename} or if the file is in the local directory, \LUATEX\ will run a little
417bit more efficient because it will not have to re|-|run the \type {find_*_file}
418callback in that case.
419
420Be careful: when mixing old and new fonts in one document, it is possible to
421create \POSTSCRIPT\ name clashes that can result in printing errors. When this
422happens, you have to change the \type {fullname} of the font to a more unique
423one.
424
425Typeset strings are written out in a wide format using 2~bytes per glyph, using
426the \type {index} key in the character information as value. The overall effect
427is like having an encoding based on numbers instead of traditional (\POSTSCRIPT)
428name|-|based reencoding. One way to get the correct \type {index} numbers for
429\TYPEONE\ fonts is by loading the font via \type {fontloader.open} and use the
430table indices as \type {index} fields.
431
432In order to make sure that cut and paste of the final document works okay you can
433best make sure that there is a \type {tounicode} vector enforced. Not all \PDF\
434viewers handle this right so take \ACROBAT\ as reference.
435
436\stopsection
437
438\startsection[reference=virtualfonts,title={Virtual fonts}]
439
440\subsection{The structure}
441
442\topicindex {fonts+virtual}
443
444You have to take the following steps if you want \LUATEX\ to treat the returned
445table from \cbk {define_font} as a virtual font:
446
447\startitemize[packed]
448\startitem
449    Set the top|-|level key \type {type} to \type {virtual}. In most cases it's
450    optional because we look at the \type {commands} entry anyway.
451\stopitem
452\startitem
453    Make sure there is at least one valid entry in \type {fonts} (see below),
454    although recent versions of \LUATEX\ add a default entry when this table is
455    missing.
456\stopitem
457\startitem
458    Add a \type {commands} array to those characters that matter. A virtual
459    character can itself point to virtual characters but be careful with nesting
460    as you can create loops and overflow the stack (which often indicates an
461    error anyway).
462\stopitem
463\stopitemize
464
465The presence of the toplevel \type {type} key with the specific value \type
466{virtual} will trigger handling of the rest of the special virtual font fields in
467the table, but the mere existence of 'type' is enough to prevent \LUATEX\ from
468looking for a virtual font on its own. This also works \quote {in reverse}: if
469you are absolutely certain that a font is not a virtual font, assigning the value
470\type {real} to \type {type} will inhibit \LUATEX\ from looking for a virtual
471font file, thereby saving you a disk search. This only matters when we load a
472\TFM\ file.
473
474The \type {fonts} is an (indexed) \LUA\ table. The values are one- or two|-|key
475hashes themselves, each entry indicating one of the base fonts in a virtual font.
476In case your font is referring to itself, you can use the \type {font.nextid()}
477function which returns the index of the next to be defined font which is probably
478the currently defined one. So, a table looks like this:
479
480\starttyping
481fonts = {
482  { name = "ptmr8a", size = 655360 },
483  { name = "psyr", size = 600000 },
484  { id = 38 }
485}
486\stoptyping
487
488The first referenced font (at index~1) in this virtual font is \type {ptrmr8a}
489loaded at 10pt, and the second is \type {psyr} loaded at a little over 9pt. The
490third one is a previously defined font that is known to \LUATEX\ as font id~38.
491The array index numbers are used by the character command definitions that are
492part of each character.
493
494The \type {commands} array is a hash where each item is another small array,
495with the first entry representing a command and the extra items being the
496parameters to that command. The allowed commands and their arguments are:
497
498\starttabulate[|l|l|l|p|]
499\DB command        \BC arguments \BC type      \BC description \NC \NR
500\TB
501\NC \type{font}    \NC 1         \NC number    \NC select a new font from the local \type {fonts} table \NC \NR
502\NC \type{char}    \NC 1         \NC number    \NC typeset this character number from the current font,
503                                                   and move right by the character's width \NC \NR
504\NC \type{node}    \NC 1         \NC node      \NC output this node (list), and move right
505                                                   by the width of this list\NC \NR
506\NC \type{slot}    \NC 2         \NC 2 numbers \NC a shortcut for the combination of a font and char command\NC \NR
507\NC \type{push}    \NC 0         \NC           \NC save current position\NC \NR
508\NC \type{nop}     \NC 0         \NC           \NC do nothing \NC \NR
509\NC \type{pop}     \NC 0         \NC           \NC pop position \NC \NR
510\NC \type{rule}    \NC 2         \NC 2 numbers \NC output a rule $ht*wd$, and move right. \NC \NR
511\NC \type{down}    \NC 1         \NC number    \NC move down on the page \NC \NR
512\NC \type{right}   \NC 1         \NC number    \NC move right on the page \NC \NR
513\NC \type{special} \NC 1         \NC string    \NC output a \prm {special} command \NC \NR
514\NC \type{pdf}     \NC 2         \NC 2 strings \NC output a \PDF\ literal, the first string is one of \type {origin},
515                                                   \type {page}, \type {text}, \type {font}, \type {direct} or \type {raw}; if you
516                                                   have one string only \type {origin} is assumed \NC \NR
517\NC \type{lua}     \NC 1         \NC string,
518                                     function  \NC execute a \LUA\ script when the glyph is embedded; in case of a
519                                                   function it gets the font id and character code passed \NC \NR
520\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
521\NC \type{comment} \NC any       \NC any       \NC the arguments of this command are ignored \NC \NR
522\LL
523\stoptabulate
524
525When a font id is set to~0 then it will be replaced by the currently assigned
526font id. This prevents the need for hackery with future id's. Normally one could
527use \type {font.nextid} but when more complex fonts are built in the meantime
528other instances could have been loaded.
529
530The \type {pdf} option also accepts a \type {mode} keyword in which case the
531third argument sets the mode. That option will change the mode in an efficient
532way (passing an empty string would result in an extra empty lines in the \PDF\
533file. This option only makes sense for virtual fonts. The \type {font} mode only
534makes sense in virtual fonts. Modes are somewhat fuzzy and partially inherited
535from \PDFTEX.
536
537\starttabulate[|l|p|]
538\DB mode           \BC description \NC \NR
539\TB
540\NC \type {origin} \NC enter page mode and set the position \NC \NR
541\NC \type {page}   \NC enter page mode \NC \NR
542\NC \type {text}   \NC enter text mode \NC \NR
543\NC \type {font}   \NC enter font mode (kind of text mode, only in virtual fonts) \NC \NR
544\NC \type {always} \NC finish the current string and force a transform if needed \NC \NR
545\NC \type {raw}    \NC finish the current string \NC \NR
546\LL
547\stoptabulate
548
549You always need to check what \PDF\ code is generated because there can be all
550kind of interferences with optimization in the backend and fonts are complicated
551anyway. Here is a rather elaborate glyph commands example using such keys:
552
553\starttyping
554...
555commands = {
556    { "push" },                     -- remember where we are
557    { "right", 5000 },              -- move right about 0.08pt
558    { "font", 3 },                  -- select the fonts[3] entry
559    { "char", 97 },                 -- place character 97 (ASCII 'a')
560 -- { "slot", 2, 97 },              -- an alternative for the previous two
561    { "pop" },                      -- go all the way back
562    { "down", -200000 },            -- move upwards by about 3pt
563    { "special", "pdf: 1 0 0 rg" }  -- switch to red color
564 -- { "pdf", "origin", "1 0 0 rg" } -- switch to red color (alternative)
565    { "rule", 500000, 20000 }       -- draw a bar
566    { "special", "pdf: 0 g" }       -- back to black
567 -- { "pdf", "origin", "0 g" }      -- back to black (alternative)
568}
569...
570\stoptyping
571
572The default value for \type {font} is always~1 at the start of the
573\type {commands} array. Therefore, if the virtual font is essentially only a
574re|-|encoding, then you do usually not have created an explicit \quote {font}
575command in the array.
576
577Rules inside of \type {commands} arrays are built up using only two dimensions:
578they do not have depth. For correct vertical placement, an extra \type {down}
579command may be needed.
580
581Regardless of the amount of movement you create within the \type {commands}, the
582output pointer will always move by exactly the width that was given in the \type
583{width} key of the character hash. Any movements that take place inside the \type
584{commands} array are ignored on the upper level.
585
586The special can have a \type {pdf:}, \type {pdf:origin:},  \type {pdf:page:},
587\type {pdf:direct:} or  \type {pdf:raw:} prefix. When you have to concatenate
588strings using the \type {pdf} command might be more efficient.
589
590\subsection{Artificial fonts}
591
592Even in a \quote {real} font, there can be virtual characters. When \LUATEX\
593encounters a \type {commands} field inside a character when it becomes time to
594typeset the character, it will interpret the commands, just like for a true
595virtual character. In this case, if you have created no \quote {fonts} array,
596then the default (and only) \quote {base} font is taken to be the current font
597itself. In practice, this means that you can create virtual duplicates of
598existing characters which is useful if you want to create composite characters.
599
600Note: this feature does {\it not\/} work the other way around. There can not be
601\quote {real} characters in a virtual font! You cannot use this technique for
602font re-encoding either; you need a truly virtual font for that (because
603characters that are already present cannot be altered).
604
605\subsection{Example virtual font}
606
607\topicindex {fonts+virtual}
608
609Finally, here is a plain \TEX\ input file with a virtual font demonstration:
610
611\startbuffer
612\directlua {
613  callback.register('define_font',
614    function (name,size)
615      if name == 'cmr10-red' then
616        local f = font.read_tfm('cmr10',size)
617        f.name  = 'cmr10-red'
618        f.type  = 'virtual'
619        f.fonts = {
620          { name = 'cmr10', size = size }
621        }
622        for i,v in pairs(f.characters) do
623          if string.char(i):find('[tacohanshartmut]') then
624             v.commands = {
625               { "special", "pdf: 1 0 0 rg" },
626               { "char", i },
627               { "special", "pdf: 0 g" },
628              }
629          end
630        end
631        return f
632      else
633        return font.read_tfm(name,size)
634      end
635    end
636  )
637}
638
639\font\myfont  = cmr10-red at 10pt \myfont  This is a line of text \par
640\font\myfontx = cmr10     at 10pt \myfontx Here is another line of text \par
641\stopbuffer
642
643\typebuffer
644
645\stopsection
646
647\startsection[title={The \type {vf} library}]
648
649The \type {vf} library can be used when \LUA\ code, as defined in the \type
650{commands} of the font, is executed. The functions provided are similar as the
651commands: \type {char}, \type {down}, \type {fontid}, \type {image}, \type
652{node}, \type {nop}, \type {pop}, \type {push}, \type {right}, \nod {rule}, \type
653{special} and \type {pdf}. This library has been present for a while but not been
654advertised and tested much, if only because it's easy to define an invalid font
655(or mess up the \PDF\ stream). Keep in mind that the \LUA\ snippets are executed
656each time when a character is output.
657
658\stopsection
659
660\startsection[title={The \type {font} library}]
661
662\topicindex {fonts+library}
663
664The font library provides the interface into the internals of the font system,
665and it also contains helper functions to load traditional \TEX\ font metrics
666formats. Other font loading functionality is provided by the \type {fontloader}
667library that will be discussed in the next section.
668
669\subsection{Loading a \TFM\ file}
670
671\topicindex {fonts+tfm}
672
673The behaviour documented in this subsection is considered stable in the sense that
674there will not be backward|-|incompatible changes any more.
675
676\startfunctioncall
677<table> fnt =
678    font.read_tfm(<string> name, <number> s)
679\stopfunctioncall
680
681The number is a bit special:
682
683\startitemize
684\startitem
685    If it is positive, it specifies an \quote {at size} in scaled points.
686\stopitem
687\startitem
688    If it is negative, its absolute value represents a \quote {scaled}
689    setting relative to the designsize of the font.
690\stopitem
691\stopitemize
692
693\subsection{Loading a \VF\ file}
694
695\topicindex {fonts+vf}
696
697The behavior documented in this subsection is considered stable in the sense that
698there will not be backward-incompatible changes any more.
699
700\startfunctioncall
701<table> vf_fnt =
702    font.read_vf(<string> name, <number> s)
703\stopfunctioncall
704
705The meaning of the number \type {s} and the format of the returned table are
706similar to the ones in the \type {read_tfm} function.
707
708\subsection{The fonts array}
709
710\topicindex {fonts+virtual}
711
712The whole table of \TEX\ fonts is accessible from \LUA\ using a virtual array.
713
714\starttyping
715font.fonts[n] = { ... }
716<table> f = font.fonts[n]
717\stoptyping
718
719Because this is a virtual array, you cannot call \type {pairs} on it, but see
720below for the \type {font.each} iterator.
721
722The two metatable functions implementing the virtual array are:
723
724\startfunctioncall
725<table> f = font.getfont(<number> n)
726font.setfont(<number> n, <table> f)
727\stopfunctioncall
728
729Note that at the moment, each access to the \type {font.fonts} or call to \type
730{font.getfont} creates a \LUA\ table for the whole font unless you cached it.
731If you want a copy of the internal data you can use \type {font.getcopy}:
732
733\startfunctioncall
734<table> f = font.getcopy(<number> n)
735\stopfunctioncall
736
737This one will return a table of the parameters as known to \TEX. These can be
738different from the ones in the cached table:
739
740\startfunctioncall
741<table> p = font.getparameters(<number> n)
742\stopfunctioncall
743
744Also note the following: assignments can only be made to fonts that have already
745been defined in \TEX, but have not been accessed {\it at all\/} since that
746definition. This limits the usability of the write access to \type {font.fonts}
747quite a lot, a less stringent ruleset will likely be implemented later.
748
749\subsection{Checking a font's status}
750
751You can test for the status of a font by calling this function:
752
753\startfunctioncall
754<boolean> f =
755    font.frozen(<number> n)
756\stopfunctioncall
757
758The return value is one of \type {true} (unassignable), \type {false} (can be
759changed) or \type {nil} (not a valid font at all).
760
761\subsection{Defining a font directly}
762
763\topicindex {fonts+define}
764
765You can define your own font into \type {font.fonts} by calling this function:
766
767\startfunctioncall
768<number> i =
769    font.define(<table> f)
770\stopfunctioncall
771
772The return value is the internal id number of the defined font (the index into
773\type {font.fonts}). If the font creation fails, an error is raised. The table is
774a font structure. An alternative call is:
775
776\startfunctioncall
777<number> i =
778    font.define(<number> n, <table> f)
779\stopfunctioncall
780
781Where the first argument is a reserved font id (see below).
782
783\subsection{Extending a font}
784
785\topicindex {fonts+extend}
786
787Within reasonable bounds you can extend a font after it has been defined. Because
788some properties are best left unchanged this is limited to adding characters.
789
790\startfunctioncall
791font.addcharacters(<number> n, <table> f)
792\stopfunctioncall
793
794The table passed can have the fields \type {characters} which is a (sub)table
795like the one used in define, and for virtual fonts a \type {fonts} table can be
796added. The characters defined in the \type {characters} table are added (when not
797yet present) or replace an existing entry. Keep in mind that replacing can have
798side effects because a character already can have been used. Instead of posing
799restrictions we expect the user to be careful. (The \type {setfont} helper is
800a more drastic replacer.)
801
802\subsection{Projected next font id}
803
804\topicindex {fonts+id}
805
806\startfunctioncall
807<number> i =
808    font.nextid()
809\stopfunctioncall
810
811This returns the font id number that would be returned by a \type {font.define}
812call if it was executed at this spot in the code flow. This is useful for virtual
813fonts that need to reference themselves. If you pass \type {true} as argument,
814the id gets reserved and you can pass to \type {font.define} as first argument.
815This can be handy when you create complex virtual fonts.
816
817\startfunctioncall
818<number> i =
819    font.nextid(true)
820\stopfunctioncall
821
822\subsection{Font ids}
823
824\topicindex {fonts+id}
825\topicindex {fonts+current}
826
827\startfunctioncall
828<number> i =
829    font.id(<string> csname)
830\stopfunctioncall
831
832This returns the font id associated with \type {csname}, or $-1$ if \type
833{csname} is not defined.
834
835\startfunctioncall
836<number> i =
837    font.max()
838\stopfunctioncall
839
840This is the largest used index in \type {font.fonts}.
841
842\startfunctioncall
843<number> i = font.current()
844font.current(<number> i)
845\stopfunctioncall
846
847This gets or sets the currently used font number.
848
849\subsection{Iterating over all fonts}
850
851\topicindex {fonts+iterate}
852
853\startfunctioncall
854for i,v in font.each() do
855  ...
856end
857\stopfunctioncall
858
859This is an iterator over each of the defined \TEX\ fonts. The first returned
860value is the index in \type {font.fonts}, the second the font itself, as a \LUA\
861table. The indices are listed incrementally, but they do not always form an array
862of consecutive numbers: in some cases there can be holes in the sequence.
863
864\startsubsection[title={\type{\glyphdimensionsmode}}]
865
866Already in the early days of \LUATEX\ the decision was made to calculate the
867effective height and depth of glyphs in a way that reflected the applied vertical
868offset. The height got that offset added, the depth only when the offset was
869larger than zero. We can now control this in more detail with this mode
870parameter. An offset is added to the height and|/|or subtracted from the depth.
871The effective values are never negative. The zero mode is the default.
872
873\starttabulate[|l|pl|]
874\DB value     \BC effect \NC\NR
875\TB
876\NC \type {0} \NC the old behavior: add the offset to the height and only subtract
877                  the offset only from the depth when it is positive \NC \NR
878\NC \type {1} \NC add the offset to the height and subtract it from the depth \NC \NR
879\NC \type {2} \NC add the offset to the height and subtract it from the depth but
880                  keep the maxima of the current and previous results \NC \NR
881\NC \type {3} \NC use the height and depth of the glyph, so no offset is applied \NC \NR
882\LL
883\stoptabulate
884
885\stopsubsection
886
887\startsubsection[title={\type {\discretionaryligaturemode}}]
888
889This parameter controls how complex ligatures interact with discretionaries (as
890injected by the hyphenator). The non||zero values prevent the construction of
891so called init and select discretionaries.
892
893\definefontfeature[ligmodetest][default][mode=base]
894\definefont       [ligmodefont][Serif*ligmodetest]
895
896\hyphenation{xx-f-f-i-xx}
897
898\starttabulate[|p|p|p|]
899    \DB 0 \BC 1 \BC 2 \NC \NR
900    \TB
901    \NC \ligmodefont \discretionaryligaturemode0 \hsize1pt xxffixx
902    \NC \ligmodefont \discretionaryligaturemode1 \hsize1pt xxffixx
903    \NC \ligmodefont \discretionaryligaturemode2 \hsize1pt xxffixx \NC \NR
904    \LL
905\stoptabulate
906
907\stopsubsection
908
909\stopsection
910
911\stopchapter
912
913\stopcomponent
914