tools: add script to sync -O opt-level in rustc manpage with rustc --…

[jkelley129]

This PR updates the rustc.1 manpage to reflect that the -O flag is equivalent to -C opt-level=3 (matching rustc --help). It also adds a maintenance script to keep this documentation in sync with the compiler.

Documentation

• Updated the description of -O in rustc.1 to state that it corresponds to -C opt-level=3.

Tooling

Added a new script: src/tools/update-rustc-man-opt-level.py, which:

• Extracts the -O → opt-level mapping from rustc --help (or a provided expected level).
• Updates the manpage accordingly, with a conservative heuristic to avoid unrelated rewrites.
• Supports dry-run by default and optional apply mode with automatic backups.
• Displays colored unified diffs for review.
• Allows specifying a custom rustc binary.

Fixes: #149875

[rustbot]

r? @GuillaumeGomez

rustbot has assigned @GuillaumeGomez.
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

[bjorn3]

Would you mind disabling the option in your user profile to automatically request copilot reviews?

[GuillaumeGomez]

r? compiler