# Tools for automating document compilation

A lot of people write makefiles that say something like

paper.pdf: paper.tex
pdflatex paper
bibtex paper
pdflatex paper
pdflatex paper


To handle re-running TeX to get new/changed references and so forth. Is there a better way to do this?

-
A somewhat related comment (given the current set of answers to your question): I think that any program that claims to be able to automatically discover the proper build sequence for a (La)TeX document must also be able to solve the halting problem. –  ESultanik Sep 3 '10 at 2:04
@ESultanik: If a finite sequence of finite length steps exists to compile the document, an algorithm to find it is pretty easy. If no finite sequence of steps exist, you're not going to be able to write an algorithm to deduce that in every case. It's possible to deal with some steps being infinite length (by having increasing length time outs). –  TH. Sep 4 '10 at 21:08
Should this question be CW? –  doncherry Oct 14 '11 at 15:02

Latexmk is one possibility, although I've never used it myself.

-
This is what I regularly use, and I can highly recommend it. –  Juan A. Navarro Jul 27 '10 at 16:44
Let me second that, I use it as well, the only thing I haven't (yet) been able to automate with it is running of 'makeglossaries' (part of the 'glossaries' package). For everything else it works great, automatic dependency tracking (even using multi-file documents). –  Giel Aug 6 '10 at 13:53
I haven't used it with glossaries, but I am using biblatex, and it picks that up just fine. –  rcollyer Sep 30 '10 at 14:00
Solutions for latexmk + makeglossaries: tex.stackexchange.com/questions/1226/… –  doncherry Oct 14 '11 at 15:01
If you run latexmk -pvc, it will monitor your files for changes. See magic.aladdin.cs.cmu.edu/2007/11/06/… –  Jack Morrison Sep 24 at 14:36

There is a tool named Rubber. It is for instance used by Gedit LaTeX plugin. It should recognize which tools to run (BibTeX, makeindex...) and run (pdf)latex and them in right order and how many times it is needed to converge to the ready file. It behaves like make, i.e. it does not recreate files that it thinks won't change recompiled (this can be omitted by adding -f option).

Compiling to dvi:

rubber filename.tex


Compiling to pdf:

rubber --pdf filename.tex


Cleaning compilation debris:

rubber --clean filename.tex

-
–  Quadrescence Jul 26 '10 at 20:03
It's not Linux specific. I'm using it on Mac OS X nowadays. Excellent, highly recommended (and, unfortunately, not actively maintained). –  Jukka Suomela Jul 26 '10 at 20:06
Does it support multibib? –  Dima Jul 27 '10 at 12:45
I don't think so. Still it is in major linux distros' repositories. –  mbq Jul 27 '10 at 21:49
@Dima: Yes, multibib with rubber seems to work ok. –  Jukka Suomela Aug 4 '10 at 20:51

I did a large amount of research for a very similar StackOverflow question. To summarize the problems of each tool:

• latexmk will overwrite your document in place, frequently causing your viewer to display an incomplete document (eg when there are errors). Its error support is bad.

• rubber will overwrite your document in place (see above). It also frequently doesn't update your document enough.

• rubber-info prints errors spectacularly, and is better than all other tools at this task. It can be used seperately from rubber, with any other tool.

• vim-latexsuite has an awful build system. Avoid.

• I couldnt make ltx work.

• MikTex is windows only.

• latex-makefile doesn't allow you use pdflatex, only latex -> ps -> pdf. It also misses bibtex sometimes.

My final solution constantly rebuilds the document via pdflatex, only overwriting when the document has changed (for your viewing pleasure). It relies on rubber-info for errors. I set vim to save the file after every X keystrokes, so that my script constantly rebuilds.

-
Regarding overwriting in place: Many viewers nowadays handle this very well. For example, Preview.app (standard part of Mac OS X) doesn't seem to have any problems with that – when you change windows from your editor to Preview, it'll notice that the document has changed and reload it. On Linux, modern PDF viewers seemed to work very well, too; after all, this is a very common use case. –  Jukka Suomela Aug 17 '10 at 10:53
Regarding rubber not updating your document enough: I have never seen this with Latex documents that compile without errors. This seems to happen only if Latex, Bibtex or one of the other tools terminates with an error. (It can be extremely confusing, however, as rubber -Wall foo.tex does not necessarily print anything if something very unexpected happens; you need to inspect the log files by yourself or re-run with -v -v -v.) –  Jukka Suomela Aug 17 '10 at 10:57
@Jukka: The problem with viewers is that they don't wait until the document is finished. So they render the first 50 pages of a 200 page doc. –  Paul Biggar Aug 21 '10 at 14:51
@TH.: By the way, if you prefer atomic renames, you can use it with any tool. Just write a one-line shell script that runs something like your-favourite-tool foo.tex && mv foo.pdf foo-real.pdf. –  Jukka Suomela Sep 5 '10 at 12:45
@TH, look into Skim. It doesn't require that application change before updating. –  Reid Jan 6 '11 at 16:01

