Improve the technical documentation for GNU/Emacs mode (still in `REA…

…DME.md`)

README.md

@@ -67,27 +67,55 @@ You can check the documentation on using the extension on [this page](https://oc
 
 ### GNU/Emacs mode
 
-* An experimental mode for GNU/Emacs, that is based on [lsp-mode](https://github.com/emacs-lsp/lsp-mode), is provided. It can be tested via the following commands:
+Within the GNU/Emacs ecosystem, two main clients exist to interact with LSP servers: 
+
+#### `lsp-mode`
+
+[lsp-mode](https://github.com/emacs-lsp/lsp-mode) appears to be the most prominent at the moment.  The main advantages for using it in our context is its support for [semantic tokens](https://code.visualstudio.com/api/language-extensions/semantic-highlight-guide), that provide a way for LSPs to issue information about the semantics of symbols from the source code.  By means of semantic tokens, LSPs drastically improve code readability via more detailed hightligting of source code elements that via traditional grammar-based syntax hightligting;
+
+This mode benefits from a large user-base, but is also considered "bloated" by some.
+
+#### `eglot`
+
+Another possiblity is to use [eglot](https://elpa.gnu.org/packages/eglot.html), that is sometimes considered easier to configure and more lightweight than `lsp-mode` (which notably makes it more reactive to user inputs).  Being more recent, it lacks some of the features of `lsp-mode`, among which is the support for semantic tokens [^eglot-semtok-issue].
+However, additionally enabling `cobol-mode` (available via GNU ELPA — https://elpa.gnu.org/packages/cobol-mode.html ) provides reasonable syntax highlighting.
+
+[^eglot-semtok-issue] Note there is a pending issue on this point at https://github.com/joaotavora/eglot/issues/615 .
+
+#### Setup
+
+To ease the setup process, we first define an environment variable that indicates where the `superbol` executable can be found.  We additionally define a variable that points to the root of the source directory for the extension.
 
 ```shell
-# Derive customization variables from "package.json"
-make emacs/lsp-superbol-customs.el
-# Setup path to superbol directory, where the "padbol" executable can be found
-export SUPERBOL_DIR="$HOME/work/repos/superbol";
-# Launch an Emacs with an lsp-mode LSP for superbol-mode, triggered for some default COBOL file extensions
-\emacs -L emacs --load lsp-superbol --eval "(custom-set-variables '(lsp-superbol-path \"$SUPERBOL_DIR\"))" --funcall superbol-mode-enable-for-default-extensions
-# Then visit a COBOL file and have fun
+export SUPERBOL_DIR="<directory where superbol can be found>";
+export SUPERBOL_VSCODE_PLATFORM_DIR="$PWD";
 ```
 
-* An alternative experimental mode for GNU/Emacs, based on [eglot](https://elpa.gnu.org/packages/eglot.html), is provided.  Test it via the following commands:
+Then, the following command launches a GNU/Emacs instance with an `lsp-mode`-based client configured for COBOL files:
+
+[comment]: # # Derive customization variables from "package.json"
+[comment]: # make -C "$SUPERBOL_VSCODE_PLATFORM_DIR" emacs/lsp-superbol-customs.el LSP_MODE_SRCDIR="<lsp-mode source-code>"
 
 ```shell
-# Setup path to superbol directory, where the "padbol" executable can be found
-export SUPERBOL_DIR="$HOME/work/repos/superbol";
-# Launch an Emacs with eglot-based LSP for superbol-mode, triggered for some default COBOL file extensions
-\emacs -L emacs --load eglot-superbol --eval "(add-to-list 'exec-path \"$SUPERBOL_DIR\")" --funcall superbol-mode-enable-for-default-extensions
+emacs -L "$SUPERBOL_VSCODE_PLATFORM_DIR/emacs" \
+      --load lsp-superbol \
+      --eval "(custom-set-variables '(lsp-superbol-path \"$SUPERBOL_DIR\"))" \
+      --funcall superbol-mode-enable-for-default-extensions
 ```
 
+To use `eglot`, type the following instead:
+
+```shell
+emacs -L "$SUPERBOL_VSCODE_PLATFORM_DIR/emacs" \
+      --load eglot-superbol \
+      --eval "(add-to-list 'exec-path \"$SUPERBOL_DIR\")" \
+      --funcall superbol-mode-enable-for-default-extensions
+```
+
+#### Further configuration for auto-indentation:
+
+`lsp-mode` provides a `lsp-format-region` function that may be used to use the LSP-provided intentation.  When using `eglot`, the same functionality is provided by `eglot-format`.
+
 ## Resources
 
 * Website: https://ocamlpro.github.io/superbol-vscode-platform