Documentation rewrite

Much leaner README now. The website evangelises, and the Wiki is thorough.

1 files changed, 20 insertions, 239 deletions

diff --git a/README.md b/README.md
index e0edef220..5a9b5c0cf 100644
--- a/README.md
+++ b/README.md
@@ -1,255 +1,36 @@
 Homebrew
 ========
-Homebrew is a package management system for OS X. In other words it is a tool
-that helps you manage the installation of other open source software on your
-Mac.
+Homebrew helps you install the UNIX tools that didn't come with OS X.
 
-Here's why you may prefer Homebrew to the alternatives:
 
-1.  Zero configuration installation  
-    Copy the contents of this directory to /usr/local. Homebrew is now ready
-    for use.
+Quick Install
+-------------
+Install [Xcode][xcode] and then run this script: <http://gist.github.com/323731>
 
-2.  Or… install anywhere!  
-    You can actually stick this directory anywhere. Like ~/.local or /opt or
-    /lol if you like. You can even move this directory somewhere else later.
-    Homebrew never changes any files outside of its prefix.
+If you want to install Homebrew somewhere other than /usr/local see the
+[installation instructions][install].
 
-3.  The GoboLinux approach  
-    Packages are installed into their own prefix (eg. /usr/local/Cellar/wget)
-    and then symlinked into the Homebrew prefix (eg. /usr/local).
 
-    This way the filesystem is the package database and packages can be
-    managed with existing command line tools. For example, you can
-    uninstall with rm -rf, list with find, query with du. It also means you
-    can install multiple versions of software or libraries and switch
-    on demand.
+Look dude, I know what I'm doing!
+---------------------------------
+Alright then… as long as you're sure:
 
-    Of course, you don't have to do anything by hand, we also provide a
-    convenient and fully-featured four-letter tool called brew.
-
-4.  You don't have to sudo  
-    It's up to you.
-
-5.  Create new package descriptions in seconds  
-    Package descriptions (formula) are simple Ruby scripts. Generate a
-    template with:
-
-        brew create http://foo.com/tarball-0.8.9.tgz
-
-    Or edit an existing formula:
-
-        brew edit foo
-
-6.  Package descriptions not required  
-    MacPorts doesn't support the beta version? Need an older version? Need
-    custom compile flags? The Homebrew tool-chain is carefully segregated so
-    you can build stuff by hand but still end up with package management.
-
-    Just install to the Cellar and then call brew link to symlink that
-    installation into your PATH, eg.
-
-        ./configure --prefix=/usr/local/Cellar/wget/1.10
-        make install
-        brew ln wget
-
-    Or Homebrew can figure out the prefix:
-
-        ./configure `brew diy`
-        cmake . `brew diy`
-
-7.  Optimization  
-    We optimize for (Snow) Leopard Intel, binaries are stripped, compile flags
-    are tuned to your exact Mac model. Slow software sucks.
-
-8.  Making the most of OS X  
-    A touch of RubyCocoa, a cheeky sysctl query or two and a smattering of
-    FSEvent monitoring. In these manic days of cross-platform development,
-    it's can be a welcome relief to use something that is better because
-    it isn't too generalized.
-
-9.  No duplication  
-    MacPorts is an autarky -- you get a duplicate copy of zlib, OpenSSL,
-    Python, etc. Homebrew uses what is already there, and consequently,
-    most stuff has zero dependencies and builds faster.
-
-    We resist packaging stuff that is already packaged. So we have a [wiki page][wiki]
-    that describes how best to use RubyGems, Pip (or easy_install) and
-    CPAN with OS X and Homebrew.
-
-10. Fork with Git  
-    The formula are all on git, so just fork to add new packages, or add extra
-    remotes to get packages from more exotic maintainers.
-
-11. Surfing the cutting edge  
-    If the package provides a git://, svn://, cvs:// or hg:// url you can
-    choose to install that instead and then update as often as you like.
-
-12. Homebrew has a beer theme  
-    Beer goggles will help you to evangelise Homebrew more effectively.
-
-13. Homebrew can help you hook up  
-    There's no conclusive scientific evidence as yet, but I firmly believe
-    it's just a matter of time and statistics.
-
-I know I've made it sound so awesome you can hardly wait to embrace the fresh,
-hoppy taste of Homebrew, but I should point out that it is really new and
-still under heavy development. Also:
-
-1.  It's a little more hands-on than the competition. For example, we don't
-    set up PostgreSQL for you after installing it, but we do provide
-    instructions. This isn't apathy, it's by design -- Homebrew doesn't make
-    assumptions about how you want your software to run. You have to have some
-    knowledge or be willing to learn to use Homebrew for some tasks.
-
-2.  Dependency resolution and updates are basic or not working yet.
-
-3.  We don't support PowerPC or OS X less than Tiger (though you could always
-    maintain your own fork for such things if you like…)
-
-Max Howell — <http://twitter.com/mxcl>
-
-
-Installation
-============
-You can install Homebrew anywhere:
-
-    mkdir homebrew
-    curl -L http://github.com/mxcl/homebrew/tarball/master | tar xz --strip 1 -C homebrew
-
-Homebrew can already be used, try it:
-
-    homebrew/bin/brew install pip
-    homebrew/bin/brew list pip
-
-Notice how Pip was installed to homebrew/bin/pip — Homebrew never touches
-files outside of its prefix.
-
-But… we recommend installing to /usr/local because:
----------------------------------------------------
-1. It's already in your PATH
-2. It makes it easier to install other stuff like Ruby Gems
-
-Build tools all look to /usr/local for library dependencies and thus you can
-get on with building your own gems and not worry about having to Google for
-unnecessary build assistance.
-
-But… don't sudo!
-----------------
-Homebrew can be used with or without sudo, but, OS X was designed to
-minimise sudo use, you only need it occasionally. For example, as long as your
-user is in the admin group, this just works:
-
-    cpan -i MP3::Info
-
-Using sudo all the time is annoying, but far worse — it conditions you to type
-in your root password without thinking about it. Homebrew compliments OS X
-so you are unlikely to install anything that really needs to be chown:root.
-Let this be your last sudo for some time:
-
-    sudo chown -R `whoami` /usr/local
-
-_NOTE_: If you already installed, eg. MySQL into /usr/local then the recursive
-chown _may_ break it. Fixing MySQL should be as simple as:
-
-    sudo chown -R mysql:mysql /usr/local/mysql
-
-Installing to /usr/local
-------------------------
-    curl -L http://github.com/mxcl/homebrew/tarball/master | tar xz --strip 1 -C /usr/local
-
-Homebrew can co-exist with any software already installed in its prefix.
-
-Installing with Git
--------------------
     cd /usr/local
