fix(man.vim): filetype=man is too eager #15489

Problem:
"set filetype=man" assumes the user wants :Man features, this does extra
stuff like renaming the buffer as "man://".

Solution:
- old entrypoint was ":set filetype=man", but this is too presumptuous #15487
- make the entrypoints more explicit:
  1. when the ":Man" command is run
  2. when a "man://" buffer is opened
- remove the tricky b:man_sect checks in ftplugin/man.vim and syntax/man.vim
- MANPAGER is supported via ":Man!", as documented.

fixes #15487

4 files changed, 17 insertions, 23 deletions

diff --git a/runtime/autoload/man.vim b/runtime/autoload/man.vim
index 4f556e6e87..8bf95651b7 100644
--- a/runtime/autoload/man.vim
+++ b/runtime/autoload/man.vim
@@ -65,6 +65,7 @@ function! man#open_page(count, mods, ...) abort
   let b:man_sect = sect
 endfunction
 
+" Called when a man:// buffer is opened.
 function! man#read_page(ref) abort
   try
     let [sect, name] = s:extract_sect_and_name_ref(a:ref)
@@ -121,6 +122,15 @@ function! s:system(cmd, ...) abort
   return opts.stdout
 endfunction
 
+function! s:set_options(pager) abort
+  setlocal filetype=man
+  setlocal noswapfile buftype=nofile bufhidden=hide
+  setlocal nomodified readonly nomodifiable
+  if a:pager
+    nnoremap <silent> <buffer> <nowait> q :lclose<CR>:q<CR>
+  endif
+endfunction
+
 function! s:get_page(path) abort
   " Disable hard-wrap by using a big $MANWIDTH (max 1000 on some systems #9065).
   " Soft-wrap: ftplugin/man.vim sets wrap/breakindent/….
@@ -134,9 +144,7 @@ function! s:get_page(path) abort
 endfunction
 
 function! s:put_page(page) abort
-  setlocal modifiable
-  setlocal noreadonly
-  setlocal noswapfile
+  setlocal modifiable noreadonly noswapfile
   silent keepjumps %delete _
   silent put =a:page
   while getline(1) =~# '^\s*$'
@@ -148,7 +156,7 @@ function! s:put_page(page) abort
   silent! keeppatterns keepjumps %s/\s\{199,}/\=repeat(' ', 10)/g
   1
   lua require("man").highlight_man_page()
-  setlocal filetype=man
+  call s:set_options(v:false)
 endfunction
 
 function! man#show_toc() abort
@@ -397,6 +405,7 @@ function! s:format_candidate(path, psect) abort
   endif
 endfunction
 
+" Called when Nvim is invoked as $MANPAGER.
 function! man#init_pager() abort
   " https://github.com/neovim/neovim/issues/6828
   let og_modifiable = &modifiable
@@ -420,6 +429,7 @@ function! man#init_pager() abort
     execute 'silent file man://'.tolower(fnameescape(ref))
   endif
 
+  call s:set_options(v:true)
   let &l:modifiable = og_modifiable
 endfunction
 
diff --git a/runtime/ftplugin/man.vim b/runtime/ftplugin/man.vim
index 5d3e00d033..fce12012b5 100644
--- a/runtime/ftplugin/man.vim
+++ b/runtime/ftplugin/man.vim
@@ -6,14 +6,6 @@ if exists('b:did_ftplugin') || &filetype !=# 'man'
 endif
 let b:did_ftplugin = 1
 
-let s:pager = !exists('b:man_sect')
-
-if s:pager
-  call man#init_pager()
-endif
-
-setlocal noswapfile buftype=nofile bufhidden=hide
-setlocal nomodified readonly nomodifiable
 setlocal noexpandtab tabstop=8 softtabstop=8 shiftwidth=8
 setlocal wrap breakindent linebreak
 
@@ -32,11 +24,7 @@ if !exists('g:no_plugin_maps') && !exists('g:no_man_maps')
   nnoremap <silent> <buffer> k             gk
   nnoremap <silent> <buffer> gO            :call man#show_toc()<CR>
   nnoremap <silent> <buffer> <2-LeftMouse> :Man<CR>
-  if s:pager
-    nnoremap <silent> <buffer> <nowait> q :lclose<CR>:q<CR>
-  else
-    nnoremap <silent> <buffer> <nowait> q :lclose<CR><C-W>c
-  endif
+  nnoremap <silent> <buffer> <nowait> q :lclose<CR><C-W>c
 endif
 
 if get(g:, 'ft_man_folding_enable', 0)
diff --git a/runtime/plugin/man.vim b/runtime/plugin/man.vim
index 689aa32ef3..f814fbad3b 100644
--- a/runtime/plugin/man.vim
+++ b/runtime/plugin/man.vim
@@ -6,7 +6,7 @@ endif
 let g:loaded_man = 1
 
 command! -bang -bar -range=-1 -complete=customlist,man#complete -nargs=* Man
-      \ if <bang>0 | set ft=man |
+      \ if <bang>0 | call man#init_pager() |
       \ else | call man#open_page(<count>, <q-mods>, <f-args>) | endif
 
 augroup man
diff --git a/runtime/syntax/man.vim b/runtime/syntax/man.vim
index a01bd1c0e7..7772d2d6aa 100644
--- a/runtime/syntax/man.vim
+++ b/runtime/syntax/man.vim
@@ -27,11 +27,7 @@ if &filetype != 'man'
   finish
 endif
 
-if !exists('b:man_sect')
-  call man#init_pager()
-endif
-
-if b:man_sect =~# '^[023]'
+if get(b:, 'man_sect', '') =~# '^[023]'
   syntax case match
   syntax include @c $VIMRUNTIME/syntax/c.vim
   syntax match manCFuncDefinition display '\<\h\w*\>\ze\(\s\|\n\)*(' contained