4
***********************************************************************
5
FUNNELWEB MANUAL WEB PAGE
6
=========================
7
Copyright (c) Ross N. Williams 1992,1999. All rights reserved.
9
Permission is granted to redistribute and use this manual in
10
any medium, with or without modification, provided that all
11
notices (including, without limitation, the copyright
12
notice, this permission notice, any record of modification,
13
and all legal notices) are preserved on all copies, that all
14
modifications are clearly marked, and that modified versions
15
are not represented as the original version unless all the
16
modifications since the manual's original release by Ross N.
17
Williams (www.ross.net) consist of translations or other
18
transformations that alter only the manual's form, not its
19
content. THIS MANUAL IS PROVIDED "AS IS" AND WITHOUT ANY
20
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT
21
LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND
22
FITNESS FOR A PARTICULAR PURPOSE. TO THE EXTENT PERMITTED BY
23
LAW THERE IS ABSOLUTELY NO WARRANTY.
25
***********************************************************************
29
<TITLE>1.1 What Is Literate Programming?</TITLE>
30
<STYLE TYPE="text/css"> <!-- A {text-decoration: none} // --> </STYLE>
32
<BODY BACKGROUND="binary/background.gif"
41
<TD WIDTH="130" VALIGN="top">
42
<IMG SRC="binary/d_clear.gif" ALT="" WIDTH="130" HEIGHT="1"><BR>
47
<A HREF="http://www.ross.net/"
49
onClick="window.open('','rosshome','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
51
<IMG SRC="binary/rossnet_logo.gif"
52
WIDTH="64" HEIGHT="32"
53
BORDER="0" ALT="RossNet"
54
HSPACE="0" VSPACE="1"></A><BR>
57
<A HREF="../index.shtml"
59
onClick="window.open('','funnelweb','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
61
<IMG SRC="binary/linklogo.gif"
62
WIDTH="64" HEIGHT="32"
63
BORDER="0" ALT="FunnelWeb"
64
HSPACE="0" VSPACE="1"></A><BR>
66
<TABLE CELLSPACING=0 CELLPADDING=0 BORDER=0><TR><TD BGCOLOR="#000000">
67
<A HREF="../reference/index.html"
68
TARGET="funnelwebreference"
69
onClick="window.open('','funnelwebreference','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
70
><FONT COLOR="#FFFFFF"><B>Reference</B></FONT></A><BR>
72
<A HREF="../developer/index.html"
73
TARGET="funnelwebdeveloper"
74
onClick="window.open('','funnelwebdeveloper','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
75
><FONT COLOR="#FFFFFF"><B>Developer</B></FONT></A><BR>
77
<A HREF="index.html"><FONT COLOR="#FFFFFF"><B>Tutorial</B></FONT></A><BR>
78
<A HREF="intro.html"><FONT COLOR="#FFFFFF">1 Introduction</FONT></A><BR>
79
<A HREF="macro.html"><FONT COLOR="#FFFFFF">2 Macros</FONT></A><BR>
80
<A HREF="type.html"><FONT COLOR="#FFFFFF">3 Typesetting</FONT></A><BR>
81
<A HREF="example.html"><FONT COLOR="#FFFFFF">4 Example</FONT></A><BR>
82
<A HREF="hints.html"><FONT COLOR="#FFFFFF">5 Hints</FONT></A><BR>
83
<A HREF="examples.html"><FONT COLOR="#FFFFFF">6 Examples</FONT></A><BR>
84
<A HREF="web.html"><FONT COLOR="#FFFFFF">7 Webmaking</FONT></A><BR>
87
<A HREF="search.html"><FONT COLOR="#FFFFFF"><B>SEARCH</B></FONT></A><BR>
93
<TD WIDTH="360" VALIGN="top">
97
<A HREF="../reference/index.html"><IMG SRC="binary/title.gif"
98
WIDTH="302" HEIGHT="24"
99
BORDER="0" ALT="FunnelWeb Tutorial Manual"
100
HSPACE="0" VSPACE="0"></A>
101
<P><FONT SIZE="5">1.1 What Is Literate Programming?</FONT><BR>
105
<P>A traditional computer program consists of a text file
106
containing program code. Scattered in amongst the program
107
code are comments which describe the various parts of the
110
<P>In <STRONG>literate programming</STRONG> the emphasis is
111
reversed. Instead of writing code containing documentation,
112
the literate programmer writes documentation containing
113
code. No longer does the English commentary injected into a
114
program have to be hidden in comment delimiters at the top
115
of the file, or under procedure headings, or at the end of
116
lines. Instead, it is wrenched into the daylight and made
117
the main focus. The "program" then becomes primarily
118
a document directed at humans, with the code being herded
119
between "code delimiters" from where it can be
120
extracted and shuffled out sideways to the language system
121
by literate programming tools.
123
<P>The effect of this simple shift of emphasis can be so
124
profound as to change one's whole approach to programming.
125
Under the literate programming paradigm, the central
126
activity of programming becomes that of conveying meaning to
127
other intelligent beings rather than merely convincing the
128
computer to behave in a particular way. It is the difference
129
between performing and exposing a magic trick.
131
<P>In order to program in a literate style, particular
132
tools are required. The
133
traditional approach (used in the FunnelWeb system) is to
134
have some sort of text-file-in/text-file-out utility that
135
reads a literate program (containing a program commentary
136
peppered with scraps of program text) and writes out a file
137
containing all the program code and a file containing
138
typesetter commands representing the entire input document,
139
documentation, code, and all. See the diagram below.
143
+-----------------------------------------+
144
| File containing the program description |
145
| peppered with scraps of program code. |
146
| This is what the programmer works on. |
148
+-----------------------------------------+
151
o---------------------------o
152
| Literate Programming Tool |
153
o---------------------------o
155
+------------+-------------+
158
+------------------+ +--------------------------+
159
| Traditional | | Documentation file |
160
| Computer Program | | (e.g. sloth.tex) |
161
| (e.g. sloth.c) | | (e.g. sloth.html) |
162
+------------------+ +--------------------------+
165
<CENTER><B>Traditional architecture of literate programming tools.</B><BR></CENTER>
168
Literate programming tools could be organized in a number of
169
ways. However, to fit in with current file and command line
170
based environments, most tools conform to the traditional
171
architecture shown here in which the user feeds in a file
172
containing a literate program, and the literate programming
173
utility generates program files and a documentation file.
177
<P>Given the coming age of hypertext
178
systems, this is probably not the best approach. However, it
179
does mesh beautifully with current text files and command
180
line interfaces, the expectation of linear presentations in
181
the documents we read, and the particular requirements of
182
current programming languages and typesetting systems. It is
183
certainly not a bad approach.
185
<P>With this structure in place, the literate programming
186
system can provide far more than just a reversal of the
187
priority of comments and code. In its full blown form, a
188
good literate programming facility can provide total support
189
for the essential thrust of literate programming, which is
190
that computer programs should be written more for the human
191
reader than for the compiler. In particular, a literate
192
programming system can provide:
194
<P><BLOCKQUOTE><B>Re-ordering of code:</B> Programming languages
195
often force the programmer to give the various parts of a
196
computer program in a particular
197
order. For example, the
198
Pascal programming language<STRONG>[BSI82]</STRONG>
199
imposes the ordering: constants, types, variables,
200
procedures, code. Pascal also requires that procedures
201
appear in an order consistent with the partial ordering
202
imposed by the static call graph (but forward declarations
203
allow this to be bypassed). In contrast, the literate style
204
requires that the programmer be free to present the computer
205
program in any order whatsoever. The facility to do this is
206
implemented in literate programming tools by providing text
207
<I>macros</I> that can be defined and used in any order.</BLOCKQUOTE>
209
<P><BLOCKQUOTE><B>Typeset code and
210
documentation:</B> Traditionally program listings are dull
211
affairs consisting of pages of fan-form paper imprinted with
212
meandering coastlines of structured text in a boring font.
213
In contrast, literate programming systems are capable of
214
producing documentation that is superior in two ways. First,
215
because most of the documentation text is fed straight to
216
the typesetter, the programmer can make use of all the power
217
of the underlying typesetter, resulting in documentation
218
that has the same presentation as an ordinary typeset
219
document. Second, because the literate programming utility
220
sees all the code, it can use its knowledge of the
221
programming language and the features of the typesetting
222
language to typeset the program code as if it were appearing
223
in a technical journal. It is the difference between:</BLOCKQUOTE>
227
while sloth<walrus loop
239
<STRONG>while</STRONG> <I>sloth</I> <<I>walrus</I> <STRONG>loop</STRONG><BR>
240
<I>sloth</I> =<I>sloth</I> +1;<BR>
241
<STRONG>end</STRONG> <STRONG>loop</STRONG>
247
<P>Unfortunately, while FunnelWeb provides full
248
typesetting of the documentation, it typesets all of its
249
code in the style of the first of these two examples. To
250
typeset in the style of the second requires knowledge of the
251
programming language, and the current version of FunnelWeb
252
is programming language independent. At a later stage, it is
253
possible that FunnelWeb will be modified to read in a file
254
containing information about the target programming language
255
to be used to assist in typesetting the code properly.
257
<P><BLOCKQUOTE><B>Cross referencing:</B> Because the literate tool sees all the code and
258
documentation, it is able to generate extensive cross
259
referencing information in the typeset documentation. This
260
makes the printed program document more easy to navigate and
261
partially compensates for the lack of an automatic searching
262
facility when reading printed documentation.</BLOCKQUOTE>
264
<P>In the end, the details don't matter. The most
265
significant benefit that literate programming offers is
266
<I>its capacity to transform the state of mind of the
267
programmer</I> . It is well known that the act of explaining
268
something can transform one's understanding of it. This is
269
one of the justifications behind the powerful combination of
270
research and teaching in
271
universities <STRONG>[Rosovsky90]</STRONG>.
272
Similarly, by constantly explaining the unfolding program
273
code in English to an imaginary reader, the programmer
274
transforms his perception of the code, laying it open,
275
prone, to the critical eye.
277
<P>The result of this exposure is a higher quality of
278
programming. When exposed to the harsh light of the literate
279
eye, bugs crawl out, special cases vanish, and sloppy code
280
evaporates. As a rule, literate programs take longer to write
281
than ordinary programs, but the total development
282
time is the same or less because
283
the time taken to write and document the program carefully
284
is compensated for by a reduced debugging and maintenance
285
time. Thus literate programming does not merely assist in
286
the preparation of documentation, but also makes significant
287
contributes to the process of programming itself. In
288
practice this has turned out to be a contribution far more
289
important than the mere capacity to produce typeset
292
<P>For more information on literate programming, the
293
reader is directed to Knuth's early founding work
294
<STRONG>[Knuth83]</STRONG> and <STRONG>[Knuth84]</STRONG>. For more
295
recent information refer to <STRONG>[Smith91]</STRONG>, which
296
provides a comprehensive bibliography up to 1990.
303
<TD ALIGN="left" VALIGN="bottom"><A HREF="intro.html"><IMG SRC="binary/fw_up.gif" HEIGHT="32" WIDTH="32" BORDER="0" ALT="Up"></A></TD>
304
<TD ALIGN="center" VALIGN="bottom"><A HREF="intro.html"><IMG SRC="binary/fw_up.gif" HEIGHT="32" WIDTH="32" BORDER="0" ALT="Up"></A></TD>
305
<TD ALIGN="right" VALIGN="bottom"><A HREF="intro_whatfw.html"><IMG SRC="binary/fw_right.gif" HEIGHT="32" WIDTH="32" BORDER="0" ALT="Next"></A></TD>
313
<A HREF="mailto:webmaster@ross.net">Webmaster</A>
314
<A HREF="copyright.html">Copyright © Ross N. Williams 1992,1999. All rights reserved.</A><BR>
325
<!-- *********************************************************************** -->
326
<!-- End Of A FunnelWeb Manual Web Page (www.ross.net/funnelweb/) -->
327
<!-- *********************************************************************** -->
added
removed
tutorial/intro_what.html
