Commit: patch 9.1.1946: Cannot open the help in the current window

[Christian Brabandt]

patch 9.1.1946: Cannot open the help in the current window

Commit: https://github.com/vim/vim/commit/c0f2d2f14076c32451edb9622da15d54f4abae73
Author: Peter Kenny <githu...@k1w1.cyou>
Date: Tue Dec 2 20:42:53 2025 +0000

patch 9.1.1946: Cannot open the help in the current window

Problem: Cannot open the help in the current window
Solution: Promote the example from tips.txt to a proper package and
include the helpcurwin package, add tests for it
(Peter Kenny)

closes: #18840

Signed-off-by: Peter Kenny <githu...@k1w1.cyou>
Signed-off-by: Christian Brabandt <c...@256bit.org>

diff --git a/Filelist b/Filelist
index 9ab71cb89..4441d4cb4 100644
--- a/Filelist
+++ b/Filelist
@@ -829,6 +829,10 @@ RT_ALL = \
runtime/pack/dist/opt/editorconfig/doc/editorconfig.txt \
runtime/pack/dist/opt/editorconfig/ftdetect/editorconfig.vim \
runtime/pack/dist/opt/editorconfig/plugin/editorconfig.vim \
+ runtime/pack/dist/opt/helpcurwin/autoload/helpcurwin.vim \
+ runtime/pack/dist/opt/helpcurwin/doc/helpcurwin.txt \
+ runtime/pack/dist/opt/helpcurwin/doc/tags \
+ runtime/pack/dist/opt/helpcurwin/plugin/helpcurwin.vim \
runtime/pack/dist/opt/helptoc/autoload/helptoc.vim \
runtime/pack/dist/opt/helptoc/doc/helptoc.txt \
runtime/pack/dist/opt/helptoc/doc/tags \
diff --git a/runtime/doc/helphelp.txt b/runtime/doc/helphelp.txt
index eb90fe9f1..c014e558c 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 Nov 09
+*helphelp.txt* For Vim version 9.1. Last change: 2025 Dec 02


VIM REFERENCE MANUAL by Bram Moolenaar
@@ -158,11 +158,12 @@ When no argument is given to |:help| the file given with the 'helpfile' option
will be opened. Otherwise the specified tag is searched for in all "doc/tags"
files in the directories specified in the 'runtimepath' option.

