Command Reference

Every command, grouped by topic. Those marked (format) require \use{document} (or the named package); the rest are engine primitives available in any document. The engine variables they read are in Parameters and Variables, and the \picture drawing commands are in the Drawing Reference.

Document structure (format)

List labels change with depth and each is a macro of its own, so redefining one changes that level throughout: \labelenumi…\labelenumiv are 1., (a), i., A., and \labelitemi…\labelitemiv are •, –, ∗, ·. Each enumerate level counts on its own counter (enumi…enumiv), so a nested list never disturbs the one around it. \marginparwidth, \marginparsep and \marginparstyle are the margin note’s measure, gap and setting; a two-sided document puts its notes in the outer margin.

Citations, bibliography and index (format)

Both resolve across passes, like every other cross-reference: an index or a citation of something the pass has not reached yet appears once the document has been set through.

In book the reference list and the index open as chapters rather than sections, and \bibname is “Bibliography” rather than “References”.

Cross-references and contents (format)

The document is typeset twice over a shared label table, so forward references resolve.

Text and markup

Fonts and font shape

\bold/\italic/\smallcaps/\slanted wrap an argument; the declarations switch the font for the rest of the enclosing group (so an environment can set its whole body in one shape) and revert at the closing brace or \end. Family roles select the roman/sans/typewriter member of the current super-family, keeping weight and slope.

Small caps come from a real cut when the family has one (Latin Modern, Alegreya SC); otherwise, if the current face carries the OpenType smcp feature (EB Garamond and most modern text romans), \smallcaps/\scshape synthesise true small capitals from that feature rather than falling back to ordinary lowercase.

\mono/\ttfamily and \sans/\sffamily fall back to a document-level typewriter or sans family when the current family has no such member (Garamond, Cinzel, Amiri …), so an inline \mono never fails. \ttdefault{name}/\sfdefault{name} name those fallback families (Latin Modern by default); the target may be a super-family with a typewriter/sans member or a standalone family whose plain cut is the typewriter (\ttdefault{jetbrains}).

Bundled text faces

Four faces are core — compiled into the artifact, so they are there whatever a host has installed:

• \font lmroman — Latin Modern, the default body face, with its sans and typewriter roles and its small-caps and slanted cuts.
• \font lmmath — Latin Modern Math, the default math font.
• \font newcm — New Computer Modern, also the glyph-fallback face (see below).
• \font jetbrains — JetBrains Mono, the face \code sets a listing in, in regular and bold.

Every other bundled face is catalogue: it comes from a font tree on disk, and a host asks for the set with loadBundledCatalogue() (the command-line tool does this for you). Among the Latin text faces there:

• \font cinzel — an all-capitals inscriptional titling serif in the Trajan tradition, for titles and chapter openings, in six weights (regular, medium, semibold, bold, extrabold, black).
• \font ebgaramond — a Garamond revival for running text, with italic, the medium/semibold/ extrabold weights and their italics, a real bold, and true small caps through the smcp feature.
• \font alegreya, \font gentium, \font gentiumbook, \font noto, \font pt, and the rest of JetBrains Mono’s weight range.
• \font chess — Noto Sans Symbols 2, named for what the chess package stamps its pieces from. No text face covers the Miscellaneous Symbols chess block (U+2654–265F).

Naming a catalogue face on an installation that has no font tree is an error that says so, naming the file it went looking for. Any face texish does not bundle is brought in with \loadfont{name}{path}.

Glyph fallback (Cyrillic, Greek)

A codepoint the current face has no glyph for is set from New Computer Modern (\font newcm) rather than drawn as a missing-glyph box, so Cyrillic and Greek work in ordinary text with no setup — Привет, αβγ — and, because New Computer Modern is Computer Modern, the substituted glyphs sit invisibly beside Latin Modern.

The substitution matches the weight and slope of the text around it: Cyrillic inside a \bold{…} heading is set from the fallback’s bold cut, so the weight does not break mid-phrase. The family role is the one thing not carried over — the fallback stands in for a face’s coverage, not its family, so Cyrillic inside \mono is set in the fallback’s roman rather than sent to the typewriter family, which is no likelier to have the glyph.

