From e0b4c582a1f71f884a62716f26a9db1331d16405 Mon Sep 17 00:00:00 2001
From: Peter Marheine <peter@taricorp.net>
Date: Mon, 8 Jan 2018 15:35:28 +1100
Subject: [PATCH 01/18] Recover docs for incremental compilation

Cherry-picked from 45cc30bc7379ae13b079157b660de9d084de7a9e which failed
to update the book and was replaced in
1271bb4de0c0e0a085be239c2418af9c673ffc87.
---
 src/doc/src/reference/config.md                | 2 ++
 src/doc/src/reference/environment-variables.md | 4 ++++
 src/doc/src/reference/manifest.md              | 5 +++++
 3 files changed, 11 insertions(+)

diff --git a/src/doc/src/reference/config.md b/src/doc/src/reference/config.md
index 047853eec06..c590f5d4f43 100644
--- a/src/doc/src/reference/config.md
+++ b/src/doc/src/reference/config.md
@@ -76,6 +76,8 @@ runner = ".."
 # custom flags to pass to all compiler invocations that target $triple
 # this value overrides build.rustflags when both are present
 rustflags = ["..", ".."]
+# Whether or not to enable incremental compilation
+incremental = true
 
 [target.'cfg(...)']
 # Similar for the $triple configuration, but using the `cfg` syntax.
diff --git a/src/doc/src/reference/environment-variables.md b/src/doc/src/reference/environment-variables.md
index 08d2adaa8bb..ebe3edf6b4d 100644
--- a/src/doc/src/reference/environment-variables.md
+++ b/src/doc/src/reference/environment-variables.md
@@ -28,6 +28,10 @@ system:
 * `RUSTFLAGS` - A space-separated list of custom flags to pass to all compiler
   invocations that Cargo performs. In contrast with `cargo rustc`, this is
   useful for passing a flag to *all* compiler instances.
+* `CARGO_INCREMENTAL` - If this is set to 1 then Cargo will force incremental
+  compilation to be enabled for the current compilation, and when set to 0 it
+  will force disabling it. If this env var isn't present then cargo's defaults
+  will otherwise be used.
 
 Note that Cargo will also read environment variables for `.cargo/config`
 configuration values, as described in [that documentation][config-env]
diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md
index 48372bb223c..b8f74695670 100644
--- a/src/doc/src/reference/manifest.md
+++ b/src/doc/src/reference/manifest.md
@@ -299,6 +299,7 @@ codegen-units = 1  # if > 1 enables parallel code generation which improves
                    # compile times, but prevents some optimizations.
                    # Passes `-C codegen-units`. Ignored when `lto = true`.
 panic = 'unwind'   # panic strategy (`-C panic=...`), can also be 'abort'
+incremental = true # whether or not incremental compilation is enabled
 
 # The release profile, used for `cargo build --release`.
 [profile.release]
@@ -309,6 +310,7 @@ lto = false
 debug-assertions = false
 codegen-units = 1
 panic = 'unwind'
+incremental = false
 
 # The testing profile, used for `cargo test`.
 [profile.test]
@@ -319,6 +321,7 @@ lto = false
 debug-assertions = true
 codegen-units = 1
 panic = 'unwind'
+incremental = true
 
 # The benchmarking profile, used for `cargo bench` and `cargo test --release`.
 [profile.bench]
@@ -329,6 +332,7 @@ lto = false
 debug-assertions = false
 codegen-units = 1
 panic = 'unwind'
+incremental = false
 
 # The documentation profile, used for `cargo doc`.
 [profile.doc]
@@ -339,6 +343,7 @@ lto = false
 debug-assertions = true
 codegen-units = 1
 panic = 'unwind'
