8 The WEB System of Structured Software Design and Documentation for C, C++, Fortran, Ratfor, and TEX User Manual JOHN A. KROMMES Princeton University [email protected] FWEB Version 1.30 June 15, 1993 1. INTRODUCTION This manual describes how to write programs in Knuth’s WEB system, as adapted and extended by J. A. Krommes to handle the programming languages of Fortran (including both Fortran–77 and Fortran– 90), Ratfor,C,C++,andTEX. We shall call this new version FWEB when necessary, but generally we’ll just refer to the WEB system. This adaptation is a substantial modification of S. Levy’s C version CWEB of WEB, which in turn was a complete rewrite in C of Knuth’s original Pascal source. (TEX is written in the original Pascal WEB.) The principal design contributions to this version of WEB are (1) the concept of a current language, so that one can process code FWEB understands C, C++,Fortran– written in multiple languages in the same WEB 77, Fortran–90, Ratfor, and TEX. run; (2) new production rules for Fortran, Ratfor,andTEX (and some modifications of Levy’s rules for C); (3) a C-like built-in macro preprocessor; and (4) the ability to directly translate Ratfor into Fortran. In addition, many miscellaneous details have been changed and a variety of convenience features have been added. For example, a general style-file mechanism allows the user to customize various actions of the system. This manual covers quite a breadth of material, from the most introductory to very advanced. To help identify the level of difficulty, the sections are marked with 0, 1, or 2 dangerous bends (here shown as ♣) alatheTEXbook. 1.1 Previous authors, and the structure of this manual The WEB system and this manual have evolved through contributions of several authors, principally Knuth and Levy, and the flavor of the system is best captured with those authors’ original words. Levy attempted to highlight Knuth’s original text by indenting it. Quoting from Levy’s manual, “The bulk of this document consists of quotes from Knuth’s memo ‘The WEB System of Structured Documentation’; these quotes are clearly distinguished by their indentation, and apart from such substitutions as ‘code’ for ‘Pascal’, all other changes to them are explicitly indicated. This also serves to indicate which commands and features are common to all versions of WEB and which are characteristic of this version (of course if you’re new to WEB you don’t have to worry about this).” In practice, new users of WEB seem to find the indented style somewhat confusing; furthermore, the length of this manual has grown to a point where more than 50% of the text is new. Therefore, in an attempt to accomodate everyone, this user manual can be TEXedintwo ways, depending on the setting of the TEXmacro\ifbilevel, defined near the beginning of the macro package fmanmacs.tex for this manual. By default, that switch is false and most indentation is suppressed. (A few of the most significant quotes are indented in both formats.) To obtain the indented style, say \bileveltrue. In the bilevel mode, we shall preface Levy’s remarks by “[Levy]:”, and we shall feel free to interject additional remarks by enclosing them in square brackets or to skip extraneous material by using an ellipsis. The brackets and ellipses are also suppressed when the bilevel switch is false. — The origins of FWEB — 9 1.2 The origins of FWEB (The contents of this subsection are totally irrelevant to the narrow goal of learning to use FWEB.But they might be of some “cultural” interest.) FWEB was born of necessity. One of the focuses of my research in theoretical plasma physics has been the construction and solution of so-called “statistical closure approximations,” the most famous example of which is Kraichnan’s 1959 direct-interaction approximation (DIA). At some point around 1985 I decided that further progress would benefit greatly from numerical solutions of the DIA and related closures applied specifically to plasma turbulence. (Kraichnan, Herring, and others had long before done the analogous calculations for neutral-fluid turbulence.) So I began writing my DIA code—in standard Fortran.The result was a disaster. I needed extensive memory allocation facilities, but Fortran–77 doesn’t provide them. I simulated them using tricky array manipulations, but the code was difficult to debug and to understand. I wanted complicated data structures, but again Fortran–77 wasn’t up to the task. Ditto for simple string manip- ulations, communication with the command line, and transparent, easy-to-write I/O statements. In other words, I didn’t want Fortran–77 at all; I wanted C! So I threw away a year’s worth of work and started over. The second time around, I at least had a better sense of the scale of the project—it was large. Also, upon looking back at my original attempt, I realized that I couldn’t understand the code at all, even though I had been fairly liberal with Fortran-style comments. Looking ahead, I also realized that graduate students would likely become involved. Since I have strong feelings about wanting my students to actually do physics instead of just computing, it became imperative to write the code using the most powerful documentation scheme available so they could quickly understand how it worked and could modify it as easily as possible. Knuth’s article on “Literate programming” [1] had already provided a “religious experience” for me when I read it several years previously, tempered only by the fact that I hadn’t been in a computing phase at that time. But faced with the demands of the DIA project, Knuth’s excellent points all came back and I realized that WEB was the natural choice. Luckily, Levy had just announced his beautiful CWEB, so everything seemed to be in place. Then, another setback. One of the important characteristics of plasma, as opposed to incompressible fluid, turbulence is the presence of linearly propagating waves—described most naturally with complex numbers. Unfortunately, C doesn’t have an intrinsic complex type. C++ can easily be taught complex arithmetic, but good C++ compilers weren’t widely available, especially on the Cray supercomputers on which I intended to work. One can, of course, easily typedef a C structure that duplicates Fortran’s layout of a complex number, but short of function calls one can’t in C perform arithmetic on complex structures in the natural way one does in Fortran. Readability was important. So was vectorization, which also wasn’t available in the C compilers available at that time and in any case would probably be broken by function calls. So reluctantly I decided that the innermost, computational routines of the code should be written in Fortran. Of course, no way was CWEB going to handle Fortran code gracefully. But my colleague Henry Greenside had been arguing strongly for the use of Ratfor as a superior tool, given that one was stuck with some sort of Fortran. I agreed, and also hoped that Ratfor’s C-like syntax would be close enough to C’s that CWEB would be adequate. And so I plunged ahead, writing in a mixture of C and Ratfor. CWEB worked for Ratfor—sort of. One was able to obtain the invaluable index, and often the Ratfor routines typeset just fine. But there were constant annoying glitches because of the inevitable differences of syntax. After a few years of experience, it became clear that one really wanted a proper Fortran version of WEB. Also, the absence of a Fortran macro preprocessor was causing us major annoyance. Although 10 — The origins of FWEB — Knuth’s original WEB had a rudimentary preprocessor, Levy had deleted it for CWEB, since C has its own preprocessor. I decided there needed to be one built in that would serve all languages equally well. Thus, the major design goals were clear: a new Fortran WEB that also supported Ratfor and C, with a macro preprocessor. So I learned how Knuth and Levy had implemented the syntax production rules, sat down with a Fortran reference manual, and began to write some Fortran productions. I thought this would take a couple of weeks. That was actually about right. Ultimately, however, my estimate of the total amount of work involved in realizing all of my ideas about an “industrial strength” WEB easily usable in the scientific environment was off by at least two orders of magnitude. (Well, I’m a theoretical physicist.) Some years later, I’m still upgrading FWEB. Had I been left to my own devices, I probably would never have made it publicly available, since the conflicts between trying to complete the research I had intended to do and maintaining a reasonable robust code are almost overwhelming. But my colleague Charles Karney, a true expert both in TEX and scientific computation, began distributing codes written in FWEB and convinced me that a public announcement was the best way of both achieving some sort of standardization and accomplishing the debugging task. So an announcement was timidly made, and the response has been amazing. Most incredible has been the continuing patience of the many users who are faced with a utility that is still not bug-free and that they might have designed differently. FWEB is far from perfect, but it’s much better than my original attempt because of the many well-thought-out suggestions and questions that I continue to receive. My profound thanks. (Incidently, in the midst of all this a workable version of the DIA code was finally finished with the completion of John Bowman’s Ph.D.