Doc: add bracketed-paste-mode #3028

Reviewed-by: Felipe Morales <hel.sheep@gmail.com>
Reviewed-by: Justin M. Keyes <justinkz@gmail.com>
Reviewed-by: Michael Reed <Pyrohh@users.noreply.github.com>

runtime/doc/options.txt

@@ -4729,6 +4729,8 @@ A jump table for the options with a short description can be found at |Q_op|.
 						*'paste'* *'nopaste'*
 'paste'			boolean	(default off)
 			global
+	You probably don't have to set this option: |bracketed-paste-mode|.
+
 	Put Vim in Paste mode.  This is useful if you want to cut or copy
 	some text from one window and paste it in Vim.  This will avoid
 	unexpected effects.

runtime/doc/term.txt

@@ -592,6 +592,19 @@ before using the mouse:
 	"g<LeftMouse>"	is "<C-LeftMouse>	(jump to tag under mouse click)
 	"g<RightMouse>" is "<C-RightMouse>	("CTRL-T")
 
+							*bracketed-paste-mode*
+Bracketed paste mode allows terminal emulators to distinguish between typed
+text and pasted text.
+
+For terminal emulators that support it, this mode is enabled by default. Thus
+you can paste text without Neovim giving any special meaning to it. Most
+notably it won't try reindenting those lines.
+
+If your terminal emulator doesn't support it yet, you can get the old Vim
+behaviour by enabling |'paste'| temporarily.
+
+NOTE: See https://cirw.in/blog/bracketed-paste for technical details.
+
 					*mouse-mode-table* *mouse-overview*
 A short overview of what the mouse buttons do, when 'mousemodel' is "extend":
 

runtime/doc/vim_diff.txt

@@ -69,6 +69,8 @@ are always available and may be used simultaneously in separate plugins.  The
 
 See |nvim-intro| for a list of Nvim's largest new features.
 
+|bracketed-paste-mode| is built-in and enabled by default.
+
 Meta (alt) chords are recognized (even in the terminal).
   <M-1>, <M-2>, ...
   <M-BS>, <M-Del>, <M-Ins>, ...