Chinese, Japanese and Korean

Chinese and Japanese text has no spaces between characters, so the line breaker inserts its own break opportunities between adjacent characters and applies kinsoku — a closing mark never starts a line and an opening mark never ends one — then justifies the line by stretching the inter-character space. This happens automatically for any run of Chinese or Japanese text; the line breaker is otherwise unchanged.

Noto Serif CJK is bundled with a face for each region, since Han (kanji/hanja) has region-specific glyph forms and Korean adds the Hangul syllables the Chinese faces do not carry:

• \font cjksc — Simplified Chinese (also the default noto-adjacent face for Han)
• \font cjktc — Traditional Chinese
• \font cjkjp (alias \font japanese) — Japanese, with the Japanese kanji forms and the kana
• \font cjkkr (alias \font korean) — Korean Hangul (and Hanja)

Each has a regular and a bold cut (\font cjkjp 12 bold). Korean breaks differently: it is written with interword spaces, so its lines break at those spaces the way Latin does, rather than between syllables. A break inside a Korean word is offered only as a last resort, at a heavy penalty, so a run with no space in it still wraps instead of overflowing. Any other CJK font can be brought in with \loadfont{name}{path}.

Devanagari (Hindi)

Devanagari text is shaped a syllable at a time: consonants fuse into conjuncts and half-forms, the short-i sign and a word-initial reph are reordered, a nukta composes with its consonant, and the vowel signs are positioned by the font — all automatically from text typed in Unicode order. Noto Serif Devanagari is bundled: \font devanagari 12 regular (or the alias \font hindi), with a bold cut (\font devanagari 12 bold). See Devanagari (Hindi) for the full treatment.

Bengali–Assamese

Bengali text is shaped a syllable at a time: consonants fuse into conjuncts, the pre-base i/e/ai signs are reordered, the two-part o and au signs are split into a front and a trailing part, a word-initial reph and a post-base ya-phalaa are formed, a nukta composes with its consonant, and the vowel signs are positioned by the font — all automatically from text typed in Unicode order. Noto Serif Bengali is bundled: \font bengali 12 regular (or the alias \font assamese), with a bold cut (\font bengali 12 bold). See Bengali–Assamese for the full treatment.

Gujarati

Gujarati is Devanagari’s closest relative here, written without the shirorekha, and is shaped the same way: consonants fuse into conjuncts and half-forms, the pre-base i sign is reordered ahead of its syllable, and a syllable-initial ra with a virama rises as a reph above the base — closing the cluster after any post-base vowel sign, as Devanagari’s does rather than as Bengali’s does. Every vowel sign is a single codepoint, so nothing is split. All of it happens automatically from text typed in Unicode order. Noto Serif Gujarati is bundled: \font gujarati 12 regular, with a bold cut (\font gujarati 12 bold). See Gujarati for the full treatment.

Gurmukhi (Punjabi)

Gurmukhi text is shaped a syllable at a time: a consonant joined by the virama takes a subjoined pairin form beneath the base, the pre-base sihari (i-sign) is reordered, and the addak, the nasal tippi and bindi, and the vowel signs are positioned by the font — all automatically from text typed in Unicode order. Unlike Devanagari and Bengali, Gurmukhi has no reph. Noto Serif Gurmukhi is bundled: \font gurmukhi 12 regular (or the alias \font punjabi), with a bold cut (\font gurmukhi 12 bold). See Gurmukhi (Punjabi) for the full treatment.

Kannada

