master fb09079ced2 07/12: Merge from origin/emacs-31

branch: master
commit fb09079ced2da9faccc880d699c0ab9c9f11b4bb
Merge: d3b3007f529 f6e3b4232f7
Author: Eli Zaretskii <[email protected]>
Commit: Eli Zaretskii <[email protected]>

    Merge from origin/emacs-31
    
    f6e3b4232f7 ; Fix docs for browse-url-transform-alist.
    71df1ea6d07 Fix Fns_block_system_sleep to respect activity_id lifetim...
    769bd892810 Remove assertion in erc-speedbar--dframe-controlled
    2dca4a88544 ; Fix recently-installed documentation changes
    6f71867f27c ; Clarify issues with frames and windows in Elisp manual
    
    # Conflicts:
    #       etc/NEWS
---
 doc/lispref/frames.texi                       | 53 ++++++++++++----------
 doc/lispref/windows.texi                      | 63 +++++++++++++++------------
 lisp/erc/erc-speedbar.el                      | 10 ++---
 lisp/net/browse-url.el                        |  6 +--
 src/nsfns.m                                   |  8 ++--
 test/lisp/erc/erc-scenarios-status-sidebar.el |  7 ++-
 6 files changed, 78 insertions(+), 69 deletions(-)

diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 95bfb520605..242b4c8a455 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -1318,12 +1318,15 @@ are specified as with the corresponding frame parameters @code{width},
 @defun set-frame-size-and-position-pixelwise frame width height x y &optional gravity
 This function sets the new size and position of a frame, similarly to
 @code{set-frame-size-and-position}, but in pixel units.  The optional
-argument @var{gravity} specified the new @dfn{gravity} of a frame and
-must be a value between 0 and 10; it defaults to 1.  The gravity
-determines how a window or its contents adjust when resized or
-positioned.  The interpretation is specific to each window-system; for
-example, GTK uses window gravity to define which point of the window
-remains fixed during resizing.
+argument @var{gravity} specifies the new @dfn{gravity} of @var{frame}
+and must be a value between 0 and 10; it defaults to 1.  Gravity is
+window-system dependent and conceptually determines which corner of a
+frame retains its position relative to that of its parent frame when the
+size of that frame or its parent changes.  (Top-level frames have no
+parent frame, the window-system root window will be considered their
+parent in this regard.)  The value 1 specifies NorthWest gravity and
+means that the top-left corner of the frame should keep its relative
+position.  Many window managers seem to ignore gravity.
 @end defun
 
 @cindex tracking frame size changes
@@ -2974,16 +2977,16 @@ A frame cannot be safely deleted in the following cases:
 @itemize @bullet
 @item
 It is the only visible or iconified frame (@pxref{Visibility of
-Frames}).
+Frames}) on its terminal.
 
 @item
 It hosts the active minibuffer window and minibuffer windows do not
 follow the selected frame (@pxref{Basic Minibuffer,,, emacs}).
 
 @item
-All other visible or iconified frames are either child frames
-(@pxref{Child Frames}) or have a non-@code{nil} @code{delete-before}
-parameter.
+All other visible or iconified frames on the same terminal are either
+child frames (@pxref{Child Frames}) or have a non-@code{nil}
+@code{delete-before} parameter.
 
 @item
 The frame or one of its descendants hosts the minibuffer window of a
@@ -3970,12 +3973,14 @@ parameter indicates the number of pixels where the frame @dfn{snaps} at
 the respective edge or corner of its parent frame.  On a text terminal,
 the outer border can used for resizing.
 
-  There are two ways to drag an entire child frame with the mouse: The
+  There are three ways to drag an entire child frame with the mouse: The
 @code{drag-with-mode-line} parameter, if non-@code{nil}, enables