Try Arara. It also has a great manual.

# \expandafter\thecomment

Arara provides us with ways (rules) to compile the document that are specific to the document. The rules for compilation are put inside the document. Hence, compilation boils down to a simple arara yourtexfile.

First, install arara and make sure that the arara executable is included in system path. Arara also needs java runtime environment (jre) to be installed. To use arara we should add the rules inside the document itself as in the following code. Save this code as yourfile.tex and execute arara yourfile:

% arara: pdflatex: {synctex: yes}
% arara: makeindex: { style: yourfile }
% arara: biber
% arara: pdflatex: {synctex: yes}
% arara: pdflatex: {synctex: yes}
% arara: clean: {files: [yourfile.aux, yourfile.idx, yourfile.ilg, yourfile.ind, yourfile.log, yourfile.bbl, yourfile.bcf, yourfile.ist, yourfile.blg, yourfile.run.xml]}
%
\documentclass{article}
\usepackage[utf8]{inputenc}
\usepackage{filecontents}
\usepackage{makeidx}
\begin{filecontents}{\jobname.ist}
delim_0 "\\dotfill "
delim_1 "\\dotfill "
delim_2 "\\dotfill "
delim_r "\\textendash"
suffix_2p "\\nohyperpage{\\,f.}"
suffix_3p "\\nohyperpage{\\,ff.}"
\end{filecontents}
\usepackage[backend=biber]{biblatex}
\makeindex
\begin{document}
A citation\cite{companion} and an index entry\index{bla} and some arbitrary text.
\printbibliography
\printindex
\end{document}


To comment out an arara directive, just put ! like

% !arara: makeindex


For more details, consult the excellent arara guide.

