*** empty log message ***
[emacs.git] / man / help.texi
blob926ff03c2f865b78e4d23cc51c25ea60a951b309
1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985, 86, 87, 93, 94, 95, 97, 2000
3 @c   Free Software Foundation, Inc.
4 @c See file emacs.texi for copying conditions.
5 @node Help, Mark, M-x, Top
6 @chapter Help
7 @kindex Help
8 @cindex help
9 @cindex self-documentation
10 @findex help-command
11 @kindex C-h
12 @kindex F1
14   Emacs provides extensive help features accessible through a single
15 character, @kbd{C-h}.  @kbd{C-h} is a prefix key that is used only for
16 documentation-printing commands.  The characters that you can type after
17 @kbd{C-h} are called @dfn{help options}.  One help option is @kbd{C-h};
18 that is how you ask for help about using @kbd{C-h}.  To cancel, type
19 @kbd{C-g}.  The function key @key{F1} is equivalent to @kbd{C-h}.
21 @kindex C-h C-h
22 @findex help-for-help
23   @kbd{C-h C-h} (@code{help-for-help}) displays a list of the possible
24 help options, each with a brief description.  Before you type a help
25 option, you can use @key{SPC} or @key{DEL} to scroll through the list.
27   @kbd{C-h} or @key{F1} means ``help'' in various other contexts as
28 well.  For example, in the middle of @code{query-replace}, it describes
29 the options available for how to operate on the current match.  After a
30 prefix key, it displays a list of the alternatives that can follow the
31 prefix key.  (A few prefix keys don't support @kbd{C-h}, because they
32 define other meanings for it, but they all support @key{F1}.)
34   Most help buffers use a special major mode, Help mode, which lets you
35 scroll conveniently with @key{SPC} and @key{DEL}.  It also offers
36 hyperlinks to more help on cross-referenced names, Info nodes,
37 customization buffers and the like.  @xref{Help Mode}.
39 @cindex searching documentation efficiently
40 @cindex looking for a subject in documentation
41   If you are looking for a certain feature, but don't know where exactly
42 it is documented, and aren't even sure what is the name of the related
43 command or option, we recommend the following procedure:
45 @table @kbd
46 @item C-h a @var{topic} @key{RET}
47 This searches for commands whose names match @var{topic}.  @var{topic}
48 is a regular expression (@pxref{Regexps}).  Browse the buffer popped up
49 by Emacs, to find what you are looking for.  @xref{Apropos}.
51 @item M-x apropos @var{topic} @key{RET}
52 This works like @kbd{C-h a}, but it also searches for user options and
53 other variables, in case the feature you are looking for is controlled
54 by an option, not a command.  @xref{Apropos}.
56 @item C-h i emacs @key{RET} i @var{topic} @key{RET}
57 This looks up @var{topic} in the indices of the Emacs on-line manual.
58 Press @key{,} repetitively until you find what you are looking for.
60 @item C-h i emacs @key{RET} s @var{topic} @key{RET}
61 This works like the previous command, but it searches for @var{topic}
62 (which can be a regular expression) in the @emph{text} of the manual
63 rather than in its indices.
65 @item M-x apropos-documentation @var{topic} @key{RET}
66 This searches the @emph{documentation strings} (the built-in short
67 descriptions) of all variables and functions (not their names) for a
68 match for @var{topic}, a regular expression.  @xref{Apropos}.
70 @item C-h F
71 This brings up the Emacs FAQ, where you can use the usual search
72 commands (@pxref{Search}) to find the information.
74 @item C-h p
75 Finally, you can try looking up a suitable package using keywords
76 pertinent to the feature you need.  @xref{Library Keywords}.
77 @end table
79 @menu
80 * Help Summary::        Brief list of all Help commands.
81 * Key Help::            Asking what a key does in Emacs.
82 * Name Help::           Asking about a command, variable or function name.
83 * Apropos::             Asking what pertains to a given topic.
84 * Library Keywords::    Finding Lisp libraries by keywords (topics).
85 * Language Help::       Help relating to international language support.
86 * Help Mode::           Special features of Help mode and Help buffers.
87 * Misc Help::           Other help commands.
88 * Help Echo::           Help on active text and tooltips (`balloon help')
89 @end menu
91 @iftex
92 @node Help Summary
93 @end iftex
94 @ifinfo
95 @node Help Summary
96 @section Help Summary
97 @end ifinfo
99   Here is a summary of the defined help commands.
101 @table @kbd
102 @item C-h a @var{regexp} @key{RET}
103 Display a list of commands whose names match @var{regexp}
104 (@code{apropos-command}).
105 @item C-h b
106 Display a table of all key bindings in effect now, in this order: minor
107 mode bindings, major mode bindings, and global bindings
108 (@code{describe-bindings}).
109 @item C-h c @var{key}
110 Print the name of the command that @var{key} runs
111 (@code{describe-key-briefly}).  Here @kbd{c} stands for `character'.  For more
112 extensive information on @var{key}, use @kbd{C-h k}.
113 @item C-h f @var{function} @key{RET}
114 Display documentation on the Lisp function named @var{function}
115 (@code{describe-function}).  Since commands are Lisp functions,
116 a command name may be used.
117 @item C-h h
118 Display the @file{hello} file, which shows examples of various character
119 sets.
120 @item C-h i
121 Run Info, the program for browsing documentation files (@code{info}).
122 The complete Emacs manual is available on-line in Info.
123 @item C-h k @var{key}
124 Display the name and documentation of the command that @var{key} runs
125 (@code{describe-key}).
126 @item C-h l
127 Display a description of the last 100 characters you typed
128 (@code{view-lossage}).
129 @item C-h m
130 Display documentation of the current major mode (@code{describe-mode}).
131 @item C-h n
132 Display documentation of Emacs changes, most recent first
133 (@code{view-emacs-news}).
134 @item C-h P
135 Display info on known problems with Emacs and possible workarounds
136 (@code{view-emacs-problems}).
137 @item C-h p
138 Find packages by topic keyword (@code{finder-by-keyword}).
139 @item C-h s
140 Display current contents of the syntax table, plus an explanation of
141 what they mean (@code{describe-syntax}).  @xref{Syntax}.
142 @item C-h t
143 Enter the Emacs interactive tutorial (@code{help-with-tutorial}).
144 @item C-h v @var{var} @key{RET}
145 Display the documentation of the Lisp variable @var{var}
146 (@code{describe-variable}).
147 @item C-h w @var{command} @key{RET}
148 Print which keys run the command named @var{command} (@code{where-is}).
149 @item C-h C @var{coding} @key{RET}
150 Describe coding system @var{coding}
151 (@code{describe-coding-system}).
152 @item C-h C @key{RET}
153 Describe the coding systems currently in use.
154 @item C-h I @var{method} @key{RET}
155 Describe an input method (@code{describe-input-method}).
156 @item C-h L @var{language-env} @key{RET}
157 Describe information on the character sets, coding systems and input
158 methods used for language environment @var{language-env}
159 (@code{describe-language-environment}).
160 @item C-h C-c
161 Display the copying conditions for GNU Emacs.
162 @item C-h C-d
163 Display information about getting new versions of GNU Emacs.
164 @item C-h C-f @var{function} @key{RET}
165 Enter Info and go to the node documenting the Emacs function @var{function}
166 (@code{Info-goto-emacs-command-node}).
167 @item C-h C-k @var{key}
168 Enter Info and go to the node where the key sequence @var{key} is
169 documented (@code{Info-goto-emacs-key-command-node}).
170 @item C-h C-p
171 Display information about the GNU Project.
172 @item C-h @key{TAB} @var{symbol} @key{RET}
173 Display the Info documentation on symbol @var{symbol} according to the
174 programming language you are editing (@code{info-lookup-symbol}).
175 @end table
177 @node Key Help
178 @section Documentation for a Key
180 @kindex C-h c
181 @findex describe-key-briefly
182   The most basic @kbd{C-h} options are @kbd{C-h c}
183 (@code{describe-key-briefly}) and @w{@kbd{C-h k}} (@code{describe-key}).
184 @kbd{C-h c @var{key}} prints in the echo area the name of the command
185 that @var{key} is bound to.  For example, @kbd{C-h c C-f} prints
186 @samp{forward-char}.  Since command names are chosen to describe what
187 the commands do, this is a good way to get a very brief description of
188 what @var{key} does.
190 @kindex C-h k
191 @findex describe-key
192   @kbd{C-h k @var{key}} is similar but gives more information: it
193 displays the documentation string of the command as well as its name.
194 This is too big for the echo area, so a window is used for the display.
196   @kbd{C-h c} and @kbd{C-h k} work for any sort of key sequences,
197 including function keys and mouse events.
199 @node Name Help
200 @section Help by Command or Variable Name
202 @kindex C-h f
203 @findex describe-function
204   @kbd{C-h f} (@code{describe-function}) reads the name of a Lisp function
205 using the minibuffer, then displays that function's documentation string
206 in a window.  Since commands are Lisp functions, you can use this to get
207 the documentation of a command that you know by name.  For example,
209 @example
210 C-h f auto-fill-mode @key{RET}
211 @end example
213 @noindent
214 displays the documentation of @code{auto-fill-mode}.  This is the only
215 way to get the documentation of a command that is not bound to any key
216 (one which you would normally run using @kbd{M-x}).
218   @kbd{C-h f} is also useful for Lisp functions that you are planning to
219 use in a Lisp program.  For example, if you have just written the
220 expression @code{(make-vector len)} and want to check that you are using
221 @code{make-vector} properly, type @kbd{C-h f make-vector @key{RET}}.
222 Because @kbd{C-h f} allows all function names, not just command names,
223 you may find that some of your favorite abbreviations that work in
224 @kbd{M-x} don't work in @kbd{C-h f}.  An abbreviation may be unique
225 among command names yet fail to be unique when other function names are
226 allowed.
228   The function name for @kbd{C-h f} to describe has a default which is
229 used if you type @key{RET} leaving the minibuffer empty.  The default is
230 the function called by the innermost Lisp expression in the buffer around
231 point, @emph{provided} that is a valid, defined Lisp function name.  For
232 example, if point is located following the text @samp{(make-vector (car
233 x)}, the innermost list containing point is the one that starts with
234 @samp{(make-vector}, so the default is to describe the function
235 @code{make-vector}.
237   @kbd{C-h f} is often useful just to verify that you have the right
238 spelling for the function name.  If @kbd{C-h f} mentions a name from the
239 buffer as the default, that name must be defined as a Lisp function.  If
240 that is all you want to know, just type @kbd{C-g} to cancel the @kbd{C-h
241 f} command, then go on editing.
243 @kindex C-h w
244 @findex where-is
245   @kbd{C-h w @var{command} @key{RET}} tells you what keys are bound to
246 @var{command}.  It prints a list of the keys in the echo area.  If it
247 says the command is not on any key, you must use @kbd{M-x} to run it.
248 @kbd{C-h w} runs the command @code{where-is}.
250   @kbd{C-h v} (@code{describe-variable}) is like @kbd{C-h f} but describes
251 Lisp variables instead of Lisp functions.  Its default is the Lisp symbol
252 around or before point, but only if that is the name of a known Lisp
253 variable.  @xref{Variables}.@refill
255 Help buffers describing variables or functions defined in Lisp normally
256 have hyperlinks to their definitions if you have the Lisp source files
257 installed.  If you can read Lisp, this provides the ultimate
258 documentation.
259   
260 @node Apropos
261 @section Apropos
263 @kindex C-h a
264 @findex apropos-command
265 @cindex apropos
266   A more sophisticated sort of question to ask is, ``What are the
267 commands for working with files?''  To ask this question, type @kbd{C-h
268 a file @key{RET}}, which displays a list of all command names that
269 contain @samp{file}, including @code{copy-file}, @code{find-file}, and
270 so on.  With each command name appears a brief description of how to use
271 the command, and what keys you can currently invoke it with.  For
272 example, it would say that you can invoke @code{find-file} by typing
273 @kbd{C-x C-f}.  The @kbd{a} in @kbd{C-h a} stands for `Apropos';
274 @kbd{C-h a} runs the command @code{apropos-command}.  This command
275 normally checks only commands (interactive functions); if you specify a
276 prefix argument, it checks noninteractive functions as well.
278   Because @kbd{C-h a} looks only for functions whose names contain the
279 string you specify, you must use ingenuity in choosing the
280 string.  If you are looking for commands for killing backwards and
281 @kbd{C-h a kill-backwards @key{RET}} doesn't reveal any, don't give up.
282 Try just @kbd{kill}, or just @kbd{backwards}, or just @kbd{back}.  Be
283 persistent.  Also note that you can use a regular expression as the
284 argument, for more flexibility (@pxref{Regexps}).
286   Here is a set of arguments to give to @kbd{C-h a} that covers many
287 classes of Emacs commands, since there are strong conventions for naming
288 the standard Emacs commands.  By giving you a feel for the naming
289 conventions, this set should also serve to aid you in developing a
290 technique for picking @code{apropos} strings.
292 @quotation
293 char, line, word, sentence, paragraph, region, page, sexp, list, defun,
294 rect, buffer, frame, window, face, file, dir, register, mode, beginning, end,
295 forward, backward, next, previous, up, down, search, goto, kill, delete,
296 mark, insert, yank, fill, indent, case, change, set, what, list, find,
297 view, describe, default.
298 @end quotation
300 @findex apropos-variable
301   To list all user variables that match a regexp, use the command
302 @kbd{M-x apropos-variable}. This command shows only user variables and
303 customization options by default; if you specify a prefix argument, it
304 checks all variables.
306 @findex apropos
307   To list all Lisp symbols that contain a match for a regexp, not just
308 the ones that are defined as commands, use the command @kbd{M-x apropos}
309 instead of @kbd{C-h a}.  This command does not check key bindings by
310 default; specify a numeric argument if you want it to check them.
312 @findex apropos-documentation
313   The @code{apropos-documentation} command is like @code{apropos} except
314 that it searches documentation strings as well as symbol names for
315 matches for the specified regular expression.
317 @findex apropos-value
318   The @code{apropos-value} command is like @code{apropos} except that it
319 searches symbols' values for matches for the specified regular
320 expression.  This command does not check function definitions or
321 property lists by default; specify a numeric argument if you want it to
322 check them.
324 @vindex apropos-do-all
325   If the variable @code{apropos-do-all} is non-@code{nil}, the commands
326 above all behave as if they had been given a prefix argument.
328   If you want more information about a function definition, variable or
329 symbol property listed in the Apropos buffer, you can click on it with
330 @kbd{Mouse-2} or move there and type @key{RET}.
332 @node Library Keywords
333 @section Keyword Search for Lisp Libraries
335 @kindex C-h p
336 @findex finder-by-keyword
337 The @kbd{C-h p} command lets you search the standard Emacs Lisp
338 libraries by topic keywords.  Here is a partial list of keywords you can
339 use:
341 @display
342 abbrev --- abbreviation handling, typing shortcuts, macros.
343 bib --- support for the bibliography processor @code{bib}.
344 c --- C and C++ language support.
345 calendar --- calendar and time management support.
346 comm --- communications, networking, remote access to files.
347 data --- support for editing files of data.
348 docs --- support for Emacs documentation.
349 emulations --- emulations of other editors.
350 extensions --- Emacs Lisp language extensions.
351 faces --- support for using faces (fonts and colors; @pxref{Faces}).
352 frames --- support for Emacs frames and window systems.
353 games --- games, jokes and amusements.
354 hardware --- support for interfacing with exotic hardware.
355 help --- support for on-line help systems.
356 hypermedia --- support for links within text, or other media types.
357 i18n --- internationalization and alternate character-set support.
358 internal --- code for Emacs internals, build process, defaults.
359 languages --- specialized modes for editing programming languages.
360 lisp --- support for using Lisp (including Emacs Lisp).
361 local --- libraries local to your site.
362 maint --- maintenance aids for the Emacs development group.
363 mail --- modes for electronic-mail handling.
364 matching --- searching and matching.
365 news --- support for netnews reading and posting.
366 non-text --- support for editing files that are not ordinary text.
367 oop --- support for object-oriented programming.
368 outlines --- hierarchical outlining.
369 processes --- process, subshell, compilation, and job control support.
370 terminals --- support for terminal types.
371 tex --- support for the @TeX{} formatter.
372 tools --- programming tools.
373 unix --- front-ends/assistants for, or emulators of, Unix features.
374 vms --- support code for VMS.
375 wp --- word processing.
376 @end display
378 @node Language Help
379 @section Help for International Language Support
381   You can use the command @kbd{C-h L}
382 (@code{describe-language-environment}) to find out the support for a
383 specific language environment.  @xref{Language Environments}.  This
384 tells you which languages this language environment is useful for, and
385 lists the character sets, coding systems, and input methods that go with
386 it.  It also shows some sample text to illustrate scripts.
388   The command @kbd{C-h h} (@code{view-hello-file}) displays the file
389 @file{etc/HELLO}, which shows how to say ``hello'' in many languages.
391   The command @kbd{C-h I} (@code{describe-input-method}) describes
392 information about input methods---either a specified input method, or by
393 default the input method in use.  @xref{Input Methods}.
395   The command @kbd{C-h C} (@code{describe-coding-system}) describes
396 information about coding systems---either a specified coding system, or
397 the ones currently in use.  @xref{Coding Systems}.
399 @node Help Mode
400 @section Help Mode Commands
402   Help buffers provide the commands of View mode (@pxref{Misc File
403 Ops}), plus a few special commands of their own.
405 @table @kbd
406 @item @key{SPC}
407 Scroll forward.
408 @item @key{DEL}
409 Scroll backward.
410 @item @key{RET}
411 Follow a cross reference at point.
412 @item @key{TAB}
413 Move point forward to the next cross reference.
414 @item S-@key{TAB}
415 Move point back to the previous cross reference.
416 @item Mouse-2
417 Follow a cross reference that you click on.
418 @end table
420   When a command name (@pxref{M-x,, Running Commands by Name}) or
421 variable name (@pxref{Variables}) appears in the documentation, it
422 normally appears inside paired single-quotes.  You can click on the name
423 with @kbd{Mouse-2}, or move point there and type @key{RET}, to view the
424 documentation of that command or variable.  Use @kbd{C-c C-b} to retrace
425 your steps.
427 @kindex @key{TAB} @r{(Help mode)}
428 @findex help-next-ref
429 @kindex S-@key{TAB} @r{(Help mode)}
430 @findex help-previous-ref
431   There are convenient commands for moving point to cross references in
432 the help text.  @key{TAB} (@code{help-next-ref}) moves point down to the
433 next cross reference.  Use @kbd{S-@key{TAB}} to move point up to the
434 previous cross reference (@code{help-previous-ref}).
436 @node Misc Help
437 @section Other Help Commands
439 @kindex C-h i
440 @findex info
441 @cindex Info
442 @cindex manuals, on-line
443 @cindex on-line manuals
444   @kbd{C-h i} (@code{info}) runs the Info program, which is used for
445 browsing through structured documentation files.  The entire Emacs manual
446 is available within Info.  Eventually all the documentation of the GNU
447 system will be available.  Type @kbd{h} after entering Info to run
448 a tutorial on using Info.
450   If you specify a numeric argument, @kbd{C-h i} prompts for the name of
451 a documentation file.  This way, you can browse a file which doesn't
452 have an entry in the top-level Info menu.  It is also handy when you
453 need to get to the documentation quickly, and you know the exact name of
454 the file.
456 @kindex C-h C-f
457 @kindex C-h C-k
458 @findex Info-goto-emacs-key-command-node
459 @findex Info-goto-emacs-command-node
460   There are two special help commands for accessing Emacs documentation
461 through Info.  @kbd{C-h C-f @var{function} @key{RET}} enters Info and
462 goes straight to the documentation of the Emacs function
463 @var{function}.  @kbd{C-h C-k @var{key}} enters Info and goes straight
464 to the documentation of the key @var{key}.  These two keys run the
465 commands @code{Info-goto-emacs-command-node} and
466 @code{Info-goto-emacs-key-command-node}.
468   When editing a program, if you have an Info version of the manual for
469 the programming language, you can use the command @kbd{C-h C-i} to refer
470 to the manual documentation for a symbol (keyword, function or
471 variable).  The details of how this command works depend on the major
472 mode.
474 @kindex C-h l
475 @findex view-lossage
476   If something surprising happens, and you are not sure what commands you
477 typed, use @kbd{C-h l} (@code{view-lossage}).  @kbd{C-h l} prints the last
478 100 command characters you typed in.  If you see commands that you don't
479 know, you can use @kbd{C-h c} to find out what they do.
481 @kindex C-h m
482 @findex describe-mode
483   Emacs has numerous major modes, each of which redefines a few keys and
484 makes a few other changes in how editing works.  @kbd{C-h m}
485 (@code{describe-mode}) prints documentation on the current major mode,
486 which normally describes all the commands that are changed in this
487 mode.
489 @kindex C-h b
490 @findex describe-bindings
491   @kbd{C-h b} (@code{describe-bindings}) and @kbd{C-h s}
492 (@code{describe-syntax}) present other information about the current
493 Emacs mode.  @kbd{C-h b} displays a list of all the key bindings now in
494 effect; the local bindings defined by the current minor modes first,
495 then the local bindings defined by the current major mode, and finally
496 the global bindings (@pxref{Key Bindings}).  @kbd{C-h s} displays the
497 contents of the syntax table, with explanations of each character's
498 syntax (@pxref{Syntax}).
500   You can get a similar list for a particular prefix key by typing
501 @kbd{C-h} after the prefix key.  (There are a few prefix keys for which
502 this does not work---those that provide their own bindings for
503 @kbd{C-h}.  One of these is @key{ESC}, because @kbd{@key{ESC} C-h} is
504 actually @kbd{C-M-h}, which marks a defun.)
506 @kindex C-h F
507 @findex view-emacs-FAQ
508 @kindex C-h n
509 @findex view-emacs-news
510 @kindex C-h C-c
511 @findex describe-copying
512 @kindex C-h C-d
513 @findex describe-distribution
514 @kindex C-h C-w
515 @findex describe-no-warranty
516 @kindex C-h C-p
517 @findex describe-project
518 @kindex C-h P
519 @findex view-emacs-problems
520   The other @kbd{C-h} options display various files of useful
521 information.  @kbd{C-h C-w} displays the full details on the complete
522 absence of warranty for GNU Emacs.  @kbd{C-h n} (@code{view-emacs-news})
523 displays the file @file{emacs/etc/NEWS}, which contains documentation on
524 Emacs changes arranged chronologically.  @kbd{C-h F}
525 (@code{view-emacs-FAQ}) displays the Emacs frequently-answered-questions
526 list.  @kbd{C-h t} (@code{help-with-tutorial}) displays the
527 learn-by-doing Emacs tutorial.  @kbd{C-h C-c} (@code{describe-copying})
528 displays the file @file{emacs/etc/COPYING}, which tells you the
529 conditions you must obey in distributing copies of Emacs.  @kbd{C-h C-d}
530 (@code{describe-distribution}) displays the file
531 @file{emacs/etc/DISTRIB}, which tells you how you can order a copy of
532 the latest version of Emacs.  @kbd{C-h C-p} (@code{describe-project})
533 displays general information about the GNU Project.  @kbd{C-h P}
534 (@code{view-emacs-problems}) displays the file
535 @file{emacs/etc/PROBLEMS}, which lists known problems with Emacs in
536 various situations with solutions or workarounds in many cases.
538 @node Help Echo
539 @section Help on Active Text and Tooltips
541 @cindex tooltips
542 @cindex ballon help
543 Often when a region of text is `active' so that you can select it with
544 the mouse or a key like @kbd{RET}, it has associated help text.  Areas
545 of the mode line are examples.  This help will normally be printed in
546 the echo area when you move point into the active text.  In a window
547 system you can display the help text as `tooltips'.  @xref{Tooltips}.