[Axiom-developer] Re: [Aldor-l] Ann: ALLPROSE / Suggestions

[Ralf Hemmecke]

Dear Bill,

Page, Bill wrote:
> On Wednesday, November 16, 2005 7:53 AM Ralf Hemmecke wrote:
> > Martin Rubey wrote:
> >
> > > * 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.
>
> I have read quickly through the 225 pages of documentation of 
> ALLPROSE and I have to agree with Martin. A short concise summary in 
> 1 or 2 pages that gives the basic ideas, motivation and a few **very 
> simple** examples is necessary. The examples can be just partial 
> examples - only enough to get the basic idea across.

Unfortunately, I must agree with you. But as it is written somewhere in
the ALLPROSE documentation, it is not yet finished. I wanted to get it
out so that people see that I am working on something. I do not claim
ALLPROSE to be THE solution to all problems. And if the Axiom developers
find it difficult, who else could find it easy?

I will work on all of your suggestions, but don't expect something much
better already tomorrow.

> Although I am strongly in favor of this literate programming 
> methodology, if there is one criticism that I would make against it 
> is it easily leads to excessive verbosity and it does very little to 
> help with documentation organization.

Sad but only half true. ALLPROSE contains 2 parts of documentation.
1) It documents itself, and
2) it documents a library project.

Since 1) is not important anymore if you know how to work with ALLPROSE,
you can turn it of and are left with part 2). After all, ALLPROSE is
meant to help library programmers. Its own documentation only comes as
an additional part.

But in some way you are right. ALLPROSE still lacks a guideline of how
to write good literate programs. I am not quite sure whether I can
provide this, since I am new to this paradigm myself.

> In many cases it is often more difficult for the author of a complex 
> program (or any scientific work for that matter) to write 2 really 
> good pages about the work than it is to write 200 pages. As a result
>  the documentation can get so verbose that it becomes inaccessible 
> even though it is complete.

But clearly, literate programming does not help at all here. LP is just
a tool that enables people to write documents instead of programs.
Unfortunately, the reality is the other way round. Most people find it
difficult to change their minds from programs to documents. So it would
be good to provide many more examples like dhmatrix.spad.

> > 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"?
>
> I find it is rather difficult to say precisely what is missing 
> because I think that really is not the problem. The issue is more the
>  way the information is presented. The best analogy that I can think 
> of is something like this: suppose that you have been invited to 
> create a one page advertisement for the ALLPROSE product that will be
>  placed in a technical journal such as the mythical "IEEE Advanced 
> Computer Algebra Systems". What do you want to say to the experienced
>  readers who are not likely to take more than 10 minutes at most to 
> review your advertisement?

So you think Section 5 (5.1-5.3) is not good enough? Maybe I should
really turn this into an advertisment.

> I think this is the sort of thing that should appear at the beginning
>  of an literate programming documentation - a sort of technical 
> executive summary.
>
> > > * maybe you can connect yourself with Eitan Gurari to enable 
> > > automatic translation to html/mathml via tex4ht?
> > Thank you, I would really be happy if somebody could assist me with
> >  that translation.
>
> What problems are you having using tex4ht? Have you tried any of the 
> other packages for converting LaTeX to HTML?

I think, if any at all then tex4ht would be the only possibility.
latex2html does not understand several things of my style files.
Unfortunately, I have never worked with tex4ht. I only learnt that there
are several different commands. "tex4ht myalps.tex" runs through and
produces an .html file, but that is not really what I would expect, it
is just a text file, no HTML tags, nothing. If somebody gives me an
example of a command line that I could execute, I'd appreciate it.

man tex4th

comes with so many programs and options that I don't know where to start.

Ralf