@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 86, 87, 93, 94, 95, 97, 2000
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 97, 2000, 2001, 2004
@c Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Help, Mark, M-x, Top
@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
+character, @kbd{C-h}. @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}.
Most help buffers use a special major mode, Help mode, which lets you
scroll conveniently with @key{SPC} and @key{DEL}. It also offers
-hyperlinks to more help on cross-referenced names, Info nodes,
+hyperlinks to 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 option, 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{topic} @key{RET}
+This searches for commands whose names match @var{topic}, which should
+be a regular expression (@pxref{Regexps}). Browse the buffer that this
+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}.
+
+@item M-x apropos-documentation @key{RET} @var{topic} @key{RET}
+This searches the @emph{documentation strings} (the built-in short
+descriptions) of all variables and functions (not their names) for a
+match for @var{topic}, a regular expression. @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, where you can use the usual search
+commands (@pxref{Search}) to find the information.
+
+@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
+
+ To find the documentation of a key sequence or a menu item, type
+@kbd{C-h K} and then type that key sequence or select the menu
+item. This looks up the description of the command invoked by the key
+or the menu in the appropriate manual (not necessarily the Emacs
+manual). Likewise, use @kbd{C-h F} for reading documentation of a
+command.
+
@menu
* Help Summary:: Brief list of all Help commands.
* Key Help:: Asking what a key does in Emacs.
* 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.
@table @kbd
@item C-h a @var{regexp} @key{RET}
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 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
-Display info on known problems with Emacs and possible workarounds
-(@code{view-emacs-problems}).
@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}).
@end table
@findex describe-key-briefly
The most basic @kbd{C-h} options 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.
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}.
+ 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
@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
+@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}.
around or before point, but only if that is the name of a known Lisp
variable. @xref{Variables}.@refill
-Help buffers describing variables or functions defined in Lisp normally
-have hyperlinks to their definitions if you have the Lisp source files
-installed. If you can read Lisp, this provides the ultimate
-documentation.
-
+ 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.
+
@node Apropos
@section Apropos
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-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.
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 go with it. 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
@item @key{SPC}
Scroll forward.
@item @key{DEL}
-Scroll backward.
+@itemx @key{BS}
+Scroll backward. On some keyboards, this key is known as @key{BS} or
+@key{backspace}.
@item @key{RET}
Follow a cross reference at point.
@item @key{TAB}
system will be available. Type @kbd{h} after entering Info to run
a tutorial on using Info.
+@cindex find Info manual by its file name
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
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.
-@kindex C-h C-f
-@kindex C-h C-k
+@kindex C-h F
+@kindex C-h 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}.
-
- 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.
+ There are two special help commands for accessing Emacs
+documentation through Info. @kbd{C-h F @var{function} @key{RET}}
+enters Info and goes straight to the documentation of the Emacs
+function @var{function}. @kbd{C-h 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}. You can use @kbd{C-h K} to
+find the documentation of a menu item: just select that menu item when
+@kbd{C-h K} prompts for a key.
+
+ @kbd{C-h F} and @kbd{C-h K} know about commands and keys described
+in manuals other than the Emacs manual. Thus, they make it easier to
+find the documentation of commands and keys when you are not sure
+which manual describes them, like when using some specialized 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
-@kindex C-h P
-@findex view-emacs-problems
- 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. @kbd{C-h P}
-(@code{view-emacs-problems}) displays the file
-@file{emacs/etc/PROBLEMS}, which lists known problems with Emacs in
-various situations with solutions or workarounds in many cases.
+@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 ballon help
-Often when a region of text is `active' so that you can select it with
-the mouse or a key like @kbd{RET}, it has associated help text. Areas
-of the mode line are examples. This help will normally be printed in
-the echo area when you move point into the active text. In a window
-system you can display the help text as `tooltips'. @xref{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. 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}.
+
+@ignore
+ arch-tag: 6f33ab62-bc75-4367-8057-fd67cc15c3a1
+@end ignore
HCoop / bpt / emacs.git / blobdiff