From 53aac6aecd24ad95a8224f05784687dd1de13ccb Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Sat, 18 Oct 2025 10:47:29 +0300
Subject: [PATCH] ; Improve documentation of commands that split current window

* doc/emacs/sending.texi (Sending Mail):
* doc/emacs/dired.texi (Dired Enter, Dired Visiting):
* doc/emacs/maintaining.texi (Old Revisions)
(Change Log Commands, Looking Up Identifiers):
* doc/emacs/windows.texi (Displaying Buffers):
* doc/emacs/files.texi (Visiting): Add cross-references to where
user options are described which control how windows are split.

* lisp/mail/sendmail.el (mail-other-window):
* lisp/gnus/message.el (message-mail-other-window)
(message-news-other-window):
* lisp/replace.el (occur-mode-goto-occurrence-other-window):
* lisp/vc/vc.el (vc-revision-other-window):
* lisp/vc/vc-dir.el (vc-dir-find-file-other-window):
* lisp/progmodes/xref.el (xref-find-definitions-other-window):
* lisp/simple.el (compose-mail-other-window)
(clone-indirect-buffer-other-window):
* lisp/vc/add-log.el (add-change-log-entry-other-window):
* lisp/view.el (view-file-other-window)
(view-buffer-other-window):
* lisp/window.el (switch-to-buffer-other-window):
* lisp/files.el (find-file-other-window)
(find-file-read-only-other-window)
(find-alternate-file-other-window):
* lisp/dired.el (dired-other-window)
(dired-mouse-find-file-other-window)
(dired-find-file-other-window, dired-jump-other-window): Mention
in the doc strings how to control the way the current window is
split.
---
 doc/emacs/dired.texi       |  7 ++++---
 doc/emacs/files.texi       |  7 ++++---
 doc/emacs/maintaining.texi |  9 +++++----
 doc/emacs/sending.texi     |  3 ++-
 doc/emacs/windows.texi     |  5 +++--
 lisp/dired.el              | 20 ++++++++++++++++----
 lisp/files.el              | 17 ++++++++++++++---
 lisp/gnus/message.el       | 10 ++++++++--
 lisp/mail/sendmail.el      |  5 ++++-
 lisp/progmodes/xref.el     |  5 ++++-
 lisp/replace.el            |  5 ++++-
 lisp/simple.el             | 10 ++++++++--
 lisp/vc/add-log.el         |  5 ++++-
 lisp/vc/vc-dir.el          |  5 ++++-
 lisp/vc/vc.el              |  6 +++++-
 lisp/view.el               | 12 ++++++++++--
 lisp/window.el             |  5 ++++-
 17 files changed, 103 insertions(+), 33 deletions(-)

diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi
index 53cbcd65c10..24a9b5775ea 100644
--- a/doc/emacs/dired.texi
+++ b/doc/emacs/dired.texi
@@ -124,7 +124,7 @@ buffer, Emacs displays the directory listing of the parent directory
 and places point on the line that corresponds to the directory where
 you invoked @code{dired-jump}.  Typing @kbd{C-x 4 C-j}
 (@code{dired-jump-other-window}) has the same effect, but displays the
-Dired buffer in a new window.
+Dired buffer in a new window (@pxref{Window Choice}).
 
   The variable @code{dired-listing-switches} specifies the options to
 give to @command{ls} for listing the directory; this string
@@ -182,7 +182,7 @@ peculiarities of this emulation.
   To display the Dired buffer in another window, use @kbd{C-x 4 d}
 (@code{dired-other-window}).  @kbd{C-x 5 d}
 (@code{dired-other-frame}) displays the Dired buffer in a separate
-frame.
+frame.  @xref{Window Choice}.
 
 @kindex q @r{(Dired)}
 @findex quit-window@r{, in Dired buffers}
@@ -435,7 +435,8 @@ that of an alternate file or directory (@code{dired-find-alternate-file}).
 @item o
 @kindex o @r{(Dired)}
 @findex dired-find-file-other-window
-Like @kbd{f}, but uses another window to display the file's buffer
+Like @kbd{f}, but uses another window (@pxref{Window Choice}) to display
+the file's buffer
 (@code{dired-find-file-other-window}).  The Dired buffer remains visible
 in the first window.  This is like using @kbd{C-x 4 C-f} to visit the
 file.  @xref{Windows}.
diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 7c798331711..cb2903166a2 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -287,9 +287,10 @@ yourself from entering changes accidentally, visit it with the command
 except that the buffer containing the specified file is selected in another
 window.  The window that was selected before @kbd{C-x 4 f} continues to
 show the same buffer it was already showing.  If this command is used when
