25.3 ドキュメント内でのキーバインディングの置き換え

ドキュメント文字列がキーシーケンスを参照する際、それらはカレントである実際のキーバインディングを使用するべきです。これらは以下で説明する特別なキーシーケンスを使用して行うことができます。通常の方法によるドキュメント文字列へのアクセスは、これらの特別なキーシーケンスをカレントキーバインディングに置き換えます。これはsubstitute-command-keysを呼び出すことにより行われます。あなた自身がこの関数を呼び出すこともできます。

以下はそれら特別なシーケンスと、その意味についてのリストです:

\[command]

これはcommandを呼び出すキーシーケンス、またはcommandがキーバインディングをもたなければ‘M-x command’。

\{mapvar}

これは変数mapvarの値であるようなキーマップのサマリー(summary: 要約)を意味する。この要約はdescribe-bindingsを用いて作成される。このサマリーからはメニューのキーバインディングが除外されているが、substitute-command-keysの引数include-menusに非nilを渡せばメニューのバインディングも含められるようになる。

\<mapvar>

これ自体は何のテキストも意味せず副作用のためだけに使用される。これはこのドキュメント文字列内にある、後続のすべての‘\[command]’にたいするキーマップとしてmapvarの値を指定する。

\`KEYSEQ'

これはキーシーケンスKEYSEQを表し、コマンド置き換えと同じフェイスが使用される。これはキーシーケンスがたとえばread-key-sequenceによって直接読み取られた場合のように、対応するコマンドがない場合のみ使用すること。キーシーケンスはkey-valid-pに照らして有効なキーシーケンスでなければならない。これは‘\`M-x foo'’のようなコマンド名にたいして、キーボードシーケンスのようにフォント表示したいものの、‘\[foo]’が行うようなキーシーケンスへの変換を抑止したい場合にも使用できる。

`

グレイブアクセント(grave accent)は左クォートを意味する。これはtext-quoting-styleの値に応じて左シングルクォーテーションマーク、アポストロフィ、グレイブアクセントのいずれかを生成する。テキストのクォートスタイルを参照のこと。

'

アポストロフィ(apostrophe)は右クォートを意味する。これはtext-quoting-styleの値に応じて右シングルクォーテーションマーク、アポストロフィのいずれかを生成する。テキストのクォートスタイルを参照のこと。

\=

これは後続の文字をクォートして無効にする。したがって‘\=`’は‘`’、‘\=\[’は‘\[’、‘\=\=’は‘\=’を出力する。

\+

これは直後のシンボルを*Help*バッファーでリンクとしてマークするべきではないことを示す。

注意してください: Emacs Lisp内の文字列として記述する際は‘\’を2つ記述しなければなりません。

Function: substitute-command-keys string &optional no-face include-menus ¶

この関数は上述の特別なシーケンスをstringからスキャンして、それらが意味するもので置き換えてその結果を文字列としてリターンする。これによりそのユーザー自身がカスタマイズした実際のキーシーケンスを参照するドキュメントが表示できる。そのキーバインディングにはデフォルトでは特別なフェイスhelp-key-bindingが与えられるが、オプション引数no-faceが非nilなら、この関数は生成した文字列にこのフェイスを追加しない。

あるコマンドが複数のバインディングをもつ場合、通常この関数は最初に見つかったバインディングを使用する。以下のようにしてコマンドのシンボルプロパティ:advertised-bindingに割り当てることにより、特定のキーバインディングを指定できる:

(put 'undo :advertised-binding [?\C-/])

:advertised-bindingプロパティはメニューアイテム(メニューバーを参照)に表示されるバインディングにも影響する。コマンドが実際にもたないキーバインディングを指定するとこのプロパティは無視される。

以下は特別なキーシーケンスの例:

(substitute-command-keys
   "To abort recursive edit, type `\\[abort-recursive-edit]'.")
⇒ "To abort recursive edit, type ‘C-]’."

(substitute-command-keys
   "The keys that are defined for the minibuffer here are:
  \\{minibuffer-local-must-match-map}")
⇒ "The keys that are defined for the minibuffer here are:

?               minibuffer-completion-help
SPC             minibuffer-complete-word
TAB             minibuffer-complete
C-j             minibuffer-complete-and-exit
RET             minibuffer-complete-and-exit
C-g             abort-recursive-edit
"

The keymap description will normally exclude menu items, but if
include-menus is non-nil, include them.

(substitute-command-keys
   "To abort a recursive edit from the minibuffer, type \
`\\<minibuffer-local-must-match-map>\\[abort-recursive-edit]'.")
⇒ "To abort a recursive edit from the minibuffer, type ‘C-g’."

Function: substitute-quotes string ¶

この関数はsubstitute-command-keysと同じように機能するが、クォート文字だけを置き換える。

ドキュメント文字列内のテキストにたいしては他にも特別な慣習があります。それらはたとえばこのマニュアルの関数、変数、およびセクションで参照できます。詳細はドキュメント文字列のヒントを参照してください。