* doc/lispref/variables.texi (Converting to Lexical Binding): New section

Extract it from `Using Lexical Binding` and extend it a bit.

1 files changed, 20 insertions, 6 deletions

diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index 94c8c88796f..acbc8df6eae 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -934,6 +934,7 @@ Lisp programs.
 * Dynamic Binding Tips::    Avoiding problems with dynamic binding.
 * Lexical Binding::         A different type of local variable binding.
 * Using Lexical Binding::   How to enable lexical binding.
+* Converting to Lexical Binding:: Convert existing code to lexical binding.
 @end menu
 
 @node Dynamic Binding
@@ -1242,9 +1243,10 @@ for those that are only special in the current lexical scope.
 @end defun
 
   The use of a special variable as a formal argument in a function is
-discouraged.  Doing so gives rise to unspecified behavior when lexical
-binding mode is enabled (it may use lexical binding sometimes, and
-dynamic binding other times).
+not supported.
+
+@node Converting to Lexical Binding
+@subsection Converting to Lexical Binding
 
   Converting an Emacs Lisp program to lexical binding is easy.  First,
 add a file-local variable setting of @code{lexical-binding} to
@@ -1264,9 +1266,21 @@ variable.  If a non-special variable is bound but not used within a
 variable.  The byte-compiler will also issue a warning if you use a
 special variable as a function argument.
 
-  (To silence byte-compiler warnings about unused variables, just use
-a variable name that starts with an underscore.  The byte-compiler
-interprets this as an indication that this is a variable known not to
+  A warning about a reference or an assignment to a free variable is
+usually a clear sign that that variable should be marked as
+dynamically scoped, so you need to add an appropriate @code{defvar}
+before the first use of that variable.
+
+  A warning about an unused variable may be a good hint that the
+variable was intended to be dynamically scoped (because it is actually
+used, but in another function), but it may also be an indication that
+the variable is simply really not used and could simply be removed.
+So you need to find out which case it is, and based on that, either
+add a @code{defvar} or remove the variable altogether.  If removal is
+not possible or not desirable (typically because it is a formal
+argument and that we cannot or don't want to change all the callers),
+you can also add a leading underscore to the variable's name to
+indicate to the compiler that this is a variable known not to
 be used.)
 
 @node Buffer-Local Variables