1
2
3\setupexternalfigures
4 [location={default,global}]
5
6\enableexperiments[fonts.compact]
7\enableexperiments[fonts.accurate]
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29\usemodule[systemsyntax]
30\usemodule[systemunits]
31\usemodule[articlebasic]
32\usemodule[abbreviationslogos]
33\usemodule[scite]
34
35\setupinteraction
36 [state=start,
37 color=,
38 contrastcolor=,
39 style=,
40 contraststyle=]
41
42\definecolor[maincolor][darkblue]
43\definecolor[primcolor][darkblue]
44\definecolor[nonecolor][darkgray]
45
46\setuptyping
47 [option=tex]
48
49\setuptype
50 [option=tex]
51
52\setuphead
53 [subject]
54 [color=maincolor]
55
56\definehead
57 [newprimitive]
58 [subsection]
59 [color=maincolor]
60
61\definehead
62 [oldprimitive]
63 [subsection]
64 [
65 color=\ifcstok{\structureuservariable{obsolete}}{yes}darkred\else nonecolor\fi]
66
67\setuplist
68 [newprimitive]
69 [textcolor=maincolor]
70
71\setuplist
72 [oldprimitive]
73 [textcolor=nonecolor]
74
75
76
77
78\protected\def\prm#1
79
80
81 {\ifmode{*bodypart}\index{\tex{#1}}\fi\tex{#1}}
82
83\protected\def\stx#1
84 {\ctxlua{moduledata.engine.specification("#1")}}
85
86
87
88\starttext
89
90\startbodymatter
91
92\pushoverloadmode
93
94\startMPpage
95 fill Page
96 withcolor "darkgray" ;
97 draw textext("\sstf {\white new} primitives")
98 xysized (.9bbwidth(Page),bbheight(Page)-2cm)
99 shifted center Page
100 withcolor "maincolor" ;
101 draw textext.ulft("\sstf in luametatex")
102 xysized (.9bbwidth(Page)3,(bbheight(Page)-2cm)6)
103 shifted center lrcorner Page
104 shifted (-.1bbwidth(Page),.05bbwidth(Page))
105 withcolor "white" ;
106 setbounds currentpicture to Page ;
107\stopMPpage
108
109\startsubject[title={Introduction}]
110
111Here I will discuss some of the new primitives in \LUATEX\ and \LUAMETATEX, the
112later being a successor that permits the \CONTEXT\ folks to experiment with new
113features. The order is arbitrary. When you compare \LUATEX\ with \PDFTEX, there
114are actually quite some differences. Some primitives that \PDFTEX\ introduced
115have been dropped in \LUATEX\ because they can be done better in \LUA. Others
116have been promoted to core primitives that no longer have a \type {pdf} prefix.
117Then there are lots of new primitives, some introduce new concepts, some are a
118side effect of for instance new math font technologies, and then there are those
119that are handy extensions to the macro language. The \LUAMETATEX\ engine drops
120quite some primitives, like those related to \PDFTEX\ specific f(r)ont or backend
121features. It also adds some new primitives, mostly concerning the macro language.
122
123We also discuss the primitives that fit into the macro programming scope that are
124present in traditional \TEX\ and \ETEX\ but there are for sure better of
125explanations out there already. Primitives that relate to typesetting, like those
126controlling math, fonts, boxes, attributes, directions, catcodes, \LUA\
127(functions) etc are not discussed or discussed in less detail here.
128
129There are for instance primitives to create aliases to low level registers like
130counters and dimensions, as well as other (seminumeric) quantities like
131characters, but normally these are wrapped into high level macros so that
132definitions cant clash too much. Numbers, dimensions etc can be advanced,
133multiplied and divided and there is a simple expression mechanism to deal with
134them. We dont go into these details here: its mostly an overview of what the
135engine provides. If you are new to \TEX, you need to play a while with its mixed
136bag of typesetting and programming features in order to understand the difference
137between this macro language and other languages you might be familiar with.
138
139\startcolumns
140 \placelist
141 [newprimitive,oldprimitive]
142 [alternative=c]
143\stopcolumns
144
145In this document the section titles that discuss the \color [nonecolor] {original
146\TEX\ and \ETEX\ primitives} have a different color those explaining the \color
147[primcolor] {\LUATEX\ and \LUAMETATEX\ primitives}.
148
149Primitives that extend typesetting related functionality, provide control over
150subsystems (like math), allocate additional data types and resources, deal with
151fonts and languages, manipulate boxes and glyphs, etc.\ are hardly discussed
152here, only mentioned. Math for instance is a topic of its own. In this document
153we concentrate on the programming aspects.
154
155Most of the new primitives are discussed in specific manuals and often also
156original primitives are covered there but the best explanations of the
157traditional primitives can be found in The \TEX book by Donald Knuth and \TEX\ by
158Topic from Victor Eijkhout. I see no need to try to improve on those.
159
160
161
162
163\stopsubject
164
165
166
167
168
169\startsubject[title=Primitives]
170
171\startoldprimitive[title={\prm {<space>}}]
172
173This original \TEX\ primitive is equivalent to the more verbose \prm
174{explicitspace}.
175
176\stopoldprimitive
177
178\startoldprimitive[title={\prm {}}]
179
180This original \TEX\ primitive is equivalent to the more verbose \prm
181{explicitdiscretionary}.
182
183\stopoldprimitive
184
185\startoldprimitive[title={\prm {}}]
186
187This original \TEX\ primitive is equivalent to the more verbose \prm
188{explicititaliccorrection}.
189
190\stopoldprimitive
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681\startoldprimitive[title={\prm {above}}][obsolete=yes]
682
683This is a variant of \prm {over} that doesnt put a rule in between.
684
685\stopoldprimitive
686
687\startoldprimitive[title={\prm {abovedisplayshortskip}}]
688
689The glue injected before a display formula when the line above it is not
690overlapping with the formula. Watch out for interference with \prm
691{baselineskip}. It can be controlled by \prm {displayskipmode}.
692
693\stopoldprimitive
694
695\startoldprimitive[title={\prm {abovedisplayskip}}]
696
697The glue injected before a display formula. Watch out for interference with
698\prm {baselineskip}. It can be controlled by \prm {displayskipmode}.
699
700\stopoldprimitive
701
702\startoldprimitive[title={\prm {abovewithdelims}}][obsolete=yes]
703
704This is a variant of \prm {atop} but with delimiters. It has a more advanced
705upgrade in \prm {Uabovewithdelims}.
706
707\stopoldprimitive
708
709\startoldprimitive[title={\prm {accent}}][obsolete=yes]
710
711This primitive is kind of obsolete in wide engines and takes two arguments: the
712indexes of an accent and a base character.
713
714\stopoldprimitive
715
716\startnewprimitive[title={\prm {additionalpageskip}}]
717
718This quantity will be added to the current page goal, stretch and shrink after
719which it will be set to zero.
720
721\stopnewprimitive
722
723\startoldprimitive[title={\prm {adjdemerits}}]
724
725When \TEX\ considers to lines to be incompatible it will add this penalty to its
726verdict when considering this breakpoint.
727
728\stopoldprimitive
729
730\startnewprimitive[title={\prm {adjustspacing}}]
731
732This parameter controls expansion (hz). A value2 expands glyphs and font kerns
733and a value of3 only glyphs. Expansion of kerns can have side effects when they
734are used for positioning by \OPENTYPE\ features.
735
736\stopnewprimitive
737
738\startnewprimitive[title={\prm {adjustspacingshrink}}]
739
740When set to a non zero value this overloads the shrink maximum in a font when
741expansion is applied. This is then the case for all fonts.
742
743\stopnewprimitive
744
745\startnewprimitive[title={\prm {adjustspacingstep}}]
746
747When set to a non zero value this overloads the expansion step in a font when
748expansion is applied. This is then the case for all fonts.
749
750\stopnewprimitive
751
752\startnewprimitive[title={\prm {adjustspacingstretch}}]
753
754When set to a non zero value this overloads the stretch maximum in a font when
755expansion is applied. This is then the case for all fonts.
756
757\stopnewprimitive
758
759\startoldprimitive[title={\prm {advance}}]
760
761Advances the given register by an also given value:
762
763\starttyping
764\advance\scratchdimen 10pt
765\advance\scratchdimen by 3pt
766\advance\scratchcounterone \zerocount
767\advance\scratchcounterone \scratchcountertwo
768\stoptyping
769
770The \type {by} keyword is optional.
771
772\stopoldprimitive
773
774\startnewprimitive[title={\prm {advanceby}}]
775
776This is slightly more efficient variant of \prm {advance} that doesnt look for
777\type {by} and therefore, if one is missing, doesnt need to push back the last
778seen token. Using \prm {advance} with \type {by} is nearly as efficient but takes
779more tokens.
780
781\stopnewprimitive
782
783\startnewprimitive[title={\prm {afterassigned}}]
784
785The \prm {afterassignment} primitive stores a token to be injected (and thereby
786expanded) after an assignment has happened. Unlike \prm {aftergroup}, multiple
787calls are not accumulated, and changing that would be too incompatible. This is
788why we have \prm {afterassigned}, which can be used to inject a bunch of
789tokens. But in order to be consistent this one is also not accumulative.
790
791\startbuffer
792\afterassigned{done}
793\afterassigned{{\bf done}}
794\scratchcounter=123
795\stopbuffer
796
797\typebuffer
798
799results in: \inlinebuffer\ being typeset.
800
801\stopnewprimitive
802
803\startoldprimitive[title={\prm {afterassignment}}]
804
805The token following \prm {afterassignment}, a traditional \TEX\ primitive, is
806saved and gets injected (and then expanded) after a following assignment took
807place.
808
809\startbuffer
810\afterassignment !\def\MyMacro {}\quad
811\afterassignment !\let\MyMacro ?\quad
812\afterassignment !\scratchcounter 123\quad
813\afterassignment !
814\afterassignment ?\advance\scratchcounter by 1
815\stopbuffer
816
817\typebuffer
818
819The \prm {afterassignment}s are not accumulated, the last one wins:
820
821{\getbuffer}
822
823\stopoldprimitive
824
825\startoldprimitive[title={\prm {aftergroup}}]
826
827The traditional \TEX\ \prm {aftergroup} primitive stores the next token and
828expands that after the group has been closed.
829
830\startbuffer
831before{ ! \aftergroup a\aftergroup f\aftergroup t\aftergroup e\aftergroup r}
832\stopbuffer
833
834Multiple \prm {aftergroup}s are combined:
835
836\typebuffer
837
838\getbuffer
839
840\stopoldprimitive
841
842\startnewprimitive[title={\prm {aftergrouped}}]
843
844The in itself powerful \prm {aftergroup} primitives works quite well, even
845if you need to do more than one thing: you can either use it multiple times, or
846you can define a macro that does multiple things and apply that after the group.
847However, you can avoid that by using this primitive which takes a list of tokens.
848
849\startbuffer
850regular
851\bgroup
852\aftergrouped{regular}
853\bf bold
854\egroup
855\stopbuffer
856
857\typebuffer
858
859Because it happens after the group, were no longer typesetting in bold.
860
861{\getbuffer}
862
863\stopnewprimitive
864
865\startnewprimitive[title={\prm {aliased}}]
866
867This primitive is part of the overload protection subsystem where control sequences
868can be tagged.
869
870\startbuffer
871\permanent\def\foo{FOO}
872 \let\ofo\foo
873\aliased \let\oof\foo
874
875\meaningasis\foo
876\meaningasis\ofo
877\meaningasis\oof
878\stopbuffer
879
880\typebuffer
881
882gives:
883
884\startlines \tt
885\getbuffer
886\stoplines
887
888When a something is \prm {let} the \quote {permanent}, \quote {primitive} and
889\quote {immutable} flags are removed but the \prm {aliased} prefix retains
890them.
891
892\startbuffer
893\let\relaxed\relax
894
895\meaningasis\relax
896\meaningasis\relaxed
897\stopbuffer
898
899\typebuffer
900
901So in this example the \type {\relaxed} alias is not flagged as primitive:
902
903\startlines \tt
904\getbuffer
905\stoplines
906
907\stopnewprimitive
908
909\startnewprimitive[title={\prm {aligncontent}}]
910
911This is equivalent to a hash in an alignment preamble. Contrary to \prm
912{alignmark} there is no need to duplicate inside a macro definition.
913
914\stopnewprimitive
915
916\startnewprimitive[title={\prm {alignmark}}]
917
918When you have the \type {#} not set up as macro parameter character cq.\ align
919mark, you can use this primitive instead. The same rules apply with respect to
920multiple such tokens in (nested) macros and alignments.
921
922\stopnewprimitive
923
924\startnewprimitive[title={\prm {alignmentcellsource}}]
925
926This sets the source id (a box property) of the current alignment cell.
927
928\stopnewprimitive
929
930\startnewprimitive[title={\prm {alignmentwrapsource}}]
931
932This sets the source id (a box property) of the current alignment row (in a \prm
933{halign}) or column (in a \prm {valign}).
934
935\stopnewprimitive
936
937\startnewprimitive[title={\prm {aligntab}}]
938
939When you have the \type {} not set up as align tab, you can use this primitive
940instead. The same rules apply with respect to multiple such tokens in (nested)
941macros and alignments.
942
943\stopnewprimitive
944
945\startnewprimitive[title={\prm {allcrampedstyles}}]
946
947A symbolic representation of \prm {crampeddisplaystyle}, \prm {crampedtextstyle},
948\prm {crampedscriptstyle} and \prm {crampedscriptscriptstyle}; integer
949representation: \the\allcrampedstyles.
950
951\stopnewprimitive
952
953\startnewprimitive[title={\prm {alldisplaystyles}}]
954
955A symbolic representation of \prm {displaystyle} and \prm {crampeddisplaystyle};
956integer representation: \the\alldisplaystyles.
957
958\stopnewprimitive
959
960\startnewprimitive[title={\prm {allmainstyles}}]
961
962A symbolic representation of \prm {displaystyle}, \prm {crampeddisplaystyle},
963\prm {textstyle} and \prm {crampedtextstyle}; integer representation:
964\the\allmainstyles.
965
966\stopnewprimitive
967
968\startnewprimitive[title={\prm {allmathstyles}}]
969
970A symbolic representation of \prm {displaystyle}, \prm {crampeddisplaystyle},
971\prm {textstyle}, \prm {crampedtextstyle}, \prm {scriptstyle}, \prm
972{crampedscriptstyle}, \prm {scriptscriptstyle} and \prm
973{crampedscriptscriptstyle}; integer representation: \the\allmathstyles.
974
975\stopnewprimitive
976
977\startnewprimitive[title={\prm {allscriptscriptstyles}}]
978
979A symbolic representation of \prm {scriptscriptstyle} and \prm
980{crampedscriptscriptstyle}; integer representation: \the\allscriptscriptstyles.
981
982\stopnewprimitive
983
984\startnewprimitive[title={\prm {allscriptstyles}}]
985
986A symbolic representation of \prm {scriptstyle} and \prm {crampedscriptstyle};
987integer representation: \the\allscriptstyles.
988
989\stopnewprimitive
990
991\startnewprimitive[title={\prm {allsplitstyles}}]
992
993A symbolic representation of \prm {displaystyle} and \prm {textstyle} but not
994\prm {scriptstyle} and \prm {scriptscriptstyle}: set versus reset; integer
995representation: \the\allsplitstyles.
996
997\stopnewprimitive
998
999\startnewprimitive[title={\prm {alltextstyles}}]
1000
1001A symbolic representation of \prm {textstyle} and \prm {crampedtextstyle};
1002integer representation: \the\alltextstyles.
1003
1004\stopnewprimitive
1005
1006\startnewprimitive[title={\prm {alluncrampedstyles}}]
1007
1008A symbolic representation of \prm {displaystyle}, \prm {textstyle}, \prm
1009{scriptstyle} and \prm {scriptscriptstyle}; integer representation:
1010\the\alluncrampedstyles.
1011
1012\stopnewprimitive
1013
1014\startnewprimitive[title={\prm {allunsplitstyles}}]
1015
1016A symbolic representation of \prm {scriptstyle} and \prm {scriptscriptstyle}; integer
1017representation: \the\allunsplitstyles.
1018
1019\stopnewprimitive
1020
1021\startnewprimitive[title={\prm {amcode}}]
1022\stopnewprimitive
1023
1024\startnewprimitive[title={\prm {associateunit}}]
1025
1026The \TEX\ engine comes with some build in units, like \type {pt} (fixed) and
1027\type {em} (adaptive). On top of that a macro package can add additional units, which is
1028what we do in \CONTEXT. In \in {figure} [fig:units] we show the current repertoire.
1029
1030\startplacefigure[title=Available units,reference=fig:units]
1031 \showunitsmap[tight]
1032 \showunitsmaplegend
1033\stopplacefigure
1034
1035When this primitive is used in a context where a number is expected it returns the origin
1036of the unit (in the color legend running from 1 upto 4). A new unit is defined as:
1037
1038\starttyping
1039\newdimen\MyDimenZA \MyDimenZA=10pt
1040
1041\protected\def\MyDimenAB{\dimexpr\hsize2\relax}
1042
1043\associateunit za \MyDimenZA
1044\associateunit zb \MyMacroZB
1045\stoptyping
1046
1047Possible associations are: macros that expand to a dimension, internal dimension
1048registers, register dimensions (\prm {dimendef}, direct dimensions (\prm
1049{dimensiondef}) and \LUA\ functions that return a dimension.
1050
1051One can run into scanning ahead issues where \TEX\ expects a unit and a user unit
1052gets expanded. This is why for instance in \CONTEXT\ we define the \type{ma} unit
1053as:
1054
1055\starttyping
1056\protected\def\mathaxisunit{\scaledmathaxis\mathstyle\norelax}
1057
1058\associateunit ma \mathaxisunit
1059\stoptyping
1060
1061So that it can be used in rule specifications that themselves look ahead for
1062keywords and therefore are normally terminated by a \prm {relax}. Adding the
1063extra \prm {norelax} will make the scanner see one that doesnt get fed back into
1064the input. Of course a macro package has to manage extra units in order to avoid
1065conflicts.
1066
1067\stopnewprimitive
1068
1069\startnewprimitive[title={\prm {atendoffile}}]
1070
1071The \prm {everyeof} primitive is kind of useless because you dont know if a file
1072(which can be a tokenlist processed as pseudo file) itself includes a file, which
1073then results in nested application of this token register. One way around this is:
1074
1075\startbuffer
1076\atendoffile\SomeCommand
1077\stopbuffer
1078
1079\typebuffer
1080
1081This acts on files the same way as \prm {atendofgroup} does. Multiple calls will
1082be accumulated and are bound to the current file.
1083
1084\stopnewprimitive
1085
1086\startnewprimitive[title={\prm {atendoffiled}}]
1087
1088This is the multi token variant of \prm {atendoffile}. Multiple invocations are
1089accumulated and by default prepended to the existing list. As with grouping this
1090permits proper nesting. You can force an append by the optional keyword {reverse}.
1091
1092\stopnewprimitive
1093
1094\startnewprimitive[title={\prm {atendofgroup}}]
1095
1096The token provided will be injected just before the group ends. Because
1097these tokens are collected, you need to be aware of possible interference
1098between them. However, normally this is managed by the macro package.
1099
1100\startbuffer
1101\bgroup
1102\atendofgroup\unskip
1103\atendofgroup )
1104(but it works okay
1105\egroup
1106\stopbuffer
1107
1108\typebuffer
1109
1110Of course these effects can also be achieved by combining (extra) grouping with
1111\prm {aftergroup} calls, so this is more a convenience primitives than a real
1112necessity: {\inlinebuffer}, as proven here.
1113
1114\stopnewprimitive
1115
1116\startnewprimitive[title={\prm {atendofgrouped}}]
1117
1118This is the multi token variant of \prm {atendofgroup}. Of course the next
1119example is somewhat naive when it comes to spacing and so, but it shows the
1120purpose.
1121
1122\startbuffer
1123\bgroup
1124\atendofgrouped{\bf QED}
1125\atendofgrouped{ (indeed)}
1126This sometimes looks nicer.
1127\egroup
1128\stopbuffer
1129
1130\typebuffer
1131
1132Multiple invocations are accumulated: {\inlinebuffer}.
1133
1134\stopnewprimitive
1135
1136\startoldprimitive[title={\prm {atop}}][obsolete=yes]
1137
1138This one stack two math elements on top of each other, like a fraction but with
1139no rule. It has a more advanced upgrade in \prm {Uatop}.
1140
1141\stopoldprimitive
1142
1143\startoldprimitive[title={\prm {atopwithdelims}}][obsolete=yes]
1144
1145This is a variant of \prm {atop} but with delimiters. It has a more advanced
1146upgrade in \prm {Uatopwithdelims}.
1147
1148\stopoldprimitive
1149
1150\startnewprimitive[title={\prm {attribute}}]
1151
1152The following sets an attribute(register) value:
1153
1154\starttyping
1155\attribute 999 = 123
1156\stoptyping
1157
1158An attribute is unset by assigning \the \attributeunsetvalue\ to it. A user needs
1159to be aware of attributes being used now and in the future of a macro package and
1160setting them this way is very likely going to interfere.
1161
1162\stopnewprimitive
1163
1164\startnewprimitive[title={\prm {attributedef}}]
1165
1166This primitive can be used to relate a control sequence to an attribute register
1167and can be used to implement a mechanism for defining unique ones that wont
1168interfere. As with other registers: leave management to the macro package in
1169order to avoid unwanted side effects!
1170
1171\stopnewprimitive
1172
1173\startnewprimitive[title={\prm {automaticdiscretionary}}]
1174
1175This is an alias for the automatic hyphen trigger \type {}.
1176
1177\stopnewprimitive
1178
1179\startnewprimitive[title={\prm {automatichyphenpenalty}}]
1180
1181The penalty injected after an automatic discretionary \type {}, when \prm
1182{hyphenationmode} enables this.
1183
1184\stopnewprimitive
1185
1186\startnewprimitive[title={\prm {automigrationmode}}]
1187
1188This bitset determines what will bubble up to an outer level:
1189
1190\getbuffer[engine:syntax:automigrationcodes]
1191
1192The current value is {\tttf 0x\tohexadecimal\automigrationmode}.
1193
1194\stopnewprimitive
1195
1196\startnewprimitive[title={\prm {autoparagraphmode}}]
1197
1198A paragraph can be triggered by an empty line, a \prm {par} token or an
1199equivalent of it. This parameter controls how \type {\par} is interpreted in
1200different scenarios:
1201
1202\getbuffer[engine:syntax:autoparagraphcodes]
1203
1204The current value is {\tttf 0x\tohexadecimal\autoparagraphmode} and setting it to
1205a nonzero value can have consequences for mechanisms that expect otherwise.
1206The text option uses the same code as an empty line. The macro option checks a
1207token in a macro preamble against the frozen \prm {\par} token. The last option
1208ignores the par token.
1209
1210\stopnewprimitive
1211
1212\startoldprimitive[title={\prm {badness}}]
1213
1214This one returns the last encountered badness value.
1215
1216\stopoldprimitive
1217
1218\startoldprimitive[title={\prm {baselineskip}}]
1219
1220This is the maximum glue put between lines. The depth of the previous and height
1221of the next line are substracted.
1222
1223\stopoldprimitive
1224
1225\startoldprimitive[title={\prm {batchmode}}]
1226
1227This command disables (error) messages which can safe some runtime in situations
1228where \TEXs characterbycharacter log output impacts runtime. It only makes
1229sense in automated workflows where one doesnt look at the log anyway.
1230
1231\stopoldprimitive
1232
1233\startnewprimitive[title={\prm {begincsname}}]
1234
1235The next code creates a control sequence token from the given serialized tokens:
1236
1237\starttyping
1238\csname mymacro\endcsname
1239\stoptyping
1240
1241When \type {\mymacro} is not defined a control sequence will be created with the
1242meaning \prm {relax}. A side effect is that a test for its existence might fail
1243because it now exists. The next sequence will {\em not} create an controil
1244sequence:
1245
1246\starttyping
1247\begincsname mymacro\endcsname
1248\stoptyping
1249
1250This actually is kind of equivalent to:
1251
1252\starttyping
1253\ifcsname mymacro\endcsname
1254 \csname mymacro\endcsname
1255\fi
1256\stoptyping
1257
1258\stopnewprimitive
1259
1260\startoldprimitive[title={\prm {begingroup}}]
1261
1262This primitive starts a group and has to be ended with \prm {endgroup}. See \prm
1263{beginsimplegroup} for more info.
1264
1265\stopoldprimitive
1266
1267\startnewprimitive[title={\prm {beginlocalcontrol}}]
1268
1269Once \TEX\ is initialized it will enter the main loop. In there certain commands
1270trigger a function that itself can trigger further scanning and functions. In
1271\LUAMETATEX\ we can have local main loops and we can either enter it from the
1272\LUA\ end (which we dont discuss here) or at the \TEX\ end using this primitive.
1273
1274\startbuffer
1275\scratchcounter100
1276
1277\edef\whatever{
1278 a
1279 \beginlocalcontrol
1280 \advance\scratchcounter 10
1281 b
1282 \endlocalcontrol
1283 \beginlocalcontrol
1284 c
1285 \endlocalcontrol
1286 d
1287 \advance\scratchcounter 10
1288}
1289
1290\the\scratchcounter
1291\whatever
1292\the\scratchcounter
1293\stopbuffer
1294
1295\typebuffer
1296
1297A bit of close reading probably gives an impression of what happens here:
1298
1299{\getbuffer}
1300
1301The local loop can actually result in material being injected in the current node
1302list. However, where normally assignments are not taking place in an \prm
1303{edef}, here they are applied just fine. Basically we have a local \TEX\ job, be
1304it that it shares all variables with the parent loop.
1305
1306\stopnewprimitive
1307
1308\startnewprimitive[title={\prm {beginmathgroup}}]
1309
1310In math mode grouping with \prm {begingroup} and \prm {endgroup} in some cases
1311works as expected, but because the math input is converted in a list that gets
1312processed later some settings can become persistent, like changes in style or
1313family. The engine therefore provides the alternatives \prm {beginmathgroup} and
1314\prm {endmathgroup} that restore some properties.
1315
1316\stopnewprimitive
1317
1318\startnewprimitive[title={\prm {beginsimplegroup}}]
1319
1320The original \TEX\ engine distinguishes two kind of grouping that at the user end
1321show up as:
1322
1323\starttyping
1324\begingroup \endgroup
1325\bgroup \egroup { }
1326\stoptyping
1327
1328where the last two pairs are equivalent unless the scanner explicitly wants to see a
1329left andor right brace and not an equivalent. For the sake of simplify we use
1330the aliases here. It is not possible to mix these pairs, so:
1331
1332\starttyping
1333\bgroup xxx\endgroup
1334\begingroup xxx\egroup
1335\stoptyping
1336
1337will in both cases issue an error. This can make it somewhat hard to write generic
1338grouping macros without somewhat dirty trickery. The way out is to use the generic
1339group opener \prm {beginsimplegroup}.
1340
1341Internally \LUAMETATEX\ is aware of what group it currently is dealing with and
1342there we distinguish:
1343
1344\starttabulate[]
1345\NC simple group \NC \type {\bgroup} \NC \type {\egroup} \NC \NR
1346\NC semi simple group \NC \type {\begingroup} \NC \type {\endgroup} \type {\endsimplegroup} \NC \NR
1347\NC also simple group \NC \type {\beginsimplegroup} \NC \type {\egroup} \type {\endgroup} \type {\endsimplegroup} \NC \NR
1348\NC math simple group \NC \type {\beginmathgroup} \NC \type {\endmathgroup} \NC \NR
1349\stoptabulate
1350
1351This means that you can say:
1352
1353\starttyping
1354\beginsimplegroup xxx\endsimplegroup
1355\beginsimplegroup xxx\endgroup
1356\beginsimplegroup xxx\egroup
1357\stoptyping
1358
1359So a group started with \prm {beginsimplegroup} can be finished in three ways
1360which means that the user (or calling macro) doesnt have take into account what
1361kind of grouping was used to start with. Normally usage of this primitive is
1362hidden in macros and not something the user has to be aware of.
1363
1364\stopnewprimitive
1365
1366\startoldprimitive[title={\prm {belowdisplayshortskip}}]
1367
1368The glue injected aftter a display formula when the line above it is not
1369overlapping with the formula (\TEX\ cant look ahead). Watch out for interference
1370with \prm {baselineskip}. It can be controlled by \prm {displayskipmode}.
1371
1372\stopoldprimitive
1373
1374\startoldprimitive[title={\prm {belowdisplayskip}}]
1375
1376The glue injected after a display formula. Watch out for interference with \prm
1377{baselineskip}. It can be controlled by \prm {displayskipmode}.
1378
1379\stopoldprimitive
1380
1381\startoldprimitive[title={\prm {binoppenalty}}][obsolete=yes]
1382
1383This internal quantity is a compatibility feature because normally we will use
1384the inter atom spacing variables.
1385
1386\stopoldprimitive
1387
1388\startoldprimitive[title={\prm {botmark}}][obsolete=yes]
1389
1390This is a reference to the last mark on the current page, it gives back tokens.
1391
1392\stopoldprimitive
1393
1394\startoldprimitive[title={\prm {botmarks}}]
1395
1396This is a reference to the last mark with the given id (a number) on the current
1397page, it gives back tokens.
1398
1399\stopoldprimitive
1400
1401\startnewprimitive[title={\prm {boundary}}]
1402
1403Boundaries are signals added to he current list. This primitive injects a user
1404boundary with the given (integer) value. Such a boundary can be consulted at the
1405\LUA\ end or with \prm {lastboundary}.
1406
1407\stopnewprimitive
1408
1409\startoldprimitive[title={\prm {box}}]
1410
1411This is the box register accessor. While other registers have one property a box
1412has many, like \prm {wd}, \prm {ht} and \prm {dp}. This primitive returns the box
1413and resets the register.
1414
1415\stopoldprimitive
1416
1417\startnewprimitive[title={\prm {boxadapt}}]
1418
1419Adapting will recalculate the dimensions with a scale factor for the glue:
1420
1421\startbuffer
1422\setbox 0 \hbox {test test test}
1423\setbox 2 \hbox {\red test test test} \boxadapt 0 200
1424\setbox 4 \hbox {\blue test test test} \boxadapt 0 200
1425\ruledhbox{\box0} \vskip\lineheight
1426\ruledhbox{\box0} \vskip\lineheight
1427\ruledhbox{\box0}
1428\stopbuffer
1429
1430\typebuffer
1431
1432Like \prm {boxfreeze} and \prm {boxrepack} this primitive has been introduced for
1433experimental usage, although we do use some in production code.
1434
1435\getbuffer
1436
1437\stopnewprimitive
1438
1439\startnewprimitive[title={\prm {boxanchor}}]
1440
1441This feature is part of an (experimental) mechanism that relates boxes. The
1442engine just tags a box and it is up to the macro package to deal with it.
1443
1444\startbuffer
1445\setbox0\hbox anchor "01010202 {test}\tohexadecimal\boxanchor0
1446\stopbuffer
1447
1448\typebuffer
1449
1450This gives: \inlinebuffer. Of course this feature is very macro specific and
1451should not be used across macro packages without coordination. An anchor has
1452two parts each not exceeding \type {0x0FFF}.
1453
1454\stopnewprimitive
1455
1456\startnewprimitive[title={\prm {boxanchors}}]
1457
1458This feature is part of an (experimental) mechanism that relates boxes. The
1459engine just tags a box and it is up to the macro package to deal with it.
1460
1461\startbuffer
1462\setbox0\hbox anchors "0101 "0202 {test}\tohexadecimal\boxanchors0
1463\stopbuffer
1464
1465\typebuffer
1466
1467This gives: \inlinebuffer. Of course this feature is very macro specific and
1468should not be used across macro packages without coordination. An anchor has
1469two parts each not exceeding \type {0x0FFF}.
1470
1471\stopnewprimitive
1472
1473\startnewprimitive[title={\prm {boxattribute}}]
1474
1475Every node, and therefore also every box gets the attributes set that are
1476active at the moment of creation. Additional attributes can be set too:
1477
1478\startbuffer
1479\darkred
1480\setbox0\hbox attr 9999 1 {whatever}
1481\the\boxattribute 0 \colorattribute
1482\the\boxattribute 0 9998
1483\the\boxattribute 0 9999
1484\stopbuffer
1485
1486\typebuffer
1487
1488A macro package should make provide a way define attributes that dont clash the
1489ones it needs itself, like, in \CONTEXT, the ones that can set a color
1490
1491\startlines \getbuffer \stoplines
1492
1493The number \the\attributeunsetvalue\ (\tohexadecimal\attributeunsetvalue)
1494indicates an unset attribute.
1495
1496\stopnewprimitive
1497
1498\startnewprimitive[title={\prm {boxdirection}}]
1499
1500The direction of a box defaults to \type {l2r} but can be explicitly set:
1501
1502\startbuffer
1503\setbox0\hbox direction 1 {this is a test}\textdirection1
1504\setbox2\hbox direction 0 {this is a test}\textdirection0
1505\the\boxdirection0: \box0
1506\the\boxdirection2: \box2
1507\stopbuffer
1508
1509\typebuffer
1510
1511The \prm {textdirection} does not influence the box direction:
1512
1513\startlines \getbuffer \stoplines
1514
1515\stopnewprimitive
1516
1517\startnewprimitive[title={\prm {boxfinalize}}]
1518
1519This is special version of \prm {boxfreeze} which we demonstrate
1520with an example:
1521
1522\startbuffer[setthem]
1523\setbox0\ruledvbox to 3cm{\hsize 2cm test\vskip10pt plus 10pt test}
1524\setbox2\copy0\setbox4\copy0\setbox6\copy0\setbox8\copy0
1525\stopbuffer
1526
1527\startbuffer[usethem]
1528\boxlimitate 0 0
1529\boxfreeze 2 0
1530\boxfinalize 4 500
1531\boxfinalize 6 250
1532\boxfinalize 8 100
1533
1534\hpack\bgroup
1535 \copy0\quad\copy2\quad\copy4\quad\copy6\quad\copy8
1536\egroup
1537\stopbuffer
1538
1539\typebuffer[usethem]
1540
1541where the boxes are populated with:
1542
1543\typebuffer[setthem]
1544
1545\startlinecorrection
1546\getbuffer[setthem,usethem]
1547\stoplinecorrection
1548
1549\stopnewprimitive
1550
1551\startnewprimitive[title={\prm {boxfreeze}}]
1552
1553Glue in a box has a fixed component that will always be used and stretch and
1554shrink that kicks in when needed. The effective value (width) of the glue is
1555driven by some box parameters that are set by the packaging routine. This is why
1556we can unbox: the original value is kept. It is the backend that calculates the
1557effective value. Te \prm {boxfreeze} primitive can do the same: turn the flexible
1558glue into a fixed one.
1559
1560\startbuffer
1561\setbox 0 \hbox to 6cm {\hss frost}
1562\setbox 2 \hbox to 6cm {\hss frost}
1563\boxfreeze 2 0
1564\ruledhbox{\unhbox 0}
1565\ruledhbox{\unhbox 2}
1566\stopbuffer
1567
1568\typebuffer
1569
1570The second parameter to \prm {boxfreeze} determines recursion. We dont recurse
1571here so just freeze the outer level:
1572
1573\getbuffer
1574
1575\stopnewprimitive
1576
1577\startnewprimitive[title={\prm {boxgeometry}}]
1578
1579A box can have an orientation, offsets andor anchors. These are stored
1580independently but for efficiency reasons we register if one or more of these
1581properties is set. This primitive accesses this state; it is a bitset:
1582
1583\getbuffer[engine:syntax:listgeometrycodes]
1584
1585\stopnewprimitive
1586
1587\startnewprimitive[title={\prm {boxlimit}}]
1588
1589This primitive will freeze the glue in a box but only when there is glue marked
1590with the limit option.
1591
1592\stopnewprimitive
1593
1594\startnewprimitive[title={\prm {boxlimitate}}]
1595
1596This primitive will freeze the glue in a box. It takes two arguments, a box
1597number and an number that when set to nonzero will recurse into nested lists.
1598
1599\stopnewprimitive
1600
1601\startnewprimitive[title={\prm {boxlimitmode}}]
1602
1603This variable controls if boxes with glue marked \quote {limit} will be checked
1604and frozen.
1605
1606\stopnewprimitive
1607
1608\startoldprimitive[title={\prm {boxmaxdepth}}]
1609
1610You can limit the depth of boxes being constructed. Its one of these parameters
1611that should be used with care because when that box is filled nested boxes can be
1612influenced.
1613
1614\stopoldprimitive
1615
1616\startnewprimitive[title={\prm {boxorientation}}]
1617
1618The orientation field can take quite some values and is discussed in one of the low level
1619\CONTEXT\ manuals. Some properties are dealt with in the \TEX\ engine because they
1620influence dimensions but in the end it is the backend that does the work.
1621
1622\stopnewprimitive
1623
1624\startnewprimitive[title={\prm {boxrepack}}]
1625
1626When a box of to wide or tight we can tweak it a bit with this primitive. The
1627primitive expects a box register and a dimension, where a positive number adds
1628and a negatie subtracts from the current box with.
1629
1630\startbuffer
1631\setbox 0 \hbox {test test test}
1632\setbox 2 \hbox {\red test test test} \boxrepack0 .2em
1633\setbox 4 \hbox {\green test test test} \boxrepack0 .2em
1634\ruledhbox{\box0} \vskip\lineheight
1635\ruledhbox{\box0} \vskip\lineheight
1636\ruledhbox{\box0}
1637\stopbuffer
1638
1639\typebuffer
1640
1641\getbuffer
1642
1643We can also use this primitive to check the natural dimensions of a box:
1644
1645\startbuffer
1646\setbox 0 \hbox spread 10pt {test test test}
1647\ruledhbox{\box0} (\the\boxrepack0,\the\wd0)
1648\stopbuffer
1649
1650\typebuffer
1651
1652In this context only one argument is expected.
1653
1654\getbuffer
1655
1656\stopnewprimitive
1657
1658\startnewprimitive[title={\prm {boxshift}}]
1659
1660Returns or sets how much the box is shifted: up or down in horizontally mode, left or
1661right in vertical mode.
1662
1663\stopnewprimitive
1664
1665\startnewprimitive[title={\prm {boxshrink}}]
1666
1667Returns the amount of shrink found (applied) in a box:
1668
1669\startbuffer
1670\setbox0\hbox to 4em {m m m m}
1671\the\boxshrink0
1672\stopbuffer
1673
1674\typebuffer
1675
1676gives: \inlinebuffer
1677
1678\stopnewprimitive
1679
1680\startnewprimitive[title={\prm {boxsource}}]
1681
1682This feature is part of an (experimental) mechanism that relates boxes. The
1683engine just tags a box and it is up to the macro package to deal with it.
1684
1685\startbuffer
1686\setbox0\hbox source 123 {m m m m}
1687\the\boxsource0
1688\stopbuffer
1689
1690\typebuffer
1691
1692This gives: \inlinebuffer. Of course this feature is very macro specific and
1693should not be used across macro packages without coordination.
1694
1695\stopnewprimitive
1696
1697\startnewprimitive[title={\prm {boxstretch}}]
1698
1699Returns the amount of stretch found (applied) in a box:
1700
1701\startbuffer
1702\setbox0\hbox to 6em {m m m m}
1703\the\boxstretch0
1704\stopbuffer
1705
1706\typebuffer
1707
1708gives: \inlinebuffer
1709
1710\stopnewprimitive
1711
1712\startnewprimitive[title={\prm {boxtarget}}]
1713
1714This feature is part of an (experimental) mechanism that relates boxes. The
1715engine just tags a box and it is up to the macro package to deal with it.
1716
1717\startbuffer
1718\setbox0\hbox source 123 {m m m m}
1719\the\boxsource0
1720\stopbuffer
1721
1722\typebuffer
1723
1724This gives: \inlinebuffer. Of course this feature is very macro specific and
1725should not be used across macro packages without coordination.
1726
1727\stopnewprimitive
1728
1729\startnewprimitive[title={\prm {boxtotal}}]
1730
1731Returns the total of height and depth of the given box.
1732
1733\stopnewprimitive
1734
1735\startnewprimitive[title={\prm {boxvadjust}}]
1736
1737When used as query this returns a bitset indicating the associated adjust and
1738migration (marks and inserts) data:
1739
1740\starttabulate[Tl]
1741\NC 0x1 \NC pre adjusted \NC \NR
1742\NC 0x2 \NC post adjusted \NC \NR
1743\NC 0x4 \NC pre migrated \NC \NR
1744\NC 0x8 \NC post migrated \NC \NR
1745\stoptabulate\
1746
1747When used as a setter it directly adds adjust data to the box and it accepts the
1748same keywords as \prm {vadjust}.
1749
1750\stopnewprimitive
1751
1752\startnewprimitive[title={\prm {boxxmove}}]
1753
1754This will set the vertical offset and adapt the dimensions accordingly.
1755
1756\stopnewprimitive
1757
1758\startnewprimitive[title={\prm {boxxoffset}}]
1759
1760Returns or sets the horizontal offset of the given box.
1761
1762\stopnewprimitive
1763
1764\startnewprimitive[title={\prm {boxymove}}]
1765
1766This will set the vertical offset and adapt the dimensions accordingly.
1767
1768\stopnewprimitive
1769
1770\startnewprimitive[title={\prm {boxyoffset}}]
1771
1772Returns or sets the vertical offset of the given box.
1773
1774\stopnewprimitive
1775
1776\startoldprimitive[title={\prm {brokenpenalty}}]
1777
1778This penalty is added after a line that ends with a hyphen; it can help to
1779discourage a page break (or split in a box).
1780
1781\stopoldprimitive
1782
1783\startoldprimitive[title={\prm {catcode}}]
1784
1785Every character can be put in a category, but this is typically
1786something that the macro package manages because changes can affect
1787behavior. Also, once passed as an argument, the catcode of a character
1788is frozen. There are 16 different values:
1789
1790\starttabulate[lclc]
1791\NC \type {\escapecatcode } \NC \the\escapecatcode
1792\NC \type {\begingroupcatcode } \NC \the\begingroupcatcode \NC \NR
1793\NC \type {\endgroupcatcode } \NC \the\endgroupcatcode
1794\NC \type {\mathshiftcatcode } \NC \the\mathshiftcatcode \NC \NR
1795\NC \type {\alignmentcatcode } \NC \the\alignmentcatcode
1796\NC \type {\endoflinecatcode } \NC \the\endoflinecatcode \NC \NR
1797\NC \type {\parametercatcode } \NC \the\parametercatcode
1798\NC \type {\superscriptcatcode} \NC \the\superscriptcatcode \NC \NR
1799\NC \type {\subscriptcatcode } \NC \the\subscriptcatcode
1800\NC \type {\ignorecatcode } \NC \the\ignorecatcode \NC \NR
1801\NC \type {\spacecatcode } \NC \the\spacecatcode
1802\NC \type {\lettercatcode } \NC \the\lettercatcode \NC \NR
1803\NC \type {\othercatcode } \NC \the\othercatcode
1804\NC \type {\activecatcode } \NC \the\activecatcode \NC \NR
1805\NC \type {\commentcatcode } \NC \the\commentcatcode
1806\NC \type {\invalidcatcode } \NC \the\invalidcatcode \NC \NR
1807\stoptabulate
1808
1809The first column shows the constant that \CONTEXT\ provides and the
1810name indicates the purpose. Here are two examples:
1811
1812\starttyping
1813\catcode123=\begingroupcatcode
1814\catcode125=\endgroupcatcode
1815\stoptyping
1816
1817\stopoldprimitive
1818
1819\startnewprimitive[title={\prm {catcodetable}}]
1820
1821The catcode table with the given index will become active.
1822
1823\stopnewprimitive
1824
1825\startnewprimitive[title={\prm {cdef}}]
1826
1827This primitive is like \prm {edef} but in some usage scenarios is slightly
1828more efficient because (delayed) expansion is ignored which in turn saves
1829building a temporary token list.
1830
1831\startbuffer
1832\edef\FooA{this is foo} \meaningfull\FooA\crlf
1833\cdef\FooB{this is foo} \meaningfull\FooB\par
1834\stopbuffer
1835
1836\typebuffer {\tttf \getbuffer}
1837
1838\stopnewprimitive
1839
1840\startnewprimitive[title={\prm {cdefcsname}}]
1841
1842This primitive is like \prm {edefcsame} but in some usage scenarios is slightly
1843more efficient because (delayed) expansion is ignored which in turn saves
1844building a temporary token list.
1845
1846\startbuffer
1847\edefcsname FooA\endcsname{this is foo} \meaningasis\FooA\crlf
1848\cdefcsname FooB\endcsname{this is foo} \meaningasis\FooB\par
1849\stopbuffer
1850
1851\typebuffer {\tttf \getbuffer}
1852
1853\stopnewprimitive
1854
1855\startnewprimitive[title={\prm {cfcode}}]
1856
1857This primitive is a companion to \prm {efcode} and sets the compression factor.
1858It takes three values: font, character code, and factor.
1859
1860\stopnewprimitive
1861
1862\startoldprimitive[title={\prm {char}}]
1863
1864This appends a character with the given index in the current font.
1865
1866\stopoldprimitive
1867
1868\startoldprimitive[title={\prm {chardef}}]
1869
1870The following definition relates a control sequence to a specific character:
1871
1872\starttyping
1873\chardef\copyrightsign"A9
1874\stoptyping
1875
1876However, because in a context where a number is expected, such a \prm {chardef}
1877is seen as valid number, there was a time when this primitive was used to define
1878constants without overflowing the by then limited pool of count registers. In
1879\ETEX\ aware engines this was less needed, and in \LUAMETATEX\ we have \prm
1880{integerdef} as a more natural candidate.
1881
1882\stopoldprimitive
1883
1884\startoldprimitive[title={\prm {cleaders}}]
1885
1886See \prm {gleaders} for an explanation.
1887
1888\stopoldprimitive
1889
1890\startnewprimitive[title={\prm {clearmarks}}]
1891
1892This primitive is an addition to the multiple marks mechanism that originates in
1893\ETEX\ and reset the mark registers of the given category (a number).
1894
1895\stopnewprimitive
1896
1897\startoldprimitive[title={\prm {clubpenalties}}]
1898
1899This is an array of penalty put before the first lines in a paragraph. High values
1900discourage (or even prevent) a lone line at the end of a page. This
1901command expects a count value indicating the number of entries that will follow.
1902The first entry is ends up after the first line.
1903
1904\stopoldprimitive
1905
1906\startoldprimitive[title={\prm {clubpenalty}}]
1907
1908This is the penalty put before a club line in a paragraph. High values discourage
1909(or even prevent) a lone line at the end of a next page.
1910
1911\stopoldprimitive
1912
1913\startnewprimitive[title={\prm {constant}}]
1914
1915This prefix tags a macro (without arguments) as being constant. The main
1916consequence is that in some cases expansion gets delayed which gives a little
1917performance boost and less (temporary) memory usage, for instance in \type
1918{\csname} like scenarios.
1919
1920\stopnewprimitive
1921
1922\startnewprimitive[title={\prm {constrained}}]
1923
1924See previous section about \prm {retained}.
1925
1926\stopnewprimitive
1927
1928\startoldprimitive[title={\prm {copy}}]
1929
1930This is the box register accessor that returns a copy of the box.
1931
1932\stopoldprimitive
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943\startoldprimitive[title={\prm {count}}]
1944
1945This accesses a count register by index. This is kind of \quote {not done} unless
1946you do it local and make sure that it doesnt influence macros that you call.
1947
1948\starttyping
1949\count4023=10
1950\stoptyping
1951
1952In standard \TEX\ the first 10 counters are special because they get reported to
1953the console, and \type {\count0} is then assumed to be the page counter.
1954
1955\stopoldprimitive
1956
1957\startoldprimitive[title={\prm {countdef}}]
1958
1959This primitive relates a control sequence to a count register. Compare this to
1960the example in the previous section.
1961
1962\starttyping
1963\countdef\MyCounter4023
1964\MyCounter=10
1965\stoptyping
1966
1967However, this is also \quote {not done}. Instead one should use the allocator that
1968the macro package provides.
1969
1970\starttyping
1971\newcount\MyCounter
1972\MyCounter=10
1973\stoptyping
1974
1975In \LUAMETATEX\ we also have integers that dont rely on registers. These are
1976assigned by the primitive \prm {integerdef}:
1977
1978\starttyping
1979\integerdef\MyCounterA 10
1980\stoptyping
1981
1982Or better \type {\newinteger}.
1983
1984\starttyping
1985\newinteger\MyCounterB
1986\MyCounterN10
1987\stoptyping
1988
1989There is a lowlevel manual on registers.
1990
1991\stopoldprimitive
1992
1993\startoldprimitive[title={\prm {cr}}]
1994
1995This ends a row in an alignment. It also ends an alignment preamble.
1996\stopoldprimitive
1997
1998
1999\startnewprimitive[title={\prm {crampeddisplaystyle}}]
2000
2001A less spacy alternative of \prm {displaystyle}; integer representation:
2002\the\scriptstyle.
2003
2004\stopnewprimitive
2005
2006\startnewprimitive[title={\prm {crampedscriptscriptstyle}}]
2007
2008A less spacy alternative of \prm {scriptscriptstyle}; integer representation:
2009\the\scriptscriptstyle.
2010
2011\stopnewprimitive
2012
2013\startnewprimitive[title={\prm {crampedscriptstyle}}]
2014
2015A less spacy alternative of \prm {scriptstyle}; integer representation:
2016\the\scriptstyle.
2017
2018\stopnewprimitive
2019
2020\startnewprimitive[title={\prm {crampedtextstyle}}]
2021
2022A less spacy alternative of \prm {textstyle}; integer representation:
2023\the\textstyle.
2024
2025\stopnewprimitive
2026
2027\startoldprimitive[title={\prm {crcr}}]
2028
2029This ends a row in an alignment when it hasnt ended yet.
2030
2031\stopoldprimitive
2032
2033\startnewprimitive[title={\prm {csactive}}]
2034
2035Because \LUATEX\ (and \LUAMETATEX) are \UNICODE\ engines active characters are
2036implemented a bit differently. They dont occupy a eight bit range of characters
2037but are stored as control sequence with a special prefix \type {UFFFF} which
2038never shows up in documents. The \prm {csstring} primitive injects the name of a
2039control sequence without leading escape character, the \prm {csactive} injects
2040the internal name of the following (either of not active) character. As we cannot
2041display the prefix: \type {\csactive} will inject the \UTF\ sequences for \type
2042{UFFFF} and \type {U007E}, so here we get the bytes \type {EFBFBF7E}. Basically
2043the next token is preceded by \prm {string}, so when you dont provide a
2044character you are in for a surprise.
2045
2046\stopnewprimitive
2047
2048\startoldprimitive[title={\prm {csname}}]
2049
2050This original \TEX\ primitive starts the construction of a control sequence
2051reference. It does a lookup and when no sequence with than name is found, it will
2052create a hash entry and defaults its meaning to \prm {relax}.
2053
2054\starttyping
2055\csname letters and other characters\endcsname
2056\stoptyping
2057
2058\stopoldprimitive
2059
2060\startnewprimitive[title={\prm {csstring}}]
2061
2062This primitive returns the name of the control sequence given without the leading
2063escape character (normally a backslash). Of course you could strip that character
2064with a simple helper but this is more natural.
2065
2066\startbuffer
2067\csstring\mymacro
2068\stopbuffer
2069
2070\typebuffer
2071
2072We get the name, not the meaning: {\tt \inlinebuffer}.
2073
2074\stopnewprimitive
2075
2076\startoldprimitive[title={\prm {currentgrouplevel}}]
2077
2078\startbuffer
2079[\the\currentgrouplevel] \bgroup
2080 [\the\currentgrouplevel] \bgroup
2081 [\the\currentgrouplevel]
2082 \egroup [\the\currentgrouplevel]
2083\egroup [\the\currentgrouplevel]
2084\stopbuffer
2085
2086The next example gives: \inlinebuffer.
2087
2088\typebuffer
2089
2090\stopoldprimitive
2091
2092\startoldprimitive[title={\prm {currentgrouptype}}]
2093
2094\startbuffer
2095[\the\currentgrouptype] \bgroup
2096 [\the\currentgrouptype] \begingroup
2097 [\the\currentgrouptype]
2098 \endgroup [\the\currentgrouptype]
2099 [\the\currentgrouptype] \beginmathgroup
2100 [\the\currentgrouptype]
2101 \endmathgroup [\the\currentgrouptype]
2102[\the\currentgrouptype] \egroup
2103\stopbuffer
2104
2105The next example gives: \inlinebuffer.
2106
2107\typebuffer
2108
2109The possible values depend in the engine and for \LUAMETATEX\ they are:
2110
2111\startluacode
2112context.startcolumns { n = 4 }
2113context.starttabulate { "|r|l|" }
2114for i=0,#tex.groupcodes do
2115 context.NC() context(i)
2116 context.NC() context(tex.groupcodes[i])
2117 context.NC() context.NR()
2118end
2119context.stoptabulate()
2120context.stopcolumns()
2121\stopluacode
2122
2123\stopoldprimitive
2124
2125\startoldprimitive[title={\prm {currentifbranch}}]
2126
2127\startbuffer
2128[\the\currentifbranch] \iftrue
2129 [\the\currentifbranch] \iffalse
2130 [\the\currentifbranch]
2131 \else
2132 [\the\currentifbranch]
2133 \fi [\the\currentifbranch]
2134\fi [\the\currentifbranch]
2135\stopbuffer
2136
2137The next example gives: \inlinebuffer.
2138
2139\typebuffer
2140
2141So when in the \quote {then} branch we get plus one and when in the \quote {else}
2142branch we end up with a minus one.
2143
2144\stopoldprimitive
2145
2146\startoldprimitive[title={\prm {currentiflevel}}]
2147
2148\startbuffer
2149[\the\currentiflevel] \iftrue
2150 [\the\currentiflevel]\iftrue
2151 [\the\currentiflevel] \iftrue
2152 [\the\currentiflevel]
2153 \fi [\the\currentiflevel]
2154 \fi [\the\currentiflevel]
2155\fi [\the\currentiflevel]
2156\stopbuffer
2157
2158The next example gives: \inlinebuffer.
2159
2160\typebuffer
2161
2162\stopoldprimitive
2163
2164\startoldprimitive[title={\prm {currentiftype}}]
2165
2166\startbuffer
2167[\the\currentiftype] \iftrue
2168 [\the\currentiftype]\iftrue
2169 [\the\currentiftype] \iftrue
2170 [\the\currentiftype]
2171 \fi [\the\currentiftype]
2172 \fi [\the\currentiftype]
2173\fi [\the\currentiftype]
2174\stopbuffer
2175
2176The next example gives: \inlinebuffer.
2177
2178\typebuffer
2179
2180The values are engine dependent:
2181
2182\startluacode
2183local t = tex.getiftypes()
2184context.startcolumns { n = 5 }
2185context.starttabulate { "|r|l|" }
2186for i=0,#tex.groupcodes do
2187 context.NC() context(i)
2188 context.NC() context(t[i])
2189 context.NC() context.NR()
2190end
2191context.stoptabulate()
2192context.stopcolumns()
2193\stopluacode
2194
2195\stopoldprimitive
2196
2197\startnewprimitive[title={\prm {currentloopiterator}}]
2198
2199Here we show the different expanded loop variants:
2200
2201\startbuffer
2202\edef\testA{\expandedloop 1 10 1{!}}
2203\edef\testB{\expandedrepeat 10 {!}}
2204\edef\testC{\expandedendless {\ifnum\currentloopiterator>10 \quitloop\else !\fi}}
2205\edef\testD{\expandedendless {\ifnum#I>10 \quitloop\else !\fi}}
2206\stopbuffer
2207
2208\typebuffer \getbuffer
2209
2210All these give the same result:
2211
2212\startlines \tt
2213\meaningasis\testA
2214\meaningasis\testB
2215\meaningasis\testC
2216\meaningasis\testD
2217\stoplines
2218
2219The \type {#I} is a shortcut to the current loop iterator; other shortcuts are
2220\type {#P} for the parent iterator value and \type {#G} for the grand parent.
2221
2222\stopnewprimitive
2223
2224\startnewprimitive[title={\prm {currentloopnesting}}]
2225
2226This integer reports how many nested loops are currently active. Of course in
2227practice the value only has meaning when you know at what outer level your nested
2228loop started.
2229
2230\stopnewprimitive
2231
2232\startnewprimitive[title={\prm {currentmarks}}]
2233
2234Marks only get updated when a page is split off or part of a box using \prm
2235{vsplit} gets wrapped up. This primitive gives access to the current value of a
2236mark and takes the number of a mark class.
2237
2238\stopnewprimitive
2239
2240\startoldprimitive[title={\prm {currentstacksize}}]
2241
2242This is more diagnostic feature than a useful one but we show it anyway. There is
2243some basic overhead when we enter a group:
2244
2245\startbuffer
2246\bgroup [\the\currentstacksize]
2247 \bgroup [\the\currentstacksize]
2248 \bgroup [\the\currentstacksize]
2249 [\the\currentstacksize] \egroup
2250 [\the\currentstacksize] \egroup
2251[\the\currentstacksize] \egroup
2252\stopbuffer
2253
2254\typebuffer \getbuffer
2255
2256As soon as we define something or change a value, the stack gets populated by
2257information needed for recovery after the group ends.
2258
2259\startbuffer
2260\bgroup [\the\currentstacksize]
2261 \scratchcounter 1
2262 \bgroup [\the\currentstacksize]
2263 \scratchdimen 1pt
2264 \scratchdimen 2pt
2265 \bgroup [\the\currentstacksize]
2266 \scratchcounter 2
2267 \scratchcounter 3
2268 [\the\currentstacksize] \egroup
2269 [\the\currentstacksize] \egroup
2270[\the\currentstacksize] \egroup
2271\stopbuffer
2272
2273\typebuffer \getbuffer
2274
2275The stack also keeps some state information, for instance when a box is being
2276built. In \LUAMETATEX\ that is is quite a bit more than in other engines but it
2277is compensated by more efficient save stack handling elsewhere.
2278
2279\startbuffer
2280\hbox \bgroup [\the\currentstacksize]
2281 \hbox \bgroup [\the\currentstacksize]
2282 \hbox \bgroup [\the\currentstacksize]
2283 [\the\currentstacksize] \egroup
2284 [\the\currentstacksize] \egroup
2285[\the\currentstacksize] \egroup
2286\stopbuffer
2287
2288\typebuffer \getbuffer
2289
2290\stopoldprimitive
2291
2292\startoldprimitive[title={\prm {day}}]
2293
2294This internal number starts out with the day that the job started.
2295
2296\stopoldprimitive
2297
2298\startnewprimitive[title={\prm {dbox}}]
2299
2300A \prm {dbox} is just a \prm {vbox} (baseline at the bottom) but it has the
2301property \quote {dual baseline} which means that is some cases it will behave
2302like a \prm {vtop} (baseline at the top) too. Like:
2303
2304\ruledhbox\bgroup \showstruts
2305 \ruleddbox {\hsize 3cm \strut dbox \par \strut dbox \par\strut dbox }
2306 \ruledvbox {\hsize 3cm \strut vbox \par \strut vbox \par\strut vbox }
2307 \ruledvtop {\hsize 3cm \strut vtop \par \strut vtop \par\strut vtop }
2308 \ruledvcenter{\hsize 3cm \strut vcenter \par \strut vcenter \par\strut vcenter}
2309\egroup
2310
2311A \type {\dbox} behaves like a \type {\vtop} when its appended to a vertical list which
2312means that the height of the first box or rule determines the (base)line correction that
2313gets applied.
2314
2315
2316
2317\startlinecorrection
2318\startcombination [nx=3,ny=1,location=top]
2319 {\vbox \bgroup \hsize .3\textwidth
2320 \small\small \setupalign[tolerant,stretch] \dontcomplain
2321 xxxxxxxxxxxxxxxx\par
2322 \ruledvbox{\samplefile{ward}}\par
2323 xxxxxxxxxxxxxxxx\par
2324 \egroup} {\type {\vbox}}
2325 {\vbox \bgroup \hsize .3\textwidth
2326 \small\small \setupalign[tolerant,stretch] \dontcomplain
2327 xxxxxxxxxxxxxxxx\par
2328 \ruledvtop{\samplefile{ward}}\par
2329 xxxxxxxxxxxxxxxx\par
2330 \egroup} {\type {\vtop}}
2331 {\vbox \bgroup \hsize .3\textwidth
2332 \small\small \setupalign[tolerant,stretch] \dontcomplain
2333 xxxxxxxxxxxxxxxx\par
2334 \ruleddbox{\samplefile{ward}}\par
2335 xxxxxxxxxxxxxxxx\par
2336 \egroup} {\type {\dbox}}
2337\stopcombination
2338\stoplinecorrection
2339
2340\stopnewprimitive
2341
2342\startoldprimitive[title={\prm {deadcycles}}]
2343
2344This counter is incremented every time the output routine is entered. When \prm
2345{maxdeadcycles} is reached \TEX\ will issue an error message, so youd better
2346reset its value when a page is done.
2347
2348\stopoldprimitive
2349
2350\startoldprimitive[title={\prm {def}}]
2351
2352This is the main definition command, as in:
2353
2354\starttyping
2355\def\foo{l me}
2356\stoptyping
2357
2358with companions like \prm {gdef}, \prm {edef}, \prm {xdef}, etc. and variants
2359like:
2360
2361\starttyping
2362\def\foo#1{... #1...}
2363\stoptyping
2364
2365where the hash is used in the preamble and for referencing. More about that can
2366be found in the low level manual about macros.
2367
2368\stopoldprimitive
2369
2370\startoldprimitive[title={\prm {defaulthyphenchar}}][obsolete=yes]
2371
2372When a font is loaded its hyphen character is set to this value. It can be
2373changed afterwards. However, in \LUAMETATEX\ font loading is under \LUA\ control
2374so these properties can be set otherwise.
2375
2376\stopoldprimitive
2377
2378\startoldprimitive[title={\prm {defaultskewchar}}][obsolete=yes]
2379
2380When a font is loaded its skew character is set to this value. It can be changed
2381afterwards. However, in \LUAMETATEX\ font loading is under \LUA\ control so these
2382properties can be set otherwise. Also, \OPENTYPE\ math fonts have top anchor
2383instead.
2384
2385\stopoldprimitive
2386
2387\startnewprimitive[title={\prm {defcsname}}]
2388
2389We now get a series of log clutter avoidance primitives. Its fine if you argue
2390that they are not really needed, just dont use them.
2391
2392\starttyping
2393\expandafter\def\csname MyMacro:1\endcsname{...}
2394 \defcsname MyMacro:1\endcsname{...}
2395\stoptyping
2396
2397The fact that \TEX\ has three (expanded and global) companions can be seen as a
2398signal that less verbosity makes sense. Its just that macro packages use plenty
2399of \prm {csname}s.
2400
2401\stopnewprimitive
2402
2403\startnewprimitive[title={\prm {deferred}}]
2404
2405This is mostly a compatibility prefix and it can be checked at the \LUA\ end when
2406there is a \LUA\ based assignment going on. It is the counterpart of \prm
2407{immediate}. In the traditional engines a \prm {write} is normally deferred
2408(turned into a node) and can be handled \prm {immediate}, while a \prm {special}
2409does the opposite.
2410
2411\stopnewprimitive
2412
2413\startoldprimitive[title={\prm {delcode}}][obsolete=yes]
2414
2415This assigns delimiter properties to an eight bit character so it has little use
2416in an \OPENTYPE\ math setup. WHen the assigned value is hex encoded, the first
2417byte denotes the small family, then we have two bytes for the small index,
2418followed by three similar bytes for the large variant.
2419
2420\stopoldprimitive
2421
2422\startoldprimitive[title={\prm {delimiter}}][obsolete=yes]
2423
2424This command inserts a delimiter with the given specification. In \OPENTYPE\ math
2425we use a different command so it is unlikely that this primitive is used in
2426\LUAMETATEX. It takes a number that can best be coded hexadecimal: one byte for
2427the class, one for the small family, two for the small index, one for the large
2428family and two for the large index. This demonstrates that it cant handle wide
2429fonts. Also, in \OPENTYPE\ math fonts the larger sizes and extensible come from
2430the same font as the small symbol. On top of that, in \LUAMETATEX\ we have more
2431classes than fit in a byte.
2432
2433\stopoldprimitive
2434
2435\startoldprimitive[title={\prm {delimiterfactor}}][obsolete=yes]
2436
2437This is one of the parameters that determines the size of a delimiter: at least
2438this factor times the formula height divided by 1000. In \OPENTYPE\ math
2439different properties and strategies are used.
2440
2441\stopoldprimitive
2442
2443\startoldprimitive[title={\prm {delimitershortfall}}][obsolete=yes]
2444
2445This is one of the parameters that determines the size of a delimiter: at least
2446the formula height minus this parameter. In \OPENTYPE\ math different properties
2447and strategies are used.
2448
2449\stopoldprimitive
2450
2451\startnewprimitive[title={\prm {detokened}}]
2452
2453The following token will be serialized into characters with category \quote
2454{other}.
2455
2456\startbuffer
2457\toks0{123}
2458\def\foo{lets be \relaxd}
2459\def\oof#1{lets see #1}
2460\detokened\toks0
2461\detokened\foo
2462\detokened\oof
2463\detokened\setbox
2464\detokened X
2465\stopbuffer
2466
2467\typebuffer
2468
2469Gives:
2470
2471\startlines\tt
2472\getbuffer
2473\stoplines
2474
2475Macros with arguments are not shown.
2476
2477\stopnewprimitive
2478
2479\startoldprimitive[title={\prm {detokenize}}]
2480
2481This \ETEX\ primitive turns the content of the provides list will become
2482characters, kind of verbatim.
2483
2484\startbuffer
2485\expandafter\let\expandafter\temp\detokenize{1} \meaning\temp
2486\expandafter\let\expandafter\temp\detokenize{A} \meaning\temp
2487\stopbuffer
2488
2489\typebuffer
2490
2491\startlines \tttf \getbuffer \stoplines
2492
2493\stopoldprimitive
2494
2495\startnewprimitive[title={\prm {detokenized}}]
2496
2497The following (single) token will be serialized into characters with category
2498\quote {other}.
2499
2500\startbuffer
2501\toks0{123}
2502\def\foo{lets be \relaxd}
2503\def\oof#1{lets see #1}
2504\detokenized\toks0
2505\detokenized\foo
2506\detokenized\oof
2507\detokenized\setbox
2508\detokenized X
2509\stopbuffer
2510
2511\typebuffer
2512
2513Gives:
2514
2515\startlines\tt
2516\getbuffer
2517\stoplines
2518
2519It is one of these new primitives that complement others like \prm {detokened}
2520and such, and they are often mostly useful in experiments of some low level
2521magic, which made them stay.
2522
2523\stopnewprimitive
2524
2525\startoldprimitive[title={\prm {dimen}}]
2526
2527Like \prm {count} this is a register accessor which is described in more
2528detail in a low level manual.
2529
2530\starttyping
2531\dimen0=10pt
2532\stoptyping
2533
2534While \TEX\ has some assumptions with respect to the first ten count registers
2535(as well as the one that holds the output, normally 255), all dimension registers
2536are treated equal. However, you need to be aware of clashes with other usage.
2537Therefore you can best use the predefined scratch registers or define dedicate
2538ones with the \type {\newdimen} macro.
2539
2540\stopoldprimitive
2541
2542\startoldprimitive[title={\prm {dimendef}}]
2543
2544This primitive is used by the \type {\newdimen} macro when it relates a control
2545sequence with a specific register. Only use it when you know what youre doing.
2546
2547\stopoldprimitive
2548
2549\startnewprimitive[title={\prm {dimensiondef}}]
2550
2551A variant of \prm {integerdef} is:
2552
2553\starttyping
2554\dimensiondef\MyDimen = 1234pt
2555\stoptyping
2556
2557The properties are comparable to the ones described in the section \prm
2558{integerdef}.
2559
2560\stopnewprimitive
2561
2562\startoldprimitive[title={\prm {dimexpr}}]
2563
2564This primitive is similar to of \prm {numexpr} but operates on dimensions
2565instead. Integer quantities are interpreted as dimensions in scaled points.
2566
2567\startbuffer
2568\the\dimexpr (1pt 2pt 5pt) * 10 2 \relax
2569\stopbuffer
2570
2571\typebuffer
2572
2573gives: \inlinebuffer. You can mix in symbolic integers and dimensions. This doesnt work:
2574
2575\startbuffer
2576\the\dimexpr 10 * (1pt 2pt 5pt) 2 \relax
2577\stopbuffer
2578
2579because the engine scans for a dimension and only for an integer (or equivalent)
2580after a \type {*} or \type {}.
2581
2582
2583\stopoldprimitive
2584
2585\startnewprimitive[title={\prm {dimexpression}}]
2586
2587This command is like \prm {numexpression} but results in a dimension instead of
2588an integer. Where \prm {dimexpr} doesnt like \typ {2 * 10pt} this expression
2589primitive is quite happy with it.
2590
2591\stopnewprimitive
2592
2593\startnewprimitive[title={\prm {directlua}}]
2594
2595This is the low level interface to \LUA:
2596
2597\startbuffer
2598\directlua { tex.print ("Greetings from the lua end!") }
2599\stopbuffer
2600
2601Gives: \quotation {\inlinebuffer} as expected. In \LUA\ we have access to all
2602kind of internals of the engine. In \LUAMETATEX\ the interfaces have been
2603polished and extended compared to \LUATEX. Although many primitives and
2604mechanisms were added to the \TEX\ frontend, the main extension interface remains
2605\LUA. More information can be found in documents that come with \CONTEXT, in
2606presentations and in articles.
2607
2608\stopnewprimitive
2609
2610\startoldprimitive[title={\prm {discretionary}}]
2611
2612The three snippets given with this command determine the pre, post and replace
2613component of the injected discretionary node. The \type {penalty} keyword permits
2614setting a penalty with this node. The \type {postword} keyword indicates that
2615this discretionary starts a word, and \type {preword} ends it. With \type {break}
2616the line break algorithm will prefer a pre or post component over a replace, and
2617with \type {nobreak} replace will win over pre. With \type {class} you can set a
2618math class that will determine spacing and such for discretionaries used in math
2619mode.
2620
2621\stopoldprimitive
2622
2623\startnewprimitive[title={\prm {discretionaryoptions}}]
2624
2625Processing of discretionaries is controlled by this bitset:
2626
2627\getbuffer[engine:syntax:discoptioncodes]
2628
2629These can also be set on \prm {discretionary} using the \type {options} key.
2630
2631\stopnewprimitive
2632
2633\startoldprimitive[title={\prm {displayindent}}]
2634
2635The \prm {displaywidth}, \prm {displayindent} and \prm {predisplaysize}
2636parameters are set by the line break routine (but can be adapted by the user), so
2637that midpar display formula can adapt itself to hanging indentation and par
2638shapes. I order to calculate thee values and adapt the line break state
2639afterwards such a display formula is assumed to occupy three lines, so basically
2640a rather compact formula.
2641
2642\stopoldprimitive
2643
2644\startoldprimitive[title={\prm {displaylimits}}]
2645
2646By default in math display mode limits are place on top while in inline mode they
2647are placed like scripts, after the operator. Placement can be forced with the
2648\prm {limits} and \prm {nolimits} modifiers (after the operator). Because there
2649can be multiple of these in a row there is \prm {displaylimits} that forces the
2650default placement, so effectively it acts here as a reset modifier.
2651
2652\stopoldprimitive
2653
2654\startoldprimitive[title={\prm {displaystyle}}]
2655
2656One of the main math styles; integer representation: \the\displaystyle.
2657
2658\stopoldprimitive
2659
2660\startoldprimitive[title={\prm {displaywidowpenalties}}]
2661
2662This is a math specific variant of \prm {widowpenalties}.
2663
2664\stopoldprimitive
2665
2666\startoldprimitive[title={\prm {displaywidowpenalty}}]
2667
2668This is a math specific variant of \prm {widowpenalty}.
2669
2670\stopoldprimitive
2671
2672\startoldprimitive[title={\prm {displaywidth}}]
2673
2674This parameter determines the width of the formula and normally defaults to the
2675\prm {hsize} unless we are in the middle of a paragraph in which case it is
2676compensated for hanging indentation or the par shape.
2677
2678\stopoldprimitive
2679
2680\startoldprimitive[title={\prm {divide}}]
2681
2682The \prm {divide} operation can be applied to integers, dimensions, float,
2683attribute and glue quantities. There are subtle rounding differences between
2684the divisions in expressions and \prm {divide}:
2685
2686\starttabulate
2687\NC \type {\scratchcounter1049 \numexpr\scratchcounter 10\relax}
2688\EQ \scratchcounter1049 \the\numexpr\scratchcounter 10\relax
2689\NC \NR
2690\NC \type {\scratchcounter1049 \numexpr\scratchcounter: 10\relax}
2691\EQ \scratchcounter1049 \the\numexpr\scratchcounter: 10\relax
2692\NC \NR
2693\NC \type {\scratchcounter1049 \divide\scratchcounter by 10}
2694\EQ \scratchcounter1049 \divide\scratchcounter by 10
2695 \the\scratchcounter
2696\NC \NR
2697\stoptabulate
2698
2699The \type {:} divider in \prm {dimexpr} is something that we introduced in
2700\LUATEX.
2701
2702\stopoldprimitive
2703
2704\startnewprimitive[title={\prm {divideby}}]
2705
2706This is slightly more efficient variant of \prm {divide} that doesnt look for
2707\type {by}. See previous section.
2708
2709\stopnewprimitive
2710
2711\startnewprimitive[title={\prm {doubleadjdemerits}}]
2712
2713This penalty will be added to the penalty assigned to a breakpoint that results
2714in two incompatible lines (in \LUAMETATEX\ we can be more granular with respect
2715to compatible lines and this concerns a larger delta).
2716
2717\stopnewprimitive
2718
2719\startoldprimitive[title={\prm {doublehyphendemerits}}]
2720
2721This penalty will be added to the penalty assigned to a breakpoint that results
2722in two lines ending with a hyphen.
2723
2724\stopoldprimitive
2725
2726\startoldprimitive[title={\prm {dp}}]
2727
2728Returns the depth of the given box.
2729
2730\stopoldprimitive
2731
2732\startnewprimitive[title={\prm {dpack}}]
2733
2734This does what \prm {dbox} does but without callback overhead.
2735
2736\stopnewprimitive
2737
2738\startnewprimitive[title={\prm {dsplit}}]
2739
2740This is the dual baseline variant of \prm {vsplit} (see \prm {dbox} for what that
2741means).
2742
2743\stopnewprimitive
2744
2745\startoldprimitive[title={\prm {dump}}]
2746
2747This finishes an (ini) run and dumps a format (basically the current state of the
2748engine).
2749
2750\stopoldprimitive
2751
2752\startoldprimitive[title={\prm {edef}}]
2753
2754This is the expanded version of \prm {def}.
2755
2756\startbuffer
2757\def \foo{foo} \meaning\foo
2758\def \ofo{\foo\foo} \meaning\ofo
2759\edef\oof{\foo\foo} \meaning\oof
2760\stopbuffer
2761
2762\typebuffer
2763
2764Because \type {\foo} is unprotected it will expand inside the body definition:
2765
2766\startlines \tt
2767\getbuffer
2768\stoplines
2769
2770\stopoldprimitive
2771
2772\startnewprimitive[title={\prm {edefcsname}}]
2773
2774This is the companion of \prm {edef}:
2775
2776\starttyping
2777\expandafter\edef\csname MyMacro:1\endcsname{...}
2778 \edefcsname MyMacro:1\endcsname{...}
2779\stoptyping
2780
2781\stopnewprimitive
2782
2783\startnewprimitive[title={\prm {edivide}}]
2784
2785When expressions were introduced the decision was made to round the divisions which is
2786incompatible with the way \prm {divide} works. The expression scanners in \LUAMETATEX\
2787compensates that by providing a \type {:} for integer division. The \prm {edivide} does
2788the opposite: it rounds the way expressions do.
2789
2790\startbuffer
2791\the\dimexpr .4999pt : 2 \relax =.24994pt
2792\the\dimexpr .4999pt 2 \relax =.24995pt
2793\scratchdimen.4999pt \divide \scratchdimen 2 \the\scratchdimen=.24994pt
2794\scratchdimen.4999pt \edivide\scratchdimen 2 \the\scratchdimen=.24995pt
2795
2796\the\numexpr 1001 : 2 \relax =500
2797\the\numexpr 1001 2 \relax =501
2798\scratchcounter1001 \divide \scratchcounter 2 \the\scratchcounter=500
2799\scratchcounter1001 \edivide\scratchcounter 2 \the\scratchcounter=501
2800\stopbuffer
2801
2802\typebuffer
2803
2804Keep in mind that with dimensions we have a fractional part so we actually
2805rounding applies to the fraction. For that reason we also provide \prm {rdivide}.
2806
2807\startlines
2808\getbuffer
2809\stoplines
2810
2811\stopnewprimitive
2812
2813\startnewprimitive[title={\prm {edivideby}}]
2814
2815This the \type {by}less variant of \prm {edivide}.
2816
2817\stopnewprimitive
2818
2819\startnewprimitive[title={\prm {efcode}}]
2820
2821This primitive originates in \PDFTEX\ and can be used to set the expansion factor
2822of a glyph (characters). This primitive is obsolete because the values can be set
2823in the font specification that gets passed via \LUA\ to \TEX. Keep in mind that
2824setting font properties at the \TEX\ end is a global operation and can therefore
2825influence related fonts. In \LUAMETATEX\ the \prm {cf} code can be used to
2826specify the compression factor independent from the expansion factor. The
2827primitive takes three values: font, character code, and factor.
2828
2829\stopnewprimitive
2830
2831\startoldprimitive[title={\prm {else}}]
2832
2833This traditional primitive is part of the condition testing mechanism. When a
2834condition matches, \TEX\ will continue till it sees an \prm {else} or \prm
2835{or} or \prm {orelse} (to be discussed later). It will then do a fast skipping
2836pass till it sees an \prm {fi}.
2837
2838\stopoldprimitive
2839
2840\startoldprimitive[title={\prm {emergencyextrastretch}}]
2841
2842This is one of the extended parbuilder parameters. You can you it so temporary
2843increase the permitted stretch without knowing or messing with the normal value.
2844
2845\stopoldprimitive
2846
2847\startnewprimitive[title={\prm {emergencyleftskip}}]
2848
2849This is one of the extended parbuilder parameters (playground). It permits going
2850ragged left in case of a too bad result.
2851
2852\stopnewprimitive
2853
2854\startnewprimitive[title={\prm {emergencyrightskip}}]
2855
2856This is one of the extended parbuilder parameters (playground). It permits going
2857ragged right in case of a too bad result.
2858
2859\stopnewprimitive
2860
2861\startoldprimitive[title={\prm {emergencystretch}}]
2862
2863When set the par builder will run a third pass in order to fit the set criteria.
2864
2865\stopoldprimitive
2866
2867\startoldprimitive[title={\prm {end}}]
2868
2869This ends a \TEX\ run, unless of course this primitive is redefined.
2870
2871\stopoldprimitive
2872
2873\startoldprimitive[title={\prm {endcsname}}]
2874
2875This primitive is used in combination with \prm {csname}, \prm {ifcsname} and
2876\prm {begincsname} where its end the scanning for the to be constructed control
2877sequence token.
2878
2879\stopoldprimitive
2880
2881\startoldprimitive[title={\prm {endgroup}}]
2882
2883This is the companion of the \prm {begingroup} primitive that opens a group. See
2884\prm {beginsimplegroup} for more info.
2885
2886\stopoldprimitive
2887
2888\startoldprimitive[title={\prm {endinput}}]
2889
2890The engine can be in different input modes: reading from file, reading from a
2891token list, expanding a macro, processing something that comes back from \LUA,
2892etc. This primitive quits reading from file:
2893
2894\startbuffer
2895this is seen
2896\endinput
2897here were already quit
2898\stopbuffer
2899
2900\typebuffer
2901
2902There is a catch. This is what the above gives:
2903
2904\getbuffer
2905
2906but how about this:
2907
2908\startbuffer
2909this is seen
2910before \endinput after
2911here were already quit
2912\stopbuffer
2913
2914\typebuffer
2915
2916Here we get:
2917
2918\getbuffer
2919
2920Because a token list is one line, the following works okay:
2921
2922\starttyping
2923\def\quitrun{\ifsomething \endinput \fi}
2924\stoptyping
2925
2926but in a file youd have to do this when you quit in a conditional:
2927
2928\starttyping
2929\ifsomething
2930 \expandafter \endinput
2931\fi
2932\stoptyping
2933
2934While the oneliner works as expected:
2935
2936\starttyping
2937\ifsomething \endinput \fi
2938\stoptyping
2939
2940\stopoldprimitive
2941
2942\startoldprimitive[title={\prm {endlinechar}}]
2943
2944This is an internal integer register. When set to positive value the character
2945with that code point will be appended to the line. The current value is \the
2946\endlinechar. Here is an example:
2947
2948\startbuffer
2949\endlinechar\hyphenasciicode
2950line 1
2951line 2
2952\stopbuffer
2953
2954\typebuffer
2955
2956\start \getbuffer \stop
2957
2958If the character is active, the property is honored and the command kicks in. The
2959maximum value is 127 (the maximum character code a single byte \UTF\ character
2960can carry.)
2961
2962\stopoldprimitive
2963
2964\startnewprimitive[title={\prm {endlocalcontrol}}]
2965
2966See \prm {beginlocalcontrol}.
2967
2968\stopnewprimitive
2969
2970\startnewprimitive[title={\prm {endmathgroup}}]
2971
2972This primitive is the counterpart of \prm {beginmathgroup}.
2973
2974\stopnewprimitive
2975
2976\startnewprimitive[title={\prm {endsimplegroup}}]
2977
2978This one ends a simple group, see \prm {beginsimplegroup} for an explanation
2979about grouping primitives.
2980
2981\stopnewprimitive
2982
2983\startnewprimitive[title={\prm {enforced}}]
2984
2985The engine can be set up to prevent overloading of primitives and macros defined
2986as \prm {permanent} or \prm {immutable}. However, a macro package might want
2987to get around this in controlled situations, which is why we have a \prm
2988{enforced} prefix. This prefix in interpreted differently in so called \quote
2989{ini} mode when macro definitions can be dumped in the format. Internally they
2990get an \type {always} flag as indicator that in these places an overload is
2991possible.
2992
2993\starttyping
2994\permanent\def\foo{original}
2995
2996\def\oof {\def\foo{fails}}
2997\def\oof{\enforced\def\foo{succeeds}}
2998\stoptyping
2999
3000Of course this only has an effect when overload protection is enabled.
3001
3002\stopnewprimitive
3003
3004\startoldprimitive[title={\prm {eofinput}}]
3005
3006This is a variant on \prm {input} that takes a token list as first argument. That
3007list is expanded when the file ends. It has companion primitives \prm
3008{atendoffile} (single token) and \prm {atendoffiled} (multiple tokens).
3009
3010\stopoldprimitive
3011
3012\startoldprimitive[title={\prm {eqno}}]
3013
3014This primitive stores the (typeset) content (presumably a number) and when the
3015display formula is wrapped that number will end up right of the formula.
3016
3017\stopoldprimitive
3018
3019\startoldprimitive[title={\prm {errhelp}}]
3020
3021This is additional help information to \prm {errmessage} that triggers an error
3022and shows a message.
3023
3024\stopoldprimitive
3025
3026\startoldprimitive[title={\prm {errmessage}}]
3027
3028This primitive expects a token list and shows its expansion on the console
3029andor in the log file, depending on how \TEX\ is configured. After that it
3030will enter the error state and either goes on or waits for input, again depending
3031on how \TEX\ is configured. For the record: we dont use this primitive in
3032\CONTEXT.
3033
3034\stopoldprimitive
3035
3036\startoldprimitive[title={\prm {errorcontextlines}}]
3037
3038This parameter determines the number on lines shown when an error is triggered.
3039
3040\stopoldprimitive
3041
3042\startoldprimitive[title={\prm {errorstopmode}}]
3043
3044This directive stops at every opportunity to interact. In \CONTEXT\ we overload
3045the actions in a callback and quit the run because we can assume that a
3046successful outcome is unlikely.
3047
3048\stopoldprimitive
3049
3050\startoldprimitive[title={\prm {escapechar}}]
3051
3052This internal integer has the code point of the character that get prepended to a
3053control sequence when it is serialized (for instance in tracing or messages).
3054
3055\stopoldprimitive
3056
3057\startnewprimitive[title={\prm {etoks}}]
3058
3059This assigns an expanded token list to a token register:
3060
3061\starttyping
3062\def\temp{less stuff}
3063\etoks\scratchtoks{a bit \temp}
3064\stoptyping
3065
3066The orginal value of the register is lost.
3067
3068\stopnewprimitive
3069
3070\startnewprimitive[title={\prm {etoksapp}}]
3071
3072A variant of \prm {toksapp} is the following: it expands the to be appended
3073content.
3074
3075\starttyping
3076\def\temp{more stuff}
3077\etoksapp\scratchtoks{some \temp}
3078\stoptyping
3079
3080\stopnewprimitive
3081
3082\startnewprimitive[title={\prm {etokspre}}]
3083
3084A variant of \prm {tokspre} is the following: it expands the to be prepended
3085content.
3086
3087\starttyping
3088\def\temp{less stuff}
3089\etokspre\scratchtoks{a bit \temp}
3090\stoptyping
3091
3092\stopnewprimitive
3093
3094\startnewprimitive[title={\prm {eufactor}}]
3095
3096When we introduced the \type {es} (2.5cm) and \type {ts} (2.5mm) units as metric
3097variants of the \type {in} we also added the \type {eu} factor. One \type {eu}
3098equals one tenth of a \type {es} times the \prm {eufactor}. The \type {ts} is a
3099convenient offset in test files, the \type {es} a convenient ones for layouts and
3100image dimensions and the \type {eu} permits definitions that scale nicely without
3101the need for dimensions. They also were a prelude to what later became possible
3102with \prm {associateunit}.
3103
3104\stopnewprimitive
3105
3106\startnewprimitive[title={\prm {everybeforepar}}]
3107
3108This token register is expanded before a paragraph is triggered. The reason for
3109triggering is available in \prm {lastpartrigger}.
3110
3111\stopnewprimitive
3112
3113\startoldprimitive[title={\prm {everycr}}]
3114
3115This token list gets expanded when a row ends in an alignment. Normally it will
3116use \prm {noalign} as wrapper
3117
3118\startbuffer
3119{\everycr{\noalign{H}} \halign{#\cr test\cr test\cr}}
3120{\everycr{\noalign{V}} \hsize 4cm \valign{#\cr test\cr test\cr}}
3121\stopbuffer
3122
3123\typebuffer
3124
3125Watch how the \prm {cr} ending the preamble also get this treatment:
3126
3127\getbuffer
3128
3129\stopoldprimitive
3130
3131\startoldprimitive[title={\prm {everydisplay}}]
3132
3133This token list gets expanded every time we enter display mode. It is a companion
3134of \prm {everymath}.
3135
3136\stopoldprimitive
3137
3138\startoldprimitive[title={\prm {everyeof}}]
3139
3140The content of this token list is injected when a file ends but it can only be
3141used reliably when one is really sure that no other file is loaded in the
3142process. So in the end it is of no real use in a more complex macro package.
3143
3144\stopoldprimitive
3145
3146\startoldprimitive[title={\prm {everyhbox}}]
3147
3148This token list behaves similar to \prm {everyvbox} so look there for an
3149explanation.
3150
3151\stopoldprimitive
3152
3153\startoldprimitive[title={\prm {everyjob}}]
3154
3155This token list register is injected at the start of a job, or more precisely,
3156just before the main control loop starts.
3157
3158\stopoldprimitive
3159
3160\startoldprimitive[title={\prm {everymath}}]
3161
3162Often math needs to be set up independent from the running text and this token
3163list can be used to do that. There is also \prm {everydisplay}.
3164
3165\stopoldprimitive
3166
3167\startnewprimitive[title={\prm {everymathatom}}]
3168
3169When a math atom is seen this tokenlist is expanded before content is processed
3170inside the atom body.
3171
3172\stopnewprimitive
3173
3174\startoldprimitive[title={\prm {everypar}}]
3175
3176When a paragraph starts this tokenlist is expanded before content is processed.
3177
3178\stopoldprimitive
3179
3180\startnewprimitive[title={\prm {everytab}}]
3181
3182This token list gets expanded every time we start a table cell in \prm {halign} or
3183\prm {valign}.
3184
3185\stopnewprimitive
3186
3187\startoldprimitive[title={\prm {everyvbox}}]
3188
3189This token list gets expanded every time we start a vertical box. Like \prm
3190{everyhbox} this is not that useful unless you are certain that there are no
3191nested boxes that dont need this treatment. Of course you can wipe this register
3192in this expansion, like:
3193
3194\starttyping
3195\everyvbox{\kern10pt\everyvbox{}}
3196\stoptyping
3197
3198\stopoldprimitive
3199
3200\startnewprimitive[title={\prm {exceptionpenalty}}]
3201
3202In exceptions we can indicate a penalty by \type {[digit]} in which case a
3203penalty is injected set by this primitive, multiplied by the digit.
3204
3205\stopnewprimitive
3206
3207\startoldprimitive[title={\prm {exhyphenchar}}]
3208
3209The character that is used as pre component of the related discretionary.
3210
3211\stopoldprimitive
3212
3213\startoldprimitive[title={\prm {exhyphenpenalty}}]
3214
3215The penalty injected after \type {} or \type {\-} unless \prm {hyphenationmode}
3216is set to force the dedisated penalties.
3217
3218\stopoldprimitive
3219
3220\startnewprimitive[title={\prm {expand}}]
3221
3222Beware, this is not a prefix but a directive to ignore the protected characters of
3223the following macro.
3224
3225\startbuffer
3226\protected \def \testa{\the\scratchcounter}
3227 \edef\testb{\testa}
3228 \edef\testc{\expand\testa}
3229\stopbuffer
3230
3231\typebuffer
3232
3233The meaning of the three macros is:
3234
3235\startlines \getbuffer \tttf
3236\meaningfull\testa
3237\meaningfull\testb
3238\meaningfull\testc
3239\stoplines
3240
3241\stopnewprimitive
3242
3243\startnewprimitive[title={\prm {expandactive}}]
3244
3245This a bit of an outlier and mostly there for completeness.
3246
3247\startbuffer
3248 \meaningasis
3249\edef\foo{} \meaningasis\foo
3250\edef\foo{\expandactive} \meaningasis\foo
3251\stopbuffer
3252
3253\typebuffer
3254
3255There seems to be no difference but the real meaning of the first \type {\foo} is
3256\quote {active character 126} while the second \type {\foo} \quote {protected
3257call } is.
3258
3259
3260
3261\startlines
3262\getbuffer
3263\stoplines
3264
3265Of course the definition of the active tilde is \CONTEXT\ specific and situation
3266dependent.
3267
3268\stopnewprimitive
3269
3270\startoldprimitive[title={\prm {expandafter}}]
3271
3272This original \TEX\ primitive stores the next token, does a one level expansion
3273of what follows it, which actually can be an not expandable token, and
3274reinjects the stored token in the input. Like:
3275
3276\starttyping
3277\expandafter\let\csname my weird macro name\endcsname{m w m n}
3278\stoptyping
3279
3280Without \prm {expandafter} the \prm {csname} primitive would have been let to
3281the left brace (effectively then a begin group). Actually in this particular case
3282the control sequence with the weird name is injected and when it didnt yet exist
3283it will get the meaning \prm {relax} so we sort of have two assignments in a
3284row then.
3285
3286\stopoldprimitive
3287
3288\startnewprimitive[title={\prm {expandafterpars}}]
3289
3290Here is another gobbler: the next token is reinjected after following spaces
3291and par tokens have been read. So:
3292
3293\startbuffer
3294[\expandafterpars 1 2]
3295[\expandafterpars 3
32964]
3297[\expandafterpars 5
3298
32996]
3300\stopbuffer
3301
3302\typebuffer
3303
3304gives us: \inlinebuffer, because empty lines are like \prm {par} and therefore
3305ignored.
3306
3307\stopnewprimitive
3308
3309\startnewprimitive[title={\prm {expandafterspaces}}]
3310
3311This is a gobbler: the next token is reinjected after following spaces have been
3312read. Here is a simple example:
3313
3314\startbuffer
3315[\expandafterspaces 1 2]
3316[\expandafterspaces 3
33174]
3318[\expandafterspaces 5
3319
33206]
3321\stopbuffer
3322
3323\typebuffer
3324
3325We get this typeset: \inlinebuffer, because a newline normally is configured to be
3326a space (and leading spaces in a line are normally being ingored anyway).
3327
3328\stopnewprimitive
3329
3330\startnewprimitive[title={\prm {expandcstoken}}]
3331
3332The rationale behind this primitive is that when we \prm {let} a single token
3333like a character it is hard to compare that with something similar, stored in a
3334macro. This primitive pushes back a single token alias created by \prm {let}
3335into the input.
3336
3337\startbuffer
3338\let\tempA \meaning\tempA
3339
3340\let\tempB X \meaning\tempB \crlf
3341\let\tempC $ \meaning\tempC \par
3342
3343\edef\temp {\tempA} \doifelse{\temp}{}{Y}{N} \meaning\temp \crlf
3344\edef\temp {\tempB} \doifelse{\temp}{X}{Y}{N} \meaning\temp \crlf
3345\edef\temp {\tempC} \doifelse{\temp}{X}{Y}{N} \meaning\temp \par
3346
3347\edef\temp{\expandcstoken\tempA} \doifelse{\temp}{}{Y}{N} \meaning\temp \crlf
3348\edef\temp{\expandcstoken\tempB} \doifelse{\temp}{X}{Y}{N} \meaning\temp \crlf
3349\edef\temp{\expandcstoken\tempC} \doifelse{\temp}{$}{Y}{N} \meaning\temp \par
3350
3351\doifelse{\expandcstoken\tempA}{}{Y}{N}
3352\doifelse{\expandcstoken\tempB}{X}{Y}{N}
3353\doifelse{\expandcstoken\tempC}{$}{Y}{N} \par
3354\stopbuffer
3355
3356\typebuffer
3357
3358The meaning of the \prm {let} macros shows that we have a shortcut to a
3359character with (in this case) catcode letter, other (here \quote {other
3360character} gets abbreviated to \quote {character}), math shift etc.
3361
3362\start \tttf \getbuffer \stop
3363
3364Here we use the \CONTEXT\ macro \type {\doifelse} which can be implemented in
3365different ways, but the only property relevant to the user is that the expanded
3366content of the two arguments is compared.
3367
3368\stopnewprimitive
3369
3370\startnewprimitive[title={\prm {expanded}}]
3371
3372This primitive complements the two expansion related primitives mentioned in the
3373previous two sections. This time the content will be expanded and then pushed
3374back into the input. Protected macros will not be expanded, so you can use this
3375primitive to expand the arguments in a call. In \CONTEXT\ you need to use \type
3376{\normalexpanded} because we already had a macro with that name. We give some
3377examples:
3378
3379\startbuffer
3380\def\A{!}
3381 \def\B#1{\string#1} \B{\A}
3382 \def\B#1{\string#1} \normalexpanded{\noexpand\B{\A}}
3383\protected\def\B#1{\string#1} \B{\A}
3384\stopbuffer
3385
3386\typebuffer \startlines\getbuffer\stoplines
3387
3388\stopnewprimitive
3389
3390\startnewprimitive[title={\prm {expandedafter}}]
3391
3392The following two lines are equivalent:
3393
3394\startbuffer
3395\def\foo{123}
3396\expandafter[\expandafter[\expandafter\secondofthreearguments\foo]]
3397\expandedafter{[[\secondofthreearguments}\foo]]
3398\stopbuffer
3399
3400\typebuffer
3401
3402In \CONTEXT\ \MKIV\ the number of times that one has multiple \prm {expandafter}s
3403is much larger than in \CONTEXT\ \LMTX\ thanks to some of the new features in
3404\LUAMETATEX, and this primitive is not really used yet in the core code.
3405
3406\startlines\getbuffer\stoplines
3407
3408\stopnewprimitive
3409
3410\startnewprimitive[title={\prm {expandeddetokenize}}]
3411
3412This is a companion to \prm {detokenize} that expands its argument:
3413
3414\startbuffer
3415\def\foo{12#H3}
3416\def\oof{\foo}
3417\detokenize {\foo} \detokenize {\oof}
3418\expandeddetokenize{\foo} \expandeddetokenize{\oof}
3419\edef\ofo{\expandeddetokenize{\foo}} \meaningless\ofo
3420\edef\ofo{\expandeddetokenize{\oof}} \meaningless\ofo
3421\stopbuffer
3422
3423\typebuffer
3424
3425This is a bit more convenient than
3426
3427\starttyping
3428\detokenize \expandafter {\normalexpanded {\foo}}
3429\stoptyping
3430
3431kind of solutions. We get:
3432
3433\startlines
3434\getbuffer
3435\stoplines
3436
3437\stopnewprimitive
3438
3439\startnewprimitive[title={\prm {expandedendless}}]
3440
3441This one loops forever but because the loop counter is not set you need to find a
3442way to quit it.
3443
3444\stopnewprimitive
3445
3446\startnewprimitive[title={\prm {expandedloop}}]
3447
3448This variant of the previously introduced \prm {localcontrolledloop} doesnt
3449enter a local branch but immediately does its work. This means that it can be
3450used inside an expansion context like \prm {edef}.
3451
3452\startbuffer
3453\edef\whatever
3454 {\expandedloop 1 10 1
3455 {\scratchcounter=\the\currentloopiterator\relax}}
3456
3457\meaningasis\whatever
3458\stopbuffer
3459
3460\typebuffer
3461
3462\start \veryraggedright \tt\tfx \getbuffer \stop \blank
3463
3464\stopnewprimitive
3465
3466\startnewprimitive[title={\prm {expandedrepeat}}]
3467
3468This one takes one instead of three arguments which is sometimes more
3469convenient.
3470
3471\stopnewprimitive
3472
3473\startnewprimitive[title={\prm {expandparameter}}]
3474
3475This primitive is a predecessor of \prm {parameterdef} so we stick to a simple
3476example.
3477
3478\startbuffer
3479\def\foo#1#2
3480 {\integerdef\MyIndexOne\parameterindex\plusone
3481 \integerdef\MyIndexTwo\parameterindex\plustwo
3482 \oof{P}\oof{Q}\oof{R}\norelax}
3483
3484\def\oof#1
3485 {<1:\expandparameter\MyIndexOne><1:\expandparameter\MyIndexOne>
3486 #1
3487 <2:\expandparameter\MyIndexTwo><2:\expandparameter\MyIndexTwo>}
3488
3489\foo{A}{B}
3490\stopbuffer
3491
3492\typebuffer
3493
3494In principle the whole parameter stack can be accessed but often
3495one never knows if a specific macro is called nested. The original
3496idea behind this primitive was tracing but it can also be used to
3497avoid passing parameters along a chain of calls.
3498
3499\getbuffer
3500
3501\stopnewprimitive
3502
3503\startnewprimitive[title={\prm {expandtoken}}]
3504
3505This primitive creates a token with a specific combination of catcode and
3506character code. Because it assumes some knowledge of \TEX\ we can show it
3507using some \prm {expandafter} magic:
3508
3509\startbuffer
3510\expandafter\let\expandafter\temp\expandtoken 11 X \meaning\temp
3511\expandafter\let\expandafter\temp\expandtoken 12 X \meaning\temp
3512\stopbuffer
3513
3514\typebuffer
3515
3516The meanings are:
3517
3518\startlines \tttf \getbuffer \stoplines
3519
3520Using other catcodes is possible but the results of injecting them into the input
3521directly (or here by injecting \type {\temp}) can be unexpected because of what
3522\TEX\ expects. You can get messages you normally wont get, for instance about
3523unexpected alignment interference, which is a side effect of \TEX\ using some
3524catcodecharacter combinations as signals and there is no reason to change
3525those internals. That said:
3526
3527\startbuffer
3528\xdef\tempA{\expandtoken 9 X} \meaning\tempA
3529\xdef\tempB{\expandtoken 10 X} \meaning\tempB
3530\xdef\tempC{\expandtoken 11 X} \meaning\tempC
3531\xdef\tempD{\expandtoken 12 X} \meaning\tempD
3532\stopbuffer
3533
3534\typebuffer
3535
3536are all valid and from the meaning you cannot really deduce whats in there:
3537
3538\startlines \tttf \getbuffer \stoplines
3539
3540But you can be assured that:
3541
3542\startbuffer
3543[AB: \ifx\tempA\tempB Y\else N\fi]
3544[AC: \ifx\tempA\tempC Y\else N\fi]
3545[AD: \ifx\tempA\tempD Y\else N\fi]
3546[BC: \ifx\tempB\tempC Y\else N\fi]
3547[BD: \ifx\tempB\tempD Y\else N\fi]
3548[CD: \ifx\tempC\tempD Y\else N\fi]
3549\stopbuffer
3550
3551\typebuffer
3552
3553makes clear that theyre different: \inlinebuffer, and in case you wonder, the
3554characters with catcode 10 are spaces, while those with code 9 are ignored.
3555
3556\stopnewprimitive
3557
3558\startnewprimitive[title={\prm {expandtoks}}]
3559
3560This is a more efficient equivalent of \prm {the} applied to a token register,
3561so:
3562
3563\startbuffer
3564\scratchtoks{just some tokens}
3565\edef\TestA{[\the \scratchtoks]}
3566\edef\TestB{[\expandtoks\scratchtoks]}
3567[\the \scratchtoks] [\TestA] \meaning\TestA
3568[\expandtoks\scratchtoks] [\TestB] \meaning\TestB
3569\stopbuffer
3570
3571\typebuffer
3572
3573does the expected:
3574
3575\startlines
3576\getbuffer
3577\stoplines
3578
3579The \prm {expandtoken} primitive avoid a copy into the input when there is no
3580need for it.
3581
3582\stopnewprimitive
3583
3584\startnewprimitive[title={\prm {explicitdiscretionary}}]
3585
3586This is the verbose alias for one of \TEXs single character control sequences:
3587\type {\-}.
3588
3589\stopnewprimitive
3590
3591\startnewprimitive[title={\prm {explicithyphenpenalty}}]
3592
3593The penalty injected after an automatic discretionary \type {\-}, when \prm
3594{hyphenationmode} enables this.
3595
3596\stopnewprimitive
3597
3598\startnewprimitive[title={\prm {explicititaliccorrection}}]
3599
3600This is the verbose alias for one of \TEXs single character control sequences:
3601\type {\/}. Italic correction is a character property specific to \TEX\ and the
3602concept is not present in modern font technologies. There is a callback that
3603hooks into this command so that a macro package can provide its own solution
3604to this (or alternatively it can assign values to the italic correction field.
3605
3606\stopnewprimitive
3607
3608\startnewprimitive[title={\prm {explicitspace}}]
3609
3610This is the verbose alias for one of \TEXs single character control sequences:
3611\type {\ }. A space is inserted with properties according the space related
3612variables. There is lookback involved in order to deal with space factors.
3613
3614When \prm {nospaces} is set to1 no spaces are inserted, when its value is2 a
3615zero space is inserted.
3616
3617\stopnewprimitive
3618
3619\startoldprimitive[title={\prm {fam}}]
3620
3621In a numeric context it returns the current family number, otherwise it sets the
3622given family. The number of families in a traditional engine is 16, in \LUATEX\
3623it is 256 and in \LUAMETATEX\ we have at most \cldcontext {tex . magicconstants .
3624max_n_of_math_families} families. A future version can lower that number when we
3625need more classes.
3626
3627\stopoldprimitive
3628
3629\startoldprimitive[title={\prm {fi}}]
3630
3631This traditional primitive is part of the condition testing mechanism and ends a
3632test. So, we have:
3633
3634\starttyping
3635\ifsomething ... \else ... \fi
3636\ifsomething ... \or ... \or ... \else ... \fi
3637\ifsomething ... \orelse \ifsometing ... \else ... \fi
3638\ifsomething ... \or ... \orelse \ifsometing ... \else ... \fi
3639\stoptyping
3640
3641The \prm {orelse} is new in \LUAMETATEX\ and a continuation like we find in
3642other programming languages (see later section).
3643
3644\stopoldprimitive
3645
3646\startoldprimitive[title={\prm {finalhyphendemerits}}]
3647
3648This penalty will be added to the penalty assigned to a breakpoint when that
3649break results in a prelast line ending with a hyphen.
3650
3651\stopoldprimitive
3652
3653\startoldprimitive[title={\prm {firstmark}}][obsolete=yes]
3654
3655This is a reference to the first mark on the (split off) page, it gives back
3656tokens.
3657
3658\stopoldprimitive
3659
3660\startoldprimitive[title={\prm {firstmarks}}]
3661
3662This is a reference to the first mark with the given id (a number) on the (split
3663off) page, it gives back tokens.
3664
3665\stopoldprimitive
3666
3667\startnewprimitive[title={\prm {firstvalidlanguage}}]
3668
3669Language ids start at zero, which makes it the first valid language. You can set
3670this parameter to indicate the first language id that is actually a language. The
3671current value is \the \firstvalidlanguage, so lower values will not trigger
3672hyphenation.
3673
3674\stopnewprimitive
3675
3676\startnewprimitive[title={\prm {float}}]
3677
3678In addition to integers and dimensions, which are fixed 16.16 integer floats we
3679also have \quote {native} floats, based on 32 bit posit unums.
3680
3681\startbuffer
3682\float0 = 123.456 \the\float0
3683\float2 = 123.456 \the\float0
3684\advance \float0 by 123.456 \the\float0
3685\advance \float0 by \float2 \the\float0
3686\divideby\float0 3 \the\float0
3687\stopbuffer
3688
3689\typebuffer
3690
3691They come with the same kind of support as the other numeric data types:
3692
3693\startlines \getbuffer \stoplines
3694
3695\startbuffer
3696\dimen00 = 123.456pt \the\dimen0
3697\dimen02 = 123.456pt \the\dimen0
3698\advance \dimen0 by 123.456pt \the\dimen0
3699\advance \dimen0 by \dimen2 \the\dimen0
3700\divideby\dimen0 3 \the\dimen0
3701\stopbuffer
3702
3703We leave the subtle differences between floats and dimensions to the user to
3704investigate:
3705
3706\typebuffer
3707
3708The nature of posits is that they are more accurate around zero (or smaller
3709numbers in general).
3710
3711\startlines \getbuffer \stoplines
3712
3713This also works:
3714
3715\startbuffer
3716\float0=123.456e4
3717\float2=123.456 \multiply\float2 by 10000
3718\the\float0
3719\the\float2
3720\stopbuffer
3721
3722\typebuffer
3723
3724The values are (as expected) the same:
3725
3726\startlines \getbuffer \stoplines
3727
3728\stopnewprimitive
3729
3730\startnewprimitive[title={\prm {floatdef}}]
3731
3732This primitive defines a symbolic (macro) alias to a float register, just like
3733\prm {countdef} and friends do.
3734
3735\stopnewprimitive
3736
3737\startnewprimitive[title={\prm {floatexpr}}]
3738
3739This is the companion of \prm {numexpr}, \prm {dimexpr} etc.
3740
3741\startbuffer
3742\scratchcounter 200
3743\the \floatexpr 123.456456.123 \relax
3744\the \floatexpr 1.2*\scratchcounter \relax
3745\the \floatexpr \scratchcounter3 \relax
3746\number\floatexpr \scratchcounter3 \relax
3747\stopbuffer
3748
3749\typebuffer
3750
3751Watch the difference between \prm {the} and \prm {number}:
3752
3753\startlines \getbuffer \stoplines
3754
3755\stopnewprimitive
3756
3757\startoldprimitive[title={\prm {floatingpenalty}}]
3758
3759When an insertion is split (across pages) this one is added to to accumulated
3760\prm {insertpenalties}. In \LUAMETATEX\ this penalty can be stored per insertion
3761class.
3762
3763\stopoldprimitive
3764
3765\startnewprimitive[title={\prm {flushmarks}}]
3766
3767This primitive is an addition to the multiple marks mechanism that originates in
3768\ETEX\ and inserts a reset signal for the mark given category that will perform a
3769clear operation (like \prm {clearmarks} which operates immediately).
3770
3771\stopnewprimitive
3772
3773\startoldprimitive[title={\prm {font}}]
3774
3775This primitive is either a symbolic reference to the current font or in the
3776perspective of an assignment is used to trigger a font definitions with a given
3777name (\type {cs}) and specification. In \LUAMETATEX\ the assignment will trigger
3778a callback that then handles the definition; in addition to the filename an
3779optional size specifier is checked (\type {at} or \type {scaled}).
3780
3781In \LUAMETATEX\ {\em all} font loading is delegated to \LUA, and there is no
3782loading code built in the engine. Also, instead of \prm {font} in \CONTEXT\ one
3783uses dedicated and more advanced font definition commands.
3784
3785\stopoldprimitive
3786
3787\startnewprimitive[title={\prm {fontcharba}}]
3788
3789Fetches the bottom anchor of a character in the given font, so:
3790
3791\startbuffer
3792\the\fontcharba\textfont0 "222B
3793\stopbuffer
3794
3795results in: \inlinebuffer. However, this anchor is only available when it is set
3796and it is not part of \OPENTYPE; it is something that \CONTEXT\ provides for math
3797fonts.
3798
3799\stopnewprimitive
3800
3801\startoldprimitive[title={\prm {fontchardp}}]
3802
3803Fetches the depth of a character in the given font, so:
3804
3805\startbuffer
3806\the\fontchardp\fontg
3807\stopbuffer
3808
3809results in: \inlinebuffer.
3810
3811\stopoldprimitive
3812
3813\startoldprimitive[title={\prm {fontcharht}}]
3814
3815Fetches the width of a character in the given font, so:
3816
3817\startbuffer
3818\the\fontcharht\fontg
3819\stopbuffer
3820
3821results in: \inlinebuffer.
3822
3823\stopoldprimitive
3824
3825\startoldprimitive[title={\prm {fontcharic}}]
3826
3827Fetches the italic correction of a character in the given font, but because it is
3828not an \OPENTYPE\ property it is unlikely to return something useful. Although
3829math fonts have such a property in \CONTEXT\ we deal with it differently.
3830
3831\stopoldprimitive
3832
3833\startnewprimitive[title={\prm {fontcharta}}]
3834
3835Fetches the top anchor of a character in the given font, so:
3836
3837\startbuffer
3838\the\fontcharba\textfont0 "222B
3839\stopbuffer
3840
3841results in: \inlinebuffer. This is a specific property of math characters because
3842in text mark anchoring is driven by a feature.
3843
3844\stopnewprimitive
3845
3846\startoldprimitive[title={\prm {fontcharwd}}]
3847
3848Fetches the width of a character in the given font, so:
3849
3850\startbuffer
3851\the\fontcharwd\fontg
3852\stopbuffer
3853
3854results in: \inlinebuffer.
3855
3856\stopoldprimitive
3857
3858\startoldprimitive[title={\prm {fontdimen}}]
3859
3860A traditional \TEX\ font has a couple of font specific dimensions, we only
3861mention the seven that come with text fonts:
3862
3863\startitemize[n,packed]
3864\startitem
3865 The slant (slope) is an indication that we have an italic shape. The value
3866 divided by 65.536 is a fraction that can be compared with for instance the
3867 \type {slanted} operator in \METAPOST. It is used for positioning accents, so
3868 actually not limited to oblique fonts (just like italic correction can be a
3869 property of any character). It is not relevant in the perspective of
3870 \OPENTYPE\ fonts where we have glyph specific top and bottom anchors.
3871\stopitem
3872\startitem
3873 Unless is it overloaded by \prm {spaceskip} this determines the space between
3874 words (or actually anything separated by a space).
3875\stopitem
3876\startitem
3877 This is the stretch component of \prm {fontdimen}2(space).
3878\startitem
3879 This is the shrink component of \prm {fontdimen}2(space).
3880\stopitem
3881\startitem
3882 The so called exheight is normally the height of the \quote {x} and is
3883 also accessible as \type {em} unit.
3884\stopitem
3885\startitem
3886 The so called emwidth or in \TEX\ speak quad width is about the with of an
3887 \quote {M} but in many fonts just matches the font size. It is also
3888 accessible as \type {em} unit.
3889\stopitem
3890\startitem
3891 This is a very \TEX\ specific property also known as extra space. It gets
3892 {\em added} to the regular space after punctuation when \prm {spacefactor} is
3893 2000 or more. It can be overloaded by \prm {xspaceskip}.
3894\stopitem
3895\stopitemize
3896
3897This primitive expects a a number and a font identifier. Setting a font dimension
3898is a global operation as it directly pushes the value in the font resource.
3899
3900\stopoldprimitive
3901
3902\startnewprimitive[title={\prm {fontid}}]
3903
3904Returns the (internal) number associated with the given font:
3905
3906\startbuffer
3907{\bf \xdef\MyFontA{\the\fontid\font}}
3908{\sl \xdef\MyFontB{\setfontid\the\fontid\font}}
3909\stopbuffer
3910
3911\typebuffer \getbuffer
3912
3913with:
3914
3915\startbuffer
3916test {\setfontid\MyFontA test} test {\MyFontB test} test
3917\stopbuffer
3918
3919\typebuffer
3920
3921gives: \inlinebuffer.
3922
3923\stopnewprimitive
3924
3925
3926
3927
3928\startoldprimitive[title={\prm {fontname}}]
3929
3930Depending on how the font subsystem is implemented this gives some information
3931about the used font:
3932
3933\startbuffer
3934{\tf \fontname\font}
3935{\bf \fontname\font}
3936{\sl \fontname\font}
3937\stopbuffer
3938
3939\typebuffer
3940
3941\startlines
3942\getbuffer
3943\stoplines
3944
3945\stopoldprimitive
3946
3947\startnewprimitive[title={\prm {fontspecdef}}]
3948
3949This primitive creates a reference to a specification that when triggered will
3950change multiple parameters in one go.
3951
3952\starttyping
3953\fontspecdef\MyFontSpec
3954 \fontid\font
3955 scale 1200
3956 xscale 1100
3957 yscale 800
3958 weight 200
3959 slant 500
3960\relax
3961\stoptyping
3962
3963is equivalent to:
3964
3965\starttyping
3966\fontspecdef\MyFontSpec
3967 \fontid\font
3968 all 1200 1100 800 200 500
3969\relax
3970\stoptyping
3971
3972while
3973
3974\starttyping
3975\fontspecdef\MyFontSpec
3976 \fontid\font
3977 all \glyphscale \glyphxscale \glyphyscale \glyphslant \glyphweight
3978\relax
3979\stoptyping
3980
3981is the same as
3982
3983\starttyping
3984\fontspecdef\MyFontSpec
3985 \fontid\font
3986\relax
3987\stoptyping
3988
3989The engine adapts itself to these glyph parameters but when you access certain
3990quantities you have to make sure that you use the scaled ones. The same is true
3991at the \LUA\ end. This is somewhat fundamental in the sense that when one uses
3992these sort of dynamic features one also need to keep an eye on code that uses
3993font specific dimensions.
3994
3995\stopnewprimitive
3996
3997\startnewprimitive[title={\prm {fontspecid}}]
3998
3999Internally a font reference is a number and this primitive returns the number of
4000the font bound to the specification.
4001
4002\stopnewprimitive
4003
4004\startnewprimitive[title={\prm {fontspecifiedname}}]
4005
4006Depending on how the font subsystem is implemented this gives some information
4007about the (original) definition of the used font:
4008
4009\startbuffer
4010{\tf \fontspecifiedname\font}
4011{\bf \fontspecifiedname\font}
4012{\sl \fontspecifiedname\font}
4013\stopbuffer
4014
4015\typebuffer
4016
4017\startlines
4018\getbuffer
4019\stoplines
4020
4021\stopnewprimitive
4022
4023\startnewprimitive[title={\prm {fontspecifiedsize}}]
4024
4025Depending on how the font subsystem is implemented this gives some information
4026about the (original) size of the used font:
4027
4028\startbuffer
4029{\tf \the\fontspecifiedsize\font : \the\glyphscale}
4030{\bfa \the\fontspecifiedsize\font : \the\glyphscale}
4031{\slx \the\fontspecifiedsize\font : \the\glyphscale}
4032\stopbuffer
4033
4034\typebuffer
4035
4036Depending on how the font system is setup, this is not the real value that is
4037used in the text because we can use for instance \prm {glyphscale}. So the next
4038lines depend on what font mode this document is typeset.
4039
4040\startlines
4041\getbuffer
4042\stoplines
4043
4044\stopnewprimitive
4045
4046\startnewprimitive[title={\prm {fontspecscale}}]
4047
4048This returns the scale factor of a fontspec where as usual 1000 means scaling
4049by1.
4050
4051\stopnewprimitive
4052
4053\startnewprimitive[title={\prm {fontspecslant}}]
4054
4055This returns the slant factor of a font specification, usually between zero and
40561000 with 1000 being maximum slant.
4057
4058\stopnewprimitive
4059
4060\startnewprimitive[title={\prm {fontspecweight}}]
4061
4062This returns the weight of the font specification. Reasonable values are between
4063zero and 500.
4064
4065\stopnewprimitive
4066
4067\startnewprimitive[title={\prm {fontspecxscale}}]
4068
4069This returns the scale factor of a font specification where as usual 1000 means
4070scaling by1.
4071
4072\stopnewprimitive
4073
4074\startnewprimitive[title={\prm {fontspecyscale}}]
4075
4076This returns the scale factor of a font specification where as usual 1000 means
4077scaling by1.
4078
4079\stopnewprimitive
4080
4081\startnewprimitive[title={\prm {fonttextcontrol}}]
4082
4083This returns the text control flags that are set on the given font, here {\tttf
40840x\tohexadecimal \fonttextcontrol \font}. Bits that can be set are:
4085
4086\getbuffer[engine:syntax:textcontrolcodes]
4087
4088\stopnewprimitive
4089
4090\startnewprimitive[title={\prm {forcedleftcorrection}}]
4091
4092This is a callback driven left correction signal similar to italic corrections.
4093
4094\stopnewprimitive
4095
4096\startnewprimitive[title={\prm {forcedrightcorrection}}]
4097
4098This is a callback driven right correction signal similar to italic corrections.
4099
4100\stopnewprimitive
4101
4102\startnewprimitive[title={\prm {formatname}}]
4103
4104It is in the name: {\tttf \filenameonly {\formatname}}, but we cheat here by only
4105showing the filename and not the full path, which in a \CONTEXT\ setup can span
4106more than a line in this paragraph.
4107
4108\stopnewprimitive
4109
4110\startnewprimitive[title={\prm {frozen}}]
4111
4112You can define a macro as being frozen:
4113
4114\starttyping
4115\frozen\def\MyMacro{...}
4116\stoptyping
4117
4118When you redefine this macro you get an error:
4119
4120\starttyping
4121! You cant redefine a frozen macro.
4122\stoptyping
4123
4124This is a prefix like \prm {global} and it can be combined with other prefixes.
4125\footnote {The \prm {outer} and \prm {long} prefixes are noops in
4126\LUAMETATEX\ and \LUATEX\ can be configured to ignore them.}
4127
4128\stopnewprimitive
4129
4130\startnewprimitive[title={\prm {futurecsname}}]
4131
4132In order to make the repertoire of \type {def}, \type {let} and \type {futurelet}
4133primitives complete we also have:
4134
4135\starttyping
4136\futurecsname MyMacro:1\endcsname\MyAction
4137\stoptyping
4138
4139\stopnewprimitive
4140
4141\startnewprimitive[title={\prm {futuredef}}]
4142
4143We elaborate on the example of using \prm {futurelet} in the previous section.
4144Compare that one with the next:
4145
4146\startbuffer
4147\def\MySpecialToken{[}
4148\def\DoWhatever{\ifx\NextToken\MySpecialToken YES\else NOP\fi : }
4149\futurelet\NextToken\DoWhatever [A]\crlf
4150\futurelet\NextToken\DoWhatever (A)\par
4151\stopbuffer
4152
4153\typebuffer
4154
4155This time we get:
4156
4157{\getbuffer}
4158
4159It is for that reason that we now also have \prm {futuredef}:
4160
4161\startbuffer
4162\def\MySpecialToken{[}
4163\def\DoWhatever{\ifx\NextToken\MySpecialToken YES\else NOP\fi : }
4164\futuredef\NextToken\DoWhatever [A]\crlf
4165\futuredef\NextToken\DoWhatever (A)\par
4166\stopbuffer
4167
4168\typebuffer
4169
4170So were back to what we want:
4171
4172{\getbuffer}
4173
4174\stopnewprimitive
4175
4176\startnewprimitive[title={\prm {futureexpand}}]
4177
4178This primitive can be used as an alternative to a \prm {futurelet} approach,
4179which is where the name comes from. \footnote {In the engine primitives
4180that have similar behavior are grouped in commands that are then dealt with
4181together, code wise.}
4182
4183\startbuffer
4184\def\variantone<#1>{(#1)}
4185\def\varianttwo#1{[#1]}
4186\futureexpand<\variantone\varianttwo<one>
4187\futureexpand<\variantone\varianttwo{two}
4188\stopbuffer
4189
4190\typebuffer
4191
4192So, the next token determines which of the two variants is taken:
4193
4194{\getbuffer}
4195
4196Because we look ahead there is some magic involved: spaces are ignored but when
4197we have no match they are pushed back into the input. The next variant
4198demonstrates this:
4199
4200\startbuffer
4201\def\variantone<#1>{(#1)}
4202\def\varianttwo{}
4203\def\temp{\futureexpand<\variantone\varianttwo}
4204[\temp <one>]
4205[\temp {two}]
4206[\expandafter\temp\space <one>]
4207[\expandafter\temp\space {two}]
4208\stopbuffer
4209
4210\typebuffer
4211
4212This gives us:
4213
4214{\getbuffer}
4215
4216\stopnewprimitive
4217
4218\startnewprimitive[title={\prm {futureexpandis}}]
4219
4220We assume that the previous section is read. This variant will not push back
4221spaces, which permits a consistent approach i.e.\ the user can assume that macro
4222always gobbles the spaces.
4223
4224\startbuffer
4225\def\variantone<#1>{(#1)}
4226\def\varianttwo{}
4227\def\temp{\futureexpandis<\variantone\varianttwo}
4228[\temp <one>]
4229[\temp {two}]
4230[\expandafter\temp\space <one>]
4231[\expandafter\temp\space {two}]
4232\stopbuffer
4233
4234\typebuffer
4235
4236So, here no spaces are pushed back. This \type {is} in the name of this primitive
4237means \quote {ignore spaces}, but having that added to the name would have made
4238the primitive even more verbose (after all, we also dont have \type
4239{\expandeddef} but \prm {edef} and no \type {\globalexpandeddef} but \prm
4240{xdef}.
4241
4242{\getbuffer}
4243
4244\stopnewprimitive
4245
4246\startnewprimitive[title={\prm {futureexpandisap}}]
4247
4248This primitive is like the one in the previous section but also ignores par
4249tokens, so \type {isap} means \quote {ignore spaces and paragraphs}.
4250
4251\stopnewprimitive
4252
4253\startoldprimitive[title={\prm {futurelet}}]
4254
4255The original \TEX\ primitive \prm {futurelet} can be used to create an alias to a next token,
4256push it back into the input and then expand a given token.
4257
4258\startbuffer
4259\let\MySpecialTokenL[
4260\let\MySpecialTokenR]
4261\def\DoWhatever{\ifx\NextToken\MySpecialTokenL YES\else NOP\fi : }
4262\futurelet\NextToken\DoWhatever [A]\crlf
4263\futurelet\NextToken\DoWhatever (A)\par
4264\stopbuffer
4265
4266\typebuffer
4267
4268This is typically the kind of primitive that most users will never use because it
4269expects a sane follow up handler (here \type {\DoWhatever}) and therefore is
4270related to user interfacing.
4271
4272{\getbuffer}
4273
4274\stopoldprimitive
4275
4276\startoldprimitive[title={\prm {gdef}}]
4277
4278The is the global companion of \prm {def}.
4279
4280\stopoldprimitive
4281
4282\startnewprimitive[title={\prm {gdefcsname}}]
4283
4284As with standard \TEX\ we also define global ones:
4285
4286\starttyping
4287\expandafter\gdef\csname MyMacro:1\endcsname{...}
4288 \gdefcsname MyMacro:1\endcsname{...}
4289\stoptyping
4290
4291\stopnewprimitive
4292
4293
4294
4295
4296\startnewprimitive[title={\prm {gleaders}}]
4297
4298Leaders are glue with special property: a box, rule of (in \LUAMETATEX) glyph, like:
4299
4300\startlines
4301x\leaders \glyph M \hfill x
4302xx\leaders \glyph M \hfill xx
4303
4304x\cleaders \glyph M \hfill x
4305xx\cleaders \glyph M \hfill xx
4306
4307x\xleaders \glyph M \hfill x
4308xx\xleaders \glyph M \hfill xx
4309
4310x\gleaders \glyph M \hfill x
4311xx\gleaders \glyph M \hfill xx
4312\stoplines
4313
4314Leaders fill the available space. The \prm {leaders} command starts at the left
4315edge and stops when there is no more space. The blobs get centered when we use
4316\prm {cleaders}: excess space is distributed before and after a blob while \prm
4317{xleaders} also puts space between the blobs.
4318
4319When a rule is given the advance (width or height and depth) is ignored, so these
4320are equivalent.
4321
4322\starttyping
4323x\leaders \hrule \hfill x
4324x\leaders \hrule width 1cm \hfill x
4325\stoptyping
4326
4327When a box is used one will normally have some alignment in that box.
4328
4329\starttyping
4330x\leaders \hbox {\hss.\hss} \hfill x
4331x\leaders \hbox {\hss.\hss} \hskip 6cm \relax x
4332\stoptyping
4333
4334The reference point is the left edge of the current (outer) box and the effective
4335glue (when it has stretch or shrink) depends on that box. The \prm {gleaders}
4336variant takes the page as reference. That makes it possible to \quote {align}
4337across boxes.
4338
4339\stopnewprimitive
4340
4341\startnewprimitive[title={\prm {glet}}]
4342
4343This is the global companion of \prm {let}. The fact that it is not an original
4344primitive is probably due to the expectation for it not it not being used (as)
4345often (as in \CONTEXT).
4346
4347\stopnewprimitive
4348
4349\startnewprimitive[title={\prm {gletcsname}}]
4350
4351Naturally \LUAMETATEX\ also provides a global variant:
4352
4353\starttyping
4354\expandafter\global\expandafter\let\csname MyMacro:1\endcsname\relax
4355\expandafter \glet\csname MyMacro:1\endcsname\relax
4356 \gletcsname MyMacro:1\endcsname\relax
4357\stoptyping
4358
4359So, here we save even more.
4360
4361\stopnewprimitive
4362
4363\startnewprimitive[title={\prm {glettonothing}}]
4364
4365This is the global companion of \prm {lettonothing}.
4366
4367\stopnewprimitive
4368
4369\startoldprimitive[title={\prm {global}}]
4370
4371This is one of the original prefixes that can be used when we define a macro of
4372change some register.
4373
4374\starttyping
4375\bgroup
4376 \def\MyMacroA{a}
4377\global\def\MyMacroB{a}
4378 \gdef\MyMacroC{a}
4379\egroup
4380\stoptyping
4381
4382The macro defined in the first line is forgotten when the groups is left. The
4383second and third definition are both global and these definitions are retained.
4384
4385\stopoldprimitive
4386
4387\startoldprimitive[title={\prm {globaldefs}}]
4388
4389When set to a positive value, this internal integer will force all definitions to
4390be global, and in a complex macro package that is not something a user will do
4391unless it is very controlled.
4392
4393\stopoldprimitive
4394
4395\startoldprimitive[title={\prm {glueexpr}}]
4396
4397This is a more extensive variant of \prm {dimexpr} that also handles the optional
4398stretch and shrink components.
4399
4400\stopoldprimitive
4401
4402\startoldprimitive[title={\prm {glueshrink}}]
4403
4404This returns the shrink component of a glue quantity. The result is a dimension
4405so you need to apply \prm {the} when applicable.
4406
4407\stopoldprimitive
4408
4409\startoldprimitive[title={\prm {glueshrinkorder}}]
4410
4411This returns the shrink order of a glue quantity. The result is a integer so you
4412need to apply \prm {the} when applicable.
4413
4414\stopoldprimitive
4415
4416\startnewprimitive[title={\prm {gluespecdef}}]
4417
4418A variant of \prm {integerdef} and \prm {dimensiondef} is:
4419
4420\starttyping
4421\gluespecdef\MyGlue = 3pt plus 2pt minus 1pt
4422\stoptyping
4423
4424The properties are comparable to the ones described in the previous sections.
4425
4426\stopnewprimitive
4427
4428\startoldprimitive[title={\prm {gluestretch}}]
4429
4430This returns the stretch component of a glue quantity. The result is a dimension
4431so you need to apply \prm {the} when applicable.
4432
4433\stopoldprimitive
4434
4435\startoldprimitive[title={\prm {gluestretchorder}}]
4436
4437This returns the stretch order of a glue quantity. The result is a integer so you
4438need to apply \prm {the} when applicable.
4439
4440\stopoldprimitive
4441
4442\startoldprimitive[title={\prm {gluetomu}}]
4443
4444The sequence \typ {\the \gluetomu 20pt plus 10pt minus 5pt} gives \the \gluetomu
444520pt plus 10pt minus 5pt.
4446
4447\stopoldprimitive
4448
4449\startnewprimitive[title={\prm {glyph}}]
4450
4451This is a more extensive variant of \prm {char} that permits setting some
4452properties if the injected character node.
4453
4454\startbuffer
4455\ruledhbox{\glyph
4456 scale 2000 xscale 9000 yscale 1200
4457 slant 700 weight 200
4458 xoffset 10pt yoffset 5pt left 10pt right 20pt
4459 123}
4460\quad
4461\ruledhbox{\glyph
4462 scale 2000 xscale 9000 yscale 1200
4463 slant 700 weight 200
4464 125}
4465\stopbuffer
4466
4467\typebuffer
4468
4469In addition one can specify \type {font} (symbol), \type {id} (valid font id
4470number), an \type {options} (bit set) and \type {raise}.
4471
4472\startlinecorrection
4473\dontleavehmode\getbuffer
4474\stoplinecorrection
4475
4476When no parameters are set, the current ones are used. More details and examples
4477of usage can be found in the \CONTEXT\ distribution.
4478
4479\stopnewprimitive
4480
4481\startnewprimitive[title={\prm {glyphdatafield}}]
4482
4483The value of this parameter is assigned to data field in glyph nodes that get
4484injected. It has no meaning in itself but can be used at the \LUA\ end.
4485
4486\stopnewprimitive
4487
4488\startnewprimitive[title={\prm {glyphoptions}}]
4489
4490The value of this parameter is assigned to the options field in glyph nodes that
4491get injected.
4492
4493\startcolumns
4494\getbuffer[engine:syntax:glyphoptions]
4495\stopcolumns
4496
4497\stopnewprimitive
4498
4499\startnewprimitive[title={\prm {glyphscale}}]
4500
4501An integer parameter defining the current glyph scale, assigned to glyphs
4502(characters) inserted into the current list.
4503
4504\stopnewprimitive
4505
4506\startnewprimitive[title={\prm {glyphscriptfield}}]
4507
4508The value of this parameter is assigned to script field in glyph nodes that get
4509injected. It has no meaning in itself but can be used at the \LUA\ end.
4510
4511\stopnewprimitive
4512
4513\startnewprimitive[title={\prm {glyphscriptscale}}]
4514
4515This multiplier is applied to text font and glyph dimension properties when script
4516style is used.
4517
4518\stopnewprimitive
4519
4520\startnewprimitive[title={\prm {glyphscriptscriptscale}}]
4521
4522This multiplier is applied to text font and glyph dimension properties when
4523script script style is used.
4524
4525\stopnewprimitive
4526
4527\startnewprimitive[title={\prm {glyphslant}}]
4528
4529An integer parameter defining the current glyph slant, assigned to glyphs
4530(characters) inserted into the current list.
4531
4532\stopnewprimitive
4533
4534\startnewprimitive[title={\prm {glyphstatefield}}]
4535
4536The value of this parameter is assigned to script state in glyph nodes that get
4537injected. It has no meaning in itself but can be used at the \LUA\ end.
4538
4539\stopnewprimitive
4540
4541\startnewprimitive[title={\prm {glyphtextscale}}]
4542
4543This multiplier is applied to text font and glyph dimension properties when text
4544style is used.
4545
4546\stopnewprimitive
4547
4548\startnewprimitive[title={\prm {glyphweight}}]
4549
4550An integer parameter defining the current glyph weight, assigned to glyphs
4551(characters) inserted into the current list.
4552
4553\stopnewprimitive
4554
4555\startnewprimitive[title={\prm {glyphxoffset}}]
4556
4557An integer parameter defining the current glyph x offset, assigned to glyphs
4558(characters) inserted into the current list. Normally this will only be set when
4559one explicitly works with glyphs and defines a specific sequence.
4560
4561\stopnewprimitive
4562
4563\startnewprimitive[title={\prm {glyphxscale}}]
4564
4565An integer parameter defining the current glyph x scale, assigned to glyphs
4566(characters) inserted into the current list.
4567
4568\stopnewprimitive
4569
4570\startnewprimitive[title={\prm {glyphxscaled}}]
4571
4572This primitive returns the given dimension scaled by the \prm {glyphscale} and
4573\prm {glyphxscale}.
4574
4575\stopnewprimitive
4576
4577\startnewprimitive[title={\prm {glyphyoffset}}]
4578
4579An integer parameter defining the current glyph x offset, assigned to glyphs
4580(characters) inserted into the current list. Normally this will only be set when
4581one explicitly works with glyphs and defines a specific sequence.
4582
4583\stopnewprimitive
4584
4585\startnewprimitive[title={\prm {glyphyscale}}]
4586
4587An integer parameter defining the current glyph y scale, assigned to glyphs
4588(characters) inserted into the current list.
4589
4590\stopnewprimitive
4591
4592\startnewprimitive[title={\prm {glyphyscaled}}]
4593
4594This primitive returns the given dimension scaled by the \prm {glyphscale} and
4595\prm {glyphyscale}.
4596
4597\stopnewprimitive
4598
4599\startnewprimitive[title={\prm {gtoksapp}}]
4600
4601This is the global variant of \prm {toksapp}.
4602
4603\stopnewprimitive
4604
4605\startnewprimitive[title={\prm {gtokspre}}]
4606
4607This is the global variant of \prm {tokspre}.
4608
4609\stopnewprimitive
4610
4611\startoldprimitive[title={\prm {halign}}]
4612
4613This command starts horizontally aligned material. Macro packages use this
4614command in table mechanisms and math alignments. It starts with a preamble
4615followed by entries (rows and columns).
4616
4617\stopoldprimitive
4618
4619\startoldprimitive[title={\prm {hangafter}}]
4620
4621This parameter tells the par builder when indentation specified with \prm
4622{hangindent} starts. A negative value does the opposite and starts indenting
4623immediately. So, a value of $2$ will make the first two lines indent.
4624
4625\startoldprimitive[title={\prm {hangindent}}]
4626
4627This parameter relates to \prm {hangafter} and sets the amount of indentation.
4628When larger than zero indentation happens left, otherwise it starts at the right
4629edge.
4630
4631\stopoldprimitive
4632
4633\stopoldprimitive
4634
4635\startoldprimitive[title={\prm {hbadness}}]
4636
4637This sets the threshold for reporting a horizontal badness value, its current
4638value is \the \badness.
4639
4640\stopoldprimitive
4641
4642\startoldprimitive[title={\prm {hbox}}]
4643
4644This constructs a horizontal box. There are a lot of optional parameters so more
4645details can be found in dedicated manuals. When the content is packed a callback
4646can kick in that can be used to apply for instance font features.
4647
4648\stopoldprimitive
4649
4650\startnewprimitive[title={\prm {hccode}}]
4651
4652The \TEX\ engine is good at hyphenating but traditionally that has been limited
4653to hyphens. Some languages however use different characters. You can set up a
4654different \prm {hyphenchar} as well as pre and post characters, but theres also
4655a dedicated code for controlling this.
4656
4657\startbuffer
4658\hccode"2013 "2013
4659
4660\hsize 50mm test\char"2013test\par
4661\hsize 1mm test\char"2013test\par
4662
4663\hccode"2013 !
4664
4665\hsize 50mm test\char"2013test\par
4666\hsize 1mm test\char"2013test\par
4667\stopbuffer
4668
4669\typebuffer
4670
4671This example shows that we can mark a character as hyphenlike but also can
4672remap it to something else:
4673
4674\startpacked \getbuffer \stoppacked
4675
4676\stopnewprimitive
4677
4678\startoldprimitive[title={\prm {hfil}}]
4679
4680This is a shortcut for \typ {\hskip plus 1 fil} (first order filler).
4681
4682\stopoldprimitive
4683
4684\startoldprimitive[title={\prm {hfill}}]
4685
4686This is a shortcut for \typ {\hskip plus 1 fill} (second order filler).
4687
4688\stopoldprimitive
4689
4690\startoldprimitive[title={\prm {hfilneg}}]
4691
4692This is a shortcut for \typ {\hskip plus 1 fil} so it can compensate \prm
4693{hfil}.
4694
4695\stopoldprimitive
4696
4697\startoldprimitive[title={\prm {hfuzz}}]
4698
4699This dimension sets the threshold for reporting horizontal boxes that are under
4700or overfull. The current value is \the \hfuzz.
4701
4702\stopoldprimitive
4703
4704\startnewprimitive[title={\prm {hjcode}}]
4705
4706The so called lowercase code determines if a character is part of a
4707tobehyphenated word. In \LUATEX\ we introduced the \quote {hyphenation
4708justification} code as replacement. When a language is saved and no \prm {hjcode}
4709is set the \prm {lccode} is used instead. This code serves a second purpose. When
4710the assigned value is greater than 0 but less than 32 it indicated the to be used
4711length when checking for left and righthyphenmin. For instance it make sense to
4712set the code to2 for characters like œ.
4713
4714\stopnewprimitive
4715
4716\startoldprimitive[title={\prm {hkern}}]
4717
4718This primitive is like \prm {kern} but will force the engine into horizontal mode
4719if it isnt yet.
4720
4721\stopoldprimitive
4722
4723\startnewprimitive[title={\prm {hmcode}}]
4724
4725The \type {hm} stands for \quote {hyphenation math}. When bit1 is set the
4726characters will be repeated on the next line after a break. The second bit
4727concerns italic correction but is of little relevance now that we moved to a
4728different model in \CONTEXT. Here are some examples, we also show an example of
4729\prm {mathdiscretionary} because that is what this code triggers:
4730
4731\startbuffer
4732test $ \dorecurse {50} {
4733 a \discretionary class 2 {$\darkred $}{$\darkgreen $}{$\darkblue $}
4734} b$
4735
4736test $ a \mathdiscretionary class 1 {}{}{} b$
4737
4738\bgroup
4739 \hmcode"002B=1
4740 \hmcode"002D=1
4741 \hmcode"2212=1
4742 test $ \dorecurse{50}{a b } c$
4743\egroup
4744\stopbuffer
4745
4746\typebuffer
4747
4748{\setuptolerance[verytolerant,stretch]\getbuffer}
4749
4750\stopnewprimitive
4751
4752\startoldprimitive[title={\prm {holdinginserts}}]
4753
4754When set to a positive value inserts will be kept in the stream and not moved to
4755the insert registers.
4756
4757\stopoldprimitive
4758
4759\startnewprimitive[title={\prm {holdingmigrations}}]
4760
4761When set to a positive value marks (and adjusts) will be kept in the stream and
4762not moved to the outer level or related registers.
4763
4764\stopnewprimitive
4765
4766\startnewprimitive[title={\prm {hpack}}]
4767
4768This primitive is like \prm {hbox} but without the callback overhead.
4769
4770\stopnewprimitive
4771
4772\startnewprimitive[title={\prm {hpenalty}}]
4773
4774This primitive is like \prm {penalty} but will force the engine into horizontal
4775mode if it isnt yet.
4776
4777\stopnewprimitive
4778
4779\startoldprimitive[title={\prm {hrule}}]
4780
4781This creates a horizontal rule. Unless the width is set it will stretch to fix
4782the available width. In addition to the traditional \type {width}, \type {height}
4783and \type {depth} specifiers some more are accepted. These are discussed in other
4784manuals. To give an idea:
4785
4786\startbuffer
4787h\hrule width 10mm height 2mm depth 1mm \relax rule
4788h\hrule width 10mm height 2mm depth 1mm xoffset 30mm yoffset 10mm \relax rule
4789v\vrule width 10mm height 2mm depth 1mm \relax rule
4790v\vrule width 10mm height 2mm depth 1mm xoffset 30mm yoffset 10mm \relax rule
4791\stopbuffer
4792
4793\typebuffer
4794
4795The \prm {relax} stops scanning and because we have more keywords we get a
4796different error report than in traditional \TEX\ when a lookahead confuses the
4797engine. On separate lines we get the following.
4798
4799\startlines
4800\getbuffer
4801\stoplines
4802
4803\stopoldprimitive
4804
4805\startoldprimitive[title={\prm {hsize}}]
4806
4807This sets (or gets) the current horizontal size.
4808
4809\startbuffer
4810\hsize 40pt \setbox0\vbox{x} hsize: \the\wd0
4811\setbox0\vbox{\hsize 40pt x} hsize: \the\wd0
4812\stopbuffer
4813
4814\typebuffer
4815
4816In both cases we get the same size reported but the first one will also influence
4817the current paragraph when used ungrouped.
4818
4819\startlines
4820\getbuffer
4821\stoplines
4822
4823\stopoldprimitive
4824
4825\startoldprimitive[title={\prm {hskip}}]
4826
4827The given glue is injected in the horizontal list. If possible horizontal mode is
4828entered.
4829
4830\stopoldprimitive
4831
4832\startoldprimitive[title={\prm {hss}}]
4833
4834\startbuffer
4835x\hbox to 0pt{\hskip 0pt plus 1 fil minus 1 fil\relax test}x
4836x\hbox to 0pt{\hss test}x
4837x\hbox to 0pt{test\hskip 0pt plus 1 fil minus 1 fil\relax}x
4838x\hbox to 0pt{test\hss}x
4839\stopbuffer
4840
4841In traditional \TEX\ glue specifiers are shared. This makes a lot of sense when
4842memory has to be saved. For instance spaces in a paragraph of text are often the
4843same and a glue specification has at least an amount, stretch, shrink, stretch
4844order and shrink order field plus a leader pointer; in \LUAMETATEX\ we have even
4845more fields. In \LUATEX\ these shared (and therefore referenced) glue spec nodes
4846became just copies.
4847
4848\typebuffer
4849
4850The \prm {hss} primitives injects a glue node with one order stretch and one
4851order shrink. In traditional \TEX\ this is a reference to a shared specification,
4852and in \LUATEX\ just a copy of a predefined specifier. The only gain is now in
4853tokens because one could just be explicit or use a glue register with that value
4854because we have plenty glue registers.
4855
4856\startlines
4857\getbuffer
4858\stoplines
4859
4860We could have this:
4861
4862\starttyping
4863\permanent\protected\untraced\def\hss
4864 {\hskip0pt plus 1 fil minus 1 fil\relax}
4865\stoptyping
4866
4867or this:
4868
4869\starttyping
4870\gluespecdef\hssglue 0pt plus 1 fil minus 1 fil
4871
4872\permanent\protected\untraced\def\hss
4873 {\hskip\hssglue}
4874\stoptyping
4875
4876but we just keep the originals around.
4877
4878\stopoldprimitive
4879
4880\startoldprimitive[title={\prm {ht}}]
4881
4882Returns the height of the given box.
4883
4884\stopoldprimitive
4885
4886\startoldprimitive[title={\prm {hyphenation}}]
4887
4888The list passed to this primitive contains hyphenation exceptions that get bound
4889to the current language. In \LUAMETATEX\ this can be managed at the \LUA\ end.
4890Exceptions are not stored in the format file.
4891
4892\stopoldprimitive
4893
4894\startnewprimitive[title={\prm {hyphenationmin}}]
4895
4896This property (that also gets bond to the current language) sets the minimum
4897length of a word that gets hyphenated.
4898
4899\stopnewprimitive
4900
4901
4902
4903
4904\startoldprimitive[title={\prm {hyphenchar}}]
4905
4906This is one of the font related primitives: it returns the number of the hyphen
4907set in the given font.
4908
4909\stopoldprimitive
4910
4911\startoldprimitive[title={\prm {hyphenpenalty}}]
4912
4913Discretionary nodes have a related default penalty. The \prm {hyphenpenalty} is
4914injected after a regular discretionary, and \prm {exhyphenpenalty} after \type
4915{\-} or \type {}. The later case is called an automatic discretionary. In
4916\LUAMETATEX\ we have two extra penalties: \prm {explicithyphenpenalty} and \prm
4917{automatichyphenpenalty} and these are used when the related bits are set in \prm
4918{hyphenationmode}.
4919
4920\stopoldprimitive
4921
4922\startoldprimitive[title={\prm {if}}]
4923
4924This traditional \TEX\ conditional checks if two character codes are the same. In
4925order to understand unexpanded results it is good to know that internally \TEX\
4926groups primitives in a way that serves the implementation. Each primitive has a
4927command code and a character code, but only for real characters the name
4928character code makes sense. This condition only really tests for character codes
4929when we have a character, in all other cases, the result is true.
4930
4931\startbuffer
4932\def\A{A}\def\B{B} \chardef\C=C \chardef\D=D \def\AA{AA}
4933
4934[\if AA YES \else NOP \fi] [\if AB YES \else NOP \fi]
4935[\if \A\B YES \else NOP \fi] [\if \A\A YES \else NOP \fi]
4936[\if \C\D YES \else NOP \fi] [\if \C\C YES \else NOP \fi]
4937[\if \count\dimen YES \else NOP \fi] [\if \AA\A YES \else NOP \fi]
4938
4939\stopbuffer
4940
4941\typebuffer
4942
4943The last example demonstrates that the tokens get expanded, which is why
4944we get the extra \type {A}:
4945
4946{\getbuffer}
4947
4948\stopoldprimitive
4949
4950\startnewprimitive[title={\prm {ifabsdim}}]
4951
4952This test will negate negative dimensions before comparison, as in:
4953
4954\startbuffer
4955\def\TestA#1{\ifdim #1<2pt too small\orelse\ifdim #1>4pt too large\else okay\fi}
4956\def\TestB#1{\ifabsdim#1<2pt too small\orelse\ifabsdim#1>4pt too large\else okay\fi}
4957
4958\TestA {1pt}\quad\TestA {3pt}\quad\TestA {5pt}\crlf
4959\TestB {1pt}\quad\TestB {3pt}\quad\TestB {5pt}\crlf
4960\TestB{1pt}\quad\TestB{3pt}\quad\TestB{5pt}\par
4961\stopbuffer
4962
4963\typebuffer
4964
4965So we get this:
4966
4967{\getbuffer}
4968
4969\stopnewprimitive
4970
4971\startnewprimitive[title={\prm {ifabsfloat}}]
4972
4973This test will negate negative floats before comparison, as in:
4974
4975\startbuffer
4976\def\TestA#1{\iffloat #1<2.46 small\orelse\iffloat #1>4.68 large\else medium\fi}
4977\def\TestB#1{\ifabsfloat#1<2.46 small\orelse\ifabsfloat#1>4.68 large\else medium\fi}
4978
4979\TestA {1.23}\quad\TestA {3.45}\quad\TestA {5.67}\crlf
4980\TestB {1.23}\quad\TestB {3.45}\quad\TestB {5.67}\crlf
4981\TestB{1.23}\quad\TestB{3.45}\quad\TestB{5.67}\par
4982\stopbuffer
4983
4984\typebuffer
4985
4986So we get this:
4987
4988{\getbuffer}
4989
4990\stopnewprimitive
4991
4992\startnewprimitive[title={\prm {ifabsnum}}]
4993
4994This test will negate negative numbers before comparison, as in:
4995
4996\startbuffer
4997\def\TestA#1{\ifnum #1<100 too small\orelse\ifnum #1>200 too large\else okay\fi}
4998\def\TestB#1{\ifabsnum#1<100 too small\orelse\ifabsnum#1>200 too large\else okay\fi}
4999
5000\TestA {10}\quad\TestA {150}\quad\TestA {210}\crlf
5001\TestB {10}\quad\TestB {150}\quad\TestB {210}\crlf
5002\TestB{10}\quad\TestB{150}\quad\TestB{210}\par
5003\stopbuffer
5004
5005\typebuffer
5006
5007Here we get the same result each time:
5008
5009{\getbuffer}
5010
5011\stopnewprimitive
5012
5013\startnewprimitive[title={\prm {ifarguments}}]
5014
5015This is a variant of \prm {ifcase} were the selector is the number of arguments
5016picked up. For example:
5017
5018\startbuffer
5019\def\MyMacro#1#2#3{\ifarguments\0\or1\or2\or3\else ?\fi} \MyMacro{A}{B}{C}
5020\def\MyMacro#1#0#3{\ifarguments\0\or1\or2\or3\else ?\fi} \MyMacro{A}{B}{C}
5021\def\MyMacro#1##2{\ifarguments\0\or1\or2\or3\else ?\fi} \MyMacro{A}{B}{C}\par
5022\stopbuffer
5023
5024\typebuffer
5025
5026Watch the non counted, ignored, argument in the last case. Normally this test will
5027be used in combination with \prm {ignorearguments}.
5028
5029{\getbuffer}
5030
5031\stopnewprimitive
5032
5033\startnewprimitive[title={\prm {ifboolean}}]
5034
5035This tests a number (register or equivalent) and any nonzero value represents
5036\type {true}, which is nicer than using an \type {\unless \ifcase}.
5037
5038\stopnewprimitive
5039
5040\startoldprimitive[title={\prm {ifcase}}]
5041
5042This numeric \TEX\ conditional takes a counter (literal, register, shortcut to a
5043character, internal quantity) and goes to the branch that matches.
5044
5045\startbuffer
5046\ifcase 3 zero\or one\or two\or three\or four\else five or more\fi
5047\stopbuffer
5048
5049\typebuffer
5050
5051Indeed: \inlinebuffer\ equals three. In later sections we will see some
5052\LUAMETATEX\ primitives that behave like an \prm {ifcase}.
5053
5054\stopoldprimitive
5055
5056\startoldprimitive[title={\prm {ifcat}}]
5057
5058Another traditional \TEX\ primitive: what happens with what gets read in depends
5059on the catcode of a character, think of characters marked to start math mode, or
5060alphabetic characters (letters) versus other characters (like punctuation).
5061
5062\startbuffer
5063\def\A{A}\def\B{,} \chardef\C=C \chardef\D=, \def\AA{AA}
5064
5065[\ifcat $! YES \else NOP \fi] [\ifcat () YES \else NOP \fi]
5066[\ifcat AA YES \else NOP \fi] [\ifcat AB YES \else NOP \fi]
5067[\ifcat \A\B YES \else NOP \fi] [\ifcat \A\A YES \else NOP \fi]
5068[\ifcat \C\D YES \else NOP \fi] [\ifcat \C\C YES \else NOP \fi]
5069[\ifcat \count\dimen YES \else NOP \fi] [\ifcat \AA\A YES \else NOP \fi]
5070\stopbuffer
5071
5072\typebuffer
5073
5074Close reading is needed here:
5075
5076{\getbuffer}
5077
5078This traditional \TEX\ condition as a well as the one in the previous section are
5079hardly used in \CONTEXT, if only because they expand what follows and we seldom
5080need to compare characters.
5081
5082\stopoldprimitive
5083
5084\startnewprimitive[title={\prm {ifchkdim}}]
5085
5086A variant on the checker in the previous section is a dimension checker:
5087
5088\startbuffer
5089\ifchkdim oeps \or okay\else error\fi\quad
5090\ifchkdim 12 \or okay\else error\fi\quad
5091\ifchkdim 12pt \or okay\else error\fi\quad
5092\ifchkdim 12pt or more\or okay\else error\fi
5093\stopbuffer
5094
5095\typebuffer
5096
5097We get:
5098
5099{\getbuffer}
5100
5101\stopnewprimitive
5102
5103\startnewprimitive[title={\prm {ifchkdimension}}]
5104
5105COntrary to \prm {ifchkdim} this test doesnt accept trailing crap:
5106
5107\startbuffer
5108\ifchkdimension oeps \or okay\else error\fi\quad
5109\ifchkdimension 12 \or okay\else error\fi\quad
5110\ifchkdimension 12pt \or okay\else error\fi\quad
5111\ifchkdimension 12pt or more\or okay\else error\fi
5112\stopbuffer
5113
5114\typebuffer
5115
5116reports:
5117
5118{\getbuffer}
5119
5120\stopnewprimitive
5121
5122\startnewprimitive[title={\prm {ifchknum}}]
5123
5124In \CONTEXT\ there are quite some cases where a variable can have a number or a
5125keyword indicating a symbolic name of a number or maybe even some special
5126treatment. Checking if a valid number is given is possible to some extend, but a
5127native checker makes much sense too. So here is one:
5128
5129\startbuffer
5130\ifchknum oeps \or okay\else error\fi\quad
5131\ifchknum 12 \or okay\else error\fi\quad
5132\ifchknum 12pt \or okay\else error\fi\quad
5133\ifchknum 12pt or more\or okay\else error\fi
5134\stopbuffer
5135
5136\typebuffer
5137
5138The result is as expected:
5139
5140{\getbuffer}
5141
5142\stopnewprimitive
5143
5144\startnewprimitive[title={\prm {ifchknumber}}]
5145
5146This check is more restrictive than \prm {ifchknum} discussed in the previous
5147section:
5148
5149\startbuffer
5150\ifchknumber oeps \or okay\else error\fi\quad
5151\ifchknumber 12 \or okay\else error\fi\quad
5152\ifchknumber 12pt \or okay\else error\fi\quad
5153\ifchknumber 12pt or more\or okay\else error\fi
5154\stopbuffer
5155
5156\typebuffer
5157
5158Here we get:
5159
5160{\getbuffer}
5161
5162\stopnewprimitive
5163
5164\startnewprimitive[title={\prm {ifcmpdim}}]
5165
5166This conditional compares two dimensions and the resulting \prm {ifcase}
5167reflects their relation:
5168
5169\startbuffer
5170[1pt 2pt : \ifcmpdim 1pt 2pt less\or equal\or more\fi]\quad
5171[1pt 1pt : \ifcmpdim 1pt 1pt less\or equal\or more\fi]\quad
5172[2pt 1pt : \ifcmpdim 2pt 1pt less\or equal\or more\fi]
5173\stopbuffer
5174
5175\typebuffer
5176
5177This gives:
5178
5179{\getbuffer}
5180
5181\stopnewprimitive
5182
5183\startnewprimitive[title={\prm {ifcmpnum}}]
5184
5185This conditional compares two numbers and the resulting \prm {ifcase} reflects
5186their relation:
5187
5188\startbuffer
5189[1 2 : \ifcmpnum 1 2 less\or equal\or more\fi]\quad
5190[1 1 : \ifcmpnum 1 1 less\or equal\or more\fi]\quad
5191[2 1 : \ifcmpnum 2 1 less\or equal\or more\fi]
5192\stopbuffer
5193
5194\typebuffer
5195
5196This gives:
5197
5198{\getbuffer}
5199
5200\stopnewprimitive
5201
5202\startnewprimitive[title={\prm {ifcondition}}]
5203
5204The conditionals in \TEX\ are hard coded as primitives and although it might
5205look like \type {\newif} creates one, it actually just defined three macros.
5206
5207\startbuffer
5208\newif\ifMyTest
5209\meaning\MyTesttrue \crlf
5210\meaning\MyTestfalse \crlf
5211\meaning\ifMyTest \crlf \MyTesttrue
5212\meaning\ifMyTest \par
5213\stopbuffer
5214
5215\typebuffer {\tttf \getbuffer}
5216
5217This means that when you say:
5218
5219\starttyping
5220\ifMytest ... \else ... \fi
5221\stoptyping
5222
5223You actually have one of:
5224
5225\starttyping
5226\iftrue ... \else ... \fi
5227\iffalse ... \else ... \fi
5228\stoptyping
5229
5230and because these are proper conditions nesting them like:
5231
5232\starttyping
5233\ifnum\scratchcounter > 0 \ifMyTest A\else B\fi \fi
5234\stoptyping
5235
5236will work out well too. This is not true for macros, so for instance:
5237
5238\starttyping
5239\scratchcounter = 1
5240\unexpanded\def\ifMyTest{\iftrue}
5241\ifnum\scratchcounter > 0 \ifMyTest A\else B\fi \fi
5242\stoptyping
5243
5244will make a run fail with an error (or simply loop forever, depending on your
5245code). This is where \prm {ifcondition} enters the picture:
5246
5247\starttyping
5248\def\MyTest{\iftrue} \scratchcounter0
5249\ifnum\scratchcounter > 0
5250 \ifcondition\MyTest A\else B\fi
5251\else
5252 x
5253\fi
5254\stoptyping
5255
5256This primitive is seen as a proper condition when \TEX\ is in \quotation {fast
5257skipping unused branches} mode but when it is expanding a branch, it checks if
5258the next expanded token is a proper tests and if so, it deals with that test,
5259otherwise it fails. The main condition here is that the \type {\MyTest} macro
5260expands to a proper true or false test, so, a definition like:
5261
5262\starttyping
5263\def\MyTest{\ifnum\scratchcounter<10 }
5264\stoptyping
5265
5266is also okay. Now, is that neat or not?
5267
5268\stopnewprimitive
5269
5270\startoldprimitive[title={\prm {ifcsname}}]
5271
5272This is an \ETEX\ conditional that complements the one on the previous section:
5273
5274\starttyping
5275\expandafter\ifx\csname MyMacro\endcsname\relax ... \else ... \fi
5276 \ifcsname MyMacro\endcsname ... \else ... \fi
5277\stoptyping
5278
5279Here the first one has the side effect of defining the macro and defaulting it to
5280\prm {relax}, while the second one doesnt do that. Juts think of checking a
5281few million different names: the first one will deplete the hash table and
5282probably string space too.
5283
5284In \LUAMETATEX\ the construction stops when there is no letter or other character
5285seen (\TEX\ expands on the go so expandable macros are dealt with). Instead of an
5286error message, the match is simply false and all tokens till the \prm
5287{endcsname} are gobbled.
5288
5289\stopoldprimitive
5290
5291\startnewprimitive[title={\prm {ifcstok}}]
5292
5293A variant on the primitive mentioned in the previous section is one that
5294operates on lists and macros:
5295
5296\startbuffer[a]
5297\def\a{a} \def\b{b} \def\c{a}
5298\stopbuffer
5299
5300\typebuffer[a]
5301
5302\startbuffer[b]
5303\ifcstok\a\b Y\else N\fi\space
5304\ifcstok\a\c Y\else N\fi\space
5305\ifcstok{\a}\c Y\else N\fi\space
5306\ifcstok{a}\c Y\else N\fi
5307\stopbuffer
5308
5309This:
5310
5311\typebuffer[b]
5312
5313{\getbuffer[a]will give us: \inlinebuffer[b].}
5314
5315\stopnewprimitive
5316
5317\startoldprimitive[title={\prm {ifdefined}}]
5318
5319In traditional \TEX\ checking for a macro to exist was a bit tricky and therefore
5320\ETEX\ introduced a convenient conditional. We can do this:
5321
5322\starttyping
5323\ifx\MyMacro\undefined ... \else ... \fi
5324\stoptyping
5325
5326but that assumes that \type {\undefined} is indeed undefined. Another test often
5327seen was this:
5328
5329\starttyping
5330\expandafter\ifx\csname MyMacro\endcsname\relax ... \else ... \fi
5331\stoptyping
5332
5333Instead of comparing with \type {\undefined} we need to check with \prm {relax}
5334because the control sequence is defined when not yet present and defaults to
5335\prm {relax}. This is not pretty.
5336
5337\stopoldprimitive
5338
5339\startoldprimitive[title={\prm {ifdim}}]
5340
5341Dimensions can be compared with this traditional \TEX\ primitive.
5342
5343\startbuffer
5344\scratchdimen=1pt \scratchcounter=65536
5345
5346\ifdim\scratchdimen=\scratchcounter sp YES \else NOP\fi
5347\ifdim\scratchdimen=1 pt YES \else NOP\fi
5348\stopbuffer
5349
5350\typebuffer
5351
5352The units are mandate:
5353
5354{\getbuffer}
5355
5356\stopoldprimitive
5357
5358\startnewprimitive[title={\prm {ifdimexpression}}]
5359
5360The companion of the previous primitive is:
5361
5362\startbuffer
5363\ifdimexpression 10pt > 10bp \relax
5364 dosomething
5365\fi
5366\stopbuffer
5367
5368This matches when the result is non zero, and you can mix calculations and tests
5369as with normal expressions. Contrary to the number variant units can be used and
5370precision kicks in.
5371
5372\stopnewprimitive
5373
5374\startnewprimitive[title={\prm {ifdimval}}]
5375
5376This conditional is a variant on \prm {ifchkdim} and provides some more
5377detailed information about the value:
5378
5379\startbuffer
5380[12pt : \ifdimval12pt\or negative\or zero\or positive\else error\fi]\quad
5381[0pt : \ifdimval 0pt\or negative\or zero\or positive\else error\fi]\quad
5382[12pt : \ifdimval 12pt\or negative\or zero\or positive\else error\fi]\quad
5383[oeps : \ifdimval oeps\or negative\or zero\or positive\else error\fi]
5384\stopbuffer
5385
5386\typebuffer
5387
5388This gives:
5389
5390{\getbuffer}
5391
5392\stopnewprimitive
5393
5394\startnewprimitive[title={\prm {ifempty}}]
5395
5396This conditional checks if a control sequence is empty:
5397
5398\starttyping
5399is \ifempty\MyMacro \else not \fi empty
5400\stoptyping
5401
5402It is basically a shortcut of:
5403
5404\starttyping
5405is \ifx\MyMacro\empty \else not \fi empty
5406\stoptyping
5407
5408with:
5409
5410\starttyping
5411\def\empty{}
5412\stoptyping
5413
5414Of course this is not empty at all:
5415
5416\starttyping
5417\def\notempty#1{}
5418\stoptyping
5419
5420\stopnewprimitive
5421
5422\startoldprimitive[title={\prm {iffalse}}]
5423
5424Here we have a traditional \TEX\ conditional that is always false (therefore the
5425same is true for any macro that is \prm {let} to this primitive).
5426
5427\stopoldprimitive
5428
5429\startnewprimitive[title={\prm {ifflags}}]
5430
5431This test primitive relates to the various flags that one can set on a control
5432sequence in the perspective of overload protection and classification.
5433
5434\startbuffer
5435\protected\untraced\tolerant\def\foo[#1]{...#1...}
5436\permanent\constant \def\oof{okay}
5437\stopbuffer
5438
5439\typebuffer
5440
5441\start \getbuffer
5442\starttabulate[lcclcc]
5443\FL
5444\NC flag \NC \type {\foo} \NC \type {\oof}
5445\NC flag \NC \type {\foo} \NC \type {\oof} \NC \NR
5446\ML
5447\NC frozen \NC \ifflags\foo\frozen Y\else N\fi \NC \ifflags\oof\frozen Y\else N\fi
5448\NC permanent \NC \ifflags\foo\permanent Y\else N\fi \NC \ifflags\oof\permanent Y\else N\fi \NC \NR
5449\NC immutable \NC \ifflags\foo\immutable Y\else N\fi \NC \ifflags\oof\immutable Y\else N\fi
5450\NC mutable \NC \ifflags\foo\mutable Y\else N\fi \NC \ifflags\oof\mutable Y\else N\fi \NC \NR
5451\NC noaligned \NC \ifflags\foo\noaligned Y\else N\fi \NC \ifflags\oof\noaligned Y\else N\fi
5452\NC instance \NC \ifflags\foo\instance Y\else N\fi \NC \ifflags\oof\instance Y\else N\fi \NC \NR
5453\NC untraced \NC \ifflags\foo\untraced Y\else N\fi \NC \ifflags\oof\untraced Y\else N\fi
5454\NC global \NC \ifflags\foo\global Y\else N\fi \NC \ifflags\oof\global Y\else N\fi \NC \NR
5455\NC tolerant \NC \ifflags\foo\tolerant Y\else N\fi \NC \ifflags\oof\tolerant Y\else N\fi
5456\NC constant \NC \ifflags\foo\constant Y\else N\fi \NC \ifflags\oof\constant Y\else N\fi \NC \NR
5457\NC protected \NC \ifflags\foo\protected Y\else N\fi \NC \ifflags\oof\protected Y\else N\fi
5458\NC semiprotected \NC \ifflags\foo\semiprotected Y\else N\fi \NC \ifflags\oof\semiprotected Y\else N\fi \NC \NR
5459\LL
5460\stoptabulate
5461\stop
5462
5463Instead of checking against a prefix you can test against a bitset made from:
5464
5465\startluacode
5466context.starttabulate { "|r|l|r|l|r|l|r|l|" }
5467local n = 4
5468for k, v in table.sortedhash(tex.flagcodes) do
5469 if tonumber(k) then
5470 n = n - 1
5471 context.NC() context("0x%X",k)
5472 context.NC() context(v)
5473 if n == 0 then
5474 context.NC()
5475 context.NR()
5476 n = 4
5477 end
5478 end
5479end
5480context.stoptabulate()
5481\stopluacode
5482
5483\stopnewprimitive
5484
5485\startnewprimitive[title={\prm {iffloat}}]
5486
5487This test does for floats what \prm {ifnum}, \prm {ifdim} do for numbers and
5488dimensions: comparing two of them.
5489
5490\stopnewprimitive
5491
5492\startoldprimitive[title={\prm {iffontchar}}]
5493
5494This is an \ETEX\ conditional. It takes a font identifier and a character number.
5495In modern fonts simply checking could not be enough because complex font features
5496can swap in other ones and their index can be anything. Also, a font mechanism
5497can provide fallback fonts and characters, so dont rely on this one too much. It
5498just reports true when the font passed to the frontend has a slot filled.
5499
5500\stopoldprimitive
5501
5502\startnewprimitive[title={\prm {ifhaschar}}]
5503
5504This one is a simplified variant of the above:
5505
5506\startbuffer
5507\ifhaschar !{this ! works} yes \else no \fi
5508\stopbuffer
5509
5510\typebuffer
5511
5512and indeed we get: \inlinebuffer ! Of course the spaces in this this example
5513code are normally not present in such a test.
5514
5515\stopnewprimitive
5516
5517\startnewprimitive[title={\prm {ifhastok}}]
5518
5519This conditional looks for occurrences in token lists where each argument has to
5520be a proper list.
5521
5522\startbuffer
5523\def\scratchtoks{x}
5524
5525\ifhastoks{yz} {xyz} Y\else N\fi\quad
5526\ifhastoks\scratchtoks {xyz} Y\else N\fi
5527\stopbuffer
5528
5529\typebuffer
5530
5531We get:
5532
5533{\getbuffer}
5534
5535\stopnewprimitive
5536
5537\startnewprimitive[title={\prm {ifhastoks}}]
5538
5539This test compares two token lists. When a macro is passed its meaning
5540gets used.
5541
5542\startbuffer
5543\def\x {x}
5544\def\xyz{xyz}
5545
5546(\ifhastoks {x} {xyz}Y\else N\fi)\quad
5547(\ifhastoks {\x} {xyz}Y\else N\fi)\quad
5548(\ifhastoks \x {xyz}Y\else N\fi)\quad
5549(\ifhastoks {y} {xyz}Y\else N\fi)\quad
5550(\ifhastoks {yz} {xyz}Y\else N\fi)\quad
5551(\ifhastoks {yz} {\xyz}Y\else N\fi)
5552\stopbuffer
5553
5554\typebuffer {\getbuffer}
5555
5556\stopnewprimitive
5557
5558\startnewprimitive[title={\prm {ifhasxtoks}}]
5559
5560This primitive is like the one in the previous section but this time the
5561given lists are expanded.
5562
5563\startbuffer
5564\def\x {x}
5565\def\xyz{\x yz}
5566
5567(\ifhasxtoks {x} {xyz}Y\else N\fi)\quad
5568(\ifhasxtoks {\x} {xyz}Y\else N\fi)\quad
5569(\ifhastoks \x {xyz}Y\else N\fi)\quad
5570(\ifhasxtoks {y} {xyz}Y\else N\fi)\quad
5571(\ifhasxtoks {yz} {xyz}Y\else N\fi)\quad
5572(\ifhasxtoks {yz} {\xyz}Y\else N\fi)
5573\stopbuffer
5574
5575\typebuffer {\getbuffer}
5576
5577This primitive has some special properties.
5578
5579\startbuffer
5580\edef\+{\expandtoken 9 }
5581
5582\ifhasxtoks {xy} {xyz}Y\else N\fi\quad
5583\ifhasxtoks {x\+y} {xyz}Y\else N\fi
5584\stopbuffer
5585
5586\typebuffer
5587
5588Here the first argument has a token that has category code \quote {ignore} which
5589means that such a character will be skipped when seen. So the result is:
5590
5591{\getbuffer}
5592
5593This permits checks like these:
5594
5595\startbuffer
5596\edef\,{\expandtoken 9 ,}
5597
5598\ifhasxtoks{\,x\,} {,x,y,z,}Y\else N\fi\quad
5599\ifhasxtoks{\,y\,} {,x,y,z,}Y\else N\fi\quad
5600\ifhasxtoks{\,z\,} {,x,y,z,}Y\else N\fi\quad
5601\ifhasxtoks{\,x\,} {,xy,z,}Y\else N\fi
5602\stopbuffer
5603
5604\typebuffer
5605
5606I admit that it needs a bit of a twisted mind to come up with this, but it works
5607ok:
5608
5609{\getbuffer}
5610
5611\stopnewprimitive
5612
5613\startoldprimitive[title={\prm {ifhbox}}]
5614
5615This traditional conditional checks if a given box register or internal box
5616variable represents a horizontal box,
5617
5618\stopoldprimitive
5619
5620\startoldprimitive[title={\prm {ifhmode}}]
5621
5622This traditional conditional checks we are in (restricted) horizontal mode.
5623
5624\stopoldprimitive
5625
5626\startnewprimitive[title={\prm {ifinalignment}}]
5627
5628As the name indicates, this primitive tests for being in an alignment. Roughly
5629spoken, the engine is either in a state of align, handling text or dealing with
5630math.
5631
5632\stopnewprimitive
5633
5634\startnewprimitive[title={\prm {ifincsname}}]
5635
5636This conditional is sort of obsolete and can be used to check if were inside a
5637\prm {csname} or \prm {ifcsname} construction. Its not used in \CONTEXT.
5638
5639\stopnewprimitive
5640
5641\startoldprimitive[title={\prm {ifinner}}]
5642
5643This traditional one can be confusing. It is true when we are in restricted
5644horizontal mode (a box), internal vertical mode (a box), or inline math mode.
5645
5646\startbuffer
5647test \ifhmode \ifinner INNER\fi HMODE\fi\crlf
5648\hbox{test \ifhmode \ifinner INNER \fi HMODE\fi} \par
5649
5650\ifvmode \ifinner INNER\fi VMODE \fi\crlf
5651\vbox{\ifvmode \ifinner INNER \fi VMODE\fi} \crlf
5652\vbox{\ifinner INNER \ifvmode VMODE \fi \fi} \par
5653\stopbuffer
5654
5655\typebuffer
5656
5657Watch the last line: because we typeset \type {INNER} we enter horizontal mode:
5658
5659{\getbuffer}
5660
5661\stopoldprimitive
5662
5663\startnewprimitive[title={\prm {ifinsert}}]
5664
5665This is the equivalent of \prm {ifvoid} for a given insert class.
5666
5667\stopnewprimitive
5668
5669\startnewprimitive[title={\prm {ifintervaldim}}]
5670
5671This conditional is true when the intervals around the values of two dimensions
5672overlap. The first dimension determines the interval.
5673
5674\startbuffer
5675[\ifintervaldim1pt 20pt 21pt \else no \fi overlap]
5676[\ifintervaldim1pt 18pt 20pt \else no \fi overlap]
5677\stopbuffer
5678
5679\typebuffer
5680
5681So here: \inlinebuffer
5682
5683\stopnewprimitive
5684
5685\startnewprimitive[title={\prm {ifintervalfloat}}]
5686
5687This one does with floats what we described under \prm {ifintervaldim}.
5688
5689\stopnewprimitive
5690
5691\startnewprimitive[title={\prm {ifintervalnum}}]
5692
5693This one does with integers what we described under \prm {ifintervaldim}.
5694
5695\stopnewprimitive
5696
5697\startnewprimitive[title={\prm {iflastnamedcs}}]
5698
5699When a \prm {csname} is constructed and succeeds the last one is remembered and
5700can be accessed with \prm {lastnamedcs}. It can however be an undefined one. That
5701state can be checked with this primitive. Of course it also works with the \prm
5702{ifcsname} and \prm {begincsname} variants.
5703
5704\stopnewprimitive
5705
5706\startnewprimitive[title={\prm {ifmathparameter}}]
5707
5708This is an \prm {ifcase} where the value depends on if the given math parameter
5709is zero, (\type {0}), set (\type {1}), or unset (\type {2}).
5710
5711\starttyping
5712\ifmathparameter\Umathpunctclosespacing\displaystyle
5713 zero \or
5714 nonzero \or
5715 unset \fi
5716\stoptyping
5717
5718\stopnewprimitive
5719
5720\startnewprimitive[title={\prm {ifmathstyle}}]
5721
5722This is a variant of \prm {ifcase} were the number is one of the seven possible
5723styles: display, text, cramped text, script, cramped script, script script,
5724cramped script script.
5725
5726\starttyping
5727\ifmathstyle
5728 display
5729\or
5730 text
5731\or
5732 cramped text
5733\else
5734 normally smaller than text
5735\fi
5736\stoptyping
5737
5738\stopnewprimitive
5739
5740\startoldprimitive[title={\prm {ifmmode}}]
5741
5742This traditional conditional checks we are in (inline or display) math mode mode.
5743
5744\stopoldprimitive
5745
5746\startoldprimitive[title={\prm {ifnum}}]
5747
5748This is a frequently used conditional: it compares two numbers where a number is
5749anything that can be seen as such.
5750
5751\startbuffer
5752\scratchcounter=65 \chardef\A=65
5753
5754\ifnum65=A YES \else NOP\fi
5755\ifnum\scratchcounter=65 YES \else NOP\fi
5756\ifnum\scratchcounter=\A YES \else NOP\fi
5757\stopbuffer
5758
5759\typebuffer
5760
5761Unless a number is an unexpandable token it ends with a space or \prm {relax},
5762so when you end up in the true branch, youd better check if \TEX\ could
5763determine where the number ends.
5764
5765{\getbuffer}
5766
5767
5768
5769
5770
5771
5772
5773On top of these \ASCII\ combinations, the engine also accepts some \UNICODE\
5774characters. This brings the full repertoire to:
5775
5776\starttabulate[lcTcTl]
5777\FL
5778\BC character \BC \BC \BC operation \NC \NR
5779\ML
5780\NC \type {0x003C} \NC $\Uchar"003C$ \NC \NC less \NC \NR
5781\NC \type {0x003D} \NC $\Uchar"003D$ \NC \NC equal \NC \NR
5782\NC \type {0x003E} \NC $\Uchar"003E$ \NC \NC more \NC \NR
5783\NC \type {0x2208} \NC $\Uchar"2208$ \NC \NC element of \NC \NR
5784\NC \type {0x2209} \NC $\Uchar"2209$ \NC \NC not element of \NC \NR
5785\NC \type {0x2260} \NC $\Uchar"2260$ \NC != \NC not equal \NC \NR
5786\NC \type {0x2264} \NC $\Uchar"2264$ \NC !> \NC less equal \NC \NR
5787\NC \type {0x2265} \NC $\Uchar"2265$ \NC !< \NC greater equal \NC \NR
5788\NC \type {0x2270} \NC $\Uchar"2270$ \NC \NC not less equal \NC \NR
5789\NC \type {0x2271} \NC $\Uchar"2271$ \NC \NC not greater equal \NC \NR
5790\LL
5791\stoptabulate
5792
5793This also applied to \prm {ifdim} although in the case of element we discard the
5794fractional part (read: divide the numeric representation by 65536).
5795
5796\stopoldprimitive
5797
5798\startnewprimitive[title={\prm {ifnumexpression}}]
5799
5800Here is an example of a conditional using expressions:
5801
5802\startbuffer
5803\ifnumexpression (\scratchcounterone > 5) and (\scratchcountertwo > 5) \relax
5804 dosomething
5805\fi
5806\stopbuffer
5807
5808This matches when the result is non zero, and you can mix calculations and tests
5809as with normal expressions.
5810
5811\stopnewprimitive
5812
5813\startnewprimitive[title={\prm {ifnumval}}]
5814
5815This conditional is a variant on \prm {ifchknum}. This time we get
5816some more detail about the value:
5817
5818\startbuffer
5819[12 : \ifnumval 12\or negative\or zero\or positive\else error\fi]\quad
5820[0 : \ifnumval 0\or negative\or zero\or positive\else error\fi]\quad
5821[12 : \ifnumval 12\or negative\or zero\or positive\else error\fi]\quad
5822[oeps : \ifnumval oeps\or negative\or zero\or positive\else error\fi]
5823\stopbuffer
5824
5825\typebuffer
5826
5827This gives:
5828
5829{\getbuffer}
5830
5831\stopnewprimitive
5832
5833\startoldprimitive[title={\prm {ifodd}}]
5834
5835One reason for this condition to be around is that in a double sided layout we
5836need test for being on an odd or even page. It scans for a number the same was
5837as other primitives,
5838
5839\startbuffer
5840\ifodd65 YES \else NO\fi
5841\ifoddB YES \else NO\fi .
5842\stopbuffer
5843
5844\typebuffer
5845
5846So: {\inlinebuffer}
5847
5848\stopoldprimitive
5849
5850\startnewprimitive[title={\prm {ifparameter}}]
5851
5852In a macro body \type {#1} is a reference to a parameter. You can check if one is
5853set using a dedicated parameter condition:
5854
5855\startbuffer
5856\tolerant\def\foo[#1]#*[#2]
5857 {\ifparameter#1\or one\else no one\fi\enspace
5858 \ifparameter#2\or two\else no two\fi\emspace}
5859
5860\foo
5861\foo[1]
5862\foo[1][2]
5863\stopbuffer
5864
5865\typebuffer
5866
5867We get:
5868
5869\getbuffer
5870
5871\stopnewprimitive
5872
5873\startnewprimitive[title={\prm {ifparameters}}]
5874
5875This is equivalent to an \prm {ifcase} with as value the number of parameters
5876passed to the current macro.
5877
5878\stopnewprimitive
5879
5880\startnewprimitive[title={\prm {ifrelax}}]
5881
5882This is a convenient shortcut for \typ {\ifx\relax} and the motivation for adding
5883this one is (as with some others) to get less tracing.
5884
5885\stopnewprimitive
5886
5887\startnewprimitive[title={\prm {iftok}}]
5888
5889When you want to compare two arguments, the usual way to do this is the
5890following:
5891
5892\starttyping
5893\edef\tempA{#1}
5894\edef\tempb{#2}
5895\ifx\tempA\tempB
5896 the same
5897\else
5898 different
5899\fi
5900\stoptyping
5901
5902This works quite well but the fact that we need to define two macros can be
5903considered a bit of a nuisance. It also makes macros that use this method to be
5904not so called \quote {fully expandable}. The next one avoids both issues:
5905
5906\starttyping
5907\iftok{#1}{#2}
5908 the same
5909\else
5910 different
5911\fi
5912\stoptyping
5913
5914Instead of direct list you can also pass registers, so given:
5915
5916\startbuffer[a]
5917\scratchtoks{a}
5918\toks0{a}
5919\stopbuffer
5920
5921\typebuffer[a]
5922
5923This:
5924
5925\startbuffer[b]
5926\iftok 0 \scratchtoks Y\else N\fi\space
5927\iftok{a}\scratchtoks Y\else N\fi\space
5928\iftok\scratchtoks\scratchtoks Y\else N\fi
5929\stopbuffer
5930
5931\typebuffer[b]
5932
5933{\getbuffer[a]gives: \inlinebuffer[b].}
5934
5935\stopnewprimitive
5936
5937\startoldprimitive[title={\prm {iftrue}}]
5938
5939Here we have a traditional \TEX\ conditional that is always true (therefore the
5940same is true for any macro that is \prm {let} to this primitive).
5941
5942\stopoldprimitive
5943
5944\startoldprimitive[title={\prm {ifvbox}}]
5945
5946This traditional conditional checks if a given box register or internal box
5947variable represents a vertical box,
5948
5949\stopoldprimitive
5950
5951\startoldprimitive[title={\prm {ifvmode}}]
5952
5953This traditional conditional checks we are in (internal) vertical mode.
5954
5955\stopoldprimitive
5956
5957\startoldprimitive[title={\prm {ifvoid}}]
5958
5959This traditional conditional checks if a given box register or internal box
5960variable has any content.
5961
5962\stopoldprimitive
5963
5964\startoldprimitive[title={\prm {ifx}}]
5965
5966We use this traditional \TEX\ conditional a lot in \CONTEXT. Contrary to \prm {if}
5967the two tokens that are compared are not expanded. This makes it possible to compare
5968the meaning of two macros. Depending on the need, these macros can have their content
5969expanded or not. A different number of parameters results in false.
5970
5971Control sequences are identical when they have the same command code and
5972character code. Because a \prm {let} macro is just a reference, both let macros
5973are the same and equal to \prm {relax}:
5974
5975\starttyping
5976\let\one\relax \let\two\relax
5977\stoptyping
5978
5979The same is true for other definitions that result in the same (primitive) or
5980meaning encoded in the character field (think of \prm {chardef}s and so).
5981
5982\stopoldprimitive
5983
5984\startnewprimitive[title={\prm {ifzerodim}}]
5985
5986This tests for a dimen (dimension) being zero so we have:
5987
5988\starttyping
5989\ifdim<dimension>=0pt
5990\ifzerodim<dimension>
5991\ifcase<dimension register>
5992\stoptyping
5993
5994\stopnewprimitive
5995
5996\startnewprimitive[title={\prm {ifzerofloat}}]
5997
5998As the name indicated, this tests for a zero float value.
5999
6000\startbuffer
6001[\scratchfloat\zerofloat \ifzerofloat\scratchfloat \else not \fi zero]
6002[\scratchfloat\plusone \ifzerofloat\scratchfloat \else not \fi zero]
6003[\scratchfloat 0.01 \ifzerofloat\scratchfloat \else not \fi zero]
6004[\scratchfloat 0.0e0 \ifzerofloat\scratchfloat \else not \fi zero]
6005[\scratchfloat \zeropoint\ifzerofloat\scratchfloat \else not \fi zero]
6006\stopbuffer
6007
6008\typebuffer
6009
6010So: \inlinebuffer
6011
6012\stopnewprimitive
6013
6014\startnewprimitive[title={\prm {ifzeronum}}]
6015
6016This tests for a number (integer) being zero so we have these variants now:
6017
6018\starttyping
6019\ifnum<integer or equivalent>=0
6020\ifzeronum<integer or equivalent>
6021\ifcase<integer or equivalent>
6022\stoptyping
6023
6024\stopnewprimitive
6025
6026\startnewprimitive[title={\prm {ignorearguments}}]
6027
6028This primitive will quit argument scanning and start expansion of the body of a
6029macro. The number of grabbed arguments can be tested as follows:
6030
6031\startbuffer
6032\def\MyMacro[#1][#2][#3]
6033 {\ifarguments zero\or one\or two\or three \else hm\fi}
6034
6035\MyMacro \ignorearguments \quad
6036\MyMacro [1]\ignorearguments \quad
6037\MyMacro [1][2]\ignorearguments \quad
6038\MyMacro [1][2][3]\ignorearguments \par
6039\stopbuffer
6040
6041\typebuffer
6042
6043{\getbuffer}
6044
6045{\em Todo: explain optional delimiters.}
6046
6047\stopnewprimitive
6048
6049\startnewprimitive[title={\prm {ignoredepthcriterion}}]
6050
6051When setting the \prm {prevdepth} (either by \TEX\ or by the current user) of the
6052current vertical list the value 1000pt is a signal for special treatment of the
6053skip between \quote {lines}. There is an article on that in the distribution. It
6054also demonstrates that \prm {ignoredepthcriterion} can be used to change this
6055special signal, just in case it is needed.
6056
6057\stopnewprimitive
6058
6059\startnewprimitive[title={\prm {ignorenestedupto}}]
6060
6061This primitive gobbles following tokens and can deal with nested \quote
6062{environments}, for example:
6063
6064\startbuffer
6065\def\startfoo{\ignorenestedupto\startfoo\stopfoo}
6066
6067(before
6068\startfoo
6069 test \startfoo test \stopfoo
6070 {test \startfoo test \stopfoo}
6071\stopfoo
6072after)
6073\stopbuffer
6074
6075\typebuffer
6076
6077delivers:
6078
6079\getbuffer
6080
6081\stopnewprimitive
6082
6083\startnewprimitive[title={\prm {ignorepars}}]
6084
6085This is a variant of \prm {ignorespaces}: following spaces {\em and} \type
6086{\par} equivalent tokens are ignored, so for instance:
6087
6088\startbuffer
6089one \ignorepars
6090
6091two = \ignorepars \par
6092three
6093\stopbuffer
6094
6095\typebuffer
6096
6097renders as: \inlinebuffer. Traditionally \TEX\ has been sensitive to \prm {par}
6098tokens in some of its building blocks. This has to do with the fact that it could
6099indicate a runaway argument which in the times of slower machines and terminals
6100was best to catch early. In \LUAMETATEX\ we no longer have long macros and the
6101mechanisms that are sensitive can be told to accept \prm {par} tokens (and
6102\CONTEXT\ set them such that this is the case).
6103
6104\stopnewprimitive
6105
6106\startnewprimitive[title={\prm {ignorerest}}]
6107
6108An example shows what this primitive does:
6109
6110\startbuffer
6111\tolerant\def\foo[#1]#*[#2]
6112 {1234
6113 \ifparameter#1\or\else
6114 \expandafter\ignorerest
6115 \fi
6116 #1
6117 \ifparameter#2\or\else
6118 \expandafter\ignorerest
6119 \fi
6120 #2 }
6121
6122\foo test \foo[456] test \foo[456][789] test
6123\stopbuffer
6124
6125\typebuffer
6126
6127As this likely makes most sense in conditionals you need to make sure the current
6128state is properly finished. Because \prm {expandafter} bumps the input state,
6129here we actually quit two levels; this is because so called \quote {backed up
6130text} is intercepted by this primitive.
6131
6132\getbuffer
6133
6134\stopnewprimitive
6135
6136\startoldprimitive[title={\prm {ignorespaces}}]
6137
6138This traditional \TEX\ primitive signals the scanner to ignore the following
6139spaces, if any. We mention it because we show a companion in the next section.
6140
6141\stopoldprimitive
6142
6143\startnewprimitive[title={\prm {ignoreupto}}]
6144
6145This ignores everything upto the given token, so
6146
6147\startbuffer
6148\ignoreupto \foo not this but\foo only this
6149\stopbuffer
6150
6151\typebuffer
6152
6153will give: \inlinebuffer .
6154
6155\stopnewprimitive
6156
6157\startoldprimitive[title={\prm {immediate}}]
6158
6159This one has no effect unless you intercept it at the \LUA\ end and act upon it.
6160In original \TEX\ immediate is used in combination with read from and write to
6161file operations. So, this is an old primitive with a new meaning.
6162
6163\stopoldprimitive
6164
6165\startnewprimitive[title={\prm {immutable}}]
6166
6167This prefix flags what follows as being frozen and is usually applied to for
6168instance \prm {integerdef}d control sequences. In that respect is is like \prm
6169{permanent} but it makes it possible to distinguish quantities from macros.
6170
6171\stopnewprimitive
6172
6173\startoldprimitive[title={\prm {indent}}]
6174
6175In engines other than \LUAMETATEX\ a paragraph starts with an indentation box.
6176The width of that (empty) box is determined by \prm {parindent}. In \LUAMETATEX\
6177we can use a dedicated indentation skip instead (as part of paragraph
6178normalization). An indentation can be zerod with \prm {undent}.
6179
6180\stopoldprimitive
6181
6182\startnewprimitive[title={\prm {indexofcharacter}}]
6183
6184This primitive is more versatile variant of the backward quote operator, so
6185instead of:
6186
6187\starttyping
6188\number
6189\number
6190\number\a
6191\number\q
6192\stoptyping
6193
6194you can say:
6195
6196\starttyping
6197\the\indexofcharacter
6198\the\indexofcharacter
6199\the\indexofcharacter \a
6200\the\indexofcharacter \q
6201\stoptyping
6202
6203In both cases active characters and unknown single character control sequences
6204are valid. In addition this also works:
6205
6206\starttyping
6207\chardef \foo 128
6208\mathchardef\oof 130
6209
6210\the\indexofcharacter \foo
6211\the\indexofcharacter \oof
6212\stoptyping
6213
6214An important difference is that \prm {indexofcharacter} returns an integer and
6215not a serialized number. A negative value indicates no valid character.
6216
6217\stopnewprimitive
6218
6219\startnewprimitive[title={\prm {indexofregister}}]
6220
6221You can use this instead of \prm {number} for determining the index of a register
6222but it also returns a number when a register value is seen. The result is an
6223integer, not a serialized number.
6224
6225\stopnewprimitive
6226
6227\startnewprimitive[title={\prm {inherited}}]
6228
6229When this prefix is used in a definition using \prm {let} the target will inherit
6230all the properties of the source.
6231
6232\stopnewprimitive
6233
6234\startnewprimitive[title={\prm {initcatcodetable}}]
6235
6236This initializes the catcode table with the given index.
6237
6238\stopnewprimitive
6239
6240\startnewprimitive[title={\prm {initialpageskip}}]
6241
6242When a page starts the value of this register are used to initialize \prm
6243{pagetotal}, \prm {pagestretch} and \prm {pageshrink}. This make nicer code than
6244using a \prm {topskip} with weird values.
6245
6246\stopnewprimitive
6247
6248\startnewprimitive[title={\prm {initialtopskip}}]
6249
6250When set this one will be used instead of \prm {topskip}. The rationale is that
6251the \prm {topskip} is often also used for side effects and compensation.
6252
6253\stopnewprimitive
6254
6255\startoldprimitive[title={\prm {input}}]
6256
6257There are several ways to use this primitive:
6258
6259\starttyping
6260\input test
6261\input {test}
6262\input "test"
6263\input test
6264\stoptyping
6265
6266When no suffix is given, \TEX\ will assume the suffix is \type {.tex}. The second
6267one is normally used.
6268
6269\stopoldprimitive
6270
6271\startoldprimitive[title={\prm {inputlineno}}]
6272
6273This integer holds the current linenumber but it is not always reliable.
6274
6275\stopoldprimitive
6276
6277\startoldprimitive[title={\prm {insert}}]
6278
6279This stores content in the insert container with the given index. In \LUAMETATEX\
6280inserts bubble up to outer boxes so we dont have the \quote {deeply buried
6281insert issue}.
6282
6283\stopoldprimitive
6284
6285\startnewprimitive[title={\prm {insertbox}}]
6286
6287This is the accessor for the box (with results) of an insert with the given
6288index. This is equivalent to the \prm {box} in the traditional method.
6289
6290\stopnewprimitive
6291
6292\startnewprimitive[title={\prm {insertcopy}}]
6293
6294This is the accessor for the box (with results) of an insert with the given
6295index. It makes a copy so the original is kept. This is equivalent to a \prm
6296{copy} in the traditional method.
6297
6298\stopnewprimitive
6299
6300\startnewprimitive[title={\prm {insertdepth}}]
6301
6302This is the (current) depth of the inserted material with the given index. It is
6303comparable to the \prm {dp} in the traditional method.
6304
6305\stopnewprimitive
6306
6307\startnewprimitive[title={\prm {insertdistance}}]
6308
6309This is the space before the inserted material with the given index. This is
6310equivalent to \prm {glue} in the traditional method.
6311
6312\stopnewprimitive
6313
6314\startnewprimitive[title={\prm {insertheight}}]
6315
6316This is the (current) depth of the inserted material with the given index. It is
6317comparable to the \prm {ht} in the traditional method.
6318
6319\stopnewprimitive
6320
6321\startnewprimitive[title={\prm {insertheights}}]
6322
6323This is the combined height of the inserted material.
6324
6325\stopnewprimitive
6326
6327\startnewprimitive[title={\prm {insertlimit}}]
6328
6329This is the maximum height that the inserted material with the given index can
6330get. This is equivalent to \prm {dimen} in the traditional method.
6331
6332\stopnewprimitive
6333
6334\startnewprimitive[title={\prm {insertmaxdepth}}]
6335
6336This is the maximum depth that the inserted material with the given index can
6337get.
6338
6339\stopnewprimitive
6340
6341\startnewprimitive[title={\prm {insertmode}}]
6342
6343In traditional \TEX\ inserts are controlled by a \prm {box}, \prm {dimen}, \prm
6344{glue} and \prm {count} register with the same index. The allocators have to take
6345this into account. When this primitive is set to one a different model is
6346followed with its own namespace. There are more abstract accessors to interface
6347to this. \footnote {The old model might be removed at some point.}
6348
6349\stopnewprimitive
6350
6351\startnewprimitive[title={\prm {insertmultiplier}}]
6352
6353This is the height (contribution) multiplier for the inserted material with the
6354given index. This is equivalent to \prm {count} in the traditional method.
6355
6356\stopnewprimitive
6357
6358\startoldprimitive[title={\prm {insertpenalties}}]
6359
6360This dual purpose internal counter holds the sum of penalties for insertions that
6361got split. When were the output routine in reports the number of insertions that
6362is kept in store.
6363
6364\stopoldprimitive
6365
6366\startnewprimitive[title={\prm {insertpenalty}}]
6367
6368This is the insert penalty associated with the inserted material with the given
6369index.
6370
6371\stopnewprimitive
6372
6373\startnewprimitive[title={\prm {insertprogress}}]
6374
6375This returns the current accumulated insert height of the insert with the given
6376index.
6377
6378\stopnewprimitive
6379
6380\startnewprimitive[title={\prm {insertstorage}}]
6381
6382The value passed will enable (one) or disable (zero) the insert with the given
6383index.
6384
6385\stopnewprimitive
6386
6387\startnewprimitive[title={\prm {insertstoring}}]
6388
6389The value passed will enable (one) or disable (zero) inserts.
6390
6391\stopnewprimitive
6392
6393\startnewprimitive[title={\prm {insertunbox}}]
6394
6395This is the accessor for the box (with results) of an insert with the given
6396index. It makes a copy so the original is kept. The content is unpacked and
6397injected. This is equivalent to an \prm {unvbox} in the traditional method.
6398
6399\stopnewprimitive
6400
6401\startnewprimitive[title={\prm {insertuncopy}}]
6402
6403This is the accessor for the box (with results) of an insert with the given
6404index. It makes a copy so the original is kept. The content is unpacked and
6405injected. This is equivalent to the \prm {unvcopy} in the traditional method.
6406
6407\stopnewprimitive
6408
6409\startnewprimitive[title={\prm {insertwidth}}]
6410
6411This is the (current) width of the inserted material with the given index. It is
6412comparable to the \prm {wd} in the traditional method.
6413
6414\stopnewprimitive
6415
6416\startnewprimitive[title={\prm {instance}}]
6417
6418This prefix flags a macro as an instance which is mostly relevant when a macro
6419package want to categorize macros.
6420
6421\stopnewprimitive
6422
6423\startnewprimitive[title={\prm {integerdef}}]
6424
6425You can alias to a count (integer) register with \prm {countdef}:
6426
6427\starttyping
6428\countdef\MyCount134
6429\stoptyping
6430
6431Afterwards the next two are equivalent:
6432
6433\starttyping
6434\MyCount = 99
6435\count1234 = 99
6436\stoptyping
6437
6438where \type {\MyCount} can be a bit more efficient because no index needs to be
6439scanned. However, in terms of storage the value (here 99) is always in the register
6440so \type {\MyCount} has to get there. This indirectness has the benefit that directly
6441setting the value is reflected in the indirect accessor.
6442
6443\starttyping
6444\integerdef\MyCount = 99
6445\stoptyping
6446
6447This primitive also defines a numeric equivalent but this time the number is stored
6448with the equivalent. This means that:
6449
6450\starttyping
6451\let\MyCopyOfCount = \MyCount
6452\stoptyping
6453
6454will store the {\em current} value of \type {\MyCount} in \type {\MyCopyOfCount} and
6455changing either of them is not reflected in the other.
6456
6457The usual \prm {advance}, \prm {multiply} and \prm {divide} can be used with these
6458integers and they behave like any number. But compared to registers they are actually
6459more a constant.
6460
6461\stopnewprimitive
6462
6463\startoldprimitive[title={\prm {interactionmode}}]
6464
6465This internal integer can be used to set or query the current interaction mode:
6466
6467\starttabulate[]
6468\NC \type {\batchmode } \NC \the\batchmodecode \NC omits all stops and terminal output \NC \NR
6469\NC \type {\nonstopmode } \NC \the\nonstopmodecode \NC omits all stops \NC \NR
6470\NC \type {\scrollmode } \NC \the\scrollmodecode \NC omits error stops \NC \NR
6471\NC \type {\errorstopmode} \NC \the\errorstopmodecode \NC stops at every opportunity to interact \NC \NR
6472\stoptabulate
6473
6474
6475
6476
6477
6478
6479
6480
6481
6482
6483
6484\stopoldprimitive
6485
6486\startoldprimitive[title={\prm {interlinepenalties}}]
6487
6488This is a more granular variant of \prm {interlinepenalty}: an array of penalties
6489to be put between successive line from the start of a paragraph. The list starts
6490with the number of penalties that gets passed.
6491
6492\stopoldprimitive
6493
6494\startoldprimitive[title={\prm {interlinepenalty}}]
6495
6496This is the penalty that is put between lines.
6497
6498\stopoldprimitive
6499
6500\startoldprimitive[title={\prm {jobname}}]
6501
6502This gives the current job name without suffix: {\tttf \jobname}.
6503
6504\stopoldprimitive
6505
6506\startoldprimitive[title={\prm {kern}}]
6507
6508A kern is injected with the given dimension. For variants that switch to a mode
6509we have \prm {hkern} and \prm {vkern}.
6510
6511\stopoldprimitive
6512
6513\startoldprimitive[title={\prm {language}}]
6514
6515Sets (or returns) the current language, a number. In \LUATEX\ and \LUAMETATEX\
6516the current language is stored in the glyph nodes.
6517
6518\stopoldprimitive
6519
6520\startnewprimitive[title={\prm {lastarguments}}]
6521
6522\startbuffer
6523\def\MyMacro #1{\the\lastarguments (#1) } \MyMacro{1} \crlf
6524\def\MyMacro #1#2{\the\lastarguments (#1) (#2)} \MyMacro{1}{2} \crlf
6525\def\MyMacro#1#2#3{\the\lastarguments (#1) (#2) (#3)} \MyMacro{1}{2}{3} \par
6526
6527\def\MyMacro #1{(#1) \the\lastarguments} \MyMacro{1} \crlf
6528\def\MyMacro #1#2{(#1) (#2) \the\lastarguments} \MyMacro{1}{2} \crlf
6529\def\MyMacro#1#2#3{(#1) (#2) (#3) \the\lastarguments} \MyMacro{1}{2}{3} \par
6530\stopbuffer
6531
6532\typebuffer
6533
6534The value of \prm {lastarguments} can only be trusted in the expansion until
6535another macro is seen and expanded. For instance in these examples, as soon as a
6536character (like the left parenthesis) is seen, horizontal mode is entered and
6537\prm {everypar} is expanded which in turn can involve macros. You can see that
6538in the second block (that is: unless we changed \prm {everypar} in the
6539meantime).
6540
6541{\getbuffer}
6542
6543\stopnewprimitive
6544
6545\startnewprimitive[title={\prm {lastatomclass}}]
6546
6547This returns the class number of the last atom seen in the math input parser.
6548
6549\stopnewprimitive
6550
6551\startnewprimitive[title={\prm {lastboundary}}]
6552
6553This primitive looks back in the list for a user boundary injected with \prm
6554{boundary} and when seen it returns that value or otherwise zero.
6555
6556\stopnewprimitive
6557
6558\startoldprimitive[title={\prm {lastbox}}]
6559
6560When issued this primitive will, if possible, pull the last box from the current
6561list.
6562
6563\stopoldprimitive
6564
6565\startnewprimitive[title={\prm {lastchkdimension}}]
6566
6567When the last check for a dimension with \prm {ifchkdimension} was successful
6568this primitive returns the value.
6569
6570\stopnewprimitive
6571
6572\startnewprimitive[title={\prm {lastchknumber}}]
6573
6574When the last check for an integer with \prm {ifchknumber} was successful this
6575primitive returns the value.
6576
6577\stopnewprimitive
6578
6579\startoldprimitive[title={\prm {lastkern}}]
6580
6581This returns the last kern seen in the list (if possible).
6582
6583\stopoldprimitive
6584
6585\startnewprimitive[title={\prm {lastleftclass}}]
6586
6587This variable registers the first applied math class in a formula.
6588
6589\stopnewprimitive
6590
6591\startoldprimitive[title={\prm {lastlinefit}}]
6592
6593The \ETEX\ manuals explains this parameter in detail but in practice it is enough
6594to know that when set to 1000 spaces in the last line might match those in the
6595previous line. Basically it counters the strong push of a \prm {parfillskip}.
6596
6597\stopoldprimitive
6598
6599\startnewprimitive[title={\prm {lastloopiterator}}]
6600
6601In addition to \prm {currentloopiterator} we have a variant that stores the value
6602in case an unexpanded loop is used:
6603
6604\startbuffer
6605\localcontrolledrepeat 8 { [\the\currentloopiterator\eq\the\lastloopiterator] }
6606\expandedrepeat 8 { [\the\currentloopiterator\eq\the\lastloopiterator] }
6607\unexpandedrepeat 8 { [\the\currentloopiterator\ne\the\lastloopiterator] }
6608\stopbuffer
6609
6610\typebuffer
6611
6612\startlines
6613\getbuffer
6614\stoplines
6615
6616\stopnewprimitive
6617
6618\startnewprimitive[title={\prm {lastnamedcs}}]
6619
6620The example code in the previous section has some redundancy, in the sense that
6621there to be looked up control sequence name \type {mymacro} is assembled twice.
6622This is no big deal in a traditional eight bit \TEX\ but in a \UNICODE\ engine
6623multibyte sequences demand some more processing (although it is unlikely that
6624control sequences have many multibyte \UTF8\ characters).
6625
6626\starttyping
6627\ifcsname mymacro\endcsname
6628 \csname mymacro\endcsname
6629\fi
6630\stoptyping
6631
6632Instead we can say:
6633
6634\starttyping
6635\ifcsname mymacro\endcsname
6636 \lastnamedcs
6637\fi
6638\stoptyping
6639
6640Although there can be some performance benefits another advantage is that it uses
6641less tokens and parsing. It might even look nicer.
6642
6643\stopnewprimitive
6644
6645\startnewprimitive[title={\prm {lastnodesubtype}}]
6646
6647When possible this returns the subtype of the last node in the current node list.
6648Possible values can be queried (for each node type) via \LUA\ helpers.
6649
6650\stopnewprimitive
6651
6652\startoldprimitive[title={\prm {lastnodetype}}]
6653
6654When possible this returns the type of the last node in the current node list.
6655Possible values can be queried via \LUA\ helpers.
6656
6657\stopoldprimitive
6658
6659\startnewprimitive[title={\prm {lastpageextra}}]
6660
6661This reports the last applied (permitted) overshoot.
6662
6663\stopnewprimitive
6664
6665\startnewprimitive[title={\prm {lastparcontext}}]
6666
6667When a paragraph is wrapped up the reason is reported by this state variable.
6668Possible values are:
6669
6670\startcolumns[n=4]
6671\getbuffer[engine:syntax:parcontextcodes]
6672\stopcolumns
6673
6674\stopnewprimitive
6675
6676\startnewprimitive[title={\prm {lastpartrigger}}]
6677
6678There are several reasons for entering a paragraphs and some are automatic and
6679triggered by other commands that force \TEX\ into horizontal mode.
6680
6681\startcolumns[n=4]
6682\getbuffer[engine:syntax:partriggercodes]
6683\stopcolumns
6684
6685\stopnewprimitive
6686
6687\startoldprimitive[title={\prm {lastpenalty}}]
6688
6689This returns the last penalty seen in the list (if possible).
6690
6691\stopoldprimitive
6692
6693\startnewprimitive[title={\prm {lastrightclass}}]
6694
6695This variable registers the last applied math class in a formula.
6696
6697\stopnewprimitive
6698
6699\startoldprimitive[title={\prm {lastskip}}]
6700
6701This returns the last glue seen in the list (if possible).
6702
6703\stopoldprimitive
6704
6705\startoldprimitive[title={\prm {lccode}}]
6706
6707When the \prm {lowercase} operation is applied the lowercase code of a character
6708is used for the replacement. This primitive is used to set that code, so it
6709expects two character number. The code is also used to determine what characters
6710make a word suitable for hyphenation, although in \LUATEX\ we introduced the \prm
6711{hj} code for that.
6712
6713\stopoldprimitive
6714
6715\startoldprimitive[title={\prm {leaders}}]
6716
6717See \prm {gleaders} for an explanation.
6718
6719\stopoldprimitive
6720
6721\startoldprimitive[title={\prm {left}}]
6722
6723Inserts the given delimiter as left fence in a math formula.
6724
6725\stopoldprimitive
6726
6727\startoldprimitive[title={\prm {lefthyphenmin}}]
6728
6729This is the minimum number of characters after the last hyphen in a hyphenated
6730word.
6731
6732\stopoldprimitive
6733
6734\startnewprimitive[title={\prm {leftmarginkern}}]
6735
6736The dimension returned is the protrusion kern that has been added (if at all)
6737to the left of the content in the given box.
6738
6739\stopnewprimitive
6740
6741\startoldprimitive[title={\prm {leftskip}}]
6742
6743This skip will be inserted at the left of every line.
6744
6745\stopoldprimitive
6746
6747\startoldprimitive[title={\prm {leqno}}]
6748
6749This primitive stores the (typeset) content (presumably a number) and when the
6750display formula is wrapped that number will end up left of the formula.
6751
6752\stopoldprimitive
6753
6754\startoldprimitive[title={\prm {let}}]
6755
6756Where a \prm {def} creates a new macro, either or not with argument, a \prm {let}
6757creates an alias. You are not limited to aliasing macros, basically everything
6758can be aliased.
6759
6760\stopoldprimitive
6761
6762\startnewprimitive[title={\prm {letcharcode}}]
6763
6764Assigning a meaning to an active character can sometimes be a bit cumbersome;
6765think of using some documented uppercase magic that one tends to forget as its
6766used only a few times and then never looked at again. So we have this:
6767
6768\startbuffer
6769{\letcharcode 65 1 \catcode 65 13 A : \meaning A}\crlf
6770{\letcharcode 65 2 \catcode 65 13 A : \meaning A}\par
6771\stopbuffer
6772
6773\typebuffer
6774
6775here we define \type {A} as an active charcter with meaning \type {1} in the
6776first line and \type {2} in the second.
6777
6778{\tttf \getbuffer}
6779
6780Normally one will assign a control sequence:
6781
6782\startbuffer
6783{\letcharcode 66 \bf \catcode 66 13 {B bold}: \meaning B}\crlf
6784{\letcharcode 73 \it \catcode 73 13 {I italic}: \meaning I}\par
6785\stopbuffer
6786
6787\typebuffer
6788
6789Of course \type {\bf} and \type {\it} are \CONTEXT\ specific commands:
6790
6791{\tttf \getbuffer}
6792
6793\stopnewprimitive
6794
6795\startnewprimitive[title={\prm {letcsname}}]
6796
6797It is easy to see that we save two tokens when we use this primitive. As with the
6798\type {..defcs..} variants it also saves a push back of the composed macro name.
6799
6800\starttyping
6801\expandafter\let\csname MyMacro:1\endcsname\relax
6802 \letcsname MyMacro:1\endcsname\relax
6803\stoptyping
6804
6805\stopnewprimitive
6806
6807\startnewprimitive[title={\prm {letfrozen}}]
6808
6809You can explicitly freeze an unfrozen macro:
6810
6811\starttyping
6812\def\MyMacro{...}
6813\letfrozen\MyMacro
6814\stoptyping
6815
6816A redefinition will now give:
6817
6818\starttyping
6819! You cant redefine a frozen macro.
6820\stoptyping
6821
6822\stopnewprimitive
6823
6824\startnewprimitive[title={\prm {letmathatomrule}}]
6825
6826You can change the class for a specific style. This probably only makes sense
6827for user classes. Its one of those features that we used when experimenting
6828with more control.
6829
6830\starttyping
6831\letmathatomrule 4 = 4 4 0 0
6832\letmathatomrule 5 = 5 5 0 0
6833\stoptyping
6834
6835This changes the classes4 and5 into class 0 in the two script styles and keeps
6836them the same in display and text. We leave it to the reader to ponder how useful
6837this is.
6838
6839\stopnewprimitive
6840
6841
6842
6843
6844
6845
6846
6847\startnewprimitive[title={\prm {letprotected}}]
6848
6849Say that you have these definitions:
6850
6851\startbuffer
6852 \def \MyMacroA{alpha}
6853\protected \def \MyMacroB{beta}
6854 \edef \MyMacroC{\MyMacroA\MyMacroB}
6855\letprotected \MyMacroA
6856 \edef \MyMacroD{\MyMacroA\MyMacroB}
6857\meaning \MyMacroC\crlf
6858\meaning \MyMacroD\par
6859\stopbuffer
6860
6861\typebuffer
6862
6863The typeset meaning in this example is:
6864
6865{\tttf \getbuffer}
6866
6867\stopnewprimitive
6868
6869\startnewprimitive[title={\prm {lettolastnamedcs}}]
6870
6871The \prm {lastnamedcs} primitive is somewhat special as it is a (possible)
6872reference to a control sequence which is why we have a dedicated variant of
6873\prm {let}.
6874
6875\startbuffer
6876\csname relax\endcsname\let \foo\lastnamedcs \meaning\foo
6877\csname relax\endcsname\expandafter\let\expandafter \oof\lastnamedcs \meaning\oof
6878\csname relax\endcsname\lettolastnamedcs \ofo \meaning\ofo
6879\stopbuffer
6880
6881\typebuffer
6882
6883These give the following where the first one obviously is not doing what we want
6884and the second one is kind of cumbersome.
6885
6886\startlines
6887\getbuffer
6888\stoplines
6889
6890\stopnewprimitive
6891
6892\startnewprimitive[title={\prm {lettonothing}}]
6893
6894This one lets a control sequence to nothing. Assuming that \type {\empty}
6895is indeed empty, these two lines are equivalent.
6896
6897\starttyping
6898\let \foo\empty
6899\lettonothing\oof
6900\stoptyping
6901
6902\stopnewprimitive
6903
6904\startoldprimitive[title={\prm {limits}}]
6905
6906This is a modifier: it flags the previous math atom to have its scripts above and
6907below the (summation, product, integral etc.) symbol. In \LUAMETATEX\ this can be
6908any atom (that is: any class). In display mode the location defaults to above and
6909below.
6910
6911\stopoldprimitive
6912
6913\startnewprimitive[title={\prm {linebreakcriterion}}]
6914
6915The par builder has a concept of \quote {compatible} lines, and has categories
6916for that: loose, decent and tight. In \LUAMETATEX\ we also have semiloose and
6917semitight as intermediate categories. This parameter can set the ranges for
6918those, using four double bytes:
6919
6920\starttabulate[Tlc]
6921\NC 0x7F000000 \NC semi tight \NC 12 \NC \NR
6922\NC 0x007F0000 \NC decent \NC 12 \NC \NR
6923\NC 0x00007F00 \NC semi loose \NC 12 \NC \NR
6924\NC 0x0000007F \NC loose \NC 99 \NC \NR
6925\stoptabulate
6926
6927The (decimal) default values are given in the last column. Dont expect a big
6928influence from changing these and this option is mostly a side effect of
6929experiments.
6930
6931\stopnewprimitive
6932
6933\startnewprimitive[title={\prm {linebreakoptional}}]
6934
6935This selects the optional text range that is to be used. Optional content is
6936marked with {optionalboundary} nodes.
6937
6938\stopnewprimitive
6939
6940\startnewprimitive[title={\prm {linebreakpasses}}]
6941
6942When set to a positive value it will apply additional line break runs defined
6943with \prm {parpasses} until the criteria set in there are met. When set to$1$
6944it will signal a final pass
6945
6946\stopnewprimitive
6947
6948\startnewprimitive[title={\prm {linedirection}}]
6949
6950This sets the text direction (1 for \type {r2l}) to the given value but keeps
6951preceding glue into the range.
6952
6953\stopnewprimitive
6954
6955\startoldprimitive[title={\prm {linepenalty}}]
6956
6957Every line gets this penalty attached, so normally it is a small value, like
6958here: \the \linepenalty.
6959
6960\stopoldprimitive
6961
6962\startoldprimitive[title={\prm {lineskip}}]
6963
6964This is the amount of glue that gets added when the distance between lines falls
6965below \prm {lineskiplimit}.
6966
6967\stopoldprimitive
6968
6969\startoldprimitive[title={\prm {lineskiplimit}}]
6970
6971When the distance between two lines becomes less than \prm {lineskiplimit} a \prm
6972{lineskip} glue item is added.
6973
6974\startbuffer
6975\ruledvbox{
6976 \lineskiplimit 0pt \lineskip3pt \baselineskip0pt
6977 \ruledhbox{line 1}
6978 \ruledhbox{line 2}
6979 \ruledhbox{\tx line 3}
6980}
6981\stopbuffer
6982
6983\typebuffer
6984
6985Normally the \prm {baselineskip} kicks in first but here weve set that to zero,
6986so we get two times a 3pt glue injected.
6987
6988\startlocallinecorrection
6989\getbuffer
6990\stoplocallinecorrection
6991
6992\stopoldprimitive
6993
6994
6995
6996
6997\startnewprimitive[title={\prm {localcontrol}}]
6998
6999This primitive takes a single token:
7000
7001\startbuffer
7002\edef\testa{\scratchcounter123 \the\scratchcounter}
7003\edef\testc{\testa \the\scratchcounter}
7004\edef\testd{\localcontrol\testa \the\scratchcounter}
7005\stopbuffer
7006
7007\typebuffer
7008
7009The three meanings are:
7010
7011\start \getbuffer
7012\starttabulate[TT]
7013\NC \string\testa \NC \meaning\testa \NC \NR
7014\NC \string\testc \NC \meaning\testc \NC \NR
7015\NC \string\testd \NC \meaning\testd \NC \NR
7016\stoptabulate
7017\stop
7018
7019The \prm {localcontrol} makes that the following token gets expanded so we dont
7020see the yet to be expanded assignment show up in the macro body.
7021
7022\stopnewprimitive
7023
7024\startnewprimitive[title={\prm {localcontrolled}}]
7025
7026The previously described local control feature comes with two extra helpers. The
7027\prm {localcontrolled} primitive takes a token list and wraps this into a local
7028control sidetrack. For example:
7029
7030\startbuffer
7031\edef\testa{\scratchcounter123 \the\scratchcounter}
7032\edef\testb{\localcontrolled{\scratchcounter123}\the\scratchcounter}
7033\stopbuffer
7034
7035\typebuffer
7036
7037The two meanings are:
7038
7039\start \getbuffer
7040\starttabulate[TT]
7041\NC \string\testa \NC \meaningfull\testa \NC \NR
7042\NC \string\testb \NC \meaningfull\testb \NC \NR
7043\stoptabulate
7044\stop
7045
7046The assignment is applied immediately in the expanded definition.
7047
7048\stopnewprimitive
7049
7050\startnewprimitive[title={\prm {localcontrolledendless}}]
7051
7052As the name indicates this will loop forever. You need to explicitly quit the
7053loop with \prm {quitloop} or \prm {quitloopnow}. The first quitter aborts the
7054loop at the start of a next iteration, the second one tries to exit immediately,
7055but is sensitive for interference with for instance nested conditionals.
7056
7057\stopnewprimitive
7058
7059\startnewprimitive[title={\prm {localcontrolledloop}}]
7060
7061As with more of the primitives discussed here, there is a manual in the \quote
7062{lowlevel} subset that goes into more detail. So, here a simple example has to
7063do:
7064
7065\startbuffer
7066\localcontrolledloop 1 100 1 {
7067 \ifnum\currentloopiterator>6\relax
7068 \quitloop
7069 \else
7070 [\number\currentloopnesting:\number\currentloopiterator]
7071 \localcontrolledloop 1 8 1 {
7072 (\number\currentloopnesting:\number\currentloopiterator)
7073 }\par
7074 \fi
7075}
7076\stopbuffer
7077
7078\typebuffer
7079
7080Here we see the main loop primitive being used nested. The code shows how we can
7081\prm {quitloop} and have access to the \prm {currentloopiterator} as well as the
7082nesting depth \prm {currentloopnesting}.
7083
7084\startpacked \getbuffer \stoppacked
7085
7086Be aware of the fact that \prm {quitloop} will end the loop at the {\em next}
7087iteration so any content after it will show up. Normally this one will be issued
7088in a condition and we want to end that properly. Also keep in mind that because
7089we use local control (a nested \TEX\ expansion loop) anything you feed back can
7090be injected out of order.
7091
7092The three numbers can be separated by an equal sign which is a trick to avoid
7093look ahead issues that can result from multiple serialized numbers without spaces
7094that indicate the end of sequence of digits.
7095
7096\stopnewprimitive
7097
7098\startnewprimitive[title={\prm {localcontrolledrepeat}}]
7099
7100This one takes one instead three arguments which looks a bit better
7101in simple looping.
7102
7103\stopnewprimitive
7104
7105
7106
7107
7108\startnewprimitive[title={\prm {localleftbox}}]
7109
7110This sets the box that gets injected at the left of every line.
7111
7112\stopnewprimitive
7113
7114\startnewprimitive[title={\prm {localleftboxbox}}]
7115
7116This returns the box set with \prm {localleftbox}.
7117
7118\stopnewprimitive
7119
7120\startnewprimitive[title={\prm {localmiddlebox}}]
7121
7122This sets the box that gets injected at the left of every line but its width
7123is ignored.
7124
7125\stopnewprimitive
7126
7127\startnewprimitive[title={\prm {localmiddleboxbox}}]
7128
7129This returns the box set with \prm {localmiddlebox}.
7130
7131\stopnewprimitive
7132
7133
7134
7135
7136\startnewprimitive[title={\prm {localrightbox}}]
7137
7138This sets the box that gets injected at the right of every line.
7139
7140\stopnewprimitive
7141
7142\startnewprimitive[title={\prm {localrightboxbox}}]
7143
7144This returns the box set with \prm {localrightbox}.
7145
7146\stopnewprimitive
7147
7148
7149
7150
7151\startoldprimitive[title={\prm {long}}][obsolete=yes]
7152
7153This original prefix gave the macro being defined the property that it could not
7154have \prm {par} (or the often equivalent empty lines) in its arguments. It was
7155mostly a protection against a forgotten right curly brace, resulting in a so called
7156runaway argument. That mattered on a paper terminal or slow system where such a
7157situation should be catched early. In \LUATEX\ it was already optional, and in
7158\LUAMETATEX\ we dropped this feature completely (so that we could introduce others).
7159
7160\stopoldprimitive
7161
7162\startoldprimitive[title={\prm {looseness}}]
7163
7164The number fo lines in the current paragraph will be increased by given number of
7165lines. For this to succeed there need to be enough stretch in the spacing to make
7166that happen. There is some wishful thinking involved.
7167
7168\stopoldprimitive
7169
7170\startoldprimitive[title={\prm {lower}}]
7171
7172This primitive takes two arguments, a dimension and a box. The box is moved down.
7173The operation only succeeds in horizontal mode.
7174
7175\stopoldprimitive
7176
7177\startoldprimitive[title={\prm {lowercase}}]
7178
7179This token processor converts character tokens to their lowercase counterparts as
7180defined per \prm {lccode}. In order to permit dirty tricks active characters are
7181also processed. We dont really use this primitive in \CONTEXT, but for
7182consistency we let it respond to \prm {expand}: \footnote {Instead of providing
7183\type {\lowercased} and \type {\uppercased} primitives that would clash with
7184macros anyway.}
7185
7186\startbuffer
7187\edef \foo {\lowercase{tex TeX \TEX}} \meaningless\foo
7188\lowercase{\edef\foo {tex TeX \TEX}} \meaningless\foo
7189\edef \foo{\expand\lowercase{tex TeX \TEX}} \meaningless\foo
7190\stopbuffer
7191
7192\typebuffer
7193
7194Watch how \prm {lowercase} is not expandable but can be forced to. Of course, as
7195the logo macro is protected the \TEX\ logo remains mixed case.
7196
7197\startlines
7198\getbuffer
7199\stoplines
7200
7201\stopoldprimitive
7202
7203\startnewprimitive[title={\prm {lpcode}}]
7204
7205This one can be used to set the left protrusion factor of a glyph in a font and
7206takes three arguments: font, character code and factor. It is kind of obsolete
7207because we can set up vectors at definition time and tweaking from \TEX\ can have
7208side effects because it globally adapts the font.
7209
7210\stopnewprimitive
7211
7212\startnewprimitive[title={\prm {luabytecode}}]
7213
7214This behaves like \prm {luafunction} but here the number is a byte code register.
7215These bytecodes are in the \typ {lua.bytecode} array.
7216
7217\stopnewprimitive
7218
7219\startnewprimitive[title={\prm {luabytecodecall}}]
7220
7221This behaves like \prm {luafunctioncall} but here the number is a byte code
7222register. These bytecodes are in the \typ {lua.bytecode} array.
7223
7224\stopnewprimitive
7225
7226\startnewprimitive[title={\prm {luacopyinputnodes}}]
7227
7228When set to a positive value this will ensure that when nodes are printed from
7229\LUA\ to \TEX\ copies are used.
7230
7231\stopnewprimitive
7232
7233\startnewprimitive[title={\prm {luadef}}]
7234
7235
7236
7237
7238
7239
7240
7241
7242
7243This command relates a (user) command to a \LUA\ function registered in the \typ
7244{lua.lualibgetfunctionstable()}, so after:
7245
7246\starttyping
7247\luadef\foo123
7248\stoptyping
7249
7250the \type {\foo} command will trigger the function at index 123. Of course a
7251macro package has to make sure that these definitions are unique. \footnote
7252{Plain \TEX\ established a norm for allocating registers, like \typ {\newdimen}
7253but there is no such convention for \LUA\ functions.}
7254
7255This command is accompanied by \prm {luafunctioncall} and
7256\prm {luafunction}. When we have funciton 123 defined as
7257
7258\starttyping
7259function() tex.sprint("!") end
7260\stoptyping
7261
7262the following:
7263
7264\starttyping
7265(\luafunctioncall \foocode ?)
7266(\normalluafunction\foocode ?)
7267(\foo ?)
7268\stoptyping
7269
7270gives three times \type {(!?)}. But this:
7271
7272\starttyping
7273\edef\oof{\foo } \meaning\oof
7274\edef\oof{\luafunctioncall \foocode} \meaning\oof
7275\edef\oof{\normalluafunction\foocode} \meaning\oof
7276\stoptyping
7277
7278returns:
7279
7280\starttyping
7281macro:!
7282macro:\luafunctioncall 1740
7283macro:!
7284\stoptyping
7285
7286Because the definition command is like any other
7287
7288\starttyping
7289\permanent\protected\luadef\foo123
7290\stoptyping
7291
7292boils down to:
7293
7294\starttyping
7295permanent protected luacall 123
7296\stoptyping
7297
7298\stopnewprimitive
7299
7300\startnewprimitive[title={\prm {luaescapestring}}]
7301
7302This command converts the given (token) list into something that is acceptable
7303for \LUA. It is inherited from \LUATEX\ and not used in \CONTEXT.
7304
7305\startbuffer
7306\directlua { tex.print ("\luaescapestring {{\tt This is a "test".}}") }
7307\stopbuffer
7308
7309\typebuffer
7310
7311Results in: \inlinebuffer\space (Watch the grouping.)
7312
7313\stopnewprimitive
7314
7315\startnewprimitive[title={\prm {luafunction}}]
7316
7317The integer passed to this primitive is the index in the table returned by \typ
7318{lua.lualibgetfunctionstable()}. Of course a macro package has to provide
7319reliable management for this. This is a so called convert command so it expands
7320in an expansion context (like an \prm {edef}).
7321
7322\stopnewprimitive
7323
7324\startnewprimitive[title={\prm {luafunctioncall}}]
7325
7326The integer passed to this primitive is the index in the table returned by \typ
7327{lua.lualibgetfunctionstable()}. Of course a macro package has to provide
7328reliable management for this. This primitive doesnt expand in an expansion
7329context (like an \prm {edef}).
7330
7331\stopnewprimitive
7332
7333\startnewprimitive[title={\prm {luatexbanner}}]
7334
7335This gives: {\tttf \luatexbanner}.
7336
7337\stopnewprimitive
7338
7339\startnewprimitive[title={\prm {luatexrevision}}]
7340
7341This is an integer. The current value is: {\tttf \number\luatexrevision}.
7342
7343\stopnewprimitive
7344
7345\startnewprimitive[title={\prm {luatexversion}}]
7346
7347This is an integer. The current value is: {\tttf \number\luatexversion}.
7348
7349\stopnewprimitive
7350
7351\startoldprimitive[title={\prm {mark}}][obsolete=yes]
7352
7353The given token list is stored in a node in the current list and might become
7354content of \prm {topmark}, \prm {botmark} or \prm {firstmark} when a page split
7355off, or in the case of a box split in \prm {splitbotmark} or \prm
7356{splitfirstmark}. In \LUAMETATEX\ deeply burried marks bubbly up to an outer box
7357level.
7358
7359\stopoldprimitive
7360
7361\startoldprimitive[title={\prm {marks}}]
7362
7363This command is similar to \prm {mark} but first expects a number of a mark
7364register. Multiple marks were introduced in \ETEX.
7365
7366\stopoldprimitive
7367
7368\startoldprimitive[title={\prm {mathaccent}}][obsolete=yes]
7369
7370This takes a number and a math object to put the accent on. The four byte number
7371has a dummy class byte, a family byte and two index bytes. It is replaced by \prm
7372{Umathaccent} that handles wide fonts.
7373
7374\stopoldprimitive
7375
7376\startnewprimitive[title={\prm {mathatom}}]
7377
7378This operation wraps following content in a atom with the given class. It is part
7379of \LUAMETATEXs extended math support. There are three class related
7380keyvalues: \type {class}, \typ {leftclass} and \typ {rightclass} (or \type
7381{all} for all of them). When none is given this command expects a class number
7382before scanning the content. The \type {options} key expects a bitset but there
7383are also direct option keys, like \type {limits}, \typ {nolimits}, \type
7384{unpack}, \type {unroll}, \type {single}, \type {nooverflow}, \type {void} and
7385\type {phantom}. A \type {source} id can be set, one or more \type {attr}
7386assigned, and for specific purposes \typ {textfont} and \typ {mathfont}
7387directives are accepted. Features like this are discussed in dedicated manuals.
7388
7389\stopnewprimitive
7390
7391
7392
7393
7394
7395
7396
7397
7398
7399
7400\startnewprimitive[title={\prm {mathbeginclass}}]
7401
7402This variable can be set to signal the class that starts the formula (think of an
7403imaginary leading atom).
7404
7405\stopnewprimitive
7406
7407\startoldprimitive[title={\prm {mathbin}}]
7408
7409This operation wraps following content in a atom with class \quote {binary}.
7410
7411\stopoldprimitive
7412
7413
7414
7415
7416\startoldprimitive[title={\prm {mathchar}}][obsolete=yes]
7417
7418Replaced by \prm {Umathchar} this old one takes a four byte number: one byte for
7419the class, one for the family an two for the index. The specified character is
7420appended to to the list.
7421
7422\stopoldprimitive
7423
7424\startnewprimitive[title={\prm {mathcharclass}}]
7425
7426Returns the slot (in the font) of the given math character.
7427
7428\startbuffer
7429\the\mathcharclass\Umathchar 4 2 123
7430\stopbuffer
7431
7432\typebuffer
7433
7434The first passed number is the class, so we get: \inlinebuffer.
7435
7436\stopnewprimitive
7437
7438\startoldprimitive[title={\prm {mathchardef}}][obsolete=yes]
7439
7440Replaced by \prm {Umathchardef} this primitive relates a control sequence with a
7441four byte number: one byte for the class, one for the family an two for the
7442index. The defined command will insert that character.
7443
7444\stopoldprimitive
7445
7446\startnewprimitive[title={\prm {mathcharfam}}]
7447
7448Returns the family number of the given math character.
7449
7450\startbuffer
7451\the\mathcharfam\Umathchar 4 2 123
7452\stopbuffer
7453
7454\typebuffer
7455
7456The second passed number is the family, so we get: \inlinebuffer.
7457
7458\stopnewprimitive
7459
7460\startnewprimitive[title={\prm {mathcharslot}}]
7461
7462Returns the slot (or index in the font) of the given math character.
7463
7464\startbuffer
7465\the\mathcharslot\Umathchar 4 2 123
7466\stopbuffer
7467
7468\typebuffer
7469
7470The third passed number is the slot, so we get: \inlinebuffer.
7471
7472\stopnewprimitive
7473
7474
7475
7476
7477\startoldprimitive[title={\prm {mathchoice}}]
7478
7479This command expects four subformulas, for display, text, script and scriptscript
7480and it will eventually use one of them depending on circumstances later on. Keep
7481in mind that a formula is first scanned and when that is finished the analysis
7482and typesetting happens.
7483
7484\stopoldprimitive
7485
7486\startnewprimitive[title={\prm {mathclass}}]
7487
7488This primitive expects a class number and a valid character number or math character
7489and inserts the symbol as if it were of the given class; so the original class is
7490replaced.
7491
7492\startbuffer
7493\ruledhbox{$(x)$} and \ruledhbox{$\mathclass 1 (x\mathclass 1 )$}
7494\stopbuffer
7495
7496\typebuffer
7497
7498Changing the class is likely to change the spacing, compare \inlinebuffer.
7499
7500\stopnewprimitive
7501
7502\startoldprimitive[title={\prm {mathclose}}]
7503
7504This operation wraps following content in a atom with class \quote {close}.
7505
7506\stopoldprimitive
7507
7508\startoldprimitive[title={\prm {mathcode}}][obsolete=yes]
7509
7510This maps a character to one in a family: the assigned value has one byte for the
7511class, one for the family and two for the index. It has little use in an
7512\OPENTYPE\ math setup.
7513
7514\stopoldprimitive
7515
7516
7517
7518
7519
7520
7521
7522
7523
7524
7525\startnewprimitive[title={\prm {mathdirection}}]
7526
7527When set to 1 this will result in \type {r2l} typeset math formulas but of course
7528you then also need to set up math accordingly (which is the case in \CONTEXT).
7529
7530\stopnewprimitive
7531
7532
7533
7534
7535\startnewprimitive[title={\prm {mathdisplaymode}}]
7536
7537Display mode is entered with two dollars (other characters can be used but the
7538dollars are a convention). Mid paragraph display formulas get a different
7539treatment with respect to the width and indentation than stand alone. When \prm
7540{mathdisplaymode} is larger than zero the double dollars (or equivalents) will
7541behave as inline formulas starting out in \prm {displaystyle} and with \prm
7542{everydisplay} expanded.
7543
7544\stopnewprimitive
7545
7546
7547
7548
7549
7550
7551
7552
7553
7554
7555\startnewprimitive[title={\prm {mathendclass}}]
7556
7557This variable can be set to signal the class that ends the formula (think of an
7558imaginary trailing atom).
7559
7560\stopnewprimitive
7561
7562\startnewprimitive[title={\prm {matheqnogapstep}}]
7563
7564The display formula number placement heuristic puts the number on the same line
7565when there is place and then separates it by a quad. In \LUATEX\ we decided to
7566keep that quantity as it can be tight into the math font metrics but introduce
7567a multiplier \prm {matheqnogapstep} that defaults to 1000.
7568
7569\stopnewprimitive
7570
7571
7572
7573
7574
7575
7576
7577\startnewprimitive[title={\prm {mathgluemode}}]
7578
7579We can influence the way math glue is handled. By default stretch and shrink is applied but
7580this variable can be used to change that. The limit option ensures that the stretch and shrink
7581doesnt go beyond their natural values.
7582
7583\getbuffer[engine:syntax:mathgluecodes]
7584
7585\stopnewprimitive
7586
7587\startnewprimitive[title={\prm {mathgroupingmode}}]
7588
7589Normally a \type {{}} or \type {\bgroup}\type {\egroup} pair in math create a
7590math list. However, users are accustomed to using it also for grouping and then a
7591list being created might not be what a user wants. As an alternative to the more
7592verbose \prm {begingroup}\prm {endgroup} or even less sensitive \prm
7593{beginmathgroup}\prm {endmathgroup} you can set the math grouping mode to a
7594non zero value which makes curly braces (and the aliases) behave as expected.
7595
7596\stopnewprimitive
7597
7598
7599
7600
7601\startoldprimitive[title={\prm {mathinner}}]
7602
7603This operation wraps following content in a atom with class \quote {inner}. In
7604\LUAMETATEX\ we have more classes and this general wrapper one is therefore kind
7605of redundant.
7606
7607\stopoldprimitive
7608
7609\startnewprimitive[title={\prm {mathleftclass}}]
7610
7611When set this class will be used when a formula starts.
7612
7613\stopnewprimitive
7614
7615
7616
7617
7618
7619
7620
7621
7622
7623
7624\startoldprimitive[title={\prm {mathop}}]
7625
7626This operation wraps following content in a atom with class \quote {operator}.
7627
7628\stopoldprimitive
7629
7630\startoldprimitive[title={\prm {mathopen}}]
7631
7632This operation wraps following content in a atom with class \quote {open}.
7633
7634\stopoldprimitive
7635
7636\startoldprimitive[title={\prm {mathord}}]
7637
7638This operation wraps following content in a atom with class \quote {ordinary}.
7639
7640\stopoldprimitive
7641
7642
7643
7644
7645\startnewprimitive[title={\prm {mathpretolerance}}]
7646
7647This is used instead of \prm {pretolerance} when a breakpoint is calculated when
7648a math formula starts.
7649
7650\stopnewprimitive
7651
7652\startoldprimitive[title={\prm {mathpunct}}]
7653
7654This operation wraps following content in a atom with class \quote {punctuation}.
7655
7656\stopoldprimitive
7657
7658\startoldprimitive[title={\prm {mathrel}}]
7659
7660This operation wraps following content in a atom with class \quote {relation}.
7661
7662\stopoldprimitive
7663
7664\startnewprimitive[title={\prm {mathrightclass}}]
7665
7666When set this class will be used when a formula ends.
7667
7668\stopnewprimitive
7669
7670
7671
7672
7673
7674
7675
7676\startnewprimitive[title={\prm {mathscale}}]
7677
7678In \LUAMETATEX\ we can either have a family of three (text, script and
7679scriptscript) fonts or we can use one font that we scale and where we also pass
7680information about alternative shapes for the smaller sizes. When we use this
7681more compact mode this primitive reflects the scale factor used.
7682
7683\startbuffer
7684\im {
7685 \textstyle \the\mathscale\textfont \fam\enspace
7686 \scriptstyle \the\mathscale\scriptfont \fam\enspace
7687 \scriptscriptstyle\the\mathscale\scriptscriptfont\fam\enspace
7688 \textstyle \the\mathscale\textfont \fam\enspace
7689 \scriptstyle \the\mathscale\textfont \fam\enspace
7690 \scriptscriptstyle\the\mathscale\textfont \fam
7691
7692}
7693\stopbuffer
7694
7695What gets reported depends on how math is implemented, where in \CONTEXT\ we can
7696have either normal or compact mode: \inlinebuffer. In compact mode we have the
7697same font three times so then it doesnt matter which of the three is passed.
7698
7699\stopnewprimitive
7700
7701
7702
7703
7704
7705
7706
7707
7708
7709
7710
7711
7712
7713
7714
7715
7716\startnewprimitive[title={\prm {mathstyle}}]
7717
7718This returns the current math style, so \type {$\the\mathstyle$} gives $\the\mathstyle$.
7719
7720\stopnewprimitive
7721
7722
7723
7724
7725\startoldprimitive[title={\prm {mathsurround}}]
7726
7727The kern injected before and after an inline math formula. In practice it will be
7728set to zero, if only because otherwise nested math will also get that space
7729added. We also have \prm {mathsurroundskip} which, when set, takes precedence.
7730Spacing is controlled by \prm {mathsurroundmode}.
7731
7732\stopoldprimitive
7733
7734\startnewprimitive[title={\prm {mathsurroundmode}}]
7735
7736The possible ways to control spacing around inline math formulas in other manuals
7737and mostly serve as playground.
7738
7739\stopnewprimitive
7740
7741\startnewprimitive[title={\prm {mathsurroundskip}}]
7742
7743When set this one wins over \prm {mathsurround}.
7744
7745\stopnewprimitive
7746
7747
7748
7749
7750\startnewprimitive[title={\prm {mathtolerance}}]
7751
7752This is used instead of \prm {tolerance} when a breakpoint is calculated when a
7753math formula starts.
7754
7755\stopnewprimitive
7756
7757\startoldprimitive[title={\prm {maxdeadcycles}}]
7758
7759When the output routine is called this many times and no page is shipped out an
7760error will be triggered. You therefore need to reset its companion counter \prm
7761{deadcycles} if needed. Keep in mind that \LUAMETATEX\ has no real \prm {shipout}
7762because providing a backend is up to the macro package.
7763
7764\stopoldprimitive
7765
7766\startoldprimitive[title={\prm {maxdepth}}]
7767
7768The depth of the page is limited to this value.
7769
7770\stopoldprimitive
7771
7772\startoldprimitive[title={\prm {meaning}}]
7773
7774We start with a primitive that will be used in the following sections. The
7775reported meaning can look a bit different than the one reported by other engines
7776which is a side effect of additional properties and more extensive argument
7777parsing.
7778
7779\startbuffer
7780\tolerant\permanent\protected\gdef\foo[#1]#*[#2]{(#1)(#2)} \meaning\foo
7781\stopbuffer
7782
7783\typebuffer \getbuffer
7784
7785\stopoldprimitive
7786
7787\startnewprimitive[title={\prm {meaningasis}}]
7788
7789Although it is not really round trip with the original due to information
7790being lost this primitive tries to return an equivalent definition.
7791
7792\startbuffer
7793\tolerant\permanent\protected\gdef\foo[#1]#*[#2]{(#1)(#2)} \meaningasis\foo
7794\stopbuffer
7795
7796\typebuffer \getbuffer
7797
7798\stopnewprimitive
7799
7800\startnewprimitive[title={\prm {meaningful}}]
7801
7802This one reports a bit less than \prm {meaningful}.
7803
7804\startbuffer
7805\tolerant\permanent\protected\gdef\foo[#1]#*[#2]{(#1)(#2)} \meaningful\foo
7806\stopbuffer
7807
7808\typebuffer \getbuffer
7809
7810\stopnewprimitive
7811
7812\startnewprimitive[title={\prm {meaningfull}}]
7813
7814This one reports a bit more than \prm {meaning}.
7815
7816\startbuffer
7817\tolerant\permanent\protected\gdef\foo[#1]#*[#2]{(#1)(#2)} \meaningfull\foo
7818\stopbuffer
7819
7820\typebuffer \getbuffer
7821
7822\stopnewprimitive
7823
7824\startnewprimitive[title={\prm {meaningles}}]
7825
7826This one reports a bit less than \prm {meaningless}.
7827
7828\startbuffer
7829\tolerant\permanent\protected\gdef\foo[#1]#*[#2]{(#1)(#2)} \meaningles\foo
7830\stopbuffer
7831
7832\typebuffer \getbuffer
7833
7834\stopnewprimitive
7835
7836\startnewprimitive[title={\prm {meaningless}}]
7837
7838This one reports a bit less than \prm {meaning}.
7839
7840\startbuffer
7841\tolerant\permanent\protected\gdef\foo[#1]#*[#2]{(#1)(#2)} \meaningless\foo
7842\stopbuffer
7843
7844\typebuffer \getbuffer
7845
7846\stopnewprimitive
7847
7848\startoldprimitive[title={\prm {medmuskip}}]
7849
7850A predefined mu skip register that can be used in math (inter atom) spacing. The
7851current value is {\tt \the\medmuskip}. In traditional \TEX\ most inter atom
7852spacing is hard coded using the predefined registers.
7853
7854\stopoldprimitive
7855
7856\startoldprimitive[title={\prm {message}}]
7857
7858Prints the serialization of the (tokenized) argument to the log file andor
7859console.
7860
7861\stopoldprimitive
7862
7863\startoldprimitive[title={\prm {middle}}]
7864
7865Inserts the given delimiter as middle fence in a math formula. In \LUAMETATEX\ it
7866is a full blown fence and not (as in \ETEX) variation of \prm {open}.
7867
7868\stopoldprimitive
7869
7870\startoldprimitive[title={\prm {mkern}}]
7871
7872This one injects a kern node in the current (math) list and expects a value in so
7873called mu units.
7874
7875\stopoldprimitive
7876
7877\startoldprimitive[title={\prm {month}}]
7878
7879This internal number starts out with the month that the job started.
7880
7881\stopoldprimitive
7882
7883\startoldprimitive[title={\prm {moveleft}}]
7884
7885This primitive takes two arguments, a dimension and a box. The box is moved to
7886the left. The operation only succeeds in vertical mode.
7887
7888\stopoldprimitive
7889
7890\startoldprimitive[title={\prm {moveright}}]
7891
7892This primitive takes two arguments, a dimension and a box. The box is moved to
7893the right. The operation only succeeds in vertical mode.
7894
7895\stopoldprimitive
7896
7897\startoldprimitive[title={\prm {mskip}}]
7898
7899The given math glue (in \type {mu} units) is injected in the horizontal list. For
7900this to succeed we need to be in math mode.
7901
7902\stopoldprimitive
7903
7904\startoldprimitive[title={\prm {muexpr}}]
7905
7906This is a companion of \prm {glueexpr} so it handles the optional stretch and
7907shrink components. Here math units (\type {mu}) are expected.
7908
7909\stopoldprimitive
7910
7911\startnewprimitive[title={\prm {mugluespecdef}}]
7912
7913A variant of \prm {gluespecdef} that expects \type {mu} units is:
7914
7915\starttyping
7916\mugluespecdef\MyGlue = 3mu plus 2mu minus 1mu
7917\stoptyping
7918
7919The properties are comparable to the ones described in the previous sections.
7920
7921\stopnewprimitive
7922
7923\startoldprimitive[title={\prm {multiply}}]
7924
7925The given quantity is multiplied by the given integer (that can be preceded by
7926the keyword \quote {by}, like:
7927
7928\starttyping
7929\scratchdimen=10pt \multiply\scratchdimen by 3
7930\stoptyping
7931
7932\stopoldprimitive
7933
7934\startnewprimitive[title={\prm {multiplyby}}]
7935
7936This is slightly more efficient variant of \prm {multiply} that doesnt look for
7937\type {by}. See previous section.
7938
7939\stopnewprimitive
7940
7941\startoldprimitive[title={\prm {muskip}}]
7942
7943This is the accessor for an indexed muskip (muglue) register.
7944
7945\stopoldprimitive
7946
7947\startoldprimitive[title={\prm {muskipdef}}]
7948
7949This command associates a control sequence with a muskip (math skip) register
7950(accessed by number).
7951
7952\stopoldprimitive
7953
7954\startnewprimitive[title={\prm {mutable}}]
7955
7956This prefix flags what follows can be adapted and is not subjected to overload
7957protection.
7958
7959\stopnewprimitive
7960
7961\startoldprimitive[title={\prm {mutoglue}}]
7962
7963The sequence \typ {\the \mutoglue 20mu plus 10mu minus 5mu} gives \the \mutoglue
796420mu plus 10mu minus 5mu.
7965
7966\stopoldprimitive
7967
7968\startnewprimitive[title={\prm {nestedloopiterator}}]
7969
7970This is one of the accessors of loop iterators:
7971
7972\startbuffer
7973\expandedrepeat 2 {
7974 \expandedrepeat 3 {
7975 (n=\the\nestedloopiterator 1,
7976 p=\the\previousloopiterator1,
7977 c=\the\currentloopiterator)
7978 }
7979}
7980\stopbuffer
7981
7982\typebuffer
7983
7984Gives:
7985
7986\getbuffer
7987
7988Where a nested iterator starts relative to innermost loop, the previous one is
7989relative to the outer loop (which is less predictable because we can already be
7990in a loop).
7991
7992\stopnewprimitive
7993
7994\startoldprimitive[title={\prm {newlinechar}}]
7995
7996When something is printed to one of the log channels the character with this code
7997will trigger a linebreak. That also resets some counters that deal with
7998suppressing redundant ones and possible indentation. Contrary to other engines
7999\LUAMETATEX\ doesnt bother about the length of lines.
8000
8001\stopoldprimitive
8002
8003\startoldprimitive[title={\prm {noalign}}]
8004
8005The token list passed to this primitive signals that we dont enter a table row
8006yet but for instance in a \prm {halign} do something between the lines: some
8007calculation or injecting interrow material. In \LUAMETATEX\ this primitive can
8008be used nested.
8009
8010\stopoldprimitive
8011
8012\startnewprimitive[title={\prm {noaligned}}]
8013
8014The alignment mechanism is kind of special when it comes to expansion because it
8015has to look ahead for a \prm {noalign}. This interferes with for instance
8016protected macros, but using this prefix we get around that. Among the reasons to
8017use protected macros inside an alignment is that they behave better inside for
8018instance \prm {expanded}.
8019
8020\stopnewprimitive
8021
8022\startnewprimitive[title={\prm {noatomruling}}]
8023
8024Spacing in math is based on classes and this primitive inserts a signal that
8025there is no ruling in place here. Basically we have a zero skip glue tagged as
8026non breakable because in math mode glue is not a valid breakpoint unless we have
8027configured interclass penalties.
8028
8029\stopnewprimitive
8030
8031\startnewprimitive[title={\prm {noboundary}}]
8032
8033This inserts a boundary node with no specific property. It can still serve as
8034boundary but is not interpreted in special ways, like the others.
8035
8036\stopnewprimitive
8037
8038\startoldprimitive[title={\prm {noexpand}}]
8039
8040This prefix prevents expansion in a context where expansion happens. Another way
8041to prevent expansion is to define a macro as \prm {protected}.
8042
8043\startbuffer
8044 \def\foo{foo} \edef\oof{we expanded \foo} \meaning\oof
8045 \def\foo{foo} \edef\oof{we keep \noexpand\foo} \meaning\oof
8046\protected\def\foo{foo} \edef\oof{we keep \foo} \meaning\oof
8047\stopbuffer
8048
8049\typebuffer
8050
8051\startlines
8052\getbuffer
8053\stoplines
8054
8055\stopoldprimitive
8056
8057\startnewprimitive[title={\prm {nohrule}}]
8058
8059This is a rule but flagged as empty which means that the dimensions kick in as
8060for a normal rule but the backend can decide not to show it.
8061
8062\stopnewprimitive
8063
8064\startoldprimitive[title={\prm {noindent}}]
8065
8066This starts a paragraph. In \LUATEX\ (and \LUAMETATEX) a paragraph starts with a
8067so called par node (see \prm {indent} on how control that. After that comes
8068either \prm {parindent} glue or a horizontal box. The \prm {indent} makes gives
8069them some width, while \prm {noindent} keeps that zero.
8070
8071\stopoldprimitive
8072
8073\startoldprimitive[title={\prm {nolimits}}]
8074
8075This is a modifier: it flags the previous math atom to have its scripts after the
8076the atom (contrary to \prm {limits}. In \LUAMETATEX\ this can be any atom (that
8077is: any class). In display mode the location defaults to above and below.
8078
8079\stopoldprimitive
8080
8081\startoldprimitive[title={\prm {nonscript}}]
8082
8083This prevents \TEX\ from adding interatom glue at this spot in script or
8084scriptscript mode. It actually is a special glue itself that serves as signal.
8085
8086\stopoldprimitive
8087
8088\startoldprimitive[title={\prm {nonstopmode}}]
8089
8090This directive omits all stops.
8091
8092\stopoldprimitive
8093
8094\startnewprimitive[title={\prm {norelax}}]
8095
8096The rationale for this command can be shown by a few examples:
8097
8098\startbuffer
8099\dimen0 1pt \dimen2 1pt \dimen4 2pt
8100\edef\testa{\ifdim\dimen0=\dimen2\norelax N\else Y\fi}
8101\edef\testb{\ifdim\dimen0=\dimen2\relax N\else Y\fi}
8102\edef\testc{\ifdim\dimen0=\dimen4\norelax N\else Y\fi}
8103\edef\testd{\ifdim\dimen0=\dimen4\relax N\else Y\fi}
8104\edef\teste{\norelax}
8105\stopbuffer
8106
8107\typebuffer
8108
8109The five meanings are:
8110
8111\start \getbuffer \starttabulate[TT]
8112\NC \string\testa \NC \meaning\testa \NC \NR
8113\NC \string\testb \NC \meaning\testb \NC \NR
8114\NC \string\testc \NC \meaning\testc \NC \NR
8115\NC \string\testd \NC \meaning\testd \NC \NR
8116\NC \string\teste \NC \meaning\teste \NC \NR
8117\stoptabulate \stop
8118
8119So, the \prm {norelax} acts like \prm {relax} but is not pushed back as
8120usual (in some cases).
8121
8122\stopnewprimitive
8123
8124\startnewprimitive[title={\prm {normalizelinemode}}]
8125
8126The \TEX\ engine was not designed to be opened up, and therefore the result of
8127the linebreak effort can differ depending on the conditions. For instance not
8128every line gets the left or rightskip. The first and last lines have some unique
8129components too. When \LUATEX\ made it possible too get the (intermediate) result
8130manipulating the result also involved checking what one encountered, for instance
8131glue and its origin. In \LUAMETATEX\ we can normalize lines so that they have for
8132instance balanced skips.
8133
8134\startcolumns[n=2]
8135\getbuffer[engine:syntax:normalizelinecodes]
8136\stopcolumns
8137
8138The order in which the skips get inserted when we normalize is as follows:
8139
8140\starttabulate
8141\NC \prm {lefthangskip} \NC the hanging indentation (or zero) \NC \NR
8142\NC \prm {leftskip} \NC the value even when zero \NC \NR
8143\NC \prm {parfillleftskip} \NC only on the last line \NC \NR
8144\NC \prm {parinitleftskip} \NC only on the first line \NC \NR
8145\NC \prm {indentskip} \NC the amount of indentation \NC \NR
8146\NC \unknown \NC the (optional) content \NC \NR
8147\NC \prm {parinitrightskip} \NC only on the first line \NC \NR
8148\NC \prm {parfillrightskip} \NC only on the last line \NC \NR
8149\NC \prm {correctionskip} \NC the correction needed to stay within the \prm {hsize} \NC \NR
8150\NC \prm {rightskip} \NC the value even when zero \NC \NR
8151\NC \prm {righthangskip} \NC the hanging indentation (or zero) \NC \NR
8152\stoptabulate
8153
8154The init and fill skips can both show up when we have a single line. The
8155correction skip replaces the traditional juggling with the right skip and shift
8156of the boxed line.
8157
8158For now we leave the other options to your imagination. Some of these can be
8159achieved by callbacks (as we did in older versions of \CONTEXT) but having the
8160engine do the work we get a better performance.
8161
8162\stopnewprimitive
8163
8164\startnewprimitive[title={\prm {normalizeparmode}}]
8165
8166For now we just mention the few options available. It is also worth mentioning that
8167\LUAMETATEX\ tries to balance the direction nodes.
8168
8169\startcolumns[n=2]
8170\getbuffer[engine:syntax:normalizeparcodes]
8171\stopcolumns
8172
8173\stopnewprimitive
8174
8175\startnewprimitive[title={\prm {nospaces}}]
8176
8177When \prm {nospaces} is set to1 no spaces are inserted, when its value is2 a
8178zero space is inserted. The default value is0 which means that spaces become
8179glue with properties depending on the font, specific parameters andor space
8180factors determined preceding characters.
8181
8182\stopnewprimitive
8183
8184\startnewprimitive[title={\prm {nosubprescript}}]
8185
8186This processes the given script in the current style, so:
8187
8188\startbuffer
8189$ x2 x\nosubprescript{2} x\subprescript{2} $
8190\stopbuffer
8191
8192comes out as: \inlinebuffer.
8193
8194\stopnewprimitive
8195
8196\startnewprimitive[title={\prm {nosubscript}}]
8197
8198This processes the given script in the current style, so:
8199
8200\startbuffer
8201$ x2 x\nosubscript{2} x\subscript{2} $
8202\stopbuffer
8203
8204comes out as: \inlinebuffer.
8205
8206\stopnewprimitive
8207
8208\startnewprimitive[title={\prm {nosuperprescript}}]
8209
8210This processes the given script in the current style, so:
8211
8212\startbuffer
8213$ x2 x\nosuperprescript{2} x\superprescript{2} $
8214\stopbuffer
8215
8216comes out as: \inlinebuffer.
8217
8218\stopnewprimitive
8219
8220\startnewprimitive[title={\prm {nosuperscript}}]
8221
8222This processes the given script in the current style, so:
8223
8224\startbuffer
8225$ x2 x\nosuperprescript{2} x\superprescript{2} $
8226\stopbuffer
8227
8228comes out as: \inlinebuffer.
8229
8230\stopnewprimitive
8231
8232\startnewprimitive[title={\prm {novrule}}]
8233
8234This is a rule but flagged as empty which means that the dimensions kick in as
8235for a normal rule but the backend can decide not to show it.
8236
8237\stopnewprimitive
8238
8239\startoldprimitive[title={\prm {nulldelimiterspace}}]
8240
8241In fenced math delimiters can be invisible in which case this parameter
8242determines the amount of space (width) that ghost delimiter takes.
8243
8244\stopoldprimitive
8245
8246\startoldprimitive[title={\prm {nullfont}}]
8247
8248This a symbolic reference to a font with no glyphs and a minimal set of font
8249dimensions.
8250
8251\stopoldprimitive
8252
8253\startoldprimitive[title={\prm {number}}]
8254
8255This \TEX\ primitive serializes the next token into a number, assuming that it
8256is indeed a number, like
8257
8258\starttyping
8259\numberA
8260\number65
8261\number\scratchcounter
8262\stoptyping
8263
8264For counters and such the \prm {the} primitive does the same, but when youre
8265not sure if what follows is a verbose number or (for instance) a counter the
8266\prm {number} primitive is a safer bet, because \type {\the 65} will not work.
8267
8268\stopoldprimitive
8269
8270\startnewprimitive[title={\prm {numericscale}}]
8271
8272This primitive can best be explained by a few examples:
8273
8274\startbuffer
8275\the\numericscale 1323
8276\the\numericscale 1323.0
8277\the\numericscale 1.323
8278\the\numericscale 13.23
8279\stopbuffer
8280
8281\typebuffer
8282
8283In several places \TEX\ uses a scale but due to the lack of floats it then uses
82841000 as 1.0 replacement. This primitive can be used for \quote {real} scales:
8285
8286\startlines \getbuffer \stoplines
8287
8288\stopnewprimitive
8289
8290\startnewprimitive[title={\prm {numericscaled}}]
8291
8292This is a variant if \prm {numericscale}:
8293
8294\startbuffer
8295\scratchcounter 1000
8296\the\numericscaled 1323 \scratchcounter
8297\the\numericscaled 1323.0 \scratchcounter
8298\the\numericscaled 1.323 \scratchcounter
8299\the\numericscaled 13.23 \scratchcounter
8300\stopbuffer
8301
8302\typebuffer
8303
8304The second number gets multiplied by the first fraction:
8305
8306\startlines \getbuffer \stoplines
8307
8308\stopnewprimitive
8309
8310\startoldprimitive[title={\prm {numexpr}}]
8311
8312This primitive was introduced by \ETEX\ and supports a simple expression syntax:
8313
8314\startbuffer
8315\the\numexpr 10 * (1 2 5) 2 \relax
8316\stopbuffer
8317
8318\typebuffer
8319
8320gives: \inlinebuffer. You can mix in symbolic integers and dimensions.
8321
8322\stopoldprimitive
8323
8324\startnewprimitive[title={\prm {numexpression}}]
8325
8326The normal \prm {numexpr} primitive understands the \type {}, \type {}, \type
8327{*} and \type {} operators but in \LUAMETATEX\ we also can use \type {:} for a
8328non rounded integer division (think of \LUAs \type {}). if you want more than
8329that, you can use the new expression primitive where you can use the following
8330operators.
8331
8332\starttabulate[cTcT]
8333\BC add \NC \NC \NC \NR
8334\BC subtract \NC \NC \NC \NR
8335\BC multiply \NC * \NC \NC \NR
8336\BC divide \NC : \NC \NC \NR
8337\BC mod \NC \letterpercent \NC mod \NC \NR
8338\BC band \NC \NC band \NC \NR
8339\BC bxor \NC \NC bxor \NC \NR
8340\BC bor \NC \letterbar \space v \NC bor \NC \NR
8341\BC and \NC \NC and \NC \NR
8342\BC or \NC \letterbar\letterbar \NC or \NC \NR
8343\BC setbit \NC <undecided> \NC bset \NC \NR
8344\BC resetbit \NC <undecided> \NC breset \NC \NR
8345\BC left \NC << \NC \NC \NR
8346\BC right \NC >> \NC \NC \NR
8347\BC less \NC < \NC \NC \NR
8348\BC lessequal \NC <= \NC \NC \NR
8349\BC equal \NC = == \NC \NC \NR
8350\BC moreequal \NC >= \NC \NC \NR
8351\BC more \NC > \NC \NC \NR
8352\BC unequal \NC <> != \lettertilde = \NC \NC \NR
8353\BC not \NC ! \lettertilde \NC not \NC \NR
8354\stoptabulate
8355
8356An example of the verbose bitwise operators is:
8357
8358\starttyping
8359\scratchcounter = \numexpression
8360 "00000 bor "00001 bor "00020 bor "00400 bor "08000 bor "F0000
8361\relax
8362\stoptyping
8363
8364In the table you might have notices that some operators have equivalents. This
8365makes the scanner a bit less sensitive for catcode regimes.
8366
8367When \prm {tracingexpressions} is set to one or higher the intermediate \quote
8368{reverse polish notation} stack that is used for the calculation is shown, for
8369instance:
8370
8371\starttyping
83724:8: {numexpression rpn: 2 5 > 4 5 > and}
8373\stoptyping
8374
8375When you want the output on your console, you need to say:
8376
8377\starttyping
8378\tracingexpressions 1
8379\tracingonline 1
8380\stoptyping
8381
8382\stopnewprimitive
8383
8384\startoldprimitive[title={\prm {omit}}]
8385
8386This primitive cancels the template set for the upcoming cell. Often it is used
8387in combination with \prm {span}.
8388
8389\stopoldprimitive
8390
8391\startnewprimitive[title={\prm {optionalboundary}}]
8392
8393This boundary is used to mark optional content. An positive \prm
8394{optionalboundary} starts a range and a zero one ends it. Nesting is not
8395supported. Optional content is considered when an additional paragraph pass
8396enables it as part of its recipe.
8397
8398\stopnewprimitive
8399
8400\startoldprimitive[title={\prm {or}}]
8401
8402This traditional primitive is part of the condition testing mechanism and relates
8403to an \prm {ifcase} test (or a similar test to be introduced in later
8404sections). Depending on the value, \TEX\ will do a fast scanning till the right
8405\prm {or} is seen, then it will continue expanding till it sees a \prm {or}
8406or \prm {else} or \prm {orelse} (to be discussed later). It will then do a
8407fast skipping pass till it sees an \prm {fi}.
8408
8409\stopoldprimitive
8410
8411\startnewprimitive[title={\prm {orelse}}]
8412
8413This primitive provides a convenient way to flatten your conditional tests. So
8414instead of
8415
8416\starttyping
8417\ifnum\scratchcounter<10
8418 too small
8419\else\ifnum\scratchcounter>10
8420 too large
8421\else
8422 just right
8423\fi\fi
8424\stoptyping
8425
8426You can say this:
8427
8428\starttyping
8429\ifnum\scratchcounter<10
8430 too small
8431\orelse\ifnum\scratchcounter>10
8432 too large
8433\else
8434 just right
8435\fi
8436\stoptyping
8437
8438You can mix tests and even the case variants will work in most cases \footnote {I
8439just play safe because there are corner cases that might not work yet.}
8440
8441\starttyping
8442\ifcase\scratchcounter zero
8443\or one
8444\or two
8445\orelse\ifnum\scratchcounter<10 less than ten
8446\else ten or more
8447\fi
8448\stoptyping
8449
8450Performance wise there are no real benefits although in principle there is a bit
8451less housekeeping involved than with nested checks. However you might like this:
8452
8453\starttyping
8454\ifnum\scratchcounter<10
8455 \expandafter\toosmall
8456\orelse\ifnum\scratchcounter>10
8457 \expandafter\toolarge
8458\else
8459 \expandafter\justright
8460\fi
8461\stoptyping
8462
8463over:
8464
8465\starttyping
8466\ifnum\scratchcounter<10
8467 \expandafter\toosmall
8468\else\ifnum\scratchcounter>10
8469 \expandafter\expandafter\expandafter\toolarge
8470\else
8471 \expandafter\expandafter\expandafter\justright
8472\fi\fi
8473\stoptyping
8474
8475or the more \CONTEXT\ specific:
8476
8477\starttyping
8478\ifnum\scratchcounter<10
8479 \expandafter\toosmall
8480\else\ifnum\scratchcounter>10
8481 \doubleexpandafter\toolarge
8482\else
8483 \doubleexpandafter\justright
8484\fi\fi
8485\stoptyping
8486
8487But then, some \TEX ies like complex and obscure code and throwing away working
8488old code that took ages to perfect and get working and also showed that one
8489masters \TEX\ might hurt.
8490
8491\stopnewprimitive
8492
8493\startnewprimitive[title={\prm {orphanpenalties}}]
8494
8495This an (single entry) array parameter: first the size is given followed by that
8496amount of penalties. These penalties are injected before spaces, going backward
8497from the end of a paragraph. When we see a math node with a penalty set then we
8498take the max and jump over a (preceding) skip.
8499
8500\stopnewprimitive
8501
8502\startnewprimitive[title={\prm {orphanpenalty}}]
8503
8504This penalty is inserted before the last space in a paragraph, unless \prm
8505{orphanpenalties} mandates otherwise.
8506
8507\stopnewprimitive
8508
8509\startnewprimitive[title={\prm {orunless}}]
8510
8511This is the negated variant of \prm {orelse} (prefixing that one with \tex
8512{unless} doesnt work well.
8513
8514\stopnewprimitive
8515
8516\startoldprimitive[title={\prm {outer}}][obsolete=yes]
8517
8518An outer macro is one that can only be used at the outer level. This property is
8519no longer supported. Like \prm {long}, the \prm {outer} prefix is now an
8520noop (and we dont expect this to have unfortunate side effects).
8521
8522\stopoldprimitive
8523
8524\startoldprimitive[title={\prm {output}}]
8525
8526This token list register holds the code that will be expanded when \TEX\ enters
8527the output routine. That code is supposed to do something with the content in
8528the box with number \prm {outputbox}. By default this is box 255 but that can be
8529changed with \prm {outputbox}.
8530
8531\stopoldprimitive
8532
8533\startnewprimitive[title={\prm {outputbox}}]
8534
8535This is where the split off page contend ends up when the output routine is
8536triggered.
8537
8538\stopnewprimitive
8539
8540\startoldprimitive[title={\prm {outputpenalty}}]
8541
8542This is the penalty that triggered the output routine.
8543
8544\stopoldprimitive
8545
8546\startoldprimitive[title={\prm {over}}][obsolete=yes]
8547
8548This math primitive is actually a bit of a spoiler for the parser as it is one of
8549the few that looks back. The \prm {Uover} variant is different and takes two
8550arguments. We leave it to the user to predicts the results of:
8551
8552\starttyping
8553$ {1} \over {x} $
8554$ 1 \over x $
8555$ 12 \over x y $
8556$ a 1 \over {x} $
8557\stoptyping
8558
8559and:
8560
8561\starttyping
8562$ \textstyle 1 \over x $
8563$ {\textstyle 1} \over x $
8564$ \textstyle {1 \over x} $
8565\stoptyping
8566
8567Its one of the reasons why macro packages provide \type {\frac}.
8568
8569\stopoldprimitive
8570
8571\startoldprimitive[title={\prm {overfullrule}}]
8572
8573When an overfull box is encountered a rule can be shown in the margin and this
8574parameter sets its width. For the record: \CONTEXT\ does it different.
8575
8576\stopoldprimitive
8577
8578\startoldprimitive[title={\prm {overline}}]
8579
8580This is a math specific primitive that draws a line over the given content. It is
8581a poor mans replacement for a delimiter. The thickness is set with \prm
8582{Umathoverbarrule}, the distance between content and rule is set by \prm
8583{Umathoverbarvgap} and \prm {Umathoverbarkern} is added above the rule. The style
8584used for the content under the rule can be set with \prm {Umathoverlinevariant}.
8585
8586Because \CONTEXT\ set up math in a special way, the following example:
8587
8588\startbuffer[demo]
8589\normaloverline {
8590 \blackrule[color=red, height=1ex,depth=0ex,width=2cm]
8591 \kern2cm
8592 \blackrule[color=blue,height=0ex,depth=.5ex,width=2cm]
8593 x x
8594}
8595\stopbuffer
8596
8597\typebuffer[demo]
8598
8599gives: \ruledhbox {$\getbuffer[demo]$}, while:
8600
8601\startbuffer[setup]
8602\mathfontcontrol\zerocount
8603\Umathoverbarkern\allmathstyles10pt
8604\Umathoverbarvgap\allmathstyles5pt
8605\Umathoverbarrule\allmathstyles2.5pt
8606\Umathoverlinevariant\textstyle\scriptstyle
8607\stopbuffer
8608
8609\typebuffer[setup]
8610
8611gives this: \ruledhbox {$\getbuffer[setup,demo]$}. We have to disable the related
8612\prm {mathfontcontrol} bits because otherwise the thickness is taken from the font. The
8613variant is just there to overload the (in traditional \TEX\ engines) default.
8614
8615\stopoldprimitive
8616
8617\startnewprimitive[title={\prm {overloaded}}]
8618
8619This prefix can be used to overload a frozen macro.
8620
8621\stopnewprimitive
8622
8623\startnewprimitive[title={\prm {overloadmode}}]
8624
8625The overload protection mechanism can be used to prevent users from redefining
8626a control sequence. The mode can have several values, the higher the more strict
8627we are:
8628
8629\starttabulate[]
8630 \NC \NC \NC immutable \NC permanent \NC primitive \NC frozen \NC instance \NC \NR
8631 \NC 1 \NC warning \NC \NC \NC \NC \NC \NC \NR
8632 \NC 2 \NC error \NC \NC \NC \NC \NC \NC \NR
8633 \NC 3 \NC warning \NC \NC \NC \NC \NC \NC \NR
8634 \NC 4 \NC error \NC \NC \NC \NC \NC \NC \NR
8635 \NC 5 \NC warning \NC \NC \NC \NC \NC \NC \NR
8636 \NC 6 \NC error \NC \NC \NC \NC \NC \NC \NR
8637\stoptabulate
8638
8639When you set a high error value, you can of course temporary lower or even zero
8640the mode. In \CONTEXT\ all macros and quantities are tagged so there setting the
8641mode to6 gives a proper protection against overloading. We need to zero the mode
8642when we load for instance tikz, so when you use that generic package, you loose
8643some.
8644
8645\stopnewprimitive
8646
8647\startnewprimitive[title={\prm {overshoot}}]
8648
8649This primitive is a companion to \prm {badness} and reports how much a box
8650overflows.
8651
8652\startbuffer
8653\setbox0\hbox to 1em {mmm} \the\badness\quad\the\overshoot
8654\setbox0\hbox {mm} \the\badness\quad\the\overshoot
8655\setbox0\hbox to 3em {m} \the\badness\quad\the\overshoot
8656\stopbuffer
8657
8658\typebuffer
8659
8660This reports:
8661
8662\startlines
8663\getbuffer
8664\stoplines
8665
8666When traditional \TEX\ wraps up the lines in a paragraph it uses a mix of shift
8667(a box property) to position the content suiting the hanging indentation andor
8668paragraph shape, and fills up the line using right skip glue, also in order to
8669silence complaints in packaging. In \LUAMETATEX\ the lines can be normalized so
8670that they all have all possible skips to the left and right (even if theyre
8671zero). The \prm {overshoot} primitive fits into this picture and is present as a
8672compensation glue. This all fits better in a situation where the internals are
8673opened up via \LUA.
8674
8675\stopnewprimitive
8676
8677\startoldprimitive[title={\prm {overwithdelims}}][obsolete=yes]
8678
8679This is a variant of \prm {over} but with delimiters. It has a more advanced
8680upgrade in \prm {Uoverwithdelims}.
8681
8682\stopoldprimitive
8683
8684\startnewprimitive[title={\prm {pageboundary}}]
8685
8686In order to avoid side effects of triggering the page builder with a specific
8687penalty we can use this primitive which expects a value that actually gets
8688inserted as zero penalty before triggering the page builder callback. Think of
8689adding a noop to the contribution list. We fake a zero penalty so that all
8690gets processed. The main rationale is that we get a better indication of what we
8691do. Of course a callback can remove this node so that it is never seen.
8692Triggering from the callback is not doable. Consider this experimental code
8693(which is actually used in \CONTEXT\ anyway).
8694
8695\stopnewprimitive
8696
8697\startnewprimitive[title={\prm {pagedepth}}]
8698
8699This page property holds the depth of the page.
8700
8701\stopnewprimitive
8702
8703\startoldprimitive[title={\prm {pagediscards}}]
8704
8705The leftovers after a page is split of the main vertical list when glue and
8706penalties are normally discarded. The discards can be pushed back in (for
8707instance) trial runs.
8708
8709\stopoldprimitive
8710
8711\startnewprimitive[title={\prm {pageexcess}}]
8712
8713This page property hold the amount of overflow when a page break occurs.
8714
8715\stopnewprimitive
8716
8717\startnewprimitive[title={\prm {pageextragoal}}]
8718
8719This (experimental) dimension will be used when the page overflows but a bit of
8720overshoot is considered okay.
8721
8722\stopnewprimitive
8723
8724\startoldprimitive[title={\prm {pagefilllstretch}}]
8725
8726The accumulated amount of third order stretch on the current page.
8727
8728\stopoldprimitive
8729
8730\startoldprimitive[title={\prm {pagefillstretch}}]
8731
8732The accumulated amount of second order stretch on the current page.
8733
8734\stopoldprimitive
8735
8736\startoldprimitive[title={\prm {pagefilstretch}}]
8737
8738The accumulated amount of first order stretch on the current page.
8739
8740\stopoldprimitive
8741
8742\startnewprimitive[title={\prm {pagefistretch}}]
8743
8744The accumulated amount of zero order stretch on the current page.
8745
8746\stopnewprimitive
8747
8748\startoldprimitive[title={\prm {pagegoal}}]
8749
8750The target height of a page (the running text). This value will be decreased by
8751the height of inserts something to keep into mind when messing around with this
8752and other (pseudo) page related parameters like \prm {pagetotal}.
8753
8754\stopoldprimitive
8755
8756\startnewprimitive[title={\prm {pagelastdepth}}]
8757
8758The accumulated depth of the current page.
8759
8760\stopnewprimitive
8761
8762\startnewprimitive[title={\prm {pagelastfilllstretch}}]
8763
8764The accumulated amount of third order stretch on the current page. Contrary to
8765\prm {pagefilllstretch} this is the really contributed amount, not the upcoming.
8766
8767\stopnewprimitive
8768
8769\startnewprimitive[title={\prm {pagelastfillstretch}}]
8770
8771The accumulated amount of second order stretch on the current page. Contrary to
8772\prm {pagefillstretch} this is the really contributed amount, not the upcoming.
8773
8774\stopnewprimitive
8775
8776\startnewprimitive[title={\prm {pagelastfilstretch}}]
8777
8778The accumulated amount of first order stretch on the current page. Contrary to
8779\prm {pagefilstretch} this is the really contributed amount, not the upcoming.
8780
8781\stopnewprimitive
8782
8783\startnewprimitive[title={\prm {pagelastfistretch}}]
8784
8785The accumulated amount of zero order stretch on the current page. Contrary to
8786\prm {pagefistretch} this is the really contributed amount, not the upcoming.
8787
8788\stopnewprimitive
8789
8790\startnewprimitive[title={\prm {pagelastheight}}]
8791
8792The accumulated height of the current page.
8793
8794\stopnewprimitive
8795
8796\startnewprimitive[title={\prm {pagelastshrink}}]
8797
8798The accumulated amount of shrink on the current page. Contrary to \prm
8799{pageshrink} this is the really contributed amount, not the upcoming.
8800
8801\stopnewprimitive
8802
8803\startnewprimitive[title={\prm {pagelaststretch}}]
8804
8805The accumulated amount of stretch on the current page. Contrary to \prm
8806{pagestretch} this is the really contributed amount, not the upcoming.
8807
8808\stopnewprimitive
8809
8810\startoldprimitive[title={\prm {pageshrink}}]
8811
8812The accumulated amount of shrink on the current page.
8813
8814\stopoldprimitive
8815
8816\startoldprimitive[title={\prm {pagestretch}}]
8817
8818The accumulated amount of stretch on the current page.
8819
8820\stopoldprimitive
8821
8822\startoldprimitive[title={\prm {pagetotal}}]
8823
8824The accumulated page total (height) of the current page.
8825
8826\stopoldprimitive
8827
8828\startnewprimitive[title={\prm {pagevsize}}]
8829
8830This parameter, when set, is used as the target page height. This lessens the
8831change of \prm {vsize} interfering.
8832
8833\stopnewprimitive
8834
8835\startoldprimitive[title={\prm {par}}]
8836
8837This is the explicit \quote {finish paragraph} command. Internally we distinguish
8838a par triggered by a new line, as side effect of another primitive or this \prm
8839{par} command.
8840
8841\stopoldprimitive
8842
8843\startnewprimitive[title={\prm {parametercount}}]
8844
8845The number of parameters passed to the current macro.
8846
8847\stopnewprimitive
8848
8849\startnewprimitive[title={\prm {parameterdef}}]
8850
8851Here is an example of binding a variable to a parameter. The alternative is of
8852course to use an \prm {edef}.
8853
8854\startbuffer
8855\def\foo#1#2
8856 {\parameterdef\MyIndexOne\plusone
8857 \parameterdef\MyIndexTwo\plustwo
8858 \oof{P}\oof{Q}\oof{R}\norelax}
8859
8860\def\oof#1
8861 {<1:\MyIndexOne><1:\MyIndexOne>
8862 #1
8863 <2:\MyIndexTwo><2:\MyIndexTwo>}
8864
8865\foo{A}{B}
8866\stopbuffer
8867
8868\typebuffer
8869
8870The outcome is:
8871
8872\getbuffer
8873
8874\stopnewprimitive
8875
8876\startnewprimitive[title={\prm {parameterindex}}]
8877
8878This gives the zero based position on the parameter stack. One reason for
8879introducing \prm {parameterdef} is that the position remains abstract so there we
8880dont need to use \prm {parameterindex}.
8881
8882\stopnewprimitive
8883
8884\startnewprimitive[title={\prm {parametermark}}]
8885
8886This is an equivalent for \type {#}.
8887
8888\stopnewprimitive
8889
8890\startnewprimitive[title={\prm {parametermode}}]
8891
8892Setting this internal integer to a positive value (best use1 because future
8893versions might use bit set) will enable the usage of \type {#} for escaped in the
8894main text and body of macros.
8895
8896\stopnewprimitive
8897
8898\startnewprimitive[title={\prm {parattribute}}]
8899
8900This primitive takes an attribute index and value and sets that attribute on the
8901current paragraph.
8902
8903\stopnewprimitive
8904
8905\startnewprimitive[title={\prm {pardirection}}]
8906
8907This set the text direction for the whole paragraph which in the case of \type
8908{r2l} (1) makes the right edge the starting point.
8909
8910\stopnewprimitive
8911
8912\startnewprimitive[title={\prm {parfillleftskip}}]
8913
8914The glue inserted at the start of the last line.
8915
8916\stopnewprimitive
8917
8918\startnewprimitive[title={\prm {parfillrightskip}}]
8919
8920The glue inserted at the end of the last line (aka \prm {parfillskip}).
8921
8922\stopnewprimitive
8923
8924\startoldprimitive[title={\prm {parfillskip}}]
8925
8926The glue inserted at the end of the last line.
8927
8928\stopoldprimitive
8929
8930\startoldprimitive[title={\prm {parindent}}]
8931
8932The amount of space inserted at the start of the first line. When bit \tobit
8933\parindentskipnormalizecode\ is set in \prm {normalizelinemode} a glue is
8934inserted, otherwise an empty \prm {hbox} with the given width is inserted.
8935
8936\stopoldprimitive
8937
8938\startnewprimitive[title={\prm {parinitleftskip}}]
8939
8940The glue inserted at the start of the first line.
8941
8942\stopnewprimitive
8943
8944\startnewprimitive[title={\prm {parinitrightskip}}]
8945
8946The glue inserted at the end of the first line.
8947
8948\stopnewprimitive
8949
8950\startnewprimitive[title={\prm {parpasses}}]
8951
8952Specifies one or more recipes for additional second linebreak passes. Examples
8953can be found in the \CONTEXT\ distribution.
8954
8955\stopnewprimitive
8956
8957\startoldprimitive[title={\prm {parshape}}]
8958
8959Stores a shape specification. The first argument is the length of the list,
8960followed by that amount of indentationwidth pairs (two dimensions).
8961
8962\stopoldprimitive
8963
8964\startoldprimitive[title={\prm {parshapedimen}}]
8965
8966This oddly named (\ETEX) primitive returns the width component (dimension) of the
8967given entry (an integer). Obsoleted by \prm {parshapewidth}.
8968
8969\stopoldprimitive
8970
8971\startoldprimitive[title={\prm {parshapeindent}}]
8972
8973Returns the indentation component (dimension) of the given entry (an integer).
8974
8975\stopoldprimitive
8976
8977\startoldprimitive[title={\prm {parshapelength}}]
8978
8979Returns the number of entries (an integer).
8980
8981\stopoldprimitive
8982
8983\startnewprimitive[title={\prm {parshapewidth}}]
8984
8985Returns the width component (dimension) of the given entry (an integer).
8986
8987\stopnewprimitive
8988
8989\startoldprimitive[title={\prm {parskip}}]
8990
8991This is the amount of glue inserted before a new paragraph starts.
8992
8993\stopoldprimitive
8994
8995\startoldprimitive[title={\prm {patterns}}]
8996
8997The argument to this primitive contains hyphenation patterns that are bound to
8998the current language. In \LUATEX\ and \LUAMETATEX\ we can also manage this at the
8999\LUA\ end. In \LUAMETATEX\ we dont store patterns in te format file
9000
9001\stopoldprimitive
9002
9003\startoldprimitive[title={\prm {pausing}}][obsolete=yes]
9004
9005In \LUAMETATEX\ this variable is ignored but in other engines it can be used to
9006single step thought the input file by setting it to a positive value.
9007
9008\stopoldprimitive
9009
9010\startoldprimitive[title={\prm {penalty}}]
9011
9012The given penalty (a number) is inserted at the current spot in the horizontal or
9013vertical list. We also have \prm {vpenalty} and \prm {hpenalty} that first change
9014modes.
9015
9016\stopoldprimitive
9017
9018\startnewprimitive[title={\prm {permanent}}]
9019
9020This is one of the prefixes that is part of the overload protection mechanism. It
9021is normally used to flag a macro as being at the same level as a primitive: dont
9022touch it. primitives are flagged as such but that property cannot be set on
9023regular macros. The similar \prm {immutable} flag is normally used for variables.
9024
9025\stopnewprimitive
9026
9027\startnewprimitive[title={\prm {pettymuskip}}]
9028
9029A predefined mu skip register that can be used in math (inter atom) spacing. The
9030current value is {\tt \the\pettymuskip}. This one complements \prm {thinmuskip},
9031\prm {medmuskip}, \prm {thickmuskip} and the new \prm {tinymuskip}.
9032
9033\stopnewprimitive
9034
9035\startnewprimitive[title={\prm {positdef}}]
9036
9037The engine uses 32 bit integers for various purposes and has no (real) concept of
9038a floating point quantity. We get around this by providing a floating point data
9039type based on 32 bit unums (posits). These have the advantage over native floats
9040of more precision in the lower ranges but at the cost of a software
9041implementation.
9042
9043The \prm {positdef} primitive is the floating point variant of \prm {integerdef}
9044and \prm {dimensiondef}: an efficient way to implement named quantities other
9045than registers.
9046
9047\startbuffer
9048\positdef \MyFloatA 5.678
9049\positdef \MyFloatB 567.8
9050[\the\MyFloatA] [\todimension\MyFloatA] [\tointeger\MyFloatA]
9051[\the\MyFloatB] [\todimension\MyFloatB] [\tointeger\MyFloatB]
9052\stopbuffer
9053
9054\typebuffer
9055
9056For practical reasons we can map posit (or float) onto an integer or dimension:
9057
9058\startlines
9059\getbuffer
9060\stoplines
9061
9062
9063
9064
9065\stopnewprimitive
9066
9067\startoldprimitive[title={\prm {postdisplaypenalty}}]
9068
9069This is the penalty injected after a display formula.
9070
9071\stopoldprimitive
9072
9073\startnewprimitive[title={\prm {postexhyphenchar}}]
9074
9075This primitive expects a language number and a character code. A negative
9076character code is equivalent to ignore. In case of an explicit discretionary the
9077character is injected at the beginning of a new line.
9078
9079\stopnewprimitive
9080
9081\startnewprimitive[title={\prm {posthyphenchar}}]
9082
9083This primitive expects a language number and a character code. A negative
9084character code is equivalent to ignore. In case of an automatic discretionary the
9085character is injected at the beginning of a new line.
9086
9087\stopnewprimitive
9088
9089\startnewprimitive[title={\prm {postinlinepenalty}}]
9090
9091When set this penalty is inserted after an inline formula unless we have a short
9092formula and \prm {postshortinlinepenalty} is set.
9093
9094\stopnewprimitive
9095
9096\startnewprimitive[title={\prm {postshortinlinepenalty}}]
9097
9098When set this penalty is inserted after a short inline formula. The criterium is
9099set by \prm {shortinlinemaththreshold} but only applied when it is enabled for
9100the class involved.
9101
9102\stopnewprimitive
9103
9104\startnewprimitive[title={\prm {prebinoppenalty}}]
9105
9106This internal quantity is a compatibility feature because normally we will use
9107the inter atom spacing variables.
9108
9109\stopnewprimitive
9110
9111\startoldprimitive[title={\prm {predisplaydirection}}]
9112
9113This is the direction that the math sub engine will take into account when
9114dealing with right to left typesetting.
9115
9116\stopoldprimitive
9117
9118\startnewprimitive[title={\prm {predisplaygapfactor}}]
9119
9120The heuristics related to determine if the previous line in a formula overlaps
9121with a (display) formula are hard coded but in \LUATEX\ to be two times the quad
9122of the current font. This parameter is a multiplier set to 2000 and permits you
9123to change the overshoot in this heuristic.
9124
9125\stopnewprimitive
9126
9127\startoldprimitive[title={\prm {predisplaypenalty}}]
9128
9129This is the penalty injected before a display formula.
9130
9131\stopoldprimitive
9132
9133\startoldprimitive[title={\prm {predisplaysize}}]
9134
9135This parameter holds the length of the last line in a paragraph when a display
9136formula is part of it.
9137
9138\stopoldprimitive
9139
9140\startnewprimitive[title={\prm {preexhyphenchar}}]
9141
9142This primitive expects a language number and a character code. A negative
9143character code is equivalent to ignore. In case of an explicit discretionary the
9144character is injected at the end of the line.
9145
9146\stopnewprimitive
9147
9148\startnewprimitive[title={\prm {prehyphenchar}}]
9149
9150This primitive expects a language number and a character code. A negative
9151character code is equivalent to ignore. In case of an automatic discretionary the
9152character is injected at the end of the line.
9153
9154\stopnewprimitive
9155
9156\startnewprimitive[title={\prm {preinlinepenalty}}]
9157
9158When set this penalty is inserted before an inline formula unless we have a short
9159formula and \prm {preshortinlinepenalty} is set.
9160
9161\stopnewprimitive
9162
9163\startnewprimitive[title={\prm {prerelpenalty}}]
9164
9165This internal quantity is a compatibility feature because normally we will use
9166the inter atom spacing variables.
9167
9168\stopnewprimitive
9169
9170\startnewprimitive[title={\prm {preshortinlinepenalty}}]
9171
9172When set this penalty is inserted before a short inline formula. The criterium is
9173set by \prm {shortinlinemaththreshold} but only applied when it is enabled for
9174the class involved.
9175
9176\stopnewprimitive
9177
9178\startoldprimitive[title={\prm {pretolerance}}]
9179
9180When the badness of a line in a paragraph exceeds this value a second linebreak
9181pass will be enabled.
9182
9183\stopoldprimitive
9184
9185\startoldprimitive[title={\prm {prevdepth}}]
9186
9187The depth of current list. It can also be set to special (signal) values in order
9188to inhibit line corrections. It is not an internal dimension but a (current) list
9189property.
9190
9191\stopoldprimitive
9192
9193\startoldprimitive[title={\prm {prevgraf}}]
9194
9195The number of lines in a previous paragraph.
9196
9197\stopoldprimitive
9198
9199\startnewprimitive[title={\prm {previousloopiterator}}]
9200
9201\startbuffer
9202\edef\testA{
9203 \expandedrepeat 2 {
9204 \expandedrepeat 3 {
9205 (\the\previousloopiterator1:\the\currentloopiterator)
9206 }
9207 }
9208}
9209\edef\testB{
9210 \expandedrepeat 2 {
9211 \expandedrepeat 3 {
9212 (#P:#I)
9213 }
9214 }
9215}
9216\stopbuffer
9217
9218\typebuffer \getbuffer
9219
9220These give the same result:
9221
9222\startlines \tt
9223\meaningasis\testA
9224\meaningasis\testB
9225\stoplines
9226
9227The number indicates the number of levels we go up the loop chain.
9228
9229\stopnewprimitive
9230
9231\startnewprimitive[title={\prm {primescript}}]
9232
9233This is a math script primitive dedicated to primes (which are somewhat
9234troublesome on math). It complements the six script primitives (like \prm
9235{subscript} and \prm {presuperscript}).
9236
9237\stopnewprimitive
9238
9239\startoldprimitive[title={\prm {protected}}]
9240
9241A protected macro is one that doesnt get expanded unless it is time to do so.
9242For instance, inside an \prm {edef} it just stays what it is. It often makes
9243sense to pass macros asis to (multipass) file (for tables of contents).
9244
9245In \CONTEXT\ we use either \prm {protected} or \prm {unexpanded} because the
9246later was the command we used to achieve the same results before \ETEX\
9247introduced this protection primitive. Originally the \prm {protected} macro was
9248also defined but it has been dropped.
9249
9250\stopoldprimitive
9251
9252\startnewprimitive[title={\prm {protecteddetokenize}}]
9253
9254This is a variant of \prm {protecteddetokenize} that uses some escapes encoded as
9255body parameters, like \type {#H} for a hash.
9256
9257\stopnewprimitive
9258
9259\startnewprimitive[title={\prm {protectedexpandeddetokenize}}]
9260
9261This is a variant of \prm {expandeddetokenize} that uses some escapes encoded as
9262body parameters, like \type {#H} for a hash.
9263
9264\stopnewprimitive
9265
9266\startnewprimitive[title={\prm {protrudechars}}]
9267
9268This variable controls protrusion (into the margin). A value2 is comparable with
9269other engines, while a value of3 does a bit more checking when were doing
9270righttoleft typesetting.
9271
9272\stopnewprimitive
9273
9274\startnewprimitive[title={\prm {protrusionboundary}}]
9275
9276This injects a boundary with the given value:
9277
9278\getbuffer[engine:syntax:protrusionboundarycodes]
9279
9280This signal makes the protrusion checker skip over a node.
9281
9282\stopnewprimitive
9283
9284\startnewprimitive[title={\prm {pxdimen}}]
9285
9286The current numeric value of this dimension is \tointeger \pxdimen, \todimension
9287\pxdimen: one \type {bp}. We kept it around because it was introduced in \PDFTEX\
9288and made it into \LUATEX, where it relates to the resolution of included images.
9289In \CONTEXT\ it is not used.
9290
9291\stopnewprimitive
9292
9293\startnewprimitive[title={\prm {quitloop}}]
9294
9295There are several loop primitives and they can be quit with \prm {quitloop} at
9296the next the {\em next} iteration. An immediate quit is possible with \prm
9297{quitloopnow}. An example is given with \prm {localcontrolledloop}.
9298
9299\stopnewprimitive
9300
9301\startnewprimitive[title={\prm {quitloopnow}}]
9302
9303There are several loop primitives and they can be quit with \prm {quitloopnow}
9304at the spot.
9305
9306\stopnewprimitive
9307
9308\startnewprimitive[title={\prm {quitvmode}}]
9309
9310This primitive forces horizontal mode but has no side effects when were already
9311in that mode.
9312
9313\stopnewprimitive
9314
9315\startoldprimitive[title={\prm {radical}}][obsolete=yes]
9316
9317This old school radical constructor is replaced by \prm {Uradical}. It takes a
9318number where the first byte is the small family, the next two index of this
9319symbol from that family, and the next three the family and index of the first
9320larger variant.
9321
9322\stopoldprimitive
9323
9324\startoldprimitive[title={\prm {raise}}]
9325
9326This primitive takes two arguments, a dimension and a box. The box is moved up.
9327The operation only succeeds in horizontal mode.
9328
9329\stopoldprimitive
9330
9331\startnewprimitive[title={\prm {rdivide}}]
9332
9333This is variant of \prm {divide} that rounds the result. For integers the result
9334is the same as \prm {edivide}.
9335
9336\startbuffer
9337\the\dimexpr .4999pt : 2 \relax =.24994pt
9338\the\dimexpr .4999pt 2 \relax =.24995pt
9339\scratchdimen.4999pt \divide \scratchdimen 2 \the\scratchdimen =.24994pt
9340\scratchdimen.4999pt \edivide\scratchdimen 2 \the\scratchdimen =.24995pt
9341\scratchdimen 4999pt \rdivide\scratchdimen 2 \the\scratchdimen =2500.0pt
9342\scratchdimen 5000pt \rdivide\scratchdimen 2 \the\scratchdimen =2500.0pt
9343
9344\the\numexpr 1001 : 2 \relax =500
9345\the\numexpr 1001 2 \relax =501
9346\scratchcounter1001 \divide \scratchcounter 2 \the\scratchcounter=500
9347\scratchcounter1001 \edivide\scratchcounter 2 \the\scratchcounter=501
9348\scratchcounter1001 \rdivide\scratchcounter 2 \the\scratchcounter=501
9349\stopbuffer
9350
9351\typebuffer
9352
9353\startlines
9354\getbuffer
9355\stoplines
9356
9357\stopnewprimitive
9358
9359\startnewprimitive[title={\prm {rdivideby}}]
9360
9361This is the \type {by}less companion to \prm {rdivide}.
9362
9363\stopnewprimitive
9364
9365\startoldprimitive[title={\prm {relax}}]
9366
9367This primitive does nothing and is often used to end a verbose number or
9368dimension in a comparison, for example:
9369
9370\starttyping
9371\ifnum \scratchcounter = 123\relax
9372\stoptyping
9373
9374which prevents a lookahead. A variant would be:
9375
9376\starttyping
9377\ifnum \scratchcounter = 123
9378\stoptyping
9379
9380assuming that spaces are not ignored. Another application is finishing
9381an expression like \prm {numexpr} or \prm {dimexpr}. I is also used
9382to prevent lookahead in cases like:
9383
9384\starttyping
9385\vrule height 3pt depth 2pt width 5pt\relax
9386\hskip 5pt plus 3pt minus 2pt\relax
9387\stoptyping
9388
9389Because \prm {relax} is not expandable the following:
9390
9391\startbuffer
9392\edef\foo{\relax} \meaningfull\foo
9393\edef\oof{\norelax} \meaningfull\oof
9394\stopbuffer
9395
9396\typebuffer
9397
9398gives this:
9399
9400\startlines
9401\getbuffer
9402\stoplines
9403
9404A \prm {norelax} disappears here but in the previously mentioned scenarios
9405it has the same function as \prm {relax}. It will not be pushed back either
9406in cases where a lookahead demands that.
9407
9408\stopoldprimitive
9409
9410\startoldprimitive[title={\prm {relpenalty}}]
9411
9412This internal quantity is a compatibility feature because normally we will use
9413the inter atom spacing variables.
9414
9415\stopoldprimitive
9416
9417
9418
9419
9420\startnewprimitive[title={\prm {retained}}]
9421
9422When a value is assigned inside a group \TEX\ pushes the current value on the save
9423stack in order to be able to restore the original value after the group has ended. You
9424can reach over a group by using the \prm {global} prefix. A mix between local and
9425global assignments can be achieved with the \prm {retained} primitive.
9426
9427\newdimension\MyDim
9428
9429\startbuffer[one]
9430\MyDim 15pt \bgroup \the\MyDim \space
9431\bgroup
9432 \bgroup
9433 \bgroup \advance\MyDim10pt \the\MyDim \egroup\space
9434 \bgroup \advance\MyDim10pt \the\MyDim \egroup\space
9435 \egroup
9436 \bgroup
9437 \bgroup \advance\MyDim10pt \the\MyDim \egroup\space
9438 \bgroup \advance\MyDim10pt \the\MyDim \egroup\space
9439 \egroup
9440\egroup
9441\egroup \the\MyDim
9442\stopbuffer
9443
9444\startbuffer[two]
9445\MyDim 15pt \bgroup \the\MyDim \space
9446\bgroup
9447 \bgroup
9448 \bgroup \global\advance\MyDim10pt \the\MyDim \egroup\space
9449 \bgroup \global\advance\MyDim10pt \the\MyDim \egroup\space
9450 \egroup
9451 \bgroup
9452 \bgroup \global\advance\MyDim10pt \the\MyDim \egroup\space
9453 \bgroup \global\advance\MyDim10pt \the\MyDim \egroup\space
9454 \egroup
9455\egroup
9456\egroup \the\MyDim
9457\stopbuffer
9458
9459\startbuffer[three]
9460\MyDim 15pt \bgroup \the\MyDim \space
9461 \constrained\MyDim\zeropoint
9462 \bgroup
9463 \bgroup \retained\advance\MyDim10pt \the\MyDim \egroup\space
9464 \bgroup \retained\advance\MyDim10pt \the\MyDim \egroup\space
9465 \egroup
9466 \bgroup
9467 \bgroup \retained\advance\MyDim10pt \the\MyDim \egroup\space
9468 \bgroup \retained\advance\MyDim10pt \the\MyDim \egroup\space
9469 \egroup
9470\egroup \the\MyDim
9471\stopbuffer
9472
9473\typebuffer[one,two,three]
9474
9475These lines result in:
9476
9477\startlines
9478\hbox{\getbuffer[one]}
9479\hbox{\getbuffer[two]}
9480\hbox{\getbuffer[three]}
9481\stoplines
9482
9483Because \LUAMETATEX\ avoids redundant stack entries and reassignments this
9484mechanism is a bit fragile but the \prm {constrained} prefix makes sure that we
9485do have a stack entry. If it is needed depends on the usage pattern.
9486
9487\stopnewprimitive
9488
9489\startnewprimitive[title={\prm {retokenized}}]
9490
9491This is a companion of \prm {tokenized} that accepts a catcode table, so the
9492whole repertoire is:
9493
9494\startbuffer
9495\tokenized {test $x$ test: current}
9496\tokenized catcodetable \ctxcatcodes {test $x$ test: context}
9497\tokenized catcodetable \vrbcatcodes {test $x$ test: verbatim}
9498\retokenized \ctxcatcodes {test $x$ test: context}
9499\retokenized \vrbcatcodes {test $x$ test: verbatim}
9500\stopbuffer
9501
9502\typebuffer
9503
9504Here we pass the numbers known to \CONTEXT\ and get:
9505
9506\startlines
9507\getbuffer
9508\stoplines
9509
9510\stopnewprimitive
9511
9512\startoldprimitive[title={\prm {right}}]
9513
9514Inserts the given delimiter as right fence in a math formula.
9515
9516\stopoldprimitive
9517
9518\startoldprimitive[title={\prm {righthyphenmin}}]
9519
9520This is the minimum number of characters before the first hyphen in a hyphenated
9521word.
9522
9523\stopoldprimitive
9524
9525\startnewprimitive[title={\prm {rightmarginkern}}]
9526
9527The dimension returned is the protrusion kern that has been added (if at all) to
9528the left of the content in the given box.
9529
9530\stopnewprimitive
9531
9532\startoldprimitive[title={\prm {rightskip}}]
9533
9534This skip will be inserted at the right of every line.
9535
9536\stopoldprimitive
9537
9538\startoldprimitive[title={\prm {romannumeral}}]
9539
9540This converts a number into a sequence of characters representing a roman
9541numeral. Because the Romans had no zero, a zero will give no output, a fact that
9542is sometimes used for hacks and showing off ones macro coding capabilities. A
9543large number will for sure result in a long string because after thousand we
9544start duplicating.
9545
9546\stopoldprimitive
9547
9548\startnewprimitive[title={\prm {rpcode}}]
9549
9550This is the companion of \prm {lpcode} (see there) and also takes three
9551arguments: font, character code and factor.
9552
9553\stopnewprimitive
9554
9555\startnewprimitive[title={\prm {savecatcodetable}}]
9556
9557This primitive stores the currently set catcodes in the current table.
9558
9559\stopnewprimitive
9560
9561\startoldprimitive[title={\prm {savinghyphcodes}}]
9562
9563When set to nonzero, this will trigger the setting of \prm {hjcode}s from \prm
9564{lccode}s for the current font. These codes determine what characters are taken
9565into account when hyphenating words.
9566
9567\stopoldprimitive
9568
9569\startoldprimitive[title={\prm {savingvdiscards}}]
9570
9571When set to a positive value the page builder will store the discarded items
9572(like glues) so that they can later be retrieved and pushed back if needed with
9573\prm {pagediscards} or \prm {splitdiscards}.
9574
9575\stopoldprimitive
9576
9577\startnewprimitive[title={\prm {scaledemwidth}}]
9578
9579Returns the current (font specific) emwidth scaled according to \prm {glyphscale}
9580and \prm {glyphxscale}.
9581
9582\stopnewprimitive
9583
9584\startnewprimitive[title={\prm {scaledexheight}}]
9585
9586Returns the current (font specific) exheight scaled according to \prm {glyphscale}
9587and \prm {glyphyscale}.
9588
9589\stopnewprimitive
9590
9591\startnewprimitive[title={\prm {scaledextraspace}}]
9592
9593Returns the current (font specific) extra space value scaled according to \prm
9594{glyphscale} and \prm {glyphxscale}.
9595
9596\stopnewprimitive
9597
9598\startnewprimitive[title={\prm {scaledfontcharba}}]
9599
9600Returns the bottom accent position of the given fontcharacter pair scaled
9601according to \prm {glyphscale} and \prm {glyphyscale}.
9602
9603\stopnewprimitive
9604
9605\startnewprimitive[title={\prm {scaledfontchardp}}]
9606
9607Returns the depth of the given fontcharacter pair scaled according to \prm
9608{glyphscale} and \prm {glyphyscale}.
9609
9610\stopnewprimitive
9611
9612\startnewprimitive[title={\prm {scaledfontcharht}}]
9613
9614Returns the height of the given fontcharacter pair scaled according to \prm
9615{glyphscale} and \prm {glyphyscale}.
9616
9617\stopnewprimitive
9618
9619\startnewprimitive[title={\prm {scaledfontcharic}}]
9620
9621Returns the italic correction of the given fontcharacter pair scaled according
9622to \prm {glyphscale} and \prm {glyphxscale}. This property is only real for
9623traditional fonts.
9624
9625\stopnewprimitive
9626
9627\startnewprimitive[title={\prm {scaledfontcharta}}]
9628
9629Returns the top accent position of the given fontcharacter pair scaled
9630according to \prm {glyphscale} and \prm {glyphxscale}.
9631
9632\stopnewprimitive
9633
9634\startnewprimitive[title={\prm {scaledfontcharwd}}]
9635
9636Returns width of the given fontcharacter pair scaled according to \prm
9637{glyphscale} and \prm {glyphxscale}.
9638
9639\stopnewprimitive
9640
9641\startnewprimitive[title={\prm {scaledfontdimen}}]
9642
9643Returns value of a (numeric) font dimension of the given fontcharacter pair
9644scaled according to \prm {glyphscale} and \prm {glyphxscale} andor \prm
9645{glyphyscale}.
9646
9647\stopnewprimitive
9648
9649\startnewprimitive[title={\prm {scaledinterwordshrink}}]
9650
9651Returns the current (font specific) shrink of a space value scaled according to
9652\prm {glyphscale} and \prm {glyphxscale}.
9653
9654\stopnewprimitive
9655
9656\startnewprimitive[title={\prm {scaledinterwordspace}}]
9657
9658Returns the current (font specific) space value scaled according to \prm
9659{glyphscale} and \prm {glyphxscale}.
9660
9661\stopnewprimitive
9662
9663\startnewprimitive[title={\prm {scaledinterwordstretch}}]
9664
9665Returns the current (font specific) stretch of a space value scaled according to
9666\prm {glyphscale} and \prm {glyphxscale}.
9667
9668\stopnewprimitive
9669
9670\startnewprimitive[title={\prm {scaledmathaxis}}]
9671
9672This primitive returns the math axis of the given math style. Its a dimension.
9673
9674\stopnewprimitive
9675
9676\startnewprimitive[title={\prm {scaledmathemwidth}}]
9677
9678Returns the emwidth of the given style scaled according to \prm {glyphscale} and
9679\prm {glyphxscale}.
9680
9681\stopnewprimitive
9682
9683\startnewprimitive[title={\prm {scaledmathexheight}}]
9684
9685Returns the exheight of the given style scaled according to \prm {glyphscale} and
9686\prm {glyphyscale}.
9687
9688\stopnewprimitive
9689
9690\startnewprimitive[title={\prm {scaledmathstyle}}]
9691
9692This command inserts a signal in the math list that tells how to scale the (upcoming)
9693part of the formula.
9694
9695\startbuffer
9696$ x {\scaledmathstyle900 x} x$
9697\stopbuffer
9698
9699\typebuffer
9700
9701We get: \inlinebuffer. Of course using this properly demands integration in the macro
9702packages font system.
9703
9704\stopnewprimitive
9705
9706\startnewprimitive[title={\prm {scaledslantperpoint}}]
9707
9708This primitive is equivalent to \typ {\scaledfontdimen1\font} where \quote
9709{scaled} means that we multiply by the glyph scales.
9710
9711\stopnewprimitive
9712
9713\startnewprimitive[title={\prm {scantextokens}}]
9714
9715This primitive scans the input as if it comes from a file. In the next examples
9716the \prm {detokenize} primitive turns tokenized code into verbatim code that is
9717similar to what is read from a file.
9718
9719\startbuffer
9720\edef\whatever{\detokenize{This is {\bf bold} and this is not.}}
9721\detokenize {This is {\bf bold} and this is not.}\crlf
9722\scantextokens{This is {\bf bold} and this is not.}\crlf
9723\scantextokens{\whatever}\crlf
9724\scantextokens\expandafter{\whatever}\par
9725\stopbuffer
9726
9727\typebuffer
9728
9729This primitive does not have the endoffile side effects of its precursor
9730\prm {scantokens}.
9731
9732{\getbuffer}
9733
9734\stopnewprimitive
9735
9736\startoldprimitive[title={\prm {scantokens}}]
9737
9738Just forget about this \ETEX\ primitive, just take the one in the next section.
9739
9740\stopoldprimitive
9741
9742\startoldprimitive[title={\prm {scriptfont}}]
9743
9744This primitive is like \prm {font} but with a family number as (first) argument
9745so it is specific for math. It is the middle one of the three family members; its
9746relatives are \prm {textfont} and \prm {scriptscriptfont}.
9747
9748\stopoldprimitive
9749
9750\startoldprimitive[title={\prm {scriptscriptfont}}]
9751
9752This primitive is like \prm {font} but with a family number as (first) argument
9753so it is specific for math. It is the smallest of the three family members; its
9754relatives are \prm {textfont} and \prm {scriptfont}.
9755
9756\stopoldprimitive
9757
9758\startoldprimitive[title={\prm {scriptscriptstyle}}]
9759
9760One of the main math styles, normally one size smaller than \prm {scriptstyle}:
9761integer representation: \the\scriptscriptstyle.
9762
9763\stopoldprimitive
9764
9765\startoldprimitive[title={\prm {scriptspace}}]
9766
9767The math engine will add this amount of space after subscripts and superscripts.
9768It can be seen as compensation for the often too small widths of characters (in
9769the traditional engine italic correction is used too). It prevents scripts from
9770running into what follows.
9771
9772\stopoldprimitive
9773
9774\startoldprimitive[title={\prm {scriptstyle}}]
9775
9776One of the main math styles, normally one size smaller than \prm {displaystyle}
9777and \prm {textstyle}; integer representation: \the\scriptstyle.
9778
9779\stopoldprimitive
9780
9781\startoldprimitive[title={\prm {scrollmode}}]
9782
9783 This directive omits error stops.
9784
9785\stopoldprimitive
9786
9787\startnewprimitive[title={\prm {semiexpand}}]
9788
9789This command expands the next macro when it is protected with \prm
9790{semprotected}. See that primitive there for an example.
9791
9792\stopnewprimitive
9793
9794\startnewprimitive[title={\prm {semiexpanded}}]
9795
9796This command expands the tokens in the given list including the macros protected
9797by with \prm {semprotected}. See that primitive there for an example.
9798
9799\stopnewprimitive
9800
9801\startnewprimitive[title={\prm {semiprotected}}]
9802
9803\startbuffer
9804 \def\TestA{A}
9805\semiprotected\def\TestB{B}
9806 \protected\def\TestC{C}
9807
9808\edef\TestD{\TestA \TestB \TestC}
9809\edef\TestE{\TestA\semiexpand\TestB\semiexpand\TestC}
9810\edef\TestF{\TestA\expand \TestB\expand \TestC}
9811
9812\edef\TestG{\normalexpanded {\TestA\TestB\TestC}}
9813\edef\TestH{\normalsemiexpanded{\TestA\TestB\TestC}}
9814\stopbuffer
9815
9816The working of this prefix can best be explained with an example. We define a few
9817macros first:
9818
9819\typebuffer \getbuffer
9820
9821The meaning of the macros that are made from the other three are:
9822
9823\startbuffer
9824\meaningless\TestD
9825\meaningless\TestE
9826\meaningless\TestF
9827\meaningless\TestG
9828\meaningless\TestH
9829\stopbuffer
9830
9831Here we use the \type {\normal..} variants because (currently) we still have the
9832macro with the \type {\expanded} in the \CONTEXT\ core.
9833
9834\startlines \tttf \getbuffer \stoplines
9835
9836\stopnewprimitive
9837
9838\startoldprimitive[title={\prm {setbox}}]
9839
9840This important primitive is used to set a box register. It expects a number and a
9841box, like \prm {hbox} or \prm {box}. There is no \type {\boxdef} primitive
9842(analogue to other registers) because it makes no sense but numeric registers or
9843equivalents are okay as register value.
9844
9845\stopoldprimitive
9846
9847
9848
9849
9850\startnewprimitive[title={\prm {setfontid}}]
9851
9852Internally a font instance has a number and this number is what gets assigned to
9853a glyph node. You can get the number with \prm {fontid} an set it with \prm
9854{setfontid}.
9855
9856\starttyping
9857\setfontid\fontid\font
9858\stoptyping
9859
9860The code above shows both primitives and effectively does nothing useful but
9861shows the idea.
9862
9863\stopnewprimitive
9864
9865\startoldprimitive[title={\prm {setlanguage}}]
9866
9867In \LUATEX\ and \LUAMETATEX\ this is equivalent to \prm {language} because we
9868carry the language in glyph nodes instead of putting triggers in the list.
9869
9870\stopoldprimitive
9871
9872\startnewprimitive[title={\prm {setmathatomrule}}]
9873
9874The math engine has some built in logic with respect to neighboring atoms that
9875change the class. The following combinations are intercepted and remapped:
9876
9877\starttabulate[cccc]
9878\BC old first \BC old second \NC new first \NC new second \NC \NR
9879\ML
9880\NC begin \NC binary \NC ordinary \NC ordinary \NC \NR
9881\NC \NC \NC \NC \NC \NR
9882\NC operator \NC binary \NC operator \NC ordinary \NC \NR
9883\NC open \NC binary \NC open \NC ordinary \NC \NR
9884\NC punctuation \NC binary \NC punctuation \NC ordinary \NC \NR
9885\NC \NC \NC \NC \NC \NR
9886\NC binary \NC end \NC ordinary \NC ordinary \NC \NR
9887\NC binary \NC binary \NC binary \NC ordinary \NC \NR
9888\NC binary \NC close \NC ordinary \NC close \NC \NR
9889\NC binary \NC punctuation \NC ordinary \NC punctuation \NC \NR
9890\NC binary \NC relation \NC ordinary \NC relation \NC \NR
9891\NC \NC \NC \NC \NC \NR
9892\NC relation \NC binary \NC relation \NC ordinary \NC \NR
9893\NC relation \NC close \NC ordinary \NC close \NC \NR
9894\NC relation \NC punctuation \NC ordinary \NC punctuation \NC \NR
9895\stoptabulate
9896
9897You can change this logic if needed, for instance:
9898
9899\starttyping
9900\setmathatomrule 1 2 \allmathstyles 1 1
9901\stoptyping
9902
9903Keep in mind that the defaults are what users expect. You might set them up for
9904additional classes that you define but even then you probably clone an existing
9905class and patch its properties. Most extra classes behave like ordinary anyway.
9906
9907\stopnewprimitive
9908
9909\startnewprimitive[title={\prm {setmathdisplaypostpenalty}}]
9910
9911This penalty is inserted after an item of a given class but only in inline math
9912when display style is used, for instance:
9913
9914\starttyping
9915\setmathdisplayprepenalty 2 750
9916\stoptyping
9917
9918\stopnewprimitive
9919
9920\startnewprimitive[title={\prm {setmathdisplayprepenalty}}]
9921
9922This penalty is inserted before an item of a given class but only in inline math
9923when display style is used, for instance:
9924
9925\starttyping
9926\setmathdisplayprepenalty 2 750
9927\stoptyping
9928
9929\stopnewprimitive
9930
9931\startnewprimitive[title={\prm {setmathignore}}]
9932
9933You can flag a math parameter to be ignored, like:
9934
9935\starttyping
9936\setmathignore \Umathxscale 2
9937\setmathignore \Umathyscale 2
9938\setmathignore \Umathspacebeforescript 1
9939\setmathignore \Umathspaceafterscript 1
9940\stoptyping
9941
9942A value of two will not initialize the variable, so its old value (when set) is
9943kept. This is somewhat experimental and more options might show up.
9944
9945\stopnewprimitive
9946
9947\startnewprimitive[title={\prm {setmathoptions}}]
9948
9949This primitive expects a class (number) and a bitset.
9950
9951\testpage[2]
9952
9953\startcolumns
9954\getbuffer[engine:syntax:mathcontrol]
9955\stopcolumns
9956
9957\stopnewprimitive
9958
9959\startnewprimitive[title={\prm {setmathpostpenalty}}]
9960
9961This penalty is inserted after an item of a given class but only in inline math
9962when text, script or scriptscript style is used, for instance:
9963
9964\starttyping
9965\setmathpostpenalty 2 250
9966\stoptyping
9967
9968\stopnewprimitive
9969
9970\startnewprimitive[title={\prm {setmathprepenalty}}]
9971
9972This penalty is inserted before an item of a given class but only in inline math
9973when text, script or scriptscript style is used, for instance:
9974
9975\starttyping
9976\setmathprepenalty 2 250
9977\stoptyping
9978
9979\stopnewprimitive
9980
9981
9982
9983
9984\startoldprimitive[title={\prm {sfcode}}]
9985
9986You can set a space factor on a character. That factor is used when a space
9987factor is applied (as part of spacing). It is (mostly) used for adding a
9988different space (glue) after punctuation. In some languages different punctuation
9989has different factors.
9990
9991\stopoldprimitive
9992
9993\startnewprimitive[title={\prm {shapingpenaltiesmode}}]
9994
9995Shaping penalties are inserted after the lines of a \prm {parshape} and
9996accumulate according to this mode, a bitset of:
9997
9998\getbuffer[engine:syntax:shapingpenaltiescodes]
9999
10000\stopnewprimitive
10001
10002\startnewprimitive[title={\prm {shapingpenalty}}]
10003
10004In order to prevent a \prm {parshape} to break in unexpected ways we can add a
10005dedicated penalty, specified by this parameter.
10006
10007\stopnewprimitive
10008
10009\startnewprimitive[title={\prm {shiftedsubprescript}}]
10010
10011This primitive (or \type {}) influences the alignment of scripts:
10012
10013\startbuffer
10014$
10015 x \shiftedsuperprescript{2} \subprescript {2}
10016 x \superprescript {2} \shiftedsubprescript{2}
10017 x \superprescript {2} {2} =
10018 x \superprescript {2} \subprescript {2}
10019$
10020\stopbuffer
10021
10022\typebuffer
10023
10024Gives: \inlinebuffer.
10025
10026\stopnewprimitive
10027
10028\startnewprimitive[title={\prm {shiftedsubscript}}]
10029
10030This primitive (or \type {}) influences the alignment of scripts:
10031
10032\startbuffer
10033$
10034 x \shiftedsuperscript{2} \subscript {2}
10035 x \superscript {2} \shiftedsubscript{2}
10036 x \superscript {2} {2} =
10037 x \superscript {2} \subscript {2}
10038$
10039\stopbuffer
10040
10041\typebuffer
10042
10043Gives: \inlinebuffer.
10044
10045\stopnewprimitive
10046
10047\startnewprimitive[title={\prm {shiftedsuperprescript}}]
10048
10049This primitive (or \type {}) influences the alignment of scripts:
10050
10051\startbuffer
10052$
10053 x \shiftedsuperprescript{2} \subprescript {2}
10054 x {2} \subprescript {2}
10055 x \superprescript {2} \shiftedsubprescript{2} =
10056 x \superprescript {2} \subprescript {2}
10057$
10058\stopbuffer
10059
10060\typebuffer
10061
10062Gives: \inlinebuffer.
10063
10064\stopnewprimitive
10065
10066\startnewprimitive[title={\prm {shiftedsuperscript}}]
10067
10068This primitive (or \type {}) influences the alignment of scripts:
10069
10070\startbuffer
10071$
10072 x \shiftedsuperscript{2} \subscript {2}
10073 x {2} \subscript {2}
10074 x \superscript {2} \shiftedsubscript{2} =
10075 x \superscript {2} \subscript {2}
10076$
10077\stopbuffer
10078
10079\typebuffer
10080
10081Gives: \inlinebuffer.
10082
10083\stopnewprimitive
10084
10085\startoldprimitive[title={\prm {shipout}}][obsolete=yes]
10086
10087Because there is no backend, this is not supposed to be used. As in traditional
10088\TEX\ a box is grabbed but instead of it being processed it gets shown and then
10089wiped. There is no real benefit of turning it into a callback.
10090
10091\stopoldprimitive
10092
10093\startnewprimitive[title={\prm {shortinlinemaththreshold}}]
10094
10095This parameter determines when an inline formula is considered to be short. This
10096criterium is used for for \prm {preshortinlinepenalty} and \prm
10097{postshortinlinepenalty}.
10098
10099\stopnewprimitive
10100
10101\startnewprimitive[title={\prm {shortinlineorphanpenalty}}]
10102
10103Short formulas at the end of a line are normally not followed by something other
10104than punctuation. This penalty will discourage a break before a short inline
10105formula. In practice one can set this penalty to e.g. a relatively low 200 to get
10106the desired effect.
10107
10108\stopnewprimitive
10109
10110\startoldprimitive[title={\prm {show}}]
10111
10112Prints to the console (andor log) what the token after
10113it represents.
10114
10115\stopoldprimitive
10116
10117\startoldprimitive[title={\prm {showbox}}]
10118
10119The given box register is shown in the log and on te console (depending on \prm
10120{tracingonline}. How much is shown depends on \prm {showboxdepth} and \prm
10121{showboxbreadth}. In \LUAMETATEX\ we show more detailed information than in the
10122other engines; some specific information is provided via callbacks.
10123
10124\stopoldprimitive
10125
10126\startoldprimitive[title={\prm {showboxbreadth}}]
10127
10128This primitives determine how much of a box is shown when asked for or when
10129tracing demands it.
10130
10131\stopoldprimitive
10132
10133\startoldprimitive[title={\prm {showboxdepth}}]
10134
10135This primitives determine how deep tracing a box goes into the box. Some boxes,
10136like the ones that has the assembled page.
10137
10138\stopoldprimitive
10139
10140\startoldprimitive[title={\prm {showgroups}}]
10141
10142This primitive reports the group nesting. At this spot we have a not so
10143impressive nesting:
10144
10145\starttyping
101462:3: simple group entered at line 9375:
101471:3: semisimple group: \begingroup
101480:3: bottomlevel
10149\stoptyping
10150
10151\stopoldprimitive
10152
10153\startoldprimitive[title={\prm {showifs}}]
10154
10155This primitive will show the conditional stack in the log file or on the console
10156(assuming \prm {tracingonline} being nonzero). The shown data is different
10157from other engines because we have more conditionals and also support a more flat
10158nesting model
10159
10160\stopoldprimitive
10161
10162\startoldprimitive[title={\prm {showlists}}]
10163
10164This shows the currently built list.
10165
10166\stopoldprimitive
10167
10168\startoldprimitive[title={\prm {shownodedetails}}]
10169
10170When set to a positive value more details will be shown of nodes when applicable.
10171Values larger than one will also report attributes. What gets shown depends on
10172related callbacks being set.
10173
10174\stopoldprimitive
10175
10176\startoldprimitive[title={\prm {showstack}}]
10177
10178This tracer is only useful for low level debugging of macros, for instance when
10179you run out of save space or when you encounter a performance hit.
10180
10181\starttyping
10182 test\scratchcounter0 \showstack
10183 {test\scratchcounter1 \showstack}
10184{{test\scratchcounter1 \showstack}}
10185\stoptyping
10186
10187reports
10188
10189\starttyping
101901:3: [savestack size 0]
101911:3: [savestack bottom]
10192
101932:3: [savestack size 2]
101942:3: [1: restore, level 1, cs \scratchcounter=integer 1]
101952:3: [0: boundary, group bottomlevel, boundary 0, attrlist 3600, line 0]
101962:3: [savestack bottom]
10197
101983:3: [savestack size 3]
101993:3: [2: restore, level 1, cs \scratchcounter=integer 1]
102003:3: [1: boundary, group simple, boundary 0, attrlist 3600, line 12]
102013:3: [0: boundary, group bottomlevel, boundary 0, attrlist 3600, line 0]
102023:3: [savestack bottom]
10203\stoptyping
10204
10205while
10206
10207\starttyping
10208 test\scratchcounter1 \showstack
10209 {test\scratchcounter1 \showstack}
10210{{test\scratchcounter1 \showstack}}
10211\stoptyping
10212
10213shows this:
10214
10215\starttyping
102161:3: [savestack size 0]
102171:3: [savestack bottom]
10218
102192:3: [savestack size 1]
102202:3: [0: boundary, group bottomlevel, boundary 0, attrlist 3600, line 0]
102212:3: [savestack bottom]
10222
102233:3: [savestack size 2]
102243:3: [1: boundary, group simple, boundary 0, attrlist 3600, line 16]
102253:3: [0: boundary, group bottomlevel, boundary 0, attrlist 3600, line 0]
102263:3: [savestack bottom]
10227\stoptyping
10228
10229Because in the second example the value of \type {\scratchcounter} doesnt really
10230change inside the group there is no need for a restore entry on the stack. In
10231\LUAMETATEX\ there are checks for that so that we consume less stack space. We
10232also store some states (like the line number and current attribute list pointer)
10233in a stack boundary.
10234
10235\stopoldprimitive
10236
10237\startoldprimitive[title={\prm {showthe}}]
10238
10239Prints to the console (andor log) the value of token after it.
10240
10241\stopoldprimitive
10242
10243\startoldprimitive[title={\prm {showtokens}}]
10244
10245This command expects a (balanced) token list, like
10246
10247\starttyping
10248\showtokens{a few tokens}
10249\stoptyping
10250
10251Depending on what you want to see you need to expand:
10252
10253\starttyping
10254\showtokens\expandafter{\the\everypar}
10255\stoptyping
10256
10257which is equivalent to \typ {\showthe \everypar}. It is an \ETEX\ extension.
10258
10259\stopoldprimitive
10260
10261\startnewprimitive[title={\prm {singlelinepenalty}}]
10262
10263This is a penalty that gets injected before a paragraph that has only one line.
10264It is a oneshot parameter, so like \prm {looseness} it only applies to the
10265upcoming (or current) paragraph.
10266
10267\stopnewprimitive
10268
10269\startoldprimitive[title={\prm {skewchar}}][obsolete=yes]
10270
10271This is an (imaginary) character that is used in math fonts. The kerning pair
10272between this character and the current one determines the top anchor of a
10273possible accent. In \OPENTYPE\ there is a dedicated character property for this
10274(but for some reason not for the bottom anchor).
10275
10276\stopoldprimitive
10277
10278\startoldprimitive[title={\prm {skip}}]
10279
10280This is the accessor for an indexed skip (glue) register.
10281
10282\stopoldprimitive
10283
10284\startoldprimitive[title={\prm {skipdef}}]
10285
10286This command associates a control sequence with a skip register (accessed by number).
10287
10288\stopoldprimitive
10289
10290\startnewprimitive[title={\prm {snapshotpar}}]
10291
10292There are many parameters involved in typesetting a paragraph. One complication
10293is that parameters set in the middle might have unpredictable consequences due to
10294grouping, think of:
10295
10296\starttyping
10297text text <some setting> text text \par
10298text {text <some setting> text } text \par
10299\stoptyping
10300
10301This makes in traditional \TEX\ because there is no state related to the current
10302paragraph. But in \LUATEX\ we have the initial so called par node that remembers
10303the direction as well as local boxes. In \LUAMETATEX\ we store way more when this
10304node is created. That means that later settings no longer replace the stored ones.
10305
10306The \prm {snapshotpar} takes a bitset that determine what stored parameters get
10307updated to the current values.
10308
10309\startcolumns[n=3]
10310\getbuffer[engine:syntax:frozenparcodes]
10311\stopcolumns
10312
10313One such value covers multiple values, so for instance \type {skip} is good for
10314storing the current \prm {leftskip} and \prm {rightskip} values. More about this
10315feature can be found in the \CONTEXT\ documentation.
10316
10317The list of parameters that gets reset after a paragraph is longer than for
10318\PDFTEX\ and \LUAMETATEX: \prm {emergencyleftskip}, \prm {emergencyrightskip}, \prm
10319{hangafter}, \prm {hangindent}, \prm {interlinepenalties}, \prm
10320{localbrokenpenalty}, \prm {localinterlinepenalty}, \prm {localpretolerance},
10321\prm {localtolerance}, \prm {looseness}, \prm {parshape} and \prm
10322{singlelinepenalty}.
10323
10324\stopnewprimitive
10325
10326\startoldprimitive[title={\prm {spacefactor}}]
10327
10328The space factor is a somewhat complex feature. When during scanning a character
10329is appended that has a \prm {sfcode} other than 1000, that value is saved. When
10330the time comes to insert a space triggered glue, and that factor is 2000 or more,
10331and when \prm {xspaceskip} is nonzero, that value is used and were done.
10332
10333If these criteria are not met, and \prm {spaceskip} is nonzero, that value is
10334used, otherwise the space value from the font is used. Now, it if the space factor
10335is larger than 2000 the extra space value from the font is added to the set value.
10336Next the engine is going to tweak the stretch and shrink if that value and in
10337\LUAMETATEX\ that can be done in different ways, depending on \prm {spacefactormode},
10338\prm {spacefactorstretchlimit} and \prm {spacefactorshrinklimit}.
10339
10340First the stretch. When the set limit is 1000 or more and the saved space factor
10341is also 1000 or more, we multiply the stretch by the limit, otherwise the saved
10342space factor is used.
10343
10344Shrink is done differently. When the shrink limit and space factor are both 1000
10345or more, we will scale the shrink component by the limit, otherwise we multiply
10346by the saved space factor but here we have three variants, determined by the
10347value of \prm {spacefactormode}.
10348
10349In the first case, when the limit kicks in, a mode value1 will multiply by limit
10350and divides by 1000. A value of2 multiplies by 2000 and divides by the limit.
10351Other mode values multiply by 1000 and divide by the limit. When the limit is not
10352used, the same happens but with the saved space factor.
10353
10354If this sounds complicated, here is what regular \TEX\ does: stretch is
10355multiplied by the factor and divided by 1000 while shrink is multiplied by 1000
10356and divided by the saved factor. The (new) mode driven alternatives are the
10357result of extensive experiments done in the perspective of enhancing the
10358rendering of inline math as well as additional par builder passes. For sure
10359alternative strategies are possible and we can always add more modes.
10360
10361A better explanation of the default strategy around spaces can be found in (of
10362course) The \TEX book and \TEX\ by Topic.
10363
10364\stopoldprimitive
10365
10366\startnewprimitive[title={\prm {spacefactormode}}]
10367
10368Its setting determines the way the glue components (currently only shrink) adapts
10369itself to the current space factor (determined by by the character preceding a
10370space).
10371
10372\stopnewprimitive
10373
10374\startnewprimitive[title={\prm {spacefactorshrinklimit}}]
10375
10376This limit is used when \prm {spacefactormode} is set. See \prm {spacefactor} for a
10377bit more explanation.
10378
10379\stopnewprimitive
10380
10381\startnewprimitive[title={\prm {spacefactorstretchlimit}}]
10382
10383This limit is used when \prm {spacefactormode} is set. See \prm {spacefactor} for a
10384bit more explanation.
10385
10386\stopnewprimitive
10387
10388\startoldprimitive[title={\prm {spaceskip}}]
10389
10390Normally the glue inserted when a space is encountered is taken from the font but
10391this parameter can overrule that.
10392
10393\stopoldprimitive
10394
10395\startoldprimitive[title={\prm {span}}]
10396
10397This primitive combined two upcoming cells into one. Often it is used in combination with
10398\prm {omit}.
10399
10400\stopoldprimitive
10401
10402\startoldprimitive[title={\prm {splitbotmark}}][obsolete=yes]
10403
10404This is a reference to the last mark on the currently split off box, it gives
10405back tokens.
10406
10407\stopoldprimitive
10408
10409\startoldprimitive[title={\prm {splitbotmarks}}]
10410
10411This is a reference to the last mark with the given id (a number) on the
10412currently split off box, it gives back tokens.
10413
10414\stopoldprimitive
10415
10416\startoldprimitive[title={\prm {splitdiscards}}]
10417
10418When a box is split off, items like glue are discarded. This internal register
10419keeps the that list so that it can be pushed back if needed.
10420
10421\stopoldprimitive
10422
10423\startoldprimitive[title={\prm {splitfirstmark}}][obsolete=yes]
10424
10425This is a reference to the first mark on the currently split off box, it gives
10426back tokens.
10427
10428\stopoldprimitive
10429
10430\startoldprimitive[title={\prm {splitfirstmarks}}]
10431
10432This is a reference to the first mark with the given id (a number) on the
10433currently split off box, it gives back tokens.
10434
10435\stopoldprimitive
10436
10437\startoldprimitive[title={\prm {splitmaxdepth}}]
10438
10439The depth of the box that results from a \prm {vsplit}.
10440
10441\stopoldprimitive
10442
10443\startoldprimitive[title={\prm {splittopskip}}]
10444
10445This is the amount of glue that is added to the top of a (new) split of part of a
10446box when \prm {vsplit} is applied.
10447
10448\stopoldprimitive
10449
10450\startnewprimitive[title={\prm {srule}}]
10451
10452This inserts a rule with no width. When a \type {font} and a \type {char} are
10453given the height and depth of that character are taken. Instead of a font \type
10454{fam} is also accepted so that we can use it in math mode.
10455
10456\stopnewprimitive
10457
10458\startoldprimitive[title={\prm {string}}]
10459
10460We mention this original primitive because of the one in the next section. It
10461expands the next token or control sequence as if it was just entered, so normally
10462a control sequence becomes a backslash followed by characters and a space.
10463
10464\stopoldprimitive
10465
10466\startnewprimitive[title={\prm {subprescript}}]
10467
10468Instead of two characters with catcode \the\subscriptcatcode\ (like \type {})
10469this primitive can be used. It will add the following argument as lower left
10470script to the nucleus.
10471
10472\stopnewprimitive
10473
10474\startnewprimitive[title={\prm {subscript}}]
10475
10476Instead of a character with catcode \the\subscriptcatcode\ (normally \type {})
10477this primitive can be used. It will add the following argument as lower right
10478script to the nucleus.
10479
10480\stopnewprimitive
10481
10482\startnewprimitive[title={\prm {superprescript}}]
10483
10484Instead of two characters with catcode \the\superscriptcatcode\ (like \type {})
10485this primitive can be used. It will add the following argument as upper left
10486script to the nucleus.
10487
10488\stopnewprimitive
10489
10490\startnewprimitive[title={\prm {superscript}}]
10491
10492Instead of a character with catcode \the\superscriptcatcode\ (normally \type {})
10493this primitive can be used. It will add the following argument as upper right
10494script to the nucleus.
10495
10496\stopnewprimitive
10497
10498\startnewprimitive[title={\prm {supmarkmode}}]
10499
10500As in other languages, \TEX\ has ways to escape characters and get whatever
10501character needed into the input. By default multiple \type {} are used for this.
10502The dual \type {} variant is a bit weird as it is not continuous but \type
10503{} and \type {} provide four or six byte hexadecimal references ot
10504characters. The single \type {} is also used for superscripts but because we
10505support prescripts and indices we get into conflicts with the escapes.
10506
10507When this internal quantity is set to zero, multiple \type {}s are interpreted
10508in the input and produce characters. Other values disable the multiple parsing in
10509text andor math mode:
10510
10511\startbuffer
10512\normalsupmarkmode0 $ X58 \quad X58 $ 58
10513\normalsupmarkmode1 $ X58 \quad X58 $ 58
10514\normalsupmarkmode2 $ X58 \quad X58 $
10515\stopbuffer
10516
10517\typebuffer
10518
10519In \CONTEXT\ we default to one but also have the \prm {catcode} set to \the
10520\catcode and the \prm {amcode} to \the \amcode .
10521
10522\startlines
10523\catcode=\superscriptcatcode
10524\amcode =\superscriptcatcode
10525\getbuffer
10526\stoplines
10527
10528\stopnewprimitive
10529
10530\startnewprimitive[title={\prm {swapcsvalues}}]
10531
10532Because we mention some \type {def} and \type {let} primitives here, it makes
10533sense to also mention a primitive that will swap two values (meanings). This one
10534has to be used with care. Of course that what gets swapped has to be of the same
10535type (or at least similar enough not to cause issues). Registers for instance
10536store their values in the token, but as soon as we are dealing with token lists
10537we also need to keep an eye on reference counting. So, to some extend this is
10538an experimental feature.
10539
10540\stopnewprimitive
10541
10542\startnewprimitive[title={\prm {tabsize}}]
10543
10544This primitive can be used in the preamble of an alignment and sets the size of
10545a column, as in:
10546
10547\startbuffer
10548\halign{
10549 \aligncontent \aligntab
10550 \aligncontent\tabsize 3cm \aligntab
10551 \aligncontent \aligntab
10552 \aligncontent\tabsize 0cm \cr
10553 1 \aligntab 111\aligntab 1111\aligntab 11\cr
10554 222\aligntab 2 \aligntab 2222\aligntab 22\cr
10555}
10556\stopbuffer
10557
10558\typebuffer
10559
10560As with \prm {tabskip} you need to reset the value explicitly, so that is why we
10561get two wide columns:
10562
10563\blank {\showboxes \getbuffer} \blank
10564
10565\stopnewprimitive
10566
10567\startoldprimitive[title={\prm {tabskip}}]
10568
10569This traditional primitive can be used in the preamble of an alignment and sets the
10570space added between columns, for example:
10571
10572\startbuffer
10573\halign{
10574 \aligncontent \aligntab
10575 \aligncontent\tabskip 3cm \aligntab
10576 \aligncontent \aligntab
10577 \aligncontent\tabskip 0cm \cr
10578 1 \aligntab 111\aligntab 1111\aligntab 11\cr
10579 222\aligntab 2 \aligntab 2222\aligntab 22\cr
10580}
10581\stopbuffer
10582
10583\typebuffer
10584
10585You need to reset the skip explicitly, which is why we get it applied twice here:
10586
10587\blank {\showboxes \getbuffer} \blank
10588
10589\stopoldprimitive
10590
10591\startnewprimitive[title={\prm {textdirection}}]
10592
10593This set the text direction to \type {l2r} (0) or \type {r2l} (1). It also
10594triggers additional checking for balanced flipping in node lists.
10595
10596\stopnewprimitive
10597
10598\startoldprimitive[title={\prm {textfont}}]
10599
10600This primitive is like \prm {font} but with a family number as (first) argument
10601so it is specific for math. It is the largest one of the three family members; its
10602relatives are \prm {scriptfont} and \prm {scriptscriptfont}.
10603
10604\stopoldprimitive
10605
10606\startoldprimitive[title={\prm {textstyle}}]
10607
10608One of the main math styles; integer representation: \the\textstyle.
10609
10610\stopoldprimitive
10611
10612\startoldprimitive[title={\prm {the}}]
10613
10614The \prm {the} primitive serializes the following token, when applicable:
10615integers, dimensions, token registers, special quantities, etc. The catcodes of
10616the result will be according to the current settings, so in \type {\the \dimen0},
10617the \type {pt} will have catcode \quote {letter} and the number and period will
10618become \quote {other}.
10619
10620\stopoldprimitive
10621
10622\startnewprimitive[title={\prm {thewithoutunit}}]
10623
10624The \prm{the} primitive, when applied to a dimension variable, adds a \type {pt}
10625unit. because dimensions are the only traditional unit with a fractional part
10626they are sometimes used as pseudo floats in which case \prm {thewithoutunit} can
10627be used to avoid the unit. This is more convenient than stripping it off
10628afterwards (via an expandable macro).
10629
10630\stopnewprimitive
10631
10632\startoldprimitive[title={\prm {thickmuskip}}]
10633
10634A predefined mu skip register that can be used in math (inter atom) spacing. The
10635current value is {\tt \the\thickmuskip}. In traditional \TEX\ most inter atom
10636spacing is hard coded using the predefined registers.
10637
10638\stopoldprimitive
10639
10640\startoldprimitive[title={\prm {thinmuskip}}]
10641
10642A predefined mu skip register that can be used in math (inter atom) spacing. The
10643current value is {\tt \the\thinmuskip}. In traditional \TEX\ most inter atom
10644spacing is hard coded using the predefined registers.
10645
10646\stopoldprimitive
10647
10648\startoldprimitive[title={\prm {time}}]
10649
10650This internal number starts out with minute (starting at midnight) that the job
10651started.
10652
10653\stopoldprimitive
10654
10655\startnewprimitive[title={\prm {tinymuskip}}]
10656
10657A predefined mu skip register that can be used in math (inter atom) spacing. The
10658current value is {\tt \the\tinymuskip}. This one complements \prm {thinmuskip},
10659\prm {medmuskip}, \prm {thickmuskip} and the new \prm {pettymuskip}
10660
10661\stopnewprimitive
10662
10663\startnewprimitive[title={\prm {tocharacter}}]
10664
10665The given number is converted into an \UTF8 sequence. In \LUATEX\ this one is
10666named \type {\Uchar}.
10667
10668\stopnewprimitive
10669
10670\startnewprimitive[title={\prm {todimension}}]
10671
10672\startbuffer
10673\scratchdimen = 1234pt \todimension\scratchdimen
10674\stopbuffer
10675
10676The following code gives this: {\nospacing\inlinebuffer} and like its numeric
10677counterparts accepts anything that resembles a number this one goes beyond
10678(user, internal or pseudo) registers values too.
10679
10680\typebuffer
10681
10682\stopnewprimitive
10683
10684\startnewprimitive[title={\prm {tohexadecimal}}]
10685
10686\startbuffer
10687\scratchcounter = 1234 \tohexadecimal\scratchcounter
10688\stopbuffer
10689
10690The following code gives this: {\nospacing\inlinebuffer} with uppercase letters.
10691
10692\typebuffer
10693
10694\stopnewprimitive
10695
10696\startnewprimitive[title={\prm {tointeger}}]
10697
10698\startbuffer
10699\scratchcounter = 1234 \tointeger\scratchcounter
10700\stopbuffer
10701
10702The following code gives this: {\nospacing\inlinebuffer} and is equivalent to
10703\prm {number}.
10704
10705\typebuffer
10706
10707\stopnewprimitive
10708
10709\startnewprimitive[title={\prm {tokenized}}]
10710
10711Just as \prm {expanded} has a counterpart \prm {unexpanded}, it makes sense to give
10712\prm {detokenize} a companion:
10713
10714\startbuffer
10715\edef\foo{\detokenize{\inframed{foo}}}
10716\edef\oof{\detokenize{\inframed{oof}}}
10717
10718\meaning\foo \crlf \dontleavehmode\foo
10719
10720\edef\foo{\tokenized{\foo\foo}}
10721
10722\meaning\foo \crlf \dontleavehmode\foo
10723
10724\dontleavehmode\tokenized{\foo\oof}
10725\stopbuffer
10726
10727\typebuffer {\tttf \getbuffer}
10728
10729This primitive is similar to:
10730
10731\starttyping
10732\def\tokenized#1{\scantextokens\expandafter{\normalexpanded{#1}}}
10733\stoptyping
10734
10735and should be more efficient, not that it matters much as we dont use it that
10736much (if at all).
10737
10738\stopnewprimitive
10739
10740\startoldprimitive[title={\prm {toks}}]
10741
10742This is the accessor of a token register so it expects a number or \prm
10743{toksdef}d macro.
10744
10745\stopoldprimitive
10746
10747\startnewprimitive[title={\prm {toksapp}}]
10748
10749One way to append something to a token list is the following:
10750
10751\starttyping
10752\scratchtoks\expandafter{\the\scratchtoks more stuff}
10753\stoptyping
10754
10755This works all right, but it involves a copy of what is already in \type
10756{\scratchtoks}. This is seldom a real issue unless we have large token lists and
10757many appends. This is why \LUATEX\ introduced:
10758
10759\starttyping
10760\toksapp\scratchtoks{more stuff}
10761\toksapp\scratchtoksone\scratchtokstwo
10762\stoptyping
10763
10764At some point, when working on \LUAMETATEX, I realized that primitives like this
10765one and the next appenders and prependers to be discussed were always on the
10766radar of Taco and me. Some were even implemented in what we called \type {eetex}:
10767extended \ETEX, and we even found back the prototypes, dating from pre\PDFTEX\
10768times.
10769
10770\stopnewprimitive
10771
10772\startoldprimitive[title={\prm {toksdef}}]
10773
10774The given name (control sequence) will be bound to the given token register (a
10775number). Often this primitive is hidden in a high level macro that manages
10776allocation.
10777
10778\stopoldprimitive
10779
10780\startnewprimitive[title={\prm {tokspre}}]
10781
10782Where appending something is easy because of the possible \prm {expandafter}
10783trickery a prepend would involve more work, either using temporary token
10784registers andor using a mixture of the (no)expansion added by \ETEX, but all
10785are kind of inefficient and cumbersome.
10786
10787\starttyping
10788\tokspre\scratchtoks{less stuff}
10789\tokspre\scratchtoksone\scratchtokstwo
10790\stoptyping
10791
10792This prepends the token list that is provided.
10793
10794\stopnewprimitive
10795
10796\startoldprimitive[title={\prm {tolerance}}]
10797
10798When the par builder runs into a line with a badness larger than this value and
10799when \prm {emergencystretch} is set a third pass is enabled. In \LUAMETATEX\ we
10800can have more than one second pass and there are more parameters that influence
10801the process.
10802
10803\stopoldprimitive
10804
10805\startnewprimitive[title={\prm {tolerant}}]
10806
10807This prefix tags the following macro as being tolerant with respect to the
10808expected arguments. It only makes sense when delimited arguments are used or when
10809braces are mandate.
10810
10811\startbuffer
10812\tolerant\def\foo[#1]#*[#2]{(#1)(#2)}
10813\stopbuffer
10814
10815\typebuffer \getbuffer
10816
10817This definition makes \type {\foo} tolerant for various calls:
10818
10819\startbuffer
10820\foo \foo[1] \foo [1] \foo[1] [2] \foo [1] [2]
10821\stopbuffer
10822
10823\typebuffer
10824
10825these give: \inlinebuffer. The spaces after the first call disappear because the
10826macro name parser gobbles it, while in the second case the \type {#*} gobbles
10827them. Here is a variant:
10828
10829\startbuffer
10830\tolerant\def\foo[#1]#,[#2]{!#1!#2!}
10831
10832\foo[?] x
10833\foo[?] [?] x
10834
10835\tolerant\def\foo[#1]#*[#2]{!#1!#2!}
10836
10837\foo[?] x
10838\foo[?] [?] x
10839\stopbuffer
10840
10841\typebuffer
10842
10843We now get the following:
10844
10845\getbuffer
10846
10847Here the \type {#,} remembers that spaces were gobbles and they will be put back
10848when there is no further match. These are just a few examples of this tolerant
10849feature. More details can be found in the lowlevel manuals.
10850
10851\stopnewprimitive
10852
10853\startnewprimitive[title={\prm {tomathstyle}}]
10854
10855Internally math styles are numbers, where \prm {displaystyle} is \tomathstyle
10856\displaystyle \space and \prm {crampedscriptscriptstyle} is \tomathstyle
10857\crampedscriptscriptstyle. You can convert the verbose style to a number with
10858\prm {tomathstyle}.
10859
10860\stopnewprimitive
10861
10862\startoldprimitive[title={\prm {topmark}}][obsolete=yes]
10863
10864This is a reference to the last mark on the previous (split off) page, it gives
10865back tokens.
10866
10867\stopoldprimitive
10868
10869\startoldprimitive[title={\prm {topmarks}}]
10870
10871This is a reference to the last mark with the given id (a number) on the previous
10872page, it gives back tokens.
10873
10874\stopoldprimitive
10875
10876This is a reference to the first mark on the (split off) page, it gives back
10877tokens.
10878
10879This is a reference to the first mark with the given id (a number) on the (split
10880off) page, it gives back tokens.
10881
10882\startoldprimitive[title={\prm {topskip}}]
10883
10884This is the amount of glue that is added to the top of a (new) page.
10885
10886\stopoldprimitive
10887
10888\startnewprimitive[title={\prm {toscaled}}]
10889
10890\startbuffer
10891\scratchdimen = 1234pt \toscaled\scratchdimen
10892\stopbuffer
10893
10894The following code gives this: {\nospacing\inlinebuffer} is similar to \prm
10895{todimension} but omits the \type {pt} so that we dont need to revert to some
10896nasty stripping code.
10897
10898\typebuffer
10899
10900\stopnewprimitive
10901
10902\startnewprimitive[title={\prm {tosparsedimension}}]
10903
10904\startbuffer
10905\scratchdimen = 1234pt \tosparsedimension\scratchdimen
10906\stopbuffer
10907
10908The following code gives this: {\nospacing\inlinebuffer} where \quote {sparse}
10909indicates that redundant trailing zeros are not shown.
10910
10911\typebuffer
10912
10913\stopnewprimitive
10914
10915\startnewprimitive[title={\prm {tosparsescaled}}]
10916
10917\startbuffer
10918\scratchdimen = 1234pt \tosparsescaled\scratchdimen
10919\stopbuffer
10920
10921The following code gives this: {\nospacing\inlinebuffer} where \quote {sparse}
10922means that redundant trailing zeros are omitted.
10923
10924\typebuffer
10925
10926\stopnewprimitive
10927
10928\startnewprimitive[title={\prm {tpack}}]
10929
10930This primitive is like \prm {vtop} but without the callback overhead.
10931
10932\stopnewprimitive
10933
10934\startnewprimitive[title={\prm {tracingadjusts}}]
10935
10936In \LUAMETATEX\ the adjust feature has more functionality and also is carried
10937over. When set to a positive values \prm {vadjust} processing reports details.
10938The higher the number, the more youll get.
10939
10940\stopnewprimitive
10941
10942\startnewprimitive[title={\prm {tracingalignments}}]
10943
10944When set to a positive value the alignment mechanism will keep you informed about
10945what is done in various stages. Higher values unleash more information, including
10946what callbacks kick in.
10947
10948\stopnewprimitive
10949
10950\startoldprimitive[title={\prm {tracingassigns}}]
10951
10952When set to a positive values assignments to parameters and variables are
10953reported on the console andor in the log file. Because \LUAMETATEX\ avoids
10954redundant assignments these dont get reported.
10955
10956\stopoldprimitive
10957
10958\startoldprimitive[title={\prm {tracingcommands}}]
10959
10960When set to a positive values the commands (primitives) are reported on the console
10961andor in the log file.
10962
10963\stopoldprimitive
10964
10965\startnewprimitive[title={\prm {tracingexpressions}}]
10966
10967The extended expression commands like \prm {numexpression} and \prm
10968{dimexpression} can be traced by setting this parameter to a positive value.
10969
10970\stopnewprimitive
10971
10972\startnewprimitive[title={\prm {tracingfullboxes}}]
10973
10974When set to a positive value the box will be shown in case of an overfull box.
10975When a quality callback is set this will not happen as all reporting is then
10976delegated.
10977
10978\stopnewprimitive
10979
10980\startoldprimitive[title={\prm {tracinggroups}}]
10981
10982When set to a positive values grouping is reported on the console andor in the
10983log file.
10984
10985\stopoldprimitive
10986
10987\startnewprimitive[title={\prm {tracinghyphenation}}]
10988
10989When set to a positive values the hyphenation process is reported on the console
10990andor in the log file.
10991
10992\stopnewprimitive
10993
10994\startoldprimitive[title={\prm {tracingifs}}]
10995
10996When set some details of what gets tested and what results are seen is reported.
10997
10998\stopoldprimitive
10999
11000\startnewprimitive[title={\prm {tracinginserts}}]
11001
11002A positive value enables tracing where values larger than1 will report more
11003details.
11004
11005\stopnewprimitive
11006
11007\startnewprimitive[title={\prm {tracinglevels}}]
11008
11009The lines in a log file can be prefixed with some details, depending on the bits
11010set:
11011
11012\starttabulate[Tl]
11013\NC 0x1 \NC current group \NC \NR
11014\NC 0x2 \NC current input \NC \NR
11015\NC 0x4 \NC catcode table \NC \NR
11016\stoptabulate
11017
11018\stopnewprimitive
11019
11020\startnewprimitive[title={\prm {tracinglists}}]
11021
11022At various stages the lists being processed can be shown. This is mostly an
11023option for developers.
11024
11025\stopnewprimitive
11026
11027\startoldprimitive[title={\prm {tracinglostchars}}]
11028
11029When set to one characters not present in a font will be reported in the log
11030file, a value of two will also report this on the console.
11031
11032\stopoldprimitive
11033
11034\startoldprimitive[title={\prm {tracingmacros}}]
11035
11036This parameter controls reporting of what macros are seen and expanded.
11037
11038\stopoldprimitive
11039
11040\startnewprimitive[title={\prm {tracingmarks}}]
11041
11042Marks are information blobs that track states that can be queried when a page is
11043handled over to the shipout routine. They travel through the system in a bit
11044different than traditionally: like like adjusts and inserts deeply buried ones
11045bubble up to outer level boxes. This parameters controls what progress gets
11046reported.
11047
11048\stopnewprimitive
11049
11050\startnewprimitive[title={\prm {tracingmath}}]
11051
11052The higher the value, the more information you will get about the various stages
11053in rendering math. Because tracing of nodes is rather verbose you need to know a
11054bit what this engine does. Conceptually there are differences between the
11055\LUAMETATEX\ and traditional engine, like more passes, interatom spacing,
11056different low level mechanisms. This feature is mostly meant for developers who
11057tweak the many available parameters.
11058
11059\stopnewprimitive
11060
11061\startoldprimitive[title={\prm {tracingnesting}}]
11062
11063A positive value triggers log messages about the current level.
11064
11065\stopoldprimitive
11066
11067\startnewprimitive[title={\prm {tracingnodes}}]
11068
11069When set to a positive value more details about nodes (in boxes) will be
11070reported. Because this is also controlled by callbacks what gets reported is
11071macro package dependent.
11072
11073\stopnewprimitive
11074
11075\startoldprimitive[title={\prm {tracingonline}}]
11076
11077The engine has two output channels: the log file and the console and by default
11078most tracing (when enabled) goes to the log file. When this parameter is set to a
11079positive value tracing will also happen in the console. Messages from the \LUA\
11080end can be channeled independently.
11081
11082\stopoldprimitive
11083
11084\startoldprimitive[title={\prm {tracingoutput}}]
11085
11086Values larger than one result in some information about what gets passed to the
11087output routine.
11088
11089\stopoldprimitive
11090
11091\startoldprimitive[title={\prm {tracingpages}}]
11092
11093Values larger than one result in some information about the page building
11094process. In \LUAMETATEX\ there is more info for higher values.
11095
11096\stopoldprimitive
11097
11098\startoldprimitive[title={\prm {tracingparagraphs}}]
11099
11100Values larger than one result in some information about the par building process.
11101In \LUAMETATEX\ there is more info for higher values.
11102
11103\stopoldprimitive
11104
11105\startnewprimitive[title={\prm {tracingpasses}}]
11106
11107In \LUAMETATEX\ you can configure additional second stage par builder passes and
11108this parameter controls what gets reported on the console andor in the log
11109file.
11110
11111\stopnewprimitive
11112
11113\startnewprimitive[title={\prm {tracingpenalties}}]
11114
11115This setting triggers reporting of actions due to special penalties in the
11116page builder.
11117
11118\stopnewprimitive
11119
11120\startoldprimitive[title={\prm {tracingrestores}}]
11121
11122When set to a positive values (re)assignments after grouping to parameters and
11123variables are reported on the console andor in the log file. Because
11124\LUAMETATEX\ avoids redundant assignments these dont get reported.
11125
11126\stopoldprimitive
11127
11128\startoldprimitive[title={\prm {tracingstats}}]
11129
11130This parameter is a dummy in \LUAMETATEX. There are anyway some statistic
11131reported when the format is made but for a regular run it is up to the macro
11132package to come up with useful information.
11133
11134\stopoldprimitive
11135
11136\startnewprimitive[title={\prm {tsplit}}]
11137
11138This splits like \prm {vsplit} but it returns a \prm {vtop} box instead.
11139
11140\stopnewprimitive
11141
11142\startoldprimitive[title={\prm {uccode}}]
11143
11144When the \prm {uppercase} operation is applied the uppercase code of a character
11145is used for the replacement. This primitive is used to set that code, so it
11146expects two character number.
11147
11148\stopoldprimitive
11149
11150\startoldprimitive[title={\prm {uchyph}}]
11151
11152When set to a positive number words that start with a capital will be hyphenated.
11153
11154\stopoldprimitive
11155
11156\startnewprimitive[title={\prm {uleaders}}]
11157
11158This leader adapts itself after a paragraph has been typeset. Here are a few
11159examples:
11160
11161\startbuffer
11162test \leaders \hbox {x}\hfill\ test
11163test \uleaders \hbox{x x x x}\hfill\ test
11164test \hbox{x x x x}\hskip 3cm plus 1cm\ test
11165test \uleaders \hbox{x x x x}\hskip 3cm plus 1cm\ test
11166\stopbuffer
11167
11168\typebuffer
11169
11170When an \prm {uleaders} is used the glue in the given box will be adapted to the
11171available space.
11172
11173\startlines \getbuffer \stoplines
11174
11175\startsetups adaptive:test
11176 \setbox\usedadaptivebox\hbox to \usedadaptivewidth yoffset \usedadaptivedepth \bgroup
11177 \externalfigure
11178 [cow.pdf]
11179 [width=\usedadaptivewidth,
11180 height=\dimexpr\usedadaptiveheight\usedadaptivedepth\relax]
11181 \egroup
11182\stopsetups
11183
11184Optionally the \type {callback} followed by a number can be given, in which case
11185a callback kicks in that gets that the node, a group identifier, and the number
11186passed. It permits (for instance) adaptive graphics: \dostepwiserecurse {1} {100} {5}
11187{\hbox {#1=\romannumerals{#1}} {\adaptivebox [strut=yes, setups=adaptive:test]{}} }.
11188
11189\stopnewprimitive
11190
11191\startoldprimitive[title={\prm {unboundary}}]
11192
11193When possible a preceding boundary node will be removed.
11194
11195\stopoldprimitive
11196
11197\startnewprimitive[title={\prm {undent}}]
11198
11199When possible the already added indentation will be removed.
11200
11201\stopnewprimitive
11202
11203\startoldprimitive[title={\prm {underline}}]
11204
11205This is a math specific primitive that draws a line under the given content. It
11206is a poor mans replacement for a delimiter. The thickness is set with \prm
11207{Umathunderbarrule}, the distance between content and rule is set by \prm
11208{Umathunderbarvgap} and \prm {Umathunderbarkern} is added above the rule. The
11209style used for the content under the rule can be set with \prm
11210{Umathunderlinevariant}. See \prm {overline} for what these parameters do.
11211
11212\stopoldprimitive
11213
11214\startoldprimitive[title={\prm {unexpanded}}]
11215
11216This is an \ETEX\ enhancement. The content will not be expanded in a context
11217where expansion is happening, like in an \prm {edef}. In \CONTEXT\ you need to
11218use \prm {normalunexpanded} because we already had a macro with that name.
11219
11220\startbuffer
11221\def \A{!} \meaning\A
11222\def \B{?} \meaning\B
11223\edef\C{\A\B} \meaning\C
11224\edef\C{\normalunexpanded{\A}\B} \meaning\C
11225\stopbuffer
11226
11227\typebuffer
11228
11229\startlines \tttf \getbuffer \stoplines
11230
11231\stopoldprimitive
11232
11233\startnewprimitive[title={\prm {unexpandedendless}}]
11234
11235This one loops forever so you need to quit explicitly.
11236
11237\stopnewprimitive
11238
11239\startnewprimitive[title={\prm {unexpandedloop}}]
11240
11241As follow up on \prm {expandedloop} we now show its counterpart:
11242
11243\startbuffer
11244\edef\whatever
11245 {\unexpandedloop 1 10 1
11246 {\scratchcounter=\the\currentloopiterator\relax}}
11247
11248\meaningasis\whatever
11249\stopbuffer
11250
11251\typebuffer
11252
11253\start \veryraggedright \tt\tfx \getbuffer \stop \blank
11254
11255The difference between the (un)expanded loops and a local controlled
11256one is shown here. Watch the out of order injection of \type {A}s.
11257
11258\startbuffer
11259\edef\TestA{\localcontrolledloop 1 5 1 {A}}
11260\edef\TestB{\expandedloop 1 5 1 {B}}
11261\edef\TestC{\unexpandedloop 1 5 1 {C\relax}}
11262\stopbuffer
11263
11264\typebuffer \getbuffer
11265
11266We show the effective definition as well as the outcome of using them
11267
11268\startbuffer
11269\meaningasis\TestA
11270\meaningasis\TestB
11271\meaningasis\TestC
11272
11273A: \TestA
11274B: \TestB
11275C: \TestC
11276\stopbuffer
11277
11278\typebuffer \startlines \tttf \getbuffer \stoplines
11279
11280Watch how because it is empty \type {\TestA} has become a constant macro because
11281thats what deep down empty boils down to.
11282
11283\stopnewprimitive
11284
11285\startnewprimitive[title={\prm {unexpandedrepeat}}]
11286
11287This one takes one instead of three arguments which looks better in simple loops.
11288
11289\stopnewprimitive
11290
11291\startoldprimitive[title={\prm {unhbox}}]
11292
11293A box is a packaged list and once packed travels through the system as a single
11294object with properties, like dimensions. This primitive injects the original list
11295and discards the wrapper.
11296
11297\stopoldprimitive
11298
11299\startoldprimitive[title={\prm {unhcopy}}]
11300
11301This is like \prm {unhbox} but keeps the original. It is one of the more costly
11302operations.
11303
11304\stopoldprimitive
11305
11306\startnewprimitive[title={\prm {unhpack}}]
11307
11308This primitive is like \prm {unhbox} but without the callback overhead.
11309
11310\stopnewprimitive
11311
11312\startoldprimitive[title={\prm {unkern}}]
11313
11314This removes the last kern, if possible.
11315
11316\stopoldprimitive
11317
11318\startoldprimitive[title={\prm {unless}}]
11319
11320This \ETEX\ prefix will negate the test (when applicable).
11321
11322\starttyping
11323 \ifx\one\two YES\else NO\fi
11324\unless\ifx\one\two NO\else YES\fi
11325\stoptyping
11326
11327This primitive is hardly used in \CONTEXT\ and we probably could get rid of these
11328few cases.
11329
11330\stopoldprimitive
11331
11332\startnewprimitive[title={\prm {unletfrozen}}]
11333
11334A frozen macro cannot be redefined: you get an error. But as nothing in \TEX\ is set
11335in stone, you can do this:
11336
11337\starttyping
11338\frozen\def\MyMacro{...}
11339\unletfrozen\MyMacro
11340\stoptyping
11341
11342and \type {\MyMacro} is no longer protected from overloading. It is still
11343undecided to what extend \CONTEXT\ will use this feature.
11344
11345\stopnewprimitive
11346
11347\startnewprimitive[title={\prm {unletprotected}}]
11348
11349The complementary operation of \prm {letprotected} can be used to unprotect
11350a macro, so that it gets expandable.
11351
11352\startbuffer
11353 \def \MyMacroA{alpha}
11354\protected \def \MyMacroB{beta}
11355 \edef \MyMacroC{\MyMacroA\MyMacroB}
11356\unletprotected \MyMacroB
11357 \edef \MyMacroD{\MyMacroA\MyMacroB}
11358\meaning \MyMacroC\crlf
11359\meaning \MyMacroD\par
11360\stopbuffer
11361
11362\typebuffer
11363
11364Compare this with the example in the previous section:
11365
11366{\tttf \getbuffer}
11367
11368\stopnewprimitive
11369
11370\startoldprimitive[title={\prm {unpenalty}}]
11371
11372This removes the last penalty, if possible.
11373
11374\stopoldprimitive
11375
11376\startoldprimitive[title={\prm {unskip}}]
11377
11378This removes the last glue, if possible.
11379
11380\stopoldprimitive
11381
11382\startnewprimitive[title={\prm {untraced}}]
11383
11384Related to the meaning providers is the \prm {untraced} prefix. It marks a macro
11385as to be reported by name only. It makes the macro look like a primitive.
11386
11387\starttyping
11388 \def\foo{}
11389\untraced\def\oof{}
11390
11391\scratchtoks{\foo\foo\oof\oof}
11392
11393\tracingall \the\scratchtoks \tracingnone
11394\stoptyping
11395
11396This will show up in the log as follows:
11397
11398\starttyping
113991:4: {\the}
114001:5: \foo >
114011:5: \foo >
114021:5: \oof
114031:5: \oof
11404\stoptyping
11405
11406This is again a trick to avoid too much clutter in a log. Often it doesnt matter
11407to users what the meaning of a macro is (if they trace at all). \footnote {An
11408earlier variant could also hide the expansion completely but that was just
11409confusing.}
11410
11411\stopnewprimitive
11412
11413\startoldprimitive[title={\prm {unvbox}}]
11414
11415A box is a packaged list and once packed travels through the system as a single
11416object with properties, like dimensions. This primitive injects the original list
11417and discards the wrapper.
11418
11419\stopoldprimitive
11420
11421\startoldprimitive[title={\prm {unvcopy}}]
11422
11423This is like \prm {unvbox} but keeps the original. It is one of the more costly
11424operations.
11425
11426\stopoldprimitive
11427
11428\startnewprimitive[title={\prm {unvpack}}]
11429
11430This primitive is like \prm {unvbox} but without the callback overhead.
11431
11432\stopnewprimitive
11433
11434\startoldprimitive[title={\prm {uppercase}}]
11435
11436See its counterpart \prm {lowercase} for an explanation.
11437
11438\stopoldprimitive
11439
11440\startoldprimitive[title={\prm {vadjust}}]
11441
11442This injects a node that stores material that will injected before or after the
11443line where it has become part of. In \LUAMETATEX\ there are more features, driven
11444by keywords.
11445
11446\stopoldprimitive
11447
11448\startoldprimitive[title={\prm {valign}}]
11449
11450This command starts vertically aligned material. Its counterpart \prm {halign} is
11451used more frequently. Most macro packages provide wrappers around these commands.
11452First one specifies a preamble which is then followed by entries (rows and
11453columns).
11454
11455\stopoldprimitive
11456
11457\startnewprimitive[title={\prm {variablefam}}]
11458
11459In traditional \TEX\ sets the family of what are considered variables (class 7)
11460to the current family (which often means that they adapt to the current alphabet)
11461and then injects a math character of class ordinary. This parameter can be used
11462to obey the given class when the family set for a character is the same as this
11463parameter. So we then use the given class with the current family. It is mostly
11464there for compatibility with \LUATEX\ and experimenting (outside \CONTEXT).
11465
11466\stopnewprimitive
11467
11468\startoldprimitive[title={\prm {vbadness}}]
11469
11470This sets the threshold for reporting a (vertical) badness value, its current
11471value is \the \badness.
11472
11473\stopoldprimitive
11474
11475\startoldprimitive[title={\prm {vbox}}]
11476
11477This creates a vertical box. In the process callbacks can be triggered that can
11478preprocess the content, influence line breaking as well as assembling the
11479resulting paragraph. More can be found in dedicated manuals. The baseline is
11480at the bottom.
11481
11482\stopoldprimitive
11483
11484\startoldprimitive[title={\prm {vcenter}}]
11485
11486In traditional \TEX\ this box packer is only permitted in math mode but in
11487\LUAMETATEX\ it also works in text mode. The content is centered in the vertical
11488box.
11489
11490\stopoldprimitive
11491
11492\startoldprimitive[title={\prm {vfil}}]
11493
11494This is a shortcut for \typ {\vskip plus 1 fil} (first order filler).
11495
11496\stopoldprimitive
11497
11498\startoldprimitive[title={\prm {vfill}}]
11499
11500This is a shortcut for \typ {\vskip plus 1 fill} (second order filler).
11501
11502\stopoldprimitive
11503
11504\startoldprimitive[title={\prm {vfilneg}}]
11505
11506This is a shortcut for \typ {\vskip plus 1 fil} so it can compensate \prm
11507{vfil}.
11508
11509\stopoldprimitive
11510
11511\startoldprimitive[title={\prm {vfuzz}}]
11512
11513This dimension sets the threshold for reporting vertical boxes that are under or
11514overfull. The current value is \the \vfuzz.
11515
11516\stopoldprimitive
11517
11518\startnewprimitive[title={\prm {virtualhrule}}]
11519
11520This is a horizontal rule with zero dimensions from the perspective of the
11521frontend but the backend can access them as set.
11522
11523\stopnewprimitive
11524
11525\startnewprimitive[title={\prm {virtualvrule}}]
11526
11527This is a vertical rule with zero dimensions from the perspective of the frontend
11528but the backend can access them as set.
11529
11530\stopnewprimitive
11531
11532\startoldprimitive[title={\prm {vkern}}]
11533
11534This primitive is like \prm {kern} but will force the engine into vertical mode
11535if it isnt yet.
11536
11537\stopoldprimitive
11538
11539\startnewprimitive[title={\prm {vpack}}]
11540
11541This primitive is like \prm {vbox} but without the callback overhead.
11542
11543\stopnewprimitive
11544
11545\startnewprimitive[title={\prm {vpenalty}}]
11546
11547This primitive is like \prm {penalty} but will force the engine into vertical
11548mode if it isnt yet.
11549
11550\stopnewprimitive
11551
11552\startoldprimitive[title={\prm {vrule}}]
11553
11554This creates a vertical rule. Unless the height and depth are set they will
11555stretch to fix the available space. In addition to the traditional \type {width},
11556\type {height} and \type {depth} specifiers some more are accepted. These are
11557discussed in other manuals. See \prm {hrule} for a simple example.
11558
11559\stopoldprimitive
11560
11561\startoldprimitive[title={\prm {vsize}}]
11562
11563This sets (or gets) the current vertical size. While setting the \prm {hsize}
11564inside a \prm {vbox} has consequences, setting the \prm {vsize} mostly makes
11565sense at the outer level (the page).
11566
11567\stopoldprimitive
11568
11569\startoldprimitive[title={\prm {vskip}}]
11570
11571The given glue is injected in the vertical list. If possible vertical mode is
11572entered.
11573
11574\stopoldprimitive
11575
11576\startoldprimitive[title={\prm {vsplit}}]
11577
11578This operator splits a given amount from a vertical box. In \LUAMETATEX\ we can
11579split \type {to} but also \type {upto}, so that we dont have to repack the
11580result in order to see how much is actually in there.
11581
11582\stopoldprimitive
11583
11584\startoldprimitive[title={\prm {vss}}]
11585
11586This is the vertical variant of \prm {hss}. See there for what it means.
11587
11588\stopoldprimitive
11589
11590\startoldprimitive[title={\prm {vtop}}]
11591
11592This creates a vertical box. In the process callbacks can be triggered that can
11593preprocess the content, influence line breaking as well as assembling the
11594resulting paragraph. More can be found in dedicated manuals. The baseline is
11595at the top.
11596
11597\stopoldprimitive
11598
11599\startoldprimitive[title={\prm {wd}}]
11600
11601Returns the width of the given box.
11602
11603\stopoldprimitive
11604
11605\startoldprimitive[title={\prm {widowpenalties}}]
11606
11607This is an array of penalty put before the last lines in a paragraph. High values
11608discourage (or even prevent) a lone line at the beginning of a next page. This
11609command expects a count value indicating the number of entries that will follow.
11610The first entry is ends up before the last line.
11611
11612\stopoldprimitive
11613
11614\startoldprimitive[title={\prm {widowpenalty}}]
11615
11616This is the penalty put before a widow line in a paragraph. High values
11617discourage (or even prevent) a lone line at the beginning of a next page.
11618
11619\stopoldprimitive
11620
11621\startnewprimitive[title={\prm {wordboundary}}]
11622
11623The hypenation routine has to decide where a word begins and ends. If you want to
11624make sure that there is a proper begin or end of a word you can inject this
11625boundary.
11626
11627\stopnewprimitive
11628
11629\startnewprimitive[title={\prm {wrapuppar}}]
11630
11631What this primitive does can best be shown with an example:
11632
11633\startbuffer
11634some text\wrapuppar{one} and some\wrapuppar{two} more
11635\stopbuffer
11636
11637\typebuffer
11638
11639We get:
11640
11641\blank \getbuffer \blank
11642
11643So, it is a complementary command to \prm {everypar}. It can only be issued
11644inside a paragraph.
11645
11646\stopnewprimitive
11647
11648\startoldprimitive[title={\prm {xdef}}]
11649
11650This is an alternative for \type {\global \edef}:
11651
11652\starttyping
11653\xdef\MyMacro{...}
11654\stoptyping
11655
11656\stopoldprimitive
11657
11658\startnewprimitive[title={\prm {xdefcsname}}]
11659
11660This is the companion of \prm {xdef}:
11661
11662\starttyping
11663\expandafter\xdef\csname MyMacro:1\endcsname{...}
11664 \xdefcsname MyMacro:1\endcsname{...}
11665\stoptyping
11666
11667\stopnewprimitive
11668
11669\startoldprimitive[title={\prm {xleaders}}]
11670
11671See \prm {gleaders} for an explanation.
11672
11673\stopoldprimitive
11674
11675\startoldprimitive[title={\prm {xspaceskip}}]
11676
11677Normally the glue inserted when a space is encountered after a character with a
11678space factor other than 1000 is taken from the font (fontdimen 7) unless this
11679parameter is set in which case its value is added.
11680
11681\stopoldprimitive
11682
11683\startnewprimitive[title={\prm {xtoks}}]
11684
11685This is the global variant of \prm {etoks}.
11686
11687\stopnewprimitive
11688
11689\startnewprimitive[title={\prm {xtoksapp}}]
11690
11691This is the global variant of \prm {etoksapp}.
11692
11693\stopnewprimitive
11694
11695\startnewprimitive[title={\prm {xtokspre}}]
11696
11697This is the global variant of \prm {etokspre}.
11698
11699\stopnewprimitive
11700
11701\startoldprimitive[title={\prm {year}}]
11702
11703This internal number starts out with the year that the job started.
11704
11705\stopoldprimitive
11706
11707\stopsubject
11708
11709\startsubject[title=Obsolete]
11710
11711The \LUAMETATEX\ engine has more than its \LUATEX\ ancestor but it also has less.
11712Because in the end the local control mechanism performed quite okay I decided to
11713drop the \prm {immediateassignment} and \prm {immediateassigned} variants. They
11714sort of used the same trick so there isnt much to gain and it was less generic
11715(read: error prone).
11716
11717
11718
11719
11720
11721
11722
11723
11724
11725
11726
11727
11728
11729
11730
11731
11732
11733
11734
11735
11736
11737
11738
11739
11740
11741
11742
11743
11744
11745
11746
11747
11748
11749
11750
11751
11752
11753
11754
11755
11756
11757
11758
11759
11760
11761
11762
11763
11764
11765
11766
11767
11768\stopsubject
11769
11770\page
11771
11772
11773\definehead
11774 [Syntax]
11775 [subsection]
11776
11777
11778
11779
11780
11781\startsubject[title=Syntax]
11782
11783\startpagecolumns[page=no]
11784 \startluacode
11785 moduledata.engine.allspecifications()
11786 \stopluacode
11787\stoppagecolumns
11788
11789\stopsubject
11790
11791\page
11792
11793
11794
11795
11796
11797
11798
11799
11800
11801
11802
11803
11804
11805
11806
11807
11808
11809
11810
11811
11812
11813
11814
11815
11816
11817
11818
11819
11820
11821
11822
11823
11824
11825
11826
11827
11828
11829
11830
11831
11832
11833
11834
11835
11836
11837
11838
11839
11840
11841
11842
11843
11844
11845
11846
11847
11848
11849
11850
11851
11852
11853
11854
11855
11856
11857
11858
11859
11860
11861
11862
11863
11864
11865\startsubject[title=Rationale]
11866
11867Some words about the why and how it came. One of the early adopters of \CONTEXT\
11868was Taco Hoekwater and we spent numerous trips to \TEX\ meetings all over the
11869globe. He was also the only one I knew who had read the \TEX\ sources. Because
11870\CONTEXT\ has always been on the edge of what is possible and at that time we
11871both used it for rather advanced rendering, we also ran into the limitations. Im
11872not talking of \TEX\ features here. Naturally old school \TEX\ is not really
11873geared for dealing with images of all kind, colors in all kind of color spaces,
11874highly interactive documents, input methods like \XML, etc. The nice thing is
11875that it offers some escapes, like specials and writes and later execution of
11876programs that opened up lots of possibilities, so in practice there were no real
11877limitations to what one could do. But coming up with a consistent and extensible
11878(multi lingual) user interface was non trivial, because it had an impact in
11879memory usage and performance. A lot could be done given some programming, as
11880\CONTEXT\ \MKII\ proves, but it was not always pretty under the hood. The move to
11881\LUATEX\ and \MKIV\ transferred some action to \LUA, and because \LUATEX\
11882effectively was a \CONTEXT\ related project, we could easily keep them in sync.
11883
11884Our traveling together, meeting several times per year, and eventually email and
11885intense \LUATEX\ developments (lots of Skype sessions) for a couple of years,
11886gave us enough opportunity to discuss all kind of nice features not present in
11887the engine. The previous century we discussed lots of them, rejected some, stayed
11888with others, and I admit that forgot about most of the arguments already. Some
11889that we did was already explored in \type {eetex}, some of those ended up in
11890\LUATEX, and eventually what we have in \LUAMETATEX\ can been seen as the result
11891of years of programming in \TEX, improving macros, getting more performance and
11892efficiency out of existing \CONTEXT\ code and inspiration that we got out of the
11893\CONTEXT\ community, a demanding lot, always willing to experiment with us.
11894
11895Once I decided to work on \LUAMETATEX\ and bind its source to the \CONTEXT\
11896distribution so that we can be sure that it wont get messed up and might
11897interfere with the \CONTEXT\ expectations, some more primitives saw their way
11898into it. It is very easy to come up with all kind of bells and whistles but it is
11899equally easy to hurt performance of an engine and what might go unnoticed in
11900simple tests can really affect a macro package that depends on stability. So, what
11901I did was mostly looking at the \CONTEXT\ code and wondering how to make some of
11902the low level macros look more natural, also because I know that there are users
11903who look into these sources. We spend a lot of time making them look consistent
11904and nice and the nicer the better. Getting a better performance was seldom an
11905argument because much is already as fast as can be so there is not that much to
11906gain, but less clutter in tracing was an argument for some new primitives. Also,
11907the fact that we soon might need to fall back on our phones to use \TEX\ a
11908smaller memory footprint and less byte shuffling also was a consideration. The
11909\LUAMETATEX\ memory footprint is somewhat smaller than the \LUATEX\ footprint.
11910By binding \LUAMETATEX\ to \CONTEXT\ we can also guarantee that the combinations
11911works as expected.
11912
11913Im aware of the fact that \CONTEXT\ is in a somewhat unique position. First of
11914all it has always been kind of cutting edge so its users are willing to
11915experiment. There are users who immediately update and run tests, so bugs can and
11916will be fixed fast. Already for a long time the community has an convenient
11917infrastructure for updating and the build farm for generating binaries (also for
11918other engines) is running smoothly.
11919
11920Then there is the \CONTEXT\ user interface that is quite consistent and permits
11921extensions with staying backward compatible. Sometimes users run into old manuals
11922or examples and then complain that \CONTEXT\ is not compatible but that then
11923involves obsolete technology: we no longer need font and input encodings and font
11924definitions are different for \OPENTYPE\ fonts. We always had an abstract backend
11925model, but nowadays \PDF\ is kind of dominant and drives a lot of expectations.
11926So, some of the \MKII\ commands are gone and \MKIV\ has some more. Also, as
11927\METAPOST\ evolved that department in \CONTEXT\ also evolved. Think of it like
11928cars: soon all are electric so one cannot expect a hole to poor in some fluid but
11929gets a (often incompatible) plug instead. And buttons became touch panels. There
11930is no need to use much force to steer or brake. Navigation is different, as are
11931many controls. And do we need to steer ourselves a decade from now?
11932
11933So, just look at \TEX\ and \CONTEXT\ in the same way. A system from the nineties
11934in the previous century differs from one three decades later. Demands differ,
11935input differs, resources change, editing and processing moves on, and so on.
11936Manuals, although still being written are seldom read from cover to cover because
11937online searching replaced them. And who buys books about programming? So
11938\LUAMETATEX, while still being \TEX\ also moves on, as do the way we do our low
11939level coding. This makes sense because the original \TEX\ ecosystem was not made
11940with a huge and complex macro package in mind, that just happened. An author was
11941supposed to make a style for each document. An often used argument for using
11942another macro package over \CONTEXT\ was that the later evolved and other macro
11943packages would work the same forever and not change from the perspective of the
11944user. In retrospect those arguments were somewhat strange because the world,
11945computers, users etc.\ do change. Standards come and go, as do software politics
11946and preferences. In many aspects the \TEX\ community is not different from other
11947large software projects, operating system wars, library devotees, programming
11948language addicts, paradigm shifts. But, dont worry, if you dont like
11949\LUAMETATEX\ and its new primitives, just forget about them. The other engines
11950will be there forever and are a safe bet, although \LUATEX\ already stirred up
11951the pot I guess. But keep in mind that new features in the latest greatest
11952\CONTEXT\ version will more and more rely on \LUAMETATEX\ being used; after all
11953that is where its made for. And this manual might help understand its users why,
11954where and how the low level code differs between \MKII, \MKIV\ and \LMTX.
11955
11956Can we expect more new primitives than the ones introduced here? Given the amount
11957of time I spent on experimenting and considering what made sense and what not,
11958the answer probably is \quotation {no}, or at least \quotation {not that much}.
11959As in the past no user ever requested the kind of primitives that were added, I
11960dont expect users to come up with requests in the future either. Of course,
11961those more closely related to \CONTEXT\ development look at it from the other
11962end. Because its there where the low level action really is, demands might still
11963evolve.
11964
11965Basically there are wo areas where the engine can evolve: the programming part
11966and the rendering. In this manual we focus on the programming and writing the
11967manual sort of influences how details get filled in. Rendering in more complex
11968because there heuristics and usage plays a more dominant role. Good examples are
11969the math, par and page builder. They were extended and features were added over
11970time but improved rendering came later. Not all extensions are critical, some are
11971there (and got added) in order to write more readable code but there is only so
11972much one can do in that area. Occasionally a feature pops up that is a side
11973effect of a challenge. No matter what gets added it might not affect complexity
11974too much and definitely not impact performance significantly!
11975
11976Hans Hagen \crlf Hasselt NL
11977
11978\stopsubject
11979
11980\popoverloadmode
11981
11982\startluacode
11983 local match = string.match
11984 local find = string.match
11985
11986 function document.CheckCompleteness()
11987 local primitives = token.getprimitives()
11988 local luametatex = { }
11989 local indexed = { }
11990 local everything = { }
11991
11992 for i=1,#primitives do
11993 local prim = primitives[i]
11994 local name = prim[3]
11995 if prim[4] == 4 then
11996 if find(name,"U") or find(name,"math") then
11997
11998 luametatex[name] = nil
11999 everything[name] = false
12000 else
12001 luametatex[name] = false
12002 end
12003 else
12004 everything[name] = true
12005 end
12006 end
12007
12008 local function collect(index)
12009 if index then
12010 local data = index.entries
12011 for i=1,#data do
12012 local name = match(data[i].list[1][1],"\\tex%s*{(.-)}") or ""
12013 if luametatex[name] == false then
12014 luametatex[name] = true
12015 end
12016 indexed[name] = true
12017 everything[name] = nil
12018 end
12019 end
12020 end
12021
12022 collect(structures.registers.collected and structures.registers.collected.index)
12023
12024 context.startsubject { title = "To be checked primitives (new)" }
12025
12026 context.blank()
12027 context.startcolumns { n = 2 }
12028 for k, v in table.sortedhash(luametatex) do
12029 if not v then
12030 context.dontleavehmode()
12031 context.type(k)
12032 context.crlf()
12033 end
12034 end
12035 context.stopcolumns()
12036
12037 context.page()
12038
12039 context.stopsubject()
12040
12041 everything[""] = nil
12042 everything[" "] = nil
12043
12044 context.startsubject { title = "To be checked primitives (math)" }
12045
12046 context.blank()
12047 context.startcolumns { n = 2 }
12048 for k, v in table.sortedhash(everything) do
12049 if not v then
12050 context.dontleavehmode()
12051 context.type(k)
12052 context.crlf()
12053 end
12054 end
12055 context.stopcolumns()
12056
12057 context.page()
12058
12059 context.stopsubject()
12060
12061 context.startsubject { title = "To be checked primitives (old)" }
12062
12063 context.blank()
12064 context.startcolumns { n = 2 }
12065 for k, v in table.sortedhash(everything) do
12066 if v then
12067 context.dontleavehmode()
12068 context.type(k)
12069 context.crlf()
12070 end
12071 end
12072 context.stopcolumns()
12073
12074 context.page()
12075
12076 context.stopsubject()
12077
12078 context.startsubject { title = "Indexed primitives" }
12079
12080 context.blank()
12081 context.startcolumns { n = 2 }
12082 for k, v in table.sortedhash(indexed) do
12083 context.dontleavehmode()
12084 if luametatex[k] == true then
12085 context("\\color[darkgreen]{\\tttf %s}",k)
12086 elseif luametatex[k] == false then
12087 context("\\color[darkred]{\\tttf %s}",k)
12088 else
12089 context("{\\tttf %s}",k)
12090 end
12091 context.crlf()
12092 end
12093 context.stopcolumns()
12094
12095 context.page()
12096
12097 context.stopsubject()
12098 end
12099\stopluacode
12100
12101\startmode[atpragma]
12102 \startluacode
12103 context.page()
12104 document.CheckCompleteness()
12105 \stopluacode
12106
12107
12108
12109\stopmode
12110
12111\stopbodymatter
12112
12113\stoptext
12114
12115
12116 |