From b549e6c8ff159013c48269f16a62858ced96faaf Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Sat, 16 Nov 2024 11:47:34 +0200
Subject: [PATCH] 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)

(cherry picked from commit 81816800628f1eef1928eee3ccf9a2f8b53ab9a7)
---
 doc/emacs/files.texi |  7 +++++++
 doc/emacs/modes.texi | 47 ++++++++++++++++++++++++++++++++++++++++----
 2 files changed, 50 insertions(+), 4 deletions(-)

diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 60f84bd58b2..bcbdc078a56 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -1149,6 +1149,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 1321464014d..644dc21a684 100644
--- 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
-- 
2.39.5