LaTeX as written: a specification

A reader MUST read the source with TeX's standard category codes:

@ is a letter between \makeatletter and \makeatother and other characters elsewhere. A reader MUST NOT follow other category code changes (\catcode, \ExplSyntaxOn, active characters); it MAY report them.

A control word is \ followed by one or more letters; it ends at the first character that is not a letter. A control symbol is \ followed by any one other character, a line ending counting as a character (it reads as a control space).

Blanks after a control word. The blanks after a control word are not text: TeX skips them while reading the name. A single line ending among them is skipped too; a blank line is a paragraph break and is not.

\LaTeX is   fine   ⇒ LaTeXis fine
\LaTeX{} is fine   ⇒ LaTeX is fine
\LaTeX\ is fine    ⇒ LaTeX is fine

Blanks after a control symbol are text: \% followed by two blanks and x typesets % x, with one space (runs of blanks are one space, §5.1).

A line ending is a space in text. One or more blank lines (lines of only blanks) end a paragraph, as \par does. Blanks at the start of a line are skipped. A comment removes the rest of its line and its line ending, so a% at the end of a line joins it to the next with no space.

Runs of blanks and a single line ending typeset one interword space. Spaces at the start of a paragraph are dropped. ~ is an interword space that does not break. The control space, a backslash followed by a blank, is an interword space that is not skipped after a control word.

\ignorespaces expands. \ignorespaces skips the blanks after it and expands macros while it skips, so a macro that expands to a space (\space) is skipped too. xcolor's \color{c} ends with it:

A{\color{blue} \space x}  ⇒ Ax

In the text fonts of LaTeX's standard encodings (OT1, T1) the characters below are ligatures, made by the font:

A ligature forms only between characters in the same font with nothing between them: -{}- and -\relax- typeset two hyphens. Whether two quotes join into one ligature depends on what boxes are between them. The typewriter fonts have no ligatures of dashes and quotes in T1.

The accent commands (\' \` \^ \" \~ \= \. \u \v \H \c \k \r \b \d \t) take one argument, a group or a single token: \'e \'{e} \' e all typeset é. \i and \j are the dotless letters for accenting. The named letters (\ss \ae \AE \oe \OE \o \O \aa \AA \l \L) and the text symbols (\textohm, \texteuro, \textdegree, \textsection, …) typeset one character. With \textohm that character is U+2126 OHM SIGN; it is not changed by a case change.

\romannumeral n typesets n in lower-case Roman numerals (\romannumeral 4 ⇒ iv; nothing for 0), so \MakeUppercase{\romannumeral 4} ⇒ IV.

A reader SHOULD NOT nest TeX's \lowercase around LaTeX's case change of an accented letter: \lowercase{\MakeLowercase{é}} does not end in pdfLaTeX.

The text commands (\textbf, \textit, \emph, \texttt, \textsc, \textsf, \textrm, \textsl, \textup, \textmd, \textnormal, \underline, \textsuperscript, \textsubscript) take one argument and style it. The declarations (\bfseries \itshape \em \ttfamily \scshape \sffamily \normalfont, the old \bf \it \tt \sc \sf \rm, and the sizes \tiny … \Huge, \normalsize) style the rest of their group: to the } that closes it, to the end of the environment, or, outside both, to the end of the paragraph. \emph inside italic text is upright.

\textcolor{c}{x} colors x; \color{c} colors the rest of its group and skips the blanks after it (§5.1). \textcolor[model]{spec}{x} and \color[model]{spec} give the color by a model (rgb, RGB, HTML, gray, cmyk).

{…} is a group: declarations inside it end at its }. A group MAY span paragraph breaks. An environment's body is a group.

A command takes its arguments by a signature, a string of letters read left to right:

