Re: [SPAM UNSURE] Explain a bit more on how to configure language server in Eglot's manual

[Yuan Fu <casouri@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 2316 bytes --]



> On Mar 5, 2023, at 4:16 PM, João Távora <joaotavora@gmail.com> wrote:
> 
> Yuan, please show the patch to Eglot's manual and let's work from
> there.

I’m not an amazing writer, but here it is.

> 
> I'm also OK with adding more examples, and work on simplifying the
> per-project configuration workflow, maybe by somehow making it
> easier to translate that dotted path notation into the nested JSON
> object that the server is ultimately looking for.

I feel that explaining the relationship between the dotted notation, the JSON object and the plist value that eglot accepts is already some cognitive load. And adding a translator into the mix will make it worse. If we provide the translator but don’t explain how it works, it will be just as confusing. But I could be wrong, I didn’t ponder this too deeply.

> By the way, it's per-project server configuration that you're
> presumably after when looking at eglot-workspace-configuration,
> NOT per-user.
> 
> A per-user thing would be :initializationOptions or custom
> command-line arguments in eglot-server-programs, or even a
> special ~/.foorc file that the server reads (rust analyzer doesn't
> seem to have one, though, but clangd does).  The reason I bring
> up the distinction is that, in many cases (but not all of course),
> the user is actually interested in that, but strays from
> the objective and ends up the same configuration over all her
> different projects.
> 

You are right, I was following an old GitHub issue that uses workspaceConfiguration and sends it as a initializationOption. 

> If this distinction is not clear in the manual, either, it should
> be made so.

initializatiOption is only mentioned in the documentation of eglot-server-progrems, while workspaceConfiguration has a dozen paragraphs devoted to it. So maybe it’s easy to take workspaceConfiguration as the “main” way to configure a server. Maybe we can spend a little bit of text noting initializationOption under the “Customizing eglot” section.

> 
> Reading the docs, rust-analyzer allows per-user configuration via
> :initializationOptions.  The syntax and supported options are
> usually the same but the difficulties and confusion associated
> with ~/.dir-locals.el are not there.
> 
> João


[-- Attachment #2: eglot-manual.patch --]
[-- Type: application/octet-stream, Size: 3615 bytes --]

From da0732e4629f3378d65946c63e1c1488c70198c3 Mon Sep 17 00:00:00 2001
From: Yuan Fu <casouri@gmail.com>
Date: Mon, 6 Mar 2023 14:13:43 -0800
Subject: [PATCH] Improve Eglot manual

* doc/misc/eglot.texi (Customizing Eglot): Mention that you can
configure the server through eglot-server-progrems; explain how to
interpret a language server's notation of configuration.
---
 doc/misc/eglot.texi | 62 ++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 56 insertions(+), 6 deletions(-)

diff --git a/doc/misc/eglot.texi b/doc/misc/eglot.texi
index eed9744b9f0..10df54c5ec1 100644
--- a/doc/misc/eglot.texi
+++ b/doc/misc/eglot.texi
@@ -923,8 +923,9 @@ Customizing Eglot
 @table @code
 @item eglot-server-programs
 This variable determines which language server to start for each
-supported major mode, and how to invoke that server's program.
-@xref{Setting Up LSP Servers}, for the details.
+supported major mode, how to invoke that server's program, and
+configures the server with server-specific options.  @xref{Setting Up
+LSP Servers}, for the details.
 
 @vindex eglot-strict-mode
 @item eglot-strict-mode
@@ -1012,10 +1013,59 @@ Customizing Eglot
 @var{plist} is the corresponding keyword-value property list of one or
 more parameter settings for that server, serialized by Eglot as a JSON
 object.  @var{plist} may be arbitrarily complex, generally containing
-other keyword-value property sublists corresponding to JSON subobjects.
-The JSON values @code{true}, @code{false}, @code{null} and @code{@{@}}
-are represented by the Lisp values @code{t}, @code{:json-false},
-@code{nil}, and @code{eglot-@{@}}, respectively.
+other keyword-value property sublists corresponding to JSON
+subobjects.  The JSON values @code{true}, @code{false}, @code{null}
+and @code{@{@}} are represented by the Lisp values @code{t},
+@code{:json-false}, @code{nil}, and @code{eglot-@{@}}, respectively.
+A JSON key @code{"xxx"} is represented by a Lisp keyword @code{:xxx};
+and a JSON array @code{[1, 2, 3]} is represented by a Lisp vector
+@code{([1 2 3])}.
+
+Language servers often describe their configuration options in the
+form of @code{xxx.yyy.zzz}, for example
+
+@example
+@group
+pylsp.plugins.jedi_completion.inclue_params: true
+pylsp.plugins.jedi_completion.fuzzy: true
+pylsp.plugins.pylint.endabled: false
+@end group
+@end example
+
+These configuration are shorthands that collectively corresponds to
+the following JSON configuration:
+
+@example
+@group
+{
+  "pylsp": {
+    "plugins": {
+      "jedi_completion": {
+        "include_params": true,
+        "fuzzy": true
+      },
+      "pylint": {
+        "enabled": false
+      }
+    }
+  }
+}
+@end group
+@end example
+
+To configure the server as such, set
+@code{eglot-workspace-configuration} to the corresponding plist of
+this JSON configuration.  Note that @code{"pylsp"} corresponds to the
+@var{server} (as @code{:pylsp}), and the rest corresponds to the
+@var{plist} of @code{:pylsp}.
+
+Language servers usually don't state clearly what's the value of
+@var{server} that they recognize. Sometimes it's the name of the
+language server, like @code{"pylsp"} or @code{"rust-analyzer"};
+sometimes it's the name of the language itself, like
+@code{"javascript"} or @code{"haskell"}.  Fortunately, the @code{xxx}
+part of the @code{xxx.yyy.zzz} pattern usually discloses the expected
+value of @var{server}.
 
 @findex eglot-show-workspace-configuration
 When experimenting with workspace settings, you can use the command
-- 
2.33.1


[-- Attachment #3: Type: text/plain, Size: 2 bytes --]