[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Axiom-developer] documenation standards

From: daly
Subject: [Axiom-developer] documenation standards
Date: Thu, 25 Dec 2014 00:40:43 -0600


I only have an official position on Axiom. 

> The basic issue that I see is that PanAxiom is really a
> software engineering project before it can continue to live.

Making Axiom "live" is the WHOLE point of the Literate Programming effort.

Currently you need have a deep knowledge of computation, mathematics,
Spad, and Lisp to use Axiom efficiently. Axiom needs to communicate
ideas behind those implementations at all levels so that it can be
maintained and modified.

If you just want a copy of the system for your own use then there
is no reason to bother with natural language. When you stop then
your work dies. Exactly zero people care.

> A significant part its development was thoroughly documenting
> what it did and how it did it.

And "WHY" it was done. Even with my own code, after 20 years,
I know WHAT I did and HOW I did it. I can even tell you what
bytes the compiler will lay down in memory.... I just don't
remember "WHY", only that if I remove it the system breaks.

Axiom isn't trying to "document", it is trying to COMMUNICATE ideas
from human to human. This is NOT a subtle difference. When you read
a physics textbook the natural language paragraphs explain the ideas,
not the equations. Imagine how useless a physics textbook would be
if all you had was a book of equations.

Source code is equations. Axiom is trying to write the text
surrounding the equations.

The literate programming focus is for the next generation, people we
will never meet who want to maintain, modify, and extend the system.
People die (Jenks, Bronstein, Sundarasan), which makes it hard to 
get answers. 

Writing new source code without a full explanation just makes the
same fundamental mistake the Axiom team made in the last century.
In our defense, we were doing research, not product development.

Now we have the benefit of hindsight and the prospect of a future.
New "source code equations" need to have the paragraphs that
communicate the ideas.

Writing the ideas is tedious but it is MUCH harder to reverse engineer
the ideas from the equations, if it can be done at all. A lot of the
details in Spad code exist nowhere in the literature. Theory papers
rarely explain how to cons up an s-expression and funcall it to
dynamically compute the result.

Axiom is trying to set professional quality standards for computational 
mathematics software based on COMMUNICATION with future computational 
mathematicians, developers, and users.

The "gold standard" form of Axiom can be found in the book
"Physically Based Rendering" by Pharr and Humphries. When Axiom
looks like that we will have achieved a minimum professional
standard for Axiom as computational mathematics.

> Even minimal documentation efforts may either hard to start or
> will be too much bother with to add or maintain. Besides who needs it?

Axiom has about 1.2 million lines of code. It has taken years, so far,
just to organize, hyperlink, index, and automate. The "minimal
documentation effort" has been massive but progress is being made.
There are still 200,000 lines of code to rewrite and merge which
will consume most of next year, at minimum.

Nobody currently needs documentation. But documentation is part
of being a software professional. Quality software is easy to
understand, easy to use, and has "to the point" documentation.

Axiom is expanding the available documentation. There are more
)help files, there are now code examples shown with )d op responses,
there are full hypertext index lookups in each book, there are input 
files in specific areas (e.g. Hamiltonian Biquaternions, the Cohen 
algebra with references to the book, database query language 
example, etc.), with more to come.

There is a book outlining related theory that is being organized
with hyperlinks to the related algebra. There are SVG graphs with
hyperlinks to the algebra. There are hyperlinks within the algebra
to other categories, domains, or packages used. There is a website
with historical papers that will eventually be hyperlinked from
the current bibliography book.

There is a computer algebra test suite based on published books
that show Axiom being used and tested by outside literature.

So there is a "documentation" effort as well as a literate
programming effort. 

> "I didn't know I needed to know archeology."

Charybdis is the equation output formatting program from the
1960s. The zipper parser for algebra input is a research effort from
the 70s. The type system is inspired by Sammet's Modula and other
early ideas. What was cutting edge research 50 years ago is now
archeology. What is cutting edge research now will be archeology in 50
years, assuming the work is written up and published.

> The literate approach that Knuth created has no answer to
> mass of existing code problem: that is, he didn't think out
> a mechanism for the curious to dynamically add insights to
> the system's code even if literate.  Inverses are sooo.. hard.

Last month I attended a Knuth talk. I asked him about literate
programming. He said that he believed he could not have written
the MMIX simulator without it because it was too complex for him.
He considers literate programming to be one of his most important ideas.

Knuth has the luxury of writing literate programs from scratch. We
have the horror of understanding "source code equations", reverse
engineering the ideas, and the communicating that understanding in
natural language.

I believe literate programming is the only tool that can make software
live, especially complex software like Axiom.

If Axiom is going to live, it must be done... 
I want Axiom to live. Therefore...


reply via email to

[Prev in Thread] Current Thread [Next in Thread]