doc: Add support for MyST roles

Officially, only the manpage role is supported at the moment.

Unlike in rST, the syntax uses braces instead of colons:

    {manpage}`nix.conf(5)`

4 files changed, 113 insertions, 0 deletions

diff --git a/doc/build-aux/pandoc-filters/docbook-reader/citerefentry-to-rst-role.lua b/doc/build-aux/pandoc-filters/docbook-reader/citerefentry-to-rst-role.lua
new file mode 100644
index 000000000000..281e85af2717
--- /dev/null
+++ b/doc/build-aux/pandoc-filters/docbook-reader/citerefentry-to-rst-role.lua
@@ -0,0 +1,23 @@
+--[[
+Converts Code AST nodes produced by pandoc’s DocBook reader
+from citerefentry elements into AST for corresponding role
+for reStructuredText.
+
+We use subset of MyST syntax (CommonMark with features from rST)
+so let’s use the rST AST for rST features.
+
+Reference: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-manpage
+]]
+
+function Code(elem)
+  elem.classes = elem.classes:map(function (x)
+    if x == 'citerefentry' then
+      elem.attributes['role'] = 'manpage'
+      return 'interpreted-text'
+    else
+      return x
+    end
+  end)
+
+  return elem
+end
diff --git a/doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua b/doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua
new file mode 100644
index 000000000000..92dc6895750f
--- /dev/null
+++ b/doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua
@@ -0,0 +1,36 @@
+--[[
+Converts AST for reStructuredText roles into corresponding
+DocBook elements.
+
+Currently, only a subset of roles is supported.
+
+Reference:
+  List of roles:
+    https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
+  manpage:
+    https://tdg.docbook.org/tdg/5.1/citerefentry.html
+  file:
+    https://tdg.docbook.org/tdg/5.1/filename.html
+]]
+
+function Code(elem)
+  if elem.classes:includes('interpreted-text') then
+    local tag = nil
+    local content = elem.text
+    if elem.attributes['role'] == 'manpage' then
+      tag = 'citerefentry'
+      local title, volnum = content:match('^(.+)%((%w+)%)$')
+      if title == nil then
+        -- No volnum in parentheses.
+        title = content
+      end
+      content = '<refentrytitle>' .. title .. '</refentrytitle>' .. (volnum ~= nil and ('<manvolnum>' .. volnum .. '</manvolnum>') or '')
+    elseif elem.attributes['role'] == 'file' then
+      tag = 'filename'
+    end
+
+    if tag ~= nil then
+      return pandoc.RawInline('docbook', '<' .. tag .. '>' .. content .. '</' .. tag .. '>')
+    end
+  end
+end
diff --git a/doc/build-aux/pandoc-filters/myst-reader/roles.lua b/doc/build-aux/pandoc-filters/myst-reader/roles.lua
new file mode 100644
index 000000000000..c33a688eeba7
--- /dev/null
+++ b/doc/build-aux/pandoc-filters/myst-reader/roles.lua
@@ -0,0 +1,29 @@
+--[[
+Replaces Str AST nodes containing {role}, followed by a Code node
+by a Code node with attrs that would be produced by rST reader
+from the role syntax.
+
+This is to emulate MyST syntax in Pandoc.
+(MyST is a CommonMark flavour with rST features mixed in.)
+
+Reference: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point
+]]
+
+function Inlines(inlines)
+  for i = #inlines-1,1,-1 do
+    local first = inlines[i]
+    local second = inlines[i+1]
+    local correct_tags = first.tag == 'Str' and second.tag == 'Code'
+    if correct_tags then
+      -- docutils supports alphanumeric strings separated by [-._:]
+      -- We are slightly more liberal for simplicity.
+      local role = first.text:match('^{([-._+:%w]+)}$')
+      if role ~= nil then
+        inlines:remove(i)
+        second.attributes['role'] = role
+        second.classes:insert('interpreted-text')
+      end
+    end
+  end
+  return inlines
+end
diff --git a/doc/build-aux/pandoc-filters/myst-writer/roles.lua b/doc/build-aux/pandoc-filters/myst-writer/roles.lua
new file mode 100644
index 000000000000..0136bc550652
--- /dev/null
+++ b/doc/build-aux/pandoc-filters/myst-writer/roles.lua
@@ -0,0 +1,25 @@
+--[[
+Replaces Code nodes with attrs that would be produced by rST reader
+from the role syntax by a Str AST node containing {role}, followed by a Code node.
+
+This is to emulate MyST syntax in Pandoc.
+(MyST is a CommonMark flavour with rST features mixed in.)
+
+Reference: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point
+]]
+
+function Code(elem)
+  local role = elem.attributes['role']
+
+  if elem.classes:includes('interpreted-text') and role ~= nil then
+    elem.classes = elem.classes:filter(function (c)
+      return c ~= 'interpreted-text'
+    end)
+    elem.attributes['role'] = nil
+
+    return {
+      pandoc.Str('{' .. role .. '}'),
+      elem,
+    }
+  end
+end