[elpa] externals/auctex 09a181fa14 04/10: Increase description of `TeX-modes' in the document

[Tassilo Horn]

branch: externals/auctex
commit 09a181fa148d27c0351097bdb5da1ed018a49112
Author: Ikumi Keita <ikumi@ikumi.que.jp>
Commit: Ikumi Keita <ikumi@ikumi.que.jp>

    Increase description of `TeX-modes' in the document
    
    * doc/install.texi (Loading the package): Increase the explanation of
    the purpose and usage of `TeX-modes' with proper entry of @defopt.
    Add a paragraph for an alternative method to arrange the redirections.
    ; Update copyright year.
---
 doc/install.texi | 28 ++++++++++++++++++++++++----
 1 file changed, 24 insertions(+), 4 deletions(-)

diff --git a/doc/install.texi b/doc/install.texi
index 52be62f932..c2499e63dc 100644
--- a/doc/install.texi
+++ b/doc/install.texi
@@ -1,6 +1,6 @@
 @c This is part of the AUCTeX Manual.
 @c Copyright (C) 1994, 1996, 2003-2007, 2012-2013,
-@c               2015-2023  Free Software Foundation, Inc.
+@c               2015-2024  Free Software Foundation, Inc.
 @c See the file auctex.texi for copying conditions.
 @ifset rawfile
 @include macros.texi
@@ -353,11 +353,31 @@ below.
 @end ifclear
 
 Once activated, the modes provided by @AUCTeX{} are used per default for
-all supported file types.  If you want to change the modes for which it
-is operative instead of the default, use
+all supported file types, namely @code{plain-tex-mode}, @code{latex-mode},
+@code{doctex-mode} and @code{texinfo-mode}.  This might not match your
+preference.  You can have control over which @AUCTeX{} mode is activated
+per file types by @code{TeX-modes} option.  For example, you can use Emacs
+built-in @code{plain-tex-mode} for plain @TeX{} files while you can use
+@AUCTeX{} @code{LaTeX-mode} for @LaTeX{} files.
+
+@defopt TeX-modes
+List of Emacs built-in @TeX{} modes redirected to @AUCTeX{} modes.  If you
+prefer a particular built-in mode over @AUCTeX{} mode, remove it from this
+list.  Type
 @example
 @kbd{M-x customize-option @key{RET} TeX-modes @key{RET}}
 @end example
+@noindent
+to manipulate the contents of @code{TeX-modes}.
+@end defopt
+
+Don't remove @code{tex-mode} from @code{TeX-modes} because it results in
+inconsistent behavior.
+
+On Emacs 29 and later, you can alter @code{major-mode-remap-alist} instead
+of @code{TeX-modes} as you like to arrange @AUCTeX{} redirections.  In
+fact, @code{TeX-modes} option does nothing other than setting up
+@code{major-mode-remap-alist} according its value on those Emacsens.
 
 If you want to remove a preinstalled @AUCTeX{} completely before any of
 its modes have been used,
@@ -365,7 +385,7 @@ its modes have been used,
 (unload-feature 'tex-site)
 @end lisp
 @noindent
-should accomplish that.
+in your init file should accomplish that.
 
 @node Advice for package providers
 @section Providing @AUCTeX{} as a package