→ Code Bloggin' at Gist
http://gist.github.com/defunkt, in case you missed it.
Today Ruby gave me a birthday present: ARGF. If you write a lot of
shell scripts you're gonna love it.
To demonstrate we'll write rcat, a dumbed down version of cat(1),
in Ruby. But first let's examine some of cat's basic functionality
using one.txt and two.txt.
$ echo 'File one!' > one.txt
$ echo 'File two :(' > two.txt
Printing a single file:
$ cat one.txt
File one!
Printing multiple files:
$ cat one.txt two.txt
File one!
File two :(
Mixing files and streams:
$ cat - two.txt < one.txt
File one!
File two :(
Okay. And rcat?
$ rcat one.txt
File one!
$ rcat one.txt two.txt
File one!
File two :(
$ rcat - two.txt < one.txt
File one!
File two :(
Great! So, how's rcat work?
$ rcat rcat
#!/usr/bin/env ruby
puts ARGF.read
Gorgeous. From the docs:
The global constant
ARGF(also accessible as$<) provides an IO-like stream which allows access to all files mentioned on the command line (or STDIN if no files are mentioned).ARGFprovides the methods#pathand#filenameto access the name of the file currently being read.
I've just rewritten mustache(1) to use ARGF. Less code, more
functionality - what else could you want for your birthday? Thanks
Ruby!
Want to install gem-man(1) and forget about it? You can. Add
this to your ~/.bash_profile or whatever after installing 0.2.0:
alias man='gem man -s'
Now:
$ man 5 mustache
$ man fork
$ man grep
And, of course:
$ man gem-man
Everyone loves having instant access to documentation. This is one of
the things Cheat does really well: just type cheat git and
you've got a git cheat sheet in your terminal. Or in your editor,
whatever. It's cool stuff.
Well, man pages do the same thing. For instance, I've installed
node.js via homebrew which means I can type man node at any time to
see the docs to the entire node.js standard library. Seriously. Thanks
mxcl and ryah.
In Emacs I can hit M-x man to pull up any man page. Vim has a
plugin and so does TextMate.
If you're using a tool that came with your OS, you can bet there's a man page for it. Unicorn has a great one, so does ack. And if you've installed cmatrix, which I hope you have, it has one too.
It's the way Unix documents things, and it's already really easy for you to access. man pages are worth understanding.
Wikipedia says:
Man pages (short for manual pages) are the extensive documentation that comes preinstalled with almost all substantial Unix and Unix-like operating systems. The Unix command used to display them is man. Each page is a self-contained document.
You can see one by going to your terminal and typing:
$ man grep
Or, naturally, man man.
On some systems like Debian, every program is required to come with a man page. I don't know if the same is true for OS X, but all the Mac-specific commands I've used have man pages. For example:
$ man pbcopy
Same for launchctl, say, and more.
Man pages are a great way to learn about a piece of software. Try man
grep or check out man strftime. Yes, C functions have man pages
too.
man pages are broken into sections:
This means we can have markdown(1) and markdown(5), two man pages
with the same name that live in different sections. One is a man page
describing a command, typing markdown in your shell, and one is a
man page describing the Markdown file format. Like what you'd read on
Gruber's Markdown page.
You can specify which you'd like to view like so:
$ man 1 markdown
$ man 5 markdown
You can use apropos on many systems to search for man pages matching
a string:
$ apropos ruby
macruby(1), ruby(1) - Interpreted object-oriented scripting language
cap(1) - Ruby on Rails web applications deployment utility
gem(1) - RubyGems program
irb(1), erb(1), ri(1), rdoc(1), testrb(1) - Ruby helper programs
mongrel_rails(1) - Fast HTTP library and server for Ruby
rake(1) - Ruby Make
ruby(1) - Interpreted object-oriented scripting
language
There are also at least five iPhone apps dedicated to man pages, all of which cost money:

If you're using Ruby, you can discover man pages that RubyGems you've
installed contain by installing gem-man and using --all:
$ gem install gem-man
$ gem man --all
These gems have man pages:
ronn 0.4.1
unicorn 0.97.0
unicorn 0.96.0
gem-man 0.1.3
mustache 0.6.0
And then:
$ gem man 1 mustache
Sweet. There's also Richard Crowley's alias man trick.
man pages are written in a funky macro language as part of a
typesetting system called roff, which dates back to around 1973. That
is, according to man roff. Anyway, it's nasty - you can look at
mustache.1 for an example. You don't wanna write it by hand.
It's much easier to let a computer generate this markup for us, just like how we let Markdown generate HTML. As far as I know there are two excellent tools you can use to author man pages.
Git and Unicorn use AsciiDoc. The Passenger guys do, too. It can generate both HTML and man pages from quite readable text files.
In fact, check this out: I grabbed ParseTree's spartan yet extremely
readable README.txt and ran it through asciidoc:

Tasty.
You can grab AsciiDoc with:
$ brew install asciidoc
or by any of the methods documented on their Installation page.
It, naturally, has a man page: man asciidoc once you've got it installed.
Personally, I like to use Ryan Tomayko's ronn. If you have RubyGems:
$ gem install ronn
Now run it on any README.markdown. I'll try it on Resque's:
$ ronn -b5 README.markdown

Gorgeous.
It looks even better when passed something in the Markdown derived ronn(5) format:
Here are some I've published:
Perl has Pod - I can man Apache2::Const and see a different
yet familiar face, presumably a man page generated by pod2man, which
is neat.
Ruby also has rtfm, a gem for building man pages in Ruby.
Then there's Doxygen, and probably many more.
For generating them, I use these rake tasks. You might also want to look at Richard Crowley's manskeleton.
For HTML I like to use GitHub Pages. It's pretty easy to write a
Rake task or something that generates a man page's HTML and
publishes it to your gh-pages branch. I pretty much do it in all my
projects - I'm sure many others do the same.
Many packaging systems support files in man/file.section or
man/manSECTION/file.SECTION format. For example, manskeleton's man
pages or mustache's.
When you install a Debian or homebrew package, any man pages get installed automatically. This means if you package man pages users will magically get them, and everyone wins.
So let's do that.
Finally, some manuals of interest:
I've fallen in love with CoffeeScript.
It's the best parts of my three favorite languages (JavaScript, Ruby, and Python) rolled into one. It runs on node.js, compiles to surprisingly readable JavaScript, has great documentation, and is written in itself.
Yes, CoffeeScript is written in CoffeeScript. Check the source code or the beautiful internals documentation.
You can use it on the server with node.js (or, presumably, any CommonJS compatible process), or you can use it in the browser.
Deployment? When you bundle your JavaScript, compile your CoffeeScript and include it. In development mode use something like rack-coffee to have your CoffeeScript automatically compiled and served to the browser - no work on your part.
There's a Vim plugin, a TextMate bundle, and, now, an Emacs mode.
Say hello to coffee-mode.

It does all the things you want it to.
customize-group supportalt-; and ⌘; for me)tab-widthRET after a -> will indent you
properly)If you're using Aquamacs, ⌘r should compile the current coffee-mode
buffer and open the resulting JavaScript in a new buffer using
js2-mode. You can customize the mode used to open JavaScript by
overriding coffee-js-mode and you can override the key combo by
adding this to the coffee-mode-hook like so:
(defun coffee-custom ()
"coffee-mode-hook"
;; Emacs key binding
(define-key coffee-mode-map [(meta r)] 'coffee-compile-buffer))
(add-hook 'coffee-mode-hook '(lambda () (coffee-custom)))
Make sure you have CoffeeScript 0.5.4 or higher, or change your
coffee-command and coffee-args-compile variables to whatever you
know works.
Why is this worth pointing out? Because it means you can hit a single key and see the compiled JavaScript in your editor, which is just great:

In your shell:
$ cd ~/.emacs.d/vendor
$ git clone git://github.com/defunkt/coffee-mode.git
In your emacs config:
(add-to-list 'load-path "~/.emacs.d/vendor/coffee-mode")
(require 'coffee-mode)
If coffee-mode is not enabled automatically for any files ending in
".coffee" or named "Cakefile", add this to your emacs config as well:
(add-to-list 'auto-mode-alist '("\\.coffee$" . coffee-mode))
(add-to-list 'auto-mode-alist '("Cakefile" . coffee-mode))
Bugs http://github.com/defunkt/coffee-mode/issues
Source http://github.com/defunkt/coffee-mode
Enjoy.