5 ms·

Journo and Literate CoffeeScript

65 points by jashkenas 14y ago

jashkenas 14y ago
TL;DR posted up the earlier-promised example Literate CoffeeScript blog engine: https://github.com/jashkenas/journo https://github.com/jashkenas/journo
- weareconvo 14y 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.
  - jashkenas 14y 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.
    - weareconvo 14y ago
      But that sounds haaaaaaard.
    - smoyer 14y ago
      Do you have a link to the vim plugin you referenced?
      - joyrex 14y ago
        https://github.com/mintplant/vim-literate-coffeescript https://github.com/mintplant/vim-literate-coffeescript
- david4096 14y 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 https://gist.github.com/david4096/5106218
Riesling 14y 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.
deleted 14y ago
[deleted]
danso 14y 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 14y 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!
- jashkenas 14y 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 14y 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 14y 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 14y 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 https://github.com/JonAbrams/tomljs
- bergie 14y ago
  I experimented with Literate Programming in PHP two years ago: http://bergie.iki.fi/blog/literate_programming_with_php/ http://bergie.iki.fi/blog/literate_programming_with_php/
goldfeld 14y 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.
joyrex 14y ago
Loving the litcoffee format! Clean, elegant, addictive. Simple example usage: https://github.com/joyrexus/tester https://github.com/joyrexus/tester &: https://gist.github.com/joyrexus/5147449 https://gist.github.com/joyrexus/5147449 For vim-ers, check out vim-literate-coffeescript: https://github.com/mintplant/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 https://gist.github.com/joyrexus/5112582 Now need to take a closer look at journo and docco integration.

65 points by jashkenas 14y ago

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

weareconvo 14y 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.
- jashkenas 14y 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.
  - weareconvo 14y ago
    But that sounds haaaaaaard.
  - smoyer 14y ago
    Do you have a link to the vim plugin you referenced?
    - joyrex 14y ago
      https://github.com/mintplant/vim-literate-coffeescript https://github.com/mintplant/vim-literate-coffeescript
david4096 14y 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 https://gist.github.com/david4096/5106218

Riesling 14y 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.

deleted 14y ago

[deleted]

danso 14y 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 14y 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!

jashkenas 14y 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 14y 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 14y 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 14y 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 https://github.com/JonAbrams/tomljs

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

goldfeld 14y 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.

joyrex 14y ago

Loving the litcoffee format! Clean, elegant, addictive. Simple example usage: https://github.com/joyrexus/tester https://github.com/joyrexus/tester &: https://gist.github.com/joyrexus/5147449 https://gist.github.com/joyrexus/5147449 For vim-ers, check out vim-literate-coffeescript: https://github.com/mintplant/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 https://gist.github.com/joyrexus/5112582 Now need to take a closer look at journo and docco integration.