-If you would like to open the help in the current window, see this tip:
-|help-curwin|.
-
The initial height of the help window can be set with the 'helpheight' option
(default 20).
+
+If you want to open help on {subject} in the current window, the helpcurwin
+optional package can be used. See |package-helpcurwin|.
+
*help-buffer-options*
When the help buffer is created, several local options are set to make sure
the help text is displayed as it was intended:
diff --git a/runtime/doc/tags b/runtime/doc/tags
index 520369610..441d8b413 100644
--- a/runtime/doc/tags
+++ b/runtime/doc/tags
@@ -8309,7 +8309,6 @@ help helphelp.txt /*help*
help-TOC helphelp.txt /*help-TOC*
help-buffer-options helphelp.txt /*help-buffer-options*
help-context help.txt /*help-context*
-help-curwin tips.txt /*help-curwin*
help-notation helphelp.txt /*help-notation*
help-summary usr_02.txt /*help-summary*
help-tags tags 1
@@ -9622,6 +9621,7 @@ package-create repeat.txt /*package-create*
package-doc repeat.txt /*package-doc*
package-documentation repeat.txt /*package-documentation*
package-editorconfig usr_05.txt /*package-editorconfig*
+package-helpcurwin tips.txt /*package-helpcurwin*
package-helptoc helphelp.txt /*package-helptoc*
package-hlyank usr_05.txt /*package-hlyank*
package-justify usr_25.txt /*package-justify*
diff --git a/runtime/doc/tips.txt b/runtime/doc/tips.txt
index cd3b5d052..8a0da1437 100644
--- a/runtime/doc/tips.txt
+++ b/runtime/doc/tips.txt
@@ -1,4 +1,4 @@
-*tips.txt* For Vim version 9.1. Last change: 2025 Nov 09
+*tips.txt* For Vim version 9.1. Last change: 2025 Dec 02


VIM REFERENCE MANUAL by Bram Moolenaar
@@ -30,7 +30,7 @@ Executing shell commands in a window |shell-window|
Hex editing |hex-editing|
Using <> notation in autocommands |autocmd-<>|
Highlighting matching parens |match-parens|
-Opening help in the current window |help-curwin|
+Opening help in the current window |package-helpcurwin|

==============================================================================
Editing C programs *C-editing*
@@ -544,28 +544,22 @@ A slightly more advanced version is used in the |matchparen| plugin.
<

==============================================================================
-Opening help in the current window *help-curwin*
+Opening help in the current window *package-helpcurwin*

-By default, help is displayed in a split window. If you prefer it opens in
-the current window, try this custom `:HelpCurwin` command:
->
- command -bar -nargs=? -complete=help HelpCurwin execute s:HelpCurwin(<q-args>)
- let s:did_open_help = v:false
-
- function s:HelpCurwin(subject) abort
- let mods = 'silent noautocmd keepalt'
- if !s:did_open_help
- execute mods .. ' help'
- execute mods .. ' helpclose'
- let s:did_open_help = v:true
- endif
- if !getcompletion(a:subject, 'help')->empty()
- execute mods .. ' edit ' .. &helpfile
- set buftype=help
- endif
- return 'help ' .. a:subject
- endfunction
-<
+By default, help is displayed in a split window. In some scenarios, you may
+prefer to open the help in the current window. The optional helpcurwin
+package makes this possible. Load the package manually, or in your |vimrc|,
+with: >vim

+ packadd helpcurwin
+<
+After it has loaded:
+- The command `:HelpCurwin` {subject} can be used to open help in the current
+ window.
+- If the current window contains a modified buffer, the plugin asks for
+ confirmation before replacing it. If confirmed, the buffer becomes
+ hidden |hidden-buffer|.
+- The help file, |helpcurwin.txt|, will be available and describes the plugin
+ in more details.

vim:tw=78:ts=8:noet:ft=help:norl:
diff --git a/runtime/pack/dist/opt/helpcurwin/autoload/helpcurwin.vim b/runtime/pack/dist/opt/helpcurwin/autoload/helpcurwin.vim
new file mode 100644
index 000000000..52a2d4f7c
--- /dev/null
+++ b/runtime/pack/dist/opt/helpcurwin/autoload/helpcurwin.vim
@@ -0,0 +1,42 @@
+vim9script
+
+# Open Vim help on {subject} in the current window (rather than a new split)
+#
+# Maintainer: The Vim Project <https://github.com/vim/vim>
+# Last change: 2025 Dec 02
+
+export def Open(subject: string): void
+
+ const HELPCURWIN: func = (): string => {
+ if !getcompletion(subject, 'help')->empty() || subject->empty()
+ if &buftype != 'help'
+ execute 'silent noautocmd keepalt enew'
+ setlocal buftype=help noswapfile
+ endif
+ endif
+ return $'help {subject}'
+ }
+
+ var contmod: bool = true
+ if &modified
+ echohl MoreMsg
+ echo $'Buffer {bufname()} is modified - continue? (y/n)'
+ echohl None
+ contmod = (getcharstr() == 'y')
+ endif
+ if contmod
+ try
+ execute HELPCURWIN()
+ catch
+ echohl Error
+ # {subject} invalid - Echo 'helpcurwin: E149:' (omit 'Vim(help):')
+ echo $'helpcurwin: {v:exception->substitute("^[^:]\+:", "", "")}'
+ echohl None
+ endtry
+ else
+ echo $'Aborted opening in current window, :help {subject}'
+ endif
+
+enddef
+
+# vim: ts=8 sts=2 sw=2 et
diff --git a/runtime/pack/dist/opt/helpcurwin/doc/helpcurwin.txt b/runtime/pack/dist/opt/helpcurwin/doc/helpcurwin.txt
new file mode 100644
index 000000000..2bca8d034
--- /dev/null
+++ b/runtime/pack/dist/opt/helpcurwin/doc/helpcurwin.txt
@@ -0,0 +1,59 @@
+*helpcurwin.txt* For Vim version 9.1. Last change: 2025 Dec 02
+
+The helpcurwin optional package enables opening help in the current window.
+
+1. :HelpCurwin |helpcurwin-command|
+2. helpcurwin#Open() |helpcurwin-function|
+3. <Plug>HelpCurwin; |helpcurwin-mapping|
+
+
+==============================================================================
+1. :HelpCurwin *:HelpCurwin* *helpcurwin-command*
+
+:HelpCurwin Use the current window to display the help file,
+ |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: >vi
+
+ cnoreabbrev <expr> hc getcmdtype() == ":" &&
+ \ getcmdline() == 'hc' ? 'HelpCurwin' : 'hc'
+<
+
+==============================================================================
+2. helpcurwin#Open() *helpcurwin-function*
+
+The underlying `:def` function may also be used, for example: >vim
+
+ :vim9cmd helpcurwin#Open('version9.2')
+<
+This may be useful from other scripts where you want to bring up help on
+{subject} in the current window.
+
+
+==============================================================================
+3. <Plug>HelpCurwin; *helpcurwin-mapping*
+
+There may be times when you want to get the help for a WORD, such as when it
+is in a Vim9 script. If you want to open it in the same window, you can map
+<Plug>HelpCurwin; to keys of your choosing to enable that. For example: >vim9
+
+ nnoremap <Leader>hc <Plug>HelpCurwin;
+
+Once sourced (in this instance, when <Leader>hc is typed), the applicable
+help file will be opened in the current window at the tag for <cWORD> (that
+is, the |WORD| under the cursor), if it exists.
+
+
+==============================================================================
+ vim:tw=78:ts=8:noet:ft=help:norl:
diff --git a/runtime/pack/dist/opt/helpcurwin/doc/tags b/runtime/pack/dist/opt/helpcurwin/doc/tags
new file mode 100644
index 000000000..c552ad5fa
--- /dev/null
+++ b/runtime/pack/dist/opt/helpcurwin/doc/tags
@@ -0,0 +1,5 @@
+:HelpCurwin helpcurwin.txt /*:HelpCurwin*
+helpcurwin-command helpcurwin.txt /*helpcurwin-command*
+helpcurwin-function helpcurwin.txt /*helpcurwin-function*
+helpcurwin-mapping helpcurwin.txt /*helpcurwin-mapping*
+helpcurwin.txt helpcurwin.txt /*helpcurwin.txt*
diff --git a/runtime/pack/dist/opt/helpcurwin/plugin/helpcurwin.vim b/runtime/pack/dist/opt/helpcurwin/plugin/helpcurwin.vim
new file mode 100644
index 000000000..97631d348
--- /dev/null
+++ b/runtime/pack/dist/opt/helpcurwin/plugin/helpcurwin.vim
@@ -0,0 +1,20 @@
+vim9script
+
+# Open Vim help on {subject} in the current window (rather than a new split)
+#
+# Maintainer: The Vim Project <https://github.com/vim/vim>
+# Last change: 2025 Dec 02
+
+# Exit when the helpcurwin plugin is loaded already
+if exists('g:loaded_helpcurwin')
+ finish
+endif
+g:loaded_helpcurwin = true
+
+import autoload 'helpcurwin.vim'
+
+command -bar -nargs=? -complete=help HelpCurwin helpcurwin.Open(<q-args>)
+
+nnoremap <Plug>HelpCurwin; <ScriptCmd>helpcurwin.Open(expand('<cWORD>'))<CR>
+
+# vim: ts=8 sts=2 sw=2 et
diff --git a/src/testdir/Make_all.mak b/src/testdir/Make_all.mak
index a587034c8..97ad9089a 100644
--- a/src/testdir/Make_all.mak
+++ b/src/testdir/Make_all.mak
@@ -244,6 +244,7 @@ NEW_TESTS = \
test_perl \
test_plugin_comment \
test_plugin_glvs \
+ test_plugin_helpcurwin \
test_plugin_helptoc \
test_plugin_man \
test_plugin_matchparen \
@@ -518,6 +519,7 @@ NEW_TESTS_RES = \
test_perl.res \
test_plugin_comment.res \
test_plugin_glvs.res \
+ test_plugin_helpcurwin.res \
test_plugin_helptoc.res \
test_plugin_man.res \
test_plugin_matchparen.res \
diff --git a/src/testdir/test_plugin_helpcurwin.vim b/src/testdir/test_plugin_helpcurwin.vim
new file mode 100644
index 000000000..c2b4f7954
--- /dev/null
+++ b/src/testdir/test_plugin_helpcurwin.vim
@@ -0,0 +1,13 @@
+" Test for the HelpCurwin package
+
+func Test_helpcurwin_1()
+ packadd helpcurwin
+ call assert_equal(2, exists(':HelpCurwin'))
+ new Xfoobar.txt
+ only
+ HelpCurwin tips.txt
+ call assert_match('.*tips.txt', bufname('%'))
+ call assert_equal(1, winnr('$'))
+ call assert_true(bufexists('Xfoobar.txt'))
+ %bw
+endfunc
diff --git a/src/version.c b/src/version.c
index 9daa59bfd..916bc2174 100644
--- a/src/version.c
+++ b/src/version.c
@@ -729,6 +729,8 @@ static char *(features[]) =

static int included_patches[] =
{ /* Add new patch number below this line */
+/**/
+ 1946,
/**/
1945,
/**/