luametatex-fonts.tex /size: 44 Kb    last modification: 2023-12-21 09:43
1% language=us runpath=texruns:manuals/luametatex
2
3\environment luametatex-style
4
5\startcomponent luametatex-fonts
6
7\startchapter[reference=fonts,title={Fonts}]
8
9\startsection[title={Introduction}]
10
11The traditional \TEX\ ligature and kerning routines are build in but anything
12more (like \OPENTYPE\ rendering) has to be implemented in \LUA. In \CONTEXT\ we
13call the former base mode and the later node mode (we have some more modes). This
14conforms to the \LUATEX\ philosophy. When you pass a font to the frontend only
15the dimensions matter, as these are used in typesetting, and optionally ligatures
16and kerns when you rely on the built|-|in font handler. For math some extra data
17is needed, like information about extensibles and next in size glyphs. You can of
18course put more information in your \LUA\ tables because when such a table is
19passed to \TEX\ only that what is needed is filtered from it.
20
21Because there is no built|-|in backend, virtual font information is not used. If
22you want to be compatible you'd better make sure that your tables are okay, and
23in that case you can best consult the \LUATEX\ manual. For instance, parameters
24like \type {extend} are backend related and the standard \LUATEX\ backend sets
25the standard here.
26
27\stopsection
28
29\startsection[title={Defining fonts}]
30
31All \TEX\ fonts are represented to \LUA\ code as tables, and internally as
32\CCODE\ structures. All keys in the table below are saved in the internal font
33structure if they are present in the table passed to \type {font.define}. When
34the callback is set, which is needed for \type {\font} to work, its function
35gets the name and size passed, and it has to return a valid font identifier (a
36positive number).
37
38For the engine to work well, the following information has to be present at
39the font level:
40
41\starttabulate[|l|l|pl|]
42\DB key                       \BC value type \BC description \NC \NR
43\TB
44\NC \type {name}              \NC string     \NC metric (file) name \NC \NR
45\NC \type {original}          \NC string     \NC the name used in logging and feedback \NC \NR
46\NC \type {designsize}        \NC number     \NC expected size (default: 655360 == 10pt) \NC \NR
47\NC \type {size}              \NC number     \NC the required scaling (by default the same as designsize) \NC \NR
48\HL
49\NC \type {characters}        \NC table      \NC the defined glyphs of this font \NC \NR
50\NC \type {fonts}             \NC table      \NC locally used fonts \NC \NR
51\NC \type {parameters}        \NC hash       \NC default: 7 parameters, all zero \NC \NR
52\HL
53\NC \type {stretch}           \NC number     \NC the \quote {stretch} \NC \NR
54\NC \type {shrink}            \NC number     \NC the \quote {shrink} \NC \NR
55\NC \type {step}              \NC number     \NC the \quote {step} \NC \NR
56\HL
57\NC \type {textcontrol}       \NC bitset     \NC this controls various code paths in the text engine \NC \NR
58\NC \type {hyphenchar}        \NC number     \NC default: \TEX's \prm {hyphenchar} \NC \NR
59\HL
60\NC \type {skewchar}          \NC number     \NC default: \TEX's \prm {skewchar} \NC \NR
61\NC \type {nomath}            \NC boolean    \NC this key allows a minor speedup for text fonts; if it
62                                                 is present and true, then \LUATEX\ will not check the
63                                                 character entries for math|-|specific keys \NC \NR
64\NC \type {oldmath}           \NC boolean    \NC this key flags a font as representing an old school \TEX\
65                                                 math font and disables the \OPENTYPE\ code path \NC \NR
66\NC \type {mathcontrol}       \NC bitset     \NC this controls various code paths in the math engine,
67                                                 like enforcing the traditional code path \NC \NR
68\NC \type {compactmath}       \NC boolean    \NC experimental: use the smaller chain to locate a character \NC \NR
69\NC \type {textscale}         \NC number     \NC scale applied to math text \NC \NR
70\NC \type {scriptscale}       \NC number     \NC scale applied to math script \NC \NR
71\NC \type {scriptscriptscale} \NC number     \NC scale applied to math script script \NC \NR
72\LL
73\stoptabulate
74
75The \type {parameters} is a hash with mixed key types. There are seven possible
76string keys, as well as a number of integer indices (these start from 8 up). The
77seven strings are actually used instead of the bottom seven indices, because that
78gives a nicer user interface.
79
80The names and their internal remapping are:
81
82\starttabulate[|l|c|]
83\DB name                  \BC remapping \NC \NR
84\TB
85\NC \type {slant}        \NC 1 \NC \NR
86\NC \type {space}        \NC 2 \NC \NR
87\NC \type {spacestretch} \NC 3 \NC \NR
88\NC \type {spaceshrink}  \NC 4 \NC \NR
89\NC \type {xheight}      \NC 5 \NC \NR
90\NC \type {quad}         \NC 6 \NC \NR
91\NC \type {extraspace}   \NC 7 \NC \NR
92\LL
93\stoptabulate
94
95The \type {characters} table is a \LUA\ hash table where the keys are integers.
96When a character in the input is turned into a glyph node, it gets a character
97code that normally refers to an entry in that table. For proper paragraph
98building and math rendering the following fields can be present in an entry in
99the \type {characters} table. You can of course add all kind of extra fields. The
100engine only uses those that it needs for typesetting a paragraph or formula. The
101subtables that define ligatures and kerns are also hashes with integer keys, and
102these indices should point to entries in the main characters table.
103
104Providing ligatures and kerns this way permits \TEX\ to construct ligatures and
105add inter|-|character kerning. However, normally you will use an \OPENTYPE\ font
106in combination with \LUA\ code that does this. In \CONTEXT\ we have base mode
107that uses the engine, and node mode that uses \LUA. A monospaced font normally
108has no ligatures and kerns and is normally not processed at all.
109
110We can group the parameters. All characters have the following base set. It must
111be noted here that \OPENTYPE\ doesn't have a italic property and that the height
112and depth are also not part of the design: one can choose to derive them from the
113bounding box.
114
115\starttabulate[|l|l|pl|]
116\DB key                     \BC type    \BC description \NC\NR
117\TB
118\NC \type {width}           \NC number  \NC width in sp (default 0) \NC\NR
119\NC \type {height}          \NC number  \NC height in sp (default 0) \NC\NR
120\NC \type {depth}           \NC number  \NC depth in sp (default 0) \NC\NR
121\NC \type {italic}          \NC number  \NC italic correction in sp (default 0) \NC\NR
122\stoptabulate
123
124Then there are three parameters that are more optional and relate to advanced
125optical paragraph optimization:
126
127\starttabulate[|l|l|pl|]
128\DB key                     \BC type    \BC description \NC\NR
129\TB
130\NC \type {leftprotruding}  \NC number  \NC left protruding factor (\prm {lpcode}) \NC\NR
131\NC \type {rightprotruding} \NC number  \NC right protruding factor (\prm {rpcode}) \NC\NR
132\NC \type {expansion}       \NC number  \NC expansion factor (\prm {efcode}) \NC\NR
133\NC \type {compression}     \NC number  \NC compression factor (\prm {cfcode}) \NC\NR
134\stoptabulate
135
136The \prm {lpcode}, \prm {rpcode} and \prm {efcode} are comparable to the ones
137introduced by \PDFTEX, while \prm {cfcode} complements \prm {efcode}: a
138compression alongside expansion code per character. In \LUAMETATEX\ the expansion
139mechanism is also available in math.
140
141From \TEX\ we inherit the following tables. Ligatures are only used in so call
142base mode, when the engine does the font magic. Kerns are used in text and
143optionally in math: More details follow below.
144
145\starttabulate[|l|l|pl|]
146\DB key                     \BC type    \BC description \NC\NR
147\TB
148\NC \type {ligatures}       \NC table   \NC ligaturing information \NC\NR
149\NC \type {kerns}           \NC table   \NC kerning information \NC\NR
150\stoptabulate
151
152The next two fields control the engine and are a variant on \TEX's \TFM\ tag
153property. In a future we might provide a bit more (local) control although
154currently we see no need. Originally the tag and next field were combined into a
155packed integer but in current \LUAMETATEX\ we have a 32 bit tag and the next
156field moved to the math blob as it only is used as variant selector.
157
158\starttabulate[|l|l|pl|]
159\DB key                     \BC type    \BC description \NC\NR
160\TB
161\NC \type {tag}             \NC number  \NC a bitset, currently not really exposed \NC\NR
162%NC \type {reserved}        \NC number  \NC note for myself \NC \NR
163\stoptabulate
164
165In a math font characters have many more fields.
166
167\starttabulate[|l|l|pl|]
168\DB key                      \BC type    \BC description \NC\NR
169\TB
170\NC \type {smaller}          \NC number  \NC the next smaller math size character \NC\NR
171\NC \type {mirror}           \NC number  \NC a right to left alternative \NC\NR
172\NC \type {flataccent}       \NC number  \NC an accent alternative with less height (\OPENTYPE) \NC\NR
173\NC \type {next}             \NC number  \NC \quote {next larger} character index \NC\NR
174\HL
175\NC \type {topleft}          \NC number  \NC alternative script kern \NC\NR
176\NC \type {topright}         \NC number  \NC alternative script kern \NC\NR
177\NC \type {bottomleft}       \NC number  \NC alternative script kern \NC\NR
178\NC \type {bottomright}      \NC number  \NC alternative script kern \NC\NR
179\HL
180\NC \type {topmargin}        \NC number  \NC alternative accent calculation margin \NC\NR
181\NC \type {bottomargin}      \NC number  \NC alternative accent calculation margin \NC\NR
182\NC \type {leftmargin}       \NC number  \NC alternative accent calculation margin \NC\NR
183\NC \type {rightmargin}      \NC number  \NC alternative accent calculation margin \NC\NR
184\HL
185\NC \type {topovershoot}     \NC number  \NC accent width tolerance \NC\NR
186\NC \type {bottomovershoot}  \NC number  \NC accent width tolerance \NC\NR
187\HL
188\NC \type {topanchor}        \NC number  \NC horizontal top accent alignment position \NC\NR
189\NC \type {bottomanchor}     \NC number  \NC horizontal bottom accent alignment position \NC\NR
190\HL
191\NC \type {innerlocation}    \NC string  \NC \type {left} or \type {right}  \NC\NR
192\NC \type {innerxoffset}     \NC number  \NC radical degree horizontal position \NC\NR
193\NC \type {inneryoffset}     \NC number  \NC radical degree vertical position \NC\NR
194\HL
195\NC \type {parts}            \NC table   \NC constituent parts of an extensible \NC \NR
196\NC \type {partsitalic}      \NC number  \NC the italic correction applied with the extensible \NC \NR
197\NC \type {partsorientation} \NC number  \NC \type {horizontal} or \type {vertical} \NC\NR
198\HL
199\NC \type {mathkerns}        \NC table   \NC math cut-in specifications \NC\NR
200\HL
201\NC \type {extensible}       \NC table   \NC stretch a fixed width accent to fit\NC\NR
202\LL
203\stoptabulate
204
205Now some more details follow. For example, here is the character \quote {f}
206(decimal 102) in the font \type {cmr10 at 10pt}. The numbers that represent
207dimensions are in scaled points. Of course you will use Latin Modern \OPENTYPE\
208instead but the principles are the same:
209
210\starttyping
211[102] = {
212    ["width"]  = 200250,
213    ["height"] = 455111,
214    ["depth"]  = 0,
215    ["italic"] = 50973,
216    ["kerns"]  = {
217        [63] = 50973,
218        [93] = 50973,
219        [39] = 50973,
220        [33] = 50973,
221        [41] = 50973
222    },
223    ["ligatures"] = {
224        [102] = { ["char"] = 11, ["type"] = 0 },
225        [108] = { ["char"] = 13, ["type"] = 0 },
226        [105] = { ["char"] = 12, ["type"] = 0 }
227    }
228}
229\stoptyping
230
231Two very special string indexes can be used also: \type {leftboundary} is a
232virtual character whose ligatures and kerns are used to handle word boundary
233processing. \type {rightboundary} is similar but not actually used for anything
234(yet).
235
236The values of \type {leftprotrusion} and \type {rightprotrusion} are used only
237when \prm {protrudechars} is non-zero. Whether or not \type {expansion} is used
238depends on the font's global expansion settings, as well as on the value of \prm
239{adjustspacing}.
240
241The values of \type {topanchor}, \type {bottomanchor} and \type {mathkern} are
242used only for math accent and superscript placement, see \at {page} [math] in
243this manual for details. The italic corrections are a story in themselves and
244discussed in detail in other manuals. The additional parameters that deal with
245kerns, margins, overshoots, inner anchoring, etc. are engine specific and not
246part of \OPENTYPE. More information can be found in the \CONTEXT\ distribution;
247they relate the upgraded math engine project by Mikael and Hans.
248
249A math character can have a \type {next} field that points to a next larger
250shape. However, the presence of \type {extensible} will overrule \type {next}, if
251that is also present. The \type {extensible} field in turn can be overruled by
252\type {parts}, the \OPENTYPE\ version. The \type {extensible} table is very
253simple:
254
255\starttabulate[|l|l|p|]
256\DB key        \BC type   \BC description                \NC\NR
257\TB
258\NC \type{top} \NC number \NC top character index        \NC\NR
259\NC \type{mid} \NC number \NC middle character index     \NC\NR
260\NC \type{bot} \NC number \NC bottom character index     \NC\NR
261\NC \type{rep} \NC number \NC repeatable character index \NC\NR
262\LL
263\stoptabulate
264
265The \type {parts} entru is an arrays of components. Each of those components is
266itself a hash of up to five keys:
267
268\starttabulate[|l|l|p|]
269\DB key             \BC type   \BC explanation \NC \NR
270\TB
271\NC \type{glyph}    \NC number \NC The character index. Note that this is an encoding number, not a name. \NC \NR
272\NC \type{extender} \NC number \NC One (1) if this part is repeatable, zero (0) otherwise. \NC \NR
273\NC \type{start}    \NC number \NC The maximum overlap at the starting side (in scaled points). \NC \NR
274\NC \type{end}      \NC number \NC The maximum overlap at the ending side (in scaled points). \NC \NR
275\NC \type{advance}  \NC number \NC The total advance width of this item. It can be zero or missing,
276                                   then the natural size of the glyph for character \type {component}
277                                   is used. \NC \NR
278\LL
279\stoptabulate
280
281The traditional (text and math) \type {kerns} table is a hash indexed by
282character index (and \quote {character index} is defined as either a
283non|-|negative integer or the string value \type {rightboundary}), with the
284values of the kerning to be applied, in scaled points.
285
286The traditional (text) \type {ligatures} table is a hash indexed by character
287index (and \quote {character index} is defined as either a non|-|negative integer
288or the string value \type {rightboundary}), with the values being yet another
289small hash, with two fields:
290
291\starttabulate[|l|l|p|]
292\DB key         \BC type   \BC description \NC \NR
293\TB
294\NC \type{type} \NC number \NC the type of this ligature command, default 0 \NC \NR
295\NC \type{char} \NC number \NC the character index of the resultant ligature \NC \NR
296\LL
297\stoptabulate
298
299The \type {char} field in a ligature is required. The \type {type} field inside a
300ligature is the numerical or string value of one of the eight possible ligature
301types supported by \TEX. When \TEX\ inserts a new ligature, it puts the new glyph
302in the middle of the left and right glyphs. The original left and right glyphs
303can optionally be retained, and when at least one of them is kept, it is also
304possible to move the new \quote {insertion point} forward one or two places. The
305glyph that ends up to the right of the insertion point will become the next
306\quote {left}.
307
308\starttabulate[|l|c|l|l|]
309\DB textual (Knuth)       \BC number \BC string        \BC result      \NC\NR
310\TB
311\NC \type{l + r =: n}     \NC 0      \NC \type{=:}     \NC \type{|n}   \NC\NR
312\NC \type{l + r =:| n}    \NC 1      \NC \type{=:|}    \NC \type{|nr}  \NC\NR
313\NC \type{l + r |=: n}    \NC 2      \NC \type{|=:}    \NC \type{|ln}  \NC\NR
314\NC \type{l + r |=:| n}   \NC 3      \NC \type{|=:|}   \NC \type{|lnr} \NC\NR
315\NC \type{l + r  =:|> n}  \NC 5      \NC \type{=:|>}   \NC \type{n|r}  \NC\NR
316\NC \type{l + r |=:> n}   \NC 6      \NC \type{|=:>}   \NC \type{l|n}  \NC\NR
317\NC \type{l + r |=:|> n}  \NC 7      \NC \type{|=:|>}  \NC \type{l|nr} \NC\NR
318\NC \type{l + r |=:|>> n} \NC 11     \NC \type{|=:|>>} \NC \type{ln|r} \NC\NR
319\LL
320\stoptabulate
321
322The default value is~0, and can be left out. That signifies a \quote {normal}
323ligature where the ligature replaces both original glyphs. In this table the~\type {|}
324indicates the final insertion point.
325
326% The \type {mathcontrol} bitset is mostly there for experimental purposes. Because
327% there is inconsistency in the \OPENTYPE\ math fonts with respect to for instance
328% glyph dimensions, it is possible to force the traditional code path. We just mention
329% the possible flags:
330%
331% \startluacode
332%     context.starttabulate { "|||" }
333%     context.DB() context("value") context.BC() context("effect") context.NC() context.NR()
334%     context.TB()
335%     for k, v in table.sortedhash(tex.getmathcontrolvalues()) do
336%         context.NC() context("0x%04X",k) context.NC() context(v) context.NC() context.NR()
337%     end
338%     context.LL()
339%     context.stoptabulate()
340% \stopluacode
341
342Compact math is an experimental feature. The smaller field in a character
343definition of a text character can point to a script character that itself can
344point to a scriptscript one. When set the \type {textscale}, \type {scriptscale}
345and \type {scriptscriptscale} is applied to those.
346
347Bidirectional math is also experimental and driven by (in \CONTEXT\ speak) tweaks
348which means that it has to be set up explicitly as it uses a combination of
349fonts. In \CONTEXT\ is also uses specific features of the font subsystems that
350hook into the backend where we have a more advanced virtual font subsystem than
351in \LUATEX. Because this is macro package dependent it will not be discussed
352here.
353
354% The \type {textcontrol} field is used to control some aspects of text processing.
355% More options might be added in the future.
356
357% \startluacode
358%     context.starttabulate { "|||" }
359%     context.DB() context("value") context.BC() context("effect") context.NC() context.NR()
360%     context.TB()
361%     for k, v in table.sortedhash(tex.gettextcontrolvalues()) do
362%         context.NC() context("0x%04X",k) context.NC() context(v) context.NC() context.NR()
363%     end
364%     context.LL()
365%     context.stoptabulate()
366% \stopluacode
367%
368% In \CONTEXT\ these are interfaced via pseudo features. The math control flags of
369% a font can be overloaded by \prm {mathcontrolmode} on the spot and the set
370% controls of a font can be queried by \prm {fontmathcontrol}. The text control
371% flags in a font always win over the ones set by other parameters, like \prm
372% {hyphenationmode}. They can be queried with \prm {fonttextcontrol}.
373
374\stopsection
375
376\startsection[reference=virtualfonts,title={Virtual fonts}]
377
378% \topicindex {fonts+virtual}
379
380Virtual fonts have been introduced to overcome limitations of good old \TEX. They
381were mostly used for providing a direct mapping from for instance accented
382characters onto a glyph. The backend was responsible for turning a reference to a
383character slot into a real glyph, possibly constructed from other glyphs. In our
384case there is no backend so there is also no need to pass this information
385through \TEX. But it can of course be part of the font information and because it is
386a kind of standard, we describe it here.
387
388A character is virtual when it has a \type {commands} array as part of the data.
389A virtual character can itself point to virtual characters but be careful with
390nesting as you can create loops and overflow the stack (which often indicates an
391error anyway).
392
393At the font level there can be a an (indexed) \type {fonts} table. The values are
394one- or two|-|key hashes themselves, each entry indicating one of the base fonts
395in a virtual font. In case your font is referring to itself in for instance a
396virtual font, you can use the \type {slot} command with a zero font reference,
397which indicates that the font itself is used. So, a table looks like this:
398
399\starttyping
400fonts = {
401  { name = "ptmr8a", size = 655360 },
402  { name = "psyr", size = 600000 },
403  { id = 38 }
404}
405\stoptyping
406
407The first referenced font (at index~1) in this virtual font is \type {ptrmr8a}
408loaded at 10pt, and the second is \type {psyr} loaded at a little over 9pt. The
409third one is a previously defined font that is known to \LUATEX\ as font id~38.
410The array index numbers are used by the character command definitions that are
411part of each character.
412
413The \type {commands} array is a hash where each item is another small array, with
414the first entry representing a command and the extra items being the parameters
415to that command. The frontend is only interested in the dimensions, ligatures and
416kerns of a font, which is the reason why the \TEX\ engine didn't have to be
417extended when virtual fonts showed up: dealing with it is up to the driver that
418comes after the backend. In \PDFTEX\ and \LUATEX\ that driver is integrated so
419there the backend also deals with virtual fonts. The first block in the next
420table is what the standard mentions. The \type {special} command is indeed
421special because it is an extension container. The mentioned engines only support
422pseudo standards where the content starts with \type {pdf:}. The last block is
423\LUATEX\ specific and will not be found in native fonts. These entries can be
424used in virtual fonts that are constructed in \LUA.
425
426But \unknown\ in \LUAMETATEX\ there is no backend built in but we might assume
427that the one provided deals with these entries. However, a provided backend can
428provide more and that is indeed what happens in \CONTEXT. There, because we no
429longer have compacting (of passed tables) and unpacking (when embedding) of these
430tables going on we stay in the \LUA\ domain. None of the virtual specification is
431ever seen in the engine.
432
433\starttabulate[|l|l|l|p|]
434\DB command        \BC arguments \BC type      \BC description \NC \NR
435\TB
436\NC \type{font}    \NC 1         \NC number    \NC select a new font from the local \type {fonts} table \NC \NR
437\NC \type{char}    \NC 1         \NC number    \NC typeset this character number from the current font,
438                                                   and move right by the character's width \NC \NR
439\NC \type{push}    \NC 0         \NC           \NC save current position\NC \NR
440\NC \type{pop}     \NC 0         \NC           \NC pop position \NC \NR
441\NC \type{rule}    \NC 2         \NC 2 numbers \NC output a rule $ht*wd$, and move right. \NC \NR
442\NC \type{down}    \NC 1         \NC number    \NC move down on the page \NC \NR
443\NC \type{right}   \NC 1         \NC number    \NC move right on the page \NC \NR
444\HL
445\NC \type{special} \NC 1         \NC string    \NC output a driver directive \NC \NR
446\HL
447\NC \type{nop}     \NC 0         \NC           \NC do nothing \NC \NR
448\NC \type{slot}    \NC 2         \NC 2 numbers \NC a shortcut for the combination of a font and char command\NC \NR
449\NC \type{node}    \NC 1         \NC node      \NC output this node (list), and move right
450                                                   by the width of this list\NC \NR
451\NC \type{pdf}     \NC 2         \NC 2 strings \NC output a \PDF\ literal, the first string is one of \type {origin},
452                                                   \type {page}, \type {text}, \type {font}, \type {direct} or \type {raw}; if you
453                                                   have one string only \type {origin} is assumed \NC \NR
454\NC \type{lua}     \NC 1         \NC string,
455                                     function  \NC execute a \LUA\ script when the glyph is embedded; in case of a
456                                                   function it gets the font id and character code passed \NC \NR
457\NC \type{image}   \NC 1         \NC image     \NC depends on the backend \NC \NR
458\NC \type{comment} \NC any       \NC any       \NC the arguments of this command are ignored \NC \NR
459\LL
460\stoptabulate
461
462When a font id is set to~0 then it will be replaced by the currently assigned
463font id. This prevents the need for hackery with future id's.
464
465The \type {pdf} option also accepts a \type {mode} keyword in which case the
466third argument sets the mode. That option will change the mode in an efficient
467way (passing an empty string would result in an extra empty lines in the \PDF\
468file. This option only makes sense for virtual fonts. The \type {font} mode only
469makes sense in virtual fonts. Modes are somewhat fuzzy and partially inherited
470from \PDFTEX.
471
472\starttabulate[|l|p|]
473\DB mode           \BC description \NC \NR
474\TB
475\NC \type {origin} \NC enter page mode and set the position \NC \NR
476\NC \type {page}   \NC enter page mode \NC \NR
477\NC \type {text}   \NC enter text mode \NC \NR
478\NC \type {font}   \NC enter font mode (kind of text mode, only in virtual fonts) \NC \NR
479\NC \type {always} \NC finish the current string and force a transform if needed \NC \NR
480\NC \type {raw}    \NC finish the current string \NC \NR
481\LL
482\stoptabulate
483
484You always need to check what \PDF\ code is generated because there can be all
485kind of interferences with optimization in the backend and fonts are complicated
486anyway. Here is a rather elaborate glyph commands example using such keys:
487
488\starttyping
489...
490commands = {
491    { "push" },                     -- remember where we are
492    { "right", 5000 },              -- move right about 0.08pt
493    { "font", 3 },                  -- select the fonts[3] entry
494    { "char", 97 },                 -- place character 97 (ASCII 'a')
495 -- { "slot", 2, 97 },              -- an alternative for the previous two
496    { "pop" },                      -- go all the way back
497    { "down", -200000 },            -- move upwards by about 3pt
498    { "special", "pdf: 1 0 0 rg" }  -- switch to red color
499 -- { "pdf", "origin", "1 0 0 rg" } -- switch to red color (alternative)
500    { "rule", 500000, 20000 }       -- draw a bar
501    { "special", "pdf: 0 g" }       -- back to black
502 -- { "pdf", "origin", "0 g" }      -- back to black (alternative)
503}
504...
505\stoptyping
506
507The default value for \type {font} is always~1 at the start of the
508\type {commands} array. Therefore, if the virtual font is essentially only a
509re|-|encoding, then you do usually not have created an explicit \quote {font}
510command in the array.
511
512Rules inside of \type {commands} arrays are built up using only two dimensions:
513they do not have depth. For correct vertical placement, an extra \type {down}
514command may be needed.
515
516Regardless of the amount of movement you create within the \type {commands}, the
517output pointer will always move by exactly the width that was given in the \type
518{width} key of the character hash. Any movements that take place inside the \type
519{commands} array are ignored on the upper level.
520
521The special can have a \type {pdf:}, \type {pdf:origin:},  \type {pdf:page:},
522\type {pdf:direct:} or  \type {pdf:raw:} prefix. When you have to concatenate
523strings using the \type {pdf} command might be more efficient.
524
525{\em For the record: in \CONTEXT\ \LMTX\ we no longer support the \type {pdf}, \type
526{image} and \type {special} keywords.}
527
528\stopsection
529
530\startsection[title={Additional \TEX\ commands}]
531
532\startsubsection[title={Font syntax}]
533
534\topicindex {fonts}
535
536\LUATEX\ will accept a braced argument as a font name:
537
538\starttyping
539\font\myfont = {cmr10}
540\stoptyping
541
542This allows for embedded spaces, without the need for double quotes. Macro
543expansion takes place inside the argument.
544
545\stopsubsection
546
547\startsubsection[title={\prm {fontid}, \prm {setfontid} and \prm {mathstylefontid}}]
548
549\startsyntax
550\fontid\font
551\stopsyntax
552
553This primitive expands into a number. The currently used font id is
554\number\fontid\font. Here are some more: \footnote {Contrary to \LUATEX\ this is
555now a number so you need to use \prm {number} or \prm {the}. The same is true
556for some other numbers and dimensions that for some reason ended up in the
557serializer that produced a sequence of tokens.}
558
559\starttabulate[|l|c|c|]
560\DB style \BC command \BC font id \NC \NR
561\TB
562\NC normal      \NC \type {\tf} \NC \tf \number\fontid\font \NC \NR
563\NC bold        \NC \type {\bf} \NC \bf \number\fontid\font \NC \NR
564\NC italic      \NC \type {\it} \NC \it \number\fontid\font \NC \NR
565\NC bold italic \NC \type {\bi} \NC \bi \number\fontid\font \NC \NR
566\LL
567\stoptabulate
568
569These numbers depend on the macro package used because each one has its own way
570of dealing with fonts. They can also differ per run, as they can depend on the
571order of loading fonts. For instance, when in \CONTEXT\ virtual math \UNICODE\
572fonts are used, we can easily get over a hundred ids in use. Not all ids have to
573be bound to a real font, after all it's just a number.
574
575The primitive \prm {setfontid} can be used to enable a font with the given id,
576which of course needs to be a valid one.
577
578In math mode the font id depends on the style because there we have a family of
579three related fonts. In this document we get the following identifiers:
580
581\starttabulate[|l|c|]
582\NC \type {$ \the \mathstylefontid \scriptscriptstyle \fam$} \NC $\the\mathstylefontid\scriptscriptstyle \fam$ \NC \NR
583\NC \type {$ \the \mathstylefontid \scriptstyle       \fam$} \NC $\the\mathstylefontid\scriptstyle       \fam$ \NC \NR
584\NC \type {$ \the \mathstylefontid \textstyle         \fam$} \NC $\the\mathstylefontid\textstyle         \fam$ \NC \NR
585\stoptabulate
586
587\stopsubsection
588
589\startsubsection[title={\prm {fontspecifiedname} and \prm {fontspecifiedsize}}]
590
591These two primitives provide some details about the given font:
592
593\startbuffer
594{\tf [\fontspecifiedname\font] [\the\fontspecifiedsize\font]}
595{\bf [\fontspecifiedname\font] [\the\fontspecifiedsize\font]}
596{\it [\fontspecifiedname\font] [\the\fontspecifiedsize\font]}
597\stopbuffer
598
599\typebuffer
600
601So for this document we get:
602
603\startlines
604\getbuffer
605\stoplines
606
607Of course this also depends on the macro package because that is responsible for
608implementing font support and because all that is driven by callbacks the
609reported name doesn't even have to resemble a font.
610
611\stopsubsection
612
613\startsubsection[title={\prm {glyphoptions}}]
614
615\topicindex {ligatures+suppress}
616\topicindex {kerns+suppress}
617\topicindex {expansion+suppress}
618\topicindex {protrusion+suppress}
619
620In \LUATEX\ the \type {\noligs} and \type {\nokerns} primitives suppress these
621features but in \LUAMETATEX\ these primitives are gone. They are replace by a more
622generic control primitive \prm {glyphoptions}. This numerical parameter is a
623bitset with the following fields:
624
625% todo: use values
626
627\starttabulate[|l|pl|]
628\DB value       \BC effect \NC\NR
629\TB
630\NC \type{0x01} \NC prevent left ligature             \NC \NR
631\NC \type{0x02} \NC prevent right ligature            \NC \NR
632\NC \type{0x04} \NC block left kern                   \NC \NR
633\NC \type{0x08} \NC block right kern                  \NC \NR
634\NC \type{0x10} \NC don't apply  expansion            \NC \NR
635\NC \type{0x20} \NC don't apply protrusion            \NC \NR
636\NC \type{0x40} \NC apply xoffset to width            \NC \NR
637\NC \type{0x80} \NC apply yoffset to height and depth \NC \NR
638\LL
639\stoptabulate
640
641The effects speak for themselves. They provide detailed control over individual
642glyph, this because the current value of this option is stored with glyphs.
643
644\stopsubsection
645
646\startsubsection[title={\prm {glyphscale}, \prm {glyphxscale}, \prm {glyphyscale} and \prm {scaledfontdimen}}]
647
648The three scale parameters control the current scaling. They are traditional
649\TEX\ integer parameters that operate independent of each other. The scaling is
650reflected in the dimensions of glyphs as well as in the related font dimensions,
651which means that units like \type {ex} and \type {em} work as expected. If you
652query a font dimensions with \prm {fontdimen} you get the raw value but with \prm
653{scaledfontdimen} you get the useable value.
654
655\stopsubsection
656
657\startsubsection[title={\prm {glyphxscaled}, \prm {glyphyscaled}}]
658
659These two relate to the previous one:
660
661\startbuffer
662{\glyphxscale 1500 \the\glyphxscaled 100pt} and
663{\glyphyscale  750 \the\glyphyscaled 100pt}
664\stopbuffer
665
666\typebuffer
667
668We get: \inlinebuffer.
669
670\stopsubsection
671
672\startsubsection[title={Scaled fontdimensions}]
673
674When you use \prm {glyphscale},  \prm {glyphxscale} and|/|or  \prm {glyphyscale} the font
675dimensions
676
677\starttabulate[|l|c|c|c|]
678\DB dimension                     \BC scale \NC xscale \NC yscale \NC\NR
679\TB
680\NC \prm {scaledemwidth}          \NC \star \NC \star  \NC        \NC\NR
681\NC \prm {scaledexheight}         \NC \star \NC        \NC \star  \NC\NR
682\NC \prm {scaledextraspace}       \NC \star \NC \star  \NC        \NC\NR
683\NC \prm {scaledinterwordshrink}  \NC \star \NC \star  \NC        \NC\NR
684\NC \prm {scaledinterwordspace}   \NC \star \NC \star  \NC        \NC\NR
685\NC \prm {scaledinterwordstretch} \NC \star \NC \star  \NC        \NC\NR
686\NC \prm {scaledslantperpoint}    \NC \star \NC \star  \NC        \NC\NR
687\LL
688\stoptabulate
689
690The next table shows the effective sized when we scale by 2000. The last two
691columns scale twice: the shared scale and the x or y scale.
692
693\def\ShowThem#1%
694  {\normalexpanded{
695   \BC \small \prm {\csstring\parametermark1}
696   \NC {\localcontrolled{\glyphscale2000 \glyphxscale1000 \glyphyscale 1000} \withoutpt\parametermark1}
697   \NC {\localcontrolled{\glyphscale1000 \glyphxscale2000 \glyphyscale 1000} \withoutpt\parametermark1}
698   \NC {\localcontrolled{\glyphscale1000 \glyphxscale1000 \glyphyscale 2000} \withoutpt\parametermark1}
699   \NC {\localcontrolled{\glyphscale2000 \glyphxscale2000 \glyphyscale 1000} \withoutpt\parametermark1}
700   \NC {\localcontrolled{\glyphscale2000 \glyphxscale1000 \glyphyscale 2000} \withoutpt\parametermark1}
701   \NC \NR}}
702
703\starttabulate[|l|c{.}|c{.}|c{.}|c{.}|c{.}|]
704    \ShowThem\scaledemwidth
705    \ShowThem\scaledexheight
706    \ShowThem\scaledextraspace
707    \ShowThem\scaledinterwordshrink
708    \ShowThem\scaledinterwordspace
709    \ShowThem\scaledinterwordstretch
710    \ShowThem\scaledslantperpoint
711\stoptabulate
712
713\startsubsection[title={\prm {fontspecdef}, \prm {fontspecid}, \prm {fontspecscale}, , \prm {fontspecxscale}, \prm {fontspecyscale}}]
714
715Because we have three scale related primitives \prm {glyphscale}, \prm
716{glyphxscale} and \prm {glyphyscale}, we also have a way to quickly set them all.
717
718\starttyping
719\fontspecdef \MyFontA 2 all 1000
720\fontspecdef \MyFontB \MyFontA xscale 1200
721\stoptyping
722
723The defined control sequence will set the font id (which is 2 in the case of
724\type {\MyFontA}) as well as the scale(s). Possible keywords are \type {scale},
725\type {xscale}, \type {yscale} and \type {all}. By default the values are 1000.
726Instead of an id an already defined specification can be given in which case we
727start from a copy. This mechanism is still somewhat experimental and might
728evolve. The main reason for introducing it is that it gives less tracing.
729
730Say that we have:
731
732\startbuffer
733\fontspecdef\MyFoo\font xscale 1200 \relax
734\stopbuffer
735
736\typebuffer \getbuffer
737
738The four properties of such a specification can then be queried as follows:
739
740\startbuffer
741[\the\fontspecid    \MyFoo]
742[\the\fontspecscale \MyFoo]
743[\the\fontspecxscale\MyFoo]
744[\the\fontspecyscale\MyFoo]
745\stopbuffer
746
747\typebuffer \getbuffer
748
749A font specification obeys grouping but is not a register. Like \prm {integerdef}
750and \prm {dimendef} it is just a control sequence with a special meaning.
751
752% \the\fontspecifiedsize\font
753%     \fontspecifiedname\font
754
755\stopsubsection
756
757\startsubsection[title={\prm {glyphxoffset}, \prm {glyphyoffset}}]
758
759These two parameters control the horizontal and vertical shift of glyphs with,
760when applied to a stretch of them, the horizontal offset probably being the least
761useful.
762
763\stopsubsection
764
765\startsubsection[title={\prm {glyph}}]
766
767This command is a variation in \prm {char} that takes keywords:
768
769\starttabulate[|l|p|]
770\DB keyword \BC effect \NC type \NC \NR
771\TB
772\NC \type {xoffset} \NC (virtual) horizontal shift \NC dimension  \NC \NR
773\NC \type {yoffset} \NC (virtual) vertical shift   \NC dimension  \NC \NR
774\NC \type {xscale}  \NC horizontal scaling         \NC integer    \NC \NR
775\NC \type {yscale}  \NC vertical scaling           \NC integer    \NC \NR
776\NC \type {options} \NC glyph options              \NC bitset     \NC \NR
777\NC \type {font}    \NC font                       \NC identifier \NC \NR
778\NC \type {id}      \NC font                       \NC integer    \NC \NR
779\LL
780\stoptabulate
781
782The values default to the currently set values. Here is a \CONTEXT\ example:
783
784\startbuffer
785\ruledhbox{
786    \ruledhbox{\glyph yoffset 1ex options 0 123}
787    \ruledhbox{\glyph xoffset .5em yoffset 1ex options "C0 125}
788    \ruledhbox{baseline\glyphyoffset 1ex \glyphxscale 800 \glyphyscale\glyphxscale raised}
789}
790\stopbuffer
791
792\typebuffer
793
794Visualized:
795
796\getbuffer
797
798\stopsubsection
799
800\startsubsection[title={\prm{nospaces}}]
801
802\topicindex {spaces+suppress}
803
804This new primitive can be used to overrule the usual \prm {spaceskip} related
805heuristics when a space character is seen in a text flow. The value~\type{1}
806triggers no injection while \type{2} results in injection of a zero skip. In \in
807{figure} [fig:nospaces] we see the results for four characters separated by a
808space.
809
810\startplacefigure[reference=fig:nospaces,title={The \prm {nospaces} options.}]
811\startcombination[3*2]
812    {\ruledhbox to 5cm{\vtop{\hsize 10mm\nospaces=0\relax x x x x \par}\hss}} {\type {0 / hsize 10mm}}
813    {\ruledhbox to 5cm{\vtop{\hsize 10mm\nospaces=1\relax x x x x \par}\hss}} {\type {1 / hsize 10mm}}
814    {\ruledhbox to 5cm{\vtop{\hsize 10mm\nospaces=2\relax x x x x \par}\hss}} {\type {2 / hsize 10mm}}
815    {\ruledhbox to 5cm{\vtop{\hsize  1mm\nospaces=0\relax x x x x \par}\hss}} {\type {0 / hsize 1mm}}
816    {\ruledhbox to 5cm{\vtop{\hsize  1mm\nospaces=1\relax x x x x \par}\hss}} {\type {1 / hsize 1mm}}
817    {\ruledhbox to 5cm{\vtop{\hsize  1mm\nospaces=2\relax x x x x \par}\hss}} {\type {2 / hsize 1mm}}
818\stopcombination
819\stopplacefigure
820
821\stopsubsection
822
823\startsubsection[title={\prm{protrusionboundary}}]
824
825\topicindex {protrusion}
826\topicindex {boundaries}
827
828The protrusion detection mechanism is enhanced a bit to enable a bit more complex
829situations. When protrusion characters are identified some nodes are skipped:
830
831\startitemize[packed,columns,two]
832\startitem zero glue \stopitem
833\startitem penalties \stopitem
834\startitem empty discretionaries \stopitem
835\startitem normal zero kerns \stopitem
836\startitem rules with zero dimensions \stopitem
837\startitem math nodes with a surround of zero \stopitem
838\startitem dir nodes \stopitem
839\startitem empty horizontal lists \stopitem
840\startitem local par nodes \stopitem
841\startitem inserts, marks and adjusts \stopitem
842\startitem boundaries \stopitem
843\startitem whatsits \stopitem
844\stopitemize
845
846Because this can not be enough, you can also use a protrusion boundary node to
847make the next node being ignored. When the value is~1 or~3, the next node will be
848ignored in the test when locating a left boundary condition. When the value is~2
849or~3, the previous node will be ignored when locating a right boundary condition
850(the search goes from right to left). This permits protrusion combined with for
851instance content moved into the margin:
852
853\starttyping
854\protrusionboundary1\llap{!\quad}«Who needs protrusion?»
855\stoptyping
856
857\stopsubsection
858
859\startsubsection[title={\prm{fontcharta} and \prm{fontcharba}}]
860
861\topicindex {glyphs + properties}
862
863The \prm {fontcharwd}, \prm {fontcharht}, \prm {fontchardp} and \prm {fontcharic}
864give access to character properties. To this repertoire \LUAMETATEX\ adds the top
865and bottom accent accessors \prm {fontcharta} and \prm {fontcharba} that came in
866handy for tracing. You pass a font reference and character code. Normally only
867\OPENTYPE\ math fonts have this property.
868
869\stopsubsection
870
871\stopsection
872
873\startsection[title={The \LUA\ font library}][library=font]
874
875\startsubsection[title={Introduction}]
876
877The \LUA\ font library is reduced to a few commands. Contrary to \LUATEX\ there
878is no loading of \TFM\ or \VF\ files. The explanation of the following commands
879is in the \LUATEX\ manual.
880
881\starttabulate[|l|pl|]
882\DB function              \BC description \NC\NR
883\TB
884\NC \type {current}       \NC returns the id of the currently active font \NC \NR
885\NC \type {max}           \NC returns the last assigned font identifier \NC \NR
886\NC \type {setfont}       \NC enables a font setfont (sets the current font id) \NC \NR
887\NC \type {addcharacters} \NC adds characters to a font \NC \NR
888\NC \type {define}        \NC defined a font \NC \NR
889\NC \type {id}            \NC returns the id that relates to a command name \NC \NR
890\LL
891\stoptabulate
892
893For practical reasons the management of font identifiers is still done by \TEX\
894but it can become an experiment to delegate that to \LUA\ as well.
895
896\stopsubsection
897
898\startsubsection[title={Defining a font with \type {define}, \type {addcharacters} and \type
899{setfont}}]
900
901\topicindex {fonts+define}
902\topicindex {fonts+extend}
903
904Normally you will use a callback to define a font but there's also a \LUA\
905function that does the job.
906
907\startfunctioncall
908id = font.define(<table> f)
909\stopfunctioncall
910
911Within reasonable bounds you can extend a font after it has been defined. Because
912some properties are best left unchanged this is limited to adding characters.
913
914\startfunctioncall
915font.addcharacters(<number n>, <table> f)
916\stopfunctioncall
917
918The table passed can have the fields \type {characters} which is a (sub)table
919like the one used in define, and for virtual fonts a \type {fonts} table can be
920added. The characters defined in the \type {characters} table are added (when not
921yet present) or replace an existing entry. Keep in mind that replacing can have
922side effects because a character already can have been used. Instead of posing
923restrictions we expect the user to be careful. The \type {setfont} helper is
924a more drastic replacer and only works when a font has not been used yet.
925
926\stopsubsection
927
928\startsubsection[title={Font ids: \type {id}, \type {max} and \type {current}}]
929
930\topicindex {fonts+id}
931\topicindex {fonts+current}
932
933\startfunctioncall
934<number> i = font.id(<string> csname)
935\stopfunctioncall
936
937This returns the font id associated with \type {csname}, or $-1$ if \type
938{csname} is not defined.
939
940\startfunctioncall
941<number> i = font.max()
942\stopfunctioncall
943
944This is the largest used index so far. The currently active font id can be
945queried or set with:
946
947\startfunctioncall
948<number> i = font.current()
949font.current(<number> i)
950\stopfunctioncall
951
952\stopsubsection
953
954\startsubsection[title={Glyph data: \prm {glyphdatafield}, \prm {glyphscriptfield}, \prm {glyphstatefield}}]
955
956These primitives can be used to set an additional glyph properties. Of course
957it's very macro package dependant what is done with that. It started with just
958the first one as experiment, simply because we had some room left in the glyph
959data structure. It's basically an single attribute. Then, when we got rid of the
960ligature pointer we could either drop it or use that extra field for some more,
961and because \CONTEXT\ already used the data field, that is what happened. The
962script and state fields are shorts, that is, they run from zero to \type {0xFFFF}
963where we assume that zero means \quote {unset}. Although they can be used for
964whatever purpose their use in \CONTEXT\ is fixed.
965
966\stopsubsection
967
968\startsubsection[title={Scaling math fonts with \prm {glyphtextscale} etc}]
969
970More details about fonts in math mode can be found in the chapter about math so
971here we just mention a few primitives. The internal \prm {glyphtextscale}, \prm
972{glyphscriptscale} and \prm {glyphscriptscriptscale} registers can be set to
973enforce additional scaling of math, like this:
974
975\startbuffer
976$                            a = b^2 = c^{d^2}$
977$\glyphtextscale         800 a = b^2 = c^{d^2}$
978$\glyphscriptscale       800 a = b^2 = c^{d^2}$
979$\glyphscriptscriptscale 800 a = b^2 = c^{d^2}$
980\stopbuffer
981
982\typebuffer
983
984You can of course set them all in any mix as long as the value is larger than
985zero and doesn't exceed 1000. In \CONTEXT\ we use this for special purposes so
986don't mess with it there. as there can be side unexpected (but otherwise valid)
987side effects.
988
989\startlines
990\getbuffer
991\stoplines
992
993The next few reported values depend on the font setup. A math font can be loaded
994at a certain scale and further scaled on the fly. An open type math font comes with
995recommended script and scriptscript scales and gets passed to the engine scaled. The
996values reported by \prm {mathscale} are {\em additional} scales.
997
998\startbuffer
999$\the\mathscale\textfont        \zerocount$
1000$\the\mathscale\scriptfont      \zerocount$
1001$\the\mathscale\scriptscriptfont\zerocount$
1002\stopbuffer
1003
1004\typebuffer
1005
1006In \CONTEXT\ we use this for some experiments (of which some made it into
1007features) but discussing this fall behind this manual. You cannot set these
1008values because the engine has to work with consistent settings and messing around
1009with fonts during a run only works well if the backend also cooperates. Also the
1010values only makes sense in the perspective of the used macro package.
1011
1012\stopsubsection
1013
1014\startsubsection[title={Tracing}]
1015
1016The \prm {tracingfonts} primitive that has been inherited from \PDFTEX\ has
1017been adapted to support variants in reporting the font. The reason for this
1018extension is that a csname not always makes sense. The zero case is the default.
1019
1020\starttabulate[|l|l|]
1021\DB value \BC reported \NC \NR
1022\TB
1023\NC \type{0} \NC \type{\foo xyz} \NC \NR
1024\NC \type{1} \NC \type{\foo (bar)} \NC \NR
1025\NC \type{2} \NC \type{<bar> xyz} \NC \NR
1026\NC \type{3} \NC \type{<bar @ ..pt> xyz} \NC \NR
1027\NC \type{4} \NC \type{<id>} \NC \NR
1028\NC \type{5} \NC \type{<id: bar>} \NC \NR
1029\NC \type{6} \NC \type{<id: bar @ ..pt> xyz} \NC \NR
1030\LL
1031\stoptabulate
1032
1033\stopsubsection
1034
1035\stopsection
1036
1037\stopchapter
1038
1039\stopcomponent
1040
1041