move cross compile doc to into build category

docs/_install-and-build/cross-compile.md

@@ -1,21 +1,21 @@
 ---
-title: Cross-compiling Ethereum
+title: Cross-Compiling Geth
 ---
-**Note: All of these and much more have been merged into the project Makefile.
-You can cross build via `make geth-<os>-<platform>` without needing to know any
-of these details from below.**
 
-Developers usually have a preferred platform that they feel most comfortable
+**Note: All of these and much more have been merged into the project Makefile. You can
-working in, with all the necessary tools, libraries and environments set up for
+cross build via `make geth-<os>-<platform>` without needing to know any of these details
-an optimal workflow. However, there's often need to build for either a different
+from below.**
-CPU architecture, or an entirely different operating system; but maintaining a
-development environment for each and switching between the them quickly becomes
-unwieldy.
 
-Here we present a very simple way to cross compile Ethereum to various operating
+Developers usually have a preferred platform that they feel most comfortable working in,
-systems and architectures using a minimal set of prerequisites and a completely
+with all the necessary tools, libraries and environments set up for an optimal workflow.
-containerized approach, guaranteeing that your development environment remains
+However, there's often need to build for either a different CPU architecture, or an
-clean even after the complex requirements and mechanisms of a cross compilation.
+entirely different operating system; but maintaining a development environment for each
+and switching between the them quickly becomes unwieldy.
+
+Here we present a very simple way to cross compile Ethereum to various operating systems
+and architectures using a minimal set of prerequisites and a completely containerized
+approach, guaranteeing that your development environment remains clean even after the
+complex requirements and mechanisms of a cross compilation.
 
 The currently supported target platforms are:
 
@@ -24,28 +24,27 @@ The currently supported target platforms are:
  - 32 bit and 64 bit Mac OSX
  - 32 bit and 64 bit Windows
 
-Please note, that cross compilation does not replace a release build. Although
+Please note, that cross compilation does not replace a release build. Although resulting
-resulting binaries can usually run perfectly on the desired platform, compiling
+binaries can usually run perfectly on the desired platform, compiling on a native system
-on a native system with the specialized tools provided by the official vendor
+with the specialized tools provided by the official vendor can often result in more a
-can often result in more a finely optimized code.
+finely optimized code.
 
 ## Cross compilation environment
 
