diff options
| author | Hans Hagen <pragma@wxs.nl> | 2020-10-31 00:09:22 +0100 |
|---|---|---|
| committer | Context Git Mirror Bot <phg@phi-gamma.net> | 2020-10-31 00:09:22 +0100 |
| commit | 7043cd3b7046f6a11112a5d49c4ae5e2dc0c6896 (patch) | |
| tree | 92ffcd258fb29e37b4a136eb071fbfd0717be29e /doc/context | |
| parent | a0270f13065d116355a953c6f246cbba26289fc2 (diff) | |
| download | context-7043cd3b7046f6a11112a5d49c4ae5e2dc0c6896.tar.gz | |
2020-10-30 22:27:00
Diffstat (limited to 'doc/context')
21 files changed, 499 insertions, 236 deletions
diff --git a/doc/context/documents/general/manuals/luametatex.pdf b/doc/context/documents/general/manuals/luametatex.pdf Binary files differindex b3b05d2f9..0455781a3 100644 --- a/doc/context/documents/general/manuals/luametatex.pdf +++ b/doc/context/documents/general/manuals/luametatex.pdf diff --git a/doc/context/scripts/mkiv/context.html b/doc/context/scripts/mkiv/context.html index d13a88d45..808da3209 100644 --- a/doc/context/scripts/mkiv/context.html +++ b/doc/context/scripts/mkiv/context.html @@ -14,7 +14,7 @@ <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"> <head> - <title>ConTeXt Process Management 1.03</title> + <title>ConTeXt Process Management 1.04</title> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> <style type="text/css"> body { color: #FFFFFF; background-color: #808080; font-family: optima, verdana, futura, "lucida sans", arial, geneva, helvetica, sans; font-size: 12px; line-height: 18px; } a:link, a:active, a:visited { color: #FFFFFF; } a.dir-view:link, a.dir-view:active, a.dir-view:visited { color: #FFFFFF; text-decoration: underline; } .valid { color: #00FF00; } .invalid { color: #FF0000; } .invisible { visibility: hidden; } button, .commonlink, .smallbutton { font-weight: bold; font-size: 12px; text-decoration: none; color: #000000; border-color: #7F7F7F; border-style: solid; border-width: .125ex; background-color: #FFFFFF; padding: .5ex; } .smallbutton { width: 1em; } a.commonlink:link, a.commonlink:active, a.commonlink:visited, a.smalllink:link, a.smalllink:active, a.smalllink:visited { font-weight: bold; font-size: 12px; text-decoration: none; color: #000000; } h1, .title { font-style: normal; font-weight: normal; font-size: 18px; line-height: 18px; margin-bottom: 20px; } h2, .subtitle { font-style: normal; font-weight: normal; font-size: 12px; margin-top: 18px; margin-bottom: 18px; } table { line-height: 18px; font-size: 12px; margin: 0; } th { font-weight: bold; text-align: left; padding-bottom: 6px; } .tc { font-weight: bold; text-align: left; } p, li { max-width: 60em; } .empty-line { margin-top: 4px; } .more-room { margin-right: 1.5em; } .much-more-room { margin-right: 3em; } #main { position: absolute; left: 10%; top: 10%; right: 10%; bottom: 10%; z-index: 2; width: 80%; height: 80%; padding: 0%; margin: 0%; overflow: auto; border-style: none; border-width: 0; background-color: #3F3F3F; } #main-settings { margin: 12px; x_max-width: 60em; line-height: 18px; font-size: 12px; } #left { position: absolute; top : 10%; left: 0%; bottom: 0%; right: 90%; z-index: 1; width: 10%; height: 90%; padding: 0%; margin: 0%; font-size: 16px; border-style: none; border-width: 0; background-color: #4F6F6F; } #right { position: absolute; top : 0%; left: 90%; bottom: 10%; right: 0%; z-index: 1; width: 10%; height: 90%; padding: 0%; margin: 0%; font-size: 16px; border-style: none; border-width: 0; background-color: #4F6F6F; _margin-left: -15px; } #bottom { position: absolute; left: 10%; right: 0%; top: 90%; bottom: 0%; z-index: 1; width: 90%; height: 10%; padding: 0%; margin: 0%; font-size: 16px; border-style: none; border-width: 0; background-color: #6F6F8F; } #top { position: absolute; left: 0%; right: 10%; top: 0%; bottom: 90%; z-index: 1; width: 90%; height: 10%; padding: 0%; margin: 0%; font-size: 16px; border-style: none; border-width: 0; background-color: #6F6F8F; } #top-one { position: absolute; bottom: 50%; width: 100%; buggedheight: 100%; } #top-two { position: relative; margin-bottom: -9px; margin-left: 12px; margin-right: 12px; line-height: 18px; text-align: right; vertical-align: middle; } #bottom-one { position: absolute; bottom: 50%; width: 100%; buggedheight: 100%; } #bottom-two { position: relative; margin-bottom: -9px; margin-left: 12px; margin-right: 12px; line-height: 18px; text-align: left; vertical-align: middle; } #left-one { position: absolute; width: 100%; buggedheight: 100%; } #left-two { position: relative; margin-top: 12px; line-height: 18px; text-align: center; vertical-align: top; } #right-one { display: table; height: 100%; width: 100%; } #right-two { display: table-row; height: 100%; width: 100%; } #right-three { display: table-cell; width: 100%; vertical-align: bottom; _position: absolute; _top: 100%; } #right-four { text-align: center; margin-bottom: 2ex; _position: relative; _top: -100%; } #more-top { position: absolute; top: 0%; left: 90%; bottom: 90%; right: 0%; z-index: 3; width: 10%; height: 10%; padding: 0%; margin: 0%; border-style: none; border-width: 0; } #more-top-settings { text-align: center; } #more-right-settings { margin-right: 12px; margin-left: 12px; line-height: 18px; font-size: 10px; text-align: center; } #right-safari { _display: table; width: 100%; height: 100%; } @@ -24,7 +24,7 @@ </head> <body> <div id="top"> <div id="top-one"> - <div id="top-two">ConTeXt Process Management 1.03 </div> + <div id="top-two">ConTeXt Process Management 1.04 </div> </div> </div> <div id="bottom"> <div id="bottom-one"> @@ -108,6 +108,7 @@ <tr><th>--keeptuc</th><td></td><td>keep previous tuc files (jobname-tuc-[run].tmp)</td></tr> <tr><th>--keeplog</th><td></td><td>keep previous log files (jobname-log-[run].tmp)</td></tr> <tr><th>--lmtx</th><td></td><td>force lmtx mode (when available)</td></tr> + <tr><th>--overloadmode=error|warning|0--6|255</th><td></td><td>enable csname overload checking</td></tr> <tr><th/><td/><td/></tr> <tr><th>--extra=name</th><td></td><td>process extra (mtx-context-... in distribution)</td></tr> <tr><th>--extras</th><td></td><td>show extras</td></tr> diff --git a/doc/context/scripts/mkiv/context.man b/doc/context/scripts/mkiv/context.man index 23d986903..5f3c33a4a 100644 --- a/doc/context/scripts/mkiv/context.man +++ b/doc/context/scripts/mkiv/context.man @@ -1,4 +1,4 @@ -.TH "mtx-context" "1" "01-01-2020" "version 1.03" "ConTeXt Process Management" +.TH "mtx-context" "1" "01-01-2020" "version 1.04" "ConTeXt Process Management" .SH NAME mtx-context - ConTeXt Process Management .SH SYNOPSIS @@ -174,6 +174,9 @@ keep previous log files (jobname-log-[run].tmp) .B --lmtx force lmtx mode (when available) .TP +.B --overloadmode=error|warning|0--6|255 +enable csname overload checking +.TP .B --extra=name process extra (mtx-context-... in distribution) .TP diff --git a/doc/context/scripts/mkiv/context.xml b/doc/context/scripts/mkiv/context.xml index 8abafafa2..40751c613 100644 --- a/doc/context/scripts/mkiv/context.xml +++ b/doc/context/scripts/mkiv/context.xml @@ -4,7 +4,7 @@ <metadata> <entry name="name">mtx-context</entry> <entry name="detail">ConTeXt Process Management</entry> - <entry name="version">1.03</entry> + <entry name="version">1.04</entry> <entry name="comment">external helpinfo file</entry> </metadata> <flags> @@ -203,6 +203,9 @@ <flag name="lmtx"> <short>force lmtx mode (when available)</short> </flag> + <flag name="overloadmode=error|warning|0--6|255"> + <short>enable csname overload checking</short> + </flag> </subcategory> <subcategory> <flag name="extra=name"> diff --git a/doc/context/scripts/mkiv/mtx-context.html b/doc/context/scripts/mkiv/mtx-context.html index d13a88d45..808da3209 100644 --- a/doc/context/scripts/mkiv/mtx-context.html +++ b/doc/context/scripts/mkiv/mtx-context.html @@ -14,7 +14,7 @@ <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"> <head> - <title>ConTeXt Process Management 1.03</title> + <title>ConTeXt Process Management 1.04</title> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> <style type="text/css"> body { color: #FFFFFF; background-color: #808080; font-family: optima, verdana, futura, "lucida sans", arial, geneva, helvetica, sans; font-size: 12px; line-height: 18px; } a:link, a:active, a:visited { color: #FFFFFF; } a.dir-view:link, a.dir-view:active, a.dir-view:visited { color: #FFFFFF; text-decoration: underline; } .valid { color: #00FF00; } .invalid { color: #FF0000; } .invisible { visibility: hidden; } button, .commonlink, .smallbutton { font-weight: bold; font-size: 12px; text-decoration: none; color: #000000; border-color: #7F7F7F; border-style: solid; border-width: .125ex; background-color: #FFFFFF; padding: .5ex; } .smallbutton { width: 1em; } a.commonlink:link, a.commonlink:active, a.commonlink:visited, a.smalllink:link, a.smalllink:active, a.smalllink:visited { font-weight: bold; font-size: 12px; text-decoration: none; color: #000000; } h1, .title { font-style: normal; font-weight: normal; font-size: 18px; line-height: 18px; margin-bottom: 20px; } h2, .subtitle { font-style: normal; font-weight: normal; font-size: 12px; margin-top: 18px; margin-bottom: 18px; } table { line-height: 18px; font-size: 12px; margin: 0; } th { font-weight: bold; text-align: left; padding-bottom: 6px; } .tc { font-weight: bold; text-align: left; } p, li { max-width: 60em; } .empty-line { margin-top: 4px; } .more-room { margin-right: 1.5em; } .much-more-room { margin-right: 3em; } #main { position: absolute; left: 10%; top: 10%; right: 10%; bottom: 10%; z-index: 2; width: 80%; height: 80%; padding: 0%; margin: 0%; overflow: auto; border-style: none; border-width: 0; background-color: #3F3F3F; } #main-settings { margin: 12px; x_max-width: 60em; line-height: 18px; font-size: 12px; } #left { position: absolute; top : 10%; left: 0%; bottom: 0%; right: 90%; z-index: 1; width: 10%; height: 90%; padding: 0%; margin: 0%; font-size: 16px; border-style: none; border-width: 0; background-color: #4F6F6F; } #right { position: absolute; top : 0%; left: 90%; bottom: 10%; right: 0%; z-index: 1; width: 10%; height: 90%; padding: 0%; margin: 0%; font-size: 16px; border-style: none; border-width: 0; background-color: #4F6F6F; _margin-left: -15px; } #bottom { position: absolute; left: 10%; right: 0%; top: 90%; bottom: 0%; z-index: 1; width: 90%; height: 10%; padding: 0%; margin: 0%; font-size: 16px; border-style: none; border-width: 0; background-color: #6F6F8F; } #top { position: absolute; left: 0%; right: 10%; top: 0%; bottom: 90%; z-index: 1; width: 90%; height: 10%; padding: 0%; margin: 0%; font-size: 16px; border-style: none; border-width: 0; background-color: #6F6F8F; } #top-one { position: absolute; bottom: 50%; width: 100%; buggedheight: 100%; } #top-two { position: relative; margin-bottom: -9px; margin-left: 12px; margin-right: 12px; line-height: 18px; text-align: right; vertical-align: middle; } #bottom-one { position: absolute; bottom: 50%; width: 100%; buggedheight: 100%; } #bottom-two { position: relative; margin-bottom: -9px; margin-left: 12px; margin-right: 12px; line-height: 18px; text-align: left; vertical-align: middle; } #left-one { position: absolute; width: 100%; buggedheight: 100%; } #left-two { position: relative; margin-top: 12px; line-height: 18px; text-align: center; vertical-align: top; } #right-one { display: table; height: 100%; width: 100%; } #right-two { display: table-row; height: 100%; width: 100%; } #right-three { display: table-cell; width: 100%; vertical-align: bottom; _position: absolute; _top: 100%; } #right-four { text-align: center; margin-bottom: 2ex; _position: relative; _top: -100%; } #more-top { position: absolute; top: 0%; left: 90%; bottom: 90%; right: 0%; z-index: 3; width: 10%; height: 10%; padding: 0%; margin: 0%; border-style: none; border-width: 0; } #more-top-settings { text-align: center; } #more-right-settings { margin-right: 12px; margin-left: 12px; line-height: 18px; font-size: 10px; text-align: center; } #right-safari { _display: table; width: 100%; height: 100%; } @@ -24,7 +24,7 @@ </head> <body> <div id="top"> <div id="top-one"> - <div id="top-two">ConTeXt Process Management 1.03 </div> + <div id="top-two">ConTeXt Process Management 1.04 </div> </div> </div> <div id="bottom"> <div id="bottom-one"> @@ -108,6 +108,7 @@ <tr><th>--keeptuc</th><td></td><td>keep previous tuc files (jobname-tuc-[run].tmp)</td></tr> <tr><th>--keeplog</th><td></td><td>keep previous log files (jobname-log-[run].tmp)</td></tr> <tr><th>--lmtx</th><td></td><td>force lmtx mode (when available)</td></tr> + <tr><th>--overloadmode=error|warning|0--6|255</th><td></td><td>enable csname overload checking</td></tr> <tr><th/><td/><td/></tr> <tr><th>--extra=name</th><td></td><td>process extra (mtx-context-... in distribution)</td></tr> <tr><th>--extras</th><td></td><td>show extras</td></tr> diff --git a/doc/context/scripts/mkiv/mtx-context.man b/doc/context/scripts/mkiv/mtx-context.man index 23d986903..5f3c33a4a 100644 --- a/doc/context/scripts/mkiv/mtx-context.man +++ b/doc/context/scripts/mkiv/mtx-context.man @@ -1,4 +1,4 @@ -.TH "mtx-context" "1" "01-01-2020" "version 1.03" "ConTeXt Process Management" +.TH "mtx-context" "1" "01-01-2020" "version 1.04" "ConTeXt Process Management" .SH NAME mtx-context - ConTeXt Process Management .SH SYNOPSIS @@ -174,6 +174,9 @@ keep previous log files (jobname-log-[run].tmp) .B --lmtx force lmtx mode (when available) .TP +.B --overloadmode=error|warning|0--6|255 +enable csname overload checking +.TP .B --extra=name process extra (mtx-context-... in distribution) .TP diff --git a/doc/context/scripts/mkiv/mtx-context.xml b/doc/context/scripts/mkiv/mtx-context.xml index 8abafafa2..40751c613 100644 --- a/doc/context/scripts/mkiv/mtx-context.xml +++ b/doc/context/scripts/mkiv/mtx-context.xml @@ -4,7 +4,7 @@ <metadata> <entry name="name">mtx-context</entry> <entry name="detail">ConTeXt Process Management</entry> - <entry name="version">1.03</entry> + <entry name="version">1.04</entry> <entry name="comment">external helpinfo file</entry> </metadata> <flags> @@ -203,6 +203,9 @@ <flag name="lmtx"> <short>force lmtx mode (when available)</short> </flag> + <flag name="overloadmode=error|warning|0--6|255"> + <short>enable csname overload checking</short> + </flag> </subcategory> <subcategory> <flag name="extra=name"> diff --git a/doc/context/sources/general/manuals/evenmore/evenmore-keywords.tex b/doc/context/sources/general/manuals/evenmore/evenmore-keywords.tex index 1cd0bee25..1ffacf0ab 100644 --- a/doc/context/sources/general/manuals/evenmore/evenmore-keywords.tex +++ b/doc/context/sources/general/manuals/evenmore/evenmore-keywords.tex @@ -1,5 +1,10 @@ % language=us +% Talking of keywords: Jacob Collier, Count The People is definitely an example +% of showing keywords and no way that the fonts used there are done by tex: +% +% https://www.youtube.com/watch?v=icplHV25fqs + \environment evenmore-style \startcomponent evenmore-keywords @@ -288,6 +293,103 @@ weren't the case. % \luaexpr{(0.076+0.085+0.088+0.073+0.078)/5} 0.080\crlf % \luaexpr{(0.136+0.138+0.142+0.135+0.140)/5} 0.138\crlf +After the \CONTEXT\ 2020 meeting I entered another round of staring at the code. +One of the decision made at that meeting was to drop the \type {nd} and \type +{nc} units as they were never official. That made me (again) wonder of that bit +of the code could be done nicer as there is a mix of scanning units like \type +{pt}, \type {bp} and \type {cm}, fillers like \type {fi} and \type {fill}, pseudo +units like \type {ex} and \type {em}, special interception of \type {mu}, as well +as the \type {plus} and \type {minus} parsing for glue. That code was already +redone a bit so that here was less push back of tokens which had the side effect +of dimension scanning being some 50\% faster than in \LUATEX. + +The same is true for scanning rule specs and scanning the box properties. In the +later case part of the optimization came from not checking properties that +already had been set, or only scanning them when for instance the \type +{orientation} flag had been set (a new option in \LUAMETATEX\ with an additional +four offset and move parameters). Also, some options, like the target dimensions, +came after scanning the new ones. Again, this was quite a bit faster than in +\LUATEX, not that it is noticeable on a normal run. All is mixed with skipping +spacers and relax tokens plus quitting at a brace. + +Similar mixed scanning happens in some of the (new) math command, but these are +less critical. Actually there some new commands had to be used because for +instance \type {\over} takes any character as valid argument and keywords would +definitely be incompatible there. + +Anyway, I started wondering if some could be done differently and finally decided +to use a method that I already played with years ago. The main reason for not +using it was that I wanted to remain compatible with the way traditional \TEX\ +scans. However, as we have many more keyword we already are no longer compatible +in that department and the alternative implementation makes the code look nicer +and has the benefit of being (more than) twice as fast. And when I run into +issues in \CONTEXT\ I should just fix sloppy code. + +The compatibility issue is not really a problem when you consider the following +cases. + +\starttyping +\hbox reverse attr 123 456 orientation 4 xoffset 10pt spread 10cm { } +\hrule xoffset 10pt width 10cm depth 3mm +\hskip 3pt plus 2pt minus 1pt +\stoptyping + +In the original approach these three case each have their own special side +effects. In the case of a \type {\hbox} the scanning stops at a relax or left +brace. An unknown keyword gives an error. So, there is no real benefit in pushing +back tokens here. The order matters: the \type {spread} or \type {to} comes last. + +In the case of a \type {\hrule} the scanning stops when the keyword is not one of +the known. This has the side effect that when such a rule definition is hidden in +a macro and followed by for instance \type {width} without unit one gets an error +and when a unit is given the rule can come out different than expected and the +text is gone. For that reason a rule specification like this is often closed by +\type {\relax} (any command that doesn't expand to a keyword works too). Here +keywords can occur multiple times. As we have additional keyword a lookahead +becomes even more an issue (not that \type {xoffset}) is a likely candidate. + +The last example is special in a different way: order matters in the sense that a +\type {minus} specifier can follow a \type {plus} but not the reverse. And only +one \type {plus} and \type {minus} can be given. Again one can best finish this +specification by a something that doesn't look like a keyword, so often one will +see a \type {\relax}. + +The advantage of the new method is that the order doesn't matter any more and +that using a keyword multiple times overloads earlier settings. And this is +consistent for all commands that used keywords (with a few exceptions in math +where keywords drive later parsing and for font definitions where we need to be +compatible. We give a slightly better error message: we mention the expected +keyword. Another side effect is that any characters that is a legal start of a +known keyword will trigger further parsing and issue an error message when it +fails. Indeed, \LUAMETATEX\ has no mercy. + +In practice the mentioned special effects mean that a macro package will not run +into trouble with boxes because unknown keywords make it crash and that rules and +glue is terminated in a way that prevents lookahead. The new method kind of +assumes this and one can argue that when something breaks one has to fix the +macro code. Macro writers know that one cannot predict what users come up with +and that users also don't look into the macros and therefore they take +precautions. Also, a more rigorous parsing results in hopefully a better message. + +And yes, when I ran the test suite there was indeed a case where I had to add a +\type {\relax}, but I can live with that. As long as users don't notice it. + +Now, one of the interesting properties of the slightly different scanning is +that we can do this: + +\starttyping +\hbox to 4cm attr 123 456 reverse to 3cm {...} +\stoptyping + +So, we have a less strict order and we can overload arguments too. We'll see how +this will be applied in \CONTEXT. + \stopchapter \stopcomponent + +% another nice example: \the is expanded so we get the old value + +% \scratchskip = 10pt plus 1fill \the\scratchskip % old value +% \scratchskip = 10pt plus 1fill [\the\scratchskip] % new value +% \scratchskip = 10pt plus 1fi l l [\the\scratchskip] % also works diff --git a/doc/context/sources/general/manuals/evenmore/evenmore.tex b/doc/context/sources/general/manuals/evenmore/evenmore.tex index 87044b34d..b351e8c68 100644 --- a/doc/context/sources/general/manuals/evenmore/evenmore.tex +++ b/doc/context/sources/general/manuals/evenmore/evenmore.tex @@ -25,10 +25,19 @@ \component evenmore-parsing \component evenmore-tokens \component evenmore-keywords + + \startchapter[title=Paragraphs] {\em This chapter is not yet public.} \stopchapter + \startchapter[title=Hyphenation] {\em This chapter is not yet public.} \stopchapter + \startchapter[title=Bitwise] {\em This chapter is not yet public.} \stopchapter + \startchapter[title=Offloading] {\em This chapter is not yet public.} \stopchapter + \startchapter[title=Inserts] {\em This chapter is not yet public.} \stopchapter + % \component evenmore-paragraphs % \component evenmore-hyphenation % \component evenmore-bitwise % \component evenmore-offloading + % \component evenmore-inserts + \stopbodymatter \stopdocument diff --git a/doc/context/sources/general/manuals/lowlevel/lowlevel-conditionals.tex b/doc/context/sources/general/manuals/lowlevel/lowlevel-conditionals.tex index ea3c9e1a2..ff23d1909 100644 --- a/doc/context/sources/general/manuals/lowlevel/lowlevel-conditionals.tex +++ b/doc/context/sources/general/manuals/lowlevel/lowlevel-conditionals.tex @@ -1224,6 +1224,15 @@ defined at the user level or is a build in one. This one might evolve. \stopsubsection +\startsubsection[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 + \startsubsection[title={\tex{orelse}}] This it not really a test primitive but it does act that way. Say that we have this: @@ -1254,13 +1263,16 @@ A bit nicer looks this: \fi \stoptyping -We stay at the same level and the only test that cannot be used this way is \type -{\ifcondition} but that is no real problem. Sometimes a more flat test tree had -advantages but if you think that it gives better performance then you will be -disappointed. The fact that we stay at the same level is compensated by a bit -more parsing, so unless you have millions such cases (or expansions) it might -make a bit of a difference. As mentioned, I'm a bit sensitive for how code looks so -that was the main motivation for introducing it. +% We stay at the same level and the only test that cannot be used this way is \type +% {\ifcondition} but that is no real problem. Sometimes a more flat test tree had + +We stay at the same level. Sometimes a more flat test tree had advantages but if +you think that it gives better performance then you will be disappointed. The +fact that we stay at the same level is compensated by a bit more parsing, so +unless you have millions such cases (or expansions) it might make a bit of a +difference. As mentioned, I'm a bit sensitive for how code looks so that was the +main motivation for introducing it. There is a companion \type {\orunless} +continuation primitive. A rather neat trick is the definition of \type {\quitcondition}: diff --git a/doc/context/sources/general/manuals/lowlevel/lowlevel-expansion.tex b/doc/context/sources/general/manuals/lowlevel/lowlevel-expansion.tex index 1e2e00a35..19c5efe12 100644 --- a/doc/context/sources/general/manuals/lowlevel/lowlevel-expansion.tex +++ b/doc/context/sources/general/manuals/lowlevel/lowlevel-expansion.tex @@ -315,7 +315,7 @@ Although you can never really get back to the original input, you can come prett close, with: \startbuffer -\normaldetokenize{this can $ be anything \bgroup} +\detokenize{this can $ be anything \bgroup} \stopbuffer \typebuffer[option=TEX] @@ -432,9 +432,26 @@ These two macros now have the meaning: \startsection[title={\LUAMETATEX\ primitives}] -{\em todo} +To be discussed: + +\starttyping +\expand +\expandtoken +\localcontrol +\localcontrolled +\beginlocalcontrol ... \endlocalcontrol +\immediate +\stoptyping + +And maybe also here: + +\starttyping +\tokenized : a bonus +\scantokens : original etex, now using the lua method +\stoptyping % \aftergroups +% \aftergrouped \stopsection diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-callbacks.tex b/doc/context/sources/general/manuals/luametatex/luametatex-callbacks.tex index d589e04bd..4c8a0db78 100644 --- a/doc/context/sources/general/manuals/luametatex/luametatex-callbacks.tex +++ b/doc/context/sources/general/manuals/luametatex/luametatex-callbacks.tex @@ -531,13 +531,13 @@ pass. You must not ruin the node list. For instance, the head normally is a local par node, and the tail a glue. Messing too much can push \LUATEX\ into panic mode. -\subsection{\type {insert_local_par}} +\subsection{\type {insert_par}} Each paragraph starts with a local par node that keeps track of for instance the direction. You can hook a callback into the creator: \startfunctioncall -function(<node> local_par, <string> location) +function(<node> par, <string> location) end \stopfunctioncall diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-differences.tex b/doc/context/sources/general/manuals/luametatex/luametatex-differences.tex index 482371cd9..ba3b903b0 100644 --- a/doc/context/sources/general/manuals/luametatex/luametatex-differences.tex +++ b/doc/context/sources/general/manuals/luametatex/luametatex-differences.tex @@ -236,7 +236,7 @@ if luatex and luametatex then -- context.page() - context("The following primitives are available in \\LUATEX\\ but not in \\LUAMETATEX.") + context("The following primitives are available in \\LUATEX\\ but not in \\LUAMETATEX. ") context("Some of these are emulated in \\CONTEXT.") context.startcolumns { n = 2 } @@ -251,7 +251,7 @@ if luatex and luametatex then -- context.page() - context("The following primitives are available in \\LUAMETATEX\\ only.") + context("The following primitives are available in \\LUAMETATEX\\ only. ") context("At some point in time some might be added to \\LUATEX.") context.startcolumns { n = 2 } diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-enhancements.tex b/doc/context/sources/general/manuals/luametatex/luametatex-enhancements.tex index a233bf630..ee30683e8 100644 --- a/doc/context/sources/general/manuals/luametatex/luametatex-enhancements.tex +++ b/doc/context/sources/general/manuals/luametatex/luametatex-enhancements.tex @@ -35,8 +35,8 @@ assigned to them at this early time (giving a \quote {Missing number} error), so it may be needed to put these assignments before the above line: \starttyping -\catcode `\{=1 -\catcode `\}=2 +\catcode `\{ = 1 +\catcode `\} = 2 \stoptyping More fine|-|grained primitives control is possible and you can look up the @@ -819,103 +819,123 @@ but faster (only measurable with millions of calls) and probably more convenient \stopsubsection -\startsubsection[title={\lpr {expanded}, \lpr {immediateassignment} and \lpr {immediateassigned}}] +\startsubsection[title={\lpr {expanded}}] \topicindex {expansion} -The \lpr {expanded} primitive takes a token list and expands its content which can -come in handy: it avoids a tricky mix of \prm {expandafter} and \prm {noexpand}. -You can compare it with what happens inside the body of an \prm {edef}. But this -kind of expansion still doesn't expand some primitive operations. - -\startbuffer -\newcount\NumberOfCalls - -\def\TestMe{\advance\NumberOfCalls1 } - -\edef\Tested{\TestMe foo:\the\NumberOfCalls} -\edef\Tested{\TestMe foo:\the\NumberOfCalls} -\edef\Tested{\TestMe foo:\the\NumberOfCalls} - -\meaning\Tested -\stopbuffer - -\typebuffer - -The result is a macro that has the not expanded code in its body: - -\getbuffer - -Instead we can define \tex {TestMe} in a way that expands the assignment -immediately. You need of course to be aware of preventing look ahead interference -by using a space or \tex {relax} (often an expression works better as it doesn't -leave an \tex {relax}). - -\startbuffer -\def\TestMe{\immediateassignment\advance\NumberOfCalls1 } - -\edef\Tested{\TestMe foo:\the\NumberOfCalls} -\edef\Tested{\TestMe foo:\the\NumberOfCalls} -\edef\Tested{\TestMe foo:\the\NumberOfCalls} - -\meaning\Tested -\stopbuffer - -\typebuffer - -This time the counter gets updates and we don't see interference in the -resulting \tex {Tested} macro: - -\getbuffer - -Here is a somewhat silly example of expanded comparison: - -\startbuffer -\def\expandeddoifelse#1#2#3#4% - {\immediateassignment\edef\tempa{#1}% - \immediateassignment\edef\tempb{#2}% - \ifx\tempa\tempb - \immediateassignment\def\next{#3}% - \else - \immediateassignment\def\next{#4}% - \fi - \next} - -\edef\Tested - {(\expandeddoifelse{abc}{def}{yes}{nop}/% - \expandeddoifelse{abc}{abc}{yes}{nop})} - -\meaning\Tested -\stopbuffer - -\typebuffer - -It gives: - -\getbuffer - -A variant is: +The \lpr {expanded} primitive takes a token list and expands its content which +can come in handy: it avoids a tricky mix of \prm {expandafter} and \prm +{noexpand}. You can compare it with what happens inside the body of an \prm +{edef}. The \tex {immediateassignment} and \tex {immediateassigned} commands are +gone because we have the more powerful local control commands. They are a tad +slower but this mechanism isn't used that much anyway. Inside an \prm {edef} you +can use the \type {\immediate} prefix anyway, so if you really want these +primitives back you can say: \starttyping -\def\expandeddoifelse#1#2#3#4% - {\immediateassigned{ - \edef\tempa{#1}% - \edef\tempb{#2}% - }% - \ifx\tempa\tempb - \immediateassignment\def\next{#3}% - \else - \immediateassignment\def\next{#4}% - \fi - \next} +\let\immediateassignment\immediate +\let\immediateassigned \localcontrolled \stoptyping -The possible error messages are the same as using assignments in preambles of -alignments and after the \prm {accent} command. The supported assignments are the -so called prefixed commands (except box assignments). - \stopsubsection +% \startsubsection[title={\lpr {expanded}, \lpr {immediateassignment} and \lpr {immediateassigned}}] +% +% \topicindex {expansion} +% +% The \lpr {expanded} primitive takes a token list and expands its content which can +% come in handy: it avoids a tricky mix of \prm {expandafter} and \prm {noexpand}. +% You can compare it with what happens inside the body of an \prm {edef}. But this +% kind of expansion still doesn't expand some primitive operations. +% +% \startbuffer +% \newcount\NumberOfCalls +% +% \def\TestMe{\advance\NumberOfCalls1 } +% +% \edef\Tested{\TestMe foo:\the\NumberOfCalls} +% \edef\Tested{\TestMe foo:\the\NumberOfCalls} +% \edef\Tested{\TestMe foo:\the\NumberOfCalls} +% +% \meaning\Tested +% \stopbuffer +% +% \typebuffer +% +% The result is a macro that has the not expanded code in its body: +% +% \getbuffer +% +% Instead we can define \tex {TestMe} in a way that expands the assignment +% immediately. You need of course to be aware of preventing look ahead interference +% by using a space or \tex {relax} (often an expression works better as it doesn't +% leave an \tex {relax}). +% +% \startbuffer +% \def\TestMe{\immediateassignment\advance\NumberOfCalls1 } +% +% \edef\Tested{\TestMe foo:\the\NumberOfCalls} +% \edef\Tested{\TestMe foo:\the\NumberOfCalls} +% \edef\Tested{\TestMe foo:\the\NumberOfCalls} +% +% \meaning\Tested +% \stopbuffer +% +% \typebuffer +% +% This time the counter gets updates and we don't see interference in the +% resulting \tex {Tested} macro: +% +% \getbuffer +% +% Here is a somewhat silly example of expanded comparison: +% +% \startbuffer +% \def\expandeddoifelse#1#2#3#4% +% {\immediateassignment\edef\tempa{#1}% +% \immediateassignment\edef\tempb{#2}% +% \ifx\tempa\tempb +% \immediateassignment\def\next{#3}% +% \else +% \immediateassignment\def\next{#4}% +% \fi +% \next} +% +% \edef\Tested +% {(\expandeddoifelse{abc}{def}{yes}{nop}/% +% \expandeddoifelse{abc}{abc}{yes}{nop})} +% +% \meaning\Tested +% \stopbuffer +% +% \typebuffer +% +% It gives: +% +% \getbuffer +% +% A variant is: +% +% \starttyping +% \def\expandeddoifelse#1#2#3#4% +% {\immediateassigned{ +% \edef\tempa{#1}% +% \edef\tempb{#2}% +% }% +% \ifx\tempa\tempb +% \immediateassignment\def\next{#3}% +% \else +% \immediateassignment\def\next{#4}% +% \fi +% \next} +% \stoptyping +% +% The possible error messages are the same as using assignments in preambles of +% alignments and after the \prm {accent} command. The supported assignments are the +% so called prefixed commands (except box assignments). +% +% \stopsubsection + \startsubsection[title={\lpr {ignorepars}}] This primitive is like \prm {ignorespaces} but also skips paragraph ending @@ -1291,6 +1311,24 @@ the acceptable range is from 0 to 65535. \stopsubsection +\startsubsection[title={\prm {hrule} and \prm {vrule}}] + +\topicindex {rules} + +Both rule drawing commands take an optional \type {xoffset} and \type {yoffset} +parameter. The displacement is virtual and not taken into account when the +dimensions are calculated. + +\stopsubsection + +\topicindex {splitting} + +The \prm {vsplit} primitive has to be followed by a specification of the required +height. As alternative for the \type {to} keyword you can use \type {upto} to get +a split of the given size but result has the natural dimensions then. + +\stopsubsection + \startsubsection[title={\prm {vsplit}}] \topicindex {splitting} @@ -1317,12 +1355,12 @@ point this approach was abandoned and a more natural trick was used: images (and box resources) became a special kind of rules, and as rules already have dimensions, the code could be simplified. -When direction nodes and localpar nodes also became first class nodes, whatsits -again became just that: nodes representing whatever you want, but without -dimensions, and therefore they could again be ignored when dimensions mattered. -And, because images were disguised as rules, as mentioned, their dimensions -automatically were taken into account. This seperation between front and backend -cleaned up the code base already quite a bit. +When direction nodes and (formerly local) par nodes also became first class +nodes, whatsits again became just that: nodes representing whatever you want, but +without dimensions, and therefore they could again be ignored when dimensions +mattered. And, because images were disguised as rules, as mentioned, their +dimensions automatically were taken into account. This separation between front +and backend cleaned up the code base already quite a bit. In \LUAMETATEX\ we still have the image specific subtypes for rules, but the engine never looks at subtypes of rules. That was up to the backend. This means @@ -1843,6 +1881,47 @@ take some time (and user input).} \stopsection +\startsection[title=Keywords] + +Some primitives accept one or more keywords and \LUAMETATEX\ adds some more. In +order to deal with this efficiently the keyword scanner has been optimized, where +even the context was taken into account. As a result the scanner was quite a bit +faster. This kind of optimization was a graduate process the eventually ended up +in what we have now. In traditional \TEX\ (and also \LUATEX) the order of +keywords is sometimes mixed and sometimes prescribed. In most cases only one +occurrence is permitted. So, for instance, this is valid in \LUATEX: + +\starttyping +\hbox attr 123 456 attr 123 456 spread 10cm { } +\hrule width 10cm depth 3mm +\hskip 3pt plus 2pt minus 1pt +\stoptyping + +The \type {attr} comes before the \type {spread}, rules can have multiple mixed +dimension specifiers, and in glue the optional \type {minus} part always comes +last. The last two commands are famous for look ahead side effects which is why +macro packages will end them with something not keyword, like \type {\relax}, +when needed. + +In \LUAMETATEX\ the following is okay. Watch the few more keywords in box and +rule specifications. + +\starttyping +\hbox reverse to 10cm attr 123 456 orientation 4 xoffset 10pt spread 10cm { } +\hrule xoffset 10pt width 10cm depth 3mm +\hskip 3pt minus 1pt plus 2pt +\stoptyping + +Here the order is not prescribed and, as demonstrated with the box specifier, for +instance dimensions (specified by \type {to} or \type {spread} can be overloaded +by later settings. In case you wonder if that breaks compatibility: in some way +it does but bad or sloppy keyword usage breaks a run anyway. For instance \type +{minuscule} results in \type {minus} with no dimension being seen. So, in the end +the user should not noticed it and when a user does, the macro package already +had an issue that had to be fixed. + +\stopsection + \startsection[title=Expressions] The \type {*expr} parsers now accept \type {:} as operator for integer division diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-introduction.tex b/doc/context/sources/general/manuals/luametatex/luametatex-introduction.tex index 2afdf75bd..1ad055a83 100644 --- a/doc/context/sources/general/manuals/luametatex/luametatex-introduction.tex +++ b/doc/context/sources/general/manuals/luametatex/luametatex-introduction.tex @@ -28,43 +28,60 @@ happened in a series of documents, parts of which were published as articles in user group journals, but all are in the \CONTEXT\ distribution. I did the same with the development of \LUAMETATEX. -The \LUAMETATEX\ engine is, as said, a lightweight version of \LUATEX, that for -now targets \CONTEXT. We will use it for possibly drastic experiments but without -affecting \LUATEX. As we can easily adapt \CONTEXT\ to support both, no other -macro package will be harmed when (for instance) interfaces change as part of an -experiment. Of course, when we consider something to be useful, it can be ported -back to \LUATEX, but only when there are good reasons for doing so and when no -compatibility issues are involved. When considering this follow up one -consideration was that a lean and mean version with an extension mechanism is a -bit closer to original \TEX. Of course, because we also have new primitives, this -is not entirely true. The move to \LUA\ already meant that some aspects, -especially system dependent ones, no longer made sense and therefore had -consequences for the interface at the system level. - -This manual currently has quite a bit of overlap with the \LUATEX\ manual but -some chapters are removed, others added and the rest has been (and will be -further) adapted. It also discusses the (main) differences. Some of the new -primitives or functions that show up in \LUAMETATEX\ might show up in \LUATEX\ at -some point, others might not, so don't take this manual as reference for \LUATEX -! For now it is an experimental engine in which we can change things at will but -with \CONTEXT\ in tandem so that this macro package will keep working. Often you -can find examples of usage in \CONTEXT\ related documents and the source code. - -For \CONTEXT\ users the \LUAMETATEX\ engine will become the default. The -\CONTEXT\ variant for this engine is tagged \LMTX. The pair can be used in -production, just as with \LUATEX\ and \MKIV. In fact, most users will probably -not really notice the difference. In some cases there will be a drop in +The \LUAMETATEX\ engine is, as said, a follow up on \LUATEX. Just as we have +\CONTEXT\ \MKII\ for \PDFTEX\ and \XETEX, we have \MKIV\ for \LUATEX. For +\LUAMETATEX\ we have yet another version of \CONTEXT: \LMTX. By freezing \MKII, +and at soem point freezing \MKIV, we can move on as we like, but we try to remain +downward compatible where possible, something that the user interface makes +possible. Although \LUAMETATEX\ can be used for production we can also use it for +possibly drastic experiments but without affecting \LUATEX. Because we can easily +adapt \CONTEXT\ to support both, no other macro package will be harmed when (for +instance) the interface that the engine provides change as part of an experiment +or cleanup of code. Of course, when we consider something to be useful, it can be +ported back to \LUATEX, but only when there are good reasons for doing so and +when no compatibility issues are involved. + +By now the code of these two related engines differs a lot so in retrospect it +makes less sense to waste time on backporting anyway. When considering this +follow up one consideration was that a lean and mean version with an extension +mechanism is a bit closer to original \TEX. Of course, because we also have new +primitives, this is not entirely true. The basic algorithms remain the same but +code got reshuffled and because we expose internals names of variables and such +are sometimes changed, something that is noticeable in the token and node +interfaces. Delegating tasks to \LUA\ already meant that some aspects, especially +system dependent ones, no longer made sense and therefore had consequences for +the interface at the system level. In \LUAMETATEX\ more got delegated, like all +file related operations. The penalty of moving more responsibility to \LUA\ has +been compensated by (hopefully) harmless optimization of code in the engine and +some more core functionality. + +This manual started as an adaptation of the \LUATEX\ manual and therefore looks +similar. Some chapters are removed, others were added and the rest has been (and +will be further) adapted. It also discusses the (main) differences. Some of the +new primitives or functions that show up in \LUAMETATEX\ might show up in +\LUATEX\ at some point, but most will be exclusive to \LUAMETATEX, so don't take +this manual as reference for \LUATEX ! As long as we're experimenting we can +change things at will but as we keep \CONTEXT\ \LMTX\ synchronized users normally +won't notice this. Often you can find examples of usage in \CONTEXT\ related +documents and the source code so that serves a reference too. + +For \CONTEXT\ users the \LUAMETATEX\ engine will become the default. As +mentioned, the \CONTEXT\ variant for this engine is tagged \LMTX. The pair can be +used in production, just as with \LUATEX\ and \MKIV. In fact, most users will +probably not really notice the difference. In some cases there will be a drop in performance, due to more work being delegated to \LUA, but on the average performance will be better, also due to some changes below the hood of the -engine. Memory consumption is also less. +engine. Memory consumption is also less. The timeline of development is roughly: +from 2018 upto 2020 engine development, 2019 upto 2021 the stepwise code split +between \MKIV\ and \LMTX, while in 2020 we will (mostly) freeze \MKIV\ and \LMTX\ +will be the default. As this follow up is closely related to \CONTEXT\ development, and because we expect stock \LUATEX\ to be used outside the \CONTEXT\ proper, there will be no special mailing list nor coverage (or pollution) on the \LUATEX\ related mailing lists. We have the \CONTEXT\ mailing lists for that. In due time the source code -will be part of the regular \CONTEXT\ distribution. - -% \testpage[8] +will be part of the regular \CONTEXT\ distribution so that is then also the +reference implementation: if needed users can compile the binary themselves. This manual sometimes refers to \LUATEX, especially when we talk of features common to both engine, as well as to \LUAMETATEX, when it is more specific to the @@ -113,15 +130,17 @@ progress all around. {\bf remark:} When there are non|-|intrusive features that also make sense in \LUATEX, these will be applied in the experimental branch first, so that there is -no interference with the stable release. +no interference with the stable release. However, given that in the meantime the +code bases differs a lot, it is unlikely that much will trickle back. This is no +real problem as there's not much demand for that anyway. {\bf remark:} Most \CONTEXT\ users seem always willing to keep up with the latest versions which means that \LMTX\ is tested well. We can therefore safely claim that end of 2019 the code has become quite stable. There are no complaints about -performance (on my laptop this manual compiles at 22.5 pps with \LMTX\ versus -20.7 pps for the \LUATEX\ manual with \MKIV). Probably no one notices it, but -memory consumption stepwise got reduced too. And \unknown\ the binary is still -below 3~MegaBytes on all platforms. +performance (on my 2013 laptop this manual compiles at 24.5 pps with \LMTX\ +versus 20.7 pps for the \LUATEX\ manual with \MKIV). Probably no one notices it, +but memory consumption stepwise got reduced too. And \unknown\ the binary is +still below 3~MegaBytes on all platforms. \stopchapter diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-languages.tex b/doc/context/sources/general/manuals/luametatex/luametatex-languages.tex index 85701bdc3..d767bb5ae 100644 --- a/doc/context/sources/general/manuals/luametatex/luametatex-languages.tex +++ b/doc/context/sources/general/manuals/luametatex/luametatex-languages.tex @@ -190,7 +190,7 @@ kerning steps. The start and end of a sequence of characters is signalled by a \nod {glue}, \nod {penalty}, \nod {kern} or \nod {boundary} node. But by default also a \nod -{hlist}, \nod {vlist}, \nod {rule}, \nod {dir}, \nod {whatsit}, \nod {ins}, and +{hlist}, \nod {vlist}, \nod {rule}, \nod {dir}, \nod {whatsit}, \nod {insert}, and \nod {adjust} node indicate a start or end. You can omit the last set from the test by setting flags in \lpr {hyphenationmode}: @@ -507,7 +507,7 @@ In the last line of the table, you see there is no \prm {discretionary} command in the value: the command is optional in the \TEX-based input syntax. The underlying reason for that is that it is conceivable that a whole dictionary of words is stored as a plain text file and loaded into \LUATEX\ using one of the -functions in the \LUA\ \type {lang} library. This loading method is quite a bit +functions in the \LUA\ \type {language} library. This loading method is quite a bit faster than going through the \TEX\ language primitives, but some (most?) of that speed gain would be lost if it had to interpret command sequences while doing so. @@ -598,7 +598,7 @@ of the implementation: \startitem Because there is no \quote {trie preparation} stage, language patterns never become frozen. This means that the primitive \prm {patterns} (and its \LUA\ - counterpart \type {lang.patterns}) can be used at any time, not only in + counterpart \type {language.patterns}) can be used at any time, not only in ini\TEX. \stopitem \startitem @@ -622,7 +622,7 @@ of the implementation: permits a local overload for explicit \prm {discretionary} commands. The value current when the hyphenation pass is applied is used. When no callbacks are used this is compatible with traditional \TEX. When you apply the \LUA\ - \type {lang.hyphenate} function the current values are used. + \type {language.hyphenate} function the current values are used. \stopitem \startitem The hyphenation exception dictionary is maintained as key|-|value hash, and @@ -668,7 +668,7 @@ eventually either the limitation will be removed or perhaps it will become possible to silently ignore the excess characters (this is what happens in \TEX82, but there the behaviour cannot be controlled). -If you are using the \LUA\ function \type {lang.hyphenate}, you should be aware +If you are using the \LUA\ function \type {language.hyphenate}, you should be aware that this function expects to receive a list of \quote {character} nodes. It will not operate properly in the presence of \quote {glyph}, \quote {ligature}, or \quote {ghost} nodes, nor does it know how to deal with kerning. @@ -844,7 +844,7 @@ ligatures are used. Of course kerning also complicates matters here. \stopsection -\startsection[title={The \type {lang} library}][library=lang] +\startsection[title={The \type {language} library}][library=lang] \subsection {\type {new} and \type {id}} @@ -857,34 +857,38 @@ This library provides the interface to \LUATEX's structure representing a language, and the associated functions. \startfunctioncall -<language> l = lang.new() -<language> l = lang.new(<number> id) +<language> l = language.new() +<language> l = language.new(<number> id) \stopfunctioncall This function creates a new userdata object. An object of type \type {<language>} -is the first argument to most of the other functions in the \type {lang} library. -These functions can also be used as if they were object methods, using the colon -syntax. Without an argument, the next available internal id number will be -assigned to this object. With argument, an object will be created that links to -the internal language with that id number. +is the first argument to most of the other functions in the \type {language} +library. These functions can also be used as if they were object methods, using +the colon syntax. Without an argument, the next available internal id number will +be assigned to this object. With argument, an object will be created that links +to the internal language with that id number. \startfunctioncall -<number> n = lang.id(<language> l) +<number> n = language.id(<language> l) \stopfunctioncall -The number returned is the internal \prm {language} id number this object refers to. +The number returned is the internal \prm {language} id number this object refers +to. \subsection {\type {hyphenation}} \libindex {hyphenation} -You can hyphenate a string directly with: +You can load exceptions with: \startfunctioncall -<string> n = lang.hyphenation(<language> l) -lang.hyphenation(<language> l, <string> n) +<string> n = language.hyphenation(<language> l) +language.hyphenation(<language> l, <string> n) \stopfunctioncall +When no string is given (the first example) a string with all exceptions is +returned. + \subsection {\type {clear_hyphenation} and \type {clean}} \libindex {clear_hyphenation} @@ -895,14 +899,14 @@ new ones. The syntax of the string is explained in~\in {section} [patternsexceptions]. \startfunctioncall -lang.clear_hyphenation(<language> l) +language.clear_hyphenation(<language> l) \stopfunctioncall This call clears the exception dictionary (string) for this language. \startfunctioncall -<string> n = lang.clean(<language> l, <string> o) -<string> n = lang.clean(<string> o) +<string> n = language.clean(<language> l, <string> o) +<string> n = language.clean(<string> o) \stopfunctioncall This function creates a hyphenation key from the supplied hyphenation value. The @@ -916,8 +920,8 @@ dictionary file, like spell|-|checking. \libindex {clear_patterns} \startfunctioncall -<string> n = lang.patterns(<language> l) -lang.patterns(<language> l, <string> n) +<string> n = language.patterns(<language> l) +language.patterns(<language> l, <string> n) \stopfunctioncall This adds additional patterns for this language object, or returns the current @@ -925,7 +929,7 @@ set. The syntax of this string is explained in \in {section} [patternsexceptions]. \startfunctioncall -lang.clear_patterns(<language> l) +language.clear_patterns(<language> l) \stopfunctioncall This can be used to clear the pattern dictionary for a language. @@ -938,8 +942,8 @@ This function sets (or gets) the value of the \TEX\ parameter \type {\hyphenationmin}. \startfunctioncall -n = lang.hyphenationmin(<language> l) -lang.hyphenationmin(<language> l, <number> n) +n = language.hyphenationmin(<language> l) +language.hyphenationmin(<language> l, <number> n) \stopfunctioncall \subsection {\type {[pre|post][ex|]hyphenchar}} @@ -950,11 +954,11 @@ lang.hyphenationmin(<language> l, <number> n) \libindex {postexhyphenchar} \startfunctioncall -<number> n = lang.prehyphenchar(<language> l) -lang.prehyphenchar(<language> l, <number> n) +<number> n = language.prehyphenchar(<language> l) +language.prehyphenchar(<language> l, <number> n) -<number> n = lang.posthyphenchar(<language> l) -lang.posthyphenchar(<language> l, <number> n) +<number> n = language.posthyphenchar(<language> l) +language.posthyphenchar(<language> l, <number> n) \stopfunctioncall These two are used to get or set the \quote {pre|-|break} and \quote @@ -962,11 +966,11 @@ These two are used to get or set the \quote {pre|-|break} and \quote intial values are decimal 45 (hyphen) and decimal~0 (indicating emptiness). \startfunctioncall -<number> n = lang.preexhyphenchar(<language> l) -lang.preexhyphenchar(<language> l, <number> n) +<number> n = language.preexhyphenchar(<language> l) +language.preexhyphenchar(<language> l, <number> n) -<number> n = lang.postexhyphenchar(<language> l) -lang.postexhyphenchar(<language> l, <number> n) +<number> n = language.postexhyphenchar(<language> l) +language.postexhyphenchar(<language> l, <number> n) \stopfunctioncall These gets or set the \quote {pre|-|break} and \quote {post|-|break} hyphen @@ -983,8 +987,8 @@ The next call inserts hyphenation points (discretionary nodes) in a node list. I are proper nodes, regardless of possible other errors. \startfunctioncall -<boolean> success = lang.hyphenate(<node> head) -<boolean> success = lang.hyphenate(<node> head, <node> tail) +<boolean> success = language.hyphenate(<node> head) +<boolean> success = language.hyphenate(<node> head, <node> tail) \stopfunctioncall Hyphenation works only on \quote {characters}, a special subtype of all the glyph @@ -1000,8 +1004,8 @@ more details. The following two commands can be used to set or query hj codes: \startfunctioncall -lang.sethjcode(<language> l, <number> char, <number> usedchar) -<number> usedchar = lang.gethjcode(<language> l, <number> char) +language.sethjcode(<language> l, <number> char, <number> usedchar) +<number> usedchar = language.gethjcode(<language> l, <number> char) \stopfunctioncall When you set a hjcode the current sets get initialized unless the set was already diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-modifications.tex b/doc/context/sources/general/manuals/luametatex/luametatex-modifications.tex index 9827884ad..ff401a1ba 100644 --- a/doc/context/sources/general/manuals/luametatex/luametatex-modifications.tex +++ b/doc/context/sources/general/manuals/luametatex/luametatex-modifications.tex @@ -257,12 +257,7 @@ don't expect \LUAMETATEX\ to be compatible. \startitem When \lpr {adjustspacing} has value~2, hz optimization will be applied to glyphs and kerns. When the value is~3, only glyphs will be treated. A value - smaller than~2 disables this feature. With value of~1, font expansion is - applied after \TEX's normal paragraph breaking routines have broken the - paragraph into lines. In this case, line breaks are identical to standard - \TEX\ behavior (as with \PDFTEX). But \unknown\ this is a left|-|over from - the early days of \PDFTEX\ when this feature was part of a research topic. At - some point level~1 might be dropped from \LUAMETATEX. + smaller than~2 disables this feature. \stopitem \startitem diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-nodes.tex b/doc/context/sources/general/manuals/luametatex/luametatex-nodes.tex index 0d0218ed9..d56d85ceb 100644 --- a/doc/context/sources/general/manuals/luametatex/luametatex-nodes.tex +++ b/doc/context/sources/general/manuals/luametatex/luametatex-nodes.tex @@ -174,12 +174,12 @@ discussed here (yet). \stopsubsection -\startsubsection[title={\nod {ins} nodes}] +\startsubsection[title={\nod {insert} nodes}] \topicindex {nodes+insertions} \topicindex {insertions} -This node relates to the \prm {insert} primitive and support the fields: \showfields{ins}. +This node relates to the \prm {insert} primitive and support the fields: \showfields{insert}. \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR @@ -455,7 +455,7 @@ fields: \showfields {glyph}. \NC \type{attr} \NC node \NC list of attributes \NC \NR \NC \type{char} \NC number \NC the character index in the font \NC \NR \NC \type{font} \NC number \NC the font identifier \NC \NR -\NC \type{lang} \NC number \NC the language identifier \NC \NR +\NC \type{language} \NC number \NC the language identifier \NC \NR \NC \type{left} \NC number \NC the frozen \type {\lefthyphenmnin} value \NC \NR \NC \type{right} \NC number \NC the frozen \type {\righthyphenmnin} value \NC \NR \NC \type{uchyph} \NC boolean \NC the frozen \prm {uchyph} value \NC \NR @@ -527,13 +527,13 @@ nodes: \showfields {boundary} are the only fields. \stopsubsection -\startsubsection[title={\nod {local_par} nodes}] +\startsubsection[title={\nod {par} nodes}] \topicindex {nodes+paragraphs} \topicindex {paragraphs} This node is inserted at the start of a paragraph. You should not mess -too much with this one. Valid fields are: \showfields {local_par}. +too much with this one. Valid fields are: \showfields {par}. \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR @@ -613,7 +613,7 @@ into a single node type with separate subtypes for differentiation: \showfields Many object fields in math mode are either simple characters in a specific family or math lists or node lists: \type {math_char}, \type {math_text_char}, {sub_box} -and \type {sub_mlist} and \type {delim}. These are endpoints and therefore the +and \type {sub_mlist} and \type {delimiter}. These are endpoints and therefore the \type {next} and \type {prev} fields of these these subnodes are unused. Some of the more elaborate noads have an option field. The values in this bitset @@ -681,11 +681,11 @@ its internal link structure is correct, otherwise an error is triggered. \stopsubsubsection -\startsubsubsection[title={\nod {delim} subnodes}] +\startsubsubsection[title={\nod {delimiter} subnodes}] There is a fifth subnode type that is used exclusively for delimiter fields. As before, the \type {next} and \type {prev} fields are unused, but we do have: -\showfields {delim}. +\showfields {delimiter}. \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR @@ -854,14 +854,14 @@ renderer and might get adapted in the process. \starttabulate[|l|l|p|] \DB field \BC type \BC explanation \NC \NR \TB -\NC \type{subtype} \NC number \NC \showsubtypes{fence} \NC \NR -\NC \type{attr} \NC node \NC list of attributes \NC \NR -\NC \type{delim} \NC delimiter node \NC delimiter specification \NC \NR -\NC \type{italic} \NC number \NC italic correction \NC \NR -\NC \type{height} \NC number \NC required height \NC \NR -\NC \type{depth} \NC number \NC required depth \NC \NR -\NC \type{options} \NC number \NC bitset of rendering options \NC \NR -\NC \type{class} \NC number \NC spacing related class \NC \NR +\NC \type{subtype} \NC number \NC \showsubtypes{fence} \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{delimiter} \NC delimiter node \NC delimiter specification \NC \NR +\NC \type{italic} \NC number \NC italic correction \NC \NR +\NC \type{height} \NC number \NC required height \NC \NR +\NC \type{depth} \NC number \NC required depth \NC \NR +\NC \type{options} \NC number \NC bitset of rendering options \NC \NR +\NC \type{class} \NC number \NC spacing related class \NC \NR \LL \stoptabulate diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-preamble.tex b/doc/context/sources/general/manuals/luametatex/luametatex-preamble.tex index 9a2fe5690..1897d0f3e 100644 --- a/doc/context/sources/general/manuals/luametatex/luametatex-preamble.tex +++ b/doc/context/sources/general/manuals/luametatex/luametatex-preamble.tex @@ -10,12 +10,12 @@ \topicindex{boxes} \topicindex{\LUA} -This is a reference manual, not a tutorial. This means that we discuss changes -relative to traditional \TEX\ and also present new functionality. As a -consequence we will refer to concepts that we assume to be known or that might be -explained later. Because the \LUATEX\ and \LUAMETATEX\ engines open up \TEX\ -there's suddenly quite some more to explain, especially about the way a (to be) -typeset stream moves through the machinery. However, discussing all that in +This is a reference manual and not a tutorial. This means that we discuss changes +relative to traditional \TEX\ and also present new (or extended) functionality. +As a consequence we will refer to concepts that we assume to be known or that +might be explained later. Because the \LUATEX\ and \LUAMETATEX\ engines open up +\TEX\ there's suddenly quite some more to explain, especially about the way a (to +be) typeset stream moves through the machinery. However, discussing all that in detail makes not much sense, because deep knowledge is only relevant for those who write code not possible with regular \TEX\ and who are already familiar with these internals (or willing to spend time on figuring it out). @@ -57,11 +57,11 @@ H <=> i <=> [glue] <=> T <=> h <=> e <=> r <=> e ... \stoptyping When we have a paragraph, we actually get something like this, where a \type -{localpar} node stores some metadata and is followed by a \type {hlist} flagged -as indent box: +{par} node stores some metadata and is followed by a \type {hlist} flagged as +indent box: \starttyping -[localpar] <=> [hlist] <=> H <=> i <=> [glue] <=> T <=> h <=> e <=> r <=> e ... +[par] <=> [hlist] <=> H <=> i <=> [glue] <=> T <=> h <=> e <=> r <=> e ... \stoptyping Each character becomes a so called glyph node, a record with properties like the @@ -71,14 +71,14 @@ back to a previous node or next node, given that these exist. Sometimes multiple characters are represented by one glyphs, so one can also get: \starttyping -[localpar] <=> [hlist] <=> H <=> i <=> [glue] <=> Th <=> e <=> r <=> e ... +[par] <=> [hlist] <=> H <=> i <=> [glue] <=> Th <=> e <=> r <=> e ... \stoptyping And maybe some characters get positioned relative to each other, so we might see: \starttyping -[localpar] <=> [hlist] <=> H <=> [kern] <=> i <=> [glue] <=> Th <=> e <=> r <=> e ... +[par] <=> [hlist] <=> H <=> [kern] <=> i <=> [glue] <=> Th <=> e <=> r <=> e ... \stoptyping It's also good to know beforehand that \TEX\ is basically centered around @@ -131,6 +131,12 @@ what commands relate to them. Here are a few: \LL \stoptabulate +Whatever we feed into \TEX\ at some point becomes a token which is either +interpreted directly or stored in a linked list. A token is just a number that +encodes a specific command (operator) and some value (operand) that further +specifies what that command is supposed to do. In addition to an interface to +nodes, there is an interface to tokens, as later chapters will demonstrate. + Text (interspersed with macros) comes from an input medium. This can be a file, token list, macro body cq.\ arguments, \ some internal quantity (like a number), \LUA, etc. Macros get expanded. In the process \TEX\ can enter a group. Inside @@ -150,14 +156,14 @@ of the content is calculated and the box gets its width, height and depth. What happens with the box depends on what macros do with it. The other thing that can happen is that the text starts a new paragraph. In that -case some information is stored in a leading \type {localpar} node. Then -indentation is appended and the paragraph ends with some glue. Again the three -stages are applied but this time, afterwards, the long line is broken into lines -and the result is either added to the content of a box or to the main vertical -list (the running text so to say). This is called par building. At some point -\TEX\ decides that enough is enough and it will trigger the page builder. So, -building is another concept we will encounter. Another example of a builder is -the one that turns an intermediate math list into something typeset. +case some information is stored in a leading \type {par} node. Then indentation +is appended and the paragraph ends with some glue. Again the three stages are +applied but this time, afterwards, the long line is broken into lines and the +result is either added to the content of a box or to the main vertical list (the +running text so to say). This is called par building. At some point \TEX\ decides +that enough is enough and it will trigger the page builder. So, building is +another concept we will encounter. Another example of a builder is the one that +turns an intermediate math list into something typeset. Wrapping something in a box is called packing. Adding something to a list is described in terms of contributing. The more complicated processes are wrapped diff --git a/doc/context/sources/general/manuals/luametatex/luametatex-tex.tex b/doc/context/sources/general/manuals/luametatex/luametatex-tex.tex index 28cf20840..5aaa73cec 100644 --- a/doc/context/sources/general/manuals/luametatex/luametatex-tex.tex +++ b/doc/context/sources/general/manuals/luametatex/luametatex-tex.tex @@ -1077,7 +1077,7 @@ keep track of building page lists. \DB field \BC explanation \NC \NR \TB \NC \type{page_ins_head} \NC circular list of pending insertions \NC \NR -\NC \type{contrib_head} \NC the recent contributions \NC \NR +\NC \type{contribute_head} \NC the recent contributions \NC \NR \NC \type{page_head} \NC the current page content \NC \NR %NC \type{temp_head} \NC \NC \NR \NC \type{hold_head} \NC used for held-over items for next page \NC \NR @@ -1136,7 +1136,7 @@ The known fields are: \NC \type{prevgraf} \NC number \NC vmode \NC number of lines in the previous paragraph \NC \NR \NC \type{prevdepth} \NC number \NC vmode \NC depth of the previous paragraph \NC \NR \NC \type{spacefactor} \NC number \NC hmode \NC the current space factor \NC \NR -\NC \type{dirs} \NC node \NC hmode \NC used for temporary storage by the line break algorithm\NC \NR +\NC \type{direction} \NC node \NC hmode \NC stack used for temporary storage by the line break algorithm \NC \NR \NC \type{noad} \NC node \NC mmode \NC used for temporary storage of a pending fraction numerator, for \prm {over} etc. \NC \NR \NC \type{delimptr} \NC node \NC mmode \NC used for temporary storage of the previous math delimiter, @@ -1798,7 +1798,7 @@ horizontal mode): \startitemize \startitem - add an \quote {indent box} and perhaps a \nod {local_par} node at the start + add an \quote {indent box} and perhaps a \nod {par} node at the start (only if you need them) \stopitem \startitem @@ -1986,8 +1986,8 @@ texio.write(<string> s, ...) Without the \type {target} argument, writes all given strings to the same location(s) \TEX\ writes messages to at this moment. If \prm {batchmode} is in effect, it writes only to the log, otherwise it writes to the log and the -terminal. The optional \type {target} can be one of three possibilities: \type -{term}, \type {log} or \type {term and log}. +terminal. The optional \type {target} can be one of \type {terminal}, +\type {logfile} or \type {terminal_and_logfile}. Note: If several strings are given, and if the first of these strings is or might be one of the targets above, the \type {target} must be specified explicitly to diff --git a/doc/context/sources/general/manuals/luametatex/luametatex.tex b/doc/context/sources/general/manuals/luametatex/luametatex.tex index debfdb358..99cd6cfa5 100644 --- a/doc/context/sources/general/manuals/luametatex/luametatex.tex +++ b/doc/context/sources/general/manuals/luametatex/luametatex.tex @@ -9,6 +9,12 @@ % mswin 2562k 2555k mswin 2481k 2471k % ------------------------ ------------------------ +% \loggingall +% \tracingonline \zerocount +% \tracingmacros \plusone + +% \enabletexdirective{vspacing.experimental} + % \nopdfcompression % 20200509 : 258 pages |