man.vim #5249

- fix synopsis highlighting in other locales. Cannot always rely on the first
  line for the section in some locales; instead, use the file path and
  explicitly set b:man_sect to the actual section.
- eliminate separate s:man_args function
- simplify logic: do not reuse buffer content
- introduce b:man_default_sects Fixes #5233
- introduce <Plug>(man_vsplit), <Plug>(man_tab)
- simplify regexps

6 files changed, 80 insertions, 91 deletions

diff --git a/runtime/autoload/man.vim b/runtime/autoload/man.vim
index 7eb7ac1ab1..934a44e3e6 100644
--- a/runtime/autoload/man.vim
+++ b/runtime/autoload/man.vim
@@ -8,9 +8,9 @@ endif
 
 let s:man_find_arg = "-w"
 
-" TODO(nhooyr) I do not think completion will work on SunOS because I'm not sure if `man -l`
-" displays the list of directories that are searched by man for manpages.
-" I also do not think Solaris supports the '-P' flag used above and uses only $PAGER.
+" TODO(nhooyr) Completion may work on SunOS; I'm not sure if `man -l` displays
+" the list of searched directories. I also do not think Solaris supports the
+" '-P' flag used above and uses only $PAGER.
 try
   if !has('win32') && $OSTYPE !~? 'cygwin\|linux' && system('uname -s') =~? 'SunOS' && system('uname -r') =~# '^5'
     let s:man_find_arg = '-l'
@@ -19,10 +19,6 @@ catch /E145:/
   " Ignore the error in restricted mode
 endtry
 
-" We need count and count1 to ensure the section was explicitly set
-" by the user. count defaults to 0 which is a valid section and
-" count1 defaults to 1 which is also a valid section. Only when they
-" are equal was the count explicitly set.
 function! man#open_page(count, count1, mods, ...) abort
   if a:0 > 2
     call s:error('too many arguments')
@@ -34,16 +30,17 @@ function! man#open_page(count, count1, mods, ...) abort
     endif
     let ref = a:1
   else
-    " We combine the name and sect into a manpage reference so that all
+    " Combine the name and sect into a manpage reference so that all
     " verification/extraction can be kept in a single function.
     " If a:2 is a reference as well, that is fine because it is the only
     " reference that will match.
     let ref = a:2.'('.a:1.')'
   endif
   try
-    let [sect, name] = s:extract_sect_and_name_ref(ref)
+    let [sect, name] = man#extract_sect_and_name_ref(ref)
     if a:count ==# a:count1
-      " user explicitly set a count
+      " v:count defaults to 0 which is a valid section, and v:count1 defaults to
+      " 1, also a valid section. If they are equal, count explicitly set.
       let sect = string(a:count)
     endif
     let [sect, name, path] = s:verify_exists(sect, name)
@@ -54,44 +51,42 @@ function! man#open_page(count, count1, mods, ...) abort
   call s:push_tag()
   let bufname = 'man://'.name.(empty(sect)?'':'('.sect.')')
   if a:mods !~# 'tab' && s:find_man()
-    if s:manwidth() ==# getbufvar(bufname, 'manwidth')
-      silent execute 'buf' bufname
-      call man#set_window_local_options()
-      keepjumps 1
-      return
-    endif
     noautocmd execute 'edit' bufname
-  elseif s:manwidth() ==# getbufvar(bufname, 'manwidth')
-    execute a:mods 'split' bufname
-    call man#set_window_local_options()
-    keepjumps 1
-    return
   else
     noautocmd execute a:mods 'split' bufname
   endif
+  let b:man_sect = sect
   call s:read_page(path)
 endfunction
 
 function! man#read_page(ref) abort
   try
-    let [sect, name] = s:extract_sect_and_name_ref(a:ref)
-    " The third element is the path.
-    call s:read_page(s:verify_exists(sect, name)[2])
+    let [sect, name] = man#extract_sect_and_name_ref(a:ref)
+    let [b:man_sect, name, path] = s:verify_exists(sect, name)
   catch
-    call s:error(v:exception)
+    " call to s:error() is unnecessary
     return
   endtry
+  call s:read_page(path)
 endfunction
 
 function! s:read_page(path) abort
   setlocal modifiable
   setlocal noreadonly
   keepjumps %delete _
-  let b:manwidth = s:manwidth()
   " Ensure Vim is not recursively invoked (man-db does this)
   " by forcing man to use cat as the pager.
   " More info here http://comments.gmane.org/gmane.editors.vim.devel/29085
-  silent execute 'read !env MANPAGER=cat MANWIDTH='.b:manwidth s:man_cmd a:path
+  let cmd = 'read !env MANPAGER=cat'
+  if empty($MANWIDTH)
+    " Do not set $MANWIDTH globally.
+    silent execute cmd 'MANWIDTH='.winwidth(0) s:man_cmd shellescape(a:path)
+  else
+    " Respect $MANWIDTH even if it is wider/smaller than the current window,
+    " because the current window might only be temporarily wide/narrow. Since we
+    " don't reflow, we assume the user set $MANWIDTH intentionally.
+    silent execute cmd s:man_cmd shellescape(a:path)
+  endif
   " remove all the backspaced text
   silent execute 'keeppatterns keepjumps %substitute,.\b,,e'.(&gdefault?'':'g')
   while getline(1) =~# '^\s*$'
@@ -102,17 +97,17 @@ endfunction
 
 " attempt to extract the name and sect out of 'name(sect)'
 " otherwise just return the largest string of valid characters in ref
-function! s:extract_sect_and_name_ref(ref) abort
+function! man#extract_sect_and_name_ref(ref) abort
   if a:ref[0] ==# '-' " try ':Man -pandoc' with this disabled.
-    throw 'manpage name starts with ''-'''
+    throw 'manpage name cannot start with ''-'''
   endif
   let ref = matchstr(a:ref, '[^()]\+([^()]\+)')
   if empty(ref)
     let name = matchstr(a:ref, '[^()]\+')
     if empty(name)
-      throw 'manpage reference contains only parantheses'
+      throw 'manpage reference cannot contain only parentheses'
     endif
-    return ['', name]
+    return [get(b:, 'man_default_sects', ''), name]
   endif
   let left = split(ref, '(')
   " see ':Man 3X curses' on why tolower.
@@ -121,21 +116,29 @@ function! s:extract_sect_and_name_ref(ref) abort
   return [tolower(split(left[1], ')')[0]), left[0]]
 endfunction
 
-function! s:verify_exists(sect, name) abort
-  let path = system(s:man_cmd.' '.s:man_find_arg.' '.s:man_args(a:sect, a:name))
-  if path !~# '^\/'
-    if empty(a:sect)
-      throw 'no manual entry for '.a:name
-    endif
+function! s:get_path(sect, name) abort
+  if empty(a:sect)
     let path = system(s:man_cmd.' '.s:man_find_arg.' '.shellescape(a:name))
     if path !~# '^\/'
-      throw 'no manual entry for '.a:name.'('.a:sect.') or '.a:name
+      throw 'no manual entry for '.a:name
     endif
+    return path
   endif
-  if a:name =~# '\/'
-    " We do not need to extract the section/name from the path if the name is
-    " just a path.
-    return ['', a:name, path]
+  " '-s' flag handles:
+  "   - tokens like 'printf(echo)'
+  "   - sections starting with '-'
+  "   - 3pcap section (found on macOS)
+  "   - commas between sections (for section priority)
+  return system(s:man_cmd.' '.s:man_find_arg.' -s '.shellescape(a:sect).' '.shellescape(a:name))
+endfunction
+
+function! s:verify_exists(sect, name) abort
+  let path = s:get_path(a:sect, a:name)
+  if path !~# '^\/'
+    let path = s:get_path(get(b:, 'man_default_sects', ''), a:name)
+    if path !~# '^\/'
+      let path = s:get_path('', a:name)
+    endif
   endif
   " We need to extract the section from the path because sometimes
   " the actual section of the manpage is more specific than the section
@@ -160,7 +163,7 @@ endfunction
 function! man#pop_tag() abort
   if !empty(s:tag_stack)
     let tag = remove(s:tag_stack, -1)
-    execute tag['buf'].'b'
+    silent execute tag['buf'].'buffer'
     call cursor(tag['lnum'], tag['col'])
   endif
 endfunction
