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

Функция: documentation-property символ свойство &необязательно verbatim

Эта функция возвращает строку документации, записанную в списке свойств символ под свойством свойство. Чаще всего она используется для поиска строк документации переменных, для которых свойство является 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 функция &необязательно verbatim

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

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

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

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

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

Функция: face-documentation стиль

Эта функция возвращает строку документации стиля как стиль.

Вот пример использования двух функций, 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 'string<)))))

Функция 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 имя_файла

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

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

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

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

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