runtime(helptoc): add s keymap to split and jump to selected entry

closes: #17876

Signed-off-by: lacygoill <lacygoill@lacygoill.me>
Signed-off-by: Christian Brabandt <cb@256bit.org>

runtime/doc/helphelp.txt

@@ -1,4 +1,4 @@
-*helphelp.txt*	For Vim version 9.1.  Last change: 2025 Jul 07
+*helphelp.txt*	For Vim version 9.1.  Last change: 2025 Aug 06
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -253,20 +253,21 @@ If you want to access an interactive table of contents, from any position in
 the file, you can use the helptoc plugin.  Load the plugin with: >vim
 
     packadd helptoc
-
+<
+					*HelpToc-mappings*
 Then you can use the `:HelpToc` command to open a popup menu.
 The latter supports the following normal commands: >
 
 	key | effect
 	----+---------------------------------------------------------
-	j   | select next entry
-	k   | select previous entry
-	J   | same as j, and jump to corresponding line in main buffer
-	K   | same as k, and jump to corresponding line in main buffer
 	c   | select nearest entry from cursor position in main buffer
 	g   | select first entry
 	G   | select last entry
 	H   | collapse one level
+	j   | select next entry
+	J   | same as j, and jump to corresponding line in main buffer
+	k   | select previous entry
+	K   | same as k, and jump to corresponding line in main buffer
 	L   | expand one level
 	p   | print current entry on command-line
 
@@ -274,6 +275,7 @@ The latter supports the following normal commands: >
 	    | press multiple times to toggle feature on/off
 
 	q   | quit menu
+	s   | split window, and jump to selected entry
 	z   | redraw menu with current entry at center
 	+   | increase width of popup menu
 	-   | decrease width of popup menu

runtime/doc/tags

