Eglot: Demote errors to warnings in eglot-ensure

Github-reference: https://github.com/joaotavora/eglot/discussions/1318

* doc/misc/eglot.texi (Quick Start): Reword.
(Starting Eglot): Reword.

* lisp/progmodes/eglot.el (eglot-ensure): Demote errors to warnings.

2 files changed, 33 insertions, 11 deletions

diff --git a/doc/misc/eglot.texi b/doc/misc/eglot.texi
index 9ffea80b641..2d9b2a2b60e 100644
--- a/doc/misc/eglot.texi
+++ b/doc/misc/eglot.texi
@@ -139,16 +139,19 @@ To start using Eglot for a project, type @kbd{M-x eglot @key{RET}} in
 a buffer visiting any file that belongs to the project.  This starts
 the language server configured for the programming language of that
 buffer, and causes Eglot to start managing all the files of the
-project which use the same programming language.  The notion of a
-``project'' used by Eglot is the same Emacs uses (@pxref{Projects,,,
-emacs, GNU Emacs Manual}): in the simplest case, the ``project'' is
-the single file you are editing, but it can also be all the files in a
-single directory or a directory tree under some version control
-system, such as Git.
+project which use the same programming language.  This includes files
+of a given project that are already visited at the time the
+@code{eglot} command is invoked as well as files visited after this
+invocation.
 
-Alternatively, you can start Eglot automatically from the major-mode
-hook of the mode used for the programming language; see @ref{Starting
-Eglot}.
+The notion of a ``project'' used by Eglot is the same Emacs uses
+(@pxref{Projects,,, emacs, GNU Emacs Manual}): in the simplest case,
+the ``project'' is the single file you are editing, but it can also be
+all the files in a single directory or a directory tree under some
+version control system, such as Git.
+
+There are alternate ways of starting Eglot; see @ref{Starting Eglot}
+for details.
 
 @item
 Use Eglot.
@@ -344,6 +347,12 @@ starting an Eglot session is non-interactive, so it should be used
 only when you are confident that Eglot can be started reliably for any
 file which may be visited with the major-mode in question.
 
+Note that it's often difficult to establish this confidence fully, so
+it may be wise to use the interactive command @code{eglot} instead.
+You only need to invoke it once per project, as all other files
+visited within the same project will automatically be managed with no
+further user intervention needed.
+
 When Eglot connects to a language server for the first time in an
 Emacs session, it runs the hook @code{eglot-connect-hook}
 (@pxref{Eglot Variables}).
diff --git a/lisp/progmodes/eglot.el b/lisp/progmodes/eglot.el
index eba66503bf7..816f6952d2e 100644
--- a/lisp/progmodes/eglot.el
+++ b/lisp/progmodes/eglot.el
@@ -1366,7 +1366,18 @@ INTERACTIVE is t if called interactively."
 
 ;;;###autoload
 (defun eglot-ensure ()
-  "Start Eglot session for current buffer if there isn't one."
+  "Start Eglot session for current buffer if there isn't one.
+
+Only use this function (in major mode hooks, etc) if you are
+confident that Eglot can be started safely and efficiently for
+*every* buffer visited where these hooks may execute.
+
+Since it is difficult to establish this confidence fully, it's
+often wise to use the interactive command `eglot' instead.  This
+command only needs to be invoked once per project, as all other
+files of a given major mode visited within the same project will
+automatically become managed with no further user intervention
+needed."
   (let ((buffer (current-buffer)))
     (cl-labels
         ((maybe-connect
@@ -1374,7 +1385,9 @@ INTERACTIVE is t if called interactively."
            (eglot--when-live-buffer buffer
              (remove-hook 'post-command-hook #'maybe-connect t)
              (unless eglot--managed-mode
-               (apply #'eglot--connect (eglot--guess-contact))))))
+               (condition-case-unless-debug oops
+                   (apply #'eglot--connect (eglot--guess-contact))
+                 (error (eglot--warn (error-message-string oops))))))))
       (when buffer-file-name
         (add-hook 'post-command-hook #'maybe-connect 'append t)))))