\documentclass{book}
%\newcommand{\VolumeName}{Volume 2: Axiom Users Guide}
%\input{bookheader.tex}
\pagenumbering{arabic}
\mainmatter
\setcounter{chapter}{0} % Chapter 1

\usepackage{makeidx}
\makeindex
\begin{document}
\begin{verbatim}
\start
Date: Sun, 4 Dec 2011 12:24:45 -0600
From: Tim Daly
To: list
Subject: Axiom Code Graphs

I am experimenting with dynamic code graphs for the Axiom source code.
I have put up 3 graphs, two come from the Jenks book flyleaf.
One is the graph of the source code for the compiler. See

http://axiom-developer.org/axiom-website/axiomgraph/index.html

\start
Date: Mon, 5 Dec 2011 10:54:55 +1100
From: Minh Nguyen
To: Tim Daly
Subject: Re: Axiom Code Graphs

Hi Tim,

On Mon, Dec 5, 2011 at 5:24 AM,  Tim Daly wrote:
> I am experimenting with dynamic code graphs for the Axiom source code.
> I have put up 3 graphs, two come from the Jenks book flyleaf.
> One is the graph of the source code for the compiler.

Do you happen to know how the graphs are produced?  I'm interested in
an automated way to produce such graphs from each source release of
Axiom.

\start
Date: Sun, 04 Dec 2011 19:42:01 -0500
From: Tim Daly
To: Minh Nguyen
Subject: Re: Axiom Code Graphs

Look at the file
http://axiom-developer.org/axiom-website/axiomgraph/maps/algebra.json

It is a json format file. The top level is a hashmap of 2 items
{"nodes": { ... },
 "edges": { ... }
}

Each node is a pair, as in:

  "ABELGRP" : {"c":"back" , "visible":"show"}

Each edge is a pair, as in:

  "ABELGRP" : {"CABMON":{},"LMODULE":{},...}


