From: Eli Zaretskii <eliz@gnu.org>
Date: Sun, 1 May 2022 07:01:28 +0000 (+0300)
Subject: Document 'help-window-select'
X-Git-Tag: emacs-29.0.90~1931^2~163
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=a3024ab4fb6b608d2110aa778c1eadec8113f498;p=emacs.git

Document 'help-window-select'

* etc/NEWS:
* doc/emacs/help.texi (Apropos, Help): Document
'help-window-select'; improve indexing.  (Bug#46034)
---

diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi
index a4b329d0890..3c8f90da102 100644
--- a/doc/emacs/help.texi
+++ b/doc/emacs/help.texi
@@ -20,10 +20,20 @@ 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.
+
 @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
@@ -335,9 +345,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
@@ -396,6 +406,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}.
diff --git a/etc/NEWS b/etc/NEWS
index 47e04cfcbe9..3f22e0b04e9 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -478,6 +478,11 @@ displayed, if any.
 It now only includes local minor modes at the start, and the global
 minor modes are listed after the major mode.
 
++++
+*** The user option 'help-window-select' now affects apropos commands.
+The apropos commands will now select the apropos window if
+'help-window-select' is non-nil.
+
 ** Outline Mode
 
 +++