ヘルプ

GNU Emacs Lispは、便利なオンラインヘルプ機能を備えています。ヘルプ機 能で使用される情報は、ほとんどの場合、関数または変数に付属している説明文字 列から得られます。この章では、Lispプログラムに適切な説明文字列を書く方法、 説明文字列にアクセスするプログラムを書く方法について説明します。

Emacsの説明文字列は、Emacsのマニュアルと同じものではないことに注意し てください。マニュアルは、それ自身のソース・ファイルを持っており、 Texinfo言語で記述されています。説明文字列は、対応する関数または変数の定 義の中で指定されます。説明文字列を集めてもマニュアルとしては不十分です。 なぜなら、よいマニュアルは、説明文字列とは異なり、トピックごとに構成され ているものだからです。

説明文字列の基礎

説明文字列は文字列に対するLispの文法に従い、テキストの両端を二重引 用符で括って記述します。説明文字列もLispの文字列オブジェクトの一種で あるからです。関数または変数の定義の際に、適切な位置に文字列を書き込む ことで、説明文字列となります。関数の定義では、説明文字列は、引数リスト の次に置かれます。変数の定義の場合は、変数の初期値の後に説明文字列を記述 します。

説明文字列を書く際には、最初の一行で最初の一文が終わるようにします(二 つの文を含むのはかまいません)。これは、aproposコマンドなど、複数行に わたる説明文字列のうち最初の一行しか表示しないコマンドがあるためです。ま た説明文字列の２行目は、字下げしないようにします。こちらは、C-h f (describe-function)やC-h v (describe-variable)の 出力がおかしくならないようにするためです。

説明文字列には、表示された時点でのキーマップに対応したキー割り当てを表 す数種類の特殊文字列が使用できます。これらの特殊文字列を使うことにより、 ユーザがキー割り当てを変更していても、説明文字列が正しいキーを示すように できます。(See section 説明文字列へのアクセス.)

Lispの中では、説明文字列は、関数または変数からアクセスでき、以下のよう に扱われます。

• 関数の説明文字列は、定義した関数そのものの中に格納されます (see section ラムダ式)。documentation関数によって、説明文 字列を取り出すことができます。
• 変数の説明文字列は、変数の属性リストの中に、 variable-documentationという属性名で格納されます。 documentation-property関数によって、説明文字列を取り出すことがで きます。

スペースを節約するため、あらかじめロードされる関数と変数(プリミティブ 変数や、オートロードされる変数も含みます)の説明文字列は、 `emacs/etc/DOC-version'ファイルに格納されます。Emacsセッショ ン中にバイトコンパイルされたファイルから読み込まれた関数と変数の説明文 字列もバイトコンパイルされたファイルに格納されています(see section 説明文字列とコンパイル)。

Emacs内部のデータ構造には、説明文字列の代わりに、ファイルへ格納する場合 の整数オフセットまたは文字列と整数を含むリストが含まれます。 documentationとdocumentation-propertyはそのような情報を 使用して、適切なファイルから説明文字列を読み込みます。これはユーザに対し ては透過です。

説明文字列の使用方法については、section `Help' in The GNU Emacs Manualを参照してください。

`emacs/lib-src'ディレクトリには、`emacs/etc/DOC-version' を美しくプリントアウトするために、`sorted-doc.c'と`digest-doc.c' の二つのユーティリティがあります。

説明文字列へのアクセス

Function: documentation-property symbol property &optional verbatim

この関数は、symbolの属性リストにproperty属性で記録されている 説明文字列を返します。必要に応じ、文字列はファイルから読み込まれることも あります。現行のキー・バインドを反映するために、 substitute-command-keysを実行し、特殊文字の置換を行います (verbatimが非nilに設定されている場合、キー・バインドの置換は 行われません。verbatimは、Emacs 19の場合にのみ存在します)。

(documentation-property 'command-line-processed
   'variable-documentation)
     => "t once command line has been processed"
(symbol-plist 'command-line-processed)
     => (variable-documentation 188902)

Function: documentation function &optional verbatim

この関数は、functionの説明文字列を返します。必要に応じ、文字列は ファイルから読み込まれることもあります。(verbatiomが非nilに設 定されている場合をのぞき)現行のキー・バインドを反映するために、 substitute-command-keysを実行します。

functionに関数の定義がない場合、documentationは void-functionエラーを通知します。ただし、指定された関数に説明文字 列が含まれない場合はこれは正常な動作です。この場合documentationは nilを返します。

documentationとdocumentation-propertyの２つの関数を使い、 いくつかのシンボルの説明文字列を`*Help*'バッファに表示する例を、以 下に示します。

