guile/guile-core/doc ChangeLog extend.texi gh.t...

[Neil Jerram]

CVSROOT:        /cvs
Module name:    guile
Changes by:     Neil Jerram <address@hidden>    01/06/20 15:08:19

Modified files:
        guile-core/doc : ChangeLog extend.texi gh.texi guile.texi 

Log message:
        * Explain GH deprecation & plan for scm documentation.

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/guile/guile-core/doc/ChangeLog.diff?cvsroot=OldCVS&tr1=1.97&tr2=1.98&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/guile/guile-core/doc/extend.texi.diff?cvsroot=OldCVS&tr1=1.1&tr2=1.2&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/guile/guile-core/doc/gh.texi.diff?cvsroot=OldCVS&tr1=1.4&tr2=1.5&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/guile/guile-core/doc/guile.texi.diff?cvsroot=OldCVS&tr1=1.10&tr2=1.11&r1=text&r2=text

Patches:
Index: guile/guile-core/doc/ChangeLog
diff -u guile/guile-core/doc/ChangeLog:1.97 guile/guile-core/doc/ChangeLog:1.98
--- guile/guile-core/doc/ChangeLog:1.97 Mon Jun 18 12:08:31 2001
+++ guile/guile-core/doc/ChangeLog      Wed Jun 20 15:08:19 2001
@@ -1,3 +1,11 @@
+2001-06-20  Neil Jerram  <address@hidden>
+
+       * 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  <address@hidden>
 
        * srfi-modules.texi (SRFI-1): Completed procedure documentation.
Index: guile/guile-core/doc/extend.texi
diff -u guile/guile-core/doc/extend.texi:1.1 
guile/guile-core/doc/extend.texi:1.2
--- guile/guile-core/doc/extend.texi:1.1        Fri Mar  9 00:21:59 2001
+++ guile/guile-core/doc/extend.texi    Wed Jun 20 15:08:19 2001
@@ -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.
Index: guile/guile-core/doc/gh.texi
diff -u guile/guile-core/doc/gh.texi:1.4 guile/guile-core/doc/gh.texi:1.5
--- guile/guile-core/doc/gh.texi:1.4    Sun Apr 22 07:56:52 2001
+++ guile/guile-core/doc/gh.texi        Wed Jun 20 15:08:19 2001
@@ -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.
address@hidden SCM interpreter
address@hidden 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.
address@hidden gh_ interface
address@hidden libguile interface
-
-If you are @emph{programming with Guile}, you should only use the C
-subroutines described in this manual, which all begin with
address@hidden
-
-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}).
address@hidden Guile - extending
address@hidden extending Guile
address@hidden 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::  
@@ -52,6 +29,57 @@
 * Calling Scheme procedures from C::  
 * Mixing gh and scm APIs::      
 @end menu
+
+
address@hidden GH deprecation
address@hidden 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
address@hidden 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
address@hidden functions, all that is needed is a definition of the
address@hidden 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
address@hidden 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
Index: guile/guile-core/doc/guile.texi
diff -u guile/guile-core/doc/guile.texi:1.10 
guile/guile-core/doc/guile.texi:1.11
--- guile/guile-core/doc/guile.texi:1.10        Wed May 23 10:24:49 2001
+++ guile/guile-core/doc/guile.texi     Wed Jun 20 15:08:19 2001
@@ -80,7 +80,7 @@
 @sp 10
 @comment The title is printed in a large font.
 @title Guile Reference Manual
address@hidden $Id: guile.texi,v 1.10 2001/05/23 17:24:49 mgrabmue Exp $
address@hidden $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 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 @@
 @end iftex
 
 @include extend.texi
address@hidden gh.texi
 @include data-rep.texi
 @include scm.texi
address@hidden gh.texi
 
 @c Appendices
 @iftex