Annotating Codes with FWEB

 

Consider the following code:

  real(kind=long) function gligf02(a, x)
    real (kind=long), intent(in) :: a, x
    real (kind=long), parameter :: epsilon = 1.0E-9
    real (kind=long) :: a0, b0, a1, b1, r_old, r_new
    integer :: n
    if (x .le. 0.0_long) then
       if (x .lt. 0.0_long) then
          stop 'error: gligf02 called with x < 0'
       else
          gligf02 = glegf02(a)
       end if
    else
       a0 = 0.0_long; b0 = 1.0_long; a1 = 1.0_long; b1 = x
       r_old = a1/b1; delta = r_old
       n = 1
       do while (abs(delta) .gt. abs(epsilon * r_old))
          a0 = a1 + (n - a) * a0; b0 = b1 + (n - a) * b0
          a1 = x * a0 + n * a1; b1 = x * b0 + n * b1
          r_new = a1/b1
          delta = r_new - r_old; r_old = r_new
          n = n + 1
       end do
       gligf02 = r_new * exp(-x + a * log(x))
    end if
  end function gligf02

Even though neatly typed in, this code is thoroughly incomprehensible. There is no way that just by looking at it, you can figure out that it evaluates:

$$\int_x^\infty e^{-t} t^{a - 1}\,\textrm{d}t$$

• In order to explain the meaning of the code you have to:

  1.

  Quote the continued fraction expansion for the integral.

  2.

  Demonstrate or quote the way that the continued fraction expansion is rewritten in terms of a recursive relationship.

  3.

  Show the precise form that the recursive relationship assumes in this case.

  4.

  Describe the mapping between the recursive relationship and the code.

  5.

  Discuss any simplifications or shortcuts present in the code.

  6.

  Discuss the convergence criterion employed by the code.

• Once you've done that much work, you can also attach any tests that the code has been subjected to, demonstrating its accuracy and performance.
• All the above requires a considerable amount of mathematical typesetting interleaved with the code.

• To annotate a complex scientific code we need to provide a brief paper for just about every function implemented in the code, and then for the mainlines too.
• If the annotations and the code live on separate files, it is easy for the annotations and the code to diverge eventually.
• The recommended methodology for annotating scientific programs is to divide the code into short fragments, no longer than between 10 to 20 lines each, and then discuss relevant mathematics while displaying the corresponding fragment at the same time.
• This implies that the program effectively has to be typed in twice: first on a program file, and then on a file with annotations. This makes coding mistakes in either document likely.

• WEB  is a system invented by Donald Knuth , which lets scientific programmers combine annotations and code on a single source file.
• The WEB input file can be then processed by one of two programs:

  tangle

  This program extracts the code from the document and formats it into a Pascal, C, C++, Fortran77, Fortran90, or a Ratfor program.

  • The code in the input document must be explained in a top-down fashion.
  • Various code fragments are likely to appear in the input document out of machine order, although they would be usually represented in a logical order that is more natural for a human reader.
  • The task of tangle is to untangle the WEB code and to write all code fragments in their machine order.
  • The reason why tangle is called tangle and not untangle, is because the original WEB order is considered natural, whereas the machine order is thought of as unnatural - to a human reader anyway.
  • Some people can't cope with it. Many professional professional programmers can.

  weave

  This program takes the WEB file as it is, and converts it into a TEX or a L^ATEX input file (depending on options).

  • Either TEX or L^ATEX with all their mathematical and code text formatting abilities can then be called to generate a .dvi file.
  • The .dvi file is then filtered and sent to a programmable phototypesetter, most commonly a PostScript printer.

• Working with WEB is immensely difficult and fraud with dangers. A WEB programmer must know intimately:
  • a programming language of choice
  • TeX or LaTeX, preferably both
  • WEB
  A WEB programmer must know how to debug all of the above. Simultaneously.
• Symbolic debuggers that are run on object files will generate line numbers referring to an object language file, e.g., an .f90 file, not to the WEB input file. This can be easily fixed in C, but not in Fortran.
• In spite of all the WEB complexities some professional programmers and programming scientists hold WEB in great regard:

  I am grateful to Donald E. Knuth and his colleagues for producing the TEX text formatting system, which was used to produce and typeset the manuscript. Knuth did an especially good job of publishing the program for TeX; I had to consult the code about eight times while debugging particularly complicated macros. Thanks to the extensive indexing and cross-references, in each case it took me less than five minutes to find the relevant fragment of that 500-page program.

  Guy L. Steele, Jr,  ``Common Lisp, the Language''

• This combination of annotations and code in a single document is referred to as Literate Programming.
• The original WEB by Donald Knuth worked with Pascal only.
• CWEB , written later by Silvio Levy , supported C.
• Spider-WEB , by Ramsey and Brigg , can be customised to support any Algol like language, e.g., C, Pascal, Modula-II, but not Fortran or Lisp.
• FWEB , derived from CWEB-0.5, was developed by John Krommes  from the Princeton Plasma Physics Laboratory : the best WEB around. Supports and understands syntax of:
  • C and C++
  • Fortran-77  and Fortran-90 
  • Ratfor-77  and Ratfor-90 
  • TEX itself, i.e., you can use FWEB to write TEX programs
  • The verbatim mode, i.e., every other language around, e.g., Lisp - but in this case FWEB does not understand the syntax and does not format the code
• Different FWEB supported languages can be used in a single FWEB document.
• Has a built-in C-like macro preprocessor. Very useful for Fortran and Ratfor codes. Certain extensions, e.g., variable numbers, make it useful for C and C++ too. 
• FWEB's default behaviour can be customized by editing an fweb.sty file in one's $HOME$.

• FWEB documentation: 

  1.

  Emacs info (must run OVPIT Emacs!):

  • invoke it by typing C-h i or M-x info
  • jump all the way down by pressing M-> (i.e., Meta-greater-than, not Meta-right-arrow)
  • place your cursor on the FWEB entry and press return

  2.

  PostScript version of the same document:

  • /afs/ovpit.indiana.edu/common/teTeX/doc/fweb-1.62/fweb-600dpi.ps.gz
  • http://beige.ucs.indiana.edu/PostScript/fweb-1.62/fweb-600dpi.ps.gz

  3.

  FWEB man page, type man fweb

  4.

  PostScript version of the FWEB man page:

  • /afs/ovpit.indiana.edu/common/teTeX/doc/fweb-1.62/fweb.1.ps
  • http://beige.ucs.indiana.edu/PostScript/fweb-1.62/fweb.1.ps

  5.

  HTML document:

  • http://http://w3.pppl.gov/~krommes/fweb_toc.html