X-Git-Url: https://git.hcoop.net/bpt/emacs.git/blobdiff_plain/dc941693e94f00cdf557f47cf546e42795070553..b653cee476923bfab4fcaa808aa8b870051de70f:/man/help.texi diff --git a/man/help.texi b/man/help.texi dissimilarity index 71% index 66ffbf6dcc..6696b3440d 100644 --- a/man/help.texi +++ b/man/help.texi @@ -1,556 +1,666 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 86, 87, 93, 94, 95, 97, 2000 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Help, Mark, M-x, Top -@chapter Help -@kindex Help -@cindex help -@cindex self-documentation -@findex help-command -@kindex C-h -@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}. - -@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. - - @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}.) - - 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 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 even sure what is the name of the -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 popped -up by Emacs, 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 @key{,} 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 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 - -@menu -* Help Summary:: Brief list of all Help commands. -* Key Help:: Asking what a key does in Emacs. -* Name Help:: Asking about a command, variable or function name. -* Apropos:: Asking what pertains to a given topic. -* Library Keywords:: Finding Lisp libraries by keywords (topics). -* Language Help:: Help relating to international language support. -* Help Mode:: Special features of Help mode and Help buffers. -* Misc Help:: Other help commands. -* Help Echo:: Help on active text and tooltips (`balloon help') -@end menu - -@iftex -@node Help Summary -@end iftex -@ifinfo -@node Help Summary -@section Help Summary -@end ifinfo - - Here is a summary of the defined help commands. - -@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 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}. -@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 -sets. -@item C-h i -Run Info, the program for browsing documentation files (@code{info}). -The complete Emacs manual is available on-line in Info. -@item C-h k @var{key} -Display the name and documentation of the command that @var{key} runs -(@code{describe-key}). -@item C-h l -Display a description of the last 100 characters you typed -(@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 -what they mean (@code{describe-syntax}). @xref{Syntax}. -@item C-h t -Enter the Emacs interactive tutorial (@code{help-with-tutorial}). -@item C-h v @var{var} @key{RET} -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}). -@item C-h C @var{coding} @key{RET} -Describe coding system @var{coding} -(@code{describe-coding-system}). -@item C-h C @key{RET} -Describe the coding systems currently in use. -@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 -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} -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} -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} -Display the Info documentation on symbol @var{symbol} according to the -programming language you are editing (@code{info-lookup-symbol}). -@end table - -@node Key Help -@section Documentation for a Key - -@kindex C-h c -@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 -@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. - -@kindex C-h k -@findex describe-key - @kbd{C-h k @var{key}} is similar but gives more information: it -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. - -@node Name Help -@section Help by Command or Variable Name - -@kindex C-h f -@findex describe-function - @kbd{C-h f} (@code{describe-function}) reads the name of a Lisp function -using the minibuffer, then displays that function's documentation string -in a window. Since commands are Lisp functions, you can use this to get -the documentation of a command that you know by name. For example, - -@example -C-h f auto-fill-mode @key{RET} -@end example - -@noindent -displays the documentation of @code{auto-fill-mode}. This is the only -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 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 -buffer as the default, that name must be defined as a Lisp function. If -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 - - 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 - -@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}). - - 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. - -@quotation -char, line, word, sentence, paragraph, region, page, sexp, list, defun, -rect, buffer, frame, window, face, file, dir, register, mode, beginning, end, -forward, backward, next, previous, up, down, search, goto, kill, delete, -mark, insert, yank, fill, indent, case, change, set, what, list, find, -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. - -@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. - -@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. - -@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}. - -@node Library Keywords -@section Keyword Search for Lisp Libraries - -@kindex C-h p -@findex finder-by-keyword -The @kbd{C-h p} command lets you search the standard Emacs Lisp -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 - -@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. - - 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. - - The command @kbd{C-h I} (@code{describe-input-method}) describes -information about input methods---either a specified input method, or by -default the input method in use. @xref{Input Methods}. - - The command @kbd{C-h C} (@code{describe-coding-system}) describes -information about coding systems---either a specified coding system, or -the ones currently in use. @xref{Coding Systems}. - -@node Help Mode -@section Help Mode Commands - - Help buffers provide the commands of View mode (@pxref{Misc File -Ops}), plus a few special commands of their own. - -@table @kbd -@item @key{SPC} -Scroll forward. -@item @key{DEL} -@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} -Move point forward to the next cross reference. -@item S-@key{TAB} -Move point back to the previous cross reference. -@item Mouse-2 -Follow a cross reference that you click on. -@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. - -@kindex @key{TAB} @r{(Help mode)} -@findex help-next-ref -@kindex S-@key{TAB} @r{(Help mode)} -@findex help-previous-ref - There are convenient commands for moving point to cross references in -the help text. @key{TAB} (@code{help-next-ref}) moves point down to the -next cross reference. Use @kbd{S-@key{TAB}} to move point up to the -previous cross reference (@code{help-previous-ref}). - -@node Misc Help -@section Other Help Commands - -@kindex C-h i -@findex info -@cindex Info -@cindex manuals, on-line -@cindex on-line manuals - @kbd{C-h i} (@code{info}) runs the Info program, which is used for -browsing through structured documentation files. The entire Emacs manual -is available within Info. Eventually all the documentation of the GNU -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 -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 -@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. - -@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 -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 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, -which normally describes all the commands that are changed in this -mode. - -@kindex C-h b -@findex describe-bindings - @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, -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 -syntax (@pxref{Syntax}). - - You can get a similar list for a particular prefix key by typing -@kbd{C-h} after the prefix key. (There are a few prefix keys for which -this does not work---those that provide their own bindings for -@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 -@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-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. - -@node Help Echo -@section Help on Active Text and Tooltips - -@cindex tooltips -@cindex ballon 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 -printed 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.'' -@xref{Tooltips}. +@c This is part of the Emacs manual. +@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 Help +@cindex help +@cindex self-documentation +@findex help-command +@kindex C-h +@kindex F1 + + Emacs provides extensive help features, all accessible through the +@dfn{help character}, @kbd{C-h}. This is a prefix key that is used +for commands that display documentation; the next character you type +should be a @dfn{help options}, to ask for a particular kind of help. +You can cancel the @kbd{C-h} command with @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} itself is one of the help options; @kbd{C-h C-h} displays +a list of help options, with a brief description of each one +(@code{help-for-help}). You can scroll the list with @key{SPC} and +@key{DEL}, 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 instance, you can type them after a prefix key to display +list of the keys that can follow the prefix key. (A few prefix keys +don't support @kbd{C-h} in this way, because they define other +meanings for it, but they all support @key{F1} for help.) + + Most help buffers use a special major mode, Help mode, which lets +you scroll conveniently with @key{SPC} and @key{DEL}. You can also +follow hyperlinks to URLs, and to other facilities including Info +nodes and customization buffers. @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 what it is +called or where to look, we recommend three methods. First, try an +apropos command, then try searching the manual index, then 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 the argument +@var{topics}. The argument can 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 searches for @var{topic} in the indices of the on-line Emacs +manual, and displays the first match found. Press @kbd{,} to see +subsequent matches. You can use a regular expression as @var{topic}. + +@item C-h i d m emacs @key{RET} s @var{topic} @key{RET} +Similar, but searches the @emph{text} of the manual rather than the +indices. + +@item C-h C-f +This displays the Emacs FAQ. You can use the Info commands +to browse it. + +@item C-h p +This displays the available Emacs packages based on keywords. +@xref{Library Keywords}. +@end table + +@menu +* Help Summary:: Brief list of all Help commands. +* Key Help:: Asking what a key does in Emacs. +* Name Help:: Asking about a command, variable or function name. +* Apropos:: Asking what pertains to a given topic. +* Library Keywords:: Finding Lisp libraries by keywords (topics). +* 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 +@ifnottex +@node Help Summary +@section Help Summary +@end ifnottex + + Here is a summary of the Emacs interactive help commands. (The +character that follows @kbd{C-h} is the ``help option.'') @xref{Help +Files}, for other help commands that display fixed files of +information. + +@table @kbd +@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 all active key bindings; minor mode bindings first, then those +of the major mode, then global bindings (@code{describe-bindings}). +@item C-h c @var{key} +Given a key sequence @var{key}, show the name of the command that it +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 the 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, +this works for commands too. +@item C-h h +Display the @file{HELLO} file, which shows examples of various character +sets. +@item C-h i +Run Info, the GNU documentation browser (@code{info}). +The complete Emacs manual is available on-line in Info. +@item C-h k @var{key} +Display the name and documentation of the command that @var{key} runs +(@code{describe-key}). +@item C-h l +Display a description of the last 100 characters you typed +(@code{view-lossage}). +@item C-h m +Display documentation of the current major mode (@code{describe-mode}). +@item C-h p +Find packages by topic keyword (@code{finder-by-keyword}). +@item C-h s +Display the current contents of the syntax table, with an explanation of +what they mean (@code{describe-syntax}). @xref{Syntax}. +@item C-h t +Enter the Emacs interactive tutorial (@code{help-with-tutorial}). +@item C-h v @var{var} @key{RET} +Display the documentation of the Lisp variable @var{var} +(@code{describe-variable}). +@item C-h w @var{command} @key{RET} +Show which keys run the command named @var{command} (@code{where-is}). +@item C-h C @var{coding} @key{RET} +Describe the coding system @var{coding} +(@code{describe-coding-system}). +@item C-h C @key{RET} +Describe the coding systems currently in use. +@item C-h I @var{method} @key{RET} +Describe the input method @var{method} (@code{describe-input-method}). +@item C-h L @var{language-env} @key{RET} +Display information on the character sets, coding systems, and input +methods used in language environment @var{language-env} +(@code{describe-language-environment}). +@item C-h F @var{function} @key{RET} +Enter Info and goes to the node that documents the Emacs function +@var{function} (@code{Info-goto-emacs-command-node}). +@item C-h K @var{key} +Enter Info and goes to the node that documents the key sequence +@var{key} (@code{Info-goto-emacs-key-command-node}). +@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 the help message for a special text area, if point is in one +(@code{display-local-help}). (These include, for example, links in +@samp{*Help*} buffers.) +@end table + +@node Key Help +@section Documentation for a Key + +@kindex C-h c +@findex describe-key-briefly + The help commands to get information about a key sequence are +@kbd{C-h c} and @w{@kbd{C-h k}}. @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 gives you a +very brief description of what @var{key} does. + +@kindex C-h k +@findex describe-key + @kbd{C-h k @var{key}} is similar but gives more information: it +displays the documentation string of the command as well as its name. +It displays this information in a window, since it may not fit in the +echo area. + +@kindex C-h K +@findex Info-goto-emacs-key-command-node + To find the documentation of a key sequence @var{key}, type @kbd{C-h +K @var{key}}. This displays the appropriate manual section which +contains the documentation of @var{key}. + + @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, after @kbd{C-h k} you can select a menu item from the menu +bar, to view the documentation string of the command it runs. + +@kindex C-h w +@findex where-is + @kbd{C-h w @var{command} @key{RET}} lists the keys that are bound to +@var{command}. It displays the list in the echo area. If it says the +command is not on any key, that means 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 + +@kindex C-h f +@findex describe-function + @kbd{C-h f @var{function} @key{RET}} (@code{describe-function}) +displays the documentation of Lisp function @var{function}, in a +window. Since commands are Lisp functions, you can use this method to +view the documentation of any command whose name you know. For +example, + +@example +C-h f auto-fill-mode @key{RET} +@end example + +@noindent +displays the documentation of @code{auto-fill-mode}. This is the only +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 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 that is +unique among command names may not be unique among all function names. + + If you type @kbd{C-h f @key{RET}}, it describes the function called +by the innermost Lisp expression in the buffer around point, +@emph{provided} that function name is a valid, defined Lisp function. +(That name appears as the default while you enter the argument.) 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 @kbd{C-h f @key{RET}} will describe the +function @code{make-vector}. + + @kbd{C-h f} is also useful just to verify that you spelled a +function name correctly. If the minibuffer prompt for @kbd{C-h f} +shows the function name from the buffer as the default, it means that +name is defined as a Lisp function. Type @kbd{C-g} to cancel the +@kbd{C-h f} command if you don't really want to view the +documentation. + +@kindex C-h v +@findex describe-variable + @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, if that is the name of a +defined Lisp variable. @xref{Variables}. + + Help buffers that describe Emacs variables and functions normally +have hyperlinks to the corresponding source 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.) If Emacs feels you are just @emph{using} it, treating +it as an object program, its feelings may be hurt. For real intimacy, +read the Emacs source code. + +@kindex C-h F +@findex Info-goto-emacs-command-node + To find a 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 + + The @dfn{apropos} commands answer questions like, ``What are the +commands for working with files?'' More precisely, you specify an +@dfn{apropos pattern}, which means either a word, a list of words, or +a regular expression. Each apropos command displays a list of items +that match the pattern, in a separate 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} +Search for functions and variables whose names match @var{pattern}. +Both interactive functions (commands) and noninteractive functions can +be found by this command. + +@item M-x apropos-variable @key{RET} @var{pattern} @key{RET} +Search for user-option variables whose names match @var{pattern}. + +@item M-x apropos-value @key{RET} @var{pattern} @key{RET} +Search for functions whose definitions @var{pattern}, and variables +whose values match @var{pattern}. + +@item C-h d @var{pattern} @key{RET} +Search for functions and variables whose @strong{documentation +strings} match @var{pattern}. +@end table + +@kindex C-h a +@findex apropos-command +@cindex apropos + The simplest kind of apropos pattern is one word. Anything which +contains that word matches the pattern. Thus, 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. Each command name +comes with a brief description and a list of keys you can currently +invoke it with. In our 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. + + For 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}. + + 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}}. The +real command name @code{kill-backward} will match that; if there were +a command @code{kill-text-before}, it would also match, since it +contains two of the specified words. + + 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{^$*+?.\[}. + + Following the conventions for naming Emacs commands, here are some +words that you'll find useful in apropos patterns. By using them in +@kbd{C-h a}, you will also get a feel for the naming conventions. + +@quotation +char, line, word, sentence, paragraph, region, page, sexp, list, defun, +rect, buffer, frame, window, face, file, dir, register, mode, beginning, end, +forward, backward, next, previous, up, down, search, goto, kill, delete, +mark, insert, yank, fill, indent, case, change, set, what, list, find, +view, describe, default. +@end quotation + +@findex apropos + Use @kbd{M-x apropos} instead of @kbd{C-h a} to list all the Lisp +symbols that match an apropos pattern, not just the symbols that are +commands. This command does not list key bindings by default; specify +a numeric argument if you want it to list them. + +@findex apropos-variable + Use @kbd{M-x apropos-variable} to list user-customizable variables +that match an apropos pattern. If you specify a prefix argument, it +lists all matching variables. + +@kindex C-h d +@findex apropos-documentation + The @code{apropos-documentation} command is like @code{apropos} +except that it searches documentation strings instead of symbol names +for matches. + +@findex apropos-value + The @code{apropos-value} command is like @code{apropos} except that +it searches variables' values for matches for the apropos 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 apropos +commands always 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}, the +apropos commands try to guess the relevance of each result, and +display 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 + +@kindex C-h p +@findex finder-by-keyword +The @kbd{C-h p} command lets you search the standard Emacs Lisp +libraries by topic keywords. Here is a partial list of keywords you can +use: + +@multitable {convenience} {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 get information about a +specific language environment. @xref{Language Environments}. This +tells you which languages this language environment supports. It also +lists the character sets, coding systems, and input methods that work +with this language environment, and finally 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. + + The command @kbd{C-h I} (@code{describe-input-method}) describes an +input method---either a specified input method, or by default the +input method currently in use. @xref{Input Methods}. + + The command @kbd{C-h C} (@code{describe-coding-system}) describes +coding systems---either a specified coding system, or the ones +currently in use. @xref{Coding Systems}. + +@node Help Mode +@section Help Mode Commands + + 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. +@item @key{RET} +Follow a cross reference at point. +@item @key{TAB} +Move point forward to the next cross reference. +@item S-@key{TAB} +Move point back to the previous cross reference. +@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 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. To view the documentation of that command, variable or +face, you can click on the name with @kbd{Mouse-1} or @kbd{Mouse-2}, +or move point there and type @key{RET}. 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) also. This uses +the @code{browse-url} command to view the page in the browser you +choose. @xref{Browse-URL}. + +@kindex @key{TAB} @r{(Help mode)} +@findex help-next-ref +@kindex S-@key{TAB} @r{(Help mode)} +@findex help-previous-ref + There are convenient commands to move point to cross references in +the help text. @key{TAB} (@code{help-next-ref}) moves point down to +the next cross reference. @kbd{S-@key{TAB}} moves up to the previous +cross reference (@code{help-previous-ref}). + + To view all documentation about any symbol name that appears in the +text, move point to the symbol name and type @kbd{C-c C-c} +(@code{help-follow-symbol}). This shows all available documentation +about the symbol as a variable, function and/or face. As above, use +@kbd{C-c C-b} to retrace your steps. + +@node Misc Help +@section Other Help Commands + +@kindex C-h i +@findex info +@cindex Info +@cindex manuals, on-line +@cindex on-line manuals + @kbd{C-h i} (@code{info}) runs the Info program, which browses +structured documentation files. The entire Emacs manual is available +within Info, along with many other manuals for the GNU system. Type +@kbd{h} after entering Info to run a tutorial on using Info. + +@cindex find Info manual by its file name + With a numeric argument @var{n}, @kbd{C-h i} selects the Info buffer +@samp{*info*<@var{n}>}. 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, so you can browse a file which doesn't have an entry in the +top-level Info menu. + + 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}. + +@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 @kbd{C-h S} +(@code{info-lookup-symbol}) to find symbol (keyword, function or +variable) in the proper manual. 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 you +typed, use @kbd{C-h l} (@code{view-lossage}). @kbd{C-h l} displays +the last 100 characters you typed in Emacs. 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 recent echo area messages, 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 + Each Emacs major mode typically redefines a few keys and makes other +changes in how editing works. @kbd{C-h m} (@code{describe-mode}) +displays documentation on the current major mode, which normally +describes the commands and features that are changed in this mode. + +@kindex C-h b +@findex describe-bindings + @kbd{C-h b} (@code{describe-bindings}) and @kbd{C-h s} +(@code{describe-syntax}) show other information about the current +environment within Emacs. @kbd{C-h b} displays a list of all the key +bindings now in effect: first the local bindings of the current minor +modes, 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 syntax (@pxref{Syntax}). + + You can get a list of subcommands for a particular prefix key by +typing @kbd{C-h} after the prefix key. (There are a few prefix keys +for which this does not work---those that provide their own bindings +for @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.) + +@node Help Files +@section Help Files + + The Emacs help commands described above display dynamic help based +on the current state within Emacs, or refer to manuals. Other help +commands display pre-written, static 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-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 C-t +@findex view-emacs-todo +@kindex C-h C-w +@findex describe-no-warranty + +@table @kbd +@item C-h C-c +Display the Emacs copying conditions (@code{describe-copying}). +These are the rules under which you can copy and redistribute Emacs. +@item C-h C-d +Display how to download or order the latest version of +Emacs and other GNU software (@code{describe-distribution}). +@item C-h C-e +Display the list of known Emacs problems, sometimes with suggested +workarounds (@code{view-emacs-problems}). +@item C-h C-f +Display the Emacs frequently-answered-questions list (@code{view-emacs-FAQ}). +@item C-h C-n +Display the Emacs ``news'' file, which lists new features in the most +recent version of Emacs (@code{view-emacs-news}). +@item C-h C-p +Display general information about the GNU Project +(@code{describe-project}). +@item C-h C-t +Display the Emacs to-do list (@code{view-todo}). +@item C-h C-w +Display 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. +For instance, most parts of the mode line have help text. 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, if Emacs cannot follow the +mouse, it cannot 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