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 | 464 |
1 files changed, 276 insertions, 188 deletions
diff --git a/doc/context/sources/general/manuals/luatex/luatex-fonts.tex b/doc/context/sources/general/manuals/luatex/luatex-fonts.tex index 221c0ce85..ddb64d946 100644 --- a/doc/context/sources/general/manuals/luatex/luatex-fonts.tex +++ b/doc/context/sources/general/manuals/luatex/luatex-fonts.tex @@ -22,92 +22,106 @@ The column \quote {\VF} means that this key will be created by the \type The top|-|level keys in the table are as follows: -\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. This has to be a valid string, e.g.\ no spaces - and such, as the backend will not do a cleanup. This gives - complete control to the loader. \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 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 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[|l|c|c|c|l|p|] +\BC key \BC vf \BC tfm \BC used \BC value type \BC description \NC \NR +\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 +\NC \type{characters} \NC yes \NC yes \NC yes \NC table \NC the defined glyphs of this font \NC \NR +\NC \type{checksum} \NC yes \NC yes \NC no \NC number \NC default: 0 \NC \NR +\NC \type{designsize} \NC no \NC yes \NC yes \NC number \NC expected size (default: 655360 == 10pt) \NC \NR +\NC \type{direction} \NC no \NC yes \NC yes \NC number \NC default: 0 \NC \NR +\NC \type{encodingbytes} \NC no \NC no \NC yes \NC number \NC default: depends on \type {format} \NC \NR +\NC \type{encodingname} \NC no \NC no \NC yes \NC string \NC encoding name \NC \NR +\NC \type{fonts} \NC yes \NC no \NC yes \NC table \NC locally used fonts \NC \NR +\NC \type{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. This has to be a valid string, e.g.\ no spaces + and such, as the backend will not do a cleanup. This gives + complete control to the loader. \NC \NR +\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{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{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{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{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 \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 \stoptabulate The key \type {name} is always required. The keys \type {stretch}, \type -{shrink}, \type {step} and optionally \type {auto_expand} only have meaning when -used together: they can be used to replace a post|-|loading \type -{\expandglyphsinfont} command. 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 \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 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 +{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 +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 +\type {-shrink} and \type {stretch}, with step \type {step}) of a font that was +automatically generated by the font expansion algorithm. + +Because we store the actual state of expansion with each glyph and don't have +special font instances, we can change some font related parameters before lines +are constructed, like: + +\starttyping +font.setexpansion(font.current(),100,100,20) +\stoptyping + +This is mostly meant for experiments (or an optimizing routing written in \LUA) +so there is no primitive. + +The key \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[|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 \stoptabulate These are \OMEGA|-|style direction abbreviations: the first character indicates @@ -123,15 +137,15 @@ gives a nicer user interface. The names and their internal remapping are: -\starttabulate[|lT|c|] -\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 -\NC space_shrink \NC 4 \NC\NR -\NC x_height \NC 5 \NC\NR -\NC quad \NC 6 \NC\NR -\NC extra_space \NC 7 \NC\LR +\starttabulate[|l|c|] +\BC name \BC remapping \NC \NR +\NC \type {slant} \NC 1 \NC \NR +\NC \type {space} \NC 2 \NC \NR +\NC \type {space_stretch} \NC 3 \NC \NR +\NC \type {space_shrink} \NC 4 \NC \NR +\NC \type {x_height} \NC 5 \NC \NR +\NC \type {quad} \NC 6 \NC \NR +\NC \type {extra_space} \NC 7 \NC \NR \stoptabulate The keys \type {type}, \type {format}, \type {embedding}, \type {fullname} and @@ -182,29 +196,29 @@ 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 \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 +\starttabulate[|l|c|c|c|l|p|] +\BC key \BC vf \BC tfm \BC used \BC type \BC description \NC\NR +\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{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 +\NC \type{vert_variants} \NC no \NC no \NC yes \NC table \NC constituent parts of a vertical variant set \NC \NR +\NC \type{horiz_variants} \NC no \NC no \NC yes \NC table \NC constituent parts of a horizontal variant set \NC \NR +\NC \type{kerns} \NC no \NC yes \NC yes \NC table \NC kerning information \NC\NR +\NC \type{ligatures} \NC no \NC yes \NC yes \NC table \NC ligaturing information \NC\NR +\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{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 @@ -236,26 +250,26 @@ present. It in in turn can be overruled by \type {vert_variants}. The \type {extensible} table is very simple: -\starttabulate[|lT|l|p|] -\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 +\starttabulate[|l|l|p|] +\BC key \BC type \BC description \NC\NR +\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 \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 \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 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 +\starttabulate[|l|l|p|] +\BC key \BC type \BC explanation \NC \NR +\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 +\NC \type{end} \NC number \NC The maximum overlap at the ending side (in scaled points). \NC \NR +\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 \stoptabulate The \type {kerns} table is a hash indexed by character index (and \quote @@ -268,10 +282,10 @@ The \type {ligatures} table is a hash indexed by character index (and \quote value \type {right_boundary}), with the values being yet another small hash, with two fields: -\starttabulate[|lT|l|p|] -\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 +\starttabulate[|l|l|p|] +\BC key \BC type \BC description \NC \NR +\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 \stoptabulate The \type {char} field in a ligature is required. @@ -285,15 +299,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 +\BC textual (Knuth) \BC number \BC string \BC 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} @@ -310,10 +324,10 @@ 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} are: -\starttabulate[|Tl|p|] -\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 +\starttabulate[|l|p|] +\BC value \BC description \NC\NR +\NC \type{real} \NC this is a base font \NC\NR +\NC \type{virtual} \NC this is a virtual font \NC\NR \stoptabulate The actions to be taken depend on a number of different variables: @@ -354,12 +368,12 @@ the separate characters. Values for \type {format} are: -\starttabulate[|Tl|p|] -\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 -\NC opentype \NC this is a \POSTSCRIPT|-|based \OPENTYPE\ font \NC \NR +\starttabulate[|l|p|] +\BC value \BC description \NC \NR +\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 \stoptabulate \type {type3} fonts are provided for backward compatibility only, and do not @@ -367,11 +381,11 @@ support the new wide encoding options. Values for \type {embedding} are: -\starttabulate[|Tl|p|] -\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 +\starttabulate[|l|p|] +\BC value \BC description \NC \NR +\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 \stoptabulate The other fields are used as follows: The \type {fullname} will be the @@ -453,25 +467,28 @@ The \type {commands} array is a hash where each item is another small array, 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 \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 +\starttabulate[|l|l|l|p|] +\BC command name \BC arguments \BC type \BC description \NC \NR +\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 +\NC \type{node} \NC 1 \NC node \NC output this node (list), and move right + by the width of this list\NC \NR +\NC \type{slot} \NC 2 \NC 2 numbers \NC a shortcut for the combination of a font and char command\NC \NR +\NC \type{push} \NC 0 \NC \NC save current position\NC \NR +\NC \type{nop} \NC 0 \NC \NC do nothing \NC \NR +\NC \type{pop} \NC 0 \NC \NC pop position \NC \NR +\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{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{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 @@ -479,20 +496,43 @@ 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. +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. + +\starttabulate[|l|p|] +\BC mode \BC description \NC \NR +\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 +\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: \starttyping ... commands = { - { 'push' }, -- remember where we are - { 'right', 5000 }, -- move right about 0.08pt - { 'font', 3 }, -- select the fonts[3] entry - { 'char', 97 }, -- place character 97 (ASCII 'a') - { 'pop' }, -- go all the way back - { 'down', -200000 }, -- move upwards by about 3pt - { 'special', 'pdf: 1 0 0 rg' } -- switch to red color - { 'rule', 500000, 20000 } -- draw a bar - { 'special','pdf: 0 g' } -- back to black + { "push" }, -- remember where we are + { "right", 5000 }, -- move right about 0.08pt + { "font", 3 }, -- select the fonts[3] entry + { "char", 97 }, -- place character 97 (ASCII 'a') + { "pop" }, -- go all the way back + { "down", -200000 }, -- move upwards by about 3pt + { "special", "pdf: 1 0 0 rg" } -- switch to red color + -- { "pdf", "origin", "1 0 0 rg" } -- switch to red color (alternative) + { "rule", 500000, 20000 } -- draw a bar + { "special", "pdf: 0 g" } -- back to black + -- { "pdf", "origin", "0 g" } -- back to black (alternative) } ... \stoptyping @@ -511,6 +551,10 @@ output pointer will always move by exactly the width that was given in the \type {width} key of the character hash. Any movements that take place inside the \type {commands} array are ignored on the upper level. +The special can have a \type {pdf:}, \type {pdf:origin:}, \type {pdf:page:}, +\type {pdf:direct:} or \type {pdf:raw:} prefix. When you have to concatenate +strings using the \type {pdf} command might be more efficient. + \subsection{Artificial fonts} Even in a \quote {real} font, there can be virtual characters. When \LUATEX\ @@ -564,6 +608,18 @@ Finally, here is a plain \TEX\ input file with a virtual font demonstration: \typebuffer +\section{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. + + \section{The \type {font} library} The font library provides the interface into the internals of the font system, @@ -662,7 +718,32 @@ You can define your own font into \type {font.fonts} by calling this function: 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]. +is a font structure, as explained in \in {chapter} [fonts]. An alternative call +is: + +\startfunctioncall +<number> i = + font.define(<number> n, <table> f) +\stopfunctioncall + +Where the first argument is a reserved font id (see below). + +\subsection{Extending a font} + +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. + +\startfunctioncall +font.addcharacters(<number n>, <table> f) +\stopfunctioncall + +The table passed can have the fields \type {characters} which is a (sub)table +like the one used in define, and for virtual fonts a \type {fonts} table can be +added. The characters defined in the \type {characters} table are added (when not +yet present) or replace an existing entry. Keep in mind that replacing can have +side effects because a character already can have been used. Instead of posing +restrictions we expect the user to be careful. (The \type {setfont} helper is +a more drastic replacer.) \subsection{Projected next font id} @@ -673,7 +754,14 @@ is a font structure, as explained in \in {chapter} [fonts]. 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. +fonts that need to reference themselves. If you pass \type {true} as argument, +the id gets reserved and you can pass to \type {font.define} as first argument. +This can be handy when you create complex virtual fonts. + +\startfunctioncall +<number> i = + font.nextid(true) +\stopfunctioncall \subsection{Font id} |