pesterhazy · January 15, 2019 02:14 · Nov 14, 2018 · Nov 14, 2018 · Nov 13, 2018 · Nov 13, 2018
diff --git a/configuring-zprint.md b/configuring-zprint.md
@@ -18,10 +18,10 @@ $ zprintm-0.4.12 <<< $'(defn discombobulate-widget [x]\n(foo foo foo foo foo)\n(
 The default [for defn](https://github.com/kkinnear/zprint/blob/4bbfc0579f8088cad6d7e4e3c85c93cbdaed5dc9/src/zprint/config.cljc#L415)
 is  `:arg1-body`.
 You can make zprint keep the first argument on the same line as the function
-name (if it fits) by setting the "defn" key in `:fn-map` to `:fn`:
+name (if it fits) by setting the "defn" key in `:fn-map` to `:arg2`:
 
 ```
-$ zprintm-0.4.12 '{:fn-map {"defn" :fn}}' <<< $'(defn discombobulate-widget [x]\n(foo foo foo foo foo)\n(bar bar bar bar bar bar bar))'
+$ zprintm-0.4.12 '{:fn-map {"defn" :arg2}}' <<< $'(defn discombobulate-widget [x]\n(foo foo foo foo foo)\n(bar bar bar bar bar bar bar))'
 (defn discombobulate-widget [x]
   (foo foo foo foo foo)
   (bar bar bar bar bar bar bar))

diff --git a/configuring-zprint.md b/configuring-zprint.md
@@ -102,4 +102,22 @@ function definitions without any regard to style or indentation. You can be conf
 zprint will clean up after you.
 
 So re-organizing top-level newlines is not part of zprint's primary job. If you still want to
-use it to normalize newlines, see the `:parse` option contained in [this answer](https://github.com/kkinnear/zprint/issues/68#issuecomment-435243712).
+use it to normalize newlines, see the `:parse` option contained in [this answer](https://github.com/kkinnear/zprint/issues/68#issuecomment-435243712).
+
+## Commas in maps
+
+By default, zprint separates k/v-pairs in maps with commas. But you can turn that behavior off:
+
+Before:
+
+```
+$ zprintm-0.4.12 <<< $'{"a" "b" "c" "d"}'
+{"a" "b", "c" "d"}
+```
+
+After:
+
+```
+$ zprintm-0.4.12 '{:map {:comma? false}}' <<< $'{"a" "b" "c" "d"}'
+{"a" "b" "c" "d"}
+```
diff --git a/configuring-zprint.md b/configuring-zprint.md
@@ -101,5 +101,5 @@ reformatted using its layouting algorithm. That's a powerful property: you can w
 function definitions without any regard to style or indentation. You can be confident that 
 zprint will clean up after you.
 
-Touching top-level newlines is not the main behavior. If you still want to normalize
-newlines, see the `:parse` option contained in [this answer](https://github.com/kkinnear/zprint/issues/68#issuecomment-435243712).
+So re-organizing top-level newlines is not part of zprint's primary job. If you still want to
+use it to normalize newlines, see the `:parse` option contained in [this answer](https://github.com/kkinnear/zprint/issues/68#issuecomment-435243712).
diff --git a/configuring-zprint.md b/configuring-zprint.md
@@ -99,4 +99,7 @@ the one hand, it doesn't touch the whitespace outside the top-level forms. Newli
 and other whitespace _inside_ the forms, on the other hand, is mostly ignored and
 reformatted using its layouting algorithm. That's a powerful property: you can write 
 function definitions without any regard to style or indentation. You can be confident that 
-zprint will clean up after you.
+zprint will clean up after you.
+
+Touching top-level newlines is not the main behavior. If you still want to normalize
+newlines, see the `:parse` option contained in [this answer](https://github.com/kkinnear/zprint/issues/68#issuecomment-435243712).
diff --git a/configuring-zprint.md b/configuring-zprint.md
@@ -86,4 +86,17 @@ $ zprintm-0.4.12 '{:width 15}' <<< $'(defn square [n] (* n n))'
 (defn square
   [n]
   (* n n))
-```
+```
+
+## Top-level newline characters
+
+Zprint newline handling may seem confusing at first glance
+but makes sense once you understand it.
+
+A source file is a sequence of top-level forms (such as defns) separated by 
+newlines. In general, zprint's newline philosophy can be summarized like this. On
+the one hand, it doesn't touch the whitespace outside the top-level forms. Newlines
+and other whitespace _inside_ the forms, on the other hand, is mostly ignored and
+reformatted using its layouting algorithm. That's a powerful property: you can write 
+function definitions without any regard to style or indentation. You can be confident that 
+zprint will clean up after you.
diff --git a/configuring-zprint.md b/configuring-zprint.md
@@ -64,4 +64,26 @@ $ zprintm-0.4.12 '{:style :keyword-respect-nl}' <<< $'(defn nav-ui [x]\n  [:nav\
    [:a {:href "#/"} "Home"]])
 ```
 
-You can also apply this setting for [only a single form](https://github.com/pesterhazy/cljs-spa-example/blob/08756951dfff2b86c0fabe68b1025279cc543319/src/cljs_spa/layout.cljs#L18).
+You can also apply this setting for [only a single form](https://github.com/pesterhazy/cljs-spa-example/blob/08756951dfff2b86c0fabe68b1025279cc543319/src/cljs_spa/layout.cljs#L18).
+
+## Line width
+
+By default, zprint assumes a line width of 80 characters. The top-level option
+`:width` allows you to customize this number. This can be useful for experimenting
+with options. Often formatting becomes interesting as soon as a form doesn't fit
+in a single line. For example, this is boring:
+
+```
+$ zprintm-0.4.12 '{}' <<< $'(defn square [n] (* n n))'
+(defn square [n] (* n n))
+```
+
+But by setting an artificially short line width, we can cause zprint to introduce
+newlines:
+
+```
+$ zprintm-0.4.12 '{:width 15}' <<< $'(defn square [n] (* n n))'
+(defn square
+  [n]
+  (* n n))
+```
diff --git a/configuring-zprint.md b/configuring-zprint.md
@@ -62,7 +62,6 @@ $ zprintm-0.4.12 '{:style :keyword-respect-nl}' <<< $'(defn nav-ui [x]\n  [:nav\
   [x]
   [:nav
    [:a {:href "#/"} "Home"]])
-$
 ```
 
 You can also apply this setting for [only a single form](https://github.com/pesterhazy/cljs-spa-example/blob/08756951dfff2b86c0fabe68b1025279cc543319/src/cljs_spa/layout.cljs#L18).
diff --git a/configuring-zprint.md b/configuring-zprint.md
@@ -3,6 +3,8 @@ with built-in defaults, but it is also highly customizable. The [docs](https://g
 can be a bit daunting, so in what follows I will explain how to set some configuration
 options that are commonly used.
 
+## defn
+
 By default, zprint will move the arg vector of `defn` forms to a separate line:
 
 ```
@@ -23,4 +25,44 @@ $ zprintm-0.4.12 '{:fn-map {"defn" :fn}}' <<< $'(defn discombobulate-widget [x]\
 (defn discombobulate-widget [x]
   (foo foo foo foo foo)
   (bar bar bar bar bar bar bar))
-```
+```
+
+## Meaningful vectors
+
+In Hiccup, Reagent or Sablono, HTML elements are represented by a vector:
+
+```
+(defn nav-ui
+  []
+  [:nav
+   [:a {:href "#/"} "Home"]
+   [:span " "]
+   [:a {:href "#/users"} "Users"]
+   [:span " "]
+   [:a {:href "#/users/1"} "User #1"]
+   [:span " "]
+   [:a {:href "#/users/999"} "Invalid user"]
+   [:span " "]
+   [:a {:href "#/clock"} "Clock"]])
+ ```
+
+With default settings, zprint will will reformat the vector as if it
+were pure data, trying to fill the page width with elements:
+
+```
+$ zprintm-0.4.12 <<< $'(defn nav-ui [x]\n  [:nav\n    [:a {:href "#/"} "Home"]])'
+(defn nav-ui [x] [:nav [:a {:href "#/"} "Home"]])
+```
+To avoid this, you can instruct zprint to respect newlines in vectors starting
+with a keyword:
+
+```
+$ zprintm-0.4.12 '{:style :keyword-respect-nl}' <<< $'(defn nav-ui [x]\n  [:nav\n    [:a {:href "#/"} "Home"]])'
+(defn nav-ui
+  [x]
+  [:nav
+   [:a {:href "#/"} "Home"]])
+$
+```
+
+You can also apply this setting for [only a single form](https://github.com/pesterhazy/cljs-spa-example/blob/08756951dfff2b86c0fabe68b1025279cc543319/src/cljs_spa/layout.cljs#L18).
diff --git a/configuring-zprint.md b/configuring-zprint.md
@@ -13,7 +13,8 @@ $ zprintm-0.4.12 <<< $'(defn discombobulate-widget [x]\n(foo foo foo foo foo)\n(
   (bar bar bar bar bar bar bar))
 ```
 
-The default [is `:arg1-body`](https://github.com/kkinnear/zprint/blob/4bbfc0579f8088cad6d7e4e3c85c93cbdaed5dc9/src/zprint/config.cljc#L415).
+The default [for defn](https://github.com/kkinnear/zprint/blob/4bbfc0579f8088cad6d7e4e3c85c93cbdaed5dc9/src/zprint/config.cljc#L415)
+is  `:arg1-body`.
 You can make zprint keep the first argument on the same line as the function
 name (if it fits) by setting the "defn" key in `:fn-map` to `:fn`:
 

diff --git a/configuring-zprint.md b/configuring-zprint.md
@@ -1,5 +1,7 @@
 The [zprint](https://github.com/kkinnear/zprint) auto-formatter for Clojure comes
-with built-in defaults, but it is also highly customizable.
+with built-in defaults, but it is also highly customizable. The [docs](https://github.com/kkinnear/zprint#configuration)
+can be a bit daunting, so in what follows I will explain how to set some configuration
+options that are commonly used.
 
 By default, zprint will move the arg vector of `defn` forms to a separate line:
 

diff --git a/configuring-zprint.md b/configuring-zprint.md
@@ -0,0 +1,23 @@
+The [zprint](https://github.com/kkinnear/zprint) auto-formatter for Clojure comes
+with built-in defaults, but it is also highly customizable.
+
+By default, zprint will move the arg vector of `defn` forms to a separate line:
+
+```
+$ zprintm-0.4.12 <<< $'(defn discombobulate-widget [x]\n(foo foo foo foo foo)\n(bar bar bar bar bar bar bar))'
+(defn discombobulate-widget
+  [x]
+  (foo foo foo foo foo)
+  (bar bar bar bar bar bar bar))
+```
+
+The default [is `:arg1-body`](https://github.com/kkinnear/zprint/blob/4bbfc0579f8088cad6d7e4e3c85c93cbdaed5dc9/src/zprint/config.cljc#L415).
+You can make zprint keep the first argument on the same line as the function
+name (if it fits) by setting the "defn" key in `:fn-map` to `:fn`:
+
+```
+$ zprintm-0.4.12 '{:fn-map {"defn" :fn}}' <<< $'(defn discombobulate-widget [x]\n(foo foo foo foo foo)\n(bar bar bar bar bar bar bar))'
+(defn discombobulate-widget [x]
+  (foo foo foo foo foo)
+  (bar bar bar bar bar bar bar))
+```
No results found