improve installation instructions and other docs

3 files changed, 290 insertions, 86 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0a0206c..6dc39c4 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,40 +1,47 @@
-# How to contribute
+How to contribute
+=================
 
-Contributions to Magit are highly welcome. Here are a few guidelines that will
-help your patches hit upstream as soon as possible.
+Contributions to Magit are highly welcome.  Here are a few guidelines
+that will help your patches hit upstream as soon as possible.
 
-## Branching scheme
+Branching scheme
+----------------
 
-Magit uses 3 main branches for its lifecyle: `maint`, `master` and `next`.
+Magit uses three main branches for its lifecyle: `maint`, `master` and
+`next`.
 
-* `maint` contains the set of patches that will definitely make it into the next
-  minor release.
-* `master` contains the set of patches that will highly likely make it into the
-  next major release.
-* `next` contains patches that necessitate some additional checks/improvements
-  before they're integrated into a release.
+* `maint` contains the set of patches that will definitely make it
+  into the next minor release.
+* `master` contains the set of patches that will highly likely make it
+  into the next major release.
+* `next` contains patches that necessitate some additional
+  checks/improvements before they're integrated into a release.
 
-## Making changes
+Making changes
+--------------
 
-A good practice is to create a topic branch off Magit, from the branch you
-target for *final* inclusion. This should *always* be either `maint` or
-`master`.
+A good practice is to create a topic branch off Magit, from the branch
+you target for *final* inclusion.  This should *always* be either
+`maint` or `master`.
 
-If you branch off `next`, you'll only put more overhead on the maintainer's
-shoulders, and the integration will suffer from additional delays.
+If you branch off `next`, you'll only put more overhead on the
+maintainer's shoulders, and the integration will suffer from
+additional delays.
 
-Please make sure your commits are well-organized and "atomic" (hitting a single
-well-defined target each).
+Please make sure your commits are well-organized and "atomic" (hitting
+a single well-defined target each).
 
-Please also make sure you check that byte-compilation completes without errors
-or warnings, and that tests run without failures.
+Please also make sure you check that byte-compilation completes
+without errors or warnings, and that tests run without failures.
 
 Bonus points if you add tests to cover the feature you're hacking.
 
-## Submitting changes
+Submitting changes
+------------------
 
