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

make-variable-buffer-local.

Fixes: debbugs:10258

doc/lispref/ChangeLog

+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.

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