The node data structure gives a label ("ABELGRP") for every
node in the graph. The attributes are used to control how to
color the node ("back" == background color) and whether to
show the node (
"visible" == "show" ==> show it
"visible" == "hide" ==> hide it
"visible" == "icon" ==> show a rectangle without a label

The edge data structure determines lines between the nodes.
So "ABELGRP" has a line to "CABMON", "LMODULE", etc...

The color attribute is interpreted in the file axiomgraph.js
http://axiom-developer.org/axiom-website/axiomgraph/js/axiomgraph.js

There is a variable called "tencolors" which gives meaning to the
"c" variable. So "back" becomes "#ECEA81" which is the background
color of the page. This makes the bounding rectangle disappear and
leave only the text. The background color of the page is determined
in the file
http://axiom-developer.org/axiom-website/axiomgraph/style/axiomgraph.css
with the "body" CSS tag. The color "ECEA81" is the new global color
of the Axiom web pages.

The variable "tencomplement" is the inverse color so the text will
show up on the bounding box. So setting the "c" variable to "calls"
will set the box background color to "#0000FF" and the text in the
box to "#FFFF00".

The "visible" variable is interpreted (badly) in the axiomgraph.js
file at line 66 (to determine line colors) and line 210 (to determine
whether the text shows).


If you copy the axiomgraph subdirectory
wget http://axiom-developer.org/axiom-website/axiomgraph
you will have a complete, working copy. Then you can modify the
maps subdirectory with a new map.

When adding a new map you need to change lines 180 to include
your new map. For example, to create a new map "nguyen.json"

in maps/nguyen.json:
{"nodes":
  {"node1" : {"c":"White","visible":"show"},
   "node2" : {"c":"Yellow","visible":"show"}
  },
 "edges":
  {"node1" : {"node2":{}},
   "node2" : {"node1":{}}
  }
}

add a new in axiomgraph.js that reads:
nguyen:(title:"MyGraph",;:{stiffness:500},source:_sources:mine}

The _sources variable is at line 174. Add the line
mine:'I am the source of this graph'
and it will show up in the "datalink" div at the bottom
of the screen. The "datalink" dev is defined in index.html

Let me know if you have any questions.

On Mon, 2011-12-05 at 10:54 +1100, Minh Nguyen wrote:
> Hi Tim,
> 
> On Mon, Dec 5, 2011 at 5:24 AM,  Tim Daly wrote:
> > I am experimenting with dynamic code graphs for the Axiom source code.
> > I have put up 3 graphs, two come from the Jenks book flyleaf.
> > One is the graph of the source code for the compiler.
> 
> Do you happen to know how the graphs are produced?  I'm interested in
> an automated way to produce such graphs from each source release of
> Axiom.

\start
Date: Sun, 04 Dec 2011 19:51:48 -0500
From: Tim Daly
To: Minh Nguyen
Subject: Re: Axiom Code Graphs

On Sun, 2011-12-04 at 19:42 -0500, daly wrote:
> The color attribute is interpreted in the file axiomgraph.js
> http://axiom-developer.org/axiom-website/axiomgraph/js/axiomgraph.js
> 
> 

Sorry, my mistake. That link should be:
The color attribute is interpreted in the file axiomcode.js
http://axiom-developer.org/axiom-website/axiomgraph/js/axiomcode.js

\start
Date: Sun, 04 Dec 2011 19:55:55 -0500
From: Tim Daly
To: Minh Nguyen
Subject: Re: Axiom Code Graphs

On Mon, 2011-12-05 at 10:54 +1100, Minh Nguyen wrote:
> Hi Tim,
> 
> On Mon, Dec 5, 2011 at 5:24 AM,  Tim Daly wrote:
> > I am experimenting with dynamic code graphs for the Axiom source code.
> > I have put up 3 graphs, two come from the Jenks book flyleaf.
> > One is the graph of the source code for the compiler.
> 
> Do you happen to know how the graphs are produced?  I'm interested in
> an automated way to produce such graphs from each source release of
> Axiom.
> 

Yes, the nodes are intended to be active with hover information
and links to the code in the literate sources. Of course, I
still have to figure out how to make that work.

I'm also thinking about a breadth-first expansion of the selected
node so you could navigate. Clicking on a node shows the nearest
neighbors and hides the rest. That's still to be coded and tried.

\start
Date: Mon, 5 Dec 2011 17:19:49 +1100
From: Minh Nguyen
To: Tim Daly
Subject: Re: Axiom Code Graphs

Hi Tim,

On Mon, Dec 5, 2011 at 11:42 AM, Tim Daly wrote:
<SNIP>
> Let me know if you have any questions.

Thank you for your detailed explanation.  Let me explain what I want
to do with the Axiom source code.  As part of my research project, I
want to collect datasets on a variety of domains such as social
interactions and technology.  For each domain, collect time stamped
datasets on it.  In the case of the Axiom project, this means
downloading all stable source releases of Axiom up to and including
the latest stable release.  For each release, get a list of all
functions, classes, methods, etc. and work out which one calls which.
The general idea is to construct a (di)graph representation of such
data in a source release.  I'm working on developing a mathematical
model to explain how such interactions among units within a domain
(e.g. functions, classes, methods in Axiom) change over time.  As you
can guess, my stumbling block is how to extract a list of all
functions, classes, methods, etc. from each Axiom source release and
work out which one invokes which.  I hope you would help me by
shedding some light on how to parse the Axiom source code in order to
obtain the interaction (di)graphs I described above.

\start
Date: Mon, 05 Dec 2011 02:37:36 -0500
From: Tim Daly
To: Minh Nguyen
Subject: Re: Axiom Code Graphs

On Mon, 2011-12-05 at 17:19 +1100, Minh Nguyen wrote:
> Hi Tim,
> 
> On Mon, Dec 5, 2011 at 11:42 AM, Tim Daly wrote:
> <SNIP>
> > Let me know if you have any questions.
> 
> Thank you for your detailed explanation.  Let me explain what I want
> to do with the Axiom source code.  As part of my research project, I
> want to collect datasets on a variety of domains such as social
> interactions and technology.  For each domain, collect time stamped
> datasets on it.  In the case of the Axiom project, this means
> downloading all stable source releases of Axiom up to and including
> the latest stable release.  For each release, get a list of all
> functions, classes, methods, etc. and work out which one calls which.
> The general idea is to construct a (di)graph representation of such
> data in a source release.  I'm working on developing a mathematical
> model to explain how such interactions among units within a domain
> (e.g. functions, classes, methods in Axiom) change over time.  As you
> can guess, my stumbling block is how to extract a list of all
> functions, classes, methods, etc. from each Axiom source release and
> work out which one invokes which.  I hope you would help me by
> shedding some light on how to parse the Axiom source code in order to
> obtain the interaction (di)graphs I described above.
> 

The Axiom source code is quite stable. In general we have been
rewriting the system into pure common lisp. This does not involve
changes to the function names or calling sequences. Code is 
migrating from individual files into literate books so many of
the files in src/interp have been removed.

Axiom is released every 2 months. The source code for the last
few releases is at
http://axiom-developer.org/axiom-website/download.html

If you do
    git clone git://github.com/daly/axiom.git
you will get every change made to Axiom for the last 4 or 5
years. You can use git to see every change. I should warn you
that, on average, we have committed a new change every day.

There are 5 classes of changes. First, there is a rewrite of code
from the Boot language to common lisp. This does not change the
function. Boot is just a syntactic sugar that translates to lisp.

Second, code that is not used has been removed. For instance,
the code to support Aldor is gone.

Third, code that implements MacLisp and LispVM idioms is being
rewritten into straight common lisp.

Fourth, there have been file renames for 2 reasons. The whole
system was changed so every filename is only lower case. The
whole src/interp directory of files was renamed when support
for Boot was removed.

Fifth, new code has been added. There is new code for:
algebra, such as support for special functions,
HTML, such as Volume 11, which is the Axiom HTML browser,
numerics, such as Volume 10.5,
MathML, such as Arthur's extensions,
OpenMath, including the semantic CDs.

If you just want the names of functions or variables in any
release you can start Axiom and type:
 )lisp (do-all-symbols (x) 
        (format t "~s:~s~%" (symbol-package x) (symbol-name x)))
