We're building a book, and we want your help!
Clojure Cookbook is set to be O'Reilly's next book in the Cookbook Series. The book will detail a large number of Clojure recipes – pairs of problems and solutions – covering a wide number of common topics.
The goal behind the Clojure Cookbook is to build the best cookbook we can. We plan to do this by leveraging the breadth of experience across the entire community. We hope the rest of the community will rise to the occasion and contribute their best Clojure recipes.
Every author of an accepted contribution will receive a free digital copy of the book and abundant credit in the book. Authors of five or more recipes will receive a signed physical copy of the book (and major kudos!) Write a whole chapter and we might have to see if we can get your name on the cover 😉.
No contribution is too small. We welcome anything from typo fixes or ideas for recipes all the way to complete recipes and anything in between. You can find more information on how to contribute in our CONTRIBUTING.md document.
You can build a PDF/MOBI/EPUB/HTML version of the book with the asciidoc
command-line utility. (You must also have the source-highlight application
installed and properly configured.)
You must have the asciidoc and source-highlight command-line utilities
installed and configured before attempting to build the book.
To install and configure the tools on OS X,
run the included bootstrap_osx.sh script:
$ ./script/asciidoc/bootstrap_osx.shLinux users will need to follow a similar process to
bootstrap_osx.sh, but we have not
automated it yet. The most important part after installing asciidoc and
source-highlight is to obtain and configure the proper bindings for Clojure
(and other) syntax highlighting.
With installation and configuration complete, all that is left is to run the asciidoc command.
-
To render a single document:
$ asciidoc -b html5 conventions.asciidoc # ... outputs conventions.html -
To render the entire book:
$ asciidoc -b html5 clojure-cookbook.asciidoc # ... outputs clojure-cookbook.html
NOTE: Rendered out put is similar to the final book, but does not include O'Reilly style sheets.
To verify asciidoc files are without error/warning, run the following:
$ ./script/asciidoc/check.shThe only output should be the file detail.
The only acceptable warning is related to structure of the book sections. It's OK to ignore this one:
asciidoc: WARNING: conventions.asciidoc: line 1: section title out of sequence: expected level 1, got level 2
Please correct all others or ask for guidance if the error message is unclear. A common one is related to callouts like "<1>" at the end of a line of code.
asciidoc: WARNING: formatting-strings.asciidoc: line 57: no callouts refer to list item 1
To prevent this warning, the callout must be commented using the language appropriate comment character(s). This also keeps the code runnable in the REPL when pasted.
Clojure Example:
(defn foo [] "bar" ) <1>requires a semicolon before the callout reference
(defn foo [] "bar" ) ; <1>Console Example:
Username: <1>should be
Username: #<1>The following users are trusted contributors (push access) that have proven themselves through excellent judgement and outstanding contributions to the book. We support and strongly encourage these users to make corrections and improvements to the book at will (recipes aside.)
- @jcromartie
We are Luke Vanderhart (@levand) and Ryan Neufeld (@rkneufeld), developers, authors, conference speakers and (at the moment), teachers. For this book-building adventure we will be your guides; we'll be collecting and editing your contributions, interfacing with the publisher (O'Reilly) and writing a solid chunk of the book ourselves.
This draft of Clojure Cookbook is licensed under a Creative Commons Attribution-NonCommercial-NoDerivs 3.0 Unported License.
Please see the contribution guide for how this works for accepting pull requests.
Also, please note that because this is a No Derivatives license, you may not use this repository as a basis for creating your own book based on this one. Technically speaking, this book is open source in the "free as in beer" sense, rather than "free as in speech."
