pptx-refresh

pptx-refresh updates selected figures and rendered TeX tables in a PowerPoint presentation without changing the rest of the deck. You continue editing text, layout, and styling in PowerPoint; the generated presentation embeds refreshed assets and remains portable.

Requirements

• macOS with a logged-in desktop session
• Python 3.10 or newer
• Microsoft 365 PowerPoint, installed and licensed
• permission for the calling terminal application to control PowerPoint
• latexmk and pdflatex only when rendering TeX tables

Supported figure sources are PNG, JPEG, and PDF. A PDF may use a same-named PNG companion for deterministic rendering.

Install

Install the released package in an isolated environment:

python3 -m venv .venv
.venv/bin/python -m pip install "pptx-refresh==0.1.0"
.venv/bin/pptx-refresh --version
.venv/bin/pptx-refresh doctor

The first doctor run may trigger a macOS Automation prompt. Grant the calling terminal access to Microsoft PowerPoint under System Settings > Privacy & Security > Automation, then run doctor again.

Declare managed objects

In PowerPoint, select an ungrouped picture, ordinary shape, or supported table placeholder. Give it a unique Selection Pane name beginning with AUTO: and put the source path on the first line of Alt Text.

Selection Pane name:
AUTO:figures/main-results.pdf

Alt Text:
figures/main-results.pdf

Source paths must be relative. Absolute paths, .., empty path segments, directories, missing files, and unsupported extensions are rejected. Save and close the source presentation before validating or building it.

Standalone projects

When --input-dir is omitted, source paths are relative to the presentation's directory:

slides-project/
├── presentation.pptx
├── figures/
│   └── main-results.pdf
└── tables/
    └── summary-results.tex

pptx-refresh validate presentation.pptx
pptx-refresh build presentation.pptx

The default output directory is output/ beside the presentation.

Projects with a separate input directory

Use --input-dir when the presentation lives under source/ and its declared assets live under input/:

slides-module/
├── source/
│   └── main.pptx
├── input/
│   └── figures/result.pdf
└── output/

From source/, run:

pptx-refresh validate main.pptx \
    --input-dir ../input \
    --output-dir ../output/pptx-refresh

pptx-refresh build main.pptx \
    --input-dir ../input \
    --output-dir ../output/pptx-refresh

Relative input and output directories are resolved from the presentation's directory. Alt Text remains relative to the selected input directory, so the example deck declares figures/result.pdf, not input/figures/result.pdf.

An explicit input directory is a trusted logical namespace. File and directory symlinks declared beneath it may resolve to existing regular files elsewhere, which supports generated-input workflows. Sources may not resolve into the active publication-owned output paths. When --input-dir is omitted, the stricter standalone policy requires symlink targets to remain inside the presentation directory. The same rules apply to PDF companion PNGs.

Outputs and exit status

A successful build publishes an atomic bundle without overwriting the source:

output/
├── presentation_updated.pptx
├── presentation_updated.pdf
└── report/
    ├── index.html
    ├── report.json
    ├── previews/
    └── diffs/

Exit status 0 means the bundle was published without review items. Status 2 also means publication succeeded, but the report recommends review. Any other status is a failure.

Open report/index.html after each build and review the refreshed presentation and exported PDF before circulating them.

Troubleshooting

Run diagnostics with:

pptx-refresh doctor --json

If PowerPoint is unavailable, confirm that it is installed, licensed, and not blocked by macOS Automation permissions. If a presentation is reported as open, save and close it in PowerPoint before retrying. TeX-table errors require both latexmk and pdflatex; figure-only presentations do not require TeX.

For path errors, check the first Alt Text line, the selected --input-dir, and every symlink target. Build failures leave the source presentation unchanged.

License

pptx-refresh is distributed under the MIT License.