Provide more setup tips in the README

cf. guns#4

Author: guns

README.markdown

@@ -39,13 +39,47 @@ please refer to [Pathogen](https://github.com/tpope/vim-pathogen).
 # Usage
 
 `vim-clojure-highlight` installs an autocommand that detects and highlights
-local vars, ns-refers, and aliased references every time a `*.clj` file is
-(re)loaded.
+local vars, ns-refers, and aliased references every time a `*.clj` file
+is (re)loaded. The syntax highlighting reflects the state of the REPL, so
+unevaluated references remain unmatched.
 
-This will fail silently if fireplace is unable to connect to an nREPL server.
+This will fail silently if no fireplace nREPL sessions exist.
 
-Reload your buffer with `:e` to update syntax matches. Alternately, use the
-`:ClojureHighlightReferences` command in a custom autocommand or mapping to do
-the same.
+Reload your buffer with `:e` after an eval to update syntax matches.
+Alternately, use the `:ClojureHighlightReferences` command in a custom
+autocommand or mapping to do the same.
 
-See the `doc/vim-clojure-highlight.txt` for more commands and options.
+# Eager loading
+
+If you would like to eager-load a fireplace session so that
+vim-clojure-highlight works on the first load of a clojure file, install an
+autocommand hook that calls `:Require`:
+
+```vim
+" Evaluate Clojure buffers on load
+autocmd BufRead *.clj try | silent! Require | catch /^Fireplace/ | endtry
+```
+
+# Rainbow parentheses and other syntax extensions
+
+Since vim-clojure-highlight dynamically alters the syntax state of a buffer,
+it's possible that other syntax extensions will be affected by this plugin.
+
+A simple workaround is to activate Clojure syntax extensions in an autocmd:
+
+```vim
+autocmd Syntax clojure EnableSyntaxExtension
+```
+
+For example, this is how you might enable
+[`rainbow_parentheses.vim`](https://github.com/kien/rainbow_parentheses.vim)
+for Clojure buffers:
+
+```vim
+autocmd VimEnter *       RainbowParenthesesToggle
+autocmd Syntax   clojure RainbowParenthesesLoadRound
+autocmd Syntax   clojure RainbowParenthesesLoadSquare
+autocmd Syntax   clojure RainbowParenthesesLoadBraces
+```
+
+See `doc/vim-clojure-highlight.txt` for more commands and options.

plugin/vim_clojure_highlight.vim

@@ -27,7 +27,7 @@ endfunction
 
 augroup vim_clojure_highlight
 	autocmd!
-	autocmd BufRead *.clj call s:syntax_match_references()
+	autocmd BufRead *.clj ClojureHighlightReferences
 augroup END
 
 command! -bar ToggleClojureHighlightReferences call s:toggle_clojure_highlight_references()