Merge pull request #914 from tsuyoshicho/update/map-sign-20210504

Update {map,sign}.{txt.jax}

Author: h-east

doc/map.jax

@@ -1,4 +1,4 @@
-*map.txt*       For Vim バージョン 8.2.  Last change: 2020 Dec 10
+*map.txt*       For Vim バージョン 8.2.  Last change: 2021 Apr 23
 
 
 		  VIMリファレンスマニュアル	  by Bram Moolenaar
@@ -238,9 +238,12 @@ Note: ":map <script>" と ":noremap <script>" の動作は同じです。コマ
 マップや短縮入力を定義するときに "<expr>" 引数を指定すると、引数が式 (スクリプ
 ト) として扱われます。マップが実行されたときに、式が評価され、その値が {rhs}
 として使われます。例: >
-	:inoremap <expr> . InsertDot()
-InsertDot() 関数の戻り値が挿入されます。カーソルの前のテキストをチェックして、
-ある条件に一致するなら omni 補完を開始する、というようなことができます。
+	:inoremap <expr> . <SID>InsertDot()
+s:InsertDot() 関数の戻り値が挿入されます。カーソルの前のテキストをチェックし
+て、ある条件に一致するなら omni 補完を開始する、というようなことができます。
+グローバルな名前空間の汚染を回避するには、スクリプトローカル関数を利用すること
+が望しいです。RHS内に <SID> を使ってマッピングが定義されたスクリプトを見付けら
+れるようにします。
 
 短縮入力では、入力されて短縮入力展開のトリガーとなった文字が |v:char| にセット
 されます。これを使って {lhs} の展開方法を決めることもできます。自分で v:char
@@ -254,7 +257,20 @@ InsertDot() 関数の戻り値が挿入されます。カーソルの前のテ
 	  call popup_create(... arguments ...)
 	  return "\<Ignore>"
 	endfunc
-	nnoremap <expr> <F3> <Sid>OpenPopup()
+	nnoremap <expr> <F3> <SID>OpenPopup()
+
+また、前のコマンドが実行される前に、先行入力を探す時に式が評価されることがある
+ことを覚えておいてください。例: >
+	func StoreColumn()
+	  let g:column = col('.')
+	  return 'x'
+	endfunc
+	nnoremap <expr> x StoreColumn()
+	nmap ! f!x
+g:column に "f!" 実行前の値がある、つまり "x" が評価されるのが "f!" の実行前で
+あることに気付くでしょう。
+これは評価のマッピングの文字の前に <Ignore> を挿入することで解決できます: >
+	nmap ! f!<Ignore>x
 
 副作用に注意してください。式は文字の取得中に評価されるため、簡単に異常動作を起
 こせてしまいます。そのため、次のものは制限されます:

doc/sign.jax

@@ -1,4 +1,4 @@
-*sign.txt*      For Vim バージョン 8.2.  Last change: 2020 Oct 28
+*sign.txt*      For Vim バージョン 8.2.  Last change: 2021 Mar 07
 
 
 		VIMリファレンスマニュアル    by Gordon Prieur
@@ -142,6 +142,9 @@
 	texthl={group}
 		テキスト部分に使用されるハイライトグループ。
 
+	例: >
+		:sign define MySign text=>> texthl=Search linehl=DiffText
+<
 
 (定義した)目印を削除する				*:sign-undefine* *E155*
 
@@ -151,7 +154,9 @@
 		既に定義された目印を削除する。{name}という名前の目印がまだ設置
 		されたままの場合はトラブルを引き起こす。
 
-
+		例: >
+			:sign undefine MySign
+<
 
 (定義した)目印を一覧表示する				*:sign-list* *E156*
 
@@ -204,6 +209,10 @@
 		上に同じ。バッファ番号を使用していることが異なる。buffer引数が
 		与えられていない場合は、現在のバッファに目印を設置する。
 
+		例: >
+			:sign place 10 line=99 name=sign3
+			:sign place 10 line=99 name=sign3 buffer=3
+<
 							*E885*
 :sign place {id} name={name} file={fname}
 		ファイル{fname}に{id}で設置された目印を、{name}で定義されてい
@@ -216,10 +225,17 @@
 		ループの目印を選択することができる。任意の "priority={prio}"
 		属性を使用して、既存の目印の優先順位を変更することができる。
 
