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

[Neil Jerram]

CVSROOT:        /cvs
Module name:    guile
Changes by:     Neil Jerram <address@hidden>    01/06/25 15:27:11

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

Log message:
        * More GH to scm transition documentation.
        * Revise info about GH deprecation following Marius' suggestions.

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/guile/guile-core/doc/ChangeLog.diff?cvsroot=OldCVS&tr1=1.100&tr2=1.101&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/guile/guile-core/doc/extend.texi.diff?cvsroot=OldCVS&tr1=1.2&tr2=1.3&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/guile/guile-core/doc/gh.texi.diff?cvsroot=OldCVS&tr1=1.6&tr2=1.7&r1=text&r2=text

Patches:
Index: guile/guile-core/doc/ChangeLog
diff -u guile/guile-core/doc/ChangeLog:1.100 
guile/guile-core/doc/ChangeLog:1.101
--- guile/guile-core/doc/ChangeLog:1.100        Mon Jun 25 08:08:22 2001
+++ guile/guile-core/doc/ChangeLog      Mon Jun 25 15:27:11 2001
@@ -1,3 +1,10 @@
+2001-06-25  Neil Jerram  <address@hidden>
+
+       * gh.texi (GH deprecation): Remove paragraph about portability.
+
+       * extend.texi (Libguile Intro): Updated following Marius'
+       suggestions.
+
 2001-06-25  Marius Vollmer  <address@hidden>
 
        * Makefile.am (version.texi, version-tutorial.texi): Removed
@@ -8,6 +15,12 @@
        * gh.texi (scm transition summary): New node for summary of how to
        transition from GH to scm interface.
        (GH): Link to new node.
+       (Calling Scheme procedures from C): Remove doc for gh_set_car and
+       gh_set_cdr, which don't actually exist.
+       (Data types and constants defined by gh): Correct
+       SCM_UNSPECIFIED/SCM_UNDEFINED confusion.
+       (Calling Scheme procedures from C): Correct SCM_EOL/SCM_UNDEFINED
+       confusion.
 
 2001-06-20  Neil Jerram  <address@hidden>
 
Index: guile/guile-core/doc/extend.texi
diff -u guile/guile-core/doc/extend.texi:1.2 
guile/guile-core/doc/extend.texi:1.3
--- guile/guile-core/doc/extend.texi:1.2        Wed Jun 20 15:08:19 2001
+++ guile/guile-core/doc/extend.texi    Mon Jun 25 15:27:11 2001
@@ -13,14 +13,32 @@
 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 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.
