ドキュメンテーション

GNU Emacs Lisp は、ユーザーに対し関数や変数のドキュメンテーションストリングを 表示する(簡単な)機能を持っています。

Emacs Lisp で定義された関数に対し、それに対するドキュメンテーションストリング はその関数の関数定義にストアされます (セクション 10.1 [ラムダ式]、ページ 84 参 照)。関数 documentation はその取り出し方を知っています。

Emacs Lisp で定義されたグローバル変数 (でプリロードされていないもの - 以下参 照) に対し、それに対するドキュメンテーションストリングはそのプロパティーリスト 中の variable-documentation というプロパティー名の下にストアされます。関数 documentation-property はその取り出し方を知っています。

ダンプされ Emacs にプリロードされた (primitive 関数やオートロードされた関数を 含む)変数や関数に関しては、それらに対するドキュメンテーションストリングは (上 記の 2つの関数がそれへのアクセス方法を知っている)ファイル (`etc/DOC') に入れら れます。この場合、シンボルに対するプロパティー vatiable-documentation は `etc/DOC' ファイル中への integer オフセットになります。ドキュメンテーションス トリングを Emacs のコアイメージの外に持つことでかなりの量のスペースを省いてい ます。

ドキュメンテーションストリングは、いくつか特別なサブストリングを含むことがあり ます。このサブストリングにより、ある関数で実際の(カレントな)キーバインディング を求め、それをそのストリングの中に入れることが可能になります (チャプター 21 [substitute-command-keys]、ページ 195 参照)。

Function: documentation-property symbol property

この関数は、 symbol の property であるドキュメンテーションストリングを返し ます。`etc/DOC' ファイルにストアされたドキュメンテーションストリングをアク セスすることのできる点と、結果のストリングに対し substitute-command-keys

を走らせることのできる点で、 get を用いるのとは異なっています。

  (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

この関数は、 function のドキュメンテーションストリングを返します。 function が primitive の場合、このストリングは `etc/DOC' ファイルで探され ます。

(ドキュメンテーションストリングを持つ必要はありませんが) function が関数定 義を持たない場合、エラーになります。ドキュメンテーションストリングが存在し ない場合 nil を返します。

以下にいくつかの関数のドキュメンテーションストリングを (documentation を用 いて) *Help* バッファに表示する関数を示します。

  (defun describe-functions (s)
    "Display the documentation of the currently active GNU functions
  that have PREFIX as a prefix of their name in the *Help* buffer."
    (interactive "slead characters: ")
    (with-output-to-temp-buffer "*Help*"
        (mapcar '(lambda (f)
   (prin1 f) (princ ":\n")
   (princ (or (documentation f) "not documented"))
   (princ "\n\n"))
        (sort (mapcar 'intern (all-completions s obarray 'fboundp))
      'string<))
        (pirnt-help-return-mesage)
        ))

(もっと良い例を見つける!!)

  (documentation 'bar)
  => nil

  (documentation 'rnews) > "
  Read USENET news for groups for which you are a member (one can add or
  delete groups. You can replay to articles posted and send articles to any
  group.

  Type C-f m once reading news to get a list of rnews commands."

  (documentation 'car)
  => "Return the car of CONSCELL. If arg is nil, return nil."

  (symbol-function 'car)
  => #<subr car>

Function: Snarf-documentation filename

この関数は、Emacs の初期化 (走行可能な Emacs をダンプする前) でのみ用いま す。これは、ファイル filename にストアされたドキュメンテーションストリング へのポインタを見つけ、それを in-core 関数定義のドキュメンテーションストリ ングの場所に記録します。 filename は `../etc' で探します(通常 filename は "DOC" です)。 Emacs がダンプされ、(その後)実行されると、参照されたドキュメ ンテーションストリングは exec-directory で見つかります。

Function: substitute-command-keys string

この関数は、カレントなキーバインディングに関する情報を含むようドキュメン テーションメッセージを変更し、 string を返します (キーバインディングは Emacs が作られた時からこのドキュメントが要求される時までの間に変更されてい ることがあります)。

以下に、substitute-command-keys で認識される特別なサブストリングと、それが

置き換えられるもののリストを示します。

\[command]

  command を起動するキーストロークシーケンスか ( command がキーシー
  ケンスにバインドされていない場合) M-x command で置き換えられます。
  \{mapvar}
  (キーマップとして見られた) mapvar の値のサマリ(訳注：要約)
  (describe-bindings により作られたもの) で置き換えられます。
  \<mapvar>
  substitute-command-keys が、 (以後の \[command] サブストリングにお
  いて) mapvar の値を(その)キーマップとして用いるようにします。

  (substitute-command-keys
     "To abort recursive edit, type: \\[abort-recursive-edit]")
  => "To abort recursive edit, type: C-]"

  (substitute-command-keys
     "The keys which are defined for the minibuffer here are:
    \\{minibuffer-local-must-match-map}")

  => "The keys which 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 recursive edit from the minibuffer, type
     \\<minibuffer-local-must-match-map>\\[abort-recursive-edit]")
  =>  "To abort recursive edit from the minibuffer, type
     C-g"

Command: apropos regexp &optional predicate noprint

この関数は、 (その名前に)正規表現 regexp にマッチする部分を持つ (全ての)シ ンボルを探し、そのリストを返します。 (通常) `*Help*' バッファを持つウィン ドウをポップアップし、そのシンボルと (訳注：それに対する) 1 行の記述とを表 示します。 noprint が non-nil の場合、表示は行なわずリストのみを返します。

インタラクティブに呼ばれた場合、 regexp を求め(ミニバッファに)プロンプトを 出します。

最初の例では、exec にマッチするもの(全て)を探します。表示は行ないません。 2 番目の例では、コマンドでもあるもののみをリストし、`*Help*' バッファに表 示します。

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

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

  ---------- Buffer: *Help* ----------
  Buffer-menu-execute
    Function: Save and/or delete buffers marked with M-x Buffer-menu-
  save or M-x Buffer-menu-delete commands.
  execute-extended-command      ESC x
    Function: Read function name, then read its arguments and call it.
  ---------- Buffer: *Help* ----------

Function: key-description string

この関数は、 string 中の文字を Emacs 標準記法で print するストリングを返し ます。 single-key-description に対する例を参照して下さい。

Function: single-key-description character

この関数は、 char をEmacs 標準記法で print するストリングを返します。通常 の printing 文字は変更せず、control 文字は `C-' で始まるストリングに、メタ 文字は `M-' で始まるストリングに、スペースやラインフィード等は SPC, LFD 等 に変更します。

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

Function: text-char-description character

この関数は、 character を print するストリングを返します。これは、control 文字を ^ (訳注：caret) で示す点を除いて single-key-description に似ていま す。

  (text-char-description ?\C-c)
  => "^C"
  (text-char-description ?\M-m)
  => "M-m"
  (text-char-description ?\C-\M-m)
  => "M-^M"