Free LaTeX Tools

The LaTeX Makefile

During my sojourn through academia, I have had cause to spend a lot of quality time with LaTeX. Unfortunately, this often meant that I spent less time with my wife and children (though I would have spent far more time trying to coerce Word into doing what I needed). LaTeX, wonderful and beautiful though it is, has issues when it comes to its use on the command line: building a document, especially a complex document, is not necessarily the easiest thing in the world to do correctly and efficiently.

For many, LaTeX's quirks in this regard are not an issue. They write a couple of pages, stick in a couple of graphics, and do the following little dance:

    > latex myfile
    > bibtex myfile
    > latex myfile
    > latex myfile
    > dvips -o myfile.ps myfile.dvi
    > ps2pdf myfile.ps myfile.pdf

Additionally, many documents built with LaTeX have dependencies that would be better tracked by the computer than the document author, like graphics or a bibliography database, which made me think, ``Why not create a GNU make file?'' So, I did. You may obtain it from its project page at Google. You can submit bug reports or request permission to hack on it through that site.

Version 1.0 is the makefile that I have used during most of my research and has been developed over the course of several years. It is not, however, something that I would recommend that anybody actually use, but can be found here in case someone is already using it and wants to download it again. It is poorly documented, has weird file name requirements, and just isn't as useful and cool as version 2.0.

LaTeX Makefile 2.x Feature Summary

When creating a document, simply take the file ``Makefile'' and drop it into the same directory. Then run ``make''. It should really be that simple most of the time. There are some requirements for complex documents that should be met if you want everything to go smoothly, but they are very easy requirements to meet. Here are the basic features of the makefile:

Dependency tracking

LaTeX files can include other files, input other files directly, and often depend on graphics and bibliography database files. The makefile discovers all of these dependencies on the fly and therefore knows what should be rebuilt when any of these dependencies change.

Graphics from Data

When doing research, it is common to include graphs in your paper. There is no better tool for generating these graphs than gnuplot, which has a postscript output option. Because these graphs and their data change all the time during the course of a paper, automating the generation of appropriate .eps files is important, and the makefile does this. If it sees, for example, that it needs mygraph.eps and only has mygraph.gpi, it will take steps to build mygraph.eps from the gnuplot file. It does this for other formats, as well, like XFig and GraphViz. Currently supported are the following:

• .gpi: Gnuplot
• .fig: XFig
• .dot: GraphViz
• .eps.gz: GZipped postscript

Of course, if the needed .eps file already exists, it will simply use it.

Better Error Output

LaTeX produces way more output than you, the author, need to see. Because of the mountain of output that it produces, it can be difficult to see important information, like information about the number of pages produced, overfull hbox warnings, large float problems, cross reference relocation issues, or even fatal LaTeX errors due to mismatched braces and the like. The makefile swallows all of LaTeX's output unless there is something useful to say, and it only says it once. It also says it in customizable color!

Creation of Common Target Formats

The default output of the makefile is a PDF document. It can also, however, just build a DVI or Postscript document upon request. When needed, you can also instruct it to just build the .bbl file or any of the graphics files that are needed by the document.

Grayscale Output

Usually you want to create your documents in full color, only moving to grayscale for printing. While in many cases this is most easily achieved by leaving the document in its native colors and relying on the printer to convert them to grayscale, this is not always a good idea. Gnuplot, for example, generates different line styles depending on whether it is outputting color or monochrome postscript; the monochrome version is more readable in a grayscale context because it does not rely on color for plot line differentiation. The makefile provides special grayscale compilation features that allow you to build both color and grayscale documents from the same source without any changes and without clobbering previous builds.

Font Embedding

Many conferences and journals prefer that you embed your fonts within the document. This does that automatically unless you specifically tell it not to.

Beamer Output

Beamer, an excellent presentation class for LaTeX, generates very tiny pages that get enlarged on a screen without problem. Printing slides, however, is not as easy as it should be. You generally get a tiny little slide on a largely blank page. A special comment at the top of your source file will enlarge the beamer output to take up an entire page. You can then safely print multiple slides per page by using other tools like a2ps.

Embedded Documentation and Tools

The makefile contains complete documentation within it. Simply run

    > make help | more

(or less) and you will have more help than you ever knew you wanted about how to use the makefile. One especially helpful target documented there is _check_programs, which tests your system for all of the programs on which the makefile relies. Try it, it's pretty neat and very helpful. In fact, the built-in help is far more complete than this web site.

Scripted Source Files

Just in case there is something wacky that I haven't thought of, you can drop a script in the directory that generates a .tex file. If you specify that you want a document built and there is no .tex file, but there is a .tex.sh file, it will run the script to generate the needed source, then build it. This is a highly flexible feature, since the .tex file is the very first thing built. You can generate all kinds of things in that script and the makefile will pick them up in the same run (provided that the generated source document is dependent on them).

ReStructured Text

You can now drop a .rst file into the directory and it will create a .tex document and build it for you, all automatically. I've been fiddling with reST a lot lately, and it's been very handy to have reST handling built into the makefile.

BYU MS/PhD LaTeX Class

Writing a Master's thesis or PhD dissertation is not necessarily an easy task, and this is definitely the case at Brigham Young University's CS Department. The requirements are fairly strict and can be hard to get right in LaTeX. Furthermore, once you have satisfied the minimum requirements, it's hard to create documents that actually look good. Finally, the requirements are not verified on your computer screen, but on a printed document, and every printer is different.

The BYU MS/PhD LaTeX Class (also linked from the sidebar) makes it easier to create a compliant document that looks good and it provides means for you to verify whether the margins and spacing are correct. Simply use it as your document class and set appropriate options. Full documentation is included in the form of an example .tex file that you can compile and view. The makefile I wrote makes a nice companion to the class file.

Even if you don't go to school at BYU, the class file may provide a nice starting point for your own school's requirements. It is heavily commented, uses a minimum of deep TeX magic to do its work, and is straightforward to modify.