]> code.delx.au - gnu-emacs/blobdiff - man/help.texi
(last_point_position_window): Declare.
[gnu-emacs] / man / help.texi
index 29c06b499df0c7273ab392f4cca7f1e0a0a2113b..747f51aaaa7d8fe071d38232ff96b24a483b9a5c 100644 (file)
@@ -1,6 +1,6 @@
 @c This is part of the Emacs manual.
 @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
 @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
 
   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
 
 @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
 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.
 
 @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
 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
 @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}.
 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,
 @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
 
 @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
 @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
 
   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,
 
 @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
 
 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
 @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.
 
 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
 @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
 
 @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
 
 @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.
 
 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
 
 @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.
 
 @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)}
 @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
 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
 
 @kindex C-h .
 @findex display-local-help