all on one line. This will list all of the function and
variable names. You can collect these lists and find what
changes from one version to the next.

\start
Date: Sat, 10 Dec 2011 12:56:08 +0000 (GMT)
From: Leon Dutoit
To: list
Subject: axiom and glibc-2.14


Compilation of axiom fails on slackware64 (current) because in glibc-2.14 s=
upport of rpc has been suppressed.=0A=0AThe problem is with gcl-2.6.8pre4 (=
and maybe after). =0A=0A=0ATo have rpc support the library "libtiprc" must =
be installed, but then at the link stage "-ltirpc" should be added.=0AThis =
is apparently not checked in the configure script in gcl-2.6.8pre4.

\start
Date: Sun, 18 Dec 2011 13:29:44 +0100
From: Udo Ott
To: list
Subject: Overflow

Hello,

since some days I am using Axiom-Ubuntu-64Bit in order to construct
combinatorial structures with the help of a back-tracking algorithm.

Unfortunately, after about 2**12 calls the function terminates with the
system error

frame stack overflow

What can I do to allow more calls?

Secend question: Is there a version of Axiom-XL for Ubuntu 64-Bit?

Thank you for your help

Sincerely yours, Udo Ott.

\start
Date: Wed, 21 Dec 2011 06:35:37 -0500
From: Tim Daly
To: Udo Ott
Subject: Re: Overflow

Sorry for the delay in the reply.
I tried to build a 64 bit version and failed.
I'm not sure I can help you. You may have to
rethink the algorithm.

Tim

On Sun, 2011-12-18 at 13:29 +0100, Udo Ott wrote:
> Hello,
> 
> since some days I am using Axiom-Ubuntu-64Bit in order to construct
> combinatorial structures with the help of a back-tracking algorithm.
> 
> Unfortunately, after about 2**12 calls the function terminates with
> the system error
> 
> frame stack overflow
> 
> What can I do to allow more calls?
> 
> Secend question: Is there a version of Axiom-XL for Ubuntu 64-Bit?
> 
> Thank you for your help
> 
\start
Date: Thu, 22 Dec 2011 10:45:04 -0500
From: Bill Page
To: Udo Ott
Subject: Re: Overflow

Udo Ott,

As you might be aware, the message:

  frame stack overflow

