Re: About file formats (was Re: [Axiom-developer] First (quick & dirty) port of Axiom to gcl-2.5.2 and powerpc architecture)

[root]

> Why not use noweb facility to standardize some predefined noweb chunks,
> like:
> 
> <<user documentation>>=
> 
> <<Makefile>>=
> 
> <<programmer documentation>>=
> 

There are several "uses" for noweb files that are in the goals list
on savannah. They all stem from the idea that we need to create good
documentation if Axiom is going to survive the next 30 years. More
to the point, we need to change Axiom so it is driven from the noweb
files (documentation is a word that fails to cover the ideas and is
so emotionally overloaded as to be an impediment to clear thinking)

Let me talk about the ideas "from the top down" (sorry, old coding
ideas never die :-) )

Use 1: An Axiom Journal

Ideally people would publish research papers with new mathematics in
them using an extended, stylized noweb format that is standardized
for the Axiom Journal (similar to other Journal "standard latex" ideas).

The research paper would contain the research work, the code, the
documentation, and test cases (and possibly more). A referree could
get the paper, fire up Axiom, "drag and drop the paper onto Axiom"
and have a running system extended with the new mathematics so they
can test the new research ideas.

So assuming that "drag and drop" (D&D) works what machinery must 
exist so that the new research paper is seamlessly available. Clearly
the math must exist. But it will reference other math research papers
(that contain math) in the bibliography. These need to be fetched and
automatically added (D&D'ed). Axiom sort-of does this already as you
can see from the various loading messages. However it does not do it
thru the bibliography.

Ok, so the algebra gets loaded from the paper. That clearly can happen
because we can write the paper to "chunk" the code. I've already done
this with one domain (see src/algebra/dhmatrix.spad.pamphlet which is
the first part of Richard Paul's Ph.D thesis (with permission)). And
the paper gets formatted properly for review into a .dvi file. Clearly
this mechanism can be recursively expanded thru the bibligraphy.

But the rest of the system parts need to know about the new research
so there needs to be some user documentation, unit test cases, sample
input files, etc.

I know the complaint will be leveled that this stuff should not be
in a research paper but I disagree. If the system supported "extracting"
the parts automatically (D&D again) and composing them into a research
paper it would be painless on both ends. (I've already begun experimenting
with this. I have Barry Trager's Ph.D thesis (with permission) which is
the basis for the integration routines in the system. I'm experimenting
with the methods mentioned using this as a test case.

So the Axiom Journal mechanism will end up connecting the algebra you
run with the research behind it and the rest of the research literature.

Use 2: Books based on Axiom's algebra

Suppose you wanted to write a book on linear algebra. You'd like to
be able to use Axiom's pamphlet files to include examples about the
subject from the highest concepts to the lowest details. Ideally you'd
be able to take a "vertical slice" thru Axiom pamphlets so that you
can pick out the chunks that you find most useful and include them.

The vertical slice requires a way of cross-referencing the system
beyond the traditional bibligraphy mentioned above. In particular,
it is very similar to the notion of hyperlinks. But it is a funny
sort of hyperlink because you want to extract "tex sections" (or
even subsections) and "noweb chunks" as well as any cited references.

Use 3: Booklets within Axiom, horizontal and vertical

A subset of the above Books use is the notion that you'd like to be
able to document a "horizontal slice" of Axiom which would be all of
the matrix facilities, for instance. This booklet form would allow
users to understand various kinds of matricies Axiom knows.

Another slice direction, the "vertical slice", would explain Axiom's
integration mathematics from the highest to the lowest levels.

So you can form a "slice matrix" and categorize the position of a
pamphlet by the position that its chunks occupy in the slice matrix.

Use 4: Pamphlets within Axiom

Of course, as you mentioned above, pamphlet files need some basic
required structure so they can be decomposed into a running system.
In order to seamlessly drag and drop a pamphlet it needs to have
parts that update the documentation, the algebra, the cross-references,
etc.

In 30 years we will have won the game if researchers assume these
facilities are used by research papers as a matter of course rather
than as magic. After all, symbolic mathematics is only a method of
doing more mathematics rather than an end in itself and Axiom needs
to support that to survive.

> 
> 
> > Several issues arise including things like the fact that dvi files
> > don't support hyperlinks so some sort of a viewer needs to exist.
> 
> DVI files does support hyperlinks. Just include the 'hyperref' (or
> 'hyperef'?) package at the beginning of the latex file.

Cool. I didn't know that. I'll check it out. Thanks.

noweb needs to be extended with a hyperref syntax in the chunk names.
At the moment the name is uninterpreted but there is no reason why
it couldn't have <<ftp://ftp.tenkan.org/....>> or 
<<pamphlet://src/algebra/foo.pamphlet#chunkname>> or
some further syntax and protocols.

> 
> > Ideally this would be some standard viewer as we'd have less code
> > to maintain. 
> 
> Why not use the PDF file format. Substitute pdflatex instead of latex
> and bingo, you have a pdf output (of course, you must have installed
> necessary packages from your linux distro).

I tried PDF files initially and got feedback that the display resolution
of the files was lousy. It was likely a problem with the dvips program
as other PDF files work fine. This is certainly a viable path for 
viewing one file. But how do we solve the organizational problem if
there are several thousand pamphlet files?

> 
> And, as a bonus, using noweb and hyperref, you have cross references
> between code chunks. I tested it on C code with noweb facilites to index
> C code. Of course, we should do that for Axiom programming language.
> 
> > Ultimately we need to think out how the pamphlet, booklet, and 
> > other documentation/usage/FAQ/maint information is going to be
> > structured and viewed.
> 
> Yes. For example, should we produce one big book (like Knuth TeX Book)
> or several small books?
> 
> But probably usage will tell us some insights. Why not choose an easy
> approach and correct it if it is the wrong path?

Tim
address@hidden
address@hidden