[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Axiom-developer] Literate Programming -- Knuth interview
From: |
Martin Baker |
Subject: |
Re: [Axiom-developer] Literate Programming -- Knuth interview |
Date: |
Sat, 19 Nov 2011 16:11:30 +0000 |
User-agent: |
KMail/1.13.6 (Linux/2.6.37.6-0.9-desktop; KDE/4.6.0; x86_64; ; ) |
> Documentation and comment systems are not like this. They make the
> program organization "fit the machine". They talk about the code, and
> focus on line-by-line or file-by-file. They tend to work well with all
> kinds of "tools" like Eclipse, Javadoc, or Doxygen.
I tend think of this as reference information. The sort of thing that Axiom
produces dynamically at runtime like )show and )display. I think there would
be advantages in generating this statically with a compile-time documentation
tool, the information would be much more richly interlinked with itself and
the other type of information.
> It is easy to confuse literate programming with these documentation
> and commenting system but they are nowhere the same.
They may not be the same but why should the user have to switch between them
and know which to use and when?
In Axiom, I have often tried to find something in pdf generated by literate
code when what I wanted was in hyperdoc or runtime commands or visa-versa.
There seems to be a lot of overlap of these sources of information in Axiom. I
would like to be able to link between them by clicking on the text.
Also I may be reading something as a story when I come across some issue that
I need to clarify which may be a different type of documentation and so I need
to switch to a more reference way of working. I think there are all kinds of
things that the user/maintainer needs to do between these extremes and I find
well produced HTML to be the best way to get to the information that I need
(of course, like anything else, there is a lot of bad HTML around).
Also I think a tree structure scales up better than a linear structure. A
story works well for a small program, but for a big program like Axiom, there
has to be some form of structure doesn't there?
Martin
- Re: [Axiom-developer] Literate Programming -- Knuth interview, (continued)
- Message not available
- Re: [Axiom-developer] Literate Programming -- Knuth interview, Eugene Surowitz, 2011/11/14
- Re: [Axiom-developer] Literate Programming -- Knuth interview, daly, 2011/11/14
- Re: [Axiom-developer] Literate Programming -- Knuth interview, Eugene Surowitz, 2011/11/18
- Re: [Axiom-developer] Literate Programming -- Knuth interview, daly, 2011/11/18
- Re: [Axiom-developer] Literate Programming -- Knuth interview, C Y, 2011/11/18
- Re: [Axiom-developer] Literate Programming -- Knuth interview, daly, 2011/11/19
- Re: [Axiom-developer] Literate Programming -- Knuth interview, Martin Baker, 2011/11/19
- Re: [Axiom-developer] Literate Programming -- Knuth interview, daly, 2011/11/19
- Re: [Axiom-developer] Literate Programming -- Knuth interview, Martin Baker, 2011/11/19
- Message not available
- Re: [Axiom-developer] Literate Programming -- Knuth interview, daly, 2011/11/19
- Re: [Axiom-developer] Literate Programming -- Knuth interview,
Martin Baker <=
- Re: [Axiom-developer] Literate Programming -- Knuth interview, daly, 2011/11/19