master 18e25c198f 1/2: Improve scroll-bar-mode/default-frame-alist interaction docs

[Lars Ingebrigtsen]

branch: master
commit 18e25c198f39895438c05ef293789358232dfd76
Author: Lars Ingebrigtsen <larsi@gnus.org>
Commit: Lars Ingebrigtsen <larsi@gnus.org>

    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.
---
 lisp/scroll-bar.el |  7 +++++--
 src/frame.c        | 18 ++++++++++++++----
 2 files changed, 19 insertions(+), 6 deletions(-)

diff --git a/lisp/scroll-bar.el b/lisp/scroll-bar.el
index 3d12723c02..5786a21e88 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 b7ff7fd1fc..b3990ae2aa 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;