Re: out of date documentation

[Neil Jerram]

>>>>> "Dirk" == Dirk Herrmann <address@hidden> writes:

    Dirk> Some more points:

    Dirk> * The documentation for gh_eval_file and gh_load is
    Dirk> incorrect: These functions do not return the result of the
    Dirk> last expression evaluated, but rather SCM_UNSPECIFIED.

Right - I will fix these soon.

    Dirk> * The chapter about pairs states, that SCM_CAR and friends
    Dirk> may be used on any non-immediate data type.  This is not
    Dirk> true any more, since we only want them to be used on real
    Dirk> pairs.

    Dirk> * SCM_LENGTH has been replaced by a set of different macros
    Dirk> like SCM_STRING_LENGTH etc.

Yes... and there are probably several other problems in the same
class.  I think to fix this exhaustively I need to grep through the
manual for everything that the NEWS file now says is deprecated.

    Dirk> More general, it seems that the whole part V needs some
    Dirk> restructuring.  In contrast to the current structure, I
    Dirk> suggest a hierarchy like the following [...]

This sounds good.  In terms of structure, part V is the part that I've
least thought about.  (Plus I confused myself for a while worrying
about why GH should exist at all!)

    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.

    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.

Thanks for your comments!

Regards,
        Neil