docs: deliver the user guide as a formatted PDF

The guide now ships as `doc/Rectify_user_guide.pdf` alongside the Markdown
it is rendered from. The PDF is the one to read; the Markdown remains the
source and is authoritative if the two ever disagree.

It is committed rather than built here because rendering it needs a font
store and a headless browser, which no one should have to install in order
to read a guide. The same PDF is downloadable on its own from
https://andykopra.com/Rectify_user_guide.pdf — the macOS disk image holds
the application only.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

.gitignore

@@ -44,3 +44,17 @@ notes/
 # Editor backup files
 *~
 *.py~
+
+# ktext build products (the user guide is written in Markdown and rendered
+# through Klammertext).  Intermediates are ignored; the rendered PDF is NOT.
+#
+# doc/Rectify_user_guide.pdf is a build product that is deliberately committed,
+# because it is the documentation users receive and nobody downstream can
+# rebuild it: rendering needs Klammertext, its font store, and a Chromium-based
+# browser.  Shipping the source alone would ship nothing readable.  Rebuild it
+# with `make` in doc/ and commit it alongside the Markdown it came from.
+doc/*.aux
+doc/*.log
+doc/*.out
+doc/*.tex
+doc/Rectify_user_guide/

README.md

@@ -15,6 +15,19 @@ python -m rectify --gui photo.jpg
 On macOS there is also a ready-to-run signed app — see
 [Installation methods](#installation-methods).
 
+## Documentation
+
+The full user and programmer's guide ships in two forms, both in `doc/`:
+
+- **`Rectify_user_guide.pdf`** — the formatted guide, and the one to read. It is
+  also downloadable on its own from <https://andykopra.com/Rectify_user_guide.pdf>
+- **`Rectify_user_guide.md`** — the Markdown the PDF is rendered from
+
+The Markdown is the source and is authoritative. If the two ever disagree, the
+Markdown is right and the PDF is behind it. The PDF is committed to the
+repository rather than built here because rendering it needs a font store and a
+headless browser, which no one should have to install in order to read a guide.
+
 ## Setup from source
 
 The repository is public — no account, login, or permission is needed to clone
@@ -265,6 +278,9 @@ The GUI always runs the automatic two-pass sweep — both detection strategies,
 - Double-click `Rectify.app` to launch — it opens the GUI with a file dialog
 - You can also drag an image file onto the `Rectify.app` icon in Finder or the Dock to open it directly
 
+The disk image holds the application and nothing else, so the guide is a
+separate download: <https://andykopra.com/Rectify_user_guide.pdf>
+
 **Linux and Windows** run from source ([above](#setup-from-source)). You can
 build a standalone executable yourself if you want one — see
 [Building a standalone executable](#building-a-standalone-executable) — but it is
@@ -296,4 +312,6 @@ The output appears in `dist/`. On macOS, `rectify.spec` also creates a `Rectify.
 - **macOS:** The spec file includes `BUNDLE` configuration for a `.app` bundle. Code signing may be needed for distribution outside of direct sharing.
 - **Windows:** Use `pyinstaller rectify.spec` from a command prompt. The spec sets `console=False` to suppress the console window.
 
-See `doc/Rectify_user_guide.md` for full documentation including usage examples and a programmer's guide.
+See `doc/Rectify_user_guide.pdf` for full documentation including usage examples
+and a programmer's guide — or the Markdown it is rendered from, as
+[Documentation](#documentation) describes.