doc: Build as CommonMark

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

@@ -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  > $@