reorg and rewrote build-from-source instructions

7 files changed, 78 insertions, 95 deletions

diff --git a/doc/contribute.mdwn b/doc/contribute.mdwn
index 71bce6c54..bc087348d 100644
--- a/doc/contribute.mdwn
+++ b/doc/contribute.mdwn
@@ -24,7 +24,8 @@ you'll make Joey more productive!
 
 ## code contributions
 
-[[download]] the source code and send patches!
+[[download]] the source code, [[build|install/fromsource]] it
+and send patches!
 
 If you know Haskell, git-annex has lots of Haskell code that
 could be improved. See the [[coding_style]] and have at it.
diff --git a/doc/install.mdwn b/doc/install.mdwn
index 7fe21c9ba..adaaa3eb6 100644
--- a/doc/install.mdwn
+++ b/doc/install.mdwn
@@ -22,15 +22,13 @@ detailed instructions             | quick install
 All the downloads above use https for security. For added security, see
 [[verifying_downloads]].
 
-## Using cabal
+## Building it yourself
 
-As a haskell package, git-annex can be installed from source pretty easily
-[[using cabal|cabal]].
-
-## Installation from scratch
-
-This is not recommended, but if you really want to, see [[fromscratch]].
+git-annex is [[Free Software|license]], written in [Haskell](http://www.haskell.org/).
+Experienced users should not find it too hard to build and install
+it [[from source|fromsource]].
 
 ## See also
 
+
 [[autobuild overview|builds]]
diff --git a/doc/install/Linux_standalone.mdwn b/doc/install/Linux_standalone.mdwn
index f7aca5b9a..fbb3b97ab 100644
--- a/doc/install/Linux_standalone.mdwn
+++ b/doc/install/Linux_standalone.mdwn
@@ -1,5 +1,5 @@
 If your Linux distribution does not have git-annex packaged up for you,
-you can either build it [[fromscratch]], or you can use a handy
+you can either build it [[fromsource]], or you can use a handy
 prebuilt tarball of the most recent release.
 
 This tarball should work on most Linux systems. It has basically no
diff --git a/doc/install/OSX/porting.mdwn b/doc/install/OSX/porting.mdwn
index 2003af684..7aeb1c12c 100644
--- a/doc/install/OSX/porting.mdwn
+++ b/doc/install/OSX/porting.mdwn
@@ -3,4 +3,5 @@ from eg [[HomeBrew]] or the regular [[OSX]] prebuilt app, you
 can try building git-annex from source on OSX, using haskell's cabal package
 manager.
 
-For general instructions for using cabal, see [[this page|/install/cabal]].
+For general instructions on building git-annex from source see
+[[install/fromsource]]
diff --git a/doc/install/cabal.mdwn b/doc/install/cabal.mdwn
deleted file mode 100644
index 3270dd0f9..000000000
--- a/doc/install/cabal.mdwn
+++ /dev/null
@@ -1,58 +0,0 @@
-As a haskell package, git-annex can be installed using cabal. 
-
-This involves building a lot of haskell packages from source, and so it has
-a lot of moving parts, and it's not uncommon for it to be broken from time
-to time.
-
-If you are not comfortable tracking down and dealing with library build
-problems, installing git-annex with cabal is probably not the right choice
-for you!
-
-## prerequisites
-
-Start by installing the [Haskell Platform][]. In Debian, this is as
-simple as:
-
-    sudo apt-get install haskell-platform
-
- [Haskell Platform]: http://hackage.haskell.org/platform/
-
-## minimal build
-
-This builds git-annex without some features that require C libraries, that
-can be harder to get installed. This is plenty to get started using it,
-although it does not include the assistant or webapp.
-
-	cabal update
-	PATH=$HOME/bin:$PATH
-	cabal install git-annex --bindir=$HOME/bin -f"-assistant -webapp -webdav -pairing -xmpp -dns"
-
-## full build
-
-To build with all features enabled, including the assistant and webapp,
-you will need to install several C libraries and their headers,
-including libgnutls, libgsasl, libxml2, and zlib. Then run:
-
-	cabal update
-	PATH=$HOME/bin:$PATH
-	cabal install c2hs --bindir=$HOME/bin
-	cabal install git-annex --bindir=$HOME/bin
-
-## building from git checkout
-
-But maybe you want something newer (or older). Then [[download]] the version
-you want, and use cabal as follows inside its source tree:
-
-	cabal update
-	PATH=$HOME/bin:$PATH
-	cabal install c2hs --bindir=$HOME/bin
-	cabal install --only-dependencies
-	cabal configure
-	cabal build
-	cabal install --bindir=$HOME/bin
-
-## EKG
-
-When building with cabal, you can optionally enable the 
-[[EKG monitoring interface|ekg]]. This is great for debugging resource
-usage problems.
diff --git a/doc/install/fromscratch.mdwn b/doc/install/fromscratch.mdwn
deleted file mode 100644
index 46ee5a055..000000000
--- a/doc/install/fromscratch.mdwn
+++ /dev/null
@@ -1,27 +0,0 @@
-To install git-annex from scratch, you need a lot of stuff. Really
-quite a lot.
-
-* Haskell stuff
-  * [The Haskell Platform](http://haskell.org/platform/) (GHC 7.4 or newer)
-  * A ton of haskell libraries. Rather than try to list them all here,
-    see git-annex.cabal. Probably the easiest way to install them:
-    `cabal update; cabal install git-annex --only-dependencies`
-* Shell commands
-  * [git](http://git-scm.com/) (1.7.2 or newer; 1.8.5 or newer recommended)
-  * [xargs](http://savannah.gnu.org/projects/findutils/)
-  * [rsync](http://rsync.samba.org/)
-  * [curl](http://http://curl.haxx.se/) (optional, but recommended)
-  * [wget](http://www.gnu.org/software/wget/) (optional)
-  * [sha*sum](ftp://ftp.gnu.org/gnu/coreutils/) (optional)
-  * [gpg](http://gnupg.org/) (optional; needed for encryption)
-  * [lsof](ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/)
-    (optional; recommended for watch mode)
-  * [gcrypt](https://github.com/joeyh/git-remote-gcrypt)
-    (optional)
-  * [nocache](https://github.com/Feh/nocache)
-    (optional)
-  * multicast DNS support, provided on linux by [nss-mdns](http://www.0pointer.de/lennart/projects/nss-mdns/)
-    (optional; recommended for the assistant to support pairing well)
-  * [ikiwiki](http://ikiwiki.info) (optional; used to build the docs)
-
-Then just [[download]] git-annex and run: `make; make install`
diff --git a/doc/install/fromsource.mdwn b/doc/install/fromsource.mdwn
new file mode 100644
index 000000000..baa4e1b06
--- /dev/null
+++ b/doc/install/fromsource.mdwn
@@ -0,0 +1,68 @@
+So you want to build git-annex from source. This is encouraged for
+users with experience building code from source. But the build may
+require some care and feeding. This page will start with the easy
+methods and work up to the harder ones.
+
+## prerequisites
+
+Start by installing the 
+[Haskell Platform](http://hackage.haskell.org/platform/).
+
+In Debian, this is as simple as:
+
+	sudo apt-get install haskell-platform
+
+## downloading the source code
+
+The easiest way is using git; see [[download]] or just:
+
+	git clone git://git-annex.branchable.com/ git-annex
+
+Or, you can use cabal to get the source code:
+
+	cabal update; cabal unpack git-annex
+
+## building from source on Debian
+
+This is the method used by git-annex's author, and so it's the one most
+likely to work without problems.
+
+First, install everything git-annex needs to build:
+
+	sudo apt-get build-dep git-annex
+
+Now you can build git-annex using either `make` or `cabal build`.
+
+## minimal build with cabal
+
+This can be done anywhere, and builds git-annex without some features that
+require C libraries, that can be harder to get installed. This is plenty to
+get started using it, although it does not include the assistant or webapp.
+
+Be warned that this involves building a lot of Haskell libraries from
+source, and so it has a lot of moving parts, and it's not uncommon for it
+to be broken from time to time.
+
+	cabal configure -f"-assistant -webapp -webdav -pairing -xmpp -dns"
+	cabal build
+	PATH=$HOME/bin:$PATH
+	cabal install --bindir=$HOME/bin
+
+## full build with cabal
+
+To build with all features enabled, including the assistant and webapp,
+you will need to install several C libraries and their headers,
+including libgnutls, libgsasl, libxml2, and zlib. How to do that for
+your OS is beyond the scope of this page. Once the C libraries are
+installed:
+
+	cabal configure
+	cabal build
+	PATH=$HOME/bin:$PATH
+	cabal install --bindir=$HOME/bin
+
+## EKG
+
+When building with cabal, you can optionally enable the 
+[[EKG monitoring interface|ekg]]. This is great for debugging resource
+usage problems. Just pass `-f+EKG` to `cabal configure`