Re: [Axiom-developer] ADVI browser

[root]

Bertfried,

I like your idea of "synopsys" and "algorithm" tags.  Clearly the
pamphlet files need structure.  However I'm not sure that the chunk
tags are the right place for the structure. The chunk tags are 
intended to quote and embed code in a tex document. The booklet
extension allows the code to be in files which are "included" but
still has the idea that they embed code. We're beginning to evolve
the noweb idea. David Mentre took the first step with the booklet
code.

> Regarding my current view on mathematics, ist far from beeing a static
> sort of things. Many people do belife that methamatics is given as-is and
> has only to be 'described' or 'explained'. However, I personally expect a
> great reworking of many areas of mathematics in a more 'categorial' way.
> Any documentation of a project like AXIOM should be capabal of such
> reorganization, and you do indeed think about this.

Actually, Axiom's math evolves. Bill Sit has given me a newer version
of the PLEQN domain that includes later work. Several other people
have indicated that they also have later, improved work. I'm
struggling with the idea that Axiom should have an embedded CVS so you
can add new work while still referencing the old. And CVS solves the
problem of authors taking different directions with the same
mathematics. But I'd have to change the build structure to take this
into account so this idea is a long way off yet.

What you appear to suggest is that portions of the document might contain
tags, lists, or markers (TLM) that indicate the intended use of the
material.  The machinery for this would be easy to add. We simply need
to have a parameter on various tex tags (e.g. \section[synopsys]{The
Section}) What isn't clear, as you point out, is the meaning
associated with the TLMs. Perhaps a standard portion of the pamphlet
could exist (similar to an index) to carry this information. I have
a "concept index" for commutative algebra which I plan to use to
structure the booklet files once they come into existence.

My thoughts on the subject, clearly open to debate, are that the 
pamphlet files contain information that the author can structure
to explain a particular point. Think of these files as "technical
papers" which potentially contain code. A technical paper has a
certain assumed, but not required, structure by convention. It has
an abstract, background, new results, summary, and bibliography.
I think the pamphlet files will evolve structure by convention also.

This raw information can be used and viewed in many different ways.
My thought was that "booklet" files would be the organizers of information.
So to address your example of sophistication level I'd expect an author
to write a booklet file that includes portions of pamphlet files. Simple
booklets such as an intro to linear algebra would only include text from
the examples portions of pamphlets. Complex booklets about lie algebras
might include portions of the theory sections containing theorems. So
booklets are intended to organize the pamphlet information for a particular
purpose. Pamphlet files are for organizing raw information about the code
and its supporting mathematics. I'm not sure if this is (a) a clear division
of responsibility or (b) a workable solution to your issue. It needs more
discussion.

> My own experience shows, that documentation of code takes away 2/3 of the
> total amount of work needed and only 1/3 goes into codeing and testing.
> Waht is clear to oneself has to be described very precicely in a
> documentation and there has to be a mechanism guaranteeing that code and
> documentation are recent and mutually related. Perhaps this is already
> guaranteed by using literate programming. However, there is a notorious
> tendency to make small hacks and 'forget' about documenting them, since
> one thinks about doing this in the next major realeas.... which never
> happens.

Knuth and Dijkstra both made this observation and both decided that
literate programming was the technique most likely to attack the issue
of documenting the code. It is ultimately up to the programmer to document.
I'm hoping, by force of convention, to convince Axiom programmers that it
is worthwhile spending 2/3 of their time documenting. The saving grace
is that, at least in mathematics, you get professional recognition for
writing up your results so you can, at minimum, attach the technical
paper to the code and call it a "pamphlet". That allows later authors to
better structure the mixture. If we succeed in keeping the theory with
the code it will be a major improvement over the current situation. Of
course, I'm not satisfied with just mixing the two. I want to exploit
the collection and make it useful for broader purposes.

When the alpha version gets uploaded look at
src/algebra/dhmatrix.spad.pamphlet. I've combined the theory with the
code. Denavit-Hartenburg Matricies (DH Matricies) are 4x4 matricies
with special structure that enable them to describe rotations,
translations, scale, perspective, and skew operations. This domain was
used to create the graphics in the glossy pages of the Axiom book.  I
wrote the original spad code essentially without comments. The theory
comes from Richard Paul's Ph.D.  thesis (which he gave me permission
to use). I'm now trying to atone for my sins and document the domain
properly. Since this code will support graphics I'm hoping to use it
as an example domain to exploit ADVI's ability to embed active graphics.

ADVI seems like worthwhile technology as they have found a mechanism
that allows authors of tex documents to embed information into the
dvi file that ADVI can use. This allows Axiom to perform all kinds of
interesting magic which opens up new ways to construct "books", booklets,
pamphlets, slides, technical papers, etc. And it uses "standard technology"
(since Knuth anticipated this in the dvi file format).

The alpha release of Axiom will use an axiom.sty file that will eventually
allow us to embed ADVI information. ADVI has shown what's possible but we
need to do much more.

Tim