

Journo and Literate CoffeeScript - jashkenas
http://ashkenas.com/literate-coffeescript/

======
mkdir
Jeremy, your code's comments are all hard-wrapped at column 80, but the code
itself extends beyond that.

Do you tell your editor to hard-wrap each "block" of comments as you write (or
edit) them, or is your editor configured to automatically hard-wrap all
comments?

Either way, have you considered configuring your editor to _soft-wrap_
comments while leaving your code alone? I'd say that's the most natural
approach from a writing standpoint.

P.S. Every day, I use tools you've made. Keep making!

~~~
jashkenas
Yeah, in an ideal world, that would be better -- and I've tried writing like
that ... but sooner or later I end up wanting to open the file in a location
where the wrapping isn't configured properly, and all of the super long lines
look terrible.

So I just tend to hard-wrap manually, out of habit, even when writing in a
.txt file or an email. In fact, it's hard to stop myself from doing it in this
textarea ;)

~~~
eric-hu
What editor do you use? With vim I think I've always been able to select
comments and "gq" them to autoformat them to whatever the linewidth is set to.

------
jashkenas
TL;DR posted up the earlier-promised example Literate CoffeeScript blog
engine: <https://github.com/jashkenas/journo>

~~~
weareconvo
I've always been excited by the idea of literate programming, and after having
flirted with most of the other Javascript meta-languages, now use Coffeescript
as my main language for both server-side (node.js) and client-side code. Is
there currently a good syntax highlighting mode that properly displays
.litcoffee files? I currently use Emacs with the coffee-mode major mode, but I
don't think it's been updated yet.

~~~
jashkenas
I'm not aware of an Emacs one being updated yet, although I think that
someone's finished it for Vim.

If you want to be an open-source hero -- go ahead and do it yourself ;) It's
mainly a matter of taking the Markdown package, and the CoffeeScript package,
and pasting the latter into the former, right where the syntax rule for "code
block" goes.

~~~
smoyer
Do you have a link to the vim plugin you referenced?

~~~
joyrex
<https://github.com/mintplant/vim-literate-coffeescript>

------
Riesling
Jeremy,

I am a big fan of the goals of your work (CoffeeScript, Literate Programming).

Both projects make code easier to understand and more accessible to everyone.

I have the feeling that many of us forget about the value of this, after
having invested many hours to understand complex syntaxes and general
patterns.

From lowering the entry barrier and increasing efficiency, everybody will
profit in the end.

------
minikomi
Well that was interesting. Started reading the readme formatted on the page..
Well commented as usual, nice little snippets to demonstrate..

About half way through realized it was the actual source file.

------
joyrex
Loving the litcoffee format! Clean, elegant, addictive.

Simple example usage: <https://github.com/joyrexus/tester>

&: <https://gist.github.com/joyrexus/5147449>

For vim-ers, check out _vim-literate-coffeescript_ :
<https://github.com/mintplant/vim-literate-coffeescript>

I've found a few additional mappings quite useful:
<https://gist.github.com/joyrexus/5112582>

Now need to take a closer look at _journo_ and _docco_ integration.

------
jonny_eh
I had never heard of literate programming until Monday with the release of
CoffeeScript 1.5.0

So I tried it out and found it to be a really rewarding experience:
<https://github.com/JonAbrams/tomljs>

~~~
bergie
I experimented with Literate Programming in PHP two years ago:
<http://bergie.iki.fi/blog/literate_programming_with_php/>

------
goldfeld
I thought the `do loadManifesto' syntax was discouraged in favor of
'loadManifesto()'? I've read jashkenas say he wished that hadn't been
introduced in the first place, and now I see it in his code.

------
danso
It's always interesting how something that shouldn't be that big of a deal is
a much bigger deal when experienced. I mean that using Markdown is not
conceptually different than writing judiciously-placed block comments, but the
ease of formatting for the coder -- and the most definite impact on reading
for the reader -- is a _huge_ impact. Thinking about it now, I sometimes skip
self-documentation even when I _know_ it's the right thing to do (given how
much time we spend re-reading code compared to writing it) because it's
annoying just enough to remember what my style/convention is to make long
comments readable. Having Markdown provide the template removes that cognitive
barrier, and hopefully makes it easier to _ease_ into the documentation
process.

