Next: Keys in Documentation, Previous: Documentation Basics, Up: Documentation [Contents][Index]
この関数はプロパティ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のドキュメント文字列をリターンする。この関数はマクロ、名前付きキーボードマクロ、およびスペシャルフォームも通常の関数と同様に処理する。
functionがシンボルならそのシンボルのfunction-documentationプロパティを最初に調べる。それが非nil値をもつなら、その値(プロパティの値が文字列以外ならそれを評価した値)がドキュメントとなる。
functionがシンボル以外、あるいはfunction-documentationプロパティをもたなければ、documentationは必要ならファイルを読み込んで実際の関数定義のドキュメント文字列を抽出する。
最後にverbatimがnilなら、この関数はsubstitute-command-keysを呼び出す。結果はリターンするための文字列。
documentation関数はfunctionが関数定義をもたなければvoid-functionエラーをシグナルする。しかし関数定義がドキュメントをもたない場合は問題ない。その場合はdocumentationはnilをリターンする。
この関数はfaceのドキュメント文字列をフェイスとしてリターンする。
以下は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 (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 …
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* ----------
この関数はEmacsビルド時の実行可能なEmacsダンプ直前に使用される。これはファイルfilename内に格納されたドキュメント文字列の位置を探して、メモリー上の関数定義および変数のプロパティリスト内にそれらの位置を記録する。Building Emacsを参照のこと。
Emacsはemacs/etcディレクトリーからファイルfilenameを読み込む。その後ダンプされたEmacs実行時に、ディレクトリーdoc-directory内の同じファイルを照会する。filenameは通常は"DOC"。
この変数はビルトインおよび事前ロードされた関数と変数のドキュメント文字列を含んだファイル"DOC"があるべきディレクトリーの名前を保持する。
これはほとんどの場合はdata-directoryと同一。実際にインストールしたEmacsではなくEmacsをビルドしたディレクトリーからEmacsを実行したときは異なるかもしれない。Definition of data-directoryを参照のこと。
Next: Keys in Documentation, Previous: Documentation Basics, Up: Documentation [Contents][Index]