Fix - #883 Document linting behavior better, sync up the lists of supported tools, andautomatically demand that they stay in sync

1 files changed, 254 insertions, 178 deletions

diff --git a/doc/ale.txt b/doc/ale.txt
index 6c3be18e..481c531d 100644
--- a/doc/ale.txt
+++ b/doc/ale.txt
@@ -8,11 +8,12 @@ CONTENTS                                                         *ale-contents*
 
   1. Introduction.........................|ale-introduction|
   2. Supported Languages & Tools..........|ale-support|
-  3. Global Options.......................|ale-options|
-    3.1 Highlights........................|ale-highlights|
+  3. Linting..............................|ale-lint|
   4. Fixing Problems......................|ale-fix|
   5. Completion...........................|ale-completion|
-  6. Integration Documentation............|ale-integrations|
+  6. Global Options.......................|ale-options|
+    6.1 Highlights........................|ale-highlights|
+  7. Integration Documentation............|ale-integrations|
     asm...................................|ale-asm-options|
       gcc.................................|ale-asm-gcc|
     c.....................................|ale-c-options|
@@ -140,10 +141,10 @@ CONTENTS                                                         *ale-contents*
     yaml..................................|ale-yaml-options|
       swaglint............................|ale-yaml-swaglint|
       yamllint............................|ale-yaml-yamllint|
-  7. Commands/Keybinds....................|ale-commands|
-  8. API..................................|ale-api|
-  9. Special Thanks.......................|ale-special-thanks|
-  10. Contact.............................|ale-contact|
+  8. Commands/Keybinds....................|ale-commands|
+  9. API..................................|ale-api|
+  10. Special Thanks......................|ale-special-thanks|
+  11. Contact.............................|ale-contact|
 
 ===============================================================================
 1. Introduction                                              *ale-introduction*
@@ -174,80 +175,246 @@ for the current buffer.
 
 The following languages and tools are supported.
 
