1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012
3 @c Free Software Foundation, Inc.
4 @c See file emacs.texi for copying conditions.
5 @node Help, Mark, M-x, Top
9 @cindex self-documentation
16 Emacs provides a wide variety of help commands, all accessible
17 through the prefix key @kbd{C-h} (or, equivalently, the function key
18 @key{F1}). These help commands are described in the following
19 sections. You can also type @kbd{C-h C-h} to view a list of help
20 commands (@code{help-for-help}). You can scroll the list with
21 @key{SPC} and @key{DEL}, then type the help command you want. To
22 cancel, type @kbd{C-g}.
24 Many help commands display their information in a special @dfn{help
25 buffer}. In this buffer, you can type @key{SPC} and @key{DEL} to
26 scroll and type @key{RET} to follow hyperlinks. @xref{Help Mode}.
28 @cindex searching documentation efficiently
29 @cindex looking for a subject in documentation
30 If you are looking for a certain feature, but don't know what it is
31 called or where to look, we recommend three methods. First, try an
32 apropos command, then try searching the manual index, then look in the
33 FAQ and the package keywords.
36 @item C-h a @var{topics} @key{RET}
37 This searches for commands whose names match the argument
38 @var{topics}. The argument can be a keyword, a list of keywords, or a
39 regular expression (@pxref{Regexps}). @xref{Apropos}.
41 @item C-h i d m emacs @key{RET} i @var{topic} @key{RET}
42 This searches for @var{topic} in the indices of the Emacs Info manual,
43 displaying the first match found. Press @kbd{,} to see subsequent
44 matches. You can use a regular expression as @var{topic}.
46 @item C-h i d m emacs @key{RET} s @var{topic} @key{RET}
47 Similar, but searches the @emph{text} of the manual rather than the
51 This displays the Emacs FAQ, using Info.
54 This displays the available Emacs packages based on keywords.
55 @xref{Package Keywords}.
58 @kbd{C-h} or @key{F1} means ``help'' in various other contexts as
59 well. For instance, you can type them after a prefix key to view a
60 list of the keys that can follow the prefix key. (A few prefix keys
61 don't support @kbd{C-h} in this way, because they define other
62 meanings for it, but they all support @key{F1} for help.)
65 * Help Summary:: Brief list of all Help commands.
66 * Key Help:: Asking what a key does in Emacs.
67 * Name Help:: Asking about a command, variable or function name.
68 * Apropos:: Asking what pertains to a given topic.
69 * Help Mode:: Special features of Help mode and Help buffers.
70 * Package Keywords:: Finding Lisp libraries by keywords (topics).
71 * Language Help:: Help relating to international language support.
72 * Misc Help:: Other help commands.
73 * Help Files:: Commands to display auxiliary help files.
74 * Help Echo:: Help on active text and tooltips ("balloon help").
85 Here is a summary of help commands for accessing the built-in
86 documentation. Most of these are described in more detail in the
90 @item C-h a @var{topics} @key{RET}
91 Display a list of commands whose names match @var{topics}
92 (@code{apropos-command}).
94 Display all active key bindings; minor mode bindings first, then those
95 of the major mode, then global bindings (@code{describe-bindings}).
97 Show the name of the command that the key sequence @var{key} is bound
98 to (@code{describe-key-briefly}). Here @kbd{c} stands for
99 ``character.'' For more extensive information on @var{key}, use
101 @item C-h d @var{topics} @key{RET}
102 Display the commands and variables whose documentation matches
103 @var{topics} (@code{apropos-documentation}).
105 Display the @file{*Messages*} buffer
106 (@code{view-echo-area-messages}).
107 @item C-h f @var{function} @key{RET}
108 Display documentation on the Lisp function named @var{function}
109 (@code{describe-function}). Since commands are Lisp functions,
110 this works for commands too.
112 Display the @file{HELLO} file, which shows examples of various character
115 Run Info, the GNU documentation browser (@code{info}). The Emacs
116 manual is available in Info.
117 @item C-h k @var{key}
118 Display the name and documentation of the command that @var{key} runs
119 (@code{describe-key}).
121 Display a description of your last 300 keystrokes
122 (@code{view-lossage}).
124 Display documentation of the current major mode (@code{describe-mode}).
126 Display news of recent Emacs changes (@code{view-emacs-news}).
128 Find packages by topic keyword (@code{finder-by-keyword}). This lists
129 packages using a package menu buffer. @xref{Packages}.
130 @item C-h P @var{package} @key{RET}
131 Display documentation about the package named @var{package}
132 (@code{describe-package}).
134 Display the Emacs manual in Info (@code{info-emacs-manual}).
136 Display the contents of the current @dfn{syntax table}
137 (@code{describe-syntax}). The syntax table says which characters are
138 opening delimiters, which are parts of words, and so on. @xref{Syntax
139 Tables,, Syntax Tables, elisp, The Emacs Lisp Reference Manual}, for
142 Enter the Emacs interactive tutorial (@code{help-with-tutorial}).
143 @item C-h v @var{var} @key{RET}
144 Display the documentation of the Lisp variable @var{var}
145 (@code{describe-variable}).
146 @item C-h w @var{command} @key{RET}
147 Show which keys run the command named @var{command} (@code{where-is}).
148 @item C-h C @var{coding} @key{RET}
149 Describe the coding system @var{coding}
150 (@code{describe-coding-system}).
151 @item C-h C @key{RET}
152 Describe the coding systems currently in use.
153 @item C-h F @var{command} @key{RET}
154 Enter Info and go to the node that documents the Emacs command
155 @var{command} (@code{Info-goto-emacs-command-node}).
156 @item C-h I @var{method} @key{RET}
157 Describe the input method @var{method} (@code{describe-input-method}).
158 @item C-h K @var{key}
159 Enter Info and go to the node that documents the key sequence
160 @var{key} (@code{Info-goto-emacs-key-command-node}).
161 @item C-h L @var{language-env} @key{RET}
162 Display information on the character sets, coding systems, and input
163 methods used in language environment @var{language-env}
164 (@code{describe-language-environment}).
165 @item C-h S @var{symbol} @key{RET}
166 Display the Info documentation on symbol @var{symbol} according to the
167 programming language you are editing (@code{info-lookup-symbol}).
169 Display the help message for a special text area, if point is in one
170 (@code{display-local-help}). (These include, for example, links in
171 @file{*Help*} buffers.)
175 @section Documentation for a Key
177 @findex describe-key-briefly
179 The help commands to get information about a key sequence are
180 @kbd{C-h c} (@code{describe-key-briefly}) and @kbd{C-h k}
181 (@code{describe-key}).
184 @kbd{C-h c @var{key}} displays in the echo area the name of the
185 command that @var{key} is bound to. For example, @kbd{C-h c C-f}
186 displays @samp{forward-char}.
188 @cindex documentation string
190 @kbd{C-h k @var{key}} is similar but gives more information: it
191 displays a help buffer containing the command's @dfn{documentation
192 string}, which describes exactly what the command does.
195 @findex Info-goto-emacs-key-command-node
196 @kbd{C-h K @var{key}} displays the section of the Emacs manual that
197 describes the command corresponding to @var{key}.
199 @kbd{C-h c}, @kbd{C-h k} and @kbd{C-h K} work for any sort of key
200 sequences, including function keys, menus, and mouse events. For
201 instance, after @kbd{C-h k} you can select a menu item from the menu
202 bar, to view the documentation string of the command it runs.
206 @kbd{C-h w @var{command} @key{RET}} lists the keys that are bound to
207 @var{command}. It displays the list in the echo area. If it says the
208 command is not on any key, that means you must use @kbd{M-x} to run
209 it. @kbd{C-h w} runs the command @code{where-is}.
212 @section Help by Command or Variable Name
215 @findex describe-function
216 @kbd{C-h f @var{function} @key{RET}} (@code{describe-function})
217 displays the documentation of Lisp function @var{function}, in a
218 window. Since commands are Lisp functions, you can use this method to
219 view the documentation of any command whose name you know. For
223 C-h f auto-fill-mode @key{RET}
227 displays the documentation of @code{auto-fill-mode}. This is the only
228 way to get the documentation of a command that is not bound to any key
229 (one which you would normally run using @kbd{M-x}).
231 @kbd{C-h f} is also useful for Lisp functions that you use in a Lisp
232 program. For example, if you have just written the expression
233 @code{(make-vector len)} and want to check that you are using
234 @code{make-vector} properly, type @kbd{C-h f make-vector @key{RET}}.
235 Because @kbd{C-h f} allows all function names, not just command names,
236 you may find that some of your favorite completion abbreviations that
237 work in @kbd{M-x} don't work in @kbd{C-h f}. An abbreviation that is
238 unique among command names may not be unique among all function names.
240 If you type @kbd{C-h f @key{RET}}, it describes the function called
241 by the innermost Lisp expression in the buffer around point,
242 @emph{provided} that function name is a valid, defined Lisp function.
243 (That name appears as the default while you enter the argument.) For
244 example, if point is located following the text @samp{(make-vector
245 (car x)}, the innermost list containing point is the one that starts
246 with @samp{(make-vector}, so @kbd{C-h f @key{RET}} will describe the
247 function @code{make-vector}.
249 @kbd{C-h f} is also useful just to verify that you spelled a
250 function name correctly. If the minibuffer prompt for @kbd{C-h f}
251 shows the function name from the buffer as the default, it means that
252 name is defined as a Lisp function. Type @kbd{C-g} to cancel the
253 @kbd{C-h f} command if you don't really want to view the
257 @findex describe-variable
258 @kbd{C-h v} (@code{describe-variable}) is like @kbd{C-h f} but
259 describes Lisp variables instead of Lisp functions. Its default is
260 the Lisp symbol around or before point, if that is the name of a
261 defined Lisp variable. @xref{Variables}.
263 Help buffers that describe Emacs variables and functions normally
264 have hyperlinks to the corresponding source code, if you have the
265 source files installed (@pxref{Hyperlinking}).
268 @findex Info-goto-emacs-command-node
269 To find a command's documentation in a manual, use @kbd{C-h F}
270 (@code{Info-goto-emacs-command-node}). This knows about various
271 manuals, not just the Emacs manual, and finds the right one.
277 The @dfn{apropos} commands answer questions like, ``What are the
278 commands for working with files?'' More precisely, you specify an
279 @dfn{apropos pattern}, which means either a word, a list of words, or
280 a regular expression.
282 Each of the following apropos commands reads an apropos pattern in
283 the minibuffer, searches for items that match the pattern, and
284 displays the results in a different window.
289 @findex apropos-command
290 Search for commands (@code{apropos-command}). With a prefix argument,
291 search for noninteractive functions too.
295 Search for functions and variables. Both interactive functions
296 (commands) and noninteractive functions can be found by this.
298 @item M-x apropos-variable
299 @findex apropos-variable
300 Search for user-customizable variables. With a prefix argument,
301 search for non-customizable variables too.
303 @item M-x apropos-value
304 @findex apropos-value
305 Search for variables whose values match the specified pattern. With a
306 prefix argument, search also for functions with definitions matching
307 the pattern, and Lisp symbols with properties matching the pattern.
311 @findex apropos-documentation
312 Search for functions and variables whose documentation strings match
313 the specified pattern (@code{apropos-documentation}).
316 The simplest kind of apropos pattern is one word. Anything
317 containing that word matches the pattern. Thus, to find commands that
318 work on files, type @kbd{C-h a file @key{RET}}. This displays a list
319 of all command names that contain @samp{file}, including
320 @code{copy-file}, @code{find-file}, and so on. Each command name
321 comes with a brief description and a list of keys you can currently
322 invoke it with. In our example, it would say that you can invoke
323 @code{find-file} by typing @kbd{C-x C-f}.
325 For more information about a function definition, variable or symbol
326 property listed in an apropos buffer, you can click on it with
327 @kbd{Mouse-1} or @kbd{Mouse-2}, or move there and type @key{RET}.
329 When you specify more than one word in the apropos pattern, a name
330 must contain at least two of the words in order to match. Thus, if
331 you are looking for commands to kill a chunk of text before point, you
332 could try @kbd{C-h a kill back backward behind before @key{RET}}. The
333 real command name @code{kill-backward} will match that; if there were
334 a command @code{kill-text-before}, it would also match, since it
335 contains two of the specified words.
337 For even greater flexibility, you can specify a regular expression
338 (@pxref{Regexps}). An apropos pattern is interpreted as a regular
339 expression if it contains any of the regular expression special
340 characters, @samp{^$*+?.\[}.
342 Following the conventions for naming Emacs commands, here are some
343 words that you'll find useful in apropos patterns. By using them in
344 @kbd{C-h a}, you will also get a feel for the naming conventions.
347 char, line, word, sentence, paragraph, region, page, sexp, list, defun,
348 rect, buffer, frame, window, face, file, dir, register, mode, beginning, end,
349 forward, backward, next, previous, up, down, search, goto, kill, delete,
350 mark, insert, yank, fill, indent, case, change, set, what, list, find,
351 view, describe, default.
354 @vindex apropos-do-all
355 If the variable @code{apropos-do-all} is non-@code{nil}, the apropos
356 commands always behave as if they had been given a prefix argument.
358 @vindex apropos-sort-by-scores
359 @cindex apropos search results, order by score
360 @vindex apropos-documentation-sort-by-scores
361 By default, all apropos commands except @code{apropos-documentation}
362 list their results in alphabetical order. If the variable
363 @code{apropos-sort-by-scores} is non-@code{nil}, these commands
364 instead try to guess the relevance of each result, and display the
365 most relevant ones first. The @code{apropos-documentation} command
366 lists its results in order of relevance by default; to list them in
367 alphabetical order, change the variable
368 @code{apropos-documentation-sort-by-scores} to @code{nil}.
371 @section Help Mode Commands
373 Help buffers provide the same commands as View mode (@pxref{View
374 Mode}); for instance, @key{SPC} scrolls forward, and @key{DEL} scrolls
375 backward. A few special commands are also provided:
379 Follow a cross reference at point (@code{help-follow}).
381 Move point forward to the next hyperlink (@code{forward-button}).
383 Move point back to the previous hyperlink (@code{backward-button}).
386 Follow a hyperlink that you click on.
388 Show all documentation about the symbol at point
389 (@code{help-follow-symbol}).
391 Go back to the previous help topic (@code{help-go-back}).
397 @kindex RET @r{(Help mode)}
398 @kindex C-c C-b @r{(Help mode)}
399 When a function name, variable name, or face name (@pxref{Faces})
400 appears in the documentation in the help buffer, it is normally an
401 underlined @dfn{hyperlink}. To view the associated documentation,
402 move point there and type @key{RET} (@code{help-follow}), or click on
403 the hyperlink with @kbd{Mouse-1} or @kbd{Mouse-2}. Doing so replaces
404 the contents of the help buffer; to retrace your steps, type @kbd{C-c
405 C-b} (@code{help-go-back}).
407 @cindex URL, viewing in help
408 @cindex help, viewing web pages
409 @cindex viewing web pages in help
410 @cindex web pages, viewing in help
412 A help buffer can also contain hyperlinks to Info manuals, source
413 code definitions, and URLs (web pages). The first two are opened in
414 Emacs, and the third using a web browser via the @code{browse-url}
415 command (@pxref{Browse-URL}).
417 @kindex TAB @r{(Help mode)}
418 @findex forward-button
419 @kindex S-TAB @r{(Help mode)}
420 @findex backward-button
421 In a help buffer, @key{TAB} (@code{forward-button}) moves point
422 forward to the next hyperlink, while @kbd{S-@key{TAB}}
423 (@code{backward-button}) point back to the previous hyperlink. These
424 commands act cyclically; for instance, typing @key{TAB} at the last
425 hyperlink moves back to the first hyperlink.
427 To view all documentation about any symbol in the text, move point
428 to there and type @kbd{C-c C-c} (@code{help-follow-symbol}). This
429 shows all available documentation about the symbol---as a variable,
430 function and/or face.
432 @node Package Keywords
433 @section Keyword Search for Packages
436 Most optional features in Emacs are grouped into @dfn{packages}.
437 Emacs contains several hundred built-in packages, and more can be
438 installed over the network (@pxref{Packages}).
441 @findex finder-by-keyword
442 To make it easier to find packages related to a topic, most packages
443 are associated with one or more @dfn{keywords} based on what they do.
444 Type @kbd{C-h p} (@code{finder-by-keyword}) to bring up a list of
445 package keywords, together with a description of what the keywords
446 mean. To view a list of packages for a given keyword, type @key{RET}
447 on that line; this displays the list of packages in a Package Menu
448 buffer (@pxref{Package Menu}).
450 @findex describe-package
452 @kbd{C-h P} (@code{describe-package}) prompts for the name of a
453 package, and displays a help buffer describing the attributes of the
454 package and the features that it implements.
457 @section Help for International Language Support
459 For information on a specific language environment (@pxref{Language
460 Environments}), type @kbd{C-h L}
461 (@code{describe-language-environment}). This displays a help buffer
462 describing the languages supported by the language environment, and
463 listing the associated character sets, coding systems, and input
464 methods, as well as some sample text for that language environment.
466 The command @kbd{C-h h} (@code{view-hello-file}) displays the file
467 @file{etc/HELLO}, which demonstrates various character sets by showing
468 how to say ``hello'' in many languages.
470 The command @kbd{C-h I} (@code{describe-input-method}) describes an
471 input method---either a specified input method, or by default the
472 input method currently in use. @xref{Input Methods}.
474 The command @kbd{C-h C} (@code{describe-coding-system}) describes
475 coding systems---either a specified coding system, or the ones
476 currently in use. @xref{Coding Systems}.
479 @section Other Help Commands
484 @cindex manuals, on-line
485 @cindex on-line manuals
486 @kbd{C-h i} (@code{info}) runs the Info program, which browses
487 structured documentation files. The entire Emacs manual is available
488 within Info, along with many other manuals for the GNU system. Type
489 @kbd{h} after entering Info to run a tutorial on using Info.
491 @cindex find Info manual by its file name
492 With a numeric argument @var{n}, @kbd{C-h i} selects the Info buffer
493 @samp{*info*<@var{n}>}. This is useful if you want to browse multiple
494 Info manuals simultaneously. If you specify just @kbd{C-u} as the
495 prefix argument, @kbd{C-h i} prompts for the name of a documentation
496 file, so you can browse a file which doesn't have an entry in the
499 The help commands @kbd{C-h F @var{function} @key{RET}} and @kbd{C-h
500 K @var{key}}, described above, enter Info and go straight to the
501 documentation of @var{function} or @var{key}.
504 @findex info-lookup-symbol
505 When editing a program, if you have an Info version of the manual
506 for the programming language, you can use @kbd{C-h S}
507 (@code{info-lookup-symbol}) to find an entry for a symbol (keyword,
508 function or variable) in the proper manual. The details of how this
509 command works depend on the major mode.
513 If something surprising happens, and you are not sure what you typed,
514 use @kbd{C-h l} (@code{view-lossage}). @kbd{C-h l} displays your last
515 300 input keystrokes. If you see commands that you don't know, you can
516 use @kbd{C-h c} to find out what they do.
519 @findex view-echo-area-messages
520 To review recent echo area messages, use @kbd{C-h e}
521 (@code{view-echo-area-messages}). This displays the buffer
522 @file{*Messages*}, where those messages are kept.
525 @findex describe-mode
526 Each Emacs major mode typically redefines a few keys and makes other
527 changes in how editing works. @kbd{C-h m} (@code{describe-mode})
528 displays documentation on the current major mode, which normally
529 describes the commands and features that are changed in this mode.
532 @findex describe-bindings
533 @kbd{C-h b} (@code{describe-bindings}) and @kbd{C-h s}
534 (@code{describe-syntax}) show other information about the current
535 environment within Emacs. @kbd{C-h b} displays a list of all the key
536 bindings now in effect: first the local bindings of the current minor
537 modes, then the local bindings defined by the current major mode, and
538 finally the global bindings (@pxref{Key Bindings}). @kbd{C-h s}
539 displays the contents of the syntax table, with explanations of each
540 character's syntax (@pxref{Syntax Tables,, Syntax Tables, elisp, The
541 Emacs Lisp Reference Manual}).
543 @findex describe-prefix-bindings
544 You can get a list of subcommands for a particular prefix key by
545 typing @kbd{C-h} (@code{describe-prefix-bindings}) after the prefix
546 key. (There are a few prefix keys for which this does not
547 work---those that provide their own bindings for @kbd{C-h}. One of
548 these is @key{ESC}, because @kbd{@key{ESC} C-h} is actually
549 @kbd{C-M-h}, which marks a defun.)
554 Apart from the built-in documentation and manuals, Emacs contains
555 several other files describing topics like copying conditions, release
556 notes, instructions for debugging and reporting bugs, and so forth.
557 You can use the following commands to view these files. Apart from
558 @kbd{C-h g}, they all have the form @kbd{C-h C-@var{char}}.
561 @findex describe-copying
563 @findex view-emacs-debugging
565 @findex view-external-packages
567 @findex view-emacs-FAQ
569 @findex describe-gnu-project
571 @findex view-order-manuals
573 @findex view-emacs-news
575 @findex describe-distribution
577 @findex view-emacs-problems
579 @findex view-emacs-todo
581 @findex describe-no-warranty
585 Display the rules under which you can copy and redistribute Emacs
586 (@code{describe-copying}).
588 Display help for debugging Emacs (@code{view-emacs-debugging}).
590 Display information about where to get external packages
591 (@code{view-external-packages}).
593 Display the Emacs frequently-answered-questions list (@code{view-emacs-FAQ}).
595 Display information about the GNU Project (@code{describe-gnu-project}).
597 Display information about ordering printed copies of Emacs manuals
598 (@code{view-order-manuals}).
600 Display the ``news'' file, which lists the new features in this
601 version of Emacs (@code{view-emacs-news}).
603 Display how to order or download the latest version of
604 Emacs and other GNU software (@code{describe-distribution}).
606 Display the list of known Emacs problems, sometimes with suggested
607 workarounds (@code{view-emacs-problems}).
609 Display the Emacs to-do list (@code{view-emacs-todo}).
611 Display the full details on the complete absence of warranty for GNU
612 Emacs (@code{describe-no-warranty}).
616 @section Help on Active Text and Tooltips
620 In Emacs, stretches of ``active text'' (text that does something
621 special in response to mouse clicks or @key{RET}) often have
622 associated help text. This includes hyperlinks in Emacs buffers, as
623 well as parts of the mode line. On graphical displays, as well as
624 some text terminals which support mouse tracking, moving the mouse
625 over the active text displays the help text as a @dfn{tooltip}.
629 @findex display-local-help
630 @vindex help-at-pt-display-when-idle
631 On terminals that don't support mouse-tracking, you can display the
632 help text for active buffer text at point by typing @kbd{C-h .}
633 (@code{display-local-help}). This shows the help text in the echo
634 area. To display help text automatically whenever it is available at
635 point, set the variable @code{help-at-pt-display-when-idle} to