branch: externals/eglot
commit a62a3880212daef7ac950596e8f425aacdaf9f16
Author: João Távora <joaotav...@gmail.com>
Commit: João Távora <joaotav...@gmail.com>
Fix README.md typos and rework section about Workspace configuration
* README.md (Workspace Configuration): Fix typos and rework
---
README.md | 67 ++++++++++++++++++++++++++++++++++++++++-----------------------
1 file changed, 43 insertions(+), 24 deletions(-)
diff --git a/README.md b/README.md
index 2314eb2d32..b0b54ad064 100644
--- a/README.md
+++ b/README.md
@@ -130,15 +130,29 @@ the ensuing TCP connection finds a listening server.
## Workspace configuration
-Most servers can guess good defaults and will operate nicely
-out-of-the-box, but some need to be configured specially via LSP
-interfaces. Additionally, in some situations, you may also want a
-particular server to operate differently across different projects.
+Many servers can guess good defaults and operate nicely
+out-of-the-box, but some need to be configured via a special LSP
+`workspace/configuration` RPC call to work at all. Additionally, you
+may also want a particular server to operate differently across
+different projects.
-Per-project settings are realized with Emacs's _directory variables
-and the Elisp variable `eglot-workspace-configuration`. To make a
-particular Python project always enable Pyls's snippet support, put a
-file named `.dir-locals.el` in the project's root:
+Per-project settings are realized with the Elisp variable
+`eglot-workspace-configuration`.
+
+Before considering what to set the variable to, one must understand
+_how_ to set it. `eglot-workspace-configuration` is a
+"directory-local" variable, and setting its variable globally or
+buffer-locally likely makes no sense. It should be set via
+`.dir-locals.el` or equivalent mechanisms.
+
+The variable's value is an _association list_ of _parameter sections_
+to _parameter objects_. Names and formats of section and parameter
+objects are server specific.
+
+#### Simple `eglot-workspace-configuration`
+
+To make a particular Python project always enable Pyls's snippet
+support, put a file named `.dir-locals.el` in the project's root:
```lisp
((python-mode
@@ -148,17 +162,16 @@ file named `.dir-locals.el` in the project's root:
This tells Emacs that any `python-mode` buffers in that directory
should have a particular value of `eglot-workspace-configuration`.
-That variable's value should be _association list_ of _parameter
-sections_ which are presumably understood by the server.
-In this above, we associated the _section_ `:pyls` with the parameters
-object `(:plugins (:jedi_completion (:include_params t)))`.
+Here, the value in question associates section `:pyls` with parameters
+`(:plugins (:jedi_completion (:include_params t)))`. The parameter
+object is a plist converted to JSON before being sent to the server.
-### Multiple workspace configuration for multiple servers
+#### Multiple servers in `eglot-workspace-configuration`
Suppose you also had some Go code in the very same project, you can
-configure the Gopls server in the same `.dir-locals.el' file. Adding
-a section for `go-mode`, the file's contents become:
+configure the Gopls server in the same `.dir-locals.el` file. Adding
+a section for `go-mode`, the file's contents now become:
```lisp
((python-mode
@@ -169,7 +182,9 @@ a section for `go-mode`, the file's contents become:
. ((:gopls . (:usePlaceholders t)))))))
```
-As a matter of taste, you might prefer this equivalent setup.
+Alternatively, as a matter of taste, you may choose this equivalent
+setup, which sets the variables value in all all major modes of all
+buffers of a given project.
```lisp
((nil
@@ -178,19 +193,22 @@ As a matter of taste, you might prefer this equivalent
setup.
(:gopls . (:usePlaceholders t)))))))
```
-### Setting up without `.dir-locals.el`
+#### `eglot-workspace-configuration` without `.dir-locals.el`
If you can't afford an actual `.dir-locals.el` file, or if managing
-this file becomes cumbersome, the Emacs manual (49.2.5 Per-Directory
-Local Variables) teaches you programmatic ways to leverage
-per-directory local variables. Look for the functions
+this file becomes cumbersome, the [Emacs
+manual][dir-locals-emacs-manual] teaches you programmatic ways to
+leverage per-directory local variables. Look for the functions
`dir-locals-set-directory-class` and `dir-locals-set-class-variables`.
-### Setting a dynamic `eglot-workspace-configuration` dynamically
+#### Dynamic `eglot-workspace-configuration` as a function
-If you need to decide `eglot-workspace-configuration` can be a function, too.
It is passed
-the `eglot-lsp-server` instance and runs with `default-directory` set
-to the root of your project.
+If you need to determine the workspace configuration base on some
+dynamic context, make `eglot-workspace-configuration` a function. It
+is passed the `eglot-lsp-server` instance and runs with
+`default-directory` set to the root of your project. The function
+should return a value of the same form as described in the previous
+paragraphs.
## Handling quirky servers
@@ -598,3 +616,4 @@ for the request form, and we'll send it to you.
[gospb]:
https://opensource.googleblog.com/2020/10/announcing-latest-google-open-source.html
[copyright-assignment]: https://www.fsf.org/licensing/contributor-faq
[legally-significant]:
https://www.gnu.org/prep/maintain/html_node/Legally-Significant.html#Legally-Significant
+[dir-locals-emacs-manual]:
https://www.gnu.org/software/emacs/manual/html_node/emacs/Directory-Variables.html
