\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, 04 Sep 2011 18:09:35 -0400
From: Tim Daly
To: Grigory Sarnitskiy
Subject: Re: How was axiom's bookvol10.2.pamphlet file generated?

It occurs to me that I didn't fully answer your question about
the complete graph information. 

The complete graph is VERY complex and I could not find a way
to visualize the whole thing. I'm getting better at HTML5,
Javascript, and CSS so I may eventually figure out a good way.

In any case, the complete dependence graph information is 
available in src/algebra/Makefile.pamphlet. The layerpic
chunks have all of the edges listed although mostly as
comments. Only the "supporting edge" is not commented.

To construct a "supporting edge" you need to find out every
dependence and then find the one in the highest layer. This
forces a new domain to be one layer higher and is the edge
that supports the new domain. So everything in layer 14
depends on something in layer 13 and nothing in or above
layer 14.

Adding new algebra involves finding the supporting edge.
I have written some code for this but it is not very robust
so it is not part of the system.

If you really want to construct the "FULL" graph you can use
the dot information in src/algebra/Makefile.pamphlet. All you
need to do is uncomment the dot commands in the layerpic chunks.

On Sun, 2011-08-28 at 16:19 +0400, Grigory Sarnitskiy wrote:
> 
> 08.08.2011, 00:25, Tim Daly:
> > The pamphlet file was hand generated. Pamphlet files are the source
> > code of the system.All of the pamphlet files are source code and are
> > hand generated in latex.
> >
> > The system is moving to using pure latex rather than using noweb for the
> > pamphlet format. A new latex "chunk" environment was written to support
> > this. All of the new latex macros are in the axiom.sty file. Volume 10.2
> > (the category structure) is still in noweb format for the moment but this
> > will change.
> >
> > Axiom's source structure is being moved from the "tree-of-tiny-files"
> > structure into a "literate software" structure. The process involves
> > rewriting the source code into straight common lisp. Each function is
> > rewritten and placed into one of the pamphlets in the books directory.
> > This phase takes a while as there are about 1M "things of code" that
> > need to be rewritten. Work is currently being done in volume 5 (the
> > interpreter) and volume 9 (the compiler).
> >
> > The next step is to organize and document the system using these books.
> > The ultimate idea is that you will be able to read the system as a
> > series of novels, moving from ideas to implementation.
> >
> > Volume 10.2 (categories) is the category structure of the system.
> > It is currently in alphabetical order but that will change in whatever
> > way needed to support the human documentation.
> >
> > Tim Daly
 
> And how were graphs generated from this pamphlet? I mean dotfull and
  dotabb. The latter is supplied with axiom sources (in
  axiom/src/axiom-website), but I want to have dot source for the full
  name graph.

\start
Date: Thu, 22 Sep 2011 12:18:31 +0400
From: Dmitry Semikin
To: list
Subject: [axiom-developer] What do diagrams in bookvol10.3 mean?

Hi, axiom-developers,

I'm new to axiom and just getting aquainted to it, trying to solve my
problems using it, so please, forgive me, if I ask questions with obvious
answers.

The one thing, which confused me is what do diagrams in bookvol10.3 (Domains
reference) mean.

The first question is what is the legend? It seems to me, that green boxes
are domains and blue ones are categories. But there are some other colors
and shapes. What do they mean? Is some kind of legend given anywhere?

The sencod question is what kind of relation is depicted on those diagrams?
E.g. for the category Symbol we have diagram with arrow pointing to STRICAT
(StringCategory) category. But if I look at the code bellow (in the same
section of the bookvol10.3) or browse documentation of the Symbol in the
HyperDoc, I cannot find any reference to StringCategory. So, what is the
relation, depicted in the diagram in the bookvol 10.3? (Note: similar
situation presents for other domains eiher).

\start
Date: Thu, 22 Sep 2011 10:29:13 +0200
From: Ralf Hemmecke
To: list
Subject: Re: [axiom-developer] What do diagrams in bookvol10.3 mean?

> The first question is what is the legend?

Page 1?

> The sencod question is what kind of relation is depicted on those
> diagrams?

Hmmm, that's really hard to decipher. I have no idea.

