From 6592873f773b4c358ea950bfcfa8cbc3fc3bc8cc Mon Sep 17 00:00:00 2001 From: Christian Clason Date: Sat, 8 Jun 2024 10:49:15 +0200 Subject: [PATCH] feat(help): use treesitter for table of contents Problem: Creating the table of contents for `gO` is complicated. Solution: Use treesitter instead. --- runtime/doc/help.txt | 4 +-- runtime/ftplugin/help.lua | 4 +++ runtime/ftplugin/help.vim | 72 ------------------------------------- runtime/lua/vim/vimhelp.lua | 38 ++++++++++++++++++++ 4 files changed, 44 insertions(+), 74 deletions(-) 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, or 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/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 gO :call show_toc() -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