+incremental = true
 ```
 
 ### The `[features]` section

From 12385f26ad3e306eeba79bde45aa85f9bcfe845a Mon Sep 17 00:00:00 2001
From: Peter Marheine <peter@taricorp.net>
Date: Mon, 8 Jan 2018 15:46:55 +1100
Subject: [PATCH 02/18] Recover docs for git vendoring

Cherry-picked from 5b08b8fe1019147fe489db17a9a8ae7ebe97f9e9 which failed
to update the book and was replaced in
1271bb4de0c0e0a085be239c2418af9c673ffc87.
---
 src/doc/src/reference/source-replacement.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/src/doc/src/reference/source-replacement.md b/src/doc/src/reference/source-replacement.md
index 343a7296af4..20099b29c91 100644
--- a/src/doc/src/reference/source-replacement.md
+++ b/src/doc/src/reference/source-replacement.md
@@ -20,6 +20,12 @@ like so:
 [source.my-awesome-source]
 directory = "vendor"
 
+# Git sources can optionally specify a branch/tag/rev as well
+git = "https://example.com/path/to/repo"
+# branch = "master"
+# tag = "v1.0.1"
+# rev = "313f44e8"
+
 # The crates.io default source for crates is available under the name
 # "crates-io", and here we use the `replace-with` key to indicate that it's
 # replaced with our source above.

From 05043ab742fb72ae6ad02cd0c7d117657b54a4db Mon Sep 17 00:00:00 2001
From: Peter Marheine <peter@taricorp.net>
Date: Mon, 8 Jan 2018 15:54:18 +1100
Subject: [PATCH 03/18] Recover doc mention of sccache

Cherry-picked from 13bb7bd95b457f7383487cf8dcf476009939cfac which failed
to update the book and was replaced in
1271bb4de0c0e0a085be239c2418af9c673ffc87.
---
 src/doc/src/guide/build-cache.md | 14 ++++++++++++++
 src/doc/src/guide/index.md       |  1 +
 2 files changed, 15 insertions(+)
 create mode 100644 src/doc/src/guide/build-cache.md

diff --git a/src/doc/src/guide/build-cache.md b/src/doc/src/guide/build-cache.md
new file mode 100644
index 00000000000..f3b62e700d6
--- /dev/null
+++ b/src/doc/src/guide/build-cache.md
@@ -0,0 +1,14 @@
+## Build cache
+
+Cargo shares build artifacts among all the packages of a single workspaces.
+Today, Cargo does not share build results across different workspaces, but 
+a similar result can be achieved by using a third party tool, [sccache].
+
+To setup `sccache`, install it with `cargo install sccache` and set 
+`RUSTC_WRAPPER` environmental variable to `sccache` before invoking Cargo.
+If you use bash, it makes sense to add `export RUSTC_WRAPPER=sccache` to 
+`.bashrc`. Refer to sccache documentation for more details.
+
+[sccache]: https://github.com/mozilla/sccache
+
+
diff --git a/src/doc/src/guide/index.md b/src/doc/src/guide/index.md
index d8bfda17c86..c8a61b28df9 100644
--- a/src/doc/src/guide/index.md
+++ b/src/doc/src/guide/index.md
@@ -11,3 +11,4 @@ develop Rust projects.
 * [Cargo.toml vs Cargo.lock](guide/cargo-toml-vs-cargo-lock.html)
 * [Tests](guide/tests.html)
 * [Continuous Integration](guide/continuous-integration.html)
+* [Build Cache](guide/build-cache.html)

From bfb72c5776bf029b8dc365e765eb316e68a0125d Mon Sep 17 00:00:00 2001
From: Peter Marheine <peter@taricorp.net>
Date: Mon, 8 Jan 2018 15:57:56 +1100
Subject: [PATCH 04/18] Recover doc for appveyor project ID

Cherry-picked from f59eb30bbb9f1c30dcbfebe54aed72e1f51ba7cc which failed
to update the book and was replaced in
1271bb4de0c0e0a085be239c2418af9c673ffc87.
---
 src/doc/src/reference/manifest.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md
index b8f74695670..5f5ac6a9871 100644
--- a/src/doc/src/reference/manifest.md
+++ b/src/doc/src/reference/manifest.md
@@ -199,7 +199,8 @@ license-file = "..."
 
 # Appveyor: `repository` is required. `branch` is optional; default is `master`
 # `service` is optional; valid values are `github` (default), `bitbucket`, and
-# `gitlab`.
+# `gitlab`; `id` is optional; you can specify the appveyor project id if you
+# want to use that instead.
 appveyor = { repository = "...", branch = "master", service = "github" }
 
 # Circle CI: `repository` is required. `branch` is optional; default is `master`

From 74b4d0ff4fac250d0731d80e86c35bb3db0c182f Mon Sep 17 00:00:00 2001
From: Peter Marheine <peter@taricorp.net>
Date: Mon, 8 Jan 2018 15:59:59 +1100
Subject: [PATCH 05/18] Recover workspace member clarification from
 8139a5d830d2c59b76abd9865ae7aeffdaaa107f

The original failed to update the book and was lost in
1271bb4de0c0e0a085be239c2418af9c673ffc87.
---
 src/doc/src/reference/manifest.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md
index 5f5ac6a9871..71aede54306 100644
--- a/src/doc/src/reference/manifest.md
+++ b/src/doc/src/reference/manifest.md
@@ -481,10 +481,12 @@ as:
 ```toml
 [workspace]
 
