Debian Codegraph @

texmf-dist/doc/luatex/base/luatex-fonts.tex

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