\start
Date: Thu, 22 Sep 2011 11:05:53 +0200
From: Ralf Hemmecke
To: Dmitry Semikin
Subject: Re: [axiom-developer] What do diagrams in bookvol10.3 mean?

>     Page 1?

Actually, page 1 seems to suggest that the diagrams have nothing to do 
with inheritance but rather with build dependency (read the first 
paragraph).

> By the way, are those diagrams generated automatically, or they are
> hand-made?

I'm not sure, but 
https://github.com/daly/axiom/blob/master/books/ps/v103symbol.ps 
suggests that they are "pre-made" and stored in the version control 
system. Tim can probably tell you more truth here.

In what are you actually interested in? Pose your problem and maybe 
there is someone who can help you. Reading all the details of the 
implementation is probably not something a newcomer should do. It's well 
known that Axiom has a very steep learning curve. There's no trivial 
route around it since the system *is* really complex.

PS: If you want me to anwser further mails, you'd better keep CC'ing the 
mailing list.

\start
Date: Thu, 22 Sep 2011 13:10:39 +0400
From: Dmitry Semikin
To: list
Subject: HyperDoc bug

May be, the bug is known, I did not found any public issue tracker (I mean
alive one). So, here it is:

AXIOM Computer Algebra System
Version: Axiom (July 2011)
Timestemp: Monday September 19, 2011 at 02:15:02

OS: Ubuntu 10.10 (running within VMWare Player under Windows XP)

1. In HyperDoc window click Browse
2. Type in: "CARTEN" into search line
3. Click "Constructors" bellow

Result: HyperDoc window is closed, the following line is printed out in
console:
>> System error:
The function MAKE-INPUT-FILENAME is undefined.


After that typing ")hd" into the console brings HyperDoc window, there is
warning string in the console:
binding UNIX server socket: Address already in use (HyperDoc) Warning: Not
conected to AXIOM server!

and Browse facility of Hyperdoc do not work.


Note: The same thing happens with other domains too (e.g. Integer). More
over, it looks, like HyperDoc crashes, when I try to access domain
descriptions. E. g. If I go to some Category description (it works), and
than use "Domains" link at the bottom, the result is the same.

Note: The same behaviour is observed in standard Ubuntu package AXIOM (there
earlier version of axiom is included).

\start
Date: Thu, 22 Sep 2011 11:26:58 +0200
From: Ralf Hemmecke
To: list
Subject: Re: HyperDoc bug

> Result: HyperDoc window is closed, the following line is printed out in
> console:
>  >> System error:
> The function MAKE-INPUT-FILENAME is undefined.

Sorry, I cannot help here since I'm actually a FriCAS user (I don't have 
AXIOM installed) and in FriCAS I cannot reproduce this bug.

\start
Date: Thu, 22 Sep 2011 14:33:24 +0400
From: Dmitry Semikin
To: Ralf Hemmecke
Subject: Re: [axiom-developer] What do diagrams in bookvol10.3 mean?

Ralf, thanks again.

Actually, page 1 seems to suggest that the diagrams have nothing to do with
> inheritance but rather with build dependency (read the first paragraph).


I see. I treated voluemes 10.2, 10.3, 10.4 as printed version of (extended)
library reference. But I see, that actually, it is much more, that it
includes either testcases and building process related information.

Now I see, that actually for reference HyperDoc is much better option, than
those volumes... But in my distribution for some reason HyperDoc do not show
reference information on domains (I've posted it to this mailing list with
other topic). I either did not find any HTML documentation, so I started to
look into PDFs. But there are only AXIOM-book, which is good tutorial, but
not reference. And those volumes...

Besides, in my opinion (it is only my opinion, but still it is opinion of
newcomer) HyperDoc documentaion is structured in non-standard fasion, which
makes it not so easy to use at the beginning. I mean the following thing:
when I look at other programming languages usually standard documentation
consists of the following parts:

1. Syntax reference (which is formal description of keywords and syntactic
costructs accepted by compiler or interpreter);
2. Standard library refererence, which lists and describes all packages,
classes, functions (in case of axiom - Domains, Categories, Packages and
operations).
3. Tutorial, which gives an overivew of standard facilities and pushes into
the language.

