1. LatexMake

1.1. Basic Info

1.1.1. Synopsis

1.1.2. Info

This is a generic makefile to create output from a Latex file.

It will run the designated LaTeX file through TeX in turn until all references (including BibTeX) are resolved, and all indexes are built.

It can also generate .pdf, .html, .txt or .rtf files.

Tags: TeX LaTeX BibTeX CJK automate build compile generate multi-invocation ps pdf html text .txt rtf book reference cross-reference table of content index gnu make makefile texi2dvi

1.1.3. Source

1.1.4. Features

This makefile is not merely a make file, it is total solution for your LaTex file processing.

1.1.5. Installation

Install the package anywhere you want. Copy or symbol-link the 'Makefile' and 'target.mk' files into the directory of your tex source file.

1.1.6. Description

This makefile is driven/customized by environment variables. The most important environment variables is 'TEX_SOURCE_BASE', which is the base name of your tex source file (without the .tex extension). The benefit of setting this variable is that you can clean all the generated files easily using 'make clean' or 'make cleangen'.

You can use 'make check' to show the current setting, or let the makefile make recommendations for the setting. 'make check' will:

The recommendation is made in both sh or csh format, just to save you from some typing. That's all the environment variables you need to know if you are in a hurry. However, it is strongly recommended to build your target into a separated directory, which is controlled by environment variable TEX_DEST_DIR. Set it to where you want for generated files to be store. It does not have to be exist. The makefile will create one if it does not. Setting TEX_DEST_DIR is mandatory if you want to build an HTML (or .txt) version from the .tex file. The default is current directory.

The general procedure when building your tex file would be, run 'make view' over and over, to build the .dvi file and view it, until you are fully satisfied with the result. I.e., 'make view' will make the .dvi file, then launch the dvi viewer to show you the result.

You can also leave the dvi viewer on, and run 'make' repeatedly, to build the .dvi file. Merely invoking 'make' will only make .dvi file. The dvi viewer can pick up the changes right after the build automatically. Finally, use 'make ps', 'make all', or 'make ps pdf html' to generate the files that you want in specific formats.

For online help, type 'make help'. Note, if you use the -f parameter to change the default name/location of the Makefile, you need to set the environment var MAKEFILE for 'make help' to work.

1.2. Similar Tools

In order to resolve cross-references, or build all indexes, the latex command has to be ran many times. Various efforts has been attempted to automate this procedure, but all I that tried failed to produce satisfying results.

The problem with the aforementioned approaches is, no matter how versatile they are, I found that they are not sufficient enough for my thesis preparation, which was not terribly complicated, and should be much simpler than other complicated tasks such as book preparation and publishing. Another slightly complicated example, it needs 10 runs to get everything OK for the apacite package, and this is only a package document, not a book. The only solution that might work is to fully analysis the tex output, not to play with the dependencies alone.

I found the multi-invocation of latex command has been solved nicely with texi2dvi command, which runs the designated LaTeX file through TeX in turn until all cross-references are resolved, building all indexes.

Hence, the goal of this package is to find the best solution, then provide the require dependencies for make so that the target can be generated automatically. No other extra prerequisites, hacking or processing are involved unless strictly required. However, in order for the generate-into-alternative-directory feature to work, GNU make is required.

1.2.1. Stefan's makefile

Stefan's makefile is a big make file, over 300 lines long. The good part is that it utilize make to solve dependencies, the bad part is that it still relies heavily on bash/zsh scripts to hack its own solution for latex multi-invocation problem. Other than that, it is nice tool. I "borrow" many of the cool ideas from it into my makefile, and removed the dependencies on bash/zsh.

1.2.2. CTAN latexmk

latexmk, is a Perl script that monitor all your changes (almost). It monitors included files, whether the aux, idx has changed. It also supports bibtex. It can run on both Linux and Windows. However, it required Perl to be installed before you can use it. More over, it is not a make file. It is basically a Perl script that tries to do what texi2dvi does.

1.2.3. LaTeX-Mk

LaTeX-Mk http://latex-mk.sourceforge.net/ it is a *collection* of *makefile fragments* and *shell scripts*

I haven't try it, but from its documents, it seems to rely on the ".old" files to hack its own dependencies/re-compilation solution, which I found very hard to achieve. Moreover, it seems to need 'bmake' for it to work. I haven't heard of bmake.

1.2.4. Rubber

http://xpt.sourceforge.net/techdocs/language/latex/latex06-MakefileForTeX/ar01s02.html or http://rubber.sourceforge.net/

1.3. LatexMake in details

1.3.1. To clean up

make clean-bak # clean all backups of source files
make clean     # clean generated files
make clean-gen # clean all generated ps/pdf related files
make clean-th  # clean all generated text/html related files
make clean-all # wipe out TEX_DEST_DIR directory entirely

1.3.2. Trouble shooting

If you suspect something is wrong with the making process (tex compiling), e.g., the latest update is not reflected in the compiled file, or some weird error can't be fixed, Try

TEX_DEST_DIR=. make view

to compile in the current directory first. This will eliminate all possible problems related with the approach of compiling latex into another directory. Only after all the tex/compiling problem solved, should you resume your normal making (compiling to the destination directory).

If somehow some extreme weird error occurs, e.g., compiling to the current directory works but compiling to the destination directory fails, it will always help to do from a fresh start. I.e., use 'make clean' to wipe out any temporary/incorrect intermediate files.

I found it is a good practice to keep a error free latex source file. I.e., build often, and build whenever you try something that you are not sure. Having a error free latex source file will save you lot of headaches troubleshooting. When everything else failed, you can always invoke latex manually and see what is exactly went wrong.

Note that you can always use

TEX_DEST_DIR=. make clean

to clear your source directory from any generated files.

1.3.3. Advanced usage

The values of the LATEX (or PDFLATEX), DVIPS, LATEX2RTF, HTML2TEXT, DVIVIEWER, PSVIEWER and PDFVIEWER environment variables are used to run those commands, if they are set. For example, to generate ps file in landscape mode, do:

export DVIPS='dvips -t landscape'
export PDFLATEX='dvipdfm -p letter -l'

All tools used in this Makefile are well-known tools. They can all be easily located on the web using any search engines. Most of them may have already been included in your *nix distribution.

1.3.4. Coin you own make rules

If this make file is not enough for you, you can create you own build rules. The following make files will be automatically picked up and used:


1.3.5. Support

Please visit the xpt tools support page.

1.4. About This Release Note File

Revision: 1.1 (for latexmake-2.0 release) - Date: 2003/04/19 15:20:38

Since latexmake-2.0 public release, this Makefile has evolved from revision 1.4 to revision 1.18, bug fixing, and fine tuning to make it work as expected as much as possible.

Version: $Revision: 1.3 $
Last update: $Date: 2006/10/12 18:27:32 $