bug#58893: 29.0.50; Feedback on Eglot manual

bug#58893: 29.0.50; Feedback on Eglot manual

[Felician Nemeth]

All in all, I think the new eglot.texi is really informative.
Nevertheless, having reread Eglot's github page, I've found some
information that's missing from the manual.  Maybe it's worth including
some of them to the manual.

* Missing commands

I'm not sure whether it is necessary to document all the commands
defined by Eglot, but the manual mentions xref-find-definitions, so
probably it should call the reader's attention to
eglot-find-declaration, eglot-find-implementation,
eglot-find-typeDefinition, and xref-find-references as well.


* WorkspaceFolders

The LSP protocol supports multiple workspace folders.  Eglot relies on
project-external-roots to get the additional folders (besides
project-root).  This is not mentioned in the manual.  However, (info
"(emacs)Projects") doesn't talk about how the user should configure
these external roots.

Maybe a simple solution is to rework the relevant part from NEWS.md into
the eglot.texi. NEWS.md has this:

   Eglot now advertises project-root and project-external-roots as
   workspace-folders. (Configuring tags-table-list sets the external
   roots of a simple git project.)


* Snippet completion

Yasnippet should be enabled in the current buffer before Eglot connects
to the LSP server.


Thanks.

bug#58893: 29.0.50; Feedback on Eglot manual

[Eli Zaretskii]

> From: Felician Nemeth <felician.nemeth@gmail.com>
> Date: Sun, 30 Oct 2022 10:42:45 +0100
> 
> I'm not sure whether it is necessary to document all the commands
> defined by Eglot, but the manual mentions xref-find-definitions, so
> probably it should call the reader's attention to
> eglot-find-declaration, eglot-find-implementation,
> eglot-find-typeDefinition, and xref-find-references as well.

Xref-related Eglot features are already mentioned in the Emacs user
manual, where Xref is described.  Eglot is documented there as an
additional backend for Xref.  I think that's the right place for that
to be documented.

The Eglot-specific commands you mention are AFAIU direct calls to the
Eglot's Xref backend, so why do we need to describe them in the
manual, when Xref itself is already described?

> * WorkspaceFolders
> 
> The LSP protocol supports multiple workspace folders.  Eglot relies on
> project-external-roots to get the additional folders (besides
> project-root).  This is not mentioned in the manual.  However, (info
> "(emacs)Projects") doesn't talk about how the user should configure
> these external roots.
> 
> Maybe a simple solution is to rework the relevant part from NEWS.md into
> the eglot.texi. NEWS.md has this:
> 
>    Eglot now advertises project-root and project-external-roots as
>    workspace-folders. (Configuring tags-table-list sets the external
>    roots of a simple git project.)

I'm not sure what exactly are you proposing to mention in the manual
in this respect.  If we are going to add the description of how to add
directories to a project, then yes, Eglot should be mentioned there
(but only in passing, IMO, since Eglot follows the project settings
automatically, AFAIU).  But as long as we don't have such a
description in the manual, how can we say anything in this respect
about Eglot?

> * Snippet completion
> 
> Yasnippet should be enabled in the current buffer before Eglot connects
> to the LSP server.

That's a detail best left for README's, in particular that of
Yasnippet, IMO.  The manual mentions Yasnippet as an optional package,
and leaves it at that, because it really isn't TRT to start describing
unbundled packages in our manuals.

Thanks.

bug#58893: 29.0.50; Feedback on Eglot manual

[Felician Nemeth]

I wanted to raise these topics, but if you think these are non-issues,
then I'm OK with closing this bug report.  I continue in-line.

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Felician Nemeth <felician.nemeth@gmail.com>
>> Date: Sun, 30 Oct 2022 10:42:45 +0100
>> 
>> I'm not sure whether it is necessary to document all the commands
>> defined by Eglot, but the manual mentions xref-find-definitions, so
>> probably it should call the reader's attention to
>> eglot-find-declaration, eglot-find-implementation,
>> eglot-find-typeDefinition, and xref-find-references as well.
>
> Xref-related Eglot features are already mentioned in the Emacs user
> manual, where Xref is described.  Eglot is documented there as an
> additional backend for Xref.  I think that's the right place for that
> to be documented.
>
> The Eglot-specific commands you mention are AFAIU direct calls to the
> Eglot's Xref backend, so why do we need to describe them in the
> manual, when Xref itself is already described?

For completeness and discoverability.  eglot.texi documents all the
elgot-code-action-* commands as well.  But the users can bump into these
commands with M-x eglot- TAB, and eglot-menu has these as well.  So
maybe these commands can be omitted from the manual.

>> * WorkspaceFolders
>> 
>> The LSP protocol supports multiple workspace folders.  Eglot relies on
>> project-external-roots to get the additional folders (besides
>> project-root).  This is not mentioned in the manual.  However, (info
>> "(emacs)Projects") doesn't talk about how the user should configure
>> these external roots.
>> 
>> Maybe a simple solution is to rework the relevant part from NEWS.md into
>> the eglot.texi. NEWS.md has this:
>> 
>>    Eglot now advertises project-root and project-external-roots as
>>    workspace-folders. (Configuring tags-table-list sets the external
>>    roots of a simple git project.)
>
> I'm not sure what exactly are you proposing to mention in the manual
> in this respect.  If we are going to add the description of how to add
> directories to a project, then yes, Eglot should be mentioned there
> (but only in passing, IMO, since Eglot follows the project settings
> automatically, AFAIU).  But as long as we don't have such a
> description in the manual, how can we say anything in this respect
> about Eglot?

