2018-07-02 14:46:00

1 files changed, 375 insertions, 235 deletions

diff --git a/doc/context/sources/general/manuals/luatex/luatex-enhancements.tex b/doc/context/sources/general/manuals/luatex/luatex-enhancements.tex
index 243dc6985..5a2764f68 100644
--- a/doc/context/sources/general/manuals/luatex/luatex-enhancements.tex
+++ b/doc/context/sources/general/manuals/luatex/luatex-enhancements.tex
@@ -6,12 +6,14 @@
 
 \startchapter[reference=enhancements,title={Basic \TEX\ enhancements}]
 
-\section{Introduction}
+\startsection[title={Introduction}]
+
+\startsubsection[title={Primitive behaviour}]
 
 From day one, \LUATEX\ has offered extra features compared to the superset of
-\PDFTEX\ and \ALEPH. This has not been limited to the possibility to execute
-\LUA\ code via \prm {directlua}, but \LUATEX\ also adds functionality via new
-\TEX|-|side primitives or extensions to existing ones.
+\PDFTEX, which includes \ETEX, and \ALEPH. This has not been limited to the
+possibility to execute \LUA\ code via \prm {directlua}, but \LUATEX\ also adds
+functionality via new \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
@@ -39,17 +41,19 @@ assumes that you have executed the \prm {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
-from \ALEPH\ (\OMEGA) are also promoted. Effectively this means that we now only
-have the \type {tex}, \type {etex} and \type {luatex} sets left.
+rather generic \PDFTEX\ primitives to core \LUATEX\ ones, and the few that we
+inherited from \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}
+\stopsubsection
+
+\startsubsection[title={Version information}]
 
-\subsection {\lpr {luatexbanner}, \lpr {luatexversion} and \lpr {luatexrevision}}
+\startsubsubsection {\lpr {luatexbanner}, \lpr {luatexversion} and \lpr {luatexrevision}}
 
 \topicindex{version}
 \topicindex{banner}
@@ -93,7 +97,9 @@ The official \LUATEX\ version is defined as follows:
 \stopitem
 \stopitemize
 
-\subsection{\lpr {formatname}}
+\stopsubsubsection
+
+\startsubsubsection{\lpr {formatname}}
 
 \topicindex{format}
 
@@ -102,9 +108,15 @@ expansion is empty. Otherwise, the expansion is the value that \prm {jobname} ha
 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}
+\stopsubsubsection
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={\UNICODE\ text support}]
 
-\subsection {Extended ranges}
+\startsubsection[title={Extended ranges}]
 
 \topicindex{\UNICODE}
 
@@ -133,7 +145,8 @@ As far as the core engine is concerned, all input and output to text files is
 \UTF-8 encoded. Input files can be pre|-|processed using the \type {reader}
 callback. This will be explained in \in {section} [iocallback]. Normalization of
 the \UNICODE\ input is on purpose not built|-|in and can be handled by a macro
-package during callback processing.
+package during callback processing. We have made some practical choices and the
+user has to live with those.
 
 Output in byte|-|sized chunks can be achieved by using characters just outside of
 the valid \UNICODE\ range, starting at the value $1{,}114{,}112$ (0x110000). When
@@ -146,14 +159,18 @@ 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.
 
-\subsection{\lpr {Uchar}}
+\stopsubsection
+
+\startsubsection[title={\lpr {Uchar}}]
 
 \topicindex{\UNICODE}
 
 The expandable command \lpr {Uchar} reads a number between~0 and $1{,}114{,}111$
 and expands to the associated \UNICODE\ character.
 
-\section{Extended tables}
+\stopsubsection
+
+\startsubsection[title={Extended tables}]
 
 All traditional \TEX\ and \ETEX\ registers can be 16-bit numbers. The affected
 commands are:
@@ -188,41 +205,17 @@ commands are:
 
 Because font memory management has been rewritten, character properties in fonts
 are no longer shared among font instances that originate from the same metric