-
Could you expand this answer? As it is, it's more of a comment than an answer. –  doncherry Dec 21 '12 at 17:47
Thanks ;) [filler] –  doncherry Dec 21 '12 at 22:45
@doncherry Also \expandafter\thecomment is great! It took a while, until I realized the meaning … ;-) –  Speravir Dec 21 '12 at 23:29
Arara requires Java :( –  AIB May 23 at 22:09

Scons seems to be the ultimate LaTeX building tool.

Let me elaborate on Karsten W.'s answer on the configuration file.

A typical build script for building LaTeX can be the following. Put this in a file called SConstruct:

# make sure scons finds tex executables:
import os
env = Environment(ENV=os.environ)
# target and source:
pdf_output = env.PDF(target='main.pdf', source='main.tex')
# make sure that the pdf is reloaded properly (e.g., in Skim)
env.Precious(pdf_output)


You can build the pdf simply by running

scons


Notice that, quite amazingly, scons will detect the changes in the files \included in the main.tex file and also the bibliography file!

-

For emacs users, AUCTeX provides the command TeX-command-master (bound to C-c C-c by default) that doesn't quite answer the request, but nevertheless helps a lot. The command runs (pdf)latex, bibtex, and makeindex on a .tex file as required. You do have to invoke it multiple times, but it does a pretty good job of sorting out what commands need to be run in what order. (I have had the occasional document that outsmarted it, mostly ones using the exam.cls document class.)

-
Yes, it's great. You can just hit C-c C-c, and it will call whichever relevant compilation command is necessary, and "View" if it's fully compiled. –  ShreevatsaR Jul 26 '10 at 21:57
A hook to make it automagic in AUCTeX to rerun the next command? –  Dima Jul 27 '10 at 12:44
YaTeX is also nice: yatex.org –  Suppressingfire Jul 27 '10 at 21:08
Annoyingly, it doesn't know to rerun bibtex if the .bib has changed, but the .tex hasn't. but overall it's still much better than doing it by hand. –  Seamus Aug 5 '10 at 17:40
@Seamus: true enough. I console myself by noting that a change in a .bib is relatively rare. But, the grumble isn't entirely dissipated. –  vanden Aug 7 '10 at 17:03
show 1 more comment

Generation of references is handled automatically by the ConTeXt toolchain, so you never have to worry about remembering how many runs you need. The example Makefile would look like this if you used ConTeXt:

paper.pdf: paper.tex
context paper

-
Isn't texexec the preferred way to typeset ConTeXt files? –  Sharpie Aug 11 '10 at 7:04
In mkII yes, but with mkIV things got simpler (or different). In the example above I'm asuming one is using mkIV. –  helcim Aug 11 '10 at 13:31

In addition to all of the good answers above, users on Windows using MiKTeX can use the texify program, which has a number of options to adjust output mode (DVI or PDF), options for BibTeX and MakeIndex and so on.

-
For me as a MiKTeX user, texify seemed like the way to go. Unfortunately, although it is possible to switch from bibtex to bibtex8 by setting the respective environment variable, I never managed to pass options to bibtex8. As I need the option --wolfgang to run bibtex8 together with the biblatex package, texify is out of the question. –  lockstep Aug 6 '10 at 11:55
@lockstep. You can use bibtex8 --wolfgang with MikTeX. In WinEdt, for example, go to execution modes, select BibTeX and switch executable to bibtex8 and add "--wolfgang" to the switches. –  Rob Hyndman Aug 11 '10 at 5:23
I know - I have used the --wolfgang switch with TeXnicCenter. However, I can't set a bibtex(8)-option with texify (the compiler driver that comes with MiKTeX). –  lockstep Aug 11 '10 at 7:54

I find GNU Make incredibly convenient for parsing. In vim I've mapped F2 to make, so when I've edited something I can just hit F2 and switch to evince to see it instantly.

Below is my Makefile, which also handles parsing graphviz files.

GRAPHS=overview_dot.pdf hello_dot.pdf
TARGET=something.pdf
TEXFILES=file1.tex file2.tex file3.tex
HELPFILES=

all: $(TARGET)$(TARGET): out.pdf
mv out.pdf $(TARGET) out.pdf:$(GRAPHS) $(TEXFILES)$(HELPFILES) Makefile

clean:
rm -rf *.aux *.log *.out *.toc *.eps *.data *~ $(GRAPHS)$(TARGET)

%.svg: %.dot
dot $*.dot -Tsvg -o$*.svg

%.png: %.dot
dot $*.dot -Tpng -o$*.png

%.ps: %.dot
dot $*.dot -Tps -o$*.ps

%_dot.pdf: %.dot
dot $*.dot -Tpdf -o$*_dot.pdf

%_neato.pdf: %.dot
neato $*.dot -Tpdf -o$*_neato.pdf

%_circo.pdf: %.dot
circo $*.dot -Tpdf -o$*_circo.pdf

%_dia.eps: %.dia
dia $*.dia -e$*_dia.eps

%_eps.pdf: %.eps
epstopdf $*.eps -o$*_eps.pdf

%.pdf: %.tex
pdflatex $*.tex pdflatex$*.tex
pdflatex $*.tex  - So you maintain this yourself? Is 3 runs of TeX always enough (hint: no)? Does this handle bibtex-generated references? Does it recognize when changed included files necessitate rebuilds? – Novelocrat Jul 26 '10 at 21:26 add comment It does more than just compile documents, being a fully featured editor, but Kile is very good at completing all the compilation steps. You can also define your own build processes which use command line tools. By adding a ViewPDF option at the end of the compile your pdf viewer of choice will be launched (or updated) after a successful compilation. - add comment I like LatexMake. It defines a big pile of pattern rules for make to automate the most common steps of compiling a LaTeX document. Using it is a simple matter of copying one makefile into your document's directory, or include LaTeX.mk (as named in Debian's latex-make package) in a makefile you already have, or symlink to it if your makefile wouldn't need to include anything else. One really neat feature about it is that it detects dependencies on included files, and rebuilds as much of your document as needed to reflect those changes. Another neat feature is that it knows about things like bibtex, and runs the appropriate commands. - Sun Tong's LatexMake has nothing to do with Debian's latex-make package, which is INRIA's latex-utils – huitseeker Aug 10 '11 at 21:11 add comment I use scons, a python based make tool. Some documents I have contain R code, scons (with rpy2) works well in handling them. I had to program the rules for document creation by myself, but it was basically calling texify. - Does it know the appropriate rules to apply and conditions to look for, or is that logic that you have fed it? – Novelocrat Aug 4 '10 at 23:15 I also use Scons, I like that it has the rules for TeX builtin, so I don't need to care about them. On the other hand, it's somewhat complicated (for example when I want the output in a different directory). – Roman Plášil Aug 7 '10 at 20:51 @Novelocrat: Modern scons has the basic rules of LaTeX/PDFLaTeX built in, including bibtex handling, and if you want it to do something more complicated, you can program it yourself. On the other hand, the documentation is somewhat lacking. – Faheem Mitha Aug 14 '11 at 8:49 add comment Only for Windows users. Create a batch file as follows. Let's name it batch.bat. echo off rem %1 TeX input filename without extension rem %2 The number of times to invoke pdflatex in draftmode del "%~1.pdf" for /l %%x in (1,1,%2) do pdflatex --shell-escape -draftmode -interaction=batchmode "%~1.tex" pdflatex --shell-escape "%~1.tex" for %%x in (aux log out toc nav snm) do (del "%~1.%%x")  It takes 2 mandatory arguments: • %1 represents the TeX input file name without extension. • %2 represents the number of times you invoke pdflatex in draftmode. There are %2 plus one pdflatex invocations in total. Once the PDF file has been successfully generated, the auxiliary files are deleted to save more data storage, etc, etc. You can invoke the batch as follows: You can edit and insert other calls to the batch file above to meet your need. - In what way is this better than using make? – Stephan Lehmke Jan 4 at 16:57 @StephanLehmke There is no make on Windows, so it's more normal to code-you-own (see the LaTeX3 build scripts, for example, where we use make on *nix and batch files on Windows). – Joseph Wright Jan 4 at 16:58 @StephanLehmke: I cannot compare because I don't know make. :-) – Donut E. Knot Jan 4 at 16:58 @AdorableCreature It might not pay you to clean all auxiliary files immediately (as you may have errors that need correction). Rather have a second batch file that you can call it clean.bat to clear them. – Yiannis Lazarides Jan 5 at 6:08 @YiannisLazarides: I agree with you. – Donut E. Knot Jan 5 at 9:33 add comment Like @crazymaik, I’ve set up a script that runs continually in the background so the file is automatically compiled whenever I save. The idea for that originally comes from Paul Biggar. Mine uses latexmk instead of rubber (however, I use rubber-info from inside Vim to parse the log file). This has the advantage of working out of the box with TeXLive. The script is a bit longer – I think the comments sufficiently explain why this is. I’ve posted the source as a gist on GitHub. #!/bin/bash # Author: Konrad Rudolph # Original idea: Paul Biggar # # Usage: texit [--latex] target # # --latex: Use pdflatex instead of xelatex as the processor. Optional # target: The name of the target (i.e. the source file without trailing .tex) …  - add comment There is nothing wrong with Makefiles, the magic is to understand the dependency chain that exist so make don't rerun everything all the time and when he reruns he does this in the right order. How about a simple example with table of context, that is stored in a .toc file. So just add .toc as a dependency in the Makefile, that way it will run twice the first time but only once the following times. NAME=MyTestFile pdf:$(NAME).toc
pdflatex $(NAME).tex$(NAME).toc:
pdflatex -draftmode $(NAME).tex  And when it is time to to a final version make sure you do a "clean" so everything builds and links together in a correct way. Update: After reading you question (and comment), I will change my answer to. There is nothing wrong with makefiles but it is not the most optimal solution for all people in all circumstances. If you don't plan to add some command line magic in your makefile and never plan to script anything at all maybe the makefile method is unnecessary complicated. But if you plan to use LaTeX in a little bit unorthodox way and with some command line magic, a Makefile will help you a lot. - You realize Make is supposed to work based on not having to clean things out and rebuild, right? You recognize the silliness in every user constructing these rules for themself? Or do you recode LaTeX and whatever macro packages you wish to use for each new document you construct? – Novelocrat Aug 16 '10 at 0:24 I did this once, then depending on what kind of document I modify the rules slightly. And then I use my makefile to add "strange" things from the system into my document like this example (tex.stackexchange.com/questions/161/…). And sometime I integrate it into another projects, and in those cases it is actually simpler to just add a handful of rules in the "other" makefile. But it does look strange/silly if you only look at the first basic building blocks like this example. – Johan Aug 16 '10 at 5:40 One advantage of makefiles is that (once you get the hang of it) it is easy to add other targets than just for typesetting. I don't know of latexmk/rubber support such things, but I usually have targets for 'distrib', 'clean', 'draft' etc. – Taco Hoekwater Aug 16 '10 at 5:59 @Taco: Rubber has the switch "--clean" which is similar to "make clean" (except that everything is automatic – it knows what to delete based on your Latex source code and its dependencies). For more complicated things like creating a zip package ready for submission, I usually use shell scripts or Makefiles (which first invoke rubber to build everything and only after that do the packaging). – Jukka Suomela Aug 17 '10 at 10:45 add comment I use a shell script to automatically compile the file with rubber every time i save the file and my viewer automatically reloads the pdf. #!/bin/sh if [ "$#" != 2 ]; then
echo "USAGE: onsave <file> <action>"
exit 1
fi

file=$1 action=$2
last_modified="0"

while [ 1 ]
do
current=stat -c "%Y" $file if [$current -gt $last_modified ]; then $action
last_modified=$current fi sleep 2 done  - Presumably you call this as onsave %s rubber ? – András Salamon Jul 27 '10 at 21:35 Most of the time i have a Makefile, so i would just call onsave paper.tex make but if you want to call rubber instead and create a pdf onsave paper.tex "rubber --pdf paper.tex" – crazymaik Jul 28 '10 at 8:17 add comment Those makefile are always a bit difficult, in part because they have to interact with the engine to find out how many compilation runs are necessary, which additional tools need to be run etc. and these steps are usually harder than trivial with makefiles. That being said, I'd suggest you to try latex-makefile, which is a make-only solution, which goes long ways to accomplish what's needed. It's not complete, however it's better than most makefile solutions out there, tries covering all generation steps including converting images to right formats and most importantly it supports PDF(La)TeX and Xe(La)TeX out of the box now! - add comment texi2dvi, from the texinfo package, is a tool similar to MiKTeX's texify (actually, IIRC, MiKTeX has an alias to texify called texi2dvi). It is a front-end to both LaTeX and PDFLaTeX, and through environment variables you can specify extra options to either processor (and even run XeLaTeX). - add comment I posted some sample makefiles for TeX/Sweave on my site: http://cgibbons.berkeley.edu/Research/writings.html One makefile does a simple compilation, another compiles a Beamer file into presentation slides, handout slides, and a notes page. The third takes a tex file that contains questions and solutions to an exam or problem set and turns it into a plain version to pass out and a solutions set. Using some tips from the web (don't remember where), the following code only runs bibtex or reruns pdflatex if a warning is found in the log file produced by the initial pdflatex run: $(TEXFILE).pdf: $(TEXFILE).tex$(FIGURES) $(INPUTS) # Initial run pdflatex$(TEXFILE)

