2018-05-12 00:16:00

1 files changed, 183 insertions, 23 deletions

diff --git a/doc/context/sources/general/manuals/luatex/luatex-enhancements.tex b/doc/context/sources/general/manuals/luatex/luatex-enhancements.tex
index e9fd951fc..8d53852ae 100644
--- a/doc/context/sources/general/manuals/luatex/luatex-enhancements.tex
+++ b/doc/context/sources/general/manuals/luatex/luatex-enhancements.tex
@@ -56,11 +56,14 @@ chapters on fonts and math we discuss a few more new ones.
 
 There are three new primitives to test the version of \LUATEX:
 
+\unexpanded\def\VersionHack#1% otherwise different luatex and luajittex runs
+  {\cldcontext{(string.gsub(string.match("\luatexbanner","(.+)\letterpercent("),"jit",""))}}
+
 \starttabulate[|l|l|pl|]
 \DB primitive             \BC value
                           \BC explanation \NC \NR
 \TB
-\NC \lpr {luatexbanner}   \NC \cldcontext{string.match("\luatexbanner","(.+)\letterpercent(")}
+\NC \lpr {luatexbanner}   \NC \VersionHack{\luatexbanner}
                           \NC the banner reported on the command line \NC \NR
 \NC \lpr {luatexversion}  \NC \the\luatexversion
                           \NC a combination of major and minor number \NC \NR
@@ -78,10 +81,10 @@ The official \LUATEX\ version is defined as follows:
     its use with \prm {the} depending on the context.
 \stopitem
 \startitem
-    The minor version is the two-digit result of \lpr {luatexversion} modulo 100.
+    The minor version is the two|-|digit result of \lpr {luatexversion} modulo 100.
 \stopitem
 \startitem
-    The revision is the given by \lpr {luatexrevision}. This primitive expands to
+    The revision is reported by \lpr {luatexrevision}. This primitive expands to
     a positive integer.
 \stopitem
 \startitem
@@ -113,7 +116,7 @@ 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 up to the user: subtypes larger than 255 indicate that
+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
@@ -121,15 +124,15 @@ to accommodate for a larger range of acceptable numbers. For instance, \prm
 {char} now accepts values between~0 and $1{,}114{,}111$. This should not be a
 problem for well|-|behaved input files, but it could create incompatibilities for
 input that would have generated an error when processed by older \TEX|-|based
-engines. The affected commands with an altered initial (left of the equals sign)
-or secondary (right of the equals sign) value are: \prm {char}, \prm {lccode},
+engines. The affected commands with an altered initial (left of the equal sign)
+or secondary (right of the equal sign) value are: \prm {char}, \prm {lccode},
 \prm {uccode}, \lpr {hjcode}, \prm {catcode}, \prm {sfcode}, \lpr {efcode}, \lpr
 {lpcode}, \lpr {rpcode}, \prm {chardef}.
 
 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 can be handled by a macro
+the \UNICODE\ input is on purpose not built|-|in and can be handled by a macro
 package during callback processing.
 
 Output in byte|-|sized chunks can be achieved by using characters just outside of
@@ -184,7 +187,7 @@ commands are:
 \stopfourcolumns
 
 Because font memory management has been rewritten, character properties in fonts
-are no longer shared among fonts instances that originate from the same metric
+are no longer shared among font instances that originate from the same metric
 file.
 
 \section{Attributes}
@@ -247,7 +250,7 @@ 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 oof this chapter.
+able to follow the rest of this chapter.
 
 \subsection{Box attributes}
 
@@ -455,10 +458,9 @@ sequence is fully expanded.
 \stopsyntax
 
 Most often, this command is not actually the best way to deal with the
-differences between the \TEX\ and \LUA. In very short bits of \LUA\
-code it is often not needed, and for longer stretches of \LUA\ code it
-is easier to keep the code in a separate file and load it using \LUA's
-\type {dofile}:
+differences between \TEX\ and \LUA. In very short bits of \LUA\ code it is often
+not needed, and for longer stretches of \LUA\ code it is easier to keep the code
+in a separate file and load it using \LUA's \type {dofile}:
 
 \starttyping
 \directlua { dofile('mysetups.lua') }