-Although the `go-ethereum` project is written in Go, it does include a bit of C
+Although the `go-ethereum` project is written in Go, it does include a bit of C code
-code shared between all implementations to ensure that all perform equally well,
+shared between all implementations to ensure that all perform equally well, including a
-including a dependency to the GNU Multiple Precision Arithmetic Library. Because
+dependency to the GNU Multiple Precision Arithmetic Library. Because of these, Go cannot
-of these, Go cannot by itself compile to a different platform than the host. To
+by itself compile to a different platform than the host. To overcome this limitation, we
-overcome this limitation, we will use [`xgo`](https://github.com/karalabe/xgo),
+will use [`xgo`](https://github.com/karalabe/xgo), a Go cross compiler package based on
-a Go cross compiler package based on Docker containers that has been architected
+Docker containers that has been architected specifically to allow both embedded C snippets
-specifically to allow both embedded C snippets as well as simpler external C
+as well as simpler external C dependencies during compilation.
-dependencies during compilation.
 
 The `xgo` project has two simple dependencies: Docker (to ensure that the build
-environment is completely contained) and Go. On most platforms these should be
+environment is completely contained) and Go. On most platforms these should be available
-available from the official package repositories. For manually installing them,
+from the official package repositories. For manually installing them, please consult their
-please consult their install guides at [Docker](https://docs.docker.com/installation/)
+install guides at [Docker](https://docs.docker.com/installation/) and
-and [Go](https://golang.org/doc/install) respectively. This guide assumes that these
+[Go](https://golang.org/doc/install) respectively. This guide assumes that these two
-two dependencies are met.
+dependencies are met.
 
 To install and/or update xgo, simply type:
 
@@ -70,8 +69,8 @@ compile itself and verifying that all cross compilations succeeded or not.
 
 ## Building Ethereum
 
-Cross compiling Ethereum is analogous to the above example, but an additional
+Cross compiling Ethereum is analogous to the above example, but an additional flags is
-flags is required to satisfy the dependencies:
+required to satisfy the dependencies:
 
  - `--deps` is used to inject arbitrary C dependency packages and pre-build them
 
@@ -92,38 +91,38 @@ Injecting the GNU Arithmetic Library dependency and selecting `geth` would be:
     -rwxr-xr-x  1 root     root     19418071 Sep 14 17:59 geth-windows-amd64.exe
 
 
-As the cross compiler needs to build all the dependencies as well as the main
+As the cross compiler needs to build all the dependencies as well as the main project
-project itself for each platform, it may take a while for the build to complete
+itself for each platform, it may take a while for the build to complete (approximately 3-4
-(approximately 3-4 minutes on a Core i7 3770K machine).
+minutes on a Core i7 3770K machine).
 
 ### Fine tuning the build
 
-By default Go, and inherently `xgo`, checks out and tries to build the master
+By default Go, and inherently `xgo`, checks out and tries to build the master branch of a
-branch of a source repository. However, more often than not, you'll probably
+source repository. However, more often than not, you'll probably want to build a different
-want to build a different branch from possibly an entirely different remote
+branch from possibly an entirely different remote repository. These can be controlled via
-repository. These can be controlled via the `--remote` and `--branch` flags.
+the `--remote` and `--branch` flags.
 
-To build the `develop` branch of the official `go-ethereum` repository instead
+To build the `develop` branch of the official `go-ethereum` repository instead of the
-of the default `master` branch, you just need to specify it as an additional
+default `master` branch, you just need to specify it as an additional command line flag
-command line flag (`--branch`):
+(`--branch`):
 
     $ xgo --deps=https://gmplib.org/download/gmp/gmp-6.0.0a.tar.bz2 \
           --branch=develop                                          \
           github.com/ethereum/go-ethereum/cmd/geth
 
-Additionally, during development you will most probably want to not only build
+Additionally, during development you will most probably want to not only build a custom
-a custom branch, but also one originating from your own fork of the repository
+branch, but also one originating from your own fork of the repository instead of the
-instead of the upstream one. This can be done via the `--remote` flag:
+upstream one. This can be done via the `--remote` flag:
 
     $ xgo --deps=https://gmplib.org/download/gmp/gmp-6.0.0a.tar.bz2 \
           --remote=https://github.com/karalabe/go-ethereum          \
           --branch=rpi-staging                                      \
           github.com/ethereum/go-ethereum/cmd/geth
 
-By default `xgo` builds binaries for all supported platforms and architectures,
+By default `xgo` builds binaries for all supported platforms and architectures, with
-with Android binaries defaulting to the highest released Android NDK platform.
+Android binaries defaulting to the highest released Android NDK platform. To limit the
-To limit the build targets or compile to a different Android platform, use the
+build targets or compile to a different Android platform, use the `--targets` CLI
-`--targets` CLI parameter.
+parameter.
 
     $ xgo --deps=https://gmplib.org/download/gmp/gmp-6.0.0a.tar.bz2 \
           --targets=android-16/arm,windows/*                        \
@@ -131,20 +130,20 @@ To limit the build targets or compile to a different Android platform, use the
 
 ### Building locally
 
-If you would like to cross compile your local development version, simply specify
+If you would like to cross compile your local development version, simply specify a local
-a local path (starting with `.` or `/`), and `xgo` will use all local code from
+path (starting with `.` or `/`), and `xgo` will use all local code from `GOPATH`, only
-`GOPATH`, only downloading missing dependencies. In such a case of course, the
+downloading missing dependencies. In such a case of course, the `--branch`, `--remote` and
-`--branch`, `--remote` and `--pkg` arguments are no-op:
+`--pkg` arguments are no-op:
 
     $ xgo --deps=https://gmplib.org/download/gmp/gmp-6.0.0a.tar.bz2 \
           ./cmd/geth
 
 ## Using the Makefile
 
-Having understood the gist of `xgo` based cross compilation, you do not need to
+Having understood the gist of `xgo` based cross compilation, you do not need to actually
-actually memorize and maintain these commands, as they have been incorporated into
+memorize and maintain these commands, as they have been incorporated into the official
-the official [Makefile](https://github.com/ethereum/go-ethereum/blob/master/Makefile)
+[Makefile](https://github.com/ethereum/go-ethereum/blob/master/Makefile) and can be
-and can be invoked with a trivial `make` request:
+invoked with a trivial `make` request:
 
  * `make geth-cross`: Cross compiles to every supported OS and architecture
  * `make geth-<os>`: Cross compiles supported architectures of a particular OS (e.g. `linux`)
@@ -163,5 +162,5 @@ fancier mechanics.
  - `make ... GO=<go>`: Use a specific Go runtime (e.g. `1.5.1`, `1.5-develop`, `develop`)
  - `make ... MODE=<mode>`: Build a specific target type (e.g. `exe`, `c-archive`).
 
-Please note that these are not yet fully finalized, so they may or may not change in
+Please note that these are not yet fully finalized, so they may or may not change in the
-the future as our code and the Go runtime features change.
+future as our code and the Go runtime features change.