The Essence of Literate Programming
Phil Bewig
When Donald Knuth invented literate programming, he designed very big
systems which included prettyprinting, macro processing and rudimentary
version control systems, among other features. Even the more modern
literate programming systems, which tend to be much smaller, include
such features as automatic indexing of code chunks and identifiers. But
the essence of literate programming is simply the rearranging of chunks
of code, from an order which is convenient for the programmer to an
order which is convenient for the compiler.
Described below is a complete literate programming system which is
implemented in a dozen and a half lines of awk. It has almost no
features. Input files consist of text, which is ignored, and chunks of
code, which are rearranged as indicated by the programmer. This
document is itself a literate program.
The form of the input file is very simple. Code chunks are introduced
by a line beginning with double less-than signs and ending with double
greater-than signs and an equals sign; there may be no white space at
the beginning or end of the line. Code chunks are referenced on any
line within another code chunk by surrounding the name of the chunk,
which must exactly match the name given on the definition line, with
double less-than and greater-than signs; there may be only one reference
per line. A code chunk ends at the first blank line following its
beginning, or at the end of the file, whichever comes sooner.
The action of the essential literate programming system is to read an
input file, expand a root chunk named "*", and write the expanded file
to standard output; that is, it performs the functions of the tangle
program of most other literate programming systems. The program looks
like this:
<<*>>=
<<read input and store chunks>>
END { <<output tangled file>> }
<<recursively tangle a chunk>>
Reading the input file is simple. Lines are read and ignored until a
chunk definition line is seen. Then, all of the following non-blank
lines are saved. After the end of a chunk, lines are again read and
ignored until the next chunk definition line is seen.
<<read input and store chunks>>=
/^<<.+>>=$/ {
name = substr($0, 3, length($0) - 5)
while (getline > 0) {
if (length($0) == 0) next
chunk[name, ++count[name]] = $0 } }
It is necessary that the tangled output file preserve the indentation of
the input, so that code included by reference is aligned at the same
relative level of indentation as the reference itself. Function tangle
takes two arguments: a chunk name to expand and a string containing the
necessary white space to be prepended to each output line. Whenever
tangle sees a code reference, it calls itself recursively to include the
referenced code.
<<recursively tangle a chunk>>=
function tangle(name, prefix, i, tag, suffix) {
for (i = 1; i <= count[name]; i++) {
if (i == 2) gsub(/[^ \t]/, " ", prefix)
if (match(chunk[name,i], /<<.+>>/)) {
tag = substr(chunk[name,i], RSTART + 2, RLENGTH - 4)
if (tag in count) {
suffix = substr(chunk[name,i], RSTART + RLENGTH)
tangle(tag, prefix substr(chunk[name,i], 1, RSTART - 1))
printf "%s", suffix }
else printf "%s%s", prefix, chunk[name,i] }
else printf "%s%s", prefix, chunk[name,i]
if (i < count[name]) printf "\n" } }
Basically, tangle encodes a depth-first search through the chunk-call
graph, replacing each reference to a chunk with the text of the chunk.
Keeping prefixes and suffixes straight adds some complication. Newlines
are never printed at the end of a chunk, so that the suffix of the
calling chunk can be printed. Likewise, that portion of an input line
which precedes a chunk reference is passed to the lower-level chunk as
part of the prefix, so it is printed at the beginning of the first line
of the lower-level chunk.
To write the output, all that is necessary is to start the recursive
process of tangling the file by tangling the "*" chunk with no prefix.
A printf adds the newline that ends the "*" chunk.
<<output tangled file>>=
tangle("*", ""); printf "\n"
That's all there is. Unlike other literate programming systems, there
is no weave command. The input file *is* the woven output. Simple,
plain ascii. No formatting commands. No index of identifiers. No
cross-referencing of chunks. Nothing.
In fact, for programmers who are writing or maintaining a literate
program, nothing else is necessary. Most of the time, you only see your
code from within your favorite editor. Prettyprinting isn't available
there, and searching with your editor is more convenient than a printed
index of your program which is probably out of date anyway. The essence
of literate programming is rearranging chunks of code, and a dozen and a
half lines of awk is all you need for that.
Of course, with so little code it's not possible for everything to be
perfect. There is no checking for bad or missing chunks. Cycles in the
input will cause an infinite loop. And, worst of all, if your language
uses double less-than or greater-than signs as an operator, the program
can become confused. Even so, this microscopic system provides a useful
tool that encompasses the essence of literate programming.
--
Phil Bewig ... pbe...@netcom.COM
cameron
Phil Bewig (pbe...@netcom.com) wrote:
> [... T]he essence of literate programming is simply the rearranging of
> chunks of code, from an order which is convenient for the programmer to
> an order which is convenient for the compiler.
While I might be persuaded to agree that this is a necessary feature for
a tool to posess in order for that tool to qualify as a literate programming
tool, I draw the line at the claim that rearranging chunks of code is the
essence of literate programming.
Literate programming (to me, anyway) means writing programs as pieces
of literature. It means writing programs at least to the standards
of the literature of computer science (i.e., clearly enough to meet
the editorial standards of a refereed journal), if not to the standards
of great works of literature. It means, more than anything else, writing
programs as if human beings were the primary audience, with the needs
of a particular compiler or interpreter taking a back seat to the needs
of the human beings who must read and understand the software.
The fact that, in order to have the freedom to take this approach
and still produce a workable program, the author must have the ability
to present code in a different order than the compiler needs, and the
fact that a tool must provide this ability if it claims to support
literate programming, is incidental.
I'm especially concerned by the reference to "an order which is
convenient for the programmer" in opposition to "an order which is
convenient for the compiler", as if the programmer and the compiler
were the only players involved. To me, this misses the point.
Literate programming not only doesn't mean "write the program for the
convenience of the compiler", but it ALSO does NOT mean "write the program
for the convenience of the programmer". It means "write the program
for the understanding of a later, human reader, who may or may not
(but probably won't) be the original programmer". If all you want as a
programmer is the freedom to write code in a different order than that
in which the compiler will compile it or the processor will execute it,
then you only need a macro processor, or maybe even only a language that
supports subroutines. (In fact, it could be argued that your *text editor*
lets you write code in any order you want -- granted, the code may have
to appear in a certain sequence in the final document, but as long as
your editor supports jumping back and forth in the document, you can write
the lines of code in any order in which they occur to you.) Literate
programming means writing a literate exposition of your program, with an
account of the algorithms and data structures it uses (and why they are
the right ones to use), the environment in which the program will run
(and what changes in that environment can and cannot be made without
breaking the program), etc. etc. etc.
Programming literately implies that the programmer has an obligation to
do more than just provide a working program; s/he must also explain and
justify the code. This says a lot more about what is required of the
programmer than it does about what is required of the programmer's tools.
That is why a lot of programs written with tools that are unarguably
"literate programming tools" are still not "literate programs".
(If I remember correctly, Norman Ramsey himself puts the programs for
noweb in this category, according to statements in the text files that
accompany the noweb distribution).
A lot of the discussion about what literate programming tools must do
is (IMHO) misplaced or futile. If programmers aren't willing to write
genuinely literate programs, what difference does it make whether or not
they have genuine literate programming tools?
I have had a book and several articles published, so I have some opinions
about what kind of effort is required to do a good job in those activities.
(Not just "how much effort", but "what kind" -- i.e. what things a writer
has to pay attention to and worry about in order to produce a good result.)
I've been programming for almost twenty years, so I have opinions about
that too. For the last five or six years have tried hard to write
literate programs, and I haven't found that to be any easier than the
other forms of writing I've done, and I've found it to be lots harder
than banging out code. I do feel more confident of the correctness and
robustness of the literate programs I've written than of the non-literate
ones, and so I deem the extra effort to be worth it (on all but throw-away
programs, anyway... and how often does a program written as a throw-away
actually get thrown away?). But I do NOT feel that "the essence of literate
programming is being able to rearrange chunks of code". That's an
enabling technology, but not the essence by any means.
But to the extent that Phil's example (of a very short but functional
"tangle" program) makes the point that you don't absolutely need big
tools to do literate programming, I agree.
(For what it's worth, my runaway favorite litprog tool is noweb,
which as far as I know pioneered the "small tools" approach to
literate programming. Even though it has now grown into quite a
large system, it grew in small steps, with pieces contributed by
many authors, which was enabled by its modular design. And it was
already a useful tool from the start, before most of these add-ons
were built. For that matter, I don't use even half of the applets
that come with the noweb distribution, and I've customized some of
what I do use -- I didn't have to, but I wanted to, and it's nice
that the tool's open design allows this.)
> Phil Bewig ... pbe...@netcom.COM
--Cameron Smith
cam...@dnaco.net
Norman Ramsey
In article <pbewigDs...@netcom.com>, Phil Bewig <pbe...@netcom.com> wrote:
>
>When Donald Knuth invented literate programming, he designed very big
>systems which included prettyprinting, macro processing and rudimentary
>version control systems, among other features. Even the more modern
>literate programming systems, which tend to be much smaller, include
>such features as automatic indexing of code chunks and identifiers. But
>the essence of literate programming is simply the rearranging of chunks
I'm highly amused. You have wandered down the same path I followed in
1988, when I was asking myself ``how many features can we remove from
WEB and still call it a literate-programming tool?'' I came to
similar conclusion about writing code chunks in any order being
essential, but I agree with Cameron Smith that is it also essnetial to
plan for hte human reader, and I don't think flat ASCII documentation
does a very good job---the leverage I get from diagrams (and for some
programs, mathematics) is too much to give up.
I'm also amused that you've duplicated part of my implementation path,
although noweb was written in C from the beginning, and it has always
supported extraction of any chunk by name (not just <<*>>). Also,
noweb very quickly acquired support for #line and friends as people
got to use it for real software. Other than that, notangle has
remained pretty much unchanged since 1989.
Noweave, on the other hand, has turned into a monster, both in the
command itself (too many options!) and in the supporting macros.
There are a few things I am happy with:
- support for Tex, LaTeX, and HTML, and LaTeX or HTML from one document
- the ``take it or leave it'' attitude toward prettyprinting and indexing
- the extensibility
But I confess that these days I mostly ask myself ``how could I take
most of the features out of noweave without crippling myself and
annoying all my users?'' :-(
Norman
P.S. Actually, what I really want is support for references *between*
--
Norman Ramsey
http://www.cs.purdue.edu/homes/nr
Phil Bewig
cam...@sisko.dnaco.net (cameron) writes:
>Phil Bewig (pbe...@netcom.com) wrote:
>> [... T]he essence of literate programming is simply the rearranging of
>> chunks of code, from an order which is convenient for the programmer to
>> an order which is convenient for the compiler.
>While I might be persuaded to agree that this is a necessary feature for
>a tool to posess in order for that tool to qualify as a literate programming
>tool, I draw the line at the claim that rearranging chunks of code is the
>essence of literate programming.
>Literate programming (to me, anyway) means writing programs as pieces
>of literature. It means writing programs at least to the standards
>of the literature of computer science (i.e., clearly enough to meet
>the editorial standards of a refereed journal), if not to the standards
>of great works of literature. It means, more than anything else, writing
>programs as if human beings were the primary audience, with the needs
>of a particular compiler or interpreter taking a back seat to the needs
>of the human beings who must read and understand the software.
Hmmm, ... well, yes. You are right, of course. Perhaps I was
writing more from the point of view of the tool than the point
of view of the product.
On the other hand, I don't think a single one of my literate
programs would meet the editorial standards of a refereed journal.
I tend to write very little in my literate programs. When I
introduce a flag variable that takes only few possible values,
I note each possible value in a table. I tend to describe data
structures in a few sentences of prose, or sometimes a diagram.
I tend not to describe algorithms, because the code does that.
And I find that properly splitting the program into small chunks
that do one small thing, and describing the function of that small
chunk in the chunk name, is sufficient for most of my code.
I am not trying to start an argument. Literate programming is
big enough to encompass different points of view. Whether you
want to be more or less "literate" is up to you. My main point
in writing what I did is that adding features to literate
programming systems (indexing, cross-referencing, prettyprinting)
doesn't add lots of value; the point of diminishing returns is
very quickly reached.
By the way, I am both a user of and a contributor to noweb.
Phil
felix gaertner
In article <pbewigDs...@netcom.com>, pbe...@netcom.com (Phil Bewig) writes:
> cam...@sisko.dnaco.net (cameron) writes:
>
> >Phil Bewig (pbe...@netcom.com) wrote:
> >> [... T]he essence of literate programming is simply the rearranging of
> >> chunks of code, from an order which is convenient for the programmer to
> >> an order which is convenient for the compiler.
>
> >While I might be persuaded to agree that this is a necessary feature for
> >a tool to posess in order for that tool to qualify as a literate programming
> >tool, I draw the line at the claim that rearranging chunks of code is the
> >essence of literate programming.
>
> >programs as if human beings were the primary audience, with the needs
> >of a particular compiler or interpreter taking a back seat to the needs
> >of the human beings who must read and understand the software.
I agree with Cameron that the essence lies not in the tools you have, but
in the way of thinking about a program. In a recent talk I gave on this
subject I compared the process of literate programming with a meeting of
a group of programmers in which every programmer presented his piece of
code and explained why s/he wrote it the way it turned out to be. Thinking
of this kind of szenario while you work on a piece of code helps a lot.
Someone in this newsgroup called this ``working in expository mode''
(which gets to the point quite well).
With this main concern in mind, a few things follow:
- Because you are writing for human beings, you want to present the
code in the best understandable way for your reader(s).
=> rearranging facilities are needed if the language you use is too
unflexible
- Because you are writing for human beings, you want to use the best
tools available to express what you want to do in writing
=> a document formatting language is needed to write your prose in;
it should enable you to express everything you want to easily
(figures, tables, mathematical formulas, ...) [I'm not saying
that this language should be TeX]
- Because you are writing for human beings, you want to use the best
tools available to retrieve information from your program
=> tools that support indexing, building tables of contents,
glossaries etc. are needed.
- Because you are writing for human beings, you want to present your
code in an aesthetically pleasant fashion that makes it easier and
more enjoyable to read
=> you'll need prettyprinting and high quality printed output of
your program
- Because you are writing for human beings, you want to express yourself
clearly, concisely and pleasantly
=> practise your expository skills and learn how to ``write good,
helpful English, and that's tough'' (Preston Briggs)
Cheers,
Felix
cameron
I wrote:
>> Literate programming (to me, anyway) means writing programs as pieces
>> of literature. It means writing programs at least to the standards
>> of the literature of computer science (i.e., clearly enough to meet
>> the editorial standards of a refereed journal), if not to the standards
Phil Bewig (pbe...@netcom.com) replied:
> [...] I don't think a single one of my literate
> programs would meet the editorial standards of a refereed journal.
> I tend to write very little in my literate programs.
> [...comments about Phil's literate coding style...]
> I am not trying to start an argument. Literate programming is
> big enough to encompass different points of view. Whether you
> want to be more or less "literate" is up to you. [...]
Believe me, I'm not trying to start an argument either, and I hope I
won't give that impression if I make a few more remarks. But as
long as we're in a newsgroup devoted to discussions about literate
programming, I thought I'd take one more shot at clarifying (if only
for myself) what I think makes the difference between a well-commented
ordinary program and a genuinely literate program.
First of all, I may have gone a *teeny* bit overboard in making
journal-publication standards the litmus test for whether a program
is literate. Nevertheless I do think that that is the direction
in which literate programming should aim.
At a bare minimum, I would say that the threshold of "literateness"
(as opposed to "literacy", which refers to the reader rather than
the program?) is crossed when the documented program (or each major
subdivision of it, if the program itself is too large) can be read
from front to back and give the impression of being a complete and
coherent exposition. But if it reads as a series of chunks of code,
some of which happen to have helpful wads of English text glued on the
front of them, then it ain't literate programming, it's just fancy
commenting, even if it's beautifully typeset in TeX with lots of
pretty PostScript diagrams thrown in.
I'm not saying that there isn't a place for that kind of program --
that may be sufficient for certain types of project, and it's certainly
a damn sight better than most program documentation ever gets.
And as you say, it is up to you to decide how much is required
(and how much investment is justified) in each project.
I also feel that this is an appropriate time for me to mention that
I'm somewhat amused/amazed by what seems to be a consensus (judging
from articles I've seen in this group lately) that most of the practice
of literate programming is in academic rather than commercial settings.
I'd like to throw in my two cents' worth: *ALL* the literate programming
I've ever done has been commercial. And I'm certain that this has
influenced my idea of what the standard for literateness should be.
I worked for several years as a roving programmer-for-hire, first as a
free-lance consultant, and later as an employee of a contracting firm.
I got into the habit of producing my work product in the form of a
literate program, with the woven and typeset document being one of the
contract deliverables. Every customer to whom I've delivered such a
document has been happy to get it (some even ecstatic), and not one has
ever suggested that the time required to produce it was not well spent.
However, when you're creating a document to be read not just by another
staff programmer in your own company, or informally by a fellow academic,
but by a paying customer from whom you hope to obtain future business,
I assure you that you're a lot more sensitive to the impression that your
work creates, and a lot more anxious to ensure that your document is
coherent. After all, the customer isn't likely to consult your document
until he's in trouble -- he needs to fix or upgrade the program, or to
interface to it, or something -- and the last thing you want is for your
document to increase his frustration. So you try to ensure that it has
a good table of contents and an even better index, and you provide
some discussion of the context in which the program operates and the
algorithms that it uses, and you use diagrams wherever possible, and you
generally try to lead the reader by the hand through the code so he
won't get confused and make things worse.
I have a (somewhat cynical) theory about why the customers I've worked
for have been willing to pay for this kind of documentation. I suspect
that consulting/contracting differs from other software development
mainly in that the manager who brings in a hired gun is (or should
be) acutely aware that after the developer of the code is gone, the
organization is left holding the bag if the software doesn't perform
as required (or if the requirements change). For that reason, managers
may take the need for documentation more seriously for code written by
consultants than they do for code written by in-house staff, whom they
perhaps tend to view as permanent assets who will always be available
to be consulted if a problem is discovered later. (Managers who think
their staff are more permanent than their consultants are foolish, of
course -- people do change jobs, or even get hit by lightning -- but
it's never a surprise to discover yet another way that managers take
employees for granted.) That may be why I see people in this group
talking about the added cost (in time as well as money) of literate
documentation and debating when and whether it's justified, while in
my experience no one I've programmed literately for has ever even
raised that as a concern at all.
Or it may be that I'm just a nut for documentation and that I've been
lucky in working for customers who have indulged me. Similarly it may
be that people who claim to be concerned about tight schedules and
budgets are really looking for excuses not to do a lot of writing
that for them is drudgery. Presumably, however, people with that
attitude toward documentation don't hang out in comp.programming.literate.
By the way, about six weeks ago I started a new job at a totally
different kind of company. I no longer do any consulting; all my
code is now written for internal consumption and gets integrated
into a quite massive existing system. So I'm in the process of
learning how to adapt my literate habits to an environment in which
I'm adding bits and pieces onto a much larger body of code over
which I have no control. If I figure out how to work it I'll
let you know!
--Cameron Smith
cam...@dnaco.net
cameron
[ This is a repost of message <4okasl$c...@sisko.dnaco.net>, which ]
[ seems not to have made it out of my ISP's news host. We appear ]
[ to be having news feed problems both inbound and outbound here. ]
[ Forgive me if you have indeed seen this posting already. --CCS ]
Ron Paul
In article <4ofdoo$d...@sisko.dnaco.net>,
cam...@sisko.dnaco.net (cameron) wrote:
>Phil Bewig (pbe...@netcom.com) wrote:
>> [... T]he essence of literate programming is simply the rearranging of
>> chunks of code, from an order which is convenient for the programmer to
>> an order which is convenient for the compiler.
>
>While I might be persuaded to agree that this is a necessary feature for
>a tool to posess in order for that tool to qualify as a literate programming
>tool, I draw the line at the claim that rearranging chunks of code is the
>essence of literate programming.
>
>Literate programming (to me, anyway) means writing programs as pieces
>of literature.
I think this bit of mail illustrates a fundamental problem with the
development of literate programming (at least as I understand it). It focuses
on writing "programs", not on writing "software systems" which are composed
potentially of 100's or more programs, all inter-related. This is a big weak
spot that needs to be addressed if this technique is to move out of academia.
Ron Paul
Senior Engineer and Co-Founder
Emtek Healthcare Systems / Motorola Inc.
602 531-5240 (work)
1-800-sky-page #8674120 (pager)
602 279 5034 (fax)
r...@syspac.com
"Imagination is more Important than Knowledge"
"There are only two ways to live your life. One is though
nothing is a miracle. THe other is as if everything is."
- A. Einstein
Patrick TJ McPhee
In article <4ol5d3$h...@news.syspac.com>, Ron Paul <ron...@syspac.com> wrote:
% [LP] focuses on writing "programs", not on writing "software systems" which
% are composed potentially of 100's or more programs, all inter-related.
How so? All the best known LP sources are parts of larger systems. I don't
really see anything that makes LP less valid when used in that context.
--
Patrick TJ McPhee
Toronto Canada
pt...@io.org
cameron
I wrote:
>> Literate programming (to me, anyway) means writing programs as pieces
>> of literature.
Ron Paul (ron...@syspac.com) replied:
> I think this bit of mail illustrates a fundamental problem with the
> development of literate programming (at least as I understand it).
> It focuses on writing "programs", not on writing "software systems"
> which are composed potentially of 100's or more programs, all inter-related.
> This is a big weak spot that needs to be addressed if this technique is
> to move out of academia.
Ron--
I'm a bit nonplussed. As I've said, both in articles posted here and in
private email to you a few weeks ago, I have done *all* my litprog work in
commercial settings, so I already consider this technique to have "moved
out of academia". I realize it hasn't exactly taken the industry by storm,
but it is out here, and I don't quite see the point of repeatedly saying
"it'll never work in industry!" about a technique that in fact has already
done so.
You draw a distinction between writing "programs" (which I take to mean
writing *code*) and writing "software systems". What is it that you want
or expect literate programming to do for the non-code parts of a system
(the specifications, the design documents, the test plan, etc.) that you
are not already able to do?
I have used litprog techniques to document small but complete "software
systems" (collections of programs and data) in literate documents,
including specification, design and test information as well as the code.
Naturally, in the non-code parts of the documents, there are no "code
chunks", and so the source for those chapters looks like plain LaTeX markup
(which is what it is). There is nothing particularly "litproggish" about
those parts of the system documentation -- but it is nice to be able,
in the literate code, to have cross references back to the design or the
requirements, and in the test plan, it's likewise nice to be able to say
something like "Section 6 of the test plan contains coverage tests for
sections 1-4 of the code". That is one justification (among many) for
including those materials as chapters in a literate document, rather than
developing them as separate documents (although, as I've said elsewhere,
there is high value in writing certain chapters so that they also make sense
if excerpted and typeset as standalone documents).
I did say "small but complete" systems, and I admit I have not yet figured
out the best way to ease litprog techniques into use on "large and incomplete"
systems -- such as a project that already has a huge body of existing
non-literate code (in the case with which I'm presently concerned, thousands
of modules and literally millions of lines of code). That is, I know I could
start writing noweb source tomorrow, and just write my Makefiles to ensure
that (say) foo.c and foo.h are extracted from foo.nw before they are compiled.
That would let me do literate documentation on a unit-by-unit basis.
I'm just not sure that that is the most useful way to proceed. But no really
massive system is built all in a single piece: there are loosely coupled
subsystems that operate more or less independently, and I'm convinced that
if the right size subsystem is chosen as the development unit, then litprog
techniques can be applied to developing the subsystems of a large system
as well as they can to the small standalone systems that I've documented
literately in the past.
Maybe I'm missing the point of your posting altogether? Are you,
for example, simply saying that to write a "software system" you need to
be able to present many separate programs in a single document? It was
true of the original web, and may for all I know still be true of cweb,
that one document corresponded to one program, but such was never true of
noweb or nuweb (to name the two I'm most familiar with). Because notangle
lets you specify the target chunk to expand, you can extract files foo.c,
foo.h, bar.c, bar.sh, make.foobar, foo.data, and bar.test all from the same
noweb source file. (In fact, I automated this somewhat by writing a shell
script called "nodepend" -- it uses "noroots" to find the root chunks in a
noweb document and, for each root chunk whose name looks like a filename,
generates a dependency line for a Makefile that invokes notangle to extract
the named file from the noweb source.) So you can indeed document all the
components of a system in a single document. Is that what you're asking?
You may also be commenting that there is more involved in a software
project than just writing the code. Getting the code to build (especially
in a multi-platform environment) is often a big headache -- that's why I
literately document my Imakefiles and Makefiles as well as my C code.
Revision control is absolutely necessary, especially in a multi-programmer
development environment, and that's why I place my noweb sources under
the control of RCS or CVS as soon as I start a new project. Literate
documents are more useful when they have things like a glossary and
one or more indexes -- that's why I have custom LaTeX macros that I
use in preparing my literate documentation. Nobody's saying that if you
have noweb or another good litprog tool, you won't also need imake, make,
RCS, a good linker, a good debugger, and lots of other development tools.
Or is it your point (I have heard this argued) that a really effective
software development environment will have to have all these functions
integrated into a single package, and that litprog tool developers should
start thinking about how to build such a package and incorporate litprog
features? I happen not to agree, but it is a position that can be adopted
and for which arguments can be made.
I realize I'm saying "I've done this" and "I do that" a lot, and I don't
mean to over-personalize your remarks, which I'm sure weren't directed
specifically at me. It's just that you used a posting of mine to illustrate
"a fundamental problem with the development of literate programming", and
here I thought I thought I was already doing (if only in a small way) all
the things that you seem to be saying need to be done! So I am honestly
confused as to what more you're looking for. I'm trying to figure out
your comments, but (as you can see) I'm just groping. How about, instead
of simply saying "litprog won't work until it addresses the issues that
arise in engineering complete software systems", you say what specific
tasks you think litprog needs to address? I'm not asking you to solve the
problem, just to define it a bit more. If you can do that, maybe the
readership of this group can talk about how litprog techniques can be
extended to meet the needs of real software systems engineering.
I was just about to send this off, when I thought of one other thing you
might mean. You may be saying that most *people* who practice literate
programming are entirely wrapped up in writing beautifully documented code
and have little concern for the environment in which the code is built and
tested or the environment in which it must operate. If so, I agree.
Writing code is the fun part, and programmers (literate or otherwise)
prefer to focus on that. I also admit that literate *coding* was the primary
focus of the particular posting of mine from which you excerpted my comment
about "literate programming means writing programs as pieces of literature."
But I claim that this preoccupation is not inherent in the (currently
available) tools and techniques of literate programming. So instead of
saying that
> [literate programming] focuses on writing "programs", not on writing
> "software systems" [...]
I would say "literate programmers need to focus on writing systems, not
just on writing programs". It can already be done, but programmers need
to make up their minds that that's what they want to do. Which is in the
same vein as another comment of mine from the same posting:
>> If programmers aren't willing to write genuinely literate programs,
>> what difference does it make whether or not they have genuine literate
>> programming tools?
--Cameron Smith
cam...@dnaco.net