[vim/vim] refactor/improve helpcurwin in Vim9 script and make it a standard plugin (PR #18840)

[Peter Kenny]

runtime/plugin/helpcurwin.vim

Enhancing the command and function in tips.txt

Currently, tips.txt (tag *help-curwin*) includes a command and legacy Vim script function providing the ability to open help in the current window. It’s okay, though not optimal, because:

1. It would be better to provide the recommended functionality without users needing either to weave a legacy Vim script into their .vimrc or create a plugin, command, etc., themselves.
2. There are not many legacy Vim scripts in Vim’s help promoted as complete solutions - and perhaps only two if you, :helpgrep ^\tfunction\ss:; both are in tips.txt, with help-curwin following on from “the slightly less advanced version” of matchparen. So, providing helpcurwin as a standard plugin makes sense in that context, joining matchparen.
3. The function can be improved. For example, the execute commands in the script open a transition help buffer, then close it. That is not ideal because it breaks the tags list. Using CTRL-T to go back through the tags reveals a transitional help.txt buffer, which also pollutes the buffer list unnecessarily.
4. Although not a big thing from a performance perspective given it is a short script, making it Vim9 script is a contemporary improvement.
5. Improvements such as a <Plug> mapping make it more versatile, enabling help in the current window from WORD. Another improvement is checking for a modified buffer, and asking whether the user wants to proceed when it is modified.
6. As a standard plugin with a new help file, pi_helpcurwin.txt, it will be easier for users to use helpcurwin.

The legacy Vim script in action

As noted, above, the legacy Vim script does not handle tags properly so CTRL-T back through the help buffers does not perform as expected, and an unnecessary help.txt buffer is retained, shown in the following GIF:

The help.txt buffer also pollutes the buffer list unnecessarily. A further deficiency is the function will not work from a terminal buffer (not shown).

runtime/plugin/helpcurwin.vim in action

The same is not the case with the helpcurwin plugin. With it loaded, it works as expected, as shown in this GIF:

The GIF also shows helpcurwin#Open({subject}) and <Plug>HelpCurwin;.

Not shown

• It works from a terminal buffer (CTRL-W  :  then :HelpCurwin {subject}).
• There is no buffer pollution like there is with the legacy function’s help.txt transition buffers.

Updated tips.txt and new pi_helpcurwin.txt

The new dedicated help, pi_helpcurwin.txt replaces and expands on the content under *help-curwin* in tips.txt. The tag has been retained in the form, *help-curwin*, only for hot-linking from the Contents in tips.txt.

Why not just make it only Vim9 script and/or pack/dist/opt?

It could be a pack/dist/opt package/plugin, though a few things make it more compelling as a standard plugin in runtime/plugin, I think:

• The improved Vim9 script’s functionality really is useful, generally. For example, it enables simple and fine control over using a particular help window or several help windows. Although that can be achieved using workarounds without helpcurwin, providing :HelpCurwin, etc., simplifies it.
• It has 000.000 sourcing time, so there is no, or at least trivial,
  startuptime impact.
• The history of issue 7534 points to a solution being only partly delivered in a rather latent manner, so:

  • It is a natural progression to refactor, improve, and broaden helpcurwin’s availability, and

  • This standard plugin implementation does not alter normal :help behaviour, keeping in line with one of that issue’s concluding remarks:

    “The current help behaviour won't be changed. We don't know what is in the current buffer going on, so opening the help in a split window makes sense and has always been like this. ... But we won't be changing the existing help window behaviour.”

Incidental: in testing, using plugin/helpcurwin.vim and autoload/helpcurwin.vim works back to at least version 8.2.4922.

---

You can view, comment on, or merge this pull request online at:

  https://github.com/vim/vim/pull/18840

Commit Summary

• e61529f refactor/improve helpcurwin in Vim9 script and make it a standard plugin

File Changes

(7 files)

• A runtime/autoload/helpcurwin.vim (43)
• M runtime/doc/helphelp.txt (9)
• A runtime/doc/pi_helpcurwin.txt (65)
• M runtime/doc/tags (5)
• M runtime/doc/tips.txt (24)
• M runtime/plugin/README.txt (1)
• A runtime/plugin/helpcurwin.vim (21)

Patch Links:

• https://github.com/vim/vim/pull/18840.patch
• https://github.com/vim/vim/pull/18840.diff

—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.Message ID: <vim/vim/pull/18840@github.com>

[Christian Brabandt]

@chrisbra commented on this pull request.

---

In runtime/doc/pi_helpcurwin.txt:

> +			|help.txt| in read-only mode.  It leaves any other
+			windows as-is (including when there is another
+			help window(s)).
+
+:HelpCurwin {subject}	Like ":HelpCurwin" but, additionally open the
+			applicable help file at the tag {subject}.
+			For example: >
+
+			  :HelpCurwin version9.2
+<
+			It should otherwise behave like :help {subject}.
+
+You may also want to save typing with a command line abbreviation,
+for example: >vim9
+
+	cnoreabbrev hc HelpCurwin

Note, that this will expand hc in other contexts, this may not be desirable. Perhaps this is better:

cnoreabbrev <expr> hc getcmdtype() == ":" && getcmdline() == 'hc' ? 'HelpCurwin' : 'hc'

—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.Message ID: <vim/vim/pull/18840/review/3521173672@github.com>

[Christian Brabandt]

chrisbra left a comment (vim/vim#18840)

Thanks, I am not so happy with using this as a standard plugin and adding another command to Vim by default. I think it would be beneficial to make this an optional plugin, that could then even shadow the default :help command instead. What do you think?

—
Reply to this email directly, view it on GitHub.

You are receiving this because you are subscribed to this thread.Message ID: <vim/vim/pull/18840/c3592379649@github.com>

[Peter Kenny]

kennypete left a comment (vim/vim#18840)

Thanks, I am not so happy with using this as a standard plugin and adding another command to Vim by default. I think it would be beneficial to make this an optional plugin, that could then even shadow the default :help command instead. What do you think?

I thought there would be a variety of thoughts on that, originally looking at it making it optional in help/dist/opt, but then (as explained in the commit commentary) thought it would be more useful as an always available/standard command. Thing is, it feels more standard than some of the current standard plugins' commands? (Examples, GetLatestVimScripts and GetScripts from getscriptPlugin.vim and the Vimball commands in vimballPlugin.vim.) That said, especially if the latter day general expectation is not to add more commands, and appreciating my view doesn't carry as much weight as many others, making it an optional plugin works for me. It's not hard to rejig it, though would it be better as a fresh commit / reject this one?

I'm not sure about shadowing :help, though. Although after using :HelpCurwin a while (and finding it really useful in the right contexts - what drove me to reviewing it and then discovering the current legacy Vim script's deficiencies), I don't think it's a suitable general replacement for :help, if that's your meaning?

—
Reply to this email directly, view it on GitHub.

You are receiving this because you are subscribed to this thread.Message ID: <vim/vim/pull/18840/c3592932392@github.com>

[Christian Brabandt]

chrisbra left a comment (vim/vim#18840)

Yeah, understood. Those old plugins basically come from a time, where packs where not available yet and so they were made generally made available.

However, I don't really like the idea of polluting the runtime by default with additional plugin commands. It's only a very minor annoyance of mine, but it changes what e.g. a completion plugin would show, so I'd very much appreciate if we could make this optional, and in the help simply mention: If you don't like the current behavior of opening all the help windows in a new window, do :packadd HelpCurwin and then use the :HelpCurwin command instead, which will then try to open the help file in the current window (if possible)

I'm not sure about shadowing :help, though. Although after using :HelpCurwin a while (and finding it really useful in the right contexts - what drove me to reviewing it and then discovering the current legacy Vim script's deficiencies), I don't think it's a suitable general replacement for :help, if that's your meaning?

Thinking more about it, I think you are right and we shouldn't shadow it, as one may want to intentionally use either behaviour and so we should allow the user to specify what they want.

—
Reply to this email directly, view it on GitHub.

You are receiving this because you are subscribed to this thread.Message ID: <vim/vim/pull/18840/c3592975789@github.com>

[Peter Kenny]

kennypete left a comment (vim/vim#18840)

Yeah, understood. Those old plugins basically come from a time, where packs where not available yet and so they were made generally made available.

However, I don't really like the idea of polluting the runtime by default with additional plugin commands...

Understood, and pack/dist/opt makes sense too. Would you prefer a fresh PR/commit, or just change the PR title and do a second commit to this PR?

—
Reply to this email directly, view it on GitHub.

You are receiving this because you are subscribed to this thread.Message ID: <vim/vim/pull/18840/c3593051114@github.com>

[Peter Kenny]

@kennypete commented on this pull request.

---

In runtime/doc/pi_helpcurwin.txt:

> +			|help.txt| in read-only mode.  It leaves any other
+			windows as-is (including when there is another
+			help window(s)).
+
+:HelpCurwin {subject}	Like ":HelpCurwin" but, additionally open the
+			applicable help file at the tag {subject}.
+			For example: >
+
+			  :HelpCurwin version9.2
+<
+			It should otherwise behave like :help {subject}.
+
+You may also want to save typing with a command line abbreviation,
+for example: >vim9
+
+	cnoreabbrev hc HelpCurwin

Much better, yes. It'll be there in the next commit.

—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.Message ID: <vim/vim/pull/18840/review/3522011277@github.com>

[Christian Brabandt]

chrisbra left a comment (vim/vim#18840)

you can amend this PR and I'll squash into a single commit later on.

—
Reply to this email directly, view it on GitHub.

You are receiving this because you are subscribed to this thread.Message ID: <vim/vim/pull/18840/c3593121367@github.com>

[Peter Kenny]

@kennypete pushed 2 commits.

• 4465ef0 refactor/improve helpcurwin in Vim9 script and make it a standard plugin
• 4fef4fe pack/dist/opt/helpcurwin - not a standard plugin

—
View it on GitHub or unsubscribe.
You are receiving this because you are subscribed to this thread.Message ID: <vim/vim/pull/18840/before/e61529fdf60f49853fee318fc067082338379f2c/after/4fef4fece089dfc224e9f359d719043c6e44adbd@github.com>

[Peter Kenny]

kennypete left a comment (vim/vim#18840)

you can amend this PR and I'll squash into a single commit later on.

Okay, I think that it's all updated to be a pack/dist/opt package correctly now.

—
Reply to this email directly, view it on GitHub.

You are receiving this because you are subscribed to this thread.Message ID: <vim/vim/pull/18840/c3598875609@github.com>

[Christian Brabandt]

chrisbra left a comment (vim/vim#18840)

thanks

—
Reply to this email directly, view it on GitHub.

You are receiving this because you are subscribed to this thread.Message ID: <vim/vim/pull/18840/c3603752422@github.com>

[Christian Brabandt]

chrisbra left a comment (vim/vim#18840)

Okay, I slightly updated the documentation in tips.txt, added a simple test and added the plugin to the Filelist. Let me know if you see any issue with this.

—
Reply to this email directly, view it on GitHub.

You are receiving this because you are subscribed to this thread.Message ID: <vim/vim/pull/18840/c3603901446@github.com>

[Christian Brabandt]

Closed #18840 via c0f2d2f.

—
Reply to this email directly, view it on GitHub.

You are receiving this because you are subscribed to this thread.Message ID: <vim/vim/pull/18840/issue_event/21316485250@github.com>