Merge #29238 from clason/feat/help-toc

9 files changed, 63 insertions, 87 deletions

diff --git a/cmake.deps/deps.txt b/cmake.deps/deps.txt
index f2b152640e..356bfd92d4 100644
--- a/cmake.deps/deps.txt
+++ b/cmake.deps/deps.txt
@@ -47,8 +47,8 @@ TREESITTER_LUA_URL https://github.com/tree-sitter-grammars/tree-sitter-lua/archi
 TREESITTER_LUA_SHA256 230cfcbfa74ed1f7b8149e9a1f34c2efc4c589a71fe0f5dc8560622f8020d722
 TREESITTER_VIM_URL https://github.com/neovim/tree-sitter-vim/archive/v0.4.0.tar.gz
 TREESITTER_VIM_SHA256 9f856f8b4a10ab43348550fa2d3cb2846ae3d8e60f45887200549c051c66f9d5
-TREESITTER_VIMDOC_URL https://github.com/neovim/tree-sitter-vimdoc/archive/v2.5.1.tar.gz
-TREESITTER_VIMDOC_SHA256 063645096504b21603585507c41c6d8718ff3c11b2150c5bfc31e8f3ee9afea3
+TREESITTER_VIMDOC_URL https://github.com/neovim/tree-sitter-vimdoc/archive/v3.0.0.tar.gz
+TREESITTER_VIMDOC_SHA256 a639bf92bf57bfa1cdc90ca16af27bfaf26a9779064776dd4be34c1ef1453f6c
 TREESITTER_QUERY_URL https://github.com/tree-sitter-grammars/tree-sitter-query/archive/v0.4.0.tar.gz
 TREESITTER_QUERY_SHA256 d3a423ab66dc62b2969625e280116678a8a22582b5ff087795222108db2f6a6e
 TREESITTER_PYTHON_URL https://github.com/tree-sitter/tree-sitter-python/archive/v0.21.0.tar.gz
diff --git a/runtime/doc/ft_sql.txt b/runtime/doc/ft_sql.txt
index 241fa4bd74..1dbac66db0 100644
--- a/runtime/doc/ft_sql.txt
+++ b/runtime/doc/ft_sql.txt
@@ -293,7 +293,7 @@ loaded by Vim: >
     ftplugin/sql.vim
     syntax/sqlinformix.vim
     indent/sql.vim
->
+<
 Notice indent/sqlinformix.sql was not loaded.  There is no indent file
 for Informix, Vim loads the default files if the specified files does not
 exist.
@@ -349,7 +349,7 @@ The defaults static maps are: >
 The use of "<C-C>" can be user chosen by using the following in your |init.vim|
 as it may not work properly on all platforms: >
     let g:ftplugin_sql_omni_key = '<C-C>'
->
+<
 The static maps (which are based on the syntax highlight groups) follow this
 format: >
     imap <buffer> <C-C>k <C-\><C-O>:call sqlcomplete#Map('sqlKeyword')<CR><C-X><C-O>
@@ -664,7 +664,7 @@ your |init.vim|: >
 	  filetype is changed temporarily to SQL, the sqlcompletion plugin
 	  will cache the syntax groups listed in the List specified in this
 	  option.
->
+
 
 ------------------------------------------------------------------------------
 4.5 SQL Maps					*sql-completion-maps*
diff --git a/runtime/doc/help.txt b/runtime/doc/help.txt
index 685bce2553..fefead7fc9 100644
--- a/runtime/doc/help.txt
+++ b/runtime/doc/help.txt
@@ -188,7 +188,7 @@ Local additions ~
 							*local-additions*
 
 ------------------------------------------------------------------------------
-*bars*		Bars example
+Bars example								*bars*
 
 Now that you've jumped here with CTRL-] or a double mouse click, you can use
 CTRL-T, CTRL-O, g<RightMouse>, or <C-RightMouse> to go back to where you were.
@@ -200,5 +200,5 @@ You can use CTRL-] on any word (even if it is not within "|") and Nvim will
 try to find help for it.  Especially for options in single quotes, e.g.
 'hlsearch'.
 
-------------------------------------------------------------------------------
+
  vim:tw=78:isk=!-~,^*,^\|,^\":ts=8:noet:ft=help:norl:
