Make a Variable Buffer-Local within a Let-Binding

Question

12.11.2 Creating and Deleting Buffer-Local Bindings:

Making a variable buffer-local within a let-binding for that variable does not work reliably, unless the buffer in which you do this is not current either on entry to or exit from the let.

So I test an example (in which the buffer is not current either on entry to or exit from the let) in the *scratch* buffer:

(setq number 0)

(with-current-buffer "*Messages*"
  (let (number)
    (with-current-buffer "*scratch*"
      (make-local-variable 'number)
      (setq number 1))))

number
;; ==> 0
;; Still, it returns the default value.

It seems that I did not understand what the manual said correctly.

I wonder what the manual mean by "work reliably",
can anyone give me an example that meets the conditions following "unless" and an opposite example that cannot "work reliably"?

---

Then the manual continued:

This is because let does not distinguish between different kinds of bindings; it knows only which variable the binding was made for.

But according to another example in 12.11.1 Introduction to Buffer-Local Variables:

(setq foo 'g)

(set-buffer "a")
(make-local-variable 'foo)
(setq foo 'a)

(let ((foo 'temp))
  (set-buffer "b")
  foo)
;; ==> g

let seems to distinguish ...

---

I know that making a variable buffer-local within a let-binding may not be a good coding convention, but since the manual mentioned it, I just want to figure it out.

Answer 1

The following works well.
After execution of the code the value of foo is 1 in all buffers except buffer *test2*, there the value is 3.
This is expected since in buffer *test2* the buffer-local value of foo was changed.

(unintern 'foo)
(defvar foo)
(setq foo 1)

(list
 (with-current-buffer (get-buffer-create "*test1*")
   (let ((foo 2))
     (with-current-buffer (get-buffer-create "*test2*")
       (make-variable-buffer-local 'foo)
       (setq foo 3)
       )
     foo
     )
   )
 (with-current-buffer "*test1*"
   foo)
 (with-current-buffer "*test2*"
   foo)
 foo
 )
;; => (2 1 3 1)

In the following example the local let-binding of foo leaks out of the let form.
In buffer *test1* the variable foo is locally let-bound and set to 3 within the let-body.
Outside the let-body it should have back its old value 1 in buffer *test1* but it is still has the value 3.

(unintern 'foo)
(defvar foo)
(setq foo 1)

(list
 (with-current-buffer (get-buffer-create "*test1*")
   (let ((foo 2))
     (make-variable-buffer-local 'foo)
     (setq foo 3)
     foo)
   )

 (with-current-buffer "*test1*"
   foo)
 (with-current-buffer (get-buffer-create "*test2*")
   foo)
 )
;; => (3 3 1)

An important aspect mentioned in Drew's comment:
Let-binding is not buffer local if the locally bound variable is not already declared as buffer-local.
Example:

(unintern 'foo)
(defvar foo 0)

(with-current-buffer (get-buffer-create "*test1*")
  (let ((foo 1))
    (with-current-buffer (get-buffer-create "*test2*")
      foo)))

But, if a variable is already declared as buffer-local a let-binding of this variable is also buffer-local:

(unintern 'foo)
(defvar-local foo 0)

(defvar ans)
(setq ans nil)

(with-current-buffer (get-buffer-create "*test1*")
  (setq foo 1)
  (let ((foo 2))
    (with-current-buffer (get-buffer-create "*test2*")
      (push foo ans)
      )
    (push foo ans)
    )
  (push foo ans)
  )
(nreverse ans)
;; => (0 2 1)