ドキュメント文字列でキーシーケンスを参照する場合、現在実際に適用されているキーバインドを使用する必要があります。これは、以下に説明する特定の特殊なテキストシーケンスを用いることで実現できます。通常の方法でドキュメント文字列にアクセスすると、これらの特殊なシーケンスが現在のキーバインド情報に置換されます。これは
substitute-command-keys
を呼び出すことで動作します。また、この関数を自身で呼び出すことも可能です。
特殊シーケンスの一覧とその意味は以下の通りです。
\[command]commandを呼び出すキーシーケンス、またはcommandにキーバインドがない場合は‘M-x command’を表します。
\{mapvar}キーマップの概要を表しており、その値は変数 mapvar となります。概要は 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
の値に応じて、左シングルクォート、アポストロフィ、またはグレイヴアクセントが生成されます。テキスト引用スタイルを参照してください。
'(アポストロフィ) は右引用符を表します。これにより、text-quoting-style
の値に応じて、右シングルクォートまたはアポストロフィが生成されます。
\=次の文字を引用して破棄します。したがって、‘\=`’は‘`’を出力に、‘\=\[’は‘\[’を出力に、‘\=\=’は‘\=’を出力にそれぞれ入れます。
\+これは、直後の記号を *Help* バッファ内でリンクとしてマークすべきではないことを示しています。
ご注意： Emacs Lisp の文字列内で記述する場合、各 ‘\’ は2回記述する必要があります（文字列の構文を参照してください）。
この関数は 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’."
この関数はsubstitute-command-keysと同様に動作しますが、引用符のみを置換します。
ドキュメント文字列内のテキストには、他にも特別な規約があります。例えば、本マニュアルの関数や変数、セクションを参照することができます。詳細はドキュメント文字列のヒントをご覧ください。