@@ -172,7 +175,7 @@ function! s:extract_sect_and_name_path(path) abort
     let tail = fnamemodify(tail, ':r')
   endif
   let sect = matchstr(tail, '\.\zs[^.]\+$')
-  let name = matchstr(tail, '^.\+\ze\.[^.]\+$')
+  let name = matchstr(tail, '^.\+\ze\.')
   return [sect, name]
 endfunction
 
@@ -191,41 +194,6 @@ function! s:find_man() abort
   endwhile
 endfunction
 
-function! s:manwidth() abort
-  " The reason for respecting $MANWIDTH even if it is wider/smaller than the
-  " current window is that the current window might only be temporarily
-  " narrow/wide. Since we don't reflow, we should just assume the
-  " user knows what they're doing and respect $MANWIDTH.
-  if empty($MANWIDTH)
-    " If $MANWIDTH is not set, we do not assign directly to $MANWIDTH because
-    " then $MANWIDTH will always stay the same value as we only use
-    " winwidth(0) when $MANWIDTH is empty. Instead we set it locally for the command.
-    return winwidth(0)
-  endif
-  return $MANWIDTH
-endfunction
-
-function! man#set_window_local_options() abort
-  setlocal nonumber
-  setlocal norelativenumber
-  setlocal foldcolumn=0
-  setlocal colorcolumn=0
-  setlocal nolist
-  setlocal nofoldenable
-endfunction
-
-function! s:man_args(sect, name) abort
-  if empty(a:sect)
-    return shellescape(a:name)
-  endif
-  " The '-s' flag is very useful.
-  " We do not need to worry about stuff like 'printf(echo)'
-  " (two manpages would be interpreted by man without -s)
-  " We do not need to check if the sect starts with '-'
-  " Lastly, the 3pcap section on macOS doesn't work without -s
-  return '-s '.shellescape(a:sect).' '.shellescape(a:name)
-endfunction
-
 function! s:error(msg) abort
   redraw
   echohl ErrorMsg
@@ -235,7 +203,7 @@ endfunction
 
 let s:mandirs = join(split(system(s:man_cmd.' '.s:man_find_arg), ':\|\n'), ',')
 
-" see s:extract_sect_and_name_ref on why tolower(sect)
+" see man#extract_sect_and_name_ref on why tolower(sect)
 function! man#complete(arg_lead, cmd_line, cursor_pos) abort
   let args = split(a:cmd_line)
   let l = len(args)
@@ -289,7 +257,7 @@ function! s:format_candidate(path, sect) abort
   let [sect, name] = s:extract_sect_and_name_path(a:path)
   if sect ==# a:sect
     return name
-  elseif sect =~# a:sect.'[^.]\+$'
+  elseif sect =~# a:sect.'.\+$'
     " We include the section if the user provided section is a prefix
     " of the actual section.
     return name.'('.sect.')'
diff --git a/runtime/doc/filetype.txt b/runtime/doc/filetype.txt
index bbe2bbe50f..21092b7081 100644
--- a/runtime/doc/filetype.txt
+++ b/runtime/doc/filetype.txt
@@ -534,8 +534,11 @@ Man {path}                Open the manpage specified by path. Prepend "./" if
      :vertical Man printf
 
 Global Mappings:
-<Plug>(Man)               Jump to the manpage for the <cWORD> under the
-                          cursor. Takes a count for the section.
+<Plug>(man)               Jump to the manpage for the <cWORD> (man buffers)
+                          or <cword> (non-man buffers) under the cursor.
+                          Takes a count for the section.
+<Plug>(man_vsplit)        Same as <Plug>(man) but open in a vertical split.
+<Plug>(man_tab)           Same as <Plug>(man) but open in a new tab.
 
 Local mappings:
 K or CTRL-]               Jump to the manpage for the <cWORD> under the
@@ -547,6 +550,9 @@ 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.
+*b:man_default_sects*       Comma-separated, ordered list of preferred sections.
+                          For example in C one usually wants section 3 or 2: >
+                               :let b:man_default_sections = '3,2'
 
 PDF							*ft-pdf-plugin*
 