is generated by the Lisp system apon which the version of Axiom that
you are using is built. Exactly how to configure the Lisp memory
configuration to allow a greater depth of recursion or other possible
constraints is highly dependent on the particular version of Lisp you
are using. I expect that Axiom-Ubuntu-64Bit is using GCL but I am not
certain. If so you might look online for configuration suggestions
from GCL users.  Axiom and especially it's variants OpenAxiom and
FriCAS can be built with several different Lisp systems and each
manages memory a little differently so it is possible that you might
get more "mileage" with Axiom (or OpenAxiom or FriCAS) built with some
other Lisp such as SBCL, CLISP, or ECL.  Again, exactly how to do this
depends on the particular variant of Axiom and Lisp.

You may be able to find some hints about this at
http://axiom-wiki.newsynthesis.org For example the page

  http://axiom-wiki.newsynthesis.org/SandBoxAldorGenerator

but like most wiki's this information is only as good as the
dedication of the people who created and modified the page.

AXIOM-XL is an obsolete name for Aldor which many years ago was
intended to become the "next generation" compiler for Axiom. At this
time only the FriCAS project supports the use of Aldor. Due to
licensing constraints Aldor must be compiled separately from FriCAS.
See http://www.aldor.org  or
http://algebraist.origo.ethz.ch/wiki/algebraist.  When used with
FriCAS the code generated by Aldor is compiled using the same
underlying Lisp system, so memory constraints are similar to using
SPAD.  But Aldor can also be used in a "stand alone" mode in which it
compiles and links to a C runtime system.  In this case the memory
usage is likely to be quite different (although not necessary better)
than when using Lisp.

I hope some of this information helps.

On Sun, Dec 18, 2011 at 7:29 AM, Udo Ott Udo Ott wrote:
> Hello,
>
> since some days I am using Axiom-Ubuntu-64Bit in order to construct
> combinatorial structures with the help of a back-tracking algorithm.
>
> Unfortunately, after about 2**12 calls the function terminates with the
> system error
>
> frame stack overflow
>
> What can I do to allow more calls?
>
> Secend question: Is there a version of Axiom-XL for Ubuntu 64-Bit?
>
> Thank you for your help

\start
Date: Fri, 23 Dec 2011 03:45:11 -0600
From: Tim Daly
To: gcl-devel@gnu.org
Subject: read-from-string bug

gcl-2.6.8 built from repository source on Dec 22, 2011

This works:

(read-from-string ";;;" nil nil :start 0)

This fails:

(read-from-string ";;;" nil nil :start 0 :preserve-whitespace t)

The read-from-string calls read-preserving-whitespace 
which wanders off to lsp/gcl_iolib.c
which is where you lost me.

\start
Date: Fri, 23 Dec 2011 23:37:07 -0600
From: Tim Daly
To: Adam Getchell
Subject: Literate Programming

Good Sir and Fellow Traveler, 

On Fri, 2011-12-23 at 03:33 -0800, Adam Getchell wrote:
> Having received the benefit of your kind reply, I must confess to a
> puzzlement which has vexed me ever since I read your missive. It is
> this: how should I have read it so as to receive some knowledge or
> insight with which I had not formerly possessed in the moments prior?
> For in truth I have not been able to discern its helpfulness thereby.

Methinks thou hast conflated the spirit of literate programming, 
intended as a communication medium between fellow traveling souls
on this dark road with the substance of the task involving the
choice of conveyance and walking stick. Replying to the former
'twas I, whilest thou was't addressing the latter. 

We did pass by in our respective darkness. 
Forgive me for lacking light to guide your chosen path.
I mistook your destination for mine own, a grievous fault,
one to which I am ever prone.

> Clearly, as a craftsman of computer algebra tools yourself, you 
> must agree that the selection of implements is of some import,
> lest you abandon that enterprise entirely and use Mathematica 
> instead.

Truly I do quake at the co-opting possible should the fair winds
drift the conversation from the soul of the art to the choice and
heft of tooling. Like the goodly Saint Alexander [1] we need to 
seek the order which contains life. What doth make a program live,
or the building alive, is not to be found in the tooling but in
ourselves. We must eschew the pernicious present practice lest
we find our creation among the dead and dying on Sourceforge.

I have chosen minimal tools for my algebra opus. Latex for
smithing and tangle for forging. I find no need for any other
save the, as yet unrealized, potential of graphing tools.

'Tis not the tools but my poor craftsmanship that constrains 
the quality of the work.

