> On Monday, October 16, 2006 8:47 PM Waldek Hebisch wrote:
> > ...
> > 1) ATM I can not add much value to what is already there --
> > I can read the code but the classic rule of documentation is
> > "documentation should not repeat the code"...
>
> Actually this classic rule of documentation is *not* appropriate
> to literate programming. In a literate program the document contains
> the code so it certainly "repeats the code" in that sense. The code
> illustrates and implements the ideas described in the document. Code
> and documentation are not two separate things.
>
Let us look at an example. I wrote:
------------<start example>------------
....
; Clean old data
(do-symbols (symbol)
(when (get symbol 'database)
(setf (get symbol 'database) nil)))
(setq *allconstructors* nil)
...
------------<end example>------------
Do you think that:
------------<start example>------------
...
<<Clean old data>>
....
....
To clean old data we loop over all symbols from [[boot]] package
and reset [[boot::database]] property to [[nil]]. We also rest
[boot::*allconstructors*]] to [[nil]].
<<Clean old data>>=
(do-symbols (symbol)
(when (get symbol 'database)
(setf (get symbol 'database) nil)))
(setq *allconstructors* nil)
------------<end example>------------
is better (I admit that as a reader I find the first version much
better).
> > 2) AFAIK Tim is working on the same file and scattered changes
> > (or some re-organization) is likely to create conflict with his
> > changes.
>
> No problem. That is why we use version control systems. You both
> can make changes and conflicts can be easily resolved.
>
version control detects conflicts. One has still manually resolve them.
If Tim permute hunks in one way and I in another way then resoving
conflits will require some work.
> > 3) For me diff is a very important tool and to make my work easier
> > (or even possible) I want to do minimal changes.
>
> If you wish to run diff on only the code you should run notangle
> first to extract just the code from each literate document
> (pamphlet).
>
If I have to notangle files before doing work on then, then why this
talk abot literate programming? OTOH if I work on a pamphlet, but
to do diff I must first run notangle, then this is significant
extra burden (yes, I know aliases and scripts, but this is still
significant extra burden).
> What Gaby (and Tim Daly) are saying is that when you submit patches,
> these patches should be changes to the pamphlet files which result
> in an easy to understand document (e.g. in dvi format) and which
> produce your modified code when input to notangle.
>
The patch I wrote changed the paphlet file. I admit that I did not
use dvi viewer to check formatting, but since the parts I changed
follow textual format using only text terminal should be OK.
--
Waldek Hebisch
[EMAIL PROTECTED]
_______________________________________________
Axiom-developer mailing list
[email protected]
http://lists.nongnu.org/mailman/listinfo/axiom-developer
