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

Функция: 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)
  "Описать символы Emacs Lisp, соответствующие PATTERN.
Все символы, содержащие PATTERN в своём имени, описываются
в буфере *Help*."
  (interactive "sОпишите символы, соответствующие: ")
  (let ((describe-func
         (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
                             "Клавиши: "
                             (mapconcat 'key-description
                                        keys " "))
                          "Клавиши: нет"))
                    "Функция")

                  (or (documentation s)
                      "не документирована"))))

           (if (boundp s)              ; Это переменная.

               (princ
                (format "%s\t%s\n%s\n\n" s
                  (if (custom-variable-p s)
                      "Параметр " "Переменная")

                  (or (documentation-property
                        s 'variable-documentation)
                      "не документирована"))))))
        sym-list)

    ;; Построить список символов, соответствующих шаблону.
    (mapatoms (lambda (sym)
                (if (string-match pattern (symbol-name sym))
                    (setq sym-list (cons sym sym-list)))))

    ;; Отобразить данные.
    (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")

---------- Буфер: *Help* ----------
goal-column     Параметр
Полупостоянная целевая колонка для вертикального перемещения, задаваемая …

minibuffer-temporary-goal-position      Переменная
не документирована

set-goal-column Клавиши: C-x C-n
Установить текущую горизонтальную позицию как цель для C-n и C-p.

Эти команды будут перемещаться в эту позицию в строке, в которую перешли,
вместо попытки сохранить ту же горизонтальную позицию.
С не-nil аргументом ARG очищает целевую колонку,
так что C-n и C-p возобновляют вертикальное перемещение.
Целевая колонка хранится в переменной ‘goal-column’.

(fn ARG)

temporary-goal-column   Переменная
Текущая целевая колонка для вертикального перемещения.
Это колонка, в которой находилась точка в начале текущего запуска
команд вертикального перемещения.

При перемещении по визуальным строкам с помощью функции ‘line-move-visual’
это ячейка cons (COL . HSCROLL), где COL — это x-позиция в пикселях,
делённая на ширину колонки по умолчанию, а HSCROLL — это количество
колонок, на которое окно прокручено от левого поля.

Когда работает особенность ‘track-eol’, значение равно
‘most-positive-fixnum’.
---------- Буфер: *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.