The very important thing, which must present in the beginning of any
tutorial (and overall documentaion) is how to get help for particular thing.
In axiom there are many things involved, such as )summary, )help, )what,
)hd, )describe, )show commands (by the way, not even all of them are listed
by )summary command). HyperDoc system - it pops up on start, so it is ok.
But it is structured in not so obvious way. Why AXIOM book is in Reference
secion? And why Reference->Language do not contain description of creation
of Domains, Packages and Categories? Where in reference compiler is
described? Why Examples anre in Reference section? etc... All those things
confuses for the first time significantly. Lack of formal syntax reference,
collected in one place is either makes learning harder.

Please, do not think, that I'm ungreatful man. Actually, I understand, that
great efforts was made to develop axiom system (and its help in particular).
I think, that axiom is really wonderfull (it is the only CAS I know, which
has strict typing and syntax similar to haskell... although I did not try
Reduce). I like it very much and I only hope, that things, that I've told
above will help make Axiom even better and easier for newcomers to adopt, so
more people will start working with it.

Sorry, all those things become off-topic, as initial post was about
diagrams...

By the way, are those diagrams generated automatically, or they are
>> hand-made?
>>
>
> I'm not sure, but https://github.com/daly/axiom/**blob/master/books/ps/**
> v103symbol.ps<https://github.com/daly/axiom/blob/master/books/ps/v103symbol.ps>suggests that they are "pre-made" and stored in the version control system.
> Tim can probably tell you more truth here.
>

I think, that it is enough truth for me at the moment. Thanks.

In what are you actually interested in? Pose your problem and maybe there is
> someone who can help you. Reading all the details of the implementation is
> probably not something a newcomer should do. It's well known that Axiom has
> a very steep learning curve. There's no trivial route around it since the
> system *is* really complex.
>

I already see it. The problem I'm solving can be formulated as following:
There is finite part of Taylor expansion of the Energy as function of one
vector and one tensor of sencod rank. If the expansion is taken up to the
4-th degrees on variables it already has about hundred of terms in it
(actually, I need expansion up to 6-th or 8-th degree). But the system has
some symmetries, so I should simplify this polynomial taking into account
the symmetries of underlying system.

Actually, at the moment for me the main issue is that axiom has too many
domains, categories and packages and I do not know what to start with.
(that's why I was wondering about diagrams, as I thought they could help me
to build hierarchies of Domains of categories - diagram given on the
axiom-developers.org is too big to be usable).

At the moment I think, that I will generate CartesianTensor(1, 3, Expression
Integer) of required rank, filled with symbols (named in spacial way, e.g.
a11 for the a[1,1]). And while generating those tensors I will imply
symmetries (actually, I'm not still sure how to do that, e.g., there are
some domains related to permutations, but looking at tham I cannot figure
out, if I can use them in my applicaiton). After tensors are generated, they
can be contracted and initial polynom (expression, coercible to polynom)
will be obtained. Than extract monomials (using Polynomial's operations with
monomials) one by one and check their sysmmetry properties.

If some one can give some hints about what can be used in solution of this
problem, I would really appreciate it.

PS: If you want me to anwser further mails, you'd better keep CC'ing the
> mailing list.
>

\start
Date: Thu, 22 Sep 2011 14:36:52 +0400
From: Dmitry Semikin
To: Ralf Hemmecke
Subject: Re: HyperDoc bug

> Sorry, I cannot help here since I'm actually a FriCAS user (I don't have
> AXIOM installed) and in FriCAS I cannot reproduce this bug.
>

Yes, I've found already, that in both: fricas and open-axiom this bug is not
reproduced. It presents itself only in original branch of Axiom.

Thanks anyway.

\start
Date: Thu, 22 Sep 2011 13:05:20 +0200
From: Ralf Hemmecke
To: Dmitry Semikin
Subject: Re: [axiom-developer] What do diagrams in bookvol10.3 mean?

> Besides, in my opinion (it is only my opinion, but still it is opinion
> of newcomer) HyperDoc documentaion is structured in non-standard fasion,
> which makes it not so easy to use at the beginning.