-The preferred way of submitting your changes is to open a pull request on the
-central Magit GitHub repository (https://github.com/magit/magit).
+The preferred way of submitting your changes is to open a pull request
+on the central Magit Github repository
+(https://github.com/magit/magit).
 
 Alternately, you can send your patches to the Magit mailing list
 (magit@googlegroups.com), using `git send-email`.
diff --git a/INSTALL.md b/INSTALL.md
new file mode 100644
index 0000000..73f3694
--- /dev/null
+++ b/INSTALL.md
@@ -0,0 +1,182 @@
+Installing with `package.el`
+============================
+
+Emacs >=24.1 includes a facility that lets you easily download and
+install packages.  Using `package.el` is the easiest and recommended
+way to install Magit and its dependencies.
+
+The stable Magit version is available from the [Marmalade][marmalade]
+package repository.  If you want to install the development version
+(the `master` branch) use the [Melpa][melpa] repository instead.
+Please note that *all* packages on Melpa are built from the upstream
+`master` branch.  If you generally want stable versions but the latest
+Magit use Marmalade and install Magit from Git.
+
+First tell `package.el` to use one of the package repository:
+
+```lisp
+(add-to-list 'package-archives
+             '("melpa" . "http://melpa.milkbox.net/packages/") t)
+```
+
+**or**
+
+```lisp
+(add-to-list 'package-archives
+             '("marmalade" . "http://marmalade-repo.org/packages/") t)
+```
+
+For details please see the website of the package repository of your
+choosing.
+
+Then install Magit (and its run-time dependencies):
+
+<kbd>M-x install-package RET magit RET</kbd>
+
+Dependencies
+============
+
+If you install Magit using `package.el` then dependencies are
+automatically being taken care of.  Otherwise you have to track down
+dependencies and install them manually.
+
+Release `1.2.0` and branch `maint` (stable)
+-------------------------------------------
+
+This release/branch only depends on libraries that are built into
+Emacs.
+
+Branch `master` (development)
+-----------------------------
+
+* `cl-lib` is a new library in Emacs 24.3.  Like the old `cl` it
+  provides various Common Lisp forms, but differs in that symbols are
+  prefixed with `cl-`.  A forward compatibility `cl-lib` for older
+  versions of Emacs is available from the GNU Elpa repository.  You
+  can install it using `package.el` or get it [here][cl-lib].
+
+* `contrib/magit-inotify.el` requires `inotify` with is only available
+  from Emacs' `trunk` branch; it will be released with Emacs 24.4.
+
+* `magit-wip.el` requires the `git-wip` shell script available
+  [here][git-wip].
+
+Branch `next` (experimental)
+----------------------------
+
+Same as for `master`.
+
+Running tests
+-------------
+
+To run tests the following libraries are also required:
+
+* `ert` is a tool for automated testing.  It is part of Emacs
+  starting with version 24.1.  You can also obtain an old version from
+  the former development [repository][ert].
+
+* [`mocker`][mocker] a mocking framework
+
+* [`el-x`][el-x] various utilities (required by mocker)
+
+Installing from Git
+===================
+
+If you want to live on the bleeding edge or just aren't that much into
+`package.el` the next best thing is to get Magit from Git.  This is
+also necessary if you want to contribute to Magit.
+
+    git clone git://github.com/magit/magit.git
+
+You then have the choice between the `maint` (stable), `master`
+(development), and `next` (experimental) branches.  The latter two
+depend on third-party libraries, which have to be properly installed
+for the following to succeed.
+
+Start by adding the following lines to your init file:
+
+```lisp
+(add-to-list 'load-path "/path/to/magit-repo")
+(require 'magit)
+```
+
+If you intend to use contributed libraries also add this:
+
+```lisp
+(add-to-list 'load-path "/path/to/magit-repo/contrib")
+```
+
+To finish the installation you can use `make` as explained in the
+tarball section below.  The only difference is that you have to skip
+the final `make install` step, since we already added the repository
+itself to the `load-path`.
+
+Or you could just do it manually, by running something like this:
+
+    $ emacs -Q -batch -L . -L ../DEPENDENCY -b batch-byte-compile *.el
+    $ makeinfo -o magit.info magit.texi
+    $ ginstall-info --dir=dir magit.info
+
+and adding this to your initialization file:
+
+```lisp
+(eval-after-load 'info
+  '(progn (info-initialize)
+          (add-to-list 'Info-directory-list "/path/to/magit-repo/")))
+```
+
+Installing from Tarball
+=======================
+
+Download and unpack [magit-1.2.0.tar.gz][download]. Then build and
+install as usual:
+
+    $ wget https://github.com/downloads/magit/magit/magit-1.2.0.tar.gz
+    $ tar -xf magit-1.2.0.tar.gz
+	$ cd magit-1.2.0
+    $ make
+    $ sudo make install
+
+This requires the `makeinfo` binary (usually available from a package
+named `texinfo`).  If you don't have it you can skip creating the info
+page by using this instead:
+
+    $ make core
+    $ sudo make install_core
+
+You might also want to compile and install the additional libraries in
+`contrib/`:
+
+    $ make contrib
+    $ sudo make install_contrib
+
+In either case Emacs lisp libraries are put into
+`/usr/local/share/emacs/site-lisp/`, where Emacs should be able to
+find them.  Finally add this to your initialization file.
+
+    (require 'magit)
+
+
+[contributing]: https://github.com/magit/magit/blob/maint/CONTRIBUTING.md
+[contributors]: https://github.com/magit/magit/contributors
+[development]: http://github.com/magit/magit
+[download]: https://github.com/downloads/magit/magit/magit-1.2.0.tar.gz
+[group]: https://groups.google.com/forum/?fromgroups#!forum/magit
+[installing]: https://github.com/magit/magit/blob/maint/INSTALL.md
+[issues]: https://github.com/magit/magit/issues
+[manual]: http://magit.github.com/magit/magit.html
+[owners]: https://github.com/magit?tab=members
+[pulls]: https://github.com/magit/magit/pulls
+[screencast]: http://vimeo.com/2871241
+[website]: http://magit.github.com/magit
+
+[cl-lib]: http://elpa.gnu.org/packages/cl-lib.html
+[el-x]: https://github.com/sigma/el-x
+[emacs]: http://www.gnu.org/software/emacs
+[ert]: https://github.com/ohler/ert
+[git-wip]: https://github.com/bartman/git-wip
+[git]: http://git-scm.com
+[marmalade]: http://marmalade-repo.org
+[melpa]: http://melpa.milkbox.net
+[mocker]: https://github.com/sigma/mocker.el
+[vc]: http://www.gnu.org/software/emacs/manual/html_node/emacs/Version-Control.html
diff --git a/README.md b/README.md
index a323c85..365d90e 100644
--- a/README.md
+++ b/README.md
@@ -1,88 +1,103 @@
-It's Magit!  An Emacs mode for Git.
-===================================
+It's Magit!  An Emacs mode for Git
+==================================
 
-Magit is an interface to Git for Emacs, supporting GNU Emacs 22 or
-later.
+Magit is an interface to [Git][git] for [Emacs][emacs].
 
- Unlike Emacs's native [version control support][vc], Magit can take
-advantage of Git's native features without breaking compatibility with
-other systems.
+Unlike Emacs's native [version control support][vc] which strives to
+provide a unified interface to various version control systems, Magit
+only supports Git and can therefor take full advantage of its native
+features.
 
-To get started see the [Magit User Manual][manual]. There's also an
-excellent [Magit screencast][screencast] by Alex Vollmer which
-demonstrates some of the major features.
+Magit supports GNU Emacs 22.1 or later; 24.1 or later is recommended.
 
-Installing
-----------
+Getting Started
+===============
 
-Download the latest tarball from [the github download page][download],
-then Magit can be installed with the popular recipe of:
+To get started with Magit, run <kbd>M-x magit-status</kbd>.  If you
+are inside a Git repository this opens a buffer that summarizes its
+status.  Otherwise you are first prompted for a repository.  Read the
+short help for `magit-mode` (<kbd>C-h m</kbd> in the status buffer),
+make some changes to your files, stage (<kbd>s</kbd>), and commit
+(<kbd>c</kbd>) them.
 
-    $ make && sudo make install
+For more details consult the Magit user manual.  You can read it
+[on the web][manual] or in Emacs with <kbd>C-u C-h i magit.info</kbd>.
 
-This requires `emacs` and `makeinfo` binaries, so please make sure the relevant
-packages (generally `emacs` and `texinfo`) are installed on your system.
-This will put magit.el into `/usr/local/share/emacs/site-lisp`, where
-Emacs should be able to find it.  Then add
+Magit also has a [website][website].
 
-    (require 'magit)
+Installation
+============
 
-to your `.emacs` file.
+Emacs >=24.1 includes a facility that lets you easily download and
+install packages.  Using `package.el` is the easiest and recommended
+way to install Magit and its dependencies.  If you don't want use it
+see the extended installation instructions in INSTALL.md
+([weblink][installing]).
 
-Getting started
----------------
+The stable Magit version is available from the [Marmalade][marmalade]
+package repository.  If you want to install the development version
+(the `master` branch) use the [Melpa][melpa] repository instead.
+Please note that *all* packages on Melpa are built from the upstream
+`master` branch.  If you generally want stable versions but the latest
+Magit use Marmalade and install Magit from Git.
 
-To get started with Magit, open any file in a Git repository in Emacs
-and run `M-x magit-status`.  Read the short help for magit-mode (`C-h
-m` in the Magit buffer), make some changes to your files, and try to
-commit them.
+First tell `package.el` to use one of the package repository:
 
-Learning more
--------------
+```lisp
+(add-to-list 'package-archives
+             '("melpa" . "http://melpa.milkbox.net/packages/") t)
+```
 
-The [Magit User Manual][manual] describes things with more words than
-the online help.  You can read it in Emacs with `C-u C-h i
-magit.info`, or [on the web][manual].
+**or**
 
-If you have any questions, please use [the mailing list][google group]
-at Google Groups.
+```lisp
+(add-to-list 'package-archives
+             '("marmalade" . "http://marmalade-repo.org/packages/") t)
+```
 
-Magit's website is currently hosted [on GitHub][website].
+For details please see the website of the package repository of your
+choosing.
 
-Extensions
-----------
+Then install Magit (and its run-time dependencies):
 
-Magit also now supports extensions:
-
-### git-svn
-
-`(require 'magit-svn)` - integrates with git-svn. Hit 'N' to see your
-options.
-
-### git-topgit
-
-`(require 'magit-topgit)` - integrates with topgit.
-
-### git-stgit
-
-`(require 'magit-stgit)` - integrates with StGit.
+<kbd>M-x install-package RET magit RET</kbd>
 
 Development
------------
+===========
 
-Magit was started by Marius Vollmer. It is now collectively maintained
-by the [Magit Owners Team][owners]. [Many more people][contributors]
+Magit's canonical source repository is
+[hosted on Github][development].
+
+Magit was started by Marius Vollmer and is now collectively maintained
+by the [Magit Owners Team][owners].  [Many more people][contributors]
 have contributed.
 
-Magit's canonical source repository is currently
-[hosted on GitHub][development].
+To report bugs and make feature requests please use the
+[issue tracker][issues] and Github [pull requests][pulls].  You may
+also use Magit's [Google group][group].  Before making a pull request
+please read CONTRIBUTING.md ([weblink][contributing]).
 
-[vc]: http://www.gnu.org/software/emacs/manual/html_node/emacs/Version-Control.html#Version-Control
-[website]: http://magit.github.com/magit
+
+[contributing]: https://github.com/magit/magit/blob/maint/CONTRIBUTING.md
+[contributors]: https://github.com/magit/magit/contributors
 [development]: http://github.com/magit/magit
+[download]: https://github.com/downloads/magit/magit/magit-1.2.0.tar.gz
+[group]: https://groups.google.com/forum/?fromgroups#!forum/magit
+[installing]: https://github.com/magit/magit/blob/maint/INSTALL.md
+[issues]: https://github.com/magit/magit/issues
 [manual]: http://magit.github.com/magit/magit.html
-[screencast]: http://vimeo.com/2871241
-[download]: http://github.com/magit/magit/downloads
-[google group]: http://groups.google.com/group/magit/
 [owners]: https://github.com/magit?tab=members
-[contributors]: https://github.com/magit/magit/contributors
+[pulls]: https://github.com/magit/magit/pulls
+[screencast]: http://vimeo.com/2871241
+[website]: http://magit.github.com/magit
+
+[cl-lib]: http://elpa.gnu.org/packages/cl-lib.html
+[el-x]: https://github.com/sigma/el-x
+[emacs]: http://www.gnu.org/software/emacs
+[ert]: https://github.com/ohler/ert
+[git-wip]: https://github.com/bartman/git-wip
+[git]: http://git-scm.com
+[marmalade]: http://marmalade-repo.org
+[melpa]: http://melpa.milkbox.net
+[mocker]: https://github.com/sigma/mocker.el
+[vc]: http://www.gnu.org/software/emacs/manual/html_node/emacs/Version-Control.html