feat(clipboard): add OSC 52 clipboard support

This is opt-in as not all terminal emulators support OSC 52, so it is up
to the user to enable it explicitly.

2 files changed, 32 insertions, 1 deletions

diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index fa77e8d086..985adb5b0d 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -208,6 +208,9 @@ The following new APIs and features were added.
 • The |TermResponse| autocommand event can be used with |v:termresponse| to
   read escape sequence responses from the terminal.
 
+• A clipboard provider which uses OSC 52 to copy the selection to the system
+  clipboard is now bundled by default. |clipboard-osc52|
+
 ==============================================================================
 CHANGED FEATURES                                                 *news-changed*
 
diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt
index 9e70ff8945..1b49ee3a3d 100644
--- a/runtime/doc/provider.txt
+++ b/runtime/doc/provider.txt
@@ -253,7 +253,35 @@ For Windows WSL, try this g:clipboard definition:
                 \   },
                 \   'cache_enabled': 0,
                 \ }
-
+<
+							    *clipboard-osc52*
+Nvim bundles a clipboard provider that allows copying to the system clipboard
+using OSC 52. OSC 52 is an Operating System Command control sequence that
+writes the copied text to the terminal emulator. If the terminal emulator
+supports OSC 52 then it will write the copied text into the system clipboard.
+
+This is most useful when using Nvim remotely (e.g. via ssh) as Nvim does not
+have direct access to the system clipboard in that case.
+
+Because not all terminal emulators support OSC 52, this provider must be opted
+into explicitly by setting the following |g:clipboard| definition: >lua
+
+    vim.g.clipboard = {
+      name = 'OSC 52',
+      copy = {
+        ['+'] = require('vim.clipboard.osc52').copy,
+        ['*'] = require('vim.clipboard.osc52').copy,
+      },
+      paste = {
+        ['+'] = require('vim.clipboard.osc52').paste,
+        ['*'] = require('vim.clipboard.osc52').paste,
+      },
+    }
+<
+Note that not all terminal emulators support reading from the system clipboard
+(and even for those that do, users should be aware of the security
+implications), so using OSC 52 for pasting may not be possible.
+<
 ==============================================================================
 Paste							*provider-paste* *paste*