>> The combination of literate + TDD seems forbidding
>  Are you finding it hard to explain why you wrote a test?

In this platonic exchange is made apparent my confusion. The
dross of failures that skins the molten and fluid gold of your
smelting needs but a few words. "Lo, this might arise at the
boundary of my creation." That the dross needeth explaining
to the Smithy new to your endeavor, yet still it certainly
can be conveyed in flowing natural language.

Sharing the tale of the journey, the wonders of the vision, and
the pleasures of final offering depends not on the choice of pen 
but on the craftmanship of language. That the gentle reader
delight in your creation and sing its praises, see the vision,
and dedication lifeblood to its continuance is all. That we might 
achieve such essential Quality [2] with Clojure is the dream.

Sir Tim Daly, Elder of the Internet


[1] Alexander, Christopher 
"The Nature of Order: The Phenomenon of Life"
2002 ISBN 0-9726529-1-4

[2] Persig, Robert
"Zen and the Art of Motorcycle Maintenance: An Inquiry into Values"
1974 ISBN 0-553-27747-2

\start
Date: Sun, 25 Dec 2011 02:36:09 -0500
From: Tim Daly
To: Jay Edwards
Subject: Re: Literate Programming
Cc: Nick Church

On Sat, 2011-12-24 at 12:56 -0600, Jay Edwards wrote:
> Like this?  http://brighterplanet.github.com/flight/impact_model.html

My first reaction, after the first reading was "almost ok".

The task is reasonably mathematical so it seems useful to 
show the equations. Unfortunately, at the end, I have to ask
myself the "Hawaii question".... If someone sent me off to
hawaii (so I couldn't talk to the author), would I know enough
to maintain the program?

Well, maybe. 

I really liked that they embedded a link to the impacts web page.
That placed the problem in context.

And I especially liked
   "A multiplier to account for the extra climate impact of 
    greenhouse gas emissions high in the atmosphere.

    Use 2.0 after Kollmuss and Crimmins (2009)."

I was unhappy with:

=begin
  FIXME TODO date should already be coerced
=end

Really? Coerced to what, by what, for what reason, in what format?
I was just hired and asked to solve this problem.

=begin
  FIXME TODO deal with cities in multiple countries that share a name
  Tried pushing country, which works on a flight from Mexico City to 
  Barcelona, Spain because it does not include flights to Barcelona, 
  Venezuela BUT it doesn't work if we're trying to go from Montreal
  end up with flights to London, United Kingdom. Also pushing country
  breaks addition of cohorts - all 'AND' statements get changed to 'OR' 
  so you end up with all flights to that country e.g. WHERE 
  origin_airport_iata_code = 'JFK' OR origin_country_iso_3166_code =
'US'
=end

So why isn't this part of the dialog? Why does it break? Is the
database improperly structured? Do we need a schema change? Or
do we need program logic to handle this case?

The use of FIXME is horribly jarring. Get rid of it.

Think of a calculus textbook where the source code is the equations.
Now imagine that in the middle of an equation you see the above
comment. Something like:

   area = \sum_i^j x*3 =begin FIXME might be x^4 =end * y

The editor-in-chief would never let the above equation get into
the text. The FIXME should be discussed as part of the prose
rather than "in the equations". 

I don't think it would pass the code review phase with these
"FIXME" things hanging around. FIXME is the programmer's internal
dialog. Discuss the issue in the text as though you were talking
to someone other than yourself. Odds are good this is where a
design mistake (e.g. in the database schema) or a program bug lurks.

The meta-issue is distinguishing "communication" from "documentation".
Literate programming is about communication, not documentation.

Write with your audience in mind and assume that the audience is
NOT your shower committee (a shower committee is the group of people
you talk to in the shower who are not really there).

This example really skates along the border. Overall I think it is
wildly better than most examples I've seen. I'd much rather maintain
this program with the text than without it. I'd certainly place it
on the high side of the curve. 









\end{verbatim}
\eject
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\cleardoublepage
%\phantomsection
\addcontentsline{toc}{chapter}{Bibliography}
\bibliographystyle{axiom}
\bibliography{axiom}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\cleardoublepage
%\phantomsection
\addcontentsline{toc}{chapter}{Index}
\printindex
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\end{document}
