bug#58894: Comments on Eglot manual

bug#58894: Comments on Eglot manual

[Augusto Stoffel]

Find below some comments on the "Customizing Eglot" section of the manual:

> [...] via the variable ‘eglot-workspace-configuration’.  Eglot sends the
> portion of the settings contained in this variable to each server for
> which such settings were defined in the variable.

This is not true.  The entire `eglot-workspace-configuration' is sent to
the server; presumably, severs ignore everything which is not under its
own prefix, but that's just a convention.

> JSON values ‘true’, ‘false’, ‘null’ and ‘{}’ are represented by the
> Lisp values ‘t’, ‘:json-false’, ‘nil’, and ‘eglot-{}’, respectively.

Unless something has been renamed recently, it's `eglot--{}', not
`eglot-{}'.

>    Alternatively, the same configuration could be defined as follows:
> 
>      ((nil
>        . ((eglot-workspace-configuration
>            . (:pylsp (:plugins (:jedi_completion (:include_params t
>                                                   :fuzzy t)
>                                 :pylint (:enabled :json-false)))
>               :gopls (:usePlaceholders t))))))

This is more or less obvious, if you know how dir-local variables work.
So I would suggest mentioning a different configuration method:

Alternatively, you can set a default workspace configuration globally by
adding the following to your init file:

       (setq-default
         eglot-workspace-configuration
         '(:pylsp (:plugins (:jedi_completion (:include_params t
                                               :fuzzy t)
                             :pylint (:enabled :json-false)))
           :gopls (:usePlaceholders t))



>    This is an equivalent setup which sets the value for all the
> major-modes inside the project; Eglot will use for each server only the
> section of the parameters intended for that server.

Again, this is not true.  Rather, each sever will presumably ignore any
settings not under its own "namespace".

bug#58894: Comments on Eglot manual

[Eli Zaretskii]

> From: Augusto Stoffel <arstoffel@gmail.com>
> Date: Sun, 30 Oct 2022 12:05:27 +0100
> 
> Find below some comments on the "Customizing Eglot" section of the manual:
> 
> > [...] via the variable ‘eglot-workspace-configuration’.  Eglot sends the
> > portion of the settings contained in this variable to each server for
> > which such settings were defined in the variable.
> 
> This is not true.  The entire `eglot-workspace-configuration' is sent to
> the server; presumably, severs ignore everything which is not under its
> own prefix, but that's just a convention.
> 
> > JSON values ‘true’, ‘false’, ‘null’ and ‘{}’ are represented by the
> > Lisp values ‘t’, ‘:json-false’, ‘nil’, and ‘eglot-{}’, respectively.
> 
> Unless something has been renamed recently, it's `eglot--{}', not
> `eglot-{}'.
> 
> >    Alternatively, the same configuration could be defined as follows:
> > 
> >      ((nil
> >        . ((eglot-workspace-configuration
> >            . (:pylsp (:plugins (:jedi_completion (:include_params t
> >                                                   :fuzzy t)
> >                                 :pylint (:enabled :json-false)))
> >               :gopls (:usePlaceholders t))))))
> 
> This is more or less obvious, if you know how dir-local variables work.
> So I would suggest mentioning a different configuration method:
> 
> Alternatively, you can set a default workspace configuration globally by
> adding the following to your init file:
> 
>        (setq-default
>          eglot-workspace-configuration
>          '(:pylsp (:plugins (:jedi_completion (:include_params t
>                                                :fuzzy t)
>                              :pylint (:enabled :json-false)))
>            :gopls (:usePlaceholders t))
> 
> 
> 
> >    This is an equivalent setup which sets the value for all the
> > major-modes inside the project; Eglot will use for each server only the
> > section of the parameters intended for that server.
> 
> Again, this is not true.  Rather, each sever will presumably ignore any
> settings not under its own "namespace".

João, any comments?

bug#58894: Comments on Eglot manual

[João Távora]

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

Hello, my comments:

On Thu, Nov 3, 2022, 13:51 Eli Zaretskii <eliz@gnu.org> wrote:

> > From: Augusto Stoffel .
> >
> > This is not true.  The entire `eglot-workspace-configuration' is sent to
> > the server; presumably, severs ignore everything which is not under its
> > own prefix, but that's just a convention.
>

Augusto is correct. His phrasing is acceptably clear for the manual imo.

