GNU bug report logs - #58893
29.0.50; Feedback on Eglot manual

Previous Next

Full log

Message #14 received at 58893 <at> debbugs.gnu.org (full text, mbox):

From: João Távora <joaotavora <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Felician Nemeth <felician.nemeth <at> gmail.com>, 58893 <at> debbugs.gnu.org
Subject: Re: bug#58893: 29.0.50; Feedback on Eglot manual
Date: Wed, 2 Nov 2022 08:26:00 +0000

[Message part 1 (text/plain, inline)]

On Sun, Oct 30, 2022 at 10:31 AM Eli Zaretskii <eliz <at> gnu.org> wrote:
>
> > From: Felician Nemeth <felician.nemeth <at> 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.

[Message part 2 (text/html, inline)]

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.