feat: improve docs and render files that contain prefix with [prefix:text] or [prefix:bin] (#2031)

Author: wolfv

docs/understanding_terminal_output.md

@@ -404,7 +404,7 @@ Then, any license files matched by the globs given are copied into `info/license
 ```txt
  │ │ Files in package:
  │ │   ├─ bin/curl (198.28 KiB)
- │ │   ├─ bin/curl-config (8.92 KiB)
+ │ │   ├─ bin/curl-config (8.92 KiB) [prefix:text]
  │ │   ├─ include/curl/curl.h (124.84 KiB)
  │ │   ├─ include/curl/curlver.h (2.97 KiB)
  │ │   ├─ include/curl/easy.h (3.93 KiB)
@@ -419,7 +419,7 @@ Then, any license files matched by the globs given are copied into `info/license
  │ │   ├─ include/curl/websockets.h (2.68 KiB)
  │ │   ├─ lib/libcurl.4.dylib (541.50 KiB)
  │ │   ├─ lib/libcurl.dylib -> libcurl.4.dylib
- │ │   ├─ lib/pkgconfig/libcurl.pc (1.86 KiB)
+ │ │   ├─ lib/pkgconfig/libcurl.pc (1.86 KiB) [prefix:text]
  │ │   ├─ info/about.json (453 B)
  │ │   ├─ info/hash_input.json (32 B)
  │ │   ├─ info/index.json (253 B)
@@ -448,6 +448,12 @@ The files are highlighted:
 
 - green: executable
 - magenta: symlink (shows symlink target)
+- yellow brackets: files that contain the value of `$PREFIX` as a string (`[prefix:text]` or `[prefix:bin]`).
+
+Files that contain the $PREFIX (that is files that contain the current installation path, e.g. `/user/name/.../output/.../host_env_placehold_placehold...`) are marked with the yellow brackets. 
+
+When a file contains the $PREFIX as a string, it will be replaced at installation time with the actual installation prefix (that is also the reason for the long placeholder string!). You can read more about prefix replacement in [Debugging Builds](internals.md#making-packages-relocatable-with-rattler-build).
+Ideally, no file contains the installation prefix as string, so that there is no text replacement at installation time.
 
 We then see a listing of the largest files in the package which can be a helpful sanity check.
 

docs/windows_quirks.md

@@ -22,14 +22,16 @@ On the top level, there is an additional `Scripts` folder, as well as a `bin/` f
 Additionally, the site-packages folder is _also_ located at the root of the filesystem layout:
 
 ```text
-- Library\
-  - lib\
-  - bin\
-  - share\
-  ...
-- site-packages\
-- Scripts\
-- bin\
+%PREFIX%
+├── Library
+│   ├── lib
+│   ├── bin
+│   ├── share
+│   ├── etc
+│   └── ...
+├── site-packages
+├── Scripts
+└── bin
 ```
 
 The reasons for this layout are historical: Python on Windows traditionally installs packages to `site-packages` at the root, and `Scripts` is where Python console scripts and entry points are placed. The `Library` folder mimics a Unix-style hierarchy for non-Python packages.
@@ -40,15 +42,15 @@ To make this easier, certain shortcut env vars are available on Windows: `%LIBRA
 
 ### Cmd.exe
 
-The _default interpreter_ for build scripts on Windows is `cmd.exe` which has a quite clunky syntax and execution model. 
+The _default interpreter_ for build scripts on Windows is `cmd.exe` which has a quite clunky syntax and execution model.
 
 It will, for example, skip over errors if you do not manually insert `if %ERRORLEVEL% neq 0 exit 1` after each statement. If the build script is a list of commands, then rattler-build will automatically inject this after each list item. If you pass in a complete build script or file, you will have to do this manually to recognize issues in command execution early on.
 
 ### Using Powershell
 
 You can select PowerShell as an interpreter, which comes pre-installed on Windows these days. To do so, just set
 
-```
+```yaml title="recipe.yaml"
 build:
   script:
     interpreter: powershell
@@ -61,7 +63,7 @@ Or save your build script as `build.ps1` (which will automatically use powershel
 
 To use bash on Windows, you can install bash in your build requirements (e.g. on conda-forge it would be `m2-bash`) and call the bash script from a cmd.exe script:
 
-```batch
+```batch title="build.bat"
 bash %RECIPE_DIR%/build_win.sh
 if %ERRORLEVEL% neq 0 exit 1
 
@@ -90,6 +92,9 @@ Invoke-WebRequest -Uri "https://aka.ms/vs/17/release/vs_BuildTools.exe" -OutFile
 
 ## MinGW64 compiler stack
 
+!!! note conda-forge specific information
+    Everything that follows on this page is specific to `conda-forge` and choices this distribution made. If you run your own software distribution you might do things differently, or not have certain compilers available.
+
 As an alternative to MSVC, conda-forge provides a MinGW-based compiler stack for Windows. This can be useful when porting Unix software that relies on GCC-specific features or when you want to avoid MSVC licensing requirements.
 
 ### Using MinGW compilers in recipes
@@ -117,12 +122,13 @@ The MinGW C++ and Fortran compilers are **not ABI-compatible** with the default
 
 ### When to use MinGW vs MSVC
 
-| Use MinGW when... | Use MSVC when... |
-|-------------------|------------------|
-| Porting Unix/Linux software with GCC-specific code | Building native Windows applications |
-| The project uses GNU autotools extensively | Integrating with other MSVC-compiled libraries |
-| You need GCC-specific compiler extensions | Maximum compatibility with Windows ecosystem |
-| Building Fortran code (simpler than Flang setup) | Performance-critical Windows applications |
+| Use MinGW when...                                  | Use MSVC when...                               |
+| -------------------------------------------------- | ---------------------------------------------- |
+| Porting Unix/Linux software with GCC-specific code  | Building native Windows applications           |
+| The project uses GNU autotools extensively         | Integrating with other MSVC-compiled libraries |
+| You need GCC-specific compiler extensions           | Maximum compatibility with Windows ecosystem   |
+| Building Fortran code (simpler than Flang setup)   | Performance-critical Windows applications      |
+| Building R packages (requires MingW64)             |                                                |
 
 ### Legacy packages
 
@@ -136,10 +142,10 @@ Note that while Clang replaces the compiler itself, you still need the **Windows
 
 ### clang vs clang-cl
 
-| Frontend | Argument syntax | Use case |
-|----------|-----------------|----------|
-| `clang` | GCC-style arguments | Cross-platform builds, porting from Unix |
-| `clang-cl` | MSVC-style arguments | Drop-in replacement for MSVC's `cl.exe` |
+| Frontend   | Argument syntax      | Use case                                 |
+| ---------- | -------------------- | ---------------------------------------- |
+| `clang`    | GCC-style arguments  | Cross-platform builds, porting from Unix |
+| `clang-cl` | MSVC-style arguments | Drop-in replacement for MSVC's `cl.exe`  |
 
 ### Using Clang in recipes
 

mkdocs.yml

@@ -136,6 +136,7 @@ nav:
       - Creating patches: create_patch.md
       - Debugging builds: debugging_builds.md
       - Tips and tricks: tips_and_tricks.md
+      - Windows Quirks: windows_quirks.md
 
   - Testing:
       - Testing packages: testing.md