*paste_insert.txt*	For Vim version 7.0	Last change: 2019 Jun 23

DESCRIPTION				*paste_insert*

This small plugin provides a simple "one shot paste" method, with a command or
mapping to prefix opening an insert, with the 'paste' option automatically set
after the insert ends, to avoid the annoyances caused by forgetting to do so.

It includes a timeout if insert mode isn't entered within 'updatetime'
seconds, or if the user navigates away from the buffer or window.  It can also
be cancelled with keys in normal mode, by default CTRL-C or Escape.

REQUIREMENTS				*paste_insert-requirements*

This plugin only loads if 'compatible' is not set.

MAPPINGS				*paste_insert-mappings*

					*<Plug>(PasteInsert)*
The `<Plug>(PasteInsert)` map in normal mode just does `:PasteInsert`.  This
is probably the way you want to use this plugin.  To use `<Leader>p`, for
example, you might do this in your |vimrc|:
>
	nmap <Leader>p <Plug>(PasteInsert)
<
COMMANDS				*paste_insert-commands*

					*:PasteInsert*
Enter the `:PasteInsert` command just before entering insert mode to set up
the relevant hooks.  It takes neither range prefix nor arguments.  It's made
available for you if you want it, but most users probably just want the
|<Plug>(PasteInsert)| mapping above.

OPTIONS					*paste_insert-options*

					*g:paste_insert_cancel*
Set `g:paste_insert_cancel` to a |List| of the special codes for keys you want
to cancel the pending paste in normal mode. `['<C-C>', '<Esc>']` is the
default, for CTRL-C and Escape.

The plugin will overwrite any existing normal mode maps for these keys during
the normal mode phase of the operation, but will try to restore them
afterwards.  If you don't want your mappings touched at all, set this to the
empty list, and the plugin will leave them alone.

CAVEATS					*paste_insert-caveats*

By design (Vim's), mappings don't work in paste mode.  If you break the insert
with CTRL-C, the |InsertLeave| event doesn't fire, and you'll still be in
'paste' mode, just as you would be without this plugin.  Leaving the buffer or
window should fix it.  Friends don't let friends use CTRL-C to break insert
mode!

The map restoration for your chosen cancel keys works well in Vim v7.3.032 or
newer, but before that patch, recursive maps and flags like <expr> or <silent>
won't be restored correctly, although <buffer> should still work.  If it's
mangling your mappings and you don't want to change keys, your only option is
to upgrade Vim.

AUTHOR					*paste_insert-author*

Written and maintained by Tom Ryder <tom@sanctum.geek.nz>.

LICENSE					*paste_insert-license*

Licensed for distribution under the same terms as Vim itself (see |license|).

 vim:tw=78:ts=8:ft=help:norl: