Explain a bit more on how to configure language server in Eglot's manual

Explain a bit more on how to configure language server in Eglot's manual

[Yuan Fu]

Recently I was trying to use eglot with rust-analyzer and configure rust-analyzer. It turns out more confusing than it should be, and I think we can add a paragraph to eglot’s manual to help others like me.

LSP servers generally allow configuration through either LSP’s workspaceConfiguration protocol or their custom configuration file. For those who use workspaceConfiguration, it is common for the documentation to say something like this:

    This is the list of config options rust-analyzer supports:

    rust-analyzer.assist.emitMustUse (default: false) blah blah blah
    …

To pass this configuration to rust-analyzer through eglot, you need to set eglot-workspace-configuration to 

'(:rust-analyzer (:assist (:emitMustUse t)))

However, it is not obviously clear how to interpret “rust-analyzer.assist.emitMustUse”, not for someone inexperience with LSP, at least. (OTOH, the manual explains very clearly how to translate a JSON config to a plist, great job!)

I suggest we add a sentence or a paragraph to the eglot manual explaining that rust-analyzer.assist.emitMustUse translates to the JSON configuration

{
  "rust-analyzer": {
    "assist": {
      "emitMustUse": true
    }
  }
}

And the user should translate that to the plist format for eglot-workspace-configuration.

This is not something only rust-analyzer does. I surveyed a bunch of language servers, all the servers that support LSP’s workspaceConfiguration (typescript, rust, python, OCaml, Haskell, perl, Java) describe their configuration in the xxx.xx.xxx format. Because this is the format one can copy and paste into VSCode’s setting file.

We should probably also mention that the “root key” (the "rust-analyzer” part) isn’t always the name of the language server. Some server expects the language name rather than the server’s name, ie, haskell rather than haskell-language-server. Typescript expects “typescript” or “javascript”, perl, ocaml, java expects language names, python expects “pyls”, the name of the server.

Yuan

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

[Stephen Leake]

Yuan Fu <casouri@gmail.com> writes:

> Recently I was trying to use eglot with rust-analyzer and configure
> rust-analyzer. It turns out more confusing than it should be, and I
> think we can add a paragraph to eglot’s manual to help others like me.

+1

-- 
-- Stephe

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

[João Távora]

Yuan, please show the patch to Eglot's manual and let's work from
there.

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.

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.

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

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

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

[Augusto Stoffel]

On Sat,  4 Mar 2023 at 20:45, Yuan Fu wrote:

> Recently I was trying to use eglot with rust-analyzer and configure
> rust-analyzer. It turns out more confusing than it should be, and I
> think we can add a paragraph to eglot’s manual to help others like me.

I gave a suggestion in bug#61868 to make the
eglot-show-workspace-configuration buffer editable so that you can
commit changes with C-c C-c, fetch old configuration with M-n/M-p, etc.,
a bit like VC or Magit commit buffers.

> This is not something only rust-analyzer does. I surveyed a bunch of
> language servers, all the servers that support LSP’s
> workspaceConfiguration (typescript, rust, python, OCaml, Haskell,
> perl, Java) describe their configuration in the xxx.xx.xxx
> format. Because this is the format one can copy and paste into
> VSCode’s setting file.

I've argued in favor of that in the past, but now I think loc. cit. is a
better idea.

The best solution IMO, thought, would be if the server could announce
the schema of configurations it accepts, including types and docstrings.
Then one could construct an easy Customize interface.  But unfortunately
there is no such thing in the LSP spec.

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

[João Távora]

On Mon, Mar 6, 2023 at 10:35 AM Augusto Stoffel <arstoffel@gmail.com> wrote:
>
> On Sat,  4 Mar 2023 at 20:45, Yuan Fu wrote:
>
> > Recently I was trying to use eglot with rust-analyzer and configure
> > rust-analyzer. It turns out more confusing than it should be, and I
> > think we can add a paragraph to eglot’s manual to help others like me.
>
> I gave a suggestion in bug#61868 to make the
> eglot-show-workspace-configuration buffer editable so that you can
> commit changes with C-c C-c, fetch old configuration with M-n/M-p, etc.,
> a bit like VC or Magit commit buffers.

Conveniently editing Emacs variables (file-local, dir-local, buffer
-local, global) interactively from the minibuffer (or some other similar
place) is an idea that has been discussed before here.  We could
restart that discussion.

If such a mechanism  is eventually agreed on for Emacs in general, Eglot
could very well take advantage, but don't think eglot.el should just make
its own idiosyncratic take on that.

João

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

[Augusto Stoffel]

On Mon,  6 Mar 2023 at 10:51, João Távora wrote:

> Conveniently editing Emacs variables (file-local, dir-local, buffer
> -local, global) interactively from the minibuffer (or some other similar
> place) is an idea that has been discussed before here.  We could
> restart that discussion.

But this exists: add-local add-dir-local-variable,
add-file-local-variable, customize-set-variable, set-variable are all
interactive functions that use the minibuffer.  But I don't think this
UI is the most suitable for this purpose.

> If such a mechanism  is eventually agreed on for Emacs in general, Eglot
> could very well take advantage, but don't think eglot.el should just make
> its own idiosyncratic take on that.

AFAICT this mechanism has been agreed upon.  VC log, Magit commit, Org
capture, to name a few, all use the kind of UI I described.

However, I agree that this is a common type of UI that does not to have
a corresponding library to create easily, unless I'm missing something.

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

[João Távora]

On Mon, Mar 6, 2023 at 11:00 AM Augusto Stoffel <arstoffel@gmail.com> wrote:
>
> On Mon,  6 Mar 2023 at 10:51, João Távora wrote:
>
> > Conveniently editing Emacs variables (file-local, dir-local, buffer
> > -local, global) interactively from the minibuffer (or some other similar
> > place) is an idea that has been discussed before here.  We could
> > restart that discussion.
>
> But this exists: add-local add-dir-local-variable,
> add-file-local-variable, customize-set-variable, set-variable are all
> interactive functions that use the minibuffer.  But I don't think this
> UI is the most suitable for this purpose.

Then they should be upgraded so that they do become suitable, because
this is first and foremost about editing variables.  For example, there
could be:

* a way to ask to do do the editing in a separate buffer
* a way to insert the current value of the variable to be added
  as the initial value of the thing to be read
* a way to ask to use 'eval' of the user's input rather then just
  'read' (here, an Eglot function could be used to spit out a plist
  from a bunch of dotted strings in VSCode style).
* maybe more?

Also, the LSP use case you're asking for here is for add-dir-local-variable
where the directory is the current project's project-root.  So maybe a
add-project-local-variable or somesuch would be a good first step.

> > If such a mechanism  is eventually agreed on for Emacs in general, Eglot
> > could very well take advantage, but don't think eglot.el should just make
> > its own idiosyncratic take on that.
>
> AFAICT this mechanism has been agreed upon.  VC log, Magit commit, Org
> capture, to name a few, all use the kind of UI I described.

These are not for editing values of Emacs Lisp variables.

João

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

[Pedro Andres Aranda Gutierrez]

Hi,

>> But this exists: add-local add-dir-local-variable,
>> add-file-local-variable, customize-set-variable, set-variable are all
>> interactive functions that use the minibuffer.  But I don't think this
>> UI is the most suitable for this purpose.

>Then they should be upgraded so that they do become suitable, because
>this is first and foremost about editing variables.

There you could face resistance from people using the already existing
functionality.

>  For example, there could be:
> * a way to ask to do do the editing in a separate buffer
customize-set-variable

> * a way to insert the current value of the variable to be added
>   as the initial value of the thing to be read
.emacs.d/init.el or .dirlocals.el

> * a way to ask to use 'eval' of the user's input rather then just
>  'read' (here, an Eglot function could be used to spit out a plist
>  from a bunch of dotted strings in VSCode style).
> * maybe more?

I for me am not completely convinced that "VSCode-alike is good" ;-)

And to be 'positive', if the main issue here is VScode <-> emacs compatibility
what about a layer to read VSCode configs and converting them to Emacs LISP.
Because that's something that may be challenging.

/PA

On Mon, 6 Mar 2023 at 12:13, João Távora <joaotavora@gmail.com> wrote:
>
> On Mon, Mar 6, 2023 at 11:00 AM Augusto Stoffel <arstoffel@gmail.com> wrote:
> >
> > On Mon,  6 Mar 2023 at 10:51, João Távora wrote:
> >
> > > Conveniently editing Emacs variables (file-local, dir-local, buffer
> > > -local, global) interactively from the minibuffer (or some other similar
> > > place) is an idea that has been discussed before here.  We could
> > > restart that discussion.
> >
> > But this exists: add-local add-dir-local-variable,
> > add-file-local-variable, customize-set-variable, set-variable are all
> > interactive functions that use the minibuffer.  But I don't think this
> > UI is the most suitable for this purpose.
>
> Then they should be upgraded so that they do become suitable, because
> this is first and foremost about editing variables.  For example, there
> could be:
>
> * a way to ask to do do the editing in a separate buffer
> * a way to insert the current value of the variable to be added
>   as the initial value of the thing to be read
> * a way to ask to use 'eval' of the user's input rather then just
>   'read' (here, an Eglot function could be used to spit out a plist
>   from a bunch of dotted strings in VSCode style).
> * maybe more?
>
> Also, the LSP use case you're asking for here is for add-dir-local-variable
> where the directory is the current project's project-root.  So maybe a
> add-project-local-variable or somesuch would be a good first step.
>
> > > If such a mechanism  is eventually agreed on for Emacs in general, Eglot
> > > could very well take advantage, but don't think eglot.el should just make
> > > its own idiosyncratic take on that.
> >
> > AFAICT this mechanism has been agreed upon.  VC log, Magit commit, Org
> > capture, to name a few, all use the kind of UI I described.
>
> These are not for editing values of Emacs Lisp variables.
>
> João



-- 
Fragen sind nicht da um beantwortet zu werden,
Fragen sind da um gestellt zu werden
Georg Kreisler

Headaches with a Juju log:
unit-basic-16: 09:17:36 WARNING juju.worker.uniter.operation we should
run a leader-deposed hook here, but we can't yet

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