-# Optional key, inferred if not present
+# Optional key, inferred from path dependencies if not present.
+# Additional non-path dependencies that should be included must be given here.
+# In particular, for a virtual manifest, all members have to be listed.
 members = ["path/to/member1", "path/to/member2", "path/to/member3/*"]
 
-# Optional key, empty if not present
+# Optional key, empty if not present.
 exclude = ["path1", "path/to/dir2"]
 ```
 

From 999cba158826e488dc6b9e56588a74fc94560dbc Mon Sep 17 00:00:00 2001
From: Peter Marheine <peter@taricorp.net>
Date: Mon, 8 Jan 2018 16:02:46 +1100
Subject: [PATCH 06/18] Recover doc for inferred directory targets

First created in 6b94ed2238a3f378cfe4fda47922cef0908a942c and lost by
1271bb4de0c0e0a085be239c2418af9c673ffc87.
---
 src/doc/src/reference/manifest.md | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md
index 71aede54306..94680d07110 100644
--- a/src/doc/src/reference/manifest.md
+++ b/src/doc/src/reference/manifest.md
@@ -557,7 +557,8 @@ each file you want to build.
 
 Your project can optionally contain folders named `examples`, `tests`, and
 `benches`, which Cargo will treat as containing examples,
-integration tests, and benchmarks respectively.
+integration tests, and benchmarks respectively. Analogous to `bin` targets, they
+may be composed of single files or directories with a `main.rs` file.
 
 ```shell
 ▾ src/           # directory containing source files
@@ -569,10 +570,16 @@ integration tests, and benchmarks respectively.
     main.rs
 ▾ examples/      # (optional) examples
   *.rs
+▾ */             # (optional) directories containing multi-file examples
+  main.rs
 ▾ tests/         # (optional) integration tests
   *.rs
+▾ */             # (optional) directories containing multi-file tests
+  main.rs
 ▾ benches/       # (optional) benchmarks
   *.rs
