[RFC] optional plugin to provide table of contents in help files in popup menu #10446

lacygoill · 2022-05-19T02:45:36Z

Usually, there is a table of contents at the top of a help file. But it might not be detailed enough. And having to jump to the top of the file makes us lose the current context. This PR adds an optional helptoc plugin which lets the user access an interactive popup menu showing a table of contents for the current help file, from any position in the latter.

Among other features, the menu can be collapsed or expanded to control the type of overview one wants to see (e.g. only the main sections, or everything down to every tag). Also, it can be fuzzy searched to find an arbitrary entry from some text input by the user.

Here is a short demo:

https://i.imgur.com/23RwN1K.mp4

It also works in man pages, markdown files, and terminal buffers. I added a short documentation at :help help-TOC.

I think it could be helpful to people frequently using Vim to read some documentation. If I'm wrong, feel free to close the PR.

benknoble · 2022-05-19T15:10:38Z

I like this. From a quick glance, I noticed it supports standard help tags. How does it deal with the help headers as I saw in the video? If there is a "standard" way to support helptoc, documenting it as such would mean 3rd-party help files could be written to support it as well.

codecov · 2022-05-19T15:32:30Z

Codecov Report

Merging #10446 (f11f1cd) into master (aaadb5b) will decrease coverage by 0.03%.
The diff coverage is n/a.

❗ Current head f11f1cd differs from pull request most recent head ba7f3b9. Consider uploading reports for the commit ba7f3b9 to get more accurate results

@@            Coverage Diff             @@
##           master   #10446      +/-   ##
==========================================
- Coverage   81.62%   81.60%   -0.03%     
==========================================
  Files         158      158              
  Lines      184737   184986     +249     
  Branches    41768    41844      +76     
==========================================
+ Hits       150797   150960     +163     
- Misses      21452    21506      +54     
- Partials    12488    12520      +32

