diff options
Diffstat (limited to 'doc/context/sources/general/manuals/luatex/luatex-fonts.tex')
-rw-r--r-- | doc/context/sources/general/manuals/luatex/luatex-fonts.tex | 535 |
1 files changed, 314 insertions, 221 deletions
diff --git a/doc/context/sources/general/manuals/luatex/luatex-fonts.tex b/doc/context/sources/general/manuals/luatex/luatex-fonts.tex index 150532ec2..7384f3b3e 100644 --- a/doc/context/sources/general/manuals/luatex/luatex-fonts.tex +++ b/doc/context/sources/general/manuals/luatex/luatex-fonts.tex @@ -7,133 +7,78 @@ \startchapter[reference=fonts,title={Font structure}] +\section {The font tables} + All \TEX\ fonts are represented to \LUA\ code as tables, and internally as \CCODE~structures. All keys in the table below are saved in the internal font structure if they are present in the table returned by the \type {define_font} callback, or if they result from the normal \TFM|/|\VF\ reading routines if there is no \type {define_font} callback defined. -The column \quote {from \VF} means that this key will be created by the \type -{font.read_vf()} routine, \quote {from \TFM} means that the key will be created -by the \type {font.read_tfm()} routine, and \quote{used} means whether or not -the \LUATEX\ engine itself will do something with the key. +The column \quote {\VF} means that this key will be created by the \type +{font.read_vf()} routine, \quote {\TFM} means that the key will be created by the +\type {font.read_tfm()} routine, and \quote{used} means whether or not the +\LUATEX\ engine itself will do something with the key. The top|-|level keys in the table are as follows: -\starttabulate[|Tl|l|l|l|l|p|] -\NC \ssbf key \NC \bf from vf \NC \bf from tfm \NC \bf used\NC \bf value type \NC - \bf description -\NC \NR -\NC name \NC yes \NC yes \NC yes \NC string \NC - metric (file) name -\NC \NR -\NC area \NC no \NC yes \NC yes \NC string \NC - (directory) location, typically empty -\NC \NR -\NC used \NC no \NC yes \NC yes \NC boolean\NC - used already? (initial: false) -\NC \NR -\NC characters \NC yes \NC yes \NC yes \NC table \NC - the defined glyphs of this font -\NC \NR -\NC checksum \NC yes \NC yes \NC no \NC number \NC - default: 0 -\NC \NR -\NC designsize \NC no \NC yes \NC yes \NC number \NC - expected size (default: 655360 == 10pt) -\NC \NR -\NC direction \NC no \NC yes \NC yes \NC number \NC - default: 0 (TLT) -\NC \NR -\NC encodingbytes \NC no \NC no \NC yes \NC number \NC - default: depends on \type {format} -\NC \NR -\NC encodingname \NC no \NC no \NC yes \NC string \NC - encoding name -\NC \NR -\NC fonts \NC yes \NC no \NC yes \NC table \NC - locally used fonts -\NC \NR -\NC psname \NC no \NC no \NC yes \NC string \NC - actual (\POSTSCRIPT) name (this is the PS fontname in the incoming font - source, also used as fontname identifier in the \PDF\ output) -\NC \NR -\NC fullname \NC no \NC no \NC yes \NC string \NC - output font name, used as a fallback in the \PDF\ output - if the psname is not set -\NC \NR -\NC header \NC yes \NC no \NC no \NC string \NC - header comments, if any -\NC \NR -\NC hyphenchar \NC no \NC no \NC yes \NC number \NC - default: TeX's \type {\hyphenchar} -\NC \NR -\NC parameters \NC no \NC yes \NC yes \NC hash \NC - default: 7 parameters, all zero -\NC \NR -\NC size \NC no \NC yes \NC yes \NC number \NC - loaded (at) size. (default: same as designsize) -\NC \NR -\NC skewchar \NC no \NC no \NC yes \NC number \NC - default: TeX's \type {\skewchar} -\NC \NR -\NC type \NC yes \NC no \NC yes \NC string \NC - basic type of this font -\NC \NR -\NC format \NC no \NC no \NC yes \NC string \NC - disk format type -\NC \NR -\NC embedding \NC no \NC no \NC yes \NC string \NC - \PDF\ inclusion -\NC \NR -\NC filename \NC no \NC no \NC yes \NC string \NC - disk file name -\NC \NR -\NC tounicode \NC no \NC yes \NC yes \NC number \NC - if 1, \LUATEX\ assumes per-glyph tounicode entries are - present in the font -\NC \NR -\NC stretch \NC no \NC no \NC yes \NC number \NC - the \quote {stretch} value from \type {\expandglyphsinfont} -\NC \NR -\NC shrink \NC no \NC no \NC yes \NC number \NC - the \quote {shrink} value from \type {\expandglyphsinfont} -\NC \NR -\NC step \NC no \NC no \NC yes \NC number \NC - the \quote {step} value from \type {\expandglyphsinfont} -\NC \NR -\NC auto_expand \NC no \NC no \NC yes \NC boolean\NC - the \quote {autoexpand} keyword from\crlf \type {\expandglyphsinfont} -\NC \NR -\NC expansion_factor \NC no \NC no \NC no \NC number \NC - the actual expansion factor of an expanded font -\NC \NR -\NC attributes \NC no \NC no \NC yes \NC string \NC - the \type {\pdffontattr} -\NC \NR -\NC cache \NC no \NC no \NC yes \NC string \NC - this key controls caching of the \LUA\ table on the \type {tex} end. \type - {yes}: use a reference to the table that is passed to \LUATEX\ (this is the - default). \type {no}: don't store the table reference, don't cache any \LUA\ - data for this font. \type {renew}: don't store the table reference, but save - a reference to the table that is created at the first access to one of its - fields in font.fonts. Note: the saved reference is thread-local, so be - careful when you are using coroutines: an error will be thrown if the table - has been cached in one thread, but you reference it from another thread - ($\approx$ coroutine) -\NC \NR -\NC nomath \NC no \NC no \NC yes \NC boolean\NC - this key allows a minor speedup for text fonts. if it is present and true, - then \LUATEX\ will not check the character enties for math-specific keys. -\NC \NR -\NC slant \NC no \NC no \NC yes \NC number \NC - This has the same semantics as the \type {SlantFont} operator in font map - files. -\NC \NR -\NC extent \NC no \NC no \NC yes \NC number \NC - This has the same semantics as the \type {ExtendFont} operator in font map - files. -\NC \NR +\starttabulate[|Tl|c|c|c|l|p|] +\NC \rmbf key \NC \bf vf \NC \bf tfm \NC \bf used \NC \bf value type \NC \bf description \NC \NR +\NC name \NC yes \NC yes \NC yes \NC string \NC metric (file) name \NC \NR +\NC area \NC no \NC yes \NC yes \NC string \NC (directory) location, typically empty \NC \NR +\NC used \NC no \NC yes \NC yes \NC boolean\NC indicates usage (initial: false) \NC \NR +\NC characters \NC yes \NC yes \NC yes \NC table \NC the defined glyphs of this font \NC \NR +\NC checksum \NC yes \NC yes \NC no \NC number \NC default: 0 \NC \NR +\NC designsize \NC no \NC yes \NC yes \NC number \NC expected size (default: 655360 == 10pt) \NC \NR +\NC direction \NC no \NC yes \NC yes \NC number \NC default: 0 \NC \NR +\NC encodingbytes \NC no \NC no \NC yes \NC number \NC default: depends on \type {format} \NC \NR +\NC encodingname \NC no \NC no \NC yes \NC string \NC encoding name \NC \NR +\NC fonts \NC yes \NC no \NC yes \NC table \NC locally used fonts \NC \NR +\NC psname \NC no \NC no \NC yes \NC string \NC This is the \POSTSCRIPT\ fontname in the incoming font + source, and it's used as fontname identifier in the \PDF\ + output. \NC \NR +\NC fullname \NC no \NC no \NC yes \NC string \NC output font name, used as a fallback in the \PDF\ output + if the \type {psname} is not set \NC \NR +\NC header \NC yes \NC no \NC no \NC string \NC header comments, if any \NC \NR +\NC hyphenchar \NC no \NC no \NC yes \NC number \NC default: \TEX's \type {\hyphenchar} \NC \NR +\NC parameters \NC no \NC yes \NC yes \NC hash \NC default: 7 parameters, all zero \NC \NR +\NC size \NC no \NC yes \NC yes \NC number \NC loaded (at) size. (default: same as designsize) \NC \NR +\NC skewchar \NC no \NC no \NC yes \NC number \NC default: \TEX's \type {\skewchar} \NC \NR +\NC type \NC yes \NC no \NC yes \NC string \NC basic type of this font \NC \NR +\NC format \NC no \NC no \NC yes \NC string \NC disk format type \NC \NR +\NC embedding \NC no \NC no \NC yes \NC string \NC \PDF\ inclusion \NC \NR +\NC filename \NC no \NC no \NC yes \NC string \NC the name of the font on disk \NC \NR +\NC tounicode \NC no \NC yes \NC yes \NC number \NC When this is set to~1 \LUATEX\ assumes per|-|glyph + tounicode entries are present in the font. \NC \NR +\NC stretch \NC no \NC no \NC yes \NC number \NC the \quote {stretch} value from \type + {\expandglyphsinfont} \NC \NR +\NC shrink \NC no \NC no \NC yes \NC number \NC the \quote {shrink} value from \type + {\expandglyphsinfont} \NC \NR +\NC step \NC no \NC no \NC yes \NC number \NC the \quote {step} value from \type + {\expandglyphsinfont} \NC \NR +\NC auto_expand \NC no \NC no \NC yes \NC boolean\NC the \quote {autoexpand} keyword from \crlf + \type {\expandglyphsinfont} \NC \NR +\NC expansion_factor \NC no \NC no \NC no \NC number \NC the actual expansion factor of an expanded font \NC \NR +\NC attributes \NC no \NC no \NC yes \NC string \NC the \type {\pdffontattr} \NC \NR +\NC cache \NC no \NC no \NC yes \NC string \NC This key controls caching of the \LUA\ table on the + \TEX\ end where \type {yes} means: use a reference to + the table that is passed to \LUATEX\ (this is the + default), and no \type {no} means: don't store the + table reference, don't cache any \LUA\ data for this + font while \type {renew} means: don't store the table + reference, but save a reference to the table that is + created at the first access to one of its fields in font. + Note: the saved reference is thread|-|local, so be + careful when you are using coroutines: an error will be + thrown if the table has been cached in one thread, but + you reference it from another thread. \NC \NR +\NC nomath \NC no \NC no \NC yes \NC boolean\NC This key allows a minor speedup for text fonts. If it + is present and true, then \LUATEX\ will not check the + character entries for math|-|specific keys. \NC \NR +\NC slant \NC no \NC no \NC yes \NC number \NC This has the same semantics as the \type {SlantFont} + operator in font map files. \NC \NR +\NC extent \NC no \NC no \NC yes \NC number \NC This has the same semantics as the \type {ExtendFont} + operator in font map files. \NC \NR \stoptabulate The key \type {name} is always required. The keys \type {stretch}, \type @@ -143,27 +88,29 @@ used together: they can be used to replace a post|-|loading \type present inside a font in \type {font.fonts}. It is the actual expansion factor (a value between \type {-shrink} and \type {stretch}, with step \type {step}) of a font that was automatically generated by the font expansion algorithm. The key -\type {attributes} can be used to replace \type {\pdffontattr}. The key \type {used} -is set by the engine when a font is actively in use, this makes sure that the -font's definition is written to the output file (\DVI\ or \PDF). The \TFM\ reader -sets it to false. The \type {direction} is a number signalling the \quote -{normal} direction for this font. There are sixteen possibilities: - -\starttabulate[|Tc|c|c|c|] -\NC \ssbf number \NC \bf meaning \NC \bf number \NC \bf meaning \NC\NR -\NC 0 \NC LT \NC 8 \NC TT \NC\NR -\NC 1 \NC LL \NC 9 \NC TL \NC\NR -\NC 2 \NC LB \NC 10 \NC TB \NC\NR -\NC 3 \NC LR \NC 11 \NC TR \NC\NR -\NC 4 \NC RT \NC 12 \NC BT \NC\NR -\NC 5 \NC RL \NC 13 \NC BL \NC\NR -\NC 6 \NC RB \NC 14 \NC BB \NC\NR -\NC 7 \NC RR \NC 15 \NC BR \NC\NR +\type {attributes} can be used to set font attributes in the \PDF\ file. The key +\type {used} is set by the engine when a font is actively in use, this makes sure +that the font's definition is written to the output file (\DVI\ or \PDF). The +\TFM\ reader sets it to false. The \type {direction} is a number signalling the +\quote {normal} direction for this font. There are sixteen possibilities: + +\starttabulate[|Tc|Tc|Tc|Tc|] +\NC \rmbf number \NC \rmbf meaning \NC \rmbf number \NC \rmbf meaning \NC\NR +\NC 0 \NC LT \NC 8 \NC TT \NC\NR +\NC 1 \NC LL \NC 9 \NC TL \NC\NR +\NC 2 \NC LB \NC 10 \NC TB \NC\NR +\NC 3 \NC LR \NC 11 \NC TR \NC\NR +\NC 4 \NC RT \NC 12 \NC BT \NC\NR +\NC 5 \NC RL \NC 13 \NC BL \NC\NR +\NC 6 \NC RB \NC 14 \NC BB \NC\NR +\NC 7 \NC RR \NC 15 \NC BR \NC\NR \stoptabulate These are \OMEGA|-|style direction abbreviations: the first character indicates the \quote {first} edge of the character glyphs (the edge that is seen first in -the writing direction), the second the \quote {top} side. +the writing direction), the second the \quote {top} side. Keep in mind that +\LUATEX\ has a bit different directional model so these values are not used for +anything. The \type {parameters} is a hash with mixed key types. There are seven possible string keys, as well as a number of integer indices (these start from 8 up). The @@ -173,7 +120,7 @@ gives a nicer user interface. The names and their internal remapping are: \starttabulate[|lT|c|] -\NC \ssbf name \NC \bf internal remapped number \NC\NR +\NC \rmbf name \NC \rmbf remapping \NC\NR \NC slant \NC 1 \NC\NR \NC space \NC 2 \NC\NR \NC space_stretch \NC 3 \NC\NR @@ -192,12 +139,12 @@ number. The number is the \quote {internal code} \TEX\ knows this character by. Two very special string indexes can be used also: \type {left_boundary} is a virtual character whose ligatures and kerns are used to handle word boundary processing. \type {right_boundary} is similar but not actually used for anything -(yet!). +(yet). Other index keys are ignored. Each character hash itself is a hash. For example, here is the character \quote -{f} (decimal 102) in the font cmr10 at 10 points: +{f} (decimal 102) in the font \type {cmr10 at 10pt}: \starttyping [102] = { @@ -232,28 +179,28 @@ Each character hash itself is a hash. For example, here is the character \quote The following top|-|level keys can be present inside a character hash: \starttabulate[|lT|c|c|c|l|p|] -\NC \ssbf key \NC \bf from vf \NC \bf from tfm \NC \bf used \NC \bf value type \NC \bf description \NC\NR -\NC width \NC yes \NC yes \NC yes \NC number \NC character's width, in sp (default 0) \NC\NR -\NC height \NC no \NC yes \NC yes \NC number \NC character's height, in sp (default 0) \NC\NR -\NC depth \NC no \NC yes \NC yes \NC number \NC character's depth, in sp (default 0) \NC\NR -\NC italic \NC no \NC yes \NC yes \NC number \NC character's italic correction, in sp (default zero) \NC\NR -\NC top_accent \NC no \NC no \NC maybe \NC number \NC character's top accent alignment place, in sp (default zero) \NC\NR -\NC bot_accent \NC no \NC no \NC maybe \NC number \NC character's bottom accent alignment place, in sp (default zero) \NC\NR -\NC left_protruding \NC no \NC no \NC maybe \NC number \NC character's \type {\lpcode} \NC\NR -\NC right_protruding \NC no \NC no \NC maybe \NC number \NC character's \type {\rpcode} \NC\NR -\NC expansion_factor \NC no \NC no \NC maybe \NC number \NC character's \type {\efcode} \NC\NR -\NC tounicode \NC no \NC no \NC maybe \NC string \NC character's \UNICODE\ equivalent(s), in \UTF|-|16BE hexadecimal format \NC\NR -\NC next \NC no \NC yes \NC yes \NC number \NC the \quote {next larger} character index \NC\NR -\NC extensible \NC no \NC yes \NC yes \NC table \NC the constituent parts of an extensible recipe \NC\NR -\NC vert_variants \NC no \NC no \NC yes \NC table \NC constituent parts of a vertical variant set \NC \NR -\NC horiz_variants \NC no \NC no \NC yes \NC table \NC constituent parts of a horizontal variant set \NC \NR -\NC kerns \NC no \NC yes \NC yes \NC table \NC kerning information \NC\NR -\NC ligatures \NC no \NC yes \NC yes \NC table \NC ligaturing information \NC\NR -\NC commands \NC yes \NC no \NC yes \NC array \NC virtual font commands \NC\NR -\NC name \NC no \NC no \NC no \NC string \NC the character (\POSTSCRIPT) name \NC\NR -\NC index \NC no \NC no \NC yes \NC number \NC the (\OPENTYPE\ or \TRUETYPE) font glyph index \NC\NR -\NC used \NC no \NC yes \NC yes \NC boolean \NC typeset already (default: false)? \NC\NR -\NC mathkern \NC no \NC no \NC yes \NC table \NC math cut-in specifications \NC\NR +\NC \rmbf key \NC \bf vf \NC \bf tfm \NC \bf used \NC \bf type \NC \bf description \NC\NR +\NC width \NC yes \NC yes \NC yes \NC number \NC character's width, in sp (default 0) \NC\NR +\NC height \NC no \NC yes \NC yes \NC number \NC character's height, in sp (default 0) \NC\NR +\NC depth \NC no \NC yes \NC yes \NC number \NC character's depth, in sp (default 0) \NC\NR +\NC italic \NC no \NC yes \NC yes \NC number \NC character's italic correction, in sp (default zero) \NC\NR +\NC top_accent \NC no \NC no \NC maybe \NC number \NC character's top accent alignment place, in sp (default zero) \NC\NR +\NC bot_accent \NC no \NC no \NC maybe \NC number \NC character's bottom accent alignment place, in sp (default zero) \NC\NR +\NC left_protruding \NC no \NC no \NC maybe \NC number \NC character's \type {\lpcode} \NC\NR +\NC right_protruding \NC no \NC no \NC maybe \NC number \NC character's \type {\rpcode} \NC\NR +\NC expansion_factor \NC no \NC no \NC maybe \NC number \NC character's \type {\efcode} \NC\NR +\NC tounicode \NC no \NC no \NC maybe \NC string \NC character's \UNICODE\ equivalent(s), in \UTF|-|16BE hexadecimal format \NC\NR +\NC next \NC no \NC yes \NC yes \NC number \NC the \quote {next larger} character index \NC\NR +\NC extensible \NC no \NC yes \NC yes \NC table \NC the constituent parts of an extensible recipe \NC\NR +\NC vert_variants \NC no \NC no \NC yes \NC table \NC constituent parts of a vertical variant set \NC \NR +\NC horiz_variants \NC no \NC no \NC yes \NC table \NC constituent parts of a horizontal variant set \NC \NR +\NC kerns \NC no \NC yes \NC yes \NC table \NC kerning information \NC\NR +\NC ligatures \NC no \NC yes \NC yes \NC table \NC ligaturing information \NC\NR +\NC commands \NC yes \NC no \NC yes \NC array \NC virtual font commands \NC\NR +\NC name \NC no \NC no \NC no \NC string \NC the character (\POSTSCRIPT) name \NC\NR +\NC index \NC no \NC no \NC yes \NC number \NC the (\OPENTYPE\ or \TRUETYPE) font glyph index \NC\NR +\NC used \NC no \NC yes \NC yes \NC boolean \NC typeset already (default: false)? \NC\NR +\NC mathkern \NC no \NC no \NC yes \NC table \NC math cut-in specifications \NC\NR \stoptabulate The values of \type {top_accent}, \type {bot_accent} and \type {mathkern} are @@ -276,7 +223,7 @@ If the font level \type {tounicode} is not set, then \LUATEX\ will build up \typ {/ToUnicode} based on the \TEX\ code points you used, and any character-level \type {tounicodes} will be ignored. The string format is exactly the format that is expected by Adobe \CMAP\ files (\UTF-16BE in hexadecimal encoding), minus the -enclosing angle brackets. Small example: the \type {tounicode} for a \type {fi} +enclosing angle brackets. For instance the \type {tounicode} for a \type {fi} ligature would be \type {00660069}. When you pass a number the conversion will be done for you. @@ -286,25 +233,25 @@ present. It in in turn can be overruled by \type {vert_variants}. The \type {extensible} table is very simple: \starttabulate[|lT|l|p|] -\NC \ssbf key \NC \bf type \NC \bf description \NC\NR -\NC top \NC number \NC \quote{top} character index \NC\NR -\NC mid \NC number \NC \quote{middle} character index \NC\NR -\NC bot \NC number \NC \quote{bottom} character index \NC\NR -\NC rep \NC number \NC \quote{repeatable} character index \NC\NR +\NC \rmbf key \NC \bf type \NC \bf description \NC\NR +\NC top \NC number \NC top character index \NC\NR +\NC mid \NC number \NC middle character index \NC\NR +\NC bot \NC number \NC bottom character index \NC\NR +\NC rep \NC number \NC repeatable character index \NC\NR \stoptabulate The \type {horiz_variants} and \type {vert_variants} are arrays of components. Each of those components is itself a hash of up to five keys: \starttabulate[|lT|l|p|] -\NC \ssbf key \NC \bf type \NC \bf explanation \NC\NR -\NC glyph \NC number \NC The character index (note that this is an encoding number, not a name). \NC \NR +\NC \rmbf key \NC \bf type \NC \bf explanation \NC\NR +\NC glyph \NC number \NC The character index. Note that this is an encoding number, not a name. \NC \NR \NC extender \NC number \NC One (1) if this part is repeatable, zero (0) otherwise. \NC \NR -\NC start \NC number \NC Maximum overlap at the starting side (in scaled points). \NC \NR -\NC end \NC number \NC Maximum overlap at the ending side (in scaled points). \NC \NR -\NC advance \NC number \NC The total advance width of this item (can be zero or missing, +\NC start \NC number \NC The maximum overlap at the starting side (in scaled points). \NC \NR +\NC end \NC number \NC The maximum overlap at the ending side (in scaled points). \NC \NR +\NC advance \NC number \NC The total advance width of this item. It can be zero or missing, then the natural size of the glyph for character \type {component} - is used). \NC \NR + is used. \NC \NR \stoptabulate The \type {kerns} table is a hash indexed by character index (and \quote @@ -318,7 +265,7 @@ value \type {right_boundary}), with the values being yet another small hash, wit two fields: \starttabulate[|lT|l|p|] -\NC \ssbf key \NC \bf type \NC \bf description \NC \NR +\NC \rmbf key \NC \bf type \NC \bf description \NC \NR \NC type \NC number \NC the type of this ligature command, default 0 \NC \NR \NC char \NC number \NC the character index of the resultant ligature \NC \NR \stoptabulate @@ -334,15 +281,15 @@ forward one or two places. The glyph that ends up to the right of the insertion point will become the next \quote {left}. \starttabulate[|l|c|l|l|] -\NC \bf textual (Knuth) \NC \bf number \NC \bf string \NC result \NC\NR -\NC \type{l + r =: n} \NC 0 \NC \type {=:} \NC \type{|n} \NC\NR -\NC \type{l + r =:| n} \NC 1 \NC \type {=:|} \NC \type{|nr} \NC\NR -\NC \type{l + r |=: n} \NC 2 \NC \type {|=:} \NC \type{|ln} \NC\NR -\NC \type{l + r |=:| n} \NC 3 \NC \type {|=:|} \NC \type{|lnr} \NC\NR -\NC \type{l + r =:|> n} \NC 5 \NC \type {=:|>} \NC \type{n|r} \NC\NR -\NC \type{l + r |=:> n} \NC 6 \NC \type {|=:>} \NC \type{l|n} \NC\NR -\NC \type{l + r |=:|> n} \NC 7 \NC \type {|=:|>} \NC \type{l|nr} \NC\NR -\NC \type{l + r |=:|>> n} \NC 11 \NC \type {|=:|>>} \NC \type{ln|r} \NC\NR +\NC \bf textual (Knuth) \NC \bf number \NC \bf string \NC result \NC\NR +\NC \type{l + r =: n} \NC 0 \NC \type{=:} \NC \type{|n} \NC\NR +\NC \type{l + r =:| n} \NC 1 \NC \type{=:|} \NC \type{|nr} \NC\NR +\NC \type{l + r |=: n} \NC 2 \NC \type{|=:} \NC \type{|ln} \NC\NR +\NC \type{l + r |=:| n} \NC 3 \NC \type{|=:|} \NC \type{|lnr} \NC\NR +\NC \type{l + r =:|> n} \NC 5 \NC \type{=:|>} \NC \type{n|r} \NC\NR +\NC \type{l + r |=:> n} \NC 6 \NC \type{|=:>} \NC \type{l|n} \NC\NR +\NC \type{l + r |=:|> n} \NC 7 \NC \type{|=:|>} \NC \type{l|nr} \NC\NR +\NC \type{l + r |=:|>> n} \NC 11 \NC \type{|=:|>>} \NC \type{ln|r} \NC\NR \stoptabulate The default value is~0, and can be left out. That signifies a \quote {normal} @@ -357,12 +304,10 @@ Whether or not a \TEX\ font is a \quote {real} font that should be written to th \PDF\ document is decided by the \type {type} value in the top|-|level font structure. If the value is \type {real}, then this is a proper font, and the inclusion mechanism will attempt to add the needed font object definitions to the -\PDF. - -Values for \type {type}: +\PDF. Values for \type {type} are: \starttabulate[|Tl|p|] -\NC \ssbf value \NC \bf description \NC\NR +\NC \rmbf value \NC \rmbf description \NC\NR \NC real \NC this is a base font \NC\NR \NC virtual \NC this is a virtual font \NC\NR \stoptabulate @@ -391,11 +336,11 @@ and \TRUETYPE\ fonts loaded via \LUA. For \TYPEONE\ fonts, you have to set \type supported at all. If no special care is needed, \LUATEX\ currently falls back to the -mapfile|-|based solution used by \PDFTEX\ and \DVIPS. This behaviour will be -removed in the future, when the existing code becomes integrated in the new -subsystem. +mapfile|-|based solution used by \PDFTEX\ and \DVIPS. This behaviour might +silently be removed in the future, in which case the related primitives and \LUA\ +functions will become no|-|ops. -But if this is a \quote {wide} font, then the new subsystem kicks in, and some +If a \quote {wide} font is used, the new subsystem kicks in, and some extra fields have to be present in the font structure. In this case, \LUATEX\ does not use a map file at all. @@ -406,7 +351,7 @@ the separate characters. Values for \type {format} are: \starttabulate[|Tl|p|] -\NC \ssbf value \NC \bf description \NC \NR +\NC \rmbf value \NC \rmbf description \NC \NR \NC type1 \NC this is a \POSTSCRIPT\ \TYPEONE\ font \NC \NR \NC type3 \NC this is a bitmapped (\PK) font \NC \NR \NC truetype \NC this is a \TRUETYPE\ or \TRUETYPE|-|based \OPENTYPE\ font \NC \NR @@ -419,15 +364,12 @@ support the new wide encoding options. Values for \type {embedding} are: \starttabulate[|Tl|p|] -\NC \ssbf value \NC \bf description \NC \NR -\NC no \NC don't embed the font at all \NC \NR +\NC \rmbf value \NC \rmbf description \NC \NR +\NC no \NC don't embed the font at all \NC \NR \NC subset \NC include and atttempt to subset the font \NC \NR -\NC full \NC include this font in its entirety \NC \NR +\NC full \NC include this font in its entirety \NC \NR \stoptabulate -It is not possible to artificially modify the transformation matrix -for the font at the moment. - The other fields are used as follows: The \type {fullname} will be the \POSTSCRIPT|/|\PDF\ font name. The \type {cidinfo} will be used as the character set (the CID \type {/Ordering} and \type {/Registry} keys). The \type {filename} @@ -444,15 +386,16 @@ Typeset strings are written out in a wide format using 2~bytes per glyph, using the \type {index} key in the character information as value. The overall effect is like having an encoding based on numbers instead of traditional (\POSTSCRIPT) name|-|based reencoding. The way to get the correct \type {index} numbers for -\TYPEONE\ fonts is by loading the font via \type {fontloader.open}; use the table +\TYPEONE\ fonts is by loading the font via \type {fontloader.open} and use the table indices as \type {index} fields. -This type of reencoding means that there is no longer a clear connection between -the text in your input file and the strings in the output \PDF\ file. Dealing -with this is high on the agenda. +In order to make sure that cut and paste of the final document works okay you can +best make sure that there is a \type {tounicode} vector enforced. \section[virtualfonts]{Virtual fonts} +\subsection{The structure} + You have to take the following steps if you want \LUATEX\ to treat the returned table from \type {define_font} as a virtual font: @@ -507,24 +450,24 @@ with the first entry representing a command and the extra items being the parameters to that command. The allowed commands and their arguments are: \starttabulate[|Tl|l|l|p|] -\NC \ssbf command name \NC \bf arguments \NC \bf arg type \NC \bf description \NC\NR -\NC font \NC 1 \NC number \NC select a new font from the local \type {fonts} table\NC\NR -\NC char \NC 1 \NC number \NC typeset this character number from the current font, - and move right by the character's width\NC\NR -\NC node \NC 1 \NC node \NC output this node (list), and move right - by the width of this list\NC\NR -\NC slot \NC 2 \NC number \NC a shortcut for the combination of a font and char command\NC\NR -\NC push \NC 0 \NC \NC save current position\NC\NR -\NC nop \NC 0 \NC \NC do nothing \NC\NR -\NC pop \NC 0 \NC \NC pop position \NC\NR -\NC rule \NC 2 \NC 2 numbers \NC output a rule $ht*wd$, and move right.\NC\NR -\NC down \NC 1 \NC number \NC move down on the page\NC\NR -\NC right \NC 1 \NC number \NC move right on the page\NC\NR -\NC special \NC 1 \NC string \NC output a \type {\special} command\NC\NR -\NC lua \NC 1 \NC string \NC execute a \LUA\ script (at \type {\latelua} time)\NC\NR -\NC 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 -\NC comment \NC any \NC any \NC the arguments of this command are ignored\NC\NR +\NC \rmbf command name \NC \bf arguments \NC \bf type \NC \bf description \NC\NR +\NC font \NC 1 \NC number \NC select a new font from the local \type {fonts} table\NC\NR +\NC char \NC 1 \NC number \NC typeset this character number from the current font, + and move right by the character's width\NC\NR +\NC node \NC 1 \NC node \NC output this node (list), and move right + by the width of this list\NC\NR +\NC slot \NC 2 \NC number \NC a shortcut for the combination of a font and char command\NC\NR +\NC push \NC 0 \NC \NC save current position\NC\NR +\NC nop \NC 0 \NC \NC do nothing \NC\NR +\NC pop \NC 0 \NC \NC pop position \NC\NR +\NC rule \NC 2 \NC 2 numbers \NC output a rule $ht*wd$, and move right.\NC\NR +\NC down \NC 1 \NC number \NC move down on the page\NC\NR +\NC right \NC 1 \NC number \NC move right on the page\NC\NR +\NC special \NC 1 \NC string \NC output a \type {\special} command\NC\NR +\NC lua \NC 1 \NC string \NC execute a \LUA\ script (at \type {\latelua} time)\NC\NR +\NC 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 +\NC comment \NC any \NC any \NC the arguments of this command are ignored\NC\NR \stoptabulate When a font id is set to~0 then it will be replaced by the currently assigned @@ -612,12 +555,162 @@ Finally, here is a plain \TEX\ input file with a virtual font demonstration: } \font\myfont = cmr10-red at 10pt \myfont This is a line of text \par -\font\myfontx= cmr10 at 10pt \myfontx Here is another line of text \par +\font\myfontx= cmr10 at 10pt \myfontx Here is another line of text \par \stopbuffer \typebuffer -% \getbuffer +\section{The \type {font} library} + +The font library provides the interface into the internals of the font system, +and also it contains helper functions to load traditional \TEX\ font metrics +formats. Other font loading functionality is provided by the \type {fontloader} +library that will be discussed in the next section. + +\subsection{Loading a \TFM\ file} + +The behavior documented in this subsection is considered stable in the sense that +there will not be backward-incompatible changes any more. + +\startfunctioncall +<table> fnt = + font.read_tfm(<string> name, <number> s) +\stopfunctioncall + +The number is a bit special: + +\startitemize +\startitem + If it is positive, it specifies an \quote {at size} in scaled points. +\stopitem +\startitem + If it is negative, its absolute value represents a \quote {scaled} + setting relative to the designsize of the font. +\stopitem +\stopitemize + +The internal structure of the metrics font table that is returned is explained in +\in {chapter} [fonts]. + +\subsection{Loading a \VF\ file} + +The behavior documented in this subsection is considered stable in the sense that +there will not be backward-incompatible changes any more. + +\startfunctioncall +<table> vf_fnt = + font.read_vf(<string> name, <number> s) +\stopfunctioncall + +The meaning of the number \type {s} and the format of the returned table are +similar to the ones in the \type {read_tfm()} function. + +\subsection{The fonts array} + +The whole table of \TEX\ fonts is accessible from \LUA\ using a virtual array. + +\starttyping +font.fonts[n] = { ... } +<table> f = font.fonts[n] +\stoptyping + +See \in {chapter} [fonts] for the structure of the tables. Because this is a +virtual array, you cannot call \type {pairs} on it, but see below for the \type +{font.each} iterator. + +The two metatable functions implementing the virtual array are: + +\startfunctioncall +<table> f = font.getfont(<number> n) +font.setfont(<number> n, <table> f) +\stopfunctioncall + +Note that at the moment, each access to the \type {font.fonts} or call to \type +{font.getfont} creates a \LUA\ table for the whole font. This process can be quite +slow. In a later version of \LUATEX, this interface will change (it will start +using userdata objects instead of actual tables). + +Also note the following: assignments can only be made to fonts that have already +been defined in \TEX, but have not been accessed {\it at all\/} since that +definition. This limits the usability of the write access to \type {font.fonts} +quite a lot, a less stringent ruleset will likely be implemented later. + +\subsection{Checking a font's status} + +You can test for the status of a font by calling this function: + +\startfunctioncall +<boolean> f = + font.frozen(<number> n) +\stopfunctioncall + +The return value is one of \type {true} (unassignable), \type {false} (can be +changed) or \type {nil} (not a valid font at all). + +\subsection{Defining a font directly} + +You can define your own font into \type {font.fonts} by calling this function: + +\startfunctioncall +<number> i = + font.define(<table> f) +\stopfunctioncall + +The return value is the internal id number of the defined font (the index into +\type {font.fonts}). If the font creation fails, an error is raised. The table +is a font structure, as explained in \in {chapter} [fonts]. + +\subsection{Projected next font id} + +\startfunctioncall +<number> i = + font.nextid() +\stopfunctioncall + +This returns the font id number that would be returned by a \type {font.define} +call if it was executed at this spot in the code flow. This is useful for virtual +fonts that need to reference themselves. + +\subsection{Font id} + +\startfunctioncall +<number> i = + font.id(<string> csname) +\stopfunctioncall + +This returns the font id associated with \type {csname} string, or $-1$ if \type +{csname} is not defined. + +\subsection{Currently active font} + +\startfunctioncall +<number> i = font.current() +font.current(<number> i) +\stopfunctioncall + +This gets or sets the currently used font number. + +\subsection{Maximum font id} + +\startfunctioncall +<number> i = + font.max() +\stopfunctioncall + +This is the largest used index in \type {font.fonts}. + +\subsection{Iterating over all fonts} + +\startfunctioncall +for i,v in font.each() do + ... +end +\stopfunctioncall + +This is an iterator over each of the defined \TEX\ fonts. The first returned +value is the index in \type {font.fonts}, the second the font itself, as a \LUA\ +table. The indices are listed incrementally, but they do not always form an array +of consecutive numbers: in some cases there can be holes in the sequence. \stopchapter |