[Aldor-l] +++ Documentation structure

[Martin Rubey]

Dear Ralf, *,

I think that it would be *VERY* sensible to see that Aldor and Axiom use the
same documentation markup.

Currently, Axiom uses LaTeX + NoWeb to produce documentation, and I must say
that it works quite well, although it certainly could be improved.

However, the philosophy is a little bit different, it rather follows
possibility (1) below and the outcome might be comparable to the way the LaTeX
project documents its code: compiling the ("literate") source code produces the
.spad file (= source code for axiom's compiler) and a .dvi (or .pdf) file,
which contains the documentation and, additionally all of the code in verbatim
format. In future it will probably also a third file containing test cases and
maybe a file containing usage information only.

In general it is not the case that the code appears in the documentation in the
same sequence as it does in the .spad file, rather, more important or difficult
parts of the code will be separately discussed, less interesting code will
appear only at the end of the documentation.

Maybe an example explains all this a lot better. Look at 

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

Bits of code start to appear at the end of section "Translation
Transformation".

Again, I think it could well be improved, but for a start it's working quite
well. 

A question: the use of ++ before documentation is only of syntactical nature,
it seems to me. The approach used for axiom is the opposite: chunks of code are
marked as 

<<translate>>=
    translate(x,y,z) ==
     matrix(_
      [[1,0,0,x],_
       [0,1,0,y],_
       [0,0,1,z],_
       [0,0,0,1]])
@

in the source code of the documentation, and are processed as verbatim
environments, all the rest is directly processed by LaTeX. 

<<translate>> gives the code that follows a name, which is necessary to be able
to put it back together at the end again: if a markup like <<translate>>
appears in a chunk of code later-on, the above code will be substituted for it.

Martin

Ralf Hemmecke writes:
 > Hello all
 > 
 > With this mail I want to address the documentation of ++ comments in
 > Aldor and everyone is invited to add his/her view or any remarks to
 > the following.
 > 
 > The goal is to come up with a Aldor Documentation Guide that specifies 
 > the conventions/norm used for the ++ comments.
 > 
 > 
 > Currently, there are two ways to document Aldor sources.
 > 
 > 1) Write the documentation in #if ALDOC ... #endif blocks where the
 > contents follows the rule set by the aldoc.cls LaTeX class file.
 > 
 > 2) Write inside ++ comments and use AldorDoc later.
 > 
 > 
 > 
 > Both approches have advantages and disadvantages.
 > 
 > 
 > Aldoc approach:
 > 
 > 1+) Writing in LaTeX without bothering about putting ++ at the
 > beginning of every line certainly eases the writing process and gives
 > the full power of LaTeX for the documentation.
 > 
 > 1-) The source becomes almost impossible to read when the
 > documentation is put in between the code lines. There is no good tool
 > that helps to make the code and documentation more readable by
 > highligthing the parts.
 > 
 > 1-) There is redundant information. Signatures have to be written in
 > the documentation and may not always agree with the corresponding code
 > they document. So this way of documenting Aldor sources is error prone.
 > 
 > 1-) The code is not seen by the compiler. Thus the .al library does
 > not anymore contain the documentation.
 > 
 > 
 > AldorDoc approach:
 > 
 > 2+) Extracting the documentation is in principle possible.
 > 
 > 2-) AldorDoc is would be a nice tool to extract documentation, but it
 > is incomplete and nobody seems to work on it since Yannis left.
 > 
 > 2-) There has never been an agreement of how ++ comments should be
 > structured so that the resulting documentation is not much better than
 > writing it in ASCII. (In particular, no nice formatting or hyperlinks
 > could be made.)
 > 
 > 
 > There is definitely a need for a good documentation extraction tool.
 > However, such a tool cannot be written if there is no agreement on how
 > the contents of ++ comments should be structured.
 > 
 > Personally, I like the Aldoc idea of using LaTeX, but I'd rather like
 > to see the documentation as ++ comments. I don't like the complexity
 > of Aldoc: one has to remember \altype, \this, \alfunc, \alexp, \name,
 > etc.
 > 
 > 
 > The goal should be to write a nice documentation tool comparable to
 > JavaDoc. Before writing a tool let us start with a few specifications.
 > 
 > 1. The documentation should appear as ++ and +++ comments so that the
 > compiler is able to put them into the .ao file and some program (a bit
 > more advanced than AldorDoc) is able to extract those comments and
 > puts them into a nice browser form similar to what hyperdoc (in Axiom)
 > used to be.
 > 
 > 2. The ++ comments should not contain information that could be
 > extracted from the actual code (like, for example, the name of the
 > type that is described inside ++ or name and signature of functions).
 > 
 > 3. The ++ comments should be easily readable in the .as file.
 > 
 > 4. The markup for structuring ++ comments should be easy to learn and
 > easy to remember.
 > 
 > 
 > 
 > A Suggestion:
 > 
 > Although not everyone is fluent in LaTeX, I propose LaTeX for the
 > general markup of ++ comments. One good reason for LaTeX is that it is
 > very powerful. A second one is that I am about to release an
 >    Aldor Literate Programming Support
 > in a few weeks where everything between code lines IS LaTeX including
 > the ++ API description.
 > 
 > 
 > As additional markup I (actually together with Christian Aistleitner)
 > propose
 > 
 > \adtype{TYPENAME}
 >      markup for a category, a domain or package name, TYPENAME should
 >      be typeset as a link to where TYPENAME is defined. Typeset in
 >     verbatim mode.
 > \adthistype
 >      expands to the type most recently defined,
 > \adname[TYPENAME]{FUNC:SIGNATURE}
 >      markup for a function or a constant, FUNC appears in the text. The
 >      other information is used for hyperlinks. FUNC should be set in
 >      verbatim mode.
 > \adthisname
 >      expands to the function or constant most recently defined,
 > \adcode{SHORT ALDOR CODE}
 >      markup for very short pieces of Aldor code (oneliners),
 > \begin{adsnippet} .. \end{adsnippet}
 >      environment to set (possibly incomplete) pieces of aldor code,
 >      code appears in verbatim mode.
 > \begin{adprogram} .. \end{adprogram}
 >      environment to set short programs (which should be compilable),
 >      code appears in verbatim mode.
 > \begin{adusage} .. \end{adusage}
 >      environment to describe the usage of a function, constant
 >      or type,
 > \begin{addescription}{SHORTDESCRIPTION} .. \end{description}
 >      environments to describe the function, constant, type more clearly,
 > \begin{adseealso} .. \end{adseealso}
 >      environment to refer to related things,
 > \begin{adremarks} .. \end{asremarks}
 >      environment to describe particular behavior.
 >      ((I am not sure whether remarks should get their own environment.))
 > 
 > Maybe there should also be
 > 
 > \begin{adparameters} .. \end{adparmeters}
 >      environment to describe function parameters
 > 
 > \begin{adexceptions}
 > \adthrows{MyExeption} Description of \adthisexception.
 > \adthrows{MyOtherExeption} Description of \adthisexception.
 > \end{adexceptions}
 >      environment to describe which exceptions the function throws.
 > 
 > 
 > Does anybody see a need for other markup?
 > 
 > I hope that this mail starts a short or long discussion on this issue.
 > 
 > Ralf
 > _______________________________________________
 > Aldor-l mailing list
 > Aldor-l at aldor.org
 > http://www.aldor.org/mailman/listinfo/aldor-l