diff --git a/runtime/doc/index.txt b/runtime/doc/index.txt
index 79f10b33f1..05c8b94d94 100644
--- a/runtime/doc/index.txt
+++ b/runtime/doc/index.txt
@@ -366,7 +366,7 @@ tag		char	      note action in Normal mode	~
 				   or start of putted text
 |`]|		`]		1  cursor to the end of last operated text or
 				   end of putted text
-|``|		``		1  cursor to the position before latest jump
+|``|		"``"		1  cursor to the position before latest jump
 |`{|		`{		1  cursor to the start of the current paragraph
 |`}|		`}		1  cursor to the end of the current paragraph
 |a|		a		2  append text after the cursor N times
@@ -1136,7 +1136,7 @@ tag		command		action ~
 |:!!|		:!!		repeat last ":!" command
 |:#|		:#		same as ":number"
 |:&|		:&		repeat last ":substitute"
-|:star|		:*		use the last Visual area, like :'<,'>
+|:star|		:*		use the last Visual area, like ":'<,'>"
 |:<|		:<		shift lines one 'shiftwidth' left
 |:=|		:=		print the last line number
 |:>|		:>		shift lines one 'shiftwidth' right
diff --git a/runtime/doc/usr_29.txt b/runtime/doc/usr_29.txt
index dd8598a3a0..9929be5079 100644
--- a/runtime/doc/usr_29.txt
+++ b/runtime/doc/usr_29.txt
@@ -87,7 +87,7 @@ The ":tags" command shows the list of tags that you traversed through:
 	  1  1 write_line	   8  write_block.c ~
 	  2  1 write_char	   7  write_line.c ~
 	> ~
->
+<
 Now to go back.  The CTRL-T command goes to the preceding tag.  In the example
 above you get back to the "write_line" function, in the call to "write_char".
    This command takes a count argument that indicates how many tags to jump
diff --git a/runtime/ftplugin/help.lua b/runtime/ftplugin/help.lua
index 67c417b1be..86e181504f 100644
--- a/runtime/ftplugin/help.lua
+++ b/runtime/ftplugin/help.lua
@@ -26,3 +26,7 @@ elseif vim.endswith(bufname, '/doc/lsp.txt') then
     { start = [[\*lsp-semantic-highlight\*]], stop = '^======', match = '^@[%w%p]+' },
   })
 end
+
+vim.keymap.set('n', 'gO', function()
+  require('vim.vimhelp').show_toc()
+end, { buffer = 0, silent = true })
diff --git a/runtime/ftplugin/help.vim b/runtime/ftplugin/help.vim
index a188e45cb4..833baf5d8f 100644
--- a/runtime/ftplugin/help.vim
+++ b/runtime/ftplugin/help.vim
@@ -21,77 +21,5 @@ endif
 " Prefer Vim help instead of manpages.
 setlocal keywordprg=:help
 
-if !exists('g:no_plugin_maps')
-  function! s:show_toc() abort
-    let bufname = bufname('%')
-    let info = getloclist(0, {'winid': 1})
-    if !empty(info) && getwinvar(info.winid, 'qf_toc') ==# bufname
-      lopen
-      return
-    endif
-
-    let toc = []
-    let lnum = 2
-    let last_line = line('$') - 1
-    let last_added = 0
-    let has_section = 0
-    let has_sub_section = 0
-
-    while lnum && lnum <= last_line
-      let level = 0
-      let add_text = ''
-      let text = getline(lnum)
-
-      if text =~# '^=\+$' && lnum + 1 < last_line
-        " A de-facto section heading.  Other headings are inferred.
-        let has_section = 1
-        let has_sub_section = 0
-        let lnum = nextnonblank(lnum + 1)
-        let text = getline(lnum)
-        let add_text = text
-        while add_text =~# '\*[^*]\+\*\s*$'
-          let add_text = matchstr(add_text, '.*\ze\*[^*]\+\*\s*$')
-        endwhile
-      elseif text =~# '^[A-Z0-9][-A-ZA-Z0-9 .][-A-Z0-9 .():]*\%([ \t]\+\*.\+\*\)\?$'
-        " Any line that's yelling is important.
-        let has_sub_section = 1
-        let level = has_section
-        let add_text = matchstr(text, '.\{-}\ze\s*\%([ \t]\+\*.\+\*\)\?$')
-      elseif text =~# '\~$'
-            \ && matchstr(text, '^\s*\zs.\{-}\ze\s*\~$') !~# '\t\|\s\{2,}'
-            \ && getline(lnum - 1) =~# '^\s*<\?$\|^\s*\*.*\*$'
-            \ && getline(lnum + 1) =~# '^\s*>\?$\|^\s*\*.*\*$'
-        " These lines could be headers or code examples.  We only want the
-        " ones that have subsequent lines at the same indent or more.
-        let l = nextnonblank(lnum + 1)
-        if getline(l) =~# '\*[^*]\+\*$'
-          " Ignore tag lines
-          let l = nextnonblank(l + 1)
-        endif
-
-        if indent(lnum) <= indent(l)
-          let level = has_section + has_sub_section
-          let add_text = matchstr(text, '\S.\{-}\ze\s\=\~$')
-        endif
-      endif
-
-      let add_text = substitute(add_text, '\s\+$', '', 'g')
-      if !empty(add_text) && last_added != lnum
-        let last_added = lnum
-        call add(toc, {'bufnr': bufnr('%'), 'lnum': lnum,
-              \ 'text': repeat("\u00a0\u00a0", level) . add_text})
-      endif
-      let lnum = nextnonblank(lnum + 1)
-    endwhile
-
-    call setloclist(0, toc, ' ')
-    call setloclist(0, [], 'a', {'title': 'Help TOC'})
-    lopen
-    let w:qf_toc = bufname
-  endfunction
-
-  nnoremap <silent><buffer> gO :call <sid>show_toc()<cr>
-endif
-
 let &cpo = s:cpo_save
 unlet s:cpo_save
