Source Browser ?

1% language=us runpath=texruns:manuals/luametatex
2
3% run locally!
4% \enablemode[checktodo]
5
6\environment luametatex-style
7
8% \tracepositions
9
10
11% The usual time stamp. This written while listening intermized to Fish (just ran
12% into), Lazulli (some yt videos too, looking forward to a next live act) and
13% because this all is boring checking out Sarah Coopers channel for new DT syncs
14% every few hours. (Picking up writing this manual in 2023 makes me realize how
15% time flies.)
16%
17% And now it's 2024, so time for a new time (musical) stamp when adding a few
18% more descriptions after watching Tyler Visser perform Fear Inoculum in one take
19% (think Pneuma): great to discover this in a time of artificial music popping up:
20% an amazing drum only version; there is also an older equally amazing version.
21
22% When you feel unhappy about the lack of detail in this manual, just keep in mind
23% that you cannot really demand anything from volunteers: just hope for more (or
24% pay for it). Friendly comments and corrections are of course always welcome. As
25% we like what we're doing here, it all might eventually evolve to perfection, stay
26% tuned.
27%
28% Hans Hagen | j.hagen @ xs4all . nl | ntg-context @ ntg . nl
29
30% iflastnamedcs
31% ignorerest
32
33% boxinserts bitset return codes
34% boxmigrate bitset return codes
35
36% \enableexperiments[fonts.compact]
37
38% \string\Uabove               \quad:\quad\meaning\mathabove               \par
39% \string\Uabovewithdelims     \quad:\quad\meaning\mathabovewithdelims     \par
40% \string\Uatop                \quad:\quad\meaning\mathatop                \par
41% \string\Uatopwithdelims      \quad:\quad\meaning\mathatopwithdelims      \par
42% \string\Udelcode             \quad:\quad\meaning\mathdelcode             \par
43% \string\Udelimited           \quad:\quad\meaning\mathdelimited           \par
44% \string\Udelimiter           \quad:\quad\meaning\mathdelimiter           \par %
45% \string\Udelimiterover       \quad:\quad\meaning\mathdelimiterover       \par
46% \string\Udelimiterunder      \quad:\quad\meaning\mathdelimiterunder      \par
47% \string\Uhextensible         \quad:\quad\meaning\mathhextensible         \par
48% \string\Uleft                \quad:\quad\meaning\mathleft                \par
49% \string\Umiddle              \quad:\quad\meaning\mathmiddle              \par %
50% \string\Uoperator            \quad:\quad\meaning\mathoperator            \par %
51% \string\Uover                \quad:\quad\meaning\mathover                \par %
52% \string\Uoverdelimiter       \quad:\quad\meaning\mathoverdelimiter       \par
53% \string\Uoverwithdelims      \quad:\quad\meaning\mathoverwithdelims      \par
54% \string\Uradical             \quad:\quad\meaning\mathradical             \par %
55% \string\Uright               \quad:\quad\meaning\mathright               \par
56% \string\Uroot                \quad:\quad\meaning\mathroot                \par
57% \string\Urooted              \quad:\quad\meaning\mathrooted              \par
58% \string\Uskewed              \quad:\quad\meaning\mathskewed              \par
59% \string\Uskewedwithdelims    \quad:\quad\meaning\mathskewedwithdelims    \par
60% \string\Ustartdisplaymath    \quad:\quad\meaning\mathstartdisplaymath    \par
61% \string\Ustartmath           \quad:\quad\meaning\mathstartmath           \par
62% \string\Ustartmathmode       \quad:\quad\meaning\mathstartmathmode       \par
63% \string\Ustopdisplaymath     \quad:\quad\meaning\mathstopdisplaymath     \par
64% \string\Ustopmath            \quad:\quad\meaning\mathstopmath            \par
65% \string\Ustopmathmode        \quad:\quad\meaning\mathstopmathmode        \par
66% \string\Ustretched           \quad:\quad\meaning\mathstretched           \par
67% \string\Ustretchedwithdelims \quad:\quad\meaning\mathstretchedwithdelims \par
68% \string\Uunderdelimiter      \quad:\quad\meaning\mathunderdelimiter      \par
69% \string\Uvextensible         \quad:\quad\meaning\mathvextensible         \par
70
71% Umathaccent
72% Umathchar
73% Umathchardef
74
75% Umathnolimitsubfactor
76% Umathnolimitsupfactor
77% Umathoverbarkern
78% Umathoverbarrule
79% Umathoverbarvgap
80% Umathoverlinevariant
81% Umathspaceafterscript
82% Umathspacebeforescript
83% Umathspacebetweenscript
84% Umathunderbarkern
85% Umathunderbarrule
86% Umathunderbarvgap
87% Umathunderlinevariant
88
89\startdocument[title=Primitives]
90
91\pushoverloadmode
92
93\doifmode{checktodo}{\startbodymatter}
94
95\startsection[title={Introduction}]
96
97Here I will discuss some of the new primitives in \LUATEX\ and \LUAMETATEX, the
98later being a successor that permits the \CONTEXT\ folks to experiment with new
99features. The order is arbitrary. When you compare \LUATEX\ with \PDFTEX, there
100are actually quite some differences. Some primitives that \PDFTEX\ introduced
101have been dropped in \LUATEX\ because they can be done better in \LUA. Others
102have been promoted to core primitives that no longer have a \type {pdf} prefix.
103Then there are lots of new primitives, some introduce new concepts, some are a
104side effect of for instance new math font technologies, and then there are those
105that are handy extensions to the macro language. The \LUAMETATEX\ engine drops
106quite some primitives, like those related to \PDFTEX\ specific f(r)ont or backend
107features. It also adds some new primitives, mostly concerning the macro language.
108
109We also discuss the primitives that fit into the macro programming scope that are
110present in traditional \TEX\ and \ETEX\ but there are for sure better of
111explanations out there already. Primitives that relate to typesetting, like those
112controlling math, fonts, boxes, attributes, directions, catcodes, \LUA\
113(functions) etc are not discussed or discussed in less detail here.
114
115There are for instance primitives to create aliases to low level registers like
116counters and dimensions, as well as other (semi|-|numeric) quantities like
117characters, but normally these are wrapped into high level macros so that
118definitions can't clash too much. Numbers, dimensions etc can be advanced,
119multiplied and divided and there is a simple expression mechanism to deal with
120them. We don't go into these details here: it's mostly an overview of what the
121engine provides. If you are new to \TEX, you need to play a while with its mixed
122bag of typesetting and programming features in order to understand the difference
123between this macro language and other languages you might be familiar with.
124
125% \starttworows \hsize.5\textwidth
126\startcolumns
127    \placelist
128      [newprimitive,oldprimitive]
129      [alternative=c,criterium=text]
130\stopcolumns
131
132In this document the section titles that discuss the \color [nonecolor] {original
133\TEX\ and \ETEX\ primitives} have a different color those explaining the \color
134[primcolor] {\LUATEX\ and \LUAMETATEX\ primitives}.
135
136Primitives that extend typesetting related functionality, provide control over
137subsystems (like math), allocate additional data types and resources, deal with
138fonts and languages, manipulate boxes and glyphs, etc.\ are hardly discussed
139here, only mentioned. Math for instance is a topic of its own. In this document
140we concentrate on the programming aspects.
141
142Most of the new primitives are discussed in specific manuals and often also
143original primitives are covered there but the best explanations of the
144traditional primitives can be found in The \TEX book by Donald Knuth and \TEX\ by
145Topic from Victor Eijkhout. I see no need to try to improve on those.
146
147% {\em Some new primitives in this list might be forgotten or already became
148% obsolete. Let me know if you run into one.}
149
150% How likely is it that an eight bit setup is used? Maybe we should at some point
151% just replace the old math primitives like \tex {above} replace by \tex
152% {Uabove}.
153
154\stopsection
155
156\startsection[title=Rationale] % ,placeholder=todo]
157
158Some words about the why and how it came. One of the early adopters of \CONTEXT\
159was Taco Hoekwater and we spent numerous trips to \TEX\ meetings all over the
160globe. He was also the only one I knew who had read the \TEX\ sources. Because
161\CONTEXT\ has always been on the edge of what is possible and at that time we
162both used it for rather advanced rendering, we also ran into the limitations. I'm
163not talking of \TEX\ features here. Naturally old school \TEX\ is not really
164geared for dealing with images of all kind, colors in all kind of color spaces,
165highly interactive documents, input methods like \XML, etc. The nice thing is
166that it offers some escapes, like specials and writes and later execution of
167programs that opened up lots of possibilities, so in practice there were no real
168limitations to what one could do. But coming up with a consistent and extensible
169(multi lingual) user interface was non trivial, because it had an impact in
170memory usage and performance. A lot could be done given some programming, as
171\CONTEXT\ \MKII\ proves, but it was not always pretty under the hood. The move to
172\LUATEX\ and \MKIV\ transferred some action to \LUA, and because \LUATEX\
173effectively was a \CONTEXT\ related project, we could easily keep them in sync.
174
175Our traveling together, meeting several times per year, and eventually email and
176intense \LUATEX\ developments (lots of Skype sessions) for a couple of years,
177gave us enough opportunity to discuss all kind of nice features not present in
178the engine. The previous century we discussed lots of them, rejected some, stayed
179with others, and I admit that forgot about most of the arguments already. Some
180that we did was already explored in \type {eetex}, some of those ended up in
181\LUATEX, and eventually what we have in \LUAMETATEX\ can been seen as the result
182of years of programming in \TEX, improving macros, getting more performance and
183efficiency out of existing \CONTEXT\ code and inspiration that we got out of the
184\CONTEXT\ community, a demanding lot, always willing to experiment with us.
185
186Once I decided to work on \LUAMETATEX\ and bind its source to the \CONTEXT\
187distribution so that we can be sure that it won't get messed up and might
188interfere with the \CONTEXT\ expectations, some more primitives saw their way
189into it. It is very easy to come up with all kind of bells and whistles but it is
190equally easy to hurt performance of an engine and what might go unnoticed in
191simple tests can really affect a macro package that depends on stability. So, what
192I did was mostly looking at the \CONTEXT\ code and wondering how to make some of
193the low level macros look more natural, also because I know that there are users
194who look into these sources. We spend a lot of time making them look consistent
195and nice and the nicer the better. Getting a better performance was seldom an
196argument because much is already as fast as can be so there is not that much to
197gain, but less clutter in tracing was an argument for some new primitives. Also,
198the fact that we soon might need to fall back on our phones to use \TEX\ a
199smaller memory footprint and less byte shuffling also was a consideration. The
200\LUAMETATEX\ memory footprint is somewhat smaller than the \LUATEX\ footprint.
201By binding \LUAMETATEX\ to \CONTEXT\ we can also guarantee that the combinations
202works as expected.
203
204I'm aware of the fact that \CONTEXT\ is in a somewhat unique position. First of
205all it has always been kind of cutting edge so its users are willing to
206experiment. There are users who immediately update and run tests, so bugs can and
207will be fixed fast. Already for a long time the community has an convenient
208infrastructure for updating and the build farm for generating binaries (also for
209other engines) is running smoothly.
210
211Then there is the \CONTEXT\ user interface that is quite consistent and permits
212extensions with staying backward compatible. Sometimes users run into old manuals
213or examples and then complain that \CONTEXT\ is not compatible but that then
214involves obsolete technology: we no longer need font and input encodings and font
215definitions are different for \OPENTYPE\ fonts. We always had an abstract backend
216model, but nowadays \PDF\ is kind of dominant and drives a lot of expectations.
217So, some of the \MKII\ commands are gone and \MKIV\ has some more. Also, as
218\METAPOST\ evolved that department in \CONTEXT\ also evolved. Think of it like
219cars: soon all are electric so one cannot expect a hole to poor in some fluid but
220gets a (often incompatible) plug instead. And buttons became touch panels. There
221is no need to use much force to steer or brake. Navigation is different, as are
222many controls. And do we need to steer ourselves a decade from now?
223
224So, just look at \TEX\ and \CONTEXT\ in the same way. A system from the nineties
225in the previous century differs from one three decades later. Demands differ,
226input differs, resources change, editing and processing moves on, and so on.
227Manuals, although still being written are seldom read from cover to cover because
228online searching replaced them. And who buys books about programming? So
229\LUAMETATEX, while still being \TEX\ also moves on, as do the way we do our low
230level coding. This makes sense because the original \TEX\ ecosystem was not made
231with a huge and complex macro package in mind, that just happened. An author was
232supposed to make a style for each document. An often used argument for using
233another macro package over \CONTEXT\ was that the later evolved and other macro
234packages would work the same forever and not change from the perspective of the
235user. In retrospect those arguments were somewhat strange because the world,
236computers, users etc.\ do change. Standards come and go, as do software politics
237and preferences. In many aspects the \TEX\ community is not different from other
238large software projects, operating system wars, library devotees, programming
239language addicts, paradigm shifts. But, don't worry, if you don't like
240\LUAMETATEX\ and its new primitives, just forget about them. The other engines
241will be there forever and are a safe bet, although \LUATEX\ already stirred up
242the pot I guess. But keep in mind that new features in the latest greatest
243\CONTEXT\ version will more and more rely on \LUAMETATEX\ being used; after all
244that is where it's made for. And this manual might help understand its users why,
245where and how the low level code differs between \MKII, \MKIV\ and \LMTX.
246
247Can we expect more new primitives than the ones introduced here? Given the amount
248of time I spent on experimenting and considering what made sense and what not,
249the answer probably is \quotation {no}, or at least \quotation {not that much}.
250As in the past no user ever requested the kind of primitives that were added, I
251don't expect users to come up with requests in the future either. Of course,
252those more closely related to \CONTEXT\ development look at it from the other
253end. Because it's there where the low level action really is, demands might still
254evolve.
255
256Basically there are wo areas where the engine can evolve: the programming part
257and the rendering. In this manual we focus on the programming and writing the
258manual sort of influences how details get filled in. Rendering in more complex
259because there heuristics and usage plays a more dominant role. Good examples are
260the math, par and page builder. They were extended and features were added over
261time but improved rendering came later. Not all extensions are critical, some are
262there (and got added) in order to write more readable code but there is only so
263much one can do in that area. Occasionally a feature pops up that is a side
264effect of a challenge. No matter what gets added it might not affect complexity
265too much and definitely not impact performance significantly!
266
267\stopsection
268
269% When writing this manual I also decided to merge some of the condition related
270% code so that it dealt a bit more natural with the newer features. A usual side
271% effects if writing manuals.
272
273\startsection[title=Primitives]
274
275\startoldprimitive[title={\prm {<space>}}]
276
277This original \TEX\ primitive is equivalent to the more verbose \prm
278{explicitspace}.
279
280\stopoldprimitive
281
282\startoldprimitive[title={\prm {-}}]
283
284This original \TEX\ primitive is equivalent to the more verbose \prm
285{explicitdiscretionary}.
286
287\stopoldprimitive
288
289\startoldprimitive[title={\prm {/}}]
290
291This original \TEX\ primitive is equivalent to the more verbose \prm
292{explicititaliccorrection}.
293
294\stopoldprimitive
295
296% \startnewprimitive[title={\prm {Uabove}}]
297% \stopnewprimitive
298
299% \startnewprimitive[title={\prm {Uabovewithdelims}}]
300% \stopnewprimitive
301
302% \startnewprimitive[title={\prm {Uatop}}]
303% \stopnewprimitive
304
305% \startnewprimitive[title={\prm {Uatopwithdelims}}]
306% \stopnewprimitive
307
308% \startnewprimitive[title={\prm {Udelcode}}]
309% \stopnewprimitive
310
311% \startnewprimitive[title={\prm {Udelimited}}]
312% \stopnewprimitive
313
314% \startnewprimitive[title={\prm {Udelimiter}}]
315% \stopnewprimitive
316
317% \startnewprimitive[title={\prm {Udelimiterover}}]
318% \stopnewprimitive
319
320% \startnewprimitive[title={\prm {Udelimiterunder}}]
321% \stopnewprimitive
322
323% \startnewprimitive[title={\prm {Uhextensible}}]
324% \stopnewprimitive
325
326% \startnewprimitive[title={\prm {Uleft}}]
327% \stopnewprimitive
328
329% \startnewprimitive[title={\prm {Umathaccent}}]
330% \stopnewprimitive
331
332% \startnewprimitive[title={\prm {Umathaccentbasedepth}}]
333% \stopnewprimitive
334
335% \startnewprimitive[title={\prm {Umathaccentbaseheight}}]
336% \stopnewprimitive
337
338% \startnewprimitive[title={\prm {Umathaccentbottomovershoot}}]
339% \stopnewprimitive
340
341% \startnewprimitive[title={\prm {Umathaccentbottomshiftdown}}]
342% \stopnewprimitive
343
344% \startnewprimitive[title={\prm {Umathaccentextendmargin}}]
345% \stopnewprimitive
346
347% \startnewprimitive[title={\prm {Umathaccentsuperscriptdrop}}]
348% \stopnewprimitive
349
350% \startnewprimitive[title={\prm {Umathaccentsuperscriptpercent}}]
351% \stopnewprimitive
352
353% \startnewprimitive[title={\prm {Umathaccenttopovershoot}}]
354% \stopnewprimitive
355
356% \startnewprimitive[title={\prm {Umathaccenttopshiftup}}]
357% \stopnewprimitive
358
359% \startnewprimitive[title={\prm {Umathaccentvariant}}]
360% \stopnewprimitive
361
362% \startnewprimitive[title={\prm {Umathadapttoleft}}]
363% \stopnewprimitive
364
365% \startnewprimitive[title={\prm {Umathadapttoright}}]
366% \stopnewprimitive
367
368% \startnewprimitive[title={\prm {Umathaxis}}]
369% \stopnewprimitive
370
371% \startnewprimitive[title={\prm {Umathbottomaccentvariant}}]
372% \stopnewprimitive
373
374% \startnewprimitive[title={\prm {Umathchar}}]
375% \stopnewprimitive
376
377% \startnewprimitive[title={\prm {Umathchardef}}]
378% \stopnewprimitive
379
380% \startnewprimitive[title={\prm {Umathcode}}]
381% \stopnewprimitive
382
383% \startnewprimitive[title={\prm {Umathconnectoroverlapmin}}]
384% \stopnewprimitive
385
386% \startnewprimitive[title={\prm {Umathdegreevariant}}]
387% \stopnewprimitive
388
389% \startnewprimitive[title={\prm {Umathdelimiterextendmargin}}]
390% \stopnewprimitive
391
392% \startnewprimitive[title={\prm {Umathdelimiterovervariant}}]
393% \stopnewprimitive
394
395% \startnewprimitive[title={\prm {Umathdelimiterpercent}}]
396% \stopnewprimitive
397
398% \startnewprimitive[title={\prm {Umathdelimitershortfall}}]
399% \stopnewprimitive
400
401% \startnewprimitive[title={\prm {Umathdelimiterundervariant}}]
402% \stopnewprimitive
403
404% \startnewprimitive[title={\prm {Umathdenominatorvariant}}]
405% \stopnewprimitive
406
407% \startnewprimitive[title={\prm {Umathdictdef}}]
408% \stopnewprimitive
409
410% \startnewprimitive[title={\prm {Umathexheight}}]
411% \stopnewprimitive
412
413% \startnewprimitive[title={\prm {Umathextrasubpreshift}}]
414% \stopnewprimitive
415
416% \startnewprimitive[title={\prm {Umathextrasubprespace}}]
417% \stopnewprimitive
418
419% \startnewprimitive[title={\prm {Umathextrasubshift}}]
420% \stopnewprimitive
421
422% \startnewprimitive[title={\prm {Umathextrasubspace}}]
423% \stopnewprimitive
424
425% \startnewprimitive[title={\prm {Umathextrasuppreshift}}]
426% \stopnewprimitive
427
428% \startnewprimitive[title={\prm {Umathextrasupprespace}}]
429% \stopnewprimitive
430
431% \startnewprimitive[title={\prm {Umathextrasupshift}}]
432% \stopnewprimitive
433
434% \startnewprimitive[title={\prm {Umathextrasupspace}}]
435% \stopnewprimitive
436
437% \startnewprimitive[title={\prm {Umathflattenedaccentbasedepth}}]
438% \stopnewprimitive
439
440% \startnewprimitive[title={\prm {Umathflattenedaccentbaseheight}}]
441% \stopnewprimitive
442
443% \startnewprimitive[title={\prm {Umathflattenedaccentbottomshiftdown}}]
444% \stopnewprimitive
445
446% \startnewprimitive[title={\prm {Umathflattenedaccenttopshiftup}}]
447% \stopnewprimitive
448
449% \startnewprimitive[title={\prm {Umathfractiondelsize}}]
450% \stopnewprimitive
451
452% \startnewprimitive[title={\prm {Umathfractiondenomdown}}]
453% \stopnewprimitive
454
455% \startnewprimitive[title={\prm {Umathfractiondenomvgap}}]
456% \stopnewprimitive
457
458% \startnewprimitive[title={\prm {Umathfractionnumup}}]
459% \stopnewprimitive
460
461% \startnewprimitive[title={\prm {Umathfractionnumvgap}}]
462% \stopnewprimitive
463
464% \startnewprimitive[title={\prm {Umathfractionrule}}]
465% \stopnewprimitive
466
467% \startnewprimitive[title={\prm {Umathfractionvariant}}]
468% \stopnewprimitive
469
470% \startnewprimitive[title={\prm {Umathhextensiblevariant}}]
471% \stopnewprimitive
472
473% \startnewprimitive[title={\prm {Umathlimitabovebgap}}]
474% \stopnewprimitive
475
476% \startnewprimitive[title={\prm {Umathlimitabovekern}}]
477% \stopnewprimitive
478
479% \startnewprimitive[title={\prm {Umathlimitabovevgap}}]
480% \stopnewprimitive
481
482% \startnewprimitive[title={\prm {Umathlimitbelowbgap}}]
483% \stopnewprimitive
484
485% \startnewprimitive[title={\prm {Umathlimitbelowkern}}]
486% \stopnewprimitive
487
488% \startnewprimitive[title={\prm {Umathlimitbelowvgap}}]
489% \stopnewprimitive
490
491% \startnewprimitive[title={\prm {Umathlimits}}]
492% \stopnewprimitive
493
494% \startnewprimitive[title={\prm {Umathnoaxis}}]
495% \stopnewprimitive
496
497% \startnewprimitive[title={\prm {Umathnolimits}}]
498% \stopnewprimitive
499
500% \startnewprimitive[title={\prm {Umathnolimitsubfactor}}]
501% \stopnewprimitive
502
503% \startnewprimitive[title={\prm {Umathnolimitsupfactor}}]
504% \stopnewprimitive
505
506% \startnewprimitive[title={\prm {Umathnumeratorvariant}}]
507% \stopnewprimitive
508
509% \startnewprimitive[title={\prm {Umathopenupdepth}}]
510% \stopnewprimitive
511
512% \startnewprimitive[title={\prm {Umathopenupheight}}]
513% \stopnewprimitive
514
515% \startnewprimitive[title={\prm {Umathoperatorsize}}]
516% \stopnewprimitive
517
518% \startnewprimitive[title={\prm {Umathoverbarkern}}]
519% \stopnewprimitive
520
521% \startnewprimitive[title={\prm {Umathoverbarrule}}]
522% \stopnewprimitive
523
524% \startnewprimitive[title={\prm {Umathoverbarvgap}}]
525% \stopnewprimitive
526
527% \startnewprimitive[title={\prm {Umathoverdelimiterbgap}}]
528% \stopnewprimitive
529
530% \startnewprimitive[title={\prm {Umathoverdelimitervariant}}]
531% \stopnewprimitive
532
533% \startnewprimitive[title={\prm {Umathoverdelimitervgap}}]
534% \stopnewprimitive
535
536% \startnewprimitive[title={\prm {Umathoverlayaccentvariant}}]
537% \stopnewprimitive
538
539% \startnewprimitive[title={\prm {Umathoverlinevariant}}]
540% \stopnewprimitive
541
542% \startnewprimitive[title={\prm {Umathphantom}}]
543% \stopnewprimitive
544
545% \startnewprimitive[title={\prm {Umathprimeraise}}]
546% \stopnewprimitive
547
548% \startnewprimitive[title={\prm {Umathprimeraisecomposed}}]
549% \stopnewprimitive
550
551% \startnewprimitive[title={\prm {Umathprimeshiftdrop}}]
552% \stopnewprimitive
553
554% \startnewprimitive[title={\prm {Umathprimeshiftup}}]
555% \stopnewprimitive
556
557% \startnewprimitive[title={\prm {Umathprimespaceafter}}]
558% \stopnewprimitive
559
560% \startnewprimitive[title={\prm {Umathprimevariant}}]
561% \stopnewprimitive
562
563% \startnewprimitive[title={\prm {Umathquad}}]
564% \stopnewprimitive
565
566% \startnewprimitive[title={\prm {Umathradicaldegreeafter}}]
567% \stopnewprimitive
568
569% \startnewprimitive[title={\prm {Umathradicaldegreebefore}}]
570% \stopnewprimitive
571
572% \startnewprimitive[title={\prm {Umathradicaldegreeraise}}]
573% \stopnewprimitive
574
575% \startnewprimitive[title={\prm {Umathradicalextensibleafter}}]
576% \stopnewprimitive
577
578% \startnewprimitive[title={\prm {Umathradicalextensiblebefore}}]
579% \stopnewprimitive
580
581% \startnewprimitive[title={\prm {Umathradicalkern}}]
582% \stopnewprimitive
583
584% \startnewprimitive[title={\prm {Umathradicalrule}}]
585% \stopnewprimitive
586
587% \startnewprimitive[title={\prm {Umathradicalvariant}}]
588% \stopnewprimitive
589
590% \startnewprimitive[title={\prm {Umathradicalvgap}}]
591% \stopnewprimitive
592
593% \startnewprimitive[title={\prm {Umathruledepth}}]
594% \stopnewprimitive
595
596% \startnewprimitive[title={\prm {Umathruleheight}}]
597% \stopnewprimitive
598
599% \startnewprimitive[title={\prm {Umathskeweddelimitertolerance}}]
600% \stopnewprimitive
601
602% \startnewprimitive[title={\prm {Umathskewedfractionhgap}}]
603% \stopnewprimitive
604
605% \startnewprimitive[title={\prm {Umathskewedfractionvgap}}]
606% \stopnewprimitive
607
608% \startnewprimitive[title={\prm {Umathsource}}]
609% \stopnewprimitive
610
611% \startnewprimitive[title={\prm {Umathspaceafterscript}}]
612% \stopnewprimitive
613
614% \startnewprimitive[title={\prm {Umathspacebeforescript}}]
615% \stopnewprimitive
616
617% \startnewprimitive[title={\prm {Umathspacebetweenscript}}]
618% \stopnewprimitive
619
620% \startnewprimitive[title={\prm {Umathstackdenomdown}}]
621% \stopnewprimitive
622
623% \startnewprimitive[title={\prm {Umathstacknumup}}]
624% \stopnewprimitive
625
626% \startnewprimitive[title={\prm {Umathstackvariant}}]
627% \stopnewprimitive
628
629% \startnewprimitive[title={\prm {Umathstackvgap}}]
630% \stopnewprimitive
631
632% \startnewprimitive[title={\prm {Umathsubscriptsnap}}]
633% \stopnewprimitive
634
635% \startnewprimitive[title={\prm {Umathsubscriptvariant}}]
636% \stopnewprimitive
637
638% \startnewprimitive[title={\prm {Umathsubshiftdown}}]
639% \stopnewprimitive
640
641% \startnewprimitive[title={\prm {Umathsubshiftdrop}}]
642% \stopnewprimitive
643
644% \startnewprimitive[title={\prm {Umathsubsupshiftdown}}]
645% \stopnewprimitive
646
647% \startnewprimitive[title={\prm {Umathsubsupvgap}}]
648% \stopnewprimitive
649
650% \startnewprimitive[title={\prm {Umathsubtopmax}}]
651% \stopnewprimitive
652
653% \startnewprimitive[title={\prm {Umathsupbottommin}}]
654% \stopnewprimitive
655
656% \startnewprimitive[title={\prm {Umathsuperscriptsnap}}]
657% \stopnewprimitive
658
659% \startnewprimitive[title={\prm {Umathsuperscriptvariant}}]
660% \stopnewprimitive
661
662% \startnewprimitive[title={\prm {Umathsupshiftdrop}}]
663% \stopnewprimitive
664
665% \startnewprimitive[title={\prm {Umathsupshiftup}}]
666% \stopnewprimitive
667
668% \startnewprimitive[title={\prm {Umathsupsubbottommax}}]
669% \stopnewprimitive
670
671% \startnewprimitive[title={\prm {Umathtopaccentvariant}}]
672% \stopnewprimitive
673
674% \startnewprimitive[title={\prm {Umathunderbarkern}}]
675% \stopnewprimitive
676
677% \startnewprimitive[title={\prm {Umathunderbarrule}}]
678% \stopnewprimitive
679
680% \startnewprimitive[title={\prm {Umathunderbarvgap}}]
681% \stopnewprimitive
682
683% \startnewprimitive[title={\prm {Umathunderdelimiterbgap}}]
684% \stopnewprimitive
685
686% \startnewprimitive[title={\prm {Umathunderdelimitervariant}}]
687% \stopnewprimitive
688
689% \startnewprimitive[title={\prm {Umathunderdelimitervgap}}]
690% \stopnewprimitive
691
692% \startnewprimitive[title={\prm {Umathunderlinevariant}}]
693% \stopnewprimitive
694
695% \startnewprimitive[title={\prm {Umathuseaxis}}]
696% \stopnewprimitive
697
698% \startnewprimitive[title={\prm {Umathvextensiblevariant}}]
699% \stopnewprimitive
700
701% \startnewprimitive[title={\prm {Umathvoid}}]
702% \stopnewprimitive
703
704\startnewprimitive[title={\prm {Umathxscale}}]
705
706The \prm {Umathxscale} and \prm {Umathyscale} factors are applied to the
707horizontal and vertical parameters. They are set by style. There is no combined
708scaling primitive.
709
710\startbuffer
711$\Umathxscale\textstyle  800 a + b + x + d + e = f $\par
712$\Umathxscale\textstyle 1000 a + b + x + d + e = f $\par
713$\Umathxscale\textstyle 1200 a + b + x + d + e = f $\blank
714
715$\Umathyscale\textstyle  800 \sqrt[2]{x+1}$\quad
716$\Umathyscale\textstyle 1000 \sqrt[2]{x+1}$\quad
717$\Umathyscale\textstyle 1200 \sqrt[2]{x+1}$\blank
718\stopbuffer
719
720\typebuffer
721
722Normally only small deviations from 1000 make sense but here we want to show the
723effect and use a 20\percent\ scaling:
724
725\getbuffer
726
727\stopnewprimitive
728
729\startnewprimitive[title={\prm {Umathyscale}}]
730
731See \prm {Umathxscale}]
732
733\stopnewprimitive
734
735% \startnewprimitive[title={\prm {Umiddle}}]
736% \stopnewprimitive
737
738% \startnewprimitive[title={\prm {Uoperator}}]
739% \stopnewprimitive
740
741% \startnewprimitive[title={\prm {Uover}}]
742% \stopnewprimitive
743
744% \startnewprimitive[title={\prm {Uoverdelimiter}}]
745% \stopnewprimitive
746
747% \startnewprimitive[title={\prm {Uoverwithdelims}}]
748% \stopnewprimitive
749
750% \startnewprimitive[title={\prm {Uradical}}]
751% \stopnewprimitive
752
753% \startnewprimitive[title={\prm {Uright}}]
754% \stopnewprimitive
755
756% \startnewprimitive[title={\prm {Uroot}}]
757% \stopnewprimitive
758
759% \startnewprimitive[title={\prm {Urooted}}]
760% \stopnewprimitive
761
762% \startnewprimitive[title={\prm {Uskewed}}]
763% \stopnewprimitive
764
765% \startnewprimitive[title={\prm {Uskewedwithdelims}}]
766% \stopnewprimitive
767
768% \startnewprimitive[title={\prm {Ustartdisplaymath}}]
769% \stopnewprimitive
770
771% \startnewprimitive[title={\prm {Ustartmath}}]
772% \stopnewprimitive
773
774% \startnewprimitive[title={\prm {Ustartmathmode}}]
775% \stopnewprimitive
776
777% \startnewprimitive[title={\prm {Ustopdisplaymath}}]
778% \stopnewprimitive
779
780% \startnewprimitive[title={\prm {Ustopmath}}]
781% \stopnewprimitive
782
783% \startnewprimitive[title={\prm {Ustopmathmode}}]
784% \stopnewprimitive
785
786% \startnewprimitive[title={\prm {Ustretched}}]
787% \stopnewprimitive
788
789% \startnewprimitive[title={\prm {Ustretchedwithdelims}}]
790% \stopnewprimitive
791
792% \startnewprimitive[title={\prm {Uunderdelimiter}}]
793% \stopnewprimitive
794
795% \startnewprimitive[title={\prm {Uvextensible}}]
796% \stopnewprimitive
797
798\startoldprimitive[title={\prm {above}}][obsolete=yes]
799
800This is a variant of \prm {over} that doesn't put a rule in between.
801
802\stopoldprimitive
803
804\startoldprimitive[title={\prm {abovedisplayshortskip}}]
805
806The glue injected before a display formula when the line above it is not
807overlapping with the formula. Watch out for interference with \prm
808{baselineskip}. It can be controlled by \prm {displayskipmode}.
809
810\stopoldprimitive
811
812\startoldprimitive[title={\prm {abovedisplayskip}}]
813
814The glue injected before a display formula. Watch out for interference with
815\prm {baselineskip}. It can be controlled by \prm {displayskipmode}.
816
817\stopoldprimitive
818
819\startoldprimitive[title={\prm {abovewithdelims}}][obsolete=yes]
820
821This is a variant of \prm {atop} but with delimiters. It has a more advanced
822upgrade in \prm {Uabovewithdelims}.
823
824\stopoldprimitive
825
826\startoldprimitive[title={\prm {accent}}][obsolete=yes]
827
828This primitive is kind of obsolete in wide engines and takes two arguments: the
829indexes of an accent and a base character.
830
831\stopoldprimitive
832
833\startnewprimitive[title={\prm {additionalpageskip}}]
834
835This quantity will be added to the current page goal, stretch and shrink after
836which it will be set to zero.
837
838\stopnewprimitive
839
840\startnewprimitive[title={\prm {adjacentdemerits}}]
841
842This is a more granular variant of \prm {adjdemerits} and mostly meant for multipass
843par building, for instance:
844
845\starttyping
846\adjacentdemerits 8 0 2500 5000 7500 10000 12500 15000 20000
847\stoptyping
848
849More details can be found in the \quote {beyond paragraphs} chapter of the \quote
850{beyond} progress report. One can also discriminate between loose and tight
851deltas. In these examples we also assume a more granular fitness classes setup.
852
853\starttyping
854\adjacentdemerits 8 double
855        0  2500   5000  7500 10000 12500 15000 20000
856    20000 15000 125000 10000 7500   5000  2500     0
857\stoptyping
858
859\stopnewprimitive
860
861\startoldprimitive[title={\prm {adjdemerits}}]
862
863When \TEX\ considers to lines to be incompatible it will add this penalty to its
864verdict when considering this breakpoint.
865
866\stopoldprimitive
867
868\startnewprimitive[title={\prm {adjustspacing}}]
869
870This parameter controls expansion (hz). A value~2 expands glyphs and font kerns
871and a value of~3 only glyphs. Expansion of kerns can have side effects when they
872are used for positioning by \OPENTYPE\ features.
873
874\stopnewprimitive
875
876\startnewprimitive[title={\prm {adjustspacingshrink}}]
877
878When set to a non zero value this overloads the shrink maximum in a font when
879expansion is applied. This is then the case for all fonts.
880
881\stopnewprimitive
882
883\startnewprimitive[title={\prm {adjustspacingstep}}]
884
885When set to a non zero value this overloads the expansion step in a font when
886expansion is applied. This is then the case for all fonts.
887
888\stopnewprimitive
889
890\startnewprimitive[title={\prm {adjustspacingstretch}}]
891
892When set to a non zero value this overloads the stretch maximum in a font when
893expansion is applied. This is then the case for all fonts.
894
895\stopnewprimitive
896
897\startoldprimitive[title={\prm {advance}}]
898
899Advances the given register by an also given value:
900
901\starttyping
902\advance\scratchdimen      10pt
903\advance\scratchdimen      by 3pt
904\advance\scratchcounterone \zerocount
905\advance\scratchcounterone \scratchcountertwo
906\stoptyping
907
908The \type {by} keyword is optional.
909
910\stopoldprimitive
911
912\startnewprimitive[title={\prm {advanceby}}]
913
914This is slightly more efficient variant of \prm {advance} that doesn't look for
915\type {by} and therefore, if one is missing, doesn't need to push back the last
916seen token. Using \prm {advance} with \type {by} is nearly as efficient but takes
917more tokens.
918
919\stopnewprimitive
920
921\startnewprimitive[title={\prm {afterassigned}}]
922
923The \prm {afterassignment} primitive stores a token to be injected (and thereby
924expanded) after an assignment has happened. Unlike \prm {aftergroup}, multiple
925calls are not accumulated, and changing that would be too incompatible. This is
926why we have \prm {afterassigned}, which can be used to inject a bunch of
927tokens. But in order to be consistent this one is also not accumulative.
928
929\startbuffer
930\afterassigned{done}%
931\afterassigned{{\bf done}}%
932\scratchcounter=123
933\stopbuffer
934
935\typebuffer
936
937results in: \inlinebuffer\ being typeset.
938
939\stopnewprimitive
940
941\startoldprimitive[title={\prm {afterassignment}}]
942
943The token following \prm {afterassignment}, a traditional \TEX\ primitive, is
944saved and gets injected (and then expanded) after a following assignment took
945place.
946
947\startbuffer
948\afterassignment !\def\MyMacro {}\quad
949\afterassignment !\let\MyMacro ?\quad
950\afterassignment !\scratchcounter 123\quad
951\afterassignment !%
952\afterassignment ?\advance\scratchcounter by 1
953\stopbuffer
954
955\typebuffer
956
957The \prm {afterassignment}s are not accumulated, the last one wins:
958
959{\getbuffer}
960
961\stopoldprimitive
962
963\startoldprimitive[title={\prm {aftergroup}}]
964
965The traditional \TEX\ \prm {aftergroup} primitive stores the next token and
966expands that after the group has been closed.
967
968\startbuffer
969before{ ! \aftergroup a\aftergroup f\aftergroup t\aftergroup e\aftergroup r}
970\stopbuffer
971
972Multiple \prm {aftergroup}s are combined:
973
974\typebuffer
975
976\getbuffer
977
978\stopoldprimitive
979
980\startnewprimitive[title={\prm {aftergrouped}}]
981
982The in itself powerful \prm {aftergroup} primitives works quite well, even
983if you need to do more than one thing: you can either use it multiple times, or
984you can define a macro that does multiple things and apply that after the group.
985However, you can avoid that by using this primitive which takes a list of tokens.
986
987\startbuffer
988regular
989\bgroup
990\aftergrouped{regular}%
991\bf bold
992\egroup
993\stopbuffer
994
995\typebuffer
996
997Because it happens after the group, we're no longer typesetting in bold.
998
999{\getbuffer}
1000
1001You can mix \prm {aftergroup} and \prm {aftergrouped}. Which one is more
1002efficient depends on how many tokens are delayed. Picking up one token is faster
1003than scanning a list.
1004
1005\startbuffer
1006{
1007    \aftergroup A \aftergroup B \aftergroup C
1008test 1 : }
1009
1010{
1011    \aftergrouped{What comes next 1}
1012    \aftergrouped{What comes next 2}
1013    \aftergrouped{What comes next 3}
1014test 2 : }
1015
1016
1017{
1018    \aftergroup A \aftergrouped{What comes next 1}
1019    \aftergroup B \aftergrouped{What comes next 2}
1020    \aftergroup C \aftergrouped{What comes next 3}
1021test 3 : }
1022
1023{
1024    \aftergrouped{What comes next 1} \aftergroup A
1025    \aftergrouped{What comes next 2} \aftergroup B
1026    \aftergrouped{What comes next 3} \aftergroup C
1027test 4 : }
1028\stopbuffer
1029
1030\typebuffer
1031
1032This gives:
1033
1034\startpacked\getbuffer\stoppacked
1035
1036\stopnewprimitive
1037
1038\startnewprimitive[title={\prm {aliased}}]
1039
1040This primitive is part of the overload protection subsystem where control sequences
1041can be tagged.
1042
1043\startbuffer
1044\permanent\def\foo{FOO}
1045          \let\ofo\foo
1046\aliased  \let\oof\foo
1047
1048\meaningasis\foo
1049\meaningasis\ofo
1050\meaningasis\oof
1051\stopbuffer
1052
1053\typebuffer
1054
1055gives:
1056
1057\startlines \tt
1058\getbuffer
1059\stoplines
1060
1061When a something is \prm {let} the \quote {permanent}, \quote {primitive} and
1062\quote {immutable} flags are removed but the \prm {aliased} prefix retains
1063them.
1064
1065\startbuffer
1066\let\relaxed\relax
1067
1068\meaningasis\relax
1069\meaningasis\relaxed
1070\stopbuffer
1071
1072\typebuffer
1073
1074So in this example the \type {\relaxed} alias is not flagged as primitive:
1075
1076\startlines \tt
1077\getbuffer
1078\stoplines
1079
1080\stopnewprimitive
1081
1082\startnewprimitive[title={\prm {aligncontent}}]
1083
1084This is equivalent to a hash in an alignment preamble. Contrary to \prm
1085{alignmark} there is no need to duplicate inside a macro definition.
1086
1087\stopnewprimitive
1088
1089\startnewprimitive[title={\prm {alignmark}}]
1090
1091When you have the \type {#} not set up as macro parameter character cq.\ align
1092mark, you can use this primitive instead. The same rules apply with respect to
1093multiple such tokens in (nested) macros and alignments.
1094
1095\stopnewprimitive
1096
1097\startnewprimitive[title={\prm {alignmentcellsource}}]
1098
1099This sets the source id (a box property) of the current alignment cell.
1100
1101\stopnewprimitive
1102
1103\startnewprimitive[title={\prm {alignmentwrapsource}}]
1104
1105This sets the source id (a box property) of the current alignment row (in a \prm
1106{halign}) or column (in a \prm {valign}).
1107
1108\stopnewprimitive
1109
1110\startnewprimitive[title={\prm {aligntab}}]
1111
1112When you have the \type {&} not set up as align tab, you can use this primitive
1113instead. The same rules apply with respect to multiple such tokens in (nested)
1114macros and alignments.
1115
1116\stopnewprimitive
1117
1118\startnewprimitive[title={\prm {allcrampedstyles}}]
1119
1120A symbolic representation of \prm {crampeddisplaystyle}, \prm {crampedtextstyle},
1121\prm {crampedscriptstyle} and \prm {crampedscriptscriptstyle}; integer
1122representation: \the\allcrampedstyles.
1123
1124\stopnewprimitive
1125
1126\startnewprimitive[title={\prm {alldisplaystyles}}]
1127
1128A symbolic representation of \prm {displaystyle} and \prm {crampeddisplaystyle};
1129integer representation: \the\alldisplaystyles.
1130
1131\stopnewprimitive
1132
1133\startnewprimitive[title={\prm {allmainstyles}}]
1134
1135A symbolic representation of \prm {displaystyle}, \prm {crampeddisplaystyle},
1136\prm {textstyle} and \prm {crampedtextstyle}; integer representation:
1137\the\allmainstyles.
1138
1139\stopnewprimitive
1140
1141\startnewprimitive[title={\prm {allmathstyles}}]
1142
1143A symbolic representation of \prm {displaystyle}, \prm {crampeddisplaystyle},
1144\prm {textstyle}, \prm {crampedtextstyle}, \prm {scriptstyle}, \prm
1145{crampedscriptstyle}, \prm {scriptscriptstyle} and \prm
1146{crampedscriptscriptstyle}; integer representation: \the\allmathstyles.
1147
1148\stopnewprimitive
1149
1150\startnewprimitive[title={\prm {allscriptscriptstyles}}]
1151
1152A symbolic representation of \prm {scriptscriptstyle} and \prm
1153{crampedscriptscriptstyle}; integer representation: \the\allscriptscriptstyles.
1154
1155\stopnewprimitive
1156
1157\startnewprimitive[title={\prm {allscriptstyles}}]
1158
1159A symbolic representation of \prm {scriptstyle} and \prm {crampedscriptstyle};
1160integer representation: \the\allscriptstyles.
1161
1162\stopnewprimitive
1163
1164\startnewprimitive[title={\prm {allsplitstyles}}]
1165
1166A symbolic representation of \prm {displaystyle} and \prm {textstyle} but not
1167\prm {scriptstyle} and \prm {scriptscriptstyle}: set versus reset; integer
1168representation: \the\allsplitstyles.
1169
1170\stopnewprimitive
1171
1172\startnewprimitive[title={\prm {alltextstyles}}]
1173
1174A symbolic representation of \prm {textstyle} and \prm {crampedtextstyle};
1175integer representation: \the\alltextstyles.
1176
1177\stopnewprimitive
1178
1179\startnewprimitive[title={\prm {alluncrampedstyles}}]
1180
1181A symbolic representation of \prm {displaystyle}, \prm {textstyle}, \prm
1182{scriptstyle} and \prm {scriptscriptstyle}; integer representation:
1183\the\alluncrampedstyles.
1184
1185\stopnewprimitive
1186
1187\startnewprimitive[title={\prm {allunsplitstyles}}]
1188
1189A symbolic representation of \prm {scriptstyle} and \prm {scriptscriptstyle}; integer
1190representation: \the\allunsplitstyles.
1191
1192\stopnewprimitive
1193
1194\startnewprimitive[title={\prm {amcode}}]
1195\stopnewprimitive
1196
1197\startnewprimitive[title={\prm {associateunit}}]
1198
1199The \TEX\ engine comes with some build in units, like \type {pt} (fixed) and
1200\type {em} (adaptive). On top of that a macro package can add additional units, which is
1201what we do in \CONTEXT. In \in {figure} [fig:units] we show the current repertoire.
1202
1203\startplacefigure[title=Available units,reference=fig:units]
1204    \showunitsmap[tight]
1205    \showunitsmaplegend
1206\stopplacefigure
1207
1208When this primitive is used in a context where a number is expected it returns the origin
1209of the unit (in the color legend running from 1 upto 4). A new unit is defined as:
1210
1211\starttyping
1212\newdimen\MyDimenZA  \MyDimenZA=10pt
1213
1214\protected\def\MyDimenAB{\dimexpr\hsize/2\relax}
1215
1216\associateunit za \MyDimenZA
1217\associateunit zb \MyMacroZB
1218\stoptyping
1219
1220Possible associations are: macros that expand to a dimension, internal dimension
1221registers, register dimensions (\prm {dimendef}, direct dimensions (\prm
1222{dimensiondef}) and \LUA\ functions that return a dimension.
1223
1224One can run into scanning ahead issues where \TEX\ expects a unit and a user unit
1225gets expanded. This is why for instance in \CONTEXT\ we define the \type{ma} unit
1226as:
1227
1228\starttyping
1229\protected\def\mathaxisunit{\scaledmathaxis\mathstyle\norelax}
1230
1231\associateunit ma \mathaxisunit % or \newuserunit \mathaxisunit ma
1232\stoptyping
1233
1234So that it can be used in rule specifications that themselves look ahead for
1235keywords and therefore are normally terminated by a \prm {relax}. Adding the
1236extra \prm {norelax} will make the scanner see one that doesn't get fed back into
1237the input. Of course a macro package has to manage extra units in order to avoid
1238conflicts.
1239
1240\stopnewprimitive
1241
1242\startnewprimitive[title={\prm {atendoffile}}]
1243
1244The \prm {everyeof} primitive is kind of useless because you don't know if a file
1245(which can be a tokenlist processed as pseudo file) itself includes a file, which
1246then results in nested application of this token register. One way around this is:
1247
1248\startbuffer
1249\atendoffile\SomeCommand
1250\stopbuffer
1251
1252\typebuffer
1253
1254This acts on files the same way as \prm {atendofgroup} does. Multiple calls will
1255be accumulated and are bound to the current file.
1256
1257\stopnewprimitive
1258
1259\startnewprimitive[title={\prm {atendoffiled}}]
1260
1261This is the multi token variant of \prm {atendoffile}. Multiple invocations are
1262accumulated and by default prepended to the existing list. As with grouping this
1263permits proper nesting. You can force an append by the optional keyword {reverse}.
1264
1265\stopnewprimitive
1266
1267\startnewprimitive[title={\prm {atendofgroup}}]
1268
1269The token provided will be injected just before the group ends. Because
1270these tokens are collected, you need to be aware of possible interference
1271between them. However, normally this is managed by the macro package.
1272
1273\startbuffer
1274\bgroup
1275\atendofgroup\unskip
1276\atendofgroup )%
1277(but it works okay
1278\egroup
1279\stopbuffer
1280
1281\typebuffer
1282
1283Of course these effects can also be achieved by combining (extra) grouping with
1284\prm {aftergroup} calls, so this is more a convenience primitives than a real
1285necessity: {\inlinebuffer}, as proven here.
1286
1287\stopnewprimitive
1288
1289\startnewprimitive[title={\prm {atendofgrouped}}]
1290
1291This is the multi token variant of \prm {atendofgroup}. Of course the next
1292example is somewhat naive when it comes to spacing and so, but it shows the
1293purpose.
1294
1295\startbuffer
1296\bgroup
1297\atendofgrouped{\bf QED}%
1298\atendofgrouped{ (indeed)}%
1299This sometimes looks nicer.
1300\egroup
1301\stopbuffer
1302
1303\typebuffer
1304
1305Multiple invocations are accumulated: {\inlinebuffer}.
1306
1307\stopnewprimitive
1308
1309\startoldprimitive[title={\prm {atop}}][obsolete=yes]
1310
1311This one stack two math elements on top of each other, like a fraction but with
1312no rule. It has a more advanced upgrade in \prm {Uatop}.
1313
1314\stopoldprimitive
1315
1316\startoldprimitive[title={\prm {atopwithdelims}}][obsolete=yes]
1317
1318This is a variant of \prm {atop} but with delimiters. It has a more advanced
1319upgrade in \prm {Uatopwithdelims}.
1320
1321\stopoldprimitive
1322
1323\startnewprimitive[title={\prm {attribute}}]
1324
1325The following sets an attribute(register) value:
1326
1327\starttyping
1328\attribute 999 = 123
1329\stoptyping
1330
1331An attribute is unset by assigning \the \attributeunsetvalue\ to it. A user needs
1332to be aware of attributes being used now and in the future of a macro package and
1333setting them this way is very likely going to interfere.
1334
1335\stopnewprimitive
1336
1337\startnewprimitive[title={\prm {attributedef}}]
1338
1339This primitive can be used to relate a control sequence to an attribute register
1340and can be used to implement a mechanism for defining unique ones that won't
1341interfere. As with other registers: leave management to the macro package in
1342order to avoid unwanted side effects!
1343
1344\stopnewprimitive
1345
1346\startnewprimitive[title={\prm {automaticdiscretionary}}]
1347
1348This is an alias for the automatic hyphen trigger \type {-}.
1349
1350\stopnewprimitive
1351
1352\startnewprimitive[title={\prm {automatichyphenpenalty}}]
1353
1354The penalty injected after an automatic discretionary \type {-}, when \prm
1355{hyphenationmode} enables this.
1356
1357\stopnewprimitive
1358
1359\startnewprimitive[title={\prm {automigrationmode}}]
1360
1361This bitset determines what will bubble up to an outer level:
1362
1363\getbuffer[engine:syntax:automigrationcodes]
1364
1365The current value is {\tttf 0x\tohexadecimal\automigrationmode}.
1366
1367\stopnewprimitive
1368
1369\startnewprimitive[title={\prm {autoparagraphmode}}]
1370
1371A paragraph can be triggered by an empty line, a \type {\par} token or an
1372equivalent of it. This parameter controls how \type {\par} is interpreted in
1373different scenarios:
1374
1375\getbuffer[engine:syntax:autoparagraphcodes]
1376
1377The current value is {\tttf 0x\tohexadecimal\autoparagraphmode} and setting it to
1378a non|-|zero value can have consequences for mechanisms that expect otherwise.
1379The text option uses the same code as an empty line. The macro option checks a
1380token in a macro preamble against the frozen \prm {par} token. The last option
1381ignores the par token.
1382
1383\stopnewprimitive
1384
1385\startoldprimitive[title={\prm {badness}}]
1386
1387This one returns the last encountered badness value.
1388
1389\stopoldprimitive
1390
1391\startnewprimitive[title={\prm {balanceadjdemerits}}]
1392
1393These are added to the accumulated demerits depending on the fitness of
1394neighbouring slots in balancing act.
1395
1396\stopnewprimitive
1397
1398\startnewprimitive[title={\prm {balancebottomskip}}]
1399
1400The counterpart of \prm {balancetopskip} and ensures that the last depth honors
1401this criterium.
1402
1403\stopnewprimitive
1404
1405\startnewprimitive[title={\prm {balanceboundary}}]
1406
1407This boundary is triggering a callback that can itself trigger a try break call. It's up to
1408the macro package to come up with a usage scenario.
1409
1410\stopnewprimitive
1411
1412\startnewprimitive[title={\prm {balancebreakpasses}}]
1413
1414See (upcoming) \CONTEXT\ documentation for an explanation.
1415
1416\stopnewprimitive
1417
1418\startnewprimitive[title={\prm {balancechecks}}]
1419
1420The balance tracer callback gets this paremeter passed.
1421
1422\stopnewprimitive
1423
1424\startnewprimitive[title={\prm {balanceemergencyshrink}}]
1425
1426{\em This is a reserved parameter.}
1427
1428\stopnewprimitive
1429
1430\startnewprimitive[title={\prm {balanceemergencystretch}}]
1431
1432When set this will make the balancer more tolerant. It's comparable to \prm
1433{emergencystretch} in the par builder.
1434
1435\stopnewprimitive
1436
1437\startnewprimitive[title={\prm {balancelineheight}}]
1438
1439{\em This is a reserved parameter.}
1440
1441\stopnewprimitive
1442
1443\startnewprimitive[title={\prm {balancelooseness}}]
1444
1445When set the balancer tries to produce nore or less slots. As with the par
1446builder the result of looseness is kind of unpredictable. One needs plenty of
1447glue and normally that is not present in a vertical list.
1448
1449\stopnewprimitive
1450
1451\startnewprimitive[title={\prm {balancepasses}}]
1452
1453Specifies one or more recipes for additional second balance passes. Examples
1454can be found in the \CONTEXT\ distribution (in due time).
1455
1456\stopnewprimitive
1457
1458\startnewprimitive[title={\prm {balancepenalty}}]
1459
1460This is the penalty applied between slots, prety much like \prm {linepenalty}.
1461
1462\stopnewprimitive
1463
1464\startnewprimitive[title={\prm {balancefinalpenalties}}]
1465
1466This is a penalty array which values will be applied to the end of the to be
1467balanced list, starting at the end. Widow, club and other encountered penalties
1468will be overloaded.
1469
1470\starttyping
1471\balancefinalpenalties 4
1472    10000 9000 8000 7000
1473\relax
1474\stoptyping
1475
1476The last one is not repetitive so here at most four penalties will be injected
1477between lines (that is: hlists with the line subtype).
1478
1479\stopnewprimitive
1480
1481\startnewprimitive[title={\prm {balanceshape}}]
1482
1483\startbuffer[shape]
1484\balanceshape 3
1485    topskip 11pt bottomskip 21pt vsize 91pt next
1486    topskip 12pt bottomskip 22pt vsize 92pt next
1487    topskip 13pt bottomskip 23pt vsize 93pt
1488\relax
1489\stopbuffer
1490
1491\stopnewprimitive
1492
1493\startnewprimitive[title={\prm {balanceshapebottomspace}}]
1494
1495This gives the (fixed) amount of space added at the bottom of the given shape
1496slot.
1497
1498\startbuffer
1499\the\balanceshapebottomspace 1 \space
1500\the\balanceshapebottomspace 3
1501\stopbuffer
1502
1503\typebuffer
1504
1505\start \getbuffer[shape] We get: {\inlinebuffer}. \stop
1506
1507\stopnewprimitive
1508
1509\startnewprimitive[title={\prm {balanceshapetopspace}}]
1510
1511This provides (fixed) amount of space added at the top of the given shape slot.
1512
1513\startbuffer
1514\the\balanceshapetopspace 1 \space
1515\the\balanceshapetopspace 3
1516\stopbuffer
1517
1518\typebuffer
1519
1520\start \getbuffer[shape] This results in: {\inlinebuffer}. \stop
1521
1522\stopnewprimitive
1523
1524\startnewprimitive[title={\prm {balanceshapevsize}}]
1525
1526This returns the the target height of the given shape slot.
1527
1528\startbuffer
1529\the\balanceshapevsize 1 \space
1530\the\balanceshapevsize 3
1531\stopbuffer
1532
1533\typebuffer
1534
1535\start \getbuffer[shape] This results in: {\inlinebuffer}. \stop
1536
1537\stopnewprimitive
1538
1539\startnewprimitive[title={\prm {balancetolerance}}]
1540
1541This parameter sets the criterium for a slot being bad (pretty much like in the
1542linebreak for a line). Although the code is able to have a pre balance pass it
1543has no meaning here so we don't have a \type {\balancepretolerance}. \footnote
1544{We might find usage for it some day.}
1545
1546\stopnewprimitive
1547
1548\startnewprimitive[title={\prm {balancetopskip}}]
1549
1550This glue ensures the height of the first content (box or rule) in a slot. It can
1551be compared to \prm {topskip} and \prm {splittopskip}.
1552
1553\stopnewprimitive
1554
1555\startnewprimitive[title={\prm {balancevsize}}]
1556
1557This sets the target height of a balance slot unless \prm {balanceshape} is used.
1558
1559\stopnewprimitive
1560
1561\startoldprimitive[title={\prm {baselineskip}}]
1562
1563This is the maximum glue put between lines. The depth of the previous and height
1564of the next line are substracted.
1565
1566\stopoldprimitive
1567
1568\startoldprimitive[title={\prm {batchmode}}]
1569
1570This command disables (error) messages which can safe some runtime in situations
1571where \TEX's character|-|by|-|character log output impacts runtime. It only makes
1572sense in automated workflows where one doesn't look at the log anyway.
1573
1574\stopoldprimitive
1575
1576\startnewprimitive[title={\prm {begincsname}}]
1577
1578The next code creates a control sequence token from the given serialized tokens:
1579
1580\starttyping
1581\csname mymacro\endcsname
1582\stoptyping
1583
1584When \type {\mymacro} is not defined a control sequence will be created with the
1585meaning \prm {relax}. A side effect is that a test for its existence might fail
1586because it now exists. The next sequence will {\em not} create an controil
1587sequence:
1588
1589\starttyping
1590\begincsname mymacro\endcsname
1591\stoptyping
1592
1593This actually is kind of equivalent to:
1594
1595\starttyping
1596\ifcsname mymacro\endcsname
1597    \csname mymacro\endcsname
1598\fi
1599\stoptyping
1600
1601\stopnewprimitive
1602
1603\startoldprimitive[title={\prm {begingroup}}]
1604
1605This primitive starts a group and has to be ended with \prm {endgroup}. See \prm
1606{beginsimplegroup} for more info.
1607
1608\stopoldprimitive
1609
1610\startnewprimitive[title={\prm {beginlocalcontrol}}]
1611
1612Once \TEX\ is initialized it will enter the main loop. In there certain commands
1613trigger a function that itself can trigger further scanning and functions. In
1614\LUAMETATEX\ we can have local main loops and we can either enter it from the
1615\LUA\ end (which we don't discuss here) or at the \TEX\ end using this primitive.
1616
1617\startbuffer
1618\scratchcounter100
1619
1620\edef\whatever{
1621    a
1622    \beginlocalcontrol
1623        \advance\scratchcounter 10
1624        b
1625    \endlocalcontrol
1626    \beginlocalcontrol
1627        c
1628    \endlocalcontrol
1629    d
1630    \advance\scratchcounter 10
1631}
1632
1633\the\scratchcounter
1634\whatever
1635\the\scratchcounter
1636\stopbuffer
1637
1638\typebuffer
1639
1640A bit of close reading probably gives an impression of what happens here:
1641
1642{\getbuffer}
1643
1644The local loop can actually result in material being injected in the current node
1645list. However, where normally assignments are not taking place in an \prm
1646{edef}, here they are applied just fine. Basically we have a local \TEX\ job, be
1647it that it shares all variables with the parent loop.
1648
1649\stopnewprimitive
1650
1651\startnewprimitive[title={\prm {beginmathgroup}}]
1652
1653In math mode grouping with \prm {begingroup} and \prm {endgroup} in some cases
1654works as expected, but because the math input is converted in a list that gets
1655processed later some settings can become persistent, like changes in style or
1656family. The engine therefore provides the alternatives \prm {beginmathgroup} and
1657\prm {endmathgroup} that restore some properties.
1658
1659\stopnewprimitive
1660
1661\startnewprimitive[title={\prm {beginmvl}}]
1662
1663This initiates intercepting the main vertical list (the page). There has to be a
1664matching \prm {endmvl}. For example:
1665
1666\starttyping
1667\beginmvl 1 the main vertical list, one \endmvl
1668\beginmvl 2 the main vertical list, two \endmvl
1669\stoptyping
1670
1671The streams can be flushed out of order:
1672
1673\starttyping
1674\setbox\scratchboxone\flushmvl 2
1675\setbox\scratchboxtwo\flushmvl 1
1676\stoptyping
1677
1678One can be more specific:
1679
1680\starttyping
1681\beginmvl
1682    index   1
1683    options 5 % ignore prevdepth (1) and discard top (4)
1684\relax
1685    ....
1686\endmvl
1687\stoptyping
1688
1689More details can be found in the \CONTEXT\ low level manuals that describe this
1690feature in combination with balancing.
1691
1692\stopnewprimitive
1693
1694\startnewprimitive[title={\prm {beginsimplegroup}}]
1695
1696The original \TEX\ engine distinguishes two kind of grouping that at the user end
1697show up as:
1698
1699\starttyping
1700\begingroup \endgroup
1701\bgroup \egroup { }
1702\stoptyping
1703
1704where the last two pairs are equivalent unless the scanner explicitly wants to see a
1705left and|/|or right brace and not an equivalent. For the sake of simplify we use
1706the aliases here. It is not possible to mix these pairs, so:
1707
1708\starttyping
1709\bgroup xxx\endgroup
1710\begingroup xxx\egroup
1711\stoptyping
1712
1713will in both cases issue an error. This can make it somewhat hard to write generic
1714grouping macros without somewhat dirty trickery. The way out is to use the generic
1715group opener \prm {beginsimplegroup}.
1716
1717Internally \LUAMETATEX\ is aware of  what group it currently is dealing with and
1718there we distinguish:
1719
1720\starttabulate[||||]
1721\NC simple group      \NC \type {\bgroup}           \NC \type {\egroup} \NC \NR
1722\NC semi simple group \NC \type {\begingroup}       \NC \type {\endgroup} \type {\endsimplegroup} \NC \NR
1723\NC also simple group \NC \type {\beginsimplegroup} \NC \type {\egroup} \type {\endgroup} \type {\endsimplegroup} \NC \NR
1724\NC math simple group \NC \type {\beginmathgroup}   \NC \type {\endmathgroup} \NC \NR
1725\stoptabulate
1726
1727This means that you can say:
1728
1729\starttyping
1730\beginsimplegroup xxx\endsimplegroup
1731\beginsimplegroup xxx\endgroup
1732\beginsimplegroup xxx\egroup
1733\stoptyping
1734
1735So a group started with \prm {beginsimplegroup} can be finished in three ways
1736which means that the user (or calling macro) doesn't have take into account what
1737kind of grouping was used to start with. Normally usage of this primitive is
1738hidden in macros and not something the user has to be aware of.
1739
1740\stopnewprimitive
1741
1742\startoldprimitive[title={\prm {belowdisplayshortskip}}]
1743
1744The glue injected aftter a display formula when the line above it is not
1745overlapping with the formula (\TEX\ can't look ahead). Watch out for interference
1746with \prm {baselineskip}. It can be controlled by \prm {displayskipmode}.
1747
1748\stopoldprimitive
1749
1750\startoldprimitive[title={\prm {belowdisplayskip}}]
1751
1752The glue injected after a display formula. Watch out for interference with \prm
1753{baselineskip}. It can be controlled by \prm {displayskipmode}.
1754
1755\stopoldprimitive
1756
1757\startoldprimitive[title={\prm {binoppenalty}}][obsolete=yes]
1758
1759This internal quantity is a compatibility feature because normally we will use
1760the inter atom spacing variables.
1761
1762\stopoldprimitive
1763
1764\startoldprimitive[title={\prm {botmark}}][obsolete=yes]
1765
1766This is a reference to the last mark on the current page, it gives back tokens.
1767
1768\stopoldprimitive
1769
1770\startoldprimitive[title={\prm {botmarks}}]
1771
1772This is a reference to the last mark with the given id (a number) on the current
1773page, it gives back tokens.
1774
1775\stopoldprimitive
1776
1777\startnewprimitive[title={\prm {bottomskip}}]
1778
1779{\em This is a reserved parameter.}
1780
1781\stopnewprimitive
1782
1783\startnewprimitive[title={\prm {boundary}}]
1784
1785Boundaries are signals added to he current list. This primitive injects a user
1786boundary with the given (integer) value. Such a boundary can be consulted at the
1787\LUA\ end or with \prm {lastboundary}.
1788
1789\stopnewprimitive
1790
1791\startoldprimitive[title={\prm {box}}]
1792
1793This is the box register accessor. While other registers have one property a box
1794has many, like \prm {wd}, \prm {ht} and \prm {dp}. This primitive returns the box
1795and resets the register.
1796
1797\stopoldprimitive
1798
1799\startnewprimitive[title={\prm {boxadapt}}]
1800
1801Adapting will recalculate the dimensions with a scale factor for the glue:
1802
1803\startbuffer
1804\setbox 0 \hbox       {test test test}
1805\setbox 2 \hbox {\red  test test test} \boxadapt 0  200
1806\setbox 4 \hbox {\blue test test test} \boxadapt 0 -200
1807\ruledhbox{\box0} \vskip-\lineheight
1808\ruledhbox{\box0} \vskip-\lineheight
1809\ruledhbox{\box0}
1810\stopbuffer
1811
1812\typebuffer
1813
1814Like \prm {boxfreeze} and \prm {boxrepack} this primitive has been introduced for
1815experimental usage, although we do use some in production code.
1816
1817\getbuffer
1818
1819\stopnewprimitive
1820
1821\startnewprimitive[title={\prm {boxanchor}}]
1822
1823This feature is part of an (experimental) mechanism that relates boxes. The
1824engine just tags a box and it is up to the macro package to deal with it.
1825
1826\startbuffer
1827\setbox0\hbox anchor "01010202 {test}\tohexadecimal\boxanchor0
1828\stopbuffer
1829
1830\typebuffer
1831
1832This gives: \inlinebuffer. Of course this feature is very macro specific and
1833should not be used across macro packages without coordination. An anchor has
1834two parts each not exceeding \type {0x0FFF}.
1835
1836\stopnewprimitive
1837
1838\startnewprimitive[title={\prm {boxanchors}}]
1839
1840This feature is part of an (experimental) mechanism that relates boxes. The
1841engine just tags a box and it is up to the macro package to deal with it.
1842
1843\startbuffer
1844\setbox0\hbox anchors "0101 "0202 {test}\tohexadecimal\boxanchors0
1845\stopbuffer
1846
1847\typebuffer
1848
1849This gives: \inlinebuffer. Of course this feature is very macro specific and
1850should not be used across macro packages without coordination. An anchor has
1851two parts each not exceeding \type {0x0FFF}.
1852
1853\stopnewprimitive
1854
1855\startnewprimitive[title={\prm {boxattribute}}]
1856
1857Every node, and therefore also every box gets the attributes set that are
1858active at the moment of creation. Additional attributes can be set too:
1859
1860\startbuffer
1861\darkred
1862\setbox0\hbox attr 9999 1 {whatever}
1863\the\boxattribute 0 \colorattribute
1864\the\boxattribute 0 9998
1865\the\boxattribute 0 9999
1866\stopbuffer
1867
1868\typebuffer
1869
1870A macro package should make provide a way define attributes that don't clash the
1871ones it needs itself, like, in \CONTEXT, the ones that can set a color
1872
1873\startlines \getbuffer \stoplines
1874
1875The number \the\attributeunsetvalue\ (\tohexadecimal\attributeunsetvalue)
1876indicates an unset attribute.
1877
1878\stopnewprimitive
1879
1880\startnewprimitive[title={\prm {boxdirection}}]
1881
1882The direction of a box defaults to \type {l2r} but can be explicitly set:
1883
1884\startbuffer
1885\setbox0\hbox direction 1 {this is a test}\textdirection1
1886\setbox2\hbox direction 0 {this is a test}\textdirection0
1887\the\boxdirection0: \box0
1888\the\boxdirection2: \box2
1889\stopbuffer
1890
1891\typebuffer
1892
1893The \prm {textdirection} does not influence the box direction:
1894
1895\startlines \getbuffer \stoplines
1896
1897\stopnewprimitive
1898
1899\startnewprimitive[title={\prm {boxfinalize}}]
1900
1901This is special version of \prm {boxfreeze} which we demonstrate
1902with an example:
1903
1904\startbuffer[setthem]
1905\setbox0\ruledvbox to 3cm{\hsize 2cm test\vskip10pt plus 10pt test}
1906\setbox2\copy0\setbox4\copy0\setbox6\copy0\setbox8\copy0
1907\stopbuffer
1908
1909\startbuffer[usethem]
1910\boxlimitate 0 0   % don't recurse
1911\boxfreeze   2 0   % don't recurse
1912\boxfinalize 4 500 % scale glue multiplier by .50
1913\boxfinalize 6 250 % scale glue multiplier by .25
1914\boxfinalize 8 100 % scale glue multiplier by .10
1915
1916\hpack\bgroup
1917    \copy0\quad\copy2\quad\copy4\quad\copy6\quad\copy8
1918\egroup
1919\stopbuffer
1920
1921\typebuffer[usethem]
1922
1923where the boxes are populated with:
1924
1925\typebuffer[setthem]
1926
1927\startlinecorrection
1928\getbuffer[setthem,usethem]
1929\stoplinecorrection
1930
1931\stopnewprimitive
1932
1933\startnewprimitive[title={\prm {boxfreeze}}]
1934
1935Glue in a box has a fixed component that will always be used and stretch and
1936shrink that kicks in when needed. The effective value (width) of the glue is
1937driven by some box parameters that are set by the packaging routine. This is why
1938we can unbox: the original value is kept. It is the backend that calculates the
1939effective value. Te \prm {boxfreeze} primitive can do the same: turn the flexible
1940glue into a fixed one.
1941
1942\startbuffer
1943\setbox    0 \hbox to 6cm {\hss frost}
1944\setbox    2 \hbox to 6cm {\hss frost}
1945\boxfreeze 2 0
1946\ruledhbox{\unhbox 0}
1947\ruledhbox{\unhbox 2}
1948\stopbuffer
1949
1950\typebuffer
1951
1952The second parameter to \prm {boxfreeze} determines recursion. We don't recurse
1953here so just freeze the outer level:
1954
1955\getbuffer
1956
1957\stopnewprimitive
1958
1959\startnewprimitive[title={\prm {boxgeometry}}]
1960
1961A box can have an orientation, offsets and|/|or anchors. These are stored
1962independently but for efficiency reasons we register if one or more of these
1963properties is set. This primitive accesses this state; it is a bitset:
1964
1965\getbuffer[engine:syntax:listgeometrycodes]
1966
1967\stopnewprimitive
1968
1969\startnewprimitive[title={\prm {boxinserts}}]
1970
1971A non zero value return indicates that there are inserts in this box. This
1972primitive is meant to be used with the balancer.
1973
1974\stopnewprimitive
1975
1976\startnewprimitive[title={\prm {boxlimit}}]
1977
1978This primitive will freeze the glue in a box but only when there is glue marked
1979with the limit option.
1980
1981\stopnewprimitive
1982
1983\startnewprimitive[title={\prm {boxlimitate}}]
1984
1985This primitive will freeze the glue in a box. It takes two arguments, a box
1986number and an number that when set to non|-|zero will recurse into nested lists.
1987
1988\stopnewprimitive
1989
1990\startnewprimitive[title={\prm {boxlimitmode}}]
1991
1992This variable controls if boxes with glue marked \quote {limit} will be checked
1993and frozen.
1994
1995\stopnewprimitive
1996
1997\startoldprimitive[title={\prm {boxmaxdepth}}]
1998
1999You can limit the depth of boxes being constructed. It's one of these parameters
2000that should be used with care because when that box is filled nested boxes can be
2001influenced.
2002
2003\stopoldprimitive
2004
2005\startnewprimitive[title={\prm {boxmigrate}}]
2006
2007When the given box has pre migration material the value will have \type {0x08}
2008set. When there is post material the \type {0x10} bit is set. Of course both can
2009be set.
2010
2011\stopnewprimitive
2012
2013\startnewprimitive[title={\prm {boxorientation}}]
2014
2015The orientation field can take quite some values and is discussed in one of the low level
2016\CONTEXT\ manuals. Some properties are dealt with in the \TEX\ engine because they
2017influence dimensions but in the end it is the backend that does the work.
2018
2019\stopnewprimitive
2020
2021\startnewprimitive[title={\prm {boxrepack}}]
2022
2023When a box of to wide or tight we can tweak it a bit with this primitive. The
2024primitive expects a box register and a dimension, where a positive number adds
2025and a negatie subtracts from the current box with.
2026
2027\startbuffer
2028\setbox 0 \hbox        {test test test}
2029\setbox 2 \hbox {\red   test test test} \boxrepack0 +.2em
2030\setbox 4 \hbox {\green test test test} \boxrepack0 -.2em
2031\ruledhbox{\box0} \vskip-\lineheight
2032\ruledhbox{\box0} \vskip-\lineheight
2033\ruledhbox{\box0}
2034\stopbuffer
2035
2036\typebuffer
2037
2038\getbuffer
2039
2040We can also use this primitive to check the natural dimensions of a box:
2041
2042\startbuffer
2043\setbox 0 \hbox spread 10pt {test test test}
2044\ruledhbox{\box0} (\the\boxrepack0,\the\wd0)
2045\stopbuffer
2046
2047\typebuffer
2048
2049In this context only one argument is expected.
2050
2051\getbuffer
2052
2053\stopnewprimitive
2054
2055\startnewprimitive[title={\prm {boxshift}}]
2056
2057Returns or sets how much the box is shifted: up or down in horizontally mode, left or
2058right in vertical mode.
2059
2060\stopnewprimitive
2061
2062\startnewprimitive[title={\prm {boxshrink}}]
2063
2064Returns the amount of shrink found (applied) in a box:
2065
2066\startbuffer
2067\setbox0\hbox to 4em {m m m m}
2068\the\boxshrink0
2069\stopbuffer
2070
2071\typebuffer
2072
2073gives: \inlinebuffer
2074
2075\stopnewprimitive
2076
2077\startnewprimitive[title={\prm {boxsource}}]
2078
2079This feature is part of an (experimental) mechanism that relates boxes. The
2080engine just tags a box and it is up to the macro package to deal with it.
2081
2082\startbuffer
2083\setbox0\hbox source 123 {m m m m}
2084\the\boxsource0
2085\stopbuffer
2086
2087\typebuffer
2088
2089This gives: \inlinebuffer. Of course this feature is very macro specific and
2090should not be used across macro packages without coordination.
2091
2092\stopnewprimitive
2093
2094\startnewprimitive[title={\prm {boxstretch}}]
2095
2096Returns the amount of stretch found (applied) in a box:
2097
2098\startbuffer
2099\setbox0\hbox to 6em {m m m m}
2100\the\boxstretch0
2101\stopbuffer
2102
2103\typebuffer
2104
2105gives: \inlinebuffer
2106
2107\stopnewprimitive
2108
2109\startnewprimitive[title={\prm {boxsubtype}}]
2110
2111Returns the subtype of the given box.
2112
2113\startbuffer
2114\setbox0\hbox           {test}[\the\boxsubtype0]
2115\setbox2\hbox container {test}[\the\boxsubtype2]
2116\stopbuffer
2117
2118\typebuffer
2119
2120gives: \inlinebuffer. Beware that the numbers can change so best use the symbolic
2121values that can be queried via \LUA.
2122
2123\stopnewprimitive
2124
2125\startnewprimitive[title={\prm {boxtarget}}]
2126
2127This feature is part of an (experimental) mechanism that relates boxes. The
2128engine just tags a box and it is up to the macro package to deal with it.
2129
2130\startbuffer
2131\setbox0\hbox source 123 {m m m m}
2132\the\boxsource0
2133\stopbuffer
2134
2135\typebuffer
2136
2137This gives: \inlinebuffer. Of course this feature is very macro specific and
2138should not be used across macro packages without coordination.
2139
2140\stopnewprimitive
2141
2142\startnewprimitive[title={\prm {boxtotal}}]
2143
2144Returns the total of height and depth of the given box.
2145
2146\stopnewprimitive
2147
2148\startnewprimitive[title={\prm {boxvadjust}}]
2149
2150When used as query this returns a bitset indicating the associated adjust and
2151migration (marks and inserts) data:
2152
2153\starttabulate[|T|l|]
2154\NC 0x1 \NC pre  adjusted \NC \NR
2155\NC 0x2 \NC post adjusted \NC \NR
2156\NC 0x4 \NC pre  migrated \NC \NR
2157\NC 0x8 \NC post migrated \NC \NR
2158\stoptabulate\
2159
2160When used as a setter it directly adds adjust data to the box and it accepts the
2161same keywords as \prm {vadjust}.
2162
2163\stopnewprimitive
2164
2165\startnewprimitive[title={\prm {boxxmove}}]
2166
2167This will set the vertical offset and adapt the dimensions accordingly.
2168
2169\stopnewprimitive
2170
2171\startnewprimitive[title={\prm {boxxoffset}}]
2172
2173Returns or sets the horizontal offset of the given box.
2174
2175\stopnewprimitive
2176
2177\startnewprimitive[title={\prm {boxymove}}]
2178
2179This will set the vertical offset and adapt the dimensions accordingly.
2180
2181\stopnewprimitive
2182
2183\startnewprimitive[title={\prm {boxyoffset}}]
2184
2185Returns or sets the vertical offset of the given box.
2186
2187\stopnewprimitive
2188
2189\startnewprimitive[title={\prm {brokenpenalties}}]
2190
2191Together with \prm {widowpenalties} and \prm {clubpenalties} this one permits
2192discriminating left- and right page (doublesided) penalties. For this one needs
2193to also specify \prm {options 4} and provide penalty pairs. Where the others
2194accept multiple pairs, this primitives expects a count value one.
2195
2196\stopnewprimitive
2197
2198\startoldprimitive[title={\prm {brokenpenalty}}]
2199
2200This penalty is added after a line that ends with a hyphen; it can help to
2201discourage a page break (or split in a box).
2202
2203\stopoldprimitive
2204
2205\startoldprimitive[title={\prm {catcode}}]
2206
2207Every character can be put in a category, but this is typically
2208something that the macro package manages because changes can affect
2209behavior. Also, once passed as an argument, the catcode of a character
2210is frozen. There are 16 different values:
2211
2212\starttabulate[|l|c|l|c|]
2213\NC \type {\escapecatcode     } \NC \the\escapecatcode
2214\NC \type {\begingroupcatcode } \NC \the\begingroupcatcode  \NC \NR
2215\NC \type {\endgroupcatcode   } \NC \the\endgroupcatcode
2216\NC \type {\mathshiftcatcode  } \NC \the\mathshiftcatcode   \NC \NR
2217\NC \type {\alignmentcatcode  } \NC \the\alignmentcatcode
2218\NC \type {\endoflinecatcode  } \NC \the\endoflinecatcode   \NC \NR
2219\NC \type {\parametercatcode  } \NC \the\parametercatcode
2220\NC \type {\superscriptcatcode} \NC \the\superscriptcatcode \NC \NR
2221\NC \type {\subscriptcatcode  } \NC \the\subscriptcatcode
2222\NC \type {\ignorecatcode     } \NC \the\ignorecatcode      \NC \NR
2223\NC \type {\spacecatcode      } \NC \the\spacecatcode
2224\NC \type {\lettercatcode     } \NC \the\lettercatcode      \NC \NR
2225\NC \type {\othercatcode      } \NC \the\othercatcode
2226\NC \type {\activecatcode     } \NC \the\activecatcode      \NC \NR
2227\NC \type {\commentcatcode    } \NC \the\commentcatcode
2228\NC \type {\invalidcatcode    } \NC \the\invalidcatcode     \NC \NR
2229\stoptabulate
2230
2231The first column shows the constant that \CONTEXT\ provides and the
2232name indicates the purpose. Here are two examples:
2233
2234\starttyping
2235\catcode123=\begingroupcatcode
2236\catcode125=\endgroupcatcode
2237\stoptyping
2238
2239\stopoldprimitive
2240
2241\startnewprimitive[title={\prm {catcodetable}}]
2242
2243The catcode table with the given index will become active.
2244
2245\stopnewprimitive
2246
2247\startnewprimitive[title={\prm {cccode}}]
2248
2249This is an experimental feature that can set some processing options. The
2250character specific code is stored in the glyph node and consulted later. An
2251example of such option is \quote {ignore twin}, bit one, which we set for a few
2252punctuation characters.
2253
2254\stopnewprimitive
2255
2256\startnewprimitive[title={\prm {cdef}}]
2257
2258This primitive is like \prm {edef} but in some usage scenarios is slightly
2259more efficient because (delayed) expansion is ignored which in turn saves
2260building a temporary token list.
2261
2262\startbuffer
2263\edef\FooA{this is foo} \meaningfull\FooA\crlf
2264\cdef\FooB{this is foo} \meaningfull\FooB\par
2265\stopbuffer
2266
2267\typebuffer {\tttf \getbuffer}
2268
2269\stopnewprimitive
2270
2271\startnewprimitive[title={\prm {cdefcsname}}]
2272
2273This primitive is like \prm {edefcsame} but in some usage scenarios is slightly
2274more efficient because (delayed) expansion is ignored which in turn saves
2275building a temporary token list.
2276
2277\startbuffer
2278\edefcsname FooA\endcsname{this is foo} \meaningasis\FooA\crlf
2279\cdefcsname FooB\endcsname{this is foo} \meaningasis\FooB\par
2280\stopbuffer
2281
2282\typebuffer {\tttf \getbuffer}
2283
2284\stopnewprimitive
2285
2286\startnewprimitive[title={\prm {cfcode}}]
2287
2288This primitive is a companion to \prm {efcode} and sets the compression factor.
2289It takes three values: font, character code, and factor.
2290
2291\stopnewprimitive
2292
2293\startoldprimitive[title={\prm {char}}]
2294
2295This appends a character with the given index in the current font.
2296
2297\stopoldprimitive
2298
2299\startoldprimitive[title={\prm {chardef}}]
2300
2301The following definition relates a control sequence to a specific character:
2302
2303\starttyping
2304\chardef\copyrightsign"A9
2305\stoptyping
2306
2307However, because in a context where a number is expected, such a \prm {chardef}
2308is seen as valid number, there was a time when this primitive was used to define
2309constants without overflowing the by then limited pool of count registers. In
2310\ETEX\ aware engines this was less needed, and in \LUAMETATEX\ we have \prm
2311{integerdef} as a more natural candidate.
2312
2313\stopoldprimitive
2314
2315\startoldprimitive[title={\prm {cleaders}}]
2316
2317See \prm {gleaders} for an explanation.
2318
2319\stopoldprimitive
2320
2321\startnewprimitive[title={\prm {clearmarks}}]
2322
2323This primitive is an addition to the multiple marks mechanism that originates in
2324\ETEX\ and reset the mark registers of the given category (a number).
2325
2326\stopnewprimitive
2327
2328\startoldprimitive[title={\prm {clubpenalties}}]
2329
2330This is an array of penalty put before the first lines in a paragraph. High values
2331discourage (or even prevent) a lone line at the end of a page. This
2332command expects a count value indicating the number of entries that will follow.
2333The first entry is ends up after the first line.
2334
2335\stopoldprimitive
2336
2337\startoldprimitive[title={\prm {clubpenalty}}]
2338
2339This is the penalty put before a club line in a paragraph. High values discourage
2340(or even prevent) a lone line at the end of a next page.
2341
2342\stopoldprimitive
2343
2344\startnewprimitive[title={\prm {constant}}]
2345
2346This prefix tags a macro (without arguments) as being constant. The main
2347consequence is that in some cases expansion gets delayed which gives a little
2348performance boost and less (temporary) memory usage, for instance in \type
2349{\csname} like scenarios.
2350
2351\stopnewprimitive
2352
2353\startnewprimitive[title={\prm {constrained}}]
2354
2355See previous section about \prm {retained}.
2356
2357\stopnewprimitive
2358
2359\startoldprimitive[title={\prm {copy}}]
2360
2361This is the box register accessor that returns a copy of the box.
2362
2363\stopoldprimitive
2364
2365\startnewprimitive[title={\prm {copymathatomrule}}]
2366
2367This copies the rule bitset from the parent class (second argument) to the target
2368class (first argument). The bitset controls the features that apply to atoms.
2369
2370\stopnewprimitive
2371
2372\startnewprimitive[title={\prm {copymathparent}}]
2373
2374This binds the given class (first argument) to another class (second argument) so
2375that one doesn't need to define all properties.
2376
2377\stopnewprimitive
2378
2379\startnewprimitive[title={\prm {copymathspacing}}]
2380
2381This copies an class spacing specification to another one, so in
2382
2383\starttyping
2384\copymathspacing 34 2
2385\stoptyping
2386
2387class 34 (a user one) get the spacing from class 2 (binary).
2388
2389\stopnewprimitive
2390
2391\startnewprimitive[title={\prm {copysplitdiscards}}]
2392
2393This is a variant of \prm {splitdiscards} that keep the original.
2394
2395\stopnewprimitive
2396
2397\startoldprimitive[title={\prm {count}}]
2398
2399This accesses a count register by index. This is kind of \quote {not done} unless
2400you do it local and make sure that it doesn't influence macros that you call.
2401
2402\starttyping
2403\count4023=10
2404\stoptyping
2405
2406In standard \TEX\ the first 10 counters are special because they get reported to
2407the console, and \type {\count0} is then assumed to be the page counter.
2408
2409\stopoldprimitive
2410
2411\startoldprimitive[title={\prm {countdef}}]
2412
2413This primitive relates a control sequence to a count register. Compare this to
2414the example in the previous section.
2415
2416\starttyping
2417\countdef\MyCounter4023
2418\MyCounter=10
2419\stoptyping
2420
2421However, this is also \quote {not done}. Instead one should use the allocator that
2422the macro package provides.
2423
2424\starttyping
2425\newcount\MyCounter
2426\MyCounter=10
2427\stoptyping
2428
2429In \LUAMETATEX\ we also have integers that don't rely on registers. These are
2430assigned by the primitive \prm {integerdef}:
2431
2432\starttyping
2433\integerdef\MyCounterA 10
2434\stoptyping
2435
2436Or better \type {\newinteger}.
2437
2438\starttyping
2439\newinteger\MyCounterB
2440\MyCounterN10
2441\stoptyping
2442
2443There is a lowlevel manual on registers.
2444
2445\stopoldprimitive
2446
2447\startoldprimitive[title={\prm {cr}}]
2448
2449This ends a row in an alignment. It also ends an alignment preamble.
2450\stopoldprimitive
2451
2452\startnewprimitive[title={\prm {crampeddisplaystyle}}]
2453
2454A less spacy alternative of \prm {displaystyle}; integer representation:
2455\the\scriptstyle.
2456
2457\stopnewprimitive
2458
2459\startnewprimitive[title={\prm {crampedscriptscriptstyle}}]
2460
2461A less spacy alternative of \prm {scriptscriptstyle}; integer representation:
2462\the\scriptscriptstyle.
2463
2464\stopnewprimitive
2465
2466\startnewprimitive[title={\prm {crampedscriptstyle}}]
2467
2468A less spacy alternative of \prm {scriptstyle}; integer representation:
2469\the\scriptstyle.
2470
2471\stopnewprimitive
2472
2473\startnewprimitive[title={\prm {crampedtextstyle}}]
2474
2475A less spacy alternative of \prm {textstyle}; integer representation:
2476\the\textstyle.
2477
2478\stopnewprimitive
2479
2480\startoldprimitive[title={\prm {crcr}}]
2481
2482This ends a row in an alignment when it hasn't ended yet.
2483
2484\stopoldprimitive
2485
2486\startnewprimitive[title={\prm {csactive}}]
2487
2488Because \LUATEX\ (and \LUAMETATEX) are \UNICODE\ engines active characters are
2489implemented a bit differently. They don't occupy a eight bit range of characters
2490but are stored as control sequence with a special prefix \type {U+FFFF} which
2491never shows up in documents. The \prm {csstring} primitive injects the name of a
2492control sequence without leading escape character, the \prm {csactive} injects
2493the internal name of the following (either of not active) character. As we cannot
2494display the prefix: \type {\csactive~} will inject the \UTF\ sequences for \type
2495{U+FFFF} and \type {U+007E}, so here we get the bytes \type {EFBFBF7E}. Basically
2496the next token is preceded by \prm {string}, so when you don't provide a
2497character you are in for a surprise.
2498
2499\stopnewprimitive
2500
2501\startoldprimitive[title={\prm {csname}}]
2502
2503This original \TEX\ primitive starts the construction of a control sequence
2504reference. It does a lookup and when no sequence with than name is found, it will
2505create a hash entry and defaults its meaning to \prm {relax}.
2506
2507\starttyping
2508\csname letters and other characters\endcsname
2509\stoptyping
2510
2511\stopoldprimitive
2512
2513\startnewprimitive[title={\prm {csnamestring}}]
2514
2515This is a companion of \prm {lastnamedcs} that injects the name of the found
2516control sequence. When used inside a \type {csname} constructor it is more
2517efficient than repeating a token list, compare:
2518
2519\starttyping
2520\csname\ifcsname whatever\endcsname\csnamestring\endcsname % referenced
2521\csname\ifcsname whatever\endcsname     whatever\endcsname % scanned
2522\stoptyping
2523
2524\stopnewprimitive
2525
2526\startnewprimitive[title={\prm {csstring}}]
2527
2528This primitive returns the name of the control sequence given without the leading
2529escape character (normally a backslash). Of course you could strip that character
2530with a simple helper but this is more natural.
2531
2532\startbuffer
2533\csstring\mymacro
2534\stopbuffer
2535
2536\typebuffer
2537
2538We get the name, not the meaning: {\tt \inlinebuffer}.
2539
2540\stopnewprimitive
2541
2542\startoldprimitive[title={\prm {currentgrouplevel}}]
2543
2544\startbuffer
2545[\the\currentgrouplevel] \bgroup
2546    [\the\currentgrouplevel] \bgroup
2547        [\the\currentgrouplevel]
2548    \egroup [\the\currentgrouplevel]
2549\egroup [\the\currentgrouplevel]
2550\stopbuffer
2551
2552The next example gives: \inlinebuffer.
2553
2554\typebuffer
2555
2556\stopoldprimitive
2557
2558\startoldprimitive[title={\prm {currentgrouptype}}]
2559
2560\startbuffer
2561[\the\currentgrouptype] \bgroup
2562    [\the\currentgrouptype] \begingroup
2563        [\the\currentgrouptype]
2564    \endgroup [\the\currentgrouptype]
2565    [\the\currentgrouptype] \beginmathgroup
2566        [\the\currentgrouptype]
2567    \endmathgroup [\the\currentgrouptype]
2568[\the\currentgrouptype] \egroup
2569\stopbuffer
2570
2571The next example gives: \inlinebuffer.
2572
2573\typebuffer
2574
2575The possible values depend in the engine and for \LUAMETATEX\ they are:
2576
2577\startluacode
2578context.startfourrows()
2579context.starttabulate { "|r|l|" }
2580for i=0,#tex.groupcodes do
2581    context.NC() context(i)
2582    context.NC() context(tex.groupcodes[i])
2583    context.NC() context.NR()
2584end
2585context.stoptabulate()
2586context.stopfourrows()
2587\stopluacode
2588
2589\stopoldprimitive
2590
2591\startoldprimitive[title={\prm {currentifbranch}}]
2592
2593\startbuffer
2594[\the\currentifbranch] \iftrue
2595    [\the\currentifbranch] \iffalse
2596        [\the\currentifbranch]
2597    \else
2598        [\the\currentifbranch]
2599    \fi [\the\currentifbranch]
2600\fi [\the\currentifbranch]
2601\stopbuffer
2602
2603The next example gives: \inlinebuffer.
2604
2605\typebuffer
2606
2607So when in the \quote {then} branch we get plus one and when in the \quote {else}
2608branch we end up with a minus one.
2609
2610\stopoldprimitive
2611
2612\startoldprimitive[title={\prm {currentiflevel}}]
2613
2614\startbuffer
2615[\the\currentiflevel] \iftrue
2616    [\the\currentiflevel]\iftrue
2617        [\the\currentiflevel] \iftrue
2618            [\the\currentiflevel]
2619        \fi [\the\currentiflevel]
2620    \fi [\the\currentiflevel]
2621\fi [\the\currentiflevel]
2622\stopbuffer
2623
2624The next example gives: \inlinebuffer.
2625
2626\typebuffer
2627
2628\stopoldprimitive
2629
2630\startoldprimitive[title={\prm {currentiftype}}]
2631
2632\startbuffer
2633[\the\currentiftype] \iftrue
2634    [\the\currentiftype]\iftrue
2635        [\the\currentiftype] \iftrue
2636            [\the\currentiftype]
2637        \fi [\the\currentiftype]
2638    \fi [\the\currentiftype]
2639\fi [\the\currentiftype]
2640\stopbuffer
2641
2642The next example gives: \inlinebuffer.
2643
2644\typebuffer
2645
2646The values are engine dependent:
2647
2648\startluacode
2649local t = tex.getiftypes()
2650context.startfiverows()
2651context.starttabulate { "|r|l|" }
2652for i=0,#tex.groupcodes do
2653    context.NC() context(i)
2654    context.NC() context(t[i])
2655    context.NC() context.NR()
2656end
2657context.stoptabulate()
2658context.stopfiverows()
2659\stopluacode
2660
2661\stopoldprimitive
2662
2663\startnewprimitive[title={\prm {currentloopiterator}}]
2664
2665Here we show the different expanded loop variants:
2666
2667\startbuffer
2668\edef\testA{\expandedloop  1 10 1{!}}
2669\edef\testB{\expandedrepeat  10  {!}}
2670\edef\testC{\expandedendless     {\ifnum\currentloopiterator>10 \quitloop\else !\fi}}
2671\edef\testD{\expandedendless     {\ifnum#I>10 \quitloop\else !\fi}}
2672\stopbuffer
2673
2674\typebuffer \getbuffer
2675
2676All these give the same result:
2677
2678\startlines \tt
2679\meaningasis\testA
2680\meaningasis\testB
2681\meaningasis\testC
2682\meaningasis\testD
2683\stoplines
2684
2685The \type {#I} is a shortcut to the current loop iterator; other shortcuts are
2686\type {#P} for the parent iterator value and \type {#G} for the grand parent.
2687
2688\stopnewprimitive
2689
2690\startnewprimitive[title={\prm {currentloopnesting}}]
2691
2692This integer reports how many nested loops are currently active. Of course in
2693practice the value only has meaning when you know at what outer level your nested
2694loop started.
2695
2696\startbuffer
2697\expandedloop 1 10 1 {%
2698    \ifodd\currentloopiterator\else
2699      [\expandedloop 1 \currentloopiterator 1 {%
2700        \the\currentloopnesting
2701      }]
2702    \fi
2703}
2704\stopbuffer
2705
2706\typebuffer
2707
2708Here we use the two numeric state primitives \prm {currentloopiterator} and \prm
2709{currentloopnesting}. This results in:
2710
2711\getbuffer
2712
2713\stopnewprimitive
2714
2715\startnewprimitive[title={\prm {currentlysetmathstyle}}]
2716    TODO
2717\stopnewprimitive
2718
2719\startnewprimitive[title={\prm {currentmarks}}]
2720
2721Marks only get updated when a page is split off or part of a box using \prm
2722{vsplit} gets wrapped up. This primitive gives access to the current value of a
2723mark and takes the number of a mark class.
2724
2725\stopnewprimitive
2726
2727\startoldprimitive[title={\prm {currentstacksize}}]
2728
2729This is more diagnostic feature than a useful one but we show it anyway. There is
2730some basic overhead when we enter a group:
2731
2732\startbuffer
2733\bgroup [\the\currentstacksize]
2734    \bgroup [\the\currentstacksize]
2735        \bgroup [\the\currentstacksize]
2736        [\the\currentstacksize] \egroup
2737    [\the\currentstacksize] \egroup
2738[\the\currentstacksize] \egroup
2739\stopbuffer
2740
2741\typebuffer \getbuffer
2742
2743As soon as we define something or change a value, the stack gets populated by
2744information needed for recovery after the group ends.
2745
2746\startbuffer
2747\bgroup [\the\currentstacksize]
2748    \scratchcounter 1
2749    \bgroup [\the\currentstacksize]
2750        \scratchdimen 1pt
2751        \scratchdimen 2pt
2752        \bgroup [\the\currentstacksize]
2753            \scratchcounter 2
2754            \scratchcounter 3
2755        [\the\currentstacksize] \egroup
2756    [\the\currentstacksize] \egroup
2757[\the\currentstacksize] \egroup
2758\stopbuffer
2759
2760\typebuffer \getbuffer
2761
2762The stack also keeps some state information, for instance when a box is being
2763built. In \LUAMETATEX\ that is is quite a bit more than in other engines but it
2764is compensated by more efficient save stack handling elsewhere.
2765
2766\startbuffer
2767\hbox \bgroup [\the\currentstacksize]
2768    \hbox \bgroup [\the\currentstacksize]
2769        \hbox \bgroup [\the\currentstacksize]
2770        [\the\currentstacksize] \egroup
2771    [\the\currentstacksize] \egroup
2772[\the\currentstacksize] \egroup
2773\stopbuffer
2774
2775\typebuffer \getbuffer
2776
2777\stopoldprimitive
2778
2779\startoldprimitive[title={\prm {day}}]
2780
2781This internal number starts out with the day that the job started.
2782
2783\stopoldprimitive
2784
2785\startnewprimitive[title={\prm {dbox}}]
2786
2787A \prm {dbox} is just a \prm {vbox} (baseline at the bottom) but it has the
2788property \quote {dual baseline} which means that is some cases it will behave
2789like a \prm {vtop} (baseline at the top) too. Like:
2790
2791\ruledhbox\bgroup \showstruts
2792    \ruleddbox   {\hsize 3cm \strut dbox    \par \strut dbox    \par\strut dbox   }
2793    \ruledvbox   {\hsize 3cm \strut vbox    \par \strut vbox    \par\strut vbox   }
2794    \ruledvtop   {\hsize 3cm \strut vtop    \par \strut vtop    \par\strut vtop   }
2795    \ruledvcenter{\hsize 3cm \strut vcenter \par \strut vcenter \par\strut vcenter}%
2796\egroup
2797
2798A \type {\dbox} behaves like a \type {\vtop} when it's appended to a vertical list which
2799means that the height of the first box or rule determines the (base)line correction that
2800gets applied.
2801
2802% This example is taken from lowlevel-boxes:
2803
2804\startlinecorrection
2805\startcombination [nx=3,ny=1,location=top]
2806    {\vbox \bgroup \hsize .3\textwidth
2807        \small\small \setupalign[tolerant,stretch] \dontcomplain
2808        xxxxxxxxxxxxxxxx\par
2809        \ruledvbox{\samplefile{ward}}\par
2810        xxxxxxxxxxxxxxxx\par
2811     \egroup} {\type {\vbox}}
2812    {\vbox \bgroup \hsize .3\textwidth
2813        \small\small \setupalign[tolerant,stretch] \dontcomplain
2814        xxxxxxxxxxxxxxxx\par
2815        \ruledvtop{\samplefile{ward}}\par
2816        xxxxxxxxxxxxxxxx\par
2817     \egroup} {\type {\vtop}}
2818    {\vbox \bgroup \hsize .3\textwidth
2819        \small\small \setupalign[tolerant,stretch] \dontcomplain
2820        xxxxxxxxxxxxxxxx\par
2821        \ruleddbox{\samplefile{ward}}\par
2822        xxxxxxxxxxxxxxxx\par
2823     \egroup} {\type {\dbox}}
2824\stopcombination
2825\stoplinecorrection
2826
2827\stopnewprimitive
2828
2829\startoldprimitive[title={\prm {deadcycles}}]
2830
2831This counter is incremented every time the output routine is entered. When \prm
2832{maxdeadcycles} is reached \TEX\ will issue an error message, so you'd better
2833reset its value when a page is done.
2834
2835\stopoldprimitive
2836
2837\startoldprimitive[title={\prm {def}}]
2838
2839This is the main definition command, as in:
2840
2841\starttyping
2842\def\foo{l me}
2843\stoptyping
2844
2845with companions like \prm {gdef}, \prm {edef}, \prm {xdef}, etc. and variants
2846like:
2847
2848\starttyping
2849\def\foo#1{... #1...}
2850\stoptyping
2851
2852where the hash is used in the preamble and for referencing. More about that can
2853be found in the low level manual about macros.
2854
2855In the \CONTEXT\ distribution you can find explanations about how \LUAMETATEX\
2856extends the argument parser. When defining a macro you can do this:
2857
2858\starttyping
2859\def\foo(#1)#2{...}
2860\stoptyping
2861
2862Here the first argument between parentheses is mandate. But the magic
2863prefix \prm {tolerant} makes that limitation go away:
2864
2865\starttyping
2866\tolerant\def\foo(#1)#2{...}
2867\stoptyping
2868
2869A variant is this:
2870
2871\starttyping
2872\tolerant\def\foo(#1)#*(#2){...}
2873\stoptyping
2874
2875Here we have two optional arguments, possibly be separated by spaces. There are
2876more parsing options, that we just mention:
2877
2878\starttabulate[|T|i2l|]
2879\FL
2880\NC +   \NC keep the braces \NC \NR
2881\NC -   \NC discard and don't count the argument \NC \NR
2882\NC /   \NC remove leading an trailing spaces and pars \NC \NR
2883\NC =   \NC braces are mandate \NC \NR
2884\NC _   \NC braces are mandate and kept \NC \NR
2885\NC ^   \NC keep leading spaces \NC \NR
2886\ML
2887\NC 1-9 \NC an argument \NC \NR
2888\NC 0   \NC discard but count the argument \NC \NR
2889\ML
2890\NC *   \NC ignore spaces \NC \NR
2891\NC .   \NC ignore pars and spaces \NC \NR
2892\NC ,   \NC push back space when no match \NC \NR
2893\ML
2894\NC :   \NC pick up scanning here  \NC \NR
2895\NC ;   \NC quit scanning \NC \NR
2896\LL
2897\stoptabulate
2898
2899\stopoldprimitive
2900
2901\startoldprimitive[title={\prm {defaulthyphenchar}}][obsolete=yes]
2902
2903When a font is loaded its hyphen character is set to this value. It can be
2904changed afterwards. However, in \LUAMETATEX\ font loading is under \LUA\ control
2905so these properties can be set otherwise.
2906
2907\stopoldprimitive
2908
2909\startoldprimitive[title={\prm {defaultskewchar}}][obsolete=yes]
2910
2911When a font is loaded its skew character is set to this value. It can be changed
2912afterwards. However, in \LUAMETATEX\ font loading is under \LUA\ control so these
2913properties can be set otherwise. Also, \OPENTYPE\ math fonts have top anchor
2914instead.
2915
2916\stopoldprimitive
2917
2918\startnewprimitive[title={\prm {defcsname}}]
2919
2920We now get a series of log clutter avoidance primitives. It's fine if you argue
2921that they are not really needed, just don't use them.
2922
2923\starttyping
2924\expandafter\def\csname MyMacro:1\endcsname{...}
2925             \defcsname MyMacro:1\endcsname{...}
2926\stoptyping
2927
2928The fact that \TEX\ has three (expanded and global) companions can be seen as a
2929signal that less verbosity makes sense. It's just that macro packages use plenty
2930of \prm {csname}'s.
2931
2932\stopnewprimitive
2933
2934\startnewprimitive[title={\prm {deferred}}]
2935
2936This is mostly a compatibility prefix and it can be checked at the \LUA\ end when
2937there is a \LUA\ based assignment going on. It is the counterpart of \prm
2938{immediate}. In the traditional engines a \prm {write} is normally deferred
2939(turned into a node) and can be handled \prm {immediate}, while a \prm {special}
2940does the opposite.
2941
2942\stopnewprimitive
2943
2944\startoldprimitive[title={\prm {delcode}}][obsolete=yes]
2945
2946This assigns delimiter properties to an eight bit character so it has little use
2947in an \OPENTYPE\ math setup. WHen the assigned value is hex encoded, the first
2948byte denotes the small family, then we have two bytes for the small index,
2949followed by three similar bytes for the large variant.
2950
2951\stopoldprimitive
2952
2953\startoldprimitive[title={\prm {delimiter}}][obsolete=yes]
2954
2955This command inserts a delimiter with the given specification. In \OPENTYPE\ math
2956we use a different command so it is unlikely that this primitive is used in
2957\LUAMETATEX. It takes a number that can best be coded hexadecimal: one byte for
2958the class, one for the small family, two for the small index, one for the large
2959family and two for the large index. This demonstrates that it can't handle wide
2960fonts. Also, in \OPENTYPE\ math fonts the larger sizes and extensible come from
2961the same font as the small symbol. On top of that, in \LUAMETATEX\ we have more
2962classes than fit in a byte.
2963
2964\stopoldprimitive
2965
2966\startoldprimitive[title={\prm {delimiterfactor}}][obsolete=yes]
2967
2968This is one of the parameters that determines the size of a delimiter: at least
2969this factor times the formula height divided by 1000. In \OPENTYPE\ math
2970different properties and strategies are used.
2971
2972\stopoldprimitive
2973
2974\startoldprimitive[title={\prm {delimitershortfall}}][obsolete=yes]
2975
2976This is one of the parameters that determines the size of a delimiter: at least
2977the formula height minus this parameter. In \OPENTYPE\ math different properties
2978and strategies are used.
2979
2980\stopoldprimitive
2981
2982\startnewprimitive[title={\prm {detokened}}]
2983
2984The following token will be serialized into characters with category \quote
2985{other}.
2986
2987\startbuffer
2988\toks0{123}
2989\def\foo{let's be \relax'd}
2990\def\oof#1{let's see #1}
2991\detokened\toks0
2992\detokened\foo
2993\detokened\oof
2994\detokened\setbox
2995\detokened X
2996\stopbuffer
2997
2998\typebuffer
2999
3000Gives:
3001
3002\startlines\tt
3003\getbuffer
3004\stoplines
3005
3006Macros with arguments are not shown.
3007
3008\stopnewprimitive
3009
3010\startoldprimitive[title={\prm {detokenize}}]
3011
3012This \ETEX\ primitive turns the content of the provides list will become
3013characters, kind of verbatim.
3014
3015\startbuffer
3016\expandafter\let\expandafter\temp\detokenize{1} \meaning\temp
3017\expandafter\let\expandafter\temp\detokenize{A} \meaning\temp
3018\stopbuffer
3019
3020\typebuffer
3021
3022\startlines \tttf \getbuffer \stoplines
3023
3024\stopoldprimitive
3025
3026\startnewprimitive[title={\prm {detokenized}}]
3027
3028The following (single) token will be serialized into characters with category
3029\quote {other}.
3030
3031\startbuffer
3032\toks0{123}
3033\def\foo{let's be \relax'd}
3034\def\oof#1{let's see #1}
3035\detokenized\toks0
3036\detokenized\foo
3037\detokenized\oof
3038\detokenized\setbox
3039\detokenized X
3040\stopbuffer
3041
3042\typebuffer
3043
3044Gives:
3045
3046\startlines\tt
3047\getbuffer
3048\stoplines
3049
3050It is one of these new primitives that complement others like \prm {detokened}
3051and such, and they are often mostly useful in experiments of some low level
3052magic, which made them stay.
3053
3054\stopnewprimitive
3055
3056\startoldprimitive[title={\prm {dimen}}]
3057
3058Like \prm {count} this is a register accessor which is described in more
3059detail in a low level manual.
3060
3061\starttyping
3062\dimen0=10pt
3063\stoptyping
3064
3065While \TEX\ has some assumptions with respect to the first ten count registers
3066(as well as the one that holds the output, normally 255), all dimension registers
3067are treated equal. However, you need to be aware of clashes with other usage.
3068Therefore you can best use the predefined scratch registers or define dedicate
3069ones with the \type {\newdimen} macro.
3070
3071\stopoldprimitive
3072
3073\startoldprimitive[title={\prm {dimendef}}]
3074
3075This primitive is used by the \type {\newdimen} macro when it relates a control
3076sequence with a specific register. Only use it when you know what you're doing.
3077
3078\stopoldprimitive
3079
3080\startnewprimitive[title={\prm {dimensiondef}}]
3081
3082A variant of \prm {integerdef} is:
3083
3084\starttyping
3085\dimensiondef\MyDimen = 1234pt
3086\stoptyping
3087
3088The properties are comparable to the ones described in the section \prm
3089{integerdef}.
3090
3091\stopnewprimitive
3092
3093\startoldprimitive[title={\prm {dimexpr}}]
3094
3095This primitive is similar to of \prm {numexpr} but operates on dimensions
3096instead. Integer quantities are interpreted as dimensions in scaled points.
3097
3098\startbuffer
3099\the\dimexpr (1pt + 2pt - 5pt) * 10 / 2 \relax
3100\stopbuffer
3101
3102\typebuffer
3103
3104gives: \inlinebuffer. You can mix in symbolic integers and dimensions. This doesn't work:
3105
3106\startbuffer
3107\the\dimexpr 10 * (1pt + 2pt - 5pt) / 2 \relax
3108\stopbuffer
3109
3110because the engine scans for a dimension and only for an integer (or equivalent)
3111after a \type {*} or \type {/}.
3112
3113
3114\stopoldprimitive
3115
3116\startnewprimitive[title={\prm {dimexpression}}]
3117
3118This command is like \prm {numexpression} but results in a dimension instead of
3119an integer. Where \prm {dimexpr} doesn't like \typ {2 * 10pt} this expression
3120primitive is quite happy with it.
3121
3122You can get an idea what the engines sees by setting \prm {tracingexpressions}
3123to a value larger than zero. It shows the expression in rpn form.
3124
3125\starttyping
3126\dimexpression 4pt * 2   + 6pt   \relax
3127\dimexpression 2   * 4pt + 6pt   \relax
3128\dimexpression 4pt * 2.5 + 6pt   \relax
3129\dimexpression 2.5 * 4pt + 6pt   \relax
3130\numexpression 2 * 4 + 6         \relax
3131\numexpression (1 + 2) * (3 + 4) \relax
3132\stoptyping
3133
3134The \prm {relax} is mandate simply because there are keywords involved so the
3135parser needs to know where to stop scanning. It made no sense to be more clever
3136and introduce fuzziness (so there is no room for exposing in|-|depth \TEX\
3137insight and expertise here). In case you wonder: the difference in performance
3138between the \ETEX\ expression mechanism and the more extended variant will
3139normally not be noticed, probably because they both use a different approach and
3140because the \ETEX\ variant also has been optimized.
3141
3142\stopnewprimitive
3143
3144\startnewprimitive[title={\prm {directlua}}]
3145
3146This is the low level interface to \LUA:
3147
3148\startbuffer
3149\directlua { tex.print ("Greetings from the lua end!") }
3150\stopbuffer
3151
3152Gives: \quotation {\inlinebuffer} as expected. In \LUA\ we have access to all
3153kind of internals of the engine. In \LUAMETATEX\ the interfaces have been
3154polished and extended compared to \LUATEX. Although many primitives and
3155mechanisms were added to the \TEX\ frontend, the main extension interface remains
3156\LUA. More information can be found in documents that come with \CONTEXT, in
3157presentations and in articles.
3158
3159\stopnewprimitive
3160
3161\startoldprimitive[title={\prm {discretionary}}]
3162
3163The three snippets given with this command determine the pre, post and replace
3164component of the injected discretionary node. The \type {penalty} keyword permits
3165setting a penalty with this node. The \type {postword} keyword indicates that
3166this discretionary starts a word, and \type {preword} ends it. With \type {break}
3167the line break algorithm will prefer a pre or post component over a replace, and
3168with \type {nobreak} replace will win over pre. With \type {class} you can set a
3169math class that will determine spacing and such for discretionaries used in math
3170mode.
3171
3172\stopoldprimitive
3173
3174\startnewprimitive[title={\prm {discretionaryoptions}}]
3175
3176Processing of discretionaries is controlled by this bitset:
3177
3178\getbuffer[engine:syntax:discoptioncodes]
3179
3180These can also be set on \prm {discretionary} using the \type {options} key.
3181
3182\stopnewprimitive
3183
3184\startoldprimitive[title={\prm {displayindent}}]
3185
3186The \prm {displaywidth}, \prm {displayindent} and \prm {predisplaysize}
3187parameters are set by the line break routine (but can be adapted by the user), so
3188that mid|-|par display formula can adapt itself to hanging indentation and par
3189shapes. I order to calculate thee values and adapt the line break state
3190afterwards such a display formula is assumed to occupy three lines, so basically
3191a rather compact formula.
3192
3193\stopoldprimitive
3194
3195\startoldprimitive[title={\prm {displaylimits}}]
3196
3197By default in math display mode limits are place on top while in inline mode they
3198are placed like scripts, after the operator. Placement can be forced with the
3199\prm {limits} and \prm {nolimits} modifiers (after the operator). Because there
3200can be multiple of these in a row there is \prm {displaylimits} that forces the
3201default placement, so effectively it acts here as a reset modifier.
3202
3203\stopoldprimitive
3204
3205\startoldprimitive[title={\prm {displaystyle}}]
3206
3207One of the main math styles; integer representation: \the\displaystyle.
3208
3209\stopoldprimitive
3210
3211\startoldprimitive[title={\prm {displaywidowpenalties}}]
3212
3213This is a math specific variant of \prm {widowpenalties}.
3214
3215\stopoldprimitive
3216
3217\startoldprimitive[title={\prm {displaywidowpenalty}}]
3218
3219This is a math specific variant of \prm {widowpenalty}.
3220
3221\stopoldprimitive
3222
3223\startoldprimitive[title={\prm {displaywidth}}]
3224
3225This parameter determines the width of the formula and normally defaults to the
3226\prm {hsize} unless we are in the middle of a paragraph in which case it is
3227compensated for hanging indentation or the par shape.
3228
3229\stopoldprimitive
3230
3231\startoldprimitive[title={\prm {divide}}]
3232
3233The \prm {divide} operation can be applied to integers, dimensions, float,
3234attribute and glue quantities. There are subtle rounding differences between
3235the divisions in expressions and \prm {divide}:
3236
3237\starttabulate
3238\NC \type {\scratchcounter1049     \numexpr\scratchcounter/ 10\relax}
3239\EQ        \scratchcounter1049 \the\numexpr\scratchcounter/ 10\relax
3240\NC \NR
3241\NC \type {\scratchcounter1049     \numexpr\scratchcounter: 10\relax}
3242\EQ        \scratchcounter1049 \the\numexpr\scratchcounter: 10\relax
3243\NC \NR
3244\NC \type {\scratchcounter1049 \divide\scratchcounter by 10}
3245\EQ        \scratchcounter1049 \divide\scratchcounter by 10
3246                               \the\scratchcounter
3247\NC \NR
3248\stoptabulate
3249
3250The \type {:} divider in \prm {dimexpr} is something that we introduced in
3251\LUATEX.
3252
3253\stopoldprimitive
3254
3255\startnewprimitive[title={\prm {divideby}}]
3256
3257This is slightly more efficient variant of \prm {divide} that doesn't look for
3258\type {by}. See previous section.
3259
3260\stopnewprimitive
3261
3262\startoldprimitive[title={\prm {doublehyphendemerits}}]
3263
3264This penalty will be added to the penalty assigned to a breakpoint that results
3265in two lines ending with a hyphen.
3266
3267\stopoldprimitive
3268
3269\startnewprimitive[title={\prm {doublepenaltymode}}]
3270
3271When set to one this parameter signals the backend to use the alternative (left
3272side) penalties of the pairs set on \prm {widowpenalties}, \prm {clubpenalties}
3273and \prm {brokenpenalties}. For more information on this you can consult manuals
3274(and articles) that come with \CONTEXT.
3275
3276\stopnewprimitive
3277
3278\startoldprimitive[title={\prm {dp}}]
3279
3280Returns the depth of the given box.
3281
3282\stopoldprimitive
3283
3284\startnewprimitive[title={\prm {dpack}}]
3285
3286This does what \prm {dbox} does but without callback overhead.
3287
3288\stopnewprimitive
3289
3290\startnewprimitive[title={\prm {dsplit}}]
3291
3292This is the dual baseline variant of \prm {vsplit} (see \prm {dbox} for what that
3293means).
3294
3295\stopnewprimitive
3296
3297\startoldprimitive[title={\prm {dump}}]
3298
3299This finishes an (ini) run and dumps a format (basically the current state of the
3300engine).
3301
3302\stopoldprimitive
3303
3304\startoldprimitive[title={\prm {edef}}]
3305
3306This is the expanded version of \prm {def}.
3307
3308\startbuffer
3309\def \foo{foo}      \meaning\foo
3310\def \ofo{\foo\foo} \meaning\ofo
3311\edef\oof{\foo\foo} \meaning\oof
3312\stopbuffer
3313
3314\typebuffer
3315
3316Because \type {\foo} is unprotected it will expand inside the body definition:
3317
3318\startlines \tt
3319\getbuffer
3320\stoplines
3321
3322\stopoldprimitive
3323
3324\startnewprimitive[title={\prm {edefcsname}}]
3325
3326This is the companion of \prm {edef}:
3327
3328\starttyping
3329\expandafter\edef\csname MyMacro:1\endcsname{...}
3330             \edefcsname MyMacro:1\endcsname{...}
3331\stoptyping
3332
3333\stopnewprimitive
3334
3335\startnewprimitive[title={\prm {edivide}}]
3336
3337When expressions were introduced the decision was made to round the divisions which is
3338incompatible with the way \prm {divide} works. The expression scanners in \LUAMETATEX\
3339compensates that by providing a \type {:} for integer division. The \prm {edivide} does
3340the opposite: it rounds the way expressions do.
3341
3342\startbuffer
3343\the\dimexpr .4999pt                     : 2 \relax           =.24994pt
3344\the\dimexpr .4999pt                     / 2 \relax           =.24995pt
3345\scratchdimen.4999pt \divide \scratchdimen 2 \the\scratchdimen=.24994pt
3346\scratchdimen.4999pt \edivide\scratchdimen 2 \the\scratchdimen=.24995pt
3347
3348\the\numexpr   1001                        : 2 \relax             =500
3349\the\numexpr   1001                        / 2 \relax             =501
3350\scratchcounter1001  \divide \scratchcounter 2 \the\scratchcounter=500
3351\scratchcounter1001  \edivide\scratchcounter 2 \the\scratchcounter=501
3352\stopbuffer
3353
3354\typebuffer
3355
3356Keep in mind that with dimensions we have a fractional part so we actually
3357rounding applies to the fraction. For that reason we also provide \prm {rdivide}.
3358
3359\startlines
3360\getbuffer
3361\stoplines
3362
3363\stopnewprimitive
3364
3365\startnewprimitive[title={\prm {edivideby}}]
3366
3367This the \type {by}|-|less variant of \prm {edivide}.
3368
3369\stopnewprimitive
3370
3371\startnewprimitive[title={\prm {efcode}}]
3372
3373This primitive originates in \PDFTEX\ and can be used to set the expansion factor
3374of a glyph (characters). This primitive is obsolete because the values can be set
3375in the font specification that gets passed via \LUA\ to \TEX. Keep in mind that
3376setting font properties at the \TEX\ end is a global operation and can therefore
3377influence related fonts. In \LUAMETATEX\ the \prm {cf} code can be used to
3378specify the compression factor independent from the expansion factor. The
3379primitive takes three values: font, character code, and factor.
3380
3381\stopnewprimitive
3382
3383\startoldprimitive[title={\prm {else}}]
3384
3385This traditional primitive is part of the condition testing mechanism. When a
3386condition matches, \TEX\ will continue till it sees an \prm {else} or \prm
3387{or} or \prm {orelse} (to be discussed later). It will then do a fast skipping
3388pass till it sees an \prm {fi}.
3389
3390\stopoldprimitive
3391
3392\startoldprimitive[title={\prm {emergencyextrastretch}}]
3393
3394This is one of the extended parbuilder parameters. You can you it so temporary
3395increase the permitted stretch without knowing or messing with the normal value.
3396
3397\stopoldprimitive
3398
3399\startnewprimitive[title={\prm {emergencyleftskip}}]
3400
3401This is one of the extended parbuilder parameters (playground). It permits going
3402ragged left in case of a too bad result.
3403
3404\stopnewprimitive
3405
3406\startnewprimitive[title={\prm {emergencyrightskip}}]
3407
3408This is one of the extended parbuilder parameters (playground). It permits going
3409ragged right in case of a too bad result.
3410
3411\stopnewprimitive
3412
3413\startoldprimitive[title={\prm {emergencystretch}}]
3414
3415When set the par builder will run a third pass in order to fit the set criteria.
3416
3417\stopoldprimitive
3418
3419\startoldprimitive[title={\prm {end}}]
3420
3421This ends a \TEX\ run, unless of course this primitive is redefined.
3422
3423\stopoldprimitive
3424
3425\startoldprimitive[title={\prm {endcsname}}]
3426
3427This primitive is used in combination with \prm {csname}, \prm {ifcsname} and
3428\prm {begincsname} where its end the scanning for the to be constructed control
3429sequence token.
3430
3431\stopoldprimitive
3432
3433\startoldprimitive[title={\prm {endgroup}}]
3434
3435This is the companion of the \prm {begingroup} primitive that opens a group. See
3436\prm {beginsimplegroup} for more info.
3437
3438\stopoldprimitive
3439
3440\startoldprimitive[title={\prm {endinput}}]
3441
3442The engine can be in different input modes: reading from file, reading from a
3443token list, expanding a macro, processing something that comes back from \LUA,
3444etc. This primitive quits reading from file:
3445
3446\startbuffer
3447this is seen
3448\endinput
3449here we're already quit
3450\stopbuffer
3451
3452\typebuffer
3453
3454There is a catch. This is what the above gives:
3455
3456\getbuffer
3457
3458but how about this:
3459
3460\startbuffer
3461this is seen
3462before \endinput after
3463here we're already quit
3464\stopbuffer
3465
3466\typebuffer
3467
3468Here we get:
3469
3470\getbuffer
3471
3472Because a token list is one line, the following works okay:
3473
3474\starttyping
3475\def\quitrun{\ifsomething \endinput \fi}
3476\stoptyping
3477
3478but in a file you'd have to do this when you quit in a conditional:
3479
3480\starttyping
3481\ifsomething
3482    \expandafter \endinput
3483\fi
3484\stoptyping
3485
3486While the one|-|liner works as expected:
3487
3488\starttyping
3489\ifsomething \endinput \fi
3490\stoptyping
3491
3492\stopoldprimitive
3493
3494\startoldprimitive[title={\prm {endlinechar}}]
3495
3496This is an internal integer register. When set to positive value the character
3497with that code point will be appended to the line. The current value is \the
3498\endlinechar. Here is an example:
3499
3500\startbuffer
3501\endlinechar\hyphenasciicode
3502line 1
3503line 2
3504\stopbuffer
3505
3506\typebuffer
3507
3508\start \getbuffer \stop
3509
3510If the character is active, the property is honored and the command kicks in. The
3511maximum value is 127 (the maximum character code a single byte \UTF\ character
3512can carry.)
3513
3514\stopoldprimitive
3515
3516\startnewprimitive[title={\prm {endlocalcontrol}}]
3517
3518See \prm {beginlocalcontrol}.
3519
3520\stopnewprimitive
3521
3522\startnewprimitive[title={\prm {endmathgroup}}]
3523
3524This primitive is the counterpart of \prm {beginmathgroup}.
3525
3526\stopnewprimitive
3527
3528\startnewprimitive[title={\prm {endmvl}}]
3529
3530This ends \prm {beginmvl}.
3531
3532\stopnewprimitive
3533
3534\startnewprimitive[title={\prm {endsimplegroup}}]
3535
3536This one ends a simple group, see \prm {beginsimplegroup} for an explanation
3537about grouping primitives.
3538
3539\stopnewprimitive
3540
3541\startnewprimitive[title={\prm {enforced}}]
3542
3543The engine can be set up to prevent overloading of primitives and macros defined
3544as \prm {permanent} or \prm {immutable}. However, a macro package might want
3545to get around this in controlled situations, which is why we have a \prm
3546{enforced} prefix. This prefix in interpreted differently in so called \quote
3547{ini} mode when macro definitions can be dumped in the format. Internally they
3548get an \type {always} flag as indicator that in these places an overload is
3549possible.
3550
3551\starttyping
3552\permanent\def\foo{original}
3553
3554\def\oof         {\def\foo{fails}}
3555\def\oof{\enforced\def\foo{succeeds}}
3556\stoptyping
3557
3558Of course this only has an effect when overload protection is enabled.
3559
3560\stopnewprimitive
3561
3562\startoldprimitive[title={\prm {eofinput}}]
3563
3564This is a variant on \prm {input} that takes a token list as first argument. That
3565list is expanded when the file ends. It has companion primitives \prm
3566{atendoffile} (single token) and \prm {atendoffiled} (multiple tokens).
3567
3568\stopoldprimitive
3569
3570\startoldprimitive[title={\prm {eqno}}]
3571
3572This primitive stores the (typeset) content (presumably a number) and when the
3573display formula is wrapped that number will end up right of the formula.
3574
3575\stopoldprimitive
3576
3577\startoldprimitive[title={\prm {errhelp}}]
3578
3579This is additional help information to \prm {errmessage} that triggers an error
3580and shows a message.
3581
3582\stopoldprimitive
3583
3584\startoldprimitive[title={\prm {errmessage}}]
3585
3586This primitive expects a token list and shows its expansion on the console
3587and|/|or in the log file, depending on how \TEX\ is configured. After that it
3588will enter the error state and either goes on or waits for input, again depending
3589on how \TEX\ is configured. For the record: we don't use this primitive in
3590\CONTEXT.
3591
3592\stopoldprimitive
3593
3594\startoldprimitive[title={\prm {errorcontextlines}}]
3595
3596This parameter determines the number on lines shown when an error is triggered.
3597
3598\stopoldprimitive
3599
3600\startoldprimitive[title={\prm {errorstopmode}}]
3601
3602This directive stops at every opportunity to interact. In \CONTEXT\ we overload
3603the actions in a callback and quit the run because we can assume that a
3604successful outcome is unlikely.
3605
3606\stopoldprimitive
3607
3608\startoldprimitive[title={\prm {escapechar}}]
3609
3610This internal integer has the code point of the character that get prepended to a
3611control sequence when it is serialized (for instance in tracing or messages).
3612
3613\stopoldprimitive
3614
3615\startnewprimitive[title={\prm {etexexprmode}}]
3616
3617When set to a positive value the \type {:} and \type {;} operators are not
3618interpreted. In \CONTEXT\ we keep this value zero! This flag was added in 2024
3619for \LATEX\ where in places \type {;} is used as signal to end an expression
3620instead of \type {\relax}). Because one never knows what users expect this flag
3621disables both.
3622
3623\stopnewprimitive
3624
3625\startnewprimitive[title={\prm {etoks}}]
3626
3627This assigns an expanded token list to a token register:
3628
3629\starttyping
3630\def\temp{less stuff}
3631\etoks\scratchtoks{a bit \temp}
3632\stoptyping
3633
3634The orginal value of the register is lost.
3635
3636\stopnewprimitive
3637
3638\startnewprimitive[title={\prm {etoksapp}}]
3639
3640A variant of \prm {toksapp} is the following: it expands the to be appended
3641content.
3642
3643\starttyping
3644\def\temp{more stuff}
3645\etoksapp\scratchtoks{some \temp}
3646\stoptyping
3647
3648\stopnewprimitive
3649
3650\startnewprimitive[title={\prm {etokspre}}]
3651
3652A variant of \prm {tokspre} is the following: it expands the to be prepended
3653content.
3654
3655\starttyping
3656\def\temp{less stuff}
3657\etokspre\scratchtoks{a bit \temp}
3658\stoptyping
3659
3660\stopnewprimitive
3661
3662\startnewprimitive[title={\prm {eufactor}}]
3663
3664When we introduced the \type {es} (2.5cm) and \type {ts} (2.5mm) units as metric
3665variants of the \type {in} we also added the \type {eu} factor. One \type {eu}
3666equals one tenth of a \type {es} times the \prm {eufactor}. The \type {ts} is a
3667convenient offset in test files, the \type {es} a convenient ones for layouts and
3668image dimensions and the \type {eu} permits definitions that scale nicely without
3669the need for dimensions. They also were a prelude to what later became possible
3670with \prm {associateunit}.
3671
3672\stopnewprimitive
3673
3674\startnewprimitive[title={\prm {everybeforepar}}]
3675
3676This token register is expanded before a paragraph is triggered. The reason for
3677triggering is available in \prm {lastpartrigger}.
3678
3679\stopnewprimitive
3680
3681\startoldprimitive[title={\prm {everycr}}]
3682
3683This token list gets expanded when a row ends in an alignment. Normally it will
3684use \prm {noalign} as wrapper
3685
3686\startbuffer
3687{\everycr{\noalign{H}}            \halign{#\cr test\cr test\cr}}
3688{\everycr{\noalign{V}} \hsize 4cm \valign{#\cr test\cr test\cr}}
3689\stopbuffer
3690
3691\typebuffer
3692
3693Watch how the \prm {cr} ending the preamble also get this treatment:
3694
3695\getbuffer
3696
3697\stopoldprimitive
3698
3699\startoldprimitive[title={\prm {everydisplay}}]
3700
3701This token list gets expanded every time we enter display mode. It is a companion
3702of \prm {everymath}.
3703
3704\stopoldprimitive
3705
3706\startoldprimitive[title={\prm {everyeof}}]
3707
3708The content of this token list is injected when a file ends but it can only be
3709used reliably when one is really sure that no other file is loaded in the
3710process. So in the end it is of no real use in a more complex macro package.
3711
3712\stopoldprimitive
3713
3714\startoldprimitive[title={\prm {everyhbox}}]
3715
3716This token list behaves similar to \prm {everyvbox} so look there for an
3717explanation.
3718
3719\stopoldprimitive
3720
3721\startoldprimitive[title={\prm {everyjob}}]
3722
3723This token list register is injected at the start of a job, or more precisely,
3724just before the main control loop starts.
3725
3726\stopoldprimitive
3727
3728\startoldprimitive[title={\prm {everymath}}]
3729
3730Often math needs to be set up independent from the running text and this token
3731list can be used to do that. There is also \prm {everydisplay}.
3732
3733\stopoldprimitive
3734
3735\startnewprimitive[title={\prm {everymathatom}}]
3736
3737When a math atom is seen this tokenlist is expanded before content is processed
3738inside the atom body. It is basically a math companion for \prm {everyhbox} and
3739friends and it is therefore probably just as useless. The next example shows how
3740it works:
3741
3742\startbuffer
3743\everymathatom
3744  {\begingroup
3745   \scratchcounter\lastatomclass
3746   \everymathatom{}%
3747   \mathghost{\hbox to 0pt yoffset -1ex{\smallinfofont \setstrut\strut \the\scratchcounter\hss}}%
3748   \endgroup}
3749
3750$ a = \mathatom class 4 {b} + \mathatom class 5 {c} $
3751\stopbuffer
3752
3753\typebuffer
3754
3755We get a formula with open- and close atom spacing applied to~$b$ and~$c$:
3756
3757{\getbuffer}
3758
3759This example shows bit of all: we want the number to be invisible to the math
3760machinery so we ghost it. So, we need to make sure we don't get recursion due to
3761nested injection and expansion of \prm {everymathatom} and of course we need to
3762store the number. The \prm {lastatomclass} state variable is only meaningful
3763inside an explicit atom wrapper like \prm {mathatom} and \prm {mathatom}.
3764
3765\stopnewprimitive
3766
3767\startoldprimitive[title={\prm {everypar}}]
3768
3769When a paragraph starts this tokenlist is expanded before content is processed.
3770
3771\stopoldprimitive
3772
3773\startnewprimitive[title={\prm {everytab}}]
3774
3775This token list gets expanded every time we start a table cell in \prm {halign} or
3776\prm {valign}.
3777
3778\stopnewprimitive
3779
3780\startoldprimitive[title={\prm {everyvbox}}]
3781
3782This token list gets expanded every time we start a vertical box. Like \prm
3783{everyhbox} this is not that useful unless you are certain that there are no
3784nested boxes that don't need this treatment. Of course you can wipe this register
3785in this expansion, like:
3786
3787\starttyping
3788\everyvbox{\kern10pt\everyvbox{}}
3789\stoptyping
3790
3791\stopoldprimitive
3792
3793\startnewprimitive[title={\prm {exceptionpenalty}}]
3794
3795In exceptions we can indicate a penalty by \type {[digit]} in which case a
3796penalty is injected set by this primitive, multiplied by the digit.
3797
3798\stopnewprimitive
3799
3800\startoldprimitive[title={\prm {exhyphenchar}}]
3801
3802The character that is used as pre component of the related discretionary.
3803
3804\stopoldprimitive
3805
3806\startoldprimitive[title={\prm {exhyphenpenalty}}]
3807
3808The penalty injected after \type {-} or \type {\-} unless \prm {hyphenationmode}
3809is set to force the dedisated penalties.
3810
3811\stopoldprimitive
3812
3813\startnewprimitive[title={\prm {expand}}]
3814
3815Beware, this is not a prefix but a directive to ignore the protected characters of
3816the following macro.
3817
3818\startbuffer
3819\protected \def \testa{\the\scratchcounter}
3820           \edef\testb{\testa}
3821           \edef\testc{\expand\testa}
3822\stopbuffer
3823
3824\typebuffer
3825
3826The meaning of the three macros is:
3827
3828\startlines \getbuffer \tttf
3829\meaningfull\testa
3830\meaningfull\testb
3831\meaningfull\testc
3832\stoplines
3833
3834\stopnewprimitive
3835
3836\startnewprimitive[title={\prm {expandactive}}]
3837
3838This a bit of an outlier and mostly there for completeness.
3839
3840\startbuffer
3841                          \meaningasis~
3842\edef\foo{~}              \meaningasis\foo
3843\edef\foo{\expandactive~} \meaningasis\foo
3844\stopbuffer
3845
3846\typebuffer
3847
3848There seems to be no difference but the real meaning of the first \type {\foo} is
3849\quote {active character 126} while the second \type {\foo} \quote {protected
3850call ~} is.
3851
3852% \showluatokens\foo
3853
3854\startlines
3855\getbuffer
3856\stoplines
3857
3858Of course the definition of the active tilde is \CONTEXT\ specific and situation
3859dependent.
3860
3861\stopnewprimitive
3862
3863\startoldprimitive[title={\prm {expandafter}}]
3864
3865This original \TEX\ primitive stores the next token, does a one level expansion
3866of what follows it, which actually can be an not expandable token, and
3867reinjects the stored token in the input. Like:
3868
3869\starttyping
3870\expandafter\let\csname my weird macro name\endcsname{m w m n}
3871\stoptyping
3872
3873Without \prm {expandafter} the \prm {csname} primitive would have been let to
3874the left brace (effectively then a begin group). Actually in this particular case
3875the control sequence with the weird name is injected and when it didn't yet exist
3876it will get the meaning \prm {relax} so we sort of have two assignments in a
3877row then.
3878
3879\stopoldprimitive
3880
3881\startnewprimitive[title={\prm {expandafterpars}}]
3882
3883Here is another gobbler: the next token is reinjected after following spaces
3884and par tokens have been read. So:
3885
3886\startbuffer
3887[\expandafterpars 1 2]
3888[\expandafterpars 3
38894]
3890[\expandafterpars 5
3891
38926]
3893\stopbuffer
3894
3895\typebuffer
3896
3897gives us: \inlinebuffer, because empty lines are like \prm {par} and therefore
3898ignored.
3899
3900\stopnewprimitive
3901
3902\startnewprimitive[title={\prm {expandafterspaces}}]
3903
3904This is a gobbler: the next token is reinjected after following spaces have been
3905read. Here is a simple example:
3906
3907\startbuffer
3908[\expandafterspaces 1 2]
3909[\expandafterspaces 3
39104]
3911[\expandafterspaces 5
3912
39136]
3914\stopbuffer
3915
3916\typebuffer
3917
3918We get this typeset: \inlinebuffer, because a newline normally is configured to be
3919a space (and leading spaces in a line are normally being ingored anyway).
3920
3921\stopnewprimitive
3922
3923\startnewprimitive[title={\prm {expandcstoken}}]
3924
3925The rationale behind this primitive is that when we \prm {let} a single token
3926like a character it is hard to compare that with something similar, stored in a
3927macro. This primitive pushes back a single token alias created by \prm {let}
3928into the input.
3929
3930\startbuffer
3931\let\tempA + \meaning\tempA
3932
3933\let\tempB X \meaning\tempB \crlf
3934\let\tempC $ \meaning\tempC \par
3935
3936\edef\temp         {\tempA} \doifelse{\temp}{+}{Y}{N} \meaning\temp \crlf
3937\edef\temp         {\tempB} \doifelse{\temp}{X}{Y}{N} \meaning\temp \crlf
3938\edef\temp         {\tempC} \doifelse{\temp}{X}{Y}{N} \meaning\temp \par
3939
3940\edef\temp{\expandcstoken\tempA} \doifelse{\temp}{+}{Y}{N} \meaning\temp \crlf
3941\edef\temp{\expandcstoken\tempB} \doifelse{\temp}{X}{Y}{N} \meaning\temp \crlf
3942\edef\temp{\expandcstoken\tempC} \doifelse{\temp}{$}{Y}{N} \meaning\temp \par
3943
3944\doifelse{\expandcstoken\tempA}{+}{Y}{N}
3945\doifelse{\expandcstoken\tempB}{X}{Y}{N}
3946\doifelse{\expandcstoken\tempC}{$}{Y}{N} \par
3947\stopbuffer
3948
3949\typebuffer
3950
3951The meaning of the \prm {let} macros shows that we have a shortcut to a
3952character with (in this case) catcode letter, other (here \quote {other
3953character} gets abbreviated to \quote {character}), math shift etc.
3954
3955\start \tttf \getbuffer \stop
3956
3957Here we use the \CONTEXT\ macro \type {\doifelse} which can be implemented in
3958different ways, but the only property relevant to the user is that the expanded
3959content of the two arguments is compared.
3960
3961\stopnewprimitive
3962
3963\startnewprimitive[title={\prm {expanded}}]
3964
3965This primitive complements the two expansion related primitives mentioned in the
3966previous two sections. This time the content will be expanded and then pushed
3967back into the input. Protected macros will not be expanded, so you can use this
3968primitive to expand the arguments in a call. In \CONTEXT\ you need to use \type
3969{\normalexpanded} because we already had a macro with that name. We give some
3970examples:
3971
3972\startbuffer
3973\def\A{!}
3974          \def\B#1{\string#1}                          \B{\A}
3975          \def\B#1{\string#1} \normalexpanded{\noexpand\B{\A}}
3976\protected\def\B#1{\string#1}                          \B{\A}
3977\stopbuffer
3978
3979\typebuffer \startlines\getbuffer\stoplines
3980
3981\stopnewprimitive
3982
3983\startnewprimitive[title={\prm {expandedafter}}]
3984
3985The following two lines are equivalent:
3986
3987\startbuffer
3988\def\foo{123}
3989\expandafter[\expandafter[\expandafter\secondofthreearguments\foo]]
3990\expandedafter{[[\secondofthreearguments}\foo]]
3991\stopbuffer
3992
3993\typebuffer
3994
3995In \CONTEXT\ \MKIV\ the number of times that one has multiple \prm {expandafter}s
3996is much larger than in \CONTEXT\ \LMTX\ thanks to some of the new features in
3997\LUAMETATEX, and this primitive is not really used yet in the core code.
3998
3999\startlines\getbuffer\stoplines
4000
4001\stopnewprimitive
4002
4003\startnewprimitive[title={\prm {expandeddetokenize}}]
4004
4005This is a companion to \prm {detokenize} that expands its argument:
4006
4007\startbuffer
4008\def\foo{12#H3}
4009\def\oof{\foo}
4010\detokenize        {\foo} \detokenize        {\oof}
4011\expandeddetokenize{\foo} \expandeddetokenize{\oof}
4012\edef\ofo{\expandeddetokenize{\foo}} \meaningless\ofo
4013\edef\ofo{\expandeddetokenize{\oof}} \meaningless\ofo
4014\stopbuffer
4015
4016\typebuffer
4017
4018This is a bit more convenient than
4019
4020\starttyping
4021\detokenize \expandafter {\normalexpanded {\foo}}
4022\stoptyping
4023
4024kind of solutions. We get:
4025
4026\startlines
4027\getbuffer
4028\stoplines
4029
4030\stopnewprimitive
4031
4032\startnewprimitive[title={\prm {expandedendless}}]
4033
4034This one loops forever but because the loop counter is not set you need to find a
4035way to quit it.
4036
4037\stopnewprimitive
4038
4039\startnewprimitive[title={\prm {expandedloop}}]
4040
4041This variant of the previously introduced \prm {localcontrolledloop} doesn't
4042enter a local branch but immediately does its work. This means that it can be
4043used inside an expansion context like \prm {edef}.
4044
4045\startbuffer
4046\edef\whatever
4047  {\expandedloop 1 10 1
4048     {\scratchcounter=\the\currentloopiterator\relax}}
4049
4050\meaningasis\whatever
4051\stopbuffer
4052
4053\typebuffer
4054
4055\start \veryraggedright \tt\tfx \getbuffer \stop \blank
4056
4057\stopnewprimitive
4058
4059\startnewprimitive[title={\prm {expandedrepeat}}]
4060
4061This one takes one instead of three arguments which is sometimes more
4062convenient.
4063
4064\stopnewprimitive
4065
4066\startnewprimitive[title={\prm {expandparameter}}]
4067
4068This primitive is a predecessor of \prm {parameterdef} so we stick to a simple
4069example.
4070
4071\startbuffer
4072\def\foo#1#2%
4073  {\integerdef\MyIndexOne\parameterindex\plusone % 1
4074   \integerdef\MyIndexTwo\parameterindex\plustwo % 2
4075   \oof{P}\oof{Q}\oof{R}\norelax}
4076
4077\def\oof#1%
4078  {<1:\expandparameter\MyIndexOne><1:\expandparameter\MyIndexOne>%
4079   #1%
4080   <2:\expandparameter\MyIndexTwo><2:\expandparameter\MyIndexTwo>}
4081
4082\foo{A}{B}
4083\stopbuffer
4084
4085\typebuffer
4086
4087In principle the whole parameter stack can be accessed but often
4088one never knows if a specific macro is called nested. The original
4089idea behind this primitive was tracing but it can also be used to
4090avoid passing parameters along a chain of calls.
4091
4092\getbuffer
4093
4094\stopnewprimitive
4095
4096\startnewprimitive[title={\prm {expandtoken}}]
4097
4098This primitive creates a token with a specific combination of catcode and
4099character code. Because it assumes some knowledge of \TEX\ we can show it
4100using some \prm {expandafter} magic:
4101
4102\startbuffer
4103\expandafter\let\expandafter\temp\expandtoken 11 `X \meaning\temp
4104\expandafter\let\expandafter\temp\expandtoken 12 `X \meaning\temp
4105\stopbuffer
4106
4107\typebuffer
4108
4109The meanings are:
4110
4111\startlines \tttf \getbuffer \stoplines
4112
4113Using other catcodes is possible but the results of injecting them into the input
4114directly (or here by injecting \type {\temp}) can be unexpected because of what
4115\TEX\ expects. You can get messages you normally won't get, for instance about
4116unexpected alignment interference, which is a side effect of \TEX\ using some
4117catcode|/|character combinations as signals and there is no reason to change
4118those internals. That said:
4119
4120\startbuffer
4121\xdef\tempA{\expandtoken  9 `X} \meaning\tempA
4122\xdef\tempB{\expandtoken 10 `X} \meaning\tempB
4123\xdef\tempC{\expandtoken 11 `X} \meaning\tempC
4124\xdef\tempD{\expandtoken 12 `X} \meaning\tempD
4125\stopbuffer
4126
4127\typebuffer
4128
4129are all valid and from the meaning you cannot really deduce what's in there:
4130
4131\startlines \tttf \getbuffer \stoplines % grouped therefore xdef
4132
4133But you can be assured that:
4134
4135\startbuffer
4136[AB: \ifx\tempA\tempB Y\else N\fi]
4137[AC: \ifx\tempA\tempC Y\else N\fi]
4138[AD: \ifx\tempA\tempD Y\else N\fi]
4139[BC: \ifx\tempB\tempC Y\else N\fi]
4140[BD: \ifx\tempB\tempD Y\else N\fi]
4141[CD: \ifx\tempC\tempD Y\else N\fi]
4142\stopbuffer
4143
4144\typebuffer
4145
4146makes clear that they're different: \inlinebuffer, and in case you wonder, the
4147characters with catcode 10 are spaces, while those with code 9 are ignored.
4148
4149\stopnewprimitive
4150
4151\startnewprimitive[title={\prm {expandtoks}}]
4152
4153This is a more efficient equivalent of \prm {the} applied to a token register,
4154so:
4155
4156\startbuffer
4157\scratchtoks{just some tokens}
4158\edef\TestA{[\the       \scratchtoks]}
4159\edef\TestB{[\expandtoks\scratchtoks]}
4160[\the       \scratchtoks] [\TestA] \meaning\TestA
4161[\expandtoks\scratchtoks] [\TestB] \meaning\TestB
4162\stopbuffer
4163
4164\typebuffer
4165
4166does the expected:
4167
4168\startlines
4169\getbuffer
4170\stoplines
4171
4172The \prm {expandtoken} primitive avoid a copy into the input when there is no
4173need for it.
4174
4175\stopnewprimitive
4176
4177\startnewprimitive[title={\prm {explicitdiscretionary}}]
4178
4179This is the verbose alias for one of \TEX's single character control sequences:
4180\type {\-}.
4181
4182\stopnewprimitive
4183
4184\startnewprimitive[title={\prm {explicithyphenpenalty}}]
4185
4186The penalty injected after an automatic discretionary \type {\-}, when \prm
4187{hyphenationmode} enables this.
4188
4189\stopnewprimitive
4190
4191\startnewprimitive[title={\prm {explicititaliccorrection}}]
4192
4193This is the verbose alias for one of \TEX's single character control sequences:
4194\type {\/}. Italic correction is a character property specific to \TEX\ and the
4195concept is not present in modern font technologies. There is a callback that
4196hooks into this command so that a macro package can provide its own solution
4197to this (or alternatively it can assign values to the italic correction field.
4198
4199\stopnewprimitive
4200
4201\startnewprimitive[title={\prm {explicitspace}}]
4202
4203This is the verbose alias for one of \TEX's single character control sequences:
4204\type {\ }. A space is inserted with properties according the space related
4205variables. There is look|-|back involved in order to deal with space factors.
4206
4207When \prm {nospaces} is set to~1 no spaces are inserted, when its value is~2 a
4208zero space is inserted.
4209
4210\stopnewprimitive
4211
4212\startoldprimitive[title={\prm {fam}}]
4213
4214In a numeric context it returns the current family number, otherwise it sets the
4215given family. The number of families in a traditional engine is 16, in \LUATEX\
4216it is 256 and in \LUAMETATEX\ we have at most \cldcontext {tex . magicconstants .
4217max_n_of_math_families} families. A future version can lower that number when we
4218need more classes.
4219
4220\stopoldprimitive
4221
4222\startoldprimitive[title={\prm {fi}}]
4223
4224This traditional primitive is part of the condition testing mechanism and ends a
4225test. So, we have:
4226
4227\starttyping
4228\ifsomething ... \else ... \fi
4229\ifsomething ... \or ... \or ... \else ... \fi
4230\ifsomething ... \orelse \ifsometing  ... \else ... \fi
4231\ifsomething ... \or ... \orelse \ifsometing  ... \else ... \fi
4232\stoptyping
4233
4234The \prm {orelse} is new in \LUAMETATEX\ and a continuation like we find in
4235other programming languages (see later section).
4236
4237\stopoldprimitive
4238
4239\startoldprimitive[title={\prm {finalhyphendemerits}}]
4240
4241This penalty will be added to the penalty assigned to a breakpoint when that
4242break results in a pre|-|last line ending with a hyphen.
4243
4244\stopoldprimitive
4245
4246\startoldprimitive[title={\prm {firstmark}}][obsolete=yes]
4247
4248This is a reference to the first mark on the (split off) page, it gives back
4249tokens.
4250
4251\stopoldprimitive
4252
4253\startoldprimitive[title={\prm {firstmarks}}]
4254
4255This is a reference to the first mark with the given id (a number) on the (split
4256off) page, it gives back tokens.
4257
4258\stopoldprimitive
4259
4260\startnewprimitive[title={\prm {firstvalidlanguage}}]
4261
4262Language id's start at zero, which makes it the first valid language. You can set
4263this parameter to indicate the first language id that is actually a language. The
4264current value is \the \firstvalidlanguage, so lower values will not trigger
4265hyphenation.
4266
4267\stopnewprimitive
4268
4269\startnewprimitive[title={\prm {fitnessclasses}}]
4270
4271We can have more fitness classes than traditional \TEX\ that has \quote {very
4272loose}, \quote {loose}, \quote {decent} and \quote {tight}. In \CONTEXT\ we have
4273\quote {veryloose}, \quote {loose}, \quote {almostloose}, \quote {barelyloose},
4274\quote {decent}, \quote {barelytight}, \quote {almosttight}, \quote {tight} and
4275\quote {verytight}. Although we can go up to 31 this is already more than enough.
4276The default is the same as in regular \TEX.
4277
4278The \prm {fitnessclasses} can be used to set the criteria and like other
4279specification primitives (like \prm {parshape} and \prm {widowpenalties}, it
4280expects a count. With \prm {adjacentdemerits} one can set the demerits that are
4281added depending on the distance between classes (in traditional \TEX\ that is
4282\typ {adjdemerits} for all distances larger than one. With the double option the
4283demerits come in pairs because we can go up or down in the list of fitness
4284classes.
4285
4286\stopnewprimitive
4287
4288\startnewprimitive[title={\prm {float}}]
4289
4290In addition to integers and dimensions, which are fixed 16.16 integer floats we
4291also have \quote {native} floats, based on 32 bit posit unums.
4292
4293\startbuffer
4294\float0 = 123.456           \the\float0
4295\float2 = 123.456           \the\float0
4296\advance \float0 by 123.456 \the\float0
4297\advance \float0 by \float2 \the\float0
4298\divideby\float0 3          \the\float0
4299\stopbuffer
4300
4301\typebuffer
4302
4303They come with the same kind of support as the other numeric data types:
4304
4305\startlines \getbuffer \stoplines
4306
4307\startbuffer
4308\dimen00 = 123.456pt          \the\dimen0
4309\dimen02 = 123.456pt          \the\dimen0
4310\advance \dimen0 by 123.456pt \the\dimen0
4311\advance \dimen0 by \dimen2   \the\dimen0
4312\divideby\dimen0 3            \the\dimen0
4313\stopbuffer
4314
4315We leave the subtle differences between floats and dimensions to the user to
4316investigate:
4317
4318\typebuffer
4319
4320The nature of posits is that they are more accurate around zero (or smaller
4321numbers in general).
4322
4323\startlines \getbuffer \stoplines
4324
4325This also works:
4326
4327\startbuffer
4328\float0=123.456e4
4329\float2=123.456    \multiply\float2 by 10000
4330\the\float0
4331\the\float2
4332\stopbuffer
4333
4334\typebuffer
4335
4336The values are (as expected) the same:
4337
4338\startlines \getbuffer \stoplines
4339
4340\stopnewprimitive
4341
4342\startnewprimitive[title={\prm {floatdef}}]
4343
4344This primitive defines a symbolic (macro) alias to a float register, just like
4345\prm {countdef} and friends do.
4346
4347\stopnewprimitive
4348
4349\startnewprimitive[title={\prm {floatexpr}}]
4350
4351This is the companion of \prm {numexpr}, \prm {dimexpr} etc.
4352
4353\startbuffer
4354\scratchcounter 200
4355\the   \floatexpr 123.456/456.123     \relax
4356\the   \floatexpr 1.2*\scratchcounter \relax
4357\the   \floatexpr \scratchcounter/3   \relax
4358\number\floatexpr \scratchcounter/3   \relax
4359\stopbuffer
4360
4361\typebuffer
4362
4363Watch the difference between \prm {the} and \prm {number}:
4364
4365\startlines \getbuffer \stoplines
4366
4367\stopnewprimitive
4368
4369\startoldprimitive[title={\prm {floatingpenalty}}]
4370
4371When an insertion is split (across pages) this one is added to to accumulated
4372\prm {insertpenalties}. In \LUAMETATEX\ this penalty can be stored per insertion
4373class.
4374
4375\stopoldprimitive
4376
4377\startnewprimitive[title={\prm {flushmarks}}]
4378
4379This primitive is an addition to the multiple marks mechanism that originates in
4380\ETEX\ and inserts a reset signal for the mark given category that will perform a
4381clear operation (like \prm {clearmarks} which operates immediately).
4382
4383\stopnewprimitive
4384
4385\startnewprimitive[title={\prm {flushmvl}}]
4386
4387This returns a vertical box with the content of the accumulated mvl list (see
4388\prm {beginmvl}).
4389
4390\stopnewprimitive
4391
4392\startoldprimitive[title={\prm {font}}]
4393
4394This primitive is either a symbolic reference to the current font or in the
4395perspective of an assignment is used to trigger a font definitions with a given
4396name (\type {cs}) and specification. In \LUAMETATEX\ the assignment will trigger
4397a callback that then handles the definition; in addition to the filename an
4398optional size specifier is checked (\type {at} or \type {scaled}).
4399
4400In \LUAMETATEX\ {\em all} font loading is delegated to \LUA, and there is no
4401loading code built in the engine. Also, instead of \prm {font} in \CONTEXT\ one
4402uses dedicated and more advanced font definition commands.
4403
4404\stopoldprimitive
4405
4406\startnewprimitive[title={\prm {fontcharba}}]
4407
4408Fetches the bottom anchor of a character in the given font, so:
4409
4410\startbuffer
4411\the\fontcharba\textfont0 "222B
4412\stopbuffer
4413
4414results in: \inlinebuffer. However, this anchor is only available when it is set
4415and it is not part of \OPENTYPE; it is something that \CONTEXT\ provides for math
4416fonts.
4417
4418\stopnewprimitive
4419
4420\startoldprimitive[title={\prm {fontchardp}}]
4421
4422Fetches the depth of a character in the given font, so:
4423
4424\startbuffer
4425\the\fontchardp\font`g
4426\stopbuffer
4427
4428results in: \inlinebuffer.
4429
4430\stopoldprimitive
4431
4432\startoldprimitive[title={\prm {fontcharht}}]
4433
4434Fetches the width of a character in the given font, so:
4435
4436\startbuffer
4437\the\fontcharht\font`g
4438\stopbuffer
4439
4440results in: \inlinebuffer.
4441
4442\stopoldprimitive
4443
4444\startoldprimitive[title={\prm {fontcharic}}]
4445
4446Fetches the italic correction of a character in the given font, but because it is
4447not an \OPENTYPE\ property it is unlikely to return something useful. Although
4448math fonts have such a property in \CONTEXT\ we deal with it differently.
4449
4450\stopoldprimitive
4451
4452\startnewprimitive[title={\prm {fontcharta}}]
4453
4454Fetches the top anchor of a character in the given font, so:
4455
4456\startbuffer
4457\the\fontcharba\textfont0 "222B
4458\stopbuffer
4459
4460results in: \inlinebuffer. This is a specific property of math characters because
4461in text mark anchoring is driven by a feature.
4462
4463\stopnewprimitive
4464
4465\startoldprimitive[title={\prm {fontcharwd}}]
4466
4467Fetches the width of a character in the given font, so:
4468
4469\startbuffer
4470\the\fontcharwd\font`g
4471\stopbuffer
4472
4473results in: \inlinebuffer.
4474
4475\stopoldprimitive
4476
4477\startoldprimitive[title={\prm {fontdimen}}][obsolete=yes]
4478
4479A traditional \TEX\ font has a couple of font specific dimensions, we only
4480mention the seven that come with text fonts:
4481
4482\startitemize[n,packed]
4483\startitem
4484    The slant (slope) is an indication that we have an italic shape. The value
4485    divided by 65.536 is a fraction that can be compared with for instance the
4486    \type {slanted} operator in \METAPOST. It is used for positioning accents, so
4487    actually not limited to oblique fonts (just like italic correction can be a
4488    property of any character). It is not relevant in the perspective of
4489    \OPENTYPE\ fonts where we have glyph specific top and bottom anchors.
4490\stopitem
4491\startitem
4492    Unless is it overloaded by \prm {spaceskip} this determines the space between
4493    words (or actually anything separated by a space).
4494\stopitem
4495\startitem
4496    This is the stretch component of \prm {fontdimen}~2(space).
4497\startitem
4498    This is the shrink component of \prm {fontdimen}~2(space).
4499\stopitem
4500\startitem
4501    The so called ex|-|height is normally the height of the \quote {x} and is
4502    also accessible as \type {em} unit.
4503\stopitem
4504\startitem
4505    The so called em|-|width or in \TEX\ speak quad width is about the with of an
4506    \quote {M} but in many fonts just matches the font size. It is also
4507    accessible as \type {em} unit.
4508\stopitem
4509\startitem
4510    This is a very \TEX\ specific property also known as extra space. It gets
4511    {\em added} to the regular space after punctuation when \prm {spacefactor} is
4512    2000 or more. It can be overloaded by \prm {xspaceskip}.
4513\stopitem
4514\stopitemize
4515
4516This primitive expects a a number and a font identifier. Setting a font dimension
4517is a global operation as it directly pushes the value in the font resource.
4518
4519\stopoldprimitive
4520
4521\startnewprimitive[title={\prm {fontid}}]
4522
4523Returns the (internal) number associated with the given font:
4524
4525\startbuffer
4526{\bf \xdef\MyFontA{\the\fontid\font}}
4527{\sl \xdef\MyFontB{\setfontid\the\fontid\font}}
4528\stopbuffer
4529
4530\typebuffer \getbuffer
4531
4532with:
4533
4534\startbuffer
4535test {\setfontid\MyFontA test} test {\MyFontB test} test
4536\stopbuffer
4537
4538\typebuffer
4539
4540gives: \inlinebuffer.
4541
4542\stopnewprimitive
4543
4544\startnewprimitive[title={\prm {fontidentifier}}]
4545
4546This one is just there for completeness: it reports the string used to identify a
4547font when logging. Compare:
4548
4549\starttabulate
4550\NC \type {\fontname      \font} \NC \fontname      \font \NC \NR
4551\NC \type {\fontidentifier\font} \NC \fontidentifier\font \NC \NR
4552\NC \type {\the\fontid    \font} \NC \the\fontid    \font \NC \NR
4553\stoptabulate
4554
4555\stopnewprimitive
4556
4557\startnewprimitive[title={\prm {fontmathcontrol}}]
4558
4559The \prm {mathfontcontrol} parameter controls how the engine deals with specific
4560font related properties and possibilities. It is set at the \TEX\ end. It makes
4561it possible to fine tune behavior in this mixed traditional and not perfect
4562\OPENTYPE\ math font arena. One can also set this bitset when initializing
4563(loading) the font (at the \LUA\ end) and the value set there is available in
4564\prm {fontmathcontrol}. The bits set in the font win over those in \prm
4565{mathfontcontrol}. There are a few cases where we set these options in the (so
4566called) goodie files. For instance we ignore font kerns in Libertinus, Antykwa
4567and some more.
4568
4569\starttabulate[|l|rT|]
4570\NC modern     \NC \bgroup\switchtobodyfont    [modern]\normalexpanded{\egroup 0x\tohexadecimal\fontmathcontrol\textfont\fam} \NC \NR
4571\NC pagella    \NC \bgroup\switchtobodyfont   [pagella]\normalexpanded{\egroup 0x\tohexadecimal\fontmathcontrol\textfont\fam} \NC \NR
4572\NC antykwa    \NC \bgroup\switchtobodyfont   [antykwa]\normalexpanded{\egroup 0x\tohexadecimal\fontmathcontrol\textfont\fam} \NC \NR
4573\NC libertinus \NC \bgroup\switchtobodyfont[libertinus]\normalexpanded{\egroup 0x\tohexadecimal\fontmathcontrol\textfont\fam} \NC \NR
4574\stoptabulate
4575
4576\stopnewprimitive
4577
4578\startoldprimitive[title={\prm {fontname}}]
4579
4580Depending on how the font subsystem is implemented this gives some information
4581about the used font:
4582
4583\startbuffer
4584{\tf \fontname\font}
4585{\bf \fontname\font}
4586{\sl \fontname\font}
4587\stopbuffer
4588
4589\typebuffer
4590
4591\startlines
4592\getbuffer
4593\stoplines
4594
4595\stopoldprimitive
4596
4597\startnewprimitive[title={\prm {fontspecdef}}]
4598
4599This primitive creates a reference to a specification that when triggered will
4600change multiple parameters in one go.
4601
4602\starttyping
4603\fontspecdef\MyFontSpec
4604    \fontid\font
4605    scale  1200
4606    xscale 1100
4607    yscale  800
4608    weight  200
4609    slant   500
4610\relax
4611\stoptyping
4612
4613is equivalent to:
4614
4615\starttyping
4616\fontspecdef\MyFontSpec
4617    \fontid\font
4618    all 1200 1100 800 200 500
4619\relax
4620\stoptyping
4621
4622while
4623
4624\starttyping
4625\fontspecdef\MyFontSpec
4626    \fontid\font
4627    all \glyphscale \glyphxscale \glyphyscale \glyphslant \glyphweight
4628\relax
4629\stoptyping
4630
4631is the same as
4632
4633\starttyping
4634\fontspecdef\MyFontSpec
4635    \fontid\font
4636\relax
4637\stoptyping
4638
4639The engine adapts itself to these glyph parameters but when you access certain
4640quantities you have to make sure that you use the scaled ones. The same is true
4641at the \LUA\ end. This is somewhat fundamental in the sense that when one uses
4642these sort of dynamic features one also need to keep an eye on code that uses
4643font specific dimensions.
4644
4645\stopnewprimitive
4646
4647\startnewprimitive[title={\prm {fontspecid}}]
4648
4649Internally a font reference is a number and this primitive returns the number of
4650the font bound to the specification.
4651
4652\stopnewprimitive
4653
4654\startnewprimitive[title={\prm {fontspecifiedname}}]
4655
4656Depending on how the font subsystem is implemented this gives some information
4657about the (original) definition of the used font:
4658
4659\startbuffer
4660{\tf \fontspecifiedname\font}
4661{\bf \fontspecifiedname\font}
4662{\sl \fontspecifiedname\font}
4663\stopbuffer
4664
4665\typebuffer
4666
4667\startlines
4668\getbuffer
4669\stoplines
4670
4671\stopnewprimitive
4672
4673\startnewprimitive[title={\prm {fontspecifiedsize}}]
4674
4675Depending on how the font subsystem is implemented this gives some information
4676about the (original) size of the used font:
4677
4678\startbuffer
4679{\tf  \the\fontspecifiedsize\font : \the\glyphscale}
4680{\bfa \the\fontspecifiedsize\font : \the\glyphscale}
4681{\slx \the\fontspecifiedsize\font : \the\glyphscale}
4682\stopbuffer
4683
4684\typebuffer
4685
4686Depending on how the font system is setup, this is not the real value that is
4687used in the text because we can use for instance \prm {glyphscale}. So the next
4688lines depend on what font mode this document is typeset.
4689
4690\startlines
4691\getbuffer
4692\stoplines
4693
4694\stopnewprimitive
4695
4696\startnewprimitive[title={\prm {fontspecscale}}]
4697
4698This returns the scale factor of a fontspec where as usual 1000 means scaling
4699by~1.
4700
4701\stopnewprimitive
4702
4703\startnewprimitive[title={\prm {fontspecslant}}]
4704
4705This returns the slant factor of a font specification, usually between zero and
47061000 with 1000 being maximum slant.
4707
4708\stopnewprimitive
4709
4710\startnewprimitive[title={\prm {fontspecweight}}]
4711
4712This returns the weight of the font specification. Reasonable values are between
4713zero and 500.
4714
4715\stopnewprimitive
4716
4717\startnewprimitive[title={\prm {fontspecxscale}}]
4718
4719This returns the scale factor of a font specification where as usual 1000 means
4720scaling by~1.
4721
4722\stopnewprimitive
4723
4724\startnewprimitive[title={\prm {fontspecyscale}}]
4725
4726This returns the scale factor of a font specification where as usual 1000 means
4727scaling by~1.
4728
4729\stopnewprimitive
4730
4731\startnewprimitive[title={\prm {fonttextcontrol}}]
4732
4733This returns the text control flags that are set on the given font, here {\tttf
47340x\tohexadecimal \fonttextcontrol \font}. Bits that can be set are:
4735
4736\getbuffer[engine:syntax:textcontrolcodes]
4737
4738\stopnewprimitive
4739
4740\startnewprimitive[title={\prm {forcedleftcorrection}}]
4741
4742This is a callback driven left correction signal similar to italic corrections.
4743
4744\stopnewprimitive
4745
4746\startnewprimitive[title={\prm {forcedrightcorrection}}]
4747
4748This is a callback driven right correction signal similar to italic corrections.
4749
4750\stopnewprimitive
4751
4752\startnewprimitive[title={\prm {formatname}}]
4753
4754It is in the name: {\tttf \filenameonly {\formatname}}, but we cheat here by only
4755showing the filename and not the full path, which in a \CONTEXT\ setup can span
4756more than a line in this paragraph.
4757
4758\stopnewprimitive
4759
4760\startnewprimitive[title={\prm {frozen}}]
4761
4762You can define a macro as being frozen:
4763
4764\starttyping
4765\frozen\def\MyMacro{...}
4766\stoptyping
4767
4768When you redefine this macro you get an error:
4769
4770\starttyping
4771! You can't redefine a frozen macro.
4772\stoptyping
4773
4774This is a prefix like \prm {global} and it can be combined with other prefixes.
4775\footnote {The \prm {outer} and \prm {long} prefixes are no|-|ops in
4776\LUAMETATEX\ and \LUATEX\ can be configured to ignore them.}
4777
4778\stopnewprimitive
4779
4780\startnewprimitive[title={\prm {futurecsname}}]
4781
4782In order to make the repertoire of \type {def}, \type {let} and \type {futurelet}
4783primitives complete we also have:
4784
4785\starttyping
4786\futurecsname MyMacro:1\endcsname\MyAction
4787\stoptyping
4788
4789\stopnewprimitive
4790
4791\startnewprimitive[title={\prm {futuredef}}]
4792
4793We elaborate on the example of using \prm {futurelet} in the previous section.
4794Compare that one with the next:
4795
4796\startbuffer
4797\def\MySpecialToken{[}
4798\def\DoWhatever{\ifx\NextToken\MySpecialToken YES\else NOP\fi : }
4799\futurelet\NextToken\DoWhatever [A]\crlf
4800\futurelet\NextToken\DoWhatever (A)\par
4801\stopbuffer
4802
4803\typebuffer
4804
4805This time we get:
4806
4807{\getbuffer}
4808
4809It is for that reason that we now also have \prm {futuredef}:
4810
4811\startbuffer
4812\def\MySpecialToken{[}
4813\def\DoWhatever{\ifx\NextToken\MySpecialToken YES\else NOP\fi : }
4814\futuredef\NextToken\DoWhatever [A]\crlf
4815\futuredef\NextToken\DoWhatever (A)\par
4816\stopbuffer
4817
4818\typebuffer
4819
4820So we're back to what we want:
4821
4822{\getbuffer}
4823
4824\stopnewprimitive
4825
4826\startnewprimitive[title={\prm {futureexpand}}]
4827
4828This primitive can be used as an alternative to a \prm {futurelet} approach,
4829which is where the name comes from. \footnote {In the engine primitives
4830that have similar behavior are grouped in commands that are then dealt with
4831together, code wise.}
4832
4833\startbuffer
4834\def\variantone<#1>{(#1)}
4835\def\varianttwo#1{[#1]}
4836\futureexpand<\variantone\varianttwo<one>
4837\futureexpand<\variantone\varianttwo{two}
4838\stopbuffer
4839
4840\typebuffer
4841
4842So, the next token determines which of the two variants is taken:
4843
4844{\getbuffer}
4845
4846Because we look ahead there is some magic involved: spaces are ignored but when
4847we have no match they are pushed back into the input. The next variant
4848demonstrates this:
4849
4850\startbuffer
4851\def\variantone<#1>{(#1)}
4852\def\varianttwo{}
4853\def\temp{\futureexpand<\variantone\varianttwo}
4854[\temp <one>]
4855[\temp {two}]
4856[\expandafter\temp\space <one>]
4857[\expandafter\temp\space {two}]
4858\stopbuffer
4859
4860\typebuffer
4861
4862This gives us:
4863
4864{\getbuffer}
4865
4866\stopnewprimitive
4867
4868\startnewprimitive[title={\prm {futureexpandis}}]
4869
4870We assume that the previous section is read. This variant will not push back
4871spaces, which permits a consistent approach i.e.\ the user can assume that macro
4872always gobbles the spaces.
4873
4874\startbuffer
4875\def\variantone<#1>{(#1)}
4876\def\varianttwo{}
4877\def\temp{\futureexpandis<\variantone\varianttwo}
4878[\temp <one>]
4879[\temp {two}]
4880[\expandafter\temp\space <one>]
4881[\expandafter\temp\space {two}]
4882\stopbuffer
4883
4884\typebuffer
4885
4886So, here no spaces are pushed back. This \type {is} in the name of this primitive
4887means \quote {ignore spaces}, but having that added to the name would have made
4888the primitive even more verbose (after all, we also don't have \type
4889{\expandeddef} but \prm {edef} and no \type {\globalexpandeddef} but \prm
4890{xdef}.
4891
4892{\getbuffer}
4893
4894\stopnewprimitive
4895
4896\startnewprimitive[title={\prm {futureexpandisap}}]
4897
4898This primitive is like the one in the previous section but also ignores par
4899tokens, so \type {isap} means \quote {ignore spaces and paragraphs}.
4900
4901\stopnewprimitive
4902
4903\startoldprimitive[title={\prm {futurelet}}]
4904
4905The original \TEX\ primitive \prm {futurelet} can be used to create an alias to a next token,
4906push it back into the input and then expand a given token.
4907
4908\startbuffer
4909\let\MySpecialTokenL[
4910\let\MySpecialTokenR] % nicer for checker
4911\def\DoWhatever{\ifx\NextToken\MySpecialTokenL YES\else NOP\fi : }
4912\futurelet\NextToken\DoWhatever [A]\crlf
4913\futurelet\NextToken\DoWhatever (A)\par
4914\stopbuffer
4915
4916\typebuffer
4917
4918This is typically the kind of primitive that most users will never use because it
4919expects a sane follow up handler (here \type {\DoWhatever}) and therefore is
4920related to user interfacing.
4921
4922{\getbuffer}
4923
4924\stopoldprimitive
4925
4926\startoldprimitive[title={\prm {gdef}}]
4927
4928The is the global companion of \prm {def}.
4929
4930\stopoldprimitive
4931
4932\startnewprimitive[title={\prm {gdefcsname}}]
4933
4934As with standard \TEX\ we also define global ones:
4935
4936\starttyping
4937\expandafter\gdef\csname MyMacro:1\endcsname{...}
4938             \gdefcsname MyMacro:1\endcsname{...}
4939\stoptyping
4940
4941\stopnewprimitive
4942
4943\startnewprimitive[title={\prm {givenmathstyle}}]
4944
4945This primitive expects a math style and returns it when valid or otherwise issues
4946an error.
4947
4948\stopnewprimitive
4949
4950\startnewprimitive[title={\prm {gleaders}}]
4951
4952Leaders are glue with special property: a box, rule of (in \LUAMETATEX) glyph, like:
4953
4954\startlines
4955x\leaders   \glyph `M \hfill  x
4956xx\leaders  \glyph `M \hfill xx
4957
4958x\cleaders  \glyph `M \hfill x
4959xx\cleaders \glyph `M \hfill xx
4960
4961x\xleaders  \glyph `M \hfill x
4962xx\xleaders \glyph `M \hfill xx
4963
4964x\gleaders  \glyph `M \hfill x
4965xx\gleaders \glyph `M \hfill xx
4966\stoplines
4967
4968Leaders fill the available space. The \prm {leaders} command starts at the left
4969edge and stops when there is no more space. The blobs get centered when we use
4970\prm {cleaders}: excess space is distributed before and after a blob while \prm
4971{xleaders} also puts space between the blobs.
4972
4973When a rule is given the advance (width or height and depth) is ignored, so these
4974are equivalent.
4975
4976\starttyping
4977x\leaders \hrule           \hfill x
4978x\leaders \hrule width 1cm \hfill x
4979\stoptyping
4980
4981When a box is used one will normally have some alignment in that box.
4982
4983\starttyping
4984x\leaders \hbox {\hss.\hss} \hfill            x
4985x\leaders \hbox {\hss.\hss} \hskip 6cm \relax x
4986\stoptyping
4987
4988The reference point is the left edge of the current (outer) box and the effective
4989glue (when it has stretch or shrink) depends on that box. The \prm {gleaders}
4990variant takes the page as reference. That makes it possible to \quote {align}
4991across boxes.
4992
4993\stopnewprimitive
4994
4995\startnewprimitive[title={\prm {glet}}]
4996
4997This is the global companion of \prm {let}. The fact that it is not an original
4998primitive is probably due to the expectation for it not it not being used (as)
4999often (as in \CONTEXT).
5000
5001\stopnewprimitive
5002
5003\startnewprimitive[title={\prm {gletcsname}}]
5004
5005Naturally \LUAMETATEX\ also provides a global variant:
5006
5007\starttyping
5008\expandafter\global\expandafter\let\csname MyMacro:1\endcsname\relax
5009\expandafter                  \glet\csname MyMacro:1\endcsname\relax
5010                               \gletcsname MyMacro:1\endcsname\relax
5011\stoptyping
5012
5013So, here we save even more.
5014
5015\stopnewprimitive
5016
5017\startnewprimitive[title={\prm {glettonothing}}]
5018
5019This is the global companion of \prm {lettonothing}.
5020
5021\stopnewprimitive
5022
5023\startoldprimitive[title={\prm {global}}]
5024
5025This is one of the original prefixes that can be used when we define a macro of
5026change some register.
5027
5028\starttyping
5029\bgroup
5030       \def\MyMacroA{a}
5031\global\def\MyMacroB{a}
5032      \gdef\MyMacroC{a}
5033\egroup
5034\stoptyping
5035
5036The macro defined in the first line is forgotten when the groups is left. The
5037second and third definition are both global and these definitions are retained.
5038
5039\stopoldprimitive
5040
5041\startoldprimitive[title={\prm {globaldefs}}]
5042
5043When set to a positive value, this internal integer will force all definitions to
5044be global, and in a complex macro package that is not something a user will do
5045unless it is very controlled.
5046
5047\stopoldprimitive
5048
5049\startoldprimitive[title={\prm {glueexpr}}]
5050
5051This is a more extensive variant of \prm {dimexpr} that also handles the optional
5052stretch and shrink components.
5053
5054\stopoldprimitive
5055
5056\startoldprimitive[title={\prm {glueshrink}}]
5057
5058This returns the shrink component of a glue quantity. The result is a dimension
5059so you need to apply \prm {the} when applicable.
5060
5061\stopoldprimitive
5062
5063\startoldprimitive[title={\prm {glueshrinkorder}}]
5064
5065This returns the shrink order of a glue quantity. The result is a integer so you
5066need to apply \prm {the} when applicable.
5067
5068\stopoldprimitive
5069
5070\startnewprimitive[title={\prm {gluespecdef}}]
5071
5072A variant of \prm {integerdef} and \prm {dimensiondef} is:
5073
5074\starttyping
5075\gluespecdef\MyGlue = 3pt plus 2pt minus 1pt
5076\stoptyping
5077
5078The properties are comparable to the ones described in the previous sections.
5079
5080\stopnewprimitive
5081
5082\startoldprimitive[title={\prm {gluestretch}}]
5083
5084This returns the stretch component of a glue quantity. The result is a dimension
5085so you need to apply \prm {the} when applicable.
5086
5087\stopoldprimitive
5088
5089\startoldprimitive[title={\prm {gluestretchorder}}]
5090
5091This returns the stretch order of a glue quantity. The result is a integer so you
5092need to apply \prm {the} when applicable.
5093
5094\stopoldprimitive
5095
5096\startoldprimitive[title={\prm {gluetomu}}]
5097
5098The sequence \typ {\the \gluetomu 20pt plus 10pt minus 5pt} gives \the \gluetomu
509920pt plus 10pt minus 5pt.
5100
5101\stopoldprimitive
5102
5103\startnewprimitive[title={\prm {glyph}}]
5104
5105This is a more extensive variant of \prm {char} that permits setting some
5106properties if the injected character node.
5107
5108\startbuffer
5109\ruledhbox{\glyph
5110    scale 2000 xscale 9000 yscale 1200
5111    slant 700 weight 200
5112    xoffset 10pt yoffset -5pt left 10pt right 20pt
5113    123}
5114\quad
5115\ruledhbox{\glyph
5116    scale 2000 xscale 9000 yscale 1200
5117    slant 700 weight 200
5118    125}
5119\stopbuffer
5120
5121\typebuffer
5122
5123In addition one can specify \type {font} (symbol), \type {id} (valid font id
5124number), an \type {options} (bit set) and \type {raise}.
5125
5126\startlinecorrection
5127\dontleavehmode\getbuffer
5128\stoplinecorrection
5129
5130When no parameters are set, the current ones are used. More details and examples
5131of usage can be found in the \CONTEXT\ distribution.
5132
5133\stopnewprimitive
5134
5135\startnewprimitive[title={\prm {glyphdatafield}}]
5136
5137The value of this parameter is assigned to data field in glyph nodes that get
5138injected. It has no meaning in itself but can be used at the \LUA\ end.
5139
5140\stopnewprimitive
5141
5142\startnewprimitive[title={\prm {glyphoptions}}]
5143
5144The value of this parameter is assigned to the options field in glyph nodes that
5145get injected.
5146
5147\starttworows
5148\getbuffer[engine:syntax:glyphoptions]
5149\stoptworows
5150
5151\stopnewprimitive
5152
5153\startnewprimitive[title={\prm {glyphscale}}]
5154
5155An integer parameter defining the current glyph scale, assigned to glyphs
5156(characters) inserted into the current list.
5157
5158\stopnewprimitive
5159
5160\startnewprimitive[title={\prm {glyphscriptfield}}]
5161
5162The value of this parameter is assigned to script field in glyph nodes that get
5163injected. It has no meaning in itself but can be used at the \LUA\ end.
5164
5165\stopnewprimitive
5166
5167\startnewprimitive[title={\prm {glyphscriptscale}}]
5168
5169This multiplier is applied to text font and glyph dimension properties when script
5170style is used.
5171
5172\stopnewprimitive
5173
5174\startnewprimitive[title={\prm {glyphscriptscriptscale}}]
5175
5176This multiplier is applied to text font and glyph dimension properties when
5177script script style is used.
5178
5179\stopnewprimitive
5180
5181\startnewprimitive[title={\prm {glyphslant}}]
5182
5183An integer parameter defining the current glyph slant, assigned to glyphs
5184(characters) inserted into the current list.
5185
5186\stopnewprimitive
5187
5188\startnewprimitive[title={\prm {glyphstatefield}}]
5189
5190The value of this parameter is assigned to script state in glyph nodes that get
5191injected. It has no meaning in itself but can be used at the \LUA\ end.
5192
5193\stopnewprimitive
5194
5195\startnewprimitive[title={\prm {glyphtextscale}}]
5196
5197This multiplier is applied to text font and glyph dimension properties when text
5198style is used.
5199
5200\stopnewprimitive
5201
5202\startnewprimitive[title={\prm {glyphweight}}]
5203
5204An integer parameter defining the current glyph weight, assigned to glyphs
5205(characters) inserted into the current list.
5206
5207\stopnewprimitive
5208
5209\startnewprimitive[title={\prm {glyphxoffset}}]
5210
5211An integer parameter defining the current glyph x offset, assigned to glyphs
5212(characters) inserted into the current list. Normally this will only be set when
5213one explicitly works with glyphs and defines a specific sequence.
5214
5215\stopnewprimitive
5216
5217\startnewprimitive[title={\prm {glyphxscale}}]
5218
5219An integer parameter defining the current glyph x scale, assigned to glyphs
5220(characters) inserted into the current list.
5221
5222\stopnewprimitive
5223
5224\startnewprimitive[title={\prm {glyphxscaled}}]
5225
5226This primitive returns the given dimension scaled by the \prm {glyphscale} and
5227\prm {glyphxscale}.
5228
5229\stopnewprimitive
5230
5231\startnewprimitive[title={\prm {glyphyoffset}}]
5232
5233An integer parameter defining the current glyph x offset, assigned to glyphs
5234(characters) inserted into the current list. Normally this will only be set when
5235one explicitly works with glyphs and defines a specific sequence.
5236
5237\stopnewprimitive
5238
5239\startnewprimitive[title={\prm {glyphyscale}}]
5240
5241An integer parameter defining the current glyph y scale, assigned to glyphs
5242(characters) inserted into the current list.
5243
5244\stopnewprimitive
5245
5246\startnewprimitive[title={\prm {glyphyscaled}}]
5247
5248This primitive returns the given dimension scaled by the \prm {glyphscale} and
5249\prm {glyphyscale}.
5250
5251\stopnewprimitive
5252
5253\startnewprimitive[title={\prm {gtoksapp}}]
5254
5255This is the global variant of \prm {toksapp}.
5256
5257\stopnewprimitive
5258
5259\startnewprimitive[title={\prm {gtokspre}}]
5260
5261This is the global variant of \prm {tokspre}.
5262
5263\stopnewprimitive
5264
5265\startoldprimitive[title={\prm {halign}}]
5266
5267This command starts horizontally aligned material. Macro packages use this
5268command in table mechanisms and math alignments. It starts with a preamble
5269followed by entries (rows and columns). There are some related primitives, for
5270instance \prm {alignmark} duplicates the functionality of \type {#} inside
5271alignment preambles, while \prm {aligntab} duplicates the functionality of \type
5272{&}. The \prm {aligncontent} primitive directly refers to an entry so that one
5273does not get repeated.
5274
5275Alignments can be traced with \prm {tracingalignments}. When set to~1 basics
5276usage is shown, for instance of \prm {noalign} but more interesting is~2 or more:
5277you then get the preambles reported.
5278
5279The \prm {halign} (tested) and \prm {valign} (yet untested) primitives accept a
5280few keywords in addition to \type {to} and \type {spread}:
5281
5282\starttabulate[|l|p|]
5283\FL
5284\BC keyword          \BC explanation \NC \NR
5285\TL
5286\NC \type {attr}     \NC set the given attribute to the given value \NC \NR
5287\NC \type {callback} \NC trigger the \type {alignment_filter} callback \NC \NR
5288\NC \type {discard}  \NC discard zero \prm {tabskip}'s \NC \NR
5289\NC \type {noskips}  \NC don't even process zero \prm {tabskip}'s \NC \NR
5290\NC \type {reverse}  \NC reverse the final rows \NC \NR
5291\LL
5292\stoptabulate
5293
5294In the preamble the \prm {tabsize} primitive can be used to set the width of a
5295column. By doing so one can avoid using a box in the preamble which, combined
5296with the sparse tabskip features, is a bit easier on memory when you produce
5297tables that span hundreds of pages and have a dozen columns.
5298
5299The \prm {everytab} complements the \prm {everycr} token register but is sort of
5300experimental as it might become more selective and powerful some day.
5301
5302The two primitives \prm {alignmentcellsource} and \prm {alignmentwrapsource} that
5303associate a source id (integer) to the current cell and row (line). Sources and
5304targets are experimental and are being explored in \CONTEXT\ so we'll see where
5305that ends up in.
5306
5307\stopoldprimitive
5308
5309\startoldprimitive[title={\prm {hangafter}}]
5310
5311This parameter tells the par builder when indentation specified with \prm
5312{hangindent} starts. A negative value does the opposite and starts indenting
5313immediately. So, a value of $-2$ will make the first two lines indent.
5314
5315\stopoldprimitive
5316
5317\startoldprimitive[title={\prm {hangindent}}]
5318
5319This parameter relates to \prm {hangafter} and sets the amount of indentation.
5320When larger than zero indentation happens left, otherwise it starts at the right
5321edge.
5322
5323\stopoldprimitive
5324
5325\startoldprimitive[title={\prm {hbadness}}]
5326
5327This sets the threshold for reporting a horizontal badness value, its current
5328value is \the \badness.
5329
5330\stopoldprimitive
5331
5332\startnewprimitive[title={\prm {hbadnessmode}}]
5333
5334This parameter determines what gets reported when the (in the horizontal packer)
5335badness exceeds some limit. The current value of this bitset is {\tt
5336"\tohexadecimal \hbadnessmode}.
5337
5338\startfourrows
5339\getbuffer[engine:syntax:badnessmodecodes]
5340\stopfourrows
5341
5342\stopnewprimitive
5343
5344\startoldprimitive[title={\prm {hbox}}]
5345
5346This constructs a horizontal box. There are a lot of optional parameters so more
5347details can be found in dedicated manuals. When the content is packed a callback
5348can kick in that can be used to apply for instance font features.
5349
5350\stopoldprimitive
5351
5352\startnewprimitive[title={\prm {hccode}}]
5353
5354The \TEX\ engine is good at hyphenating but traditionally that has been limited
5355to hyphens. Some languages however use different characters. You can set up a
5356different \prm {hyphenchar} as well as pre and post characters, but there's also
5357a dedicated code for controlling this.
5358
5359\startbuffer
5360\hccode"2013 "2013
5361
5362\hsize 50mm test\char"2013test\par
5363\hsize  1mm test\char"2013test\par
5364
5365\hccode"2013 `!
5366
5367\hsize 50mm test\char"2013test\par
5368\hsize  1mm test\char"2013test\par
5369\stopbuffer
5370
5371\typebuffer
5372
5373This example shows that we can mark a character as hyphen|-|like but also can
5374remap it to something else:
5375
5376\startpacked \getbuffer \stoppacked
5377
5378\stopnewprimitive
5379
5380\startoldprimitive[title={\prm {hfil}}]
5381
5382This is a shortcut for \typ {\hskip plus 1 fil} (first order filler).
5383
5384\stopoldprimitive
5385
5386\startoldprimitive[title={\prm {hfill}}]
5387
5388This is a shortcut for \typ {\hskip plus 1 fill} (second order filler).
5389
5390\stopoldprimitive
5391
5392\startoldprimitive[title={\prm {hfilneg}}]
5393
5394This is a shortcut for \typ {\hskip plus - 1 fil} so it can compensate \prm
5395{hfil}.
5396
5397\stopoldprimitive
5398
5399\startoldprimitive[title={\prm {hfuzz}}]
5400
5401This dimension sets the threshold for reporting horizontal boxes that are under-
5402or overfull. The current value is \the \hfuzz.
5403
5404\stopoldprimitive
5405
5406\startnewprimitive[title={\prm {hjcode}}]
5407
5408The so called lowercase code determines if a character is part of a
5409to|-|be|-|hyphenated word. In \LUATEX\ we introduced the \quote {hyphenation
5410justification} code as replacement. When a language is saved and no \prm {hjcode}
5411is set the \prm {lccode} is used instead. This code serves a second purpose. When
5412the assigned value is greater than 0 but less than 32 it indicated the to be used
5413length when checking for left- and righthyphenmin. For instance it make sense to
5414set the code to~2 for characters like œ.
5415
5416\stopnewprimitive
5417
5418\startoldprimitive[title={\prm {hkern}}]
5419
5420This primitive is like \prm {kern} but will force the engine into horizontal mode
5421if it isn't yet.
5422
5423\stopoldprimitive
5424
5425\startnewprimitive[title={\prm {hmcode}}]
5426
5427The \type {hm} stands for \quote {hyphenation math}. When bit~1 is set the
5428characters will be repeated on the next line after a break. The second bit
5429concerns italic correction but is of little relevance now that we moved to a
5430different model in \CONTEXT. Here are some examples, we also show an example of
5431\prm {mathdiscretionary} because that is what this code triggers:
5432
5433\startbuffer
5434test $ \dorecurse {50} {
5435    a \discretionary class 2 {$\darkred +$}{$\darkgreen +$}{$\darkblue +$}
5436} b$
5437
5438test $ a \mathdiscretionary class 1 {-}{-}{-} b$
5439
5440\bgroup
5441    \hmcode"002B=1 % +
5442    \hmcode"002D=1 % -
5443    \hmcode"2212=1 % -
5444    test $ \dorecurse{50}{a + b - } c$
5445\egroup
5446\stopbuffer
5447
5448\typebuffer
5449
5450{\setuptolerance[verytolerant,stretch]\getbuffer}
5451
5452\stopnewprimitive
5453
5454\startoldprimitive[title={\prm {holdinginserts}}]
5455
5456When set to a positive value inserts will be kept in the stream and not moved to
5457the insert registers.
5458
5459\stopoldprimitive
5460
5461\startnewprimitive[title={\prm {holdingmigrations}}]
5462
5463When set to a positive value marks (and adjusts) will be kept in the stream and
5464not moved to the outer level or related registers.
5465
5466\stopnewprimitive
5467
5468\startnewprimitive[title={\prm {hpack}}]
5469
5470This primitive is like \prm {hbox} but without the callback overhead.
5471
5472\stopnewprimitive
5473
5474\startnewprimitive[title={\prm {hpenalty}}]
5475
5476This primitive is like \prm {penalty} but will force the engine into horizontal
5477mode if it isn't yet.
5478
5479\stopnewprimitive
5480
5481\startoldprimitive[title={\prm {hrule}}]
5482
5483This creates a horizontal rule. Unless the width is set it will stretch to fix
5484the available width. In addition to the traditional \type {width}, \type {height}
5485and \type {depth} specifiers some more are accepted. These are discussed in other
5486manuals. To give an idea:
5487
5488\startbuffer
5489h\hrule width 10mm height 2mm depth 1mm \relax rule
5490h\hrule width 10mm height 2mm depth 1mm xoffset 30mm yoffset -10mm \relax rule
5491v\vrule width 10mm height 2mm depth 1mm \relax rule
5492v\vrule width 10mm height 2mm depth 1mm xoffset 30mm yoffset  10mm \relax rule
5493\stopbuffer
5494
5495\typebuffer
5496
5497The \prm {relax} stops scanning and because we have more keywords we get a
5498different error report than in traditional \TEX\ when a lookahead confuses the
5499engine. On separate lines we get the following.
5500
5501\startlines
5502\getbuffer
5503\stoplines
5504
5505\stopoldprimitive
5506
5507\startoldprimitive[title={\prm {hsize}}]
5508
5509This sets (or gets) the current horizontal size.
5510
5511\startbuffer
5512\hsize 40pt \setbox0\vbox{x} hsize: \the\wd0
5513\setbox0\vbox{\hsize 40pt x} hsize: \the\wd0
5514\stopbuffer
5515
5516\typebuffer
5517
5518In both cases we get the same size reported but the first one will also influence
5519the current paragraph when used ungrouped.
5520
5521\startlines
5522\getbuffer
5523\stoplines
5524
5525\stopoldprimitive
5526
5527\startoldprimitive[title={\prm {hskip}}]
5528
5529The given glue is injected in the horizontal list. If possible horizontal mode is
5530entered.
5531
5532\stopoldprimitive
5533
5534\startoldprimitive[title={\prm {hss}}]
5535
5536\startbuffer
5537x\hbox to 0pt{\hskip 0pt plus 1 fil minus 1 fil\relax test}x
5538x\hbox to 0pt{\hss test}x
5539x\hbox to 0pt{test\hskip 0pt plus 1 fil minus 1 fil\relax}x
5540x\hbox to 0pt{test\hss}x
5541\stopbuffer
5542
5543In traditional \TEX\ glue specifiers are shared. This makes a lot of sense when
5544memory has to be saved. For instance spaces in a paragraph of text are often the
5545same and a glue specification has at least an amount, stretch, shrink, stretch
5546order and shrink order field plus a leader pointer; in \LUAMETATEX\ we have even
5547more fields. In \LUATEX\ these shared (and therefore referenced) glue spec nodes
5548became just copies.
5549
5550\typebuffer
5551
5552The \prm {hss} primitives injects a glue node with one order stretch and one
5553order shrink. In traditional \TEX\ this is a reference to a shared specification,
5554and in \LUATEX\ just a copy of a predefined specifier. The only gain is now in
5555tokens because one could just be explicit or use a glue register with that value
5556because we have plenty glue registers.
5557
5558\startlines
5559\getbuffer
5560\stoplines
5561
5562We could have this:
5563
5564\starttyping
5565\permanent\protected\untraced\def\hss
5566  {\hskip0pt plus 1 fil minus 1 fil\relax}
5567\stoptyping
5568
5569or this:
5570
5571\starttyping
5572\gluespecdef\hssglue 0pt plus 1 fil minus 1 fil
5573
5574\permanent\protected\untraced\def\hss
5575  {\hskip\hssglue}
5576\stoptyping
5577
5578but we just keep the originals around.
5579
5580\stopoldprimitive
5581
5582\startoldprimitive[title={\prm {ht}}]
5583
5584Returns the height of the given box.
5585
5586\stopoldprimitive
5587
5588\startoldprimitive[title={\prm {hyphenation}}]
5589
5590The list passed to this primitive contains hyphenation exceptions that get bound
5591to the current language. In \LUAMETATEX\ this can be managed at the \LUA\ end.
5592Exceptions are not stored in the format file.
5593
5594\stopoldprimitive
5595
5596\startnewprimitive[title={\prm {hyphenationmin}}]
5597
5598This property (that also gets bond to the current language) sets the minimum
5599length of a word that gets hyphenated.
5600
5601\stopnewprimitive
5602
5603\startnewprimitive[title={\prm {hyphenationmode}}]
5604    TODO
5605\stopnewprimitive
5606
5607\startoldprimitive[title={\prm {hyphenchar}}]
5608
5609This is one of the font related primitives: it returns the number of the hyphen
5610set in the given font.
5611
5612\stopoldprimitive
5613
5614\startoldprimitive[title={\prm {hyphenpenalty}}]
5615
5616Discretionary nodes have a related default penalty. The \prm {hyphenpenalty} is
5617injected after a regular discretionary, and \prm {exhyphenpenalty} after \type
5618{\-} or \type {-}. The later case is called an automatic discretionary. In
5619\LUAMETATEX\ we have two extra penalties: \prm {explicithyphenpenalty} and \prm
5620{automatichyphenpenalty} and these are used when the related bits are set in \prm
5621{hyphenationmode}.
5622
5623\stopoldprimitive
5624
5625\startoldprimitive[title={\prm {if}}]
5626
5627This traditional \TEX\ conditional checks if two character codes are the same. In
5628order to understand unexpanded results it is good to know that internally \TEX\
5629groups primitives in a way that serves the implementation. Each primitive has a
5630command code and a character code, but only for real characters the name
5631character code makes sense. This condition only really tests for character codes
5632when we have a character, in all other cases, the result is true.
5633
5634\startbuffer
5635\def\A{A}\def\B{B} \chardef\C=`C \chardef\D=`D \def\AA{AA}
5636
5637[\if AA   YES \else NOP \fi] [\if AB   YES \else NOP \fi]
5638[\if \A\B YES \else NOP \fi] [\if \A\A YES \else NOP \fi]
5639[\if \C\D YES \else NOP \fi] [\if \C\C YES \else NOP \fi]
5640[\if \count\dimen YES \else NOP \fi] [\if \AA\A YES \else NOP \fi]
5641
5642\stopbuffer
5643
5644\typebuffer
5645
5646The last example demonstrates that the tokens get expanded, which is why
5647we get the extra \type {A}:
5648
5649{\getbuffer}
5650
5651\stopoldprimitive
5652
5653\startnewprimitive[title={\prm {ifabsdim}}]
5654
5655This test will negate negative dimensions before comparison, as in:
5656
5657\startbuffer
5658\def\TestA#1{\ifdim   #1<2pt too small\orelse\ifdim   #1>4pt too large\else okay\fi}
5659\def\TestB#1{\ifabsdim#1<2pt too small\orelse\ifabsdim#1>4pt too large\else okay\fi}
5660
5661\TestA {1pt}\quad\TestA {3pt}\quad\TestA {5pt}\crlf
5662\TestB {1pt}\quad\TestB {3pt}\quad\TestB {5pt}\crlf
5663\TestB{-1pt}\quad\TestB{-3pt}\quad\TestB{-5pt}\par
5664\stopbuffer
5665
5666\typebuffer
5667
5668So we get this:
5669
5670{\getbuffer}
5671
5672\stopnewprimitive
5673
5674\startnewprimitive[title={\prm {ifabsfloat}}]
5675
5676This test will negate negative floats before comparison, as in:
5677
5678\startbuffer
5679\def\TestA#1{\iffloat   #1<2.46 small\orelse\iffloat   #1>4.68 large\else medium\fi}
5680\def\TestB#1{\ifabsfloat#1<2.46 small\orelse\ifabsfloat#1>4.68 large\else medium\fi}
5681
5682\TestA {1.23}\quad\TestA {3.45}\quad\TestA {5.67}\crlf
5683\TestB {1.23}\quad\TestB {3.45}\quad\TestB {5.67}\crlf
5684\TestB{-1.23}\quad\TestB{-3.45}\quad\TestB{-5.67}\par
5685\stopbuffer
5686
5687\typebuffer
5688
5689So we get this:
5690
5691{\getbuffer}
5692
5693\stopnewprimitive
5694
5695\startnewprimitive[title={\prm {ifabsnum}}]
5696
5697This test will negate negative numbers before comparison, as in:
5698
5699\startbuffer
5700\def\TestA#1{\ifnum   #1<100 too small\orelse\ifnum   #1>200 too large\else okay\fi}
5701\def\TestB#1{\ifabsnum#1<100 too small\orelse\ifabsnum#1>200 too large\else okay\fi}
5702
5703\TestA {10}\quad\TestA {150}\quad\TestA {210}\crlf
5704\TestB {10}\quad\TestB {150}\quad\TestB {210}\crlf
5705\TestB{-10}\quad\TestB{-150}\quad\TestB{-210}\par
5706\stopbuffer
5707
5708\typebuffer
5709
5710Here we get the same result each time:
5711
5712{\getbuffer}
5713
5714\stopnewprimitive
5715
5716\startnewprimitive[title={\prm {ifarguments}}]
5717
5718This is a variant of \prm {ifcase} were the selector is the number of arguments
5719picked up. For example:
5720
5721\startbuffer
5722\def\MyMacro#1#2#3{\ifarguments\0\or1\or2\or3\else ?\fi} \MyMacro{A}{B}{C}
5723\def\MyMacro#1#0#3{\ifarguments\0\or1\or2\or3\else ?\fi} \MyMacro{A}{B}{C}
5724\def\MyMacro#1#-#2{\ifarguments\0\or1\or2\or3\else ?\fi} \MyMacro{A}{B}{C}\par
5725\stopbuffer
5726
5727\typebuffer
5728
5729Watch the non counted, ignored, argument in the last case. Normally this test will
5730be used in combination with \prm {ignorearguments}.
5731
5732{\getbuffer}
5733
5734\stopnewprimitive
5735
5736\startnewprimitive[title={\prm {ifboolean}}]
5737
5738This tests a number (register or equivalent) and any nonzero value represents
5739\type {true}, which is nicer than using an \type {\unless \ifcase}.
5740
5741\stopnewprimitive
5742
5743\startoldprimitive[title={\prm {ifcase}}]
5744
5745This numeric \TEX\ conditional takes a counter (literal, register, shortcut to a
5746character, internal quantity) and goes to the branch that matches.
5747
5748\startbuffer
5749\ifcase 3 zero\or one\or two\or three\or four\else five or more\fi
5750\stopbuffer
5751
5752\typebuffer
5753
5754Indeed: \inlinebuffer\ equals three. In later sections we will see some
5755\LUAMETATEX\ primitives that behave like an \prm {ifcase}.
5756
5757\stopoldprimitive
5758
5759\startoldprimitive[title={\prm {ifcat}}]
5760
5761Another traditional \TEX\ primitive: what happens with what gets read in depends
5762on the catcode of a character, think of characters marked to start math mode, or
5763alphabetic characters (letters) versus other characters (like punctuation).
5764
5765\startbuffer
5766\def\A{A}\def\B{,} \chardef\C=`C \chardef\D=`, \def\AA{AA}
5767
5768[\ifcat $!   YES \else NOP \fi] [\ifcat ()   YES \else NOP \fi]
5769[\ifcat AA   YES \else NOP \fi] [\ifcat AB   YES \else NOP \fi]
5770[\ifcat \A\B YES \else NOP \fi] [\ifcat \A\A YES \else NOP \fi]
5771[\ifcat \C\D YES \else NOP \fi] [\ifcat \C\C YES \else NOP \fi]
5772[\ifcat \count\dimen YES \else NOP \fi] [\ifcat \AA\A YES \else NOP \fi]
5773\stopbuffer
5774
5775\typebuffer
5776
5777Close reading is needed here:
5778
5779{\getbuffer}
5780
5781This traditional \TEX\ condition as a well as the one in the previous section are
5782hardly used in \CONTEXT, if only because they expand what follows and we seldom
5783need to compare characters.
5784
5785\stopoldprimitive
5786
5787\startnewprimitive[title={\prm {ifchkdim}}]
5788
5789A variant on the checker in the previous section is a dimension checker:
5790
5791\startbuffer
5792\ifchkdim oeps        \or okay\else error\fi\quad
5793\ifchkdim 12          \or okay\else error\fi\quad
5794\ifchkdim 12pt        \or okay\else error\fi\quad
5795\ifchkdim 12pt or more\or okay\else error\fi
5796\stopbuffer
5797
5798\typebuffer
5799
5800We get:
5801
5802{\getbuffer}
5803
5804\stopnewprimitive
5805
5806\startnewprimitive[title={\prm {ifchkdimension}}]
5807
5808COntrary to \prm {ifchkdim} this test doesn't accept trailing crap:
5809
5810\startbuffer
5811\ifchkdimension oeps        \or okay\else error\fi\quad
5812\ifchkdimension 12          \or okay\else error\fi\quad
5813\ifchkdimension 12pt        \or okay\else error\fi\quad
5814\ifchkdimension 12pt or more\or okay\else error\fi
5815\stopbuffer
5816
5817\typebuffer
5818
5819reports:
5820
5821{\getbuffer}
5822
5823\stopnewprimitive
5824
5825\startnewprimitive[title={\prm {ifchkdimexpr}}]
5826
5827This primitive is like \prm {ifchkdim} but handles an expression.
5828
5829\stopnewprimitive
5830
5831\startnewprimitive[title={\prm {ifchknum}}]
5832
5833In \CONTEXT\ there are quite some cases where a variable can have a number or a
5834keyword indicating a symbolic name of a number or maybe even some special
5835treatment. Checking if a valid number is given is possible to some extend, but a
5836native checker makes much sense too. So here is one:
5837
5838\startbuffer
5839\ifchknum oeps        \or okay\else error\fi\quad
5840\ifchknum 12          \or okay\else error\fi\quad
5841\ifchknum 12pt        \or okay\else error\fi\quad
5842\ifchknum 12pt or more\or okay\else error\fi
5843\stopbuffer
5844
5845\typebuffer
5846
5847The result is as expected:
5848
5849{\getbuffer}
5850
5851\stopnewprimitive
5852
5853\startnewprimitive[title={\prm {ifchknumber}}]
5854
5855This check is more restrictive than \prm {ifchknum} discussed in the previous
5856section:
5857
5858\startbuffer
5859\ifchknumber oeps        \or okay\else error\fi\quad
5860\ifchknumber 12          \or okay\else error\fi\quad
5861\ifchknumber 12pt        \or okay\else error\fi\quad
5862\ifchknumber 12pt or more\or okay\else error\fi
5863\stopbuffer
5864
5865\typebuffer
5866
5867Here we get:
5868
5869{\getbuffer}
5870
5871\stopnewprimitive
5872
5873\startnewprimitive[title={\prm {ifchknumexpr}}]
5874
5875This primitive is like \prm {ifchknum} but handles an expression.
5876
5877\stopnewprimitive
5878
5879\startnewprimitive[title={\prm {ifcmpdim}}]
5880
5881This is a less strict veriant of \prm {ifchkdimension} that doesn't bark on
5882trailing tokens.
5883
5884\stopnewprimitive
5885
5886\startnewprimitive[title={\prm {ifcmpnum}}]
5887
5888This is a less strict veriant of \prm {ifchknumber} that doesn't bark on
5889trailing tokens.
5890
5891\stopnewprimitive
5892
5893\startnewprimitive[title={\prm {ifcondition}}]
5894
5895The conditionals in \TEX\ are hard coded as primitives and although it might
5896look like \type {\newif} creates one, it actually just defined three macros.
5897
5898\startbuffer
5899\newif\ifMyTest
5900\meaning\MyTesttrue  \crlf
5901\meaning\MyTestfalse \crlf
5902\meaning\ifMyTest    \crlf \MyTesttrue
5903\meaning\ifMyTest    \par
5904\stopbuffer
5905
5906\typebuffer {\tttf \getbuffer}
5907
5908This means that when you say:
5909
5910\starttyping
5911\ifMytest ... \else ... \fi
5912\stoptyping
5913
5914You actually have one of:
5915
5916\starttyping
5917\iftrue  ... \else ... \fi
5918\iffalse ... \else ... \fi
5919\stoptyping
5920
5921and because these are proper conditions nesting them like:
5922
5923\starttyping
5924\ifnum\scratchcounter > 0 \ifMyTest A\else B\fi \fi
5925\stoptyping
5926
5927will work out well too. This is not true for macros, so for instance:
5928
5929\starttyping
5930\scratchcounter = 1
5931\unexpanded\def\ifMyTest{\iftrue}
5932\ifnum\scratchcounter > 0 \ifMyTest A\else B\fi \fi
5933\stoptyping
5934
5935will make a run fail with an error (or simply loop forever, depending on your
5936code). This is where \prm {ifcondition} enters the picture:
5937
5938\starttyping
5939\def\MyTest{\iftrue} \scratchcounter0
5940\ifnum\scratchcounter > 0
5941    \ifcondition\MyTest A\else B\fi
5942\else
5943    x
5944\fi
5945\stoptyping
5946
5947This primitive is seen as a proper condition when \TEX\ is in \quotation {fast
5948skipping unused branches} mode but when it is expanding a branch, it checks if
5949the next expanded token is a proper tests and if so, it deals with that test,
5950otherwise it fails. The main condition here is that the \type {\MyTest} macro
5951expands to a proper true or false test, so, a definition like:
5952
5953\starttyping
5954\def\MyTest{\ifnum\scratchcounter<10 }
5955\stoptyping
5956
5957is also okay. Now, is that neat or not?
5958
5959\stopnewprimitive
5960
5961\startnewprimitive[title={\prm {ifcramped}}]
5962
5963Depending on the given math style this returns true of false:
5964
5965\startbuffer
5966\ifcramped\mathstyle        no  \fi
5967\ifcramped\crampedtextstyle yes \fi
5968\ifcramped\textstyle        no  \fi
5969\ifcramped\displaystyle     yes \fi
5970\stopbuffer
5971
5972\typebuffer
5973
5974gives: \inlinebuffer.
5975
5976\stopnewprimitive
5977
5978\startoldprimitive[title={\prm {ifcsname}}]
5979
5980This is an \ETEX\ conditional that complements the one on the previous section:
5981
5982\starttyping
5983\expandafter\ifx\csname MyMacro\endcsname\relax ... \else ... \fi
5984            \ifcsname   MyMacro\endcsname       ... \else ... \fi
5985\stoptyping
5986
5987Here the first one has the side effect of defining the macro and defaulting it to
5988\prm {relax}, while the second one doesn't do that. Just think of checking a
5989few million different names: the first one will deplete the hash table and
5990probably string space too.
5991
5992In \LUAMETATEX\ the construction stops when there is no letter or other character
5993seen (\TEX\ expands on the go so expandable macros are dealt with). Instead of an
5994error message, the match is simply false and all tokens till the \prm
5995{endcsname} are gobbled.
5996
5997\stopoldprimitive
5998
5999\startnewprimitive[title={\prm {ifcstok}}]
6000
6001A variant on the primitive mentioned in the previous section is one that
6002operates on lists and macros:
6003
6004\startbuffer[a]
6005\def\a{a} \def\b{b} \def\c{a}
6006\stopbuffer
6007
6008\typebuffer[a]
6009
6010\startbuffer[b]
6011\ifcstok\a\b   Y\else N\fi\space
6012\ifcstok\a\c   Y\else N\fi\space
6013\ifcstok{\a}\c Y\else N\fi\space
6014\ifcstok{a}\c  Y\else N\fi
6015\stopbuffer
6016
6017This:
6018
6019\typebuffer[b]
6020
6021{\getbuffer[a]will give us: \inlinebuffer[b].}
6022
6023\stopnewprimitive
6024
6025\startoldprimitive[title={\prm {ifdefined}}]
6026
6027In traditional \TEX\ checking for a macro to exist was a bit tricky and therefore
6028\ETEX\ introduced a convenient conditional. We can do this:
6029
6030\starttyping
6031\ifx\MyMacro\undefined ... \else ... \fi
6032\stoptyping
6033
6034but that assumes that \type {\undefined} is indeed undefined. Another test often
6035seen was this:
6036
6037\starttyping
6038\expandafter\ifx\csname MyMacro\endcsname\relax ... \else ... \fi
6039\stoptyping
6040
6041Instead of comparing with \type {\undefined} we need to check with \prm {relax}
6042because the control sequence is defined when not yet present and defaults to
6043\prm {relax}. This is not pretty.
6044
6045\stopoldprimitive
6046
6047\startoldprimitive[title={\prm {ifdim}}]
6048
6049Dimensions can be compared with this traditional \TEX\ primitive.
6050
6051\startbuffer
6052\scratchdimen=1pt \scratchcounter=65536
6053
6054\ifdim\scratchdimen=\scratchcounter sp YES \else NOP\fi
6055\ifdim\scratchdimen=1               pt YES \else NOP\fi
6056\stopbuffer
6057
6058\typebuffer
6059
6060The units are mandate:
6061
6062{\getbuffer}
6063
6064\stopoldprimitive
6065
6066\startnewprimitive[title={\prm {ifdimexpression}}]
6067
6068The companion of the previous primitive is:
6069
6070\startbuffer
6071\ifdimexpression 10pt > 10bp \relax
6072    do-something
6073\fi
6074\stopbuffer
6075
6076This matches when the result is non zero, and you can mix calculations and tests
6077as with normal expressions. Contrary to the number variant units can be used and
6078precision kicks in.
6079
6080\stopnewprimitive
6081
6082\startnewprimitive[title={\prm {ifdimval}}]
6083
6084This conditional is a variant on \prm {ifchkdim} and provides some more
6085detailed information about the value:
6086
6087\startbuffer
6088[-12pt : \ifdimval-12pt\or negative\or zero\or positive\else error\fi]\quad
6089[0pt   : \ifdimval  0pt\or negative\or zero\or positive\else error\fi]\quad
6090[12pt  : \ifdimval 12pt\or negative\or zero\or positive\else error\fi]\quad
6091[oeps  : \ifdimval oeps\or negative\or zero\or positive\else error\fi]
6092\stopbuffer
6093
6094\typebuffer
6095
6096This gives:
6097
6098{\getbuffer}
6099
6100\stopnewprimitive
6101
6102\startnewprimitive[title={\prm {ifempty}}]
6103
6104This conditional checks if a control sequence is empty:
6105
6106\starttyping
6107is \ifempty\MyMacro \else not \fi empty
6108\stoptyping
6109
6110It is basically a shortcut of:
6111
6112\starttyping
6113is \ifx\MyMacro\empty \else not \fi empty
6114\stoptyping
6115
6116with:
6117
6118\starttyping
6119\def\empty{}
6120\stoptyping
6121
6122Of course this is not empty at all:
6123
6124\starttyping
6125\def\notempty#1{}
6126\stoptyping
6127
6128\stopnewprimitive
6129
6130\startoldprimitive[title={\prm {iffalse}}]
6131
6132Here we have a traditional \TEX\ conditional that is always false (therefore the
6133same is true for any macro that is \prm {let} to this primitive).
6134
6135\stopoldprimitive
6136
6137\startnewprimitive[title={\prm {ifflags}}]
6138
6139This test primitive relates to the various flags that one can set on a control
6140sequence in the perspective of overload protection and classification.
6141
6142\startbuffer
6143\protected\untraced\tolerant\def\foo[#1]{...#1...}
6144\permanent\constant         \def\oof{okay}
6145\stopbuffer
6146
6147\typebuffer
6148
6149\start \getbuffer
6150\starttabulate[|l|c|c|l|c|c|]
6151\FL
6152\NC flag          \NC \type  {\foo}                          \NC \type  {\oof}
6153\NC flag          \NC \type  {\foo}                          \NC \type  {\oof}                          \NC \NR
6154\ML
6155\NC frozen        \NC \ifflags\foo\frozen        Y\else N\fi \NC \ifflags\oof\frozen        Y\else N\fi
6156\NC permanent     \NC \ifflags\foo\permanent     Y\else N\fi \NC \ifflags\oof\permanent     Y\else N\fi \NC \NR
6157\NC immutable     \NC \ifflags\foo\immutable     Y\else N\fi \NC \ifflags\oof\immutable     Y\else N\fi
6158\NC mutable       \NC \ifflags\foo\mutable       Y\else N\fi \NC \ifflags\oof\mutable       Y\else N\fi \NC \NR
6159\NC noaligned     \NC \ifflags\foo\noaligned     Y\else N\fi \NC \ifflags\oof\noaligned     Y\else N\fi
6160\NC instance      \NC \ifflags\foo\instance      Y\else N\fi \NC \ifflags\oof\instance      Y\else N\fi \NC \NR
6161\NC untraced      \NC \ifflags\foo\untraced      Y\else N\fi \NC \ifflags\oof\untraced      Y\else N\fi
6162\NC global        \NC \ifflags\foo\global        Y\else N\fi \NC \ifflags\oof\global        Y\else N\fi \NC \NR
6163\NC tolerant      \NC \ifflags\foo\tolerant      Y\else N\fi \NC \ifflags\oof\tolerant      Y\else N\fi
6164\NC constant      \NC \ifflags\foo\constant      Y\else N\fi \NC \ifflags\oof\constant      Y\else N\fi \NC \NR
6165\NC protected     \NC \ifflags\foo\protected     Y\else N\fi \NC \ifflags\oof\protected     Y\else N\fi
6166\NC semiprotected \NC \ifflags\foo\semiprotected Y\else N\fi \NC \ifflags\oof\semiprotected Y\else N\fi \NC \NR
6167\LL
6168\stoptabulate
6169\stop
6170
6171Instead of checking against a prefix you can test against a bitset made from:
6172
6173\startluacode
6174context.starttabulate { "|r|l|r|l|r|l|r|l|" }
6175local n = 4
6176for k, v in table.sortedhash(tex.flagcodes) do
6177    if tonumber(k) then
6178        n = n - 1
6179        context.NC() context("0x%X",k)
6180        context.NC() context(v)
6181        if n == 0 then
6182            context.NC()
6183            context.NR()
6184            n = 4
6185        end
6186    end
6187end
6188context.stoptabulate()
6189\stopluacode
6190
6191\stopnewprimitive
6192
6193\startnewprimitive[title={\prm {iffloat}}]
6194
6195This test does for floats what \prm {ifnum}, \prm {ifdim} do for numbers and
6196dimensions: comparing two of them.
6197
6198\stopnewprimitive
6199
6200\startoldprimitive[title={\prm {iffontchar}}]
6201
6202This is an \ETEX\ conditional. It takes a font identifier and a character number.
6203In modern fonts simply checking could not be enough because complex font features
6204can swap in other ones and their index can be anything. Also, a font mechanism
6205can provide fallback fonts and characters, so don't rely on this one too much. It
6206just reports true when the font passed to the frontend has a slot filled.
6207
6208\stopoldprimitive
6209
6210\startnewprimitive[title={\prm {ifhaschar}}]
6211
6212This one is a simplified variant of the above:
6213
6214\startbuffer
6215\ifhaschar !{this ! works} yes \else no \fi
6216\stopbuffer
6217
6218\typebuffer
6219
6220and indeed we get: \inlinebuffer ! Of course the spaces in this this example
6221code are normally not present in such a test.
6222
6223\stopnewprimitive
6224
6225\startnewprimitive[title={\prm {ifhastok}}]
6226
6227This conditional looks for occurrences in token lists where each argument has to
6228be a proper list.
6229
6230\startbuffer
6231\def\scratchtoks{x}
6232
6233\ifhastoks{yz}         {xyz} Y\else N\fi\quad
6234\ifhastoks\scratchtoks {xyz} Y\else N\fi
6235\stopbuffer
6236
6237\typebuffer
6238
6239We get:
6240
6241{\getbuffer}
6242
6243\stopnewprimitive
6244
6245\startnewprimitive[title={\prm {ifhastoks}}]
6246
6247This test compares two token lists. When a macro is passed it's meaning
6248gets used.
6249
6250\startbuffer
6251\def\x  {x}
6252\def\xyz{xyz}
6253
6254(\ifhastoks  {x}  {xyz}Y\else N\fi)\quad
6255(\ifhastoks {\x}  {xyz}Y\else N\fi)\quad
6256(\ifhastoks  \x   {xyz}Y\else N\fi)\quad
6257(\ifhastoks  {y}  {xyz}Y\else N\fi)\quad
6258(\ifhastoks {yz}  {xyz}Y\else N\fi)\quad
6259(\ifhastoks {yz} {\xyz}Y\else N\fi)
6260\stopbuffer
6261
6262\typebuffer {\getbuffer}
6263
6264\stopnewprimitive
6265
6266\startnewprimitive[title={\prm {ifhasxtoks}}]
6267
6268This primitive is like the one in the previous section but this time the
6269given lists are expanded.
6270
6271\startbuffer
6272\def\x  {x}
6273\def\xyz{\x yz}
6274
6275(\ifhasxtoks  {x}  {xyz}Y\else N\fi)\quad
6276(\ifhasxtoks {\x}  {xyz}Y\else N\fi)\quad
6277(\ifhastoks   \x   {xyz}Y\else N\fi)\quad
6278(\ifhasxtoks  {y}  {xyz}Y\else N\fi)\quad
6279(\ifhasxtoks {yz}  {xyz}Y\else N\fi)\quad
6280(\ifhasxtoks {yz} {\xyz}Y\else N\fi)
6281\stopbuffer
6282
6283\typebuffer {\getbuffer}
6284
6285This primitive has some special properties.
6286
6287\startbuffer
6288\edef\+{\expandtoken 9 `+}
6289
6290\ifhasxtoks {xy}   {xyz}Y\else N\fi\quad
6291\ifhasxtoks {x\+y} {xyz}Y\else N\fi
6292\stopbuffer
6293
6294\typebuffer
6295
6296Here the first argument has a token that has category code \quote {ignore} which
6297means that such a character will be skipped when seen. So the result is:
6298
6299{\getbuffer}
6300
6301This permits checks like these:
6302
6303\startbuffer
6304\edef\,{\expandtoken 9 `,}
6305
6306\ifhasxtoks{\,x\,} {,x,y,z,}Y\else N\fi\quad
6307\ifhasxtoks{\,y\,} {,x,y,z,}Y\else N\fi\quad
6308\ifhasxtoks{\,z\,} {,x,y,z,}Y\else N\fi\quad
6309\ifhasxtoks{\,x\,}  {,xy,z,}Y\else N\fi
6310\stopbuffer
6311
6312\typebuffer
6313
6314I admit that it needs a bit of a twisted mind to come up with this, but it works
6315ok:
6316
6317{\getbuffer}
6318
6319\stopnewprimitive
6320
6321\startoldprimitive[title={\prm {ifhbox}}]
6322
6323This traditional conditional checks if a given box register or internal box
6324variable represents a horizontal box,
6325
6326\stopoldprimitive
6327
6328\startoldprimitive[title={\prm {ifhmode}}]
6329
6330This traditional conditional checks we are in (restricted) horizontal mode.
6331
6332\stopoldprimitive
6333
6334\startnewprimitive[title={\prm {ifinalignment}}]
6335
6336As the name indicates, this primitive tests for being in an alignment. Roughly
6337spoken, the engine is either in a state of align, handling text or dealing with
6338math.
6339
6340\stopnewprimitive
6341
6342\startnewprimitive[title={\prm {ifincsname}}]
6343
6344This conditional is sort of obsolete and can be used to check if we're inside a
6345\prm {csname} or \prm {ifcsname} construction. It's not used in \CONTEXT.
6346
6347\stopnewprimitive
6348
6349\startoldprimitive[title={\prm {ifinner}}]
6350
6351This traditional one can be confusing. It is true when we are in restricted
6352horizontal mode (a box), internal vertical mode (a box), or inline math mode.
6353
6354\startbuffer
6355test \ifhmode \ifinner INNER\fi HMODE\fi\crlf
6356\hbox{test \ifhmode \ifinner INNER \fi HMODE\fi} \par
6357
6358\ifvmode \ifinner INNER\fi VMODE \fi\crlf
6359\vbox{\ifvmode \ifinner INNER \fi VMODE\fi} \crlf
6360\vbox{\ifinner INNER \ifvmode VMODE \fi \fi} \par
6361\stopbuffer
6362
6363\typebuffer
6364
6365Watch the last line: because we typeset \type {INNER} we enter horizontal mode:
6366
6367{\getbuffer}
6368
6369\stopoldprimitive
6370
6371\startnewprimitive[title={\prm {ifinsert}}]
6372
6373This is the equivalent of \prm {ifvoid} for a given insert class.
6374
6375\stopnewprimitive
6376
6377\startnewprimitive[title={\prm {ifintervaldim}}]
6378
6379This conditional is true when the intervals around the values of two dimensions
6380overlap. The first dimension determines the interval.
6381
6382\startbuffer
6383[\ifintervaldim1pt 20pt 21pt \else no \fi overlap]
6384[\ifintervaldim1pt 18pt 20pt \else no \fi overlap]
6385\stopbuffer
6386
6387\typebuffer
6388
6389So here: \inlinebuffer
6390
6391\stopnewprimitive
6392
6393\startnewprimitive[title={\prm {ifintervalfloat}}]
6394
6395This one does with floats what we described under \prm {ifintervaldim}.
6396
6397\stopnewprimitive
6398
6399\startnewprimitive[title={\prm {ifintervalnum}}]
6400
6401This one does with integers what we described under \prm {ifintervaldim}.
6402
6403\stopnewprimitive
6404
6405\startnewprimitive[title={\prm {iflastnamedcs}}]
6406
6407When a \prm {csname} is constructed and succeeds the last one is remembered and
6408can be accessed with \prm {lastnamedcs}. It can however be an undefined one. That
6409state can be checked with this primitive. Of course it also works with the \prm
6410{ifcsname} and \prm {begincsname} variants.
6411
6412\stopnewprimitive
6413
6414\startnewprimitive[title={\prm {iflist}}]
6415
6416The \prm {ifvoid} conditional checks is a box is unset, that is, no \type {hlist}
6417or \type {vlist} node is assigned. The \prm {iflist} conditional also checks is a
6418list is assigned to this node. If there is a node assigned the box can of course
6419have dimensions, but it's the presence of a list (content) that matters here.
6420
6421\startbuffer
6422[\setbox0\hbox{!}\iflist0 \else no \fi list, \ifvoid0 \else not \fi void]
6423[\setbox0\hbox {}\iflist0 \else no \fi list, \ifvoid0 \else not \fi void]
6424[\box0           \iflist0 \else no \fi list, \ifvoid0 \else not \fi void]
6425\stopbuffer
6426
6427\typebuffer
6428
6429We get: \inlinebuffer
6430
6431\stopnewprimitive
6432
6433\startnewprimitive[title={\prm {ifmathparameter}}]
6434
6435This is an \prm {ifcase} where the value depends on if the given math parameter
6436is zero, (\type {0}), set (\type {1}), or unset (\type {2}).
6437
6438\starttyping
6439\ifmathparameter\Umathpunctclosespacing\displaystyle
6440    zero    \or
6441    nonzero \or
6442    unset   \fi
6443\stoptyping
6444
6445\stopnewprimitive
6446
6447\startnewprimitive[title={\prm {ifmathstyle}}]
6448
6449This is a variant of \prm {ifcase} were the number is one of the seven possible
6450styles: display, text, cramped text, script, cramped script, script script,
6451cramped script script.
6452
6453\starttyping
6454\ifmathstyle
6455  display
6456\or
6457  text
6458\or
6459  cramped text
6460\else
6461  normally smaller than text
6462\fi
6463\stoptyping
6464
6465\stopnewprimitive
6466
6467\startoldprimitive[title={\prm {ifmmode}}]
6468
6469This traditional conditional checks we are in (inline or display) math mode mode.
6470
6471\stopoldprimitive
6472
6473\startoldprimitive[title={\prm {ifnum}}]
6474
6475This is a frequently used conditional: it compares two numbers where a number is
6476anything that can be seen as such.
6477
6478\startbuffer
6479\scratchcounter=65 \chardef\A=65
6480
6481\ifnum65=`A              YES \else NOP\fi
6482\ifnum\scratchcounter=65 YES \else NOP\fi
6483\ifnum\scratchcounter=\A YES \else NOP\fi
6484\stopbuffer
6485
6486\typebuffer
6487
6488Unless a number is an unexpandable token it ends with a space or \prm {relax},
6489so when you end up in the true branch, you'd better check if \TEX\ could
6490determine where the number ends.
6491
6492{\getbuffer}
6493
6494% When comparing integers, definitions (for instance characters) that can be seen
6495% as such, or any converter that produces a number (like the \type {`} or \prm
6496% {number} the usual \type {=}, \type {<} or \type {>} can be used. However, in
6497% \LUAMETATEX\ you can negate such a comparison by \type {!}: \type {!=}, \type
6498% {!<} or \type {!>}. Successive \type {!} toggle the negation state.
6499
6500On top of these \ASCII\ combinations, the engine also accepts some \UNICODE\
6501characters. This brings the full repertoire to:
6502
6503\starttabulate[|l|cT|cT|l|]
6504\FL
6505\BC character      \BC               \BC    \BC operation         \NC \NR
6506\ML
6507\NC \type {0x003C} \NC $\Uchar"003C$ \NC    \NC less              \NC \NR
6508\NC \type {0x003D} \NC $\Uchar"003D$ \NC    \NC equal             \NC \NR
6509\NC \type {0x003E} \NC $\Uchar"003E$ \NC    \NC more              \NC \NR
6510\NC \type {0x2208} \NC $\Uchar"2208$ \NC    \NC element of        \NC \NR
6511\NC \type {0x2209} \NC $\Uchar"2209$ \NC    \NC not element of    \NC \NR
6512\NC \type {0x2260} \NC $\Uchar"2260$ \NC != \NC not equal         \NC \NR
6513\NC \type {0x2264} \NC $\Uchar"2264$ \NC !> \NC less equal        \NC \NR
6514\NC \type {0x2265} \NC $\Uchar"2265$ \NC !< \NC greater equal     \NC \NR
6515\NC \type {0x2270} \NC $\Uchar"2270$ \NC    \NC not less equal    \NC \NR
6516\NC \type {0x2271} \NC $\Uchar"2271$ \NC    \NC not greater equal \NC \NR
6517\LL
6518\stoptabulate
6519
6520This also applied to \prm {ifdim} although in the case of element we discard the
6521fractional part (read: divide the numeric representation by 65536).
6522
6523\stopoldprimitive
6524
6525\startnewprimitive[title={\prm {ifnumexpression}}]
6526
6527Here is an example of a conditional using expressions:
6528
6529\startbuffer
6530\ifnumexpression (\scratchcounterone > 5) and (\scratchcountertwo > 5) \relax
6531    do-something
6532\fi
6533\stopbuffer
6534
6535This matches when the result is non zero, and you can mix calculations and tests
6536as with normal expressions.
6537
6538\stopnewprimitive
6539
6540\startnewprimitive[title={\prm {ifnumval}}]
6541
6542This conditional is a variant on \prm {ifchknum}. This time we get
6543some more detail about the value:
6544
6545\startbuffer
6546[-12  : \ifnumval  -12\or negative\or zero\or positive\else error\fi]\quad
6547[0    : \ifnumval    0\or negative\or zero\or positive\else error\fi]\quad
6548[12   : \ifnumval   12\or negative\or zero\or positive\else error\fi]\quad
6549[oeps : \ifnumval oeps\or negative\or zero\or positive\else error\fi]
6550\stopbuffer
6551
6552\typebuffer
6553
6554This gives:
6555
6556{\getbuffer}
6557
6558\stopnewprimitive
6559
6560\startoldprimitive[title={\prm {ifodd}}]
6561
6562One reason for this condition to be around is that in a double sided layout we
6563need test for being on an odd or even page. It scans for a number the same was
6564as other primitives,
6565
6566\startbuffer
6567\ifodd65 YES \else NO\fi &
6568\ifodd`B YES \else NO\fi .
6569\stopbuffer
6570
6571\typebuffer
6572
6573So: {\inlinebuffer}
6574
6575\stopoldprimitive
6576
6577\startnewprimitive[title={\prm {ifparameter}}]
6578
6579In a macro body \type {#1} is a reference to a parameter. You can check if one is
6580set using a dedicated parameter condition:
6581
6582\startbuffer
6583\tolerant\def\foo[#1]#*[#2]%
6584  {\ifparameter#1\or one\else no one\fi\enspace
6585   \ifparameter#2\or two\else no two\fi\emspace}
6586
6587\foo
6588\foo[1]
6589\foo[1][2]
6590\stopbuffer
6591
6592\typebuffer
6593
6594We get:
6595
6596\getbuffer
6597
6598\stopnewprimitive
6599
6600\startnewprimitive[title={\prm {ifparameters}}]
6601
6602This is equivalent to an \prm {ifcase} with as value the number of parameters
6603passed to the current macro.
6604
6605\stopnewprimitive
6606
6607\startnewprimitive[title={\prm {ifrelax}}]
6608
6609This is a convenient shortcut for \typ {\ifx\relax} and the motivation for adding
6610this one is (as with some others) to get less tracing.
6611
6612\stopnewprimitive
6613
6614\startnewprimitive[title={\prm {iftok}}]
6615
6616When you want to compare two arguments, the usual way to do this is the
6617following:
6618
6619\starttyping
6620\edef\tempA{#1}
6621\edef\tempb{#2}
6622\ifx\tempA\tempB
6623    the same
6624\else
6625    different
6626\fi
6627\stoptyping
6628
6629This works quite well but the fact that we need to define two macros can be
6630considered a bit of a nuisance. It also makes macros that use this method to be
6631not so called \quote {fully expandable}. The next one avoids both issues:
6632
6633\starttyping
6634\iftok{#1}{#2}
6635    the same
6636\else
6637    different
6638\fi
6639\stoptyping
6640
6641Instead of direct list you can also pass registers, so given:
6642
6643\startbuffer[a]
6644\scratchtoks{a}%
6645\toks0{a}%
6646\stopbuffer
6647
6648\typebuffer[a]
6649
6650This:
6651
6652\startbuffer[b]
6653\iftok 0 \scratchtoks          Y\else N\fi\space
6654\iftok{a}\scratchtoks          Y\else N\fi\space
6655\iftok\scratchtoks\scratchtoks Y\else N\fi
6656\stopbuffer
6657
6658\typebuffer[b]
6659
6660{\getbuffer[a]gives: \inlinebuffer[b].}
6661
6662\stopnewprimitive
6663
6664\startoldprimitive[title={\prm {iftrue}}]
6665
6666Here we have a traditional \TEX\ conditional that is always true (therefore the
6667same is true for any macro that is \prm {let} to this primitive).
6668
6669\stopoldprimitive
6670
6671\startoldprimitive[title={\prm {ifvbox}}]
6672
6673This traditional conditional checks if a given box register or internal box
6674variable represents a vertical box,
6675
6676\stopoldprimitive
6677
6678\startoldprimitive[title={\prm {ifvmode}}]
6679
6680This traditional conditional checks we are in (internal) vertical mode.
6681
6682\stopoldprimitive
6683
6684\startoldprimitive[title={\prm {ifvoid}}]
6685
6686This traditional conditional checks if a given box register or internal box
6687variable has any content.
6688
6689\stopoldprimitive
6690
6691\startoldprimitive[title={\prm {ifx}}]
6692
6693We use this traditional \TEX\ conditional a lot in \CONTEXT. Contrary to \prm {if}
6694the two tokens that are compared are not expanded. This makes it possible to compare
6695the meaning of two macros. Depending on the need, these macros can have their content
6696expanded or not. A different number of parameters results in false.
6697
6698Control sequences are identical when they have the same command code and
6699character code. Because a \prm {let} macro is just a reference, both let macros
6700are the same and equal to \prm {relax}:
6701
6702\starttyping
6703\let\one\relax \let\two\relax
6704\stoptyping
6705
6706The same is true for other definitions that result in the same (primitive) or
6707meaning encoded in the character field (think of \prm {chardef}s and so).
6708
6709\stopoldprimitive
6710
6711\startnewprimitive[title={\prm {ifzerodim}}]
6712
6713This tests for a dimen (dimension) being zero so we have:
6714
6715\starttyping
6716\ifdim<dimension>=0pt
6717\ifzerodim<dimension>
6718\ifcase<dimension register>
6719\stoptyping
6720
6721\stopnewprimitive
6722
6723\startnewprimitive[title={\prm {ifzerofloat}}]
6724
6725As the name indicated, this tests for a zero float value.
6726
6727\startbuffer
6728[\scratchfloat\zerofloat \ifzerofloat\scratchfloat \else not \fi zero]
6729[\scratchfloat\plusone   \ifzerofloat\scratchfloat \else not \fi zero]
6730[\scratchfloat 0.01      \ifzerofloat\scratchfloat \else not \fi zero]
6731[\scratchfloat 0.0e0     \ifzerofloat\scratchfloat \else not \fi zero]
6732[\scratchfloat \zeropoint\ifzerofloat\scratchfloat \else not \fi zero]
6733\stopbuffer
6734
6735\typebuffer
6736
6737So: \inlinebuffer
6738
6739\stopnewprimitive
6740
6741\startnewprimitive[title={\prm {ifzeronum}}]
6742
6743This tests for a number (integer) being zero so we have these variants now:
6744
6745\starttyping
6746\ifnum<integer or equivalent>=0
6747\ifzeronum<integer or equivalent>
6748\ifcase<integer or equivalent>
6749\stoptyping
6750
6751\stopnewprimitive
6752
6753\startnewprimitive[title={\prm {ignorearguments}}]
6754
6755This primitive will quit argument scanning and start expansion of the body of a
6756macro. The number of grabbed arguments can be tested as follows:
6757
6758\startbuffer
6759\def\MyMacro[#1][#2][#3]%
6760 {\ifarguments zero\or one\or two\or three \else hm\fi}
6761
6762\MyMacro          \ignorearguments \quad
6763\MyMacro       [1]\ignorearguments \quad
6764\MyMacro    [1][2]\ignorearguments \quad
6765\MyMacro [1][2][3]\ignorearguments \par
6766\stopbuffer
6767
6768\typebuffer
6769
6770{\getbuffer}
6771
6772{\em Todo: explain optional delimiters.}
6773
6774\stopnewprimitive
6775
6776\startnewprimitive[title={\prm {ignoredepthcriterion}}]
6777
6778When setting the \prm {prevdepth} (either by \TEX\ or by the current user) of the
6779current vertical list the value 1000pt is a signal for special treatment of the
6780skip between \quote {lines}. There is an article on that in the distribution. It
6781also demonstrates that \prm {ignoredepthcriterion} can be used to change this
6782special signal, just in case it is needed.
6783
6784\stopnewprimitive
6785
6786\startnewprimitive[title={\prm {ignorenestedupto}}]
6787
6788This primitive gobbles following tokens and can deal with nested \quote
6789{environments}, for example:
6790
6791\startbuffer
6792\def\StartFoo{\ignorenestedupto\StartFoo\StopFoo}
6793
6794(before
6795\StartFoo
6796    test \StartFoo test \StopFoo
6797   {test \StartFoo test \StopFoo}
6798\StopFoo
6799after)
6800\stopbuffer
6801
6802\typebuffer
6803
6804delivers:
6805
6806\getbuffer
6807
6808\stopnewprimitive
6809
6810\startnewprimitive[title={\prm {ignorepars}}]
6811
6812This is a variant of \prm {ignorespaces}: following spaces {\em and} \type
6813{\par} equivalent tokens are ignored, so for instance:
6814
6815\startbuffer
6816one + \ignorepars
6817
6818two = \ignorepars \par
6819three
6820\stopbuffer
6821
6822\typebuffer
6823
6824renders as: \inlinebuffer. Traditionally \TEX\ has been sensitive to \prm {par}
6825tokens in some of its building blocks. This has to do with the fact that it could
6826indicate a runaway argument which in the times of slower machines and terminals
6827was best to catch early. In \LUAMETATEX\ we no longer have long macros and the
6828mechanisms that are sensitive can be told to accept \prm {par} tokens (and
6829\CONTEXT\ set them such that this is the case).
6830
6831\stopnewprimitive
6832
6833\startnewprimitive[title={\prm {ignorerest}}]
6834
6835An example shows what this primitive does:
6836
6837\startbuffer
6838\tolerant\def\foo[#1]#*[#2]%
6839  {1234
6840   \ifparameter#1\or\else
6841     \expandafter\ignorerest
6842   \fi
6843   /#1/
6844   \ifparameter#2\or\else
6845     \expandafter\ignorerest
6846   \fi
6847   /#2/ }
6848
6849\foo test \foo[456] test \foo[456][789] test
6850\stopbuffer
6851
6852\typebuffer
6853
6854As this likely makes most sense in conditionals you need to make sure the current
6855state is properly finished. Because \prm {expandafter} bumps the input state,
6856here we actually quit two levels; this is because so called \quote {backed up
6857text} is intercepted by this primitive.
6858
6859\getbuffer
6860
6861\stopnewprimitive
6862
6863\startoldprimitive[title={\prm {ignorespaces}}]
6864
6865This traditional \TEX\ primitive signals the scanner to ignore the following
6866spaces, if any. We mention it because we show a companion in the next section.
6867
6868\stopoldprimitive
6869
6870\startnewprimitive[title={\prm {ignoreupto}}]
6871
6872This ignores everything upto the given token, so
6873
6874\startbuffer
6875\ignoreupto \foo not this but\foo only this
6876\stopbuffer
6877
6878\typebuffer
6879
6880will give: \inlinebuffer .
6881
6882\stopnewprimitive
6883
6884\startoldprimitive[title={\prm {immediate}}]
6885
6886This one has no effect unless you intercept it at the \LUA\ end and act upon it.
6887In original \TEX\ immediate is used in combination with read from and write to
6888file operations. So, this is an old primitive with a new meaning.
6889
6890\stopoldprimitive
6891
6892\startnewprimitive[title={\prm {immutable}}]
6893
6894This prefix flags what follows as being frozen and is usually applied to for
6895instance \prm {integerdef}'d control sequences. In that respect is is like \prm
6896{permanent} but it makes it possible to distinguish quantities from macros.
6897
6898\stopnewprimitive
6899
6900\startoldprimitive[title={\prm {indent}}]
6901
6902In engines other than \LUAMETATEX\ a paragraph starts with an indentation box.
6903The width of that (empty) box is determined by \prm {parindent}. In \LUAMETATEX\
6904we can use a dedicated indentation skip instead (as part of paragraph
6905normalization). An indentation can be zero'd with \prm {undent}.
6906
6907\stopoldprimitive
6908
6909\startnewprimitive[title={\prm {indexedsubprescript}}]
6910
6911This primitive (or \type {____}) puts a flag on the script but renders
6912the same:
6913
6914\startbuffer
6915$
6916    x \indexedsuperprescript{2} \subprescript       {2} +
6917    x \superprescript       {2} \indexedsubprescript{2} +
6918    x \superprescript       {2} ____                {2} =
6919    x \superprescript       {2} \subprescript       {2}
6920$
6921\stopbuffer
6922
6923\typebuffer
6924
6925Gives: \inlinebuffer.
6926
6927\stopnewprimitive
6928
6929\startnewprimitive[title={\prm {indexedsubscript}}]
6930
6931This primitive (or \type {__}) puts a flag on the script but renders
6932the same:
6933
6934\startbuffer
6935$
6936    x \indexedsuperscript{2} \subscript       {2} +
6937    x \superscript       {2} \indexedsubscript{2} +
6938    x \superscript       {2} __               {2} =
6939    x \superscript       {2} \subscript       {2}
6940$
6941\stopbuffer
6942
6943\typebuffer
6944
6945Gives: \inlinebuffer.
6946
6947\stopnewprimitive
6948
6949\startnewprimitive[title={\prm {indexedsuperprescript}}]
6950
6951This primitive (or \type {^^^^}) puts a flag on the script but renders
6952the same:
6953
6954\startbuffer
6955$
6956    x \indexedsuperprescript{2} \subprescript       {2} +
6957    x ^^^^                  {2} \subprescript       {2} +
6958    x \superprescript       {2} \indexedsubprescript{2} =
6959    x \superprescript       {2} \subprescript       {2}
6960$
6961\stopbuffer
6962
6963\typebuffer
6964
6965Gives: \inlinebuffer.
6966
6967\stopnewprimitive
6968
6969\startnewprimitive[title={\prm {indexedsuperscript}}]
6970
6971This primitive (or \type {^^}) puts a flag on the script but renders
6972the same:
6973
6974\startbuffer
6975$
6976    x \indexedsuperscript{2} \subscript       {2} +
6977    x ^^                 {2} \subscript       {2} +
6978    x \superscript       {2} \indexedsubscript{2} =
6979    x \superscript       {2} \subscript       {2}
6980$
6981\stopbuffer
6982
6983\typebuffer
6984
6985Gives: \inlinebuffer.
6986
6987\stopnewprimitive
6988
6989\startnewprimitive[title={\prm {indexofcharacter}}]
6990
6991This primitive is more versatile variant of the backward quote operator, so
6992instead of:
6993
6994\starttyping
6995\number`|
6996\number`~
6997\number`\a
6998\number`\q
6999\stoptyping
7000
7001you can say:
7002
7003\starttyping
7004\the\indexofcharacter |
7005\the\indexofcharacter ~
7006\the\indexofcharacter \a
7007\the\indexofcharacter \q
7008\stoptyping
7009
7010In both cases active characters and unknown single character control sequences
7011are valid. In addition this also works:
7012
7013\starttyping
7014\chardef    \foo 128
7015\mathchardef\oof 130
7016
7017\the\indexofcharacter \foo
7018\the\indexofcharacter \oof
7019\stoptyping
7020
7021An important difference is that \prm {indexofcharacter} returns an integer and
7022not a serialized number. A negative value indicates no valid character.
7023
7024\stopnewprimitive
7025
7026\startnewprimitive[title={\prm {indexofregister}}]
7027
7028You can use this instead of \prm {number} for determining the index of a register
7029but it also returns a number when a register value is seen. The result is an
7030integer, not a serialized number.
7031
7032When you have defined a register with one of the \tex {...def} primitives but for
7033some reasons needs to know the register index you can query that:
7034
7035\startbuffer
7036\the\indexofregister \scratchcounterone,
7037\the\indexofregister \scratchcountertwo,
7038\the\indexofregister \scratchwidth,
7039\the\indexofregister \scratchheight,
7040\the\indexofregister \scratchdepth,
7041\the\indexofregister \scratchbox
7042\stopbuffer
7043
7044\typebuffer
7045
7046We lie a little here because in \CONTEXT\ the box index \tex {scratchbox} is
7047actually defined as: \normalexpanded {\typ {\meaningasis \scratchbox}} but it
7048still is a number so it fits in.
7049
7050\getbuffer
7051
7052\stopnewprimitive
7053
7054\startnewprimitive[title={\prm {inherited}}]
7055
7056When this prefix is used in a definition using \prm {let} the target will inherit
7057all the properties of the source.
7058
7059\stopnewprimitive
7060
7061\startnewprimitive[title={\prm {initcatcodetable}}]
7062
7063This initializes the catcode table with the given index.
7064
7065\stopnewprimitive
7066
7067\startnewprimitive[title={\prm {initialpageskip}}]
7068
7069When a page starts the value of this register are used to initialize \prm
7070{pagetotal}, \prm {pagestretch} and \prm {pageshrink}. This make nicer code than
7071using a \prm {topskip} with weird values.
7072
7073\stopnewprimitive
7074
7075\startnewprimitive[title={\prm {initialtopskip}}]
7076
7077When set this one will be used instead of \prm {topskip}. The rationale is that
7078the \prm {topskip} is often also used for side effects and compensation.
7079
7080\stopnewprimitive
7081
7082\startoldprimitive[title={\prm {input}}]
7083
7084There are several ways to use this primitive:
7085
7086\starttyping
7087\input  test
7088\input {test}
7089\input "test"
7090\input 'test'
7091\stoptyping
7092
7093When no suffix is given, \TEX\ will assume the suffix is \type {.tex}. The second
7094one is normally used.
7095
7096\stopoldprimitive
7097
7098\startoldprimitive[title={\prm {inputlineno}}]
7099
7100This integer holds the current linenumber but it is not always reliable.
7101
7102\stopoldprimitive
7103
7104\startoldprimitive[title={\prm {insert}}]
7105
7106This stores content in the insert container with the given index. In \LUAMETATEX\
7107inserts bubble up to outer boxes so we don't have the \quote {deeply buried
7108insert issue}.
7109
7110\stopoldprimitive
7111
7112\startnewprimitive[title={\prm {insertbox}}]
7113
7114This is the accessor for the box (with results) of an insert with the given
7115index. This is equivalent to the \prm {box} in the traditional method.
7116
7117\stopnewprimitive
7118
7119\startnewprimitive[title={\prm {insertcopy}}]
7120
7121This is the accessor for the box (with results) of an insert with the given
7122index. It makes a copy so the original is kept. This is equivalent to a \prm
7123{copy} in the traditional method.
7124
7125\stopnewprimitive
7126
7127\startnewprimitive[title={\prm {insertdepth}}]
7128
7129This is the (current) depth of the inserted material with the given index. It is
7130comparable to the \prm {dp} in the traditional method.
7131
7132\stopnewprimitive
7133
7134\startnewprimitive[title={\prm {insertdistance}}]
7135
7136This is the space before the inserted material with the given index. This is
7137equivalent to \prm {glue} in the traditional method.
7138
7139\stopnewprimitive
7140
7141\startnewprimitive[title={\prm {insertheight}}]
7142
7143This is the (current) depth of the inserted material with the given index. It is
7144comparable to the \prm {ht} in the traditional method.
7145
7146\stopnewprimitive
7147
7148\startnewprimitive[title={\prm {insertheights}}]
7149
7150This is the combined height of the inserted material.
7151
7152\stopnewprimitive
7153
7154\startnewprimitive[title={\prm {insertlimit}}]
7155
7156This is the maximum height that the inserted material with the given index can
7157get. This is equivalent to \prm {dimen} in the traditional method.
7158
7159\stopnewprimitive
7160
7161\startnewprimitive[title={\prm {insertlinedepth}}]
7162
7163This property is used in the balancer where the currently checked insert has no
7164depth. It is experimental.
7165
7166\stopnewprimitive
7167
7168\startnewprimitive[title={\prm {insertlineheight}}]
7169
7170This is a reserved property.
7171
7172\stopnewprimitive
7173
7174\startnewprimitive[title={\prm {insertmaxdepth}}]
7175
7176This is the maximum depth that the inserted material with the given index can
7177get.
7178
7179\stopnewprimitive
7180
7181\startnewprimitive[title={\prm {insertmode}}]
7182
7183In traditional \TEX\ inserts are controlled by a \prm {box}, \prm {dimen}, \prm
7184{glue} and \prm {count} register with the same index. The allocators have to take
7185this into account. When this primitive is set to one a different model is
7186followed with its own namespace. There are more abstract accessors to interface
7187to this. \footnote {The old model might be removed at some point.}
7188
7189\stopnewprimitive
7190
7191\startnewprimitive[title={\prm {insertmultiplier}}]
7192
7193This is the height (contribution) multiplier for the inserted material with the
7194given index. This is equivalent to \prm {count} in the traditional method.
7195
7196\stopnewprimitive
7197
7198\startoldprimitive[title={\prm {insertpenalties}}]
7199
7200This dual purpose internal counter holds the sum of penalties for insertions that
7201got split. When we're the output routine in reports the number of insertions that
7202is kept in store.
7203
7204\stopoldprimitive
7205
7206\startnewprimitive[title={\prm {insertpenalty}}]
7207
7208This is the insert penalty associated with the inserted material with the given
7209index.
7210
7211\stopnewprimitive
7212
7213\startnewprimitive[title={\prm {insertprogress}}]
7214
7215This returns the current accumulated insert height of the insert with the given
7216index.
7217
7218\stopnewprimitive
7219
7220\startnewprimitive[title={\prm {insertshrink}}]
7221
7222When set this will be taken into account. It basically turns ann insert into a
7223kind of glue but without it being a valid break point.
7224
7225\stopnewprimitive
7226
7227\startnewprimitive[title={\prm {insertstorage}}]
7228
7229The value passed will enable (one) or disable (zero) the insert with the given
7230index.
7231
7232\stopnewprimitive
7233
7234\startnewprimitive[title={\prm {insertstoring}}]
7235
7236The value passed will enable (one) or disable (zero) inserts.
7237
7238\stopnewprimitive
7239
7240\startnewprimitive[title={\prm {insertstretch}}]
7241
7242When set this will be taken into account. It basically turns ann insert into a
7243kind of glue but without it being a valid break point.
7244
7245\stopnewprimitive
7246
7247\startnewprimitive[title={\prm {insertunbox}}]
7248
7249This is the accessor for the box (with results) of an insert with the given
7250index. It makes a copy so the original is kept. The content is unpacked and
7251injected. This is equivalent to an \prm {unvbox} in the traditional method.
7252
7253\stopnewprimitive
7254
7255\startnewprimitive[title={\prm {insertuncopy}}]
7256
7257This is the accessor for the box (with results) of an insert with the given
7258index. It makes a copy so the original is kept. The content is unpacked and
7259injected. This is equivalent to the \prm {unvcopy} in the traditional method.
7260
7261\stopnewprimitive
7262
7263\startnewprimitive[title={\prm {insertwidth}}]
7264
7265This is the (current) width of the inserted material with the given index. It is
7266comparable to the \prm {wd} in the traditional method.
7267
7268\stopnewprimitive
7269
7270\startnewprimitive[title={\prm {instance}}]
7271
7272This prefix flags a macro as an instance which is mostly relevant when a macro
7273package want to categorize macros.
7274
7275\stopnewprimitive
7276
7277\startnewprimitive[title={\prm {integerdef}}]
7278
7279You can alias to a count (integer) register with \prm {countdef}:
7280
7281\starttyping
7282\countdef\MyCount134
7283\stoptyping
7284
7285Afterwards the next two are equivalent:
7286
7287\starttyping
7288\MyCount   = 99
7289\count1234 = 99
7290\stoptyping
7291
7292where \type {\MyCount} can be a bit more efficient because no index needs to be
7293scanned. However, in terms of storage the value (here 99) is always in the register
7294so \type {\MyCount} has to get there. This indirectness has the benefit that directly
7295setting the value is reflected in the indirect accessor.
7296
7297\starttyping
7298\integerdef\MyCount = 99
7299\stoptyping
7300
7301This primitive also defines a numeric equivalent but this time the number is stored
7302with the equivalent. This means that:
7303
7304\starttyping
7305\let\MyCopyOfCount = \MyCount
7306\stoptyping
7307
7308will store the {\em current} value of \type {\MyCount} in \type {\MyCopyOfCount} and
7309changing either of them is not reflected in the other.
7310
7311The usual \prm {advance}, \prm {multiply} and \prm {divide} can be used with these
7312integers and they behave like any number. But compared to registers they are actually
7313more a constant.
7314
7315\stopnewprimitive
7316
7317\startoldprimitive[title={\prm {interactionmode}}]
7318
7319This internal integer can be used to set or query the current interaction mode:
7320
7321\starttabulate[||||]
7322\NC \type {\batchmode    } \NC \the\batchmodecode     \NC omits all stops and terminal output \NC \NR
7323\NC \type {\nonstopmode  } \NC \the\nonstopmodecode   \NC omits all stops \NC \NR
7324\NC \type {\scrollmode   } \NC \the\scrollmodecode    \NC omits error stops \NC \NR
7325\NC \type {\errorstopmode} \NC \the\errorstopmodecode \NC stops at every opportunity to interact \NC \NR
7326\stoptabulate
7327
7328% In \LUAMETATEX, for consistency, we have enabled these four as integers after
7329% \prm {the} but we can also decide to remove them and do this. So we leave this
7330% as an undocumented feature. It could have been an \ETEX\ way of abstracting the
7331% numeric values.
7332%
7333% \untraced\permanent\protected\def\batchmode    {\interactionmode\batchmodecode}
7334% \untraced\permanent\protected\def\nonstopmode  {\interactionmode\nonstopmodecode}
7335% \untraced\permanent\protected\def\scrollmode   {\interactionmode\scrollmodecode}
7336% \untraced\permanent\protected\def\errorstopmode{\interactionmode\errorstopmodecode}
7337
7338\stopoldprimitive
7339
7340\startoldprimitive[title={\prm {interlinepenalties}}]
7341
7342This is a more granular variant of \prm {interlinepenalty}: an array of penalties
7343to be put between successive line from the start of a paragraph. The list starts
7344with the number of penalties that gets passed.
7345
7346\stopoldprimitive
7347
7348\startoldprimitive[title={\prm {interlinepenalty}}]
7349
7350This is the penalty that is put between lines.
7351
7352\stopoldprimitive
7353
7354\startoldprimitive[title={\prm {jobname}}]
7355
7356This gives the current job name without suffix: {\tttf \jobname}.
7357
7358\stopoldprimitive
7359
7360\startoldprimitive[title={\prm {kern}}]
7361
7362A kern is injected with the given dimension. For variants that switch to a mode
7363we have \prm {hkern} and \prm {vkern}.
7364
7365\stopoldprimitive
7366
7367\startoldprimitive[title={\prm {language}}]
7368
7369Sets (or returns) the current language, a number. In \LUATEX\ and \LUAMETATEX\
7370the current language is stored in the glyph nodes.
7371
7372\stopoldprimitive
7373
7374\startnewprimitive[title={\prm {lastarguments}}]
7375
7376\startbuffer
7377\def\MyMacro    #1{\the\lastarguments (#1) }          \MyMacro{1}       \crlf
7378\def\MyMacro  #1#2{\the\lastarguments (#1) (#2)}      \MyMacro{1}{2}    \crlf
7379\def\MyMacro#1#2#3{\the\lastarguments (#1) (#2) (#3)} \MyMacro{1}{2}{3} \par
7380
7381\def\MyMacro    #1{(#1)           \the\lastarguments} \MyMacro{1}       \crlf
7382\def\MyMacro  #1#2{(#1) (#2)      \the\lastarguments} \MyMacro{1}{2}    \crlf
7383\def\MyMacro#1#2#3{(#1) (#2) (#3) \the\lastarguments} \MyMacro{1}{2}{3} \par
7384\stopbuffer
7385
7386\typebuffer
7387
7388The value of \prm {lastarguments} can only be trusted in the expansion until
7389another macro is seen and expanded. For instance in these examples, as soon as a
7390character (like the left parenthesis) is seen, horizontal mode is entered and
7391\prm {everypar} is expanded which in turn can involve macros. You can see that
7392in the second block (that is: unless we changed \prm {everypar} in the
7393meantime).
7394
7395{\getbuffer}
7396
7397\stopnewprimitive
7398
7399\startnewprimitive[title={\prm {lastatomclass}}]
7400
7401This returns the class number of the last atom seen in the math input parser.
7402
7403\stopnewprimitive
7404
7405\startnewprimitive[title={\prm {lastboundary}}]
7406
7407This primitive looks back in the list for a user boundary injected with \prm
7408{boundary} and when seen it returns that value or otherwise zero.
7409
7410\stopnewprimitive
7411
7412\startoldprimitive[title={\prm {lastbox}}]
7413
7414When issued this primitive will, if possible, pull the last box from the current
7415list.
7416
7417\stopoldprimitive
7418
7419\startnewprimitive[title={\prm {lastchkdimension}}]
7420
7421When the last check for a dimension with \prm {ifchkdimension} was successful
7422this primitive returns the value.
7423
7424\stopnewprimitive
7425
7426\startnewprimitive[title={\prm {lastchknumber}}]
7427
7428When the last check for an integer with \prm {ifchknumber} was successful this
7429primitive returns the value.
7430
7431\stopnewprimitive
7432
7433\startoldprimitive[title={\prm {lastkern}}]
7434
7435This returns the last kern seen in the list (if possible).
7436
7437\stopoldprimitive
7438
7439\startnewprimitive[title={\prm {lastleftclass}}]
7440
7441This variable registers the first applied math class in a formula.
7442
7443\stopnewprimitive
7444
7445\startoldprimitive[title={\prm {lastlinefit}}]
7446
7447The \ETEX\ manuals explains this parameter in detail but in practice it is enough
7448to know that when set to 1000 spaces in the last line might match those in the
7449previous line. Basically it counters the strong push of a \prm {parfillskip}.
7450
7451\stopoldprimitive
7452
7453\startnewprimitive[title={\prm {lastloopiterator}}]
7454
7455In addition to \prm {currentloopiterator} we have a variant that stores the value
7456in case an unexpanded loop is used:
7457
7458\startbuffer
7459\localcontrolledrepeat 8 { [\the\currentloopiterator\eq\the\lastloopiterator] }
7460\expandedrepeat        8 { [\the\currentloopiterator\eq\the\lastloopiterator] }
7461\unexpandedrepeat      8 { [\the\currentloopiterator\ne\the\lastloopiterator] }
7462\stopbuffer
7463
7464\typebuffer
7465
7466\startlines
7467\getbuffer
7468\stoplines
7469
7470\stopnewprimitive
7471
7472\startnewprimitive[title={\prm {lastnamedcs}}]
7473
7474The example code in the previous section has some redundancy, in the sense that
7475there to be looked up control sequence name \type {mymacro} is assembled twice.
7476This is no big deal in a traditional eight bit \TEX\ but in a \UNICODE\ engine
7477multi|-|byte sequences demand some more processing (although it is unlikely that
7478control sequences have many multi|-|byte \UTF8\ characters).
7479
7480\starttyping
7481\ifcsname mymacro\endcsname
7482    \csname mymacro\endcsname
7483\fi
7484\stoptyping
7485
7486Instead we can say:
7487
7488\starttyping
7489\ifcsname mymacro\endcsname
7490    \lastnamedcs
7491\fi
7492\stoptyping
7493
7494Although there can be some performance benefits another advantage is that it uses
7495less tokens and parsing. It might even look nicer.
7496
7497\stopnewprimitive
7498
7499\startnewprimitive[title={\prm {lastnodesubtype}}]
7500
7501When possible this returns the subtype of the last node in the current node list.
7502Possible values can be queried (for each node type) via \LUA\ helpers.
7503
7504\stopnewprimitive
7505
7506\startoldprimitive[title={\prm {lastnodetype}}]
7507
7508When possible this returns the type of the last node in the current node list.
7509Possible values can be queried via \LUA\ helpers.
7510
7511\stopoldprimitive
7512
7513\startnewprimitive[title={\prm {lastpageextra}}]
7514
7515This reports the last applied (permitted) overshoot.
7516
7517\stopnewprimitive
7518
7519\startnewprimitive[title={\prm {lastparcontext}}]
7520
7521When a paragraph is wrapped up the reason is reported by this state variable.
7522Possible values are:
7523
7524\startfourrows
7525\getbuffer[engine:syntax:parcontextcodes]
7526\stopfourrows
7527
7528\stopnewprimitive
7529
7530\startnewprimitive[title={\prm {lastpartrigger}}]
7531
7532There are several reasons for entering a paragraphs and some are automatic and
7533triggered by other commands that force \TEX\ into horizontal mode.
7534
7535\startfourrows
7536\getbuffer[engine:syntax:partriggercodes]
7537\stopfourrows
7538
7539\stopnewprimitive
7540
7541\startoldprimitive[title={\prm {lastpenalty}}]
7542
7543This returns the last penalty seen in the list (if possible).
7544
7545\stopoldprimitive
7546
7547\startnewprimitive[title={\prm {lastrightclass}}]
7548
7549This variable registers the last applied math class in a formula.
7550
7551\stopnewprimitive
7552
7553\startoldprimitive[title={\prm {lastskip}}]
7554
7555This returns the last glue seen in the list (if possible).
7556
7557\stopoldprimitive
7558
7559\startoldprimitive[title={\prm {lccode}}]
7560
7561When the \prm {lowercase} operation is applied the lowercase code of a character
7562is used for the replacement. This primitive is used to set that code, so it
7563expects two character number. The code is also used to determine what characters
7564make a word suitable for hyphenation, although in \LUATEX\ we introduced the \prm
7565{hj} code for that.
7566
7567\stopoldprimitive
7568
7569\startoldprimitive[title={\prm {leaders}}]
7570
7571See \prm {gleaders} for an explanation.
7572
7573\stopoldprimitive
7574
7575\startoldprimitive[title={\prm {left}}]
7576
7577Inserts the given delimiter as left fence in a math formula.
7578
7579\stopoldprimitive
7580
7581\startoldprimitive[title={\prm {lefthyphenmin}}]
7582
7583This is the minimum number of characters after the last hyphen in a hyphenated
7584word.
7585
7586\stopoldprimitive
7587
7588\startnewprimitive[title={\prm {leftmarginkern}}]
7589
7590The dimension returned is the protrusion kern that has been added (if at all)
7591to the left of the content in the given box.
7592
7593\stopnewprimitive
7594
7595\startoldprimitive[title={\prm {leftskip}}]
7596
7597This skip will be inserted at the left of every line.
7598
7599\stopoldprimitive
7600
7601\startnewprimitive[title={\prm {lefttwindemerits}}]
7602
7603Additional demerits for a glyph sequence at the left edge when a previous line
7604also has that sequence.
7605
7606\stopnewprimitive
7607
7608\startoldprimitive[title={\prm {leqno}}]
7609
7610This primitive stores the (typeset) content (presumably a number) and when the
7611display formula is wrapped that number will end up left of the formula.
7612
7613\stopoldprimitive
7614
7615\startoldprimitive[title={\prm {let}}]
7616
7617Where a \prm {def} creates a new macro, either or not with argument, a \prm {let}
7618creates an alias. You are not limited to aliasing macros, basically everything
7619can be aliased.
7620
7621\stopoldprimitive
7622
7623\startnewprimitive[title={\prm {letcharcode}}]
7624
7625Assigning a meaning to an active character can sometimes be a bit cumbersome;
7626think of using some documented uppercase magic that one tends to forget as it's
7627used only a few times and then never looked at again. So we have this:
7628
7629\startbuffer
7630{\letcharcode 65 1 \catcode 65 13 A : \meaning A}\crlf
7631{\letcharcode 65 2 \catcode 65 13 A : \meaning A}\par
7632\stopbuffer
7633
7634\typebuffer
7635
7636here we define \type {A} as an active charcter with meaning \type {1} in the
7637first line and \type {2} in the second.
7638
7639{\tttf \getbuffer}
7640
7641Normally one will assign a control sequence:
7642
7643\startbuffer
7644{\letcharcode 66 \bf \catcode 66 13 {B   bold}: \meaning B}\crlf
7645{\letcharcode 73 \it \catcode 73 13 {I italic}: \meaning I}\par
7646\stopbuffer
7647
7648\typebuffer
7649
7650Of course \type {\bf} and \type {\it} are \CONTEXT\ specific commands:
7651
7652{\tttf \getbuffer}
7653
7654\stopnewprimitive
7655
7656\startnewprimitive[title={\prm {letcsname}}]
7657
7658It is easy to see that we save two tokens when we use this primitive. As with the
7659\type {..defcs..} variants it also saves a push back of the composed macro name.
7660
7661\starttyping
7662\expandafter\let\csname MyMacro:1\endcsname\relax
7663             \letcsname MyMacro:1\endcsname\relax
7664\stoptyping
7665
7666\stopnewprimitive
7667
7668\startnewprimitive[title={\prm {letfrozen}}]
7669
7670You can explicitly freeze an unfrozen macro:
7671
7672\starttyping
7673\def\MyMacro{...}
7674\letfrozen\MyMacro
7675\stoptyping
7676
7677A redefinition will now give:
7678
7679\starttyping
7680! You can't redefine a frozen macro.
7681\stoptyping
7682
7683\stopnewprimitive
7684
7685\startnewprimitive[title={\prm {letmathatomrule}}]
7686
7687You can change the class for a specific style. This probably only makes sense
7688for user classes. It's one of those features that we used when experimenting
7689with more control.
7690
7691\starttyping
7692\letmathatomrule 4 = 4 4 0 0
7693\letmathatomrule 5 = 5 5 0 0
7694\stoptyping
7695
7696This changes the classes~4 and~5 into class~ 0 in the two script styles and keeps
7697them the same in display and text. We leave it to the reader to ponder how useful
7698this is.
7699
7700\stopnewprimitive
7701
7702\startnewprimitive[title={\prm {letmathparent}}]
7703
7704This primitive takes five arguments: the target class, and four classes that
7705determine the pre penalty class, post penalty class, options class and a dummy
7706class for future use.
7707
7708\stopnewprimitive
7709
7710\startnewprimitive[title={\prm {letmathspacing}}]
7711
7712By default inter|-|class spacing inherits from the ordinary class but you can
7713remap specific combinations is you want:
7714
7715\starttyping
7716\letmathspacing \mathfunctioncode
7717    \mathordinarycode \mathordinarycode
7718    \mathordinarycode \mathordinarycode
7719\stoptyping
7720
7721The first value is the target class, and the nest four tell how it behaves in
7722display, text, script and script script style. Here \typ {\mathfunctioncode} is a
7723\CONTEXT\ specific class (\the\mathfunctioncode), one of the many.
7724
7725\stopnewprimitive
7726
7727\startnewprimitive[title={\prm {letprotected}}]
7728
7729Say that you have these definitions:
7730
7731\startbuffer
7732             \def  \MyMacroA{alpha}
7733\protected   \def  \MyMacroB{beta}
7734             \edef \MyMacroC{\MyMacroA\MyMacroB}
7735\letprotected      \MyMacroA
7736             \edef \MyMacroD{\MyMacroA\MyMacroB}
7737\meaning           \MyMacroC\crlf
7738\meaning           \MyMacroD\par
7739\stopbuffer
7740
7741\typebuffer
7742
7743The typeset meaning in this example is:
7744
7745{\tttf \getbuffer}
7746
7747\stopnewprimitive
7748
7749\startnewprimitive[title={\prm {lettolastnamedcs}}]
7750
7751The \prm {lastnamedcs} primitive is somewhat special as it is a (possible)
7752reference to  a control sequence which is why we have a dedicated variant of
7753\prm {let}.
7754
7755\startbuffer
7756\csname relax\endcsname\let                         \foo\lastnamedcs \meaning\foo
7757\csname relax\endcsname\expandafter\let\expandafter \oof\lastnamedcs \meaning\oof
7758\csname relax\endcsname\lettolastnamedcs            \ofo             \meaning\ofo
7759\stopbuffer
7760
7761\typebuffer % we need oneliners because intermediate csnames kick in
7762
7763These give the following where the first one obviously is not doing what we want
7764and the second one is kind of cumbersome.
7765
7766\startlines
7767\getbuffer
7768\stoplines
7769
7770\stopnewprimitive
7771
7772\startnewprimitive[title={\prm {lettonothing}}]
7773
7774This one let's a control sequence to nothing. Assuming that \type {\empty}
7775is indeed empty, these two lines are equivalent.
7776
7777\starttyping
7778\let         \foo\empty
7779\lettonothing\oof
7780\stoptyping
7781
7782\stopnewprimitive
7783
7784\startoldprimitive[title={\prm {limits}}]
7785
7786This is a modifier: it flags the previous math atom to have its scripts above and
7787below the (summation, product, integral etc.) symbol. In \LUAMETATEX\ this can be
7788any atom (that is: any class). In display mode the location defaults to above and
7789below.
7790
7791Like any modifier it looks back for a math specific element. This means that the
7792following will work well:
7793
7794\starttyping
7795\sum \limits ^2 _3
7796\sum ^2 \limits _3
7797\sum ^2 _3 \limits
7798\sum ^2 _3 \limits \nolimits \limits
7799\stoptyping
7800
7801because scripts are bound to these elements so looking back just sees the element.
7802
7803\stopoldprimitive
7804
7805\startnewprimitive[title={\prm {linebreakchecks}}]
7806
7807The value of this parameter is passed to the linebreak callback so that one can
7808act on it if needed.
7809
7810\stopnewprimitive
7811
7812\startnewprimitive[title={\prm {linebreakoptional}}]
7813
7814This selects the optional text range that is to be used. Optional content is
7815marked with {optionalboundary} nodes.
7816
7817\stopnewprimitive
7818
7819\startnewprimitive[title={\prm {linebreakpasses}}]
7820
7821When set to a positive value it will apply additional line break runs defined
7822with \prm {parpasses} until the criteria set in there are met.
7823
7824\stopnewprimitive
7825
7826\startnewprimitive[title={\prm {linedirection}}]
7827
7828This sets the text direction (1 for \type {r2l}) to the given value but keeps
7829preceding glue into the range.
7830
7831\stopnewprimitive
7832
7833\startoldprimitive[title={\prm {linepenalty}}]
7834
7835Every line gets this penalty attached, so normally it is a small value, like
7836here: \the \linepenalty.
7837
7838\stopoldprimitive
7839
7840\startoldprimitive[title={\prm {lineskip}}]
7841
7842This is the amount of glue that gets added when the distance between lines falls
7843below \prm {lineskiplimit}.
7844
7845\stopoldprimitive
7846
7847\startoldprimitive[title={\prm {lineskiplimit}}]
7848
7849When the distance between two lines becomes less than \prm {lineskiplimit} a \prm
7850{lineskip} glue item is added.
7851
7852\startbuffer
7853\ruledvbox{
7854    \lineskiplimit 0pt \lineskip3pt \baselineskip0pt
7855    \ruledhbox{line 1}
7856    \ruledhbox{line 2}
7857    \ruledhbox{\tx line 3}
7858}
7859\stopbuffer
7860
7861\typebuffer
7862
7863Normally the \prm {baselineskip} kicks in first but here we've set that to zero,
7864so we get two times a 3pt glue injected.
7865
7866\startlocallinecorrection
7867\getbuffer
7868\stoplocallinecorrection
7869
7870\stopoldprimitive
7871
7872\startnewprimitive[title={\prm {localbreakpar}}]
7873
7874This forces a newline in a paragraph without side effects so that for instance
7875\prm {widowpenalties} work as expected in scenarios where using a \prm {par}
7876would have been the solution. This is an experimental primitive!
7877
7878\stopnewprimitive
7879
7880\startnewprimitive[title={\prm {localbrokenpenalty}}]
7881    TODO
7882\stopnewprimitive
7883
7884\startnewprimitive[title={\prm {localcontrol}}]
7885
7886This primitive takes a single token:
7887
7888\startbuffer
7889\edef\testa{\scratchcounter123 \the\scratchcounter}
7890\edef\testc{\testa \the\scratchcounter}
7891\edef\testd{\localcontrol\testa \the\scratchcounter}
7892\stopbuffer
7893
7894\typebuffer
7895
7896The three meanings are:
7897
7898\start \getbuffer
7899\starttabulate[|T|T|]
7900\NC \string\testa \NC \meaning\testa \NC \NR
7901\NC \string\testc \NC \meaning\testc \NC \NR
7902\NC \string\testd \NC \meaning\testd \NC \NR
7903\stoptabulate
7904\stop
7905
7906The \prm {localcontrol} makes that the following token gets expanded so we don't
7907see the yet to be expanded assignment show up in the macro body.
7908
7909\stopnewprimitive
7910
7911\startnewprimitive[title={\prm {localcontrolled}}]
7912
7913The previously described local control feature comes with two extra helpers. The
7914\prm {localcontrolled} primitive takes a token list and wraps this into a local
7915control sidetrack. For example:
7916
7917\startbuffer
7918\edef\testa{\scratchcounter123 \the\scratchcounter}
7919\edef\testb{\localcontrolled{\scratchcounter123}\the\scratchcounter}
7920\stopbuffer
7921
7922\typebuffer
7923
7924The two meanings are:
7925
7926\start \getbuffer
7927\starttabulate[|T|T|]
7928\NC \string\testa \NC \meaningfull\testa \NC \NR
7929\NC \string\testb \NC \meaningfull\testb \NC \NR
7930\stoptabulate
7931\stop
7932
7933The assignment is applied immediately in the expanded definition.
7934
7935\stopnewprimitive
7936
7937\startnewprimitive[title={\prm {localcontrolledendless}}]
7938
7939As the name indicates this will loop forever. You need to explicitly quit the
7940loop with \prm {quitloop} or \prm {quitloopnow}. The first quitter aborts the
7941loop at the start of a next iteration, the second one tries to exit immediately,
7942but is sensitive for interference with for instance nested conditionals. Of
7943course in the next case one can just adapt the final iterator value instead. Here
7944we step by 2:
7945
7946\startbuffer
7947\expandedloop 1 20 2 {%
7948    \ifnum\currentloopiterator>10
7949        \quitloop
7950    \else
7951        [!]
7952    \fi
7953}
7954\stopbuffer
7955
7956\typebuffer
7957
7958This results in:
7959
7960\getbuffer
7961
7962\stopnewprimitive
7963
7964\startnewprimitive[title={\prm {localcontrolledloop}}]
7965
7966As with more of the primitives discussed here, there is a manual in the \quote
7967{lowlevel} subset that goes into more detail. So, here a simple example has to
7968do:
7969
7970\startbuffer
7971\localcontrolledloop 1 100 1 {%
7972    \ifnum\currentloopiterator>6\relax
7973        \quitloop
7974    \else
7975        [\number\currentloopnesting:\number\currentloopiterator]
7976        \localcontrolledloop 1 8 1 {%
7977            (\number\currentloopnesting:\number\currentloopiterator)
7978        }\par
7979    \fi
7980}
7981\stopbuffer
7982
7983\typebuffer
7984
7985Here we see the main loop primitive being used nested. The code shows how we can
7986\prm {quitloop} and have access to the \prm {currentloopiterator} as well as the
7987nesting depth \prm {currentloopnesting}.
7988
7989\startpacked \getbuffer \stoppacked
7990
7991Be aware of the fact that \prm {quitloop} will end the loop at the {\em next}
7992iteration so any content after it will show up. Normally this one will be issued
7993in a condition and we want to end that properly. Also keep in mind that because
7994we use local control (a nested \TEX\ expansion loop) anything you feed back can
7995be injected out of order.
7996
7997The three numbers can be separated by an equal sign which is a trick to avoid
7998look ahead issues that can result from multiple serialized numbers without spaces
7999that indicate the end of sequence of digits.
8000
8001\stopnewprimitive
8002
8003\startnewprimitive[title={\prm {localcontrolledrepeat}}]
8004
8005This one takes one instead three arguments which looks a bit better
8006in simple looping.
8007
8008\stopnewprimitive
8009
8010\startnewprimitive[title={\prm {localinterlinepenalty}}]
8011    TODO
8012\stopnewprimitive
8013
8014\startnewprimitive[title={\prm {localleftbox}}]
8015
8016This sets the box that gets injected at the left of every line.
8017
8018\stopnewprimitive
8019
8020\startnewprimitive[title={\prm {localleftboxbox}}]
8021
8022This returns the box set with \prm {localleftbox}.
8023
8024\stopnewprimitive
8025
8026\startnewprimitive[title={\prm {localmiddlebox}}]
8027
8028This sets the box that gets injected at the left of every line but its width
8029is ignored.
8030
8031\stopnewprimitive
8032
8033\startnewprimitive[title={\prm {localmiddleboxbox}}]
8034
8035This returns the box set with \prm {localmiddlebox}.
8036
8037\stopnewprimitive
8038
8039\startnewprimitive[title={\prm {localpretolerance}}]
8040    TODO
8041\stopnewprimitive
8042
8043\startnewprimitive[title={\prm {localrightbox}}]
8044
8045This sets the box that gets injected at the right of every line.
8046
8047\stopnewprimitive
8048
8049\startnewprimitive[title={\prm {localrightboxbox}}]
8050
8051This returns the box set with \prm {localrightbox}.
8052
8053\stopnewprimitive
8054
8055\startnewprimitive[title={\prm {localtolerance}}]
8056    TODO
8057\stopnewprimitive
8058
8059\startoldprimitive[title={\prm {long}}][obsolete=yes]
8060
8061This original prefix gave the macro being defined the property that it could not
8062have \prm {par} (or the often equivalent empty lines) in its arguments. It was
8063mostly a protection against a forgotten right curly brace, resulting in a so called
8064run|-|away argument. That mattered on a paper terminal or slow system where such a
8065situation should be catched early. In \LUATEX\ it was already optional, and in
8066\LUAMETATEX\ we dropped this feature completely (so that we could introduce others).
8067
8068\stopoldprimitive
8069
8070\startoldprimitive[title={\prm {looseness}}]
8071
8072The number fo lines in the current paragraph will be increased by given number of
8073lines. For this to succeed there need to be enough stretch in the spacing to make
8074that happen. There is some wishful thinking involved.
8075
8076\stopoldprimitive
8077
8078\startoldprimitive[title={\prm {lower}}]
8079
8080This primitive takes two arguments, a dimension and a box. The box is moved down.
8081The operation only succeeds in horizontal mode.
8082
8083\stopoldprimitive
8084
8085\startoldprimitive[title={\prm {lowercase}}]
8086
8087This token processor converts character tokens to their lowercase counterparts as
8088defined per \prm {lccode}. In order to permit dirty tricks active characters are
8089also processed. We don't really use this primitive in \CONTEXT, but for
8090consistency we let it respond to \prm {expand}: \footnote {Instead of providing
8091\type {\lowercased} and \type {\uppercased} primitives that would clash with
8092macros anyway.}
8093
8094\startbuffer
8095\edef           \foo       {\lowercase{tex TeX \TEX}} \meaningless\foo
8096\lowercase{\edef\foo                  {tex TeX \TEX}} \meaningless\foo
8097\edef           \foo{\expand\lowercase{tex TeX \TEX}} \meaningless\foo
8098\stopbuffer
8099
8100\typebuffer
8101
8102Watch how \prm {lowercase} is not expandable but can be forced to. Of course, as
8103the logo macro is protected the \TEX\ logo remains mixed case.
8104
8105\startlines
8106\getbuffer
8107\stoplines
8108
8109\stopoldprimitive
8110
8111\startnewprimitive[title={\prm {lpcode}}]
8112
8113This one can be used to set the left protrusion factor of a glyph in a font and
8114takes three arguments: font, character code and factor. It is kind of obsolete
8115because we can set up vectors at definition time and tweaking from \TEX\ can have
8116side effects because it globally adapts the font.
8117
8118\stopnewprimitive
8119
8120\startnewprimitive[title={\prm {luaboundary}}]
8121
8122This primive inserts a boundary that takes two integer values. Some mechanisms
8123(like math constructors) can trigger a callback when preceded by such a boundary.
8124As we go more mechanisms might do such a check but we don't want a performance
8125hit on \CONTEXT\ as we do so (nor unwanted interference).
8126
8127\stopnewprimitive
8128
8129\startnewprimitive[title={\prm {luabytecode}}]
8130
8131This behaves like \prm {luafunction} but here the number is a byte code register.
8132These bytecodes are in the \typ {lua.bytecode} array.
8133
8134\stopnewprimitive
8135
8136\startnewprimitive[title={\prm {luabytecodecall}}]
8137
8138This behaves like \prm {luafunctioncall} but here the number is a byte code
8139register. These bytecodes are in the \typ {lua.bytecode} array.
8140
8141\stopnewprimitive
8142
8143\startnewprimitive[title={\prm {luacopyinputnodes}}]
8144
8145When set to a positive value this will ensure that when nodes are printed from
8146\LUA\ to \TEX\ copies are used.
8147
8148\stopnewprimitive
8149
8150\startnewprimitive[title={\prm {luadef}}]
8151
8152% \edef\foocode{\ctxlua{
8153%     context(
8154%         context.functions.register(
8155%             function() context("!") end
8156%         )
8157%     )
8158% }}
8159
8160This command relates a (user) command to a \LUA\ function registered in the \typ
8161{lua.lualib_get_functions_table()}, so after:
8162
8163\starttyping
8164\luadef\foo123
8165\stoptyping
8166
8167the \type {\foo} command will trigger the function at index 123. Of course a
8168macro package has to make sure that these definitions are unique. \footnote
8169{Plain \TEX\ established a norm for allocating registers, like \typ {\newdimen}
8170but there is no such convention for \LUA\ functions.}
8171
8172This command is accompanied by \prm {luafunctioncall} and
8173\prm {luafunction}. When we have funciton 123 defined as
8174
8175\starttyping
8176function() tex.sprint("!") end
8177\stoptyping
8178
8179the following:
8180
8181\starttyping
8182(\luafunctioncall  \foocode ?)
8183(\normalluafunction\foocode ?)
8184(\foo                       ?)
8185\stoptyping
8186
8187gives three times \type {(!?)}. But this:
8188
8189\starttyping
8190\edef\oof{\foo                      } \meaning\oof  % protected
8191\edef\oof{\luafunctioncall  \foocode} \meaning\oof  % protected
8192\edef\oof{\normalluafunction\foocode} \meaning\oof  % expands
8193\stoptyping
8194
8195returns:
8196
8197\starttyping
8198macro:!
8199macro:\luafunctioncall 1740
8200macro:!
8201\stoptyping
8202
8203Because the definition command is like any other
8204
8205\starttyping
8206\permanent\protected\luadef\foo123
8207\stoptyping
8208
8209boils down to:
8210
8211\starttyping
8212permanent protected luacall 123
8213\stoptyping
8214
8215\stopnewprimitive
8216
8217\startnewprimitive[title={\prm {luaescapestring}}]
8218
8219This command converts the given (token) list into something that is acceptable
8220for \LUA. It is inherited from \LUATEX\ and not used in \CONTEXT.
8221
8222\startbuffer
8223\directlua { tex.print ("\luaescapestring {{\tt This is a "test".}}") }
8224\stopbuffer
8225
8226\typebuffer
8227
8228Results in: \inlinebuffer\space (Watch the grouping.)
8229
8230\stopnewprimitive
8231
8232\startnewprimitive[title={\prm {luafunction}}]
8233
8234The integer passed to this primitive is the index in the table returned by \typ
8235{lua.lualib_get_functions_table()}. Of course a macro package has to provide
8236reliable management for this. This is a so called convert command so it expands
8237in an expansion context (like an \prm {edef}).
8238
8239\stopnewprimitive
8240
8241\startnewprimitive[title={\prm {luafunctioncall}}]
8242
8243The integer passed to this primitive is the index in the table returned by \typ
8244{lua.lualib_get_functions_table()}. Of course a macro package has to provide
8245reliable management for this. This primitive doesn't expand in an expansion
8246context (like an \prm {edef}).
8247
8248\stopnewprimitive
8249
8250\startnewprimitive[title={\prm {luatexbanner}}]
8251
8252This gives: {\tttf \luatexbanner}.
8253
8254\stopnewprimitive
8255
8256\startnewprimitive[title={\prm {luametatexmajorversion}}]
8257
8258This is the numeric major version number, so it's an integer: \the
8259\luametatexmajorversion, which will only change when we have very drastic
8260changes. The whole repertoire of numbers is:
8261
8262\starttabulate
8263\NC \type {\the\luametatexmajorversion} \NC \the\luametatexmajorversion \NC \NR
8264\NC \type {\the\luametatexminorversion} \NC \the\luametatexminorversion \NC \NR
8265\NC \type {\the\luametatexrelease}      \NC \the\luametatexrelease      \NC \NR
8266\NC \type {\the\luatexversion}          \NC \the\luatexversion          \NC \NR
8267\NC \type {\the\luatexrevision}         \NC \the\luatexrevision         \NC \NR
8268\stoptabulate
8269
8270The last two are there because they might be tested but the first three are the
8271official ones.
8272
8273\stopnewprimitive
8274
8275\startnewprimitive[title={\prm {luametatexminorversion}}]
8276
8277This is a numeric minor version number, so it's an integer: \the
8278\luametatexminorversion. It changes when we add functionality. Intermediate
8279updates
8280
8281\stopnewprimitive
8282
8283\startnewprimitive[title={\prm {luametatexrelease}}]
8284
8285This is a numeric release number, so it's an integer: \the\luametatexrelease. It
8286changes when we are developing functionality.
8287
8288\stopnewprimitive
8289
8290\startnewprimitive[title={\prm {luatexrevision}}]
8291
8292This is an integer. The current value is: {\tttf \number\luatexrevision}.
8293
8294\stopnewprimitive
8295
8296\startnewprimitive[title={\prm {luatexversion}}]
8297
8298This is an integer. The current value is: {\tttf \number\luatexversion}.
8299
8300\stopnewprimitive
8301
8302\startoldprimitive[title={\prm {mark}}][obsolete=yes]
8303
8304The given token list is stored in a node in the current list and might become
8305content of \prm {topmark}, \prm {botmark} or \prm {firstmark} when a page split
8306off, or in the case of a box split in \prm {splitbotmark} or \prm
8307{splitfirstmark}. In \LUAMETATEX\ deeply burried marks bubbly up to an outer box
8308level.
8309
8310\stopoldprimitive
8311
8312\startoldprimitive[title={\prm {marks}}]
8313
8314This command is similar to \prm {mark} but first expects a number of a mark
8315register. Multiple marks were introduced in \ETEX.
8316
8317\stopoldprimitive
8318
8319\startoldprimitive[title={\prm {mathaccent}}][obsolete=yes]
8320
8321This takes a number and a math object to put the accent on. The four byte number
8322has a dummy class byte, a family byte and two index bytes. It is replaced by \prm
8323{Umathaccent} that handles wide fonts.
8324
8325\stopoldprimitive
8326
8327\startnewprimitive[title={\prm {mathatom}}]
8328
8329This operation wraps following content in a atom with the given class. It is part
8330of \LUAMETATEX's extended math support. There are three class related
8331key|/|values: \type {class}, \typ {leftclass} and \typ {rightclass} (or \type
8332{all} for all of them). When none is given this command expects a class number
8333before scanning the content. The \type {options} key expects a bitset but there
8334are also direct option keys, like \type {limits}, \typ {nolimits}, \type
8335{unpack}, \type {unroll}, \type {single}, \type {nooverflow}, \type {void} and
8336\type {phantom}. A \type {source} id can be set, one or more \type {attr}
8337assigned, and for specific purposes \typ {textfont} and \typ {mathfont}
8338directives are accepted. Features like this are discussed in dedicated manuals.
8339
8340\stopnewprimitive
8341
8342\startnewprimitive[title={\prm {mathatomglue}}]
8343
8344This returns the glue that will be inserted between two atoms of a given class
8345for a specific style.
8346
8347\startbuffer
8348\the\mathatomglue \textstyle   1 1
8349\the\mathatomglue \textstyle   0 2
8350\the\mathatomglue \scriptstyle 1 1
8351\the\mathatomglue \scriptstyle 0 2
8352\stopbuffer
8353
8354\typebuffer
8355
8356\startlines \tttf
8357\getbuffer
8358\stoplines
8359
8360\stopnewprimitive
8361
8362\startnewprimitive[title={\prm {mathatomskip}}]
8363
8364\startbuffer
8365$x x$
8366$x \mathatomskip \textstyle   1 1 x$
8367$x \mathatomskip \textstyle   0 2 x$
8368$x \mathatomskip \scriptstyle 1 1 x$
8369$x \mathatomskip \scriptstyle 0 2 x$
8370\stopbuffer
8371
8372This injects a glue with the given style and class pair specification:
8373\inlinebuffer.
8374
8375\typebuffer
8376
8377
8378\stopnewprimitive
8379
8380\startnewprimitive[title={\prm {mathbackwardpenalties}}]
8381
8382See \prm {mathforwardpenalties} for an explanation.
8383
8384\stopnewprimitive
8385
8386\startnewprimitive[title={\prm {mathbeginclass}}]
8387
8388This variable can be set to signal the class that starts the formula (think of an
8389imaginary leading atom).
8390
8391\stopnewprimitive
8392
8393\startoldprimitive[title={\prm {mathbin}}]
8394
8395This operation wraps following content in a atom with class \quote {binary}.
8396
8397\stopoldprimitive
8398
8399\startnewprimitive[title={\prm {mathboundary}}]
8400
8401This primitive is part of an experiment with granular penalties in math. When set
8402nested fences will use the \prm {mathdisplaypenaltyfactor} or \prm
8403{mathinlinepenaltyfactor} to increase nested penalties. A bit more control is
8404possible with \prm {mathboundary}:
8405
8406\starttabulate[||||]
8407\NC 0 \NC begin \NC factor 1000  \NC \NR
8408\NC 1 \NC end   \NC factor 1000  \NC \NR
8409\NC 2 \NC begin \NC given factor \NC \NR
8410\NC 3 \NC end   \NC given factor \NC \NR
8411\stoptabulate
8412
8413These will be used when the mentioned factors are zero. The last two variants
8414expect factor to be given.
8415
8416\stopnewprimitive
8417
8418\startoldprimitive[title={\prm {mathchar}}][obsolete=yes]
8419
8420Replaced by \prm {Umathchar} this old one takes a four byte number: one byte for
8421the class, one for the family an two for the index. The specified character is
8422appended to to the list.
8423
8424\stopoldprimitive
8425
8426\startnewprimitive[title={\prm {mathcharclass}}]
8427
8428Returns the slot (in the font) of the given math character.
8429
8430\startbuffer
8431\the\mathcharclass\Umathchar 4 2 123
8432\stopbuffer
8433
8434\typebuffer
8435
8436The first passed number is the class, so we get: \inlinebuffer.
8437
8438\stopnewprimitive
8439
8440\startoldprimitive[title={\prm {mathchardef}}][obsolete=yes]
8441
8442Replaced by \prm {Umathchardef} this primitive relates a control sequence with a
8443four byte number: one byte for the class, one for the family an two for the
8444index. The defined command will insert that character.
8445
8446\stopoldprimitive
8447
8448\startnewprimitive[title={\prm {mathcharfam}}]
8449
8450Returns the family number of the given math character.
8451
8452\startbuffer
8453\the\mathcharfam\Umathchar 4 2 123
8454\stopbuffer
8455
8456\typebuffer
8457
8458The second passed number is the family, so we get: \inlinebuffer.
8459
8460\stopnewprimitive
8461
8462\startnewprimitive[title={\prm {mathcharslot}}]
8463
8464Returns the slot (or index in the font) of the given math character.
8465
8466\startbuffer
8467\the\mathcharslot\Umathchar 4 2 123
8468\stopbuffer
8469
8470\typebuffer
8471
8472The third passed number is the slot, so we get: \inlinebuffer.
8473
8474\stopnewprimitive
8475
8476\startnewprimitive[title={\prm {mathcheckfencesmode}}]
8477
8478When set to a positive value there will be no warning if a right fence (\prm
8479{right} or \prm {Uright}) is missing.
8480
8481\stopnewprimitive
8482
8483\startoldprimitive[title={\prm {mathchoice}}]
8484
8485This command expects four subformulas, for display, text, script and scriptscript
8486and it will eventually use one of them depending on circumstances later on. Keep
8487in mind that a formula is first scanned and when that is finished the analysis
8488and typesetting happens.
8489
8490\stopoldprimitive
8491
8492\startnewprimitive[title={\prm {mathclass}}]
8493
8494There are build in classes and user classes. The first possible user class is
8495\cldcontext {tex . magicconstants . mathfirstuserclass} and the last one is
8496\cldcontext {tex . magicconstants . mathlastuserclass}. You can better not touch
8497the special classes \quote {all} (\number \mathallcode), \quote {begin} (\number
8498\mathbegincode) and \quote {end} (\number \mathendcode). The basic 8 classes that
8499original \TEX\ provides are of course also present in \LUAMETATEX. In addition we
8500have some that relate to constructs that the engine builds.
8501
8502\starttabulate[|l|l|T|l|]
8503\FL
8504\NC ordinary        \NC ord    \NC \the\mathordinarycode    \NC the default \NR
8505\NC operator        \NC op     \NC \the\mathoperatorcode    \NC small and large operators \NC \NR
8506\NC binary          \NC bin    \NC \the\mathbinarycode      \NC \NC \NR
8507\NC relation        \NC rel    \NC \the\mathrelationcode    \NC \NC \NR
8508\NC open            \NC        \NC \the\mathopencode        \NC \NC \NR
8509\NC close           \NC        \NC \the\mathclosecode       \NC \NC \NR
8510\NC punctuation     \NC punct  \NC \the\mathpunctuationcode \NC \NC \NR
8511\NC variable        \NC        \NC \the\mathvariablecode    \NC adapts to the current family \NC \NR
8512\NC active          \NC        \NC \the\mathactivecode      \NC character marked as such becomes active \NR
8513\NC inner           \NC        \NC \the\mathinnercode       \NC this class is not possible for characters \NR
8514\ML
8515\NC under           \NC        \NC \the\mathundercode       \NC \NC \NR
8516\NC over            \NC        \NC \the\mathovercode        \NC \NC \NR
8517\NC fraction        \NC        \NC \the\mathfractioncode    \NC \NC \NR
8518\NC radical         \NC        \NC \the\mathradicalcode     \NC \NC \NR
8519\NC middle          \NC        \NC \the\mathmiddlecode      \NC \NC \NR
8520\NC accent          \NC        \NC \the\mathaccentcode      \NC \NC \NR
8521\NC fenced          \NC        \NC \the\mathfencedcode      \NC \NC \NR
8522\NC ghost           \NC        \NC \the\mathghostcode       \NC \NC \NR
8523\NC vcenter         \NC        \NC \the\mathvcentercode     \NC \NC \NR
8524\LL
8525\stoptabulate
8526
8527There is no standard for user classes but \CONTEXT\ users should be aware of
8528quite some additional ones that are set up. The engine initialized the default
8529properties of classes (spacing, penalties, etc.) the same as original \TEX.
8530
8531Normally characters have class bound to them but you can (temporarily) overload
8532that one. The \prm {mathclass} primitive expects a class number and a valid
8533character number or math character and inserts the symbol as if it were of the
8534given class; so the original class is replaced.
8535
8536\startbuffer
8537\ruledhbox{$(x)$} and \ruledhbox{$\mathclass 1 `(x\mathclass 1 `)$}
8538\stopbuffer
8539
8540\typebuffer
8541
8542Changing the class is likely to change the spacing, compare \inlinebuffer.
8543
8544\stopnewprimitive
8545
8546\startoldprimitive[title={\prm {mathclose}}]
8547
8548This operation wraps following content in a atom with class \quote {close}.
8549
8550\stopoldprimitive
8551
8552\startoldprimitive[title={\prm {mathcode}}][obsolete=yes]
8553
8554This maps a character to one in a family: the assigned value has one byte for the
8555class, one for the family and two for the index. It has little use in an
8556\OPENTYPE\ math setup.
8557
8558\stopoldprimitive
8559
8560\startnewprimitive[title={\prm {mathdictgroup}}]
8561
8562This is an experimental feature that in due time will be explored in \CONTEXT. It
8563currently has no consequences for rendering.
8564
8565\stopnewprimitive
8566
8567\startnewprimitive[title={\prm {mathdictionary}}]
8568
8569This is an experimental feature that in due time will be explored in \CONTEXT. It
8570currently has no consequences for rendering.
8571
8572\stopnewprimitive
8573
8574\startnewprimitive[title={\prm {mathdictproperties}}]
8575
8576This is an experimental feature that in due time will be explored in \CONTEXT. It
8577currently has no consequences for rendering.
8578
8579\stopnewprimitive
8580
8581\startnewprimitive[title={\prm {mathdirection}}]
8582
8583When set to 1 this will result in \type {r2l} typeset math formulas but of course
8584you then also need to set up math accordingly (which is the case in \CONTEXT).
8585
8586\stopnewprimitive
8587
8588\startnewprimitive[title={\prm {mathdiscretionary}}]
8589
8590The usual \prm {discretionary} command is supported in math mode but it has the
8591disadvantage that one needs to make sure that the content triplet does the math
8592right (especially the style). This command takes an optional class specification.
8593
8594\starttyping
8595\mathdiscretionary                       {+} {+} {+}
8596\mathdiscretionary class \mathbinarycode {+} {+} {+}
8597\stoptyping
8598
8599It uses the same logic as \prm {mathchoice} but in this case we handle three
8600snippets in the current style.
8601
8602A fully automatic mechanism kicks in when a character has a \prm {hmcode} set:
8603
8604\starttabulate[|c|l|p|]
8605\FL
8606\BC bit \BC meaning \BC explanation \NC \NR
8607\TL
8608\NC 1   \NC normal  \NC a discretionary is created with the same components \NC \NR
8609\NC 2   \NC italic  \NC following italic correction is kept with the component \NC \NR
8610\LL
8611\stoptabulate
8612
8613So we can say:
8614
8615\starttyping
8616\hmcode `+ 3
8617\stoptyping
8618
8619When the \type {italic} bit is set italic correction is kept at a linebreak.
8620
8621\stopnewprimitive
8622
8623\startnewprimitive[title={\prm {mathdisplaymode}}]
8624
8625Display mode is entered with two dollars (other characters can be used but the
8626dollars are a convention). Mid paragraph display formulas get a different
8627treatment with respect to the width and indentation than stand alone. When \prm
8628{mathdisplaymode} is larger than zero the double dollars (or equivalents) will
8629behave as inline formulas starting out in \prm {displaystyle} and with \prm
8630{everydisplay} expanded.
8631
8632\stopnewprimitive
8633
8634\startnewprimitive[title={\prm {mathdisplaypenaltyfactor}}]
8635
8636This one is simular to \prm {mathinlinepenaltyfactor} but is used when we're in
8637display style.
8638
8639\stopnewprimitive
8640
8641\startnewprimitive[title={\prm {mathdisplayskipmode}}]
8642
8643A display formula is preceded and followed by vertical glue specified by
8644\prm{abovedisplayskip} and \prm {belowdisplayskip} or \prm
8645{abovedisplayshortskip} and \prm {belowdisplayshortskip}. Spacing \quote {above}
8646is always inserted, even when zero, but the spacing \quote {below} is only
8647inserted when it is non|-|zero. There's also \prm {baselineskip} involved. The
8648way spacing is handled can be influenced with \prm {mathdisplayskipmode}, which
8649takes the following values:
8650
8651% use value reporter
8652
8653\starttabulate[|c|l|]
8654\FL
8655\BC value \BC meaning                                 \NC \NR
8656\TL
8657\NC 0     \NC does the same as any \TEX\ engine       \NC \NR
8658\NC 1     \NC idem                                    \NC \NR
8659\NC 2     \NC only insert spacing when it is not zero \NC \NR
8660\NC 3     \NC never insert spacing                    \NC \NR
8661\LL
8662\stoptabulate
8663
8664\stopnewprimitive
8665
8666\startnewprimitive[title={\prm {mathdoublescriptmode}}]
8667
8668When this parameter has a negative value double scripts trigger an error, so with
8669\prm {superscript}, \prm {nosuperscript}, \prm {indexedsuperscript}, \prm
8670{superprescript}, \prm {nosuperprescript}, \prm {indexedsuperprescript}, \prm
8671{subscript}, \prm {nosubscript}, \prm {indexedsubscript}, \prm {subprescript},
8672\prm {nosubprescript}, \prm {indexedsubprescript} and \prm {primescript}, as well
8673as their (multiple) \type {_} and \type {^} aliases.
8674
8675A value of zero does the normal and inserts a dummy atom (basically a \type {{}})
8676but a positive value is more interesting. Compare these:
8677
8678\startbuffer
8679{\mathdoublescriptmode 0      $x_x_x$}
8680{\mathdoublescriptmode"000000 $x_x_x$}
8681{\mathdoublescriptmode"030303 $x_x_x$}
8682{$x_x_x$}
8683\stopbuffer
8684
8685\typebuffer
8686
8687The three pairs of bytes indicate the main class, left side class and right side
8688class of the inserted atom, so we get this: \inlinebuffer. The last line gives
8689what \CONTEXT\ is configured for.
8690
8691\stopnewprimitive
8692
8693\startnewprimitive[title={\prm {mathendclass}}]
8694
8695This variable can be set to signal the class that ends the formula (think of an
8696imaginary trailing atom).
8697
8698\stopnewprimitive
8699
8700\startnewprimitive[title={\prm {matheqnogapstep}}]
8701
8702The display formula number placement heuristic puts the number on the same line
8703when there is place and then separates it by a quad. In \LUATEX\ we decided to
8704keep that quantity as it can be tight into the math font metrics but introduce
8705a multiplier \prm {matheqnogapstep} that defaults to 1000.
8706
8707\stopnewprimitive
8708
8709\startnewprimitive[title={\prm {mathfontcontrol}}]
8710
8711This bitset controls how the math engine deals with fonts, and provides a way
8712around dealing with inconsistencies in the way they are set up. The \prm
8713{fontmathcontrol} makes it possible to bind options ot a specific math font. In
8714practice, we just set up the general approach which ii possible because we
8715normalize the math fonts and \quote {fix} issues at runtime.
8716
8717\getbuffer[engine:syntax:mathcontrolcodes]
8718
8719\stopnewprimitive
8720
8721\startnewprimitive[title={\prm {mathforwardpenalties}}]
8722
8723Inline math can have multiple atoms and constructs and one can configure the
8724penalties between then bases on classes. In addition it is possible to configure
8725additional penalties starting from the beginning or end using \prm
8726{mathforwardpenalties} and \prm {mathbackwardpenalties}. This is one the features
8727that we added in the perspective of breaking paragraphs heavy on math into lines.
8728It not that easy to come up with useable values.
8729
8730These penalties are added to the regular penalties between atoms. Here is an
8731example, as with other primitives that take more arguments the first number
8732indicates how much follows.
8733
8734\startbuffer
8735$ a + b + c + d + e + f + g + h = x $\par
8736\mathforwardpenalties  3 300 200 100
8737\mathbackwardpenalties 3 250 150  50
8738$ a + b + c + d + e + f + g + h = x $\par
8739\stopbuffer
8740
8741\typebuffer
8742
8743You'll notice that we apply more severe penalties at the edges:
8744
8745{\showmakeup[penalty]\multiply\glyphscale\plustwo \getbuffer}
8746
8747
8748\stopnewprimitive
8749
8750\startnewprimitive[title={\prm {mathgluemode}}]
8751
8752We can influence the way math glue is handled. By default stretch and shrink is applied but
8753this variable can be used to change that. The limit option ensures that the stretch and shrink
8754doesn't go beyond their natural values.
8755
8756\getbuffer[engine:syntax:mathgluecodes]
8757
8758\stopnewprimitive
8759
8760\startnewprimitive[title={\prm {mathgroupingmode}}]
8761
8762Normally a \type {{}} or \type {\bgroup}|-|\type {\egroup} pair in math create a
8763math list. However, users are accustomed to using it also for grouping and then a
8764list being created might not be what a user wants. As an alternative to the more
8765verbose \prm {begingroup}|-|\prm {endgroup} or even less sensitive \prm
8766{beginmathgroup}|-|\prm {endmathgroup} you can set the math grouping mode to a
8767non zero value which makes curly braces (and the aliases) behave as expected.
8768
8769\stopnewprimitive
8770
8771\startnewprimitive[title={\prm {mathinlinepenaltyfactor}}]
8772
8773A math formula can have nested (sub)formulas and one might want to discourage a
8774line break inside those. If this value is non zero it becomes a mulitiplier, so a
8775value of 1000 will make an inter class penalty of 100 into 200 when at nesting
8776level 2 and 500 when at level 5.
8777
8778\stopnewprimitive
8779
8780\startoldprimitive[title={\prm {mathinner}}]
8781
8782This operation wraps following content in a atom with class \quote {inner}. In
8783\LUAMETATEX\ we have more classes and this general wrapper one is therefore kind
8784of redundant.
8785
8786\stopoldprimitive
8787
8788\startnewprimitive[title={\prm {mathleftclass}}]
8789
8790When set this class will be used when a formula starts.
8791
8792\stopnewprimitive
8793
8794\startnewprimitive[title={\prm {mathlimitsmode}}]
8795
8796When this parameter is set to a value larger than zero real dimensions are used
8797and longer limits will not stick out, which is a traditional \TEX\ feature. We
8798could have more advanced control but this will do.
8799
8800\startbuffer
8801\dontleavehmode
8802\ruledhbox{\dm{\left|\integral^{!!!!!!!!!!!}\right|}}
8803\ruledhbox{\dm{\left|\integral^{!!!!!!!!!!} \right|}}
8804\ruledhbox{\dm{\left|\integral^{!!!!!!!!!}  \right|}}
8805\ruledhbox{\dm{\left|\integral^{!!!!!!!!}   \right|}}
8806\ruledhbox{\dm{\left|\integral^{!!!!!!!}    \right|}}
8807\ruledhbox{\dm{\left|\integral^{!!!!!!}     \right|}}
8808\ruledhbox{\dm{\left|\integral^{!!!!!}      \right|}}
8809\ruledhbox{\dm{\left|\integral^{!!!!}       \right|}}
8810\ruledhbox{\dm{\left|\integral^{!!!}        \right|}}
8811\ruledhbox{\dm{\left|\integral^{!!}         \right|}}
8812\ruledhbox{\dm{\left|\integral^{!}          \right|}}
8813\blank
8814\dontleavehmode
8815\ruledhbox{\dm{\left|\integral_{!!!!!!!!!!!}\right|}}
8816\ruledhbox{\dm{\left|\integral_{!!!!!!!!!!} \right|}}
8817\ruledhbox{\dm{\left|\integral_{!!!!!!!!!}  \right|}}
8818\ruledhbox{\dm{\left|\integral_{!!!!!!!!}   \right|}}
8819\ruledhbox{\dm{\left|\integral_{!!!!!!!}    \right|}}
8820\ruledhbox{\dm{\left|\integral_{!!!!!!}     \right|}}
8821\ruledhbox{\dm{\left|\integral_{!!!!!}      \right|}}
8822\ruledhbox{\dm{\left|\integral_{!!!!}       \right|}}
8823\ruledhbox{\dm{\left|\integral_{!!!}        \right|}}
8824\ruledhbox{\dm{\left|\integral_{!!}         \right|}}
8825\ruledhbox{\dm{\left|\integral_{!}          \right|}}
8826\blank
8827\dontleavehmode
8828\ruledhbox{\dm{\left|\integral_{!}      ^{!}              \right|}}
8829\ruledhbox{\dm{\left|\integral_{!!!!!!!}^{!}              \right|}}
8830\ruledhbox{\dm{\left|\integral_{!}      ^{!!!!!!!}        \right|}}
8831\ruledhbox{\dm{\left|\integral_{!}      ^{!!!!!!!!!!}     \right|}}
8832\ruledhbox{\dm{\left|\integral_{!!!!!!!}^{!!!!!!!!!}      \right|}}
8833\ruledhbox{\dm{\left|\integral_{!!!!!!!}^{!!!!!!!!!!!!!!!}\right|}}
8834\ruledhbox{\dm{\left|\integral^{\mtext{for demanding}}_{\mtext{integral freaks}}\right|}}
8835\stopbuffer
8836
8837Compare the zero setting:
8838
8839{\switchtobodyfont[modern]\setupmathoperators[integral][method=limits]\mathlimitsmode 0 \getbuffer}
8840
8841with the positive variant:
8842
8843{\switchtobodyfont[modern]\setupmathoperators[integral][method=limits]\mathlimitsmode 1 \getbuffer}
8844
8845Here we switched to Latin Modern because it's font dependent how serious this
8846issue is. In Pagella all is fine in both modes.
8847
8848\stopnewprimitive
8849
8850\startnewprimitive[title={\prm {mathmainstyle}}]
8851
8852This inspector returns the outermost math style (contrary to \prm {mathstyle}),
8853as we can see in the next examples where use these snippets:
8854
8855\startbuffer
8856\def\foo{(\the\mathmainstyle,\the\mathstyle)}
8857\def\oof{\sqrt[\foo]{\foo}}
8858\def\ofo{\frac{\foo}{\foo}}
8859\def\fof{\mathchoice{\foo}{\foo}{\foo}{\foo}}
8860\stopbuffer
8861
8862\typebuffer \getbuffer
8863
8864When we use the regular math triggers we get this:
8865
8866\startbuffer
8867$\displaystyle     \foo + \oof + \ofo$
8868$\textstyle        \foo + \oof + \ofo$
8869$\displaystyle     \foo + \fof$
8870$\textstyle        \foo + \fof$
8871$\scriptstyle      \foo + \fof$
8872$\scriptscriptstyle\foo + \fof$
8873\stopbuffer
8874
8875\typebuffer
8876
8877\startlines
8878\getbuffer
8879\stoplines
8880
8881But we can also do this:
8882
8883\startbuffer
8884\Ustartmathmode \displaystyle     \foo + \oof + \ofo \Ustopmathmode
8885\Ustartmathmode \textstyle        \foo + \oof + \ofo \Ustopmathmode
8886\Ustartmathmode \displaystyle     \foo + \fof \Ustopmathmode
8887\Ustartmathmode \textstyle        \foo + \fof \Ustopmathmode
8888\Ustartmathmode \scriptstyle      \foo + \fof \Ustopmathmode
8889\Ustartmathmode \scriptscriptstyle\foo + \fof \Ustopmathmode
8890\stopbuffer
8891
8892\typebuffer
8893
8894\startlines
8895\getbuffer
8896\stoplines
8897
8898\stopnewprimitive
8899
8900\startnewprimitive[title={\prm {mathnolimitsmode}}]
8901
8902This parameter influences the placement of scripts after an operator. The reason
8903we have this lays in the fact that traditional \TEX\ uses italic correction and
8904\OPENTYPE\ math does the same but fonts are not consistent in how they set this
8905up. Actually, in \OPENTYPE\ math it's the only reason that there is italic
8906correction. Say that we have a shift $\delta$ determined by the italic correction:
8907
8908\starttabulate[|c|c|c|]
8909\BC mode  \BC top                \BC bottom                \NC \NR
8910\NC $0$   \NC $0$                \NC $-\delta$             \NC \NR
8911\NC $1$   \NC $\delta\times f_t$ \NC $\delta\times f_b$    \NC \NR
8912\NC $2$   \NC $0$                \NC $0$                   \NC \NR
8913\NC $3$   \NC $0$                \NC $-\delta/2$           \NC \NR
8914\NC $4$   \NC $\delta/2$         \NC $-\delta/2$           \NC \NR
8915\NC $>15$ \NC $0$                \NC $-n\times\delta/1000$ \NC \NR
8916\stoptabulate
8917
8918Mode~1 uses two font parameters: $f_b$: \prm {Umathnolimitsubfactor} and $f_t$:
8919\prm {Umathnolimitsupfactor}.
8920
8921\stopnewprimitive
8922
8923\startoldprimitive[title={\prm {mathop}}]
8924
8925This operation wraps following content in a atom with class \quote {operator}.
8926
8927\stopoldprimitive
8928
8929\startoldprimitive[title={\prm {mathopen}}]
8930
8931This operation wraps following content in a atom with class \quote {open}.
8932
8933\stopoldprimitive
8934
8935\startoldprimitive[title={\prm {mathord}}]
8936
8937This operation wraps following content in a atom with class \quote {ordinary}.
8938
8939\stopoldprimitive
8940
8941\startnewprimitive[title={\prm {mathparentstyle}}]
8942
8943This inspector returns the math style used in a construct, so is is either
8944equivalent to \prm {mathmainstyle} or a nested \prm {mathstyle}. For instance
8945in a nested fraction we get this (in \CONTEXT) in display formulas:
8946
8947\def\foo{(\the\mathmainstyle,\the\mathparentstyle,\the\mathstyle)}
8948
8949\dm{
8950    \frac{\frac{\foo}{\foo}}{\frac{\foo}{\foo}} + \foo
8951}
8952
8953but this in inline formulas:
8954
8955\im{
8956    \frac{\frac{\foo}{\foo}}{\frac{\foo}{\foo}} + \foo
8957}
8958
8959where the first element in a nested fraction.
8960
8961\stopnewprimitive
8962
8963\startnewprimitive[title={\prm {mathpenaltiesmode}}]
8964
8965Normally the \TEX\ math engine only inserts penalties when in textstyle. You can
8966force penalties in displaystyle with this parameter. In inline math we always
8967honor penalties, with mode~0 and mode~1 we get this:
8968
8969\pushoverloadmode
8970
8971\startlines
8972{\mathpenaltiesmode=0 \let\mathpenaltiesmode\scratchcounter $\showmakeup[hpenalty]x+2x=0$}
8973{\mathpenaltiesmode=1 \let\mathpenaltiesmode\scratchcounter $\showmakeup[hpenalty]x+2x=1$}
8974\stoplines
8975
8976However in \CONTEXT, where all is done in inline math mode, we set this this
8977parameter to~1, otherwise we wouldn't get these penalties, as shown next:
8978
8979{\mathpenaltiesmode=0 \let\mathpenaltiesmode\scratchcounter \startformula \showmakeup[hpenalty]x+2x=0 \stopformula}
8980{\mathpenaltiesmode=1 \let\mathpenaltiesmode\scratchcounter \startformula \showmakeup[hpenalty]x+2x=1 \stopformula}
8981
8982\popoverloadmode
8983
8984If one uses a callback it is possible to force penalties from there too.
8985
8986\stopnewprimitive
8987
8988\startnewprimitive[title={\prm {mathpretolerance}}]
8989
8990This is used instead of \prm {pretolerance} when a breakpoint is calculated when
8991a math formula starts.
8992
8993\stopnewprimitive
8994
8995\startoldprimitive[title={\prm {mathpunct}}]
8996
8997This operation wraps following content in a atom with class \quote {punctuation}.
8998
8999\stopoldprimitive
9000
9001\startoldprimitive[title={\prm {mathrel}}]
9002
9003This operation wraps following content in a atom with class \quote {relation}.
9004
9005\stopoldprimitive
9006
9007\startnewprimitive[title={\prm {mathrightclass}}]
9008
9009When set this class will be used when a formula ends.
9010
9011\stopnewprimitive
9012
9013\startnewprimitive[title={\prm {mathrulesfam}}]
9014
9015When set, this family will be used for setting rule properties in fractions,
9016under and over.
9017
9018\stopnewprimitive
9019
9020\startnewprimitive[title={\prm {mathrulesmode}}]
9021
9022When set to a non zero value rules (as in fractions and radicals) will be based
9023on the font parameters in the current family.
9024
9025\stopnewprimitive
9026
9027\startnewprimitive[title={\prm {mathscale}}]
9028
9029In \LUAMETATEX\ we can either have a family of three (text, script and
9030scriptscript) fonts or we can use one font that we scale and where we also pass
9031information about alternative shapes for the smaller sizes. When we use this
9032more compact mode this primitive reflects the scale factor used.
9033
9034\startbuffer
9035\im {
9036    \textstyle        \the\mathscale\textfont        \fam\enspace
9037    \scriptstyle      \the\mathscale\scriptfont      \fam\enspace
9038    \scriptscriptstyle\the\mathscale\scriptscriptfont\fam\enspace
9039    \textstyle        \the\mathscale\textfont        \fam\enspace
9040    \scriptstyle      \the\mathscale\textfont        \fam\enspace
9041    \scriptscriptstyle\the\mathscale\textfont        \fam
9042
9043}
9044\stopbuffer
9045
9046What gets reported depends on how math is implemented, where in \CONTEXT\ we can
9047have either normal or compact mode: \inlinebuffer. In compact mode we have the
9048same font three times so then it doesn't matter which of the three is passed.
9049
9050\stopnewprimitive
9051
9052\startnewprimitive[title={\prm {mathscriptsmode}}]
9053
9054There are situations where you don't want \TEX\ to be clever and optimize the
9055position of super- and subscripts by shifting. This parameter can be used to
9056influence this.
9057
9058\startlinecorrection
9059\startcombination[3*2]
9060  {\startoverlay
9061     {\ruledhbox     {\mathscriptsmode 0 0: $x^2_2 + y^x_x + z_2 + w^2$}}
9062     {\ruledhbox{\red \mathscriptsmode 1 1: $x^2_2 + y^x_x + z_2 + w^2$}}
9063   \stopoverlay} {}
9064  {\startoverlay
9065     {\ruledhbox     {\mathscriptsmode 0 0: $x^2_2 + y^x_x + z_2 + w^2$}}
9066     {\ruledhbox{\red \mathscriptsmode 2 2: $x^2_2 + y^x_x + z_2 + w^2$}}
9067   \stopoverlay} {}
9068  {\startoverlay
9069     {\ruledhbox     {\mathscriptsmode 1 1: $x^2_2 + y^x_x + z_2 + w^2$}}
9070     {\ruledhbox{\red \mathscriptsmode 2 2: $x^2_2 + y^x_x + z_2 + w^2$}}
9071   \stopoverlay} {}
9072  {\startoverlay
9073     {\ruledhbox     {\mathscriptsmode 0 0: $x^f_f + y^x_x + z_f + w^f$}}
9074     {\ruledhbox{\red \mathscriptsmode 1 1: $x^f_f + y^x_x + z_f + w^f$}}
9075   \stopoverlay} {1 over 0}
9076  {\startoverlay
9077     {\ruledhbox     {\mathscriptsmode 0 0: $x^f_f + y^x_x + z_f + w^f$}}
9078     {\ruledhbox{\red \mathscriptsmode 2 2: $x^f_f + y^x_x + z_f + w^f$}}
9079   \stopoverlay} {2 over 0}
9080  {\startoverlay
9081     {\ruledhbox     {\mathscriptsmode 1 1: $x^f_f + y^x_x + z_f + w^f$}}
9082     {\ruledhbox{\red \mathscriptsmode 2 2: $x^f_f + y^x_x + z_f + w^f$}}
9083   \stopoverlay} {2 over 1}
9084\stopcombination
9085\stoplinecorrection
9086
9087The next table shows what parameters kick in when:
9088
9089\starttabulate[|l|l|l|p|]
9090\NC       \BC or (1)         \BC and (2)            \BC otherwise       \NC \NR
9091\BC super \NC sup shift up   \NC sup shift up       \NC sup shift up,
9092                                                        sup bot min     \NC \NR
9093\BC sub   \NC sub shift down \NC sub sup shift down \NC sub shift down,
9094                                                        sub top max     \NC \NR
9095\BC both  \NC sub shift down \NC sub sup shift down \NC sub sup shift down,
9096                                                        sub sup vgap,
9097                                                        sup sub bot max \NC \NR
9098\stoptabulate
9099
9100\stopnewprimitive
9101
9102\startnewprimitive[title={\prm {mathslackmode}}]
9103
9104When positive this parameter will make sure that script spacing is discarded when
9105there is no reason to add it.
9106
9107\startlinecorrection
9108\startcombination[nx=3,ny=1]
9109    {\mathslackmode0
9110     \ruledhbox{$\setmscale{3}x^2 + x^2$}\space
9111     \ruledhbox{$\setmscale{3}x^2$}}
9112    {disabled (0)}
9113    {\mathslackmode1
9114     \ruledhbox{$\setmscale{3}x^2 + x^2$}\space
9115     \ruledhbox{$\setmscale{3}x^2$}}
9116    {enabled (1)}
9117    {\startoverlay
9118       {\mathslackmode0     \ruledhbox{$\setmscale{3}x^2 + x^2$}}
9119       {\mathslackmode1 \red\ruledhbox{$\setmscale{3}x^2 + x^2$}}
9120     \stopoverlay
9121     \space
9122     \startoverlay
9123       {\mathslackmode0     \ruledhbox{$\setmscale{3}x^2$}}
9124       {\mathslackmode1 \red\ruledhbox{$\setmscale{3}x^2$}}
9125     \stopoverlay}
9126   {{\red enabled} over disabled}
9127\stopcombination
9128\stoplinecorrection
9129
9130\stopnewprimitive
9131
9132\startnewprimitive[title={\prm {mathspacingmode}}]
9133
9134Zero inter|-|class glue is not injected but setting this parameter to a positive
9135value bypasses that check. This can be handy when checking (tracing) how (and
9136what) spacing is applied. Keep in mind that glue in math is special in the sense
9137that it is not a valid breakpoint. Line breaks in (inline) math are driven by
9138penalties.
9139
9140\stopnewprimitive
9141
9142\startnewprimitive[title={\prm {mathstack}}]
9143
9144There are a few commands in \TEX\ that can behave confusing due to the way they
9145are scanned. Compare these:
9146
9147\starttyping
9148$ 1 \over 2 $
9149$ 1 + x \over 2 + x$
9150$ {1 + x} \over {2 + x}$
9151$ {{1 + x} \over {2 + x}}$
9152\stoptyping
9153
9154A single $1$ is an atom as is the curly braced ${1 + x}$. The two arguments to
9155\prm {over} eventually will get typeset in the style that this fraction
9156constructor uses for the numerator and denominator but on might actually also
9157like to relate that to the circumstances. It is comparable to using a \prm
9158{mathchoice}. In order not to waste runtime on four variants, which itself can have
9159side effects, for instance when counters are involved, \LUATEX\ introduced
9160\prm {mathstack}, used like:
9161
9162\starttyping
9163$\mathstack {1 \over 2}$
9164\stoptyping
9165
9166This \prm {mathstack} command will scan the next brace and opens a new math group
9167with the correct (in this case numerator) math style. The \prm {mathstackstyle}
9168primitive relates to this feature that defaults to \quote {smaller unless already
9169scriptscript}.
9170
9171\stopnewprimitive
9172
9173\startnewprimitive[title={\prm {mathstackstyle}}]
9174
9175This returns the (normally) numerator style but the engine can be configured to
9176default to another style. Although all these in the original \TEX\ engines hard
9177coded style values can be changed in \LUAMETATEX\ it is unlikely to happen. So
9178this primitive will normally return the (current) style \quote {smaller unless
9179already scriptscript}.
9180
9181\stopnewprimitive
9182
9183\startnewprimitive[title={\prm {mathstyle}}]
9184
9185This returns the current math style, so \type {$\the \mathstyle$} gives $\the
9186\mathstyle$.
9187
9188\stopnewprimitive
9189
9190\startnewprimitive[title={\prm {mathstylefontid}}]
9191
9192This returns the font id (a number) of a style|/|family combination. What you get
9193back depends on how a macro package implements math fonts.
9194
9195\startbuffer
9196(\the\mathstylefontid\textstyle        \fam)
9197(\the\mathstylefontid\scriptstyle      \fam)
9198(\the\mathstylefontid\scriptscriptstyle\fam)
9199\stopbuffer
9200
9201\typebuffer
9202
9203In \CONTEXT\ gives: \inlinebuffer.
9204
9205\stopnewprimitive
9206
9207\startoldprimitive[title={\prm {mathsurround}}]
9208
9209The kern injected before and after an inline math formula. In practice it will be
9210set to zero, if only because otherwise nested math will also get that space
9211added. We also have \prm {mathsurroundskip} which, when set, takes precedence.
9212Spacing is controlled by \prm {mathsurroundmode}.
9213
9214\stopoldprimitive
9215
9216\startnewprimitive[title={\prm {mathsurroundmode}}]
9217
9218The possible ways to control spacing around inline math formulas in other manuals
9219and mostly serve as playground.
9220
9221\stopnewprimitive
9222
9223\startnewprimitive[title={\prm {mathsurroundskip}}]
9224
9225When set this one wins over \prm {mathsurround}.
9226
9227\stopnewprimitive
9228
9229\startnewprimitive[title={\prm {maththreshold}}]
9230
9231This is a glue parameter. The amount determines what happens: when it is non zero
9232and the inline formula is less than that value it will become a special kind of
9233box that can stretch and|/| or shrink within the given specification. The par
9234builder will use these stretch and|/| or shrink components but it is up to one of
9235the \LUA\ callbacks to deal with the content eventually (if at all). As this is
9236somewhat specialized, more details can be found on \CONTEXT\ documentation.
9237
9238\stopnewprimitive
9239
9240\startnewprimitive[title={\prm {mathtolerance}}]
9241
9242This is used instead of \prm {tolerance} when a breakpoint is calculated when a
9243math formula starts.
9244
9245\stopnewprimitive
9246
9247\startoldprimitive[title={\prm {maxdeadcycles}}]
9248
9249When the output routine is called this many times and no page is shipped out an
9250error will be triggered. You therefore need to reset its companion counter \prm
9251{deadcycles} if needed. Keep in mind that \LUAMETATEX\ has no real \prm {shipout}
9252because providing a backend is up to the macro package.
9253
9254\stopoldprimitive
9255
9256\startoldprimitive[title={\prm {maxdepth}}]
9257
9258The depth of the page is limited to this value.
9259
9260\stopoldprimitive
9261
9262\startoldprimitive[title={\prm {meaning}}]
9263
9264We start with a primitive that will be used in the following sections. The
9265reported meaning can look a bit different than the one reported by other engines
9266which is a side effect of additional properties and more extensive argument
9267parsing.
9268
9269\startbuffer
9270\tolerant\permanent\protected\gdef\foo[#1]#*[#2]{(#1)(#2)} \meaning\foo
9271\stopbuffer
9272
9273\typebuffer \getbuffer
9274
9275\stopoldprimitive
9276
9277\startnewprimitive[title={\prm {meaningasis}}]
9278
9279Although it is not really round trip with the original due to information
9280being lost this primitive tries to return an equivalent definition.
9281
9282\startbuffer
9283\tolerant\permanent\protected\gdef\foo[#1]#*[#2]{(#1)(#2)} \meaningasis\foo
9284\stopbuffer
9285
9286\typebuffer \getbuffer
9287
9288\stopnewprimitive
9289
9290\startnewprimitive[title={\prm {meaningful}}]
9291
9292This one reports a bit less than \prm {meaningful}.
9293
9294\startbuffer
9295\tolerant\permanent\protected\gdef\foo[#1]#*[#2]{(#1)(#2)} \meaningful\foo
9296\stopbuffer
9297
9298\typebuffer \getbuffer
9299
9300\stopnewprimitive
9301
9302\startnewprimitive[title={\prm {meaningfull}}]
9303
9304This one reports a bit more than \prm {meaning}.
9305
9306\startbuffer
9307\tolerant\permanent\protected\gdef\foo[#1]#*[#2]{(#1)(#2)} \meaningfull\foo
9308\stopbuffer
9309
9310\typebuffer \getbuffer
9311
9312\stopnewprimitive
9313
9314\startnewprimitive[title={\prm {meaningles}}]
9315
9316This one reports a bit less than \prm {meaningless}.
9317
9318\startbuffer
9319\tolerant\permanent\protected\gdef\foo[#1]#*[#2]{(#1)(#2)} \meaningles\foo
9320\stopbuffer
9321
9322\typebuffer \getbuffer
9323
9324\stopnewprimitive
9325
9326\startnewprimitive[title={\prm {meaningless}}]
9327
9328This one reports a bit less than \prm {meaning}.
9329
9330\startbuffer
9331\tolerant\permanent\protected\gdef\foo[#1]#*[#2]{(#1)(#2)} \meaningless\foo
9332\stopbuffer
9333
9334\typebuffer \getbuffer
9335
9336\stopnewprimitive
9337
9338\startoldprimitive[title={\prm {medmuskip}}]
9339
9340A predefined mu skip register that can be used in math (inter atom) spacing. The
9341current value is {\tt \the\medmuskip}. In traditional \TEX\ most inter atom
9342spacing is hard coded using the predefined registers.
9343
9344\stopoldprimitive
9345
9346\startoldprimitive[title={\prm {message}}]
9347
9348Prints the serialization of the (tokenized) argument to the log file and|/|or
9349console.
9350
9351\stopoldprimitive
9352
9353\startoldprimitive[title={\prm {middle}}]
9354
9355Inserts the given delimiter as middle fence in a math formula. In \LUAMETATEX\ it
9356is a full blown fence and not (as in \ETEX) variation of \prm {open}.
9357
9358\stopoldprimitive
9359
9360\startoldprimitive[title={\prm {mkern}}]
9361
9362This one injects a kern node in the current (math) list and expects a value in so
9363called mu units.
9364
9365\stopoldprimitive
9366
9367\startoldprimitive[title={\prm {month}}]
9368
9369This internal number starts out with the month that the job started.
9370
9371\stopoldprimitive
9372
9373\startoldprimitive[title={\prm {moveleft}}]
9374
9375This primitive takes two arguments, a dimension and a box. The box is moved to
9376the left. The operation only succeeds in vertical mode.
9377
9378\stopoldprimitive
9379
9380\startoldprimitive[title={\prm {moveright}}]
9381
9382This primitive takes two arguments, a dimension and a box. The box is moved to
9383the right. The operation only succeeds in vertical mode.
9384
9385\stopoldprimitive
9386
9387\startoldprimitive[title={\prm {mskip}}]
9388
9389The given math glue (in \type {mu} units) is injected in the horizontal list. For
9390this to succeed we need to be in math mode.
9391
9392\stopoldprimitive
9393
9394\startoldprimitive[title={\prm {muexpr}}]
9395
9396This is a companion of \prm {glueexpr} so it handles the optional stretch and
9397shrink components. Here math units (\type {mu}) are expected.
9398
9399\stopoldprimitive
9400
9401\startnewprimitive[title={\prm {mugluespecdef}}]
9402
9403A variant of \prm {gluespecdef} that expects \type {mu} units is:
9404
9405\starttyping
9406\mugluespecdef\MyGlue = 3mu plus 2mu minus 1mu
9407\stoptyping
9408
9409The properties are comparable to the ones described in the previous sections.
9410
9411\stopnewprimitive
9412
9413\startoldprimitive[title={\prm {multiply}}]
9414
9415The given quantity is multiplied by the given integer (that can be preceded by
9416the keyword \quote {by}, like:
9417
9418\starttyping
9419\scratchdimen=10pt \multiply\scratchdimen by 3
9420\stoptyping
9421
9422\stopoldprimitive
9423
9424\startnewprimitive[title={\prm {multiplyby}}]
9425
9426This is slightly more efficient variant of \prm {multiply} that doesn't look for
9427\type {by}. See previous section.
9428
9429\stopnewprimitive
9430
9431\startoldprimitive[title={\prm {muskip}}]
9432
9433This is the accessor for an indexed muskip (muglue) register.
9434
9435\stopoldprimitive
9436
9437\startoldprimitive[title={\prm {muskipdef}}]
9438
9439This command associates a control sequence with a muskip (math skip) register
9440(accessed by number).
9441
9442\stopoldprimitive
9443
9444\startnewprimitive[title={\prm {mutable}}]
9445
9446This prefix flags what follows can be adapted and is not subjected to overload
9447protection.
9448
9449\stopnewprimitive
9450
9451\startoldprimitive[title={\prm {mutoglue}}]
9452
9453The sequence \typ {\the \mutoglue 20mu plus 10mu minus 5mu} gives \the \mutoglue
945420mu plus 10mu minus 5mu.
9455
9456\stopoldprimitive
9457
9458\startnewprimitive[title={\prm {mvlcurrentlyactive}}]
9459
9460This numeric state variable hold the id of the currently active mvl. Unless one
9461is in \prm {beginmlv} it's zero (regular page).
9462
9463\stopnewprimitive
9464
9465\startnewprimitive[title={\prm {nestedloopiterator}}]
9466
9467This is one of the accessors of loop iterators:
9468
9469\startbuffer
9470\expandedrepeat 2 {%
9471    \expandedrepeat 3 {%
9472        (n=\the\nestedloopiterator  1,
9473         p=\the\previousloopiterator1,
9474         c=\the\currentloopiterator)
9475    }%
9476}%
9477\stopbuffer
9478
9479\typebuffer
9480
9481Gives:
9482
9483\getbuffer
9484
9485Where a nested iterator starts relative to innermost loop, the previous one is
9486relative to the outer loop (which is less predictable because we can already be
9487in a loop).
9488
9489\stopnewprimitive
9490
9491\startoldprimitive[title={\prm {newlinechar}}]
9492
9493When something is printed to one of the log channels the character with this code
9494will trigger a linebreak. That also resets some counters that deal with
9495suppressing redundant ones and possible indentation. Contrary to other engines
9496\LUAMETATEX\ doesn't bother about the length of lines.
9497
9498\stopoldprimitive
9499
9500\startoldprimitive[title={\prm {noalign}}]
9501
9502The token list passed to this primitive signals that we don't enter a table row
9503yet but for instance in a \prm {halign} do something between the lines: some
9504calculation or injecting inter-row material. In \LUAMETATEX\ this primitive can
9505be used nested.
9506
9507{\em Todo: discuss keywords.}
9508
9509\stopoldprimitive
9510
9511\startnewprimitive[title={\prm {noaligned}}]
9512
9513The alignment mechanism is kind of special when it comes to expansion because it
9514has to look ahead for a \prm {noalign}. This interferes with for instance
9515protected macros, but using this prefix we get around that. Among the reasons to
9516use protected macros inside an alignment is that they behave better inside for
9517instance \prm {expanded}.
9518
9519\stopnewprimitive
9520
9521\startnewprimitive[title={\prm {noatomruling}}]
9522
9523Spacing in math is based on classes and this primitive inserts a signal that
9524there is no ruling in place here. Basically we have a zero skip glue tagged as
9525non breakable because in math mode glue is not a valid breakpoint unless we have
9526configured inter|-|class penalties.
9527
9528\stopnewprimitive
9529
9530\startnewprimitive[title={\prm {noboundary}}]
9531
9532This inserts a boundary node with no specific property. It can still serve as
9533boundary but is not interpreted in special ways, like the others.
9534
9535\stopnewprimitive
9536
9537\startoldprimitive[title={\prm {noexpand}}]
9538
9539This prefix prevents expansion in a context where expansion happens. Another way
9540to prevent expansion is to define a macro as \prm {protected}.
9541
9542\startbuffer
9543          \def\foo{foo} \edef\oof{we expanded      \foo} \meaning\oof
9544          \def\foo{foo} \edef\oof{we keep \noexpand\foo} \meaning\oof
9545\protected\def\foo{foo} \edef\oof{we keep          \foo} \meaning\oof
9546\stopbuffer
9547
9548\typebuffer
9549
9550\startlines
9551\getbuffer
9552\stoplines
9553
9554\stopoldprimitive
9555
9556\startnewprimitive[title={\prm {nohrule}}]
9557
9558This is a rule but flagged as empty which means that the dimensions kick in as
9559for a normal rule but the backend can decide not to show it.
9560
9561\stopnewprimitive
9562
9563\startoldprimitive[title={\prm {noindent}}]
9564
9565This starts a paragraph. In \LUATEX\ (and \LUAMETATEX) a paragraph starts with a
9566so called par node (see \prm {indent} on how control that. After that comes
9567either \prm {parindent} glue or a horizontal box. The \prm {indent} makes gives
9568them some width, while \prm {noindent} keeps that zero.
9569
9570\stopoldprimitive
9571
9572\startoldprimitive[title={\prm {nolimits}}]
9573
9574This is a modifier: it flags the previous math atom to have its scripts after the
9575the atom (contrary to \prm {limits}. In \LUAMETATEX\ this can be any atom (that
9576is: any class). In display mode the location defaults to above and below.
9577
9578\stopoldprimitive
9579
9580\startnewprimitive[title={\prm {nomathchar}}]
9581
9582This can be used when a math character is expected but not available (or needed).
9583
9584\stopnewprimitive
9585
9586\startoldprimitive[title={\prm {nonscript}}]
9587
9588This prevents \TEX\ from adding inter|-|atom glue at this spot in script or
9589scriptscript mode. It actually is a special glue itself that serves as signal.
9590
9591\stopoldprimitive
9592
9593\startoldprimitive[title={\prm {nonstopmode}}]
9594
9595This directive omits all stops.
9596
9597\stopoldprimitive
9598
9599\startnewprimitive[title={\prm {nooutputboxerror}}]
9600
9601Setting this a positive value will silence the error triggered by a still
9602somewhat full output box after the output routine returns. It is a bitset:
9603
9604\starttabulate[|T||]
9605\NC 0x1 \NC when firing up \NC \NR
9606\NC 0x2 \NC after output   \NC \NR
9607\stoptabulate
9608
9609where values larger than two will always silence,
9610
9611\stopnewprimitive
9612
9613\startnewprimitive[title={\prm {norelax}}]
9614
9615The rationale for this command can be shown by a few examples:
9616
9617\startbuffer
9618\dimen0 1pt \dimen2 1pt \dimen4 2pt
9619\edef\testa{\ifdim\dimen0=\dimen2\norelax N\else Y\fi}
9620\edef\testb{\ifdim\dimen0=\dimen2\relax   N\else Y\fi}
9621\edef\testc{\ifdim\dimen0=\dimen4\norelax N\else Y\fi}
9622\edef\testd{\ifdim\dimen0=\dimen4\relax   N\else Y\fi}
9623\edef\teste{\norelax}
9624\stopbuffer
9625
9626\typebuffer
9627
9628The five meanings are:
9629
9630\start \getbuffer \starttabulate[|T|T|]
9631\NC \string\testa \NC \meaning\testa \NC \NR
9632\NC \string\testb \NC \meaning\testb \NC \NR
9633\NC \string\testc \NC \meaning\testc \NC \NR
9634\NC \string\testd \NC \meaning\testd \NC \NR
9635\NC \string\teste \NC \meaning\teste \NC \NR
9636\stoptabulate \stop
9637
9638So, the \prm {norelax} acts like \prm {relax} but is not pushed back as
9639usual (in some cases).
9640
9641\stopnewprimitive
9642
9643\startnewprimitive[title={\prm {normalizelinemode}}]
9644
9645The \TEX\ engine was not designed to be opened up, and therefore the result of
9646the linebreak effort can differ depending on the conditions. For instance not
9647every line gets the left- or rightskip. The first and last lines have some unique
9648components too. When \LUATEX\ made it possible too get the (intermediate) result
9649manipulating the result also involved checking what one encountered, for instance
9650glue and its origin. In \LUAMETATEX\ we can normalize lines so that they have for
9651instance balanced skips.
9652
9653\starttworows
9654\getbuffer[engine:syntax:normalizelinecodes]
9655\stoptworows
9656
9657The order in which the skips get inserted when we normalize is as follows:
9658
9659\starttabulate
9660\NC \prm {lefthangskip}     \NC the hanging indentation (or zero) \NC \NR
9661\NC \prm {leftskip}         \NC the value even when zero \NC \NR
9662\NC \prm {parfillleftskip}  \NC only on the last line \NC \NR
9663\NC \prm {parinitleftskip}  \NC only on the first line \NC \NR
9664\NC \prm {indentskip}       \NC the amount of indentation \NC \NR
9665\NC \unknown                \NC the (optional) content \NC \NR
9666\NC \prm {parinitrightskip} \NC only on the first line \NC \NR
9667\NC \prm {parfillrightskip} \NC only on the last line \NC \NR
9668\NC \prm {correctionskip}   \NC the correction needed to stay within the \prm {hsize} \NC \NR
9669\NC \prm {rightskip}        \NC the value even when zero \NC \NR
9670\NC \prm {righthangskip}    \NC the hanging indentation (or zero) \NC \NR
9671\stoptabulate
9672
9673The init and fill skips can both show up when we have a single line. The
9674correction skip replaces the traditional juggling with the right skip and shift
9675of the boxed line.
9676
9677For now we leave the other options to your imagination. Some of these can be
9678achieved by callbacks (as we did in older versions of \CONTEXT) but having the
9679engine do the work we get a better performance.
9680
9681\stopnewprimitive
9682
9683\startnewprimitive[title={\prm {normalizeparmode}}]
9684
9685For now we just mention the few options available. It is also worth mentioning that
9686\LUAMETATEX\ tries to balance the direction nodes.
9687
9688\starttworows
9689\getbuffer[engine:syntax:normalizeparcodes]
9690\stoptworows
9691
9692\stopnewprimitive
9693
9694\startnewprimitive[title={\prm {noscript}}]
9695
9696In math we can have multiple pre- and postscript. These get typeset in pairs and
9697this primitive can be used to skip one. More about multiple scripts (and indices)
9698can be found in the \CONTEXT\ math manual.
9699
9700\stopnewprimitive
9701
9702\startnewprimitive[title={\prm {nospaces}}]
9703
9704When \prm {nospaces} is set to~1 no spaces are inserted, when its value is~2 a
9705zero space is inserted. The default value is~0 which means that spaces become
9706glue with properties depending on the font, specific parameters and|/|or space
9707factors determined preceding characters. A value of~3 will inject a glyph node
9708with code \prm {spacechar}.
9709
9710\stopnewprimitive
9711
9712\startnewprimitive[title={\prm {nosubprescript}}]
9713
9714This processes the given script in the current style, so:
9715
9716\startbuffer
9717$ x___2 + x\nosubprescript{2} + x\subprescript{2} $
9718\stopbuffer
9719
9720comes out as: \inlinebuffer.
9721
9722\stopnewprimitive
9723
9724\startnewprimitive[title={\prm {nosubscript}}]
9725
9726This processes the given script in the current style, so:
9727
9728\startbuffer
9729$ x_2 + x\nosubscript{2} + x\subscript{2} $
9730\stopbuffer
9731
9732comes out as: \inlinebuffer.
9733
9734\stopnewprimitive
9735
9736\startnewprimitive[title={\prm {nosuperprescript}}]
9737
9738This processes the given script in the current style, so:
9739
9740\startbuffer
9741$ x^^^2 + x\nosuperprescript{2} + x\superprescript{2} $
9742\stopbuffer
9743
9744comes out as: \inlinebuffer.
9745
9746\stopnewprimitive
9747
9748\startnewprimitive[title={\prm {nosuperscript}}]
9749
9750This processes the given script in the current style, so:
9751
9752\startbuffer
9753$ x^2 + x\nosuperprescript{2} + x\superprescript{2} $
9754\stopbuffer
9755
9756comes out as: \inlinebuffer.
9757
9758\stopnewprimitive
9759
9760\startnewprimitive[title={\prm {novrule}}]
9761
9762This is a rule but flagged as empty which means that the dimensions kick in as
9763for a normal rule but the backend can decide not to show it.
9764
9765\stopnewprimitive
9766
9767\startoldprimitive[title={\prm {nulldelimiterspace}}]
9768
9769In fenced math delimiters can be invisible in which case this parameter
9770determines the amount of space (width) that ghost delimiter takes.
9771
9772\stopoldprimitive
9773
9774\startoldprimitive[title={\prm {nullfont}}]
9775
9776This a symbolic reference to a font with no glyphs and a minimal set of font
9777dimensions.
9778
9779\stopoldprimitive
9780
9781\startoldprimitive[title={\prm {number}}]
9782
9783This \TEX\ primitive serializes the next token into a number, assuming that it
9784is indeed a number, like
9785
9786\starttyping
9787\number`A
9788\number65
9789\number\scratchcounter
9790\stoptyping
9791
9792For counters and such the \prm {the} primitive does the same, but when you're
9793not sure if what follows is a verbose number or (for instance) a counter the
9794\prm {number} primitive is a safer bet, because \type {\the 65} will not work.
9795
9796\stopoldprimitive
9797
9798\startnewprimitive[title={\prm {numericscale}}]
9799
9800This primitive can best be explained by a few examples:
9801
9802\startbuffer
9803\the\numericscale 1323
9804\the\numericscale 1323.0
9805\the\numericscale 1.323
9806\the\numericscale 13.23
9807\stopbuffer
9808
9809\typebuffer
9810
9811In several places \TEX\ uses a scale but due to the lack of floats it then uses
98121000 as 1.0 replacement. This primitive can be used for \quote {real} scales:
9813
9814\startlines \getbuffer \stoplines
9815
9816\stopnewprimitive
9817
9818\startnewprimitive[title={\prm {numericscaled}}]
9819
9820This is a variant if \prm {numericscale}:
9821
9822\startbuffer
9823\scratchcounter 1000
9824\the\numericscaled 1323   \scratchcounter
9825\the\numericscaled 1323.0 \scratchcounter
9826\the\numericscaled 1.323  \scratchcounter
9827\the\numericscaled 13.23  \scratchcounter
9828\stopbuffer
9829
9830\typebuffer
9831
9832The second number gets multiplied by the first fraction:
9833
9834\startlines \getbuffer \stoplines
9835
9836\stopnewprimitive
9837
9838\startoldprimitive[title={\prm {numexpr}}]
9839
9840This primitive was introduced by \ETEX\ and supports a simple expression syntax:
9841
9842\startbuffer
9843\the\numexpr 10 * (1 + 2 - 5) / 2 \relax
9844\stopbuffer
9845
9846\typebuffer
9847
9848gives: \inlinebuffer. You can mix in symbolic integers and dimensions.
9849
9850\stopoldprimitive
9851
9852\startnewprimitive[title={\prm {numexpression}}]
9853
9854The normal \prm {numexpr} primitive understands the \type {+}, \type {-}, \type
9855{*} and \type {/} operators but in \LUAMETATEX\ we also can use \type {:} for a
9856non rounded integer division (think of \LUA's \type {//}). if you want more than
9857that, you can use the new expression primitive where you can use the following
9858operators.
9859
9860\starttabulate[||cT|cT|]
9861\BC add       \NC +                    \NC        \NC \NR
9862\BC subtract  \NC -                    \NC        \NC \NR
9863\BC multiply  \NC *                    \NC        \NC \NR
9864\BC divide    \NC / :                  \NC        \NC \NR
9865\BC mod       \NC \letterpercent       \NC mod    \NC \NR
9866\BC band      \NC &                    \NC band   \NC \NR
9867\BC bxor      \NC ^                    \NC bxor   \NC \NR
9868\BC bor       \NC \letterbar \space v  \NC bor    \NC \NR
9869\BC and       \NC &&                   \NC and    \NC \NR
9870\BC or        \NC \letterbar\letterbar \NC or     \NC \NR
9871\BC setbit    \NC <undecided>          \NC bset   \NC \NR
9872\BC resetbit  \NC <undecided>          \NC breset \NC \NR
9873\BC left      \NC <<                   \NC        \NC \NR
9874\BC right     \NC >>                   \NC        \NC \NR
9875\BC less      \NC <                    \NC        \NC \NR
9876\BC lessequal \NC <=                   \NC        \NC \NR
9877\BC equal     \NC = ==                 \NC        \NC \NR
9878\BC moreequal \NC >=                   \NC        \NC \NR
9879\BC more      \NC >                    \NC        \NC \NR
9880\BC unequal   \NC <> != \lettertilde = \NC        \NC \NR
9881\BC not       \NC ! \lettertilde       \NC not    \NC \NR
9882\stoptabulate
9883
9884An example of the verbose bitwise operators is:
9885
9886\starttyping
9887\scratchcounter = \numexpression
9888    "00000 bor "00001 bor "00020 bor "00400 bor "08000 bor "F0000
9889\relax
9890\stoptyping
9891
9892In the table you might have notices that some operators have equivalents. This
9893makes the scanner a bit less sensitive for catcode regimes.
9894
9895When \prm {tracingexpressions} is set to one or higher the intermediate \quote
9896{reverse polish notation} stack that is used for the calculation is shown, for
9897instance:
9898
9899\starttyping
99004:8: {numexpression rpn: 2 5 > 4 5 > and}
9901\stoptyping
9902
9903When you want the output on your console, you need to say:
9904
9905\starttyping
9906\tracingexpressions 1
9907\tracingonline      1
9908\stoptyping
9909
9910Here are some things that \prm {numexpr} is not suitable for but \prm
9911{numexpression} can handle:
9912
9913\starttyping
9914\scratchcounter = \numexpression
9915    "00000 bor "00001 bor "00020 bor "00400 bor "08000 bor "F0000
9916\relax
9917
9918\ifcase \numexpression
9919    (\scratchcounterone > 5) && (\scratchcountertwo > 5)
9920\relax yes\else nop\fi
9921\stoptyping
9922
9923\stopnewprimitive
9924
9925\startoldprimitive[title={\prm {omit}}]
9926
9927This primitive cancels the template set for the upcoming cell. Often it is used
9928in combination with \prm {span}.
9929
9930\stopoldprimitive
9931
9932\startnewprimitive[title={\prm {optionalboundary}}]
9933
9934This boundary is used to mark optional content. An positive \prm
9935{optionalboundary} starts a range and a zero one ends it. Nesting is not
9936supported. Optional content is considered when an additional paragraph pass
9937enables it as part of its recipe.
9938
9939\stopnewprimitive
9940
9941\startoldprimitive[title={\prm {or}}]
9942
9943This traditional primitive is part of the condition testing mechanism and relates
9944to an \prm {ifcase} test (or a similar test to be introduced in later
9945sections). Depending on the value, \TEX\ will do a fast scanning till the right
9946\prm {or} is seen, then it will continue expanding till it sees a \prm {or}
9947or \prm {else} or \prm {orelse} (to be discussed later). It will then do a
9948fast skipping pass till it sees an \prm {fi}.
9949
9950\stopoldprimitive
9951
9952\startnewprimitive[title={\prm {orelse}}]
9953
9954This primitive provides a convenient way to flatten your conditional tests. So
9955instead of
9956
9957\starttyping
9958\ifnum\scratchcounter<-10
9959    too small
9960\else\ifnum\scratchcounter>10
9961    too large
9962\else
9963    just right
9964\fi\fi
9965\stoptyping
9966
9967You can say this:
9968
9969\starttyping
9970\ifnum\scratchcounter<-10
9971    too small
9972\orelse\ifnum\scratchcounter>10
9973    too large
9974\else
9975    just right
9976\fi
9977\stoptyping
9978
9979You can mix tests and even the case variants will work in most cases \footnote {I
9980just play safe because there are corner cases that might not work yet.}
9981
9982\starttyping
9983\ifcase\scratchcounter          zero
9984\or                             one
9985\or                             two
9986\orelse\ifnum\scratchcounter<10 less than ten
9987\else                           ten or more
9988\fi
9989\stoptyping
9990
9991Performance wise there are no real benefits although in principle there is a bit
9992less housekeeping involved than with nested checks. However you might like this:
9993
9994\starttyping
9995\ifnum\scratchcounter<-10
9996    \expandafter\toosmall
9997\orelse\ifnum\scratchcounter>10
9998    \expandafter\toolarge
9999\else
10000    \expandafter\justright
10001\fi
10002\stoptyping
10003
10004over:
10005
10006\starttyping
10007\ifnum\scratchcounter<-10
10008    \expandafter\toosmall
10009\else\ifnum\scratchcounter>10
10010    \expandafter\expandafter\expandafter\toolarge
10011\else
10012    \expandafter\expandafter\expandafter\justright
10013\fi\fi
10014\stoptyping
10015
10016or the more \CONTEXT\ specific:
10017
10018\starttyping
10019\ifnum\scratchcounter<-10
10020    \expandafter\toosmall
10021\else\ifnum\scratchcounter>10
10022    \doubleexpandafter\toolarge
10023\else
10024    \doubleexpandafter\justright
10025\fi\fi
10026\stoptyping
10027
10028But then, some \TEX ies like complex and obscure code and throwing away working
10029old code that took ages to perfect and get working and also showed that one
10030masters \TEX\ might hurt.
10031
10032There is a nice side effect of this mechanism. When you define:
10033
10034\starttyping
10035\def\quitcondition{\orelse\iffalse}
10036\stoptyping
10037
10038you can do this:
10039
10040\starttyping
10041\ifnum\count0<10
10042    less
10043\orelse\ifnum\count0=10
10044    equal
10045    \quitcondition
10046    indeed
10047\else
10048    more
10049\fi
10050\stoptyping
10051
10052Of course it is only useful at the right level, so you might end up with cases like
10053
10054\starttyping
10055\ifnum\count0<10
10056    less
10057\orelse\ifnum\count0=10
10058    equal
10059    \ifnum\count2=30
10060        \expandafter\quitcondition
10061    \fi
10062    indeed
10063\else
10064    more
10065\fi
10066\stoptyping
10067
10068\stopnewprimitive
10069
10070\startnewprimitive[title={\prm {orphanlinefactors}}]
10071
10072Normally this (specification) parameter is set in a \prm {parpasses} as it
10073supports multiple orphan penalties with a different weight (starting from the
10074last candidate).
10075
10076\stopnewprimitive
10077
10078\startnewprimitive[title={\prm {orphanpenalties}}]
10079
10080This an (single entry) array parameter: first the size is given followed by that
10081amount of penalties. These penalties are injected before spaces, going backward
10082from the end of a paragraph. When we see a math node with a penalty set then we
10083take the max and jump over a (preceding) skip.
10084
10085\stopnewprimitive
10086
10087\startnewprimitive[title={\prm {orunless}}]
10088
10089This is the negated variant of \prm {orelse} (prefixing that one with \tex
10090{unless} doesn't work well.
10091
10092\stopnewprimitive
10093
10094\startoldprimitive[title={\prm {outer}}][obsolete=yes]
10095
10096An outer macro is one that can only be used at the outer level. This property is
10097no longer supported. Like \prm {long}, the \prm {outer} prefix is now an
10098no|-|op (and we don't expect this to have unfortunate side effects).
10099
10100\stopoldprimitive
10101
10102\startoldprimitive[title={\prm {output}}]
10103
10104This token list register holds the code that will be expanded when \TEX\ enters
10105the output routine. That code is supposed to do something with the content in
10106the box with number \prm {outputbox}. By default this is box 255 but that can be
10107changed with \prm {outputbox}.
10108
10109\stopoldprimitive
10110
10111\startnewprimitive[title={\prm {outputbox}}]
10112
10113This is where the split off page contend ends up when the output routine is
10114triggered.
10115
10116\stopnewprimitive
10117
10118\startoldprimitive[title={\prm {outputpenalty}}]
10119
10120This is the penalty that triggered the output routine.
10121
10122\stopoldprimitive
10123
10124\startoldprimitive[title={\prm {over}}][obsolete=yes]
10125
10126This math primitive is actually a bit of a spoiler for the parser as it is one of
10127the few that looks back. The \prm {Uover} variant is different and takes two
10128arguments. We leave it to the user to predicts the results of:
10129
10130\starttyping
10131$    {1} \over {x}    $
10132$     1  \over  x     $
10133$    12  \over  x / y $
10134$ a + 1  \over {x}    $
10135\stoptyping
10136
10137and:
10138
10139\starttyping
10140$  \textstyle 1  \over x  $
10141$ {\textstyle 1} \over x  $
10142$  \textstyle {1 \over x} $
10143\stoptyping
10144
10145It's one of the reasons why macro packages provide \type {\frac}.
10146
10147\stopoldprimitive
10148
10149\startoldprimitive[title={\prm {overfullrule}}]
10150
10151When an overfull box is encountered a rule can be shown in the margin and this
10152parameter sets its width. For the record: \CONTEXT\ does it different.
10153
10154\stopoldprimitive
10155
10156\startoldprimitive[title={\prm {overline}}]
10157
10158This is a math specific primitive that draws a line over the given content. It is
10159a poor mans replacement for a delimiter. The thickness is set with \prm
10160{Umathoverbarrule}, the distance between content and rule is set by \prm
10161{Umathoverbarvgap} and \prm {Umathoverbarkern} is added above the rule. The style
10162used for the content under the rule can be set with \prm {Umathoverlinevariant}.
10163
10164Because \CONTEXT\ set up math in a special way, the following example:
10165
10166\startbuffer[demo]
10167\normaloverline {
10168    \blackrule[color=red, height=1ex,depth=0ex,width=2cm]%
10169    \kern-2cm
10170    \blackrule[color=blue,height=0ex,depth=.5ex,width=2cm]
10171    x + x
10172}
10173\stopbuffer
10174
10175\typebuffer[demo]
10176
10177gives: \ruledhbox {$\getbuffer[demo]$}, while:
10178
10179\startbuffer[setup]
10180\mathfontcontrol\zerocount
10181\Umathoverbarkern\allmathstyles10pt
10182\Umathoverbarvgap\allmathstyles5pt
10183\Umathoverbarrule\allmathstyles2.5pt
10184\Umathoverlinevariant\textstyle\scriptstyle
10185\stopbuffer
10186
10187\typebuffer[setup]
10188
10189gives this: \ruledhbox {$\getbuffer[setup,demo]$}. We have to disable the related
10190\prm {mathfontcontrol} bits because otherwise the thickness is taken from the font. The
10191variant is just there to overload the (in traditional \TEX\ engines) default.
10192
10193\stopoldprimitive
10194
10195\startnewprimitive[title={\prm {overloaded}}]
10196
10197This prefix can be used to overload a frozen macro.
10198
10199\stopnewprimitive
10200
10201\startnewprimitive[title={\prm {overloadmode}}]
10202
10203The overload protection mechanism can be used to prevent users from redefining
10204a control sequence. The mode can have several values, the higher the more strict
10205we are:
10206
10207\starttabulate[||||||||]
10208    \NC   \NC         \NC immutable \NC permanent \NC primitive \NC frozen \NC instance \NC \NR
10209    \NC 1 \NC warning \NC +         \NC +         \NC +         \NC        \NC          \NC \NR
10210    \NC 2 \NC error   \NC +         \NC +         \NC +         \NC        \NC          \NC \NR
10211    \NC 3 \NC warning \NC +         \NC +         \NC +         \NC +      \NC          \NC \NR
10212    \NC 4 \NC error   \NC +         \NC +         \NC +         \NC +      \NC          \NC \NR
10213    \NC 5 \NC warning \NC +         \NC +         \NC +         \NC +      \NC +        \NC \NR
10214    \NC 6 \NC error   \NC +         \NC +         \NC +         \NC +      \NC +        \NC \NR
10215\stoptabulate
10216
10217When you set a high error value, you can of course temporary lower or even zero
10218the mode. In \CONTEXT\ all macros and quantities are tagged so there setting the
10219mode to~6 gives a proper protection against overloading. We need to zero the mode
10220when we load for instance tikz, so when you use that generic package, you loose
10221some.
10222
10223\stopnewprimitive
10224
10225\startnewprimitive[title={\prm {overshoot}}]
10226
10227This primitive is a companion to \prm {badness} and reports how much a box
10228overflows.
10229
10230\startbuffer
10231\setbox0\hbox to 1em {mmm} \the\badness\quad\the\overshoot
10232\setbox0\hbox         {mm} \the\badness\quad\the\overshoot
10233\setbox0\hbox to 3em   {m} \the\badness\quad\the\overshoot
10234\stopbuffer
10235
10236\typebuffer
10237
10238This reports:
10239
10240\startlines
10241\getbuffer
10242\stoplines
10243
10244And:
10245
10246\startbuffer
10247\hbox to 2cm {does it fit}               \the\overshoot
10248\hbox to 2cm {does it fit in here}       \the\overshoot
10249\hbox to 2cm {how much does fit in here} \the\overshoot
10250\stopbuffer
10251
10252\typebuffer
10253
10254gives:
10255
10256\startlines
10257\getbuffer
10258\stoplines
10259
10260When traditional \TEX\ wraps up the lines in a paragraph it uses a mix of shift
10261(a box property) to position the content suiting the hanging indentation and|/|or
10262paragraph shape, and fills up the line using right skip glue, also in order to
10263silence complaints in packaging. In \LUAMETATEX\ the lines can be normalized so
10264that they all have all possible skips to the left and right (even if they're
10265zero). The \prm {overshoot} primitive fits into this picture and is present as a
10266compensation glue. This all fits better in a situation where the internals are
10267opened up via \LUA.
10268
10269\stopnewprimitive
10270
10271\startoldprimitive[title={\prm {overwithdelims}}][obsolete=yes]
10272
10273This is a variant of \prm {over} but with delimiters. It has a more advanced
10274upgrade in \prm {Uoverwithdelims}.
10275
10276\stopoldprimitive
10277
10278\startnewprimitive[title={\prm {pageboundary}}]
10279
10280In order to avoid side effects of triggering the page builder with a specific
10281penalty we can use this primitive which expects a value that actually gets
10282inserted as zero penalty before triggering the page builder callback. Think of
10283adding a no|-|op to the contribution list. We fake a zero penalty so that all
10284gets processed. The main rationale is that we get a better indication of what we
10285do. Of course a callback can remove this node so that it is never seen.
10286Triggering from the callback is not doable. Consider this experimental code
10287(which is actually used in \CONTEXT\ anyway).
10288
10289\stopnewprimitive
10290
10291\startnewprimitive[title={\prm {pagedepth}}]
10292
10293This page property holds the depth of the page.
10294
10295\stopnewprimitive
10296
10297\startoldprimitive[title={\prm {pagediscards}}]
10298
10299The left|-|overs after a page is split of the main vertical list when glue and
10300penalties are normally discarded. The discards can be pushed back in (for
10301instance) trial runs.
10302
10303\stopoldprimitive
10304
10305\startnewprimitive[title={\prm {pageexcess}}]
10306
10307This page property hold the amount of overflow when a page break occurs.
10308
10309\stopnewprimitive
10310
10311\startnewprimitive[title={\prm {pageextragoal}}]
10312
10313This (experimental) dimension will be used when the page overflows but a bit of
10314overshoot is considered okay.
10315
10316\stopnewprimitive
10317
10318\startoldprimitive[title={\prm {pagefilllstretch}}]
10319
10320The accumulated amount of third order stretch on the current page.
10321
10322\stopoldprimitive
10323
10324\startoldprimitive[title={\prm {pagefillstretch}}]
10325
10326The accumulated amount of second order stretch on the current page.
10327
10328\stopoldprimitive
10329
10330\startoldprimitive[title={\prm {pagefilstretch}}]
10331
10332The accumulated amount of first order stretch on the current page.
10333
10334\stopoldprimitive
10335
10336\startnewprimitive[title={\prm {pagefistretch}}]
10337
10338The accumulated amount of zero order stretch on the current page.
10339
10340\stopnewprimitive
10341
10342\startoldprimitive[title={\prm {pagegoal}}]
10343
10344The target height of a page (the running text). This value will be decreased by
10345the height of inserts something to keep into mind when messing around with this
10346and other (pseudo) page related parameters like \prm {pagetotal}.
10347
10348\stopoldprimitive
10349
10350\startnewprimitive[title={\prm {pagelastdepth}}]
10351
10352The accumulated depth of the current page.
10353
10354\stopnewprimitive
10355
10356\startnewprimitive[title={\prm {pagelastfilllstretch}}]
10357
10358The accumulated amount of third order stretch on the current page. Contrary to
10359\prm {pagefilllstretch} this is the really contributed amount, not the upcoming.
10360
10361\stopnewprimitive
10362
10363\startnewprimitive[title={\prm {pagelastfillstretch}}]
10364
10365The accumulated amount of second order stretch on the current page. Contrary to
10366\prm {pagefillstretch} this is the really contributed amount, not the upcoming.
10367
10368\stopnewprimitive
10369
10370\startnewprimitive[title={\prm {pagelastfilstretch}}]
10371
10372The accumulated amount of first order stretch on the current page. Contrary to
10373\prm {pagefilstretch} this is the really contributed amount, not the upcoming.
10374
10375\stopnewprimitive
10376
10377\startnewprimitive[title={\prm {pagelastfistretch}}]
10378
10379The accumulated amount of zero order stretch on the current page. Contrary to
10380\prm {pagefistretch} this is the really contributed amount, not the upcoming.
10381
10382\stopnewprimitive
10383
10384\startnewprimitive[title={\prm {pagelastheight}}]
10385
10386The accumulated height of the current page.
10387
10388\stopnewprimitive
10389
10390\startnewprimitive[title={\prm {pagelastshrink}}]
10391
10392The accumulated amount of shrink on the current page. Contrary to \prm
10393{pageshrink} this is the really contributed amount, not the upcoming.
10394
10395\stopnewprimitive
10396
10397\startnewprimitive[title={\prm {pagelaststretch}}]
10398
10399The accumulated amount of stretch on the current page. Contrary to \prm
10400{pagestretch} this is the really contributed amount, not the upcoming.
10401
10402\stopnewprimitive
10403
10404\startoldprimitive[title={\prm {pageshrink}}]
10405
10406The accumulated amount of shrink on the current page.
10407
10408\stopoldprimitive
10409
10410\startoldprimitive[title={\prm {pagestretch}}]
10411
10412The accumulated amount of stretch on the current page.
10413
10414\stopoldprimitive
10415
10416\startoldprimitive[title={\prm {pagetotal}}]
10417
10418The accumulated page total (height) of the current page.
10419
10420\stopoldprimitive
10421
10422\startnewprimitive[title={\prm {pagevsize}}]
10423
10424This parameter, when set, is used as the target page height. This lessens the
10425change of \prm {vsize} interfering.
10426
10427\stopnewprimitive
10428
10429\startoldprimitive[title={\prm {par}}]
10430
10431This is the explicit \quote {finish paragraph} command. Internally we distinguish
10432a par triggered by a new line, as side effect of another primitive or this \prm
10433{par} command.
10434
10435\stopoldprimitive
10436
10437\startnewprimitive[title={\prm {parametercount}}]
10438
10439The number of parameters passed to the current macro.
10440
10441\stopnewprimitive
10442
10443\startnewprimitive[title={\prm {parameterdef}}]
10444
10445Here is an example of binding a variable to a parameter. The alternative is of
10446course to use an \prm {edef}.
10447
10448\startbuffer
10449\def\foo#1#2%
10450  {\parameterdef\MyIndexOne\plusone % 1
10451   \parameterdef\MyIndexTwo\plustwo % 2
10452   \oof{P}\oof{Q}\oof{R}\norelax}
10453
10454\def\oof#1%
10455  {<1:\MyIndexOne><1:\MyIndexOne>%
10456   #1%
10457   <2:\MyIndexTwo><2:\MyIndexTwo>}
10458
10459\foo{A}{B}
10460\stopbuffer
10461
10462\typebuffer
10463
10464The outcome is:
10465
10466\getbuffer
10467
10468\stopnewprimitive
10469
10470\startnewprimitive[title={\prm {parameterindex}}]
10471
10472This gives the zero based position on the parameter stack. One reason for
10473introducing \prm {parameterdef} is that the position remains abstract so there we
10474don't need to use \prm {parameterindex}.
10475
10476\stopnewprimitive
10477
10478\startnewprimitive[title={\prm {parametermark}}]
10479
10480The meaning of primitive \prm {parametermark} is equivalent to \type {#} in a
10481macro definition, just like \prm {alignmark} is in an alignment. It can be used
10482to circumvent catcode issues. The normal \quotation {duplicate them when nesting}
10483rules apply.
10484
10485\startbuffer
10486\def\foo\parametermark1%
10487  {\def\oof\parametermark\parametermark1%
10488     {[\parametermark1:\parametermark\parametermark1]}}
10489\stopbuffer
10490
10491\typebuffer \getbuffer
10492
10493Here \type {\foo{X}\oof{Y}} gives: \foo{X}\oof{Y}.
10494
10495\stopnewprimitive
10496
10497\startnewprimitive[title={\prm {parametermode}}]
10498
10499Setting this internal integer to a positive value (best use~1 because future
10500versions might use bit set) will enable the usage of \type {#} for escaped in the
10501main text and body of macros.
10502
10503\stopnewprimitive
10504
10505\startnewprimitive[title={\prm {parattribute}}]
10506
10507This primitive takes an attribute index and value and sets that attribute on the
10508current paragraph.
10509
10510\stopnewprimitive
10511
10512\startnewprimitive[title={\prm {pardirection}}]
10513
10514This set the text direction for the whole paragraph which in the case of \type
10515{r2l} (1) makes the right edge the starting point.
10516
10517\stopnewprimitive
10518
10519\startnewprimitive[title={\prm {parfillleftskip}}]
10520
10521The glue inserted at the start of the last line.
10522
10523\stopnewprimitive
10524
10525\startnewprimitive[title={\prm {parfillrightskip}}]
10526
10527The glue inserted at the end of the last line (aka \prm {parfillskip}).
10528
10529\stopnewprimitive
10530
10531\startoldprimitive[title={\prm {parfillskip}}]
10532
10533The glue inserted at the end of the last line.
10534
10535\stopoldprimitive
10536
10537\startoldprimitive[title={\prm {parindent}}]
10538
10539The amount of space inserted at the start of the first line. When bit \tobit
10540\parindentskipnormalizecode\ is set in \prm {normalizelinemode} a glue is
10541inserted, otherwise an empty \prm {hbox} with the given width is inserted.
10542
10543\stopoldprimitive
10544
10545\startnewprimitive[title={\prm {parinitleftskip}}]
10546
10547The glue inserted at the start of the first line.
10548
10549\stopnewprimitive
10550
10551\startnewprimitive[title={\prm {parinitrightskip}}]
10552
10553The glue inserted at the end of the first line.
10554
10555\stopnewprimitive
10556
10557\startnewprimitive[title={\prm {paroptions}}]
10558
10559This adds options to already set options in a paragraph. It is used for
10560experiments so for now just forget about it.
10561
10562\stopnewprimitive
10563
10564\startnewprimitive[title={\prm {parpasses}}]
10565
10566Specifies one or more recipes for additional second linebreak passes. Examples
10567can be found in the \CONTEXT\ distribution.
10568
10569\stopnewprimitive
10570
10571\startnewprimitive[title={\prm {parpassesexception}}]
10572
10573Specifies al alternative parpass to use in the upcoming paragraph, for instance
10574one with a specific looseness that then demands for instance more emergency
10575stretch.
10576
10577\stopnewprimitive
10578
10579\startoldprimitive[title={\prm {parshape}}]
10580
10581Stores a shape specification. The first argument is the length of the list,
10582followed by that amount of indentation|-|width pairs (two dimensions).
10583
10584\stopoldprimitive
10585
10586\startoldprimitive[title={\prm {parshapedimen}}]
10587
10588This oddly named (\ETEX) primitive returns the width component (dimension) of the
10589given entry (an integer). Obsoleted by \prm {parshapewidth}.
10590
10591\stopoldprimitive
10592
10593\startoldprimitive[title={\prm {parshapeindent}}]
10594
10595Returns the indentation component (dimension) of the given entry (an integer).
10596
10597\stopoldprimitive
10598
10599\startoldprimitive[title={\prm {parshapelength}}]
10600
10601Returns the number of entries (an integer).
10602
10603\stopoldprimitive
10604
10605\startnewprimitive[title={\prm {parshapewidth}}]
10606
10607Returns the width component (dimension) of the given entry (an integer).
10608
10609\stopnewprimitive
10610
10611\startoldprimitive[title={\prm {parskip}}]
10612
10613This is the amount of glue inserted before a new paragraph starts.
10614
10615\stopoldprimitive
10616
10617\startoldprimitive[title={\prm {patterns}}]
10618
10619The argument to this primitive contains hyphenation patterns that are bound to
10620the current language. In \LUATEX\ and \LUAMETATEX\ we can also manage this at the
10621\LUA\ end. In \LUAMETATEX\ we don't store patterns in te format file
10622
10623\stopoldprimitive
10624
10625\startoldprimitive[title={\prm {pausing}}][obsolete=yes]
10626
10627In \LUAMETATEX\ this variable is ignored but in other engines it can be used to
10628single step thought the input file by setting it to a positive value.
10629
10630\stopoldprimitive
10631
10632\startoldprimitive[title={\prm {penalty}}]
10633
10634The given penalty (a number) is inserted at the current spot in the horizontal or
10635vertical list. We also have \prm {vpenalty} and \prm {hpenalty} that first change
10636modes.
10637
10638\stopoldprimitive
10639
10640\startnewprimitive[title={\prm {permanent}}]
10641
10642This is one of the prefixes that is part of the overload protection mechanism. It
10643is normally used to flag a macro as being at the same level as a primitive: don't
10644touch it. primitives are flagged as such but that property cannot be set on
10645regular macros. The similar \prm {immutable} flag is normally used for variables.
10646
10647\stopnewprimitive
10648
10649\startnewprimitive[title={\prm {pettymuskip}}]
10650
10651A predefined mu skip register that can be used in math (inter atom) spacing. The
10652current value is {\tt \the\pettymuskip}. This one complements \prm {thinmuskip},
10653\prm {medmuskip}, \prm {thickmuskip} and the new \prm {tinymuskip}.
10654
10655\stopnewprimitive
10656
10657\startnewprimitive[title={\prm {positdef}}]
10658
10659The engine uses 32 bit integers for various purposes and has no (real) concept of
10660a floating point quantity. We get around this by providing a floating point data
10661type based on 32 bit unums (posits). These have the advantage over native floats
10662of more precision in the lower ranges but at the cost of a software
10663implementation.
10664
10665The \prm {positdef} primitive is the floating point variant of \prm {integerdef}
10666and \prm {dimensiondef}: an efficient way to implement named quantities other
10667than registers.
10668
10669\startbuffer
10670\positdef     \MyFloatA 5.678
10671\positdef     \MyFloatB 567.8
10672[\the\MyFloatA] [\todimension\MyFloatA] [\tointeger\MyFloatA]
10673[\the\MyFloatB] [\todimension\MyFloatB] [\tointeger\MyFloatB]
10674\stopbuffer
10675
10676\typebuffer
10677
10678For practical reasons we can map posit (or float) onto an integer or dimension:
10679
10680\startlines
10681\getbuffer
10682\stoplines
10683
10684% {\em I might eventually decide to go for 32 bit floats but it all depends on how
10685% unums evolve cq. become native to \CCODE.}
10686
10687\stopnewprimitive
10688
10689\startoldprimitive[title={\prm {postdisplaypenalty}}]
10690
10691This is the penalty injected after a display formula.
10692
10693\stopoldprimitive
10694
10695\startnewprimitive[title={\prm {postexhyphenchar}}]
10696
10697This primitive expects a language number and a character code. A negative
10698character code is equivalent to ignore. In case of an explicit discretionary the
10699character is injected at the beginning of a new line.
10700
10701\stopnewprimitive
10702
10703\startnewprimitive[title={\prm {posthyphenchar}}]
10704
10705This primitive expects a language number and a character code. A negative
10706character code is equivalent to ignore. In case of an automatic discretionary the
10707character is injected at the beginning of a new line.
10708
10709\stopnewprimitive
10710
10711\startnewprimitive[title={\prm {postinlinepenalty}}]
10712
10713When set this penalty is inserted after an inline formula unless we have a short
10714formula and \prm {postshortinlinepenalty} is set.
10715
10716\stopnewprimitive
10717
10718\startnewprimitive[title={\prm {postshortinlinepenalty}}]
10719
10720When set this penalty is inserted after a short inline formula. The criterium is
10721set by \prm {shortinlinemaththreshold} but only applied when it is enabled for
10722the class involved.
10723
10724\stopnewprimitive
10725
10726\startnewprimitive[title={\prm {prebinoppenalty}}]
10727
10728This internal quantity is a compatibility feature because normally we will use
10729the inter atom spacing variables.
10730
10731\stopnewprimitive
10732
10733\startoldprimitive[title={\prm {predisplaydirection}}]
10734
10735This is the direction that the math sub engine will take into account when
10736dealing with right to left typesetting.
10737
10738\stopoldprimitive
10739
10740\startnewprimitive[title={\prm {predisplaygapfactor}}]
10741
10742The heuristics related to determine if the previous line in a formula overlaps
10743with a (display) formula are hard coded but in \LUATEX\ to be two times the quad
10744of the current font. This parameter is a multiplier set to 2000 and permits you
10745to change the overshoot in this heuristic.
10746
10747\stopnewprimitive
10748
10749\startoldprimitive[title={\prm {predisplaypenalty}}]
10750
10751This is the penalty injected before a display formula.
10752
10753\stopoldprimitive
10754
10755\startoldprimitive[title={\prm {predisplaysize}}]
10756
10757This parameter holds the length of the last line in a paragraph when a display
10758formula is part of it.
10759
10760\stopoldprimitive
10761
10762\startnewprimitive[title={\prm {preexhyphenchar}}]
10763
10764This primitive expects a language number and a character code. A negative
10765character code is equivalent to ignore. In case of an explicit discretionary the
10766character is injected at the end of the line.
10767
10768\stopnewprimitive
10769
10770\startnewprimitive[title={\prm {prehyphenchar}}]
10771
10772This primitive expects a language number and a character code. A negative
10773character code is equivalent to ignore. In case of an automatic discretionary the
10774character is injected at the end of the line.
10775
10776\stopnewprimitive
10777
10778\startnewprimitive[title={\prm {preinlinepenalty}}]
10779
10780When set this penalty is inserted before an inline formula unless we have a short
10781formula and \prm {preshortinlinepenalty} is set. These are not real penalties but
10782properties of the math begin and end markers. Just as with spacing as such
10783property, these penalties are not visible as nodes in the list.
10784
10785\stopnewprimitive
10786
10787\startnewprimitive[title={\prm {prerelpenalty}}]
10788
10789This internal quantity is a compatibility feature because normally we will use
10790the inter atom spacing variables.
10791
10792\stopnewprimitive
10793
10794\startnewprimitive[title={\prm {preshortinlinepenalty}}]
10795
10796When set this penalty is inserted before a short inline formula. The criterium is
10797set by \prm {shortinlinemaththreshold} but only applied when it is enabled for
10798the class involved.
10799
10800\stopnewprimitive
10801
10802\startoldprimitive[title={\prm {pretolerance}}]
10803
10804When the badness of a line in a paragraph exceeds this value a second linebreak
10805pass will be enabled.
10806
10807\stopoldprimitive
10808
10809\startoldprimitive[title={\prm {prevdepth}}]
10810
10811The depth of current list. It can also be set to special (signal) values in order
10812to inhibit line corrections. It is not an internal dimension but a (current) list
10813property.
10814
10815\stopoldprimitive
10816
10817\startoldprimitive[title={\prm {prevgraf}}]
10818
10819The number of lines in a previous paragraph.
10820
10821\stopoldprimitive
10822
10823\startnewprimitive[title={\prm {previousloopiterator}}]
10824
10825\startbuffer
10826\edef\testA{
10827    \expandedrepeat 2 {%
10828        \expandedrepeat 3 {%
10829            (\the\previousloopiterator1:\the\currentloopiterator)
10830        }%
10831    }%
10832}
10833\edef\testB{
10834    \expandedrepeat 2 {%
10835        \expandedrepeat 3 {%
10836            (#P:#I) % #G is two levels up
10837        }%
10838    }%
10839}
10840\stopbuffer
10841
10842\typebuffer \getbuffer
10843
10844These give the same result:
10845
10846\startlines \tt
10847\meaningasis\testA
10848\meaningasis\testB
10849\stoplines
10850
10851The number indicates the number of levels we go up the loop chain.
10852
10853\stopnewprimitive
10854
10855\startnewprimitive[title={\prm {primescript}}]
10856
10857This is a math script primitive dedicated to primes (which are somewhat
10858troublesome on math). It complements the six script primitives (like \prm
10859{subscript} and \prm {presuperscript}).
10860
10861\stopnewprimitive
10862
10863\startoldprimitive[title={\prm {protected}}]
10864
10865A protected macro is one that doesn't get expanded unless it is time to do so.
10866For instance, inside an \prm {edef} it just stays what it is. It often makes
10867sense to pass macros as|-|is to (multi|-|pass) file (for tables of contents).
10868
10869In \CONTEXT\ we use either \prm {protected} or \prm {unexpanded} because the
10870later was the command we used to achieve the same results before \ETEX\
10871introduced this protection primitive. Originally the \prm {protected} macro was
10872also defined but it has been dropped.
10873
10874\stopoldprimitive
10875
10876\startnewprimitive[title={\prm {protecteddetokenize}}]
10877
10878This is a variant of \prm {protecteddetokenize} that uses some escapes encoded as
10879body parameters, like \type {#H} for a hash.
10880
10881\stopnewprimitive
10882
10883\startnewprimitive[title={\prm {protectedexpandeddetokenize}}]
10884
10885This is a variant of \prm {expandeddetokenize} that uses some escapes encoded as
10886body parameters, like \type {#H} for a hash.
10887
10888\stopnewprimitive
10889
10890\startnewprimitive[title={\prm {protrudechars}}]
10891
10892This variable controls protrusion (into the margin). A value~2 is comparable with
10893other engines, while a value of~3 does a bit more checking when we're doing
10894right|-|to|-|left typesetting.
10895
10896\stopnewprimitive
10897
10898\startnewprimitive[title={\prm {protrusionboundary}}]
10899
10900This injects a boundary with the given value:
10901
10902\getbuffer[engine:syntax:protrusionboundarycodes]
10903
10904This signal makes the protrusion checker skip over a node.
10905
10906\stopnewprimitive
10907
10908\startnewprimitive[title={\prm {pxdimen}}]
10909
10910The current numeric value of this dimension is \tointeger \pxdimen, \todimension
10911\pxdimen: one \type {bp}. We kept it around because it was introduced in \PDFTEX\
10912and made it into \LUATEX, where it relates to the resolution of included images.
10913In \CONTEXT\ it is not used.
10914
10915\stopnewprimitive
10916
10917\startnewprimitive[title={\prm {quitloop}}]
10918
10919There are several loop primitives and they can be quit with \prm {quitloop} at
10920the next the {\em next} iteration. An immediate quit is possible with \prm
10921{quitloopnow}. An example is given with \prm {localcontrolledloop}.
10922
10923\stopnewprimitive
10924
10925\startnewprimitive[title={\prm {quitloopnow}}]
10926
10927There are several loop primitives and they can be quit with \prm {quitloopnow}
10928at the spot.
10929
10930\stopnewprimitive
10931
10932\startnewprimitive[title={\prm {quitvmode}}]
10933
10934This primitive forces horizontal mode but has no side effects when we're already
10935in that mode.
10936
10937\stopnewprimitive
10938
10939\startoldprimitive[title={\prm {radical}}][obsolete=yes]
10940
10941This old school radical constructor is replaced by \prm {Uradical}. It takes a
10942number where the first byte is the small family, the next two index of this
10943symbol from that family, and the next three the family and index of the first
10944larger variant.
10945
10946\stopoldprimitive
10947
10948\startoldprimitive[title={\prm {raise}}]
10949
10950This primitive takes two arguments, a dimension and a box. The box is moved up.
10951The operation only succeeds in horizontal mode.
10952
10953\stopoldprimitive
10954
10955\startnewprimitive[title={\prm {rdivide}}]
10956
10957This is variant of \prm {divide} that rounds the result. For integers the result
10958is the same as \prm {edivide}.
10959
10960\startbuffer
10961\the\dimexpr .4999pt                     : 2 \relax            =.24994pt
10962\the\dimexpr .4999pt                     / 2 \relax            =.24995pt
10963\the\dimexpr .4999pt                     ; 2 \relax            =.00002pt
10964\scratchdimen.4999pt \divide \scratchdimen 2 \the\scratchdimen =.24994pt
10965\scratchdimen.4999pt \edivide\scratchdimen 2 \the\scratchdimen =.24995pt
10966\scratchdimen 4999pt \rdivide\scratchdimen 2 \the\scratchdimen =2500.0pt
10967\scratchdimen 5000pt \rdivide\scratchdimen 2 \the\scratchdimen =2500.0pt
10968
10969\the\numexpr   1001                       : 2 \relax             =500
10970\the\numexpr   1001                       / 2 \relax             =501
10971\the\numexpr   1001                       ; 2 \relax             =1
10972\scratchcounter1001 \divide \scratchcounter 2 \the\scratchcounter=500
10973\scratchcounter1001 \edivide\scratchcounter 2 \the\scratchcounter=501
10974\scratchcounter1001 \rdivide\scratchcounter 2 \the\scratchcounter=501
10975\stopbuffer
10976
10977\typebuffer
10978
10979\startlines
10980\getbuffer
10981\stoplines
10982
10983The integer division \type{:} and modulo \type {;} are an addition to the \ETEX\
10984compatible expressions.
10985
10986\stopnewprimitive
10987
10988\startnewprimitive[title={\prm {rdivideby}}]
10989
10990This is the \type {by}|-|less companion to \prm {rdivide}.
10991
10992\stopnewprimitive
10993
10994\startnewprimitive[title={\prm {realign}}]
10995
10996Where \prm {omit} suspends a preamble template, this one overloads is for the
10997current table cell. It expects two token lists as arguments.
10998
10999\stopnewprimitive
11000
11001\startoldprimitive[title={\prm {relax}}]
11002
11003This primitive does nothing and is often used to end a verbose number or
11004dimension in a comparison, for example:
11005
11006\starttyping
11007\ifnum \scratchcounter = 123\relax
11008\stoptyping
11009
11010which prevents a lookahead. A variant would be:
11011
11012\starttyping
11013\ifnum \scratchcounter = 123 %
11014\stoptyping
11015
11016assuming that spaces are not ignored. Another application is finishing
11017an expression like \prm {numexpr} or \prm {dimexpr}. I is also used
11018to prevent lookahead in cases like:
11019
11020\starttyping
11021\vrule height 3pt depth 2pt width 5pt\relax
11022\hskip 5pt plus 3pt minus 2pt\relax
11023\stoptyping
11024
11025Because \prm {relax} is not expandable the following:
11026
11027\startbuffer
11028\edef\foo{\relax}   \meaningfull\foo
11029\edef\oof{\norelax} \meaningfull\oof
11030\stopbuffer
11031
11032\typebuffer
11033
11034gives this:
11035
11036\startlines
11037\getbuffer
11038\stoplines
11039
11040A \prm {norelax} disappears here but in the previously mentioned scenarios
11041it has the same function as \prm {relax}. It will not be pushed back either
11042in cases where a lookahead demands that.
11043
11044\stopoldprimitive
11045
11046\startoldprimitive[title={\prm {relpenalty}}]
11047
11048This internal quantity is a compatibility feature because normally we will use
11049the inter atom spacing variables.
11050
11051\stopoldprimitive
11052
11053\startnewprimitive[title={\prm {resetlocalboxes}}]
11054
11055Its purpose should be clear from the name.
11056
11057\stopnewprimitive
11058
11059\startnewprimitive[title={\prm {resetmathspacing}}]
11060
11061This initializes all parameters to their initial values.
11062
11063\stopnewprimitive
11064
11065\startnewprimitive[title={\prm {restorecatcodetable}}]
11066
11067This is an experimental feature that should be used with care. The next example
11068shows usage. It was added when debugging and exploring a side effect.
11069
11070\starttyping
11071\tracingonline1
11072
11073\bgroup
11074
11075    \catcode`6 = 11 \catcode`7 = 11
11076
11077    \bgroup
11078
11079    \tracingonline1
11080
11081    current: \the\catcodetable
11082
11083    original: \the\catcode`6\quad \the\catcode`7
11084
11085    \catcode`6 = 11 \catcode`7 = 11
11086
11087    \showcodestack\catcode
11088
11089    assigned: \the\catcode`6\quad \the\catcode`7
11090
11091    \showcodestack\catcode
11092
11093    \catcodetable\ctxcatcodes switched: \the\catcodetable
11094
11095    stored: \the\catcode`6\quad \the\catcode`7
11096
11097    \showcodestack\catcode
11098
11099    \restorecatcodetable\ctxcatcodes
11100
11101    \showcodestack\catcode
11102
11103    restored: \the\catcode`6\quad \the\catcode`7
11104
11105    \showcodestack\catcode
11106
11107    \egroup
11108
11109    \catcodetable\ctxcatcodes
11110
11111    inner: \the\catcode`6\quad\the\catcode`7
11112
11113\egroup
11114
11115outer: \the\catcode`6\quad\the\catcode`7
11116\stoptyping
11117
11118In \CONTEXT\ this typesets:
11119
11120\starttyping
11121current: 9
11122original: 11 11
11123assigned: 11 11
11124switched: 9
11125stored: 11 11
11126restored: 12 12
11127inner: 11 11
11128outer; 12 12
11129\stoptyping
11130
11131and on the console we see:
11132
11133\starttyping
111343:3: [codestack 1, size 3]
111353:3: [1: level 2, code 54, value 12]
111363:3: [2: level 2, code 55, value 12]
111373:3: [3: level 3, code 54, value 11]
111383:3: [4: level 3, code 55, value 11]
111393:3: [codestack 1 bottom]
111403:3: [codestack 1, size 3]
111413:3: [1: level 2, code 54, value 12]
111423:3: [2: level 2, code 55, value 12]
111433:3: [3: level 3, code 54, value 11]
111443:3: [4: level 3, code 55, value 11]
111453:3: [codestack 1 bottom]
111463:3: [codestack 1, size 3]
111473:3: [1: level 2, code 54, value 12]
111483:3: [2: level 2, code 55, value 12]
111493:3: [3: level 3, code 54, value 11]
111503:3: [4: level 3, code 55, value 11]
111513:3: [codestack 1 bottom]
111523:3: [codestack 1, size 7]
111533:3: [1: level 2, code 54, value 12]
111543:3: [2: level 2, code 55, value 12]
111553:3: [3: level 3, code 54, value 11]
111563:3: [4: level 3, code 55, value 11]
111573:3: [5: level 3, code 55, value 11]
111583:3: [6: level 3, code 54, value 11]
111593:3: [7: level 3, code 55, value 11]
111603:3: [8: level 3, code 54, value 11]
111613:3: [codestack 1 bottom]
111623:3: [codestack 1, size 7]
111633:3: [1: level 2, code 54, value 12]
111643:3: [2: level 2, code 55, value 12]
111653:3: [3: level 3, code 54, value 11]
111663:3: [4: level 3, code 55, value 11]
111673:3: [5: level 3, code 55, value 11]
111683:3: [6: level 3, code 54, value 11]
111693:3: [7: level 3, code 55, value 11]
111703:3: [8: level 3, code 54, value 11]
111713:3: [codestack 1 bottom]
11172\stoptyping
11173
11174So basically \prm {restorecatcodetable} brings us (temporarily) back to the
11175global settings.
11176
11177\stopnewprimitive
11178
11179\startnewprimitive[title={\prm {retained}}]
11180
11181When a value is assigned inside a group \TEX\ pushes the current value on the save
11182stack in order to be able to restore the original value after the group has ended. You
11183can reach over a group by using the \prm {global} prefix. A mix between local and
11184global assignments can be achieved with the \prm {retained} primitive.
11185
11186\newdimension\MyDim
11187
11188\startbuffer[one]
11189\MyDim 15pt \bgroup \the\MyDim \space
11190\bgroup
11191    \bgroup
11192        \bgroup \advance\MyDim10pt \the\MyDim \egroup\space
11193        \bgroup \advance\MyDim10pt \the\MyDim \egroup\space
11194    \egroup
11195    \bgroup
11196        \bgroup \advance\MyDim10pt \the\MyDim \egroup\space
11197        \bgroup \advance\MyDim10pt \the\MyDim \egroup\space
11198    \egroup
11199\egroup
11200\egroup \the\MyDim
11201\stopbuffer
11202
11203\startbuffer[two]
11204\MyDim 15pt \bgroup \the\MyDim \space
11205\bgroup
11206    \bgroup
11207        \bgroup \global\advance\MyDim10pt \the\MyDim \egroup\space
11208        \bgroup \global\advance\MyDim10pt \the\MyDim \egroup\space
11209    \egroup
11210    \bgroup
11211        \bgroup \global\advance\MyDim10pt \the\MyDim \egroup\space
11212        \bgroup \global\advance\MyDim10pt \the\MyDim \egroup\space
11213    \egroup
11214\egroup
11215\egroup \the\MyDim
11216\stopbuffer
11217
11218\startbuffer[three]
11219\MyDim 15pt \bgroup \the\MyDim \space
11220    \constrained\MyDim\zeropoint
11221    \bgroup
11222        \bgroup \retained\advance\MyDim10pt \the\MyDim \egroup\space
11223        \bgroup \retained\advance\MyDim10pt \the\MyDim \egroup\space
11224    \egroup
11225    \bgroup
11226        \bgroup \retained\advance\MyDim10pt \the\MyDim \egroup\space
11227        \bgroup \retained\advance\MyDim10pt \the\MyDim \egroup\space
11228    \egroup
11229\egroup \the\MyDim
11230\stopbuffer
11231
11232\typebuffer[one,two,three]
11233
11234These lines result in:
11235
11236\startlines
11237\hbox{\getbuffer[one]}
11238\hbox{\getbuffer[two]}
11239\hbox{\getbuffer[three]}
11240\stoplines
11241
11242Because \LUAMETATEX\ avoids redundant stack entries and reassignments this
11243mechanism is a bit fragile but the \prm {constrained} prefix makes sure that we
11244do have a stack entry. If it is needed depends on the usage pattern.
11245
11246\stopnewprimitive
11247
11248\startnewprimitive[title={\prm {retokenized}}]
11249
11250This is a companion of \prm {tokenized} that accepts a catcode table, so the
11251whole repertoire is:
11252
11253\startbuffer
11254\tokenized                             {test $x$ test: current}
11255\tokenized   catcodetable \ctxcatcodes {test $x$ test: context}
11256\tokenized   catcodetable \vrbcatcodes {test $x$ test: verbatim}
11257\retokenized              \ctxcatcodes {test $x$ test: context}
11258\retokenized              \vrbcatcodes {test $x$ test: verbatim}
11259\stopbuffer
11260
11261\typebuffer
11262
11263Here we pass the numbers known to \CONTEXT\ and get:
11264
11265\startlines
11266\getbuffer
11267\stoplines
11268
11269\stopnewprimitive
11270
11271\startoldprimitive[title={\prm {right}}]
11272
11273Inserts the given delimiter as right fence in a math formula.
11274
11275\stopoldprimitive
11276
11277\startoldprimitive[title={\prm {righthyphenmin}}]
11278
11279This is the minimum number of characters before the first hyphen in a hyphenated
11280word.
11281
11282\stopoldprimitive
11283
11284\startnewprimitive[title={\prm {rightmarginkern}}]
11285
11286The dimension returned is the protrusion kern that has been added (if at all) to
11287the left of the content in the given box.
11288
11289\stopnewprimitive
11290
11291\startoldprimitive[title={\prm {rightskip}}]
11292
11293This skip will be inserted at the right of every line.
11294
11295\stopoldprimitive
11296
11297\startnewprimitive[title={\prm {righttwindemerits}}]
11298
11299Additional demerits for a glyph sequence at the right edge when a previous line
11300also has that sequence.
11301
11302\stopnewprimitive
11303
11304\startoldprimitive[title={\prm {romannumeral}}]
11305
11306This converts a number into a sequence of characters representing a roman
11307numeral. Because the Romans had no zero, a zero will give no output, a fact that
11308is sometimes used for hacks and showing off ones macro coding capabilities. A
11309large number will for sure result in a long string because after thousand we
11310start duplicating.
11311
11312\stopoldprimitive
11313
11314\startnewprimitive[title={\prm {rpcode}}]
11315
11316This is the companion of \prm {lpcode} (see there) and also takes three
11317arguments: font, character code and factor.
11318
11319\stopnewprimitive
11320
11321\startnewprimitive[title={\prm {savecatcodetable}}]
11322
11323This primitive stores the currently set catcodes in the current table.
11324
11325\stopnewprimitive
11326
11327\startoldprimitive[title={\prm {savinghyphcodes}}]
11328
11329When set to non|-|zero, this will trigger the setting of \prm {hjcode}s from \prm
11330{lccode}s for the current font. These codes determine what characters are taken
11331into account when hyphenating words.
11332
11333\stopoldprimitive
11334
11335\startoldprimitive[title={\prm {savingvdiscards}}]
11336
11337When set to a positive value the page builder will store the discarded items
11338(like glues) so that they can later be retrieved and pushed back if needed with
11339\prm {pagediscards} or \prm {splitdiscards}.
11340
11341\stopoldprimitive
11342
11343\startnewprimitive[title={\prm {scaledemwidth}}]
11344
11345Returns the current (font specific) emwidth scaled according to \prm {glyphscale}
11346and \prm {glyphxscale}.
11347
11348\stopnewprimitive
11349
11350\startnewprimitive[title={\prm {scaledexheight}}]
11351
11352Returns the current (font specific) exheight scaled according to \prm {glyphscale}
11353and \prm {glyphyscale}.
11354
11355\stopnewprimitive
11356
11357\startnewprimitive[title={\prm {scaledextraspace}}]
11358
11359Returns the current (font specific) extra space value scaled according to \prm
11360{glyphscale} and \prm {glyphxscale}.
11361
11362\stopnewprimitive
11363
11364\startnewprimitive[title={\prm {scaledfontcharba}}]
11365
11366Returns the bottom accent position of the given font|-|character pair scaled
11367according to \prm {glyphscale} and \prm {glyphyscale}.
11368
11369\stopnewprimitive
11370
11371\startnewprimitive[title={\prm {scaledfontchardp}}]
11372
11373Returns the depth of the given font|-|character pair scaled according to \prm
11374{glyphscale} and \prm {glyphyscale}.
11375
11376\stopnewprimitive
11377
11378\startnewprimitive[title={\prm {scaledfontcharht}}]
11379
11380Returns the height of the given font|-|character pair scaled according to \prm
11381{glyphscale} and \prm {glyphyscale}.
11382
11383\stopnewprimitive
11384
11385\startnewprimitive[title={\prm {scaledfontcharic}}]
11386
11387Returns the italic correction of the given font|-|character pair scaled according
11388to \prm {glyphscale} and \prm {glyphxscale}. This property is only real for
11389traditional fonts.
11390
11391\stopnewprimitive
11392
11393\startnewprimitive[title={\prm {scaledfontcharta}}]
11394
11395Returns the top accent position of the given font|-|character pair scaled
11396according to \prm {glyphscale} and \prm {glyphxscale}.
11397
11398\stopnewprimitive
11399
11400\startnewprimitive[title={\prm {scaledfontcharwd}}]
11401
11402Returns width of the given font|-|character pair scaled according to \prm
11403{glyphscale} and \prm {glyphxscale}.
11404
11405\stopnewprimitive
11406
11407\startnewprimitive[title={\prm {scaledfontdimen}}]
11408
11409Returns value of a (numeric) font dimension of the given font|-|character pair
11410scaled according to \prm {glyphscale} and \prm {glyphxscale} and|/|or \prm
11411{glyphyscale}.
11412
11413\stopnewprimitive
11414
11415\startnewprimitive[title={\prm {scaledinterwordshrink}}]
11416
11417Returns the current (font specific) shrink of a space value scaled according to
11418\prm {glyphscale} and \prm {glyphxscale}.
11419
11420\stopnewprimitive
11421
11422\startnewprimitive[title={\prm {scaledinterwordspace}}]
11423
11424Returns the current (font specific) space value scaled according to \prm
11425{glyphscale} and \prm {glyphxscale}.
11426
11427\stopnewprimitive
11428
11429\startnewprimitive[title={\prm {scaledinterwordstretch}}]
11430
11431Returns the current (font specific) stretch of a space value scaled according to
11432\prm {glyphscale} and \prm {glyphxscale}.
11433
11434\stopnewprimitive
11435
11436\startnewprimitive[title={\prm {scaledmathaxis}}]
11437
11438This primitive returns the math axis of the given math style. It's a dimension.
11439
11440\stopnewprimitive
11441
11442\startnewprimitive[title={\prm {scaledmathemwidth}}]
11443
11444Returns the emwidth of the given style scaled according to \prm {glyphscale} and
11445\prm {glyphxscale}.
11446
11447\stopnewprimitive
11448
11449\startnewprimitive[title={\prm {scaledmathexheight}}]
11450
11451Returns the exheight of the given style scaled according to \prm {glyphscale} and
11452\prm {glyphyscale}.
11453
11454\stopnewprimitive
11455
11456\startnewprimitive[title={\prm {scaledmathstyle}}]
11457
11458This command inserts a signal in the math list that tells how to scale the (upcoming)
11459part of the formula.
11460
11461\startbuffer
11462$ x + {\scaledmathstyle900 x} + x$
11463\stopbuffer
11464
11465\typebuffer
11466
11467We get: \inlinebuffer. Of course using this properly demands integration in the macro
11468packages font system.
11469
11470\stopnewprimitive
11471
11472\startnewprimitive[title={\prm {scaledslantperpoint}}]
11473
11474This primitive is equivalent to \typ {\scaledfontdimen1\font} where \quote
11475{scaled} means that we multiply by the glyph scales.
11476
11477\stopnewprimitive
11478
11479\startnewprimitive[title={\prm {scantextokens}}]
11480
11481This primitive scans the input as if it comes from a file. In the next examples
11482the \prm {detokenize} primitive turns tokenized code into verbatim code that is
11483similar to what is read from a file.
11484
11485\startbuffer
11486\edef\whatever{\detokenize{This is {\bf bold} and this is not.}}
11487\detokenize   {This is {\bf bold} and this is not.}\crlf
11488\scantextokens{This is {\bf bold} and this is not.}\crlf
11489\scantextokens{\whatever}\crlf
11490\scantextokens\expandafter{\whatever}\par
11491\stopbuffer
11492
11493\typebuffer
11494
11495This primitive does not have the end|-|of|-|file side effects of its precursor
11496\prm {scantokens}.
11497
11498{\getbuffer}
11499
11500\stopnewprimitive
11501
11502\startoldprimitive[title={\prm {scantokens}}]
11503
11504Just forget about this \ETEX\ primitive, just take the one in the next section.
11505
11506\stopoldprimitive
11507
11508\startoldprimitive[title={\prm {scriptfont}}]
11509
11510This primitive is like \prm {font} but with a family number as (first) argument
11511so it is specific for math. It is the middle one of the three family members; its
11512relatives are \prm {textfont} and \prm {scriptscriptfont}.
11513
11514\stopoldprimitive
11515
11516\startoldprimitive[title={\prm {scriptscriptfont}}]
11517
11518This primitive is like \prm {font} but with a family number as (first) argument
11519so it is specific for math. It is the smallest of the three family members; its
11520relatives are \prm {textfont} and \prm {scriptfont}.
11521
11522\stopoldprimitive
11523
11524\startoldprimitive[title={\prm {scriptscriptstyle}}]
11525
11526One of the main math styles, normally one size smaller than \prm {scriptstyle}:
11527integer representation: \the\scriptscriptstyle.
11528
11529\stopoldprimitive
11530
11531\startoldprimitive[title={\prm {scriptspace}}][obsolete=yes]
11532
11533The math engine will add this amount of space after subscripts and superscripts.
11534It can be seen as compensation for the often too small widths of characters (in
11535the traditional engine italic correction is used too). It prevents scripts from
11536running into what follows.
11537
11538\stopoldprimitive
11539
11540\startnewprimitive[title={\prm {scriptspaceafterfactor}}]
11541
11542This is a (1000 based) multiplier for \prm {Umathspaceafterscript}.
11543
11544\stopnewprimitive
11545
11546\startnewprimitive[title={\prm {scriptspacebeforefactor}}]
11547
11548This is a (1000 based) multiplier for \prm {Umathspacebeforescript}.
11549
11550\stopnewprimitive
11551
11552\startnewprimitive[title={\prm {scriptspacebetweenfactor}}]
11553
11554This is a (1000 based) multiplier for \prm {Umathspacebetweenscript}.
11555
11556\stopnewprimitive
11557
11558\startoldprimitive[title={\prm {scriptstyle}}]
11559
11560One of the main math styles, normally one size smaller than \prm {displaystyle}
11561and \prm {textstyle}; integer representation: \the\scriptstyle.
11562
11563\stopoldprimitive
11564
11565\startoldprimitive[title={\prm {scrollmode}}]
11566
11567    This directive omits error stops.
11568
11569\stopoldprimitive
11570
11571\startnewprimitive[title={\prm {semiexpand}}]
11572
11573This command expands the next macro when it is protected with \prm
11574{semprotected}. See that primitive there for an example.
11575
11576\stopnewprimitive
11577
11578\startnewprimitive[title={\prm {semiexpanded}}]
11579
11580This command expands the tokens in the given list including the macros protected
11581by with \prm {semprotected}. See that primitive there for an example.
11582
11583\stopnewprimitive
11584
11585\startnewprimitive[title={\prm {semiprotected}}]
11586
11587\startbuffer
11588              \def\TestA{A}
11589\semiprotected\def\TestB{B}
11590    \protected\def\TestC{C}
11591
11592\edef\TestD{\TestA           \TestB           \TestC}
11593\edef\TestE{\TestA\semiexpand\TestB\semiexpand\TestC}
11594\edef\TestF{\TestA\expand    \TestB\expand    \TestC}
11595
11596\edef\TestG{\normalexpanded    {\TestA\TestB\TestC}}
11597\edef\TestH{\normalsemiexpanded{\TestA\TestB\TestC}}
11598\stopbuffer
11599
11600The working of this prefix can best be explained with an example. We define a few
11601macros first:
11602
11603\typebuffer \getbuffer
11604
11605The meaning of the macros that are made from the other three are:
11606
11607\startbuffer
11608\meaningless\TestD
11609\meaningless\TestE
11610\meaningless\TestF
11611\meaningless\TestG
11612\meaningless\TestH
11613\stopbuffer
11614
11615Here we use the \type {\normal..} variants because (currently) we still have the
11616macro with the \type {\expanded} in the \CONTEXT\ core.
11617
11618\startlines \tttf \getbuffer \stoplines
11619
11620\stopnewprimitive
11621
11622\startoldprimitive[title={\prm {setbox}}]
11623
11624This important primitive is used to set a box register. It expects a number and a
11625box, like \prm {hbox} or \prm {box}. There is no \type {\boxdef} primitive
11626(analogue to other registers) because it makes no sense but numeric registers or
11627equivalents are okay as register value.
11628
11629\stopoldprimitive
11630
11631\startnewprimitive[title={\prm {setdefaultmathcodes}}]
11632
11633This sets the math codes of upper- and lowercase alphabet and digits and the
11634delimiter code of the period. It's not so much a useful feature but more just an
11635accessor to the internal initializer.
11636
11637\stopnewprimitive
11638
11639\startnewprimitive[title={\prm {setfontid}}]
11640
11641Internally a font instance has a number and this number is what gets assigned to
11642a glyph node. You can get the number with \prm {fontid} an set it with \prm
11643{setfontid}.
11644
11645\starttyping
11646\setfontid\fontid\font
11647\stoptyping
11648
11649The code above shows both primitives and effectively does nothing useful but
11650shows the idea.
11651
11652\stopnewprimitive
11653
11654\startoldprimitive[title={\prm {setlanguage}}]
11655
11656In \LUATEX\ and \LUAMETATEX\ this is equivalent to \prm {language} because we
11657carry the language in glyph nodes instead of putting triggers in the list.
11658
11659\stopoldprimitive
11660
11661\startnewprimitive[title={\prm {setmathatomrule}}]
11662
11663The math engine has some built in logic with respect to neighboring atoms that
11664change the class. The following combinations are intercepted and remapped:
11665
11666\starttabulate[|c|c|c|c|]
11667\BC old first   \BC old second  \NC new first   \NC new second  \NC \NR
11668\ML
11669\NC begin       \NC binary      \NC ordinary    \NC ordinary    \NC \NR
11670\NC             \NC             \NC             \NC             \NC \NR
11671\NC operator    \NC binary      \NC operator    \NC ordinary    \NC \NR
11672\NC open        \NC binary      \NC open        \NC ordinary    \NC \NR
11673\NC punctuation \NC binary      \NC punctuation \NC ordinary    \NC \NR
11674\NC             \NC             \NC             \NC             \NC \NR
11675\NC binary      \NC end         \NC ordinary    \NC ordinary    \NC \NR
11676\NC binary      \NC binary      \NC binary      \NC ordinary    \NC \NR
11677\NC binary      \NC close       \NC ordinary    \NC close       \NC \NR
11678\NC binary      \NC punctuation \NC ordinary    \NC punctuation \NC \NR
11679\NC binary      \NC relation    \NC ordinary    \NC relation    \NC \NR
11680\NC             \NC             \NC             \NC             \NC \NR
11681\NC relation    \NC binary      \NC relation    \NC ordinary    \NC \NR
11682\NC relation    \NC close       \NC ordinary    \NC close       \NC \NR
11683\NC relation    \NC punctuation \NC ordinary    \NC punctuation \NC \NR
11684\stoptabulate
11685
11686You can change this logic if needed, for instance:
11687
11688\starttyping
11689\setmathatomrule 1 2 \allmathstyles 1 1
11690\stoptyping
11691
11692Keep in mind that the defaults are what users expect. You might set them up for
11693additional classes that you define but even then you probably clone an existing
11694class and patch its properties. Most extra classes behave like ordinary anyway.
11695
11696\stopnewprimitive
11697
11698\startnewprimitive[title={\prm {setmathdisplaypostpenalty}}]
11699
11700This penalty is inserted after an item of a given class but only in inline math
11701when display style is used, for instance:
11702
11703\starttyping
11704\setmathdisplayprepenalty 2 750
11705\stoptyping
11706
11707\stopnewprimitive
11708
11709\startnewprimitive[title={\prm {setmathdisplayprepenalty}}]
11710
11711This penalty is inserted before an item of a given class but only in inline math
11712when display style is used, for instance:
11713
11714\starttyping
11715\setmathdisplayprepenalty 2 750
11716\stoptyping
11717
11718\stopnewprimitive
11719
11720\startnewprimitive[title={\prm {setmathignore}}]
11721
11722You can flag a math parameter to be ignored, like:
11723
11724\starttyping
11725\setmathignore \Umathxscale             2
11726\setmathignore \Umathyscale             2
11727\setmathignore \Umathspacebeforescript  1
11728\setmathignore \Umathspacebetweenscript 1
11729\setmathignore \Umathspaceafterscript   1
11730\stoptyping
11731
11732A value of two will not initialize the variable, so its old value (when set) is
11733kept. This is somewhat experimental and more options might show up.
11734
11735\stopnewprimitive
11736
11737\startnewprimitive[title={\prm {setmathoptions}}]
11738
11739This primitive expects a class (number) and a bitset.
11740
11741\testpage[2]
11742
11743\starttworows
11744\getbuffer[engine:syntax:classoptioncodes] % weird: one liner at end of page
11745\stoptworows
11746
11747\stopnewprimitive
11748
11749\startnewprimitive[title={\prm {setmathpostpenalty}}]
11750
11751This penalty is inserted after an item of a given class but only in inline math
11752when text, script or scriptscript style is used, for instance:
11753
11754\starttyping
11755\setmathpostpenalty 2 250
11756\stoptyping
11757
11758\stopnewprimitive
11759
11760\startnewprimitive[title={\prm {setmathprepenalty}}]
11761
11762This penalty is inserted before an item of a given class but only in inline math
11763when text, script or scriptscript style is used, for instance:
11764
11765\starttyping
11766\setmathprepenalty 2 250
11767\stoptyping
11768
11769\stopnewprimitive
11770
11771\startnewprimitive[title={\prm {setmathspacing}}]
11772
11773More details about this feature can be found in \CONTEXT\ but it boils down to
11774registering what spacing gets inserted between a pair of classes. It can be
11775defined per style or for a set of styles, like:
11776
11777\starttyping
11778\inherited\setmathspacing
11779  \mathimplicationcode \mathbinarycode
11780  \alldisplaystyles \thickermuskip
11781\inherited\setmathspacing
11782  \mathradicalcode \mathmiddlecode
11783  \allunsplitstyles \pettymuskip
11784\stoptyping
11785
11786Here the \prm {inherited} prefix signals that a change in for instance \prm
11787{pettymuskip} is reflected in this spacing pair. In \CONTEXT\ there is a lot of
11788granularity with respect to spacing and it took years of experimenting (and
11789playing with examples) to get at the current stage. In general users are not
11790invited to mess around too much with these values, although changing the bound
11791registers (here \prm {pettymuskip} and \type {thickermuskip}) is no problem as it
11792consistently makes related spacing pairs follow.
11793
11794\stopnewprimitive
11795
11796\startoldprimitive[title={\prm {sfcode}}]
11797
11798You can set a space factor on a character. That factor is used when a space
11799factor is applied (as part of spacing). It is (mostly) used for adding a
11800different space (glue) after punctuation. In some languages different punctuation
11801has different factors.
11802
11803\stopoldprimitive
11804
11805\startnewprimitive[title={\prm {shapingpenaltiesmode}}]
11806
11807Shaping penalties are inserted after the lines of a \prm {parshape} and
11808accumulate according to this mode, a bitset of:
11809
11810\getbuffer[engine:syntax:shapingpenaltiescodes]
11811
11812\stopnewprimitive
11813
11814\startnewprimitive[title={\prm {shapingpenalty}}]
11815
11816In order to prevent a \prm {parshape} to break in unexpected ways we can add a
11817dedicated penalty, specified by this parameter.
11818
11819\stopnewprimitive
11820
11821\startoldprimitive[title={\prm {shipout}}][obsolete=yes]
11822
11823Because there is no backend, this is not supposed to be used. As in traditional
11824\TEX\ a box is grabbed but instead of it being processed it gets shown and then
11825wiped. There is no real benefit of turning it into a callback.
11826
11827\stopoldprimitive
11828
11829\startnewprimitive[title={\prm {shortinlinemaththreshold}}]
11830
11831This parameter determines when an inline formula is considered to be short. This
11832criterium is used for for \prm {preshortinlinepenalty} and \prm
11833{postshortinlinepenalty}.
11834
11835\stopnewprimitive
11836
11837\startnewprimitive[title={\prm {shortinlineorphanpenalty}}]
11838
11839Short formulas at the end of a line are normally not followed by something other
11840than punctuation. This penalty will discourage a break before a short inline
11841formula. In practice one can set this penalty to e.g. a relatively low 200 to get
11842the desired effect.
11843
11844\stopnewprimitive
11845
11846\startoldprimitive[title={\prm {show}}]
11847
11848Prints to the console (and/or log) what the token after
11849it represents.
11850
11851\stopoldprimitive
11852
11853\startoldprimitive[title={\prm {showbox}}]
11854
11855The given box register is shown in the log and on te console (depending on \prm
11856{tracingonline}. How much is shown depends on \prm {showboxdepth} and \prm
11857{showboxbreadth}. In \LUAMETATEX\ we show more detailed information than in the
11858other engines; some specific information is provided via callbacks.
11859
11860\stopoldprimitive
11861
11862\startoldprimitive[title={\prm {showboxbreadth}}]
11863
11864This primitives determine how much of a box is shown when asked for or when
11865tracing demands it.
11866
11867\stopoldprimitive
11868
11869\startoldprimitive[title={\prm {showboxdepth}}]
11870
11871This primitives determine how deep tracing a box goes into the box. Some boxes,
11872like the ones that has the assembled page.
11873
11874\stopoldprimitive
11875
11876\startnewprimitive[title={\prm {showcodestack}}]
11877
11878This inspector is only useful for low level debugging and reports the current
11879state of for instance the current catcode table: \typ {\showcodestack \catcode}.
11880See \prm {restorecatcodes} for an example.
11881
11882\stopnewprimitive
11883
11884\startoldprimitive[title={\prm {showgroups}}]
11885
11886This primitive reports the group nesting. At this spot we have a not so
11887impressive nesting:
11888
11889\starttyping
118902:3: simple group entered at line 9375:
118911:3: semisimple group: \begingroup
118920:3: bottomlevel
11893\stoptyping
11894
11895\stopoldprimitive
11896
11897\startoldprimitive[title={\prm {showifs}}]
11898
11899This primitive will show the conditional stack in the log file or on the console
11900(assuming \prm {tracingonline} being non|-|zero). The shown data is different
11901from other engines because we have more conditionals and also support a more flat
11902nesting model
11903
11904\stopoldprimitive
11905
11906\startoldprimitive[title={\prm {showlists}}]
11907
11908This shows the currently built list.
11909
11910\stopoldprimitive
11911
11912\startoldprimitive[title={\prm {shownodedetails}}]
11913
11914When set to a positive value more details will be shown of nodes when applicable.
11915Values larger than one will also report attributes. What gets shown depends on
11916related callbacks being set.
11917
11918\stopoldprimitive
11919
11920\startoldprimitive[title={\prm {showstack}}]
11921
11922This tracer is only useful for low level debugging of macros, for instance when
11923you run out of save space or when you encounter a performance hit.
11924
11925\starttyping
11926  test\scratchcounter0 \showstack
11927 {test\scratchcounter1 \showstack}
11928{{test\scratchcounter1 \showstack}}
11929\stoptyping
11930
11931reports
11932
11933\starttyping
119341:3: [savestack size 0]
119351:3: [savestack bottom]
11936
119372:3: [savestack size 2]
119382:3: [1: restore, level 1, cs \scratchcounter=integer 1]
119392:3: [0: boundary, group 'bottomlevel', boundary 0, attrlist 3600, line 0]
119402:3: [savestack bottom]
11941
119423:3: [savestack size 3]
119433:3: [2: restore, level 1, cs \scratchcounter=integer 1]
119443:3: [1: boundary, group 'simple', boundary 0, attrlist 3600, line 12]
119453:3: [0: boundary, group 'bottomlevel', boundary 0, attrlist 3600, line 0]
119463:3: [savestack bottom]
11947\stoptyping
11948
11949while
11950
11951\starttyping
11952  test\scratchcounter1 \showstack
11953 {test\scratchcounter1 \showstack}
11954{{test\scratchcounter1 \showstack}}
11955\stoptyping
11956
11957shows this:
11958
11959\starttyping
119601:3: [savestack size 0]
119611:3: [savestack bottom]
11962
119632:3: [savestack size 1]
119642:3: [0: boundary, group 'bottomlevel', boundary 0, attrlist 3600, line 0]
119652:3: [savestack bottom]
11966
119673:3: [savestack size 2]
119683:3: [1: boundary, group 'simple', boundary 0, attrlist 3600, line 16]
119693:3: [0: boundary, group 'bottomlevel', boundary 0, attrlist 3600, line 0]
119703:3: [savestack bottom]
11971\stoptyping
11972
11973Because in the second example the value of \type {\scratchcounter} doesn't really
11974change inside the group there is no need for a restore entry on the stack. In
11975\LUAMETATEX\ there are checks for that so that we consume less stack space. We
11976also store some states (like the line number and current attribute list pointer)
11977in a stack boundary.
11978
11979\stopoldprimitive
11980
11981\startoldprimitive[title={\prm {showthe}}]
11982
11983Prints to the console (and/or log) the value of token after it.
11984
11985\stopoldprimitive
11986
11987\startoldprimitive[title={\prm {showtokens}}]
11988
11989This command expects a (balanced) token list, like
11990
11991\starttyping
11992\showtokens{a few tokens}
11993\stoptyping
11994
11995Depending on what you want to see you need to expand:
11996
11997\starttyping
11998\showtokens\expandafter{\the\everypar}
11999\stoptyping
12000
12001which is equivalent to \typ {\showthe \everypar}. It is an \ETEX\ extension.
12002
12003\stopoldprimitive
12004
12005\startnewprimitive[title={\prm {singlelinepenalty}}]
12006
12007This is a penalty that gets injected before a paragraph that has only one line.
12008It is a one|-|shot parameter, so like \prm {looseness} it only applies to the
12009upcoming (or current) paragraph.
12010
12011\stopnewprimitive
12012
12013\startoldprimitive[title={\prm {skewchar}}][obsolete=yes]
12014
12015This is an (imaginary) character that is used in math fonts. The kerning pair
12016between this character and the current one determines the top anchor of a
12017possible accent. In \OPENTYPE\ there is a dedicated character property for this
12018(but for some reason not for the bottom anchor).
12019
12020\stopoldprimitive
12021
12022\startoldprimitive[title={\prm {skip}}]
12023
12024This is the accessor for an indexed skip (glue) register.
12025
12026\stopoldprimitive
12027
12028\startoldprimitive[title={\prm {skipdef}}]
12029
12030This command associates a control sequence with a skip register (accessed by number).
12031
12032\stopoldprimitive
12033
12034\startnewprimitive[title={\prm {snapshotpar}}]
12035
12036There are many parameters involved in typesetting a paragraph. One complication
12037is that parameters set in the middle might have unpredictable consequences due to
12038grouping, think of:
12039
12040\starttyping
12041text  text <some setting> text   text \par
12042text {text <some setting> text } text \par
12043\stoptyping
12044
12045This makes in traditional \TEX\ because there is no state related to the current
12046paragraph. But in \LUATEX\ we have the initial so called par node that remembers
12047the direction as well as local boxes. In \LUAMETATEX\ we store way more when this
12048node is created. That means that later settings no longer replace the stored ones.
12049
12050The \prm {snapshotpar} takes a bitset that determine what stored parameters get
12051updated to the current values.
12052
12053\startthreerows
12054\getbuffer[engine:syntax:frozenparcodes]
12055\stopthreerows
12056
12057One such value covers multiple values, so for instance \type {skip} is good for
12058storing the current \prm {leftskip} and \prm {rightskip} values. More about this
12059feature can be found in the \CONTEXT\ documentation.
12060
12061The list of parameters that gets reset after a paragraph is longer than for
12062\PDFTEX\ and \LUAMETATEX: \prm {emergencyleftskip}, \prm {emergencyrightskip}, \prm
12063{hangafter}, \prm {hangindent}, \prm {interlinepenalties}, \prm
12064{localbrokenpenalty}, \prm {localinterlinepenalty}, \prm {localpretolerance},
12065\prm {localtolerance}, \prm {looseness}, \prm {parshape} and \prm
12066{singlelinepenalty}.
12067
12068\stopnewprimitive
12069
12070\startnewprimitive[title={\prm {spacechar}}]
12071
12072When \prm {nospaces} is set to~3 a glyph node with the character value of
12073this parameter is injected.
12074
12075\stopnewprimitive
12076
12077\startoldprimitive[title={\prm {spacefactor}}]
12078
12079The space factor is a somewhat complex feature. When during scanning a character
12080is appended that has a \prm {sfcode} other than 1000, that value is saved. When
12081the time comes to insert a space triggered glue, and that factor is 2000 or more,
12082and when \prm {xspaceskip} is nonzero, that value is used and we're done.
12083
12084If these criteria are not met, and \prm {spaceskip} is nonzero, that value is
12085used, otherwise the space value from the font is used. Now, it if the space factor
12086is larger than 2000 the extra space value from the font is added to the set value.
12087Next the engine is going to tweak the stretch and shrink if that value and in
12088\LUAMETATEX\ that can be done in different ways, depending on \prm {spacefactormode},
12089\prm {spacefactorstretchlimit} and \prm {spacefactorshrinklimit}.
12090
12091First the stretch. When the set limit is 1000 or more and the saved space factor
12092is also 1000 or more, we multiply the stretch by the limit, otherwise the saved
12093space factor is used.
12094
12095Shrink is done differently. When the shrink limit and space factor are both 1000
12096or more, we will scale the shrink component by the limit, otherwise we multiply
12097by the saved space factor but here we have three variants, determined by the
12098value of \prm {spacefactormode}.
12099
12100In the first case, when the limit kicks in, a mode value~1 will multiply by limit
12101and divides by 1000. A value of~2 multiplies by 2000 and divides by the limit.
12102Other mode values multiply by 1000 and divide by the limit. When the limit is not
12103used, the same happens but with the saved space factor.
12104
12105If this sounds complicated, here is what regular \TEX\ does: stretch is
12106multiplied by the factor and divided by 1000 while shrink is multiplied by 1000
12107and divided by the saved factor. The (new) mode driven alternatives are the
12108result of extensive experiments done in the perspective of enhancing the
12109rendering of inline math as well as additional par builder passes. For sure
12110alternative strategies are possible and we can always add more modes.
12111
12112A better explanation of the default strategy around spaces can be found in (of
12113course) The \TEX book and \TEX\ by Topic.
12114
12115\stopoldprimitive
12116
12117\startnewprimitive[title={\prm {spacefactormode}}]
12118
12119Its setting determines the way the glue components (currently only shrink) adapts
12120itself to the current space factor (determined by by the character preceding a
12121space).
12122
12123\stopnewprimitive
12124
12125\startnewprimitive[title={\prm {spacefactoroverload}}]
12126
12127When set to value between zero and thousand, this value will be used when \TEX\
12128encounters a below thousand space factor situation (usually used to suppress
12129additional space after a period following an uppercase character which then gets
12130(often) a 999 space factor. This feature only kicks in when the overload flag is
12131set in the glyph options, so it can be applied selectively.
12132
12133\stopnewprimitive
12134
12135\startnewprimitive[title={\prm {spacefactorshrinklimit}}]
12136
12137This limit is used when \prm {spacefactormode} is set. See \prm {spacefactor} for a
12138bit more explanation.
12139
12140\stopnewprimitive
12141
12142\startnewprimitive[title={\prm {spacefactorstretchlimit}}]
12143
12144This limit is used when \prm {spacefactormode} is set. See \prm {spacefactor} for a
12145bit more explanation.
12146
12147\stopnewprimitive
12148
12149\startoldprimitive[title={\prm {spaceskip}}]
12150
12151Normally the glue inserted when a space is encountered is taken from the font but
12152this parameter can overrule that.
12153
12154\stopoldprimitive
12155
12156\startoldprimitive[title={\prm {span}}]
12157
12158This primitive combined two upcoming cells into one. Often it is used in
12159combination with \prm {omit}. However, in the preamble it forces the next token
12160to be expanded, which means that nested \prm {tabskips} and align content markers
12161are seen.
12162
12163\stopoldprimitive
12164
12165\startnewprimitive[title={\prm {specificationdef}}]
12166
12167There are some datastructures that are like arrays: \prm {adjacentdemerits}, \prm
12168{brokenpenalties}, \prm {clubpenalties}, \prm {displaywidowpenalties}, \prm
12169{fitnessclasses}, \prm {interlinepenalties}, \prm {mathbackwardpenalties}, \prm
12170{mathforwardpenalties}, \prm {orphanpenalties}, \prm {parpasses}, \prm {parshape}
12171and \prm {widowpenalties}. They accept a counter than tells how many entries
12172follow and depending in the specification options, keywords and|/|or just values
12173are expected.
12174
12175With \prm {specificationdef} you can define a command that holds such an array
12176and that can be used afterwards as a fast way to enable that specification. The
12177way it work is as follows:
12178
12179\starttyping
12180\specificationdef\MyWidowPenalties
12181    \widowpenalties 4 2000 1000 500 250
12182\relax
12183\stoptyping
12184
12185where the relax is optional but a reasonabel way to make sure we end the
12186definition (when keywords are used, as in \prm {parpasses} it prevents running
12187into unexpected keywords.
12188
12189\stopnewprimitive
12190
12191\startoldprimitive[title={\prm {splitbotmark}}][obsolete=yes]
12192
12193This is a reference to the last mark on the currently split off box, it gives
12194back tokens.
12195
12196\stopoldprimitive
12197
12198\startoldprimitive[title={\prm {splitbotmarks}}]
12199
12200This is a reference to the last mark with the given id (a number) on the
12201currently split off box, it gives back tokens.
12202
12203\stopoldprimitive
12204
12205\startoldprimitive[title={\prm {splitdiscards}}]
12206
12207When a box is split off, items like glue are discarded. This internal register
12208keeps the that list so that it can be pushed back if needed.
12209
12210\stopoldprimitive
12211
12212\startnewprimitive[title={\prm {splitextraheight}}]
12213
12214A possible (permissive) overrun of the split off part in a \prm {vsplit}.
12215
12216\stopnewprimitive
12217
12218\startoldprimitive[title={\prm {splitfirstmark}}][obsolete=yes]
12219
12220This is a reference to the first mark on the currently split off box, it gives
12221back tokens.
12222
12223\stopoldprimitive
12224
12225\startoldprimitive[title={\prm {splitfirstmarks}}]
12226
12227This is a reference to the first mark with the given id (a number) on the
12228currently split off box, it gives back tokens.
12229
12230\stopoldprimitive
12231
12232\startnewprimitive[title={\prm {splitlastdepth}}]
12233
12234This returns the last depth in a \type {vsplit}.
12235
12236\stopnewprimitive
12237
12238\startnewprimitive[title={\prm {splitlastheight}}]
12239
12240This returns the last (accumulated) height in a \type {vsplit}.
12241
12242\stopnewprimitive
12243
12244\startnewprimitive[title={\prm {splitlastshrink}}]
12245
12246This returns the last (accumulated) shrink in a \type {vsplit}.
12247
12248\stopnewprimitive
12249
12250\startnewprimitive[title={\prm {splitlaststretch}}]
12251
12252This returns the last (accumulated) stretch in a \type {vsplit}.
12253
12254\stopnewprimitive
12255
12256\startoldprimitive[title={\prm {splitmaxdepth}}]
12257
12258The depth of the box that results from a \prm {vsplit}.
12259
12260\stopoldprimitive
12261
12262\startoldprimitive[title={\prm {splittopskip}}]
12263
12264This is the amount of glue that is added to the top of a (new) split of part of a
12265box when \prm {vsplit} is applied.
12266
12267\stopoldprimitive
12268
12269\startnewprimitive[title={\prm {srule}}]
12270
12271This inserts a rule with no width. When a \type {font} and a \type {char} are
12272given the height and depth of that character are taken. Instead of a font \type
12273{fam} is also accepted so that we can use it in math mode.
12274
12275\stopnewprimitive
12276
12277\startoldprimitive[title={\prm {string}}]
12278
12279We mention this original primitive because of the one in the next section. It
12280expands the next token or control sequence as if it was just entered, so normally
12281a control sequence becomes a backslash followed by characters and a space.
12282
12283\stopoldprimitive
12284
12285\startnewprimitive[title={\prm {subprescript}}]
12286
12287Instead of three or four characters with catcode \the\subscriptcatcode\ (\type
12288{__} or \type {____}) this primitive can be used. It will add the following
12289argument as lower left script to the nucleus.
12290
12291\stopnewprimitive
12292
12293\startnewprimitive[title={\prm {subscript}}]
12294
12295Instead of one or two characters with catcode \the\superscriptcatcode\ (\type {_}
12296or \type {__}) this primitive can be used. It will add the following argument as
12297upper left script to the nucleus.
12298
12299\stopnewprimitive
12300
12301\startnewprimitive[title={\prm {superprescript}}]
12302
12303Instead of three or four characters with catcode \the\superscriptcatcode\ (\type
12304{^^^} or \type {^^^^}) this primitive can be used. It will add the following
12305argument as upper left script to the nucleus.
12306
12307\stopnewprimitive
12308
12309\startnewprimitive[title={\prm {superscript}}]
12310
12311Instead of one or two character with catcode \the\superscriptcatcode\ (\type {^}
12312or \type {^^})t his primitive can be used. It will add the following argument as
12313upper right script to the nucleus.
12314
12315\stopnewprimitive
12316
12317\startnewprimitive[title={\prm {supmarkmode}}]
12318
12319As in other languages, \TEX\ has ways to escape characters and get whatever
12320character needed into the input. By default multiple \type {^} are used for this.
12321The dual \type {^^} variant is a bit weird as it is not continuous but \type
12322{^^^^} and \type {^^^^^^} provide four or six byte hexadecimal references ot
12323characters. The single \type {^} is also used for superscripts but because we
12324support prescripts and indices we get into conflicts with the escapes.
12325
12326When this internal quantity is set to zero, multiple \type {^}'s are interpreted
12327in the input and produce characters. Other values disable the multiple parsing in
12328text and|/|or math mode:
12329
12330\startbuffer
12331\normalsupmarkmode0 $ X^58 \quad X^^58 $
12332\normalsupmarkmode1 $ X^58 \quad X^^58 $ ^^58
12333\normalsupmarkmode2 $ X^58 \quad X^^58 $ % ^^58 : error
12334\stopbuffer
12335
12336\typebuffer
12337
12338In \CONTEXT\ we default to one but also have the \prm {catcode} set to \the
12339\catcode`^, and the \prm {amcode} to \the \amcode `^.
12340
12341\startlines
12342\catcode`^=\superscriptcatcode % to make sure we handle it in math
12343\amcode `^=\superscriptcatcode
12344\getbuffer
12345\stoplines
12346
12347% \startlines
12348% \amcode \circumflexasciicode\superscriptcatcode
12349% \catcode\circumflexasciicode\superscriptcatcode % to make sure we handle it in math
12350% \getbuffer
12351% \stoplines
12352
12353\stopnewprimitive
12354
12355\startnewprimitive[title={\prm {swapcsvalues}}]
12356
12357Because we mention some \type {def} and \type {let} primitives here, it makes
12358sense to also mention a primitive that will swap two values (meanings). This one
12359has to be used with care. Of course that what gets swapped has to be of the same
12360type (or at least similar enough not to cause issues). Registers for instance
12361store their values in the token, but as soon as we are dealing with token lists
12362we also need to keep an eye on reference counting. So, to some extend this is
12363an experimental feature.
12364
12365\startbuffer
12366\scratchcounterone 1 \scratchcountertwo 2
12367(\the\scratchcounterone,\the\scratchcountertwo)
12368\swapcsvalues \scratchcounterone \scratchcountertwo
12369(\the\scratchcounterone,\the\scratchcountertwo)
12370\swapcsvalues \scratchcounterone \scratchcountertwo
12371(\the\scratchcounterone,\the\scratchcountertwo)
12372
12373\scratchcounterone 3 \scratchcountertwo 4
12374(\the\scratchcounterone,\the\scratchcountertwo)
12375\bgroup
12376\swapcsvalues \scratchcounterone \scratchcountertwo
12377(\the\scratchcounterone,\the\scratchcountertwo)
12378\egroup
12379(\the\scratchcounterone,\the\scratchcountertwo)
12380\stopbuffer
12381
12382\typebuffer
12383
12384We get similar results:
12385
12386\startlines
12387\getbuffer
12388\stoplines
12389
12390\stopnewprimitive
12391
12392\startnewprimitive[title={\prm {tabsize}}]
12393
12394This primitive can be used in the preamble of an alignment and sets the size of
12395a column, as in:
12396
12397\startbuffer
12398\halign{%
12399    \aligncontent             \aligntab
12400    \aligncontent\tabsize 3cm \aligntab
12401    \aligncontent             \aligntab
12402    \aligncontent\tabsize 0cm \cr
12403    1  \aligntab 111\aligntab 1111\aligntab 11\cr
12404    222\aligntab 2  \aligntab 2222\aligntab 22\cr
12405}
12406\stopbuffer
12407
12408\typebuffer
12409
12410As with \prm {tabskip} you need to reset the value explicitly, so that is why we
12411get two wide columns:
12412
12413\blank {\showboxes \getbuffer} \blank
12414
12415\stopnewprimitive
12416
12417\startoldprimitive[title={\prm {tabskip}}]
12418
12419This traditional primitive can be used in the preamble of an alignment and sets the
12420space added between columns, for example:
12421
12422\startbuffer
12423\halign{%
12424    \aligncontent             \aligntab
12425    \aligncontent\tabskip 3cm \aligntab
12426    \aligncontent             \aligntab
12427    \aligncontent\tabskip 0cm \cr
12428    1  \aligntab 111\aligntab 1111\aligntab 11\cr
12429    222\aligntab 2  \aligntab 2222\aligntab 22\cr
12430}
12431\stopbuffer
12432
12433\typebuffer
12434
12435You need to reset the skip explicitly, which is why we get it applied twice here:
12436
12437\blank {\showboxes \getbuffer} \blank
12438
12439\stopoldprimitive
12440
12441\startnewprimitive[title={\prm {textdirection}}]
12442
12443This set the text direction to \type {l2r} (0) or \type {r2l} (1). It also
12444triggers additional checking for balanced flipping in node lists.
12445
12446\stopnewprimitive
12447
12448\startoldprimitive[title={\prm {textfont}}]
12449
12450This primitive is like \prm {font} but with a family number as (first) argument
12451so it is specific for math. It is the largest one of the three family members; its
12452relatives are \prm {scriptfont} and \prm {scriptscriptfont}.
12453
12454\stopoldprimitive
12455
12456\startoldprimitive[title={\prm {textstyle}}]
12457
12458One of the main math styles; integer representation: \the\textstyle.
12459
12460\stopoldprimitive
12461
12462\startoldprimitive[title={\prm {the}}]
12463
12464The \prm {the} primitive serializes the following token, when applicable:
12465integers, dimensions, token registers, special quantities, etc. The catcodes of
12466the result will be according to the current settings, so in \type {\the \dimen0},
12467the \type {pt} will have catcode \quote {letter} and the number and period will
12468become \quote {other}.
12469
12470\stopoldprimitive
12471
12472\startnewprimitive[title={\prm {thewithoutunit}}]
12473
12474The \prm{the} primitive, when applied to a dimension variable, adds a \type {pt}
12475unit. because dimensions are the only traditional unit with a fractional part
12476they are sometimes used as pseudo floats in which case \prm {thewithoutunit} can
12477be used to avoid the unit. This is more convenient than stripping it off
12478afterwards (via an expandable macro).
12479
12480\stopnewprimitive
12481
12482\startoldprimitive[title={\prm {thickmuskip}}]
12483
12484A predefined mu skip register that can be used in math (inter atom) spacing. The
12485current value is {\tt \the\thickmuskip}. In traditional \TEX\ most inter atom
12486spacing is hard coded using the predefined registers.
12487
12488\stopoldprimitive
12489
12490\startoldprimitive[title={\prm {thinmuskip}}]
12491
12492A predefined mu skip register that can be used in math (inter atom) spacing. The
12493current value is {\tt \the\thinmuskip}. In traditional \TEX\ most inter atom
12494spacing is hard coded using the predefined registers.
12495
12496\stopoldprimitive
12497
12498\startoldprimitive[title={\prm {time}}]
12499
12500This internal number starts out with minute (starting at midnight) that the job
12501started.
12502
12503\stopoldprimitive
12504
12505\startnewprimitive[title={\prm {tinymuskip}}]
12506
12507A predefined mu skip register that can be used in math (inter atom) spacing. The
12508current value is {\tt \the\tinymuskip}. This one complements \prm {thinmuskip},
12509\prm {medmuskip}, \prm {thickmuskip} and the new \prm {pettymuskip}
12510
12511\stopnewprimitive
12512
12513\startnewprimitive[title={\prm {tocharacter}}]
12514
12515The given number is converted into an \UTF-8 sequence. In \LUATEX\ this one is
12516named \type {\Uchar}.
12517
12518\stopnewprimitive
12519
12520\startnewprimitive[title={\prm {toddlerpenalties}}]
12521
12522This an (possible double entry) array parameter: first the size is given followed
12523by that amount of penalties (can be pairs). These penalties are injected after
12524(and before) single glyphs bounded by spaces, going backward from the end of a
12525sequence of them.
12526
12527\stopnewprimitive
12528
12529\startnewprimitive[title={\prm {todimension}}]
12530
12531\startbuffer
12532\scratchdimen = 1234pt \todimension\scratchdimen
12533\stopbuffer
12534
12535The following code gives this: {\nospacing\inlinebuffer} and like its numeric
12536counterparts accepts anything that resembles a number this one goes beyond
12537(user, internal or pseudo) registers values too.
12538
12539\typebuffer
12540
12541\stopnewprimitive
12542
12543\startnewprimitive[title={\prm {tohexadecimal}}]
12544
12545\startbuffer
12546\scratchcounter = 1234 \tohexadecimal\scratchcounter
12547\stopbuffer
12548
12549The following code gives this: {\nospacing\inlinebuffer} with uppercase letters.
12550
12551\typebuffer
12552
12553\stopnewprimitive
12554
12555\startnewprimitive[title={\prm {tointeger}}]
12556
12557\startbuffer
12558\scratchcounter = 1234 \tointeger\scratchcounter
12559\stopbuffer
12560
12561The following code gives this: {\nospacing\inlinebuffer} and is equivalent to
12562\prm {number}.
12563
12564\typebuffer
12565
12566\stopnewprimitive
12567
12568\startnewprimitive[title={\prm {tokenized}}]
12569
12570Just as \prm {expanded} has a counterpart \prm {unexpanded}, it makes sense to give
12571\prm {detokenize} a companion:
12572
12573\startbuffer
12574\edef\foo{\detokenize{\inframed{foo}}}
12575\edef\oof{\detokenize{\inframed{oof}}}
12576
12577\meaning\foo \crlf \dontleavehmode\foo
12578
12579\edef\foo{\tokenized{\foo\foo}}
12580
12581\meaning\foo \crlf \dontleavehmode\foo
12582
12583\dontleavehmode\tokenized{\foo\oof}
12584\stopbuffer
12585
12586\typebuffer {\tttf \getbuffer}
12587
12588This primitive is similar to:
12589
12590\starttyping
12591\def\tokenized#1{\scantextokens\expandafter{\normalexpanded{#1}}}
12592\stoptyping
12593
12594and should be more efficient, not that it matters much as we don't use it that
12595much (if at all).
12596
12597\stopnewprimitive
12598
12599\startoldprimitive[title={\prm {toks}}]
12600
12601This is the accessor of a token register so it expects a number or \prm
12602{toksdef}'d macro.
12603
12604\stopoldprimitive
12605
12606\startnewprimitive[title={\prm {toksapp}}]
12607
12608One way to append something to a token list is the following:
12609
12610\starttyping
12611\scratchtoks\expandafter{\the\scratchtoks more stuff}
12612\stoptyping
12613
12614This works all right, but it involves a copy of what is already in \type
12615{\scratchtoks}. This is seldom a real issue unless we have large token lists and
12616many appends. This is why \LUATEX\ introduced:
12617
12618\starttyping
12619\toksapp\scratchtoks{more stuff}
12620\toksapp\scratchtoksone\scratchtokstwo
12621\stoptyping
12622
12623At some point, when working on \LUAMETATEX, I realized that primitives like this
12624one and the next appenders and prependers to be discussed were always on the
12625radar of Taco and me. Some were even implemented in what we called \type {eetex}:
12626extended \ETEX, and we even found back the prototypes, dating from pre|-|\PDFTEX\
12627times.
12628
12629\stopnewprimitive
12630
12631\startoldprimitive[title={\prm {toksdef}}]
12632
12633The given name (control sequence) will be bound to the given token register (a
12634number). Often this primitive is hidden in a high level macro that manages
12635allocation.
12636
12637\stopoldprimitive
12638
12639\startnewprimitive[title={\prm {tokspre}}]
12640
12641Where appending something is easy because of the possible \prm {expandafter}
12642trickery a prepend would involve more work, either using temporary token
12643registers and|/|or using a mixture of the (no)expansion added by \ETEX, but all
12644are kind of inefficient and cumbersome.
12645
12646\starttyping
12647\tokspre\scratchtoks{less stuff}
12648\tokspre\scratchtoksone\scratchtokstwo
12649\stoptyping
12650
12651This prepends the token list that is provided.
12652
12653\stopnewprimitive
12654
12655\startoldprimitive[title={\prm {tolerance}}]
12656
12657When the par builder runs into a line with a badness larger than this value and
12658when \prm {emergencystretch} is set a third pass is enabled. In \LUAMETATEX\ we
12659can have more than one second pass and there are more parameters that influence
12660the process.
12661
12662\stopoldprimitive
12663
12664\startnewprimitive[title={\prm {tolerant}}]
12665
12666This prefix tags the following macro as being tolerant with respect to the
12667expected arguments. It only makes sense when delimited arguments are used or when
12668braces are mandate.
12669
12670\startbuffer
12671\tolerant\def\foo[#1]#*[#2]{(#1)(#2)}
12672\stopbuffer
12673
12674\typebuffer \getbuffer
12675
12676This definition makes \type {\foo} tolerant for various calls:
12677
12678\startbuffer
12679\foo \foo[1] \foo [1] \foo[1] [2] \foo [1] [2]
12680\stopbuffer
12681
12682\typebuffer
12683
12684these give: \inlinebuffer. The spaces after the first call disappear because the
12685macro name parser gobbles it, while in the second case the \type {#*} gobbles
12686them. Here is a variant:
12687
12688\startbuffer
12689\tolerant\def\foo[#1]#,[#2]{!#1!#2!}
12690
12691\foo[?] x
12692\foo[?] [?] x
12693
12694\tolerant\def\foo[#1]#*[#2]{!#1!#2!}
12695
12696\foo[?] x
12697\foo[?] [?] x
12698\stopbuffer
12699
12700\typebuffer
12701
12702We now get the following:
12703
12704\getbuffer
12705
12706Here the \type {#,} remembers that spaces were gobbles and they will be put back
12707when there is no further match. These are just a few examples of this tolerant
12708feature. More details can be found in the lowlevel manuals.
12709
12710\stopnewprimitive
12711
12712\startnewprimitive[title={\prm {tomathstyle}}]
12713
12714Internally math styles are numbers, where \prm {displaystyle} is \tomathstyle
12715\displaystyle \space and \prm {crampedscriptscriptstyle} is \tomathstyle
12716\crampedscriptscriptstyle. You can convert the verbose style to a number with
12717\prm {tomathstyle}.
12718
12719\stopnewprimitive
12720
12721\startoldprimitive[title={\prm {topmark}}][obsolete=yes]
12722
12723This is a reference to the last mark on the previous (split off) page, it gives
12724back tokens.
12725
12726\stopoldprimitive
12727
12728\startoldprimitive[title={\prm {topmarks}}]
12729
12730This is a reference to the last mark with the given id (a number) on the previous
12731page, it gives back tokens.
12732
12733\stopoldprimitive
12734
12735\startoldprimitive[title={\prm {topskip}}]
12736
12737This is the amount of glue that is added to the top of a (new) page.
12738
12739\stopoldprimitive
12740
12741\startnewprimitive[title={\prm {toscaled}}]
12742
12743\startbuffer
12744\scratchdimen = 1234pt \toscaled\scratchdimen
12745\stopbuffer
12746
12747The following code gives this: {\nospacing\inlinebuffer} is similar to \prm
12748{todimension} but omits the \type {pt} so that we don't need to revert to some
12749nasty stripping code.
12750
12751\typebuffer
12752
12753\stopnewprimitive
12754
12755\startnewprimitive[title={\prm {tosparsedimension}}]
12756
12757\startbuffer
12758\scratchdimen = 1234pt \tosparsedimension\scratchdimen
12759\stopbuffer
12760
12761The following code gives this: {\nospacing\inlinebuffer} where \quote {sparse}
12762indicates that redundant trailing zeros are not shown.
12763
12764\typebuffer
12765
12766\stopnewprimitive
12767
12768\startnewprimitive[title={\prm {tosparsescaled}}]
12769
12770\startbuffer
12771\scratchdimen = 1234pt \tosparsescaled\scratchdimen
12772\stopbuffer
12773
12774The following code gives this: {\nospacing\inlinebuffer} where \quote {sparse}
12775means that redundant trailing zeros are omitted.
12776
12777\typebuffer
12778
12779\stopnewprimitive
12780
12781\startnewprimitive[title={\prm {tpack}}]
12782
12783This primitive is like \prm {vtop} but without the callback overhead.
12784
12785\stopnewprimitive
12786
12787\startnewprimitive[title={\prm {tracingadjusts}}]
12788
12789In \LUAMETATEX\ the adjust feature has more functionality and also is carried
12790over. When set to a positive values \prm {vadjust} processing reports details.
12791The higher the number, the more you'll get.
12792
12793\stopnewprimitive
12794
12795\startnewprimitive[title={\prm {tracingalignments}}]
12796
12797When set to a positive value the alignment mechanism will keep you informed about
12798what is done in various stages. Higher values unleash more information, including
12799what callbacks kick in.
12800
12801\stopnewprimitive
12802
12803\startoldprimitive[title={\prm {tracingassigns}}]
12804
12805When set to a positive values assignments to parameters and variables are
12806reported on the console and|/|or in the log file. Because \LUAMETATEX\ avoids
12807redundant assignments these don't get reported.
12808
12809\stopoldprimitive
12810
12811\startnewprimitive[title={\prm {tracingbalancing}}]
12812
12813When set to a positive some insight in the balancing process is given, kind of
12814like with the par builder, so it can be noisy.
12815
12816\stopnewprimitive
12817
12818\startoldprimitive[title={\prm {tracingcommands}}]
12819
12820When set to a positive values the commands (primitives) are reported on the console
12821and|/|or in the log file.
12822
12823\stopoldprimitive
12824
12825\startnewprimitive[title={\prm {tracingexpressions}}]
12826
12827The extended expression commands like \prm {numexpression} and \prm
12828{dimexpression} can be traced by setting this parameter to a positive value.
12829
12830\stopnewprimitive
12831
12832\startnewprimitive[title={\prm {tracingfitness}}]
12833
12834Because we have more fitness classes we also have (need) a (bit) more detailed
12835tracing.
12836
12837\stopnewprimitive
12838
12839\startnewprimitive[title={\prm {tracingfullboxes}}]
12840
12841When set to a positive value the box will be shown in case of an overfull box.
12842When a quality callback is set this will not happen as all reporting is then
12843delegated.
12844
12845\stopnewprimitive
12846
12847\startoldprimitive[title={\prm {tracinggroups}}]
12848
12849When set to a positive values grouping is reported on the console and|/|or in the
12850log file.
12851
12852\stopoldprimitive
12853
12854\startnewprimitive[title={\prm {tracinghyphenation}}]
12855
12856When set to a positive values the hyphenation process is reported on the console
12857and|/|or in the log file.
12858
12859\stopnewprimitive
12860
12861\startoldprimitive[title={\prm {tracingifs}}]
12862
12863When set some details of what gets tested and what results are seen is reported.
12864
12865\stopoldprimitive
12866
12867\startnewprimitive[title={\prm {tracinginserts}}]
12868
12869A positive value enables tracing where values larger than~1 will report more
12870details.
12871
12872\stopnewprimitive
12873
12874\startnewprimitive[title={\prm {tracinglevels}}]
12875
12876The lines in a log file can be prefixed with some details, depending on the bits
12877set:
12878
12879\starttabulate[|T|l|]
12880\NC 0x1 \NC current group \NC \NR
12881\NC 0x2 \NC current input \NC \NR
12882\NC 0x4 \NC catcode table \NC \NR
12883\stoptabulate
12884
12885\stopnewprimitive
12886
12887\startnewprimitive[title={\prm {tracinglists}}]
12888
12889At various stages the lists being processed can be shown. This is mostly an
12890option for developers.
12891
12892\stopnewprimitive
12893
12894\startnewprimitive[title={\prm {tracingloners}}]
12895
12896With loners we mean \quote {widow} and \quote {club} lines. This tracer can be
12897handy when \prm {doublepenaltymode} is set and facing pages have different
12898penalty values.
12899
12900\stopnewprimitive
12901
12902\startnewprimitive[title={\prm {tracinglooseness}}]
12903
12904This tracer reports some details about the decision made towards a possible
12905loose result.
12906
12907\stopnewprimitive
12908
12909\startoldprimitive[title={\prm {tracinglostchars}}]
12910
12911When set to one characters not present in a font will be reported in the log
12912file, a value of two will also report this on the console. In \CONTEXT\ we use
12913the \type {missing_character} instead. Contrary to in \LUATEX\ values larger than
12914two have no special meaning and we don't error.
12915
12916\stopoldprimitive
12917
12918\startoldprimitive[title={\prm {tracingmacros}}]
12919
12920This parameter controls reporting of what macros are seen and expanded.
12921
12922\stopoldprimitive
12923
12924\startnewprimitive[title={\prm {tracingmarks}}]
12925
12926Marks are information blobs that track states that can be queried when a page is
12927handled over to the shipout routine. They travel through the system in a bit
12928different than traditionally: like like adjusts and inserts deeply buried ones
12929bubble up to outer level boxes. This parameters controls what progress gets
12930reported.
12931
12932\stopnewprimitive
12933
12934\startnewprimitive[title={\prm {tracingmath}}]
12935
12936The higher the value, the more information you will get about the various stages
12937in rendering math. Because tracing of nodes is rather verbose you need to know a
12938bit what this engine does. Conceptually there are differences between the
12939\LUAMETATEX\ and traditional engine, like more passes, inter-atom spacing,
12940different low level mechanisms. This feature is mostly meant for developers who
12941tweak the many available parameters.
12942
12943\stopnewprimitive
12944
12945\startnewprimitive[title={\prm {tracingmvl}}]
12946
12947When set to a positive value mvl switching is reported.
12948
12949\stopnewprimitive
12950
12951\startoldprimitive[title={\prm {tracingnesting}}]
12952
12953A positive value triggers log messages about the current level.
12954
12955\stopoldprimitive
12956
12957\startnewprimitive[title={\prm {tracingnodes}}]
12958
12959When set to a positive value more details about nodes (in boxes) will be
12960reported. Because this is also controlled by callbacks what gets reported is
12961macro package dependent.
12962
12963\stopnewprimitive
12964
12965\startoldprimitive[title={\prm {tracingonline}}]
12966
12967The engine has two output channels: the log file and the console and by default
12968most tracing (when enabled) goes to the log file. When this parameter is set to a
12969positive value tracing will also happen in the console. Messages from the \LUA\
12970end can be channeled independently.
12971
12972\stopoldprimitive
12973
12974\startnewprimitive[title={\prm {tracingorphans}}]
12975
12976When set to a positive value handling of orphans is shown.
12977
12978\stopnewprimitive
12979
12980\startoldprimitive[title={\prm {tracingoutput}}]
12981
12982Values larger than zero result in some information about what gets passed to the
12983output routine.
12984
12985\stopoldprimitive
12986
12987\startoldprimitive[title={\prm {tracingpages}}]
12988
12989Values larger than one result in some information about the page building
12990process. In \LUAMETATEX\ there is more info for higher values.
12991
12992\stopoldprimitive
12993
12994\startoldprimitive[title={\prm {tracingparagraphs}}]
12995
12996Values larger than one result in some information about the par building process.
12997In \LUAMETATEX\ there is more info for higher values.
12998
12999\stopoldprimitive
13000
13001\startnewprimitive[title={\prm {tracingpasses}}]
13002
13003In \LUAMETATEX\ you can configure additional second stage par builder passes and
13004this parameter controls what gets reported on the console and|/|or in the log
13005file.
13006
13007\stopnewprimitive
13008
13009\startnewprimitive[title={\prm {tracingpenalties}}]
13010
13011This setting triggers reporting of actions due to special penalties in the
13012page builder.
13013
13014\stopnewprimitive
13015
13016\startoldprimitive[title={\prm {tracingrestores}}]
13017
13018When set to a positive values (re)assignments after grouping to parameters and
13019variables are reported on the console and|/|or in the log file. Because
13020\LUAMETATEX\ avoids redundant assignments these don't get reported.
13021
13022\stopoldprimitive
13023
13024\startoldprimitive[title={\prm {tracingstats}}]
13025
13026This parameter is a dummy in \LUAMETATEX. There are anyway some statistic
13027reported when the format is made but for a regular run it is up to the macro
13028package to come up with useful information.
13029
13030\stopoldprimitive
13031
13032\startnewprimitive[title={\prm {tracingtoddlers}}]
13033
13034When set to a positive value handling of toddlers is shown.
13035
13036\stopnewprimitive
13037
13038\startnewprimitive[title={\prm {tsplit}}]
13039
13040This splits like \prm {vsplit} but it returns a \prm {vtop} box instead.
13041
13042\stopnewprimitive
13043
13044\startoldprimitive[title={\prm {uccode}}]
13045
13046When the \prm {uppercase} operation is applied the uppercase code of a character
13047is used for the replacement. This primitive is used to set that code, so it
13048expects two character number.
13049
13050\stopoldprimitive
13051
13052\startoldprimitive[title={\prm {uchyph}}]
13053
13054When set to a positive number words that start with a capital will be hyphenated.
13055
13056\stopoldprimitive
13057
13058\startnewprimitive[title={\prm {uleaders}}]
13059
13060This leader adapts itself after a paragraph has been typeset. Here are a few
13061examples:
13062
13063\startbuffer
13064test \leaders  \hbox      {x}\hfill\              test
13065test \uleaders \hbox{x x x x}\hfill\              test
13066test           \hbox{x x x x}\hskip 3cm plus 1cm\ test
13067test \uleaders \hbox{x x x x}\hskip 3cm plus 1cm\ test
13068\stopbuffer
13069
13070\typebuffer
13071
13072When an \prm {uleaders} is used the glue in the given box will be adapted to the
13073available space.
13074
13075\startlines \getbuffer \stoplines
13076
13077\startsetups adaptive:test
13078    \setbox\usedadaptivebox\hbox to \usedadaptivewidth yoffset -\usedadaptivedepth \bgroup
13079        \externalfigure
13080          [cow.pdf]
13081          [width=\usedadaptivewidth,
13082           height=\dimexpr\usedadaptiveheight+\usedadaptivedepth\relax]%
13083   \egroup
13084\stopsetups
13085
13086Optionally the \type {callback} followed by a number can be given, in which case
13087a callback kicks in that gets that the node, a group identifier, and the number
13088passed. It permits (for instance) adaptive graphics: \dostepwiserecurse {1} {100} {5}
13089{\hbox {#1=\romannumerals{#1}} {\adaptivebox [strut=yes, setups=adaptive:test]{}} }.
13090
13091These \prm {uleaders} can be used in horizontal and vertical mode so we give a few more
13092examples.
13093
13094\startbuffer
13095\unexpandedloop 1 30 1 {x            \hbox{1 2 3}                                                           x }
13096\unexpandedloop 1 30 1 {x {\uleaders \hbox{1 2 3}\hskip 0pt plus 10pt               minus 10pt\relax}        x }
13097\unexpandedloop 1 30 1 {x {\uleaders \hbox{1 2 3}\hskip 0pt plus  \interwordstretch minus \interwordshrink}  x }
13098\unexpandedloop 1 30 1 {x {\uleaders \hbox{1 2 3}\hskip 0pt plus 2\interwordstretch minus 2\interwordshrink} x }
13099\stopbuffer
13100
13101\typebuffer
13102
13103This renders as:
13104
13105\startlines
13106\getbuffer
13107\stoplines
13108
13109It is clear that the flexibility of the box plays a role in the line break
13110calculations. But in the end the backend has to do the work which is why it's a
13111\quote {user} leader. Here is an example of a vertical one. Compare:
13112
13113\startbuffer[a]
13114{\green \hrule width \hsize} \par \vskip2pt
13115\vbox to 40pt {
13116    {\red\hrule width \hsize} \par \vskip2pt
13117    \vbox {
13118        \vskip2pt {\blue\hrule width \hsize} \par
13119        \vskip 10pt plus 10pt minus 10pt
13120        {\blue\hrule width \hsize} \par \vskip2pt
13121    }
13122    \vskip2pt {\red\hrule width \hsize} \par
13123}
13124\vskip2pt {\green \hrule width \hsize} \par
13125\stopbuffer
13126
13127\startbuffer[b]
13128{\green \hrule width \hsize} \par \vskip2pt
13129\vbox to 40pt {
13130    {\red\hrule width \hsize} \par \vskip2pt
13131    \uleaders\vbox {
13132        \vskip2pt {\blue\hrule width \hsize} \par
13133        \vskip 10pt plus 10pt minus 10pt
13134        {\blue\hrule width \hsize} \par \vskip2pt
13135    }\vskip 0pt plus 10pt minus 10pt
13136    \vskip2pt {\red\hrule width \hsize} \par
13137}
13138\vskip2pt {\green \hrule width \hsize} \par
13139\stopbuffer
13140
13141\typebuffer[a]
13142
13143with:
13144
13145\typebuffer[b]
13146
13147In the first case we get the this:
13148
13149\startlinecorrection
13150\getbuffer[a]
13151\stoplinecorrection
13152
13153but with \prm {uleaders} we get:
13154
13155\startlinecorrection
13156\normalizeparmode\zerocount
13157\getbuffer[b]
13158\stoplinecorrection
13159
13160or this:
13161
13162\startlinecorrection
13163\normalizeparmode"FF
13164\getbuffer[b]
13165\stoplinecorrection
13166
13167In the second case we flatten the leaders in the engine by setting the second bit
13168in the \prm {normalizeparmode} parameter (\type {0x2}). We actually do the same
13169with \prm {normalizelinemode} where bit 10 is set (\type {0x200}). The \type
13170{delay} keyword can be passed with a box to prevent flattening. If we don't do
13171this in the engine, the backend has to take care of it. In principle this permits
13172implementing variants in a macro package. Eventually there will be plenty examples in
13173the \CONTEXT\ code base and documentation. Till then, consider this experimental.
13174
13175\stopnewprimitive
13176
13177\startoldprimitive[title={\prm {unboundary}}]
13178
13179When possible a preceding boundary node will be removed.
13180
13181\stopoldprimitive
13182
13183\startnewprimitive[title={\prm {undent}}]
13184
13185When possible the already added indentation will be removed.
13186
13187\stopnewprimitive
13188
13189\startoldprimitive[title={\prm {underline}}]
13190
13191This is a math specific primitive that draws a line under the given content. It
13192is a poor mans replacement for a delimiter. The thickness is set with \prm
13193{Umathunderbarrule}, the distance between content and rule is set by \prm
13194{Umathunderbarvgap} and \prm {Umathunderbarkern} is added above the rule. The
13195style used for the content under the rule can be set with \prm
13196{Umathunderlinevariant}. See \prm {overline} for what these parameters do.
13197
13198\stopoldprimitive
13199
13200\startoldprimitive[title={\prm {unexpanded}}]
13201
13202This is an \ETEX\ enhancement. The content will not be expanded in a context
13203where expansion is happening, like in an \prm {edef}. In \CONTEXT\ you need to
13204use \prm {normalunexpanded} because we already had a macro with that name.
13205
13206\startbuffer
13207\def \A{!}                       \meaning\A
13208\def \B{?}                       \meaning\B
13209\edef\C{\A\B}                    \meaning\C
13210\edef\C{\normalunexpanded{\A}\B} \meaning\C
13211\stopbuffer
13212
13213\typebuffer
13214
13215\startlines \tttf \getbuffer \stoplines
13216
13217\stopoldprimitive
13218
13219\startnewprimitive[title={\prm {unexpandedendless}}]
13220
13221This one loops forever so you need to quit explicitly.
13222
13223\stopnewprimitive
13224
13225\startnewprimitive[title={\prm {unexpandedloop}}]
13226
13227As follow up on \prm {expandedloop} we now show its counterpart:
13228
13229\startbuffer
13230\edef\whatever
13231  {\unexpandedloop 1 10 1
13232     {\scratchcounter=\the\currentloopiterator\relax}}
13233
13234\meaningasis\whatever
13235\stopbuffer
13236
13237\typebuffer
13238
13239\start \veryraggedright \tt\tfx \getbuffer \stop \blank
13240
13241The difference between the (un)expanded loops and a local controlled
13242one is shown here. Watch the out of order injection of \type {A}'s.
13243
13244\startbuffer
13245\edef\TestA{\localcontrolledloop 1 5 1 {A}} % out of order
13246\edef\TestB{\expandedloop        1 5 1 {B}}
13247\edef\TestC{\unexpandedloop      1 5 1 {C\relax}}
13248\stopbuffer
13249
13250\typebuffer \getbuffer
13251
13252We show the effective definition as well as the outcome of using them
13253
13254\startbuffer
13255\meaningasis\TestA
13256\meaningasis\TestB
13257\meaningasis\TestC
13258
13259A: \TestA
13260B: \TestB
13261C: \TestC
13262\stopbuffer
13263
13264\typebuffer \startlines \tttf \getbuffer \stoplines
13265
13266Watch how because it is empty \type {\TestA} has become a constant macro because
13267that's what deep down empty boils down to.
13268
13269\stopnewprimitive
13270
13271\startnewprimitive[title={\prm {unexpandedrepeat}}]
13272
13273This one takes one instead of three arguments which looks better in simple loops.
13274
13275\stopnewprimitive
13276
13277\startoldprimitive[title={\prm {unhbox}}]
13278
13279A box is a packaged list and once packed travels through the system as a single
13280object with properties, like dimensions. This primitive injects the original list
13281and discards the wrapper.
13282
13283\stopoldprimitive
13284
13285\startoldprimitive[title={\prm {unhcopy}}]
13286
13287This is like \prm {unhbox} but keeps the original. It is one of the more costly
13288operations.
13289
13290\stopoldprimitive
13291
13292\startnewprimitive[title={\prm {unhpack}}]
13293
13294This primitive is like \prm {unhbox} but without the callback overhead.
13295
13296\stopnewprimitive
13297
13298\startoldprimitive[title={\prm {unkern}}]
13299
13300This removes the last kern, if possible.
13301
13302\stopoldprimitive
13303
13304\startoldprimitive[title={\prm {unless}}]
13305
13306This \ETEX\ prefix will negate the test (when applicable).
13307
13308\starttyping
13309       \ifx\one\two YES\else NO\fi
13310\unless\ifx\one\two NO\else YES\fi
13311\stoptyping
13312
13313This primitive is hardly used in \CONTEXT\ and we probably could get rid of these
13314few cases.
13315
13316\stopoldprimitive
13317
13318\startnewprimitive[title={\prm {unletfrozen}}]
13319
13320A frozen macro cannot be redefined: you get an error. But as nothing in \TEX\ is set
13321in stone, you can do this:
13322
13323\starttyping
13324\frozen\def\MyMacro{...}
13325\unletfrozen\MyMacro
13326\stoptyping
13327
13328and \type {\MyMacro} is no longer protected from overloading. It is still
13329undecided to what extend \CONTEXT\ will use this feature.
13330
13331\stopnewprimitive
13332
13333\startnewprimitive[title={\prm {unletprotected}}]
13334
13335The complementary operation of \prm {letprotected} can be used to unprotect
13336a macro, so that it gets expandable.
13337
13338\startbuffer
13339               \def  \MyMacroA{alpha}
13340\protected     \def  \MyMacroB{beta}
13341               \edef \MyMacroC{\MyMacroA\MyMacroB}
13342\unletprotected      \MyMacroB
13343               \edef \MyMacroD{\MyMacroA\MyMacroB}
13344\meaning             \MyMacroC\crlf
13345\meaning             \MyMacroD\par
13346\stopbuffer
13347
13348\typebuffer
13349
13350Compare this with the example in the previous section:
13351
13352{\tttf \getbuffer}
13353
13354\stopnewprimitive
13355
13356\startoldprimitive[title={\prm {unpenalty}}]
13357
13358This removes the last penalty, if possible.
13359
13360\stopoldprimitive
13361
13362\startoldprimitive[title={\prm {unskip}}]
13363
13364This removes the last glue, if possible.
13365
13366\stopoldprimitive
13367
13368\startnewprimitive[title={\prm {untraced}}]
13369
13370Related to the meaning providers is the \prm {untraced} prefix. It marks a macro
13371as to be reported by name only. It makes the macro look like a primitive.
13372
13373\starttyping
13374         \def\foo{}
13375\untraced\def\oof{}
13376
13377\scratchtoks{\foo\foo\oof\oof}
13378
13379\tracingall \the\scratchtoks \tracingnone
13380\stoptyping
13381
13382This will show up in the log as follows:
13383
13384\starttyping
133851:4: {\the}
133861:5: \foo ->
133871:5: \foo ->
133881:5: \oof
133891:5: \oof
13390\stoptyping
13391
13392This is again a trick to avoid too much clutter in a log. Often it doesn't matter
13393to users what the meaning of a macro is (if they trace at all). \footnote {An
13394earlier variant could also hide the expansion completely but that was just
13395confusing.}
13396
13397\stopnewprimitive
13398
13399\startoldprimitive[title={\prm {unvbox}}]
13400
13401A box is a packaged list and once packed travels through the system as a single
13402object with properties, like dimensions. This primitive injects the original list
13403and discards the wrapper.
13404
13405\stopoldprimitive
13406
13407\startoldprimitive[title={\prm {unvcopy}}]
13408
13409This is like \prm {unvbox} but keeps the original. It is one of the more costly
13410operations.
13411
13412\stopoldprimitive
13413
13414\startnewprimitive[title={\prm {unvpack}}]
13415
13416This primitive is like \prm {unvbox} but without the callback overhead.
13417
13418\stopnewprimitive
13419
13420\startoldprimitive[title={\prm {uppercase}}]
13421
13422See its counterpart \prm {lowercase} for an explanation.
13423
13424\stopoldprimitive
13425
13426\startoldprimitive[title={\prm {vadjust}}]
13427
13428This injects a node that stores material that will injected before or after the
13429line where it has become part of. In \LUAMETATEX\ there are more features, driven
13430by keywords.
13431
13432\stopoldprimitive
13433
13434\startoldprimitive[title={\prm {valign}}]
13435
13436This command starts vertically aligned material. Its counterpart \prm {halign} is
13437used more frequently. Most macro packages provide wrappers around these commands.
13438First one specifies a preamble which is then followed by entries (rows and
13439columns).
13440
13441\stopoldprimitive
13442
13443\startnewprimitive[title={\prm {variablefam}}]
13444
13445In traditional \TEX\ sets the family of what are considered variables (class 7)
13446to the current family (which often means that they adapt to the current alphabet)
13447and then injects a math character of class ordinary. This parameter can be used
13448to obey the given class when the family set for a character is the same as this
13449parameter. So we then use the given class with the current family. It is mostly
13450there for compatibility with \LUATEX\ and experimenting (outside \CONTEXT).
13451
13452\stopnewprimitive
13453
13454\startoldprimitive[title={\prm {vbadness}}]
13455
13456This sets the threshold for reporting a (vertical) badness value, its current
13457value is \the \badness.
13458
13459\stopoldprimitive
13460
13461\startnewprimitive[title={\prm {vbadnessmode}}]
13462
13463This parameter determines what gets reported when the (in the vertical packer)
13464badness exceeds some limit. The current value of this bitset is {\tt
13465"\tohexadecimal \vbadnessmode}.
13466
13467\startfourrows
13468\getbuffer[engine:syntax:badnessmodecodes]
13469\stopfourrows
13470
13471\stopnewprimitive
13472
13473\startnewprimitive[title={\prm {vbalance}}]
13474
13475In addition to the page builder and vbox splitter we have what's called a
13476balancer. This routine splits a vertical list in pieces (slots) according to a
13477specification (see \typ {\balanceshape}). It can do so in multiple passes (see
13478\typ {\balancepasses}). The balancing \quote {framework} operates independently
13479from the page builder and vsplitter.
13480
13481Because there are multiple primitives involved and because one will normally
13482write decent wrapper, wd delegate a more detailed explanation to a \CONTEXT\ low
13483level manual.
13484
13485\startbuffer
13486\setbox 0 \vbox\bgroup \hsize 10em
13487  line 1\par line 2\par line 3\par
13488  line 4\par line 5\par line 6\par
13489  line 7\par line 8\par
13490\egroup
13491\balancetopskip          \strutht
13492\balancebottomskip       \strutht
13493\balancevsize            3\lineheight
13494\balancetolerance        100
13495\balanceemergencystretch 0pt
13496\setbox 2 \vbalance 0
13497\hbox \bgroup
13498    \vbalancedbox 2 \hskip2em
13499    \vbalancedbox 2 \hskip2em
13500    \vbalancedbox 2
13501\egroup
13502\stopbuffer
13503
13504\typebuffer
13505
13506Here we use a simple specification (no shape). The balancer does a whole list
13507optimization so it does honor penalties and works with some tolerance too.
13508Decisions are made on badness and demerits. Like the par builder you can get
13509overfull slots so in practice one might rebalance with different specifications
13510if that happens.
13511
13512The results are collected in a box (in this example box register 2) which destroys the
13513original. With
13514
13515\starttyping
13516\setbox 2 \vbalance trial 0
13517\stoptyping
13518
13519we keep the original and the result will have empty boxes with the dimensions of
13520the slots. You can loop over the result and check the real height with \typ
13521{\balanceshapevsize}.
13522
13523\getbuffer
13524
13525\stopnewprimitive
13526
13527\startnewprimitive[title={\prm {vbalancedbox}}]
13528
13529This command take the topmost balanced slot from the given balanced box and wraps
13530it in a \type {\vbox}. When there is is no more to fetch the result is void.
13531
13532\stopnewprimitive
13533
13534\startnewprimitive[title={\prm {vbalanceddeinsert}}]
13535
13536This will convert the inserts in the given balancing result into a form that is
13537useable for the balancer. This is not mandate but needed if you want split
13538insertions. The keyword \type {descend} will locate the relevant box and \type
13539{forcedepth} will make sure that we get constant depths (but expects \prm
13540{insertlinedepth} being set.
13541
13542\stopnewprimitive
13543
13544\startnewprimitive[title={\prm {vbalanceddiscard}}]
13545
13546One of the features of balancing is that we can can have discardable content at
13547the top and|/|or bottom of slots. This primitive will remove discarded content
13548from the given result of \type {\vbalance}, like:
13549
13550\starttyping
13551\setbox 2 \vbalance 0
13552\vbalanceddiscard 2
13553\stoptyping
13554
13555\stopnewprimitive
13556
13557\startnewprimitive[title={\prm {vbalancedinsert}}]
13558
13559This one fetches the inserts from a balanced slot result. This happens per insert
13560class.
13561
13562\starttyping
13563\setbox 4 \vbalancedinsert 2 4
13564\stoptyping
13565
13566Instead you can give:
13567
13568\starttyping
13569\setbox 4 \vbalancedinsert 2 index 4 descend \relax
13570\stoptyping
13571
13572Here \type {descend} will locate the relevant slot box which is handy in case one
13573already wrapped the result in a box.
13574
13575\stopnewprimitive
13576
13577\startnewprimitive[title={\prm {vbalancedreinsert}}]
13578
13579This will convert the inserts in the given balancing slot result into a more
13580original form, assumign that \prm {vbalanceddeinsert} was applied.. This is not
13581mandate and depends on what is expected further down the line (read: this is
13582macro package specific). You can use the keyword \type {descend} to locate the
13583relevant slot box.
13584
13585\stopnewprimitive
13586
13587\startnewprimitive[title={\prm {vbalancedtop}}]
13588
13589This command take the topmost balanced slot from the given balanced box and wraps
13590it in a \type {\vbox}. When there is is no more to fetch the result is void.
13591
13592\stopnewprimitive
13593
13594\startoldprimitive[title={\prm {vbox}}]
13595
13596This creates a vertical box. In the process callbacks can be triggered that can
13597preprocess the content, influence line breaking as well as assembling the
13598resulting paragraph. More can be found in dedicated manuals. The baseline is
13599at the bottom.
13600
13601\stopoldprimitive
13602
13603\startoldprimitive[title={\prm {vcenter}}]
13604
13605In traditional \TEX\ this box packer is only permitted in math mode but in
13606\LUAMETATEX\ it also works in text mode. The content is centered in the vertical
13607box.
13608
13609\stopoldprimitive
13610
13611\startoldprimitive[title={\prm {vfil}}]
13612
13613This is a shortcut for \typ {\vskip plus 1 fil} (first order filler).
13614
13615\stopoldprimitive
13616
13617\startoldprimitive[title={\prm {vfill}}]
13618
13619This is a shortcut for \typ {\vskip plus 1 fill} (second order filler).
13620
13621\stopoldprimitive
13622
13623\startoldprimitive[title={\prm {vfilneg}}]
13624
13625This is a shortcut for \typ {\vskip plus - 1 fil} so it can compensate \prm
13626{vfil}.
13627
13628\stopoldprimitive
13629
13630\startoldprimitive[title={\prm {vfuzz}}]
13631
13632This dimension sets the threshold for reporting vertical boxes that are under- or
13633overfull. The current value is \the \vfuzz.
13634
13635\stopoldprimitive
13636
13637\startnewprimitive[title={\prm {virtualhrule}}]
13638
13639This is a horizontal rule with zero dimensions from the perspective of the
13640frontend but the backend can access them as set.
13641
13642\stopnewprimitive
13643
13644\startnewprimitive[title={\prm {virtualvrule}}]
13645
13646This is a vertical rule with zero dimensions from the perspective of the frontend
13647but the backend can access them as set.
13648
13649\stopnewprimitive
13650
13651\startoldprimitive[title={\prm {vkern}}]
13652
13653This primitive is like \prm {kern} but will force the engine into vertical mode
13654if it isn't yet.
13655
13656\stopoldprimitive
13657
13658\startnewprimitive[title={\prm {vpack}}]
13659
13660This primitive is like \prm {vbox} but without the callback overhead.
13661
13662\stopnewprimitive
13663
13664\startnewprimitive[title={\prm {vpenalty}}]
13665
13666This primitive is like \prm {penalty} but will force the engine into vertical
13667mode if it isn't yet.
13668
13669\stopnewprimitive
13670
13671\startoldprimitive[title={\prm {vrule}}]
13672
13673This creates a vertical rule. Unless the height and depth are set they will
13674stretch to fix the available space. In addition to the traditional \type {width},
13675\type {height} and \type {depth} specifiers some more are accepted. These are
13676discussed in other manuals. See \prm {hrule} for a simple example.
13677
13678\stopoldprimitive
13679
13680\startoldprimitive[title={\prm {vsize}}]
13681
13682This sets (or gets) the current vertical size. While setting the \prm {hsize}
13683inside a \prm {vbox} has consequences, setting the \prm {vsize} mostly makes
13684sense at the outer level (the page).
13685
13686\stopoldprimitive
13687
13688\startoldprimitive[title={\prm {vskip}}]
13689
13690The given glue is injected in the vertical list. If possible vertical mode is
13691entered.
13692
13693\stopoldprimitive
13694
13695\startoldprimitive[title={\prm {vsplit}}]
13696
13697This operator splits a given amount from a vertical box. In \LUAMETATEX\ we can
13698split \type {to} but also \type {upto}, so that we don't have to repack the
13699result in order to see how much is actually in there.
13700
13701\stopoldprimitive
13702
13703\startnewprimitive[title={\prm {vsplitchecks}}]
13704
13705This parameter is passed to the \type {show_vsplit} callback.
13706
13707\stopnewprimitive
13708
13709\startoldprimitive[title={\prm {vss}}]
13710
13711This is the vertical variant of \prm {hss}. See there for what it means.
13712
13713\stopoldprimitive
13714
13715\startoldprimitive[title={\prm {vtop}}]
13716
13717This creates a vertical box. In the process callbacks can be triggered that can
13718preprocess the content, influence line breaking as well as assembling the
13719resulting paragraph. More can be found in dedicated manuals. The baseline is
13720at the top.
13721
13722\stopoldprimitive
13723
13724\startoldprimitive[title={\prm {wd}}]
13725
13726Returns the width of the given box.
13727
13728\stopoldprimitive
13729
13730\startoldprimitive[title={\prm {widowpenalties}}]
13731
13732This is an array of penalty put before the last lines in a paragraph. High values
13733discourage (or even prevent) a lone line at the beginning of a next page. This
13734command expects a count value indicating the number of entries that will follow.
13735The first entry is ends up before the last line.
13736
13737\stopoldprimitive
13738
13739\startoldprimitive[title={\prm {widowpenalty}}]
13740
13741This is the penalty put before a widow line in a paragraph. High values
13742discourage (or even prevent) a lone line at the beginning of a next page.
13743
13744\stopoldprimitive
13745
13746\startnewprimitive[title={\prm {wordboundary}}]
13747
13748The hypenation routine has to decide where a word begins and ends. If you want to
13749make sure that there is a proper begin or end of a word you can inject this
13750boundary.
13751
13752\stopnewprimitive
13753
13754\startnewprimitive[title={\prm {wrapuppar}}]
13755
13756What this primitive does can best be shown with an example:
13757
13758\startbuffer
13759some text\wrapuppar{one} and some\wrapuppar{two} more
13760\stopbuffer
13761
13762\typebuffer
13763
13764We get:
13765
13766\blank \getbuffer \blank
13767
13768So, it is a complementary command to \prm {everypar}. It can only be issued
13769inside a paragraph.
13770
13771\stopnewprimitive
13772
13773\startoldprimitive[title={\prm {xdef}}]
13774
13775This is an alternative for \type {\global \edef}:
13776
13777\starttyping
13778\xdef\MyMacro{...}
13779\stoptyping
13780
13781\stopoldprimitive
13782
13783\startnewprimitive[title={\prm {xdefcsname}}]
13784
13785This is the companion of \prm {xdef}:
13786
13787\starttyping
13788\expandafter\xdef\csname MyMacro:1\endcsname{...}
13789             \xdefcsname MyMacro:1\endcsname{...}
13790\stoptyping
13791
13792\stopnewprimitive
13793
13794\startoldprimitive[title={\prm {xleaders}}]
13795
13796See \prm {gleaders} for an explanation.
13797
13798\stopoldprimitive
13799
13800\startoldprimitive[title={\prm {xspaceskip}}]
13801
13802Normally the glue inserted when a space is encountered after a character with a
13803space factor other than 1000 is taken from the font (fontdimen 7) unless this
13804parameter is set in which case its value is added.
13805
13806\stopoldprimitive
13807
13808\startnewprimitive[title={\prm {xtoks}}]
13809
13810This is the global variant of \prm {etoks}.
13811
13812\stopnewprimitive
13813
13814\startnewprimitive[title={\prm {xtoksapp}}]
13815
13816This is the global variant of \prm {etoksapp}.
13817
13818\stopnewprimitive
13819
13820\startnewprimitive[title={\prm {xtokspre}}]
13821
13822This is the global variant of \prm {etokspre}.
13823
13824\stopnewprimitive
13825
13826\startoldprimitive[title={\prm {year}}]
13827
13828This internal number starts out with the year that the job started.
13829
13830\stopoldprimitive
13831
13832\stopsection
13833
13834\page
13835
13836\startsection[title=Syntax]
13837
13838\startpagecolumns[page=no]
13839    \startluacode
13840        moduledata.engine.allspecifications()
13841    \stopluacode
13842\stoppagecolumns
13843
13844\stopsection
13845
13846\page
13847
13848\startluacode
13849    local match = string.match
13850    local find  = string.match
13851
13852    function document.CheckCompleteness()
13853        local primitives = token.getprimitives()
13854        local luametatex = { }
13855        local indexed    = { }
13856        local everything = { }
13857
13858        for i=1,#primitives do
13859            local prim = primitives[i]
13860            local name = prim[3]
13861            if not name then
13862                print("no name, case 1")
13863            elseif prim[4] == 4 then
13864                if find(name,"U") or find(name,"math") then
13865                    -- ignore
13866                    luametatex[name] = nil
13867                    everything[name] = false
13868                else
13869                    luametatex[name] = false
13870                end
13871            else
13872                everything[name] = true
13873            end
13874        end
13875
13876        local function collect(index)
13877            if index then
13878                local data = index.entries
13879                for i=1,#data do
13880                    local name = match(data[i].list[1][1],"\\tex%s*{(.-)}") or ""
13881                    if name then
13882                        if luametatex[name] == false then
13883                            luametatex[name] = true
13884                        end
13885                        indexed[name] = true
13886                        everything[name] = nil
13887                    else
13888                        print("no name, case 2")
13889                    end
13890                end
13891            end
13892        end
13893
13894        collect(structures.registers.collected and structures.registers.collected.index)
13895
13896        context.startsection { title = "To be checked primitives (new)" }
13897
13898        context.blank()
13899        context.startcolumns()
13900     -- context.starttworows()
13901        for k, v in table.sortedhash(luametatex) do
13902            if not v then
13903                context.dontleavehmode()
13904                context.type(k)
13905                context.crlf()
13906            end
13907        end
13908     -- context.stoptworows()
13909        context.stopcolumns()
13910
13911        context.page()
13912
13913        context.stopsection()
13914
13915        everything[""]  = nil
13916        everything[" "] = nil
13917
13918        context.startsection { title = "To be checked primitives (math)" }
13919
13920        context.blank()
13921        context.startcolumns()
13922     -- context.starttworows()
13923        for k, v in table.sortedhash(everything) do
13924            if not v then
13925                context.dontleavehmode()
13926                context.type(k)
13927                context.crlf()
13928            end
13929        end
13930     -- context.stoptworows()
13931        context.stopcolumns()
13932
13933        context("Many primitives starting with \\type{Umath} are math parameters that are discussed elsewhere, if at all.")
13934
13935        context.page()
13936
13937        context.stopsection()
13938
13939        context.startsection { title = "To be checked primitives (old)" }
13940
13941        context.blank()
13942        context.startcolumns()
13943     -- context.starttworows()
13944        for k, v in table.sortedhash(everything) do
13945            if v then
13946                context.dontleavehmode()
13947                context.type(k)
13948                context.crlf()
13949            end
13950        end
13951     -- context.stoptworows()
13952        context.stopcolumns()
13953
13954        context.page()
13955
13956        context.stopsection()
13957
13958        context.startsection { title = "Indexed primitives" }
13959
13960        context.blank()
13961        context.startcolumns()
13962     -- context.starttworows()
13963        for k, v in table.sortedhash(indexed) do
13964            context.dontleavehmode()
13965            if luametatex[k] == true then
13966                context("\\color[darkgreen]{\\tttf %s}",k)
13967            elseif luametatex[k] == false then
13968                context("\\color[darkred]{\\tttf %s}",k)
13969            else
13970                context("{\\tttf %s}",k)
13971            end
13972            context.crlf()
13973        end
13974     -- context.stoptworows()
13975        context.stopcolumns()
13976
13977        context.page()
13978
13979        context.stopsection()
13980    end
13981\stopluacode
13982
13983\startmode[atpragma]
13984    \startluacode
13985        context.page()
13986        document.CheckCompleteness()
13987    \stopluacode
13988
13989%     Run \type {s-system-syntax.mkxl} for a complete overview of the \LUAMETATEX\
13990%     primitives.
13991\stopmode
13992
13993\doifmode{checktodo}{\stopbodymatter}
13994
13995\popoverloadmode
13996
13997\stopdocument
13998
13999% disk and math options: orphaned
14000