It's not just your opinion. But there is currently not enough manpower 
to treat every aspect of this big system. And if you look at the 
sources, you'll find that they are written in hypertex, which is close 
to tex, but has some hyperlinking features. There is no browser version 
since someone would have to translate (or automatically convert) the 
hypertex sources into html. Furthermore some of the sources, in 
particular the API descriptions are written in the source code itself as 
++ comments. These are currently automatically extracted from the code 
and made available to HyperDoc.

As for help, there is probably currently only HyperDoc and some friendly 
developers on the mailing list(s). I almost never use the )show, )what 
etc. commands but do all with hyperdoc.

> so it is ok. But it is structured in not so obvious way. Why AXIOM book
> is in Reference secion? And why Reference->Language do not contain
> description of creation of Domains, Packages and Categories? Where in
> reference compiler is described? Why Examples anre in Reference section?
> etc... All those things confuses for the first time significantly. Lack
> of formal syntax reference, collected in one place is either makes
> learning harder.

There are a few questions like "lack of formal syntax reference" that 
are not yet answered fully. Nobody has written a document about this (at 
least not to my knowledge). The closest thing you can find is the Aldor 
User Guide.

> Please, do not think, that I'm ungreatful man. Actually, I understand,
> that great efforts was made to develop axiom system (and its help in
> particular). I think, that axiom is really wonderfull (it is the only
> CAS I know, which has strict typing and syntax similar to haskell...
> although I did not try Reduce). I like it very much and I only hope,
> that things, that I've told above will help make Axiom even better and
> easier for newcomers to adopt, so more people will start working with it.

No problem. But the thing is, that even *you* can help. Posing such 
questions, suggesting improvements, etc. Be concrete, take your time and 
dig into the source code, ask other developers if you get stuck, provide 
patches. Axiom will not becoming better over night. More people are needed.