# Run BibTeX if missing citations
@if(grep "Citation" $(TEXFILE).log > /dev/null);\ then \ bibtex$(TEXFILE);\
pdflatex $(TEXFILE); \ fi # Recompile if instructed @if(grep "Rerun"$(TEXFILE).log > /dev/null);\
then \
pdflatex $(TEXFILE); \ fi  Note that$(TEXFILE) is the name of the tex file. Some documentation explaining the code is also available at my site. The documentation also gives code to create an emacs keybinding to save your document and run the makefile.

-

For completeness, I will mention autolatex (project page). I have not used it. It's implemented with a combination of perl scripts and makefiles.

With autolatex you can execute on the command line:

\$ autolatex -f mydoc.tex


This generates the makefiles in the current directory and makes the default targets.

-

I used a simple bash / shell script for Mac OS X / teTex to produce PDFs of various documents including my master's thesis back several years ago. It basically scans the output produced by pdflatex to see whether it needs to run the document through additional passes and also executes bibtex and makeindex.

The script was inspired by the texify.exe` program bundled with the MiKTeX package for Windows.

I'm not sure how well it works for other UNIX-like systems but at the time of initial writing it ran flawlessly on my Mac and a Linux box I tested.

Personally, this is still the solution I use when working with LaTeX documents as it just works for me, no compilation and no cumbersome installation needed, just one executable file.

However, as I haven't developed it further and didn't have the resources to test it extensively with various systems (and have no plans to develop it further), I cannot guarantee for its proper function on other systems than those that I've had at hand.

I hereby release it to the public in hope that it might still be useful for someone out there. You can find it on my user's profile page here.

-