Simplified installation instructions

Preparing-your-system-to-use-Stackage.md

@@ -1,3 +1,89 @@
+# Quick start
+
+If you want to understand things in-depth, [please start reading at the overview](#overview). If you simply want to get up-and-running, choose your OS:
+
+* [Ubuntu](#ubuntu)
+* [Other Linux](#other-linux)
+* [Mac OS X](#mac-os-x)
+* [Windows](#windows)
+* [I already have my system up and running, what's the simplest that I can do?](#simplest-usage)
+
+Note: much of the information below is inspired by [bitemyapp's guide](https://github.com/bitemyapp/learnhaskell#getting-started).
+
+## Ubuntu
+
+We'll use [Herbert's PPAs](http://launchpad.net/~hvr/+archive/ghc).
+
+1. `sudo apt-get update`
+2. `sudo apt-get install software-properties-common`
+3. `sudo add-apt-repository -y ppa:hvr/ghc`
+4. `sudo apt-get update`
+5. `sudo apt-get install cabal-install-1.20 ghc-7.8.3`
+6.  Add the following to your `PATH` environment variable:
+
+        ~/.cabal/bin:/opt/cabal/1.20/bin:/opt/ghc/7.8.3/bin
+
+7. `cabal update`
+8. Edit your `~/.cabal/config` file, and replace your `remote-repo:` line with the line [available here](http://www.stackage.org/alias/fpcomplete/unstable-ghc78-exclusive)
+9. Run `cabal update` again, and you're all ready to go!
+
+Note: Many of these steps are likely unnecessary, e.g., if you already have
+`software-properties-common` installed, you don't need to reinstall it. All
+steps are provided here for completeness.
+
+## Other Linux
+
+1. Install GHC 7.8.3, and make sure it is in your `PATH`. Also add `~/.cabal/bin` to your PATH. For more information, see [bitemyapp's guide](https://github.com/bitemyapp/learnhaskell#getting-started).
+2. `wget http://hackage.haskell.org/package/cabal-install-1.20.0.3/cabal-install-1.20.0.3.tar.gz`
+3. `tar zxfv cabal-install-1.20.0.3.tar.gz`
+4. `cd cabal-install-1.20.0.3`
+5. `sh bootstrap.sh`
+6. `cabal update`
+7. Edit your `~/.cabal/config` file, and replace your `remote-repo:` line with the line [available here](http://www.stackage.org/alias/fpcomplete/unstable-ghc78-exclusive)
+8. Run `cabal update` again, and you're all ready to go!
+
+## Mac OS X
+
+It is highly recommended to install GHC via the Haskell Platform. Therefore,
+you should also use a Haskell Platform snapshot.
+
+1. [Install Haskell Platform for Mac](https://www.haskell.org/platform/mac.html)
+2. Modify your PATH to include `$HOME/Library/Haskell/bin`
+3. `cabal update`
+4. Edit your `~/.cabal/config` file, and replace your `remote-repo:` line with the line [available here](http://www.stackage.org/alias/fpcomplete/unstable-ghc78hp-exclusive)
+5. Run `cabal update` again, and you're all ready to go!
+
+## Windows
+
+It is highly recommended to install GHC via the Haskell Platform. Therefore,
+you should also use a Haskell Platform snapshot.
+
+1. [Install Haskell Platform for Windows](https://www.haskell.org/platform/windows.html)
+2. Modify your PATH to include `%APPDATA%\cabal\bin`
+3. `cabal update`
+4. Edit your ` %appdata%\cabal\config` file, and replace your `remote-repo:` line with the line [available here](http://www.stackage.org/alias/fpcomplete/unstable-ghc78hp-exclusive)
+5. Run `cabal update` again, and you're all ready to go!
+
+## Simplest usage
+
+If you already have your system up-and-running with GHC and cabal, and don't
+want to play around with modifying your remote-repo, you can still get most of
+the benefits of Stackage. Assuming you're using GHC 7.8, download [the current
+cabal.config
+file](http://www.stackage.org/alias/fpcomplete/unstable-ghc78-exclusive/cabal.config)
+into your projects working directory (next to your `.cabal` file). Poof! Your
+project is now (mostly) Stackage-enabled.
+
+# Switching to a new snapshot
+
+You have the following options when switching to a new snapshot:
+
+1. Switch globally, by:
+    1. Updating your `~/.cabal/config` file with a new remote-repo.
+    2. Deleting your `~/.ghc` directory.
+    3. Running `cabal update`
+2. Switch in a sandbox. You can currently use `hsenv` to do that. cabal sandboxes are currently limited
+
 # Overview
 
 These instructions are for users wishing to use [Stackage Server](http://www.stackage.org/) as their package repository. There are two different tools that need to be installed on your system to use Stackage Server: GHC, and cabal-install. There are generally speaking two ways of getting these tools: via [Haskell Platform](https://www.haskell.org/platform/), or installing them separately. We'll cover these options in a bit.
@@ -73,4 +159,4 @@ This will automatically download and install all the packages necessary to setup
 
 ```sh
 $ cabal update
-```
+```