Next: Keys in Documentation, Previous: Documentation Basics, Up: Documentation
This function returns the documentation string that is recorded in symbol's property list under property property. It retrieves the text from a file if the value calls for that. If the property value isn't
nil
, isn't a string, and doesn't refer to text in a file, then it is evaluated to obtain a string.Finally,
documentation-property
passes the string throughsubstitute-command-keys
to substitute actual key bindings, unless verbatim is non-nil
.(documentation-property 'command-line-processed 'variable-documentation) => "Non-nil once command line has been processed" (symbol-plist 'command-line-processed) => (variable-documentation 188902)
This function returns the documentation string of function.
If function is a symbol, this function first looks for the
function-documentation
property of that symbol; if that has a non-nil
value, the documentation comes from that value (if the value is not a string, it is evaluated). If function is not a symbol, or if it has nofunction-documentation
property, thendocumentation
extracts the documentation string from the actual function definition, reading it from a file if called for.Finally, unless verbatim is non-
nil
, it callssubstitute-command-keys
so as to return a value containing the actual (current) key bindings.The function
documentation
signals avoid-function
error if function has no function definition. However, it is OK if the function definition has no documentation string. In that case,documentation
returnsnil
.
Here is an example of using the two functions, documentation
and
documentation-property
, to display the documentation strings for
several symbols in a ‘*Help*’ buffer.
(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) ; 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 (user-variable-p s) "Option " "Variable") (or (documentation-property s 'variable-documentation) "not documented"))))))) sym-list) ;; Build a list of symbols that match pattern. (mapatoms (function (lambda (sym) (if (string-match pattern (symbol-name sym)) (setq sym-list (cons sym sym-list)))))) ;; Display the data. (with-output-to-temp-buffer "*Help*" (mapcar describe-func (sort sym-list 'string<)) (print-help-return-message))))
The describe-symbols
function works like apropos
,
but provides more information.
(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* ----------
The asterisk ‘*’ as the first character of a variable's doc string,
as shown above for the goal-column
variable, means that it is a
user option; see the description of defvar
in Defining Variables.
This function is used only during Emacs initialization, just before the runnable Emacs is dumped. It finds the file offsets of the documentation strings stored in the file filename, and records them in the in-core function definitions and variable property lists in place of the actual strings. See Building Emacs.
Emacs reads the file filename from the emacs/etc directory. When the dumped Emacs is later executed, the same file will be looked for in the directory
doc-directory
. Usually filename is"DOC-
version"
.
This variable holds the name of the directory which should contain the file
"DOC-
version"
that contains documentation strings for built-in and preloaded functions and variables.In most cases, this is the same as
data-directory
. They may be different when you run Emacs from the directory where you built it, without actually installing it. Seedata-directory
in Help Functions.In older Emacs versions,
exec-directory
was used for this.