vim-patch:094494b: runtime(vim): improve &keywordprg in ftplugin

- let keywordprg in vim filetype handle context-sensitive help calls by
  detecting the syntax group of the word under the cursor
- reformat whitespace
- add modeline

related: vim/vim#16677
closes: vim/vim#16680

https://github.com/vim/vim/commit/094494bf2eef8d788944b2b00b3361feb545d3ae

Co-authored-by: Konfekt <Konfekt@users.noreply.github.com>
Co-authored-by: Andrew Radev <andrey.radev@gmail.com>
Co-authored-by: "D. Ben Knoble" <ben.knoble+github@gmail.com>
Co-authored-by: Gary Johnson <garyjohn@spocom.com>
Co-authored-by: Tim Pope <code@tpope.net>
Co-authored-by: Doug Kearns <dougkearns@gmail.com>
Co-authored-by: Christian Brabandt <cb@256bit.org>

1 files changed, 75 insertions, 28 deletions

diff --git a/runtime/ftplugin/vim.vim b/runtime/ftplugin/vim.vim
index 6ba057fc03..9fa415daa4 100644
--- a/runtime/ftplugin/vim.vim
+++ b/runtime/ftplugin/vim.vim
@@ -1,9 +1,11 @@
 " Vim filetype plugin
-" Language:		Vim
-" Maintainer:		Doug Kearns <dougkearns@gmail.com>
-" Last Change:		2025 Jan 06
-" Former Maintainer:	Bram Moolenaar <Bram@vim.org>
-" Contributors:		Riley Bruins <ribru17@gmail.com> ('commentstring')
+" Language:          Vim
+" Maintainer:        Doug Kearns <dougkearns@gmail.com>
+" Last Change:       2025 Feb 23
+" Former Maintainer: Bram Moolenaar <Bram@vim.org>
+" Contributors:      Riley Bruins <ribru17@gmail.com> ('commentstring'),
+"                    @Konfekt
+"                    @tpope (s:Help())
 
 " Only do this when not done yet for this buffer
 if exists("b:did_ftplugin")
@@ -19,19 +21,20 @@ set cpo&vim
 if !exists('*VimFtpluginUndo')
   func VimFtpluginUndo()
     setl fo< isk< com< tw< commentstring< keywordprg<
+    sil! delc -buffer VimKeywordPrg
     if exists('b:did_add_maps')
       silent! nunmap <buffer> [[
-      silent! vunmap <buffer> [[
+      silent! xunmap <buffer> [[
       silent! nunmap <buffer> ]]
-      silent! vunmap <buffer> ]]
+      silent! xunmap <buffer> ]]
       silent! nunmap <buffer> []
-      silent! vunmap <buffer> []
+      silent! xunmap <buffer> []
       silent! nunmap <buffer> ][
-      silent! vunmap <buffer> ][
+      silent! xunmap <buffer> ][
       silent! nunmap <buffer> ]"