Kannada builds downward like Telugu: a consonant joined by the virama is drawn as the ottakshara beneath the base, so the base of a conjunct is its first consonant rather than its last, and a consonant and its vowel sign commonly fuse into a single drawn glyph. A vowel sign belongs to the base and is moved back across the subscripts to reach it. Where it differs from Telugu is that it forms a reph — a syllable-opening ra is lifted out as the arkavattu and set after the syllable, taking its own room on the line rather than floating above it as Devanagari’s does — and that five of its vowel signs are written as combinations of others, one of them nesting two deep (ೋ is ೊ plus a length mark, and ೊ is an e sign plus a uu sign). All of it happens automatically from text typed in Unicode order. Noto Serif Kannada is bundled: \font kannada 12 regular, with a bold cut (\font kannada 12 bold). See Kannada for the full treatment.

Telugu

Telugu builds downward: a consonant joined by the virama is drawn as a subscript beneath the base, so the base of a conjunct is its first consonant rather than its last, and a consonant and its vowel sign commonly fuse into a single drawn glyph. A vowel sign belongs to the base, so it is moved back across the subscripts to reach it — ప్రేమ joins its vowel to the pa, not to the subjoined ra. The ai sign is split into the two parts the font draws, and a word-initial ra with a virama forms no reph. All of it happens automatically from text typed in Unicode order. Noto Serif Telugu is bundled: \font telugu 12 regular, with a bold cut (\font telugu 12 bold). See Telugu for the full treatment.

Tamil

Tamil keeps its virama on the page as the pulli, a dot above the consonant it silences, rather than folding that consonant into a half-form or subjoining it beneath the base. A silenced consonant is therefore a letter in its own right, and a pre-base vowel sign moves before the consonant it belongs to rather than to the front of the syllable: க்கே sets ka, pulli, the ee sign, ka. The two-part o, oo and au signs are split into the parts the font draws, the u signs fuse with their consonant, the short-i and long-i signs take width-matched forms, and the two surviving conjuncts (க்ஷ and ஸ்ரீ) are drawn as single ligatures — a pre-base sign does reach the front of those, since the ligature has swallowed the pulli. A word-initial ra with a virama forms no reph. All of it happens automatically from text typed in Unicode order. Noto Serif Tamil is bundled: \font tamil 12 regular, with a bold cut (\font tamil 12 bold). See Tamil for the full treatment.

Ethiopic (Amharic, Tigrinya, Ge’ez)

Ethiopic needs no shaping: it is a syllabary, so the vowel is written into the letterform rather than hung on it as a sign, and one codepoint is one glyph. Nothing reorders, nothing joins, there is no bidirectional work — the text takes the plain path through the engine and breaks at its spaces like a roman paragraph. Noto Serif Ethiopic is bundled: \font ethiopic 12 regular (or the aliases \font amharic and \font tigrinya), with a bold cut (\font ethiopic 12 bold). It covers the Ethiopic block along with the Supplement and both Extended blocks. Ethiopic’s own punctuation (፡ ። ፣ ፤) and numerals (፩ ፪ ፫) are typed literally. See Ethiopic for the full treatment.

Thai

Thai is written without spaces between words and uses them to separate phrases instead, so a run of it would reach the line breaker as one box and overflow the measure. The breaker offers somewhere to break between orthographic clusters, and never parts a vowel or tone mark from its consonant, nor strands a pre-posed vowel from the consonant that follows it. Charm is bundled: \font thai 12 regular (or \font charm), with a bold cut.

Vowels and tone marks are placed on their consonant by the font’s anchors, so the stacked combinations Thai builds set correctly.

One limitation to know. Thai lines properly break at word boundaries, and finding those needs a dictionary, which texish does not carry — so a cluster break may land inside a word. Because of that it is offered only as a last resort, at a heavy penalty: text with normal phrase spacing breaks at those spaces and never sees one.

Right-to-left scripts

\rtl and \ltr set the paragraph base direction. Faces are bundled for both scripts, each in a regular and a bold cut: \font hebrew (Noto Serif Hebrew) and \font arabic (Noto Naskh Arabic), with the traditional book hands \font amiri (a Naskh alternative to Noto for Arabic) and \font ezra (Ezra SIL, the Biblia Hebraica Stuttgartensia face, with vowel points and cantillation marks) alongside them. Hebrew niqqud, Arabic cursive joining, the lam-alef and Allah ligatures, and Arabic harakat are all applied automatically from the text in logical order — see Right-to-left text for the full treatment.

