diff options
author | Naïm Favier <n@monade.li> | 2023-01-02 14:00:58 +0100 |
---|---|---|
committer | Naïm Favier <n@monade.li> | 2023-01-02 14:11:22 +0100 |
commit | a8d4cf149cda4f82145291cc9a6819a9baa3951e (patch) | |
tree | a92d5a3a9c5bff6a5969561910113d9f8f88e6b6 /doc/build-aux/pandoc-filters | |
parent | 5a9a3353342fc2a964c58f91ef8cbb19585c3af8 (diff) |
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.
Diffstat (limited to 'doc/build-aux/pandoc-filters')
-rw-r--r-- | doc/build-aux/pandoc-filters/link-manpages.nix | 28 | ||||
-rw-r--r-- | doc/build-aux/pandoc-filters/link-unix-man-references.lua | 38 |
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 |