doc: separate manpage URLs from the Pandoc filter

Move the manpage-to-URL mapping to `doc/manpage-urls.json` so that we can
reuse that file elsewhere, and generate the `link-manpages.lua` filter from
that file.

Also modify the Pandoc filter so that it doesn't wrap manpages that are
already inside a link.

Keeping a Lua filter is essential for speed: a Python filter would
increase the runtime `md-to-db.sh` from ~20s to ~30s (but Python is not
to blame; marshalling Pandoc types to and from JSON is a costly operation).
Parsing in Lua seems tedious, so I went with the Nix way.

2 files changed, 28 insertions, 38 deletions

diff --git a/doc/build-aux/pandoc-filters/link-manpages.nix b/doc/build-aux/pandoc-filters/link-manpages.nix
new file mode 100644
index 000000000000..ee27c5d60812
--- /dev/null
+++ b/doc/build-aux/pandoc-filters/link-manpages.nix
@@ -0,0 +1,28 @@
+{ pkgs ? import ../../.. {} }:
+let
+  inherit (pkgs) lib;
+  manpageURLs = builtins.fromJSON (builtins.readFile (pkgs.path + "/doc/manpage-urls.json"));
+in pkgs.writeText "link-manpages.lua" ''
+  --[[
+  Adds links to known man pages that aren't already in a link.
+  ]]
+
+  local manpage_urls = {
+  ${lib.concatStringsSep "\n" (lib.mapAttrsToList (man: url:
+    "  [${builtins.toJSON man}] = ${builtins.toJSON url},") manpageURLs)}
+  }
+
+  traverse = 'topdown'
+
+  -- Returning false as the second value aborts processing of child elements.
+  function Link(elem)
+    return elem, false
+  end
+
+  function Code(elem)
+    local is_man_role = elem.classes:includes('interpreted-text') and elem.attributes['role'] == 'manpage'
+    if is_man_role and manpage_urls[elem.text] ~= nil then
+      return pandoc.Link(elem, manpage_urls[elem.text]), false
+    end
+  end
+''
diff --git a/doc/build-aux/pandoc-filters/link-unix-man-references.lua b/doc/build-aux/pandoc-filters/link-unix-man-references.lua
deleted file mode 100644
index b81d4a0979e7..000000000000
--- a/doc/build-aux/pandoc-filters/link-unix-man-references.lua
+++ /dev/null
@@ -1,38 +0,0 @@
---[[
-Turns a manpage reference into a link, when a mapping is defined below.
-]]
-
-local man_urls = {
-  ["nix.conf(5)"] = "https://nixos.org/manual/nix/stable/#sec-conf-file",
-
-  ["journald.conf(5)"] = "https://www.freedesktop.org/software/systemd/man/journald.conf.html",
-  ["logind.conf(5)"] = "https://www.freedesktop.org/software/systemd/man/logind.conf.html",
-  ["networkd.conf(5)"] = "https://www.freedesktop.org/software/systemd/man/networkd.conf.html",
-  ["systemd.automount(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.automount.html",
-  ["systemd.exec(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.exec.html",
-  ["systemd.link(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.link.html",
-  ["systemd.mount(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.mount.html",
-  ["systemd.netdev(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.netdev.html",
-  ["systemd.network(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.network.html",
-  ["systemd.nspawn(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.nspawn.html",
-  ["systemd.path(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.path.html",
-  ["systemd.resource-control(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.resource-control.html",
-  ["systemd.scope(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.scope.html",
-  ["systemd.service(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.service.html",
-  ["systemd.slice(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.slice.html",
-  ["systemd.socket(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.socket.html",
-  ["systemd.timer(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.timer.html",
-  ["systemd.unit(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.unit.html",
-  ["timesyncd.conf(5)"] = "https://www.freedesktop.org/software/systemd/man/timesyncd.conf.html",
-  ["tmpfiles.d(5)"] = "https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html",
-  ["systemd.time(7)"] = "https://www.freedesktop.org/software/systemd/man/systemd.time.html",
-  ["systemd-fstab-generator(8)"] = "https://www.freedesktop.org/software/systemd/man/systemd-fstab-generator.html",
-  ["systemd-networkd-wait-online.service(8)"] = "https://www.freedesktop.org/software/systemd/man/systemd-networkd-wait-online.service.html",
-}
-
-function Code(elem)
-  local is_man_role = elem.classes:includes('interpreted-text') and elem.attributes['role'] == 'manpage'
-  if is_man_role and man_urls[elem.text] ~= nil then
-    return pandoc.Link(elem, man_urls[elem.text])
-  end
-end