emacs-29 ea5fd375bb2: Fix documentation of 'normal-mode' in buffers that don't visit files

[Eli Zaretskii]

branch: emacs-29
commit ea5fd375bb2656562f57325b3d5c6fd17f6b2e72
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Fix documentation of 'normal-mode' in buffers that don't visit files
    
    * lisp/files.el (normal-mode):
    * lisp/subr.el (run-mode-hooks):
    * doc/emacs/modes.texi (Choosing Modes): Mention the caveat with
    'normal-mode' in buffers not visiting files.  (Bug#61925)
    * lisp/files.el (hack-local-variables): Doc fix.
---
 doc/emacs/modes.texi |  9 ++++++---
 lisp/files.el        | 18 +++++++++++++-----
 lisp/subr.el         |  5 +++--
 3 files changed, 22 insertions(+), 10 deletions(-)

diff --git a/doc/emacs/modes.texi b/doc/emacs/modes.texi
index 0e4b15fb514..d2f96af0b55 100644
--- a/doc/emacs/modes.texi
+++ b/doc/emacs/modes.texi
@@ -473,9 +473,12 @@ specify which mode you prefer.
   If you have changed the major mode of a buffer, you can return to
 the major mode Emacs would have chosen automatically, by typing
 @kbd{M-x normal-mode}.  This is the same function that
-@code{find-file} calls to choose the major mode.  It also processes
-the file's @samp{-*-} line or local variables list (if any).
-@xref{File Variables}.
+@code{find-file} calls to choose the major mode.  If the buffer is
+visiting a file, this command also processes the file's @samp{-*-}
+line and file-local variables list (if any).  @xref{File Variables}.
+If the buffer doesn't visit a file, the command processes only the
+major mode specification, if any, in the @samp{-*-} line and in the
+file-local variables list.
 
 @vindex change-major-mode-with-file-name
   The commands @kbd{C-x C-w} and @code{set-visited-file-name} change to
diff --git a/lisp/files.el b/lisp/files.el
index db3f348c4b5..63ad2806ca3 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -2775,7 +2775,11 @@ not set local variables (though we do notice a mode 
specified with -*-.)
 
 `enable-local-variables' is ignored if you run `normal-mode' interactively,
 or from Lisp without specifying the optional argument FIND-FILE;
-in that case, this function acts as if `enable-local-variables' were t."
+in that case, this function acts as if `enable-local-variables' were t.
+
+If invoked in a buffer that doesn't visit a file, this function
+processes only the major mode specification in the -*- line and
+the local variables spec."
   (interactive)
   (kill-all-local-variables)
   (unless delay-mode-hooks
@@ -3925,9 +3929,6 @@ variables.
 
 Uses `hack-local-variables-apply' to apply the variables.
 
-See `hack-local-variables--find-variables' for the meaning of
-HANDLE-MODE.
-
 If `enable-local-variables' or `local-enable-local-variables' is
 nil, or INHIBIT-LOCALS is non-nil, this function disregards all
 normal local variables.  If `inhibit-local-variables-regexps'
@@ -3937,7 +3938,14 @@ applied.
 
 Variables present in `permanently-enabled-local-variables' will
 still be evaluated, even if local variables are otherwise
-inhibited."
+inhibited.
+
+If HANDLE-MODE is t, the function only checks whether a \"mode:\"
+is specified, and returns the corresponding mode symbol, or nil.
+In this case, try to ignore minor-modes, and return only a major-mode.
+If HANDLE-MODE is nil, the function gathers all the specified local
+variables.  If HANDLE-MODE is neither nil nor t, the functions gathers
+all the specified local variables, but ignores any settings of \"mode:\"."
   ;; We don't let inhibit-local-variables-p influence the value of
   ;; enable-local-variables, because then it would affect dir-local
   ;; variables.  We don't want to search eg tar files for file local
diff --git a/lisp/subr.el b/lisp/subr.el
index a0a22072a18..b8bda0efd3d 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -2406,8 +2406,9 @@ If the variable `delay-mode-hooks' is non-nil, does not 
do anything,
 just adds the HOOKS to the list `delayed-mode-hooks'.
 Otherwise, runs hooks in the sequence: `change-major-mode-after-body-hook',
 `delayed-mode-hooks' (in reverse order), HOOKS, then runs
-`hack-local-variables', runs the hook `after-change-major-mode-hook', and
-finally evaluates the functions in `delayed-after-hook-functions' (see
+`hack-local-variables' (if the buffer is visiting a file),
+runs the hook `after-change-major-mode-hook', and finally
+evaluates the functions in `delayed-after-hook-functions' (see
 `define-derived-mode').
 
 Major mode functions should use this instead of `run-hooks' when