Bill Page wrote:
From my point of view the objectives of using ALLPROSE are a
little different than the objectives satisfied by the Axiom
pamphlet files. As I understand it, one of the main points
is to be able to extract the comments embedded in the Aldor/SPAD
source code and typeset it along with other parts of the
documentation that are just LaTeX segments of the pamphlet
file.
Wrong. In ALLPROSE there are no places where you should write
+++ or ++ inside code chunks. If you do it, ALLPROSE doesn't
care, but such documentation is NEVER extracted by ALLPROSE.
That is a pity. It means that *somebody* has to edit 1,300
packages, domains and categories and manually extract all
that documentation. In order that it can become "proper"
documentation. :(
Come on, if you like I'll write a 10 lines perl script that translates
the +++ stuff into \begin{+++}..\end{+++} environments.
But there would be more to do. Take
+++ text
MyDomain: with {
0: %;
++ that is a zero
+++ This is a one.
1: %;
foo: () -> (); ++ and that is a foo.
} == add { ... }
In ALLPROSE that should have the format
\begin{+++}
text
\end{+++}
<<dom: MyDomain>>=
MyDomain: with {
<<exports: MyDomain>>
} == add {...}
@
\begin{+++}
that is a zero
\end{+++}
%
<<exports: MyDomain>>=
0: %;
@
\begin{+++}
This is a one.
\end{+++}
%
<<exports: MyDomain>>=
1: %;
@
\begin{+++}
and that is a foo.
\end{+++}
%
<<exports: MyDomain>>=
foo: () -> ();
@
(OK, I guess the Perl script is going to be a bit longer.)
Now if you believe that it becomes unreadable then you forgot that we
are actually writing in a literate programming style. All the empty
lines above should be filled with your ideas and explain why this or
that function is needed here or there, what your overall design is etc.
Wouldn't it be nice if ALLPROSE treated both occurrence
of ++ comments the same way?
NO. A strict NO. The reason is,
a) if I allow several ways for the user, he/she has to deal with several
ways to write the documentation. Such a flexibility steepens the
learning curve and complicates the code that has to deals with the
extraction of the documentation
b) documentation is documentation why would you want to write +++ in
front of each line if you can have it in a Latex environment? Code
chunks should be code chunks, why would you want documentation inside
it? Let's keep it simple.
c) If someone happens to write +++ comments inside code chunks ALLPROSE
simply considers them as code (they are in a code chunk), but if you go
all the way down, ie, compile the .spad.pamplet or .as.pamphlet file
into a library then extract the +++ comments from the .ao files in that
library, ALL the +++ comments are there. ALLPROSE simply doesn't use
them while it is compiling to dvi. If you go the long way
.nw -> .as -> .ao -> (extract +++ comments) .tex -> .dvi
then everything would be there, but the result is the API description only.
Of course this same information is already extracted by the
SPAD compiler and stored in the Axiom database. This database
is what is consulted by Hyperdoc and the )sh command etc. I
wonder whether a system like ALLPROSE should also have such
a database component?
Yep. Going the 'long way' is exactly that. But I have not yet written
the AldorDoc tool to do the "extract +++ comments".
Ralf
_______________________________________________
Axiom-developer mailing list
Axiom-developer@nongnu.org
http://lists.nongnu.org/mailman/listinfo/axiom-developer
