Re: [Axiom-developer] Re: literate programming pamphlet files for MathAction

[root]

> >  > In ++ comments one might wish to include some mathematical formulae. 
> >  > Writing them in MathML makes the ++ comments unreadable. Many 
> >  > mathematicians can read LaTeX these days, so I would prefer LaTeX here.
> > 
> > Why on earth would you write them in MathML?
> 
> What would you suggest?
> 
> I am very much open to everything, even LaTeX, but there should be some 
> standard of how to document with ++ and this is missing currently!

I'm interested in this thread (though buried under a huge project in work
at the moment). The ++ and -- comments were part of the original 
documentation mechanism. In the long term these will go away. The 
code generated for the compiler won't contain documentation (since the
compiler doesn't care). There will be new environments in the pamphlet
file which will be standardized and automatically extracted. Standard
environments include \begin{testcase} for integrating .input file tests,
\begin{concept} for tagging the introduction of a new concept that needs
to be pushed into a semantic network (see the crystal discussion in the
history), etc. These stylized environments will, like \begin{list}, 
probably have special sub-tags (like \testinput and \testresult so 
testcases can automatically verify the results).

++ and -- suffer from the usual problem of documentation. programmers
will not maintain documentation tags. mostly because almost nobody
but the programmer ever reads code. we tried to be clever about it
and make the comments "live" with hyperdoc (a pre-javadoc idea). 
unfortunately it still suffers from the fact that embedded comments
are not the primary reason for a .spad file. I'm hoping that the
pamphlet file (which makes the documentation task primary and coding
secondary) will encourage computational mathematicians to actually
write papers that include working code and programmers to write real
papers that explain their algorithms. 

t