# LaTeX setup

> The latex feature of fframes-kit (MathTex, Tex, ChemEq, see components.md) typesets MathTex formulas with Typst, built into the kit, so most videos need…

Page: https://fframes-kit.pages.dev/docs/start/latex-setup/

The `latex` feature of `fframes-kit` (`MathTex`, `Tex`, `ChemEq`, see
[components.md](https://fframes-kit.pages.dev/docs/text-and-formulas/formulas.md)) typesets `MathTex` formulas with Typst, built into
the kit, so most videos need nothing installed. TeX is needed only for:

- `Tex` (text mode) and TikZ pictures;
- `ChemEq` and the chemistry kit's reactions (mhchem);
- templates with a preamble, compiler or wrapper of your own;
- formulas that fail with `TexError::NeedsTex` and are switched to TeX with
  `.backend(TexBackend::Tex)`, or every formula after `TexEngine::with_backend(TexBackend::Tex)`.

For those the kit runs the TeX installed on your machine. It needs:

- `latex` (or `xelatex` / `lualatex` for `TexCompiler::XeLatex` / `LuaLatex`);
- `dvisvgm`.

MiKTeX and TeX Live both ship them. Formulas that are already in a video's cache render
without TeX, so only the person who adds or changes such a formula needs it.

## Windows: MiKTeX

1. Install MiKTeX from [https://miktex.org/download](https://miktex.org/download), or run `choco install miktex`.
2. Enable automatic package installation, so a missing package installs itself instead of
   opening a dialog that stalls the render until the timeout:

```powershell
initexmf --set-config-value "[MPM]AutoInstall=1"
```

3. Check it in a new terminal:

```powershell
latex --version
dvisvgm --version
```

If the terminal does not find `latex`, the kit still looks in the default MiKTeX folders:

- `%LOCALAPPDATA%\Programs\MiKTeX\miktex\bin\x64` (an install for the current user);
- `C:\Program Files\MiKTeX\miktex\bin\x64`.

### Without a working installer

If the installer cannot download (proxies, a broken Chocolatey package), MiKTeX's
command-line setup works offline in two steps. Get `miktexsetup_standalone.exe` from the
same download page, then:

```powershell
miktexsetup_standalone --remote-package-repository=https://mirrors.mit.edu/CTAN/systems/win32/miktex/tm/packages/ --local-package-repository=C:\miktex-repo --package-set=basic download
miktexsetup_standalone --local-package-repository=C:\miktex-repo --package-set=basic --shared=no install
```

- Any mirror listed on [https://ctan.org/mirrors](https://ctan.org/mirrors) works for `--remote-package-repository`.
  MiKTeX only accepts mirrors that are registered, so pick one from that list.
- `--shared=no` installs for the current user.
- The first formula that uses a package outside the basic set installs it. This takes
  20 to 30 s once, for example for mhchem and chemfig.

## Ubuntu: TeX Live (or MiKTeX)

```bash
sudo apt install texlive-latex-extra texlive-science texlive-pictures dvisvgm
latex --version && dvisvgm --version
```

`texlive-science` brings mhchem, siunitx and physics, `texlive-pictures` circuitikz. Add
`texlive-xetex` or `texlive-luatex` for the other compilers. MiKTeX for Linux works too
([https://miktex.org/download](https://miktex.org/download)). Enable its automatic installation as on Windows.

## macOS: MacTeX

```bash
brew install --cask mactex-no-gui
eval "$(/usr/libexec/path_helper)"   # or open a new terminal
latex --version && dvisvgm --version
```

## Pointing the kit at a TeX folder

`FFRAMES_TEX_BIN=<folder>` makes the kit look for the tools only in that folder. This is
useful when `PATH` is not refreshed yet, or to pick one of several installations.

Pointing it at an empty folder hides TeX. Use that to check that a video renders from its
committed cache alone.

## The cache

- `TexEngine::new(dir)` writes one small `.svg` per formula into `dir`, for both backends.
  - The file name of a TeX formula is a hash of the compiler, the preamble and the source.
    A Typst formula's is a hash of the template's definitions, the source and the Typst and
    mitex versions the kit pins. A changed formula gets a new file.
  - Old files stay until you delete them. To start over, empty the directory and render
    the video once.
- Commit the directory. Then CI and other machines render without TeX.
- The web editor has no file system. `TexEngine::with_embedded(tex_cache!("tex-cache"))`
  compiles the directory's files into the build, and the engine reads them before the
  directory. The gallery does this; its `build.rs` rebuilds the crate when a file is added.
- The same TeX and dvisvgm versions reproduce the files byte for byte on any system, and
  so does the same kit version for Typst: the kit writes `\n` line ends.
- With `core.autocrlf` on (the Git for Windows default), put a `.gitattributes` with
  `*.svg -text` into the cache directory. Otherwise git reports the files as changed after
  every regeneration (see `gallery/tex-cache`).
- When TeX is missing and a formula is not in the cache, `typeset` returns
  `TexError::NotInstalled`. The error names the formula and says how to install TeX for
  the current system.

## Errors

- **`TexError::Compile`**: the TeX log from the first `!` line, and the whole `.tex` file
  the kit wrote, for an error in the formula.
- **`TexError::Timeout`**: a run took longer than the timeout (120 s,
  `TexEngine::with_timeout`). With MiKTeX this usually means a package dialog is waiting.
  Enable automatic installation (step 2 above).
- **`TexError::Convert`**: `dvisvgm` failed. Its output is in the error.
- **`TexError::NeedsTex`**: the formula uses a command the Typst backend cannot typeset
  (`\ce`, `\begin{tikzpicture}`, an unknown macro, physics' `\div`, `\qty(x)`). The error
  names the command. Typeset that formula with `MathTex::new(..).backend(TexBackend::Tex)`;
  the kit never switches by itself.
- **`TexError::Typst`**: mitex or Typst rejected the formula (`\frac{a}`, an unbalanced
  brace). The message and the formula are in the error.
- **`TexError::NotInstalled` in the web editor** (any tool): the editor cannot typeset and
  the embedded cache has no SVG for the formula. Render natively once, then rebuild the
  editor with the cache embedded (`TexEngine::with_embedded(tex_cache!("tex-cache"))`), and
  draw `Formula::unset(source)` for what is still missing (see
  [components.md](https://fframes-kit.pages.dev/docs/text-and-formulas/formulas.md)).

The kit runs TeX with `-interaction=nonstopmode -halt-on-error` and never with
`--shell-escape`, so a formula cannot run commands.