ka wrote:
Tim,
I don't know much about either lisp or latex :). But it looks like a
really neat idea at a first thought to me. Have two remarks-
1. From the developer's pov - I'm not sure how the developer, who is
accustomed to looking at just code + some comments, will manage
working with the book. But your "tangle" step might help here.
First, let me address the question from the project point of view.
If you want to develop something that will be useful for the next 5 years,
such as the latest version of MS Word or you want to develop something that
has limited applicability, such as a device driver for a chain printer
(likely before
your time), then there is no reason to invest in literate programming.
If you want to develop something that will "last forever", e.g., a
language you
intend to use 50 years from now like lisp, then it is worth investing in
literate
documentation.
From a developer's point of view, literate programming is painful. The
point
of a literate program is to ensure that your code will OUTLIVE you. All
projects
eventually will lose all of the original developers. A literate program
is a way
to communicate with people you will never meet. You can write down WHY
you made certain design choices, such as that the immutable tree structure
is 32-words wide to fit the 128-byte cache lines. When hardware changes,
this design decision can be changed. I am working on code from the 1970s
where the original authors (including me) did NOT write down any of the
design decisions. This makes it very difficult to modify the code. I
can't go
back and ask my coworkers questions, as some of them have died and others
just don't care anymore.
So there are really two "populations" of developers.... the original set
(e.g. Rich Hickey) and the "other" set, which are the people who will join
in the future. Future developers won't have the original design decisions
written down so they will have no way to know. What is the long term
effect? Well, some bright spot will contribute a patch that allows you to
"conj" onto the front of a data structure that does not support the
operation.
This will be so horribly expensive that Clojure does not support it now.
But the future developer won't know that unless it is written down.
Literate programming gives a chapter-like view of the data structure,
including a section on performance criteria, which has a paragraph that
explains why such operations should never be supported. It includes
benchmark test code to ensure that it doesn't break somewhere else.
Can we do this with comments? Yes, but we won't. Because comments
are about code, not about the ideas. Can we do this with Javadoc?
Yes, but we won't, because Javadoc is about code, not about ideas.
Can we do this with properly chosen variable names? Oh, please....
Literate programs communicate with people, and as a side-effect,
with the machine.
2. From the user's pov - Users will still look for small snippets of
docs like - http://clojure.org/reader; not everyone will have to
patience to go through an entire "chapter". How do you think we can
extract just these small snippets from the whole book?
- Thanks
A user document would be a separate volume. The Axiom documentation
has 19 published volumes so far. The first volume is a book that covers
(http://axiom-developer.org/axiom-website/documentation.html)
the whole system. The second volume is a tutorial. These volumes include
REPL examples and code sequences to illustrate using the system. These
code sequences can be automatically extracted and run. This provides
automatic regression tests to ensure that the published examples work.
Other volumes contain background material, which in the case of Clojure,
would be a discussion of immutable data structures (with literature refs),
state/time discussions, java interop discussions, etc. These could include
specific snippets of code that actually implement things like immutability.
So when the bright spot programmer decides to add the bad idea, everyone
will be able to read the paragraph explaining why it is a bad idea.
In a well-written book you can easily find the chapter/section/paragraph
that you need to answer a question. And, if you can't find it, you can ask
the newsgroup... who can then add the chapter/section/paragraph to the
books for future users.
Users who want to write new code (e.g. to compute the date/time) would
contribute a whole section to the books. This would be included in the table
of contents, the index, and the cross-references. Another user could easily
find that the date/time code already exists. At the moment it is easier to
write it from scratch, throw it into "contrib", and see if it sticks.
If you improve date/time to handle "locale" then you rewrite the
section, including
your changed version of code. This would be submitted to the
"editor-in-chief"
who get it approved by the editor for the contrib book, who fixes up the
style, content, cross-references, etc. (See? Even the english majors can
now contribute :-) )
Are you writing code that should survive? Will it be useful 30 years
from now?
Java survives because Sun/Oracle can pay people to constantly "get up
to speed" on the internals, to have a continuous group that is charged with
design decisions, testing, maintenance, etc. Java lasted long enough that
the rest of the world saw value in making clones and developing experts
in their own versions. Sun/Oracle sets standards and rejects "good ideas"
that do not conform to the original design.
Clojure does not have this luxury. People come, people go. This has no
effect in the short term because the core people are still with the project.
What about 5 years from now when Rich is running Google?
Is Clojure going to be useful and used 30 years from now?
Clojure breaks ground in so many ways but it is still written,
built, and maintained like it was 1970. We can do better.
Knuth wrote TeX in literate form (which he invented) and TeX
still lives today.
From my experience I would estimate that literate programming is a
factor of 3 more expensive than writing code the traditional way.
Is it worth it? Only if you want to write code that lasts forever.
I get paid to write code that will be thrown away.
In my free time I want to write code that lives....
So the question is
"Should Clojure be restructured into literate form?"
Tim Daly (Axiom Editor-in-Chief)
--
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
