Improve the documentation of major-mode remapping

* etc/NEWS (example):
* doc/emacs/files.texi (Reverting):
* doc/emacs/modes.texi (Choosing Modes): Improve the documentation
of 'major-mode-remap-alist' and mode remapping.  (Bug#74339)

diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 709cb0910e6146d1e687329e75cdc4e7a3b1579b..e22d1fb6daba999af6284bce1d8e565873cbb247 100644 (file)
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -1091,6 +1091,13 @@ is non-@code{nil}, use a shorter @kbd{y/n} query instead of a longer
   You can also tell Emacs to revert buffers automatically when their
 visited files change on disk; @pxref{Auto Revert}.
 
+@vindex major-mode-remap-alist@r{, and reverting a buffer}
+  Note that reverting a buffer turns on the major mode appropriate for
+visiting the buffer's file, as described in @ref{Choosing Modes}.  Thus,
+the major mode actually turned on as result of reverting a buffer
+depends on mode remapping, and could be different from the original mode
+if you customized @code{major-mode-remap-alist} in-between.
+
 @node Auto Revert
 @section Auto Revert: Keeping buffers automatically up-to-date
 @cindex Global Auto Revert mode

diff --git a/doc/emacs/modes.texi b/doc/emacs/modes.texi
index 1321464014dd596d953bb353de54973f1738920c..644dc21a684633161212a00c48ed862a32785ff2 100644 (file)
--- a/doc/emacs/modes.texi
+++ b/doc/emacs/modes.texi
@@ -465,12 +465,47 @@ only @emph{after} @code{auto-mode-alist}.  By default,
 files, HTML/XML/SGML files, PostScript files, and Unix style Conf
 files.
 
+@cindex remapping of major modes
+@cindex major modes, remapping
 @vindex major-mode-remap-alist
   Once a major mode is found, Emacs does a final check to see if the
-mode has been remapped by @code{major-mode-remap-alist}, in which case
-it uses the remapped mode instead.  This is used when several
+mode has been @dfn{remapped} by @code{major-mode-remap-alist}, in which
+case it uses the remapped mode instead.  This is used when several
 different major modes can be used for the same file type, so you can
-specify which mode you prefer.
+specify which mode you prefer.  Note that this remapping affects the
+major mode found by all of the methods described above, so, for example,
+the mode specified by the first line of the file will not necessarily be
+the mode actually turned on in the buffer visiting the file.  (This
+remapping also affects @code{revert-buffer}, @pxref{Reverting}.)  When
+several modes are available for the same file type, you can tell Emacs
+about your major-mode preferences by customizing
+@code{major-mode-remap-alist}.  For example, put this in your
+@file{~/.emacs} init file (@pxref{Init File})
+
+@lisp
+  (add-to-list 'major-mode-remap-alist '(c-mode . c-ts-mode))
+@end lisp
+
+@noindent
+to force Emacs to invoke @code{c-ts-mode} when @code{c-mode} is
+specified by @code{auto-mode-alist} or by file-local variables.
+Conversely,
+
+@lisp
+  (add-to-list 'major-mode-remap-alist '(c-mode))
+@end lisp
+
+@noindent
+will force Emacs to never remap @code{c-mode} to any other mode.
+
+  The default value of @code{major-mode-remap-alist} is @code{nil}, so
+no remapping takes place.  However, loading some Lisp packages or
+features might introduce mode remapping, because Emacs assumes that
+loading those means the user prefers using an alternative mode.  So for
+predictable behavior, we recommend that you always customize
+@code{major-mode-remap-alist} to express your firm preferences, because
+this variable overrides any remapping that Emacs might decide to perform
+internally.
 
 @findex normal-mode
   If you have changed the major mode of a buffer, you can return to
@@ -481,7 +516,11 @@ 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.
+file-local variables list.  @kbd{M-x normal-mode} takes the mode
+remapping into consideration, so if you customized
+@code{major-mode-remap-alist} after the buffer's major mode was chosen
+by Emacs, @code{normal-mode} could turn on a mode that is different from
+the one Emacs chose originally.
 
 @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/etc/NEWS b/etc/NEWS
index fbc29206039df8ec29ec37825d1f22252417fef8..3c3c772d0d1b4bd15bdd9d905723465e334058f2 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -103,6 +103,36 @@ collections of snippets automatically apply to the new Tree-Sitter modes.
 Note that those modes still do not inherit from the non-TS mode, so
 configuration settings installed via mode hooks are not affected.
 
+Loading a Tree-Sitter mode (such as by using 'M-x load-library' or with
+'M-x load-file') by default causes the corresponding non-Tree-Sitter
+mode be remapped to the Tree-Sitter mode.  This remapping affects
+visiting files for which 'auto-mode-alist' specifies a non-Tree-Sitter
+mode, and also affects mode-specification cookies on the first line of a
+file and mode specifications in file- and directory-local variables.  To
+revert to using a non-Tree-Sitter mode, reload the corresponding mode
+file anew.  To prevent file loading from turning on Tree-Sitter mode
+when 'auto-mode-alist' or the file/directory-local variables specify a
+non-Tree-Sitter mode, customize the user option 'major-mode-remap-alist'
+to specify that a non-Tree-Sitter mode is "remapped" to itself.  For
+example:
+
+   (add-to-list 'major-mode-remap-alist '(c-mode))
+
+specifies that C Mode should not be remapped to 'c-ts-mode' even if and
+when 'c-ts-mode' is loaded.  Conversely,
+
+   (add-to-list 'major-mode-remap-alist '(c-mode . c-ts-mode))
+
+tells Emacs to always invoke 'c-ts-mode' whenever 'c-mode' is
+requested, either by 'auto-mode-alist' or by file/directory-local
+variables.
+
+We recommend using 'major-mode-remap-alist' to express your preferences
+for using Tree-Sitter or non-Tree-Sitter modes for files for which both
+variants of major modes are available, because that variable overrides
+the remapping Emacs might decide to perform as result of loading Lisp
+files and features.
+
 ---
 ** Mouse wheel events should now always be 'wheel-up/down/left/right'.
 At those places where the old 'mouse-4/5/6/7' events could still occur