bug#67870: 29.1; Eglot missing or un-findable advertised feature

bug#67870: 29.1; Eglot missing or un-findable advertised feature

[Dave Abrahams]

The info page for Eglot says:

3.1 Eglot features:

   • On-the-fly diagnostic annotations with server-suggested fixes, via
     the Flymake package (*note (flymake)Top::).  

But I can find no evidence of the support for server-suggested fixes
either in flymake or in eglot itself.  I am working with an LSP server
that offers fix-its but can't find any way to apply them.

Either what's meant by this should be clarified, leading to discoverable
instructions for exploiting the feature, or the text should be removed.


In GNU Emacs 29.1 (build 1, x86_64-apple-darwin23.1.0, Carbon Version
170 AppKit 2487.2) of 2023-12-13 built on DaveMBP16.localdomain
Windowing system distributor 'Apple Inc.', version 14.2.0
System Description:  macOS 14.2

Configured using:
'configure --enable-locallisppath=/usr/local/share/emacs/site-lisp
--infodir=/usr/local/Cellar/emacs-mac/emacs-29.1-mac-10.0/share/info
--mandir=/usr/local/Cellar/emacs-mac/emacs-29.1-mac-10.0/share/man
--prefix=/usr/local/Cellar/emacs-mac/emacs-29.1-mac-10.0 --with-mac
--enable-mac-app=/usr/local/Cellar/emacs-mac/emacs-29.1-mac-10.0
--with-gnutls --with-modules --with-native-compilation
--with-tree-sitter 'CFLAGS=-I/usr/local/opt/gcc/include
-I/usr/local/opt/libgccjit/include' 'LDFLAGS=-L/usr/local/lib/gcc/13
-I/usr/local/opt/gcc/include -I/usr/local/opt/libgccjit/include''

Configured features:
ACL GMP GNUTLS JSON LIBXML2 MODULES NATIVE_COMP NOTIFY KQUEUE PDUMPER
SQLITE3 THREADS TOOLKIT_SCROLL_BARS TREE_SITTER XIM ZLIB

Important settings:
  value of $LANG: en_US.UTF-8
  locale-coding-system: utf-8-unix

Major mode: Info

Minor modes in effect:
  annotate-mode: t
  magit-wip-initial-backup-mode: t
  magit-wip-before-change-mode: t
  magit-wip-after-apply-mode: t
  magit-wip-after-save-mode: t
  which-function-mode: t
  global-git-commit-mode: t
  shell-dirtrack-mode: t
  server-mode: t
  ws-butler-global-mode: t
  ws-butler-mode: t
  global-auto-revert-mode: t
  savehist-mode: t
  delete-selection-mode: t
  override-global-mode: t
  straight-use-package-mode: t
  straight-package-neutering-mode: t
  tooltip-mode: t
  global-eldoc-mode: t
  show-paren-mode: t
  electric-indent-mode: t
  mac-mouse-wheel-mode: t
  file-name-shadow-mode: t
  isearch-fold-quotes-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  buffer-read-only: t
  line-number-mode: t
  indent-tabs-mode: t
  transient-mark-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t

