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

[Marius Vollmer <mvo@zagadka.de>]

ludovic.courtes@laas.fr (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
+@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}.
 
-@code{#: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
+@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

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


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel