@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/help
@node Documentation, Files, Modes, Top
@c Wordy to prevent overfull hbox. --rjc 15mar92
The @file{emacs/lib-src} directory contains two utilities that you can
use to print nice-looking hardcopy for the file
-@file{emacs/etc/DOC-@var{version}}. These are @file{sorted-doc.c} and
-@file{digest-doc.c}.
+@file{emacs/etc/DOC-@var{version}}. These are @file{sorted-doc} and
+@file{digest-doc}.
@node Accessing Documentation
@section Access to Documentation Strings
@defun documentation-property symbol property &optional verbatim
-This function returns the documentation string that is recorded
+This function returns the documentation string that is recorded in
@var{symbol}'s property list under property @var{property}. It
-retrieves the text from a file if necessary, and runs
-@code{substitute-command-keys} to substitute actual key bindings. (This
-substitution is not done if @var{verbatim} is non-@code{nil}.)
+retrieves the text from a file if the value calls for that. If the
+property value isn't @code{nil}, isn't a string, and doesn't refer to
+text in a file, then it is evaluated to obtain a string.
+
+Finally, @code{documentation-property} passes the string through
+@code{substitute-command-keys} to substitute actual key bindings,
+unless @var{verbatim} is non-@code{nil}.
@smallexample
@group
(documentation-property 'command-line-processed
'variable-documentation)
- @result{} "t once command line has been processed"
+ @result{} "Non-nil once command line has been processed"
@end group
@group
(symbol-plist 'command-line-processed)
@end defun
@defun documentation function &optional verbatim
-This function returns the documentation string of @var{function}. It
-reads the text from a file if necessary. Then (unless @var{verbatim} is
-non-@code{nil}) it calls @code{substitute-command-keys}, to return a
-value containing the actual (current) key bindings.
+This function returns the documentation string of @var{function}.
+
+If @var{function} is a symbol, this function first looks for the
+@code{function-documentation} property of that symbol; if that has a
+non-@code{nil} value, the documentation comes from that value (if the
+value is not a string, it is evaluated). If @var{function} is not a
+symbol, or if it has no @code{function-documentation} property, then
+@code{documentation} extracts the documentation string from the actual
+function definition, reading it from a file if called for.
+
+Finally, unless @var{verbatim} is non-@code{nil}, it calls
+@code{substitute-command-keys} so as to return a value containing the
+actual (current) key bindings.
The function @code{documentation} signals a @code{void-function} error
if @var{function} has no function definition. However, it is OK if
in the `*Help*' buffer."
(interactive "sDescribe symbols matching: ")
(let ((describe-func
- (function
+ (function
(lambda (s)
@end group
@group
(if (fboundp s) ; @r{It is a function.}
(princ
(format "%s\t%s\n%s\n\n" s
- (if (commandp s)
+ (if (commandp s)
(let ((keys (where-is-internal s)))
(if keys
(concat
"Keys: "
- (mapconcat 'key-description
+ (mapconcat 'key-description
keys " "))
"Keys: none"))
"Function")
@end group
@group
- (or (documentation s)
+ (or (documentation s)
"not documented"))))
-
+
(if (boundp s) ; @r{It is a variable.}
@end group
@group
(princ
(format "%s\t%s\n%s\n\n" s
- (if (user-variable-p s)
+ (if (user-variable-p s)
"Option " "Variable")
@end group
@group
- (or (documentation-property
+ (or (documentation-property
s 'variable-documentation)
"not documented")))))))
sym-list)
@group
;; @r{Build a list of symbols that match pattern.}
- (mapatoms (function
+ (mapatoms (function
(lambda (sym)
(if (string-match pattern (symbol-name sym))
(setq sym-list (cons sym sym-list))))))
(describe-symbols "goal")
---------- Buffer: *Help* ----------
-goal-column Option
+goal-column Option
*Semipermanent goal column for vertical motion, as set by @dots{}
@end group
@c Do not blithely break or fill these lines.
@c That makes them incorrect.
@group
-set-goal-column Command: C-x C-n
+set-goal-column Keys: C-x C-n
Set the current horizontal position as a goal for C-n and C-p.
@end group
@c DO NOT put a blank line here! That is factually inaccurate!
@end group
@end smallexample
+The asterisk @samp{*} as the first character of a variable's doc string,
+as shown above for the @code{goal-column} variable, means that it is a
+user option; see the description of @code{defvar} in @ref{Defining
+Variables}.
+
@defun 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
stands for a key sequence that will invoke @var{command}, or @samp{M-x
@var{command}} if @var{command} has no key bindings.
-@item \@{@var{mapvar}@}
+@item \@{@var{mapvar}@}
stands for a summary of the keymap which is the value of the variable
@var{mapvar}. The summary is made using @code{describe-bindings}.
-@item \<@var{mapvar}>
+@item \<@var{mapvar}>
stands for no text itself. It is used only for a side effect: it
specifies @var{mapvar}'s value as the keymap for any following
@samp{\[@var{command}]} sequences in this documentation string.
@smallexample
@group
-(substitute-command-keys
+(substitute-command-keys
"To abort recursive edit, type: \\[abort-recursive-edit]")
@result{} "To abort recursive edit, type: C-]"
@end group
@group
-(substitute-command-keys
+(substitute-command-keys
"The keys that are defined for the minibuffer here are:
\\@{minibuffer-local-must-match-map@}")
@result{} "The keys that are defined for the minibuffer here are:
@code{single-key-description}, below.
@end defun
-@defun single-key-description event
+@defun single-key-description event &optional no-angles
@cindex event printing
@cindex character printing
@cindex control character printing
@cindex meta character printing
This function returns a string describing @var{event} in the standard
-Emacs notation for keyboard input. A normal printing character appears
-as itself, but a control character turns into a string starting with
-@samp{C-}, a meta character turns into a string starting with @samp{M-},
-and space, tab, etc.@: appear as @samp{SPC}, @samp{TAB}, etc. A
-function key symbol appears as itself. An event that is a list appears
-as the name of the symbol in the @sc{car} of the list.
+Emacs notation for keyboard input. A normal printing character
+appears as itself, but a control character turns into a string
+starting with @samp{C-}, a meta character turns into a string starting
+with @samp{M-}, and space, tab, etc.@: appear as @samp{SPC},
+@samp{TAB}, etc. A function key symbol appears inside angle brackets
+@samp{<@dots{}>}. An event that is a list appears as the name of the
+symbol in the @sc{car} of the list, inside angle brackets.
+
+If the optional argument @var{no-angles} is non-@code{nil}, the angle
+brackets around function keys and event symbols are omitted; this is
+for compatibility with old versions of Emacs which didn't use the
+brackets.
@smallexample
@group
@result{} "C-x SPC M-y SPC C-j SPC TAB SPC RET SPC C-l 1 2 3"
@end group
@group
+(single-key-description 'delete)
+ @result{} "<delete>"
+@end group
+@group
(single-key-description 'C-mouse-1)
+ @result{} "<C-mouse-1>"
+@end group
+@group
+(single-key-description 'C-mouse-1 t)
@result{} "C-mouse-1"
@end group
@end smallexample
@end smallexample
@end defun
+@defun read-kbd-macro string
+This function is used mainly for operating on keyboard macros, but it
+can also be used as a rough inverse for @code{key-description}. You
+call it with a string containing key descriptions, separated by spaces;
+it returns a string or vector containing the corresponding events.
+(This may or may not be a single valid key sequence, depending on what
+events you use; @pxref{Keymap Terminology}.)
+@end defun
+
@node Help Functions
@section Help Functions
beginning of its documentation string.
@c Emacs 19 feature
-If @var{do-all} is non-@code{nil}, then @code{apropos} also shows
-key bindings for the functions that are found.
+If @var{do-all} is non-@code{nil}, then @code{apropos} also shows key
+bindings for the functions that are found; it also shows all symbols,
+even those that are neither functions nor variables.
In the first of the following examples, @code{apropos} finds all the
symbols with names containing @samp{exec}. (We don't show here the
@defvar help-char
The value of this variable is the help character---the character that
-Emacs recognizes as meaning Help. By default, it stands for 8, which is
-@kbd{C-h}. When Emacs reads this character, if @code{help-form} is
-non-@code{nil} Lisp expression, it evaluates that expression, and
-displays the result in a window if it is a string.
+Emacs recognizes as meaning Help. By default, its value is 8, which
+stands for @kbd{C-h}. When Emacs reads this character, if
+@code{help-form} is a non-@code{nil} Lisp expression, it evaluates that
+expression, and displays the result in a window if it is a string.
-Usually the value of @code{help-form}'s value is @code{nil}. Then the
+Usually the value of @code{help-form} is @code{nil}. Then the
help character has no special meaning at the level of command input, and
it becomes part of a key sequence in the normal way. The standard key
binding of @kbd{C-h} is a prefix key for several general-purpose help
subcommands of the prefix key.
@end defvar
-@tindex help-event-list
@defvar help-event-list
The value of this variable is a list of event types that serve as
alternative ``help characters.'' These events are handled just like the
sequence. (The last event is, presumably, the help character.)
@end defun
- The following two functions are found in the library @file{helper}.
-They are for modes that want to provide help without relinquishing
-control, such as the ``electric'' modes. You must load that library
-with @code{(require 'helper)} in order to use them. Their names begin
-with @samp{Helper} to distinguish them from the ordinary help functions.
+ The following two functions are meant for modes that want to provide
+help without relinquishing control, such as the ``electric'' modes.
+Their names begin with @samp{Helper} to distinguish them from the
+ordinary help functions.
@deffn Command Helper-describe-bindings
This command pops up a window displaying a help buffer containing a
@c Emacs 19 feature
@defmac make-help-screen fname help-line help-text help-map
-This macro defines a help command named @var{fname} that acts like a
+This macro defines a help command named @var{fname} that acts like a
prefix key that shows a list of the subcommands it offers.
When invoked, @var{fname} displays @var{help-text} in a window, then