Autogenerate man pages

[jyn514]

Right now the man pages need to be manually updated, which in practice means they're almost never updated. We should find a way to autogenerate these if we want them to be accurate.

Originally posted by @jyn514 in #98975 (comment)

[ghost]

For Cargo

Cargo seems to use Clap unlike Rustc and Rustdoc, which does have a utility for auto-generating man pages.

For Rustc and Rustdoc

Rustc and Rustdoc use getopt, which does not include a utility for generating man pages.

There is a common utility for this known as help2man, which gives a relatively good enough output. Although, some customization might be needed to improve it. [Which, fortunately, help2man allows.]

Current command to generate man pages for rustc/rustdoc [Not final¹] ->

help2man -N rustc | man -l -

Current flags passed to help2man

• -N

-N, --no-info suppress pointer to Texinfo manual

---

¹ - help2man's output is not perfect.

• Currently the generated man page lacks information compared to the old handwritten ones².
  Solutions ->
  • Implement an even more³ verbose help message when --verbose is passed to rustc --help so help2man could have the information
  • Have different man pages and run help2man on different help message sections.
    For eg. the autogenerated man pages lack detailed information regarding codegen options, it could be split into another manpage.

---

² - The autogenerated man pages lack detailed-information such as

• Codegen options
• Lints

One may compare on their own by comparing the outputs using the following commands [On Unix-y systems and using Rustup]

man -l $HOME/.rustup/toolchains/<toolchain>/share/man/man1/rustc.1

---

³ - While --help --verbose does exist, and it does add slightly more information.

Click to expand (Diff between verbose and non-verbose help messages of Rustc.)

It doesn't include in-depth information about for eg. Codegen options, those are split into separate help messages (rustc -C help for help regarding codegen options).

---

[cuviper]

Cargo seems to use Clap unlike Rustc and Rustdoc, which does have a utility for auto-generating man pages.

Looks like Cargo has manually-written Markdown that is converted with its own mdman.
https://github.com/rust-lang/cargo/blob/master/src/doc/man