Merge pull request #2129 from h-east/add-wayland

h-east · web-flow · commit 1b723ba582ec · 2025-06-29T22:34:41.000+09:00
Add wayland.{txt,jax}
diff --git a/doc/wayland.jax b/doc/wayland.jax
@@ -0,0 +1,116 @@
+*wayland.txt*   For Vim バージョン 9.1.  Last change: 2025 Jun 28
+
+
+		  VIMリファレンスマニュアル	  by Bram Moolenaar
+
+
+Wayland プロトコルのサポート				*wayland*
+
+1. Wayland の役立つ情報		|wayland-useful|
+2. Wayland セレクション		|wayland-selections|
+
+==============================================================================
+1. Wayland の役立つ情報					*wayland-useful*
+
+							*wayland-seat*
+Wayland のクリップボードなどの機能を使用するには、シートが必要である。Wayland
+シートは、キーボード、ポインター、タッチデバイスで構成される。使用するシートは
+'wlseat' オプションで設定できる。これは、同じ Wayland セッションで複数の
+Wayland シートを使用する場合にのみ役立つ。
+
+							*wayland-gui*
+|gui-wayland| を参照。GUI 使用時、Vim はクリップボードへのアクセスに GTK など
+のツールキットを使用し、Wayland 経由ではアクセスしない。これは |v:clipmethod|
+変数で確認できる。GUI 実行時にはこの変数は "none" になる。
+
+Wayland のコマンド:
+							*:wlrestore* *:wl*
+:wl[restore] [display]	Wayland コンポジタへの接続を再初期化する。Wayland コン
+			ポジタの再起動後も Vim を screen/tmux セッションで実行
+			し続ける場合に便利である。
+
+			[display] は、環境変数 $WAYLAND_DISPLAY の形式（例:
+			"wayland-0"）で指定する必要がある。[display] を省略し
+			た場合は、このコマンドの前回実行時に使用された値と同じ
+			値を使用して接続を再初期化する。
+			値が指定されていない場合は、環境変数 $WAYLAND_DISPLAY
+			の値が使用される。また、|v:clipmethod| も更新される。
+			{Vimが |+wayland| 機能付きでコンパイルされたときのみ有
+			効}
+
+Wayland のエラー:
+							*E1548*
+Vim は Wayland コンポジタとの通信に失敗した。これは Wayland コンポジタのプロセ
+スが強制終了したことが原因である可能性がある。再接続するには `:wlrestore` コマ
+ンドを試すこと。
+
+==============================================================================
+2. Wayland セレクション					*wayland-selections*
+
+Vim は、現在の Wayland セレクションにアクセスするための
+wlr-data-control-unstable-v1 プロトコルと ext-data-control-v1 プロトコルをサ
+ポートしている。これらは最適なシナリオのプロトコルである。
+|wayland-focus-steal| を参照。この場合のセレクションは基本的に "clipboard" を
+指す。Wayland コンポジタがこれらのプロトコルをサポートしているかどうかを確認す
+るには、wayland-info コマンドを実行する。このコマンドは、あなたのシステムでは
+libwayland にバンドルされているはずである: >
+	wayland-info | grep -E '(ext_data_control|zwlr_data_control)'
+<grep で一致するものが見つかった場合、システムにはどちらか、または両方のプロト
+コルが存在する。一致するものが見つからない場合、詳細については
+|wayland-focus-steal| を参照。
+
+X11 から移行する場合、通常の Waylandセレクション は X11 のクリップボードセレク
+ションに相当し、プライマリ Wayland セレクションは X11 のプライマリセレクション
+に相当する。これらのセレクションへのアクセスは Vim の X11 と同様で、+ レジスタ
+が通常のセレクション、* レジスタがプライマリセレクションである。Note コンポジ
+タがプライマリセレクションをサポートしていない可能性があることに注意。詳細は
+|wayland-primary-selection| を参照。
+
+							*wayland-persist*
+X11 のカットバッファを使用する場合、Wayland にはそのような機能は存在しない。そ
+のような機能をエミュレートするには、Wayland クライアントが存在する場合にセレク
+ションデータを保持するために、別のクリップボードマネージャーを使用する必要があ
+る。
+
+							*wayland-and-x11*
+使用している Vim のバージョンが X11 と Wayland の両方のサポートでコンパイルさ
+れている場合、Vim は 'clipmethod' オプションを使用してクリップボードにアクセス
+するときにどちらを使用するかを決定する。
+
+						*wayland-primary-selection*
+X11 スタイルのプライマリセレクションが便利だと感じる場合、Wayland も独自のプロ
+トコルでこの動作を実装している:
+
+- プライマリセレクションプロトコルは最も広くサポートされているが、使用するには
+  フォーカスが必要である。|wayland-focus-steal| を参照。
+
+- システムで利用可能なデータ制御プロトコル (ext プロトコルや wlr プロトコルな
+  ど) を使用している場合は、プライマリセレクションもサポートされる。ただし、
+  wlr-data-control プロトコルのバージョン 1 (プロトコル名の 'v1' とは異なる)
+  を使用している場合は、プライマリセレクションプロトコルがフォールバックとして
+  使用される。
+
+					*wayland-focus-steal* *wayland-gnome*
+Wayland で GNOME デスクトップ環境を使用している場合、この記事の執筆時点では、
+Vim などの外部クライアントがフォーカスされていない状態でクリップボードにアクセ
+スしたり、クリップボードを変更したりする手段はない。この場合のフォーカスされて
+いるの意味は、クライアントが何らかの入力イベント (ウィンドウがフォーカスされて
+いるなど) を受信したことを意味する。これは、wlr-data-control-unstable-v1 プロ
+トコルと ext-data-control-v1 プロトコルによって解決される。Wayland コンポジタ
+が上記のプロトコルをサポートしていない場合は、上記の説明が適用される。
+
+この問題を解決するため、Vim は一時的に透明なトップレベルサーフェスを作成するこ
+とで、クリップボードにアクセスするためにフォーカスを取得する方法を実装してい
+る。これはデフォルトでは無効になっているが、'wlsteal' オプションで有効にでき
+る。さらに、キーボード付きのシート、'wlseat' を参照、と xdg-shell プロトコルが
+利用可能である必要がある。
+
+Note この方法は、フォーカスを奪取することによるいくつかの副作用を引き起こす可
+能性があることに注意。例えば、デスクトップ環境に現在開いているアプリを表示する
+タスクバーがある場合、Vim がフォーカスを奪取しようとすると、ウィンドウを開いて
+すぐに閉じたかのように「ちらつく」ことがある。
+さらに、フルスクリーンモードの場合、作成されたサーフェスがフォーカスを取得しな
+いため、このフォーカス奪取は機能しない。この場合、Vim は一時的にフリーズしたよ
+うに見える。詳細については、'wltimeoutlen' を参照。
+
+ vim:tw=78:ts=8:noet:ft=help:norl:
diff --git a/en/wayland.txt b/en/wayland.txt
@@ -0,0 +1,118 @@
+*wayland.txt*   For Vim version 9.1.  Last change: 2025 Jun 28
+
+
+		  VIM REFERENCE MANUAL    by Bram Moolenaar
+
+
+Wayland Protocol Support				*wayland*
+
+1. Useful Wayland information	|wayland-useful|
+2. Wayland selections		|wayland-selections|
+
+==============================================================================
+1. Useful Wayland information				*wayland-useful*
+
+							*wayland-seat*
+Functionality such as the clipboard for Wayland requires a seat to use.  A
+Wayland seat can consist of a keyboard, pointer, and touch device(s).  The
+seat to use can be set with the 'wlseat' option.  Only useful if you use
+multiple Wayland seats in the same Wayland session.
+
+							*wayland-gui*
+See |gui-wayland|.  Please note that when using the GUI, Vim uses the toolkit
+such as GTK for accessing the clipboard, and does not access the clipboard
+though Wayland.  You can check this though the |v:clipmethod| variable, which
+should equal to "none" when running the GUI.
+
+Wayland commands:
+							*:wlrestore* *:wl*
+:wl[restore] [display]	Reinitializes the connection to the Wayland compositor.
+			Useful when running Vim in a screen/tmux session that
+			continues running after the Wayland compositor
+			restarts.
+
+			[display] should be in the format of the
+			$WAYLAND_DISPLAY environment variable (e.g.
+			"wayland-0").  If [display] is omitted, then it
+			reinitializes the connection using the same value as
+			was used for the previous execution of this command.
+			If the value was never specified, then it uses the
+			value of $WAYLAND_DISPLAY environment variable.  This
+			will also update |v:clipmethod|.
+			{only available when compiled with the |+wayland|
+			feature}
+
+Wayland errors:
+							*E1548*
+Vim failed communicating with the Wayland compositor.  This is likely due to
+the Wayland compositor process being killed.  Try the `:wlrestore` command to
+try connecting again.
+
+==============================================================================
+2. Wayland Selections					*wayland-selections*
+
+Vim supports the wlr-data-control-unstable-v1 and ext-data-control-v1
+protocols, for accessing the current Wayland selection.  These are the best
+case scenario protocols, see |wayland-focus-steal|.  Selection in this case
+essentially means the "clipboard."  You can check if your Wayland compositor
+supports either of these protocols by running the wayland-info command, which
+should be bunded with libwayland on your system: >
+	wayland-info | grep -E '(ext_data_control|zwlr_data_control)'
+<If grep finds a match, then you have either or both protocols on your system.
+If you don't get any match, then please see |wayland-focus-steal| for more
+information.
+
+If you come from X11, then the regular Wayland selection is equivalent to the
+CLIPBOARD selection in X11, and the primary Wayland selection equates to the
+X11 primary selection.  Accessing these selections is the same as X11 in Vim,
+in which the + register is the regular selection, and the * register is the
+primary selection, note that your compositor may not support primary
+selections, see |wayland-primary-selection| for more details.
+
+							*wayland-persist*
+If you use X11 cut buffers, no such things exist on Wayland.  Instead to
+emulate such functionality, a separate clipboard manager must be used in order
+to persist selection data when a Wayland client exists.
+
+							*wayland-and-x11*
+If your version of Vim comes compiled with both X11 and Wayland support, then
+Vim determines which one to use when accessing the clipboard using the
+'clipmethod' option.
+
+						*wayland-primary-selection*
+If you find X11 style primary selections useful, Wayland also implements this
+behaviour in its own protocols:
+
+- The primary selection protocol is the most widely supported, but requires
+  focus in order to be used, see |wayland-focus-steal|.
+
+- Data control protocol available on your system, such as the ext or wlr
+  protocols, then primary selection is also supported.  This is unless you are
+  using version 1 (not the same as the 'v1' in the protocol name), of the
+  wlr-data-control protocol.  Then the primary selection protocol will be used
+  as a fallback.
+
+					*wayland-focus-steal* *wayland-gnome*
+If you are using the GNOME desktop environment on Wayland, as of this writing,
+there is no method of accessing/modifying the clipboard for external clients
+such as Vim without being focused.  Focused in this case means the client has
+received some sort of input event, such as a window being focused.  This is
+what the wlr-data-control-unstable-v1 and ext-data-control-v1 protocols solve.
+If your Wayland compositor does not support the above protocols, then the
+above explanation applies.
+
+To solve this problem, Vim implements a way of gaining focus in order to
+access the clipboard, by creating a temporary transparent top-level surface.
+This is by default disabled and can be enabled via the 'wlsteal' option.
+Moreover, a seat that has a keyboard is also required, see 'wlseat', and the
+xdg-shell protocol must be available.
+
+Note that this method can have several side effects from the result of focus
+stealing.  For example, if you have a taskbar that shows currently opened apps
+in your desktop environment, then when Vim attempts to steal focus, it may
+"flicker," as if a window was opened then immediately closed after.
+Additionally, if you are in fullscreen mode, this focus stealing won't work,
+because the created surface won't ever gain focus.  If this happens, Vim will
+seem to freeze temporarily, see 'wltimeoutlen' for more information.
+
+ vim:tw=78:ts=8:noet:ft=help:norl
