From ec71d0da98aa4e9fab4e84701512ef3e2930b884 Mon Sep 17 00:00:00 2001
From: pennae <github@quasiparticle.net>
Date: Sat, 16 Mar 2024 11:13:18 +0100
Subject: [PATCH] docs/nrd: move make_xml_id to manual_structure

since we don't want to break links and changing the id generation scheme
would Very Break links this id generation function is unfortunately
somewhat part of the manual structure now, so we may as well put it there.
---
 .../src/nixos_render_docs/docbook.py            | 13 -------------
 .../src/nixos_render_docs/manual.py             |  4 ++--
 .../src/nixos_render_docs/manual_structure.py   | 17 +++++++++++++++++
 .../src/nixos_render_docs/options.py            |  4 ++--
 4 files changed, 21 insertions(+), 17 deletions(-)

diff --git a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/docbook.py b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/docbook.py
index d54392cca553..671cc24e0673 100644
--- a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/docbook.py
+++ b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/docbook.py
@@ -6,19 +6,6 @@ from xml.sax.saxutils import escape, quoteattr
 
 from .md import Renderer
 
-_xml_id_translate_table = {
-    ord('*'): ord('_'),
-    ord('<'): ord('_'),
-    ord(' '): ord('_'),
-    ord('>'): ord('_'),
-    ord('['): ord('_'),
-    ord(']'): ord('_'),
-    ord(':'): ord('_'),
-    ord('"'): ord('_'),
-}
-def make_xml_id(s: str) -> str:
-    return s.translate(_xml_id_translate_table)
-
 class Deflist:
     has_dd = False
 
diff --git a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manual.py b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manual.py
index c72a9d53cd18..af2c5af0b153 100644
--- a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manual.py
+++ b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manual.py
@@ -13,9 +13,9 @@ from typing import Any, Callable, cast, ClassVar, Generic, get_args, NamedTuple
 from markdown_it.token import Token
 
 from . import md, options
-from .docbook import DocBookRenderer, Heading, make_xml_id
+from .docbook import DocBookRenderer, Heading
 from .html import HTMLRenderer, UnresolvedXrefError
-from .manual_structure import check_structure, FragmentType, is_include, TocEntry, TocEntryType, XrefTarget
+from .manual_structure import check_structure, FragmentType, is_include, make_xml_id, TocEntry, TocEntryType, XrefTarget
 from .md import Converter, Renderer
 
 class BaseConverter(Converter[md.TR], Generic[md.TR]):
diff --git a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manual_structure.py b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manual_structure.py
index c6e6bf429370..724ca4b72707 100644
--- a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manual_structure.py
+++ b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manual_structure.py
@@ -201,3 +201,20 @@ class TocEntry(Freezeable):
         while len(entries) > 1:
             entries[-2][1].children.append(entries.pop()[1])
         return (entries[0][1], examples, figures)
+
+_xml_id_translate_table = {
+    ord('*'): ord('_'),
+    ord('<'): ord('_'),
+    ord(' '): ord('_'),
+    ord('>'): ord('_'),
+    ord('['): ord('_'),
+    ord(']'): ord('_'),
+    ord(':'): ord('_'),
+    ord('"'): ord('_'),
+}
+# this function is needed to generate option id attributes in the same format as
+# the docbook toolchain did to not break existing links. we don't actually use
+# xml any more, that's just the legacy we're dealing with and part of our structure
+# now.
+def make_xml_id(s: str) -> str:
+    return s.translate(_xml_id_translate_table)
diff --git a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/options.py b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/options.py
index 9a00da567fa9..699164c8a1a8 100644
--- a/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/options.py
+++ b/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/options.py
@@ -17,10 +17,10 @@ from . import md
 from . import parallel
 from .asciidoc import AsciiDocRenderer, asciidoc_escape
 from .commonmark import CommonMarkRenderer
-from .docbook import DocBookRenderer, make_xml_id
+from .docbook import DocBookRenderer
 from .html import HTMLRenderer
 from .manpage import ManpageRenderer, man_escape
-from .manual_structure import XrefTarget
+from .manual_structure import make_xml_id, XrefTarget
 from .md import Converter, md_escape, md_make_code
 from .types import OptionLoc, Option, RenderedOption