From e3c06a451afaca49ef6fa3718100a08b5854026e Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 22 Jun 2024 09:01:12 +0300 Subject: [PATCH] ; 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) --- doc/emacs/custom.texi | 49 +++++++++++++++++++++++++++---------------- doc/emacs/emacs.texi | 4 ++++ 2 files changed, 35 insertions(+), 18 deletions(-) diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi index c7dad72e911..4ea335365cb 100644 --- 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 08b90f85993..d2258faa625 100644 --- 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. -- 2.39.2