GNU Info
(elisp)Accessing Documentation
Access to Documentation Strings
===============================
- Function: documentation-property symbol property &optional verbatim
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 through
`substitute-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)
- Function: documentation function &optional verbatim
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 no `function-documentation' property, then
`documentation' extracts the documentation string from the actual
function definition, reading it from a file if called for.
Finally, unless VERBATIM is non-`nil', it calls
`substitute-command-keys' so as to return a value containing the
actual (current) key bindings.
The function `documentation' signals a `void-function' error if
FUNCTION has no function definition. However, it is OK if the
function definition has no documentation string. In that case,
`documentation' returns `nil'.
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 Note: Defining Variables.
- Function: Snarf-documentation filename
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. Note: 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"'.
- Variable: doc-directory
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. See `data-directory' in Note:
Help Functions.
In older Emacs versions, `exec-directory' was used for this.
automatically generated by info2www version 1.2.2.9