From 613dbb35dbc142fd5cadca847f8677e64a502bfa Mon Sep 17 00:00:00 2001
From: Viktor Kronvall <viktor.kronvall@gmail.com>
Date: Thu, 7 Dec 2023 21:36:39 +0900
Subject: [PATCH] docs: rename generated manual to `index.xhtml`

The `nixos-render-docs` tool outputs XHTML formatted content. In
order to convince browsers like `firefox` to treat the data as XHTML
the extension must be `.xhtml` and not `.html`.

Using the XHTML-formatted content as HTML is mainly an issue with
self-closing `<a />` tags.
---
 docs/home-manager-manual.nix         | 12 +++++++++---
 docs/html-open-tool.nix              | 12 ++++++++----
 tests/modules/misc/manual/manual.nix |  2 +-
 3 files changed, 18 insertions(+), 8 deletions(-)

diff --git a/docs/home-manager-manual.nix b/docs/home-manager-manual.nix
index 903456ecf..504cf2651 100644
--- a/docs/home-manager-manual.nix
+++ b/docs/home-manager-manual.nix
@@ -1,5 +1,11 @@
-{ stdenv, lib, documentation-highlighter, nmd, revision, home-manager-options
-, nixos-render-docs }:
+{ stdenv
+, lib
+, documentation-highlighter
+, nmd
+, revision
+, home-manager-options
+, nixos-render-docs
+}:
 let outputPath = "share/doc/home-manager";
 in stdenv.mkDerivation {
   name = "home-manager-manual";
@@ -46,7 +52,7 @@ in stdenv.mkDerivation {
       --toc-depth 1 \
       --section-toc-depth 1 \
       manual.md \
-      out/index.html
+      out/index.xhtml
   '';
 
   installPhase = ''
diff --git a/docs/html-open-tool.nix b/docs/html-open-tool.nix
index 9cdd27601..6154caf13 100644
--- a/docs/html-open-tool.nix
+++ b/docs/html-open-tool.nix
@@ -1,6 +1,9 @@
 { writeShellScriptBin, makeDesktopItem, symlinkJoin }:
-{ html, pathName ? "home-manager", projectName ? pathName
-, name ? "${pathName}-help" }:
+{ html
+, pathName ? "home-manager"
+, projectName ? pathName
+, name ? "${pathName}-help"
+}:
 let
   helpScript = writeShellScriptBin name ''
     set -euo pipefail
@@ -18,7 +21,7 @@ let
       echo "$0: unable to start a web browser; please set \$BROWSER"
       exit 1
     else
-      exec "$BROWSER" "${html}/share/doc/${pathName}/index.html"
+      exec "$BROWSER" "${html}/share/doc/${pathName}/index.xhtml"
     fi
   '';
 
@@ -30,7 +33,8 @@ let
     exec = "${helpScript}/bin/${name}";
     categories = [ "System" ];
   };
-in symlinkJoin {
+in
+symlinkJoin {
   inherit name;
   paths = [ helpScript desktopItem ];
 }
diff --git a/tests/modules/misc/manual/manual.nix b/tests/modules/misc/manual/manual.nix
index c7f67a517..a6bd58bee 100644
--- a/tests/modules/misc/manual/manual.nix
+++ b/tests/modules/misc/manual/manual.nix
@@ -9,7 +9,7 @@
     };
 
     nmt.script = ''
-      assertFileExists home-path/share/doc/home-manager/index.html
+      assertFileExists home-path/share/doc/home-manager/index.xhtml
       assertFileExists home-path/share/doc/home-manager/options.html
       assertFileExists home-path/share/doc/home-manager/options.json
       assertFileExists home-path/share/man/man1/home-manager.1