X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/a9f0a989a17f47f9d25b7a426b4e82a8ff684ee4..c5c927519c95b69cf998228a975c66e0d75d3215:/lispref/help.texi diff --git a/lispref/help.texi b/lispref/help.texi index cde0956b5b..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 @@ -496,7 +529,7 @@ 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 @@ -509,7 +542,6 @@ subcommands of the prefix key. @end defvar @defvar help-event-list -@tindex 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 event specified by @code{help-char}.