X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/969fe9b5696c9d9d31f2faf1ca2e8af107013dcb..c5c927519c95b69cf998228a975c66e0d75d3215:/lispref/help.texi diff --git a/lispref/help.texi b/lispref/help.texi index d31315c0ef..eb9dc0a75d 100644 --- a/lispref/help.texi +++ b/lispref/help.texi @@ -1,6 +1,7 @@ @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 @@ -99,24 +100,28 @@ Help, emacs, The GNU Emacs Manual}. @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) @@ -126,10 +131,19 @@ substitution is not done if @var{verbatim} is non-@code{nil}.) @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 @@ -218,7 +232,7 @@ goal-column Option @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! @@ -240,6 +254,11 @@ When the `track-eol' feature is doing its job, the value is 9999. @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 @@ -363,18 +382,24 @@ about valid events. See also the examples for @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 @@ -386,7 +411,15 @@ as the name of the symbol in the @sc{car} of the list. @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{} "" +@end group +@group (single-key-description 'C-mouse-1) + @result{} "" +@end group +@group +(single-key-description 'C-mouse-1 t) @result{} "C-mouse-1" @end group @end smallexample @@ -415,6 +448,15 @@ Emacs buffers are usually displayed). @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 @@ -431,8 +473,9 @@ named @samp{*Help*}, each with a one-line description taken from the 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 @@ -481,12 +524,12 @@ Documentation}. @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 @@ -498,7 +541,6 @@ binding as a subcommand of the prefix key, it runs 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 @@ -534,11 +576,10 @@ prefix described consists of all but the last event of that key 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