1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
|
<HTML>
<!--
***********************************************************************
FUNNELWEB MANUAL WEB PAGE
=========================
Copyright (c) Ross N. Williams 1992,1999. All rights reserved.
Permission is granted to redistribute and use this manual in
any medium, with or without modification, provided that all
notices (including, without limitation, the copyright
notice, this permission notice, any record of modification,
and all legal notices) are preserved on all copies, that all
modifications are clearly marked, and that modified versions
are not represented as the original version unless all the
modifications since the manual's original release by Ross N.
Williams (www.ross.net) consist of translations or other
transformations that alter only the manual's form, not its
content. THIS MANUAL IS PROVIDED "AS IS" AND WITHOUT ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT
LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND
FITNESS FOR A PARTICULAR PURPOSE. TO THE EXTENT PERMITTED BY
LAW THERE IS ABSOLUTELY NO WARRANTY.
***********************************************************************
-->
<HEAD>
<TITLE>1.1 What Is Literate Programming?</TITLE>
<STYLE TYPE="text/css"> <!-- A {text-decoration: none} // --> </STYLE>
</HEAD>
<BODY BACKGROUND="binary/background.gif"
BGCOLOR="#FFFFFF"
TEXT="#000000"
VLINK="#660000"
LINK="#FF0000"
ALINK="#CC0000">
<TABLE WIDTH="490">
<TR>
<TD WIDTH="130" VALIGN="top">
<IMG SRC="binary/d_clear.gif" ALT="" WIDTH="130" HEIGHT="1"><BR>
<FONT SIZE="2">
<BR>
<A HREF="http://www.ross.net/"
TARGET="rosshome"
onClick="window.open('','rosshome','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
>
<IMG SRC="binary/rossnet_logo.gif"
WIDTH="64" HEIGHT="32"
BORDER="0" ALT="RossNet"
HSPACE="0" VSPACE="1"></A><BR>
<BR>
<A HREF="../index.shtml"
TARGET="funnelweb"
onClick="window.open('','funnelweb','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
>
<IMG SRC="binary/linklogo.gif"
WIDTH="64" HEIGHT="32"
BORDER="0" ALT="FunnelWeb"
HSPACE="0" VSPACE="1"></A><BR>
<BR>
<TABLE CELLSPACING=0 CELLPADDING=0 BORDER=0><TR><TD BGCOLOR="#000000">
<A HREF="../reference/index.html"
TARGET="funnelwebreference"
onClick="window.open('','funnelwebreference','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
><FONT COLOR="#FFFFFF"><B>Reference</B></FONT></A><BR>
<BR>
<A HREF="../developer/index.html"
TARGET="funnelwebdeveloper"
onClick="window.open('','funnelwebdeveloper','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
><FONT COLOR="#FFFFFF"><B>Developer</B></FONT></A><BR>
<BR>
<A HREF="index.html"><FONT COLOR="#FFFFFF"><B>Tutorial</B></FONT></A><BR>
<A HREF="intro.html"><FONT COLOR="#FFFFFF">1 Introduction</FONT></A><BR>
<A HREF="macro.html"><FONT COLOR="#FFFFFF">2 Macros</FONT></A><BR>
<A HREF="type.html"><FONT COLOR="#FFFFFF">3 Typesetting</FONT></A><BR>
<A HREF="example.html"><FONT COLOR="#FFFFFF">4 Example</FONT></A><BR>
<A HREF="hints.html"><FONT COLOR="#FFFFFF">5 Hints</FONT></A><BR>
<A HREF="examples.html"><FONT COLOR="#FFFFFF">6 Examples</FONT></A><BR>
<A HREF="web.html"><FONT COLOR="#FFFFFF">7 Webmaking</FONT></A><BR>
<BR>
<A HREF="search.html"><FONT COLOR="#FFFFFF"><B>SEARCH</B></FONT></A><BR>
</FONT>
</TD></TR></TABLE>
</TD>
<TD WIDTH="360" VALIGN="top">
<FONT SIZE="3">
<A HREF="../reference/index.html"><IMG SRC="binary/title.gif"
WIDTH="302" HEIGHT="24"
BORDER="0" ALT="FunnelWeb Tutorial Manual"
HSPACE="0" VSPACE="0"></A>
<P><FONT SIZE="5">1.1 What Is Literate Programming?</FONT><BR>
<P>A traditional computer program consists of a text file
containing program code. Scattered in amongst the program
code are comments which describe the various parts of the
code.
<P>In <STRONG>literate programming</STRONG> the emphasis is
reversed. Instead of writing code containing documentation,
the literate programmer writes documentation containing
code. No longer does the English commentary injected into a
program have to be hidden in comment delimiters at the top
of the file, or under procedure headings, or at the end of
lines. Instead, it is wrenched into the daylight and made
the main focus. The "program" then becomes primarily
a document directed at humans, with the code being herded
between "code delimiters" from where it can be
extracted and shuffled out sideways to the language system
by literate programming tools.
<P>The effect of this simple shift of emphasis can be so
profound as to change one's whole approach to programming.
Under the literate programming paradigm, the central
activity of programming becomes that of conveying meaning to
other intelligent beings rather than merely convincing the
computer to behave in a particular way. It is the difference
between performing and exposing a magic trick.
<P>In order to program in a literate style, particular
tools are required. The
traditional approach (used in the FunnelWeb system) is to
have some sort of text-file-in/text-file-out utility that
reads a literate program (containing a program commentary
peppered with scraps of program text) and writes out a file
containing all the program code and a file containing
typesetter commands representing the entire input document,
documentation, code, and all. See the diagram below.
<P>
<PRE>
+-----------------------------------------+
| File containing the program description |
| peppered with scraps of program code. |
| This is what the programmer works on. |
| (e.g. sloth.web) |
+-----------------------------------------+
|
v
o---------------------------o
| Literate Programming Tool |
o---------------------------o
|
+------------+-------------+
| |
v v
+------------------+ +--------------------------+
| Traditional | | Documentation file |
| Computer Program | | (e.g. sloth.tex) |
| (e.g. sloth.c) | | (e.g. sloth.html) |
+------------------+ +--------------------------+
</PRE>
<CENTER><B>Traditional architecture of literate programming tools.</B><BR></CENTER>
<BLOCKQUOTE>
<FONT SIZE="2">
Literate programming tools could be organized in a number of
ways. However, to fit in with current file and command line
based environments, most tools conform to the traditional
architecture shown here in which the user feeds in a file
containing a literate program, and the literate programming
utility generates program files and a documentation file.
</FONT>
</BLOCKQUOTE>
<P>Given the coming age of hypertext
systems, this is probably not the best approach. However, it
does mesh beautifully with current text files and command
line interfaces, the expectation of linear presentations in
the documents we read, and the particular requirements of
current programming languages and typesetting systems. It is
certainly not a bad approach.
<P>With this structure in place, the literate programming
system can provide far more than just a reversal of the
priority of comments and code. In its full blown form, a
good literate programming facility can provide total support
for the essential thrust of literate programming, which is
that computer programs should be written more for the human
reader than for the compiler. In particular, a literate
programming system can provide:
<P><BLOCKQUOTE><B>Re-ordering of code:</B> Programming languages
often force the programmer to give the various parts of a
computer program in a particular
order. For example, the
Pascal programming language<STRONG>[BSI82]</STRONG>
imposes the ordering: constants, types, variables,
procedures, code. Pascal also requires that procedures
appear in an order consistent with the partial ordering
imposed by the static call graph (but forward declarations
allow this to be bypassed). In contrast, the literate style
requires that the programmer be free to present the computer
program in any order whatsoever. The facility to do this is
implemented in literate programming tools by providing text
<I>macros</I> that can be defined and used in any order.</BLOCKQUOTE>
<P><BLOCKQUOTE><B>Typeset code and
documentation:</B> Traditionally program listings are dull
affairs consisting of pages of fan-form paper imprinted with
meandering coastlines of structured text in a boring font.
In contrast, literate programming systems are capable of
producing documentation that is superior in two ways. First,
because most of the documentation text is fed straight to
the typesetter, the programmer can make use of all the power
of the underlying 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:</BLOCKQUOTE>
<P>
<PRE>
while sloth<walrus loop
sloth:=sloth+1;
end loop
</PRE>
and
<DL>
<DT>
<DL>
<STRONG>while</STRONG> <I>sloth</I> <<I>walrus</I> <STRONG>loop</STRONG><BR>
<I>sloth</I> =<I>sloth</I> +1;<BR>
<STRONG>end</STRONG> <STRONG>loop</STRONG>
</DL>
</DL>
<P>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.
<P><BLOCKQUOTE><B>Cross referencing:</B> 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.</BLOCKQUOTE>
<P>In the end, the details don't matter. The most
significant benefit that literate programming offers is
<I>its capacity to transform the state of mind of the
programmer</I> . 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 <STRONG>[Rosovsky90]</STRONG>.
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.
<P>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 to be a contribution far more
important than the mere capacity to produce typeset
documentation.
<P>For more information on literate programming, the
reader is directed to Knuth's early founding work
<STRONG>[Knuth83]</STRONG> and <STRONG>[Knuth84]</STRONG>. For more
recent information refer to <STRONG>[Smith91]</STRONG>, which
provides a comprehensive bibliography up to 1990.
<P>
<TABLE WIDTH="100%">
<TR>
<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>
<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>
<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>
</TR>
</TABLE>
<HR>
<FONT SIZE="2">
<A HREF="mailto:webmaster@ross.net">Webmaster</A>
<A HREF="copyright.html">Copyright © Ross N. Williams 1992,1999. All rights reserved.</A><BR>
</FONT>
</FONT>
</TD>
</TR>
</TABLE>
</BODY>
<!-- *********************************************************************** -->
<!-- End Of A FunnelWeb Manual Web Page (www.ross.net/funnelweb/) -->
<!-- *********************************************************************** -->
</HTML>
|
