From 26a37aadfa1c26b389c7ef9c5f310a1e2ddf596c Mon Sep 17 00:00:00 2001 From: Hans Hagen Date: Fri, 3 Sep 2021 19:26:31 +0200 Subject: 2021-09-03 18:47:00 --- .../documents/general/manuals/lowlevel-marks.pdf | Bin 0 -> 62467 bytes .../manuals/interaction/interaction-buttons.tex | 2 +- .../manuals/lowlevel/lowlevel-alignments.tex | 22 + .../general/manuals/lowlevel/lowlevel-marks.tex | 506 +++++++++++++++++++++ .../manuals/luametatex/luametatex-enhancements.tex | 118 ++++- .../general/manuals/luametatex/luametatex.tex | 10 +- 6 files changed, 650 insertions(+), 8 deletions(-) create mode 100644 doc/context/documents/general/manuals/lowlevel-marks.pdf create mode 100644 doc/context/sources/general/manuals/lowlevel/lowlevel-marks.tex (limited to 'doc') 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 Binary files /dev/null and b/doc/context/documents/general/manuals/lowlevel-marks.pdf differ 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: +2:7: ..{sample 9.1} +2:7: +2:7: ..{sample 10.1} +2:7: +2:7: ..{sample 10.1} +2:7: +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: +1:9: ..{sample 5.1} +1:9: +1:9: ..{sample 6.1} +1:9: +1:9: ..{sample 6.1} +1:9: +1:9: ..{sample 7.1} +1:9: +1:9: ..{sample 8.1} +1:9: +1:9: ..{sample 9.1} +1:9: +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) -- cgit v1.2.3