From 9ef7b2f4aa9b8cb20a497e627e31b73b8b4d1169 Mon Sep 17 00:00:00 2001
From: Behnam Esfahbod <behnam@zwnj.org>
Date: Thu, 31 Aug 2017 12:22:24 -0700
Subject: [PATCH 1/8] [doc/book] Expand installation.md

Import install text and links from <https://crates.io/install>, as we
want to drop that page and redirect it to here.

See <https://github.com/rust-lang/crates.io/issues/1029>
---
 src/doc/book/src/01-01-installation.md | 35 +++++++++++++++++++-------
 1 file changed, 26 insertions(+), 9 deletions(-)

diff --git a/src/doc/book/src/01-01-installation.md b/src/doc/book/src/01-01-installation.md
index 9f9052344cc..8428a9063f0 100644
--- a/src/doc/book/src/01-01-installation.md
+++ b/src/doc/book/src/01-01-installation.md
@@ -1,21 +1,38 @@
 ## Installation
 
-The easiest way to get Cargo is to get the current stable release of Rust by
+### Install Stable Rust and Cargo
+
+The easiest way to get Cargo is to get the current stable release of [Rust] by
 using the `rustup` script:
 
 ```shell
 $ curl -sSf https://static.rust-lang.org/rustup.sh | sh
 ```
 
-This will get you the current stable release of Rust for your platform along
-with the latest Cargo.
+After this, you can use the `rustup` command to also install `beta` or `nightly`
+channels for Rust and Cargo.
+
+### Install Nightly Cargo
+
+To install just Cargo, the current recommended installation method is through
+the official nightly builds. Note that Cargo will also require that [Rust] is
+already installed on the system.
 
-If you are on Windows, you can directly download the latest stable Rust and nightly Cargo:
+| Platform         | 64-bit            | 32-bit            |
+|------------------|-------------------|-------------------|
+| Linux binaries   | [tar.gz][linux64] | [tar.gz][linux32] |
+| MacOS binaries   | [tar.gz][mac64]   | [tar.gz][mac32]   |
+| Windows binaries | [tar.gz][win64]   | [tar.gz][win32]   |
 
