manual/LaTeX.Rules

   1 #
   2 # Makefile for the automation of LaTeX document processing
   3 #
   4 # Usage:  make [target]
   5 # The following targets are understood:
   6 #       dvi             generate dvi output (latex default target)
   7 #       pdf             generate pdf output (pdflatex default target)
   8 #       ps              generate postscript
   9 #       clean           erase all intermediate files
  10 #       realclean       erase all but the source files
  11 #
  12 # To do:
  13 #       -recursively process \include{} and \input{} commands for .tex
  14 #       dependancies
  15 #       -do the same for \bibliography{} commands
  16 #       -add metapost processing
  17 #
  18
  19 #
  20 # Document information (provided by top-level Makefile)
  21 #
  22 # LATEX
  23 #       The name of the latex compiler to use.  If the program name is,
  24 #       specifically, "pdflatex" then the .pdf will be the default target
  25 #       rather than the .dvi.  Note that at present there is no way to ask
  26 #       for one or the other without switching the contents of this
  27 #       variable.
  28 #
  29 # DOCUMENT
  30 #       (required) The root name for all files.
  31 #
  32 # GRAPHIC_FILES
  33 #       Any graphic files the document depends on, for example any .eps or
  34 #       .pdf files included with \includegraphics{}.  The output is rebuilt
  35 #       if any of these files change but otherwise they play no role in the
  36 #       build process.
  37 #
  38 # XFIG_FILES
  39 #       Thes Makefile rules allow your LaTeX document to include xfig .fig
  40 #       files directly.  Each .fig file is converted to a graphic format
  41 #       suitable for inclusion by the LaTeX processor, for example
  42 #       postscript or pdf.  This is accomplished by processing the .fig
  43 #       file with fig2dev and producing two output files:  a graphics
  44 #       version of the .fig file and a LaTeX source file containing the
  45 #       commands needed to import that graphics file.  In your own LaTeX
  46 #       document, you will need to include this .tex source file.  For
  47 #       example, if you have an xfig file called diagram.fig, you should
  48 #       set "XFIG_FILES = diagram.fig" in your Makefile and place the
  49 #       command "\include{diagram.fig}" in your LaTeX document where you
  50 #       would like the image placed.  When your document is processed, the
  51 #       xfig file will be converted to a, for example, postscript file
  52 #       called diagram.fig.ps and a LaTeX source file called
  53 #       diagram.fig.tex.  The \include{} command in your LaTeX source reads
  54 #       in the .fig.tex file (the .tex extension is assumed by the command)
  55 #       which in turn contains the commands to import the graphics file.
  56 #
  57 #       As an added bonus, any text objects in the xfig document that have
  58 #       their "special" flag set will be removed from the document before
  59 #       it is converted to a graphics format.  Their contents are added to
  60 #       the LaTeX source file along with the commands needed to overlay
  61 #       them in the correct places on the figure.  In this way, you can use
  62 #       LaTeX to typset the text of your xfig figure.  This has the
  63 #       advantage of having the text rendered in the same font as the rest
  64 #       of your document and also allows you to make use of all of LaTeX's
  65 #       typsetting facilities.  Note that in your xfig document you should
  66 #       set the pen colour of the "special" text to "Default" in order to
  67 #       prevent \color commands from being issued, otherwise you will need
  68 #       to include the LaTeX package "color".
  69 #
  70 #       If you get error messages about "unknown graphics format" related
  71 #       to the .fig.ps or .fig.pdf intermediate graphics file then you must
  72 #       issue the \DeclareGraphicsRule{.fig.ps}{eps}{.fig.ps}{} command or
  73 #       the \DeclareGraphicsRule{.fig.pdf}{pdf}{.fig.pdf}{} command in your
  74 #       document's preamble.  See the grfguide.ps graphics package
  75 #       documentation for more information.
  76 #
  77 # BIB_FILES
  78 #       $(DOCUMENT).tex will be automatically searched for all .bib files
  79 #       specified via \bibliography{} commands.  Use this variable to
  80 #       override the automatic search and manually specify the .bib files.
  81 #       Reasons for wanting to override the automatics:  (i) scanning a
  82 #       large document can be time-consuming and can be skipped by entering
  83 #       the info yourself (ii) the algorithm may be broken for your
  84 #       document.
  85 #
  86 # BSTINPUTS
  87 # BIBINPUTS
  88 #       The contents of these variables override the system default search
  89 #       paths for bibtex.  If you are using a custom bibliographic style,
  90 #       you may need to set BSTINPUTS to the directory in which the .bst
  91 #       file resides.  If your .bib databases cannot be found, then you
  92 #       will need to set BIBINPUTS to a colon-separated list of the
  93 #       directories in which they reside.
  94 #
  95 # DVIPS_FLAGS
  96 #       Flags to pass to dvips.  It might be necessary to include the -K
  97 #       flag if you are having trouble getting mpage to handle documents
  98 #       that contain EPS figures generated by certain applications.
  99 #
 100
 101
 102 ###############################################################################
 103 #
 104 #                                   Preamble
 105 #
 106 ###############################################################################
 107
 108 DVI_FILE  := $(DOCUMENT).dvi
 109 PDF_FILE  := $(DOCUMENT).pdf
 110 PS_FILE   := $(DOCUMENT).ps
 111 AUX_FILE  := $(DOCUMENT).aux
 112 LOF_FILE  := $(shell ls $(DOCUMENT).lof 2>/dev/null)
 113 LOT_FILE  := $(shell ls $(DOCUMENT).lot 2>/dev/null)
 114 TOC_FILE  := $(shell ls $(DOCUMENT).toc 2>/dev/null)
 115 IDX_FILE  := $(shell ls $(DOCUMENT).idx 2>/dev/null)
 116 END_FILE  := $(shell ls $(DOCUMENT).end 2>/dev/null)
 117 TEX_FILES := $(DOCUMENT).tex
 118 OTHER_FILES := $(DOCUMENT).blg $(DOCUMENT).log $(DOCUMENT).out
 119 INDEX_ARGS := -s mkidx.ist
 120 LATEXOPTS := -interaction=nonstopmode
 121
 122 # program to pipe stdout through. Note: this needs to start with a pipe symbol
 123 # to not make the command fail if no filter is defined.
 124 ifndef V
 125 LATEXFILTER := | ./latexfilter.pl
 126 else
 127 LATEXFILTER := | ./latexfilter.pl -v
 128 endif
 129
 130 # grab the contents of \bibliograph{} commands
 131 ifeq ($(BIB_FILES),)
 132         BIB_FILES := $(shell for source in $(TEX_FILES) ; do sed -e '{' -e 'y/,/ /' -e 's?.*\\bibliography[{]\(.*\)[}].*?\1?' -e 't' -e 'd' -e '}' <$$source ; done)
 133         BIB_FILES := $(BIB_FILES:%=%.bib)
 134 endif
 135
 136 ifneq ($(BIB_FILES),)
 137         BBL_FILE := $(DOCUMENT).bbl
 138 endif
 139 ifneq ($(IDX_FILE),)
 140         IND_FILE := $(DOCUMENT).ind
 141 endif
 142
 143 # construct the names of auxiliary files related to xfig documents
 144 XFIG_AUX = $(strip $(XFIG_FILES:%.fig=%.fig.aux))
 145 XFIG_GFX = $(strip $(XFIG_FILES:%.fig=%.fig.pdf) $(XFIG_FILES:%.fig=%.fig.ps))
 146 XFIG_TEX = $(strip $(XFIG_FILES:%.fig=%.fig.tex))
 147
 148 # latex will be run over and over and over again until the following files
 149 # stop changing.
 150 MONITOR_FILES := $(strip $(AUX_FILE) $(TOC_FILE) $(LOF_FILE) $(LOT_FILE) $(BBL_FILE) $(IND_FILE) $(END_FILE))
 151
 152 # the following files must be present or processing will fail
 153 SOURCE_FILES := $(TEX_FILES) $(BIB_FILES) $(GRAPHIC_FILES) $(XFIG_FILES)
 154
 155
 156 ###############################################################################
 157 #
 158 #                                    Targets
 159 #
 160 ###############################################################################
 161
 162 .PHONY : dvi pdf ps clean realclean check_for_sources
 163
 164 .SECONDARY : $(MONITOR_FILES) $(XFIG_AUX) $(XFIG_GFX) $(XFIG_TEX)
 165
 166 ifeq (,$(LATEX))
 167 LATEX := latex
 168 endif
 169
 170 ifeq ($(notdir $(LATEX)),pdflatex)
 171 pdf : $(PDF_FILE)
 172 else
 173 dvi : $(DVI_FILE)
 174 endif
 175
 176 ps : $(PS_FILE)
 177
 178 clean :
 179         -rm -f $(MONITOR_FILES)
 180         -rm -f $(MONITOR_FILES:%=%.old)
 181         -rm -f $(OTHER_FILES)
 182         -rm -f $(XFIG_AUX)
 183         -rm -f $(XFIG_GFX)
 184         -rm -f $(XFIG_TEX)
 185
 186 realclean : clean
 187         -rm -f $(DVI_FILE)
 188         -rm -f $(PDF_FILE)
 189         -rm -f $(PS_FILE)
 190
 191
 192 ###############################################################################
 193 #
 194 #                                   Macros
 195 #
 196 ###############################################################################
 197
 198
 199 ###############################################################################
 200 #
 201 #                       Dependancies and Generation Rules
 202 #
 203 ###############################################################################
 204
 205 #
 206 # Check for the existance of all required source files
 207 #
 208
 209 check_for_sources :
 210         @FOUNDALL=1 ; for source in $(SOURCE_FILES) ; do [ -f "$$source" ] || { echo "Error: cannot find source file: $$source" ; FOUNDALL=0 ; } ; done ; [ $$FOUNDALL == 1 ]
 211
 212 #
 213 # Generate a postscript file from a .dvi file
 214 #
 215
 216 %.ps : %.dvi
 217         dvips $(DVIPS_FLAGS) -o $@ $*
 218
 219 #
 220 # Generate the .dvi (or .pdf) file by running LaTeX (or PDFLaTeX) until the
 221 # auxiliary files listed in MONITOR_FILES stop changing.  Rather than just
 222 # looping, make is re-run which allows any files that depend on the
 223 # particular auxiliary files that changed to be updated as well.
 224 #
 225
 226 define run-latex
 227         @saveold() { for file ; do [ -f $${file} ] && cp -fp $${file} $${file}.old ; done ; true ; } ; \
 228         restoreold() { for file ; do [ -f $${file}.old ] && mv -f $${file}.old $${file} ; done ; true ; } ; \
 229         deleteold()  { for file ; do rm -f $${file}.old ; done ; true ; } ; \
 230         makeobsolete() { touch -r $$(ls *.old | tail -n 1) $${1} ; true ; } ; \
 231         nochange() { for file ; do [ ! -f $${1} ] || cmp $${1} $${1}.old >/dev/null || return ; done ; true ; } ; \
 232         saveold $(MONITOR_FILES) ; \
 233         if $(LATEX) $(LATEXOPTS) $* $(LATEXFILTER) ; then \
 234            if nochange $(MONITOR_FILES) ; then \
 235               echo "$(MAKE): LaTeX auxiliary files did not change (processing is complete)" ; \
 236               restoreold $(MONITOR_FILES) ; \
 237            else \
 238               echo "$(MAKE): LaTeX auxiliary files changed (further processing is required)" ; \
 239               echo "please wait..." ; sleep 2 ; \
 240               makeobsolete $@ ; \
 241               deleteold $(MONITOR_FILES) ; \
 242               $(MAKE) --no-print-directory $@ ; \
 243            fi ; \
 244         else \
 245            echo ; \
 246            false ; \
 247         fi
 248 endef
 249
 250 $(DVI_FILE) : %.dvi : $(TEX_FILES) $(MONITOR_FILES) $(GRAPHIC_FILES) $(XFIG_TEX)
 251         $(run-latex)
 252
 253 $(PDF_FILE) : %.pdf : $(TEX_FILES) $(MONITOR_FILES) $(GRAPHIC_FILES) $(XFIG_TEX)
 254         $(run-latex)
 255
 256 #
 257 # Generate a .bbl file from the .aux file.
 258 #
 259
 260 %.bbl : %.aux $(BIB_FILES)
 261         BSTINPUTS="$(BSTINPUTS)" BIBINPUTS="$(BIBINPUTS)" bibtex $*
 262
 263 #
 264 # Generate a .ind file from the .idx file.
 265 #
 266
 267 %.ind : %.idx
 268         makeindex $(INDEX_ARGS) $<
 269
 270 #
 271 # Generate a .aux or .idx file if it doesn't already exist.  The existance
 272 # of these files is a prerequisite for the main document processing loop
 273 # above so that's what we're doing here.  Note, however, that all .fig.tex
 274 # files must be present in order for this first pass to succeed
 275 #
 276
 277 %.aux %.idx : $(XFIG_TEX)
 278         $(LATEX) $(LATEXOPTS) $* $(LATEXFILTER)
 279
 280 #
 281 # Distill xfig .fig files into .fig.tex and either .fig.pdf or .fig.ps
 282 # compoents
 283 #
 284
 285 ifeq ($(notdir $(LATEX)),pdflatex)
 286 %.fig.tex : %.fig %.fig.pdf
 287         fig2dev -L pstex_t -p $*.fig.pdf <$< >$@
 288 else
 289 %.fig.tex : %.fig %.fig.ps
 290         fig2dev -L pstex_t -p $*.fig.ps <$< >$@
 291 endif
 292
 293 %.fig.pdf : %.fig
 294         pushd $(dir $<) ; fig2dev -L pstex <$(nodir $<) | ps2pdf - - >$(nodir $@) ; popd
 295
 296 %.fig.ps : %.fig
 297         pushd $(dir $<) ; fig2dev -L pstex <$(notdir $<) >$(notdir $@) ; popd