Usage

Configuration

To configure how your .tex file is compiled, simply write the necessary commands before your preamble, preceded with %$. That’s all:

% Compile this file using latex+dvipdf:
%
%$ latex foo.tex
%$ dvipdf foo.dvi

\documentclass{article}
\begin{document}
Hello, world!
\end{document}

Now, when calling SpiX on this file, commands latex foo.tex and dvipdf foo.dvi are called:

spix foo.tex

Note

  • The lines that are interpreted as snippets by SpiX must begin exactly with the two characters %$ followed by a space. Any other prefix is not considered a command:

%$ A command
% $ Ignored
%$Ignored
 %$ Ignored
$% Ignored
  • Any snippet defined after the beginning of the preamble is ignored. SpiX does not parse LaTeX code, so it considers any line that is not empty, or does not begin with % (maybe preceded by spaces) as a preamble.

%$ A snippet
\documentclass{article}
%$ Ignored
\begin{document}
%$ Ignored
\end{document}
%$ Ignored

Note

There is no configuration file. SpiX is meant to run the same way on any machine: you set up configuration in a .tex file, you send this file to your friend, she runs SpiX on it, and it runs exactly the same way (not relying on a configuration file located somewhere in your home directory, that you forgot to send along the .tex file).

Allowed commands

The code snippets defined in SpiX are interpreted by the sh shell [1] (but try to stick to valid sh code, to make your snippet portable). This means that variables and control structures are allowed.

%$ dviname=$basename.dvi
%$ latex $texname
%$ bibtex $basename
%$ for i in $(seq 3)
%$ do
%$     latex $basename
%$ endfor
%$ dvipdf $dviname

Consecutive lines starting with %$ are interpreted by one single shell call.

%$ myvariable=foo
%$ # This would display "foo"
%$ echo $myvariable
% This line does not start with "%$", starting another shell.
%$ # This would display nothing, since "$myvariable" has been defined in another shell.
%$ echo $myvariable

Environment variables

In order to be readable by a person who has never heard about SpiX, the snippets are run as-is (interpreted by the sh shell).

A few environment variables are introduced (this allows snippets to be independent on file name). For instance, suppose Donald is writing his next book, in ~/taocp/vol7.tex:

  • $texname is the file name (without directory): vol7.tex;

  • $basename is the file name, without extension: vol7.

For instance, if file foo.tex contains the following snippet:

%$ latex $texname
%$ dvipdf $basename

When calling SpiX, commands latex foo.tex and dvipdf foo are run.

About errors

SpiX will stop compilation when a code snippets fails (returns an error code different from 0).

To change this behavior, see How to stop compilation on first error? or How to go on compiling, even when errors occur?.

Command line arguments

Since there is no option to configure how compilation is performed (everything is in the .tex file), the binary has very few options.

Compile a .tex file, executing commands that are set inside the file itself.

usage: spix [-h] [-n] [--version] FILE

Positional Arguments

FILE

File to process.

Named Arguments

-n, --dry-run

Print the commands that would be executed, but do not execute them.

Default: False

--version

Show version and exit.

Warning

SpiX is dumb: it does not control what is run, it does not check that it is safe to run. It runs what it is told to run. For instance:

  • it does not prevent malicious commands:

    %$ rm -fr /
    
  • it does not prevent infinite loops:

    %$ spix $texname
    
  • it does not prevent fork bombs:

    %$ spix $texname & spix $texname &
    

Basically, calling SpiX is like running a shell script: do not call SpiX on an untrusted .tex file.

Footnotes