[João Távora]

On Mon, Mar 6, 2023 at 11:31 AM Pedro Andres Aranda Gutierrez
<paaguti@gmail.com> wrote:

> >Then they should be upgraded so that they do become suitable, because
> >this is first and foremost about editing variables.
>
> There you could face resistance from people using the already existing
> functionality.

That's why we should discuss and come up with a solution that is
backward compatible with existing usage.  Business as usual, I'm afraid.

> >  For example, there could be:

> > * a way to ask to use 'eval' of the user's input rather then just
> >  'read' (here, an Eglot function could be used to spit out a plist
> >  from a bunch of dotted strings in VSCode style).
> > * maybe more?
>
> I for me am not completely convinced that "VSCode-alike is good" ;-)

Precisely: neither am I.  But others seem to appreciate it and that's
fine.  You wouldn't be required to use that Eglot helper to enter
the plist value.

> And to be 'positive', if the main issue here is VScode <-> emacs compatibility
> what about a layer to read VSCode configs and converting them to Emacs LISP.
> Because that's something that may be challenging

I think that's exactly what I'm proposing with the Eglot helper.

(defun eglot-dotted-to-plist (strings)
  "Return plist suitable for adding to `eglot-workspace-configuration'
STRINGS is a list of VSCode style dotted notation settings."
   ...)

A fun exercise, probably.  First stab at it gets a virtual cookie :-)

João

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

[Augusto Stoffel]

On Mon,  6 Mar 2023 at 11:13, João Távora wrote:

> On Mon, Mar 6, 2023 at 11:00 AM Augusto Stoffel <arstoffel@gmail.com> wrote:
>>
>> On Mon,  6 Mar 2023 at 10:51, João Távora wrote:
>> AFAICT this mechanism has been agreed upon.  VC log, Magit commit, Org
>> capture, to name a few, all use the kind of UI I described.
>
> These are not for editing values of Emacs Lisp variables.

To me, the server configuration is a Lisp value to the same extent that
my ~/.config/pycodestyle or .clangd files are.  IOW, not at all.  Except
that, due to Microsoft reasons, the server doesn't read its own
configuration file as has been done since the dawn of civilization and,
instead, we need to intermediate this.

So the best and least vscode-oriented UI is the one that lets the user
edit the configuration as if it was a config file.  If it is presented
as in sexp or JSON or YAML or TOML format is immaterial (I dislike the
sexp format a bit because it leaks details about how jsonrpc.el
represents null, false and the empty mapping.)

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

[Augusto Stoffel]

On Mon,  6 Mar 2023 at 11:46, João Távora wrote:

> I think that's exactly what I'm proposing with the Eglot helper.
>
> (defun eglot-dotted-to-plist (strings)
>   "Return plist suitable for adding to `eglot-workspace-configuration'
> STRINGS is a list of VSCode style dotted notation settings."
>    ...)
>
> A fun exercise, probably.  First stab at it gets a virtual cookie :-)

If you think this is the best approach, then let's make a
Customize-based thing where you can enter the alist of "dotted names"
and the corresponding value.

I bet it's actually _way more_ code than the Magit commit style thingy,
but it's indeed a bit more user friendly.  And when LSP adds the ability
for the server to communicate its configuration schema (funny how this
idea escaped them), we can adapt the UI easily to it.

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

[João Távora]

On Mon, Mar 6, 2023 at 1:08 PM Augusto Stoffel <arstoffel@gmail.com> wrote:
> > (defun eglot-dotted-to-plist (strings)
> >   "Return plist suitable for adding to `eglot-workspace-configuration'
> > STRINGS is a list of VSCode style dotted notation settings."
> >    ...)
> >
> > A fun exercise, probably.  First stab at it gets a virtual cookie :-)
>
> If you think this is the best approach, then let's make a
> Customize-based thing where you can enter the alist of "dotted names"
> and the corresponding value.

The helper function I'm proposing here is just an expedited
way to get a plist from the dotted notation that some people
seem to like.

I'm not a fan of Customize myself, and AFAIK it doesn't support
dir/file/buffer variable locality cleanly (or at all).  I think
the enhancements we are talking about should go to the existing
add-dir-local-variable,  add-file-local-variable etc.  Of course
you may convince others of the contrary and go on a Customize
overhauling adventure (of which I will probably not be a part of).

Anyway if eglot-dotted-to-plist appears in eglot.el anytime soon,
it's an improvement to work with a-d-l-v and a-f-l-v or whatever
variable setting-methods are available today ortomorrow.

If someone comes up with the code, I'll probably merge it soon and
mention its utility in the manual.

IOW, it's an improvement in this area, but is also orthogonal to
whichever UI is eventually chosen to simplify editing values
of Elisp variables in .dir-locals.el etc.

João

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

[Augusto Stoffel]

On Mon,  6 Mar 2023 at 13:50, João Távora wrote:

> I'm not a fan of Customize myself, and AFAIK it doesn't support
> dir/file/buffer variable locality cleanly (or at all).  I think
> the enhancements we are talking about should go to the existing
> add-dir-local-variable,  add-file-local-variable etc.  Of course
> you may convince others of the contrary and go on a Customize
> overhauling adventure (of which I will probably not be a part of).

To be clear, I didn't mean that we should use Customize to save the
values.  I just said a Customize-type buffer with widgets could be used
to view and edit the so-called "workspace configuration".

If you use Gnus, I'd suggest to try M-x gnus-group-edit-group-parameters
and M-x gnus-group-customize in the Group buffer to see how the two
ideas I raised here look like in practice.

> Anyway if eglot-dotted-to-plist appears in eglot.el anytime soon,
> it's an improvement to work with a-d-l-v and a-f-l-v or whatever
> variable setting-methods are available today ortomorrow.

I think this could be helpful; maybe a lot, maybe just a little.  If I
may give an honest opinion, I think you've searching for the minimal
quick fix for this configuration conundrum for some time now and it
doesn't look it's working.

We wouldn't be discussing any of this is LSP servers had configuration
files like any other normal program, but, given the state of affairs, we
should just decide on an "actually good" solution and spend the 300 LOC
it takes to implement that.

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

[João Távora]

On Mon, Mar 6, 2023 at 4:10 PM Augusto Stoffel <arstoffel@gmail.com> wrote:

> > Anyway if eglot-dotted-to-plist appears in eglot.el anytime soon,
> > it's an improvement to work with a-d-l-v and a-f-l-v or whatever
> > variable setting-methods are available today ortomorrow.
>
> I think this could be helpful; maybe a lot, maybe just a little.  If I
> may give an honest opinion, I think you've searching for the minimal
> quick fix for this configuration conundrum for some time now and it
> doesn't look it's working.

I'm looking for the right fix.  Proceeding minimally and deliberately
is how I roll, and that's how I avoid bloat that I know I won't
have time to maintain.

> We wouldn't be discussing any of this is LSP servers had configuration
> files like any other normal program, but, given the state of affairs, we
> should just decide on an "actually good" solution and spend the 300 LOC
> it takes to implement that.

I gave my take on where those 300 LOC should be spent:

add-dir-local-variable with new edit-in-buffer option, an eval option,
and a fill-in-existing-value option.  As a bonus, all those are
orthogonal, so you can do 100 + 100 + 100.

João

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

[Augusto Stoffel]

On Mon,  6 Mar 2023 at 16:25, João Távora wrote:

>> We wouldn't be discussing any of this is LSP servers had configuration
>> files like any other normal program, but, given the state of affairs, we
>> should just decide on an "actually good" solution and spend the 300 LOC
>> it takes to implement that.
>
> I gave my take on where those 300 LOC should be spent:
>
> add-dir-local-variable with new edit-in-buffer option, an eval option,
> and a fill-in-existing-value option.  As a bonus, all those are
> orthogonal, so you can do 100 + 100 + 100.

Fair enough.  I think you might be overestimating the general interest
in those things and underestimating the amount of glue code Eglot would
still need, but it's just a hunch.  Anyway, my offer to make the
eglot-show-workspace-configuration buffer editable remains open.  (If
you find a better solution you should probably remove e-s-w-c because it
feels like a hack in the current state.)

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

[João Távora]

On Mon, Mar 6, 2023 at 6:18 PM Augusto Stoffel <arstoffel@gmail.com> wrote:

> > add-dir-local-variable with new edit-in-buffer option, an eval option,
> > and a fill-in-existing-value option.  As a bonus, all those are
> > orthogonal, so you can do 100 + 100 + 100.
>
> Fair enough.  I think you might be overestimating the general interest
> in those things and underestimating the amount of glue code Eglot would
> still need, but it's just a hunch.

What glue code?  M-x add-dir-local-variable (or M-x add-project-local-variable
which is a just a very thing shim on top of the other), then select
eglot-workspace-configuration, then edit the value and you're done.

> Anyway, my offer to make the
> eglot-show-workspace-configuration buffer editable remains open.  (If
> you find a better solution you should probably remove e-s-w-c because it
> feels like a hack in the current state.)

Not a hack, really.  eglot-show-workspace-configuration shows the actual
configuration in JSON format.  That's useful and LSP specific, so it
belongs in Eglot. Fredrik Bergroth added it because that is what is
sent to the server and is really good for debug purposes and
communicating with server devs, for example.  So it's not subsumed
by C-h v, for example.

João

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

[Pedro Andres Aranda Gutierrez]

If we have the plist-> json part, how difficult would it be to do the reverse and allow the config to be stored as a JSON string?

Just an innocent 😇 question…

PA

Enviado desde mi iPhone

