compile-latex - compile TeX files as many times as needed
compile-latex [options] file[.tex]
compile-latex --depends|--outputs|--internals file[.tex]
compile-latex [--makefile-prefix prefix] --makefile makefile file[.tex]
A few short options are provided. They can be agregated (such as
-MI), but only the last one may have a value.
--jobname|-j job Use this jobname. Can be repeated to loop through several jobnames. Not persistent.
--variant compilation chain name Changes the compilation chain (see "COMPILATION CHAINS").
--debug n Change the verbosity level to n (see "DEBUG"). Not persistent.
--quiet Same as
--manual Removes automatic mode.
--discover (default) Automatic discovery mode. Currently, finds all bibtex-able files and add appropriate actions to deal with them. Also adds the idx/ind index action (only if no other index option is given).
--load-all|-l Load options from command line, input file and hash file(s).
--load-old Load options from command line and hash file(s).
--load-input Load options from command line and input file.
--load-none|-L Load options from command line only.
--bibtex-file somefile Marks some file to be an input for
bibtex. Can be given multiple times. Discovery mode will probably
spot all bibtex-able files anyway, so mostly useful in manual
--bibtex-file-suffix string Same as above, except it uses
--bibtex Equivalent to --bibtex-file file.aux.
--index-file somefile Marks some file to be an input for
makeindex. Can be given multiple times.
--index-file-suffix|-i extension The same as above, but for the file file.extension.
Each of the following option applies to the preceding
--index-style somefile Corresponds to option -t of makeindex.
--index-output somefile Corresponds to option -t of makeindex.
--index-output-suffix|-o extension The same as above, but for the file file.extension.
--index-options string Corresponds to other options of makeindex, separated by spaces, see "QUOTING".
All of these options are not persistent.
--depends List local files read by compilation and not overwritten
--internals List local files both output and read by compilation
--outputs List local files output by compilation, but not read
--makefile file.mk Outputs a makefile snippet included in file.mk. The sections are self-delimited and replaced if already present (see "MAKEFILE").
--make|-M Same as
--makefile-prefix Prepend a common prefix to all phony targets of the makefile generated by the --makefile option.
--separator string Use this quoted string as separator between names instead of one space (see "QUOTING").
--ignore|-I Autoignore mode. Select first CVS and use it.
./.gitignore to ignore output and internals files.
--svnignore Edit property
svn:ignore to ignore output and internals files.
--noignore No ignore generation.
--help|-h Generate this help (long version).
--usage Generate this help (short version).
--man Generate man page.
--nroff Generate man page in NROFF format.
--variant pdflatex (default)
latex file.tex;dvips file.dvi
xelatex file.tex;xdvipdfmx file.xdv
compile-latex is a program that compiles a TeX file until it reaches a fixed point. The program assumes that if all the inputs of a program are the same, then not repeating this program is acceptable; and if any input of a program changes, then the program is rerun.
compile-latex also manages makeindex. It supports the use of the
index packages for multiple indexes; however, the
automatic mode only uses the
.ind standard index.
compile-latex also manages bibtex and any combination of packages that use only bibtex as an auxiliary program.
compile-latex remembers from one compilation to another the index options it was given. It is not necessary to repeat them (not harmful either).
compile-latex uses strace to determine the files accessed by a program.
Options may come from:
- the command line
- previous invocations (if --load-all or --load-old is used)
- the file itself in specially formatted comments (if --load-all or --load-input is used)
Most options are persistent: they will be stored in the hashfile and
remembered on subsequent calls. However, if one category of options is
given in two different sources, the first one takes precedence. For
example, if the command line indicates
--index-file-suffix adx and
the last invocation was
--index-file-suffix idx, only one index
.adx will be processed (options are not merged).
The --load-* options can be used to select which sources are considered. Of course, jobnames cannot be read from the hashfile (they have to be already known at this point).
Comment lines in the input file formatted as follows: one or more
percent char, zero or more spaces, the string
compile-latex, one or
more spaces, the string
"option", zero or more spaces, the string
":" and one option (without any excess spaces), will be considered as
an option. These options will not be stored for later invocations, since
they are in the file anyway.
Another format for in-file options is as follows: one or more percent
char, zero or more spaces, the string
compile-latex, one or more
spaces, the string
"options" (remark the plural), zero or more
spaces, the string
":" and options separated by spaces (spaces at the
end or the beginning will be removed). The options can embed spaces;
they will be quoted (see "QUOTING") (thus, do not forget to quote
the other chars if you ever need them).
Each option expects a single argument. Some may require spaces to
separate various parts (e.g. --index-options). If one part needs
spaces (a filename, for example), use
%20 for the space inside the
%25 for a litteral
%3B for a
should almost never be necessary.
It is difficult to build generic Makefile snippets that satisfy everyone. The current choice is to build some phony targets: all, do, clean, distclean, depends and depends-as-is. all, do and depends will rebuild the targets with the same options that were used when building the makefile (using --load-none); depends-as-is will not use --load-none, thus using the currently selected options. do is phony and will always rebuild all files. all will rebuild all files that are not up-to-date (it means older than their dependencies, or not existent). depends will do the same as do, and rebuild the Makefile (and possibly ignore files). clean and distclean remove the files (except for the main output with clean).
To avoid interacting with other targets in the Makefile, all these targets can be prefixed by some chosen prefix using --makefile-prefix.
Debug level varies from 0 (silent, except for results of --depends or like options) to 7 (very verbose).
The default level is 1 and will print all time consuming operations.
Level 2 will print changed files before launching time consuming operations.
Level 3 will print all operations even skipped ones.
Level 5 will print changed checksums.
file.tex as many times as necessary, processing index
and bibtex files as many times as necessary too (sometimes, bibtex index
have to be processed several times because of cross-references).
compile-latex file.tex --manual --index-file-suffix adx \ --index-output-suffix and \ --index-options '-g -t /tmp/log%20indexation' \ --index-file-suffix odx --index-output-suffix ond --bibtex
file.tex and do some special treatment for auxiliary
programs. First, normal index
file.idx will not be processed, as well
as support for
bibtex is removed. However, two index files ending in
.odx (coming from the
multind package for example)
will be processed to
file.and and the second one to
first being indexed with the
-t /tmp/log indexation (remark the space in the filename).
Generation of pictures by other programs is not supposed to be done by
compile-latex, unless the document uses
write18 to generate the
images (in which case, compile-latex will happily rerun the generation).
Makefile and gitignore options create files not safe to be invoked outside their own directory. Files with weird names may cause problems (especially since GNUmake does not support filenames with spaces).
Copyright Jean-Christophe Dubacq 2012
This work is licensed under the BSD licence. It is explicitly stated here that the license does not extend to the data managed by the program, in case anyone had doubts.