Next: A simple FWEB example
Up: Caring, Really Caring About
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'
gligf02 = glegf02(a)
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
gligf02 = r_new * exp(-x + a * log(x))
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:
- In order to explain the meaning of the code you have to:
- Quote the continued fraction expansion for the
- Demonstrate or quote the way that the
continued fraction expansion is rewritten in terms
of a recursive relationship.
- Show the precise form that the recursive relationship
assumes in this case.
- Describe the mapping between the recursive relationship
and the code.
- Discuss any simplifications or shortcuts present in
- Discuss the convergence criterion employed by the
- 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
- 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
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
- 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
- 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
- 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.
- This program takes the WEB file as it is,
and converts it into a TEX or a LATEX input
file (depending on options).
- Either TEX
or LATEX 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 WEB programmer must know how to debug all of the above.
- a programming language of choice
- TeX or LaTeX, preferably both
- 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
- 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
- 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
- FWEB documentation:
- Emacs info (must run OVPIT Emacs!):
- invoke it by typing C-h i
or M-x info
- jump all the way down by pressing
(i.e., Meta-greater-than, not
- place your cursor on the FWEB entry
and press return
- PostScript version of the same document:
- FWEB man page, type
- PostScript version of the FWEB man page:
- HTML document:
Next: A simple FWEB example
Up: Caring, Really Caring About