Доступ к строкам документации

Функция: documentation-property symbol property &optional verbatim

Эта функция возвращает строку документации, записанную в списке свойств symbol под свойством property. Чаще всего она используется для поиска строк документации переменных, для которых property — variable-documentation. Однако её также можно использовать для поиска других видов документации, например документации групп настройки (для документации функций используйте функцию documentation ниже).

Если значение свойства указывает на строку документации, хранящуюся в файле DOC или в байт-компилированном файле, эта функция находит и возвращает эту строку.

Если значение свойства не является nil, не является строкой и не указывает на текст в файле, оно вычисляется как выражение Lisp для получения строки.

Наконец, эта функция передаёт строку в substitute-command-keys для подстановки привязок клавиш (см. Подстановка привязок клавиш в документации). Этот шаг пропускается, если 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."

Функция: documentation function &optional verbatim

Эта функция возвращает строку документации function. Она обрабатывает макросы, именованные клавиатурные макросы и специальные формы, а также обычные функции.

Если function — символ, эта функция сначала ищет у него свойство function-documentation; если его значение не равно nil, документация берётся из этого значения (если значение не является строкой, оно вычисляется).

Если function не является символом или у него нет свойства function-documentation, documentation извлекает строку документации из фактического определения функции, при необходимости считывая её из файла.

Наконец, если verbatim не равно nil, эта функция вызывает substitute-command-keys. Результатом является возвращаемая строка документации.

Функция documentation сигнализирует об ошибке void-function, если для function нет определения функции. Однако допустимо, чтобы определение функции не содержало строки документации. В этом случае documentation возвращает nil.

Функция: function-documentation function

Обобщённая функция, используемая documentation для извлечения исходной строки документации из объекта функции. Чтобы указать, как получать строку документации для определённого типа функции, добавьте к ней соответствующий метод.

Функция: 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
         (lambda (s)

           ;; Print description of symbol.
           (if (fboundp s)             ; It is a function.
               (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)              ; It is a variable.

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

    ;; Build a list of symbols that match pattern.
    (mapatoms (lambda (sym)
                (if (string-match pattern (symbol-name sym))
                    (setq sym-list (cons sym sym-list)))))

    ;; Display the data.
    (help-setup-xref (list 'describe-symbols pattern)
                 (called-interactively-p 'interactive))
    (with-help-window (help-buffer)
      (mapcar describe-func (sort sym-list)))))

Функция 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'.

(fn ARG)

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* ----------

Функция: Snarf-documentation filename

Эта функция используется при сборке Emacs, непосредственно перед созданием дампа исполняемого Emacs. Она находит позиции строк документации, хранящихся в файле filename, и записывает эти позиции в память — в определения функций и списки свойств переменных. См. Сборка Emacs.

Emacs считывает файл filename из каталога emacs/etc. Когда созданный дамп Emacs впоследствии запускается, тот же файл ищется в каталоге doc-directory. Обычно filename — "DOC".

Переменная: doc-directory

Эта переменная содержит имя каталога, в котором должен находиться файл "DOC" со строками документации встроенных функций и переменных.

В большинстве случаев это то же значение, что и data-directory. Они могут различаться, если вы запускаете Emacs из каталога, в котором его собрали, не устанавливая его. См. Определение data-directory.