2018-04-19 16:02:00

1 files changed, 105 insertions, 83 deletions

diff --git a/doc/context/sources/general/manuals/luatex/luatex-fonts.tex b/doc/context/sources/general/manuals/luatex/luatex-fonts.tex
index d3932a30b..8480d7f2f 100644
--- a/doc/context/sources/general/manuals/luatex/luatex-fonts.tex
+++ b/doc/context/sources/general/manuals/luatex/luatex-fonts.tex
@@ -8,22 +8,24 @@
 
 \section {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|pl|]
 \DB key                     \BC vf  \BC tfm \BC used \BC value type \BC description \NC \NR
-\TB[small,samepage]
+\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,24 +44,21 @@ 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{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
@@ -88,18 +87,18 @@ The top|-|level keys in the table are as follows:
 \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
@@ -126,11 +125,12 @@ possibilities:
 
 \starttabulate[|Tc|c|Tc|c|Tc|c|Tc|c|]
 \DB \# \BC dir \BC \# \BC dir \BC \# \BC dir \BC \# \BC dir \NC \NR
-\TB[small,samepage]
+\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
@@ -148,7 +148,7 @@ The names and their internal remapping are:
 
 \starttabulate[|l|c|]
 \DB name                  \BC remapping \NC \NR
-\TB[small,samepage]
+\TB
 \NC \type {slant}         \NC 1 \NC \NR
 \NC \type {space}         \NC 2 \NC \NR
 \NC \type {space_stretch} \NC 3 \NC \NR
@@ -156,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
@@ -198,16 +199,16 @@ The following top|-|level keys can be present inside a character hash:
 
 \starttabulate[|l|c|c|c|l|p|]
 \DB key                     \BC vf  \BC tfm \BC used  \BC type    \BC description \NC\NR
-\TB[small,samepage]
+\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
@@ -220,23 +221,21 @@ The following top|-|level keys can be present inside a character hash:
 \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
+\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.
+\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 \type {\adjustspacing}.
+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}
-entry for the \PDF\ font (or font subset) based on the character|-|level \type
-{tounicode} strings, where they are available. If a character does not have a
+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}
+entry for the \PDF\ font (or font subset) based on the character|-|level \type {tounicode} strings, where they are available. If a character does not have a
 sensible \UNICODE\ equivalent, do not provide a string either (no empty strings).
 
-If the font level \type {tounicode} is not set, then \LUATEX\ will build up \type
-{/ToUnicode} based on the \TEX\ code points you used, and any character-level
+If the font level \type {tounicode} is not set, then \LUATEX\ will build up \type {/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. For instance the \type {tounicode} for a \type {fi}
@@ -251,11 +250,12 @@ very simple:
 
 \starttabulate[|l|l|p|]
 \DB key        \BC type   \BC description                \NC\NR
-\TB[small,samepage]
+\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.
@@ -263,7 +263,7 @@ Each of those components is itself a hash of up to five keys:
 
 \starttabulate[|l|l|p|]
 \DB key             \BC type   \BC explanation \NC \NR
-\TB[small,samepage]
+\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
@@ -271,6 +271,7 @@ 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
@@ -285,24 +286,24 @@ two fields:
 
 \starttabulate[|l|l|p|]
 \DB key         \BC type   \BC description \NC \NR
-\TB[small,samepage]
+\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|]
 \DB textual (Knuth)       \BC number \BC string        \BC result      \NC\NR
-\TB[small,samepage]
+\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
@@ -311,6 +312,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}
@@ -321,6 +323,9 @@ The \type {commands} array is explained below.
 
 \section {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
 structure. If the value is \type {real}, then this is a proper font, and the
@@ -329,9 +334,10 @@ inclusion mechanism will attempt to add the needed font object definitions to th
 
 \starttabulate[|l|p|]
 \DB value          \BC description            \NC\NR
-\TB[small,samepage]
+\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:
@@ -363,9 +369,7 @@ If no special care is needed, \LUATEX\ falls back to the mapfile|-|based solutio
 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.
+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
@@ -373,28 +377,29 @@ encoding options.
 
 \starttabulate[|l|p|]
 \DB value           \BC description                                               \NC \NR
-\TB[small,samepage]
+\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
 
 Valid values for the \type {embedding} variable are:
 
 \starttabulate[|l|p|]
 \DB value         \BC description                             \NC \NR
-\TB[small,samepage]
+\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
 \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}
-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
+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_*_file}
 callback in that case.
 
@@ -418,8 +423,10 @@ viewers handle this right so take \ACROBAT\ as reference.
 
 \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
@@ -474,7 +481,7 @@ parameters to that command. The allowed commands and their arguments are:
 
 \starttabulate[|l|l|l|p|]
 \DB command        \BC arguments \BC type      \BC description \NC \NR
-\TB[small,samepage]
+\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
@@ -487,16 +494,16 @@ 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,
                                      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{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
@@ -513,13 +520,14 @@ from \PDFTEX.
 
 \starttabulate[|l|p|]
 \DB mode           \BC description \NC \NR
-\TB[small,samepage]
+\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
@@ -580,6 +588,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
@@ -621,15 +631,16 @@ Finally, here is a plain \TEX\ input file with a virtual font demonstration:
 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.
 
 \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
 formats. Other font loading functionality is provided by the \type {fontloader}
@@ -637,6 +648,8 @@ library that will be discussed in the next section.
 
 \subsection{Loading a \TFM\ file}
 
+\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.
 
@@ -662,6 +675,8 @@ The internal structure of the metrics font table that is returned is explained i
 
 \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.
 
@@ -675,6 +690,8 @@ 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
@@ -683,8 +700,7 @@ 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.
+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:
 
@@ -693,8 +709,7 @@ The two metatable functions implementing the virtual array are:
 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
+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).
 
@@ -717,6 +732,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
@@ -738,6 +755,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.
 
@@ -755,6 +774,8 @@ a more drastic replacer.)
 
 \subsection{Projected next font id}
 
+\topicindex {fonts+id}
+
 \startfunctioncall
 <number> i =
     font.nextid()
@@ -771,36 +792,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
   ...