-- [Rust (32-bit)](https://static.rust-lang.org/dist/rust-1.17.0-i686-pc-windows-gnu.msi)
-- [Cargo (32-bit)](https://static.rust-lang.org/cargo-dist/cargo-nightly-i686-pc-windows-gnu.tar.gz)
+### Build and Install Cargo from Source
 
-- [Rust (64-bit)](https://static.rust-lang.org/dist/rust-1.17.0-x86_64-pc-windows-gnu.msi)
-- [Cargo (64-bit)](https://static.rust-lang.org/cargo-dist/cargo-nightly-x86_64-pc-windows-gnu.tar.gz)
+Alternatively, you can [build Cargo from source][compiling-from-source].
 
-Alternatively, you can [build Cargo from source](https://github.com/rust-lang/cargo#compiling-from-source).
+[rust]: https://www.rust-lang.org/
+[linux64]: https://static.rust-lang.org/cargo-dist/cargo-nightly-x86_64-unknown-linux-gnu.tar.gz
+[linux32]: https://static.rust-lang.org/cargo-dist/cargo-nightly-i686-unknown-linux-gnu.tar.gz
+[mac64]: https://static.rust-lang.org/cargo-dist/cargo-nightly-x86_64-apple-darwin.tar.gz
+[mac32]: https://static.rust-lang.org/cargo-dist/cargo-nightly-i686-apple-darwin.tar.gz
+[win64]: https://static.rust-lang.org/cargo-dist/cargo-nightly-x86_64-pc-windows-gnu.tar.gz
+[win32]: https://static.rust-lang.org/cargo-dist/cargo-nightly-i686-pc-windows-gnu.tar.gz
+[compiling-from-source]: https://github.com/rust-lang/cargo#compiling-from-source

From 63f37e3f179f585e2c2fe79f954ab9dea3b12f31 Mon Sep 17 00:00:00 2001
From: Behnam Esfahbod <behnam@zwnj.org>
Date: Thu, 31 Aug 2017 01:04:54 -0700
Subject: [PATCH 2/8] [src/doc/book] Add introduction page

---
 src/doc/book/src/01-02-first-steps.md |  2 +-
 src/doc/book/src/SUMMARY.md           |  4 ++-
 src/doc/book/src/cargo-in-depth.md    |  9 ++---
 src/doc/book/src/getting-started.md   |  2 ++
 src/doc/book/src/guide.md             | 12 +++----
 src/doc/book/src/introduction.md      | 51 +++++++++++++++++++++++++++
 6 files changed, 66 insertions(+), 14 deletions(-)
 create mode 100644 src/doc/book/src/introduction.md

diff --git a/src/doc/book/src/01-02-first-steps.md b/src/doc/book/src/01-02-first-steps.md
index 25d36f96b93..097f3455d45 100644
--- a/src/doc/book/src/01-02-first-steps.md
+++ b/src/doc/book/src/01-02-first-steps.md
@@ -65,6 +65,6 @@ $ cargo run
 Hello, world!
 ```
 
-## Going further
+### Going further
 
 For more details on using Cargo, check out the [Cargo Guide](guide.html)
diff --git a/src/doc/book/src/SUMMARY.md b/src/doc/book/src/SUMMARY.md
index 21e8c151c13..ab4028d2ff2 100644
--- a/src/doc/book/src/SUMMARY.md
+++ b/src/doc/book/src/SUMMARY.md
@@ -1,5 +1,7 @@
 # Summary
 
+[Introduction](introduction.md)
+
 * [Getting Started](getting-started.md)
     * [Installation](01-01-installation.md)
     * [First Steps with Cargo](01-02-first-steps.md)
@@ -26,4 +28,4 @@
     * [External Tools](03-09-external-tools.md)
     * [Policies](03-10-policies.md)
 
-* [FAQ](faq.md)
+[FAQ](faq.md)
diff --git a/src/doc/book/src/cargo-in-depth.md b/src/doc/book/src/cargo-in-depth.md
index e73c9cdbf10..b367ccba3dd 100644
--- a/src/doc/book/src/cargo-in-depth.md
+++ b/src/doc/book/src/cargo-in-depth.md
@@ -1,17 +1,14 @@
 ## Cargo In Depth
 
-Now that you have an overview of how to use cargo and have created your first
-crate, you may be interested in:
+Now that you have an overview of how to use Cargo and have created your first
+crate, you may be interested in more details in the following areas.
 
-* [Publishing your crate on crates.io](03-06-crates-io.html)
 * [Reading about all the possible ways of specifying dependencies](03-01-specifying-dependencies.html)
 * [Learning more details about what you can specify in your `Cargo.toml` manifest](03-02-manifest.html)
-* [Specifying Dependencies](03-01-specifying-dependencies.html)
-* [Cargo.toml Format](03-02-manifest.html)
 * [Configuration](03-03-config.html)
 * [Environment Variables](03-04-environment-variables.html)
 * [Build Scripts](03-05-build-scripts.html)
-* [Publishing on crates.io](03-06-crates-io.html)
+* [Publishing your crate on crates.io](03-06-crates-io.html)
 * [Package ID specs](03-07-pkgid-spec.html)
 * [Source Replacement](03-08-source-replacement.html)
 * [External Tools](03-09-external-tools.html)
diff --git a/src/doc/book/src/getting-started.md b/src/doc/book/src/getting-started.md
index 7865c4e9496..89c69a755fc 100644
--- a/src/doc/book/src/getting-started.md
+++ b/src/doc/book/src/getting-started.md
@@ -1,4 +1,6 @@
 ## Getting Started
 
+To get started with Cargo, install Cargo (and Rust) and set up your first crate.
+
 * [Installation](01-01-installation.html)
 * [First steps with Cargo](01-02-first-steps.html)
diff --git a/src/doc/book/src/guide.md b/src/doc/book/src/guide.md
index 704f87b8acf..7e8ecaedbd8 100644
--- a/src/doc/book/src/guide.md
+++ b/src/doc/book/src/guide.md
@@ -1,13 +1,13 @@
 ## Cargo Guide
 
-Welcome to the Cargo guide. This guide will give you all that you need to know
-about how to use Cargo to develop Rust projects.
+This guide will give you all that you need to know about how to use Cargo to
+develop Rust projects.
 
-* [Why Cargo exists](02-01-why-cargo-exists.html)
-* [Creating a new project](02-02-creating-a-new-project.html)
-* [Working on an existing Cargo project](02-03-working-on-an-existing-project.html)
+* [Why Cargo Exists](02-01-why-cargo-exists.html)
+* [Creating a New Project](02-02-creating-a-new-project.html)
+* [Working on an Existing Cargo Project](02-03-working-on-an-existing-project.html)
 * [Dependencies](02-04-dependencies.html)
-* [Project layout](02-05-project-layout.html)
+* [Project Layout](02-05-project-layout.html)
 * [Cargo.toml vs Cargo.lock](02-06-cargo-toml-vs-cargo-lock.html)
 * [Tests](02-07-tests.html)
 * [Continuous Integration](02-08-continuous-integration.html)
diff --git a/src/doc/book/src/introduction.md b/src/doc/book/src/introduction.md
new file mode 100644
index 00000000000..850ede20ebd
--- /dev/null
+++ b/src/doc/book/src/introduction.md
@@ -0,0 +1,51 @@
+# The Cargo Manual
+
+![Cargo Logo](images/Cargo-Logo-Small.png)
+
+Cargo is the [Rust] *package manager*. Cargo downloads your Rust project’s
+dependencies, compiles your project, makes packages, and upload them to
+[crates.io], the Rust *package registry*.
+
+
+## [Getting Started](getting-started.html)
+
+To get started with Cargo, install Cargo (and Rust) and set up your first crate.
+
+* [Installation](01-01-installation.html)
+* [First Steps with Cargo](01-02-first-steps.html)
+
+## [Cargo Guide](guide.html)
+
+The guide will give you all you need to know about how to use Cargo to develop
+Rust projects.
+
+* [Why Cargo exists](02-01-why-cargo-exists.html)
+* [Creating a new project](02-02-creating-a-new-project.html)
+* [Working on an existing Cargo
+    project](02-03-working-on-an-existing-project.html)
+* [Dependencies](02-04-dependencies.html)
+* [Project layout](02-05-project-layout.html)
+* [Cargo.toml vs Cargo.lock](02-06-cargo-toml-vs-cargo-lock.html)
+* [Tests](02-07-tests.html)
+* [Continuous Integration](02-08-continuous-integration.html)
+
+## [Cargo In Depth](cargo-in-depth.html)
+
+After having an overview of how to use Cargo and have created your first crate,
+you may be interested in more details in the following areas.
+
+* [Specifying Dependencies](03-01-specifying-dependencies.html)
+* [Cargo.toml Format](03-02-manifest.html)
+* [Configuration](03-03-config.html)
+* [Environment Variables](03-04-environment-variables.html)
+* [Build Scripts](03-05-build-scripts.html)
+* [Publishing on crates.io](03-06-crates-io.html)
+* [Package ID specs](03-07-pkgid-spec.html)
+* [Source Replacement](03-08-source-replacement.html)
+* [External Tools](03-09-external-tools.html)
+* [Policies](03-10-policies.html)
+
+## [Frequently Asked Questions](faq.html)
+
+[rust]: https://www.rust-lang.org/
+[crates.io]: https://crates.io/

From 79d10021e7cfd1e6fe3cce755a3812c59b6868a9 Mon Sep 17 00:00:00 2001
From: Behnam Esfahbod <behnam@zwnj.org>
Date: Thu, 31 Aug 2017 12:53:55 -0700
Subject: [PATCH 3/8] [doc/book] Improve page titles

---
 src/doc/book/src/03-02-manifest.md           |  3 +++
 src/doc/book/src/03-05-build-scripts.md      |  2 +-
 src/doc/book/src/03-08-source-replacement.md |  2 +-
 src/doc/book/src/03-10-policies.md           |  2 +-
 src/doc/book/src/SUMMARY.md                  |  6 +++---
 src/doc/book/src/cargo-in-depth.md           | 14 +++++++-------
 6 files changed, 16 insertions(+), 13 deletions(-)

diff --git a/src/doc/book/src/03-02-manifest.md b/src/doc/book/src/03-02-manifest.md
index a5d25e77bd4..2b2367ad662 100644
--- a/src/doc/book/src/03-02-manifest.md
+++ b/src/doc/book/src/03-02-manifest.md
@@ -1,5 +1,8 @@
 ## The Manifest Format
 
+The `Cargo.toml` file for each package is called its *manifest*. Every manifest
+file consists of one or more sections.
+
 ### The `[package]` section
 
 The first section in a `Cargo.toml` is `[package]`.
diff --git a/src/doc/book/src/03-05-build-scripts.md b/src/doc/book/src/03-05-build-scripts.md
index 9b7367c4c55..6d775ed1bf6 100644
--- a/src/doc/book/src/03-05-build-scripts.md
+++ b/src/doc/book/src/03-05-build-scripts.md
@@ -1,4 +1,4 @@
-## Build Script Support
+## Build Scripts
 
 Some packages need to compile third-party non-Rust code, for example C
 libraries. Other packages need to link to C libraries which can either be
diff --git a/src/doc/book/src/03-08-source-replacement.md b/src/doc/book/src/03-08-source-replacement.md
index dcb88346d02..8407bc0e679 100644
--- a/src/doc/book/src/03-08-source-replacement.md
+++ b/src/doc/book/src/03-08-source-replacement.md
@@ -1,4 +1,4 @@
-## Replacing sources
+## Source Replacement
 
 Cargo supports the ability to **replace one source with another** to express
 strategies along the lines of mirrors or vendoring dependencies. Configuration
diff --git a/src/doc/book/src/03-10-policies.md b/src/doc/book/src/03-10-policies.md
index f6565d305ad..9d48d095f9e 100644
--- a/src/doc/book/src/03-10-policies.md
+++ b/src/doc/book/src/03-10-policies.md
@@ -1,4 +1,4 @@
-## Crates.io package policies
+## Crates.io Package Policies
 
 In general, these policies are guidelines. Problems are often contextual, and
 exceptional circumstances sometimes require exceptional measures. We plan to
diff --git a/src/doc/book/src/SUMMARY.md b/src/doc/book/src/SUMMARY.md
index ab4028d2ff2..b5b7dd30674 100644
--- a/src/doc/book/src/SUMMARY.md
+++ b/src/doc/book/src/SUMMARY.md
@@ -18,14 +18,14 @@
 
 * [Cargo In Depth](cargo-in-depth.md)
     * [Specifying Dependencies](03-01-specifying-dependencies.md)
-    * [Cargo.toml Format](03-02-manifest.md)
+    * [The Manifest Format](03-02-manifest.md)
     * [Configuration](03-03-config.md)
     * [Environment Variables](03-04-environment-variables.md)
     * [Build Scripts](03-05-build-scripts.md)
     * [Publishing on crates.io](03-06-crates-io.md)
-    * [Package ID specs](03-07-pkgid-spec.md)
+    * [Package ID Specifications](03-07-pkgid-spec.md)
     * [Source Replacement](03-08-source-replacement.md)
     * [External Tools](03-09-external-tools.md)
-    * [Policies](03-10-policies.md)
+    * [Crates.io Package Policies](03-10-policies.md)
 
 [FAQ](faq.md)
diff --git a/src/doc/book/src/cargo-in-depth.md b/src/doc/book/src/cargo-in-depth.md
index b367ccba3dd..e4a749fee9a 100644
--- a/src/doc/book/src/cargo-in-depth.md
+++ b/src/doc/book/src/cargo-in-depth.md
@@ -5,11 +5,11 @@ crate, you may be interested in more details in the following areas.
 
 * [Reading about all the possible ways of specifying dependencies](03-01-specifying-dependencies.html)
 * [Learning more details about what you can specify in your `Cargo.toml` manifest](03-02-manifest.html)
-* [Configuration](03-03-config.html)
-* [Environment Variables](03-04-environment-variables.html)
-* [Build Scripts](03-05-build-scripts.html)
+* [Learn how Cargo's Configuration system works](03-03-config.html)
+* [Environment Variables that Cargo sets and reads](03-04-environment-variables.html)
+* [Build Script Support](03-05-build-scripts.html)
 * [Publishing your crate on crates.io](03-06-crates-io.html)
-* [Package ID specs](03-07-pkgid-spec.html)
-* [Source Replacement](03-08-source-replacement.html)
-* [External Tools](03-09-external-tools.html)
-* [Policies](03-10-policies.html)
+* [Package ID Specifications](03-07-pkgid-spec.html)
+* [Learn how to replace one source with another](03-08-source-replacement.html)
+* [Integration with external tools, like IDEs and other build systems](03-09-external-tools.html)
+* [Crates.io Package Policies](03-10-policies.html)

From 3f2d93e3b04a3ad9b59cdd37b30de8347aa4ab35 Mon Sep 17 00:00:00 2001
From: Behnam Esfahbod <behnam@zwnj.org>
Date: Thu, 31 Aug 2017 13:17:19 -0700
Subject: [PATCH 4/8] [doc/book] Create dir for book sections

---
 src/doc/MIGRATION_MAP                         | 24 +++++-----
 src/doc/book/src/SUMMARY.md                   | 44 +++++++++----------
 src/doc/book/src/cargo-in-depth.md            | 15 -------
 src/doc/book/src/faq.md                       |  8 ++--
 src/doc/book/src/getting-started.md           |  4 +-
 .../first-steps.md}                           |  0
 .../installation.md}                          |  0
 src/doc/book/src/guide.md                     | 16 +++----
 .../cargo-toml-vs-cargo-lock.md}              |  2 +-
 .../continuous-integration.md}                |  0
 .../creating-a-new-project.md}                |  0
 .../dependencies.md}                          |  2 +-
 .../project-layout.md}                        |  4 +-
 .../src/{02-07-tests.md => guide/tests.md}    |  0
 .../why-cargo-exists.md}                      |  0
 .../working-on-an-existing-project.md}        |  0
 src/doc/book/src/introduction.md              | 42 +++++++++---------
 src/doc/book/src/reference.md                 | 15 +++++++
 .../build-scripts.md}                         |  4 +-
 .../{03-03-config.md => reference/config.md}  |  4 +-
 .../crates-io.md}                             |  4 +-
 .../environment-variables.md}                 |  6 +--
 .../external-tools.md}                        |  0
 .../manifest.md}                              |  8 ++--
 .../pkgid-spec.md}                            |  0
 .../policies.md}                              |  0
 .../source-replacement.md}                    |  4 +-
 .../specifying-dependencies.md}               |  6 +--
 28 files changed, 106 insertions(+), 106 deletions(-)
 delete mode 100644 src/doc/book/src/cargo-in-depth.md
 rename src/doc/book/src/{01-02-first-steps.md => getting-started/first-steps.md} (100%)
 rename src/doc/book/src/{01-01-installation.md => getting-started/installation.md} (100%)
 rename src/doc/book/src/{02-06-cargo-toml-vs-cargo-lock.md => guide/cargo-toml-vs-cargo-lock.md} (97%)
 rename src/doc/book/src/{02-08-continuous-integration.md => guide/continuous-integration.md} (100%)
 rename src/doc/book/src/{02-02-creating-a-new-project.md => guide/creating-a-new-project.md} (100%)
 rename src/doc/book/src/{02-04-dependencies.md => guide/dependencies.md} (96%)
 rename src/doc/book/src/{02-05-project-layout.md => guide/project-layout.md} (97%)
 rename src/doc/book/src/{02-07-tests.md => guide/tests.md} (100%)
 rename src/doc/book/src/{02-01-why-cargo-exists.md => guide/why-cargo-exists.md} (100%)
 rename src/doc/book/src/{02-03-working-on-an-existing-project.md => guide/working-on-an-existing-project.md} (100%)
 create mode 100644 src/doc/book/src/reference.md
 rename src/doc/book/src/{03-05-build-scripts.md => reference/build-scripts.md} (99%)
 rename src/doc/book/src/{03-03-config.md => reference/config.md} (98%)
 rename src/doc/book/src/{03-06-crates-io.md => reference/crates-io.md} (98%)
 rename src/doc/book/src/{03-04-environment-variables.md => reference/environment-variables.md} (97%)
 rename src/doc/book/src/{03-09-external-tools.md => reference/external-tools.md} (100%)
 rename src/doc/book/src/{03-02-manifest.md => reference/manifest.md} (99%)
 rename src/doc/book/src/{03-07-pkgid-spec.md => reference/pkgid-spec.md} (100%)
 rename src/doc/book/src/{03-10-policies.md => reference/policies.md} (100%)
 rename src/doc/book/src/{03-08-source-replacement.md => reference/source-replacement.md} (98%)
 rename src/doc/book/src/{03-01-specifying-dependencies.md => reference/specifying-dependencies.md} (98%)

diff --git a/src/doc/MIGRATION_MAP b/src/doc/MIGRATION_MAP
index c239954e23b..bbcdcf28697 100644
--- a/src/doc/MIGRATION_MAP
+++ b/src/doc/MIGRATION_MAP
@@ -1,13 +1,13 @@
-build-script.md book/src/03-05-build-scripts.md
-config.md book/src/03-03-config.md
-crates-io.md book/src/03-06-crates-io.md
-environment-variables.md book/src/03-04-environment-variables.md
-external-tools.md book/src/03-09-external-tools.md
+index.md book/src/SUMMARY.md book/src/getting-started.md book/src/getting-started/*.md
+guide.md book/src/guide.md book/src/guide/*.md
+build-script.md book/src/reference/build-scripts.md
+config.md book/src/reference/config.md
+crates-io.md book/src/reference/crates-io.md
+environment-variables.md book/src/reference/environment-variables.md
+external-tools.md book/src/reference/external-tools.md
+manifest.md book/src/reference/manifest.md
+pkgid-spec.md book/src/reference/pkgid-spec.md
+policies.md book/src/reference/policies.md
+source-replacement.md book/src/reference/source-replacement.md
+specifying-dependencies.md book/src/reference/specifying-dependencies.md
 faq.md book/src/faq.md
-guide.md book/src/guide.md book/src/02-*.md
-index.md book/src/SUMMARY.md book/src/01-*.md
-manifest.md book/src/03-02-manifest.md
-pkgid-spec.md book/src/03-07-pkgid-spec.md
-policies.md book/src/03-10-policies.md
-source-replacement.md book/src/03-08-source-replacement.md
-specifying-dependencies.md book/src/03-01-specifying-dependencies.md
diff --git a/src/doc/book/src/SUMMARY.md b/src/doc/book/src/SUMMARY.md
index b5b7dd30674..74e7aae5510 100644
--- a/src/doc/book/src/SUMMARY.md
+++ b/src/doc/book/src/SUMMARY.md
@@ -3,29 +3,29 @@
 [Introduction](introduction.md)
 
 * [Getting Started](getting-started.md)
-    * [Installation](01-01-installation.md)
-    * [First Steps with Cargo](01-02-first-steps.md)
+    * [Installation](getting-started/installation.md)
+    * [First Steps with Cargo](getting-started/first-steps.md)
 
 * [Cargo Guide](guide.md)
-    * [Why Cargo Exists](02-01-why-cargo-exists.md)
-    * [Creating a New Project](02-02-creating-a-new-project.md)
-    * [Working on an Existing Project](02-03-working-on-an-existing-project.md)
-    * [Dependencies](02-04-dependencies.md)
-    * [Project Layout](02-05-project-layout.md)
-    * [Cargo.toml vs Cargo.lock](02-06-cargo-toml-vs-cargo-lock.md)
-    * [Tests](02-07-tests.md)
-    * [Continuous Integration](02-08-continuous-integration.md)
+    * [Why Cargo Exists](guide/why-cargo-exists.md)
+    * [Creating a New Project](guide/creating-a-new-project.md)
+    * [Working on an Existing Project](guide/working-on-an-existing-project.md)
+    * [Dependencies](guide/dependencies.md)
+    * [Project Layout](guide/project-layout.md)
+    * [Cargo.toml vs Cargo.lock](guide/cargo-toml-vs-cargo-lock.md)
+    * [Tests](guide/tests.md)
+    * [Continuous Integration](guide/continuous-integration.md)
 
-* [Cargo In Depth](cargo-in-depth.md)
-    * [Specifying Dependencies](03-01-specifying-dependencies.md)
-    * [The Manifest Format](03-02-manifest.md)
-    * [Configuration](03-03-config.md)
-    * [Environment Variables](03-04-environment-variables.md)
-    * [Build Scripts](03-05-build-scripts.md)
-    * [Publishing on crates.io](03-06-crates-io.md)
-    * [Package ID Specifications](03-07-pkgid-spec.md)
-    * [Source Replacement](03-08-source-replacement.md)
-    * [External Tools](03-09-external-tools.md)
-    * [Crates.io Package Policies](03-10-policies.md)
+* [Cargo Reference](reference.md)
+    * [Specifying Dependencies](reference/specifying-dependencies.md)
+    * [The Manifest Format](reference/manifest.md)
+    * [Configuration](reference/config.md)
+    * [Environment Variables](reference/environment-variables.md)
+    * [Build Scripts](reference/build-scripts.md)
+    * [Publishing on crates.io](reference/crates-io.md)
+    * [Package ID Specifications](reference/pkgid-spec.md)
+    * [Source Replacement](reference/source-replacement.md)
+    * [External Tools](reference/external-tools.md)
+    * [Crates.io Package Policies](reference/policies.md)
 
-[FAQ](faq.md)
+* [FAQ](faq.md)
diff --git a/src/doc/book/src/cargo-in-depth.md b/src/doc/book/src/cargo-in-depth.md
deleted file mode 100644
index e4a749fee9a..00000000000
--- a/src/doc/book/src/cargo-in-depth.md
+++ /dev/null
@@ -1,15 +0,0 @@
-## Cargo In Depth
-
-Now that you have an overview of how to use Cargo and have created your first
-crate, you may be interested in more details in the following areas.
-
-* [Reading about all the possible ways of specifying dependencies](03-01-specifying-dependencies.html)
-* [Learning more details about what you can specify in your `Cargo.toml` manifest](03-02-manifest.html)
-* [Learn how Cargo's Configuration system works](03-03-config.html)
-* [Environment Variables that Cargo sets and reads](03-04-environment-variables.html)
-* [Build Script Support](03-05-build-scripts.html)
-* [Publishing your crate on crates.io](03-06-crates-io.html)
-* [Package ID Specifications](03-07-pkgid-spec.html)
-* [Learn how to replace one source with another](03-08-source-replacement.html)
-* [Integration with external tools, like IDEs and other build systems](03-09-external-tools.html)
-* [Crates.io Package Policies](03-10-policies.html)
diff --git a/src/doc/book/src/faq.md b/src/doc/book/src/faq.md
index f2da9f39717..7f13573fdc6 100644
--- a/src/doc/book/src/faq.md
+++ b/src/doc/book/src/faq.md
@@ -50,7 +50,7 @@ Cargo handles compiling Rust code, but we know that many Rust projects
 link against C code. We also know that there are decades of tooling
 built up around compiling languages other than Rust.
 
-Our solution: Cargo allows a package to [specify a script](03-05-build-scripts.html)
+Our solution: Cargo allows a package to [specify a script](reference/build-scripts.html)
 (written in Rust) to run before invoking `rustc`. Rust is leveraged to
 implement platform-specific configuration and refactor out common build
 functionality among packages.
@@ -74,7 +74,7 @@ on the platform. Cargo also supports [platform-specific
 dependencies][target-deps], and we plan to support more per-platform
 configuration in `Cargo.toml` in the future.
 
-[target-deps]: 03-02-manifest.html#the-dependencies-section
+[target-deps]: reference/manifest.html#the-dependencies-section
 
 In the longer-term, we’re looking at ways to conveniently cross-compile
 projects using Cargo.
@@ -83,7 +83,7 @@ projects using Cargo.
 
 We support environments through the use of [profiles][profile] to support:
 
-[profile]: 03-02-manifest.html#the-profile-sections
+[profile]: reference/manifest.html#the-profile-sections
 
 * environment-specific flags (like `-g --opt-level=0` for development
   and `--opt-level=3` for production).
@@ -190,4 +190,4 @@ shouldn't be necessary.
 For more information about vendoring, see documentation on [source
 replacement][replace].
 
-[replace]: 03-08-source-replacement.html
+[replace]: reference/source-replacement.html
diff --git a/src/doc/book/src/getting-started.md b/src/doc/book/src/getting-started.md
index 89c69a755fc..22a7315cf11 100644
--- a/src/doc/book/src/getting-started.md
+++ b/src/doc/book/src/getting-started.md
@@ -2,5 +2,5 @@
 
 To get started with Cargo, install Cargo (and Rust) and set up your first crate.
 
-* [Installation](01-01-installation.html)
-* [First steps with Cargo](01-02-first-steps.html)
+* [Installation](getting-started/installation.html)
+* [First steps with Cargo](getting-started/first-steps.html)
diff --git a/src/doc/book/src/01-02-first-steps.md b/src/doc/book/src/getting-started/first-steps.md
similarity index 100%
rename from src/doc/book/src/01-02-first-steps.md
rename to src/doc/book/src/getting-started/first-steps.md
diff --git a/src/doc/book/src/01-01-installation.md b/src/doc/book/src/getting-started/installation.md
similarity index 100%
rename from src/doc/book/src/01-01-installation.md
rename to src/doc/book/src/getting-started/installation.md
diff --git a/src/doc/book/src/guide.md b/src/doc/book/src/guide.md
index 7e8ecaedbd8..d8bfda17c86 100644
--- a/src/doc/book/src/guide.md
+++ b/src/doc/book/src/guide.md
@@ -3,11 +3,11 @@
 This guide will give you all that you need to know about how to use Cargo to
 develop Rust projects.
 
-* [Why Cargo Exists](02-01-why-cargo-exists.html)
-* [Creating a New Project](02-02-creating-a-new-project.html)
-* [Working on an Existing Cargo Project](02-03-working-on-an-existing-project.html)
-* [Dependencies](02-04-dependencies.html)
-* [Project Layout](02-05-project-layout.html)
-* [Cargo.toml vs Cargo.lock](02-06-cargo-toml-vs-cargo-lock.html)
-* [Tests](02-07-tests.html)
-* [Continuous Integration](02-08-continuous-integration.html)
+* [Why Cargo Exists](guide/why-cargo-exists.html)
+* [Creating a New Project](guide/creating-a-new-project.html)
+* [Working on an Existing Cargo Project](guide/working-on-an-existing-project.html)
+* [Dependencies](guide/dependencies.html)
+* [Project Layout](guide/project-layout.html)
+* [Cargo.toml vs Cargo.lock](guide/cargo-toml-vs-cargo-lock.html)
+* [Tests](guide/tests.html)
+* [Continuous Integration](guide/continuous-integration.html)
diff --git a/src/doc/book/src/02-06-cargo-toml-vs-cargo-lock.md b/src/doc/book/src/guide/cargo-toml-vs-cargo-lock.md
similarity index 97%
rename from src/doc/book/src/02-06-cargo-toml-vs-cargo-lock.md
rename to src/doc/book/src/guide/cargo-toml-vs-cargo-lock.md
index fa0890957af..e373e386911 100644
--- a/src/doc/book/src/02-06-cargo-toml-vs-cargo-lock.md
+++ b/src/doc/book/src/guide/cargo-toml-vs-cargo-lock.md
@@ -100,5 +100,5 @@ $ cargo update -p rand   # updates just “rand”
 
 This will write out a new `Cargo.lock` with the new version information. Note
 that the argument to `cargo update` is actually a
-[Package ID Specification](03-07-pkgid-spec.html) and `rand` is just a short
+[Package ID Specification](reference/pkgid-spec.html) and `rand` is just a short
 specification.
diff --git a/src/doc/book/src/02-08-continuous-integration.md b/src/doc/book/src/guide/continuous-integration.md
similarity index 100%
rename from src/doc/book/src/02-08-continuous-integration.md
rename to src/doc/book/src/guide/continuous-integration.md
diff --git a/src/doc/book/src/02-02-creating-a-new-project.md b/src/doc/book/src/guide/creating-a-new-project.md
similarity index 100%
rename from src/doc/book/src/02-02-creating-a-new-project.md
rename to src/doc/book/src/guide/creating-a-new-project.md
diff --git a/src/doc/book/src/02-04-dependencies.md b/src/doc/book/src/guide/dependencies.md
similarity index 96%
rename from src/doc/book/src/02-04-dependencies.md
rename to src/doc/book/src/guide/dependencies.md
index 87a13c5d413..e199487f21e 100644
--- a/src/doc/book/src/02-04-dependencies.md
+++ b/src/doc/book/src/guide/dependencies.md
@@ -20,7 +20,7 @@ time = "0.1.12"
 ```
 
 The version string is a [semver] version requirement. The [specifying
-dependencies](03-01-specifying-dependencies.html) docs have more information about
+dependencies](reference/specifying-dependencies.html) docs have more information about
 the options you have here.
 
 [semver]: https://github.com/steveklabnik/semver#requirements
diff --git a/src/doc/book/src/02-05-project-layout.md b/src/doc/book/src/guide/project-layout.md
similarity index 97%
rename from src/doc/book/src/02-05-project-layout.md
rename to src/doc/book/src/guide/project-layout.md
index 9b2df404f1b..f122e46eb9d 100644
--- a/src/doc/book/src/02-05-project-layout.md
+++ b/src/doc/book/src/guide/project-layout.md
@@ -32,7 +32,7 @@ Cargo project:
 * Benchmarks go in the `benches` directory.
 
 These are explained in more detail in the [manifest
-description](03-02-manifest.html#the-project-layout).
+description](reference/manifest.html#the-project-layout).
 
 ## Cargo.toml vs Cargo.lock
 
@@ -136,5 +136,5 @@ $ cargo update -p rand   # updates just “rand”
 
 This will write out a new `Cargo.lock` with the new version information. Note
 that the argument to `cargo update` is actually a
-[Package ID Specification](03-07-pkgid-spec.html) and `rand` is just a short
+[Package ID Specification](reference/pkgid-spec.html) and `rand` is just a short
 specification.
diff --git a/src/doc/book/src/02-07-tests.md b/src/doc/book/src/guide/tests.md
similarity index 100%
rename from src/doc/book/src/02-07-tests.md
rename to src/doc/book/src/guide/tests.md
diff --git a/src/doc/book/src/02-01-why-cargo-exists.md b/src/doc/book/src/guide/why-cargo-exists.md
similarity index 100%
rename from src/doc/book/src/02-01-why-cargo-exists.md
rename to src/doc/book/src/guide/why-cargo-exists.md
diff --git a/src/doc/book/src/02-03-working-on-an-existing-project.md b/src/doc/book/src/guide/working-on-an-existing-project.md
similarity index 100%
rename from src/doc/book/src/02-03-working-on-an-existing-project.md
rename to src/doc/book/src/guide/working-on-an-existing-project.md
diff --git a/src/doc/book/src/introduction.md b/src/doc/book/src/introduction.md
index 850ede20ebd..4ecf1a7d8ba 100644
--- a/src/doc/book/src/introduction.md
+++ b/src/doc/book/src/introduction.md
@@ -11,39 +11,39 @@ dependencies, compiles your project, makes packages, and upload them to
 
 To get started with Cargo, install Cargo (and Rust) and set up your first crate.
 
-* [Installation](01-01-installation.html)
-* [First Steps with Cargo](01-02-first-steps.html)
+* [Installation](getting-started/installation.html)
+* [First Steps with Cargo](getting-started/first-steps.html)
 
 ## [Cargo Guide](guide.html)
 
 The guide will give you all you need to know about how to use Cargo to develop
 Rust projects.
 
-* [Why Cargo exists](02-01-why-cargo-exists.html)
-* [Creating a new project](02-02-creating-a-new-project.html)
+* [Why Cargo exists](guide/why-cargo-exists.html)
+* [Creating a new project](guide/creating-a-new-project.html)
 * [Working on an existing Cargo
-    project](02-03-working-on-an-existing-project.html)
-* [Dependencies](02-04-dependencies.html)
-* [Project layout](02-05-project-layout.html)
-* [Cargo.toml vs Cargo.lock](02-06-cargo-toml-vs-cargo-lock.html)
-* [Tests](02-07-tests.html)
-* [Continuous Integration](02-08-continuous-integration.html)
+    project](guide/working-on-an-existing-project.html)
+* [Dependencies](guide/dependencies.html)
+* [Project layout](guide/project-layout.html)
+* [Cargo.toml vs Cargo.lock](guide/cargo-toml-vs-cargo-lock.html)
+* [Tests](guide/tests.html)
+* [Continuous Integration](guide/continuous-integration.html)
 
-## [Cargo In Depth](cargo-in-depth.html)
+## [Cargo Reference](reference.html)
 
 After having an overview of how to use Cargo and have created your first crate,
 you may be interested in more details in the following areas.
 
-* [Specifying Dependencies](03-01-specifying-dependencies.html)
-* [Cargo.toml Format](03-02-manifest.html)
-* [Configuration](03-03-config.html)
-* [Environment Variables](03-04-environment-variables.html)
-* [Build Scripts](03-05-build-scripts.html)
-* [Publishing on crates.io](03-06-crates-io.html)
-* [Package ID specs](03-07-pkgid-spec.html)
-* [Source Replacement](03-08-source-replacement.html)
-* [External Tools](03-09-external-tools.html)
-* [Policies](03-10-policies.html)
+* [Specifying Dependencies](reference/specifying-dependencies.html)
+* [The Manifest Format](reference/manifest.html)
+* [Configuration](reference/config.html)
+* [Environment Variables](reference/environment-variables.html)
+* [Build Scripts](reference/build-scripts.html)
+* [Publishing on crates.io](reference/crates-io.html)
+* [Package ID Specifications](reference/pkgid-spec.html)
+* [Source Replacement](reference/source-replacement.html)
+* [External Tools](reference/external-tools.html)
+* [Crates.io Package Policies](reference/policies.html)
 
 ## [Frequently Asked Questions](faq.html)
 
diff --git a/src/doc/book/src/reference.md b/src/doc/book/src/reference.md
new file mode 100644
index 00000000000..1c034b7dbc9
--- /dev/null
+++ b/src/doc/book/src/reference.md
@@ -0,0 +1,15 @@
+## Cargo Reference
+
+Now that you have an overview of how to use Cargo and have created your first
+crate, you may be interested in more details in the following areas.
+
+* [Specifying Dependencies](reference/specifying-dependencies.html)
+* [The Manifest Format](reference/manifest.html)
+* [Configuration](reference/config.html)
+* [Environment Variables](reference/environment-variables.html)
+* [Build Scripts](reference/build-scripts.html)
+* [Publishing on crates.io](reference/crates-io.html)
+* [Package ID Specifications](reference/pkgid-spec.html)
+* [Source Replacement](reference/source-replacement.html)
+* [External Tools](reference/external-tools.html)
+* [Crates.io Package Policies](reference/policies.html)
diff --git a/src/doc/book/src/03-05-build-scripts.md b/src/doc/book/src/reference/build-scripts.md
similarity index 99%
rename from src/doc/book/src/03-05-build-scripts.md
rename to src/doc/book/src/reference/build-scripts.md
index 6d775ed1bf6..eb5bb0d2120 100644
--- a/src/doc/book/src/03-05-build-scripts.md
+++ b/src/doc/book/src/reference/build-scripts.md
@@ -40,7 +40,7 @@ all passed in the form of [environment variables][env].
 In addition to environment variables, the build script’s current directory is
 the source directory of the build script’s package.
 
-[env]: 03-04-environment-variables.html
+[env]: reference/environment-variables.html
 
 ### Outputs of the Build Script
 
@@ -184,7 +184,7 @@ prevent running the build script in question altogether and instead supply the
 metadata ahead of time.
 
 To override a build script, place the following configuration in any acceptable
-Cargo [configuration location](03-03-config.html).
+Cargo [configuration location](reference/config.html).
 
 ```toml
 [target.x86_64-unknown-linux-gnu.foo]
diff --git a/src/doc/book/src/03-03-config.md b/src/doc/book/src/reference/config.md
similarity index 98%
rename from src/doc/book/src/03-03-config.md
rename to src/doc/book/src/reference/config.md
index 4768957f14b..a815bf9814f 100644
--- a/src/doc/book/src/03-03-config.md
+++ b/src/doc/book/src/reference/config.md
@@ -2,7 +2,7 @@
 
 This document will explain how Cargo’s configuration system works, as well as
 available keys or configuration.  For configuration of a project through its
-manifest, see the [manifest format](03-02-manifest.html).
+manifest, see the [manifest format](reference/manifest.html).
 
 ### Hierarchical structure
 
@@ -134,4 +134,4 @@ environment variables.
 In addition to the system above, Cargo recognizes a few other specific
 [environment variables][env].
 
-[env]: 03-04-environment-variables.html
+[env]: reference/environment-variables.html
diff --git a/src/doc/book/src/03-06-crates-io.md b/src/doc/book/src/reference/crates-io.md
similarity index 98%
rename from src/doc/book/src/03-06-crates-io.md
rename to src/doc/book/src/reference/crates-io.md
index 2e68a738c59..f1a76ddfa98 100644
--- a/src/doc/book/src/03-06-crates-io.md
+++ b/src/doc/book/src/reference/crates-io.md
@@ -95,14 +95,14 @@ If you’d like to skip the `cargo package` step, the `cargo publish` subcommand
 will automatically package up the local crate if a copy isn’t found already.
 
 Be sure to check out the [metadata you can
-specify](03-02-manifest.html#package-metadata) to ensure your crate can be
+specify](reference/manifest.html#package-metadata) to ensure your crate can be
 discovered more easily!
 
 ### Publishing a new version of an existing crate
 
 In order to release a new version, change the `version` value specified in your
 `Cargo.toml` manifest. Keep in mind [the semver
-rules](03-02-manifest.html#the-version-field). Then optionally run `cargo package` if
+rules](reference/manifest.html#the-version-field). Then optionally run `cargo package` if
 you want to inspect the `*.crate` file for the new version before publishing,
 and run `cargo publish` to upload the new version.
 
diff --git a/src/doc/book/src/03-04-environment-variables.md b/src/doc/book/src/reference/environment-variables.md
similarity index 97%
rename from src/doc/book/src/03-04-environment-variables.md
rename to src/doc/book/src/reference/environment-variables.md
index 32b57da2969..7abebd0f795 100644
--- a/src/doc/book/src/03-04-environment-variables.md
+++ b/src/doc/book/src/reference/environment-variables.md
@@ -32,7 +32,7 @@ system:
 Note that Cargo will also read environment variables for `.cargo/config`
 configuration values, as described in [that documentation][config-env]
 
-[config-env]: 03-03-config.html#environment-variables
+[config-env]: reference/config.html#environment-variables
 
 ### Environment variables Cargo sets for crates
 
@@ -117,8 +117,8 @@ let out_dir = env::var("OUT_DIR").unwrap();
                        resolved to use, passed to the build script so it might
                        use it as well.
 
-[links]: 03-05-build-scripts.html#the-links-manifest-key
-[profile]: 03-02-manifest.html#the-profile-sections
+[links]: reference/build-scripts.html#the-links-manifest-key
+[profile]: reference/manifest.html#the-profile-sections
 [configuration]: https://doc.rust-lang.org/reference/attributes.html#conditional-compilation
 [clang]:http://clang.llvm.org/docs/CrossCompilation.html#target-triple
 
diff --git a/src/doc/book/src/03-09-external-tools.md b/src/doc/book/src/reference/external-tools.md
similarity index 100%
rename from src/doc/book/src/03-09-external-tools.md
rename to src/doc/book/src/reference/external-tools.md
diff --git a/src/doc/book/src/03-02-manifest.md b/src/doc/book/src/reference/manifest.md
similarity index 99%
rename from src/doc/book/src/03-02-manifest.md
rename to src/doc/book/src/reference/manifest.md
index 2b2367ad662..a87b7fd53bb 100644
--- a/src/doc/book/src/03-02-manifest.md
+++ b/src/doc/book/src/reference/manifest.md
@@ -37,7 +37,7 @@ This field specifies a file in the project root which is a [build script][1] for
 building native code. More information can be found in the build script
 [guide][1].
 
-[1]: 03-05-build-scripts.html
+[1]: reference/build-scripts.html
 
 ```toml
 [package]
@@ -249,7 +249,7 @@ assets = "path/to/static"
 
 ### Dependency sections
 
-See the [specifying dependencies page](03-01-specifying-dependencies.html) for
+See the [specifying dependencies page](reference/specifying-dependencies.html) for
 information on the `[dependencies]`, `[dev-dependencies]`,
 `[build-dependencies]`, and target-specific `[target.*.dependencies]` sections.
 
@@ -731,7 +731,7 @@ technical specification of this feature. Note that the `[patch]` feature will
 first become available in Rust 1.20, set to be released on 2017-08-31.
 
 [RFC 1969]: https://github.com/rust-lang/rfcs/pull/1969
-[replace]: 03-01-specifying-dependencies.html#overriding-dependencies
+[replace]: reference/specifying-dependencies.html#overriding-dependencies
 
 ### The `[replace]` Section
 
@@ -745,7 +745,7 @@ other copies. The syntax is similar to the `[dependencies]` section:
 ```
 
 Each key in the `[replace]` table is a [package id
-specification](03-07-pkgid-spec.html) which allows arbitrarily choosing a node in the
+specification](reference/pkgid-spec.html) which allows arbitrarily choosing a node in the
 dependency graph to override. The value of each key is the same as the
 `[dependencies]` syntax for specifying dependencies, except that you can't
 specify features. Note that when a crate is overridden the copy it's overridden
diff --git a/src/doc/book/src/03-07-pkgid-spec.md b/src/doc/book/src/reference/pkgid-spec.md
similarity index 100%
rename from src/doc/book/src/03-07-pkgid-spec.md
rename to src/doc/book/src/reference/pkgid-spec.md
diff --git a/src/doc/book/src/03-10-policies.md b/src/doc/book/src/reference/policies.md
similarity index 100%
rename from src/doc/book/src/03-10-policies.md
rename to src/doc/book/src/reference/policies.md
diff --git a/src/doc/book/src/03-08-source-replacement.md b/src/doc/book/src/reference/source-replacement.md
similarity index 98%
rename from src/doc/book/src/03-08-source-replacement.md
rename to src/doc/book/src/reference/source-replacement.md
index 8407bc0e679..343a7296af4 100644
--- a/src/doc/book/src/03-08-source-replacement.md
+++ b/src/doc/book/src/reference/source-replacement.md
@@ -5,7 +5,7 @@ strategies along the lines of mirrors or vendoring dependencies. Configuration
 is currently done through the [`.cargo/config` configuration][config] mechanism,
 like so:
 
-[config]: 03-03-config.html
+[config]: reference/config.html
 
 ```toml
 # The `source` table is where all keys related to source-replacement
@@ -49,7 +49,7 @@ patching a dependency or a private registry. Cargo supports patching
 dependencies through the usage of [the `[replace]` key][replace-section], and
 private registry support is planned for a future version of Cargo.
 
-[replace-section]: 03-02-manifest.html#the-replace-section
+[replace-section]: reference/manifest.html#the-replace-section
 
 ### Configuration
 
diff --git a/src/doc/book/src/03-01-specifying-dependencies.md b/src/doc/book/src/reference/specifying-dependencies.md
similarity index 98%
rename from src/doc/book/src/03-01-specifying-dependencies.md
rename to src/doc/book/src/reference/specifying-dependencies.md
index 962ea73495e..a671de516b1 100644
--- a/src/doc/book/src/03-01-specifying-dependencies.md
+++ b/src/doc/book/src/reference/specifying-dependencies.md
@@ -194,8 +194,8 @@ stable and will be released on 2017-08-31. Historically some of these scenarios
 have been solved with [the `[replace]` section][replace-section], but we'll
 document the `[patch]` section here.
 
-[patch-section]: 03-02-manifest.html#the-patch-section
-[replace-section]: 03-02-manifest.html#the-replace-section
+[patch-section]: reference/manifest.html#the-patch-section
+[replace-section]: reference/manifest.html#the-replace-section
 
 ### Testing a bugfix
 
@@ -523,4 +523,4 @@ features = ["secure-password", "civet"]
 ```
 
 More information about features can be found in the
-[manifest documentation](03-02-manifest.html#the-features-section).
+[manifest documentation](reference/manifest.html#the-features-section).

From 4c535b65d9e1da9c0de65117e2a75661bc8e3c94 Mon Sep 17 00:00:00 2001
From: Behnam Esfahbod <behnam@zwnj.org>
Date: Thu, 31 Aug 2017 14:01:17 -0700
Subject: [PATCH 5/8] [doc/book] Assign langs to more code blocks

---
 src/doc/book/README.md                              |  8 ++++----
 src/doc/book/src/getting-started/first-steps.md     |  2 +-
 src/doc/book/src/guide/cargo-toml-vs-cargo-lock.md  |  1 -
 src/doc/book/src/guide/creating-a-new-project.md    |  2 +-
 src/doc/book/src/guide/project-layout.md            |  1 -
 src/doc/book/src/reference/build-scripts.md         |  6 +++---
 src/doc/book/src/reference/crates-io.md             | 10 +++++-----
 src/doc/book/src/reference/environment-variables.md |  4 ++--
 src/doc/book/src/reference/manifest.md              |  4 ++--
 9 files changed, 18 insertions(+), 20 deletions(-)

diff --git a/src/doc/book/README.md b/src/doc/book/README.md
index af8d04a59ea..b24da689e67 100644
--- a/src/doc/book/README.md
+++ b/src/doc/book/README.md
@@ -7,7 +7,7 @@ Building the book requires [mdBook]. To get it:
 
 [mdBook]: https://github.com/azerupi/mdBook
 
-```bash
+```shell
 $ cargo install mdbook
 ```
 
@@ -15,7 +15,7 @@ $ cargo install mdbook
 
 To build the book:
 
-```bash
+```shell
 $ mdbook build
 ```
 
@@ -23,7 +23,7 @@ The output will be in the `book` subdirectory. To check it out, open it in
 your web browser.
 
 _Firefox:_
-```bash
+```shell
 $ firefox book/index.html                       # Linux
 $ open -a "Firefox" book/index.html             # OS X
 $ Start-Process "firefox.exe" .\book\index.html # Windows (PowerShell)
@@ -31,7 +31,7 @@ $ start firefox.exe .\book\index.html           # Windows (Cmd)
 ```
 
 _Chrome:_
-```bash
+```shell
 $ google-chrome book/index.html                 # Linux
 $ open -a "Google Chrome" book/index.html       # OS X
 $ Start-Process "chrome.exe" .\book\index.html  # Windows (PowerShell)
diff --git a/src/doc/book/src/getting-started/first-steps.md b/src/doc/book/src/getting-started/first-steps.md
index 097f3455d45..e0f964e801c 100644
--- a/src/doc/book/src/getting-started/first-steps.md
+++ b/src/doc/book/src/getting-started/first-steps.md
@@ -36,7 +36,7 @@ needs to compile your project.
 
 Here’s what’s in `src/main.rs`:
 
-```
+```rust
 fn main() {
     println!("Hello, world!");
 }
diff --git a/src/doc/book/src/guide/cargo-toml-vs-cargo-lock.md b/src/doc/book/src/guide/cargo-toml-vs-cargo-lock.md
index e373e386911..de3f18cb08b 100644
--- a/src/doc/book/src/guide/cargo-toml-vs-cargo-lock.md
+++ b/src/doc/book/src/guide/cargo-toml-vs-cargo-lock.md
@@ -82,7 +82,6 @@ dependencies = [
 name = "rand"
 version = "0.1.0"
 source = "git+https://github.com/rust-lang-nursery/rand.git#9f35b8e439eeedd60b9414c58f389bdc6a3284f9"
-
 ```
 
 You can see that there’s a lot more information here, including the exact
diff --git a/src/doc/book/src/guide/creating-a-new-project.md b/src/doc/book/src/guide/creating-a-new-project.md
index 541fec7f6b4..3f0c90e3cec 100644
--- a/src/doc/book/src/guide/creating-a-new-project.md
+++ b/src/doc/book/src/guide/creating-a-new-project.md
@@ -39,7 +39,7 @@ needs to compile your project.
 
 Here’s what’s in `src/main.rs`:
 
-```
+```rust
 fn main() {
     println!("Hello, world!");
 }
diff --git a/src/doc/book/src/guide/project-layout.md b/src/doc/book/src/guide/project-layout.md
index f122e46eb9d..1850e5efa3c 100644
--- a/src/doc/book/src/guide/project-layout.md
+++ b/src/doc/book/src/guide/project-layout.md
@@ -118,7 +118,6 @@ dependencies = [
 name = "rand"
 version = "0.1.0"
 source = "git+https://github.com/rust-lang-nursery/rand.git#9f35b8e439eeedd60b9414c58f389bdc6a3284f9"
-
 ```
 
 You can see that there’s a lot more information here, including the exact
diff --git a/src/doc/book/src/reference/build-scripts.md b/src/doc/book/src/reference/build-scripts.md
index eb5bb0d2120..2c6fe3d8123 100644
--- a/src/doc/book/src/reference/build-scripts.md
+++ b/src/doc/book/src/reference/build-scripts.md
@@ -49,7 +49,7 @@ All the lines printed to stdout by a build script are written to a file like
 configuration). Any line that starts with `cargo:` is interpreted directly by
 Cargo. This line must be of the form `cargo:key=value`, like the examples below:
 
-```notrust
+```shell
 # specially recognized by Cargo
 cargo:rustc-link-lib=static=foo
 cargo:rustc-link-search=native=/path/to/foo
@@ -212,7 +212,7 @@ library call as part of the build script.
 
 First, let’s take a look at the directory structure of this package:
 
-```notrust
+```shell
 .
 ├── Cargo.toml
 ├── build.rs
@@ -298,7 +298,7 @@ a Rust library which calls into C to print “Hello, World!”.
 
 Like above, let’s first take a look at the project layout:
 
-```notrust
+```shell
 .
 ├── Cargo.toml
 ├── build.rs
diff --git a/src/doc/book/src/reference/crates-io.md b/src/doc/book/src/reference/crates-io.md
index f1a76ddfa98..76a36a103b1 100644
--- a/src/doc/book/src/reference/crates-io.md
+++ b/src/doc/book/src/reference/crates-io.md
@@ -16,7 +16,7 @@ account (required for now). After this, visit your [Account
 Settings](https://crates.io/me) page and run the `cargo login` command
 specified.
 
-```notrust
+```shell
 $ cargo login abcdefghijklmnopqrstuvwxyz012345
 ```
 
@@ -37,7 +37,7 @@ The next step is to package up your crate into a format that can be uploaded to
 our entire crate and package it all up into a `*.crate` file in the
 `target/package` directory.
 
-```notrust
+```shell
 $ cargo package
 ```
 
@@ -87,7 +87,7 @@ Now that we’ve got a `*.crate` file ready to go, it can be uploaded to
 [crates.io] with the `cargo publish` command. And that’s it, you’ve now published
 your first crate!
 
-```notrust
+```shell
 $ cargo publish
 ```
 
@@ -119,7 +119,7 @@ being broken for one reason or another (syntax error, forgot to include a file,
 etc.). For situations such as this, Cargo supports a “yank” of a version of a
 crate.
 
-```notrust
+```shell
 $ cargo yank --vers 1.0.1
 $ cargo yank --vers 1.0.1 --undo
 ```
@@ -142,7 +142,7 @@ A crate is often developed by more than one person, or the primary maintainer
 may change over time! The owner of a crate is the only person allowed to publish
 new versions of the crate, but an owner may designate additional owners.
 
-```notrust
+```shell
 $ cargo owner --add my-buddy
 $ cargo owner --remove my-buddy
 $ cargo owner --add github:rust-lang:owners
diff --git a/src/doc/book/src/reference/environment-variables.md b/src/doc/book/src/reference/environment-variables.md
index 7abebd0f795..e95b79d6cbc 100644
--- a/src/doc/book/src/reference/environment-variables.md
+++ b/src/doc/book/src/reference/environment-variables.md
@@ -40,7 +40,7 @@ Cargo exposes these environment variables to your crate when it is compiled.
 Note that this applies for test binaries as well.
 To get the value of any of these variables in a Rust program, do this:
 
-```
+```rust
 let version = env!("CARGO_PKG_VERSION");
 ```
 
@@ -66,7 +66,7 @@ Cargo sets several environment variables when build scripts are run. Because the
 are not yet set when the build script is compiled, the above example using `env!` won't work
 and instead you'll need to retrieve the values when the build script is run:
 
-```
+```rust
 use std::env;
 let out_dir = env::var("OUT_DIR").unwrap();
 ```
diff --git a/src/doc/book/src/reference/manifest.md b/src/doc/book/src/reference/manifest.md
index a87b7fd53bb..8b71819c0c4 100644
--- a/src/doc/book/src/reference/manifest.md
+++ b/src/doc/book/src/reference/manifest.md
@@ -417,7 +417,7 @@ features that people can enable or disable when they build it.
 In that case, Servo will describe features in its `Cargo.toml` and they can be
 enabled using command-line flags:
 
-```
+```shell
 $ cargo build --release --features "shumway pdf"
 ```
 
@@ -535,7 +535,7 @@ Your project can optionally contain folders named `examples`, `tests`, and
 `benches`, which Cargo will treat as containing examples,
 integration tests, and benchmarks respectively.
 
-```notrust
+```shell
 ▾ src/           # directory containing source files
   lib.rs         # the main entry point for libraries and packages
   main.rs        # the main entry point for projects producing executables

From 21ffd599701bc588872be362d367972142d5ed8e Mon Sep 17 00:00:00 2001
From: Behnam Esfahbod <behnam@zwnj.org>
Date: Thu, 31 Aug 2017 14:36:07 -0700
Subject: [PATCH 6/8] [doc/book] Final touches to introduction.md

---
 src/doc/book/src/introduction.md | 41 +++++++-------------------------
 src/doc/book/src/reference.md    |  2 ++
 2 files changed, 11 insertions(+), 32 deletions(-)

diff --git a/src/doc/book/src/introduction.md b/src/doc/book/src/introduction.md
index 4ecf1a7d8ba..ddbd8b16349 100644
--- a/src/doc/book/src/introduction.md
+++ b/src/doc/book/src/introduction.md
@@ -7,45 +7,22 @@ dependencies, compiles your project, makes packages, and upload them to
 [crates.io], the Rust *package registry*.
 
 
-## [Getting Started](getting-started.html)
+### Sections
 
-To get started with Cargo, install Cargo (and Rust) and set up your first crate.
+**[Getting Started](getting-started.html)**
 
-* [Installation](getting-started/installation.html)
-* [First Steps with Cargo](getting-started/first-steps.html)
+To get started with Cargo, install Cargo (and Rust) and set up your first crate.
 
-## [Cargo Guide](guide.html)
+**[Cargo Guide](guide.html)**
 
 The guide will give you all you need to know about how to use Cargo to develop
 Rust projects.
 
-* [Why Cargo exists](guide/why-cargo-exists.html)
-* [Creating a new project](guide/creating-a-new-project.html)
-* [Working on an existing Cargo
-    project](guide/working-on-an-existing-project.html)
-* [Dependencies](guide/dependencies.html)
-* [Project layout](guide/project-layout.html)
-* [Cargo.toml vs Cargo.lock](guide/cargo-toml-vs-cargo-lock.html)
-* [Tests](guide/tests.html)
-* [Continuous Integration](guide/continuous-integration.html)
-
-## [Cargo Reference](reference.html)
-
-After having an overview of how to use Cargo and have created your first crate,
-you may be interested in more details in the following areas.
-
-* [Specifying Dependencies](reference/specifying-dependencies.html)
-* [The Manifest Format](reference/manifest.html)
-* [Configuration](reference/config.html)
-* [Environment Variables](reference/environment-variables.html)
-* [Build Scripts](reference/build-scripts.html)
-* [Publishing on crates.io](reference/crates-io.html)
-* [Package ID Specifications](reference/pkgid-spec.html)
-* [Source Replacement](reference/source-replacement.html)
-* [External Tools](reference/external-tools.html)
-* [Crates.io Package Policies](reference/policies.html)
-
-## [Frequently Asked Questions](faq.html)
+**[Cargo Reference](reference.html)**
+
+The reference covers the details of various areas of Cargo.
+
+**[Frequently Asked Questions](faq.html)**
 
 [rust]: https://www.rust-lang.org/
 [crates.io]: https://crates.io/
diff --git a/src/doc/book/src/reference.md b/src/doc/book/src/reference.md
index 1c034b7dbc9..dd3f724cb5f 100644
--- a/src/doc/book/src/reference.md
+++ b/src/doc/book/src/reference.md
@@ -3,6 +3,8 @@
 Now that you have an overview of how to use Cargo and have created your first
 crate, you may be interested in more details in the following areas.
 
+The reference covers the details of various areas of Cargo.
+
 * [Specifying Dependencies](reference/specifying-dependencies.html)
 * [The Manifest Format](reference/manifest.html)
 * [Configuration](reference/config.html)

From 664f5a184118d9651a146731ba5ebe6c65b1ee94 Mon Sep 17 00:00:00 2001
From: Behnam Esfahbod <behnam@zwnj.org>
Date: Thu, 31 Aug 2017 14:42:32 -0700
Subject: [PATCH 7/8] [doc/book] Add book.toml

---
 src/doc/book/book.toml | 2 ++
 1 file changed, 2 insertions(+)
 create mode 100644 src/doc/book/book.toml

diff --git a/src/doc/book/book.toml b/src/doc/book/book.toml
new file mode 100644
index 00000000000..1b84b2978c2
--- /dev/null
+++ b/src/doc/book/book.toml
@@ -0,0 +1,2 @@
+title = "The Cargo Manual"
+author = "Alex Crichton, Steve Klabnik and Carol Nichols, with Contributions from the Rust Community"

From 2ad45a563ef60819360ecd54d6eccc5b588e6401 Mon Sep 17 00:00:00 2001
From: Behnam Esfahbod <behnam@zwnj.org>
Date: Thu, 31 Aug 2017 15:07:55 -0700
Subject: [PATCH 8/8] [doc] Sync back doc/book changes into old docs

---
 src/doc/book/src/guide/project-layout.md | 104 -----------------------
 src/doc/guide.md                         |   5 +-
 src/doc/index.md                         |  34 ++++++--
 3 files changed, 29 insertions(+), 114 deletions(-)

diff --git a/src/doc/book/src/guide/project-layout.md b/src/doc/book/src/guide/project-layout.md
index 1850e5efa3c..f9eb7d3310e 100644
--- a/src/doc/book/src/guide/project-layout.md
+++ b/src/doc/book/src/guide/project-layout.md
@@ -33,107 +33,3 @@ Cargo project:
 
 These are explained in more detail in the [manifest
 description](reference/manifest.html#the-project-layout).
-
-## Cargo.toml vs Cargo.lock
-
-`Cargo.toml` and `Cargo.lock` serve two different purposes. Before we talk
-about them, here’s a summary:
-
-* `Cargo.toml` is about describing your dependencies in a broad sense, and is
-  written by you.
-* `Cargo.lock` contains exact information about your dependencies. It is
-  maintained by Cargo and should not be manually edited.
-
-If you’re building a library that other projects will depend on, put
-`Cargo.lock` in your `.gitignore`. If you’re building an executable like a
-command-line tool or an application, check `Cargo.lock` into `git`. If you're
-curious about why that is, see ["Why do binaries have `Cargo.lock` in version
-control, but not libraries?" in the
-FAQ](faq.html#why-do-binaries-have-cargolock-in-version-control-but-not-libraries).
-
-Let’s dig in a little bit more.
-
-`Cargo.toml` is a **manifest** file in which we can specify a bunch of
-different metadata about our project. For example, we can say that we depend
-on another project:
-
-```toml
-[package]
-name = "hello_world"
-version = "0.1.0"
-authors = ["Your Name <you@example.com>"]
-
-[dependencies]
-rand = { git = "https://github.com/rust-lang-nursery/rand.git" }
-```
-
-This project has a single dependency, on the `rand` library. We’ve stated in
-this case that we’re relying on a particular Git repository that lives on
-GitHub. Since we haven’t specified any other information, Cargo assumes that
-we intend to use the latest commit on the `master` branch to build our project.
-
-Sound good? Well, there’s one problem: If you build this project today, and
-then you send a copy to me, and I build this project tomorrow, something bad
-could happen. There could be more commits to `rand` in the meantime, and my
-build would include new commits while yours would not. Therefore, we would
-get different builds. This would be bad because we want reproducible builds.
-
-We could fix this problem by putting a `rev` line in our `Cargo.toml`:
-
-```toml
-[dependencies]
-rand = { git = "https://github.com/rust-lang-nursery/rand.git", rev = "9f35b8e" }
-```
-
-Now our builds will be the same. But there’s a big drawback: now we have to
-manually think about SHA-1s every time we want to update our library. This is
-both tedious and error prone.
-
-Enter the `Cargo.lock`. Because of its existence, we don’t need to manually
-keep track of the exact revisions: Cargo will do it for us. When we have a
-manifest like this:
-
-```toml
-[package]
-name = "hello_world"
-version = "0.1.0"
-authors = ["Your Name <you@example.com>"]
-
-[dependencies]
-rand = { git = "https://github.com/rust-lang-nursery/rand.git" }
-```
-
-Cargo will take the latest commit and write that information out into our
-`Cargo.lock` when we build for the first time. That file will look like this:
-
-```toml
-[root]
-name = "hello_world"
-version = "0.1.0"
-dependencies = [
- "rand 0.1.0 (git+https://github.com/rust-lang-nursery/rand.git#9f35b8e439eeedd60b9414c58f389bdc6a3284f9)",
-]
-
-[[package]]
-name = "rand"
-version = "0.1.0"
-source = "git+https://github.com/rust-lang-nursery/rand.git#9f35b8e439eeedd60b9414c58f389bdc6a3284f9"
-```
-
-You can see that there’s a lot more information here, including the exact
-revision we used to build. Now when you give your project to someone else,
-they’ll use the exact same SHA, even though we didn’t specify it in our
-`Cargo.toml`.
-
-When we’re ready to opt in to a new version of the library, Cargo can
-re-calculate the dependencies and update things for us:
-
-```shell
-$ cargo update           # updates all dependencies
-$ cargo update -p rand   # updates just “rand”
-```
-
-This will write out a new `Cargo.lock` with the new version information. Note
-that the argument to `cargo update` is actually a
-[Package ID Specification](reference/pkgid-spec.html) and `rand` is just a short
-specification.
diff --git a/src/doc/guide.md b/src/doc/guide.md
index e2b7da39715..e8986f78faf 100644
--- a/src/doc/guide.md
+++ b/src/doc/guide.md
@@ -57,7 +57,7 @@ needs to compile your project.
 
 Here’s what’s in `src/main.rs`:
 
-```
+```rust
 fn main() {
     println!("Hello, world!");
 }
@@ -201,7 +201,7 @@ we choose to `cargo update`.
 
 You can now use the `regex` library using `extern crate` in `main.rs`.
 
-```
+```rust
 extern crate regex;
 
 use regex::Regex;
@@ -339,7 +339,6 @@ dependencies = [
 name = "rand"
 version = "0.1.0"
 source = "git+https://github.com/rust-lang-nursery/rand.git#9f35b8e439eeedd60b9414c58f389bdc6a3284f9"
-
 ```
 
 You can see that there’s a lot more information here, including the exact
diff --git a/src/doc/index.md b/src/doc/index.md
index f2fbf81a0f5..cf3f36b585e 100644
--- a/src/doc/index.md
+++ b/src/doc/index.md
@@ -1,21 +1,41 @@
 % Cargo, Rust’s Package Manager
 
-# Installing
+### Install Stable Rust and Cargo
 
-The easiest way to get Cargo is to get the current stable release of Rust by
+The easiest way to get Cargo is to get the current stable release of [Rust] by
 using the `rustup` script:
 
 ```shell
 $ curl -sSf https://static.rust-lang.org/rustup.sh | sh
 ```
 
-This will get you the current stable release of Rust for your platform along
-with the latest Cargo.
+After this, you can use the `rustup` command to also install `beta` or `nightly`
+channels for Rust and Cargo.
 
-If you are on Windows, you can directly download the latest 32bit ([Rust](https://static.rust-lang.org/dist/rust-1.0.0-i686-pc-windows-gnu.msi)
-and [Cargo](https://static.rust-lang.org/cargo-dist/cargo-nightly-i686-pc-windows-gnu.tar.gz)) or 64bit ([Rust](https://static.rust-lang.org/dist/rust-1.0.0-x86_64-pc-windows-gnu.msi) and [Cargo](https://static.rust-lang.org/cargo-dist/cargo-nightly-x86_64-pc-windows-gnu.tar.gz)) Rust stable releases or Cargo nightlies.
+### Install Nightly Cargo
 
-Alternatively, you can build Cargo from source.
+To install just Cargo, the current recommended installation method is through
+the official nightly builds. Note that Cargo will also require that [Rust] is
+already installed on the system.
+
+| Platform         | 64-bit            | 32-bit            |
+|------------------|-------------------|-------------------|
+| Linux binaries   | [tar.gz][linux64] | [tar.gz][linux32] |
+| MacOS binaries   | [tar.gz][mac64]   | [tar.gz][mac32]   |
+| Windows binaries | [tar.gz][win64]   | [tar.gz][win32]   |
+
+### Build and Install Cargo from Source
+
+Alternatively, you can [build Cargo from source][compiling-from-source].
+
+[rust]: https://www.rust-lang.org/
+[linux64]: https://static.rust-lang.org/cargo-dist/cargo-nightly-x86_64-unknown-linux-gnu.tar.gz
+[linux32]: https://static.rust-lang.org/cargo-dist/cargo-nightly-i686-unknown-linux-gnu.tar.gz
+[mac64]: https://static.rust-lang.org/cargo-dist/cargo-nightly-x86_64-apple-darwin.tar.gz
+[mac32]: https://static.rust-lang.org/cargo-dist/cargo-nightly-i686-apple-darwin.tar.gz
+[win64]: https://static.rust-lang.org/cargo-dist/cargo-nightly-x86_64-pc-windows-gnu.tar.gz
+[win32]: https://static.rust-lang.org/cargo-dist/cargo-nightly-i686-pc-windows-gnu.tar.gz
+[compiling-from-source]: https://github.com/rust-lang/cargo#compiling-from-source
 
 # Let’s get started