From fcce86cbed0b696faf99638711c1396cae749c35 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=B6rn-Michael=20Miehe?= <jmm@yavook.de>
Date: Wed, 8 Oct 2025 22:53:38 +0000
Subject: [PATCH] "pdftools.mk" makeover

---
 src/usr/local/share/autodoc/pdftools.mk | 106 +++++++++++++++++-------
 1 file changed, 77 insertions(+), 29 deletions(-)

diff --git a/src/usr/local/share/autodoc/pdftools.mk b/src/usr/local/share/autodoc/pdftools.mk
index edc05f4..6ea1e9e 100644
--- a/src/usr/local/share/autodoc/pdftools.mk
+++ b/src/usr/local/share/autodoc/pdftools.mk
@@ -1,46 +1,94 @@
-#############
-# FUNCTIONS #
-#############
+# use pandoc to process markdown
+#
+# params:
+#   1. input file
+#   2. pandoc template
+#   3. output format (e.g. pdf, latex, ...)
+#   4. output file
+#
+# vars:
+# 	- PANDOCVARS: template variables given as "name:value", separated by space
+# 	- PANDOCFLAGS: additional flags for `pandoc` commands
+pdftools_pdmd = pandoc \
+	$(1) \
+	--standalone \
+	--from markdown \
+	--to $(3) \
+	--template $(2) \
+	$(addprefix --variable ,$(PANDOCVARS) csquotes:true hyperrefoptions:pdfa) \
+	--output $(4) \
+	$(PANDOCFLAGS)
 
-PDFTOOLS_GSFLAGS := \
+# common flags for `gs` invocations (internal)
+__PDFTOOLS_GSFLAGS := \
 	-sDEVICE=pdfwrite \
-	-dNOOUTERSAVE \
+	-dSAFER \
 	-dNOPAUSE \
 	-dQUIET \
 	-dBATCH
 
+# use ghostscript to concatenate and/or adjust PDF file(s)
+#
+# params:
+#   1. input file(s)
+#   2. output file
+#
+# vars:
+#   - GS_CompatibilityLevel (default: 1.7): Refer to gs "dCompatibilityLevel"
+#   - GSNOFORCE: Set to anything to avoid forcing the paper size
+#   - GS_PAPERSIZE (if GSNOFORCE is unset, default: a4): Refer to gs "sPAPERSIZE"
+#   - GSNOCOMPRESS: Set to anything to avoid "distilling" the PDF
+#   - GS_PDFSETTINGS (if GSNOCOMPRESS is unset, default: /ebook): Refer to gs "dPDFSETTINGS"
+#   - GSFLAGS: additional flags for `gs` commands
 pdftools_pdfcat = gs \
-	$(PDFTOOLS_GSFLAGS) \
-	-sPAPERSIZE=a4 \
-	-dFIXEDMEDIA \
-	-dPDFFitPage \
-	-dCompatibilityLevel=1.7 \
-	-dPDFSETTINGS=/ebook \
+	$(__PDFTOOLS_GSFLAGS) \
+	-dCompatibilityLevel=$(or $(GS_CompatibilityLevel),1.7) \
+	$(if $(GSNOFORCE),,-sPAPERSIZE=$(or $(GS_PAPERSIZE),a4) -dFIXEDMEDIA -dPDFFitPage) \
+	$(if $(GSNOCOMPRESS),,-dPDFSETTINGS=$(or $(GS_PDFSETTINGS),/ebook)) \
 	-sOutputFile=$(2) \
+	$(GSFLAGS) \
 	$(1)
 
+# use ghostscript to concatenate PDF file(s) into a PDF/A
+#
+# params:
+#   1. input file(s)
+#   2. output file
+#
+# vars:
+#   - GS_PDFA (default: 3): Refer to gs "dPDFA"
+#   - GS_PDFACompatibilityPolicy (default: 1): Refer to gs "dPDFACompatibilityPolicy"
+#   - GSFLAGS: additional flags for `gs` commands
 pdftools_mkpdfa = gs \
-	$(PDFTOOLS_GSFLAGS) \
-	-dPDFA=$(1) \
+	$(__PDFTOOLS_GSFLAGS) \
+	-dPDFA=$(or $(GS_PDFA),3) \
+	-dPDFACompatibilityPolicy=$(or $(GS_PDFACompatibilityPolicy),1) \
 	-sColorConversionStrategy=RGB \
-	-dPDFACompatibilityPolicy=1 \
 	--permit-file-read=/usr/local/share/autodoc/ \
-	-sOutputFile=$(3) \
+	-sOutputFile=$(2) \
+	$(GSFLAGS) \
 	/usr/local/share/autodoc/PDFA_def.ps \
-	$(2)
+	$(1)
 
-############
-# PATTERNS #
-############
+# shorthands for `pdftools_pdfcat` and `pdftools_mkpdfa` reading from stdin (param is just output file, vars applicable)
+pdftools_pdfpipe = $(call pdftools_pdfcat,-,$(1))
+pdftools_pdfapipe = $(call pdftools_mkpdfa,-,$(1))
 
-# convert PDF to PDF/A-2B
-%_pdfa2.pdf: %.pdf
-	$(call pdftools_mkpdfa,2,$<,$@)
+# shorthands for `pdftools_pdmd` to compile into LaTeX, PDF and PDF/A
+#
+# vars applicable from `pdftools_pdmd`, `pdftools_pdfcat` and `pdftools_mkpdfa` as expected
+#
+# params:
+#   1. input file
+#   2. pandoc template
+#   3. output file
+pdftools_md2tex = $(call pdftools_pdmd,$(1),$(2),latex,$(3))
+pdftools_md2pdf = $(call pdftools_pdmd,$(1),$(2),pdf,-) | $(call pdftools_pdfpipe,$(3))
+pdftools_md2pdfa = $(call pdftools_md2pdf,$(1),$(2),-) | $(call pdftools_pdfapipe,$(3))
 
-# convert PDF to PDF/A-3B
-%_pdfa3.pdf: %.pdf
-	$(call pdftools_mkpdfa,3,$<,$@)
-
-# convert PDF to PDF/A (default variant 3B)
-%_pdfa.pdf: %.pdf
-	$(call pdftools_mkpdfa,3,$<,$@)
+# shorthands based on automatic Make variables
+pdftools_pdfcat_auto = $(call pdftools_pdfcat,$^,$@)
+pdftools_mkpdfa_auto = $(call pdftools_mkpdfa,$^,$@)
+pdftools_md2tex_auto = $(call pdftools_md2tex,$<,$(1),$@)
+pdftools_md2pdf_auto = $(call pdftools_md2pdf,$<,$(1),$@)
+pdftools_md2pdfa_auto = $(call pdftools_md2pdfa,$<,$(1),$@)