INTRODUCTION

At SEP we have UNIX machines from many vendors including HP, IBM, Sun, TMC, DEC, and Convex, yet most of our programs run with no changes when we switch from one machine to another. The reason we can do this so easily is that Dave Nichols imported cake (a variant of the UNIX utility make) and prepared compiling and linking rules for our needs. Then also using cake, Jon Claerbout tackled the problem of organizing the management of his textbooks so that students could easily repeat all the calculations that generated all his illustrations. After organizing the first 300 or so figures, he learned what is common to all figure making and abstracted it into two pages of cake rules that are linked (included) into all figure making directories. By extracting what is common, what remains is the small nucleus that varies from one figure to the next. Thus, after learning what is in the common part, the researcher-author needs to supply a minimum of information to give the reader a consistent and powerful interface. As Dave Nichols supplied SEP with SEP.obj.rules and SEP.prog.rules and some accompanying documentation, (at SEP this is found in /usr/local/lib/cake) Claerbout supplied you with SEP.idoc.rules, and early versions of this document describing it. Claerbout's original goal was research reproducibility. Since then, Martin Karrenbach enlarged the scope of SEP.idoc.rules to use Steve Cole's new xtpanel to give much greater reader interaction.

We assume our readers are familiar with the UNIX make utility which is widely used for software maintenance. We use the dialect of the make language called cake because it better expresses the needs of document development.

The main strategy is to isolate the reusable code in two files, SEP.defs that we ``include'' at the beginning of each figure-making cakefile and SEP.idoc.rules that we include at the end. Each of the many figure-building cakefiles starts with

        #define USRLIBS SEPCLASSLIB
        #include <SEP.defs>

The (optional) first line says that linking will include the library used in all Claerbout's classes. If you need additional libraries, add them to the end of this line. SEP.defs also sets up a default location for our figures because it contains the lines

        #ifndef FIGDIR
        #define FIGDIR ./../Fig

which means a sister directory to any of our figure-building directories is named Fig (which is generally a symbolic link to a nonprecious area). Some people prefer to keep their figures in a daughter directory so they start off with

        #define FIGDIR ./Fig
        #include <SEP.defs>

Often people write cakefiles so that if you come into a directory and type a simple cake, you will view a succession of figures emerging from the tube program. In the skeleton cakefile below, typing cake will show two figures named data and spectrum, and it will build them first if they are out-of-date.

        #define USRLIBS SEPCLASSLIB
        #include <SEP.defs>
        #define FIGLIST data spectrum
        default& : tube
        $         comment
        $ Application dependent stuff described later belongs here.
        $
        clean& : jclean
        #include <SEP.idoc.rules>
        #include <SEP.obj.rules>
        #include <SEP.prog.rules>

The line containing jclean defines the clean-up procedure and will be explained later. At the bottom of this skeleton cakefile we included the compilation and linking rules of Dave Nichols, and we include SEP.idoc.rules, which has grown to about four pages of cake rules that are common to all our figure building and interactive documentation and whose content is our main subject here.