Auto merge of #14339 - weihanglo:mdman, r=epage

fix: also build manpage for cargo.md

Author: bors

crates/xtask-build-man/src/main.rs

@@ -45,14 +45,14 @@ fn build_mdman() -> io::Result<()> {
 /// saved in the src/doc/src/commands/ directory. These are included in the
 /// Cargo book, which is converted to HTML by mdbook.
 fn build_cargo() -> io::Result<()> {
-    // Find all `src/doc/man/cargo-*.md`
+    // Find all `src/doc/man/cargo*.md`
     let src_paths = {
         let mut src_paths = Vec::new();
         for entry in fs::read_dir("src/doc/man")? {
             let entry = entry?;
             let file_name = entry.file_name();
             let file_name = file_name.to_str().unwrap();
-            if file_name.starts_with("cargo-") && file_name.ends_with(".md") {
+            if file_name.starts_with("cargo") && file_name.ends_with(".md") {
                 src_paths.push(entry.path());
             }
         }

src/doc/man/cargo.md

@@ -56,6 +56,9 @@ available at <https://rust-lang.org>.
 
 ### Manifest Commands
 
+{{man "cargo-add" 1}}\
+&nbsp;&nbsp;&nbsp;&nbsp;Add dependencies to a `Cargo.toml` manifest file.
+
 {{man "cargo-generate-lockfile" 1}}\
 &nbsp;&nbsp;&nbsp;&nbsp;Generate `Cargo.lock` for a project.
 
@@ -68,6 +71,9 @@ available at <https://rust-lang.org>.
 {{man "cargo-pkgid" 1}}\
 &nbsp;&nbsp;&nbsp;&nbsp;Print a fully qualified package specification.
 
+{{man "cargo-remove" 1}}\
+&nbsp;&nbsp;&nbsp;&nbsp;Remove dependencies from a `Cargo.toml` manifest file.
+
 {{man "cargo-tree" 1}}\
 &nbsp;&nbsp;&nbsp;&nbsp;Display a tree visualization of a dependency graph.
 

src/doc/man/generated_txt/cargo.txt

@@ -50,6 +50,9 @@ COMMANDS
            Execute unit and integration tests of a package.
 
    Manifest Commands
+       cargo-add(1)
+           Add dependencies to a Cargo.toml manifest file.
+
        cargo-generate-lockfile(1)
            Generate Cargo.lock for a project.
 
@@ -63,6 +66,9 @@ COMMANDS
        cargo-pkgid(1)
            Print a fully qualified package specification.
 
+       cargo-remove(1)
+           Remove dependencies from a Cargo.toml manifest file.
+
        cargo-tree(1)
            Display a tree visualization of a dependency graph.
 
@@ -158,16 +164,19 @@ OPTIONS
            <https://doc.rust-lang.org/cargo/reference/config.html>.
 
    Manifest Options
-       --frozen, --locked
-           Either of these flags requires that the Cargo.lock file is
-           up-to-date. If the lock file is missing, or it needs to be updated,
-           Cargo will exit with an error. The --frozen flag also prevents Cargo
-           from attempting to access the network to determine if it is
-           out-of-date.
+       --locked
+           Asserts that the exact same dependencies and versions are used as
+           when the existing Cargo.lock file was originally generated. Cargo
+           will exit with an error when either of the following scenarios
+           arises:
+
+           o  The lock file is missing.
 
-           These may be used in environments where you want to assert that the
-           Cargo.lock file is up-to-date (such as a CI build) or want to avoid
-           network access.
+           o  Cargo attempted to change the lock file due to a different
+              dependency resolution.
+
+           It may be used in environments where deterministic builds are
+           desired, such as in CI pipelines.
 
        --offline
            Prevents Cargo from accessing the network for any reason. Without
@@ -184,6 +193,9 @@ OPTIONS
            May also be specified with the net.offline config value
            <https://doc.rust-lang.org/cargo/reference/config.html>.
 
+       --frozen
+           Equivalent to specifying both --locked and --offline.
+
    Common Options
        +toolchain
            If Cargo has been installed with rustup, and the first argument to

src/doc/src/commands/cargo.md

@@ -56,6 +56,9 @@ available at <https://rust-lang.org>.
 
 ### Manifest Commands
 
+[cargo-add(1)](cargo-add.html)\
+&nbsp;&nbsp;&nbsp;&nbsp;Add dependencies to a `Cargo.toml` manifest file.
+
 [cargo-generate-lockfile(1)](cargo-generate-lockfile.html)\
 &nbsp;&nbsp;&nbsp;&nbsp;Generate `Cargo.lock` for a project.
 
@@ -68,6 +71,9 @@ available at <https://rust-lang.org>.
 [cargo-pkgid(1)](cargo-pkgid.html)\
 &nbsp;&nbsp;&nbsp;&nbsp;Print a fully qualified package specification.
 
+[cargo-remove(1)](cargo-remove.html)\
+&nbsp;&nbsp;&nbsp;&nbsp;Remove dependencies from a `Cargo.toml` manifest file.
+
 [cargo-tree(1)](cargo-tree.html)\
 &nbsp;&nbsp;&nbsp;&nbsp;Display a tree visualization of a dependency graph.
 
@@ -180,21 +186,21 @@ terminal.</li>
 <a href="../reference/config.html">config value</a>.</dd>
 
 
-
 </dl>
 
 ### Manifest Options
 
 <dl>
-<dt class="option-term" id="option-cargo---frozen"><a class="option-anchor" href="#option-cargo---frozen"></a><code>--frozen</code></dt>
 <dt class="option-term" id="option-cargo---locked"><a class="option-anchor" href="#option-cargo---locked"></a><code>--locked</code></dt>
-<dd class="option-desc">Either of these flags requires that the <code>Cargo.lock</code> file is
-up-to-date. If the lock file is missing, or it needs to be updated, Cargo will
-exit with an error. The <code>--frozen</code> flag also prevents Cargo from
-attempting to access the network to determine if it is out-of-date.</p>
-<p>These may be used in environments where you want to assert that the
-<code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network
-access.</dd>
+<dd class="option-desc">Asserts that the exact same dependencies and versions are used as when the
+existing <code>Cargo.lock</code> file was originally generated. Cargo will exit with an
+error when either of the following scenarios arises:</p>
+<ul>
+<li>The lock file is missing.</li>
+<li>Cargo attempted to change the lock file due to a different dependency resolution.</li>
+</ul>
+<p>It may be used in environments where deterministic builds are desired,
+such as in CI pipelines.</dd>
 
 
 <dt class="option-term" id="option-cargo---offline"><a class="option-anchor" href="#option-cargo---offline"></a><code>--offline</code></dt>
@@ -210,6 +216,9 @@ offline.</p>
 <p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</dd>
 
 
+<dt class="option-term" id="option-cargo---frozen"><a class="option-anchor" href="#option-cargo---frozen"></a><code>--frozen</code></dt>
+<dd class="option-desc">Equivalent to specifying both <code>--locked</code> and <code>--offline</code>.</dd>
+
 </dl>
 
 ### Common Options
@@ -252,19 +261,16 @@ requires the <code>-Z unstable-options</code> flag to enable (see
 
 </dl>
 
-
 ## ENVIRONMENT
 
 See [the reference](../reference/environment-variables.html) for
 details on environment variables that Cargo reads.
 
-
 ## EXIT STATUS
 
 * `0`: Cargo succeeded.
 * `101`: Cargo failed to complete.
 
-
 ## FILES
 
 `~/.cargo/`\

src/etc/man/cargo.1

@@ -64,6 +64,10 @@ available at <https://rust\-lang.org>\&.
 .br
 \ \ \ \ Execute unit and integration tests of a package.
 .SS "Manifest Commands"
+\fBcargo\-add\fR(1)
+.br
+\ \ \ \ Add dependencies to a \fBCargo.toml\fR manifest file.
+.sp
 \fBcargo\-generate\-lockfile\fR(1)
 .br
 \ \ \ \ Generate \fBCargo.lock\fR for a project.
@@ -80,6 +84,10 @@ available at <https://rust\-lang.org>\&.
 .br
 \ \ \ \ Print a fully qualified package specification.
 .sp
+\fBcargo\-remove\fR(1)
+.br
+\ \ \ \ Remove dependencies from a \fBCargo.toml\fR manifest file.
+.sp
 \fBcargo\-tree\fR(1)
 .br
 \ \ \ \ Display a tree visualization of a dependency graph.
@@ -209,17 +217,22 @@ May also be specified with the \fBterm.color\fR
 .RE
 .SS "Manifest Options"
 .sp
-\fB\-\-frozen\fR, 
 \fB\-\-locked\fR
 .RS 4
-Either of these flags requires that the \fBCargo.lock\fR file is
-up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will
-exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from
-attempting to access the network to determine if it is out\-of\-date.
+Asserts that the exact same dependencies and versions are used as when the
+existing \fBCargo.lock\fR file was originally generated. Cargo will exit with an
+error when either of the following scenarios arises:
 .sp
-These may be used in environments where you want to assert that the
-\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network
-access.
+.RS 4
+\h'-04'\(bu\h'+02'The lock file is missing.
+.RE
+.sp
+.RS 4
+\h'-04'\(bu\h'+02'Cargo attempted to change the lock file due to a different dependency resolution.
+.RE
+.sp
+It may be used in environments where deterministic builds are desired,
+such as in CI pipelines.
 .RE
 .sp
 \fB\-\-offline\fR
@@ -237,6 +250,11 @@ offline.
 .sp
 May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
 .RE
+.sp
+\fB\-\-frozen\fR
+.RS 4
+Equivalent to specifying both \fB\-\-locked\fR and \fB\-\-offline\fR\&.
+.RE
 .SS "Common Options"
 .sp
 \fB+\fR\fItoolchain\fR