Why SpiX?

Which problems does SpiX solve?

The goal of SpiX is to have every information about a .tex compilation process inside the very file to process.

Example 1

Alice is a math teacher. She writes every document she shows or hands out to her students using LaTeX. She has a repository consisting of hundreds of LaTeX files. Most of her documents are compiled using a single pass of LuaLaTeX, but some of them need two passes (because labels and references), some of them contains pstricks figures that must be compiled with LaTeX, then converted to PDF (because she copied them from another repository that uses LaTeX)…

When she works on a file she edited one year ago, with her previous class, she has to guess how to compile it (lualatex? lualatex+lualatex? latex+dvipdf?).

Using SpiX, the compilation process is written inside the .tex file, so she can:

  • look at it to see which tool to use to compile it;

  • compile it using SpiX.

Example 2

Alice happens to work with Bob, who also uses LaTeX. The ideal way to work on the same file would be to share a git repository containing a Makefile, but evoking those tools would scare Bob away. So they exchange files via email. Using SpiX, the compilation process of the file they exchange is written inside the file itself:

% Use lualatex twice to compile this file:
%$ lualatex foo.tex
%$ lualatex foo.tex

\documentclass{article}
\begin{document}
Hello, world!
\end{document}
  • Alice: The first three lines of this file can be parsed by SpiX, so that Alice simply runs spix foo to compile it;

  • Bob: The first three lines of this file are human-readable, so Bob understands how he should compile it.

Why not using any other tool?

Makefile

If your project is complex (convert images, compile .dot graphs, several latex passes, bibliography, index…), use a Makefile. You may prefer SpiX if:

  • the Makefile would be only two lines long;

  • you have tens or hundreds of simple .tex files, with slighly different compilation processes (which would mean tens or hundreds of Makefiles, or one huge Makefile);

  • you want to have the compilation process inside the .tex file itself.

Arara

I got the idea to write compilation information into the .tex file itself from Arara.

Arara provides a set of rules to compile files. If something is missing, you can write your own rule in an external file, so you might prefer SpiX if you want everything in the same .tex file.

Arara configuration is written using YAML. So, to understang Arara configuration, one has to know YAML and Arara (while SpiX configuration is plain shell commands, so it is human readable [1]).

You might prefer Arara if you have complex rules; SpiX is well suited for plain, simple commands.

TrY

TrY does exactly what SpiX does (and I copied the syntax of commands in .tex files from TrY). But it is written in Python2 (which is obsolete), and it seems to be no longer maintained.

SpiX can be seen as a successor of TrY [2].

Latexmk

Latexmk (and similar tools) has a slightly different purpose.

  • It guesses how to compile file (how many passes, etc.), while SpiX commands are explicit (there is no magic in SpiX).

  • User has to specify which flavor (LaTeX, pdflatex, LuaTeX, XeLaTeX…) to use, while with SpiX, this is stored in the .tex file.

Why is it named SpiX?

Arara is named after the blue-and-yellow macaw (arara meaning macaw in Portuguese), which is a big parrot. This project, which happens to be a simpler version of Arara, is named after the blue winged parrotlet (toui de Spix in French), which is a small parrot.

Obviously, the capital X is a nod to the capital X of LaTeX.

A blue winged parrotlet.

A blue winged parrotlet. Photo by Evaldo Resende - Own work, CC BY-SA 4.0 (flipped, resized, reframed by Louis Paternault).

Footnotes