@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@setfilename ../../info/help
-@node Documentation, Files, Modes, Top
+@node Documentation
@chapter Documentation
@cindex documentation strings
@end menu
@node Documentation Basics
-@comment node-name, next, previous, up
@section Documentation Basics
@cindex documentation conventions
@cindex writing a documentation string
@c Wordy to prevent overfull hboxes. --rjc 15mar92
Here is an example of using the two functions, @code{documentation} and
@code{documentation-property}, to display the documentation strings for
-several symbols in a @samp{*Help*} buffer.
+several symbols in a @file{*Help*} buffer.
@anchor{describe-symbols example}
@smallexample
@group
(princ
(format "%s\t%s\n%s\n\n" s
- (if (user-variable-p s)
+ (if (custom-variable-p s)
"Option " "Variable")
@end group
@group
replaces them by what they stand for, returning the result as a string.
This permits display of documentation that refers accurately to the
user's own customized key bindings.
+
+@cindex advertised binding
+If a command has multiple bindings, this function normally uses the
+first one it finds. You can specify one particular key binding by
+assigning an @code{:advertised-binding} symbol property to the
+command, like this:
+
+@smallexample
+(put 'undo :advertised-binding [?\C-/])
+@end smallexample
+
+@noindent
+The @code{:advertised-binding} property also affects the binding shown
+in menu items (@pxref{Menu Bar}). The property is ignored if it
+specifies a key binding that the command does not actually have.
@end defun
Here are examples of the special sequences:
@end smallexample
@end defun
-@defun read-kbd-macro string &optional need-vector
+@deffn Command read-kbd-macro string &optional need-vector
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;
(This may or may not be a single valid key sequence, depending on what
events you use; @pxref{Key Sequences}.) If @var{need-vector} is
non-@code{nil}, the return value is always a vector.
-@end defun
+@end deffn
@node Help Functions
@section Help Functions
The function returns a list of elements that look like this:
@example
-(@var{symbol} @var{score} @var{functionn-doc} @var{variable-doc}
+(@var{symbol} @var{score} @var{function-doc} @var{variable-doc}
@var{plist-doc} @var{widget-doc} @var{face-doc} @var{group-doc})
@end example
documentation string, or @code{nil}, for @var{symbol} as a function,
variable, etc.
-It also displays the symbols in a buffer named @samp{*Apropos*}, each
+It also displays the symbols in a buffer named @file{*Apropos*}, each
with a one-line description taken from the beginning of its
documentation string.
@defopt 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
+alternative ``help characters''. These events are handled just like the
event specified by @code{help-char}.
@end defopt
variable's default value is @code{describe-prefix-bindings}.
@end defvar
-@defun describe-prefix-bindings
+@deffn Command describe-prefix-bindings
This function calls @code{describe-bindings} to display a list of all
the subcommands of the prefix key of the most recent key sequence. The
prefix described consists of all but the last event of that key
sequence. (The last event is, presumably, the help character.)
-@end defun
+@end deffn
The following two functions are meant for modes that want to provide
help without relinquishing control, such as the ``electric'' modes.
options)}, and then provides assistance in finding out what the key
bindings are, and what the mode is intended for. It returns @code{nil}.
+@vindex Helper-help-map
This can be customized by changing the map @code{Helper-help-map}.
@end deffn
@defun help-buffer
This function returns the name of the help buffer, which is normally
-@samp{*Help*}; if such a buffer does not exist, it is first created.
+@file{*Help*}; if such a buffer does not exist, it is first created.
@end defun
@defmac with-help-window buffer-name body@dots{}
@end defmac
@defun help-setup-xref item interactive-p
-This function updates the cross reference data in the @samp{*Help*}
+This function updates the cross reference data in the @file{*Help*}
buffer, which is used to regenerate the help information when the user
clicks on the @samp{Back} or @samp{Forward} buttons. Most commands
-that use the @samp{*Help*} buffer should invoke this function before
+that use the @file{*Help*} buffer should invoke this function before
clearing the buffer. The @var{item} argument should have the form
@code{(@var{function} . @var{args})}, where @var{function} is a function
to call, with argument list @var{args}, to regenerate the help buffer.
The @var{interactive-p} argument is non-@code{nil} if the calling
command was invoked interactively; in that case, the stack of items
-for the @samp{*Help*} buffer's @samp{Back} buttons is cleared.
+for the @file{*Help*} buffer's @samp{Back} buttons is cleared.
@end defun
@xref{describe-symbols example}, for an example of using
HCoop / bpt / emacs.git / blobdiff