diff options
author | Tom Ryder <tom@sanctum.geek.nz> | 2019-06-23 01:16:26 +1200 |
---|---|---|
committer | Tom Ryder <tom@sanctum.geek.nz> | 2019-06-23 01:24:14 +1200 |
commit | 114c41dc69884f496c478baf956a75d794de39e7 (patch) | |
tree | 108fc55a60b1cc3deafec5d798554f76aa3117df /doc | |
parent | Flesh out comment a little (diff) | |
download | vim-paste-insert-114c41dc69884f496c478baf956a75d794de39e7.tar.gz vim-paste-insert-114c41dc69884f496c478baf956a75d794de39e7.zip |
Flesh out documentation a lot
Diffstat (limited to 'doc')
-rw-r--r-- | doc/paste_insert.txt | 48 |
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* |