Man pages

[alexreg]

It would be great to have a command of the form

rustup man [TOOLCHAIN] MAN_PAGE

that displays the man page MAN_PAGE (e.g. rustc, cargo) for either the active toolchain or the specified TOOLCHAIN if given.

[brson]

Yeah this should probably exist, though I'd like to have a solution that works reliably on Windows.

[alexreg]

Do the man pages get installed on Windows? Perhaps Unix platforms could display the man page using man, but Windows could open an HTML-rendered version in the browser.

On 3 Jun 2016, at 22:22, Brian Anderson notifications@github.com wrote:

Yeah this should probably exist, though I'd like to have a solution that works reliably on Windows.

—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub #490 (comment), or mute the thread https://github.com/notifications/unsubscribe/AAEF3C5i9nqkLEU7FG4pS2WjdPoKw23Eks5qIJsHgaJpZM4IkHNl.

[brson]

I think it would make sense for upstream Rust to generate HTML versions of the man pages and include them in the docs.

[brson]

Based on existing commands I'd expect this to look like rustup man <program> [--toolchain]. This should be relatively easy to implement: add the command to rustup_mode.rs; lookup the toolchain dir; then just run the command and report any errors.

[typesanitizer]

Is this already taken? Otherwise, I'd like to do it as a first contribution.

[brson]

@theindigamer It's all yours!

[typesanitizer]

Sorry if these questions sound very naive/elementary to you:

1. Any particular advice for getting started? I've read the rustup_mode.rs file and have spotted a few places to make additions such as the App::new("rustup") and match matches.subcommand(). I also need to add a function fn man(cfg: &Cfg, m: &ArgMatches) -> Result<()>.
2. Should the specification have <command> (like rustup which) or <program>? Can you give a couple of examples (with/without the toolchain)?
3. Also, there aren't actual man pages for rustc,cargo etc., or am I wrong about this? As I understand it, the man subcommand is just supposed to display the corresponding help menu.

[sanmai-NL]

Maybe the need and the requirements for this feature could use some more thought?
I personally don't see the advantage over the usual man invocation. Is this supposed to become something else than the -h/--help option used in various contexts (e.g., subcommand)?

[brson]

I personally don't see the advantage over the usual man invocation.

rustup doesn't install the toolchain-specific Rust man pages to the system so running man rustc or man cargo is just an error today. This command allows the toolchains' man pages to be multiplexed like the toolchains' binaries.

Is this supposed to become something else than the -h/--help option used in various contexts (e.g., subcommand)?

Yes. This is for the Rust toolchain man pages, like rustc, cargo, rustdoc; -h is for help with the rustup tool.

[brson]

@theindigamer

Sorry if these questions sound very naive/elementary to you:

Any particular advice for getting started? I've read the rustup_mode.rs file and have spotted a few places to make additions such as the App::new("rustup") and match matches.subcommand(). I also need to add a function fn man(cfg: &Cfg, m: &ArgMatches) -> Result<()>.

• Add a new branch to dispatch the command in rustup_mode::main after the "doc" case (they cases are in order they should show up in the UI).
• Add the new arg definition in rustup_mode::cli again after "doc". Use the clap docs and existing examples as guides.
• Add the fn man as you've described. It can probably just use Command::status to spawn man with the correct args, not redirect stdio, and wait for the exit status. Report any errors.

Should the specification have <command> (like rustup which) or <program>? Can you give a couple of examples (with/without the toolchain)?

Yes, I'd call in 'command' for consistency. The optional 'toolchain' arg will look like this one.

Also, there aren't actual man pages for rustc,cargo etc., or am I wrong about this? As I understand it, the man subcommand is just supposed to display the corresponding help menu.

The man pages are located in the toolchain directory under share/man/man1/. The subcommand should invoke the man program to display them.

Good luck!

[brson]

@sanmai-NL Personally, I also wish we could just discard the man pages, but it doesn't seem like a position that can be maintained. On Unix people expect man pages to exist, and some distros will just write them themselves if we don't provide them, so they are going to continue to be a thing I think, so I reluctantly think rustup should make them accessible.

[typesanitizer]

Apologies for the delay. I have some code written down for the fn man but how do I go about testing it? There is no binary for rustup generated by compilation as far as I can tell, only a librustup.rlib and a rustup-init.

[brson]

@theindigamer The way I usually test is by running cargo run --release -- -y, which will run rustup-init to install rustup to your system. Then just run rustup normally to test.

It's possible to break your own rustup installation this way but rustup is easy to reinstall when that happens.

[typesanitizer]

I have made the changes here:
master...theindigamer:man-subcommand

Should I submit a PR or are there other changes to be made?

[brson]

@theindigamer That looks about right! Please submit a PR.

[brson]

Fixed!