Re: [Axiom-developer] database fixes

[Waldek Hebisch]

> 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
address@hidden