Add some more detail on compiletest normalization.

src/tests/adding.md

@@ -136,6 +136,9 @@ Some examples of `X` in `ignore-X`:
 * Stage: `stage0`, `stage1`, `stage2`.
 * When cross compiling: `cross-compile`
 * When remote testing is used: `remote`
+* When debug-assertions are enabled: `debug`
+* When particular debuggers are being tested: `cdb`, `gdb`, `lldb`
+* Specific compare modes: `compare-mode-nll`, `compare-mode-polonius`
 
 ### Other Header Commands
 
@@ -360,12 +363,43 @@ you can even run the resulting program. Just add one of the following
 
 ### Normalization
 
-The normalization applied is aimed at eliminating output difference
+The compiler output is normalized to eliminate output difference between
-between platforms, mainly about filenames:
+platforms, mainly about filenames.
 
-- the test directory is replaced with `$DIR`
+The following strings replace their corresponding values:
-- all backslashes (`\`) are converted to forward slashes (`/`) (for Windows)
+
-- all CR LF newlines are converted to LF
+- `$DIR`: The directory where the test is defined.
+  - Example: `/path/to/rust/src/test/ui/error-codes`
+- `$SRC_DIR`: The root source directory.
+  - Example: `/path/to/rust/src`
+- `$TEST_BUILD_DIR`: The base directory where the test's output goes.
+  - Example: `/path/to/rust/build/x86_64-unknown-linux-gnu/test/ui`
+
+Additionally, the following changes are made:
+
+- Line and column numbers for paths in `$SRC_DIR` are replaced with `LL:CC`.
+  For example, `/path/to/rust/src/libcore/clone.rs:122:8` is replaced with
+  `$SRC_DIR/libcore/clone.rs:LL:COL`.
+
+  Note: The line and column numbers for `-->` lines pointing to the test are
+  *not* normalized, and left as-is. This ensures that the compiler continues
+  to point to the correct location, and keeps the stderr files readable.
+  Ideally all line/column information would be retained, but small changes to
+  the source causes large diffs, and more frequent merge conflicts and test
+  errors. See also `-Z ui-testing` below which applies additional line number
+  normalization.
+- `\t` is replaced with an actual tab character.
+- Error line annotations like `// ~ERROR some message` are removed.
+- Backslashes (`\`) are converted to forward slashes (`/`) within paths (using
+  a heuristic). This helps normalize differences with Windows-style paths.
+- CRLF newlines are converted to LF.
+
+Additionally, the compiler is run with the `-Z ui-testing` flag which causes
+the compiler itself to apply some changes to the diagnostic output to make it
+more suitable for UI testing. For example, it will anonymize line numbers in
+the output (line numbers prefixing each source line are replaced with `LL`).
+In extremely rare situations, this mode can be disabled with the header
+command `// compile-flags: -Z ui-testing=no`.
 
 Sometimes these built-in normalizations are not enough. In such cases, you
 may provide custom normalization rules using the header commands, e.g.
@@ -399,6 +433,6 @@ concrete usage example.
 [`main.stderr`]: https://github.com/rust-lang/rust/blob/master/src/test/ui/transmute/main.stderr
 
 Besides `normalize-stderr-32bit` and `-64bit`, one may use any target
-information or stage supported by `ignore-X` here as well (e.g.
+information or stage supported by [`ignore-X`](#ignoring-tests) here as well (e.g.
 `normalize-stderr-windows` or simply `normalize-stderr-test` for unconditional
 replacement).