[src/doc/book] Update 03-02-manifest.md from manifest.md

diff --git a/src/doc/MIGRATION_MAP b/src/doc/MIGRATION_MAP
index 85c7ed5702a21bb208cab5af487f7f124168c2c8..80cf26787467fe4c2625d838c77c28a03fe56fdb 100644 (file)
--- a/src/doc/MIGRATION_MAP
+++ b/src/doc/MIGRATION_MAP
@@ -6,7 +6,7 @@ external-tools.md book/src/03-09-external-tools.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
+manifest.md book/src/03-02-manifest.md
 pkgid-spec.md
 policies.md
 source-replacement.md

diff --git a/src/doc/book/src/03-02-manifest.md b/src/doc/book/src/03-02-manifest.md
index 6068bb5a5348e76ee5c4dacbe0a40224d30b1a35..a5d25e77bd46b894e2c01dab82f0ccff2effc3a0 100644 (file)
--- a/src/doc/book/src/03-02-manifest.md
+++ b/src/doc/book/src/03-02-manifest.md
@@ -30,7 +30,7 @@ Versioning](http://semver.org/), so make sure you follow some basic rules:
 
 #### The `build` field (optional)
 
-This field specifies a file in the repository which is a [build script][1] for
+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].
 
@@ -52,7 +52,8 @@ Documentation links from specific hosts are blacklisted. Hosts are added
 to the blacklist if they are known to not be hosting documentation and are
 possibly of malicious intent e.g. ad tracking networks. URLs from the
 following hosts are blacklisted:
-- rust-ci.org
+
+* rust-ci.org
 
 Documentation URLs from blacklisted hosts will not appear on crates.io, and
 may be replaced by docs.rs links.
@@ -107,7 +108,7 @@ migration.
 #### The `publish`  field (optional)
 
 The `publish` field can be used to prevent a package from being published to a
-repository by mistake.
+package registry (like *crates.io*) by mistake.
 
 ```toml
 [package]
@@ -124,7 +125,7 @@ Cargo.toml with `[workspace]` upwards in the filesystem.
 ```toml
 [package]
 # ...
