Closes #3019 - Implement default navigation

Default navigation for commands that jump to new locations has been
implemented with the `ale_default_navigation` variable, and all commands
that jump to locations now support `-tab`, `-split`, or `-vsplit`
arguments for overriding the default navigation behavior.

1 files changed, 65 insertions, 77 deletions

diff --git a/doc/ale.txt b/doc/ale.txt
index da4328d9..469fa106 100644
--- a/doc/ale.txt
+++ b/doc/ale.txt
@@ -478,12 +478,9 @@ would like to use. An example here shows the available options for symbols  >
 
 ALE supports jumping to the files and locations where symbols are defined
 through any enabled LSP linters. The locations ALE will jump to depend on the
-information returned by LSP servers. The following commands are supported:
-
-|ALEGoToDefinition|      - Open the definition of the symbol under the cursor.
-|ALEGoToDefinitionInTab| - The same, but for opening the file in a new tab.
-|ALEGoToDefinitionInSplit| - The same, but in a new split.
-|ALEGoToDefinitionInVSplit| - The same, but in a new vertical split.
+information returned by LSP servers. The |ALEGoToDefinition| command will jump
+to the definition of symbols under the cursor. See the documentation for the
+command for configuring how the location will be displayed.
 
 ALE will update Vim's |tagstack| automatically unless |g:ale_update_tagstack| is
 set to `0`.
@@ -493,15 +490,10 @@ set to `0`.
 
 ALE supports jumping to the files and locations where symbols' types are
 defined through any enabled LSP linters. The locations ALE will jump to depend
-on the information returned by LSP servers. The following commands are
-supported:
-
-|ALEGoToTypeDefinition|      - Open the definition of the symbol's type under
-                             the cursor.
-|ALEGoToTypeDefinitionInTab| - The same, but for opening the file in a new tab.
-|ALEGoToTypeDefinitionInSplit| - The same, but in a new split.
-|ALEGoToTypeDefinitionInVSplit| - The same, but in a new vertical split.
-
+on the information returned by LSP servers. The |ALEGoToTypeDefinition|
+command will jump to the definition of symbols under the cursor. See the
+documentation for the command for configuring how the location will be
+displayed.
 
 -------------------------------------------------------------------------------
 5.4 Find References                                       *ale-find-references*
@@ -666,7 +658,7 @@ g:ale_completion_delay                                 *g:ale_completion_delay*
 
 
 g:ale_completion_enabled                             *g:ale_completion_enabled*
-b:ale_completion_enabled                             *b:ale_completion_enabled*
+                                                     *b:ale_completion_enabled*
 
   Type: |Number|
   Default: `0`
@@ -793,6 +785,16 @@ g:ale_cursor_detail                                       *g:ale_cursor_detail*
   loaded for messages to be displayed. See |ale-lint-settings-on-startup|.
 
 
+g:ale_default_navigation                             *g:ale_default_navigation*
+                                                     *b:ale_default_navigation*
+
+  Type: |String|
+  Default: `'buffer'`
+
+  The default method for navigating away from the current buffer to another
+  buffer, such as for |ALEFindReferences:|, or |ALEGoToDefinition|.
+
+
 g:ale_disable_lsp                                           *g:ale_disable_lsp*
                                                             *b:ale_disable_lsp*
 
@@ -845,7 +847,7 @@ g:ale_echo_msg_error_str                             *g:ale_echo_msg_error_str*
 
 
 g:ale_echo_msg_format                                   *g:ale_echo_msg_format*
-b:ale_echo_msg_format                                   *b:ale_echo_msg_format*
+                                                        *b:ale_echo_msg_format*
 
   Type: |String|
   Default: `'%code: %%s'`
@@ -924,7 +926,7 @@ g:ale_enabled                                                   *g:ale_enabled*
 
 
 g:ale_exclude_highlights                             *g:ale_exclude_highlights*
-b:ale_exclude_highlights                             *b:ale_exclude_highlights*
+                                                     *b:ale_exclude_highlights*
 
   Type: |List|
   Default: `[]`
@@ -961,7 +963,7 @@ g:ale_fixers                                                     *g:ale_fixers*
 <
 
 g:ale_fix_on_save                                           *g:ale_fix_on_save*
-b:ale_fix_on_save                                           *b:ale_fix_on_save*
+                                                            *b:ale_fix_on_save*
 
   Type: |Number|
   Default: `0`
@@ -983,7 +985,7 @@ b:ale_fix_on_save                                           *b:ale_fix_on_save*
 
 
 g:ale_fix_on_save_ignore                             *g:ale_fix_on_save_ignore*
