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

[Ralf HEMMECKE]

Hi Martin,

It is not exactly clear what you want, but if it is just for the purpose 
of editing .pamphlet files, there is already some support for Aldor code 
edited in Emacs. See aldor.org or http://www.hemmecke.de/aldor.

However, I don't like the #pile mode of Aldor/Axiom very much. This 
might cause some problems with syntax highlighting.

My mode even seems to work in connection with the Emacs noweb-mode, so 
it should even highlight code within pamphlet files. You should put 
something like this

%EMACS Local Variables:
%EMACS mode: noweb
%EMACS noweb-code-mode: aldor-mode
%EMACS End:

At the end of each pamphlet file or use other methods to convince Emacs 
to load the right mode if it displays a .pamphlet file.


Jinlong Cai <address@hidden> wrote another aldor-mode which is certainly 
more advanced than mine, since it incorporates support for the Aldor 
debugger. However, I haven't seen his mode openly available.



There are some attempts to extract the ++ and +++ documentation from 
Aldor .asy files and transform them finally to html. This goes under the 
name AldorDoc, but is not very much advance yet. Unfortunately, Yannis 
Chicha has no time to make progress with AldorDoc.

But appart from syntax highlighting there is another question which is 
still to be discussed. "What kind of structure should ++ comments have?"
Note that if these documentation comments are processed automatically, 
there should be some tags so that the documentation compiler knows where 
to link some names to or how to typeset certain pieces of the 
documentation. Personally, I would very much like to get the 
functionality of JavaDoc, but unfortunately ++ comments might become 
unreadable in the .pamphlet file (which is undesirable).
But here people of Axiom and Aldor should work together so that they 
come up with ONE nice suggestion and program that produces a online 
version of the category hierarchy similar to JavaDoc or AlDoc (see
http://www-sop.inria.fr/cafe/Manuel.Bronstein/libaldor/html)

Aldoc (http://www-sop.inria.fr/safir/WHOSWHO/Manuel.Bronstein/) (in 
contrast to AldorDoc) unfortunately does NOT use the ++ comments but 
uses LaTeX code embedded in the .as files.


Ralf

Martin Rubey wrote:
> Yet another suggestion:
>
> In Axiom (and Aldor) code, there are two types of comments: -- and ++.
>
> The first tells the compiler to throw the comment away, the latter to keep
> it. It seems that there are programs that can use these "descriptions", I
> suppose Hyperdoc is one. More precisely: +++ tells the compiler that the
> comment concerns the next name, ++ concerns the preceding name.
>
> I thus suggest a tiny bit of syntax highlighting: It would be great if the
> ++(+) comments would be printed a *little* differnent than the rest of the
> code, maybe in italic or a different color. (Since the often contain code, they
> need to be printed in the same font as code.)
>
> The -- comments often contain old code, so maybe a "lighter" face would be
> appropriate. Those -- comments that explain the code will vanish and merge into
> the pamphlet style documentation, I suspect.
>
> Martin