Next: , Previous: Documentation Basics, Up: Documentation


23.2 説明文字列の参照

— Function: documentation-property symbol property &optional verbatim

この関数は、シンボルsymbolの属性リストに 属性propertyで記録されている説明文字列を返す。 必要ならばファイルからテキストを取り出し、 実際のキーバインディングに置き換えるために substitute-command-keysを実行する。 (verbatimnil以外であると、置換を行わない。)

          (documentation-property 'command-line-processed
             'variable-documentation)
               ⇒ "Non-nil once command line has been processed"
          (symbol-plist 'command-line-processed)
               ⇒ (variable-documentation 188902)
— Function: documentation function &optional verbatim

この関数は、関数functionの説明文字列を返す。 必要ならばファイルからテキストを取り出す。 続いて、(verbatimnilならば) 実際の(現在の)キーバインディングを含んだ値を返すために substitute-command-keysを実行する。

関数documentationは、functionに関数定義がないと エラーvoid-functionを通知する。 しかし、関数定義に説明文字列がなくてもエラーではない。 その場合、documentationnilを返す。

2つの関数documentationdocumentation-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)
                 ;; Print description of symbol.
     
                 (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-symbolsaproposのように動作しますが、 より多くの情報を提供します。

     (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* ----------
— Function: Snarf-documentation filename

この関数は、実行可能なEmacsをダンプする直前の Emacsの初期化処理中にのみ使われる。 ファイルfilenameに格納された説明文字列のファイル内位置を探し出し、 それらの情報を実際の文字列のかわりに メモリ内の関数定義や変数の属性リストに記録する。 see Building Emacs

Emacsはファイルfilenameをディレクトリemacs/etcから読む。 ダンプしたEmacsをのちに実行すると、 同じファイルをディレクトリdoc-directoryで探す。 通常、filename"DOC-version"である。

— Variable: doc-directory

この変数は、組み込みであったりあらかじめロード済みの関数や変数の 説明文字列を収めたファイル"DOC-version"を置いた ディレクトリの名前を保持する。

ほとんどの場合、これはdata-directoryと同じである。 Emacsをインストールせずに構築したディレクトリから起動すると、 それらは異なることがある。 Help Functionsdata-directoryを参照。

Emacsの古い版では、この目的にはexec-directoryを用いていた。