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

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

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

\[command]

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

\{mapvar}

これは変数mapvarの値であるようなキーマップの要約(summary)を意味する。この要約はdescribe-bindingsを用いて作成される。

\<mapvar>

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

`

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

'

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

\=

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

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

User Option: text-quoting-style ¶

この変数の値はヘルプやメッセージの文言中のシングルクォートにたいして、Emacsが使用するべきスタイルを指定するシンボル。変数の値がcurveなら‘like this’のようなcurved single quotesスタイル。値がstraightなら'like this'のような素のアポストロフィスタイル。値がgraveならクォートは変換せずに、`like this'のようなEmacsバージョン25以前の標準スタイルであるグレイブアクセントとアポストロフィのスタイル。デフォルト値のnilはcurved single quotesが表示可能なようならcurve、それ以外ならgraveのように機能する。

このオプションはcurved quotesに問題があるプラットフォームで有用。個人の好みに応じてこれを自由にカスタマイズできる。

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

この関数は上述の特別なシーケンスを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
"

(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’."

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