summaryrefslogtreecommitdiff
path: root/doc/context/sources/general/manuals/lowlevel/lowlevel-marks.tex
diff options
context:
space:
mode:
Diffstat (limited to 'doc/context/sources/general/manuals/lowlevel/lowlevel-marks.tex')
-rw-r--r--doc/context/sources/general/manuals/lowlevel/lowlevel-marks.tex506
1 files changed, 506 insertions, 0 deletions
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