Literate Programming, a Practioner's View
Total Page：16
File Type：pdf, Size：1020Kb
Literate Programming, A Practioner’s View Bart Childs Texas A&M University Department of Computer Science College Station, TX 77843-3112 Phone (409) 845-5470; FAX (409) 847-8578 Internet: [email protected] Abstract I have been using the WEB style of Literate Programming since my first efforts to port TEX to the Data General AOS system. When I looked back at those efforts, the work in porting drivers that were not written in WEB and the writing of drivers in WEB (based upon DVITYPE, of course), the value of this method of programming became evident. I have concentrated my research (and some teaching) efforts upon this style of programming. I will relate my insights and opinions of the following: some quantitative and qualitative measures of the value of WEB programming; a description of some tools that are part of an environment for writing and maintaining literate programs; literate programming environments that are alternatives to the WEB style; an annotated list of some literate programming systems; and I will conclude with my perception of the future of literate programming. Introduction A Definition Donald Knuth created the WEB system of literate I use the following list of requirements to imply a programming when he wrote the TEX typesetting definition of a literate program and the minimum system a second time (see “The WEB system set of tools which are needed to prepare, use, and of structured documentation”, 1983; “Literate study the resulting code. programming”, 1984; TEX: The Program, 1986; • The high-level language code and the system METAFONT WEB and :TheProgram). The system documentation of the program come from the can be described as the merging of documentation, same set of source files. code, and presenting the listings in a typeset format • The documentation and high-level language with aids of table of contents, cross-referencing, and code are complementary and should address indices. the same elements of the algorithms being I have used Knuth’s original WEB system and written. several descendants for a number of years. It is • The literate program should have logical my opinion that the training necessary to learn how subdivisions. Knuth called these modules or to program in a literate style is relatively small. I sections. believe the benefits of literate programming make • The system should be presented in an order it worthwhile. The benefits are better and more based upon logical considerations rather than maintainable code (it can be argued that this is not syntactic constraints. proven.) • The documentation should include an examina- In this paper I will also report on available tion of alternative solutions and should suggest literate programming systems, some of my successes future maintenance problems and extensions. and failures as a literate programmer, creation of • The documentation should include a descrip- some tools to aid the literate programmer, the tion of the problem and its solution. This community of literate programmers that I have should include all aids such as mathematics been able to identify, alternatives to the WEB system, and graphics that enhance communication of and suggested directions for use and research in the problem statement and the understanding literate programming. of its challenge. TUGboat, Volume 13(1992), No. 3—Proceedings of the 1992 Annual Meeting 261 Bart Childs • Cross references, indices, and different fonts for by today’s systems programmers but sometimes it is text, high-level language keywords, variable a convenient way to represent certain ideas. (Knuth names, and literals should be reasonably used Pascal because “it was everybody’s second automatic and obvious in the source and the best language” at the time (Knuth, TUGboat, 7(2), documentation. 1986). It was before C was widely available.) These requirements have been adapted from (Knuth, 1992), and (VanWyk, 1989 and 1990). Some of My Successes and Failures My adaptations of the list were affected by my My introduction to the WEB system of literate experience as a WEB user — first in a maintenance programming was rather abrupt — I was porting mode, then as an author, and finally using T X82. I had not written a Pascal program or a WEB in undergraduate and graduate education E T X document at the time. I had written a number environments. The last has involved the creation E of systems programs in PL/1. of some tools to enhance the use of literate Version 0.6 of the T Xsystemwasmade programming in all environments. E available to me in the fall semester of 1982. Knuth posed this thought to introduce literate Distribution tapes contained about 300 files. Most programming: “Instead of imagining that our main of these had to do with the fonts in a binary form. task is to instruct a computer what to do, let us Binary files were written in a format of twenty bytes concentrate rather on explaining to human beings per record. Each byte was converted to four ASCII what we want a computer to do” (Knuth, 1984). characters; for example, ‘255’ for the byte with all His thesis was that it should be just as important to bits being one. Over a two or three week period I communicate with the other persons who read the ported the TANGLE processor and began work on the program as it is to communicate with the computer WEAVE processor. I also had the ‘report version’ of which executes it (Knuth, 1992). David Ness said volume B of the C&Tseries (Knuth, 1986). “it is the most important task.” Theendofthesemestercausedmetostopthe work and I did not resume until the spring with Knuth’s WEB System version 0.9 of TEX. I spent some time reviewing the When Don Knuth wrote TEX the second time, changes in the necessary parts of the TEXsystem: he gave thought to making it portable to many TANGLE, WEAVE,andTEX. different systems. WEB was created as a superset of The WEB sources were usually complemented Unix TEXandPascal. with the change files for TOPS, VMS, and WEB’s design encourages writing programs in systems. These were valuable, but I recall the small chunks which Knuth called modules (he also feeling that the “system dependencies” entries in used the term sections). Modules have three parts: the index were even more valuable. It helped to documentation, definitions, and code.Atleastone see what was changed for other systems, but often of these three parts must be non-null. those changes were in terms of “system calls” whose The documentation portion is often a verbal documentation I did not have. description of the algorithm. It may be any The necessary codes are approximately 2,700, textual information that aids the understanding of 7,000, and 25,000 lines of Pascal each of the the problem. It is not uncommon for a WEB to INITeX and TEX processors. I was able to port have a number of ‘documentation only’ modules. approximately 60,000 lines of Pascal code to a These usually describe the problem independent system on which only 2,700 lines had previously of the chosen language for implementation. For been ported. I did this in three days (probably 15 example, a WEB for a subprogram that solves the hours of work). I regret that I did not keep a diary linear equation, Ax = b, could have discussion of or log errors like Don Knuth did, (Knuth, TUGboat, singularity, condition numbers, partial pivoting, the 7(2), 1986; and Knuth, chapters 10 and 11, 1992). banded nature of the expected coefficient matrices, The experience of porting the system convinced etc. It should be an unusual but not exceptional me that the literate programming style had case when a module contains no documentation. significant merit. Most of the programs I The definition part of a module was often subsequently wrote for the TEXsystemwereWEBs. used by Knuth to offset shortcomings of Pascal The existence of dvitype asamodelfordrivers when used in systems programming. (Wirth created helped this decision. I created a family of drivers for Pascal to be a language for pedagogy, not systems the AOS system for QMS, HP, and Canon printers. programming.) This is rarely the language of choice These used a common source and adaptations for 262 TUGboat, Volume 13(1992), No. 3—Proceedings of the 1992 Annual Meeting Literate Programming, A Practioner’s View the different printers were accomplished by change • WEB systems that have been adapted to a files. different high-level language by pre-processors This further experience led to the logical and/or post-processors. These include support conclusion that an “environment” could help for Fortran,andthefirstWEB for Reduce. significantly. We created several environments • WEB systems that have a different basis for to automate the steps of creation of code and their creation but generally follow the same WEB documentation for the AOS system. The emergence concepts. Ramsey’s Spider enables reasonably of Unix and availability of workstations has easy creation of WEBs for several different relegated these early works to simply being a languages (Ramsey, 1989). His example include pleasant memory that in some sense could be called WEBs for Ada, C, awk, and SPL. Gragert and a failure. Roelofs created the second WEB for Reduce with Marcus Brown built part of an “Interactive Spider (Gragert, 1991). They are now creating Environment for Literate Programming” as part of a WEB for Maple (Gragert, 1992). his dissertation under my direction (Brown, 1988 • WEB systems using a different language or and 1990). This was essentially the output side of formatting system. Three will be mentioned. an editor which also allowed the navigation of the Thimbelby did his CWEB with the Unix source with views of the typeset output, a graphical standards of C and troff (Thimbelby, 1986).