-b:ale_fix_on_save_ignore                             *b:ale_fix_on_save_ignore*
+                                                     *b:ale_fix_on_save_ignore*
 
   Type: |Dictionary| or |List|
   Default: `{}`
@@ -1359,7 +1361,7 @@ g:ale_list_vertical                                       *g:ale_list_vertical*
 
 
 g:ale_loclist_msg_format                             *g:ale_loclist_msg_format*
-b:ale_loclist_msg_format                             *b:ale_loclist_msg_format*
+                                                     *b:ale_loclist_msg_format*
 
   Type: |String|
   Default: `g:ale_echo_msg_format`
@@ -1411,7 +1413,7 @@ g:ale_lsp_show_message_severity               *g:ale_lsp_show_message_severity*
 
 
 g:ale_lsp_root                                                 *g:ale_lsp_root*
-b:ale_lsp_root                                                 *b:ale_lsp_root*
+                                                               *b:ale_lsp_root*
 
   Type: |Dictionary| or |String|
   Default: {}
@@ -1892,7 +1894,8 @@ g:ale_virtualtext_cursor                             *g:ale_virtualtext_cursor*
 
 
 g:ale_virtualtext_delay                               *g:ale_virtualtext_delay*
-b:ale_virtualtext_delay                               *b:ale_virtualtext_delay*
+                                                      *b:ale_virtualtext_delay*
+
   Type: |Number|
   Default: `10`
 
@@ -1911,7 +1914,7 @@ g:ale_virtualtext_prefix                             *g:ale_virtualtext_prefix*
   Prefix to be used with |g:ale_virtualtext_cursor|.
 
 g:ale_virtualenv_dir_names                         *g:ale_virtualenv_dir_names*
-b:ale_virtualenv_dir_names                         *b:ale_virtualenv_dir_names*
+                                                   *b:ale_virtualenv_dir_names*
 
   Type: |List|
   Default: `['.env', '.venv', 'env', 've-py3', 've', 'virtualenv', 'venv']`
@@ -1925,7 +1928,7 @@ b:ale_virtualenv_dir_names                         *b:ale_virtualenv_dir_names*
 
 
 g:ale_warn_about_trailing_blank_lines   *g:ale_warn_about_trailing_blank_lines*
-b:ale_warn_about_trailing_blank_lines   *b:ale_warn_about_trailing_blank_lines*
+                                        *b:ale_warn_about_trailing_blank_lines*
 
   Type: |Number|
   Default: `1`
@@ -1937,7 +1940,7 @@ b:ale_warn_about_trailing_blank_lines   *b:ale_warn_about_trailing_blank_lines*
 
 
 g:ale_warn_about_trailing_whitespace     *g:ale_warn_about_trailing_whitespace*
-b:ale_warn_about_trailing_whitespace     *b:ale_warn_about_trailing_whitespace*
+                                         *b:ale_warn_about_trailing_whitespace*
 
   Type: |Number|
   Default: `1`
@@ -2704,11 +2707,23 @@ ALEFindReferences                                           *ALEFindReferences*
   Enter key (`<CR>`) can be used to jump to a referencing location, or the `t`
   key can be used to jump to the location in a new tab.
 
+  The locations opened in different ways using the following variations.
+
+  `:ALEFindReferences -tab`    - Open the location in a new tab.
+  `:ALEFindReferences -split`  - Open the location in a horizontal split.
+  `:ALEFindReferences -vsplit` - Open the location in a vertical split.
+
+  The default method used for navigating to a new location can be changed
+  by modifying |g:ale_default_navigation|.
+
+  The selection can be opened again with the |ALERepeatSelection| command.
+
   You can jump back to the position you were at before going to a reference of
   something with jump motions like CTRL-O. See |jump-motions|.
 
   A plug mapping `<Plug>(ale_find_references)` is defined for this command.
 
+
 ALEFix                                                                 *ALEFix*
 
   Fix problems with the current buffer. See |ale-fix| for more information.
@@ -2723,12 +2738,21 @@ ALEFixSuggest                                                   *ALEFixSuggest*
   See |ale-fix| for more information.
 
 
-ALEGoToDefinition                                           *ALEGoToDefinition*
+ALEGoToDefinition `<options>`                               *ALEGoToDefinition*
 
   Jump to the definition of a symbol under the cursor using the enabled LSP
   linters for the buffer. ALE will jump to a definition if an LSP server
   provides a location to jump to. Otherwise, ALE will do nothing.
 
