[Emacs-diffs] master d5cf1b3 2/4: Improve documentation for "other window" scrolling

[Noam Postavsky]

branch: master
commit d5cf1b3160a5510198fc5dd4e28b3eca7aadf71b
Author: Basil L. Contovounesios <address@hidden>
Commit: Noam Postavsky <address@hidden>

    Improve documentation for "other window" scrolling
    
    * doc/emacs/windows.texi (Other Window):
    * doc/lispref/windows.texi (Textual Scrolling):
    Document scroll-other-window-down.
    * doc/lispref/minibuf.texi (Minibuffer Misc):
    Cross-reference minibuffer-scroll-window with Textual Scrolling.
    * src/window.c (Fother_window_for_scrolling):
    Clarify how "other window" is determined in docstring.
    (Fscroll_other_window): Simplify docstring, pointing to that of
    Fother_window_for_scrolling. (bug#30207)
---
 doc/emacs/windows.texi   | 19 +++++++++++++------
 doc/lispref/minibuf.texi |  2 +-
 doc/lispref/windows.texi |  7 +++++++
 src/window.c             | 27 +++++++++++++--------------
 4 files changed, 34 insertions(+), 21 deletions(-)

diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi
index 8093633..17ce4ad 100644
--- a/doc/emacs/windows.texi
+++ b/doc/emacs/windows.texi
@@ -157,7 +157,9 @@ this option is @code{nil}.
 @item C-x o
 Select another window (@code{other-window}).
 @item C-M-v
-Scroll the next window (@code{scroll-other-window}).
+Scroll the next window upward (@code{scroll-other-window}).
address@hidden C-M-S-v
+Scroll the next window downward (@code{scroll-other-window-down}).
 @item mouse-1
 @kbd{mouse-1}, in the text area of a window, selects the window and
 moves point to the position clicked.  Clicking in the mode line
@@ -181,13 +183,18 @@ back and finish supplying the minibuffer argument that is 
requested.
 
 @kindex C-M-v
 @findex scroll-other-window
address@hidden C-M-S-v
address@hidden scroll-other-window-down
   The usual scrolling commands (@pxref{Display}) apply to the selected
-window only, but there is one command to scroll the next window.
+window only, but there are also commands to scroll the next window.
 @kbd{C-M-v} (@code{scroll-other-window}) scrolls the window that
address@hidden o} would select.  It takes arguments, positive and negative,
-like @kbd{C-v}.  (In the minibuffer, @kbd{C-M-v} scrolls the help
-window associated with the minibuffer, if any, rather than the next
-window in the standard cyclic order; @pxref{Minibuffer Edit}.)
address@hidden o} would select.  In other respects, the command behaves like
address@hidden; both move the buffer text upward relative to the window, and
+take positive and negative arguments.  (In the minibuffer, @kbd{C-M-v}
+scrolls the help window associated with the minibuffer, if any, rather
+than the next window in the standard cyclic order; @pxref{Minibuffer
+Edit}.)  @kbd{C-M-S-v} (@code{scroll-other-window-down}) scrolls the
+next window downward in a similar way.
 
 @vindex mouse-autoselect-window
   If you set @code{mouse-autoselect-window} to a address@hidden value,
diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index 338e03e..889b64a 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -2462,7 +2462,7 @@ locally inside the minibuffer (@pxref{Help Functions}).
 @anchor{Definition of minibuffer-scroll-window}
 If the value of this variable is address@hidden, it should be a window
 object.  When the function @code{scroll-other-window} is called in the
-minibuffer, it scrolls this window.
+minibuffer, it scrolls this window (@pxref{Textual Scrolling}).
 @end defvar
 
 @defun minibuffer-selected-window
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index f5de2fc..315ffd4 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -4028,6 +4028,13 @@ line reappears after the echo area momentarily displays 
the message
 @samp{End of buffer}.
 @end deffn
 
address@hidden Command scroll-other-window-down &optional count
+This function scrolls the text in another window downward @var{count}
+lines.  Negative values of @var{count}, or @code{nil}, are handled as
+in @code{scroll-down}.  In other respects, it behaves the same way as
address@hidden does.
address@hidden deffn
+
 @defvar other-window-scroll-buffer
 If this variable is address@hidden, it tells @code{scroll-other-window}
 which buffer's window to scroll.
diff --git a/src/window.c b/src/window.c
index 59c9422..af31767 100644
--- a/src/window.c
+++ b/src/window.c
@@ -5696,11 +5696,12 @@ When calling from a program, supply as argument a 
number, nil, or `-'.  */)
 
 DEFUN ("other-window-for-scrolling", Fother_window_for_scrolling, 
Sother_window_for_scrolling, 0, 0, 0,
        doc: /* Return the other window for \"other window scroll\" commands.
-If `other-window-scroll-buffer' is non-nil, a window
-showing that buffer is used.
 If in the minibuffer, `minibuffer-scroll-window' if non-nil
-specifies the window.  This takes precedence over
-`other-window-scroll-buffer'.  */)
+specifies the window.
+Otherwise, if `other-window-scroll-buffer' is non-nil, a window
+showing that buffer is used, popping the buffer up if necessary.
+Finally, look for a neighboring window on the selected frame,
+followed by all visible frames on the current terminal.  */)
   (void)
 {
   Lisp_Object window;
@@ -5739,16 +5740,14 @@ specifies the window.  This takes precedence over
 DEFUN ("scroll-other-window", Fscroll_other_window, Sscroll_other_window, 0, 
1, "P",
        doc: /* Scroll next window upward ARG lines; or near full screen if no 
ARG.
 A near full screen is `next-screen-context-lines' less than a full screen.
-The next window is the one below the current one; or the one at the top
-if the current one is at the bottom.  Negative ARG means scroll downward.
-If ARG is the atom `-', scroll downward by nearly full screen.
-When calling from a program, supply as argument a number, nil, or `-'.
-
-If `other-window-scroll-buffer' is non-nil, scroll the window
-showing that buffer, popping the buffer up if necessary.
-If in the minibuffer, `minibuffer-scroll-window' if non-nil
-specifies the window to scroll.  This takes precedence over
-`other-window-scroll-buffer'.  */)
+Negative ARG means scroll downward.  If ARG is the atom `-', scroll
+downward by nearly full screen.  When calling from a program, supply
+as argument a number, nil, or `-'.
+
+The next window is usually the one below the current one;
+or the one at the top if the current one is at the bottom.
+It is determined by the function `other-window-for-scrolling',
+which see.  */)
   (Lisp_Object arg)
 {
   Lisp_Object window;