From 54df89f601b3b4502a5c99173c9563495265d7e7 Mon Sep 17 00:00:00 2001
From: helle <helle@h3l.li>
Date: Wed, 26 Nov 2025 21:27:44 +0100
Subject: [PATCH] docs build system: Fixed manual to be compatible with mdbook
 0.5.x

Maintains compatibility with mdbook 0.4.x.

Includes comments for what to remove once 0.5.x is the only we care
about. Some other changes technically could be changed at that point,
but currently serve to enable universal support of 0.4.x and 0.5.x

Fixes #1051.

Change-Id: Ic5b405038d180bcd357bbd9e5716879e0c26e5f5
---
 doc/manual/anchors.jq    |  6 +++---
 doc/manual/book.toml     | 11 ++++++-----
 doc/manual/meson.build   |  6 ++++--
 doc/manual/substitute.py |  9 +++++----
 package.nix              |  5 ++++-
 5 files changed, 22 insertions(+), 15 deletions(-)

diff --git a/doc/manual/anchors.jq b/doc/manual/anchors.jq
index 72309779c..4fd944958 100644
--- a/doc/manual/anchors.jq
+++ b/doc/manual/anchors.jq
@@ -24,8 +24,8 @@ def map_contents_recursively(transformer):
 def process_command:
     .[0] as $context |
     .[1] as $body |
-    $body + {
-        sections: $body.sections | map(map_contents_recursively(if $context.renderer == "html" then transform_anchors_html else transform_anchors_strip end)),
-    };
+	# XXX FUTURE: drop sections once mdBook is at 0.5.0 or above in nixpkgs
+	$body | (.items? // .sections) |= map(map_contents_recursively(if $context.renderer == "html" then transform_anchors_html else transform_anchors_strip end))
+	;
 
 process_command
diff --git a/doc/manual/book.toml b/doc/manual/book.toml
index 228d6328e..f070922bd 100644
--- a/doc/manual/book.toml
+++ b/doc/manual/book.toml
@@ -22,20 +22,21 @@ fold.level = 30
 # not want to disable the links preprocessor entirely though because that requires
 # disabling *all* built-in preprocessors and selectively reenabling those we want.
 [preprocessor.substitute]
-command = "python3 doc/manual/substitute.py"
+command = "python3 substitute.py"
 before = ["anchors", "links"]
 
 [preprocessor.anchors]
 renderers = ["html"]
-command = "jq --from-file doc/manual/anchors.jq"
+command = "jq --from-file anchors.jq"
 
 [output.markdown]
 
-[output.linkcheck]
+# XXX FUTURE: may be reenabled once mdBook 0.5.0 or above and matching mdbook-linkchecker are in nixpkgs
+#[output.linkcheck]
 # no Internet during the build (in the sandbox)
-follow-web-links = false
+#follow-web-links = false
 
 # mdbook-linkcheck does not understand [foo]{#bar} style links, resulting in
 # excessive "Potential incomplete link" warnings. No other kind of warning was
 # produced at the time of writing.
-warning-policy = "ignore"
+#warning-policy = "ignore"
diff --git a/doc/manual/meson.build b/doc/manual/meson.build
index f7763d19a..85a5bb802 100644
--- a/doc/manual/meson.build
+++ b/doc/manual/meson.build
@@ -42,8 +42,9 @@ manual = custom_target(
     '-c',
     '''
         @0@ @INPUT0@ @CURRENT_SOURCE_DIR@ > @DEPFILE@
+        cd @3@
+        @1@ build . -d @2@ | { grep -Fv "because fragment resolution isn't implemented" || :; }
         cd @SOURCE_ROOT@
-        @1@ build doc/manual -d @2@ | { grep -Fv "because fragment resolution isn't implemented" || :; }
         rm -rf @2@/manual
         mv @2@/html @2@/manual
         find @2@/manual -iname meson.build -delete
@@ -51,6 +52,7 @@ manual = custom_target(
       python.full_path(),
       mdbook.full_path(),
       meson.current_build_dir(),
+      meson.current_source_dir()
     ),
   ],
   input : [
@@ -81,7 +83,7 @@ manual = custom_target(
   depfile : 'manual.d',
   env : {
     'RUST_LOG': 'info',
-    'MDBOOK_SUBSTITUTE_SEARCH': meson.current_build_dir() / 'src',
+    'MANUAL_SUBSTITUTE_SEARCH': meson.current_build_dir() / 'src',
   },
 )
 manual_md = manual[1]
diff --git a/doc/manual/substitute.py b/doc/manual/substitute.py
index 6a140305e..d14c4ca13 100755
--- a/doc/manual/substitute.py
+++ b/doc/manual/substitute.py
@@ -70,9 +70,10 @@ def do_include(content: str, relative_md_path: Path, source_root: Path, search_p
 
 def recursive_replace(data, book_root, search_path):
     match data:
-        case {'sections': sections}:
+        # XXX FUTURE: drop sections once mdBook is at 0.5.0 or above in nixpkgs
+        case {'sections': items} | {'items': items}:
             return data | dict(
-                sections = [recursive_replace(section, book_root, search_path) for section in sections],
+                items = [recursive_replace(item, book_root, search_path) for item in items],
             )
         case {'Chapter': chapter}:
             path_to_chapter = Path(chapter['path'])
@@ -119,10 +120,10 @@ def main():
     context, book = json.load(sys.stdin)
 
     # book_root is the directory where book contents leave (ie, src/)
-    book_root = Path(context['root']) / context['config']['book']['src']
+    book_root = Path(context['root']) / context['config']['book'].get('src', 'src')
 
     # includes pointing into @generated@ will look here
-    search_path = Path(os.environ['MDBOOK_SUBSTITUTE_SEARCH'])
+    search_path = Path(os.environ['MANUAL_SUBSTITUTE_SEARCH'])
 
     # Find @var@ in all parts of our recursive book structure.
     replaced_content = recursive_replace(book, book_root, search_path)
diff --git a/package.nix b/package.nix
index 94f435fb9..f8a3e46e1 100644
--- a/package.nix
+++ b/package.nix
@@ -335,7 +335,10 @@ stdenv.mkDerivation (finalAttrs: {
   ]
   ++ [
     (lib.getBin lowdown-unsandboxed)
-    mdbook
+    (lib.warnIf (lib.versionAtLeast mdbook.version "0.5.0")
+      "Workarounds for mdbook 0.4.x/0.5.x interoperability can be removed when 0.5.0 or above is in nixpkgs-stable"
+      mdbook
+    )
     mdbook-linkcheck
   ]
   ++ [