Beef up node creation docs

- User guide now gives guidance
- Node API now lists fns by category in ns docstring
- Node API creation fns now include code examples in docstrings
  - brought in current version of test-doc-blocks to test these
  - fixed escaping issue for docstrings in apply-import-vars

CommonMark code blocks in docstrings are awkward when they require
escaping, but they sure look good on cljdoc.

Closes #97

Author: lread

CHANGELOG.adoc

@@ -16,6 +16,8 @@ For a list of breaking changes see link:#v1-breaking[breaking changes].
 
 === Unreleased
 
+* Beef up docs on node creation https://github.com/clj-commons/rewrite-clj/issues/97[#97]
+
 === v1.0.579-alpha
 
 * Release workflow now creates a GitHub release

deps.edn

@@ -26,12 +26,13 @@
                          :extra-paths ["test"]}
 
            ;; document block testing
-           :test-doc-blocks {:replace-deps {lread/test-doc-blocks {:mvn/version "1.0.101-alpha"}}
+           :test-doc-blocks {:replace-deps {lread/test-doc-blocks {:mvn/version "1.0.107-alpha"}}
                              :replace-paths []
                              :ns-default lread.test-doc-blocks
                              :exec-args {:docs ["doc/01-user-guide.adoc"
                                                 "doc/design/01-merging-rewrite-clj-and-rewrite-cljs.adoc"
-                                                "doc/design/namespaced-elements.adoc"]}}
+                                                "doc/design/namespaced-elements.adoc"
+                                                "src/rewrite_clj/node.cljc"]}}
 
            :test-docs {:extra-paths ["target/test-doc-blocks/test"]}
 

doc/01-user-guide.adoc

@@ -498,6 +498,81 @@ Inspect, analyze, create and render rewrite-clj nodes.
 
 See link:{cljdoc-api-url}/rewrite-clj.node[node API docs].
 
+==== Creating Nodes
+
+Rewrite-clj nodes can be created in a number of ways:
+
+1. Indirectly via the parser API:
++
+[source,Clojure]
+----
+(-> (p/parse-string "[1 2 3]")
+    n/string)
+;; => "[1 2 3]"
+----
+2. Indirectly via the zip API (which uses the parser API):
++
+[source,Clojure]
+----
+(-> (z/of-string "[1 2 3]")
+    z/node
+    n/string)
+;; => "[1 2 3]"
+----
+3. Via coercion from Clojure forms:
++
+[source,Clojure]
+----
+(-> (n/coerce '[1 2 3])
+     n/string)
+;; => "[1 2 3]"
+----
+4. By explicitly calling node creation functions.
++
+[source,Clojure]
+----
+(-> (n/vector-node [(n/token-node 1)
+                    (n/whitespace-node " ")
+                    (n/token-node 2)
+                    (n/whitespace-node " ")
+                    (n/token-node 3)])
+    n/string)
+;; => "[1 2 3]"
+----
++
+The node creation function are what the parser API uses to create nodes.
+
+Which technique you use depends on our needs.
+
+Coercion is convenient, but doesn't offer control over whitespace. In some cases coercion might not give you the result you expect:
+
+//:test-doc-blocks/skip
+[source,Clojure]
+----
+(-> (n/coerce '#(+ %1 %2))
+    n/string)
+;; => "(fn* [p1__10532# p2__10533#] (+ p1__10532# p2__10533#))"
+----
+
+Be aware that node creation functions do not force you to use rewrite-clj nodes (notice the raw `1` `2` and `3`):
+
+[source,Clojure]
+----
+(-> (n/vector-node [1 (n/spaces 1) 2 (n/spaces 1) 3])
+    n/string)
+;; => "[1 2 3]"
+----
+
+...but no automatic coercion will be done on non rewrite-clj elements and their `tag` will return unknown.
+
+[source,Clojure]
+----
+(n/tag 1)
+;; :unknown
+----
+
+Finally, there are a handful of node whitespace creation convenience functions such as `spaces`, `newlines`, `line-separated` and `comma-separated`, see link:{cljdoc-api-url}/rewrite-clj.node[the node API docs for details].
+
 === Paredit API
 Structured editing was introduce by rewrite-cljs and carried over to rewrite-clj v1.
 

script/lread/apply_import_vars.clj

@@ -163,7 +163,10 @@
                                                           ;; mimic what parser does 
                                                           (nstring/string-node (some->> (imported-docstring vm opts)
                                                                                         string/split-lines
-                                                                                        (map #(string/replace % "\"" "\\\""))
+                                                                                        ;; TODO: this escaping seems too awkward
+                                                                                        (map #(-> % 
+                                                                                                  (string/replace "\\" "\\\\")
+                                                                                                  (string/replace "\"" "\\\"")))
                                                                                         (into []))))
                                                     (if (= 1 (count delegators))
                                                       (concat [(nws/newlines 1) (nws/spaces 2)]