From 160f0bedeb45df6815e0331e743cfaa74ca9753f Mon Sep 17 00:00:00 2001 From: Stefan Monnier Date: Tue, 18 Jun 2024 19:00:29 -0400 Subject: [PATCH] Add doc for EditorConfig support Also, remove the old `editorconfig.texi` since most of it is not applicable to the (current) bundled version of the code anyway. * etc/NEWS: Add entry for EditorConfig. * doc/emacs/custom.texi (EditorConfig support): New node. (cherry picked from commit d236b67622aa808a20b6da6e7f4eb93523acd80c) --- doc/emacs/custom.texi | 35 +++++ doc/man/editorconfig.texi | 298 -------------------------------------- etc/NEWS | 8 + 3 files changed, 43 insertions(+), 298 deletions(-) delete mode 100644 doc/man/editorconfig.texi diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi index 1d6419d78f1..c0ff573b13b 100644 --- a/doc/emacs/custom.texi +++ b/doc/emacs/custom.texi @@ -1550,6 +1550,41 @@ variables are handled in the same way as unsafe file-local variables do not visit a file directly but perform work within a directory, such as Dired buffers (@pxref{Dired}). +@node EditorConfig support +@subsubsection Per-Directory Variables via EditorConfig +@cindex EditorConfig support + +The EditorConfig standard is an alternative to the @code{.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 @code{.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 @code{.editorconfig} +files whenever a file is visited, just as it does for @code{.dir-locals.el}. + +When both @code{.editorconfig} and @code{.dir-locals.el} files are +encountered, the corresponding settings are combined, and in case there +is overlap, the settings coming from the nearest file take precedence. + +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 +modes should set the corresponding @code{editorconfig-indent-size-vars}, +but if you use a major mode in which @code{indent_size} does not take +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. + +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 +your preference, such as @code{ws-butler-mode}. + @node Connection Variables @subsection Per-Connection Local Variables @cindex local variables, for all remote connections diff --git a/doc/man/editorconfig.texi b/doc/man/editorconfig.texi deleted file mode 100644 index 98bc87743a5..00000000000 --- a/doc/man/editorconfig.texi +++ /dev/null @@ -1,298 +0,0 @@ -@dircategory Emacs -@direntry -* EditorConfig: (editorconfig). EditorConfig Plugin. -@end direntry - -@node Top -@chapter EditorConfig Plugin -@anchor{#editorconfig-emacs-plugin} -This is an @uref{https://editorconfig.org,EditorConfig} plugin for -@uref{https://www.gnu.org/software/emacs/,Emacs}. - -@menu -* Getting Started:: -* Supported properties:: -* Customize:: -* Troubleshooting:: -* Submitting Bugs and Feature Requests:: -* License:: -@end menu - -@node Getting Started -@section Getting Started -@anchor{#getting-started} - -@menu -* package:: -* use-package:: -* Manual installation:: -@end menu - -@node package -@subsection package.el -@anchor{#package.el} - -This package is shipped with Emacs. More recent versions can be -installed from -@uref{http://elpa.nongnu.org/nongnu/editorconfig.html,NonGNU ELPA}. - -Install from these repositories and enable global minor-mode -@code{editorconfig-mode}: - -@verbatim -(editorconfig-mode 1) -@end verbatim - -Normally, enabling @code{editorconfig-mode} should be enough for this -plugin to work: all other configurations are optional. This mode sets up -hooks so that EditorConfig properties will be loaded and applied to the -new buffers automatically when visiting files. - -@node use-package -@subsection use-package -@anchor{#use-package} -If you use -@uref{https://www.emacswiki.org/emacs/UsePackage,@strong{use-package}}, -add the following to your @code{init.el} file: - -@verbatim -(use-package editorconfig - :ensure t - :config - (editorconfig-mode 1)) -@end verbatim - -@node Manual installation -@subsection Manual installation -@anchor{#manual-installation} -Copy all @code{.el} files in this repository to @code{~/.emacs.d/lisp} -and add the following: - -@verbatim -(add-to-list 'load-path "~/.emacs.d/lisp") -(require 'editorconfig) -(editorconfig-mode 1) -@end verbatim - -@node Supported properties -@section Supported properties -@anchor{#supported-properties} -Current Emacs plugin coverage for EditorConfig's -@uref{https://editorconfig.org/#supported-properties,properties}: - -@itemize -@item -@code{indent_style} -@item -@code{indent_size} -@item -@code{tab_width} -@item -@code{end_of_line} -@item -@code{charset} -@item -@code{trim_trailing_whitespace} -@item -@code{insert_final_newline = true} is supported -@item -@code{insert_final_newline = false} -is not enforced (as in trailing newlines actually being removed -automagically), we just buffer-locally override any preferences that -would auto-add them to files @code{.editorconfig} marks as -trailing-newline-free -@item -@code{max_line_length} -@item -@code{file_type_ext} (Experimental) -(See below) -@item -@code{file_type_emacs} (Experimental) -(See below) -@item -@code{root} (only used by EditorConfig core) -@end itemize - -Not yet covered properties marked with over-strike -- pull requests -implementing missing features warmly welcomed! Typically, you will want -to tie these to native functionality, or the configuration of existing -packages handling the feature. - -As several packages have their own handling of, say, indentation, we -might not yet cover some mode you use, but we try to add the ones that -show up on our radar. - -@menu -* File Type file_type_ext file_type_emacs:: -@end menu - -@node File Type file_type_ext file_type_emacs -@subsection File Type (file_type_ext, file_type_emacs) -@anchor{#file-type-file_type_ext-file_type_emacs} -File-type feature is currently disabled, because this package is now -undergoing big internal refactoring. For those who want this -functionality, please consider using -@uref{https://github.com/10sr/editorconfig-custom-majormode-el,editorconfig-custom-majormode}. - -@node Customize -@section Customize -@anchor{#customize} -@code{editorconfig-emacs} provides some customize variables. - -Here are some of these variables: for the full list of available -variables, type M-x customize-group [RET] editorconfig [RET]. - -@menu -* editorconfig-trim-whitespaces-mode:: -* editorconfig-after-apply-functions:: -* editorconfig-hack-properties-functions:: -@end menu - -@node editorconfig-trim-whitespaces-mode -@subsection @code{editorconfig-trim-whitespaces-mode} -@anchor{#editorconfig-trim-whitespaces-mode} -Buffer local minor-mode to use to trim trailing whitespaces. - -If set, editorconfig will enable/disable this mode in accord with -@code{trim_trailing_whitespace} property in @code{.editorconfig}. -Otherwise, use Emacs built-in @code{delete-trailing-whitespace} -function. - -One possible value is -@uref{https://github.com/lewang/ws-butler,@code{ws-butler-mode}}, with -which only lines touched get trimmed. To use it, add following to your -init.el: - -@verbatim -(setq editorconfig-trim-whitespaces-mode - 'ws-butler-mode) -@end verbatim - -@node editorconfig-after-apply-functions -@subsection @code{editorconfig-after-apply-functions} -@anchor{#editorconfig-after-apply-functions} -(Formerly @code{editorconfig-custom-hooks}) - -A list of functions which will be called after loading common -EditorConfig settings, when you can set some custom variables. - -For example, @code{web-mode} has several variables for indentation -offset size and EditorConfig sets them at once by @code{indent_size}. -You can stop indenting only blocks of @code{web-mode} by adding -following to your init.el: - -@verbatim -(add-hook 'editorconfig-after-apply-functions - (lambda (props) (setq web-mode-block-padding 0))) -@end verbatim - -@node editorconfig-hack-properties-functions -@subsection @code{editorconfig-hack-properties-functions} -@anchor{#editorconfig-hack-properties-functions} -A list of functions to alter property values before applying them. - -These functions will be run after loading ".editorconfig" files and -before applying them to current buffer, so that you can alter some -properties from ".editorconfig" before they take effect. - -For example, Makefile files always use tab characters for indentation: -you can overwrite "indent_style" property when current @code{major-mode} -is @code{makefile-mode}: - -@verbatim -(add-hook 'editorconfig-hack-properties-functions - '(lambda (props) - (when (derived-mode-p 'makefile-mode) - (puthash 'indent_style "tab" props)))) -@end verbatim - -@node Troubleshooting -@section Troubleshooting -@anchor{#troubleshooting} -Enabling @code{editorconfig-mode} should be enough for normal cases. - -When EditorConfig properties are not effective for unknown reason, we -recommend first trying -@code{M-x editorconfig-display-current-properties}. - -This command will open a new buffer and display the EditorConfig -properties loaded for current buffer. You can check if EditorConfig -properties were not read for buffers at all, or they were loaded but did -not take effect for some other reasons. - -@menu -* Indentation for new major-modes:: -* Not work at all for FOO-mode!:: -@end menu - -@node Indentation for new major-modes -@subsection Indentation for new major-modes -@anchor{#indentation-for-new-major-modes} -Because most Emacs major-modes have their own indentation settings, this -plugin requires explicit support for each major-mode for -@code{indent_size} property. - -By default this plugin ships with settings for many major-modes, but, -sorry to say, it cannot be perfect. Especially it is difficult to -support brand-new major-modes. Please feel free to submit issue or -pull-request for such major-mode! - -Supported major-modes and their indentation configs are defined in the -variable @code{editorconfig-indentation-alist}. - -@node Not work at all for FOO-mode! -@subsection Not work at all for FOO-mode! -@anchor{#not-work-at-all-for-foo-mode} -Most cases properties are loaded just after visiting files when -@code{editorconfig-mode} is enabled. But it is known that there are -major-modes that this mechanism does not work for and require explicit -call of @code{editorconfig-apply}. - -Typically it will occur when the major-mode is not defined using -@code{define-derived-mode} (@code{rpm-spec-mode} is an example for -this). Please feel free to submit issues if you find such modes! - -@node Submitting Bugs and Feature Requests -@section Submitting Bugs and Feature Requests -@anchor{#submitting-bugs-and-feature-requests} -Bugs, feature requests, and other issues should be submitted to the -issue tracker: https://github.com/editorconfig/editorconfig-emacs/issues - -@menu -* Development:: -@end menu - -@node Development -@subsection Development -@anchor{#development} -Make and @uref{https://cmake.org,CMake} must be installed to run the -tests locally: - -@verbatim -$ make check -@end verbatim - -To start a new Emacs process with current @code{*.el} and without -loading user init file, run: - -@verbatim -$ make sandbox -@end verbatim - -@node License -@section License -@anchor{#license} -EditorConfig Emacs Plugin is free software: you can redistribute it -and/or modify it under the terms of the GNU General Public License as -published by the Free Software Foundation, either version 3 of the -License, or (at your option) any later version. - -This program is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General -Public License for more details. - -You should have received a copy of the GNU General Public License along -with this program. If not, see @url{https://www.gnu.org/licenses/}. - -@bye diff --git a/etc/NEWS b/etc/NEWS index 5abcf88847d..cfcf6923c93 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -2057,6 +2057,14 @@ The following new XML schemas are now supported: * New Modes and Packages in Emacs 30.1 +** New package EditorConfig. +This package provides support for the EditorConfig standard that +is an editor-neutral way to provide directory local settings. +It is enabled via a new global minor mode 'editorconfig-mode' +which makes Emacs obey the '.editorconfig' files. +And the package also comes with a new major mode 'editorconfig-conf-mode' +to edit those configuration files. + +++ ** New package Track-Changes. This library is a layer of abstraction above 'before-change-functions' -- 2.39.2