[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Ralf Hemmecke
Subject: [Axiom-developer] Pamphlet style (was: Literated VMLISP.LISP.PAMPHLET)
Date: Sat, 23 Sep 2006 15:03:44 +0200
User-agent: Thunderbird (X11/20060909)


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

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...

It is already something, especially 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 And add your experience and vision of how pamphlets should look like. Hopefully, we will soon have some good guideline for new contributors.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]