Skip to content

Commit d69008f

Browse files
axvraxvr
committed
Update indentation options sections of the README and vim help file
1 parent eb0463e commit d69008f

File tree

2 files changed

+59
-153
lines changed

2 files changed

+59
-153
lines changed

‎README.md

+35-73
Original file line numberDiff line numberDiff line change
@@ -71,96 +71,58 @@ disabled by default.
7171

7272
### Indent options
7373

74-
Clojure indentation differs somewhat from traditional Lisps, due in part to
75-
the use of square and curly brackets, and otherwise by community convention.
76-
These conventions are not universally followed, so the Clojure indent script
77-
offers a few configuration options.
74+
By default Clojure.vim will attempt to follow the indentation rules in the
75+
[Clojure Style Guide](https://guide.clojure.style), but various configuration
76+
options are provided to alter the indentation as you prefer.
7877

79-
(If the current Vim does not include `searchpairpos()`, the indent script falls
80-
back to normal `'lisp'` indenting, and the following options are ignored.)
78+
> **Warning**<br>
79+
> If your installation of Vim does not include `searchpairpos()`, the indent
80+
> script falls back to normal `'lisp'` and `'lispwords'` indenting, ignoring
81+
> the following indentation options.
8182
8283

83-
#### `g:clojure_maxlines`
84+
#### `clojure_indent_rules`
8485

85-
Sets maximum scan distance of `searchpairpos()`. Larger values trade
86-
performance for correctness when dealing with very long forms. A value of
87-
0 will scan without limits. The default is 300.
86+
> **Note**<br>
87+
> The indentation code was recently rebuilt, which included the removal of
88+
> several former configuration options (`clojure_fuzzy_indent`,
89+
> `clojure_fuzzy_indent_patterns`, `clojure_fuzzy_indent_blacklist`,
90+
> `clojure_special_indent_words`, `clojure_cljfmt_compat` and now ignores the
91+
> value of `'lispwords'`).
92+
>
93+
> All of those options were rolled into this new option.
8894
8995

90-
#### `g:clojure_fuzzy_indent`, `g:clojure_fuzzy_indent_patterns`, `g:clojure_fuzzy_indent_blacklist`
96+
#### `clojure_align_multiline_strings`
9197

92-
The `'lispwords'` option is a list of comma-separated words that mark special
93-
forms whose subforms should be indented with two spaces.
94-
95-
For example:
96-
97-
```clojure
98-
(defn bad []
99-
"Incorrect indentation")
100-
101-
(defn good []
102-
"Correct indentation")
103-
```
104-
105-
If you would like to specify `'lispwords'` with a pattern instead, you can use
106-
the fuzzy indent feature:
107-
108-
```vim
109-
" Default
110-
let g:clojure_fuzzy_indent = 1
111-
let g:clojure_fuzzy_indent_patterns = ['^with', '^def', '^let']
112-
let g:clojure_fuzzy_indent_blacklist = ['-fn$', '\v^with-%(meta|out-str|loading-context)$']
113-
```
114-
115-
`g:clojure_fuzzy_indent_patterns` and `g:clojure_fuzzy_indent_blacklist` are
116-
lists of patterns that will be matched against the unqualified symbol at the
117-
head of a list. This means that a pattern like `"^foo"` will match all these
118-
candidates: `foobar`, `my.ns/foobar`, and `#'foobar`.
119-
120-
Each candidate word is tested for special treatment in this order:
121-
122-
1. Return true if word is literally in `'lispwords'`
123-
2. Return false if word matches a pattern in `g:clojure_fuzzy_indent_blacklist`
124-
3. Return true if word matches a pattern in `g:clojure_fuzzy_indent_patterns`
125-
4. Return false and indent normally otherwise
126-
127-
128-
#### `g:clojure_special_indent_words`
129-
130-
Some forms in Clojure are indented such that every subform is indented by only
131-
two spaces, regardless of `'lispwords'`. If you have a custom construct that
132-
should be indented in this idiosyncratic fashion, you can add your symbols to
133-
the default list below.
134-
135-
```vim
136-
" Default
137-
let g:clojure_special_indent_words = 'deftype,defrecord,reify,proxy,extend-type,extend-protocol,letfn'
138-
```
139-
140-
141-
#### `g:clojure_align_multiline_strings`
142-
143-
Align subsequent lines in multi-line strings to the column after the opening
144-
quote, instead of the same column.
145-
146-
For example:
98+
Alter alignment of newly created lines within multi-line strings (and regular
99+
expressions).
147100

148101
```clojure
102+
;; let g:clojure_align_multiline_strings = 0 " Default
149103
(def default
150104
"Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
151-
eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
152-
enim ad minim veniam, quis nostrud exercitation ullamco laboris
153-
nisi ut aliquip ex ea commodo consequat.")
105+
eiusmod tempor incididunt ut labore et dolore magna aliqua.")
154106

107+
;; let g:clojure_align_multiline_strings = 1
155108
(def aligned
156109
"Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
157-
eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
158-
enim ad minim veniam, quis nostrud exercitation ullamco laboris
159-
nisi ut aliquip ex ea commodo consequat.")
110+
eiusmod tempor incididunt ut labore et dolore magna aliqua.")
111+
112+
;; let g:clojure_align_multiline_strings = -1
113+
(def traditional
114+
"Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
115+
eiusmod tempor incididunt ut labore et dolore magna aliqua.")
160116
```
161117

118+
There is also a buffer-local (`b:`) version of this option.
119+
120+
> **Note**<br>
121+
> Indenting the string with `=` will not alter the indentation of existing
122+
> multi-line strings as that would break intentional formatting.
123+
162124

163-
#### `g:clojure_align_subforms`
125+
#### `clojure_align_subforms`
164126

165127
By default, parenthesized compound forms that look like function calls and
166128
whose head subform is on its own line have subsequent subforms indented by

‎doc/clojure.txt

+24-80
Original file line numberDiff line numberDiff line change
@@ -7,92 +7,44 @@ Clojure runtime files for Vim.
77

88
CLOJURE *ft-clojure-indent* *clojure-indent*
99

10-
Clojure indentation differs somewhat from traditional Lisps, due in part to
11-
the use of square and curly brackets, and otherwise by community convention.
12-
These conventions are not universally followed, so the Clojure indent script
13-
offers a few configuration options.
10+
By default Clojure.vim will attempt to follow the indentation rules in the
11+
Clojure Style Guide, [1] but various configuration options are provided to
12+
alter the indentation as you prefer.
1413

15-
(If the current Vim does not include |searchpairpos()|, the indent script falls
16-
back to normal 'lisp' indenting, and the following options are ignored.)
14+
[1]: https://guide.clojure.style
1715

16+
WARNING: if your installation of Vim does not include `searchpairpos()`, the
17+
indent script falls back to normal 'lisp' and 'lispwords' indenting,
18+
ignoring the following indentation options.
1819

19-
*g:clojure_maxlines*
20+
*b:clojure_indent_rules*
21+
*g:clojure_indent_rules*
2022

21-
Sets maximum scan distance of `searchpairpos()`. Larger values trade
22-
performance for correctness when dealing with very long forms. A value of
23-
0 will scan without limits. The default is 300.
24-
25-
26-
*g:clojure_fuzzy_indent*
27-
*g:clojure_fuzzy_indent_patterns*
28-
*g:clojure_fuzzy_indent_blacklist*
29-
30-
The 'lispwords' option is a list of comma-separated words that mark special
31-
forms whose subforms should be indented with two spaces.
32-
33-
For example:
34-
>
35-
(defn bad []
36-
"Incorrect indentation")
37-
38-
(defn good []
39-
"Correct indentation")
40-
<
41-
If you would like to specify 'lispwords' with a |pattern| instead, you can use
42-
the fuzzy indent feature:
43-
>
44-
" Default
45-
let g:clojure_fuzzy_indent = 1
46-
let g:clojure_fuzzy_indent_patterns = ['^with', '^def', '^let']
47-
let g:clojure_fuzzy_indent_blacklist =
48-
\ ['-fn$', '\v^with-%(meta|out-str|loading-context)$']
49-
<
50-
|g:clojure_fuzzy_indent_patterns| and |g:clojure_fuzzy_indent_blacklist| are
51-
lists of patterns that will be matched against the unqualified symbol at the
52-
head of a list. This means that a pattern like `"^foo"` will match all these
53-
candidates: `foobar`, `my.ns/foobar`, and `#'foobar`.
54-
55-
Each candidate word is tested for special treatment in this order:
56-
57-
1. Return true if word is literally in 'lispwords'
58-
2. Return false if word matches a pattern in
59-
|g:clojure_fuzzy_indent_blacklist|
60-
3. Return true if word matches a pattern in
61-
|g:clojure_fuzzy_indent_patterns|
62-
4. Return false and indent normally otherwise
63-
64-
65-
*g:clojure_special_indent_words*
66-
67-
Some forms in Clojure are indented such that every subform is indented by only
68-
two spaces, regardless of 'lispwords'. If you have a custom construct that
69-
should be indented in this idiosyncratic fashion, you can add your symbols to
70-
the default list below.
71-
>
72-
" Default
73-
let g:clojure_special_indent_words =
74-
\ 'deftype,defrecord,reify,proxy,extend-type,extend-protocol,letfn'
75-
<
23+
TODO: add this option and write this section.
7624

25+
*b:clojure_align_multiline_strings*
7726
*g:clojure_align_multiline_strings*
7827

79-
Align subsequent lines in multi-line strings to the column after the opening
80-
quote, instead of the same column.
81-
82-
For example:
28+
Alter alignment of newly created lines within multi-line strings (and regular
29+
expressions).
8330
>
31+
;; let g:clojure_align_multiline_strings = 0 " Default
8432
(def default
8533
"Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
86-
eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
87-
enim ad minim veniam, quis nostrud exercitation ullamco laboris
88-
nisi ut aliquip ex ea commodo consequat.")
34+
eiusmod tempor incididunt ut labore et dolore magna aliqua.")
8935
36+
;; let g:clojure_align_multiline_strings = 1
9037
(def aligned
9138
"Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
92-
eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
93-
enim ad minim veniam, quis nostrud exercitation ullamco laboris
94-
nisi ut aliquip ex ea commodo consequat.")
39+
eiusmod tempor incididunt ut labore et dolore magna aliqua.")
40+
41+
;; let g:clojure_align_multiline_strings = -1
42+
(def traditional
43+
"Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
44+
eiusmod tempor incididunt ut labore et dolore magna aliqua.")
9545
<
46+
NOTE: indenting the string with |=| will not alter the indentation of existing
47+
multi-line strings as that would break intentional formatting.
9648

9749
*g:clojure_align_subforms*
9850

@@ -113,14 +65,6 @@ clojure-mode.el:
11365
baz)
11466
<
11567

116-
*g:clojure_cljfmt_compat*
117-
118-
Try to be (more) compatible with `cljfmt` Clojure code formatting tool. Turns
119-
on single space indenting for forms starting with `:keywords`, `'symbols`,
120-
`#'variables` and `@dereferences` (it affects, for instance, `(:require ...)`
121-
clause in Clojure `ns` form).
122-
123-
12468
CLOJURE *ft-clojure-syntax*
12569

12670
*g:clojure_syntax_keywords*

0 commit comments

Comments
 (0)