2016-04-10 23:57:00

1 files changed, 289 insertions, 215 deletions

diff --git a/doc/context/sources/general/manuals/luatex/luatex-enhancements.tex b/doc/context/sources/general/manuals/luatex/luatex-enhancements.tex
index 37d99a84d..35c27cfb6 100644
--- a/doc/context/sources/general/manuals/luatex/luatex-enhancements.tex
+++ b/doc/context/sources/general/manuals/luatex/luatex-enhancements.tex
@@ -10,9 +10,9 @@
 \section{Introduction}
 
 From day one, \LUATEX\ has offered extra features compared to the superset of
-\PDFTEX\ and \ALEPH. That has not been limited to the possibility to execute
+\PDFTEX\ and \ALEPH. This has not been limited to the possibility to execute
 \LUA\ code via \type {\directlua}, but \LUATEX\ also adds functionality via new
-\TEX-side primitives.
+\TEX|-|side primitives or extensions to existing ones.
 
 When \LUATEX\ starts up in \quote {iniluatex} mode (\type {luatex -ini}), it
 defines only the primitive commands known by \TEX82 and the one extra command
@@ -34,21 +34,27 @@ it may be needed to put these assignments before the above line:
 \catcode `\}=2
 \stoptyping
 
-More fine|-|grained primitives control is possible, you can look up the details in
-\in {section} [luaprimitives]. For simplicity's sake, this manual assumes that you
-have executed the \type {\directlua} command as given above.
+More fine|-|grained primitives control is possible and you can look up the
+details in \in {section} [luaprimitives]. For simplicity's sake, this manual
+assumes that you have executed the \type {\directlua} command as given above.
 
 The startup behaviour documented above is considered stable in the sense that
 there will not be backward|-|incompatible changes any more. We have promoted some
 rather generic \PDFTEX\ primitives to core \LUATEX\ ones, and the ones inherited
-frome \ALEPH\ (\OMEGA) are also promoted. Effectively this means that we now have
-the \type {tex}, \type {etex}, \type {luatex} and \type {pdftex} (sub)sets left.
+frome \ALEPH\ (\OMEGA) are also promoted. Effectively this means that we now only
+have the \type {tex}, \type {etex} and \type {luatex} sets left.
+
+In \in {Chapter} [modifications] we discuss several primitives that are derived
+from \PDFTEX\ and \ALEPH\ (\OMEGA). Here we stick to real new ones. In the
+chapters on fonts and math we discuss a few more new ones.
 
 \section{Version information}
 
+\subsection {\type {\luatexbanner}, \type {\luatexversion} and \type {\luatexrevision}}
+
 There are three new primitives to test the version of \LUATEX:
 
-\starttabulate[|l|p|p|]
+\starttabulate[|l|pl|pl|]
 \NC \bf primitive           \NC \bf explanation                           \NC \bf value          \NC \NR
 \NC \type {\luatexbanner}   \NC the banner reported on the command line   \NC \luatexbanner      \NC \NR
 \NC \type {\luatexversion}  \NC a combination of major and minor number   \NC \the\luatexversion \NC \NR
@@ -76,8 +82,17 @@ The official \LUATEX\ version is defined as follows:
 \stopitem
 \stopitemize
 
+\subsection{\type {\formatname}}
+
+The \type {\formatname} syntax is identical to \type {\jobname}. In \INITEX, the
+expansion is empty. Otherwise, the expansion is the value that \type {\jobname} had
+during the \INITEX\ run that dumped the currently loaded format. You can use this
+token list to provide your own version info.
+
 \section{\UNICODE\ text support}
 
+\subsection {Extended ranges}
+
 Text input and output is now considered to be \UNICODE\ text, so input characters
 can use the full range of \UNICODE\ ($2^{20}+2^{16}-1 = \hbox{0x10FFFF}$). Later
 chapters will talk of characters and glyphs. Although these are not
@@ -86,7 +101,8 @@ always converted to a suitable graphic representation of that character in a
 specific font. However, while processing a list of to|-|be|-|typeset nodes, its
 contents may still be seen as a character. Inside \LUATEX\ there is no clear
 separation between the two concepts. Because the subtype of a glyph node can be
-changed in \LUA\ it is lso up to the user.
+changed in \LUA\ it is up to the user: subtypes larger than 255 indicate that
+font processing has happened.
 
 A few primitives are affected by this, all in a similar fashion: each of them has
 to accommodate for a larger range of acceptable numbers. For instance, \type
@@ -109,10 +125,17 @@ print the single byte corresponding to $c$ minus 1{,}114{,}112.
 
 Output to the terminal uses \type {^^} notation for the lower control range
 ($c<32$), with the exception of \type {^^I}, \type {^^J} and \type {^^M}. These
-are considered \quote {safe} and therefore printed as-is.
+are considered \quote {safe} and therefore printed as|-|is. You can disable
+escaping with \type {texio.setescape(false)} in which case you get the normal
+characters on the console.
 
 Normalization of the \UNICODE\ input can be handled by a macro package during
-callback processing (this will be explained in \in{section}[iocallback]).
+callback processing (this will be explained in \in {section} [iocallback]).
+
+\subsection{\type {\Uchar}}
+
+The expandable command \type {\Uchar} reads a number between~0 and $1{,}114{,}111$
+and expands to the associated \UNICODE\ character.
 
 \section{Extended tables}
 
@@ -147,11 +170,9 @@ commands are:
 \stoptyping
 \stopfourcolumns
 
-The glyph properties \type {\efcode}, \type {\lpcode} and \type {\rpcode},
-introduced in \PDFTEX\ that deal with font expansion (hz) and character
-protruding, are also 16-bit. Because font memory management has been rewritten,
-these character properties are no longer shared among fonts instances that
-originate from the same metric file.
+Because font memory management has been rewritten, character properties in fonts
+are no longer shared among fonts instances that originate from the same metric
+file.
 
 \section{Attributes}
 
@@ -180,6 +201,9 @@ attached to all nodes created in their scope. These can then be queried from any
 \LUA\ code that deals with node processing. Further information about how to use
 attributes for node list processing from \LUA\ is given in~\in {chapter}[nodes].
 
+Attributes are stored in a sorted (sparse) linked list that are shared when
+possible. This permits efficient testing and updating.
+
 \subsection{Box attributes}
 
 Nodes typically receive the list of attributes that is in effect when they are
@@ -231,11 +255,10 @@ syntax is
 
 \startsyntax
 \directlua <general text>!crlf
-\directlua name <general text> <general text>!crlf
 \directlua <16-bit number> <general text>
 \stopsyntax
 
-The last \syntax {<general text>} is expanded fully, and then fed into the \LUA\
+The \syntax {<general text>} is expanded fully, and then fed into the \LUA\
 interpreter. After reading and expansion has been applied to the \syntax
 {<general text>}, the resulting token list is converted to a string as if it was
 displayed using \type {\the\toks}. On the \LUA\ side, each \type {\directlua}
@@ -260,24 +283,11 @@ say:
 Then \LUA\ line comments can be used, since \TEX\ does not replace line endings
 with spaces.
 
-The \syntax {name <general text>} specifies the name of the \LUA\ chunk, mainly
-shown in the stack backtrace of error messages created by \LUA\ code. The \syntax
-{<general text>} is expanded fully, thus macros can be used to generate the chunk
-name, i.e.
-
-\starttyping
-\directlua name{\jobname:\the\inputlineno} ...
-\stoptyping
-
-to include the name of the input file as well as the input line into the chunk
-name.
-
-Likewise, the \syntax {<16-bit number>} designates a name of a \LUA\ chunk, but
-in this case the name will be taken from the \type {lua.name} array (see the
-documentation of the \type {lua} table further in this manual).
-
-The chunk name should not start with a \type {@}, or it will be displayed as a
-file name (this is a quirk in the current \LUA\ implementation).
+Likewise, the \syntax {<16-bit number>} designates a name of a \LUA\ chunk and is
+taken from the \type {lua.name} array (see the documentation of the \type {lua}
+table further in this manual). When a chunk name starts with a \type {@} it will
+be displayed as a file name. This is a side effect of the way \LUA\ implements
+error handling.
 
 The \type {\directlua} command is expandable. Since it passes \LUA\ code to the
 \LUA\ interpreter its expansion from the \TEX\ viewpoint is usually empty.
@@ -332,23 +342,24 @@ that there will not be backward-incompatible changes any more.
 
 \subsection{\type {\latelua}}
 
-\type {\latelua} stores \LUA\ code in a whatsit that will be processed at the time
-of shipping out. Its intended use is a cross between \type {\pdfliteral} and
-\type {\write}. Within the \LUA\ code you can print \PDF\ statements directly to the
-\PDF\ file via \type {pdf.print}, or you can write to other output streams via
-\type {texio.write} or simply using \LUA\ I/O routines.
+Contrary to \type {\directlua}, \type {\latelua} stores \LUA\ code in a whatsit
+that will be processed at the time of shipping out. Its intended use is a cross
+between \PDF\ literals (often available as \type {\pdfliteral}) and the
+traditional \TEX\ extension \type {\write}. Within the \LUA\ code you can print
+\PDF\ statements directly to the \PDF\ file via \type {pdf.print}, or you can
+write to other output streams via \type {texio.write} or simply using \LUA\ \IO\
+routines.
 
 \startsyntax
 \latelua <general text>!crlf
-\latelua name <general text> <general text>!crlf
 \latelua <16-bit number> <general text>
 \stopsyntax
 
-Expansion of macros etcetera in the final \type {<general text>} is delayed until
-just before the whatsit is executed (like in \type {\write}). With regard to \PDF\
-output stream \type {\latelua} behaves as \type {\pdfliteral page}. The \syntax {name
-<general text>} and \syntax {<16-bit number>} behave in the same way as they do
-for \type {\directlua}
+Expansion of macros in the final \type {<general text>} is delayed until just
+before the whatsit is executed (like in \type {\write}). With regard to \PDF\
+output stream \type {\latelua} behaves as \PDF\ page literals. The \syntax
+{name <general text>} and \syntax {<16-bit number>} behave in the same way as
+they do for \type {\directlua}
 
 \subsection{\type {\luaescapestring}}
 
@@ -378,7 +389,7 @@ is easier to keep the code in a separate file and load it using \LUA's
 The \type {\directlua} commands involves tokenization of its argument (after
 picking up an optional name or number specification). The tokenlist is then
 converted into a string and given to \LUA\ to turn into a function that is
-called. The overhead is rather small but when you use this primitive hundreds or
+called. The overhead is rather small but when you use this primitive hundreds of
 thousands of times, it can become noticeable. For this reason there is a variant
 call available: \type {\luafunction}. This command is used as follows:
 
@@ -406,61 +417,6 @@ in the following example the number \type {8} gets typeset.
 }
 \stoptyping
 
-\section{\type {\clearmarks}}
-
-This primitive complements the \ETEX\ mark primitives and clears a mark class
-completely, resetting all three connected mark texts to empty. It is an
-immediate command.
-
-\startsyntax
-\clearmarks <16-bit number>
-\stopsyntax
-
-\section{\type {\noligs} and \type {\nokerns}}
-
-These primitives prohibit ligature and kerning insertion at the time when the
-initial node list is built by \LUATEX's main control loop. They are part of a
-temporary trick and will be removed in the near future. For now, you need to
-enable these primitives when you want to do node list processing of \quote
-{characters}, where \TEX's normal processing would get in the way.
-
-\startsyntax
-\noligs <integer>!crlf
-\nokerns <integer>
-\stopsyntax
-
-These primitives can now be implemented by overloading the ligature building and
-kerning functions, i.e.\ by assigning dummy functions to their associated
-callbacks.
-
-\section{\type {\formatname}}
-
-The \type {\formatname} syntax is identical to \type {\jobname}. In \INITEX, the
-expansion is empty. Otherwise, the expansion is the value that \type {\jobname} had
-during the \INITEX\ run that dumped the currently loaded format.
-
-\section{\type {\scantextokens}}
-
-The syntax of \type {\scantextokens} is identical to \type {\scantokens}. This
-primitive is a slightly adapted version of \ETEX's \type {\scantokens}. The
-differences are:
-
-\startitemize
-\startitem
-    The last (and usually only) line does not have a \type {\endlinechar}
-    appended.
-\stopitem
-\startitem
-    \type {\scantextokens} never raises an EOF error, and it does not execute
-    \type {\everyeof} tokens.
-\stopitem
-\startitem
-    The \quote{\unknown\ while end of file \unknown} error tests are not
-    executed, allowing the expansion to end on a different grouping level or
-    while a conditional is still incomplete.
-\stopitem
-\stopitemize
-
 \section {Alignments}
 
 \subsection{\tex {alignmark}}
@@ -502,16 +458,16 @@ has to be zero. Table zero is initialized by \INITEX.
 The primitive \type {\initcatcodetable} creates a new table with catcodes identical
 to those defined by \INITEX:
 
-\starttabulate[|r|l|l|l|l|]
-\NC  0 \NC \type {\letterbackslash}       \NC         \NC \type {escape}       \NC\NR
-\NC  5 \NC \type {\letterhat\letterhat M} \NC return  \NC \type {car_ret}      \NC (this name may change) \NC\NR
-\NC  9 \NC \type {\letterhat\letterhat @} \NC null    \NC \type {ignore}       \NC\NR
-\NC 10 \NC \type {<space>}                \NC space   \NC \type {spacer}       \NC\NR
-\NC 11 \NC \type {a} -- \type {z}         \NC         \NC \type {letter}       \NC\NR
-\NC 11 \NC \type {A} -- \type {Z}         \NC         \NC \type {letter}       \NC\NR
-\NC 12 \NC everything else                \NC         \NC \type {other}        \NC\NR
-\NC 14 \NC \type {\letterpercent}         \NC         \NC \type {comment}      \NC\NR
-\NC 15 \NC \type {\letterhat\letterhat ?} \NC delete  \NC \type {invalid_char} \NC\NR
+\starttabulate[|r|l|l|l|]
+\NC  0 \NC \tttf \letterbackslash       \NC         \NC \type {escape}       \NC\NR
+\NC  5 \NC \tttf \letterhat\letterhat M \NC return  \NC \type {car_ret}      \NC\NR
+\NC  9 \NC \tttf \letterhat\letterhat @ \NC null    \NC \type {ignore}       \NC\NR
+\NC 10 \NC \tttf <space>                \NC space   \NC \type {spacer}       \NC\NR
+\NC 11 \NC {\tttf a} \endash\ {\tttf z} \NC         \NC \type {letter}       \NC\NR
+\NC 11 \NC {\tttf A} \endash\ {\tttf Z} \NC         \NC \type {letter}       \NC\NR
+\NC 12 \NC everything else              \NC         \NC \type {other}        \NC\NR
+\NC 14 \NC \tttf \letterpercent         \NC         \NC \type {comment}      \NC\NR
+\NC 15 \NC \tttf \letterhat\letterhat ? \NC delete  \NC \type {invalid_char} \NC\NR
 \stoptabulate
 
 The new catcode table is allocated globally: it will not go away after the
@@ -540,10 +496,10 @@ raised.
 \suppressfontnotfounderror = 1
 \stopsyntax
 
-If this new integer parameter is non|-|zero, then \LUATEX\ will not complain
-about font metrics that are not found. Instead it will silently skip the font
-assignment, making the requested csname for the font \type {\ifx} equal to
-\type {\nullfont}, so that it can be tested against that without bothering the user.
+If this integer parameter is non|-|zero, then \LUATEX\ will not complain about
+font metrics that are not found. Instead it will silently skip the font
+assignment, making the requested csname for the font \type {\ifx} equal to \type
+{\nullfont}, so that it can be tested against that without bothering the user.
 
 \subsection{\type {\suppresslongerror}}
 
@@ -551,9 +507,9 @@ assignment, making the requested csname for the font \type {\ifx} equal to
 \suppresslongerror = 1
 \stopsyntax
 
-If this new integer parameter is non|-|zero, then \LUATEX\ will not complain
-about \type {\par} commands encountered in contexts where that is normally
-prohibited (most prominently in the arguments of non-long macros).
+If this integer parameter is non|-|zero, then \LUATEX\ will not complain about
+\type {\par} commands encountered in contexts where that is normally prohibited
+(most prominently in the arguments of non-long macros).
 
 \subsection{\type {\suppressifcsnameerror}}
 
@@ -561,12 +517,11 @@ prohibited (most prominently in the arguments of non-long macros).
 \suppressifcsnameerror = 1
 \stopsyntax
 
-If this new integer parameter is non|-|zero, then \LUATEX\ will not complain
-about non-expandable commands appearing in the middle of a \type {\ifcsname}
-expansion. Instead, it will keep getting expanded tokens from the input until it
-encounters an \type {\endcsname} command. Use with care! This command is
-experimental: if the input expansion is unbalanced with respect to \type
-{\csname} \ldots \type {\endcsname} pairs, the \LUATEX\ process may hang
+If this integer parameter is non|-|zero, then \LUATEX\ will not complain about
+non-expandable commands appearing in the middle of a \type {\ifcsname} expansion.
+Instead, it will keep getting expanded tokens from the input until it encounters
+an \type {\endcsname} command. If the input expansion is unbalanced with respect
+to \type {\csname} \ldots \type {\endcsname} pairs, the \LUATEX\ process may hang
 indefinitely.
 
 \subsection{\type {\suppressoutererror}}
@@ -581,7 +536,7 @@ prohibited.
 
 \subsection{\type {\suppressmathparerror}}
 
-The following setting will permit \par tokens in a math formula:
+The following setting will permit \type {\par} tokens in a math formula:
 
 \startsyntax
 \suppressmathparerror = 1
@@ -595,7 +550,15 @@ $ x + 1 =
 a $
 \stoptyping
 
-\section{\type {\matheqnogapstep}}
+\section {Math}
+
+\subsection{Extensions}
+
+We will cover math in its own chapter because not only the font subsystem and
+spacing model have been enhanced (thereby introducing many new primitives) but
+also because some more control has been added to existing functionality.
+
+\subsection{\type {\matheqnogapstep}}
 
 By default \TEX\ will add one quad between the equation and the number. This is
 hard coded. A new primitive can control this:
@@ -609,17 +572,20 @@ use a step to control the size. A value of zero will suppress the gap. The step
 is divided by 1000 which is the usual way to mimmick floating point factors in
 \TEX.
 
-\section{\type {\outputbox}}
+\section{Fonts}
 
-\startsyntax
-\outputbox = 65535
-\stopsyntax
+\subsection{Font syntax}
 
-This new integer parameter allows you to alter the number of the box that will be
-used to store the page sent to the output routine. Its default value is 255, and
-the acceptable range is from 0 to 65535.
+\LUATEX\ will accept a braced argument as a font name:
+
+\starttyping
+\font\myfont = {cmr10}
+\stoptyping
+
+This allows for embedded spaces, without the need for double quotes. Macro
+expansion takes place inside the argument.
 
-\section{\type {\fontid} and \type {\setfontid}}
+\subsection{\type {\fontid}}
 
 \startsyntax
 \fontid\font
@@ -641,58 +607,159 @@ order of loading fonts. For instance, when in \CONTEXT\ virtual math \UNICODE\
 fonts are used, we can easily get over a hundred ids in use. Not all ids have to
 be bound to a real font, after all it's just a number.
 
+\subsection{\type {\setfontid}}
+
 The primitive \type {\setfontid} can be used to enable a font with the given id
 (which of course needs to be a valid one).
 
-\section{\type {\gleaders}}
+\subsection{\type {\noligs} and \type {\nokerns}}
 
-This type of leaders is anchored to the origin of the box to be shipped out. So
-they are like normal \type {\leaders} in that they align nicely, except that the
-alignment is based on the {\it largest\/} enclosing box instead of the {\it
-smallest\/}. The \type {g} stresses this global nature.
+These primitives prohibit ligature and kerning insertion at the time when the
+initial node list is built by \LUATEX's main control loop. You can enable these
+primitives when you want to do node list processing of \quote {characters}, where
+\TEX's normal processing would get in the way.
 
-\section{\type {\nohrule} and \type {\novrule}}
+\startsyntax
+\noligs <integer>!crlf
+\nokerns <integer>
+\stopsyntax
 
-Because internally box resources and image resources are now stored as a special
-kind of rule, we also introduced an empty rule variant. Because introducing a new
-keyword can cause incompatibilities, two new primitives were introduced: \type
-{\nohrule} and \type {\novrule}. These can be used to reserve space. This is
-often more efficient than creating an empty box with fake dimensions).
+These primitives can also be implemented by overloading the ligature building and
+kerning functions, i.e.\ by assigning dummy functions to their associated
+callbacks. Keep in mind that when you define a font (using \LUA) you can also
+omit the kern and ligature tables, which has the same effect as the above.
 
-\section{\type {\Uchar}}
+\subsection{\type{\nospaces}}
 
-The expandable command \type {\Uchar} reads a number between~0 and $1{,}114{,}111$
-and expands to the associated \UNICODE\ character.
+This new primitive can be used to overrule the usual \type {\spaceskip}
+related heuristics when a space character is seen in a text flow. The
+value~\type{1} triggers no injection while \type{2} results in injection of
+a zero skip. Below we see the results for four characters separated by a
+space.
 
-\section{\type {\hyphenationmin}}
+\startlinecorrection
+\startcombination[3*2]
+    {\ruledhbox to 5cm{\vtop{\hsize 10mm\nospaces=0\relax x x x x \par}\hss}} {\type {0 / hsize 10mm}}
+    {\ruledhbox to 5cm{\vtop{\hsize 10mm\nospaces=1\relax x x x x \par}\hss}} {\type {1 / hsize 10mm}}
+    {\ruledhbox to 5cm{\vtop{\hsize 10mm\nospaces=2\relax x x x x \par}\hss}} {\type {2 / hsize 10mm}}
+    {\ruledhbox to 5cm{\vtop{\hsize  1mm\nospaces=0\relax x x x x \par}\hss}} {\type {0 / hsize 1mm}}
+    {\ruledhbox to 5cm{\vtop{\hsize  1mm\nospaces=1\relax x x x x \par}\hss}} {\type {1 / hsize 1mm}}
+    {\ruledhbox to 5cm{\vtop{\hsize  1mm\nospaces=2\relax x x x x \par}\hss}} {\type {2 / hsize 1mm}}
+\stopcombination
+\stoplinecorrection
 
-This primitive can be used to set the minimal word length, so setting it to a value
-of~$5$ means that only words of 6 characters and more will be hyphenated, of course
-within the constraints of the \type {\lefthyphenmin} and \type {\righthyphenmin}
-values (as stored in the glyph node). This primitive accepts a number and stores
-the value with the language.
+\section{Tokens, commands and strings}
 
-\section{\type {\boundary} and \type {\noboundary}}
+\subsection{\type {\scantextokens}}
 
-The \type {\noboundary} commands used to inject a whatsit node but now injects a normal
-node with type \type {boundary} and subtype~0. In addition you can say:
+The syntax of \type {\scantextokens} is identical to \type {\scantokens}. This
+primitive is a slightly adapted version of \ETEX's \type {\scantokens}. The
+differences are:
+
+\startitemize
+\startitem
+    The last (and usually only) line does not have a \type {\endlinechar}
+    appended.
+\stopitem
+\startitem
+    \type {\scantextokens} never raises an EOF error, and it does not execute
+    \type {\everyeof} tokens.
+\stopitem
+\startitem
+    There are no \quote {\unknown\ while end of file \unknown} error tests
+    executed. This allows the expansion to end on a different grouping level or
+    while a conditional is still incomplete.
+\stopitem
+\stopitemize
+
+\subsection{\type {\toksapp}, \type {\tokspre}, \type {\etoksapp} and \type {\etokspre}}
+
+Instead of:
 
 \starttyping
-x\boundary 123\relax y
+\toks0\expandafter{\the\toks0 foo}
 \stoptyping
 
-This has the same effect but the subtype is now~1 and the value~123 is stored. The
-traditional ligature builder still sees this as a cancel boundary directive but at the
-\LUA\ end you can implement different behaviour. The added benefit of passing this
-value is a side effect of the generalization.
+you can use:
 
+\starttyping
+\etoksapp0{foo}
+\stoptyping
 
-\section{Debugging}
+The \type {pre} variants prepend instead of append, and the \type {e} variants
+expand the passed general text.
 
-If \type {\tracingonline} is larger than~2, the node list display will also print
-the node number of the nodes.
+\subsection{\type {\csstring}, \type {\begincsname} and \type {\lastnamedcs}}
+
+These are somewhat special. The \type {\csstring} primitive is like
+\type {\string} but it omits the leading escape character. This can be
+somewhat more efficient that stripping it of afterwards.
+
+The \type {\begincsname} primitive is like \type {\csname} but doesn't create
+a relaxed equivalent when there is no such name. It is equivalent to
+
+\starttyping
+\ifcsname foo\endcsname
+  \csname foo\endcsname
+\fi
+\stoptyping
+
+The advantage is that it saves a lookup (don't expect much speedup) but more
+important is that it avoids using the \type {\if}.
+
+The \type {\lastnamedcs} is one that should be used with care. The above
+example could be written as:
+
+\starttyping
+\ifcsname foo\endcsname
+  \lastnamedcs
+\fi
+\stoptyping
+
+This is slightly more efficient than constructing the string twice (deep down in
+\LUATEX\ this also involves some \UTF8 juggling), but probably more relevant is
+that it saves a few tokens and can make code a bit more more readable.
 
-\section{Images and Forms}
+\subsection{\type {\clearmarks}}
+
+This primitive complements the \ETEX\ mark primitives and clears a mark class
+completely, resetting all three connected mark texts to empty. It is an
+immediate command.
+
+\startsyntax
+\clearmarks <16-bit number>
+\stopsyntax
+
+\subsection{\type{\letcharcode}}
+
+This primitive is still experimental but can be used to assign a meaning to an active
+character, as in:
+
+\starttyping
+\def\foo{bar} \letcharcode123\foo
+\stoptyping
+
+This can be a bit nicer that using the uppercase tricks (using the property of
+\type {\uppercase} that it treats active characters special).
+
+\section{Boxes, rules and leaders}
+
+\subsection{\type {\outputbox}}
+
+\startsyntax
+\outputbox = 65535
+\stopsyntax
+
+This new integer parameter allows you to alter the number of the box that will be
+used to store the page sent to the output routine. Its default value is 255, and
+the acceptable range is from 0 to 65535.
+
+\subsection{\type {\vpack}, \type {\hpack} and \type {\tpack}}
+
+These three primitives are like \type {\vbox}, \type {\hbox} and \type {\vtop}
+but don't apply the related callbacks.
+
+\subsection{Images and Forms}
 
 These two concepts are now core concepts and no longer whatsits. They are in fact
 now implemented as rules with special properties. Normal rules have subtype~0,
@@ -723,11 +790,58 @@ provides the image with dimensions defined by \type {\saveimageresource}. These
 optional parameters are not implemented for \type {\saveboxresource}.
 
 \starttyping
-\pdfrefximage width 20mm height 10mm depth 5mm \pdflastximage
-\pdfrefxform  width 20mm height 10mm depth 5mm \pdflastxform
+\useimageresource width 20mm height 10mm depth 5mm \lastsavedimageresourceindex
+\useboxresource   width 20mm height 10mm depth 5mm \lastsavedboxresourceindex
+\stoptyping
+
+\subsection{\type {\nohrule} and \type {\novrule}}
+
+Because introducing a new keyword can cause incompatibilities, two new primitives
+were introduced: \type {\nohrule} and \type {\novrule}. These can be used to
+reserve space. This is often more efficient than creating an empty box with fake
+dimensions).
+
+\subsection{\type {\gleaders}}
+
+This type of leaders is anchored to the origin of the box to be shipped out. So
+they are like normal \type {\leaders} in that they align nicely, except that the
+alignment is based on the {\it largest\/} enclosing box instead of the {\it
+smallest\/}. The \type {g} stresses this global nature.
+
+\section {Languages}
+
+\subsection{\type {\hyphenationmin}}
+
+This primitive can be used to set the minimal word length, so setting it to a value
+of~$5$ means that only words of 6 characters and more will be hyphenated, of course
+within the constraints of the \type {\lefthyphenmin} and \type {\righthyphenmin}
+values (as stored in the glyph node). This primitive accepts a number and stores
+the value with the language.
+
+\subsection{\type {\boundary}, \type {\noboundary}, \type {\protrusionboundary} and \type
+{\wordboundary}}
+
+The \type {\noboundary} commands used to inject a whatsit node but now injects a normal
+node with type \type {boundary} and subtype~0. In addition you can say:
+
+\starttyping
+x\boundary 123\relax y
 \stoptyping
 
-\section{\type {\outputmode} and \type {\draftmode}}
+This has the same effect but the subtype is now~1 and the value~123 is stored.
+The traditional ligature builder still sees this as a cancel boundary directive
+but at the \LUA\ end you can implement different behaviour. The added benefit of
+passing this value is a side effect of the generalization. The subtypes~2 and~3
+are used to control protrusion and word boundaries in hyphenation.
+
+\section{Control and debugging}
+
+\subsection {Tracing}
+
+If \type {\tracingonline} is larger than~2, the node list display will also print
+the node number of the nodes.
+
+\subsection{\type {\outputmode} and \type {\draftmode}}
 
 The \type {\outputmode} variable tells \LUATEX\ what it has to produce:
 
@@ -740,7 +854,9 @@ The value of the \type {\draftmode} counter signals the backend if it should
 output less. The \PDF\ backend accepts a value of~$1$, while the \DVI\ backend
 ignores the value.
 
-\section{File syntax}
+\section {Files}
+
+\subsection{File syntax}
 
 \LUATEX\ will accept a braced argument as a file name:
 
@@ -752,54 +868,12 @@ ignores the value.
 This allows for embedded spaces, without the need for double quotes. Macro
 expansion takes place inside the argument.
 
-\section{Font syntax}
-
-\LUATEX\ will accept a braced argument as a font name:
-
-\starttyping
-\font\myfont = {cmr10}
-\stoptyping
-
-This allows for embedded spaces, without the need for double quotes. Macro
-expansion takes place inside the argument.
-
-\section{Writing to file}
+\subsection{Writing to file}
 
 You can now open upto 127 files with \type {\openout}. When no file is open
 writes will go to the console and log. As a consequence a system command is
 no longer possible but one can use \type {os.execute} to do the same.
 
-\section{\type{\nospaces}}
-
-This new primitive can be used to overrule the usual \type {\spaceskip}
-related heuristics when a space character is seen in a text flow. The
-value~\type{1} triggers no injection while \type{2} results in injection of
-a zero skip. Below we see the results for four characters separated by a
-space.
-
-\startlinecorrection
-\startcombination[3*2]
-    {\ruledhbox to 5cm{\vtop{\hsize 10mm\nospaces=0\relax x x x x \par}\hss}} {\type {0 / hsize 10mm}}
-    {\ruledhbox to 5cm{\vtop{\hsize 10mm\nospaces=1\relax x x x x \par}\hss}} {\type {1 / hsize 10mm}}
-    {\ruledhbox to 5cm{\vtop{\hsize 10mm\nospaces=2\relax x x x x \par}\hss}} {\type {2 / hsize 10mm}}
-    {\ruledhbox to 5cm{\vtop{\hsize  1mm\nospaces=0\relax x x x x \par}\hss}} {\type {0 / hsize 1mm}}
-    {\ruledhbox to 5cm{\vtop{\hsize  1mm\nospaces=1\relax x x x x \par}\hss}} {\type {1 / hsize 1mm}}
-    {\ruledhbox to 5cm{\vtop{\hsize  1mm\nospaces=2\relax x x x x \par}\hss}} {\type {2 / hsize 1mm}}
-\stopcombination
-\stoplinecorrection
-
-\section{\type{\letcharcode}}
-
-This primitive is still experimental but can be used to assign a meaning to an active
-character, as in:
-
-\starttyping
-\def\foo{bar} \letcharcode123\foo
-\stoptyping
-
-This can be a bit nicer that using the uppercase tricks (using the property of
-\type {\uppercase} that it treats active characters special).
-
 \stopchapter
 
 \stopcomponent