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

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

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

\[command]

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

\{mapvar}

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

\<mapvar>

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

‘

`

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

’

'

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

\=

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

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

Variable: text-quoting-style

この変数の値はEmacsがヘルプとメッセージの文言でシングルクォートに使用するべきスタイルを指定するシンボルである。この変数の値がcurveなら‘like this’のようなcurved single quotesスタイル。値がstraightなら'like this'のようなstraight apostrophesスタイル。値がgraveなら`like this'のようなEmacsのバージョン25以前の標準であるgrave accentとapostropheのスタイル。デフォルト値のnilはcurved single quotesが表示可能ならcurve、それ以外ならgraveと同様に振る舞う。

この変数はcurved quotesに問題のあるプラットフォームでエキスパートが使用可能。通常の使用を意図していないのでユーザーオプションではない。

Function: substitute-command-keys string

この関数は上述の特別なシーケンスをstringからスキャンして、それらが意味するもので置き換えてその結果を文字列としてリターンする。これによりそのユーザー自身がカスタマイズした実際のキーシーケンスを参照するドキュメントが表示できる。

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

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

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

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

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

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