From: João Távora <joaotavora@gmail.com>
Date: Thu, 10 Nov 2022 21:06:33 +0000 (+0000)
Subject: Improve Eglot's docstrings and manual
X-Git-Tag: emacs-29.0.90~1616^2~206
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=c3b64985aa6f61886a24974836635284c86478ef;p=emacs.git

Improve Eglot's docstrings and manual

The examples in the manual can now be copy-pasted to user's init
files as-is.

* doc/misc/eglot.texi (Setting Up LSP Servers): Use
`with-eval-after-load'.  Add eglot-alternatives example.
(Customizing Eglot): Use 'require and fix  a typo.

* lisp/progmodes/eglot.el (eglot-server-programs): Mention
eglot-alternatives in eglot-server-program's docstring.
---

diff --git a/doc/misc/eglot.texi b/doc/misc/eglot.texi
index 8d184976cde..04bdcc61614 100644
--- a/doc/misc/eglot.texi
+++ b/doc/misc/eglot.texi
@@ -264,8 +264,9 @@ Emacs major-mode @code{foo-mode}, you can add it to the alist like
 this:
 
 @lisp
-(add-to-list 'eglot-server-programs
-             '(foo-mode . ("fools" "--stdio")))
+(with-eval-after-load 'eglot
+  (add-to-list 'eglot-server-programs
+               '(foo-mode . ("fools" "--stdio"))))
 @end lisp
 
 This will invoke the program @command{fools} with the command-line
@@ -277,6 +278,24 @@ mentioned by the @code{exec-path} variable (@pxref{Subprocess
 Creation,,, elisp, GNU Emacs Lisp Reference Manual}), for Eglot to be
 able to find it.
 
+Sometimes, multiple servers are acceptable alternatives for handling a
+given major-mode.  In those cases, you may combine the helper function
+@code{eglot-alternatives} with the funcional form of
+@code{eglot-server-programs}.
+
+@lisp
+(with-eval-after-load 'eglot
+  (add-to-list 'eglot-server-programs
+               `(foo-mode . ,(eglot-alternatives
+                               '(("fools" "--stdio")
+                                 ("phewls" "--fast"))))))
+@end lisp
+
+If you have @command{fools} and @command{phewls} installed, the
+function produced by @code{eglot-alternatives} will prompt for the
+server to use in @code{foo-mode} buffers.  Else it will use whichever
+is available.
+
 @node Starting Eglot
 @section Starting Eglot
 @cindex starting Eglot
@@ -1046,8 +1065,10 @@ Eglot via Elisp to adapt to it, by defining a suitable
 Here's an example:
 
 @lisp
+(require 'eglot)
+
 (add-to-list 'eglot-server-programs
-             '((c++ mode c-mode) . (eglot-cquery "cquery")))
+             '((c++-mode c-mode) . (eglot-cquery "cquery")))
 
 (defclass eglot-cquery (eglot-lsp-server) ()
   :documentation "A custom class for cquery's C/C++ langserver.")
diff --git a/lisp/progmodes/eglot.el b/lisp/progmodes/eglot.el
index 7fa4bd380ca..1b1302d6897 100644
--- a/lisp/progmodes/eglot.el
+++ b/lisp/progmodes/eglot.el
@@ -298,7 +298,10 @@ CONTACT can be:
   the call is interactive, the function can ask the user for
   hints on finding the required programs, etc.  Otherwise, it
   should not ask the user for any input, and return nil or signal
-  an error if it can't produce a valid CONTACT.")
+  an error if it can't produce a valid CONTACT.  The helper
+  function `eglot-alternatives' (which see) can be used to
+  produce a function that offers more than one server for a given
+  MAJOR-MODE.")
 
 (defface eglot-highlight-symbol-face
   '((t (:inherit bold)))