Journo and Literate CoffeeScript

http://ashkenas.com/literate-coffeescript/

by jashkenas • 13 years ago

65 17 13 years ago

jashkenas3• 13 years ago

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

weareconvo2• 13 years ago

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.

jashkenas3• 13 years ago

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.

david4096• 13 years ago

First, I'd like to thank you for your great work, I'm one of the many to have benefitted from it.

I decided to take journo for a spin and wrote this up in hopes you'd continue to work on it.

https://gist.github.com/david4096/5106218

Riesling• 13 years ago

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.

danso• 13 years ago

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.

mkdir• 13 years ago

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!

jashkenas3• 13 years ago

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• 13 years ago

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.

minikomi• 13 years ago

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.

jonny_eh• 13 years ago

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• 13 years ago

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

goldfeld• 13 years ago

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.

joyrex2• 13 years ago

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.

Journo and Literate CoffeeScript

Related Stories