Ralf, On Tuesday, August 22, 2006 11:08 AM you wrote: > Bill Page wrote: > > To deal with pile syntax maybe we could make use of the > > SPAD to Aldor translation option built into Axiom that > > you mentioned in another thread? Even if it is not perfect, > > perhaps it is good enough to enable ALLPROSE to more easily > > extract the necessary information? > > Don't leave me in the dark. Specify exactly what you want to > do/achieve otherwise I cannot follow.
??? On Sunday, August 20, 2006 6:55 PM Martin Rubey wrote: > ... > Note that a (rudimentary) converter from pile to nopile is > included in the axiom compiler. just say > > (1) -> )co test.spad )tr > Compiling AXIOM source code from file test.spad using old > system compiler. > Warning: translation of an old-style source code ".spad" > file to a new-style ".as" file changes the old system > compiler. > If you wish to use the old system compiler for regular > compilation, you must exit and re-enter AXIOM. > Creating output file with name test.as . > #include "axiom.as" > Compiling AXIOM source code from file test.spad using old > system compiler. > TEST abbreviates package Test > compiling exported tst : Integer -> Integer > --)abbrev package TEST Test > No documentation for tst > No documentation for tst > > +++ > Test(): with tst: Integer -> Integer; == { > add { > import from PositiveInteger; > import from SingleInteger; > import from String; > import from OutputForm; > import from NoValueMode; > tst(n:Integer):Integer == { > for (free i) in 1..n repeat { > i = 2 => 0; > output(i::OutputForm)$OutputPackage; > } > 0; > } > > } > } > > Note that it makes many mistakes, but that's probably fixable. > > ... > 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. :( Wouldn't it be nice if ALLPROSE treated both occurrence of ++ comments the same way? 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? > Instead you write the documentation into a \begin{+++} ... > \end{+++} environment. And all that appears in the Latex part > of the noweb file. Of course, inside that environment you use > latex as usual, but you should not just write arbitrary latex, > you should follow some style. Agreed. I think you might find it very interesting to study how this was handled in the Sage project. A very large amount of program-level documentation is coded as a LaTeX document in the docstring of each Python module. This text is extracted and processed by LaTeX to create the 1000+ page reference manual and also available for online help in the interpreter. It is not literate programming in the style of Knuth, but is a **lot** better than what we have sprinkled throughout Axiom's SPAD code. And this is a project that is only two years old... > ... > > And also to create appropriate hyperlinks to this stuff. > > Is that right? In that case, in the end will it be at least > > a partial replacement for the hyperdoc browser? > > Right. That part of ALLPROSE aims at replacing hyperdoc. But > as I said before, I would rather like to take a set of libraries, > extract all the +++ comments and then produce a hyperlinked > document (website or such) as an API description just from the > libraries. No .as source code should be needed. Again I wonder about the need for a database. The web pages on the Axiom Wiki for example are stored in the Zope Database. This allows pages to carry additional attributes such as the list of "parents" that define the subtopic lattice, last editor, dates, etc. This information is being searched dynamically to create the left sidebar navigation for the wiki. A similar thing could be code for navigating between pages containing literate source code. But this does require a web site interface and does not translate easily to a printed format. > > > I think we need to talk more about how this would work both > > in a stand alone desktop environment and on the Axiom Wiki. > > The stand alone way, I just describe above. The Wiki way is > maybe as simple as extracting the +++ environments and the > corresponding code chunk and putting it together. In principle there is no reason why the Axiom Wiki could not directly consult the Axiom database (daase files) the way hyperdoc does now. > But note, in order to get links from one piece of code to > another you have to noweave all the files together (for > getting links inside the codechunks) and latex them all > together for latex taking care of the hyperlinks across > different files. Maybe the latter could also done separately > but sharing .aux files, but that is beyond my abilities. Sometimes I wonder just how appropriate LaTeX-oriented tools are for this task... Regards, Bill Page. _______________________________________________ Axiom-developer mailing list Axiom-developer@nongnu.org http://lists.nongnu.org/mailman/listinfo/axiom-developer