[elpa] externals/eglot a62a388021 11/15: Fix README.md typos and rework section about Workspace configuration

[ELPA Syncer]

branch: externals/eglot
commit a62a3880212daef7ac950596e8f425aacdaf9f16
Author: João Távora <joaotavora@gmail.com>
Commit: João Távora <joaotavora@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