* src/data.c (Fmake_variable_buffer_local): Mention `permanent-local'.

2 files changed, 10 insertions, 2 deletions

diff --git a/src/ChangeLog b/src/ChangeLog
index d17f320516c..c3062d0fc0a 100644
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,3 +1,7 @@
+2013-11-24  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * data.c (Fmake_variable_buffer_local): Mention `permanent-local'.
+
 2013-11-23  Romain Francoise  <romain@orebokech.com>
 
         * fileio.c (init_fileio): Move `write_region_inhibit_fsync'
diff --git a/src/data.c b/src/data.c
index bdd56bf0f62..ca896897ddf 100644
--- a/src/data.c
+++ b/src/data.c
@@ -1551,8 +1551,12 @@ Note that binding the variable with `let', or setting it while
 a `let'-style binding made in this buffer is in effect,
 does not make the variable buffer-local.  Return VARIABLE.
 
-In most cases it is better to use `make-local-variable',
-which makes a variable local in just one buffer.
+This globally affects all uses of this variable, so it belongs together with
+the variable declaration, rather than with its uses (if you just want to make
+a variable local to the current buffer for one particular use, use
+`make-local-variable').  Buffer-local bindings are normally cleared
+while setting up a new major mode, unless they have a `permanent-local'
+property.
 
 The function `default-value' gets the default value and `set-default' sets it.  */)
   (register Lisp_Object variable)