Merge pull request #1324 from vim-jp/hh2-update-term

Update term.{txt,jax}

doc/term.jax

@@ -1,4 +1,4 @@
-*term.txt*      For Vim バージョン 9.0.  Last change: 2022 Apr 23
+*term.txt*      For Vim バージョン 9.0.  Last change: 2023 Jan 15
 
 
 		VIMリファレンスマニュアル    by Bram Moolenaar
@@ -42,15 +42,10 @@ Unix 以外のシステムでは、TERMCAP を定義してコンパイルした
 用できます。
 
 					*builtin-terms* *builtin_terms*
-どの組み込み端末が利用できるかは、feature.h で定義されているマクロに依存します。
-これらはコンパイル時に設定しなければなりません:
-    define		":version" の出力	組み込まれる端末	~
-NO_BUILTIN_TCAPS	-builtin_terms		なし
-SOME_BUILTIN_TCAPS	+builtin_terms		一般的なもの (デフォルト)
-ALL_BUILTIN_TCAPS	++builtin_terms		全て使用可能
-
-利用可能な組み込み端末のリストを見るには ":set term=xxx" とします(GUI でないと
-きのみ)。|+builtin_terms|も参照。
+多くの組み込み端末が利用可能です。パッチ 9.0.0280 以降、Vim のバージョンによる
+違いはありません。利用可能な組み込み端末のリストは `:set term=xxx` のエラーメッ
+セージで見ることができます (GUI を実行していない場合)。|++builtin_terms| も参
+照してください。
 
 termcap のコードが組み込まれているときは、termcap ファイルと組み込みの termcap
 から、使われている端末用のキーシーケンスを取得しようとします。使われている端末
@@ -89,7 +84,14 @@ termcap のコードが組み込まれているときは、termcap ファイル
 
 Note: 't_ti' が空でない場合、Vimは代替画面への切り替えが生じると想定します。こ
 れにより、シェルコマンドの実行時またはVimの終了時の動作がわずかに変わる場合が
-あります。これを回避するには、't_TI' と 't_TE' を使用します。
+あります。これを回避するには、't_TI' と 't_TE' を使用します。(ただし、上書きで
+はなく追加してください)。
+
+Vim は 't_RK' termcap エントリを使用して、端末が使用しているキーボードプロトコ
+ルを検出しようとします。これは 't_TI' の後に送信されますが、何もすることがない
+(typeahead も保留中のコマンドもない) 場合にのみ送信されます。これはレスポンス
+がシェルコマンドで終わってしまったり、Vim が終了した後に届くのを避けるためで
+す。
 
 						*xterm-bracketed-paste*
 't_BE' がオンの場合、raw モードに入るときに 't_BE' が端末に送信され、raw モー
@@ -113,6 +115,10 @@ Note: 't_ti' が空でない場合、Vimは代替画面への切り替えが生
 もし Vim の実行中にこれを実行した場合、bracketed paste を無効化するため 't_BD'
 が端末に送信されます。
 
+|t_PS| または |t_PE| が設定されていない場合、|t_BE| は使用されません。これは、
+貼り付けられたテキストを囲むエスケープコードが認識できない場合に、bracketed
+paste が有効にならないようにするためです。
+
 端末が bracketed paste をサポートしているにもかかわらずオプションが自動的に設
 定されない場合、以下のような設定を試すことができます: >
 
@@ -122,7 +128,11 @@ Note: 't_ti' が空でない場合、Vimは代替画面への切り替えが生
 	  exec "set t_PS=\e[200~"
 	  exec "set t_PE=\e[201~"
 	endif
