Merge branch dev into published

.gitignore

@@ -75,7 +75,7 @@ report.*
 .lsp
 output.calva-repl
 .clj-kondo
-clojure-lsp*
+/clojure-lsp*
 
 # MkDocs
 /site/

CHANGELOG.md

@@ -4,9 +4,13 @@ Changes to Calva.
 
 ## [Unreleased]
 
+## [2.0.254] - 2022-03-16
+- [Add commands for starting and stopping clojure-lsp](https://github.com/BetterThanTomorrow/calva/pull/1592)
+- Maintenance: [Dumb down the token cursor some dealing with meta data and readers](https://github.com/BetterThanTomorrow/calva/pull/1585)
+
 ## [2.0.253] - 2022-03-09
 - Fix: [Structural editing hangs in specific cases of unbalanced forms](https://github.com/BetterThanTomorrow/calva/pull/1585)
-- Fix: [over snippet markdown and adds example](https://github.com/BetterThanTomorrow/calva/pull/1582)
+- Fix: [Hover snippet markdown and adds example](https://github.com/BetterThanTomorrow/calva/pull/1582)
 - Maintenance: [Begin work on enabling strictNullChecks in the TypeScript config.](https://github.com/BetterThanTomorrow/calva/pull/1568)
 
 ## [2.0.252] - 2022-03-05

README.md

@@ -1,12 +1,26 @@
-# Calva: Clojure & ClojureScript with Visual Studio Code
+# Calva: A Clojure & ClojureScript IDE in Visual Studio Code
 
 ![Calva logo](assets/calva-64h.png)
 
 _Distilled from [CIDER](https://cider.mx/)*._
 
-Welcome to [Calva](https://marketplace.visualstudio.com/items?itemName=betterthantomorrow.calva), an integrated REPL powered environment for enjoyable and productive [Clojure](https://clojure.org) and [ClojureScript](https://clojurescript.org) in [Visual Studio Code](https://code.visualstudio.com). It includes inline code evaluation, [Paredit](https://calva.io/paredit/), a Clojure formatter, a test runner, Clojure syntax highlighting, and more. Most of the REPL power is harvested from the produce of [The Orchard](https://github.com/clojure-emacs/orchard).
+Welcome to [Calva](https://marketplace.visualstudio.com/items?itemName=betterthantomorrow.calva), an integrated, REPL powered, development environment for enjoyable and productive [Clojure](https://clojure.org) and [ClojureScript](https://clojurescript.org) programming in [Visual Studio Code](https://code.visualstudio.com). It includes:
 
-(*) Calva is short for Calvados, a liquid gifted to humanity from God.
+* inline [code evaluation](https://calva.io/evaluation.md)
+* [structural editing](https://calva.io/paredit.md)
+* code [formatting](https://calva.io/formatting.md)
+* code navigation
+* a [debugger](ttps://calva.io/debugger.md)
+* [linting](https://calva.io/linting.md)
+* syntax highlighting
+* Clojure aware rainbow brackets
+* a [test runner](https://calva.io/test-runner.md)
+* refactoring support
+* and much more.
+
+A lot of effort has been put into making Calva a good choice to start if you are new to Clojure. [Calva is open source](https://github.com/BetterThanTomorrow/calva) and free to use.
+
+(*) Calva is short for Calvados, a liquid gifted to humanity from God. Calvas's REPL power is harvested from the produce of [The Orchard](https://github.com/clojure-emacs/orchard).
 
 ## Users Like it 😍
 

docs/site/clojure-lsp.md

@@ -7,16 +7,52 @@ description: Learn about how Calva leverages clojure-lsp for a lot of the featur
 
 Calva uses a mix of static and dynamic analysis to power the experience. A lot of the static abilities come from [clojure-lsp](https://github.com/snoe/clojure-lsp). This enables you to check something up in a project, with a lot of navigational and contextual support, without starting a REPL for it. (And once you do start a REPL you'll get even more capabilities, enabled by the dynamic analysis.)
 
-!!! Note
-    By default, Calva determines the version of clojure-lsp it uses, and it defaults to `latest`. To use a different version of clojure-lsp, see the [configuration](#configuration) section. **Calva does not use the clojure-lsp installed on your system, unless you [set the path for clojure-lsp](#using-a-custom-clojure-lsp-native-binary) to the installed binary in your settings**. You can see what version is being used by running the `Clojure-lsp Server Info` command, which will also show the version of clj-kondo that's being used as well as other info. 
+!!! Note "Which clojure-lsp does Calva use?"
+    Calva defaults to using the `latest` clojure-lsp released. To use a different version of clojure-lsp, see the [configuration](#configuration) section. **Calva does not use the clojure-lsp installed on your system, unless you [set the path for clojure-lsp](#using-a-custom-clojure-lsp-native-binary) to the installed binary in your settings**. You can see what version is being used by running the `Clojure-lsp Server Info` command, which will also show the version of clj-kondo that's being used as well as other info. 
 
-## Starting the LSP server
+## The LSP server starts automatically
 
-You don't need to do anything to start clojure-lsp. No install, no commands, no nothing. Calva downloads the correct binary for your operating system if necessary (this should only happen when the clojure-lsp version is updated in a new release of Calva) and then starts it. It does take a while for clojure-lsp to start, though, especially the first time for a new project, when clojure-lsp (via `clj-kondo`) indexes the project files.
+Unless you set `calva.enableClojureLspOnStart` to `false`, Calva will automatically start clojure-lsp. And you won't need to install antyting, because Calva handles that. It can take a while for clojure-lsp to start, especially the first time for a new project, when clojure-lsp (via `clj-kondo`) indexes the project files.
 
-Calva will show a status bar message during the download and while the server is starting, which will go away once the server is ready. However, _much of Calva's functionality is available regardless of the LSP server_, so please start using Calva while this server is starting.
+## LSP server process control
 
-!["Clojure-lsp status bar downloading and intializing messages"](images/clojure-lsp/lsp-status-bar-message.gif "Clojure-lsp status bar downloading and intializing messages")
+It is highly recommended to let clojure-lsp start automatically, and most often you can just let it do its wonderful magic without bothering with it. There are times when you might want to control and inspect the process, though. Calva has commands for:
+
+* Inspecting the clojure-lsp server information
+* Read the clojure-lsp server log
+* Stopping clojure-lsp
+* Starting clojure-lsp
+* Download the configured clojure-lsp version
+
+In the status bar, Calva will show an indicator with the clojure-lsp status.
+
+### Active clojure-lsp
+
+When clojure-lsp is downloaded, started and initialized the status bar indicator will look like so:
+
+!["Active clojure-lsp status bar item"](images/clojure-lsp/calva-clojure-lsp-statusbar-active.png "Active clojure-lsp status bar item")
+
+Clicking the item will bring up this menu:
+
+!["Active clojure-lsp menu"](images/clojure-lsp/calva-clojure-lsp-menu-active.png "Active clojure-lsp menu")
+
+See below about the [server info](#server-info-command) and [server log](#opening-the-server-log-file) commands.
+
+### Stopped clojure-lsp
+
+When clojure-lsp is stopped the status bar indicator will look like so:
+
+!["Inactive clojure-lsp status bar item"](images/clojure-lsp/calva-clojure-lsp-statusbar-inactive.png "Inactive clojure-lsp status bar item")
+
+The clojure-lsp inactive menu:
+
+!["Inactive clojure-lsp  menu"](images/clojure-lsp/calva-clojure-lsp-menu-inactive.png "Inactive clojure-lsp menu")
+
+The download option here will download the configured clojure-lsp version regardless if it is already installed or not. This can be useful when some earlier download has failed resulting in that clojure-lsp can't be started. *NB: It will not download anything if `calva.clojureLspPath` is set to something non-blank.*
+
+### Downloading and starting
+
+The statusbar item also will indicate when clojure-lsp is being downloaded and while it is starting.
 
 ## Ignoring LSP cache files
 

docs/site/formatting.md

@@ -7,7 +7,7 @@ description: Community Styleguide conforming formatting by default. And it just
 
 We have tried to make Calva's formatter so that it _just works_. It is enabled by default for Clojure files, and with the default configuration it mostly follows Bozhidar Batsov's [Clojure Style Guide](https://github.com/bbatsov/clojure-style-guide). Calva uses [cljfmt](https://github.com/weavejester/cljfmt) for the formatting.
 
-!!! Tips
+!!! Tips "Tab formats the current surrounding form"
     Calva's code formatter sets the default keybinding of its **Format Current Form** command to `tab`. Meaning that most often when things look a bit untidy, you can press `tab` to make things look pretty. Good to know, right? For performance reasons it only formats the current enclosing form, so sometimes you want to move the cursor up/out a form (`ctrl+up`) first. See [The Paredit Guide](paredit.md) for more on moving the cursor structurally through your code.
 
 With the default settings, Calva's formatting behaves like so:
@@ -19,7 +19,7 @@ With the default settings, Calva's formatting behaves like so:
 -   formats the current form, _aligning map keys and values_, when you press `ctrl+alt+l`
 -   formats `(comment ...)` forms special, see [rich comments](#rich-comments)
 
-!!! Tips
+!!! Tips "Infer parens at will"
     Calva has a command that will ”heal” the bracket structure if it is correctly indented using Parinfer **Infer parens**. This command is default bound to `ctrl+alt+p i`.
 
 Also: If you have **Format on Save** enabled in VS Code, it will be Calva doing the formatting for Clojure files.
@@ -37,14 +37,19 @@ Not a fan of some default setting? The formatter is quite configurable.
 
 You configure Calva's formatting using [cljfmt's configuration EDN](https://github.com/weavejester/cljfmt#configuration). This means that you can adjust the above mentioned defaults, including the indenting.
 
-This configuration can either be provided via a file or via clojure-lsp (see [Clojure LSP Settings](https://clojure-lsp.io/settings/)).
+This configuration can either be provided via a file or via clojure-lsp (see [Clojure LSP Settings]
+(https://clojure-lsp.io/settings/)).
 
-!!! Note
-    The `cljfmt` docs mention the `:cljfmt` config key of Leiningen projects. Calva does not yet read the config from there, so if your Leiningen project has such a configuration, you will need to copy it out into a file.
+??? Note "Only use the clojure-lsp config option if you need it"
+    The option to read formatting config from clojure-lsp is there to let teams where some members use clojure-lsp for formatting, share the config. To provide the settings via clojure-lsp, set `calva.fmt.configPath` to `CLOJURE-LSP` (case sensitive). However, there are limitations:
+
+    1. There is no config hot reloading support (see below)
+    1. clojure-lsp's cljfmt config is special in that it does not support regular Clojure syntax for regular expressions. This can make it difficult to run cljfmt as part of a CI pipline.
 
-To provide the settings via clojure-lsp, set `calva.fmt.configPath` to `CLOJURE-LSP` (case sensitive).
+??? Note "No Leiningen config support"
+    The **cljfmt** docs mention the `:cljfmt` config key of Leiningen projects. Calva does not yet read the config from there, so if your Leiningen project has such a configuration, you will need to copy it out into a file.
 
-If providing settings via a file, start changing the Calva formatting defaults by pasting the following map into a file and save it. It could be somewhere in the project workspace, or some other place, depending on your requirements:
+If providing settings via a file, start changing the Calva formatting defaults by pasting the following map into a file and save it. It could be somewhere in the project workspace (supporting hot reload), or some other place (no hot reload), depending on your requirements:
 
 ```clojure
 {:remove-surrounding-whitespace? true
@@ -61,10 +66,10 @@ Since you are editing the file in Calva (you are, right?), you can quickly test
 2. then save
 3. then hit `tab`, and see what happens.
 
-!!! Note
-    This particular setting is experimental and known to cause trouble together with namespaced keywords. Consider using `ctrl+alt+l` instead of `tab` as your formatting command, instead of enabling this setting. See below for more info about this.
+??? Note "`:align-associative?` is experimental"
+    This particular setting is experimental and known to cause trouble together with namespaced keywords. Consider using `ctrl+alt+l` instead of `tab` as your formatting command, instead of enabling this setting. See below for more info about this. See [more below](#about-aligning-associative-forms) about this.
 
-!!! Note
+!!! Note "Hot reloding requirements"
     The hot reloading of the config file only works for config files inside the project directory structure. And if you are providing the settings via clojure-lsp: no hot-reload for you.
 
 ### About aligning associative forms

docs/site/index.md

@@ -1,13 +1,13 @@
 ---
 title: Clojure Interactive Programming for Visual Studio Code
-description: Learn how to use Calva, an IDE bringing full Clojure and ClojureScript Interactive Programming to VS Code.
+description: Learn how to use Calva, a rich IDE for enjoyable and productive Clojure and ClojureScript Interactive Programming in VS Code.
 ---
 
 # Welcome!
 
 ![Calva Logo](https://raw.githubusercontent.com/BetterThanTomorrow/calva/dev/assets/calva-64h.png)
 
-[Calva](https://marketplace.visualstudio.com/items?itemName=betterthantomorrow.calva) is an integrated REPL powered environment for enjoyable and productive [Clojure](https://clojure.org) and [ClojureScript](https://clojurescript.org) development in [Visual Studio Code](https://code.visualstudio.com). It includes inline code evaluation, Paredit, code formatting, a test runner, syntax highlighting, [linting](linting.md), and more. [Calva is open source](https://github.com/BetterThanTomorrow/calva) and free to use.
+[Calva](https://marketplace.visualstudio.com/items?itemName=betterthantomorrow.calva) is an integrated, REPL powered, development environment for enjoyable and productive [Clojure](https://clojure.org) and [ClojureScript](https://clojurescript.org) programming in [Visual Studio Code](https://code.visualstudio.com). It includes inline [code evaluation](evaluation.md), [structural editing](paredit.md), code [formatting](formatting.md), code navigation, a [debugger](debugger.md), [linting](linting.md), syntax highlighting, Clojure aware rainbow brackets, a [test runner](test-runner.md), refactoring support, and more. A lot of effort has been put into making Calva a good choice to start if you are new to Clojure. [Calva is open source](https://github.com/BetterThanTomorrow/calva) and free to use.
 
 ## Getting Started
 

docs/site/rich-comments.md

@@ -80,6 +80,9 @@ With the cursor somewhere directly inside the comment form (denoted with a `|`):
   |)
 ```
 
+!!! Note "Only for the current comment form”
+    The special formatting only applies in the current `comment` form. When outside it, formatting tucks the closing paren in again. That's why fold when done, [below]](#fold-when-done) works like it does. This also applies to VS Code commands like **Format Document**, or when you have **Format On Save** enabled. There are several reasons for this, and one is that there is no `cljfmt` config for it and leaving the closing comment un-tucked might give you troubles with CI pipelines that enforce some cljfmt config be followed. (Another reason is that it would be pretty hard to do on the whole document.)
+
 #### Thinking space is kept
 
 The formatter will not remove newlines between the cursor and the closing bracket. So if you have entered a few lines to get ”thinking” room: