[P0] Declare and enforce a minimum pandoc binary version #54

Activity

1. vivekVells

   added

   bugSomething isn't workingSomething isn't working

   on Aug 9, 2026
2. vivekVells

   self-assigned this

   on Aug 9, 2026
3. vivekVells commented on Aug 9, 2026

   

   vivekVells

   on Aug 9, 2026

   OwnerAuthor

   More actions

   Evidence for the open question, and a recommendation

   Researched while reviewing #59. This answers the "hard floor vs capability detection" question at the bottom of this issue.

   1. Upgrading pandoc is safe. Requiring a recent pandoc is not.

   These are two different questions and they have opposite answers.

   Do pandoc's own changes 3.7 → 3.10 break us? No. Checked every breaking change in the 3.8, 3.9 and 3.10.1 release notes against what this project actually passes to pandoc:

   Breaking change	Affects us?	Why
   Haskell API changes (WriterOptions, CommonState, tableWith)	No	We shell out to the binary, we do not link the library
   Lua API: pandoc.readers returns strings not booleans	No	We use --filter (JSON filters), not Lua
   Drop GHC < 9.6	No	Compilation only
   compact_definition_lists extension removed	No	Never enabled
   --no-highlighting, --highlight-style, --listings deprecated	No	Never passed, and deprecated still works
   Org writer: smart quotes off by default	No	org is not exposed

   Our entire pandoc surface is --reference-doc, --pdf-engine=xelatex, -V geometry:margin=1in, --defaults, --filter. None of them changed.

   2. The real risk is distro packaging lag

   Install method	pandoc version	≥ 3.8.3?
   apt-get install pandoc, Ubuntu 24.04 LTS	3.1.3	No
   apt-get install pandoc, Debian trixie	3.1.11.1	No
   brew install pandoc	3.10.1	Yes
   Our own CI (apt-get install -y pandoc on ubuntu-latest)	3.1.3	No

   A hard floor at 3.8.3 would break every Ubuntu LTS and Debian stable user following the install instructions in our own README, and would fail our own CI.

   3. Recommendation: per-feature minimums, checked at point of use

   Not one global floor. Declare a minimum per capability, and check only when that capability is requested:

   PPTX_INPUT_MIN_PANDOC = "3.8.3"
   
   if input_format == "pptx" and installed < PPTX_INPUT_MIN_PANDOC:
       return isError(
           f"pptx input requires pandoc >= 3.8.3 (released 2025-12-01). You have {installed}. "
           f"apt on Ubuntu 24.04 ships 3.1.3, so use pandoc's installer or Homebrew. "
           f"This reader is recent and may not handle every deck."
       )

   Everything else keeps working on pandoc 3.1.3 indefinitely. No breaking change for anyone.

   4. Revised acceptance criteria

   • A documented, non-enforced baseline in README ("tested against pandoc X"), with the reasoning
   • Per-feature minimum constants in server.py, checked at point of use, not at startup
   • Error messages name the detected version, the required version, its release date, and where to get it
   • Decide: static enum + runtime error, or build the input_format enum dynamically from the detected version. Dynamic is the only option that satisfies the AGENTS.md rule "only enumerate formats verified in the direction being enumerated"
   • pypandoc.get_pandoc_version() result cached, not re-shelled per call

   Rejected: pypandoc_binary

   Bundles a pandoc in the wheel, but uses whichever is higher between bundled and system, so it does not guarantee a version either. PyPI does not document which pandoc 1.17 (2026-03-14) bundles.

   Sources: pandoc 3.8 · 3.9 · 3.10.1 · Ubuntu noble · Debian trixie
4. vivekVells

   added 3 commits that reference this issue on Aug 10, 2026

   feat: expose pptx as an output format, and split the input and output…

   ...

   4084c10

   docs: document pptx output and make the write-only direction explicit

   ...

   70cccc3

   feat: expose pptx as an output format (#49) (#61)

   ...

   120dc78