Added more words to #:replace from Ludovic. Thanks!

[bpt/guile.git] / doc / ref / api-modules.texi

diff --git a/doc/ref/api-modules.texi b/doc/ref/api-modules.texi
index f6f2985..91e70f3 100644 (file)
--- a/doc/ref/api-modules.texi
+++ b/doc/ref/api-modules.texi
@@ -456,17 +456,32 @@ will have the effect of replacing any binding with the same name that
 is not also ``replacing''.  Normally a replacement results in an
 ``override'' warning message, @code{#:replace} avoids that.
 
-This can be used by a module extending a core function in an upwardly
-compatible way, like SRFI-39 @code{current-input-port}
-(@pxref{SRFI-39}).
-
-Or it can be used by a module which is intentionally producing a new
-special kind of environment and should override any core or other
-bindings already in scope.  For example perhaps a logic processing
-environment where @code{<=} is an inference instead of a comparison.
-
-@code{#:duplicates} below provides fine-grain control about duplicate
-binding handling on the module-user side.
+This is useful for modules that export bindings that have the same
+name as core bindings.  @code{#:replace}, in a sense, lets Guile know
+that the module @emph{purposefully} replaces a core binding.  It is
+important to note, however, that this binding replacement is confined
+to the name space of the module user.  In other words, the value of the
+core binding in question remains unchanged for other modules.
+
+For instance, SRFI-39 exports a binding named
+@code{current-input-port} (@pxref{SRFI-39}) that is a function which
+is upwardly compatible with the core @code{current-input-port}
+function.  Therefore, SRFI-39 exports its version with
+@code{#:replace}.
+
+SRFI-19, on the other hand, exports its own version of
+@code{current-time} (@pxref{SRFI-19 Time}) which is not compatible
+with the core @code{current-time} function (@pxref{Time}).  Therefore,
+SRFI-19 does not use @code{#:replace}.
+
+The @code{#:replace} option can also be used by a module which is
+intentionally producing a new special kind of environment and should
+override any core or other bindings already in scope.  For example
+perhaps a logic processing environment where @code{<=} is an inference
+instead of a comparison.
+
+The @code{#:duplicates} (see below) provides fine-grain control about
+duplicate binding handling on the module-user side.
 
 @item #:duplicates @var{list}
 @cindex duplicate binding handlers