nixos-render-docs: add options manpage converter

mdoc is just too slow to render on groff, and semantic markup doesn't
help us any for generated pages.

this produces a lot of changes to configuration.nix.5, but only few
rendering changes. most of those seem to be place losing a space where
docbook emitted roff code that did not faithfully represent the input
text, though a few places also gained space where docbook dropped them.
notably we also don't need the compatibility code docbook-xsl emitted
because that problem was fixed over a decade ago.

this will handle block quotes, which the docbook stylesheets turned into
a mess of roff requests that ended up showing up in the output instead
of being processed.

1 files changed, 25 insertions, 10 deletions

diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix
index 342834e257a..9dab1738abe 100644
--- a/nixos/doc/manual/default.nix
+++ b/nixos/doc/manual/default.nix
@@ -21,6 +21,8 @@ let
     withManOptDedupPatch = true;
   };
 
+  manpageUrls = pkgs.path + "/doc/manpage-urls.json";
+
   # We need to strip references to /nix/store/* from options,
   # including any `extraSources` if some modules came from elsewhere,
   # or else the build will fail.
@@ -72,7 +74,7 @@ let
     nativeBuildInputs = [ pkgs.nixos-render-docs ];
   } ''
     nixos-render-docs manual docbook \
-      --manpage-urls ${pkgs.path + "/doc/manpage-urls.json"} \
+      --manpage-urls ${manpageUrls} \
       "$out" \
       --section \
         --section-id modules \
@@ -255,9 +257,12 @@ in rec {
   manpages = runCommand "nixos-manpages"
     { inherit sources;
       nativeBuildInputs = [
+        buildPackages.installShellFiles
+      ] ++ lib.optionals allowDocBook [
         buildPackages.libxml2.bin
         buildPackages.libxslt.bin
-        buildPackages.installShellFiles
+      ] ++ lib.optionals (! allowDocBook) [
+        buildPackages.nixos-render-docs
       ];
       allowedReferences = ["out"];
     }
@@ -265,14 +270,24 @@ in rec {
       # Generate manpages.
       mkdir -p $out/share/man/man8
       installManPage ${./manpages}/*
-      xsltproc --nonet \
-        --maxdepth 6000 \
-        --param man.output.in.separate.dir 1 \
-        --param man.output.base.dir "'$out/share/man/'" \
-        --param man.endnotes.are.numbered 0 \
-        --param man.break.after.slash 1 \
-        ${docbook_xsl_ns}/xml/xsl/docbook/manpages/docbook.xsl \
-        ${manual-combined}/man-pages-combined.xml
+      ${if allowDocBook
+        then ''
+          xsltproc --nonet \
+            --maxdepth 6000 \
+            --param man.output.in.separate.dir 1 \
+            --param man.output.base.dir "'$out/share/man/'" \
+            --param man.endnotes.are.numbered 0 \
+            --param man.break.after.slash 1 \
+            ${docbook_xsl_ns}/xml/xsl/docbook/manpages/docbook.xsl \
+            ${manual-combined}/man-pages-combined.xml
+        ''
+        else ''
+          mkdir -p $out/share/man/man5
+          nixos-render-docs options manpage \
+            --revision ${lib.escapeShellArg revision} \
+            ${optionsJSON}/share/doc/nixos/options.json \
+            $out/share/man/man5/configuration.nix.5
+        ''}
     '';
 
 }