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 <github.com@k1w1.cyou>
Signed-off-by: Christian Brabandt <cb@256bit.org>

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 \

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:

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*

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
+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
 
-	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
+    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:

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

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:

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*

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

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 \

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

src/version.c

@@ -729,6 +729,8 @@ static char *(features[]) =
 
 static int included_patches[] =
 {   /* Add new patch number below this line */
+/**/
+    1946,
 /**/
     1945,
 /**/