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). ARGF provides the methods #path and #filename to 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.

What's a man page?

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.

What do the sections mean?

man pages are broken into sections:

1. General commands
2. System calls
3. C library functions
4. Special files (usually devices, those found in /dev) and drivers
5. File formats and conventions
6. Games and screensavers
7. Miscellanea
8. System administration commands and daemons

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

How do you find man pages?

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.

How do you write man pages?

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.

AsciiDoc

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.

ronn

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:

• mustache(1)
• mustache(5)
• hub(1)
• gem-man(1)
• gist(1)

Others

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.

How do you publish man pages?

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.

Manuals of Interest

Finally, some manuals of interest:

• man fork
• man bash
• man zsh
• man curl
• man httpd
• man 5 crontab
• man netcat
• man gist
• man hub
• man git-rebase
• gem man 7 ronn
• gem man unicorn

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.

coffee-mode: An Emacs major mode for CoffeeScript.

It does all the things you want it to.

• Syntax Highlighting
• imenu support (for ⇧⌘T in textmate.el)
• customize-group support
• Comment support (alt-; and ⌘; for me)
• Indentation using tab-width
• "Smart" indentation (e.g. hitting RET after a -> will indent you properly)
• Menu Bar with links to the documentation for CoffeeScript and node.js.
• Compiles CoffeeScript

A Note on Compilation

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:

Installation

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.