Move indent documentation into own file

Author: weavejester

README.md

@@ -0,0 +1,311 @@
+# Indentation
+
+When we talk about how rules affect indentation of source code, we
+refer to <code>(foo arg<sub>1</sub> arg<sub>2</sub>...
+arg<sub>n</sub>)</code> as a form, `foo` as a form symbol, and
+<code>arg<sub>1</sub> arg<sub>2</sub> ...  arg<sub>n</sub></code> as
+form arguments.
+
+The default indentation rules are encoded
+[here](cljfmt/resources/cljfmt/).
+
+Rules affect indentation of form arguments. A form argument is
+eligible for indentation only when it is the first element on a line.
+
+An indentation rule specifies an indentation type and indentation type
+arguments. One or more rules can be applied to a form symbol.
+
+Indentation types are:
+
+* `:inner` -
+  two character indentation applied to form arguments at a depth
+  relative to a form symbol
+
+* `:block` -
+  first argument aligned indentation applied to form arguments at form
+  depth 0 for a symbol
+
+## Form depth
+
+A rule for depth n affects indentation of form arguments relative to
+form symbol at depth n.
+
+Form depth is the nested depth of any element within the form.
+
+A contrived example will help to explain depth:
+
+```clojure
+(foo
+ bar
+ (baz
+  (qux plugh)
+  corge)
+ (grault
+  waldo
+  (thud wubble flob)))
+```
+
+If we look at the example code as a tree, we can visualize the effect
+of different form depths relative to `foo`:
+
+![form depth 0 diagram](images/form-depth-0.png)
+![form depth 1 diagram](images/form-depth-1.png)
+![form depth 2 diagram](images/form-depth-2.png)
+
+## Default behavior
+
+In the absence of indentation rules:
+
+```clojure
+(foo bar                           (foo bar
+baz            == formats to =>         baz
+bang)                                   bang)
+```
+
+```clojure
+(foo                               (foo
+bar            == formats to =>     bar
+bang)                               bang)
+```
+
+## Inner rules
+
+The `:inner` rule applies an indentation of two spaces to all eligible
+form arguments of forms at a given form depth. It has 2 rule type
+arguments:
+
+* `form-depth` -
+  apply inner indentation within forms at this depth
+
+* `limit-to-form-index` -
+  optionally limit indentation formatting to a single form, by default
+  formatting is applied to all forms at `form-depth`
+
+Indent rule:
+
+```clojure
+{foo [[:inner 0]]}
+```
+
+Will indent all arguments for symbol `foo` at depth `0` by two spaces:
+
+```clojure
+(foo bar                           (foo bar
+baz            == formats to =>      baz
+bang)                                bang)
+```
+
+Indent rule:
+
+```clojure
+{foo [[:inner 1]]}
+```
+
+Results in `:inner` indenting form arguments at depth `1`. Form
+`(bang...)` is at depth `1` so its arguments are affected:
+
+```clojure
+(foo bar                           (foo bar
+baz                                     baz
+(bang          == formats to =>         (bang
+quz                                       quz
+qoz))                                     qoz))
+```
+
+Because no rule was specified for depth 0, default indentation is
+applied to `bar` `baz` and `(bang...)`.
+
+## Limiting inner indentation
+
+Sometimes it is useful to limit `:inner` indentation to one, rather
+than all, forms at the specified depth. For example, we'd like `letfn`
+to use inner indentation only in its binding vector.
+
+Let's look at `letfn` example in the absence of any indentation rules:
+
+```clojure
+(letfn [(double [x]
+                (* x 2))] ;; want inner indentation here
+       (let [y (double 2)
+             z (double 3)]
+            (println y
+                     z))) ;; but not here
+```
+
+Applying the rule:
+
+```clojure
+{letfn [[:inner 2]]}
+```
+
+Brings in the `letfn` function body to where we want it by affecting
+form `(double [x]...)`:
+
+```clojure
+(letfn [(double [x]
+          (* x 2))] ;; want inner indentation here
+       (let [y (double 2)
+             z (double 3)]
+            (println y
+              z))) ;; but not here
+```
+
+But also affects all other forms at depth `2`. In this case,
+`(println...)` indentation is affected in an undesirable way. To limit
+formatting to `(double [x]...)`, the `0`th form at depth `2`, the
+`limit-to-form-index` rule type argument is added:
+
+```clojure
+{letfn [[:inner 2 0]]}
+```
+
+... giving us:
+```clojure
+(letfn [(double [x]
+          (* x 2))] ;; want inner indentation here
+       (let [y (double 2)
+             z (double 3)]
+            (println y
+                     z))) ;; but not here
+```
+
+Remember that when calculating `limit-to-form-index`, all forms at the
+specified depth are included, even self-evaluating ones. Given:
+
+```clojure
+(foo a b c
+     (e f
+        g)
+     (h i
+        j))
+```
+
+To affect inner indentation within form `(e...)` only, we use a rule
+of:
+
+```clojure
+{foo [[:inner 1 3]]}
+```
+
+Which results in:
+
+```clojure
+(foo a b c
+     (e f
+       g)
+     (h i
+        j))
+```
+
+Because `(e...)` is the 4th (index `3`) at form depth `1`.
+
+#### Block rules
+
+The `:block` rule works like the `:inner` rule under some
+circumstances, and like a normal list form under others. It takes one
+argument:
+
+* `line-threshold-index` -
+  if the argument at this index starts a new line, all following lines
+  will be indented by a constant 2 spaces. Any other lines are
+  indented normally.
+
+For example:
+
+```clojure
+{foo [[:block 0]]}
+```
+
+If the argument at index 0 (the first argument) does not start a new
+line, the form is indented as normal:
+
+```clojure
+(foo bar                           (foo bar
+baz            == formats to =>         baz
+bang)                                   bang)
+```
+
+If it does, the lines are indented with a constant 2 spaces:
+
+```clojure
+(foo                               (foo
+bar            == formats to =>      bar
+baz                                  baz
+bang)                                bang)
+```
+
+To give another example
+
+```clojure
+{foo [[:block 1]]}
+```
+
+This time we're looking at the argument at index 1 (the second
+argument). If it starts a new line, the indent is constant:
+
+```clojure
+(foo bar                           (foo bar
+baz            == formats to =>      baz
+bang)                                bang)
+```
+
+But if it does not, start a new line, normal indentation rules are
+used instead:
+
+```clojure
+(foo bar baz   == formats to =>    (foo bar baz
+bang)                                   bang)
+```
+
+Any lines before the threshold are always indented normally:
+
+```clojure
+(foo                               (foo
+bar                                 bar
+baz            == formats to =>      baz
+bang)                                bang)
+```
+
+## Multiple rules
+
+Multiple rules can be specified. Picking up from our previous `letfn`
+example, the rule:
+
+```clojure
+{letfn [[:inner 2 0]]}
+```
+
+Gave us:
+
+```clojure
+(letfn [(double [x]
+          (* x 2))] ;; want inner indentation here
+       (let [y (double 2)
+             z (double 3)]
+            (println y
+                     z))) ;; but not here
+```
+
+Adding a `:block` rule:
+
+```clojure
+{letfn [[:block 1][:inner 2 0]]}
+```
+
+Matches the [current default rule for `letfn`][default-rule] and
+results in indenting the `(let...` to where we want it:
+
+```clojure
+(letfn [(double [x]
+          (* x 2))] ;; want inner indentation here
+  (let [y (double 2)
+        z (double 3)]
+       (println y
+                z))) ;; but not here
+```
+
+In this case, single form argument `[(double...)]` does not break the
+`line-arg-count-threshold` of `1` and we therefore get inner
+indentation for form argument `(let...)`.
+
+[default-rule]: cljfmt/resources/cljfmt/indents/clojure.clj