Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Utility to compile TeX files as many times as needed with index and bibliography support based on strace
Perl TeX
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
src
tests
Makefile
README.md

README.md

NAME

compile-latex - compile TeX files as many times as needed

SYNOPSIS

compile-latex [options] file[.tex]

compile-latex --depends|--outputs|--internals file[.tex]

compile-latex [--makefile-prefix prefix] --makefile makefile file[.tex]

compile-latex --help|--man|--nroff|--usage

OPTIONS

SHORT OPTIONS

A few short options are provided. They can be agregated (such as -MI), but only the last one may have a value.

GENERIC OPTIONS

--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 --debug 0.

--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 OPTIONS

--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 mode. Persistent.

--bibtex-file-suffix string Same as above, except it uses jobname.string.

--bibtex Equivalent to --bibtex-file file.aux.

INDEX OPTIONS

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

--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".

DEPENDENCY OPTIONS

All of these options are not persistent.

--depends List local files read by compilation and not overwritten (.tex, .cls,...)

--internals List local files both output and read by compilation (.aux...)

--outputs List local files output by compilation, but not read (.log...).

--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 Makefile.

--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 Edit ./.gitignore to ignore output and internals files.

--svnignore Edit property svn:ignore to ignore output and internals files.

--noignore No ignore generation.

HELP OPTIONS

--help|-h Generate this help (long version).

--usage Generate this help (short version).

--man Generate man page.

--nroff Generate man page in NROFF format.

COMPILATION CHAINS

--variant pdflatex (default) pdflatex file.tex

--variant dvips|latex+dvips latex file.tex;dvips file.dvi

--variant xelatex xelatex file.tex;xdvipdfmx file.xdv

--variant lualatex lualatex file.tex

DESCRIPTION

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 multind and index packages for multiple indexes; however, the automatic mode only uses the .idx to .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.

GIVING OPTIONS

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 ending in .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).

QUOTING

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 part. Use %25 for a litteral % and %3B for a ;. Quoting should almost never be necessary.

MAKEFILE

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

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.

EXAMPLES

compile-latex file.tex

will compile 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

will compile 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 .adx and .odx (coming from the multind package for example) will be processed to file.and and the second one to file.ond, the first being indexed with the makeindex options -g and -t /tmp/log indexation (remark the space in the filename).

BUGS

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

AUTHOR

Copyright Jean-Christophe Dubacq 2012

COPYING

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.

Something went wrong with that request. Please try again.