> (that's why I was wondering about diagrams, as I thought they could help
> me to build hierarchies of Domains of categories - diagram given on the
> axiom-developers.org <http://axiom-developers.org> is too big to be usable).

There are two quite usable diagrams in the original Axiom book by 
Jenks&Sutor. I don't however know whether these (smaller) hierarchies 
exist somewhere in the net.

> At the moment I think, that I will generate CartesianTensor(1, 3,
> Expression Integer) of required rank, ...

> If some one can give some hints about what can be used in solution of
> this problem, I would really appreciate it.

Open up a sandbox on http://axiom-wiki.newsynthesis.org, i.e. create, 
for example, the page 
http://axiom-wiki.newsynthesis.org/SandBoxTensorWithSymmetry and put 
your initial commands there. Perhaps, someone might help you in entering 
the right commands. Of course, you have to clearly describe you 
mathematical problem, i.e. what is input and what do you want to obtain 
in the end.

\start
Date: Thu, 22 Sep 2011 08:16:48 -0400
From: Tim Daly
To: Dmitry Semikin
Subject: Re: [axiom-developer] What do diagrams in bookvol10.3 mean?

On Thu, 2011-09-22 at 12:18 +0400, Dmitry Semikin wrote:
> Hi, axiom-developers,
> 
> 
> I'm new to axiom and just getting aquainted to it, trying to solve my
> problems using it, so please, forgive me, if I ask questions with
> obvious answers.
> 
> 
> The one thing, which confused me is what do diagrams in bookvol10.3
> (Domains reference) mean.

These diagrams are subgraphs of the whole "support lattice". 

Each domain requires a lot of other domains before it can be compiled.
If you create a lattice and place each domain in the lattice such that
everything it depends upon is below it you will find a "highest"
precondition domain. If you try to place Symbol in this lattice you 
will find that StringCategory is the "highest" required domain. 
This is a compile constraint, not an algebra constraint.

StringCategory is in layer 9 and will be compiled before anything in
layer 10 of the support graph. Symbol is in layer 10 because it 
depends upon StringCategory.

The complete support lattice is documented in the Makefile
(src/algebra/Makefile.pamphlet). 

There is a complication in the case of SYMBOL and some other domains.

If the support lattice was a pure lattice then we could compile the
algebra from scratch. Unfortunately, this is not the case. The algebra
forms a graph. At the bottom of the lattice is a clique of files that
all depend on each other. These files have to be compiled before any
other files. So SYMBOL has to be compiled before STRCAT. But we just
figured out that STRCAT has to be compiled before SYMBOL. This is
called the "bootstrap set".

In the past Axiom always needed a running Axiom to compile the algebra.
Since a running Axiom already contained the algebra, SYMBOL and STRCAT
already existed. This was never a problem when I worked at IBM since
I always had a running Axiom available.

When I got the Axiom sources I was not given permission to distribute
a running Axiom from NAG. That means that you could not build Axiom
entirely from the source code. Since the whole point of an open source
project is that anyone can build it from source I needed to figure out
a way to build the algebra from scratch.

One of the most difficult tasks was to discover the support lattice,
find the "bootstrap set", and set up a "precompile phase" which compiled
the algebra from the lisp sources rather than the spad sources. Note
that spad is really just syntactic sugar over common lisp so this is
always possible. It turns out that there are 85 algebra files in the
bootstrap set (see LAYER0BOOTSTRAP in src/algebra/Makefile.pamphlet).
SYMBOL is a member of the bootstrap set.

So the process is:
 (LAYER0BOOTSTRAP) compile these algebra files from lisp sources
 (LAYER0 - LAYERn) compile these algebra files from spad
 (LAYER0COPY) recompile these algebra files from spad
this happens because of the ORDER variable
(see ORDER= in src/algebra/Makefile.pamphlet)

Once this bootstrap problem was solved I could build the rest of the
algebra lattice.

> 
> 
> The first question is what is the legend? It seems to me, that green
> boxes are domains and blue ones are categories. But there are some
> other colors and shapes. What do they mean? Is some kind of legend
> given anywhere?

This is explained in the section "Adding new algebra" in 
src/algebra/Makefile.pamphlet

The color and the shape carry the same information.
  #4488FF == category (bookvol10.2) box
  #88FF44 == domain   (bookvol10.3) ellipse
  #FF4488 == package  (bookvol10.4) circle
  #444488 == numeric  (bookvol10.5)

I apologize for the horrid choice of colors (I am partially color
blind). You'll notice that they are just rotations of the hex codes.

In the books (10.2, 10.3, 10.4, 10.5) I have a chunk that enables
me to recreate the support lattice. The information for each 
domain includes the subgraph. The image is created from this
tiny specification and is a subgraph of the full graph.
(axiom-developer.org/axiom-website/bookvol10.2full.html)
(axiom-developer.org/axiom-website/bookvol10.2abb.html)
If you click on a node it will take you to the appropriate
book. I plan to make this link to the proper section of the
book but have not done that yet.

Actually, I do not draw the full graph. All of the full graph
information is documented in src/algebra/Makefile.pamphlet but
the actual graph is HUGE. You will see that most of the links
are comments. I have tried several different ways to make this
graph available. I wrote a few graphing tools to do tricks 
like force-based node expansion but I never published the results.

Ultimately I plan to make the graph have links to the domains
in the books. Those domains will have documentation of the theory
(some exist), the algebra (exists), the test cases (some exist), 
the help file (some exist), proofs (in plan but not published), etc.

All of this takes time and most of my time these days involve
treeshaking and documenting the interpreter and compiler. 

> The second question is what kind of relation is depicted on those
> diagrams? E.g. for the category Symbol we have diagram with arrow
> pointing to STRICAT (StringCategory) category. But if I look at the
> code bellow (in the same section of the bookvol10.3) or browse
> documentation of the Symbol in the HyperDoc, I cannot find any
> reference to StringCategory. So, what is the relation, depicted in the
> diagram in the bookvol 10.3? (Note: similar situation presents for
> other domains eiher).

The relationship in the support lattice is NOT the same as the
algebraic relationships. The support lattice documents the compile
time constraints.

I have a plan to document the algebraic support lattice but I have
not done it yet.

\start
Date: Thu, 22 Sep 2011 10:02:12 -0400
From: Tim Daly
To: Dmitry Semikin, Ralf Hemmecke
Subject: Re: [axiom-developer] What do diagrams in bookvol10.3 mean?

On Thu, 2011-09-22 at 14:33 +0400, Dmitry Semikin wrote:
> Ralf, thanks again.
> 
>         Actually, page 1 seems to suggest that the diagrams have
>         nothing to do with inheritance but rather with build
>         dependency (read the first paragraph).
> 
> 
> I see. I treated voluemes 10.2, 10.3, 10.4 as printed version of
> (extended) library reference. But I see, that actually, it is much
> more, that it includes either testcases and building process related
> information.

The algebra has been reorganized from hundreds of tiny files to a few
books. The 10.2, 10.3, 10.4, and 10.5 volumes contain the actual
algebra. Volume 10.1 will focus on explaining the algebra in a
more mathematical area approach (e.g. linear algebra) with uses and
explanations that are mathematical and have examples. There will
be hyperlinks to the appropriate Axiom domains in other volumes.

Needless to say, this takes time.

> 
> 
> Now I see, that actually for reference HyperDoc is much better option,
> than those volumes... But in my distribution for some reason HyperDoc
> do not show reference information on domains (I've posted it to this
> mailing list with other topic). I either did not find any HTML
> documentation, so I started to look into PDFs. But there are only
> AXIOM-book, which is good tutorial, but not reference. And those
> volumes...

I have rewritten and reorganized the hyperdoc information into html
form and I have created a set of web pages that communicate to a 
running Axiom. This forms a notebook front end that will contain the
same information as hyperdoc. The new Axiom HTML browser lives in
Volume 11 (books/bookvol11.pamphlet). The Axiom browser allows you
to interact with Axiom through web pages.

That effort was put on hold while I learned more Javascript and AJAX.

Unfortunately, HTML5 came along and I have learned better ways to write
the pages using Javascript, CSS, and the Canvas element so I will end 
up redesigning the HTML. In particular, the Canvas element allows me 
to draw Axiom's graphics directly in web pages so I am looking at 
replacing the X11 graph subsystem (Volume 8) with interactive graphics.

I have now learned how to write apps for the iPad and Android devices
and am looking at ways to support the new front end on these devices.
Of course, I need to make the Axiom browser work on all devices so 
there are some things I need to think about and design. Some of the
animations I have written do not work on all browsers.

Ultimately, this is converging on the Crystal design (Volume 12).

> Besides, in my opinion (it is only my opinion, but still it is opinion
> of newcomer) HyperDoc documentaion is structured in non-standard
> fasion, which makes it not so easy to use at the beginning. I mean the
> following thing: when I look at other programming languages usually
> standard documentation consists of the following parts: 
> 
> 
> 1. Syntax reference (which is formal description of keywords and
> syntactic costructs accepted by compiler or interpreter); 

Volume 0 contains this information although not with a formal grammar.

> 2. Standard library refererence, which lists and describes all
> packages, classes, functions (in case of axiom - Domains, Categories,
> Packages and operations). 

Volumes 10.x contain this information

> 3. Tutorial, which gives an overivew of standard facilities and pushes
> into the language.

Volume 0 and Volume 1 contain this information.

> 
> 
> The very important thing, which must present in the beginning of any
> tutorial (and overall documentaion) is how to get help for particular
> thing. In axiom there are many things involved, such
> as )summary, )help, )what, )hd, )describe, )show commands (by the way,
> not even all of them are listed by )summary command). 

