Manual updates.

doc/ref/ChangeLog

@@ -1,3 +1,14 @@
+2002-03-16  Neil Jerram  <neil@ossau.uklinux.net>
+
+	* scheme-utility.texi (Hooks): Further updates.  New material on
+	GC hooks.
+	
+	* scheme-evaluation.texi (Fly Evaluation): Note disappearance of
+	eval2 and read-and-eval!.
+
+	* deprecated.texi (Deprecated): Remove docs about previously
+	deprecated items that have now been removed.
+
 2002-03-15  Thien-Thi Nguyen  <ttn@giblet.glug.org>
 
 	* tools.texi (guile-1.4 guile-snarf): Remove this node.

doc/ref/deprecated.texi

@@ -1,138 +1,3 @@
 @page
 @node Deprecated
 @chapter Deprecated
-
-@menu
-* Shared And Read Only Strings::
-@end menu
-
-
-@node Shared And Read Only Strings
-@section Shared And Read Only Strings
-
-The procedures described in this section are deprecated because explicit
-shared substrings are planned to disappear from Guile.
-
-Instead, all strings will be implemented using sharing internally,
-combined with a copy-on-write strategy.  Once internal string sharing
-and copy-on-write have been implemented, it will be unnecessary to
-preserve the concept of read only strings.
-
-@menu
-* Shared Substrings::           Strings which share memory with each other.
-* Read Only Strings::           Treating certain non-strings as strings.
-@end menu
-
-
-@node Shared Substrings
-@subsection Shared Substrings
-
-Whenever you extract a substring using @code{substring}, the Scheme
-interpreter allocates a new string and copies data from the old string.
-This is expensive, but @code{substring} is so convenient for
-manipulating text that programmers use it often.
-
-Guile Scheme provides the concept of the @dfn{shared substring} to
-improve performance of many substring-related operations.  A shared
-substring is an object that mostly behaves just like an ordinary
-substring, except that it actually shares storage space with its parent
-string.
-
-@deffn {Scheme Procedure} make-shared-substring str [start [end]]
-Return a shared substring of @var{str}.  The arguments are the
-same as for the @code{substring} function: the shared substring
-returned includes all of the text from @var{str} between
-indexes @var{start} (inclusive) and @var{end} (exclusive).  If
-@var{end} is omitted, it defaults to the end of @var{str}.  The
-shared substring returned by @code{make-shared-substring}
-occupies the same storage space as @var{str}.
-@end deffn
-
-Example:
-
-@example
-(define foo "the quick brown fox")
-(define bar (make-shared-substring some-string 4 9))
-
-foo => "t h e   q u i c k   b r o w n   f o x"
-bar =========> |---------|
-@end example
-
-The shared substring @var{bar} is not given its own storage space.
-Instead, the Guile interpreter notes internally that @var{bar} points to
-a portion of the memory allocated to @var{foo}.  However, @var{bar}
-behaves like an ordinary string in most respects: it may be used with
-string primitives like @code{string-length}, @code{string-ref},
-@code{string=?}.  Guile makes the necessary translation between indices
-of @var{bar} and indices of @var{foo} automatically.
-
-@example
-(string-length? bar) @result{} 5	; bar only extends from indices 4 to 9
-(string-ref bar 3)  @result{} #\c	; same as (string-ref foo 7)
-(make-shared-substring bar 2)
-  @result{} "ick"			; can even make a shared substring!
-@end example
-
-Because creating a shared substring does not require allocating new
-storage from the heap, it is a very fast operation.  However, because it
-shares memory with its parent string, a change to the contents of the
-parent string will implicitly change the contents of its shared
-substrings.
-
-@example
-(string-set! foo 7 #\r)
-bar @result{} "quirk"
-@end example
-
-Guile considers shared substrings to be immutable.  This is because
-programmers might not always be aware that a given string is really a
-shared substring, and might innocently try to mutate it without
-realizing that the change would affect its parent string.  (We are
-currently considering a "copy-on-write" strategy that would permit
-modifying shared substrings without affecting the parent string.)
-
-In general, shared substrings are useful in circumstances where it is
-important to divide a string into smaller portions, but you do not
-expect to change the contents of any of the strings involved.
-
-
-@node Read Only Strings
-@subsection Read Only Strings
-
-In previous versions of Guile, there was the idea that some string-based
-primitives such as @code{string-append} could equally accept symbols as
-arguments.  For example, one could write
-
-@lisp
-(string-append '/home/ 'vigilia)
-@end lisp
-
-@noindent
-and get @code{"/home/vigilia"} as the result.  The term @dfn{read only
-string} was adopted to describe the argument type expected by such
-primitives.
-
-This idea has now been removed.  The predicate @code{read-only-string?}
-still exists, but deprecated, and is equivalent to
-
-@lisp
-(lambda (x) (or (string? x) (symbol? x)))
-@end lisp
-
-@noindent
-But no Guile primitives now use @code{read-only-string?} to validate
-their arguments.
-
-String-based primitives such as @code{string-append}
-now require strings:
-
-@lisp
-(string-append '/home/ 'vigilia)
-@result{}
-ERROR: Wrong type argument (expecting STRINGP): /home/
-@end lisp
-
-@deffn {Scheme Procedure} read-only-string? obj
-Return @code{#t} if @var{obj} is either a string or a symbol,
-otherwise return @code{#f}.
-@end deffn

doc/ref/guile.texi

@@ -83,7 +83,7 @@
 
 @dircategory The Algorithmic Language Scheme
 @direntry
-* Guile Reference: (guile).  The Guile reference manual.
+* Guile Reference: (guile).     The Guile reference manual.
 @end direntry
 
 @setchapternewpage off
@@ -121,7 +121,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.14 2002-03-15 14:03:53 ossau Exp $
+@subtitle $Id: guile.texi,v 1.15 2002-03-16 13:51:03 ossau Exp $
 @subtitle For use with Guile @value{VERSION}
 
 @c AUTHORS

doc/ref/intro.texi

@@ -1,6 +1,3 @@
-@c $Id: intro.texi,v 1.8 2002-01-08 08:29:00 ttn Exp $
-
-
 @page
 @node What is Guile?
 @chapter What is Guile?

doc/ref/posix.texi

@@ -280,6 +280,7 @@ The return value is unspecified.
 @end deffn
 
 @deffn {Scheme Procedure} unread-char char [port]
+@deffnx {C Function} scm_unread_char (char, port)
 Place @var{char} in @var{port} so that it will be read by the
 next read operation.  If called multiple times, the unread characters
 will be read again in last-in first-out order.  If @var{port} is
@@ -395,14 +396,7 @@ the port was opened, since modes such as "append" which are
 used only during port creation are not retained.
 @end deffn
 
-@deffn {Scheme Procedure} close-all-ports-except . ports
-[DEPRECATED] Close all open file ports used by the interpreter
-except for those supplied as arguments.  This procedure
-was intended to be used before an exec call to close file descriptors
-which are not needed in the new process.  However it has the
-undesirable side-effect of flushing buffers, so it's deprecated.
-Use port-for-each instead.
-@end deffn
+@vgone{close-all-ports-except,1.6}
 
 @deffn {Scheme Procedure} port-for-each proc
 @deffnx {C Function} scm_port_for_each (proc)
@@ -2239,7 +2233,7 @@ number.
 @deffnx {C Function} scm_getsockname (sock)
 Return the address of @var{sock}, in the same form as the
 object returned by @code{accept}.  On many systems the address
-of a socket in the @code{AF_FILE} name space cannot be read.
+of a socket in the @code{AF_FILE} namespace cannot be read.
 @end deffn
 
 @deffn {Scheme Procedure} getpeername sock
@@ -2247,7 +2241,7 @@ of a socket in the @code{AF_FILE} name space cannot be read.
 Return the address that @var{sock}
 is connected to, in the same form as the object returned by
 @code{accept}.  On many systems the address of a socket in the
-@code{AF_FILE} name space cannot be read.
+@code{AF_FILE} namespace cannot be read.
 @end deffn
 
 @deffn {Scheme Procedure} recv! sock buf [flags]

doc/ref/scheme-evaluation.texi

@@ -235,6 +235,9 @@ Evaluate @var{exp} in the top-level environment specified by
 the current module.
 @end deffn
 
+@vgone{eval2,1.6}
+@vgone{read-and-eval!,1.6}
+
 
 @node Loading
 @section Loading Scheme Code from File

doc/ref/scheme-utility.texi

@@ -572,25 +572,28 @@ code needs to do, you may prefer to use this interface.
 To create a C hook, you should allocate storage for a structure of type
 @code{scm_t_c_hook} and then initialize it using @code{scm_c_hook_init}.
 
-@deffn {C Type} scm_t_c_hook
+@deftp {C Type} scm_t_c_hook
 Data type for a C hook.  The internals of this type should be treated as
 opaque.
-@end deffn
+@end deftp
 
-@deffn {C Enum} scm_t_c_hook_type
+@deftp {C Enum} scm_t_c_hook_type
 Enumeration of possible hook types, which are:
 
 @table @code
 @item SCM_C_HOOK_NORMAL
+@vindex SCM_C_HOOK_NORMAL
 Type of hook for which all the registered functions will always be called.
 @item SCM_C_HOOK_OR
+@vindex SCM_C_HOOK_OR
 Type of hook for which the sequence of registered functions will be
 called only until one of them returns C true (a non-NULL pointer).
 @item SCM_C_HOOK_AND
+@vindex SCM_C_HOOK_AND
 Type of hook for which the sequence of registered functions will be
 called only until one of them returns C false (a NULL pointer).
 @end table
-@end deffn
+@end deftp
 
 @deftypefn {C Function} void scm_c_hook_init (scm_t_c_hook *hook, void *hook_data, scm_t_c_hook_type type)
 Initialize the C hook at memory pointed to by @var{hook}.  @var{type}
@@ -618,10 +621,10 @@ The call closure data specified by the @code{scm_c_hook_run} call that
 runs the hook.
 @end table
 
-@deffn {C Type} scm_t_c_hook_function
+@deftp {C Type} scm_t_c_hook_function
 Function type for a C hook function: takes three @code{void *}
 parameters and returns a @code{void *} result.
-@end deffn
+@end deftp
 
 @deftypefn {C Function} void scm_c_hook_add (scm_t_c_hook *hook, scm_t_c_hook_function func, void *func_data, int appendp)
 Add function @var{func}, with function closure data @var{func_data}, to
@@ -654,13 +657,73 @@ function to be called.
 @node Guile Hooks
 @subsection Hooks Provided by Guile
 
-@table @code
-@item scm_before_gc_c_hook
-@item scm_before_mark_c_hook
-@item scm_before_sweep_c_hook
-@item scm_after_sweep_c_hook
-@item scm_after_gc_c_hook
-@end table
+@menu
+* GC Hooks::                    Garbage collection hooks.
+* REPL Hooks::                  Hooks into the Guile REPL.
+@end menu
+
+
+@node GC Hooks
+@subsubsection Hooks for Garbage Collection
+
+Whenever Guile performs a garbage collection, it calls the following
+hooks in the order shown.
+
+@defvr {C Hook} scm_before_gc_c_hook
+C hook called at the very start of a garbage collection, after setting
+@code{scm_gc_running_p} to 1, but before entering the GC critical
+section.
+
+If garbage collection is blocked because @code{scm_block_gc} is
+non-zero, GC exits early soon after calling this hook, and no further
+hooks will be called.
+@end defvr
+
+@defvr {C Hook} scm_before_mark_c_hook
+C hook called before beginning the mark phase of garbage collection,
+after the GC thread has entered a critical section.
+@end defvr
+
+@defvr {C Hook} scm_before_sweep_c_hook
+C hook called before beginning the sweep phase of garbage collection.
+This is the same as at the end of the mark phase, since nothing else
+happens between marking and sweeping.
+@end defvr
+
+@defvr {C Hook} scm_after_sweep_c_hook
+C hook called after the end of the sweep phase of garbage collection,
+but while the GC thread is still inside its critical section.
+@end defvr
+
+@defvr {C Hook} scm_after_gc_c_hook
+C hook called at the very end of a garbage collection, after the GC
+thread has left its critical section.
+@end defvr
+
+@defvr {Scheme Hook} after-gc-hook
+@vindex scm_after_gc_hook
+Scheme hook with arity 0.  This hook is run asynchronously
+(@pxref{Asyncs}) soon after the GC has completed and any other events
+that were deferred during garbage collection have been processed.  (Also
+accessible from C with the name @code{scm_after_gc_hook}.)
+@end defvr
+
+All the C hooks listed here have type @code{SCM_C_HOOK_NORMAL}, are
+initialized with hook closure data NULL, are are invoked by
+@code{scm_c_hook_run} with call closure data NULL.
+
+@cindex guardians, testing for GC'd objects
+The Scheme hook @code{after-gc-hook} is particularly useful in
+conjunction with guardians (@pxref{Guardians}).  Typically, if you are
+using a guardian, you want to call the guardian after garbage collection
+to see if any of the objects added to the guardian have been collected.
+By adding a thunk that performs this call to @code{after-gc-hook}, you
+can ensure that your guardian is tested after every garbage collection
+cycle.
+
+
+@node REPL Hooks
+@subsubsection Hooks into the Guile REPL
 
 
 @c Local Variables:

doc/ref/scripts.texi

@@ -101,7 +101,7 @@ slow down execution.  By default, the debugging evaluator is only used
 when entering an interactive session.  When executing a script with
 @code{-s} or @code{-c}, the normal, faster evaluator is used by default.
 
-@vnew{1.6}
+@vnew{1.8}
 @item --no-debug
 Do not use the debugging evaluator, even when entering an interactive
 session.