+  The locations opened in different ways using the following variations.
+
+  `:ALEGoToDefinition -tab`    - Open the location in a new tab.
+  `:ALEGoToDefinition -split`  - Open the location in a horizontal split.
+  `:ALEGoToDefinition -vsplit` - Open the location in a vertical split.
+
+  The default method used for navigating to a new location can be changed
+  by modifying |g:ale_default_navigation|.
+
   You can jump back to the position you were at before going to the definition
   of something with jump motions like CTRL-O. See |jump-motions|.
 
@@ -2739,30 +2763,6 @@ ALEGoToDefinition                                           *ALEGoToDefinition*
   A plug mapping `<Plug>(ale_go_to_definition)` is defined for this command.
 
 
-ALEGoToDefinitionInTab                                 *ALEGoToDefinitionInTab*
-
-  The same as |ALEGoToDefinition|, but opens results in a new tab.
-
-  A plug mapping `<Plug>(ale_go_to_definition_in_tab)` is defined for this
-  command.
-
-
-ALEGoToDefinitionInSplit                             *ALEGoToDefinitionInSplit*
-
-  The same as |ALEGoToDefinition|, but opens results in a new split.
-
-  A plug mapping `<Plug>(ale_go_to_definition_in_split)` is defined for this
-  command.
-
-
-ALEGoToDefinitionInVSplit                           *ALEGoToDefinitionInVSplit*
-
-  The same as |ALEGoToDefinition|, but opens results in a new vertical split.
-
-  A plug mapping `<Plug>(ale_go_to_definition_in_vsplit)` is defined for this
-  command.
-
-
 ALEGoToTypeDefinition                                   *ALEGoToTypeDefinition*
 
   This works similar to |ALEGoToDefinition| but instead jumps to the
@@ -2770,6 +2770,15 @@ ALEGoToTypeDefinition                                   *ALEGoToTypeDefinition*
   definition if an LSP server provides a location to jump to. Otherwise, ALE
   will do nothing.
 
+  The locations opened in different ways using the following variations.
+
+  `:ALEGoToTypeDefinition -tab`    - Open the location in a new tab.
+  `:ALEGoToTypeDefinition -split`  - Open the location in a horizontal split.
+  `:ALEGoToTypeDefinition -vsplit` - Open the location in a vertical split.
+
+  The default method used for navigating to a new location can be changed
+  by modifying |g:ale_default_navigation|.
+
   You can jump back to the position you were at before going to the definition
   of something with jump motions like CTRL-O. See |jump-motions|.
 
@@ -2777,31 +2786,6 @@ ALEGoToTypeDefinition                                   *ALEGoToTypeDefinition*
   command.
 
 
-ALEGoToTypeDefinitionInTab                         *ALEGoToTypeDefinitionInTab*
-
-  The same as |ALEGoToTypeDefinition|, but opens results in a new tab.
-
-  A plug mapping `<Plug>(ale_go_to_type_definition_in_tab)` is defined for
-  this command.
-
-
-ALEGoToTypeDefinitionInSplit                     *ALEGoToTypeDefinitionInSplit*
-
-  The same as |ALEGoToTypeDefinition|, but opens results in a new split.
-
-  A plug mapping `<Plug>(ale_go_to_type_definition_in_split)` is defined for
-  this command.
-
-
-ALEGoToTypeDefinitionInVSplit                   *ALEGoToTypeDefinitionInVSplit*
-
-  The same as |ALEGoToTypeDefinition|, but opens results in a new vertical
-  split.
-
-  A plug mapping `<Plug>(ale_go_to_type_definition_in_vsplit)` is defined for
-  this command.
-
-
 ALEHover                                                             *ALEHover*
 
   Print brief information about the symbol under the cursor, taken from any
@@ -2827,6 +2811,11 @@ ALERename                                                           *ALERename*
   The user will be prompted for a new name.
 
 
+ALERepeatSelection                                         *ALERepeatSelection*
+
+  Repeat the last selection displayed in the preview window.
+
+
 ALESymbolSearch `<query>`                                     *ALESymbolSearch*
 
   Search for symbols in the workspace, taken from any available LSP linters.
@@ -3135,7 +3124,6 @@ ale#command#Run(buffer, command, callback, [options])       *ale#command#Run()*
 
     'command': {b -> ale#command#Run(b, 'foo', function('s:GetCommand'))}
 <
-
   The following `options` can be provided.
 
     `output_stream` - Either `'stdout'`, `'stderr'`, `'both'`, or `'none`' for