On 1/5/2011 9:27 AM, Seth wrote:
Just discovered org-mode myself --- does anyone know of guide to using
it with clojure for a total newbie?
I havent actually used it for clojure per se. I was just imagining how
it could be used. You have the ability to embed arbitrary code (from
many different languages). You can edit the code in its own emacs
major mode and then it will automatically be saved back once done. You
can then document it using org-modes awesome abilities.
However, this is sort of clumsy.
I would rather be able to have all of my code in all of its 'little
files' arranged in directories.
Just out of curiosity, what is the advantage of maintaining code
in 'little files'? The main reason people use an IDE is that they
get a whole-project view. The IDE lets you move around and find
things as though your project was effectively one big file. It really
is a kind of patch on the little-file organization. What is it about
'little file format' that is actually useful? Except for habit, is
there a real advantage?
Conceptually separate efforts, such as the Clojure-contrib effort
could be done in separate volumes. But you would expect this kind of
natural organization, just as you might expect a multi-volume story
like the Asimov Foundation series. Wouldn't a well organized contrib
literate document be useful? When you program and reach for your
books, don't you find a good index and cross-reference the best way
to find the idea you need?
And when im editing the clojure files,
i would like to be like 'oh, i want to document this better/introduce
the motivation etc! And then automatically have the code, or parts of
the code, copied to the org file and then i could document it. And
then jump back to the code to continue developing.
Viewing the step of 'documenting the code' as just another step in
development is one of the reasons that documentation is rarely done
and even more rarely done well. The target audience is usually another
developer so tools like Javadoc exist to make it easy to look up class
details. What tools exist to support whole-project, idea-to-implementation
documentation?
Viewing documentation as a phase of development is conceptually and
actually very different from viewing the project as a literate effort.
Development targets the machine whereas a literate effort targets people.
The difference in target audience makes a qualitative difference in what
you write, when you write it, and why you write it. There is nothing
about the Javadoc organization (to pick on one tool) that encourages or
even supports the 'idea-to-implementation' flow. Are there open source
examples of documentation from the ideas to the implementation?
Literate programming allows you to reorganize your code by ideas. For
instance, in the clojure example, the PersistentTreeMap class is split
into its subclasses like Node. Okasaki's work starts with the idea of
Nodes so we highlight and explain the Node structure of PersistentTreeMap
before we get into the top level class details. In this way you motivate
the need for the Node class and 'bring the reader along' so that when
they get to PersistentTreeMap they already understand Nodes.
Because of the way Java forces you to organize your code you have to
introduce the PersistentTreeMap class before you introduce the Node class.
This is the late 90s and we ought to be able to organize our code any
way we want rather than be forced to organize it for the compilers,
linkers, and loaders. Why would we want to organize our code for the
convenience of our tools?
And have changes in
the clojure file automatically reflected in the org file. I was
thinking that 'chunk' labels could be embedded in the source code
(like in marginalia in github: just comments like ;;##Block Name) so
that we wouldn't have to have all code in one file in one chunk, but
could split it up.
Having literate code in more than one file is certainly possible because
Latex supports an 'include' command. You could include the code chunks or
you could include the chapters and keep them in 'litte file format'.
I'm not sure what advantage this confers. Working in a single file or
working in multiple files is pretty transparent. Emacs lets me split
buffers in the same file as easily as having two files in split windows.
Finding things is SO much easier (hey, its certainly in THIS file :-) )
The hardest initial part is using apt-get texlive.
The difference is not the physical organization but the mental organization.
A single file format gives the impression of a book and with that comes the
skills of organizing the material for presenting the ideas in a logical
fashion. It is this change of mental viewpoint that is the critical part
of literate programming rather than the tools like emacs-org-mode or latex.
The mental transition to this style of programming is at least as hard as
the mental transition from Object Oriented programming to Functional
programming.
In my experience, the gain is worth the effort.
Clojure code is nearly documentation-free at the moment. We could certainly
create some Javadoc-like tools or IDEs or Emacs-modes that fit our normal
routines or we could experiment with a whole new mindset. Clojure users
are early-adopting, risk-taking, leading-edge developers. Literate
programming
is just the right kind of challenge for innovating away from the past.
Besides, wouldn't it be great if the community could point at "the Clojure
book", like the Lisp community points to "the Steele book"? Steele managed
to organize an unreadable standard into a readable and very useful book.
Surely we can do the same.
Tim Daly
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@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+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
