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ではなく、EmacswpeyビルドしたディレクトリーからEmacsを実行したときは、異なるかもしれない。Definition of data-directoryを参照のこと。
Next: Keys in Documentation, Previous: Documentation Basics, Up: Documentation [Contents][Index]