Of Mages and Grimoires

When I first got started with Clojure, I didn’t know (and it was a while before I was told) about the Clojure.repl toolkit which offers Clojure documentation access from within an nREPL instance. Coming from the Python community I assumed that Clojure, like Python, has excellent API documentation with examples that a total n00b like myself could leverage to bootstrap my way into simple competence.

While Clojure does indeed have web documentation hosted on GitHub’s Pages service, they are eclipsed in Google PageRank score if not in quality as well by a community built site owned by Zachary Kim: ClojureDocs. This wouldn’t be a real problem at all, were it not for the fact that ClojureDocs was last updated when Clojure 1.3 was released. In 2011.

While Clojure’s core documentation and core toolkits haven’t changed much since the 1.3 removal of Clojure.contrib.*, I have recently felt frustrated that newer features of Clojure such as the as->, and cond->> which I find very useful in my day to day Clojure hacking not only were impossible to search for on Google (being made of characters Google tends to ignore) but also didn’t have ClojureDocs pages due to being additions since 1.3. Long story short: I finally got hacked off enough to yak shave my own alternative.




Grimoire seeks to do what ClojureDocs did, being provide community examples of Clojure’s core functions along with their source code and official documentation. However with Grimoire I hope to go farther than ClojureDocs did in a number of ways.

I would like to explore how I find and choose the functions I need, and try to optimize accessing Grimoire accordingly so that I can find the right spanner as quickly as possible. Part of this effort is the recent introduction of a modified Clojure Cheat Sheet (thanks to Andy Fingerhut & contributors) as Grimoire’s primary index.

Something else I would like to explore with Grimoire is automated analysis and link generation between examples. In ClojureDocs, (and I admit Grimoire as it stands) examples were static text analyzed for syntax before display to users. As part of my work on Oxcart, I had an idea for how to build a line information table from symbols to binding locations and I’d like to explore providing examples with inline links to the documentation of other functions used.

Finally I’d like to go beyond Clojure’s documentation. ClojureDocs and Grimoire at present only present the official documentation of Clojure functions. However some of Clojure’s behavior such as the type hierarchy is not always obvious.

< amalloy> ~colls

< Clojurebot> colls is http://www.brainonfire.net/files/seqs-and-colls/main.html

Frankly the choice of the word Grimoire is a nod in this direction… a joke as it were on Invoker’s fluff and the Archmagus like mastery which I see routinely exhibited on Freenode’s Clojure channel of the many ins and outs of the language while I struggle with basic stuff like “Why don’t we have Clojure.core/atom?” and “why is a Vector not seq? when it is Sequable and routinely used as such?”. “Why don’t we have Clojure.core/sequable?”?

Clojure’s core documentation doesn’t feature type signatures, even types against Clojure’s data interfaces. I personally find that I think to a large degree in terms of the types and structure of what I’m manipulating I find this burdensome. Many docstrings are simply wanting if even present. I think these are usability defects and would like to explore augmenting the “official” Clojure documentation. Andy Fingerhut’s thalia is another effort in this direction and one which I hope to explore integrating into Grimoire as non-invasively as possible.


Much of what I have talked about here is work that needs to be done. The first version of Grimoire that I announced originally on the Clojure mailing list was a trivial hierarchical directory structure aimed at users who sorta kinda knew what they were looking for and where to find it because that’s all I personally need out of a documentation tool for the most part after two years of non-stop Clojure. Since then I’ve been delighted to welcome and incorporate criticism and changes from those who have found Grimoire similarly of day to day use, however I think it’s important to note that Grimoire is fundamentally user land tooling as is Leiningen and as is Thalia.

As such, I don’t expect that Grimoire will ever have any official truck with Rich’s sanctioned documentation. This and the hope that we may one day get better official docs mean that I don’t really foresee migrating Grimoire off of my personal hosting to a more “Clojure-ey” domain. Doing so would lend Grimoire an undue level of “official-ness”, forget the fact that I’m now rather attached to the name and that my browser goes to the right page with four keystrokes.


As far as I am concerned, Grimoire is in a good place. It’s under my control, I have shall we say a side project as I’m chugging along on “day job” for GSoC and it seems judging by Google Analytics that some 300 other Clojureists have at least bothered to stop by and some 70 have found Grimoire useful enough to come back for more all in the three days that I’ve had analytics on. There is still basic UI work to be done, which isn’t surprising because I claim no skill or taste as a graphic designer, and there’s a lot of stuff I’d like to do in terms of improving upon the existing documentation.

Frankly I think it’s pretty crazy that I put about 20 hours of effort into something, threw it up on the internet and suddenly for the first time in my life I have honest to god users. From 38 countries. I should try this “front end” stuff more often.

So here’s hoping that Grimoire continues to grow, that other people find it useful, and that I manage to accomplish at least some of the above. While working on Oxcart. And summer classes. Yeah…..