man pages not configured.

[cheako]

man cargo should do something decent.

Append to MANPATH environment variable, if none exists use manpath binary to supply default.

export MANPATH="$HOME/.rustup/toolchains/stable-x86_64-unknown-linux-gnu/share/man:${MANPATH:-`manpath`}"

Notes I originally installed the Debian rust packages, where by Policy all executables should have a man-page. I opted to use rustup only because a newer version of rust was required to run the VSCode Extension. At the time I was unaware that man-pages wouldn't be setup.

[kinnison]

We are working on improving the manual pages experience with rustup we cannot do as you suggest because that'd lock a singular toolchain into the MANPATH - a toolchain which might not even remain installed. Instead we're working on a man proxy which will detect the requisite toolchain and amend MANPATH before invoking the man binary further on. For now you can run rustup man cargo.

[tesuji]

ping @cheako : Do you satisfy with Daniel suggestion? If not, could you describe your problem a bit:

• Things you want to do?
• What do you expect?
• Suggestion to improve things?

[cheako]

I still think that "man cargo" and "man rustc" ect should display something useful. Even if they just display to run "rustup man cargo".

[tesuji]

I don't think injecting rustup manpath to shell MANPATH variable is a good thing. MANPATH is not a particular environment variable of rustup. If rustup manipulates the global shell MANPATH, it will interfere or conflict with other programs using MANPATH.

There is one proposed workaround here:

• Add option to print current rust toolchain's manpath, something like rustup man --print. Then adding this line to .profile file:

  export MANPATH="$(rustup man --print):$MANPATH"
  

  After refreshing or spawning new shell session, you could run man cargo to display cargo's manpages of the current toolchain.

[kinnison]

@lzutao Do you fancy having a go at adding a man_mode.rs to rustup, i.e. detecting that rustup was invoked as man and acting as though rustup man was run? You'd need to find and eliminate the path to the rustup proxy from the PATH environment variable before then invoking the real man.

[cheako]

@lzutao Since rustup changes PATH I think it's already behaved more destructively than any change to MANPATH could possibly be.

I think it would be a grave mistake to try and replace the man command when man already provides an API for achieving the intended goal of adding additional places to look for manpages.

[kinnison]

man cannot know where to look because the requisite information is held by rustup. i.e. man cannot examine rust-toolchain or the rustup default setting, or directory overrides, etc. in order to know the correct toolchain to display the manpage from. As such we'd have to proxy man to do what you're asking.

[cheako]

@kinnison All I'm asking for is that "man cargo" display something, it doesn't have to display the correct manual, just a manual that says that cargo is a command that has further documentation under the "rustup man cargo" command.

[tesuji]

@cheako

Since rustup changes PATH I think it's already behaved more destructively than any change to MANPATH could possibly be.

rustup doesn't change global shell PATH. All it does when using something like rustup +nighly rustc is to call appropriate toolchain using exec function family.

All I'm asking for is that "man cargo" display something

man program is not a part of rustup project. I don't know how we could manage to do that unless you're willing to change MANPATH yourself.

[kennytm]

At least on macOS and Linux, if you symlink $TOOLCHAIN/share/man as ~/.cargo/man, then man cargo and all manpages work properly.

The behavior is documented in /private/etc/man.conf:

# If people ask for "man foo" and have "/dir/bin/foo" in their PATH
# and the docs are found in "/dir/man", then no mapping is required.

[kinnison]

man program is not a part of rustup project. I don't know how we could manage to do that unless you're willing to change MANPATH yourself.

I think we could yet manage to proxy man

[kinnison]

At least on macOS, if you symlink $TOOLCHAIN/share/man as ~/.cargo/man, then man cargo and all manpages work properly.

Same problem as I mentioned above - it still isn't toolchain-sensitive. i.e. it's (IMO) less optimal than rustup man cargo

[kennytm]

@kinnison At least this could make man rustup work 🤷, and the symlink can be updated when you change the rustup default (so it works as long as you don't override a toolchain).

[cheako]

I offered this suggestion so that new users would be able to find the documentation with man. I think it's entirely do able with toolchan agnostic man pages for each command being made available when PATH is altered, just extended MANPATH at the same time.

[kinnison]

I offered this suggestion so that new users would be able to find the documentation with man. I think it's entirely do able with toolchan agnostic man pages for each command being made available when PATH is altered, just extended MANPATH at the same time.

Please don't think that I'm not wanting to solve the problem - I entirely agree that man rustc or man cargo should absolutely work -- I think I just disagree with the implementation plan :D

[glhrmv]

Any updates on this?

[kinnison]

@glhrmv As of now, no there has been no consensus on an acceptable approach.

[pickfire]

Another solution, use section to identify man pages.

1. Name the manpage cargo.1-stable-x86_64-unknown-linux-gnu
2. Add the man pages to MANPATH
3. Optionally, modify .TH "CARGO" "1" "2020-04-16" "\ \&" "\ \&" in the man page from 1 to 1-stable-x86_64-unknown-linux-gnu (this is a challenge to verify signature)

After that, we get

> ls  # filename, haven't thought about the structure to safe the man pages yet
cargo.1-stable-x86_64-unknown-linux-gnu
> man -k cargo
cargo (1-stable-x86_64-unknown-linux-gnu) - The Rust package manager
> man cargo  # 1st line in pager if we do optional step 3
CARGO(1-stable-x86_64-unknown-linux-gnCARGO(1-stable-x86_64-unknown-linux-gnu)
> man cargo  # 1st line in pager if we did not do optional step 3
CARGO(1)                                                              CARGO(1)
> man cargo  # last line in less pager
 Manual page cargo(1-stable-x86_64-unknown-linux-gnu) line 1 (press h for help or q to quit)

Side note, I don't like why CARGO in the first line is SCREAMING_SNAKE_CASE, I wish it is cargo like the other man pages which is snake_case.

This way, if the user types in man cargo they might see it for any man page for any toolchain they installed, if they wish to see the specific man page they are in, they can man 1-nightly-x86_64-unknown-linux-gnu cargo or rustup man cargo. This provides easy access to man pages in fish shell by pressing alt-h. The downside is they may not see the correct man page for the toolchain at first, we could add it in NOTES section regarding this.

[workingjubilee]

@rustbot label: +O-linux

[louwers]

This is also a problem on macOS.

[djc]

Added the macOS label, too.

[wezm]

@djc may as well add O-bsd while you're at it

[cheako]

Does this not affect everything POSIX?

[wezm]

Does this not affect everything POSIX?

Yes. There is no O-unix or O-posix label though (there is O-bsd).

[tritoke]

Would a solution like this work: When rustup is working with an official toolchain, e.g. stable/nightly and the default changes create a symlink from rustup home/man to toolchains/<new_default>/share/man. This way if a user wants to add to MANPATH themself they can add rustup home/man to the man path? this at least gives a way to consistently get the "current" toolchains directly through man instead of via rustup man.

[cheako]

I don't get why ~/.cargo/env changes PATH, but don't you dare touch MANPATH and instead devise clever workarounds :/