-file.
-
-\section{Attributes}
+file. Of course we share fonts in the backend when possible so that the resulting
+\PDF\ file is as efficient as possible, but for instance also expansion and
+protrusion no longer use copies as in \PDFTEX.
 
-\subsection{Attribute registers}
+\stopsubsection
 
-\topicindex {attributes}
-
-Attributes are a completely new concept in \LUATEX. Syntactically, they behave a
-lot like counters: attributes obey \TEX's nesting stack and can be used after
-\prm {the} etc.\ just like the normal \prm {count} registers.
-
-\startsyntax
-\attribute <16-bit number> <optional equals> <32-bit number>!crlf
-\attributedef <csname> <optional equals> <16-bit number>
-\stopsyntax
-
-Conceptually, an attribute is either \quote {set} or \quote {unset}. Unset
-attributes have a special negative value to indicate that they are unset, that
-value is the lowest legal value: \type {-"7FFFFFFF} in hexadecimal, a.k.a.
-$-2147483647$ in decimal. It follows that the value \type {-"7FFFFFFF} cannot be
-used as a legal attribute value, but you {\it can\/} assign \type {-"7FFFFFFF} to
-\quote {unset} an attribute. All attributes start out in this \quote {unset}
-state in \INITEX.
-
-Attributes can be used as extra counter values, but their usefulness comes mostly
-from the fact that the numbers and values of all \quote {set} attributes are
-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].
+\stopsection
 
-Attributes are stored in a sorted (sparse) linked list that are shared when
-possible. This permits efficient testing and updating.
+\startsection[title={Attributes}]
 
-\subsection{Nodes}
+\startsubsection[title={Nodes}]
 
 \topicindex {nodes}
 
@@ -249,10 +242,53 @@ constructed explicitly or can be the result of subprocesses. For instance, when
 lines are broken into paragraphs, the lines are a linked list of \nod {hlist}
 nodes.
 
-We will see more of these nodes later on but for now that should be enough to be
-able to follow the rest of this chapter.
+So, to summarize: all that you enter as content eventually becomes a node, often
+as part of a (nested) list structure. They have a relative small memory footprint
+and carry only the minimal amount of information needed. In traditional \TEX\ a
+character node only held the font and slot number, in \LUATEX\ we also store some
+language related information, the expansion factor, etc. Now that we have access
+to these nodes from \LUA\ it makes sense to be able to carry more information
+with an node and this is where attributes kick in.
+
+\stopsubsection
+
+\startsubsection[title={Attribute registers}]
+
+\topicindex {attributes}
+
+Attributes are a completely new concept in \LUATEX. Syntactically, they behave a
+lot like counters: attributes obey \TEX's nesting stack and can be used after
+\prm {the} etc.\ just like the normal \prm {count} registers.
+
+\startsyntax
+\attribute <16-bit number> <optional equals> <32-bit number>!crlf
+\attributedef <csname> <optional equals> <16-bit number>
+\stopsyntax
+
+Conceptually, an attribute is either \quote {set} or \quote {unset}. Unset
+attributes have a special negative value to indicate that they are unset, that
+value is the lowest legal value: \type {-"7FFFFFFF} in hexadecimal, a.k.a.
+$-2147483647$ in decimal. It follows that the value \type {-"7FFFFFFF} cannot be
+used as a legal attribute value, but you {\it can\/} assign \type {-"7FFFFFFF} to
+\quote {unset} an attribute. All attributes start out in this \quote {unset}
+state in \INITEX.
 
-\subsection{Box attributes}
+Attributes can be used as extra counter values, but their usefulness comes mostly
+from the fact that the numbers and values of all \quote {set} attributes are
+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. You can define many
+thousands of attributes but normally such a large number makes no sense and is
+also not that efficient because each node carries a (possibly shared) link to a
+list of currently set attributes. But they are a convenient extension and one of
+the first extensions we implemented in \LUATEX.
+
+\stopsubsection
+
+\startsubsection[title={Box attributes}]
 
 \topicindex {attributes}
 \topicindex {boxes}
@@ -328,9 +364,13 @@ indexing the node (here we do that with \type {[a]}. Running this snippet gives:
 Because some values are not set we need to apply the \type {tostring} function
 here so that we get the word \type {nil}.
 
-\section{\LUA\ related primitives}
+\stopsubsection
+
+\stopsection
+
+\startsection[title={\LUA\ related primitives}]
 
-\subsection{\prm {directlua}}
+\startsubsection[title={\prm {directlua}}]
 
 In order to merge \LUA\ code with \TEX\ input, a few new primitives are needed.
 The primitive \prm {directlua} is used to execute \LUA\ code immediately. The
@@ -421,7 +461,9 @@ can break up \LUATEX\ pretty bad. If you are not careful while working with the
 node list interface, you may even end up with assertion errors from within the
 \TEX\ portion of the executable.
 
-\subsection{\lpr {latelua}}
+\stopsubsection
+
+\startsubsection[title={\lpr {latelua}}]
 
 Contrary to \prm {directlua}, \lpr {latelua} stores \LUA\ code in a whatsit
 that will be processed at the time of shipping out. Its intended use is a cross
@@ -442,7 +484,9 @@ output stream \lpr {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 \prm {directlua}
 
-\subsection{\lpr {luaescapestring}}
+\stopsubsection
+
+\startsubsection[title={\lpr {luaescapestring}}]
 
 \topicindex {escaping}
 
@@ -466,7 +510,9 @@ in a separate file and load it using \LUA's \type {dofile}:
 \directlua { dofile('mysetups.lua') }
 \stoptyping
 
-\subsection{\lpr {luafunction}, \lpr {luafunctioncall} and \lpr {luadef}}
+\stopsubsection
+
+\startsubsection[title={\lpr {luafunction}, \lpr {luafunctioncall} and \lpr {luadef}}]
 
 The \prm {directlua} commands involves tokenization of its argument (after
 picking up an optional name or number specification). The tokenlist is then
@@ -508,9 +554,14 @@ instance in an \prm {edef}. In addition \LUATEX\ provides a definer:
 \protected\global\luadef\MyFunctionC 3
 \stoptyping
 
+You should really use these commands with care. Some references get stored in
+tokens and assume that the function is available when that token expands. On the
+other hand, as we have tested this functionality in relative complex situations
+normal usage should not give problems.
 
+\stopsubsection
 
-\subsection{\lpr {luabytecode} and \lpr {luabytecodecall}}
+\startsubsection[title={\lpr {luabytecode} and \lpr {luabytecodecall}}]
 
 Analogue to the function callers discussed in the previous section we have byte
 code callers. Again the call variant is unexpandable.
@@ -537,15 +588,13 @@ The variable \type {s} in the code is the number of the byte code register that
 can be used for diagnostic purposes. The advantage of bytecode registers over
 function calls is that they are stored in the format (but without upvalues).
 
-\section {Alignments}
+\stopsubsection
 
-\subsection{\lpr {alignmark} and \lpr {aligntab}}
+\stopsection
 
-The primitive \lpr {alignmark} duplicates the functionality of \type {#} inside
-alignment preambles, while \lpr {aligntab} duplicates the functionality of \type
-{&}.
+\startsection[title={Catcode tables}]
 
-\section{Catcode tables}
+\startsubsection[title={Catcodes}]
 
 \topicindex {catcodes}
 
@@ -557,7 +606,9 @@ compared to traditional \TEX. The contents of each catcode table is independent
 from any other catcode table, and its contents is stored and retrieved from the
 format file.
 
-\subsection{\lpr {catcodetable}}
+\stopsubsection
+
+\startsubsection[title={\lpr {catcodetable}}]
 
 \startsyntax
 \catcodetable <15-bit number>
@@ -567,7 +618,9 @@ The primitive \lpr {catcodetable} switches to a different catcode table. Such a
 table has to be previously created using one of the two primitives below, or it
 has to be zero. Table zero is initialized by \INITEX.
 
-\subsection{\lpr {initcatcodetable}}
+\stopsubsection
+
+\startsubsection[title={\lpr {initcatcodetable}}]
 
 \startsyntax
 \initcatcodetable <15-bit number>
@@ -594,7 +647,9 @@ initial values are:
 \LL
 \stoptabulate
 
-\subsection{\lpr {savecatcodetable}}
+\stopsubsection
+
+\startsubsection[title={\lpr {savecatcodetable}}]
 
 \startsyntax
 \savecatcodetable <15-bit number>
@@ -608,9 +663,13 @@ The new table is allocated globally: it will not go away after the current group
 has ended. If the supplied number is the currently active table, an error is
 raised.
 
-\section{Suppressing errors}
+\stopsubsection
+
+\stopsection
+
+\startsection[title={Suppressing errors}]
 
-\subsection{\lpr {suppressfontnotfounderror}}
+\startsubsection[title={\lpr {suppressfontnotfounderror}}]
 
 \topicindex {errors}
 
@@ -623,7 +682,9 @@ assignment, making the requested csname for the font \prm {ifx} equal to \prm
 \suppressfontnotfounderror = 1
 \stopsyntax
 
-\subsection{\lpr {suppresslongerror}}
+\stopsubsection
+
+\startsubsection[title={\lpr {suppresslongerror}}]
 
 \topicindex {errors}
 
@@ -635,7 +696,9 @@ If this integer parameter is non|-|zero, then \LUATEX\ will not complain about
 \suppresslongerror = 1
 \stopsyntax
 
-\subsection{\lpr {suppressifcsnameerror}}
+\stopsubsection
+
+\startsubsection[title={\lpr {suppressifcsnameerror}}]
 
 \topicindex {errors}
 
@@ -650,7 +713,9 @@ indefinitely.
 \suppressifcsnameerror = 1
 \stopsyntax
 
-\subsection{\lpr {suppressoutererror}}
+\stopsubsection
+
+\startsubsection[title={\lpr {suppressoutererror}}]
 
 \topicindex {errors}
 
@@ -662,7 +727,9 @@ prohibited.
 \suppressoutererror = 1
 \stopsyntax
 
-\subsection{\lpr {suppressmathparerror}}
+\stopsubsection
+
+\startsubsection[title={\lpr {suppressmathparerror}}]
 
 \topicindex {errors}
 \topicindex {math}
@@ -681,7 +748,9 @@ $ x + 1 =
 a $
 \stoptyping
 
-\subsection{\lpr {suppressprimitiveerror}}
+\stopsubsection
+
+\startsubsection[title={\lpr {suppressprimitiveerror}}]
 
 \topicindex {errors}
 \topicindex {primitives}
@@ -694,19 +763,13 @@ When set to a non|-|zero value the following command will not issue an error:
 \primitive\notaprimitive
 \stopsyntax
 
-\section {Math}
-
-\topicindex {math}
+\stopsubsection
 
-We will cover math extensions 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. Much of this relates to the different approaches of traditional
-\TEX\ fonts and \OPENTYPE\ math.
+\stopsection
 
-\section{Fonts}
+\startsection[title={Fonts}]
 
-\subsection{Font syntax}
+\startsubsection[title={Font syntax}]
 
 \topicindex {fonts}
 
@@ -719,7 +782,9 @@ functionality. Much of this relates to the different approaches of traditional
 This allows for embedded spaces, without the need for double quotes. Macro
 expansion takes place inside the argument.
 
-\subsection{\lpr {fontid} and \lpr {setfontid}}
+\stopsubsection
+
+\startsubsection[title={\lpr {fontid} and \lpr {setfontid}}]
 
 \startsyntax
 \fontid\font
@@ -748,7 +813,9 @@ be bound to a real font, after all it's just a number.
 The primitive \lpr {setfontid} can be used to enable a font with the given id,
 which of course needs to be a valid one.
 
-\subsection{\lpr {noligs} and \lpr {nokerns}}
+\stopsubsection
+
+\startsubsection[title={\lpr {noligs} and \lpr {nokerns}}]
 
 \topicindex {ligatures+suppress}
 \topicindex {kerns+suppress}
@@ -768,7 +835,9 @@ 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.
 
-\subsection{\type{\nospaces}}
+\stopsubsection
+
+\startsubsection[title={\type{\nospaces}}]
 
 \topicindex {spaces+suppress}
 
@@ -789,9 +858,13 @@ space.
 \stopcombination
 \stopplacefigure
 
-\section{Tokens, commands and strings}
+\stopsubsection
 
-\subsection{\lpr {scantextokens}}
+\stopsection
+
+\startsection[title={Tokens, commands and strings}]
+
+\startsubsection[title={\lpr {scantextokens}}]
 
 \topicindex {tokens+scanning}
 
@@ -815,7 +888,9 @@ differences are:
 \stopitem
 \stopitemize
 
-\subsection{\lpr {toksapp}, \lpr {tokspre}, \lpr {etoksapp} and \lpr {etokspre}}
+\stopsubsection
+
+\startsubsection[title={\lpr {toksapp}, \lpr {tokspre}, \lpr {etoksapp} and \lpr {etokspre}}]
 
 Instead of:
 
@@ -832,7 +907,9 @@ you can use:
 The \type {pre} variants prepend instead of append, and the \type {e} variants
 expand the passed general text.
 
-\subsection{\prm {csstring}, \lpr {begincsname} and \lpr {lastnamedcs}}
+\stopsubsection
+
+\startsubsection[title={\prm {csstring}, \lpr {begincsname} and \lpr {lastnamedcs}}]
 
 These are somewhat special. The \prm {csstring} primitive is like
 \prm {string} but it omits the leading escape character. This can be
@@ -861,7 +938,9 @@ 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 readable.
 
-\subsection{\lpr {clearmarks}}
+\stopsubsection
+
+\startsubsection[title={\lpr {clearmarks}}]
 
 \topicindex {marks}
 
@@ -873,7 +952,17 @@ immediate command.
 \clearmarks <16-bit number>
 \stopsyntax
 
-\subsection{\lpr {letcharcode}}
+\stopsubsection
+
+\startsubsection[title={\lpr {alignmark} and \lpr {aligntab}}]
+
+The primitive \lpr {alignmark} duplicates the functionality of \type {#} inside
+alignment preambles, while \lpr {aligntab} duplicates the functionality of \type
+{&}.
+
+\stopsubsection
+
+\startsubsection[title={\lpr {letcharcode}}]
 
 This primitive can be used to assign a meaning to an active character, as in:
 
@@ -884,7 +973,9 @@ This primitive can be used to assign a meaning to an active character, as in:
 This can be a bit nicer than using the uppercase tricks (using the property of
 \prm {uppercase} that it treats active characters special).
 
-\subsection{\lpr {glet}}
+\stopsubsection
+
+\startsubsection[title={\lpr {glet}}]
 
 This primitive is similar to:
 
@@ -895,9 +986,142 @@ This primitive is similar to:
 but faster (only measurable with millions of calls) and probably more convenient
 (after all we also have \type {\gdef}).
 
-\section{Boxes, rules and leaders}
+\subsubsection{\lpr {expanded}, \lpr {immediateassignment} and \lpr {immediateassigned}}
+
+\topicindex {expansion}
+
+The \lpr {expanded} primitive takes a token list and expands it content which can
+come in handy: it avoids a tricky mix of \prm {expandafter} and \prm {noexpand}.
+You can compare it with what happens inside the body of an \prm {edef}. But this
+kind of expansion it still doesn't expand some primitive operations.
+
+\startbuffer
+\newcount\NumberOfCalls
 
-\subsection{\lpr {outputbox}}
+\def\TestMe{\advance\NumberOfCalls1 }
+
+\edef\Tested{\TestMe foo:\the\NumberOfCalls}
+\edef\Tested{\TestMe foo:\the\NumberOfCalls}
+\edef\Tested{\TestMe foo:\the\NumberOfCalls}
+
+\meaning\Tested
+\stopbuffer
+
+\typebuffer
+
+The result is a macro that has the not expanded code in its body:
+
+\getbuffer
+
+Instead we can define \tex {TestMe} in a way that expands the assignment
+immediately. You need of course to be aware of preventing look ahead interference
+by using a space or \tex {relax} (often an expression works better as it doesn't
+leave an \tex {relax}).
+
+\startbuffer
+\def\TestMe{\immediateassignment\advance\NumberOfCalls1 }
+
+\edef\Tested{\TestMe foo:\the\NumberOfCalls}
+\edef\Tested{\TestMe foo:\the\NumberOfCalls}
+\edef\Tested{\TestMe foo:\the\NumberOfCalls}
+
+\meaning\Tested
+\stopbuffer
+
+\typebuffer
+
+This time the counter gets updates and we don't see interference in the
+resulting \tex {Tested} macro:
+
+\getbuffer
+
+Here is a somewhat silly example of expanded comparison:
+
+\startbuffer
+\def\expandeddoifelse#1#2#3#4%
+  {\immediateassignment\edef\tempa{#1}%
+   \immediateassignment\edef\tempb{#2}%
+   \ifx\tempa\tempb
+     \immediateassignment\def\next{#3}%
+   \else
+     \immediateassignment\def\next{#4}%
+   \fi
+   \next}
+
+\edef\Tested
+  {(\expandeddoifelse{abc}{def}{yes}{nop}/%
+    \expandeddoifelse{abc}{abc}{yes}{nop})}
+
+\meaning\Tested
+\stopbuffer
+
+\typebuffer
+
+It gives:
+
+\getbuffer
+
+A variant is:
+
+\starttyping
+\def\expandeddoifelse#1#2#3#4%
+  {\immediateassigned{
+     \edef\tempa{#1}%
+     \edef\tempb{#2}%
+   }%
+   \ifx\tempa\tempb
+     \immediateassignment\def\next{#3}%
+   \else
+     \immediateassignment\def\next{#4}%
+   \fi
+   \next}
+\stoptyping
+
+The possible error messages are the same as using assignments in preambles of
+alignments and after the \prm {accent} command. The supported assignments are the
+so called prefixed commands (except box assignments).
+
+\subsubsection{\lpr {ifcondition}}
+
+\topicindex {conditions}
+
+This is a somewhat special one. When you write macros conditions need to be
+properly balanced in order to let \TEX's fast branch skipping work well. This new
+primitive is basically a no||op flagged as a condition so that the scanner can
+recognize it as an if|-|test. However, when a real test takes place the work is
+done by what follows, in the next example \tex {something}.
+
+\starttyping
+\unexpanded\def\something#1#2%
+  {\edef\tempa{#1}%
+   \edef\tempb{#2}
+   \ifx\tempa\tempb}
+
+\ifcondition\something{a}{b}%
+    \ifcondition\something{a}{a}%
+        true 1
+    \else
+        false 1
+    \fi
+\else
+    \ifcondition\something{a}{a}%
+        true 2
+    \else
+        false 2
+    \fi
+\fi
+\stoptyping
+
+If you are familiar with \METAPOST, this is a bit like \type {vardef} where the macro
+has a return value. Here the return value is a test.
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={Boxes, rules and leaders}]
+
+\startsubsection[title={\lpr {outputbox}}]
 
 \topicindex {output}
 
@@ -909,12 +1133,16 @@ the acceptable range is from 0 to 65535.
 \outputbox = 12345
 \stopsyntax
 
-\subsection{\prm {vpack}, \prm {hpack} and \prm {tpack}}
+\stopsubsection
+
+\startsubsection[title={\prm {vpack}, \prm {hpack} and \prm {tpack}}]
 
 These three primitives are like \prm {vbox}, \prm {hbox} and \prm {vtop}
 but don't apply the related callbacks.
 
-\subsection{\prm {vsplit}}
+\stopsubsection
+
+\startsubsection[title={\prm {vsplit}}]
 
 \topicindex {splitting}
 
@@ -922,7 +1150,9 @@ The \prm {vsplit} primitive has to be followed by a specification of the require
 height. As alternative for the \type {to} keyword you can use \type {upto} to get
 a split of the given size but result has the natural dimensions then.
 
-\subsection[sec:imagedandforms]{Images and reused box objects}
+\stopsubsection
+
+\startsubsection[title={Images and reused box objects},reference=sec:imagedandforms]
 
 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,
@@ -965,7 +1195,9 @@ is the \type {type} key. When set to non|-|zero the \type {/Type} entry is
 omitted. A value of 1 or 3 still writes a \type {/BBox}, while 2 or 3 will write
 a \type {/Matrix}.
 
-\subsection{\lpr {nohrule} and \lpr {novrule}}
+\stopsubsection
+
+\startsubsection[title={\lpr {nohrule} and \lpr {novrule}}]
 
 \topicindex {rules}
 
@@ -974,7 +1206,9 @@ were introduced: \lpr {nohrule} and \lpr {novrule}. These can be used to
 reserve space. This is often more efficient than creating an empty box with fake
 dimensions.
 
-\subsection{\lpr {gleaders}}
+\stopsubsection
+
+\startsubsection[title={\lpr {gleaders}}]
 
 \topicindex {leaders}
 
@@ -983,9 +1217,13 @@ they are like normal \prm {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}
+\stopsubsection
+
+\stopsection
+
+\startsection[title={Languages}]
 
-\subsection{\lpr {hyphenationmin}}
+\startsubsection[title={\lpr {hyphenationmin}}]
 
 \topicindex {languages}
 \topicindex {hyphenation}
@@ -996,7 +1234,9 @@ within the constraints of the \prm {lefthyphenmin} and \prm {righthyphenmin}
 values (as stored in the glyph node). This primitive accepts a number and stores
 the value with the language.
 
-\subsection{\prm {boundary}, \prm {noboundary}, \prm {protrusionboundary} and \prm {wordboundary}}
+\stopsubsection
+
+\startsubsection[title={\prm {boundary}, \prm {noboundary}, \prm {protrusionboundary} and \prm {wordboundary}}]
 
 The \prm {noboundary} command is used to inject a whatsit node but now injects a normal
 node with type \nod {boundary} and subtype~0. In addition you can say:
@@ -1012,16 +1252,22 @@ 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 and have
 related primitives.
 
-\section{Control and debugging}
+\stopsubsection
+
+\stopsection
+
+\startsection[title={Control and debugging}]
 
-\subsection {Tracing}
+\startsubsection[title={Tracing}]
 
 \topicindex {tracing}
 
 If \prm {tracingonline} is larger than~2, the node list display will also print
 the node number of the nodes.
 
-\subsection{\lpr {outputmode}}
+\stopsubsection
+
+\startsubsection[title={\lpr {outputmode}}]
 
 \topicindex {output}
 \topicindex {backend}
@@ -1036,15 +1282,22 @@ The \lpr {outputmode} variable tells \LUATEX\ what it has to produce:
 \LL
 \stoptabulate
 
-\subsection{\lpr {draftmode}}
+\stopsubsection
+
+\startsubsection[title={\lpr {draftmode}}]
 
-The value of the \lpr {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.
+The value of the \lpr {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. This is no critical feature so we can remove it in future versions when it
+can make the backend cleaner.
 
-\section {Files}
+\stopsubsection
 
-\subsection{File syntax}
+\stopsection
+
+\startsection[title={Files}]
+
+\startsubsection[title={File syntax}]
 
 \topicindex {files+names}
 
@@ -1075,7 +1328,9 @@ extension is that a csname not always makes sense. The zero case is the default.
 \LL
 \stoptabulate
 
-\subsection{Writing to file}
+\stopsubsection
+
+\startsubsection[title={Writing to file}]
 
 \topicindex {files+writing}
 
@@ -1083,134 +1338,19 @@ You can now open upto 127 files with \prm {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.
 
-\subsection{\lpr {expanded}, \lpr {immediateassignment}, \lpr {immediateassigned}}
-
-\topicindex {expansion}
-
-The \lpr {expanded} primitive takes a token list and expands it content which can
-come in handy: it avoids a tricky mix of \prm {expandafter} and \prm {noexpand}.
-You can compare it with what happens inside the body of an \prm {edef}. But this
-kind of expansion it still doesn't expand some primitive operations.
-
-\startbuffer
-\newcount\NumberOfCalls
-
-\def\TestMe{\advance\NumberOfCalls1 }
-
-\edef\Tested{\TestMe foo:\the\NumberOfCalls}
-\edef\Tested{\TestMe foo:\the\NumberOfCalls}
-\edef\Tested{\TestMe foo:\the\NumberOfCalls}
-
-\meaning\Tested
-\stopbuffer
-
-\typebuffer
-
-The result is a macro that has the not expanded code in its body:
-
-\getbuffer
-
-Instead we can define \tex {TestMe} in a way that expands the assignment
-immediately. You need of course to be aware of preventing look ahead interference
-by using a space or \tex {relax} (often an expression works better as it doesn't
-leave an \tex {relax}).
-
-\startbuffer
-\def\TestMe{\immediateassignment\advance\NumberOfCalls1 }
-
-\edef\Tested{\TestMe foo:\the\NumberOfCalls}
-\edef\Tested{\TestMe foo:\the\NumberOfCalls}
-\edef\Tested{\TestMe foo:\the\NumberOfCalls}
-
-\meaning\Tested
-\stopbuffer
-
-\typebuffer
-
-This time the counter gets updates and we don't see interference in the
-resulting \tex {Tested} macro:
+\stopsubsection
 
-\getbuffer
-
-Here is a somewhat silly example of expanded comparison:
-
-\startbuffer
-\def\expandeddoifelse#1#2#3#4%
-  {\immediateassignment\edef\tempa{#1}%
-   \immediateassignment\edef\tempb{#2}%
-   \ifx\tempa\tempb
-     \immediateassignment\def\next{#3}%
-   \else
-     \immediateassignment\def\next{#4}%
-   \fi
-   \next}
-
-\edef\Tested
-  {(\expandeddoifelse{abc}{def}{yes}{nop}/%
-    \expandeddoifelse{abc}{abc}{yes}{nop})}
-
-\meaning\Tested
-\stopbuffer
-
-\typebuffer
-
-It gives:
-
-\getbuffer
-
-A variant is:
-
-\starttyping
-\def\expandeddoifelse#1#2#3#4%
-  {\immediateassigned{
-     \edef\tempa{#1}%
-     \edef\tempb{#2}%
-   }%
-   \ifx\tempa\tempb
-     \immediateassignment\def\next{#3}%
-   \else
-     \immediateassignment\def\next{#4}%
-   \fi
-   \next}
-\stoptyping
-
-The possible error messages are the same as using assignments in preambles of
-alignments and after the \prm {accent} command. The supported assignments are the
-so called prefixed commands (except box assignments).
-
-\subsection{\lpr {ifcondition}}
-
-\topicindex {conditions}
-
-This is a somewhat special one. When you write macros conditions need to be
-properly balanced in order to let \TEX's fast branch skipping work well. This new
-primitive is basically a no||op flagged as a condition so that the scanner can
-recognize it as an if|-|test. However, when a real test takes place the work is
-done by what follows, in the next example \tex {something}.
+\stopsection
 
-\starttyping
-\unexpanded\def\something#1#2%
-  {\edef\tempa{#1}%
-   \edef\tempb{#2}
-   \ifx\tempa\tempb}
+\startsection[title={Math}]
 
-\ifcondition\something{a}{b}%
-    \ifcondition\something{a}{a}%
-        true 1
-    \else
-        false 1
-    \fi
-\else
-    \ifcondition\something{a}{a}%
-        true 2
-    \else
-        false 2
-    \fi
-\fi
-\stoptyping
+\topicindex {math}
 
-If you are familiar with \METAPOST, this is a bit like \type {vardef} where the macro
-has a return value. Here the return value is a test.
+We will cover math extensions 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. Much of this relates to the different approaches of traditional
+\TEX\ fonts and \OPENTYPE\ math.
 
 \stopsection