From 22a70451f3448c6e0af9bc0a5cb6fe15a757fb12 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Jo=C3=A3o=20T=C3=A1vora?= <joaotavora@gmail.com>
Date: Sat, 18 Mar 2023 12:28:22 +0000
Subject: [PATCH] Merge confusing duplicate sections on commands in Eglot
manual
Also describe eglot-diagnostics-map.
* doc/misc/eglot.texi (Eglot Features): Don't describe commands here.
(Eglot Commands): Describe commands here.
---
doc/misc/eglot.texi | 90 ++++++++++++++++++---------------------------
1 file changed, 35 insertions(+), 55 deletions(-)
diff --git a/doc/misc/eglot.texi b/doc/misc/eglot.texi
index 034297b0e68..4ab961a951f 100644
--- a/doc/misc/eglot.texi
+++ b/doc/misc/eglot.texi
@@ -465,52 +465,10 @@ ElDoc look nicer on display.
@item
In addition to enabling and enhancing other features and packages,
-Eglot also provides a small number of user commands based directly on
-the capabilities of language servers. These commands are:
-
-@table @kbd
-@item M-x eglot-rename
-This prompts for a new name for the symbol at point, and then modifies
-all the project source files to rename the symbol to the new name,
-based on editing data received from the language-server. @xref{Eglot
-and Buffers}, for the details of how project files are defined.
-
-@item M-x eglot-format
-This reformats and prettifies the current active region according to
-source formatting rules of the language-server. If the region is not
-active, it reformats the entire buffer instead.
-
-@item M-x eglot-format-buffer
-This reformats and prettifies the current buffer according to source
-formatting rules of the language-server.
-
-@cindex code actions
-@item M-x eglot-code-actions
-@itemx M-x eglot-code-action-organize-imports
-@itemx M-x eglot-code-action-quickfix
-@itemx M-x eglot-code-action-extract
-@itemx M-x eglot-code-action-inline
-@itemx M-x eglot-code-action-rewrite
-These command allow you to invoke the so-called @dfn{code actions}:
-requests for the language-server to provide editing commands for
-various code fixes, typically either to fix an error diagnostic or to
-beautify/refactor code. For example,
-@code{eglot-code-action-organize-imports} rearranges the program
-@dfn{imports}---declarations of modules whose capabilities the program
-uses. These commands affect all the files that belong to the
-project. The command @kbd{M-x eglot-code-actions} will pop up a menu
-of code applicable actions at point.
-@end table
-
-@item M-x eglot-inlay-hints-mode
-This command toggles LSP ``inlay hints'' on and off for the current
-buffer. Inlay hints are small text annotations to specific parts of
-the whole buffer, not unlike diagnostics, but designed to help
-readability instead of indicating problems. For example, a C++ LSP
-server can serve hints about positional parameter names in function
-calls and a variable's automatically deduced type. Inlay hints help
-the user not have to remember these things by heart.
-
+Eglot also provides a number of user commands based on the
+capabilities of language servers. Examples include renaming symbols
+with @kbd{eglot-rename} and asking to automatically correct problems
+with @kbd{eglot-code-actions}. @xref{Eglot commands}.
@end itemize
Not all servers support the full set of LSP capabilities, but most of
@@ -714,19 +672,41 @@ This command reformats the current buffer, in the same manner as
@code{eglot-format} does.
@item M-x eglot-code-actions
-@itemx mouse-1
-This command asks the server for any @dfn{code actions} applicable at
-point. It can also be invoked by @kbd{mouse-1} clicking on
-diagnostics provided by the server.
-
-@item M-x eglot-code-action-organize-imports
+@itemx M-x eglot-code-action-organize-imports
@itemx M-x eglot-code-action-quickfix
@itemx M-x eglot-code-action-extract
@itemx M-x eglot-code-action-inline
@itemx M-x eglot-code-action-rewrite
-These commands invoke specific code actions supported by the language
-server.
-@c FIXME: Need more detailed description of each action.
+These commands allow you to invoke the so-called @dfn{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 belong to the project.
+
+The command @code{eglot-code-actions} asks the server if there any
+code actions for any point in the buffer or contained in the active
+region. If there are, you 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 (@pxref{Top,,, flymake, GNU Flymake manual}).
+Clicking on a diagnostic with @kbd{mouse-2} invokes
+@code{eglot-code-actions-at-mouse} which pops up a menu of available
+code actions. The variable @code{eglot-diagnostics-map} can be used
+to control the mouse binding.
+
+Other commands execute a specific code action. For example,
+@code{eglot-code-action-organize-imports} rearranges the program's
+@dfn{imports}---declarations of modules whose capabilities the program
+uses.
+
+@item M-x eglot-inlay-hints-mode
+This command toggles LSP ``inlay hints'' on and off for the current
+buffer. Inlay hints are small text annotations to specific parts of
+the whole buffer, not unlike diagnostics, but designed to help
+readability instead of indicating problems. For example, a C++
+language server can serve hints about positional parameter names in
+function calls and a variable's automatically deduced type. Inlay
+hints help the user not have to remember these things by heart.
@end ftable
The following Eglot commands are used less commonly, mostly for
--
2.39.5