+▾ */             # (optional) directories containing multi-file benchmarks
+  main.rs
 ```
 
 To structure your code after you've created the files and folders for your

From 72f20b54e5d2391c5dd207cde6cc4b417eb88dd3 Mon Sep 17 00:00:00 2001
From: Peter Marheine <peter@taricorp.net>
Date: Mon, 8 Jan 2018 16:07:25 +1100
Subject: [PATCH 07/18] Recover typo fix from
 95fa8fe027ba080f5f5cb336c8a7d31d046bbf4b

Lost in 1271bb4de0c0e0a085be239c2418af9c673ffc87
---
 src/doc/src/guide/build-cache.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/doc/src/guide/build-cache.md b/src/doc/src/guide/build-cache.md
index f3b62e700d6..d253b8acc4d 100644
--- a/src/doc/src/guide/build-cache.md
+++ b/src/doc/src/guide/build-cache.md
@@ -1,6 +1,6 @@
 ## Build cache
 
-Cargo shares build artifacts among all the packages of a single workspaces.
+Cargo shares build artifacts among all the packages of a single workspace.
 Today, Cargo does not share build results across different workspaces, but 
 a similar result can be achieved by using a third party tool, [sccache].
 

From ea42706d2de1412efbc3e47526673ae5971c59f9 Mon Sep 17 00:00:00 2001
From: Peter Marheine <peter@taricorp.net>
Date: Mon, 8 Jan 2018 16:10:09 +1100
Subject: [PATCH 08/18] Recover doc for appveyor project_name

First added in 53012bd4df83a0d43ce7dfd0175d78b084823477 which failed
to update the book and was replaced in
1271bb4de0c0e0a085be239c2418af9c673ffc87.
---
 src/doc/src/reference/manifest.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md
index 94680d07110..99e5965e958 100644
--- a/src/doc/src/reference/manifest.md
+++ b/src/doc/src/reference/manifest.md
@@ -200,7 +200,8 @@ license-file = "..."
 # Appveyor: `repository` is required. `branch` is optional; default is `master`
 # `service` is optional; valid values are `github` (default), `bitbucket`, and
 # `gitlab`; `id` is optional; you can specify the appveyor project id if you
-# want to use that instead.
+# want to use that instead. `project_name` is optional; use when the repository
+# name differs from the appveyor project name.
 appveyor = { repository = "...", branch = "master", service = "github" }
 
 # Circle CI: `repository` is required. `branch` is optional; default is `master`

From 1208798cf05708f9c78e92c53670dd5ce6b0b778 Mon Sep 17 00:00:00 2001
From: Peter Marheine <peter@taricorp.net>
Date: Mon, 8 Jan 2018 16:11:26 +1100
Subject: [PATCH 09/18] Re-fix spelling of 'workspace'

First fixed in 4848c30414c6ed6b7afbe6067703ccfe0510d0ec which failed
to update the book and was replaced in
1271bb4de0c0e0a085be239c2418af9c673ffc87.
---
 src/doc/src/reference/manifest.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md
index 99e5965e958..a29f2c5afbd 100644
--- a/src/doc/src/reference/manifest.md
+++ b/src/doc/src/reference/manifest.md
@@ -532,8 +532,8 @@ Most of the time workspaces will not need to be dealt with as `cargo new` and
 #### Virtual Manifest
 
 In workspace manifests, if the `package` table is present, the workspace root
-crate will be treated as a normal package, as well as a worksapce. If the
-`package` table is not present in a worksapce manifest, it is called a *virtual
+crate will be treated as a normal package, as well as a workspace. If the
+`package` table is not present in a workspace manifest, it is called a *virtual
 manifest*.
 
 When working with *virtual manifests*, package-related cargo commands, like

From 9011d43fb3e3e8e7e6ff3b74f97e5d8aeb94c82f Mon Sep 17 00:00:00 2001
From: Peter Marheine <peter@taricorp.net>
Date: Mon, 8 Jan 2018 16:13:34 +1100
Subject: [PATCH 10/18] Recover discussion of -vv for build output

First added in 723945cb0eae7d642caa88812c6ecee3ed5895a1 which failed
to update the book and was replaced in
1271bb4de0c0e0a085be239c2418af9c673ffc87.
---
 src/doc/src/reference/build-scripts.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/doc/src/reference/build-scripts.md b/src/doc/src/reference/build-scripts.md
index a50f3afea15..42113a1ffe2 100644
--- a/src/doc/src/reference/build-scripts.md
+++ b/src/doc/src/reference/build-scripts.md
@@ -47,8 +47,10 @@ the source directory of the build script’s package.
 
 All the lines printed to stdout by a build script are written to a file like
 `target/debug/build/<pkg>/output` (the precise location may depend on your
-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:
+configuration). If you would like to see such output directly in your terminal,
+invoke cargo as 'very verbose' with the `-vv` flag. 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:
 
 ```shell
 # specially recognized by Cargo

From 1ea9c994d019d095237ed0620d74e59e61a1ff5e Mon Sep 17 00:00:00 2001
From: Peter Marheine <peter@taricorp.net>
Date: Mon, 8 Jan 2018 16:14:54 +1100
Subject: [PATCH 11/18] Recover spelling correction for 'otherwsie'

First fixed in 7b65667d5912e46ab2a39a7914a0ade869acc258 which failed
to update the book and was replaced in
1271bb4de0c0e0a085be239c2418af9c673ffc87.
---
 src/doc/src/reference/publishing.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/doc/src/reference/publishing.md b/src/doc/src/reference/publishing.md