Oops. Thanks for the bug report. Fixed in the next release.

More documentation is being added. Help files are being written for
many more domains. The new )describe command shows the description
section for a category, domain, or package. For example:

(1) -> )describe DHMATRIX
4x4 Matrices for coordinate transformations
This package contains functions to create 4x4 matrices useful for
rotating and transforming coordinate systems. These matrices are
useful for graphics and robotics. (Reference: Robot Manipulators
Richard Paul MIT Press 1981)

 A Denavit-Hartenberg Matrix is a 4x4 Matrix of the form:
      nx ox ax px
      ny oy ay py
      nz oz az pz
      0 0 0 1
 
 (n, o, and a are the direction cosines)


The ")d op foo" command now shows examples of how
to use functions from domains. For example, the pop! function:

(1) -> )d op pop!

There are 4 exposed functions called pop! :
   [1] ArrayStack D1 -> D1 from ArrayStack D1 if D1 has SETCAT
   [2] Dequeue D1 -> D1 from Dequeue D1 if D1 has SETCAT
   [3] D -> D1 from D if D has SKAGG D1 and D1 has TYPE
   [4] Stack D1 -> D1 from Stack D1 if D1 has SETCAT

Examples of pop! from ArrayStack

a:ArrayStack INT:= arrayStack [1,2,3,4,5] 
pop! a 
a


