Re: out of date documentation

[Dirk Herrmann]

On 16 Apr 2001, Neil Jerram wrote:

> Thanks - applying in a few moments.  Now that the manuals are part of
> guile-core, I think it's reasonable for them to document the current
> state of the code in guile-core.

Some more points:

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

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

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


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

libguile intro
A general C to scheme interface: GH
  - Hierarchy as for the chapter GH before, except for the section about
    mixing the gh and scm APIs
A Guile specific C to scheme interface: SCM
  - all the points about data-representation, scheme primitives, I/O
    extensions and error handling go here.
Mixing GH and SCM APIs


Further suggestions:  I'd like Jim's essay about data representation to be
changed in some aspects.  Since Guile's data representation is actually
_completely_ different from the simple representation that Jim uses as an
example, it has confused me a lot at that time, especially since there was
no description of the way guile actually does it.

Thus, IMO we should either make it more obvious that the whole essay is
just an introduction and actually differs enormously from guile's actual
representation.  In this case, I suggest for example not to use SCM as the
name for the universal type in the examples, to avoid confusion with
guile's usage of SCM.

Alternatively, we could try to bring the description of the data types
closer to guile's actual representation.  This would make it easier to
integrate this with the paragraphs about SCM / scm_bits_t and such.

Best regards,
Dirk Herrmann