Improve scroll-bar-mode/default-frame-alist interaction docs

* lisp/scroll-bar.el (scroll-bar-mode): Mention
default-frame-alist (bug#54237).

* src/frame.c (syms_of_frame): Clarify further that setting this
variable may have unintended consequences.

2 files changed, 19 insertions, 6 deletions

diff --git a/lisp/scroll-bar.el b/lisp/scroll-bar.el
index 3d12723c025..5786a21e88e 100644
--- a/lisp/scroll-bar.el
+++ b/lisp/scroll-bar.el
@@ -132,8 +132,11 @@ Setting the variable with a customization buffer also takes effect."
 (define-minor-mode scroll-bar-mode
   "Toggle vertical scroll bars on all frames (Scroll Bar mode).
 
-This command applies to all frames that exist and frames to be
-created in the future."
+This command applies to all frames that exist, as well as new
+frames to be created in the future.  This is done by altering the
+frame parameters, so if you (re-)set `default-frame-alist' after
+toggling the scroll bars on or off with this command, the scroll
+bars may reappear on new frames."
   :variable ((get-scroll-bar-mode)
              . (lambda (v) (set-scroll-bar-mode
                             (if v (or previous-scroll-bar-mode
diff --git a/src/frame.c b/src/frame.c
index b7ff7fd1fc4..b3990ae2aa5 100644
--- a/src/frame.c
+++ b/src/frame.c
@@ -6233,14 +6233,24 @@ You can also use a floating number between 0.0 and 1.0.  */);
                doc: /* Alist of default values for frame creation.
 These may be set in your init file, like this:
   (setq default-frame-alist \\='((width . 80) (height . 55) (menu-bar-lines . 1)))
+
 These override values given in window system configuration data,
- including X Windows' defaults database.
+including X Windows' defaults database.
+
+Note that many display-related modes (like `scroll-bar-mode' or
+`menu-bar-mode') alter `default-frame-alist', so if you set this
+variable directly, you may be overriding other settings
+unintentionally.  Instead it's often better to use
+`modify-all-frames-parameters' or push new elements to the front of
+this alist.
+
 For values specific to the first Emacs frame, see `initial-frame-alist'.
+
 For window-system specific values, see `window-system-default-frame-alist'.
+
 For values specific to the separate minibuffer frame, see
- `minibuffer-frame-alist'.
-The `menu-bar-lines' element of the list controls whether new frames
- have menu bars; `menu-bar-mode' works by altering this element.
+`minibuffer-frame-alist'.
+
 Setting this variable does not affect existing frames, only new ones.  */);
   Vdefault_frame_alist = Qnil;