## 1. LatexMake

### 1.1. Basic Info

#### 1.1.1. Synopsis

`make help`
• to prepare or show the current setting

`make check`
• to build the .dvi file

`make`
• to build the .dvi file then launch the dvi viewer to show the result

`make view`
• to build the .ps file

`make ps`
• to build the .ps file then launch the .ps viewer to show the result

`make view-ps`
• to build the .pdf file and/or launch the .pdf viewer to show the result

```make pdf
make view-pdf```
• to build the many target at once

`make all`

or

`make ps pdf html`

to generate the files that you want in specific formats.

• use 'hevea' to build the html files

`LM_USE_HEVEA=T make html`
• to build the .rft file need a special syntax, due to the limitation of the latex to rtf compiler.

`_MAKE_TARGET=T make rtf`
• to clean all the generated files

`make clean`

or

`make cleangen`

#### 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.4. Features

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

• Unlike all other similar tools, it make use of the existing state-of-art tools to achieve its goal, instead of hacking its own solution. For details, please refer to the Similar Tools section.

• You need nothing more than the common LaTex compiling tools for it to work. The gnu make and this makefile drives all the compiling and building. No other language/tool packages are required. The total solution is less than 20K, including documents.

• This is a one-stop solution. All common file formats can be generated from your single LaTex source, using this makefile, provided that the selected building tool is installed in your system. You have the options to choose between the tools and even to choose the tools of your own too.

• What's unique in this solution is that it can generate files into another (target) directory. Your tex source directory will no longer be littered with built or intermediate files. It will be always clean and ready for backup. Thus, the backup would be 5 to 8 times smaller than including the built and intermediate files.

• It is designed to solve "complicated" task nicely, e.g., you have cross-references, BibTeX, table of content, index, and multi-level of \input, \include, or \includeonly in your tex source files.

• It supports CJK Latex files compiling.

• It also work well when the main tex file is a symbol-link, of which modification time does not change to reflect your latest modification.

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

• check if there is only one .tex file, then recommends that one.

• Otherwise, recommends the basename of the directory. For example, if the directory is named "Thesis", then "Thesis" is recommended.

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

• written entierly in the Python

• need at least Python version 2.3 to function

• producing PDF is an "extra" feature

• don't know if it can produce html, text, and rtf files.

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

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:

`makefile.*.mk`

#### 1.3.5. Support

Please visit the xpt tools support page.

```Version: \$Revision: 1.3 \$