| 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 |