diff --git a/runtime/ftplugin/c.vim b/runtime/ftplugin/c.vim
index 487ce7a165..d1b2a4941e 100644
--- a/runtime/ftplugin/c.vim
+++ b/runtime/ftplugin/c.vim
@@ -55,5 +55,7 @@ if (has("gui_win32") || has("gui_gtk")) && !exists("b:browsefilter")
   endif
 endif
 
+let b:man_default_sects = '3,2'
+
 let &cpo = s:cpo_save
 unlet s:cpo_save
diff --git a/runtime/ftplugin/man.vim b/runtime/ftplugin/man.vim
index fddfee3c31..08a88e6b90 100644
--- a/runtime/ftplugin/man.vim
+++ b/runtime/ftplugin/man.vim
@@ -19,7 +19,9 @@ if has('vim_starting')
   endif
   " This is not perfect. See `man glDrawArraysInstanced`. Since the title is
   " all caps it is impossible to tell what the original capitilization was.
-  execute 'file man://'.tolower(matchstr(getline(1), '^\S\+'))
+  let ref = tolower(matchstr(getline(1), '^\S\+'))
+  let b:man_sect = man#extract_sect_and_name_ref(ref)[0]
+  execute 'file man://'.ref
 endif
 
 setlocal buftype=nofile
@@ -33,11 +35,16 @@ setlocal tabstop=8
 setlocal softtabstop=8
 setlocal shiftwidth=8
 
-call man#set_window_local_options()
+setlocal nonumber
+setlocal norelativenumber
+setlocal foldcolumn=0
+setlocal colorcolumn=0
+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>
diff --git a/runtime/plugin/man.vim b/runtime/plugin/man.vim
index f3fe7151ca..df457c2243 100644
--- a/runtime/plugin/man.vim
+++ b/runtime/plugin/man.vim
@@ -7,7 +7,13 @@ let g:loaded_man = 1
 
 command! -range=0 -complete=customlist,man#complete -nargs=+ Man call man#open_page(v:count, v:count1, <q-mods>, <f-args>)
 
-nnoremap <silent> <Plug>(Man) :<C-U>call man#open_page(v:count, v:count1, '', &filetype ==# 'man' ? expand('<cWORD>') : expand('<cword>'))<CR>
+function! s:cword() abort
+  return &filetype ==# 'man' ? expand('<cWORD>') : expand('<cword>')
+endfunction
+
+nnoremap <silent> <Plug>(man)        :<C-U>execute 'Man '         .<SID>cword()<CR>
+nnoremap <silent> <Plug>(man_vsplit) :<C-U>execute 'vertical Man '.<SID>cword()<CR>
+nnoremap <silent> <Plug>(man_tab)    :<C-U>execute 'tab Man '     .<SID>cword()<CR>
 
 augroup man
   autocmd!
diff --git a/runtime/syntax/man.vim b/runtime/syntax/man.vim
index 5dd41b3af5..4a527dd350 100644
--- a/runtime/syntax/man.vim
+++ b/runtime/syntax/man.vim
@@ -7,10 +7,10 @@ endif
 
 syntax case  ignore
 syntax match manReference      display '[^()[:space:]]\+([0-9nx][a-z]*)'
-syntax match manSectionHeading display '^\%(\S.*\)\=\S$'
+syntax match manSectionHeading display '^\S.*$'
 syntax match manTitle          display '^\%1l.*$'
 syntax match manSubHeading     display '^ \{3\}\S.*$'
-syntax match manOptionDesc     display '^\s\+\%(+\|--\=\)\S\+'
+syntax match manOptionDesc     display '^\s\+\%(+\|-\)\S\+'
 
 highlight default link manTitle          Title
 highlight default link manSectionHeading Statement
@@ -18,7 +18,7 @@ highlight default link manOptionDesc     Constant
 highlight default link manReference      PreProc
 highlight default link manSubHeading     Function
 
-if getline(1) =~# '^[^()[:space:]]\+([23].*'
+if b:man_sect =~# '^[23]'
   syntax include @c $VIMRUNTIME/syntax/c.vim
   syntax match manCFuncDefinition display '\<\h\w*\>\ze\(\s\|\n\)*(' contained
   syntax region manSynopsis start='^\%(