From df55fbb62aea05fa3e48c4f7c2021bba49485ed5 Mon Sep 17 00:00:00 2001
From: Jan Tojnar <jtojnar@gmail.com>
Date: Mon, 12 Jul 2021 04:44:46 +0200
Subject: [PATCH] doc: comment lua scripts

---
 .../docbook-writer/labelless-link-is-xref.lua          | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/doc/build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua b/doc/build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua
index 67569b020916..fa97729a28bc 100644
--- a/doc/build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua
+++ b/doc/build-aux/pandoc-filters/docbook-writer/labelless-link-is-xref.lua
@@ -1,3 +1,13 @@
+--[[
+Converts Link AST nodes with empty label to DocBook xref elements.
+
+This is a temporary script to be able use cross-references conveniently
+using syntax taken from MyST, while we still use docbook-xsl
+for generating the documentation.
+
+Reference: https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing
+]]
+
 local function starts_with(start, str)
   return str:sub(1, #start) == start
 end