Examples of pop! from Dequeue

a:Dequeue INT:= dequeue [1,2,3,4,5] 
pop! a 
a


Examples of pop! from StackAggregate

a:Stack INT:= stack [1,2,3,4,5] 
pop! a 
a


Examples of pop! from Stack

a:Stack INT:= stack [1,2,3,4,5] 
pop! a 
a

(1) -> 

> HyperDoc system - it pops up on start, so it is ok. But it is
> structured in not so obvious way. Why AXIOM book is in Reference
> secion? And why Reference->Language do not contain description of
> creation of Domains, Packages and Categories? Where in reference
> compiler is described? Why Examples anre in Reference section? etc...
> All those things confuses for the first time significantly. Lack of
> formal syntax reference, collected in one place is either makes
> learning harder.

Hyperdoc was written in the 1980 prior to the idea of a browser or
the web. It was wildly far advanced for its time and still allows some
functionality you don't see in browsers. Most of the content was 
machine generated.

The Axiom book was written by the group under intense pressure to
have some kind of user documentation before we sold the system to NAG.
IBM intended to sell Axiom somehow but IBM sales required that all
documentation be written "to the eighth grade level" (age 12). They
had programs to check this constraint. Clearly Axiom was never going
to be an IBM product. 

At the time Hyperdoc was created we only had a few users worldwide
and almost all of them were using Axiom for research. They were also 
primary authors of the algebra so the "user documentation" was not
a priority. In fact, we often got algebra that we had to reverse
engineer because we had no documentation. People who program, and
in particular, people who program algebra, do not spend a lot of 
time and effort on the documentation. The best you tend to get are
"notes to self" kind of markup meaningful only to the author.

The open source version of Axiom has changed the focus and made
documentation be a primary goal. This is not shared by everyone 
and is one of the main reasons behind the forks of the project.

Literate programming is a great idea. The only hard part is the 
documentation.

