X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/846d7db22f9a3c43415efa5171f1789318b677a5..74338b5eb869852f7305c40f830e1dc5ea19d145:/man/help.texi diff --git a/man/help.texi b/man/help.texi index 29c06b499d..747f51aaaa 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 @@ -32,8 +32,8 @@ 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}. +hyperlinks to URLs and further help regarding cross-referenced names, Info +nodes, customization buffers and the like. @xref{Help Mode}. @cindex searching documentation efficiently @cindex looking for a subject in documentation @@ -44,19 +44,11 @@ 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 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 -descriptions) of all variables and functions (not their names) for a -match for @var{topic}, a regular expression. @xref{Apropos}. +@item C-h a @var{topics} @key{RET} +This searches for commands whose names match @var{topics}, which +should be a keyword, a list of keywords, or a regular expression +(@pxref{Regexps}). This command displays all the matches in a new +buffer. @xref{Apropos}. @item C-h i d m emacs @key{RET} i @var{topic} @key{RET} This looks up @var{topic} in the indices of the Emacs on-line manual. @@ -111,9 +103,9 @@ command. pre-written file of information. @table @kbd -@item C-h a @var{regexp} @key{RET} -Display a list of commands whose names match @var{regexp} -(@code{apropos-command}). +@item C-h a @var{topics} @key{RET} +Display a list of commands whose names match @var{topics} +(@code{apropos-command}; @pxref{Apropos}). @item C-h b Display a table of all key bindings in effect now, in this order: minor mode bindings, major mode bindings, and global bindings @@ -122,6 +114,12 @@ mode bindings, major mode bindings, and global bindings Show the name of the command that @var{key} runs (@code{describe-key-briefly}). Here @kbd{c} stands for ``character.'' For more extensive information on @var{key}, use @kbd{C-h k}. +@item C-h d @var{topics} @key{RET} +Display a list of commands and variables whose documentation matches +@var{topics} (@code{apropos-documentation}). +@item C-h e +Display the @code{*Messages*} buffer +(@code{view-echo-area-messages}). @item C-h f @var{function} @key{RET} Display documentation on the Lisp function named @var{function} (@code{describe-function}). Since commands are Lisp functions, @@ -265,35 +263,69 @@ editor, you need to read the source code. @node Apropos @section Apropos + A more sophisticated sort of question to ask is, ``What are the +commands for working with files?'' The @dfn{apropos} commands ask +such questions---they look for things whose names match an +@dfn{apropos pattern}, which means either a word, a list of words, or +a regular expression. Each apropos command displays a list of +matching items in a special buffer. + +@table @kbd +@item C-h a @var{pattern} @key{RET} +Search for commands whose names match @var{pattern}. + +@item M-x apropos @key{RET} @var{pattern} @key{RET} +Similar, but it searches for noninteractive functions and for +variables, as well as commands. + +@item M-x apropos-variable @key{RET} @var{pattern} @key{RET} +Similar, but it searches for variables only. + +@item M-x apropos-value @key{RET} @var{pattern} @key{RET} +Similar, but it searches for variables based on their values, or +functions based on their definitions. + +@item C-h d @var{pattern} @key{RET} +Search the @emph{documentation strings} (the built-in short +descriptions) of all variables and functions (not their names) for a +match for @var{pattern}. +@end table + @kindex C-h a @findex apropos-command @cindex apropos - A more sophisticated sort of question to ask is, ``What are the -commands for working with files?'' To ask this question, type @kbd{C-h -a file @key{RET}}, which displays a list of all command names that -contain @samp{file}, including @code{copy-file}, @code{find-file}, and -so on. With each command name appears a brief description of how to use -the command, and what keys you can currently invoke it with. For -example, it would say that you can invoke @code{find-file} by typing -@kbd{C-x C-f}. The @kbd{a} in @kbd{C-h a} stands for ``Apropos''; -@kbd{C-h a} runs the command @code{apropos-command}. This command -normally checks only commands (interactive functions); if you specify a -prefix argument, it checks noninteractive functions as well. - - Because @kbd{C-h a} looks only for 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}). + To find the commands that work on files, type @kbd{C-h a file +@key{RET}}. This displays a list of all command names that contain +@samp{file}, including @code{copy-file}, @code{find-file}, and so on. +With each command name appears a brief description of how to use the +command, and what keys you can currently invoke it with. For example, +it would say that you can invoke @code{find-file} by typing @kbd{C-x +C-f}. The @kbd{a} in @kbd{C-h a} stands for ``Apropos''; @kbd{C-h a} +runs the command @code{apropos-command}. This command normally checks +only commands (interactive functions); if you specify a prefix +argument, it checks noninteractive functions as well. + + If you want more information about a function definition, variable or +symbol property listed in the Apropos buffer, you can click on it with +@kbd{Mouse-1} or @kbd{Mouse-2}, or move there and type @key{RET}. + + @kbd{C-h a} with a single word can find too many matches. Don't +just give up; you can give Apropos a list of words to search for. +When you specify more than one word in the apropos pattern, a name +must contain at least two of the words in order to match. Thus, if +you are looking for commands to kill a chunk of text before point, you +could try @kbd{C-h a kill back backward behind before @key{RET}}. + + For even greater flexibility, you can specify a regular expression +(@pxref{Regexps}). An apropos pattern is interpreted as a regular +expression if it contains any of the regular expression special +characters, @samp{^$*+?.\[}. Here is a set of arguments to give to @kbd{C-h a} that covers many -classes of Emacs commands, since there are strong conventions for naming -the standard Emacs commands. By giving you a feel for the naming -conventions, this set should also serve to aid you in developing a -technique for picking @code{apropos} strings. +classes of Emacs commands, since there are strong conventions for +naming the standard Emacs commands. By giving you a feel for the +naming conventions, this set should also serve to aid you in +developing a technique for picking Apropos keywords. @quotation char, line, word, sentence, paragraph, region, page, sexp, list, defun, @@ -303,29 +335,29 @@ mark, insert, yank, fill, indent, case, change, set, what, list, find, view, describe, default. @end quotation +@findex apropos + To list all Lisp symbols that contain a match for an Apropos pattern, +not just the ones that are defined as commands, use the command +@kbd{M-x apropos} instead of @kbd{C-h a}. This command does not check +key bindings by default; specify a numeric argument if you want it to +check them. + @findex apropos-variable - To list all user variables that match a regexp, use the command -@kbd{M-x apropos-variable}. By default, this command shows only -variables meant for user customization; if you specify a prefix + To list user-customizable variables that match an apropos pattern, +use the command @kbd{M-x apropos-variable}. If you specify a prefix argument, it checks all variables. -@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. - +@kindex C-h d @findex apropos-documentation - The @code{apropos-documentation} command is like @code{apropos} except -that it searches documentation strings as well as symbol names for -matches for the specified regular expression. + The @code{apropos-documentation} command is like @code{apropos} +except that it searches documentation strings instead of symbol names +for matches for the specified Apropos pattern. @findex apropos-value - The @code{apropos-value} command is like @code{apropos} except that it -searches symbols' values for matches for the specified regular -expression. This command does not check function definitions or -property lists by default; specify a numeric argument if you want it to -check them. + The @code{apropos-value} command is like @code{apropos} except that +it searches variables' values for matches for the pattern. With a +prefix argument, it also checks symbols' function definitions and +property lists. @vindex apropos-do-all If the variable @code{apropos-do-all} is non-@code{nil}, the commands @@ -338,9 +370,11 @@ 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-1} or @kbd{Mouse-2}, or move there and type @key{RET}. +@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 @@ -443,6 +477,16 @@ 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. +@cindex URL, viewing in help +@cindex help, viewing web pages +@cindex viewing web pages in help +@cindex web pages, viewing in help +@findex browse-url + You can follow cross references to URLs (web pages) as well. When +you follow a cross reference that is a URL, the @code{browse-url} +command is used to view the web page in a browser of your choosing. +@xref{Browse-URL}. + @kindex @key{TAB} @r{(Help mode)} @findex help-next-ref @kindex S-@key{TAB} @r{(Help mode)} @@ -603,8 +647,10 @@ Emacs (@code{describe-no-warranty}). the mouse or a key like @kbd{RET}, it often has associated help text. 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. +help''), when you move the mouse over the active text. @xref{Tooltips}. +On some systems, it is shown in the echo area. On text-only +terminals, Emacs may not be able to follow the mouse and hence will +not show the help text on mouse-over. @kindex C-h . @findex display-local-help