Archive-Date: Tue, 22 Dec 1992 14:56:59 CST
Date: Tue, 22 Dec 92 14:56:45 -0600
From: plyon@emx.cc.utexas.edu (Paul Lyon)
Message-ID: <9212222056.AA00970@emx.cc.utexas.edu>
To: LitProg@SHSU.edu
Subject: OO Literate Programming?
----------------------------------------------------------------
On the face of it, it would seem that the concept of literate
programming is not easily adapted to the "Object Oriented" approach to
programming.  Let us recur to Knuth's original article on the subject
(I refer to the version reprinted in {\it Literate Programming}, CLSI,
Stanford, 1992, pages 99--136). There we find literate programming
characterized in a way that seems to fit best with the approach Knuth
took in writing TeX and Metafont. The woven web file, when printed, is
to read rather like a technical article (shorter programme) or a
technical book (for example, {\it Metafont: the Program}).

All of the source goes into one file, from which Weave will generate a
(and other things designated by the author using the Web control
code), and an alphabetized listing of the code section names. The
author is meant to follow a narrative order in presenting the parts of
the programme; as Knuth says but always it is an order that makes
sense on expository grounds'' (op cit, page 125). And further,
"...there's no need to be hung up on the question of top-down versus
bottom-up---since a programmer can now view a large program as a web,
to be explored in a psychologically correct order..." (op cit, page
126). [I expect that, in most cases, there will be a number of ways of
ordering that will work.]

Finally, besides the obvious benefits to the reader---either another
or oneself at some remove---of a more pleasing presentation of the
source and of greater clarity, another benefit claimed, one now to the
author, is a shorter time required to make the code work properly. The
reason for this, according to Knuth, is that in preparing a proper
account of the programme while writing it, one is led to clarify one's
thoughts about it; as he puts it, you go into "expository mode".  In
trying to write enough to explain it to someone else, you are forced
to explain it to yourself! [Aside: this last, in particular, is one of
the things that I most liked about Knuth's idea when I first
encountered it. The more carefully I write, the better I understand
what I am writing about.]

Now I have said this much about the original idea for two reasons: (1)
it is an attractive idea about how to write programmes, and (2), more
importantly, most of the existing Web systems are designed with this
idea in mind. In particular, those features of WEB itself, and its
progeny, Cweb, Fweb, Spiderweb, and so on, that go beyond the bare
bones required for tangling and weaving, are mostly about forming the
index, allowing the programmer to insert things besides identifiers in
the index, forming the section headings, and the like, whence my
remarks above about these matters.

On the other hand, for "Object Oriented" programming, one is meant to
split up a programme into a number of modules, most of which contain
the interface and implementation for a single data type, or group of
closely related data types, and only a few of which will contain the
code that ties all of these together. Furthermore, the modules that
contain the programme data types are meant to be relatively
independent of the particularities of the programme one is working on.
In pursuit of code reuse, one is meant to make something more akin to
library code out of these, free-standing and comprehensible by itself
rather than tightly integrated into one programme.

It is this last that prevents one from simply adapting Cweb or Fweb in
their current versions by using the file inclusion capability. This
might work for the traditional way of laying out the modules that is
used, for example, in C programming, but the approach taken in C++
programming is another matter. It is instructive, I think, to consider
the contrast as given by Bjarne Stroustrup in Chapter 4 ("Functions
and Files") of {\it The C++ Programming Language} (Second Edition, but
the same is to be found in the first edition). The example Stroustrup
gives is a simple calculator programme, rather like the one the
Cameron Smith dug out of Kernighan & Ritchie and used for his Cweb
example (described in previous postings to this group, and available
from niord.shsu.edu). Stroustrup considers how this example, might be
put in modular form in the traditional C style, and then goes to do
describe a different layout of the kind one would use in C++ or Ada
(and Modula 2, as well, I suspect). One gets five pieces: one contains
the main programme, and the other four, each with its own header file
and source file, contain (1) the error handler, (2) the symbol table
code, (3) the eval code for the calculator, and (4) the lexical
scanning code. All this, mind you, without yet introducing classes and
inheritance; it is, rather, the prelude to that. Still, the header
(interface) file contains the declarations of the data structure(s),
if any, together with the prototypes of the functions that provide the
services that are collected in this module, and the source file
contains the implementation of those functions. Add in the real
apparatus of C++ and one gets a header file with the class
declaration(s) and a source file with the implementation of the class
"methods". The syntax and accoutrement will be different for Eiffel,
or Clos, or Ada, but the style remains the same.

The obvious way to proceed is to construct a web source file from
which you will generate the header file and implementation source, one
that usually starts out with a description of the data type, with,
perhaps, a table or itemized list giving brief descriptions of the
methods (functions, procedures) for the data type, and perhaps, also
one describing the fields of the data structure, and then goes on to
string together the implementation of the functions, adding to each
some account of its implementation where that is pertinent.  In short,
something that looks rather less like an exercise in literate
programming as conceived by Knuth, and rather more like a UN*X man
page with added source code.

Now there may be no cure for this, or it may be that I am not
imaginative in the right sort of way :-) In any case there is little
in the way of support in the existing Web systems for this sort of
thing So far as Weave goes, I have nothing concrete to suggest at
this point, rather, I hope to stimulate discussion, assuming, as I do,
that the efforts to add C++ support to Cweb mean that there are others
out there with similar concerns. (I have the same thing, though, on my
"Web wish list" as I suspect others do as well, namely support for
user configurable pretty-printing styles; my tastes in these matters
being significantly different from those of the authors of Cweb).

Some things that come to mind for a C++ tangle, however, might include
the following. First of all, most of us still have to contend with
dumb'' linkers that insist on linking in the whole of a object
module, even if one only uses a couple of things out of it. So it is
desirable that one have a separate output file for each function or
procedure defined in one of this library like modules, and further
desirable that on each run of tangle, in the development phase I mean,
one should generate only those output files that have changed since
the last time one ran tangle. Otherwise, assuming that you already
have a makefile for it least this much, you will end up recompiling
the lot instead of just the one or two bits that you changed.
[Funnelweb has a simple version of this; one of the reasons why I like
it.] Indeed, it would be nice if tangle could generate the appropriate
parts of the makefile for you (more to the point, the GNU makefile,
since this will be the more easily done, I think, using GNU make).

It would also be helpful if a C++ tangle would, given the definition
of a function, generate a function prototype for you if you have not
already provided one. This feature'' will not be simple one, since
tangle will have to know where to put the prototype, and that will
depend on whether the function is a class method, or a friend
function, or one that just happens to live in the source file in
question because it is more or less related to the class(es) being
defined. On the otherhand, it could be a useful one; both in saving
effort, and helping to cut down on programme errors.

There are other things for the wish list as well, but I have likely
said more than enough already :-)