index 76a36a103b1..4f574fe6e11 100644
--- a/src/doc/src/reference/publishing.md
+++ b/src/doc/src/reference/publishing.md
@@ -52,7 +52,7 @@ accidentally package up that 2GB video asset, or large data files used for code
 generation, integration tests, or benchmarking.  There is currently a 10MB
 upload size limit on `*.crate` files. So, if the size of `tests` and `benches`
 directories and their dependencies are up to a couple of MBs, you can keep them
-in your package; otherwsie, better to exclude them.
+in your package; otherwise, better to exclude them.
 
 Cargo will automatically ignore files ignored by your version control system
 when packaging, but if you want to specify an extra set of files to ignore you

From e05dd84431e6ab00fea4d0d2ee6a5c1da33d56ff Mon Sep 17 00:00:00 2001
From: Peter Marheine <peter@taricorp.net>
Date: Mon, 8 Jan 2018 16:17:15 +1100
Subject: [PATCH 12/18] Recover gcc -> cc in build docs

First changed in 209513d8991e05049c1e78c6cdf14c0865f2dd16 which failed
to update the book and was replaced in
1271bb4de0c0e0a085be239c2418af9c673ffc87.
---
 src/doc/src/reference/build-scripts.md | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/src/doc/src/reference/build-scripts.md b/src/doc/src/reference/build-scripts.md
index 42113a1ffe2..aa62140b861 100644
--- a/src/doc/src/reference/build-scripts.md
+++ b/src/doc/src/reference/build-scripts.md
@@ -373,24 +373,26 @@ portable, and standardized. For example, the build script could be written as:
 ```rust,ignore
 // build.rs
 
-// Bring in a dependency on an externally maintained `gcc` package which manages
+// Bring in a dependency on an externally maintained `cc` package which manages
 // invoking the C compiler.
-extern crate gcc;
+extern crate cc;
 
 fn main() {
-    gcc::compile_library("libhello.a", &["src/hello.c"]);
+    cc::Build::new()
+        .file("src/hello.c")
+        .compile("hello");
 }
 ```
 
-Add a build time dependency on the `gcc` crate with the following addition to
+Add a build time dependency on the `cc` crate with the following addition to
 your `Cargo.toml`:
 
 ```toml
 [build-dependencies]
-gcc = "0.3"
+gcc = "1.0"
 ```
 
