help, man.vim: "outline" (TOC) feature #5169

runtime/autoload/man.vim

@@ -151,6 +151,31 @@ function! s:put_page(page) abort
   setlocal filetype=man
 endfunction
 
+function! man#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
+  while lnum && lnum < last_line
+    let text = getline(lnum)
+    if text =~# '^\%( \{3\}\)\=\S.*$'
+      call add(toc, {'bufnr': bufnr('%'), 'lnum': lnum, 'text': text})
+    endif
+    let lnum = nextnonblank(lnum + 1)
+  endwhile
+
+  call setloclist(0, toc, ' ')
+  call setloclist(0, [], 'a', {'title': 'Man TOC'})
+  lopen
+  let w:qf_toc = bufname
+endfunction
+
 " attempt to extract the name and sect out of 'name(sect)'
 " otherwise just return the largest string of valid characters in ref
 function! man#extract_sect_and_name_ref(ref) abort

runtime/doc/filetype.txt

@@ -542,6 +542,7 @@ K or CTRL-]               Jump to the manpage for the <cWORD> under the
                           cursor. Takes a count for the section.
 CTRL-T                    Jump back to the location that the manpage was
                           opened from.
+META-]                    Show the manpage outline in the |location-list|.
 q                         :quit if invoked as $MANPAGER, otherwise :close.
 
 Variables:

runtime/doc/helphelp.txt

@@ -25,6 +25,8 @@ Help on help files					*helphelp*
 			The 'helplang' option is used to select a language, if
 			the main help file is available in several languages.
 
+			Type <M-]> to see the table of contents.
+
 						*{subject}* *E149* *E661*
 :h[elp] {subject}	Like ":help", additionally jump to the tag {subject}.
 			For example:  >

runtime/ftplugin/help.vim

@@ -18,5 +18,77 @@ if has("conceal")
   setlocal cole=2 cocu=nc
 endif
 
+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.*')
+        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('  ', 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> <M-]> :call <sid>show_toc()<cr>
+endif
+
 let &cpo = s:cpo_save
 unlet s:cpo_save

runtime/ftplugin/man.vim

@@ -31,13 +31,14 @@ setlocal nolist
 setlocal nofoldenable
 
 if !exists('g:no_plugin_maps') && !exists('g:no_man_maps')
+  nnoremap <silent> <buffer> <M-]>      :call man#show_toc()<CR>
   nnoremap <silent> <buffer> <C-]>      :Man<CR>
   nnoremap <silent> <buffer> K          :Man<CR>
   nnoremap <silent> <buffer> <C-T>      :call man#pop_tag()<CR>
   if s:pager
-    nnoremap <silent> <buffer> <nowait> q :q<CR>
+    nnoremap <silent> <buffer> <nowait> q :lclose<CR>:q<CR>
   else
-    nnoremap <silent> <buffer> <nowait> q <C-W>c
+    nnoremap <silent> <buffer> <nowait> q :lclose<CR><C-W>c
   endif
 endif
 

runtime/ftplugin/qf.vim

@@ -14,3 +14,26 @@ let b:undo_ftplugin = "set stl<"
 
 " Display the command that produced the list in the quickfix window:
 setlocal stl=%t%{exists('w:quickfix_title')?\ '\ '.w:quickfix_title\ :\ ''}\ %=%-15(%l,%c%V%)\ %P
+
+function! s:setup_toc() abort
+  if get(w:, 'quickfix_title') !~# '\<TOC$' || &syntax != 'qf'
+    return
+  endif
+
+  let list = getloclist(0)
+  if empty(list)
+    return
+  endif
+
+  let bufnr = list[0].bufnr
+  setlocal modifiable
+  silent %delete _
+  call setline(1, map(list, 'v:val.text'))
+  setlocal nomodifiable nomodified
+  let &syntax = getbufvar(bufnr, '&syntax')
+endfunction
+
+augroup qf_toc
+  autocmd!
+  autocmd Syntax <buffer> call s:setup_toc()
+augroup END

runtime/syntax/help.vim

@@ -87,6 +87,8 @@ syn match helpSpecial		"CTRL-PageDown"
 syn match helpSpecial		"CTRL-Insert"
 syn match helpSpecial		"CTRL-Del"
 syn match helpSpecial		"CTRL-{char}"
+syn match helpSpecial		"META-."
+syn match helpSpecial		"ALT-."
 
 " Highlight group items in their own color.
 syn match helpComment		"\t[* ]Comment\t\+[a-z].*"

runtime/syntax/man.vim

@@ -18,6 +18,11 @@ highlight default link manOptionDesc     Constant
 highlight default link manReference      PreProc
 highlight default link manSubHeading     Function
 
+if &filetype != 'man'
+  " May have been included by some other filetype.
+  finish
+endif
+
 if !exists('b:man_sect')
   call man#init_pager()
 endif