説明文字列は、文字列に対するLisp構文、 つまり、文字列のテキストをダブルクォートで囲って書きます。 これは、説明文字列が実際にはLispの文字列オブジェクトだからです。 関数や変数の定義の正しい箇所に文字列を書くと、 説明文としての役割を果たします。 関数定義においては、説明文字列は引数のつぎにあります。 変数定義においては、変数の初期値のつぎにあります。
説明文字列を書くときには、
最初の1行は1つの(あるいは2つの)完全な文にしてください。
apropos
などのある種のコマンドは、
複数行にまたがる説明文字列の最初の1行だけを表示するからです。
また、説明文字列の2行目以降を字下げしないでください。
字下げがあると、
C-h f(describe-function
)や
C-h v(describe-variable
)で説明文字列を表示すると
不恰好になります。
See Documentation Tips。
説明文字列には、特別な部分文字列、つまり、 説明文を表示するときに現在のキーマップからキーバインディングを探す ことを表すものがあります。 これにより、ユーザーがキーバインディングを変更していても 説明文字列から関連するコマンドのキーを参照できます。 (see Accessing Documentation)。
Emacs Lispでは、説明文字列はその説明対象である関数や変数を介して参照します。
documentation
がその取り出し方を知っている。
variable-documentation
で収められている。
関数documentation-property
がその取り出し方を知っている。
場所を節約するために、あらかじめロード済みの関数や変数 (基本関数や自動ロード対象の関数を含む)に対する説明文は、 Emacs本体にではなく、ファイルemacs/etc/DOC-versionに 収めてあります。 Emacsセッションの最中にバイトコンパイル済みのファイルから ロードされる関数や変数の説明文字列は、当該ファイルに収めてあります (see Docs and Compilation)。
Emacs内部のデータ構造では、説明文字列のかわりに、
ファイル内の位置を表す整数かファイル名と整数を含むリストで表します。
関数documentation
やdocumentation-property
は、
この情報を用いて適切なファイルから説明文字列を取り出します。
この処理はユーザーには見えません。
説明文字列の利用に関する情報は、 ヘルプ機能を参照してください。
ディレクトリemacs/lib-srcには、 ファイルemacs/etc/DOC-versionを美しく印刷するための コマンドが2つあります。 sorted-docとdigest-docです。