-* ASM: 'gcc'
-* Ansible: 'ansible-lint'
-* Asciidoc: 'proselint'
-* Bash: 'shell' (-n flag), 'shellcheck'
-* Bourne Shell: 'shell' (-n flag), 'shellcheck'
-* C: 'cppcheck', 'gcc', 'clang', 'clang-format'
-* C++ (filetype cpp): 'clang', 'clangtidy', 'cppcheck', 'cpplint', 'gcc', 'clang-format'
-* C#: 'mcs'
-* Chef: 'foodcritic'
-* CMake: 'cmakelint'
-* CoffeeScript: 'coffee', 'coffelint'
-* Crystal: 'crystal'
-* CSS: 'csslint', 'stylelint'
-* Cython (pyrex filetype): 'cython'
-* D: 'dmd'
-* Dart: 'dartanalyzer'
-* Dockerfile: 'hadolint'
-* Elixir: 'credo', 'dogma'
-* Elm: 'elm-make'
-* Erlang: 'erlc'
-* Fortran: 'gcc'
-* Go: 'gofmt', 'go vet', 'golint', 'go build', 'gosimple', 'staticcheck'
-* FusionScript: 'fusion-lint'
-* Haml: 'hamllint'
-* Handlebars: 'ember-template-lint'
-* Haskell: 'ghc', 'stack-ghc', 'stack-build', 'ghc-mod', 'stack-ghc-mod', 'hlint', 'hdevtools'
-* HTML: 'HTMLHint', 'proselint', 'tidy'
-* Idris: 'idris'
-* Java: 'javac'
-* JavaScript: 'eslint', 'jscs', 'jshint', 'flow', 'prettier', 'prettier-eslint', 'xo'
-* JSON: 'jsonlint'
-* Kotlin: 'kotlinc'
-* LaTeX (tex): 'chktex', 'lacheck', 'proselint'
-* Lua: 'luacheck'
-* Markdown: 'mdl', 'proselint', 'vale'
-* MATLAB: 'mlint'
-* nim: 'nim check'
-* nix: 'nix-instantiate'
-* nroff: 'proselint'
-* Objective-C: 'clang'
-* Objective-C++: 'clang'
-* OCaml: 'merlin' (see |ale-ocaml-merlin|)
-* Perl: 'perl' (-c flag), 'perlcritic'
-* PHP: 'hack', 'langserver', 'php' (-l flag), 'phpcs', 'phpmd', 'phpstan', 'phpcbf'
-* Pod: 'proselint'
-* Pug: 'pug-lint'
-* Puppet: 'puppet', 'puppet-lint'
-* Python: 'autopep8', 'flake8', 'isort', 'mypy', 'pylint', 'yapf'
-* R: 'lintr'
-* ReasonML: 'merlin'
-* reStructuredText: 'proselint'
-* RPM spec: 'spec'
-* Rust: 'cargo', 'rls', 'rustc' (see |ale-integration-rust|)
-* Ruby: 'reek', 'rubocop'
-* SASS: 'sasslint', 'stylelint'
-* SCSS: 'sasslint', 'scsslint', 'stylelint'
-* Scala: 'scalac', 'scalastyle'
-* Slim: 'slim-lint'
-* SML: 'smlnj'
-* Stylus: 'stylelint'
-* SQL: 'sqlint'
-* Swift: 'swiftlint', 'swiftformat'
-* Texinfo: 'proselint'
-* Text: 'proselint', 'vale'
-* TypeScript: 'eslint', 'tslint', 'tsserver', 'typecheck'
-* Verilog: 'iverilog', 'verilator'
-* Vim: 'vint'
-* Vim help: 'proselint'
-* XHTML: 'proselint'
-* XML: 'xmllint'
-* YAML: 'swaglint', 'yamllint'
+Notes:
+
+`^` No linters for text or Vim help filetypes are enabled by default.
+`!` These linters check only files on disk. See |ale-lint-file-linters|
+
+* ASM: `gcc`
+* Ansible: `ansible-lint`
+* AsciiDoc: `proselint`
+* Awk: `gawk`
+* Bash: `shell` (-n flag), `shellcheck`
+* Bourne Shell: `shell` (-n flag), `shellcheck`
+* C: `cppcheck`, `cpplint`!, `gcc`, `clang`, `clang-format`
+* C++ (filetype cpp): `clang`, `clangcheck`!, `clangtidy`!, `cppcheck`, `cpplint`!, `gcc`, `clang-format`
+* C#: `mcs`
+* Chef: `foodcritic`
+* CMake: `cmakelint`
+* CoffeeScript: `coffee`, `coffeelint`
+* Crystal: `crystal`!
+* CSS: `csslint`, `stylelint`
+* Cython (pyrex filetype): `cython`
+* D: `dmd`
+* Dart: `dartanalyzer`
+* Dockerfile: `hadolint`
+* Elixir: `credo`, `dogma`!
+* Elm: `elm-make`
+* Erb: `erb`, `erubis`
+* Erlang: `erlc`, `SyntaxErl`
+* Fortran: `gcc`
+* FusionScript: `fusion-lint`
+* Go: `gofmt`, `go vet`, `golint`, `gometalinter`!, `go build`!, `gosimple`, `staticcheck`
+* GraphQL: `gqlint`
+* Haml: `haml-lint`
+* Handlebars: `ember-template-lint`
+* Haskell: `ghc`, `stack-ghc`, `stack-build`!, `ghc-mod`, `stack-ghc-mod`, `hlint`, `hdevtools`
+* HTML: `HTMLHint`, `proselint`, `tidy`
+* Idris: `idris`
+* Java: `checkstyle`, `javac`
+* JavaScript: `eslint`, `jscs`, `jshint`, `flow`, `prettier`, `prettier-eslint`, `prettier-standard`, `standard`, `xo`
+* JSON: `jsonlint`
+* Kotlin: `kotlinc`, `ktlint`
+* LaTeX (tex): `chktex`, `lacheck`, `proselint`
+* Lua: `luacheck`
+* Markdown: `mdl`, `proselint`, `vale`
+* MATLAB: `mlint`
+* Nim: `nim check`!
+* nix: `nix-instantiate`
+* nroff: `proselint`
+* Objective-C: `clang`
+* Objective-C++: `clang`
+* OCaml: `merlin` (see |ale-ocaml-merlin|)
+* Perl: `perl -c`, `perl-critic`
+* PHP: `hack`, `langserver`, `php -l`, `phpcs`, `phpmd`, `phpstan`, `phpcbf`
+* Pod: `proselint`
+* Pug: `pug-lint`
+* Puppet: `puppet`, `puppet-lint`
+* Python: `autopep8`, `flake8`, `isort`, `mypy`, `pycodestyle`, `pylint`!, `yapf`
+* R: `lintr`
+* ReasonML: `merlin`
+* reStructuredText: `proselint`
+* RPM spec: `rpmlint`
+* Ruby: `brakeman`, `rails_best_practices`!, `reek`, `rubocop`, `ruby`
+* Rust: `cargo`!, `rls`, `rustc` (see |ale-integration-rust|)
+* SASS: `sass-lint`, `stylelint`
+* SCSS: `sass-lint`, `scss-lint`, `stylelint`
+* Scala: `scalac`, `scalastyle`
+* Slim: `slim-lint`
+* SML: `smlnj`
+* Stylus: `stylelint`
+* SQL: `sqlint`
+* Swift: `swiftlint`, `swiftformat`
+* Tcl: `nagelfar`!
+* Texinfo: `proselint`
+* Text^: `proselint`, `vale`
+* TypeScript: `eslint`, `tslint`, `tsserver`, `typecheck`
+* Verilog: `iverilog`, `verilator`
+* Vim: `vint`
+* Vim help^: `proselint`
+* XHTML: `proselint`
+* XML: `xmllint`
+* YAML: `swaglint`, `yamllint`
 
 ===============================================================================
