axiom-developer
[Top][All Lists]

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

 From: Ralf HEMMECKE Subject: [Axiom-developer] Re: literate programming pamphlet files for MathAction Date: Fri, 01 Oct 2004 23:50:43 +0200 User-agent: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.7) Gecko/20040616

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


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