[Axiom-developer] 20071215.01.tpd.patch

[root]

For some reason this changeset does not appear on the list.
This is my 4th try.

This changeset creates a new hyperdoc facility that can be used from a browser.

This is not production-ready but is first-draft. There are many known
problems but please post anything you find wrong. 

This work is a joint effort with Arthur Ralfs and Alfredo Portes. 
Alasdair McAndrew contributed the Cryptography pages. 
I contributed the mistakes.



To use this you start Axiom and type

   )browse

at the command prompt. Axiom will now serve AJAX pages on port 8085.
To see the new hyper pages in the browser you need to know the local
IP address (127.0.0.1 should work) and the path to $AXIOM, which we
will assume is something like /usr/local/axiom/mnt/linux. 

It is also assumed that your browser supports AJAX and mathML. All
testing has been done using Firefox which supports both. If it doesn't
work in your browser please post javascript patches. I had to learn
javascript for this effort and I'm not familiar with browser-specific
hacks.

Start your firefox browser and go to:

  http://127.0.0.1:8085/usr/local/axiom/mnt/linux/doc/hypertex/rootpage.xhtml

that is

  http://(yourIP):8085(your$AXIOM)/doc/hypertex/rootpage.xhtml

Note: the ".xhtml" is not a typo. It really is .xhtml.

Note that Firefox has Tools->Javascript Console for debugging. 
The Axiom browser pages should not generate any error messages there.
Please post any error messages you find (along with diff-Naur fixes?).

Note that you can run Axiom on linux and reach it from anywhere once
it starts serving pages. So it is possible to put up a copy of Axiom
that serves browser pages while using another copy to do useful work.
It is also possible to serve pages to a Windows box, obviously.

The "Any Command" will eventually become a workbook kind of interface
that will allow you to work on Axiom directly from the browser. Thus
you can run Axiom anywhere and work on it from somewhere else.

I still don't know how to do drag-and-drop to a browser page so if
anyone knows how (or finds a tutorial how) to do this, please let me
know. I'd like to enable dragging a pamphlet file onto Axiom and have
it installed automatically.





Handling MathML Fonts

The last entry in the rootpage is a Fonts page which will test whether
you have the proper fonts installed to handle the Axiom MathML output.
If not, see the FAQ 44: I don't have the math fonts. 

There is a file zips/axiomfonts.tgz which contains some linux and stix
fonts as well as some instructions for downloading the
free-but-non-distributable Mathematica fonts. I gave a couple
instructions for installing linux fonts in the README file inside
axiomfonts.tgz. If you do need to install fonts, please document the
process and post it so we can all benefit.




Working

Most of the working pages exist under the Basic Commands and Topics
pages. Arthur Ralf's version of the Axiom book, converted to MathML
and AJAX, exists under the Axiom Textbook link. (see src/hyper/axbook.tgz)

All of the html pages are in src/hyper/bookvol11.pamphlet. That file
also contains instructions for creating new pages. 

The rootpage background image is src/hyper/bigbayou.png. 
The per-page banner is src/hyper/doctitle.png.

There are new pages that do not exist in the current hyperdoc.
For instance Topics->Cryptography contains the course notes for
Alasdair McAndrew's Cryptography course.

More new pages are planned but not yet available. It is very easy to
create new pages so I expect that people will find adding
documentation using html acceptable. It was possible to add pages to
hyperdoc but I don't know of anyone who wrote new pages except the
original group. Hopefully this will change now that they are html.

I have started trying to add new pages related to external material.
I've been auditing the MIT Courseware Mathematical Methods course.
My notes are being written into pages (see Topics->Mathematical Methods).

Other links are known not to work. Some of the pages have been 
partially expanded and you will hit "page not implemented".




Not working

The basic functionality of all of the hyperdoc exists but there is
still a lot of conversion work to be done for many pages. There has
been no attention paid to the 
  Axiom Tutorial, 
  Reference, 
  Browser, 
  Examples,
  Settings, and 
  What's New 
links. The 
  Any Command 
link used to work but was broken by recent changes.



The )browse command

The )browse command has been added to the system. As part of this
change some of the top level command handling has been added to book
volume 5 (the interpreter, see src/interp/bookvol5.pamphlet).  There
has been a rewrite of some of the top-level command handling into
lisp. Various functions have been brought together and documented. 
Further collection, rewrite, and documentation of the command handling 
will occur with new updates.

Note that there is currently no exit from the browse command.
Once it starts serving pages you have to interrupt the command loop.
Interrupting the command loop will leave the socket hung so you cannot
restart the )browse command. An EXIT command from the browser is planned.

The )browse command needs to accept a port and a path as arguments.
Currently these are hardcoded as "8085" and "/". The default should
be your $AXIOM variable if it is set.





Hyperdoc

Hyperdoc is unchanged. It should still work. However, the plan is
to completely drop hyperdoc, all C source code, all pages, and any
supporting boot/lisp functionality once the browser becomes stable.
This should considerably reduce the system complexity and reduce
the need for X11. (The graphics needs to be redone before all the
C and X11 support can disappear.)





The axserver.spad file

The src/algebra/axserver.spad file is the primary support for the 
AJAX/browser interface. It has been rewritten and expanded to handle
lisp calls, )show calls, and database lookups from the browser. 

Note that changing this file could potentially break the )browse
command.  Axiom hashes function names and changing the file MIGHT
break the hash. The |browse| command is sensitive to the hash which
might or might not change if the file is changed.  (See
src/interp/bookvol5, function |browse|)




The TODO list

It's long and, for the most part, tedious. 
 o Pages need to be converted from hyperdoc. 
 o The tutorial book needs to be converted to AJAX/MathML.
 o The Graphics needs to be embedded in a canvas tag. 
 o The notebook interface will replace the Any Command so that Axiom 
   can be used directly in the browser. 
 o The EXIT command needs to exit )browse and reset the socket. 
 o The )browse command needs )port and )path options
 o The input/regression test files need to be integrated into the browser 
   as examples. 
 o The )help files need to be integrated into the browser. 
 o The dvi files need to be processed into pdf so the
   source code can be displayed in the browser.
 o Automatic html cross-linking needs to be integrated into the build.
 o Live links from the source code need to be hyperlinks.
 o Axiom error message need html links to browse for further information
 o Pamphlet drag-and-drop needs to be demonstrated.
 o etc.

Tim