//! The primitive-reference corpus: the `(name, chapter, doc, syntax + example)`
//! table behind editor completion, editor hover (`src/lsp.rs`) and the generated
//! `docs/reference.html` (`src/bin/gen_docs.rs`).
//!
//! One entry per primitive the engine actually resolves. Every entry mirrors
//! something in the implementation:
//!
//! * "Category codes" → `catcode.rs` and `expand::do_catcode`.
//! * "Macro definition" → `expand::do_def` / `do_let` and
//! `lower::compile_time_def`.
//! * "Expansion" → `expand::expand_one` and the `lower` message path.
//! * "Conditionals" → `expand::CONDITIONALS`, `expand::do_conditional`,
//! and the branch lowering in `lower.rs`.
//! * "Registers" → `compiler::COUNT_SLOTS` and `expand::do_arith`.
//! * "Grouping" → `expand::begin_group` / `end_group` and the
//! save/restore wrapper `lower.rs` emits around a group body.
//! * "LaTeX" → `latex.rs`, `expand::do_newcommand` and
//! `expand::compile_time_preamble_directive`.
//!
//! A primitive is documented here only if texrs resolves it, so the language
//! server and the static reference never drift from what the engine can run.
//! Where the behaviour diverges from real tex, the entry says so rather than
//! describing tex — `BUGS.md` carries the same divergence with its reason.
//!
//! The fourth field is a syntax line followed by a usage example, both rendered
//! in one TeX code block.
/// A reference entry: `(name, chapter, one-line doc, syntax + example)`.
pub type Entry = (&'static str, &'static str, &'static str, &'static str);
/// The chapters, in the order the reference presents them.
pub const CHAPTERS: &[&str] = &[
"Category codes",
"Macro definition",
"Expansion",
"Conditionals",
"Registers",
"Boxes",
"Mathematics",
"Grouping",
"Intercepts",
"Inline Rust",
"Files",
"PDF backend",
"LaTeX",
];
/// The reference corpus, in chapter order.
pub const CORPUS: &[Entry] = &[
// ══ Category codes — catcode.rs, expand::do_catcode ════════════════════
(
"\\catcode",
"Category codes",
"Set 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\n\\catcode`\\{=1 \\catcode`\\}=2 \\catcode`\\#=6\n\\message{now braces group}",
),
(
"^^X",
"Category codes",
"Control-character notation (tex.web \u{a7}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` \u{2014} `A` is not a lowercase hex digit, so the shift applies to the `4` alone. The substitution belongs to the input processor (\u{a7}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\n^^I % tab\n^^41 % the hex form: A",
),
(
"`",
"Category codes",
"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\n\\message{\\the\\count1} % => 65",
),
(
"\\catcodetable",
"Category codes",
"Which 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>\n\\initcatcodetable 3 \\catcodetable 3 % INITEX's codes",
),
(
"\\savecatcodetable",
"Category codes",
"Make table N a copy of the current one. N may not be the current table, and must be in 0..32767.",
"\\savecatcodetable 1",
),
(
"\\initcatcodetable",
"Category codes",
"Make table N INITEX's: letters 11, `\\` 0, `%` 14, the space 10, `^^M` 5, `^^@` 9, `^^?` 15, everything else 12.",
"\\initcatcodetable 2",
),
// ══ Macro definition — expand::do_def / do_let ═════════════════════════
(
"\\def",
"Macro definition",
"Define 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 \u{a7}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` \u{a7}1215): `\\catcode`\\~=13 \\def~{...}` defines `~` itself, and an active `~` and the control sequence `\\~` stay different things.",
"\\def\\name<parameter text>{<body>}\n\\def\\greet#1{HELLO-#1}\n\\def\\pair#1,#2.{[#1|#2]}\n\\message{\\greet{WORLD}} % => HELLO-WORLD\n\\message{\\pair 1,2.} % => [1|2]",
),
(
"\\gdef",
"Macro definition",
"Define globally: the definition survives the enclosing group, where a `\\def` inside braces is undone at the closing brace.",
"\\gdef\\name{<body>}\n{\\gdef\\v{IN}}\n\\message{\\v} % => IN",
),
(
"\\edef",
"Macro definition",
"Define with the body expanded NOW, so a register read is frozen at definition time and a later assignment cannot move it. tex.web \u{a7}366 expands the body while READING it, which decides a conditional in it there and turns `\\the` into \u{a7}478's characters. texrs does that whenever it can prove the registers the body reads \u{2014} a register nothing has assigned yet is at INITEX's zero, which is what the compiler writes into every slot \u{2014} 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>}\n\\count1=1\n\\edef\\frozen{\\the\\count1}\n\\count1=2\n\\message{\\frozen} % => 1\n\\edef\\case{\\ifcase\\count2 ZERO\\else OTHER\\fi}\n\\count2=5\n\\message{\\case} % => ZERO",
),
(
"\\xdef",
"Macro definition",
"A global `\\edef`: the body is expanded now and the definition survives the enclosing group.",
"\\xdef\\name{<body>}\n{\\xdef\\frozen{\\the\\count1}}",
),
(
"\\let",
"Macro definition",
"Give a control sequence another's CURRENT meaning, not a reference to it: redefining the source afterwards does not change the alias.",
"\\let\\alias=\\source\n\\def\\v{ONE}\n\\let\\w=\\v\n\\def\\v{TWO}\n\\message{\\w} % => ONE",
),
(
"\\futurelet",
"Macro definition",
"Look 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 \u{a7}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 \u{2014} which is the comparison the whole idiom rests on.",
"\\futurelet\\next<token><token>\n\\def\\peek{\\futurelet\\next\\decide}\n\\def\\decide{\\ifx\\next[ OPTIONAL\\else PLAIN\\fi}",
),
(
"\\global",
"Macro definition",
"Prefix making the following assignment global, so it survives the enclosing group.",
"\\global\\count1=5\n\\global\\def\\v{OUT}",
),
// ══ Expansion — expand::expand_one, lower's message path ═══════════════
(
"\\csname",
"Expansion",
"Build 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\n\\def\\greeting{HI}\n\\def\\name{greeting}\n\\message{\\csname \\name\\endcsname} % => HI",
),
(
"\\endcsname",
"Expansion",
"Terminate a `\\csname`. It is an error to reach one without an open `\\csname`.",
"\\csname foo\\endcsname",
),
(
"\\string",
"Expansion",
"Print a control sequence as text, escape character included \u{2014} the inverse of `\\csname`.",
"\\string\\cs\n\\message{\\string\\undefined} % => \\undefined",
),
(
"\\show",
"Expansion",
"Print what the next token means (tex.web \u{a7}1294), read UNEXPANDED: `> `, the name and `=`, the same text `\\meaning` gives, and a period, followed by the context an error shows \u{2014} `\\show` ends by calling `error`, so the run closes with the transcript notice as it does after an error.",
"\\show<token>\n\\def\\a#1{x#1}\\show\\a % => > \\a=macro:#1->x#1.",
),
(
"\\showthe",
"Expansion",
"Print what `\\the` would make of an internal quantity (tex.web \u{a7}1297): `> `, the value as \u{a7}465 writes it \u{2014} a count as digits, a dimension as `3.5pt`, a glue with its stretch and shrink, a token list with each `#` doubled \u{2014} 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>\n\\count1=5 \\showthe\\count1 % => > 5.",
),
(
"\\showtokens",
"Expansion",
"Print 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>}\n\\showtokens{\\a b #} % => > \\a b ##.",
),
(
"\\interactionmode",
"Expansion",
"The 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>\n\\message{\\the\\interactionmode} % => 1 under -interaction=nonstopmode",
),
(
"\\batchmode",
"Expansion",
"From 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 \u{a7}1264).",
"\\batchmode\\message{not shown}\\nonstopmode",
),
(
"\\nonstopmode",
"Expansion",
"Report errors and carry on without stopping; what a run starts in under the parity harnesses. Global, and it ends the terminal line.",
"\\nonstopmode",
),
(
"\\scrollmode",
"Expansion",
"The same as `\\nonstopmode` here, since texrs never stops to ask; `\\interactionmode` reads 2.",
"\\scrollmode",
),
(
"\\errorstopmode",
"Expansion",
"The same as `\\nonstopmode` here, since texrs never stops to ask; `\\interactionmode` reads 3.",
"\\errorstopmode",
),
(
"\\eTeXversion",
"Expansion",
"e-TeX's major version, a read-only integer: 2, as luatex reports it. `\\eTeXminorversion` is the minor one.",
"\\message{\\the\\eTeXversion} % => 2",
),
(
"\\eTeXminorversion",
"Expansion",
"e-TeX's minor version, a read-only integer: 2, as luatex reports it.",
"\\message{\\the\\eTeXminorversion} % => 2",
),
(
"\\eTeXrevision",
"Expansion",
"e-TeX's revision as characters: `.2`, as luatex expands it.",
"\\message{\\eTeXrevision} % => .2",
),
(
"\\eTeXVersion",
"Expansion",
"e-TeX's version as characters: `2.2`, as luatex expands it.",
"\\message{\\eTeXVersion} % => 2.2",
),
(
"\\luatexversion",
"Expansion",
"LuaTeX'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",
),
(
"\\luatexrevision",
"Expansion",
"LuaTeX's revision as characters: `0`.",
"\\message{\\luatexrevision} % => 0",
),
(
"\\inputlineno",
"Expansion",
"The 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\n\\message{\\the\\inputlineno} % => the line this is on",
),
(
"\\meaning",
"Expansion",
"What a token MEANS, as characters (tex.web \u{a7}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>\n\\def\\a#1{[#1]}\n\\message{\\meaning\\a} % => macro:#1->[#1]",
),
(
"\\uppercase",
"Expansion",
"Read the following group WITHOUT expanding it, replace every character by its `\\uccode` and put the result back to be read again (tex.web \u{a7}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 \u{2014} which is what LaTeX's `\\MakeUppercase` is built on.",
"\\uppercase{<text>}\n\\uppercase{\\message{abc 123}} % => ABC 123",
),
(
"\\lowercase",
"Expansion",
"The 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>}\n\\lowercase{\\message{ABC dEf}} % => abc def",
),
(
"\\the",
"Expansion",
"The 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>\n\\count1=12\n\\message{count=\\the\\count1} % => count=12",
),
(
"\\number",
"Expansion",
"A 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>\n\\message{\\number0042} % => 42",
),
(
"\\expandafter",
"Expansion",
"One 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>\n\\def\\a{\\b}\n\\def\\b{DEEP}\n\\message{\\expandafter\\string\\a} % => \\b",
),
(
"\\noexpand",
"Expansion",
"Suppress expansion of the next token for one step \u{2014} the token is used for its own sake rather than its meaning.",
"\\noexpand<token>\n\\edef\\keep{\\noexpand\\later}",
),
(
"\\message",
"Expansion",
"Write 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>}\n\\message{HELLO-WORLD} % => (./file.tex HELLO-WORLD )",
),
(
"\\immediate",
"Expansion",
"Do the `\\openout`, `\\write` or `\\closeout` that follows now rather than at shipout (tex.web \u{a7}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>}\n\\immediate\\openout3=notes % => notes.tex, created empty",
),
(
"\\openout",
"Expansion",
"Open a write stream on a file (tex.web \u{a7}1351, \u{a7}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>\n\\immediate\\openout1=\\jobname.aux % => job.aux\n\\immediate\\openout2={my notes} % => my notes.tex",
),
(
"\\closeout",
"Expansion",
"Close a write stream (tex.web \u{a7}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>",
),
(
"\\special",
"Expansion",
"A whatsit for the driver (tex.web \u{a7}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>}\n\\special shipout{<text>}",
),
(
"\\write",
"Expansion",
"Write a line (tex.web \u{a7}1350, \u{a7}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>}\n\\immediate\\write16{\\the\\count0} % => its own line on the terminal\n\\immediate\\write-1{log only}",
),
(
"\\errmessage",
"Expansion",
"Report an error of the document's own and carry on (tex.web \u{a7}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>}\n\\errmessage{Bad value \\the\\count1 } % => ! Bad value 5.",
),
(
"\\relax",
"Expansion",
"Do nothing. Accepted so a document can stop a number scan, or fill a slot that needs a token but no action \u{2014} which is also what `\\csname` makes of a name with no meaning.",
"\\relax",
),
(
"\\par",
"Expansion",
"End 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",
),
(
"\\ignorespaces",
"Expansion",
"Skip the spaces that follow (tex.web \u{a7}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 \u{2014} the horizontal-mode half needs a stomach.",
"\\ignorespaces\n\\def\\a{\\ignorespaces}\n\\a X % the spaces before X are gone",
),
(
"\\end",
"Expansion",
"Stop 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",
),
(
"\\fontname",
"Expansion",
"Expands to the name of the font the next token identifies, as category-12 characters (tex.web \u{a7}470, \u{a7}472). A name `\\font` defined answers its file, with ` at Xpt` when it was loaded at another size (\u{a7}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>\n\\message{\\fontname\\nullfont} % nullfont",
),
(
"\\nullfont",
"Expansion",
"The null font (tex.web \u{a7}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\n\\message{\\fontname\\nullfont} % nullfont",
),
(
"\\font",
"Expansion",
"Load a font (tex.web \u{a7}1257-\u{a7}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\n\\message{\\fontname\\font} % cmr10",
),
(
"\\textfont",
"Expansion",
"A math family slot for text style (tex.web \u{a7}230), named by a family number 0\u{2013}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\n\\message{\\fontname\\textfont0} % nullfont",
),
(
"\\scriptfont",
"Expansion",
"A math family slot for script style (tex.web \u{a7}230), named by a family number 0\u{2013}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\n\\message{\\fontname\\scriptfont1} % nullfont",
),
(
"\\scriptscriptfont",
"Expansion",
"A math family slot for scriptscript style (tex.web \u{a7}230), named by a family number 0\u{2013}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\n\\message{\\fontname\\scriptscriptfont2} % nullfont",
),
// ══ Conditionals — expand::do_conditional, lower's branch emission ═════
(
"\\ifnum",
"Conditionals",
"Compare two numbers with `<`, `=` or `>`. It tests run-time state, so it lowers to a real branch \u{2014} a comparison plus a jump \u{2014} rather than a decision taken while walking a tree.",
"\\ifnum<number><rel><number> <true>\\else <false>\\fi\n\\count1=5\n\\message{\\ifnum\\count1>3 BIG\\else SMALL\\fi} % => BIG",
),
(
"\\ifodd",
"Conditionals",
"True 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\n\\message{\\ifodd\\count1 ODD\\else EVEN\\fi}",
),
(
"\\ifcase",
"Conditionals",
"Switch 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\n\\count1=2\n\\message{\\ifcase\\count1 ZERO\\or ONE\\or TWO\\else MANY\\fi} % => TWO",
),
(
"\\iftrue",
"Conditionals",
"Constant truth. Decidable without the VM, so it is FOLDED while lowering and the untaken arm is never emitted \u{2014} 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",
),
(
"\\iffalse",
"Conditionals",
"Constant falsity. Folded while lowering, like `\\iftrue`, so the taken arm is the only code that reaches the chunk.",
"\\iffalse <true>\\else <false>\\fi",
),
(
"\\ifx",
"Conditionals",
"Compare 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\n\\def\\a{X}\\def\\b{X}\n\\message{\\ifx\\a\\b SAME\\else DIFF\\fi} % => SAME",
),
(
"\\if",
"Conditionals",
"Compare 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 \u{2014} that is `tex.web` \u{a7}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",
),
(
"\\ifdefined",
"Conditionals",
"True 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",
),
(
"\\else",
"Conditionals",
"Start 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",
),
(
"\\or",
"Conditionals",
"Start the next case of an `\\ifcase`: the case before the first `\\or` is 0, and each `\\or` moves to the next.",
"\\or",
),
(
"\\fi",
"Conditionals",
"End a conditional. A control word swallows the space after it, so `\\fi X` prints `X` with no leading space.",
"\\fi",
),
(
"\\ifcat",
"Conditionals",
"Compare two category codes after expansion, reading each operand as `\\if` does (`tex.web` \u{a7}506-\u{a7}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",
),
(
"\\ifdim",
"Conditionals",
"Compare two dimensions. tex.web \u{a7}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\n\\dimen1=2pt\n\\ifdim\\dimen1>1pt \\message{[WIDER]}\\else \\message{[NARROWER]}\\fi % => [WIDER]",
),
(
"\\ifvoid",
"Conditionals",
"Is box register N empty? A real branch on the register as the program holds it (tex.web \u{a7}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\n\\ifvoid200 \\message{[EMPTY]}\\else \\message{[FULL]}\\fi % => [EMPTY]",
),
(
"\\ifhbox",
"Conditionals",
"Does box register N hold an \\hbox? A real branch on the kind the stomach mirrors, as `\\ifvoid` is.",
"\\ifhbox<N> <true>\\else <false>\\fi\n\\ifhbox200 \\message{[H]}\\else \\message{[NO]}\\fi % => [NO]",
),
(
"\\ifvbox",
"Conditionals",
"Does box register N hold a \\vbox? A real branch on the kind the stomach mirrors, as `\\ifvoid` is.",
"\\ifvbox<N> <true>\\else <false>\\fi\n\\ifvbox200 \\message{[V]}\\else \\message{[NO]}\\fi % => [NO]",
),
(
"\\ifvmode",
"Conditionals",
"True in vertical mode, internal or not (\u{a7}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",
),
(
"\\ifhmode",
"Conditionals",
"True in horizontal mode, restricted or not (\u{a7}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",
),
(
"\\ifmmode",
"Conditionals",
"True in math mode, in a display or not (\u{a7}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",
),
(
"\\ifinner",
"Conditionals",
"True in an inner mode (\u{a7}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",
),
(
"\\ifeof",
"Conditionals",
"True when a `\\read` stream is closed (tex.web \u{a7}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",
),
(
"\\ifcsname",
"Conditionals",
"Is 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 \u{2014} which is the whole difference from `\\csname`, whose lookup DEFINES what it misses as `\\relax` (tex.web \u{a7}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\n\\def\\foo{F}\n\\ifcsname foo\\endcsname \\message{[YES]}\\else \\message{[NO]}\\fi % => [YES]\n\\ifcsname nope\\endcsname \\message{[YES]}\\else \\message{[NO]}\\fi % => [NO], twice over",
),
(
"\\ifabsnum",
"Conditionals",
"`\\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",
"Conditionals",
"`\\ifdim` on the magnitudes, as `\\ifabsnum` is to `\\ifnum`. A LuaTeX primitive.",
"\\ifabsdim -2pt<1pt \\message{no}\\else\\message{yes}\\fi % => yes",
),
(
"\\ifincsname",
"Conditionals",
"True 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",
),
(
"\\ifprimitive",
"Conditionals",
"Is 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",
),
(
"\\ifcondition",
"Conditionals",
"Nothing 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",
),
(
"\\currentiflevel",
"Conditionals",
"How 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",
),
(
"\\currentiftype",
"Conditionals",
"Which 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",
),
(
"\\currentifbranch",
"Conditionals",
"Which 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",
),
// ══ Registers — compiler::COUNT_SLOTS, expand::do_arith ════════════════
(
"\\count",
"Registers",
"A count register. There are exactly 256 of them (tex.web \u{a7}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 \u{2014} where the reference `tex` has plain's values, including `\\count0` = the page number.",
"\\count<N>=<number>\n\\count1=7\n\\message{\\the\\count1} % => 7",
),
(
"\\advance",
"Registers",
"Add to a register. Lowers to `GetSlot / LoadInt / Add / SetSlot` \u{2014} native ops the JIT can compile.",
"\\advance\\count<N> by <number>\n\\count1=7 \\advance\\count1 by 5\n\\message{\\the\\count1} % => 12",
),
(
"\\multiply",
"Registers",
"Multiply 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>\n\\count1=7 \\multiply\\count1 by 3 % => 21",
),
(
"\\divide",
"Registers",
"Divide a register, truncating toward zero as TeX's does.",
"\\divide\\count<N> by <number>\n\\count1=7 \\divide\\count1 by 2 % => 3",
),
// ══ Boxes — stomach.rs, lower/stomach.rs ═════════════════════════════
(
"\\setbox",
"Boxes",
"Assign a box register (tex.web \u{a7}1241, \u{a7}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 (\u{a7}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>\n\\font\\tenrm=cmr10 \\tenrm\n\\setbox0\\hbox{abc}\\message{[\\the\\wd0]} % => [15.27782pt]",
),
(
"\\hbox",
"Boxes",
"Build a horizontal list and package it (\u{a7}1083-\u{a7}1086): `to <dimen>` sets it to that width, `spread <dimen>` that much wider than natural, and the glue inside is set by \u{a7}649's `hpack`. Characters go through the font's ligature and kern program (\u{a7}1034-\u{a7}1040), spaces become the font's interword glue (\u{a7}1041-\u{a7}1044), and `\\everyhbox` is inserted after the brace.",
"\\hbox to<dimen>{...} \\hbox spread<dimen>{...} \\hbox{...}",
),
(
"\\vbox",
"Boxes",
"Build a vertical list and package it with \u{a7}668's `vpackage`, its depth limited by `\\boxmaxdepth`; boxes on it are separated by `\\baselineskip` glue as \u{a7}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}}",
),
(
"\\vtop",
"Boxes",
"A `\\vbox` whose reference point is its first box's baseline (\u{a7}1087): the height is the first item's, the rest is depth.",
"\\vtop{\\hbox{a}\\hbox{b}}",
),
(
"\\box",
"Boxes",
"The box in register N, which leaves the register void (\u{a7}1079) -- at the same level, so no group brings it back.",
"\\box<N>",
),
(
"\\copy",
"Boxes",
"The box in register N, leaving the register as it was.",
"\\copy<N>",
),
(
"\\lastbox",
"Boxes",
"The last box of the current list, taken off it with its shift cleared (\u{a7}1080-\u{a7}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",
),
(
"\\vsplit",
"Boxes",
"Split a vbox register at the best place for a box of the given height (\u{a7}977-\u{a7}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",
),
(
"\\wd",
"Boxes",
"The width of box register N, readable wherever a dimension is (`\\the\\wd0`, `\\ifdim\\wd0>\\hsize`, `.5\\wd0`) and assignable (\u{a7}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>\n\\message{[\\the\\wd0]}",
),
(
"\\ht",
"Boxes",
"The height of box register N, read and assigned as `\\wd` is.",
"\\ht<N>=<dimen>",
),
(
"\\dp",
"Boxes",
"The depth of box register N, read and assigned as `\\wd` is.",
"\\dp<N>=<dimen>",
),
(
"\\showbox",
"Boxes",
"Display box register N as \u{a7}1296 and \u{a7}173-\u{a7}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",
),
(
"\\unhbox",
"Boxes",
"Append the contents of an hbox register to the current horizontal list and void the register (\u{a7}1110); `\\unhcopy` keeps it. Unboxing a vbox here is `Incompatible list can't be unboxed`.",
"\\unhbox<N> \\unhcopy<N>",
),
(
"\\unvbox",
"Boxes",
"The vertical counterpart of `\\unhbox` (\u{a7}1110); `\\unvcopy` keeps the register.",
"\\unvbox<N> \\unvcopy<N>",
),
(
"\\raise",
"Boxes",
"Shift the box that follows up in a horizontal list (\u{a7}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",
),
(
"\\hskip",
"Boxes",
"Glue in a horizontal list (\u{a7}1060), from a glue specification or a `\\skip` register; `\\hfil`, `\\hfill`, `\\hss` and `\\hfilneg` are the four fixed ones of \u{a7}1058. `\\vskip` and its four are the vertical versions.",
"\\hskip 3pt plus 1fil minus 1pt \\hfil \\hss",
),
(
"\\kern",
"Boxes",
"A rigid space in the current list (\u{a7}1061), explicit -- which `\\showbox` marks with a space after `\\kern` and a break may discard.",
"\\kern 3pt",
),
(
"\\penalty",
"Boxes",
"A penalty node (\u{a7}1103). `\\unpenalty`, `\\unkern` and `\\unskip` remove the last node of the current list when it is of that kind (\u{a7}1105).",
"\\penalty-50 \\unpenalty",
),
(
"\\hrule",
"Boxes",
"A rule in a vertical list, 0.4pt tall and as wide as the box it lands in unless `width`, `height` and `depth` say otherwise (\u{a7}463); the box after it gets no interline glue (\u{a7}1056). `\\vrule` is the horizontal-list rule, 0.4pt wide.",
"\\hrule height 2pt \\vrule width 1pt",
),
(
"\\leaders",
"Boxes",
"Glue filled with copies of a box or a rule (\u{a7}1078): the box or rule, then the glue it fills. `\\cleaders` centres the copies and `\\xleaders` spreads them.",
"\\leaders\\hrule\\hfil \\cleaders\\hbox{.}\\hfil",
),
(
"\\discretionary",
"Boxes",
"A discretionary break with its pre-break, post-break and replacement lists, each built in restricted horizontal mode (\u{a7}1117-\u{a7}1121). `\\-` is one whose pre-break text is the font's hyphen character.",
"\\discretionary{a}{b}{c} ab\\-cd",
),
(
"\\mark",
"Boxes",
"A mark node holding its text, expanded as `\\message` expands it (\u{a7}1101).",
"\\mark{hello}",
),
(
"\\topmark",
"Boxes",
"The mark that was `\\botmark` when the current page began (\u{a7}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}",
),
(
"\\firstmark",
"Boxes",
"The first mark on the page the output routine is working on, or `\\topmark` when the page has none (\u{a7}1014, \u{a7}1012). Read as `\\topmark` is.",
"\\headline={\\firstmark\\hfil}",
),
(
"\\botmark",
"Boxes",
"The last mark on the page the output routine is working on (\u{a7}1014). Read as `\\topmark` is.",
"\\footline={\\hfil\\botmark}",
),
(
"\\splitfirstmark",
"Boxes",
"The first mark in the material the last `\\vsplit` took off (\u{a7}979). Read as `\\topmark` is.",
"\\setbox2\\vsplit1 to 1in [\\splitfirstmark]",
),
(
"\\splitbotmark",
"Boxes",
"The last mark in the material the last `\\vsplit` took off (\u{a7}979). Read as `\\topmark` is.",
"\\setbox2\\vsplit1 to 1in [\\splitbotmark]",
),
(
"\\showlists",
"Boxes",
"Show what is being built at every level of the semantic nest, innermost first (\u{a7}218-\u{a7}219): each list with the mode it is in and the line it began on, a formula's noads (\u{a7}690-\u{a7}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 (\u{a7}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$",
),
(
"\\deadcycles",
"Boxes",
"How many times the output routine has run since a page was last shipped (\u{a7}592): past `\\maxdeadcycles` the page builder ships the page itself. Assigned in place (\u{a7}1246), as an output routine that holds a page back does.",
"\\output={\\global\\setbox1\\box255 \\deadcycles=0 }",
),
(
"\\insertpenalties",
"Boxes",
"The sum of the penalties of the insertions held over to the next page (\u{a7}982), and in the output routine the number of insertions held over (\u{a7}1018). Assigned in place (\u{a7}1246).",
"\\showthe\\insertpenalties",
),
(
"\\pagegoal",
"Boxes",
"The height the current page is being filled to (\u{a7}982): `\\vsize` less what the insertions on it take, `\\maxdimen` before the page has a box. Assigned in place (\u{a7}1245), which is how an output routine says how much room is left.",
"\\pagegoal=\\maxdimen",
),
(
"\\pagetotal",
"Boxes",
"The natural height of the current page so far (\u{a7}982). Assigned in place (\u{a7}1245).",
"\\showthe\\pagetotal",
),
(
"\\pagestretch",
"Boxes",
"The finite stretch of the glue on the current page (\u{a7}982); `\\pagefilstretch`, `\\pagefillstretch` and `\\pagefilllstretch` are the infinite orders. Assigned in place (\u{a7}1245).",
"\\showthe\\pagestretch",
),
(
"\\pagefilstretch",
"Boxes",
"The `fil` stretch on the current page (\u{a7}982), as `\\pagestretch` is the finite one.",
"\\showthe\\pagefilstretch",
),
(
"\\pagefillstretch",
"Boxes",
"The `fill` stretch on the current page (\u{a7}982).",
"\\showthe\\pagefillstretch",
),
(
"\\pagefilllstretch",
"Boxes",
"The `filll` stretch on the current page (\u{a7}982).",
"\\showthe\\pagefilllstretch",
),
(
"\\pageshrink",
"Boxes",
"The shrink of the glue on the current page (\u{a7}982). Assigned in place (\u{a7}1245).",
"\\showthe\\pageshrink",
),
(
"\\pagedepth",
"Boxes",
"The depth of the last box on the current page (\u{a7}982). Assigned in place (\u{a7}1245).",
"\\showthe\\pagedepth",
),
(
"\\halign",
"Boxes",
"A table of rows (\u{a7}768-\u{a7}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, \u{a7}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 (\u{a7}1206), which is how plain.tex's `\\eqalignno` and `\\displaylines` are built.",
"\\halign{#\\hfil&\\hfil#\\cr name&value\\cr alpha&1\\cr}",
),
(
"\\valign",
"Boxes",
"`\\halign` turned on its side (\u{a7}768): columns of entries set in vertical mode, whose heights are aligned across the columns.",
"\\hbox{\\valign{\\hbox{#}\\vfil\\cr a\\cr b\\cr}}",
),
(
"\\cr",
"Boxes",
"End a row of an alignment, or its preamble (\u{a7}780, \u{a7}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",
"Boxes",
"`\\cr`, except that right after a `\\cr` (or at the start of the alignment's body) it does nothing (\u{a7}785), so a macro can end a row whether or not its argument already did.",
"\\halign{#\\cr a\\cr\\crcr}",
),
(
"\\span",
"Boxes",
"In an alignment's body, join the entry to the next column's, so the two are set as one entry spanning both (\u{a7}791, \u{a7}798); in a preamble, expand the token after it (\u{a7}782).",
"\\halign{#&#\\cr a\\span b\\cr}",
),
(
"\\omit",
"Boxes",
"At the start of an entry, leave out its column's templates (\u{a7}788-\u{a7}789).",
"\\halign{[#]&#\\cr \\omit a&b\\cr}",
),
(
"\\noalign",
"Boxes",
"Between two rows of an alignment, material for the list the rows are in, in its own group (\u{a7}785, \u{a7}1133): a rule, a skip, a penalty.",
"\\halign{#\\cr a\\cr\\noalign{\\hrule}b\\cr}",
),
(
"\\insert",
"Boxes",
"An 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 (\u{a7}1099-\u{a7}1100). `\\vadjust` is the same with material for the enclosing vertical list.",
"\\insert100{\\hbox{n}} \\vadjust{\\kern2pt}",
),
(
"\\shipout",
"Boxes",
"Ship the box that follows as a page (\u{a7}638-\u{a7}641): the terminal says `[` and `\\count0..9` and `]`, as tex does.",
"\\shipout\\hbox{page}",
),
(
"\\unhcopy",
"Boxes",
"`\\unhbox` that leaves the register as it was (\u{a7}1110).",
"\\unhcopy<N>",
),
(
"\\unvcopy",
"Boxes",
"`\\unvbox` that leaves the register as it was (\u{a7}1110).",
"\\unvcopy<N>",
),
(
"\\lower",
"Boxes",
"Shift the box that follows down in a horizontal list: a positive `shift_amount` (\u{a7}1073).",
"\\lower1pt\\hbox{a}",
),
(
"\\moveleft",
"Boxes",
"Shift the box that follows left in a vertical list: a negative `shift_amount` (\u{a7}1073).",
"\\moveleft2pt\\hbox{a}",
),
(
"\\moveright",
"Boxes",
"Shift the box that follows right in a vertical list (\u{a7}1073).",
"\\moveright2pt\\hbox{a}",
),
(
"\\hfil",
"Boxes",
"`\\hskip 0pt plus 1fil` (\u{a7}1058).",
"\\hfil",
),
(
"\\hfill",
"Boxes",
"`\\hskip 0pt plus 1fill` (\u{a7}1058).",
"\\hfill",
),
(
"\\hss",
"Boxes",
"`\\hskip 0pt plus 1fil minus 1fil` (\u{a7}1058), which lets a box shrink past its contents.",
"\\hbox to 0pt{\\hss x}",
),
(
"\\hfilneg",
"Boxes",
"`\\hskip 0pt plus -1fil` (\u{a7}1058), cancelling one `\\hfil`.",
"\\hfilneg",
),
(
"\\vskip",
"Boxes",
"Glue in a vertical list (\u{a7}1060), as `\\hskip` is in a horizontal one.",
"\\vskip 4pt plus 1fil",
),
(
"\\vfil",
"Boxes",
"`\\vskip 0pt plus 1fil` (\u{a7}1058).",
"\\vfil",
),
(
"\\vfill",
"Boxes",
"`\\vskip 0pt plus 1fill` (\u{a7}1058).",
"\\vfill",
),
(
"\\vss",
"Boxes",
"`\\vskip 0pt plus 1fil minus 1fil` (\u{a7}1058).",
"\\vss",
),
(
"\\vfilneg",
"Boxes",
"`\\vskip 0pt plus -1fil` (\u{a7}1058).",
"\\vfilneg",
),
(
"\\vrule",
"Boxes",
"A 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 (\u{a7}463).",
"\\vrule width 1pt",
),
(
"\\cleaders",
"Boxes",
"Leaders whose copies are centred in the glue (\u{a7}1078, \u{a7}626).",
"\\cleaders\\hbox{.}\\hfil",
),
(
"\\xleaders",
"Boxes",
"Leaders whose leftover space is spread between the copies (\u{a7}1078, \u{a7}626).",
"\\xleaders\\hbox{.}\\hfil",
),
(
"\\unpenalty",
"Boxes",
"Remove the last node of the current list if it is a penalty (\u{a7}1105).",
"\\unpenalty",
),
(
"\\unkern",
"Boxes",
"Remove the last node of the current list if it is a kern (\u{a7}1105).",
"\\unkern",
),
(
"\\unskip",
"Boxes",
"Remove the last node of the current list if it is glue (\u{a7}1105); on the page's own list, where the page builder has the node, it does nothing.",
"\\unskip",
),
(
"\\vadjust",
"Boxes",
"Material for the vertical list enclosing the paragraph, built in internal vertical mode (\u{a7}1099-\u{a7}1100).",
"\\vadjust{\\kern2pt}",
),
(
"\\prevdepth",
"Boxes",
"The depth of the last box on the current vertical list, which the next interline glue is computed from (\u{a7}679); assignable in vertical mode (\u{a7}1242). `-1000pt` means no interline glue before the next box.",
"\\prevdepth=-1000pt",
),
(
"\\spacefactor",
"Boxes",
"The space factor of the current horizontal list (\u{a7}1034, \u{a7}1043), read and assigned in horizontal mode.",
"\\spacefactor=3000",
),
(
"\\indent",
"Boxes",
"In horizontal mode, an empty box `\\parindent` wide (\u{a7}1093). Starting a paragraph with it in vertical mode needs the paragraph builder, which the list path does not have yet.",
"\\hbox{\\indent x}",
),
(
"\\noindent",
"Boxes",
"In horizontal mode, nothing (\u{a7}1093). Starting a paragraph with it in vertical mode needs the paragraph builder, which the list path does not have yet.",
"\\hbox{\\noindent x}",
),
(
"\\noboundary",
"Boxes",
"Cancel the font's boundary character on that side of the next or previous run of characters (\u{a7}1034, \u{a7}1038), so a boundary ligature or kern is not made.",
"\\hbox{\\noboundary ab}",
),
(
"\\prevgraf",
"Boxes",
"The number of lines in the most recent paragraph of the nearest enclosing vertical list (\u{a7}422), read and assigned (\u{a7}1244).",
"\\prevgraf=2",
),
(
"\\fontdimen",
"Boxes",
"Font parameter N of a font (tex.web \u{a7}558, \u{a7}578): read as a dimension, and assigned globally (\u{a7}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\n\\message{\\the\\fontdimen6\\tenrm}",
),
(
"\\hyphenchar",
"Boxes",
"The character a font hyphenates with (\u{a7}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",
),
(
"\\skewchar",
"Boxes",
"The character whose kerns position a font's math accents (\u{a7}1253).",
"\\skewchar\\teni='177",
),
(
"\\patterns",
"Boxes",
"Liang hyphenation patterns (\u{a7}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}",
),
(
"\\accent",
"Boxes",
"Put character N of the current font over the character that follows (\u{a7}1123-\u{a7}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>\n\\accent\"13 e % plain.tex's \\'e",
),
(
"\\parshape",
"Boxes",
"Give the next paragraph a shape line by line (\u{a7}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 (\u{a7}1149), and is reset by the end of the paragraph (\u{a7}1070) and by its group. `\\the\\parshape` is not read on the list path yet.",
"\\parshape 2 0pt 4in 1in 3in\nA first line four inches wide, the rest three inches wide and indented an inch.\\par",
),
(
"\\hyphenation",
"Boxes",
"Words with their hyphens written in (\u{a7}934), which the second pass takes over the patterns.",
"\\hyphenation{man-u-script}",
),
// ══ Mathematics — lower/math.rs, stomach/math.rs, math/mlist.rs ═══════
(
"\\mathord",
"Mathematics",
"Make the next math field an Ord atom (\u{a7}1158). `\\mathop`, `\\mathbin`, `\\mathrel`, `\\mathopen`, `\\mathclose`, `\\mathpunct` and `\\mathinner` make the other seven classes; the class decides the spacing \u{a7}764's table puts around the atom. The field is a character or a subformula in braces (\u{a7}1151).",
"$\\mathord{+}x$",
),
("\\mathop", "Mathematics", "An Op atom (\u{a7}1158): a large operator, with limits above and below in display style unless `\\nolimits` says otherwise (\u{a7}749).", "$\\mathop{\\rm sup}\\limits_x f$"),
("\\mathbin", "Mathematics", "A Bin atom (\u{a7}1158): a binary operator, which \u{a7}728 turns into an Ord where nothing binary surrounds it, and after which \u{a7}767 allows a break at `\\binoppenalty`.", "$a\\mathbin{\\#}b$"),
("\\mathrel", "Mathematics", "A Rel atom (\u{a7}1158): a relation, with thick spaces either side and a break after it at `\\relpenalty` (\u{a7}767).", "$a\\mathrel{:=}b$"),
("\\mathopen", "Mathematics", "An Open atom (\u{a7}1158): an opening bracket, after which \u{a7}764 puts no space.", "$\\mathopen{[}x$"),
("\\mathclose", "Mathematics", "A Close atom (\u{a7}1158): a closing bracket, before which \u{a7}764 puts no space.", "$x\\mathclose{]}$"),
("\\mathpunct", "Mathematics", "A Punct atom (\u{a7}1158), with a thin space after it outside the script styles.", "$x\\mathpunct{;}y$"),
("\\mathinner", "Mathematics", "An Inner atom (\u{a7}1158), the class a `\\left`..`\\right` subformula gets (\u{a7}1191).", "$\\mathinner{\\ldotp\\ldotp\\ldotp}$"),
("\\underline", "Mathematics", "An Under atom (\u{a7}1158): its nucleus with a rule `default_rule_thickness` thick below it (\u{a7}735).", "$\\underline{ab}$"),
("\\overline", "Mathematics", "An Over atom (\u{a7}1158): its nucleus with a rule above it, cramped (\u{a7}734).", "$\\overline{ab}$"),
("\\limits", "Mathematics", "After an Op atom, set its scripts above and below in every style (\u{a7}1159); elsewhere it is the error `Limit controls must follow a math operator`.", "$\\sum\\limits_{i=1}^n$"),
("\\nolimits", "Mathematics", "After an Op atom, set its scripts beside it in every style (\u{a7}1159).", "$\\int\\nolimits_0^1$"),
("\\displaylimits", "Mathematics", "After an Op atom, the default: limits above and below in display style only (\u{a7}1159).", "$\\mathop{\\rm max}\\displaylimits_x$"),
("\\radical", "Mathematics", "A radical noad with a 24-bit delimiter code, over the next field (\u{a7}1163); plain.tex's `\\sqrt` is `\\radical\"270370`. The sign grows to the height of its nucleus plus the clearance \u{a7}737 computes.", "$\\radical\"270370{x+1}$"),
("\\mathaccent", "Mathematics", "An accent noad with a 15-bit math code, over the next field (\u{a7}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 (\u{a7}741).", "$\\mathaccent\"705E x$"),
("\\vcenter", "Mathematics", "A vbox centred on the math axis (\u{a7}1167-\u{a7}1168, \u{a7}736), as a noad of its own; `to` and `spread` are read as for `\\vbox`.", "$\\vcenter{\\hbox{a}\\hbox{b}}$"),
("\\displaystyle", "Mathematics", "A style node (\u{a7}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 (\u{a7}703).", "$\\displaystyle{a\\over b}$"),
("\\textstyle", "Mathematics", "A style node for text style (\u{a7}1171).", "$$\\textstyle\\sum_i x_i$$"),
("\\scriptstyle", "Mathematics", "A style node for script style (\u{a7}1171): the script size fonts.", "$\\scriptstyle a+b$"),
("\\scriptscriptstyle", "Mathematics", "A style node for scriptscript style (\u{a7}1171).", "$\\scriptscriptstyle a+b$"),
("\\nonscript", "Mathematics", "Glue that deletes the glue or kern right after it when the formula is in a script style (\u{a7}1171, \u{a7}732).", "$a\\nonscript\\mskip\\thinmuskip b$"),
("\\mathchoice", "Mathematics", "Four subformulas, for display, text, script and scriptscript style; the one the style at that point asks for is set (\u{a7}1172-\u{a7}1174, \u{a7}731). plain.tex's `\\mathpalette` is built on it.", "$\\mathchoice{D}{T}{S}{SS}$"),
("\\over", "Mathematics", "Make everything so far in the subformula the numerator and everything after it the denominator, with a bar `default_rule_thickness` thick (\u{a7}1181-\u{a7}1185). Two in one subformula is `Ambiguous; you need another { and }`.", "${n+1\\over2}$"),
("\\atop", "Mathematics", "A fraction with no bar (\u{a7}1182).", "${n\\atop k}$"),
("\\above", "Mathematics", "A fraction with a bar of the thickness given (\u{a7}1182).", "${a\\above1pt b}$"),
("\\overwithdelims", "Mathematics", "`\\over` with a delimiter on each side, each grown to `delim1` or `delim2` (\u{a7}748); `\\atopwithdelims` and `\\abovewithdelims` likewise. plain.tex's `\\choose` is `\\atopwithdelims()`.", "${a\\overwithdelims() b}$"),
("\\atopwithdelims", "Mathematics", "`\\atop` with delimiters (\u{a7}1182).", "${n\\atopwithdelims() k}$"),
("\\abovewithdelims", "Mathematics", "`\\above` with delimiters (\u{a7}1182).", "${a\\abovewithdelims[]1pt b}$"),
("\\left", "Mathematics", "Open a subformula whose delimiters grow to its height and depth (\u{a7}1191, \u{a7}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)$"),
("\\right", "Mathematics", "Close the `\\left` subformula (\u{a7}1191); outside one it is `Extra \\right`.", "$\\left[x\\right.$"),
("\\eqno", "Mathematics", "In a display, set what follows to the closing `$$` as the equation number, at the right (\u{a7}1142, \u{a7}1199-\u{a7}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)$$"),
("\\leqno", "Mathematics", "The same with the number at the left (\u{a7}1142, \u{a7}1203).", "$$x=1\\leqno(2)$$"),
("\\mkern", "Mathematics", "A kern in math units: eighteen mu are the quad of the family 2 font at the size the formula is set in (\u{a7}717).", "$a\\mkern18mu b$"),
("\\mskip", "Mathematics", "Glue in math units (\u{a7}716), converted at the size it lands in; `\\thinmuskip`, `\\medmuskip` and `\\thickmuskip` are the three \u{a7}764's spacing table uses.", "$a\\mskip\\thickmuskip b$"),
("\\mathchar", "Mathematics", "A math character by its 15-bit code: class, family and character, as `\\mathcode` holds them (\u{a7}1154-\u{a7}1155). Class 7 takes its family from `\\fam` when that is 0..15.", "$\\mathchar\"7141$"),
("\\delimiter", "Mathematics", "A delimiter by its 27-bit code (\u{a7}1160): where a delimiter is wanted it is that, and as a math character it is its class and small variant (\u{a7}1154).", "$\\left\\delimiter\"426630A x\\right.$"),
// ══ Intercepts — intercepts.rs, expand::weave_advice ══════════════════
(
"\\intercept",
"Intercepts",
"Register 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}\n\\def\\greet#1{HELLO-#1}\n\\def\\trace{[in]}\n\\intercept{before}{greet}{\\trace}\n\\message{\\greet{WORLD}} % => [in]HELLO-WORLD",
),
(
"\\proceed",
"Intercepts",
"Inside 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>>}\n\\intercept{around}{greet}{\\loud}\n\\message{\\greet{WORLD}} % => <<HELLO-WORLD>>",
),
(
"\\char",
"Registers",
"Set the character of a code in the text (tex.web \u{a7}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",
),
(
"\\chardef",
"Registers",
"Define 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\n\\catcode`\\~=\\active",
),
(
"\\countdef",
"Registers",
"Give 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\n\\pageno=7\n\\advance\\pageno by 1",
),
(
"\\long",
"Macro definition",
"A 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]}",
),
(
"\\outer",
"Macro definition",
"A 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{...}",
),
(
"\\mathcode",
"Registers",
"How a character is set in math mode, as a 15-bit code: class, family and position. INITEX gives a letter \u{a7}7100+c, a digit \u{a7}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",
),
(
"\\lccode",
"Registers",
"A 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",
),
(
"\\uccode",
"Registers",
"The same for uppercase, consulted by `\\uppercase`. Also 0 for a character with no case.",
"\\uccode`\\a=`\\A",
),
(
"\\sfcode",
"Registers",
"The 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",
),
(
"\\delcode",
"Registers",
"A 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",
),
(
"\\mathchardef",
"Registers",
"Define 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\n\\mathcode`\\y=\\half",
),
(
"\"",
"Registers",
"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\n\\count2='777 % 511",
),
(
"\\dimen",
"Registers",
"A 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 \u{a7}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 \u{a7}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 (\u{a7}103), the fewest digits that read back as the same integer, and `\\number` gives the scaled points instead.",
"\\dimen0=1in\n\\message{\\the\\dimen0} % => 72.26999pt",
),
(
"\\dimendef",
"Registers",
"Give 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\n\\dimen@=2pt",
),
(
"\\skip",
"Registers",
"A 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\n\\skip1=0pt plus 1fil",
),
(
"\\skipdef",
"Registers",
"Give 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\n\\skip@=1pt plus 2pt",
),
(
"\\muskip",
"Registers",
"A MATH glue register: the same natural-plus-stretch-minus-shrink a `\\skip` holds, measured in mu. tex.web \u{a7}455 makes `mu` the only finite unit a math glue may be written in, and the only place `mu` is a unit at all \u{2014} `\\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\n\\message{[\\the\\muskip0]} % => [3.0mu plus 1.0mu minus 2.0mu]",
),
(
"\\muskipdef",
"Registers",
"Give 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\n\\thinmuskip=3mu",
),
(
"\\toks",
"Registers",
"A 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}\n\\message{\\the\\toks0} % => a\\b c",
),
(
"\\toksdef",
"Registers",
"Give 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\n\\toks@={...}",
),
(
"\\attribute",
"Registers",
"LuaTeX'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\n\\attribute5=3 \\message{\\the\\attribute5} % => 3",
),
(
"\\attributedef",
"Registers",
"Give an attribute register a name, as `\\countdef` does for a count; `\\meaning` writes the register (`\\attribute5`).",
"\\attributedef\\a=5\n\\a=3",
),
// ══ eTeX extensions — expand::scan_expr ═══════════════════════════════
(
"\\numexpr",
"Registers",
"An 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",
),
(
"\\dimexpr",
"Registers",
"The 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",
),
(
"\\unless",
"Conditionals",
"Negate 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",
),
(
"\\protected",
"Macro definition",
"A 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]}",
),
(
"\\detokenize",
"Expansion",
"The 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",
"Expansion",
"`\\string` without the escape character: `\\csstring\\foo` is `foo` where `\\string\\foo` is `\\foo`. A LuaTeX primitive.",
"\\message{\\csstring\\foo} % => foo",
),
(
"\\romannumeral",
"Expansion",
"A number as lowercase roman numerals, by tex.web \u{a7}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>\n\\message{\\romannumeral 1984} % => mcmlxxxiv",
),
(
"\\jobname",
"Expansion",
"The job's name, as characters (tex.web \u{a7}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\n\\message{\\jobname} % => report",
),
(
"\\Uchar",
"Expansion",
"The 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",
),
(
"\\expanded",
"Expansion",
"Expand 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}}",
),
(
"\\unexpanded",
"Expansion",
"The 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}}",
),
(
"\\scantokens",
"Expansion",
"Read 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",
"Expansion",
"`\\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",
),
(
"\\lastnamedcs",
"Expansion",
"The 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",
),
(
"\\immediateassignment",
"Expansion",
"Carry 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",
),
(
"\\immediateassigned",
"Expansion",
"The 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",
"Expansion",
"`\\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",
),
(
"\\gluestretch",
"Registers",
"The 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",
),
(
"\\glueshrink",
"Registers",
"The shrink of a glue, as a dimension; see `\\gluestretch`.",
"\\dimen0=\\glueshrink\\skip0",
),
(
"\\gluestretchorder",
"Registers",
"The 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",
),
(
"\\glueshrinkorder",
"Registers",
"The order of a glue's shrink, LuaTeX's numbering; see `\\gluestretchorder`.",
"\\count0=\\glueshrinkorder\\skip0",
),
(
"\\eTeXgluestretchorder",
"Registers",
"The order of a glue's stretch as e-TeX counts it: 0 finite, 1 `fil`, 2 `fill`, 3 `filll`.",
"\\count0=\\eTeXgluestretchorder\\skip0",
),
(
"\\eTeXglueshrinkorder",
"Registers",
"The order of a glue's shrink as e-TeX counts it.",
"\\count0=\\eTeXglueshrinkorder\\skip0",
),
(
"\\glueexpr",
"Registers",
"A 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",
),
(
"\\muexpr",
"Registers",
"The same expression grammar over MATH glue, and the only kind of expression a `\\muskip` assignment accepts \u{2014} 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",
),
(
"\\gluetomu",
"Registers",
"The 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",
),
(
"\\mutoglue",
"Registers",
"The 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",
),
// ══ Files — lower::open_input ═════════════════════════════════════════
(
"\\input",
"Files",
"Read 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 \u{a7}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\n\\input chapters/one.tex",
),
(
"\\endinput",
"Files",
"End the file being read with the line `\\endinput` is on (tex.web \u{a7}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\n\\message{last}\\endinput\\message{still read}",
),
(
"\\openin",
"Files",
"Open a `\\read` stream on a file (tex.web \u{a7}1275): the stream is closed first, then opened on the file the name finds \u{2014} searched for as `\\input` searches, with `.tex` supplied \u{2014} 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>\n\\openin3=data \\ifeof3 \\message{no data}\\fi",
),
(
"\\closein",
"Files",
"Close a `\\read` stream (tex.web \u{a7}1275), so `\\ifeof` is true for it.",
"\\closein<0-15>\n\\closein3",
),
(
"\\read",
"Files",
"Define a macro as the next line of a stream (tex.web \u{a7}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 \u{2014} 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>\n\\openin3=data \\read3 to\\line \\message{\\meaning\\line}",
),
(
"\\readline",
"Files",
"e-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>\n\\openin3=data \\readline3 to\\line",
),
// ══ Inline Rust — rust_ffi.rs, fusevm::ffi ════════════════════════════
(
"\\rust",
"Inline Rust",
"Open a block of Rust compiled and loaded at run time. The body is Rust, not TeX \u{2014} 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> }\n\\rust{\n #[no_mangle]\n pub extern \"C\" fn twice(n: i64) -> i64 { n * 2 }\n}",
),
(
"\\rustcall",
"Inline Rust",
"Call 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 \u{2014} a register assignment, an arithmetic operand, a conditional, or a `\\message` body \u{2014} and in running text it is called for its effect with the value dropped.",
"\\rustcall <name> <numbers…>\\endrust\n\\count1=21\n\\message{\\rustcall twice \\count1 \\endrust} % => 42\n\\count2=\\rustcall add \\count1 22 \\endrust",
),
(
"\\rustcompile",
"Inline Rust",
"What 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",
),
(
"\\endrust",
"Inline Rust",
"Terminate 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",
),
// ══ Grouping — expand::begin_group / end_group, lower's save/restore ═══
(
"{",
"Grouping",
"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>}\n\\def\\v{OUT}\n{\\def\\v{IN}\\message{\\v}} % => IN\n\\message{\\v} % => OUT",
),
(
"}",
"Grouping",
"Close a group (category code 2), undoing every non-global assignment made inside it.",
"{<body>}",
),
(
"\\begingroup",
"Grouping",
"Open 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",
),
(
"\\endgroup",
"Grouping",
"Close 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",
),
(
"\\aftergroup",
"Grouping",
"Hold the next token and insert it after the enclosing group closes (tex.web \u{a7}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 `}` \u{2014} 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>\n{\\aftergroup\\message\\aftergroup{\\aftergroup X\\aftergroup}} % => X",
),
(
"\\afterassignment",
"Grouping",
"Hold the next token until the following ASSIGNMENT has finished (tex.web \u{a7}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>\n\\def\\m{\\message{DONE}}\n\\afterassignment\\m \\count1=5 % => DONE, with \\count1 already 5",
),
(
"\\currentgrouplevel",
"Grouping",
"How many groups are open, a read-only integer: 0 outside every group. An eTeX primitive.",
"{\\message{\\the\\currentgrouplevel}} % => 1",
),
(
"\\currentgrouptype",
"Grouping",
"What 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",
),
(
"\\showgroups",
"Grouping",
"List 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}",
),
// ══ PDF backend — backend.rs, pdfdoc.rs, pdfpage.rs ═══════════════════
(
"\\pdfvariable",
"PDF backend",
"LuaTeX'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\n\\message{\\the\\pdfvariable compresslevel} % => 0\n\\pdfvariable pageresources{/ExtGState 12 0 R}",
),
(
"\\pdffeedback",
"PDF backend",
"What 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 >>}\n\\message{\\pdffeedback lastobj} % => 1",
),
(
"\\pdfextension",
"PDF backend",
"LuaTeX'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}\n\\pdfextension info{/Title (A report)}\n\\pdfextension literal{1 0 0 rg}",
),
(
"\\saveimageresource",
"PDF backend",
"Read 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}\n\\useimageresource\\lastsavedimageresourceindex",
),
(
"\\useimageresource",
"PDF backend",
"Place 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",
),
(
"\\saveboxresource",
"PDF backend",
"Save 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\n\\useboxresource\\lastsavedboxresourceindex",
),
(
"\\useboxresource",
"PDF backend",
"Place a saved form (`scan_pdfrefxform`): optional dimensions and the number. A whatsit for the page.",
"\\useboxresource\\lastsavedboxresourceindex",
),
(
"\\lastsavedimageresourceindex",
"PDF backend",
"The number the last `\\saveimageresource` gave its picture: an internal integer.",
"\\message{\\the\\lastsavedimageresourceindex}",
),
(
"\\lastsavedimageresourcepages",
"PDF backend",
"How many pages the last `\\saveimageresource`'s file holds: 1, since only a picture's file is counted yet.",
"\\message{\\the\\lastsavedimageresourcepages}",
),
(
"\\lastsavedboxresourceindex",
"PDF backend",
"The number the last `\\saveboxresource` gave its form, assigned when the form is read; `\\useboxresource` takes it.",
"\\message{\\the\\lastsavedboxresourceindex}",
),
(
"\\savepos",
"PDF backend",
"A 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 — latex.rs, expand::do_newcommand ════════════════════════════
(
"\\newcommand",
"LaTeX",
"Define 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}\n\\newcommand{\\greet}[1]{hello #1}\n\\message{\\greet{world}} % => hello world",
),
(
"\\renewcommand",
"LaTeX",
"Redefine a macro. Identical to `\\newcommand` here, because texrs does not check whether the name already exists in either direction.",
"\\renewcommand{\\NAME}[ARGC]{BODY}\n\\newcommand{\\x}{one}\n\\renewcommand{\\x}{two}\n\\message{\\x} % => two",
),
(
"\\providecommand",
"LaTeX",
"Define 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}\n\\newcommand{\\x}{first}\n\\providecommand{\\x}{second}\n\\message{\\x} % => first",
),
(
"\\DeclareRobustCommand",
"LaTeX",
"Define 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}\n\\DeclareRobustCommand{\\x}{text}\n\\message{\\x} % => text",
),
(
"\\documentclass",
"LaTeX",
"Consumed, 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}\n\\documentclass[12pt]{article}\n\\message{the body still runs}",
),
(
"\\usepackage",
"LaTeX",
"Consumed 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}\n\\usepackage[margin=0.95in]{geometry}",
),
(
"\\RequirePackage",
"LaTeX",
"Consumed 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}\n\\RequirePackage{amsmath}",
),
(
"\\PassOptionsToPackage",
"LaTeX",
"Consumed with both of its arguments, producing nothing, because the package it would have carried options to is never loaded.",
"\\PassOptionsToPackage{OPTIONS}{PACKAGE}\n\\PassOptionsToPackage{dvipsnames}{xcolor}",
),
(
"\\PassOptionsToClass",
"LaTeX",
"Consumed with both of its arguments, producing nothing. The class counterpart of `\\PassOptionsToPackage`.",
"\\PassOptionsToClass{OPTIONS}{CLASS}\n\\PassOptionsToClass{a4paper}{article}",
),
(
"\\begin",
"LaTeX",
"Open 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}\n\\begin{verbatim}\n\\this is text, not a command\n\\end{verbatim}",
),
// ── Page structure — lower::lower_page_break ─────────────────────────
(
"\\newpage",
"LaTeX",
"Start 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\nfirst page\n\\newpage\nsecond page",
),
(
"\\clearpage",
"LaTeX",
"Start 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",
),
(
"\\cleardoublepage",
"LaTeX",
"Start 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",
),
(
"\\pagebreak",
"LaTeX",
"Break 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\n\\pagebreak[4]",
),
(
"\\chapter",
"LaTeX",
"Begin 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}\n\\chapter*{Preface}\n\\chapter[Short]{A Longer Title}",
),
(
"\\section",
"LaTeX",
"Begin 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}\n\\section*{Unnumbered}\n\\section[Short]{A Longer Title}",
),
(
"\\subsection",
"LaTeX",
"Begin 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}\n\\subsection*{Unnumbered}",
),
(
"\\subsubsection",
"LaTeX",
"Begin a subsubsection, set as `\\section` and `\\subsection` are: its own lines, with a line of vertical space above and below.",
"\\subsubsection{TITLE}\n\\subsubsection*{Unnumbered}",
),
// ── Contents — lower::lower_page_break, typeset::contents_set ────────
(
"\\tableofcontents",
"LaTeX",
"Set 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}\n\\tableofcontents\n\\chapter{First}",
),
(
"\\setcounter",
"LaTeX",
"Set 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}\n\\setcounter{secnumdepth}{-1}",
),
(
"\\endtitlepage",
"LaTeX",
"End 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}\ncover\n\\end{titlepage}",
),
// ── Cross-references — lower::lower_cross_ref, typeset::refs_numbered ─
(
"\\label",
"LaTeX",
"Name 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}",
),
(
"\\ref",
"LaTeX",
"Set 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}.",
),
(
"\\pageref",
"LaTeX",
"Set 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}.",
),
// ── Centring — lower::lower_centre ───────────────────────────────────
(
"\\center",
"LaTeX",
"Start 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}\ncentred\n\\end{center}",
),
(
"\\endcenter",
"LaTeX",
"Stop centring: what `\\end{center}` runs, and the close of the region `\\center` opened. Lines after it go back to the left margin.",
"\\begin{center}\ncentred\n\\end{center}\nat the margin",
),
(
"\\centering",
"LaTeX",
"Centre 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}\nat the margin",
),
(
"\\centerline",
"LaTeX",
"Centre 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}\n\\centerline{a colophon}",
),
// ── Tables — lower::lower_table, typeset::table_lines ────────────────
(
"\\tabular",
"LaTeX",
"Open 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}\nName & Value \\\\\nalpha & 1 \\\\\n\\end{tabular}",
),
(
"\\endtabular",
"LaTeX",
"Close 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}\na & b \\\\\n\\end{tabular}",
),
(
"\\longtable",
"LaTeX",
"Open 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@{}}\n\\toprule\nName & Value \\\\\n\\midrule\n\\endhead\n\\bottomrule\n\\endlastfoot\nalpha & 1 \\\\\n\\end{longtable}",
),
(
"\\endlongtable",
"LaTeX",
"Close a longtable: what `\\end{longtable}` runs, and the same close `\\endtabular` is.",
"\\begin{longtable}[]{@{}ll@{}}\na & b \\\\\n\\end{longtable}",
),
(
"\\toprule",
"LaTeX",
"booktabs' 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}\n\\toprule\nName & Value \\\\\n\\bottomrule\n\\end{tabular}",
),
(
"\\midrule",
"LaTeX",
"booktabs' 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}\nName & Value \\\\\n\\midrule\nalpha & 1 \\\\\n\\end{tabular}",
),
(
"\\bottomrule",
"LaTeX",
"booktabs' 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}\nalpha & 1 \\\\\n\\bottomrule\n\\end{tabular}",
),
(
"\\hline",
"LaTeX",
"The 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}\n\\hline\na & b \\\\\n\\hline\n\\end{tabular}",
),
(
"\\tabularnewline",
"LaTeX",
"End 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}\na & b \\tabularnewline\nc & d \\tabularnewline\n\\end{tabular}",
),
(
"\\endhead",
"LaTeX",
"End 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@{}}\n\\toprule\nName & Value \\\\\n\\midrule\n\\endhead\nalpha & 1 \\\\\n\\end{longtable}",
),
(
"\\endfirsthead",
"LaTeX",
"End 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@{}}\nName & Value \\\\\n\\endfirsthead\nName & Value \\\\\n\\endhead\nalpha & 1 \\\\\n\\end{longtable}",
),
(
"\\endfoot",
"LaTeX",
"End 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@{}}\n\\endhead\n\\bottomrule\n\\endfoot\nalpha & 1 \\\\\n\\end{longtable}",
),
(
"\\endlastfoot",
"LaTeX",
"End 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@{}}\n\\endhead\n\\bottomrule\n\\endlastfoot\nalpha & 1 \\\\\n\\end{longtable}",
),
// ── Lists — lower::lower_list, typeset::fill ─────────────────────────
(
"\\itemize",
"LaTeX",
"Open 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}\n\\item first\n\\item second\n\\end{itemize}",
),
(
"\\enditemize",
"LaTeX",
"Close 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}\n\\item only\n\\end{itemize}\nback at the margin",
),
(
"\\enumerate",
"LaTeX",
"Open 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}\n\\item first\n\\item second\n\\end{enumerate}",
),
(
"\\endenumerate",
"LaTeX",
"Close a numbered list: what `\\end{enumerate}` runs, and the same close `\\enditemize` is.",
"\\begin{enumerate}\n\\item only\n\\end{enumerate}\nback at the margin",
),
(
"\\description",
"LaTeX",
"Open 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}\n\\item[term] what it means\n\\end{description}",
),
(
"\\enddescription",
"LaTeX",
"Close a list of terms: what `\\end{description}` runs, and the same close the other two lists have.",
"\\begin{description}\n\\item[term] meaning\n\\end{description}\nback at the margin",
),
(
"\\item",
"LaTeX",
"Start 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>\n\\begin{itemize}\n\\item plain\n\\item[!] labelled\n\\end{itemize}",
),
// ── Colour — lower::lower_colour, colour.rs ──────────────────────────
(
"\\definecolor",
"LaTeX",
"Name 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}\n\\definecolor{neonCyan}{HTML}{05D9E8}",
),
(
"\\providecolor",
"LaTeX",
"Define a colour only if that name is not already defined. Otherwise `\\definecolor`.",
"\\providecolor{NAME}{MODEL}{SPEC}\n\\providecolor{link}{HTML}{05D9E8}",
),
(
"\\colorlet",
"LaTeX",
"Give an existing colour another name. A name nothing has defined yet defines nothing.",
"\\colorlet{NEW}{OLD}\n\\definecolor{brand}{HTML}{FF2A6D}\n\\colorlet{heading}{brand}",
),
(
"\\color",
"LaTeX",
"Switch 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}\n\\color[MODEL]{SPEC}\n{\\color{neonCyan}cyan words}",
),
(
"\\textcolor",
"LaTeX",
"Colour 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}\n\\textcolor[MODEL]{SPEC}{TEXT}\n\\textcolor{red}{warning}",
),
(
"\\pagecolor",
"LaTeX",
"Paint 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}\n\\definecolor{bgPrimary}{HTML}{05050A}\n\\pagecolor{bgPrimary}",
),
(
"\\titleformat",
"LaTeX",
"titlesec'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}\n\\titleformat{\\chapter}[hang]{\\sffamily\\bfseries\\Huge}{}{0pt}{}\n\\titleformat*{\\section}{\\sffamily\\Large}",
),
(
"\\pandocbounded",
"LaTeX",
"Set 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}\n\\pandocbounded{\\includegraphics[keepaspectratio]{diagrams/plot.pdf}}",
),
(
"\\includegraphics",
"LaTeX",
"Place 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}\n\\includegraphics[width=0.8\\textwidth]{figures/plot.png}\n\\includegraphics[width=5cm,height=3cm]{cover.jpg}",
),
(
"\\setmainfont",
"LaTeX",
"Record 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]\n\\setmainfont{Arimo} % embedded if Arimo is installed, else Helvetica's metrics\n\\setmainfont{Arimo-VF.ttf}[Path=./.fonts/] % the file itself, embedded from Path=",
),
(
"\\setromanfont",
"LaTeX",
"The 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}\n\\setromanfont{Arimo} % identical in effect to \\setmainfont{Arimo}",
),
(
"\\setsansfont",
"LaTeX",
"Record 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]\n\\setsansfont{Arimo}",
),
(
"\\setmonofont",
"LaTeX",
"Record 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]\n\\setmonofont{Cousine}\n\\setmonofont{ShareTechMono}[Path=./.fonts/,Extension=.ttf,UprightFont=ShareTechMono-Regular]",
),
(
"\\directlua",
"LaTeX",
"Hand 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}\n\\count10=20 \\directlua{tex.print(tex.count[10]+5)}\n\\directlua{luaotfload.add_fallback(\"symfb\", {\"Arial Unicode MS:mode=base;\", \"Arial:mode=base;\"})}",
),
(
"\\ttfamily",
"LaTeX",
"Set 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}\n\\texttt{fixed pitch}",
),
(
"\\slshape",
"LaTeX",
"Set 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}\n\\textsl{leaning}",
),
(
"\\bfseries",
"LaTeX",
"Set 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}\n\\textbf{heavy}",
),
(
"\\itshape",
"LaTeX",
"Set 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}\n\\emph{stressed}",
),
(
"\\rmfamily",
"LaTeX",
"Back 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}",
),
(
"\\sffamily",
"LaTeX",
"Select 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}",
),
(
"\\normalfont",
"LaTeX",
"Undo 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}",
),
(
"\\makeatletter",
"LaTeX",
"Make `@` 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",
),
(
"\\makeatother",
"LaTeX",
"Make `@` 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",
),
];
/// The entry for `name`, if the corpus documents it.
pub fn lookup(name: &str) -> Option<&'static Entry> {
CORPUS.iter().find(|(n, ..)| *n == name)
}
/// Every name the corpus documents, with its leading backslash.
pub fn names() -> impl Iterator<Item = &'static str> {
CORPUS.iter().map(|(n, ..)| *n)
}