Automate rustc(1) man page generation using help2man script

[jkelley129]

Summary

This PR introduces a reproducible and automated process for generating the rustc(1) man page directly from the compiler’s help output, ensuring it always reflects the current CLI.

---

Details

• Adds src/doc/man/generate-rustc-man.sh:
  A shell script that invokes help2man on any given rustc binary, via that binary’s --help -v output.

  • Produces src/doc/man/rustc.1
  • Script is robust to execution directory and always writes to the correct location.

• Documentation in src/doc/man/README.md:

  • Explains the motivation, the step-by-step usage, prerequisites, and the rationale for making the man page solely reflect the actual compiler binary.
  • Documents command usage and expectations.

---

Rationale

• Source of Truth:
  The man page is generated entirely from the compiler’s current help text, eliminating drift between documentation and reality.
• Reproducible:
  The script ensures anyone can regenerate the man page exactly, as long as they have a target compiler binary and help2man installed.
• Minimal coupling:
  By keeping the script and artifacts local to src/doc/man, there’s no need to depend on build system internals.

---

Usage

After building rustc, simply run:

./src/doc/man/generate-rustc-man.sh path/to/rustc

• Requires help2man on the host system (apt install help2man, dnf install help2man, etc).

---

Notes

• No changes are made to core Rust sources.
• The man page should be regenerated if any CLI options/output are changed in the future.

---

Ready for feedback or further suggestions!

[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

[GuillaumeGomez]

Not too sure who's supposed to review this.

r? compiler

[Kivooeo]

I’m a bit unsure how to route and review this change, since it was redirected to a compiler team. As far as I understand it introduces new documentation-generation tooling and touches on how the rustc(1) man page is produced, and it’s not clear to me which team should be reviewing this or how it fits into our existing documentation processes

Could you clarify:

• what problem this is intended to solve in the context of the current rustc documentation workflow?

• whether this is meant as a proposal/experiment, or something you expect to be adopted as-is?

That would help figure out how (and by whom) this should be discussed further

[jkelley129]

I noticed two different issues(#149875 and #98977) that mentioned the rustc man page being out of sync with the rustc --help output, and they both suggested using an script to generate the man page from the help output to keep documentation in sync. This PR was meant to be an implementation of that. I am open to any modifications or suggestions to the implementation or to make it fit better into the current documentation workflow.

I apologize for not linking the issues initially, that may have made it more clear.

[jyn514]

@Kivooeo i’m willing to review this if you can’t find a reviewer. i don’t have r+ permissions anymore though.

[Kivooeo]

@Kivooeo i’m willing to review this if you can’t find a reviewer

Yeah, that's sounds really nice, thanks for taking time on it

also if you know, because I don't if we have to cooperate this with our release or infra teams to integrate this into our release process, like generate man before/with new release or only after editing cli flags, you might know this better

i don’t have r+ permissions anymore though.

Also not a problem

Do "r=me,jyn514" after approval, I'd only ask to be impartial as you can (for example README here is obviously written by ai, I'd prefer to see something more human if you share this. If it's important to clarify, I'm not writing this to criticize the author, but rather as something that could be improved, nothing personal)

r? jyn514

[rustbot]

jyn514 is not on the review rotation at the moment.
They may take a while to respond.

[Kivooeo]

@bors delegate=jyn514

[bors]

✌️ @jyn514, you can now approve this pull request!

If @Kivooeo told you to "r=me" after making some further change, please make that change, then do @bors r=@Kivooeo