man.vim: doc fixes #5171

- Weird tab+space combination used for alignment. All spaces now
- Added back <C-T> mapping (somehow we missed that completely)
- Fixed mistake that <Plug>(Man) opens in a new tab. Also added note at
  top on how the window is chosen/opened.
- Clarified q local mapping
- Removed section that shows an example autocmd to add desired folding
  style.
- Removed random line in `usr_12.txt` about `<Leader>` and backslash.
- :Man supports completion, not auto-completion.

Closes #5171

4 files changed, 26 insertions, 25 deletions

diff --git a/runtime/doc/filetype.txt b/runtime/doc/filetype.txt
index 92ed9de369..bbe2bbe50f 100644
--- a/runtime/doc/filetype.txt
+++ b/runtime/doc/filetype.txt
@@ -512,40 +512,41 @@ Local mappings:
 
 MAN					*ft-man-plugin* *:Man* *man.vim*
 
-View manpages in Nvim. Supports highlighting, autocompletion, locales, and
-navigation. See also |find-manpage|.
-
-To use Nvim as a manpager:
+View manpages in Nvim. Supports highlighting, completion, locales, and
+navigation. Also see |find-manpage|.
 
+To use Nvim as a manpager: >
      export MANPAGER="nvim -c 'set ft=man' -"
 
+man.vim will always attempt to reuse the closest man window (above/left) but
+otherwise create a split.
+
 Commands:
-Man {name}		  Display the manpage for {name} in a window.
-Man {sect} {name}	  Display the manpage for {name} and section {sect}.
-Man {name}({sect})	  Alternate syntax which auto-completes the section.
+Man {name}                Display the manpage for {name}.
+Man {sect} {name}         Display the manpage for {name} and section {sect}.
+Man {name}({sect})        Alternate syntax which completes the section.
 Man {sect} {name}({sect}) Used during completion to show the real section of
-			  when the provided section is a prefix, e.g. 1m vs 1.
-Man {path}		  Open the manpage specified by path. Use "./" if it
-                          is in the current directory.
+                          when the provided section is a prefix, e.g. 1m vs 1.
+Man {path}                Open the manpage specified by path. Prepend "./" if
+                          page is in the current directory.
+
+|:Man| accepts command modifiers. For example, to use a vertical split: >
+     :vertical Man printf
 
 Global Mappings:
 <Plug>(Man)               Jump to the manpage for the <cWORD> under the
-                          cursor in a new tab. Takes a count for the section.
+                          cursor. Takes a count for the section.
 
 Local mappings:
-K
-CTRL-]			  Jump to the manpage for the <cWORD> under the
+K or CTRL-]               Jump to the manpage for the <cWORD> under the
                           cursor. Takes a count for the section.
-CTRL-T			  Jump back to the previous manpage.
-q			  Close the window.
+CTRL-T                    Jump back to the location that the manpage was
+                          opened from.
+q                         :quit if invoked as $MANPAGER, otherwise :close.
 
 Variables:
-g:no_man_maps		  Do not create mappings in manpage buffers.
-g:ft_man_folding_enable   Fold manpages with foldmethod=indent foldnestmax=1.
-
-If you do not like the default folding, use an autocommand to add your desired
-folding style instead. For example: >
-          :autocmd FileType man setlocal foldmethod=indent foldenable
+*g:no_man_maps*             Do not create mappings in manpage buffers.
+*g:ft_man_folding_enable*   Fold manpages with foldmethod=indent foldnestmax=1.
 
 PDF							*ft-pdf-plugin*
 
diff --git a/runtime/doc/usr_12.txt b/runtime/doc/usr_12.txt
index 169d886e78..f64a230576 100644
--- a/runtime/doc/usr_12.txt
+++ b/runtime/doc/usr_12.txt
@@ -258,7 +258,6 @@ To display a man page for the word under the cursor, use this: >
 
 	K
 
-(If you redefined the <Leader>, use it instead of the backslash).
 For example, you want to know the return value of "strstr()" while editing
 this line:
 
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index 9bd129a7c2..2b1c66d0c1 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -96,7 +96,7 @@ Options:
 
 Commands:
   |:CheckHealth|
-  |:Man| has many improvements, including auto-completion
+  |:Man| is available by default, with many improvements such as completion
 
 Functions:
   |execute()| works with |:redir|
diff --git a/runtime/ftplugin/man.vim b/runtime/ftplugin/man.vim
index 614e1cb161..79aecb123d 100644
--- a/runtime/ftplugin/man.vim
+++ b/runtime/ftplugin/man.vim
@@ -41,8 +41,9 @@ setlocal nolist
 setlocal nofoldenable
 
 if !exists('g:no_plugin_maps') && !exists('g:no_man_maps')
-  nmap <silent> <buffer> <C-]>      <Plug>(Man)
-  nmap <silent> <buffer> K          <Plug>(Man)
+  nmap     <silent> <buffer> <C-]>      <Plug>(Man)
+  nmap     <silent> <buffer> K          <Plug>(Man)
+  nnoremap <silent> <buffer> <C-T>      :call man#pop_tag()<CR>
   if s:pager
     nnoremap <silent> <buffer> <nowait> q :q<CR>
   else