Collect "Weak Pairs" and "Ephemerons" into a section called "Weak References".

State the common motivation, define the common terminology, and
describe the contrasts between weak pairs and ephemerons in the common
section, and tighten the "Weak Pairs" and "Ephemerons" sections
themselves back to just describing their data structures.

diff --git a/doc/ref-manual/misc-datatypes.texi b/doc/ref-manual/misc-datatypes.texi
index 64db1239ffacf1181a436f8a54aaac028da5b56f..239dacb6e884ca5de22ca6069133c34be3a0c3a8 100644 (file)
--- a/doc/ref-manual/misc-datatypes.texi
+++ b/doc/ref-manual/misc-datatypes.texi
@@ -8,8 +8,7 @@
 * Records::                     
 * Promises::                    
 * Streams::                     
-* Weak Pairs::                  
-* Ephemerons::
+* Weak References::                  
 @end menu
 
 @node Booleans, Symbols, Miscellaneous Datatypes, Miscellaneous Datatypes
@@ -740,7 +739,7 @@ value of a promise is forced by primitive procedures like @code{car} and
 @end example
 @end itemize
 
-@node Streams, Weak Pairs, Promises, Miscellaneous Datatypes
+@node Streams, Weak References, Promises, Miscellaneous Datatypes
 @section Streams
 
 @cindex stream (defn)
@@ -858,20 +857,62 @@ invoking @var{procedure} with the corresponding elements of the
 @var{stream}s as its arguments.
 @end deffn
 
-@node Weak Pairs, Ephemerons, Streams, Miscellaneous Datatypes
-@section Weak Pairs
+@node Weak References,  , Streams, Miscellaneous Datatypes
+@section Weak References
+
+Weak references are a mechanism for building data structures that
+point at objects without protecting them from garbage collection.  An
+example of such a data structure might be an entry in a lookup table
+that should be removed if the rest of the program does not reference
+its key.  Such an entry must still point at its key to carry out
+comparisons, but should not in itself prevent its key from being
+garbage collected.
+
+@cindex weak reference (defn)
+@cindex strong reference (defn)
+@cindex reference, weak (defn)
+@cindex reference, strong (defn)
+A @dfn{weak reference} is a reference that points at an object without
+preventing it from being garbage collected.  The term @dfn{strong
+reference} is used to distinguish normal references from weak ones.
+If there is no path of strong references to some object, the garbage
+collector will reclaim that object and mark any weak references to it
+to indicate that it has been reclaimed.
+
+If there is a path of strong references from an object @var{A} to an
+object @var{B}, @var{A} is said to hold @var{B} @dfn{strongly}.  If
+there is a path of references from an object @var{A} to an object
+@var{B}, but every such path traverses at least one weak reference,
+@var{A} is said to hold @var{B} @dfn{weakly}.
+
+MIT Scheme provides two mechanisms for using weak references.
+@dfn{Weak pairs} are like normal pairs, except that their car slot is
+a weak reference (but the cdr is still strong).  The heavier-weight
+@dfn{ephemerons} additionally arrange that the ephemeron does not
+count as holding the object in its key field strongly even if the
+object in its datum field does.
+
+@menu
+* Weak Pairs::                  
+* Ephemerons::
+@end menu
+
+@node Weak Pairs, Ephemerons, Weak References, Weak References
+@subsection Weak Pairs
 
 @cindex weak pair (defn)
 @cindex pair, weak (defn)
-@dfn{Weak pairs} are a mechanism for building data structures that
-point at objects without protecting them from garbage collection.  The
-car of a weak pair holds its pointer weakly, while the cdr holds its
-pointer in the normal way.  If the object in the car of a weak pair is
-not held normally by any other data structure, it will be
-garbage-collected.  Note that the object in the cdr of a weak pair
-could prevent the object in the car of a weak pair from being garbage
-collected, if it held a normal reference thereto.  In contrast,
-@xref{Ephemerons}.
+The car of a @dfn{weak pair} holds its pointer weakly, while the cdr
+holds its pointer strongly.  If the object in the car of a weak pair
+is not held strongly by any other data structure, it will be
+garbage-collected.
+
+Note: weak pairs can be defeated by cross references among their
+slots.  Consider a weak pair @var{P} holding an object @var{A} in its
+car and an object @var{D} in its cdr.  @var{P} points to @var{A}
+weakly and to @var{D} strongly.  If @var{D} holds @var{A} strongly,
+however, then @var{P} ends up holding @var{A} strongly after all.  If
+avoiding this is worth a heavier-weight structure, @xref{Ephemerons}.
 
 @findex pair?
 Note: weak pairs are @emph{not} pairs; that is, they do not satisfy the
@@ -949,15 +990,14 @@ Sets the cdr component of @var{weak-pair} to @var{object} and returns an
 unspecified result.
 @end deffn
 
-@node Ephemerons,  , Weak Pairs, Miscellaneous Datatypes
-@section Ephemerons
+@node Ephemerons,  , Weak Pairs, Weak References
+@subsection Ephemerons
 
 @cindex ephemeron (defn)
 @cindex ephemeron, broken
 @cindex broken ephemeron
-@dfn{Ephemerons} are a mechanism for building data structures that
-point at objects without protecting them from garbage collection.  An
-ephemeron is an object with two weakly referenced components called
+An
+@dfn{ephemeron} is an object with two weakly referenced components called
 its @dfn{key} and @dfn{datum}.  The garbage collector drops an
 ephemeron's references to both key and datum, rendering the ephemeron
 @dfn{broken}, if and only if the garbage collector can prove that