On Thu, Jan 6, 2011 at 11:05 PM, Tim Daly <d...@axiom-developer.org> wrote: > On 1/6/2011 9:15 PM, Ken Wesson wrote: >> And then of course the overarching purpose of Clojure itself isn't >> even given, let alone why it has sorted-map, and why it's an immutable >> sorted-map ... > > There is very little that needs to be said about the overarching > purpose of Clojure for the expected target audience. Since this > includes detailed source code in two languages it is reasonable to > assume that it is being read by a programmer and, more specifically, > it is being read by a programmer who is interested in the details > of Clojure's implementation.
Perhaps, but I think it might be worth considering broadening the potential target audience to include people with some Java knowledge that are curious about Clojure, but don't necessarily know much about Clojure. >> I know, I know, tall order, right? I hope you're at least thinking >> about this stuff for the eventual final version, though. (And why >> start with the red-black tree, anyway? After introducing Clojure I'd >> probably start with getting a minimalist implementation that is >> runnable first > > The included implementation is runnable. I was not advocating > literate program at the introduction of Clojure 1.0 so the first > version is 1.3 which is not minimalist in any sense. Oh, I wasn't suggesting to leave anything out entirely; just to organize the text to put the bootstrap-necessary material first, until the code up to that point can get you a working repl with some functionality, and then after that fleshing out the rest of the feature-set and standard (clojure.core; contrib would be biting off more than anyone could probably chew) library. >> -- so the compiler and evaluator and repl and >> s-expressions, lists and any other infrastructure these need under the >> hood, and whatever else is needed for this -- some of the numerics >> stuff, symbols and symbol interning, etc.; then with already a basic >> Lisp environment in play, adding the other functions and data >> structures in core that weren't needed just to get things up and >> running with a basically functional repl. > > I wish Clojure was "factored" in terms of the implementation > to suit the I2I (ideas-to-implementation) approach but it isn't. I thought you had been saying all kinds of stuff about how your literate-programming tools allow you to organize the material for the benefit of human readers, rather than the requirements of the compiling tools? This seems somewhat at odds with that. >> Of course, you might need to ask Rich some questions to get some of >> this information. > > Rich obviously knows the answers to these questions but he is > a valuable and highly constrained resource. It would be nice if > he provided some motivating material but I think that we, as programmers, > can figure out how bit-partitioning works and how the code implements > it. Every new developer needs to do that to make changes. Literate > source code would decrease the time it takes to get up to speed. > So while it would be nice if Rich contributed I think he has better > things to do. ... > Rich has provided a lot of discussion about his motivations > in his videos. Then those videos should prove a valuable resource for you. > There was a discussion a while back about providing > this same information in textual form and as a result of that > I ended up advocating literate programming.... which led to this. I seem to recall being involved in that discussion. :) > I am hoping that showing an example of literate Clojure will > motivate others to pick a section (e.g. agents) and work through > the details. Once a section is written it can benefit from the > "many eyes" of open source to improve the style and accuracy > of presentation. In that way we all end up developing a document > that quickly brings up the average quality material for developers. That seems to me to suggest creating a wiki or similar for this project. Why stop with half-measures? Let anyone contribute. Sections can be marked as code-only, code and partial text, and code with completed text; encourage people to flesh out the first two and proofread and correct errors in the latter. Sections with "completed text" would also have an uneditable "canonical version" that could be added to the .pamphlet file, though still updated from time to time with typo fixes and other corrections. (And the whole thing would retain an uneditable history, like wikis commonly do, as a defense against vandalism. Think of it as persistent, immutable text editing. :)) There's also the need though for motivating sections that may not have any code themselves but would preface some series of code-sections related to implementing a particular larger element of the architecture, such as the compiler, maps, or lazy sequences. Any such wiki should probably allow such sections to be created, and provide a discussion forum of some sort for debating which such sections are needed, creations/deletions, any other wiki administrivia, and the question of how to sequence and organize the thing as a whole. TOC pages could exist that provide the organization as editable sequences of wikilinks to smaller chunks of the thing. Perhaps these should be the same as the motivating-sections, with the motivating text at the top and the TOC of subsections at the bottom. (In the .pamphlet file these sub-TOCs would be removed, of course, leaving just the motivating text as chapter X section 1 and the subsequent subsections as sections 2 onward of chapter X, and LaTeX would generate its own, global TOC.) -- 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
