A WYSIWYG literate programming system (preliminary report)

Conceptually, literate programming systems are document preparat ion systems that are augmented with features for writing programs. They offer features for identifying the different components of the programs, for highlighting the relations that exist between the components, and for explaining the components and the relations. We introduce a literate programming system that is based on a hierarchical variation of MacWrite. The system distinguishes code from prose by the fonts that they are written in, uses boxes for abstract ing and structuring code, and employs ports for generating different views of the code. 1. Background Programs are sequences of commands which specify how computat ions should be carried out. They are written for computers which execute them blindly without paying at tent ion to the objective of the programs and to the motivat ion for their designs. They are quite easy to execute because they consist of primitive commands, but for this same reason they are normally large in size and complex in structure. Writing programs of large sizes and complex structures is a difficult task, because at any given time a human being can handle only a small amount of information. Programming languages simplify this task by introducing abst ract commands tailored for the problems under consideration and by providing the users with features for defining their own abstractions. Such abstractions allow for programs that are expressed in more natural fashion and tha t are reduced in size and structural complexity. Yet, with all the advantages that such abstractions offer even the most advanced programming languages have their limitations with regard to the extent to which they can facilitate the task of programming. By their nature, programming languages are suitable mostly for stating what the programs should do and less so for stat ing why the programs do whatever they do the way that they do it. Tha t is, they do not provide their users with acceptable medium for documenting design issues. This shortcoming is evident in the pluralization of poorly documented pieces of software, despite the wide recognition that documentat ion is a must. A recognition that brought much preaching to produce documentat ion but very little in environments that genuinely support such activities. 1.1 L i t e r a t e P r o g r a m m i n g With this perspective in mind, the discipline of literate programming [6] deserves a special a t tent ion because it calls to write programs for computers the way that we explain them to human beings. Tha t is, it promotes the writing of programs that interleave commenta ry with code, rearrange the different parts of the code to orPermission to copy without fee all or part of this material is granted provided that the copies are not made or distributed for direct commercial advantage, the ACM copyright notice and the title of the publication and its date appear, and notice is given that copying is by permission of the Association for Computing Machinery. To copy otherwise, or to republish, requires a fee and/or specific permission. t Current address: ATgzT Bell Laboratories, 200 Laurel Ave., Room 4G-213, Middletown, NJ 07748 © 1991 ACM 089791-382-5/91/0003/0094 $1.50 94 ders that bet ter appeal to human readers, and use abstract ions presented in a natural language (and implemented elsewhere) as substi tutions for pieces of code. Programs of this kind are called literate programs and they assume the appearance of documents that describe programs. Literate programs provide us a channel for communicat ing our thoughts between the different phases of the programming process, and provide us with encouragement to clarify our thoughts when we write them down and to refine them when we review them. Moreover, they allow us to decompose and rearrange the code based on logical considerations, and to use enhanced visual expositions for highlighting logical units and structural relationships between the units. 1.2 L i t e r a t e P r o g r a m m i n g S y s t e m s Systems that provide the tools needed for practicing literate programming are called literate programming systems. Systems of this kind at the very least must offer the features that document preparation systems offer, should provide features for identifying f ragments of code and relations between fragments of code, and should be equiped with the ability to extract the code from the documents. On the other hand, the more sophisticated literate programming systems should also assist their users in navigating around the code and should be able to interact with the agents that execute the programs. Computers that are sufficiently powerful to run literate programming systems became available to the community of programmers only in recent years. Hence, it is not surprising that l i terate programming systems are new entries in the field, and that the currently available systems are few in number and lean in features. 1.3 B a t e h O r l e n t e d S y s t e m s The first literate programming system to appear was WEB I6]. In essence, WEB is a preprocessor that gets fragments of a Pascal [18] program and pieces of prose mixed together and identified with special markers. From such an input, called a source literate program, WEB generates two files: one file containing the Pascal program for an agent that executes the program, and a second file containing the literate program with formatt ing instructions for generating a viewing copy with TEX [5]. In addition, WEB produces cross referencing information and an index, to facilitate the navigation between the different fragments of code. Since its appearance, variants of WEB have been written for other programming languages besides Pascal, for instance, [1, 3, 7, 12, 13, 14, 17]. In particular, [12] provides a version of WEB which facilitates the tailoring of the system to different programming languages (but it requires some knowledge of the architecture of WEB [14]). On the other hand, [4] introduced a small extension to 'rEX which provides a highly-portable language-independent system that can be easily adjusted to meet different specifications. The above literate programming systems are very useful systems. However, they are suitable mainly for sophisticated programmers because they are quite complex and costly to operate. Specifically, they expect their users to write and modify their literate programs indirectly through source literate programs. Moreover, they require that their users will navigate around between a literate program, a source literate program, and a computer program whenever errors arise and changes are to be made. Further more, they increase the amount of t ime that it takes for making changes in code, because the literate programming systems have to be activated to propagate the changes from the source programs. The increase in time is even more severe when the users work with interactive compilers and interpreters, because the stand alone literate programming systems dictate a batch-oriented mode of programming. (Yet, the increase in t ime for each cycle of modifications is more than compensated for by the reduced number of cycles.) 1.4 I n t e r a e t l v e S y s t e m s In contrast to the above systems, BOXER [2] offers a programming environment for unsophisticated users. It was not constructed with the intention to make it a literate programming system. Instead, its intended objective was to provide an environment for constructing electronical books that can be dynamically changed by their readers. Yet, in some respects BOXER has the flavor of a futurist literate programming system. Specifically, BOXER can be used to prepare a literate program on a b i tmap screen in a what-you-see-is-whatyou-get (WYSIWYG, for short) [15] mode. A literate program of BOXER contains text and boxes, where the boxes are rectangular regions with visible boundaries. The boxes may contain text or (LOGO [11]) code, and they can be organized into hierarchies that relate their contents. In addition, BOXER provides an interpreter for executing the code that is contained within the boxes. The user designates special boxes from which the interpreter gets its input, and designates special boxes for holding the output of the interpreter.