bug#72088: eglot: Segregates language servers in a way that hampers polyglot language servers

[Niels Thykier]

João Távora:
> On Sun, Jul 14, 2024, 10:36 Niels Thykier <niels@thykier.net> wrote:
>
> > I read through
> >
> > https://www.gnu.org/software/emacs/manual/html_node/eglot/Setting-Up-LSP-Servers.html
> > and I do not see anything here that decides how to control whether one
> > or two instances per project will be spawned.
>
> In that section, did you happen to read this sentence?
>
> "In addition, major-mode can be a list of several major modes specified in
> one of the above forms – this means a running instance of the associated
> server is responsible for files of multiple major modes or languages in the
> project. "
>
> If so, how do you comprehend or interpret it? Maybe it could be clarified.
> Regardless, the default value of the eglot-server-programs variable that
> ships with Emacs has several examples that make use of this feature, so it
> may be worth studying those.
>
> João

I missed it entirely.

My recommendations would one or more of the following:

 1 Use a more verbose variant of the `major-mode` placeholder, like
   `(major-mode-or-modes . server)`. This would have prompted me
   to not assume `major-mode` was just a single major-mode.

 2 Provide an example featuring multiple modes in addition the existing
   examples. This example could also show off the `:language-id`
   feature.

 3 Provide a howto guide for adding a new LSP server configuration
   that explicitly featured the distinction between single mode vs.
   multi-mode LSP servers.
   (Note "howto guide" is specifically the "howto guide" from
    https://docs.divio.com/documentation-system/)

For me, either 1+2 would definitely have worked. The third option is a 
question of which kind of audience you want to optimize for. Personally, 
I find it difficult myself to figure out what deserves a howto guide, so 
I can totally understand if you pass on doing one of those.



A bit more on what happened on my end:


I think a key aspect of this problem is that I was trying to quickly 
solve a problem. Namely getting my prototype to work and all I could 
find was reference documentation, which is tailored for solving a 
different type of documentation problem than what I ideally needed 
(Compare problem-oriented vs information-oriented on 
https://docs.divio.com/documentation-system/).
  Since I know the documentation has the "wrong focus" for the thing I 
want to do, I scan much more aggressively for examples and highlighted 
words that looks like definitions and then retrace from there if 
relevant. This is a common issue for many projects including some of my 
own that they only provide one or two types of documentation (with 
reference documentation being the most common type of documentation), 
which has made me adopt this reading style.


The use of `major-mode` in the documentation had me assume that it was 
one major mode at the time which works out of the box with no warnings. 
The moment I saw: "The value of the variable is an alist, whose elements 
are of the form (major-mode . server)", I was like "Got it, one major 
mode + a server definition. Where do I find the definition of `server`? 
Next line talks about the major-mode and I got what is. I need the 
server part, oh I see the highlighted `(programs args)` below, so skip 
to that. Oh, there are examples in the bottom. Ok, so 5x the first 
example that with a bit of replacements" and I had some code that worked 
and I was back to working on my language server. From there it took me 
several months until the server reached maturity enough to provide 
features where this mistake got in the way.


As mentioned, an example that might have worked would have been:

```
;; Polyglot LSP server example. The instance is reused
;; in a given project for all the listed modes.
(with-eval-after-load 'eglot
  (add-to-list 'eglot-server-programs
               '((
                  c-mode
                  (cpp-mode :language-id "c++"))
                  . ("custom-c-lsp" "--stdio"))))
```


In fact, it would have been nice to have this example, because I spent 
30 minutes fighting with the elisp syntax figuring out the syntax. After 
that, I spent 15 minutes trying to figure out why my `eglot-ensure` 
configuration stopped working (as you can probably tell, lisp/elisp is 
not really not my jam).

Hope that helped.

Best regards,
Niels