GH. Again.

[Marius Vollmer]

Hi,

I'd like to revive the discussion about the GH interface, and
hopefully formulate an acceptable plan on how to proceed.

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


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

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

Instead of dividing the interface into a easy and a difficult part and
making a very massive distinction between them (by using different
prefixes and different header files, etc), we should only provide one
API.  That API might contain easy parts and more difficult ones, but
we should not ask the user to make a decision upfront whether he wants
to use a easy or a hard API.  Technically, this decision does not need
to be made even when we keep the current role of the GH interface, but
crossing the gh_ / scm_ border connotes a deep decision, and people
might refrain from using scm_ functions in situations where it would
be the right thing.  Instead of extending GH to become nearly as
powerful as the scm_ interface, we should make scm_ as easy as GH.

Therefore, we should study in what way GH is cleaner than what we have
now in the scm_ API, and make sure that using the (appropriate part
of) the scm_ API is as easy as using GH.  Along with that, we should
prepare a "GH to SCM transition guide" so that people know how to
switch from using GH to scm_.

Portability has not been achieved for the GH interface as far as I
know.  Still I think that portability is a noble goal, and I would say
that it is what GH is really about and what distinguishes it from
scm_.  If someone wants to work on portability, he should do so in the
context of the GH API.  For that, GH does not need to be part of
Guile, and it might even help if it isn't in the same distribution
tarball as Guile.


Thus, my plan would be to

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

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

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

 - Assure people that they can continue to use the GH interface for
   quite some time if they are comfortable with it, but suggest they
   consider moving away from it.

 - Stating that the main goal of GH is to provide a portable interface
   to Scheme implementations from C, but that this goal has not been
   realized yet (if that is true).  Contributors welcome.

 - Moving the GH code out of guile-core into its own module.  This
   should be done later, after a period of `deprecation', when nobody
   is using GH anymore (except for its portability features).