-3. Global Options                                                 *ale-options*
+3. Linting                                                           *ale-lint*
+
+ALE's primary focus is on checking for problems with your code with various
+programs via some Vim code for integrating with those programs, referred to
+as 'linters.' ALE supports a wide array of programs for linting by default,
+but additional programs can be added easily by defining files in |runtimepath|
+with the filename pattern `ale_linters/<filetype>/<filename>.vim`. For more
+information on defining new linters, see the extensive documentation
+for |ale#linter#Define()|.
+
+Without any configuration, ALE will attempt to check all of the code for every
+file you open in Vim with all available tools by default. To see what ALE
+is doing, and what options have been set, try using the |:ALEInfo| command.
+
+Most of the linters ALE runs will check the Vim buffer you are editing instead
+of the file on disk. This allows you to check your code for errors before you
+have even saved your changes. ALE will check your code in the following
+circumstances, which can be configured with the associated options.
+
+* When you modify a buffer.                - |g:ale_lint_on_text_changed|
+* When you open a new or modified buffer.  - |g:ale_lint_on_enter|
+* When you save a buffer.                  - |g:ale_lint_on_save|
+* When the filetype changes for a buffer.  - |g:ale_lint_on_filetype_changed|
+* If ALE is used to check ccode manually.  - |:ALELint|
+
+In addition to the above options, ALE can also check buffers for errors when
+you leave insert mode with |g:ale_lint_on_insert_leave|, which is off by
+default. It is worth reading the documentation for every option.
+
+                                                        *ale-lint-file-linters*
+
+Some programs must be run against files which have been saved to disk, and
+simply do not support reading temporary files or stdin, either of which are
+required for ALE to be able to check for errors as you type. The programs
+which behave this way are documented in the lists and tables of supported
+programs. ALE will only lint files with these programs in the following
+circumstances.
+
+* When you open a new or modified buffer.  - |g:ale_lint_on_enter|
+* When you save a buffer.                  - |g:ale_lint_on_save|
+* When the filetype changes for a buffer.  - |g:ale_lint_on_filetype_changed|
+* If ALE is used to check ccode manually.  - |:ALELint|
+
+ALE will report problems with your code in the following ways, listed with
+their relevant options.
+
+* By updating loclist. (On by default)       - |g:ale_set_loclist|
+* By updating quickfix. (Off by default)     - |g:ale_set_quickfix|
+* By setting error highlights.               - |g:ale_set_highlights|
+* By creating signs in the sign column.      - |g:ale_set_signs|
+* By echoing messages based on your cursor.  - |g:ale_echo_cursor|
+* By showing balloons for your mouse cursor  - |g:ale_set_balloons|
+
+Please consult the documentation for each option, which can reveal some other
+ways of tweaking the behaviour of each way of displaying problems. You can
+disable or enable whichever options you prefer.
+
+Most settings can be configured for each buffer. (|b:| instead of |g:|),
+including disabling ALE for certain buffers with |b:ale_enabled|. The
+|g:ale_pattern_options| setting can be used to configure files differently
+based on regular expressions for filenames. For configuring entire projects,
+the buffer-local options can be used with external plugins for reading Vim
+project configuration files.
+
+
+===============================================================================
+4. Fixing Problems                                                    *ale-fix*
+
+ALE can fix problems with files with the |ALEFix| command. When |ALEFix| is
+run, the variable |g:ale_fixers| will be read for getting a |List| of commands
+for filetypes, split on `.`, and the functions named in |g:ale_fixers| will be
+executed for fixing the errors.
+
+The |ALEFixSuggest| command can be used to suggest tools that be used to
+fix problems for the current buffer.
+
+The values for `g:ale_fixers` can be a list of |String|, |Funcref|, or
+|lambda| values. String values must either name a function, or a short name
+for a function set in the ALE fixer registry.
+
+Each function for fixing errors must accept either one argument `(buffer)` or
+two arguments `(buffer, lines)`, representing the buffer being fixed and the
+lines to fix. The functions must return either `0`, for changing nothing, a
+|List| for new lines to set, or a |Dictionary| for describing a command to be
+run in the background.
+
+Functions receiving a variable number of arguments will not receive the second
+argument `lines`. Functions should name two arguments if the `lines` argument
+is desired. This is required to avoid unnecessary copying of the lines of
+the buffers being checked.
+
+When a |Dictionary| is returned for an |ALEFix| callback, the following keys
+are supported for running the commands.
+
+  `command`             A |String| for the command to run. This key is required.
+
+                      When `%t` is included in a command string, a temporary
+                      file will be created, containing the lines from the file
+                      after previous adjustment have been done.
+
+  `read_temporary_file` When set to `1`, ALE will read the contents of the
+                      temporary file created for `%t`. This option can be used
+                      for commands which need to modify some file on disk in
+                      order to fix files.
+
+                                                        *ale-fix-configuration*
+
+Synchronous functions and asynchronous jobs will be run in a sequence for
+fixing files, and can be combined. For example:
+>
+  let g:ale_fixers = {
+  \   'javascript': [
+  \       'DoSomething',
+  \       'eslint',
+  \       {buffer, lines -> filter(lines, 'v:val !=~ ''^\s*//''')},
+  \   ],
+  \}
+
+  ALEFix
+<
+The above example will call a function called `DoSomething` which could act
+upon some lines immediately, then run `eslint` from the ALE registry, and
+then call a lambda function which will remove every single line comment
+from the file.
+
+For convenience, a plug mapping is defined for |ALEFix|, so you can set up a
+keybind easily for fixing files. >
+
+  " Bind F8 to fixing problems with ALE
+  nmap <F8> <Plug>(ale_fix)
+<
+Files can be fixed automatically with the following options, which are all off
+by default.
+
+|g:ale_fix_on_save| - Fix files when they are saved.
+
+
+===============================================================================
+5. Completion                                                  *ale-completion*
+
+ALE offers some limited support for automatic completion of code while you
+type. Completion is only supported via Language Server Protocol servers which
+ALE can connect to for linting, which can offer good built-in support for
+suggesting completion information. ALE will only suggest symbols for
+completion for LSP linters that are enabled.
+
+NOTE: At the moment, only `tsserver` for TypeScript code is supported for
+completion.
+
+Suggestions will be made while you type after completion is enabled.
+Completion can be enabled by setting |g:ale_completion_enabled| to `1`. The
+delay for completion can be configured with |g:ale_completion_delay|. ALE will
+only suggest so many possible matches for completion. The maximum number of
+items can be controlled with |g:ale_completion_max_suggestions|.
+
+
+===============================================================================
+6. Global Options                                                 *ale-options*
 
 g:airline#extensions#ale#enabled             *g:airline#extensions#ale#enabled*
 
