Prefer foreign objects over smobs in manual

* doc/ref/api-memory.texi (Memory Blocks): Recommend against
  scm_gc_free.  Refer to foreign objects instead of smobs.  Remove
  discussion of scm_must_malloc et al.

* doc/ref/guile.texi (API Reference): Rename SMOB menu item.

* doc/ref/libguile-snarf.texi (Function Snarfing): Update example to not
  refer to smobs.
* doc/ref/tools.texi (How guile-snarf works): Likewise.

4 files changed, 24 insertions, 84 deletions

diff --git a/doc/ref/api-memory.texi b/doc/ref/api-memory.texi
index 657f745b4..099d80678 100644
--- a/doc/ref/api-memory.texi
+++ b/doc/ref/api-memory.texi
@@ -112,15 +112,16 @@ functions for dynamic memory allocation that are integrated into the
 garbage collector and the error reporting system.
 
 Memory blocks that are associated with Scheme objects (for example a
-smob) should be allocated with @code{scm_gc_malloc} or
+foreign object) should be allocated with @code{scm_gc_malloc} or
 @code{scm_gc_malloc_pointerless}.  These two functions will either
 return a valid pointer or signal an error.  Memory blocks allocated this
-way can be freed with @code{scm_gc_free}; however, this is not strictly
-needed: memory allocated with @code{scm_gc_malloc} or
-@code{scm_gc_malloc_pointerless} is automatically reclaimed when the
-garbage collector no longer sees any live reference to it@footnote{In
-Guile up to version 1.8, memory allocated with @code{scm_gc_malloc}
-@emph{had} to be freed with @code{scm_gc_free}.}.
+way may be released explicitly; however, this is not strictly needed,
+and we recommend @emph{not} calling @code{scm_gc_free}.  All memory
+allocated with @code{scm_gc_malloc} or @code{scm_gc_malloc_pointerless}
+is automatically reclaimed when the garbage collector no longer sees any
+live reference to it@footnote{In Guile up to version 1.8, memory
+allocated with @code{scm_gc_malloc} @emph{had} to be freed with
+@code{scm_gc_free}.}.
 
 Memory allocated with @code{scm_gc_malloc} is scanned for live pointers.
 This means that if @code{scm_gc_malloc}-allocated memory contains a
@@ -204,7 +205,9 @@ size of a reallocated memory block as well.  See below for a motivation.
 
 @deftypefn {C Function} void scm_gc_free (void *@var{mem}, size_t @var{size}, const char *@var{what})
 Explicitly free the memory block pointed to by @var{mem}, which was
-previously allocated by one of the above @code{scm_gc} functions.
+previously allocated by one of the above @code{scm_gc} functions.  This
+function is almost always unnecessary, except for codebases that still
+need to compile on Guile 1.8.
 
 Note that you need to explicitly pass the @var{size} parameter.  This
 is done since it should normally be easy to provide this parameter
@@ -225,7 +228,7 @@ often (as appropriate).
 
 It is especially important to call this function when large unmanaged
 allocations, like images, may be freed by small Scheme allocations, like
-SMOBs.
+foreign objects.
 @end deftypefn
 
 
@@ -248,69 +251,6 @@ preprocessor macro was defined when Guile was compiled.
 @end deffn
 
 
-@subsubsection Upgrading from scm_must_malloc et al.
-
-Version 1.6 of Guile and earlier did not have the functions from the
-previous section.  In their place, it had the functions
-@code{scm_must_malloc}, @code{scm_must_realloc} and
-@code{scm_must_free}.  This section explains why we want you to stop
-using them, and how to do this.
-
-@findex scm_must_malloc
-@findex scm_must_realloc
-@findex scm_must_calloc
-@findex scm_must_free
-The functions @code{scm_must_malloc} and @code{scm_must_realloc}
-behaved like @code{scm_gc_malloc} and @code{scm_gc_realloc} do now,
-respectively.  They would inform the GC about the newly allocated
-memory via the internal equivalent of
-@code{scm_gc_register_allocation}.  However,
-@code{scm_must_free} did not unregister the memory it was about to
-free.  The usual way to unregister memory was to return its size from
-a smob free function.
-
-This disconnectedness of the actual freeing of memory and reporting
-this to the GC proved to be bad in practice.  It was easy to make
-mistakes and report the wrong size because allocating and freeing was
-not done with symmetric code, and because it is cumbersome to compute
-the total size of nested data structures that were freed with multiple
-calls to @code{scm_must_free}.  Additionally, there was no equivalent
-to @code{scm_malloc}, and it was tempting to just use
-@code{scm_must_malloc} and never to tell the GC that the memory has
-been freed.
-
-The effect was that the internal statistics kept by the GC drifted out
-of sync with reality and could even overflow in long running programs.
-When this happened, the result was a dramatic increase in (senseless)
-GC activity which would effectively stop the program dead.
-
-@findex scm_done_malloc
-@findex scm_done_free
-The functions @code{scm_done_malloc} and @code{scm_done_free} were
-introduced to help restore balance to the force, but existing bugs did
-not magically disappear, of course.
-
-Therefore we decided to force everybody to review their code by
-deprecating the existing functions and introducing new ones in their
-place that are hopefully easier to use correctly.
-
-For every use of @code{scm_must_malloc} you need to decide whether to
-use @code{scm_malloc} or @code{scm_gc_malloc} in its place.  When the
-memory block is not part of a smob or some other Scheme object whose
-lifetime is ultimately managed by the garbage collector, use
-@code{scm_malloc} and @code{free}.  When it is part of a smob, use
-@code{scm_gc_malloc} and change the smob free function to use
-@code{scm_gc_free} instead of @code{scm_must_free} or @code{free} and
-make it return zero.
-
-The important thing is to always pair @code{scm_malloc} with
-@code{free}; and to always pair @code{scm_gc_malloc} with
-@code{scm_gc_free}.
-
-The same reasoning applies to @code{scm_must_realloc} and
-@code{scm_realloc} versus @code{scm_gc_realloc}.
-
-
 @node Weak References
 @subsection Weak References
 
diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi
index a06e49558..5b368df83 100644
--- a/doc/ref/guile.texi
+++ b/doc/ref/guile.texi
@@ -300,7 +300,7 @@ available through both Scheme and C interfaces.
 * Simple Data Types::           Numbers, strings, booleans and so on.
 * Compound Data Types::         Data types for holding other data.
 * Foreign Objects::             Defining new data types in C.
-* Smobs::                       Legacy version of foreign objects.
+* Smobs::                       Use foreign objects instead.
 * Procedures::                  Procedures.
 * Macros::                      Extending the syntax of Scheme.
 * Utility Functions::           General utility functions.
diff --git a/doc/ref/libguile-snarf.texi b/doc/ref/libguile-snarf.texi
index c70727f2d..9b0e42fa3 100644
--- a/doc/ref/libguile-snarf.texi
+++ b/doc/ref/libguile-snarf.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
-@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2012
+@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2012, 2014
 @c   Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
@@ -61,10 +61,10 @@ implemented by the C function @code{clear_image}:
 #include <libguile.h>
 
 SCM_DEFINE (clear_image, "clear-image", 1, 0, 0,
-            (SCM image_smob),
+            (SCM image),
             "Clear the image.")
 @{
-  /* C code to clear the image in @code{image_smob}... */
+  /* C code to clear the image in @code{image}... */
 @}
 
 void
@@ -78,9 +78,9 @@ init_image_type ()
 The @code{SCM_DEFINE} declaration says that the C function
 @code{clear_image} implements a Scheme function called
 @code{clear-image}, which takes one required argument (of type
-@code{SCM} and named @code{image_smob}), no optional arguments, and no
-rest argument.  The string @code{"Clear the image."} provides a short
-help text for the function, it is called a @dfn{docstring}.
+@code{SCM} and named @code{image}), no optional arguments, and no rest
+argument.  The string @code{"Clear the image."} provides a short help
+text for the function, it is called a @dfn{docstring}.
 
 @code{SCM_DEFINE} macro also defines a static array of characters
 initialized to the Scheme name of the function.  In this case,
diff --git a/doc/ref/tools.texi b/doc/ref/tools.texi
index 2c624936f..e962a86ab 100644
--- a/doc/ref/tools.texi
+++ b/doc/ref/tools.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
-@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2011
+@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2011, 2014
 @c   Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
@@ -112,11 +112,11 @@ For example, here is how you might define a new subr called
 #include <libguile.h>
 
 SCM_DEFINE (clear_image, "clear-image", 1, 0, 0,
-            (SCM image_smob),
+            (SCM image),
             "Clear the image.")
 #define FUNC_NAME s_clear_image
 @{
-  /* C code to clear the image in @code{image_smob}... */
+  /* C code to clear the image in @code{image}... */
 @}
 #undef FUNC_NAME
 
@@ -131,8 +131,8 @@ init_image_type ()
 The @code{SCM_DEFINE} declaration says that the C function
 @code{clear_image} implements a Scheme subr called @code{clear-image},
 which takes one required argument (of type @code{SCM} and named
-@code{image_smob}), no optional arguments, and no rest argument.
-@xref{Doc Snarfing}, for info on the docstring.
+@code{image}), no optional arguments, and no rest argument.  @xref{Doc
+Snarfing}, for info on the docstring.
 
 This works in concert with @code{FUNC_NAME} to also define a static
 array of characters named @code{s_clear_image}, initialized to the