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 will mark such figures NR denoting ``non reproducible''.) 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 I am 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 I am writing this, I am wondering if I should change these rules to something with the cando construction.)
Now let us do something constructive. To build all the figures in any of my books or documents, I 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:
#define PSARGS color=y invras=n fat=1 fatmult=1.5
#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)
At this moment, color=y should be used for making interactive documents, but not paper copy (since we use black and white printers and color comes out dithered). Thus, before our next report generation, we will change this definition to color=n, burn all the postscript files, build the paper document, send it to the printer, then burn all the postscript files and rebuild them again with color=y for our electronic documents.
Recall, I said that cake tube will take the user through a tube view of all the plot files. This happens because of the rules
#ifndef TUBE
#define TUBE tube width=.8 height=.8
#endif
tube&: [[ sub -i X X.tube FIGLIST ]]
%.tube&: FIGDIR/%.v if cando FIGDIR/%.v
TUBE FIGDIR/%.v
%.tube&: 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. I should eliminate this error message by including a do-nothing rule, or by calling a postscript previewer where possible.)