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