@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 86, 87, 93, 94, 95, 97, 2000, 2001, 2004
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
+@c 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Help, Mark, M-x, Top
@chapter Help
option, you can use @key{SPC} or @key{DEL} to scroll through the list.
@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}. It also offers
@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 option, we recommend trying these methods. Usually
+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.
command displays to find what you are looking for. @xref{Apropos}.
@item M-x apropos @key{RET} @var{topic} @key{RET}
-This works like @kbd{C-h a}, but it also searches for user options and
-other variables, in case the feature you are looking for is controlled
-by an option, not a command. @xref{Apropos}.
+This works like @kbd{C-h a}, but it also searches for noninteractive
+functions and for variables. @xref{Apropos}.
@item M-x apropos-documentation @key{RET} @var{topic} @key{RET}
This searches the @emph{documentation strings} (the built-in short
@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 @key{,} to move to other matches, until you find what you are
+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}
indices.
@item C-h C-f
-This brings up the Emacs FAQ, where you can use the usual search
-commands (@pxref{Search}) to find the information.
+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
@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
@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 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.
+ @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
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 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}.
-
@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 variables or functions defined in Lisp
-normally have hyperlinks to the Lisp definition, if you have the Lisp
-source files installed. If you know Lisp, this provides the ultimate
-documentation. If you don't know Lisp, you should learn it. If you
-are treating Emacs as an object file, then you are just @emph{using}
-Emacs. For real intimacy with Emacs, you must read the source code.
+ 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.
+If you are just @emph{using} Emacs, treating Emacs as an object
+(file), then you don't really love it. For true intimacy with your
+editor, you need to read the source code.
@node Apropos
@section Apropos
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}).
+ Because @kbd{C-h a} looks only for commands matching the string you
+specify, you may not find what you want on the first try. In that
+case, don't just give up. You can give Apropos a list of words to
+search for. When more than one word is specified, at least two of
+those words must be present for an item to match. If you are looking
+for commands to kill a chunk of text before point, try @kbd{C-h a kill
+back behind before @key{RET}}. For even greater flexibility, you can
+also supply a regular expression to Apropos (@pxref{Regexps}).
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
@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.
+@kbd{M-x apropos-variable}. By default, this command shows only
+variables meant for user customization; 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
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.
+@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.
+
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}.
+@kbd{Mouse-1} or @kbd{Mouse-2}, or move there and type @key{RET}.
@node Library Keywords
@section Keyword Search for Lisp Libraries
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.
@end table
- When a command name (@pxref{M-x,, Running Commands by Name}) or
+ When a function 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.
+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 or variable. Use
+@kbd{C-c C-b} to retrace your steps.
@kindex @key{TAB} @r{(Help mode)}
@findex help-next-ref
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 F
@kindex C-h K
@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. This help will normally be
-shown in the echo area when you move point into the active text. In
-a window system you can display the help text as a ``tooltip''
-(sometimes known as ``balloon help''). @xref{Tooltips}.
+Areas of the mode line are examples. On most window systems, the help
+text is displayed as a ``tooltip'' (sometimes known as ``balloon
+help''). @xref{Tooltips}. Otherwise, it is shown in the echo area
+when you move point into the active text.
+
+@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