-workspace = "path/to/root"
+workspace = "path/to/workspace/root"
 ```
 
 For more information, see the documentation for the workspace table below.
@@ -142,15 +143,15 @@ There are a number of optional metadata fields also accepted under the
 # uploaded to crates.io (aka this is not markdown).
 description = "..."
 
-# These URLs point to more information about the repository. These are
+# These URLs point to more information about the package. These are
 # intended to be webviews of the relevant data, not necessarily compatible
 # with VCS tools and the like.
 documentation = "..."
 homepage = "..."
 repository = "..."
 
-# This points to a file in the repository (relative to this `Cargo.toml`). The
-# contents of this file are stored and indexed in the registry.
+# This points to a file under the package root (relative to this `Cargo.toml`).
+# The contents of this file are stored and indexed in the registry.
 readme = "..."
 
 # This is a list of up to five keywords that describe this crate. Keywords
@@ -175,31 +176,47 @@ license = "..."
 license-file = "..."
 
 # Optional specification of badges to be displayed on crates.io. The badges
-# currently available are Travis CI, Appveyor, and GitLab latest build status,
-# specified using the following parameters:
+# pertaining to build status that are currently available are Appveyor, CircleCI,
+# GitLab, and TravisCI. Available badges pertaining to code test coverage are
+# Codecov and Coveralls. There are also maintenance-related badges which state
+# the issue resolution time, percent of open issues, and future maintenance
+# intentions.
 [badges]
-# Travis CI: `repository` in format "<user>/<project>" is required.
-# `branch` is optional; default is `master`
-travis-ci = { repository = "...", branch = "master" }
+
 # Appveyor: `repository` is required. `branch` is optional; default is `master`
 # `service` is optional; valid values are `github` (default), `bitbucket`, and
 # `gitlab`.
 appveyor = { repository = "...", branch = "master", service = "github" }
+
+# Circle CI: `repository` is required. `branch` is optiona; default is `master`
+circle-ci = { repository = "...", branch = "master" }
+
 # GitLab: `repository` is required. `branch` is optional; default is `master`
 gitlab = { repository = "...", branch = "master" }
-# Circle CI: `repository` is required. `branch` is optional; default is `master`
-circle-ci = { repository = "...", branch = "master" }
-# Is it maintained resolution time: `repository` is required.
-is-it-maintained-issue-resolution = { repository = "..." }
-# Is it maintained percentage of open issues: `repository` is required.
-is-it-maintained-open-issues = { repository = "..." }
+
+# Travis CI: `repository` in format "<user>/<project>" is required.
+# `branch` is optional; default is `master`
+travis-ci = { repository = "...", branch = "master" }
+
 # Codecov: `repository` is required. `branch` is optional; default is `master`
 # `service` is optional; valid values are `github` (default), `bitbucket`, and
 # `gitlab`.
 codecov = { repository = "...", branch = "master", service = "github" }
+
 # Coveralls: `repository` is required. `branch` is optional; default is `master`
 # `service` is optional; valid values are `github` (default) and `bitbucket`.
 coveralls = { repository = "...", branch = "master", service = "github" }
+
+# Is it maintained resolution time: `repository` is required.
+is-it-maintained-issue-resolution = { repository = "..." }
+
+# Is it maintained percentage of open issues: `repository` is required.
+is-it-maintained-open-issues = { repository = "..." }
+
+# Maintenance: `status` is required Available options are `actively-developed`,
+# `passively-maintained`, `as-is`, `none`, `experimental`, `looking-for-maintainer`
+# and `deprecated`.
+maintenance = { status = "..." }
 ```
 
 The [crates.io](https://crates.io) registry will render the description, display
@@ -446,23 +463,22 @@ members = ["path/to/member1", "path/to/member2", "path/to/member3/*"]
 exclude = ["path1", "path/to/dir2"]
 ```
 
-Workspaces were added to Cargo as part [RFC 1525] and have a number of
+Workspaces were added to Cargo as part of [RFC 1525] and have a number of
 properties:
 
-* A workspace can contain multiple crates where one of them is the root crate.
-* The root crate's `Cargo.toml` contains the `[workspace]` table, but is not
+* A workspace can contain multiple crates where one of them is the *root crate*.
+* The *root crate*'s `Cargo.toml` contains the `[workspace]` table, but is not
   required to have other configuration.
-* Whenever any crate in the workspace is compiled, output is placed next to the
-  root crate's `Cargo.toml`.
-* The lock file for all crates in the workspace resides next to the root crate's
-  `Cargo.toml`.
+* Whenever any crate in the workspace is compiled, output is placed in the
+  *workspace root*. i.e. next to the *root crate*'s `Cargo.toml`.
+* The lock file for all crates in the workspace resides in the *workspace root*.
 * The `[patch]` and `[replace]` sections in `Cargo.toml` are only recognized
-  at the workspace root crate, they are ignored in member crates' manifests.
+  in the *root crate*'s manifest, and ignored in member crates' manifests.
 
 [RFC 1525]: https://github.com/rust-lang/rfcs/blob/master/text/1525-cargo-workspace.md
 
-The root crate of a workspace, indicated by the presence of `[workspace]` in its
-manifest, is responsible for defining the entire workspace. All `path`
+The *root crate* of a workspace, indicated by the presence of `[workspace]` in
+its manifest, is responsible for defining the entire workspace. All `path`
 dependencies residing in the workspace directory become members. You can add
 additional packages to the workspace by listing them in the `members` key. Note
 that members of the workspaces listed explicitly will also have their path
@@ -485,6 +501,18 @@ and also be a member crate of another workspace (contain `package.workspace`).
 Most of the time workspaces will not need to be dealt with as `cargo new` and
 `cargo init` will handle workspace configuration automatically.
 
+#### 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
+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.
+
 #TODO: move this to a more appropriate place
 ### The project layout
 

diff --git a/src/doc/manifest.md b/src/doc/manifest.md
index 544b50665396ddaac85eadb69071c07661bf45e8..482d9c764997dd09cfd01aa7349cf193e58e625b 100644 (file)
--- a/src/doc/manifest.md
+++ b/src/doc/manifest.md
@@ -108,7 +108,7 @@ migration.
 ## The `publish`  field (optional)
 
 The `publish` field can be used to prevent a package from being published to a
-package repository (like *crates.io*) by mistake.
+package registry (like *crates.io*) by mistake.
 
 ```toml
 [package]
@@ -175,7 +175,7 @@ license = "..."
 # (similar to the readme key).
 license-file = "..."
 
-# Optional specification of badges to be displayed on crates.io. The badges 
+# Optional specification of badges to be displayed on crates.io. The badges
 # pertaining to build status that are currently available are Appveyor, CircleCI,
 # GitLab, and TravisCI. Available badges pertaining to code test coverage are
 # Codecov and Coveralls. There are also maintenance-related badges which state
@@ -217,7 +217,6 @@ is-it-maintained-open-issues = { repository = "..." }
 # `passively-maintained`, `as-is`, `none`, `experimental`, `looking-for-maintainer`
 # and `deprecated`.
 maintenance = { status = "..." }
-
 ```
 
 The [crates.io](https://crates.io) registry will render the description, display
@@ -520,7 +519,7 @@ If your project is an executable, name the main source file `src/main.rs`. If it
 is a library, name the main source file `src/lib.rs`.
 
 Cargo will also treat any files located in `src/bin/*.rs` as executables. If your
-executable consist of more than just one source file, you might also use a directory
+executable consists of more than just one source file, you might also use a directory
 inside `src/bin` containing a `main.rs` file which will be treated as an executable
 with a name of the parent directory.
 Do note, however, once you add a `[[bin]]` section ([see
@@ -572,8 +571,8 @@ name = "foo"
 crate-type = ["staticlib"]
 ```
 
-You can build individual library examples with the command
-`cargo build --example <example-name>`.
+You can build individual library examples with the command `cargo build
+--example <example-name>`.
 
 # Tests