@@ -919,7 +1086,7 @@ b:ale_warn_about_trailing_whitespace     *b:ale_warn_about_trailing_whitespace*
 
 
 -------------------------------------------------------------------------------
-3.1. Highlights                                                *ale-highlights*
+6.1. Highlights                                                *ale-highlights*
 
 ALEError                                                             *ALEError*
 
@@ -1013,98 +1180,7 @@ ALEWarningSign                                                 *ALEWarningSign*
 
 
 ===============================================================================
-4. Fixing Problems                                                    *ale-fix*
-
-ALE can fix problems with files with the |ALEFix| command. When |ALEFix| is
-run, the variable |g:ale_fixers| will be read for getting a |List| of commands
-for filetypes, split on `.`, and the functions named in |g:ale_fixers| will be
-executed for fixing the errors.
-
-The |ALEFixSuggest| command can be used to suggest tools that be used to
-fix problems for the current buffer.
-
-The values for `g:ale_fixers` can be a list of |String|, |Funcref|, or
-|lambda| values. String values must either name a function, or a short name
-for a function set in the ALE fixer registry.
-
-Each function for fixing errors must accept either one argument `(buffer)` or
-two arguments `(buffer, lines)`, representing the buffer being fixed and the
-lines to fix. The functions must return either `0`, for changing nothing, a
-|List| for new lines to set, or a |Dictionary| for describing a command to be
-run in the background.
-
-Functions receiving a variable number of arguments will not receive the second
-argument `lines`. Functions should name two arguments if the `lines` argument
-is desired. This is required to avoid unnecessary copying of the lines of
-the buffers being checked.
-
-When a |Dictionary| is returned for an |ALEFix| callback, the following keys
-are supported for running the commands.
-
-  `command`             A |String| for the command to run. This key is required.
-
-                      When `%t` is included in a command string, a temporary
-                      file will be created, containing the lines from the file
-                      after previous adjustment have been done.
-
-  `read_temporary_file` When set to `1`, ALE will read the contents of the
-                      temporary file created for `%t`. This option can be used
-                      for commands which need to modify some file on disk in
-                      order to fix files.
-
-                                                        *ale-fix-configuration*
-
-Synchronous functions and asynchronous jobs will be run in a sequence for
-fixing files, and can be combined. For example:
->
-  let g:ale_fixers = {
-  \   'javascript': [
-  \       'DoSomething',
-  \       'eslint',
-  \       {buffer, lines -> filter(lines, 'v:val !=~ ''^\s*//''')},
-  \   ],
-  \}
-
-  ALEFix
-<
-The above example will call a function called `DoSomething` which could act
-upon some lines immediately, then run `eslint` from the ALE registry, and
-then call a lambda function which will remove every single line comment
-from the file.
-
-For convenience, a plug mapping is defined for |ALEFix|, so you can set up a
-keybind easily for fixing files. >
-
-  " Bind F8 to fixing problems with ALE
-  nmap <F8> <Plug>(ale_fix)
-<
-Files can be fixed automatically with the following options, which are all off
-by default.
-
-|g:ale_fix_on_save| - Fix files when they are saved.
-
-
-===============================================================================
-5. Completion                                                  *ale-completion*
-
-ALE offers some limited support for automatic completion of code while you
-type. Completion is only supported via Language Server Protocol servers which
-ALE can connect to for linting, which can offer good built-in support for
-suggesting completion information. ALE will only suggest symbols for
-completion for LSP linters that are enabled.
-
-NOTE: At the moment, only `tsserver` for TypeScript code is supported for
-completion.
-
-Suggestions will be made while you type after completion is enabled.
-Completion can be enabled by setting |g:ale_completion_enabled| to `1`. The
-delay for completion can be configured with |g:ale_completion_delay|. ALE will
-only suggest so many possible matches for completion. The maximum number of
-items can be controlled with |g:ale_completion_max_suggestions|.
-
-
-===============================================================================
-6. Integration Documentation                                 *ale-integrations*
+7. Integration Documentation                                 *ale-integrations*
 
 Linter and fixer options are documented in individual help files. See the
 table of contents at |ale-contents|.
