Re: [PATCH] Explain a bit more on how to configure language server in Eglot's manual

[Michael Eliachevitch <m.eliachevitch@posteo.de>]

[-- Attachment #1: Type: text/plain, Size: 800 bytes --]

Thanks Eli, I incorporated your comments into v2 of the patch attached below.

>>  giving all your projects a certain default configuration, as described
>> -in @xref{Project-specific configuration}.  Here is an example.
>> +in @xref{Project-specific configuration}.  Here is an example:
>
> @xref here is wrong: it produces a capitalized "See", so is only
> appropriate at the beginning of a sentence.  You want @pxref instead.

Good point. However, due to the "as described" above, I think it should just be a @ref instead. I also found a wrong @xref  inside a sentence in line 1201 of eglot.texi, which I now also replaced by @pxref v2 of my patch.

> If you want to continue a sentence after @lisp, you need to have
> @noindent before the text.

Thanks, also incorporated that.

Cheers, Michael


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: v2 of patch that documents how to represent json arrays as vectors in eglot/jsonrpc --]
[-- Type: text/x-patch, Size: 3200 bytes --]

From 4cbaa88d2a19cc59e727efd35ba17facdc36b01e Mon Sep 17 00:00:00 2001
From: Michael Eliachevitch <m.eliachevitch@posteo.de>
Date: Tue, 14 Mar 2023 22:47:37 +0100
Subject: [PATCH v2] Document how to set JSON arrays in
 eglot-workspace-configuration

Many language server configuration options are lists of the JSON array
datatype, for example argument lists for executables. These can be
configured in emacs lisp as vectors. The eglot documentation talked
about confiring json as plists and introduced some basic json
datatypes, but didn't yet mention arrays, which this commit introduced.

* Other minor changes

- Align property lists in eglot documentation, so that keywords of the same level
  are aligned

- Slightly change punctuation before code example to better
  grammatically integrate the example code and the text.
---
 doc/misc/eglot.texi | 22 +++++++++++++++-------
 1 file changed, 15 insertions(+), 7 deletions(-)

diff --git a/doc/misc/eglot.texi b/doc/misc/eglot.texi
index 735da5f0163..d6c43c8ac02 100644
--- a/doc/misc/eglot.texi
+++ b/doc/misc/eglot.texi
@@ -1201,7 +1201,7 @@ User-specific configuration
 The argument @code{(:compilationDatabasePath "/tmp")} is Emacs's
 representation in plist format of a simple JSON object
 @code{@{"compilationDatabasePath": "/tmp"@}}.  To learn how to
-represent more deeply nested options in this format, @xref{JSONRPC
+represent more deeply nested options in this format, @pxref{JSONRPC
 objects in Elisp}.
 
 In this case, the two examples achieve exactly the same, but notice
@@ -1214,7 +1214,7 @@ User-specific configuration
 @code{eglot-workspace-configuration}, a variable originally intended
 for project-specific configuration.  This has the same effect as
 giving all your projects a certain default configuration, as described
-in @xref{Project-specific configuration}.  Here is an example.
+in @ref{Project-specific configuration}.  Here is an example:
 
 @lisp
 (setq-default eglot-workspace-configuration
@@ -1241,17 +1241,21 @@ JSONRPC objects in Elisp
 For representing the JSON leaf values @code{true}, @code{false},
 @code{null} and @code{@{@}}, you can use the Lisp values @code{t},
 @code{:json-false}, @code{nil}, and @code{eglot-@{@}}, respectively.
+JSON arrays are represented as lisp vectors surrounded by square brackets
+(@pxref{Vectors,,,elisp,GNU Emacs Lisp Reference Manual}).
 
-For example, this plist:
+For example, the plist
 
 @lisp
 (:pylsp (:plugins (:jedi_completion (:include_params t
-                                             :fuzzy t)
-                           :pylint (:enabled :json-false)))
+                                     :fuzzy t)
+                   :pylint (:enabled :json-false
+                            :args ["--disable" "C0103"])))
  :gopls (:usePlaceholders t))
 @end lisp
 
-Is serialized by Eglot to the following JSON text:
+@noindent
+is serialized by Eglot to the following JSON text:
 
 @example
 @{
@@ -1262,7 +1266,11 @@ JSONRPC objects in Elisp
         "fuzzy": true
       @},
       "pylint": @{
-        "enabled": false
+        "enabled": false,
+        "args": [
+          "--disable",
+          "C0103"
+        ]
       @}
     @}
   @},
-- 
2.40.0