23. 説明文

[ ? ]

23.1 説明文の基本

説明文字列は, 文字列に対するLisp構文, つまり, 文字列のテキストをダブルクォートで囲って書きます. これは, 説明文字列が実際にはLispの文字列オブジェクトだからです. 関数や変数の定義の正しい箇所に文字列を書くと, 説明文としての役割を果たします. 関数定義においては, 説明文字列は引数のつぎにあります. 変数定義においては, 変数の初期値のつぎにあります.

説明文字列を書くときには, 最初の1行は1つの（あるいは2つの）完全な文にしてください. aproposなどのある種のコマンドは, 複数行にまたがる説明文字列の最初の1行だけを表示するからです. また, 説明文字列の2行目以降を字下げしないでください. 字下げがあると, C-h f（describe-function）や C-h v（describe-variable）で説明文字列を表示すると不恰好になります. See section 説明文字列に関するヒント.

説明文字列には, 特別な部分文字列, つまり, 説明文を表示するときに現在のキーマップからキーバインディングを探すことを表すものがあります. これにより, ユーザーがキーバインディングを変更していても説明文字列から関連するコマンドのキーを参照できます. （see section 説明文字列の参照）.

Emacs Lispでは, 説明文字列はその説明対象である関数や変数を介して参照します.

関数の説明文は, 関数定義自身に収められている（see section ラムダ式）. 関数documentationがその取り出し方を知っている.
変数の説明文は, 変数の属性リストに属性名variable-documentationで収められている. 関数documentation-propertyがその取り出し方を知っている.

場所を節約するために, あらかじめロード済みの関数や変数（基本関数や自動ロード対象の関数を含む）に対する説明文は, Emacs本体にではなく, ファイル‘emacs/etc/DOC-version’に収めてあります. Emacsセッションの最中にバイトコンパイル済みのファイルからロードされる関数や変数の説明文字列は, 当該ファイルに収めてあります（see section 説明文字列とコンパイル）.

Emacs内部のデータ構造では, 説明文字列のかわりに, ファイル内の位置を表す整数かファイル名と整数を含むリストで表します. 関数documentationやdocumentation-propertyは, この情報を用いて適切なファイルから説明文字列を取り出します. この処理はユーザーには見えません.

説明文字列の利用に関する情報は, (emacs-ja)Help section ‘ヘルプ機能’ in GNU Emacs マニュアルを参照してください.

ディレクトリ‘emacs/lib-src’には, ファイル‘emacs/etc/DOC-version’を美しく印刷するためのコマンドが2つあります. ‘sorted-doc’と‘digest-doc’です.

[ < ]

[ > ]

[ << ]

[上]

[ >> ]

[ ? ]

23.2 説明文字列の参照

Function: documentation-property symbol property &optional verbatim

この関数は, シンボルsymbolの属性リストに属性propertyで記録されている説明文字列を返す. 必要ならばファイルからテキストを取り出し, 実際のキーバインディングに置き換えるために substitute-command-keysを実行する. （verbatimがnil以外であると, 置換を行わない. ）

