// TEXRS — PRIMITIVE REFERENCE

texrs v0.6.8 · TeX on fusevm · mouth → expander → command stream → bytecode → Cranelift JIT · MIT · in active development

Docs Report GitHub
// Color scheme

>_PRIMITIVE REFERENCE

Every primitive texrs carries, what it does, and where it happens — at compile time while lowering, or at run time on the VM. A primitive not on this page is not implemented; BUGS.md says so explicitly for the ones that are commonly reached for.

358
Primitives
13
Chapters
256
Count registers
53
Command-line options

Category codes

PrimitiveWhat it doesSyntax and example
\catcodeSet or read a character's category code. A character's category is a mutable table entry, not a property of the language: texrs starts from INITEX's sparse defaults, where { is an ordinary character until something makes it a group opener. Takes effect at COMPILE time, because it changes how the rest of the file reads.
\catcode`\X=N
\catcode`\{=1 \catcode`\}=2 \catcode`\#=6
\message{now braces group}
^^XControl-character notation (tex.web §352), in two forms decided by what follows: ^^ and two LOWERCASE hex digits is that hex code, while ^^ and anything else is one character shifted by 64. So ^^41 is A and ^^4a is J, but ^^4A is tA — A is not a lowercase hex digit, so the shift applies to the 4 alone. The substitution belongs to the input processor (§353), which runs before anything is classified, so it applies inside a control sequence name too: plain.tex writes \catcode\^^K=7. This is also how a line end is written inside a macro body.
^^M   % carriage return
^^I   % tab
^^41  % the hex form: A
`A character code as a number, for a register assignment or a comparison: a backtick followed by a character is that character's code, and the backslash before the character is optional unless it is a control sequence.
\count1=`\A
\message{\the\count1}   % => 65
\catcodetableWhich category-code table the mouth reads with, as a number: LuaTeX keeps many, so a document can switch regimes in one assignment. Only table 0 and the tables \savecatcodetable or \initcatcodetable have made can be switched to; anything else is ! Invalid \catcode table. Local to the group unless \global, and a \catcode changes the table that is current, which the group's end restores whatever table is current then.
\catcodetable=<number>
\initcatcodetable 3 \catcodetable 3   % INITEX's codes
\savecatcodetableMake table N a copy of the current one. N may not be the current table, and must be in 0..32767.
\savecatcodetable 1
\initcatcodetableMake table N INITEX's: letters 11, \ 0, % 14, the space 10, ^^M 5, ^^@ 9, ^^? 15, everything else 12.
\initcatcodetable 2

Macro definition

PrimitiveWhat it doesSyntax and example
\defDefine a macro. Parameters may be undelimited (#1) or delimited (\def\pair#1,#2.{...}, where the argument is whatever precedes the delimiter), and ## is a literal parameter character. The parameter text is validated as tex.web §476 validates it: every # must be followed by a digit, and the digits must run consecutively. Takes effect at COMPILE time. The name may be an ACTIVE CHARACTER as well as a control sequence (tex.web §1215): \catcode\~=13 \def~{...} defines ~ itself, and an active ~ and the control sequence \~ stay different things.
\def\name<parameter text>{<body>}
\def\greet#1{HELLO-#1}
\def\pair#1,#2.{[#1|#2]}
\message{\greet{WORLD}}   % => HELLO-WORLD
\message{\pair 1,2.}      % => [1|2]
\gdefDefine globally: the definition survives the enclosing group, where a \def inside braces is undone at the closing brace.
\gdef\name{<body>}
{\gdef\v{IN}}
\message{\v}   % => IN
\edefDefine with the body expanded NOW, so a register read is frozen at definition time and a later assignment cannot move it. tex.web §366 expands the body while READING it, which decides a conditional in it there and turns \the into §478's characters. texrs does that whenever it can prove the registers the body reads — a register nothing has assigned yet is at INITEX's zero, which is what the compiler writes into every slot — and otherwise falls back to snapshotting the \the\count read into a scratch register (taken from the top of the count range) and carrying the conditional. The fallback is the case BUGS.md records: a conditional over a register the program HAS written is still decided at use time.
\edef\name{<body>}
\count1=1
\edef\frozen{\the\count1}
\count1=2
\message{\frozen}   % => 1
\edef\case{\ifcase\count2 ZERO\else OTHER\fi}
\count2=5
\message{\case}      % => ZERO
\xdefA global \edef: the body is expanded now and the definition survives the enclosing group.
\xdef\name{<body>}
{\xdef\frozen{\the\count1}}
\letGive a control sequence another's CURRENT meaning, not a reference to it: redefining the source afterwards does not change the alias.
\let\alias=\source
\def\v{ONE}
\let\w=\v
\def\v{TWO}
\message{\w}   % => ONE
\futureletLook one token past the next without eating either: \futurelet\a\b\c gives \a the meaning of \c and then puts \b and \c back, so the stream is exactly as it was (tex.web §1221). That non-destructive peek is what LaTeX's \@ifnextchar is built from, and so is every optional argument in the language. A control sequence let to a character MEANS that character, so \ifx\next[ compares true — which is the comparison the whole idiom rests on.
\futurelet\next<token><token>
\def\peek{\futurelet\next\decide}
\def\decide{\ifx\next[ OPTIONAL\else PLAIN\fi}
\globalPrefix making the following assignment global, so it survives the enclosing group.
\global\count1=5
\global\def\v{OUT}
\longA definition prefix: the macro's arguments may contain \par. Without it a paragraph break inside an argument is a runaway, which is TeX's guard against a missing closing brace swallowing the rest of a document. A macro without it whose argument meets \par reports Runaway argument? and Paragraph ended before \x was complete, puts the \par back and drops the call, as tex does.
\long\def\note#1{[#1]}
\outerA definition prefix: the macro may not then appear in an argument, in a group being scanned as text, or in skipped conditional text. It is an error-detection feature -- plain.tex marks its sectioning macros \outer so a missing brace is caught at the next section rather than at the end of the file. texrs records the prefix and does not police the restriction, so a use tex forbids is accepted here; tests/cases/outer_forbidden_use.tex pins the difference. Prefixes are part of the meaning, so \ifx tells a prefixed definition from a bare one.
\outer\def\chapter{...}
\protectedA definition prefix: the macro does not expand inside an \edef, it survives as itself and runs when the result does. Redefining it afterwards therefore changes what the \edef'd macro produces, which is the observable difference. An eTeX primitive, and the one LaTeX leans on to keep a fragile command safe in a moving argument.
\protected\def\note#1{[#1]}

Expansion

PrimitiveWhat it doesSyntax and example
\csnameBuild a control sequence out of the characters up to \endcsname, so a macro can name another macro. A name with no meaning becomes \relax, as in tex.
\csname <characters>\endcsname
\def\greeting{HI}
\def\name{greeting}
\message{\csname \name\endcsname}   % => HI
\endcsnameTerminate a \csname. It is an error to reach one without an open \csname.
\csname foo\endcsname
\stringPrint a control sequence as text, escape character included — the inverse of \csname.
\string\cs
\message{\string\undefined}   % => \undefined
\showPrint what the next token means (tex.web §1294), read UNEXPANDED: > , the name and =, the same text \meaning gives, and a period, followed by the context an error shows — \show ends by calling error, so the run closes with the transcript notice as it does after an error.
\show<token>
\def\a#1{x#1}\show\a   % => > \a=macro:#1->x#1.
\showthePrint what \the would make of an internal quantity (tex.web §1297): > , the value as §465 writes it — a count as digits, a dimension as 3.5pt, a glue with its stretch and shrink, a token list with each # doubled — and a period, followed by the context an error shows, as \show does. A register's value is the run's, so it is read when the run reaches the \showthe.
\showthe<internal quantity>
\count1=5 \showthe\count1   % => > 5.
\showtokensPrint a token list as \show prints a macro's body: > , the general text with each # doubled and a space after a control word, a period, and the context. The text is read as \detokenize reads it, expanding up to the brace, so \showtokens\expandafter{\x} shows \x's replacement. An eTeX primitive.
\showtokens{<general text>}
\showtokens{\a b #}   % => > \a b ##.
\interactionmodeThe interaction mode as an integer -- 0 batch, 1 nonstop, 2 scroll, 3 errorstop -- read where a number is scanned and assigned like a parameter, though always globally. A value outside 0..3 is ! Bad interaction mode and is ignored. An eTeX primitive.
\interactionmode=<number>
\message{\the\interactionmode}   % => 1 under -interaction=nonstopmode
\batchmodeFrom here on nothing reaches the terminal: messages and error reports alike are withheld, and a run that reported anything still ends pointing to the transcript. Global, and like the other three it ends the terminal line, so what is printed next starts one of its own (tex.web §1264).
\batchmode\message{not shown}\nonstopmode
\nonstopmodeReport errors and carry on without stopping; what a run starts in under the parity harnesses. Global, and it ends the terminal line.
\nonstopmode
\scrollmodeThe same as \nonstopmode here, since texrs never stops to ask; \interactionmode reads 2.
\scrollmode
\errorstopmodeThe same as \nonstopmode here, since texrs never stops to ask; \interactionmode reads 3.
\errorstopmode
\eTeXversione-TeX's major version, a read-only integer: 2, as luatex reports it. \eTeXminorversion is the minor one.
\message{\the\eTeXversion}   % => 2
\eTeXminorversione-TeX's minor version, a read-only integer: 2, as luatex reports it.
\message{\the\eTeXminorversion}   % => 2
\eTeXrevisione-TeX's revision as characters: .2, as luatex expands it.
\message{\eTeXrevision}   % => .2
\eTeXVersione-TeX's version as characters: 2.2, as luatex expands it.
\message{\eTeXVersion}   % => 2.2
\luatexversionLuaTeX's version as a read-only integer, the one packages test to find the engine: 124, for the luatex 1.24.0 texrs is measured against.
\ifnum\luatexversion>100 \message{new enough}\fi
\luatexrevisionLuaTeX's revision as characters: 0.
\message{\luatexrevision}   % => 0
\inputlinenoThe line of the current file the token was read on, as a read-only integer: it stands wherever a number is scanned, and \the and \number write it.
\inputlineno
\message{\the\inputlineno}   % => the line this is on
\meaningWhat a token MEANS, as characters (tex.web §296's print_meaning). A macro reads back as macro: then its parameter text, -> and its body, with \long, \outer and \protected run together in front; a \chardef constant reads back as \char"41; a register name reads back as the register it stands for; a character carries the NAME of its category, so \meaning A is the letter A. A name nothing has defined is undefined. Expandable, like \string, so it works inside a \message.
\meaning<token>
\def\a#1{[#1]}
\message{\meaning\a}   % => macro:#1->[#1]
\uppercaseRead the following group WITHOUT expanding it, replace every character by its \uccode and put the result back to be read again (tex.web §1288). A zero code means the character has no case and stands, so digits and punctuation come through untouched, and the category code travels with the character unchanged — which is what LaTeX's \MakeUppercase is built on.
\uppercase{<text>}
\uppercase{\message{abc 123}}   % => ABC 123
\lowercaseThe same as \uppercase over the \lccode table: the group is read unexpanded, every character is replaced by its lowercase code, and the result is read again with its category codes intact.
\lowercase{<text>}
\lowercase{\message{ABC dEf}}   % => abc def
\theThe value of a register, as characters. The read happens at RUN time on the VM, which is why a \message containing \the\count0 follows a later assignment.
\the\count<N>
\count1=12
\message{count=\the\count1}   % => count=12
\numberA scanned number, as characters, with no leading zeros or plus sign. The scan keeps reading (and expanding) until something that cannot be part of a number stops it, so a following letter needs a terminating space.
\number<number>
\message{\number0042}   % => 42
\expandafterOne token of lookahead: hold the next token back, expand what follows it once, then put the held token in front of the result.
\expandafter<token><token>
\def\a{\b}
\def\b{DEEP}
\message{\expandafter\string\a}   % => \b
\noexpandSuppress expansion of the next token for one step — the token is used for its own sake rather than its meaning.
\noexpand<token>
\edef\keep{\noexpand\later}
\messageWrite to the terminal. This is texrs's parity contract for the milestone: two host builtins, one appending a rendered piece and one flushing the assembled string, so a message reads its registers at run time.
\message{<text>}
\message{HELLO-WORLD}   % => (./file.tex HELLO-WORLD )
\immediateDo the \openout, \write or \closeout that follows now rather than at shipout (tex.web §1375). The next token is read with expansion; anything else is put back and read as if \immediate had not been there.
\immediate\write<number>{<text>}
\immediate\openout3=notes   % => notes.tex, created empty
\openoutOpen a write stream on a file (tex.web §1351, §1374), closing it first if it is open. LuaTeX's 128 streams, 0 to 127. The name is read with expansion -- \openout1=\jobname.aux -- or taken whole from braces, spaces and all, and .tex is added when it has no extension; the file goes under -output-directory when one is given. A file written now is read back as it now stands by a later \input or \openin. Without \immediate it waits in its page as a whatsit and opens the file when that page is shipped -- on a plain document's list path (--dvi); on the string path it is held and never reached.
\immediate\openout<number>=<file name>
\immediate\openout1=\jobname.aux   % => job.aux
\immediate\openout2={my notes}   % => my notes.tex
\closeoutClose a write stream (tex.web §1374). Every stream still open is closed when the run ends. Without \immediate it closes the stream when its page is shipped, on a plain document's list path (--dvi); on the string path only \immediate\closeout is done.
\immediate\closeout<number>
\specialA whatsit for the driver (tex.web §1354): the text is expanded now as \xdef expands, or kept unexpanded for the shipout after LuaTeX's shipout keyword. At shipout LuaTeX's PDF backend writes one whose text begins pdf: as a literal, its mode named by direct:, page:, text:, raw: or origin:, and ignores any other with Non-PDF special ignored! (crate::pdfpage does both); the whatsit is held for the page it lands on, and no shipout reaches it yet.
\special{<text>}
\special shipout{<text>}
\writeWrite a line (tex.web §1350, §1370). The text is read unexpanded and expanded when written, as \message expands its own. To an open stream it goes into the file as LuaTeX writes it -- every character raw, \newlinechar ending the line; to a negative number, the log alone; to a closed stream or one past 127, the terminal, on a line of its own. Without \immediate, on a plain document's list path (--dvi), it is a whatsit of its page, written when that page is shipped (§1373): between the page's [1 and its ] on the terminal, its registers read then, though its macros take the meanings they had at the \write. On the string path one waiting for a shipout is held and never reached.
\immediate\write<number>{<text>}
\immediate\write16{\the\count0}   % => its own line on the terminal
\immediate\write-1{log only}
\errmessageReport an error of the document's own and carry on (tex.web §1283). The text is expanded as \message expands its own and printed as tex prints an error: ! , the text, a . and the context. The help goes to the log alone in nonstop mode, so the terminal shows nothing more, and the run ends with the transcript notice.
\errmessage{<text>}
\errmessage{Bad value \the\count1 }   % => ! Bad value 5.
\relaxDo nothing. Accepted so a document can stop a number scan, or fill a slot that needs a token but no action — which is also what \csname makes of a name with no meaning.
\relax
\parEnd a paragraph. A blank line produces one, which is why the line scanner tracks its state, and in a typesetting run it reaches the page: the breaker starts a fresh paragraph, so the line before it ends where the paragraph does however short that leaves it.
\par
\ignorespacesSkip the spaces that follow (tex.web §1060). It is a mouth-level effect: the spaces are read and dropped, so what comes next is the first non-blank token. That is the whole of it here — the horizontal-mode half needs a stomach.
\ignorespaces
\def\a{\ignorespaces}
\a   X   % the spaces before X are gone
\endStop the run, and ship what it built. A document that set text comes out as Output written on NAME.pdf (N pages, N bytes).; one that only sent messages reports No pages of output., which is what real tex says for every case in the parity corpus and why the contract for those is still the \message stream.
\end
\fontnameExpands to the name of the font the next token identifies, as category-12 characters (tex.web §470, §472). A name \font defined answers its file, with at Xpt when it was loaded at another size (§472); \font is the current font; the family slots are \nullfont because \textfont is not assigned yet. A token that is not a font identifier reports Missing font identifier, is read again, and \nullfont is used.
\fontname<font identifier>
\message{\fontname\nullfont}   % nullfont
\nullfontThe null font (tex.web §552): no characters, seven zero parameters, and the current font until a font identifier is selected. Selecting it is an assignment the enclosing group undoes.
\nullfont
\message{\fontname\nullfont}   % nullfont
\fontLoad a font (tex.web §1257-§1260): \font\x=cmr10 at 12pt or scaled 1200 reads the .tfm, or reuses a font already loaded at that size, and makes \x a font identifier; selecting it is an assignment the group scopes. Characters set in it carry its metrics, ligatures and kerns. On its own, \font is the current font, which \fontname\font names.
\font\tenrm=cmr10 \tenrm
\message{\fontname\font}   % cmr10
\textfontA math family slot for text style (tex.web §230), named by a family number 0–15. \fontname\textfont<n> reads the number and gives the font in that slot, which is nullfont in texrs. Used as a number it is the wrong kind of quantity and gives Missing number.
\fontname\textfont0
\message{\fontname\textfont0}   % nullfont
\scriptfontA math family slot for script style (tex.web §230), named by a family number 0–15. \fontname\scriptfont<n> gives the font in that slot, which is nullfont in texrs. Used as a number it gives Missing number.
\fontname\scriptfont1
\message{\fontname\scriptfont1}   % nullfont
\scriptscriptfontA math family slot for scriptscript style (tex.web §230), named by a family number 0–15. \fontname\scriptscriptfont<n> gives the font in that slot, which is nullfont in texrs. Used as a number it gives Missing number.
\fontname\scriptscriptfont2
\message{\fontname\scriptscriptfont2}   % nullfont
\detokenizeThe tokens of {...} written as text, by the token-list rule: a control word carries a trailing space, a one-character control sequence does not. Nothing in the group expands. An eTeX primitive.
\message{\detokenize{\a b}}   % => \a b
\csstring\string without the escape character: \csstring\foo is foo where \string\foo is \foo. A LuaTeX primitive.
\message{\csstring\foo}   % => foo
\romannumeralA number as lowercase roman numerals, by tex.web §69's print_roman_int: \romannumeral 1984 is mcmlxxxiv. Zero and negative numbers produce NOTHING, which is why \romannumeral0 or \romannumeral-0 is the classic way to force expansion: the number scan expands everything up to the first non-digit and then vanishes. Expandable, so it works in running text, in a number position and inside a \message.
\romannumeral<number>
\message{\romannumeral 1984}   % => mcmlxxxiv
\jobnameThe job's name, as characters (tex.web §472): -jobname=NAME when the command line gives one, otherwise the input file's name without its directory or extension, and texput when the input did not come from a file. Expandable, so it works in running text and inside a \message alike.
texrs report.tex
\message{\jobname}   % => report
\UcharThe character with the given code: \Uchar65 is A. A LuaTeX primitive, and the one that reaches past 255 -- texrs reads characters rather than bytes, so it carries the whole range.
\message{\Uchar65\Uchar97}   % => Aa
\expandedExpand the group's contents completely, here and now, and put the result back. Inside an \edef it is the wrapper coming off, since everything there expands anyway; in running text it forces the expansion a macro would otherwise have deferred. An eTeX primitive.
\message{\expanded{\body}}
\unexpandedThe opposite: the group's tokens are used as they stand. Inside an \edef they survive as TOKENS, so a macro among them is called when the body runs rather than when it is defined -- which is where this and \expanded part company. In a message the two render alike, by the token-list rule. An eTeX primitive.
\edef\keep{\unexpanded{\later}}
\scantokensRead a token list again as a file: written as \meaning writes a body, cut into lines at the \newlinechar, each line ended with the \endlinechar, and tokenised as it is read -- so a \catcode inside it changes the rest. \everyeof is inserted at its end. An eTeX primitive.
\scantokens{\catcode`\@=11 \def\a@b{AB}}
\scantextokens\scantokens with no line end after the last line and nothing inserted at the end, so it can stand inside an \edef without an \everyeof. A LuaTeX primitive.
\edef\x{\scantextokens{a\relax b}}   % \x is a\relax b
\lastnamedcsThe control sequence the last \csname, \begincsname or \ifcsname looked up, put back where this stands -- so a name built once can be used again without building it twice. After a lookup that found nothing it is an undefined control sequence; after an empty name, or before any, it is nothing. A LuaTeX primitive.
\ifcsname foo\endcsname \expandafter\show\lastnamedcs \fi
\immediateassignmentCarry out the assignment that follows even while expanding. Where the lowerer reads a file the assignment runs where it stands anyway, so in running text the prefix simply vanishes; in an \edef or \message body it is not carried out. A LuaTeX primitive.
\immediateassignment\count1=5
\immediateassignedThe same for every assignment in a braced text; the braces open no group. In running text the text simply runs. A LuaTeX primitive.
\immediateassigned{\count1=5 \def\x{X}}
\begincsname\csname that does not define what it does not find: an unknown name expands to nothing, where \csname would make it \relax and leave it defined ever after. A LuaTeX primitive, and the one that makes "is this defined?" answerable without changing the answer.
\begincsname maybe\endcsname

Conditionals

PrimitiveWhat it doesSyntax and example
\ifnumCompare two numbers with <, = or >. It tests run-time state, so it lowers to a real branch — a comparison plus a jump — rather than a decision taken while walking a tree.
\ifnum<number><rel><number> <true>\else <false>\fi
\count1=5
\message{\ifnum\count1>3 BIG\else SMALL\fi}   % => BIG
\ifoddTrue when a number is odd. Reads run-time state, so it lowers to a real branch rather than folding. Negative odd numbers are odd: the test is on the remainder being non-zero, not on its sign.
\ifodd<number> <true>\else <false>\fi
\message{\ifodd\count1 ODD\else EVEN\fi}
\ifcaseSwitch on a number: the first case is 0, each \or starts the next, and \else catches everything past the last. Lowers to a real branch. A selector that is negative or past the last \or takes \else (tex.web §509), and selects nothing when there is none. A register selector is read when the run reaches the \ifcase. Pinned by tests/cases/cond_ifcase_negative.tex and tests/cases/ifcase_register_selector.tex.
\ifcase<number> <0>\or <1>\or <2>\else <other>\fi
\count1=2
\message{\ifcase\count1 ZERO\or ONE\or TWO\else MANY\fi}   % => TWO
\iftrueConstant truth. Decidable without the VM, so it is FOLDED while lowering and the untaken arm is never emitted — it does not merely jump over that code, it never emits it. This is why a \def inside the untaken arm of an \iftrue is safe where the same \def inside a run-time conditional is not; see def_in_conditional_arm.tex., so it is FOLDED while lowering and the untaken arm is never emitted.
\iftrue <true>\else <false>\fi
\iffalseConstant falsity. Folded while lowering, like \iftrue, so the taken arm is the only code that reaches the chunk.
\iffalse <true>\else <false>\fi
\ifxCompare two meanings: two macros are equal when their parameter texts and bodies match, and two primitives when they are the same primitive. Decidable from the macro table alone, so it is folded while lowering.
\ifx<token><token> <true>\else <false>\fi
\def\a{X}\def\b{X}
\message{\ifx\a\b SAME\else DIFF\fi}   % => SAME
\ifCompare two character codes after expansion. A control sequence \let to a character stands for that character (\let\x=a makes \if\x a true); any other control sequence compares equal to any OTHER control sequence, because neither has a character code to compare — that is tex.web §506's rule, not a shortcut. Both sides are expanded first, so \if\a\b tests what the macros produce, not their names. Decided in running text and inside a \message alike.
\if<token><token> <true>\else <false>\fi
\ifdefinedTrue when a control sequence has a meaning. Decidable from the macro table alone, so it is FOLDED while lowering and only the taken arm is emitted. An undefined name is false rather than an error, which is the one place an undefined control sequence is not a divergence here.
\ifdefined<token> <true>\else <false>\fi
\elseStart the false arm of a conditional. Both arms are collected as token runs and lowered, so the untaken one is real code the VM jumps over rather than a subtree nobody walked.
\else
\orStart the next case of an \ifcase: the case before the first \or is 0, and each \or moves to the next.
\or
\fiEnd a conditional. A control word swallows the space after it, so \fi X prints X with no leading space.
\fi
\ifcatCompare two category codes after expansion, reading each operand as \if does (tex.web §506-§507): a control sequence \let to a character has that character's category, and any other one reads as \relax, so \ifcat\relax\def is true and \ifcat a1 is false. Decided in running text and inside a \message alike.
\ifcat<token><token> <true>\else <false>\fi
\ifdimCompare two dimensions. tex.web §503 shares the comparison with \ifnum and differs only in the scanner, and a dimension is an integer in a slot here, so this lowers to the same run-time branch \ifnum does rather than being recognised and skipped.
\ifdim<dimen><rel><dimen> <true>\else <false>\fi
\dimen1=2pt
\ifdim\dimen1>1pt \message{[WIDER]}\else \message{[NARROWER]}\fi   % => [WIDER]
\ifvoidIs box register N empty? A real branch on the register as the program holds it (tex.web §505): the stomach mirrors each register's kind into a slot, so \setbox0\hbox{} makes \ifvoid0 false. In a LaTeX document, whose boxes are not built as lists, it is decided while lowering and every register is void. The reference tex loads plain.tex, which fills \box0 and puts an \hbox in \box11, so those two disagree the way \count0 does.
\ifvoid<N> <true>\else <false>\fi
\ifvoid200 \message{[EMPTY]}\else \message{[FULL]}\fi   % => [EMPTY]
\ifhboxDoes box register N hold an \hbox? A real branch on the kind the stomach mirrors, as \ifvoid is.
\ifhbox<N> <true>\else <false>\fi
\ifhbox200 \message{[H]}\else \message{[NO]}\fi   % => [NO]
\ifvboxDoes box register N hold a \vbox? A real branch on the kind the stomach mirrors, as \ifvoid is.
\ifvbox<N> <true>\else <false>\fi
\ifvbox200 \message{[V]}\else \message{[NO]}\fi   % => [NO]
\ifvmodeTrue in vertical mode, internal or not (§501). In a plain document the lowerer follows the semantic nest, so the test is decided where it is read. In a LaTeX document, whose lists the stomach does not build, reaching one stops the run with ! Unsupported conditional \NAME..
\ifvmode <true>\else <false>\fi
\ifhmodeTrue in horizontal mode, restricted or not (§501). In a plain document the lowerer follows the semantic nest, so the test is decided where it is read. In a LaTeX document, whose lists the stomach does not build, reaching one stops the run with ! Unsupported conditional \NAME..
\ifhmode <true>\else <false>\fi
\ifmmodeTrue in math mode, in a display or not (§501). In a plain document the lowerer follows the semantic nest, so the test is decided where it is read. In a LaTeX document, whose lists the stomach does not build, reaching one stops the run with ! Unsupported conditional \NAME..
\ifmmode <true>\else <false>\fi
\ifinnerTrue in an inner mode (§501): internal vertical, restricted horizontal, or math that is not a display. Decided while lowering in a plain document; in a LaTeX document reaching one stops the run with ! Unsupported conditional \NAME..
\ifinner <true>\else <false>\fi
\ifeofTrue when a \read stream is closed (tex.web §501): every stream is, until \openin finds a file, and again once \closein closes it or a \read finds nothing left. The number is a four-bit integer, and one out of range is Bad number and reads as 0.
\ifeof<N> <true>\else <false>\fi
\ifcsnameIs the name built from these characters defined? etex.ch's if_cs_code reads them exactly as \csname does and then looks the name up with no_new_control_sequence still true, so a name it does not find is NOT entered — which is the whole difference from \csname, whose lookup DEFINES what it misses as \relax (tex.web §372) and so changes the answer for every later ask. Decided while lowering, in running text and inside a \message body alike, because the macro table is a frontend fact. LaTeX's \@ifundefined is built on this.
\ifcsname <characters>\endcsname <true>\else <false>\fi
\def\foo{F}
\ifcsname foo\endcsname \message{[YES]}\else \message{[NO]}\fi   % => [YES]
\ifcsname nope\endcsname \message{[YES]}\else \message{[NO]}\fi  % => [NO], twice over
\ifabsnum\ifnum on the magnitudes: each side is made positive before the comparison, so \ifabsnum -5>3 is true. A LuaTeX primitive.
\ifabsnum <number><relation><number> <true>\else <false>\fi
\ifabsdim\ifdim on the magnitudes, as \ifabsnum is to \ifnum. A LuaTeX primitive.
\ifabsdim -2pt<1pt \message{no}\else\message{yes}\fi   % => yes
\ifincsnameTrue while a \csname, \ifcsname or \begincsname is reading its name, so a macro can tell it is being expanded into one. A LuaTeX primitive.
\csname\ifincsname in\else out\fi\endcsname   % names \in
\ifprimitiveIs the next token, unexpanded, a primitive that still means itself? A \let copy under another name is not, and neither is a primitive's name once something has redefined it. A LuaTeX primitive.
\ifprimitive\relax \message{untouched}\fi
\ifconditionNothing at all where it is expanded, and a conditional to text that is being skipped, so a macro that stands for a test can be written \ifcondition\mytest and still nest. A LuaTeX primitive.
\ifcondition\ifnum1=1 \message{yes}\fi
\currentiflevelHow many conditionals are open where it is read, a read-only integer -- a conditional whose text is running, whether the lowerer decided it or the run will. The one whose test is being read does not count yet. An eTeX primitive.
\iftrue\iftrue \count1=\currentiflevel \fi\fi   % \count1 is 2
\currentiftypeWhich conditional is innermost, in luatex's numbering: \if 1, \ifnum 3, \ifx 13, \iftrue 15, \ifcase 17, \ifdefined 18, \ifcsname 19, \ifabsnum 23 and so on, negative under \unless, 0 outside every one. An eTeX primitive.
\unless\ifx ab \message{\the\currentiftype}\fi   % => -13
\currentifbranchWhich text of the innermost conditional is running: 1 the true text, -1 the \else text, 0 outside every conditional. An eTeX primitive.
\iffalse\else \message{\the\currentifbranch}\fi   % => -1
\unlessNegate the conditional that follows: \unless\ifnum 1>2 A\else B\fi runs A. An eTeX primitive. A negated conditional is the same conditional with its arms exchanged, which is how it is lowered.
\unless\ifnum \count0>2 few\else many\fi

Registers

PrimitiveWhat it doesSyntax and example
\countA count register. There are exactly 256 of them (tex.web §236) and they map onto VM slots 0..255, so a read is an array index rather than a hash lookup. texrs loads no format, so every register starts at zero as INITEX leaves them — where the reference tex has plain's values, including \count0 = the page number.
\count<N>=<number>
\count1=7
\message{\the\count1}   % => 7
\advanceAdd to a register. Lowers to GetSlot / LoadInt / Add / SetSlot — native ops the JIT can compile.
\advance\count<N> by <number>
\count1=7 \advance\count1 by 5
\message{\the\count1}   % => 12
\multiplyMultiply a register. Like the other arithmetic, it lowers to native fusevm ops on the register's slot rather than a call.
\multiply\count<N> by <number>
\count1=7 \multiply\count1 by 3   % => 21
\divideDivide a register, truncating toward zero as TeX's does.
\divide\count<N> by <number>
\count1=7 \divide\count1 by 2   % => 3
\charSet the character of a code in the text (tex.web §1110): A\char66 C sets ABC. The code is scanned as a number and must be known while lowering, so a register is refused; a code outside 0..255 is Bad character code. A name made by \chardef does the same without the command.
A\char66 \char"43
\chardefDefine a control sequence that IS a number: \chardef\active=13 makes \active usable wherever a number is scanned, which is how plain.tex writes \catcode\~=\active. The code is 0..255 and a wider one is ! Bad character code (N).. The value is fixed when it is defined, so it folds while lowering rather than being read at run time.
\chardef\active=13
\catcode`\~=\active
\countdefGive a count register a name, usable in every position the register itself is: assignment, \advance and \the all reach the same register through either spelling. plain.tex's \pageno is \countdef\pageno=0. The register number is 0..255 and a wider one is ! Bad register code (N)..
\countdef\pageno=0
\pageno=7
\advance\pageno by 1
\mathcodeHow a character is set in math mode, as a 15-bit code: class, family and position. INITEX gives a letter §7100+c, a digit §7000+c and everything else its own code, so \mathcode\A is "7141 and \mathcode\+ is 43. Written and read like \catcode, and restored at the end of a group the same way.
\mathcode`\x="2201
\lccodeA character's lowercase form, which is what \lowercase consults. INITEX sets it for the letters and leaves it 0 for everything else -- a character with no case is not lowercased to a null, it is left alone.
\lccode`\A=`\a
\uccodeThe same for uppercase, consulted by \uppercase. Also 0 for a character with no case.
\uccode`\a=`\A
\sfcodeThe space factor a character leaves behind, which stretches the space after it. INITEX gives every character 1000 except an uppercase letter, which gets 999 -- that is what stops a sentence appearing to end at the full stops in "N.A.S.A.".
\sfcode`\A=999
\delcodeA character's meaning as a delimiter, as a 24-bit code naming a small and a large variant. INITEX gives -1 everywhere, meaning "not a delimiter", except the period, whose code is 0.
\delcode`\(="161361
\mathchardefDefine a control sequence standing for a math code, as \chardef does for a character code. The range runs to "7FFF and a wider value is ! Bad mathchar (N)..
\mathchardef\half="2201
\mathcode`\y=\half
"A hexadecimal constant, and ' an octal one (tex.web \u{a7}445). The hex digits are UPPERCASE: "FF is 255 and "ff is an error -- the opposite of ^^ notation, which takes lowercase. plain.tex writes every \mathcode as a hexadecimal constant.
\count1="FF   % 255
\count2='777  % 511
\dimenA dimension register. A dimension is an integer count of scaled points, 65536 to the printer's point, and a unit is an exact integer ratio to a point (tex.web §458) rather than a float -- which is why 1in is 72.26999pt. The units are pt, in, pc, cm, mm, bp, dd, cc and sp, plus §455's two font-dependent ones: em is the current font's quad (\fontdimen6) and ex its x-height (\fontdimen5), so a factor multiplies them rather than being converted -- 1em is 10.00002pt and 1ex is 4.30554pt in cmr10, the font this engine sets in. \the writes one back by Knuth's print_scaled (§103), the fewest digits that read back as the same integer, and \number gives the scaled points instead.
\dimen0=1in
\message{\the\dimen0}   % => 72.26999pt
\dimendefGive a dimension register a name, as \countdef does for a count. The name behaves as the register does on both sides: an assignment through it reads a dimension, and \the through it writes one.
\dimendef\dimen@=0
\dimen@=2pt
\skipA glue register: a natural dimension that can stretch and shrink. The stretch and shrink may be infinite -- fil, fill, filll -- and an infinite component beats any finite one however large, which is what \hfil is made of. \the writes the components back with plus and minus, omitting a zero one, and \number gives the natural component alone.
\skip0=1pt plus 2pt minus 3pt
\skip1=0pt plus 1fil
\skipdefGive a glue register a name, as \countdef and \dimendef do for theirs. An assignment through the name reads a whole glue, not the dimension at the front of one.
\skipdef\skip@=0
\skip@=1pt plus 2pt
\muskipA MATH glue register: the same natural-plus-stretch-minus-shrink a \skip holds, measured in mu. tex.web §455 makes mu the only finite unit a math glue may be written in, and the only place mu is a unit at all — \muskip0=1pt and \dimen0=1mu are both ! Illegal unit of measure. The arithmetic is a point's: a mu is 65536ths, so \advance, \multiply and a group's save and restore are the ones \skip already had. An infinite component is still fil, fill or filll, in either kind of glue.
\muskip0=3mu plus 1mu minus 2mu
\message{[\the\muskip0]}   % => [3.0mu plus 1.0mu minus 2.0mu]
\muskipdefGive a math glue register a name, as \skipdef does for an ordinary one. The name stands for the register everywhere the spelt-out form works, and only where a math glue is wanted: a \muskipdef name is not accepted as the source of a \skip assignment, nor the other way about.
\muskipdef\thinmuskip=0
\thinmuskip=3mu
\toksA token register: a token list stored VERBATIM, since nothing inside the braces expands -- which is the difference between it and a macro, and why \toks0={\x} reads back as \x whatever \x means. \toks1=\toks0 copies one register to another. \the writes the list back by the token-list rule rather than \string's: a control word carries a trailing space however short, a one-character control sequence does not.
\toks0={a\b c}
\message{\the\toks0}   % => a\b c
\toksdefGive a token register a name, as \countdef does for a count. The list is frontend state like a macro body rather than a number in a slot, so the name stands for the register itself.
\toksdef\toks@=0
\toks@={...}
\attributeLuaTeX's attribute registers, 65536 of them: unset until assigned, which \the prints as -2147483647, and scoped by a group like a count. Their values are frontend state, so a conditional over one is decided while lowering.
\attribute N=V
\attribute5=3 \message{\the\attribute5}   % => 3
\attributedefGive an attribute register a name, as \countdef does for a count; \meaning writes the register (\attribute5).
\attributedef\a=5
\a=3
\numexprAn integer expression, closed by an optional \relax: +, -, *, / with ordinary precedence and parentheses. Division ROUNDS, half away from zero, so \numexpr 7/2 is 4 where \divide gives 3 -- the two are different operations and texrs keeps them apart. A multiplication followed by a division is one scaling, 7*11/3 taken without the product overflowing, and a step outside the integer range makes the whole expression zero with ! Arithmetic overflow. A register operand is read when the program runs, so \count2=\numexpr\count1*3\relax uses the value \count1 has then. An eTeX primitive, so the oracle for it is LuaTeX rather than tex; tests/luatex_cases holds the comparison.
\count0=\numexpr (2+3)*4\relax   % => 20
\dimexprThe same for dimensions: the operands are lengths and the multiplier and divisor are integers, so \dimexpr 1pt*3 is three points. The arithmetic happens in scaled points, which is the only form a dimension has, and is bounded by the largest dimension rather than the largest integer.
\dimen0=\dimexpr 1pt+2pt\relax   % => 3.0pt
\gluestretchThe stretch of a glue, as a dimension: \gluestretch\skip0 is 2.0pt for 1pt plus 2fil, whatever its order. \glueshrink is the shrink. eTeX primitives; the glue may be a register the run holds.
\dimen0=\gluestretch\skip0
\glueshrinkThe shrink of a glue, as a dimension; see \gluestretch.
\dimen0=\glueshrink\skip0
\gluestretchorderThe order of a glue's stretch as LuaTeX counts it: 0 finite, 1 fi, 2 fil, 3 fill, 4 filll. \glueshrinkorder is the shrink's.
\count0=\gluestretchorder\skip0
\glueshrinkorderThe order of a glue's shrink, LuaTeX's numbering; see \gluestretchorder.
\count0=\glueshrinkorder\skip0
\eTeXgluestretchorderThe order of a glue's stretch as e-TeX counts it: 0 finite, 1 fil, 2 fill, 3 filll.
\count0=\eTeXgluestretchorder\skip0
\eTeXglueshrinkorderThe order of a glue's shrink as e-TeX counts it.
\count0=\eTeXglueshrinkorder\skip0
\glueexprA glue expression, the same grammar as \numexpr over glue. Addition is componentwise with TeX's order rule -- an infinite component beats a finite one however large, a higher infinity beats a lower, and only equal orders add -- while * and / scale every component. A higher-order stretch or shrink REPLACES the one it meets even when it is being subtracted, as luatex's scan_expr does. An eTeX primitive. A register operand is read when the program runs.
\skip0=\glueexpr 1pt plus 2pt+3pt plus 4fil\relax
\muexprThe same expression grammar over MATH glue, and the only kind of expression a \muskip assignment accepts — eTeX gives each unit its own primitive so the two cannot be mixed. Its operands are math glue, and like \glueexpr's they may be registers the run holds.
\muskip0=\muexpr 3mu plus 1mu + 2mu plus 2mu\relax   % => 5.0mu plus 3.0mu
\gluetomuThe glue that follows, read as MATH glue: the same width, stretch and shrink, each point taken as one mu. eTeX's way across the wall \muexpr keeps between the two kinds.
\skip0=1pt plus 2pt \muskip0=\gluetomu\skip0   % => 1.0mu plus 2.0mu
\mutoglueThe math glue that follows, read as ordinary glue: the same width, stretch and shrink, each mu taken as one point. The inverse of \gluetomu.
\muskip1=3mu minus 1mu \skip1=\mutoglue\muskip1   % => 3.0pt minus 1.0pt

Boxes

PrimitiveWhat it doesSyntax and example
\setboxAssign a box register (tex.web §1241, §1077): the box after the optional = is built while the program runs and stored in register N. The register is an eqtb entry, so a \setbox inside a group is undone at the group's end and a \global\setbox is not (§283). The list commands are the stomach's in a plain document; a LaTeX document's prelude defines \hbox as a text macro, so there they are not built.
\setbox<N>=<box>
\font\tenrm=cmr10 \tenrm
\setbox0\hbox{abc}\message{[\the\wd0]}   % => [15.27782pt]
\hboxBuild a horizontal list and package it (§1083-§1086): to <dimen> sets it to that width, spread <dimen> that much wider than natural, and the glue inside is set by §649's hpack. Characters go through the font's ligature and kern program (§1034-§1040), spaces become the font's interword glue (§1041-§1044), and \everyhbox is inserted after the brace.
\hbox to<dimen>{...}  \hbox spread<dimen>{...}  \hbox{...}
\vboxBuild a vertical list and package it with §668's vpackage, its depth limited by \boxmaxdepth; boxes on it are separated by \baselineskip glue as §679 computes it. A paragraph inside one needs the paragraph builder, which the list path does not have yet, and is refused with a message saying so.
\vbox to<dimen>{...}  \vbox{\hbox{a}\hbox{b}}
\vtopA \vbox whose reference point is its first box's baseline (§1087): the height is the first item's, the rest is depth.
\vtop{\hbox{a}\hbox{b}}
\boxThe box in register N, which leaves the register void (§1079) -- at the same level, so no group brings it back.
\box<N>
\copyThe box in register N, leaving the register as it was.
\copy<N>
\lastboxThe last box of the current list, taken off it with its shift cleared (§1080-§1081); void when the list does not end with a box, and refused in math mode and on the page's own list.
\setbox0\lastbox
\vsplitSplit a vbox register at the best place for a box of the given height (§977-§979): the top part is returned packed to that height, the register keeps the rest with \splittopskip above it, and the marks of the top part become \splitfirstmark and \splitbotmark.
\setbox1=\vsplit0 to 20pt
\wdThe width of box register N, readable wherever a dimension is (\the\wd0, \ifdim\wd0>\hsize, .5\wd0) and assignable (§1247): the box changes in place, and a void register stays void and reads zero. The value is mirrored into a VM slot by the stomach, so a read is a register read.
\wd<N>=<dimen>
\message{[\the\wd0]}
\htThe height of box register N, read and assigned as \wd is.
\ht<N>=<dimen>
\dpThe depth of box register N, read and assigned as \wd is.
\dp<N>=<dimen>
\showboxDisplay box register N as §1296 and §173-§198 do -- nesting dots, unit-less glue, \showboxdepth and \showboxbreadth -- and stop with ! OK.. With \tracingonline zero the display goes to the log alone and the terminal says ! OK (see the transcript file)..
\tracingonline1 \showbox0
\unhboxAppend the contents of an hbox register to the current horizontal list and void the register (§1110); \unhcopy keeps it. Unboxing a vbox here is Incompatible list can't be unboxed.
\unhbox<N>  \unhcopy<N>
\unvboxThe vertical counterpart of \unhbox (§1110); \unvcopy keeps the register.
\unvbox<N>  \unvcopy<N>
\raiseShift the box that follows up in a horizontal list (§1073): a NEGATIVE shift_amount, because DVI's vertical axis points down. \lower shifts it down; \moveleft and \moveright do the same in a vertical list.
\raise2pt\hbox{a}  \lower1pt\copy4
\hskipGlue in a horizontal list (§1060), from a glue specification or a \skip register; \hfil, \hfill, \hss and \hfilneg are the four fixed ones of §1058. \vskip and its four are the vertical versions.
\hskip 3pt plus 1fil minus 1pt  \hfil  \hss
\kernA rigid space in the current list (§1061), explicit -- which \showbox marks with a space after \kern and a break may discard.
\kern 3pt
\penaltyA penalty node (§1103). \unpenalty, \unkern and \unskip remove the last node of the current list when it is of that kind (§1105).
\penalty-50  \unpenalty
\hruleA rule in a vertical list, 0.4pt tall and as wide as the box it lands in unless width, height and depth say otherwise (§463); the box after it gets no interline glue (§1056). \vrule is the horizontal-list rule, 0.4pt wide.
\hrule height 2pt  \vrule width 1pt
\leadersGlue filled with copies of a box or a rule (§1078): the box or rule, then the glue it fills. \cleaders centres the copies and \xleaders spreads them.
\leaders\hrule\hfil  \cleaders\hbox{.}\hfil
\discretionaryA discretionary break with its pre-break, post-break and replacement lists, each built in restricted horizontal mode (§1117-§1121). \- is one whose pre-break text is the font's hyphen character.
\discretionary{a}{b}{c}  ab\-cd
\markA mark node holding its text, expanded as \message expands it (§1101).
\mark{hello}
\topmarkThe mark that was \botmark when the current page began (§1012), read as the tokens it was written with; empty on the first page. In a paragraph, a box or a formula each mark the document has written is a branch on which one the page builder holds when the program runs. Inside an \edef or a \message it expands to nothing, and in vertical mode once a mark exists it is refused as unsupported.
\headline={\hfil\topmark}
\firstmarkThe first mark on the page the output routine is working on, or \topmark when the page has none (§1014, §1012). Read as \topmark is.
\headline={\firstmark\hfil}
\botmarkThe last mark on the page the output routine is working on (§1014). Read as \topmark is.
\footline={\hfil\botmark}
\splitfirstmarkThe first mark in the material the last \vsplit took off (§979). Read as \topmark is.
\setbox2\vsplit1 to 1in [\splitfirstmark]
\splitbotmarkThe last mark in the material the last \vsplit took off (§979). Read as \topmark is.
\setbox2\vsplit1 to 1in [\splitbotmark]
\showlistsShow what is being built at every level of the semantic nest, innermost first (§218-§219): each list with the mode it is in and the line it began on, a formula's noads (§690-§697), \prevdepth, \spacefactor or the fraction waiting for its denominator, and at the bottom the current page with its total and goal heights and the insertions on it (§986), then the recent contributions. A diagnostic, on the terminal when \tracingonline is positive, then ! OK.
\tracingonline1 Some text \hbox{in a box} $x^2\showlists$
\deadcyclesHow many times the output routine has run since a page was last shipped (§592): past \maxdeadcycles the page builder ships the page itself. Assigned in place (§1246), as an output routine that holds a page back does.
\output={\global\setbox1\box255 \deadcycles=0 }
\insertpenaltiesThe sum of the penalties of the insertions held over to the next page (§982), and in the output routine the number of insertions held over (§1018). Assigned in place (§1246).
\showthe\insertpenalties
\pagegoalThe height the current page is being filled to (§982): \vsize less what the insertions on it take, \maxdimen before the page has a box. Assigned in place (§1245), which is how an output routine says how much room is left.
\pagegoal=\maxdimen
\pagetotalThe natural height of the current page so far (§982). Assigned in place (§1245).
\showthe\pagetotal
\pagestretchThe finite stretch of the glue on the current page (§982); \pagefilstretch, \pagefillstretch and \pagefilllstretch are the infinite orders. Assigned in place (§1245).
\showthe\pagestretch
\pagefilstretchThe fil stretch on the current page (§982), as \pagestretch is the finite one.
\showthe\pagefilstretch
\pagefillstretchThe fill stretch on the current page (§982).
\showthe\pagefillstretch
\pagefilllstretchThe filll stretch on the current page (§982).
\showthe\pagefilllstretch
\pageshrinkThe shrink of the glue on the current page (§982). Assigned in place (§1245).
\showthe\pageshrink
\pagedepthThe depth of the last box on the current page (§982). Assigned in place (§1245).
\showthe\pagedepth
\halignA table of rows (§768-§812): a preamble of templates, u#v per column between &s and ended by \cr, then rows whose entries are read inside their column's templates. Each entry is set at its natural width, each column as wide as its widest entry (and the entries spanning it, §798), and the rows are packed to or spread the size given, with \tabskip glue between the columns. In a display it is the display (§1206), which is how plain.tex's \eqalignno and \displaylines are built.
\halign{#\hfil&\hfil#\cr name&value\cr alpha&1\cr}
\valign\halign turned on its side (§768): columns of entries set in vertical mode, whose heights are aligned across the columns.
\hbox{\valign{\hbox{#}\vfil\cr a\cr b\cr}}
\crEnd a row of an alignment, or its preamble (§780, §791): the last entry's v template is read, the entry and the row are finished, and \everycr is inserted. Outside an alignment it is the error Misplaced \cr.
a&b\cr
\crcr\cr, except that right after a \cr (or at the start of the alignment's body) it does nothing (§785), so a macro can end a row whether or not its argument already did.
\halign{#\cr a\cr\crcr}
\spanIn an alignment's body, join the entry to the next column's, so the two are set as one entry spanning both (§791, §798); in a preamble, expand the token after it (§782).
\halign{#&#\cr a\span b\cr}
\omitAt the start of an entry, leave out its column's templates (§788-§789).
\halign{[#]&#\cr \omit a&b\cr}
\noalignBetween two rows of an alignment, material for the list the rows are in, in its own group (§785, §1133): a rule, a skip, a penalty.
\halign{#\cr a\cr\noalign{\hrule}b\cr}
\insertAn insertion of class N, its vertical list built in internal vertical mode and packed with \splittopskip, \splitmaxdepth and \floatingpenalty as they stand at its end (§1099-§1100). \vadjust is the same with material for the enclosing vertical list.
\insert100{\hbox{n}}  \vadjust{\kern2pt}
\shipoutShip the box that follows as a page (§638-§641): the terminal says [ and \count0..9 and ], as tex does.
\shipout\hbox{page}
\unhcopy\unhbox that leaves the register as it was (§1110).
\unhcopy<N>
\unvcopy\unvbox that leaves the register as it was (§1110).
\unvcopy<N>
\lowerShift the box that follows down in a horizontal list: a positive shift_amount (§1073).
\lower1pt\hbox{a}
\moveleftShift the box that follows left in a vertical list: a negative shift_amount (§1073).
\moveleft2pt\hbox{a}
\moverightShift the box that follows right in a vertical list (§1073).
\moveright2pt\hbox{a}
\hfil\hskip 0pt plus 1fil (§1058).
\hfil
\hfill\hskip 0pt plus 1fill (§1058).
\hfill
\hss\hskip 0pt plus 1fil minus 1fil (§1058), which lets a box shrink past its contents.
\hbox to 0pt{\hss x}
\hfilneg\hskip 0pt plus -1fil (§1058), cancelling one \hfil.
\hfilneg
\vskipGlue in a vertical list (§1060), as \hskip is in a horizontal one.
\vskip 4pt plus 1fil
\vfil\vskip 0pt plus 1fil (§1058).
\vfil
\vfill\vskip 0pt plus 1fill (§1058).
\vfill
\vss\vskip 0pt plus 1fil minus 1fil (§1058).
\vss
\vfilneg\vskip 0pt plus -1fil (§1058).
\vfilneg
\vruleA rule in a horizontal list, 0.4pt wide and as tall and deep as the box it lands in unless width, height and depth say otherwise (§463).
\vrule width 1pt
\cleadersLeaders whose copies are centred in the glue (§1078, §626).
\cleaders\hbox{.}\hfil
\xleadersLeaders whose leftover space is spread between the copies (§1078, §626).
\xleaders\hbox{.}\hfil
\unpenaltyRemove the last node of the current list if it is a penalty (§1105).
\unpenalty
\unkernRemove the last node of the current list if it is a kern (§1105).
\unkern
\unskipRemove the last node of the current list if it is glue (§1105); on the page's own list, where the page builder has the node, it does nothing.
\unskip
\vadjustMaterial for the vertical list enclosing the paragraph, built in internal vertical mode (§1099-§1100).
\vadjust{\kern2pt}
\prevdepthThe depth of the last box on the current vertical list, which the next interline glue is computed from (§679); assignable in vertical mode (§1242). -1000pt means no interline glue before the next box.
\prevdepth=-1000pt
\spacefactorThe space factor of the current horizontal list (§1034, §1043), read and assigned in horizontal mode.
\spacefactor=3000
\indentIn horizontal mode, an empty box \parindent wide (§1093). Starting a paragraph with it in vertical mode needs the paragraph builder, which the list path does not have yet.
\hbox{\indent x}
\noindentIn horizontal mode, nothing (§1093). Starting a paragraph with it in vertical mode needs the paragraph builder, which the list path does not have yet.
\hbox{\noindent x}
\noboundaryCancel the font's boundary character on that side of the next or previous run of characters (§1034, §1038), so a boundary ligature or kern is not made.
\hbox{\noboundary ab}
\prevgrafThe number of lines in the most recent paragraph of the nearest enclosing vertical list (§422), read and assigned (§1244).
\prevgraf=2
\fontdimenFont parameter N of a font (tex.web §558, §578): read as a dimension, and assigned globally (§1253). Writing past the last parameter of the font loaded last makes room for it; past any other font's is Font ... has only N fontdimen parameters.
\fontdimen2\tenrm=4pt
\message{\the\fontdimen6\tenrm}
\hyphencharThe character a font hyphenates with (§1253): \- puts it in a discretionary and the main loop follows each one it sets with an empty discretionary. -1 turns both off.
\hyphenchar\tentt=-1
\skewcharThe character whose kerns position a font's math accents (§1253).
\skewchar\teni='177
\patternsLiang hyphenation patterns (§960), the characters between the braces, for the paragraph builder's second pass. hyphen.tex is read this way by plain.tex.
\patterns{.ach4 .ad4der}
\accentPut character N of the current font over the character that follows (§1123-§1125): raised or lowered by the difference between the font's x-height and the character's height, centred over it and moved by the two slants, between two kerns (for accent). Font selections and integer parameters between the two are carried out first, so \accent"7F\it e takes the e from the italic font. In math mode it is the error Please use \mathaccent for accents in math mode, after which it is read as \mathaccent.
\accent N<character>
\accent"13 e   % plain.tex's \'e
\parshapeGive the next paragraph a shape line by line (§1248): n, then n pairs of indentation and width; lines past the nth take the last pair. Takes the place of \hangindent and \hangafter while it is set, sets a display's width and indentation on the line it falls on (§1149), and is reset by the end of the paragraph (§1070) and by its group. \the\parshape is not read on the list path yet.
\parshape 2 0pt 4in 1in 3in
A first line four inches wide, the rest three inches wide and indented an inch.\par
\hyphenationWords with their hyphens written in (§934), which the second pass takes over the patterns.
\hyphenation{man-u-script}

Mathematics

PrimitiveWhat it doesSyntax and example
\mathordMake the next math field an Ord atom (§1158). \mathop, \mathbin, \mathrel, \mathopen, \mathclose, \mathpunct and \mathinner make the other seven classes; the class decides the spacing §764's table puts around the atom. The field is a character or a subformula in braces (§1151).
$\mathord{+}x$
\mathopAn Op atom (§1158): a large operator, with limits above and below in display style unless \nolimits says otherwise (§749).
$\mathop{\rm sup}\limits_x f$
\mathbinA Bin atom (§1158): a binary operator, which §728 turns into an Ord where nothing binary surrounds it, and after which §767 allows a break at \binoppenalty.
$a\mathbin{\#}b$
\mathrelA Rel atom (§1158): a relation, with thick spaces either side and a break after it at \relpenalty (§767).
$a\mathrel{:=}b$
\mathopenAn Open atom (§1158): an opening bracket, after which §764 puts no space.
$\mathopen{[}x$
\mathcloseA Close atom (§1158): a closing bracket, before which §764 puts no space.
$x\mathclose{]}$
\mathpunctA Punct atom (§1158), with a thin space after it outside the script styles.
$x\mathpunct{;}y$
\mathinnerAn Inner atom (§1158), the class a \left..\right subformula gets (§1191).
$\mathinner{\ldotp\ldotp\ldotp}$
\underlineAn Under atom (§1158): its nucleus with a rule default_rule_thickness thick below it (§735).
$\underline{ab}$
\overlineAn Over atom (§1158): its nucleus with a rule above it, cramped (§734).
$\overline{ab}$
\limitsAfter an Op atom, set its scripts above and below in every style (§1159); elsewhere it is the error Limit controls must follow a math operator.
$\sum\limits_{i=1}^n$
\nolimitsAfter an Op atom, set its scripts beside it in every style (§1159).
$\int\nolimits_0^1$
\displaylimitsAfter an Op atom, the default: limits above and below in display style only (§1159).
$\mathop{\rm max}\displaylimits_x$
\radicalA radical noad with a 24-bit delimiter code, over the next field (§1163); plain.tex's \sqrt is \radical"270370. The sign grows to the height of its nucleus plus the clearance §737 computes.
$\radical"270370{x+1}$
\mathaccentAn accent noad with a 15-bit math code, over the next field (§1165); \accent in math mode is the error Please use \mathaccent for accents in math mode and is taken as this. The accent is moved right by the \skewchar kern of the accented character (§741).
$\mathaccent"705E x$
\vcenterA vbox centred on the math axis (§1167-§1168, §736), as a noad of its own; to and spread are read as for \vbox.
$\vcenter{\hbox{a}\hbox{b}}$
\displaystyleA style node (§1171): what follows is set in display style. \textstyle, \scriptstyle and \scriptscriptstyle select the other three; each changes the size the families are read at (§703).
$\displaystyle{a\over b}$
\textstyleA style node for text style (§1171).
$$\textstyle\sum_i x_i$$
\scriptstyleA style node for script style (§1171): the script size fonts.
$\scriptstyle a+b$
\scriptscriptstyleA style node for scriptscript style (§1171).
$\scriptscriptstyle a+b$
\nonscriptGlue that deletes the glue or kern right after it when the formula is in a script style (§1171, §732).
$a\nonscript\mskip\thinmuskip b$
\mathchoiceFour subformulas, for display, text, script and scriptscript style; the one the style at that point asks for is set (§1172-§1174, §731). plain.tex's \mathpalette is built on it.
$\mathchoice{D}{T}{S}{SS}$
\overMake everything so far in the subformula the numerator and everything after it the denominator, with a bar default_rule_thickness thick (§1181-§1185). Two in one subformula is Ambiguous; you need another { and }.
${n+1\over2}$
\atopA fraction with no bar (§1182).
${n\atop k}$
\aboveA fraction with a bar of the thickness given (§1182).
${a\above1pt b}$
\overwithdelims\over with a delimiter on each side, each grown to delim1 or delim2 (§748); \atopwithdelims and \abovewithdelims likewise. plain.tex's \choose is \atopwithdelims().
${a\overwithdelims() b}$
\atopwithdelims\atop with delimiters (§1182).
${n\atopwithdelims() k}$
\abovewithdelims\above with delimiters (§1182).
${a\abovewithdelims[]1pt b}$
\leftOpen a subformula whose delimiters grow to its height and depth (§1191, §762); it ends at the matching \right and becomes an Inner atom. A delimiter is a character with a \delcode, \delimiter, or . for none.
$\left(a\over b\right)$
\rightClose the \left subformula (§1191); outside one it is Extra \right.
$\left[x\right.$
\eqnoIn a display, set what follows to the closing $$ as the equation number, at the right (§1142, §1199-§1205); a display too wide to share its line puts the number on a line of its own.
$$a^2+b^2=c^2\eqno(1)$$
\leqnoThe same with the number at the left (§1142, §1203).
$$x=1\leqno(2)$$
\mkernA kern in math units: eighteen mu are the quad of the family 2 font at the size the formula is set in (§717).
$a\mkern18mu b$
\mskipGlue in math units (§716), converted at the size it lands in; \thinmuskip, \medmuskip and \thickmuskip are the three §764's spacing table uses.
$a\mskip\thickmuskip b$
\mathcharA math character by its 15-bit code: class, family and character, as \mathcode holds them (§1154-§1155). Class 7 takes its family from \fam when that is 0..15.
$\mathchar"7141$
\delimiterA delimiter by its 27-bit code (§1160): where a delimiter is wanted it is that, and as a math character it is its class and small variant (§1154).
$\left\delimiter"426630A x\right.$

Grouping

PrimitiveWhat it doesSyntax and example
{Open a group (category code 1), which scopes the macro table AND the count registers written inside it: the lowered body is wrapped in save/restore for exactly the registers it assigns. It also delimits a macro argument.
{<body>}
\def\v{OUT}
{\def\v{IN}\message{\v}}   % => IN
\message{\v}             % => OUT
}Close a group (category code 2), undoing every non-global assignment made inside it.
{<body>}
\begingroupOpen a group without braces, scoping the macro table and the registers written inside it. It must be closed by \endgroup, not by }.
\begingroup <body>\endgroup
\endgroupClose a \begingroup, undoing every non-global assignment made since it. A } will not close one, and neither will the end of the file.
\begingroup <body>\endgroup
\aftergroupHold the next token and insert it after the enclosing group closes (tex.web §326). It goes on the SAVE STACK rather than in a list of its own, which is what makes several in one group come back in the order they were given and a nested group's tokens come out at ITS } — so a whole call can be assembled a token at a time. Outside every group there is nothing to wait for and the token is inserted at once.
\aftergroup<token>
{\aftergroup\message\aftergroup{\aftergroup X\aftergroup}}   % => X
\afterassignmentHold the next token until the following ASSIGNMENT has finished (tex.web §1269). One only: a second \afterassignment before the assignment replaces the first. A \message is not an assignment and neither is a group, so the token waits for the next \def, \let, register write or arithmetic and is inserted after it.
\afterassignment<token>
\def\m{\message{DONE}}
\afterassignment\m \count1=5   % => DONE, with \count1 already 5
\currentgrouplevelHow many groups are open, a read-only integer: 0 outside every group. An eTeX primitive.
{\message{\the\currentgrouplevel}}   % => 1
\currentgrouptypeWhat opened the innermost group, as eTeX numbers it: 0 outside every group, 1 for a brace, 14 for \begingroup.
\begingroup\message{\the\currentgrouptype}\endgroup   % => 14
\showgroupsList the open groups, innermost first, each with its level, the line it was entered on and what opened it -- ### simple group (level 1) entered at line 3 ({) -- then ### bottom level, followed by ! OK and the context. The listing reaches the terminal only under a positive \tracingonline; otherwise ! OK (see the transcript file) says where it went. An eTeX primitive.
{\tracingonline=1 \showgroups}

Intercepts

PrimitiveWhat it doesSyntax and example
\interceptRegister advice on macro expansion: before puts the handler's body in front of the expansion, after puts it behind, and around replaces it with \proceed standing for what the macro would have expanded to. The pattern is a GLOB over macro names, so advice registered now catches macros a package defines later. The handler is a macro that takes no parameters. Like \def, this takes effect at compile time and is undone by the group it was registered in.
\intercept{before|after|around}{<glob>}{\handler}
\def\greet#1{HELLO-#1}
\def\trace{[in]}
\intercept{before}{greet}{\trace}
\message{\greet{WORLD}}   % => [in]HELLO-WORLD
\proceedInside an around handler, what the intercepted macro would have expanded to. A handler with no \proceed replaces the call outright, which is how advice suppresses one. Outside an around handler it means nothing.
\def\loud{<<\proceed>>}
\intercept{around}{greet}{\loud}
\message{\greet{WORLD}}   % => <<HELLO-WORLD>>

Inline Rust

PrimitiveWhat it doesSyntax and example
\rustOpen a block of Rust compiled and loaded at run time. The body is Rust, not TeX — it is lifted out of the file BEFORE the mouth reads it, because #, {, } and & are category codes the mouth would act on. Every #[no_mangle] pub extern "C" function the block exports becomes callable with \rustcall. Needs rustc on PATH; the compiled library is cached by body hash, so a second run does not compile it again.
\rust{ <rust source> }
\rust{
    #[no_mangle]
    pub extern "C" fn twice(n: i64) -> i64 { n * 2 }
}
\rustcallCall a function a \rust block exported. The name runs to the first space, the arguments are numbers, and \endrust ends the list. It is a NUMBER wherever TeX reads one — a register assignment, an arithmetic operand, a conditional, or a \message body — and in running text it is called for its effect with the value dropped.
\rustcall <name> <numbers…>\endrust
\count1=21
\message{\rustcall twice \count1 \endrust}   % => 42
\count2=\rustcall add \count1 22 \endrust
\rustcompileWhat a \rust{ … } block becomes: compile and register the block whose base64 body follows, up to \endrust. Written by the desugarer rather than by hand, and carried in a brace-free form so it reads correctly whatever the category codes are where the block appeared.
\rustcompile <base64>\endrust
\endrustTerminate a \rustcompile body or a \rustcall argument list. A control sequence rather than a brace, so neither form depends on a category code the document may not have set yet.
\rustcall twice 21\endrust

Files

PrimitiveWhat it doesSyntax and example
\inputRead another file here, sharing every piece of state with it: a macro it defines is defined afterwards, and a \catcode it sets stays set. The name runs to the first space or end of line (tex.web §537) and .tex is supplied when it carries no extension. texrs searches the working directory and then TEXINPUTS, and asks kpsewhich only when both miss, so a document that reads the files beside it never depends on a TeX Live installation being present. Fifteen text input levels are allowed, counting the document's own, which is tex's limit and tex's wording when it is passed.
\input macros
\input chapters/one.tex
\endinputEnd the file being read with the line \endinput is on (tex.web §362): the rest of that line is still read, and nothing after it is. In the document itself that leaves no \end to find unless one is on the same line.
\endinput
\message{last}\endinput\message{still read}
\openinOpen a \read stream on a file (tex.web §1275): the stream is closed first, then opened on the file the name finds — searched for as \input searches, with .tex supplied — and left closed when nothing has it. It happens at once, whatever groups are open, and the file is read while lowering.
\openin<0-15>=<file name>
\openin3=data \ifeof3 \message{no data}\fi
\closeinClose a \read stream (tex.web §1275), so \ifeof is true for it.
\closein<0-15>
\closein3
\readDefine a macro as the next line of a stream (tex.web §482): the line is read with the category codes in force and ended by \endlinechar, and more lines are read while a brace is open. A blank line reads as \par, and so does the line a file that has run out did not have — which is when the stream closes. A closed stream reads the terminal: under the CLI, which has none, that stops the run; an embedder's run_program input answers it a line at a time.
\read<number> to <control sequence>
\openin3=data \read3 to\line \message{\meaning\line}
\readlinee-TeX's \read of one line as it stands: every character an other character and the space a space, so braces need not balance and a \ is a backslash. LuaTeX's leaves the \endlinechar off, and so does texrs.
\readline<number> to <control sequence>
\openin3=data \readline3 to\line

PDF backend

PrimitiveWhat it doesSyntax and example
\pdfvariableLuaTeX's backend parameters (textoken.c's do_variable_pdf): expands to the integer, dimension or token-list parameter its keyword names, which is then assigned, read by \the and wherever a number is scanned, and restored by a group like any parameter. The keys are luatex's 28 integers (compresslevel, objcompresslevel, decimaldigits, gentounicode, minorversion, ...), six dimensions (horigin, vorigin, the margins) and seven lists (pageattr, pageresources, pagesattr, ...); an unknown one is luatex's unexpected use of \pdfvariable warning. \the answers INITEX's zero for one nothing assigned; the file is written with what the document assigned and with luatex.fmt's values for the rest (compression 9, object streams 2, three decimal digits, PDF 1.7).
\pdfvariable compresslevel=0   % streams written plain
\message{\the\pdfvariable compresslevel}   % => 0
\pdfvariable pageresources{/ExtGState 12 0 R}
\pdffeedbackWhat LuaTeX's backend knows, as characters (do_feedback_pdf): lastobj, lastannot, lastlink and retval; pageref N, the object page N is or will be; colorstackinit [page] [direct|page|text|raw|origin] {init}, which makes a colour stack and gives its number; creationdate; fontsize <font>; version (140) and revision (0). Objects are numbered as luatex numbers them, the object stream an immediate object opens included: \immediate\pdfextension obj{...} then \pdfextension obj reserveobjnum gives 1 and 3. fontname and fontobjnum answer 0: a font is numbered by the shipout that first draws it.
\immediate\pdfextension obj{<< /A 1 >>}
\message{\pdffeedback lastobj}   % => 1
\pdfextensionLuaTeX's backend commands (do_extension_pdf), each read with luatex's keywords. Done when read: obj (reserveobjnum, useobjnum, uncompressed, stream [attr {...}], file), written then under \immediate and otherwise held for a page to refer to it; outline, whose action and title objects are written then; info, catalog (with openaction), names and trailer, which accumulate into the information dictionary, the catalogue, the /Names dictionary and the trailer; glyphtounicode, fontattr, mapfile, mapline, includechars. Placed in the list for the page they ship with: literal (direct, page, text, raw, origin, shipout), lateliteral, dest, annot, startlink/endlink, startthread/thread/endthread, save, restore, setmatrix, linkstate, refobj and colorstack; no shipout reaches those yet. Destinations an outline names are written pointing at the last page, as luatex writes one no page set, and enter the name tree.
\pdfextension outline goto name{intro} count 0 {Introduction}
\pdfextension info{/Title (A report)}
\pdfextension literal{1 0 0 rg}
\saveimageresourceRead a picture for later use (scan_pdfximage): the width/height/depth, attr, page, password, colorspace and box keywords and the file name. The picture is numbered when read, and \lastsavedimageresourceindex is the number; it is not yet read or written.
\saveimageresource width 2cm {figure.png}
\useimageresource\lastsavedimageresourceindex
\useimageresourcePlace a saved picture (scan_pdfrefximage): optional dimensions, keepopen, and the number. A whatsit for the page; no shipout reaches it yet.
\useimageresource width 1in \lastsavedimageresourceindex
\saveboxresourceSave a box as a form (scan_pdfxform): type, attr, resources, margin and the box register. The form is numbered when read and \lastsavedboxresourceindex is the number; the box itself is the stomach's, and is not yet shipped as a form.
\saveboxresource 0
\useboxresource\lastsavedboxresourceindex
\useboxresourcePlace a saved form (scan_pdfrefxform): optional dimensions and the number. A whatsit for the page.
\useboxresource\lastsavedboxresourceindex
\lastsavedimageresourceindexThe number the last \saveimageresource gave its picture: an internal integer.
\message{\the\lastsavedimageresourceindex}
\lastsavedimageresourcepagesHow many pages the last \saveimageresource's file holds: 1, since only a picture's file is counted yet.
\message{\the\lastsavedimageresourcepages}
\lastsavedboxresourceindexThe number the last \saveboxresource gave its form, assigned when the form is read; \useboxresource takes it.
\message{\the\lastsavedboxresourceindex}
\saveposA whatsit that records where on the page it is shipped, for \lastxpos and \lastypos to read after. No shipout reaches it yet, so both stay 0.
\savepos\message{\the\lastxpos}

LaTeX

PrimitiveWhat it doesSyntax and example
\newcommandDefine a macro with n positional parameters: \newcommand{\x}[2]{#1 and #2}. LaTeX writes this as a chain of \ifnum...\def, which cannot run here because lowering emits both arms of a conditional, so texrs dispatches on the argument count natively instead. Two divergences from latex.ltx: redefining an existing name is allowed rather than an error, and the [default] form's default is recorded but not yet substituted at a call that omits the bracket.
\newcommand{\NAME}[ARGC][DEFAULT]{BODY}
\newcommand{\greet}[1]{hello #1}
\message{\greet{world}}   % => hello world
\renewcommandRedefine a macro. Identical to \newcommand here, because texrs does not check whether the name already exists in either direction.
\renewcommand{\NAME}[ARGC]{BODY}
\newcommand{\x}{one}
\renewcommand{\x}{two}
\message{\x}   % => two
\providecommandDefine a macro only if the name is free. An existing definition is kept and the new body is consumed rather than left in the document as text.
\providecommand{\NAME}[ARGC]{BODY}
\newcommand{\x}{first}
\providecommand{\x}{second}
\message{\x}   % => first
\DeclareRobustCommandDefine a macro. Robustness is a property of LaTeX's expansion-in-moving-arguments machinery, which has no counterpart here, so this behaves exactly as \newcommand.
\DeclareRobustCommand{\NAME}[ARGC]{BODY}
\DeclareRobustCommand{\x}{text}
\message{\x}   % => text
\documentclassConsumed, with its arguments, and produces nothing except the page. A class is TeX that builds boxes, and nothing here runs it — the boxes on the page come from this engine's own layout rather than from the class, so the directive is read and dropped — which is what lets the REST of the document be read instead of the run failing at line one. The TYPE SIZE among its options is kept, because it needs no class to honour: [11pt] sets the text at 11pt on the 13.6pt leading size11.clo pairs with it, and --pdf sets the page from that.
\documentclass[OPTIONS]{CLASS}
\documentclass[12pt]{article}
\message{the body still runs}
\usepackageConsumed with its arguments, producing nothing, for the same reason as \documentclass: the package cannot be loaded, and dropping it reads the document minus whatever the package would have drawn. One exception: [margin=...]{geometry} is a page rather than a drawing, and --pdf sets the margins, the measure and the text height from it.
\usepackage[OPTIONS]{PACKAGE}
\usepackage[margin=0.95in]{geometry}
\RequirePackageConsumed with its optional arguments, producing nothing. Same treatment as \usepackage; the difference between them is where LaTeX allows each, which does not matter to an engine that loads neither.
\RequirePackage[OPTIONS]{PACKAGE}
\RequirePackage{amsmath}
\PassOptionsToPackageConsumed with both of its arguments, producing nothing, because the package it would have carried options to is never loaded.
\PassOptionsToPackage{OPTIONS}{PACKAGE}
\PassOptionsToPackage{dvipsnames}{xcolor}
\PassOptionsToClassConsumed with both of its arguments, producing nothing. The class counterpart of \PassOptionsToPackage.
\PassOptionsToClass{OPTIONS}{CLASS}
\PassOptionsToClass{a4paper}{article}
\beginOpen an environment. Most environments are the prelude's business, but a VERBATIM one is the lowerer's: it is caught here, before \begin expands, because expanding is exactly what must not happen to the body. A code listing is full of backslashes that are not control sequences, and reading them as control sequences is why a book of code samples could not be read at all. The body is taken as raw characters up to the matching \end.
\begin{ENVIRONMENT}
\begin{verbatim}
\this is text, not a command
\end{verbatim}
\newpageStart a new page. The prelude defined this to expand to nothing, so a book's title page, copyright page and first chapter ran together as one stream of prose and the page count came out at roughly half what the document asks for. Carried through the text as a form feed, which is what the character means, and split out before words are because Rust counts it as whitespace.
\newpage
first page
\newpage
second page
\clearpageStart a new page, after placing any pending floats. There are no floats here, so it is \newpage. Two breaks in a row are one break: \clearpage straight after \newpage does not leave a blank sheet between them.
\clearpage
\cleardoublepageStart a new page, and in a two-sided document a new RIGHT-hand one. The blank verso a two-sided run would insert is not written, so this is \clearpage here.
\cleardoublepage
\pagebreakBreak the page. \pagebreak[0-4] takes an optional strength, which is advice about how badly the break is wanted rather than a break itself; the break is taken either way, because the document asked for one.
\pagebreak
\pagebreak[4]
\chapterBegin a chapter, on a new page. The prelude defined this as its own argument -- the heading text and nothing else -- so no chapter began a page. \chapter*{...} is the unnumbered form and \chapter[short]{long} carries a running-head title; both start a page and both set the long title. The heading is not yet set in a larger face, and the number is not printed.
\chapter{TITLE}
\chapter*{Preface}
\chapter[Short]{A Longer Title}
\sectionBegin a section: the heading text, with a line of vertical space above it and a line below. The prelude defined this as its own argument, so a heading was simply the first words of the paragraph under it and the page held lines that a real run spends on white space. \section*{...} and \section[short]{long} are read the same way as \chapter's. The number is not printed and the heading is not yet set in a larger face.
\section{TITLE}
\section*{Unnumbered}
\section[Short]{A Longer Title}
\subsectionBegin a subsection. Set exactly as \section is -- its own lines, with vertical space around them -- because nothing here sets a heading in a different size yet, and the depth of a heading is otherwise invisible on the page.
\subsection{TITLE}
\subsection*{Unnumbered}
\subsubsectionBegin a subsubsection, set as \section and \subsection are: its own lines, with a line of vertical space above and below.
\subsubsection{TITLE}
\subsubsection*{Unnumbered}
\tableofcontentsSet a table of contents: one line per heading, with leader dots and the page it starts on. The prelude expanded this to nothing, so every book in the corpus opened straight on its first chapter and was short by the pages a contents takes. The page numbers cannot be known when this is read -- the contents is set before the chapters it lists, and it moves them itself -- so what goes into the text here is a REQUEST, and the typesetter breaks and paginates the document repeatedly until the numbers stop moving, which is what running latex twice does with the .aux file.
\setcounter{tocdepth}{0}
\tableofcontents
\chapter{First}
\setcounterSet a counter. Both arguments are read and nothing is set, as the prelude's stub did, with one exception: tocdepth says how deep \tableofcontents lists, 0 for chapters alone and one more for each step down, and it is read here because a contents two levels deeper lists some hundreds of headings a document never asked for. The class default is 2.
\setcounter{tocdepth}{0}
\setcounter{secnumdepth}{-1}
\endtitlepageEnd a title page, which \end{titlepage} runs. It is \newpage, and then \setcounter{page}{1} unless the class is two-sided (extreport.cls, which every book in the corpus loads): the cover sheet is not one of the document's numbered pages, so every number the contents prints is one less than the sheet it stands on. The command is handed on rather than consumed, because an \end... is also what closes a \centering region and a title page is built out of centred pieces.
\begin{titlepage}
cover
\end{titlepage}
\labelName the place this stands, so that \ref and \pageref can point at it. The prelude read the key and produced nothing, which is right -- a label is a name for a place rather than text -- but nothing recorded the place either, so neither reference could be answered. What goes into the text here is the key, marked, and the typesetter reads back which sectioning unit it stands in and which page it fell on.
\chapter{First}\label{ch:one}
\refSet the number of the sectioning unit the label stands in: 1 for the first chapter, 2.1 for the first section of the second. The prelude expanded this to nothing, so see chapter \ref{ch:one} set as see chapter. The number cannot be known where the reference is written -- the unit may not have been read yet -- so the typesetter resolves it, counting chapters and sections the way the class does. A label the document never declared sets ??, as LaTeX's own \@setref does, because a missing reference an author can see is worth more than a silent gap.
See chapter \ref{ch:one}.
\pagerefSet the page the label fell on, in the document's own numbering. Resolved after the contents is built, because the contents is pages of its own and moves every page after it, and resolved repeatedly until the numbers stop moving -- the digits are text on a line, so one reference can move the page the next one names. A label the document never declared sets ??, and text output, which has no pages, sets ?? for every one of these.
See page \pageref{ch:one}.
\centerStart centring the lines that follow. This is what \begin{center} runs, the way latex.ltx has it: \begin{x} is \csname x\endcsname here, so the environment IS this control sequence. Each line inside is positioned by the width it measures rather than at the left margin. Without it a centred line and the line after it were filled into one flowing line, which is most of why a title page collapsed into the prose under it.
\begin{center}
centred
\end{center}
\endcenterStop centring: what \end{center} runs, and the close of the region \center opened. Lines after it go back to the left margin.
\begin{center}
centred
\end{center}
at the margin
\centeringCentre every line up to the end of the group or the environment that holds it. The switch form of \begin{center}: a title page is regularly one \centering inside a titlepage or a minipage rather than a centred environment. Environments here are a macro pair rather than a group, so the region ends at the \end{...} of whichever one is open -- otherwise a single \centering would centre every remaining page of the book.
{\centering centred}
at the margin
\centerlineCentre exactly its argument, on a line of its own. The box form rather than the switch: what follows it is not centred. The prelude answered it with its argument alone, which set an imprint or a colophon flush left in the middle of the page.
\centerline{TEXT}
\centerline{a colophon}
\tabularOpen a table. \begin{tabular} runs this, the way latex.ltx has it: \begin{x} is \csname x\endcsname here, so the environment IS this control sequence. The optional position and the column specification are read and dropped -- columns are as wide as their content here, not as wide as the specification asks. Inside a table & is a cell boundary and \ ends a row; outside one both mean what they meant before. Without it a table was filled into the prose around it as one paragraph: Name Value alpha 1 beta 2.
\begin{tabular}{ll}
Name & Value \\
alpha & 1 \\
\end{tabular}
\endtabularClose a table: what \end{tabular} runs. It also ends the row in hand, so a last row written without a closing \ is still a row.
\begin{tabular}{ll}
a & b \\
\end{tabular}
\longtableOpen a longtable, which is set exactly as tabular is. This is what pandoc emits for every markdown table, so it is the shape of nearly every table in a generated book. A longtable states its head, then its foot, then its body, and it is set head, body, foot -- see \endhead and \endlastfoot.
\begin{longtable}[]{@{}lr@{}}
\toprule
Name & Value \\
\midrule
\endhead
\bottomrule
\endlastfoot
alpha & 1 \\
\end{longtable}
\endlongtableClose a longtable: what \end{longtable} runs, and the same close \endtabular is.
\begin{longtable}[]{@{}ll@{}}
a & b \\
\end{longtable}
\toprulebooktabs' rule above a table, drawn as a filled rectangle the width of the table at booktabs' own \heavyrulewidth of 0.08em. Written 3,455 times across the corpus and drawn none of them before this, because the prelude answered it with nothing.
\begin{tabular}{ll}
\toprule
Name & Value \\
\bottomrule
\end{tabular}
\midrulebooktabs' rule between a table's head and its body, drawn at \lightrulewidth -- 0.05em, thinner than the two outer rules, which is the whole visual difference between them. An optional width may follow and is read and dropped.
\begin{tabular}{ll}
Name & Value \\
\midrule
alpha & 1 \\
\end{tabular}
\bottomrulebooktabs' rule under a table, drawn at \heavyrulewidth as \toprule is. In a longtable it is written in the foot, before the body, and is set where a reader gets it: under the last row.
\begin{tabular}{ll}
alpha & 1 \\
\bottomrule
\end{tabular}
\hlineThe kernel's own horizontal rule across a table, drawn the way \midrule is. Outside a table it does nothing, which is what it did everywhere before tables were set.
\begin{tabular}{ll}
\hline
a & b \\
\hline
\end{tabular}
\tabularnewlineEnd a table row. The unambiguous spelling of \\ inside a table, for the places where \\ would be read as something else; both end a row here, and both take the * and the optional extra space LaTeX allows after them.
\begin{tabular}{ll}
a & b \tabularnewline
c & d \tabularnewline
\end{tabular}
\endheadEnd longtable's head: everything above it is set at the top of EVERY page the table runs onto, not only the first. Written above the body, which is where it is set on the first page.
\begin{longtable}[]{@{}ll@{}}
\toprule
Name & Value \\
\midrule
\endhead
alpha & 1 \\
\end{longtable}
\endfirstheadEnd longtable's FIRST head, when it differs from the one that repeats. What stands above this is set at the top of the first page, and what stands between it and \endhead at the top of every page after that.
\begin{longtable}[]{@{}ll@{}}
Name & Value \\
\endfirsthead
Name & Value \\
\endhead
alpha & 1 \\
\end{longtable}
\endfootEnd longtable's foot: what stands at the bottom of every page the table runs PAST -- so on no page at all when it fits on one, and never on the last, where \endlastfoot stands instead. Written before the body and set under it.
\begin{longtable}[]{@{}ll@{}}
\endhead
\bottomrule
\endfoot
alpha & 1 \\
\end{longtable}
\endlastfootEnd longtable's LAST foot: what is set once, under the end of the table, where \endfoot stands under every page before it. This is the boundary pandoc writes, with \bottomrule above it, in every markdown table it emits.
\begin{longtable}[]{@{}ll@{}}
\endhead
\bottomrule
\endlastfoot
alpha & 1 \\
\end{longtable}
\itemizeOpen a bulleted list. \begin{itemize} runs this, the way latex.ltx has it: \begin{x} is \csname x\endcsname here, so the environment IS this control sequence. Each \item inside it starts its own line, carries a bullet, and sets 2.5em in from the margin in a measure narrowed by the same amount, so a long item wraps inside the list. A list inside a list indents by that again. Without it a list was filled into the prose around it: an itemize of two items read back as first item second item.
\begin{itemize}
\item first
\item second
\end{itemize}
\enditemizeClose a bulleted list: what \end{itemize} runs. The lines after it go back to the margin, or to the indent of the list this one was nested inside.
\begin{itemize}
\item only
\end{itemize}
back at the margin
\enumerateOpen a numbered list, set exactly as itemize is except for the mark: each item carries its own number in the list, counted from one. Pandoc emits an \enumerate with a \def\labelenumi above it for every ordered markdown list; the label definition is read as an ordinary \def and the numbering here is arabic at every level.
\begin{enumerate}
\item first
\item second
\end{enumerate}
\endenumerateClose a numbered list: what \end{enumerate} runs, and the same close \enditemize is.
\begin{enumerate}
\item only
\end{enumerate}
back at the margin
\descriptionOpen a list of terms. The mark of each item is the term in its own \item[...], set in the bold face and followed by the item's body on the same line. An item with no term has no mark, which is the honest reading of a description item that named nothing.
\begin{description}
\item[term] what it means
\end{description}
\enddescriptionClose a list of terms: what \end{description} runs, and the same close the other two lists have.
\begin{description}
\item[term] meaning
\end{description}
back at the margin
\itemStart a list item: its own line, at the depth of the list holding it, with the mark that list sets -- a bullet, a number, or a bold term. \item[label] gives the item an explicit label, which IS the term in a description list and REPLACES the mark elsewhere; the label is TeX and is expanded, so \item[\texttt{--flag}] sets in the monospace face. Outside any list this is the prelude's own \item, which yields its optional argument and nothing else. 8,683 occurrences across the corpus.
\item[LABEL] <text>
\begin{itemize}
\item plain
\item[!] labelled
\end{itemize}
\definecolorName a colour: \definecolor{neonCyan}{HTML}{05D9E8}. The models read are HTML (six hex digits), rgb (three components in 0..=1), RGB (the same in 0..=255), gray and cmyk. A model that is not one of those defines nothing rather than guessing, because a colour read in the wrong model is wrong on every page it reaches. Documents define their palette once in the preamble and refer to it by name afterwards, so without this every later \color names something unknown and the page comes out black.
\definecolor{NAME}{MODEL}{SPEC}
\definecolor{neonCyan}{HTML}{05D9E8}
\providecolorDefine a colour only if that name is not already defined. Otherwise \definecolor.
\providecolor{NAME}{MODEL}{SPEC}
\providecolor{link}{HTML}{05D9E8}
\colorletGive an existing colour another name. A name nothing has defined yet defines nothing.
\colorlet{NEW}{OLD}
\definecolor{brand}{HTML}{FF2A6D}
\colorlet{heading}{brand}
\colorSwitch the colour of everything that follows, until the group holding it closes -- a switch rather than a wrapper, which is why {\color{red}...} colours only what is inside the braces. Takes a defined name, or a model and a spec: \color[rgb]{1,0,0}. A second \color in one group replaces the first rather than nesting, because TeX has one current colour and not a stack. A name nothing defined leaves the text in the colour it already had.
\color{NAME}
\color[MODEL]{SPEC}
{\color{neonCyan}cyan words}
\textcolorColour exactly one argument: \textcolor{neonCyan}{words}. Takes the same two forms as \color. Unlike \color it puts the previous colour back afterwards, so it never leaks into the text beside it.
\textcolor{NAME}{TEXT}
\textcolor[MODEL]{SPEC}{TEXT}
\textcolor{red}{warning}
\pagecolorPaint the page. Drawn under everything else, which is the only order that leaves the words on top of it -- and it has to be honoured, because a document that sets a dark page also sets light text to go on it, and doing one without the other leaves white on white.
\pagecolor{NAME}
\definecolor{bgPrimary}{HTML}{05050A}
\pagecolor{bgPrimary}
\titleformattitlesec's heading format, applied rather than discarded. Both spellings are read — the starred \titleformat*{\section}{FORMAT} and the plain \titleformat{\chapter}[SHAPE]{FORMAT}{LABEL}{SEP}{BEFORE}, whose optional argument follows a mandatory one. The FORMAT is lowered with the title, so the sizes, colours and family in it reach the heading and end with it; it REPLACES the class default for that level, which is what titlesec does, so a format naming no size leaves the heading at the body size. The shape, label, separator and before-code are titlesec's own layout and are still dropped. A format combining switches composes: {\sffamily\bfseries\Huge} reaches the page as the bold cut of the SANS family at \Huge, because family, series and shape are independent axes and each declaration sets only its own.
\titleformat{COMMAND}[SHAPE]{FORMAT}{LABEL}{SEP}{BEFORE}
\titleformat{\chapter}[hang]{\sffamily\bfseries\Huge}{}{0pt}{}
\titleformat*{\section}{\sffamily\Large}
\pandocboundedSet the argument, scaled down if it would overflow the page. Pandoc wraps every figure it emits in this, and a pandoc document also DEFINES it — as a box, a \Gscale@div against the box's height, and a \scalebox — and the document's definition wins over the preamble's. None of that is on this path, so the figure went into a box that was never set and vanished silently, the caption being outside the wrapper and surviving to look right. It is read here instead of expanded, so the argument is set. The bounding is real: an image with no stated size is brought down to the measure and the text height, keeping its proportions, which is what the wrapper's own comment says it is for. Scaling up never happens, which is also what it does.
\pandocbounded{CONTENT}
\pandocbounded{\includegraphics[keepaspectratio]{diagrams/plot.pdf}}
\includegraphicsPlace an image, and reserve the room it takes. PNG and JPEG are read; the file is embedded once however many pages draw it, with its alpha carried as an /SMask. width= and height= are honoured, in any of TeX's units and as a multiple of \textwidth, \linewidth or \columnwidth; give one and the other follows the file's own proportions, give neither and a pixel is a big point, which is what graphicx does with a file that states no resolution. The figure owns its own lines rather than running into the prose either side, and is centred by its own width inside a center region. A file that cannot be found or read costs the document its picture and not its remaining pages. Other keys — scale, angle, keepaspectratio, trim, clip — are consumed and not acted on, and no format beyond PNG and JPEG is read.
\includegraphics[OPTIONS]{FILE}
\includegraphics[width=0.8\textwidth]{figures/plot.png}
\includegraphics[width=5cm,height=3cm]{cover.jpg}
\setmainfontRecord the document's body typeface, and keep the name rather than dropping it. The PDF backend looks the family up on the system and EMBEDS it when it finds a TrueType-flavoured one, so the page is set in that face and measured with its own widths; failing that it falls back to one of the fourteen faces every reader has, chosen by metrics — Arimo, Liberation Sans and Arial all set at Helvetica's widths, and a name nothing is known about falls to Helvetica too. The DVI backend names .tfm fonts and cannot carry an OpenType one, so it still sets in Computer Modern. An optional bracket on either side of the family is consumed — and read: Path= and UprightFont= name a file the document ships, and BoldFont= and ItalicFont= name the files \bfseries and \itshape are set from. A mandatory argument ending in .ttf, .otf, .ttc or .otc, in any case, names that FILE rather than a family — fontspec's other spelling, resolved against Path= the same way — and an explicit UprightFont=/Extension= still wins where a document writes both.
\setmainfont[OPTIONS]{FAMILY}[OPTIONS]
\setmainfont{Arimo}   % embedded if Arimo is installed, else Helvetica's metrics
\setmainfont{Arimo-VF.ttf}[Path=./.fonts/]   % the file itself, embedded from Path=
\setromanfontThe older fontspec spelling of \setmainfont, and the same thing here: it fills the same slot, so whichever of the two the preamble writes last is the family the PDF backend embeds or maps.
\setromanfont[OPTIONS]{FAMILY}
\setromanfont{Arimo}   % identical in effect to \setmainfont{Arimo}
\setsansfontRecord the document's sans-serif family. The name is read and kept and its bracketed options are consumed, but no backend selects it yet: the PDF page is set in the main family throughout, so this records an intention rather than changing the output. Documented because a preamble writes it and the engine resolves it.
\setsansfont[OPTIONS]{FAMILY}[OPTIONS]
\setsansfont{Arimo}
\setmonofontRecord the document's monospace family, the counterpart of \setsansfont, and the face \ttfamily selects. Its options are read the way \setmainfont's are, so a Path=/UprightFont= naming a file the document ships is what the PDF backend embeds — which is the usual case, since a book carries its monospace face beside itself rather than installing it. The DVI backend names .tfm fonts and still sets in Computer Modern throughout.
\setmonofont[OPTIONS]{FAMILY}[OPTIONS]
\setmonofont{Cousine}
\setmonofont{ShareTechMono}[Path=./.fonts/,Extension=.ttf,UprightFont=ShareTechMono-Regular]
\directluaHand a chunk to an embedded Lua interpreter, and RUN it: PUC-Lua 5.3, the version LuaTeX itself embeds. Whatever the chunk prints comes back as input — \count10=20 a\directlua{tex.print(tex.count[10]+5)}b typesets a25b, the manual's own example. The tex table reaches the engine's real registers (tex.count, tex.dimen, tex.toks, tex.glue, and the get*/set*/is* functions), token reaches the input the chunk stands in front of (token.scan_int, scan_dimen, scan_keyword, scan_string, scan_word, scan_csname, get_macro, set_macro), and texio.write reaches the terminal. A chunk that fails STOPS the run with the Lua error as a TeX error, never silently. What is absent rather than stubbed is everything built on node lists: there is no node library, and tex.skip/tex.getbox refuse instead of inventing a value — tex.getglue is the same glue register as five plain numbers. luaotfload.add_fallback is answered for real: it names the faces a glyph the document's own face lacks is fetched from, and the PDF backend loads those families in order, asks each one's cmap for the character, and draws the first face that has it, carrying only the glyphs the document borrowed. \luadirect is the same primitive under ConTeXt's name; \latelua runs its chunk but contributes no input; \luaescapestring makes a TeX value safe inside a Lua string literal; \luafunction, \luafunctioncall and \luadef call a function stored in lua.get_functions_table().
\directlua{CHUNK}
\count10=20 \directlua{tex.print(tex.count[10]+5)}
\directlua{luaotfload.add_fallback("symfb", {"Arial Unicode MS:mode=base;", "Arial:mode=base;"})}
\ttfamilySet in the monospace face, until the group holding the declaration closes. This is what \texttt{...} is made of — {\ttfamily ...} — and it is honoured here rather than in the text command, because a document that redefines \texttt to colour its inline code writes the declaration in the replacement. The face is the file or family \setmonofont named, embedded when it can be found, Courier when it cannot, and the main face when the document named no monospace family at all.
{\ttfamily fixed pitch}
\texttt{fixed pitch}
\slshapeSet slanted, until the group holding the declaration closes. There is no separate slanted cut here, so it is the italic one — which is what \textsl has always expanded to. Like every other font declaration it sets ONE axis: {\sffamily\slshape} is the slanted cut of the sans family, not a replacement of it.
{\slshape leaning}
\textsl{leaning}
\bfseriesSet in the bold series, until the group holding the declaration closes; \textbf{...} is {\bfseries ...}. It sets the SERIES only and leaves the family and the shape as they stand, so {\sffamily\bfseries} is the bold cut of the sans family rather than a replacement of it. The face is the file BoldFont= named in THAT family's options — the sans family's for a sans context, the mono family's for a mono one — or the bold member of the fourteen carrying that family (Helvetica-Bold, Courier-Bold, Times-Bold) where the document named no file. A variable font whose bold is the upright file at another weight is the SAME file, so it comes out as the upright face: instantiating a weight axis is not something this does.
{\bfseries heavy}
\textbf{heavy}
\itshapeSet in the italic face, until the group holding the declaration closes; \textit{...} and \emph{...} are both {\itshape ...}. The face is the file ItalicFont= named in the main family's options, or the italic member of the fourteen — Helvetica-Oblique, Times-Italic — and the main face where the document supplies neither.
{\itshape stressed}
\emph{stressed}
\rmfamilyBack to the body face, until the group holding the declaration closes. One face is in force at a time here rather than a family, a series and a shape combining, so this replaces whatever the group had selected rather than changing one axis of it.
{\ttfamily code \rmfamily prose}
\sffamilySelect the sans-serif family. \setsansfont is read and kept, but no backend selects that family yet, so this sets in the main face — which is what a document asking for sans in a sans-set book wanted anyway. It is a declaration and runs to the end of its group.
{\sffamily sans}
\normalfontUndo every face declaration in force and set in the body face, to the end of the group. A heading writes it to start from the document's own face rather than from whatever was selected around it.
{\bfseries heavy \normalfont plain}
\makeatletterMake @ a letter (category code 11), so LaTeX's internal names like \@ifnextchar become spellable as single control sequences. This is a catcode change, so it takes effect at COMPILE time, exactly as \catcode\@=11 does.
\makeatletter <internal names> \makeatother
\makeatotherMake @ an ordinary character again (category code 12), closing a \makeatletter region. After it, \@x is the control sequence \ followed by the characters @x rather than one name.
\makeatletter <internal names> \makeatother

INITEX category codes

The table INITEX starts from, which is what texrs starts from: no format is loaded. {, }, $, &, #, ^, _ and ~ get their familiar meanings from plain.tex, not from the engine.

CodeCategoryCharacters INITEX puts here
0escape\
1begin group—
2end group—
3math shift—
4alignment tab—
5end of linecarriage return
6parameter—
7superscript—
8subscript—
9ignoredNUL
10spacespace
11letterA–Z, a–z
12otherevery other code (198 of them)
13active—
14comment%
15invalidDEL

Builtin calls

What the VM cannot do natively is a builtin call, emitted by the lowerer and dispatched by id. The numbers are a wire format: the bytecode cache keeps compiled chunks on disk and --aot serializes one into the executable it writes, and both call these BY NUMBER — so renumbering an op does not fail to build, it makes every cached chunk and every already-built binary call the wrong function.

ConstantIdWhat it does
MSG_APPEND4000Append one rendered piece to the message being built.
MSG_FLUSH4001Finish the message being built and record it.
DBG_LINE4002A statement boundary, emitted only under `--dap`. The debug adapter stops here; an ordinary run carries none of these ops.
FFI_COMPILE4003Compile and register a `\rust{ … }` block: one argument, the base64 body.
FFI_CALL4004Call a function a block exported: the name, then its arguments.
TEXT4005Append a run of the document's own text.
ARITH_CHECKED4006`\multiply` / `\divide` under TeX's overflow rule: the old value, the operand, and 0 for multiply or 1 for divide.
MSG_CLOSE4007Close an `\input` file: append `)` to the message already recorded, rather than record one, because tex writes the paren hard against what came before it while the stream is joined with spaces. No arguments.
MSG_DIMEN4008Append a dimension, written as TeX writes one: one argument, the value in scaled points.
MSG_GLUE4009Append a glue, written as TeX writes one: four arguments -- natural, stretch, shrink, and the packed orders.
COLOR_PUSH4010Open a colour: three components follow. 4010 and 4011, not 4006 and 4007: those are ARITH_CHECKED and MSG_CLOSE. Registering a builtin twice silently keeps the LAST one, so the colour ops were compiled, called, and quietly handled by somebody else's function -- the chunk was right and the page had no colour in it.
COLOR_POP4011Close the innermost colour.
ERR_SITE4012Record where the command about to run would be reported from: one argument, `tex.web` §311's context display for that point in the source.
TRANSCRIPT_NOTICE4013§1335's `(see the transcript file for additional information)`, written only if something was reported during the run, behind the `(\end occurred ...)` lines its one argument carries.
MSG_MUGLUE4014Append a MATH glue, written as TeX writes one: the same four arguments `MSG_GLUE` takes, with `mu` for the unit.
SCALE_DIMEN4015`tex.web` §453's `<factor><internal unit>`: the register's value, the factor's integer part, and its fraction in 65536ths. A builtin rather than a run of arithmetic ops because §107's truncation and §460's clamp are the port, and one Rust function is where they stay readable.
MSG_ROMAN4016Append a number as `\romannumeral` writes it: one argument, the value.
MSG_REPORT4017Append a report the lowerer made (§82's `print_err` and its context): one argument, the text. Unlike `MSG_APPEND` it marks a message that OPENS with it as starting on a fresh line rather than after a space.
WRITE_FLUSH4018Finish an `\immediate\write` and record it on a line of its own: glued to what came before, and the next message glued to it. No arguments.
EXPR_STEP4019One step of an e-TeX expression (`crate::ir::Num::Expr`): the operands, then the operation's code and the bound, for `etex_arith::apply`.
EXPR_END4020The end of an expression: its value or the error marker, then the report to make for the marker.
MSG_TAKE4021Take the message being built as a string, onto the stack: the text of a `\special` the run builds (`Cmd::Special`). No arguments.
ARITH_GLUE4022One component of a glue `\multiply` or `\divide` (`Cmd::GlueArith`): [`ARITH_CHECKED`]'s three arguments, with an overflow noted rather than reported.
ARITH_KEEP4023The value a glue component is left with: the new value, then the old; the old one back if any component overflowed.
ARITH_SETTLE4024Report the overflow a glue `\multiply` or `\divide` noted, once. No arguments.
LIST4100A list action (`crate::ir::list::ListOp`): its opcode, then its arguments in the order `ListOp::visit` gives them.
LIST_SHOWBOX4101Append §1296's display of a box register to the message being built: one argument, the register number.
LIST_SHOWLISTS4102Append §218's `show_activities` to the message being built.
OUT_OPEN4200`\openout`: the stream, then the file name (`crate::write`). Numbered from 4200, clear of the numbers after 4018 that other builtins take (the list actions are 4100 on): a number registered twice silently keeps the last function (see `COLOR_PUSH`).
OUT_WRITE4201`\write` to an open stream: the stream, after the text is built as a message's is.
OUT_CLOSE4202`\closeout`: the stream.
OUT_IS_OPEN4203Whether a stream is open: the stream; 1 or 0 back.

The --tiers report

texrs --tiers FILE runs a document and then queries fusevm's own eligibility and cache predicates, so the answer comes from the compiler that would have done the work rather than from an assumption about it.

LineWhat it answers
opsHow many bytecode ops the document lowered to, prologue included.
block-JIT eligibleWhether a region of this chunk is a shape the block tier will take at all. Eligibility is not compilation.
block-JIT compiledWhether the block tier actually compiled one, asked of fusevm's cache rather than assumed from eligibility.
largest eligible regionThe widest run of ops the block tier would take, as start..end with its length, or none.
loopsEvery loop header the lowerer emitted, and whether the tracing tier compiled a trace for it. none means the document has no backward branch, which is the usual reason nothing reaches native code.
block-ineligible opsThe ops that disqualified a region, counted by kind. A pair of CallBuiltins is enough, which is why the smallest document reaches no tier.
reaches native codeThe one line that answers the question the flag was run to ask.

Divergences from tex

Where this engine and real tex disagree, taken from tests/known_gaps.txt — the baseline the differential gate enforces in both directions, so this list can neither grow silently nor go stale.

CaseWhat differs
let_char_token.tex`\let\egroup=}' copies a CHARACTER token, and printing one through \message must print the character. texrs prints the name with the trailing space a multi-letter control word gets (tex.web 294's print_cs), so the stream ends `INSIDE\egroup ' where tex ends `INSIDE\egroup'. The meaning-copy half of \let is in parity; this is the char-token half.
outer_forbidden_use.textexrs records \outer but does not police it. tex forbids an outer macro inside a group being scanned as text and reports `Forbidden control sequence found while scanning text of \message'; texrs expands it and prints the body. \outer is ONLY an error-detection feature, and every position it governs -- an argument, a text group, skipped conditional text -- is one tex reports and recovers from while texrs stops, so enforcing it cannot reach parity either. Recorded rather than half-enforced: a false positive here would refuse a document that works.

Invocation

USAGE: texrs [OPTIONS] [FILE[.tex]]... [COMMANDS]
       texrs [OPTIONS] \FIRST-LINE      // the arguments are the input
       texrs [OPTIONS] &FMT ARGS        // with a named format
       texrs                            // no arguments: the prompt

TEX OPTIONS

OptionWhat it does
-interaction=MODEbatchmode, nonstopmode, scrollmode or errorstopmode
-jobname=NAMESet the job name
-output-directory=DIRWrite the output there instead of beside the input
-progname=NAMESet the program name
-fmt=NAMEUse a named format
-iniBe initex
-halt-on-errorStop at the first error
-file-line-error, -no-file-line-errorfile:line:error style messages
-recorderRecord the files read
-8bitWrite 8-bit characters as themselves

RUNNING

OptionWhat it does
--replStart the interactive prompt
--jobs=NCompile N documents at once (default: one per core)
--buildCompile into the bytecode cache and stop, without running
--textPrint the document text, not only the message stream
--dviTypeset to FILE.dvi -- total-fit lines, hyphenated
--pdfTypeset to FILE.pdf, in the font the document asked for
--no-cacheCompile this run rather than reading the bytecode cache
--aotCompile the document to a standalone native executable

LOOKING INSIDE

OptionWhat it does
--dump-tokensPrint the mouth's token stream and exit
--dump-astPrint the command stream the frontend lowered to, and exit
--disasmPrint the lowered fusevm bytecode and exit
--tiersRun it, then report which fusevm tier took its bytecode

EDITORS

OptionWhat it does
--lspSpeak the Language Server Protocol over stdio
--dapSpeak the Debug Adapter Protocol over stdio

CACHE

OptionWhat it does
--cache-statsSay what the bytecode cache holds and where
--cache-clearDelete it

DOCUMENTS

OptionWhat it does
-X new [DIR]Make one (Texrs.toml + index.tex)
-X initMake one here, named after this directory
-X build [--profile P]Build the document this directory is in
-X watch [--profile P]Rebuild it whenever an input changes
-X showSay what the document is and can produce
-X dump [--profile P]Build to stdout, writing nothing
-X bundle fetch URLDownload a bundle into the cache
-X bundle listSay which bundles have been fetched
-X dvi FILE.dviRead what real tex shipped for a document
-X dvi A.dvi B.dviSay whether two files are the same document
-X bib FILE.bibRead a bibliography database
-X bib FILE.auxSay what a document cites, and what is missing
-X bst FILE.bstRead a bibliography style, and check its names
-X bibtex FILE.auxRun the style: write the .bbl a document reads
-X tfm FILE.tfm [C]Read a font's metrics, or one character's
-X vf FILE.vf [C]Read a virtual font: what it really sets
-X pk FILE.pk [C]Read a packed bitmap font, and draw a character
-X otf FILE.otf [C]Read an OpenType font: its tables and its cmap
-X pfb FILE.pfb [C]Read a Type 1 font: its glyphs and their widths
-X map FILE.map [NAME]Read a font map: what a TeX font name means
-X enc FILE.encRead an encoding: what each code is called
-X itar FILE.tar [NAME]Index a tar bundle, or read one file out of it
-X special TEXTSay what a \special means to a driver
--profile NAMEWhich output to build
--interval MSHow often -X watch looks (default 250)

SYSTEM

OptionWhat it does
-h, --helpPrint this
--versionPrint the version banner

Environment

VariableWhat it does
TEXRS_CACHESet to 0, false or no to turn the bytecode cache off for a run; set to a path to put it somewhere else. A disabled cache is how you work around a cache you suspect.
TEXRS_PARALLELSet to 1 to lex a document on several threads. Off by default: the mouth is 22% of the time on the documents measured, so the win did not pay for the coordination.
TEXRS_PDFSHIP_DUMPA path. The test that compares a shipped page object by object with the file luatex writes for it saves texrs's PDF there, to inspect when the two disagree.
TEXRS_PRELEX_STATSSet to anything to print the pre-lexer's hit and miss counts when the run ends.
TEXRS_STATICLIBThe libtexrs.a that --aot links against, when the installed copy is not the one you want.
TEXRS_THREADSThe thread count for a run, a positive integer; --jobs wins when both are given. It sizes the paragraph-parallel line-breaking pool, the speculative pre-lexer and the document batch. Output does not depend on it. Unset, every pool keeps one thread per core.
SOURCE_DATE_EPOCHA Unix time to stamp a PDF with instead of the wall clock (reproducible-builds.org's specification, which LuaTeX honours too). Two runs of one document otherwise differ in their dates and nothing else, so this is what makes byte equality with LuaTeX a question that can be asked at all.
TEXINPUTSWhere \input and \openin look after the working directory. Only when neither has the file does texrs ask kpsewhich for the TeX tree, so a document that reads the files beside it needs no TeX installation.
TEX_ORACLEThe tex binary the parity harnesses compare against, when it is not the one on PATH.
TEX_VERSION_EXPECTThe oracle version the harnesses insist on, overriding the one pinned in BUGS.md. A deliberate cross-version run, and nothing else, wants this.

Links