Improve --remap-path-prefix documentation

Author: Urgau

src/doc/rustc/src/SUMMARY.md

@@ -23,6 +23,7 @@
 - [Linker-plugin-based LTO](linker-plugin-lto.md)
 - [Checking Conditional Configurations](check-cfg.md)
     - [Cargo Specifics](check-cfg/cargo-specifics.md)
+- [Remap source paths](remap-source-paths.md)
 - [Exploit Mitigations](exploit-mitigations.md)
 - [Symbol Mangling](symbol-mangling/index.md)
     - [v0 Symbol Format](symbol-mangling/v0.md)

src/doc/rustc/src/command-line-arguments.md

@@ -418,22 +418,15 @@ This flag takes a number that specifies the width of the terminal in characters.
 Formatting of diagnostics will take the width into consideration to make them better fit on the screen.
 
 <a id="option-remap-path-prefix"></a>
-## `--remap-path-prefix`: remap source names in output
+## `--remap-path-prefix`: remap source paths in output
 
 Remap source path prefixes in all output, including compiler diagnostics,
-debug information, macro expansions, etc. It takes a value of the form
-`FROM=TO` where a path prefix equal to `FROM` is rewritten to the value `TO`.
-The `FROM` may itself contain an `=` symbol, but the `TO` value may not. This
-flag may be specified multiple times.
-
-This is useful for normalizing build products, for example by removing the
-current directory out of pathnames emitted into the object files. The
-replacement is purely textual, with no consideration of the current system's
-pathname syntax. For example `--remap-path-prefix foo=bar` will match
-`foo/lib.rs` but not `./foo/lib.rs`.
-
-When multiple remappings are given and several of them match, the **last**
-matching one is applied.
+debug information, macro expansions, etc. It takes a value of the form `FROM=TO`
+where a path prefix equal to `FROM` is rewritten to the value `TO`. This flag may be
+specified multiple times.
+
+Refer to the [Remap source paths](remap-source-paths.md) of this book for
+further details and explanation.
 
 <a id="option-json"></a>
 ## `--json`: configure json messages printed by the compiler

src/doc/rustc/src/remap-source-paths.md

@@ -0,0 +1,43 @@
+# Remap source paths
+
+`rustc` supports remaping source paths prefixes *(as a best effort)* in all output, including
+compiler diagnostics, debug information, macro expansions, etc.
+
+This is useful for normalizing build products, for example by removing the current directory
+out of the paths emitted into the object files.
+
+The remaping is done via the `--remap-path-prefix` option.
+
+## `--remap-path-prefix`
+
+It takes a value of the form `FROM=TO` where a path prefix equal to `FROM` is rewritten
+to the value `TO`. `FROM` may itself contain an `=` symbol, but `TO` value may not.
+
+The replacement is purely textual, with no consideration of the current system's path separator.
+
+When multiple remappings are given and several of them match, the **last** matching one is applied.
+
+### Example
+
+```bash
+rustc --remap-path-prefix "/home/user/project=/redacted"
+```
+
+This example replaces all occurrences of `/home/user/project` in emitted paths with `/redacted`.
+
+## Caveats and Limitations
+
+- **Linkers generated paths**: On some platforms, especially Windows, the linker (such as `link.exe`)
+  may embed absolute host paths and compiler arguments into debug info files (like `.pdb`) independently
+  of rustc.
+
+  The `--remap-path-prefix` option does not affect these linker-generated paths.
+
+- **Textual replacement only**: The remapping is strictly textual and does not account for different
+  path separator conventions across platforms. Care must be taken when specifying prefixes, especially
+  on Windows where both `/` and `\` may appear in paths.
+
+- **External tools**: Paths introduced by external tools or environment
+  variables may not be covered by `--remap-path-prefix` unless explicitly accounted for.
+
+  For example, generated code introduced by Cargo's build script.