2016-04-10 23:57:00

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