[Axiom-developer] Pamphlet style (was: Literated VMLISP.LISP.PAMPHLET)

[Ralf Hemmecke]

Hello!

It seems that slowly people are starting to bring legacy code into a 
literate programming style. That is good and very important.

On 09/23/2006 12:23 PM, Frithjof Schulze wrote:

> I tried the same with eigen.spad.pamphlet. As a beginning I structured
> the file, commented the functions I understand (although sometimes what
> I wrote seems rather obvious) and began to write a little about the
> theory. 

Don't worry. Whatever you do is probably better than leaving the file as 
it is. The whole thing will be an iterative process. And why is that? 
Because nobody at this mailing list has come forward to define a 
definite style for pamphlets. I am probably right that there is no such 
thing for Axiom pamphlets as a style guide.

Now, knowing that there is no help for you, the best thing you can do is 
to invent your own style and make it public.

The only stuff that I could see on the wiki is linked here...

http://wiki.axiom-developer.org/PamphletFiles

It is already something, especially 
http://wiki.axiom-developer.org/PamphletExample
but currently it completely neglects the fact that there is relation 
between the different pamphlet files and that nowadays we should not 
just reference them via the bibliography, but via hyperlinks.

> I put the file in the wiki-source,

would it have been too hard to provide the URL directly? If you want to 
have help, make it nearly zero-effort for potential contributors.

> so hopefully somebody comes up with
> some kind of criticism. This is just a first try and I welcome
> tips/ideas what to change.

> Hopefully I didn't made any content related errors?

Hmmm... the first thing YOU have to make sure is that your local copy of 
the Axiom sources still compiles without error (including the testcases).

Whether you wrote good or bad content into the latex part of the 
pamphlet is another question that needs review by other developers.
But the semantics should not change (at least not now or not too 
drastically). In fact, I believe it must be made easier to add 
testcases. Does somebody have a quick guide or reference of how to add 
new testcases to Axiom?


> Tree additional questions concerning the literate source I have by now:
>
>     How much theory belongs in a pamphlet? For example after a nice
>     description what the gröberner basis algorithm does, is it important
>     why it terminates? Or is a reference here enough? 

Good question. My current experience says: it depends.

If we now document every simple detail we will never reach a status 
where Axiom becomes the leading research platform.

But think of Axiom as being (one of) THE leading research platform(s) 
then the only place where the theory is (should be) is in the pamphlet 
since there is no other reference in the world. You are inventing the 
theory and deliver the code together with the theory. So that says: all 
of the theory should be in the pamplet.

However, there is hundreds and hundreds of books about mathematics and 
algorithms around that I believe should (currently) not being rewritten 
in the form of pamphlets. I think, it is enough for certain well-known 
algorithms to include one (or better several) easily accessible 
references (including references to other existing implementations).

That is for now. In the long run I would even like to see standard 
algorithms documented in a self-contained way in a pamphlet. It 
basically means that Axiom should become not only a leading CAS, but a 
source for learning about algorithms and the underlying theory.

To make that possible, sooner or later we have to start that 
Axiom-Journal thing.

If you now think in terms of a journal, then a pamphlet is like an 
article. Although one can consider a pamphlet as a container for several 
code files, I am not so convinced that it is the right way to do it. For 
me it is perfectly OK, if you deliver a .tar.gz archive with several 
pamphlets to the journal for review. As in a true journal that archive 
should describe one (new) idea.

All I want to say is that not the file is the basic unit but the 
idea/topic that is described. So for example, the whole build process of 
Axiom should be described in one document (in dvi/ps/pdf/html/... 
format), but not necessarily in just one .pamphlet. I don't care much 
how the sources are mapped onto the hard disk. What matters is that I 
get something readable, I understand the process/idea/topic and I am 
able to click and my editor opens exactly at right position in the right 
file if I want to correct something.

That is basically what I provide with ALLPROSE. It is a framework to 
produce a whole Aldor library. An I consider such a library as ONE unit 
no matter on how many files it is distributed internally. It describes 
or rather should describe one idea/topic.

>     If every file should be as elaborate as dhmatrix.spad, shouldn't one
>     have a central point where the notation and foundations stuff gets
>     clarified? Else, one would have to introduce the notation of
>     vectors, matrics etc. again in every file that uses them. Maybe one
>     should have a latex-style-convention in the wiki.

We had that before with the latex-style convention. It is not possible. 
There are too many latex packages around and they are not all 
compatible. We simply cannot fix the number of packages that we allow 
since that is too much of a restriction to potential contributors. We 
could have a journal style of how things should normally come out, but 
it's impossible to think of every detail in advance.

>     How formal should a pamphlet be? Rather a heuristically description
>     what happens (with reference) or better Definiton, Theorem ... ? 

First approximation, guess and document what you've found out about the 
legacy code. Next approximation, make that all more formal, add 
definitions, theorems, PROOFS. A pamphlet should be a scientific 
document, not just a code description. So finally, a pamphlet *is* as 
formal as a journal article. (And is hopefully even formally reviewed. 
And maybe later automatically verified by a proof checker -- that would 
be cool!)

I hope that was not too long...

So first add your question to the FAQ page then open up 
http://wiki.axiom-developer.org/PamphletStyle. And add your experience 
and vision of how pamphlets should look like. Hopefully, we will soon 
have some good guideline for new contributors.

Ralf