aboutsummaryrefslogtreecommitdiff
path: root/doc/paste_insert.txt
blob: 35f1189b725e43973cdab7fce901a5c895e321dd (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
*paste_insert.txt*	For Vim version 7.0	Last change: 2019 Jul 11

DESCRIPTION				*paste_insert*

This plugin implements a method for setting paste mode with the 'paste' option
for only the duration of the next insert operation or normal mode change, to
avoid the hassle of forgetting to unset the option after inserting.

It includes a timeout if the text isn't changed and insert mode isn't entered
within 'updatetime' seconds, or if the user navigates away from the buffer or
window.  It can also be cancelled in normal mode with CTRL-C or Escape.  These
keys can be changed if they are already mapped or otherwise unsuitable.

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 complain on starting a paste operation if either of the keys
are already mapped, globally or locally, so pick keys you never remap, or set
this option to a blank |List| `[]` to disable it.

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!

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: