[Axiom-developer] Re: A modest proposal

[William Sit]

address@hidden wrote:

You state:
> So, yes, my Axiom code should be better documented, but not in a pamphlet.

Which raises two questions. First, why are you trying to associate yourself
with a project which has the goal of putting everything in a pamphlet?
Second, you're not doing documentation anyway so why is this an issue?

For the first, see below. For the second, no, it is not an issue for me.
It is one for YOU.

[sniped]

> If you want to work on this project please respect
> the fundamental goals.

> That's not an unreasonable request.
No, that is not unreasonable. I have been respecting this fundamental goal
of literate programming even though I disagree (that is the reason I have
kept quiet on the issue until recently "provoked" by your sarcastic personal
criticisms -- by the way, have I ever personally criticized your work or
even ideas before now?). Respect does not mean agreement. I associate with
the Axiom project because there are other goals besides literate programming,
say to spread the original ideas of Axiom and enlarge user base.

It is not true that:

> William Sit came to visit at IBM Research, wrote some code, documented nothing and left.

When Bob Sutor developed hyperdoc and wrote the Axiom book, I documented according to his hyperdoc requirements the packages on differential polynomial rings (I recall he explicitly said there was not enough room to have similar documentation for other packages I wrote). There are tests you can run (in Examples of the spad source) as regression tests that you can even try if hyperdoc is running as designed. But hyperdoc has not been working. Without hyperdoc working, Axiom (the algebra code) is very difficult to use. I participated in MathAction mostly to help myself and others understand Axiom's sometimes seemingly absurd outputs. Hyperdoc is not available in its full form. Hyperdoc is a way of documentation, as designed by the original Axiom team. It still is way ahead of current browser technologies in many ways. (I have articulated on this, see the archives).

If "contributing to literate programming in the style of Knuth" is a prerequisite for participation, then you are correct that I should not hang around any more. But you are wrong. Even though you started the revival of Axiom and make literate programming a primary goal, there are many more aspects that users want. Not every user of Axiom is a developer. Not every user wants to understand the theory behind a particular algorithm. Not every user cares how Axiom is built. Every user wants Axiom to "just work" on their platform of choice. That should be another primary goal of your project. "just work" is not simply "just build" or "just compute" (both essential, but not comprehensive).

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 source to LaTeX, in the hope I will expand it to a pamphlet. (and I haven't). But have you tried to read and understand the paper? If you did not (and I believe you did not) then what good would a pamphlet do? If you did, and have difficulty following the mathematics, would putting the same mathematics in a pamphlet help? and did you ever ask? I'll be very glad to explain or give talks on the subject. Where do you think the paper needs improvement? Do you think by literate programming the paper and code, you can just lie down on your bed and read and understand them without effort? Is literate programming the panacea?

I respect your philosophy of literate programming, and I only ask you to  respect that there are other ways to make code (and theory) understandable. You don't have to agree.

I do not intend to convince you or others of my way of working (or unconvince others of literate programming). I don't try to win in philosophy fights, only in logical and mathematical discussions. I have no need to create a SitAxiom branch because I have no agenda. I am a user of Axiom. I'll use it when it suits my purpose and works. I'll use other CAS if other CAS suits my purpose and works. I know my limits and I won't be able to contribute to build-development work. I'll contribute to algebra code when I start writing Axiom code again. Meanwhile, I am still learning about the subtleties of Axiom (algebra code).

Once again, I am not out to convince anyone of anything philosophical. Please continue and carry on with your good work.

My apologies for bringing this to the forum. It was not my intention. As Donnie Brasco said in the namesake movie, let's "forget about it".

William