diff options
Diffstat (limited to 'doc/context')
29 files changed, 530 insertions, 289 deletions
diff --git a/doc/context/documents/general/manuals/lowlevel-alignments.pdf b/doc/context/documents/general/manuals/lowlevel-alignments.pdf Binary files differindex bbd187dfb..abeebfee9 100644 --- a/doc/context/documents/general/manuals/lowlevel-alignments.pdf +++ b/doc/context/documents/general/manuals/lowlevel-alignments.pdf diff --git a/doc/context/documents/general/manuals/lowlevel-boxes.pdf b/doc/context/documents/general/manuals/lowlevel-boxes.pdf Binary files differindex 0ee0f66a1..f0da0d506 100644 --- a/doc/context/documents/general/manuals/lowlevel-boxes.pdf +++ b/doc/context/documents/general/manuals/lowlevel-boxes.pdf diff --git a/doc/context/documents/general/manuals/lowlevel-characters.pdf b/doc/context/documents/general/manuals/lowlevel-characters.pdf Binary files differindex e3e130630..13867666b 100644 --- a/doc/context/documents/general/manuals/lowlevel-characters.pdf +++ b/doc/context/documents/general/manuals/lowlevel-characters.pdf diff --git a/doc/context/documents/general/manuals/lowlevel-conditionals.pdf b/doc/context/documents/general/manuals/lowlevel-conditionals.pdf Binary files differindex 6de0090b3..251ccc758 100644 --- a/doc/context/documents/general/manuals/lowlevel-conditionals.pdf +++ b/doc/context/documents/general/manuals/lowlevel-conditionals.pdf diff --git a/doc/context/documents/general/manuals/lowlevel-expansion.pdf b/doc/context/documents/general/manuals/lowlevel-expansion.pdf Binary files differindex 6f50c6d22..d9f2528bc 100644 --- a/doc/context/documents/general/manuals/lowlevel-expansion.pdf +++ b/doc/context/documents/general/manuals/lowlevel-expansion.pdf diff --git a/doc/context/documents/general/manuals/lowlevel-grouping.pdf b/doc/context/documents/general/manuals/lowlevel-grouping.pdf Binary files differindex a8d103236..316edda67 100644 --- a/doc/context/documents/general/manuals/lowlevel-grouping.pdf +++ b/doc/context/documents/general/manuals/lowlevel-grouping.pdf diff --git a/doc/context/documents/general/manuals/lowlevel-inserts.pdf b/doc/context/documents/general/manuals/lowlevel-inserts.pdf Binary files differnew file mode 100644 index 000000000..d305899c1 --- /dev/null +++ b/doc/context/documents/general/manuals/lowlevel-inserts.pdf diff --git a/doc/context/documents/general/manuals/lowlevel-macros.pdf b/doc/context/documents/general/manuals/lowlevel-macros.pdf Binary files differindex 9894d0484..5f89d204f 100644 --- a/doc/context/documents/general/manuals/lowlevel-macros.pdf +++ b/doc/context/documents/general/manuals/lowlevel-macros.pdf diff --git a/doc/context/documents/general/manuals/lowlevel-marks.pdf b/doc/context/documents/general/manuals/lowlevel-marks.pdf Binary files differindex e4f600b5d..a00a7f2ae 100644 --- a/doc/context/documents/general/manuals/lowlevel-marks.pdf +++ b/doc/context/documents/general/manuals/lowlevel-marks.pdf diff --git a/doc/context/documents/general/manuals/lowlevel-paragraphs.pdf b/doc/context/documents/general/manuals/lowlevel-paragraphs.pdf Binary files differindex ab46092b2..ad6be78bb 100644 --- a/doc/context/documents/general/manuals/lowlevel-paragraphs.pdf +++ b/doc/context/documents/general/manuals/lowlevel-paragraphs.pdf diff --git a/doc/context/documents/general/manuals/lowlevel-registers.pdf b/doc/context/documents/general/manuals/lowlevel-registers.pdf Binary files differindex d00daa0cc..5c5400ec6 100644 --- a/doc/context/documents/general/manuals/lowlevel-registers.pdf +++ b/doc/context/documents/general/manuals/lowlevel-registers.pdf diff --git a/doc/context/documents/general/manuals/lowlevel-scope.pdf b/doc/context/documents/general/manuals/lowlevel-scope.pdf Binary files differindex 0a17a314c..d5b628396 100644 --- a/doc/context/documents/general/manuals/lowlevel-scope.pdf +++ b/doc/context/documents/general/manuals/lowlevel-scope.pdf diff --git a/doc/context/documents/general/manuals/lowlevel-security.pdf b/doc/context/documents/general/manuals/lowlevel-security.pdf Binary files differindex b92f00ce3..d4c7d871c 100644 --- a/doc/context/documents/general/manuals/lowlevel-security.pdf +++ b/doc/context/documents/general/manuals/lowlevel-security.pdf diff --git a/doc/context/documents/general/manuals/lowlevel.pdf b/doc/context/documents/general/manuals/lowlevel.pdf Binary files differnew file mode 100644 index 000000000..8290f2118 --- /dev/null +++ b/doc/context/documents/general/manuals/lowlevel.pdf diff --git a/doc/context/sources/general/manuals/lowlevel/lowlevel-alignments.tex b/doc/context/sources/general/manuals/lowlevel/lowlevel-alignments.tex index bdc7fecf1..79fc86aae 100644 --- a/doc/context/sources/general/manuals/lowlevel/lowlevel-alignments.tex +++ b/doc/context/sources/general/manuals/lowlevel/lowlevel-alignments.tex @@ -8,7 +8,7 @@ [title=alignments, color=middlegreen] -\startsection[title=Introduction] +\startsectionlevel[title=Introduction] \TEX\ has a couple of subsystems and alignments is one of them. This mechanism is used to construct tables or alike. Because alignments use low level primitives to @@ -115,9 +115,9 @@ that relates to a parameter and alignment tab (and in \CONTEXT\ that is not the case). The \TEX book has plenty alignment examples so if you really want to learn about them, consult that must|-|have|-|book. -\stopsection +\stopsectionlevel -\startsection[title=Between the lines] +\startsectionlevel[title=Between the lines] The individual rows of a horizontal alignment are treated as lines. This means that, as we see in the previous section, the interline spacing is okay. However, that also @@ -240,9 +240,9 @@ there. A third overhaul of the code actually did lead to some adaptations in the way alignments are constructed so let's move on to that. -\stopsection +\stopsectionlevel -\startsection[title={Pre-, inter- and post-tab skips}] +\startsectionlevel[title={Pre-, inter- and post-tab skips}] The basic structure of a preamble and row is actually not that complex: it is a mix of tab skip glue and cells (that are just boxes): @@ -372,9 +372,9 @@ skips and it triggers a check later on when the rows are constructed. The \type {<content>} is what get injected in the cell (represented by \type {\alignmark}). The pseudo primitives are internal and not public. -\stopsection +\stopsectionlevel -\startsection[title={Cell widths}] +\startsectionlevel[title={Cell widths}] Imagine this: @@ -428,9 +428,9 @@ So, both the sparse skip and new \type {\tabsize} feature help to make these extreme tables (spanning hundreds of pages) not consume irrelevant memory and also make that later on we don't have to consult useless nodes. -\stopsection +\stopsectionlevel -\startsection[title=Plugins] +\startsectionlevel[title=Plugins] Yet another \LUAMETATEX\ extension is a callback that kicks in between the preamble preroll and finalizing the alignment. Initially as test and @@ -556,9 +556,9 @@ instead?} As always with such mechanisms, the question is \quotation {Where to stop?} But it makes for nice demos and as long as little code is needed it doesn't hurt. -\stopsection +\stopsectionlevel -\startsection[title=Pitfalls and tricks] +\startsectionlevel[title=Pitfalls and tricks] The next example mixes bidirectional typesetting. It might look weird at first sight but the result conforms to what we discussed in previous paragraphs. @@ -679,9 +679,9 @@ that it's a lot of work but by providing a set of helpers like here might change that a bit. Keep in mind that much of the above is not new in the sense that we could not achieve the same already, it's just a bit programmer friendly. -\stopsection +\stopsectionlevel -\startsection[title=Remark] +\startsectionlevel[title=Remark] It can be that the way alignments are interfaced with respect to attributes is a bit different between \LUATEX\ and \LUAMETATEX\ but because the former is frozen (in @@ -692,7 +692,7 @@ In principle we can have hooks into the rows for pre and post material but it doesn't really pay of as grouping will still interfere. So for now I decided not to add these. -\stopsection +\stopsectionlevel \stopdocument diff --git a/doc/context/sources/general/manuals/lowlevel/lowlevel-boxes.tex b/doc/context/sources/general/manuals/lowlevel/lowlevel-boxes.tex index 8fbd796b4..d5105fc8c 100644 --- a/doc/context/sources/general/manuals/lowlevel/lowlevel-boxes.tex +++ b/doc/context/sources/general/manuals/lowlevel/lowlevel-boxes.tex @@ -9,7 +9,7 @@ [title=boxes, color=middlered] -\startsection[title=Introduction] +\startsectionlevel[title=Introduction] An average \CONTEXT\ user will not use the low level box primitives but a basic understanding of how \TEX\ works doesn't hurt. In fact, occasionally using a box @@ -23,9 +23,9 @@ about all kind of glues, kerns and penalties, just boxes it is. This explanation will be extended when I feel the need (or users have questions that can be answered here). -\stopsection +\stopsectionlevel -\startsection[title=Boxes] +\startsectionlevel[title=Boxes] This paragraph of text is made from lines that contain words that themselves contain symbolic representations of characters. Each line is wrapped in a so @@ -66,11 +66,9 @@ other hand wraps a linked list of so called nodes: glyphs, kerns, glue, penalties, rules, boxes, etc. It is a container with properties like width, height, depth and shift. -\stopsection +\stopsectionlevel -\stopsection - -\startsection[title={\TEX\ primitives}] +\startsectionlevel[title={\TEX\ primitives}] The box model is reflected in \TEX's user interface but not by that many commands, most noticeably \type {\hbox}, \type {\vbox} and \type {\vtop}. Here is @@ -218,9 +216,9 @@ we use copy because it serves the examples. \box \scratchbox \stoptyping -\stopsection +\stopsectionlevel -\startsection[title={\ETEX\ primitives}] +\startsectionlevel[title={\ETEX\ primitives}] The \ETEX\ extensions don't add something relevant for boxes, apart from that you can use the expressions mechanism to mess around with their dimensions. There is @@ -229,9 +227,9 @@ capabilities and doesn't change much as it's mostly a way to trick the backend into outputting a stretch of text in the other direction. This feature is not available in \LUATEX\ because it has an alternative direction mechanism. -\stopsection +\stopsectionlevel -\startsection[title={\LUATEX\ primitives}] +\startsectionlevel[title={\LUATEX\ primitives}] The concept of boxes is the same in \LUATEX\ as in its predecessors but there are some aspects to keep in mind. When a box is typeset this happens in \LUATEX: @@ -289,9 +287,9 @@ but because in \LUAMETATEX\ there are only two. Because this model has been upgr it will be discusses in the next section. A \CONTEXT\ user is supposed to use the official \CONTEXT\ interfaces in order to be downward compatible. -\stopsection +\stopsectionlevel -\startsection[title={\LUAMETATEX\ primitives}] +\startsectionlevel[title={\LUAMETATEX\ primitives}] There are two possible directions: left to right (the default) and right to left for Hebrew and Arabic. Here is an example that shows how it'd done with low level @@ -691,7 +689,7 @@ test\quad \ruledhbox{\getbuffer} \stoplinecorrection -\stopsection +\stopsectionlevel \stopdocument diff --git a/doc/context/sources/general/manuals/lowlevel/lowlevel-characters.tex b/doc/context/sources/general/manuals/lowlevel/lowlevel-characters.tex index c3d417e44..777182b84 100644 --- a/doc/context/sources/general/manuals/lowlevel/lowlevel-characters.tex +++ b/doc/context/sources/general/manuals/lowlevel/lowlevel-characters.tex @@ -6,15 +6,15 @@ [title=characters, color=middlered] -\startsection[title=Introduction] +\startsectionlevel[title=Introduction] This explanation is part of the low level manuals because in practice users will not have to deal with these matters in \MKIV\ and even less in \LMTX. You can skip to the last section for commands. -\stopsection +\stopsectionlevel -\startsection[title=History] +\startsectionlevel[title=History] If we travel back in time to when \TEX\ was written we end up in eight bit character universe. In fact, the first versions assumed seven bits, but for @@ -79,9 +79,9 @@ depending on the (local) language, referencing the relevant font. It permits users to enter the text in their preferred input encoding and also get the words properly hyphenated. But we can leave these \MKII\ details behind. -\stopsection +\stopsectionlevel -\startsection[title=The heritage] +\startsectionlevel[title=The heritage] In \MKIV\ we got rid of input and font encodings, although one can still load files in a specific code page. \footnote {I'm not sure if users ever depend on an @@ -112,9 +112,9 @@ format file. \footnote {In \MKII\ we have an abstract front|-|end with respect t encodings and also an abstract backend with respect to supported drivers but both approaches no longer make sense today.} -\stopsection +\stopsectionlevel -\startsection[title=The \LMTX\ approach] +\startsectionlevel[title=The \LMTX\ approach] In the process of tagging all (public) macros in \LMTX\ (which happened in 2020|-|2021) I wondered if we should keep these one character macros, the @@ -220,19 +220,7 @@ We get this list: Some combinations are special for \CONTEXT\ because \UNICODE\ doesn't specify decomposition for all composed characters. -\stopsection - -\startsubject[title=Colofon] - -\starttabulate -\NC Author \NC Hans Hagen \NC \NR -\NC \CONTEXT \NC \contextversion \NC \NR -\NC \LUAMETATEX \NC \texengineversion \NC \NR -\NC Support \NC www.pragma-ade.com \NC \NR -\NC \NC contextgarden.net \NC \NR -\stoptabulate - -\stopsubject +\stopsectionlevel \stopdocument diff --git a/doc/context/sources/general/manuals/lowlevel/lowlevel-conditionals.tex b/doc/context/sources/general/manuals/lowlevel/lowlevel-conditionals.tex index dfff4ac72..288521bdd 100644 --- a/doc/context/sources/general/manuals/lowlevel/lowlevel-conditionals.tex +++ b/doc/context/sources/general/manuals/lowlevel/lowlevel-conditionals.tex @@ -8,9 +8,9 @@ \pushoverloadmode -\startsection[title=Preamble] +\startsectionlevel[title=Preamble] -\startsubsection[title=Introduction] +\startsectionlevel[title=Introduction] You seldom need the low level conditionals because there are quite some so called support macros available in \CONTEXT . For instance, when you want to compare two @@ -53,9 +53,9 @@ The others are often wrapped into support macros that are more convenient. In due time I might add more examples and explanations. Also, maybe some more tests will show up as part of the \LUAMETATEX\ project. -\stopsubsection +\stopsectionlevel -\startsubsection[title={Number and dimensions}] +\startsectionlevel[title={Number and dimensions}] Numbers and dimensions are basic data types in \TEX. When you enter one, a number is just that but a dimension gets a unit. Compare: @@ -289,13 +289,13 @@ assuming that the fraction is within the maximum permitted) so these numbers the are the same. Anyway, this is not different in other programming languages and just something you need to be aware of. -\stopsubsection +\stopsectionlevel -\stopsection +\stopsectionlevel -\startsection[title={\TEX\ primitives}] +\startsectionlevel[title={\TEX\ primitives}] -\startsubsection[title={\tex{if}}] +\startsectionlevel[title={\tex{if}}] I seldom use this one. Internally \TEX\ stores (and thinks) in terms of tokens. If you see for instance \type {\def} or \type {\dimen} or \type {\hbox} these all @@ -330,9 +330,9 @@ We get: \inlinebuffer . % protected macros -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{ifcat}}] +\startsectionlevel[title={\tex{ifcat}}] In \TEX\ characters (in the input) get interpreted according to their so called catcodes. The most common are letters (alphabetic) and and other (symbols) but @@ -377,9 +377,9 @@ You can use \type {\noexpand} to prevent expansion: We get: \inlinebuffer, so who still thinks that \TEX\ is easy to understand for a novice user? -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{ifnum}}] +\startsectionlevel[title={\tex{ifnum}}] This condition compares its argument with another one, separated by an \type {<}, \type {=} or \type {>} character. @@ -410,9 +410,9 @@ case the dimension is in scaled points. Of course this equal treatment of a dimension and number is only true when the dimension is a register or box property. -\stopsubsection +\stopsectionlevel -\startsection[title={\tex{ifdim}}] +\startsectionlevel[title={\tex{ifdim}}] This condition compares one dimension with another one, separated by an \type {<}, \type {=} or \type {>} sign. @@ -430,9 +430,9 @@ This condition compares one dimension with another one, separated by an \type {< While when comparing numbers a dimension is a valid quantity but here you cannot mix them: something with a unit is expected. -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{ifodd}}] +\startsectionlevel[title={\tex{ifodd}}] This one can come in handy, although in \CONTEXT\ it is only used in checking for an odd of even page number. @@ -454,9 +454,9 @@ too, which is then interpreted as representing scaled points. Here we get: \getbuffer \stoplines -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{ifvmode}}] +\startsectionlevel[title={\tex{ifvmode}}] This is a rather trivial check. It takes no arguments and just is true when we're in vertical mode. Here is an example: @@ -470,9 +470,9 @@ in vertical mode. Here is an example: We're always in horizontal mode and issuing a \type {\par} inside a horizontal box doesn't change that, so we get: \ruledhbox{\inlinebuffer}. -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{ifhmode}}] +\startsectionlevel[title={\tex{ifhmode}}] As with \type {\ifvmode} this one has no argument and just tells if we're in vertical mode. @@ -494,9 +494,9 @@ content (or command) is done more than once: \ruledhbox{\inlinebuffer} \stoplinecorrection -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{ifmmode}}] +\startsectionlevel[title={\tex{ifmmode}}] Math is something very \TEX\ so naturally you can check if you're in math mode. here is an example of using this test: @@ -507,9 +507,9 @@ here is an example of using this test: Of course in reality macros that do such things are more advanced than this one. -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{ifinner}}] +\startsectionlevel[title={\tex{ifinner}}] \startbuffer \def\ShowMode @@ -549,9 +549,9 @@ By the way, moving the \type {\ifinner} test outside the branches (to the top of the macro) won't work because once the word \type {inner} is typeset we're no longer in vertical mode, if we were at all. -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{ifvoid}}] +\startsectionlevel[title={\tex{ifvoid}}] A box is one of the basic concepts in \TEX. In order to understand this primitive we present four cases: @@ -601,15 +601,15 @@ Setting a dimension of a void voix (empty) box doesn't make it less void: \getbuffer \stoplines -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{ifhbox}}] +\startsectionlevel[title={\tex{ifhbox}}] This test takes a box number and gives true when it is an hbox. -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{ifvbox}}] +\startsectionlevel[title={\tex{ifvbox}}] This test takes a box number and gives true when it is an vbox. Both a \type {\vbox} and \type {\vtop} are vboxes, the difference is in the height and depth @@ -627,9 +627,9 @@ And in a \type {\vtop} the first line takes control: but, once wrapped, both internally are just vlists. -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{ifx}}] +\startsectionlevel[title={\tex{ifx}}] This test is actually used a lot in \CONTEXT: it compares two token(list)s: @@ -651,29 +651,29 @@ that get compared, like in: \edef\TempA{...}\edef\TempB{...}\ifx\TempA\TempB ...\else ...\fi \stoptyping -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{ifeof}}] +\startsectionlevel[title={\tex{ifeof}}] This test checks if a the pointer in a given input channel has reached its end. It is also true when the file is not present. The argument is a number which relates to the \type {\openin} primitive that is used to open files for reading. -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{iftrue}}] +\startsectionlevel[title={\tex{iftrue}}] It does what it says: always true. -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{iffalse}}] +\startsectionlevel[title={\tex{iffalse}}] It does what it says: always false. -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{ifcase}}] +\startsectionlevel[title={\tex{ifcase}}] The general layout of an \type {\ifcase} tests is as follows: @@ -693,13 +693,13 @@ The general layout of an \type {\ifcase} tests is as follows: As in other places a number is a sequence of signs followed by one of more digits -\stopsubsection +\stopsectionlevel -\stopsection +\stopsectionlevel -\startsection[title={\ETEX\ primitives}] +\startsectionlevel[title={\ETEX\ primitives}] -\startsubsection[title={\tex{ifdefined}}] +\startsectionlevel[title={\tex{ifdefined}}] This primitive was introduced for checking the existence of a macro (or primitive) and with good reason. Say that you want to know if \type {\MyMacro} is defined? One @@ -736,9 +736,9 @@ In order to catch the last problem there is the option to test directly: This (or course) results in: \inlinebuffer, but the macro is still sort of defined (with no meaning). The next section shows how to get around this. -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{ifcsname}}] +\startsectionlevel[title={\tex{ifcsname}}] A macro is often defined using a ready made name, as in: @@ -795,9 +795,9 @@ during this test, and in \LUAMETATEX\ that is default. This means that tests can be made quite robust as it is pretty safe to assume that names that make sense are constructed from regular characters and not boxes, font switches, etc. -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{iffontchar}}] +\startsectionlevel[title={\tex{iffontchar}}] This test was also part of the \ETEX\ extensions and it can be used to see if a font has a character. @@ -824,9 +824,9 @@ In the perspective of \LUAMETATEX\ I considered also supporting \type {\fontid} but it got a bit messy due to the fact that this primitive expands in a different way so this extension was rejected. -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{unless}}] +\startsectionlevel[title={\tex{unless}}] You can negate the results of a test by using the \type {\unless} prefix, so for instance you can replace: @@ -847,41 +847,41 @@ by: \fi \stoptyping -\stopsubsection +\stopsectionlevel -\stopsection +\stopsectionlevel -\startsection[title={\LUATEX\ primitives}] +\startsectionlevel[title={\LUATEX\ primitives}] -\startsubsection[title={\tex{ifincsname}}] +\startsectionlevel[title={\tex{ifincsname}}] As it had no real practical usage uit might get dropped in \LUAMETATEX, so it will not be discussed here. -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{ifprimitive}}] +\startsectionlevel[title={\tex{ifprimitive}}] As it had no real practical usage due to limitations, this one is not available in \LUAMETATEX\ so it will not be discussed here. -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{ifabsnum}}] +\startsectionlevel[title={\tex{ifabsnum}}] This test is inherited from \PDFTEX\ and behaves like \type {\ifnum} but first turns a negative number into a positive one. -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{ifabsdim}}] +\startsectionlevel[title={\tex{ifabsdim}}] This test is inherited from \PDFTEX\ and behaves like \type {\ifdim} but first turns a negative dimension into a positive one. -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{ifcondition}}] +\startsectionlevel[title={\tex{ifcondition}}] This is not really a test but in order to unstand that you need to know how \TEX\ internally deals with tests. @@ -1061,13 +1061,13 @@ permits more complex arguments, like: Another trick is that we use an integer division (the \type {:}) which is an operator supported by \LUAMETATEX . -\stopsubsection +\stopsectionlevel -\stopsection +\stopsectionlevel -\startsection[title={\LUAMETATEX\ primitives}] +\startsectionlevel[title={\LUAMETATEX\ primitives}] -\startsubsection[title={\tex{ifcmpnum}}] +\startsectionlevel[title={\tex{ifcmpnum}}] This one is part of s set of three tests that all are a variant of a \type {\ifcase} test. A simple example of the first test is this: @@ -1080,9 +1080,9 @@ The test scans for two numbers, which of course can be registers or expressions, and sets the case value to 0, 1 or 2, which means that you then use the normal \type {\or} and \type {\else} primitives for follow up on the test. -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{ifchknum}}] +\startsectionlevel[title={\tex{ifchknum}}] This test scans a number and when it's okay sets the case value to 1, and otherwise to 2. So you can do the next: @@ -1097,9 +1097,9 @@ recovery token, although in fact we just use the fast scanner mode that comes with the \type {\ifcase}: because the result is 1 or 2, we never see invalid tokens. -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{ifnumval}}] +\startsectionlevel[title={\tex{ifnumval}}] A sort of combination of the previous two is \type {\ifnumval} which checks a number but also if it's less, equal or more than zero: @@ -1113,29 +1113,29 @@ You can decide to ignore the bad number or do something that makes more sense. Often the to be checked value will be the content of a macro or an argument like \type {#1}. -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{ifcmpdim}}] +\startsectionlevel[title={\tex{ifcmpdim}}] This test is like \type {\ifcmpnum} but for dimensions. -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{ifchkdim}}] +\startsectionlevel[title={\tex{ifchkdim}}] This test is like \type {\ifchknum} but for dimensions. The last checked value is available as \type {\lastchknum}. -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{ifdimval}}] +\startsectionlevel[title={\tex{ifdimval}}] This test is like \type {\ifnumval} but for dimensions. The last checked value is available as \type {\lastchkdim} -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{iftok}}] +\startsectionlevel[title={\tex{iftok}}] Although this test is still experimental it can be used. What happens is that two to be compared \quote {things} get scanned for. For each we first gobble @@ -1195,49 +1195,49 @@ Case one and four mixed: The last case is more a catch: it will issue an error when no number is given. Eventually that might become a bit more clever (depending on our needs.) -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{ifcstok}}] +\startsectionlevel[title={\tex{ifcstok}}] There is a subtle difference between this one and \type {iftok}: spaces and \type {\relax} tokens are skipped but nothing gets expanded. So, when we arrive at the to be compared \quote {things} we look at what is there, as|-|is. -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{iffrozen}}] +\startsectionlevel[title={\tex{iffrozen}}] {\em This is an experimental test.} Commands can be defined with the \type {\frozen} prefix and this test can be used to check if that has been the case. -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{ifprotected}}] +\startsectionlevel[title={\tex{ifprotected}}] Commands can be defined with the \type {\protected} prefix (or in \CONTEXT, for historic reasons, with \type {\unexpanded}) and this test can be used to check if that has been the case. -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{ifusercmd}}] +\startsectionlevel[title={\tex{ifusercmd}}] {\em This is an experimental test.} It can be used to see if the command is defined at the user level or is a build in one. This one might evolve. -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{ifarguments}}] +\startsectionlevel[title={\tex{ifarguments}}] This conditional can be used to check how many arguments were matched. It only makes sense when used with macros defined with the \type {\tolerant} prefix and|/|or when the sentinel \type {\ignorearguments} after the arguments is used. More details can be found in the lowlevel macros manual. -\stopsubsection +\stopsectionlevel -\startsubsection[title={\tex{orelse}}] +\startsectionlevel[title={\tex{orelse}}] This it not really a test primitive but it does act that way. Say that we have this: @@ -1297,13 +1297,13 @@ This permits: where, of course, the quitting normally is the result of some intermediate extra test. But let me play safe here: beware of side effects. -\stopsubsection +\stopsectionlevel -\stopsection +\stopsectionlevel -\startsection[title={For the brave}] +\startsectionlevel[title={For the brave}] -\startsubsection[title={Full expansion}] +\startsectionlevel[title={Full expansion}] If you don't understand the following code, don't worry. There is seldom much reason to go this complex but obscure \TEX\ code attracts some users so \unknown @@ -1361,9 +1361,9 @@ different: they contain the assignments and the test for the character is actually done when constructing the content of the \type {\edef}, but for the current font. So, basically that test is now useless. -\stopsubsection +\stopsectionlevel -\startsubsection[title={User defined if's}] +\startsectionlevel[title={User defined if's}] There is a \type {\newif} macro that defines three other macros: @@ -1411,11 +1411,11 @@ This one is cheaper on the hash and doesn't need the two extra macros per test. The price is the use of \type {\ifconditional}, which is {\em not} to confused with \type {\ifcondition} (it has bitten me already a few times). -\stopsubsection +\stopsectionlevel -\stopsection +\stopsectionlevel -\startsection[title=Relaxing] +\startsectionlevel[title=Relaxing] When \TEX\ scans for a number or dimension it has to check tokens one by one. On the case of a number, the scanning stops when there is no digit, in the case of a @@ -1532,19 +1532,7 @@ it acts as relax, but otherwise it just is ignored and disappears. \typebuffer[c] \getbuffer[c,b] -\stopsection - -\startsubject[title=Colofon] - -\starttabulate -\NC Author \NC Hans Hagen \NC \NR -\NC \CONTEXT \NC \contextversion \NC \NR -\NC \LUAMETATEX \NC \texengineversion \NC \NR -\NC Support \NC www.pragma-ade.com \NC \NR -\NC \NC contextgarden.net \NC \NR -\stoptabulate - -\stopsubject +\stopsectionlevel \popoverloadmode diff --git a/doc/context/sources/general/manuals/lowlevel/lowlevel-expansion.tex b/doc/context/sources/general/manuals/lowlevel/lowlevel-expansion.tex index 98f533859..6e9134914 100644 --- a/doc/context/sources/general/manuals/lowlevel/lowlevel-expansion.tex +++ b/doc/context/sources/general/manuals/lowlevel/lowlevel-expansion.tex @@ -11,7 +11,7 @@ [title=expansion, color=middleyellow] -\startsection[title=Preamble] +\startsectionlevel[title=Preamble] This short manual demonstrates a couple of properties of the macro language. It is not an in|-|depth philosophical expose about macro languages, tokens, @@ -23,9 +23,9 @@ book does and although there is no way to avoid the word \quote {token} I will d my best to not complicate matters by too much token speak. Examples show best what we mean. -\stopsection +\stopsectionlevel -\startsection[title={\TEX\ primitives}] +\startsectionlevel[title={\TEX\ primitives}] The \TEX\ language provides quite some commands and those built in are called primitives. User defined commands are called macros. A macro is a shortcut to a @@ -316,9 +316,9 @@ The first one gives \inlinebuffer[a], while the second gives \inlinebuffer[b]. % \afterassignment % \aftergroup -\stopsection +\stopsectionlevel -\startsection[title={\ETEX\ primitives}] +\startsectionlevel[title={\ETEX\ primitives}] In this engine a couple of extensions were added and later on \PDFTEX\ added some more. We only discuss a few that relate to expansion. There is however a pitfall @@ -439,9 +439,9 @@ letters. The next snippet shows these catcodes: The result is \quotation {\tt\inlinebuffer}: two characters are marked as \quote {letter} and two fall in the \quote {other} category. -\stopsection +\stopsectionlevel -\startsection[title={\LUATEX\ primitives}] +\startsectionlevel[title={\LUATEX\ primitives}] This engine adds a little to the expansion repertoire. First of all it offers a way to extend token lists registers: @@ -484,9 +484,9 @@ or token lists, simply because in the process \TEX\ has to create tokens lists too, but sometimes they're just more convenient to use. In \CONTEXT\ we actually do benefit from these. -\stopsection +\stopsectionlevel -\startsection[title={\LUAMETATEX\ primitives}] +\startsectionlevel[title={\LUAMETATEX\ primitives}] We already saw that macro's can be defined protected which means that @@ -999,9 +999,9 @@ performance or bloating the source. % tex.runlocal : function|number(register)|string(macro)|userdata(token) + expand + grouped % mplib.expandtex : mpx + kind + string|userdata + [string|true|table|userdata|number]* -\stopsection +\stopsectionlevel -\startsection[title=Dirty tricks] +\startsectionlevel[title=Dirty tricks] When I was updating this manual Hans vd Meer and I had some discussions about expansion and tokenization related issues when combining of \XML\ processing with @@ -1116,7 +1116,7 @@ so that we can do: A companion macro of this is \type {\wipetoken} but for that one you need to look into the source. -\stopsection +\stopsectionlevel \stopdocument diff --git a/doc/context/sources/general/manuals/lowlevel/lowlevel-grouping.tex b/doc/context/sources/general/manuals/lowlevel/lowlevel-grouping.tex index a3bfe79c9..12d12f7f4 100644 --- a/doc/context/sources/general/manuals/lowlevel/lowlevel-grouping.tex +++ b/doc/context/sources/general/manuals/lowlevel/lowlevel-grouping.tex @@ -6,15 +6,15 @@ [title=grouping, color=middlecyan] -\startsection[title=Introduction] +\startsectionlevel[title=Introduction] This is a rather short explanation. I decided to write it after presenting the other topics at the 2019 \CONTEXT\ meeting where there was a question about grouping. -\stopsection +\stopsectionlevel -\startsection[title=\PASCAL] +\startsectionlevel[title=\PASCAL] In a language like \PASCAL, the language that \TEX\ has been written in, or \MODULA, its successor, there is no concept of grouping like in \TEX. But we can @@ -30,9 +30,9 @@ instance an assignment in \METAPOST\ uses \type {:=} too. However, the \type can have local variables in a procedure or function but the block is just a way to pack a sequence of statements. -\stopsection +\stopsectionlevel -\startsection[title=\TEX] +\startsectionlevel[title=\TEX] In \TEX\ macros (or source code) the following can occur: @@ -79,9 +79,9 @@ The bottomline is: if you want a value to persist after the group, you need to explicitly change its value globally. This makes a lot of sense in the perspective of \TEX. -\stopsection +\stopsectionlevel -\startsection[title=\METAPOST] +\startsectionlevel[title=\METAPOST] The \METAPOST\ language also has a concept of grouping but in this case it's more like a programming language. @@ -110,9 +110,9 @@ implicit. So, in \METAPOST\ all assignments are global, unless a variable is explicitly saved inside a group. -\stopsection +\stopsectionlevel -\startsection[title=\LUA] +\startsectionlevel[title=\LUA] In \LUA\ all assignments are global unless a variable is defines local: @@ -132,9 +132,9 @@ some \METAPOST\ coding or using \type {end} instead of \type {endfor} in \METAPOST\ which can make the library wait for more without triggering an error. Proper syntax highlighting in an editor clearly helps. -\stopsection +\stopsectionlevel -\startsection[title=\CCODE] +\startsectionlevel[title=\CCODE] The \LUA\ language is a mix between \PASCAL\ (which is one reason why I like it) and \CCODE. @@ -151,20 +151,6 @@ for (i=1; i<=10;i++) { The semicolon is also used in \PASCAL\ but there it is a separator and not a statement end, while in \METAPOST\ it does end a statement (expression). -\stopsection - -\stopsection - -\startsubject[title=Colofon] - -\starttabulate -\NC Author \NC Hans Hagen \NC \NR -\NC \CONTEXT \NC \contextversion \NC \NR -\NC \LUAMETATEX \NC \texengineversion \NC \NR -\NC Support \NC www.pragma-ade.com \NC \NR -\NC \NC contextgarden.net \NC \NR -\stoptabulate - -\stopsubject +\stopsectionlevel \stopdocument diff --git a/doc/context/sources/general/manuals/lowlevel/lowlevel-inserts.tex b/doc/context/sources/general/manuals/lowlevel/lowlevel-inserts.tex new file mode 100644 index 000000000..4976ce564 --- /dev/null +++ b/doc/context/sources/general/manuals/lowlevel/lowlevel-inserts.tex @@ -0,0 +1,202 @@ +% language=us runpath=texruns:manuals/lowlevel + +\environment lowlevel-style + +\startdocument + [title=inserts, + color=middlecyan] + +\startsectionlevel[title=Introduction] + +This document is a mixed bag. We do discuss inserts but also touch elements of +the page builder because inserts and regular page content are handled there. +Examples of mechanisms that use inserts are footnotes. These have an anchor in +the running text and some content that ends up (normally) at the bottom of the +page. When considering a page break the engine tries to make sure that the anchor +(reference) and the content end up on the same page. When there is too much, it +will distribute (split) the content over pages. + +We can discuss page breaks in a (pseudo) scientific way and explore how to +optimize this process, taking into accounts also inserts that contain images but +it doesn't make much sense to do that because in practice we can encounter all +kind of interferences. Theory and practice are too different because a document +can contain a wild mix of text, figures, formulas, notes, have backgrounds and +location dependent processing. It get seven more complex when we are dealing with +columns because \TEX\ doesn't really know that concept. + +I will therefore stick to some practical aspects and the main reason for this +document is that I sort of document engine features and at the same time give an +impression of what we deal with. I will do that in the perspective of +\LUAMETATEX, which has a few more options and tracing than other engines. + +{\em Currently this document is mostly for myself to keep track of the state of +inserts and the page builder in \LUAMETATEX\ and \CONTEXT\ \LMTX. The text is not +yet corrected and can have errors.} + +\stopsectionlevel + +\startsectionlevel[title=The page builder] + +When your document is processed content eventually gets added to the so called +main vertical list (mvl). Content first get appended to the list of contributions +and at specific moments it will be handed over to the mvl. This process is called +page building. There we can encounter the following elements (nodes): + +\starttabulate +\NC \type {glue} \NC a vertical skip \NC \NR +\NC \type {penalty} \NC a vertical penalty \NC \NR +\NC \type {kern} \NC a vertical kern \NC \NR +\NC \type {vlist} \NC a a vertical box \NC \NR +\NC \type {hlist} \NC a horizontal box (often a line) \NC \NR +\NC \type {rule} \NC a horizontal rule \NC \NR +\NC \type {boundary} \NC a boundary node \NC \NR +\NC \type {whatsit} \NC a node that is used by user code (often some extension) \NC \NR +\NC \type {mark} \NC a token list (as used for running headers) \NC \NR +\NC \type {insert} \NC a node list (as used for notes) \NC \NR +\stoptabulate + +The engine itself will not insert anything other than this but \LUA\ code can +mess up the contribution list and the mvl and that can trigger an error. Handing +over the contributions is done by the page builder and that one kicks in in +several places: + +\startitemize[packed] +\startitem + When a penalty gets inserted it is part of evaluating if the output routine + should be triggered. This triggering can be enforced by values equal or below + 10.000 that then can be checked in the set routine. +\stopitem +\startitem + The builder is {\em not} exercised when a glue or kern is injected so there can + be multiple of them before another element triggers the builder. +\stopitem +\startitem + Adding a box triggers the builder as does the result of an alignment which can + be a list of boxes. +\stopitem +\startitem + When the output routine is finished the builder is executed because the + routine can have pushed back content. +\stopitem +\startitem + When a new paragraph is triggered by the \type {\par} command the builder kicks in + but only when the engine was able to enter vertical mode. +\stopitem +\startitem + When the job is finished the builder will make sure that pending content is handled. +\stopitem +\startitem + An insert and vadjust {\em can} trigger the builder but only at the nesting level zero + which normally is not the case (I need an example). +\stopitem +\startitem + At the beginning of a paragraph (like text), before display math is entered, + and when display math ends the builder is also activated. +\stopitem +\stopitemize + +At the \TEX\ the builder is triggered automatically in the mentioned cases but at +the \LUA\ end you can use \type {tex.triggerbuildpage()} to flush the pending +contributions. + +The properties that relate to the page look like counter and dimension registers ut +they are not. These variables are global and managed differently. + +\starttabulate +\NC \type {\pagegoal} \NC the available space \NC \NR +\NC \type {\pagetotal} \NC the accumulated space \NC \NR +\NC \type {\pagestretch} \NC the possible zero order stretch \NC \NR +\NC \type {\pagefilstretch} \NC the possible one order stretch \NC \NR +\NC \type {\pagefillstretch} \NC the possible second order stretch \NC \NR +\NC \type {\pagefilllstretch} \NC the possible third order stretch \NC \NR +\NC \type {\pageshrink} \NC the possible shrink \NC \NR +\NC \type {\pagedepth} \NC the current page depth \NC \NR +\NC \type {\pagevsize} \NC the initial page goal \NC \NR +\stoptabulate + +When the first content is added to an empty page the \type {\pagegoal} gets the +value of \type {\vsize} and gets frozen but the value is diminished by the space +needed by left over inserts. These inserts are managed via a separate list so +they don't interfere with the page that itself of course can have additional +inserts. The \type {\pagevsize} is just a (\LUAMETATEX) status variable that hold +the initial \type {\pagegoal} but it might play a role in future extensions. + +Another variable is \type {\deadcycles} that registers the number of times the +output routine is called without returning result. + +\stopsectionlevel + +\startsectionlevel[title=Inserts] + +We now come to inserts. In traditional \TEX\ an insert is a data structure that +runs on top of registers: a box, count, dimension and skip. An insert is accessed +by a number so for instance insert 123 will use the four registers of that +number. Because \TEX\ only offers a command alias mechanism for registers (like +\type {\countdef}) a macro package will implement some allocator management +subsystem (like \type {\newcount}). A \type {\newinsert} has to be defined in a +way that the four registers are not clashing with other allocators. When you +start with \TEX\ seeing code that deals with in (in plain \TEX) can be puzzling +but it follows from the way \TEX\ is set up. But inserts are probably not what +you start exploring right away away. + +In \LUAMETATEX\ you can set \type {\insertmode} to 1 and that is what we do in +\CONTEXT. In that mode inserts are taken from a pool instead of registers. A side +effect is that like the page properties the insert properties are global too but +that is normally no problem and can be managed well by a macro package (that +probably would assign register the values globally too). The insert pool will +grow dynamically on demand so one can just start at 1; in \CONTEXT\ \MKIV\ we use +the range 127 upto 255 in order to avoid a clash with registers. In \LMTX\ we start +at 1 because there are no clashes. + +A consequence of this approach is that we use dedicated commands to set the insert +properties: + +\starttabulate[|l|l|p|] +\NC \type {\insertdistance} \NC glue \NC the space before the first instance (on a page) \NC \NR +\NC \type {\insertmultiplier} \NC count \NC a factor that is used to calculate the height used \NC \NR +\NC \type {\insertlimit} \NC dimen \NC the maximum amount of space on a page to be taken \NC \NR +\NC \type {\insertpenalty} \NC count \NC the floating penalty (used when set) \NC \NR +\NC \type {\insertmaxdepth} \NC dimen \NC the maximum split depth (used when set) \NC \NR +\NC \type {\insertstorage} \NC count \NC signals that the insert has to be stored for later \NC \NR +\NC \type {\insertheight} \NC dimen \NC the accumulated height of the inserts so far \NC \NR +\NC \type {\insertdepth} \NC dimen \NC the current depth of the inserts so far \NC \NR +\NC \type {\insertwidth} \NC dimen \NC the width of the inserts \NC \NR +\stoptabulate + +These commands take a number and an integer, dimension or glue specification. +They can be set and queried but setting the dimensions can have side effects. The +accumulated height of the inserts is available in \type {\insertheights} (which +can be set too). The \type {\floatingpenalty} variable determines the penalty +applied when a split is needed. + +In the output routine the original \TEX\ variable \type {\insertpenalties} is a +counter that keeps the number of insertions that didn't fit on the page while +otherwise if has the accumulated penalties of the split insertions. When \type +{\holdinginserts} is non zero the inserts in the list are not collected for +output, which permits the list to be fed back for reprocessing. + +The \LUAMETATEX\ specific storage mode \type {\insertstoring} variable is +explained in the next section. + +\stopsectionlevel + +\startsectionlevel[title=Storing] + +This feature is kind of special and still experimental. When \type +{\insertstoring} is set 1, all inserts that have their storage flag set will be +saved. Think of a multi column setup where inserts have to end up in the last +column. If there are three columns, the first two will store inserts. Then when +the last column is dealt with \type {\insertstoring} can be set to 2 and that +will signal the builder that we will inject the inserts. In both cases, the value +of this register will be set to zero so that it doesn't influence further +processing. + +\stopsectionlevel + +\startsectionlevel[title=Callbacks] + +{\em Todo, nothing new there, so no hurry.} + +\stopsectionlevel + +\stopdocument diff --git a/doc/context/sources/general/manuals/lowlevel/lowlevel-macros.tex b/doc/context/sources/general/manuals/lowlevel/lowlevel-macros.tex index a69eec797..200cd8650 100644 --- a/doc/context/sources/general/manuals/lowlevel/lowlevel-macros.tex +++ b/doc/context/sources/general/manuals/lowlevel/lowlevel-macros.tex @@ -22,7 +22,7 @@ [title=macros, color=middleorange] -\startsection[title=Preamble] +\startsectionlevel[title=Preamble] This chapter overlaps with other chapters but brings together some extensions to the macro definition and expansion parts. As these mechanisms were stepwise @@ -33,9 +33,9 @@ have \TEX\ act like before. We keep the charm of the macro language but these additions make for easier definitions, but (at least initially) none that could not be done before using more code. -\stopsection +\stopsectionlevel -\startsection[title=Definitions] +\startsectionlevel[title=Definitions] A macro definition normally looks like like this: \footnote {The \type {\dontleavehmode} command make the examples stay on one line.} @@ -563,9 +563,9 @@ when the matching quits. Gobbling spaces versus pushing back is an interface design decision because it has to do with consistency. -\stopsection +\stopsectionlevel -\startsection[title=Runaway arguments] +\startsectionlevel[title=Runaway arguments] There is a particular troublesome case left: a runaway argument. The solution is not pretty but it's the only way: we need to tell the parser that it can quit. @@ -611,9 +611,9 @@ offset by some inefficient styling. Of course another gain of loosing some indirectness is that error messages point to the macro that the user called for and not to some follow up. -\stopsection +\stopsectionlevel -\startsection[title=Introspection] +\startsectionlevel[title=Introspection] A macro has a meaning. You can serialize that meaning as follows: @@ -659,9 +659,9 @@ macro is a special version of the online variant: That one is always available and shows a similar list on the console. Again, users normally don't want to know such details. -\stopsection +\stopsectionlevel -\startsection[title=nesting] +\startsectionlevel[title=nesting] You can nest macros, as in: @@ -760,9 +760,9 @@ sure I do know why I dislike some languages for it). The \TEX\ system is not the only one where dollars, percent signs, ampersands and hashes have special meaning. -\stopsection +\stopsectionlevel -\startsection[title=Prefixes] +\startsectionlevel[title=Prefixes] Traditional \TEX\ has three prefixes that can be used with macros: \type {\global}, \type {\outer} and \type {\long}. The last two are no|-|op's in \LUAMETATEX\ and @@ -903,24 +903,24 @@ The level of checking is controlled with the \type {\overloadmode} but I'm still not sure about how many levels we need there. A zero value disables checking, the values 1 and 3 give warnings and the values 2 and 4 trigger an error. -\stopsection +\stopsectionlevel \stopdocument -freezing pitfalls: - -- \futurelet : \overloaded needed -- \let : \overloaded sometimes needed - -primitive protection: - -\newif\iffoo \footrue \foofalse : problem when we make iftrue and iffalse -permanent ... they inherit, so we can't let them, we need a not permanent -alias which is again tricky ... something native? - -immutable : still \count000 but we can consider blocking that, for instance -by \def\count{some error} - -\defcsname -\edefcsname -\letcsname +% freezing pitfalls: +% +% - \futurelet : \overloaded needed +% - \let : \overloaded sometimes needed +% +% primitive protection: +% +% \newif\iffoo \footrue \foofalse : problem when we make iftrue and iffalse +% permanent ... they inherit, so we can't let them, we need a not permanent +% alias which is again tricky ... something native? +% +% immutable : still \count000 but we can consider blocking that, for instance +% by \def\count{some error} +% +% \defcsname +% \edefcsname +% \letcsname diff --git a/doc/context/sources/general/manuals/lowlevel/lowlevel-marks.tex b/doc/context/sources/general/manuals/lowlevel/lowlevel-marks.tex index 6eef0dd01..0ea92f150 100644 --- a/doc/context/sources/general/manuals/lowlevel/lowlevel-marks.tex +++ b/doc/context/sources/general/manuals/lowlevel/lowlevel-marks.tex @@ -1,14 +1,12 @@ % language=us runpath=texruns:manuals/lowlevel -\startcomponent lowlevel-marks - \environment lowlevel-style \startdocument [title=marks, color=middlemagenta] -\startsection[title=Introduction] +\startsectionlevel[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 @@ -50,9 +48,9 @@ In this document we discuss marks but assume that \LUAMETATEX\ is used with a few \LUA\ mechanisms, but it is to be seen if that will be either a replacement or an alternative. -\stopsection +\stopsectionlevel -\startsection[title=The basics] +\startsectionlevel[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: @@ -117,9 +115,9 @@ The current, latest assigned, value of a mark is available too: Using this value in for instance headers and footers makes no sense because the last node set can be on a following page. -\stopsection +\stopsectionlevel -\startsection[title=Migration] +\startsectionlevel[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 @@ -306,9 +304,9 @@ Here \type {sm} means \quote {set mark} while \type {rm} would indicate a \quote the box and thereby have become a a specific box property as can be seen in the above trace. -\stopsection +\stopsectionlevel -\startsection[title=Tracing] +\startsectionlevel[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 @@ -355,9 +353,9 @@ When tracing is set to 2 you also get details we get a list of marks of the anal 1:9: ..bot {sample 9.1} \stoptyping -\stopsection +\stopsectionlevel -\startsection[title=High level commands] +\startsectionlevel[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 @@ -493,14 +491,21 @@ The following three variants are (what is called) fully expandable: % \resetsynchronizemarking[#1]% % \synchronizemarking[#1][#2][#3]% (#3: options (no longer used)) -\stopsection +\stopsectionlevel -\startsection[title=Pitfalls] +\startsectionlevel[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 +\stopsectionlevel \stopdocument + +% Musical timestamp: videos showing up on YT with Nandi Bushell performing with +% Dave Grohl (e.g. https://www.youtube.com/watch?v=_AVkGj41RuA) ... the highlight +% of a nice and emotional thread of exchange between a young and capable energetic +% drummer challenging an experienced musician. During the pandemic one could +% witness quite some interesting musical experiments and Nandi and Yoyoka are some +% inspiring discoveries. diff --git a/doc/context/sources/general/manuals/lowlevel/lowlevel-paragraphs.tex b/doc/context/sources/general/manuals/lowlevel/lowlevel-paragraphs.tex index 1c0264630..b4a3c5da3 100644 --- a/doc/context/sources/general/manuals/lowlevel/lowlevel-paragraphs.tex +++ b/doc/context/sources/general/manuals/lowlevel/lowlevel-paragraphs.tex @@ -6,7 +6,7 @@ [title=paragraphs, color=middlecyan] -\startsection[title=Introduction] +\startsectionlevel[title=Introduction] This manual is mostly discussing a few low level wrappers around low level \TEX\ features. Its writing is triggered by an update to the \METAFUN\ and \LUAMETAFUN\ @@ -29,9 +29,9 @@ they get enabled by default. \footnote {For this we have \type them, make sure they don't interfere; they are not part of the updates, contrary to \type {cont-new.mkxl}.} -\stopsection +\stopsectionlevel -\startsection[title=Paragraphs] +\startsectionlevel[title=Paragraphs] Before we demonstrate some trickery, let's see what a paragraph is. Normally a document source is formatted like this: @@ -200,9 +200,9 @@ program it using macros: pickup a token, check and push it back when it's not a par equivalent token. The primitive is is just nicer (and easier on the log when tracing is enabled). -\stopsection +\stopsectionlevel -\startsection[title=Properties] +\startsectionlevel[title=Properties] A paragraph is just a collection of lines that result from one input line that got broken. This process of breaking into lines is influenced by quite some @@ -319,9 +319,9 @@ this new mechanism has been active for a while. Actually, when you now change a parameter inside the paragraph its new value will not be applied (unless you prefix it with \type {\frozen} or snapshot it) but no one did that anyway. -\stopsection +\stopsectionlevel -\startsection[title=Wrapping up] +\startsectionlevel[title=Wrapping up] In \CONTEXT\ \LMTX\ we have a mechanism to exercise macros (or content) before a paragraph ends. This is implemented using the \type {\wrapuppar} primitive. The @@ -343,9 +343,9 @@ question is: where do we apply it in old mechanisms and where not. % $$x = \vcenter{vcenter : \wrapuppar{1}test\par x\wrapuppar{2}test}$$\blank % x\vadjust{vadjust : \wrapuppar{1}test\par x\wrapuppar{2}test}x\blank -\stopsection +\stopsectionlevel -\startsection[title=Hanging] +\startsectionlevel[title=Hanging] There are two mechanisms for getting a specific paragraph shape: rectangular hanging and arbitrary shapes. Both mechanisms work top|-|down. The first @@ -377,9 +377,9 @@ uses at the same time). \stopcombination \stopplacefigure -\stopsection +\stopsectionlevel -\startsection[title=Shapes] +\startsectionlevel[title=Shapes] In \CONTEXT\ we don't use \type {\parshape} a lot. It is used in for instance side floats but even there not in all cases. It's more meant for special @@ -970,10 +970,10 @@ examples are visualized in \in {figure} [fig:flow]. \stopcombination \stopplacefigure -\stopsection +\stopsectionlevel -% \startsection[title=Linebreaks] -\startsection[title=Modes] +% \startsectionlevel[title=Linebreaks] +\startsectionlevel[title=Modes] % \ruledvbox{1\ifhmode\writestatus{!}{HMODE 1}\fi} % hsize % \ruledvbox{\hbox{\strut 2}\ifhmode\writestatus{!}{HMODE 2}\fi} % fit @@ -984,15 +984,15 @@ examples are visualized in \in {figure} [fig:flow]. {\em todo: some of the side effects of so called modes} -\stopsection +\stopsectionlevel -\startsection[title=Normalization] +\startsectionlevel[title=Normalization] {\em todo: users don't need to bother about this but it might be interesting anyway} -\stopsection +\stopsectionlevel -\startsection[title=Dirty tricks] +\startsectionlevel[title=Dirty tricks] {\em todo: explain example for combining paragraphs} @@ -1008,7 +1008,7 @@ examples are visualized in \in {figure} [fig:flow]. % % test -\stopsection +\stopsectionlevel \stopdocument diff --git a/doc/context/sources/general/manuals/lowlevel/lowlevel-registers.tex b/doc/context/sources/general/manuals/lowlevel/lowlevel-registers.tex index f24019f0d..4dbee67cd 100644 --- a/doc/context/sources/general/manuals/lowlevel/lowlevel-registers.tex +++ b/doc/context/sources/general/manuals/lowlevel/lowlevel-registers.tex @@ -6,7 +6,7 @@ [title=registers, color=darkmagenta] -\startsection[title=Preamble] +\startsectionlevel[title=Preamble] Registers are sets of variables that are accessed by index and a such resemble registers in a processing unit. You can store a quantity in a register, retrieve @@ -14,9 +14,9 @@ it, and also manipulate it. There is hardly any need to use them in \CONTEXT\ so we keep it simple. -\stopsection +\stopsectionlevel -\startsection[title={\TEX\ primitives}] +\startsectionlevel[title={\TEX\ primitives}] There are several categories: @@ -105,9 +105,11 @@ but in a macro package you should not use that one but the higher level \type Watch the difference: +\pushoverloadmode \startlines\tt \getbuffer[1,2] \stoplines +\popoverloadmode The first definition uses a yet free register so you won't get a clash. The second one is just a shortcut using a macro and the third one too but again @@ -182,9 +184,9 @@ If you want to know more about all these quantities, \quotation {\TEX\ By Topic} provides a good summary of what \TEX\ has to offer, and there is no need to repeat it here. -\stopsection +\stopsectionlevel -\startsection[title={\ETEX\ primitives}] +\startsectionlevel[title={\ETEX\ primitives}] Apart from the ability to use expressions, the contribution to registers that \ETEX\ brought was that suddenly we could use upto 65K of them, which is more @@ -194,9 +196,9 @@ and later \LUATEX\ regular arrays were used, at the cost of more memory which in the meantime has become cheap. As \CONTEXT\ moved to \ETEX\ rather early its users never had to worry about it. -\stopsection +\stopsectionlevel -\startsection[title={\LUATEX\ primitives}] +\startsectionlevel[title={\LUATEX\ primitives}] The \LUATEX\ engine introduced attributes. These are numeric properties that are bound to the nodes that are the result of typesetting operations. They are @@ -239,13 +241,13 @@ Just be aware that defining attributes can have an impact on performance. As you cannot access them at the \TEX\ end you seldom need them. If you do you can better use the proper more high level definers (not discussed here). -\stopsection +\stopsectionlevel -\startsection[title={\LUAMETATEX\ primitives}] +\startsectionlevel[title={\LUAMETATEX\ primitives}] {\em todo} -\stopsection +\stopsectionlevel \stopdocument diff --git a/doc/context/sources/general/manuals/lowlevel/lowlevel-scope.tex b/doc/context/sources/general/manuals/lowlevel/lowlevel-scope.tex index 484e80a0b..cfd9f9611 100644 --- a/doc/context/sources/general/manuals/lowlevel/lowlevel-scope.tex +++ b/doc/context/sources/general/manuals/lowlevel/lowlevel-scope.tex @@ -9,15 +9,15 @@ [title=scope, color=middleblue] -\startsection[title=Introduction] +\startsectionlevel[title=Introduction] When I visited the file where register allocations are implemented I wondered to what extend it made sense to limit allocation to global instances only. This chapter deals with this phenomena. -\stopsection +\stopsectionlevel -\startsection[title=Registers] +\startsectionlevel[title=Registers] In \TEX\ definitions can be local or global. Most assignments are local within a group. Registers and definitions can be assigned global by using the \type @@ -108,9 +108,9 @@ here the dimension is \the\scratchdimen\par \typebuffer[option=TEX] \startlines \getbuffer \stoplines -\stopsection +\stopsectionlevel -\startsection[title=Allocation] +\startsectionlevel[title=Allocation] The plain \TEX\ format has set some standards and one of them is that registers are allocated with \type {\new...} commands. So we can say: @@ -252,9 +252,9 @@ So, again we get: When used in the body of the macro there is of course a little overhead involved in the repetitive allocation but normally that can be neglected. -\stopsection +\stopsectionlevel -\startsection[title=Files] +\startsectionlevel[title=Files] When adding these new allocators I also wondered about the read and write allocators. We don't use them in \CONTEXT\ but maybe users like them, so let's @@ -334,7 +334,7 @@ SOME LINE 3 As you see in these examples, we an locally define a read channel without getting a message about it already being defined. -\stopsection +\stopsectionlevel \stopdocument diff --git a/doc/context/sources/general/manuals/lowlevel/lowlevel-security.tex b/doc/context/sources/general/manuals/lowlevel/lowlevel-security.tex index 0abc557b6..bdb3a5b87 100644 --- a/doc/context/sources/general/manuals/lowlevel/lowlevel-security.tex +++ b/doc/context/sources/general/manuals/lowlevel/lowlevel-security.tex @@ -21,7 +21,7 @@ [title=security, color=middleorange] -\startsection[title=Preamble] +\startsectionlevel[title=Preamble] Here I will discuss a moderate security subsystem of \LUAMETATEX\ and therefore \CONTEXT\ \LMTX. This is not about security in the sense of the typesetting @@ -35,9 +35,9 @@ might take a few years before the security model is finalized and all files are updated accordingly. There are lots of files and macros involved. In the process the underlying features in the engine might evolve. -\stopsection +\stopsectionlevel -\startsection[title=Flags] +\startsectionlevel[title=Flags] Before we go into the security levels we see what flags can be set. The \TEX\ language has a couple of so called prefixes that can be used when setting values @@ -205,9 +205,9 @@ really want to avoid that you can set the overload mode to 255 after which it cannot be set any more. However, it can be useful to set the mode to zero (or some warning level) when foreign macro packages are used. -\stopsection +\stopsectionlevel -\startsection[title=Complications] +\startsectionlevel[title=Complications] One side effect of all this is that all those prefixes can lead to more code. On the other hand we save some due to the extended macro argument handling features. @@ -220,9 +220,9 @@ about the same. \footnote {And if you wonder about memory, by compacting the use (often scattered) token memory before dumping I manages to save some 512K on the format file, so often the loss and gain are somewhere else.} -\stopsection +\stopsectionlevel -\startsection[title=Introspection] +\startsectionlevel[title=Introspection] In case you want to get some details about the properties of a macro, you can check its meaning. The full variant shows all of them. @@ -241,7 +241,7 @@ check its meaning. The full variant shows all of them. \startpacked \getbuffer \stoppacked -\stopsection +\stopsectionlevel % In \CONTEXT: % c! v! s! ?? diff --git a/doc/context/sources/general/manuals/lowlevel/lowlevel-style.tex b/doc/context/sources/general/manuals/lowlevel/lowlevel-style.tex index 12ccee0b5..a8eba991e 100644 --- a/doc/context/sources/general/manuals/lowlevel/lowlevel-style.tex +++ b/doc/context/sources/general/manuals/lowlevel/lowlevel-style.tex @@ -44,6 +44,10 @@ [style=\bfa, color=darkgray] +\setuplist + [chapter] + [style=bold] + \setupfootertexts [section] % [\documentvariable{title}] @@ -87,6 +91,15 @@ withcolor "white" ; \stopuseMPgraphic +\definesectionlevels + [default] + [%{chapter,title}, + {section,subject}, + {subsection,subsubject}, + {subsubsection,subsubsubject}, + {subsubsubsection,subsubsubject}, + {subsubsubsubsection,subsubsubject}] + \startsetups document:start \startMPpage @@ -95,9 +108,29 @@ \page - \startsubject[title=Contents] - \placelist[section][criterium=previous] - \stopsubject + \startsubjectlevel[title=Contents] + \placelist[chapter,section] [criterium=previous] + \stopsubjectlevel + +\stopsetups + +\startsetups document:stop + +\testpage[6] + +%startsubjectlevel[title=Colofon] +\startsectionlevel[title=Colofon,number=no,saveinlist=no] + + \starttabulate + \NC Author \NC Hans Hagen \NC \NR + \NC \CONTEXT \NC \contextversion \NC \NR + \NC \LUAMETATEX \NC \texengineversion \NC \NR + \NC Support \NC www.pragma-ade.com \NC \NR + \NC \NC contextgarden.net \NC \NR + \stoptabulate + +\stopsectionlevel +%stopsubjectlevel \stopsetups diff --git a/doc/context/sources/general/manuals/lowlevel/lowlevel.tex b/doc/context/sources/general/manuals/lowlevel/lowlevel.tex new file mode 100644 index 000000000..b958308a2 --- /dev/null +++ b/doc/context/sources/general/manuals/lowlevel/lowlevel.tex @@ -0,0 +1,39 @@ +% language=us runpath=texruns:manuals/lowlevel + +\environment lowlevel-style + +%D This is a bit if a cheat. The low level manuals are independent but I want an +%D overview document on the website. Therefore we use sectionlevels in the documents +%D that we we then overload here (we push the chapter level in front). + +\starttext + + \definesectionlevels + [default] + [{chapter,title}, + {section,subject}, + {subsection,subsubject}, + {subsubsection,subsubsubject}, + {subsubsubsection,subsubsubject}, + {subsubsubsubsection,subsubsubject}] + + \startdocument[title=lowlevel,color=middlegray] + \stopdocument + + \startsectionlevel[title=Conditionals] \component [lowlevel-conditionals] \stopsectionlevel + \startsectionlevel[title=Boxes] \component [lowlevel-boxes] \stopsectionlevel + \startsectionlevel[title=Expansion] \component [lowlevel-expansion] \stopsectionlevel + \startsectionlevel[title=Registers] \component [lowlevel-registers] \stopsectionlevel + \startsectionlevel[title=Macros] \component [lowlevel-macros] \stopsectionlevel + \startsectionlevel[title=Grouping] \component [lowlevel-grouping] \stopsectionlevel + \startsectionlevel[title=Security] \component [lowlevel-security] \stopsectionlevel + \startsectionlevel[title=Characters] \component [lowlevel-characters] \stopsectionlevel + \startsectionlevel[title=Scope] \component [lowlevel-scope] \stopsectionlevel + \startsectionlevel[title=Paragraphs] \component [lowlevel-paragraphs] \stopsectionlevel + \startsectionlevel[title=Alignments] \component [lowlevel-alignments] \stopsectionlevel + \startsectionlevel[title=Marks] \component [lowlevel-marks] \stopsectionlevel + \startsectionlevel[title=Inserts] \component [lowlevel-inserts] \stopsectionlevel + +\stoptext + + |