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

[Ralf HEMMECKE]

Hello Tim,

Tim Daly wrote:
> re: Why should ++ comments go away?

> Pamphlet files let you use the full power of tex, including hyperlinking
> packages and, now noweb and a browser. Thus we gain 4 benefits. 
>  (a) the world understands tex so no documentation of the tags is needed, 

OK.

>  (b) the mechanism is entirely general so anyone can make their own tags, 

Not always so good. Assume I want to refer in the documentation to the 
name of a function or a variable from some code junk. To me it is 
unclear how I should typeset this. I could use $function()$ or 
$variable$. Or should I use \verb'function()' or perhaps 
\spad{function()} or \axiom{function} or is it better to say 
\alfun{function}? Having a set of canonically predefined tags (latex 
commands) would leave the actual output style to some stylefile. 
Furthermore latex+hyperref (or whatever program) could produce 
hyperlinks if there where predefined tags. But there aren't. (I consider 
\spad and \axiom to be undocumented and therefore not very useful.)

>  (c) less code needs to be maintained, and 
>  (d) it all works with general purpose tools (mathaction, browser, etc).

Well, but I feel the hyperlinking from the program to the documentation 
is gone.

> (With some cleverness we COULD define a function that could allow a 
> program to reference its own pamphlet at runtime. This might be useful)

Yes, maybe this is the way to go.

> Pamphlet files change the emphasis from programming to writing a document.

That is great, but what if you want to write a new domain A which builds 
on some other (already nicely documented) domain B. You have to know 
every function signature that you intend to use from B by heart or to 
read the whole documentation of B again and again to find the right 
place where an appropriate function is defined. I consider this a 
lengthy process. Better would be to have a summary of the domain 
additionally available (of course automatically generated). Well and for 
that I would use ++ or \begin{functiondescription} ... \end{...}.

It is nowhere said that ++ can only contain a limited set of latex 
commands. It depends very much on the program that takes these comments 
and renders some useful format out of them.

> Fourth, you mention that sometimes a programmer just wants the documentation
> of the arguments. There is no reason why we need special syntax for this
> and, as mentioned above, the previous programmers did not provide this.
> The Axiom compiler does extract this type information while compiling. See
> )show Integer
> for an example of the output.

Yes, > I know it all seems like a lot of work but we are at the beginning of
> the collision of computing with science. If we go back to the last
> century and look at math proofs from that time they seem like just so
> much handwaving compared to the standards of proofs today. In 30 years
> lightly commented source code with ++ and -- will seem unprofessional.
> Algorithms will be expected to have termination proofs, correctness
> proofs, examples, test cases, complexity analysis, working source code
> and a sound basis in theory in order to pass as professional
> scientific work.
>
> All of which is clearly just my opinion on the subject.  But at least
> this will give you some idea why I believe ++ comments will die.
>
> Tim
I get a list of signatures. And how do I interpret this list? I have to 
guess from the function's name what it does.

I say it again. I am not opposing the pamphlet style, but I would like 
to keep ++ as an _additional_ feature.

> Pamphlet files allow tagging of arguments in such a way that we could
> construct automatic hyperlinks for arguments.

Is there an example somewhere?

I dont like the list of hyperlinks below the green area of

http://page.axiom-developer.org/zope/mathaction/Dhmatrix/

very much. In the green area it goes...

R : Join(Field,  TranscendentalFunctionCategory)

Now suppose, I don't know what TranscendentalFunctionCategory is. I 
cannot simply click on it, but must search the appropriate link at the 
bottom. It's a bit inconvenient, but maybe only a question of the right 
program that puts hyperlinks inside the code part. (As far as I know 
actually noweb could do this partly.)

> Fifth, you said "This is NOT true for the Aldor compiler". Currently the
> Aldor compiler will process ++ comments and pass them along... to nothing.

Sad, but true. And AldorDoc (which should do this job) is not much 
progressing at the moment.

> Sixth, you reference the javadoc-like documentation style
> (http://www-sop.inria.fr/cafe/Manuel.Bronstein/libaldor/html/node18.html)

> Pamphlet files can contain this information and it can be parsed out
> either with noweb, tex, l2h, etc. However, I'd expect that the original
> pages in the pamphlet .dvi file can not only contain this information but
> format it in a similar way if you so desire with additional information.

The point is that I don't want to repeat the function signature in the 
documentation. They should be taken from the actual code. I would only 
like to add a short note on the function. Repetition introduces the 
possibility of getting out of sync when changing code or documentation.

> As for hierarchical information the src/algebra/Makefile.pamphlet contains
> the current lattice of types. This information is waiting for someone to
> exploit it.

I know Axiom is a bit different, but for Aldor I would rather just like 
to extract the type lattice from the .al libraries by translating the 
files to the .asy format.

Ralf