Re: [Axiom-developer] Re: A modest proposal

[Ralf Hemmecke]

Hello,

sorry if I prolong this thread although much has already been said.

Literate programming can currently be seen as religion. Even though TeX 
survived until today, there must be some reason why a lot of people 
don't follow it.

I must say, I am happy that Tim set LP as a main goal for Axiom. I think 
it is an important one.

But not only from Tim's and William's mails I learned that it should not 
be the only goal. Following LP too strictly, does not work. At least not 
at the moment. Currently, more important than LP is the need to attract 
more developers. Currently, the rules that everything must per properly 
documented should be a bit relaxed. Axiom currently is not documented 
properly and it will not be for another 10 years. We have a lot of 
legacy code.

But without new and ambitious developers, Axiom will become even more 
uninteresting. Axiom must spread to the world and attract users and 
developers. If you set the entry barrrier too high. Axiom is going to 
become a Tim-only project.

Tim, that does *not* mean that I am against LP. Quite the contrary. LP 
should be preached again and again. And it should definitely be the 
essential goal of the Axiom project.

What I want to say is: Tim is right and William is right. (sic!)

But LP is not everything. Think about why there are two books "TeX the 
Program" and "The TeXbook". The first one describes the program and the 
second one is for users to teach them how to use the program.

I don't quite know whether Tim wants to have both kinds of documentation 
in the Axiom project. If I understood correctly, that is the "facets of 
the crystal" view. Yes, Axiom should be a big monster which not only 
contains code.

It should be a collection of
1 code,
2 API descriptions (this is what the +++ comments are)
3 explanation of
    motivations,
    tricks that were used in the implementation,
    things that are not used in the code (and the reason for it)
4 informal description of why the code is there
5 informal overall description of how some piece of code works
6 formal descriptions of the theory behind the code
7 proofs that the code fulfils its specification (its API)
8 test scripts that tests the code (we don't have automated
  program verification yet)
(This list is certainly not complete.)

William (I have not actually looked at your code so excuse me if I am 
wrong), what you contributed was/is in the code and API part and maybe 
in the test and formal description part (1,2,6,8). But what I think is 
very important is also the interconnection between all of this. Can you 
point me to some text in current Axiom that explains *why* (4) you have 
designed your contribution as it is now?

I agree that some people are not interested in the code and in the 
description of the code, but for developers who maintain code it is very 
important to know about design issues. That is a different issue from 
the actual mathematical theory and it is important for maintainers of 
the code.

Axiom should have everything and it should be able to show to some 
person exactly the amount of detail s/he wants to see. If someone is 
only interested in the theory, extract something that doesn't show the 
implementation details. But some people would not only like to see the 
theory, but they want to see a "running theory", they want an 
interactive paper where they see the theory and can compute with the 
algorithms implemented by the paper. Other people like to see the actual 
algorithm in a specific programming language. Some people are not 
interested to be distracted by a lot of text and want to concentrate on 
more focused details of the implementation. Axiom should be able to 
extract all these different forms in nicely human readable formats. All 
that should be provided by a (or several) pamphlet(s).

The important thing is that the information is there. I am not so sure 
that we already have a good format of how a pamphlet should look like.

I also agree that it is hard to actually write good LP documents. I made 
my experience with Aldor-Combinat. Look at it at 
http://www.risc.uni-linz.ac.at/people/hemmecke/AldorCombinat/ .
It has a lot of documentation. But I myself would not say that it is a 
proper literate program. Try it out, read it. I guess, you will not be 
able to understand the overall project goals. I have not written that 
but still the program is working. Now, if I would require proper LP 
documentation, I would never be able to release this code at all. I try 
hard to add a lot of design decisions, but all that is still not enough.

And that Aldor-Combinat experience lets me think that it is better to 
release code even if it is not properly documented. So in this sense I 
do not fully agree with Tim. I find it better if I throw something at 
the public and have referees that tell me, hey there is something wrong, 
this and that is not understandable. So I have a chance to extend 
code+documentation at places where people complain. I am committed to 
LP, but I also have only limited time so it's better if there is really 
a community develepment. I am all for feedback. That should be our 
"quality assurance" way of makeing Axiom incrementally better.

That is my little comment to the issue...
I'm sorry if I wasted your time.

Ralf