diff --git a/Filelist b/Filelist index 9ab71cb892..4441d4cb4f 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 eb90fe9f13..c014e558c1 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 520369610f..441d8b4138 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 cd3b5d0529..8a0da14375 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() - 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: 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 0000000000..52a2d4f7cf --- /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 +# 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 0000000000..2bca8d0341 --- /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. 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 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. 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 +HelpCurwin; to keys of your choosing to enable that. For example: >vim9 + + nnoremap hc HelpCurwin; + +Once sourced (in this instance, when hc is typed), the applicable +help file will be opened in the current window at the tag for (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 0000000000..c552ad5fac --- /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 0000000000..97631d348f --- /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 +# 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() + +nnoremap HelpCurwin; helpcurwin.Open(expand('')) + +# vim: ts=8 sts=2 sw=2 et diff --git a/src/testdir/Make_all.mak b/src/testdir/Make_all.mak index a587034c81..97ad9089a8 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 0000000000..c2b4f79547 --- /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 9daa59bfd7..916bc21744 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, /**/