annotate lispref/help.texi @ 7379:822429149720

(hide-ifdef-syntax-table): New variable. (hif-tokenize): Use it. (hide-ifdef-mode): Don't clobber `c-mode-syntax-table'.
author Karl Heuer <kwzh@gnu.org>
date Sat, 07 May 1994 01:42:48 +0000
parents ae9c4159e36a
children a6eb5f12b0f3
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.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4 @c See the file elisp.texi for copying conditions.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
5 @setfilename ../info/help
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
6 @node Documentation, Files, Modes, Top
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
7 @chapter Documentation
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
8 @cindex documentation strings
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
9
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
10 GNU Emacs Lisp has convenient on-line help facilities, most of which
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
11 derive their information from the documentation strings associated with
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
12 functions and variables. This chapter describes how to write good
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
13 documentation strings for your Lisp programs, as well as how to write
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
14 programs to access documentation.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
15
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
16 Note that the documentation strings for Emacs are not the same thing
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
17 as the Emacs manual. Manuals have their own source files, written in
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
18 the Texinfo language; documentation strings are specified in the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
19 definitions of the functions and variables they apply to. A collection
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
20 of documentation strings is not sufficient as a manual because a good
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
21 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
22 topics of discussion.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
23
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
24 @menu
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
25 * Documentation Basics:: Good style for doc strings.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
26 Where to put them. How Emacs stores them.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
27 * Accessing Documentation:: How Lisp programs can access doc strings.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
28 * Keys in Documentation:: Substituting current key bindings.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
29 * Describing Characters:: Making printable descriptions of
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
30 non-printing characters and key sequences.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
31 * Help Functions:: Subroutines used by Emacs help facilities.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
32 @end menu
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
33
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
34 @node Documentation Basics
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
35 @comment node-name, next, previous, up
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
36 @section Documentation Basics
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
37 @cindex documentation conventions
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
38 @cindex writing a documentation string
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
39 @cindex string, writing a doc string
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
40
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
41 A documentation string is written using the Lisp syntax for strings,
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
42 with double-quote characters surrounding the text of the string. This
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
43 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
44 documentation when it is written in the proper place in the definition
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
45 of a function or variable. In a function definition, the documentation
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
46 string follows the argument list. In a variable definition, the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
47 documentation string follows the initial value of the variable.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
48
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
49 When you write a documentation string, make the first line a complete
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
50 sentence (or two complete sentences) since some commands, such as
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
51 @code{apropos}, show only the first line of a multi-line documentation
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
52 string. Also, you should not indent the second line of a documentation
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
53 string, if you have one, because that looks odd when you use @kbd{C-h f}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
54 (@code{describe-function}) or @kbd{C-h v} (@code{describe-variable}).
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
55 @xref{Documentation Tips}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
56
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
57 Documentation strings may contain several special substrings, which
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
58 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
59 documentation is displayed. This allows documentation strings to refer
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
60 to the keys for related commands and be accurate even when a user
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
61 rearranges the key bindings. (@xref{Accessing Documentation}.)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
62
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
63 Within the Lisp world, a documentation string is kept with the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
64 function or variable that it describes:
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
65
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
66 @itemize @bullet
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
67 @item
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
68 The documentation for a function is stored in the function definition
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
69 itself (@pxref{Lambda Expressions}). The function
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
70 @code{documentation} knows how to extract it.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
71
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
72 @item
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
73 @kindex variable-documentation
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
74 The documentation for a variable is stored in the variable's property
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
75 list under the property name @code{variable-documentation}. The
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
76 function @code{documentation-property} knows how to extract it.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
77 @end itemize
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
78
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
79 @cindex @file{DOC} (documentation) file
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
80 @cindex @file{emacs/etc/DOC-@var{version}}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
81 @cindex @file{etc/DOC-@var{version}}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
82 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
83 (including primitive functions and autoloaded functions) is stored in
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
84 the file @file{emacs/etc/DOC-@var{version}}. The data structure inside
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
85 Emacs has an integer offset into the file, where the documentation
7254
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
86 string ought to be. The functions @code{documentation} and
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
87 @code{documentation-property} read the documentation from the file
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
88 @file{emacs/etc/DOC-@var{version}} when they notice the integer there;
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
89 this is transparent to the user. Keeping the documentation strings out
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
90 of the Emacs core image saves a significant amount of space.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
91 @xref{Building Emacs}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
92
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
93 For information on the uses of documentation strings, see @ref{Help, ,
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
94 Help, emacs, The GNU Emacs Manual}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
95
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
96 @c Wordy to prevent overfull hbox. --rjc 15mar92
6708
3d0ab51bfa03 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6381
diff changeset
97 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
98 use to print nice-looking hardcopy for the file
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
99 @file{emacs/etc/DOC-@var{version}}. These are @file{sorted-doc.c} and
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
100 @file{digest-doc.c}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
101
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
102 @node Accessing Documentation
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
103 @section Access to Documentation Strings
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
104
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
105 @defun documentation-property symbol property &optional verbatim
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
106 This function returns the documentation string that is recorded
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
107 @var{symbol}'s property list under property @var{property}. It
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
108 retrieves the text from the file @file{emacs/etc/DOC-@var{version}} if
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
109 necessary, and runs @code{substitute-command-keys} to substitute actual
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
110 key bindings. (This substitution is not done if @var{verbatim} is
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
111 non-@code{nil}; the @var{verbatim} argument exists only as of Emacs 19.)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
112
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
113 @smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
114 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
115 (documentation-property 'command-line-processed
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
116 'variable-documentation)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
117 @result{} "t once command line has been processed"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
118 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
119 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
120 (symbol-plist 'command-line-processed)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
121 @result{} (variable-documentation 188902)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
122 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
123 @end smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
124 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
125
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
126 @defun documentation function &optional verbatim
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
127 This function returns the documentation string of @var{function}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
128 This function will access the documentation string if it is stored in
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
129 the @file{emacs/etc/DOC-@var{version}} file.
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 In addition, @code{documentation} runs @code{substitute-command-keys}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
132 on the resulting string, so the value contains the actual (current) key
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
133 bindings. (This is not done if @var{verbatim} is non-@code{nil}; the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
134 @var{verbatim} argument exists only as of Emacs 19.)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
135
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
136 The function @code{documentation} signals a @code{void-function} error
7254
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
137 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
138 the function definition has no documentation string. In that case,
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
139 @code{documentation} returns @code{nil}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
140 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
141
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
142 @c Wordy to prevent overfull hboxes. --rjc 15mar92
7254
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
143 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
144 @code{documentation-property}, to display the documentation strings for
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
145 several symbols in a @samp{*Help*} buffer.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
146
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
147 @smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
148 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
149 (defun describe-symbols (pattern)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
150 "Describe the Emacs Lisp symbols matching PATTERN.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
151 All symbols that have PATTERN in their name are described
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
152 in the `*Help*' buffer."
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
153 (interactive "sDescribe symbols matching: ")
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
154 (let ((describe-func
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
155 (function
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
156 (lambda (s)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
157 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
158 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
159 ;; @r{Print description of symbol.}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
160 (if (fboundp s) ; @r{It is a function.}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
161 (princ
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
162 (format "%s\t%s\n%s\n\n" s
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
163 (if (commandp s)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
164 (let ((keys (where-is-internal s)))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
165 (if keys
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
166 (concat
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
167 "Keys: "
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
168 (mapconcat 'key-description
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
169 keys " "))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
170 "Keys: none"))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
171 "Function")
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
172 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
173 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
174 (or (documentation s)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
175 "not documented"))))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
176
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
177 (if (boundp s) ; @r{It is a variable.}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
178 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
179 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
180 (princ
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
181 (format "%s\t%s\n%s\n\n" s
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
182 (if (user-variable-p s)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
183 "Option " "Variable")
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
184 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
185 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
186 (or (documentation-property
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
187 s 'variable-documentation)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
188 "not documented")))))))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
189 sym-list)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
190 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
191
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
192 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
193 ;; @r{Build a list of symbols that match pattern.}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
194 (mapatoms (function
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
195 (lambda (sym)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
196 (if (string-match pattern (symbol-name sym))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
197 (setq sym-list (cons sym sym-list))))))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
198 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
199
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
200 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
201 ;; @r{Display the data.}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
202 (with-output-to-temp-buffer "*Help*"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
203 (mapcar describe-func (sort sym-list 'string<))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
204 (print-help-return-message))))
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
205 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
206 @end smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
207
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
208 The @code{describe-symbols} function works like @code{apropos},
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
209 but provides more information.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
210
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
211 @smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
212 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
213 (describe-symbols "goal")
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
214
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
215 ---------- Buffer: *Help* ----------
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
216 goal-column Option
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
217 *Semipermanent goal column for vertical motion, as set by C-x C-n, or nil.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
218 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
219 @c Do not blithely break or fill these lines.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
220 @c That makes them incorrect.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
221
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
222 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
223 set-goal-column Command: C-x C-n
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
224 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
225 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
226 @c DO NOT put a blank line here! That is factually inaccurate!
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 Those commands will move to this position in the line moved to
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
229 rather than trying to keep the same horizontal position.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
230 With a non-nil argument, clears out the goal column
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
231 so that C-n and C-p resume vertical motion.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
232 The goal column is stored in the variable `goal-column'.
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 temporary-goal-column Variable
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
237 Current goal column for vertical motion.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
238 It is the column where point was
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
239 at the start of current run of vertical motion commands.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
240 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
241 ---------- Buffer: *Help* ----------
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
242 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
243 @end smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
244
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
245 @defun Snarf-documentation filename
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
246 This function is used only during Emacs initialization, just before
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
247 the runnable Emacs is dumped. It finds the file offsets of the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
248 documentation strings stored in the file @var{filename}, and records
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
249 them in the in-core function definitions and variable property lists in
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
250 place of the actual strings. @xref{Building Emacs}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
251
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
252 Emacs finds the file @var{filename} in the @file{emacs/etc} directory.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
253 When the dumped Emacs is later executed, the same file is found in the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
254 directory @code{doc-directory}. Usually @var{filename} is
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
255 @code{"DOC-@var{version}"}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
256 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
257
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
258 @c Emacs 19 feature
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
259 @defvar doc-directory
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
260 This variable holds the name of the directory which should contion the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
261 file @code{"DOC-@var{version}"} that contains documentation strings for
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
262 built-in and preloaded functions and variables.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
263
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
264 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
265 different when you run Emacs from the directory where you built it,
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
266 without actually installing it. See @code{data-directory} in @ref{Help
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
267 Functions}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
268
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
269 In older Emacs versions, @code{exec-directory} was used for this.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
270 @end defvar
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
271
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
272 @node Keys in Documentation
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
273 @section Substituting Key Bindings in Documentation
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
274 @cindex documentation, keys in
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
275 @cindex keys in documentation strings
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
276 @cindex substituting keys in documentation
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
277
7254
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
278 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
279 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
280 sequences described below. Accessing documentation strings in the usual
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
281 way substitutes current key binding information for these special
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
282 sequences. This works by calling @code{substitute-command-keys}. You
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
283 can also call that function yourself.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
284
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
285 Here is a list of the special sequences and what they mean:
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
286
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
287 @table @code
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
288 @item \[@var{command}]
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
289 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
290 @var{command}} if @var{command} has no key bindings.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
291
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
292 @item \@{@var{mapvar}@}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
293 stands for a summary of the value of @var{mapvar}, which should be a
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
294 keymap. The summary is made by @code{describe-bindings}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
295
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
296 @item \<@var{mapvar}>
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
297 stands for no text itself. It is used for a side effect: it specifies
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
298 @var{mapvar} as the keymap for any following @samp{\[@var{command}]}
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
299 sequences in this documentation string.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
300 @end table
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
301
7254
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
302 @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
303 string in Emacs Lisp.
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 @defun substitute-command-keys string
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
306 This function scans @var{string} for the above special sequences and
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
307 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
308 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
309 user's own customized key bindings.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
310 @end defun
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 Here are examples of the special sequences:
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
313
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
314 @smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
315 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
316 (substitute-command-keys
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
317 "To abort recursive edit, type: \\[abort-recursive-edit]")
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
318 @result{} "To abort recursive edit, type: C-]"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
319 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
320
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
321 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
322 (substitute-command-keys
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
323 "The keys that are defined for the minibuffer here are:
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
324 \\@{minibuffer-local-must-match-map@}")
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
325 @result{} "The keys that are defined for the minibuffer here are:
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
326 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
327
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
328 ? minibuffer-completion-help
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
329 SPC minibuffer-complete-word
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
330 TAB minibuffer-complete
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
331 LFD minibuffer-complete-and-exit
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
332 RET minibuffer-complete-and-exit
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
333 C-g abort-recursive-edit
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
334 "
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
335
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
336 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
337 (substitute-command-keys
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
338 "To abort a recursive edit from the minibuffer, type\
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
339 \\<minibuffer-local-must-match-map>\\[abort-recursive-edit].")
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
340 @result{} "To abort a recursive edit from the minibuffer, type C-g."
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
341 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
342 @end smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
343
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
344 @node Describing Characters
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
345 @section Describing Characters for Help Messages
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
346
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
347 These functions convert events, key sequences or characters to textual
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
348 descriptions. These descriptions are useful for including arbitrary
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
349 text characters or key sequences in messages, because they convert
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
350 non-printing and whitespace characters to sequences of printing
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
351 characters. The description of a non-whitespace printing character is
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
352 the character itself.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
353
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
354 @defun key-description sequence
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
355 @cindex Emacs event standard notation
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
356 This function returns a string containing the Emacs standard notation
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
357 for the input events in @var{sequence}. The argument @var{sequence} may
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
358 be a string, vector or list. @xref{Input Events}, for more information
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
359 about valid events. See also the examples for
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
360 @code{single-key-description}, below.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
361 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
362
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
363 @defun single-key-description event
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
364 @cindex event printing
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
365 @cindex character printing
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
366 @cindex control character printing
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
367 @cindex meta character printing
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
368 This function returns a string describing @var{event} in the standard
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
369 Emacs notation for keyboard input. A normal printing character appears
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
370 as itself, but a control character turns into a string starting with
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
371 @samp{C-}, a meta character turns into a string starting with @samp{M-},
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
372 and space, linefeed, etc.@: appear as @samp{SPC}, @samp{LFD}, etc. A
7254
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
373 function key symbol appears as itself. An event that is a list appears
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
374 as the name of the symbol in the @sc{car} of the list.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
375
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
376 @smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
377 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
378 (single-key-description ?\C-x)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
379 @result{} "C-x"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
380 @end group
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 (key-description "\C-x \M-y \n \t \r \f123")
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
383 @result{} "C-x SPC M-y SPC LFD SPC TAB SPC RET SPC C-l 1 2 3"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
384 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
385 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
386 (single-key-description 'C-mouse-1)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
387 @result{} "C-mouse-1"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
388 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
389 @end smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
390 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
391
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
392 @defun text-char-description character
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
393 This function returns a string describing @var{character} in the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
394 standard Emacs notation for characters that appear in text---like
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
395 @code{single-key-description}, except that control characters are
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
396 represented with a leading caret (which is how control characters in
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
397 Emacs buffers are usually displayed).
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
398
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
399 @smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
400 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
401 (text-char-description ?\C-c)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
402 @result{} "^C"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
403 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
404 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
405 (text-char-description ?\M-m)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
406 @result{} "M-m"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
407 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
408 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
409 (text-char-description ?\C-\M-m)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
410 @result{} "M-^M"
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
411 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
412 @end smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
413 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
414
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
415 @node Help Functions
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
416 @section Help Functions
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
417
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
418 Emacs provides a variety of on-line help functions, all accessible to
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
419 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
420 about them, see @ref{Help, , Help, emacs, The GNU Emacs Manual}. Here
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
421 we describe some program-level interfaces to the same information.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
422
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
423 @deffn Command apropos regexp &optional do-all predicate
7254
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
424 This function finds all symbols whose names contain a match for the
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
425 regular expression @var{regexp}, and returns a list of them
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
426 (@pxref{Regular Expressions}). It also displays the symbols in a buffer
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
427 named @samp{*Help*}, each with a one-line description.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
428
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
429 @c Emacs 19 feature
7254
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
430 If @var{do-all} is non-@code{nil}, then @code{apropos} also shows
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
431 key bindings for the functions that are found.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
432
7254
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
433 If @var{predicate} is non-@code{nil}, it should be a function to be
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
434 called on each symbol that has matched @var{regexp}. Only symbols for
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
435 which @var{predicate} returns a non-@code{nil} value are listed or
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
436 displayed.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
437
7254
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
438 In the first of the following examples, @code{apropos} finds all the
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
439 symbols with names containing @samp{exec}. In the second example, it
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
440 finds and returns only those symbols that are also commands.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
441 (We don't show the output that results in the @samp{*Help*} buffer.)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
442
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
443 @smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
444 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
445 (apropos "exec")
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
446 @result{} (Buffer-menu-execute command-execute exec-directory
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
447 exec-path execute-extended-command execute-kbd-macro
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
448 executing-kbd-macro executing-macro)
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
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
451 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
452 (apropos "exec" nil 'commandp)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
453 @result{} (Buffer-menu-execute execute-extended-command)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
454 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
455 @ignore
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
456 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
457 ---------- Buffer: *Help* ----------
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
458 Buffer-menu-execute
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
459 Function: Save and/or delete buffers marked with
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
460 M-x Buffer-menu-save or M-x Buffer-menu-delete commands.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
461 execute-extended-command ESC x
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
462 Function: Read function name, then read its
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
463 arguments and call it.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
464 ---------- Buffer: *Help* ----------
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
465 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
466 @end ignore
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
467 @end smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
468
7254
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
469 The command @kbd{C-h a} (@code{command-apropos}) calls @code{apropos},
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
470 but specifies a @var{predicate} to restrict the output to symbols that
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
471 are commands. The call to @code{apropos} looks like this:
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
472
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
473 @smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
474 (apropos string t 'commandp)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
475 @end smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
476 @end deffn
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
477
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
478 @c Emacs 19 feature
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
479 @deffn Command super-apropos regexp &optional do-all
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
480 This function differs from @code{apropos} in that it searches
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
481 documentation strings as well as symbol names for matches for
7254
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
482 @var{regexp}. By default, it searches the documentation strings only
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
483 for preloaded functions and variables. If @var{do-all} is
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
484 non-@code{nil}, it scans the names and documentation strings of all
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
485 functions and variables.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
486 @end deffn
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
487
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
488 @defvar help-map
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
489 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
490 Help key, @kbd{C-h}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
491 @end defvar
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
492
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
493 @deffn {Prefix Command} help-command
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
494 This symbol is not a function; its function definition is actually the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
495 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
496 follows:
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
497
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
498 @smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
499 @group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
500 (define-key global-map "\C-h" 'help-command)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
501 (fset 'help-command help-map)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
502 @end group
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
503 @end smallexample
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
504 @end deffn
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
505
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
506 @defun print-help-return-message &optional function
7254
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
507 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
508 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
509 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
510 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
511
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
512 This function expects to be called inside a
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
513 @code{with-output-to-temp-buffer} special form, and expects
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
514 @code{standard-output} to have the value bound by that special form.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
515 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
516 Documentation}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
517 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
518
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
519 @defvar help-char
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
520 The value of this variable is the help character---the character that
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
521 Emacs recognizes as meaning Help. By default, it is 8, which is
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
522 @kbd{C-h}. When Emacs reads this character, if @code{help-form} is
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
523 non-@code{nil} Lisp expression, it evaluates that expression, and
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
524 displays the result in a window if it is a string.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
525
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
526 Usually the value of @code{help-form}'s value is @code{nil}. Then the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
527 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
528 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
529 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
530 features.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
531
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
532 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
533 binding as a subcommand of the prefix key, it runs
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
534 @code{describe-prefix-bindings}, which displays a list of all the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
535 subcommands of the prefix key.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
536 @end defvar
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
537
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
538 @defvar help-form
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
539 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
540 whenever the character @code{help-char} is read. If evaluating the form
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
541 produces a string, that string is displayed.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
542
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
543 A command that calls @code{read-event} or @code{read-char} probably
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
544 should bind @code{help-form} to a non-@code{nil} expression while it
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
545 does input. (The exception is when @kbd{C-h} is meaningful input.)
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
546 Evaluating this expression should result in a string that explains what
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
547 the input is for and how to enter it properly.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
548
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
549 Entry to the minibuffer binds this variable to the value of
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
550 @code{minibuffer-help-form} (@pxref{Minibuffer Misc}).
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 @defvar prefix-help-command
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
554 This variable holds a function to print help for a prefix character.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
555 The function is called when the user types a prefix key followed by the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
556 help character, and the help character has no binding after that prefix.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
557 The variable's default value is @code{describe-prefix-bindings}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
558 @end defvar
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
559
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
560 @defun describe-prefix-bindings
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
561 This function calls @code{describe-bindings} to display a list of all
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
562 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
563 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
564 sequence. (The last event is, presumably, the help character.)
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
565 @end defun
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
566
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
567 The following two functions are found in the library @file{helper}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
568 They are for modes that want to provide help without relinquishing
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
569 control, such as the ``electric'' modes. You must load that library
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
570 with @code{(require 'helper)} in order to use them. Their names begin
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
571 with @samp{Helper} to distinguish them from the ordinary help functions.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
572
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
573 @deffn Command Helper-describe-bindings
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
574 This command pops up a window displaying a help buffer containing a
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
575 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
576 It works by calling @code{describe-bindings}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
577 @end deffn
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 @deffn Command Helper-help
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
580 This command provides help for the current mode. It prompts the user
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
581 in the minibuffer with the message @samp{Help (Type ? for further
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
582 options)}, and then provides assistance in finding out what the key
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
583 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
584
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
585 This can be customized by changing the map @code{Helper-help-map}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
586 @end deffn
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
587
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
588 @c Emacs 19 feature
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
589 @defvar data-directory
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
590 This variable holds the name of the directory in which Emacs finds
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
591 certain documentation and text files that come with Emacs. In older
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
592 Emacs versions, @code{exec-directory} was used for this.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
593 @end defvar
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
594
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
595 @c Emacs 19 feature
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
596 @defmac make-help-screen fname help-line help-text help-map
7254
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
597 This macro defines a help command named @var{fname} that acts like a
ae9c4159e36a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6708
diff changeset
598 prefix key that shows a list of the subcommands it offers.
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
599
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
600 When invoked, @var{fname} displays @var{help-text} in a window, then
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
601 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
602 string @var{help-text} should describe the bindings available in
6381
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
603 @var{help-map}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
604
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
605 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
606 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
607 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
608 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
609 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
610 then returns.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
611
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
612 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
613 alternatives in @var{help-map}. In the current version of Emacs, this
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
614 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
615 @code{t}.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
616 @end defmac
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
617
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
618 @defopt three-step-help
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
619 If this variable is non-@code{nil}, commands defined with
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
620 @code{make-help-screen} display their @var{help-line} strings in the
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
621 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
622 if the user types the help character again.
52f4a94c8c3d Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
623 @end defopt