axiom-developer
[Top][All Lists]
Advanced

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

[Axiom-developer] )set output mathml on


From: daly
Subject: [Axiom-developer] )set output mathml on
Date: Sat, 10 Feb 2007 21:37:43 -0600

> I wanted to get my mathml package delivering output....

Excellent. This seems to be a simple enough change that we could
pick it up quite quickly. There is a browser plugin by Sam Dooley,
a previous Axiom author, that handles MathML. I can't remember the
name though.

In order to pick up this work into the mainstream axiom it still
lacks a few pieces:

1) DOCUMENTATION. besides modifying the pamphlet files it would
   be useful if you could write down any understanding you gained
   about how the current code works and why you needed to change
   what you did. It's the 'WHY' that is most important to future
   people trying to follow your changes. Assume some other person
   is trying to understand and change your code 30 years later.
   Plus, if you made the effort to understand how Axiom works in
   some small piece, it is worth capturing that understanding so
   others can build on it. For instance, why does TEX1 appear 
   useless? What did you depend on that moved your code up the
   layer chain? Is there a 1-to-1 correspondence between MathML
   constructs and Axiom-Tex constructs? Does your code cover all
   the cases?



2) MORE DOCUMENTATION. I, and many others, do not know the details
   of MathML. Perhaps finding/referencing/writing some overview as
   well as adding bibliographic references would be useful. Look at
   dhmatrix.spad.pamphlet for an example of possible documentation.
   A discussion of the possible forms of equation output in Axiom
   and their generation by your code would make the whole change
   much easier to maintain and modify once they come out the MATHML 2.0



3) TESTS. MathML works for your example. But a reasonable test suite
   is needed to check the range of coverage and to make sure it doesn't
   get broken in the future. One of two approaches seem reasonable to
   me, although any reasonable test strategy is fine. You could either
   collect a large number of axiom input syntax expressions into a
   single file and run your code against this set, thus testing the
   robustness on "random" input you didn't create. You could also give
   some thought to a "coverage" test suite to show that you handle
   things like summation symbols, equation numbering, various bracing
   styles, tables, as well as the usual things like exponentiation, etc.

   This kind of testing really won't cover the "format" issues for 
   output and I'm not sure how we could do that. But it will test for
   code-breakage on random and constructed input. Axiom users can
   create their own output formats for their domains which is not
   constrained to follow "standard math".

   Please add your test files to the src/input/Makefile.



4) PATCH FILES. Run

     diff -Naur axiomfile.pamphlet yourfile.pamphlet >axiomfile.pamphlet.patch

   so we can see exactly what changed in each file. The "-Naur" option is
   the standard way to create axiom patch files.

This is really the only way to "get it off your desk" and into the
distribution. I try to pick up changes I understand "in the small"
which I can test but more glorious changes really require your effort.
Packaging changes to "get it off your desk" is three times more work.
I'd like to be able to pick things up that seem "simple" but since I'm
not the author I have no real ability to debug it when the merge breaks.
  
Tim





reply via email to

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