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 <d...@mobileink.com> wrote: > On Fri, May 9, 2014 at 8:33 AM, Erlis Vidal <er...@erlisvidal.com> 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. 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.
