Re: out of date documentation

[Dirk Herrmann]

On 17 Apr 2001, Neil Jerram wrote:

>     Dirk> Further suggestions: I'd like Jim's essay about data
>     Dirk> representation to be changed in some aspects.  Since Guile's
>     Dirk> data representation is actually _completely_ different from
>     Dirk> the simple representation that Jim uses as an example, it
>     Dirk> has confused me a lot at that time, especially since there
>     Dirk> was no description of the way guile actually does it.
> 
> Err... are you saying that even the `How Guile does it' section is
> completely different from Guile's current representation?  Or just
> that the `Data representation in Scheme' example is not close enough
> to be helpful?  If the former, I'm surprised, and I think we should
> bring it into line with Guile's current reality.

Sorry for being unclear.  It's just the `Data representation in Scheme'
example.  The chapter `How Guile does it' describes quite nicely how one
should make use of guile's type system.  Both chapters, however, describe
completely different things:  The chapter about data representation
describes how the type system works internally, while the chapter about
how guile does it describes the API but not the internals.  My confusion
came from the fact that the actual internals of the type system are quite
different from those in the example.

One example:  In the essay it says that pairs are so frequent, that it
makes sense to store the information 'This SCM value points to a pair
cell' within the SCM value.  Guile, however, does not do this.  In
contrast, in guile you have to look at the car of a cell to see if it
actually is a pair or some cell for a different data type.  (This, btw,
might really be worth changing some time.)

IMO, the description of the internals should be closer to the real thing,
not in order to make people rely on internals, but to make it easier to 
understand for those who like to hack on guile itself.

[Note:  Jim wrote that essay as an explanation about how one should use
smobs.  I don't want to be unfair here:  The essay has helped a lot of
people (including me) to understand smobs and their usage.  The
introductory part about data representation was just meant to help people
understand all the fuss that is necessary when dealing with smobs.  It was
not intended to be a description of guile's internals.  But, now that we
put the essay into a manual for guile, we will probably have to adapt
some things.]

>     Dirk> Thus, IMO we should either make it more obvious that the
>     Dirk> whole essay is just an introduction and actually differs
>     Dirk> enormously from guile's actual representation.  In this
>     Dirk> case, I suggest for example not to use SCM as the name for
>     Dirk> the universal type in the examples, to avoid confusion with
>     Dirk> guile's usage of SCM.
> 
> Absolutely, if the intention is not to document real Guile.
> 
>     Dirk> Alternatively, we could try to bring the description of the
>     Dirk> data types closer to guile's actual representation.  This
>     Dirk> would make it easier to integrate this with the paragraphs
>     Dirk> about SCM / scm_bits_t and such.
> 
> This is what I think we should do, if I've understood you correctly.

The difficult thing about chapter V is, that we currently deal with three
different things:  the gh API, the scm API and finally the introduction to
data representation in scheme/guile.  The whole thing is already confusing
since there is some overlap between the gh API and the scm API (not much,
though:  SCM, SCM_BOOL_T/F, SCM_UNSPECIFIED, SCM_UNDEFINED, SCM_EOL).  
If, in addition, there is a description about data representation in
scheme which does not actually match the way that guile does it, well...

Personally, I'd like the chapters about gh and scm to be as self-contained
as possible.  This can mean that we will have to duplicate the
documentation about the parts that are common for both.  This has the
usual disadvantages of duplication.

Alternatively we could extract the common parts into an extra chapter.  
This, however, has the disadvantage that certain things need to be
discussed differently for gh and scm.  For example the SCM/scm_bits_t
distinction is not of importance for pure gh.

My favorite solution is to choose the duplicating approach:  There are not
too many overlaps, and for some of them the discussion for gh and scm is
quite different.  In cases, where both APIs share definitions, crosslinks
could be given.  (It is, btw., surprising that SCM_BOOL_F and such are
actually part of the gh interface - at least they are currently documented
as such.  GH_BOOL_F etc. would seem more natural...)

Best regards,
Dirk Herrmann