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)

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.

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.

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.

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.

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.

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.

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.

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})

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

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.