@dircategory Emacs
@direntry
* EditorConfig: (editorconfig). EditorConfig Emacs Plugin.
@end direntry

@node Top
@chapter EditorConfig Emacs Plugin
@anchor{#editorconfig-emacs-plugin}
This is an @uref{https://editorconfig.org,EditorConfig} plugin for
@uref{https://www.gnu.org/software/emacs/,Emacs}.
@menu
* Installation::
* Supported properties::
* Customize::
* Testing::
* Submitting Bugs and Feature Requests::
* License::
@end menu

@node Installation
@section Installation
@anchor{#installation}
Download the
@uref{https://github.com/editorconfig/editorconfig-core-c,EditorConfig C
Core} and follow the instructions in the README and INSTALL files to
install it.

This plugin also has a built-in core library implemented in Emacs-Lisp,
and fallback to it when no core executable is found.

In either case, copy @code{.el} files in this repository to
@code{~/.emacs.d/lisp} and add the following to your @code{~/.emacs}
file:

@verbatim
(add-to-list 'load-path "~/.emacs.d/lisp")
(require 'editorconfig)
(editorconfig-mode 1)
@end verbatim

Alternatively, you can find the package available on
@uref{https://melpa.org/#/editorconfig,MELPA} and
@uref{https://stable.melpa.org/#/editorconfig,MELPA Stable}
(@uref{http://marmalade-repo.org/packages/editorconfig,The Marmalade
package} is deprecated).

Or if you use
@uref{https://www.emacswiki.org/emacs/UsePackage,@strong{use-package}}:

@verbatim
(use-package editorconfig
  :ensure t
  :config
  (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)
@item
@code{file_type_emacs} (Experimental)
@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, indention, we might
not yet cover some mode you use, but we try to add the ones that show up
on our radar. Similarly, we don't yet hook in to all different packages
for whitespace trimming to inform them about editorconfig settings, but
aim for better coverage of things like
@uref{ftp://ftp.lysator.liu.se/pub/emacs/ws-trim.el,ws-trim}.
@menu
* File Type::
@end menu

@node File Type
@subsection File Type
@anchor{#file-type}
This plugin has experimental supports for @code{file_type_ext} and
@code{file_type_emacs}, which specify ``file types'' for files. As for
Emacs, it means @code{major-mode} can be set.

@strong{file_type_ext} When it is set to @code{md} for @code{a.txt}, for
example, @code{major-mode} will be decided as if the file name would be
@code{a.txt.md} (and thus @code{markdown-mode} is likely to be used).

@strong{file_type_emacs} When it is set to @code{markdown} for
@code{a.txt}, @code{markdown-mode} will be enabled when opening
@code{a.txt}.

These property are experimental and their meanings might change in the
future updates. When both are specified, @code{file_type_ext} takes
precedence.

@node Customize
@section Customize
@anchor{#customize}
@menu
* editorconfig-after-apply-functions::
* editorconfig-hack-properties-functions::
* editorconfig-indentation-alist::
* editorconfig-exec-path::
* editorconfig-get-properties-function::
@end menu

@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 after loading common EditorConfig settings, where
you can set some custom variables or overwrite existing properties.

For example, @code{web-mode} has several variables for indentation
offset size and EditorConfig sets them at once by @code{indent_size}.
You may want to stop indenting only blocks of @code{web-mode}: it can be
achieved by adding following to your init.el:

@verbatim
(add-hook 'editorconfig-after-apply-functions
  (lambda (hash) (setq web-mode-block-padding 0)))
@end verbatim

You can also define your own custom properties and enable them here.

@node editorconfig-hack-properties-functions
@subsection @code{editorconfig-hack-properties-functions}
@anchor{#editorconfig-hack-properties-functions}
A list of function 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, Makefiles always use tab characters for indentation: you
can overwrite "indent_style" property when current @code{major-mode} is
a @code{makefile-mode} with following code:

@verbatim
(add-hook 'editorconfig-hack-properties-functions
          '(lambda (props)
             (when (derived-mode-p 'makefile-mode)
               (puthash 'indent_style "tab" props))))
@end verbatim

@node editorconfig-indentation-alist
@subsection @code{editorconfig-indentation-alist}
@anchor{#editorconfig-indentation-alist}
Alist of indentation setting methods by modes.

For the easiest case to add a new support for a major-mode, you just
need to add a pair of major-mode symbol and its indentation variables:

@verbatim
(add-to-list 'editorconfig-indentation-alist
  ;; Just an example, of course EditorConfig has already included this setting!
  '(c-mode c-basic-offset))
@end verbatim

You can also modify this variable with the command M-x
customize-variable [RET] editorconfig-indentation-alist [RET]. For a bit
more complicated cases please take a look at the docstring of this
variable.

@node editorconfig-exec-path
@subsection @code{editorconfig-exec-path}
@anchor{#editorconfig-exec-path}
String of @code{editorconfig} executable name (command name or full path
to the executable).

@node editorconfig-get-properties-function
@subsection @code{editorconfig-get-properties-function}
@anchor{#editorconfig-get-properties-function}
Function to use to get EditorConfig properties.

For example, if you always want to use built-in core library instead of
any EditorConfig executable to get properties, add following to your
init.el:

@verbatim
(set-variable 'editorconfig-get-properties-function
              #'editorconfig-core-get-properties-hash)
@end verbatim

Possible known values are:

@itemize
@item
@code{editorconfig-get-properties} (default)
@itemize
@item
Use @code{editorconfig-get-properties-from-exec} when
@code{editorconfig-exec-path} executable is found, otherwise use
@code{editorconfig-core-get-properties-hash}
@end itemize

@item
@code{editorconfig-get-properties-from-exec}
@itemize
@item
Get properties by executing EditorConfig executable specified in
@code{editorconfig-exec-path}
@end itemize

@item
@code{editorconfig-core-get-properties-hash}
@itemize
@item
Always use built-in Emacs-Lisp implementation to get properties
@end itemize

@end itemize

@node Testing
@section Testing
@anchor{#testing}
Make and @uref{https://cmake.org,CMake} must be installed to run the
tests.

To run the tests:

@verbatim
$ make test
@end verbatim

@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

@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