Also at that time the syntax of the language was changing. There was
an effort to create a new compiler (A#, aka asharp) and there was a
great deal of debate about syntax and semantics. For a lot of reasons
I won't go into, the new compiler diverged from the Spad language.
This eventually was shipped as a separate compiler (Aldor) and has
since become moribund. Axiom has removed all support code for Aldor.

> 
> 
> Please, do not think, that I'm ungreatful man.

I'm quite happy to hear the feedback, complaints, and bug reports.

>  Actually, I understand, that great efforts was made to develop axiom
> system (and its help in particular). I think, that axiom is really
> wonderfull (it is the only CAS I know, which has strict typing and
> syntax similar to haskell... although I did not try Reduce). I like it
> very much and I only hope, that things, that I've told above will help
> make Axiom even better and easier for newcomers to adopt, so more
> people will start working with it.
> 
> 
> Sorry, all those things become off-topic, as initial post was about
> diagrams...
> 
> 
>                 By the way, are those diagrams generated
>                 automatically, or they are
>                 hand-made?

The information was collected by hand and is maintained with every new
change to the algebra. This isn't that big of an effort as adding new
algebra is a reasonably rare event and requires a lot of effort. We need
to know the information that the graph contains anyway so the graph is
really just a side-effect.

>         
>         
>         I'm not sure, but
>         https://github.com/daly/axiom/blob/master/books/ps/v103symbol.ps suggests that they are "pre-made" and stored in the version control system. Tim can probably tell you more truth here.

The "master" information is in src/algebra/Makefile.pamphlet

The information to create the subgraph in the books is kept with the
domain in the book. So Symbol (bookvol10.3.pamphlet) contains a chunk
<<SYMBOL.dotabb>> which is used to create the v103symbol.ps file using
the command "dot -Tps SYMBOL.dotabb >ps/v103symbol.ps"

Notice that the name "v103symbol.ps" means "volume 10.3 Symbol"

\start
Date: Thu, 22 Sep 2011 10:11:56 -0400
From: Tim Daly
To: Ralf Hemmecke, Dmitry Semikin
Subject: Re: [axiom-developer] What do diagrams in bookvol10.3 mean?

On Thu, 2011-09-22 at 13:05 +0200, Ralf Hemmecke wrote:
> > Besides, in my opinion (it is only my opinion, but still it is opinion
> > of newcomer) HyperDoc documentaion is structured in non-standard fasion,
> > which makes it not so easy to use at the beginning.
> 
> It's not just your opinion. But there is currently not enough manpower 
> to treat every aspect of this big system. And if you look at the 
> sources, you'll find that they are written in hypertex, which is close 
> to tex, but has some hyperlinking features. There is no browser version 

Actually, Axiom has a browser version (books/bookvol11.pamphlet)
It is being redesigned to use HTML5 rather than straight HTML.

> since someone would have to translate (or automatically convert) the 
> hypertex sources into html. Furthermore some of the sources, in 
> particular the API descriptions are written in the source code itself as 
> ++ comments. These are currently automatically extracted from the code 
> and made available to HyperDoc.

...[snip]...

> > (that's why I was wondering about diagrams, as I thought they could help
> > me to build hierarchies of Domains of categories - diagram given on the
> > axiom-developers.org <http://axiom-developers.org> is too big to be usable).
> 
> There are two quite usable diagrams in the original Axiom book by 
> Jenks&Sutor. I don't however know whether these (smaller) hierarchies 
> exist somewhere in the net.

The endpapers from the original book are in src/doc/endpaper.pamphlet
or on the web at http://axiom-developer.org/axiom-website/endpaper.pdf

\start
Date: Wed, 28 Sep 2011 23:48:42 -0500
From: Tim Daly
To: list
Subject: Axiom September 2011 release

Axiom's September 2011 release is available.

September 2011 Release

This release continues the task of treeshaking the compiler and
interpreter. Nine files were merged and removed. In addition,
several passes were made for code cleanup.

The Symbolic Ito Calculus package is being added, starting with the
BasicStochasticDifferential and  StochasticDifferential domains.
More work remains to be done.

The GUESS package is being upgraded. 

James Cloos and Wilfrid Kendall were added to the credits.

books/bookvol10.3 
  add BasicStochasticDifferential and  StochasticDifferential
  remove pairp
  start upgrade of GUESS package

books/bookvol10.4 
  remove packageTran

books/bookvol10.5 
  add StochasticDifferential

books/bookvol5 
  add BasicStochasticDifferential domain
  merge nocompil.lisp, as.lisp, nci.lisp
  treeshake interpreter
  remove pairp, ncParseAndInterpretString, packageTran
  use qc(ad)r forms

books/bookvol7 
  merge nocompil.lisp

books/bookvol7.1 
  update What's New Page

books/bookvol9
  remove pairp, isPackageFunction
  treeshake compiler
  use qc(ad)r forms

books/bookvolbib
   add Kendall Ken99a, Ken99b literature references to Axiom

books/ps/
  v103basicstochasticdifferential.ps added
  v103stochasticdifferential.ps added
  v71july2011.eps 
  v71releasenotes.eps add release notes

src/algebra/Makefile 
  BasicStochasticDifferential domain
  add StochasticDifferential
  remove upper GUESS package code

src/axiom-website/download.html add Gentoo notes by James Cloos
src/axiom-website/download.html add ubuntu

src/axiom-website/releasenotes.html

src/doc/axiom.sty 
  fix defplist

src/input/Makefile 
  document finite field bug 
  respect the BUILD=fast variable value

src/input/
  fix broken tests in axiom, cmds, setcmd, unittest1, unittest2
  ffieldbug.input: added

src/interp/Makefile 
  remove as.lisp, compiler.lisp, database.lisp, define.lisp, foam_l
  remove g-opt.lisp, nci.lisp, package.lisp, ax.lisp



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