Merge #4448 'paste: redesign'

fix #3447
fix #3566
fix #7066
fix #7212
fix #7273
fix #7455
fix #10415

NA vim-patches:
vim-patch:8.1.1198
vim-patch:8.1.0224
vim-patch:8.0.1299
vim-patch:8.0.0569
vim-patch:8.0.0303
vim-patch:8.0.0296
vim-patch:8.0.0244
vim-patch:8.0.0238
vim-patch:8.0.0232
vim-patch:8.0.0231
vim-patch:8.0.0230
vim-patch:8.0.0210

1 files changed, 35 insertions, 0 deletions

diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt
index dc045c360a..833be8a103 100644
--- a/runtime/doc/provider.txt
+++ b/runtime/doc/provider.txt
@@ -219,6 +219,41 @@ function returns the clipboard as a `[lines, regtype]` list, where `lines` is
 a list of lines and `regtype` is a register type conforming to |setreg()|.
 
 ==============================================================================
+Paste 							*provider-paste* *paste*
+
+"Paste" is a separate concept from |clipboard|: paste means "dump a bunch of
+text to the editor", whereas clipboard provides features like |quote-+| to get
+and set the OS clipboard directly.  For example, middle-click or CTRL-SHIFT-v
+(macOS: CMD-v) in your terminal is "paste", not "clipboard": the terminal
+application (Nvim) just gets a stream of text, it does not interact with the
+clipboard directly.
+
+							*bracketed-paste-mode*
+Pasting in the |TUI| depends on the "bracketed paste" terminal capability,
+which allows terminal applications to distinguish between user input and
+pasted text.  https://cirw.in/blog/bracketed-paste
+This works automatically if your terminal supports it.
+
+							*ui-paste*
+GUIs can paste by calling |nvim_paste()|.
+
+PASTE BEHAVIOR ~
+
+Paste always inserts text after the cursor.  In cmdline-mode only the first
+line is pasted, to avoid accidentally executing many commands.  Use the
+|cmdline-window| if you really want to paste multiple lines to the cmdline.
+
+When pasting a huge amount of text, screen updates are throttled and the
+message area shows a "..." pulse.
+
+You can implement a custom paste handler by redefining |vim.paste()|.
+Example: >
+
+  vim.paste = (function(lines, phase)
+    vim.api.nvim_put(lines, 'c', true, true)
+  end)
+
+==============================================================================
 X11 selection mechanism			      *clipboard-x11* *x11-selection*
 
 X11 clipboard providers store text in "selections". Selections are owned by an