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

[weihanglo]

FCP

What does this PR try to resolve?

Make space for future report kinds iun cargo report documentations.

• A new sub-section of "report commands" in the Cargo book.
• Fixed that cargo report man page didn't match its --help text equivalent
• cargo report future-incompat didn't have its own man page.

Note that cargo help hasn't yet supported for future-incompat.
It will be a separate PR.

How to test and review this PR?

mdbook serve src/doc
target/debug/cargo help report

[rustbot]

r? @epage

rustbot has assigned @epage.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[epage]

‼️ Make report future-incompat the primary name instead of an alias.

I'm a bit concerned about this as incompat isn't too obvious of a meaning. To not block the other changes and to make this more visible, should this be split out into its own PR?

[epage]

Do we need an FCP for this as well?

[weihanglo]

This is a doc change that we can easily revert by redirecting the new page to https://doc.rust-lang.org/nightly/cargo/reference/future-incompat-report.html, so I don't think it need an FCP.

[epage]

Don't remember what my concern was here

[epage]

Now I remember: do we have compatibility guarantees on the man pages that we provide?

[weihanglo]

Ah, for that, yes. The toolchain distribution tarball has them in ./share/man/man1. Also rustup man <dot-joined-cmd> displays them.

So in terms of CLI compatibility we might want an FCP.

[weihanglo]

The toolchain distribution tarball has them in ./share/man/man1

Some OS distros include them in man database when install a toolchain from the system package manager.

[weihanglo]

Before starting FCP, let's align with the concerns.

The major change of this is we expose man pages and documentation of sub-subcommand (i.e., cargo report future-incompatibilities).

• If we consider man pages for human only, it is less an concern. If we then don't want to expose sub-subcommand later, we can just redirect them to their parent command.
• If we consider man pages also for manchine/programmable use cases, then we need to be ensure what the compatibility we guarantee here before making this change.
• Do we always want sub-subcommands to have its own man pages, or case-by-case? For example, cargo worktree doesn't have man pages for worktree add|remove separately This is similar to our cargo owner case. OTOH, docker container ls|rm|inspect does, as all the sub-subcommands are different than others.

[epage]

Do we always want sub-subcommands to have its own man pages, or case-by-case? For example, cargo worktree doesn't have man pages for worktree add|remove separately This is similar to our cargo owner case. OTOH, docker container ls|rm|inspect does, as all the sub-subcommands are different than others.

I think this should be handled on a case by case basis. Some subcommands are modes of the parent subcommand, like git stash. Clap has support for this as flatten_help. Other subcommands are more independent of each other and should have independent help.

[weihanglo]

‼️ Make report future-incompat the primary name instead of an alias.

I'm a bit concerned about this as incompat isn't too obvious of a meaning. To not block the other changes and to make this more visible, should this be split out into its own PR?

Removed. incompat is already a name in the stable flag --future-incompat-report in cargo build, as well as in the config table [future-incompat-report]. Personally I am not too worried about it.

[weihanglo]

@rfcbot fcp merge T-cargo

This proposes to generate man pages of cargo report future-incompatibilities sub-subcommand.

Affected UI:

• The Cargo Book will have a new chapter for the cargo report future-incompatibilities command.
• Rust distribution tarball will contain ./share/man/man1/cargo-report-future-incompatibilities.1 man page file.
  • This will be displayed via rustup man cargo-report-future-incompatibilities
  • Some operating system will install Cargo's man pages by default.
• cargo help will need to support a way to retrieve the man-page, though the exact support format will need a separate FCP after this one (see feat(help): display manpage for nested commands #16432).

Depending on our compatibility guarantee around man pages, this can be seen as one-way door or two-way door decision:

• If man pages are for human only, it is less an concern. If later we don't want to expose sub-subcommand, we can redirect them to their parent command.
• If man pages are also for programmable use cases, then we need to ensure what the compatibility we guarantee here.

[rust-rfcbot]

Team member @weihanglo has proposed to merge this. The next step is review by the rest of the tagged team members:

• @0xPoe
• @Eh2406
• @Muscraft
• @arlosi
• @ehuss
• @epage
• @joshtriplett
• @weihanglo

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[ehuss]

FWIW, my intention was to handle this on a case-by-case basis. I suspected cargo report would want to be split up, but it depended on what subcommands were added. If the subcommands are small or closely related, then I would lean towards having them together (like git bisect). However, if the subcommands are not really related, or take more than just a little to document, then I intended for them to have separate pages. I didn't do this for the initial cargo report just because it was more effort (the existing doc and help system didn't support it), and we didn't really need it at the time.

[rustbot]

This PR was rebased onto a different master commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.