Open help windows in new buffer instead of split windows

Question

Some time ago I found an interesting trick on Damian Conway's vimrc which allows to open help files in new tabs instead of split windows. The code is the following:

"Only apply to .txt files...
augroup HelpInTabs
    autocmd!
    autocmd BufEnter  *.txt   call HelpInNewTab()
augroup END

"Only apply to help files...
function! HelpInNewTab ()
    if &buftype == 'help' && g:help_in_tabs
        "Convert the help window to a tab...
        execute "normal \<C-W>T"
    endif
endfunction

Of course this piece of code works well but I'd like to improve it: I feel that opening the help file into a new tab isn't that convenient and I rather open it into a new buffer and give the focus on this buffer.

So I'm looking for a command which would replace this line:

execute "normal \<C-W>T"

and more precisely <C-W>T to turn the window into a new buffer instead of a new tab.

Unfortunately, I could find anything which could help me in the documentation. So is it possible? And if it is, how can I do it?

Answer 1

We can open help in the current window by set buftype=help and then using the :help command.

We have the following problems:

• restore the 'buftype' value of the previous buffer, #, in the success case
• restore the 'buftype' value of the current buffer, %, in the error case
• let the :h error message through correctly

The :h command like so many of Vim's command will set v:errmsg when an error messages occurs. This means we can detect the error message. However this will give a "stack trace" when used inside of a function. We can overcome this by suppressing the error via :silent!. Now we can check v:errmsg and restore 'buftype' correctly.

Since you still want to keep the error message we will use :execute in the :command definition and have the function return the failed help command.

Below is the resulting code (Put this in your vimrc file):

function! s:help(subject)
  let buftype = &buftype
  let &buftype = 'help'
  let v:errmsg = ''
  let cmd = "help " . a:subject
  silent! execute  cmd
  if v:errmsg != ''
    let &buftype = buftype
    return cmd
  else
    call setbufvar('#', '&buftype', buftype)
  endif
endfunction
command! -nargs=? -bar -complete=help H execute <SID>help(<q-args>)

This creates the :H command which behave just like :h except open in the same window.

Thoughts

• You may want to look into something like cmdallias.vim to make this command easier to type
• Maybe instead of all this trouble just promote the help window to its own tab via <c-w>T (my preference)
• the technique will need to be adjusted to take into consideration if there is a different a window with buftype=help already open

More help

:h 'buftype'
:h :h
:h :silent
:h v:errmsg
:h :exe

Answer 2

The Vim 9.0 tips.txt help file contains a section on this topic. See:

:help help-curwin