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.