-    git init
-    git remote add origin git://github.com/mxcl/homebrew.git
-    git pull origin master
-
-One last important caveat
--------------------------
-Almost everything Homebrew installs is written in C, so you need Xcode:
-
-<http://developer.apple.com/technology/xcode.html>
-
-
-Uninstallation
-==============
-    cd `brew --prefix`
-    rm -rf Cellar
-    brew prune
-    rm -rf Library .git .gitignore bin/brew README.md
-
-It is worth noting that if you installed somewhere like /usr/local then these
-uninstallation steps will leave that directory exactly like it was before
-Homebrew was installed. Unless you manually added new stuff there, in which
-case those things will still be there too.
-
-
-Sample Usage
-============
-Install wget:
-
-    brew install wget
-
-Two ways to update the package descriptions:
-
-    brew update
-    cd /usr/local && git pull
-
-Two ways to delete a package:
-
-    brew uninstall wget
-    rm -rf /usr/local/Cellar/wget && brew prune
-
-Two ways to list all files in a package:
+    sudo chown -R $USER .
+    curl -sf http://github.com/mxcl/homebrew/tarball/master | tar xz --strip 1
 
-    brew list wget
-    find /usr/local/Cellar/wget
-
-Two ways to search for a package to install:
-
-    brew search
-    ls /usr/local/Library/Formula/
-
-Two ways to see what is already installed:
-
-    brew list
-    ls /usr/local/Cellar/
-
-Two ways to compute installed package sizes:
-
-    brew info wget
-    du /usr/local/Cellar/wget
-
-Show expensive packages:
-
-    du -md1 /usr/local/Cellar
-
-
-Contributing New Formulae
-=========================
-Create a new formula thusly:
-
-    brew create http://example.com/foo-1.2.1.tar.bz2
-
-Homebrew automatically opens Library/Formula/foo.rb in your $EDITOR. You can
-now install it:
-
-    brew install foo
-
-The [wiki][] has more help and information.
 
+The Wiki
+--------
+The [wiki][] can answer your remaining questions.
 
-Licensing
-=========
-Homebrew is mostly BSD licensed although you should refer to each file to
-confirm. Individual formulae are licensed according to their authors' wishes.
 
+Who Are You?
+------------
+I'm [Max Howell][mxcl] and I'm a splendid chap.
 
-The Wiki
-========
-The [wiki][] probably has the answers to any other questions you may have.
 
 [wiki]:http://wiki.github.com/mxcl/homebrew
+[install]:http://wiki.github.com/mxcl/homebrew/Installation
+[xcode]:http://developer.apple.com/technology/xcode.html
+[mxcl]:http://twitter.com/mxcl