Literate programming
I see that my Literate Programming session is beginning to gain some traction. I would encourage you to bring examples. We can discuss the merits and possibly gain some new insights. If nothing else, please sign up for the Literate Software session at Clojure-Conj. I promise to keep it short. Literate programming can take various forms. I am working on a survey of literate software. I came across an interesting non-latex example worth sharing: http://jashkenas.github.com/coffee-script/documentation/docs/nodes.html Notice how well they have documented an apparently simple line as in: exports.Base = class Base The Base is an abstract base class for all nodes in the syntax tree. Each subclass implements the compileNode method, which performs the code generation for that node. To compile a node to JavaScript, call compile on it, which wraps compileNode in some generic extra smarts, to know when the generated code needs to be wrapping up in a closure. An options hash is passed and cloned throughout, containing information about the environment from higher in the tree (such as if a returned value is being requested by the surrounding function), information about the current scope, and indentation level. Notice how this is not only giving trivial information (e.g. Base is an abstract base class) but WHY it exists (..as a base for all nodes in the syntax tree). It gives operational information (to compile a node..) as well as information about the effect (..which wraps...). It shows how global information is used (An options hash..) and WHY (containing information about the environment...) Code only tells you HOW something is done at the time it is done. It's like having a recipe without an idea what you would make. If our standards of documentation were raised to this level then large systems like Axiom, Clojure, and ClojureScript would be much easier to maintain and modify in the long term. If you want your code to live beyond you, make it literate. Tim Daly d...@literatesoftware.com -- 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
Literate Programming
Good Sir and Fellow Traveler, On Fri, 2011-12-23 at 03:33 -0800, Adam Getchell wrote: > Having received the benefit of your kind reply, I must confess to a > puzzlement which has vexed me ever since I read your missive. It is > this: how should I have read it so as to receive some knowledge or > insight with which I had not formerly possessed in the moments prior? > For in truth I have not been able to discern its helpfulness thereby. Methinks thou hast conflated the spirit of literate programming, intended as a communication medium between fellow traveling souls on this dark road with the substance of the task involving the choice of conveyance and walking stick. Replying to the former 'twas I, whilest thou was't addressing the latter. We did pass by in our respective darkness. Forgive me for lacking light to guide your chosen path. I mistook your destination for mine own, a grievous fault, one to which I am ever prone. > Clearly, as a craftsman of computer algebra tools yourself, you > must agree that the selection of implements is of some import, > lest you abandon that enterprise entirely and use Mathematica > instead. Truly I do quake at the co-opting possible should the fair winds drift the conversation from the soul of the art to the choice and heft of tooling. Like the goodly Saint Alexander [1] we need to seek the order which contains life. What doth make a program live, or the building alive, is not to be found in the tooling but in ourselves. We must eschew the pernicious present practice lest we find our creation among the dead and dying on Sourceforge. I have chosen minimal tools for my algebra opus. Latex for smithing and tangle for forging. I find no need for any other save the, as yet unrealized, potential of graphing tools. 'Tis not the tools but my poor craftsmanship that constrains the quality of the work. >> The combination of literate + TDD seems forbidding > Are you finding it hard to explain why you wrote a test? In this platonic exchange is made apparent my confusion. The dross of failures that skins the molten and fluid gold of your smelting needs but a few words. "Lo, this might arise at the boundary of my creation." That the dross needeth explaining to the Smithy new to your endeavor, yet still it certainly can be conveyed in flowing natural language. Sharing the tale of the journey, the wonders of the vision, and the pleasures of final offering depends not on the choice of pen but on the craftmanship of language. That the gentle reader delight in your creation and sing its praises, see the vision, and dedication lifeblood to its continuance is all. That we might achieve such essential Quality [2] with Clojure is the dream. Sir Tim Daly, Elder of the Internet [1] Alexander, Christopher "The Nature of Order: The Phenomenon of Life" 2002 ISBN 0-9726529-1-4 [2] Persig, Robert "Zen and the Art of Motorcycle Maintenance: An Inquiry into Values" 1974 ISBN 0-553-27747-2 -- 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
Rethinking Literate Programming
The thread on documentation that Val started ( https://groups.google.com/forum/?hl=en#!topic/clojure/oh_bWL9_jI0) is getting a little long so I'm starting a related one specific to litprog. I've made a start on rethinking LP at https://github.com/mobileink/codegenres/wiki/Rethinking-Literate-Programming . A few key points: * Knuth's main early LP tool (WEB) was to a certain extent an attempt to fix deficiencies in Pascal, as Knuth himself explicitly acknowledged. Some aspects of Knuthian LP (KLP) may make sense for imperative languages with side effects; since it's hard to reason about programs written in such languages, added commentary is needed. But if you already know that functions are side-effect free and data are immutable, you no longer need that. * Programming language design has not evolved in the direction of LP, as we might have expected from some of Knuth's more grandiose pronouncements; instead they have evolved in the direction of greater expressivity, which obviates the need for many kinds of documentation. You can argue that LP was a fine thing in its day, but the world has moved on. * KLP is largely based on the personal aesthetic and psychological preferences of DE Knuth involving issues such as the proper order and mode of presentation of code. Those are normative issues, and there is no reason to take Knuth's preferences as gospel. In particular there is no justification for his claim that using LP "methods" leads to "better" code. It not only depends on what "better" means, it depends on what other methods are available. Just because writing Pascal in LP was better (for Knuth et al.) than writing plain Pascal does not mean this will always be the case in all languages. It doesn't generalize. (To a hammer, everything looks like a goto.) * There is (demonstrably) no reason to think that there is any "natural" or "best" order of presentation for code; there are only preferences, and everybody has one, if you catch my drift. The point again being that Knuth was not on to some kind of laws of programming. KLP is all about his preferred style, not about the Way Things Are. * KLP is sometimes contrasted with "self-documenting code" To get a grip on what that is and what we can expect from it we need to examine the notions of function, algorithm, and code. Then it looks like code does not in fact "self-document", if "documentation" is taken to mean explanation. But it does express meaning, and sometimes expressivity is preferrable to explanation. Maybe that's terminological nit-picking, but sometimes coming up with the right terminology makes all the difference (see "lambda abstraction"). * Speaking of which, Knuth himself admitted that his choice of "literate programming" as the name of his "new method" was tongue in cheek, since it makes anybody who doesn't use it an "illiterate programmer". (The citation is in one of the essays in his book "Literate Programming".) So maybe we should stop using it and come up with a more accurate name. Howsabout "Knuthian Programming"? * Knuth's model for program text is the literary essay, read from beginning to end. This is obviously in tension with the way code actually works. Library code usually does not have a beginning or end, for example. This is a little ironic, since hypertext has liberated us from the tyranny and oppression of linear narrative. A better literary analog to program text is The Book of Lists, or Commonplace books, whose contents can be read in any order. * Finally, a whiff of a hint of a soupcon of a concrete proposal: instead of supporting some kind of structured markdown-style syntax in comments and docstrings, add support for the Z specification notation, so that we can express in clear, concise, formally defined, standard set-theoretic notation the exact meaning of code. That's the general idea, I don't have a concrete suggestion yet. There's more stuff on the wiki<https://github.com/mobileink/codegenres/wiki/Rethinking-Literate-Programming>, and more to be said, but I'll stop here. Cheers, Gregg -- 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 --- You received this message because you are subscribed to the Google Groups "Clojure" group. To unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
Re: Literate programming
is there a place introducing (e.g. overview) more about Literate? have no ideas about this stuff. On Oct 27, 3:06 am, d...@axiom-developer.org wrote: > I see that my Literate Programming session is beginning to gain some > traction. I would encourage you to bring examples. We can discuss the > merits and possibly gain some new insights. If nothing else, please > sign up for the Literate Software session at Clojure-Conj. I promise > to keep it short. > > Literate programming can take various forms. I am working on a survey > of literate software. I came across an interesting non-latex example > worth sharing: > > http://jashkenas.github.com/coffee-script/documentation/docs/nodes.html > > Notice how well they have documented an apparently simple line as in: > > exports.Base = class Base > > The Base is an abstract base class for all nodes in the syntax tree. > Each subclass implements the compileNode method, which performs the > code generation for that node. To compile a node to JavaScript, call > compile on it, which wraps compileNode in some generic extra smarts, > to know when the generated code needs to be wrapping up in a > closure. An options hash is passed and cloned throughout, containing > information about the environment from higher in the tree (such as > if a returned value is being requested by the surrounding function), > information about the current scope, and indentation level. > > Notice how this is not only giving trivial information (e.g. Base is > an abstract base class) but WHY it exists (..as a base for all nodes in > the syntax tree). It gives operational information (to compile a node..) > as well as information about the effect (..which wraps...). It shows > how global information is used (An options hash..) and WHY (containing > information about the environment...) > > Code only tells you HOW something is done at the time it is done. > It's like having a recipe without an idea what you would make. > > If our standards of documentation were raised to this level then large > systems like Axiom, Clojure, and ClojureScript would be much easier to > maintain and modify in the long term. > > If you want your code to live beyond you, make it literate. > > Tim Daly > d...@literatesoftware.com -- 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
Re: Literate programming
Try http://en.wikipedia.org/wiki/Literate_programming or the original paper www.literateprogramming.com/knuthweb.pdf or from the master himself: http://www-cs-faculty.stanford.edu/~uno/lp.html Tim Daly On Wed, 2011-10-26 at 19:49 -0700, jaime wrote: > is there a place introducing (e.g. overview) more about Literate? have > no ideas about this stuff. > > On Oct 27, 3:06 am, d...@axiom-developer.org wrote: > > I see that my Literate Programming session is beginning to gain some > > traction. I would encourage you to bring examples. We can discuss the > > merits and possibly gain some new insights. If nothing else, please > > sign up for the Literate Software session at Clojure-Conj. I promise > > to keep it short. > > > > Literate programming can take various forms. I am working on a survey > > of literate software. I came across an interesting non-latex example > > worth sharing: > > > > http://jashkenas.github.com/coffee-script/documentation/docs/nodes.html > > > > Notice how well they have documented an apparently simple line as in: > > > > exports.Base = class Base > > > > The Base is an abstract base class for all nodes in the syntax tree. > > Each subclass implements the compileNode method, which performs the > > code generation for that node. To compile a node to JavaScript, call > > compile on it, which wraps compileNode in some generic extra smarts, > > to know when the generated code needs to be wrapping up in a > > closure. An options hash is passed and cloned throughout, containing > > information about the environment from higher in the tree (such as > > if a returned value is being requested by the surrounding function), > > information about the current scope, and indentation level. > > > > Notice how this is not only giving trivial information (e.g. Base is > > an abstract base class) but WHY it exists (..as a base for all nodes in > > the syntax tree). It gives operational information (to compile a node..) > > as well as information about the effect (..which wraps...). It shows > > how global information is used (An options hash..) and WHY (containing > > information about the environment...) > > > > Code only tells you HOW something is done at the time it is done. > > It's like having a recipe without an idea what you would make. > > > > If our standards of documentation were raised to this level then large > > systems like Axiom, Clojure, and ClojureScript would be much easier to > > maintain and modify in the long term. > > > > If you want your code to live beyond you, make it literate. > > > > Tim Daly > > d...@literatesoftware.com > -- 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
Re: Literate programming
Tim, I recall that at some point you described your setup for doing Clojure literate programming, and if I recall correctly, you were primarily working in LaTeX, relying on incremental compilation to test little snippets of code as you wrote them. Have there been any new developments on the literate programming / Clojure front, in terms of tools that leverage existing build tools, test suites, generating meaningful line numbers for stack traces and debugging? -- 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
Re: Literate programming
On Thu, 2011-10-27 at 00:17 -0700, Mark Engelberg wrote: > Tim, > > I recall that at some point you described your setup for doing Clojure > literate programming, and if I recall correctly, you were primarily > working in LaTeX, relying on incremental compilation to test little > snippets of code as you wrote them. Yes, the idea is to write a literate version of Clojure, see http://daly.literatesoftware.com/clojure.pamphlet http://daly.literatesoftware.com/clojure.pdf similar in style to "Lisp in Small Pieces". (The effort has been stalled temporarily while I try to find new employment.) >From the above document you extract the Makefile, type 'make' and end up with the newly formatted PDF and a running REPL. So any edits to the document text are immediately reflected in the PDF and any edits to the code are immediately reflected in the compiled results. > > Have there been any new developments on the literate programming / > Clojure front, in terms of tools that leverage existing build tools, > test suites, generating meaningful line numbers for stack traces and > debugging? > The question is ill-posed in sense that literate programming is not a tool or technology but a change in mindset. To quote Knuth: I believe that the time is ripe for significantly better documentation of programs, and that we can best achieve this by considering programs to be works of literature. Hence, my title "Literate Programming". Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do. -- Donald Knuth "Literate Programming (1984) CSLI 1992 pg. 99 So imagine a world where the eloquence of Rich Hickey was expressed in book form. Imagine the whole immutability lecture written down and decorated with the actual running code as illustration. Imagine that the original authors clearly explained software transactional memory and illustrated it with the actual code. Imagine a discussion of argument destructuring with running code illustrations. How many more people would be able to dive into the details of Clojure to maintain and modify the code? How many people would find it much easier to understand prototypes, defrecords, macros, and all of the other struggles that populate the current email forums? How are infinite sequences supported and what code supports it? What does NIL mean and why was it defined that way? We do not capture the ideas. We do not rewrite the explanations to clarify the fine points of confusion. We do not illustrate how the ideas of Red-Black tries are moved "from ideas to implementation". We do not communicate the ideas to each other. We code for the machine. So we end up with the traditional "tree of sand" pile of little files. In order to overcome this we construct tools (IDEs) that know how to navigate this pile, tools to store the changes (SVN, git, hg), tools to put the sandpiles together (#include), tools to build guardrails, tools, tools, tools... (You can, of course, keep each chapter and section and subsection in separate files and "include" them in the book.) Now imagine that the "book" is multimedia where you can include animation (watch the tree balance), video, and a running REPL. Think Khan Academy for Clojure. This community is willing to overthrow the traditional ideas of lisp in order to make progress on a new path. Yet we continue to structure the development as though we worked on a PDP 11/40 with 4k file size limits. We continue to let the most valuable information which is the meat of Clojure disappear while we keep only the code, the bones of Clojure. Open the source code. Stare at it. Ask yourself if you understand exactly why it was needed, why it is structured that way, what would happen if you changed it and what else depends on this code. Imagine your job is to maintain and modify it but Rich is not available for questions and answers. Ultimately that is what matters. In the long term the code will be the only remaining artifact after Rich leaves the project. Look at Sourceforge and you will see thousands of dead projects that will never be picked up because they are just trees of code, dead code. Et tu, Clojure? Literate programming is about making code live. I like Clojure and I really want it to live. Think long term. Imagine a better way. 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
Re: Literate programming
I would gladly pay for such a thing to materialize on my screen; if it only took money to get that, I'm sure we'd all be willing to finance such an effort however we can. On Thursday, October 27, 2011 1:58:52 PM UTC-4, TimDaly wrote: > > So imagine a world where the eloquence of Rich Hickey was expressed in > book form. Imagine the whole immutability lecture written down and > decorated with the actual running code as illustration. Imagine that > the original authors clearly explained software transactional memory > and illustrated it with the actual code. Imagine a discussion of > argument destructuring with running code illustrations. > > How many more people would be able to dive into the details of Clojure > to maintain and modify the code? How many people would find it much > easier to understand prototypes, defrecords, macros, and all of the > other struggles that populate the current email forums? How are > infinite sequences supported and what code supports it? What does > NIL mean and why was it defined that way? > > We do not capture the ideas. We do not rewrite the explanations to > clarify the fine points of confusion. We do not illustrate how the > ideas of Red-Black tries are moved "from ideas to implementation". > We do not communicate the ideas to each other. We code for the machine. > > ... > Now imagine that the "book" is multimedia where you can include > > animation (watch the tree balance), video, and a running REPL. > Think Khan Academy for Clojure. > > This community is willing to overthrow the traditional ideas of lisp > in order to make progress on a new path. Yet we continue to structure > the development as though we worked on a PDP 11/40 with 4k file size > limits. We continue to let the most valuable information which is the > meat of Clojure disappear while we keep only the code, the bones of > Clojure. > > -- 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
Re: Literate programming
Thank you for your persistence on this subject : I'm sure that I'm not the only lurker on this list that you manage to get interested in LP. I wanted to share two thought that I had when looking at your LP take on Clojure code : 1°) The infrsastructure should really lower the barrier to participation as wiki did for wikipedia. I gain some insight into the persistent data structures in Clojure implementation as I ported persistent vector to C++ : I wish I could just jump in and add that insight as a few paragraphs. Programs nowadays can be massive hence the need of collaborative developpement. A github account would be more appropriate imho that a http server. 2°) It was my understanding that Clojure implementation was both large and poised for some overhaul (Clojure in Clojure ?). On the other hand, I heard that Clojurescript implementation was damn small and maybe the experience carried from Clojure implementation means that its foundation will last : maybe it could be an opportunity for a LP project ? Best Regards, B PS: I'm seeing awsome potential in LP as a teaching tool ! I long for the day where I can direct my students to LP projects to help them understand the tought processes that went into great programs. On Oct 27, 7:58 pm, daly wrote: > On Thu, 2011-10-27 at 00:17 -0700, Mark Engelberg wrote: > > Tim, > > > I recall that at some point you described your setup for doing Clojure > > literate programming, and if I recall correctly, you were primarily > > working in LaTeX, relying on incremental compilation to test little > > snippets of code as you wrote them. > > Yes, the idea is to write a literate version of Clojure, > seehttp://daly.literatesoftware.com/clojure.pamphlethttp://daly.literatesoftware.com/clojure.pdf > similar in style to "Lisp in Small Pieces". (The effort has been > stalled temporarily while I try to find new employment.) > > Open the source code. Stare at it. Ask yourself if you understand > exactly why it was needed, why it is structured that way, what would > happen if you changed it and what else depends on this code. Imagine > your job is to maintain and modify it but Rich is not available for > questions and answers. > > Ultimately that is what matters. In the long term the code will be > the only remaining artifact after Rich leaves the project. Look at > Sourceforge and you will see thousands of dead projects that will > never be picked up because they are just trees of code, dead code. > Et tu, Clojure? > > Literate programming is about making code live. > I like Clojure and I really want it to live. > > Think long term. Imagine a better way. > > Tim Daly Thank you for your persistence on this subject : I'm sure that I'm not the only lurker on this list that you manage to get interested in LP. I wanted to share two thought that I had when looking at your LP take on Clojure code : 1°) The infrsastructure should really lower the barrier to participation as wiki did for wikipedia. I gain some insight into the persistent data structures in Clojure implementation as I ported persistent vector to C++ : I wish I could just jump in and add that insight as a few paragraphs. Programs nowadays can be massive hence the need of collaborative developpement. A github account would be more appropriate imho that a http server. 2°) It was my understanding that Clojure implementation was both large and poised for some overhaul (Clojure in Clojure ?). On the other hand, I heard that Clojurescript implementation was damn small and maybe the experience carried from Clojure implementation means that its foundation will last : maybe it could be an opportunity for a LP project ? Best Regards, B PS: I'm seeing awsome potential in LP as a teaching tool ! I long for the day where I can direct my students to LP projects to help them understand the tought processes that went into great programs. PS2: I'd be willing to help fund LP work on Clojure[Script], now that donations to Clojure are not possible anymore . -- 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
Re: Literate programming
I'm a bit reluctant to get into this, because I'm new to clojure (and don't know the backstory of this post), but an old hand at literate programming (I recently did a podcast interview with Donald Knuth on LP). I'll be interested in the results of your survey. Larry On Wed, Oct 26, 2011 at 3:06 PM, wrote: > I see that my Literate Programming session is beginning to gain some > traction. I would encourage you to bring examples. We can discuss the > merits and possibly gain some new insights. If nothing else, please > sign up for the Literate Software session at Clojure-Conj. I promise > to keep it short. > > Literate programming can take various forms. I am working on a survey > of literate software. I came across an interesting non-latex example > worth sharing: > > http://jashkenas.github.com/coffee-script/documentation/docs/nodes.html > > Notice how well they have documented an apparently simple line as in: > > exports.Base = class Base > > The Base is an abstract base class for all nodes in the syntax tree. > Each subclass implements the compileNode method, which performs the > code generation for that node. To compile a node to JavaScript, call > compile on it, which wraps compileNode in some generic extra smarts, > to know when the generated code needs to be wrapping up in a > closure. An options hash is passed and cloned throughout, containing > information about the environment from higher in the tree (such as > if a returned value is being requested by the surrounding function), > information about the current scope, and indentation level. > > Notice how this is not only giving trivial information (e.g. Base is > an abstract base class) but WHY it exists (..as a base for all nodes in > the syntax tree). It gives operational information (to compile a node..) > as well as information about the effect (..which wraps...). It shows > how global information is used (An options hash..) and WHY (containing > information about the environment...) > > Code only tells you HOW something is done at the time it is done. > It's like having a recipe without an idea what you would make. > > If our standards of documentation were raised to this level then large > systems like Axiom, Clojure, and ClojureScript would be much easier to > maintain and modify in the long term. > > If you want your code to live beyond you, make it literate. > > Tim Daly > d...@literatesoftware.com > > > > -- > 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 -- *Off the Beaten Path in Technology http://otbeatenpath.wordpress.com * -- 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
Re: Literate programming
Programming pearls: a literate program http://www.cs.tufts.edu/~nr/cs257/archive/don-knuth/pearls-1.pdf On Wed, Oct 26, 2011 at 10:49 PM, jaime wrote: > is there a place introducing (e.g. overview) more about Literate? have > no ideas about this stuff. > > On Oct 27, 3:06 am, d...@axiom-developer.org wrote: >> I see that my Literate Programming session is beginning to gain some >> traction. I would encourage you to bring examples. We can discuss the >> merits and possibly gain some new insights. If nothing else, please >> sign up for the Literate Software session at Clojure-Conj. I promise >> to keep it short. >> >> Literate programming can take various forms. I am working on a survey >> of literate software. I came across an interesting non-latex example >> worth sharing: >> >> http://jashkenas.github.com/coffee-script/documentation/docs/nodes.html >> >> Notice how well they have documented an apparently simple line as in: >> >> exports.Base = class Base >> >> The Base is an abstract base class for all nodes in the syntax tree. >> Each subclass implements the compileNode method, which performs the >> code generation for that node. To compile a node to JavaScript, call >> compile on it, which wraps compileNode in some generic extra smarts, >> to know when the generated code needs to be wrapping up in a >> closure. An options hash is passed and cloned throughout, containing >> information about the environment from higher in the tree (such as >> if a returned value is being requested by the surrounding function), >> information about the current scope, and indentation level. >> >> Notice how this is not only giving trivial information (e.g. Base is >> an abstract base class) but WHY it exists (..as a base for all nodes in >> the syntax tree). It gives operational information (to compile a node..) >> as well as information about the effect (..which wraps...). It shows >> how global information is used (An options hash..) and WHY (containing >> information about the environment...) >> >> Code only tells you HOW something is done at the time it is done. >> It's like having a recipe without an idea what you would make. >> >> If our standards of documentation were raised to this level then large >> systems like Axiom, Clojure, and ClojureScript would be much easier to >> maintain and modify in the long term. >> >> If you want your code to live beyond you, make it literate. >> >> Tim Daly >> d...@literatesoftware.com > > -- > 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 > -- 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
Re: Literate programming
My two favorite articles on Literate Programming are both from Donald Knuth's book *Literate Programming*. One is "Computer Programming as an Art", and the other is "Literate Programming". When I was preparing to interview Knuth a bit over a year ago I re-read the entire book. I expected it to be a somewhat outdated description of WEB, TANGLE, and WEAVE. On the contrary it was wonderfully timeless. When I mentioned that to Knuth he sort of grumbled something to the effect of "Well, yes, some things in computer science have a long shelf life" (that's a paraphrase, but it was something like that). I haven't been working with it for awhile, but I did a somewhat primitive modification to the XML Docbook markup language (I just added a few appropriate tags for "tangling" the executable source code, and "weaving" the well formatted article documenting the code) which I used as the source language, then wrote a tangle and weave in perl. I got the idea from Norman Walsh's article Literate Programming in XML which can be found at http://nwalsh.com/docs/articles/xml2002/lp/paper.html The advantage of this was that given the array of tools for rendering Docbook "weaving" was a piece of cake, and perl had a good range of modules for doing the "tangle". As I stated, I'm very new to clojure, but I've always been fascinated with LP, and I'm very happy to see this discussion going on here. Larry On Wed, Oct 26, 2011 at 10:49 PM, jaime wrote: > is there a place introducing (e.g. overview) more about Literate? have > no ideas about this stuff. > > On Oct 27, 3:06 am, d...@axiom-developer.org wrote: > > I see that my Literate Programming session is beginning to gain some > > traction. I would encourage you to bring examples. We can discuss the > > merits and possibly gain some new insights. If nothing else, please > > sign up for the Literate Software session at Clojure-Conj. I promise > > to keep it short. > > > > Literate programming can take various forms. I am working on a survey > > of literate software. I came across an interesting non-latex example > > worth sharing: > > > > http://jashkenas.github.com/coffee-script/documentation/docs/nodes.html > > > > Notice how well they have documented an apparently simple line as in: > > > > exports.Base = class Base > > > > The Base is an abstract base class for all nodes in the syntax tree. > > Each subclass implements the compileNode method, which performs the > > code generation for that node. To compile a node to JavaScript, call > > compile on it, which wraps compileNode in some generic extra smarts, > > to know when the generated code needs to be wrapping up in a > > closure. An options hash is passed and cloned throughout, containing > > information about the environment from higher in the tree (such as > > if a returned value is being requested by the surrounding function), > > information about the current scope, and indentation level. > > > > Notice how this is not only giving trivial information (e.g. Base is > > an abstract base class) but WHY it exists (..as a base for all nodes in > > the syntax tree). It gives operational information (to compile a node..) > > as well as information about the effect (..which wraps...). It shows > > how global information is used (An options hash..) and WHY (containing > > information about the environment...) > > > > Code only tells you HOW something is done at the time it is done. > > It's like having a recipe without an idea what you would make. > > > > If our standards of documentation were raised to this level then large > > systems like Axiom, Clojure, and ClojureScript would be much easier to > > maintain and modify in the long term. > > > > If you want your code to live beyond you, make it literate. > > > > Tim Daly > > d...@literatesoftware.com > > -- > 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 > -- *Off the Beaten Path in Technology http://otbeatenpath.wordpress.com * -- 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
Re: Literate programming
On Thu, 2011-10-27 at 20:11 -0400, Larry Johnson wrote: > My two favorite articles on Literate Programming are both from Donald > Knuth's book Literate Programming. One is "Computer Programming as an > Art", and the other is "Literate Programming". When I was preparing > to interview Knuth a bit over a year ago I re-read the entire book. I > expected it to be a somewhat outdated description of WEB, TANGLE, and > WEAVE. On the contrary it was wonderfully timeless. When I mentioned > that to Knuth he sort of grumbled something to the effect of "Well, > yes, some things in computer science have a long shelf life" (that's a > paraphrase, but it was something like that). Knuth's invention of literate programming is one of the unrecognized pearls of computer science. I have yet to see a programming team that has an Editor-in-Chief who does patch-review for clarity, sentence structure, punctuation, relevance, location in the book, proper citations and index terms, etc. Maybe someday. > > I haven't been working with it for awhile, but I did a somewhat > primitive modification to the XML Docbook markup language (I just > added a few appropriate tags for "tangling" the executable source > code, and "weaving" the well formatted article documenting the code) > which I used as the source language, then wrote a tangle and weave in > perl. I got the idea from Norman Walsh's article Literate Programming > in XML which can be found at > http://nwalsh.com/docs/articles/xml2002/lp/paper.html > > The advantage of this was that given the array of tools for rendering > Docbook "weaving" was a piece of cake, and perl had a good range of > modules for doing the "tangle". Any means of publication can be the medium for literate programming. As I rule I prefer Latex but anything will do. All you need is a distinguished means of quoting and naming the chunks. In html this could be as simple as: your code and you need a program, often called "tangle", to extract the chunk tangle mywebpage.html somename >mysomename.file The machinery of literate programming is dirt simple. Poof! You're done. The hardest part of literate programming is the mindset. In order to do literate programming you need to change your focus from traditional programming to writing for humans and, as a side effect, writing for the machine. > > As I stated, I'm very new to clojure, but I've always been fascinated > with LP, and I'm very happy to see this discussion going on here. Java has taken the PDP 11/40 sand files to their logical extreme where we have wired the name of the tiny file to the name of the tiny object. We have packaged the automobile into a crate with labeled bags of screws, hoses, switches, etc. and are expected to understand the car. Clojure is a very early adoptive, open minded community willing to challenge old assumptions. It helps to highlight what those old assumptions are, as Rich has done for Lisp, since they can be difficult to see and hard to displace. I am hoping the community will disrupt the tiny-files, javadoc, IDE, code-for-the-machine, mindset and start communicating with humans. Rich has great ideas in Clojure and all we get is the dried bones of source code. We can do so much better. 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
Re: Literate programming
I've found org-mode in emacs quite acceptable for literate programming in clojure. http://orgmode.org/ git://orgmode.org/org-mode.git Here are some things I've used it for: http://aurellem.com/abomination/html/no_parens.html http://aurellem.com/pokemon-types/html/lpsolve.html http://aurellem.com/thoughts/html/man-years.html It's possible to automatically monitor the org files in a project, regenerate the html and source code whenever they are changed, and get a very tight write-debug-test cycle. Try it out it's fun! sincerely, --Robert McIntyre On Thu, Oct 27, 2011 at 8:52 PM, daly wrote: > > > On Thu, 2011-10-27 at 20:11 -0400, Larry Johnson wrote: > > My two favorite articles on Literate Programming are both from Donald > > Knuth's book Literate Programming. One is "Computer Programming as an > > Art", and the other is "Literate Programming". When I was preparing > > to interview Knuth a bit over a year ago I re-read the entire book. I > > expected it to be a somewhat outdated description of WEB, TANGLE, and > > WEAVE. On the contrary it was wonderfully timeless. When I mentioned > > that to Knuth he sort of grumbled something to the effect of "Well, > > yes, some things in computer science have a long shelf life" (that's a > > paraphrase, but it was something like that). > > Knuth's invention of literate programming is one of the unrecognized > pearls of computer science. I have yet to see a programming team that > has an Editor-in-Chief who does patch-review for clarity, sentence > structure, punctuation, relevance, location in the book, proper > citations and index terms, etc. Maybe someday. > > > > > I haven't been working with it for awhile, but I did a somewhat > > primitive modification to the XML Docbook markup language (I just > > added a few appropriate tags for "tangling" the executable source > > code, and "weaving" the well formatted article documenting the code) > > which I used as the source language, then wrote a tangle and weave in > > perl. I got the idea from Norman Walsh's article Literate Programming > > in XML which can be found at > > http://nwalsh.com/docs/articles/xml2002/lp/paper.html > > > > The advantage of this was that given the array of tools for rendering > > Docbook "weaving" was a piece of cake, and perl had a good range of > > modules for doing the "tangle". > > Any means of publication can be the medium for literate programming. > As I rule I prefer Latex but anything will do. > > All you need is a distinguished means of quoting and naming the > chunks. In html this could be as simple as: > > your code > > and you need a program, often called "tangle", to extract the chunk > tangle mywebpage.html somename >mysomename.file > > The machinery of literate programming is dirt simple. > Poof! You're done. > > The hardest part of literate programming is the mindset. > > In order to do literate programming you need to change your focus > from traditional programming to writing for humans and, as a side > effect, writing for the machine. > > > > > As I stated, I'm very new to clojure, but I've always been fascinated > > with LP, and I'm very happy to see this discussion going on here. > > Java has taken the PDP 11/40 sand files to their logical extreme where > we have wired the name of the tiny file to the name of the tiny object. > We have packaged the automobile into a crate with labeled bags of > screws, hoses, switches, etc. and are expected to understand the car. > > Clojure is a very early adoptive, open minded community willing to > challenge old assumptions. It helps to highlight what those old > assumptions are, as Rich has done for Lisp, since they can be > difficult to see and hard to displace. I am hoping the community > will disrupt the tiny-files, javadoc, IDE, code-for-the-machine, > mindset and start communicating with humans. Rich has great ideas > in Clojure and all we get is the dried bones of source code. > > We can do so much better. > > 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 -- 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
Re: Literate programming
Hi, just to be sure: are you are aware of Marginalia? https://github.com/fogus/marginalia Regards, Stefan -- 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
Re: Literate programming
Maybe COBOL already solves the problem which Literate Programming want to solve? -- 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
Re: Literate programming
On Thu, Oct 27, 2011 at 11:52 PM, daly wrote: > > Any means of publication can be the medium for literate programming. > As I rule I prefer Latex but anything will do. > > All you need is a distinguished means of quoting and naming the > chunks. In html this could be as simple as: > > your code > > and you need a program, often called "tangle", to extract the chunk > tangle mywebpage.html somename >mysomename.file > > Yep. That's all my Rube Goldberg-ish system did. The chunk of machine recognizable code was named as an attribute in a modified tag. The "weave" just stripped it out so you were left with "typeset ready" Docbook markup. The "tangle" just yanked out the target source code and wrote it to a file in the proper order. > > The hardest part of literate programming is the mindset. > > In order to do literate programming you need to change your focus > from traditional programming to writing for humans and, as a side > effect, writing for the machine. > > <http://groups.google.com/group/clojure?hl=en> > For programmers who are resistant to even commenting code LP must seem nightmarish (at least at first). Not only are you required to provide comments, but those comments have to be a complete, well formatted, human readable, journal article. Also, it takes some time getting one's head wrapped around the fact that the order in which the target language source code appears in the article is not necessarily the order in which the machine needs it for compilation and execution purposes. When LP is practiced consistently it prevents a number of bad habits, and I can't see that those good effects change whether one is using a "top down" or "bottom up" approach to programming. Since you're writing a complete, well formatted, human readable, article on how the code works, you can't just cut-and-paste code into a project without really understanding what the code is doing (well, I guess you can, but that would become obvious while you or another reader were trying to follow the article). -- *Off the Beaten Path in Technology http://otbeatenpath.wordpress.com * -- 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
Re: Literate programming
Hi Tim, while I agree that good documentation is important for maintaining and developing further a given code base, I always wonder how literate programming deals with refactoring and larger restructuring. I mean, in basically all software projects I'm involved in, developers have a hard time in keeping at least the most integral documentation up-to-date, e.g., docstrings, JavaDocs, etc. Now I consider a some literate code base, i.e., a book that describes the complete system in a very detailed manner including the reasons to design it that way. That's awesome for developers joining the project, but doesn't it hinder any further development? For example, I'm currently reworking some paper that includes code for some model transformation. If I had the right tools, I could extract the source code from the latex files and have a running transformation. But now, I had to do some minor modifications to the code which took me about 5 minutes, but adapting the surrounding text takes me hours over hours. I think, that's an experience many people have made: changing source code of a system that is well-designed and understood by the developer is much easier to do than changing a cohesive text in natural language. In code, I have an automated, picky lector that always reads the complete "book" after each change I make (also known as compiler). In plain text, only a human can verify consistency and only in very narrow borders. Well, that's more text than I intended to write. ;-) So short story long: how do you manage conistency of docs and code in literate code bases? Bye, Tassilo -- 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
Re: Literate programming
On Fri, 2011-10-28 at 11:59 +0200, Tassilo Horn wrote: > Hi Tim, > > while I agree that good documentation is important for maintaining and > developing further a given code base, I always wonder how literate > programming deals with refactoring and larger restructuring. I mean, in > basically all software projects I'm involved in, developers have a hard > time in keeping at least the most integral documentation up-to-date, > e.g., docstrings, JavaDocs, etc. > > Now I consider a some literate code base, i.e., a book that describes > the complete system in a very detailed manner including the reasons to > design it that way. That's awesome for developers joining the project, > but doesn't it hinder any further development? > > For example, I'm currently reworking some paper that includes code for > some model transformation. If I had the right tools, I could extract > the source code from the latex files and have a running transformation. > But now, I had to do some minor modifications to the code which took me > about 5 minutes, but adapting the surrounding text takes me hours over > hours. I think, that's an experience many people have made: changing > source code of a system that is well-designed and understood by the > developer is much easier to do than changing a cohesive text in natural > language. In code, I have an automated, picky lector that always reads > the complete "book" after each change I make (also known as compiler). > In plain text, only a human can verify consistency and only in very > narrow borders. > > Well, that's more text than I intended to write. ;-) So short story > long: how do you manage conistency of docs and code in literate code > bases? Hard work? Book authors face the same problem. Every new change to Clojure makes more work for the authors. One side-effect of Literate Programming is that you re-arrange your code to fit the presentation. As a result you bring together chunks that are all related (e.g. the code to support Red-Black tries). I would claim that refactoring "in the large" is unlikely in a literate program because you have to think through the code in order to explain it clearly. But if you do a large refactor then it is just hard work. For small refactorings you might not have to change the explanation at all. Clojure is pretty well "firmed up" at this point. I don't know if there is going to be a large rewrite of the fundamentals. 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
Re: Literate programming
On Thu, Oct 27, 2011 at 10:58 AM, daly wrote: >> Have there been any new developments on the literate programming / >> Clojure front, in terms of tools that leverage existing build tools, >> test suites, generating meaningful line numbers for stack traces and >> debugging? >> > > The question is ill-posed in sense that literate programming is not > a tool or technology but a change in mindset. To quote Knuth: I think my question is legitimate. To take an extreme example, if you tell me literate programming is great, but that I have to write out my programs by hand on paper and scan them into a computer, I'd laugh at you. Why would I want to give up the convenience of typing in my programs via keyboard to do literate programming? So I'd like an honest appraisal of the state of the art in literate programming of Clojure -- what tools and conveniences do I have to give up to do LP. Do I have to give up things like meaningful line numbers when I get an error message? -- 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
Re: Literate programming
On Fri, 2011-10-28 at 09:54 -0700, Mark Engelberg wrote: > On Thu, Oct 27, 2011 at 10:58 AM, daly wrote: > >> Have there been any new developments on the literate programming / > >> Clojure front, in terms of tools that leverage existing build tools, > >> test suites, generating meaningful line numbers for stack traces and > >> debugging? > >> > > > > The question is ill-posed in sense that literate programming is not > > a tool or technology but a change in mindset. To quote Knuth: > > I think my question is legitimate. > > To take an extreme example, if you tell me literate programming is > great, but that I have to write out my programs by hand on paper and > scan them into a computer, I'd laugh at you. Why would I want to give > up the convenience of typing in my programs via keyboard to do > literate programming? I'm not sure what tools you use for development. Straight emacs is sufficient for my development. Emacs doesn't care what style is used for development. > > So I'd like an honest appraisal of the state of the art in literate > programming of Clojure -- what tools and conveniences do I have to > give up to do LP. Do I have to give up things like meaningful line > numbers when I get an error message? > State of the art in literate programming in Clojure? Hmmm. The pamphlet link is my only example of literate programming related to Clojure. In order to develop you edit the pamphlet, type "make" at a command line, and the world is rebuilt. Since the code is extracted into the same source tree as it originally had, the line numbers will be related to the file and line as before. My development style involves changing about 10 lines of code or less followed by a complete system rebuild and test cycle. Overlapping rebuild and test is time for writing the literate explanations. Almost always, when something fails it is perfectly clear what lines caused the error. When that isn't the case then a little "navel debugging" (contemplating what might be wrong) is used. I don't use IDEs but I suppose it would be possible to write a literate plugin of some kind that ignored things that were not in code chunks. Line numbers could then be interpreted with respect to the start of the chunk. Most IDEs allow plugins. To your point, though, it is true that we may have reached a local optimum of tool development for tiny files. It might be necessary to move away from this peak in order to climb a different hill. This would imply making things "worse" for development until the tools adapt. Clojure moved off the local optimum of common lisp and broke all my code-walking software, violated quite a few of my assumptions, and invalidated my manuals but that isn't an argument for abandoning Clojure. You might feel that the current toolset is optimal and that literate programming is not worth the time and effort. De gustibus non disputandum. (There is no disputing taste). A literate Clojure would only be of benefit to those who come after. All it offers now is a lot of time and effort to communicate ideas to people we will never meet. However the thing that draws people to Clojure is the ideas, not the code. We can debate it at length over beers at the Conj. 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
Re: Literate programming
Clojure moved off the local optimum of common lisp > I can't help, but I really like that quote. Nice meme :-) Stefan -- 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
Re: Literate programming
I have also been using Emacs/Org-mode/Babel/R lately, mostly as a way to have easily modifiable write up and source code for assignments in statistics courses. I suppose this is one valid use, but I'm using it less to communicate code meaning and more as a convenient way to perform analysis, look at the results, and talk about them all in the same place, and then to easily generate documentation of my efforts [LaTeX output]. I have added the suggested LP readings from earlier in this thread to my "reading queue". Looking forward to this meetup! Best, Damion On Friday, October 28, 2011 12:21:47 AM UTC-4, Robert McIntyre wrote: > > I've found org-mode in emacs quite acceptable for literate programming > in clojure. > > -- 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
Literate Programming example
Many of you asked me to show an example of a literate program and demonstrate the use of the tangle function. I usually use Latex for literate work but I've done this example using HTML and tags. I've written a self-referential literate program that explains the details of the tangle function in literate form. You can find the web page at http://daly.literatesoftware.com/lithtml/litprog.html and the source for the tangle function (which is in the web page but) http://daly.literatesoftware.com/lithtml/tangle.c I appreciate the time and attention you all gave me at the Clojure Conj. Hopefully someone will "catch the ah-ha" and write a literate program for next year's Conj. Tim Daly d...@literatesoftware.com -- 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
Re: Literate programming
On Fri, Oct 28, 2011 at 2:45 PM, Damion Junk wrote: > I have also been using Emacs/Org-mode/Babel/R lately, mostly as a way to > have easily modifiable write up and source code for assignments in > statistics courses. I suppose this is one valid use, but I'm using it less > to communicate code meaning and more as a convenient way to perform > analysis, look at the results, and talk about them all in the same place, > and then to easily generate documentation of my efforts [LaTeX output]. I'm interested in how you're including LaTeX in your code, as I'm writing models which require LaTeX to express what they're modelling. BTW I looked at marginalia+leiningen, which seems to work for my purposes except I'm unclear where to put the .tex files. The combination of literate + TDD seems forbidding. Damion > Adam -- "Invincibility is in oneself, vulnerability in the opponent." -- Sun Tzu -- 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
Re: Literate programming
On Tue, 2011-12-20 at 00:26 -0800, Adam Getchell wrote: > > > On Fri, Oct 28, 2011 at 2:45 PM, Damion Junk wrote: > I have also been using Emacs/Org-mode/Babel/R lately, mostly > as a way to have easily modifiable write up and source code > for assignments in statistics courses. I suppose this is one > valid use, but I'm using it less to communicate code meaning > and more as a convenient way to perform analysis, look at the > results, and talk about them all in the same place, and then > to easily generate documentation of my efforts [LaTeX output]. > > > I'm interested in how you're including LaTeX in your code, as I'm > writing models which require LaTeX to express what they're modelling. > > > BTW I looked at marginalia+leiningen, which seems to work for my > purposes except I'm unclear where to put the .tex files. I'm not sure what this sentence means. The .tex files ARE the literate program. By analogy, you seem to be asking something like "I'm writing a book but I don't know where to put the text". > > > The combination of literate + TDD seems forbidding. Are you finding it hard to explain why you wrote a test? 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
Re: Literate programming
On Thu, Dec 22, 2011 at 2:54 PM, daly wrote: > > > > > The combination of literate + TDD seems forbidding. > > Are you finding it hard to explain why you wrote a test? > > Tim Daly > > I decided awhile back when trying to answer questions about literate programming, that people get caught up in the moving parts, and not in what the approach actually yields. Your statement above puts it nicely and succinctly, and hearkens back to Knuths original articles. Lately I emphasize the woven text (without inititially calling it that) and ask the person I'm talking with to imagine writing an article or book about their code, how it works, with proofs where appropriate. That article should be written as a work of literature. Not all literature has to be Hugo or Melville (or Jack Kerouac, or Gertrude Stein for that matter). Some programs are more appropriately Mickey Spillane or Terry Pratchett, or even in the style of a manual for an electric razor. The point is that it should be satisfying to read and comprehensively informative. Test code, and descriptions of external libraries are no different from any other sections of the article or book. The most important thing is to introduce them into the work at point most conducive to the reader's understanding. I really believe that there's no programming or engineering methodology which doesn't lend itself to literate programming. If it can be described, it can be presented in the form of an article. If it can't be describe in human language it's probably terrible code. Larry -- 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
Re: Literate programming
On Thu, 2011-12-22 at 15:35 -0500, Larry Johnson wrote: > > > On Thu, Dec 22, 2011 at 2:54 PM, daly > wrote: > > > > > The combination of literate + TDD seems forbidding. > > > Are you finding it hard to explain why you wrote a test? > > Tim Daly > > > > I decided awhile back when trying to answer questions about literate > programming, that people get caught up in the moving parts, and not in > what the approach actually yields. Your statement above puts it > nicely and succinctly, and hearkens back to Knuths original articles. > Lately I emphasize the woven text (without inititially calling it > that) Untangling woven text is trivial. It can be done in any language. See http://axiom-developer.org/axiom-website/litprog.html > and ask the person I'm talking with to imagine writing an article or > book about their code, how it works, with proofs where appropriate. > That article should be written as a work of literature. Not all > literature has to be Hugo or Melville (or Jack Kerouac, or Gertrude > Stein for that matter). Some programs are more appropriately Mickey > Spillane or Terry Pratchett, or even in the style of a manual for an > electric razor. The point is that it should be satisfying to read and > comprehensively informative. > > Test code, and descriptions of external libraries are no different > from any other sections of the article or book. The most important > thing is to introduce them into the work at point most conducive to > the reader's understanding. If a test is testing something worthwhile, as opposed to the "blindly testing that 3=3" mindset, then it probably only takes a couple lines to motivate why you need the test. A test paragraph could contain the details. So if you're writing a hash table implementation, the test code of overflow chaining could explain what problems might occur (e.g. what happens when the table is actually full? How do you detect that the overflow chain has looped?, etc.) So if you wrote the hash table implementation code in literate form then each test could explain (and test) a particular boundary case or issue that might arise. This has the effect of motivating tests that are detailed, based on real issues, and handle boundary cases clearly. > > I really believe that there's no programming or engineering > methodology which doesn't lend itself to literate programming. If it > can be described, it can be presented in the form of an article. If > it can't be describe in human language it's probably terrible code. Test cases don't have to appear as "test cases". They appear in the text as either example code (useful for the reader but also testing) or as explanations of possible failures, misuse, misapplication, or boundary cases. This is especially powerful if you focus your tests on precondition/postcondition testing. See Hoare's paper "An Axiomatic Basis for Computer Programming" http://citeseer.ist.psu.edu/viewdoc/summary?doi=10.1.1.116.2392 Using Hoare's ideas to focus the development of your test cases means that your tests have a good theoretical basis. They check for the conditions that should survive refactoring. Requiring precondition postcondition tests, along with clearly written natural language explanations, could be part of the peer code review prior to accepting new or revised code into the main line. Better yet, in a literate program, you can explain what the invariant is, why it is important, and what breaks when you violate it. So testing now has a good formal basis rather than random 3=3 tests. We can be so much better programmers. Raise your game. Be literate. 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
Re: Literate programming
Probably the most effective way to really hammer the benefits of literate programming into the clojure community would be to take a manageable but serious and well known clojure program, module, or library, and render it into literate form. As a clojure programmer, I'm not even there. But as someone to help with the literate part, I'd be thrilled to help out. -- 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
Re: Literate programming
Why should I write English in the first place? Because it helps me to think; and it helps me to "program" other people to think like me. But I would never have learned English unless along the way it gave me near-term results. It should follow, then, that telling people to write literate programs for the sake of posterity is never going to be enough to change mindsets. Taking an illiterate [sic] program and making it literate as you are doing with Clojure will be a tour-de- force, and an intimidating one at that. I think that making literate programming incrementally useful, however, is \inevitably going to involve tooling. Of two kinds, if you follow the logic above: social, and personal. Firstly, there really needs to be something like a Github for literate programming. Why? Because a literate program will be easier to \understand, but also easier to \find (see example below). Imagine a sort of "function search engine"code liberated from namespaces and leiningen projects, annotated and independently useable. If there were a community that actually \took \advantage of findability and understandability, it would greatly speed coding (think of how much time you have to spend hunting for documentation), and in the process not only \promote literate programming but make it \advantageous. On the personal side, writing English as part of coding has to be maximally efficient for us humans: no retyping. The identifiers we use in English should flow into the code, and vice-versa. Take the following example: To CAPITALIZE EVERY WORD in a STRING: Split the STRING on SPACE into WORDS; CAPITALIZE the first letter of every WORD, producing CAPITALIZED WORDS. Re-assemble[JOIN] the string on SPACE, to make the CAPITALIZED STRING. Using functions from clojure.string: split, join, capitalize; see documentation: http://docs.oracle.com/javase/1.5.0/docs/api/java/util/regex/Pattern.html http://clojure.org/other_functions http://www.fatvat.co.uk/2009/01/regular-expressions-in-clojure.html http://clojure.github.com/clojure/clojure.string-api.html (defn capitalize-every-word [m-string] (let [m-space " " regex-space #"\s" words (split m-string regex-space) capitalized-words (map capitalize words) capitalized-string (join m-space capitalized-words)] capitalized-string)) (defn c-e-w [m-string] (join " " (map capitalize (split m-string #"\s" Now there is actually not that much novel text here, and typing it out was an enlightening exercise (to really see how enlightening, you'd have to see the full example; but I've omitted it because the Internets are already complaining about a long post not written in their native Twitterese). But it was very cumbersome and time- consuming to do it. This cumbersomeness was incidental: because my activities were split among editing, browsing, and coding, for one thing; and also (not a complaint, Rich!) because our programming languages do not incorporate basic English concepts like abbreviation and definition-in-place. (One of the big advantages of writing English along with code is that you come up with sensible identifiers. Without English, it's a puzzling exercise done completely out of context.) You can't tell me this isn't a problem for IDE's to handle. At a minimum, I want my IDE to link up the identifiers between code and English. If they do, look at what happens: the identifiers get enriched by natural language context (notice, for instance, how JOIN gets associated with 'assemble'), and if we push everything to our social tool, the code ends up with more paths to be located by. We don't yet have Google-level findability for code, of course; but I would argue that this is not a technological defect, it is simply a failure of description! Once we have literate code, Google will build a function search engine for us. -- 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
Re: Literate programming
On Thu, 2011-12-22 at 17:53 -0800, nchurch wrote: > Firstly, there really needs to be something like a Github for literate > programming. What a great idea! I'll see what I can do. 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
Re: Literate programming
I'll do everything I can to help. I have tons of thoughts (as you might guess); but I haven't demonstrated myself to be a great coder, yet. I feel like I'm a coder who needs something like literate programming to be great, so it's kind of a chicken-and-egg problem. I'm already partway there with the existence of Clojure, but although it's the most intelligent language I've every come across (and it is at least Lisp), it still isn't enough. On Dec 22, 11:14 pm, daly wrote: > On Thu, 2011-12-22 at 17:53 -0800, nchurch wrote: > > Firstly, there really needs to be something like a Github for literate > > programming. > > What a great idea! > I'll see what I can do. > > 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
Re: Literate programming
While we're on the topic of a literate Github, let me just point out
that we might want to go just a little beyond Github to the way we
write code itself. Look again at the capitalize-every-word function I
defined above. In my original unshortened commentary, I included also
this:
.
To split a string into words (in the simplest case):
Split the string on a separator, the canonical one being space, but
also including punctuation characters such as ",';:./(){}-+_|\
BUT: Re-assembling the string will not reproduce the old string in
general unless space is the only character that splits. In order to
preserve this simple abstraction, we would need to rewrite split and
assemble. We could also change the string in-place.
Ossia: To split a string into words:
Split the string on space. Use clojure.string/split.
.
You can see that I am writing here not only about the current good-
enough implementation, but a \future implementation, should it ever be
needed. In fact, I discovered a bug in my code before I ever wrote
the code; but the question is what to do about the bug!
What I really want you to notice is how we are faced with a choice:
either we improve the library code (presumably by making split
optionally return an array of separators matched by the regex for
later reassembly by join, perhaps in metadata of some sort), or we go
with a less felicitous abstraction. There probably should be some
sort of formal analogue to this decision point in the natural language
text.
What does this mean for a Github? It may meanand no doubt this
will be controversialthat once we have the capability of a
function search engine, we don't really worry about there being
canonical library code any more. If I face this particular problem,
maybe I decide to re-write Join and Split to my own specifications. I
then put them out there under my own namespace, and when someone needs
to use them they just type (use '[nchurch :only join split]) wherever
they are in their file, or whatever the exact incantation is (this is
one place I always need to go to the docs). They have no trouble
browsing multiple alternatives, because they can see at a glance how
each one differs.
Now we have possibly multiple joins and splits; and so the community
no longer has a standard! Well, it would seem to me this fits well
with Github's always-fork philosophy. I do think there is only one
way to write a good library function, but it may be that there will
need to be a proliferation of alternativeseach making its own
argument and tradeoffs across various levels of abstraction, to return
to the theme of literate programmingbefore an optimal basis is
discovered. (There must have been a time before phillips head vs.
regular.) And when that happens, perhaps it goes into
clojure.string (modulo legalities about contributor agreements
something that might also be handled at the Github level, by the
way.).
On Dec 22, 11:19 pm, nchurch wrote:
> I'll do everything I can to help. I have tons of thoughts (as you
> might guess); but I haven't demonstrated myself to be a great coder,
> yet. I feel like I'm a coder who needs something like literate
> programming to be great, so it's kind of a chicken-and-egg problem.
> I'm already partway there with the existence of Clojure, but although
> it's the most intelligent language I've every come across (and it is
> at least Lisp), it still isn't enough.
>
> On Dec 22, 11:14 pm, daly wrote:
>
>
>
>
>
>
>
> > On Thu, 2011-12-22 at 17:53 -0800, nchurch wrote:
> > > Firstly, there really needs to be something like a Github for literate
> > > programming.
>
> > What a great idea!
> > I'll see what I can do.
>
> > 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
Re: Literate programming
On Thu, Dec 22, 2011 at 11:59 PM, nchurch wrote: > What I really want you to notice is how we are faced with a choice: > either we improve the library code (presumably by making split > optionally return an array of separators matched by the regex for > later reassembly by join, perhaps in metadata of some sort), or we go > with a less felicitous abstraction. There probably should be some > sort of formal analogue to this decision point in the natural language > text. Seems to me that the structure is this: A string that's written language is some alternating form like word separator word separator ... where a "word" consists of consecutive alphanumeric characters and a "separator" consists of consecutive nonalphanumeric characters. The separators in this paragraph include " ", " \"", "\" ", ". ", and " \" \", \" \\\"\", \"\\\" \", \". \", ", as well as one more that I can't add here without generating one more still. One tends sometimes to want to split a string in such a fashion, transform the words only, and then reassemble. This in turn suggests tools like: (wordify string) -> a seq of strings starting with a separator and alternating words and separators. The initial separator may be "". Something like (map #(apply str %) (group-by alphanumeric? string)) with alphanumeric? testing a character, but if the first character of the first string in the output seq is alphanumeric, a (cons "" %) needs to be done on the output before returning it. (map-words* f wordified-string) -> (interleave (take-nth 2 wordified-string) (map f (take-nth 2 (next wordified-string (map-words f string) -> (apply str (map-words* f (wordify string))) or similar. -- 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
Re: Literate programming
On Thu, 2011-12-22 at 20:19 -0800, nchurch wrote: > I'll do everything I can to help. I have tons of thoughts (as you > might guess); but I haven't demonstrated myself to be a great coder, > yet. I feel like I'm a coder who needs something like literate > programming to be great, so it's kind of a chicken-and-egg problem. > I'm already partway there with the existence of Clojure, but although > it's the most intelligent language I've every come across (and it is > at least Lisp), it still isn't enough. > > On Dec 22, 11:14 pm, daly wrote: > > On Thu, 2011-12-22 at 17:53 -0800, nchurch wrote: > > > Firstly, there really needs to be something like a Github for literate > > > programming. > > > > What a great idea! > > I'll see what I can do. > > > > Tim Daly > I looked into cloning a github into "lithub" but that path won't work. Github does not publish its source code. Other things like gitorious are available but the setup is a challenge. 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
Re: Literate programming
>I'll do everything I can to help. I have tons of thoughts (as you
>might guess); but I haven't demonstrated myself to be a great coder,
>yet. I feel like I'm a coder who needs something like literate
>programming to be great, so it's kind of a chicken-and-egg problem.
>I'm already partway there with the existence of Clojure, but although
>it's the most intelligent language I've every come across (and it is
>at least Lisp), it still isn't enough.
Do yourself a favor and lose the "great coder" meme. Or get a job
at google and remain blissfully unaware.
One of the best books I've ever read about programming is called
"Practicing: A Musician's Return to Music" where the author talks
about his development as a musician. He would receive compliments
on how great he was at playing the guitar. At one point he replies
"How would you know?". The better he got, the worse he knew he was.
Your opinion of how great you are at programming will follow a
bell curve. You'll start off coming out of college thinking you're
ok, memorize a few algorithms and order theory ("the google disease")
and think you're "great" ("google only hires great coders"). But as
you learn more you'll discover that you have SO much more to learn
and as you work on larger projects you'll discover the musician's
insight. People would rate you "great" but you'll be able to say
"How would you know?". At which point, the better you get, the worse
you'll know you are.
Anybody who rates themselves as "great" is probably on the uphill
side of the learning curve.
The fact that you're trying to learn Clojure, moving into areas
that are beyond your comfort zone, and trying to learn literate
programming to improve your game, all points to the fact that you
will likely reach a point where you feel that being labeled "great"
is a sign that the speaker is clueless. Give it 1 hours.
On Thu, 2011-12-22 at 20:59 -0800, nchurch wrote:
> You can see that I am writing here not only about the current good-
> enough implementation, but a \future implementation, should it ever be
> needed. In fact, I discovered a bug in my code before I ever wrote
> the code; but the question is what to do about the bug!
You found it. This is the magic hidden in literate programming.
Writing the natural language explanation, either before or during
coding exposes bugs before they get into the code. It exposes
hidden assumptions that will break boundary cases.
It is hard to demonstrate this effect. You have to try to write a
literate program and wait for the aha! moment to occur.
Lisps in general, and Clojure in particular, have the same aha!
moment where you transition from "how could anyone code like this?"
to "how could anyone code any other way?".
Pick some useful task, like a code-walker that will list all of
the called functions in a Clojure s-expression, and try to write
a literate version. Odds are good that you will learn more than
you ever wanted to know about Clojure. And, oh-by-the-way,
everyone else can read your literate code and learn Clojure too.
How sweet it that?
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
Re: Literate programming
On Thu, Dec 22, 2011 at 11:54 AM, daly wrote: > On Tue, 2011-12-20 at 00:26 -0800, Adam Getchell wrote: > > BTW I looked at marginalia+leiningen, which seems to work for my > > purposes except I'm unclear where to put the .tex files. > > I'm not sure what this sentence means. The .tex files ARE the > literate program. By analogy, you seem to be asking something like > Please allow me to elucidate. In the literate programming tool I mentioned, marginalia, the output is, in fact, raw HTML. A very kind gentlemen involved with the project pointed me to the source code documentation wherein I discerned that the LaTeX code was to be embedded directly in the comments. Unfortunately, at present the moderately complex equations with which I should like to document have not rendered in a fitting manner so as to be read or understood clearly. > "I'm writing a book but I don't know where to put the text". > That question, good sir, would seem to depend upon the choice of writing implement and media. Would not a Victorian gentleman, asked to pen such a book, eventually display a puzzled comportment were he to be presented a computer monitor? Clearly, as a craftsman of computer algebra tools yourself, you must agree that the selection of implements is of some import, lest you abandon that enterprise entirely and use Mathematica instead. > The combination of literate + TDD seems forbidding. > > Are you finding it hard to explain why you wrote a test? > The difficulties with which I have found myself in relate to some degree to my extreme inexperience with their methodologies, both theoretical and practical, as well as some odd discrepancies with the particular set of tools I have chosen. In another response to a separate missive, a gentlemen confirmed that there were some strange interactions betwixt midje and marginalia. Having received the benefit of your kind reply, I must confess to a puzzlement which has vexed me ever since I read your missive. It is this: how should I have read it so as to receive some knowledge or insight with which I had not formerly possessed in the moments prior? For in truth I have not been able to discern its helpfulness thereby. Adam Getchell -- 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
Re: Literate Programming
On Sat, 2011-12-24 at 12:56 -0600, Jay Edwards wrote: > Like this? http://brighterplanet.github.com/flight/impact_model.html My first reaction, after the first reading was "almost ok". The task is reasonably mathematical so it seems useful to show the equations. Unfortunately, at the end, I have to ask myself the "Hawaii question" If someone sent me off to hawaii (so I couldn't talk to the author), would I know enough to maintain the program? Well, maybe. I really liked that they embedded a link to the impacts web page. That placed the problem in context. And I especially liked "A multiplier to account for the extra climate impact of greenhouse gas emissions high in the atmosphere. Use 2.0 after Kollmuss and Crimmins (2009)." I was unhappy with: =begin FIXME TODO date should already be coerced =end Really? Coerced to what, by what, for what reason, in what format? I was just hired and asked to solve this problem. =begin FIXME TODO deal with cities in multiple countries that share a name Tried pushing country, which works on a flight from Mexico City to Barcelona, Spain because it does not include flights to Barcelona, Venezuela BUT it doesn't work if we're trying to go from Montreal end up with flights to London, United Kingdom. Also pushing country breaks addition of cohorts - all 'AND' statements get changed to 'OR' so you end up with all flights to that country e.g. WHERE origin_airport_iata_code = 'JFK' OR origin_country_iso_3166_code = 'US' =end So why isn't this part of the dialog? Why does it break? Is the database improperly structured? Do we need a schema change? Or do we need program logic to handle this case? The use of FIXME is horribly jarring. Get rid of it. Think of a calculus textbook where the source code is the equations. Now imagine that in the middle of an equation you see the above comment. Something like: area = \sum_i^j x*3 =begin FIXME might be x^4 =end * y The editor-in-chief would never let the above equation get into the text. The FIXME should be discussed as part of the prose rather than "in the equations". I don't think it would pass the code review phase with these "FIXME" things hanging around. FIXME is the programmer's internal dialog. Discuss the issue in the text as though you were talking to someone other than yourself. Odds are good this is where a design mistake (e.g. in the database schema) or a program bug lurks. The meta-issue is distinguishing "communication" from "documentation". Literate programming is about communication, not documentation. Write with your audience in mind and assume that the audience is NOT your shower committee (a shower committee is the group of people you talk to in the shower who are not really there). This example really skates along the border. Overall I think it is wildly better than most examples I've seen. I'd much rather maintain this program with the text than without it. I'd certainly place it on the high side of the curve. 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
Re: Literate programming
Like this? http://brighterplanet.github.com/flight/impact_model.html You can see how they handle it (from a Ruby-centric perspective) here: https://github.com/brighterplanet/numbers/blob/gh-pages/_posts/2010-12-02-github-pages-rocco-and-rake-file-tasks.markdown The same approach should work fine for a Clojure project. J. On Dec 22, 2011, at 10:14 PM, daly wrote: > On Thu, 2011-12-22 at 17:53 -0800, nchurch wrote: >> Firstly, there really needs to be something like a Github for literate >> programming. > > What a great idea! > I'll see what I can do. > > 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 -- 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
Re: Rethinking Literate Programming
PS. Just to be clear, my purpose is neither to attack nor to defend LP, just to get clear about exactly what it is, what its presuppositions are, what its implications are, etc. -G On Thu, May 8, 2014 at 7:57 AM, Gregg Reynolds wrote: > The thread on documentation that Val started ( > https://groups.google.com/forum/?hl=en#!topic/clojure/oh_bWL9_jI0) is > getting a little long so I'm starting a related one specific to litprog. > > I've made a start on rethinking LP at > https://github.com/mobileink/codegenres/wiki/Rethinking-Literate-Programming > . > > A few key points: > > * Knuth's main early LP tool (WEB) was to a certain extent an attempt to > fix deficiencies in Pascal, as Knuth himself explicitly acknowledged. Some > aspects of Knuthian LP (KLP) may make sense for imperative languages with > side effects; since it's hard to reason about programs written in such > languages, added commentary is needed. But if you already know that > functions are side-effect free and data are immutable, you no longer need > that. > * Programming language design has not evolved in the direction of LP, as > we might have expected from some of Knuth's more grandiose pronouncements; > instead they have evolved in the direction of greater expressivity, which > obviates the need for many kinds of documentation. You can argue that LP > was a fine thing in its day, but the world has moved on. > * KLP is largely based on the personal aesthetic and psychological > preferences of DE Knuth involving issues such as the proper order and mode > of presentation of code. Those are normative issues, and there is no > reason to take Knuth's preferences as gospel. In particular there is no > justification for his claim that using LP "methods" leads to "better" > code. It not only depends on what "better" means, it depends on what other > methods are available. Just because writing Pascal in LP was better (for > Knuth et al.) than writing plain Pascal does not mean this will always be > the case in all languages. It doesn't generalize. (To a hammer, > everything looks like a goto.) > * There is (demonstrably) no reason to think that there is any "natural" > or "best" order of presentation for code; there are only preferences, and > everybody has one, if you catch my drift. The point again being that Knuth > was not on to some kind of laws of programming. KLP is all about his > preferred style, not about the Way Things Are. > * KLP is sometimes contrasted with "self-documenting code" To get a grip > on what that is and what we can expect from it we need to examine the > notions of function, algorithm, and code. Then it looks like code does not > in fact "self-document", if "documentation" is taken to mean explanation. > But it does express meaning, and sometimes expressivity is preferrable to > explanation. Maybe that's terminological nit-picking, but sometimes coming > up with the right terminology makes all the difference (see "lambda > abstraction"). > * Speaking of which, Knuth himself admitted that his choice of "literate > programming" as the name of his "new method" was tongue in cheek, since it > makes anybody who doesn't use it an "illiterate programmer". (The citation > is in one of the essays in his book "Literate Programming".) So maybe we > should stop using it and come up with a more accurate name. Howsabout > "Knuthian Programming"? > * Knuth's model for program text is the literary essay, read from > beginning to end. This is obviously in tension with the way code actually > works. Library code usually does not have a beginning or end, for > example. This is a little ironic, since hypertext has liberated us from > the tyranny and oppression of linear narrative. A better literary analog > to program text is The Book of Lists, or Commonplace books, whose contents > can be read in any order. > * Finally, a whiff of a hint of a soupcon of a concrete proposal: instead > of supporting some kind of structured markdown-style syntax in comments and > docstrings, add support for the Z specification notation, so that we can > express in clear, concise, formally defined, standard set-theoretic > notation the exact meaning of code. That's the general idea, I don't have > a concrete suggestion yet. > > There's more stuff on the > wiki<https://github.com/mobileink/codegenres/wiki/Rethinking-Literate-Programming>, > and more to be said, but I'll stop here. > > Cheers, > > Gregg > > > > -- You received this message because you are subscribed to the Google Groups "Clojur
Re: Rethinking Literate Programming
Greg, I can tell by the amount of work you've put into this document that this is an earnest attempt at analysis and not trolling, so I'm going to give you my earnest response: you are wrong on so many levels. First, you seem to have several misconceptions about literate programming in general, and Knuth-style literate programming specifically, which makes me wonder whether you've ever actually read Knuth's code. For example, you say, "Knuth's model for program text is the literary essay, read from beginning to end. This is obviously in tension with the way code actually works." Yes, it is true that one goal of literate programming is to free the programmer to choose an order to describe the code that is independent of the order and structure that the compiler needs to see it. But a Knuth-style literate program is far more than a linear essay. Although you *can* often read a literate program from beginning to end in order to understand the full system, the detailed hyperlinking and indexing makes reading code almost more like a choose-your-own-adventure story, making it easy to understand the parts of code you care about and understand how the different parts relate to one another. I suggest you sit down and read some actual Knuth code if you want to try to understand what that approach does and does not accomplish. Second, you repeatedly make the case that programming expressiveness (and presumably Clojure's expressiveness specifically) is far better than in Knuth's time. This is nonsense. LISP is one of the oldest languages, and Clojure isn't profoundly different in its expressiveness. In fact, Clojure has a number of features that actively hurt its expressiveness relative to other modern languages: 1. Definitions must precede their usage. Can usually work around this with forward-declarations, but even that small extra burden causes programmers to tend towards a bottom-up style of writing Clojure code, even if that is not desirable for a certain program. 2. Very strict limitations on ways that different files/namespaces relate to one another (e.g., no cyclic dependencies), so very often, things need to be organized for the convenience of the compiler rather than for understanding. 3. Limited convenient notation for expressing that a function is merely a "helper function" (only defn has a convenient notation for this, defn-). 4. The tooling convention of having tests in separate files places even more obstacles in the way of using things like defn- in order to express the distinction between primary and secondary functions. 5. Clojure's inability to handle local recursive references (i.e., no letrec) provides obstacles for clearly expressing that certain things are merely local functions/data for another function. Some things have to be made global that conceptually aren't. 6. The "sea of sameness" problem -- no visual distinction between functions, macros, variables, control constructs. You state that functional programs are so much easier to comprehend than mutable ones, they don't really require explanation. This also is silly. I challenge you to buy this book: http://www.amazon.com/Pearls-Functional-Algorithm-Design-Richard/dp/0521513383, a collection of literate programs (in the academic article sense of the word, not really in the Knuth sense) written in Haskell, arguably the "most functional language". Most of the chapters conclude with the entire source of the program under discussion. I challenge you to pick any one of those chapters and look just at the final program, then try to figure out how and why it works. Good luck! There is a reason why academic computer science journals are not just books of raw source code. Innovative code and complex code require explanation. I would argue that Clojure would not exist were it not for a long tradition of code-embedded-in-detailed-explanation. Clojure is founded on the use of cutting-edge functional data structures, and I would wager that Rich Hickey would likely not have understood these structures well enough to implement them so successfully had he not been able to read articles explaining their construction and why they work. So this notion that the world is trending away from literate programs just isn't true. We see them all the time in the form of articles and blog posts designed to elucidate, we see them all the time in the context of real-world large, complex systems designed to outlive the people who created them, and in the context of literate programs written to teach and influence a new generation of programmers. For example, did you know that the book/literate program "Physically Based Rendering" recently won a Scientific and Technical Academy Award? (Yes, that's right, a literate program won an Academy Award -- the "Hollywood movie" kind.) "Physically based rendering h
Re: Rethinking Literate Programming
> PS. Just to be clear, my purpose is neither to attack nor to defend LP, > just to get clear about exactly what it is, what its presuppositions are, > what its implications are, etc. I also do not want to get into defending LP yet again. But I do think you might have missed the key point by focusing on presentation rather than communication. > * Knuth's main early LP tool (WEB) was to a certain extent an attempt to > fix deficiencies in Pascal, as Knuth himself explicitly acknowledged. Some > aspects of Knuthian LP (KLP) may make sense for imperative languages with > side effects; since it's hard to reason about programs written in such > languages, added commentary is needed. But if you already know that > functions are side-effect free and data are immutable, you no longer need > that. Having worked in string-free Pascal, the only real way to "fix it" would be to take it outside and burn it. :-) > * Programming language design has not evolved in the direction of LP, as we > might have expected from some of Knuth's more grandiose pronouncements; > instead they have evolved in the direction of greater expressivity, which > obviates the need for many kinds of documentation. You can argue that LP > was a fine thing in its day, but the world has moved on. "The nature of functional programming is to build, Russian doll-style, functions that use functions that use functions etc. But without something like a literate style, your efforts are quickly lost in the details. You do stuff -- and unless you have a phenomenal memory, you've simply dug a nice, deep tunnel that is, at the same time, collapsing behind you. YOU may know what you've done, but how to make others aware and get them involved? All they see is some collapsed tunnel with a sales pitch about how you should go re-dig that very same tunnel." -- Lawrence Bottorff, February 2014 > * KLP is largely based on the personal aesthetic and psychological > preferences of DE Knuth involving issues such as the proper order and mode > of presentation of code. Those are normative issues, and there is no > reason to take Knuth's preferences as gospel. In particular there is no > justification for his claim that using LP "methods" leads to "better" > code. It not only depends on what "better" means, it depends on what other > methods are available. Just because writing Pascal in LP was better (for > Knuth et al.) than writing plain Pascal does not mean this will always be > the case in all languages. It doesn't generalize. (To a hammer, > everything looks like a goto.) While the "proper order and mode of presentation" is a matter of personal preference it is not really germaine to the problem. When code is written and decorated with comments about what it does we feel we have communicated the important part. The problem is that we missed the "why". Sure, we have immutable, log32, red-black trees (ILRB trees). Yes, we documented what the arguments mean. But you'll notice that nowhere in the github tree is there any answer to "why?". A "literate programming style" isn't really the issue. The loss of "why?" is the issue. Answering "why?" means that you have to build up the background problem so people can understand "why?" the code is a solution. In other words, you need to communicate the ideas in some linear fashion so they have a common background understanding. > * There is (demonstrably) no reason to think that there is any "natural" or > "best" order of presentation for code; there are only preferences, and > everybody has one, if you catch my drift. The point again being that Knuth > was not on to some kind of laws of programming. KLP is all about his > preferred style, not about the Way Things Are. As an author I agree that there is no "natural" or "best" order of presentation. But there are clear preferences. Pick up any "book" which is a collection of conference papers and you can see that presentation choice is vital. Random, unorganized piles of ideas is not communication. The real focus of literate programming is actually about communication from one person to another. "Ideas" are missing from "The Way Things Are". At best we document what something does but not why we want to use it. If you look at the mailing list, a lot of the answers are of the form "this is why you should write it this way". Rich has been pretty good about communicating his ideas and his videos can be found on the web, assuming you know where to look and what you are looking for. Which video would I watch to get the ILRB tree concept? Which one would I watch to get the ideas behind "conj vs cons"
Re: Rethinking Literate Programming
> For example, did you know that > the book/literate program "Physically Based Rendering" recently won a > Scientific and Technical Academy Award? (Yes, that's right, a literate > program won an Academy Award -- the "Hollywood movie" kind.) An awesome book, by the way. I WISH I could write such a literate program. Like "Lisp in Small Pieces", they wrote a masterpiece. I hope it shows the next generation of programmers what beautifully written programs look like. Tim -- 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 --- You received this message because you are subscribed to the Google Groups "Clojure" group. To unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
Re: Rethinking Literate Programming
On Thu, May 8, 2014 at 11:02 AM, Mark Engelberg wrote: > In fact, Clojure has a number of features that actively hurt its > expressiveness relative to other modern languages: > BTW, that list was by no means exhaustive. In the past couple of hours I've thought of a couple more, I'm sure others could easily add to the list: 7. Use of infix notation means that math formulas look dramatically different in Clojure than in math form, and therefore, it is difficult to determine at a glance whether a formula as implemented in Clojure matches. 8. Arrays in many domains are more naturally expressed as 1-based, but in Clojure, they are 0-based. I've encountered a lot of code that was confusing because of lots of increments/decrements to shift back and forth between the problem as specified with 1-based implementation and the 0-based implementation imposed by Clojure. Lots of opportunities for off-by-one errors and/or later confusion when other readers try to make sense out of the code. 9. Clojure's ease of functional composition can result in deeply nested calls that are far easier to write than they are to read. 10. Unlike most other languages, every time you give names to local variables with let, you add a level of indentation. Especially with alternations of let and if/cond, you can easily end up with "rightward drift" that makes code harder to read. These are things we learn to live with. If these were show-stoppers, I'd be using another language, but they are not, so on balance I prefer Clojure with its other many strengths. My only point is that by no means is Clojure a pinnacle of expressiveness where all code is miraculously obvious. -- 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 --- You received this message because you are subscribed to the Google Groups "Clojure" group. To unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
Re: Rethinking Literate Programming
Guys, you really are into the Literate part, those emails are huge! let me catch up and then I'll reply... Interesting discussion! On Thu, May 8, 2014 at 4:59 PM, Mark Engelberg wrote: > On Thu, May 8, 2014 at 11:02 AM, Mark Engelberg > wrote: > >> In fact, Clojure has a number of features that actively hurt its >> expressiveness relative to other modern languages: >> > > BTW, that list was by no means exhaustive. In the past couple of hours > I've thought of a couple more, I'm sure others could easily add to the list: > > 7. Use of infix notation means that math formulas look dramatically > different in Clojure than in math form, and therefore, it is difficult to > determine at a glance whether a formula as implemented in Clojure matches. > 8. Arrays in many domains are more naturally expressed as 1-based, but in > Clojure, they are 0-based. I've encountered a lot of code that was > confusing because of lots of increments/decrements to shift back and forth > between the problem as specified with 1-based implementation and the > 0-based implementation imposed by Clojure. Lots of opportunities for > off-by-one errors and/or later confusion when other readers try to make > sense out of the code. > 9. Clojure's ease of functional composition can result in deeply nested > calls that are far easier to write than they are to read. > 10. Unlike most other languages, every time you give names to local > variables with let, you add a level of indentation. Especially with > alternations of let and if/cond, you can easily end up with "rightward > drift" that makes code harder to read. > > These are things we learn to live with. If these were show-stoppers, I'd > be using another language, but they are not, so on balance I prefer Clojure > with its other many strengths. My only point is that by no means is > Clojure a pinnacle of expressiveness where all code is miraculously obvious. > > -- > 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 > --- > You received this message because you are subscribed to the Google Groups > "Clojure" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to clojure+unsubscr...@googlegroups.com. > For more options, visit https://groups.google.com/d/optout. > -- 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 --- You received this message because you are subscribed to the Google Groups "Clojure" group. To unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
Re: Rethinking Literate Programming
In the past I've used a java tool to write "acceptance tests". Concordion [ http://concordion.org/]. The idea is simple yet effective. You write your documentation in HTML, and later you can run your code that will interact with that documentation and generate a new documentation, marking the portions of the text that are implemented and right (in green) vs the portion that's not yet implemented or failed (in red). This was an excellent communication tool. We can design the documentation in a way that the information flows and anyone could understand. I think the idea could be used in Clojure also, actually I was thinking about this for a while, it shouldn't be hard to use from clojure, it's a Java tool in the end. After reading this discussion I was wondering if a tool like this could be use to do LP, if not, I would like to know why. Thanks! On Fri, May 9, 2014 at 8:59 AM, Erlis Vidal wrote: > Guys, you really are into the Literate part, those emails are huge! let me > catch up and then I'll reply... > > Interesting discussion! > > > On Thu, May 8, 2014 at 4:59 PM, Mark Engelberg > wrote: > >> On Thu, May 8, 2014 at 11:02 AM, Mark Engelberg > > wrote: >> >>> In fact, Clojure has a number of features that actively hurt its >>> expressiveness relative to other modern languages: >>> >> >> BTW, that list was by no means exhaustive. In the past couple of hours >> I've thought of a couple more, I'm sure others could easily add to the list: >> >> 7. Use of infix notation means that math formulas look dramatically >> different in Clojure than in math form, and therefore, it is difficult to >> determine at a glance whether a formula as implemented in Clojure matches. >> 8. Arrays in many domains are more naturally expressed as 1-based, but in >> Clojure, they are 0-based. I've encountered a lot of code that was >> confusing because of lots of increments/decrements to shift back and forth >> between the problem as specified with 1-based implementation and the >> 0-based implementation imposed by Clojure. Lots of opportunities for >> off-by-one errors and/or later confusion when other readers try to make >> sense out of the code. >> 9. Clojure's ease of functional composition can result in deeply nested >> calls that are far easier to write than they are to read. >> 10. Unlike most other languages, every time you give names to local >> variables with let, you add a level of indentation. Especially with >> alternations of let and if/cond, you can easily end up with "rightward >> drift" that makes code harder to read. >> >> These are things we learn to live with. If these were show-stoppers, I'd >> be using another language, but they are not, so on balance I prefer Clojure >> with its other many strengths. My only point is that by no means is >> Clojure a pinnacle of expressiveness where all code is miraculously obvious. >> >> -- >> 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 >> --- >> You received this message because you are subscribed to the Google Groups >> "Clojure" group. >> To unsubscribe from this group and stop receiving emails from it, send an >> email to clojure+unsubscr...@googlegroups.com. >> For more options, visit https://groups.google.com/d/optout. >> > > -- 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 --- You received this message because you are subscribed to the Google Groups "Clojure" group. To unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
Re: Rethinking Literate Programming
On Fri, May 9, 2014 at 8:33 AM, Erlis Vidal wrote: > In the past I've used a java tool to write "acceptance tests". Concordion [ > http://concordion.org/]. The idea is simple yet effective. You write your > documentation in HTML, and later you can run your code that will interact > with that documentation and generate a new documentation, marking the > portions of the text that are implemented and right (in green) vs the > portion that's not yet implemented or failed (in red). > > This was an excellent communication tool. We can design the documentation > in a way that the information flows and anyone could understand. I think > the idea could be used in Clojure also, actually I was thinking about this > for a while, it shouldn't be hard to use from clojure, it's a Java tool in > the end. > > After reading this discussion I was wondering if a tool like this could be > use to do LP, if not, I would like to know why. > Hi Erlis, That looks like an excellent tool, thanks for bringing it up! Years ago, when I first started dinking around with LP, I wanted to get the good documentation of LP but without mixing code and documentation in one file and without reordering; in other words, a way to reliably attach documentation to code from the outside, keep it up to date, etc. Something akin to the way XSLT relates to XML source docs. I think something like that is doable, but it's complicated and my initial enthusiasm eventually petered out. But it never occurred to me to use tests in this way. It looks like a great way to document APIs (internal and external), and I no reason why it wouldn't work just fine for Clojure. If not Concordion, it probably would not be too tremendously difficult to add similar capabilities to one of the pure Clojure unit test frameworks. One thing I might change (having spent no more that a few minutes looking at Concordion) would be to write Condordion specs in XML instead of HTML. That would make it easier to repurpose the output to PDF, Eclipse helpfiles, Windows helpfiles, etc. (see http://dita-ot.github.io/1.8/readme/AvailableTransforms.html for a list of output formats in active use by tech documentation specialists). In fact, now I think of it, it looks like Concordion specification would be a good candidate for a DITA specialization. Personally I would not call this LP, just to avoid confusion. Knuth's original notion of LP pretty clearly means, among other things, code and documentation in the same LP source text, and free ordering. Most other LP systems that I've looked at follow those norms, so calling something like Concordian an LP tool would likely lead to gnashing of teeth, not to mention theological debates about True LP. I'm not sure what I would call it, other than a documentation tool. Maybe live documentation? Integrated external documentation? Test-based documentation? Thanks, Gregg -Gregg -- 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 --- You received this message because you are subscribed to the Google Groups "Clojure" group. To unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
Re: Rethinking Literate Programming
I've always seen this to document what the system does, as a way to gather requirements. And the name used is similar to what you propose. Live Specification or Specification by Example among other names. It never occurred to me that this could be used for API documentation, and I'm a completely n00b to LP, that's why I asked if we could use something like that. I see that the definition of LP involve the word "programming" so basically we have to bind the code with the "literate" part. Maybe concordion could be a interesting idea to present in the discussion we have around a new way of documentation for Clojure. It's nice what you can do with it. We can even use it to document how the future version of the language is progressing, we can go to the "live" page and see what's done and what's pending. I'll see if I find some time to create something in clojure that's documented using concordion. Anyway, thanks for the answer and keep up the great work, everyone! On Fri, May 9, 2014 at 10:17 AM, Gregg Reynolds wrote: > On Fri, May 9, 2014 at 8:33 AM, Erlis Vidal wrote: > >> In the past I've used a java tool to write "acceptance tests". Concordion >> [http://concordion.org/]. The idea is simple yet effective. You write >> your documentation in HTML, and later you can run your code that will >> interact with that documentation and generate a new documentation, marking >> the portions of the text that are implemented and right (in green) vs the >> portion that's not yet implemented or failed (in red). >> >> This was an excellent communication tool. We can design the documentation >> in a way that the information flows and anyone could understand. I think >> the idea could be used in Clojure also, actually I was thinking about this >> for a while, it shouldn't be hard to use from clojure, it's a Java tool in >> the end. >> >> After reading this discussion I was wondering if a tool like this could >> be use to do LP, if not, I would like to know why. >> > > Hi Erlis, > > That looks like an excellent tool, thanks for bringing it up! Years ago, > when I first started dinking around with LP, I wanted to get the good > documentation of LP but without mixing code and documentation in one file > and without reordering; in other words, a way to reliably attach > documentation to code from the outside, keep it up to date, etc. Something > akin to the way XSLT relates to XML source docs. I think something like > that is doable, but it's complicated and my initial enthusiasm eventually > petered out. But it never occurred to me to use tests in this way. It > looks like a great way to document APIs (internal and external), and I no > reason why it wouldn't work just fine for Clojure. If not Concordion, it > probably would not be too tremendously difficult to add similar > capabilities to one of the pure Clojure unit test frameworks. > > One thing I might change (having spent no more that a few minutes looking > at Concordion) would be to write Condordion specs in XML instead of HTML. > That would make it easier to repurpose the output to PDF, Eclipse > helpfiles, Windows helpfiles, etc. (see > http://dita-ot.github.io/1.8/readme/AvailableTransforms.html for a list > of output formats in active use by tech documentation specialists). In > fact, now I think of it, it looks like Concordion specification would be a > good candidate for a DITA specialization. > > Personally I would not call this LP, just to avoid confusion. Knuth's > original notion of LP pretty clearly means, among other things, code and > documentation in the same LP source text, and free ordering. Most other LP > systems that I've looked at follow those norms, so calling something like > Concordian an LP tool would likely lead to gnashing of teeth, not to > mention theological debates about True LP. I'm not sure what I would call > it, other than a documentation tool. Maybe live documentation? Integrated > external documentation? Test-based documentation? > > Thanks, > > Gregg > > -Gregg > > -- > 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 > --- > You received this message because you are subscribed to the Google Groups > "Clojure" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to clojure+unsubscr...@googlegroups.com. > For more options, visit https://groups.google.com/d/optout. > -- 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
Re: Rethinking Literate Programming
puzzler and Tim, Well said, gentlemen. As someone who has been using LP heavily for the past two years, I have certainly reaped many if not most of the benefits regularly argued in its favor (and of course, I've wrestled with all the usual tooling issues as well). While I agree with puzzler that many programmers probably don't write sufficiently novel software that would benefit from an LP style, quite a few of us do. In my case, much of my programming is aimed at environmental research, developing models and algorithms for describing and predicting natural processes and human interactions with them. In order for my work to be accepted and used for decision making (usually around land planning), it is absolutely crucial that I can transparently explain all the formulas used, literature cited, and conceptual steps taken to get from empirically measured data to modelled outputs. A literate programming style not only helps me to organize my thoughts better (both hierarchically and sequentially), but it provides me with a living (tangled) document that I can share with my non-programmer colleagues to get their domain-specific feedback about my choice of model assumptions, formulas, etc. This enables a level of collaboration that I simply could not achieve if I simply wrote the code directly. Finally, as a thoroughly unexpected side effect, some of my most complicated programs actually became much, much shorter when I rewrote them in an LP style (in terms of lines of code, of course). Part of this had to do with the available tooling (Org-mode's polyglot literate programming and reproducible research facilities are outstanding) and part of it simply came from having to write down my ideas in English first. This kept me from rushing into writing code and possibly getting lost in those "collapsing tunnels" to which Tim alluded. Instead, the additional "hammock time" that I took to think my way through how to present my solutions frequently led to "Aha!" moments in which I realized a simpler way to express the problem. Cliche, I know, but still results are results. Get Literate! (use only as necessary; LP may not be recommended for some patients due to increased blood pressure and carpal tunnel risk) ~Gary On Thursday, May 8, 2014 8:57:51 AM UTC-4, Gregg Reynolds wrote: > > The thread on documentation that Val started ( > https://groups.google.com/forum/?hl=en#!topic/clojure/oh_bWL9_jI0) is > getting a little long so I'm starting a related one specific to litprog. > > I've made a start on rethinking LP at > https://github.com/mobileink/codegenres/wiki/Rethinking-Literate-Programming > . > > A few key points: > > * Knuth's main early LP tool (WEB) was to a certain extent an attempt to > fix deficiencies in Pascal, as Knuth himself explicitly acknowledged. Some > aspects of Knuthian LP (KLP) may make sense for imperative languages with > side effects; since it's hard to reason about programs written in such > languages, added commentary is needed. But if you already know that > functions are side-effect free and data are immutable, you no longer need > that. > * Programming language design has not evolved in the direction of LP, as > we might have expected from some of Knuth's more grandiose pronouncements; > instead they have evolved in the direction of greater expressivity, which > obviates the need for many kinds of documentation. You can argue that LP > was a fine thing in its day, but the world has moved on. > * KLP is largely based on the personal aesthetic and psychological > preferences of DE Knuth involving issues such as the proper order and mode > of presentation of code. Those are normative issues, and there is no > reason to take Knuth's preferences as gospel. In particular there is no > justification for his claim that using LP "methods" leads to "better" > code. It not only depends on what "better" means, it depends on what other > methods are available. Just because writing Pascal in LP was better (for > Knuth et al.) than writing plain Pascal does not mean this will always be > the case in all languages. It doesn't generalize. (To a hammer, > everything looks like a goto.) > * There is (demonstrably) no reason to think that there is any "natural" > or "best" order of presentation for code; there are only preferences, and > everybody has one, if you catch my drift. The point again being that Knuth > was not on to some kind of laws of programming. KLP is all about his > preferred style, not about the Way Things Are. > * KLP is sometimes contrasted with "self-documenting code" To get a grip > on what that is and what we can expect from it we need to examine the &g
Re: Rethinking Literate Programming
With respect to "documentation" of open source software... "You keep using that word. I don't think it means what you think it means." -- "The Princess Bride" The notion that "reading the code" is the ultimate truth for "documentation" is based on a misunderstanding at so many levels it is hard to explain. In fact, most of the ideas don't begin to cover "documenting the system". Fortunately, Robert Lefkowitz absolutely illuminates the scope of the problem in these delightful talks. For those who have not heard it, this is truly a treat. For those who "document" this is a must-hear. Robert Lefkowitz -- The Semasiology of Open Source http://web.archive.org/web/20130729214526id_/http://itc.conversationsnetwork.org/shows/detail169.html http://web.archive.org/web/20130729210039id_/http://itc.conversationsnetwork.org/shows/detail662.html 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 --- You received this message because you are subscribed to the Google Groups "Clojure" group. To unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
Re: Rethinking Literate Programming
I think we all know this, but just to make sure the point is clear (in some of the dicussion here, it doesn't seem that it is), the alternatives are not only: (a) Source code with docstrings (or fancy formatted docstrings with links, etc.) and sparse comments, but no other explanatory text anywhere. (b) Literate programming. Of course long chunks of text are needed to explain algorithms, motivation, paths not taken, etc. Literate programming requires that those chunks be inserted into the source file, and that you have to run the source file through a filter to get rid of them. Here's how I have been working lately: Early in the process of developing a section of code, I often insert long comments to explain what I'm doing or what I intend to do, etc. Like literate code, but with comment characters in front of it. Eventually, I look at the source file and think, "That long comment is cluttering up the code. I have to scroll down to often to see what's going on in the code." Then I put the long comment into a separate file, (perhaps a file that already contains some explanatory text), strip the comment characters, and maybe add some markdown or write some additional text. I leave some essential comments in the text, or put information into docstrings if it seems appropriate. The point is that these days, at least, I don't *want* a lot of text in the file that contains my source code, even though I think that explanatory documentation is *very* important, and even though I'd guess that I've written more of it per line of code than the average programmer. But that's me. Others find LP extremely beneficial, and I support that strategy for those who like it. (The desire to be able to see a lot of code at once is also one reason why C-style code formatting is undesirable in a lisp language.) -- 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 --- You received this message because you are subscribed to the Google Groups "Clojure" group. To unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
Re: Rethinking Literate Programming
> I think we all know this, but just to make sure the point is clear (in some > of the dicussion here, it doesn't seem that it is), the alternatives are > not only: > > (a) Source code with docstrings (or fancy formatted docstrings with links, > etc.) and sparse comments, but no other explanatory text anywhere. > > (b) Literate programming. Actually, lisp has a long tradition of semicolon-style comments where Chapter ;;; Section ;; Subsection ;Paragraph or inline With some Emacs hacking it would be possible to fold/unfold these comments. I worked on a Transputer editor that had fold/unfold and it was reasonably useful. I believe Emacs org-mode can also hide comments on command. Michael Fogus (The Joy of Clojure) is a better org-mode resource. John Kitchin (CMU professor) shows org-mode in his talk: http://www.youtube.com/watch?v=1-dUkyn_fZA I'm a "software blacksmith" and tend to create my own tools from scratch so I can't give advice on org-mode, IDEs or other "store-bought" solutions. :-) > Of course long chunks of text are needed to explain algorithms, motivation, > paths not taken, etc. Literate programming requires that those chunks be > inserted into the source file, and that you have to run the source file > through a filter to get rid of them. > ...[snip]... > > The point is that these days, at least, I don't *want* a lot of text in the > file that contains my source code, even though I think that explanatory > documentation is *very* important, and even though I'd guess that I've > written more of it per line of code than the average programmer. But > that's me. Others find LP extremely beneficial, and I support that > strategy for those who like it. > > (The desire to be able to see a lot of code at once is also one reason why > C-style code formatting is undesirable in a lisp language.) I used comment-style documentation method in my youth. I created a language, called KROPS, which was the implementation language for a large expert system. It was pure lisp on a Symbolics machine so there were no other documentation tools. This limited the style of comments to the conventions mentioned above. Returning to the code many years later (which is where LP really pays off) the comments were extremely helpful but not sufficient. KROPS uses a circular, self-modifying data structure which prints as a single, solid block of code. Documenting and diagraming this structure is necessary to understand it. ASCII tools are not sufficient for the diagrams but the current tools are. The code sat in long non-comment stretches. The comments that did exist tended to follow the semicolon style mentioned above. Overall the code follows a book-like convention but used pure source code. Snippets are attached below to show the style. Things to note are * The use of #|..|# (Common Lisp has 2 comment delimiter styles) * Higher organization of the comments - an intro to check that it works - a table of contents - the use of "levels" of semicolon structure - the use of docstrings on functions - the use of UPPERCASE in docstrings to highlight symbol names - the use of inline semicolons Not shown are long uninterrupted stretches of code containing only the docstring/uppercase and a few "inline" comments. So it is possible to do some form of reasonably well documented programming that is somewhat structured, involving only some discipline on commenting style. #| ;; KROPS in common lisp ;; ;; Trivial test: ;; ;; initialize the system: ;;(PS-INITIALIZE) ;; ;; define the class TEST: ;;(LITERALIZE TEST A=) ;; ;; create one rule: ;;(P ASDF WHEN (TEST A= 1) THEN (PRINT "IT WORKS")) ;; ;; create one working memory element: ;;(MAKE TEST A= 1) ;; ;; look for the rule to fire: ;;(CS) ==> NIL.ASDF ;; ;; run one rule: ;;(RUN) ==> "IT WORKS" ;; ; STRUCTURE OF THIS FILE: ; 1.0 PACKAGE INFORMATION ; 2.0 VERSION VARIABLE ; 3.0 CHANGE LIST ; 4.0 IMPLEMENTATION PATCHES ; 5.0 DATA STRUCTURE DOCUMENTATION ; 5.1 RETE DATA STRUCTURES ; 5.1.1 R-NODE ; 5.1.2 NODES IN THE ALPHA RETE ;5.1.2.1 R-A-PLAIN ;5.1.2.2 R-A-OR ;5.1.2.3 R-A-TRIG ;5.1.2.4 R-B-A-DISTR ; 5.1.3 NODES IN THE BETA RETE ;5.1.3.1 R-B-JOIN ;5.1.3.2 R-B-SORT (sorted memory node) ;5.1.3.3 R-B-P (PRODUCTION) NODES ; 5.1.4 OTHER DATA STRUCTURES ;5.1.4.1 R-CS (A conflict set element) ;5.1.4.2 R-B-COMMON (the vector portion of an R-B-JOIN node) ;5.1.4.3 R-B-P-C (the vector portion of an R-B-P node) ;5.1.4.4 R-B-ACC (an access vector) ; 5.1.5 MEMORIES ;5.1.5.1 R-MEM (Rplacdable memory header) ;5.1.5.2 R-MEM-ITEM (an element of R-MEM) ;5.1.5.3 R-MEM-SORT (sorted memory)
Re: Rethinking Literate Programming
Emacs org-mode provides a markdown-like language, which can be organized into a foldable outline (e.g., chapters, sections, subsections, subsubsections). Syntax is provided for headers, ordered/unordered lists, tables, inline images/figures, hyperlinks, footnotes, and (most importantly for LP) code blocks. In order to avoid having to scroll up and down forever to see your code spread through the document, you simply use TAB to fold/unfold the outline sections your are currently interested in. Pressing C-c ' within any code block automatically switches to Emacs' major mode for that language, showing only the code in its own temporary buffer. When you want to see all of your code at once, just tangle the document to a *.clj file and look at it in another buffer. Using auto-refresh on the tangled buffer provides an easy way to keep checking code changes in this way with minimal effort. When you are ready to weave the document into a nicely readable format, org-mode provides output filters to auto-generate latex articles, html webpages, OpenDocument files, latex beamer presentations, and quite a few others as well. This is just meant to clarify some of the LP-related features of this platform. Obviously, some emacs lisp hacking can extend it to do whatever else people want. -- 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 --- You received this message because you are subscribed to the Google Groups "Clojure" group. To unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
Re: Literate Programming example
On Nov 18, 2011, at 7:17 AM, daly wrote: > http://daly.literatesoftware.com/lithtml/litprog.html FYI, this is 404 at the moment. - Chas -- 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
Re: Literate Programming example
sigh. Try http://daly.axiom-developer.org/lithtml/litprog.html On Fri, 2011-11-18 at 07:46 -0500, Chas Emerick wrote: > On Nov 18, 2011, at 7:17 AM, daly wrote: > > > http://daly.literatesoftware.com/lithtml/litprog.html > > FYI, this is 404 at the moment. > > - Chas > -- 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
Re: Literate Programming example
I believe I fixed it. Please try it again and let me know. Tim On Fri, 2011-11-18 at 07:46 -0500, Chas Emerick wrote: > On Nov 18, 2011, at 7:17 AM, daly wrote: > > > http://daly.literatesoftware.com/lithtml/litprog.html > > FYI, this is 404 at the moment. > > - Chas > -- 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
Re: Literate Programming example
it works for me. Las 2011/11/18 daly > I believe I fixed it. > Please try it again and let me know. > > Tim > > On Fri, 2011-11-18 at 07:46 -0500, Chas Emerick wrote: > > On Nov 18, 2011, at 7:17 AM, daly wrote: > > > > > http://daly.literatesoftware.com/lithtml/litprog.html > > > > FYI, this is 404 at the moment. > > > > - Chas > > > > > -- > 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 > -- László Török Skype: laczoka2000 Twitter: @laczoka -- 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
Re: Literate Programming example
On Nov 18, 1:17 pm, daly wrote: > Many of you asked me to show an example of a literate > program and demonstrate the use of the tangle function. Thanks to your perseverance, I am looking into practicing literate programming. However, I decided to settle for emacs org-mode environment with the literate elisp for the relevant code (abel'part of org-mode) being here : http://eschulte.github.com/org-babel/org-babel.org.html I found an example of clojure project (research on genetic programming) written in literate programming using babel org-mode for emacs is hosted here : http://gitweb.adaptive.cs.unm.edu/asm.git/tree I do hope that others find those resources as useful as I found them. Best Regards, Bernard -- 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
Re: Literate Programming example
On Fri, 2011-11-18 at 07:07 -0800, bernardH wrote: > > On Nov 18, 1:17 pm, daly wrote: > > Many of you asked me to show an example of a literate > > program and demonstrate the use of the tangle function. > > Thanks to your perseverance, I am looking into practicing literate > programming. > > However, I decided to settle for emacs org-mode environment with the > literate elisp for the relevant code (abel'part of org-mode) > being here : http://eschulte.github.com/org-babel/org-babel.org.html > I found an example of clojure project (research on genetic > programming) written in literate programming using babel org-mode for > emacs > is hosted here : > http://gitweb.adaptive.cs.unm.edu/asm.git/tree > > I do hope that others find those resources as useful as I found them. I have nothing against org-mode. Indeed, I've been an emacs user since I could spell it. I believe the above examples are not literate programmings. They miss the point completely. They are using emacs org-mode for DOCUMENTATION. Literate programming is NOT documentation. It is a way to communicate from one person to another by starting from ideas and reducing them to practice. I may have missed the point but the above programs are just fancier ways of 1970 style coding using a new format tool. Compare the example I gave at http://axiom-developer.org/axiom-website/litprog.html with the above programs. See if you can spot a qualitative difference. My literate program tries to motivate the need for tangle, to explain why it works in a development context, and then gets down to details of implementation. It is a story. Where does this happen in the org-mode example? Perhaps I missed something but the author does not seem to be concentrating on communicating their ideas to me. Where did I go wrong? What emacs keystrokes get me a copy of the full document to read? Literate programming is about communication, not documentation. The org-mode tool is perfectly fine but be very, very careful not to miss this fundamental point. People should be able to just pick up clojure-core and read it like a novel, from ideas to implementation, and be able to understand it enough to change it. If your code can pass this "independence test" then your code is literate. Tim -- 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
Re: Literate Programming example
On Friday, November 18, 2011 7:17:08 AM UTC-5, TimDaly wrote: > > Many of you asked me to show an example of a literate > program and demonstrate the use of the tangle function. > > I usually use Latex for literate work but I've done > this example using HTML and tags. > > I've written a self-referential literate program that > explains the details of the tangle function in literate > form. You can find the web page at > > http://daly.literatesoftware.com/lithtml/litprog.html > I have read your literate program, and must recognize that I know how tangle works even though I didn't want to really read the source code. I read your prose all the way through. I still haven't read the source code; I didn't feel the need to read it. Were I to maintain your program, I'd have more than enough confidence to start hacking the code right now. I think this speaks very positively about literate programming. What remains to be seen is how much (or not) I'm going to practice it in the future. What do you think of marginalia? It's a bit the reverse of tangle; it assembles all those 70's files together into this book you might want to read. Is it sound or not? Have your thoughts changed from what you wrote in [1]? [1] http://goo.gl/cXWzF -- 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
Re: Literate Programming example
On Fri, 2011-11-18 at 20:02 -0800, Daniel Jomphe wrote: > On Friday, November 18, 2011 7:17:08 AM UTC-5, TimDaly wrote: > Many of you asked me to show an example of a literate > program and demonstrate the use of the tangle function. > > I usually use Latex for literate work but I've done > this example using HTML and tags. > > I've written a self-referential literate program that > explains the details of the tangle function in literate > form. You can find the web page at > > http://daly.literatesoftware.com/lithtml/litprog.html > > I have read your literate program, and must recognize that I know how > tangle works even though I didn't want to really read the source code. > I read your prose all the way through. I still haven't read the source > code; In fact, that's the whole point. You don't read the equations in a calculus textbook either. You read the words. The equations are icons. If you understood the text and "spoke" mathematics you could probably write the equations. In programming we can reach the same level of literacy. Reading just the words in the literate version it should be possible to recreate the program in your favorite language. Note that you would be creating a different program with different design decisions but the same functionality. > I didn't feel the need to read it. Were I to maintain your program, > I'd have more than enough confidence to start hacking the code right > now. One thing worth trying would be to code the same program in Clojure. The tangle program is conceptually very simple but there are a lot of low level design decisions that I would make differently. For example, there are loops in the C program which would go away. Would you map read or would you slurp? Mapping a read function allows transforming "& lt;" to < at read time. This does not matter in the C program because the buffer is mutable but it would matter in Clojure. Would you use the Clojure pattern language to find the tags? Would you be able to parse out the string from the id? C encourages character-level hacking but Clojure would be much more powerful. > > > I think this speaks very positively about literate programming. What > remains to be seen is how much (or not) I'm going to practice it in > the future. If you do try to rewrite it in Clojure please post the program. I would be very interested to see how Clojure's concise syntax and semantics get reflected in your design decisions. The tangle program in Clojure might turn out to be a single s-expression of only a few lines. The code density would be a huge win but a literate version would still have to have the vitals of the story. Remember that the key test for a literate program is the "independence test". Someone can read it without talking to you, understand how it works, and be able to change it. > > > What do you think of marginalia? It's a bit the reverse of tangle; it > assembles all those 70's files together into this book you might want > to read. Is it sound or not? Have your thoughts changed from what you > wrote in [1]? > > > [1] http://goo.gl/cXWzF Literate programming is a mindset, not a tool. You can write a literate program in anything, including marginalia. That said, I have yet to see a Clojure program that lays out a story so I can sit and read it. For a real challenge, if you try to write tangle in Clojure, try writing the story in marginalia. I'm sure Fogus would welcome the feedback. The readability aspect is a real feature. Heck, you could even give your programs to a company so they could read them BEFORE the job interview. I would strongly favor hiring someone who could communicate, who cared about code quality, and who could improve the company's maintenance headache in the long term. A Literate Clojure programmer would be a real gotta-hire person. Companies use many programming languages but all programmers really do need good communication skills. In the long view, it would be sweet if the Clojure reader knew how to read a literate program. Just call "(literate-load file chunk)" and you get the same effect as if you had tangled the program to a file. With literate-load available you would be able to write all of your Clojure code in a literate style, making Clojure much easier to understand, maintain, and modify. 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
Re: Literate Programming example
Hello, 2011/11/19 TimDaly > On Fri, 2011-11-18 at 20:02 -0800, Daniel Jomphe wrote: > > On Friday, November 18, 2011 7:17:08 AM UTC-5, TimDaly wrote: > > Many of you asked me to show an example of a literate > > program and demonstrate the use of the tangle function. > > > > I usually use Latex for literate work but I've done > > this example using HTML and tags. > > > > I've written a self-referential literate program that > > explains the details of the tangle function in literate > > form. You can find the web page at > > > > http://daly.literatesoftware.com/lithtml/litprog.html > > > > I have read your literate program, and must recognize that I know how > > tangle works even though I didn't want to really read the source code. > > I read your prose all the way through. I still haven't read the source > > code; > > In fact, that's the whole point. You don't read the equations in a > calculus textbook either. You read the words. The equations are icons. > If you understood the text and "spoke" mathematics you could probably > write the equations. > > In programming we can reach the same level of literacy. Reading just > the words in the literate version it should be possible to recreate > the program in your favorite language. Note that you would be creating > a different program with different design decisions but the same > functionality. > > > I didn't feel the need to read it. Were I to maintain your program, > > I'd have more than enough confidence to start hacking the code right > > now. > > One thing worth trying would be to code the same program in Clojure. > > The tangle program is conceptually very simple but there are a lot > of low level design decisions that I would make differently. For > example, there are loops in the C program which would go away. > > Would you map read or would you slurp? Mapping a read function allows > transforming "& lt;" to < at read time. This does not matter in the C > program because the buffer is mutable but it would matter in Clojure. > > Would you use the Clojure pattern language to find the tags? > Would you be able to parse out the string from the id? C encourages > character-level hacking but Clojure would be much more powerful. > > > > > > > I think this speaks very positively about literate programming. What > > remains to be seen is how much (or not) I'm going to practice it in > > the future. > > If you do try to rewrite it in Clojure please post the program. I > would be very interested to see how Clojure's concise syntax and > semantics get reflected in your design decisions. > > The tangle program in Clojure might turn out to be a single > s-expression of only a few lines. The code density would be a > huge win but a literate version would still have to have the > vitals of the story. Remember that the key test for a literate > program is the "independence test". Someone can read it without > talking to you, understand how it works, and be able to change it. > > > > > > > What do you think of marginalia? It's a bit the reverse of tangle; it > > assembles all those 70's files together into this book you might want > > to read. Is it sound or not? Have your thoughts changed from what you > > wrote in [1]? > > > > > > [1] http://goo.gl/cXWzF > > Literate programming is a mindset, not a tool. You can write a > literate program in anything, including marginalia. > > That said, I have yet to see a Clojure program that lays out a story > so I can sit and read it. For a real challenge, if you try to write > tangle in Clojure, try writing the story in marginalia. I'm sure > Fogus would welcome the feedback. > > > The readability aspect is a real feature. Heck, you could even give > your programs to a company so they could read them BEFORE the job > interview. I would strongly favor hiring someone who could > communicate, who cared about code quality, and who could improve > the company's maintenance headache in the long term. A Literate > Clojure programmer would be a real gotta-hire person. Companies > use many programming languages but all programmers really do need > good communication skills. > > > In the long view, it would be sweet if the Clojure reader knew how > to read a literate program. Just call "(literate-load file chunk)" > and you get the same effect as if you had tangled the program to > a file. > > With literate-load available you would be able to write all
Re: Literate Programming example
On Sat, 2011-11-19 at 14:35 +0100, Laurent PETIT wrote: > Hello, > > 2011/11/19 TimDaly > On Fri, 2011-11-18 at 20:02 -0800, Daniel Jomphe wrote: > > On Friday, November 18, 2011 7:17:08 AM UTC-5, TimDaly > wrote: > > Many of you asked me to show an example of a > literate > > program and demonstrate the use of the tangle > function. > > > > I usually use Latex for literate work but I've done > > this example using HTML and tags. > > > > I've written a self-referential literate program > that > > explains the details of the tangle function in > literate > > form. You can find the web page at > > > > > http://daly.literatesoftware.com/lithtml/litprog.html > > > > I have read your literate program, and must recognize that I > know how > > tangle works even though I didn't want to really read the > source code. > > I read your prose all the way through. I still haven't read > the source > > code; > > > In fact, that's the whole point. You don't read the equations > in a > calculus textbook either. You read the words. The equations > are icons. > If you understood the text and "spoke" mathematics you could > probably > write the equations. > > In programming we can reach the same level of literacy. > Reading just > the words in the literate version it should be possible to > recreate > the program in your favorite language. Note that you would be > creating > a different program with different design decisions but the > same > functionality. > > > I didn't feel the need to read it. Were I to maintain your > program, > > I'd have more than enough confidence to start hacking the > code right > > now. > > > One thing worth trying would be to code the same program in > Clojure. > > The tangle program is conceptually very simple but there are a > lot > of low level design decisions that I would make differently. > For > example, there are loops in the C program which would go away. > > Would you map read or would you slurp? Mapping a read function > allows > transforming "& lt;" to < at read time. This does not matter > in the C > program because the buffer is mutable but it would matter in > Clojure. > > Would you use the Clojure pattern language to find the > tags? > Would you be able to parse out the string from the id? C > encourages > character-level hacking but Clojure would be much more > powerful. > > > > > > > I think this speaks very positively about literate > programming. What > > remains to be seen is how much (or not) I'm going to > practice it in > > the future. > > > If you do try to rewrite it in Clojure please post the > program. I > would be very interested to see how Clojure's concise syntax > and > semantics get reflected in your design decisions. > > The tangle program in Clojure might turn out to be a single > s-expression of only a few lines. The code density would be a > huge win but a literate version would still have to have the > vitals of the story. Remember that the key test for a literate > program is the "independence test". Someone can read it > without > talking to you, understand how it works, and be able to change > it. > > > > > > > What do you think of marginalia? It's a bit the reverse of > tangle; it > > assembles all those 70's files together into this book you > might want > > to read. Is it sound or not? Have your thoughts changed from > what you > > wrote in [1]? > > > > > > [1] http://goo.gl/cXWzF > > > Literate programming is a mindset,
Re: Literate Programming example
On Saturday, November 19, 2011 2:37:48 PM UTC-5, TimDaly wrote: > > However, as Knuth points out and as I've already experienced, writing > a program in literate form vastly reduces the errors. There are two > causes I can find. > > First, if I have to write an explanation then I have to justify my > poor code hacks. Sometimes I find that I rewrite the code because the > very act of explaining the bad code made me realize that the code is > bad. I find I have to talk about memory allocations so I catch leaks. > I have to talk about argument handling so I end up proving that the > arguments are correct, or I end up checking for possible failures. > > Second, because other people can see the reasoning at the code review, > they can chastise me for failing to explain, or explaining things that > the code does not do, or just plain failing to implement a correct > solution. > With the tools available to us today, there's no reason why we at least shouldn't have everything needed to make literate programming more seamless, more natural. For example, while reading your toy example, I found myself wanting to ask a question or comment on your thoughts a few times. If your book had been displayed on a dynamic website geared towards literate programming, I might have been able to click on a paragraph and write my question/comment right there. And then, after a short conversation there, you would have integrated the fruits of our conversation directly into the end result. Thus each new reader would have been an occasion to improve the book. ...It's nothing surprising since this kind of review system already exists in some publishers' toolkits. Another thing that appeals to me regarding Tangle, is the fact that it may be used to keep things DRY. For example, when we have many arity-overloaded implementations of a function, some of their arguments are repeated, and we need to duplicate their api docs. Tangle could be leveraged to get rid of this duplication. -- 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
Re: Literate Programming example
On 11/19/2011 10:21 PM, Daniel Jomphe wrote: With the tools available to us today, there's no reason why we at least shouldn't have everything needed to make literate programming more seamless, more natural. For example, while reading your toy example, I found myself wanting to ask a question or comment on your thoughts a few times. If your book had been displayed on a dynamic website geared towards literate programming, I might have been able to click on a paragraph and write my question/comment right there. And then, after a short conversation there, you would have integrated the fruits of our conversation directly into the end result. Thus each new reader would have been an occasion to improve the book. ...It's nothing surprising since this kind of review system already exists in some publishers' toolkits. Especially with support for discussions and iterations, such infrastructure could be used for design in general. I'm following one or the other Free Software project where an incredible amount of discussions happen regarding work-flow and features. So much thought, so many decisions on details, but for the most part, the implementation is all that remains. But the research, concepts and conscious decisions regarding trade-offs could actually outlive any implementation, they are portable and could be argued to be more valuable. So funny as it might sound, there's a need for literate design! -- Thorsten Wilms thorwil's design for free software: http://thorwil.wordpress.com/ -- 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
Re: Literate Programming example
FYI: some time ago the Opensuse project used such a collaborative tool (http://www.co-ment.com) in order to get a shared mindset of its goals. This was the result, see how clicking on higlight words points to their comments: https://lite.co-ment.com/text/lNPCgzeGHdV/view/ On Sat, Nov 19, 2011 at 10:21 PM, Daniel Jomphe wrote: > With the tools available to us today, there's no reason why we at least > shouldn't have everything needed to make literate programming more seamless, > more natural. For example, while reading your toy example, I found myself > wanting to ask a question or comment on your thoughts a few times. If your > book had been displayed on a dynamic website geared towards literate > programming, I might have been able to click on a paragraph and write my > question/comment right there. And then, after a short conversation there, > you would have integrated the fruits of our conversation directly into the > end result. Thus each new reader would have been an occasion to improve the > book. ...It's nothing surprising since this kind of review system already > exists in some publishers' toolkits. -- 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
Re: Literate Programming example
On Sunday, November 20, 2011 5:50:31 AM UTC-5, thorwil wrote: > > I'm following one or the other Free Software project where an incredible > amount of discussions happen regarding work-flow and features. So much > thought, so many decisions on details, but for the most part, the > implementation is all that remains. But the research, concepts and > conscious decisions regarding trade-offs could actually outlive any > implementation, they are portable and could be argued to be more valuable. > You raised my curiosity. Would you mind sharing a link? ;) -- 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
Re: Literate Programming example
On Sunday, November 20, 2011 6:17:13 AM UTC-5, robermann79 wrote: > > FYI: some time ago the Opensuse project used such a collaborative tool > (http://www.co-ment.com) in order to get a shared mindset of its > goals. > This was the result, see how clicking on higlight words points to > their comments: > https://lite.co-ment.com/text/lNPCgzeGHdV/view/ Interesting. And funny, considering I bought the cochapter.com domain to do something similar. I'm yet to deliver the application that's planned to power that domain. -- 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
Re: Literate Programming example
On 11/20/2011 11:18 PM, Daniel Jomphe wrote: On Sunday, November 20, 2011 5:50:31 AM UTC-5, thorwil wrote: I'm following one or the other Free Software project where an incredible amount of discussions happen regarding work-flow and features. So much thought, so many decisions on details, but for the most part, the implementation is all that remains. But the research, concepts and conscious decisions regarding trade-offs could actually outlive any implementation, they are portable and could be argued to be more valuable. You raised my curiosity. Would you mind sharing a link? ;) My prime example would be Ardour (ardour.org). Almost all the action happens on IRC, where the lead developer has many interactions with a few other coders and users, among them professional sound-engineers who provide critical insight into certain scenarios/work-flows and the features of related hard-and software. Starting to be off-topic, so this is as far as I will take it on this list ;) -- Thorsten Wilms thorwil's design for free software: http://thorwil.wordpress.com/ -- 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
Literate Programming in Emacs?
For those who do Literate Programming in Emacs, what do you use? I was looking at org-babel-clojure<http://orgmode.org/worg/org-contrib/babel/languages/ob-doc-clojure.html>which says: > You will need to install the following packages: clojure-mode, > swank-clojure, slime, slime-repl But when I list-packages, swank-clojure is not in the list... It also says I ought to be able to M-x slime ... but that results in "no such file or directory, lisp" -- 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
Heidegger, literate programming, and communication
The primary focus of a "documentation system" is communication from
the author to the audience.
One of the struggles apparent in discussing issues of communication,
especially with programmers, is Heideggers "present-at-hand" vs
"breaking down".
Programmers write programs to instruct a machine to perform some
task. In the ideal, this involves "communication" from the mind of
the programmer to the "execution of the program". If the program works
the first time it is all a seamless entity ("present-at-hand").
When the program fails, by compiler errors, missing libraries, runtime
errors, design errors, inappropriate actions, or any of the other dragons
of programming, the process is not seamless. The details of the process
rise to our awareness ("breaking down"). The burden of failure is likely
to fall on people who use or maintain the program rather than the authors.
If the program survives, these are likely audiences.
Programmers, generalizing from my own case, rarely have a seamless
experience. Programs that work the first time, are correct, efficient,
and all of the other properties, are rather far outside our experience.
The effect of this constant "breaking down" is that we have learned,
rather painfully, to be aware of the machinery of the process at every
step of the way. This focus on the machinery becomes the expected way
of communicating with the machine. Scratch any programmer, interview at
any company, listen to any talk, and you find "machinery".
But communication from the author to the audience is the underlying
theme of literate programming. Knuth's point is about communication,
not about the machinery of communication. The question is, to what
audience, not how.
Discussions seem to get lost in a debate about the machinery rather
than the goal. We focus our debate on docstrings versus markup versus
wiki. We consider literate programming to be "too much machinery".
In these forums there is rarely find any example of "present-at-hand"
issues of communication. That is, given a large program (e.g. Axiom,
Clojure), what is it that we need to communicate, to what audience,
and at what level of detail?
Axiom focuses on "The 30 year horizon" under the assumption that the
computational mathematics will be forever valid and that the audience
will be unable to contact the likely-dead authors.
Pharr and Humphreys' "Physically Base Rendering" [0] is written as a
literate program, a book that won an Academy Award, using Tex and
C++. The very first thing they mention in the preface is the
"Audience". They communicate to humans and, also, to machines.
What is the audience for Clojure?
Common Lisp has achieved a long-term horizon by raising the language
to a standard. No standard is perfect but it does make it possible to
construct programs which have a stable base for communication. That
base makes it possible to write a book like "Lisp in Small Pieces" [1]
which communicates ideas in natural language using an embedded program
as a reduction to practice.
So the fundamental point is what to communicate to what audience,
not how to implement it. Different audiences will need different
implementations (e.g. docstrings for REPL users) but we must avoid
losing ourselves in the noise.
Axiom, by choice, has a defined audience. Does Clojure?
Tim Daly
d...@axiom-developer.org
[0] Pharr, Matt; Humphreys, Greg
Physically Based Rendering
ISBN 978-0-12-375079-2
[1] Queinnec, Christian
Lisp in Small Pieces
ISBN 978-0521545662
--
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
---
You received this message because you are subscribed to the Google Groups
"Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Re: Literate Programming in Emacs?
I should add that I am starting with a working setup (able to M-x clojure-jack-in and compile and execute stuff in the REPL as expected). -- 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
Re: Literate Programming in Emacs?
It should work as expected if you follow http://orgmode.org/worg/org-contrib/babel/languages/ob-doc-clojure.html and use the stand-alone version of swank-clojure (Section Connecting with SLIME https://github.com/technomancy/swank-clojure). Looking at ob-clojure.el http://kanis.fr/hg/lisp/org/ob-clojure.el might give you some clues as well. Hope that helps Andreas On 23 November 2011 09:04, Andrew wrote: > I should add that I am starting with a working setup (able to M-x > clojure-jack-in and compile and execute stuff in the REPL as expected). > > -- > 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 -- ** Andreas Koestler, Software Engineer Leica Geosystems Pty Ltd 270 Gladstone Road, Dutton Park QLD 4102 Main: +61 7 3891 9772 Direct: +61 7 3117 8808 Fax: +61 7 3891 9336 Email: andreas.koest...@leica-geosystems.com www.leica-geosystems.com* when it has to be right, Leica Geosystems Please consider the environment before printing this email. -- 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
Re: Literate Programming in Emacs?
I have a bit of a weird setup I think. I put clojure-1.3.0.jar in ~/.clojure and set a variable for org-mode according to the advanced setup instructions. I also run org-mode from source. As a result I make sure to add org-mode's lisp/ dir to my load path. Sent via mobile On Nov 22, 2011, at 4:28 PM, Andrew wrote: > For those who do Literate Programming in Emacs, what do you use? I was > looking at org-babel-clojure which says: > > You will need to install the following packages: clojure-mode, swank-clojure, > slime, slime-repl > > But when I list-packages, swank-clojure is not in the list... It also says I > ought to be able to M-x slime ... but that results in "no such file or > directory, lisp" > -- > 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 -- 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
Re: Literate Programming in Emacs?
Here's my attempt at following the steps at http://orgmode.org/worg/org-contrib/babel/languages/ob-doc-clojure.html. *The result is org-babel-execute-src-block: No org-babel-execute function for clojure * 1. The recommendation was to follow "Connecting with SLIME" from https://github.com/technomancy/swank-clojure which involves M-x slime-connect, so I looked for that in http://orgmode.org/worg/org-contrib/babel/languages/ob-doc-clojure.html ... It has a section called "Server/Set up Leiningen project.clj file" which says add a dev-dependency in my project.clj file for leiningen/lein-swank. So I picked [leiningen/lein-swank "1.2.0-SNAPSHOT"] 2. lein deps 3. lein swank 4. It said I should add swank-clojure as a dev-dependency too. So I picked [swank-clojure "1.4.0-SNAPSHOT"] 5. lein deps 6. lein swank 7. M-x slime-connect ... connected 8. open tmp.org file and place cursor within a block of code and do C-c C-c 9. Evaluate this block of code on your system? y org-babel-execute-src-block: No org-babel-execute function for clojure! What am I missing? I have the following: clojure-mode 1.11.4 installed org 2022installed slime 20100404.1 installed slime-repl20100404installed ... and lein plugin swank-clojure (1.3.3 I think) -- 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
Re: Literate Programming in Emacs?
Andrew: Make sure you have (require 'ob-clojure) in your controlling emacs file (mine is .el). -ck On Nov 23, 12:00 pm, Andrew wrote: > Here's my attempt at following the steps > athttp://orgmode.org/worg/org-contrib/babel/languages/ob-doc-clojure.html. > *The > result is org-babel-execute-src-block: No org-babel-execute function for > clojure * > > 1. The recommendation was to follow "Connecting with SLIME" from > https://github.com/technomancy/swank-clojurewhich involves M-x > slime-connect, so I looked for that in > http://orgmode.org/worg/org-contrib/babel/languages/ob-doc-clojure.html... > It has a section called "Server/Set up Leiningen project.clj file" which > says add a dev-dependency in my project.clj file for leiningen/lein-swank. > So I picked [leiningen/lein-swank "1.2.0-SNAPSHOT"] > 2. lein deps > 3. lein swank > 4. It said I should add swank-clojure as a dev-dependency too. So I > picked [swank-clojure "1.4.0-SNAPSHOT"] > 5. lein deps > 6. lein swank > 7. M-x slime-connect ... connected > 8. open tmp.org file and place cursor within a block of code and do C-c > C-c > 9. Evaluate this block of code on your system? y > > org-babel-execute-src-block: No org-babel-execute function for clojure! > > What am I missing? I have the following: > > clojure-mode 1.11.4 installed > org 2022 installed > slime 20100404.1 installed > slime-repl 20100404 installed > > ... and lein plugin swank-clojure (1.3.3 I think) -- 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
Re: Literate Programming in Emacs?
Thanks! Next step: org-babel-execute:clojure:Cannot open load file: swank-clojure ... -- 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
Re: Literate Programming in Emacs?
I did not encounter that particular problem. But to compare, my project file is ... :dependencies [[org.clojure/clojure "1.3.0"]] :dev-dependencies [[jline "0.9.94"] [swank-clojure "1.3.0" :exclusions [org.clojure/ clojure]]] ... and my current ~/.emacs.d/elpha folder contains clojure-mode-1.11.4/ clojure-test-mode-1.6.0/ durendal-0.2/ org-2023/ slime-20100404.1/ slime-repl-20100404/ swank-clojure-1.1.0/ using Phil Hagelberg's emacs-starter-kit (https://github.com/ technomancy/emacs-starter-kit). I would also like to point to this excellent blog by Nurullah Akkaya http://nakkaya.com/2010/12/12/using-clojure-with-org-babel-and-inferior-lisp/ for using org-babel-clojure with inferior-lisp. Hope that helps. -ck On Nov 23, 4:36 pm, Andrew wrote: > Thanks! Next step: org-babel-execute:clojure:Cannot open load file: > swank-clojure ... -- 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
Re: Literate Programming in Emacs?
Thanks -- it does help somewhat... 1. How is it that you have swank-clojure in your elpa directory? M-x list-packages does not have swank-clojure as an option. 2. Why does your elpa directory have 1.1.0 and your project file have 1.3.0? 3. Is there a choice between SLIME and inferior lisp when doing literate programming in emacs? I want to keep all of my crutches like paredit-mode, syntax highlighting, symbol completion, etc. Do I have to be in an inferior lisp and lose all that? -- 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
Re: Literate Programming in Emacs?
On Tue, Nov 29, 2011 at 8:34 AM, Andrew wrote: > How is it that you have swank-clojure in your elpa directory? M-x > list-packages does not have swank-clojure as an option. The swank-clojure elisp package is deprecated and should not be used. > Why does your elpa directory have 1.1.0 and your project file have 1.3.0? swank-clojure.el was hard-coded to use Clojure 1.1.0 way back in the day, which is part of the reason it's deprecated. -Phil -- 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
Re: Literate Programming in Emacs?
Here's the relevant bit of my .emacs for Babel + Clojure: https://github.com/stuartsierra/dotfiles/blob/cb88b1ca020fd5beebb3de092f12aa27daddd779/.emacs#L203 This requires Org mode version 7.7. I mostly use inferior-lisp mode instead of SWANK/SLIME. -S -- 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
Re: Literate Programming in Emacs?
I would be really interested to see some examples of literate programs. Please consider releasing them as open source, possibly pushed to github. Tim Daly On Tue, 2011-11-29 at 11:26 -0800, Stuart Sierra wrote: > Here's the relevant bit of my .emacs for Babel + Clojure: > https://github.com/stuartsierra/dotfiles/blob/cb88b1ca020fd5beebb3de092f12aa27daddd779/.emacs#L203 > > This requires Org mode version 7.7. > > I mostly use inferior-lisp mode instead of SWANK/SLIME. > > -S > -- 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
Re: Literate Programming in Emacs?
Haven't done any recently. A long, long time ago I wrote a Common Lisp FFI tool using a Literate Programming tool called noweb. It's so old it predates GitHub: http://stuartsierra.com/software/perl-in-lisp -S -- 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
Re: Literate Programming in Emacs?
Here's a pew literate programs I've written, as well as the website on which they are hosted. http://hg.bortreb.com/abomination/ http://hg.bortreb.com/aurellem/ http://hg.bortreb.com/cortex/ http://www.aurellem.com I use some emacs scripts to automate tangling and weaving. http://hg.bortreb.com/org-tools/ http://hg.bortreb.com/repl/ sincerely, --Robert McIntyre On Tue, Nov 29, 2011 at 7:31 PM, Stuart Sierra wrote: > Haven't done any recently. A long, long time ago I wrote a Common Lisp > FFI tool using a Literate Programming tool called noweb. > > It's so old it predates GitHub: http://stuartsierra.com/software/perl-in-lisp > > -S > > -- > 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 -- 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
Re: Literate Programming in Emacs?
As you know, now I get org-babel-execute:clojure:Cannot open load file: swank-clojure The method org-babel-execute:clojure in my .emacs.d/elpa/org-2029/ob-clojure.el file says (require 'swank-clojure). Given that the swank-clojure elisp package is deprecated and should not be used what should I do? Thanks in advance -- 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
Re: Literate Programming in Emacs?
I found [1] from Eric Schulte which says to add certain package archives
such that ELPA finds swank-clojure... But what about the swank-clojure
elisp package being deprecated? (By the way, I do get further now... the
clojure code evaluates)
(setq package-archives
'(("original". "http://tromey.com/elpa/";;)
("gnu" . "http://elpa.gnu.org/packages/";;)
("marmalade" . "http://marmalade-repo.org/packages/";;)))
[1] http://lists.gnu.org/archive/html/emacs-orgmode/2011-12/msg00629.html
--
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
Re: Literate Programming in Emacs?
Andrew writes: > I found [1] from Eric Schulte which says to add certain package > archives such that ELPA finds swank-clojure... But what about the > swank-clojure elisp package being deprecated? swank-clojure.el is definitely deprecated, but there could still be code out there in the wild depending upon it. If that's the case then a bug should be opened for that package. -Phil -- 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
Re: Literate Programming in Emacs?
Eric asks: The only function ob-clojure uses from swank-clojure is `swank:interactive-eval-region' (used with `slime-eval') in the `org-babel-execute:clojure' function. Which function would now be used to evaluate a region of clojure code? Would `slime-eval-region' suffice? -- 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
Re: Literate Programming in Emacs?
I was able to get org-babel evaluation working with Clojure. Requires latest versions of Clojure mode, Org mode, and Lein. Check out my dotfiles repo for examples. https://github.com/stuartsierra/dotfiles -S -- 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
Re: Literate Programming in Emacs?
Andrew writes: > Eric asks: The only function ob-clojure uses from swank-clojure is > swank:interactive-eval-region' (used with `slime-eval') in the > org-babel-execute:clojure' function. Which function would now be used > to evaluate a region of clojure code? Would `slime-eval-region' > suffice? Yes, clojure-test-mode uses both slime-eval and slime-eval-async; he should pick one of these like so: (defun clojure-test-eval (string &optional handler) (slime-eval-async `(swank:eval-and-grab-output ,string) (or handler #'identity))) (defun clojure-test-eval-sync (string) (slime-eval `(swank:eval-and-grab-output ,string))) Actually swank:interactive-eval-region and friends are not elisp functions; they are Clojure functions. -Phil -- 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
Re: Heidegger, literate programming, and communication
Hi Tim,
I'm glad you're continuing the conversation, which has helped me at least
to clarify my thinking about not just LP but about the nature of
programming and the sort of tools we (or I at least) need to support good
programming. I end up in a very different place than you, but I don't
think it's a zero-sum game. Please take the comments below in the irenic
spirit in which they are offered - not "you are wrong on so many levels
that I'm compelled to enlighten you", but "here are some other ways to look
at things that seem interesting."
On Wed, May 21, 2014 at 6:03 AM, wrote:
> The primary focus of a "documentation system" is communication from
> the author to the audience.
>
Communication is an important part of the puzzle, I agree; but what exactly
is it? There are lots of
models<http://en.wikipedia.org/wiki/Models_of_communication>,
which carry very different implications.
>
> One of the struggles apparent in discussing issues of communication,
> especially with programmers, is Heideggers "present-at-hand" vs
> "breaking down".
>
> Programmers write programs to instruct a machine to perform some
> task. In the ideal, this involves "communication" from the mind of
> the programmer to the "execution of the program".
This suggests a transference or transmission model of communication based
on what Roy Harris <http://www.royharrisonline.com/INP26.html> calls the
"telementation" and fixed-code fallacies - the idea that communication
involves transference of some kind of content ("thoughts", "concepts",
etc.) from one mind to another, or to a machine, by encoding, sending,
receiving, and decoding "messages". That may be a good model for
computational communication, but it has severe (and I think insurmountable)
problems as a model for human communication. More fundamentally, whether
human-computer interaction should be considered communication at all is
problematic to say the least.
For a terrific study on communication check out Michael Tomasello's Origins
of Human
Communication<http://books.google.com/books/about/Origins_of_Human_Communication.html?id=T3bqzIe3mAEC>.
The suggestion there is that successful communication amounts to successful
coordination of joint action.
The notion that programs "instruct" a machine to perform some task is very
common - it's arguably central to Knuth's concept of LP - but I'm not
convinced it is correct. In a sense, a program just *is* a machine, albeit
an abstract one. When you compile it, you just translate it into another
language, yielding an equivalent machine, one that a physical machine
"understands". When you "run" the machine program, it doesn't "instruct"
the hardware to do this or that, any more than the laws of physics
"instruct" apples to fall in a certain way, or a hurled stone "instructs"
the window it meets to shatter.
...snip...
The effect of this constant "breaking down" is that we have learned,
> rather painfully, to be aware of the machinery of the process at every
> step of the way. This focus on the machinery becomes the expected way
> of communicating with the machine. Scratch any programmer, interview at
> any company, listen to any talk, and you find "machinery".
>
How could it be otherwise? Programming is machine construction.
>
> But communication from the author to the audience is the underlying
> theme of literate programming. Knuth's point is about communication,
> not about the machinery of communication. The question is, to what
> audience, not how.
>
I'm not sure what "machinery of communication" means. It's not something I
ever think about when I'm programming; in fact I never think about
communication. I think about language, logic, and expressiveness. Whether
others understand what I write is not something I can control; all I can do
is try to write clearly under the constraints of the language I'm using.
The problem with focusing on communication is that successful communication
is the responsibility of all parties involved. Authors can be held
responsible for what they write, but not for what readers read; this is
true for all forms of writing. There's not much an author can do to
prevent readers from misreading, other than try to write clearly.
Unfortunately, the Principle of
Charity<http://en.wikipedia.org/wiki/Principle_of_charity>is routinely
ignored (especially on the internet!)
Knuth: "Instead of imagining that our main task is to instruct a
*computer*what to do, let us concentrate rather on explaining to
*human
beings* what we want a computer to do." Notice how Knuth changes horses in
midstream, from "instructing a
Re: Heidegger, literate programming, and communication
On Wednesday, May 21, 2014 6:03:04 AM UTC-5, da...@axiom-developer.org
wrote:
>
> The primary focus of a "documentation system" is communication from
> the author to the audience.
>
> One of the struggles apparent in discussing issues of communication,
> especially with programmers, is Heideggers "present-at-hand" vs
> "breaking down".
>
> Programmers write programs to instruct a machine to perform some
> task. In the ideal, this involves "communication" from the mind of
> the programmer to the "execution of the program". If the program works
> the first time it is all a seamless entity ("present-at-hand").
>
> When the program fails, by compiler errors, missing libraries, runtime
> errors, design errors, inappropriate actions, or any of the other dragons
> of programming, the process is not seamless. The details of the process
> rise to our awareness ("breaking down"). The burden of failure is likely
> to fall on people who use or maintain the program rather than the authors.
> If the program survives, these are likely audiences.
>
>
>
> Programmers, generalizing from my own case, rarely have a seamless
> experience. Programs that work the first time, are correct, efficient,
> and all of the other properties, are rather far outside our experience.
>
> The effect of this constant "breaking down" is that we have learned,
> rather painfully, to be aware of the machinery of the process at every
> step of the way. This focus on the machinery becomes the expected way
> of communicating with the machine. Scratch any programmer, interview at
> any company, listen to any talk, and you find "machinery".
>
> But communication from the author to the audience is the underlying
> theme of literate programming. Knuth's point is about communication,
> not about the machinery of communication. The question is, to what
> audience, not how.
>
>
>
> Discussions seem to get lost in a debate about the machinery rather
> than the goal. We focus our debate on docstrings versus markup versus
> wiki. We consider literate programming to be "too much machinery".
>
> In these forums there is rarely find any example of "present-at-hand"
> issues of communication. That is, given a large program (e.g. Axiom,
> Clojure), what is it that we need to communicate, to what audience,
> and at what level of detail?
>
> Axiom focuses on "The 30 year horizon" under the assumption that the
> computational mathematics will be forever valid and that the audience
> will be unable to contact the likely-dead authors.
>
> Pharr and Humphreys' "Physically Base Rendering" [0] is written as a
> literate program, a book that won an Academy Award, using Tex and
> C++. The very first thing they mention in the preface is the
> "Audience". They communicate to humans and, also, to machines.
>
> What is the audience for Clojure?
>
> Common Lisp has achieved a long-term horizon by raising the language
> to a standard. No standard is perfect but it does make it possible to
> construct programs which have a stable base for communication. That
> base makes it possible to write a book like "Lisp in Small Pieces" [1]
> which communicates ideas in natural language using an embedded program
> as a reduction to practice.
>
>
>
> So the fundamental point is what to communicate to what audience,
> not how to implement it. Different audiences will need different
> implementations (e.g. docstrings for REPL users) but we must avoid
> losing ourselves in the noise.
>
> Axiom, by choice, has a defined audience. Does Clojure?
>
> Tim Daly
> da...@axiom-developer.org
>
> [0] Pharr, Matt; Humphreys, Greg
> Physically Based Rendering
> ISBN 978-0-12-375079-2
> [1] Queinnec, Christian
> Lisp in Small Pieces
> ISBN 978-0521545662
>
--
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
---
You received this message because you are subscribed to the Google Groups
"Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Re: Heidegger, literate programming, and communication
Tim, >From my point of view there are at least a few things that seem clear: 1. I think that Gregg Reynolds and I agree on a lot, but I would add to his remarks that there is almost always a human audience for source code, as well as the compiler/interpreter. Sometimes, the audience is just the originally programmer, perhaps at a later date. (If I missed something, Gregg, sorry, but I don't think you disagree, anyway.) 2. Since Clojure is a general-purpose tool, Clojure source code has no single kind of human audience for the code. In general, I do different things with comments, or with my coding style, depending on whether I expect that I will be the only maintainer of the code, or expect that others with whom I'm collaborating will need to interface with it, for example. Further, I think about the skill levels and background of those who will read the code. And I think about what they would want to do with it. And then I make decisions that involve tradeoffs between competing desiderata. 3. There is a tradeoff between the desire to see a lot of code at once, without a lot of text cluttering it up, and understanding what the code is doing. Comments hurt the former but can help the latter. The same thing goes for literate programming, but--it depends on your goals and your human audience. 4. Two examples to convey the context-dependence of appropriate configuration schemes: A. One time I wrote a small but slightly complex bit of code (in Perl, not Clojure). I could see that it would be confusing, if someone just started reading the code at an arbitrary place. But I also knew the ability of the other programmers I worked with, and I knew that if they started reading at one particular function, they would be able to figure out most of the rest. I provided text that explained what they wouldn't be able to figure out. About six months after I left the company, one of the programmers contacted me and asked me to explain the program; he had to make a modification. I told him to look at such and such document, which mainly said "Start reading the code at such and such point, and understand these few other things." He did, and that was all he needed. If I wrote more documentation, I would only be duplicating the information that was already there in the source code, and that would be apparent for the kind of people who would read it. In fact, if I provided *more* documentation, I doubt that the other programmers would have read it. They would have just looked at the source. B. Another example. I generally don't like the idea of LP. That is to say, I like the idea of people who want to be able to use it, using it, but I don't want to use it, usually. And the reason that I don't want to use it is not simply that I don't want to bother writing it. It's that I want the ability to use simple tools and I want to have relatively uncluttered source code. (I could use LP and have uncluttered source much of the time, but only by using special tools.) In my current main project, there is source code that implements the central functionality of the application, and there are rather complex configuration files. I write documents to describe the central functionality source code, so that someone who wants to hack on it will know where to start and where to look. I have to trust that they will know or will be willing to learn Clojure, because otherwise I'd have to explain too much. However, the configuration files should be modifiable by people who won't understand the guts of the program, and yet, they are in Clojure, and would be pretty unintelligible to someone who merely understood in general what the program was supposed to do. (I may create a DSL for the config files, but all that will do will be to get rid of a few parentheses. The information in the config files won't be expressed significantly more succinctly.) For the first time I'm thinking of using LP. It would be perfect for the config files, and in fact, any other way of documenting the config files will probably be inadequate. Interspersing explanations with the configuration code is precisely what's needed. -- 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 --- You received this message because you are subscribed to the Google Groups "Clojure" group. To unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
Re: Heidegger, literate programming, and communication
On Wed, May 21, 2014 at 4:39 PM, Mars0i wrote: > Tim, > > From my point of view there are at least a few things that seem clear: > > 1. I think that Gregg Reynolds and I agree on a lot, but I would add to > his remarks that there is almost always a human audience for source code, > as well as the compiler/interpreter. Sometimes, the audience is just the > originally programmer, perhaps at a later date. (If I missed something, > Gregg, sorry, but I don't think you disagree, anyway.) > I agree; whoever writes the code automatically forms an "audience" of one. I guess I would say "reader/responder". > > 2. Since Clojure is a general-purpose tool, Clojure source code has no > single kind of human audience for the code. > > In general, I do different things with comments, or with my coding style, > depending on whether I expect that I will be the only maintainer of the > code, or expect that others with whom I'm collaborating will need to > interface with it, for example. Further, I think about the skill levels > and background of those who will read the code. And I think about what > they would want to do with it. And then I make decisions that involve > tradeoffs between competing desiderata. > Exactly. Conclusion: it's hard, maybe impossible, to generalize about what all code should look like. Maybe it's essentially pluralistic. > > 3. There is a tradeoff between the desire to see a lot of code at once, > without a lot of text cluttering it up, and understanding what the code is > doing. Comments hurt the former but can help the latter. The same thing > goes for literate programming, but--it depends on your goals and your human > audience. > > 4. Two examples to convey the context-dependence of appropriate > configuration schemes: > > A. One time I wrote a small but slightly complex bit of code (in Perl, not > Clojure). I could see that it would be confusing, if someone just started > reading the code at an arbitrary place. But I also knew the ability of the > other programmers I worked with, and I knew that if they started reading at > one particular function, they would be able to figure out most of the > rest. I provided text that explained what they wouldn't be able to figure > out. About six months after I left the company, one of the programmers > contacted me and asked me to explain the program; he had to make a > modification. I told him to look at such and such document, which mainly > said "Start reading the code at such and such point, and understand these > few other things." He did, and that was all he needed. If I wrote more > documentation, I would only be duplicating the information that was already > there in the source code, and that would be apparent for the kind of people > who would read it. In fact, if I provided *more* documentation, I doubt > that the other programmers would have read it. They would have just looked > at the source. > Yep; there's always a point of diminishing returns. I find that in developing code (or trying to understand others' code) I often take extensive notes and sometimes try to mentally "improve" what I deem sloppy or hard-to-read by writing a clear description of it, or just expressing it in different language. But once I get comfortable with the code I don't often return to my documentation. ... > For the first time I'm thinking of using LP. It would be perfect for the > config files, and in fact, any other way of documenting the config files > will probably be inadequate. Interspersing explanations with the > configuration code is precisely what's needed. > I agree, that's a case where monolithic LP is entirely appropriate. Ditto for APIs and unit tests; maybe also for simplified examples of API usage expressly designed for training. -Gregg -- 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 --- You received this message because you are subscribed to the Google Groups "Clojure" group. To unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
Re: Heidegger, literate programming, and communication
Gregg and Gary, I understand where you are coming from. Indeed, Maturana [0] is on your side of the debate. Since even the philosophers can't agree, I doubt we will find a common ground. Unfortunately, I've decided to take on the task of documenting the Clojure internals because, yaknow, *I* don't feel I understand something until I know what the hardware does; consider this a flaw in my personality :-) I have to say that the posted Clojure code is "somewhat lacking" in the communication department. Perhaps it is only intended for an "audience of one", and I'm not "the one". :-) Contrary to popular belief, I am reading the code. As a result, I have a strongly held opinion that there is a lot that could be done to make it less of a struggle. >> From my point of view there are at least a few things that seem clear: >> >> 1. I think that Gregg Reynolds and I agree on a lot, but I would add to >> his remarks that there is almost always a human audience for source code, >> as well as the compiler/interpreter. Sometimes, the audience is just the >> originally programmer, perhaps at a later date. (If I missed something, >> Gregg, sorry, but I don't think you disagree, anyway.) >> > >I agree; whoever writes the code automatically forms an "audience" of one. >I guess I would say "reader/responder". Hmmm. Common Lisp is about 25 years old. Assume Clojure lives that long. What are the odds that the original authors will be maintaining the code? Will the code still be "an audience of one"? Are you sure that's a worthwhile goal? >> 2. Since Clojure is a general-purpose tool, Clojure source code has no >> single kind of human audience for the code. >> >> In general, I do different things with comments, or with my coding style, >> depending on whether I expect that I will be the only maintainer of the >> code, or expect that others with whom I'm collaborating will need to >> interface with it, for example. Further, I think about the skill levels >> and background of those who will read the code. And I think about what >> they would want to do with it. And then I make decisions that involve >> tradeoffs between competing desiderata. > My experience "in industry" with "general-purpose tool" code is that code does look a lot different from project to project and language to language. But as code moved out of its childhood and off the desk, it began to grow hair and get ugly. The authors all assumed they would be "the only maintainer". For instance, I once had to maintain a C program that had 14 pages of nested ifdefs just to choose the correct #include files. Each include file had ifdefs. The code ran everywhere, Intel, ARM, 68000s, SUNs, DEC, etc. but nearly every line was based on experience (e.g. compensating for floating-point errors on various platforms, hacking around errors in various C compilers and their "optimizers", etc.) with ifdefs around each hack. I had to run the compiler intermediate stage to figure out what the actual code would be for my platform. And then I had to reverse-engineer the fix into the appropriate include files; uncommented I might add. I wouldn't want to ruin the style. Sophisticated Lisp programmers use macros A LOT. Axiom, for instance, compiles code from a high-level algebra language, essentially a DSL, into macros that index into vectors for the function to call, or the category to inherit which might contain the call, and the environment passed to each function is a huge vector. DSLs, which make the top level code "so clear", often are macros generating machine-code-like lisp doing super-efficient vector indexing. One finds macros expanding into macros expanding into macros. Quick, what does the spadcall macro do? And we won't even mention that despite the use of a DSL, the DSL code isn't "perfectly clear" either. This is especially true when it gets mixed with inline, non-DSL code. For instance, Axiom's algebra code regularly invokes low-level lisp functions. >Exactly. Conclusion: it's hard, maybe impossible, to generalize about what >all code should look like. Maybe it's essentially pluralistic. Yes, it is hard to generalize about what all code should look like. But it is not hard to generalize that reading natural language explanations is faster, more accurate, and a lot easier than reverse-engineering code. It is MUCH easier to understand Greg Humphrey's rendering code than it is to understand the Clojure internals. Consider a randomly chosen paragraph from Physically Based Rendering (p356): To do the permutation, this function loops over the samples, randomly permuting the sample points in one dimension at a time. Note that this is a different permutation than the earlier Shuffle() routine: that routine does one permutation, keeping all nDim sample points in each sample together, while here nDim separate permutations of a single dimension at a time are done. (Figure 7.21
Re: Heidegger, literate programming, and communication
Howdy Tim,
On Thu, May 22, 2014 at 1:16 AM, u1204 wrote:
> Gregg and Gary,
>
> I understand where you are coming from. Indeed, Maturana [0] is on your
> side of the debate. Since even the philosophers can't agree, I doubt we
> will find a common ground.
>
Ah, but philosophers never agree. Disagreement is part of their job
description. Why should programmers be any different?
>
> Unfortunately, I've decided to take on the task of documenting the
> Clojure internals because, yaknow, *I* don't feel I understand something
> until I know what the hardware does; consider this a flaw in my
> personality :-)
I suffer from a similar malady, which compels me to continually rewrite
other peoples code, since, gee whiz, "foo" is not quite the perfect name
for that darn variable, "bar" would be just slightly better, and on and
on. You can see why I prefer code to commentary.
...
>>
>> 1. I think that Gregg Reynolds and I agree on a lot, but I would add to
>> his remarks that there is almost always a human audience for source code,
>> as well as the compiler/interpreter. Sometimes, the audience is just the
>> originally programmer, perhaps at a later date. (If I missed something,
>> Gregg, sorry, but I don't think you disagree, anyway.)
>>
>
>I agree; whoever writes the code automatically forms an "audience" of one.
>I guess I would say "reader/responder".
Hmmm. Common Lisp is about 25 years old. Assume Clojure lives that long.
> What are the odds that the original authors will be maintaining the
> code? Will the code still be "an audience of one"? Are you sure that's
> a worthwhile goal?
>
I think you may have misunderstood me (dunno about Gary): my point is that
even one-off code that gets discarded immediately has a human reader,
namely the author. A statement of (minimal) fact, not a goal.
...
>
>Sophisticated Lisp programmers use macros A LOT.
That's because they are language designers, and they know it.
>expanding into macros expanding into macros. Quick, what does the
>spadcall macro do?
>
HCF?
>Exactly. Conclusion: it's hard, maybe impossible, to generalize about what
> >all code should look like. Maybe it's essentially pluralistic.
>
> Yes, it is hard to generalize about what all code should look like. But
> it is not hard to generalize that reading natural language explanations
> is faster, more accurate, and a lot easier than reverse-engineering
> code.
Whoa Nelly! I don't agree with that at all, either in principle or by
experience. Well, ok, you've rigged the game. Easier than
"reverse-engineering code" - what does that mean? I guess you mean reading
well-written natural language explanations is faster etc. than reading
badly written code - but so what? It's not a meaningful comparison. Would
you take a comparison between a sample of well-written code and a sample
badly written LP as evidence against LP? I would not. To me the question
is whether well-written natural language explanation adds anything of
substance to well-written code.
> It is MUCH easier to understand Greg Humphrey's rendering code
> than it is to understand the Clojure internals.
>
Ok, but I don't see how exhibiting a piece of transparent code next to a
piece of opaque code demonstrates anything.
>
> Consider a randomly chosen paragraph from Physically Based Rendering
> (p356):
>
> To do the permutation, this function loops over the samples, randomly
> permuting the sample points in one dimension at a time. Note that this
> is a different permutation than the earlier Shuffle() routine: that
> routine does one permutation, keeping all nDim sample points in each
> sample together, while here nDim separate permutations of a single
> dimension at a time are done. (Figure 7.21)
>
>for (uint32_t i = 0; i < nDim; ++1) {
> for (uint32_t j = 0; j < nSamples; ++j) {
>uint32_t other = j + (rng.RandomUInt() % (nSamples - j));
>swap(samples[nDim + j + i], samples[nDim * other + i]);
> }
>}
>
> Footnote: While it's not necessary to permute the first dimension of
> the LHS pattern, the implementation here does so anyway since making
> the elements of the first dimension be randomly ordered means that LHS
> patterns can be used in conjunction with sampling patterns from other
> sources without danger of correlation between their sample points.
>
> So we learned what the code does. We also learned not to "optimize the
> code" by replacing it with Shuffle(). Further, we learned that we
> shouldn't "optimize the code" by removing the apparently useless
> shuffle of the first dimension. And, as a bonus, we get a figure.
> NONE OF THIS INFORMATION IS IN THE CODE ITSELF.
>
For "what the code does":
/* inline random, total, in-place matrix permutation - contrast Shuffle() */
...code...
The first line of commentary is totally redundant, so it is a waste of time
to read both it and the code. As for what not to "optimize": if none of
the conclusions you
Re: Heidegger, literate programming, and communication
On Wed, May 21, 2014 at 11:16 PM, u1204 wrote: > Heck, it is only 4 lines of C++. Why bother? *I* can read C++. I can > even reverse engineer it (probably by inventing the diagram in Figure > 2.7 on a napkin). Maybe it lives in the src/SamRecon/StratSam, which is > all the organization necessary. :-) But I can't reverse engineer the > important information in either paragraph of text. > > For comparison, refer back to the multi-page Java code I posted > from the Clojure core. As a maintenance programmer, which would you > rather maintain? > Tim, as someone already mentioned, the multi-page Java code you posted from "the Clojure core" is actually one file from the Java ASM library, copied into the Clojure Github repository from one version of that library available from here: http://asm.ow2.org There are 18,821 lines of Java code in that library, as it has been copied into Clojure in the src/jvm/clojure/asm directory. I would strongly recommend that you *not* spend a lot of time reading and documenting that code, if you want to document things that are unique to Clojure. That library is used by other projects besides Clojure. Between Clojure 1.5.1 and Clojure 1.6.0, a new version of it was copied over the older version that was used before then. http://dev.clojure.org/jira/browse/CLJ-713 That will likely happen again in a future Clojure release, to better support JDK8: http://dev.clojure.org/jira/browse/CLJ-1323 I would strongly recommend focusing on the 36,501 lines of Java code in src/jvm/clojure/lang, and/or the 19,207 lines of Clojure code in src/clj/clojure, first, and save the ASM library for later, if ever. Andy -- 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 --- You received this message because you are subscribed to the Google Groups "Clojure" group. To unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
Re: Heidegger, literate programming, and communication
Forward from Ralf Hemmecke: On 05/22/2014 11:21 AM, Gregg Reynolds wrote: > I can tell you I would rather maintain the four lines of C++ without > the largely useless commentary. That's a simple AXIOM program, but I'm sure one can easily translate it into any programming language. foo(a: Integer, b: Integer): Integer == if a > 0 then if a > b then return foo(b,a) return foo(b-a,a)) return b Question: Does the program have a bug? Ralf -- 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 --- You received this message because you are subscribed to the Google Groups "Clojure" group. To unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
Re: Heidegger, literate programming, and communication
>Tim, as someone already mentioned, the multi-page Java code you posted from >"the Clojure core" is actually one file from the Java ASM library, copied >into the Clojure Github repository from one version of that library >available from here: Hmmm, I didn't see that in the documentation :-) Thanks for the warning. In order to write the book I took a clone of the repository at a particular time with the intention of "walking up the diffs" after I had a clue about the details. >There are 18,821 lines of Java code in that library, as it has been copied >into Clojure in the src/jvm/clojure/asm directory. Oh, good. That means I can read the library documentation :-) >I would strongly >recommend that you *not* spend a lot of time reading and documenting that >code, if you want to document things that are unique to Clojure. That >library is used by other projects besides Clojure. Between Clojure 1.5.1 >and Clojure 1.6.0, a new version of it was copied over the older version >that was used before then. > >http://dev.clojure.org/jira/browse/CLJ-713 > >That will likely happen again in a future Clojure release, to better >support JDK8: and again for JDK9... and again for JDK10... and again for... If Clojure needs the library then it needs to be documented. I am using a "reference" model. If code references a function then document the function. If no code references the library then it won't get documented. Any living piece of software is going to have changes made but I'm hoping that the core remain reasonably stable. Assuming, of course, I can distinguish core code. Reading code is SO much fun :-) Anyway, thanks for the warning. 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 --- You received this message because you are subscribed to the Google Groups "Clojure" group. To unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
Re: Heidegger, literate programming, and communication
Tim, Your project of LP'ing the Clojure internals is not at all inconsistent with my view. That is code that would benefit from being widely understood, even by people who won't maintain it. I learned a lot from reading the "Lions" book on an early version of Unix, even though I probably never even used hardware old enough to run it. (On the other hand, I'm not sure that there should be documentation that explains the complexities of the chunking mechanism both at the definitions of `map` and `doseq`, for example. That seems redundant. Maybe LP software has convenient ways of dealing with that sort of issue, though.) And I agree that won't can't know what code will live for 25 years, and what won't, and how many people will have to maintain the code. So one approach is simply to assume that all code will live a long time and be maintained by many people, many of whom will be unfamiliar with the code. But that means that you waste a lot of time on code that gets put aside (for reasons other than lack of documentation). Yeah, there are tradeoffs. We have to make our best judgments. One option: Write with whatever documentation you think will help the code's forseen uses. Then, if you discover later, that it needs better documentation, write it then. That won't be as easy as writing it in the first place: In hindsight, it's less efficient, but it may be more efficient overall across all projects. (i.e. one "faults in" the documentation: It's sometimes most efficient to allocate all of an executable's image and heap as soon it runs, but modern OSes instead often allocate memory only as needed, which, in hindsight, is less efficient, but overall, makes for a more efficient system.) (I think I am the "Gary" mentioned above, although that isn't my name. But I'm happy to take on that name in this discussion.) -Gary -- 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 --- You received this message because you are subscribed to the Google Groups "Clojure" group. To unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
