RE: [Axiom-developer] database fixes

[Page, Bill]

> Bill Page wrote:
> > ... 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.
> >
>

On Monday, October 16, 2006 11:02 PM Waldek Hebisch wrote: 
> 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).
> 

When you say "as a reader", I wonder what you are reading:
the Lisp code or the dvi document that you generated from the
pamphlet file? In terms of creating a document that can be read
while sitting in a comfortable chair with your feet warmed by
the fireplace, I think your 2nd example is much better. :-)
Of course to make good sense you must also consider the overall
structure of the document. The paragraph starting "To clean
old data" should be located in the section of the document where
you describe why it is desirable to clean up the database in the
first place, i.e. including at least some of the text in the
email that you sent introducing this patch.

In general I agree that it is not very helpful to repeat verbatim
what one can easily read from the code. But we need to explain
that setting the database property to nil is the proper way to
remove undesirable information from the database. So for example
I probably would not have written:

  We also reset [boot::*allconstructors*]] to [[nil]].

Instead the text should say why we do that.

>  
> > > 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
> resolving conflicts will require some work.

Yes, but there are some very good tools for doing this and the
chances of this happening (usually) are not very high. Of course
if you anticipate a major reorganization of the file, then it might
be a good idea to check with Tim or Gaby first, but that should
not stop you from contributing your work to the repository. If
everyone hesitates and only one person at a time can work on the
system, progress will be very slow.

> 
> > > 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 about literate programming?

When you said "diff is a very important tool" I understood that
as implying that you were primarily interested in comparing the
program code in one file with the program code in another file.

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

Certainly it is possible to use diff on pamphlet files but in
some cases the result might include more than you are interested
in if someone has taken the time to add a lot of new (important!)
documentation to the file. Just like sometimes it is interesting
to run diff on a latex file, but most times not, because what we
are (usually) interested in when writing a latex document is the
final result not the details of source line indentation and coding.

But if we are debugging a problem and are deeply into the flow
of a program, then it makes sense to me to focus on the code by
using notangle first, just the way the compiler/makefile would.
  
> > 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 pamphlet 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.  

Actually I agree. Your original patch was not so bad - it is
just that it did not add any explanation to the document itself.
It improved the program but did not improve the document.

I would say that the main point of using a dvi viewer is not just
to check the formatting, but rather to focus on the document the
way new reader of the document would. You can ask yourself: Does
this document describe properly what this program is doing and why
I made the changes that I did?

Maybe the change in attitude from "documenting a program" to
"writing a literate program" is rather subtle. If you read the
literate programming news groups and web sites you will see that
many people have tried to explain this difference many times. So
I am not so confident that my attempt to do it again will be much
clearer. If not, I am sorry.

In any case, I do very much appreciate your work on this problem
and your willingness to contribute it to the Axiom source code
repositories. Thank you very much! :-)

Regards,
Bill Page.