23. 説明文

GNU Emacs Lispには、便利なオンラインのヘルプ機能があります。 そのほとんどは、関数や変数に付随した説明文字列から取り出したものです。 本章では、説明文を参照するプログラムの書き方に加えて、 読者のLispプログラムに適切な説明文字列を書く方法を説明します。

Emacsの説明文字列は、Emacsマニュアルと同じものではないことに注意願います。 マニュアルには言語texinfoで書いた独自のソースファイルがありますが、 説明文字列は関数や変数の定義の中で指定されています。 説明文字列を集めても、よいマニュアルとは構成が違いますので、 マニュアルとしては十分ではありません。

23.1 説明文の基本

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

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

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

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

• 関数の説明文は、関数定義自身に収められている （see 節 11.2 ラムダ式）。 関数documentationがその取り出し方を知っている。

• 変数の説明文は、変数の属性リストに 属性名variable-documentationで収められている。 関数documentation-propertyがその取り出し方を知っている。

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

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

説明文字列の利用に関する情報は、 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 節 C.1 Emacsの構築方法。

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

Variable: doc-directory

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

ほとんどの場合、これはdata-directoryと同じである。 Emacsをインストールせずに構築したディレクトリから起動すると、 それらは異なることがある。 23.5 ヘルプ機能の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\
\\\\[abort-recursive-edit].")
=> "To abort a recursive edit from the minibuffer, type C-g."

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

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

Function: key-description sequence

この関数は、sequenceの入力イベントに対する Emacsの標準表記を含んだ文字列を返す。 引数sequenceは、文字列、ベクトル、リストである。 正しいイベントについて詳しくはsee 節 20.5 入力イベント。 下記の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 節 21.1 キーマップの用語。）

23.5 ヘルプ機能

Emacsにはさまざまオンラインヘルプ関数があり、 それらはすべてプレフィックスC-hのサブコマンドとして使えます。 それらについて詳しくは、 GNU Emacs マニュアルを参照してください。 ここでは、同じ情報を得るプログラムレベルのインターフェイスを説明します。

コマンド: apropos regexp &optional do-all

この関数は、正規表現regexpに一致する名前を持つすべてのシンボルを探し、 それらのリストを返す（see 節 33.2 正規表現）。 さらに、バッファ`*Help*'に、各シンボルについて、 シンボルとその説明文字列の始めの部分から取り出した1行の説明文を表示する。

do-allがnil以外であると、 aproposは、みつけた関数に対するキーバインディングも表示する。 さらに、関数や変数以外も含めてすべてのシンボルを表示する。

つぎの例では、aproposは、 `exec'を名前に含むすべてのシンボルを探しだす。 （ここではバッファ`*Help*'の表示は示さない。）

(apropos "exec") => (Buffer-menu-execute command-execute exec-directory exec-path execute-extended-command execute-kbd-macro executing-kbd-macro executing-macro)

Variable: help-map

この変数の値は、ヘルプキーC-hに続く文字向けのローカルキーマップである。

プレフィックスコマンド: help-command

