Offer the manual as PDF and EPUB, laid out for print

The page gains a print stylesheet: A4 with a cover, a contents page whose
entries carry their page numbers, a chapter to a page with its name at the
head of each page and the page count at the foot, figures and table rows
never split, and the light palette. A line above the title links the PDF
and the EPUB on the published site, absolutely, since an installed copy
has none beside it.

The Manual pages workflow makes both: tools/manual/pdf.py renders the page
with WeasyPrint from JPEG copies of its pictures, which takes the PDF from
28 MB to 8, and pandoc makes the EPUB from the Markdown.

.gitea/workflows/manual-pages.yml

@@ -7,7 +7,8 @@ name: Manual pages
 # No site generator. docs/manual/index.html is already the rendered page —
 # `cargo run -p traceability -- manual` writes it from README.md, and the
 # Traceability workflow fails a push whose page disagrees with the README —
-# so this job only copies the page and its pictures onto the branch.
+# so this job copies the page and its pictures onto the branch, with a PDF
+# and an EPUB made from them.
 
 on:
   push:
@@ -56,6 +57,28 @@ jobs:
             echo "LFS pointers where pictures should be:"; echo "$bad"; exit 1
           fi
 
+      # The downloads the page links to (traceability's PAGES_SITE, PDF_NAME,
+      # EPUB_NAME). The PDF is the page itself through its print stylesheet —
+      # A4, a cover and a contents page with page numbers, a chapter a page —
+      # so it says what the page says; tools/manual/pdf.py says why it goes
+      # through JPEG copies of the pictures first.
+      # The EPUB comes from the Markdown, which pandoc reads better than a page.
+      - name: Make the PDF and the EPUB
+        run: |
+          set -e
+          apt-get update -qq
+          DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends \
+            pandoc python3-pip python3-venv libpango-1.0-0 libpangoft2-1.0-0 \
+            fonts-noto-core fonts-dejavu-core > /dev/null
+          python3 -m venv /tmp/wp
+          /tmp/wp/bin/pip install -q weasyprint
+          mkdir -p site
+          /tmp/wp/bin/python tools/manual/pdf.py docs/manual site/darkroom-manual.pdf
+          title=$(sed -n 's/^# //p' docs/manual/README.md | head -1)
+          (cd docs/manual && pandoc README.md -o ../../site/darkroom-manual.epub \
+            --metadata title="$title" --toc --toc-depth=2 --epub-chapter-level=2)
+          ls -l site
+
       # One commit, force-pushed: the branch is a build output, and its history
       # is in master's.
       - name: Push to gitea-pages
@@ -64,6 +87,7 @@ jobs:
         run: |
           set -e
           site=$(mktemp -d)
+          cp site/darkroom-manual.pdf site/darkroom-manual.epub "$site/"
           cp docs/manual/index.html "$site/"
           cp -r docs/manual/media "$site/"
           cd "$site"