Fix #1610 - Encourage the use of ftplugin files more

2 files changed, 63 insertions, 14 deletions

diff --git a/README.md b/README.md
index 492f52cc..80904a8a 100644
--- a/README.md
+++ b/README.md
@@ -210,24 +210,42 @@ ale-linter-options` for options specified to particular linters.
 ### 2.ii Fixing
 
 ALE can fix files with the `ALEFix` command. Functions need to be configured
-for different filetypes with the `g:ale_fixers` variable. For example, the
-following code can be used to fix JavaScript code with ESLint:
+either in each buffer with a `b:ale_fixers`, or globally with `g:ale_fixers`.
+
+The recommended way to configure fixers is to define a List in an ftplugin file.
+
+```vim
+" In ~/.vim/ftplugin/javascript.vim, or somewhere similar.
+
+" Fix files with prettier, and then ESLint.
+let b:ale_fixers = ['prettier', 'eslint']
+" Equivalent to the above.
+let b:ale_fixers = {'javascript': ['prettier', 'eslint']}
+```
+
+You can also configure your fixers from vimrc using `g:ale_fixers`, before
+or after ALE has been loaded.
 
 ```vim
-" Put this in vimrc or a plugin file of your own.
-" After this is configured, :ALEFix will try and fix your JS code with ESLint.
+" In ~/.vim/vimrc, or somewhere similar.
 let g:ale_fixers = {
 \   'javascript': ['eslint'],
 \}
+```
+
+If you want to automatically fix files when you save them, you need to turn
+a setting on in vimrc.
 
-" Set this setting in vimrc if you want to fix files automatically on save.
-" This is off by default.
+```vim
+" Set this variable to 1 to fix files when you save them.
 let g:ale_fix_on_save = 1
 ```
 
-The `:ALEFixSuggest` command will suggest some supported tools for fixing code,
-but fixers can be also implemented with functions, including lambda functions
-too. See `:help ale-fix` for detailed information.
+The `:ALEFixSuggest` command will suggest some supported tools for fixing code.
+Both `g:ale_fixers` and `b:ale_fixers` can also accept functions, including
+lambda functions, as fixers, for fixing files with custom tools.
+
+See `:help ale-fix` for complete information on how to fix files with ALE.
 
 <a name="usage-completion"></a>
 
@@ -385,12 +403,28 @@ on Freenode. Web chat is available [here](https://webchat.freenode.net/?channels
 
 ### 5.i. How do I disable particular linters?
 
-By default, all available tools for all supported languages will be run.
-If you want to only select a subset of the tools, simply create a
-`g:ale_linters` dictionary in your vimrc file mapping filetypes
-to lists of linters to run.
+By default, all available tools for all supported languages will be run. If you
+want to only select a subset of the tools, you can define `b:ale_linters` for a
+single buffer, or `g:ale_linters` globally.
+
+The recommended way to configure linters is to define a List in an ftplugin
+file.
 
 ```vim
+" In ~/.vim/ftplugin/javascript.vim, or somewhere similar.
+
+" Enable ESLint only for JavaScript.
+let b:ale_linters = ['eslint']
+
+" Equivalent to the above.
+let b:ale_linters = {'javascript': ['eslint']}
+```
+
+You can also declare which linters you want to run in your vimrc file, before or
+after ALE has been loaded.
+
+```vim
+" In ~/.vim/vimrc, or somewhere similar.
 let g:ale_linters = {
 \   'javascript': ['eslint'],
 \}
@@ -650,9 +684,18 @@ augroup END
 ```
 
 Supposing the filetype has been set correctly, you can set the following
-options in your vimrc file:
+options in a jsx.vim ftplugin file.
+
+```vim
+" In ~/.vim/ftplugin/jsx.vim, or somewhere similar.
+let b:ale_linters = ['stylelint', 'eslint']
+let b:ale_linter_aliases = ['css']
+```
+
+Or if you want, you can configure the linters from your vimrc file.
 
 ```vim
+" In ~/.vim/vimrc, or somewhere similar.
 let g:ale_linters = {'jsx': ['stylelint', 'eslint']}
 let g:ale_linter_aliases = {'jsx': 'css'}
 ```
diff --git a/doc/ale.txt b/doc/ale.txt
index b6122c3e..2b4452d9 100644
--- a/doc/ale.txt
+++ b/doc/ale.txt
@@ -475,6 +475,12 @@ the buffer-local options can be used with external plugins for reading Vim
 project configuration files. Buffer-local settings can also be used in
 ftplugin files for different filetypes.
 
+ALE offers several options for controlling which linters are run.
+
+* Selecting linters to run.            - |g:ale_linters|
+* Aliasing filetypes for linters       - |g:ale_linter_aliases|
+* Only running linters you asked for.  - |g:ale_linters_explicit|
+
 
 ===============================================================================
 4. Fixing Problems                                                    *ale-fix*