[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Axiom-developer] Literate documentation

From: Ralf Hemmecke
Subject: Re: [Axiom-developer] Literate documentation
Date: Sat, 19 May 2007 01:46:57 +0200
User-agent: Thunderbird (X11/20070326)

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":

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
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

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
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)
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


reply via email to

[Prev in Thread] Current Thread [Next in Thread]