> > JSON values ‘true’, ‘false’, ‘null’ and ‘{}’ are represented by the
> > > Lisp values ‘t’, ‘:json-false’, ‘nil’, and ‘eglot-{}’, respectively.
> >
> > Unless something has been renamed recently, it's `eglot--{}', not
> > `eglot-{}'.
>

Something has been renamed recently. eglot--{} is an alias.

> >    Alternatively, the same configuration could be defined as follows:
> > >
> > >      ((nil
> > >        . ((eglot-workspace-configuration
> > >            . (:pylsp (:plugins (:jedi_completion (:include_params t
> > >                                                   :fuzzy t)
> > >                                 :pylint (:enabled :json-false)))
> > >               :gopls (:usePlaceholders t))))))
> >
> > This is more or less obvious, if you know how dir-local variables work.
>

Many people don't, judging from a substantial amount of interactions on
this topic.

> So I would suggest mentioning a different configuration method:
> >
> > Alternatively, you can set a default workspace configuration globally by
> > adding the following to your init file:
> >
> >        (setq-default
> >          eglot-workspace-configuration
> >          '(:pylsp (:plugins (:jedi_completion (:include_params t
> >                                                :fuzzy t)
> >                              :pylint (:enabled :json-false)))
> >            :gopls (:usePlaceholders t))
>

This is purposedly not mentioned because it is not recommended and
confusing. Workspace settings are project-specific by definition. Your idea
probably works, but is better implemented as initializationOptions,
command-line switches or other means of configuring the server
independently of the workspace it is meant to operate on.

> >    This is an equivalent setup which sets the value for all the
> > > major-modes inside the project; Eglot will use for each server only the
> > > section of the parameters intended for that server.
> >
> > Again, this is not true.  Rather, each sever will presumably ignore any
> > settings not under its own "namespace".
>

Yes, that is the correct idea.

João, any comments?
>

See above.

Also, I think this information should migrate to a separate sub-section,
alongside a sub-section devoted to the "workspace folders" topic.

João

>

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

bug#58894: Comments on Eglot manual

[Eli Zaretskii]

> From: João Távora <joaotavora@gmail.com>
> Date: Thu, 3 Nov 2022 16:08:41 +0000
> Cc: Augusto Stoffel <arstoffel@gmail.com>, 58894@debbugs.gnu.org
> 
> Hello, my comments:
> 
> On Thu, Nov 3, 2022, 13:51 Eli Zaretskii <eliz@gnu.org> wrote:
> 
>  > From: Augusto Stoffel .
>  > 
>  > This is not true.  The entire `eglot-workspace-configuration' is sent to
>  > the server; presumably, severs ignore everything which is not under its
>  > own prefix, but that's just a convention.
> 
> Augusto is correct. His phrasing is acceptably clear for the manual imo.
> 
>  > > JSON values ‘true’, ‘false’, ‘null’ and ‘{}’ are represented by the
>  > > Lisp values ‘t’, ‘:json-false’, ‘nil’, and ‘eglot-{}’, respectively.
>  > 
>  > Unless something has been renamed recently, it's `eglot--{}', not
>  > `eglot-{}'.
> 
> Something has been renamed recently. eglot--{} is an alias.
> 
>  > >    Alternatively, the same configuration could be defined as follows:
>  > > 
>  > >      ((nil
>  > >        . ((eglot-workspace-configuration
>  > >            . (:pylsp (:plugins (:jedi_completion (:include_params t
>  > >                                                   :fuzzy t)
>  > >                                 :pylint (:enabled :json-false)))
>  > >               :gopls (:usePlaceholders t))))))
>  > 
>  > This is more or less obvious, if you know how dir-local variables work.
> 
> Many people don't, judging from a substantial amount of interactions on this topic.
> 
>  > So I would suggest mentioning a different configuration method:
>  > 
>  > Alternatively, you can set a default workspace configuration globally by
>  > adding the following to your init file:
>  > 
>  >        (setq-default
>  >          eglot-workspace-configuration
>  >          '(:pylsp (:plugins (:jedi_completion (:include_params t
>  >                                                :fuzzy t)
>  >                              :pylint (:enabled :json-false)))
>  >            :gopls (:usePlaceholders t))
> 
> This is purposedly not mentioned because it is not recommended and confusing. Workspace settings are
> project-specific by definition. Your idea probably works, but is better implemented as initializationOptions,
> command-line switches or other means of configuring the server independently of the workspace it is meant
> to operate on.
> 
>  > >    This is an equivalent setup which sets the value for all the
>  > > major-modes inside the project; Eglot will use for each server only the
>  > > section of the parameters intended for that server.
>  > 
>  > Again, this is not true.  Rather, each sever will presumably ignore any
>  > settings not under its own "namespace".
> 
> Yes, that is the correct idea.
> 
>  João, any comments?
> 
> See above. 

Thanks, I fixed the wording regarding sending of the settings.

> Also, I think this information should migrate to a separate sub-section, alongside a sub-section devoted to the
> "workspace folders" topic.

The eglot-workspace-configuration settings are an important part of
the Eglot customization, so I don't see why we should move that into a
separate section.  It sounds unnatural to me.

I consider this bug done, so I'm closing it.

Thanks for the feedback.