docs(user-guide): cover correct $PATH configuration for proxies

Author: rami3l

doc/user-guide/src/installation/already-installed-rust.md

@@ -7,6 +7,8 @@ will complain that you already have Rust installed in `/usr` and refuse to
 install. However, you can install Rust via `rustup` and have it coexist with
 your packaged Rust toolchain.
 
+## Set up rustup with an existing Rust toolchain
+
 When you initially install Rust with `rustup`, pass the `-y` option to make it
 ignore the packaged Rust toolchain and install a `rustup`-managed toolchain
 into `~/.cargo/bin`. Add that directory to your `$PATH` (or let `rustup` do it
@@ -28,5 +30,57 @@ you may want to make it your [default toolchain]:
 rustup default system
 ```
 
+## Ensure the correct `$PATH` configuration
+
+There are times when the above steps don't work, and you may see strange error
+messages when running commands that should have been proxied by rustup.
+For example, when running `cargo +stable --version`, you may encounter the
+following error:
+
+```text
+error: no such command: `+stable`
+
+        Cargo does not handle `+toolchain` directives.
+        Did you mean to invoke `cargo` through `rustup` instead?
+```
+
+This means `cargo` is currently not a `rustup` proxy, and your `$PATH` needs
+to be fixed.
+
+In fact, on any machine with rustup installed, you would expect **rustup
+proxies to come first in `$PATH`**, shadowing any other Rust installations.
+Don't worry: these shadowed installations can then be adopted by rustup with the
+`rustup toolchain link` command as mentioned above.
+
+The exact steps to be taken to address the `$PATH` issue may vary according to your
+system environment, but usually it is about changing the evaluation order of certain
+lines in your shell configuration file(s).
+
+To make it clearer, let's look at the example of a common conflict between the
+regular rustup downloaded from [rustup.rs] and homebrew-installed `rust` on macOS.
+In your `.profile`, you can probably find these two lines in this order:
+
+```bash
+. $HOME/.cargo/env
+eval $(/opt/homebrew/bin/brew shellenv)
+```
+
+In this example, both of these lines all _prepend_ to `$PATH`, so the last one
+takes over, letting the homebrew-installed `rust` shadow the rustup proxies,
+causing the error. At this point, it should be clear that exchanging these two
+lines will fix the issue.
+
+After the fix, the output of `cargo +stable --version` should be similar to one
+of the following, depending on whether you have had the `stable` toolchain installed:
+
+- ```text
+  cargo 1.85.1 (d73d2caf9 2024-12-31)
+  ```
+
+- ```text
+  error: toolchain 'stable' is not installed
+  ```
+
+[rustup.rs]: https://rustup.rs
 [toolchain override shorthand]: ../overrides.md#toolchain-override-shorthand
 [default toolchain]: ../overrides.md#default-toolchain

doc/user-guide/src/installation/other.md

@@ -63,14 +63,17 @@ After installing rustup with your favorite package manager, there are usually tw
   ```
 
   This will allow you to perform the initial setup of `rustup`, populate all the proxies
-  managed by rustup, and install a default toolchain. When the installation is completed,
-  please make sure that these proxies (usually under `$HOME/.cargo/bin`) are exposed via your `$PATH`.
+  managed by rustup, and install a default toolchain.
 
   > As of 2024/12/23, this is the case for
   > [DNF](https://developer.fedoraproject.org/tech/languages/rust/further-reading.html).
 
+When the installation is completed, please make sure that the rustup proxies
+(usually under `$HOME/.cargo/bin`) are [correctly exposed] via your `$PATH`.
 Now you should be able to run `rustup`, `rustc`, `cargo`, etc. normally.
 
+[correctly exposed]: ./already-installed-rust.html#ensure-the-correct-path-configuration
+
 ### APT
 
 Starting from Debian 13 (trixie) and Ubuntu 24.04 (noble),