+		例: >
+			:sign place 23 name=sign1 file=/path/to/edit.py
+<
 :sign place {id} name={name} buffer={nr}
 		上に同じ。バッファ番号を使用していることが異なる。buffer引数が
 		与えられていない場合は、現在のバッファを使用する。
 
+		例: >
+			:sign place 23 name=sign1
+			:sign place 23 name=sign1 buffer=7
+<
 
 (設置した)目印を解除する				*:sign-unplace* *E159*
 

en/map.txt

@@ -1,4 +1,4 @@
-*map.txt*       For Vim version 8.2.  Last change: 2020 Dec 10
+*map.txt*       For Vim version 8.2.  Last change: 2021 Apr 23
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -244,9 +244,12 @@ have a look at |maparg()|.
 If the first argument to one of these commands is "<expr>" and it is used to
 define a new mapping or abbreviation, the argument is an expression.  The
 expression is evaluated to obtain the {rhs} that is used.  Example: >
-	:inoremap <expr> . InsertDot()
-The result of the InsertDot() function will be inserted.  It could check the
+	:inoremap <expr> . <SID>InsertDot()
+The result of the s:InsertDot() function will be inserted.  It could check the
 text before the cursor and start omni completion when some condition is met.
+Using a script-local function is preferred, to avoid polluting the global
+namespace.  Use <SID> in the RHS so that the script that the mapping was
+defined in can be found.
 
 For abbreviations |v:char| is set to the character that was typed to trigger
 the abbreviation.  You can use this to decide how to expand the {lhs}.  You
@@ -261,7 +264,21 @@ input. Example: >
 	  call popup_create(... arguments ...)
 	  return "\<Ignore>"
 	endfunc
-	nnoremap <expr> <F3> <Sid>OpenPopup()
+	nnoremap <expr> <F3> <SID>OpenPopup()
+
+Also, keep in mind that the expression may be evaluated when looking for
+typeahead, before the previous command has been executed.  For example: >
+	func StoreColumn()
+	  let g:column = col('.')
+	  return 'x'
+	endfunc
+	nnoremap <expr> x StoreColumn()
+	nmap ! f!x
+You will notice that g:column has the value from before executing "f!",
+because "x" is evaluated before "f!" is executed.
+This can be solved by inserting <Ignore> before the character that is
+expression-mapped: >
+	nmap ! f!<Ignore>x
 
 Be very careful about side effects!  The expression is evaluated while
 obtaining characters, you may very well make the command dysfunctional.

en/sign.txt

@@ -1,4 +1,4 @@
-*sign.txt*      For Vim version 8.2.  Last change: 2020 Oct 28
+*sign.txt*      For Vim version 8.2.  Last change: 2021 Mar 07
 
 
 		  VIM REFERENCE MANUAL    by Gordon Prieur
@@ -146,6 +146,9 @@ See |sign_define()| for the equivalent Vim script function.
 	texthl={group}
 		Highlighting group used for the text item.
 
+	Example: >
+		:sign define MySign text=>> texthl=Search linehl=DiffText
+<
 
 DELETING A SIGN						*:sign-undefine* *E155*
 
@@ -155,7 +158,9 @@ See |sign_undefine()| for the equivalent Vim script function.
 		Deletes a previously defined sign.  If signs with this {name}
 		are still placed this will cause trouble.
 
-
+		Example: >
+			:sign undefine MySign
+<
 
 LISTING SIGNS						*:sign-list* *E156*
 
@@ -209,6 +214,10 @@ See |sign_place()| for the equivalent Vim script function.
 		Same, but use buffer {nr}.  If the buffer argument is not
 		given, place the sign in the current buffer.
 
+		Example: >
+			:sign place 10 line=99 name=sign3
+			:sign place 10 line=99 name=sign3 buffer=3
+<
 							*E885*
 :sign place {id} name={name} file={fname}
 		Change the placed sign {id} in file {fname} to use the defined
@@ -221,10 +230,17 @@ See |sign_place()| for the equivalent Vim script function.
 		"priority={prio}" attribute can be used to change the priority
 		of an existing sign.
 
+		Example: >
+			:sign place 23 name=sign1 file=/path/to/edit.py
+<
 :sign place {id} name={name} [buffer={nr}]
 		Same, but use buffer {nr}.  If the buffer argument is not
 		given, use the current buffer.
 
+		Example: >
+			:sign place 23 name=sign1
+			:sign place 23 name=sign1 buffer=7
+<
 
 REMOVING SIGNS						*:sign-unplace* *E159*