-<
+
+terminfo エントリ "BE"、"BD"、"PS"、"PE" は、ncurses バージョン 6.4、2023 年初
+頭に、一部の端末用に追加されました。このバージョンであれば、端末を手動で設定す
+る必要はないかもしれません。
+
 							*tmux-integration*
 tmux 内で Vim を実行する際に問題が発生する場合、ここにいくつかのヒントがありま
 す。もし動かないならその部分はコメントアウトすることができます(これは tmux を
@@ -289,6 +299,56 @@ Vim がシーケンス |t_RV| (バージョン要求)への応答を受け取っ
 で始まっていれば、その端末は 8 ビットモードであると認識し、全てのキーシーケン
 スを 8 ビット版に変換します。
 
+						*xterm-terminfo-entries*
+しばらくの間、terminfo エントリは Vim が使える全ての機能を記述するには不十分で
+した。その結果、xterm とよく似たいくつかの端末が、$TERM の端末名の前に
+"xterm-" をつけることで、この機能を利用していました。
+
+このような端末は xterm と 100% 互換性があるわけではないので、これは問題になり
+ます。"xterm" の回避策を使用せずにこれらの機能を使用できるように、2023 年の開
+始時点で、terminfo データベースにいくつかのエントリが追加されました。(今のとこ
+ろ) 以下がそのエントリです:
+
+	名前	xterm の値	説明 ~
+	RV	"\033[>c"	リクエストバージョン |t_RV|
+
+	BE	"\033[?2004h"	bracketed paste モードを有効化 |t_BE|
+	BD	"\033[?2004l"	bracketed paste モードを無効化 |t_BD|
+	PS	"\033[200~"	貼り付けテキスト開始 |t_PS|
+	PE	"\033[201~"	貼り付けテキスト終了 |t_PE|
+
+	XM	"\033[?1006;1004;1000%?%p1%{1}%=%th%el%;"
+				マウスの有効 / 無効 |t_XM|
+
+"XM" エントリは、SGR スタイルのマウスレポートを有効にするために "1006" を含み
+ます。これは223以上の桁をサポートします。また、フォーカスレポートを有効にする
+"1004" も含まれます。t_fe および t_fd エントリは空のままでよいです (どのみち
+terminfo/termcap にはエントリがありません)。
+
+						*xterm-kitty* *kitty-terminal*
+Kitty 端末は特別なケースです。主な理由は、他のほとんどの端末とは動作が異なるか
+らですが、デフォルトで他の端末と同じように動作するようにするのではなく、Kitty
+を使用する際にアプリケーションがどのように動作する必要があるかを規定しているか
+らです。このため、Vim が Kitty 端末で動作するのは非常に困難です。いくつかの例
+外はハードコーディングされていますが、ある特定の端末のために例外を作らなければ
+ならないのは全く良いことではありません。
+
+問題の 1 つは、$TERM の値が "xterm-kitty" に設定されていることです。Vim の場
+合、これは端末が xterm 互換であることを示すもので、組み込みの xterm termcap エ
+ントリを使用する必要があります。他の多くの端末はこれに依存しています。しかし、
+Kitty は完全な xterm 互換ではありません。作者は "xterm-" という接頭辞を無視し
+てとにかく terminfo エントリを使うことを提案しました。そのため、現状、組み込み
+の xterm termcap エントリは使われないということが起きています。しかし、t_RV は
+設定されます。そうしないと、自動的に 'ttymouse' を "sgr" に設定するなど、他の
+ことがうまくいきません (少なくとも |t_XM| がこれに使われるまでは)。
+
+なぜ kitty が $TERM を "xterm-kitty" に設定するのかは不明です。"kitty" の方が
+適切ですが、この名前の terminfo エントリは普及していません。
+
+Note kitty キーボードプロトコルの使用は別の機能であることに注意してください。
+|kitty-keyboard-protocol| を参照。
+
+
 ==============================================================================
 2. 端末オプション		*terminal-options* *termcap-options* *E436*
 
@@ -368,8 +428,11 @@ termcap コードに対応するオプションを設定することによって
 
 Vim 独自のもの (標準的なコードはないもの):
 	t_AU	下線色を設定する (ANSI)				*t_AU* *'t_AU'*
-	t_Ce	下波線終了					*t_Ce* *'t_Ce'*
-	t_Cs	下波線モード					*t_Cs* *'t_Cs'*
+	t_Ce	下波線および下線終了				*t_Ce* *'t_Ce'*
+	t_Cs	下波線 (波線の下線) モード			*t_Cs* *'t_Cs'*
+	t_Us	2 重下線モード					*t_Us* *'t_Us'*
+	t_ds	点線下線モード					*t_ds* *'t_ds'*
+	t_Ds	破線下線モード					*t_Ds* *'t_Ds'*
 	t_Te	取り消し線終了					*t_Te* *'t_Te'*
 	t_Ts	取り消し線モード				*t_Ts* *'t_Ts'*
 	t_IS	アイコンテキスト設定開始			*t_IS* *'t_IS'*
@@ -385,6 +448,10 @@ Vim 独自のもの (標準的なコードはないもの):
 	t_RV	端末バージョン文字列を要求 (xterm および他の	*t_RV* *'t_RV'*
 		仮想端末用) 応答は |v:termresponse| に格納される |xterm-8bit|
 		|'ttymouse'| |xterm-codes|
+	t_XM	マウスレポートの有効/無効			*t_XM* *'t_XM'*
+		以下の |mouse-reporting| 参照
+	t_RK	端末キーボートプロトコル状態を要求する		*t_RK* *'t_RK'*
+		|t_TI| の後に送信
 	t_u7	カーソル位置を要求 (xterm 用)			*t_u7* *'t_u7'*
 		|'ambiwidth'| 参照
 		応答は |v:termu7resp| に格納される
@@ -413,7 +480,7 @@ Vim 独自のもの (標準的なコードはないもの):
 	t_Si	アイコンテキストをスタックに保存		*t_Si* *'t_Si'*
 	t_Ri	アイコンテキストをスタックから復元		*t_Ri* *'t_Ri'*
 	t_TE	"raw" モードの終了				*t_TE* *'t_TE'*
-	t_TI	端末を "raw" モードにする 			*t_TI* *'t_TI'*
+	t_TI	端末を "raw" モードにする			*t_TI* *'t_TI'*
 	t_fe	フォーカスイベント追跡を有効化する		*t_fe* *'t_fe'*
 		|xterm-focus-event|
 	t_fd	フォーカスイベント追跡を無効化する		*t_fd* *'t_fd'*
@@ -436,6 +503,22 @@ t_SH は 1 つの引数を取らなければなりません:
 t_RS は、t_RV に対する応答を受け取った場合のみ送られます。termresponse から
 Terminal.app が認識され得る場合、Mac OS 上では使われません。
 
+							*mouse-reporting*
+多くの端末はマウスのクリックを報告し、いくつかの端末はマウスの動きやドラッグを
+報告することができます。Vim はこのためにどんなコードが使われているかを知る必要
+があります。
+
+これには "XM" terminfo/termcap エントリを使います。また、Vim には 'ttymouse'
+オプションがあり、使用されているマウスプロトコルを指定することができます。指定
+可能な値はオプションを参照してください。
+
+Vimが "XM" terminfo/termcap エントリを読み込むことができれば、マウス報告の有
+効/無効を指定するのに使われます。このエントリがない場合は、'ttymouse' の値が使
+われます。
+
+"XM" エントリが存在し、最初の数字が "1006" である場合、既に以前に設定されてい
+ない限り、"ttymouse" は "sgr" に設定されます。
+
 
 キーコード						*terminal-key-codes*
 Note: 可能なかぎり <> 形式を使ってください。
@@ -496,6 +579,7 @@ Note: 可能なかぎり <> 形式を使ってください。
 	t_%1	<Help>		ヘルプキー			*t_%1* *'t_%1'*
 	t_&8	<Undo>		アンドゥキー			*t_&8* *'t_&8'*
 	t_kI	<Insert>	インサートキー			*t_kI* *'t_kI'*
+		<kInsert>	キーパッドインサートキー
 	t_kD	<Del>		デリートキー			*t_kD* *'t_kD'*
 	t_kb	<BS>		バックスペースキー		*t_kb* *'t_kb'*
 	t_kB	<S-Tab>		バックタブ(シフト＋タブ) *<S-Tab>* *t_kB* *'t_kB'*
@@ -528,8 +612,13 @@ Note: 可能なかぎり <> 形式を使ってください。
 	t_KK	<k8>		キーパッド 8		 *<k8>*	*t_KK* *'t_KK'*
 	t_KL	<k9>		キーパッド 9		 *<k9>*	*t_KL* *'t_KL'*
 		<Mouse>		マウスコードの先頭部分		*<Mouse>*
-	t_PS	bracketed paste の開始 |xterm-bracketed-paste|	*t_PS* *'t_PS'*
-	t_PE	bracketed paste の終了 |xterm-bracketed-paste|	*t_PE* *'t_PE'*
+
+	t_PS	<PasteStart>	bracketed paste の開始		*t_PS* *'t_PS'*
+				|xterm-bracketed-paste|
+	t_PE	<PasteEnd>	bracketed paste の終了		*t_PE* *'t_PE'*
+				|xterm-bracketed-paste|
+		<FocusGained>	Vim ウィンドウがフォーカスを取得 (内部のみ)
+		<FocusLost>	Vim ウィンドウがフォーカスを消失 (内部のみ)
 
 Note t_so と t_mrについて: termcap に "so" エントリがない場合は "mr" が使われ
 ます。逆に "mr" がない場合は "so" が使われます。"se" と "me" も同じ関係にあり
@@ -566,14 +655,18 @@ Vimは端末がサポートするならば、トゥルーカラーを使うこ
 び |highlight-guibg| を流用する) をサポートします。これを機能させるには
 'termguicolors' オプションをセットする必要があります。
 トゥルーカラーをサポートする端末の一覧については