Load-path shadows:
/Users/dave/.emacs.d.default/straight/build/transient/transient hides /usr/local/Cellar/emacs-mac/emacs-29.1-mac-10.0/share/emacs/29.1/lisp/transient
/Users/dave/.emacs.d.default/straight/build/use-package/use-package-jump hides /usr/local/Cellar/emacs-mac/emacs-29.1-mac-10.0/share/emacs/29.1/lisp/use-package/use-package-jump
/Users/dave/.emacs.d.default/straight/build/use-package/use-package-ensure hides /usr/local/Cellar/emacs-mac/emacs-29.1-mac-10.0/share/emacs/29.1/lisp/use-package/use-package-ensure
/Users/dave/.emacs.d.default/straight/build/use-package/use-package-core hides /usr/local/Cellar/emacs-mac/emacs-29.1-mac-10.0/share/emacs/29.1/lisp/use-package/use-package-core
/Users/dave/.emacs.d.default/straight/build/use-package/use-package-delight hides /usr/local/Cellar/emacs-mac/emacs-29.1-mac-10.0/share/emacs/29.1/lisp/use-package/use-package-delight
/Users/dave/.emacs.d.default/straight/build/use-package/use-package-diminish hides /usr/local/Cellar/emacs-mac/emacs-29.1-mac-10.0/share/emacs/29.1/lisp/use-package/use-package-diminish
/Users/dave/.emacs.d.default/straight/build/use-package/use-package hides /usr/local/Cellar/emacs-mac/emacs-29.1-mac-10.0/share/emacs/29.1/lisp/use-package/use-package
/Users/dave/.emacs.d.default/straight/build/use-package/use-package-bind-key hides /usr/local/Cellar/emacs-mac/emacs-29.1-mac-10.0/share/emacs/29.1/lisp/use-package/use-package-bind-key
/Users/dave/.emacs.d.default/straight/build/bind-key/bind-key hides /usr/local/Cellar/emacs-mac/emacs-29.1-mac-10.0/share/emacs/29.1/lisp/use-package/bind-key
/Users/dave/.emacs.d.default/straight/build/use-package/use-package-lint hides /usr/local/Cellar/emacs-mac/emacs-29.1-mac-10.0/share/emacs/29.1/lisp/use-package/use-package-lint
/Users/dave/.emacs.d.default/straight/build/seq/seq hides /usr/local/Cellar/emacs-mac/emacs-29.1-mac-10.0/share/emacs/29.1/lisp/emacs-lisp/seq
/Users/dave/.emacs.d.default/straight/build/let-alist/let-alist hides /usr/local/Cellar/emacs-mac/emacs-29.1-mac-10.0/share/emacs/29.1/lisp/emacs-lisp/let-alist

