RE: [Axiom-developer] debugging information

[Page, Bill]

Tim, 

On Wednesday, October 19, 2005 8:24 PM you wrote:
> ... 
> There is much work to be done and I have no time estimate. 
> Documentation is vital and good documentation takes much
> longer than anyone expects.

Understood. "takes longer that anyone wants to admit", too
I think.

> I'm looking into parts of the system and have decided to
> write some debugging techniques and documentation on
> writing pamphlet files so most of my effort is going
> into volume 4.

Sounds good to me.

> 
> We can try putting the volumes online. Provided they still
> retain their pamphlet format (ie latex) I think it's a
> reasonable idea.

Yes, the pamphlet files on MathAction now have **exactly**
the same format as in the source code distribution (latex,
noweb markup and code).

You can access the volumes on-line here:

http://wiki.axiom-developer.org/book--main--1

Clicking on a volume displays it's first page (in png graphics
format). You can click on either the

 'pdf' or 'dvi' links to view or download the full document

 'src' for the full pamphlet source

 'tex' for the output of noweave

 'log' for the contents of the LaTeX log file

and on pamphlet files that contain code chunks you can also
select a chunk name and click

 'tangle' to extract the code

For example of pamphlets with source code see:

http://wiki.axiom-developer.org/axiom--test--1/src/algebra

Please let me know what you think of this approach.

> I'm a little concerned about changes that would use things
> like structured text, html, or other non-latex information
> in the files. Those are fine for the wiki but not for the
> system files, of which the book volumes are the cornerstone
> in my mind. 

I agree.

> 
>   Vol 5: Categories, Domains, and Package Internals
>   Vol 6: The compiler
>   Vol 7: The interpreter
>   Vol 8: The algebra
> ... 
> The system would be built from the books.
>

Great.
 
> Eventually modifying Axiom becomes a job of authoring or
> editing a section of one of the volumes.
> 
> I have a bit of machinery already (due to David Mentre)
> that extends the pamphlet idea to "booklets". etc.
> We can create our own protocols as needed.
>

I don't see any problem implementing that but I think we should
look carefully at what doing this implies for the eventual
structure of the Axiom code and documentation. More and more
these days I think we need to shift to a more dynamic and
richer model for source code then just the relatively static
literate program document. I think one way to work towards this
is through web-based services like we are building on the Axiom
wiki. So instead of a "dead" book, a complex program becomes a
dynamically changing web site, freely mixing source code and
documentation; and allowing fast and efficient navigation,
multiple "crystal" views of the same pages in different contexts
etc.

> > 
> > I wonder if there is anyone out there who would like to take
> > on the task to prepare such a CD? I could help but I don't
> > want to lead the effort.
> 
> I can look into the installable CDRom issue.
> I've already built iso images for ISSAC.
> 

Well, as usual you are pretty busy and your time might best be
spent other ways but ... Anyway, lets try to plan to get it out
"before Christmas", ok? :)

Regards,
Bill Page.