-https://gist.github.com/XVilka/8346728 を参照してください。
-
-場合によっては 'termguicolors' を設定するだけでは不十分で、|t_8f| と |t_8b| オ
-プションを明示的に設定しなければならないことがあります。これらのオプションのデ
-フォルトはそれぞれ "^[[38;2;%lu;%lu;%lum" と "^[[48;2;%lu;%lu;%lum" で、
-`$TERM` が `xterm` の時にだけ設定されます。幾つかの端末は同じシーケンスを受け
-付けますが、全てのセミコロンをコロンで置き換える必要があります (実際にはコチラ
-のほうが互換性の高い方法ですが、広くはサポートされていません): >
+https://github.com/termstandard/colors を参照してください。
+
+使用する RGB カラーを端末に伝えるために、|t_8f| と |t_8b| termcap エントリが使
+用されます。これらは、ほとんどの端末で動作する値にデフォルトで設定されていま
+す。使用している端末で動作しない場合は、手動で設定することができます。デフォル
+ト値は以下のように設定されています: >
+	 let &t_8f = "\<Esc>[38;2;%lu;%lu;%lum"
+	 let &t_8b = "\<Esc>[48;2;%lu;%lu;%lum"
+
+端末によっては、セミコロンをすべてコロンに置き換えた同じシーケンスを受け付ける
+ものもあります (この方が実際には互換性が高いですが、あまり広くサポートされてい
+ません): >
 	 let &t_8f = "\<Esc>[38:2:%lu:%lu:%lum"
 	 let &t_8b = "\<Esc>[48:2:%lu:%lu:%lum"
 
