Rewrite the description of intricacies with ephemeron-broken? per

Taylor's recommendation to name the ephemeron explicitly and use more
active language.

diff --git a/doc/ref-manual/misc-datatypes.texi b/doc/ref-manual/misc-datatypes.texi
index d8b1a2bd9c233c51a9d080fc3e168e0a7c2b8e36..64db1239ffacf1181a436f8a54aaac028da5b56f 100644 (file)
--- a/doc/ref-manual/misc-datatypes.texi
+++ b/doc/ref-manual/misc-datatypes.texi
@@ -1017,14 +1017,15 @@ is broken, neither of these operations has any effect.
 @end deffn
 
 Like @code{weak-pair/car?}, @code{ephemeron-broken?} must be used with
-care.  @code{Ephemeron-broken?} returning @code{#f} on an ephemeron
-guarantees that any
-prior call to @code{ephemeron-key} or @code{ephemeron-datum} on the
-same ephemeron yielded the key or datum that was stored in the
-ephemeron, but it makes no guarantees about subsequent calls to
-@code{ephemeron-key} or @code{ephemeron-datum}.  Thus, the correct
-idiom to fetch an ephemeron's key and datum and use them if the
-ephemeron is not broken is
+care.  If @code{(ephemeron-broken? @var{ephemeron})} yields false, it
+guarantees only that prior evaluations of @code{(ephemeron-key
+@var{ephemeron})} or @code{(ephemeron-datum @var{ephemeron})} yielded the key
+or datum that was stored in the ephemeron, but it makes no guarantees
+about subsequent calls to @code{ephemeron-key} or
+@code{ephemeron-datum}: the garbage collector may run and break the
+ephemeron immediately after @code{ephemeron-broken?} returns.  Thus,
+the correct idiom to fetch an ephemeron's key and datum and use them
+if the ephemeron is not broken is
 
 @example
 @group