Document the fact that (current-local-map) and (urrent-global-map)

return references, not copies.

2 files changed, 14 insertions, 3 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 17b3ede464d..2214ee0afa6 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,8 @@
+2008-05-03  Eric S. Raymond  <esr@golux>
+
+        * keymaps.texi: Clarify that (current-local-map) and 
+        (current-global-map) return references, not copies.
+
 2008-05-02  Juri Linkov  <juri@jurta.org>
 
         * minibuf.texi (Text from Minibuffer): Document a list of
diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index 576a02fdcd2..f97fc6b790f 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -766,9 +766,11 @@ out with.
 @end defvar
 
 @defun current-global-map
-This function returns the current global keymap.  This is the
-same as the value of @code{global-map} unless you change one or the
-other.
+This function returns the current global keymap.  This is the same as
+the value of @code{global-map} unless you change one or the other.
+The return value is a reference, not a copy; if you use
+@code{define-key} or other functions on it you will alter global
+bindings.
 
 @example
 @group
@@ -802,6 +804,10 @@ keymap.
 @end example
 @end defun
 
+@code{current-local-map} returns a reference to the local keymap, not
+a copy of it; if you use @code{define-key} or other functions on it 
+you will alter local bindings.
+
 @defun current-minor-mode-maps
 This function returns a list of the keymaps of currently enabled minor modes.
 @end defun