@@ -590,7 +683,7 @@ xterm でのウィンドウサイズ変更はリソース allowWindowOps が有
 既定値を上書きするには、次の行を ~/.Xdefaults または ~/.Xresources に書きま
 す:
 >
-	XTerm*allowWindowOps: 		true
+	XTerm*allowWindowOps:		true
 
 そして "xrdb -merge .Xresources" を実行し、この設定を有効化します。コンテキス
 トメニュー(CTRL キーを押しながらマウス右ボタン)でこの値を確認できます。
@@ -625,9 +718,13 @@ GUIが動作している時 't_Co' は 16777216 に設定されます。
 Vimが挿入モードに入るときにはエスケープシーケンス 't_SI' が送られます。置換モ
 ードに入るときにはエスケープシーケンス 't_SR' が設定されていれば送られます。設
 定されていない場合には 't_SI' が送られます。挿入モード及び置換モードを抜けると
-きには 't_EI' が送られます。これらは挿入や置換モードにおいてカーソルの形や色を
-変えるのに利用できます。またこれらは標準的な termcap/terminfo エントリではない
-ので、自分で設定する必要があります。
+きには 't_EI' が送られます。
+Note: 't_EI' が設定されていない場合、't_SI' と 't_SR' は送信されません。また、
+'t_SI' または 't_SR' が設定されていないときは、't_EI' は一度だけ送られます。
+
+これは、挿入モードや置換モードでカーソルの形や色を変更するために使用できます。
+これらは標準の termcap/terminfo 項目ではないので、自分で設定する必要がありま
+す。
 
 以下は xterm でカーソルの色を変える例です: >
     if &term =~ "xterm"
