manual/luatex-fonts.tex

   1 \environment luatex-style
   2 \environment luatex-logos
   3
   4 \startcomponent luatex-fonts
   5
   6 \startchapter[reference=fonts,title={Font structure}]
   7
   8 All \TEX\ fonts are represented to \LUA\ code as tables, and internally as
   9 \CCODE~structures. All keys in the table below are saved in the internal font
  10 structure if they are present in the table returned by the \type {define_font}
  11 callback, or if they result from the normal \TFM|/|\VF\ reading routines if there
  12 is no \type {define_font} callback defined.
  13
  14 The column \quote {from \VF} means that this key will be created by the \type
  15 {font.read_vf()} routine, \quote {from \TFM} means that the key will be created
  16 by the \type {font.read_tfm()} routine, and \quote{used} means whether or not
  17 the \LUATEX\ engine itself will do something with the key.
  18
  19 The top|-|level keys in the table are as follows:
  20
  21 \starttabulate[|Tl|l|l|l|l|p|]
  22 \NC \ssbf key  \NC \bf from vf \NC \bf from tfm \NC \bf used\NC \bf value type \NC
  23     \bf description
  24 \NC \NR
  25 \NC name               \NC yes      \NC yes      \NC yes \NC string \NC
  26     metric (file) name
  27 \NC \NR
  28 \NC area               \NC no       \NC yes      \NC yes \NC string \NC
  29     (directory) location, typically empty
  30 \NC \NR
  31 \NC used               \NC no       \NC yes      \NC yes \NC boolean\NC
  32     used already? (initial: false)
  33 \NC \NR
  34 \NC characters         \NC yes      \NC yes      \NC yes \NC table  \NC
  35     the defined glyphs of this font
  36 \NC \NR
  37 \NC checksum           \NC yes      \NC yes      \NC no  \NC number \NC
  38     default: 0
  39 \NC \NR
  40 \NC designsize         \NC no       \NC yes      \NC yes \NC number \NC
  41     expected size (default: 655360 == 10pt)
  42 \NC \NR
  43 \NC direction          \NC no       \NC yes      \NC yes \NC number \NC
  44     default: 0 (TLT)
  45 \NC \NR
  46 \NC encodingbytes      \NC no       \NC no       \NC yes \NC number \NC
  47     default: depends on \type {format}
  48 \NC \NR
  49 \NC encodingname       \NC no       \NC no       \NC yes \NC string \NC
  50     encoding name
  51 \NC \NR
  52 \NC fonts              \NC yes      \NC no       \NC yes \NC table  \NC
  53     locally used fonts
  54 \NC \NR
  55 \NC psname             \NC no       \NC no       \NC yes \NC string \NC
  56     actual (\POSTSCRIPT) name (this is the PS fontname in the incoming font
  57     source, also used as fontname identifier in the \PDF\ output, new in 0.43)
  58 \NC \NR
  59 \NC fullname           \NC no       \NC no       \NC yes \NC string \NC
  60     output font name, used as a fallback in the \PDF\ output
  61     if the psname is not set
  62 \NC \NR
  63 \NC header             \NC yes      \NC no       \NC no  \NC string \NC
  64     header comments, if any
  65 \NC \NR
  66 \NC hyphenchar         \NC no       \NC no       \NC yes \NC number \NC
  67     default: TeX's \type {\hyphenchar}
  68 \NC \NR
  69 \NC parameters         \NC no       \NC yes      \NC yes \NC hash   \NC
  70     default: 7 parameters, all zero
  71 \NC \NR
  72 \NC size               \NC no       \NC yes      \NC yes \NC number \NC
  73     loaded (at) size. (default: same as designsize)
  74 \NC \NR
  75 \NC skewchar           \NC no       \NC no       \NC yes \NC number \NC
  76     default: TeX's \type {\skewchar}
  77 \NC \NR
  78 \NC type               \NC yes      \NC no       \NC yes \NC string \NC
  79     basic type of this font
  80 \NC \NR
  81 \NC format             \NC no       \NC no       \NC yes \NC string \NC
  82     disk format type
  83 \NC \NR
  84 \NC embedding          \NC no       \NC no       \NC yes \NC string \NC
  85     \PDF\ inclusion
  86 \NC \NR
  87 \NC filename           \NC no       \NC no       \NC yes \NC string \NC
  88     disk file name
  89 \NC \NR
  90 \NC tounicode          \NC no       \NC yes      \NC yes \NC number \NC
  91     if 1, \LUATEX\ assumes per-glyph tounicode entries are
  92     present in the font
  93 \NC \NR
  94 \NC stretch            \NC no       \NC no       \NC yes \NC number \NC
  95     the \quote {stretch} value from \type {\expandglyphsinfont}
  96 \NC \NR
  97 \NC shrink             \NC no       \NC no       \NC yes \NC number \NC
  98     the \quote {shrink} value from \type {\expandglyphsinfont}
  99 \NC \NR
 100 \NC step               \NC no       \NC no       \NC yes \NC number \NC
 101     the \quote {step} value from \type {\expandglyphsinfont}
 102 \NC \NR
 103 \NC auto_expand        \NC no       \NC no       \NC yes \NC boolean\NC
 104     the \quote {autoexpand} keyword from\crlf \type {\expandglyphsinfont}
 105 \NC \NR
 106 \NC expansion_factor   \NC no       \NC no       \NC no  \NC number \NC
 107     the actual expansion factor of an expanded font
 108 \NC \NR
 109 \NC attributes         \NC no       \NC no       \NC yes \NC string \NC
 110     the \type {\pdffontattr}
 111 \NC \NR
 112 \NC cache              \NC no       \NC no       \NC yes \NC string \NC
 113     this key controls caching of the lua table on the \type {tex} end. \type {yes}:
 114     use a reference to the table that is passed to \LUATEX\ (this is the
 115     default). \type {no}: don't store the table reference, don't cache any lua
 116     data for this font. \type {renew}: don't store the table reference, but save a
 117     reference to the table that is created at the first access to one of its
 118     fields in font.fonts. (new in 0.40.0, before that caching was always
 119     \type {yes}). Note: the saved reference is thread-local, so be careful when
 120     you are using coroutines: an error will be thrown if the table has been
 121     cached in one thread, but you reference it from another thread ($\approx$
 122     coroutine)
 123 \NC \NR
 124 \NC nomath              \NC no       \NC no       \NC yes \NC boolean\NC
 125     this key allows a minor speedup for text fonts. if it is present and true,
 126     then \LUATEX\ will not check the character enties for math-specific keys.
 127 \NC \NR
 128 \NC slant               \NC no       \NC no       \NC yes \NC number \NC
 129     This has the same semantics as the \type {SlantFont} operator in font map
 130     files.
 131 \NC \NR
 132 \NC extent              \NC no       \NC no       \NC yes \NC number \NC
 133     This has the same semantics as the \type {ExtendFont} operator in font map
 134     files.
 135 \NC \NR
 136 \stoptabulate
 137
 138 The key \type {name} is always required. The keys \type {stretch}, \type
 139 {shrink}, \type {step} and optionally \type {auto_expand} only have meaning when
 140 used together: they can be used to replace a post|-|loading \type
 141 {\expandglyphsinfont} command. The \type {expansion_factor} is value that can be
 142 present inside a font in \type {font.fonts}. It is the actual expansion factor (a
 143 value between \type {-shrink} and \type {stretch}, with step \type {step}) of a
 144 font that was automatically generated by the font expansion algorithm. The key
 145 \type  {attributes} can be used to replace \type {\pdffontattr}. The key \type {used}
 146 is set by the engine when a font is actively in use, this makes sure that the
 147 font's definition is written to the output file (\DVI\ or \PDF). The \TFM\ reader
 148 sets it to false. The \type {direction} is a number signalling the \quote
 149 {normal} direction for this font. There are sixteen possibilities:
 150
 151 \starttabulate[|Tc|c|c|c|]
 152 \NC \ssbf number \NC \bf meaning \NC \bf number \NC \bf meaning \NC\NR
 153 \NC 0            \NC LT          \NC 8          \NC TT          \NC\NR
 154 \NC 1            \NC LL          \NC 9          \NC TL          \NC\NR
 155 \NC 2            \NC LB          \NC 10         \NC TB          \NC\NR
 156 \NC 3            \NC LR          \NC 11         \NC TR          \NC\NR
 157 \NC 4            \NC RT          \NC 12         \NC BT          \NC\NR
 158 \NC 5            \NC RL          \NC 13         \NC BL          \NC\NR
 159 \NC 6            \NC RB          \NC 14         \NC BB          \NC\NR
 160 \NC 7            \NC RR          \NC 15         \NC BR          \NC\NR
 161 \stoptabulate
 162
 163 These are \OMEGA|-|style direction abbreviations: the first character indicates
 164 the \quote {first} edge of the character glyphs (the edge that is seen first in
 165 the writing direction), the second the \quote {top} side.
 166
 167 The \type {parameters} is a hash with mixed key types. There are seven possible
 168 string keys, as well as a number of integer indices (these start from 8 up). The
 169 seven strings are actually used instead of the bottom seven indices, because that
 170 gives a nicer user interface.
 171
 172 The names and their internal remapping are:
 173
 174 \starttabulate[|lT|c|]
 175 \NC \ssbf name    \NC \bf internal remapped number \NC\NR
 176 \NC slant         \NC 1 \NC\NR
 177 \NC space         \NC 2 \NC\NR
 178 \NC space_stretch \NC 3 \NC\NR
 179 \NC space_shrink  \NC 4 \NC\NR
 180 \NC x_height      \NC 5 \NC\NR
 181 \NC quad          \NC 6 \NC\NR
 182 \NC extra_space   \NC 7 \NC\LR
 183 \stoptabulate
 184
 185 The keys \type {type}, \type {format}, \type {embedding}, \type {fullname} and
 186 \type {filename} are used to embed \OPENTYPE\ fonts in the result \PDF.
 187
 188 The \type {characters} table is a list of character hashes indexed by an integer
 189 number. The number is the \quote {internal code} \TEX\ knows this character by.
 190
 191 Two very special string indexes can be used also: \type {left_boundary} is a
 192 virtual character whose ligatures and kerns are used to handle word boundary
 193 processing. \type {right_boundary} is similar but not actually used for anything
 194 (yet!).
 195
 196 Other index keys are ignored.
 197
 198 Each character hash itself is a hash. For example, here is the character \quote
 199 {f} (decimal 102) in the font cmr10 at 10 points:
 200
 201 \starttyping
 202 [102] = {
 203     ['width'] = 200250,
 204     ['height'] = 455111,
 205     ['depth'] = 0,
 206     ['italic'] = 50973,
 207     ['kerns'] = {
 208         [63] = 50973,
 209         [93] = 50973,
 210         [39] = 50973,
 211         [33] = 50973,
 212         [41] = 50973
 213     },
 214     ['ligatures'] = {
 215         [102] = {
 216             ['char'] = 11,
 217             ['type'] = 0
 218         },
 219         [108] = {
 220             ['char'] = 13,
 221             ['type'] = 0
 222         },
 223         [105] = {
 224             ['char'] = 12,
 225             ['type'] = 0
 226         }
 227     }
 228 }
 229 \stoptyping
 230
 231 The following top|-|level keys can be present inside a character hash:
 232
 233 \starttabulate[|lT|c|c|c|l|p|]
 234 \NC \ssbf key        \NC \bf from vf \NC \bf from tfm \NC \bf used \NC \bf value type \NC \bf description \NC\NR
 235 \NC width            \NC yes         \NC yes          \NC yes      \NC number         \NC character's width, in sp (default 0) \NC\NR
 236 \NC height           \NC no          \NC yes          \NC yes      \NC number         \NC character's height, in sp (default 0) \NC\NR
 237 \NC depth            \NC no          \NC yes          \NC yes      \NC number         \NC character's depth, in sp (default 0) \NC\NR
 238 \NC italic           \NC no          \NC yes          \NC yes      \NC number         \NC character's italic correction, in sp (default zero) \NC\NR
 239 \NC top_accent       \NC no          \NC no           \NC maybe    \NC number         \NC character's top accent alignment place, in sp (default zero) \NC\NR
 240 \NC bot_accent       \NC no          \NC no           \NC maybe    \NC number         \NC character's bottom accent alignment place, in sp (default zero) \NC\NR
 241 \NC left_protruding  \NC no          \NC no           \NC maybe    \NC number         \NC character's \type {\lpcode} \NC\NR
 242 \NC right_protruding \NC no          \NC no           \NC maybe    \NC number         \NC character's \type {\rpcode} \NC\NR
 243 \NC expansion_factor \NC no          \NC no           \NC maybe    \NC number         \NC character's \type {\efcode} \NC\NR
 244 \NC tounicode        \NC no          \NC no           \NC maybe    \NC string         \NC character's Unicode equivalent(s), in UTF-16BE hexadecimal format\NC\NR
 245 \NC next             \NC no          \NC yes          \NC yes      \NC number         \NC the \quote{next larger} character index \NC\NR
 246 \NC extensible       \NC no          \NC yes          \NC yes      \NC table          \NC the constituent parts of an extensible recipe \NC\NR
 247 \NC vert_variants    \NC no          \NC no           \NC yes      \NC table          \NC constituent parts of a vertical variant set\NC \NR
 248 \NC horiz_variants   \NC no          \NC no           \NC yes      \NC table          \NC constituent parts of a horizontal variant set\NC \NR
 249 \NC kerns            \NC no          \NC yes          \NC yes      \NC table          \NC kerning information \NC\NR
 250 \NC ligatures        \NC no          \NC yes          \NC yes      \NC table          \NC ligaturing information \NC\NR
 251 \NC commands         \NC yes         \NC no           \NC yes      \NC array          \NC virtual font commands \NC\NR
 252 \NC name             \NC no          \NC no           \NC no       \NC string         \NC the character (\POSTSCRIPT) name \NC\NR
 253 \NC index            \NC no          \NC no           \NC yes      \NC number         \NC the (\OPENTYPE\ or \TRUETYPE) font glyph index \NC\NR
 254 \NC used             \NC no          \NC yes          \NC yes      \NC boolean        \NC typeset already (default: false)? \NC\NR
 255 \NC mathkern         \NC no          \NC no           \NC yes      \NC table          \NC math cut-in specifications \NC\NR
 256 \stoptabulate
 257
 258 The values of \type {top_accent}, \type {bot_accent} and \type {mathkern} are
 259 used only for math accent and superscript placement, see the \at {math chapter}
 260 [math] in this manual for details.
 261
 262 The values of \type {left_protruding} and \type {right_protruding} are used only
 263 when \type {\protrudechars} is non-zero.
 264
 265 Whether or not \type {expansion_factor} is used depends on the font's global
 266 expansion settings, as well as on the value of \type {\adjustspacing}.
 267
 268 The usage of \type {tounicode} is this: if this font specifies a \type
 269 {tounicode=1} at the top level, then \LUATEX\ will construct a \type {/ToUnicode}
 270 entry for the \PDF\ font (or font subset) based on the character|-|level \type
 271 {tounicode} strings, where they are available. If a character does not have a
 272 sensible \UNICODE\ equivalent, do not provide a string either (no empty strings).
 273
 274 If the font-level \type {tounicode} is not set, then \LUATEX\ will build up \type
 275 {/ToUnicode} based on the \TEX\ code points you used, and any character-level
 276 \type {tounicodes} will be ignored. {\it At the moment, the string format is
 277 exactly the format that is expected by Adobe \CMAP\ files (\UTF-16BE in
 278 hexadecimal encoding), minus the enclosing angle brackets. This may change in the
 279 future.} Small example: the \type {tounicode} for a \type {fi} ligature would be
 280 \type {00660069}.
 281
 282 The presence of \type {extensible} will overrule \type {next}, if that is also
 283 present. It in in turn can be overruled by \type {vert_variants}.
 284
 285 The \type {extensible} table is very simple:
 286
 287 \starttabulate[|lT|l|p|]
 288 \NC \ssbf key \NC \bf type \NC \bf description                    \NC\NR
 289 \NC top       \NC number   \NC \quote{top} character index        \NC\NR
 290 \NC mid       \NC number   \NC \quote{middle} character index     \NC\NR
 291 \NC bot       \NC number   \NC \quote{bottom} character index     \NC\NR
 292 \NC rep       \NC number   \NC \quote{repeatable} character index \NC\NR
 293 \stoptabulate
 294
 295 The \type {horiz_variants} and \type {vert_variants} are arrays of components.
 296 Each of those components is itself a hash of up to five keys:
 297
 298 \starttabulate[|lT|l|p|]
 299 \NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR
 300 \NC glyph     \NC number   \NC The character index (note that this is an encoding number, not a name). \NC \NR
 301 \NC extender  \NC number   \NC One (1) if this part is repeatable, zero (0) otherwise. \NC \NR
 302 \NC start     \NC number   \NC Maximum overlap at the starting side (in scaled points). \NC \NR
 303 \NC end       \NC number   \NC Maximum overlap at the ending side (in scaled points). \NC \NR
 304 \NC advance   \NC number   \NC Total advance width of this item (can be zero or missing,
 305                                then the natural size of the glyph for character \type {component}
 306                                is used). \NC \NR
 307 \stoptabulate
 308
 309 The \type {kerns} table is a hash indexed by character index (and \quote
 310 {character index} is defined as either a non|-|negative integer or the string
 311 value \type {right_boundary}), with the values the kerning to be applied, in
 312 scaled points.
 313
 314 The \type {ligatures} table is a hash indexed by character index (and \quote
 315 {character index} is defined as either a non|-|negative integer or the string
 316 value \type {right_boundary}), with the values being yet another small hash, with
 317 two fields:
 318
 319 \starttabulate[|lT|l|p|]
 320 \NC \ssbf key \NC \bf type \NC \bf description \NC \NR
 321 \NC type      \NC number   \NC the type of this ligature command, default 0 \NC \NR
 322 \NC char      \NC number   \NC the character index of the resultant ligature \NC \NR
 323 \stoptabulate
 324
 325 The \type {char} field in a ligature is required.
 326
 327 The \type {type} field inside a ligature is the numerical or string value of one
 328 of the eight possible ligature types supported by \TEX. When \TEX\ inserts a new
 329 ligature, it puts the new glyph in the middle of the left and right glyphs. The
 330 original left and right glyphs can optionally be retained, and when at least one
 331 of them is kept, it is also possible to move the new \quote {insertion point}
 332 forward one or two places. The glyph that ends up to the right of the insertion
 333 point will become the next \quote {left}.
 334
 335 \starttabulate[|l|c|l|l|]
 336 \NC \bf textual (Knuth) \NC \bf number \NC \bf string    \NC result \NC\NR
 337 \NC l + r =: n          \NC 0          \NC \type {=:}     \NC \|n    \NC\NR
 338 \NC l + r =:\| n        \NC 1          \NC \type {=:|}    \NC \|nr   \NC\NR
 339 \NC l + r \|=: n        \NC 2          \NC \type {|=:}    \NC \|ln   \NC\NR
 340 \NC l + r \|=:\| n      \NC 3          \NC \type {|=:|}   \NC \|lnr  \NC\NR
 341 \NC l + r  =:\|\> n     \NC 5          \NC \type {=:|>}   \NC n\|r   \NC\NR
 342 \NC l + r \|=:\> n      \NC 6          \NC \type {|=:>}   \NC l\|n   \NC\NR
 343 \NC l + r \|=:\|\> n    \NC 7          \NC \type {|=:|>}  \NC l\|nr  \NC\NR
 344 \NC l + r \|=:\|\>\> n  \NC 11         \NC \type {|=:|>>} \NC ln\|r  \NC\NR
 345 \stoptabulate
 346
 347 The default value is~0, and can be left out. That signifies a \quote {normal}
 348 ligature where the ligature replaces both original glyphs. In this table the~\|
 349 indicates the final insertion point.
 350
 351 The \type {commands} array is explained below.
 352
 353 \section {Real fonts}
 354
 355 Whether or not a \TEX\ font is a \quote {real} font that should be written to the
 356 \PDF\ document is decided by the \type {type} value in the top|-|level font
 357 structure. If the value is \type {real}, then this is a proper font, and the
 358 inclusion mechanism will attempt to add the needed font object definitions to the
 359 \PDF.
 360
 361 Values for \type {type}:
 362
 363 \starttabulate[|Tl|p|]
 364 \NC \ssbf value \NC \bf description        \NC\NR
 365 \NC real        \NC this is a base font    \NC\NR
 366 \NC virtual     \NC this is a virtual font \NC\NR
 367 \stoptabulate
 368
 369 The actions to be taken depend on a number of different variables:
 370
 371 \startitemize[packed]
 372 \startitem
 373     Whether the used font fits in an 8-bit encoding scheme or not.
 374 \stopitem
 375 \startitem
 376     The type of the disk font file.
 377 \stopitem
 378 \startitem
 379     The level of embedding requested.
 380 \stopitem
 381 \stopitemize
 382
 383 A font that uses anything other than an 8-bit encoding vector has to be written
 384 to the \PDF\ in a different way.
 385
 386 The rule is: if the font table has \type {encodingbytes} set to~2, then this is a
 387 wide font, in all other cases it isn't. The value~2 is the default for \OPENTYPE\
 388 and \TRUETYPE\ fonts loaded via \LUA. For \TYPEONE\ fonts, you have to set \type
 389 {encodingbytes} to~2 explicitly. For \PK\ bitmap fonts, wide font encoding is not
 390 supported at all.
 391
 392 If no special care is needed, \LUATEX\ currently falls back to the
 393 mapfile|-|based solution used by \PDFTEX\ and \DVIPS. This behavior will be
 394 removed in the future, when the existing code becomes integrated in the new
 395 subsystem.
 396
 397 But if this is a \quote {wide} font, then the new subsystem kicks in, and some
 398 extra fields have to be present in the font structure. In this case, \LUATEX\
 399 does not use a map file at all.
 400
 401 The extra fields are: \type {format}, \type {embedding}, \type {fullname}, \type
 402 {cidinfo} (as explained above), \type {filename}, and the \type {index} key in
 403 the separate characters.
 404
 405 Values for \type {format} are:
 406
 407 \starttabulate[|Tl|p|]
 408 \NC \ssbf value \NC \bf description                                           \NC \NR
 409 \NC type1       \NC this is a \POSTSCRIPT\ \TYPEONE\ font                     \NC \NR
 410 \NC type3       \NC this is a bitmapped (\PK) font                            \NC \NR
 411 \NC truetype    \NC this is a \TRUETYPE\ or \TRUETYPE|-|based \OPENTYPE\ font \NC \NR
 412 \NC opentype    \NC this is a \POSTSCRIPT|-|based \OPENTYPE\ font             \NC \NR
 413 \stoptabulate
 414
 415 \type {type3} fonts are provided for backward compatibility only, and do not
 416 support the new wide encoding options.
 417
 418 Values for \type {embedding} are:
 419
 420 \starttabulate[|Tl|p|]
 421 \NC \ssbf value \NC \bf description \NC \NR
 422 \NC no          \NC don't embed the font at all \NC \NR
 423 \NC subset      \NC include and atttempt to subset the font \NC \NR
 424 \NC full        \NC include this font in its entirety \NC \NR
 425 \stoptabulate
 426
 427 It is not possible to artificially modify the transformation matrix
 428 for the font at the moment.
 429
 430 The other fields are used as follows: The \type {fullname} will be the
 431 \POSTSCRIPT|/|\PDF\ font name. The \type {cidinfo} will be used as the character
 432 set (the CID \type {/Ordering} and \type {/Registry} keys). The \type {filename}
 433 points to the actual font file. If you include the full path in the \type
 434 {filename} or if the file is in the local directory, \LUATEX\ will run a little
 435 bit more efficient because it will not have to re|-|run the \type {find_xxx_file}
 436 callback in that case.
 437
 438 Be careful: when mixing old and new fonts in one document, it is possible to
 439 create \POSTSCRIPT\ name clashes that can result in printing errors. When this
 440 happens, you have to change the \type {fullname} of the font.
 441
 442 Typeset strings are written out in a wide format using 2~bytes per glyph, using
 443 the \type {index} key in the character information as value. The overall effect
 444 is like having an encoding based on numbers instead of traditional (\POSTSCRIPT)
 445 name|-|based reencoding. The way to get the correct \type {index} numbers for
 446 \TYPEONE\ fonts is by loading the font via \type {fontloader.open}; use the table
 447 indices as \type {index} fields.
 448
 449 This type of reencoding means that there is no longer a clear connection between
 450 the text in your input file and the strings in the output \PDF\ file. Dealing
 451 with this is high on the agenda.
 452
 453 \section[virtualfonts]{Virtual fonts}
 454
 455 You have to take the following steps if you want \LUATEX\ to treat the returned
 456 table from \type {define_font} as a virtual font:
 457
 458 \startitemize[packed]
 459 \startitem
 460     Set the top|-|level key \type {type} to \type {virtual}.
 461 \stopitem
 462 \startitem
 463     Make sure there is at least one valid entry in \type {fonts} (see below).
 464 \stopitem
 465 \startitem
 466     Give a \type {commands} array to every character (see below).
 467 \stopitem
 468 \stopitemize
 469
 470 The presence of the toplevel \type {type} key with the specific value \type
 471 {virtual} will trigger handling of the rest of the special virtual font fields in
 472 the table, but the mere existence of 'type' is enough to prevent \LUATEX\ from
 473 looking for a virtual font on its own.
 474
 475 Therefore, this also works \quote {in reverse}: if you are absolutely certain
 476 that a font is not a virtual font, assigning the value \type {base} or \type
 477 {real} to \type {type} will inhibit \LUATEX\ from looking for a virtual font
 478 file, thereby saving you a disk search.
 479
 480 The \type {fonts} is another \LUA\ array. The values are one- or two|-|key
 481 hashes themselves, each entry indicating one of the base fonts in a virtual font.
 482 In case your font is referring to itself, you can use the \type {font.nextid()}
 483 function which returns the index of the next to be defined font which is probably
 484 the currently defined one.
 485
 486 An example makes this easy to understand
 487
 488 \starttyping
 489 fonts = {
 490     { name = 'ptmr8a', size = 655360 },
 491     { name = 'psyr', size = 600000 },
 492     { id = 38 }
 493 }
 494 \stoptyping
 495
 496 says that the first referenced font (index 1) in this virtual font is \type
 497 {ptrmr8a} loaded at 10pt, and the second is \type {psyr} loaded at a little over
 498 9pt. The third one is previously defined font that is known to \LUATEX\ as fontid
 499 \quote {38}.
 500
 501 The array index numbers are used by the character command definitions that are
 502 part of each character.
 503
 504 The \type {commands} array is a hash where each item is another small array,
 505 with the first entry representing a command and the extra items being the
 506 parameters to that command. The allowed commands and their arguments are:
 507
 508 \starttabulate[|Tl|l|l|p|]
 509 \NC \ssbf command name  \NC \bf arguments \NC \bf arg type \NC \bf description \NC\NR
 510 \NC font              \NC 1         \NC number    \NC select a new font from the local \type {fonts} table\NC\NR
 511 \NC char              \NC 1         \NC number    \NC typeset this character number from the current font,
 512                                                       and move right by the character's width\NC\NR
 513 \NC node              \NC 1         \NC node      \NC output this node (list), and move right
 514                                                       by the width of this list\NC\NR
 515 \NC slot              \NC 2         \NC number    \NC a shortcut for the combination of a font and char command\NC\NR
 516 \NC push              \NC 0         \NC           \NC save current position\NC\NR
 517 \NC nop               \NC 0         \NC           \NC do nothing \NC\NR
 518 \NC pop               \NC 0         \NC           \NC pop position \NC\NR
 519 \NC rule              \NC 2         \NC 2 numbers \NC output a rule $ht*wd$, and move right.\NC\NR
 520 \NC down              \NC 1         \NC number    \NC move down on the page\NC\NR
 521 \NC right             \NC 1         \NC number    \NC move right on the page\NC\NR
 522 \NC special           \NC 1         \NC string    \NC output a \type {\special} command\NC\NR
 523 \NC lua               \NC 1         \NC string    \NC execute a \LUA\ script (at \type {\latelua} time)\NC\NR
 524 \NC image             \NC 1         \NC image     \NC output an image (the argument can be either an \type
 525                                                       {<image>} variable or an \type {image_spec} table)\NC\NR
 526 \NC comment           \NC any       \NC any       \NC the arguments of this command are ignored\NC\NR
 527 \stoptabulate
 528
 529 When a font id is set to~0 then it will be replaced by the currently assigned
 530 font id. This prevents the need for hackery with future id's (normally one could
 531 use \type {font.nextid} but when more complex fonts are built in the meantime
 532 other instances could have been loaded.
 533
 534 Here is a rather elaborate glyph commands example:
 535
 536 \starttyping
 537 ...
 538 commands = {
 539     { 'push' },                    -- remember where we are
 540     { 'right', 5000 },             -- move right about 0.08pt
 541     { 'font', 3 },                 -- select the fonts[3] entry
 542     { 'char', 97 },                -- place character 97 (ASCII 'a')
 543     { 'pop' },                     -- go all the way back
 544     { 'down', -200000 },           -- move upwards by about 3pt
 545     { 'special', 'pdf: 1 0 0 rg' } -- switch to red color
 546     { 'rule', 500000, 20000 }      -- draw a bar
 547     { 'special','pdf: 0 g' }       -- back to black
 548 }
 549 ...
 550 \stoptyping
 551
 552 The default value for \type {font} is always~1 at the start of the
 553 \type {commands} array. Therefore, if the virtual font is essentially only a
 554 re|-|encoding, then you do usually not have create an explicit \quote {font}
 555 command in the array.
 556
 557 Rules inside of \type {commands} arrays are built up using only two dimensions:
 558 they do not have depth. For correct vertical placement, an extra \type {down}
 559 command may be needed.
 560
 561 Regardless of the amount of movement you create within the \type {commands}, the
 562 output pointer will always move by exactly the width that was given in the \type
 563 {width} key of the character hash. Any movements that take place inside the \type
 564 {commands} array are ignored on the upper level.
 565
 566 \subsection{Artificial fonts}
 567
 568 Even in a \quote {real} font, there can be virtual characters. When \LUATEX\
 569 encounters a \type {commands} field inside a character when it becomes time to
 570 typeset the character, it will interpret the commands, just like for a true
 571 virtual character. In this case, if you have created no \quote {fonts} array,
 572 then the default (and only) \quote {base} font is taken to be the current font
 573 itself. In practice, this means that you can create virtual duplicates of
 574 existing characters which is useful if you want to create composite characters.
 575
 576 Note: this feature does {\it not\/} work the other way around. There can not be
 577 \quote {real} characters in a virtual font! You cannot use this technique for
 578 font re-encoding either; you need a truly virtual font for that (because
 579 characters that are already present cannot be altered).
 580
 581 \subsection{Example virtual font}
 582
 583 Finally, here is a plain \TEX\ input file with a virtual font demonstration:
 584
 585 \startbuffer
 586 \directlua {
 587   callback.register('define_font',
 588     function (name,size)
 589       if name == 'cmr10-red' then
 590         f = font.read_tfm('cmr10',size)
 591         f.name = 'cmr10-red'
 592         f.type = 'virtual'
 593         f.fonts = {{ name = 'cmr10', size = size }}
 594         for i,v in pairs(f.characters) do
 595           if (string.char(i)):find('[tacohanshartmut]') then
 596              v.commands = {
 597                {'special','pdf: 1 0 0 rg'},
 598                {'char',i},
 599                {'special','pdf: 0 g'},
 600               }
 601           else
 602              v.commands = {{'char',i}}
 603           end
 604         end
 605       else
 606         f = font.read_tfm(name,size)
 607       end
 608       return f
 609     end
 610   )
 611 }
 612
 613 \font\myfont = cmr10-red at 10pt \myfont  This is a line of text \par
 614 \font\myfontx= cmr10 at 10pt \myfontx Here is another line of text \par
 615 \stopbuffer
 616
 617 \typebuffer
 618
 619 % \getbuffer
 620
 621 \stopchapter
 622
 623 \stopcomponent