docs: add PDF export for user manual

2026-07-28 13:54:14 +02:00
parent 3b54f5ecc0
commit f81d6a871a
2 changed files with 84 additions and 0 deletions
@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SOURCE_MD="$ROOT_DIR/docs/de/user_manual.md"
+SCREENSHOT_DIR="$ROOT_DIR/docs/de/screenshots"
+OUTPUT_PDF="$ROOT_DIR/docs/de/user_manual.pdf"
+
+if ! command -v pandoc >/dev/null 2>&1; then
+  echo "Error: Pandoc is not installed or not available in PATH." >&2
+  echo "Install Pandoc first, then run this script again." >&2
+  exit 1
+fi
+
+if [[ ! -f "$SOURCE_MD" ]]; then
+  echo "Error: source Markdown not found: $SOURCE_MD" >&2
+  exit 1
+fi
+
+PDF_ENGINE=""
+for candidate in xelatex lualatex tectonic pdflatex wkhtmltopdf weasyprint; do
+  if command -v "$candidate" >/dev/null 2>&1; then
+    PDF_ENGINE="$candidate"
+    break
+  fi
+done
+
+if [[ -z "$PDF_ENGINE" ]]; then
+  echo "Error: no Pandoc-compatible PDF engine found." >&2
+  echo "Install xelatex, lualatex, tectonic, wkhtmltopdf, or weasyprint." >&2
+  exit 1
+fi
+
+TMP_DIR="$(mktemp -d)"
+trap 'rm -rf "$TMP_DIR"' EXIT
+TMP_MD="$TMP_DIR/user_manual.md"
+export XDG_CACHE_HOME="$TMP_DIR/cache"
+mkdir -p "$XDG_CACHE_HOME/fontconfig"
+
+python3 - "$SOURCE_MD" "$TMP_MD" "$SCREENSHOT_DIR" <<'PY'
+import pathlib
+import re
+import sys
+
+source = pathlib.Path(sys.argv[1])
+target = pathlib.Path(sys.argv[2])
+screenshot_dir = pathlib.Path(sys.argv[3])
+document_dir = screenshot_dir.parent
+
+markdown = source.read_text(encoding="utf-8")
+image_pattern = re.compile(r"!\[([^\]]*)\]\((screenshots/[^)]+)\)")
+
+
+def replace_missing_image(match):
+    alt_text = match.group(1).strip()
+    image_ref = match.group(2)
+    image_path = document_dir / image_ref
+
+    if image_path.exists():
+        return match.group(0)
+
+    label = alt_text or pathlib.PurePosixPath(image_ref).name
+    return f"*Screenshot placeholder: {label}*"
+
+
+target.write_text(image_pattern.sub(replace_missing_image, markdown), encoding="utf-8")
+PY
+
+pandoc "$TMP_MD" \
+  --from markdown+pipe_tables+grid_tables+multiline_tables+implicit_figures \
+  --resource-path="$ROOT_DIR/docs/de" \
+  --pdf-engine="$PDF_ENGINE" \
+  --toc \
+  --toc-depth=2 \
+  --number-sections \
+  --syntax-highlighting=tango \
+  --wrap=preserve \
+  -V papersize:a4 \
+  -V geometry:margin=20mm \
+  -V lang=de-DE \
+  -V colorlinks=true \
+  -o "$OUTPUT_PDF"
+
+echo "User manual PDF generated successfully: $OUTPUT_PDF"