Simple LP experiment
Martin ELLISON
was a simple system based on
- embedded formatting commands in comments (HTML in my case)
- no special .web type files, input file is standard .cpp file that
can be compiled without any tangle process
- no facility to prettyprint or format code, code is just output as-is
with a basic format to retain indenting and line breaks
- code is not reordered, it stays in the same order
- transalation program to convert cpp file to htm file is written in
C++, so it is a simple .exe file (no need to use PERL etc)
My argument is that object-oriented languages don't need the rearranging facilities
of Knuth's Web, that these reaordering facilities are a result of Pascal's
over-rigid syntax. At any rate, the cognitive cost of the reordering facilities not
worth it (you can measure 'cognitive costs' in how long it takes to train someone).
You could add the prettyprinting, at least to using different typefaces for
different kinds of tokens. You could also run the .cpp file through a conventional
reformatter to sort out the indenting; this need not be part of a literate
programming system.
It seems to work, it only takes a few pages of (literate) code. For HTML output, you
have to translate something like 'x < y' to 'x < y' and of course you have to
detect comment start and end and process accordingly - these are the hardest bits.
A question then - if this is so easy, then, why isn't everyone doing this? Have
there been other systems that do the same thing? And why don't Borland or Microsoft
include something like this in their systems (with a WYSIWYG editor)?
Martin
---------------------------------------------------
Martin Ellison mailto:mar...@mpce.mq.edu.au
http://www-comp.mpce.mq.edu.au/~martin/
Patrick TJ McPhee
Martin ELLISON <mar...@mpce.mq.edu.au> wrote:
[describes the standard, no-special-file-format, comments-in-comments,
`litprog' approach]
% My argument is that object-oriented languages don't need the rearranging
% facilities of Knuth's Web
I've heard this many times, and I'm highly skeptical of it. There's nothing
in oop languages which make them more flexible in terms of code organisation
than non-oop languages, or more to the point that their code is naturally
organised in a way that makes it easier to understand.
% A question then - if this is so easy, then, why isn't everyone doing this?
What exactly does it buy you?
% Have there been other systems that do the same thing?
I called this a standard approach above, because it's occurred to anyone
who's seriously considered literate programming. If we were to construct
a test of what constitutes a literate programming system, though, I think
that it would fail. I'm not going to propose such a test here (I'm
thinking on the lines of the Cobb's [is this the right name?] rules for
relational db, or somebody else's rules for oop languages), but it seems
to me the goal of any litprog system has to be to aid exposition, and
that goal suffers if you don't have a re-arranging facility.
% And why don't Borland or Microsoft include something like this in their
% systems
They do (Microsoft does, anyway)
% (with a WYSIWYG editor)?
They don't do this. It's expensive to implement, and you don't get any glory
for it. On the other hand, their souped-up pretty printer writes out
rtf files, which you can then fool around with in the WYSIWYG system of
your choice.
--
Patrick TJ McPhee
Toronto Canada
pt...@io.org
Marc van Leeuwen
|> I recently put together a simple Literate Programming 'experiment'. What I wanted
|> was a simple system based on
|> - embedded formatting commands in comments (HTML in my case)
|> - no special .web type files, input file is standard .cpp file that
|> can be compiled without any tangle process
|> - no facility to prettyprint or format code, code is just output as-is
|> with a basic format to retain indenting and line breaks
|> - code is not reordered, it stays in the same order
|> - transalation program to convert cpp file to htm file is written in
|> C++, so it is a simple .exe file (no need to use PERL etc)
Just a few remarks. My main question with this approach is, how does it
differ from doing nothing at all, i.e., just writing useful comments in your
code? It seems that the only difference is that you use HTML to ``format''
your comments (all comments, even those short ones?). But this seems rather
silly to me, since HTML is not a formatting language, but a markup language,
and there does not seem to be much to mark up about comments within programs.
OK, you can put an occasional hyperlink in if you like; while this is fairly
laborious it might occasionally be useful (but you could still only hyperlink
to comments, not to actual code, and you could only browse your program
after conversion to HTML, so this is of little help while writing the
program). Apart from this you get the possibility to include headers,
enumerations, and GIF images, in my opinion not the most essential things
(the possibility to include formulas to discuss properties of the program
seems important, and would be a real pain in this approach). Or is it maybe
your wish to indulge in Netscapism?
|> My argument is that object-oriented languages don't need the rearranging facilities
|> of Knuth's Web, that these reaordering facilities are a result of Pascal's
|> over-rigid syntax. At any rate, the cognitive cost of the reordering facilities not
|> worth it (you can measure 'cognitive costs' in how long it takes to train someone).
I'd say the cognitive cost of going from C to CWEB is much less that going
from C to C++ (and I mean the time to train people to really use something
fully and confidently), but this is of course a matter of opinion. There
have been people teaching literate programming to students, and I have heard
of no particular problems there. Learning to make the best use of the
available possibilities might be more difficult, especially to people who
have been practicing for many years the best way to use illiterate
techniques, but I don't think that is fair to use as a comparison.
|> A question then - if this is so easy, then, why isn't everyone doing this?
I think it is a fundamental misunderstanding that ease of implementation is
a reason for ``everyone'' to use something. Quite to the contrary, there is
a distinct tendency of the majority of people to use increasingly complex
systems, that are almost impossible to understand, let alone to implement,
but which give them the impression that they do not have to think for
themselves. (Of course the infortunate day always arrives when the system is
not quite doing what they want, but nobody warned them, lest they might
think the system would be be difficult to use.)
Marc van Leeuwen
CWI, AMsterdam
David Kastrup
>My argument is that object-oriented languages don't need the rearranging facilities
>of Knuth's Web, that these reaordering facilities are a result of Pascal's
>over-rigid syntax. At any rate, the cognitive cost of the reordering facilities not
>worth it (you can measure 'cognitive costs' in how long it takes to train someone).
Wrong, in my opinion. This is the most important reason for LP, and
here is why: it helps you keep your control structures optically
short, and easily perusable.
You cannot do this with C++: you don't want to separate 10 nested
loops with different indices (and doing messy integrations of some
ugly generic form in symbolical form, you can easily reach that number
of variables and more) into functions: too slow, and far too
error-prone: you don't want to invent 10 different parameter lists,
and having all parameter lists the same is hellishly inefficient and
pointless. You want some ordering, but you sure as hell do not want to
introduce local scopes not importing any variables from outside.
In a lot of structured languages, you do not modularize as much as
possible because you are going out of useful function names, and your
thesaurus goes out of synonyms which don't mean anything different,
anyhow. Just using a description of what is actually done, like in LP,
takes less mental anguish.
--
David Kastrup, Goethestr. 20, D-52064 Aachen Tel: +49-241-72419
Email: d...@pool.informatik.rwth-aachen.de Fax: +49-241-79502
Matthias Neeracher
> I recently put together a simple Literate Programming 'experiment'.
I wouldn't really call it "Literate Programming" anymore, but as an experiment,
it is certainly valid.
> What I wanted
> was a simple system based on
> - embedded formatting commands in comments (HTML in my case)
> - no special .web type files, input file is standard .cpp file that
> can be compiled without any tangle process
> - no facility to prettyprint or format code, code is just output as-is
> with a basic format to retain indenting and line breaks
> - code is not reordered, it stays in the same order
> - transalation program to convert cpp file to htm file is written in
> C++, so it is a simple .exe file (no need to use PERL etc)
I think the cnoweb system used to be similar to this.
> My argument is that object-oriented languages don't need the rearranging
> facilities of Knuth's Web, that these reaordering facilities are a result of
> Pascal's over-rigid syntax.
I disagree. You'll find examples of "over-rigid syntax" in every language. In
the specific case of C++, reordering is a big win for private members. I like
to write classes as:
class XY {
public:
XY();
~XY();
void A();
int B();
private:
<<Privatissima of class |XY|>>
};
This gets rid of the truly annoying requirement of having to declare all
implementation details right next to the specification of a class.
> At any rate, the cognitive cost of the reordering facilities not worth it
> (you can measure 'cognitive costs' in how long it takes to train someone).
I find it hard to believe that training someone to use noweb would take more
than 5% of the cost of teaching them to use C++ and object oriented
programming.
> You could add the prettyprinting, at least to using different typefaces for
> different kinds of tokens. You could also run the .cpp file through a
> conventional reformatter to sort out the indenting; this need not be part of
> a literate programming system.
I hope I won't get flamed for saying this, but I have the impression that the
non-prettyprinting (uglyprinting ?-) LP tools (noweb and nuweb) have pretty
much "won". While, thanks the productivity of Knuth, prettyprinting tools will
probably continue to dominated printed books, the lcc book by Fraser and Hanson
demonstrates that noweb is suitable to producing published literate programs of
a quality satisfying to all but the most demanding bibliophiles.
The one area where language dependent LP tools are ahead is identifier
indexing, but I suspect that for C++, this is an almost impossible task anyway.
> A question then - if this is so easy, then, why isn't everyone doing this?
> Have there been other systems that do the same thing? And why don't Borland
> or Microsoft include something like this in their systems (with a WYSIWYG
> editor)?
Good question. I suspect it's because the majority of programmers likes plain
text, or think they like it. What I hope is that someone produces an OpenDoc
based programmer's editor; this would make the WYSIWYG part much easier and
more powerful.
Matthias
-----
Matthias Neeracher <ne...@iis.ee.ethz.ch> http://err.ethz.ch/members/neeri.html
"And that's why I am going to turn this world upside down, and make
of it a fire so *bright* that someone real will notice"
-- Vernor Vinge, _Tatja Grimm's World_
Norman Ramsey
Matthias Neeracher <ne...@iis.ee.ethz.ch> wrote:
> I find it hard to believe that training someone to use noweb would take more
> than 5% of the cost of teaching them to use C++ and object oriented
> programming.
So, should I be gratified by this comment, or should I be insulted
because the figure is as high as 5%? (I do know some C++.)
Actually, learning to use the tools is the easy part. The hard part
is learning to write intelligently about programs, and I find this
idea every bit as difficult to teach as object-oriented programming
(which is much easier to teach than C++).
--
Norman Ramsey
http://www.cs.purdue.edu/homes/nr
Sven Utcke
> I recently put together a simple Literate Programming
> 'experiment'. What I wanted was a simple system based on
> - embedded formatting commands in comments (HTML in my case)
> - no special .web type files, input file is standard .cpp file that
> can be compiled without any tangle process
> - no facility to prettyprint or format code, code is just output
> as-is with a basic format to retain indenting and line breaks
> - code is not reordered, it stays in the same order
> - transalation program to convert cpp file to htm file is written in
> C++, so it is a simple .exe file (no need to use PERL etc)
> My argument is that object-oriented languages don't need the
> rearranging facilities of Knuth's Web, that these reaordering
> facilities are a result of Pascal's over-rigid syntax.
Not in my experience. Your probably right as far as simple
applications go, say an editor or somesuch (although I'm writing this
in emacs, which would hardly qualify as simple). What I mean is,
anything that requires only a few lines of code, or can easily be
broken up into functions, your fine. But especially in science,
people will normally encounter quite complex programs, which can't
easily be split up into simple functions and, at any rate, splitting
them into simple functions would just create artifical boundaries. I
found that using scraps (chunks, whatever) instead is definitely the
best way for me (although some people prefer folding-editors for
basically the same task).
> At any rate, the cognitive cost of the reordering facilities not
> worth it (you can measure 'cognitive costs' in how long it takes to
> train someone).
How long does it take to train someone to read a WEB? I would have
thought about 15 minutes.
It also seems that this approach is lacking the things I cherish most
about LitProg (apart from reordering): No index, and none of what I
might call "folding capability". And, of course, it is not really
literate at all, in that I couldn't really write a book using this
approach (or, at least, would be severely restricted without
reordering capabilities).
Greetings
Sven
PS: I rearranged linebreaks to make this more readable.
Kenneth Brittain
>
> In article <315DE0...@mpce.mq.edu.au>, Martin ELLISON <mar...@mpce.mq.edu.au> writes:
> While, thanks the productivity of Knuth, prettyprinting tools will
> probably continue to dominated printed books, the lcc book by Fraser and Hanson
> demonstrates that noweb is suitable to producing published literate programs of
> a quality satisfying to all but the most demanding bibliophiles.
Is the "lcc" book a recent publication? Does anyone have a reference to it?
> The one area where language dependent LP tools are ahead is identifier
> indexing, but I suspect that for C++, this is an almost impossible task anyway.
I use C++ and noweb (finally). I find the "@ %def" indexing method rather
helpful in that it produces "exactly" what I tell it.
> [cut]
> Good question. I suspect it's because the majority of programmers likes plain
> text, or think they like it.
You have to admit that "plain text" is pretty portable and I *think* I like it.
> What I hope is that someone produces an OpenDoc
> based programmer's editor; this would make the WYSIWYG part much easier and
> more powerful.
I have played with this idea but always fall back on my text editor. Why? It is
a small environment (compared to OpenDoc) and does exactly what I want.
Kenneth Brittain
Norman Ramsey
Kenneth Brittain <brit...@lims.com> wrote:
>Is the "lcc" book a recent publication? Does anyone have a reference to it?
@book{fraser:retargetable:book,
author="Christopher W. Fraser and David R. Hanson",
title="A Retargetable {C} Compiler: Design and Implementation",
publisher="Benjamin/Cummings", address="Redwood City, CA",
year=1995,
isbn="0-8053-1670-1",
}
Good book.