-      silent! vunmap <buffer> ]"
+      silent! xunmap <buffer> ]"
       silent! nunmap <buffer> ["
-      silent! vunmap <buffer> ["
+      silent! xunmap <buffer> ["
      endif
     unlet! b:match_ignorecase b:match_words b:match_skip b:did_add_maps
   endfunc
@@ -48,7 +51,49 @@ setlocal fo-=t fo+=croql
 setlocal isk+=#
 
 " Use :help to lookup the keyword under the cursor with K.
-setlocal keywordprg=:help
+" Distinguish between commands, options and functions.
+if !exists("*" .. expand("<SID>") .. "Help")
+  function s:Help(topic) abort
+    let topic = a:topic
+
+    if get(g:, 'syntax_on', 0)
+      let syn = synIDattr(synID(line('.'), col('.'), 1), 'name')
+      if syn ==# 'vimFuncName'
+        return topic.'()'
+      elseif syn ==# 'vimOption'
+        return "'".topic."'"
+      elseif syn ==# 'vimUserAttrbKey'
+        return ':command-'.topic
+      elseif syn =~# 'vimCommand'
+        return ':'.topic
+      endif
+    endif
+
+    let col = col('.') - 1
+    while col && getline('.')[col] =~# '\k'
+      let col -= 1
+    endwhile
+    let pre = col == 0 ? '' : getline('.')[0 : col]
+
+    let col = col('.') - 1
+    while col && getline('.')[col] =~# '\k'
+      let col += 1
+    endwhile
+    let post = getline('.')[col : -1]
+
+    if pre =~# '^\s*:\=$'
+      return ':'.topic
+    elseif pre =~# '\<v:$'
+      return 'v:'.topic
+    elseif topic ==# 'v' && post =~# ':\w\+'
+      return 'v'.matchstr(post, ':\w\+')
+    else
+      return topic
+    endif
+  endfunction
+endif
+command! -buffer -nargs=1 VimKeywordPrg :exe 'help' s:Help(<q-args>)
+setlocal keywordprg=:VimKeywordPrg
 
 " Comments starts with # in Vim9 script.  We have to guess which one to use.
 if "\n" .. getline(1, 32)->join("\n") =~# '\n\s*vim9\%[script]\>'
@@ -72,19 +117,19 @@ if !exists("no_plugin_maps") && !exists("no_vim_maps")
 
   " Move around functions.
   nnoremap <silent><buffer> [[ m':call search('^\s*\(fu\%[nction]\\|def\)\>', "bW")<CR>
-  vnoremap <silent><buffer> [[ m':<C-U>exe "normal! gv"<Bar>call search('^\s*\(fu\%[nction]\\|def\)\>', "bW")<CR>
+  xnoremap <silent><buffer> [[ m':<C-U>exe "normal! gv"<Bar>call search('^\s*\(fu\%[nction]\\|def\)\>', "bW")<CR>
   nnoremap <silent><buffer> ]] m':call search('^\s*\(fu\%[nction]\\|def\)\>', "W")<CR>
-  vnoremap <silent><buffer> ]] m':<C-U>exe "normal! gv"<Bar>call search('^\s*\(fu\%[nction]\\|def\)\>', "W")<CR>
+  xnoremap <silent><buffer> ]] m':<C-U>exe "normal! gv"<Bar>call search('^\s*\(fu\%[nction]\\|def\)\>', "W")<CR>
   nnoremap <silent><buffer> [] m':call search('^\s*end\(f\%[unction]\\|def\)\>', "bW")<CR>
-  vnoremap <silent><buffer> [] m':<C-U>exe "normal! gv"<Bar>call search('^\s*end\(f\%[unction]\\|def\)\>', "bW")<CR>
+  xnoremap <silent><buffer> [] m':<C-U>exe "normal! gv"<Bar>call search('^\s*end\(f\%[unction]\\|def\)\>', "bW")<CR>
   nnoremap <silent><buffer> ][ m':call search('^\s*end\(f\%[unction]\\|def\)\>', "W")<CR>
-  vnoremap <silent><buffer> ][ m':<C-U>exe "normal! gv"<Bar>call search('^\s*end\(f\%[unction]\\|def\)\>', "W")<CR>
+  xnoremap <silent><buffer> ][ m':<C-U>exe "normal! gv"<Bar>call search('^\s*end\(f\%[unction]\\|def\)\>', "W")<CR>
 
   " Move around comments
   nnoremap <silent><buffer> ]" :call search('\%(^\s*".*\n\)\@<!\%(^\s*"\)', "W")<CR>
-  vnoremap <silent><buffer> ]" :<C-U>exe "normal! gv"<Bar>call search('\%(^\s*".*\n\)\@<!\%(^\s*"\)', "W")<CR>
+  xnoremap <silent><buffer> ]" :<C-U>exe "normal! gv"<Bar>call search('\%(^\s*".*\n\)\@<!\%(^\s*"\)', "W")<CR>
   nnoremap <silent><buffer> [" :call search('\%(^\s*".*\n\)\%(^\s*"\)\@!', "bW")<CR>
-  vnoremap <silent><buffer> [" :<C-U>exe "normal! gv"<Bar>call search('\%(^\s*".*\n\)\%(^\s*"\)\@!', "bW")<CR>
+  xnoremap <silent><buffer> [" :<C-U>exe "normal! gv"<Bar>call search('\%(^\s*".*\n\)\%(^\s*"\)\@!', "bW")<CR>
 endif
 
 " Let the matchit plugin know what items can be matched.
@@ -96,15 +141,15 @@ if exists("loaded_matchit")
   "   func name
   " require a parenthesis following, then there can be an "endfunc".
   let b:match_words =
-	\ '\<\%(fu\%[nction]\|def\)!\=\s\+\S\+\s*(:\%(\%(^\||\)\s*\)\@<=\<retu\%[rn]\>:\%(\%(^\||\)\s*\)\@<=\<\%(endf\%[unction]\|enddef\)\>,' ..
-	\ '\<\%(wh\%[ile]\|for\)\>:\%(\%(^\||\)\s*\)\@<=\<brea\%[k]\>:\%(\%(^\||\)\s*\)\@<=\<con\%[tinue]\>:\%(\%(^\||\)\s*\)\@<=\<end\%(w\%[hile]\|fo\%[r]\)\>,' ..
-	\ '\<if\>:\%(\%(^\||\)\s*\)\@<=\<el\%[seif]\>:\%(\%(^\||\)\s*\)\@<=\<en\%[dif]\>,' ..
-	\ '{:},' ..
-	\ '\<try\>:\%(\%(^\||\)\s*\)\@<=\<cat\%[ch]\>:\%(\%(^\||\)\s*\)\@<=\<fina\%[lly]\>:\%(\%(^\||\)\s*\)\@<=\<endt\%[ry]\>,' ..
-	\ '\<aug\%[roup]\s\+\%(END\>\)\@!\S:\<aug\%[roup]\s\+END\>,' ..
-	\ '\<class\>:\<endclass\>,' ..
-	\ '\<interface\>:\<endinterface\>,' ..
-	\ '\<enum\>:\<endenum\>'
+  \ '\<\%(fu\%[nction]\|def\)!\=\s\+\S\+\s*(:\%(\%(^\||\)\s*\)\@<=\<retu\%[rn]\>:\%(\%(^\||\)\s*\)\@<=\<\%(endf\%[unction]\|enddef\)\>,' ..
+  \ '\<\%(wh\%[ile]\|for\)\>:\%(\%(^\||\)\s*\)\@<=\<brea\%[k]\>:\%(\%(^\||\)\s*\)\@<=\<con\%[tinue]\>:\%(\%(^\||\)\s*\)\@<=\<end\%(w\%[hile]\|fo\%[r]\)\>,' ..
+  \ '\<if\>:\%(\%(^\||\)\s*\)\@<=\<el\%[seif]\>:\%(\%(^\||\)\s*\)\@<=\<en\%[dif]\>,' ..
+  \ '{:},' ..
+  \ '\<try\>:\%(\%(^\||\)\s*\)\@<=\<cat\%[ch]\>:\%(\%(^\||\)\s*\)\@<=\<fina\%[lly]\>:\%(\%(^\||\)\s*\)\@<=\<endt\%[ry]\>,' ..
+  \ '\<aug\%[roup]\s\+\%(END\>\)\@!\S:\<aug\%[roup]\s\+END\>,' ..
+  \ '\<class\>:\<endclass\>,' ..
+  \ '\<interface\>:\<endinterface\>,' ..
+  \ '\<enum\>:\<endenum\>'
 
   " Ignore syntax region commands and settings, any 'en*' would clobber
   " if-endif.
@@ -112,7 +157,7 @@ if exists("loaded_matchit")
   " - au! FileType javascript syntax region foldBraces start=/{/ end=/}/ …
   " Also ignore here-doc and dictionary keys (vimVar).
   let b:match_skip = 'synIDattr(synID(line("."), col("."), 1), "name")
-	\ =~? "comment\\|string\\|vimSynReg\\|vimSet\\|vimLetHereDoc\\|vimVar"'
+                    \ =~? "comment\\|string\\|vimSynReg\\|vimSet\\|vimLetHereDoc\\|vimVar"'
 endif
 
 let &cpo = s:cpo_save
@@ -120,3 +165,5 @@ unlet s:cpo_save
 
 " removed this, because 'cpoptions' is a global option.
 " setlocal cpo+=M		" makes \%( match \)
+"
+" vim: sw=2 et