Text symbols

Mathematics

Boxes, spacing, and pages

The framing primitives read fboxsep / fboxrule; box and page behaviour is tuned through the parameters (hsize, parindent, baselineskip, tolerance, the page-break penalties, and so on).

Rules, frames, and transforms

Tables

Verbatim and code

Both read their text raw from the input, so — like LaTeX’s \verb — they cannot be produced by a macro. \code colours by the theme in codetheme; the code environment takes its language from codelang.

Language

These set the document’s language, which decides both the hyphenation patterns the line breaker uses and the typography the language sets its punctuation by.

texish bundles 78 languages. Five — en-us, es, fr, it, pt — are compiled into the binary and the rest are files in the installation’s hyphenation/ folder; \usehyphenation reaches both alike, so a document names a language without knowing which tier it is in. The full list, and what a pattern file carries besides its patterns, is in the Hyphenation guide.

Declaring French — \usehyphenation{fr}, or any regional tag built on it — also switches on French spacing of high punctuation. French sets a space before the colon, semicolon, exclamation and question marks, and inside its guillemets: a full space before the colon, a narrower one before the rest. That space neither stretches when the line is justified nor offers the line breaker a place to break, so the mark cannot drift from its word or be carried alone to the head of the next line. Type the space or leave it out as you prefer — « Oui ! » and «Oui!» set alike — and the comma and full stop, which French sets tight as English does, are left alone.

Hooks

Page geometry

\geometry sets the page frame the way LaTeX’s geometry package does, but with texish name:value options instead of a key=value list. It resolves the sheet, the text size, and the margins, then sets paperwidth/paperheight, hsize/vsize and hoffset/voffset globally — so a \geometry in the preamble holds for the whole document, and a later call re-frames the pages that follow it (as LaTeX’s \newgeometry does). The far margin is always the remainder, so the frame closes by construction.

Example: \geometry paper:a4 margin:2cm or \geometry left:2in right:1in top:1.5in bottom:1in.

Two-sided, the frame given is the recto, and every verso reflects it about the page’s vertical centre — the recto’s outer margin becomes the verso’s inner one, carrying the running head and foot with the body. So \geometry paper:a5 inner:22mm outer:14mm leaves 22mm against the spine on every page of the book, not on every odd one. The reflection is of the resolved frame, so it holds however the margins were specified, and it follows pageno, the folio a page prints, rather than a count of sheets. The document format’s \ifrecto{…}{…} and \cleardoublepage build on the same parity: the first chooses a branch by side, the second opens the next material on a recto, inserting a blank leaf when it would otherwise fall on a verso.

Page arrangement

\arrange chooses how finished logical pages are placed onto physical sheets — the output routine. The default ships one page per sheet; the booklet arrangements and nup group several. It must appear in the preamble, before any content, because the arrangement fixes the physical sheet size when the output surface is created. Imposition happens in box space, above the rendering backend, so it works on every output target.

The two-up-booklet arrangement sets the logical page with \geometry and lets the arrangement size the sheet: for a pocket A6 booklet folded from A5 paper, \geometry paper:a6 margin:10mm then \arrange two-up-booklet gives A5-landscape sheets carrying two A6 pages each. Print double-sided, fold each sheet once down the middle, nest, and staple, and the pages read in order. A run is padded with blank pages to a whole number of sheets. The name describes the imposition, not the paper, so the same arrangement serves any page size — quarter-letter pages two-up on half-letter sheets, say. Both booklet arrangements take duplexshift:<len> to cancel a duplexer’s front-to-back drift (see below).

