[Aldor-l] +++ Documentation structure

[Ralf Hemmecke]

Dear Martin, *,

> I think that it would be *VERY* sensible to see that Aldor and Axiom use the
> same documentation markup.

Yes, yes. I always keep this in mind. You know I am more in favour of 
having Aldor and Axiom converge. So don't think I want to do anything in 
any other direction. The community is still small anyway and it would be 
a waste of manpower to start different projects.

> Currently, Axiom uses LaTeX + NoWeb to produce documentation, and I must say
> that it works quite well, although it certainly could be improved.

Just wait a few more days. As I wrote in my mail, I am about to release 
a programming environment for aldor library programmers so that all the 
burden of writing Makefiles etc. is taken from the progammer.
This environment borrows from the Axiom spirit of writing literate programs.

I know this dhmatrix file. But I don't fully share the 'literate 
programming only' idea. For some people the API view of a program is 
quite sufficient. This API view is encoded into the ++ comments.

++ comments are compiled into the .ao files by the aldor compiler. The 
goal would be: Take some given set of .al libaries (the ones that 
contain .ao files), run a tool on them and obtain a hyperlinked API 
description.

I am fully supporting the literate programming style, but in my opinion 
one sometimes just wants to use a function and is not interested in the 
details of how it is implemented so an interface description would be 
just enough.

With my last mail I was thinking about a good markup that would finally 
be use in a literate program and for the ++ comments (where the latter 
are in my case generated on the fly from the literate program).

Ralf