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

4 files changed, 353 insertions, 197 deletions

diff --git a/README.md b/README.md
index cbfef300..1ecec1c3 100644
--- a/README.md
+++ b/README.md
@@ -55,50 +55,59 @@ tools will be run in combination, so they can be complementary.
 Keep the table rows sorted alphabetically by the language name,
 and the tools in the tools column sorted alphabetically by the tool
 name. That seems to be the fairest way to arrange this table.
+
+Remember to also update doc/ale.txt, which has a similar list with different
+formatting.
 -->
 
+<a name="table-notes"></a>
+**Notes:**
+
+* *^ No linters for text or Vim help filetypes are enabled by default.*
+* *! These linters check only files on disk. See `:help ale-lint-file-linters`*
+
 | Language | Tools |
 | -------- | ----- |
 | ASM | [gcc](https://gcc.gnu.org) |
 | Ansible | [ansible-lint](https://github.com/willthames/ansible-lint) |
-| AsciiDoc | [proselint](http://proselint.com/)|
+| AsciiDoc | [proselint](http://proselint.com/) |
 | Awk | [gawk](https://www.gnu.org/software/gawk/)|
-| Bash | [-n flag](https://www.gnu.org/software/bash/manual/bash.html#index-set), [shellcheck](https://www.shellcheck.net/) |
-| Bourne Shell | [-n flag](http://linux.die.net/man/1/sh), [shellcheck](https://www.shellcheck.net/) |
-| C | [cppcheck](http://cppcheck.sourceforge.net), [gcc](https://gcc.gnu.org/), [clang](http://clang.llvm.org/), [clang-format](https://clang.llvm.org/docs/ClangFormat.html)|
-| C++ (filetype cpp) | [clang](http://clang.llvm.org/), [clangcheck](http://clang.llvm.org/docs/ClangCheck.html), [clangtidy](http://clang.llvm.org/extra/clang-tidy/), [cppcheck](http://cppcheck.sourceforge.net), [cpplint](https://github.com/google/styleguide/tree/gh-pages/cpplint), [gcc](https://gcc.gnu.org/), [clang-format](https://clang.llvm.org/docs/ClangFormat.html)|
+| Bash | shell [-n flag](https://www.gnu.org/software/bash/manual/bash.html#index-set), [shellcheck](https://www.shellcheck.net/) |
+| Bourne Shell | shell [-n flag](http://linux.die.net/man/1/sh), [shellcheck](https://www.shellcheck.net/) |
+| C | [cppcheck](http://cppcheck.sourceforge.net), [cpplint](https://github.com/google/styleguide/tree/gh-pages/cpplint), [gcc](https://gcc.gnu.org/), [clang](http://clang.llvm.org/), [clang-format](https://clang.llvm.org/docs/ClangFormat.html)|
+| C++ (filetype cpp) | [clang](http://clang.llvm.org/), [clangcheck](http://clang.llvm.org/docs/ClangCheck.html)[!](#table-notes), [clangtidy](http://clang.llvm.org/extra/clang-tidy/)[!](#table-notes), [cppcheck](http://cppcheck.sourceforge.net), [cpplint](https://github.com/google/styleguide/tree/gh-pages/cpplint)[!](#table-notes), [gcc](https://gcc.gnu.org/), [clang-format](https://clang.llvm.org/docs/ClangFormat.html)|
 | C# | [mcs](http://www.mono-project.com/docs/about-mono/languages/csharp/) |
 | Chef | [foodcritic](http://www.foodcritic.io/) |
 | CMake | [cmakelint](https://github.com/richq/cmake-lint) |
 | CoffeeScript | [coffee](http://coffeescript.org/), [coffeelint](https://www.npmjs.com/package/coffeelint) |
-| Crystal | [crystal](https://crystal-lang.org/) |
+| Crystal | [crystal](https://crystal-lang.org/)[!](#table-notes) |
 | CSS | [csslint](http://csslint.net/), [stylelint](https://github.com/stylelint/stylelint) |
 | Cython (pyrex filetype) | [cython](http://cython.org/) |
 | D | [dmd](https://dlang.org/dmd-linux.html) |
 | Dart | [dartanalyzer](https://github.com/dart-lang/sdk/tree/master/pkg/analyzer_cli) |
 | Dockerfile | [hadolint](https://github.com/lukasmartinelli/hadolint) |
-| Elixir | [credo](https://github.com/rrrene/credo), [dogma](https://github.com/lpil/dogma) |
+| Elixir | [credo](https://github.com/rrrene/credo), [dogma](https://github.com/lpil/dogma)[!](#table-notes) |
 | Elm | [elm-make](https://github.com/elm-lang/elm-make) |
 | Erb | [erb](https://github.com/jeremyevans/erubi), [erubis](https://github.com/kwatch/erubis) |
 | Erlang | [erlc](http://erlang.org/doc/man/erlc.html), [SyntaxErl](https://github.com/ten0s/syntaxerl) |
 | Fortran | [gcc](https://gcc.gnu.org/) |
 | FusionScript | [fusion-lint](https://github.com/RyanSquared/fusionscript) |
-| Go | [gofmt -e](https://golang.org/cmd/gofmt/), [go vet](https://golang.org/cmd/vet/), [golint](https://godoc.org/github.com/golang/lint), [gometalinter](https://github.com/alecthomas/gometalinter), [go build](https://golang.org/cmd/go/), [gosimple](https://github.com/dominikh/go-tools/tree/master/cmd/gosimple), [staticcheck](https://github.com/dominikh/go-tools/tree/master/cmd/staticcheck) |
+| Go | [gofmt](https://golang.org/cmd/gofmt/), [go vet](https://golang.org/cmd/vet/), [golint](https://godoc.org/github.com/golang/lint), [gometalinter](https://github.com/alecthomas/gometalinter)[!](#table-notes), [go build](https://golang.org/cmd/go/)[!](#table-notes), [gosimple](https://github.com/dominikh/go-tools/tree/master/cmd/gosimple), [staticcheck](https://github.com/dominikh/go-tools/tree/master/cmd/staticcheck) |
 | GraphQL | [gqlint](https://github.com/happylinks/gqlint) |
 | Haml | [haml-lint](https://github.com/brigade/haml-lint)
 | Handlebars | [ember-template-lint](https://github.com/rwjblue/ember-template-lint) |
-| Haskell | [ghc](https://www.haskell.org/ghc/), [stack-ghc](https://haskellstack.org/), [stack-build](https://haskellstack.org/), [ghc-mod](https://github.com/DanielG/ghc-mod), [stack-ghc-mod](https://github.com/DanielG/ghc-mod), [hlint](https://hackage.haskell.org/package/hlint), [hdevtools](https://hackage.haskell.org/package/hdevtools) |
+| Haskell | [ghc](https://www.haskell.org/ghc/), [stack-ghc](https://haskellstack.org/), [stack-build](https://haskellstack.org/)[!](#table-notes), [ghc-mod](https://github.com/DanielG/ghc-mod), [stack-ghc-mod](https://github.com/DanielG/ghc-mod), [hlint](https://hackage.haskell.org/package/hlint), [hdevtools](https://hackage.haskell.org/package/hdevtools) |
 | HTML | [HTMLHint](http://htmlhint.com/), [proselint](http://proselint.com/), [tidy](http://www.html-tidy.org/) |
 | Idris | [idris](http://www.idris-lang.org/) |
 | Java | [checkstyle](http://checkstyle.sourceforge.net), [javac](http://www.oracle.com/technetwork/java/javase/downloads/index.html) |
-| JavaScript | [eslint](http://eslint.org/), [jscs](http://jscs.info/), [jshint](http://jshint.com/), [flow](https://flowtype.org/), [standard](http://standardjs.com/), [prettier](https://github.com/prettier/prettier) (and `prettier-eslint`, `prettier-standard`), [xo](https://github.com/sindresorhus/xo)
+| JavaScript | [eslint](http://eslint.org/), [jscs](http://jscs.info/), [jshint](http://jshint.com/), [flow](https://flowtype.org/), [prettier](https://github.com/prettier/prettier), prettier-eslint, prettier-standard, [standard](http://standardjs.com/), [xo](https://github.com/sindresorhus/xo)
 | JSON | [jsonlint](http://zaa.ch/jsonlint/) |
-| Kotlin | [kotlinc](https://kotlinlang.org), [ktlint](https://ktlint.github.io) see `:help ale-integration-kotlin` for configuration instructions
+| Kotlin | [kotlinc](https://kotlinlang.org)[!](#table-notes), [ktlint](https://ktlint.github.io)[!](#table-notes) see `:help ale-integration-kotlin` for configuration instructions
 | LaTeX | [chktex](http://www.nongnu.org/chktex/), [lacheck](https://www.ctan.org/pkg/lacheck), [proselint](http://proselint.com/) |
 | Lua | [luacheck](https://github.com/mpeterv/luacheck) |
 | Markdown | [mdl](https://github.com/mivok/markdownlint), [proselint](http://proselint.com/), [vale](https://github.com/ValeLint/vale) |
 | MATLAB | [mlint](https://www.mathworks.com/help/matlab/ref/mlint.html) |
-| Nim | [nim](https://nim-lang.org/docs/nimc.html) |
+| Nim | [nim check](https://nim-lang.org/docs/nimc.html)[!](#table-notes) |
 | nix | [nix-instantiate](http://nixos.org/nix/manual/#sec-nix-instantiate) |
 | nroff | [proselint](http://proselint.com/)|
 | Objective-C | [clang](http://clang.llvm.org/) |
@@ -109,13 +118,13 @@ name. That seems to be the fairest way to arrange this table.
 | Pod | [proselint](http://proselint.com/)|
 | Pug | [pug-lint](https://github.com/pugjs/pug-lint) |
 | Puppet | [puppet](https://puppet.com), [puppet-lint](https://puppet-lint.com) |
-| Python | [autopep8](https://github.com/hhatto/autopep8), [flake8](http://flake8.pycqa.org/en/latest/), [isort](https://github.com/timothycrosley/isort), [mypy](http://mypy-lang.org/), [pycodestyle](https://github.com/PyCQA/pycodestyle), [pylint](https://www.pylint.org/), [yapf](https://github.com/google/yapf) |
+| Python | [autopep8](https://github.com/hhatto/autopep8), [flake8](http://flake8.pycqa.org/en/latest/), [isort](https://github.com/timothycrosley/isort), [mypy](http://mypy-lang.org/), [pycodestyle](https://github.com/PyCQA/pycodestyle), [pylint](https://www.pylint.org/)[!](#table-notes), [yapf](https://github.com/google/yapf) |
 | R | [lintr](https://github.com/jimhester/lintr) |
 | ReasonML | [merlin](https://github.com/the-lambda-church/merlin) see `:help ale-integration-reason-merlin` for configuration instructions
-| reStructuredText | [proselint](http://proselint.com/)|
+| reStructuredText | [proselint](http://proselint.com/) |
 | RPM spec | [rpmlint](https://github.com/rpm-software-management/rpmlint) (disabled by default; see `:help ale-integration-spec`) |
-| Ruby | [brakeman](http://brakemanscanner.org/), [rails_best_practices](https://github.com/flyerhzm/rails_best_practices), [reek](https://github.com/troessner/reek), [rubocop](https://github.com/bbatsov/rubocop), [ruby](https://www.ruby-lang.org) |
-| Rust |  cargo (see `:help ale-integration-rust` for configuration instructions), [rls](https://github.com/rust-lang-nursery/rls), [rustc](https://www.rust-lang.org/) |
+| Ruby | [brakeman](http://brakemanscanner.org/)[!](#table-notes), [rails_best_practices](https://github.com/flyerhzm/rails_best_practices)[!](#table-notes), [reek](https://github.com/troessner/reek), [rubocop](https://github.com/bbatsov/rubocop), [ruby](https://www.ruby-lang.org) |
+| Rust |  cargo[!](#table-notes) (see `:help ale-integration-rust` for configuration instructions), [rls](https://github.com/rust-lang-nursery/rls), [rustc](https://www.rust-lang.org/) |
 | SASS | [sass-lint](https://www.npmjs.com/package/sass-lint), [stylelint](https://github.com/stylelint/stylelint) |
 | SCSS | [sass-lint](https://www.npmjs.com/package/sass-lint), [scss-lint](https://github.com/brigade/scss-lint), [stylelint](https://github.com/stylelint/stylelint) |
 | Scala | [scalac](http://scala-lang.org), [scalastyle](http://www.scalastyle.org) |
@@ -124,7 +133,7 @@ name. That seems to be the fairest way to arrange this table.
 | Stylus | [stylelint](https://github.com/stylelint/stylelint) |
 | SQL | [sqlint](https://github.com/purcell/sqlint) |
 | Swift | [swiftlint](https://github.com/realm/SwiftLint), [swiftformat](https://github.com/nicklockwood/SwiftFormat) |
-| Tcl | [nagelfar](http://nagelfar.sourceforge.net)|
+| Tcl | [nagelfar](http://nagelfar.sourceforge.net)[!](#table-notes) |
 | Texinfo | [proselint](http://proselint.com/)|
 | Text^ | [proselint](http://proselint.com/), [vale](https://github.com/ValeLint/vale) |
 | TypeScript | [eslint](http://eslint.org/), [tslint](https://github.com/palantir/tslint), tsserver, typecheck |
@@ -135,8 +144,6 @@ name. That seems to be the fairest way to arrange this table.
 | XML | [xmllint](http://xmlsoft.org/xmllint.html/)|
 | YAML | [swaglint](https://github.com/byCedric/swaglint), [yamllint](https://yamllint.readthedocs.io/) |
 
-* *^ No linters for text or Vim help filetypes are enabled by default.*
-
 <a name="usage"></a>
 
 ## 2. Usage
diff --git a/check-supported-tools-tables b/check-supported-tools-tables
new file mode 100755
index 00000000..9cae8d08
--- /dev/null
+++ b/check-supported-tools-tables
@@ -0,0 +1,65 @@
+#!/bin/bash -eu
+
+# This script compares the table of supported tools in both the README file
+# and the doc/ale.txt file, so we can complain if they don't match up.
+
+# Find the start and end lines for the help section.
+ale_help_start_line="$( \
+    grep -m1 -n '^[0-9][0-9]*\. *Supported Languages' doc/ale.txt \
+    | sed 's/\([0-9]*\).*/\1/' \
+)"
+ale_help_section_size="$( \
+    tail -n +"$ale_help_start_line" doc/ale.txt \
+    | grep -m1 -n '================' \
+    | sed 's/\([0-9]*\).*/\1/' \
+)"
+ale_help_end_line="$(("$ale_help_start_line" + "$ale_help_section_size"))"
+
+# Find the start and end lines for the same section in the README.
+readme_start_line="$( \
+    grep -m1 -n '^.*[0-9][0-9]*\. *Supported Languages' README.md \
+    | sed 's/\([0-9]*\).*/\1/' \
+)"
+readme_section_size="$( \
+    tail -n +"$readme_start_line" README.md \
+    | grep -m1 -n '^##.*Usage' \
+    | sed 's/\([0-9]*\).*/\1/' \
+)"
+readme_end_line="$(("$readme_start_line" + "$readme_section_size"))"
+
+doc_file="$(mktemp)"
+readme_file="$(mktemp)"
+
+sed -n "$ale_help_start_line,$ale_help_end_line"p doc/ale.txt \
+    | grep '\* .*: ' \
+    | sed 's/^*//' \
+    | sed 's/[`!^]\|([^)]*)//g' \
+    | sed 's/ *\([,:]\)/\1/g' \
+    | sed 's/  */ /g' \
+    | sed 's/^ *\| *$//g' \
+    | sed 's/^/ /' \
+    > "$doc_file"
+
+sed -n "$readme_start_line,$readme_end_line"p README.md \
+    | grep '| .* |' \
+    | sed '/^| Language\|^| ---/d' \
+    | sed 's/^|//' \
+    | sed 's/ \?|/:/' \
+    | sed 's/[`!^|]\|([^)]*)//g' \
+    | sed 's/\[\|\]//g' \
+    | sed 's/see.*\(,\|$\)/\1/g' \
+    | sed 's/ *\([,:]\)/\1/g' \
+    | sed 's/  */ /g' \
+    | sed 's/^ *\| *$//g' \
+    | sed 's/^/ /' \
+    | sed 's/ *-n flag//g' \
+    > "$readme_file"
+
+exit_code=0
+
+diff -U0 "$readme_file" "$doc_file" || exit_code=$?
+
+rm "$doc_file"
+rm "$readme_file"
+
+exit "$exit_code"
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:
diff --git a/run-tests b/run-tests
index 316eb6c9..a2843580 100755
--- a/run-tests
+++ b/run-tests
@@ -235,6 +235,14 @@ if ((run_custom_checks)); then
         <(grep --exclude=tags -roh "\*$tag_regex\*" doc | sort -u | sed 's/*//g') \
         <(grep --exclude=tags -roh "|$tag_regex|" doc | sort -u | sed 's/|//g') \
         | grep '^+[^+]' && EXIT=1
+
+    echo '========================================'
+    echo 'diff README.md and doc/ale.txt tables'
+    echo '========================================'
+    echo 'Differences follow:'
+    echo
+
+    ./check-supported-tools-tables || EXIT=$?
 fi
 
 exit $EXIT