ADR-0005: pandoc as an optional GPL system-binary backend¶
- Status: Accepted
- Date: 2026-09-28
- Deciders: user, pc-1
- Related: ADR-0001 (dependency licence rule, §4 profiles, §8 no committed binaries), ADR-0003 (optional AGPL PyMuPDF — the pattern this follows)
Context¶
ADR-0001 §2 admits only permissive licences into the core dependency set; anything copyleft needs an explicit addendum before it enters any profile. Office/ODF/EPUB/RTF conversion needs pandoc, which has two halves with different licences: the Python wrapper pypandoc is MIT, but the pandoc binary is GPL-2.0-or-later. ParseCraft therefore cannot ship, depend on, or auto-install pandoc — but it may offer conversion through an optional extra that makes the copyleft choice explicit, exactly as ADR-0003 does for the AGPL PyMuPDF binary.
Decision¶
- pandoc support lives only behind the optional
pandocextra (pandoc = ["pypandoc>=1.15"], wrapper only). It is never a core dependency and is not installed bymise devor CI. - The pandoc binary is a system dependency, not a package dependency
(same class as the LibreOffice note in the LiteParse backend): users
install it themselves (
mise use pandoc@3or their package manager). ParseCraft never downloads or bundles it — ADR-0001 §8 forbids committed binaries and network installs at runtime. - Installing the extra and the binary is the user's licence decision.
GPL-2.0-or-later terms apply to that combination of extra + binary, not
to the MIT-licensed core. Missing extra or missing binary each surface as
a typed
DependencyUnavailableErrornaming what to install. supported_formatsmay only list inputs verified against a real pandoc binary (pandoc --versionplus an actual round-trip conversion); the verified list lives with the backend and is not guessed from pandoc's documentation.
Consequences¶
- The
pandocextra is copyleft-adjacent and never enters the default orallconvenience profiles without this addendum (it ships as an extra entry only, likepdf). uv sync --all-extras --all-groups(root AGENTS.md rule 10) must keep resolving: pypandoc is a small MIT wrapper with no native pins, so the extra adds no python-level conflicts; platform/system dependencies stay outside the resolver by construction.- Any future copyleft dependency follows the same pattern: optional extra + addendum + no core/dev install + typed errors when absent.
Amendment (2026-10-13): the pandoc extra is gone — the engine gate replaces it¶
Decision 1 is reversed, deliberately. pandoc was an optional extra because the
Pandoc binary is GPL-2.0-or-later. That framing did not survive contact with what the
extra actually contained: the extra gated pypandoc — an MIT, pure-Python wrapper of
about 0 MB — while the copyleft binary it warned about is not a pip dependency at
all (decision 2) and remains the user's own system install. An extra that installs a
permissive wrapper while the licence decision it advertises lives outside the resolver
gates nothing the decision is about, so it was complexity, not a licence boundary.
What replaces it. pandoc is now a base-install backend with an engine gate
(required_engine="pandoc", ADR-0008 decision 13): it is eligible only where the
binary is present — found on PATH or declared through the engine's environment
variable — which is a stronger guarantee than the extra ever gave, because the extra
never checked for the binary at all.
The licence position is unchanged. Subprocess invocation does not propagate GPL-2.0-or-later to parsecraft: the wrapper is MIT, the binary is a separate program the operator installs and licenses themselves, and parsecraft ships neither the binary nor a copy of it. Decision 2 stands as written.
Rule 10. Removing the extra and adding pypandoc to the base dependencies keeps
uv sync -U --all-extras --all-groups --all-packages --dry-run at exit 0: the package
adds no native pins, and the system binary stays outside the resolver by construction.