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.

diff --git a/doc/emacs/modes.texi b/doc/emacs/modes.texi
index 0e4b15fb514eefab2b3da727459581bbcd88416e..d2f96af0b55efef41165d08b651bce3fa2c11429 100644 (file)
--- 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 db3f348c4b58710b606c56efb0d65edb73eb7a4a..63ad2806ca3f5c1fe8f387d4da4206af19febd9e 100644 (file)
--- 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 a0a22072a182680338f06f3c5fe920d06ea1d77d..b8bda0efd3d51096f15f834a50695c45515ef6c3 100644 (file)
--- 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