runtime(helptoc): the helptoc package can be improved
Commit:
https://github.com/vim/vim/commit/ba0062b0c7b1377b4b8ffe3eaef8c65e0be346d7
Author: Peter Kenny <github....@k1w1.cyou>
Date: Mon May 5 20:15:39 2025 +0200
runtime(helptoc): the helptoc package can be improved
Adds the following changes:
- New Maintainer: Pete Kenny
- New filetypes supported (asciidoc, html, tex, vim, xhtml)
- improved Markdown support
- Sanitised ToCs and popup presentation
- Configuration improvements and options
- Add helptoc.txt help file
closes: #17255
Signed-off-by: Peter Kenny <github....@k1w1.cyou>
Signed-off-by: Christian Brabandt <c...@256bit.org>
diff --git a/.github/MAINTAINERS b/.github/MAINTAINERS
index 19a65c0c4..b5e2bc691 100644
--- a/.github/MAINTAINERS
+++ b/.github/MAINTAINERS
@@ -431,6 +431,7 @@ runtime/lang/menu_ru_ru.koi8-r.vim @RestorerZ
runtime/lang/menu_ru_ru.utf-8.vim @RestorerZ
runtime/pack/dist/opt/cfilter/plugin/cfilter.vim @yegappan
runtime/pack/dist/opt/comment/ @habamax
+runtime/pack/dist/opt/helptoc/ @kennypete
runtime/pack/dist/opt/matchit/ @chrisbra
runtime/pack/dist/opt/nohlsearch/ @habamax
runtime/plugin/manpager.vim @Konfekt
diff --git a/Filelist b/Filelist
index a7a937c01..17ec8df2f 100644
--- a/Filelist
+++ b/Filelist
@@ -808,6 +808,8 @@ RT_ALL = \
runtime/pack/dist/opt/editorconfig/ftdetect/editorconfig.vim \
runtime/pack/dist/opt/editorconfig/plugin/editorconfig.vim \
runtime/pack/dist/opt/helptoc/autoload/helptoc.vim \
+ runtime/pack/dist/opt/helptoc/doc/helptoc.txt \
+ runtime/pack/dist/opt/helptoc/doc/tags \
runtime/pack/dist/opt/helptoc/plugin/helptoc.vim \
runtime/pack/dist/opt/hlyank/plugin/hlyank.vim \
runtime/pack/dist/opt/justify/plugin/justify.vim \
diff --git a/runtime/doc/helphelp.txt b/runtime/doc/helphelp.txt
index 647c35ad2..4e08d9059 100644
--- a/runtime/doc/helphelp.txt
+++ b/runtime/doc/helphelp.txt
@@ -1,4 +1,4 @@
-*helphelp.txt* For Vim version 9.1. Last change: 2025 Apr 21
+*helphelp.txt* For Vim version 9.1. Last change: 2025 May 04
VIM REFERENCE MANUAL by Bram Moolenaar
@@ -287,9 +287,11 @@ The latter supports the following normal commands: >
<Home> | select first entry
<End> | select last entry
-The plugin can also provide a table of contents in man pages, markdown files,
-and terminal buffers. In the latter, the entries will be the past executed
-shell commands. To find those, the following pattern is used: >
+The plugin can also provide a table of contents in buffers of the following
+filetypes: asciidoc, html, man, markdown, tex, vim, and xhtml. In addition
+it also provide a table of contents for a terminal buffer, which produces
+entries that are the past executed shell commands. To find those, by default,
+the following pattern is used: >
^\w\+@\w\+: \+\$\s
@@ -303,6 +305,9 @@ Tip: After inserting a pattern to look for with the `/`
command, if you press
<Esc> instead of <CR>, you can then get more context for each remaining entry
by pressing `J` or `K`.
+Refer |helptoc.vim| for more details about helptoc, particularly about using
+it with filetypes other than help, and configuring its options.
+
==============================================================================
2. Translated help files *help-translated*
diff --git a/runtime/pack/dist/opt/helptoc/autoload/helptoc.vim
b/runtime/pack/dist/opt/helptoc/autoload/helptoc.vim
index c0d86a4e6..a22d4bafd 100644
--- a/runtime/pack/dist/opt/helptoc/autoload/helptoc.vim
+++ b/runtime/pack/dist/opt/helptoc/autoload/helptoc.vim
@@ -1,24 +1,71 @@
vim9script noclear
-
# Config {{{1
+# g:helptoc {{{2
+# Create the g:helptoc dict (used to specify the shell_prompt and other
+# options) when it does not exist
+g:helptoc = exists('g:helptoc') ? g:helptoc : {}
+
+# Set the initial shell_prompt pattern matching a default bash prompt
+g:helptoc.shell_prompt = get(g:helptoc, 'shell_prompt', '^\w\+@\w\+: \+\$\s')
-var SHELL_PROMPT: string = ''
+# Track the prior prompt (used to reset b:toc if 'shell_prompt' changes)
+g:helptoc.prior_shell_prompt = g:helptoc.shell_prompt
def UpdateUserSettings() #{{{2
- var new_prompt: string = g:
- ->get('helptoc', {})
- ->get('shell_prompt', '^\w\+@\w\+: \+\$\s')
- if new_prompt != SHELL_PROMPT
- SHELL_PROMPT = new_prompt
+
+ if g:helptoc.shell_prompt != g:helptoc.prior_shell_prompt
# invalidate cache: user config has changed
unlet! b:toc
+ # reset the prior prompt to the new prompt
+ g:helptoc.prior_shell_prompt = g:helptoc.shell_prompt
endif
+
+ # helptoc popup presentation options{{{
+ # Enable users to choose whether, in toc and help text popups, to have:
+ # - border (default [], which is a border, so is usually wanted)
+ # - borderchars (default single box drawing; use [] for Vim's defaults)
+ # - borderhighlight (default [], but a user may prefer something else)
+ # - close (default 'none'; mouse users may prefer 'button')
+ # - drag (default true, which is a popup_menu's default)
+ # - scrollbar (default false; for long tocs/HELP_TEXT true may be better)
+ # For example, in a Vim9 script .vimrc, these settings will produce tocs
+ # with borders that have the same highlight group as the inactive
+ # statusline, a scrollbar, and an 'X' close button:
+ # g:helptoc.popup_borderchars = get(g:helptoc, 'popup_borderchars', [' '])
+ # g:helptoc.popup_borderhighlight = get(g:helptoc,
+ # 'popup_borderhighlight', ['StatusLineNC'])
+ # g:helptoc.popup_close = get(g:helptoc, 'popup_close', 'button')
+ # g:helptoc.popup_scrollbar = get(g:helptoc, 'popup_scrollbar', true)
+ # }}}
+ g:helptoc.popup_border = get(g:helptoc, 'popup_border', [])
+ g:helptoc.popup_borderchars = get(g:helptoc, 'popup_borderchars',
+ ['─', '│', '─', '│', '┌', '┐', '┘', '└'])
+ g:helptoc.popup_borderhighlight = get(g:helptoc, 'popup_borderhighlight',
+ [])
+ g:helptoc.popup_drag = get(g:helptoc, 'popup_drag', true)
+ g:helptoc.popup_close = get(g:helptoc, 'popup_close', 'none')
+ g:helptoc.popup_scrollbar = get(g:helptoc, 'popup_scrollbar', false)
+ # For sanitized tocs, allow the user to specify the level indicator
+ g:helptoc.level_indicator = get(g:helptoc, 'level_indicator', '| ')
enddef
UpdateUserSettings()
-# Init {{{1
+# Syntax {{{1
+
+# Used by sanitized tocs (asciidoc, html, markdown, tex, vim, and xhtml)
+def SanitizedTocSyntax(): void
+ silent execute "syntax match helptocLevel _^\(" ..
+ g:helptoc.level_indicator .. "\)*_ contained"
+ silent execute "syntax region helptocText start=_^\(" ..
+ g:helptoc.level_indicator .. "\)*_ end=_$_ contains=helptocLevel"
+ highlight link helptocText Normal
+ highlight link helptocLevel NonText
+enddef
+# Init {{{1
+# Constants {{{2
+# HELP_TEXT {{{3
const HELP_TEXT: list<string> =<< trim END
normal commands in help window
──────────────────────────────
@@ -73,38 +120,108 @@ const HELP_TEXT: list<string> =<< trim END
more context for each remaining entry by pressing J or K
END
+# UPTOINC_H {{{3
+const UPTOINC_H: string = '
--
--
You received this message from the "vim_dev" maillist.
Do not top-post! Type your reply below the text you are replying to.
For more information, visit http://www.vim.org/maillist.php
---
You received this message because you are subscribed to the Google Groups
"vim_dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to vim_dev+unsubscr...@googlegroups.com.
To view this discussion visit
https://groups.google.com/d/msgid/vim_dev/E1uC0Zn-009uwo-BG%40256bit.org.
