reitzig / ltx2any

Yet another LaTeX build wrapper, with one or two nifty features
GNU General Public License v3.0
59 stars 4 forks source link
build-automation build-tool latex

No Maintenance Intended Test

ltx2any


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:

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!

Requirements

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.

Basic Use

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

Example PDF log

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

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 Externalization

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.

SyncTeX

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.

Advanced Use

Parallel Compilation

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.

Daemon Mode

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.

For Developers

TODO: describe Extension and Engine interfaces -- once they have stabilized and are less likely to hurt people.