Auto merge of #4455 - behnam:book-enh, r=alexcrichton

[doc/book] Add introduction page and other enhancements

Preview: http://code.behnam.es/rust-cargo/book/

* Reorganize files to use folders instead of numbered files. This will allow us to add new sections and pages without breaking a numbering system or the URLs.

* Rename "Cargo In Depth" to "Cargo Reference", as those pages are considered *the* reference for cargo behaviors.

* Add `introduction.md`, as the landing page with the book title and Cargo logo on top.

* 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 <rust-lang/crates.io#1029>)

* Sync `SUMMARY.md` titles (and sub-pages lists in section pages) with page titles and fix some wordings and casings.

* Expand Introduction and section pages with some intro text.

* Set lang for some of the code blocks.

* Add `book.toml` to get the title in HTML head title, etc.

Tracker: <#4040>

Author: bors

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

src/doc/book/README.md

@@ -7,31 +7,31 @@ Building the book requires [mdBook]. To get it:
 
 [mdBook]: https://github.com/azerupi/mdBook
 
-```bash
+```shell
 $ cargo install mdbook
 ```
 
 ### Building
 
 To build the book:
 
-```bash
+```shell
 $ mdbook build
 ```
 
 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)
 $ 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)

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"

src/doc/book/src/01-01-installation.md

@@ -1,29 +1,31 @@
 # Summary
 
+[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)
-    * [Cargo.toml 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)
-    * [Source Replacement](03-08-source-replacement.md)
-    * [External Tools](03-09-external-tools.md)
-    * [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)

src/doc/book/src/02-05-project-layout.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

src/doc/book/src/SUMMARY.md

@@ -1,4 +1,6 @@
 ## Getting Started
 
-* [Installation](01-01-installation.html)
-* [First steps with Cargo](01-02-first-steps.html)
+To get started with Cargo, install Cargo (and Rust) and set up your first crate.
+
+* [Installation](getting-started/installation.html)
+* [First steps with Cargo](getting-started/first-steps.html)

src/doc/book/src/cargo-in-depth.md

@@ -36,7 +36,7 @@ needs to compile your project.
 
 Here’s what’s in `src/main.rs`:
 
-```
+```rust
 fn main() {
     println!("Hello, world!");
 }
@@ -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)

src/doc/book/src/faq.md

@@ -0,0 +1,38 @@
+## Installation
+
+### 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
+```
+
+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.
+
+| 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