⚠ Warning: This project is mostly abandoned, and
certainly not well-maintained.
⚠️ Use at your own risk!
Yet another LaTeX build wrapper, with one or two nifty features:
It is easy to extend ltx2any with additional LaTeX engines and secondary tools. Currently, we provide the following functionality:
pdflatex
(default), xelatex
and lualatex
for creating PDFs.bibtex
, biber
, makeindex
, SyncTex support, TikZ externalization, gnuplot
and Metapost.Pull requests with new engines or extensions are appreciated. Please make sure to adhere to the specs (upcoming) and include test cases.
Note: This is still prerelease code. It is by no means considered nicely written, bug-free or reliable. Take care!
For using ltx2any without any bells and whistles, you should have
Any of the major (La)TeX distributions should provide the binaries you need.
You can print a complete list of useful but optional gems and binaries by calling
ltx2any with the --dependencies
option; some provide improved speed or usability,
others are necessary for only some engines or extensions.
See here for slightly more elaborate installation instructions.
Once ltx2any
is in your PATH, run ltx2any <file>
to compile the specified file.
Find out about available parameters by running ltx2any --help
.
A typical run may look like this:
$> ltx2any bibtex_test.tex
[ltx2any] Initialising ... Done
[ltx2any] Copying files to tmp ... Done
[ltx2any] PdfLaTeX(1) running ... Done
[ltx2any] BibTeX running ... Error
[ltx2any] PdfLaTeX(2) running ... Done
[ltx2any] PdfLaTeX(3) running ... Done
[ltx2any] PdfLaTeX(4) running ... Done
[ltx2any] There were 1 error and 3 warnings.
[ltx2any] Output generated at bibtex_test.pdf
[ltx2any] Assembling log files ... Done
[ltx2any] Log file generated at bibtex_test.log.md
Note that ltx2any figured out the necessary number of runs and external programs:
because of some references, three runs of pdflatex
are needed (and we
need a fourth to realise that the PDF has converged) and bibtex
was
used to resolve literature references.
Rerun the command and see how this automatism speeds up subsequent runs!
Using another engine is as easy as typing e.g. ltx2any -e lualatex <file>
. The
current default is pdflatex
though that is easily changed. See a full list of
supported engines by passing the --engines
option.
By the way, this is what a PDF log looks like (add option -lf pdf
; requires
pandoc):
Note how you get clickable links to the referenced files. You can also navigate from error to error using the error count at the top and the small arrows.
Extensions are what make ltx2any special: when written properly, they detect what has to be
done after the first run of, say, pdflatex
and execute the necessary steps without any
need for user intervention.
Most do their work just by being there, with some exceptions. Run ltx2any with the
--extensions
option for a full list.
TikZ can externalize images so that they do not have to be rebuilt every run; this can save quite some compilation time. We support TikZ externalisation as long as LaTeX engines are used. Here is what you need to do in order get it running.
Read section V.50 in the pgfmanual.
Make sure you use the list and make
mode, that is your file specifies:
\tikzset{external/mode=list and make}
There are two ways to make ltx2any rebuild images:
-ir all
option to rebuild all externalised images.-ir img1:img2:...:imgN
to rebuild only images img1
through imgN
.There is currently no support for the new support in TikZ for detecting when images have to be rebuilt due to changes (cf #47). You can, however, change the set of rebuild images in daemon mode (see below).
Hint: You may want to turn off externalization while you work on an image like this:
\tikzset{external/export next=false}
\begin{tikzpicture}
...
Hint: Externalization adds quite some overhead and is probably not useful for small images. In particular, packages that use TikZ for small stuff such as todonotes can slow down compilation considerably.
Therefore, you may want to enable externalization only for specific, complex images (recommended) or redefine troublesome commands, e.g. like this:
\usepackage{letltxmacro}
\LetLtxMacro{\oldtodo}{\todo}
\renewcommand{\todo}[2][]{%
\tikzset{external/export next=false}\oldtodo[#1]{#2}%
}
Add the -synctex
parameter;
after successful compilation, a gzipped .synctex
file should appear in your main directory,
ready for other tools to use.
No additional -ep
parameter is necessary.
Alas, LaTeX engines themselves can not run in parallel. But some extensions can, namely such that create many small, independent jobs (e.g. TikZ externalization). You only have to install Ruby gem parallel for making the best out of your multicore CPU.
Install Ruby gem listen to make daemon mode available.
Option -d
then causes ltx2any
to wait for files in the working directory to change;
if that happens, the compilation process starts over.
By default, ltx2any
will ignore changes to files it creates itself (even across instances).
Everything else in the current tree is listened to, though -- with some restrictions
around symlinks -- so take care if there is lots of stuff.
As a general rule, ltx2any
works best if the document you want to compile resides in
its own directory; use symlinks for shared resources.
While ltx2any
waits for files to change, you can hit ENTER to get an interactive prompt;
hit ENTER again (with empty command) to close the prompt and recompile.
Command help
will tell you what you can do in the prompt; right now the most relevant use is
probably to force recompilation.
This feature is still subject to development and far from finished.
TODO: describe Extension and Engine interfaces -- once they have stabilized and are less likely to hurt people.