From 04b59b0328daaa2e11f5e387ad3ec475cf2d2028 Mon Sep 17 00:00:00 2001
From: Jan Tojnar <jtojnar@gmail.com>
Date: Mon, 12 Jul 2021 18:40:33 +0200
Subject: [PATCH] doc: Linkify man page references

---
 doc/Makefile                                   |  1 +
 .../link-unix-man-references.lua               | 18 ++++++++++++++++++
 .../contributing-to-documentation.chapter.md   |  4 +++-
 nixos/doc/manual/md-to-db.sh                   |  1 +
 4 files changed, 23 insertions(+), 1 deletion(-)
 create mode 100644 doc/build-aux/pandoc-filters/link-unix-man-references.lua

diff --git a/doc/Makefile b/doc/Makefile
index 9bcd30c150a2..027a8b9e7bb2 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -11,6 +11,7 @@ pandoc_commonmark_enabled_extensions = +attributes+fenced_divs+footnotes+bracket
 pandoc_flags = --extract-media=$(pandoc_media_dir) \
 	--lua-filter=$(PANDOC_LUA_FILTERS_DIR)/diagram-generator.lua \
 	--lua-filter=build-aux/pandoc-filters/myst-reader/roles.lua \
+	--lua-filter=build-aux/pandoc-filters/link-unix-man-references.lua \
 	--lua-filter=build-aux/pandoc-filters/docbook-writer/rst-roles.lua \
 	--lua-filter=build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua \
 	-f commonmark$(pandoc_commonmark_enabled_extensions)+smart
diff --git a/doc/build-aux/pandoc-filters/link-unix-man-references.lua b/doc/build-aux/pandoc-filters/link-unix-man-references.lua
new file mode 100644
index 000000000000..12431f140fed
--- /dev/null
+++ b/doc/build-aux/pandoc-filters/link-unix-man-references.lua
@@ -0,0 +1,18 @@
+--[[
+Turns a manpage reference into a link, when a mapping is defined
+in the unix-man-urls.lua file.
+]]
+
+local man_urls = {
+  ["tmpfiles.d(5)"] = "https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html",
+  ["nix.conf(5)"] = "https://nixos.org/manual/nix/stable/#sec-conf-file",
+  ["systemd.time(7)"] = "https://www.freedesktop.org/software/systemd/man/systemd.time.html",
+  ["systemd.timer(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.timer.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
diff --git a/doc/contributing/contributing-to-documentation.chapter.md b/doc/contributing/contributing-to-documentation.chapter.md
index bf73a340bcef..178fdb36262b 100644
--- a/doc/contributing/contributing-to-documentation.chapter.md
+++ b/doc/contributing/contributing-to-documentation.chapter.md
@@ -53,7 +53,9 @@ Additionally, the following syntax extensions are currently used:
   This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing).
 
 - []{#ssec-contributing-markup-inline-roles}
-  If you want to link to a man page, you can use ``{manpage}`nix.conf(5)```, which will turn into {manpage}`nix.conf(5)`.
+  If you want to link to a man page, you can use `` {manpage}`nix.conf(5)` ``, which will turn into {manpage}`nix.conf(5)`.
+
+  The references will turn into links when a mapping exists in {file}`doc/build-aux/pandoc-filters/unix-man-urls.lua`.
 
   This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point). Though, the feature originates from [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-manpage) with slightly different syntax.
 
diff --git a/nixos/doc/manual/md-to-db.sh b/nixos/doc/manual/md-to-db.sh
index e5a1919baa28..f3c851db6c93 100755
--- a/nixos/doc/manual/md-to-db.sh
+++ b/nixos/doc/manual/md-to-db.sh
@@ -17,6 +17,7 @@ pandoc_flags=(
   # - media extraction (was only required for diagram generator)
   # - docbook-reader/citerefentry-to-rst-role.lua (only relevant for DocBook → MarkDown/rST/MyST)
   "--lua-filter=$DIR/../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua"
+  "--lua-filter=$DIR/../../../doc/build-aux/pandoc-filters/link-unix-man-references.lua"
   "--lua-filter=$DIR/../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua"
   "--lua-filter=$DIR/../../../doc/build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua"
   -f "commonmark${pandoc_commonmark_enabled_extensions}+smart"