Next: , Previous: , Up: Documentation   [Contents][Index]

24.2 ドキュメント文字列へのアクセス

Function: documentation-property symbol property &optional verbatim

この関数はプロパティproperty配下のsymbolのプロパティリスト内に記録されたドキュメント文字列をリターンする。これはほとんどの場合propertyをvariable-documentationにして、変数のドキュメント文字列の照会に使用される。しかしカスタマイゼーショングループのような他の種類のドキュメント照会にも使用できる(が関数のドキュメントには以下のdocumentation関数を使用する)。

そのプロパティの値がDOCファイルやバイトコンパイル済みファイルに格納されたドキュメント文字列を参照する場合、この関数はその文字列を照会してそれをリターンする。

プロパティの値がnilや文字列以外でファイル内のテキストも参照しなければ、文字列を取得するLisp式として評価される。

最終的にこの関数はキーバインディングを置換するために、文字列をsubstitute-command-keysに引き渡す(Keys in Documentationを参照)。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)

(documentation-property 'emacs 'group-documentation)
     ⇒ "Customization of the One True Editor."
Function: documentation function &optional verbatim

この関数はfunctionのドキュメント文字列をリターンする。この関数はマクロ、名前付きキーボードマクロ、およびスペシャルフォームも通常の関数と同様に処理する。

functionがシンボルならそのシンボルのfunction-documentationプロパティを最初に調べる。それが非nil値をもつなら、その値(プロパティの値が文字列以外ならそれを評価した値)がドキュメントとなる。

functionがシンボル以外、あるいはfunction-documentationプロパティをもたなければ、documentationは必要ならファイルを読み込んで実際の関数定義のドキュメント文字列を抽出する。

最後にverbatimがnilなら、この関数はsubstitute-command-keysを呼び出す。結果はリターンするための文字列。

documentation関数はfunctionが関数定義をもたなければvoid-functionエラーをシグナルする。しかし関数定義がドキュメントをもたない場合は問題ない。その場合はdocumentationはnilをリターンする。

Function: face-documentation face

この関数はfaceのドキュメント文字列をフェイスとしてリターンする。

以下は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)

            ;; シンボルの説明をプリントする
            (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 (custom-variable-p s)
                       "Option " "Variable")

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



    ;; PATTERNにマッチするシンボルのリストを構築
    (mapatoms (function
               (lambda (sym)
                 (if (string-match pattern (symbol-name sym))
                     (setq sym-list (cons sym sym-list))))))



    ;; データを表示
    (help-setup-xref (list 'describe-symbols pattern) (interactive-p))
    (with-help-window (help-buffer)
      (mapcar describe-func (sort sym-list 'string<)))))

describe-symbols関数はaproposのように機能しますが、より多くの情報を提供します。 

(describe-symbols "goal")

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



minibuffer-temporary-goal-position      Variable
not documented



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 ARG, 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’.

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



temporary-goal-column   Variable
Current goal column for vertical motion.
It is the column where point was at the start of the current run
of vertical motion commands.

When moving by visual lines via the function ‘line-move-visual’, it is a cons
cell (COL . HSCROLL), where COL is the x-position, in pixels,
divided by the default column width, and HSCROLL is the number of
columns by which window is scrolled from left margin.

When the ‘track-eol’ feature is doing its job, the value is
‘most-positive-fixnum’.
---------- Buffer: *Help* ----------
Function: Snarf-documentation filename

この関数はEmacsビルド時の実行可能なEmacsダンプ直前に使用される。これはファイルfilename内に格納されたドキュメント文字列の位置を探して、メモリー上の関数定義および変数のプロパティリスト内にそれらの位置を記録する。Building Emacsを参照のこと。

Emacsはemacs/etcディレクトリーからファイルfilenameを読み込む。その後ダンプされたEmacs実行時に、ディレクトリーdoc-directory内の同じファイルを照会する。filenameは通常は"DOC"。

Variable: doc-directory

この変数はビルトインおよび事前ロードされた関数と変数のドキュメント文字列を含んだファイル"DOC"があるべきディレクトリーの名前を保持する。

これはほとんどの場合はdata-directoryと同一。実際にインストールしたEmacsではなくEmacsをビルドしたディレクトリーからEmacsを実行したときは異なるかもしれない。Definition of data-directoryを参照のこと。

Next: , Previous: , Up: Documentation   [Contents][Index]