Simultaneously clean and up to date

A document is best maintained both clean and up to date: each result file is younger than its ultimate source files, and the intermediate files are removed, but assumed to be up to date. A reader prefers a clean directory, since an uncluttered directory clearly presents the important source and result files. Simultaneously a reader expects reassurance that the document's results correspond with the existing source files. (Furthermore, we found that only cleaned documents are functional on a CD-ROM: intermediate files once stored on the read-only memory of a CD-ROM cannot be overwritten when the files are later regenerated by a reader.)

Unfortunately, popular make dialects generally do not support rules to keep documents simultaneously clean and up to date. These dialects consider a result file out of date when certain intermediate files are missing (for example, GNU make considers a result file out of date if a file is absent whose dependency is formulated by a non-pattern rule). Such treatment of intermediate files is convenient for software maintenance but not suitable for reproducible electronic documents.

The cake dialect of make was designed for document maintenance rather than for software maintenance. cake assumes all absent intermediate files to be up to date and therefore supports documents that are simultaneously clean and up to date. cake was originally introduced at our laboratory because it was the first freely distributed, platform-independent make dialect we found. Unfortunately, cake's limited popularity at other sites made our reproducible electronic documents unattractive to potential readers.

Today's ReDoc rules are able to maintain a document clean and up to date while being formulated in the very popular GNU make dialect. At our request, Richard Stallman recently enhanced GNU make to adequately handle the ReDoc rules' intermediate targets. He added a special built-in target, .SECONDARY that allows the author to choose the behavior of GNU make with respect to its missing intermediate files. If a makefile includes a .SECONDARY target without dependencies (the default at our laboratory), then every missing intermediate file is presumed up to date. The .SECONDARY target is implemented in GNU make versions higher than 3.74.