From: Foxe Chen <chen.foxe@gmail.com>
Date: Thu, 18 Dec 2025 20:55:25 +0000 (+0100)
Subject: runtime(osc52): Update documentation, send DA1 query when loading package
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=5fb29bb7e77ead7b9bb0eea6e9e86be774b64397;p=thirdparty%2Fvim.git

runtime(osc52): Update documentation, send DA1 query when loading package

closes: #18944

Signed-off-by: Foxe Chen <chen.foxe@gmail.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>
---

diff --git a/runtime/pack/dist/opt/osc52/doc/osc52.txt b/runtime/pack/dist/opt/osc52/doc/osc52.txt
index 2d98299b9d..97a63289ce 100644
--- a/runtime/pack/dist/opt/osc52/doc/osc52.txt
+++ b/runtime/pack/dist/opt/osc52/doc/osc52.txt
@@ -1,4 +1,4 @@
-*osc52.txt*   For Vim version 9.1.  Last change:  2025 Dec 15
+*osc52.txt*   For Vim version 9.1.  Last change:  2025 Dec 18
 
 
 			  VIM REFERENCE MANUAL
@@ -32,27 +32,33 @@ then it is up to the terminal to handle what selection to use.
 
 2. HOW TO USE THE PLUGIN                                *osc52-how-to-use*
 
-The osc52.vim plugin relies on Vim's clipboard provider functionality, see
-|clipboard-providers|.  In short, add these commands to your vimrc to get
-everything working: >vim
+The osc52.vim package relies on Vim's clipboard provider functionality, see
+|clipboard-providers|.  To enable it, add the following to your |vimrc|: >vim
         packadd osc52
         set clipmethod+=osc52
 <
-This will make the osc52.vim provider the last resort if there are other
-values in |clipmethod|.  This allows Vim, for example, to access the system
-clipboard directly if it can, but automatically switch to OSC 52 if it cannot
-(e.g. in an SSH session).  Note that this does not happen when on a platform
-that doesn't use |clipmethod| for system clipboard functionality (MacOS,
-Windows).  If OSC 52 support is detected, then it will always be used if set
-in |clipmethod| when it is the only value/method.
+This appends "osc52" to |clipmethod|, causing Vim to try it only after any
+earlier clipboard methods.  This allows Vim to use the system clipboard
+directly when available, and automatically fall back to OSC 52 method when it
+is not (for example, when running over SSH).
+
+Note: that this fallback behavior applies only on platforms that use
+|clipmethod| for accessing the clipboard.  On macOS and Windows, Vim does not
+use |clipmethod|, so this behaviour won't happen.  Instead if OSC 52 support is
+detected and "osc52" is the only value in |clipmethod|, then it will always be
+used.
+
+You can check whether the osc52.vim provider is active by inspecting
+|v:clipmethod|.  If it contains "osc52", the plugin is enabled.
+
+Note: terminal multiplexers such as tmux may interfere with automatic OSC 52
+detection.
 
                                                         *g:osc52_force_avail*
 In most cases, the plugin should automatically detect and work if your
-terminal supports the OSC 52 command.  Internally, it does this via a Primary
-Device Attributes (DA1) query.  You may force enable the plugin by setting
-|g:osc52_force_avail| to true.  You may check if the osc52.vim plugin is being
-used if the value of |v:clipmethod| is "osc52".  Note that using a terminal
-multiplexer such as tmux, may prevent automatic OSC 52 detection.
+terminal supports the OSC 52 command.  Internally, it does this by sending the
+Primary Device Attributes (DA1) query.  You may force enable the plugin by
+setting |g:osc52_force_avail| to true.
 
                                                         *g:osc52_disable_paste*
 If your terminal does not support pasting via OSC 52, or has it disabled, then
diff --git a/runtime/pack/dist/opt/osc52/plugin/osc52.vim b/runtime/pack/dist/opt/osc52/plugin/osc52.vim
index 7801ef64e5..66b5752e53 100644
--- a/runtime/pack/dist/opt/osc52/plugin/osc52.vim
+++ b/runtime/pack/dist/opt/osc52/plugin/osc52.vim
@@ -3,7 +3,7 @@ vim9script
 # Vim plugin for OSC52 clipboard support
 #
 # Maintainer:	The Vim Project <https://github.com/vim/vim>
-# Last Change:	2025 Dec 16
+# Last Change:	2025 Dec 18
 
 if !has("timers")
   finish
@@ -23,6 +23,17 @@ v:clipproviders["osc52"] = {
   },
 }
 
+def SendDA1(): void
+  if !has("gui_running") && !get(g:, 'osc52_force_avail', 0)
+      && !get(g:, 'osc52_no_da1', 0)
+    echoraw("\<Esc>[c")
+  endif
+enddef
+
+if v:vim_did_enter
+  SendDA1()
+endif
+
 augroup VimOSC52Plugin
   autocmd!
   # Query support for OSC 52 using a DA1 query
@@ -35,12 +46,7 @@ augroup VimOSC52Plugin
       :silent! clipreset
     endif
   }
-  autocmd VimEnter * {
-    if !has("gui_running") && !get(g:, 'osc52_force_avail', 0)
-        && !get(g:, 'osc52_no_da1', 0)
-      echoraw("\<Esc>[c")
-    endif
-  }
+  autocmd VimEnter * SendDA1()
 augroup END
 
 # vim: set sw=2 sts=2 :