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 | 497 |
1 files changed, 273 insertions, 224 deletions
diff --git a/doc/context/sources/general/manuals/luatex/luatex-fonts.tex b/doc/context/sources/general/manuals/luatex/luatex-fonts.tex index ddb64d946..d49c63afe 100644 --- a/doc/context/sources/general/manuals/luatex/luatex-fonts.tex +++ b/doc/context/sources/general/manuals/luatex/luatex-fonts.tex @@ -1,29 +1,31 @@ % language=uk \environment luatex-style -\environment luatex-logos \startcomponent luatex-fonts \startchapter[reference=fonts,title={Font structure}] -\section {The font tables} +\startsection[title={The font tables}] + +\topicindex {fonts} +\topicindex {fonts+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} +structure if they are present in the table returned by the \cbk {define_font} callback, or if they result from the normal \TFM|/|\VF\ reading routines if there -is no \type {define_font} callback defined. +is no \cbk {define_font} callback defined. 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: +\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[|l|c|c|c|l|p|] -\BC key \BC vf \BC tfm \BC used \BC value type \BC description \NC \NR +\starttabulate[|l|c|c|c|l|pl|] +\DB key \BC vf \BC tfm \BC used \BC value type \BC description \NC \NR +\TB \NC \type{name} \NC yes \NC yes \NC yes \NC string \NC metric (file) name \NC \NR \NC \type{area} \NC no \NC yes \NC yes \NC string \NC (directory) location, typically empty \NC \NR \NC \type{used} \NC no \NC yes \NC yes \NC boolean \NC indicates usage (initial: false) \NC \NR @@ -42,52 +44,61 @@ The top|-|level keys in the table are as follows: \NC \type{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 \type{header} \NC yes \NC no \NC no \NC string \NC header comments, if any \NC \NR -\NC \type{hyphenchar} \NC no \NC no \NC yes \NC number \NC default: \TEX's \type {\hyphenchar} \NC \NR +\NC \type{hyphenchar} \NC no \NC no \NC yes \NC number \NC default: \TEX's \prm {hyphenchar} \NC \NR \NC \type{parameters} \NC no \NC yes \NC yes \NC hash \NC default: 7 parameters, all zero \NC \NR -\NC \type{size} \NC no \NC yes \NC yes \NC number \NC loaded (at) size. (default: same as designsize) \NC \NR -\NC \type{skewchar} \NC no \NC no \NC yes \NC number \NC default: \TEX's \type {\skewchar} \NC \NR +\NC \type{size} \NC no \NC yes \NC yes \NC number \NC the required scaling (by default the same as designsize) \NC \NR +\NC \type{skewchar} \NC no \NC no \NC yes \NC number \NC default: \TEX's \prm {skewchar} \NC \NR \NC \type{type} \NC yes \NC no \NC yes \NC string \NC basic type of this font \NC \NR \NC \type{format} \NC no \NC no \NC yes \NC string \NC disk format type \NC \NR \NC \type{embedding} \NC no \NC no \NC yes \NC string \NC \PDF\ inclusion \NC \NR \NC \type{filename} \NC no \NC no \NC yes \NC string \NC the name of the font on disk \NC \NR \NC \type{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 \type{stretch} \NC no \NC no \NC yes \NC number \NC the \quote {stretch} value from \type - {\expandglyphsinfont} \NC \NR -\NC \type{shrink} \NC no \NC no \NC yes \NC number \NC the \quote {shrink} value from \type - {\expandglyphsinfont} \NC \NR -\NC \type{step} \NC no \NC no \NC yes \NC number \NC the \quote {step} value from \type - {\expandglyphsinfont} \NC \NR +\NC \type{stretch} \NC no \NC no \NC yes \NC number \NC the \quote {stretch} value from \lpr {expandglyphsinfont} \NC \NR +\NC \type{shrink} \NC no \NC no \NC yes \NC number \NC the \quote {shrink} value from \lpr {expandglyphsinfont} \NC \NR +\NC \type{step} \NC no \NC no \NC yes \NC number \NC the \quote {step} value from \lpr {expandglyphsinfont} \NC \NR \NC \type{expansion_factor} \NC no \NC no \NC no \NC number \NC the actual expansion factor of an expanded font \NC \NR -\NC \type{attributes} \NC no \NC no \NC yes \NC string \NC the \type {\pdffontattr} \NC \NR +\NC \type{attributes} \NC no \NC no \NC yes \NC string \NC the \orm {pdffontattr} \NC \NR \NC \type{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 + default), and \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 + created at the first access to one of its fields in the + font. \NC \NR \NC \type{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 \type{oldmath} \NC no \NC no \NC yes \NC boolean \NC This key flags a font as representing an old school \TEX\ math font and disables the \OPENTYPE\ code path. \NC \NR -\NC \type{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 \type{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 +\NC \type{slant} \NC no \NC no \NC yes \NC number \NC This parameter will tilt the font and + does the same as \type {SlantFont} in the map file for + \TYPEONE\ fonts. \NC \NR +\NC \type{extend} \NC no \NC no \NC yes \NC number \NC This parameter will scale the font horizontally and + does the same as \type {ExtendFont} in the map file for + \TYPEONE\ fonts. \NC \NR +\NC \type{squeeze} \NC no \NC no \NC yes \NC number \NC This parameter will scale the font vertically and has + no equivalent in the map file. \NC \NR +\NC \type{width} \NC no \NC no \NC yes \NC number \NC The backend will inject \PDF\ operators that set the + penwidth. The value is (as usual in \TEX) divided by 1000. + It works with the \type {mode} file. \NC \NR +\NC \type{mode} \NC no \NC no \NC yes \NC number \NC The backend will inject \PDF\ operators that relate to the + drawing mode with 0~being a fill, 1~being an outline, + 2~both draw and fill and 3~no painting at all. \NC \NR +\LL \stoptabulate +The saved reference in the \type {cache} option 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. + The key \type {name} is always required. The keys \type {stretch}, \type {shrink}, \type {step} only have meaning when used together: they can be used to -replace a post|-|loading \type {\expandglyphsinfont} command. The \type -{auto_expand} option is not supported in \LUATEX. In fact, the primitives -that create expanded or protruding copies are probably only useful when used with +replace a post|-|loading \lpr {expandglyphsinfont} command. The \type +{auto_expand} option is not supported in \LUATEX. In fact, the primitives that +create expanded or protruding copies are probably only useful when used with traditional fonts because all these extra \OPENTYPE\ properties are kept out of the picture. The \type {expansion_factor} is value that can be present inside a font in \type {font.fonts}. It is the actual expansion factor (a value between @@ -112,16 +123,14 @@ makes sure that the font's definition is written to the output file (\DVI\ or signalling the \quote {normal} direction for this font. There are sixteen possibilities: -\starttabulate[|c|c|c|c|] -\BC number \BC meaning \BC number \BC meaning \NC \NR -\NC \type{0} \NC \type{LT} \NC \type {8} \NC \type{TT} \NC \NR -\NC \type{1} \NC \type{LL} \NC \type {9} \NC \type{TL} \NC \NR -\NC \type{2} \NC \type{LB} \NC \type{10} \NC \type{TB} \NC \NR -\NC \type{3} \NC \type{LR} \NC \type{11} \NC \type{TR} \NC \NR -\NC \type{4} \NC \type{RT} \NC \type{12} \NC \type{BT} \NC \NR -\NC \type{5} \NC \type{RL} \NC \type{13} \NC \type{BL} \NC \NR -\NC \type{6} \NC \type{RB} \NC \type{14} \NC \type{BB} \NC \NR -\NC \type{7} \NC \type{RR} \NC \type{15} \NC \type{BR} \NC \NR +\starttabulate[|Tc|c|Tc|c|Tc|c|Tc|c|] +\DB \# \BC dir \BC \# \BC dir \BC \# \BC dir \BC \# \BC dir \NC \NR +\TB +\NC 0 \NC LT \NC 4 \NC RT \NC 8 \NC TT \NC 12 \NC BT \NC \NR +\NC 1 \NC LL \NC 5 \NC RL \NC 9 \NC TL \NC 13 \NC BL \NC \NR +\NC 2 \NC LB \NC 6 \NC RB \NC 10 \NC TB \NC 14 \NC BB \NC \NR +\NC 3 \NC LR \NC 7 \NC RR \NC 11 \NC TR \NC 15 \NC BR \NC \NR +\LL \stoptabulate These are \OMEGA|-|style direction abbreviations: the first character indicates @@ -138,7 +147,8 @@ gives a nicer user interface. The names and their internal remapping are: \starttabulate[|l|c|] -\BC name \BC remapping \NC \NR +\DB name \BC remapping \NC \NR +\TB \NC \type {slant} \NC 1 \NC \NR \NC \type {space} \NC 2 \NC \NR \NC \type {space_stretch} \NC 3 \NC \NR @@ -146,6 +156,7 @@ The names and their internal remapping are: \NC \type {x_height} \NC 5 \NC \NR \NC \type {quad} \NC 6 \NC \NR \NC \type {extra_space} \NC 7 \NC \NR +\LL \stoptabulate The keys \type {type}, \type {format}, \type {embedding}, \type {fullname} and @@ -159,37 +170,27 @@ 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). -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 \type {cmr10 at 10pt}: +{f} (decimal 102) in the font \type {cmr10 at 10pt}. The numbers that represent +dimensions are in scaled points. \starttyping [102] = { - ['width'] = 200250, - ['height'] = 455111, - ['depth'] = 0, - ['italic'] = 50973, - ['kerns'] = { + ["width"] = 200250, + ["height"] = 455111, + ["depth"] = 0, + ["italic"] = 50973, + ["kerns"] = { [63] = 50973, [93] = 50973, [39] = 50973, [33] = 50973, [41] = 50973 }, - ['ligatures'] = { - [102] = { - ['char'] = 11, - ['type'] = 0 - }, - [108] = { - ['char'] = 13, - ['type'] = 0 - }, - [105] = { - ['char'] = 12, - ['type'] = 0 - } + ["ligatures"] = { + [102] = { ["char"] = 11, ["type"] = 0 }, + [108] = { ["char"] = 13, ["type"] = 0 }, + [105] = { ["char"] = 12, ["type"] = 0 } } } \stoptyping @@ -197,16 +198,17 @@ 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[|l|c|c|c|l|p|] -\BC key \BC vf \BC tfm \BC used \BC type \BC description \NC\NR +\DB key \BC vf \BC tfm \BC used \BC type \BC description \NC\NR +\TB \NC \type{width} \NC yes \NC yes \NC yes \NC number \NC character's width, in sp (default 0) \NC\NR \NC \type{height} \NC no \NC yes \NC yes \NC number \NC character's height, in sp (default 0) \NC\NR \NC \type{depth} \NC no \NC yes \NC yes \NC number \NC character's depth, in sp (default 0) \NC\NR \NC \type{italic} \NC no \NC yes \NC yes \NC number \NC character's italic correction, in sp (default zero) \NC\NR \NC \type{top_accent} \NC no \NC no \NC maybe \NC number \NC character's top accent alignment place, in sp (default zero) \NC\NR \NC \type{bot_accent} \NC no \NC no \NC maybe \NC number \NC character's bottom accent alignment place, in sp (default zero) \NC\NR -\NC \type{left_protruding} \NC no \NC no \NC maybe \NC number \NC character's \type {\lpcode} \NC\NR -\NC \type{right_protruding} \NC no \NC no \NC maybe \NC number \NC character's \type {\rpcode} \NC\NR -\NC \type{expansion_factor} \NC no \NC no \NC maybe \NC number \NC character's \type {\efcode} \NC\NR +\NC \type{left_protruding} \NC no \NC no \NC maybe \NC number \NC character's \lpr {lpcode} \NC\NR +\NC \type{right_protruding} \NC no \NC no \NC maybe \NC number \NC character's \lpr {rpcode} \NC\NR +\NC \type{expansion_factor} \NC no \NC no \NC maybe \NC number \NC character's \lpr {efcode} \NC\NR \NC \type{tounicode} \NC no \NC no \NC maybe \NC string \NC character's \UNICODE\ equivalent(s), in \UTF|-|16BE hexadecimal format \NC\NR \NC \type{next} \NC no \NC yes \NC yes \NC number \NC the \quote {next larger} character index \NC\NR \NC \type{extensible} \NC no \NC yes \NC yes \NC table \NC the constituent parts of an extensible recipe \NC\NR @@ -217,19 +219,17 @@ The following top|-|level keys can be present inside a character hash: \NC \type{commands} \NC yes \NC no \NC yes \NC array \NC virtual font commands \NC\NR \NC \type{name} \NC no \NC no \NC no \NC string \NC the character (\POSTSCRIPT) name \NC\NR \NC \type{index} \NC no \NC no \NC yes \NC number \NC the (\OPENTYPE\ or \TRUETYPE) font glyph index \NC\NR -\NC \type{used} \NC no \NC yes \NC yes \NC boolean \NC typeset already (default: false)? \NC\NR +\NC \type{used} \NC no \NC yes \NC yes \NC boolean \NC typeset already (default: false) \NC\NR \NC \type{mathkern} \NC no \NC no \NC yes \NC table \NC math cut-in specifications \NC\NR +\LL \stoptabulate The values of \type {top_accent}, \type {bot_accent} and \type {mathkern} are -used only for math accent and superscript placement, see the \at {math chapter} -[math] in this manual for details. - -The values of \type {left_protruding} and \type {right_protruding} are used only -when \type {\protrudechars} is non-zero. - -Whether or not \type {expansion_factor} is used depends on the font's global -expansion settings, as well as on the value of \type {\adjustspacing}. +used only for math accent and superscript placement, see \at {page} [math] in +this manual for details. The values of \type {left_protruding} and \type +{right_protruding} are used only when \lpr {protrudechars} is non-zero. Whether +or not \type {expansion_factor} is used depends on the font's global expansion +settings, as well as on the value of \lpr {adjustspacing}. The usage of \type {tounicode} is this: if this font specifies a \type {tounicode=1} at the top level, then \LUATEX\ will construct a \type {/ToUnicode} @@ -245,24 +245,28 @@ 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. -The presence of \type {extensible} will overrule \type {next}, if that is also -present. It in in turn can be overruled by \type {vert_variants}. - -The \type {extensible} table is very simple: +A math character can have a \type {next} field that points to a next larger +shape. However, the presence of \type {extensible} will overrule \type {next}, if +that is also present. The \type {extensible} field in turn can be overruled by +\type {vert_variants}, the \OPENTYPE\ version. The \type {extensible} table is +very simple: \starttabulate[|l|l|p|] -\BC key \BC type \BC description \NC\NR +\DB key \BC type \BC description \NC\NR +\TB \NC \type{top} \NC number \NC top character index \NC\NR \NC \type{mid} \NC number \NC middle character index \NC\NR \NC \type{bot} \NC number \NC bottom character index \NC\NR \NC \type{rep} \NC number \NC repeatable character index \NC\NR +\LL \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[|l|l|p|] -\BC key \BC type \BC explanation \NC \NR +\DB key \BC type \BC explanation \NC \NR +\TB \NC \type{glyph} \NC number \NC The character index. Note that this is an encoding number, not a name. \NC \NR \NC \type{extender} \NC number \NC One (1) if this part is repeatable, zero (0) otherwise. \NC \NR \NC \type{start} \NC number \NC The maximum overlap at the starting side (in scaled points). \NC \NR @@ -270,11 +274,12 @@ Each of those components is itself a hash of up to five keys: \NC \type{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 +\LL \stoptabulate The \type {kerns} table is a hash indexed by character index (and \quote {character index} is defined as either a non|-|negative integer or the string -value \type {right_boundary}), with the values the kerning to be applied, in +value \type {right_boundary}), with the values of the kerning to be applied, in scaled points. The \type {ligatures} table is a hash indexed by character index (and \quote @@ -283,23 +288,25 @@ value \type {right_boundary}), with the values being yet another small hash, wit two fields: \starttabulate[|l|l|p|] -\BC key \BC type \BC description \NC \NR +\DB key \BC type \BC description \NC \NR +\TB \NC \type{type} \NC number \NC the type of this ligature command, default 0 \NC \NR \NC \type{char} \NC number \NC the character index of the resultant ligature \NC \NR +\LL \stoptabulate -The \type {char} field in a ligature is required. - -The \type {type} field inside a ligature is the numerical or string value of one -of the eight possible ligature types supported by \TEX. When \TEX\ inserts a new -ligature, it puts the new glyph in the middle of the left and right glyphs. The -original left and right glyphs can optionally be retained, and when at least one -of them is kept, it is also possible to move the new \quote {insertion point} -forward one or two places. The glyph that ends up to the right of the insertion -point will become the next \quote {left}. +The \type {char} field in a ligature is required. The \type {type} field inside a +ligature is the numerical or string value of one of the eight possible ligature +types supported by \TEX. When \TEX\ inserts a new ligature, it puts the new glyph +in the middle of the left and right glyphs. The original left and right glyphs +can optionally be retained, and when at least one of them is kept, it is also +possible to move the new \quote {insertion point} 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|] -\BC textual (Knuth) \BC number \BC string \BC result \NC\NR +\DB textual (Knuth) \BC number \BC string \BC result \NC\NR +\TB \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 @@ -308,6 +315,7 @@ point will become the next \quote {left}. \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 +\LL \stoptabulate The default value is~0, and can be left out. That signifies a \quote {normal} @@ -316,7 +324,12 @@ indicates the final insertion point. The \type {commands} array is explained below. -\section {Real fonts} +\stopsection + +\startsection[title={Real fonts}] + +\topicindex {fonts+real} +\topicindex {fonts+virtual} Whether or not a \TEX\ font is a \quote {real} font that should be written to the \PDF\ document is decided by the \type {type} value in the top|-|level font @@ -325,141 +338,150 @@ inclusion mechanism will attempt to add the needed font object definitions to th \PDF. Values for \type {type} are: \starttabulate[|l|p|] -\BC value \BC description \NC\NR +\DB value \BC description \NC\NR +\TB \NC \type{real} \NC this is a base font \NC\NR \NC \type{virtual} \NC this is a virtual font \NC\NR +\LL \stoptabulate The actions to be taken depend on a number of different variables: \startitemize[packed] \startitem - Whether the used font fits in an 8-bit encoding scheme or not. + Whether the used font fits in an 8-bit encoding scheme or not. This is true for + traditional \TEX\ fonts that communicate via \TFM\ files. \stopitem \startitem - The type of the disk font file. + The type of the disk font file, for instance a bitmap file or an outline + \TYPEONE, \TRUETYPE\ or \OPENTYPE\ font. \stopitem \startitem - The level of embedding requested. + The level of embedding requested, although in most cases a subset of + characters is embedded. The times when nothing got embedded are (in our + opinion at least) basically gone. \stopitem \stopitemize A font that uses anything other than an 8-bit encoding vector has to be written -to the \PDF\ in a different way. - -The rule is: if the font table has \type {encodingbytes} set to~2, then this is a -wide font, in all other cases it isn't. The value~2 is the default for \OPENTYPE\ -and \TRUETYPE\ fonts loaded via \LUA. For \TYPEONE\ fonts, you have to set \type -{encodingbytes} to~2 explicitly. For \PK\ bitmap fonts, wide font encoding is not -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 might -silently be removed in the future, in which case the related primitives and \LUA\ -functions will become no|-|ops. - -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. - -The extra fields are: \type {format}, \type {embedding}, \type {fullname}, \type -{cidinfo} (as explained above), \type {filename}, and the \type {index} key in -the separate characters. - -Values for \type {format} are: +to the \PDF\ in a different way. When the font table has \type {encodingbytes} +set to~2, then it is a wide font, in all other cases it isn't. The value~2 is the +default for \OPENTYPE\ and \TRUETYPE\ fonts loaded via \LUA. For \TYPEONE\ fonts, +you have to set \type {encodingbytes} to~2 explicitly. For \PK\ bitmap fonts, +wide font encoding is not supported at all. + +If no special care is needed, \LUATEX\ falls back to the mapfile|-|based solution +used by \PDFTEX\ and \DVIPS, so that legacy fonts are supported transparently. 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. These extra fields are: \type {format}, \type {embedding}, \type +{fullname}, \type {cidinfo} (as explained above), \type {filename}, and the \type +{index} key in the separate characters. + +The \type {format} variable can have the following values. \type {type3} fonts +are provided for backward compatibility only, and do not support the new wide +encoding options. \starttabulate[|l|p|] -\BC value \BC description \NC \NR +\DB value \BC description \NC \NR +\TB \NC \type{type1} \NC this is a \POSTSCRIPT\ \TYPEONE\ font \NC \NR \NC \type{type3} \NC this is a bitmapped (\PK) font \NC \NR \NC \type{truetype} \NC this is a \TRUETYPE\ or \TRUETYPE|-|based \OPENTYPE\ font \NC \NR \NC \type{opentype} \NC this is a \POSTSCRIPT|-|based \OPENTYPE\ font \NC \NR +\LL \stoptabulate -\type {type3} fonts are provided for backward compatibility only, and do not -support the new wide encoding options. - -Values for \type {embedding} are: +Valid values for the \type {embedding} variable are: \starttabulate[|l|p|] -\BC value \BC description \NC \NR +\DB value \BC description \NC \NR +\TB \NC \type{no} \NC don't embed the font at all \NC \NR \NC \type{subset} \NC include and atttempt to subset the font \NC \NR \NC \type{full} \NC include this font in its entirety \NC \NR +\LL \stoptabulate -The other fields are used as follows: The \type {fullname} will be the +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} +set: the CID \type {/Ordering} and \type {/Registry} keys. The \type {filename} points to the actual font file. If you include the full path in the \type {filename} or if the file is in the local directory, \LUATEX\ will run a little -bit more efficient because it will not have to re|-|run the \type {find_xxx_file} +bit more efficient because it will not have to re|-|run the \type {find_*_file} callback in that case. Be careful: when mixing old and new fonts in one document, it is possible to create \POSTSCRIPT\ name clashes that can result in printing errors. When this -happens, you have to change the \type {fullname} of the font. +happens, you have to change the \type {fullname} of the font to a more unique +one. 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} and use the table -indices as \type {index} fields. +name|-|based reencoding. One way to get the correct \type {index} numbers for +\TYPEONE\ fonts is by loading the font via \type {fontloader.open} and use the +table indices as \type {index} fields. 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. +best make sure that there is a \type {tounicode} vector enforced. Not all \PDF\ +viewers handle this right so take \ACROBAT\ as reference. + +\stopsection -\section[virtualfonts]{Virtual fonts} +\startsection[reference=virtualfonts,title={Virtual fonts}] \subsection{The structure} +\topicindex {fonts+virtual} + You have to take the following steps if you want \LUATEX\ to treat the returned -table from \type {define_font} as a virtual font: +table from \cbk {define_font} as a virtual font: \startitemize[packed] \startitem - Set the top|-|level key \type {type} to \type {virtual}. + Set the top|-|level key \type {type} to \type {virtual}. In most cases it's + optional because we look at the \type {commands} entry anyway. \stopitem \startitem - Make sure there is at least one valid entry in \type {fonts} (see below). + Make sure there is at least one valid entry in \type {fonts} (see below), + although recent versions of \LUATEX\ add a default entry when this table is + missing. \stopitem \startitem - Give a \type {commands} array to every character (see below). + Add a \type {commands} array to those characters that matter. A virtual + character can itself point to virtual characters but be careful with nesting + as you can create loops and overflow the stack (which often indicates an + error anyway). \stopitem \stopitemize The presence of the toplevel \type {type} key with the specific value \type {virtual} will trigger handling of the rest of the special virtual font fields in the table, but the mere existence of 'type' is enough to prevent \LUATEX\ from -looking for a virtual font on its own. - -Therefore, this also works \quote {in reverse}: if you are absolutely certain -that a font is not a virtual font, assigning the value \type {base} or \type -{real} to \type {type} will inhibit \LUATEX\ from looking for a virtual font -file, thereby saving you a disk search. +looking for a virtual font on its own. This also works \quote {in reverse}: if +you are absolutely certain that a font is not a virtual font, assigning the value +\type {real} to \type {type} will inhibit \LUATEX\ from looking for a virtual +font file, thereby saving you a disk search. This only matters when we load a +\TFM\ file. -The \type {fonts} is another \LUA\ array. The values are one- or two|-|key +The \type {fonts} is an (indexed) \LUA\ table. The values are one- or two|-|key hashes themselves, each entry indicating one of the base fonts in a virtual font. In case your font is referring to itself, you can use the \type {font.nextid()} function which returns the index of the next to be defined font which is probably -the currently defined one. - -An example makes this easy to understand +the currently defined one. So, a table looks like this: \starttyping fonts = { - { name = 'ptmr8a', size = 655360 }, - { name = 'psyr', size = 600000 }, - { id = 38 } + { name = "ptmr8a", size = 655360 }, + { name = "psyr", size = 600000 }, + { id = 38 } } \stoptyping -says that the first referenced font (index 1) in this virtual font is \type -{ptrmr8a} loaded at 10pt, and the second is \type {psyr} loaded at a little over -9pt. The third one is previously defined font that is known to \LUATEX\ as font id -\quote {38}. - +The first referenced font (at index~1) in this virtual font is \type {ptrmr8a} +loaded at 10pt, and the second is \type {psyr} loaded at a little over 9pt. The +third one is a previously defined font that is known to \LUATEX\ as font id~38. The array index numbers are used by the character command definitions that are part of each character. @@ -468,7 +490,8 @@ 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[|l|l|l|p|] -\BC command name \BC arguments \BC type \BC description \NC \NR +\DB command \BC arguments \BC type \BC description \NC \NR +\TB \NC \type{font} \NC 1 \NC number \NC select a new font from the local \type {fonts} table \NC \NR \NC \type{char} \NC 1 \NC number \NC typeset this character number from the current font, and move right by the character's width \NC \NR @@ -481,18 +504,20 @@ parameters to that command. The allowed commands and their arguments are: \NC \type{rule} \NC 2 \NC 2 numbers \NC output a rule $ht*wd$, and move right. \NC \NR \NC \type{down} \NC 1 \NC number \NC move down on the page \NC \NR \NC \type{right} \NC 1 \NC number \NC move right on the page \NC \NR -\NC \type{special} \NC 1 \NC string \NC output a \type {\special} command \NC \NR +\NC \type{special} \NC 1 \NC string \NC output a \prm {special} command \NC \NR \NC \type{pdf} \NC 2 \NC 2 strings \NC output a \PDF\ literal, the first string is one of \type {origin}, \type {page}, \type {text}, \type {font}, \type {direct} or \type {raw}; if you have one string only \type {origin} is assumed \NC \NR -\NC \type{lua} \NC 1 \NC string \NC execute a \LUA\ script (at \type {\latelua} time) \NC \NR -\NC \type{image} \NC 1 \NC image \NC output an image (the argument can be either an \type - {<image>} variable or an \type {image_spec} table) \NC \NR +\NC \type{lua} \NC 1 \NC string, + function \NC execute a \LUA\ script when the glyph is embedded; in case of a + function it gets the font id and character code passed \NC \NR +\NC \type{image} \NC 1 \NC image \NC output an image (the argument can be either an \type {<image>} variable or an \type {image_spec} table) \NC \NR \NC \type{comment} \NC any \NC any \NC the arguments of this command are ignored \NC \NR +\LL \stoptabulate When a font id is set to~0 then it will be replaced by the currently assigned -font id. This prevents the need for hackery with future id's (normally one could +font id. This prevents the need for hackery with future id's. Normally one could use \type {font.nextid} but when more complex fonts are built in the meantime other instances could have been loaded. @@ -500,24 +525,24 @@ The \type {pdf} option also accepts a \type {mode} keyword in which case the third argument sets the mode. That option will change the mode in an efficient way (passing an empty string would result in an extra empty lines in the \PDF\ file. This option only makes sense for virtual fonts. The \type {font} mode only -makes sense in virtual fonts. - -These modes are somewhat fuzzy and partially inherited from \PDFTEX. +makes sense in virtual fonts. Modes are somewhat fuzzy and partially inherited +from \PDFTEX. \starttabulate[|l|p|] -\BC mode \BC description \NC \NR +\DB mode \BC description \NC \NR +\TB \NC \type {origin} \NC enter page mode and set the position \NC \NR \NC \type {page} \NC enter page mode \NC \NR \NC \type {text} \NC enter text mode \NC \NR \NC \type {font} \NC enter font mode (kind of text mode, only in virtual fonts) \NC \NR \NC \type {always} \NC finish the current string and force a transform if needed \NC \NR \NC \type {raw} \NC finish the current string \NC \NR +\LL \stoptabulate -You always need to check what \PDF\ code is generated because there can be all kind of -interferences with optimizations in the backend and fonts are complicated anyway. - -Here is a rather elaborate glyph commands example: +You always need to check what \PDF\ code is generated because there can be all +kind of interferences with optimization in the backend and fonts are complicated +anyway. Here is a rather elaborate glyph commands example using such keys: \starttyping ... @@ -526,6 +551,7 @@ commands = { { "right", 5000 }, -- move right about 0.08pt { "font", 3 }, -- select the fonts[3] entry { "char", 97 }, -- place character 97 (ASCII 'a') + -- { "slot", 2, 97 }, -- an alternative for the previous two { "pop" }, -- go all the way back { "down", -200000 }, -- move upwards by about 3pt { "special", "pdf: 1 0 0 rg" } -- switch to red color @@ -539,7 +565,7 @@ commands = { The default value for \type {font} is always~1 at the start of the \type {commands} array. Therefore, if the virtual font is essentially only a -re|-|encoding, then you do usually not have create an explicit \quote {font} +re|-|encoding, then you do usually not have created an explicit \quote {font} command in the array. Rules inside of \type {commands} arrays are built up using only two dimensions: @@ -572,6 +598,8 @@ characters that are already present cannot be altered). \subsection{Example virtual font} +\topicindex {fonts+virtual} + Finally, here is a plain \TEX\ input file with a virtual font demonstration: \startbuffer @@ -579,58 +607,65 @@ Finally, here is a plain \TEX\ input file with a virtual font demonstration: callback.register('define_font', function (name,size) if name == 'cmr10-red' then - f = font.read_tfm('cmr10',size) - f.name = 'cmr10-red' - f.type = 'virtual' - f.fonts = {{ name = 'cmr10', size = size }} + local f = font.read_tfm('cmr10',size) + f.name = 'cmr10-red' + f.type = 'virtual' + f.fonts = { + { name = 'cmr10', size = size } + } for i,v in pairs(f.characters) do - if (string.char(i)):find('[tacohanshartmut]') then + if string.char(i):find('[tacohanshartmut]') then v.commands = { - {'special','pdf: 1 0 0 rg'}, - {'char',i}, - {'special','pdf: 0 g'}, + { "special", "pdf: 1 0 0 rg" }, + { "char", i }, + { "special", "pdf: 0 g" }, } - else - v.commands = {{'char',i}} end end + return f else - f = font.read_tfm(name,size) + return font.read_tfm(name,size) end - return f end ) } -\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\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 \stopbuffer \typebuffer -\section{The \type {vf} library} +\stopsection + +\startsection[title={The \type {vf} library}] The \type {vf} library can be used when \LUA\ code, as defined in the \type {commands} of the font, is executed. The functions provided are similar as the commands: \type {char}, \type {down}, \type {fontid}, \type {image}, \type -{node}, \type {nop}, \type {pop}, \type {push}, \type {right}, \type {rule}, -\type {special} and \type {pdf}. This library has been present for a while but -not been advertised and tested much, if only because it's easy to define an -invalid font (or mess up the \PDF\ stream). Keep in mind that the \LUA\ snippets -are executed each time when a character is output. +{node}, \type {nop}, \type {pop}, \type {push}, \type {right}, \nod {rule}, \type +{special} and \type {pdf}. This library has been present for a while but not been +advertised and tested much, if only because it's easy to define an invalid font +(or mess up the \PDF\ stream). Keep in mind that the \LUA\ snippets are executed +each time when a character is output. + +\stopsection +\startsection[title={The \type {font} library}] -\section{The \type {font} library} +\topicindex {fonts+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 +and it also 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. +\topicindex {fonts+tfm} + +The behaviour documented in this subsection is considered stable in the sense that +there will not be backward|-|incompatible changes any more. \startfunctioncall <table> fnt = @@ -649,11 +684,10 @@ The number is a bit special: \stopitem \stopitemize -The internal structure of the metrics font table that is returned is explained in -\in {chapter} [fonts]. - \subsection{Loading a \VF\ file} +\topicindex {fonts+vf} + The behavior documented in this subsection is considered stable in the sense that there will not be backward-incompatible changes any more. @@ -663,10 +697,12 @@ there will not be backward-incompatible changes any more. \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. +similar to the ones in the \type {read_tfm} function. \subsection{The fonts array} +\topicindex {fonts+virtual} + The whole table of \TEX\ fonts is accessible from \LUA\ using a virtual array. \starttyping @@ -674,9 +710,8 @@ 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. +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: @@ -686,9 +721,15 @@ 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). +{font.getfont} creates a \LUA\ table for the whole font unless you cached it. +This process can be quite slow. + +\startfunctioncall +<table> p = font.getparameters(<number> n) +\stopfunctioncall + +This one will return a table of the parameters as known to \TEX. These can be +different from the ones in the cached table. 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 @@ -709,6 +750,8 @@ changed) or \type {nil} (not a valid font at all). \subsection{Defining a font directly} +\topicindex {fonts+define} + You can define your own font into \type {font.fonts} by calling this function: \startfunctioncall @@ -717,9 +760,8 @@ You can define your own font into \type {font.fonts} by calling this function: \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]. An alternative call -is: +\type {font.fonts}). If the font creation fails, an error is raised. The table is +a font structure. An alternative call is: \startfunctioncall <number> i = @@ -730,6 +772,8 @@ Where the first argument is a reserved font id (see below). \subsection{Extending a font} +\topicindex {fonts+extend} + Within reasonable bounds you can extend a font after it has been defined. Because some properties are best left unchanged this is limited to adding characters. @@ -747,6 +791,8 @@ a more drastic replacer.) \subsection{Projected next font id} +\topicindex {fonts+id} + \startfunctioncall <number> i = font.nextid() @@ -763,36 +809,37 @@ This can be handy when you create complex virtual fonts. font.nextid(true) \stopfunctioncall -\subsection{Font id} +\subsection{Font ids} + +\topicindex {fonts+id} +\topicindex {fonts+current} \startfunctioncall <number> i = font.id(<string> csname) \stopfunctioncall -This returns the font id associated with \type {csname} string, or $-1$ if \type +This returns the font id associated with \type {csname}, or $-1$ if \type {csname} is not defined. -\subsection{Currently active font} - \startfunctioncall -<number> i = font.current() -font.current(<number> i) +<number> i = + font.max() \stopfunctioncall -This gets or sets the currently used font number. - -\subsection{Maximum font id} +This is the largest used index in \type {font.fonts}. \startfunctioncall -<number> i = - font.max() +<number> i = font.current() +font.current(<number> i) \stopfunctioncall -This is the largest used index in \type {font.fonts}. +This gets or sets the currently used font number. \subsection{Iterating over all fonts} +\topicindex {fonts+iterate} + \startfunctioncall for i,v in font.each() do ... @@ -804,6 +851,8 @@ 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. +\stopsection + \stopchapter \stopcomponent |