-only one window is being displayed, that window is split in two, with one
-window showing the same buffer as before, and the other one showing the
-newly requested file.  @xref{Windows}.
+only one window is being displayed, that window is split in two
+(@pxref{Window Choice}), with one window showing the same buffer as
+before, and the other one showing the newly requested file.
+@xref{Windows}.
 
 @kindex C-x 5 f
 @findex find-file-other-frame
diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index c6eeab770fe..e5e1ba9976d 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -944,7 +944,7 @@ and type @kbd{C-x v ~ @var{revision} @key{RET}}
 (@code{vc-revision-other-window}).  This retrieves the file version
 corresponding to @var{revision}, saves it to
 @file{@var{filename}.~@var{revision}~}, and visits it in a separate
-window.
+window (@pxref{Window Choice}).
 
 @findex vc-annotate
 @vindex vc-annotate-background-mode
@@ -2073,7 +2073,8 @@ a backup file, it makes an entry appropriate for the file's
 parent---that is useful for making log entries for functions that
 have been deleted in the current version.
 
-  @kbd{C-x 4 a} visits the change log file and creates a new entry
+  @kbd{C-x 4 a} visits the change log file in a window other than the
+selected one (@pxref{Window Choice}) and creates a new entry
 unless the most recent entry is for today's date and your name.  It
 also creates a new item for the current file.  For many languages, it
 can even guess the name of the function or other object that was
@@ -2341,8 +2342,8 @@ known identifier names being the completion candidates.
 @findex xref-find-definitions-other-frame
   Like most commands that can switch buffers,
 @code{xref-find-definitions} has a variant that displays the new
-buffer in another window, and one that makes a new frame for it.  The
-former is @w{@kbd{C-x 4 .}}
+buffer in another window (@pxref{Window Choice}), and one that makes a
+new frame for it.  The former is @w{@kbd{C-x 4 .}}
 (@code{xref-find-definitions-other-window}), and the latter is
 @w{@kbd{C-x 5 .}}  (@code{xref-find-definitions-other-frame}).
 
diff --git a/doc/emacs/sending.texi b/doc/emacs/sending.texi
index 5d610148a4f..0c45330eb24 100644
--- a/doc/emacs/sending.texi
+++ b/doc/emacs/sending.texi
@@ -48,7 +48,8 @@ you pick up editing the message where you left off.
   The command @kbd{C-x 4 m} (@code{compose-mail-other-window}) does
 the same as @kbd{C-x m}, except it displays the mail buffer in a
 different window.  The command @kbd{C-x 5 m}
-(@code{compose-mail-other-frame}) does it in a new frame.
+(@code{compose-mail-other-frame}) does it in a new frame.  @xref{Window
+Choice}.
 
   When you type @kbd{C-c C-c} or @kbd{C-c C-s} to send the mail, Emacs
 may ask you how it should deliver the mail---either directly via SMTP,
diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi
index d0136db7b8a..6753bfb8d76 100644
--- a/doc/emacs/windows.texi
+++ b/doc/emacs/windows.texi
@@ -410,8 +410,9 @@ Reference Manual}.
 
   Commands with names ending in @code{-other-window} behave like
 @code{display-buffer}, except that they never display in the selected
-window.  Several of these commands are bound in the @kbd{C-x 4} prefix
-key (@pxref{Pop Up Window}).
+window, perhaps splitting the selected window to create a new one
+(@pxref{Window Choice}).  Several of these commands are bound in the
+@kbd{C-x 4} prefix key (@pxref{Pop Up Window}).
 
   Commands with names ending in @code{-other-frame} behave like
 @code{display-buffer}, except that they (i) never display in the
diff --git a/lisp/dired.el b/lisp/dired.el
index cca6fb2e6ea..369c70b3d15 100644
--- a/lisp/dired.el
+++ b/lisp/dired.el
@@ -1203,7 +1203,10 @@ If DIRNAME is already in a Dired buffer, that buffer is used without refresh."
 ;;;###autoload (define-key ctl-x-4-map "d" 'dired-other-window)
 ;;;###autoload
 (defun dired-other-window (dirname &optional switches)
-  "\"Edit\" directory DIRNAME.  Like `dired' but select in another window."
+  "\"Edit\" directory DIRNAME.  Like `dired' but select in another window.
+If this command needs to split the current window, it by default obeys
+the user options `split-height-threshold' and `split-width-threshold',
+when it decides whether to split the window horizontally or vertically."
   (interactive (dired-read-dir-and-switches "in other window "))
   (switch-to-buffer-other-window (dired-noselect dirname switches)))
 
