annotate lispref/help.texi @ 62095:f1e37047f8ed

(Pop-Up Menus): Complete description of `x-popup-menu'. (Dialog Boxes): Complete description of `x-popup-dialog'.
author Luc Teirlinck <teirllm@auburn.edu>
date Thu, 05 May 2005 23:05:00 +0000
parents 74accd79beb7
children f69f062368dd e4694597cbf4
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1 @c -*-texinfo-*-
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2 @c This is part of the GNU Emacs Lisp Reference Manual.
56213
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2004
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 39221
diff changeset
4 @c Free Software Foundation, Inc.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
5 @c See the file elisp.texi for copying conditions.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
6 @setfilename ../info/help
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
7 @node Documentation, Files, Modes, Top
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
8 @chapter Documentation
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
9 @cindex documentation strings
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
10
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
11 GNU Emacs Lisp has convenient on-line help facilities, most of which
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
12 derive their information from the documentation strings associated with
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
13 functions and variables. This chapter describes how to write good
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
14 documentation strings for your Lisp programs, as well as how to write
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
15 programs to access documentation.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
16
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
17 Note that the documentation strings for Emacs are not the same thing
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
18 as the Emacs manual. Manuals have their own source files, written in
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
19 the Texinfo language; documentation strings are specified in the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
20 definitions of the functions and variables they apply to. A collection
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
21 of documentation strings is not sufficient as a manual because a good
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
22 manual is not organized in that fashion; it is organized in terms of
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
23 topics of discussion.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
24
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
25 @menu
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
26 * Documentation Basics:: Good style for doc strings.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
27 Where to put them. How Emacs stores them.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
28 * Accessing Documentation:: How Lisp programs can access doc strings.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
29 * Keys in Documentation:: Substituting current key bindings.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
30 * Describing Characters:: Making printable descriptions of
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
31 non-printing characters and key sequences.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
32 * Help Functions:: Subroutines used by Emacs help facilities.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
33 @end menu
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
34
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
35 @node Documentation Basics
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
36 @comment node-name, next, previous, up
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
37 @section Documentation Basics
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
38 @cindex documentation conventions
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
39 @cindex writing a documentation string
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
40 @cindex string, writing a doc string
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
41
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
42 A documentation string is written using the Lisp syntax for strings,
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
43 with double-quote characters surrounding the text of the string. This
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
44 is because it really is a Lisp string object. The string serves as
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
45 documentation when it is written in the proper place in the definition
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
46 of a function or variable. In a function definition, the documentation
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
47 string follows the argument list. In a variable definition, the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
48 documentation string follows the initial value of the variable.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
49
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
50 When you write a documentation string, make the first line a complete
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
51 sentence (or two complete sentences) since some commands, such as
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
52 @code{apropos}, show only the first line of a multi-line documentation
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
53 string. Also, you should not indent the second line of a documentation
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
54 string, if it has one, because that looks odd when you use @kbd{C-h f}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
55 (@code{describe-function}) or @kbd{C-h v} (@code{describe-variable}) to
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
56 view the documentation string. @xref{Documentation Tips}.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
57
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
58 Documentation strings can contain several special substrings, which
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
59 stand for key bindings to be looked up in the current keymaps when the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
60 documentation is displayed. This allows documentation strings to refer
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
61 to the keys for related commands and be accurate even when a user
56213
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
62 rearranges the key bindings. (@xref{Keys in Documentation}.)
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
63
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
64 In Emacs Lisp, a documentation string is accessible through the
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
65 function or variable that it describes:
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
66
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
67 @itemize @bullet
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
68 @item
60265
74accd79beb7 (Documentation Basics): Add function-documentation prop.
Richard M. Stallman <rms@gnu.org>
parents: 56213
diff changeset
69 @kindex function-documentation
74accd79beb7 (Documentation Basics): Add function-documentation prop.
Richard M. Stallman <rms@gnu.org>
parents: 56213
diff changeset
70 The documentation for a function is usually stored in the function
74accd79beb7 (Documentation Basics): Add function-documentation prop.
Richard M. Stallman <rms@gnu.org>
parents: 56213
diff changeset
71 definition itself (@pxref{Lambda Expressions}). The function
74accd79beb7 (Documentation Basics): Add function-documentation prop.
Richard M. Stallman <rms@gnu.org>
parents: 56213
diff changeset
72 @code{documentation} knows how to extract it. You can also put
74accd79beb7 (Documentation Basics): Add function-documentation prop.
Richard M. Stallman <rms@gnu.org>
parents: 56213
diff changeset
73 function documentation in the @code{function-documentation} property
74accd79beb7 (Documentation Basics): Add function-documentation prop.
Richard M. Stallman <rms@gnu.org>
parents: 56213
diff changeset
74 of the function name. That is useful with definitions such as
74accd79beb7 (Documentation Basics): Add function-documentation prop.
Richard M. Stallman <rms@gnu.org>
parents: 56213
diff changeset
75 keyboard macros that can't hold a documentation string.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
76
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
77 @item
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
78 @kindex variable-documentation
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
79 The documentation for a variable is stored in the variable's property
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
80 list under the property name @code{variable-documentation}. The
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
81 function @code{documentation-property} knows how to retrieve it.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
82 @end itemize
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
83
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
84 @cindex @file{DOC} (documentation) file
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
85 @cindex @file{emacs/etc/DOC-@var{version}}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
86 @cindex @file{etc/DOC-@var{version}}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
87 To save space, the documentation for preloaded functions and variables
7254
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
88 (including primitive functions and autoloaded functions) is stored in
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
89 the file @file{emacs/etc/DOC-@var{version}}---not inside Emacs. The
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
90 documentation strings for functions and variables loaded during the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
91 Emacs session from byte-compiled files are stored in those files
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
92 (@pxref{Docs and Compilation}).
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7254
diff changeset
93
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7254
diff changeset
94 The data structure inside Emacs has an integer offset into the file, or
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
95 a list containing a file name and an integer, in place of the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
96 documentation string. The functions @code{documentation} and
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
97 @code{documentation-property} use that information to fetch the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
98 documentation string from the appropriate file; this is transparent to
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
99 the user.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
100
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
101 For information on the uses of documentation strings, see @ref{Help, ,
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
102 Help, emacs, The GNU Emacs Manual}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
103
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
104 @c Wordy to prevent overfull hbox. --rjc 15mar92
6708
3d0ab51bfa03 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6381
diff changeset
105 The @file{emacs/lib-src} directory contains two utilities that you can
3d0ab51bfa03 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6381
diff changeset
106 use to print nice-looking hardcopy for the file
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
107 @file{emacs/etc/DOC-@var{version}}. These are @file{sorted-doc} and
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
108 @file{digest-doc}.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
109
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
110 @node Accessing Documentation
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
111 @section Access to Documentation Strings
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
112
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
113 @defun documentation-property symbol property &optional verbatim
39221
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
114 This function returns the documentation string that is recorded in
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
115 @var{symbol}'s property list under property @var{property}. It
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
116 retrieves the text from a file if the value calls for that. If the
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
117 property value isn't @code{nil}, isn't a string, and doesn't refer to
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
118 text in a file, then it is evaluated to obtain a string.
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
119
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
120 Finally, @code{documentation-property} passes the string through
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
121 @code{substitute-command-keys} to substitute actual key bindings,
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
122 unless @var{verbatim} is non-@code{nil}.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
123
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
124 @smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
125 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
126 (documentation-property 'command-line-processed
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
127 'variable-documentation)
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
128 @result{} "Non-nil once command line has been processed"
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
129 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
130 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
131 (symbol-plist 'command-line-processed)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
132 @result{} (variable-documentation 188902)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
133 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
134 @end smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
135 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
136
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
137 @defun documentation function &optional verbatim
39221
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
138 This function returns the documentation string of @var{function}.
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
139
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
140 If @var{function} is a symbol, this function first looks for the
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
141 @code{function-documentation} property of that symbol; if that has a
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
142 non-@code{nil} value, the documentation comes from that value (if the
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
143 value is not a string, it is evaluated). If @var{function} is not a
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
144 symbol, or if it has no @code{function-documentation} property, then
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
145 @code{documentation} extracts the documentation string from the actual
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
146 function definition, reading it from a file if called for.
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
147
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
148 Finally, unless @var{verbatim} is non-@code{nil}, it calls
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
149 @code{substitute-command-keys} so as to return a value containing the
39206
41ede3832703 (Describing Characters) <single-key-description>:
Eli Zaretskii <eliz@gnu.org>
parents: 31130
diff changeset
150 actual (current) key bindings.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
151
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
152 The function @code{documentation} signals a @code{void-function} error
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
153 if @var{function} has no function definition. However, it is OK if
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
154 the function definition has no documentation string. In that case,
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
155 @code{documentation} returns @code{nil}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
156 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
157
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
158 @c Wordy to prevent overfull hboxes. --rjc 15mar92
7254
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
159 Here is an example of using the two functions, @code{documentation} and
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
160 @code{documentation-property}, to display the documentation strings for
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
161 several symbols in a @samp{*Help*} buffer.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
162
53481
454b1ca272b8 (Accessing Documentation): Add anchor.
Luc Teirlinck <teirllm@auburn.edu>
parents: 53298
diff changeset
163 @anchor{describe-symbols example}
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
164 @smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
165 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
166 (defun describe-symbols (pattern)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
167 "Describe the Emacs Lisp symbols matching PATTERN.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
168 All symbols that have PATTERN in their name are described
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
169 in the `*Help*' buffer."
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
170 (interactive "sDescribe symbols matching: ")
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
171 (let ((describe-func
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 39221
diff changeset
172 (function
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
173 (lambda (s)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
174 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
175 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
176 ;; @r{Print description of symbol.}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
177 (if (fboundp s) ; @r{It is a function.}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
178 (princ
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
179 (format "%s\t%s\n%s\n\n" s
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 39221
diff changeset
180 (if (commandp s)
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
181 (let ((keys (where-is-internal s)))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
182 (if keys
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
183 (concat
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
184 "Keys: "
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 39221
diff changeset
185 (mapconcat 'key-description
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
186 keys " "))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
187 "Keys: none"))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
188 "Function")
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
189 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
190 @group
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 39221
diff changeset
191 (or (documentation s)
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
192 "not documented"))))
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 39221
diff changeset
193
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
194 (if (boundp s) ; @r{It is a variable.}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
195 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
196 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
197 (princ
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
198 (format "%s\t%s\n%s\n\n" s
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 39221
diff changeset
199 (if (user-variable-p s)
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
200 "Option " "Variable")
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
201 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
202 @group
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 39221
diff changeset
203 (or (documentation-property
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
204 s 'variable-documentation)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
205 "not documented")))))))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
206 sym-list)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
207 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
208
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
209 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
210 ;; @r{Build a list of symbols that match pattern.}
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 39221
diff changeset
211 (mapatoms (function
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
212 (lambda (sym)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
213 (if (string-match pattern (symbol-name sym))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
214 (setq sym-list (cons sym sym-list))))))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
215 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
216
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
217 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
218 ;; @r{Display the data.}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
219 (with-output-to-temp-buffer "*Help*"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
220 (mapcar describe-func (sort sym-list 'string<))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
221 (print-help-return-message))))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
222 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
223 @end smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
224
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
225 The @code{describe-symbols} function works like @code{apropos},
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
226 but provides more information.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
227
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
228 @smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
229 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
230 (describe-symbols "goal")
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
231
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
232 ---------- Buffer: *Help* ----------
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 39221
diff changeset
233 goal-column Option
16736
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 13349
diff changeset
234 *Semipermanent goal column for vertical motion, as set by @dots{}
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
235 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
236 @c Do not blithely break or fill these lines.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
237 @c That makes them incorrect.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
238
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
239 @group
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
240 set-goal-column Keys: C-x C-n
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
241 Set the current horizontal position as a goal for C-n and C-p.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
242 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
243 @c DO NOT put a blank line here! That is factually inaccurate!
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
244 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
245 Those commands will move to this position in the line moved to
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
246 rather than trying to keep the same horizontal position.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
247 With a non-nil argument, clears out the goal column
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
248 so that C-n and C-p resume vertical motion.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
249 The goal column is stored in the variable `goal-column'.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
250 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
251
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
252 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
253 temporary-goal-column Variable
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
254 Current goal column for vertical motion.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
255 It is the column where point was
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
256 at the start of current run of vertical motion commands.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
257 When the `track-eol' feature is doing its job, the value is 9999.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
258 ---------- Buffer: *Help* ----------
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
259 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
260 @end smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
261
31130
e9c859a12e47 Add a comment about the significance of an asterisk as the first
Eli Zaretskii <eliz@gnu.org>
parents: 27189
diff changeset
262 The asterisk @samp{*} as the first character of a variable's doc string,
e9c859a12e47 Add a comment about the significance of an asterisk as the first
Eli Zaretskii <eliz@gnu.org>
parents: 27189
diff changeset
263 as shown above for the @code{goal-column} variable, means that it is a
e9c859a12e47 Add a comment about the significance of an asterisk as the first
Eli Zaretskii <eliz@gnu.org>
parents: 27189
diff changeset
264 user option; see the description of @code{defvar} in @ref{Defining
e9c859a12e47 Add a comment about the significance of an asterisk as the first
Eli Zaretskii <eliz@gnu.org>
parents: 27189
diff changeset
265 Variables}.
e9c859a12e47 Add a comment about the significance of an asterisk as the first
Eli Zaretskii <eliz@gnu.org>
parents: 27189
diff changeset
266
56213
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
267 @defun Snarf-documentation filename
53298
8066757520a8 (Accessing Documentation): Add anchor.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52401
diff changeset
268 @anchor{Definition of Snarf-documentation}
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
269 This function is used only during Emacs initialization, just before
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
270 the runnable Emacs is dumped. It finds the file offsets of the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
271 documentation strings stored in the file @var{filename}, and records
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
272 them in the in-core function definitions and variable property lists in
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
273 place of the actual strings. @xref{Building Emacs}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
274
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
275 Emacs reads the file @var{filename} from the @file{emacs/etc} directory.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
276 When the dumped Emacs is later executed, the same file will be looked
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
277 for in the directory @code{doc-directory}. Usually @var{filename} is
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
278 @code{"DOC-@var{version}"}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
279 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
280
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
281 @c Emacs 19 feature
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
282 @defvar doc-directory
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
283 This variable holds the name of the directory which should contain the
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
284 file @code{"DOC-@var{version}"} that contains documentation strings for
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
285 built-in and preloaded functions and variables.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
286
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
287 In most cases, this is the same as @code{data-directory}. They may be
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
288 different when you run Emacs from the directory where you built it,
56213
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
289 without actually installing it. @xref{Definition of data-directory}.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
290
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
291 In older Emacs versions, @code{exec-directory} was used for this.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
292 @end defvar
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
293
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
294 @node Keys in Documentation
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
295 @section Substituting Key Bindings in Documentation
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
296 @cindex documentation, keys in
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
297 @cindex keys in documentation strings
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
298 @cindex substituting keys in documentation
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
299
7254
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
300 When documentation strings refer to key sequences, they should use the
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
301 current, actual key bindings. They can do so using certain special text
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
302 sequences described below. Accessing documentation strings in the usual
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
303 way substitutes current key binding information for these special
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
304 sequences. This works by calling @code{substitute-command-keys}. You
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
305 can also call that function yourself.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
306
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
307 Here is a list of the special sequences and what they mean:
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
308
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
309 @table @code
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
310 @item \[@var{command}]
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
311 stands for a key sequence that will invoke @var{command}, or @samp{M-x
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
312 @var{command}} if @var{command} has no key bindings.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
313
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 39221
diff changeset
314 @item \@{@var{mapvar}@}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
315 stands for a summary of the keymap which is the value of the variable
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
316 @var{mapvar}. The summary is made using @code{describe-bindings}.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
317
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 39221
diff changeset
318 @item \<@var{mapvar}>
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
319 stands for no text itself. It is used only for a side effect: it
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
320 specifies @var{mapvar}'s value as the keymap for any following
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
321 @samp{\[@var{command}]} sequences in this documentation string.
13349
1c9bf4febb14 Document \= in doc string.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
322
1c9bf4febb14 Document \= in doc string.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
323 @item \=
1c9bf4febb14 Document \= in doc string.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
324 quotes the following character and is discarded; thus, @samp{\=\[} puts
1c9bf4febb14 Document \= in doc string.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
325 @samp{\[} into the output, and @samp{\=\=} puts @samp{\=} into the
1c9bf4febb14 Document \= in doc string.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
326 output.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
327 @end table
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
328
7254
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
329 @strong{Please note:} Each @samp{\} must be doubled when written in a
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
330 string in Emacs Lisp.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
331
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
332 @defun substitute-command-keys string
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
333 This function scans @var{string} for the above special sequences and
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
334 replaces them by what they stand for, returning the result as a string.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
335 This permits display of documentation that refers accurately to the
7254
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
336 user's own customized key bindings.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
337 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
338
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
339 Here are examples of the special sequences:
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
340
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
341 @smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
342 @group
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 39221
diff changeset
343 (substitute-command-keys
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
344 "To abort recursive edit, type: \\[abort-recursive-edit]")
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
345 @result{} "To abort recursive edit, type: C-]"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
346 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
347
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
348 @group
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 39221
diff changeset
349 (substitute-command-keys
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
350 "The keys that are defined for the minibuffer here are:
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
351 \\@{minibuffer-local-must-match-map@}")
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
352 @result{} "The keys that are defined for the minibuffer here are:
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
353 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
354
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
355 ? minibuffer-completion-help
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
356 SPC minibuffer-complete-word
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
357 TAB minibuffer-complete
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
358 C-j minibuffer-complete-and-exit
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
359 RET minibuffer-complete-and-exit
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
360 C-g abort-recursive-edit
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
361 "
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
362
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
363 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
364 (substitute-command-keys
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
365 "To abort a recursive edit from the minibuffer, type\
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
366 \\<minibuffer-local-must-match-map>\\[abort-recursive-edit].")
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
367 @result{} "To abort a recursive edit from the minibuffer, type C-g."
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
368 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
369 @end smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
370
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
371 @node Describing Characters
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
372 @section Describing Characters for Help Messages
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
373
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
374 These functions convert events, key sequences, or characters to
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
375 textual descriptions. These descriptions are useful for including
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
376 arbitrary text characters or key sequences in messages, because they
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
377 convert non-printing and whitespace characters to sequences of printing
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
378 characters. The description of a non-whitespace printing character is
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
379 the character itself.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
380
56213
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
381 @defun key-description sequence &optional prefix
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
382 @cindex Emacs event standard notation
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
383 This function returns a string containing the Emacs standard notation
56213
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
384 for the input events in @var{sequence}. If @var{prefix} is
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
385 non-@code{nil}, it is a sequence of input events leading up to
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
386 @var{sequence} and is included in the return value. Both arguments
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
387 may be strings, vectors or lists. @xref{Input Events}, for more
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
388 information about valid events.
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
389
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
390 @smallexample
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
391 @group
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
392 (key-description [?\M-3 delete])
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
393 @result{} "M-3 <delete>"
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
394 @end group
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
395 @group
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
396 (key-description [delete] "\M-3")
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
397 @result{} "M-3 <delete>"
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
398 @end group
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
399 @end smallexample
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
400
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
401 See also the examples for @code{single-key-description}, below.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
402 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
403
39206
41ede3832703 (Describing Characters) <single-key-description>:
Eli Zaretskii <eliz@gnu.org>
parents: 31130
diff changeset
404 @defun single-key-description event &optional no-angles
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
405 @cindex event printing
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
406 @cindex character printing
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
407 @cindex control character printing
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
408 @cindex meta character printing
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
409 This function returns a string describing @var{event} in the standard
39221
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
410 Emacs notation for keyboard input. A normal printing character
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
411 appears as itself, but a control character turns into a string
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
412 starting with @samp{C-}, a meta character turns into a string starting
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
413 with @samp{M-}, and space, tab, etc.@: appear as @samp{SPC},
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
414 @samp{TAB}, etc. A function key symbol appears inside angle brackets
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
415 @samp{<@dots{}>}. An event that is a list appears as the name of the
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
416 symbol in the @sc{car} of the list, inside angle brackets.
39206
41ede3832703 (Describing Characters) <single-key-description>:
Eli Zaretskii <eliz@gnu.org>
parents: 31130
diff changeset
417
41ede3832703 (Describing Characters) <single-key-description>:
Eli Zaretskii <eliz@gnu.org>
parents: 31130
diff changeset
418 If the optional argument @var{no-angles} is non-@code{nil}, the angle
41ede3832703 (Describing Characters) <single-key-description>:
Eli Zaretskii <eliz@gnu.org>
parents: 31130
diff changeset
419 brackets around function keys and event symbols are omitted; this is
39221
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
420 for compatibility with old versions of Emacs which didn't use the
39206
41ede3832703 (Describing Characters) <single-key-description>:
Eli Zaretskii <eliz@gnu.org>
parents: 31130
diff changeset
421 brackets.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
422
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
423 @smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
424 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
425 (single-key-description ?\C-x)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
426 @result{} "C-x"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
427 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
428 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
429 (key-description "\C-x \M-y \n \t \r \f123")
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
430 @result{} "C-x SPC M-y SPC C-j SPC TAB SPC RET SPC C-l 1 2 3"
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
431 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
432 @group
39206
41ede3832703 (Describing Characters) <single-key-description>:
Eli Zaretskii <eliz@gnu.org>
parents: 31130
diff changeset
433 (single-key-description 'delete)
41ede3832703 (Describing Characters) <single-key-description>:
Eli Zaretskii <eliz@gnu.org>
parents: 31130
diff changeset
434 @result{} "<delete>"
41ede3832703 (Describing Characters) <single-key-description>:
Eli Zaretskii <eliz@gnu.org>
parents: 31130
diff changeset
435 @end group
41ede3832703 (Describing Characters) <single-key-description>:
Eli Zaretskii <eliz@gnu.org>
parents: 31130
diff changeset
436 @group
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
437 (single-key-description 'C-mouse-1)
39206
41ede3832703 (Describing Characters) <single-key-description>:
Eli Zaretskii <eliz@gnu.org>
parents: 31130
diff changeset
438 @result{} "<C-mouse-1>"
41ede3832703 (Describing Characters) <single-key-description>:
Eli Zaretskii <eliz@gnu.org>
parents: 31130
diff changeset
439 @end group
41ede3832703 (Describing Characters) <single-key-description>:
Eli Zaretskii <eliz@gnu.org>
parents: 31130
diff changeset
440 @group
41ede3832703 (Describing Characters) <single-key-description>:
Eli Zaretskii <eliz@gnu.org>
parents: 31130
diff changeset
441 (single-key-description 'C-mouse-1 t)
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
442 @result{} "C-mouse-1"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
443 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
444 @end smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
445 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
446
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
447 @defun text-char-description character
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
448 This function returns a string describing @var{character} in the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
449 standard Emacs notation for characters that appear in text---like
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
450 @code{single-key-description}, except that control characters are
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
451 represented with a leading caret (which is how control characters in
56213
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
452 Emacs buffers are usually displayed). Another difference is that
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
453 @code{text-char-description} recognizes the 2**7 bit as the Meta
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
454 character, whereas @code{single-key-description} uses the 2**27 bit
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
455 for Meta.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
456
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
457 @smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
458 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
459 (text-char-description ?\C-c)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
460 @result{} "^C"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
461 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
462 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
463 (text-char-description ?\M-m)
54032
dbcba6606213 (Describing Characters): Fix text-char-description example output.
Richard M. Stallman <rms@gnu.org>
parents: 53481
diff changeset
464 @result{} "\xed"
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
465 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
466 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
467 (text-char-description ?\C-\M-m)
54032
dbcba6606213 (Describing Characters): Fix text-char-description example output.
Richard M. Stallman <rms@gnu.org>
parents: 53481
diff changeset
468 @result{} "\x8d"
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
469 @end group
56213
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
470 @group
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
471 (text-char-description (+ 128 ?m))
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
472 @result{} "M-m"
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
473 @end group
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
474 @group
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
475 (text-char-description (+ 128 ?\C-m))
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
476 @result{} "M-^M"
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
477 @end group
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
478 @end smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
479 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
480
56213
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
481 @defun read-kbd-macro string &optional need-vector
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
482 This function is used mainly for operating on keyboard macros, but it
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
483 can also be used as a rough inverse for @code{key-description}. You
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
484 call it with a string containing key descriptions, separated by spaces;
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
485 it returns a string or vector containing the corresponding events.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
486 (This may or may not be a single valid key sequence, depending on what
56213
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
487 events you use; @pxref{Keymap Terminology}.) If @var{need-vector} is
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
488 non-@code{nil}, the return value is always a vector.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
489 @end defun
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
490
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
491 @node Help Functions
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
492 @section Help Functions
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
493
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
494 Emacs provides a variety of on-line help functions, all accessible to
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
495 the user as subcommands of the prefix @kbd{C-h}. For more information
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
496 about them, see @ref{Help, , Help, emacs, The GNU Emacs Manual}. Here
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
497 we describe some program-level interfaces to the same information.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
498
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
499 @deffn Command apropos regexp &optional do-all
56213
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
500 This function finds all ``meaningful'' symbols whose names contain a
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
501 match for the regular expression @var{regexp}, and returns a list of
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
502 them, with associated documentation (@pxref{Regular Expressions}). It
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
503 also displays the symbols in a buffer named @samp{*Apropos*}, each
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
504 with a one-line description taken from the beginning of its
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
505 documentation string. A symbol is ``meaningful'' if it has a
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
506 definition as a function, variable, or face, or has properties.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
507
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
508 @c Emacs 19 feature
56213
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
509 If @var{do-all} is non-@code{nil}, or if the user option
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
510 @code{apropos-do-all} is non-@code{nil}, then @code{apropos} also
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
511 shows key bindings for the functions that are found; it also shows
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
512 @emph{all} interned symbols, not just meaningful ones (and it lists
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
513 them in the return value as well).
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
514 @end deffn
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
515
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
516 @defvar help-map
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
517 The value of this variable is a local keymap for characters following the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
518 Help key, @kbd{C-h}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
519 @end defvar
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
520
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
521 @deffn {Prefix Command} help-command
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
522 This symbol is not a function; its function definition cell holds the
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
523 keymap known as @code{help-map}. It is defined in @file{help.el} as
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
524 follows:
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
525
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
526 @smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
527 @group
56213
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
528 (define-key global-map (char-to-string help-char) 'help-command)
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
529 (fset 'help-command help-map)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
530 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
531 @end smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
532 @end deffn
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
533
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
534 @defun print-help-return-message &optional function
7254
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
535 This function builds a string that explains how to restore the previous
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
536 state of the windows after a help command. After building the message,
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
537 it applies @var{function} to it if @var{function} is non-@code{nil}.
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
538 Otherwise it calls @code{message} to display it in the echo area.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
539
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
540 This function expects to be called inside a
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
541 @code{with-output-to-temp-buffer} special form, and expects
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
542 @code{standard-output} to have the value bound by that special form.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
543 For an example of its use, see the long example in @ref{Accessing
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
544 Documentation}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
545 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
546
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
547 @defvar help-char
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
548 The value of this variable is the help character---the character that
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
549 Emacs recognizes as meaning Help. By default, its value is 8, which
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
550 stands for @kbd{C-h}. When Emacs reads this character, if
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
551 @code{help-form} is a non-@code{nil} Lisp expression, it evaluates that
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
552 expression, and displays the result in a window if it is a string.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
553
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
554 Usually the value of @code{help-form} is @code{nil}. Then the
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
555 help character has no special meaning at the level of command input, and
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
556 it becomes part of a key sequence in the normal way. The standard key
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
557 binding of @kbd{C-h} is a prefix key for several general-purpose help
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
558 features.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
559
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
560 The help character is special after prefix keys, too. If it has no
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
561 binding as a subcommand of the prefix key, it runs
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
562 @code{describe-prefix-bindings}, which displays a list of all the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
563 subcommands of the prefix key.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
564 @end defvar
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
565
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
566 @defvar help-event-list
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
567 The value of this variable is a list of event types that serve as
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
568 alternative ``help characters.'' These events are handled just like the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
569 event specified by @code{help-char}.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
570 @end defvar
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
571
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
572 @defvar help-form
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
573 If this variable is non-@code{nil}, its value is a form to evaluate
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
574 whenever the character @code{help-char} is read. If evaluating the form
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
575 produces a string, that string is displayed.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
576
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
577 A command that calls @code{read-event} or @code{read-char} probably
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
578 should bind @code{help-form} to a non-@code{nil} expression while it
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
579 does input. (The time when you should not do this is when @kbd{C-h} has
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
580 some other meaning.) Evaluating this expression should result in a
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
581 string that explains what the input is for and how to enter it properly.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
582
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
583 Entry to the minibuffer binds this variable to the value of
56213
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
584 @code{minibuffer-help-form} (@pxref{Definition of minibuffer-help-form}).
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
585 @end defvar
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
586
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
587 @defvar prefix-help-command
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
588 This variable holds a function to print help for a prefix key. The
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
589 function is called when the user types a prefix key followed by the help
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
590 character, and the help character has no binding after that prefix. The
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
591 variable's default value is @code{describe-prefix-bindings}.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
592 @end defvar
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
593
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
594 @defun describe-prefix-bindings
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
595 This function calls @code{describe-bindings} to display a list of all
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
596 the subcommands of the prefix key of the most recent key sequence. The
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
597 prefix described consists of all but the last event of that key
7254
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
598 sequence. (The last event is, presumably, the help character.)
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
599 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
600
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
601 The following two functions are meant for modes that want to provide
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
602 help without relinquishing control, such as the ``electric'' modes.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
603 Their names begin with @samp{Helper} to distinguish them from the
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
604 ordinary help functions.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
605
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
606 @deffn Command Helper-describe-bindings
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
607 This command pops up a window displaying a help buffer containing a
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
608 listing of all of the key bindings from both the local and global keymaps.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
609 It works by calling @code{describe-bindings}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
610 @end deffn
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
611
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
612 @deffn Command Helper-help
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
613 This command provides help for the current mode. It prompts the user
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
614 in the minibuffer with the message @samp{Help (Type ? for further
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
615 options)}, and then provides assistance in finding out what the key
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
616 bindings are, and what the mode is intended for. It returns @code{nil}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
617
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
618 This can be customized by changing the map @code{Helper-help-map}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
619 @end deffn
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
620
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
621 @c Emacs 19 feature
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
622 @defvar data-directory
56213
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
623 @anchor{Definition of data-directory}
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
624 This variable holds the name of the directory in which Emacs finds
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
625 certain documentation and text files that come with Emacs. In older
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
626 Emacs versions, @code{exec-directory} was used for this.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
627 @end defvar
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
628
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
629 @c Emacs 19 feature
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
630 @defmac make-help-screen fname help-line help-text help-map
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 39221
diff changeset
631 This macro defines a help command named @var{fname} that acts like a
7254
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
632 prefix key that shows a list of the subcommands it offers.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
633
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
634 When invoked, @var{fname} displays @var{help-text} in a window, then
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
635 reads and executes a key sequence according to @var{help-map}. The
7254
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
636 string @var{help-text} should describe the bindings available in
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
637 @var{help-map}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
638
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
639 The command @var{fname} is defined to handle a few events itself, by
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
640 scrolling the display of @var{help-text}. When @var{fname} reads one of
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
641 those special events, it does the scrolling and then reads another
7254
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
642 event. When it reads an event that is not one of those few, and which
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
643 has a binding in @var{help-map}, it executes that key's binding and
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
644 then returns.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
645
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
646 The argument @var{help-line} should be a single-line summary of the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
647 alternatives in @var{help-map}. In the current version of Emacs, this
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
648 argument is used only if you set the option @code{three-step-help} to
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
649 @code{t}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
650
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
651 This macro is used in the command @code{help-for-help} which is the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
652 binding of @kbd{C-h C-h}.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
653 @end defmac
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
654
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
655 @defopt three-step-help
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
656 If this variable is non-@code{nil}, commands defined with
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
657 @code{make-help-screen} display their @var{help-line} strings in the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
658 echo area at first, and display the longer @var{help-text} strings only
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
659 if the user types the help character again.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
660 @end defopt
52401
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 49600
diff changeset
661
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 49600
diff changeset
662 @ignore
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 49600
diff changeset
663 arch-tag: ba36b4c2-e60f-49e2-bc25-61158fdcd815
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 49600
diff changeset
664 @end ignore