manual/luatex-fonts.tex

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