Small fixes in REPL examples

[andreasthoelke]

Thank you for the wonderful lib!

[ztellman]

Thanks for the fixes. I was trying to differentiate between printed lines and the returned values using the angle brackets. Did you find that confusing?

[andreasthoelke]

Ok, I see now – and I think I could have figured it out from the context. Differentiating between printed and returned output sounds reasonable.

After thinking about it a bit, I’d still vote to remove the < .. >. We have << … >> representing a deferred, which I think is intuitive and helpful - and consistent with how the REPL shows it. <..> may be misunderstood as representing some sort of object as well.

I did a quick research and found a range of different conventions for showing REPL examples: http://www.braveclojure.com/getting-started/ uses this a convention:

(do (println "no prompt here!")
   (+ 1 3))
; => no prompt here!
; => 4

The only rule to help differentiate seems to be “returned value comes last”.

“The Joy of Clojure” differentiates by indicating the returned value via the additional ..=>!

((fn [x y]
   (println "Making a set")
   #{x y})
 1 2)
;; Making a set
;;=> #{1 2}

The comments ;; and the removed > make sense as users can just copy-past the code.

“Clojure Programming” (O’Reilly) makes the same point (code examples should be copy-paste-able) and uses a similar convention:

(println (average [60 80 100 400]))
; 160
;= nil

Different styles are used here – mostly no differentiation: https://clojuredocs.org/clojure.core/println http://clojure.org/guides/getting_started http://clojure.org/guides/destructuring

I’d say a differentiation would be a nice to have, however not essential and would take additional maintenance effort. If we choose to have a differentiation, we may consider adopting the “The Joy of Clojure” or “Clojure Programming” convention. (I’d be happy to make that change).

[andreasthoelke]

I ran through the other docs, made same small changes there as well.

[ztellman]

I think it's fine as-is. Thanks for the fix, and your research into the possible approaches.