Re: [PATCH] Augmenting the doc of `define-module'

[Marius Vollmer]

address@hidden (Ludovic Courtès) writes:

> Any news regarding this patch?

I made the following changes.  OK?

Index: api-modules.texi
===================================================================
RCS file: /cvsroot/guile/guile/guile-core/doc/ref/api-modules.texi,v
retrieving revision 1.11
diff -u -r1.11 api-modules.texi
--- api-modules.texi    5 Nov 2005 21:38:49 -0000       1.11
+++ api-modules.texi    7 Dec 2005 00:28:42 -0000
@@ -456,17 +456,32 @@
 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}).
+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.
 
-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.
+For instance, SRFI-39 exports a binding named
address@hidden (@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
address@hidden:replace}.
 
address@hidden:duplicates} below provides fine-grain control about duplicate
-binding handling on the module-user side.
+SRFI-19, on the other hand, exports its own version of
address@hidden (@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

-- 
GPG: D5D4E405 - 2F9B BCCC 8527 692A 04E3  331E FAF8 226A D5D4 E405