We can add a few sentences to the "Buffers, Projects, and Eglot" part of
eglot.texi.  Here is my initial attempt:


diff --git a/doc/misc/eglot.texi b/doc/misc/eglot.texi
index 5a20028702..3fe0fe4518 100644
--- a/doc/misc/eglot.texi
+++ b/doc/misc/eglot.texi
@@ -519,6 +519,13 @@ Eglot and Buffers
 e.g.@: a VCS repository (@pxref{Version Control,,, emacs, GNU Emacs
 Manual}).
 
+@item
+A multi-directory project: if a project has set
+@code{project-external-roots}, then Eglot advertises these additional
+directories to the LSP server as extra workspace folders.  (For a
+simple VC project, @code{project-external-roots} is derived from
+@code{tags-table-list}).
+
 @item
 An EDE project: source files in a directory hierarchy managed via the
 Emacs Development Environment (@pxref{EDE,,, emacs, GNU Emacs


>> * Snippet completion
>> 
>> Yasnippet should be enabled in the current buffer before Eglot connects
>> to the LSP server.
>
> That's a detail best left for README's, in particular that of
> Yasnippet, IMO.  The manual mentions Yasnippet as an optional package,
> and leaves it at that, because it really isn't TRT to start describing
> unbundled packages in our manuals.

Usually, it is enough to enable yasnippet right before the user wants to
have a snippet completion.  However, the LSP server sends snippet-based
completion items only if yasnippet is already enabled when Eglot first
communicates with the LSP server.  But once again, maybe this is
straightforward and an uninteresting detail.  Or maybe this is enough to
clarify the situation:

-insertion of code templates (snippets), is installed, and the language
+insertion of code templates (snippets), is installed and enabled, and the language


Thank you.

bug#58893: 29.0.50; Feedback on Eglot manual

[João Távora]

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

On Sun, Oct 30, 2022 at 10:31 AM Eli Zaretskii <eliz@gnu.org> wrote:
>
> > From: Felician Nemeth <felician.nemeth@gmail.com>

> The Eglot-specific commands you mention are AFAIU direct calls to the
> Eglot's Xref backend, so why do we need to describe them in the
> manual, when Xref itself is already described?

I think what Felicián may be hinting at, and I agree, is that Eglot is
Emacs's identifiable frontend to "code intelligence" features for
many new users.  We observed this many times. Users almost never know
anything about Xref, Flymake, Eldoc, etc and these facilities.  Rather they
think
it's Eglot that it "does" the definition-finding, diagnostics, documentation
 respectively. This is not technically correct, and we do clarify it to
those
users, but it is also not at all unreasonable for a new user.

Also many new users com from the lsp-mode package where these things
are effectively all "done" by the package.

The former README went to lengths to give visibility to them,
and it was quite effective.  This is not entirely lost in the new manual,
but is much less obvious.

I understand both points of view, though.  Perhaps the solution is
to more prominently advertise the Xref, the Flymake and the Eldoc
manuals (and Eglot's  of course) in some "Emacs IDE tutorial manual".

> I'm not sure what exactly are you proposing to mention in the manual
> in this respect.  If we are going to add the description of how to add
> directories to a project, then yes, Eglot should be mentioned there
> (but only in passing, IMO, since Eglot follows the project settings
> automatically, AFAIU).

Yes, I think Felicián's idea makes sense.  There's already a part of
a manual about workspace folders in the descriptino of
eglot-workspace-configuration.

But it should really be brought into a dedicated section about LSP
workspace
folders and Eglot's translation of Emacs abstractions to them.  This a
common pain point for many users, and they have to be able to look
it up quickly.

> > * Snippet completion
> >
> > Yasnippet should be enabled in the current buffer before Eglot connects
> > to the LSP server.

Felicián, are you sure?  If that's true, then I think it's a bug.  I don't
want users
to have to remember this.  So I think the current gist "just install
yasnippet"
should be enough.

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

bug#58893: 29.0.50; Feedback on Eglot manual

[Felician Nemeth]

>> > * Snippet completion
>> >
>> > Yasnippet should be enabled in the current buffer before Eglot connects
>> > to the LSP server.
>
> Felicián, are you sure?  If that's true, then I think it's a bug.  I
> don't want users to have to remember this.  So I think the current
> gist "just install yasnippet" should be enough.

Eglot does not enable yasnippet mode anywhere.
eglot--snippet-expansion-fn only checks whether
yas-minor-mode/yas-global-mode is enabled.

So if it is considered as a bug, then I think the fix is to make
eglot--snippet-expansion-fn and eglot--managed-mode turn yas-minor-mode
on when it is available and yasnippet is not in eglot-stay-out-of.