summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/ChangeLog8
-rw-r--r--doc/extend.texi33
-rw-r--r--doc/gh.texi90
-rw-r--r--doc/guile.texi6
4 files changed, 88 insertions, 49 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog
index 553aab4f5..4482010b0 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,11 @@
+2001-06-20 Neil Jerram <neil@ossau.uklinux.net>
+
+ * guile.texi (Top): Move GH chapter to end of Part V.
+
+ * extend.texi (Libguile Intro), gh.texi (GH deprecation): Explain
+ deprecation of GH and broad plan for documentation of scm
+ interface.
+
2001-06-18 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
* srfi-modules.texi (SRFI-1): Completed procedure documentation.
diff --git a/doc/extend.texi b/doc/extend.texi
index e9e7cdd0f..5cadde4e8 100644
--- a/doc/extend.texi
+++ b/doc/extend.texi
@@ -5,19 +5,22 @@
The chapters in this part of the manual explain how to use Guile as a
powerful application extension language.
-The following chapter, ``GH: A Portable C to Scheme Interface,'' shows
-how to call Guile from your application's C code, and how to add new
-Scheme level procedures to Guile whose behaviour is specified by
-application specific code written in C. The Guile interface functions
-documented in this chapter make up a high level, portable interface
-which (we hope) will also someday work with other Scheme interpreters,
-allowing you to write C code which will work with any of several Scheme
-systems.
+An important change for the 1.6.x series of Guile releases is that the
+GH interface is now deprecated. For the reasoning behind this decision,
+see @xref{GH deprecation}. The GH interface will continue to be
+supported for the 1.6.x and 1.8.x release series, but will be dropped
+thereafter, so developers are encouraged to switch progressively to the
+scm interface. The last chapter in this part of the manual (@pxref{GH})
+documents both how to use GH and how to switch from GH to scm.
-The portable interface is rich enough to support simple use of Guile as
-an application extension language, but is limited by its own portability
-where a deeper integration is desired between Guile and your
-application's code. The subsequent chapters therefore present aspects
-of libguile that allow you to use more of Guile's C level features, and
-to extend your application in more complex ways than is possible with
-the portable interface.
+The documentation of the scm interface is currently a bit confused, but
+the situation should improve rapidly once the 1.6.0 release is out. The
+plan is to refocus the bulk of Part II, currently ``Guile Scheme'', as
+the ``Guile API Reference'' so that it covers both Scheme and C
+interfaces. (This makes sense because almost all of Guile's primitive
+procedures on the Scheme level --- e.g. @code{memq} --- are also
+available as C level primitives in the scm interface ---
+e.g. @code{scm_memq}.) There will then remain a certain amount of
+Scheme-specific (such as the ``Basic Ideas'' chapter) and C-specific
+documentation (such as SMOB usage and interaction with the garbage
+collector) to collect into corresponding chapters.
diff --git a/doc/gh.texi b/doc/gh.texi
index 668270cb8..999ea6331 100644
--- a/doc/gh.texi
+++ b/doc/gh.texi
@@ -5,40 +5,17 @@
@cindex gh
@cindex gh - reference manual
-The Guile interpreter is based on Aubrey Jaffer's @emph{SCM} interpreter
-(@pxref{Overview, SCM: a portable Scheme interpreter, Overview, scm,
-SCM: a portable Scheme interpreter}) with some modifications to make it
-suitable as an embedded interpreter, and further modifications as Guile
-evolves.
-@cindex SCM interpreter
-@cindex Jaffer, Aubrey
-
-Part of the modification has been to provide a restricted interface to
-limit access to the SCM internals; this is called the @code{gh_}
-interface, or @emph{libguile} interface.
-@cindex gh_ interface
-@cindex libguile interface
-
-If you are @emph{programming with Guile}, you should only use the C
-subroutines described in this manual, which all begin with
-@code{gh_}.
-
-If instead you are @emph{extending Guile}, you have the entire SCM
-source to play with. This manual will not help you at all, but you can
-consult Aubrey Jaffer's SCM manual (@pxref{Internals, SCM: a portable
-Scheme interpreter, Internals, scm, SCM: a portable Scheme
-interpreter}).
-@cindex Guile - extending
-@cindex extending Guile
-@cindex SCM internals
-
-If you are @emph{adding a module to Guile}, I recommend that you stick
-to the @code{gh_} interface: this interface is guaranteed to not
-change drastically, while the SCM internals might change as Guile is
-developed.
+This chapter shows how to use the GH interface to call Guile from your
+application's C code, and to add new Scheme level procedures to Guile
+whose behaviour is specified by application specific code written in C.
+Note, however, that the GH interface is now deprecated, and developers
+are encouraged to switch to using the scm interface instead. Therefore,
+for each GH feature, this chapter should also document how to achieve
+the same result using the scm interface.
@menu
+* GH deprecation:: Why the GH interface is now deprecated.
* gh preliminaries::
* Data types and constants defined by gh::
* Starting and controlling the interpreter::
@@ -54,6 +31,57 @@ developed.
@end menu
+@node GH deprecation
+@section Why the GH Interface is Now Deprecated
+
+Historically, the GH interface was the product of a practical problem
+and a neat idea. The practical problem was that the interface of the
+@code{scm_} functions with which Guile itself was written (inherited
+from Aubrey Jaffer's SCM) was so closely tied to the (rather arcane)
+details of the internal data representation that it was extremely
+difficult to write a Guile extension using these functions. The neat
+idea was to define a high level language extension interface in such a
+way that other extension language projects, not just Guile, would be
+able to provide an implementation of that interface; then applications
+using this interface could be compiled with whichever of the various
+available implementations they chose. So the GH interface was created,
+and advertised both as the recommended interface for application
+developers wishing to use Guile, and as a portable high level interface
+that could theoretically be implemented by other extension language
+projects.
+
+Time passed, and various things changed. Crucially, an enormous number
+of improvements were made to the @code{scm_} interface that Guile itself
+uses in its implementation, with the result that it is now both easy and
+comfortable to write a Guile extension with this interface. At the same
+time, the contents of the GH interface were somewhat neglected by the
+core Guile developers, such that some key operations --- such as smob
+creation and management --- are simply not possible using GH alone.
+Finally, the idea of multiple implementations of the GH interface did
+not really crystallize (apart, I believe, from a short lived
+implementation by the MzScheme project).
+
+Where portability is concerned, the @code{scm_} interface is now already
+portable in the sense that other projects could provide an alternative
+implementation of the @code{scm_} header file. For the majority of
+@code{scm_} functions, all that is needed is a definition of the
+@code{SCM} type, and then those functions are automatically portable by
+virtue of the fact that their signatures refer only to this @code{SCM}
+type.
+
+For all these reasons, the Guile developers have decided to deprecate
+the GH interface --- which means that support for GH will be completely
+removed after the next few releases --- and to focus only on the
+@code{scm_} interface, with additions to ensure that it is as easy to
+use in all respects as GH was.
+
+It remains an open question whether deeper kinds of interface
+portability would be useful for extension language-based applications,
+and it may still be an interesting project to attempt to define a
+corresponding GH-like interface, but the Guile developers no longer plan
+to try to do this as part of the core Guile project.
+
+
@node gh preliminaries
@section gh preliminaries
diff --git a/doc/guile.texi b/doc/guile.texi
index 29da7b221..d42cc8ca4 100644
--- a/doc/guile.texi
+++ b/doc/guile.texi
@@ -80,7 +80,7 @@ by the Free Software Foundation.
@sp 10
@comment The title is printed in a large font.
@title Guile Reference Manual
-@subtitle $Id: guile.texi,v 1.10 2001-05-23 17:24:49 mgrabmue Exp $
+@subtitle $Id: guile.texi,v 1.11 2001-06-20 22:08:19 ossau Exp $
@subtitle For use with Guile @value{VERSION}
@include AUTHORS
@@ -187,11 +187,11 @@ Part IV: Guile Scripting
Part V: Extending Applications Using Guile
* Libguile Intro:: Using Guile as an extension language.
-* GH:: GH: a portable C to Scheme interface.
* Data Representation:: Data representation in Guile.
* Scheme Primitives:: Writing Scheme primitives in C.
* I/O Extensions:: Using and extending ports in C.
* Handling Errors:: How to handle errors in C code.
+* GH:: The deprecated GH interface.
Appendices
@@ -273,9 +273,9 @@ Indices
@end iftex
@include extend.texi
-@include gh.texi
@include data-rep.texi
@include scm.texi
+@include gh.texi
@c Appendices
@iftex