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: 1329 bytes --]


> OK, Can you submit a patch?  Bonus points if you add your :texlab example.

Here you go. This is my first Emacs patch and I hope it's fine like this as I'm not very experienced with this patch email workflow. Is it okay that I sent it in a reply as an attachment or should I have started a new thread for the patch?

In the patch I mention that arrays can be represented as vector datatypes and extend the existing advanced configuration :pylsp example with an array option. Further, the patch also fixes the indentation for the example.

Further, the patch introduces some changes to the punctuation before/after the configuration examples, because stylistically I think they should be considered part of the surrounding text. If you want I could make this a separate patch or you can revert those changes. I admit this is also personal preference, I have some personal opinions on that but they are not strong.

Initially I didn't know how to find the proper xref reference to vectors in the elisp manual, but luckily with some grepping I found another place where that manual section was referenced and just copied that xref (this is also my first time writing texinfo). I didn't rebuild the documentation yet but hope it will be fine.

The changes are  also described in the commit message in the patch.

Cheers, Michael


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Document-how-to-set-JSON-arrays-in-eglot-workspace-c.patch --]
[-- Type: text/x-patch, Size: 2813 bytes --]

From 8edbaae1c0d8605299c863f4e95c1f3d15b3d158 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] 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 | 19 +++++++++++++------
 1 file changed, 13 insertions(+), 6 deletions(-)

diff --git a/doc/misc/eglot.texi b/doc/misc/eglot.texi
index 735da5f0163..cf4c1d5bcd1 100644
--- a/doc/misc/eglot.texi
+++ b/doc/misc/eglot.texi
@@ -1214,7 +1214,7 @@ supported.  It consists of @emph{globally} setting
 @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 @xref{Project-specific configuration}.  Here is an example:
 
 @lisp
 (setq-default eglot-workspace-configuration
@@ -1241,17 +1241,20 @@ keyword-value property sub-plists corresponding to JSON sub-objects.
 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:
+is serialized by Eglot to the following JSON text:
 
 @example
 @{
@@ -1262,7 +1265,11 @@ Is serialized by Eglot to the following JSON text:
         "fuzzy": true
       @},
       "pylint": @{
-        "enabled": false
+        "enabled": false,
+        "args": [
+          "--disable",
+          "C0103"
+        ]
       @}
     @}
   @},
-- 
2.40.0