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.
