make error messages a bit shorter

pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/redirects.py

@@ -24,74 +24,48 @@ def __str__(self):
         error_messages = []
         if self.conflicting_anchors:
             error_messages.append(f"""
-**Conflicting Anchors Found**
 Identifiers must not be identical to any historical location's anchor of the same output path.
+    The following identifiers violate this rule:
+    - {"\n    - ".join(self.conflicting_anchors)}
 
-The following identifiers violate the above rule:
-- {"\n- ".join(self.conflicting_anchors)}
-
-This can generally happen when:
-- An identifier was added
-
-This is problematic because:
-- It can cause confusion and potentially break links or redirects.
+    This can break links or redirects. If you added new content, choose a different identifier.
 """)
         if self.divergent_redirects:
             error_messages.append(f"""
-**Divergent Redirects Found**
-A given historical path must correspond to only one identifier.
-
-The following paths violate the above rule:
-- {"\n- ".join(self.divergent_redirects)}
-
-This can generally happen when:
-- A redirect was added
+All historical content locations must correspond to exactly one identifier.
+    The following locations violate this rule:
+    - {"\n    - ".join(self.divergent_redirects)}
 
-This is problematic because:
-- It leads to inconsistent behavior depending on which redirect is applied.
+    It leads to inconsistent behavior depending on which redirect is applied.
+    Please update doc/redirects.json or nixos/doc/manual/redirects.json!
 """)
         if self.identifiers_missing_current_outpath:
             error_messages.append(f"""
-**Invalid Current Paths Found**
-The head element of an identifier's corresponding historical location must be its current output location.
+The first element of an identifier's redirects list must denote its current location.
+    The following identifiers violate this rule:
+    - {"\n    - ".join(self.identifiers_missing_current_outpath)}
 
-The following identifiers violate the above rule:
-- {"\n- ".join(self.identifiers_missing_current_outpath)}
-
-This is problematic because:
-- We use the head of each historical locations list to track if an identifier moved across to another output location.
-""")
+    If you moved content, add its new location as the first element of the redirects mapping.
+    Please update doc/redirects.json or nixos/doc/manual/redirects.json!
+""") # TODO: automatically detect if you just missed adding a new location, and make a tool to do that for you
         if self.identifiers_without_redirects:
             error_messages.append(f"""
-**Redirects Missing**
-Identifiers present in the source must have a mapping in the redirects.
-
-The following identifiers violate the above rule:
-- {"\n- ".join(self.identifiers_without_redirects)}
+Identifiers present in the source must have a mapping in the redirects file.
+    - {"\n    - ".join(self.identifiers_without_redirects)}
 
-This can generally happen when:
-- An identifier was added
-- An identifier was renamed
-
-This is problematic because:
-- We cannot track the movement of identifiers reliably if we don't have a reference point.
-""")
+    This can happen when an identifier was added or renamed.
+    Please update doc/redirects.json or nixos/doc/manual/redirects.json!
+""") # TODO: add tooling in the development shell to do that automatically and point to that command
         if self.orphan_identifiers:
             error_messages.append(f"""
-**Orphan Identifiers Found**
 Keys of the redirects mapping must correspond to some identifier in the source.
+    - {"\n    - ".join(self.orphan_identifiers)}
 
-The following identifiers violate the above rule:
-- {"\n- ".join(self.orphan_identifiers)}
-
-This can generally happen when:
-- An identifier was removed
-- An identifier was renamed
-""")
-
+    This can happen when an identifier was removed or renamed.
+    Please update doc/redirects.json or nixos/doc/manual/redirects.json!
+""") # TODO: add tooling in the development shell to do that automatically and point to that command
         return "\n".join(error_messages)
 
-
 @dataclass
 class Redirects:
     _raw_redirects: dict[str, list[str]]