From adecb00f5a07ce3f5cc97e7ccf5d814f70f6704f Mon Sep 17 00:00:00 2001
From: Jan Tojnar <jtojnar@gmail.com>
Date: Sat, 5 Jun 2021 21:36:48 +0200
Subject: [PATCH] doc: Build as CommonMark
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

We were using Pandoc’s Markdown parser. This is non-standard and might cause issues when we finally switch to some other tool.

Since RFC 0072 agreed on CommonMark, let’s switch to that.

We will use some extensions to make the limited syntax bearable but these are official so they should be more portable.
---
 doc/Makefile | 25 +++++++++++++++----------
 1 file changed, 15 insertions(+), 10 deletions(-)

diff --git a/doc/Makefile b/doc/Makefile
index 7affbb0bb51..a208ce02f0c 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -1,5 +1,14 @@
 MD_TARGETS=$(addsuffix .xml, $(basename $(shell find . -type f -regex '.*\.md$$' -not -name README.md)))
 
+PANDOC ?= pandoc
+
+pandoc_media_dir = media
+# TODO: Remove raw-attribute when we can get rid of DocBook altogether.
+pandoc_commonmark_enabled_extensions = +attributes+fenced_divs+footnotes+bracketed_spans+definition_lists+pipe_tables+raw_attribute
+pandoc_flags = --extract-media=$(pandoc_media_dir) \
+	--lua-filter=$(PANDOC_LUA_FILTERS_DIR)/diagram-generator.lua \
+	-f commonmark$(pandoc_commonmark_enabled_extensions)+smart
+
 .PHONY: all
 all: validate format out/html/index.html out/epub/manual.epub
 
@@ -39,7 +48,7 @@ out/html/index.html: doc-support/result manual-full.xml style.css highlightjs
 	mkdir -p out/html/highlightjs/
 	cp -r highlightjs out/html/
 
-	cp -r media out/html/
+	cp -r $(pandoc_media_dir) out/html/
 	cp ./overrides.css out/html/
 	cp ./style.css out/html/style.css
 
@@ -54,7 +63,7 @@ out/epub/manual.epub: manual-full.xml
 		doc-support/result/epub.xsl \
 		./manual-full.xml
 
-	cp -r media out/epub/scratch/OEBPS
+	cp -r $(pandoc_media_dir) out/epub/scratch/OEBPS
 	cp ./overrides.css out/epub/scratch/OEBPS
 	cp ./style.css out/epub/scratch/OEBPS
 	mkdir -p out/epub/scratch/OEBPS/images/callouts/
@@ -89,16 +98,12 @@ functions/library/generated: doc-support/result
 	ln -rfs ./doc-support/result/function-docs functions/library/generated
 
 %.section.xml: %.section.md
-	pandoc $^ -t docbook \
-		--extract-media=media \
-		--lua-filter=$(PANDOC_LUA_FILTERS_DIR)/diagram-generator.lua \
-		-f markdown+smart \
+	$(PANDOC) $^ -t docbook \
+		$(pandoc_flags) \
 	| cat  > $@
 
 %.chapter.xml: %.chapter.md
-	pandoc $^ -t docbook \
+	$(PANDOC) $^ -t docbook \
 		--top-level-division=chapter \
-		--extract-media=media \
-		--lua-filter=$(PANDOC_LUA_FILTERS_DIR)/diagram-generator.lua \
-		-f markdown+smart \
+		$(pandoc_flags) \
 	| cat  > $@