Inconsistency in emacs' rules of scope?

Question

I have always felt that emacs' rules of scope are a bit strange and prone to contradictions. In fact I have even attempted to file bug reports just to be told that my interpretation of the rules of scope was wrong, which I always reluctantly accepted.

This time I think I nailed a contradiction caused by such rules. In the emacs manual page for setq (https://www.gnu.org/software/emacs/manual/html_node/eintr/Using-setq.html), it is stated that setq is exactly the same as using set followed by a quote, but the following two examples show that it isn't:

(progn
  (setq a "one")       ;; Global variable
  (let ((a "two"))     ;; Local variable
    (set 'a "three")   ;; Using "set + quote" affected the GLOBAL variable "a"
    a))                ;; Return local variable a

=> "two"               ;; The local variable "a" remained with its let-value "two" and was not affected by "set + quote"

Here is the second example:

(progn
  (setq a "one")       ;; Global variable
  (let ((a "two"))     ;; Local variable
    (setq a "three")   ;; Using "setq" affected the LOCAL variable "a"
    a))                ;; Return local variable a

=> "three"             ;; The local variable "a" was changed by setq 

My question is thus: Am I once more misinterpreting the rules of scope or have I really found an inconsistency in these rules?

Perhaps I should add that the above code was run with lexical binding enabled. Otherwise I believe there is no inconsistency

---

My emacs version is: GNU Emacs 27.2 (build 1, x86_64-pc-linux-gnu, GTK+ Version 3.24.20, cairo version 1.16.0) of 2021-03-26

Answer 1

Lexical scope (recently added to emacs) changes the rules, and some documentation is still out of date. The current documentation for setq is this manual page which says

When dynamic variable binding is in effect (the default), set has the same effect as setq, apart from the fact that set evaluates its symbol argument whereas setq does not. But when a variable is lexically bound, set affects its dynamic value, whereas setq affects its current (lexical) value.

It looks like the page you are viewing was written for an earlier version of emacs and hasn't been updated; you might want to file a documentation bug.