diff options
| author | Jan Tojnar <jtojnar@gmail.com> | 2021-06-05 21:36:48 +0200 |
|---|---|---|
| committer | Jan Tojnar <jtojnar@gmail.com> | 2021-06-07 06:34:59 +0200 |
| commit | adecb00f5a07ce3f5cc97e7ccf5d814f70f6704f (patch) | |
| tree | 1f30c3d55d0a0cc2a4b646b5aaaaef245b040d19 /doc | |
| parent | 6ecc641d087df8b8896ebd876bba592e981877c9 (diff) | |
| download | nixpkgs-adecb00f5a07ce3f5cc97e7ccf5d814f70f6704f.tar nixpkgs-adecb00f5a07ce3f5cc97e7ccf5d814f70f6704f.tar.gz nixpkgs-adecb00f5a07ce3f5cc97e7ccf5d814f70f6704f.tar.bz2 nixpkgs-adecb00f5a07ce3f5cc97e7ccf5d814f70f6704f.tar.lz nixpkgs-adecb00f5a07ce3f5cc97e7ccf5d814f70f6704f.tar.xz nixpkgs-adecb00f5a07ce3f5cc97e7ccf5d814f70f6704f.tar.zst nixpkgs-adecb00f5a07ce3f5cc97e7ccf5d814f70f6704f.zip | |
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.
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile | 25 |
1 files 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 > $@ |