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.

Reply via email to