diff --git a/runtime/lua/vim/vimhelp.lua b/runtime/lua/vim/vimhelp.lua
index 4af6866d48..33324602c9 100644
--- a/runtime/lua/vim/vimhelp.lua
+++ b/runtime/lua/vim/vimhelp.lua
@@ -30,4 +30,42 @@ function M.highlight_groups(patterns)
   vim.fn.setpos('.', save_cursor)
 end
 
+--- Show a table of contents for the help buffer in a loclist
+function M.show_toc()
+  local bufnr = vim.api.nvim_get_current_buf()
+  local parser = vim.treesitter.get_parser(bufnr, 'vimdoc')
+  local query = vim.treesitter.query.parse(
+    parser:lang(),
+    [[
+    (h1 (heading) @h1)
+    (h2 (heading) @h2)
+    (h3 (heading) @h3)
+    (column_heading (heading) @h4)
+  ]]
+  )
+  local root = parser:parse()[1]:root()
+  local headings = {}
+  for id, node, _, _ in query:iter_captures(root, bufnr) do
+    local text = vim.treesitter.get_node_text(node, bufnr)
+    local capture = query.captures[id]
+    local row, col = node:start()
+    -- only column_headings at col 1 are headings, otherwise it's code examples
+    local is_code = (capture == 'h4' and col > 0)
+    -- ignore tabular material
+    local is_table = (capture == 'h4' and (text:find('\t') or text:find('  ')))
+    -- ignore tag-only headings
+    local is_tag = node:child_count() == 1 and node:child(0):type() == 'tag'
+    if not (is_code or is_table or is_tag) then
+      table.insert(headings, {
+        bufnr = bufnr,
+        lnum = row + 1,
+        text = (capture == 'h3' or capture == 'h4') and '  ' .. text or text,
+      })
+    end
+  end
+  vim.fn.setloclist(0, headings, ' ')
+  vim.fn.setloclist(0, {}, 'a', { title = 'Help TOC' })
+  vim.cmd.lopen()
+end
+
 return M
diff --git a/runtime/queries/vimdoc/highlights.scm b/runtime/queries/vimdoc/highlights.scm
index 70a3a2f206..194c80362c 100644
--- a/runtime/queries/vimdoc/highlights.scm
+++ b/runtime/queries/vimdoc/highlights.scm
@@ -1,13 +1,19 @@
-(h1) @markup.heading.1
+(h1
+  (delimiter) @markup.heading.1
+  (heading) @markup.heading.1)
 
-(h2) @markup.heading.2
+(h2
+  (delimiter) @markup.heading.2
+  (heading) @markup.heading.2)
 
-(h3) @markup.heading.3
+(h3
+  (heading) @markup.heading.3)
 
-(column_heading) @markup.heading.4
+(column_heading
+  (heading) @markup.heading.4)
 
 (column_heading
-  "~" @markup.heading.4
+  (delimiter) @markup.heading.4
   (#set! conceal ""))
 
 (tag