[Axiom-developer] A modest proposal

[daly]

William,

> My parametric linear equation package IS documented: in a published
> paper in the Journal of Symbolic computation, and in the source code.
> It is not in a pamphlet style or what you call "literate with Knuth
> technology.

> You have spent time to convert my IBM script to LaTeX, in the hope
> I will expand it to a pamphlet. (and I haven't).

Yes, I spent approximately 3 weeks of evenings recasting your paper
into latex hoping to lower your "personal cost" of contributing it
and its ideas as documentation. Despite that effort you still objected.
That's fine. It is your choice to contribute or not. I didn't demand
that you do, I simply tried to make it straightforward. I've done
other "behind the scenes" work, including rewriting Barry's thesis,
which has yet to bear fruit (due to lack of time as Barry has quite
generously agreed to let his work be used in pamphlets).



> But have you tried to read the paper?  If you did not (and I believe
> you did not) then what good would a pamphlet do?

A pamphlet form would document the ideas for the future users of Axiom
in a form we can use. There are thousands of mathematics textbooks but
not many that explain the theory and the computational mathematics, in
context with a particular implementation and its choices. A pamphlet
is not just a copy of the paper. It should explain the "why" of the
code in the context of the theory. We need to know not just the theory
but how specific Axiom code implements it, what are its design
constraints, what are its limitations, etc.

I did read your paper, in detail, along with converting it. But my
primary focus at the time was making it into latex. The effort was
not for me but for people who might need to understand your code.

If my goal was to document your code rather than recast your paper I
would have spend considerably more time trying to understand the
mathematics. For instance, I documented dhmatrix by understanding how
they work. I helped Scott use them as the basis for the pictures in
the Jenks book. I just started documenting the quaternions (see the
new quat.spad). You'll recall I sent you some private links related to
the theory of exterior and geometric algebras that I found during the
course of understanding quaternions.  I'm still studying those papers
for the mathematics and hope to expand the quaternion and octonions
domains in a more general setting. Indeed, if I could find the time
there are some wonderful ideas that need to be reduced to working
code. We've had discussions about your new algebra work, which I
believe I do understand. But not to the level of being able to reduce
the ideas to code. You do and you can.

The point I'm trying to make is that I believe I could have understood
the beginnings of your algebra on differential polynomials from a pamphlet
you wrote using your paper. But my time was spent "on making the 
machinery work", which is needed rather than using my time to understand
the algebra to the point where I could document it (which would have
been a pleasant luxury). You're clearly much more qualified to explain
your own work.

That said, you have recently agreed to allow me to use the paper I
converted as the basis for a pamphlet form of your work. Since you 
disagree so strongly about making pamphlets perhaps we can compromise.
I'll make an effort to understand your algebra and an effort to write
a pamphlet form. All I ask is that you have the patience to review it,
explain what I don't understand, and correct the nonsense. Perhaps when
you've seen it done you'll be more convinced of the power of literate
programming.




> I respect your philosophy of literate programming, and I only ask you
> to repect that there are other ways to make code (and theory)
> understandable.

Of course there are other ways to make code understandable. But other
code, e.g. Microsoft Word, won't give the same answers in 100 years.
So there is a qualitative difference between computational mathematics
and any other code being written. 

Almost all commercial code dies. All of the projects I've worked on
have died "in the belly of the corporation". I believe that this fate
awaits Mathematica and Maple, a topic which we've discussed. It
certainly happened to Macsyma and would have happened to Scratchpad,
but for the very generous efforts of Mike Dewar and other people at
NAG. I've been trying hard to get Derive put into a "dead code safe",
hoping that TI will agree to release the code if they lose interest in
it.

But getting the code is not enough. I've talked to the developers of
Mathematica and Maple. The kernel code of those systems are very, very
poorly documented by the programmers estimates. Yet I've attended ISSAC
talks about the super-speed numerics at the heart of the system. I do
not know but I'd bet that the only existing documentation will be the
few pages of text from that paper. Due to publication constraints an
ISSAC paper cannot address any real details about the code, the choice
of data structures, or the relation of that code to the theory. That
would take a pamphlet file.

The point is that if Mathematica or Maple dies and if the failing
company would release the code it is unlikely that the code will be
brought back to life without the involvement of the original
developer(s). (Of course code is now considered "intellectual
property" (a non-legal concept but...) and is considered a real asset
of the company.  So if a company should go bankrupt they cannot "give
away" the code.  They need to sell it to recover the asset's value. I
was quoted a price of $250k dollars for the source code for Macsyma.
I don't have that kind of money.) Yet even in the unlikely
circumstance that they do give it away you'll have a million lines of
C code with clearly chosen variable names and no documentation.

Thus we are faced with a choice. Do we let systems simply die and then
invest the thousands of manyears of work to build new ones so the cycle
repeats? Or do we invest in the code and try to make it "live" in a
way that new users can learn about the concepts and their specific
implementation? If we do that it requires the effort of the original
developers to communicate with the future generations in specific detail.




> Is literate programming the panacea?

Would pamphlets help? We do not know for sure. But I firmly believe
they will and this project is an experiment on that thesis, among 
other goals.

So while there are many ways to write clear code (e.g. variable name
choices) and various ways of documenting (ISSAC papers, textbooks,
specification documents, Rational relation diagrams, ...) I believe
that Knuth "got it right". He produced high quality, nearly bug free
code with deep documentation. He placed his focus on writing for
people rather than writing for the machine. And his program, Tex, has
outlasted many other similar tools, even those backed by big money
like IBM script.



> As Donnie Brasco said in the namesake movie, let's "forget about it".

Drop the debate but not the fundamental goal. There really is a
guiding philosophy behind the choices that informs decisions about the
quality of a proposed direction.




All that said, I again apologize for being sarcastic. When the
fundamentals of the project are being questioned I need to be quite
clear when a debate misses the point. "Reducto ad sarcasm" is not a
proper way to debate and I'm sorry that I fell to that level.  I hold
you in high personal esteem and I regret that mistake. Mea culpa.

Tim