deprecated-features: Rewrite feature descriptions

Changed the writing style of the descriptions, expanded with more
examples and rationale, and added the new timline metadata in the
frontmatter.

Change-Id: I218389e3504fc21f4eb45a927e77a41a1a70d4f5

lix/libutil/deprecated-features/ancient-let.md

@@ -1,7 +1,12 @@
 ---
 name: ancient-let
 internalName: AncientLet
+timeline:
+  - date: 2024-09-18
+    release: 2.92.0
+    cls: [1787]
+    message: Introduced as soft deprecation with a warning.
 ---
-Allow the ancient `let { body = …; … }` syntax.
+The ancient `let { body = …; … }` syntax is deprecated.
 
 Use the `let … in` syntax instead.

lix/libutil/deprecated-features/cr-line-endings.md

@@ -1,6 +1,16 @@
 ---
 name: cr-line-endings
 internalName: CRLineEndings
+timeline:
+  - date: 2025-02-05
+    release: 2.93.0
+    cls: [2475]
+    message: Introduced as a parser error.
 ---
-Allow CR (`\r`) and CRLF (`\r\n`) as line delimiters.
-Note however that the implementation is inconsistent and buggy and may lead to unexpected evaluation results with certain strings.
+CR (`\r`) and CRLF (`\r\n`) are deprecated as line delimiters in Nix code.
+The reason for the CR line ending deprecation is that no OS still uses them anymore.
+The reason for the CRLF line ending deprecation is that there is a fatal bug in the indentation-stripping logic of indented strings,
+breaking all indented strings when CRLF indentation is used.
+In a future language revision, the CRLF line endings will be allowed again but with fixed semantics.
+
+To fix this, convert all files to have regular `\n` endings and disable all software which performs platform-specific normalizations.

lix/libutil/deprecated-features/nix-path-shadow.md

@@ -1,6 +1,12 @@
 ---
 name: nix-path-shadow
 internalName: NixPathShadow
+timeline:
+  - date: 2025-11-23
+    release: 2.95.0
+    cls: [4632]
+    message: Introduced as an evaluation-time warning.
 ---
 
-Allows shadowing `<nix/fetchurl.nix>` by configuration of the [*nix path*](@docroot@/language/builtin-constants.html#builtins-nixPath) to a value containing `nix=/some/path`.
+Shadowing `<nix/fetchurl.nix>` by configuring the [*nix path*](@docroot@/language/builtin-constants.html#builtins-nixPath) to a value containing `nix=/some/path` is deprecated.
+The namespace `nix` in the Nix path is reserved for usage in internal code, and overriding it may result in nontrivial breakage.

lix/libutil/deprecated-features/nul-bytes.md

@@ -1,6 +1,10 @@
 ---
 name: nul-bytes
 internalName: NulBytes
+timeline:
+  - date: 2025-02-05.
+    release: 2.93.0
+    cls: [2476]
+    message: Introduced as a parser error.
 ---
-Allow NUL bytes (`\0`) in Nix strings.
-Note however that due to Nix using NUL-terminated strings internally, this may cause undefined behavior.
+Raw NUL bytes (`\0`) in Nix string literals are deprecated.

lix/libutil/deprecated-features/rec-set-overrides.md

@@ -1,7 +1,13 @@
 ---
 name: rec-set-overrides
 internalName: RecSetOverrides
+timeline:
+  - date: 2024-09-18
+    release: 2.92.0
+    cls: [1744]
+    message: Introduced as soft deprecation with a warning.
 ---
-Allow `__overrides` in recursive attribute sets.
+The magic symbol `__overrides` in recursive attribute sets is deprecated.
+It was introduced in the early days of the language before the widespread use of overlays and is not needed anymore.
 
-Use fix point functions (e.g. `lib.fix` in Nixpkgs) instead.
+To fix this, use fix point functions (e.g. `lib.fix` in Nixpkgs) instead.

lix/libutil/deprecated-features/shadow-internal-symbols.md

@@ -1,5 +1,26 @@
 ---
 name: shadow-internal-symbols
 internalName: ShadowInternalSymbols
+timeline:
+  - date: 2024-11-18
+    release: 2.92.0
+    cls: [2206, 2295]
+    message:
+      Introduced as a parser error for the symbols `__sub`, `__mul`, `__div`, `__lessThan`.
 ---
-Allow shadowing the symbols `__sub`, `__mul`, `__div`, `__lessThan`, `__findFile` when used in the internal AST expansion. (`5 - 3` expands to `__sub 5 3` etc.)
+Shadowing symbol names used internally by the parser is deprecated.
+As an example, `5 - 3` internally expands to `__sub 5 3` in the parser.
+`__sub` is a symbol name in global scope, which could be shadowed by let bindings like any other.
+Shadowing internal symbols is deprecated because it can lead to confusing unintended semantics in code.
+Using this to override operators with custom implementations is not supported and will lead to unintended semantics.
+(For example, overriding `__lessThan` will be ignored within builtin functions that perform comparison operations like sorting.)
+
+Note that the check happens at usage site, so `let __sub = null; in body` remains allowed for as long as `body` does not contain a subtraction operation.
+Similarly, `let __sub = null; in __sub` remains allowed here because the explicit `__sub` usage is obvious and there is less potential for confusion.
+
+Affected symbol names:
+
+- `__sub`
+- `__mul`
+- `__div`
+- `__lessThan`

lix/libutil/deprecated-features/url-literals.md

@@ -1,5 +1,14 @@
 ---
 name: url-literals
 internalName: UrlLiterals
+timeline:
+  - date: 2024-08-17
+    release: 2.92.0
+    cls: [1785]
+    message: Removed the old `no-url-literals` experimental feature and turned it into a parse error by default.
 ---
-Allow unquoted URLs as part of the Nix language syntax.
+*URL literals* are unquoted string literals containing URLs directly as part of the Nix language syntax.
+This was deprecated because it needlessly complicates the syntax for the little benefit of merely saving two characters.
+Additionally, it is a cause of inconsistencies in the language: `x:x` is a (URL) string but `x: x` and `_:x` are functions.
+
+To fix this, put the URL in string quotation marks instead: `{ url = https://github.com/NixOS/nixpkgs; }` → `{ url = "https://github.com/NixOS/nixpkgs"; }`