Re: [Axiom-developer] [axiom-developer] What do diagrams in bookvol10.3 mean?

[daly]

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"

Tim Daly