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.