Talk about new init functions.

diff --git a/doc/ref/libguile-linking.texi b/doc/ref/libguile-linking.texi
index 6fb667c..f28de6f 100644 (file)
--- a/doc/ref/libguile-linking.texi
+++ b/doc/ref/libguile-linking.texi
@@ -35,19 +35,20 @@ use the obtained information in the Makefile.
 @node Guile Initialization Functions
 @subsection Guile Initialization Functions
 
-To initialize Guile, you can use one of two functions.  The first,
-@code{scm_boot_guile}, is the most portable way to initialize Guile.  It
-should be used whenever you have control over the main function of your
-program because it never returns.  The second function,
-@code{scm_init_guile}, does return and can thus be used in more
-situations.  However, @code{scm_init_guile} is not as widely available
-as @code{scm_boot_guile} because it needs to rely on non-portable code
-to find the stack bounds.  When Guile does not know how to find these
-bounds on your system, it will not provide @code{scm_init_guile}.
-
-When you can tolerate the limits of @code{scm_boot_guile}, you should
-use it in favor of @code{scm_init_guile} since that will make your
-program more portable.
+To initialize Guile, you can use one of several functions.  The first,
+@code{scm_with_guile}, is the most portable way to initialize Guile.  It
+will initialize Guile when necessary and then call a function that you
+can specify.  Multiple threads can call @code{scm_with_guile}
+concurrently and it can also be called more than once in a given thread.
+The global state of Guile will survive from one call of
+@code{scm_with_guile} to the next.  Your function is called from within
+@code{scm_with_guile} since the garbage collector of Guile needs to know
+where the stack of each thread is.
+
+A second function, @code{scm_init_guile}, initializes Guile for the
+current thread.  When it returns, you can use the Guile API in the
+current thread.  This function employs some non-portable magic to learn
+about stack bounds and might thus not be available on all platforms.
 
 One common way to use Guile is to write a set of C functions which
 perform some useful task, make them callable from Scheme, and then link
@@ -58,7 +59,7 @@ application --- a special-purpose scripting language.
 In this situation, the application should probably process its
 command-line arguments in the same manner as the stock Guile
 interpreter.  To make that straightforward, Guile provides the
-@code{scm_shell} function.
+@code{scm_boot_guile} and @code{scm_shell} function.
 
 @node A Sample Guile Main Program
 @subsection A Sample Guile Main Program