10 An example Makefile

In this chapter a makefile will be presented which simplifies the task of calling all the scripts in the right order and keeps track of dependencies between source and documentation files. For the sake of simplicity, the makefile used to build this documentation will be shown:

Listing 9: Makefile

dvi   : tutorial.dvi
ps    : tutorial.ps
pdf   : tutorial.pdf
html  : tutorial/tutorial.html
out   : example
clean : 
        rm -rf *.dvi *.ps *.pdf *.log *.aux *.idx *~ part1.tex tutorial.tex \
               *pk *.out _pdweave.tmp _pd_html.html tutorial

tutorial.dvi : tutorial.tex part1.tex

tutorial.pdf : tutorial.tex part1.tex progdoc.pdf

progdoc.pdf : progdoc.eps
        epstopdf progdoc.eps

part1.tex    :  ClassDefs.h test.xml test.py version.el

example : example.cpp ClassDefs.h
        g++ -o example example.cpp

tutorial/tutorial.html: tutorial.dvi
        latex2html -html_version 4.0 -show_section_numbers -image_type gif \
                -up_title "ProgDoc Home Page" -up_url "../progdoc.htm"  \
                -no_footnode -local_icons -numbered_footnotes tutorial.tex

# We generate ps from pdf now in order to depend only on pdfLaTeX!
# %.ps  : %.dvi
#        dvips -D 600 -o $@ $< 

%.ps  : %.pdf
        acroread -toPostScript -binary $< 

%.dvi : %.tex
        latex $< && latex $<

%.pdf : %.tex
        rm -f $*.aux && pdflatex $< && pdflatex $<

%.tex : %.pd
        pdweave $< 

Of course this file can be included with the \sourceinput command as well. Because syntax highlighting for makefiles is not supported yet, the file was included by using the type option set to text. But even in this case, there are still benefits in using the \sourceinput command. First of all, the documentation will always contain the actual makefile. Second, this makefile can be referenced throughout the documentation like every other source file (see Listing 9). And last but not least, ProgDoc may be extended in the future to highlight various other file formats, so you may improve your documentation by simply rebuilding it with a new version of ProgDoc.

Now lets have a closer look on the makefile. The first five lines define shortcuts for the different targets, namely the dvi, ps, pdf and html versions of the documentation and the example executable. clean, the last target removes all files created during a build process. Notice that '_pdweave.tmp' and '_pd_html.html are temporary files created by pdweave.

In the next lines, the dependencies are defined. The dvi output depends on the tex files of the documentation which in turn depend on the source code of the files they document. Therefore the documentation will be rebuild not only if the documentation source files will change, but also if the source code files change.

The next two rules tell make utility how to build the example executable and the html version of the documentation. The latter will be created by L^ATEX2HTMLin its own subdirectory.

The last four parts of the makefile contain generic actions which tell the make utility how to generate '.ps' files out of '.dvi' files, '.dvi' files out of '.tex', '.pdf' files out of '.tex' files and finally '.tex' files out of .pd-files. As you can see, for the last step the pdweave utility will be used.

Using this example as skeleton, it should be straightforward how to write makefiles for your own projects.