annotate lispref/help.texi @ 76022:e892213b9815

(w32_set_scroll_bar_thumb): Don't resize scroll-bar handle while dragging, except when we get close to eob. Fix position and size calculations so we don't scroll backwards just by clicking on the handle.
author Kim F. Storm <storm@cua.dk>
date Mon, 19 Feb 2007 14:45:39 +0000
parents 5f13eb5adc02
children fc9d442f98d2 95d0cdf160ea
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.
75250
6d19c76d81c5 Update copyright for years from Emacs 21 to present (mainly adding
Glenn Morris <rgm@gnu.org>
parents: 73397
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
6d19c76d81c5 Update copyright for years from Emacs 21 to present (mainly adding
Glenn Morris <rgm@gnu.org>
parents: 73397
diff changeset
4 @c 2002, 2003, 2004, 2005, 2006, 2007 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
75350
5f13eb5adc02 (Documentation): Add xref to Documentation Tips.
Richard M. Stallman <rms@gnu.org>
parents: 75250
diff changeset
25 For commands to display documentation strings, see @ref{Help, ,
5f13eb5adc02 (Documentation): Add xref to Documentation Tips.
Richard M. Stallman <rms@gnu.org>
parents: 75250
diff changeset
26 Help, emacs, The GNU Emacs Manual}. For the conventions for writing
5f13eb5adc02 (Documentation): Add xref to Documentation Tips.
Richard M. Stallman <rms@gnu.org>
parents: 75250
diff changeset
27 documentation strings, see @ref{Documentation Tips}.
73396
26873f2f6a26 (Documentation): Move xref to Emacs Manual here.
Richard M. Stallman <rms@gnu.org>
parents: 70904
diff changeset
28
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
29 @menu
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
30 * Documentation Basics:: Good style for doc strings.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
31 Where to put them. How Emacs stores them.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
32 * Accessing Documentation:: How Lisp programs can access doc strings.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
33 * Keys in Documentation:: Substituting current key bindings.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
34 * Describing Characters:: Making printable descriptions of
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
35 non-printing characters and key sequences.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
36 * Help Functions:: Subroutines used by Emacs help facilities.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
37 @end menu
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
38
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
39 @node Documentation Basics
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
40 @comment node-name, next, previous, up
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
41 @section Documentation Basics
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
42 @cindex documentation conventions
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
43 @cindex writing a documentation string
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
44 @cindex string, writing a doc string
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
45
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
46 A documentation string is written using the Lisp syntax for strings,
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
47 with double-quote characters surrounding the text of the string. This
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
48 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
49 documentation when it is written in the proper place in the definition
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
50 of a function or variable. In a function definition, the documentation
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
51 string follows the argument list. In a variable definition, the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
52 documentation string follows the initial value of the variable.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
53
63540
f69f062368dd (Documentation Basics): Explain the xref to Documentation Tips.
Richard M. Stallman <rms@gnu.org>
parents: 60265
diff changeset
54 When you write a documentation string, make the first line a
f69f062368dd (Documentation Basics): Explain the xref to Documentation Tips.
Richard M. Stallman <rms@gnu.org>
parents: 60265
diff changeset
55 complete sentence (or two complete sentences) since some commands,
f69f062368dd (Documentation Basics): Explain the xref to Documentation Tips.
Richard M. Stallman <rms@gnu.org>
parents: 60265
diff changeset
56 such as @code{apropos}, show only the first line of a multi-line
f69f062368dd (Documentation Basics): Explain the xref to Documentation Tips.
Richard M. Stallman <rms@gnu.org>
parents: 60265
diff changeset
57 documentation string. Also, you should not indent the second line of
f69f062368dd (Documentation Basics): Explain the xref to Documentation Tips.
Richard M. Stallman <rms@gnu.org>
parents: 60265
diff changeset
58 a documentation string, if it has one, because that looks odd when you
f69f062368dd (Documentation Basics): Explain the xref to Documentation Tips.
Richard M. Stallman <rms@gnu.org>
parents: 60265
diff changeset
59 use @kbd{C-h f} (@code{describe-function}) or @kbd{C-h v}
f69f062368dd (Documentation Basics): Explain the xref to Documentation Tips.
Richard M. Stallman <rms@gnu.org>
parents: 60265
diff changeset
60 (@code{describe-variable}) to view the documentation string. There
f69f062368dd (Documentation Basics): Explain the xref to Documentation Tips.
Richard M. Stallman <rms@gnu.org>
parents: 60265
diff changeset
61 are many other conventions for doc strings; see @ref{Documentation
f69f062368dd (Documentation Basics): Explain the xref to Documentation Tips.
Richard M. Stallman <rms@gnu.org>
parents: 60265
diff changeset
62 Tips}.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
63
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
64 Documentation strings can contain several special substrings, which
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
65 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
66 documentation is displayed. This allows documentation strings to refer
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
67 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
68 rearranges the key bindings. (@xref{Keys in Documentation}.)
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
69
73396
26873f2f6a26 (Documentation): Move xref to Emacs Manual here.
Richard M. Stallman <rms@gnu.org>
parents: 70904
diff changeset
70 @vindex emacs-lisp-docstring-fill-column
26873f2f6a26 (Documentation): Move xref to Emacs Manual here.
Richard M. Stallman <rms@gnu.org>
parents: 70904
diff changeset
71 Emacs Lisp mode fills documentation strings to the width
73397
4aa300075af8 Fix prev change.
Richard M. Stallman <rms@gnu.org>
parents: 73396
diff changeset
72 specified by @code{emacs-lisp-docstring-fill-column}.
73396
26873f2f6a26 (Documentation): Move xref to Emacs Manual here.
Richard M. Stallman <rms@gnu.org>
parents: 70904
diff changeset
73
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
74 In Emacs Lisp, a documentation string is accessible through the
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
75 function or variable that it describes:
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 @itemize @bullet
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
78 @item
60265
74accd79beb7 (Documentation Basics): Add function-documentation prop.
Richard M. Stallman <rms@gnu.org>
parents: 56213
diff changeset
79 @kindex function-documentation
74accd79beb7 (Documentation Basics): Add function-documentation prop.
Richard M. Stallman <rms@gnu.org>
parents: 56213
diff changeset
80 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
81 definition itself (@pxref{Lambda Expressions}). The function
74accd79beb7 (Documentation Basics): Add function-documentation prop.
Richard M. Stallman <rms@gnu.org>
parents: 56213
diff changeset
82 @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
83 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
84 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
85 keyboard macros that can't hold a documentation string.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
86
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
87 @item
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
88 @kindex variable-documentation
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
89 The documentation for a variable is stored in the variable's property
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
90 list under the property name @code{variable-documentation}. The
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
91 function @code{documentation-property} knows how to retrieve it.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
92 @end itemize
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
93
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
94 @cindex @file{DOC} (documentation) file
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
95 @cindex @file{emacs/etc/DOC-@var{version}}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
96 @cindex @file{etc/DOC-@var{version}}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
97 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
98 (including primitive functions and autoloaded functions) is stored in
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
99 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
100 documentation strings for functions and variables loaded during the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
101 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
102 (@pxref{Docs and Compilation}).
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7254
diff changeset
103
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7254
diff changeset
104 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
105 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
106 documentation string. The functions @code{documentation} and
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
107 @code{documentation-property} use that information to fetch the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
108 documentation string from the appropriate file; this is transparent to
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
109 the user.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
110
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
111 @c Wordy to prevent overfull hbox. --rjc 15mar92
6708
3d0ab51bfa03 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6381
diff changeset
112 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
113 use to print nice-looking hardcopy for the file
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
114 @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
115 @file{digest-doc}.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
116
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
117 @node Accessing Documentation
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
118 @section Access to Documentation Strings
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
119
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
120 @defun documentation-property symbol property &optional verbatim
39221
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
121 This function returns the documentation string that is recorded in
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
122 @var{symbol}'s property list under property @var{property}. It
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
123 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
124 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
125 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
126
63583
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63540
diff changeset
127 The last thing this function does is pass the string through
39221
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
128 @code{substitute-command-keys} to substitute actual key bindings,
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
129 unless @var{verbatim} is non-@code{nil}.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
130
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
131 @smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
132 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
133 (documentation-property 'command-line-processed
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
134 'variable-documentation)
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
135 @result{} "Non-nil once command line has been processed"
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
136 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
137 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
138 (symbol-plist 'command-line-processed)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
139 @result{} (variable-documentation 188902)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
140 @end group
67700
81bada12a00e (Help Functions): Update documentation of `apropos'.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
141 @group
81bada12a00e (Help Functions): Update documentation of `apropos'.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
142 (documentation-property 'emacs 'group-documentation)
81bada12a00e (Help Functions): Update documentation of `apropos'.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
143 @result{} "Customization of the One True Editor."
81bada12a00e (Help Functions): Update documentation of `apropos'.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
144 @end group
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
145 @end smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
146 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
147
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
148 @defun documentation function &optional verbatim
39221
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
149 This function returns the documentation string of @var{function}.
67700
81bada12a00e (Help Functions): Update documentation of `apropos'.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
150 @code{documentation} handles macros, named keyboard macros, and
81bada12a00e (Help Functions): Update documentation of `apropos'.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
151 special forms, as well as ordinary functions.
39221
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
152
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
153 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
154 @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
155 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
156 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
157 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
158 @code{documentation} extracts the documentation string from the actual
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
159 function definition, reading it from a file if called for.
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
160
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
161 Finally, unless @var{verbatim} is non-@code{nil}, it calls
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
162 @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
163 actual (current) key bindings.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
164
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
165 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
166 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
167 the function definition has no documentation string. In that case,
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
168 @code{documentation} returns @code{nil}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
169 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
170
67700
81bada12a00e (Help Functions): Update documentation of `apropos'.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
171 @defun face-documentation face
81bada12a00e (Help Functions): Update documentation of `apropos'.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
172 This function returns the documentation string of @var{face} as a
81bada12a00e (Help Functions): Update documentation of `apropos'.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
173 face.
81bada12a00e (Help Functions): Update documentation of `apropos'.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
174 @end defun
81bada12a00e (Help Functions): Update documentation of `apropos'.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
175
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
176 @c Wordy to prevent overfull hboxes. --rjc 15mar92
7254
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
177 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
178 @code{documentation-property}, to display the documentation strings for
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
179 several symbols in a @samp{*Help*} buffer.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
180
53481
454b1ca272b8 (Accessing Documentation): Add anchor.
Luc Teirlinck <teirllm@auburn.edu>
parents: 53298
diff changeset
181 @anchor{describe-symbols example}
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
182 @smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
183 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
184 (defun describe-symbols (pattern)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
185 "Describe the Emacs Lisp symbols matching PATTERN.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
186 All symbols that have PATTERN in their name are described
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
187 in the `*Help*' buffer."
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
188 (interactive "sDescribe symbols matching: ")
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
189 (let ((describe-func
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 39221
diff changeset
190 (function
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
191 (lambda (s)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
192 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
193 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
194 ;; @r{Print description of symbol.}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
195 (if (fboundp s) ; @r{It is a function.}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
196 (princ
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
197 (format "%s\t%s\n%s\n\n" s
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 39221
diff changeset
198 (if (commandp s)
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
199 (let ((keys (where-is-internal s)))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
200 (if keys
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
201 (concat
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
202 "Keys: "
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 39221
diff changeset
203 (mapconcat 'key-description
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
204 keys " "))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
205 "Keys: none"))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
206 "Function")
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 @group
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 39221
diff changeset
209 (or (documentation s)
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
210 "not documented"))))
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 39221
diff changeset
211
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
212 (if (boundp s) ; @r{It is a variable.}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
213 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
214 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
215 (princ
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
216 (format "%s\t%s\n%s\n\n" s
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 39221
diff changeset
217 (if (user-variable-p s)
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
218 "Option " "Variable")
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
219 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
220 @group
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 39221
diff changeset
221 (or (documentation-property
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
222 s 'variable-documentation)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
223 "not documented")))))))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
224 sym-list)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
225 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
226
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
227 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
228 ;; @r{Build a list of symbols that match pattern.}
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 39221
diff changeset
229 (mapatoms (function
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
230 (lambda (sym)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
231 (if (string-match pattern (symbol-name sym))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
232 (setq sym-list (cons sym sym-list))))))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
233 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
234
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
235 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
236 ;; @r{Display the data.}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
237 (with-output-to-temp-buffer "*Help*"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
238 (mapcar describe-func (sort sym-list 'string<))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
239 (print-help-return-message))))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
240 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
241 @end smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
242
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
243 The @code{describe-symbols} function works like @code{apropos},
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
244 but provides more information.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
245
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
246 @smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
247 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
248 (describe-symbols "goal")
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
249
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
250 ---------- Buffer: *Help* ----------
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 39221
diff changeset
251 goal-column Option
16736
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 13349
diff changeset
252 *Semipermanent goal column for vertical motion, as set by @dots{}
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
253 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
254 @c Do not blithely break or fill these lines.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
255 @c That makes them incorrect.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
256
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
257 @group
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
258 set-goal-column Keys: C-x C-n
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
259 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
260 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
261 @c DO NOT put a blank line here! That is factually inaccurate!
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
262 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
263 Those commands will move to this position in the line moved to
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
264 rather than trying to keep the same horizontal position.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
265 With a non-nil argument, clears out the goal column
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
266 so that C-n and C-p resume vertical motion.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
267 The goal column is stored in the variable `goal-column'.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
268 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
269
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
270 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
271 temporary-goal-column Variable
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
272 Current goal column for vertical motion.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
273 It is the column where point was
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
274 at the start of current run of vertical motion commands.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
275 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
276 ---------- Buffer: *Help* ----------
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
277 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
278 @end smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
279
31130
e9c859a12e47 Add a comment about the significance of an asterisk as the first
Eli Zaretskii <eliz@gnu.org>
parents: 27189
diff changeset
280 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
281 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
282 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
283 Variables}.
e9c859a12e47 Add a comment about the significance of an asterisk as the first
Eli Zaretskii <eliz@gnu.org>
parents: 27189
diff changeset
284
56213
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
285 @defun Snarf-documentation filename
53298
8066757520a8 (Accessing Documentation): Add anchor.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52401
diff changeset
286 @anchor{Definition of Snarf-documentation}
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
287 This function is used only during Emacs initialization, just before
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
288 the runnable Emacs is dumped. It finds the file offsets of the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
289 documentation strings stored in the file @var{filename}, and records
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
290 them in the in-core function definitions and variable property lists in
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
291 place of the actual strings. @xref{Building Emacs}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
292
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
293 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
294 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
295 for in the directory @code{doc-directory}. Usually @var{filename} is
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
296 @code{"DOC-@var{version}"}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
297 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
298
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
299 @c Emacs 19 feature
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
300 @defvar doc-directory
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
301 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
302 file @code{"DOC-@var{version}"} that contains documentation strings for
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
303 built-in and preloaded functions and variables.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
304
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
305 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
306 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
307 without actually installing it. @xref{Definition of data-directory}.
6381
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 In older Emacs versions, @code{exec-directory} was used for this.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
310 @end defvar
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
311
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
312 @node Keys in Documentation
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
313 @section Substituting Key Bindings in Documentation
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
314 @cindex documentation, keys in
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
315 @cindex keys in documentation strings
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
316 @cindex substituting keys in documentation
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
317
7254
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
318 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
319 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
320 sequences described below. Accessing documentation strings in the usual
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
321 way substitutes current key binding information for these special
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
322 sequences. This works by calling @code{substitute-command-keys}. You
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
323 can also call that function yourself.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
324
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
325 Here is a list of the special sequences and what they mean:
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
326
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
327 @table @code
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
328 @item \[@var{command}]
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
329 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
330 @var{command}} if @var{command} has no key bindings.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
331
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 39221
diff changeset
332 @item \@{@var{mapvar}@}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
333 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
334 @var{mapvar}. The summary is made using @code{describe-bindings}.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
335
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 39221
diff changeset
336 @item \<@var{mapvar}>
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
337 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
338 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
339 @samp{\[@var{command}]} sequences in this documentation string.
13349
1c9bf4febb14 Document \= in doc string.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
340
1c9bf4febb14 Document \= in doc string.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
341 @item \=
1c9bf4febb14 Document \= in doc string.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
342 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
343 @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
344 output.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
345 @end table
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
346
7254
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
347 @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
348 string in Emacs Lisp.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
349
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
350 @defun substitute-command-keys string
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
351 This function scans @var{string} for the above special sequences and
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
352 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
353 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
354 user's own customized key bindings.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
355 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
356
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
357 Here are examples of the special sequences:
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
358
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
359 @smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
360 @group
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 39221
diff changeset
361 (substitute-command-keys
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
362 "To abort recursive edit, type: \\[abort-recursive-edit]")
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
363 @result{} "To abort recursive edit, type: C-]"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
364 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
365
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
366 @group
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 39221
diff changeset
367 (substitute-command-keys
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
368 "The keys that are defined for the minibuffer here are:
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
369 \\@{minibuffer-local-must-match-map@}")
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
370 @result{} "The keys that are defined for the minibuffer here are:
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
371 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
372
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
373 ? minibuffer-completion-help
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
374 SPC minibuffer-complete-word
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
375 TAB minibuffer-complete
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
376 C-j minibuffer-complete-and-exit
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
377 RET minibuffer-complete-and-exit
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
378 C-g abort-recursive-edit
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
379 "
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
380
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
381 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
382 (substitute-command-keys
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
383 "To abort a recursive edit from the minibuffer, type\
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
384 \\<minibuffer-local-must-match-map>\\[abort-recursive-edit].")
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
385 @result{} "To abort a recursive edit from the minibuffer, type C-g."
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
386 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
387 @end smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
388
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
389 @node Describing Characters
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
390 @section Describing Characters for Help Messages
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
391
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
392 These functions convert events, key sequences, or characters to
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
393 textual descriptions. These descriptions are useful for including
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
394 arbitrary text characters or key sequences in messages, because they
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
395 convert non-printing and whitespace characters to sequences of printing
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
396 characters. The description of a non-whitespace printing character is
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
397 the character itself.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
398
56213
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
399 @defun key-description sequence &optional prefix
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
400 @cindex Emacs event standard notation
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
401 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
402 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
403 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
404 @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
405 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
406 information about valid events.
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
407
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
408 @smallexample
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
409 @group
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
410 (key-description [?\M-3 delete])
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
411 @result{} "M-3 <delete>"
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
412 @end group
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
413 @group
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
414 (key-description [delete] "\M-3")
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
415 @result{} "M-3 <delete>"
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
416 @end group
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
417 @end smallexample
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
418
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
419 See also the examples for @code{single-key-description}, below.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
420 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
421
39206
41ede3832703 (Describing Characters) <single-key-description>:
Eli Zaretskii <eliz@gnu.org>
parents: 31130
diff changeset
422 @defun single-key-description event &optional no-angles
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
423 @cindex event printing
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
424 @cindex character printing
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
425 @cindex control character printing
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
426 @cindex meta character printing
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
427 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
428 Emacs notation for keyboard input. A normal printing character
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39206
diff changeset
429 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
430 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
431 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
432 @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
433 @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
434 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
435
41ede3832703 (Describing Characters) <single-key-description>:
Eli Zaretskii <eliz@gnu.org>
parents: 31130
diff changeset
436 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
437 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
438 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
439 brackets.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
440
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
441 @smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
442 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
443 (single-key-description ?\C-x)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
444 @result{} "C-x"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
445 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
446 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
447 (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
448 @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
449 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
450 @group
39206
41ede3832703 (Describing Characters) <single-key-description>:
Eli Zaretskii <eliz@gnu.org>
parents: 31130
diff changeset
451 (single-key-description 'delete)
41ede3832703 (Describing Characters) <single-key-description>:
Eli Zaretskii <eliz@gnu.org>
parents: 31130
diff changeset
452 @result{} "<delete>"
41ede3832703 (Describing Characters) <single-key-description>:
Eli Zaretskii <eliz@gnu.org>
parents: 31130
diff changeset
453 @end group
41ede3832703 (Describing Characters) <single-key-description>:
Eli Zaretskii <eliz@gnu.org>
parents: 31130
diff changeset
454 @group
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
455 (single-key-description 'C-mouse-1)
39206
41ede3832703 (Describing Characters) <single-key-description>:
Eli Zaretskii <eliz@gnu.org>
parents: 31130
diff changeset
456 @result{} "<C-mouse-1>"
41ede3832703 (Describing Characters) <single-key-description>:
Eli Zaretskii <eliz@gnu.org>
parents: 31130
diff changeset
457 @end group
41ede3832703 (Describing Characters) <single-key-description>:
Eli Zaretskii <eliz@gnu.org>
parents: 31130
diff changeset
458 @group
41ede3832703 (Describing Characters) <single-key-description>:
Eli Zaretskii <eliz@gnu.org>
parents: 31130
diff changeset
459 (single-key-description 'C-mouse-1 t)
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
460 @result{} "C-mouse-1"
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 @end smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
463 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
464
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
465 @defun text-char-description character
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
466 This function returns a string describing @var{character} in the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
467 standard Emacs notation for characters that appear in text---like
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
468 @code{single-key-description}, except that control characters are
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
469 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
470 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
471 @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
472 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
473 for Meta.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
474
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
475 @smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
476 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
477 (text-char-description ?\C-c)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
478 @result{} "^C"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
479 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
480 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
481 (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
482 @result{} "\xed"
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
483 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
484 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
485 (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
486 @result{} "\x8d"
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
487 @end group
56213
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
488 @group
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
489 (text-char-description (+ 128 ?m))
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
490 @result{} "M-m"
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
491 @end group
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
492 @group
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
493 (text-char-description (+ 128 ?\C-m))
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
494 @result{} "M-^M"
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
495 @end group
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
496 @end smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
497 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
498
56213
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
499 @defun read-kbd-macro string &optional need-vector
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
500 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
501 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
502 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
503 it returns a string or vector containing the corresponding events.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
504 (This may or may not be a single valid key sequence, depending on what
70904
f137d96866f0 * keymaps.texi (Key Sequences): Renamed from Keymap Terminology.
Chong Yidong <cyd@stupidchicken.com>
parents: 68648
diff changeset
505 events you use; @pxref{Key Sequences}.) If @var{need-vector} is
56213
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
506 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
507 @end defun
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
508
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
509 @node Help Functions
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
510 @section Help Functions
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
511
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
512 Emacs provides a variety of on-line help functions, all accessible to
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
513 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
514 about them, see @ref{Help, , Help, emacs, The GNU Emacs Manual}. Here
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
515 we describe some program-level interfaces to the same information.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
516
67700
81bada12a00e (Help Functions): Update documentation of `apropos'.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
517 @deffn Command apropos pattern &optional do-all
56213
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
518 This function finds all ``meaningful'' symbols whose names contain a
67700
81bada12a00e (Help Functions): Update documentation of `apropos'.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
519 match for the apropos pattern @var{pattern}. An apropos pattern is
81bada12a00e (Help Functions): Update documentation of `apropos'.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
520 either a word to match, a space-separated list of words of which at
81bada12a00e (Help Functions): Update documentation of `apropos'.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
521 least two must match, or a regular expression (if any special regular
81bada12a00e (Help Functions): Update documentation of `apropos'.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
522 expression characters occur). A symbol is ``meaningful'' if it has a
81bada12a00e (Help Functions): Update documentation of `apropos'.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
523 definition as a function, variable, or face, or has properties.
81bada12a00e (Help Functions): Update documentation of `apropos'.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
524
81bada12a00e (Help Functions): Update documentation of `apropos'.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
525 The function returns a list of elements that look like this:
81bada12a00e (Help Functions): Update documentation of `apropos'.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
526
81bada12a00e (Help Functions): Update documentation of `apropos'.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
527 @example
67736
87587fc5c369 Fix previous change.
Richard M. Stallman <rms@gnu.org>
parents: 67700
diff changeset
528 (@var{symbol} @var{score} @var{fn-doc} @var{var-doc}
87587fc5c369 Fix previous change.
Richard M. Stallman <rms@gnu.org>
parents: 67700
diff changeset
529 @var{plist-doc} @var{widget-doc} @var{face-doc} @var{group-doc})
67700
81bada12a00e (Help Functions): Update documentation of `apropos'.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
530 @end example
81bada12a00e (Help Functions): Update documentation of `apropos'.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
531
81bada12a00e (Help Functions): Update documentation of `apropos'.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
532 Here, @var{score} is an integer measure of how important the symbol
81bada12a00e (Help Functions): Update documentation of `apropos'.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
533 seems to be as a match, and the remaining elements are documentation
81bada12a00e (Help Functions): Update documentation of `apropos'.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
534 strings for @var{symbol}'s various roles (or @code{nil}).
81bada12a00e (Help Functions): Update documentation of `apropos'.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
535
81bada12a00e (Help Functions): Update documentation of `apropos'.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
536 It also displays the symbols in a buffer named @samp{*Apropos*}, each
56213
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
537 with a one-line description taken from the beginning of its
67700
81bada12a00e (Help Functions): Update documentation of `apropos'.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
538 documentation string.
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 @c Emacs 19 feature
56213
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
541 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
542 @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
543 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
544 @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
545 them in the return value as well).
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
546 @end deffn
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
547
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
548 @defvar help-map
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
549 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
550 Help key, @kbd{C-h}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
551 @end defvar
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
552
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
553 @deffn {Prefix Command} help-command
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
554 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
555 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
556 follows:
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
557
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
558 @smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
559 @group
56213
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
560 (define-key global-map (char-to-string help-char) 'help-command)
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
561 (fset 'help-command help-map)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
562 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
563 @end smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
564 @end deffn
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
565
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
566 @defun print-help-return-message &optional function
7254
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
567 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
568 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
569 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
570 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
571
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
572 This function expects to be called inside a
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
573 @code{with-output-to-temp-buffer} special form, and expects
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
574 @code{standard-output} to have the value bound by that special form.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
575 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
576 Documentation}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
577 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
578
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
579 @defvar help-char
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
580 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
581 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
582 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
583 @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
584 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
585
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
586 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
587 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
588 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
589 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
590 features.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
591
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
592 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
593 binding as a subcommand of the prefix key, it runs
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
594 @code{describe-prefix-bindings}, which displays a list of all the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
595 subcommands of the prefix key.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
596 @end defvar
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
597
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
598 @defvar help-event-list
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
599 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
600 alternative ``help characters.'' These events are handled just like the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
601 event specified by @code{help-char}.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
602 @end defvar
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
603
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
604 @defvar help-form
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
605 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
606 whenever the character @code{help-char} is read. If evaluating the form
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
607 produces a string, that string is displayed.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
608
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
609 A command that calls @code{read-event} or @code{read-char} probably
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
610 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
611 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
612 some other meaning.) Evaluating this expression should result in a
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
613 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
614
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
615 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
616 @code{minibuffer-help-form} (@pxref{Definition of minibuffer-help-form}).
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
617 @end defvar
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
618
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
619 @defvar prefix-help-command
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
620 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
621 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
622 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
623 variable's default value is @code{describe-prefix-bindings}.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
624 @end defvar
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
625
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
626 @defun describe-prefix-bindings
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
627 This function calls @code{describe-bindings} to display a list of all
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
628 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
629 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
630 sequence. (The last event is, presumably, the help character.)
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
631 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
632
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
633 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
634 help without relinquishing control, such as the ``electric'' modes.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
635 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
636 ordinary help functions.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
637
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
638 @deffn Command Helper-describe-bindings
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
639 This command pops up a window displaying a help buffer containing a
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
640 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
641 It works by calling @code{describe-bindings}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
642 @end deffn
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
643
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
644 @deffn Command Helper-help
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
645 This command provides help for the current mode. It prompts the user
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
646 in the minibuffer with the message @samp{Help (Type ? for further
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
647 options)}, and then provides assistance in finding out what the key
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
648 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
649
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
650 This can be customized by changing the map @code{Helper-help-map}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
651 @end deffn
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
652
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
653 @c Emacs 19 feature
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
654 @defvar data-directory
56213
abaa918096d2 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54032
diff changeset
655 @anchor{Definition of data-directory}
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
656 This variable holds the name of the directory in which Emacs finds
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
657 certain documentation and text files that come with Emacs. In older
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
658 Emacs versions, @code{exec-directory} was used for this.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
659 @end defvar
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
660
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
661 @c Emacs 19 feature
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
662 @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
663 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
664 prefix key that shows a list of the subcommands it offers.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
665
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
666 When invoked, @var{fname} displays @var{help-text} in a window, then
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
667 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
668 string @var{help-text} should describe the bindings available in
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
669 @var{help-map}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
670
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
671 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
672 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
673 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
674 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
675 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
676 then returns.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
677
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
678 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
679 alternatives in @var{help-map}. In the current version of Emacs, this
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
680 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
681 @code{t}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
682
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
683 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
684 binding of @kbd{C-h C-h}.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
685 @end defmac
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
686
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
687 @defopt three-step-help
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
688 If this variable is non-@code{nil}, commands defined with
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
689 @code{make-help-screen} display their @var{help-line} strings in the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
690 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
691 if the user types the help character again.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
692 @end defopt
52401
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 49600
diff changeset
693
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 49600
diff changeset
694 @ignore
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 49600
diff changeset
695 arch-tag: ba36b4c2-e60f-49e2-bc25-61158fdcd815
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 49600
diff changeset
696 @end ignore