EUREKA

I didn't recognize the concept of an a-doc until I had nearly built one. My third textbook on earth soundings analysis consists of about 300 pages, 120 figures, and listings of 40 terse subroutines. The subroutines were used in preparing the figures. Each of the figure captions contains a one-word name for the figure. Behind the visible book are plot files for each figure as well as main programs and command scripts (makefiles) that I used to make each figure. I suddenly realized that I had all the materials needed by any reader or student to recreate my work. This would give a tremendous boost to anyone wishing to go beyond me. At present the reader would need all my files and the local computing environment, and a little imagination to fill in a few steps that I did manually (mostly file copying and figure scaling). But with a little effort, the figure name could be connected to the command script that generates the figure. I have begun this effort. This will create an a-doc for all those Stanford people who share my environment. With time we should learn how to encapsulate out local software environment in a more portable way thereby assisting graduating students, sponsors, and eventually the research community.

From my author's view, the transition from an active book to an interactive one was an easy step. But giant steps were made by Steve Cole, Martin Karrenbach, and Dave Nichols outside my view and are described elsewhere in this report.

What I see is that with a little extra effort on my part, my book can appear on a screen. The names in the figure captions become pushbuttons that access my command scripts. Other pushbuttons automatically appear where ever a figure or equation on one page is referenced on another page.

The little extra effort required on my part to see the document in its interactive form is exactly that required of me to be assured that the figure captions buttons do actually point to the programs that generate them. This plugs the final gap of undocumented information about how to redo a result. A document and a makefile with programs doesn't become an ``active document'' until this last connection is made.

How reproducible is reproducible?

Compiling a program is one test of its completeness. Simply viewing an i-doc can be proof of the completeness of its underlying a-doc. You won't see a figure in the document unless its caption has the required pointer to the command script that creates it. Further, with the i-doc software we are developing (see ``cake'' elsewhere in this report), a figure cannot be viewed until the figure is up-to-date with the stated subroutine dependences. If an author makes a last minute change to a subroutine that a figure is based on, that figure will be automatically rebuilt by the process of viewing or printing the document.

Impact of reproducible publication

The human consequence of reproducible publication have hardly been considered. Yet this medium of scientific communication is nearly upon us. With workstations now becoming widespread and software coming available, the burdens imposed on the author to create reproducible figures can be little more than the burdens of paper publication. We are nearing a time when it will be simply the author's choice whether to communicate fully, in which case reproducible documents will be chosen, or whether to provide sketchy advertisements of scholarship, keeping confidential the detailed means to results, in which case traditional publications will be used.