EFFORT REQUIRED BY THE AUTHOR: AN EXAMPLE

The reader interface demands minimal effort from the author. The author merely supplies the application-specific rules, while the community's ReDoc rules contain all definitions that are not application-specific. The author's definitions have to conform to the community's naming conventions, so that the author's application-specific rules can be invoked by the universal ReDoc rules.

The author of a reproducible document has to list each result file as either easily, conditionally, or non-reproducible. For every easily or conditionally reproducible result, the author has to supply a rule that generates the result file. Furthermore, the author needs to specify a cleaning rule that removes the intermediate files. The ReDoc rules offer the author a comprehensive default cleaning rule, jclean.

Since the author's rules deal with the document's application, the effort required of an author is best illustrated by an example. The electronic version of this article is accompanied by a subdirectory called Frog. Frog contains a complete albeit small reproducible electronic document about a finite-difference approximation of the 2-D surface waves caused by a frog hopping around a rectangular pond. The files paper.latex and paper.ps hold two formats of the short scientific article describing the finite-difference approximation (see Inset). Some RATFOR files implement the 2-D wave propagation code. The Fig directory contains the result files: a figure (postscript and gif version) of the pond after some wild hops by the frog and the output (two float numbers) of a dot-product test of the linear finite-difference operator and its adjoint. To organize the document's files, the author of the Frog example wrote the following makefile:

SEPINC = ../Rules
include ${SEPINC}/Doc.defs.top

RESULTSER = frog dot

col = 0.,0.,0.-1.,1.,1.
${RESDIR}/frog.ps ${RESDIR}/frog.gif: frog.x
	frog.x                   > junk.pgm
	pgmtoppm ${col} junk.pgm > junk.ppm
	ppmtogif        junk.ppm > ${RESDIR}/frog.gif
	pnmtops         junk.pgm > ${RESDIR}/frog.ps

objs = 	copy.o adjnull.o rand01.o wavecat.o  	pressure.o velocity.o viscosity.o wavesteps.o
frog.x: ${objs}

dot.build ${RESDIR}/dot.txt : dot.x
	dot.x dummy > ${RESDIR}/dot.txt
dot.tube: ${RESDIR}/dot.txt
	cat ${RESDIR}/dot.txt
dot.burn: 
	rm ${RESDIR}/dot.txt

dot.x : ${objs}

clean: jclean

include ${SEPINC}/Doc.rules.red
include ${SEPINC}/Doc.rules.idoc
include ${SEPINC}/Prg.rules.std

The variable RESULTSER contains the list of the document's easily reproducible results, frog and dot.

The next rule contains the commands to build the postscript and gif version of the frog result. Such a rule is application-specific and cannot be supplied by included default rules. The target names comprise the directory RESDIR, in which the result files reside, and file suffixes (.ps, .gif), which indicate the files' formats. The rule depends on an executable frog.x, which it executes during the computations of the result.

Default rules for compilation and linking of executables such as frog.x are supplied by a shared include file, Prg.rules.std. The dependency of the executable on its subroutine object files, as in the case of frog.x, needs to be defined by the author of the makefile, since it depends on the application-specific file names.

In the case of the dot result file, the rules supplied by the author reflect the commands of the reader interface: dot.build creates the result file, dot.tube displays it, and dot.burn removes it.

Finally, the target clean invokes the included default target jclean. The targets remove intermediate files based on our laboratory's naming conventions.