@@ -500,6 +502,33 @@ in the following example the number \type {8} gets typeset.
 The \lpr {luafunctioncall} primitive does the same but is unexpandable, for
 instance in an \prm {edef}.
 
+\subsection{\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.
+
+\starttyping
+\directlua {
+    lua.bytecode[9998] = function(s)
+        tex.sprint(s*token.scan_int())
+    end
+    lua.bytecode[5555] = function(s)
+        tex.sprint(s*token.scan_dimen())
+    end
+}
+\stoptyping
+
+This works with:
+
+\starttyping
+\luabytecode    9998 5  \luabytecode    5555 5sp
+\luabytecodecall9998 5  \luabytecodecall5555 5sp
+\stoptyping
+
+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}
 
 \subsection{\lpr {alignmark} and \lpr {aligntab}}
@@ -517,8 +546,8 @@ catcode regime in a single statement. You can have a practically unlimited numbe
 of different tables. This subsystem is backward compatible: if you never use the
 following commands, your document will not notice any difference in behaviour
 compared to traditional \TEX. The contents of each catcode table is independent
-from any other catcode tables, and their contents is stored and retrieved from
-the format file.
+from any other catcode table, and its contents is stored and retrieved from the
+format file.
 
 \subsection{\lpr {catcodetable}}
 
@@ -664,7 +693,7 @@ When set to a non|-|zero value the following command will not issue an error:
 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 differences approaches of traditional
+functionality. Much of this relates to the different approaches of traditional
 \TEX\ fonts and \OPENTYPE\ math.
 
 \section{Fonts}
@@ -799,7 +828,7 @@ expand the passed general text.
 
 These are somewhat special. The \prm {csstring} primitive is like
 \prm {string} but it omits the leading escape character. This can be
-somewhat more efficient that stripping it of afterwards.
+somewhat more efficient than stripping it afterwards.
 
 The \lpr {begincsname} primitive is like \prm {csname} but doesn't create
 a relaxed equivalent when there is no such name. It is equivalent to
@@ -822,7 +851,7 @@ is one that should be used with care. The above example could be written as:
 
 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.
+that it saves a few tokens and can make code a bit more readable.
 
 \subsection{\lpr {clearmarks}}
 
@@ -844,7 +873,7 @@ This primitive can be used to assign a meaning to an active character, as in:
 \def\foo{bar} \letcharcode123=\foo
 \stoptyping
 
-This can be a bit nicer that using the uppercase tricks (using the property of
+This can be a bit nicer than using the uppercase tricks (using the property of
 \prm {uppercase} that it treats active characters special).
 
 \section{Boxes, rules and leaders}
@@ -874,7 +903,7 @@ 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 Forms}
+\subsection[sec:imagedandforms]{Images and reused box objects}
 
 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,
@@ -890,7 +919,7 @@ should treat them as such and check for the current output mode if applicable.
 \DB command \BC explanation \NC \NR
 \TB
 \NC \lpr {saveboxresource}             \NC save the box as an object to be included later \NC \NR
-\NC \lpr {saveimageresource}           \NC save the image as an object to be includes later \NC \NR
+\NC \lpr {saveimageresource}           \NC save the image as an object to be included later \NC \NR
 \NC \lpr {useboxresource}              \NC include the saved box object here (by index) \NC \NR
 \NC \lpr {useimageresource}            \NC include the saved image object here (by index) \NC \NR
 \NC \lpr {lastsavedboxresourceindex}   \NC the index of the last saved box object \NC \NR
@@ -924,7 +953,7 @@ a \type {/Matrix}.
 Because introducing a new keyword can cause incompatibilities, two new primitives
 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).
+dimensions.
 
 \subsection{\lpr {gleaders}}
 
@@ -950,7 +979,7 @@ the value with the language.
 
 \subsection{\prm {boundary}, \prm {noboundary}, \prm {protrusionboundary} and \prm {wordboundary}}
 
-The \prm {noboundary} commands used to inject a whatsit node but now injects a normal
+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:
 
 \starttyping
@@ -1035,6 +1064,137 @@ 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:
+
+\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}.
+
+\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.
+
+\stopsection
+
 \stopchapter
 
 \stopcomponent