@@ -637,6 +734,18 @@ Vimが挿入モードに入るときにはエスケープシーケンス 't_SI'
     endif
 NOTE: Vim を終了するとき、ノーマルモードでのカーソル設定がそのまま残ります。
 Vim を起動する前のカーソル設定は復元されません。
+
+Windows Terminalの場合は、次のような使い方ができます: >
+    " Note: これは `set termguicolors` または `set t_Co=256` の後に設定する。
+    if &term =~ 'xterm' || &term == 'win32'
+	" DECSCUSR エスケープシーケンスを使用する
+	let &t_SI = "\e[5 q"    " バー点滅
+	let &t_SR = "\e[3 q"    " 下線点滅
+	let &t_EI = "\e[1 q"    " ブロック点滅
+	let &t_ti ..= "\e[1 q"   " ブロック点滅
+	let &t_te ..= "\e[0 q"   " デフォルト (端末に依存するが、通常はブロック点滅)
+    endif
+
 {|+cursorshape| つきでコンパイルしたときのみ利用可能}
 
 							*termcap-title*
@@ -746,8 +855,9 @@ Amiga 上では端末名が "amiga" または "builtin_amiga" であればアミ
 
 お使いの端末が領域のスクロールをサポートしていないが、行の挿入・削除コマンドを
 サポートしている場合、複数のウィンドウを開いた状態でスクロールすると、行が上下
-するかもしれません。これが好ましくない場合は 'ttyfast' をオンにしてください。
-するとウィンドウをスクロールするのでなく再描画するようになります。
+するかもしれません。これは、'ttyfast' オプションがリセットされている場合に起こ
+ります。それを確認してください: >
+	verbose set ttyfast?
 
 お使いの端末におけるスクロールが非常に遅いが再描画は遅くないという場合は、
 'ttyscroll' を 3 などの小さな値にしてください。すると、3 行より多くスクロール
@@ -978,6 +1088,8 @@ MS-Windows と xterm ではダブルクリックの間隔は 'mousetime' で設
 されるようになります。これはボタンが離されるまで続き、ボタンを離すと文字単位に
 戻ります。
 
+マウスによるスクロールについては |scroll-mouse-wheel| を参照。
+
 							*gpm-mouse*
 GPM マウスは |+mouse_gpm| 機能を有効にしてコンパイルしたときのみサポートされま
 す。GPM マウスドライバ(Linux コンソール)はクアドラプルクリックに対応していませ