(documentation-property 'command-line-processed
   'variable-documentation)
     ⇒ "Non-nil once command line has been processed"

(symbol-plist 'command-line-processed)
     ⇒ (variable-documentation 188902)

Function: documentation function &optional verbatim

この関数は, 関数functionの説明文字列を返す. 必要ならばファイルからテキストを取り出す. 続いて, （verbatimがnilならば）実際の（現在の）キーバインディングを含んだ値を返すために substitute-command-keysを実行する.

関数documentationは, functionに関数定義がないとエラーvoid-functionを通知する. しかし, 関数定義に説明文字列がなくてもエラーではない. その場合, documentationはnilを返す.

2つの関数documentationとdocumentation-propertyを用いて, 数個のシンボルの説明文字列をバッファ‘*Help*’に表示する例を示します.

(defun describe-symbols (pattern)
  "Describe the Emacs Lisp symbols matching PATTERN.
All symbols that have PATTERN in their name are described
in the `*Help*' buffer."
  (interactive "sDescribe symbols matching: ")
  (let ((describe-func
         (function 
          (lambda (s)

            ;; Print description of symbol.
            (if (fboundp s)             ; これは関数
                (princ
                 (format "%s\t%s\n%s\n\n" s
                   (if (commandp s) 
                       (let ((keys (where-is-internal s)))
                         (if keys
                             (concat
                              "Keys: "
                              (mapconcat 'key-description 
                                         keys " "))
                           "Keys: none"))
                     "Function")

                   (or (documentation s) 
                       "not documented"))))
            
            (if (boundp s)              ; これは変数

                (princ
                 (format "%s\t%s\n%s\n\n" s
                   (if (user-variable-p s) 
                       "Option " "Variable")

                   (or (documentation-property 
                         s 'variable-documentation)
                       "not documented")))))))
        sym-list)

    ;; パターンに一致するシンボルのリストを作る
    (mapatoms (function 
               (lambda (sym)
                 (if (string-match pattern (symbol-name sym))
                     (setq sym-list (cons sym sym-list))))))

    ;; データを表示する
    (with-output-to-temp-buffer "*Help*"
      (mapcar describe-func (sort sym-list 'string<))
      (print-help-return-message))))

関数describe-symbolsはaproposのように動作しますが, より多くの情報を提供します.

(describe-symbols "goal")

---------- Buffer: *Help* ----------
goal-column     Option 
*Semipermanent goal column for vertical motion, as set by …

set-goal-column Keys: C-x C-n
Set the current horizontal position as a goal for C-n and C-p.

Those commands will move to this position in the line moved to
rather than trying to keep the same horizontal position.
With a non-nil argument, clears out the goal column
so that C-n and C-p resume vertical motion.
The goal column is stored in the variable `goal-column'.

temporary-goal-column   Variable
Current goal column for vertical motion.
It is the column where point was
at the start of current run of vertical motion commands.
When the `track-eol' feature is doing its job, the value is 9999.
---------- Buffer: *Help* ----------

Function: Snarf-documentation filename

この関数は, 実行可能なEmacsをダンプする直前の Emacsの初期化処理中にのみ使われる. ファイルfilenameに格納された説明文字列のファイル内位置を探し出し, それらの情報を実際の文字列のかわりにメモリ内の関数定義や変数の属性リストに記録する. see section Emacsの構築方法.

Emacsはファイルfilenameをディレクトリ‘emacs/etc’から読む. ダンプしたEmacsをのちに実行すると, 同じファイルをディレクトリdoc-directoryで探す. 通常, filenameは"DOC-version"である.

Variable: doc-directory

この変数は, 組み込みであったりあらかじめロード済みの関数や変数の説明文字列を収めたファイル"DOC-version"を置いたディレクトリの名前を保持する.

ほとんどの場合, これはdata-directoryと同じである. Emacsをインストールせずに構築したディレクトリから起動すると, それらは異なることがある. ヘルプ機能のdata-directoryを参照.

Emacsの古い版では, この目的にはexec-directoryを用いていた.

[ < ]

[ > ]

[ << ]

[上]

[ >> ]

[ ? ]

23.3 説明文内のキーバインディングの置換

説明文字列からキー列を参照するときには, 現在の活性なキーバインディングを使うべきです. これは以下に述べる特別なテキスト列でできます. 普通の方法で説明文字列を参照すると, これらの特別な列は現在のキーバインディング情報で置き換えられます. 置き換えはsubstitute-command-keysを呼び出して行います. 読者自身がこの関数を使うこともできます.

特別な列とその意味を以下にあげます.

\[command]: コマンドcommandを起動するキー列を表す. commandにキーバインディングがなければ, ‘M-x command’を表す.
\{mapvar}: 変数mapvarの値であるキーマップの概要を表す. この概要はdescribe-bindingsを使って作成する.
\<mapvar>: 空テキストを表す. 副作用のためだけに使う. つまり, この説明文字列内のこれ以降にある列‘\[command]’に対するキーマップとしてmapvarの値を指定する.
\=: 後続の文字をクォートし‘\=’は破棄する. したがって, ‘\=\[’は‘\[’という出力になり, ‘\=\=’は‘\=’という出力になる.

注意： Emacs Lispでは, 文字列内の‘\’は, 2つ続けて書くこと.

Function: substitute-command-keys string: この関数は, stringから上記の特別な列を探し, それらをそれらが意味するものに置き換え, 結果を文字列で返す. これにより, 説明文の表示では, ユーザー独自のカスタマイズしたキーバインディングを実際に参照できる.

特別な列の例を示します.

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

[ < ]

[ > ]

[ << ]

[上]

[ >> ]

[ ? ]

23.4 ヘルプメッセージ用の文字変換

これらの関数は, イベント, キー列, 文字をテキスト表記に変換します. これらの表記は, メッセージに文字やキー列をテキストとして含めるのに有用です. というのは, 非印字文字や白文字を印字文字の列に変換するからです. 白文字でない印字文字は文字そのもので表記します.

Function: key-description sequence: この関数は, sequenceの入力イベントに対する Emacsの標準表記を含んだ文字列を返す. 引数sequenceは, 文字列, ベクトル, リストである. 正しいイベントについて詳しくはsee section 入力イベント. 下記のsingle-key-descriptionの例を参照.

Function: single-key-description event

この関数は, eventをキーボード入力向けのEmacsの標準表記で表した文字列を返す. 普通の印字文字はそのまま現れるが, コントロール文字は‘C-’で始まる文字列に, メタ文字は‘M-’で始まる文字列に, 空白, タブなどは, ‘SPC’, ‘TAB’などとなる. ファンクションキーのシンボルはそれ自身が現れる. リストであるイベントはリストのCARのシンボルの名前が現れる.

(single-key-description ?\C-x)
     ⇒ "C-x"

(key-description "\C-x \M-y \n \t \r \f123")
     ⇒ "C-x SPC M-y SPC C-j SPC TAB SPC RET SPC C-l 1 2 3"

(single-key-description 'C-mouse-1)
     ⇒ "C-mouse-1"

Function: text-char-description character

この関数は, characterをテキストに現れる文字向けのEmacsの標準表記で表した文字列を返す. single-key-descriptionに似ているが, コントロール文字は, 始めにカレットを付けて表現する点が異なる（Emacsのバッファでは, コントロールは普通このように表示される）.

(text-char-description ?\C-c)
     ⇒ "^C"

(text-char-description ?\M-m)
     ⇒ "M-m"

(text-char-description ?\C-\M-m)
     ⇒ "M-^M"

Function: read-kbd-macro string: この関数は, キーボードマクロの処理に主に使われるが, key-descriptionに対するおおまかな逆変換にも使える. 空白で区切ったキーの表記を収めた文字列で, この関数を呼び出す. 対応するイベントを収めた文字列かベクトルを返す. （指定したイベントに依存して, 正しい単一のキー列であったりなかったりする. see section キーマップの用語. ）

[ << ]

[ >> ]