-dragging a frame without minibuffer window (@pxref{Minibuffer
-Windows}) via the mode line area of its bottommost window.  The
-@code{drag-with-header-line} parameter, if non-@code{nil}, enables
-dragging the frame via the header line area of its topmost window.
+dragging a frame without minibuffer window (@pxref{Minibuffer Windows})
+via the mode line area of its bottommost window.  The
+@code{drag-with-header-line} and the @code{drag-with-tab-line}
+parameters, if non-@code{nil}, enable dragging the frame via the header
+or tab line area of its topmost window (dragging with the tab line is
+possible only when there's no header line above the tab line).
 
   In order to give a child frame a draggable header or mode line, the
 window parameters @code{mode-line-format} and @code{header-line-format}
@@ -3990,15 +3995,15 @@ prevent such a situation, it is advisable to set the frame's
 @code{top-visible} or @code{bottom-visible} parameter (@pxref{Mouse
 Dragging Parameters}).
 
-  Set the @code{top-visible} parameter of a child frame to a number
-when you intend to allow the user dragging that frame by its header
-line.  Setting @code{top-visible} to a number inhibits dragging the
-top edge of the child frame above the top edge of its parent.  Set the
-@code{bottom-visible} parameter to a number when you intend to drag
-that frame via its mode line; this inhibits dragging the bottom edge
-of the child frame beneath the bottom edge of its parent.  In either
-case, that number also specifies width and height (in pixels) of the
-area of the child frame that remains visible during dragging.
+  Set the @code{top-visible} parameter of a child frame to a number when
+you intend to allow dragging that frame by its header or tab
+line.  Setting @code{top-visible} to a number inhibits dragging the top
+edge of the child frame above the top edge of its parent.  Set the
+@code{bottom-visible} parameter to a number when you intend to drag that
+frame via its mode line; this inhibits dragging the bottom edge of the
+child frame beneath the bottom edge of its parent.  In either case, that
+number also specifies width and height (in pixels) of the area of the
+child frame that remains visible during dragging.
 
   When a child frame is used for displaying a buffer via
 @code{display-buffer-in-child-frame} (@pxref{Buffer Display Action
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 84345d5fb52..a71bc69846b 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -428,8 +428,8 @@ appears right below @var{window}.
 @cindex window in direction
 @defun window-in-direction direction &optional window ignore sign wrap minibuf
 This function returns the nearest live window in direction
-@var{direction} as seen from the position of @code{window-point} in
-window @var{window}.  The argument @var{direction} must be one of
+@var{direction} as seen from the position of @var{window}'s point
+(@pxref{Window Point}).  The argument @var{direction} must be one of
 @code{above}, @code{below}, @code{left} or @code{right}.  The optional
 argument @var{window} must denote a live window and defaults to the
 selected one.
@@ -736,7 +736,7 @@ rounded internally.  This is done in a way such that, if the window is a
 parent window, the sum of the total heights of all its child windows
 internally equals the total height of their parent.  This means that
 although two windows have the same pixel height, their internal total
-heights may differ by one line.  This means also, that if window is
+heights may differ by one line.  This means also, that if a window is
 vertically combined and has a next sibling, the topmost row of that
 sibling can be calculated as the sum of this window's topmost row and
 total height (@pxref{Coordinates and Windows})
@@ -745,7 +745,7 @@ total height (@pxref{Coordinates and Windows})
 returns the smallest integer larger than @var{window}'s pixel height
 divided by the canonical character height of its frame; if it is
 @code{floor}, it returns the largest integer smaller than said value;
-with any other @var{round} it returns the internal value of
+with any other value of @var{round} it returns the internal value of
 @var{windows}'s total height.
 @end defun
 
@@ -1632,15 +1632,18 @@ selected one.  Possible choices are
 
 @itemize
 @item @code{mru}
-(the default) choose the most recently used window on that frame.
+(the default) means to choose the most recently used window
+(@pxref{Cyclic Window Ordering}) other than the selected one on that
+frame.
 
 @item @code{pos}
-choose the window comprising the frame coordinates of point of the
-previously selected window on that frame.
+means to choose the window comprising the position of
+@code{window-point} (@pxref{Window Point}) of the previously selected
+window on that frame.
 
 @item @code{nil}
-choose the first window (the window returned by
-@code{frame-first-window}) on that frame.
+means to choose the first window (the window returned by
+@code{frame-first-window}, @pxref{Windows and Frames}) on that frame.
 @end itemize
 
 A window for which @code{window-no-other-p} (@pxref{Cyclic Window
@@ -2299,9 +2302,10 @@ windows by deleting them first and resurrecting them
 window gets lost and no window is added or duplicated.  Where possible,
 these commands try to preserve the relative size of windows as well as
 all other non-geometric properties including parameters.  These commands
-will signal an error if windows chosen to transpose or rotate are atomic
-or of fixed size.  The option @code{transpose-dedicated-windows} below
-decides whether dedicated windows may be transposed or rotated.
+will signal an error if windows about to change their locations are
+atomic or of fixed size.  The option @code{transpose-dedicated-windows}
+described below decides whether dedicated windows may change their
+locations.
 
    The @var{window} argument of all functions described in this section
 must specify a valid parent window (@pxref{Windows and Frames}).  If it
@@ -2313,8 +2317,8 @@ their frame's main window and the @var{window} argument is @code{nil}
 unless stated otherwise.
 
 @cindex rotate window layout
-   The first two commands rotate an entire window layout either
-clockwise or counterclockwise.
+   The first two commands @dfn{rotate a window layout} either clockwise
+or counterclockwise.
 
 @deffn Command window-layout-rotate-clockwise &optional window
 This command rotates the window layout clockwise by 90 degrees.  Imagine
@@ -2355,7 +2359,7 @@ layout in the opposite direction as demonstrated in the example below.
 @end deffn
 
 @cindex flip window layout
-The next two commands @sc{flip} the window layout---rotate it around an
+The next two commands @dfn{flip the window layout}---rotate it around an
 imaginary horizontal or vertical axis.  If the number of windows to be
 flipped is odd, the window in the middle remains in its original place.
 
@@ -2395,7 +2399,7 @@ become the windows on the left, and vice-versa.
 @end smallexample
 @end deffn
 
-The next command can be used for @sc{transposing} windows---changing
+The next command can be used to @dfn{transpose windows}---changing
 horizontal splits to vertical ones and vice-versa.
 @cindex transposing windows
 
@@ -2418,7 +2422,7 @@ becomes a vertical split and vice versa.
 @end deffn
 
 @cindex rotating windows
-The final two commands can be used to @dfn{rotate} windows within the
+The final two commands can be used to @dfn{rotate windows} within the
 existing layout.  They are like the commands that rotate the layout but
 leave the underlying structure of the layout unchanged.  What actually
 changes are the positions of windows within the existing layout.  This
@@ -2428,7 +2432,7 @@ non-@code{nil}) it in the cyclic ordering of windows (@pxref{Cyclic
 Window Ordering}) on @var{window}'s frame.
 
 @deffn Command rotate-windows &optional window reverse
-This command rotates @var{window}'c child windows in cyclic ordering.
+This command rotates @var{window}'s child windows in cyclic ordering.
 The optional argument @var{reverse} means to rotate windows backwards,
 in reverse cyclic order.
 
@@ -2477,9 +2481,10 @@ The last two commands are subject to the following option.
 
 @defopt rotate-windows-change-selected
 If this is @code{nil}, the selected window will remain unaffected by
-@code{rotate-windows} and @code{rotate-windows-back}.  Otherwise, the
-selected window will change to the window that appears at the location
-of the window selected before any of these commands were invoked.
+@code{rotate-windows} and @code{rotate-windows-back}.  If this is
+@code{t} (the default), the selected window will change to the window
+that appears at the location of the window selected before any of these
+commands were invoked.
 @end defopt
 
 
@@ -2973,7 +2978,9 @@ buffer.
 @defopt switch-to-buffer-obey-display-actions
 If this variable is non-@code{nil}, @code{switch-to-buffer} respects
 display actions specified by @code{display-buffer-overriding-action},
-@code{display-buffer-alist} and other display related variables.
+@code{display-buffer-alist} (@pxref{Buffer Display Action Functions})
+and other buffer display related variables (@pxref{Buffer Display Action
+Alists}).
 @end defopt
 
 The next two commands are similar to @code{switch-to-buffer}, except for
@@ -3536,9 +3543,9 @@ must also provide an appropriate @code{window-height} entry.
 This function tries to display @var{buffer} in a window at the bottom
 of the selected frame.
 
-This either tries to split the window at the bottom of the frame or
-the frame's root window, or to reuse an existing window at the bottom
-of the selected frame.
+This either tries to split the window at the bottom of the frame or the
+frame's main window, or to reuse an existing window at the bottom of the
+selected frame.
 @end defun
 
 @defun display-buffer-pop-up-frame buffer alist
@@ -3771,8 +3778,8 @@ well.  @code{display-buffer-in-previous-window} consults it when
 searching for a window that previously displayed the buffer on another
 frame.
 
-Action function @code{display-buffer-in-tab} searches the tabs of the
-frame(s) identified by this entry, and also interprets the value
+The action function @code{display-buffer-in-tab} searches the tabs of
+the frame(s) identified by this entry, and also interprets the value
 @code{nil} differently.
 
 @vindex inhibit-switch-frame@r{, a buffer display action alist entry}
@@ -7640,7 +7647,7 @@ affected.
 @vindex min-margins@r{, a window parameter}
 The value of this parameter is a cons cell whose @sc{car} and
 @sc{cdr}, if non-@code{nil}, specify the minimum values (in columns)
-for the left and right margin of this window (@pxref{Display Margins}.
+for the left and right margin of this window (@pxref{Display Margins}).
 When present, Emacs will use these values instead of the actual margin
 widths for determining whether a window can be split or shrunk
 horizontally.
diff --git a/lisp/erc/erc-speedbar.el b/lisp/erc/erc-speedbar.el
index 7ce52db25b7..20ae8d4402c 100644
--- a/lisp/erc/erc-speedbar.el
+++ b/lisp/erc/erc-speedbar.el
@@ -540,7 +540,8 @@ associated with an ERC session."
       (with-selected-frame speedbar-frame
         (erc-speedbar--emulate-sidebar-set-window-preserve-size)
         (erc-speedbar-toggle-nicknames-window-lock -1))
-      (cl-assert (null (cdr (erc-speedbar--get-timers))))
+      ;; The following assumes any idle timers for `dframe-timer-fn'
+      ;; from previous module sessions have been canceled.
       (with-current-buffer speedbar-buffer
         (setq speedbar-update-flag t)
         (speedbar-set-mode-line-format)))))
@@ -620,11 +621,6 @@ For controlling whether the speedbar window is selectable with
        (unless (eq erc--module-toggle-prefix-arg most-negative-fixnum)
          (dframe-close-frame))))))
 
-(defun erc-speedbar--get-timers ()
-  (cl-remove #'dframe-timer-fn timer-idle-list
-             :key #'timer--function
-             :test-not #'eq))
-
 (defun erc-speedbar--dframe-controlled (arg)
   (when speedbar-buffer
     (cl-assert (eq speedbar-buffer (current-buffer))))
@@ -635,7 +631,7 @@ For controlling whether the speedbar window is selectable with
           erc-speedbar--hidden-speedbar-frame nil)
     (speedbar-frame-mode arg) ; -1
     ;; As of Emacs 29, `dframe-set-timer' can't remove `dframe-timer'.
-    (cl-assert (= 1 (length (erc-speedbar--get-timers))) t)
+    ;; However, this may have been addressed in Emacs 31 by bug#81561.
     (cancel-function-timers #'dframe-timer-fn)
     ;; `dframe-close-frame' kills the buffer but no function in
     ;; erc-speedbar.el resets this to nil.
diff --git a/lisp/net/browse-url.el b/lisp/net/browse-url.el
index 6700211cda3..b6513d18626 100644
--- a/lisp/net/browse-url.el
+++ b/lisp/net/browse-url.el
@@ -270,11 +270,7 @@ be used instead."
   "Alist of transformations to apply to URLs before loading it.
 Each element has the form (ORIG . REPLACEMENT), where ORIG is a regular
 expression and REPLACEMENT is the replacement text.  Every element will
-be tested in turn, allowing more than one transformation to be made.
-
-Note that ORIG and REPLACEMENT are passed as arguments to
-`string-match', so you can, for example, use match groups in ORIG and
-backreferences in REPLACEMENT."
+be tested in turn, allowing more than one transformation to be made."
   :type '(choice
           (const :tag "None" nil)
           (alist
diff --git a/src/nsfns.m b/src/nsfns.m
index 3ee6315d963..f10297ed8d7 100644
--- a/src/nsfns.m
+++ b/src/nsfns.m
@@ -3940,8 +3940,6 @@ or nil if the block fails.  */)
     activity_id = [[NSProcessInfo processInfo]
 			     beginActivityWithOptions: activity_options
 					       reason: reason];
-  unblock_input ();
-
   if (!sleep_block_map)
     sleep_block_map = [[NSMutableDictionary alloc] initWithCapacity: 25];
 
@@ -3949,10 +3947,14 @@ or nil if the block fails.  */)
     {
       [sleep_block_map setObject: activity_id
 			  forKey: [NSNumber numberWithInt: ++sleep_block_id]];
+      unblock_input ();
       return make_fixnum (sleep_block_id);
     }
   else
-    return Qnil;
+    {
+      unblock_input ();
+      return Qnil;
+    }
 }
 
 DEFUN ("ns-unblock-system-sleep",
diff --git a/test/lisp/erc/erc-scenarios-status-sidebar.el b/test/lisp/erc/erc-scenarios-status-sidebar.el
index ede387ac451..44ef3a8e029 100644
--- a/test/lisp/erc/erc-scenarios-status-sidebar.el
+++ b/test/lisp/erc/erc-scenarios-status-sidebar.el
@@ -93,7 +93,7 @@
 ;; terminal, and we lack a fixture for that.  Please try running this
 ;; test interactively with both graphical Emacs and non.
 (declare-function erc-nickbar-mode "erc-speedbar" (arg))
-(declare-function erc-speedbar--get-timers "erc-speedbar" nil)
+(declare-function dframe-timer-fn "dframe" ())
 (declare-function speedbar-timer-fn "speedbar" nil)
 (defvar erc-nickbar-mode)
 (defvar speedbar-buffer)
@@ -171,6 +171,9 @@
         (should-not erc-nickbar-mode)
         (should-not (cdr (frame-list)))))
 
-    (should-not (erc-speedbar--get-timers))))
+    ;; No stray dframe timers.
+    (should-not (any (lambda (timer)
+                       (eq #'dframe-timer-fn (timer--function timer)))
+                     timer-idle-list))))
 
 ;;; erc-scenarios-status-sidebar.el ends here