Update README, CHANGELOG, install.txt and 4.0.0.txt

Author: tonsky

CHANGELOG.md

@@ -1,4 +1,4 @@
-### WIP
+### 4.0.0 - Aug 23, 2024
 
 Syntax has been significantly reworked.
 

README.md

@@ -2,46 +2,70 @@
 
 This package provides Clojure support for Sublime Text and includes:
 
-- Clojure and EDN syntax grammars (Sublime Text 3+)
-- Code formatter/indenter (Sublime Text 4075+)
-- nREPL, Socket REPL, ShadowCLJS REPL clients (Sublime Text 4075+)
+- Clojure syntax
+- Color scheme
+- Code formatter/indenter
+- Clients for nREPL, Socket REPL, ShadowCLJS REPL
+
 
 # Installation
 
 `Package Control: Install Package` → `Clojure Sublimed`
 
+
 # Clojure syntax
 
-<img src="https://raw.github.com/tonsky/Clojure-Sublimed/master/screenshots/syntaxes.png" width="463" height="362" alt="Syntaxes">
+<img src="https://raw.github.com/tonsky/Clojure-Sublimed/master/screenshots/syntaxes.png" width="710" height="796" alt="Syntaxes">
 
-Clojure Sublimed ships with its own syntax definition for Clojure and EDN. Unlike default Clojure syntax, this package is:
+Clojure Sublimed ships with its own syntax definition for Clojure and EDN. Unlike default Clojure syntax, our syntax can:
 
