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.

Changed files
+15 -10
doc
+15 -10
doc/Makefile
···
MD_TARGETS=$(addsuffix .xml, $(basename $(shell find . -type f -regex '.*\.md$$' -not -name README.md)))
.PHONY: all
all: validate format out/html/index.html out/epub/manual.epub
···
mkdir -p out/html/highlightjs/
cp -r highlightjs out/html/
-
cp -r media out/html/
cp ./overrides.css out/html/
cp ./style.css out/html/style.css
···
doc-support/result/epub.xsl \
./manual-full.xml
-
cp -r media 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/
···
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 \
| cat > $@
%.chapter.xml: %.chapter.md
-
pandoc $^ -t docbook \
--top-level-division=chapter \
-
--extract-media=media \
-
--lua-filter=$(PANDOC_LUA_FILTERS_DIR)/diagram-generator.lua \
-
-f markdown+smart \
| cat > $@
···
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
···
mkdir -p out/html/highlightjs/
cp -r highlightjs out/html/
+
cp -r $(pandoc_media_dir) out/html/
cp ./overrides.css out/html/
cp ./style.css out/html/style.css
···
doc-support/result/epub.xsl \
./manual-full.xml
+
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/
···
ln -rfs ./doc-support/result/function-docs functions/library/generated
%.section.xml: %.section.md
+
$(PANDOC) $^ -t docbook \
+
$(pandoc_flags) \
| cat > $@
%.chapter.xml: %.chapter.md
+
$(PANDOC) $^ -t docbook \
--top-level-division=chapter \
+
$(pandoc_flags) \
| cat > $@