branch: elpa/clojure-mode
commit 3238096e7637205ac109fe6b28d7a088848d2f15
Author: Bozhidar Batsov <bozhi...@batsov.dev>
Commit: Bozhidar Batsov <bozhi...@batsov.dev>
Improve the markup of the README
---
README.md | 80 ++++++++++++++++++++++++++++++++++++++-------------------------
1 file changed, 48 insertions(+), 32 deletions(-)
diff --git a/README.md b/README.md
index 24d154a454..f8ce6bf410 100644
--- a/README.md
+++ b/README.md
@@ -11,13 +11,13 @@
highlighting), indentation, navigation and refactoring support for the
[Clojure(Script) programming language](https://clojure.org).
------------
-
-**This documentation tracks the `master` branch of `clojure-mode`. Some of
-the features and settings discussed here might not be available in
-older releases (including the current stable release). Please, consult
-the relevant git tag (e.g.
[5.19.0](https://github.com/clojure-emacs/clojure-mode/tree/v5.19.0)) if you
need documentation for a
-specific `clojure-mode` release.**
+> [!IMPORTANT]
+>
+> This documentation tracks the `master` branch of `clojure-mode`. Some of the
+> features and settings discussed here might not be available in older releases
+> (including the current stable release). Please, consult the relevant git tag
+> (e.g. [5.20.0](https://github.com/clojure-emacs/clojure-mode/tree/v5.20.0))
if
+> you need documentation for a specific `clojure-mode` release.
## Installation
@@ -47,12 +47,12 @@ If the installation doesn't work try refreshing the package
list:
The `clojure-mode` package actually bundles together several major modes:
-* `clojure-mode` is a major mode for editing Clojure code
-* `clojurescript-mode` is a major mode for editing ClojureScript code
-* `clojurec-mode` is a major mode for editing `.cljc` source files
-* `clojuredart-mode` is a major mode for editing ClojureDart `.cljd` source
files
-* `jank-mode` is a major mode for editing Jank `.jank` source files
-* `joker-mode` is a major mode for editing Joker `.joke` source files
+- `clojure-mode` is a major mode for editing Clojure code
+- `clojurescript-mode` is a major mode for editing ClojureScript code
+- `clojurec-mode` is a major mode for editing `.cljc` source files
+- `clojuredart-mode` is a major mode for editing ClojureDart `.cljd` source
files
+- `jank-mode` is a major mode for editing Jank `.jank` source files
+- `joker-mode` is a major mode for editing Joker `.joke` source files
All the major modes derive from `clojure-mode` and provide more or less the
same
functionality. Differences can be found mostly in the font-locking -
@@ -140,14 +140,16 @@ The indentation of function forms is configured by the
variable
2)
```
-**Note:** Prior to clojure-mode 5.10, the configuration options for
`clojure-indent-style` used to be
-keywords, but now they are symbols. Keywords will still be supported at least
until clojure-mode 6.
+> [!NOTE]
+>
+> Prior to clojure-mode 5.10, the configuration options for
`clojure-indent-style` used to be
+> keywords, but now they are symbols. Keywords will still be supported at
least until clojure-mode 6.
#### Indentation of keywords
Similarly we have the `clojure-indent-keyword-style`, which works in the
following way:
-* `always-align` (default) - All
+- `always-align` (default) - All
args are vertically aligned with the first arg in case (A),
and vertically aligned with the function name in case (B).
@@ -159,7 +161,7 @@ Similarly we have the `clojure-indent-keyword-style`, which
works in the followi
[bar.baz])
```
-* `always-indent` - All args are indented like a macro body.
+- `always-indent` - All args are indented like a macro body.
``` clojure
(:require [foo.bar]
@@ -169,7 +171,7 @@ Similarly we have the `clojure-indent-keyword-style`, which
works in the followi
0)
```
-* `align-arguments` - Case (A) is indented like `always-align`, and
+- `align-arguments` - Case (A) is indented like `always-align`, and
case (B) is indented like a macro body.
``` clojure
@@ -288,7 +290,11 @@ You can change this behaviour like this:
You might also want to change `comment-add` to 0 in that way, so that Emacs
comment
functions (e.g. `comment-region`) would use `;` by default instead of `;;`.
-**Note:** Check out [this section](https://guide.clojure.style/#comments) of
the Clojure style guide to understand better the semantics of the different
comment levels and why `clojure-mode` treats them differently by default.
+> [!TIP]
+>
+> Check out [this section](https://guide.clojure.style/#comments) of the
Clojure
+> style guide to understand better the semantics of the different comment
levels
+> and why `clojure-mode` treats them differently by default.
### Vertical alignment
@@ -315,9 +321,11 @@ happen whenever you select some code and hit `TAB`.
### Font-locking
-`clojure-mode` features static font-locking (syntax highlighting) that you can
extend yourself
-if needed. As typical for Emacs, it's based on regular expressions. You can
find
-the default font-locking rules in `clojure-font-lock-keywords`. Here's how you
can add font-locking for built-in Clojure functions and vars:
+`clojure-mode` features static font-locking (syntax highlighting) that you can
+extend yourself if needed. As typical for Emacs, it's based on regular
+expressions. You can find the default font-locking rules in
+`clojure-font-lock-keywords`. Here's how you can add font-locking for built-in
+Clojure functions and vars:
``` el
(defvar clojure-built-in-vars
@@ -360,9 +368,12 @@ var a symbol resolves to). That's why `clojure-mode`'s
font-locking defaults are
conservative and minimalistic.
Precise font-locking requires additional data that can obtained from a running
-REPL (that's how CIDER's [dynamic
font-locking](https://docs.cider.mx/cider/config/syntax_highlighting.html)
works) or from static code analysis.
+REPL (that's how CIDER's [dynamic
+font-locking](https://docs.cider.mx/cider/config/syntax_highlighting.html)
+works) or from static code analysis.
-When it comes to non built-in definitions, `clojure-mode` needs to be manually
instructed how to handle the docstrings and highlighting. Here's an example:
+When it comes to non built-in definitions, `clojure-mode` needs to be manually
+instructed how to handle the docstrings and highlighting. Here's an example:
``` emacs-lisp
(put '>defn 'clojure-doc-string-elt 2)
@@ -373,7 +384,9 @@ When it comes to non built-in definitions, `clojure-mode`
needs to be manually i
1 font-lock-keyword-face)))
```
-**Note:** The `clojure-doc-string-elt` attribute is processed by the function
`clojure-font-lock-syntactic-face-function`.
+> [!NOTE]
+>
+> The `clojure-doc-string-elt` attribute is processed by the function
`clojure-font-lock-syntactic-face-function`.
## Refactoring support
@@ -481,7 +494,7 @@ without affecting the namespace declaration.
## Related packages
-* [clojure-mode-extra-font-locking][] provides additional font-locking
+- [clojure-mode-extra-font-locking][] provides additional font-locking
for built-in methods and macros. The font-locking is pretty
imprecise, because it doesn't take namespaces into account and it
won't font-lock a function at all possible positions in a sexp, but
@@ -502,9 +515,9 @@ plenty of incorrect font-locking. CIDER users should avoid
this package,
as CIDER does its own dynamic font-locking, which is namespace-aware
and doesn't produce almost any false positives.
-* [clj-refactor][] provides refactoring support.
+- [clj-refactor][] provides additional refactoring support.
-* Enabling `CamelCase` support for editing commands(like
+- Enabling `CamelCase` support for editing commands (like
`forward-word`, `backward-word`, etc) in `clojure-mode` is quite
useful since we often have to deal with Java class and method
names. The built-in Emacs minor mode `subword-mode` provides such
@@ -514,7 +527,7 @@ functionality:
(add-hook 'clojure-mode-hook #'subword-mode)
```
-* The use of [paredit][] when editing Clojure (or any other Lisp) code
+- The use of [paredit][] when editing Clojure (or any other Lisp) code
is highly recommended. It helps ensure the structure of your forms is
not compromised and offers a number of operations that work on code
structure at a higher level than just characters and words. To enable
@@ -524,7 +537,7 @@ it for Clojure buffers:
(add-hook 'clojure-mode-hook #'paredit-mode)
```
-* [smartparens][] is an excellent
+- [smartparens][] is an excellent
(newer) alternative to paredit. Many Clojure hackers have adopted it
recently and you might want to give it a try as well. To enable
`smartparens` use the following code:
@@ -533,7 +546,7 @@ it for Clojure buffers:
(add-hook 'clojure-mode-hook #'smartparens-strict-mode)
```
-* [RainbowDelimiters][] is a
+- [RainbowDelimiters][] is a
minor mode which highlights parentheses, brackets, and braces
according to their depth. Each successive level is highlighted in a
different color. This makes it easy to spot matching delimiters,
@@ -545,7 +558,7 @@ it for Clojure buffers:
(add-hook 'clojure-mode-hook #'rainbow-delimiters-mode)
```
-* [aggressive-indent-mode][] automatically adjust the indentation of your code,
+- [aggressive-indent-mode][] automatically adjust the indentation of your code,
while you're writing it. Using it together with `clojure-mode` is highly
recommended. Provided you've already installed `aggressive-indent-mode` you can
enable it like this:
@@ -554,6 +567,9 @@ enable it like this:
(add-hook 'clojure-mode-hook #'aggressive-indent-mode)
```
+Note that it might cause performance issues if you're dealing with large
+Clojure source files.
+
## REPL Interaction
One of the fundamental aspects of Lisps in general, and Clojure in
