Manual updates.

doc/maint/ChangeLog

@@ -1,3 +1,7 @@
+2002-03-15  Neil Jerram  <neil@ossau.uklinux.net>
+
+	* guile.texi: Replaced by regenerated libguile version.
+
 2002-03-12  Neil Jerram  <neil@ossau.uklinux.net>
 
 	* guile.texi: Replaced by regenerated libguile version.

doc/ref/ChangeLog

@@ -1,3 +1,17 @@
+2002-03-15  Neil Jerram  <neil@ossau.uklinux.net>
+
+	* scheme-utility.texi (Object Properties): Revamp documentation on
+	object properties.
+
+	* scheme-memory.texi (Weak References): Update reference to Object
+	Properties node.
+
+	* guile.texi: Add macros for describing version information.
+
+	* scheme-data.texi, scheme-debug.texi, scheme-io.texi,
+	scheme-procedures.texi: Automatic updates from snarfed libguile
+	docstrings.
+
 2002-03-13  Thien-Thi Nguyen  <ttn@giblet.glug.org>
 
 	* Makefile.am (guile_toc.html): Look for guile.texi in $(srcdir).

doc/ref/guile.texi

@@ -50,13 +50,40 @@
 
 @include version.texi
 
+@c Macros for describing version information.  I've initially defined
+@c all of these to expand to nothing, but they could perhaps be made to
+@c expand to something like "New in Guile 45!" in future.
+
+@c vnew - indicates the Guile version in which item first appeared.
+@macro vnew{VERSION}
+@end macro
+
+@c vdeprecated - indicates that the item has been deprecated, and the
+@c Guile version in which the deprecation started.
+@macro vdeprecated{VERSION}
+@end macro
+
+@c vgone - a way of tracking items that are no longer here.  In this
+@c case, VERSION is the last Guile version in which the item was present.
+@macro vgone{WHAT, VERSION}
+@end macro
+
+@c vchanged - indicates the Guile version in which item's behaviour
+@c significantly changed.
+@macro vchanged{VERSION}
+@end macro
+
+@c vnote - catchall for any additional notes.
+@macro vnote{NOTE}
+@end macro
+
 @c @iftex
 @c @cropmarks
 @c @end iftex
 
 @dircategory The Algorithmic Language Scheme
 @direntry
-* Guile Reference: (guile).     The Guile reference manual.
+* Guile Reference: (guile).  The Guile reference manual.
 @end direntry
 
 @setchapternewpage off
@@ -94,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.13 2002-03-08 21:23:36 ttn Exp $
+@subtitle $Id: guile.texi,v 1.14 2002-03-15 14:03:53 ossau Exp $
 @subtitle For use with Guile @value{VERSION}
 
 @c AUTHORS

doc/ref/new-docstrings.texi

@@ -321,7 +321,7 @@ Change the signature of export environment @var{env}.
 @deffnx {C Function} scm_sys_compute_slots (class)
 Return a list consisting of the names of all slots belonging to
 class @var{class}, i. e. the slots of @var{class} and of all of
-its super-classes.
+its superclasses.
 @end deffn
 
 @deffn {Scheme Procedure} get-keyword key l default_value
@@ -532,7 +532,7 @@ Return the direct slots of the class @var{obj}.
 
 @deffn {Scheme Procedure} class-direct-supers obj
 @deffnx {C Function} scm_class_direct_supers (obj)
-Return the direct super-classes of the class @var{obj}.
+Return the direct superclasses of the class @var{obj}.
 @end deffn
 
 @deffn {Scheme Procedure} class-name obj

doc/ref/scheme-data.texi

