Merge from origin/emacs-29

ea87c54f359 ; * lisp/subr.el (setq-local): Add missing period (bug#62...
90362f87d58 ; Correct last commit, downcase node reference
38067f05b92 Enhance section about troubleshooting in Eglot manual.
6f82596b490 Fix Eglot's snippet insertion to follow the manual
c54bda15e35 Reset abbrevs-changed after saving abbrevs (bug#62208)
e8cee15f780 ; Fix markup in previous change
e4a7d0cd6ea Document `keymap-unset' in lispref
bb3e0ded9eb Don't add a key binding when REMOVE is non-nil
a4a9ffdd80a Fix the documentation of various aspects of adding Xref h...
a2222b9a9bf ; Minor wording fix in ELisp reference manual
5cf1de683b2 Fix python-fill-paragraph problems on filling strings (bu...
7385c991dff Also exempt eglot-inlay-hints-mode from desktop.el's fumb...
1961bdb52ed ; Add WebDAV entry to index in Tramp manual
dfb36d36230 Refer to EWW instead of w3 and w3m
9d3fdf7e0d4 Fix Eglot's command generation for code actions

# Conflicts:
#	etc/NEWS

3 files changed, 82 insertions, 32 deletions

diff --git a/doc/misc/eglot.texi b/doc/misc/eglot.texi
index 85f83ee4b26..5ebc055ecf7 100644
--- a/doc/misc/eglot.texi
+++ b/doc/misc/eglot.texi
@@ -1292,53 +1292,103 @@ pop up special buffers that can be used to inspect the communications
 between the Eglot and language server.  In many cases, this will
 indicate the problems or at least provide a hint.
 
+@cindex performance
 A common and easy-to-fix cause of performance problems is the length
-of these two buffers.  If Eglot is operating correctly but slowly,
-customize the variable @code{eglot-events-buffer-size} (@pxref{Eglot
-Variables}) to limit logging, and thus speed things up.
-
-If you need to report an Eglot bug, please keep in mind that, because
-there are so many variables involved, it is generally both very
-@emph{difficult} and @emph{absolutely essential} to reproduce bugs
-exactly as they happened to you, the user.  Therefore, every bug
-report should include:
+of the Eglot events buffer because it represent additional work that
+Eglot must do.  After verifying Eglot is operating correctly but
+slowly, try to customize the variable @code{eglot-events-buffer-size}
+(@pxref{Eglot Variables}) to 0.  This will disable any debug logging
+and may speed things up.
+
+In other situations, the cause of poor performance lies in the LSP
+server itself.  Servers use aggressive caching and other techniques to
+improve their performance.  Often, this can be tweaked by changing the
+server configuration (@pxref{Advanced server configuration}).
+
+If you think you have found a bug, we want to hear about it.  Before
+reporting a bug, keep in mind that interaction with LSP servers
+represents a large quantity of unknown variables.  Therefore, it is
+generally both @emph{difficult} and @emph{absolutely essential} that
+the maintainers reproduce bugs exactly as they happened to you, the
+user.
+
+To report an Eglot bug, send e-mail to @email{bug-gnu-emacs@@gnu.org}.
+
+Get acquainted with Emacs's bug reporting guidelines (@pxref{Bugs,,,
+emacs, GNU Emacs Manual}).  Then, follow this checklist specific to
+Eglot bug rerpots.
 
 @enumerate
 @item
-The transcript of events obtained from the buffer popped up by
-@kbd{M-x eglot-events-buffer}.  If the transcript can be narrowed down
-to show the problematic exchange, so much the better.  This is
-invaluable for the investigation and reproduction of the problem.
+Include the transcript of JSONRPC events obtained from the buffer
+popped up by @kbd{M-x eglot-events-buffer}.  You may narrow down the
+transcript if you are sure of where the problematic exchange is, but
+it's safer to include the whole transcript, either attached or inline.
 
 @item
 If Emacs signaled an error (an error message was seen or heard), make
-sure to repeat the process after toggling @code{debug-on-error} on
-(via @kbd{M-x toggle-debug-on-error}).  This normally produces a
-backtrace of the error that should also be attached to the bug report.
+sure to repeat the process after turning on @code{debug-on-error} via
+@kbd{M-x toggle-debug-on-error}.  This normally produces a backtrace
+of the error that should also be attached to the bug report.
+
+@item
+Include a description of how the maintainer should obtain, install,
+and configure the language server you used.  Maintainers usually have
+access to GNU/Linux systems, though not necessarily the distribution
+that you may be using.  If possible, try to replicate the problem with
+the C/C@t{++} or Python servers, as these are very easy to install.
 
 @item
-An explanation of how to obtain, install, and configure the language
-server you used.  If possible, try to replicate the problem with the
-C/C@t{++} or Python servers, as these are very easy to install.
+Describe how to setup a @emph{minimal} project directory where Eglot
+should be started for the problem to happen.  Describe each file's
+name and its contents.  Alternatively, you can supply the address of a
+public Git repository.
 
 @item
-A description of how to setup the @emph{minimal} project (one or two
-files and their contents) where the problem happens.
+Include versions of the software used.  The Emacs version can be
+obtained with @kbd{M-x emacs-version}.
+
+It's also essential to include the version of ELPA packages that are
+explicitly or implicitly loaded.  The optional but popular Company or
+Markdown packages are distributed as GNU ELPA packages, not to mention
+Eglot itself in some situations.  Some major modes (Go, Rust, etc.)
+are provided by ELPA packages.  It's sometimes easy to miss these,
+since they are usually implicitly loaded when visiting a file in that
+language.
+
+ELPA packages usually live in @code{~/.emacs.d/elpa} (or what is in
+@code{package-user-dir}).  Please show the listing of files in that
+directory as well.
 
 @item
-A recipe to replicate the problem with @emph{a clean Emacs run}.  This
-means @kbd{emacs -Q} invocation or a very minimal (no more that 10
-lines) @file{.emacs} initialization file.  @code{eglot-ensure} and
-@code{use-package} calls are generally @emph{not} needed.
+Include a recipe to replicate the problem with @emph{a clean Emacs
+run}.  This means @kbd{emacs -Q -f package-initialize} invocation
+which starts Emacs with no configuration and initializes the ELPA
+packages.  A very minimal (no more that 10 lines) @file{.emacs}
+initialization file is also acceptable and good means to describe
+changes to variables.
+
+There is usually no need to include @kbd{require} statements in the
+recipe, as Eglot's functionality uses autoloads.
+
+Likewise, there is rarely the need to use things like
+@code{use-package} or @code{eglot-ensure}.  This just makes the recipe
+harder to follow.  Prefer setting variables with @code{setq} and
+adding to hooks with @code{add-hook}.  Prefer starting Eglot with
+@code{M-x eglot}.
 
 @item
-Make sure to double check all the above elements and re-run the
-recipe to see that the problem is reproducible.
+Make sure to double check all the above elements and re-run the recipe
+to see that the problem is reproducible.  Following the recipe should
+produce event transcript and error backtraces that are exactly the
+same or very similar to the ones you included.  If the problem only
+happens sometimes, include this information in your bug report.
 @end enumerate
 
 Please keep in mind that some problems reported against Eglot may
 actually be bugs in the language server or the Emacs feature/package
-that used Eglot to communicate with the language server.
+that used Eglot to communicate with the language server.  Eglot is, in
+many cases, just a frontend to that functionality.
 
 @node GNU Free Documentation License
 @appendix GNU Free Documentation License
diff --git a/doc/misc/idlwave.texi b/doc/misc/idlwave.texi
index 3ec07fb4a50..10fc4c85c7b 100644
--- a/doc/misc/idlwave.texi
+++ b/doc/misc/idlwave.texi
@@ -1372,10 +1372,9 @@ among, with differing advantages and disadvantages.  The variable
 to (as long as @code{idlwave-help-use-assistant} is not set).  This
 function is used to set the variable @code{browse-url-browser-function}
 locally for IDLWAVE help only.  Customize the latter variable to see
-what choices of browsers your system offers.  Certain browsers like
-@code{w3} (bundled with many versions of Emacs) and @code{w3m}
-(@uref{http://emacs-w3m.namazu.org/}) are run within Emacs, and use
-Emacs buffers to display the HTML help.  This can be convenient,
+what choices of browsers your system offers.  Certain browsers like EWW
+(@pxref{Top, EWW,, eww, The Emacs Web Wowser Manual}) are run within Emacs,
+and use Emacs buffers to display the HTML help.  This can be convenient,
 especially on small displays, and images can even be displayed in-line
 on newer Emacs versions.  However, better formatting results are often
 achieved with external browsers, like Mozilla.  IDLWAVE assumes any
diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi
index 3b5ba3b1390..6f14fc875f4 100644
--- a/doc/misc/tramp.texi
+++ b/doc/misc/tramp.texi
@@ -1247,6 +1247,7 @@ syntax requires a leading volume (share) name, for example:
 
 @item @option{dav}
 @item @option{davs}
+@cindex WebDAV
 @cindex method @option{dav}
 @cindex method @option{davs}
 @cindex @option{dav} method