[ANN] Book "The Clojure Standard Library - Annotated Reference"

[Renzo Borgatti]

Hi all,

I'm very happy to announce the early access of a new book: "Clojure Standard Library - Annotated Reference" by Manning. Although it's a reference of the roughly 700+ functions (and macros) coming out of the box with the Clojure jar file, it is not designed to read as a boring list. Think of all the Stackoverflow, mailing lists, ClojureDocs, articles, blogs all mashed together to create an essay for each function. The book website is:

https://www.manning.com/books/clojure-standard-library

It contains now a total of 4 chapters (around 200 pages) or ~30 functions, starting with some of the most important available in the standard library. Here's a sample of “case" how it appears on the book http://tinyurl.com/hekc55u to give you an idea of the kind of treatment they get. Needless to say any feedback is highly appreciated. Any question please shout here, personally at reborg*at*reborg.net or on the book forum.

Regards,
Renzo

[Alex Miller]

This is a cool idea so thanks for working on it.

I was going to buy this (as I buy most of the Clojure books that come out) but $48 for an unfinished ebook put me off so I didn't. I totally get why a physical book of this length would be that much (because paper is expensive right now), but I don't get it with the ebook (particularly EA)? I know you likely have little control over this, so it's not really fair to complain to you, but maybe you can feed it back to your editor.

While pretty thorough, that case description is still lacking a description of one important feature - grouping multiple tests that have the same output in a list. Basically this line from the doc string:

(test-constant1 ... test-constantN)  result-expr

Example:

(case 3

  (1 2 3) "1, 2, or 3"

  4         "4"

  (5 6 7) "5, 6, or 7")

;;=> "1, 2, or 3"

I think most people are unaware of this feature and seems like it's the kind of thing you'd want in the book.

Alex

[Ryan Fowler]

I love the idea.

​A gotchas section of some sort could be useful. For instance, a detail about `case` to consider mentioning is that Java Constants don't work as tests.

ryans-mbp:~% cat test.clj

(let [incoming-character Character/LINE_SEPARATOR]

  (println "case w/ constant"

           (case incoming-character

             Character/LINE_SEPARATOR :line-separator

             :unknown))

  (println "case w/ int     "

           (case incoming-character

             13 :line-separator

             :unknown)))

ryans-mbp:~% java -jar $CLOJURE test.clj

case w/ constant :unknown

case w/ int      :line-separator

​I think I understand why this doesn't work but it feels like it should work. And without prior knowledge, I don't think I would assume that constants don't work.

​Ryan​

--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clo...@googlegroups.com
Note that posts from new members are moderated - please be patient with your first post.
To unsubscribe from this group, send email to
clojure+unsubscribe@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
---
You received this message because you are subscribed to the Google Groups "Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Alex Miller]

This is a good gotcha. From Clojure's perspective this is just referencing a Java field (which could be mutable and NOT a constant). Maybe it would be possible to reflectively determine that this field is actually a constant and make it work, not sure.

The number one special case I see people ask about with case though is Java class constants (which are *not* constants and don't work). One workaround is to use the class name as a string.

[Torsten Uhlmann]

Thanks for working on this!

Back in the day I had a "Java Developers Almanac" for Java 1.4 and it helped getting around the lesser used API parts, or discovering functionality I hadn't used before.

clojure+u...@googlegroups.com

For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
---
You received this message because you are subscribed to the Google Groups "Clojure" group.

To unsubscribe from this group and stop receiving emails from it, send an email to clojure+u...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clo...@googlegroups.com
Note that posts from new members are moderated - please be patient with your first post.
To unsubscribe from this group, send email to

clojure+u...@googlegroups.com

For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
---
You received this message because you are subscribed to the Google Groups "Clojure" group.

To unsubscribe from this group and stop receiving emails from it, send an email to clojure+u...@googlegroups.com.

[rebo...@gmail.com]

Hey Alex, many good points and great feedback. More inline. 

On Wednesday, 7 December 2016 22:57:07 UTC, Alex Miller wrote:

This is a cool idea so thanks for working on it.

I was going to buy this (as I buy most of the Clojure books that come out) but $48 for an unfinished ebook put me off so I didn't. I totally get why a physical book of this length would be that much (because paper is expensive right now), but I don't get it with the ebook (particularly EA)? I know you likely have little control over this, so it's not really fair to complain to you, but maybe you can feed it back to your editor.

I'm also concerned about the price tag at this stage in the book. If this was a finished work of 1200 pages (which is a better estimate IMHO) maybe it would be appropriate. More in general I've changed my mind overtime around the book project. At the beginning was great to start with Manning (and still is a decent experience), but as an afterthought this would have been better placed as a lean-pub (or similar) and made it a community effort (BTW I'm searching collaborators and co-authors anyway). But this is where we are now. To make it easier for people to check out the book at the moment:

* there is a promotion lasting until today 50% off: https://twitter.com/ManningBooks/status/806541284722806785 I'll ask Manning to make more of those.

* I'll add 3 function examples to the free downloadable material

* I'm asking Manning to have a website for the book with the HTML version on it, with a suitable business model (like buy 10-50-100 functions offers browsable online).

* In general (not just you) please post concerns on the book forum so Manning can listen: https://forums.manning.com/forums/clojure-standard-library

While pretty thorough, that case description is still lacking a description of one important feature - grouping multiple tests that have the same output in a list. Basically this line from the doc string:

(test-constant1 ... test-constantN)  result-expr

Example:

(case 3

  (1 2 3) "1, 2, or 3"

  4         "4"

  (5 6 7) "5, 6, or 7")

;;=> "1, 2, or 3"

I think most people are unaware of this feature and seems like it's the kind of thing you'd want in the book.

Totally. And as this one I'm pretty sure expert readers will find lacking information or worse, inaccuracies. This is the kind of feedback I'd really like, because even if I'm dissecting sources and everything else, I'm pretty sure I'll always miss something.

Thanks

Renzo

[rebo...@gmail.com]

Thanks Ryan, added this (and Alex's) to the book issues tracker. Will land in the following releases.

clojure+u...@googlegroups.com

For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
---
You received this message because you are subscribed to the Google Groups "Clojure" group.

To unsubscribe from this group and stop receiving emails from it, send an email to clojure+u...@googlegroups.com.

[rebo...@gmail.com]

Yep, I mentioned the Almanac to "senior stakeholders" while pitching the book :)

It was a less internet-based age, but I think there is still room for an offline reference.

Thanks

Renzo