(defun describe-symbols (pattern)
  "PATTERNに一致したEmacs Lispシンボルの説明文字列を表示します。
名前にPATTERNを含むすべてのシンボルは、`*Help*'バッファ内に、説明
文字列が表示されます。"
  (interactive "sDescribe symbols matching: ")
  (let ((describe-func
         (function 
          (lambda (s)
            ;; シンボルの説明を印字する。
            (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 C-x C-n, or nil.

set-goal-column Command: 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に含まれる説明文字列のファイル オフセットを探し、実際の文字列の代わりに内部の関数定義および変数属性リス トに記録します。

Emacsは、filenameファイルを`emacs/etc'ディレクトリで検索しま す。後にダンプされたEmacsが実行されると、同じファイルは、 doc-directoryディレクトリで見つかります。通常filenameは、 "DOC-version"です。

Variable: doc-directory

この変数は、組み込み関数と変数、プリロードされた関数と変数の説明文字列を 含む"DOC-version"ファイルが存在するディレクトリの名前を保 持します。

ほとんどの場合、この変数の内容はdata-directoryと同一です。Emacs を実際にインストールせずに、構築したディレクトリで実行しようとした場合は、 異なることがあります。section ヘルプ関数のdata-directoryを参 照してください。

古いバージョンのEmacsでは、exec-directoryがこの用途に使われていま した。

説明文字列でのキー・バインドの置換

説明文字列がキー・シーケンスを参照する場合、現在の実際に使用されているキー ・バインドを使用する必要があります。これを行うには、以下のような特殊なテキ スト・シーケンスを用います。通常の方法で説明文字列をアクセスすると、これら のシーケンスは、現行のキー・バインド情報で置き換えられます。これは、 substitute-command-keysを呼ぶことにより行われます。この関数は、明 示的に呼ぶこともできます。

以下に特殊シーケンスとその意味のリストを示します。

\[command]

commandを起動するキー・シーケンスを表します。commandにキー・ シーケンスが割り当てられていない場合は、`M-x command'となり ます。

\{mapvar}

mapvarの値のサマリを表します。mapvarはキーマップでなければな りません。サマリは、describe-bindingsで作成されます。

\<mapvar>

直接テキストは表しません。副作用として、説明文字列であとに続く `\[command]'シーケンスのキーマップとしてmapvarを指定し ます。

注意: `\'はEmacs Lisp内に記述する場合、それぞれ二つ重ね て書く必要があります。

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

ヘルプ・メッセージでの文字の表現

この関数は、イベント、キー・シーケンス、キー文字を文字列での表現に変換 します。非印字文字や空白文字を通常の印字文字での表現に変換するため、任 意のテキスト文字、キー・シーケンスをメッセージ内で使う場合に有用です。 非印字文字や空白文字以外の通常の文字の表現は、その文字自身となります。

Function: key-description sequence

この関数は、sequenceに含まれる入力イベントのEmacs標準表記を含む 文字列を返します。引数のsequenceには、文字列、ベクタ、リストを 指定できます。有効なイベントについては、See section 入力イベントを参照してく ださい。また以下のsingle-key-descriptionの例も参照してください。

Function: single-key-description event

この関数は、キーボード入力のEmacs標準表記の中のeventを説明する文 字列を返します。通常の印字可能文字は文字自身、制御文字は`C-'で始 まる文字列、メタ文字は`M-'で始まる文字列、スペース、改行などはそれ ぞれ、`SPC'、`LFD'のように表されます。関数キー・シンボルは、その まま表示されます。リストであるイベントは、リストのCARの中のシンボルの 名前として表示されます。

(single-key-description ?\C-x)
     => "C-x"
(key-description "\C-x \M-y \n \t \r \f123")
     => "C-x SPC M-y SPC LFD SPC TAB SPC RET SPC C-l 1 2 3"
(single-key-description 'C-mouse-1)
     => "C-mouse-1"

Function: text-char-description character

この関数は、テキストに現れる文字列のEmacs標準表記の中で characterを示す文字列を返します。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"

ヘルプ関数

Emacsは、いろいろなオンライン・ヘルプ機能を提供しており、ユーザはそ のすべての機能を、C-h前置キーのサブコマンドとして使用でき ます。詳しくは、section `Help' in The GNU Emacs Manualを参照 してください。ここでは、これらの情報へのプログラムレベルでのインタフェー スについて説明します。

Command: apropos regexp &optional do-all predicate

この関数は、正規表現regexpに一致するシンボル名を全て検索し、そ のリストを返します(see section 正規表現)。また、`*Help*'とい う名前のバッファ内にそのシンボルを一行の説明とともに表示します。

do-allが非nilの場合は、aproposは検索された関数のキー バインドも表示します。

predicateが非nilの場合、regexpに一致したシンボルに 対して、この変数に設定された関数が呼ばれます。このとき、predicateが非 nil値を返したシンボルのみがリストまたは表示されます。

以下の例のうち最初のものでは、aproposは`exec'を含む名前を持 つ全てのシンボルを検索します。2番目の例では、コマンドであるシンボルのみ を検索し返します(`*Help*'バッファに表示される結果は示していません)。

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

(apropos "exec" nil 'commandp)
     => (Buffer-menu-execute execute-extended-command)

C-h a(command-apropos)コマンドは、aproposを呼び出し ます。ただしpredicateを指定して、コマンドであるシンボルのみを出力 します。aproposの呼び出しは、以下のようになります。

(apropos string t 'commandp)

Command: super-apropos regexp &optional do-all

この関数はaproposと似た動作をしますが、regexpに一致するシ ンボル名以外に説明文字列も検索する点で異なります。デフォルトでは、プリロー ドされた関数と変数の説明文字列のみを検索します。do-allが非 nilに設定されている場合は、すべての関数と変数の名前と説明文字列を 検索します。

Variable: help-map

この変数の値は、ヘルプ・キー(C-h)に続く文字のローカル・キー・マッ プです。

Prefix Command: 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 の場合、メッセージを作成した後、メッセージに対して指定された関数を使用し ます。nilの場合は、messageを呼び出してメッセージをエコー領 域に表示します。

この関数は、with-output-to-temp-buffer特殊フォーム内で使用され、 standard-outputは、この特殊フォームで指定された値をもつことを前提 としています。使用方法については、section 説明文字列へのアクセスの中の長 い例を参照してください。

Variable: help-char

この変数は、ヘルプ文字の値を示します。ヘルプ文字は、Emacsがヘルプと認 識する文字で、デフォルトでは8、すなわちC-hとなっています。 Emacsがこの文字を読み込むと、help-formが非nilなLisp式に 設定されている場合、式を評価し、結果が文字列の場合はそれを表示します。

通常は、help-formの値は、nilです。そのためヘルプ文字は、コ マンド入力レベルでは何ら特殊な意味を持たず、通常のキー・シーケンスの一部 となります。C-hは、標準のキー・バインドでは、いくつかの汎用ヘルプ機能 の前置キーに割り当てられています。

ヘルプ文字は、前置キーの後でも特殊文字として扱われます。プレフィッ クス・キーのサブコマンドにバインドされていない場合は、 describe-prefix-bidingsを実行し、サブコマンドのリストを表示します。

Variable: help-form

この変数が非nilの場合、設定された値は、help-char文字が読み 込まれるたびに評価に使用されるフォームとして使われます。フォームの評価に より文字列が得られる場合は、その文字列が表示されます。

read-eventまたはread-charを呼び出すコマンドは、入力を行う 場合、おそらくhelp-formを非nilに束縛する必要があります (C-hが意味のある入力の場合は例外です)。この式を評価した結果は、入 力の目的、入力の方法などを適切に説明した文字列とならなければなりません。

ミニバッファへ入ると、この変数はminibuffer-help-formの値に束縛 されます(see section ミニバッファそのほか)。

Variable: prefix-help-command

この変数は、前置文字のヘルプを表示する関数を保持します。ユーザが前置文字 に続いてヘルプ文字を入力した場合、その前置文字のヘルプ文字がバインドされ ていなければ、この関数が呼ばれます。この変数のデフォルト値は、 describe-prefix-bindingsです。

Function: describe-prefix-bindings

この関数は、describe-bindingsを呼び出し、最新のキー・シーケンスの 前置キーの全てのサブコマンドのリストを表示します。記述される 前置キーは、キー・シーケンスの最終のイベントを除くすべてのイベント となります。(通常、最後のイベントはヘルプ文字です)。

以下の２つの関数は、`helper'ライブラリに含まれます。これらの関数 は、"electric"モードなど、そのモード内でヘルプを提供するようなモードの ためにあります。使用する場合は、(require 'helper)を使用してライブ ラリをロードする必要があります。これらの関数は、通常のヘルプ関数と異なり、 関数名が`Helper'から始まります。

Command: Helper-describe-bindings

このコマンドはウィンドウをポップアップし、ローカルおよびグローバルキーマッ プのすべてのキー・バインドのリストを含むヘルプ・バッファを表示します。この関 数は、describe-bindingsを呼び出して動作します。

Command: 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 が、それらの特殊イベントの一つを読み込むと、スクロールを行ってから、次の イベントを読み込みます。help-mapの中にバインドがあるいくつかのイベ ント以外のイベントを読み込んだ場合は、そのキーにバインドされたコマンドを 実行し、返ります。

help-line引数は、help-mapの中の代替の一行サマリでなければな りません。現行のバージョンのEmacsでは、この引数は、 three-step-helpオプションがtに設定されている場合にのみ使用 されます。

User Option: three-step-help

この変数が非nilの場合、make-help-screenと共に定義されたコ マンドは、help-line文字列をまずエコー領域に表示し、続けてヘルプ文 字がタイプされた場合にのみ、長いhelp-text文字列を表示します。

Go to the first, previous, next, last section, table of contents.