-- slightly more pedantic as per [EDN spec](https://github.com/edn-format/edn) and [Clojure Reader](https://clojure.org/reference/reader),
-- rigorously tested,
-- can be used to highlight rainbow parentheses,
-- punctuation and validation _inside_ regexps,
-- quoted and unquoted regions are marked for highlighting,
-- semantically correct tokenization, perfect for fonts with ligatures,
-- has separate EDN syntax, same way JSON is separate from JavaScript in Sublime Text.
+- mark reader comments `#_` with the following form, including stacked comments,
+- mark `comment` forms,
+- mark quoted/unquoted forms,
+- mark metadata,
+- mark parentheses nesting,
+- mark and validate punctuation inside regexps,
+- do semantically correct tokenization, perfect for fonts with ligatures,
 
 How to enable? Assign syntax to Clojure files:
 
-- open any clj/cljc/cljs file,
-- run `View` → `Syntax` → `Open all with current extension as...` → `Clojure Sublimed` → `Clojure (Sublimed)`.
+For each file type (.clj, .cljs, .cljc, .edn) do:
+
+- Open any file with that extension
+- Go to menu -> `View` → `Syntax` → `Open all with current extension as...`
+- Select `Clojure (Sublimed)`
+
+Want to put your parser to test? Check out [syntax_test_clojure.cljc](./test_syntax/syntax_test_clojure.cljc).
+
+
+# Color scheme
+
+<img src="https://raw.github.com/tonsky/Clojure-Sublimed/master/screenshots/scheme.png" width="850" height="508" alt="Color Scheme">
+
+To make best use of improved syntax definitions, Clojure Submiled offers its own color scheme:
+
+- Cmd/Ctrl + Shift + P (Command Palette)
+- `UI: Select Color Scheme`
+- Select `Auto` -> `Clojure Sublimed Light` -> `Clojure Sublimed Dark`
+
+These color schemes will work for other languages, too.
 
-Want to put your parser to test? Check out [syntax_test_edn.edn](./test_syntax/syntax_test_edn.edn) and [syntax_test_clojure.cljc](./test_syntax/syntax_test_clojure.cljc).
 
 # Formatter/indenter
 
-Clojure Sublimed includes support for both [Simple Clojure Formatting rules](https://tonsky.me/blog/clojurefmt/) and [cljfmt](https://github.com/weavejester/cljfmt/).
+Clojure Sublimed includes support for both [Better Clojure Formatting](https://tonsky.me/blog/clojurefmt/) and [cljfmt](https://github.com/weavejester/cljfmt/).
 
-Simple Clojure Formatting doesn’t require REPL connection, any Clojure runtime or external tools. It is enabled by default.
+Better Clojure Formatting doesn’t require REPL connection, Clojure runtime or external tools. It is enabled by default.
 
-`cljfmt` requires `cljfmt` binary to be on `$PATH`. Enable it by setting `"formatter": "cljfmt"` in Clojure Sublimed settings.
+To enable `cljfmt`:
+
+- Download `cljfmt` binary from `https://github.com/weavejester/cljfmt/releases/latest`
+- Add `cljfmt` to `$PATH`
+- Add `"clojure_sublimed_formatter": "cljfmt"` to `Preferences: Settings`
 
 To reformat whole file, run `Clojure Sublimed: Reindent`. If you have non-empty selection, it will only reformat selected lines.
 
-To enable reindenting/formatting on save, add `"format_on_save": true` to settings. ([See how to edit settings](#editing-settings))
+To enable reindenting/formatting on save, add `"clojure_sublimed_format_on_save": true` to `Preferences: Settings`.
 
 To enable correct indentations as you type code, rebind `Enter` to `Clojure Sublimed: Insert Newline`:
 
@@ -53,7 +77,6 @@ To enable correct indentations as you type code, rebind `Enter` to `Clojure Subl
              {"key": "panel_has_focus", "operator": "equal", "operand": false}]}
 ```
 
-Best way to do it is through running `Preferences: Clojure Sublimed Key Bindings`.
 
 # REPL clients
 
@@ -89,16 +112,23 @@ How to choose which REPL to use?
 1. Are you on JVM? Use Socket REPL.
 2. On JVM and only have nREPL? Use JVM nREPL.
 3. CLJS? Use ShadowCLJS REPL.
-4. Otherwise (e.g. babashka) use Raw nREPL.
+4. Otherwise (e.g. babashka, sci, ...) use Raw nREPL.
 
 We intentionally excluded following features:
 
 - [ ] Autocomplete. Static analysis is much simpler and much more reliable than requiring an always-live connection to the working app.
 
 Look at [Sublime LSP](https://github.com/sublimelsp/LSP) with [Clojure LSP](https://github.com/clojure-lsp/clojure-lsp) or [SublimeLinter](https://github.com/SublimeLinter/SublimeLinter) with [clj-kondo](https://github.com/ToxicFrog/SublimeLinter-contrib-clj-kondo) if you need autocompletion.
 
+
 # How to use
 
+Clojure Sublimed will not run your app for you. Use any other way, e.g.:
+
+- Separate terminal app
+- Terminus plugin
+- Sublime Executor plugin
+
 For Clojure apps:
 
 1. Run Socket Server, e.g. with either
@@ -126,6 +156,7 @@ For other nREPL apps:
 1. Run nREPL server.
 2. Run `Clojure Sublimed: Connect to raw nREPL` command.
 
+
 ## Evaluating code from buffer
 
 From here you have three options:
@@ -150,16 +181,19 @@ By default, Clojure Sublimed will also print evaluation time if it takes more th
 
 <img src="https://raw.github.com/tonsky/Clojure-Sublimed/master/screenshots/eval_elapsed.png" width="500" height="139" alt="Elapsed time">
 
+
 ## Copying evaluation results
 
 Sometimes you want to copy evaluation result. It is recommended to rebind `Cmd+C`/`Ctrl+C` from `copy` to `sublime_clojure_copy`. This will copy evaluation result if inside evaluated region and fallback to default `copy` otherwise.
 
+
 ## Interrupting
 
 If your evaluation runs too long and you want to interrupt it, run `Clojure Sublimed: Interrupt Pending Evaluations`:
 
 <img src="https://raw.github.com/tonsky/Clojure-Sublimed/master/screenshots/interrupt.png" width="587" height="39" alt="Interrupt">
 
+
 ## Opening stacktrace
 
 If your evaluation failed, put your cursor inside failed region and run `Clojure Sublimed: Toggle Stacktrace`:
@@ -170,6 +204,7 @@ Clojure Sublimed will display stacktraces in a Clojure-friendly way. Compare wit
 
 <img src="https://raw.github.com/tonsky/Clojure-Sublimed/master/screenshots/stacktraces.png" width="806" height="390" alt="Stacktraces">
 
+
 ## Watches
 
 Watches are great alternative to debug prints: they allow you to monitor intermediate values during function execution right in the editor.
@@ -184,6 +219,7 @@ This is how they work:
 
 Watches are only supported in Socket REPL.
 
+
 ## Looking up symbol
 
 To show symbol info, run `Clojure Sublimed: Toggle Symbol Info`:
@@ -192,6 +228,7 @@ To show symbol info, run `Clojure Sublimed: Toggle Symbol Info`:
 
 Universal `Clojure Sublimed: Toggle Info` command acts as either `Toggle Stacktrace` or `Toggle Symbol Info`, depending on context.
 
+
 ## Binding keys to eval custom code
 
 Every project is different, and sometimes it’s convenient to run a piece of code so often you’d want it on a shortcut. It might be a namespace reload, test execution, database reconnect, linter, formatter — possibilities are endless.
@@ -226,6 +263,7 @@ Reload code with [clj-reload](https://github.com/tonsky/clj-reload):
  "args":    {"code": "(clj-reload.core/reload)"}}
 ```
 
+
 ## Transforming code before eval
 
 You can also modify eval to run a transformed version of code under cursor/inside selection.
@@ -289,10 +327,12 @@ Run test under cursor at work:
 
 ![](./screenshots/test_under_cursor.gif)
 
+
 ## Clearing results
 
 Finally, to clear evaluation results run `Clojure Sublimed: Clear Evaluation Results`.
 
+
 ## Editing settings
 
 To edit settings, run `Preferences: Clojure Sublimed Settings` command.
@@ -311,6 +351,7 @@ in `Clojure Sublimed.sublime-settings` becomes
 
 in `Preferences.sublime-settings`. Settings from `Preferences.sublime-settings` take priority.
 
+
 ## Session-wide settings
 
 It is sometimes desirable to set dynamic Clojure vars for the whole session. To do that, edit `"eval_shared"` setting. For example:
@@ -321,6 +362,7 @@ It is sometimes desirable to set dynamic Clojure vars for the whole session. To
 
 This will be applied to every evaluation.
 
+
 # Default Key Bindings
 
 Clojure Sublimed comes with no keybindings enabled by default to guarantee they won’t conflict with any other extension (Sublime Text’s limitation).

messages/4.0.0.txt

@@ -0,0 +1,27 @@
+Clojure Sublimed 4.0.0
+----------------------
+
+Two major new features:
+
+# Code formatting
+
+By default, Clojure Sublimed uses [Better Clojure Formatting style](https://tonsky.me/blog/clojurefmt/).
+
+Starting with 4.0.0, you can switch to `cljftm` instead:
+
+- Download `cljfmt` binary from `https://github.com/weavejester/cljfmt/releases/latest`
+- Add `cljfmt` to `$PATH`
+- In Sublime Text, open `Preferences: Settings`
+- Add `"clojure_sublimed_formatter": "cljfmt"`
+
+# Color scheme
+
+4.0.0 ships major improvement in syntax definitons for Clojure.
+
+To make best use of them, we now offer color scheme that makes use of many of these features.
+
+- Cmd/Ctrl + Shift + P (Command Palette)
+- `UI: Select Color Scheme`
+- Select `Auto` -> `Clojure Sublimed Light` -> `Clojure Sublimed Dark`
+
+These color schemes will work for other languages, too.

messages/install.txt

@@ -1,10 +1,84 @@
 Hi there! Thank you for installing Clojure Sublimed.
 
-A few important points to help you get started:
+How to get started:
 
-- Assign `Clojure (Sublimed)` syntax to your Clojure files: `View` → `Syntax` → `Open all with current extension as...` → `Clojure Sublimed` → `Clojure (Sublimed)` (this step is required for everything else to work)
-- Make sure you have nREPL version 0.8+
-- Connect using `Clojure Sublimed: Connect`
-- Configure key bindings using `Preferences: Clojure Sublimed Key Bindings`
+
+Associate syntax with *.clj* files (only needs to be done once)
+---------------------------------------------------------------
+
+For each file type (.clj, .cljs, .cljc, .edn) do:
+
+- Open any file with that extension
+- Go to menu -> `View` → `Syntax` → `Open all with current extension as...`
+- Select `Clojure (Sublimed)`
+
+
+Key bindings
+------------
+
+Sublime has no good way to ship optional key bindings with plugin. So
+
+- Cmd/Ctrl + Shift + P (Command Palette)
+- `Preferences: Clojure Sublimed Key Bindings`
+- Copy examples from the left to your config on the right
+
+I recomment at least:
+
+- Evaluate
+- Evaluate Buffer
+- Interrupt Pending Evaluations
+- Clear Evaluation Results
+- Reindent
+- Insert New Line
+
+
+Code formatting
+---------------
+
+By default, Clojure Sublimed uses [Better Clojure Formatting style](https://tonsky.me/blog/clojurefmt/).
+
+If you want to use `cljftm`:
+
+- Download `cljfmt` binary from `https://github.com/weavejester/cljfmt/releases/latest`
+- Add `cljfmt` to `$PATH`
+- In Sublime Text, open `Preferences: Settings`
+- Add `"clojure_sublimed_formatter": "cljfmt"`
+
+Color scheme
+------------
+
+If you want to try our color scheme:
+
+- Cmd/Ctrl + Shift + P (Command Palette)
+- `UI: Select Color Scheme`
+- Select `Auto` -> `Clojure Sublimed Light` -> `Clojure Sublimed Dark`
+
+These color schemes will work for other languages, too.
+
+
+Running your app
+----------------
+
+Clojure Sublimed will not run your app for you. A few alternatives instead:
+
+- Use separate terminal app
+- Terminus plugin
+- Sublime Executor plugin
+
+
+Connecting to REPLs
+-------------------
+
+Depending on what type of REPL your run, use following commands:
+
+- JVM nREPL → `Clojure Sublimed: Connect to nREPL JVM`
+- Shadow CLJS client-side → `Clojure Sublimed: Connect to shadow-cljs`
+- Shadow CLJS server-side → `Clojure Sublimed: Connect to raw nREPL`
+- Socket REPL on JVM → `Clojure Sublimed: Connect to Socket REPL`
+- Any other nREPL (babashka, sci, ...) → `Clojure Sublimed: Connect to raw nREPL`
+
+Clojure Sublimed can only run one REPL connection per window.
+
+Minimal supported nREPL version is 0.9.
 
 Read more at https://github.com/tonsky/Clojure-Sublimed/blob/master/README.md