Re: [Axiom-developer] Literate documentation

[Ralf Hemmecke]

Hi Bill,

> > In particular, if I read (4) I come to the conclusion that using
> > LEO might rather be counterproductive to our pamphlet idea.

> As far as I recall, our current exchange about Leo originated in my
> reply to Tim's post concerning "Knuth's literate style":
>
> http://lists.nongnu.org/archive/html/axiom-developer/2007-05/msg00158.html
>
>
> I mentioned Leo as an example of a literate programming style that
> specifically does *not* aim simply to product a single linear
> monolithic document (or book). As your quote above from the Leo
> user's guide shows, this is not what the developers of Leo have in
> mind.
[snip]
> But the point of view Leo is that that the outline view is more
> powerful and more flexible than that and so the woven result is of
> considerable lesser importance.

Oh, maybe I made a big mistake. By "pamphlet idea" I did *not* refer to 
the production of a monolithic 1000 pages book, but rather on the view 
that documentation is more important than code.

I know that the "clone" idea is powerful. Without clones LEO is just a 
fancy way of showing the table of contents and clicking there to get to 
the corresponding section. Plus, LEO can extract code from the sections. 
Minus, there is no real weave command.

And yes, I agree, "weave" is *not* necessary, if the documentation can 
nicely be read inside LEO. Well, and that is exactly, what I am missing.
I would have to convince LEO to write out a .nw file than noweave and 
latex and view the .dvi. But what happens if I see an typo in the .dvi? 
How do I find the place in the .leo file?

For my working style, LEO just adds overhead.

And the clones, I feel that they are a good thing, that viewing the code 
and documentation from different perspectives is desirable. However, I 
did not yet feel the need for "clones" in my own documentation efforts.
I am totally content with hyperlinks.

> In particular this was a follow-up to comments from Waldek, Gaby, and
> me that were critical of the creation of 'bookvol5.pamphlet' as
> literate documentation of the Axiom interpreter. We all expressed the
> opinion that 'bookvol5' was more difficult to appreciate even than
> the original code.

Sorry, I haven't even looked at bookvol5. But if it is recognised as 
worse than the actual pure code, then this is not a problem of whether 
using LEO or not, but rather a problem that there is no general 
guideline of how to write good literate programs, i.e. easily 
understandable documentation.

My effort in documenting my own code is probably not really literal 
programming. The best thing I've seen up to now is Cliff's description 
of cl-web.

In general, I think, understandable documentation results by 
constructive criticism of other people's works (+ enough time to 
actually rewrite the documentation).

> Of course this is from a "programmers point of view" which might not
> be the same as someone new just starting to use Axiom and trying to
> understand how it works. But I think programmers still need literate
> documentation, the question is just what form this should take. I am
> saying that the Knuth-style "book" is not a particularly good form of
> documentation for a programmer.

What we need is not programmer, but people who understand their area 
(mathematics, physics, etc.) and who are able to put their knowledge 
into code. A traditional programmer is a slave. (That is overstated.) Of 
course, programming is a creative task sometimes, but I would rather 
like to support the "paper-writing people" to aquire some programming 
knowledge.


> > The declared goal in Axiom is to write documentation that is
> > readable by humans. I am not an experienced LEO user, but all I see
> > does convince me to use LEO in order to produce an article+code
> > about some mathematical idea.

> I presume you meant to write: "does *not* convince me to use LEO
> ..."?

Oh, sorry. Of course.

> But of course Leo is intended to be a tool used by humans. Tools that
> allow one to navigate online using a web browser through svn
> revisions and change logs is another such tool intended to be used by
> humans.

I don't want to throw those tools away, but what I am saying is just 
that LEO does not meet my needs. I want some powerful editor that helps 
me in coding the ideas and can extract the code from the text.

> The question is: given current (web) technology and current 
> programming practices, what form should a "literate program" take?

> > LEO is, in my eyes, very code focused. Am I wrong?

> I think you are right. It is apparently viewed by many people who use
> it as a kind of high level integrated development environment (IDE)
> that supports literature programming.

For me LEO is not enough. Let me give a wish list for my dream IDE 
(whose purpose is to write extensions of Axiom's algebra code):

o  Code and Documentation should belong together.
o  The IDE should hide extra markup for the doc/code and code/doc
   borders.
o  Wysiwyg style. (I am not quite sure about that, but it would
   avoid the weave step. And graphics and math formulae inside the
   documentation should not be a rare thing.)
o  Hyperlinks already inside the editor.
o  Semantic code hyperlinks from symbol information of
   integrated Aldor/Spad compiler.
o  Support of (formal) API documenation.
o  File format is revision control friendly.
o  Automatic dependency recognition of files and code(library)
   compilaton.
o  Integration of test suite generation and execution.
o  Aldor/Spad Debugger support.
o  ... maybe some more properties ...

As I said in one of my previous mails. I somehow want an IDE that is as 
powerful as Eclipse+TeXmacs+LEO+(Emacs).

I think one of my next tasks is to investigate what TeXmacs misses.

Good night

Ralf