burn&: [[ sub -i X X.burn FIGLIST ]]
Reading man cake you see that this line, along with our earlier definition of FIGLIST will expand to
burn&: data.burn spectrum.burn
which means that cake burn done in this directory is equivalent to cake data.burn spectrum.burn which are the ``targets'' that can be built by the following idoc rule
%.burn&:
-/bin/rm -f FIGDIR/%.ps
-/bin/rm -f FIGDIR/%.v
To understand this rule, you need to know that in cakefiles, ``%'' is a wildcard like ``*'' in command shells.
We have a special category of figure types that cannot be easily rebuilt so they should not be burned. This is because they are scanned, prepared manually, with exotic hardware, excessive computer time, or because of any other difficulty. (Martin Karrenbach's latex environment marks such figures NR denoting ``non reproducible'' Karrenbach and Nichols (1990).) To save such files from burning, we give them names of the form NAME.v.save and NAME.ps.save. From time-to-time we redesign the vplot to postscript program (paper printing is usually black and white, but electronic documents use color) and then we want to burn all the postscript files that can be rebuilt from vplot. Here are the rules we are using now:
%.burnps& : if not exist FIGDIR/%.v.save
-/bin/rm -f FIGDIR/%.ps
%.burnps& : if exist FIGDIR/%.v.save
-/bin/rm -f FIGDIR/%.ps.save
Thus cake burnps will not burn your precious plot files if you have no way to rebuild them. (While we are writing this, we are wondering if we should change these rules to something with the cando construction.)
Now let us do something constructive. To build all the figures in any of our books or documents, we have a shell that passes over all the cakefiles in the document tree and executes cake figures. That evokes the rules below from SEP.idoc.rules
figures&: [[ sub -i X X.figure FIGLIST ]]
%.figure&: FIGDIR/%.ps.save if exist FIGDIR/%.v.save
%.figure&: FIGDIR/%.ps if not exist FIGDIR/%.v.save
These rules say that a postscript file must be created for every name in FIGLIST, either FIGDIR/%.ps or FIGDIR/%.ps.save. How the figures are created is determined by the following rules:
#ifndef PSARGS
# ifdef HARDCOPY
# define PSARGS color=n fat=1 fatmult=1.5
# else
# define PSARGS color=y
# endif
#endif
#define PSTEXPEN(A,B) pstexpen FIGDIR/A FIGDIR/B PSARGS
FIGDIR/%.ps.save : FIGDIR/%.v.save
PSTEXPEN(%.v.save,%.ps.save)
FIGDIR/%.ps : FIGDIR/%.v
PSTEXPEN(%.v,%.ps)
A few weeks before report generation, we insert in SEP.defs a line #define HARDCOPY (which you can do anytime in any of your cakefiles), burn all the postscript files, build the paper document, send it to the printer, then remove the line #define HARDCOPY, burn all the postscript files and rebuild them again for our electronic documents.
Recall, we said that cake tube will take the user through a tube view of all the plot files. The tube program will interpret single frame pictures (NAME.v) or multiple frame movies (NAME.v3). Paper documents can only cope with NAME.v files.
#define TUBEMOVIE ( cando FIGDIR/%.v3 or exist FIGDIR/%.v3.save )
%.tube&: %.tube1 if not TUBEMOVIE
%.tube&: %.tube3 if TUBEMOVIE
These rules choose the movie file if a movie exists or can be made.
If a movie cannot be made, the target becomes %.tube1
and is interpreted by
%.tube1&: FIGDIR/%.v if cando FIGDIR/%.v
TUBE FIGDIR/%.v
%.tube1&: FIGDIR/%.v.save if exist FIGDIR/%.v.save and \
not cando FIGDIR/%.v
TUBE FIGDIR/%.v.save
These rules say to show the file NAME.v if it can be made,
and if it cannot, then show the file NAME.v.save, if it exists.
(Technically, an error condition arises for a few handmade postscript
files for which tube cannot be used.
We should eliminate this error message by including a do-nothing rule,
or by calling a postscript previewer where possible.)
The rules for tube3 are like the rules for tube1.