このシンボルは関数ではない。 その関数定義セルは、help-mapとして知られるキーマップを保持している。 `help.el'での定義はつぎのとおりである。

(define-key global-map "\C-h" 'help-command) (fset 'help-command help-map)

Function: print-help-return-message &optional function

この関数は、ヘルプコマンドのあとでそれ以前のウィンドウの状態に復元する 方法を述べた文字列を作成する。 メッセージを作成後、functionがnil以外であれば、 メッセージをfunctionに適用する。 さもなければ、メッセージをエコー領域に表示するためにmessageを呼び出す。

この関数は、スペシャルフォームwith-output-to-temp-bufferの 中から呼び出され、しかも、 当該スペシャルフォームでstandard-outputに値が束縛されているものと 仮定する。 使用例については、23.2 説明文字列の参照の長い例を参照。

Variable: help-char

この変数の値はヘルプ文字、つまり、 Emacsがヘルプを意味すると認識する文字である。 デフォルトでは、その値はC-hを表す8である。 help-formがnil以外のLisp式であると、 Emacsがこの文字を読み取るとその式を評価し、 その結果が文字列であれば結果をウィンドウに表示する。

通常、help-formの値はnilである。 そうすると、ヘルプ文字にはコマンド入力のレベルでは特別な意味はなく、 普通の意味でのキー列の一部になる。 C-hの標準のキーバインディングは、 いくつかの汎用目的のヘルプ機能向けのプレフィックスキーである。

ヘルプ文字は、プレフィックスキーのうしろでも特別である。 プレフィックスのサブコマンドとしてのバインディングがないと、 プレフィックスキーのすべてのサブコマンドの一覧を表示する describe-prefix-bindingsを実行する。

Variable: help-event-list

この変数の値は、別の『ヘルプ文字』として動作するイベント型のリストである。 これらのイベントはhelp-charで指定されたイベントと まったく同様に扱われる。

Variable: help-form

この変数がnil以外であると、その値は、 help-charを読むたびに評価すべきフォームである。 フォームを評価すると文字列を生成すれば、その文字列が表示される。

read-eventやread-charを呼ぶコマンドは、 入力中にはhelp-formをnil以外に（たぶん）束縛すべきである。 （C-hに別の意味がある場合には、こうしないこと。） この式の評価結果は、なんのための入力でどのように入力すべきかを 説明する文字列であること。

ミニバッファに入ると、この変数はminibuffer-help-form （see 節 19.9 ミニバッファに関するその他）の値に束縛される。

Variable: prefix-help-command

この変数はプレフィックスキーに対するヘルプを表示する関数を保持する。 ユーザーがプレフィックスキーに続けてヘルプ文字や 当該プレフィックスのあとではバインディングを持たない文字を打つと その関数が呼ばれる。 この変数のデフォルト値はdescribe-prefix-bindingsである。

Function: describe-prefix-bindings

この関数は、もっとも最近のキー列のプレフィックスキーの すべてのサブコマンドの一覧を表示するためにdescribe-bindingsを呼び出す。 プレフィックスの説明には、当該キー列の最後のイベント以外のすべてが含まれる。 （最後のイベントはヘルプ文字であると仮定する。）

つぎの2つの関数は、『エレクトリック』モードのように 制御を放棄せずにヘルプを提供したいモードのためです。 それらの名前は、普通のヘルプ関数と区別するために`Helper'で始まります。

コマンド: Helper-describe-bindings

このコマンドは、ローカルキーマップとグローバルキーマップの両者の すべてのキーバインディングの一覧を収めたヘルプバッファを表示した ウィンドウをポップアップする。 describe-bindingsを呼び出すことで動作する。

コマンド: Helper-help

このコマンドはカレントモードについてのヘルプを提供する。 ミニバッファにおいて`Help (Type ? for further options)'のメッセージで ユーザーに問い合わせ、キーバインディングの意味やモードの目的を 調べることを補佐する。 nilを返す。

このコマンドは、キーマップHelper-help-mapを 変更することでカスタマイズできる。

Variable: data-directory

この変数は、Emacsとともに配布された特定の説明文やテキストファイルを Emacsが探すためのディレクトリの名前を保持する。 Emacsの古い版では、この目的にはexec-directoryを用いていた。

Macro: make-help-screen fname help-line help-text help-map

このマクロは、サブコマンドの一覧を表示するプレフィックスキーのように 動作するfnameという名前のコマンドのヘルプを定義する。

起動されると、fnameはウィンドウにhelp-textを表示し、 help-mapに従ってキー列を読み実行する。 文字列help-textは、help-mapが提供する バインディングを記述するべきである。

コマンドfnameは、help-textの表示をスクロールすることで、 それ自身では少数のイベントを扱うように定義される。 fnameがそれらの特殊イベントの1つを読み取ると、 スクロールしてつぎのイベントを読み取る。 読み取ったイベントが、扱えるものでなく、 help-mapにバインディングがあれば、 当該キーのバインディングを実行して戻る。

help-lineは、help-map内の選択項目を1行にまとめたものであること。 Emacsの現在の版では、この引数はオプションthree-step-helpをtに 設定してある場合にのみ使われる。

このマクロは、C-h C-hのバインディングである コマンドhelp-for-helpで使われている。

User Option: three-step-help

この変数がnil以外であると、 make-help-screenで定義されたコマンドは、 まず文字列help-lineをエコー領域に表示し、 ユーザーがヘルプ文字を再度打った場合にのみより長い文字列を表示する。