Merge from origin/emacs-29

3d87d74a23 ; * etc/PROBLEMS: Entry about slow mouse-wheel with GTK3 ...
c6899603b9 ; * doc/lispref/tips.texi (Documentation Tips): Improve (...
bd2c4d825d ; Update admin/make-tarball.txt
f107dc26e3 ; * etc/PROBLEMS: Add an entry about WebKitGTK (bug#66068).

admin/make-tarball.txt

@@ -27,6 +27,13 @@ Steps to take before starting on the first pretest in any release sequence:
     file against the previously released Emacs version to see what has
     changed.
 
+5. If this is an emergency release without a prior pretest, inform the
+   maintainers of the bundled packages which are developed separately
+   to make sure they install adjustments required for an official
+   release.  Currently, these packages include:
+
+    . Tramp
+
 General steps (for each step, check for possible errors):
 
 1.    git pull     # fetch from the repository

doc/lispref/tips.texi

@@ -834,13 +834,15 @@ it substitutes whatever key is currently bound to @code{forward-char}.
 user has moved key bindings.)  @xref{Keys in Documentation}.
 
 @item
-In documentation strings for a major mode, you will want to refer to the
-key bindings of that mode's local map, rather than global ones.
+In documentation strings for a major mode, you will want to refer to
+the key bindings of that mode's local map, rather than global ones.
 Therefore, use the construct @samp{\\<@dots{}>} once in the
 documentation string to specify which key map to use.  Do this before
-the first use of @samp{\\[@dots{}]}.  The text inside the
-@samp{\\<@dots{}>} should be the name of the variable containing the
-local keymap for the major mode.
+the first use of @samp{\\[@dots{}]}, and not in the middle of a
+sentence (since if the map is not loaded, the reference to the map
+will be replaced with a sentence saying the map is not currently
+defined).  The text inside the @samp{\\<@dots{}>} should be the name
+of the variable containing the local keymap for the major mode.
 
 Each use of @samp{\\[@dots{}]} slows the display of the documentation
 string by a tiny amount.  If you use a lot of them, these tiny

etc/PROBLEMS

@@ -178,6 +178,32 @@ The relevant bug report is here:
 A workaround is to set XLIB_SKIP_ARGB_VISUALS=1 in the environment
 before starting Emacs, or run Emacs as root.
 
+** Emacs built with xwidgets aborts when displaying WebKit xwidgets
+
+This happens, for example, when 'M-x xwidget-webkit-browse-url'
+prompts for a URL and you type the URL at the prompt.
+
+The error message might look like this:
+
+  X protocol error: GLXBadWindow on protocol request 151
+  Serial no: 4286
+  Failing resource ID (if any): 0x3c001c5
+  Minor code: 32
+
+This happens because starting from version 2.42.1, the WebKitGTK
+developers discontinued support for off-screen windows, by presuming
+that every window holding a WebView widget is an X server window
+eligible for an OpenGL context.  Emacs requires placing these widgets
+within offscreen windows managed by GTK, for each xwidget might be
+displayed in multiple distinct windows, and its contents must be
+captured and reproduced within all of them if that be the case.
+
+To put this another way, WebKitGTK doesn't support displaying a single
+widget more than once anymore.
+
+A possible workaround is to make sure xwidgets are not shown in more
+than one window.
+
 ** Emacs crashes with SIGTRAP when trying to start a WebKit xwidget.
 
 This could happen if the version of WebKitGTK installed on your system
@@ -2063,6 +2089,16 @@ For such programs to function again, Emacs must be run on an X server
 where the input extension is disabled, or alternatively be configured
 with the "--without-xinput2" option.
 
+*** Scrolling with mouse-wheel lags in GTK3 builds.
+
+We don't know why this happens, but one workaround is to build Emacs
+with a different toolkit.  For example:
+
+  ./configure --without-toolkit-scroll-bars --with-x-toolkit=athena
+
+This produces a build which uses Athena toolkit, and disables toolkit
+scroll bars which could sometimes be slow.
+
 * Runtime problems on character terminals
 
 ** The meta key does not work on xterm.