docs(report): enhance man pages for cargo report *

.ignore

@@ -13,6 +13,7 @@ src/etc/man
 !src/doc/src/commands/manifest-commands.md
 !src/doc/src/commands/package-commands.md
 !src/doc/src/commands/publishing-commands.md
+!src/doc/src/commands/report-commands.md
 
 # Snapshots of HTML reports and log files are just too large
 tests/testsuite/**/*.jsonl

src/doc/man/cargo-report-future-incompatibilities.md

@@ -0,0 +1,64 @@
+# cargo-report-future-incompatibilities(1)
+{{~*set actionverb="Display a report for"}}
+
+## NAME
+
+cargo-report-future-incompatibilities --- Reports any crates which will eventually stop compiling
+
+## SYNOPSIS
+
+`cargo report future-incompatibilities` [_options_]
+
+## DESCRIPTION
+
+Displays a report of future-incompatible warnings that were emitted during
+previous builds.
+These are warnings for changes that may become hard errors in the future,
+causing dependencies to stop building in a future version of rustc.
+
+For more, see the chapter on [Future incompat report](../reference/future-incompat-report.html).
+
+## OPTIONS
+
+{{#options}}
+
+{{#option "`--id` _id_" }}
+Show the report with the specified Cargo-generated id.
+If not specified, shows the most recent report.
+{{/option}}
+
+{{/options}}
+
+{{> section-options-package }}
+
+### Display Options
+
+{{#options}}
+{{> options-display }}
+{{/options}}
+
+### Manifest Options
+
+{{#options}}
+{{> options-locked }}
+{{/options}}
+
+{{> section-options-common }}
+
+{{> section-environment }}
+
+{{> section-exit-status }}
+
+## EXAMPLES
+
+1. Display the latest future-incompat report:
+
+       cargo report future-incompat
+
+2. Display the latest future-incompat report for a specific package:
+
+       cargo report future-incompat --package [email protected]
+
+## SEE ALSO
+
+{{man "cargo" 1}}, {{man "cargo-report" 1}}, {{man "cargo-build" 1}}

src/doc/man/cargo-report.md

@@ -8,35 +8,36 @@ cargo-report --- Generate and display various kinds of reports
 
 `cargo report` _type_ [_options_]
 
-### DESCRIPTION
+## DESCRIPTION
 
 Displays a report of the given _type_ --- currently, only `future-incompat` is supported
 
 ## OPTIONS
 
-{{#options}}
+### Display Options
 
-{{#option "`--id` _id_" }}
-Show the report with the specified Cargo-generated id
-{{/option}}
+{{#options}}
+{{> options-display }}
+{{/options}}
 
-{{#option "`-p` _spec_..." "`--package` _spec_..." }}
-Only display a report for the specified package
-{{/option}}
+### Manifest Options
 
+{{#options}}
+{{> options-locked }}
 {{/options}}
 
-## EXAMPLES
+{{> section-options-common }}
+
+{{> section-environment }}
 
-1. Display the latest future-incompat report:
+{{> section-exit-status }}
 
-       cargo report future-incompat
+## EXAMPLES
 
-2. Display the latest future-incompat report for a specific package:
+1. Display the available kinds of reports:
 
-       cargo report future-incompat --package my-dep:0.0.1
+       cargo report --help
 
 ## SEE ALSO
-[Future incompat report](../reference/future-incompat-report.html)
 
-{{man "cargo" 1}}
+{{man "cargo" 1}}, {{man "cargo-report-future-incompatibilities" 1}}

src/doc/man/cargo.md

@@ -123,6 +123,14 @@ available at <https://rust-lang.org>.
 {{man "cargo-yank" 1}}\
 &nbsp;&nbsp;&nbsp;&nbsp;Remove a pushed crate from the index.
 
+### Report Commands
+
+{{man "cargo-report" 1}}\
+&nbsp;&nbsp;&nbsp;&nbsp;Generate and display various kinds of reports.
+
+{{man "cargo-report-future-incompatibilities" 1}}\
+&nbsp;&nbsp;&nbsp;&nbsp;Reports any crates which will eventually stop compiling.
+
 ### General Commands
 
 {{man "cargo-help" 1}}\

src/doc/man/generated_txt/cargo-report-future-incompatibilities.txt

@@ -0,0 +1,148 @@
+CARGO-REPORT-FUTURE-INCOMPATIBILITIES(1)
+
+NAME
+       cargo-report-future-incompatibilities — Reports any crates which will
+       eventually stop compiling
+
+SYNOPSIS
+       cargo report future-incompatibilities [options]
+
+DESCRIPTION
+       Displays a report of future-incompatible warnings that were emitted
+       during previous builds. These are warnings for changes that may become
+       hard errors in the future, causing dependencies to stop building in a
+       future version of rustc.
+
+       For more, see the chapter on Future incompat report
+       <https://doc.rust-lang.org/cargo/reference/future-incompat-report.html>.
+
+OPTIONS
+       --id id
+           Show the report with the specified Cargo-generated id. If not
+           specified, shows the most recent report.
+
+   Package Selection
+       By default, the package in the current working directory is selected.
+       The -p flag can be used to choose a different package in a workspace.
+
+       -p spec, --package spec
+           The package to display a report for. See cargo-pkgid(1) for the SPEC
+           format.
+
+   Display Options
+       -v, --verbose
+           Use verbose output. May be specified twice for “very verbose”
+           output which includes extra output such as dependency warnings and
+           build script output. May also be specified with the term.verbose
+           config value
+           <https://doc.rust-lang.org/cargo/reference/config.html>.
+
+       -q, --quiet
+           Do not print cargo log messages. May also be specified with the
+           term.quiet config value
+           <https://doc.rust-lang.org/cargo/reference/config.html>.
+
+       --color when
+           Control when colored output is used. Valid values:
+
+           o  auto (default): Automatically detect if color support is
+              available on the terminal.
+
+           o  always: Always display colors.
+
+           o  never: Never display colors.
+
+           May also be specified with the term.color config value
+           <https://doc.rust-lang.org/cargo/reference/config.html>.
+
+   Manifest Options
+       --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.
+
+           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
+           this flag, Cargo will stop with an error if it needs to access the
+           network and the network is not available. With this flag, Cargo will
+           attempt to proceed without the network if possible.
+
+           Beware that this may result in different dependency resolution than
+           online mode. Cargo will restrict itself to crates that are
+           downloaded locally, even if there might be a newer version as
+           indicated in the local copy of the index. See the cargo-fetch(1)
+           command to download dependencies before going offline.
+
+           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
+           cargo begins with +, it will be interpreted as a rustup toolchain
+           name (such as +stable or +nightly). See the rustup documentation
+           <https://rust-lang.github.io/rustup/overrides.html> for more
+           information about how toolchain overrides work.
+
+       --config KEY=VALUE or PATH
+           Overrides a Cargo configuration value. The argument should be in
+           TOML syntax of KEY=VALUE, or provided as a path to an extra
+           configuration file. This flag may be specified multiple times. See
+           the command-line overrides section
+           <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides>
+           for more information.
+
+       -C PATH
+           Changes the current working directory before executing any specified
+           operations. This affects things like where cargo looks by default
+           for the project manifest (Cargo.toml), as well as the directories
+           searched for discovering .cargo/config.toml, for example. This
+           option must appear before the command name, for example cargo -C
+           path/to/my-project build.
+
+           This option is only available on the nightly channel
+           <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and
+           requires the -Z unstable-options flag to enable (see #10098
+           <https://github.com/rust-lang/cargo/issues/10098>).
+
+       -h, --help
+           Prints help information.
+
+       -Z flag
+           Unstable (nightly-only) flags to Cargo. Run cargo -Z help for
+           details.
+
+ENVIRONMENT
+       See the reference
+       <https://doc.rust-lang.org/cargo/reference/environment-variables.html>
+       for details on environment variables that Cargo reads.
+
+EXIT STATUS
+       o  0: Cargo succeeded.
+
+       o  101: Cargo failed to complete.
+
+EXAMPLES
+       1. Display the latest future-incompat report:
+
+              cargo report future-incompat
+
+       2. Display the latest future-incompat report for a specific package:
+
+              cargo report future-incompat --package [email protected]
+
+SEE ALSO
+       cargo(1), cargo-report(1), cargo-build(1)
+