Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

All manuals

Export presentations and PDF pages

Read the full manual →

Documentation · Changelog

Application icon
python3 tools/exporter.py presentation.pptx --output pdf,images
python3 tools/exporter.py document.pdf --output images
python3 tools/exporter.py presentation.pptx --output images --dpi 192 -d exports

exporter.py uses DeckCraft for PPTX exports and PdfCraft for PDF page rendering. It finds deckcraft-cli / pdfcraft-cli on PATH, or temporarily extracts the bundled CLI from the newest matching AppImage in ~/Applications. You can specify a CLI executable or AppImage with --deckcraft-cli / --pdfcraft-cli, or the DECKCRAFT_CLI / PDFCRAFT_CLI environment variables.

Output goes to <file-stem>_export/: <file-stem>.pdf and/or numbered PNGs inside images/. Images default to 144 DPI. Existing output requires --overwrite, which replaces generated files and removes stale numbered slide/page PNGs. PDF-to-PDF is a successful no-op unless compression is requested; other input extensions are errors. Rendering completes in temporary storage before output is copied.

Smaller PDFs for email

python3 tools/exporter.py presentation.pptx --output pdf --pdf-quality email
python3 tools/exporter.py presentation.pptx --output pdf --target-size 5MB
python3 tools/exporter.py presentation.pptx --output pdf --pdf-dpi 120
python3 tools/exporter.py document.pdf --output pdf --pdf-quality email --target-size 5MB

Compression requires Ghostscript. Its package is generally named ghostscript, while the executable placed on PATH is named gs:

# Debian / Ubuntu
sudo apt install ghostscript

# Fedora / RHEL
sudo dnf install ghostscript

# Arch Linux
sudo pacman -S ghostscript

# openSUSE
sudo zypper install ghostscript

# Alpine Linux
sudo apk add ghostscript

# macOS with Homebrew
brew install ghostscript

These commands are also shown by python3 tools/exporter.py --help and in the error displayed when compression is requested without gs. --dpi only controls PNG resolution. --pdf-quality controls PDF image downsampling:

QualityImage resolution
original (default)No compression pass
print300 DPI
email150 DPI
screen72 DPI

These presets use Ghostscript’s ebook compression settings with the indicated image resolution. They reduce image detail without deliberately rasterizing text and vector graphics. A quality preset alone does not guarantee a file size; the original is retained if it is smaller than the compressed result. Use --pdf-dpi DPI instead of a quality preset to select an exact PDF image resolution. --dpi remains specific to PNG exports.

--target-size accepts bytes or units such as 5MB, 500KB, and 2.5MiB (MB = 1,000,000 bytes; MiB = 1,048,576 bytes). It starts at the selected quality, or 300 DPI if no compression preset was selected, then tries lower resolutions: 150, 120, 96, 72, 50, and 36 DPI. Each pass uses the original PDF to avoid accumulating compression damage. It stops at the first result strictly below the target, with at most seven attempts. Progress shows each attempt and its resulting byte count. After the first completed pass, it estimates the remaining time from the average pass duration so far. A PDF already below the target is copied unchanged.

The final terminal message records the resolution actually selected. For example, 120 DPI images; reuse with --pdf-dpi 120 gives the exact option for the next export. If compression did not improve the file, it reports that the original/native image resolution was retained. PNG export messages similarly include their requested DPI.

Very small targets can noticeably degrade images, and some documents cannot reach the requested size. In that case the command fails, reports the smallest size achieved, and publishes no output; existing exports remain untouched. The target applies to the PDF file itself, not email encoding overhead. PDF compression writes a separate export and never changes the input.

Ghostscript rewrites the PDF, so some interactive content or annotations may change. See its PDF output documentation.

Interactive terminals show an updating progress line, with page counts and an approximate remaining time after the first completed page or compression pass. DeckCraft operations without measurable units use a spinner. Only output paths, the final summary, and warnings/errors remain afterward. Redirected output uses plain line logs. Set NO_COLOR to disable colors or TERM=dumb to disable animation as well.

All manuals

Development

Documentation · CI and coverage · Releases

Layout and workflow

DirectoryPurpose
tools/Python prototypes and document utilities
tests/Python regression and CI/packaging tests
crates/<tool>/Rust ports, each with its own source, tests and assets
scripts/Shared CI and release helpers
docs/Tool usage and specialized workflows

Prototype in Python, then add a Rust workspace member when the workflow is stable. Retire the Python implementation once the Rust port is validated. The PPTX reporter is now Rust-only; the document exporter remains Python. The rundown converter is a separate Rust workspace member with CLI and egui interfaces. Its implementation checklist and evaluation corpus track coverage and remaining limitations. Avoid speculative shared crates; extract common code when multiple tools need it.

The root Cargo.toml owns workspace metadata, the shared version and build profiles. Members inherit that metadata. Keep one root Cargo.lock and target/. The reporter is the default member; CI explicitly checks the entire workspace. Use -p pptx-reporter to select it when building from a multi-tool workspace.

Checks

Use a recent stable Rust toolchain. Python tools need 3.9+; CI helpers need 3.11+. Run from the repository root:

cargo fmt --all --check
cargo clippy --locked --workspace --all-targets --all-features -- -D warnings
cargo test --locked --workspace --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --locked --workspace --all-features --no-deps
python3 -m unittest discover -s tests -v
cargo build --locked --workspace --all-features

Rust regression tests cover archive parsing, trimming, loops, report formats, Ontime, CLI errors and GUI state; both PDF layouts compile with the embedded engine. Probe-process tests use a controlled stub. No external FFmpeg, FFprobe or Typst CLI is required for CI. The application still needs FFprobe at runtime. Python exporter tests mock external document applications. Inspect rendering changes visually as well.

cargo build -p pptx-reporter --no-default-features builds the CLI without the GUI or PDF engine; add --features pdf to restore embedded PDFs.

Keep generated files out of Git. Commit each completed task after checks; do not push without authorization. See CI and coverage and cross builds and packaging.

The converter can run without desktop dependencies using cargo run --locked -p rundown-converter --no-default-features --bin rundown-converter -- --help. Its tests generate synthetic XLSX inputs and never require private source files or network downloads. The existing workspace test, lint, Rustdoc and coverage commands include both tools; reporter release packaging remains separate.

The ASCII filename cleaner is a separate Rust workspace member. Run cargo run --locked -p ascii-names for its drag-and-drop window, or pass a folder for CLI cleanup. It uses the same workspace checks and coverage gates.

All manuals

Document Exporter changelog

All changelogs

Unreleased

v0.7.0 — 2026-11-14

  • Documentation release; see the release notes.

  • Add direct links to the published mdBook manual from the project README, tool guide and documentation indexes.

  • Add an mdBook manual built from the existing guides, with local assets and downloads. Jenkins publishes successful main builds under /mnt/books/manuals/; staging, link validation and scoped publication have regression coverage.

  • Use absolute Gitea main-branch URLs for repository file links in the root README; verify linked files exist.

v0.6.0 — 2026-11-14

  • Group the guide and supporting documentation in this tool’s folder; update portal, cross-document and packaging links for the new paths.

  • Add ImageGen application artwork in PNG, Windows ICO and macOS ICNS formats. Artwork is available for shortcuts and documentation; the tool remains hosted by its terminal or Companion.

2026-10-20

  • 095e7c7: Report selected export DPI and allow reusing it.