2021-09-03 18:47:00

6 files changed, 650 insertions, 8 deletions

diff --git a/doc/context/documents/general/manuals/lowlevel-marks.pdf b/doc/context/documents/general/manuals/lowlevel-marks.pdf
new file mode 100644
index 000000000..e4f600b5d
--- /dev/null
+++ b/doc/context/documents/general/manuals/lowlevel-marks.pdf
diff --git a/doc/context/sources/general/manuals/interaction/interaction-buttons.tex b/doc/context/sources/general/manuals/interaction/interaction-buttons.tex
index d083a61a7..1a8e698cf 100644
--- a/doc/context/sources/general/manuals/interaction/interaction-buttons.tex
+++ b/doc/context/sources/general/manuals/interaction/interaction-buttons.tex
@@ -89,7 +89,7 @@ An overlay button adapts its size to the current overlay so you don't need to
 worry about passing dimensions.
 
 It is possible to define more complex buttons, like roll|-|over buttons or
-buttons that change appearance when you clock on them. These are more resource
+buttons that change appearance when you click on them. These are more resource
 hungry and also depend on the viewer. These will discussed in the chapter about
 widgets.
 
diff --git a/doc/context/sources/general/manuals/lowlevel/lowlevel-alignments.tex b/doc/context/sources/general/manuals/lowlevel/lowlevel-alignments.tex
index d0a3c47af..bdc7fecf1 100644
--- a/doc/context/sources/general/manuals/lowlevel/lowlevel-alignments.tex
+++ b/doc/context/sources/general/manuals/lowlevel/lowlevel-alignments.tex
@@ -695,3 +695,25 @@ to add these.
 \stopsection
 
 \stopdocument
