Merge pull request #1272 from sudo-bmitch/pr-update-pandoc

Docs: Update pandoc for rendering documentation

Author: tianon

.tool/curver.go

@@ -0,0 +1,26 @@
+// Copyright 2025 The Linux Foundation
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main
+
+import (
+	"fmt"
+
+	"github.com/opencontainers/image-spec/specs-go"
+)
+
+// This package is intended to be executed using "go run .tool/curver.go".
+func main() {
+	fmt.Println(specs.Version)
+}

.tool/genheader.go

@@ -8,18 +8,17 @@ GOPATH:=$(shell go env GOPATH)
 OUTPUT_DIRNAME	?= output
 DOC_FILENAME	?= oci-image-spec
 
-PANDOC_CONTAINER ?= ghcr.io/opencontainers/pandoc:2.9.2.1-8.fc33.x86_64@sha256:5d81ff930a043295a557be8b003ece2a33d14e91b28c50d368413b83372f8d28
+# pinned to a 3.1 release due to a regression, see https://github.com/jgm/pandoc/issues/10952 before upgrading
+PANDOC_CONTAINER ?= docker.io/pandoc/latex:3.1@sha256:1cf54d9214a9b52de2f58cf5895cc596a5960711a54d7938dc72f2b23473caf3
 ifeq "$(strip $(PANDOC))" ''
 	ifneq "$(strip $(DOCKER))" ''
 		PANDOC = $(DOCKER) run \
 			--rm \
-			-v $(shell pwd)/:/input/:ro \
-			-v $(shell pwd)/$(OUTPUT_DIRNAME)/:/$(OUTPUT_DIRNAME)/ \
-			-u $(shell id -u) \
-			--workdir /input \
+			-v "$(CURDIR)/:/workdir/:ro" \
+			-v "$(CURDIR)/$(OUTPUT_DIRNAME)/:/workdir/$(OUTPUT_DIRNAME)/" \
+			-u "$(shell id -u):$(shell id -g)" \
+			--workdir /workdir \
 			$(PANDOC_CONTAINER)
-		PANDOC_SRC := /input/
-		PANDOC_DST := /
 	endif
 endif
 
@@ -55,24 +54,22 @@ fmt: ## format the json with indentation
 docs: $(OUTPUT_DIRNAME)/$(DOC_FILENAME).pdf $(OUTPUT_DIRNAME)/$(DOC_FILENAME).html ## generate a PDF/HTML version of the OCI image specification
 
 ifeq "$(strip $(PANDOC))" ''
-$(OUTPUT_DIRNAME)/$(DOC_FILENAME).pdf: $(DOC_FILES) $(FIGURE_FILES)
+$(OUTPUT_DIRNAME)/$(DOC_FILENAME).%: $(DOC_FILES) $(FIGURE_FILES)
 	$(error cannot build $@ without either pandoc or docker)
 else
 $(OUTPUT_DIRNAME)/$(DOC_FILENAME).pdf: $(DOC_FILES) $(FIGURE_FILES)
 	@mkdir -p $(OUTPUT_DIRNAME)/ && \
-	$(PANDOC) -f gfm -t latex --pdf-engine=xelatex -V geometry:margin=0.5in,bottom=0.8in -V block-headings -o $(PANDOC_DST)$@ $(patsubst %,$(PANDOC_SRC)%,$(DOC_FILES))
-	ls -sh $(realpath $@)
+	version="v$$(go run .tool/curver.go)" && \
+	$(PANDOC) -f gfm -t latex -o $@ --metadata "title=image-spec $${version}" --standalone --file-scope --pdf-engine=xelatex -V geometry:margin=0.5in,bottom=0.8in -V block-headings $(DOC_FILES)
+	ls -sh $@
 
-$(OUTPUT_DIRNAME)/$(DOC_FILENAME).html: header.html $(DOC_FILES) $(FIGURE_FILES)
+$(OUTPUT_DIRNAME)/$(DOC_FILENAME).html: $(DOC_FILES) $(FIGURE_FILES)
 	@mkdir -p $(OUTPUT_DIRNAME)/ && \
-	cp -ap img/ $(shell pwd)/$(OUTPUT_DIRNAME)/&& \
-	$(PANDOC) -f gfm -t html5 -H $(PANDOC_SRC)header.html --standalone -o $(PANDOC_DST)$@ $(patsubst %,$(PANDOC_SRC)%,$(DOC_FILES))
-	ls -sh $(realpath $@)
+	version="v$$(go run .tool/curver.go)" && \
+	$(PANDOC) -f gfm -t html5 -o $@ --metadata "title=image-spec $${version}" --standalone --file-scope --embed-resources -V "maxwidth:95%" $(DOC_FILES)
+	ls -sh $@
 endif
 
-header.html: .tool/genheader.go specs-go/version.go
-	go run .tool/genheader.go > $@
-
 .PHONY: validate-examples
 validate-examples: schema/schema.go ## validate examples in the specification markdown files
 	cd schema && go test -run TestValidate .