Re: [Axiom-developer] database fixes

[Waldek Hebisch]

Bill Page wrote:
> > 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 when reading paper copy first version is even more
preferable -- searching electionic verion is easier so one
can somewhat tolerate jumping from labels to corresponding
chunks. Reading paper copy one wants thing in linear order,
to minimize searching of cross-references.

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

Hmm, I do not think information from the e-mail belongs to the
document -- for example writing a paper I discard many alternatives
and failed attempts and publish only final version. IMHO information
about specific problem belongs to the ChangeLog (in form of a
pointer to the message). Now if you think that what I wrote in the
email needs extra record or additions I may register a bug.

> I probably would not have written:
> 
>   We also reset [boot::*allconstructors*]] to [[nil]].
> 
> Instead the text should say why we do that.

You, Gaby and Tim ask way. I am not sure if I can give good
explanation. Basically, database is a single logical entity
spread out into few variable and symbol properties (this is
actually quite well explained in daase.lisp.pamplet).  All
parts of database must be kept in sync.  Now, why my specific
code?  The code follows database structure, the best explanation
I can give just repats database description.

I can think of to changes to documantation: one is to say that
all five openxxxx routines must be called together (because
otherwise database gets out of sync). The second is that there
is no need to have cleanup in browseOpen, because interpOpen
should have already cleaned up old data.

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

The point is that I did what I consider a self-contained change 
(as I explained I do not think that _this_ change needs extra
documentation).  While it is good to improve documentation
part, that would be a separate change.  Keeping first change
private and accumulating changes both slows progress and
increases probability of conflicts during merge.

Maybe another point: Axiom has parts that really need better
documentation -- Bill Burge parser would be first example,
Spad compiler the second. Compared to them daase.lisp.pamphlet
contains strightforward and well documented code.  Also
daase.lisp.pamphlet seem to work quite well compared to other
parts of Axiom, so I see little reason to change it _now_ (except
for this single patch which affects other things that I want
to do) -- other parts need more care. 

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

I routinely run diff of latex files: when changing documents
I want to avoid re-reading old parts and concentrate on changes.

> > 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 respectfully disagree: my change added extra explanations (and
corrected a wrong explanation). Just is was a very small
improvement (both to code and document aspect).
 
> 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?

Well my latex workflow is as follows: I compose text at a tty,
I use xdvi to check formatting, for deeper revision I print
the document.  When I have a lot of formulas I use xdvi much
more, but for text I prefer tty.  Tty have two advantages:
first is that I find tty fonts more plasant to read, second
is that knowing that text will be reformated I can better
concentrate on meaning.

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

I have read Knuth literate programming text, later I read TeX (the
program) and (at similar time) time Andrew Tanenbaum "Operatin Systems"
which contained Minix sources.  Frankly, I find Tanenbaum's book
better document then TeX.

-- 
                              Waldek Hebisch
address@hidden