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
+++ /dev/null
-@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
projects / emacs.git / commitdiff