Flag	Coverage Δ
huge-clang-none	`82.52% <ø> (-0.03%)`	⬇️
linux	`82.52% <ø> (-0.03%)`	⬇️
mingw-x64-HUGE	`0.00% <ø> (ø)`
mingw-x64-HUGE-gui	`78.02% <ø> (-0.01%)`	⬇️
windows	`76.80% <ø> (-0.01%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

see 36 files with indirect coverage changes

lacygoill · 2022-05-22T04:48:44Z

I like this. From a quick glance, I noticed it supports standard help tags. How does it deal with the help headers as I saw in the video? If there is a "standard" way to support helptoc, documenting it as such would mean 3rd-party help files could be written to support it as well.

Sorry for the late response, I couldn't answer earlier.

Help files are tricky to handle, because there doesn't seem to be a widely adopted convention. At least one which is accurate enough. It seems everybody uses various types of headers however they like, or based on how they look, not much on what their type mean. Anyway, the plugin tries to add these lines as entries in the TOC:

*01.1* some text
1. some text
1.2 some text
1.2.3 some text
some header ~
SOME HEADLINE

The tricky part is:

not conflating 1. with a simple list item (like at :help registers)
assigning the correct level to each entry (the tags are always assigned the highest level, since their scope is always the smallest one)

I don't remember the exact logic. I just tested the algorithm on as many help files I had (builtin + third-party) and checked the end result looked as much as possible to what the user would expect.

Also, fix issue where the cache might not be invalidated in a terminal buffer (`++once` can't be used because the `ModeChanged` event could be fired in a different terminal buffer).

runtime/doc/helphelp.txt

…en menu

chrisbra · 2024-11-02T16:59:15Z

I tried it out and it is quite nice. Thanks for this!

benknoble · 2024-11-03T01:39:45Z

runtime/doc/helphelp.txt

+	z   | redraw menu with current entry at center
+	+   | increase width of popup menu
+	-   | decrease width of popup menu
+	?   | show/hide a help window


It seems search / is missing?

benknoble · 2024-11-03T01:40:01Z

runtime/doc/helphelp.txt

+
+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 regex is used: >


Probably this should say pattern, not regex.

I fix both, thanks!

closes: vim#10446 See :h help-TOC Signed-off-by: lagygoill <lacygoill@lacygoill.me> Signed-off-by: Christian Brabandt <cb@256bit.org>

related: #10446 Signed-off-by: Christian Brabandt <cb@256bit.org>

ychin · 2024-11-19T09:35:05Z

I just tried this out and it's pretty cool. I especially found it useful for Man pages.

Just a couple comments for potential improvements:

For terminal buffer usage, one issue is I find it really confusing that the setting g:helptoc['shell_prompt'] is cached to an internal variable SHELL_PROMPT. Is that for performance reasons? The issue with doing this is if the user changes that value to something else, it wouldn't be reflected in the plugin unless they restart Vim, which for me led to a bit of frustrating debugging as I thought I did something wrong. I think it should always respect the up-to-date value, either by not caching, or updating the cache if the value was updated. Options that can only be set in the initial vimrc are annoying to use and debug.
- I think it could also be useful to support a buffer-local variable instead of a global g:helptoc but that's secondary.
Given that this plugin doesn't have its own docs, I think there should be a help tag for :Helptoc. Generally I think I should be able to type :help <command> for any command I can type. It's not intuitive that I have to remember to type :h help-toc to see the help.

chrisbra · 2024-11-19T22:02:09Z

I'll add the :Helptoc tag. I leave the rest for a followup PR

Follow up on PR 10446 [1] so that changes at run-time (or after loading a vimrc) are reflected at next use. [1]: vim#10446 (comment)

benknoble · 2024-11-21T01:25:09Z

A first step: #16097.

Follow up on PR 10446 [1] so that changes at run-time (or after loading a vimrc) are reflected at next use. Instead of "uncaching" the variable by computing SHELL_PROMPT on each use, which could negatively impact performance, reload any user settings before creating the toc. [1]: vim#10446 (comment) Best-viewed-with: --ignore-space-change

Follow up on PR 10446 [1] so that changes at run-time (or after loading a vimrc) are reflected at next use. Instead of "uncaching" the variable by computing SHELL_PROMPT on each use, which could negatively impact performance, reload any user settings before creating the TOC. Also make sure, changes to the shell prompt variable do correctly invalidate b:toc, so that the table of content is correctly re-created after user makes any changes. [1]: #10446 (comment) closes: #16097 Signed-off-by: D. Ben Knoble <ben.knoble+github@gmail.com> Signed-off-by: Christian Brabandt <cb@256bit.org>

@sfsam

Updated to Vim 9.1.1128 This update contains a completely new GUI tabs implementation by @sfsam! It also contains lots of small fixes for window resizing and full screen mode that aims to make using MacVim feel rock solid and stable. Defaults Change ==================== New settings defaults related to window sizing #1528: - "Smoothly resizes window" is now on by default. MacVim's window will now resize smoothly instead of snapped to the size of the character grid. - Vim's `guioption` now has `k` set by default (`:h go-k`). This prevents MacVim's window size from changing unnecessarily when showing/hiding tabs or changing font size. These should align MacVim better with how other apps work and integrate better with OS window management, including macOS 15 Sequoia's window tiling feature. Features ==================== Tabs -------------------- MacVim has a new tabs implementation! The old version (PSMTabBarControl) is not maintained and lacks features such as overflowing tabs and customizable colors. The new tabs will overflow horizontally and are scrollable. They also animate when tabs are closed or moved, respect system settings such as right-to-left locales and high-contrast modes, and are designed to fit within the currently selected Vim colors. There are a few ways to customize the colors of the new tabs, under the "Appearance" settings pane. MacVim defaults to an "Automatic colors" mode which tries to pick sensible colors automatically based on the current foreground/background colors. However, you can also configure it to simply use the tab colors specified by the Vim color scheme (some color schemes will work better than others depending on their choice of colors). Another new option is "Use tabs background color" which when combined with "Transparent title bar" allows the title bar and tabs to look like a single cohesive whole. Relevant work: - #1120 (by @sfsam) - Also: #1535 / #1536 / #1537 / #1538 / #1539 / #1557 / #1558 / #1560 New Vim features -------------------- - new bundled color scheme: - unokai (vim/vim#16443) - new bundled optional plugins (use `packadd` to enable them): - helptoc: Use `:HelpToc` to show an interactive table of contents for Vim help, man pages, Markdown files, and terminal. vim/vim#10446 - new options: - `set diffopt+=linematch:{n}`. Matches lines better when in diff mode. v9.1.1099 - `findfunc`. Customizes `:find` and other commands. v9.1.0831 - `set completeopt+=preinsert`. Preview inserted text in completion. v9.1.1056 - `messagesopt`. Allows customizing hit-enter behavior. v9.1.0908 - new functions: - `getcellpixels()`. Query the pixel size of a character cell in the grid. v9.1.0854 / #1554 / #1555 - Vim tutor has a new interactive plugin (v9.1.0836). There is also now a chapter 2 (vim/vim#5729). Misc New Settings -------------------- - "Open untitled window" (General) has a new option to only open on MacVim re-activation. #1509 - "Show document icon at title bar" (Appearance). Previously MacVim implicitly hid the document icon when using transparent title bar. This is now customizable. #1510 General ==================== - The MacVim dmg installer has a new design. Courtesy of @jasonlong. #1540 #1545 - Legacy builds (macOS 10.9 - 10.12) are no longer built by GitHub hosted runners, due to GitHub's deprecation of old runners. They are now built by a custom self-hosted VM instead. In the future we hope to set up reproducible builds (#1506) so it will not matter who's building the app as it would be verifiable. #1559 - "Nightly" build: We now build a dmg installer for every commit. This allows for trying out the latest developmental version of MacVim, but note that the app will not be signed / notarized, and it will not be as polished as official release/pre-release builds. See [wiki](https://github.com/macvim-dev/macvim/wiki/Installing) for instructions. #1532 Fixes ==================== Apple "Intelligence" Writing Tools -------------------- macOS 15 Sequoia's Apple "Intelligence" Writing Tools should work correctly with MacVim now. To use it, select some text, right click to show menu, and then select the "Writing Tools" sub-menu. As part of this fix, the integration with the "Services" menu now works more reliably as well. You can select texts in blockwise visual mode and select a service and MacVim will try to place the new texts back to the blockwise selection if possible. #1552 Window resizing and full screen -------------------- - Flicker begone: Changing font size, showing/hiding tabs or scroll bars, or entering non-native full screen should no longer cause MacVim to flicker. Previously there could be a momentary but distracting/annoying stale image that flashes briefly. #1547 #1549 - Fixed issue where resizing MacVim window would occasionally cause Vim to be stuck in a stale wrong size. #1518 - Non-native full screen now supports `blurradius` option. #1546 - Fixed window size not always restoring correctly when exiting full screen. Non-native full screen also works more reliably in multi-monitor setup. #1525 - Fixed non-native full screen mode when using an external monitor with a MacBook with a notch, and having the "Show menu bar in non-native mode" option set. Previously MacVim would sometimes miscalculate the menu bar height in the second screen. #1548 - Fixed misc issues with non-native full screen's interaction with `fuoptions` and also the `transparency` setting, and rare crash. #1521 Other Fixes -------------------- - Fixed issue where changing font size (using Cmd =/-) with guifont set to "-monospace-" would result in guifont being changed to a confusing name like ".AppleSystemUIFontMonospaced-Regular". #1544 - "MacVim Website" menu item now goes to the updated URL. #1524 - What's New page now allows changing font size (using Cmd =/-), and showing table of contents. #1561 #1562 - Dark mode documentation is now a bit clearer on `v:os_appearance`. #1511 - Using dictionary look up on selected texts (by right clicking and then selecting "Look Up" in the pop-up menu) is now more resilient as it uses Vim's native `getregion()` to determine the selected texts. #1508 Scripting ==================== - Scripting languages versions: - Ruby is now built against 3.4, up from 3.3. - Perl is now built against 5.34, up from 5.30. Compatibility ==================== Requires macOS 10.9 or above. (10.9 - 10.12 requires downloading a separate legacy build) Script interfaces have compatibility with these versions: - Lua 5.4 - Perl 5.34 - Python2 2.7 - Python3 3.9 or above - Ruby 3.4

@sfsam

Updated to Vim 9.1.1128 This update contains a completely new GUI tabs implementation by @sfsam! It also contains lots of small fixes for window resizing and full screen mode that aims to make using MacVim feel rock solid and stable. Defaults Change ==================== New settings defaults related to window sizing #1528: - "Smoothly resizes window" is now on by default. MacVim's window will now resize smoothly instead of snapped to the size of the character grid. - Vim's `guioption` now has `k` set by default (`:h go-k`). This prevents MacVim's window size from changing unnecessarily when showing/hiding tabs or changing font size. These should align MacVim better with how other apps work and integrate better with OS window management, including macOS 15 Sequoia's window tiling feature. Features ==================== Tabs -------------------- MacVim has a new tabs implementation! The old version (PSMTabBarControl) is not maintained and lacks features such as overflowing tabs and customizable colors. The new tabs will overflow horizontally and are scrollable. They also animate when tabs are closed or moved, respect system settings such as right-to-left locales and high-contrast modes, and are designed to fit within the currently selected Vim colors. There are a few ways to customize the colors of the new tabs, under the "Appearance" settings pane. MacVim defaults to an "Automatic colors" mode which tries to pick sensible colors automatically based on the current foreground/background colors. However, you can also configure it to simply use the tab colors specified by the Vim color scheme (some color schemes will work better than others depending on their choice of colors). Another new option is "Use tabs background color" which when combined with "Transparent title bar" allows the title bar and tabs to look like a single cohesive whole. Relevant work: - #1120 (by @sfsam) - Also: #1535 / #1536 / #1537 / #1538 / #1539 / #1557 / #1558 / #1560 New Vim features -------------------- - new bundled color scheme: - unokai (vim/vim#16443) - new bundled optional plugins (use `packadd` to enable them): - helptoc: Use `:HelpToc` to show an interactive table of contents for Vim help, man pages, Markdown files, and terminal. vim/vim#10446 - new options: - `set diffopt+=linematch:{n}`. Matches lines better when in diff mode. v9.1.1099 - `findfunc`. Customizes `:find` and other commands. v9.1.0831 - `set completeopt+=preinsert`. Preview inserted text in completion. v9.1.1056 - `messagesopt`. Allows customizing hit-enter behavior. v9.1.0908 - new functions: - `getcellpixels()`. Query the pixel size of a character cell in the grid. v9.1.0854 / #1554 / #1555 - Vim tutor has a new interactive plugin (v9.1.0836). There is also now a chapter 2 (vim/vim#5729). Misc New Settings -------------------- - "Open untitled window" (General) has a new option to only open on MacVim re-activation. #1509 - "Show document icon at title bar" (Appearance). Previously MacVim implicitly hid the document icon when using transparent title bar. This is now customizable. #1510 General ==================== - The MacVim dmg installer has a new design. Courtesy of @jasonlong. #1540 #1545 - Legacy builds (macOS 10.9 - 10.12) are no longer built by GitHub hosted runners, due to GitHub's deprecation of old runners. They are now built by a custom self-hosted VM instead. In the future we hope to set up reproducible builds (#1506) so it will not matter who's building the app as it would be verifiable. #1559 - "Nightly" build: We now build a dmg installer for every commit. This allows for trying out the latest developmental version of MacVim, but note that the app will not be signed / notarized, and it will not be as polished as official release/pre-release builds. See [wiki](https://github.com/macvim-dev/macvim/wiki/Installing) for instructions. #1532 Fixes ==================== Apple "Intelligence" Writing Tools -------------------- macOS 15 Sequoia's Apple "Intelligence" Writing Tools should work correctly with MacVim now. To use it, select some text, right click to show menu, and then select the "Writing Tools" sub-menu. As part of this fix, the integration with the "Services" menu now works more reliably as well. You can select texts in blockwise visual mode and select a service and MacVim will try to place the new texts back to the blockwise selection if possible. #1552 Window resizing and full screen -------------------- - Flicker begone: Changing font size, showing/hiding tabs or scroll bars, or entering non-native full screen should no longer cause MacVim to flicker. Previously there could be a momentary but distracting/annoying stale image that flashes briefly. #1547 #1549 - Fixed issue where resizing MacVim window would occasionally cause Vim to be stuck in a stale wrong size. #1518 - Non-native full screen now supports `blurradius` option. #1546 - Fixed window size not always restoring correctly when exiting full screen. Non-native full screen also works more reliably in multi-monitor setup. #1525 - Fixed non-native full screen mode when using an external monitor with a MacBook with a notch, and having the "Show menu bar in non-native mode" option set. Previously MacVim would sometimes miscalculate the menu bar height in the second screen. #1548 - Fixed misc issues with non-native full screen's interaction with `fuoptions` and also the `transparency` setting, and rare crash. #1521 Other Fixes -------------------- - Fixed issue where changing font size (using Cmd =/-) with guifont set to "-monospace-" would result in guifont being changed to a confusing name like ".AppleSystemUIFontMonospaced-Regular". #1544 - "MacVim Website" menu item now goes to the updated URL. #1524 - What's New page now allows changing font size (using Cmd =/-), and showing table of contents. #1561 #1562 - Dark mode documentation is now a bit clearer on `v:os_appearance`. #1511 - Using dictionary look up on selected texts (by right clicking and then selecting "Look Up" in the pop-up menu) is now more resilient as it uses Vim's native `getregion()` to determine the selected texts. #1508 Scripting ==================== - Scripting languages versions: - Ruby is now built against 3.4, up from 3.3. - Perl is now built against 5.34, up from 5.30. Compatibility ==================== Requires macOS 10.9 or above. (10.9 - 10.12 requires downloading a separate legacy build) Script interfaces have compatibility with these versions: - Lua 5.4 - Perl 5.34 - Python2 2.7 - Python3 3.9 or above - Ruby 3.4

lagygoill added 2 commits May 19, 2022 02:04

first commit

da60d94

fix: P was printing wrong entry

54f4fe2

k-takata added the runtime label May 19, 2022

lagygoill added 16 commits May 22, 2022 10:40

include max level in title

12cac7d

align toplines of help window and popup menu

083215b

in terminal buffer, highlight TOC menu with Terminal instead of Normal

aae59fb

same thing for help window

f11f1cd

let user manually select nearest entry from cursor

7fd09bc

only uppercase identifiers related to user config

1a74bc6

promote TearDown() to the script-level

24e525e

Also, fix issue where the cache might not be invalidated in a terminal buffer (`++once` can't be used because the `ModeChanged` event could be fired in a different terminal buffer).

handle possible user interrupt when calling input()

af03b2b

make cache invalidation more reliable in terminal buffer

14f56c5

fix: title was not always properly updated

bcfd7bc

simplify return; rename function; add comment

d8037e3

rename variable to make it more meaningful

24846fc

simplify type check validation

90168cb

fix: max level was sometimes wrong in manpages

03ebf6f

DRYer

5dea300

remove useless utility function

a346520

yegappan reviewed May 24, 2022

View reviewed changes

runtime/doc/helphelp.txt Outdated Show resolved Hide resolved

lagygoill added 7 commits May 24, 2022 07:41

support <PageUp>, <PageDown>, <Home>, <End>

20d789a

update documentation

7dfc49b

be consistent when conjugating verb into the imperative

05a256c

update documentation in help window

fcb1ec8

soft-wrap long lines in help window in more readable way

0b39f05

handle autocmds with new autocmd_*() functions

19add9d

add TODO item

5f1b5b1

lagygoill added 10 commits May 24, 2022 12:03

fix: print 0/0 instead of 1/1 in title when TOC is empty

5db93dc

no need to compute last lnum twice

e73d029

fix: temporary mappings not removed when interrupting fuzzy search th…

1567296

…en menu

tear down temporary mappings earlier in case of an interruption

3728a1f

if a user starts a 2nd fuzzy search, they expect the TOC to be reset

64b8028

better name function

8f11147

make sure not to install duplicate autocmds

3feb443

fix typo

d21edeb

fix: popup filter did not consume "c" keypress after handling it

2b97677

don't try to handle pum on top of popup terminal

115f3ae

lacygoill mentioned this pull request Feb 26, 2023

Feedback on this proposal for packaging modern resources for plugin developers lifepillar/vim-devel#1

Open

lacygoill added 2 commits April 30, 2023 23:00

fix tab completion when looking for given text

1ae4f7d

support options in man pages

ba7f3b9

yegappan added this to the backlog milestone Aug 14, 2023

lacygoill mentioned this pull request Sep 14, 2023

Can't find this wonderful work in the release? lacygoill/vim9-syntax#7

Open

chrisbra closed this in b3ec564 Nov 2, 2024

benknoble reviewed Nov 3, 2024

View reviewed changes

techntools pushed a commit to techntools/vim that referenced this pull request Nov 3, 2024

runtime(doc): include a TOC Vim9 plugin

1c6f8b0

closes: vim#10446 See :h help-TOC Signed-off-by: lagygoill <lacygoill@lacygoill.me> Signed-off-by: Christian Brabandt <cb@256bit.org>

chrisbra added a commit that referenced this pull request Nov 3, 2024

runtime(doc): update help-toc description

6081c17

related: #10446 Signed-off-by: Christian Brabandt <cb@256bit.org>

benknoble added a commit to benknoble/vim that referenced this pull request Nov 21, 2024

runtime/helptoc: uncache g:helptoc.shell_prompt

5241774

Follow up on PR 10446 [1] so that changes at run-time (or after loading a vimrc) are reflected at next use. [1]: vim#10446 (comment)

benknoble mentioned this pull request Nov 21, 2024

[RFC] runtime/helptoc: uncache g:helptoc.shell_prompt #16097

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[RFC] optional plugin to provide table of contents in help files in popup menu #10446

[RFC] optional plugin to provide table of contents in help files in popup menu #10446

lacygoill commented May 19, 2022

benknoble commented May 19, 2022

codecov bot commented May 19, 2022 •

edited

Loading

lacygoill commented May 22, 2022

chrisbra commented Nov 2, 2024

benknoble Nov 3, 2024

benknoble Nov 3, 2024

chrisbra Nov 3, 2024

ychin commented Nov 19, 2024 •

edited

Loading

chrisbra commented Nov 19, 2024

benknoble commented Nov 21, 2024

[RFC] optional plugin to provide table of contents in help files in popup menu #10446

[RFC] optional plugin to provide table of contents in help files in popup menu #10446

Conversation

lacygoill commented May 19, 2022

benknoble commented May 19, 2022

codecov bot commented May 19, 2022 • edited Loading

Codecov Report

lacygoill commented May 22, 2022

chrisbra commented Nov 2, 2024

benknoble Nov 3, 2024

Choose a reason for hiding this comment

benknoble Nov 3, 2024

Choose a reason for hiding this comment

chrisbra Nov 3, 2024

Choose a reason for hiding this comment

ychin commented Nov 19, 2024 • edited Loading

chrisbra commented Nov 19, 2024

benknoble commented Nov 21, 2024

codecov bot commented May 19, 2022 •

edited

Loading

ychin commented Nov 19, 2024 •

edited

Loading