The four-up-booklet arrangement prints the same booklet on the next paper size up for cutting: it stacks the two-up layout two folded sheets high, so A6 pages fall four to an A4 sheet. Print double-sided, cut the sheet in half across the middle into two half-height sheets, then fold and nest those exactly as the two-up booklet — no page prints upside-down and nothing is slit. The back is laid out for long-edge duplex; if a fold-test dummy comes out mis-collated, switch the printer to long-edge binding. Padding blanks fall just before the last page, so the front and back covers always land on the outermost sheet. If a duplexer lands the front a millimetre or two off the back, duplexshift:<len> pulls every front side that far left to bring the two into register.

Images and graphics

The drawing commands available inside \picture (paths, shapes, strokes, fills, transforms, text, arrows) are listed in the drawing reference.

Two-dimensional barcodes (\use{qrcode}, \use{datamatrix})

The data is read verbatim, so a URL’s // is not a comment and %, ~ and # reach the encoder as themselves. Options ride one optional [key:value …] bracket, and each has a document variable behind it that sets the default for every later call:

The encoder is written in the document language rather than built into the engine — the mode selection, the Reed-Solomon check codewords and the mask search are all \calc, \for and \put over sequences.

Data Matrix

A Data Matrix packs the same payload into rather less area than a QR code, which is why it is the symbology of shipping labels and of parts marked directly. It has no error-correction setting — ECC200 fixes it by symbol size — and so takes four options rather than five:

Square symbols from 10×10 to 48×48, carrying up to 174 codewords — a few hundred characters, or twice that in digits, since a pair of digits costs one codeword. The rectangular symbols and the two largest square ones are not built; a payload too long is reported rather than silently truncated. Text is encoded as UTF-8, so a symbol carrying only ASCII is unambiguous, and no ECI is emitted.

Both packages load barcode, which holds what they share: the payload as bytes, and Reed-Solomon over GF(256). Nothing calls \use{barcode} directly.

Floats and text wrapping (\use{float})

The package upgrades \figure/\table to real edge floats and adds in-flow figures the text flows around, all sharing one caption sequence (\caption, numbered on independent figure and table counters, filing into the lists of figures and tables).

Captions file into the lists of figures and tables that document‘s \listoffigs / \listoftabs print, resolved on the second typesetting pass.

Chemistry (\use{chem})

Chess (\use{chess})

The package keeps a position and plays algebraic notation into it, so a diagram is what the moves before it reached. See the chess guide.

Configured with \set after \use{chess}: chesssquare, chesscoords, chessflip, chesshighlight, chesslight, chessdark, chessborder, chesshighlightink, chesspieceink, chesspiecescale, chessfigurines, chessmovesize.

Plotting (\use{plot})

Both bracket arguments are optional: with no colour (or []) a series takes the next palette colour, and a label adds a legend entry.

Geographic maps (\use{map})

Draws maps over the \picture layer in the Web Mercator projection the OpenStreetMap tile ecosystem uses. You declare the geographic window in longitude/latitude with \mapbounds, then draw inside \map{…}, writing real coordinates everywhere — \place{35.23}{31.78}{Jerusalem} lands at the true point. Because Mercator is separable, the projection is two one-argument macros (\mapx, \mapy), parallel to plot‘s \px/\py. Base coastlines/rivers/land are far too dense to project a point at a time, so they are projected offline into a \basemap macro of pre-projected paths and \included beside the document; overlays and furniture are projected at run time and register exactly. While the package is loaded its \map{…} shadows the keyed-map \map.

The base file sets the size configuration and calls \mapbounds itself, so the offline linework and the run-time overlay cannot drift out of register.

Macros and programming

Working with sequences and strings

A string is the sequence of its characters, so these take either and give back the kind they were given. Characters means code points, so an emoji or a math alphanumeric is one item. A number counts as the characters it displays as, since a run of digits becomes a number as soon as it is stored — \size{12345} is 5 whether it is written out or read from a variable. Positions count from 1, and \indexof answers 0 for “not found” — which is falsy, so one call both tests and locates.

Three take a body evaluated once per item, binding a variable of your choosing exactly as \for does — the difference being that they collect the body’s value rather than typesetting its output, which is what lets a loop compute a result instead of accumulating through a \global variable:

