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.