1 files changed, 68 insertions, 16 deletions
diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi
index 7dcd09b3a13..d206dee3859 100644
--- a/doc/emacs/help.texi
+++ b/doc/emacs/help.texi
@@ -20,10 +20,28 @@ commands (@code{help-for-help}).  You can scroll the list with
 @key{SPC} and @key{DEL}, then type the help command you want.  To
 cancel, type @kbd{C-g}.
 
+@cindex help buffer
   Many help commands display their information in a special @dfn{help
 buffer}.  In this buffer, you can type @key{SPC} and @key{DEL} to
 scroll and type @key{RET} to follow hyperlinks.  @xref{Help Mode}.
 
+@vindex help-window-select
+  By default, help commands display the help buffer in a separate
+window without selecting that window.  The variable
+@code{help-window-select} controls this: its default value is
+@code{nil}; if it's customized to the value @code{t}, the help window
+is unconditionally selected by help commands, and if its value is
+@code{other}, the help window is selected only if there are more than
+two windows on the selected frame.
+
+@vindex help-window-keep-selected
+  Conversely, many commands in the @samp{*Help*} buffer will pop up a
+new window to display the results.  For instance, clicking on the link
+to show the source code, or using the @key{i} command to display the
+manual entry, will (by default) pop up a new window.  If
+@code{help-window-keep-selected} is changed to non-@code{nil}, the
+window displaying the @samp{*Help*} buffer will be reused instead.
+
 @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
@@ -182,7 +200,10 @@ 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
-@file{*Help*} buffers.)  @xref{Help Echo}.
+@file{*Help*} buffers.)  @xref{Help Echo}.  If you invoke
+this command with a prefix argument, @kbd{C-u C-h .}, and point is on
+a button or a widget, this command will pop a new buffer that
+describes that button/widget.
 @end table
 
 @node Key Help
@@ -332,9 +353,9 @@ are included varies depending on the command used.
 @cindex 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.
+commands for working with files?''  More precisely, you specify your
+query as an @dfn{apropos pattern}, which is either a word, a list of
+words, or a regular expression.
 
   Each of the following apropos commands reads an apropos pattern in
 the minibuffer, searches for items that match the pattern, and
@@ -393,6 +414,12 @@ 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}.
 
+@vindex help-window-select@r{, and apropos commands}
+  By default, the window showing the apropos buffer with the results
+of the query is not selected, but you can cause it to be selected by
+customizing the variable @code{help-window-select} to any
+non-@code{nil} value.
+
   For more information about a function definition, variable or symbol
 property listed in an apropos buffer, you can click on it with
 @kbd{mouse-1} or @kbd{mouse-2}, or move there and type @key{RET}.
@@ -461,20 +488,26 @@ Move point back to the previous hyperlink (@code{backward-button}).
 @item mouse-1
 @itemx mouse-2
 Follow a hyperlink that you click on.
+@item n
+@itemx p
+Move forward and back between pages in the Help buffer.
 @item C-c C-c
 Show all documentation about the symbol at point
 (@code{help-follow-symbol}).
 @item C-c C-f
 @itemx r
-Go forward to the next help topic (@code{help-go-forward}).
+Go forward in history of help commands (@code{help-go-forward}).
 @item C-c C-b
 @itemx l
-Go back to the previous help topic (@code{help-go-back}).
+Go back in history of help commands (@code{help-go-back}).
 @item s
 View the source of the current help topic (if any)
 (@code{help-view-source}).
 @item i
 Look up the current topic in the manual(s) (@code{help-goto-info}).
+@item I
+Look up the current topic in the Emacs Lisp manual
+(@code{help-goto-lispref-info}).
 @item c
 Customize the variable or the face (@code{help-customize}).
 @end table
@@ -498,6 +531,35 @@ C-b} or @kbd{l} (@code{help-go-back}).  While retracing your steps,
 you can go forward by using @kbd{C-c C-f} or @kbd{r}
 (@code{help-go-forward}).
 
+@kindex TAB @r{(Help mode)}
+@findex forward-button
+@kindex S-TAB @r{(Help mode)}
+@findex backward-button
+  To move between hyperlinks in a help buffer, use @key{TAB}
+(@code{forward-button}) to move forward to the next hyperlink and
+@kbd{S-@key{TAB}} (@code{backward-button}) to move back to the
+previous hyperlink.  These commands act cyclically; for instance,
+typing @key{TAB} at the last hyperlink moves back to the first
+hyperlink.
+
+@vindex help-clean-buttons
+  By default, many links in the help buffer are displayed surrounded
+by quote characters.  If the @code{help-clean-buttons} user option is
+non-@code{nil}, these quote characters are removed from the buffer.
+
+@kindex n @r{(Help mode)}
+@kindex p @r{(Help mode)}
+@findex help-goto-next-page
+@findex help-goto-previous-page
+  Help buffers produced by some Help commands (like @kbd{C-h b}, which
+shows a long list of key bindings) are divided into pages by the
+@samp{^L} character.  In such buffers, the @kbd{n}
+(@code{help-goto-next-page}) command will take you to the next start
+of page, and the @kbd{p} (@code{help-goto-previous-page}) command will
+take you to the previous start of page.  This way you can quickly
+navigate between the different kinds of documentation in a help
+buffer.
+
 @cindex URL, viewing in help
 @cindex help, viewing web pages
 @cindex viewing web pages in help
@@ -507,16 +569,6 @@ code definitions, and URLs (web pages).  The first two are opened in
 Emacs, and the third using a web browser via the @code{browse-url}
 command (@pxref{Browse-URL}).
 
-@kindex TAB @r{(Help mode)}
-@findex forward-button
-@kindex S-TAB @r{(Help mode)}
-@findex backward-button
-  In a help buffer, @key{TAB} (@code{forward-button}) moves point
-forward to the next hyperlink, while @kbd{S-@key{TAB}}
-(@code{backward-button}) moves point back to the previous hyperlink.
-These commands act cyclically; for instance, typing @key{TAB} at the
-last hyperlink moves back to the first hyperlink.
-
   To view all documentation about any symbol in the text, move point
 to the symbol and type @kbd{C-c C-c} (@code{help-follow-symbol}).
 This shows the documentation for all the meanings of the symbol---as a