Re: GH. Again.

[Neil Jerram]

>>>>> "Marius" == Marius Vollmer <address@hidden> writes:

    Marius> The summary: the GH interface is moved out of the central
    Marius> proper of Guile.  It will be provided for quite some time,
    Marius> but only for compatibility reasons.  We will steer people
    Marius> towards using (a cleaned up version of) the `scm_'
    Marius> interface.  Ultimately, the GH interface will end up in
    Marius> its own distribution, ready to be taken by anyone who
    Marius> wants to work on it.

I agree as well.

I do still worry a bit about the GH users who'll be left unsupported,
but going with a clean scm_ interface is undoubtedly the best approach
for the future.

To avoid giving any further false impressions/hopes to those GH users,
I think we should

- state clearly for how many more releases GH will be part of Guile
  core  (I suggest 1.6.x and 1.8.x only.)

- for these releases, commit to supporting the GH interface as it was
  at the time of the 1.4 release

- after these releases, commit to removing GH completely

- remove anything that's been added to GH since 1.4, and don't add
  anything else to it.

The biggest thing affected by the last point is gh_init() - so people
will just have to write scm_init_guile() instead.

    Marius> There is confusion over the status of the GH interface.
    Marius> It is at the same time advertised as _the_ API for users
    Marius> of libguile, and mostly neglected by us developers.  We
    Marius> need to clean up this confusion by stating what the GH is
    Marius> interface is about, how it came about historically, and
    Marius> how we plan on realizing its promises.

    Marius> As far as I can see, the main virtues of the GH interface
    Marius> were to be portability between different Scheme
    Marius> implementations, and ease of use compared to the more
    Marius> awkward scm_ interface.

Right.  I think a key point here - which a lot of more recent Guile
users may not realize - is how _very_ awkward the scm_ interface used
to be.  Now scm_ is usable, clean and portable enough that GH isn't
needed.

    Marius> Thus, my plan would be to

    Marius>  - Make sure that libguile is easy to use without the GH
    Marius> interface.  For every (sensible) GH feature there should
    Marius> be a easy way to do the same thing with the scm_
    Marius> interface.

Sounds good.  I'm not aware of any GH features for which this isn't
trivial, but we should be careful anyway.

    Marius>  - Document how to get by without GH for people who want
    Marius> to stop using it in their existing programs.

    Marius>  - Reflect this change in policy in the Reference Manual.
    Marius> The section about GH should be put into a separate manual,
    Marius> and the Reference Manual should talk about the scm_
    Marius> interface exclusively.

I think the "document how to get by without GH" naturally fits with
the separate section documenting GH: for everything that is documented
there, we also say how to do it using the scm_ interface.

As regards documenting the scm_ interface, there was a discussion (on
the Guile mailing list) at the end of 1998 where the strong consensus
seemed to be for documenting the Scheme and C APIs together.  This
means restructuring the existing Parts II and V into two new parts:

- Introduction to Scheme

- Guile API Reference (covering both Scheme and C)

There will also be C only documentation to put somewhere, covering
guidelines for C code.

My plan was to start on this restructuring after the 1.6.0 release.

        Neil