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 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, 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:

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

3. Check it in a new terminal:

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:

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

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). Enable its automatic installation as on Windows.

macOS: MacTeX

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

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