Clojure in Small Pieces -- Literate Clojure
Tim Daly
and then I managed to advocate moving clojure to literate
form. Since I'm studying the details of the inner workings
of Clojure this seemed to be the right time to experiment
with a literate form.
I have put together the beginnings of a Clojure in Small Pieces
book. The PDF of the books is at:
http://daly.axiom-developer.org/clojure.pdf
and the literate program sources are at:
http://daly.axiom-developer.org/clojure.pamphlet
The book is in pure latex and requires a single style file at:
http://daly.axiom-developer.org/clojure.sty
The book is hyperlinked so if your pdf reader supports it you
can go to the index and find pieces of code or move from the
table of contents to the appropriate code chunks. Chunking is
very coarse-grained at the moment but will become smaller as
more code is explained.
The literate chunk machinery uses the previously posted code.
The code has been lightly modified to fit into the page format.
Clearly some of the developers have very wide screens. When
rendered on a page in raw form the code runs off the side of
the page. The book sources are 1.3.0-alpha4 (so far). There is
almost no prose in the book yet as the initial format process
has taken up most of the time so far.
You can see from the outline that there is much to discuss.
The goal is to break out the code that implements various
features into sections organized around the ideas, making
it easier to get a "conceptual view" of the code. Suggestions
for other sections are welcome. Feel free to pick a section
that interests you and we can coordinate adding it to the book.
I'm "Acting Editor-in-Chief" at the moment so I get to choose
the final form (mostly for style, flow, clarity, etc).
The aim of the book is to enable anyone to study and contribute
their understanding of portions of Clojure. I am beginning to
study the PersistentTreeMap which is based on Red-Black trees.
In the book you can see that I've split out portions of the
code into the Red-Black section, the Seq section, and the
Iterator section.
I am also experimenting with parallel programming using both
MPI and MapReduce (Hadoop). The idea is to build a multiple
node Ants demo that has N independent ant colonies, one per
parallel node, all being displayed on a single ant field.
I would like the parallel form to be very close in spirit
to Rich's original version so I'll have to document that in
detail first.
Note that the people named on the front cover are from the
author tags in the source code. I have no idea who else might
have worked on portions of the code. If you know, please let
me know.
Literature references are especially welcome. I have a few,
such as the Multi-Version Concurrency Control papers, which
will be added when I get to the STM section.
In any case, this is purely an experiment in literate clojure.
Feedback is welcome.
Tim Daly
Mark Engelberg
Robert McIntyre
power of a cross-referenced book format are very appealing
Might I suggest two possible improvements:
1) Colored syntax highlighting for all clojure code.
2) Cross references for every clojure symbol used in the code --- I'd
love to be able to click on + anywhere in the document and have it
bring me to the proper section in the book discussing the arithmetic
operators.
Page 971 looks like it still overflows a bit :)
I agree that some of the java parts of clojure were definitely
developed on very large screens.
Thanks for starting on this; best of luck,
Sincerely,
--Robert McIntyre
On Fri, Dec 31, 2010 at 2:07 AM, Mark Engelberg
<mark.en...@gmail.com> wrote:
> I find this exciting! Thanks for starting this.
>
> --
> 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
Tim Daly
On 12/31/2010 10:36 AM, Robert McIntyre wrote:
> This looks very cool, and the opportunities for fully exploiting the
> power of a cross-referenced book format are very appealing
>
> Might I suggest two possible improvements:
> 1) Colored syntax highlighting for all clojure code.
> 2) Cross references for every clojure symbol used in the code --- I'd
> love to be able to click on + anywhere in the document and have it
> bring me to the proper section in the book discussing the arithmetic
> operators.
I can't help much with the colored syntax. I am partially
color blind so I don't find colors all that useful.
Cross references occur naturally as part of the markup process.
The current chunks are much too large but that will change.
One useful side-effect of markup is that you can find where a
symbol is defined and every use of that symbol. Of course, since
everything is in one file you only need a text editor to find
anything.
> Page 971 looks like it still overflows a bit :)
> I agree that some of the java parts of clojure were definitely
> developed on very large screens.
Yeah, what I posted is only a snapshot to see if anyone else
found the idea interesting. I don't think that most programmers
have ever seen literate documentation so this may be their first
exposure to the idea.
> Thanks for starting on this; best of luck,
> Sincerely,
Thanks. I think that this is really useful in some contexts,
especially where you're trying to bring new developers up to
speed on a language. One problem I've found with open source
is that once the original developer team leaves the project
just dies. Another problem is that new developers will add
"new" features that are already in the language elsewhere.
Working with the actual source surrounded by an explanation of
"why" the code exists and the ideas behind the code seems to
me to solve both problems.
The other problem is that clever code is hard to maintain
even for the original authors. I got my own "dirt simple" code
back after 15 years and, while I understood what the code did,
I had no idea why it was there. Sometimes whole subsystems die
because they are no longer used but nobody is able to remove
the dead code because they don't understand it.
daly
On Wed, 2011-03-23 at 00:31 -0700, Christian Schuhegger wrote:
> Does a public repository exist (e.g. on github) where people could
> clone the repository and potentially contribute?
There is no repository. Everything (including all of the runnable
source) is in a single book. To build a running Clojure REPL and
a PDF copy of the book do:
wget http://literatesoftware.com/clojure.pamphlet
wget http://literatesoftware.com/tangle.c
(the tangle.c source is also in the book so you could extract
it from the pamphlet file instead)
wget http://literatesoftware.com/clojure.pdf
(not really necessary as the next step will create the pdf
but you might want to read it first)
gcc -o tangle tangle.c
tangle clojure.pamphlet Makefile >Makefile
make
You end up with a running Clojure REPL and a PDF of the book.
To make changes just modify the clojure.pamphlet file and type
make
You can send me your complete changed version or do
diff -Naur clojure.pamphlet.original clojure.pamphlet.new >clojure.patch
The basic philosophy of literate programming is that you
are writing for other people, not for the machine. This book
is an attempt to make the Clojure source code readable by
more people. What we are trying to do is start from the ideas
and move to the code so people understand why the code does
what it does.
Tim Daly
Christian Schuhegger
I only had time now to look at this.
I am running Ubuntu 10.04 LTS "Lucid Lynx" and on my machine running the
tangle program had always the effect that the clojure.pamphlet file was
reduced to file size 0.
Looking ad the man page for the open system call (man 2 open) says that
there is no version of the open system call with only one parameter.
I've modified the tangle program and now its working.
I've attached the patch.
I cannot imagine that I am the only one with that problem. Am I?
Thanks,
Christian
--
Christian Schuhegger
http://www.el-chef.de/