diff --git a/runtime/doc/helphelp.txt b/runtime/doc/helphelp.txt index eb90fe9f13daa1..c014e558c115f8 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 520369610f3b0d..441d8b4138d338 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 cd3b5d0529c972..ad9a58160a981d 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 @@ -544,28 +544,20 @@ 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 - - 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 +want to display help in the current window. If so, you can use the optional +helpcurwin plugin. Load the plugin 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, and +- The help file, |helpcurwin.txt|, will be available. It has further details + about using the plugin and its features. + 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 00000000000000..52a2d4f7cf17d2 --- /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 00000000000000..2bca8d0341fcc2 --- /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 00000000000000..c552ad5fac6928 --- /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 00000000000000..97631d348fd421 --- /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