@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
+@c 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Help, Mark, M-x, Top
@chapter Help
@kindex F1
Emacs provides extensive help features accessible through a single
-character, @kbd{C-h}. @kbd{C-h} is a prefix key that is used only for
-documentation-printing commands. The characters that you can type after
-@kbd{C-h} are called @dfn{help options}. One help option is @kbd{C-h};
-that is how you ask for help about using @kbd{C-h}. To cancel, type
-@kbd{C-g}. The function key @key{F1} is equivalent to @kbd{C-h}.
+character, @kbd{C-h} (or @key{F1}). @kbd{C-h} is a prefix key that is
+used for commands that display documentation. The characters that you
+can type after @kbd{C-h} are called @dfn{help options}. One help
+option is @kbd{C-h}; that is how you ask for help about using
+@kbd{C-h}. To cancel, type @kbd{C-g}. The function key @key{F1} is
+equivalent to @kbd{C-h}.
@kindex C-h C-h
@findex help-for-help
@kbd{C-h C-h} (@code{help-for-help}) displays a list of the possible
-help options, each with a brief description. Before you type a help
-option, you can use @key{SPC} or @key{DEL} to scroll through the list.
+help options, each with a brief description. You can look at the
+list, using @key{SPC} and @key{DEL} to scroll through it, then type
+the help option you want. To cancel, type @kbd{C-g}.
@kbd{C-h} or @key{F1} means ``help'' in various other contexts as
-well. For example, in the middle of @code{query-replace}, it describes
-the options available for how to operate on the current match. After a
-prefix key, it displays a list of the alternatives that can follow the
-prefix key. (A few prefix keys don't support @kbd{C-h}, because they
-define other meanings for it, but they all support @key{F1}.)
+well. After a prefix key, it displays a list of the alternatives that
+can follow the prefix key. (A few prefix keys don't support
+@kbd{C-h}, because they define other meanings for it, but they all
+support @key{F1}.)
Most help buffers use a special major mode, Help mode, which lets you
-scroll conveniently with @key{SPC} and @key{DEL}.
+scroll conveniently with @key{SPC} and @key{DEL}. It also offers
+hyperlinks to URLs and further help regarding cross-referenced names, Info
+nodes, customization buffers and the like. @xref{Help Mode}.
+
+@cindex searching documentation efficiently
+@cindex looking for a subject in documentation
+ If you are looking for a certain feature, but don't know where
+exactly it is documented, and aren't sure of the name of a
+related command or variable, we recommend trying these methods. Usually
+it is best to start with an apropos command, then try searching the
+manual index, then finally look in the FAQ and the package keywords.
+
+@table @kbd
+@item C-h a @var{topics} @key{RET}
+This searches for commands whose names match @var{topics}, which
+should be a keyword, a list of keywords, or a regular expression
+(@pxref{Regexps}). This command displays all the matches in a new
+buffer. @xref{Apropos}.
+
+@item C-h i d m emacs @key{RET} i @var{topic} @key{RET}
+This looks up @var{topic} in the indices of the Emacs on-line manual.
+If there are several matches, Emacs displays the first one. You can then
+press @kbd{,} to move to other matches, until you find what you are
+looking for.
+
+@item C-h i d m emacs @key{RET} s @var{topic} @key{RET}
+Similar, but searches for @var{topic} (which can be a regular
+expression) in the @emph{text} of the manual rather than in its
+indices.
+
+@item C-h C-f
+This brings up the Emacs FAQ. You can use the Info commands
+to browse it.
+
+@item C-h p
+Finally, you can try looking up a suitable package using keywords
+pertinent to the feature you need. @xref{Library Keywords}.
+@end table
@menu
* Help Summary:: Brief list of all Help commands.
* Language Help:: Help relating to international language support.
* Help Mode:: Special features of Help mode and Help buffers.
* Misc Help:: Other help commands.
+* Help Files:: Commands to display pre-written help files.
+* Help Echo:: Help on active text and tooltips (`balloon help')
@end menu
@iftex
@node Help Summary
@end iftex
-@ifinfo
+@ifnottex
@node Help Summary
@section Help Summary
-@end ifinfo
+@end ifnottex
- Here is a summary of the defined help commands.
+ Here is a summary of the Emacs interactive help commands.
+@xref{Help Files}, for other help commands that just display a
+pre-written file of information. The character that follows
+@kbd{C-h} is a ``help option.''
@table @kbd
-@item C-h a @var{regexp} @key{RET}
-Display a list of commands whose names match @var{regexp}
-(@code{apropos-command}).
+@item C-h a @var{topics} @key{RET}
+Display a list of commands whose names match @var{topics}
+(@code{apropos-command}; @pxref{Apropos}).
@item C-h b
Display a table of all key bindings in effect now, in this order: minor
mode bindings, major mode bindings, and global bindings
(@code{describe-bindings}).
@item C-h c @var{key}
-Print the name of the command that @var{key} runs
-(@code{describe-key-briefly}). Here @kbd{c} stands for `character'. For more
-extensive information on @var{key}, use @kbd{C-h k}.
+Show the name of the command that @var{key} runs
+(@code{describe-key-briefly}). Here @kbd{c} stands for ``character.''
+For more extensive information on @var{key}, use @kbd{C-h k}.
+@item C-h d @var{topics} @key{RET}
+Display a list of commands and variables whose documentation matches
+@var{topics} (@code{apropos-documentation}).
+@item C-h e
+Display the @code{*Messages*} buffer
+(@code{view-echo-area-messages}).
@item C-h f @var{function} @key{RET}
Display documentation on the Lisp function named @var{function}
(@code{describe-function}). Since commands are Lisp functions,
a command name may be used.
@item C-h h
-Display the @file{hello} file, which shows examples of various character
+Display the @file{HELLO} file, which shows examples of various character
sets.
@item C-h i
Run Info, the program for browsing documentation files (@code{info}).
(@code{view-lossage}).
@item C-h m
Display documentation of the current major mode (@code{describe-mode}).
-@item C-h n
-Display documentation of Emacs changes, most recent first
-(@code{view-emacs-news}).
@item C-h p
Find packages by topic keyword (@code{finder-by-keyword}).
@item C-h s
-Display current contents of the syntax table, plus an explanation of
+Display the current contents of the syntax table, plus an explanation of
what they mean (@code{describe-syntax}). @xref{Syntax}.
@item C-h t
Enter the Emacs interactive tutorial (@code{help-with-tutorial}).
Display the documentation of the Lisp variable @var{var}
(@code{describe-variable}).
@item C-h w @var{command} @key{RET}
-Print which keys run the command named @var{command} (@code{where-is}).
+Show which keys run the command named @var{command} (@code{where-is}).
@item C-h C @var{coding} @key{RET}
Describe coding system @var{coding}
(@code{describe-coding-system}).
@item C-h I @var{method} @key{RET}
Describe an input method (@code{describe-input-method}).
@item C-h L @var{language-env} @key{RET}
-Describe information on the character sets, coding systems and input
+Display information on the character sets, coding systems, and input
methods used for language environment @var{language-env}
(@code{describe-language-environment}).
-@item C-h C-c
-Display the copying conditions for GNU Emacs.
-@item C-h C-d
-Display information about getting new versions of GNU Emacs.
-@item C-h C-f @var{function} @key{RET}
+@item C-h F @var{function} @key{RET}
Enter Info and go to the node documenting the Emacs function @var{function}
(@code{Info-goto-emacs-command-node}).
-@item C-h C-k @var{key}
+@item C-h K @var{key}
Enter Info and go to the node where the key sequence @var{key} is
documented (@code{Info-goto-emacs-key-command-node}).
-@item C-h C-p
-Display information about the GNU Project.
-@item C-h @key{TAB} @var{symbol} @key{RET}
+@item C-h S @var{symbol} @key{RET}
Display the Info documentation on symbol @var{symbol} according to the
programming language you are editing (@code{info-lookup-symbol}).
+@item C-h .
+Display a help message associated with special text areas, such as
+links in @samp{*Help*} buffers (@code{display-local-help}).
@end table
@node Key Help
@kindex C-h c
@findex describe-key-briefly
- The most basic @kbd{C-h} options are @kbd{C-h c}
+ The most basic @kbd{C-h} commands are @kbd{C-h c}
(@code{describe-key-briefly}) and @w{@kbd{C-h k}} (@code{describe-key}).
-@kbd{C-h c @var{key}} prints in the echo area the name of the command
-that @var{key} is bound to. For example, @kbd{C-h c C-f} prints
+@kbd{C-h c @var{key}} displays in the echo area the name of the command
+that @var{key} is bound to. For example, @kbd{C-h c C-f} displays
@samp{forward-char}. Since command names are chosen to describe what
the commands do, this is a good way to get a very brief description of
what @var{key} does.
displays the documentation string of the command as well as its name.
This is too big for the echo area, so a window is used for the display.
- @kbd{C-h c} and @kbd{C-h k} work for any sort of key sequences,
-including function keys and mouse events.
+@kindex C-h K
+@findex Info-goto-emacs-key-command-node
+ To find the documentation of a key sequence, type @kbd{C-h K} and
+then enter that key sequence. This looks up the description of the
+command invoked by the key in whichever manual describes it (this need
+not be the Emacs manual). @kbd{C-h K} runs the command
+@code{Info-goto-emacs-key-command-node}.
+
+ @kbd{C-h c}, @kbd{C-h k} and @kbd{C-h K} work for any sort of key
+sequences, including function keys, menus, and mouse events. For
+instance, you can type @kbd{C-h k} and then select a menu item from
+the menu bar, to show the documentation string of the command that
+menu item runs.
+
+@kindex C-h w
+@findex where-is
+ @kbd{C-h w @var{command} @key{RET}} tells you what keys are bound to
+@var{command}. It displays a list of the keys in the echo area. If it
+says the command is not on any key, you must use @kbd{M-x} to run it.
+@kbd{C-h w} runs the command @code{where-is}.
@node Name Help
@section Help by Command or Variable Name
way to get the documentation of a command that is not bound to any key
(one which you would normally run using @kbd{M-x}).
- @kbd{C-h f} is also useful for Lisp functions that you are planning to
-use in a Lisp program. For example, if you have just written the
-expression @code{(make-vector len)} and want to check that you are using
-@code{make-vector} properly, type @kbd{C-h f make-vector @key{RET}}.
-Because @kbd{C-h f} allows all function names, not just command names,
-you may find that some of your favorite abbreviations that work in
-@kbd{M-x} don't work in @kbd{C-h f}. An abbreviation may be unique
-among command names yet fail to be unique when other function names are
-allowed.
-
- The function name for @kbd{C-h f} to describe has a default which is
-used if you type @key{RET} leaving the minibuffer empty. The default is
-the function called by the innermost Lisp expression in the buffer around
-point, @emph{provided} that is a valid, defined Lisp function name. For
-example, if point is located following the text @samp{(make-vector (car
-x)}, the innermost list containing point is the one that starts with
-@samp{(make-vector}, so the default is to describe the function
-@code{make-vector}.
+ @kbd{C-h f} is also useful for Lisp functions that you are planning
+to use in a Lisp program. For example, if you have just written the
+expression @code{(make-vector len)} and want to check that you are
+using @code{make-vector} properly, type @kbd{C-h f make-vector
+@key{RET}}. Because @kbd{C-h f} allows all function names, not just
+command names, you may find that some of your favorite completion
+abbreviations that work in @kbd{M-x} don't work in @kbd{C-h f}. An
+abbreviation may be unique among command names, yet fail to be unique
+when other function names are allowed.
+
+ The default function name for @kbd{C-h f} to describe, if you type
+just @key{RET}, is the name of the function called by the innermost Lisp
+expression in the buffer around point, @emph{provided} that is a valid,
+defined Lisp function name. For example, if point is located following
+the text @samp{(make-vector (car x)}, the innermost list containing
+point is the one that starts with @samp{(make-vector}, so the default is
+to describe the function @code{make-vector}.
@kbd{C-h f} is often useful just to verify that you have the right
spelling for the function name. If @kbd{C-h f} mentions a name from the
that is all you want to know, just type @kbd{C-g} to cancel the @kbd{C-h
f} command, then go on editing.
-@kindex C-h w
-@findex where-is
- @kbd{C-h w @var{command} @key{RET}} tells you what keys are bound to
-@var{command}. It prints a list of the keys in the echo area. If it
-says the command is not on any key, you must use @kbd{M-x} to run it.
-@kbd{C-h w} runs the command @code{where-is}.
-
@kbd{C-h v} (@code{describe-variable}) is like @kbd{C-h f} but describes
Lisp variables instead of Lisp functions. Its default is the Lisp symbol
around or before point, but only if that is the name of a known Lisp
-variable. @xref{Variables}.@refill
+variable. @xref{Variables}.
+
+ Help buffers describing Emacs variables and functions normally have
+hyperlinks to the definition, if you have the source files installed.
+(@xref{Hyperlinking}.) If you know Lisp (or C), this provides the
+ultimate documentation. If you don't know Lisp, you should learn it.
+(The Introduction to Emacs Lisp Programming, available from the FSF
+through fsf.org, is a good way to get started.) Emacs won't be happy
+if it feels you are just @emph{using} Emacs, treating it as an object
+program. If you really love Emacs, show that you care by reading the
+source code.
+
+@kindex C-h F
+@findex Info-goto-emacs-command-node
+ To find a specific function's documentation in a manual, use
+@kbd{C-h F} (@code{Info-goto-emacs-command-node}). This knows
+about various manuals, not just the Emacs manual, and finds the
+right one.
@node Apropos
@section Apropos
+ A more sophisticated sort of question to ask is, ``What are the
+commands for working with files?'' The @dfn{apropos} commands ask
+such questions---they look for things whose names match an
+@dfn{apropos pattern}, which means either a word, a list of words, or
+a regular expression. Each apropos command displays a list of
+matching items in a special buffer.
+
+@table @kbd
+@item C-h a @var{pattern} @key{RET}
+Search for commands whose names match @var{pattern}.
+
+@item M-x apropos @key{RET} @var{pattern} @key{RET}
+Similar, but it searches for noninteractive functions and for
+variables, as well as commands.
+
+@item M-x apropos-variable @key{RET} @var{pattern} @key{RET}
+Similar, but it searches for variables only.
+
+@item M-x apropos-value @key{RET} @var{pattern} @key{RET}
+Similar, but it searches for variables based on their values, or
+functions based on their definitions.
+
+@item C-h d @var{pattern} @key{RET}
+Search the @emph{documentation strings} (the built-in short
+descriptions) of all variables and functions (not their names) for a
+match for @var{pattern}.
+@end table
+
@kindex C-h a
@findex apropos-command
@cindex apropos
- A more sophisticated sort of question to ask is, ``What are the
-commands for working with files?'' To ask this question, type @kbd{C-h
-a file @key{RET}}, which displays a list of all command names that
-contain @samp{file}, including @code{copy-file}, @code{find-file}, and
-so on. With each command name appears a brief description of how to use
-the command, and what keys you can currently invoke it with. For
-example, it would say that you can invoke @code{find-file} by typing
-@kbd{C-x C-f}. The @kbd{a} in @kbd{C-h a} stands for `Apropos';
-@kbd{C-h a} runs the command @code{apropos-command}. This command
-normally checks only commands (interactive functions); if you specify a
-prefix argument, it checks noninteractive functions as well.
-
- Because @kbd{C-h a} looks only for functions whose names contain the
-string you specify, you must use ingenuity in choosing the
-string. If you are looking for commands for killing backwards and
-@kbd{C-h a kill-backwards @key{RET}} doesn't reveal any, don't give up.
-Try just @kbd{kill}, or just @kbd{backwards}, or just @kbd{back}. Be
-persistent. Also note that you can use a regular expression as the
-argument, for more flexibility (@pxref{Regexps}).
+ To find the commands that work on files, type @kbd{C-h a file
+@key{RET}}. This displays a list of all command names that contain
+@samp{file}, including @code{copy-file}, @code{find-file}, and so on.
+With each command name appears a brief description of how to use the
+command, and what keys you can currently invoke it with. For example,
+it would say that you can invoke @code{find-file} by typing @kbd{C-x
+C-f}. The @kbd{a} in @kbd{C-h a} stands for ``Apropos''; @kbd{C-h a}
+runs the command @code{apropos-command}. This command normally checks
+only commands (interactive functions); if you specify a prefix
+argument, it checks noninteractive functions as well.
+
+ If you want more information about a function definition, variable or
+symbol property listed in the Apropos buffer, you can click on it with
+@kbd{Mouse-1} or @kbd{Mouse-2}, or move there and type @key{RET}.
+
+ @kbd{C-h a} with a single word can find too many matches. Don't
+just give up; you can give Apropos a list of words to search for.
+When you specify more than one word in the apropos pattern, a name
+must contain at least two of the words in order to match. Thus, if
+you are looking for commands to kill a chunk of text before point, you
+could try @kbd{C-h a kill back backward behind before @key{RET}}.
+
+ For even greater flexibility, you can specify a regular expression
+(@pxref{Regexps}). An apropos pattern is interpreted as a regular
+expression if it contains any of the regular expression special
+characters, @samp{^$*+?.\[}.
Here is a set of arguments to give to @kbd{C-h a} that covers many
-classes of Emacs commands, since there are strong conventions for naming
-the standard Emacs commands. By giving you a feel for the naming
-conventions, this set should also serve to aid you in developing a
-technique for picking @code{apropos} strings.
+classes of Emacs commands, since there are strong conventions for
+naming the standard Emacs commands. By giving you a feel for the
+naming conventions, this set should also serve to aid you in
+developing a technique for picking Apropos keywords.
@quotation
char, line, word, sentence, paragraph, region, page, sexp, list, defun,
view, describe, default.
@end quotation
-@findex apropos-variable
- To list all user variables that match a regexp, use the command
-@kbd{M-x apropos-variable}. This command shows only user variables and
-customization options by default; if you specify a prefix argument, it
-checks all variables.
-
@findex apropos
- To list all Lisp symbols that contain a match for a regexp, not just
-the ones that are defined as commands, use the command @kbd{M-x apropos}
-instead of @kbd{C-h a}. This command does not check key bindings by
-default; specify a numeric argument if you want it to check them.
+ To list all Lisp symbols that contain a match for an Apropos pattern,
+not just the ones that are defined as commands, use the command
+@kbd{M-x apropos} instead of @kbd{C-h a}. This command does not check
+key bindings by default; specify a numeric argument if you want it to
+check them.
+
+@findex apropos-variable
+ To list user-customizable variables that match an apropos pattern,
+use the command @kbd{M-x apropos-variable}. If you specify a prefix
+argument, it checks all variables.
+@kindex C-h d
@findex apropos-documentation
- The @code{apropos-documentation} command is like @code{apropos} except
-that it searches documentation strings as well as symbol names for
-matches for the specified regular expression.
+ The @code{apropos-documentation} command is like @code{apropos}
+except that it searches documentation strings instead of symbol names
+for matches for the specified Apropos pattern.
@findex apropos-value
- The @code{apropos-value} command is like @code{apropos} except that it
-searches symbols' values for matches for the specified regular
-expression. This command does not check function definitions or
-property lists by default; specify a numeric argument if you want it to
-check them.
+ The @code{apropos-value} command is like @code{apropos} except that
+it searches variables' values for matches for the pattern. With a
+prefix argument, it also checks symbols' function definitions and
+property lists.
@vindex apropos-do-all
If the variable @code{apropos-do-all} is non-@code{nil}, the commands
above all behave as if they had been given a prefix argument.
- If you want more information about a function definition, variable or
-symbol property listed in the Apropos buffer, you can click on it with
-@kbd{Mouse-2} or move there and type @key{RET}.
+@vindex apropos-sort-by-scores
+@cindex apropos search results, order by score
+ By default, Apropos lists the search results in alphabetical order.
+If the variable @code{apropos-sort-by-scores} is non-@code{nil},
+Apropos tries to guess the relevance of each result, and displays the
+most relevant ones first.
+
+@vindex apropos-documentation-sort-by-scores
+ By default, Apropos lists the search results for
+@code{apropos-documentation} in order of relevance of the match. If
+the variable @code{apropos-documentation-sort-by-scores} is
+@code{nil}, Apropos lists the symbols found in alphabetical order.
@node Library Keywords
@section Keyword Search for Lisp Libraries
libraries by topic keywords. Here is a partial list of keywords you can
use:
-@display
-abbrev --- abbreviation handling, typing shortcuts, macros.
-bib --- support for the bibliography processor @code{bib}.
-c --- C and C++ language support.
-calendar --- calendar and time management support.
-comm --- communications, networking, remote access to files.
-data --- support for editing files of data.
-docs --- support for Emacs documentation.
-emulations --- emulations of other editors.
-extensions --- Emacs Lisp language extensions.
-faces --- support for using faces (fonts and colors; @pxref{Faces}).
-frames --- support for Emacs frames and window systems.
-games --- games, jokes and amusements.
-hardware --- support for interfacing with exotic hardware.
-help --- support for on-line help systems.
-hypermedia --- support for links within text, or other media types.
-i18n --- internationalization and alternate character-set support.
-internal --- code for Emacs internals, build process, defaults.
-languages --- specialized modes for editing programming languages.
-lisp --- support for using Lisp (including Emacs Lisp).
-local --- libraries local to your site.
-maint --- maintenance aids for the Emacs development group.
-mail --- modes for electronic-mail handling.
-matching --- searching and matching.
-news --- support for netnews reading and posting.
-non-text --- support for editing files that are not ordinary text.
-oop --- support for object-oriented programming.
-outlines --- hierarchical outlining.
-processes --- process, subshell, compilation, and job control support.
-terminals --- support for terminal types.
-tex --- support for the @TeX{} formatter.
-tools --- programming tools.
-unix --- front-ends/assistants for, or emulators of, Unix features.
-vms --- support code for VMS.
-wp --- word processing.
-@end display
+@multitable {emulations} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
+@item abbrev@tab abbreviation handling, typing shortcuts, macros.
+@item bib@tab code related to the @code{bib} bibliography processor.
+@item c@tab support for the C language and related languages.
+@item calendar@tab calendar and time management support.
+@item comm@tab communications, networking, remote access to files.
+@item convenience@tab convenience features for faster editing.
+@item data@tab support for editing files of data.
+@item docs@tab support for Emacs documentation.
+@item emulations@tab emulations of other editors.
+@item extensions@tab Emacs Lisp language extensions.
+@item faces@tab support for multiple fonts.
+@item files@tab support for editing and manipulating files.
+@item frames@tab support for Emacs frames and window systems.
+@item games@tab games, jokes and amusements.
+@item hardware@tab support for interfacing with exotic hardware.
+@item help@tab support for on-line help systems.
+@item hypermedia@tab support for links between text or other media types.
+@item i18n@tab internationalization and alternate character-set support.
+@item internal@tab code for Emacs internals, build process, defaults.
+@item languages@tab specialized modes for editing programming languages.
+@item lisp@tab Lisp support, including Emacs Lisp.
+@item local@tab code local to your site.
+@item maint@tab maintenance aids for the Emacs development group.
+@item mail@tab modes for electronic-mail handling.
+@item matching@tab various sorts of searching and matching.
+@item mouse@tab mouse support.
+@item multimedia@tab images and sound support.
+@item news@tab support for netnews reading and posting.
+@item oop@tab support for object-oriented programming.
+@item outlines@tab support for hierarchical outlining.
+@item processes@tab process, subshell, compilation, and job control support.
+@item terminals@tab support for terminal types.
+@item tex@tab supporting code for the @TeX{} formatter.
+@item tools@tab programming tools.
+@item unix@tab front-ends/assistants for, or emulators of, UNIX-like features.
+@item wp@tab word processing.
+@end multitable
@node Language Help
@section Help for International Language Support
You can use the command @kbd{C-h L}
-(@code{describe-language-environment}) to find out the support for a
-specific language environment. @xref{Language Environments}. This
-tells you which languages this language environment is useful for, and
-lists the character sets, coding systems, and input methods that go with
-it. It also shows some sample text to illustrate scripts.
+(@code{describe-language-environment}) to find out information about
+the support for a specific language environment. @xref{Language
+Environments}. This tells you which languages this language
+environment is useful for, and lists the character sets, coding
+systems, and input methods that it operates on. It also shows some
+sample text to illustrate scripts.
The command @kbd{C-h h} (@code{view-hello-file}) displays the file
@file{etc/HELLO}, which shows how to say ``hello'' in many languages.
@node Help Mode
@section Help Mode Commands
- Help buffers provide the commands of View mode (@pxref{Misc File
+ Help buffers provide the same commands as View mode (@pxref{Misc File
Ops}), plus a few special commands of their own.
@table @kbd
Move point forward to the next cross reference.
@item S-@key{TAB}
Move point back to the previous cross reference.
-@item Mouse-2
+@item Mouse-1
+@itemx Mouse-2
Follow a cross reference that you click on.
+@item C-c C-c
+Show all documentation about the symbol at point.
@end table
- When a command name (@pxref{M-x,, Running Commands by Name}) or
-variable name (@pxref{Variables}) appears in the documentation, it
-normally appears inside paired single-quotes. You can click on the name
-with @kbd{Mouse-2}, or move point there and type @key{RET}, to view the
-documentation of that command or variable. Use @kbd{C-c C-b} to retrace
-your steps.
+ When a function name (@pxref{M-x,, Running Commands by Name}),
+variable name (@pxref{Variables}), or face name (@pxref{Faces}) appears
+in the documentation, it normally appears inside paired single-quotes.
+You can click on the name with @kbd{Mouse-1} or @kbd{Mouse-2}, or move
+point there and type @key{RET}, to view the documentation of that
+command, variable or face. Use @kbd{C-c C-b} to retrace your steps.
+
+@cindex URL, viewing in help
+@cindex help, viewing web pages
+@cindex viewing web pages in help
+@cindex web pages, viewing in help
+@findex browse-url
+ You can follow cross references to URLs (web pages) as well. When
+you follow a cross reference that is a URL, the @code{browse-url}
+command is used to view the web page in a browser of your choosing.
+@xref{Browse-URL}.
@kindex @key{TAB} @r{(Help mode)}
@findex help-next-ref
next cross reference. Use @kbd{S-@key{TAB}} to move point up to the
previous cross reference (@code{help-previous-ref}).
+ You can view all documentation about any symbol name that appears in
+the text, by moving point to the symbol name and typing @kbd{C-c C-c}
+(@code{help-follow-symbol}). This shows all available documentation
+about the symbol as a variable, function and/or face. @kbd{C-c C-b}
+works in this case also, to retrace your steps.
+
@node Misc Help
@section Other Help Commands
system will be available. Type @kbd{h} after entering Info to run
a tutorial on using Info.
- If you specify a numeric argument, @kbd{C-h i} prompts for the name of
-a documentation file. This way, you can browse a file which doesn't
+@cindex find Info manual by its file name
+ With a numeric argument, @kbd{C-h i} selects an Info buffer with the
+number appended to the default @samp{*info*} buffer name
+(e.g. @samp{*info*<2>}). This is useful if you want to browse
+multiple Info manuals simultaneously. If you specify just @kbd{C-u}
+as the prefix argument, @kbd{C-h i} prompts for the name of a
+documentation file. This way, you can browse a file which doesn't
have an entry in the top-level Info menu. It is also handy when you
-need to get to the documentation quickly, and you know the exact name of
-the file.
+need to get to the documentation quickly, and you know the exact name
+of the file.
-@kindex C-h C-f
-@kindex C-h C-k
-@findex Info-goto-emacs-key-command-node
-@findex Info-goto-emacs-command-node
- There are two special help commands for accessing Emacs documentation
-through Info. @kbd{C-h C-f @var{function} @key{RET}} enters Info and
-goes straight to the documentation of the Emacs function
-@var{function}. @kbd{C-h C-k @var{key}} enters Info and goes straight
-to the documentation of the key @var{key}. These two keys run the
-commands @code{Info-goto-emacs-command-node} and
-@code{Info-goto-emacs-key-command-node}.
+ The help commands @kbd{C-h F @var{function} @key{RET}} and @kbd{C-h
+K @var{key}}, described above, enter Info and go straight to the
+documentation of @var{function} or @var{key}.
- When editing a program, if you have an Info version of the manual for
-the programming language, you can use the command @kbd{C-h C-i} to refer
-to the manual documentation for a symbol (keyword, function or
-variable). The details of how this command works depend on the major
-mode.
+@kindex C-h S
+@findex info-lookup-symbol
+ When editing a program, if you have an Info version of the manual
+for the programming language, you can use the command @kbd{C-h S}
+(@code{info-lookup-symbol}) to refer to the manual documentation for a
+symbol (keyword, function or variable). The details of how this
+command works depend on the major mode.
@kindex C-h l
@findex view-lossage
If something surprising happens, and you are not sure what commands you
-typed, use @kbd{C-h l} (@code{view-lossage}). @kbd{C-h l} prints the last
+typed, use @kbd{C-h l} (@code{view-lossage}). @kbd{C-h l} displays the last
100 command characters you typed in. If you see commands that you don't
know, you can use @kbd{C-h c} to find out what they do.
+@kindex C-h e
+@findex view-echo-area-messages
+ To review messages that recently appeared in the echo area, use
+@kbd{C-h e} (@code{view-echo-area-messages}). This displays the
+buffer @code{*Messages*}, where those messages are kept.
+
@kindex C-h m
@findex describe-mode
Emacs has numerous major modes, each of which redefines a few keys and
makes a few other changes in how editing works. @kbd{C-h m}
-(@code{describe-mode}) prints documentation on the current major mode,
+(@code{describe-mode}) displays documentation on the current major mode,
which normally describes all the commands that are changed in this
mode.
@kbd{C-h b} (@code{describe-bindings}) and @kbd{C-h s}
(@code{describe-syntax}) present other information about the current
Emacs mode. @kbd{C-h b} displays a list of all the key bindings now in
-effect; the local bindings defined by the current minor modes first,
+effect, showing the local bindings defined by the current minor modes first,
then the local bindings defined by the current major mode, and finally
the global bindings (@pxref{Key Bindings}). @kbd{C-h s} displays the
contents of the syntax table, with explanations of each character's
@kbd{C-h}. One of these is @key{ESC}, because @kbd{@key{ESC} C-h} is
actually @kbd{C-M-h}, which marks a defun.)
-@kindex C-h F
-@findex view-emacs-FAQ
-@kindex C-h n
-@findex view-emacs-news
+@node Help Files
+@section Help Files
+
+ The Emacs help commands described above display the state of data
+bases within Emacs. Emacs has a few other help commands that display
+pre-written help files. These commands all have the form @kbd{C-h
+C-@var{char}}; that is, @kbd{C-h} followed by a control character.
+
@kindex C-h C-c
@findex describe-copying
@kindex C-h C-d
@findex describe-distribution
-@kindex C-h C-w
-@findex describe-no-warranty
+@kindex C-h C-e
+@findex view-emacs-problems
+@kindex C-h C-f
+@findex view-emacs-FAQ
+@kindex C-h C-n
+@findex view-emacs-news
@kindex C-h C-p
@findex describe-project
- The other @kbd{C-h} options display various files of useful
-information. @kbd{C-h C-w} displays the full details on the complete
-absence of warranty for GNU Emacs. @kbd{C-h n} (@code{view-emacs-news})
-displays the file @file{emacs/etc/NEWS}, which contains documentation on
-Emacs changes arranged chronologically. @kbd{C-h F}
-(@code{view-emacs-FAQ}) displays the Emacs frequently-answered-questions
-list. @kbd{C-h t} (@code{help-with-tutorial}) displays the
-learn-by-doing Emacs tutorial. @kbd{C-h C-c} (@code{describe-copying})
-displays the file @file{emacs/etc/COPYING}, which tells you the
-conditions you must obey in distributing copies of Emacs. @kbd{C-h C-d}
-(@code{describe-distribution}) displays the file
-@file{emacs/etc/DISTRIB}, which tells you how you can order a copy of
-the latest version of Emacs. @kbd{C-h C-p} (@code{describe-project})
-displays general information about the GNU Project.
+@kindex C-h C-t
+@findex view-emacs-todo
+@kindex C-h C-w
+@findex describe-no-warranty
+ The other @kbd{C-h} options display various files containing useful
+information.
+
+@table @kbd
+@item C-h C-c
+Displays the Emacs copying conditions (@code{describe-copying}).
+These are the rules under which you can copy and redistribute Emacs.
+@item C-h C-d
+Displays information on how to download or order the latest version of
+Emacs and other GNU software (@code{describe-distribution}).
+@item C-h C-e
+Displays the list of known Emacs problems, sometimes with suggested
+workarounds (@code{view-emacs-problems}).
+@item C-h C-f
+Displays the Emacs frequently-answered-questions list (@code{view-emacs-FAQ}).
+@item C-h C-n
+Displays the Emacs ``news'' file, which lists new Emacs features, most
+recent first (@code{view-emacs-news}).
+@item C-h C-p
+Displays general information about the GNU Project
+(@code{describe-project}).
+@item C-h C-t
+Displays the Emacs to-do list (@code{view-todo}).
+@item C-h C-w
+Displays the full details on the complete absence of warranty for GNU
+Emacs (@code{describe-no-warranty}).
+@end table
+
+@node Help Echo
+@section Help on Active Text and Tooltips
+
+@cindex tooltips
+@cindex balloon help
+ When a region of text is ``active,'' so that you can select it with
+the mouse or a key like @kbd{RET}, it often has associated help text.
+Areas of the mode line are examples. On graphical displays, the help
+text is displayed as a ``tooltip'' (sometimes known as ``balloon
+help''), when you move the mouse over the active text. @xref{Tooltips}.
+On some systems, it is shown in the echo area. On text-only
+terminals, Emacs may not be able to follow the mouse and hence will
+not show the help text on mouse-over.
+
+@kindex C-h .
+@findex display-local-help
+@vindex help-at-pt-display-when-idle
+ You can also access text region help info using the keyboard. The
+command @kbd{C-h .} (@code{display-local-help}) displays any help text
+associated with the text at point, using the echo area. If you want
+help text to be displayed automatically whenever it is available at
+point, set the variable @code{help-at-pt-display-when-idle} to
+@code{t}.
+
+@ignore
+ arch-tag: 6f33ab62-bc75-4367-8057-fd67cc15c3a1
+@end ignore