@@ -1137,7 +1213,7 @@ ALE will use to search for Python executables.
 
 
 ===============================================================================
-7. Commands/Keybinds                                             *ale-commands*
+8. Commands/Keybinds                                             *ale-commands*
 
 ALEFix                                                                 *ALEFix*
 
@@ -1153,6 +1229,7 @@ ALEFixSuggest                                                   *ALEFixSuggest*
   See |ale-fix| for more information.
 
 
+                                                                     *:ALELint*
 ALELint                                                               *ALELint*
 
   Run ALE once for the current buffer. This command can be used to run ALE
@@ -1222,6 +1299,7 @@ ALEDetail                                                           *ALEDetail*
   A plug mapping `<Plug>(ale_detail)` is defined for this command.
 
 
+                                                                     *:ALEInfo*
 ALEInfo                                                               *ALEInfo*
 ALEInfoToClipboard                                         *ALEInfoToClipboard*
 
@@ -1240,7 +1318,7 @@ ALEInfoToClipboard                                         *ALEInfoToClipboard*
 
 
 ===============================================================================
-8. API                                                                *ale-api*
+9. API                                                                *ale-api*
 
 ale#Queue(delay, [linting_flag, buffer_number])                   *ale#Queue()*
 
@@ -1648,13 +1726,13 @@ ALELint                                                       *ALELint-autocmd*
   echoing messges.
 
 ===============================================================================
-9. Special Thanks                                          *ale-special-thanks*
+10. Special Thanks                                         *ale-special-thanks*
 
 Special thanks to Mark Grealish (https://www.bhalash.com/) for providing ALE's
 snazzy looking ale glass logo. Cheers, Mark!
 
 ===============================================================================
-10. Contact                                                       *ale-contact*
+11. Contact                                                       *ale-contact*
 
 If you like this plugin, and wish to get in touch, check out the GitHub
 page for issues and more at https://github.com/w0rp/ale
@@ -1662,10 +1740,8 @@ page for issues and more at https://github.com/w0rp/ale
 If you wish to contact the author of this plugin directly, please feel
 free to send an email to devw0rp@gmail.com.
 
-
 Please drink responsibly, or not at all, which is ironically the preference
 of w0rp, who is teetotal.
 
 
-
   vim:tw=78:ts=2:sts=2:sw=2:ft=help:norl: