 
 (def xml-catalog (parse-xml-str xml-string))
 
-;; first task! something simple
-;; Lets change the name of all the authors to tobias funke in this xml document.
-;; This could be accomplished by digging down to the right elements and updating them
-;; appropriately... but a lazier way would be to just walk all of the tree
-;; and replace the contents of the elements with the author tag
-
-;; we can use tree/pre-tree to accomplish this
+;; First task! Something simple: let's change the name of all the
+;; authors to Tobias Funke in this xml document.
+
+;; This could be accomplished by digging down to the right elements
+;; and updating them appropriately... But a lazier way would be to
+;; just walk all of the tree and replace the contents of the elements
+;; with the author tag.
+
+;; We can use `tree/pre-tree` to accomplish this:
 ;; it is a function that takes a traversal of all sub nodes of a node
-;; and gives you a traversal of all nodes in the tree
+;; and gives you a traversal of all nodes in the tree.
+
 ;; EXAMPLE:
-
-;; since nodes in the
 
 (def xml-nodes (tree/pre-tree
                 [:content
-                 (travers/filtered map?) ; we don't want to list the strings
-                                         ; in the tree as nodes
-                                         ; so we filter them here
+                 (travers/filtered map?) ; we don't want to consider
+                                         ; the strings in the tree as
+                                         ; nodes so we filter them
+                                         ; here
                  ]))
 
-;; xml nodes here is a lens/traversal that lets you view and modify
-;; nodes of the tree in a pre-walk fashion.
-;; (there is also a post-tree that lets you do it in a post-walk fashion)
-
-;; ok so lets shrink the nodes we are working with to only the nodes
-;; with the tag author
+;; `xml-nodes` defined above using `tree/pre-tree` is a lens/traversal
+;; that lets you view and modify nodes of an XML tree in a pre-walk
+;; fashion. (There is also a corresponding `tree/post-tree` that lets
+;; you do it in a post-walk fashion)
+
+;; ok so let's shrink the nodes we are working with and consider only
+;; the nodes with the "author" tag:
 
 (def authors [xml-nodes (travers/shrink #(= (:tag %) :author))])
 
-;; and change the contents of these nodes to be "tobias funke"
+;; then change the content of these nodes to "Tobias Funke":
 
 (pprint
  (-> xml-catalog
-     (lens/write [authors :content] ["tobias funke"])))
-
-;; perfect all the authors are now tobias funke
+     (lens/write [authors :content] ["Tobias Funke"])))
+
+;; Perfect! All the authors are now Tobias Funke!

     [collection
      (fn [f] (mapv f collection))])))

;; traversals are built a lot like lenses
;; its a function that takes the structure
;; in this case a collection
;; it returns a pair that where the first item is
;; all the items it "traverses" as a seq.
;; and the second item is a function
;; that builds a new value after applying the function
;; to every item it traverses. IE a mapping

(= (lens/update user3 [:languages mapped-vec] string/capitalize)
   {:last-name "funke",
    :first-name "tobias",
    :languages ["Clojure" "Ruby" "Elixir"]})

;; this version keeps the languages in a vector

;; traversals can be composed with lenses in any way you want

(def deep-data
  {:a [{:b [{:c [1 2 3]}

;; =====================================================
;; iso-lens

;; the `:postcode` in the nested structure is represented as a string
;; but we can write a lens that lets us treat it as a number:

(def str->num (lens/iso-lens #(Integer/parseInt %) str))

;; `iso-lens` takes two functions, the second one being the inverse of
;; the first. In this case, the first converts the root value to a
;; integer and the second converts it back to a string.

(lens/update user2 [:address :postcode str->num] inc)
;; {:last-name "funke",
;;  :first-name "tobias",
;;  :address {:address_line "sudden vale street 23",
;;            :postcode "56322",
;;            :city "bluthville"}}

;; the result after incrementing the postcode is still a string!



;; =====================================================
;; extract

;; `extract` is a function that lets you transform a structure to a
;; map of a different shape and later write back changes that are done
;; to the new map:

(def user-view
  {:first-name   :first-name
