[Top][All Lists]
[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