summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/context/documents/general/manuals/luatex.pdfbin1063120 -> 1068950 bytes
-rw-r--r--doc/context/documents/general/manuals/steps-mkiv.pdfbin297167 -> 307883 bytes
-rw-r--r--doc/context/documents/general/manuals/xml-mkiv.pdfbin1348594 -> 1351042 bytes
-rw-r--r--doc/context/documents/general/qrcs/setup-cs.pdfbin799508 -> 799581 bytes
-rw-r--r--doc/context/documents/general/qrcs/setup-de.pdfbin801177 -> 801364 bytes
-rw-r--r--doc/context/documents/general/qrcs/setup-en.pdfbin804150 -> 804340 bytes
-rw-r--r--doc/context/documents/general/qrcs/setup-fr.pdfbin798391 -> 799393 bytes
-rw-r--r--doc/context/documents/general/qrcs/setup-it.pdfbin799982 -> 800062 bytes
-rw-r--r--doc/context/documents/general/qrcs/setup-nl.pdfbin796496 -> 796873 bytes
-rw-r--r--doc/context/documents/general/qrcs/setup-ro.pdfbin795562 -> 796511 bytes
-rw-r--r--doc/context/sources/general/fonts/fonts/fonts-math.tex45
-rw-r--r--doc/context/sources/general/manuals/luatex/luatex-introduction.tex14
-rw-r--r--doc/context/sources/general/manuals/luatex/luatex-math.tex22
-rw-r--r--doc/context/sources/general/manuals/luatex/luatex-nodes.tex94
-rw-r--r--doc/context/sources/general/manuals/luatex/luatex.tex4
-rw-r--r--doc/context/sources/general/manuals/steps/steps-mkiv.tex88
-rw-r--r--doc/context/sources/general/manuals/xml/xml-mkiv.tex104
17 files changed, 341 insertions, 30 deletions
diff --git a/doc/context/documents/general/manuals/luatex.pdf b/doc/context/documents/general/manuals/luatex.pdf
index 0afa33cee..749c8f0dc 100644
--- a/doc/context/documents/general/manuals/luatex.pdf
+++ b/doc/context/documents/general/manuals/luatex.pdf
Binary files differ
diff --git a/doc/context/documents/general/manuals/steps-mkiv.pdf b/doc/context/documents/general/manuals/steps-mkiv.pdf
index f39b7be1b..f263d9e43 100644
--- a/doc/context/documents/general/manuals/steps-mkiv.pdf
+++ b/doc/context/documents/general/manuals/steps-mkiv.pdf
Binary files differ
diff --git a/doc/context/documents/general/manuals/xml-mkiv.pdf b/doc/context/documents/general/manuals/xml-mkiv.pdf
index 174bc395b..4ca2570d3 100644
--- a/doc/context/documents/general/manuals/xml-mkiv.pdf
+++ b/doc/context/documents/general/manuals/xml-mkiv.pdf
Binary files differ
diff --git a/doc/context/documents/general/qrcs/setup-cs.pdf b/doc/context/documents/general/qrcs/setup-cs.pdf
index 8061cba60..86ad7dd61 100644
--- a/doc/context/documents/general/qrcs/setup-cs.pdf
+++ b/doc/context/documents/general/qrcs/setup-cs.pdf
Binary files differ
diff --git a/doc/context/documents/general/qrcs/setup-de.pdf b/doc/context/documents/general/qrcs/setup-de.pdf
index 393df51ef..ff512abba 100644
--- a/doc/context/documents/general/qrcs/setup-de.pdf
+++ b/doc/context/documents/general/qrcs/setup-de.pdf
Binary files differ
diff --git a/doc/context/documents/general/qrcs/setup-en.pdf b/doc/context/documents/general/qrcs/setup-en.pdf
index bf623a1eb..a3be00bdf 100644
--- a/doc/context/documents/general/qrcs/setup-en.pdf
+++ b/doc/context/documents/general/qrcs/setup-en.pdf
Binary files differ
diff --git a/doc/context/documents/general/qrcs/setup-fr.pdf b/doc/context/documents/general/qrcs/setup-fr.pdf
index 3450920b8..cfed2bafc 100644
--- a/doc/context/documents/general/qrcs/setup-fr.pdf
+++ b/doc/context/documents/general/qrcs/setup-fr.pdf
Binary files differ
diff --git a/doc/context/documents/general/qrcs/setup-it.pdf b/doc/context/documents/general/qrcs/setup-it.pdf
index 46f80fd22..9b5e83cbe 100644
--- a/doc/context/documents/general/qrcs/setup-it.pdf
+++ b/doc/context/documents/general/qrcs/setup-it.pdf
Binary files differ
diff --git a/doc/context/documents/general/qrcs/setup-nl.pdf b/doc/context/documents/general/qrcs/setup-nl.pdf
index 13603b906..85e91d228 100644
--- a/doc/context/documents/general/qrcs/setup-nl.pdf
+++ b/doc/context/documents/general/qrcs/setup-nl.pdf
Binary files differ
diff --git a/doc/context/documents/general/qrcs/setup-ro.pdf b/doc/context/documents/general/qrcs/setup-ro.pdf
index 2bb62c200..21a3d7cee 100644
--- a/doc/context/documents/general/qrcs/setup-ro.pdf
+++ b/doc/context/documents/general/qrcs/setup-ro.pdf
Binary files differ
diff --git a/doc/context/sources/general/fonts/fonts/fonts-math.tex b/doc/context/sources/general/fonts/fonts/fonts-math.tex
index 2d7d26dfb..766204937 100644
--- a/doc/context/sources/general/fonts/fonts/fonts-math.tex
+++ b/doc/context/sources/general/fonts/fonts/fonts-math.tex
@@ -1,5 +1,19 @@
% language=uk
+% todo:
+
+% \starttext
+% \setupbodyfont[cambria]
+% \setupmathematics[kernpairs=yes]
+% $abcd$ % 𝑎𝑏
+% \stoptext
+%
+% kernpairs = {
+% [0x1D44E] = {
+% [0x1D44F] = 1000, -- 𝑎𝑏 demo
+% }
+% },
+
\startcomponent fonts-math
\environment fonts-environment
@@ -1043,6 +1057,37 @@ The defaults come out as:
\stopsection
+\startsection[title=Kerning]
+
+Math kerns in \OPENTYPE\ are quite advanced and use a staircase model left
+and|/|or right of characters. However, hardly any math font implements them
+(extensively). Therefore we provide a way to fine tune your fonts to your
+preferences. You can test this mechanism by patching \type {cambria-math.lfg} by
+adding this to the mathematics subtable:
+
+\starttyping
+kernpairs = {
+ [0x1D44E] = {
+ [0x1D44F] = 1000, -- 𝑎𝑏 demo
+ }
+}
+\stoptyping
+
+After that, the next example should work:
+
+\starttyping
+\starttext
+ \setupbodyfont[cambria]
+ \setupmathematics[kernpairs=yes]
+ $abcd$
+\stoptext
+\stoptyping
+
+There should be a gap between the $𝑎$ and $𝑏$. It is not shown here because I
+don't want to mess up my goodie file.
+
+\stopsection
+
\stopchapter
\stopcomponent
diff --git a/doc/context/sources/general/manuals/luatex/luatex-introduction.tex b/doc/context/sources/general/manuals/luatex/luatex-introduction.tex
index 8ab8b4463..196a9af4f 100644
--- a/doc/context/sources/general/manuals/luatex/luatex-introduction.tex
+++ b/doc/context/sources/general/manuals/luatex/luatex-introduction.tex
@@ -98,6 +98,14 @@ code in \TEX\ engines (especially code that is not needed any longer).
\stopitem
\stopitemize
+We try to keep upcoming versions compatible but intermediate releases can contain
+experimental features. A general rule is that versions that end up on \TEX live
+and|/|or are released around \CONTEXT\ meetings are stable. Future versions will
+probably become a bit leaner and meaner. Some libraries might become external as
+we don't want to bloat the binary and also don't want to add more hard coded
+solutions. After all, with \LUA\ you can extend the core functionality. The less
+dependencies, the better.
+
The \TEXLIVE\ version is to be considered the current stable version. Any version
between the yearly \TEXLIVE\ releases are to be considered beta. The beta
releases are normally available via the \CONTEXT\ distribution channels (the
@@ -112,8 +120,10 @@ Taco Hoekwater \& Luigi Scarso
\starttabulate
\NC Version \EQ \currentdate \NC \NR
-\NC \LUATEX \EQ Snapshot \number\luatexversion.\luatexrevision \NC \NR
-\NC \CONTEXT \EQ \contextversion \NC \NR
+\NC \LUATEX \EQ version \cldcontext{status.luatex_version/100},
+ revision \cldcontext{status.luatex_revision},
+ number \cldcontext{environment.luatexversion} \NC \NR
+\NC \CONTEXT \EQ MkIV \contextversion \NC \NR
\stoptabulate
\stopchapter
diff --git a/doc/context/sources/general/manuals/luatex/luatex-math.tex b/doc/context/sources/general/manuals/luatex/luatex-math.tex
index 1f92fc70c..b19f5823f 100644
--- a/doc/context/sources/general/manuals/luatex/luatex-math.tex
+++ b/doc/context/sources/general/manuals/luatex/luatex-math.tex
@@ -980,6 +980,28 @@ For Latin Modern The result looks as follows:
\stoptabulate
\stop
+\section {Last lines}
+
+There is a new primitive to control the overshoot in the calculation of the
+previous line in mid|-|paragraph display math. The default value is 2 times
+the em width of the current font:
+
+\starttyping
+\predisplaygapfactor=2000
+\stoptyping
+
+If you want to have the length of the last line independent of math i.e.\ you don't
+want to revert to a hack where you insert a fake display math formula in order to
+get the length of the last line, the following will often work too:
+
+\starttyping
+\def\lastlinelength{\dimexpr
+ \directlua {tex.sprint (
+ (nodes.dimensions(node.tail(tex.lists.page_head).list))
+ )}sp
+\relax}
+\stoptyping
+
\section {Other Math changes}
\subsection {Verbose versions of single-character math commands}
diff --git a/doc/context/sources/general/manuals/luatex/luatex-nodes.tex b/doc/context/sources/general/manuals/luatex/luatex-nodes.tex
index f9fe4e808..21f1789e5 100644
--- a/doc/context/sources/general/manuals/luatex/luatex-nodes.tex
+++ b/doc/context/sources/general/manuals/luatex/luatex-nodes.tex
@@ -1618,6 +1618,9 @@ The next call will return 5 values (or northing when no glue is passed).
<integer> shrink_order = node.getglue(<node> n)
\stopfunctioncall
+When the second argument is false, only the width is returned (this is consistent
+with \type {tex.get}).
+
\subsubsection{\type {node.is_zero_glue}}
This function returns \type {true} when the width, stretch and shrink properties
@@ -1796,7 +1799,7 @@ if next then
end
\stoptyping
-If performance matters you can use an function instead:
+Some accessors are used frequently and for these we provide more efficient helpers:
\starttabulate[|T|p|]
\NC getnext \NC parsing nodelist always involves this one \NC \NR
@@ -1807,11 +1810,10 @@ If performance matters you can use an function instead:
\NC getfont \NC used a lot in \OPENTYPE\ handling (glyph nodes are consulted a lot) \NC \NR
\NC getchar \NC idem and also in other places \NC \NR
\NC getwhd \NC returns the \type {width}, \type {height} and \type {depth} of a list, rule or
- (unexpanded) glyph \NC \NR
+ (unexpanded) glyph as well as glue (its spec is looked at) and unset nodes\NC \NR
\NC getdisc \NC returns the \type {pre}, \type {post} and \type {replace} fields and
optionally when true is passed also the tail fields. \NC \NR
-\NC getlist \NC we often parse nested lists so this is a convenient one too
- (only works for hlist and vlist!) \NC \NR
+\NC getlist \NC we often parse nested lists so this is a convenient one too \NC \NR
\NC getleader \NC comparable to list, seldom used in \TEX\ (but needs frequent consulting
like lists; leaders could have been made a dedicated node type) \NC \NR
\NC getfield \NC generic getter, sufficient for the rest (other field names are
@@ -1819,17 +1821,26 @@ If performance matters you can use an function instead:
\NC getbox \NC gets the given box (a list node) \NC \NR
\stoptabulate
-The direct variants also have setters, where the discretionary setter takes three
-(optional) arguments plus an optional fourth indicating the subtype. An additional
-setter is \type {setlink} which will link two nodes.
-
-It doesn't make sense to add getters for all fields, also because some are not
-unique to one node type. Profiling demonstrated that these fields can get
-accesses way more times than other fields. Even in complex documents, many node
-and fields types never get seen, or seen only a few times. Most functions in the
-\type {node} namespace have a companion in \type {node.direct}, but of course not
-the ones that don't deal with nodes themselves. The following table summarized
-this:
+In the direct namespace there are more such helpers and most of them are
+accompanied by setters. The getters and setters are clever enough to see what
+node is meant. We don't deal with whatsit nodes: their fields are always accessed
+by name. It doesn't make sense to add getters for all fields, we just identifier
+the most likely candidates. In complex documents, many node and fields types
+never get seen, or seen only a few times, but for instance glyphs are candidates
+for such optimization. The \type {node.direct} interface has some more helpers.
+\footnote {We can define the helpers in the node namespace with \type {getfield}
+which is about as efficient, so at some point we might provide that as module.}
+
+The \type {setdisc} helper takes three (optional) arguments plus an optional
+fourth indicating the subtype. Its \type {getdisc} takes an optional boolean;
+when its value is \type {true} the tail nodes will also be returned. The \type
+{setfont} helper takes an optional second argument, it being the character. The
+directmode setter \type {setlink} takes a list of nodes and will link them,
+thereby ignoring \type {nil} entries. The first valid node is returned (beware:
+for good reason it assumes single nodes). For rarely used fields no helpers are
+provided and there are a few that probably are used seldom too but were added for
+consistency. You can of course always define additional accessor using \type
+{getfield} and \type {setfield} with little overhead.
% \startcolumns[balance=yes]
@@ -1839,14 +1850,13 @@ this:
\HL
\NC \bf function \NC \bf node \NC \bf direct \NC \NR
\HL
+%NC \type {do_ligature_n} \NC \yes \NC \yes \NC \NR % was never documented and experimental
\NC \type {check_discretionaries}\NC \yes \NC \yes \NC \NR
\NC \type {copy_list} \NC \yes \NC \yes \NC \NR
\NC \type {copy} \NC \yes \NC \yes \NC \NR
\NC \type {count} \NC \yes \NC \yes \NC \NR
\NC \type {current_attr} \NC \yes \NC \yes \NC \NR
\NC \type {dimensions} \NC \yes \NC \yes \NC \NR
-\NC \type {rangedimensions} \NC \yes \NC \yes \NC \NR
-%NC \type {do_ligature_n} \NC \yes \NC \yes \NC \NR % was never documented and experimental
\NC \type {effective_glue} \NC \yes \NC \yes \NC \NR
\NC \type {end_of_math} \NC \yes \NC \yes \NC \NR
\NC \type {family_font} \NC \yes \NC \nop \NC \NR
@@ -1857,19 +1867,35 @@ this:
\NC \type {flush_node} \NC \yes \NC \yes \NC \NR
\NC \type {free} \NC \yes \NC \yes \NC \NR
\NC \type {get_attribute} \NC \yes \NC \yes \NC \NR
+\NC \type {getattributelist} \NC \nop \NC \yes \NC \NR
\NC \type {getboth} \NC \yes \NC \yes \NC \NR
\NC \type {getbox} \NC \nop \NC \yes \NC \NR
\NC \type {getchar} \NC \yes \NC \yes \NC \NR
+\NC \type {getcomponents} \NC \nop \NC \yes \NC \NR
+\NC \type {getdepth} \NC \nop \NC \yes \NC \NR
+\NC \type {getdir} \NC \nop \NC \yes \NC \NR
\NC \type {getdisc} \NC \yes \NC \yes \NC \NR
\NC \type {getfield} \NC \yes \NC \yes \NC \NR
\NC \type {getfont} \NC \yes \NC \yes \NC \NR
\NC \type {getglue} \NC \yes \NC \yes \NC \NR
+\NC \type {getheight} \NC \nop \NC \yes \NC \NR
\NC \type {getid} \NC \yes \NC \yes \NC \NR
+\NC \type {getkern} \NC \nop \NC \yes \NC \NR
+\NC \type {getlang} \NC \nop \NC \yes \NC \NR
\NC \type {getleader} \NC \yes \NC \yes \NC \NR
\NC \type {getlist} \NC \yes \NC \yes \NC \NR
\NC \type {getnext} \NC \yes \NC \yes \NC \NR
+\NC \type {getnucleus} \NC \nop \NC \yes \NC \NR
+\NC \type {getoffsets} \NC \nop \NC \yes \NC \NR
+\NC \type {getpenalty} \NC \nop \NC \yes \NC \NR
\NC \type {getprev} \NC \yes \NC \yes \NC \NR
+\NC \type {getproperty} \NC \yes \NC \yes \NC \NR
+\NC \type {getshift} \NC \nop \NC \yes \NC \NR
+\NC \type {getwidth} \NC \nop \NC \yes \NC \NR
+\NC \type {getwhd} \NC \nop \NC \yes \NC \NR
+\NC \type {getsub} \NC \nop \NC \yes \NC \NR
\NC \type {getsubtype} \NC \yes \NC \yes \NC \NR
+\NC \type {getsup} \NC \nop \NC \yes \NC \NR
\NC \type {has_attribute} \NC \yes \NC \yes \NC \NR
\NC \type {has_field} \NC \yes \NC \yes \NC \NR
\NC \type {has_glyph} \NC \yes \NC \yes \NC \NR
@@ -1893,18 +1919,38 @@ this:
\NC \type {protect_glyphs} \NC \yes \NC \yes \NC \NR
\NC \type {protect_glyph} \NC \yes \NC \yes \NC \NR
\NC \type {protrusion_skippable} \NC \yes \NC \yes \NC \NR
+\NC \type {rangedimensions} \NC \yes \NC \yes \NC \NR
\NC \type {remove} \NC \yes \NC \yes \NC \NR
-\NC \type {set_attribute} \NC \yes \NC \yes \NC \NR
-\NC \type {setboth} \NC \yes \NC \yes \NC \NR
+\NC \type {set_attribute} \NC \nop \NC \yes \NC \NR
+\NC \type {setattributelist} \NC \nop \NC \yes \NC \NR
+\NC \type {setboth} \NC \nop \NC \yes \NC \NR
\NC \type {setbox} \NC \nop \NC \yes \NC \NR
-\NC \type {setchar} \NC \yes \NC \yes \NC \NR
+\NC \type {setchar} \NC \nop \NC \yes \NC \NR
+\NC \type {setcomponents} \NC \nop \NC \yes \NC \NR
+\NC \type {setdepth} \NC \nop \NC \yes \NC \NR
+\NC \type {setdir} \NC \nop \NC \yes \NC \NR
\NC \type {setdisc} \NC \nop \NC \yes \NC \NR
-\NC \type {setwhd} \NC \nop \NC \yes \NC \NR
\NC \type {setfield} \NC \yes \NC \yes \NC \NR
+\NC \type {setfont} \NC \nop \NC \yes \NC \NR
\NC \type {setglue} \NC \yes \NC \yes \NC \NR
-\NC \type {setlink} \NC \yes \NC \yes \NC \NR
-\NC \type {setnext} \NC \yes \NC \yes \NC \NR
-\NC \type {setprev} \NC \yes \NC \yes \NC \NR
+\NC \type {setheight} \NC \nop \NC \yes \NC \NR
+\NC \type {setid} \NC \nop \NC \yes \NC \NR
+\NC \type {setkern} \NC \nop \NC \yes \NC \NR
+\NC \type {setlang} \NC \nop \NC \yes \NC \NR
+\NC \type {setleader} \NC \nop \NC \yes \NC \NR
+\NC \type {setlist} \NC \nop \NC \yes \NC \NR
+\NC \type {setnext} \NC \nop \NC \yes \NC \NR
+\NC \type {setnucleus} \NC \nop \NC \yes \NC \NR
+\NC \type {setoffsets} \NC \nop \NC \yes \NC \NR
+\NC \type {setpenalty} \NC \nop \NC \yes \NC \NR
+\NC \type {setprev} \NC \nop \NC \yes \NC \NR
+\NC \type {setproperty} \NC \nop \NC \yes \NC \NR
+\NC \type {setshift} \NC \nop \NC \yes \NC \NR
+\NC \type {setwidth} \NC \nop \NC \yes \NC \NR
+\NC \type {setwhd} \NC \nop \NC \yes \NC \NR
+\NC \type {setsub} \NC \nop \NC \yes \NC \NR
+\NC \type {setsubtype} \NC \nop \NC \yes \NC \NR
+\NC \type {setsup} \NC \nop \NC \yes \NC \NR
\NC \type {slide} \NC \yes \NC \yes \NC \NR
\NC \type {subtypes} \NC \yes \NC \nop \NC \NR
\NC \type {subtype} \NC \yes \NC \nop \NC \NR
diff --git a/doc/context/sources/general/manuals/luatex/luatex.tex b/doc/context/sources/general/manuals/luatex/luatex.tex
index 8cf87c47f..1ccc9b7a5 100644
--- a/doc/context/sources/general/manuals/luatex/luatex.tex
+++ b/doc/context/sources/general/manuals/luatex/luatex.tex
@@ -29,8 +29,8 @@
\dontcomplain
\startdocument
- [%status=release,
- version=1.0.2]
+ [status=intermediate release,
+ version=1.0.4]
\component luatex-titlepage
diff --git a/doc/context/sources/general/manuals/steps/steps-mkiv.tex b/doc/context/sources/general/manuals/steps/steps-mkiv.tex
index 3bbedbbcd..f0ca51613 100644
--- a/doc/context/sources/general/manuals/steps/steps-mkiv.tex
+++ b/doc/context/sources/general/manuals/steps/steps-mkiv.tex
@@ -141,6 +141,94 @@ These align around the mid element \type {c2}.
\stopsection
+\startsection[title=Lines]
+
+You can draw lines normally or dashes and with or without arrows in both
+directions. This is controlled by the \type {alternative} option of \type
+{\setupSTEPaligntable}. As an example we use this table:
+
+\startbuffer[table]
+\startSTEPaligntable
+ \cells {$2c$} {$=$} {$2a+3b$}
+ \text {with $a=5$}
+ \cells {$2c$}{$=$} {$10+3b$}
+ \text {and $b=6$}
+ \cells {$2c$} {$=$} {$10+18$}
+ \text {we get}
+\stopSTEPaligntable
+\stopbuffer
+
+\typebuffer[table]
+
+Next we show the (currently) 9 alternatives. The zero alternative draws no lines
+so there we can make the distance smaller.
+
+\startbuffer
+\setupSTEPlines
+ [alternative=0,
+ width=.5em]
+\stopbuffer
+
+\typebuffer \startlinecorrection \getbuffer \getbuffer[table] \stoplinecorrection
+
+\startbuffer
+\setupSTEPlines
+ [alternative=1]
+\stopbuffer
+
+\typebuffer \startlinecorrection \getbuffer \getbuffer[table] \stoplinecorrection
+
+\startbuffer
+\setupSTEPlines
+ [alternative=2]
+\stopbuffer
+
+\typebuffer \startlinecorrection \getbuffer \getbuffer[table] \stoplinecorrection
+
+\startbuffer
+\setupSTEPlines
+ [alternative=3]
+\stopbuffer
+
+\typebuffer \startlinecorrection \getbuffer \getbuffer[table] \stoplinecorrection
+
+\startbuffer
+\setupSTEPlines
+ [alternative=4]
+\stopbuffer
+
+\typebuffer \startlinecorrection \getbuffer \getbuffer[table] \stoplinecorrection
+
+\startbuffer
+\setupSTEPlines
+ [alternative=5]
+\stopbuffer
+
+\typebuffer \startlinecorrection \getbuffer \getbuffer[table] \stoplinecorrection
+
+\startbuffer
+\setupSTEPlines
+ [alternative=6]
+\stopbuffer
+
+\typebuffer \startlinecorrection \getbuffer \getbuffer[table] \stoplinecorrection
+
+\startbuffer
+\setupSTEPlines
+ [alternative=7]
+\stopbuffer
+
+\typebuffer \startlinecorrection \getbuffer \getbuffer[table] \stoplinecorrection
+
+\startbuffer
+\setupSTEPlines
+ [alternative=8]
+\stopbuffer
+
+\typebuffer \startlinecorrection \getbuffer \getbuffer[table] \stoplinecorrection
+
+\stopsection
+
\startsection[title=Usage]
The step chart module is loaded with:
diff --git a/doc/context/sources/general/manuals/xml/xml-mkiv.tex b/doc/context/sources/general/manuals/xml/xml-mkiv.tex
index 6e6deead0..80d51532f 100644
--- a/doc/context/sources/general/manuals/xml/xml-mkiv.tex
+++ b/doc/context/sources/general/manuals/xml/xml-mkiv.tex
@@ -3213,8 +3213,108 @@ visualizer to show the steps. Some are shown more than once as part of a set.
\xmllshow{child::something/child::whatever/self::whatever}
There is also \type {last-match::} that starts with the last found set of nodes.
-This can save some runtime when you do lots of tests combined with a same check
-afterwards.
+This can save some run time when you do lots of tests combined with a same check
+afterwards. There is however one pitfall: you never know what is done with that
+last match in the setup that gets called nested. Take the following example:
+
+\starttyping
+\startbuffer[test]
+<something>
+ <crap> <crapa> <crapb> <crapc> <crapd>
+ <crape>
+ done 1
+ </crape>
+ </crapd> </crapc> </crapb> </crapa>
+ <crap> <crapa> <crapb> <crapc> <crapd>
+ <crape>
+ done 2
+ </crape>
+ </crapd> </crapc> </crapb> </crapa>
+ <crap> <crapa> <crapb> <crapc> <crapd>
+ <crape>
+ done 3
+ </crape>
+ </crapd> </crapc> </crapb> </crapa>
+</something>
+\stopbuffer
+\stoptyping
+
+One way to filter the content is this:
+
+\starttyping
+\xmldoif {#1} {/crap/crapa/crapb/crapc/crapd/crape} {
+ some action
+}
+\stoptyping
+
+It is not unlikely that you will do something like this:
+
+\starttyping
+\xmlfirst {#1} {/crap/crapa/crapb/crapc/crapd/crape} {
+ \xmlfirst{#1}{/crap/crapa/crapb/crapc/crapd/crape}
+}
+\stoptyping
+
+This means that the path is resolved twice but that can be avoided as
+follows:
+
+\starttyping
+\xmldoif{#1}{/crap/crapa/crapb/crapc/crapd/crape}{
+ \xmlfirst{#1}{last-match::}
+}
+\stoptyping
+
+But the next is now guaranteed to work:
+
+\starttyping
+\xmldoif{#1}{/crap/crapa/crapb/crapc/crapd/crape}{
+ \xmlfirst{#1}{last-match::}
+ \xmllast{#1}{last-match::}
+}
+\stoptyping
+
+Because the first one can have done some lookup the last match can be replaced
+and the second call will give unexpected results. You can overcome this with:
+
+\starttyping
+\xmldoif{#1}{/crap/crapa/crapb/crapc/crapd/crape}{
+ \xmlpushmatch
+ \xmlfirst{#1}{last-match::}
+ \xmlpopmatch
+}
+\stoptyping
+
+Does it pay off? Here are some timings of a 10.000 times text and lookup
+like the previous (on a decent Januari 2016 laptop):
+
+\starttabulate[|r|l|]
+\NC 0.239 \NC \type {\xmldoif {...} {...}} \NC \NR
+\NC 0.292 \NC \type {\xmlfirst {...} {...}} \NC \NR
+\NC 0.538 \NC \type {\xmldoif {...} {...} + \xmlfirst {...} {...}} \NC \NR
+\NC 0.338 \NC \type {\xmldoif {...} {...} + \xmlfirst {...} {last-match::}} \NC \NR
+\NC 0.349 \NC \type {+ \xmldoif {...} {...} + \xmlfirst {...} {last-match::}-} \NC \NR
+\stoptabulate
+
+So, pushing and popping (the last row) is a bit slower than not doing that but it
+is still much faster than not using \type {last-match::} at all. As a shortcut
+you can use \type {=}, as in:
+
+\starttyping
+\xmlfirst{#1}{=}
+\stoptyping
+
+You can even do this:
+
+\starttyping
+\xmlall{#1}{last-match::/text()}
+\stoptyping
+
+or
+
+\starttyping
+\xmlall{#1}{=/text()}
+\stoptyping
+
\stopsection