; Improve documentation of EditorConfig support

* doc/emacs/custom.texi (EditorConfig support): Improve wording
and indexing.
* doc/emacs/emacs.texi (Top): Update @detailmenu.

(cherry picked from commit 4f030834994ce06822779fe0f2c316a941ee6ea8)

diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index c7dad72e911f257f99422b7e2e29d7de9c299311..4ea335365cb8362a4967e851a182fbb0a9480222 100644 (file)
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -1557,25 +1557,35 @@ as Dired buffers (@pxref{Dired}).
 @node EditorConfig support
 @subsubsection Per-Directory Variables via EditorConfig
 @cindex EditorConfig support
+@cindex directory-local variables, via EditorConfig
+@cindex per-directory local variables, via EditorConfig
 
 The @uref{https://editorconfig.org/, EditorConfig standard}
 is an alternative to the @file{.dir-locals.el}
 files, which can control only a very small number of variables, but
-has the advantage of being editor-neutral.  Those settings are stored in
-files named @file{.editorconfig}.
-
-If you want Emacs to obey those settings, you need to enable
-the @code{editorconfig-mode} minor mode.  This is usually all that is
-needed: when the mode is activated, Emacs will look for @file{.editorconfig}
-files whenever a file is visited, just as it does for @file{.dir-locals.el}.
-When both @file{.editorconfig} and @file{.dir-locals.el} files are
-found, their settings are combined, and in case of a conflict, the
-setting coming from the closest file takes precedence.
-If they are equally close, @file{.dir-locals.el} takes precedence.
-In terms of security, those settings are subject to the same checks
-as those coming from @file{.dir-locals.el} (and also honor
-@code{enable-local-variables}).
-
+has the advantage of being editor-neutral, not specific to Emacs.  Those
+settings are stored in files named @file{.editorconfig}, and affect the
+files in that directory and its subdirectories.
+
+@findex editorconfig-mode
+@vindex enable-local-variables@r{, and EditorConfig settings}
+If you want Emacs to obey the settings from @file{.editorconfig} files,
+you need to enable the @code{editorconfig-mode} global minor mode.  This
+is usually all that is needed: when the mode is activated, whenever a
+file is visited, Emacs will look for @file{.editorconfig} in the file's
+directory and its parent directories, just as it does for
+@file{.dir-locals.el}.  When both @file{.editorconfig} and
+@file{.dir-locals.el} files are found, their settings are combined, and
+in case of a conflict, the setting coming from the file closest in the
+directory hierarchy takes precedence.  If they are equally close,
+@file{.dir-locals.el} takes precedence.  In terms of security, the
+@file{.editorconfig} settings are subject to the same checks as those
+coming from @file{.dir-locals.el} and from file-local variables (and
+also honor @code{enable-local-variables}).  @xref{Safe File Variables}.
+
+@cindex @code{indent_size} setting of EditorConfig
+@vindex editorconfig-indent-size-vars
+@vindex editorconfig-indentation-alist
 The @code{indent_size} setting of the EditorConfig standard does not
 correspond to a fixed variable in Emacs, but instead needs to set
 different variables depending on the major mode.  Ideally all major
@@ -1585,12 +1595,15 @@ effect because the major mode does not yet support it, you can customize
 the @code{editorconfig-indentation-alist} variable to tell Emacs which
 variables need to be set in that major mode.
 
+@cindex @code{trim_trailing_whitespace} setting of EditorConfig
+@vindex editorconfig-trim-whitespaces-mode
+@findex delete-trailing-whitespace, and EditorConfig settings
 Similarly, there are several different ways to trim whitespace at
 the end of lines.  When the EditorConfig @code{trim_trailing_whitespace}
 setting is used, by default @code{editorconfig-mode} simply calls
-@code{delete-trailing-whitespace} every time you save your file.
-If you prefer some other behavior, You can customize
-@code{editorconfig-trim-whitespaces-mode} to the minor mode of
+@code{delete-trailing-whitespace} (@pxref{Useless Whitespace}) every
+time you save your file.  If you prefer some other behavior, you can
+customize @code{editorconfig-trim-whitespaces-mode} to the minor mode of
 your preference, such as @code{ws-butler-mode}.
 
 @node Connection Variables

diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index 08b90f8599349b00a7428e194028dd2d5ebb2212..d2258faa6251bf0c482f9ea550dc82c5d4d5bb5b 100644 (file)
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -1169,6 +1169,10 @@ Local Variables in Files
 * Specifying File Variables:: Specifying file local variables.
 * Safe File Variables::       Making sure file local variables are safe.
 
+Local Variables in Directories
+
+* EditorConfig support::  Per-Directory Variables via EditorConfig
+
 Customizing Key Bindings
 
 * Keymaps::             Generalities.  The global keymap.