\set squares {\transform\n{\range{1}{4}}{\calc{\n * \n}}}      % 1, 4, 9, 16
\set big     {\filter\n{\squares}{\> {\n} {5}}}                  % 9, 16
\set byname  {\sortby\w{\words{Zebra apple Fig}}{\downcase{\w}}} % apple, Fig, Zebra

The body may be several statements, in which case its value is the last one that produced a value. That matters because \calc reads its argument as an expression string: a variable works there (\calc{\n * 2}), but a primitive call does not — \calc{\nth{\p}{1} * 2} reads \nth{\p}{1} as an identifier. Bind what you need first:

\set sxy {\total{\transform\p{\chunk{\data}{2}}%
  {\set x {\nth{\p}{1}}\set y {\nth{\p}{2}}\calc{x * y}}}}

| \message{…} | write expanded text to standard error (a diagnostic; no page output) | | \oklch{L}{C}{h} \oklchof{color} | build / read a colour in the Oklch space (lightness, chroma, hue) — derive shades by varying L | | \newcounter \setcounter \addtocounter \stepcounter \value \counterwithin | named counters; \counterwithin resets a child when its parent steps | | \arabic/\roman/\Roman/\alph/\Alph/\fnsymbol | format a number as digits / roman / letters / footnote symbols | | \use{name} \include{path} | load a format / include raw input | | \usfm{path} | typeset a Scripture file in USFM format through the \usfm… macros (\use{usfm}) |

Scripture (\use{usfm})

\usfm{path} reads a book in USFM (the Unified Standard Format Markers that Bible translations are exchanged in) and typesets it, resolving the path beside the document as \include does. Every visible decision is a redefinable macro, so a document sets the appearance with ordinary commands before the call — \def usfmwj t {\t} to drop the red-letter words of Jesus, \set usfmqbase {24} for a deeper poetry indent, and so on. The defaults give a print-Bible page: a large chapter figure, superscript verse numbers, bold section headings with italic reference lines, justified prose and ragged poetry, real footnotes, and the words of Jesus in red.

The reader handles the full USFM marker set — including USFM 3.0 word attributes and plus-nested character markers — and a book’s front-matter introduction (its own titles, outline, prose and poetry, set a size quieter than the Scripture). Suppress the introduction with \set usfmintro {0} before the call — a pocket portion that wants only the text needs no change to the USFM file.

Railroad diagrams (\use{railroad})

The grammar is read verbatim. Rules are name ::= expression; an expression supports \| (alternation), juxtaposition (concatenation), ?/*/+ (optional / zero-or-more / one-or-more), (…) grouping, "…"/'…' terminals (rounded boxes), […] character classes (pointed hexagons), and bare names as nonterminals (square boxes). Labels are set in JetBrains Mono with terminals in bold. Common shapes are drawn idiomatically: a separated list A (sep A)* becomes A with sep on a return loop, and an optional choice (A|B|C)? folds the skip into the choice. See the guide for customising colours and sizes.

Node-and-edge diagrams (\use{diagram})

Declared inside a \picture. A node is a named, measured box of a shape; an edge is an arrow between two named nodes that meets each node’s true boundary.

A placement is at X Y, at (X,Y), or below/above/left/right REF [gap] (relative to another node). The look is set with \set on the dg… variables (dgfill, dglinecolor, dgfont, dggap, dgarrow, …).

The flowchart package (\use{flowchart}) adds role names — \start \stop (terminal), \process (box), \decision (diamond), \io (parallelogram), \subroutine — and flow edges \flow / \branch / \rejoin. The automaton package (\use{automaton}) adds \state (circle), \accepting (double circle), \initial, \trans, \arc and \loopabove. The er package (\use{er}) draws Chen-notation entity-relationship diagrams — \entity, \weakentity, \relationship, \weakrelationship, \attribute, \keyattribute, \multivalued, \derived, and \connect / \connecttotal with cardinalities. All three are thin layers over diagram; see the guide.

Units

pt (the base unit, 1/72 in), in, cm, mm, em, ex.