[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Axiom-developer] Using ALLPROSE for SPAD programming
From: |
Gernot Hueber |
Subject: |
Re: [Axiom-developer] Using ALLPROSE for SPAD programming |
Date: |
Tue, 22 Aug 2006 15:15:37 +0200 |
Hi Ralf,
On Tue, 2006-08-22 at 14:18 +0200, Ralf Hemmecke wrote:
> > First of all, I want to point out that I don't want to advocate against
> > ALLPROSE for documentation, which is in fact an interesting development
> > framework.
> > Nevertheless, my contribution do the documentation discussion is
> > non-ALLPROSE. Did you consider using an "javadoc" style for
> > documentation.
>
> Of course. You certainly know about the +++ comments. These things have
> been invented before Java came into existence. The only problem with
> Aldor is that there is not yet a proper tool to make use of this data.
>
> ALLPROSE hast \begin{+++} ... \end{+++} for that.
>
> > E.g. doxygen is a mature and flexible tool aimed primary
> > at C++ but extended to some more languages.
>
> Yep, doxygen is too much tailored for C/C++. If you make it work for
> Aldor, it might be worth another try.
>
> But as Tim suggests, that is not the point of literate programming. LP
> is here to express your ideas and illustrate these ideas by real (in
> contrast to pseudo) code. So you basically write a research article (or
> so). In that sense I fully support Tim and Knuth.
>
> But as you can see with my \begin{+++} ... \end{+++} environments, I
> also strongly believe that for using other peoples work it is often
> quite sufficient if you know about the API of what that library/program
> does on which you want to build. You do not usually want to read
> thousands of pages and books before you are able to write one single
> line of code.
>
> I, for example, would be quite happy if someone writes a library for
> factorization of multivariate polynomials in an LP style and
> additionally gives me a short API description of what his function does
> and how I have to call it. I am simply not interested in learning all
> the difficult stuff about an efficient implementation and about tricks
> in this implementation to make it even more efficient. I want to use
> factorization. If I ever become interested in the details, I can come
> back to that later.
I agree with you, most important is the API _together_ with a
description and examples, not the actual implementation. From my
experience far too often even the API is badly documented. In this case
a half of the story solution is much better than none at all.
>
> So my approach in ALLPROSE is to write in an LP style and *additionally*
> provide an API description for those who don't want to delve too deeply
> into the details.
>
> If you can make some tool available that supports such a combined
> approach, I would be quite happy to see them.
>
> But I would never sacrifice the LP approach to doxygen. Doxygen (to my
> taste--correct me if I'm wrong) is only about the API, ie half of the
> story -- if not less.
Yes, you are right, I am/was too much focused on the API.
Thanks for your comments.
Gernot
>
> Ralf
- [Axiom-developer] Another question, Alfredo Portes, 2006/08/18
- [Axiom-developer] RE: Another question, Bill Page, 2006/08/20
- Re: [Axiom-developer] RE: Another question, Martin Rubey, 2006/08/21
- RE: [Axiom-developer] RE: Another question, Bill Page, 2006/08/21
- Re: [Axiom-developer] Using ALLPROSE for SPAD programming, Martin Rubey, 2006/08/21
- RE: [Axiom-developer] Using ALLPROSE for SPAD programming, Page, Bill, 2006/08/21
- RE: [Axiom-developer] Using ALLPROSE for SPAD programming, Gernot Hueber, 2006/08/22
- Re: [Axiom-developer] Using ALLPROSE for SPAD programming, root, 2006/08/22
- Re: [Axiom-developer] Using ALLPROSE for SPAD programming, Gernot Hueber, 2006/08/22
- Re: [Axiom-developer] Using ALLPROSE for SPAD programming, Ralf Hemmecke, 2006/08/22
- Re: [Axiom-developer] Using ALLPROSE for SPAD programming,
Gernot Hueber <=
- Re: [Axiom-developer] Using ALLPROSE for SPAD programming, Ralf Hemmecke, 2006/08/22
- RE: [Axiom-developer] Using ALLPROSE for SPAD programming, Page, Bill, 2006/08/22
- Re: [Axiom-developer] Using ALLPROSE for SPAD programming, Ralf Hemmecke, 2006/08/22
- Re: [Axiom-developer] RE: Another question, Ralf Hemmecke, 2006/08/21
- RE: [Axiom-developer] RE: Another question, Page, Bill, 2006/08/21
- RE: [Axiom-developer] RE: Another question, Eitan Gurari, 2006/08/21
- RE: [Axiom-developer] RE: Another question, Page, Bill, 2006/08/21
- RE: [Axiom-developer] RE: Another question, Eitan Gurari, 2006/08/22
- RE: [Axiom-developer] RE: Another question, Page, Bill, 2006/08/22
- Re: [Axiom-developer] RE: Another question, Ralf Hemmecke, 2006/08/22