Asked: Setting the filetype
The autocommands in the question are a good start, and with 2 extra pieces of
knowledge we can finish it:
You can define autocommands everywhere. autocmd
and augroup
are "just"
regular Vim commands, not special syntax or keywords. So defining an autocmd
from within an autocmd is perfectly fine.
You can define autocommands to be buffer-local (see: :help autocmd-buffer-local
).
Armed with this information, the solution is fairly easy:
augroup help_start
autocmd!
autocmd FileType help call SetHelpFiletype()
augroup end
fun! SetHelpFiletype()
augroup help_insert
autocmd!
autocmd InsertEnter <buffer> setlocal filetype=txt
autocmd InsertLeave <buffer> setlocal filetype=help
augroup end
endfun
I used a function here since nesting multiple augroup
s inline does seem to be
problematic (the first augroup end
seems to end both groups; you can opt to
not use an augroup
for the inner autocmd
s, but this can lead to them being
executed multiple times after reloading the vimrc file).
You will need a modeline which sets the filetype
. It's pretty much standard to
add a modeline to the end of Vim help files, so this is probably already
present:
vim:tw=78:ts=8:ft=help:norl
Better: configuring concealed characters
There is another (probably better) way to solve this problem: by showing the
concealed characters in insert mode.
The ftplugin for help files does:
setlocal conceallevel=2 concealcursor=nc
conceallevel=2
tells Vim to actual conceal characters which are marked as
such, but concealcursor=nc
tells Vim to conceal the characters only in
normal and cmdline mode.
However, this still confusing:
The characters don't show up very clearly as they are still hidden due to the
syntax highlighting:
:highlight helpBar
helpBar xxx links to Ignore
:highlight Ignore
Ignore xxx ctermfg=15 guifg=bg
15
is white
, which is my terminal's background colour (this always
matches your terminal's background colour).
Only the characters for the current line show up. This can be considered both
a feature and a bug, but I don't like it.
We can fix this with:
Use :highlight clear Ignore
. This will clear the syntax highlighting for
the Ignore
group.
Tell Vim to set conceallevel
to 0
(always show all concealed characters)
when entering insert mode.
Putting this together, we end up with:
augroup help_start
autocmd!
autocmd FileType help call SetHelpFiletype()
augroup end
fun! SetHelpFiletype()
augroup help_insert
autocmd!
autocmd InsertEnter <buffer> setlocal conceallevel=0 | highlight clear Ignore
autocmd InsertLeave <buffer> setlocal conceallevel=2
augroup end
endfun
This will show the formatting characters, and still shows the syntax
highlighting in insert mode. In normal mode, it will show the help file as the
user sees it when reading it.
This method is also also a bit faster than setting the filetype since Vim
doesn't have to source a bunch of filetype/syntax files.
Preview split
(With thanks to @PeterRincker's comment).
conceallevel
is a window local setting. This means you can easily use splits. One for editing with set conceallevel=0
and the other window with the default set conceallevel=2
.
This is especially useful in combination with How can I get both splits to scroll left or right at the same time?.
You can create a command to show a "preview split" like so:
command! HelpPreview setlocal scrollbind | split | setlocal conceallevel=0 | highlight clear Ignore