Features:
(shadow sort emacsbug find-dired annotate annotate-autoloads
loaddefs-gen poly-markdown apropos grep cus-start shortdoc dabbrev
display-line-numbers checkdoc lisp-mnt help-fns radix-tree mail-extr
goto-addr vc-hg vc-bzr vc-src vc-sccs vc-svn vc-cvs vc-rcs log-view vc
bug-reference magit-extras magit-submodule magit-blame magit-stash
magit-reflog magit-bisect magit-push magit-pull magit-fetch magit-clone
magit-remote magit-commit magit-sequence magit-notes magit-worktree
magit-tag magit-merge magit-branch magit-reset magit-files magit-refs
magit-status magit magit-repos magit-apply mule-util misearch
multi-isearch markdown-mode pulse eglot external-completion array
jsonrpc ert pp ewoc debug backtrace flymake-proc flymake vc-git
vc-dispatcher swift-mode swift-mode-imenu swift-mode-repl
swift-mode-font-lock swift-mode-standard-types swift-mode-fill
swift-mode-beginning-of-defun swift-mode-indent swift-mode-lexer
find-file-in-repository dired-aux ffap jka-compr pcase dwa-init
editorconfig-generate-autoloads editorconfig-autoloads noccur
noccur-autoloads focus focus-autoloads darkroom face-remap
darkroom-autoloads org-modern org-modern-autoloads poly-org org ob
ob-tangle ob-ref ob-lob ob-table ob-exp org-macro org-src ob-comint
org-pcomplete org-list org-footnote org-faces org-entities noutline
outline ob-emacs-lisp ob-core ob-eval org-cycle org-table ol org-fold
org-fold-core org-keys oc org-loaddefs cal-menu calendar cal-loaddefs
org-version org-compat org-macs polymode poly-lock polymode-base
polymode-weave polymode-export polymode-compat advice polymode-methods
polymode-core polymode-classes eieio-custom wid-edit eieio-base color
poly-org-autoloads poly-markdown-autoloads markdown-mode-autoloads
polymode-autoloads find-file-in-repository-autoloads
magit-imerge-autoloads magit-wip magit-log which-func magit-diff
smerge-mode diff git-commit log-edit message sendmail yank-media puny
dired dired-loaddefs rfc822 mml mml-sec epa derived epg rfc6068
epg-config gnus-util time-date mm-decode mm-bodies mm-encode mail-parse
rfc2231 rfc2047 rfc2045 mm-util ietf-drums mail-prsvr mailabbrev
mail-utils gmm-utils mailheader pcvs-util add-log magit-core
magit-autorevert magit-margin magit-transient magit-process with-editor
comp comp-cstr warnings icons shell pcomplete server magit-mode
transient magit-git magit-base magit-section format-spec crm compat
magit-autoloads magit-section-autoloads git-commit-autoloads
with-editor-autoloads transient-autoloads compat-autoloads dwa-progmodes
yaml-mode yaml-mode-autoloads tide tide-lv thingatpt imenu flycheck
find-func s dash etags fileloop generator xref tide-autoloads
flycheck-autoloads let-alist-autoloads pkg-info-autoloads epl-autoloads
s-autoloads dash-autoloads typescript-mode rx cc-mode cc-fonts cc-guess
cc-menus cc-cmds cc-styles cc-align cc-engine cc-vars cc-defs
typescript-mode-autoloads hylo-mode-autoloads swift-mode-autoloads
seq-autoloads dwa-global-config compile text-property-search comint
ansi-osc ansi-color ring skeleton modus-operandi-tinted-theme
modus-themes modus-themes-autoloads use-package-bind-key ws-butler
ws-butler-autoloads use-package-diminish diminish diminish-autoloads
ediff ediff-merg ediff-mult ediff-wind ediff-diff ediff-help ediff-init
ediff-util diff-mode descr-text package browse-url url url-proxy
url-privacy url-expand url-methods url-history url-cookie
generate-lisp-file url-domsuf url-util mailcap url-handlers url-parse
auth-source eieio eieio-core password-cache json map url-vars finder-inf
ido autorevert filenotify savehist delsel cus-load use-package-core
dwa-global-keybindings edmacro kmacro bind-key easy-mmode dwa-folding
disp-table dwa-compile project byte-opt dwa-buffers dwa-navigation
use-package-autoloads info bind-key-autoloads files-x straight-autoloads
cl-seq cl-extra help-mode straight subr-x cl-macs cl-loaddefs cl-lib
bytecomp byte-compile chemacs gv rmc iso-transl tooltip cconv eldoc
paren electric uniquify ediff-hook vc-hooks lisp-float-type elisp-mode
mwheel term/mac-win mac-win term/common-win tool-bar dnd fontset image
regexp-opt fringe tabulated-list replace newcomment text-mode lisp-mode
prog-mode register page tab-bar menu-bar rfn-eshadow isearch easymenu
timer select scroll-bar mouse jit-lock font-lock syntax font-core
term/tty-colors frame minibuffer nadvice seq simple cl-generic
indonesian philippine cham georgian utf-8-lang misc-lang vietnamese
tibetan thai tai-viet lao korean japanese eucjp-ms cp51932 hebrew greek
romanian slovak czech european ethiopic indian cyrillic chinese
composite emoji-zwj charscript charprop case-table epa-hook
jka-cmpr-hook help abbrev obarray oclosure cl-preloaded button loaddefs
theme-loaddefs faces cus-face macroexp files window text-properties
overlay sha1 md5 base64 format env code-pages mule custom widget keymap
hashtable-print-readable backquote threads kqueue mac multi-tty
make-network-process native-compile emacs)

Memory information:
((conses 16 695883 110397)
(symbols 48 37327 0)
(strings 32 164145 11005)
(string-bytes 1 6507733)
(vectors 16 86991)
(vector-slots 8 2269285 196895)
(floats 8 547 976)
(intervals 56 12010 83)
(buffers 984 74))

bug#67870: Acknowledgement (29.1; Eglot missing or un-findable advertised feature)

[Dave Abrahams]

I eventually found some eglot commands with the name "quickfix" in them.  possibly adding some references to those in the text would help

bug#67870: Acknowledgement (29.1; Eglot missing or un-findable advertised feature)

[João Távora]

On Sun, Dec 17, 2023 at 8:25 PM Dave Abrahams <dave@boostpro.com> wrote:
>
> I eventually found some eglot commands with the name "quickfix" in them.  possibly adding some references to those in the text would help

