Re: Literate programming

[Larry Johnson]

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

[Larry Johnson]

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: Overused phrases in the Clojure community

[Larry Johnson]

On Tue, Nov 15, 2011 at 11:05 PM, Carl Cotner  wrote:

> In general, I agree that it's annoying to continue seeing certain words
> used over and over. But the use of the word "idiomatic" in particularseems to 
> be very idiomatic in the Clojure community, so I don't mind it.
>
> :-)
>
>
> On Tue, Nov 15, 2011 at 8:16 PM, thenwithexpandedwingshesteershisflight <
> mathn...@gmail.com> wrote:
>
>> Can we please get bored of saying "idiomatic" and "in particular"
>> please ?
>>
>>
>
>
I don't want to take this topic (or myself) too seriously, but the word
"idiomatic" is a clear and well understood word among programmers.  It's
useful and specific.  I come from a perl background, where "there is more
than one way to do it", but despite the many ways to do it, there was
idiomatic perl on the one hand, and everything else on the other.  It's
useful for me to ask, when I'm learning a new language, "How would this be
written in idiomatic befunge?"

I'll keep the word idiomatic, just as I'll keep the overused word "word".
I'll promise not to overuse it, and I'll try not to use it incorrectly.

>
>  --
> 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: Clojure Conj extracurricular activities spreadsheet

[Larry Johnson]

Ahh.  Yes, it is really, really hard.  I may have misunderstood the nature
of the session.

Larry

On Mon, Oct 31, 2011 at 5:18 PM, Gary Trakhman wrote:

> I think we're just playing it, no?  :-)   Isn't it really really hard
> to solve go?
>
> On Mon, Oct 31, 2011 at 5:12 PM, Larry Johnson
>  wrote:
> > Damn, Damn, Damn.  I'm very new to clojure, and joined this forum just a
> few
> > weeks ago.  The fact that there are sessions at Clojure Conj  on two of
> my
> > passions (Go and Literate Programming), and that I'm unable to attend,
> > frustrates me to no end.
> >
> > I assume that the session on Go refers to the Asian board game known as
> > Go/Baduk/Wei Chi.  If someone could pop a note to me offline on what work
> > Clojure programmers are doing with Go, I'd really appreciate it.
> >
> >
> >
> > On Mon, Oct 31, 2011 at 1:58 PM, h.h 
> wrote:
> >>
> >> Can someone add me (hunter.hutchinson) to:
> >> * Clojurescript
> >> * Go
> >> * Pallet
> >> * D3 & Clojurescript
> >> * The web & Clojure
> >>
> >> Thanks!
> >>
> >> On Oct 31, 7:36 am, Fogus  wrote:
> >> > I've added everyone to this thread as an editor of the spreadsheet.
> >> > Please feel free to add yourself and your sessions at your leisure.
> >>
> >> --
> >> 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
>
> --
> 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: Clojure Conj extracurricular activities spreadsheet

[Larry Johnson]

Damn, Damn, Damn.  I'm very new to clojure, and joined this forum just a
few weeks ago.  The fact that there are sessions at Clojure Conj  on two of
my passions (Go and Literate Programming), and that I'm unable to attend,
frustrates me to no end.

I assume that the session on Go refers to the Asian board game known as
Go/Baduk/Wei Chi.  If someone could pop a note to me offline on what work
Clojure programmers are doing with Go, I'd really appreciate it.



On Mon, Oct 31, 2011 at 1:58 PM, h.h  wrote:

> Can someone add me (hunter.hutchinson) to:
> * Clojurescript
> * Go
> * Pallet
> * D3 & Clojurescript
> * The web & Clojure
>
> Thanks!
>
> On Oct 31, 7:36 am, Fogus  wrote:
> > I've added everyone to this thread as an editor of the spreadsheet.
> > Please feel free to add yourself and your sessions at your leisure.
>
> --
> 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

[Larry Johnson]

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.
>  
> 
>

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

[Larry Johnson]

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

[Larry Johnson]

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: Macro tutorials?

[Larry Johnson]

Hi, Nicolas, and thanks.

I'm new to clojure (I've been  working through Programming Clojure), and
most of my long work life has gravitated around c, shell scripts, and perl.
That being said, I've tinkered with Lisp dialects for the past twenty-five
years (mostly elisp, scheme, and common lisp), and have always struggled
with both the overall meaning of Lisp (when should I use it, when should I
not?), and with macros.

I downloaded and read the intro to On Lisp, and it looks like exactly what I
need.  I'm going to work through the book, and make comments here about how
it relates to my learning of clojure (assuming that it isn't deemed
off-topic noise).

Regards,
Larry



On Mon, Oct 10, 2011 at 7:33 AM, Nicolas  wrote:

> A good book to learn lisp macros, is On Lisp from Paul Graham. This
> book really cover advanced topics and concepts, and has many chapters
> related to macros.
>
> The book is freely available in online format from Paul Graham
> Website: http://www.paulgraham.com/onlisp.html
>
> On Oct 6, 1:02 pm, Michael Jaaka  wrote:
> > Thanks to all! You have helped a lot!
> > Also I will consider reading "Practical Common Lisp".
> >
> > On Oct 6, 9:42 am, Stefan Kamphausen  wrote:
> >
> >
> >
> >
> >
> >
> >
> > > Hi.
> >
> > > You might consider reading Peter Seibel's excellent Practical Common
> Lisp
> > > which has some nice macro-work in it. If after that you're still hungry
> for
> > > more, consider Let Over Lambda by Doug Hoyte.
> >
> > > Admitted, both cover Common Lisp, but the differences will not keep you
> from
> > > getting a deeper understanding of how macros work and where and how
> they can
> > > be used.
> >
> > > (This is more an answer to the subject of this thread, less to the
> question
> > > in your body :)
> >
> > > 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
>



-- 

*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