makelatex - a LaTeX Makefile generator

Précis

makelatex is a script used to generate a Makefile that describes the dependencies between LaTeX documents. This can be particularly useful with large projects where content is split across multiple files and where included graphics require a step of translation (for example from .fig to .eepic).

Document structure mapped to files

For any sizable LaTeX report, it is sensible to divide your writing into multiple files held in multiple directories. For example: consider the following directory structure:

    
    main.tex
    introduction.tex
    background.tex
    conclusion.tex

Our report is quite large, containing three chapters: introduction, background and conclusion. Therefore, to avoid editing one long LaTeX file (mixing our content, macro definitions etc.) we split the document into introduction, background and conclusion files, one file per chapter. Often you will find that a natural divide can be found by splitting a document by chapter or section; this is the case in our example. Of course, the division into files is entirely arbitrary and need not follow such rules or guidelines.

Our document will, of course, be including some graphics and diagrams. Rather than store every graphics file in the base directory, it would make sense to group them according to the rules used when dividing the underlying document above. Hence, we create subdirectories for each chapter of our report:

    
    main.tex
    introduction/introduction.tex
    introduction/test.eps
    background/background.tex
    background/digram1.eepic
    conclusion/conclusion.tex
    conclusion/foo.eps

It's not particularly tidy to leave .tex and graphics files cluttered in the same directory (especially when you have many graphics files) so we make one further refinement by creating figures subdirectires in each of the chapter directories:

    
    main.tex
    introduction/introduction.tex
    introduction/figures/test.eps
    background/background.tex
    background/figures/digram1.eepic
    conclusion/conclusion.tex
    conclusion/figures/foo.eps

In accordance with the UK TeX FAQ, we include chapter files into the root LaTeX document (main.tex, the file on which we run latex to typeset our document) using \include or \input commands. So, our main.tex might look something like the following:

    
    \documentclass{report}

    \begin{document}

    \include{introduction/introduction}
    \include{background/background}
    \include{conclusion/conclusion}

    \end{document}

See my pages on how to include vector graphics into LaTeX documents for examples of how one might include graphics.

`makelatex`

make is a tool which controls the generation of executables and other non-source files of a program/target from source files. It is particularly well suited for use with LaTeX, but only when provided with a list of the dependencies between the root document (main.tex) and included files. Only then can make correctly cause a 'rebuild' of your report when source files change (including image files requiring a translation, i.e. fig formats requiring translation to the eepic format).

Calculating these dependencies is not within the remit of make. I wrote an ancillary script, called makelatex, to calculate the dependencies and subsequently generate a Makefile.

The script is very hacky Perl but it does the trick for my simple needs. Place the following two files somewhere in your path:

Invocation

    
    $ makelatex [root_tex_file.tex] [make_arg1 make_arg2 ...]

The first argument, as indicated, is optional. The root .tex file is only required in the case that multiple root LaTeX files exist in the current directory. If omitted, makelatex chooses the single .tex file, complaining if either no such file exists or if there is some ambiguity. Arguments to make follow and are also optional.

This invocation generates a Makefile in the current directory and immediately invokes make passing the optional make_arg* parameters. Unless your project is huge, the time taken to run texdep (invoked from within makelatex) is small. Therefore, running makelatex in place of make, even if dependencies haven't changed, will not represent a massive performance hit.

Example

Grab the example file:

makelatex_example.tar.gz

Following these instructions:

Download makelatex and texdep (see above) and ensure they are in your path.
Ensure you have fig2dev installed (otherwise comment out the figure inclusion in background/background.tex).
Unpack the example files; this will create a directory called makelatex_example.

Change to this newly created directory and type:

    
    $ makelatex

If all goes well, you should find three files, corresponding to the generated report: main.ps, main.pdf and main.ps.gz.

Some points to note

The BibTeX check (for unresolved citations) tests for errors as output by the natbib package.
The list of file extensions the script considers expendable (i.e. those that will be cleaned in a call to make clean is extensive. CHECK texdep BEFORE PROCEEDING.
Only eepic graphic files (possibly generated from fig code) are catered for in the "image files" section.

Please contact me with improvements or suggestions.