@@ -339,7 +339,7 @@ if @var{obj} is an integer number or a rational number.
 @deffn {Scheme Procedure} rational? x
 @deffnx {C Function} scm_real_p (x)
 Return @code{#t} if @var{x} is a rational number, @code{#f}
-else.  Note that the set of integer values forms a subset of
+otherwise.  Note that the set of integer values forms a subset of
 the set of rational numbers, i. e. the predicate will also be
 fulfilled if @var{x} is an integer number.  Real numbers
 will also satisfy this predicate, because of their limited
@@ -379,7 +379,7 @@ properties of inexactness and limited precision as single real numbers.
 @deffn {Scheme Procedure} complex? x
 @deffnx {C Function} scm_number_p (x)
 Return @code{#t} if @var{x} is a complex number, @code{#f}
-else.  Note that the sets of real, rational and integer
+otherwise.  Note that the sets of real, rational and integer
 values form subsets of the set of complex numbers, i. e. the
 predicate will also be fulfilled if @var{x} is a real,
 rational or integer number.
@@ -1443,7 +1443,7 @@ fulfills some specified property.
 @rnindex string?
 @deffn {Scheme Procedure} string? obj
 @deffnx {C Function} scm_string_p (obj)
-Return @code{#t} iff @var{obj} is a string, else @code{#f}.
+Return @code{#t} if @var{obj} is a string, else @code{#f}.
 @end deffn
 
 @deffn {Scheme Procedure} string-null? str

doc/ref/scheme-debug.texi

@@ -51,7 +51,7 @@ allocated.
 @deffnx {C Function} scm_debug_options (setting)
 Option interface for the debug options. Instead of using
 this procedure directly, use the procedures @code{debug-enable},
-@code{debug-disable}, @code{debug-set!} and @var{debug-options}.
+@code{debug-disable}, @code{debug-set!} and @code{debug-options}.
 @end deffn
 
 @deffn {Scheme Procedure} with-traps thunk

doc/ref/scheme-io.texi

@@ -890,7 +890,7 @@ always returns the end-of-file object when read from.
 @deffn {Scheme Procedure} %make-void-port mode
 @deffnx {C Function} scm_sys_make_void_port (mode)
 Create and return a new void port.  A void port acts like
-/dev/null.  The @var{mode} argument
+@file{/dev/null}.  The @var{mode} argument
 specifies the input/output modes for this port: see the
 documentation for @code{open-file} in @ref{File Ports}.
 @end deffn

doc/ref/scheme-memory.texi

@@ -199,8 +199,8 @@ as soon as the value is no longer in use. Entries in a doubly weak hash
 disappear when either the key or the value are not used anywhere else
 anymore.
 
-Property lists offer the same kind of functionality as weak key hashes
-in many situations. (@pxref{Property Lists})
+Object properties offer the same kind of functionality as weak key
+hashes in many situations. (@pxref{Object Properties})
 
 Here's an example (a little bit strained perhaps, but one of the
 examples is actually used in Guile):

doc/ref/scheme-procedures.texi

@@ -738,9 +738,7 @@ environment.
 Return a @dfn{macro} which, when a symbol defined to this value
 appears as the first symbol in an expression, evaluates the
 result of applying @var{code} to the expression and the
-environment.  The value returned from @var{code} which has been
-passed to @code{procedure->memoizing-macro} replaces the form
-passed to @var{code}.  For example:
+environment.  For example:
 
 @lisp
 (define trace

doc/ref/scheme-utility.texi

@@ -10,8 +10,7 @@ applications, they are collected in a @dfn{utility} chapter.
 
 @menu
 * Equality::                    When are two values `the same'?
-* Property Lists::              Managing meta-information about Scheme objects.
-* Primitive Properties::        A modern interface to object properties.
+* Object Properties::           A modern interface to object properties.
 * Sorting::                     Sort utility procedures.
 * Copying::                     Copying deep structures.
 * General Conversion::          Converting objects to strings.
@@ -75,48 +74,78 @@ terminate if its arguments are circular data structures.
 @end deffn
 
 
-@node Property Lists
-@section Property Lists
+@node Object Properties
+@section Object Properties
 
-Every object in the system can have a @dfn{property list} that may
-be used for information about that object.  For example, a
-function may have a property list that includes information about
-the source file in which it is defined.
+It's often useful to associate a piece of additional information with a
+Scheme object even though that object does not have a dedicated slot
+available in which the additional information could be stored.  Object
+properties allow you to do just that.
 
-Property lists are implemented as assq lists (@pxref{Association Lists}).
+An object property is most commonly used to associate one kind of
+additional information with each instance of a class of similar Scheme
+objects.  For example, all procedures have a `name' property, which
+stores the name of the variable in which the procedure was stored by a
+@code{define} expression, or @code{#f} if the procedure wasn't created
+by that kind of expression.
 
-Currently, property lists are implemented differently for procedures and
-closures than for other kinds of objects.  Therefore, when manipulating
-a property list associated with a procedure object, use the
-@code{procedure} functions; otherwise, use the @code{object} functions.
+Guile's representation of an object property is a procedure-with-setter
+(@pxref{Procedures with Setters}) that can be used with the generalized
+form of @code{set!} (REFFIXME) to set and retrieve that property for any
+Scheme object.  So, setting a property looks like this:
 
-@deffn {Scheme Procedure} object-properties obj
-@deffnx {C Function} scm_object_properties (obj)
-Return @var{obj}'s property list.
+@lisp
+(set! (my-property obj1) value-for-obj1)
+(set! (my-property obj2) value-for-obj2)
+@end lisp
+
+@noindent
+And retrieving values of the same property looks like this:
+
+@lisp
+(my-property obj1)
+@result{}
+value-for-obj1
+
+(my-property obj2)
+@result{}
+value-for-obj2
+@end lisp
+
+To create an object property in the first place, use the
+@code{make-object-property} procedure:
+
+@lisp
+(define my-property (make-object-property))
+@end lisp
+
+@deffn {Scheme Procedure} make-object-property
+Create and return an object property.  An object property is a
+procedure-with-setter that can be called in two ways.  @code{(set!
+(@var{property} @var{obj}) @var{val})} sets @var{obj}'s @var{property}
+to @var{val}.  @code{(@var{property} @var{obj})} returns the current
+setting of @var{obj}'s @var{property}.
 @end deffn
 
-@deffn {Scheme Procedure} set-object-properties! obj alist
-@deffnx {C Function} scm_set_object_properties_x (obj, alist)
-Set @var{obj}'s property list to @var{alist}.
-@end deffn
+A single object property created by @code{make-object-property} can
+associate distinct property values with all Scheme values that are
+distinguishable by @code{eq?} (including, for example, integers).
 
-@deffn {Scheme Procedure} object-property obj key
-@deffnx {C Function} scm_object_property (obj, key)
-Return the property of @var{obj} with name @var{key}.
-@end deffn
+Internally, object properties are implemented using a weak key hash
+table.  This means that, as long as a Scheme value with property values
+is protected from garbage collection, its property values are also
+protected.  When the Scheme value is collected, its entry in the
+property table is removed and so the (ex-) property values are no longer
+protected by the table.
 
-@deffn {Scheme Procedure} set-object-property! obj key value
-@deffnx {C Function} scm_set_object_property_x (obj, key, value)
-In @var{obj}'s property list, set the property named @var{key}
-to @var{value}.
-@end deffn
-
-[Interface bug:  there should be a second level of interface in which
-the user provides a "property table" that is possibly private.]
+@menu
+* Property Primitives::         Low level property implementation.
+* Old-fashioned Properties::    An older approach to properties.
+@end menu
 
 
-@node Primitive Properties
-@section Primitive Properties
+@node Property Primitives
+@subsection Low Level Property Implementation.
 
 @deffn {Scheme Procedure} primitive-make-property not_found_proc
 @deffnx {C Function} scm_primitive_make_property (not_found_proc)
@@ -148,6 +177,41 @@ Remove any value associated with @var{prop} and @var{obj}.
 @end deffn
 
 
+@node Old-fashioned Properties
+@subsection An Older Approach to Properties
+
+Traditionally, Lisp systems provide a different object property
+interface to that provided by @code{make-object-property}, in which the
+object property that is being set or retrieved is indicated by a symbol.
+
+Guile includes this older kind of interface as well, but it may well be
+removed in a future release, as it is less powerful than
+@code{make-object-property} and so increases the size of the Guile
+library for no benefit.  (And it is trivial to write a compatibility
+layer in Scheme.)
+
+@deffn {Scheme Procedure} object-properties obj
+@deffnx {C Function} scm_object_properties (obj)
+Return @var{obj}'s property list.
+@end deffn
+
+@deffn {Scheme Procedure} set-object-properties! obj alist
+@deffnx {C Function} scm_set_object_properties_x (obj, alist)
+Set @var{obj}'s property list to @var{alist}.
+@end deffn
+
+@deffn {Scheme Procedure} object-property obj key
+@deffnx {C Function} scm_object_property (obj, key)
+Return the property of @var{obj} with name @var{key}.
+@end deffn
+
+@deffn {Scheme Procedure} set-object-property! obj key value
+@deffnx {C Function} scm_set_object_property_x (obj, key, value)
+In @var{obj}'s property list, set the property named @var{key}
+to @var{value}.
+@end deffn
+
+
 @node Sorting
 @section Sorting
 
@@ -349,13 +413,13 @@ arguments.  When the procedures have been added, we can invoke them
 using @code{run-hook}.
 
 @lisp
-(add-hook! hook (lambda (x y) 
-                    (display "Foo: ") 
-                    (display (+ x y)) 
+(add-hook! hook (lambda (x y)
+                    (display "Foo: ")
+                    (display (+ x y))
                     (newline)))
-(add-hook! hook (lambda (x y) 
-                    (display "Bar: ") 
-                    (display (* x y)) 
+(add-hook! hook (lambda (x y)
+                    (display "Bar: ")
+                    (display (* x y))
                     (newline)))
 (run-hook hook 3 4)
 @print{} Bar: 12
@@ -367,14 +431,14 @@ added.  This can be changed by providing the optional third argument
 on the second call to @code{add-hook!}.
 
 @lisp
-(add-hook! hook (lambda (x y) 
-                    (display "Foo: ") 
-                    (display (+ x y)) 
+(add-hook! hook (lambda (x y)
+                    (display "Foo: ")
+                    (display (+ x y))
                     (newline)))
-(add-hook! hook (lambda (x y) 
-                    (display "Bar: ") 
-                    (display (* x y)) 
-                    (newline)) 
+(add-hook! hook (lambda (x y)
+                    (display "Bar: ")
+                    (display (* x y))
+                    (newline))
                     #t)   ; @r{<- Change here!}
 (run-hook hook 3 4)
 @print{} Foo: 7

doc/ref/scripts.texi

@@ -101,6 +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}
 @item --no-debug
 Do not use the debugging evaluator, even when entering an interactive
 session.