[doc/book] Create dir for book sections

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/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)

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

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)

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)

src/doc/book/src/02-06-cargo-toml-vs-cargo-lock.md → 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.

src/doc/book/src/02-04-dependencies.md → 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

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

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)
 

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)

src/doc/book/src/03-05-build-scripts.md → 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]

src/doc/book/src/03-03-config.md → 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

src/doc/book/src/03-06-crates-io.md → 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.
 

src/doc/book/src/03-04-environment-variables.md → 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
 

src/doc/book/src/03-02-manifest.md → 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

src/doc/book/src/03-08-source-replacement.md → 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