@@ -5656,6 +5656,7 @@ GetLatestVimScripts_dat	pi_getscript.txt	/*GetLatestVimScripts_dat*
 Gnome	gui_x11.txt	/*Gnome*
 H	motion.txt	/*H*
 Haiku	os_haiku.txt	/*Haiku*
+HelpToc-mappings	helphelp.txt	/*HelpToc-mappings*
 I	insert.txt	/*I*
 ICCF	uganda.txt	/*ICCF*
 IM-server	mbyte.txt	/*IM-server*

runtime/pack/dist/opt/helptoc/autoload/helptoc.vim

@@ -104,6 +104,7 @@ const HELP_TEXT: list<string> =<< trim END
 
     <C-D>       scroll down half a page
     <C-U>       scroll up half a page
+    s           split window, and jump to selected entry
     <PageUp>    scroll down a whole page
     <PageDown>  scroll up a whole page
     <Home>      select first entry
@@ -134,6 +135,23 @@ const MATCH_ENTRY: dict<dict<func: bool>> = {
 
     help: {},
 
+    # This lets the user get a TOC when piping `info(1)` to Vim:{{{
+    #
+    #     $ info coreutils | vim -
+    #}}}
+    # But it assumes that they have some heuristics to set the `info` filetype.{{{
+    #
+    # Possibly by inspecting the first line from `scripts.vim`:
+    #
+    #     if getline(1) =~ '^File: .*\.info,  Node: .*,  \%(Next\|Prev\): .*,  Up: \|This is the top of the INFO tree.'
+    #         setfiletype info
+    #     endif
+    #}}}
+    info: {
+        1: (l: string, nextline): bool => l =~ '^\d\+\%(\.\d\+\)\+ ' && nextline =~ '^=\+$',
+        2: (l: string, nextline): bool => l =~ '^\d\+\%(\.\d\+\)\+ ' && nextline =~ '^-\+$',
+    },
+
     # For asciidoc, these patterns should match:
     # https://docs.asciidoctor.org/asciidoc/latest/sections/titles-and-levels/
     asciidoc: {
@@ -618,7 +636,7 @@ def SetTocHelp() #{{{2
         if in_list
                 && curline !~ '^\d\+.\s'
                 && curline !~ '^\s*$'
-        && curline !~ '^[< \t]'
+                && curline !~ '^[<[:blank:]]'
             in_list = false
         endif
 
@@ -671,7 +689,7 @@ def SetTocHelp() #{{{2
         # header ~
         if curline =~ '\~$'
                 && curline =~ '\w'
-        && curline !~ '^[ \t<]\|\t\|---+---\|^NOTE:'
+                && curline !~ '^[[:blank:]<]\|\t\|---+---\|^NOTE:'
                 && curline !~ '^\d\+\.\%(\d\+\%(\.\d\+\)\=\)\=\s'
                 && prevline !~ $'^\s*{HELP_TAG}'
                 && prevline !~ '\~$'
@@ -763,7 +781,7 @@ def AddEntryInTocHelp(type: string, lnum: number, line: string) #{{{2
         text = tags
             # we ignore errors and warnings because those are meaningless in
             # a TOC where no context is available
-            ->filter((_, tag: string) => tag !~ '\*[EW]\d\+\*')
+            ->filter((_, tag: string): bool => tag !~ '\*[EW]\d\+\*')
             ->join()
         if text !~ HELP_TAG
             return
@@ -871,12 +889,25 @@ enddef
 
 def SelectNearestEntryFromCursor(winid: number) #{{{2
     var lnum: number = line('.')
-    var firstline: number = b:toc.entries
-        ->copy()
-        ->filter((_, line: dict<any>): bool =>
-            line.lvl <= b:toc.curlvl && line.lnum <= lnum)
-        ->len()
-    if firstline == 0
+    if lnum == 1
+        Win_execute(winid, 'normal! 1G')
+        return
+    endif
+
+    if lnum == line('$')
+        Win_execute(winid, 'normal! G')
+        return
+    endif
+
+    var collapsed_entries: list<dict<any>> = b:toc.entries
+        ->deepcopy()
+        ->filter((_, entry: dict<any>): bool => entry.lvl <= b:toc.curlvl)
+    var firstline: number = collapsed_entries
+        ->reverse()
+        ->indexof((_, entry: dict<any>): bool => entry.lnum <= lnum)
+    firstline = len(collapsed_entries) - firstline
+
+    if firstline <= 0
         return
     endif
     Win_execute(winid, $'normal! {firstline}Gzz')
@@ -937,18 +968,21 @@ def Filter(winid: number, key: string): bool #{{{2
         SetTitle(winid)
 
         return true
+    endif
 
-    elseif key == 'c'
+    if key == 'c'
         SelectNearestEntryFromCursor(winid)
         return true
+    endif
 
     # when we press `p`, print the selected line (useful when it's truncated)
-    elseif key == 'p'
+    if key == 'p'
         PrintEntry(winid)
         return true
+    endif
 
     # same thing, but automatically
-    elseif key == 'P'
+    if key == 'P'
         print_entry = !print_entry
         if print_entry
             PrintEntry(winid)
@@ -956,17 +990,20 @@ def Filter(winid: number, key: string): bool #{{{2
             echo ''
         endif
         return true
+    endif
 
-    elseif key == 'q'
+    if key == 'q'
         popup_close(winid, -1)
         return true
+    endif
 
-    elseif key == '?'
+    if key == '?'
         ToggleHelp(winid)
         return true
+    endif
 
     # scroll help window
-    elseif key == "\<C-J>" || key == "\<C-K>"
+    if key == "\<C-J>" || key == "\<C-K>"
         var scroll_cmd: string = {"\<C-J>": 'j', "\<C-K>": 'k'}->get(key, key)
         if scroll_cmd == 'j' && line('.', help_winid) == line('$', help_winid)
             scroll_cmd = '1G'
@@ -975,9 +1012,16 @@ def Filter(winid: number, key: string): bool #{{{2
         endif
         Win_execute(help_winid, $'normal! {scroll_cmd}')
         return true
+    endif
+
+    # split main window
+    if key == 's'
+        split
+        return popup_filter_menu(winid, "\<CR>")
+    endif
 
     # increase/decrease the popup's width
-    elseif key == '+' || key == '-'
+    if key == '+' || key == '-'
         var width: number = winid->popup_getoptions().minwidth
         if key == '-' && width == 1
                 || key == '+' && winid->popup_getpos().col == 1
@@ -988,13 +1032,15 @@ def Filter(winid: number, key: string): bool #{{{2
         b:toc.width = width
         popup_setoptions(winid, {minwidth: width, maxwidth: width})
         return true
+    endif
 
-    elseif key == 'H' && b:toc.curlvl > 1
+    if key == 'H' && b:toc.curlvl > 1
             || key == 'L' && b:toc.curlvl < b:toc.maxlvl
         CollapseOrExpand(winid, key)
         return true
+    endif
 
-    elseif key == '/'
+    if key == '/'
         # This is probably what the user expects if they've started a first
         # fuzzy search, press Escape, then start a new one.
         DisplayNonFuzzyToc(winid)
@@ -1005,7 +1051,8 @@ def Filter(winid: number, key: string): bool #{{{2
             pattern: '@',
             cmd: $'FuzzySearch({winid})',
             replace: true,
-        }, {
+        },
+        {
             group: 'HelpToc',
             event: 'CmdlineLeave',
             pattern: '@',
@@ -1167,7 +1214,8 @@ def Callback(winid: number, choice: number) #{{{2
     if choice == -1
         fuzzy_entries = null_list
         return
-    elseif choice == -2  # Button X is clicked (when close: 'button')
+    endif
+    if choice == -2  # Button X is clicked (when close: 'button')
         return
     endif
 
@@ -1181,8 +1229,10 @@ def Callback(winid: number, choice: number) #{{{2
         return
     endif
 
-    cursor(lnum, 1)
-    normal! zvzt
+    # Moving the cursor with `normal! 123G` instead of `cursor()` adds an
+    # entry in the jumplist (which is useful if you want to come back where
+    # you were).
+    execute $'normal! {lnum}Gzvzt'
 enddef
 
 def ToggleHelp(menu_winid: number) #{{{2

runtime/pack/dist/opt/helptoc/doc/helptoc.txt

@@ -1,10 +1,9 @@
-*helptoc.txt*   For Vim version 9.1.  Last change:  2025 May 04
+*helptoc.txt*   For Vim version 9.1.  Last change:  2025 Aug 06
 
 
 			  VIM REFERENCE MANUAL
 
 Interactive table of contents for help buffers and several other filetypes
-
 ==============================================================================
 
 
@@ -12,8 +11,11 @@ Interactive table of contents for help buffers and several other filetypes
 
 The helptoc.vim plugin provides one command, :HelpToc, which generates a
 hierarchical table of contents in a popup window, which is based on the
-structure of a Vim buffer.  It was designed initially for help buffers,
-but it also works with buffers of the following types:
+structure of a Vim buffer.  See |Helptoc-mappings| for a list of supported key
+mappings in the popup window.
+
+It was designed initially for help buffers, but it also works with buffers of
+the following types:
 	- asciidoc
 	- html
 	- man