[Aldor-l] Ann: ALLPROSE / Suggestions

[Ralf Hemmecke]

Hello Martin,

Martin Rubey wrote:
> Ralf Hemmecke <ralf at hemmecke.de> writes:
> 
>> Hi Martin,
>>
>>> * it would be very useful - if not necessary - if you provided a one page
>>>   summary on how to use ALLPROSE for the average A{ldor,xiom} programmer,
>>>   separate from the complete 225 pages documentation.
>> I thought there is enough overview material at the beginning of the ALLPROSE
>> documentation, but seemingly one easily gets distracted by the vast amount of
>> documentation of all the make files so that a short section "How to work with
>> ALLPROSE" is certainly a good idea. However, I am not quite sure what you would
>> like to see in such a section. What do you think is missing from Section 6 "How
>> to Start a New Project"?
> 
> Several things:
> 
> * it is more than one page. Two pages would be acceptable, I think.
> 
> * it doesn't contain the markup.

Hmm, are you looking for a description of aldordoc.sty (Section: User
Interface)?  I must admit that is not the first place a user of ALLPROSE
would look for. But there is a link to +++ environments in Section "How
to Document the Aldor Sources".

> So what I'm thinking of is a single page which describes all the markup in
> short phrases and *maybe* a paragraph summarizing Section 6.

I have no idea how to make Section 6 shorter. The only way would be to
write a script that does most of these setup things automatically. But a
library writer has to replace most of the code anyway so a script makes
not much sense. Are there other opinions?

> Furthermore, it should be separate from the big document.

I am somehow against this. If I understand you correctly, you would like
a kind of reference card for the "How to start a new project" and
"aldordoc user interface". Maybe I provide such documents on my website,
  but I don't see a real advantage.

If you write a library with ALLPROSE do the following.

Open allprose-x.y.z.pdf for reference purposes.
Start a new project (myprj)
Produce a myprj.dvi and open this file.
Now you could remove part of the documentation that just describes
ALLPROSE by putting a comment sign in *front of the line* containing
   \input{allprose.tex.nw} in the file myalps.tex.nw (or rather the
   corresponding file of your project (myprj.tex.nw).
Type "make dvi" again (maybe two times to get the references
   correct). Only the description of YOUR library remains.
The latter might become interesting for an AXIOM Journal since then the
documentation gets 180 pages shorter. ;-)

> you provided means to organize documentation for different groups, namely users
> and developers. But somehow, it seems not possible yet to extract the
> information for users easily... 

Correct. That part is not finished.

> In fact, this is another suggestion: There
> should be a way to produce user-only documentation. (i.e., skipping almost
> everything but the +++ comments)

I just found out, that the "verbatim" package cannot easily be tricked
to do the job. I'll have to write a short script for this.

Anyway, I don't want to invest much time in that. The reasons is that my
preferred way of producing an API description is the following.

- Install a set of libraries (.al and .a) on your computer.
- Call a program that extracts the +++ comments that are compiled into
   the  .ao files of the .al libraries together with some further
   information on the code (see the output of "aldor -fasy FILE.ao").
- Transform this information into a LaTeX document.
- Transform into HTML ...

That would lead to an API description of the libraries you have actually
installed on your system. And even more than ALLPROSE could provide: the 
references would work even between libraries since there would be 
generated ONE big LaTeX file.

Of course somebody has to put the +++ comments into the .ao file. But
ALLPROSE does this by default.

The only drawback is: The program AldorDoc (which was planned to do the 
.ao --> .html translation) by Yannis Chicha is no longer maintained. So 
somebody needs to work on that. Unfortunately I have not contact address 
of Yannis.

Ralf