-The [`gcc` crate](https://crates.io/crates/gcc) abstracts a range of build
+The [`cc` crate](https://crates.io/crates/cc) abstracts a range of build
 script requirements for C code:
 
 * It invokes the appropriate compiler (MSVC for windows, `gcc` for MinGW, `cc`
@@ -399,7 +401,7 @@ script requirements for C code:
   the compiler being used.
 * Other environment variables, such as `OPT_LEVEL`, `DEBUG`, etc., are all
   handled automatically.
-* The stdout output and `OUT_DIR` locations are also handled by the `gcc`
+* The stdout output and `OUT_DIR` locations are also handled by the `cc`
   library.
 
 Here we can start to see some of the major benefits of farming as much

From 97555df8564ee5fcbf53053a6f34a1b1bfb44b29 Mon Sep 17 00:00:00 2001
From: Peter Marheine <peter@taricorp.net>
Date: Mon, 8 Jan 2018 16:21:09 +1100
Subject: [PATCH 13/18] Recover [patch] doc clarifications

First added in 1700346a9e9fe36b6e5b6858fc9a03d63f4fa37e which failed
to update the book and was replaced in
1271bb4de0c0e0a085be239c2418af9c673ffc87.
---
 src/doc/src/reference/manifest.md | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md
index a29f2c5afbd..5dfa60f6afb 100644
--- a/src/doc/src/reference/manifest.md
+++ b/src/doc/src/reference/manifest.md
@@ -738,19 +738,28 @@ other copies. The syntax is similar to the `[dependencies]` section:
 [patch.crates-io]
 foo = { git = 'https://github.com/example/foo' }
 bar = { path = 'my/local/bar' }
+
+[dependencies.baz]
+git = 'https://github.com/example/baz'
+
+[patch.'https://github.com/example/baz']
+baz = { git = 'https://github.com/example/patched-baz', branch='my-branch' }
 ```
 
 The `[patch]` table is made of dependency-like sub-tables. Each key after
 `[patch]` is a URL of the source that's being patched, or `crates-io` if
 you're modifying the https://crates.io registry. In the example above
 `crates-io` could be replaced with a git URL such as
-`https://github.com/rust-lang-nursery/log`.
+`https://github.com/rust-lang-nursery/log`; the second `[patch]`
+section in the example uses this to specify a source called `baz`.
 
 Each entry in these tables is a normal dependency specification, the same as
 found in the `[dependencies]` section of the manifest. The dependencies listed
 in the `[patch]` section are resolved and used to patch the source at the
 URL specified. The above manifest snippet patches the `crates-io` source (e.g.
-crates.io itself) with the `foo` crate and `bar` crate.
+crates.io itself) with the `foo` crate and `bar` crate. It also
+patches the `https://github.com/example/baz` source with a `my-branch` that
+comes from elsewhere.
 
 Sources can be patched with versions of crates that do not exist, and they can
 also be patched with versions of crates that already exist. If a source is

From 97584002bd2cbf738f7add5a32affc8884b0aa66 Mon Sep 17 00:00:00 2001
From: Peter Marheine <peter@taricorp.net>
Date: Mon, 8 Jan 2018 16:22:15 +1100
Subject: [PATCH 14/18] Recover 'Add missing spaces around = sign'

First changed in e8a1ba6f63a93430b1de6fc772e3f950d5bd63f2 which failed
to update the book and was replaced in
1271bb4de0c0e0a085be239c2418af9c673ffc87.
---
 src/doc/src/reference/manifest.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md
index 5dfa60f6afb..14480978452 100644
--- a/src/doc/src/reference/manifest.md
+++ b/src/doc/src/reference/manifest.md
@@ -743,7 +743,7 @@ bar = { path = 'my/local/bar' }
 git = 'https://github.com/example/baz'
 
 [patch.'https://github.com/example/baz']
-baz = { git = 'https://github.com/example/patched-baz', branch='my-branch' }
+baz = { git = 'https://github.com/example/patched-baz', branch = 'my-branch' }
 ```
 
 The `[patch]` table is made of dependency-like sub-tables. Each key after

From 68749296495967be591491100551670de2712b97 Mon Sep 17 00:00:00 2001
From: Peter Marheine <peter@taricorp.net>
Date: Mon, 8 Jan 2018 16:24:23 +1100
Subject: [PATCH 15/18] Recover implied --all for virtual workspace docs

First changed in 1240f42c899fbba8bf85e493c3beb9f82227a09a which failed
to update the book and was replaced in
1271bb4de0c0e0a085be239c2418af9c673ffc87.
---
 src/doc/src/reference/manifest.md | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md
index 14480978452..470838e0d97 100644
--- a/src/doc/src/reference/manifest.md
+++ b/src/doc/src/reference/manifest.md
@@ -537,9 +537,8 @@ crate will be treated as a normal package, as well as a workspace. If the
 manifest*.
 
 When working with *virtual manifests*, package-related cargo commands, like
-`cargo build`, won't be available anymore. But, most of such commands support
-the `--all` option, will execute the command for all the non-virtual manifest in
-the workspace.
+`cargo build`, default to all packages in the workspace as if `--all` was used.
+This can be changed by passing a `--package` or `-p` command-line parameters.
 
 #TODO: move this to a more appropriate place
 ### The project layout

From 48b87407e77dd24f8070546360261e46a939ce70 Mon Sep 17 00:00:00 2001
From: Peter Marheine <peter@taricorp.net>
Date: Mon, 8 Jan 2018 16:26:19 +1100
Subject: [PATCH 16/18] Recover docs for workspace.default-members

First added in 82d563b71bf697f3d989cc1fdc2455c59679c309 which failed
to update the book and was replaced in
1271bb4de0c0e0a085be239c2418af9c673ffc87.
---
 src/doc/src/reference/manifest.md | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md
index 470838e0d97..95b120e4a2d 100644
--- a/src/doc/src/reference/manifest.md
+++ b/src/doc/src/reference/manifest.md
@@ -537,8 +537,19 @@ crate will be treated as a normal package, as well as a workspace. If the
 manifest*.
 
 When working with *virtual manifests*, package-related cargo commands, like
-`cargo build`, default to all packages in the workspace as if `--all` was used.
-This can be changed by passing a `--package` or `-p` command-line parameters.
+`cargo build`, default to the set of packages specified by the `default-members`
+configuration:
+
+```toml
+[workspace]
+members = ["path/to/member1", "path/to/member2", "path/to/member3/*"]
+
+# The members that commands like `cargo build` apply to by deault.
+# This must expand to a subset of `members`.
+# Optional key, defaults to the same as `members`
+# (as if `--all` were used on the command line).
+default-members = ["path/to/member2", "path/to/member3/*"]
+```
 
 #TODO: move this to a more appropriate place
 ### The project layout

From 27d4195d301ccb7c78da7481d1e8fc119c4f6f7f Mon Sep 17 00:00:00 2001
From: Peter Marheine <peter@taricorp.net>
Date: Mon, 8 Jan 2018 16:29:07 +1100
Subject: [PATCH 17/18] Recover non-virtual default-members doc

First changed in f9a27fc1f7ef0e4360c878a0209370a86b310b5e which failed
to update the book and was replaced in
1271bb4de0c0e0a085be239c2418af9c673ffc87.
---
 src/doc/src/reference/manifest.md | 21 ++++++++++++---------
 1 file changed, 12 insertions(+), 9 deletions(-)

diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md
index 95b120e4a2d..be69f967910 100644
--- a/src/doc/src/reference/manifest.md
+++ b/src/doc/src/reference/manifest.md
@@ -536,21 +536,24 @@ crate will be treated as a normal package, as well as a workspace. If the
 `package` table is not present in a workspace manifest, it is called a *virtual
 manifest*.
 
-When working with *virtual manifests*, package-related cargo commands, like
-`cargo build`, default to the set of packages specified by the `default-members`
-configuration:
+#### Package selection
+
+In a workspace, package-related cargo commands like `cargo build` apply to
+packages selected by `-p` / `--package` or `--all` command-line parameters.
+When neither is specified, the optional `default-members` configuration is used:
 
 ```toml
 [workspace]
 members = ["path/to/member1", "path/to/member2", "path/to/member3/*"]
-
-# The members that commands like `cargo build` apply to by deault.
-# This must expand to a subset of `members`.
-# Optional key, defaults to the same as `members`
-# (as if `--all` were used on the command line).
-default-members = ["path/to/member2", "path/to/member3/*"]
+default-members = ["path/to/member2", "path/to/member3/foo"]
 ```
 
+When specified, `default-members` must expand to a subset of `members`.
+
+When `default-members` is not specified, the default is the root manifest
+if it is a package, or every member manifest (as if `--all` were specified
+on the command-line) for virtual workspaces.
+
 #TODO: move this to a more appropriate place
 ### The project layout
 

From f235d7baefb8e11d7670b6c1d690042ed2eaeffa Mon Sep 17 00:00:00 2001
From: Peter Marheine <peter@taricorp.net>
Date: Mon, 8 Jan 2018 16:31:45 +1100
Subject: [PATCH 18/18] Recover caveat about -vv and cleaning

First added in 72c924230c3df67261642f74ba415cb34086935f which failed
to update the book and was replaced in
1271bb4de0c0e0a085be239c2418af9c673ffc87.
---
 src/doc/src/reference/build-scripts.md | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/src/doc/src/reference/build-scripts.md b/src/doc/src/reference/build-scripts.md
index aa62140b861..53074238c21 100644
--- a/src/doc/src/reference/build-scripts.md
+++ b/src/doc/src/reference/build-scripts.md
@@ -48,9 +48,13 @@ the source directory of the build script’s package.
 All the lines printed to stdout by a build script are written to a file like
 `target/debug/build/<pkg>/output` (the precise location may depend on your
 configuration). If you would like to see such output directly in your terminal,
-invoke cargo as 'very verbose' with the `-vv` flag. 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:
+invoke cargo as 'very verbose' with the `-vv` flag. Note that if neither the
+build script nor project source files are modified, subsequent calls to
+cargo with `-vv` will **not** print output to the terminal because a
+new build is not executed. Run `cargo clean` before each cargo invocation
+if you want to ensure that output is always displayed on your terminal.
+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:
 
 ```shell
 # specially recognized by Cargo