INTRODUCTION

For several years, SEP has published reproducible electronic documents. Such reproducible documents maintain all the software pertaining to a specific research project. A reader is supplied with a set of simple commands that enable him to remove all result files, to recompute all result files from source files, and to clean all secondary files, (i.e., those which are neither source nor result files). This set of commands helps authors to keep their documents up-to-date by recomputing their results regularly. It also helps readers by allowing them to isolate the source files and to observe the recomputation of the results.

At the center of a reproducible electronic document is a makefile. All SEP makefiles share common include files which define a set of standard rules and variables. Consequently, a reader can rely on these standard rules when interacting with any SEP document.

In the past, SEP used the make dialect cake Nichols and Cole (1989), which Somogyi specifically developed for document maintenance ().

The cake language uses the C-preprocessor for variable and macro definitions. The author of a cakefile writes Prolog-like rules. Dependencies with expressions such as cando target1 or exist target2 make rules very brief and easy to read. Unfortunately, cake is not widely used and only very sparingly documented.

We decided to replace cake with GNU make, which is another make dialect. GNU make is widely used as a public domain software maintenance tool. It is well documented Stallman and McGrath (1991) and supported by a very active newsgroup, gnu.utils.bug. GNU make has its own internal variable substitution mechanism. Its rules tend to be more serial than cake's, which is partially due to the lack of dependency features such as cando and exist.

Most of the standard GNU make rules, which are contained in the include files, are translations of the former cake version. One highly visible change is the new mechanism that declares a result file either easily-, conditionally-, or non-reproducible. According to the GNU make rules, the name-stem of all result files are listed in one of three lists: RESULTSER for easily-reproducible result files, RESULTSCR for conditionally-reproducible result files, and RESULTSNR for non-reproducible result files. When the author lists a target in one of these categories, he makes a promise to the reader about the reproducibility of that result file. The reader can verify the promise by attempting to remove and to recompute a result file using standard commands.

To improve GNU make's suitability for document maintenance, Richard Stallman added the special built-in target .SECONDARY. When one deals with electronic documents, secondary files can be large and expensive to compute. A reader may want to check if a result is up-to-date with respect to its source files, even when some secondary files are missing. Standard GNU make considers a target always out-of-date if a secondary file, which is listed explicitly as a dependency, is missing. However, if the author includes the special built-in target .SECONDARY, then all targets are considered up-to-date even if any of their secondary files are missing. Thus, a target is only out-of-date when it is older than its source files.

We have tested the new GNU make document rules by translating Claerbout's three most recent books Claerbout (1992, 1994, 1995). Based on the success of these tests, SEP plans to switch to GNU make for its future reproducible documents.