> El 6 mar 2023, a las 19:32, João Távora <joaotavora@gmail.com> escribió:
> 
> On Mon, Mar 6, 2023 at 6:18 PM Augusto Stoffel <arstoffel@gmail.com> wrote:
> 
>>> add-dir-local-variable with new edit-in-buffer option, an eval option,
>>> and a fill-in-existing-value option.  As a bonus, all those are
>>> orthogonal, so you can do 100 + 100 + 100.
>> 
>> Fair enough.  I think you might be overestimating the general interest
>> in those things and underestimating the amount of glue code Eglot would
>> still need, but it's just a hunch.
> 
> What glue code?  M-x add-dir-local-variable (or M-x add-project-local-variable
> which is a just a very thing shim on top of the other), then select
> eglot-workspace-configuration, then edit the value and you're done.
> 
>> Anyway, my offer to make the
>> eglot-show-workspace-configuration buffer editable remains open.  (If
>> you find a better solution you should probably remove e-s-w-c because it
>> feels like a hack in the current state.)
> 
> Not a hack, really.  eglot-show-workspace-configuration shows the actual
> configuration in JSON format.  That's useful and LSP specific, so it
> belongs in Eglot. Fredrik Bergroth added it because that is what is
> sent to the server and is really good for debug purposes and
> communicating with server devs, for example.  So it's not subsumed
> by C-h v, for example.
> 
> João

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

[Augusto Stoffel]

On Mon,  6 Mar 2023 at 18:32, João Távora wrote:

> On Mon, Mar 6, 2023 at 6:18 PM Augusto Stoffel <arstoffel@gmail.com> wrote:
>
>> > add-dir-local-variable with new edit-in-buffer option, an eval option,
>> > and a fill-in-existing-value option.  As a bonus, all those are
>> > orthogonal, so you can do 100 + 100 + 100.
>>
>> Fair enough.  I think you might be overestimating the general interest
>> in those things and underestimating the amount of glue code Eglot would
>> still need, but it's just a hunch.
>
> What glue code?  M-x add-dir-local-variable (or M-x add-project-local-variable
> which is a just a very thing shim on top of the other), then select
> eglot-workspace-configuration, then edit the value and you're done.

You're done and scratching your head, wondering why your server didn't
pick up the settings yet.

> Not a hack, really.  eglot-show-workspace-configuration shows the actual
> configuration in JSON format.  That's useful and LSP specific, so it
> belongs in Eglot. Fredrik Bergroth added it because that is what is
> sent to the server and is really good for debug purposes and
> communicating with server devs, for example.  So it's not subsumed
> by C-h v, for example.

By that reasoning one would want the entire events buffer in JSON
format.  In my recollection that command was really intended to debug
user configurations.

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

[João Távora]

On Mon, Mar 6, 2023 at 9:13 PM Augusto Stoffel <arstoffel@gmail.com> wrote:
>
> On Mon,  6 Mar 2023 at 18:32, João Távora wrote:
>
> > On Mon, Mar 6, 2023 at 6:18 PM Augusto Stoffel <arstoffel@gmail.com> wrote:

> You're done and scratching your head, wondering why your server didn't
> pick up the settings yet.

Don't exaggerate.  There's a command to signal a new changed configuration
to the server.  If we want we can even hook up a variable watcher and call
it automatically, but this is beside the point here.

> By that reasoning one would want the entire events buffer in JSON
> format.  In my recollection that command was really intended to debug
> user configurations.

Sure, and making a JSON version of the eglot events buffer is probably
a good idea.  Patches welcome.

> Fair enough.  I think you might be overestimating the general interest
> in those things

BTW... in reply to your earlier point. It was you, not me, who expressed
interest in a separate buffer interface where you could edit
eglot-workspace-configuration's value and finish with a C-c.  The proposal
you put forth is unacceptable to me, I'm afraid.  But I'm giving you
my view on what is an equivalent and more generally useful functionality.

So am I overestimating _your_ interest? Maybe I am, and perhaps
putting a bit too much effort in coming up in solutions to your problem.

There's nothing stopping you from making a third-party package that
implements your vision for this.  You can start with some function-add
to eglot-show-workspace-configuration, and if it's solid enough, we
can make a hook.

João

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

[Yuan Fu]

[-- 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 --]

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

[João Távora]

Yuan Fu <casouri@gmail.com> writes:

>> 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.

Thanks.  I think the most important part in your patch is to show me
exactly the points in the manual's writing that are confusing.

>> 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.

The dotted-to-plist translator proposed is optional.  Some people
requested use of dotted notation and that will surely need a translator.
I wouldn't use it.

But you're right that it's orthogonal to the request of a clearly and
well-structured writing on this topic, which I agree that this version
of the manual doesn't offer (the old Eglot README was very slightly
better in this department, IIRC)

>> 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. 

No, there are two ways, and neither is more valuable than the other.  It
depends entirely on what the user wants.  

> Maybe we can spend a little bit of text noting initializationOption
> under the “Customizing eglot” section.

I'm leaning into making a dedicated "Server configuration" section with
3 subsections: initializationOptions, eglot-workspace-configuration, and
the representations of common JSON object that is used for both of them.

João

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

[Augusto Stoffel]

In the meanwhile I've discovered that many servers have a configuration
schema available _somewhere_.  For example, pylsp has it here:

  https://raw.githubusercontent.com/python-lsp/python-lsp-server/develop/pylsp/config/schema.json

and this discussion mentions others:

  https://github.com/williamboman/nvim-lsp-installer/discussions/575

So if the difficulty of gathering these data is overcome, Eglot could do
something actually helpful and show a listing with the types and
documentation of the options (whatever the specifics look like).

Of course there isn't a no-code way for Eglot to provide such a feature.
But one starting point would be to have generic a widget screen to edit
a structure specified by a JSON schema.  This shouldn't be too hard to
do.

On Tue,  7 Mar 2023 at 11:59, João Távora wrote:

> The dotted-to-plist translator proposed is optional.  Some people
> requested use of dotted notation and that will surely need a
> translator.  I wouldn't use it.

Given how selective you are with the features you want to add, I don't
understand why you think this particular one should make it in.  It
would sure help a little, maybe, sometimes.

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

[João Távora]

On Wed, Mar 8, 2023 at 1:27 PM Augusto Stoffel <arstoffel@gmail.com> wrote:

> So if the difficulty of gathering these data is overcome, Eglot could do
> something actually helpful and show a listing with the types and
> documentation of the options (whatever the specifics look like).

If and when the LSP protocol stops specifying options as an "LSPAny"
object and builds some protocol on top of it to communicate schema
Eglot will evaluate if there's some tangible benefit of
getting that from the server.  Until then, anything you do
with this information is language-server specific.  It should
go into a major-mode or a different extension...

> > The dotted-to-plist translator proposed is optional.  Some people
> > requested use of dotted notation and that will surely need a
> > translator.  I wouldn't use it.
>
> Given how selective you are with the features you want to add, I don't
> understand why you think this particular one should make it in.  It
> would sure help a little, maybe, sometimes.

