X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/19b2c4ca1fe5defb95255b9652be5c90c3ce481d..b9661543a6cf55b261bdc69d44fac85087ff7456:/man/help.texi diff --git a/man/help.texi b/man/help.texi index fb14eb150a..bcae911d55 100644 --- a/man/help.texi +++ b/man/help.texi @@ -1,6 +1,6 @@ @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 @@ -25,11 +25,10 @@ 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}.) +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 @@ -51,9 +50,8 @@ 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 variables, -in case the feature you are looking for is controlled by a variable -rather than 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 @@ -72,8 +70,8 @@ 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. +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 @@ -174,6 +172,9 @@ documented (@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 a help message associated with special text areas, such as +links in @samp{*Help*} buffers (@code{display-local-help}). @end table @node Key Help @@ -198,6 +199,13 @@ 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 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 @@ -217,15 +225,15 @@ 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. + @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 @@ -241,24 +249,18 @@ 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 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 @@ -278,13 +280,14 @@ example, it would say that you can invoke @code{find-file} by typing 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 @@ -328,9 +331,16 @@ check them. 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 @@ -421,16 +431,17 @@ Follow a cross reference at point. 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 @@ -456,11 +467,15 @@ 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 + 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 @@ -586,10 +601,20 @@ Emacs (@code{describe-no-warranty}). @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