master c3b64985aa: Improve Eglot's docstrings and manual

[João Távora]

branch: master
commit c3b64985aa6f61886a24974836635284c86478ef
Author: João Távora <joaotavora@gmail.com>
Commit: João Távora <joaotavora@gmail.com>

    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.
---
 doc/misc/eglot.texi     | 27 ++++++++++++++++++++++++---
 lisp/progmodes/eglot.el |  5 ++++-
 2 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/doc/misc/eglot.texi b/doc/misc/eglot.texi
index 8d184976cd..04bdcc6161 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 7fa4bd380c..1b1302d689 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)))