Rollup merge of #142372 - Urgau:improve-remap_path_prefix-doc, r=wesleywiser

Improve `--remap-path-prefix` documentation

This PR improves the `--remap-path-prefix` documentation by:
 - moving it into it's own page
 - adding a small example
 - mentioning that the remapping is best effort[^1]
 - mentioning `link.exe`/PDB issues[^2]
 - mentioning the path separator issue (textual replacement)

r? ``@wesleywiser``

[^1]: [#t-compiler > link.exe leaking paths in Windows PDB @ 💬](https://rust-lang.zulipchat.com/#narrow/channel/131828-t-compiler/topic/link.2Eexe.20leaking.20paths.20in.20Windows.20PDB/near/523343774)
[^2]: [#t-compiler > link.exe leaking paths in Windows PDB @ 💬](https://rust-lang.zulipchat.com/#narrow/channel/131828-t-compiler/topic/link.2Eexe.20leaking.20paths.20in.20Windows.20PDB/near/523331762)

3 files changed, 61 insertions, 14 deletions

diff --git a/src/doc/rustc/src/SUMMARY.md b/src/doc/rustc/src/SUMMARY.md
index b942e4bfa61..b53494ed98d 100644
--- a/src/doc/rustc/src/SUMMARY.md
+++ b/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)
diff --git a/src/doc/rustc/src/command-line-arguments.md b/src/doc/rustc/src/command-line-arguments.md
index d45ad1be27b..0b15fbc24df 100644
--- a/src/doc/rustc/src/command-line-arguments.md
+++ b/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) section of this book for
+further details and explanation.
 
 <a id="option-json"></a>
 ## `--json`: configure json messages printed by the compiler
diff --git a/src/doc/rustc/src/remap-source-paths.md b/src/doc/rustc/src/remap-source-paths.md
new file mode 100644
index 00000000000..03f5d98091c
--- /dev/null
+++ b/src/doc/rustc/src/remap-source-paths.md
@@ -0,0 +1,53 @@
+# Remap source paths
+
+`rustc` supports remapping source paths prefixes **as a best effort** in all compiler generated
+output, including compiler diagnostics, debugging information, macro expansions, etc.
+
+This is useful for normalizing build products, for example by removing the current directory
+out of the paths emitted into object files.
+
+The remapping 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 like `x86_64-pc-windows-msvc`, the linker may embed absolute host paths and compiler
+arguments into debug info files (like `.pdb`) independently of `rustc`.
+
+Additionally, on Apple platforms, linkers generate [OSO entries] which are not remapped by the compiler
+and need to be manually remapped with `-oso_prefix`.
+
+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 may still contain un-remapped paths.
+
+[OSO entries]: https://wiki.dwarfstd.org/Apple%27s_%22Lazy%22_DWARF_Scheme.md