LaTeX

kalem diff-pandoc FILE... [--summary] [--format json] runs pandoc -f latex -t json on each file (in the file's folder) and counts the same things on Kalem's side, over every file the project includes:

A file's body is its document environment, or the whole file for an included file without one. Without --summary it prints each disagreement as FILE: CATEGORY: kalem A, pandoc B; with --summary, how many files agree in each category; --format json gives every category of every file with an agree flag.

The lexer uses TeX's standard category codes, fixed:

Two token kinds come from the parser rather than the lexer: STAR (the star of \section* and of a starred environment's argument list) and VERBATIM (text taken as it is), and ENV_NAME is the name inside \begin{…} and \end{…}. An environment name is a run of ASCII letters, digits and *, @, :, _, - between braces, with spaces or tabs allowed between \begin and the brace.

The document is a sequence of paragraphs separated by paragraph breaks; so is the body of every environment that is not verbatim. A paragraph is a sequence of elements: tokens, groups, commands, environments and formulas. A group {…} closed before the end of its container may contain paragraph breaks.

A command takes the arguments its signature lists, read left to right:

A command not in the signature table takes no arguments. What follows it is parsed as ordinary text and groups, which keeps it visible: an unknown \foo{a}{b} is the command \foo followed by two groups.

The commands whose arguments are text even inside math (\text, \textrm, \textbf, \textit, \textsf, \texttt, \textnormal, \mbox, \hbox, \intertext, \emph, \textup) parse their arguments in text mode, so $ inside them starts a formula.

The complete table (crates/latex-syntax/src/signatures.rs):

The *oom signature is what makes a command a citation command everywhere in Kalem: the model, the view, completion and the insert command all ask for it.

The arguments after \begin{name}:

Other environments take no arguments at \begin; a [note] after the \begin of a theorem-like environment the table does not know is read by the model all the same (see Theorems).

\begin{name} opens an environment that ends at the matching \end{name}. Pairing is done in one pass before parsing, as TeX pairs them: each \end{x} closes the nearest open x, and environments opened inside it and not closed stay unclosed. The environment is an ENVIRONMENT node holding a BEGIN node (the command, the name and the arguments of its signature), a BODY and an END.

Verbatim environments keep their body as one VERBATIM token: the body ends at the first literal \end{name} in the text, so nothing inside it is a command, a comment or a group. Their arguments are read on the \begin line only, as they are written. The verbatim environments are verbatim, verbatim*, Verbatim, Verbatim*, BVerbatim, lstlisting, minted, comment, filecontents and filecontents*.

The body of a math environment is parsed in math mode. The math environments are, each with its starred form: equation, align, gather, multline, eqnarray, alignat, flalign, math, displaymath, split, aligned, gathered, alignedat, cases, dcases, matrix, pmatrix, bmatrix, Bmatrix, vmatrix, Vmatrix, smallmatrix, array. Every other environment's body is parsed in text mode.

Inside math, $ closes inline math and $$ closes display math; \( and \[ are not special. A formula not closed before the end of its paragraph ends there, with a diagnostic.

The parser reads LaTeX's conventions, not TeX's macro expansion. It does not follow:

• \catcode changes, \ExplSyntaxOn (where _ and : are letters), active characters and babel's shorthands. Only \makeatletter and \makeatother change the lexing.
• Macros: a \newcommand does not give its command a signature, so the arguments of the document's own macros parse as the groups after an unknown command. Bodies of definitions are ordinary tokens (#1 is a HASH token and the text 1).
• Verbatim environments defined by the document or a package beyond the list above (\lstnewenvironment, fancyvrb's \DefineVerbatimEnvironment): their bodies parse as LaTeX.
• The primitive form \input file without braces: the parser's m argument is the first character; the model reads the file's name up to a blank, as TeX does, so the project follows it.
• Conditionals: \iffalse … \fi parses normally; only the view dims it.

Unbalanced input is closed where a reader would close it, and each closing is reported with its range:

Parsing stays linear on unbalanced input because the pairing of braces and environments is computed once, before the tree is built. These messages are the diagnostics with code latex-syntax (see Diagnostics).

After an edit, Parse::reparse parses again only the paragraph around the edit, and only when that is certain to give the tree a full parse gives; otherwise it parses the whole text. The region is found by going down into the innermost closed, non-verbatim environment whose body holds the edit strictly inside (after the body's first non-blank token, which must not be [, so the arguments of \begin cannot change, and before its \end), then taking the children of that body from the paragraph break before the edit to the one after it. The full parse is taken when any of these holds:

• the edit reaches the start or the end of an environment's body, where no paragraph break separates it from \begin or \end;
• a diagnostic of the old parse overlaps the region, or a \makeatletter or \makeatother lies in it;
• the document has an environment left open and the region holds a sectioning command, before or after the edit;
• the region holds the \begin or \end of a verbatim environment, before or after the edit;
• inside an environment, without a paragraph break at its end, the region's last line holds %, \verb, \url, \href or \lstinline;
• the new region, parsed alone, has a diagnostic, an unclosed environment or a \makeatletter toggle, or does not begin and end with the paragraph breaks the old one had.

The property tests check that the result is always the full parse's tree. Measured (book/part-4/performance.org): a 1 MB paper parses in 32 ms and a keystroke reparses in 0.64 ms (median).

find_root decides the root of a file in this order; the first that applies wins:

1. A % !TEX root = FILE line among the first 20 lines (! optional, TEX root in any case), resolved from the file's folder, FILE.tex tried before FILE when the name has no .tex extension; it must be readable.
2. \documentclass[MAIN]{subfiles}: the subfile's main document, resolved the same way.
3. A file named NAME.latexmain in the file's folder or a folder above it: NAME in that folder.
4. The setting latex.root, a path relative to the project's folder (the folder with .git, .kalem or another project marker; the file's folder without one), usually in the workspace's settings; it must exist.
5. The file itself, when a line of it starts with \documentclass (not the subfiles class).
6. The first .tex file with a \documentclass, in the file's folder or a folder above (up to the project's folder), whose project includes the file.
7. The first .tex file of the project, by path, with a \documentclass whose project includes the file (a main document in a sibling folder: src/main.tex for chapters/one.tex).
8. The file itself.

% !TEX root = ../thesis.tex
\chapter{Methods}
\label{ch:methods}

The editors look for the root on a thread when a .tex file opens, and again when an edit within the first 4,096 bytes changes the % !TEX root line.

The base folder starts as the root's folder, as LaTeX runs there. Each included file is read in place: its events are numbered where the include stands. A file included by \subfile counts only inside its document environment, as the subfiles package arranges; an included file's \documentclass is ignored. \includeonly{a,b} marks the \include files it leaves out as excluded, but they are still read and numbered, because LaTeX keeps their numbers from their .aux files. A file already being read (a cycle) is not read again, and reading stops 32 files deep. \graphicspath{{a/}{b/}} adds folders in which pictures are looked for.

\documentclass{report}
\usepackage{import}
\includeonly{chapters/intro}
\begin{document}
\include{chapters/intro}
\include{chapters/results}
\import{appendices/}{data}
\end{document}

In the editors the model of a file of a project is the project's model seen from that file (Model::seen_from): the file becomes file 0 and the root takes its index, so everything in it is numbered as the whole document numbers it (a chapter file's first chapter is numbered after the chapters before it) and its references to labels in other files resolve. The file being edited comes from the editor, with its incremental parse; the other files come from the disk and are read again when their modification time changes. A root document that includes nothing needs no project and uses its own model.

In every class subsection is within section, subsubsection within subsection, paragraph within subsubsection and subparagraph within paragraph; in chaptered classes section is within chapter. \part resets nothing. Resets cascade, as LaTeX's \@stpelt steps each reset counter from -1: a new chapter resets section and, through it, subsection and a theorem numbered within section. In book and report, \theequation, \thefigure and \thetable leave the chapter out while it is 0 (Figure 1 before the first chapter, not 0.1).

A starred command is not numbered. \setcounter{secnumdepth}{n} and \addtocounter{secnumdepth}{n} change the depth. \frontmatter and \backmatter stop the numbering of chapters (a section there is still numbered, as 0.1 in a book's front matter); \mainmatter resumes it. \appendix resets section and subsection in an article, chapter and section otherwise, and switches the letters on. Each section's parent is the nearest section before it with a smaller level.

\setcounter{c}{n} and \addtocounter{c}{n} set any counter to an integer. \numberwithin{c}{w} (amsmath) and \counterwithin{c}{w} make c reset with w and print as w's number, a dot and its own; \counterwithout{c}{w} undoes it. \newcounter{c}[w] makes c reset with w but print alone. \stepcounter{c} steps it, and \refstepcounter{c} also makes it what a \label points at. \renewcommand{\thec}{…} changes how c prints: \arabic, \roman, \Roman, \alph and \Alph of a counter, other \the… and text are read, other commands print nothing (\renewcommand{\thesection}{\Roman{section}} gives II, and \thesubsection built on it II.a). A definition's body is not read where it is defined: \newcommand{\step}{\refstepcounter{s}} steps nothing until it is used, and the model does not expand macros.

\[…\] and displaymath are unnumbered equations: a \tag there numbers them, as amsmath does; in $$…$$ it does not (amsmath's \tag fails there). empheq numbers as the environment its argument names (\begin{empheq}{align} as align). xxalignat numbers nothing, and CD, multlined, rcases and the other inner environments number nothing of their own.

On a line, \nonumber or \notag takes the number away and \tag{x} replaces it with x. A \label in a line gets that line's number.

\begin{align}
  a &= b \label{eq:first} \\
  c &= d \nonumber \\
  e &= f \tag{$\star$}
\end{align}

Here eq:first is 1, the second line has no number and the third shows (⋆).

A \caption inside figure or wrapfigure steps the figure counter; inside table, wraptable or longtable the table counter (starred forms too). Inside subfigure and subtable (subcaption), and for subfig's \subfloat[caption]{…}, a caption is lettered instead, a, b, … within its float, and \ref prints the float's number and the letter, 1a: the number the float's caption has, or the one it is about to get when it comes after. \captionof{figure}{…} steps figure outside a float. Any other caption outside a float is not numbered. The model keeps each float's captions with their short captions.

\newtheorem{env}{Title} declares a theorem-like environment with its own counter; \newtheorem{env}[other]{Title} shares other's counter; \newtheorem{env}{Title}[within] numbers it within within (1.1); \newtheorem* declares an unnumbered one (a \label in it prints nothing). thmtools' \declaretheorem[options]{env} declares one too: name (or title) is its title, the name with a capital first letter when missing; numberwithin (or within, parent) numbers it within a counter; sibling (or sharenumber, numberlike) shares one; numbered=no leaves it unnumbered; style and the other options are not read. ntheorem's \newtheorem is LaTeX's. Each environment of a declared name in the text steps its counter; its note is its optional argument, or a [note] at the very start of its body when the signature table does not give the environment an optional argument.

\newtheorem{theorem}{Theorem}[section]
\newtheorem{lemma}[theorem]{Lemma}

A \label takes the number and the kind of the last numbered thing in scope, as \refstepcounter leaves them: a section, an equation (line), a float's caption, a theorem, a footnote, an item of enumerate or a counter stepped by \refstepcounter. An item prints as the standard classes print it: 2, 2a, 2(b)i, 2(b)iA at the four levels; \item[label] and items of itemize and description number nothing. An environment is a group: at its end, what a \label would point at is restored to what it was before it. The same holds for a footnote's text. A label with nothing numbered before it has no number and the target None.

The model collects \newcommand, \renewcommand, \providecommand (name, number of arguments, default of the optional first one, body), \def, \gdef, \edef, \xdef (the number of # parameters), \DeclareMathOperator (no arguments), \newenvironment and \renewenvironment (arguments, default, begin and end code). The bodies of definitions are templates: no label, citation or section inside them counts. \bibliography{a,b} and \addbibresource{a.bib} give the bibliography files, .bib added where missing, found as BibTeX finds them: beside the root document, else in the folders of BIBINPUTS, else where kpsewhich says (a library in ~/texmf/bibtex/bib); \bibliographystyle gives the style. A command without arguments in a numbered display that the document defines with \tag (the common \numberthis) numbers its line, and one defined with \nonumber or \notag (\nn) leaves it unnumbered, as LaTeX does.

Every command the view renders, and how:

Styles nest: \textbf{a \emph{b}} shows b bold italic.

Font declarations style the rest of their group (latex_view::declaration): \bf and \bfseries bold; \it, \itshape, \sl, \slshape and \em italic; \tt and \ttfamily monospace; \upshape ends italic, \mdseries bold, \rmfamily and \sffamily monospace, and \normalfont and \rm all three; \sc, \scshape and \sf are known and change nothing shown. The sizes \tiny, \scriptsize, \footnotesize, \small, \large, \Large, \LARGE, \huge and \Huge show the text at the ratio the standard classes give them at 10pt (5, 7, 8, 9, 12, 14.4, 17.28, 20.74 and 24.88 points) to a 12-point text; \normalsize ends them. A declaration is followed from where it is to the end of its group {…} (Plain {\bf bold}), of its environment's body (an environment is a group), or, at the top level, of its paragraph; a declaration in the document's body does not reach into the paragraphs after it. The declarations themselves stay as source, dimmed.

Typographic replacements apply in running text and in the arguments of the commands a reader reads (the formatting, front matter and sectioning commands, \footnote, \caption, \item, \title, \author, \date, \text, \mbox, \textcolor, \thanks, \enquote), never in math, verbatim text, \begin and \end lines, or the arguments of other commands. With the cursor on one of them, it shows as typed.

Control symbols in text:

Commands without arguments (the word table):

A text accent and its letter show as one character, composed where Unicode has one: \"o (and \"{o}) ö, \'e é, \`e è, \^o ô, \~n ñ, \=a ā, \.z ż, and, with the letter after a blank or in braces, \u{g} ğ, \v{s} š, \H{o} ő, \c{c} ç, \k{a} ą, \r{a} å, \d{a} ạ, \b{a} a̱; \'{\i} is í. The BibTeX grid shows them the same way.

The journal classes put their front matter in commands of their own. Written in the body (as acmart and RevTeX require), these commands show their text styled, with the words the class prints before it:

The parts of an address run together in one argument (acmart's \affiliation{\institution{…}\city{…}\country{…}}) are separated by ", ". The front matter environments show a heading on their \begin line: IEEEkeywords "Index Terms—", keyword and keywords "Keywords: "; elsarticle's frontmatter is a container whose \begin and \end lines are delimiter lines. For \maketitle in the preamble case, the byline leaves out \thanks, \inst, \footnote, \footnotemark, \IEEEauthorblockA, \IEEEmembership, \affiliation, \institute, \address, \email, \orcid and \textsuperscript with their arguments, and \and and \\ separate the names.

A delimiter line is a \begin or \end line of its own; the frontends draw it discreetly.

Each \item of a list away from the cursor shows its label, indented by two em spaces per enclosing list (and per enclosing quote, quotation, verse or abstract) below the first; continuation lines are indented to the item's depth, the source's own indentation hidden.

enumitem's options are read from the list's optional argument: label= (\arabic*, \alph*, \Alph*, \roman*, \Roman* replaced by the item's number; in itemize the label as written) and start=. Other options are ignored. \setcounter{enumi}{4} (or \addtocounter, with the counter of the list's level) in the list sets the number the next item counts on from, as in LaTeX. LaTeX stops at an \item outside a list and at lists nested more than four of a kind or six in all; Kalem draws them as the table says and kalem check warns (latex-item-outside-list, latex-too-deep).

The \begin of an environment declared with \newtheorem or \declaretheorem shows "Title N (note)": the title and number bold, the note from the optional argument or from […] at the start of the body, followed by a period when amsthm is loaded (\usepackage{amsthm} or an AMS class), as amsthm's heads end, and by nothing otherwise, as LaTeX's own \newtheorem prints it. Its \end line is a delimiter line. \begin{proof} shows "Proof. " bold italic, or "X. " for \begin{proof}[X] (amsthm prints the note in place of "Proof"), and \end{proof} shows ∎. \theoremstyle is not read: every body is shown upright, where amsthm's plain style sets it in italics.

\begin{theorem}[Pythagoras]\label{thm:p}
  $a^2 + b^2 = c^2$.
\end{theorem}
\begin{proof}
  Trivial.
\end{proof}

In a report with \newtheorem{theorem}{Theorem}[chapter] in the second chapter and amsthm loaded, the first line shows "Theorem 2.1 (Pythagoras). ".

\includegraphics[options]{name} is drawn as the picture when its file is found: name in the document's folder, then in each \graphicspath folder; a name without an extension is tried with .png, .jpg, .jpeg, .pdf, .svg and .eps, in that order. The size comes from the first of these options present:

The graphical editor draws PNG, JPEG, SVG and PDF (its first page, as vectors, through hayro); an EPS or PostScript picture is converted to PDF once by Ghostscript, found where TeX's programs are, and drawn the same way, or shows as its name where Ghostscript is not installed. The terminal editor draws pictures through the kitty, iTerm2 or sixel protocols where the terminal has one, and [image: …] otherwise.

The bodies of the verbatim environments are monospace. lstlisting and minted are code blocks colored by kalem-highlight in the language their options name: lstlisting's language= option (a [dialect]Name form keeps Name), else the last \lstset{language=…} in the document; minted's argument. verbatim has no language and stays monospace. Comments (% to the end of the line) are dimmed; so are comment environments and the text between \iffalse and its \fi.

Everything outside the tables above is drawn as its source:

• A control word outside the signature table and the formatting table is dimmed, away from the cursor. A command the signature table knows but the view does not render (\label, \hspace, \usepackage) is drawn in the surrounding style, not dimmed. Arguments are drawn as text, with their braces.
• The \begin and \end of an environment the view does not render show as source, the command dimmed.
• A formula the renderer cannot lay out shows as its source in a red frame, as in Org.

Some commands have no drawing of their own but count as rendered in the coverage report, because they need none or have their effect elsewhere: \label, \begin, \end, \appendix, \frontmatter, \mainmatter, \backmatter, \bibliography, \bibliographystyle, \noindent, \par, \iffalse and \fi. Their names show as source.

kalem check FILE.tex --unrendered lists the commands and environments of the document's body the view does not render, most frequent first (\foo and \begin{bar} with their counts), and the share of the body rendered. Commands whose names are not all letters and @ are not listed, and nothing inside a formula counts, since formulas are the math renderer's. The share is computed over the body's non-blank characters: every command or environment not rendered counts as source whole, with its arguments and body. An environment counts as rendered when it is in the table above, or when the model declares it as a theorem.

The view gives the editors blocks (latex_view::blocks), which fold as Org's elements do. Each folds to its first line while the cursor is elsewhere.

Tab on a section's line cycles its folding as Tab does on an Org heading: its text and subsections hidden, its subsections shown, everything shown.

The outline panel lists the sections of the project in reading order with their numbers, levels counted from the highest level among them: those of the file shown, and those of the files it includes (\input, \include, \subfile=…) or that include it; choosing a section of another file opens that file at the section. A =\tableofcontents line, away from the cursor, shows the table of contents LaTeX prints there: the unstarred sections down to \subsubsection (\subsection in the classes with chapters: book, report, amsbook, memoir, scrbook, scrreprt, extbook, extreport), or down to the level \setcounter{tocdepth}{n} names, with their short titles, and the entries \addcontentsline{toc}{level}{title} adds where it stands, including those of the project's other files; each entry leads to its section. The \end{document} line, away from the cursor, lists the file's footnotes, each with its number and text, leading to it.

A reference shows what it resolves to, as a link; with any key unknown, that key shows as ?? and the chip is red. Every form is checked against what pdflatex typesets with hyperref and cleveref (tests/latex/references, regenerated by tools/latex-typeset.py).

\ref, \eqref, \pageref, \autoref and \nameref take one key: \ref{a,b} looks up the label a,b and shows ??, as LaTeX does. \cref and \Cref take a list, printed as cleveref prints it: keys of one kind grouped under the plural ("eqs. (1) and (2)", "sections 1 and 2"), sorted, three or more consecutive numbers as a range ("eqs. (1) to (3)"), kinds joined with "and", and three or more kinds with commas and ", and" ("fig. 1, table 1, and eq. (1)"). \cpageref is read by the model but not drawn.

With a \bibliographystyle Kalem knows, a citation shows what bibtex and LaTeX print for it (tests/latex/citations, one document per style, regenerated by tools/latex-typeset.py). Only the entries cited, \nocite included (\nocite{*} adds the rest of the bibliography), are numbered, and \nocite itself shows nothing.

With natbib and a numeric style, \citet shows "Knuth [5]" and \citep "[5]"; \citenum shows the number alone. For other styles (biblatex, or no \bibliographystyle), a citation shows author and year from the bibliography files the document names (\bibliography, \addbibresource), resolved from the document's folder. For each key: the family names of the authors (or editors) from the entry, "A", "A and B" or "A et al.", and the year (year, or the first four digits of date). Keys are joined with "; "; a key the bibliography lacks shows as itself and the chip is red.

With one optional argument it is the postnote, appended after ", "; with two, the first is the prenote, put before, and the second the postnote. A ~ in a note shows as a no-break space.

\citep[see][p.~12]{knuth84,lamport94}

shows "(see Knuth 1984; Lamport 1994, p. 12)".

With the cursor on a citation, a reference or a footnote, the status bar says what it is, and so does a tooltip under the mouse in the graphical editor:

• a citation: for each key, @key: and the entry as the bibliography of a CSL style renders it, or "No bibliography has the key @key";
• a reference: for each key, what the label numbers, "Section 2: Title" or "Figure 1: Caption", or "No label key";
• a footnote: its number and text.

The CSL style is chosen from biblatex's style= option, else \bibliographystyle:

Open Link (latex.link.open; Ctrl-click, Cmd-click on macOS) follows the command at the cursor: a reference to its \label (in another file of the project, that file); \url and \href to their address; \input, \include, \subfile and \import to their file (.tex added when the name has no extension and does not exist); \includegraphics to its picture; a citation to the first bibliography file. A reference to an unknown label says so.

The renderer is held to KaTeX on real formulas: tools/math-corpus.py reads every formula of two openly licensed books (the Open Logic Project and the HoTT book, 57,460 formulas) as Kalem's view reads them, and asks KaTeX 0.16 and the renderer about each, without the books' own macros. KaTeX renders 31,873 of them, and the renderer reads every one of those (the last one it did not, a control space ending a formula, L\ =, is handled since); it also reads 649 that KaTeX refuses, mostly =bussproofs trees, xymatrix diagrams and eqnarray that Kalem maps for it. A thousand of KaTeX's formulas, chosen by their hash, are kept in tests/corpus/math/katex-corpus.txt (CC BY-SA), and crates/org-math/tests/katex.rs checks that the renderer reads them all and renders a sample.

The formulas are drawn by RaTeX, which reads KaTeX's LaTeX. Of the math macros in the test list crates/org-math/tests/macros.txt (some three hundred, by package, each with an example), these are the ones it does not know; a formula using one shows as its source in a red frame, as in Org, unless Kalem handles the macro itself first. The test unsupported_macros checks that this table names exactly the macros the renderer refuses, so it changes when the renderer does.

kalem fmt FILE.tex [--check] [--align] changes only blanks: each line indented by the environments around it (not document), with the document's own step, the most common indentation the first line of an environment adds to its \begin line (a document that does not indent its environments keeps its indentation); runs of blank lines made one; blanks at line ends removed; one line ending at the end. Verbatim text is not touched, nor the \end line where it ends: verbatim environment bodies and verbatim arguments, the bodies of alltt, of fancyvrb's, PythonTeX's, LuaLaTeX's, SageTeX's and tcolorbox's listing environments, and of the environments \lstnewenvironment, \DefineVerbatimEnvironment (and its kin), \newtcblisting and minted's \newminted declare; none of them votes for the step. --align lines up the top-level & of the rows of tabular, tabularx, longtable, array, align, alignat, flalign, eqnarray, the matrices and cases written one row a line (\multicolumn rows and nested environments left). --check changes nothing and lists the files that would change.

Builds ask for SyncTeX (-synctex=1 to latexmk and the engines, --synctex to tectonic), so a NAME.synctex.gz lies beside the PDF. kalem_core::synctex reads it: its input files, then each page's boxes and points with the file and line they come from, in scaled points from the page's top left corner, given in PDF points.

• Show in PDF (latex.showInPdf) opens the root document's PDF (in latex.output_directory when set) at the first page holding a line of text from the cursor's line, or from the next line that typesets anything (a blank line or a comment typesets nothing).
• Ctrl-click (Cmd-click on macOS) on a page of a PDF that has a SyncTeX file opens the source at the line of the material nearest the point, in the line of text nearest it. A paragraph's lines of text carry the line where the paragraph ends and boundaries (x records) often do too; the material in them (kerns, glue, boxes) carries the line it was written on, so it is preferred, as synctex edit does.

Both are checked against TeX Live's synctex program on a compiled document of six sections and an included file (kalem-core/tests/synctex.rs, in the pdflatex job of CI): every line's page and box, and every line found again from a point in it.

The first of these that applies:

1. % !TEX program = NAME or % !TEX TS-program = NAME among the first 20 lines of the root document (! optional, any case).
2. The latex.engine setting (or --engine on the command line) unless it is auto or empty.
3. XeLaTeX when the project loads fontspec, unicode-math or polyglossia.
4. pdfLaTeX.

A name of step 1 or 2 means XeLaTeX when it is xelatex, LuaLaTeX when it is lualatex, Tectonic when it is tectonic (which then runs alone, below), and pdfLaTeX for anything else.

Looked for in PATH, in this order:

Without any of them, the build fails and says what to install: the command that installs TeX Live here (Homebrew's MacTeX, winget's MiKTeX, or the Linux distribution's packages), and Tectonic's site; with TeX but not the engine the document needs, it names both. latex.output_directory (or --outdir) names a folder relative to the root's, created if needed; the PDF and the log are looked for there as STEM.pdf and STEM.log.

The log is read after the build:

• Lines of exactly 79 characters are joined with the next, as TeX wraps them.
• FILE:LINE: MESSAGE (-file-line-error; the file has no blank and an extension of one to four letters or digits) is an error at that file and line, whether the file is the document's or a package's.
• ! MESSAGE is an error; its line is the l.N within the next 12 lines; its file is the one the log was reading.
• A line containing Warning: is a warning, continued on the following lines that start with three spaces until the text ends with a period; its line comes from input line N, at lines N or at line N.
• A line starting with Overfull or Underfull is a bad box.
• The file being read is followed through the log's parentheses: ( and a name opens a file, ) closes it.
• A message naming a missing file (File `x.sty' not found) gets the command that installs it: tlmgr install x when tlmgr is in PATH (TeX Live), mpm --install=x when mpm or miktex is (MiKTeX).

The status bar gives the first error at its file and line with the count of the others, or the PDF and the number of warnings. The problems are kept with their files and show in each file of the project as latex-build diagnostics. kalem latex build prints them as FILE:LINE: error|warning|info: MESSAGE followed by the PDF's path, or with --format json as an object with root, pdf and problems (file, line, severity, message); it exits with 1 when there is an error or no PDF.