Download The FunnelWeb tutorial

1.1 What Is Literate Programming?
typesetter, resulting in documentation that has the same
presentation as an ordinary typeset document. Second, because the
literate programming utility sees all the code, it can use its
knowledge of the programming language and the features of the
typesetting language to typeset the program code as if it were
appearing in a technical journal. It is the difference between:
while sloth<walrus loop
sloth:=sloth+1;
end loop
and
while sloth <walrus loop
sloth =sloth +1;
end loop
Unfortunately, while FunnelWeb provides full typesetting of the documentation,
it typesets all of its code in the style of the first of these two examples. To
typeset in the style of the second requires knowledge of the programming
language, and the current version of FunnelWeb is programming language
independent. At a later stage, it is possible that FunnelWeb will be modified to
read in a file containing information about the target programming language to
be used to assist in typesetting the code properly.
Cross referencing: Because the literate tool sees all the code and
documentation, it is able to generate extensive cross referencing
information in the typeset documentation. This makes the printed
program document more easy to navigate and partially compensates
for the lack of an automatic searching facility when reading printed
documentation.
In the end, the details don't matter. The most significant benefit that literate
programming offers is its capacity to transform the state of mind of the
programmer . It is well known that the act of explaining something can
transform one's understanding of it. This is one of the justifications behind the
powerful combination of research and teaching in universities [Rosovsky90].
Similarly, by constantly explaining the unfolding program code in English to an
imaginary reader, the programmer transforms his perception of the code, laying
it open, prone, to the critical eye.
The result of this exposure is a higher quality of programming. When exposed to
the harsh light of the literate eye, bugs crawl out, special cases vanish, and
sloppy code evaporates. As a rule, literate programs take longer to write than
ordinary programs, but the total development time is the same or less because
the time taken to write and document the program carefully is compensated for
by a reduced debugging and maintenance time. Thus literate programming does
not merely assist in the preparation of documentation, but also makes significant
contributes to the process of programming itself. In practice this has turned out
http://www.ross.net/funnelweb/tutorial/intro_what.html (3 of 4) [3/3/2000 9:44:55 PM]