Add some indentation customization examples

Author: bbatsov

README.md

@@ -51,30 +51,63 @@ To see a list of available configuration options do `M-x customize-group RET clo
 
 The default indentation rules in `clojure-mode` are derived from the
 [community Clojure Style Guide](https://github.com/bbatsov/clojure-style-guide).
+Please, refer to the guide for the general Clojure indentation rules.
+
+The indentation of special forms and macros with bodies is controlled via
+`put-clojure-indent`, `define-clojure-indent` and `clojure-backtracking-indent`.
+Nearly all special forms and built-in macros with bodies have special indentation
+settings in `clojure-mode`. You can add/alter the indentation settings in your
+personal config. Let's assume you want to indent `->>` and `->` like this:
+
+```clojure
+(->> something
+  ala
+  bala
+  portokala)
+```
+
+You can do so by putting the following in your config:
+
+```el
+(put-clojure-indent -> 1)
+(put-clojure-indent ->> 1)
+```
+
+This means that the body of the `->/->>` is after the first argument.
+
+A more compact way to do the same thing is:
+
+```el
+(define-clojure-indent
+  (-> 1)
+  (->> 1))
+```
+
+The bodies of certain more complicated macros and special forms
+(e.g. `letfn`, `deftype`, `extend-protocol`, etc) are indented using
+a contextual backtracking indentation method, controlled by
+`clojure-backtracking-indent`. Here's some example config code:
+
+```el
+(put 'implement 'clojure-backtracking-indent '(4 (2)))
+(put 'letfn 'clojure-backtracking-indent '((2) 2))
+(put 'proxy 'clojure-backtracking-indent '(4 4 (2)))
+(put 'reify 'clojure-backtracking-indent '((2)))
+(put 'deftype 'clojure-backtracking-indent '(4 4 (2)))
+(put 'defrecord 'clojure-backtracking-indent '(4 4 (2)))
+(put 'defprotocol 'clojure-backtracking-indent '(4 (2)))
+(put 'extend-type 'clojure-backtracking-indent '(4 (2)))
+(put 'extend-protocol 'clojure-backtracking-indent '(4 (2)))
+(put 'specify 'clojure-backtracking-indent '(4 (2)))
+(put 'specify! 'clojure-backtracking-indent '(4 (2)))
+```
+
+Don't use special indentation settings for forms with names that are not unique,
+as `clojure-mode`'s indentation engine is not namespace-aware and you might
+end up getting strange indentation in unexpected places.
 
-Characterizing them is difficult to do in summary; this is one
-attempt:
-
-1. Bodies of parenthesized forms are indented such that arguments are aligned to
-  the start column of the first argument, _except_ for a class of forms
-  identified by the symbol in function position, the bodies of which are
-  indented two spaces, regardless of the position of their first argument (this
-  is called "defun" indentation, for historical reasons):
-  1. Known special forms (e.g. `loop`, `try`, etc)
-  2. Nearly all "core" macros that ship as part of Clojure itself
-  3. Userland macros (and any other form?) that are locally registered via
-  `put-clojure-indent`, `define-clojure-indent` (helpers for adding mappings to
-  `clojure-indent-function`).
-2. The bodies of certain more complicated macros and special forms
-  (e.g. `letfn`, `deftype`, `extend-protocol`, etc) are indented using a
-  contextual backtracking indentation method, controlled by
-  `clojure-backtracking-indent`.
-3. The bodies of other forms (e.g. vector, map, and set literals) are indented
-  such that each new line within the form is set just inside of the opening
-  delimiter of the form.
-
-Please see the docstrings of the Emacs Lisp functions/vars noted above for
-information about customizing this indentation behaviour.
+Please, see the docstrings of the Emacs Lisp functions/vars noted above for
+information about customizing this indentation behavior.
 
 ## Related packages