Automatically check for invalid help tag references, and fix some existing documentation issues

doc/ale-java.txt

@@ -3,10 +3,10 @@ ALE Java Integration                                         *ale-java-options*
 
 
 ===============================================================================
-checkstyle                                                ale-java-checkstyle
+checkstyle                                                *ale-java-checkstyle*
 
-g:ale_java_checkstyle_options                   g:ale_java_checkstyle_options
-                                                b:ale_java_checkstyle_options
+g:ale_java_checkstyle_options                   *g:ale_java_checkstyle_options*
+                                                *b:ale_java_checkstyle_options*
 
   Type: String
   Default: '-c /google_checks.xml'

doc/ale-php.txt

@@ -63,7 +63,7 @@ g:ale_php_phpcs_use_global                         *g:ale_php_phpcs_use_global*
   See |ale-integrations-local-executables|
 
 
-------------------------------------------------------------------------------
+-------------------------------------------------------------------------------
 phpmd                                                           *ale-php-phpmd*
 
 g:ale_php_phpmd_ruleset                               *g:ale_php_phpmd_ruleset*
@@ -75,8 +75,8 @@ g:ale_php_phpmd_ruleset                               *g:ale_php_phpmd_ruleset*
   the available phpmd rulesets
 
 
-------------------------------------------------------------------------------
-phpstan                                                          *ale-php-stan*
+-------------------------------------------------------------------------------
+phpstan                                                       *ale-php-phpstan*
 
 g:ale_php_phpstan_executable                     *g:ale_php_phpstan_executable*
                                                  *b:ale_php_phpstan_executable*

doc/ale.txt

@@ -204,7 +204,7 @@ The following languages and tools are supported.
 * nroff: 'proselint'
 * Objective-C: 'clang'
 * Objective-C++: 'clang'
-* OCaml: 'merlin' (see |ale-linter-integration-ocaml-merlin|)
+* OCaml: 'merlin' (see |ale-ocaml-merlin|)
 * Perl: 'perl' (-c flag), 'perlcritic'
 * PHP: 'hack', 'langserver', 'php' (-l flag), 'phpcs', 'phpmd', 'phpstan'
 * Pod: 'proselint'

run-tests

@@ -55,6 +55,12 @@ while [ $# -ne 0 ]; do
         run_custom_checks=0
         shift
     ;;
+    --custom-checks-only)
+        run_vim_tests=0
+        run_neovim_tests=0
+        run_vint=0
+        shift
+    ;;
     --)
         shift
         break
@@ -211,6 +217,21 @@ if ((run_custom_checks)); then
     echo
 
     grep --exclude=tags -roh '\*.*\*$' doc | sort | uniq -d || EXIT=$?
+
+    echo '========================================'
+    echo 'Checking for invalid tag references'
+    echo '========================================'
+    echo 'Invalid tag references tags follow:'
+    echo
+
+    tag_regex='[gb]\?:\?\(ale\|ALE\)[a-zA-Z_\-]\+'
+
+    # Grep for tags and references, and complain if we find a reference without
+    # a tag for the reference. Only our tags will be included.
+    diff -u \
+        <(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
 fi
 
 exit $EXIT