I don't understand: didn't you state you _like_ dotted notation?
Well, this translator is needed for it, because the e-w-configuration
variable is a plist.  I reject features which I consider bloat, i.e. they
have no bearing to LSP in particular or they solve too specific
a problem that should really be solved somewhere else (normally this
isn't done simply because that takes more effort and discussion).
A special plist editing mode for a single Eglot variable falls into
that category, IMNSHO.

Dotted option notation does not.  It seems to be an LSP practice,
and I don't see any other good place to put a single utility function
that facilitates it but in Eglot.  If it helps people "a little"
and has close to 0 maintenance cost, then I don't see why it shouldn't
be included.

And yes, there are already examples of bloat in eglot.el. But two
wrongs don't make a right.  There was some bloat that I've already
extracted and put in its rightful place, like the "external" completion
style.  And there was jsonrpc.el in the beginning.  Another example
is Eglot's "glob compiler" needed for LSP but probably more generally
useful and which also belongs elsewhere.  Currently I'm also looking
to move the markdown rendering to eldoc.el: Eglot shouldn't be doing
that.  If you're looking to contribute, I'm much more open to patches
that reduce_ Eglot's bloat than ones which potentially increase it.

João

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

[Augusto Stoffel]

On Wed,  8 Mar 2023 at 13:54, João Távora wrote:

>> > The dotted-to-plist translator proposed is optional.  Some people
>> > requested use of dotted notation and that will surely need a
>> > translator.  I wouldn't use it.
>>
>> Given how selective you are with the features you want to add, I don't
>> understand why you think this particular one should make it in.  It
>> would sure help a little, maybe, sometimes.
>
> I don't understand: didn't you state you _like_ dotted notation?

Yes, as a quick fix.  But you and the circumstances showed that it isn't
nearly good enough.

> A special plist editing mode for a single Eglot variable falls into
> that category, IMNSHO.

By the way, my suggestion is to edit a JSON value, which is what the
server receives, you can copy and paste from other places, and doesn't
require you to know jsonrpc.el internals such as :json-false and the
translation of nil.

> Dotted option notation does not.  It seems to be an LSP practice,

It may be a practice, but the ground truth is a JSON object.

> and I don't see any other good place to put a single utility function
> that facilitates it but in Eglot.

The utility function belongs to map.el.  It is called `assoc-in` in
Clojure.

Speaking of bloat, and I know I shouldn't insist, but a basic version of
the savable eglot-show-workspace-configuration barely adds 30 LOC.

I'm pasting it here in case it helps anybody.

--8<---------------cut here---------------start------------->8---
(defvar-local eglot-wsconf--server nil)

(defvar eglot-wsconf-map
  (let ((map (make-sparse-keymap)))
    (define-key map "\C-c\C-c" #'eglot-wsconf-commit)
    map))

(defun eglot-wsconf-commit ()
  (interactive)
  (let ((wsconf (save-excursion
                  (goto-char (point-min))
                  (jsonrpc--json-read))))
    (save-window-excursion
      (let ((default-directory (project-root (eglot--project eglot-wsconf--server)))
            (buffers (buffer-list)))
        (add-dir-local-variable nil 'eglot-workspace-configuration wsconf)
        (save-buffer)
        (if (memq (current-buffer) buffers) (bury-buffer) (kill-buffer))))
    (eglot-signal-didChangeConfiguration eglot-wsconf--server)
    (quit-window t)))

;;;###autoload
(defun eglot-wsconf-edit (server)
  "Edit the language server workspace configuration."
  (interactive (list (eglot--read-server "Show workspace configuration for" t)))
  (pop-to-buffer (eglot-show-workspace-configuration server))
  (use-local-map eglot-wsconf-map)
  (setq-local header-line-format (substitute-command-keys "\
Press \\[eglot-wsconf-commit] to commit changes"))
  (setq eglot-wsconf--server server))
--8<---------------cut here---------------end--------------->8---

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

[Yuri Khan]

On Wed, 8 Mar 2023 at 20:55, João Távora <joaotavora@gmail.com> wrote:

> Dotted option notation does not.  It seems to be an LSP practice,

Dotted notation is a common informal convention for addressing a
subtree (or, in particular, a leaf) of a JSON structure.

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

[João Távora]

On Wed, Mar 8, 2023 at 3:24 PM Yuri Khan <yuri.v.khan@gmail.com> wrote:
>
> On Wed, 8 Mar 2023 at 20:55, João Távora <joaotavora@gmail.com> wrote:
>
> > Dotted option notation does not.  It seems to be an LSP practice,
>
> Dotted notation is a common informal convention for addressing a
> subtree (or, in particular, a leaf) of a JSON structure.

OK.  So if someone puts this function elsewhere and Eglot
can take advantage, that's fine and dandy.  Where would you
put a  dotted-settings-to-plist function?

João

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

[Yuri Khan]

On Wed, 8 Mar 2023 at 22:27, João Távora <joaotavora@gmail.com> wrote:
> > Dotted notation is a common informal convention for addressing a
> > subtree (or, in particular, a leaf) of a JSON structure.
>
> OK.  So if someone puts this function elsewhere and Eglot
> can take advantage, that's fine and dandy.  Where would you
> put a  dotted-settings-to-plist function?

I do not know if I would at all. As I said, it is an informal
convention. It skirts a number of corner cases, and as soon as you try
to build a sound implementation, you are forced to address those,
which breeds incompatible dialects.

(As a few examples, on the first sight, it looks as if the dotted path
is a dot-separated concatenation of unquoted object keys going from
the root object. What do you do if one of the keys contains a dot? a
space? What if one of the keys being traversed is an empty string?
What if you need to traverse an array?)

I just expect people to be able to read
‘rust-analyzer.assist.emitMustUse (default: false)’ in documentation
and write

    {
      "rust-analyzer": {
        "assist": {
          "emitMustUse": true
        }
      }
    }

in a JSON config or

    rust-analyzer:
      assist:
        emitMustUse: true

in YAML.

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

[João Távora]

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

On Wed, Mar 8, 2023, 15:52 Yuri Khan <yuri.v.khan@gmail.com> wrote:

> On Wed, 8 Mar 2023 at 22:27, João Távora <joaotavora@gmail.com> wrote:
>

> OK.  So if someone puts this function elsewhere and Eglot
> > can take advantage, that's fine and dandy.  Where would you
> > put a  dotted-settings-to-plist function?
>
> I do not know if I would at all. As I said, it is an informal
> convention. It skirts a number of corner cases, and as soon as you try
> to build a sound implementation, you are forced to address those,
> which breeds incompatible dialects.
>
> (As a few examples, on the first sight, it looks as if the dotted path
> is a dot-separated concatenation of unquoted object keys going from
> the root object. What do you do if one of the keys contains a dot? a
> space? What if one of the keys being traversed is an empty string?
> What if you need to traverse an array?)


Right, i see your point. Then I'd say again that it maybe belongs in Eglot
because -- presumably -- LSP options objects don't incur in those edge
cases.

I just expect people to be able to read
> ‘rust-analyzer.assist.emitMustUse (default: false)’ in documentation
> and write
>
>     {
>       "rust-analyzer": {
>         "assist": {
>           "emitMustUse": true
>         }
>       }
>     }
>
> in a JSON config or
>
>     rust-analyzer:
>       assist:
>         emitMustUse: true
>
> in YAML.
>

Indeed.  And why not a plist, since we're in lisp land? :)

João

>

[-- Attachment #2: Type: text/html, Size: 2709 bytes --]

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

[João Távora]

On Wed, Mar 8, 2023 at 3:01 PM Augusto Stoffel <arstoffel@gmail.com> wrote:

> > I don't understand: didn't you state you _like_ dotted notation?
>
> Yes, as a quick fix.  But you and the circumstances showed that it isn't
> nearly good enough.

OK.  Then we'll hold that idea back.  AFAICT, Yuan also is also a fan
of that notation, so maybe he can chime in.

> > A special plist editing mode for a single Eglot variable falls into
> > that category, IMNSHO.
>
> By the way, my suggestion is to edit a JSON value, which is what the
> server receives, you can copy and paste from other places, and doesn't
> require you to know jsonrpc.el internals such as :json-false and the
> translation of nil.

They are not internals.  They are the external, published and documented
way to create JSON for jsonrpc.el contexts.  The documentation isn't
great, I know.  This is precisely what this thread is originally about
and I'm working on it.

> > and I don't see any other good place to put a single utility function
> > that facilitates it but in Eglot.
>
> The utility function belongs to map.el.  It is called `assoc-in` in
> Clojure.

Yuri presented some pretty good arguments about how that would
be a bad idea.  Also, not a Clojure expert, but AFAIK that
function doesn't take dotted notation strings as input.

> Speaking of bloat, and I know I shouldn't insist, but a basic version of
> the savable eglot-show-workspace-configuration barely adds 30 LOC.

Your code has at least two big problems:

* it takes the current value from one place and
  potentially saves it in another place.  This is asking
  for trouble.  I know you favour the 'nil' method exclusively
  for setting e-w-configuration, but it's not the only supported
  methods and there are configurations out in the wild that
  we can't break. Also note the that per-file or per-sub-hierarchy
  workspace configurations _are_supported by LSP (the scopeUri
  argument to the workspace/configuration server request).

* it doesn't take into account dir-local-set-class-variables

These are exactly the type of edge cases that I don't want
to handle in Eglot.  In other words, Emacs has many variable
setting methods and making an Eglot function to oversimplify
them, even if it happens to work for an estimated majority of
cases, is a bad idea, simply because it will break a minority.

That said, your code has great ergonomics and you seem to be
a very able Elisper.  So I'll restate: if a generic, safe
version of this hits Emacs libraries, Eglot will be happy to
use it and I at least will be very grateful for that contribution.

A better dir-local editing facility would account for (at least)
those two cases.  Even if that accounting is, at first, just bailing
out and warning the user if it detects them.  That's perfectly fine
in my book.  It'll mean the code will work fine for the 90% of users
and not confuse the other 10% to death.

That new dir-local editing facility could even allow you to
use JSON notation to edit a variable's plist, and eglot.el could
hint on that preference by setting 'serializer' and 'deserializer'
properties on e-w-configuration (though a more lispy name would
be 'write' and 'read' perhaps).

Additionally, in eglot.el, a variable watcher could be added to
e-w-c to take care of LSP signalling automatically if changes to
the value are detected.

So I urge you to generalize your code and propose it here
in a new :core ELPA package.

Thanks,
João

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

[Augusto Stoffel]

On Wed,  8 Mar 2023 at 19:43, João Távora wrote:

>> The utility function belongs to map.el.  It is called `assoc-in` in
>> Clojure.
>
> Yuri presented some pretty good arguments about how that would
> be a bad idea.  Also, not a Clojure expert, but AFAIK that
> function doesn't take dotted notation strings as input.

Of course you would need to combine it with split-string (and a
dolist or seq-reduce to process a list of those dotted names).

>> Speaking of bloat, and I know I shouldn't insist, but a basic version of
>> the savable eglot-show-workspace-configuration barely adds 30 LOC.
>
> Your code has at least two big problems:
>
> * it takes the current value from one place and
>   potentially saves it in another place.  This is asking
>   for trouble.  I know you favour the 'nil' method exclusively
>   for setting e-w-configuration, but it's not the only supported
>   methods and there are configurations out in the wild that
>   we can't break. Also note the that per-file or per-sub-hierarchy
>   workspace configurations _are_supported by LSP (the scopeUri
>   argument to the workspace/configuration server request).

Right, this is a problem.  It's missing the part that will “not confuse
the other 10% [of users] to death”, as you said.

> * it doesn't take into account dir-local-set-class-variables

This too.  Neither the possibility of e-w-c being a function.

> These are exactly the type of edge cases that I don't want
> to handle in Eglot.  In other words, Emacs has many variable
> setting methods and making an Eglot function to oversimplify
> them, even if it happens to work for an estimated majority of
> cases, is a bad idea, simply because it will break a minority.

Fair enough, but it seems that this multiplicity of methods basically
precludes one from making a helper tool for configurations.

> So I urge you to generalize your code and propose it here
> in a new :core ELPA package.

If you provide a function that receives a new configuration value and
stores it back in the right place, then this package becomes trivial.
If you don't, then this package is completely entangled with Eglot's
logic for reading configs.  In either case this doesn't seem to make a
lot of sense as a separate package.

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

[Yuan Fu]

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



> On Mar 8, 2023, at 11:43 AM, João Távora <joaotavora@gmail.com> wrote:
> 
> On Wed, Mar 8, 2023 at 3:01 PM Augusto Stoffel <arstoffel@gmail.com> wrote:
> 
>>> I don't understand: didn't you state you _like_ dotted notation?
>> 
>> Yes, as a quick fix.  But you and the circumstances showed that it isn't
>> nearly good enough.
> 
> OK.  Then we'll hold that idea back.  AFAICT, Yuan also is also a fan
> of that notation, so maybe he can chime in.
> 
>>> A special plist editing mode for a single Eglot variable falls into
>>> that category, IMNSHO.
>> 
>> By the way, my suggestion is to edit a JSON value, which is what the
>> server receives, you can copy and paste from other places, and doesn't
>> require you to know jsonrpc.el internals such as :json-false and the
>> translation of nil.
> 
> They are not internals.  They are the external, published and documented
> way to create JSON for jsonrpc.el contexts.  The documentation isn't
> great, I know.  This is precisely what this thread is originally about
> and I'm working on it.
> 
>>> and I don't see any other good place to put a single utility function
>>> that facilitates it but in Eglot.
>> 
>> The utility function belongs to map.el.  It is called `assoc-in` in
>> Clojure.
> 
> Yuri presented some pretty good arguments about how that would
> be a bad idea.  Also, not a Clojure expert, but AFAIK that
> function doesn't take dotted notation strings as input.
> 
>> Speaking of bloat, and I know I shouldn't insist, but a basic version of
>> the savable eglot-show-workspace-configuration barely adds 30 LOC.
> 
> Your code has at least two big problems:
> 
> * it takes the current value from one place and
>  potentially saves it in another place.  This is asking
>  for trouble.  I know you favour the 'nil' method exclusively
>  for setting e-w-configuration, but it's not the only supported
>  methods and there are configurations out in the wild that
>  we can't break. Also note the that per-file or per-sub-hierarchy
>  workspace configurations _are_supported by LSP (the scopeUri
>  argument to the workspace/configuration server request).
> 
> * it doesn't take into account dir-local-set-class-variables
> 
> These are exactly the type of edge cases that I don't want
> to handle in Eglot.  In other words, Emacs has many variable
> setting methods and making an Eglot function to oversimplify
> them, even if it happens to work for an estimated majority of
> cases, is a bad idea, simply because it will break a minority.
> 
> That said, your code has great ergonomics and you seem to be
> a very able Elisper.  So I'll restate: if a generic, safe
> version of this hits Emacs libraries, Eglot will be happy to
> use it and I at least will be very grateful for that contribution.
> 
> A better dir-local editing facility would account for (at least)
> those two cases.  Even if that accounting is, at first, just bailing
> out and warning the user if it detects them.  That's perfectly fine
> in my book.  It'll mean the code will work fine for the 90% of users
> and not confuse the other 10% to death.
> 
> That new dir-local editing facility could even allow you to
> use JSON notation to edit a variable's plist, and eglot.el could
> hint on that preference by setting 'serializer' and 'deserializer'
> properties on e-w-configuration (though a more lispy name would
> be 'write' and 'read' perhaps).
> 
> Additionally, in eglot.el, a variable watcher could be added to
> e-w-c to take care of LSP signalling automatically if changes to
> the value are detected.
> 
> So I urge you to generalize your code and propose it here
> in a new :core ELPA package.

Orthogonal to Augusto’s function, but I think something like this would be nice: a function that pops up a buffer and enters recursive edit for arbitrary input and edit, and when you hit C-c C-c, it returns the buffer content, kind of like Magit’s commit buffer. Plus buffer content validator (eg, validate JSON), and arbitrary major modes in the buffer, etc.

Load the file, and try

(json-parse-string
 (read-complex-value (lambda ()
                       (js-json-mode)
                       (read-complex-value-insert-prompt
                        "Type C-c C-c to finish, C-c C-k to abort:\n\n"))
                     (lambda ()
                       (condition-case nil
                           (progn (json-parse-buffer)
                                  t)
                         ((or end-of-file json-parse-error)
                          (message "Invalid JSON")
                          nil))))
 :object-type ‘plist)

It should pop a buffer in js-json-mode, and validates your JSON value. Typing C-c C-c returns the JSON as a plist.

Yuan


[-- Attachment #2: read-complex-value.el --]
[-- Type: application/octet-stream, Size: 5387 bytes --]

;;; read-complex-value.el --- Read complex value with recursive edit  -*- lexical-binding: t; -*-

;; Author: Yuan Fu <casouri@gmail.com>

;;; This file is NOT part of GNU Emacs

;;; Commentary:
;;
;; This package provides a function ‘read-complex-value’ that pops up
;; a buffer and goes into recursive edit for user to enter and edit
;; text. When the user is done and hit C-c C-c, the buffer content is
;; returned.

;;; Code:

(defface read-complex-value-prompt-face
  '((t . (:inherit shadow)))
  "Face used for the prompt text in ‘read-complex-value’ buffer.")

(defvar-local read-complex-value--validator nil
  "The function used to validate buffer’s content.
See documentation of ‘read-complex-value-raw’ for more.")

(defvar-local read-complex-value--mode nil
  "Whether this buffer is a ‘read-complex-value’ buffer.")

(defvar read-complex-value-map
  (let ((map (make-sparse-keymap)))
    (keymap-set map "C-c C-c" #'read-complex-value--done)
    (keymap-set map "C-c C-k" #'read-complex-value--abort)
    map)
  "Keymap used in ‘read-complex-value’ buffer.")

(defun read-complex-value-insert-prompt (&rest texts)
  "Insert each string in TEXTS into buffer as prompt text."
  (dolist (text texts)
    (insert (propertize text
                        'read-complex-value-setup t
                        'rear-nonsticky t
                        'read-only t
                        'font-lock-face 'read-complex-value-prompt-face
                        'face 'read-complex-value-prompt-face))))

(defun read-complex-value
    (&optional setup validator history
               display-action return-buffer signal)
  "Pop up a buffer and enter recursive edit, then return buffer content.

Returns the buffer content or nil when user types C-c C-c or C-c
C-k, respectively.

SETUP can be either a string, which is inserted at the beginning
of the buffer as prompt, or a function that takes no arguments
that’s run in the buffer for arbitrary setup.

Any prompt are removed in the returned text. To insert prompt
text in the SETUP function, use
‘read-complex-value-insert-prompt’.

VALIDATOR should be a function that takes no argument, and
returns either t if the buffer content is valid, or nil if not.
It runs in the buffer and should display messages to help the user
to understand why, when buffer content is invalid.

HISTORY is currently unused.

DISPLAY-ACTION controls how to display the buffer, it is the same
as in the ACTION parameter in ‘display-buffer’.

If RETURN-BUFFER is non-nil, return the buffer rather than a string.

If SIGNAL is non-nil, signal ‘read-complex-value-aborted’ when
user types C-c C-k, otherwise C-c C-k causes this function to
return nil."
  (let ((buf (generate-new-buffer " *read-complex-value*"))
        (window-config (current-window-configuration))
        (aborted nil))
    (select-window (display-buffer buf display-action))
    (cond ((stringp setup)
           (read-complex-value-insert-prompt setup))
          ((functionp setup) (funcall setup))
          (t (signal 'wrong-type-argument
                     `((or stringp functionp) . ,setup))))

    (setq-local read-complex-value--validator validator
                read-complex-value--aborted nil
                read-complex-value--mode t
                minor-mode-map-alist
                (cons (cons 'read-complex-value--mode
                            read-complex-value-map)
                      minor-mode-map-alist))

    (unwind-protect
        (progn
          (condition-case data
              (recursive-edit)
            (quit
             (message "%s" data)
             (if signal
                 (signal 'read-complex-value-aborted data)
               (setq aborted t))))

          (unless aborted
            (read-complex-value--prune-buffer)
            (if return-buffer
                (current-buffer)
              (buffer-string))))

      (kill-buffer)
      (set-window-configuration window-config))))

(defun read-complex-value--prune-buffer ()
  "Remove prompt text from the current buffer."
  (goto-char (point-min))
  (let ((inhibit-read-only t)
        prop)
    (while (setq prop (text-property-search-forward
                       'read-complex-value-setup))
      (delete-region (prop-match-beginning prop)
                     (prop-match-end prop)))))

(defun read-complex-value--done ()
  "Validate buffer content and exit recursive edit."
  (interactive)
  (cond ((null read-complex-value--validator)
         (exit-recursive-edit))

        ((functionp read-complex-value--validator)
         (let ((buf (current-buffer))
               (validator read-complex-value--validator))
           (if (with-temp-buffer
                 (insert-buffer-substring buf)
                 (read-complex-value--prune-buffer)
                 (goto-char (point-min))
                 (funcall validator))
               (exit-recursive-edit)))))

  (when (or (null read-complex-value--validator)
            (funcall read-complex-value--validator))
    (exit-recursive-edit)))

(defun read-complex-value--abort ()
  "Abort the recursive edit."
  (interactive)
  (abort-recursive-edit))

(provide 'read-complex-value)

;;; read-complex-value.el ends here

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

[Augusto Stoffel]

On Wed,  8 Mar 2023 at 15:19, Yuan Fu wrote:

> Orthogonal to Augusto’s function, but I think something like this
> would be nice: a function that pops up a buffer and enters recursive
> edit for arbitrary input and edit, and when you hit C-c C-c, it
> returns the buffer content, kind of like Magit’s commit buffer. Plus
> buffer content validator (eg, validate JSON), and arbitrary major
> modes in the buffer, etc.

This sounds like a generally useful thing for Emacs.  There should be a
version without recursive edit which calls a callback function when
quitting.

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

[Augusto Stoffel]

>> The utility function belongs to map.el.  It is called `assoc-in` in
>> Clojure.
>
> Yuri presented some pretty good arguments about how that would
> be a bad idea.  Also, not a Clojure expert, but AFAIK that
> function doesn't take dotted notation strings as input.

Good, let's not do it then.  In any case, just for fun and because it
could be useful in some other situation, I proposed in bug#62068 the
suitable additions to map.el.  Then the conversion we were discussing
looks like this:

(defun dotted-to-nested (items)
  (seq-reduce
   (pcase-lambda (map `(,ks . ,v))
     (map-insert-in map
                    (mapcar 'intern (string-split ks "\\."))
                    v
                    'plist))
   (map-pairs items)
   nil))

(dotted-to-nested '("a.b.c" 1
                    "a.b.d" 2
                    "a.e.f" 3))
=> (a (e (f 3) b (d 2 c 1)))     [modulo bug#62067]

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

[João Távora]

On Wed, Mar 8, 2023 at 8:43 PM Augusto Stoffel <arstoffel@gmail.com> wrote:

> Of course you would need to combine it with split-string (and a
> dolist or seq-reduce to process a list of those dotted names).

:-)  and the kitchen sink to handle all the quirks...  I Yuri is just
right, there are too many problems in the general case, but in the LSP
case it's more tame, which explains why other editors manage to use
it al all.

> >> Speaking of bloat, and I know I shouldn't insist, but a basic version of
> >> the savable eglot-show-workspace-configuration barely adds 30 LOC.
> >
> > Your code has at least two big problems:
> >
> > * it takes the current value from one place and
> >   potentially saves it in another place.  This is asking
> >   for trouble.  I know you favour the 'nil' method exclusively
> >   for setting e-w-configuration, but it's not the only supported
> >   methods and there are configurations out in the wild that
> >   we can't break. Also note the that per-file or per-sub-hierarchy
> >   workspace configurations _are_supported by LSP (the scopeUri
> >   argument to the workspace/configuration server request).
>
> Right, this is a problem.  It's missing the part that will “not confuse
> the other 10% [of users] to death”, as you said.
>
> > * it doesn't take into account dir-local-set-class-variables
>
> This too.  Neither the possibility of e-w-c being a function.

Or the possibility of it being an '(eval ...)' form.  I think
that should make it 20% (I found a lot of eval when perusing
GitHub for .dir-locals.el examples).

> > These are exactly the type of edge cases that I don't want
> > to handle in Eglot.  In other words, Emacs has many variable
> > setting methods and making an Eglot function to oversimplify
> > them, even if it happens to work for an estimated majority of
> > cases, is a bad idea, simply because it will break a minority.
>
> Fair enough, but it seems that this multiplicity of methods basically
> precludes one from making a helper tool for configurations.

Of course not.  Just target the 90% and bail out for the 10%.
Usually, if a user has used dir-locals-set-class-variables,
probably has no trouble with editing dir-locals.

> > So I urge you to generalize your code and propose it here
> > in a new :core ELPA package.
>
> If you provide a function that receives a new configuration value and
> stores it back in the right place, then this package becomes trivial.

I think you misunderstood me.  i was proposing that you work
on that generic variable editing facility, and open up an API
for packages like Eglot to take advantage.  Start working
on it in, say, lisp/files-x.el and then later on we could
consider making it a :core ELPA package.

> If you don't, then this package is completely entangled with Eglot's
> logic for reading configs.  In either case this doesn't seem to make a
> lot of sense as a separate package.

I read your code and I even here I don't agree :-) There are
a couple of '--' references in there, but this is easy to overcome. And
Eglot cannot change that logic without breaking backward compatibility
so you're adhering to a published interface.  So even an
"eglot-edit-wconf" library would make sense as a GNU ELPA package.

João

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

[João Távora]

On Tue, Mar 7, 2023 at 11:57 AM João Távora <joaotavora@gmail.com> wrote:
>
> Yuan Fu <casouri@gmail.com> writes:
>
> >> 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.
>
> Thanks.  I think the most important part in your patch is to show me
> exactly the points in the manual's writing that are confusing.

Hi Yuan, I took some of your ideas and pushed a significant
overhaul of Eglot's manual, fleshing out a new
"Advanced server configuration" chapter.  Please have a look
and let me know what you think.  We can make more adjustments
to it.  I pushed this to emacs-29.

João

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

[Juri Linkov]

>> Orthogonal to Augusto’s function, but I think something like this
>> would be nice: a function that pops up a buffer and enters recursive
>> edit for arbitrary input and edit, and when you hit C-c C-c, it
>> returns the buffer content, kind of like Magit’s commit buffer. Plus
>> buffer content validator (eg, validate JSON), and arbitrary major
>> modes in the buffer, etc.
>
> This sounds like a generally useful thing for Emacs.  There should be a
> version without recursive edit which calls a callback function when
> quitting.

'read-string-from-buffer' was intended to do this by relying on
'string-edit'.  You could add a new function e.g. named
'read-expression-from-buffer' that does the same as
'read--expression' but using a buffer instead of the minibuffer.

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

[João Távora]

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

On Thu, Mar 9, 2023, 08:18 Augusto Stoffel <arstoffel@gmail.com> wrote:

> On Wed,  8 Mar 2023 at 15:19, Yuan Fu wrote:
>
> > Orthogonal to Augusto’s function, but I think something like this
> > would be nice: a function that pops up a buffer and enters recursive
> > edit for arbitrary input and edit, and when you hit C-c C-c, it
> > returns the buffer content, kind of like Magit’s commit buffer. Plus
> > buffer content validator (eg, validate JSON), and arbitrary major
> > modes in the buffer, etc.
>
> This sounds like a generally useful thing for Emacs.  There should be a
> version without recursive edit which calls a callback function when
> quitting.
>

Of course, that won't work as a drop-in replacement for the read-* family
that uses the minibuffer.

João

>

[-- Attachment #2: Type: text/html, Size: 1401 bytes --]

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

[Juri Linkov]

>     > Orthogonal to Augusto’s function, but I think something like this
>     > would be nice: a function that pops up a buffer and enters recursive
>     > edit for arbitrary input and edit, and when you hit C-c C-c, it
>     > returns the buffer content, kind of like Magit’s commit buffer. Plus
>     > buffer content validator (eg, validate JSON), and arbitrary major
>     > modes in the buffer, etc.
>
>     This sounds like a generally useful thing for Emacs.  There should be a
>     version without recursive edit which calls a callback function when
>     quitting.
>
> Of course, that won't work as a drop-in replacement for the read-* family
> that uses the minibuffer.

string-edit provides callback args, and
read-string-from-buffer uses recursive-edit
in these callbacks.

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

[Augusto Stoffel]

On Thu,  9 Mar 2023 at 20:05, Juri Linkov wrote:

>>     > Orthogonal to Augusto’s function, but I think something like this
>>     > would be nice: a function that pops up a buffer and enters recursive
>>     > edit for arbitrary input and edit, and when you hit C-c C-c, it
>>     > returns the buffer content, kind of like Magit’s commit buffer. Plus
>>     > buffer content validator (eg, validate JSON), and arbitrary major
>>     > modes in the buffer, etc.
>>
>>     This sounds like a generally useful thing for Emacs.  There should be a
>>     version without recursive edit which calls a callback function when
>>     quitting.
>>
>> Of course, that won't work as a drop-in replacement for the read-* family
>> that uses the minibuffer.
>
> string-edit provides callback args, and
> read-string-from-buffer uses recursive-edit
> in these callbacks.

This is very nice indeed!  It seems to be missing just one thing, which
is the ability to set a major mode in the popup buffer.  If I do M-x
js-json-mode in the string-edit buffer, the header line disappears and
C-c C-c gets unbound.

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

[Yuan Fu]

> On Mar 9, 2023, at 3:18 AM, João Távora <joaotavora@gmail.com> wrote:
> 
> On Tue, Mar 7, 2023 at 11:57 AM João Távora <joaotavora@gmail.com> wrote:
>> 
>> Yuan Fu <casouri@gmail.com> writes:
>> 
>>>> 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.
>> 
>> Thanks.  I think the most important part in your patch is to show me
>> exactly the points in the manual's writing that are confusing.
> 
> Hi Yuan, I took some of your ideas and pushed a significant
> overhaul of Eglot's manual, fleshing out a new
> "Advanced server configuration" chapter.  Please have a look
> and let me know what you think.  We can make more adjustments
> to it.  I pushed this to emacs-29.

This is much more fleshed out, and it looks great!

Yuan

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

[Yuan Fu]

> On Mar 9, 2023, at 9:20 AM, Juri Linkov <juri@linkov.net> wrote:
> 
>>> Orthogonal to Augusto’s function, but I think something like this
>>> would be nice: a function that pops up a buffer and enters recursive
>>> edit for arbitrary input and edit, and when you hit C-c C-c, it
>>> returns the buffer content, kind of like Magit’s commit buffer. Plus
>>> buffer content validator (eg, validate JSON), and arbitrary major
>>> modes in the buffer, etc.
>> 
>> This sounds like a generally useful thing for Emacs.  There should be a
>> version without recursive edit which calls a callback function when
>> quitting.
> 
> 'read-string-from-buffer' was intended to do this by relying on
> 'string-edit'.  You could add a new function e.g. named
> 'read-expression-from-buffer' that does the same as
> 'read--expression' but using a buffer instead of the minibuffer.

Of course Emacs has one built-in :-) I’ll see if I can make some improvement to the read-string-from-buffer functions. In particular, I think arbitrary setup function and validator would be useful additions.

Yuan

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

[João Távora]

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

On Fri, Mar 10, 2023, 06:26 Yuan Fu <casouri@gmail.com> wrote:

>
> > 'read-string-from-buffer' was intended to do this by relying on
> > 'string-edit'.  You could add a new function e.g. named
> > 'read-expression-from-buffer' that does the same as
> > 'read--expression' but using a buffer instead of the minibuffer.
>
> Of course Emacs has one built-in :-) I’ll see if I can make some
> improvement to the read-string-from-buffer functions. In particular, I
> think arbitrary setup function and validator would be useful additions.
>

If I'm following you correctly, also a serializer/deserializer function
pair, so the user can edit expressions in non-lisp syntax and still have
them stored as lisp values.

João

>

[-- Attachment #2: Type: text/html, Size: 1301 bytes --]

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

[João Távora]

Pedro Andres Aranda Gutierrez <paaguti@gmail.com> writes:

> Hi Joao,
>
> I've been looking at the write-eglot-manual-for-advanced-server-config
> branch in savannah and it looks great.

The documentation update is already commited to emacs-29.

>  My .2 cents to it is that would be great if you included something in
> the line of
>
> ----- cut here -------
> You can create a basic eglot configuration to use (by default) in most
> of your projects in your Emacs initialisation like below:
>
>   (setq-default eglot-workspace-configuration
>                 '(:pylsp
>                   (:configurationSources ["pycodestyle"]

Here, you're using eglot-workspace-configuration, a mechanism intended
for project-specific configuration (5.2 Project-specific
configuration), to effectively do user-specific configuration,
described in (5.1 User-specific configuration).

This indeed works, I've fixed the manual which previously said that
setting the variable globally "doesn't make sense".  It can be useful,
if you know what you're doing.

But I don't know if we should be recommending this over the use of
eglot-server-program + :initializationOptions as described in section
5.1 User-specific configuration.  Will see.

> In addition to this, it would also be nice to document a 'canonical'
> way to disable/customise the mouse code actions. If I use something,
> it's just the import organiser in Python... Disabling it, moving it to
> another binding would be great.

This is an unrelated issue which needs thinking about.  Make a bug
report and describe a reproduction for the problem you've been having.

João

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

[Michael Eliachevitch]

I suggest to also mention in the manual that json arrays should be represented
as vectors in square brackets.

I initially set an array variable as a simple lisp and got an error that the
first element is not a symbol, because it was interpreted as a plist key. This
took me a bit time to figure out and I didn't find it in the manual (if my
version is the up-to-date one). Just from saying that the json is represented
as a plist it's not clear to me that arrays are must be lisp
vectors, even though in hindsight it makes sense.

This came up in my TeXLab configuration for the :args parameter for the executable:

    (:texlab
        :build (:executable "latexmk"
                   :args ["-interaction=nonstopmode" "-f" "-output-directory=./build" "%f"]))

Other than that, I found the new documentation very clear, thanks a lot for that!

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

[João Távora]

On Tue, Mar 14, 2023 at 6:48 PM Michael Eliachevitch
<m.eliachevitch@posteo.de> wrote:
>
>
> I suggest to also mention in the manual that json arrays should be represented
> as vectors in square brackets.

OK, Can you submit a patch?  Bonus points if you add your :texlab example.

> This came up in my TeXLab configuration for the :args parameter for the executable:
>
>     (:texlab
>         :build (:executable "latexmk"
>                    :args ["-interaction=nonstopmode" "-f" "-output-directory=./build" "%f"]))
>
> Other than that, I found the new documentation very clear, thanks a lot for that!

Thanks! it wasn't easy to write, so I'm glad it helped.

João

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

[Michael Eliachevitch]

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


> OK, Can you submit a patch?  Bonus points if you add your :texlab example.

Here you go. This is my first Emacs patch and I hope it's fine like this as I'm not very experienced with this patch email workflow. Is it okay that I sent it in a reply as an attachment or should I have started a new thread for the patch?

In the patch I mention that arrays can be represented as vector datatypes and extend the existing advanced configuration :pylsp example with an array option. Further, the patch also fixes the indentation for the example.

Further, the patch introduces some changes to the punctuation before/after the configuration examples, because stylistically I think they should be considered part of the surrounding text. If you want I could make this a separate patch or you can revert those changes. I admit this is also personal preference, I have some personal opinions on that but they are not strong.

Initially I didn't know how to find the proper xref reference to vectors in the elisp manual, but luckily with some grepping I found another place where that manual section was referenced and just copied that xref (this is also my first time writing texinfo). I didn't rebuild the documentation yet but hope it will be fine.

The changes are  also described in the commit message in the patch.

Cheers, Michael


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Document-how-to-set-JSON-arrays-in-eglot-workspace-c.patch --]
[-- Type: text/x-patch, Size: 2813 bytes --]

From 8edbaae1c0d8605299c863f4e95c1f3d15b3d158 Mon Sep 17 00:00:00 2001
From: Michael Eliachevitch <m.eliachevitch@posteo.de>
Date: Tue, 14 Mar 2023 22:47:37 +0100
Subject: [PATCH] Document how to set JSON arrays in
 eglot-workspace-configuration

Many language server configuration options are lists of the JSON array
datatype, for example argument lists for executables. These can be
configured in emacs lisp as vectors. The eglot documentation talked
about confiring json as plists and introduced some basic json
datatypes, but didn't yet mention arrays, which this commit introduced.

* Other minor changes

- Align property lists in eglot documentation, so that keywords of the same level
  are aligned

- Slightly change punctuation before code example to better
  grammatically integrate the example code and the text.
---
 doc/misc/eglot.texi | 19 +++++++++++++------
 1 file changed, 13 insertions(+), 6 deletions(-)

diff --git a/doc/misc/eglot.texi b/doc/misc/eglot.texi
index 735da5f0163..cf4c1d5bcd1 100644
--- a/doc/misc/eglot.texi
+++ b/doc/misc/eglot.texi
@@ -1214,7 +1214,7 @@ supported.  It consists of @emph{globally} setting
 @code{eglot-workspace-configuration}, a variable originally intended
 for project-specific configuration.  This has the same effect as
 giving all your projects a certain default configuration, as described
-in @xref{Project-specific configuration}.  Here is an example.
+in @xref{Project-specific configuration}.  Here is an example:
 
 @lisp
 (setq-default eglot-workspace-configuration
@@ -1241,17 +1241,20 @@ keyword-value property sub-plists corresponding to JSON sub-objects.
 For representing the JSON leaf values @code{true}, @code{false},
 @code{null} and @code{@{@}}, you can use the Lisp values @code{t},
 @code{:json-false}, @code{nil}, and @code{eglot-@{@}}, respectively.
+JSON arrays are represented as lisp vectors surrounded by square brackets
+(@pxref{Vectors,,,elisp,GNU Emacs Lisp Reference Manual}).
 
-For example, this plist:
+For example, the plist
 
 @lisp
 (:pylsp (:plugins (:jedi_completion (:include_params t
-                                             :fuzzy t)
-                           :pylint (:enabled :json-false)))
+                                     :fuzzy t)
+                   :pylint (:enabled :json-false
+                            :args ["--disable" "C0103"])))
  :gopls (:usePlaceholders t))
 @end lisp
 
-Is serialized by Eglot to the following JSON text:
+is serialized by Eglot to the following JSON text:
 
 @example
 @{
@@ -1262,7 +1265,11 @@ Is serialized by Eglot to the following JSON text:
         "fuzzy": true
       @},
       "pylint": @{
-        "enabled": false
+        "enabled": false,
+        "args": [
+          "--disable",
+          "C0103"
+        ]
       @}
     @}
   @},
-- 
2.40.0

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

[Michael Eliachevitch]

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

Some additional comments to my documentation patch for json arrays as lisp vectors from the previous mail:

> I didn't rebuild the documentation yet but hope it will be fine.

I rebuild it with `make doc' now and the changes I added look fine. I attached the HTML build.

> and extend the existing advanced configuration :pylsp example with an array option

I changed the example only for the "5.3 JSONRPC objects in Elisp" section. But you use the same plist twice in the "5.1.1 Examples" section. I didn't add the json array option in those two cases to keep the examples short. But one might argue in favour of keeping all plist examples consistent and also in favor of introducing vectors in the examples as early as possible. Not sure if that would be better, I thought it might be good to mention this.


[-- Attachment #2: HTML build of the eglot texinfo manual --]
[-- Type: text/html, Size: 137391 bytes --]

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

[Eli Zaretskii]

> From: Michael Eliachevitch <m.eliachevitch@posteo.de>
> Cc: emacs-devel@gnu.org
> Date: Tue, 14 Mar 2023 22:27:00 +0000
> 
> --- a/doc/misc/eglot.texi
> +++ b/doc/misc/eglot.texi
> @@ -1214,7 +1214,7 @@ supported.  It consists of @emph{globally} setting
>  @code{eglot-workspace-configuration}, a variable originally intended
>  for project-specific configuration.  This has the same effect as
>  giving all your projects a certain default configuration, as described
> -in @xref{Project-specific configuration}.  Here is an example.
> +in @xref{Project-specific configuration}.  Here is an example:

@xref here is wrong: it produces a capitalized "See", so is only
appropriate at the beginning of a sentence.  You want @pxref instead.

>  @lisp
>  (:pylsp (:plugins (:jedi_completion (:include_params t
> -                                             :fuzzy t)
> -                           :pylint (:enabled :json-false)))
> +                                     :fuzzy t)
> +                   :pylint (:enabled :json-false
> +                            :args ["--disable" "C0103"])))
>   :gopls (:usePlaceholders t))
>  @end lisp
>  
> -Is serialized by Eglot to the following JSON text:
> +is serialized by Eglot to the following JSON text:

If you want to continue a sentence after @lisp, you need to have
@noindent before the text.

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

[Michael Eliachevitch]

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

Thanks Eli, I incorporated your comments into v2 of the patch attached below.

>>  giving all your projects a certain default configuration, as described
>> -in @xref{Project-specific configuration}.  Here is an example.
>> +in @xref{Project-specific configuration}.  Here is an example:
>
> @xref here is wrong: it produces a capitalized "See", so is only
> appropriate at the beginning of a sentence.  You want @pxref instead.

Good point. However, due to the "as described" above, I think it should just be a @ref instead. I also found a wrong @xref  inside a sentence in line 1201 of eglot.texi, which I now also replaced by @pxref v2 of my patch.

> If you want to continue a sentence after @lisp, you need to have
> @noindent before the text.

Thanks, also incorporated that.

Cheers, Michael


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: v2 of patch that documents how to represent json arrays as vectors in eglot/jsonrpc --]
[-- Type: text/x-patch, Size: 3200 bytes --]

From 4cbaa88d2a19cc59e727efd35ba17facdc36b01e Mon Sep 17 00:00:00 2001
From: Michael Eliachevitch <m.eliachevitch@posteo.de>
Date: Tue, 14 Mar 2023 22:47:37 +0100
Subject: [PATCH v2] Document how to set JSON arrays in
 eglot-workspace-configuration

Many language server configuration options are lists of the JSON array
datatype, for example argument lists for executables. These can be
configured in emacs lisp as vectors. The eglot documentation talked
about confiring json as plists and introduced some basic json
datatypes, but didn't yet mention arrays, which this commit introduced.

* Other minor changes

- Align property lists in eglot documentation, so that keywords of the same level
  are aligned

- Slightly change punctuation before code example to better
  grammatically integrate the example code and the text.
---
 doc/misc/eglot.texi | 22 +++++++++++++++-------
 1 file changed, 15 insertions(+), 7 deletions(-)

diff --git a/doc/misc/eglot.texi b/doc/misc/eglot.texi
index 735da5f0163..d6c43c8ac02 100644
--- a/doc/misc/eglot.texi
+++ b/doc/misc/eglot.texi
@@ -1201,7 +1201,7 @@ User-specific configuration
 The argument @code{(:compilationDatabasePath "/tmp")} is Emacs's
 representation in plist format of a simple JSON object
 @code{@{"compilationDatabasePath": "/tmp"@}}.  To learn how to
-represent more deeply nested options in this format, @xref{JSONRPC
+represent more deeply nested options in this format, @pxref{JSONRPC
 objects in Elisp}.
 
 In this case, the two examples achieve exactly the same, but notice
@@ -1214,7 +1214,7 @@ User-specific configuration
 @code{eglot-workspace-configuration}, a variable originally intended
 for project-specific configuration.  This has the same effect as
 giving all your projects a certain default configuration, as described
-in @xref{Project-specific configuration}.  Here is an example.
+in @ref{Project-specific configuration}.  Here is an example:
 
 @lisp
 (setq-default eglot-workspace-configuration
@@ -1241,17 +1241,21 @@ JSONRPC objects in Elisp
 For representing the JSON leaf values @code{true}, @code{false},
 @code{null} and @code{@{@}}, you can use the Lisp values @code{t},
 @code{:json-false}, @code{nil}, and @code{eglot-@{@}}, respectively.
+JSON arrays are represented as lisp vectors surrounded by square brackets
+(@pxref{Vectors,,,elisp,GNU Emacs Lisp Reference Manual}).
 
-For example, this plist:
+For example, the plist
 
 @lisp
 (:pylsp (:plugins (:jedi_completion (:include_params t
-                                             :fuzzy t)
-                           :pylint (:enabled :json-false)))
+                                     :fuzzy t)
+                   :pylint (:enabled :json-false
+                            :args ["--disable" "C0103"])))
  :gopls (:usePlaceholders t))
 @end lisp
 
-Is serialized by Eglot to the following JSON text:
+@noindent
+is serialized by Eglot to the following JSON text:
 
 @example
 @{
@@ -1262,7 +1266,11 @@ JSONRPC objects in Elisp
         "fuzzy": true
       @},
       "pylint": @{
-        "enabled": false
+        "enabled": false,
+        "args": [
+          "--disable",
+          "C0103"
+        ]
       @}
     @}
   @},
-- 
2.40.0

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

[João Távora]

Michael Eliachevitch <m.eliachevitch@posteo.de> writes:

> Thanks Eli, I incorporated your comments into v2 of the patch attached
> below.

Thanks Michael and Eli.

I'll push the patch soon it with a

  Copyright-paperwork-exempt: Yes

cookie, since this seems to fall under the "trivial" basket, but you
should probably get a FSF copyright assignment for future contributions.

Minor comments below.


>  (setq-default eglot-workspace-configuration
> @@ -1241,17 +1241,21 @@ JSONRPC objects in Elisp
>  For representing the JSON leaf values @code{true}, @code{false},
>  @code{null} and @code{@{@}}, you can use the Lisp values @code{t},
>  @code{:json-false}, @code{nil}, and @code{eglot-@{@}}, respectively.
> +JSON arrays are represented as lisp vectors surrounded by square
>  brackets

"Lisp" should be capitalized (pedantically, "Elisp", since vectors in
other dialects have different read syntax, but Lisp is fine)


>  (:pylsp (:plugins (:jedi_completion (:include_params t
> -                                             :fuzzy t)
> -                           :pylint (:enabled :json-false)))
> +                                     :fuzzy t)
> +                   :pylint (:enabled :json-false
> +                            :args ["--disable" "C0103"])))

Hmmm.  I don't use "pylint" but what sense does it make to disable it
entirely (supposedly, that's what :enabled :json-false does) and then
_also_ pass args to it.  Should we just enable it?  This is all pretend,
of course.  But shouldn't it make more sense?

João

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

[Michael Eliachevitch]

[-- Attachment #1.1: Type: text/plain, Size: 2510 bytes --]


> Hmmm.  I don't use "pylint" but what sense does it make to disable it
> entirely (supposedly, that's what :enabled :json-false does) and then
> _also_ pass args to it.  Should we just enable it?  This is all pretend,
> of course.  But shouldn't it make more sense?

Ooops. I had simply looked through the available pylsp options [1] seeing which are of array type and would fit into the example plist that we already have. But you're right it doesn't make much sense here [2].

Instead, I would prefer to set some other array option from [1]. There are many more plugin options, but most of them are better set in python project configuration files (including the earlier pylint args), so personally I never use them.

In the now attached patch v3 I set `pylsp.plugins.jedi_completion.cache_for', as we already have a :jedi_completion key (and it's enabled). By default it caches ["pandas", "numpy", "tensorflow", "matplotlib"]. One might want to extend the default list, but to keep the example short I just set it to a subset of the default. What do you think about that?

[1]: See https://github.com/python-lsp/python-lsp-server/blob/develop/CONFIGURATION.md

[2]: When I'm pedantic (:pylint (:enabled :json-false)) also doesn't do anything since pylint is disabled by default, but I see some value in being explicit so I think for an example it's fine.

> "Lisp" should be capitalized (pedantically, "Elisp", since vectors in
> other dialects have different read syntax, but Lisp is fine)

In the patch below I use "Elisp vectors" now.

I would be fine with you editing the patch if you find some minor things to improve or have a better idea for the example. Git commits can have co-authors (this is what github does when you accept suggestions from reviewers), but not sure how the typical workflows are on emacs-devel (I just recently joined to keep up-to-date with recent developments). Or should the patch submitter must aggregate all suggestions into a final patch themselves?

> I'll push the patch soon it with a
>
>   Copyright-paperwork-exempt: Yes
>
> cookie, since this seems to fall under the "trivial" basket, but you
> should probably get a FSF copyright assignment for future contributions.

I'll try that soon. This patch changes just a couple of lines of documentation, so I hope it's fine for now. Slowly I'm figuring out this mailing list workflow and with the copyright assignment, there would be no hurdles for larger contributions to Emacs in the future :)

Michael Eliachevitch


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1.2: v3 of patch for eglot jsonrpc array documentation --]
[-- Type: text/x-patch, Size: 3348 bytes --]

From d7a083c791a8a09db2f6a67603816c92baa9b690 Mon Sep 17 00:00:00 2001
From: Michael Eliachevitch <m.eliachevitch@posteo.de>
Date: Tue, 14 Mar 2023 22:47:37 +0100
Subject: [PATCH v3] Document how to set JSON arrays in
 eglot-workspace-configuration

Many language server configuration options are lists of the JSON array
datatype, for example argument lists for executables. These can be
configured in emacs lisp as vectors. The eglot documentation talked
about confiring json as plists and introduced some basic json
datatypes, but didn't yet mention arrays, which this commit
introduced.

Other changes

* Align property lists in eglot documentation, so that keywords of the
  same level are aligned

* Slightly change punctuation before code example to better
  grammatically integrate the example code and the text.
---
 doc/misc/eglot.texi | 22 +++++++++++++++-------
 1 file changed, 15 insertions(+), 7 deletions(-)

diff --git a/doc/misc/eglot.texi b/doc/misc/eglot.texi
index 735da5f0163..d3d4337af89 100644
--- a/doc/misc/eglot.texi
+++ b/doc/misc/eglot.texi
@@ -1201,7 +1201,7 @@ User-specific configuration
 The argument @code{(:compilationDatabasePath "/tmp")} is Emacs's
 representation in plist format of a simple JSON object
 @code{@{"compilationDatabasePath": "/tmp"@}}.  To learn how to
-represent more deeply nested options in this format, @xref{JSONRPC
+represent more deeply nested options in this format, @pxref{JSONRPC
 objects in Elisp}.
 
 In this case, the two examples achieve exactly the same, but notice
@@ -1214,7 +1214,7 @@ User-specific configuration
 @code{eglot-workspace-configuration}, a variable originally intended
 for project-specific configuration.  This has the same effect as
 giving all your projects a certain default configuration, as described
-in @xref{Project-specific configuration}.  Here is an example.
+in @ref{Project-specific configuration}.  Here is an example:
 
 @lisp
 (setq-default eglot-workspace-configuration
@@ -1241,17 +1241,21 @@ JSONRPC objects in Elisp
 For representing the JSON leaf values @code{true}, @code{false},
 @code{null} and @code{@{@}}, you can use the Lisp values @code{t},
 @code{:json-false}, @code{nil}, and @code{eglot-@{@}}, respectively.
+JSON arrays are represented as Elisp vectors surrounded by square brackets
+(@pxref{Vectors,,,elisp,GNU Emacs Lisp Reference Manual}).
 
-For example, this plist:
+For example, the plist
 
 @lisp
 (:pylsp (:plugins (:jedi_completion (:include_params t
-                                             :fuzzy t)
-                           :pylint (:enabled :json-false)))
+                                     :fuzzy t
+                                     :cache_for ["pandas" "numpy"]
+                   :pylint (:enabled :json-false))))
  :gopls (:usePlaceholders t))
 @end lisp
 
-Is serialized by Eglot to the following JSON text:
+@noindent
+is serialized by Eglot to the following JSON text:
 
 @example
 @{
@@ -1259,7 +1263,11 @@ JSONRPC objects in Elisp
     "plugins": @{
       "jedi_completion": @{
         "include_params": true,
-        "fuzzy": true
+        "fuzzy": true,
+        "cache_for": [
+          "pandas",
+          "numpy"
+        ],
       @},
       "pylint": @{
         "enabled": false
-- 
2.40.0


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 519 bytes --]

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

[João Távora]

Michael Eliachevitch <m.eliachevitch@posteo.de> writes:

> I would be fine with you editing the patch if you find some minor
> things to improve or have a better idea for the example. Git commits
> can have co-authors (this is what github does when you accept
> suggestions from reviewers), but not sure how the typical workflows
> are on emacs-devel (I just recently joined to keep up-to-date with
> recent developments). Or should the patch submitter must aggregate all
> suggestions into a final patch themselves?

Separate patches is fine, especially if your're proposing different
functional changes.  Big salads less fine, but also accepted.  I think
most commiters know how to split patches.  Here, I didn't because I was
lazy, and it's a very small change.

I've pushed your patch to Emacs 29 with a tweak to the commit message
and a whitespace change, so I didn't add "Co-authored-by: João Távora
<...>" like I sometimes do.

> I'll try that soon. This patch changes just a couple of lines of
> documentation, so I hope it's fine for now. Slowly I'm figuring out
> this mailing list workflow and with the copyright assignment, there
> would be no hurdles for larger contributions to Emacs in the future :)

It's just email: there's much less to figure out than people think.

João