Before each argument the reader skips blanks and at most one line ending. A mandatory argument that is not a group is one token: a control word with the blanks after it, a control symbol, or one character (\frac12 ⇒ ½: two arguments, 1 and 2). An optional argument that is not there leaves the [ or the text as text.

The signatures of the kernel's and the common packages' commands are those of their documentation; Part II's LaTeX chapter lists the ones a reader most needs. A command whose signature is not known takes no arguments: \foo{a}{b} is the command \foo and two groups, which keeps what follows it readable.

\verb|…| (any delimiter but a blank, a letter or *; \verb* shows spaces) and \lstinline take their text as written, to the delimiter, on one line. \url{…} and the address of \href{…}{text} are verbatim in a group, so %, #, _ and ~ in them are not special. The environments verbatim, verbatim*, Verbatim, BVerbatim, lstlisting, minted, comment, filecontents end at the first literal \end{name}; nothing before it is a command, a comment or a group.

A document is \documentclass[options]{class}, a preamble of definitions and \usepackage lines, then \begin{document} … \end{document}, the body. What follows \end{document} is ignored. A file without \begin{document} is a part of a document (§7.2).

A file belongs to the document that reads it. A reader MUST find it in this order:

1. a % !TEX root = file line among the first lines;
2. \documentclass[main.tex]{subfiles} (the subfiles package);
3. the file itself, when it has \documentclass;
4. a document with \documentclass in the file's folder or a folder above it, within the project, that includes the file (directly or through other files);
5. any document of the project that includes it.

A local .sty or .cls file in the document's folder is part of it: its definitions (§8) are the document's.

A file need not be UTF-8: \usepackage[latin1]{inputenc} and [applemac] files are common in older papers. A reader MUST read such a file's commands and definitions all the same (its letters outside ASCII decoded in its encoding, or replaced); a file it cannot decode MUST NOT lose the project its definitions.

Expansion is at the use. A body is a template; it is expanded where the command is used, with the definitions in force there. A definition MAY use a command defined after it (\newcommand{\vu}{\vc{u}} before \vc is fine). A label, citation or section inside a body counts only where the command is used.

Arguments of the document's own commands. A reader that does not expand macros MUST NOT give the document's commands signatures for parsing, but a renderer SHOULD use their definitions: a command whose body, its arguments put in, is text typesets that text (\newcommand{\vs}[2]{#1 versus #2}, \vs{A}{B} ⇒ A versus B); a command whose body is its first argument alone or in one style or color ({#1}, \textbf{#1}, {\color{black}{#1}}) typesets its argument. The same holds for bodies of other kinds, read as TeX reads them in running text:

• a reference (\newcommand{\eq}{\eqref}, \newcommand{\rife}[1]{(\ref{#1})}) prints what the reference prints;
• space between lines (\vspace{2mm}, \vskip.075in) prints nothing in the line;
• a formula (\ensuremath{…}, text with $…$ in it, \(…\)) is a formula; a displayed formula around the arguments (\begin{align}#1\end{align}, \[#1\]) is a displayed formula;
• of \ifmmode A\else B\fi only B counts, the text-mode branch;
• a box around the text (\scalebox{0.7}[#1]{…}, \resizebox, \raisebox) is its text;
• a body that draws pictures or reads files (\includegraphics, \input inside a figure or minipage) shows those pictures and names those files, with its caption.

\xspace (the xspace package) at the end of a body adds a space unless punctuation or a closing brace follows.

What a reader MUST NOT redefine. A document or package may redefine TeX's own definition commands (\def, \newcommand, \begin, \left, \relax, …) internally. A reader that collects definitions MUST NOT take such a redefinition: it would change every definition after it.

Papers define macros for the opening and closing of a displayed equation: \def\be{\begin{equation}}, \def\ee{\end{equation}}. A reader MUST treat a macro whose body opens (closes) a display math environment as that opening (closing), so the formula between is math. The pairs \be \ee, \beq \eeq, \beqn \eeqn, \bea \eea, \beqa \eeqa, \beqna \eeqna, \bes \ees, \ben \een and \begeq \endeq are so common that a reader SHOULD take them as such when the file does not define them (a file of a project whose root does). \begin{equation} … \ee is the same environment.

Such macros are often defined in another file of the project: a package of the document's own (\def \ba {\begin{eqnarray}} in macros.sty) or a file of definitions the root reads. A reader MUST parse each file of a project with the equation macros and formula environments that the project's files define (the root document's folder and the folders in it, .tex, .sty and .cls files), the file's own definitions after them.

In book and report, \theequation, \thefigure and \thetable leave the chapter out while it is 0 (Figure 1 before the first chapter).

A starred sectioning command is not numbered and does not step its counter. Each level resets the levels below it; resets cascade (a new chapter resets section, which resets subsection, and so on). \appendix resets section and subsection (article) or chapter and section (chaptered) and switches to letters. \frontmatter and \backmatter stop numbering chapters; \mainmatter resumes it.

\setcounter{c}{n} and \addtocounter{c}{n} set any counter. \numberwithin{c}{w} (amsmath) and \counterwithin{c}{w} reset c with w and print it as w's number, a dot, its own; \counterwithout undoes it; \newcounter{c}[w] resets c with w but prints it alone. \refstepcounter{c} steps c and makes it what \label points at. \renewcommand{\thec}{…} changes how c prints, through \arabic, \roman, \Roman, \alph, \Alph and other \the… commands.

enumerate numbers its items 1., 2., …; nested, (a), i., A. (the standard classes' four levels); a \label on an item points at 2, 2a, 2(b)i, 2(b)iA. \item[x] shows x and numbers nothing. itemize and description number nothing. enumitem's label= option changes the printed label and what \ref prints.

A \caption in figure (figure*, wrapfigure) steps figure; in table (table*, wraptable, longtable) it steps table. In subfigure and subtable (subcaption) and for \subfloat[caption]{…} (subfig) the caption is lettered a, b, … within its float, and \ref prints the float's number and the letter (1a). \captionof{figure}{…} steps figure outside a float. A caption elsewhere is not numbered.

\newtheorem{env}{Title} declares an environment with its own counter; \newtheorem{env}[other]{Title} shares other's; \newtheorem{env}{Title}[within] numbers within within (1.1); \newtheorem* declares an unnumbered one. thmtools' \declaretheorem does the same with keys (name, numberwithin, sibling, numbered=no). The environment's optional argument is its note. proof (amsthm) is unnumbered and ends with ∎.

Journals' classes declare theorems themselves (llncs, svjour3, acmart, SIAM's), and papers use theorems declared in files a reader may not have. A reader SHOULD take an undeclared environment of a usual name as that theorem on its own counter: theorem, lemma, corollary, proposition, definition, remark, example, conjecture, claim, assumption and the like, their usual short forms (thm, lem, lma, cor, prop, defn, rmk, expl, assump, …), and those after my, custom or new (myassump).

\nonumber and \notag take a line's number away; \tag{x} replaces it.

\label{k} takes the number of the last thing numbered in its scope by \refstepcounter (a section, an equation line, a caption, a theorem, an enumerated item, a footnote). An environment and a footnote's text are groups: at their end what \label points at is restored. A label with nothing numbered before it points at nothing.

When two labels have the same key, pdfLaTeX writes both to the .aux file and the last one written is the one \ref reads on the next run; a reader SHOULD report the clash.

\cite[post]{k1,k2} and its variants (natbib's \citet \citep \citeauthor \citeyear \citealt \citealp with optional pre- and post-notes [pre][post]; biblatex's \parencite \textcite \autocite \footcite and their capitalized forms) cite entries of the .bib files named by \bibliography{a,b} or \addbibresource{a.bib}, or of a thebibliography environment's \bibitem[label]{key}. The label printed follows \bibliographystyle (numbers or author–year).

A formula ends at its closing delimiter; one not closed by the end of its paragraph is an error. Inside a formula, \text{…}, \mbox{…}, \textrm{…} and the other text commands are text again, and $ inside them opens a formula. \ensuremath{x} is math in text and in math.

A renderer that draws formulas MUST accept the commands of LaTeX's math mode and of amsmath and amssymb, and SHOULD accept, as their usual definitions: \mathds \mathbbm (as \mathbb), \bm \boldsymbol, \nicefrac \sfrac, \tfrac \dfrac \cfrac, \xrightarrow \xleftarrow, \operatorname, \DeclareMathOperator's operators, \text, \intertext, \tag, \substack, the cases dcases matrix families, \overset \underset \stackrel, \overbrace \underbrace, the physics package's delimiters and Dirac notation (\abs \norm \qty \ket \bra), and the letter families papers define in loops (\cA … \cZ as \mathcal, \bA … as \mathbb, \sA … as \mathscr, \fA … as \mathfrak) when the document does not define them itself.

The document's own macros (§8.1) apply in formulas: a renderer MUST use the definitions that read, in their order, and MUST NOT let one definition it cannot read stop the formulas after it. A definition is read when it, a formula after it and its use draw nothing but the formula: a definition that leaves text behind (an optional argument's default the renderer does not take, \newcommand{\x}[2][]{#2}, read as two arguments and a stray ]#2) MUST be taken as \def\x#1{#1}, the default put in the first argument's place.

Commutative diagrams (tikz-cd, xymatrix), \buildrel, plain TeX's \matrix and \over, the size environments and \textcolor with a model are written in formulas often enough that a renderer SHOULD read them or have TeX typeset the formula.

Take the corpus (tools/arxiv-sample.py fetches it; the list of papers is fixed by the year and the share per category) and measure, for each field, the bytes of the body the reader leaves as source. kalem latex-coverage DIR does it for Kalem and reports the constructs that leave the most. A reader that follows this appendix leaves less than 0.1% of the body in each field; Kalem's target is the same (Part IV, decision D30).

tools/latex-typeset-fuzz.py writes random lines of text (words, punctuation, dashes, accents, symbols, spaces, fonts, case changes, colors, boxes, verbatim) and has pdfLaTeX put each in a box; it writes the reader's text of the same lines in a box too and compares the glyphs. --each runs every construct alone. Every rule of §4 and §5 is checked so.

tools/latex-numbering-fuzz.py writes random documents of sections, equations, floats, theorems, lists, footnotes, counters and labels, compiles them, and compares the .aux file's numbers with the reader's. Every rule of §9 is checked so.

A reader MUST give, for any input, a structure whose leaves are the whole source in order. An incremental reader MUST give, after an edit, the structure a full read gives (Kalem's fuzz target latex_reparse checks it).