 
 (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!

   :last-name "funke"
   :email "tobias.funke@gmail.com"})

;; this is the raw way to define a lens
;; you call lens/lens and give it a function
;; that takes a root value in this case a user
;; and returns a pair where the first value
;; is the field. And the second value is a function
;; that takes a function of the name and returns a new user

(def first-name
  (lens/lens

        {:b [{:c [1 3]}
             {:c [3]}]}]})


;; if you view a traversed lens you get all values it points to as a
;; flattened seq:

(= (lens/view deep-data even-cs-lens)
   [2 4 8])

;; this returns all even values in the :c fields of the deep-data
;; structure.

;; ===========================================
;; tree


;; OK! lets work with some tree data!
;; (courtesy of http://msdn.microsoft.com/en-us/library/ms762271(v=vs.85).aspx)

(def xml-string
  "<?xml version=\"1.0\"?>
