Update installation instructions

Author: Siddhanathan Shanmugam

pages/installing.md

@@ -3,105 +3,125 @@ layout: page
 title: Installing/hacking Yi
 ---
 
+Yi requires GHC 7.8 at minimum and is mainly developed with GHC 7.10.1.
 
-Yi requires GHC 7.6.3 at minimum and is mainly developed with GHC 7.8.3.
+With the Haskell Platform installed, yi can be installed with cabal-install:
 
-With the Haskell Platform installed, yi should be installed with cabal-install:
+~~~ bash
+$ cabal update
+$ cabal install yi
+~~~
 
-    $ cabal update
-    $ cabal install yi
+On Linux systems, you will need ncurses development headers for
+the Vty frontend. For example, Ubuntu requires `libncurses5-dev`
+for ncurses support  and `libicu-dev` for unicode support.
 
-On Linux systems, you'll probably need ncurses development headers for
-the Vty frontend. On Ubuntu, you'll need to install the
-`libncurses5-dev` package. Also, `libicu-dev` on Ubuntu would be required for unicode support.
+The frontends for yi can be manually specified as follows:
 
-You can specify frontends to compile, also:
-
-    $ cabal install yi -fvty -fpango
+~~~ bash
+$ cabal install yi -fvty -fpango
+~~~
 
 Options are `-fvty` and `-fpango`.
 
-You can also install the `yi-contrib` package, which contains some
-extra contributed things (like user configs):
+Note: If you get a `frontend not found` warning, install yi with the frontend
+manually specified by -fvty or -fpango while doing cabal install.
 
-    $ cabal install yi-contrib
+Note: If you're having weird problems such as your changes not seeming
+to take effect, you might have some stale stuff in the cache
+directory which you should empty: on my system it's `~/.cache/yi`.
 
-If you're in the source repository, you can install yi from source:
 
-    $ cabal update # Still update to get updated dependencies
-    $ cd yi && cabal install
+### Installing Yi from source
 
-And the contrib package:
+You can install Yi from source as follows:
 
-    $ cd yi-contrib && cabal install
+~~~ bash
+$ git clone https://github.com/yi-editor/yi
+$ cd yi
+$ cabal update
+$ cabal install
+~~~
 
-Please note that if you are looking to get absolutely latest sources,
-you should set up the supporting repositories from
-[the GitHub project page][ghproject] first.
-
-Note: if you're having weird problems such as your changes not seeming
-to take effect, you might have some stale stuff in the cache
-directory which you should empty: on my system it's `~/.cache/yi`.
+Yi is split into multiple smaller supporting packages (such as yi-rope
+and yi-language). If you are looking to get absolutely latest sources,
+make sure to install the supporting packages before installing Yi.
+Usually these packages are rarely updated and the version on Hackage
+is up-to-date. You can set up the supporting repositories from
+[the GitHub project page][ghproject].
 
 ### Installing inside a Cabal sandbox
 
-Many people want to install Yi inside a cabal sandbox (cabal-install
-1.18 feature). This is especially important if you plan on hacking on
-Yi itself or on libraries for Yi.
+Cabal-install 1.18 and higher support sandboxing which isolates
+the Yi installation from the rest of the cabal environment. This
+is especially important if you plan on hacking on Yi itself, or on
+libraries for Yi.
+
+If your cabal version is lower than 1.20, you can install a newer
+version of cabal-install using cabal itself. This is recommended
+since newer versions of Cabal have several useful utilities for
+sandboxed environments.
+
+~~~ bash
+$ cabal update
+$ cabal install cabal-install
+$ cabal --version
+~~~
 
 As Yi compiles your config file once you start it, the config needs to
 know where to look for any of its dependencies, such as Yi itself! If
 these are inside of the sandbox, it doesn't know where to look and
 you'll get config compilation errors due to missing modules.
 
 To sandbox, navigate to your source yi directory. For me it's
-`~/programming/yi/yi`.
+`~/programming/yi/`.
 
 We then setup a cabal sandbox:
 
-```
+~~~ bash
+$ cd ~/programming/yi
 $ cabal sandbox init
 $ cabal install --only-dependencies
 $ cabal install
-```
+~~~
 
 From cabal-install 1.20, Yi can be launched in an environment using the
 sandbox's package DB using `cabal exec ./dist/build/yi/yi`. It may be useful
 to create an alias or small script for this, along the lines of:
 
-```
+~~~ bash
 #!/usr/bin/env bash
 YI_DIR=$HOME/programming/yi/yi
 env CABAL_SANDBOX_CONFIG=$YI_DIR/cabal.sandbox.config cabal exec $YI_DIR/dist/build/yi/yi -- "$@"
-```
+~~~
 
-The `"$@"` part means that all the
-arguments we pass to this script are passed on to the Yi binary which
-means we can still use all the regular flags, such as `runyi
---as=emacs`. Of course, you'll need to adjust the paths used to match
-your sandbox and package directories.
+The `"$@"` part means that all the arguments we pass to this script
+are passed on to the Yi binary which means we can still use all the
+regular flags, such as `yi --as=emacs`. Of course, you'll need to
+adjust the paths used to match your sandbox and package directories.
 
-There's one more thing to mention in this section and that is config
+There's one more thing to mention in this section, and that is config
 dependencies. One of the great things about Yi is that we have access
 to the wealth of existing Haskell libraries and we can take advantage
 of this in our config file. There are two scenarios:
 
-If the package your config depends on is on Hackage and you want to
-use that, just use `cabal install` in the sandboxed Yi directory. So
-if your config depends on `semigroups`, you'd run `cabal install
-semigroups`. After doing this, `semigroups` should now be visible when
-your config is getting compiled.
-
-If the package your config depends on is local, for example when
-you're developing the library that you want to use or if you need a
-patched version, you'll have to use `cabal sandbox add-source`
-command. As an example, I'm developing a `yi-haskell-utils` package
-and my config depends on it. To accommodate for this, I ran `cabal
-sandbox add-source ~/programming/yi-haskell-utils`.
-You can then `cabal install yi-haskell-utils` to add the package to
-the sandbox. You should call `cabal build` in the sandbox directory
-after you modify a local package so that the sandbox has an up-to-date
-version of the package.
+* If the package your config depends on is on Hackage and you want to
+  use that, just use `cabal install` in the sandboxed Yi directory. So
+  if your config depends on `semigroups`, you'd run `cabal install
+  semigroups`. After doing this, `semigroups` should now be visible when
+  your config is getting compiled.
+
+* If the package your config depends on is local, for example when
+  you're developing the library that you want to use or if you need a
+  patched version, you'll have to use `cabal sandbox add-source`
+  command. As an example, I'm developing a `yi-haskell-utils` package
+  and my config depends on it. To accommodate for this, I ran `cabal
+  sandbox add-source ~/programming/yi-haskell-utils`.
+  You can then `cabal install yi-haskell-utils` to add the package to
+  the sandbox. You should call `cabal build` in the sandbox directory
+  after you modify a local package so that the sandbox has an up-to-date
+  version of the package.
+
 
 I suspect that it'd be perfectly possible to make your config file
 into a cabal project and manage the dependencies that way but I have
@@ -288,4 +308,6 @@ get clobbered so it's mostly only useful for the repositories which
 will most likely not get many extra dependencies but are likely to
 change versions often.
 
+
 [ghproject]: https://github.com/yi-editor
+