aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorTom Ryder <tom@sanctum.geek.nz>2019-06-23 01:16:26 +1200
committerTom Ryder <tom@sanctum.geek.nz>2019-06-23 01:24:14 +1200
commit114c41dc69884f496c478baf956a75d794de39e7 (patch)
tree108fc55a60b1cc3deafec5d798554f76aa3117df
parentFlesh out comment a little (diff)
downloadvim-paste-insert-114c41dc69884f496c478baf956a75d794de39e7.tar.gz
vim-paste-insert-114c41dc69884f496c478baf956a75d794de39e7.zip
Flesh out documentation a lot
-rw-r--r--doc/paste_insert.txt48
1 files changed, 33 insertions, 15 deletions
diff --git a/doc/paste_insert.txt b/doc/paste_insert.txt
index 62fa1f8..d9b2bb2 100644
--- a/doc/paste_insert.txt
+++ b/doc/paste_insert.txt
@@ -1,4 +1,4 @@
-*paste_insert.txt* For Vim version 7.0 Last change: 2019 Jun 19
+*paste_insert.txt* For Vim version 7.0 Last change: 2019 Jun 23
DESCRIPTION *paste_insert*
@@ -8,36 +8,54 @@ 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 a key in normal mode, by default CTRL-C.
+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.
-
-MAPPINGS *paste_insert-mappings*
-
- *<Plug>(PasteInsert)*
-The `<Plug>(PasteInsert)` map in normal mode just does `:PasteInsert`.
+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. This defaults to `['<C-C>',
-'<Esc>']`, for CTRL-C and Escape.
+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 back
-afterwards. This works well in versions of Vim 7.3.032 or newer, but before
-that patch, recursive maps and flags like <expr> or <silent> are broken,
-although <buffer> should still work. Either pick keys that you don't map, or
-even better--upgrade your Vim!
+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*