[Axiom-developer] code walker and crystal

[root]

Kai,

what i'm doing is pure dogwork. there are interesting parts to be
done which i have "in plan" and you can clearly get there first.
they will get done but not real soon. so i'll give you some thoughts.

besides the summer work that you're doing i think the main thing you
could help with is making the books more useful. we need a standard
who-calls/called-by mechanism for creating index entries. my experience
working with publishers is that they know that a good index is very
valuable. they have professionals on staff who help authors. several
lisps have this kind of mechanism and i've even written one once but
that was long ago and the code is gone. you have to be clever because
macros can hide code calls.

we need to find (or write) a code-walker that can collect this
information and we need to add it to the process so it can be
used to generate automatic index entries in latex. so the input
is a set of lisp files and the output is a latex index file.
assume lisp code so you can manipulate source code as data.

another subproject is to get the code hierarchy (per CY's note)
into some graphing format. i've downloaded CL-DOT from
http://www.cliki.net/cl-dot but have not had time to play with it.
there may be other/better tools. Bill has looked at some of them.
ideally this would use mcclim so we can gain expertise in lisp graphics.
i'd like to get diagrams autogenerated in the book. and i'd like
to be able to click on graph nodes entries and go right to the code
(hyperlinking in graphs).

plus this leads the way to a larger project which Bill and i have
struggled with, namely the algebra hierarchy.

the algebra hierarchy is a directed circular graph with 1100 nodes.
we need to untangle it better as the last pass was done by hand.
Bill and i have both attempted this without success. the problem
is big and hard.

beside the code-walker/algebra/graphic improvements in the books
this will give us some ideas about how to do the graphics in lisp.

the code indexer and the code grapher are both subprojects i have
"in plan" but have not yet had the cycles to devote to it.

if you REALLY want to think about the larger picture (pun intended) of
these two efforts we really need to think of the code, the walker, the
book, and the graph as "facets" in the crystal. the hard problem is
combining these things with machinery so that updating one updates all
of the others automatically. edit the book, save the book, type make
which rewalks the code, rebuilds the index, the book, the bib, and
piles it all together.

riffing off (ripping off?) bill's wiki idea consider a web page design
where there are 8 "facet" links around the page (the 4 edges and the
4 corners, probably 1/8 inch border.) consider each border area to
be a command (actually a hyperlink but with save/regen of the current
modified page) to "rotate" the crystal. so a browser "page" becomes
a "crystal facet" where you can see tiny labeled portions of the other
facets around the edge of the current page. (it takes some imagination
to view a page as a facet. think of getting REAL close to a crystal)

assume the wiki web pages are running locally.
assume all the horsepower in the world so everything gets updated
directly from sources and rebuilt every time on every change.

modifying one facet (say the code facet) in the web page would update
the other N facets (code walker, code graph, book page, index table,
who calls, who called, constant list, variable list, axiom shell,
etc). 


  whocalls                                               calledby
     +-------------------------------------------------------+
     |  /              graph                              \  |
     + +---------------------------------------------------+ +
     |/|                                                   |\|
     | |                                                   | |
     | |                                                   | |
     | |                                                   | |
     | |                                                   | |
     |a|                                                   |b|
     |x|                                                   |o|
     |i|                                                   |o|
     |o|                                                   |k|
     |m|             SOURCE CODE                           | |
     | |                                                   | |
     |s|                                                   | |
     |h|                                                   | |
     |e|                                                   | |
     |l|                                                   | |
     |l|                                                   | |
     | |                                                   | |
     | |                                                   | |
     |\|                                                   |/|
     + +---------------------------------------------------+ +
     |  \               index                             /  |
     +-------------------------------------------------------+
  constant                                                variable 
   usage                                                   usage


similarly, another facet might lead to the algebra sources
or the problem statement, the literature references, the
"semantic graph", the latex, the pdf, etc.


   pdf                                                   semantic net
     +-------------------------------------------------------+
     |  /              latex                              \  |
     + +---------------------------------------------------+ +
     |/|                                                   |\|
     | |                                                   | |
     | |                                                   | |
     | |                                                   | |
     | |                                                   | |
     |r|                                                   |b|
     |e|                                                   |o|
     |f|                                                   |o|
     |e|                                                   |k|
     |r|             AXIOM SHELL                           | |
     |e|                                                   | |
     |n|             ->                                    | |
     |c|                                                   | |
     |e|                                                   | |
     |s|                                                   | |
     | |                                                   | |
     | |                                                   | |
     | |                                                   | |
     |\|                                                   |/|
     + +---------------------------------------------------+ +
     |  \               bibliography                      /  |
     +-------------------------------------------------------+
  spad code                                                literature
                                                            search

rather than shovelling source code in the same ditch it would be
much more productive to begin to think about the longer term. the
hard part is seeing that apparently simple problems (like a code
indexer) fit into the long term. even a code indexer is hard because
you have to figure out how to make it all happen "automagiacally".

t