@@ -3077,7 +3080,10 @@ so that the original Dired buffer is not kept."
       (dired--find-file find-file-func (file-name-sans-versions file t)))))
 
 (defun dired-mouse-find-file-other-window (event)
-  "In Dired, visit the file or directory name you click on in another window."
+  "In Dired, visit the file or directory name you click on in another window.
+If this command needs to split the current window, it by default obeys
+the user options `split-height-threshold' and `split-width-threshold',
+when it decides whether to split the window horizontally or vertically."
   (interactive "e" dired-mode)
   (dired-mouse-find-file event 'find-file-other-window 'dired-other-window))
 
@@ -3099,7 +3105,10 @@ Otherwise, display it in another buffer."
       (view-file file))))
 
 (defun dired-find-file-other-window ()
-  "In Dired, visit this file or directory in another window."
+  "In Dired, visit this file or directory in another window.
+If this command needs to split the current window, it by default obeys
+the user options `split-height-threshold' and `split-width-threshold',
+when it decides whether to split the window horizontally or vertically."
   (interactive nil dired-mode)
   (dired--find-file #'find-file-other-window (dired-get-file-for-visit)))
 
@@ -5215,7 +5224,10 @@ Interactively with prefix argument, read FILE-NAME."
 
 ;;;###autoload
 (defun dired-jump-other-window (&optional file-name)
-  "Like \\[dired-jump] (`dired-jump') but in other window."
+  "Like \\[dired-jump] (`dired-jump') but in other window.
+If this command needs to split the current window, it by default obeys
+the user options `split-height-threshold' and `split-width-threshold',
+when it decides whether to split the window horizontally or vertically."
   (interactive
    (list (and current-prefix-arg
 	      (read-file-name "Jump to Dired file: "))))
diff --git a/lisp/files.el b/lisp/files.el
index 6544ee54ee4..c6211d84700 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -1988,7 +1988,11 @@ current directory to be available on first \\[next-history-element]
 request.
 
 Interactively, or if WILDCARDS is non-nil in a call from Lisp,
-expand wildcards (if any) and visit multiple files."
+expand wildcards (if any) and visit multiple files.
+
+If this command needs to split the current window, it by default obeys
+the user options `split-height-threshold' and `split-width-threshold',
+when it decides whether to split the window horizontally or vertically."
   (interactive
    (find-file-read-args "Find file in other window: "
                         (confirm-nonexistent-file-or-buffer)))
@@ -2068,7 +2072,10 @@ Use \\[read-only-mode] to permit editing."
 (defun find-file-read-only-other-window (filename &optional wildcards)
   "Edit file FILENAME in another window but don't allow changes.
 Like \\[find-file-other-window], but marks buffer as read-only.
-Use \\[read-only-mode] to permit editing."
+Use \\[read-only-mode] to permit editing.
+If this command needs to split the current window, it by default obeys
+the user options `split-height-threshold' and `split-width-threshold',
+when it decides whether to split the window horizontally or vertically."
   (interactive
    (find-file-read-args "Find file read-only other window: "
                         (confirm-nonexistent-file-or-buffer)))
@@ -2090,7 +2097,11 @@ This command does not select that window.
 See \\[find-file] for the possible forms of the FILENAME argument.
 
 Interactively, or if WILDCARDS is non-nil in a call from Lisp,
-expand wildcards (if any) and replace the file with multiple files."
+expand wildcards (if any) and replace the file with multiple files.
+
+If this command needs to split the current window, it by default obeys
+the user options `split-height-threshold' and `split-width-threshold',
+when it decides whether to split the window horizontally or vertically."
   (interactive
    (save-selected-window
      (other-window 1)
diff --git a/lisp/gnus/message.el b/lisp/gnus/message.el
index d97d2bbc21c..099a538daa0 100644
--- a/lisp/gnus/message.el
+++ b/lisp/gnus/message.el
@@ -8116,7 +8116,10 @@ you."
 
 ;;;###autoload
 (defun message-mail-other-window (&optional to subject)
-  "Like `message-mail' command, but display mail buffer in another window."
+  "Like `message-mail' command, but display mail buffer in another window.
+If this command needs to split the current window, it by default obeys
+the user options `split-height-threshold' and `split-width-threshold',
+when it decides whether to split the window horizontally or vertically."
   (interactive)
   (unless (message-mail-user-agent)
     (message-pop-to-buffer (message-buffer-name "mail" to)
@@ -8138,7 +8141,10 @@ you."
 
 ;;;###autoload
 (defun message-news-other-window (&optional newsgroups subject)
-  "Start editing a news article to be sent."
+  "Start editing a news article to be sent.
+If this command needs to split the current window, it by default obeys
+the user options `split-height-threshold' and `split-width-threshold',
+when it decides whether to split the window horizontally or vertically."
   (interactive)
   (message-pop-to-buffer (message-buffer-name "posting" nil newsgroups)
 			 'switch-to-buffer-other-window)
diff --git a/lisp/mail/sendmail.el b/lisp/mail/sendmail.el
index 44e960969d8..3ef22d2fd65 100644
--- a/lisp/mail/sendmail.el
+++ b/lisp/mail/sendmail.el
@@ -2047,7 +2047,10 @@ you can move to one of them and type C-c C-c to recover that one."
 
 ;;;###autoload
 (defun mail-other-window (&optional noerase to subject in-reply-to cc replybuffer sendactions)
-  "Like `mail' command, but display mail buffer in another window."
+  "Like `mail' command, but display mail buffer in another window.
+If this command needs to split the current window, it by default obeys
+the user options `split-height-threshold' and `split-width-threshold',
+when it decides whether to split the window horizontally or vertically."
   (interactive "P")
   (switch-to-buffer-other-window "*mail*")
   (mail noerase to subject in-reply-to cc replybuffer sendactions))
diff --git a/lisp/progmodes/xref.el b/lisp/progmodes/xref.el
index 4c27aff06a4..fa1ba8846fa 100644
--- a/lisp/progmodes/xref.el
+++ b/lisp/progmodes/xref.el
@@ -1645,7 +1645,10 @@ Use \\[xref-go-back] to return back to where you invoked this command."
 
 ;;;###autoload
 (defun xref-find-definitions-other-window (identifier)
-  "Like `xref-find-definitions' but switch to the other window."
+  "Like `xref-find-definitions' but switch to the other window.
+If this command needs to split the current window, it by default obeys
+the user options `split-height-threshold' and `split-width-threshold',
+when it decides whether to split the window horizontally or vertically."
   (interactive (list (xref--read-identifier "Find definitions of: ")))
   (xref--find-definitions identifier 'window))
 
diff --git a/lisp/replace.el b/lisp/replace.el
index ab3db69bd20..ff22641eb48 100644
--- a/lisp/replace.el
+++ b/lisp/replace.el
@@ -1522,7 +1522,10 @@ If not invoked by a mouse click, go to occurrence on the current line."
     (run-hooks 'occur-mode-find-occurrence-hook)))
 
 (defun occur-mode-goto-occurrence-other-window ()
-  "Go to the occurrence the current line describes, in another window."
+  "Go to the occurrence the current line describes, in another window.
+If this command needs to split the current window, it by default obeys
+the user options `split-height-threshold' and `split-width-threshold',
+when it decides whether to split the window horizontally or vertically."
   (interactive)
   (let ((buffer (current-buffer))
         (pos (occur--targets-start (occur-mode--find-occurrences))))
diff --git a/lisp/simple.el b/lisp/simple.el
index e1f6ae8b683..ae510722096 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -9768,7 +9768,10 @@ To disable this warning, set `compose-mail-user-agent-warnings' to nil."
 (defun compose-mail-other-window (&optional to subject other-headers continue
 					    yank-action send-actions
 					    return-action)
-  "Like \\[compose-mail], but edit the outgoing message in another window."
+  "Like \\[compose-mail], but edit the outgoing message in another window.
+If this command needs to split the current window, it by default obeys
+the user options `split-height-threshold' and `split-width-threshold',
+when it decides whether to split the window horizontally or vertically."
   (interactive (list nil nil nil current-prefix-arg))
   (compose-mail to subject other-headers continue
 		'switch-to-buffer-other-window yank-action send-actions
@@ -10707,7 +10710,10 @@ Returns the newly created indirect buffer."
 
 
 (defun clone-indirect-buffer-other-window (newname display-flag &optional norecord)
-  "Like `clone-indirect-buffer' but display in another window."
+  "Like `clone-indirect-buffer' but display in another window.
+If this command needs to split the current window, it by default obeys
+the user options `split-height-threshold' and `split-width-threshold',
+when it decides whether to split the window horizontally or vertically."
   (interactive
    (progn
      (if (get major-mode 'no-clone-indirect)
diff --git a/lisp/vc/add-log.el b/lisp/vc/add-log.el
index 2208f50812e..408d6ba1c98 100644
--- a/lisp/vc/add-log.el
+++ b/lisp/vc/add-log.el
@@ -1020,7 +1020,10 @@ non-nil, otherwise in local time."
 (defun add-change-log-entry-other-window (&optional whoami file-name)
   "Find change log file in other window and add entry and item.
 This is just like `add-change-log-entry' except that it displays
-the change log file in another window."
+the change log file in another window.
+If this command needs to split the current window, it by default obeys
+the user options `split-height-threshold' and `split-width-threshold',
+when it decides whether to split the window horizontally or vertically."
   (interactive (if current-prefix-arg
 		   (list current-prefix-arg
 			 (prompt-for-change-log-name))))
diff --git a/lisp/vc/vc-dir.el b/lisp/vc/vc-dir.el
index 54914bfd663..fde11926312 100644
--- a/lisp/vc/vc-dir.el
+++ b/lisp/vc/vc-dir.el
@@ -912,7 +912,10 @@ system."
   (find-file (vc-dir-current-file)))
 
 (defun vc-dir-find-file-other-window (&optional event)
-  "Find the file on the current line, in another window."
+  "Find the file on the current line, in another window.
+If this command needs to split the current window, it by default obeys
+the user options `split-height-threshold' and `split-width-threshold',
+when it decides whether to split the window horizontally or vertically."
   (interactive (list last-nonmenu-event))
   (if event (posn-set-point (event-end event)))
   (find-file-other-window (vc-dir-current-file)))
diff --git a/lisp/vc/vc.el b/lisp/vc/vc.el
index 1ca895cbecc..dba415c03af 100644
--- a/lisp/vc/vc.el
+++ b/lisp/vc/vc.el
@@ -2298,7 +2298,11 @@ Return nil if the root directory cannot be identified."
 (defun vc-revision-other-window (rev)
   "Visit revision REV of the current file in another window.
 If the current file is named `F', the revision is named `F.~REV~'.
-If `F.~REV~' already exists, use it instead of checking it out again."
+If `F.~REV~' already exists, use it instead of checking it out again.
+
+If this command needs to split the current window, it by default obeys
+the user options `split-height-threshold' and `split-width-threshold',
+when it decides whether to split the window horizontally or vertically."
   (interactive
    (with-current-buffer (or (buffer-base-buffer) (current-buffer))
      (vc-ensure-vc-buffer)
diff --git a/lisp/view.el b/lisp/view.el
index dc157d8996a..8a86fcc0070 100644
--- a/lisp/view.el
+++ b/lisp/view.el
@@ -226,7 +226,11 @@ are defined for moving around in the buffer.
 Space scrolls forward, Delete scrolls backward.
 For a list of all View commands, type H or h while viewing.
 
-This command runs the normal hook `view-mode-hook'."
+This command runs the normal hook `view-mode-hook'.
+
+If this command needs to split the current window, it by default obeys
+the user options `split-height-threshold' and `split-width-threshold',
+when it decides whether to split the window horizontally or vertically."
   (interactive "fIn other window view file: ")
   (unless (file-exists-p file) (error "%s does not exist" file))
   (let ((had-a-buf (get-file-buffer file))
@@ -306,7 +310,11 @@ this argument instead of explicitly setting `view-exit-action'.
 
 This function does not enable View mode if the buffer's major mode
 has a `special' mode-class, because such modes usually have their
-own View-like bindings."
+own View-like bindings.
+
+If this command needs to split the current window, it by default obeys
+the user options `split-height-threshold' and `split-width-threshold',
+when it decides whether to split the window horizontally or vertically."
   (interactive "bIn other window view buffer:\nP")
   (let ((pop-up-windows t))
     (pop-to-buffer buffer t))
diff --git a/lisp/window.el b/lisp/window.el
index 5debf6ef119..0145cf98eca 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -9221,7 +9221,10 @@ Optional second argument NORECORD non-nil means do not put this
 buffer at the front of the list of recently selected ones.
 
 This uses the function `display-buffer' as a subroutine; see its
-documentation for additional customization information."
+documentation for additional customization information.
+If this command needs to split the current window, it by default obeys
+the user options `split-height-threshold' and `split-width-threshold',
+when it decides whether to split the window horizontally or vertically."
   (interactive
    (list (read-buffer-to-switch "Switch to buffer in other window: ")))
   (let ((pop-up-windows t))