* variables.texi (Creating Buffer-Local): Warn against misuses of

make-variable-buffer-local.

Fixes: debbugs:10258

2 files changed, 7 insertions, 0 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 2db274f2703..51143c27859 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,8 @@
+2011-12-27  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * variables.texi (Creating Buffer-Local): Warn against misuses of
+        make-variable-buffer-local (bug#10258).
+
 2011-08-28  Dani Moncayo  <dmoncayo@gmail.com>  (tiny change)
 
         * lists.texi (Building Lists): Fix typo.
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index 1c86a7eb65c..c4f091484e6 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -1268,6 +1268,8 @@ needed if you use the @var{local} argument to @code{add-hook} or
 This function marks @var{variable} (a symbol) automatically
 buffer-local, so that any subsequent attempt to set it will make it
 local to the current buffer at the time.
+Contrary to @code{make-local-variable} with which it is often confused, this
+cannot be undone, and affects the behavior of the variable in all buffers.
 
 A peculiar wrinkle of this feature is that binding the variable (with
 @code{let} or other binding constructs) does not create a buffer-local