The section 3.3 Eglot Commands in the manual is worth reading.

https://joaotavora.github.io/eglot/#Eglot-Commands

It lists this and other useful commands and ways to invoke them.

In fact, the Eglot manual isn't really very long.  I recommend
at least skimming its structure.  Suggestions and patches welcome.

bug#67870: 29.1; Eglot missing or un-findable advertised feature

[João Távora]

On Sun, Dec 17, 2023 at 7:40 PM Dave Abrahams <dave@boostpro.com> wrote:

> The info page for Eglot says:
>
> 3.1 Eglot features:
>
>    • On-the-fly diagnostic annotations with server-suggested fixes, via
>      the Flymake package (*note (flymake)Top::).
>
> But I can find no evidence of the support for server-suggested fixes
> either in flymake or in eglot itself.  I am working with an LSP server
> that offers fix-its but can't find any way to apply them.

Isn't very hard to find in "3.3 Eglot commands" IMO

‘M-x eglot-code-actions’
‘M-x eglot-code-action-organize-imports’
‘M-x eglot-code-action-quickfix’
‘M-x eglot-code-action-extract’
‘M-x eglot-code-action-inline’
‘M-x eglot-code-action-rewrite’
     These commands allow you to invoke the so-called “code actions”:
     requests for the language server to provide editing commands for
     correcting, refactoring or beautifying your code.  These commands
     may affect more than one visited file belonging to the project.

     The command ‘eglot-code-actions’ asks the server if there [are] any code
     actions for any point in the buffer or contained in the active
     region.  If there are, you have the choice to execute one of them
     via the minibuffer.

     A common use of code actions is fixing the Flymake error
     diagnostics issued by Eglot (*note (flymake)Top::).  Clicking on a
     diagnostic with ‘mouse-2’ invokes ‘eglot-code-actions-at-mouse’
     which pops up a menu of available code actions.  The variable
     ‘eglot-diagnostics-map’ can be used to control the mouse binding.

     Other commands execute a specific code action.  For example,
     ‘eglot-code-action-organize-imports’ rearranges the program's
     “imports”--declarations of modules whose capabilities the program
     uses.

> Either what's meant by this should be clarified, leading to discoverable
> instructions for exploiting the feature, or the text should be removed.

