Improvements after Jens review

phel.html.markdown

@@ -47,8 +47,8 @@ It is a dialect of Lisp inspired by Phel and Janet.
 # Nesting forms works as you expect
 (+ 1 (- 3 2)) # = 1 + (3 - 2) => 2
 
-# Phel inherits PHP under the hood, so it can use native PHP (functions and classes) without any additional cost 
-# by using the `php/` prefix to all PHP native functions.
+# Phel inherits PHP under the hood, so it can use native PHP (functions and classes) without 
+# any additional cost by using the `php/` prefix to all PHP native functions.
 
 # Types
 #############
@@ -100,16 +100,16 @@ string."
 # Collections & Sequences
 #############
 
-# Lists are linked-list data structures, while vectors are array-backed.
-(type '(1 2 3)) # :list
-(type [1 2 3])  # :vector
+# Lists are linked-list data structures, while vectors are array-backed
+(type '(1 2 3)) #=> :list
+(type [1 2 3])  #=> :vector
 
 # A list would be written as just (1 2 3), but we have to quote
 # it to stop the reader thinking it's a function.
 # Also, (list 1 2 3) is the same as '(1 2 3)
 
 # You can produce a (non-lazy) sequence between a range. 
-(range 1 10 2) # <- (range from to step)
+(range 1 10 2) #=> (range from to step)
 (take 4 (range 10))
 
 # Use cons to add an item to the beginning of a list
@@ -132,35 +132,39 @@ string."
 #=> 10
 
 (reduce push [] '(3 2 1))
-# = (push (push (push [] 3) 2) 1)
+#=> (push (push (push [] 3) 2) 1)
 #=> [3 2 1]
 
 # Functions
 #############
 
-# Use fn to create new functions. A function always returns its last statement.
-(fn [] "Hello World") # => :function
+# Use fn to create new functions
+# A function always returns its last statement
+(fn [] "Hello World") #=> <function>
 
 # You need extra parens to call it
 ((fn [] "Hello World")) #=> "Hello World"
 
-# You can create a var using def
+# You can bind a value to a symbol using def for definition
 (def x 1)
 x #=> 1
 
-# Assign a function to a var
+# Variables provide a way to manage mutable state
+(def foo (var 10)) # Define a variable with value 10
+
+# Assign a function to a definition
 (def hello-world (fn [] "Hello World"))
 (hello-world) #=> "Hello World"
 
 # You can shorten this process by using defn
 (defn hello-world [] "Hello World")
 
-# The [] is the list of arguments for the function.
+# The [] is the list of arguments for the function
 (defn hello [name]
   (str "Hello " name))
 (hello "Jens") #=> "Hello Jens"
 
-# You can also use this shorthand to create functions:
+# You can also use this shorthand to create functions
 (def hello2 |(str "Hello " $1))
 (hello2 "Anna") #=> "Hello Anna"
 
@@ -178,7 +182,7 @@ x # => 1
 # Maps
 #############
 
-# Hash maps have faster lookups but don't retain key order.
+# Hash maps have faster lookups but don't retain key order
 (type {:a 1 :b 2 :c 3})          #=> :hash-map
 (type (hash-map :a 1 :b 2 :c 3)) #=> :hash-map
 
@@ -199,7 +203,7 @@ keymap # => {:a 1 :c 3 :b 2}
 # Keywords can be used to retrieve their value from a map, too!
 (:b keymap) #=> 2
 
-# Don't try this with strings.
+# Don't try this with strings
 # ("a" stringmap)
 # ...Exception: Call to undefined function a()
 
@@ -219,7 +223,7 @@ keymap # => {:a 1 :b 2 :c 3}
 # Sets
 #############
 
-# A Set contains unique values in random order.
+# A Set contains unique values in random order
 
 (type (set 1 2 3)) #=> :set
 (set 1 2 3 1 2 3 3 2 1 3 2 1) #=> (set 1 2 3)
@@ -230,17 +234,17 @@ keymap # => {:a 1 :b 2 :c 3}
 # Remove one with unset
 (unset (set 1 2 3) 1) #=> (set 2 3)
 
-# Test for existence by using the set as a function:
+# Test for existence by using the set as a function
 ((set 1 2 3) 1) #=> 1
 ((set 1 2 3) 4) #=> nil
 
-# There are more functions like: count, union, intersection, difference, etc.
+# There are more functions like: count, union, intersection, difference, etc
 
 
 # Useful forms
 #############
 
-# Logic constructs in clojure are just macros, and look like everything else
+# `If` conditionals in phel are special forms
 (if false "a" "b") #=> "b"
 (if false "a") #=> nil
 
@@ -304,7 +308,7 @@ keymap # => {:a 1 :b 2 :c 3}
 # all native functions with the prefix `php/`.
 (php/+ 1 2 3)
 
-# With :use you can use different namespaces. Similar as `use` in PHP. 
+# With :use you can use different namespaces. Similar as `use` in PHP
 (ns my\module
   (:use \DateTimeImmutable))