davidj (3) [Avatar] Offline
I think the book is coming along well and am excited to have a print copy in my hands soon. That said, I disagree with your decision to show return values as commented values using ;=>

Your rationale is that this allows for easy copying and pasting from "an EBook or PDF version of this book". First, it would probably be better to use the term "digital copy" here, especially since I don't see anyone copying Clojure code from their Kindle or iPhone into their running Clojure REPL. That said, I don't think this is a valid reason to include inline return values.

Why not?

Because a) it is not elegant (and I think this book's content *is* elegant) and more importantly b) encourages the reader to copy-paste instead of typing on his own. Especially in a nuanced and potentially unfamiliar language like Clojure (what with its lazy lists, lexical clojures, first-class functions), it is vital for the reader to type out every piece of code to understand it.

I'm reading through the Paradigms of Artificial Intelligence by Norvig at the moment, and he does this right. He uses great typography throughout, even when displaying return values. He uses the => character (but as one glyph), and it really makes the code a joy to read.

I really hope you reconsider this decision. Doing so could make for a better book that enforces good learning principles.
Chouser (21) [Avatar] Offline
Re: Return value
Thanks for your kind words and reasoned critique. The elegance of the typography might be persuasive to me if I were convinced a special => glyph truly looked better than ;=> ...you're sure this is the case?

I'm less convinced by your other points. I, for example, frequently copy-and-paste sections of code from the book, both for testing and as to seed experimental sessions at the REPL. It's nice to have the snippets in my command history, and having to avoid pasting the return values because they're invalid code seems unnecessarily awkward. In fact, having blocks of "Clojure code" in the book that are actually not valid Clojure code at all seems in a way inelegant.

I wonder if there's any way to satisfy both the desire to provide valid code and the desire for more elegant typography. Hmm...
davidj (3) [Avatar] Offline
Re: Return value
Hi Chouser,

Thanks for the response and consideration.

I believe the glyph Norvig uses is this one: http://www.fileformat.info/info/unicode/char/21d2/index.htm

It really looks fantastic and classy, and it elevates the reading experience at least 5x because I know he's really into details.

I agree that there is a time for copying and pasting code. However, if there is source code long enough to have multiple return values that you would have to edit out to paste into a REPL, maybe that source code should be available as a separate download from Manning. If the line is one line long, it really should be typed. If it is, say, three lines long and the reader doesn't want to type it, it should be easy to avoid copying a single return value.

If you don't want to set apart blocks of Clojure code as such, you may want to look at how Norvig does it (or even the PragProg books) — simply set apart the code using a monospace font and perhaps indentation. (The return value can be in a non-monospace font to indicate it is not actually code.)

How do you feel about that take on things?

I think you're doing a beautiful job with the content of the book, and I'm just making suggestions so that its style lives up to its prose.