From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Felician Nemeth Newsgroups: gmane.emacs.bugs Subject: bug#58893: 29.0.50; Feedback on Eglot manual Date: Sun, 30 Oct 2022 15:15:48 +0100 Message-ID: <87pme9iei3.fsf@betli.tmit.bme.hu> References: <874jvlk5pm.fsf@betli.tmit.bme.hu> <83o7ttfvto.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="38128"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux) Cc: 58893@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sun Oct 30 15:16:15 2022 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1op96j-0009hx-Ud for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 30 Oct 2022 15:16:14 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1op96b-0001bO-N5; Sun, 30 Oct 2022 10:16:05 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1op96Z-0001ZL-8f for bug-gnu-emacs@gnu.org; Sun, 30 Oct 2022 10:16:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1op96Z-0004Te-0C for bug-gnu-emacs@gnu.org; Sun, 30 Oct 2022 10:16:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1op96Y-00049D-Fp for bug-gnu-emacs@gnu.org; Sun, 30 Oct 2022 10:16:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Felician Nemeth Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 30 Oct 2022 14:16:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 58893 X-GNU-PR-Package: emacs Original-Received: via spool by 58893-submit@debbugs.gnu.org id=B58893.166713935815916 (code B ref 58893); Sun, 30 Oct 2022 14:16:02 +0000 Original-Received: (at 58893) by debbugs.gnu.org; 30 Oct 2022 14:15:58 +0000 Original-Received: from localhost ([127.0.0.1]:38802 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1op96U-00048d-Bb for submit@debbugs.gnu.org; Sun, 30 Oct 2022 10:15:58 -0400 Original-Received: from mail-ej1-f51.google.com ([209.85.218.51]:35739) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1op96S-00048R-5h for 58893@debbugs.gnu.org; Sun, 30 Oct 2022 10:15:57 -0400 Original-Received: by mail-ej1-f51.google.com with SMTP id k2so23702758ejr.2 for <58893@debbugs.gnu.org>; Sun, 30 Oct 2022 07:15:56 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=mime-version:face:user-agent:message-id:in-reply-to:date:references :subject:cc:to:from:from:to:cc:subject:date:message-id:reply-to; bh=a7/lYAQ8P0UFGTTS37wAb8i6ZQs+Db814rd6Jon6i4Q=; b=liFdtfZ2koCvce4p96SzlW8wLvvvHFw2l4IIJgSBEwBLm9JA9AYkP2ovNRQsGhs2LW Q+BKK0RcaXfa5zaBVsUvLdPrPjBFVHKZZuT+fXQujSNnGpqUCUI0WUz3oWWJHIitHliu ayqEokzB3/QTcOldr82/Q+Qf7ueTNmxD03L5a4bPiIJQPbnLhaM+uUYjPiOgNEzmeZpn ED+9Lfaz/Q7LFS2OUHXC/qu4qqldCDJTDUrTdn4Onvteylw1pn0vMGW1p5zypr4Ybzam 9c2FgBDME6QH7t9vAFbJ/M+LC5wU1aZjncqdxmFHs9McZ+W5QSHOKArJBvxzReRXXVta 5Akg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=mime-version:face:user-agent:message-id:in-reply-to:date:references :subject:cc:to:from:x-gm-message-state:from:to:cc:subject:date :message-id:reply-to; bh=a7/lYAQ8P0UFGTTS37wAb8i6ZQs+Db814rd6Jon6i4Q=; b=PSSqRRv80Ekn1lwJNatY2Z3J3sku7vlyEpXAQuoB0/d9QfDz6VkXOULs/0Sso0ik1B 9jikfPmNgmwlhTCSjSNOy5eMzRAZ513VzI8i47rkA/G1kd9mEo2qOSxZ7vQOre4jkosy 2Ejq1jjDUcF0tL3vHwymO4CJO5qMEIqfk/Dtz4ilhrBRqFMhs3Kgxhjb+6ghvHCxGz0p 5ke/kCZbZTOqrBqduF3JYQoIqC3399e3vLzf0Q+WFMC96NYFADetWQ73lvHm8+KLolaY 3ANEVG+TMaDJxEgVzt0oaKas2ihuW3b7LI0Q1K4XVYJIfxWt+77veInqxqgAvNePuUxX WgUQ== X-Gm-Message-State: ACrzQf1QsL61GkKa8ZYXn6e/SBJXhbwvC+/dv8AXynfhILXdoYNW8rZU QDZBEal6d6rcmPYzbJPsXIvZwQ+Rgyo= X-Google-Smtp-Source: AMsMyM6sdLkZUj8ildCKTLmccHspytt/9S+Y9YAY7uiY5sb39bWbKYsn1F9lqHIaqXBgyWPwt2LQdQ== X-Received: by 2002:a17:907:2c72:b0:7a4:a4b4:9fcb with SMTP id ib18-20020a1709072c7200b007a4a4b49fcbmr8381465ejc.403.1667139349920; Sun, 30 Oct 2022 07:15:49 -0700 (PDT) Original-Received: from betli.gmail.com (catv-86-101-66-128.catv.fixed.vodafone.hu. [86.101.66.128]) by smtp.gmail.com with ESMTPSA id f24-20020a17090631d800b007ad98918743sm1878602ejf.1.2022.10.30.07.15.49 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 30 Oct 2022 07:15:49 -0700 (PDT) In-Reply-To: <83o7ttfvto.fsf@gnu.org> (Eli Zaretskii's message of "Sun, 30 Oct 2022 12:29:55 +0200") Face: iVBORw0KGgoAAAANSUhEUgAAADAAAAAwBAMAAAClLOS0AAAAElBMVEWOdXElERN7LDLZs6/l 0dDQq6TepMcqAAACW0lEQVQ4jWWSzY7bMAyEaSm6mypylxjkroTRvUW8d9lavf+r7NDOZotWQHzg lyGHP0Sn5ed9qKrLWWIWos9/QJWIeCSywPNTd/AE0LtwFj7A+3WT5PwfeBrQKcsBnkfwVcNySWQr 3i34XN6gRNgis/v4uwSKHCD9lPitB0Aq9BHfHX4cgsI7cJJfLdZg/4bbCzoRmkD9MsagQSBDedZi CgNxkVSJmSOStTBUBKkywEnEoZzbwWj+ACiVJkF6pOpak2PMCqkMYDpaw+gatLR8atMOrB3JGzmm 3rSQo+tkxU+UAbhQSgtslULhsXKk6+IyQ1QTzeQB0MzjlpkCEUCeUdviWrwBcxVqpZjP+v0MYPA0 aq2rvIEZe4GRM0v+9QIB03rsABVSk5y+Mz3LSzExtJLlCCO6dV1uzDQFTBad+gO0TqqL9XE8x4ek +orvYiMJgzC8e+r6TqaPaK6QyqVNvoHtsRrooQ6tTi4vgaSkd8wIikodB3B0iIk58avsDdYNajpS bSKJ+mQnipGszB6zW4lGgsOkKHE2RWVcBpwhaIv3BYIAu3WsnC7YYKLRchp6w8fRGZIWiZuFsVai 7gbcUcJEhiDZ3K1+uzZvBlfaEO8oH4MLu6/hrKVM7QpQcIXJFuC1XjfbfKRxNslk94l9cYcEihV2 HWyNDQAXaLsvnrSyp7HaQhrAn13V6/XW11nh0XINBOEAV+tHK4EvAGNGvEwc0eZw8Vyr56imYEsV sOW9jxm/yb9AH1ufqGMviIK7A0Tc/723oM3tJ4HTOu9gDr3ftbdkxfdjsUv5AqWKwyfCYo5WAAAA AElFTkSuQmCC X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: "bug-gnu-emacs" Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:246625 Archived-At: 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 writes: >> From: Felician Nemeth >> 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.