That's just a summarized list of the main features, a detailed description
doesn't of how to use the feature doesn't belong there.  But patches welcome for
a link down to 3.3 (and fixing the typo while you're at it).

João

bug#67870: 29.1; Eglot missing or un-findable advertised feature

[Dave Abrahams]

Of course it's easy for *you* to find; you know what you're looking for.  I wouldn't have filed a bug if I wasn't having trouble, and I figured the experience of someone not familiar with the package might count for soimething. I looked for the words "suggested" and "fixes" and couldn't find anything.  I googled.   I looked at flymake docs too because given the phrasing I thought it might have been there.  If you'd used some of the distinctive words that could be found in the eglot manual around these commands (e.g. quickfix, action, rewrite), I wouldn't have had any trouble.  "fix" by itself is a bit too short and common to be a good search keyword.

> On Dec 18, 2023, at 9:00 AM, João Távora <joaotavora@gmail.com> wrote:
> 
> On Sun, Dec 17, 2023 at 7:40 PM Dave Abrahams <dave@boostpro.com> wrote:
> 
>> The info page for Eglot says:
>> 
>> 3.1 Eglot features:
>> 
>>   • On-the-fly diagnostic annotations with server-suggested fixes, via
>>     the Flymake package (*note (flymake)Top::).
>> 
>> But I can find no evidence of the support for server-suggested fixes
>> either in flymake or in eglot itself.  I am working with an LSP server
>> that offers fix-its but can't find any way to apply them.
> 
> Isn't very hard to find in "3.3 Eglot commands" IMO
> 
> ‘M-x eglot-code-actions’
> ‘M-x eglot-code-action-organize-imports’
> ‘M-x eglot-code-action-quickfix’
> ‘M-x eglot-code-action-extract’
> ‘M-x eglot-code-action-inline’
> ‘M-x eglot-code-action-rewrite’
>     These commands allow you to invoke the so-called “code actions”:
>     requests for the language server to provide editing commands for
>     correcting, refactoring or beautifying your code.  These commands
>     may affect more than one visited file belonging to the project.
> 
>     The command ‘eglot-code-actions’ asks the server if there [are] any code
>     actions for any point in the buffer or contained in the active
>     region.  If there are, you have the choice to execute one of them
>     via the minibuffer.
> 
>     A common use of code actions is fixing the Flymake error
>     diagnostics issued by Eglot (*note (flymake)Top::).  Clicking on a
>     diagnostic with ‘mouse-2’ invokes ‘eglot-code-actions-at-mouse’
>     which pops up a menu of available code actions.  The variable
>     ‘eglot-diagnostics-map’ can be used to control the mouse binding.
> 
>     Other commands execute a specific code action.  For example,
>     ‘eglot-code-action-organize-imports’ rearranges the program's
>     “imports”--declarations of modules whose capabilities the program
>     uses.
> 
>> Either what's meant by this should be clarified, leading to discoverable
>> instructions for exploiting the feature, or the text should be removed.
> 
> That's just a summarized list of the main features, a detailed description
> doesn't of how to use the feature doesn't belong there.  But patches welcome for
> a link down to 3.3 (and fixing the typo while you're at it).
> 
> João

bug#67870: 29.1; Eglot missing or un-findable advertised feature

[João Távora]

On Mon, Dec 18, 2023 at 7:10 PM Dave Abrahams <dave@boostpro.com> wrote:
>
> Of course it's easy for *you* to find;

Well, yes.  That's why I wrote "IMO" which abbreviates
"in my opinion".  I don't have control over your _opinion_
it's just, like, your opinion.

> I wouldn't have filed a bug if I wasn't having trouble,

I hope you are out of trouble now :-)

> in the eglot manual around these commands (e.g. quickfix, action,
> rewrite), I wouldn't have had any trouble.  "fix" by itself is a bit too short and common to be a good search keyword.

No need to justify yourself so much, but I find this odd.
For example, a simple text search within the Eglot manual for
"action" yields this as the second result in the end of the
very section you were reading.

   • In addition to enabling and enhancing other features and packages,
     Eglot also provides a number of user commands based on the
     capabilities of language servers.  Examples include renaming
     symbols with ‘eglot-rename’ and asking to automatically correct
     problems with ‘eglot-code-actions’.  *Note Eglot Commands::.

And "code actions" and "quickfix" and "rename" are easily found
in the manual's index, also just a C-s (isearch) away.

It's very good that you are using Eglot's manual, but IMO
glancing through a high-level overview of features is not
sufficient to learn how to use it.  You need at least skim the
remainder of the manual. Packages in Emacs are controlled via
commands, and so the "Eglot Commands" section is very relevant
to use Eglot.  That section is amply referenced through the
manual.

Maybe I'll add something to the existing "For the  impatient"
section.  Until then, I consider this bug report solved, so
I'm closing it.

João

bug#67870: 29.1; Eglot missing or un-findable advertised feature

[Dave Abrahams]

You’re missing my point. In that bulletin there was nothing that could have prompted me to search for “action”.

Sent from my iPad

> On Dec 18, 2023, at 12:00 PM, João Távora <joaotavora@gmail.com> wrote:
> 
> No need to justify yourself so much, but I find this odd.
> For example, a simple text search within the Eglot manual for
> "action" yields this as the second result in the end of the
> very section you were reading.

bug#67870: 29.1; Eglot missing or un-findable advertised feature

[João Távora]

On Tue, Dec 19, 2023 at 8:15 AM Dave Abrahams <dave@boostpro.com> wrote:
>
> You’re missing my point. In that bulletin there was nothing that could have prompted me to search for “action”.

Well, I can't help every user connect the pieces of this
one-piece puzzle every time. Read more of the fine
manual next time, and thanks.

João

bug#67870: 29.1; Eglot missing or un-findable advertised feature

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > You’re missing my point. In that bulletin there was nothing that could have prompted me to search for “action”.

  > Well, I can't help every user connect the pieces of this
  > one-piece puzzle every time. Read more of the fine
  > manual next time, and thanks.

Making a manual really fine includes sometimes tweaking little details
like this, to help users find what they really should be looking for.
I've done that many times in manuals I was working on.

One can tweak index entries, command names, news items, and all sorts
of things to make connections work.  We can't make them perfect, but
we can often make them better.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

bug#67870: 29.1; Eglot missing or un-findable advertised feature

[João Távora]

On Fri, Dec 22, 2023 at 3:14 AM Richard Stallman <rms@gnu.org> wrote:
>
> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
>   > > You’re missing my point. In that bulletin there was nothing that could have prompted me to search for “action”.
>
>   > Well, I can't help every user connect the pieces of this
>   > one-piece puzzle every time. Read more of the fine
>   > manual next time, and thanks.
>
> Making a manual really fine includes sometimes tweaking little details
> like this, to help users find what they really should be looking for.
> I've done that many times in manuals I was working on.

I clarified the doubt, asked for suggestions and got none.
So I've rewritten that sentence originally written by Eli, who
I understand not to be a heavy Eglot user yet.  It's generally
impossible every user's reading experience. There were numerous
other hints the user could have followed, like searching for "fix" or
"Flymake" and they could have read just have a few more paragraphs
to find more.

bug#67870: 29.1; Eglot missing or un-findable advertised feature

[João Távora]

On Fri, Dec 22, 2023 at 9:29 AM João Távora <joaotavora@gmail.com> wrote:

> > Making a manual really fine includes sometimes tweaking little details
> > like this, to help users find what they really should be looking for.
> > I've done that many times in manuals I was working on.
>
> I clarified the doubt, asked for suggestions and got none.
> So I've rewritten that sentence originally written by Eli, who
> I understand not to be a heavy Eglot user yet.  It's generally
> impossible every user's reading experience. There were numerous

^^^^
[to anticipate]

bug#67870: 29.1; Eglot missing or un-findable advertised feature

[Dave Abrahams]

I did suggest including certain words that would have helped me. Do you want a suggested rewrite of the text instead?  What qualifies as a suggestion in your book?

> 
> On Dec 22, 2023, at 1:29 AM, João Távora <joaotavora@gmail.com> wrote:
> 
> On Fri, Dec 22, 2023 at 3:14 AM Richard Stallman <rms@gnu.org> wrote:
>> 
>> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
>> [[[ whether defending the US Constitution against all enemies,     ]]]
>> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>> 
>>>> You’re missing my point. In that bulletin there was nothing that could have prompted me to search for “action”.
>> 
>>> Well, I can't help every user connect the pieces of this
>>> one-piece puzzle every time. Read more of the fine
>>> manual next time, and thanks.
>> 
>> Making a manual really fine includes sometimes tweaking little details
>> like this, to help users find what they really should be looking for.
>> I've done that many times in manuals I was working on.
> 
> I clarified the doubt, asked for suggestions and got none.
> So I've rewritten that sentence originally written by Eli, who
> I understand not to be a heavy Eglot user yet.  It's generally
> impossible every user's reading experience. There were numerous
> other hints the user could have followed, like searching for "fix" or
> "Flymake" and they could have read just have a few more paragraphs
> to find more.

bug#67870: 29.1; Eglot missing or un-findable advertised feature

[Stefan Kangas]

Dave Abrahams <dave@boostpro.com> writes:

> I did suggest including certain words that would have helped me. Do
> you want a suggested rewrite of the text instead?  What qualifies as a
> suggestion in your book?

I'm not João, but I see that he edited the text recently so that it now
reads, on current master:

   • On-the-fly diagnostic annotations, via the Flymake package (*note
     (flymake)Top::).  Eglot's Flymake backend replaces other Flymake
     backends while it is managing a buffer, and enhances diagnostics
     with interactive server-suggested fixes (so-called “code actions”,
     *note Eglot Commands::)

Does that seem okay to you or is there more we could do here?

Thanks.