+
+% \hbox \bgroup
+%     \vbox \bgroup \halign \bgroup
+%         \hss\aligncontent\hss\aligntab
+%         \hss\aligncontent\hss\cr
+%         aaaa\aligntab bbbb\cr
+%         aaa\aligntab bbb\cr
+%         aa\aligntab bb\cr
+%         a\aligntab b\cr
+%         \omit\span \hss ccc\hss\cr
+%     \egroup \egroup
+%     \quad
+%     \vbox \bgroup \halign noskips \bgroup
+%         \hss\aligncontent\hss\aligntab
+%         \hss\aligncontent\hss\cr
+%         aaaa\aligntab bbbb\cr
+%         aaa\aligntab bbb\cr
+%         aa\aligntab bb\cr
+%         a\aligntab b\cr
+%         \omit\span \hss ccc\hss\cr
+%     \egroup \egroup
+% \egroup
diff --git a/doc/context/sources/general/manuals/lowlevel/lowlevel-marks.tex b/doc/context/sources/general/manuals/lowlevel/lowlevel-marks.tex
new file mode 100644
index 000000000..6eef0dd01
--- /dev/null
+++ b/doc/context/sources/general/manuals/lowlevel/lowlevel-marks.tex
@@ -0,0 +1,506 @@
+% language=us runpath=texruns:manuals/lowlevel
+
+\startcomponent lowlevel-marks
+
+\environment lowlevel-style
+
+\startdocument
+  [title=marks,
+   color=middlemagenta]
+
+\startsection[title=Introduction]
+
+Marks are one of the subsystems of \TEX, as are for instance alignments and math
+as well as inserts which they share some properties with. Both inserts and marks
+put signals in the list that later on get intercepted and can be used to access
+stored information. In the case of inserts this is typeset materials, like
+footnotes, and in the case of marks it's token lists. Inserts are taken into
+account when breaking pages, and marks show up when a page has been broken and is
+presented to the output routine. Marks are used for running headers but other
+applications are possible.
+
+In \MKII\ marks are used to keep track of colors, transparencies and more
+properties that work across page boundaries. It permits picking up at the top of
+a page from where one left at the bottom of the preceding one. When \MKII\ was
+written there was only one mark so on top of that a multiple mark mechanism was
+implemented that filtered specific marks from a collection. Later, \ETEX\
+provided mark classes so that mechanism could be simplified. Although it is not
+that hard to do, this extension to \TEX\ didn't add any further features, so we
+can assume that there was no real demand for that. \footnote {This is probably
+true for most \LUATEX\ and \LUAMETATEX\ extensions, maybe example usage create
+retrospective demand. But one reason for picking up on engine development is that
+in the \CONTEXT\ perspective we actually had some demands.}
+
+But, marks have some nasty limitations, so from the \CONTEXT\ perspective there
+always was something to wish for. When you hide marks in boxes they will not be
+seen (the same is true for inserts). You cannot really reset them either. Okay,
+you can set them to nothing, but even then already present marks are still there.
+The \LUATEX\ engine has a \type {\clearmarks} primitive but that works global. In
+\LUAMETATEX\ a proper mark flusher is available. That engine also can work around
+the deeply nested disappearing marks. In addition, the current state of a mark
+can be queried and we have some tracing facilities.
+
+In \MKIV\ the engine's marks were not used at all and an alternative mechanism
+was written using \LUA. It actually is one of the older \MKIV\ features. It
+doesn't have the side effects that native marks have but it comes at the price of
+more overhead, although that is bearable.
+
+In this document we discuss marks but assume that \LUAMETATEX\ is used with
+\CONTEXT\ \LMTX. There we experiment with using the native marks, complemented by
+a few \LUA\ mechanisms, but it is to be seen if that will be either a replacement
+or an alternative.
+
+\stopsection
+
+\startsection[title=The basics]
+
+Although the original \TEX\ primitives are there, the plural \ETEX\ mark commands
+are to be used. Marks, signals with token lists, are set with:
+
+\starttyping[option=TEX]
+\marks0{This is mark 0} % equivalent to: \mark{This is mark 0}
+\marks4{This is mark 4}
+\stoptyping
+
+When a page has been split off, you can (normally this only makes sense in the
+output routine) access marks with:
+
+\starttyping[option=TEX]
+\topmarks  4
+\firstmarks4
+\botmarks  4
+\stoptyping
+
+A \quote {top} mark is the last one on the previous page(s), the \quote {first}
+and \quote {bottom} refer to the current page. A mark is a so called node,
+something that ends up in the current list and the token list is stored with it.
+The accessors are just commands and they fetch the token list from a separately
+managed storage. When you set or access a mark that has not yet been used, the
+storage is bumped to the right size, so it doesn't make sense to use e.g. \type
+{\marks 999} when there are no 998 ones too: it not only takes memory, it also
+makes \TEX\ run over all these mark stores when synchronization happens. The best
+way to make sure that you are sparse is:
+
+\starttyping[option=TEX]
+\newmarks\MyMark
+\stoptyping
+
+Currently the first 16 marks are skipped so this makes \type {\MyMark} become
+mark 17. The reason is that we want to make sure that users who experiment with
+marks have some scratch marks available and don't overload system defined ones.
+Future versions of \CONTEXT\ might become more restrictive.
+
+Marks can be cleared with:
+
+\starttyping[option=TEX]
+\clearmarks 4
+\stoptyping
+
+which clears the storage that keeps the top, first and bot marks. This happens
+immediately. You can delay this by putting a signal in the list:
+
+\starttyping[option=TEX]
+\flushmarks 4
+\stoptyping
+
+This (\LUAMETATEX) feature makes it for instance easy to reset marks that keep
+track of section (and lower) titles when a new chapter starts. Of course it still
+means that one has to implement some mechanism that deals with this but \CONTEXT\
+always had that.
+
+The current, latest assigned, value of a mark is available too:
+
+\starttyping[option=TEX]
+\currentmarks 4
+\stoptyping
+
+Using this value in for instance headers and footers makes no sense because the
+last node set can be on a following page.
+
+\stopsection
+
+\startsection[title=Migration]
+
+In the introduction we mentioned that \LUAMETATEX\ has migration built in. In
+\MKIV\ we have this as option too, but there it is delegated to \LUA. It permits
+deeply nested inserts (notes) and marks (but we don't use native marks in \MKIV).
+
+Migrated marks end up in the postmigrated sublist of a box. In other lowlevel
+manuals we discuss these pre- and postmigrated sublists. As example we use this
+definition:
+
+\startbuffer
+\setbox0\vbox\bgroup
+test \marks 4 {mark 4.1}\par
+test \marks 4 {mark 4.1}\par
+test \marks 4 {mark 4.1}\par
+\egroup
+\stopbuffer
+
+\typebuffer[option=TEX]
+
+% {\automigrationmode"FF \getbuffer\showbox0}
+% {\automigrationmode"00 \getbuffer\showbox0}
+
+When we turn migration on (officially the second bit):
+
+\starttyping[option=TEX]
+\automigrationmode"FF \showbox0
+\stoptyping
+
+we get this:
+
+\start \switchtobodyfont[5pt]
+\starttyping[option=TEX]
+> \box0=
+2:4: \vbox[normal][...], width 483.69687, height 63.43475, depth 0.15576, direction l2r
+2:4: .\list
+2:4: ..\hbox[line][...], width 483.69687, height 7.48193, depth 0.15576, glue 459.20468fil, direction l2r
+2:4: ...\list
+2:4: ....\glue[left hang][...] 0.0pt
+2:4: ....\glue[left][...] 0.0pt
+2:4: ....\glue[parfillleft][...] 0.0pt
+2:4: ....\par[newgraf][...], hangafter 1, hsize 483.69687, pretolerance 100, tolerance 200, adjdemerits 10000, linepenalty 10, doublehyphendemerits 10000, finalhyphendemerits 5000, clubpenalty 2000, widowpenalty 2000, brokenpenalty 100, parfillskip 0.0pt plus 1.0fil, hyphenationmode 499519
+2:4: ....\glue[indent][...] 0.0pt
+2:4: ....\glyph[32768][...], language (n=1,l=2,r=3), hyphenationmode "79F3F, options "80, font <8: DejaVuSerif @ 11.0pt>, glyph U+000074 t
+2:4: ....\glyph[32768][...], language (n=1,l=2,r=3), hyphenationmode "79F3F, options "80, font <8: DejaVuSerif @ 11.0pt>, glyph U+000065 e
+2:4: ....\glyph[32768][...], language (n=1,l=2,r=3), hyphenationmode "79F3F, options "80, font <8: DejaVuSerif @ 11.0pt>, glyph U+000073 s
+2:4: ....\glyph[32768][...], language (n=1,l=2,r=3), hyphenationmode "79F3F, options "80, font <8: DejaVuSerif @ 11.0pt>, glyph U+000074 t
+2:4: ....\glue[space][...] 3.49658pt plus 1.74829pt minus 1.16553pt, font 8
+2:4: ....\penalty[line][...] 10000
+2:4: ....\glue[parfill][...] 0.0pt plus 1.0fil
+2:4: ....\glue[right][...] 0.0pt
+2:4: ....\glue[right hang][...] 0.0pt
+2:4: ..\glue[par][...] 11.98988pt plus 3.99663pt minus 3.99663pt
+2:4: ..\glue[baseline][...] 8.34883pt
+2:4: ..\hbox[line][...], width 483.69687, height 7.48193, depth 0.15576, glue 459.20468fil, direction l2r
+2:4: ...\list
+2:4: ....\glue[left hang][...] 0.0pt
+2:4: ....\glue[left][...] 0.0pt
+2:4: ....\glue[parfillleft][...] 0.0pt
+2:4: ....\par[newgraf][...], hangafter 1, hsize 483.69687, pretolerance 100, tolerance 200, adjdemerits 10000, linepenalty 10, doublehyphendemerits 10000, finalhyphendemerits 5000, clubpenalty 2000, widowpenalty 2000, brokenpenalty 100, parfillskip 0.0pt plus 1.0fil, hyphenationmode 499519
+2:4: ....\glue[indent][...] 0.0pt
+2:4: ....\glyph[32768][...], language (n=1,l=2,r=3), hyphenationmode "79F3F, options "80, font <8: DejaVuSerif @ 11.0pt>, glyph U+000074 t
+2:4: ....\glyph[32768][...], language (n=1,l=2,r=3), hyphenationmode "79F3F, options "80, font <8: DejaVuSerif @ 11.0pt>, glyph U+000065 e
+2:4: ....\glyph[32768][...], language (n=1,l=2,r=3), hyphenationmode "79F3F, options "80, font <8: DejaVuSerif @ 11.0pt>, glyph U+000073 s
+2:4: ....\glyph[32768][...], language (n=1,l=2,r=3), hyphenationmode "79F3F, options "80, font <8: DejaVuSerif @ 11.0pt>, glyph U+000074 t
+2:4: ....\glue[space][...] 3.49658pt plus 1.74829pt minus 1.16553pt, font 8
+2:4: ....\penalty[line][...] 10000
+2:4: ....\glue[parfill][...] 0.0pt plus 1.0fil
+2:4: ....\glue[right][...] 0.0pt
+2:4: ....\glue[right hang][...] 0.0pt
+2:4: ..\glue[par][...] 11.98988pt plus 3.99663pt minus 3.99663pt
+2:4: ..\glue[baseline][...] 8.34883pt
+2:4: ..\hbox[line][...], width 483.69687, height 7.48193, depth 0.15576, glue 459.20468fil, direction l2r
+2:4: ...\list
+2:4: ....\glue[left hang][...] 0.0pt
+2:4: ....\glue[left][...] 0.0pt
+2:4: ....\glue[parfillleft][...] 0.0pt
+2:4: ....\par[newgraf][...], hangafter 1, hsize 483.69687, pretolerance 100, tolerance 200, adjdemerits 10000, linepenalty 10, doublehyphendemerits 10000, finalhyphendemerits 5000, clubpenalty 2000, widowpenalty 2000, brokenpenalty 100, parfillskip 0.0pt plus 1.0fil, hyphenationmode 499519
+2:4: ....\glue[indent][...] 0.0pt
+2:4: ....\glyph[32768][...], language (n=1,l=2,r=3), hyphenationmode "79F3F, options "80, font <8: DejaVuSerif @ 11.0pt>, glyph U+000074 t
+2:4: ....\glyph[32768][...], language (n=1,l=2,r=3), hyphenationmode "79F3F, options "80, font <8: DejaVuSerif @ 11.0pt>, glyph U+000065 e
+2:4: ....\glyph[32768][...], language (n=1,l=2,r=3), hyphenationmode "79F3F, options "80, font <8: DejaVuSerif @ 11.0pt>, glyph U+000073 s
+2:4: ....\glyph[32768][...], language (n=1,l=2,r=3), hyphenationmode "79F3F, options "80, font <8: DejaVuSerif @ 11.0pt>, glyph U+000074 t
+2:4: ....\glue[space][...] 3.49658pt plus 1.74829pt minus 1.16553pt, font 8
+2:4: ....\penalty[line][...] 10000
+2:4: ....\glue[parfill][...] 0.0pt plus 1.0fil
+2:4: ....\glue[right][...] 0.0pt
+2:4: ....\glue[right hang][...] 0.0pt
+2:4: .\postmigrated
+2:4: ..\mark[4][...]
+2:4: ..{mark 4.1}
+2:4: ..\mark[4][...]
+2:4: ..{mark 4.1}
+2:4: ..\mark[4][...]
+2:4: ..{mark 4.1}
+\stoptyping
+\stop
+
+When we don't migrate, enforced with:
+
+\starttyping[option=TEX]
+\automigrationmode"00 \showbox0
+\stoptyping
+
+the result is:
+
+\start \switchtobodyfont[5pt]
+\starttyping[option=TEX]
+> \box0=
+2:4: \vbox[normal][...], width 483.69687, height 63.43475, depth 0.15576, direction l2r
+2:4: .\list
+2:4: ..\hbox[line][...], width 483.69687, height 7.48193, depth 0.15576, glue 459.20468fil, direction l2r
+2:4: ...\list
+2:4: ....\glue[left hang][...] 0.0pt
+2:4: ....\glue[left][...] 0.0pt
+2:4: ....\glue[parfillleft][...] 0.0pt
+2:4: ....\par[newgraf][...], hangafter 1, hsize 483.69687, pretolerance 100, tolerance 200, adjdemerits 10000, linepenalty 10, doublehyphendemerits 10000, finalhyphendemerits 5000, clubpenalty 2000, widowpenalty 2000, brokenpenalty 100, parfillskip 0.0pt plus 1.0fil, hyphenationmode 499519
+2:4: ....\glue[indent][...] 0.0pt
+2:4: ....\glyph[32768][...], language (n=1,l=2,r=3), hyphenationmode "79F3F, options "80, font <8: DejaVuSerif @ 11.0pt>, glyph U+000074 t
+2:4: ....\glyph[32768][...], language (n=1,l=2,r=3), hyphenationmode "79F3F, options "80, font <8: DejaVuSerif @ 11.0pt>, glyph U+000065 e
+2:4: ....\glyph[32768][...], language (n=1,l=2,r=3), hyphenationmode "79F3F, options "80, font <8: DejaVuSerif @ 11.0pt>, glyph U+000073 s
+2:4: ....\glyph[32768][...], language (n=1,l=2,r=3), hyphenationmode "79F3F, options "80, font <8: DejaVuSerif @ 11.0pt>, glyph U+000074 t
+2:4: ....\glue[space][...] 3.49658pt plus 1.74829pt minus 1.16553pt, font 8
+2:4: ....\penalty[line][...] 10000
+2:4: ....\glue[parfill][...] 0.0pt plus 1.0fil
+2:4: ....\glue[right][...] 0.0pt
+2:4: ....\glue[right hang][...] 0.0pt
+2:4: ..\mark[4][...]
+2:4: ..{mark 4.1}
+2:4: ..\glue[par][...] 11.98988pt plus 3.99663pt minus 3.99663pt
+2:4: ..\glue[baseline][...] 8.34883pt
+2:4: ..\hbox[line][...], width 483.69687, height 7.48193, depth 0.15576, glue 459.20468fil, direction l2r
+2:4: ...\list
+2:4: ....\glue[left hang][...] 0.0pt
+2:4: ....\glue[left][...] 0.0pt
+2:4: ....\glue[parfillleft][...] 0.0pt
+2:4: ....\par[newgraf][...], hangafter 1, hsize 483.69687, pretolerance 100, tolerance 200, adjdemerits 10000, linepenalty 10, doublehyphendemerits 10000, finalhyphendemerits 5000, clubpenalty 2000, widowpenalty 2000, brokenpenalty 100, parfillskip 0.0pt plus 1.0fil, hyphenationmode 499519
+2:4: ....\glue[indent][...] 0.0pt
+2:4: ....\glyph[32768][...], language (n=1,l=2,r=3), hyphenationmode "79F3F, options "80, font <8: DejaVuSerif @ 11.0pt>, glyph U+000074 t
+2:4: ....\glyph[32768][...], language (n=1,l=2,r=3), hyphenationmode "79F3F, options "80, font <8: DejaVuSerif @ 11.0pt>, glyph U+000065 e
+2:4: ....\glyph[32768][...], language (n=1,l=2,r=3), hyphenationmode "79F3F, options "80, font <8: DejaVuSerif @ 11.0pt>, glyph U+000073 s
+2:4: ....\glyph[32768][...], language (n=1,l=2,r=3), hyphenationmode "79F3F, options "80, font <8: DejaVuSerif @ 11.0pt>, glyph U+000074 t
+2:4: ....\glue[space][...] 3.49658pt plus 1.74829pt minus 1.16553pt, font 8
+2:4: ....\penalty[line][...] 10000
+2:4: ....\glue[parfill][...] 0.0pt plus 1.0fil
+2:4: ....\glue[right][...] 0.0pt
+2:4: ....\glue[right hang][...] 0.0pt
+2:4: ..\mark[4][...]
+2:4: ..{mark 4.1}
+2:4: ..\glue[par][...] 11.98988pt plus 3.99663pt minus 3.99663pt
+2:4: ..\glue[baseline][...] 8.34883pt
+2:4: ..\hbox[line][...], width 483.69687, height 7.48193, depth 0.15576, glue 459.20468fil, direction l2r
+2:4: ...\list
+2:4: ....\glue[left hang][...] 0.0pt
+2:4: ....\glue[left][...] 0.0pt
+2:4: ....\glue[parfillleft][...] 0.0pt
+2:4: ....\par[newgraf][...], hangafter 1, hsize 483.69687, pretolerance 100, tolerance 200, adjdemerits 10000, linepenalty 10, doublehyphendemerits 10000, finalhyphendemerits 5000, clubpenalty 2000, widowpenalty 2000, brokenpenalty 100, parfillskip 0.0pt plus 1.0fil, hyphenationmode 499519
+2:4: ....\glue[indent][...] 0.0pt
+2:4: ....\glyph[32768][...], language (n=1,l=2,r=3), hyphenationmode "79F3F, options "80, font <8: DejaVuSerif @ 11.0pt>, glyph U+000074 t
+2:4: ....\glyph[32768][...], language (n=1,l=2,r=3), hyphenationmode "79F3F, options "80, font <8: DejaVuSerif @ 11.0pt>, glyph U+000065 e
+2:4: ....\glyph[32768][...], language (n=1,l=2,r=3), hyphenationmode "79F3F, options "80, font <8: DejaVuSerif @ 11.0pt>, glyph U+000073 s
+2:4: ....\glyph[32768][...], language (n=1,l=2,r=3), hyphenationmode "79F3F, options "80, font <8: DejaVuSerif @ 11.0pt>, glyph U+000074 t
+2:4: ....\glue[space][...] 3.49658pt plus 1.74829pt minus 1.16553pt, font 8
+2:4: ....\penalty[line][...] 10000
+2:4: ....\glue[parfill][...] 0.0pt plus 1.0fil
+2:4: ....\glue[right][...] 0.0pt
+2:4: ....\glue[right hang][...] 0.0pt
+2:4: ..\mark[4][...]
+2:4: ..{mark 4.1}
+\stoptyping
+\stop
+
+When you say \type {\showmakeup} or in this case \type {\showmakeup[mark]} the marks
+are visualized:
+
+\startlinecorrection
+    \startcombination
+        {\framed{\automigrationmode"FF \showmakeup[mark]\hsize2cm \getbuffer\box0}} {enabled}
+        {\framed{\automigrationmode"00 \showmakeup[mark]\hsize2cm \getbuffer\box0}} {disabled}
+    \stopcombination
+\stoplinecorrection
+
+Here \type {sm} means \quote {set mark} while \type {rm} would indicate a \quote
+{reset mark}. Of course migrated marks don't show up because these are bound to
+the box and thereby have become a a specific box property as can be seen in the
+above trace.
+
+\stopsection
+
+\startsection[title=Tracing]
+
+The \LUAMETATEX\ engine has a dedicated tracing option for marks. The fact that
+the traditional engine doesn't have this can be seen as indication that this is
+seldom needed.
+
+\starttyping[option=TEX]
+\tracingmarks1
+\tracingonline2
+\stoptyping
+
+When tracing is set to 1 we get a list of marks for the just split of page:
+
+\starttyping
+2:7: <mark class 51, top := bot>
+2:7: ..{sample 9.1}
+2:7: <mark class 51: first := mark>
+2:7: ..{sample 10.1}
+2:7: <mark class 51: bot := mark>
+2:7: ..{sample 10.1}
+2:7: <mark class 51, page state>
+2:7: ..top {sample 9.1}
+2:7: ..first {sample 10.1}
+2:7: ..bot {sample 10.1}
+\stoptyping
+
+When tracing is set to 2 you also get details we get a list of marks of the analysis:
+
+\starttyping
+1:9: <mark class 51, top := bot>
+1:9: ..{sample 5.1}
+1:9: <mark class 51: first := mark>
+1:9: ..{sample 6.1}
+1:9: <mark class 51: bot := mark>
+1:9: ..{sample 6.1}
+1:9: <mark class 51: bot := mark>
+1:9: ..{sample 7.1}
+1:9: <mark class 51: bot := mark>
+1:9: ..{sample 8.1}
+1:9: <mark class 51: bot := mark>
+1:9: ..{sample 9.1}
+1:9: <mark class 51, page state>
+1:9: ..top {sample 5.1}
+1:9: ..first {sample 6.1}
+1:9: ..bot {sample 9.1}
+\stoptyping
+
+\stopsection
+
+\startsection[title=High level commands]
+
+I think that not that many users define their own marks. They are useful for
+showing section related titles in headers and footers but the implementation of
+that is hidden. The native mark references are \type {top}, \type {first} and
+\type {bottom} but in the \CONTEXT\ interface we use different keywords.
+
+\starttabulate[|||||]
+\FL
+\BC \CONTEXT         \BC \TEX  \BC column                  \BC page                  \NC \NR
+\ML
+\NC \type {previous} \NC top   \NC last before sync        \NC last on previous page \NC \NR
+%NC \type {next}     \NC       \NC first after sync        \NC                       \NC \NR
+\NC \type {top}      \NC first \NC first in sync           \NC first on page         \NC \NR
+\NC \type {bottom}   \NC bot   \NC last in sync            \NC last on page          \NC \NR
+\NC \type {first}    \NC top   \NC first not top in sync   \NC first on page         \NC \NR
+\NC \type {last}     \NC bot   \NC last not bottom in sync \NC last on page          \NC \NR
+\ML
+\NC \type {default}  \NS[2][c] the same as \type {first} \NC \NR
+\NC \type {current}  \NS[2][c] the last set value        \NC \NR
+\LL
+\stoptabulate
+
+In order to separate marks in \CONTEXT\ from those in \TEX, the term \quote
+{marking} is used. In \MKIV\ the regular marks mechanism is of course there but,
+as mentioned, not used. By using a different namespace we could make the
+transition from \MKII\ to \MKIV\ (the same is true for some more mechanisms).
+
+A marking is defined with
+
+\starttyping[option=TEX]
+\definemarking[MyMark]
+\stoptyping
+
+A defined marking can be set with two equivalent commands:
+
+\starttyping[option=TEX]
+\setmarking[MyMark]{content}
+\marking   [MyMark]{content}
+\stoptyping
+
+The content is not typeset but stored as token list. In the sectioning mechanism
+that uses markings we don't even store titles, we store a reference to a title.
+In order to use that (deep down) we hook in a filter command. By default that command
+does nothing:
+
+\starttyping[option=TEX]
+\setupmarking[MyMark][filtercommand=\firstofoneargument]
+\stoptyping
+
+The token list does {\em not} get expanded by default, unless you set it up:
+
+\starttyping[option=TEX]
+\setupmarking[MyMark][expansion=yes]
+\stoptyping
+
+The current state of a marking can be cleared with:
+
+\starttyping[option=TEX]
+\clearmarking[MyMark]
+\stoptyping
+
+but because that en is not synchronized the real deal is:
+
+\starttyping[option=TEX]
+\resetmarking[MyMark]
+\stoptyping
+
+Be aware that it introduces a node in the list. You can test if a marking is
+defined with (as usual) a test macro. Contrary to (most) other test macros this
+one is fully expandable:
+
+\starttyping[option=TEX]
+\doifelsemarking {MyMark} {
+    defined
+} {
+    undefined
+}
+\stoptyping
+
+Because there can be a chain involved, we can relate markings. Think of sections
+below chapters and subsections below sections:
+
+\starttyping[option=TEX]
+\relatemarking[MyMark][YourMark]
+\stoptyping
+
+When a marking is set its relatives are also reset, so setting \type {YourMark}
+will reset \type {MyMark}. It is this kind of features that made for marks being
+wrapped into high level commands very early in the \CONTEXT\ development (and one
+can even argue that this is why a package like \CONTEXT\ exists in the first
+place).
+
+The rest of the (relatively small) repertoire of commands has to do with fetching
+markings. The general command is \type {\getmarking} that takes two or three
+arguments:
+
+\starttyping[option=TEX]
+\getmarking[MyMarking][first]
+\getmarking[MyMarking][page][first]
+\getmarking[MyMarking][page][first]
+\getmarking[MyMarking][column:1][first]
+\stoptyping
+
+There are (normally) three marks that can be fetched so we have three commands
+that do just that:
+
+\starttyping[option=TEX]
+\fetchonemark [MyMarking][which one]
+\fetchtwomarks[MyMarking]
+\fetchallmarks[MyMarking]
+\stoptyping
+
+You can setup a \type {separator} key which by default is:
+
+\starttyping[option=TEX]
+\setupmarking[MyMarking][separator=\space\emdash\space]
+\stoptyping
+
+Injection is enabled by default due to this default:
+
+\starttyping[option=TEX]
+\setupmarking[MyMarking][state=start]
+\stoptyping
+
+The following three variants are (what is called) fully expandable:
+
+\starttyping[option=TEX]
+\fetchonemarking [MyMarking][which one]
+\fetchtwomarkings[MyMarking]
+\fetchallmarkings[MyMarking]
+\stoptyping
+
+% \resetsynchronizemarking[#1]%
+% \synchronizemarking[#1][#2][#3]% (#3: options (no longer used))
+
+\stopsection
+
+\startsection[title=Pitfalls]
+
+The main pitfall is that a (re)setting a mark will inject a node which in
+vertical mode can interfere with spacing. In for instance section commands we
+wrap them with the title so there it should work out okay.
+
+\stopsection
+
+\stopdocument
diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-enhancements.tex b/doc/context/sources/general/manuals/luametatex/luametatex-enhancements.tex
index 8527b0e64..d8e0eeecf 100644
--- a/doc/context/sources/general/manuals/luametatex/luametatex-enhancements.tex
+++ b/doc/context/sources/general/manuals/luametatex/luametatex-enhancements.tex
@@ -50,6 +50,70 @@ purpose apart from the fact that it reveals some history.
 
 \stopsubsection
 
+\startsubsection[title={Rationale}]
+
+One can argue that \TEX\ should stay as it is but over decades usage of this
+program has evolved and resulted in large macro packages that often need to rely
+on what the \TEX\ books calls \quote {dirty tricks}. When you look deep down in
+the code of \CONTEXT\ \MKII, \MKIV\ and \MKXL\ (aka \LMTX) you will see plenty of
+differences but quite a bit of the functionality in the most recent versions is
+also available in \MKII. Of course more has been added over time, and some
+mechanisms could be made more efficient and reliable but plenty was possible.
+
+So, when you see something done in \CONTEXT\ \LMTX\ using new \LUAMETATEX\
+primitives you can assume that somehow the same is done in \CONTEXT\ \MKIV. We
+don't really need \LUAMETATEX\ instead of \LUATEX. Among the main reasons for
+still going for this new engine are:
+
+\startitemize[packed]
+\startitem
+    some new primitives make for less tracing and tracing has become rather
+    verbose over years (just try \prm {tracingall}); examples are the new macro
+    argument handling and some new hooks
+\stopitem
+\startitem
+    some new primitives permits more efficient coding and have a positive impact
+    on performance (this sort of compensates a performance hit due to delegating
+    work to \LUA)
+\stopitem
+\startitem
+    other primitives are there because they make the code look better; good
+    examples are the extensions to conditionals; they remove the necessity for
+    all kind of (somewhat unnatural) middle layers; take local control as example
+\stopitem
+\startitem
+    a few primitives make complex and demanding mechanism a bit easier to grasp
+    and explain; think of alignments, inserts and marks
+\stopitem
+\startitem
+    more access from the \LUA\ end to \TEX\ internals: a few more callbacks, more
+    options, more robust interfaces, etc
+\stopitem
+\stopitemize
+
+I realize that new primitives also can make some \TEX\ code look less threatening
+to new users. It removes a bit of hackery and limits the level of guru that comes
+with showing off the mastery of expansion and lookahead. So be it. I wonder if
+those objecting to some of the extensions (with the argument that they are not
+needed, and \CONTEXT\ \MKIV\ is proof of that) can resist using them. I admit
+that it sometimes hurt to throw away good working but cumbersome code that took a
+while to evolve, but I also admit that I favor long distance traveling by bike or
+car over riding horseback.
+
+It took a few years for \LUAMETATEX\ to evolve to what it is now and most
+extensions are not there \quotation {because they were easy} or \quotation {could
+be done}. If that were the case, there would be plenty more. In many aspects it
+has been a balancing act and much also relates to looking at the \CONTEXT\ source
+code (\TEX\ as well as \LUA) and wondering why it looks that way. It is also
+driven by the fact that I want to be able to explain to users why things are done
+in a certain way. In fact, I want users to be able to look at the code and
+understand it (apart from maybe a few real dirty low level helpers that are also
+dirty because of performance reasons). Just take this into account when reading on.
+
+And yes, there are still a few possibilities I want to explore \unknown
+
+\stopsubsection
+
 \startsubsection[title={Version information}]
 
 \startsubsubsection[title={\prm {luatexbanner}, \prm {luatexversion} and \prm {luatexrevision}}]
@@ -813,25 +877,67 @@ that it saves a few tokens and can make code a bit more readable.
 
 \stopsubsection
 
-\startsubsection[title={\prm {clearmarks}}]
+\startsubsection[title={\prm {clearmarks}, \prm {flushmarks}, \prm {currentmarks}}]
 
 \topicindex {marks}
 
-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 (no synchronization node is used).
+The \prm {clearmarks} 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 (no synchronization node is used).
 
 \startsyntax
 \clearmarks <16-bit number>
 \stopsyntax
 
+The \prm {flushmarks} variant is delayed but puts a (mark) node in the list as
+signal (we could have gone for a keyword to \prm {marks} instead).
+
+\startsyntax
+\flushmarks <16-bit number>
+\stopsyntax
+
+In addition to the three mark fetch commands, we also have access to the last set
+mark in the given class.
+
+\startsyntax
+\currentmarks <16-bit number>
+\stopsyntax
+
+Marks can be traced with \prm {tracingmarks}. When set to~1 the page builder
+shows the set values, and when set to a higher value details about collecting
+them are shown.
+
 \stopsubsection
 
-\startsubsection[title={\prm {alignmark} and \prm {aligntab}}]
+\startsubsection[title={\prm {alignmark}, \prm {aligntab}, \prm {aligncontent} and \prm {tabsize}}]
 
 The primitive \prm {alignmark} duplicates the functionality of \type {#} inside
 alignment preambles, while \prm {aligntab} duplicates the functionality of \type
-{&}.
+{&}. The \prm {aligncontent} primitive directly refers to an entry so that one
+does not get repeated.
+
+Alignments can be traced with \prm {tracingalignments}. When set to~1 basics
+usage is shown, for instance of \prm {noalign} but more interesting is~2 or more:
+you then get the preambles reported.
+
+The \prm {halign} (tested) and \prm {valign} (yet untested) primitives accept a
+few keywords in addition to \type {to} and \type {spread}:
+
+\starttabulate[|l|p|]
+\DB keyword \BC explanation \NC \NR
+\TB
+\NC \type {attr}     \NC set the given attribute to the given value \NC \NR
+\NC \type {callback} \NC trigger the \type {alignment_filter} callback \NC \NR
+\NC \type {discard}  \NC discard zero \prm {tabskip}'s \NC \NR
+\NC \type {noskips}  \NC don't even process zero \prm {tabskip}'s \NC \NR
+\NC \type {reverse}  \NC reverse the final rows \NC \NR
+\LL
+\stoptabulate
+
+In the preamble the \prm {tabsize} primitive can be used to set the width of a
+column. By doing so one can avoid using a box in the preamble which, combined
+with the sparse tabskip features, is a bit easier on memory when you produce
+tables that span hundreds of pages and have a dozen columns.
 
 \stopsubsection
 
diff --git a/doc/context/sources/general/manuals/luametatex/luametatex.tex b/doc/context/sources/general/manuals/luametatex/luametatex.tex
index a179dcb4c..71c6f997f 100644
--- a/doc/context/sources/general/manuals/luametatex/luametatex.tex
+++ b/doc/context/sources/general/manuals/luametatex/luametatex.tex
@@ -59,6 +59,10 @@
 %
 % mingw         :  9.7
 
+% 20210903      : 300 pages
+%
+% mingw         :  9.6
+
 % But speed can differ a bit per compilation (upto .5 seconds maybe due to how
 % compiled code is organized which might influence caching. Who knows ... (or
 % cares). For instance at 20200407 I measured 10.9 seconds after some new low level
@@ -68,7 +72,11 @@
 % switching to gcc9 it dropped again. In december 2020, with IPO enabled I crossed
 % the 26 pps barrier and went below 10 seconds but that was also after some further
 % cleanup in \LMTX. Mid August 2021 I measured over 30 pps but not all is due to
-% the engine I guess.
+% the engine I guess. End august we were are over 31 pps so it's not getting worse.
+
+% (This means that on a modern desktop we probably can get around 100 pps on a
+% manual like this but, always using laptops, I don't have access to machines like
+% that. A modern laptop probably could perform over 50 pps.)
 
 % msvc           1899k (2% slower than mingw)
 % msvc /GL       2297k (similar to mingw)