Mercurial > hg > xemacs-beta

comparison man/xemacs/help.texi @ 0:376386a54a3c r19-14

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r19-14
author cvs
date Mon, 13 Aug 2007 08:45:50 +0200
parents
children 972bbb6d6ca2 abe6d1db359e
comparison
equal deleted inserted replaced
-1:000000000000 0:376386a54a3c
1
2 @node Help, Mark, M-x, Top
3 @chapter Help
4 @cindex help
5 @cindex self-documentation
6
7 Emacs provides extensive help features which revolve around a single
8 character, @kbd{C-h}. @kbd{C-h} is a prefix key that is used only for
9 documentation-printing commands. The characters you can type after
10 @kbd{C-h} are called @dfn{help options}. One help option is @kbd{C-h};
11 you use it to ask for help about using @kbd{C-h}.
12
13 @kbd{C-h C-h} prints a list of the possible help options, and then asks
14 you to type the desired option. It prompts with the string:
15
16 @smallexample
17 A, B, C, F, I, K, L, M, N, S, T, V, W, C-c, C-d, C-n, C-w or C-h for more help:
18 @end smallexample
19
20 @noindent
21 You should type one of those characters.
22
23 Typing a third @kbd{C-h} displays a description of what the options mean;
24 Emacs still waits for you to type an option. To cancel, type @kbd{C-g}.
25
26 Here is a summary of the defined help commands.
27
28 @table @kbd
29 @item C-h a @var{string} @key{RET}
30 Display a list of commands whose names contain @var{string}
31 (@code{command-@*apropos}).@refill
32 @item C-h b
33 Display a table of all key bindings currently in effect, with local bindings of
34 the current major mode first, followed by all global bindings
35 (@code{describe-bindings}).
36 @item C-h c @var{key}
37 Print the name of the command that @var{key} runs (@code{describe-key-@*briefly}).
38 @kbd{c} is for `character'. For more extensive information on @var{key},
39 use @kbd{C-h k}.
40 @item C-h f @var{function} @key{RET}
41 Display documentation on the Lisp function named @var{function}
42 (@code{describe-function}). Note that commands are Lisp functions, so
43 a command name may be used.
44 @item C-h i
45 Run Info, the program for browsing documentation files (@code{info}).
46 The complete Emacs manual is available online in Info.
47 @item C-h k @var{key}
48 Display name and documentation of the command @var{key} runs (@code{describe-key}).
49 @item C-h l
50 Display a description of the last 100 characters you typed
51 (@code{view-lossage}).
52 @item C-h m
53 Display documentation of the current major mode (@code{describe-mode}).
54 @item C-h n
55 Display documentation of Emacs changes, most recent first
56 (@code{view-emacs-news}).
57 @item C-h p
58 Display a table of all mouse bindings currently in effect now, with
59 local bindings of the current major mode first, followed by all global bindings
60 (@code{describe-pointer}).
61 @item C-h s
62 Display current contents of the syntax table, plus an explanation of
63 what they mean (@code{describe-syntax}).
64 @item C-h t
65 Display the Emacs tutorial (@code{help-with-tutorial}).
66 @item C-h v @var{var} @key{RET}
67 Display the documentation of the Lisp variable @var{var}
68 (@code{describe-@*variable}).
69 @item C-h w @var{command} @key{RET}
70 Print which keys run the command named @var{command} (@code{where-is}).
71 @item M-x apropos @var{regexp}
72 Show all symbols whose names contain matches for @var{regexp}.
73 @end table
74
75 @section Documentation for a Key
76
77 @kindex C-h c
78 @findex describe-key-briefly
79 The most basic @kbd{C-h} options are @kbd{C-h c}
80 (@code{describe-key-briefly}) and @kbd{C-h k}@*(@code{describe-key}).
81 @kbd{C-h c @var{key}} prints the name of the command that @var{key} is
82 bound to in the echo area. For example, @kbd{C-h c C-f} prints
83 @samp{forward-char}. Since command names are chosen to describe what
84 the command does, using this option is a good way to get a somewhat cryptic
85 description of what @var{key} does.@refill
86
87 @kindex C-h k
88 @findex describe-key
89 @kbd{C-h k @var{key}} is similar to @kbd{C-h c} but gives more
90 information. It displays the documentation string of the function
91 @var{key} is bound to as well as its name. @var{key} is a string or
92 vector of events. When called interactively, @var{key} may also be a menu
93 selection. This information does not usually fit into the echo area, so a
94 window is used for the display.
95
96 @section Help by Command or Variable Name
97
98 @kindex C-h f
99 @findex describe-function
100 @vindex describe-function-show-arglist
101 @kbd{C-h f} (@code{describe-function}) reads the name of a Lisp
102 function using the minibuffer, then displays that function's
103 documentation string in a window. Since commands are Lisp functions,
104 you can use the argument @var{function} to get the documentation of a
105 command that you know by name. For example,
106
107 @example
108 C-h f auto-fill-mode @key{RET}
109 @end example
110
111 @noindent
112 displays the documentation for @code{auto-fill-mode}. Using @kbd{C-h f}
113 is the only way to see the documentation of a command that is not bound
114 to any key, that is, a command you would normally call using @kbd{M-x}.
115 If the variable @code{describe-function-show-arglist} is @code{t},
116 @code{describe-function} shows its arglist if the @var{function} is not
117 an autoload function.
118
119 @kbd{C-h f} is also useful for Lisp functions you are planning to
120 use in a Lisp program. For example, if you have just written the code
121 @code{(make-vector len)} and want to make sure you are using
122 @code{make-vector} properly, type @kbd{C-h f make-vector @key{RET}}. Because
123 @kbd{C-h f} allows all function names, not just command names, you may find
124 that some of your favorite abbreviations that work in @kbd{M-x} don't work
125 in @kbd{C-h f}. An abbreviation may be unique among command names, yet fail
126 to be unique when other function names are allowed.
127
128
129 If you type @key{RET}, leaving the minibuffer empty, @kbd{C-h f} by
130 default describes the function called by the innermost Lisp expression
131 in the buffer around point, @i{provided} that that is a valid, defined Lisp
132 function name. For example, if point is located following the text
133 @samp{(make-vector (car x)}, the innermost list containing point is the
134 one starting with @samp{(make-vector}, so the default is to describe
135 the function @code{make-vector}.
136
137 @kbd{C-h f} is often useful just to verify that you have the right
138 spelling for the function name. If @kbd{C-h f} mentions a default in the
139 prompt, you have typed the name of a defined Lisp function. If that is
140 what you wanted to know, just type @kbd{C-g} to cancel the @kbd{C-h f}
141 command and continue editing.
142
143 @kindex C-h w
144 @findex where-is
145 @kbd{C-h w @var{command} @key{RET}} (@code{where-s}) tells you what
146 keys are bound to @var{command}. It prints a list of the keys in the
147 echo area. Alternatively, it informs you that a command is not bound to
148 any keys, which implies that you must use @kbd{M-x} to call the
149 command.@refill
150
151 @kindex C-h v
152 @findex describe-variable
153 @kbd{C-h v} (@code{describe-variable}) is like @kbd{C-h f} but
154 describes Lisp variables instead of Lisp functions. Its default is the
155 Lisp symbol around or before point, if that is the name of a known Lisp
156 variable. @xref{Variables}.@refill
157
158 @section Apropos
159
160 @kindex C-h a
161 @findex command-apropos
162 @cindex apropos
163
164 @table @kbd
165 @item C-h a
166 Show only symbols that are names of commands
167 (@code{command-apropos}).@refill
168
169 @item M-x apropos @var{regexp}
170 Show all symbols whose names comtain matches for @var{regexp}.
171 @end table
172
173 It is possible to ask a question like, ``What are the commands for
174 working with files?'' To do this, type @kbd{C-h a file @key{RET}},
175 which displays a list of all command names that contain @samp{file},
176 such as @code{copy-file}, @code{find-file}, and so on. With each
177 command name a brief description of its use and information on the keys
178 you can use to invoke it is displayed. For example, you would be
179 informed that you can invoke @code{find-file} by typing @kbd{C-x C-f}.
180 The @kbd{a} in @kbd{C-h a} stands for `Apropos'; @kbd{C-h a} runs the
181 Lisp function @code{command-apropos}.@refill
182
183 Because @kbd{C-h a} looks only for functions whose names contain the
184 string you specify, you must use ingenuity in choosing the string. If
185 you are looking for commands for killing backwards and @kbd{C-h a
186 kill-backwards @key{RET}} doesn't reveal any commands, don't give up.
187 Try just @kbd{kill}, or just @kbd{backwards}, or just @kbd{back}. Be
188 persistent. Pretend you are playing Adventure. Also note that you can
189 use a regular expression as the argument (@pxref{Regexps}).
190
191 Here is a set of arguments to give to @kbd{C-h a} that covers many
192 classes of Emacs commands, since there are strong conventions for naming
193 standard Emacs commands. By giving you a feeling for the naming
194 conventions, this set of arguments can also help you develop a
195 technique for picking @code{apropos} strings.
196
197 @quotation
198 char, line, word, sentence, paragraph, region, page, sexp, list, defun,
199 buffer, frame, window, file, dir, register, mode,
200 beginning, end, forward, backward, next, previous, up, down, search, goto,
201 kill, delete, mark, insert, yank, fill, indent, case,
202 change, set, what, list, find, view, describe.
203 @end quotation
204
205 @findex apropos
206 To list all Lisp symbols that contain a match for a regexp, not just
207 the ones that are defined as commands, use the command @kbd{M-x apropos}
208 instead of @kbd{C-h a}.
209
210 @section Other Help Commands
211
212 @kindex C-h i
213 @findex info
214 @kbd{C-h i} (@code{info}) runs the Info program, which is used for
215 browsing through structured documentation files. The entire Emacs manual
216 is available within Info. Eventually all the documentation of the GNU
217 system will be available. Type @kbd{h} after entering Info to run
218 a tutorial on using Info.
219
220 @kindex C-h l
221 @findex view-lossage
222 If something surprising happens, and you are not sure what commands you
223 typed, use @kbd{C-h l} (@code{view-lossage}). @kbd{C-h l} prints the last
224 100 command characters you typed. If you see commands you don't
225 know, use @kbd{C-h c} to find out what they do.
226
227 @kindex C-h m
228 @findex describe-mode
229 Emacs has several major modes. Each mode redefines a few keys and
230 makes a few other changes in how editing works. @kbd{C-h m}
231 (@code{describe-mode}) prints documentation on the current major mode,
232 which normally describes all the commands that are changed in this mode.
233
234 @kindex C-h b
235 @findex describe-bindings
236 @kbd{C-h b} (@code{describe-bindings}) and @kbd{C-h s}
237 (@code{describe-syntax}) present information about the current Emacs
238 mode that is not covered by @kbd{C-h m}. @kbd{C-h b} displays a list of
239 all key bindings currently in effect, with the local bindings of the current
240 major mode first, followed by the global bindings (@pxref{Key
241 Bindings}). @kbd{C-h s} displays the contents of the syntax table with
242 explanations of each character's syntax (@pxref{Syntax}).@refill
243
244 @kindex C-h n
245 @findex view-emacs-news
246 @kindex C-h t
247 @findex help-with-tutorial
248 @kindex C-h C-c
249 @findex describe-copying
250 @kindex C-h C-d
251 @findex describe-distribution
252 @kindex C-h C-w
253 @findex describe-no-warranty
254 The other @kbd{C-h} options display various files of useful
255 information. @kbd{C-h C-w} (@code{describe-no-warranty}) displays
256 details on the complete absence of warranty for XEmacs. @kbd{C-h n}
257 (@code{view-emacs-news}) displays the file @file{emacs/etc/NEWS}, which
258 contains documentation on Emacs changes arranged chronologically.
259 @kbd{C-h t} (@code{help-with-tutorial}) displays the learn-by-doing
260 Emacs tutorial. @kbd{C-h C-c} (@code{describe-copying}) displays the file
261 @file{emacs/etc/COPYING}, which tells you the conditions you must obey
262 in distributing copies of Emacs. @kbd{C-h C-d}
263 (@code{describe-distribution}) displays another file named
264 @file{emacs/etc/DISTRIB}, which tells you how you can order a copy of
265 the latest version of Emacs.@refill