[Aldor-l] Literate programming

[Ralf Hemmecke]

Hi Thomas,

Welcome. Or have you been listening already for quite some time?

My first question. Why are *you* interested in Aldor?

>> First of all, who would be interested in having the aldor sources? I know
>> from myself that I tend not to even look at literate programming sources,
>> not even the tangled ones (as they contain no comments). The reason I
>> don't like looking at them is that vim doesn't do syntax highlighting
>> very well on noweb sources.

> And neither does noweb-mode or mmm-mode on emacs.

Oh. That is simply not true. I agree that mmm-mode sometimes get's 
confused with dollar signs, but as the mmm-mode maintainer told me that 
is a problem with (x)emacs. That editor is simply not made for switching 
major modes in the middle of a file.
I use mmm-mode together with my aldor-mode.
http://www.hemmecke.de/aldor/allprose/myalpssu11.html#x35-210009.3
I actually use xemacs. But Martin uses that with emacs and also seems to 
be quite satisfied.

> I just use a
> non-syntax-highlighting mode in my editor (not emacs or vi) for editing
> noweb code; the only real features that editor provides are text
> paragraph justification, indentation continuation, and macros.  For
> reading the source, I have the PDF output in a separate window.  Sure, I
> used to like/rely on syntax highlighting and autoindentation in my text
> editor to help catch typos and brace mismatches, but I have (re)learned
> to live without.

Well, why than switch to emacs? ;-)
No honestly, during my work on .as files I edit files in xemacs and have 
the corresponding .dvi form open in xdvi. Then I use xdvi with all the 
hyperlinks colors and search facilities to read the documentation/code. 
If I spot some place that I further want to work on, I simply click into 
the dvi viewer and voila, emacs suddenly opens the corresponding file at 
the correct place.
That works because of "inverse search".
http://www.hemmecke.de/aldor/allprose/myalpssu21.html#x62-5800024.3.9

>> The second issue or even problem I have with it (and that is what keeps
>> me from looking at nw sources) is that it is possible to scatter the
>> source over many places and let the tangler merge it later, as in:
>> <<chunk1>>
>> for (int i = 0; i < 100; i++)
>>   {
>>     <<Do something interesting here>>
>>   }
>> @
>> This requires me to look for the string "Do something interesting here"
>> in the nw document. That takes me time and I quickly get annoyed when
>> things take time.

> The noweb-mode on emacs does support a menu and side-tree and 
> hypertext-like commands (I think), but here I use PDF as well.

Like me with the DVI file. But Pippijn is right. The editor should 
simply be intelligent enough to unfold the code inside the editor and 
even letting me edit the (remote) chunk here. If only there were a smart 
elisp programmer who could do that... sigh.

> I have invested a lot into making my noweb output work the way I like.

I've glanced over your package (http://storage.iu.edu/qmgr/build.pdf). 
You seem to be quite knowledgeable in perl, shell, makefile, latex, etc.

I have the impression that I could learn quite a bit from your work. 
Whenever I will revise ALLPROSE to move it to use autoconf/automake, I 
must certainly contact you for a lot of stuff that I could improve.
In particular, since there is not yet support for hyperlinks between 
typenames in the documentation of Aldor code chunks, I would quite be 
interested in your experience with the listings package. I thought about 
introducing it for Aldor until I could use help of the compiler to spit 
out hyperlinks to the right function/type.

> I'm aware of
> allprose, but I have not done anything with it, mainly because I use C
> and Ada for nearly all of my code right now.

Right. ALLPROSE is focused on supporting the build of aldor libraries. 
Pretty useless for anything else.

> That and POD is not really literate programming.

How true.

> It does fulfill a
> different need, though: the need to document the API, and provide user
> documentation.

Yes. Both is useful an necessary. But there also must be documenation 
for the maintainer of the code. And there the API is clearly not enough.

> I have yet to find the holy grail that allows me to
> easily integrate source code documentation, API-level user
> documentation, and end user documentation in a single document/source
> file that also meets my need to have related things be as close to each
> other as possible for maintenance and document flow.

Well, do you know of a mailing list where this could be discussed? My 
experience with ALLPROSE tells me that exactly that holy grail is 
missing. It is not so easy to satisfy all needs. I guess one must forget 
about editing the actual plain text. Rather an editor is needed that can 
switch to different views. The editor should arrange of small snippets 
of code and documentation according to the view/goal one is writing for.
I thought LEO http://webpages.charter.net/edreamleo/front.html was such 
a tool, but it did not really convince me for what I have in mind. For 
me LEO feels to code or structure concentrated. It does not feel as if 
the documentation was written for humans.

>> To the noweb experts here: can <<chunk>>s be called as
>> macros? Can they be parametrised?

Sometimes I wish it could in particular if a chunk references variables 
it does not define locally for itself.
But I guess making chunks understand parameters requires additional 
noweb functionality. And maybe it's not worth the effort.

 >> If that is the case, it would be an
>> excellent alternative to the C preprocessor, because the latter kills any
>> useful line information.

I don't think I understand what the C preprocessor kills.

> One of my wild dreams is to make an aldor-like compiler, written in
> literate aldor (a change from my old dream, which was to the same in
> Ada, but aldor does most of what I like about Ada, and is less wordy).

Oh that sounds interesting. An aldor compiler in literate aldor... that 
is certainly a hard task for just one man. Why don't you start an open 
project? Dictate your literate view and see what happens...

> Missing bits are a nice formatter for aldor code I can incorporate into
> my noweb build system, a more formal/complete language specification,

Well, that's true. The AUG is not really very formal. But then you could 
write your own specification.

> and copious amounts of free time.

Only children have that, but they are not allowed to work. ;-)

Best regards
Ralf