Re: [Axiom-developer] Re: literate programming pamphlet files forMathAction

[William Sit]

Hi:

This is not a response to any particular message in this thread, but I think
some information is useful about the use of old spad source, in particular, the
++ --comments that have produced a lot of thoughtful commentaries. I am not a
system programmer and so I know almost nothing about *how* this is done, just
what was the use of ++ and some -- lines.

It is a pity that the current Open Axiom does not yet have hyperdoc, which is a
great replacement for )show, and a vast multifacet browser way ahead of its time
(or even by today's standard). I understand that those who only have the Open
Axiom version will not have experience with hyperdoc. However, there is a
chapter (Chapter 14) in the Axiom Book that is downloadable that describes
hyperdoc and certainly in lot more details than I am writing about. Those who
know hyperdoc need read no further.

Using hyperdoc, you can (I mention only those related to documentation):

(0)  read the entire Axiom Book, with several views -- by topics, language,
examples, commands, search -- kind of a precursor to Tim's crystal: under
[reference] of hyperdoc.

(1)  get what is equivalent to )show or )display for any constructor, operation,
or attributes; just type the name into a box. But hyperdoc does a lot more. This
is the [browse] function of hyperdoc. These pages, unlike ")show" the output, is
formatted to fit separately in the hyperdoc window, with a scroll bar, and is
out of way of any Axiom computation you are doing. They are derived from spad
source and in particular, the ++ lines.  Once the name is entered (and you can
fill in actual parameters for constructors after that or leave them as
undefined), you get not only the documentation, but you can see ancestors,
dependents, exports, parents, operations, examples, users, attributes and more.
For operations, you get a list of all operations of a certain domain, and you
can get descriptions, parameters, signatures, origins or filter the list. You
can also get hyperlinks to the source spad file for any of the items. If you
have your own version of a spad file and have compiled it, your version is
immediately available.

(2)  test solve problems in five topics: calculus, matrix, draw, series, solve
-- much like a live web page; each topic provides further menus to do a
particular computation. On each page, there are default examples, so you can
just click [continue], or you can fill in the parameters. Surely, this is only a
very, very, small fraction of the library (and can be extended), because the
intention is introduction to Axiom, under [Basic Commands] of hyperdoc. Under
the [Topics] menu, more advanced mathematical topics are available, including
basic commands for them.

(3)  (if the author of the spad source provided examples for the Axiom Book)
select  live examples from [Examples] menu and choose the domain. For example,
if you choose the domain OrderlyDifferentialPolynomial (Section 9.60 of Axiom
Book), you get a demonstration of ODPOL(FRAC INT). When any of the Axiom
statements is selected (click a downarrow icon next to it) the result is
displayed (even if you did not select the ones above it on which it depends).
But there is more. If you double click on the statement instead, a new Axiom
frame (interpreter window) opens and the statement, and all others on which it
depends, are executed in real time, and you can insert Axiom statements of your
own, to test your understanding of the examples. This frame is totally
independent of any other frame(s) that might be opened -- that is, all its
variables are scoped only for that frame, by perhaps a child process. You can
check the dpolcat.spad to see what is done: look for the -- Examples: lines and
what follows. (Yes, the -- lines, which are used and it's so easy!)

    I believe Bob Sutor designed (or patched in) this syntax when he wrote the
Book so he could simply extract these and put them into both hyperdoc and the
Axiom Book. It's too bad that not all spad source provided these examples (what
Tim may have called "testcase"). I don't know if the full code for hyperdoc is
available as open-source, but if so, the grammar of documentation in spad files
can be extracted, and it would be a big waste to throw it away and not built
upon it.

So I would suggest that reviving hyperdoc should be one of the highest
priorities and after that, add examples and better commentaries to the spad
source. The final design of pamphlet files (at least the code segment portions)
can then be built upon the experience with hyperdoc from more people. Hyperdoc
can then be expanded (more topics are included in basic commands), improved (for
example, display the mathematics contained in the pamphlet/LaTeX source), or
morphed into a browser plug-in, or even a web-based version like that in
MathAction.

William







-- 
William Sit
Department of Mathematics.........Email: address@hidden
City College of New York.....................Tel: 212-650-5179
Convent Ave at West 138th Street.............Fax: 212-862-0004
New York, NY 10031.......Axiom, A Scientific Computation Sytem
USA.....................http://www.nongnu.org/axiom/index.html