+The Guile developers believe that clarification of the GH vs. scm
+debate, and the consequent deprecation of the GH interface, are in the
+long term interests of the project.  However it does create an
+unfortunate situation for developers who want to start a project using
+Guile and so read the manual to find out how to proceed.  They will
+discover that the GH interface, although quite well documented, is
+deprecated, but that there is almost no adequate documentation for its
+theoretical replacement, the scm interface.  Moreover, the scm interface
+still has the odd few rough edges which need smoothing down.
+
+Therefore, although deprecated, it is quite OK to continue to use the GH
+interface if you feel uncomfortable with the `scm_' interface as it
+stands today.  By the time that support for GH is dropped, we plan to
+have thoroughly documented the `scm_' interface, and to have enhanced it
+such that conversion from GH to the `scm_' interface will be very
+straightforward, and probably mostly automated.
+
+As far as documentation of the scm interface is concerned, the current
+position is that it is a bit confused, but that 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.6 guile/guile-core/doc/gh.texi:1.7
--- guile/guile-core/doc/gh.texi:1.6    Fri Jun 22 07:23:46 2001
+++ guile/guile-core/doc/gh.texi        Mon Jun 25 15:27:11 2001
@@ -62,25 +62,17 @@
 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
 @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.
+It remains an open question whether a deep kind 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
@@ -127,9 +119,16 @@
 @end defvr
 
 @defvr Constant SCM_UNSPECIFIED
-This is an SCM object which does not correspond to any legal Scheme
-value.  It can be used in C to terminate functions with variable numbers
-of arguments, such as @code{gh_list()}.
+This is a SCM value that is not the same as any legal Scheme value.  It
+is the value that a Scheme function returns when its specification says
+that its return value is unspecified.
address@hidden defvr
+
address@hidden Constant SCM_UNDEFINED
+This is another SCM value that is not the same as any legal Scheme
+value.  It is the value used to mark variables that do not yet have a
+value, and it is also used in C to terminate functions with variable
+numbers of arguments, such as @code{gh_list()}.
 @end defvr
 
 
@@ -600,7 +599,7 @@
 they do is the same as documented in @ref{Standard procedures, R5RS, ,
 r5rs, R5RS}.  But I will point out that when a procedure takes a
 variable number of arguments (such as @code{gh_list}), you should pass
-the constant @var{SCM_EOL} from C to signify the end of the list.
+the constant @var{SCM_UNDEFINED} from C to signify the end of the list.
 
 @deftypefun SCM gh_define (char address@hidden, SCM @var{val})
 Corresponds to the Scheme @code{(define name val)}: it binds a value to
@@ -616,13 +615,6 @@
 @code{scm_listify()}.
 @end deftypefun
 
address@hidden SCM gh_set_car (SCM @var{obj}, SCM @var{val})
address@hidden SCM gh_set_cdr (SCM @var{obj}, SCM @var{val})
-These correspond to the Scheme @code{(set-car! ...)} and @code{(set-cdr!
-...)} procedures.
address@hidden deftypefun
-
-
 @deftypefun SCM gh_car (SCM @var{obj})
 @deftypefunx SCM gh_cdr (SCM @var{obj})
 @dots{}
@@ -858,7 +850,7 @@
 @item @code{SCM_BOOL_F} and @code{SCM_BOOL_T}
 No change.
 
address@hidden @code{SCM_UNSPECIFIED}
address@hidden @code{SCM_UNSPECIFIED} and @code{SCM_UNDEFINED}
 No change.
 
 @item @code{gh_enter}
@@ -939,16 +931,32 @@
 Use @code{SCM_NFALSEP} instead.
 
 @item @code{gh_scm2int}
-Use @code{scm_num2int} instead.
+Replace @code{gh_scm2int (@var{obj})} by
address@hidden
+scm_num2int (@var{obj}, SCM_ARG1, @var{str})
address@hidden example
+where @var{str} is a C string that describes the context of the call.
 
 @item @code{gh_scm2ulong}
-Use @code{scm_num2ulong} instead.
+Replace @code{gh_scm2ulong (@var{obj})} by
address@hidden
+scm_num2ulong (@var{obj}, SCM_ARG1, @var{str})
address@hidden example
+where @var{str} is a C string that describes the context of the call.
 
 @item @code{gh_scm2long}
-Use @code{scm_num2long} instead.
+Replace @code{gh_scm2long (@var{obj})} by
address@hidden
+scm_num2long (@var{obj}, SCM_ARG1, @var{str})
address@hidden example
+where @var{str} is a C string that describes the context of the call.
 
 @item @code{gh_scm2double}
-Use @code{scm_num2dbl} instead.
+Replace @code{gh_scm2double (@var{obj})} by
address@hidden
+scm_num2dbl (@var{obj}, @var{str})
address@hidden example
+where @var{str} is a C string that describes the context of the call.
 
 @item @code{gh_scm2char}
 Use the @code{SCM_CHAR} macro instead, but note that @code{SCM_CHAR}
@@ -1048,7 +1056,96 @@
 SCM_NFALSEP (scm_exact_p (@var{obj}))
 @end example
 
address@hidden @code{gh_eq_p}
+Use the @code{SCM_EQ_P} macro instead, or replace @code{gh_eq_p
+(@var{x}, @var{y})} by
address@hidden
+SCM_NFALSEP (scm_eq_p (@var{x}, @var{y}))
address@hidden example
+
address@hidden @code{gh_eqv_p}
+Replace @code{gh_eqv_p (@var{x}, @var{y})} by
address@hidden
+SCM_NFALSEP (scm_eqv_p (@var{x}, @var{y}))
address@hidden example
+
address@hidden @code{gh_equal_p}
+Replace @code{gh_equal_p (@var{x}, @var{y})} by
address@hidden
+SCM_NFALSEP (scm_equal_p (@var{x}, @var{y}))
address@hidden example
+
address@hidden @code{gh_string_equal_p}
+Replace @code{gh_string_equal_p (@var{x}, @var{y})} by
address@hidden
+SCM_NFALSEP (scm_string_equal_p (@var{x}, @var{y}))
address@hidden example
+
address@hidden @code{gh_null_p}
+Use the @code{SCM_NULLP} macro instead, or replace @code{gh_null_p
+(@var{obj})} by
address@hidden
+SCM_NFALSEP (scm_null_p (@var{obj}))
address@hidden example
+
address@hidden @code{gh_cons}
+Use @code{scm_cons} instead.
+
address@hidden @code{gh_car} and @code{gh_cdr}
+Use the @code{SCM_CAR} and @code{SCM_CDR} macros instead.
+
address@hidden @code{gh_cxxr} and @code{gh_cxxxr}
+(Where each x is either @samp{a} or @samp{d}.)  Use the corresponding
address@hidden or @code{SCM_CXXXR} macro instead.
+
address@hidden @code{gh_set_car_x} and @code{gh_set_cdr_x}
+Use @code{scm_set_car_x} and @code{scm_set_cdr_x} instead.
+
 @item @code{gh_list}
 Use @code{scm_listify} instead.
+
address@hidden @code{gh_length}
+Replace @code{gh_length (@var{lst})} by
address@hidden
+scm_num2ulong (scm_length (@var{lst}), SCM_ARG1, @var{str})
address@hidden example
+where @var{str} is a C string that describes the context of the call.
+
address@hidden @code{gh_append}
+Use @code{scm_append} instead.
+
address@hidden @code{gh_append2}, @code{gh_append3}, @code{gh_append4}
+Replace @address@hidden (@var{l1}, @dots{}, @var{lN})} by
address@hidden
+scm_append (scm_listify (@var{l1}, @dots{}, @var{lN}, SCM_UNDEFINED))
address@hidden example
+
address@hidden @code{gh_reverse}
+Use @code{scm_reverse} instead.
+
address@hidden @code{gh_list_tail} and @code{gh_list_ref}
+Use @code{scm_list_tail} and @code{scm_list_ref} instead.
+
address@hidden @code{gh_memq}, @code{gh_memv} and @code{gh_member}
+Use @code{scm_memq}, @code{scm_memv} and @code{scm_member} instead.
+
address@hidden @code{gh_assq}, @code{gh_assv} and @code{gh_assoc}
+Use @code{scm_assq}, @code{scm_assv} and @code{scm_assoc} instead.
+
address@hidden @code{gh_make_vector}
+Use @code{scm_make_vector} instead.
+
address@hidden @code{gh_vector} or @code{gh_list_to_vector}
+Use @code{scm_vector} instead.
+
address@hidden @code{gh_vector_ref} and @code{gh_vector_set_x}
+Use @code{scm_vector_ref} and @code{scm_vector_set_x} instead.
+
address@hidden @code{gh_vector_length}
+Use the @code{SCM_VECTOR_LENGTH} macro instead.
+
address@hidden @code{gh_apply}
+Use @code{scm_apply} instead, but note that @code{scm_apply} takes an
+additional third argument that you should set to @code{SCM_EOL}.
 
 @end table