From d727e7b3a126aca02f3fc565473d66de7794253b Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sat, 29 Nov 2025 18:23:33 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 14 + README.md | 3 + commands/convert.md | 39 +++ commands/help.md | 42 +++ plugin.lock.json | 53 ++++ skills/pdf-to-pptx-tool/SKILL.md | 513 +++++++++++++++++++++++++++++++ 6 files changed, 664 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 commands/convert.md create mode 100644 commands/help.md create mode 100644 plugin.lock.json create mode 100644 skills/pdf-to-pptx-tool/SKILL.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..235ed3d --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,14 @@ +{ + "name": "pdf-to-pptx-tool", + "description": "PDF to PowerPoint converter CLI tool", + "version": "0.1.0", + "author": { + "name": "Dennis Vriend" + }, + "skills": [ + "./skills" + ], + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..2bf0417 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# pdf-to-pptx-tool + +PDF to PowerPoint converter CLI tool diff --git a/commands/convert.md b/commands/convert.md new file mode 100644 index 0000000..078fda9 --- /dev/null +++ b/commands/convert.md @@ -0,0 +1,39 @@ +--- +description: Convert PDF to PowerPoint with custom DPI +argument-hint: input.pdf output.pptx +--- + +Convert a PDF file to PowerPoint (PPTX) format with each page as a slide. + +## Usage + +```bash +pdf-to-pptx-tool convert INPUT_PDF OUTPUT_PPTX [--dpi DPI] +``` + +## Arguments + +- `INPUT_PDF`: Path to input PDF file (required) +- `OUTPUT_PPTX`: Path to output PPTX file (required) +- `--dpi DPI`: Resolution for conversion (default: 200) +- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE) + +## Examples + +```bash +# Basic conversion +pdf-to-pptx-tool convert document.pdf slides.pptx + +# High quality conversion +pdf-to-pptx-tool convert report.pdf presentation.pptx --dpi 300 + +# With verbose logging +pdf-to-pptx-tool -vv convert input.pdf output.pptx +``` + +## Output + +Creates a PowerPoint (.pptx) with: +- One slide per PDF page +- 16:9 aspect ratio (10" x 5.625") +- Images sized to fill entire slide diff --git a/commands/help.md b/commands/help.md new file mode 100644 index 0000000..bb00dcb --- /dev/null +++ b/commands/help.md @@ -0,0 +1,42 @@ +--- +description: Show help information for pdf-to-pptx-tool +argument-hint: command +--- + +Display help information for pdf-to-pptx-tool CLI commands. + +## Usage + +```bash +# Show general help +pdf-to-pptx-tool --help + +# Show command-specific help +pdf-to-pptx-tool COMMAND --help + +# Show version +pdf-to-pptx-tool --version +``` + +## Arguments + +- `COMMAND` (optional): Specific command to get help for +- `--help` / `-h`: Show help information +- `--version` / `-v`: Show version information + +## Examples + +```bash +# General help +pdf-to-pptx-tool --help + +# Command help +pdf-to-pptx-tool search --help + +# Version information +pdf-to-pptx-tool --version +``` + +## Output + +Displays usage information, available commands, and options. diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..fa591a5 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,53 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:dnvriend/pdf-to-pptx-tool:plugins/pdf-to-pptx-tool", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "19ecebdeae45c5370fe2a2201c897f77a25dafb7", + "treeHash": "794ce7a38a90a62052648749aa8cd0a1e3658a65cd7fc4bd1bbfb44d6467e450", + "generatedAt": "2025-11-28T10:16:37.244224Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "pdf-to-pptx-tool", + "description": "PDF to PowerPoint converter CLI tool", + "version": "0.1.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "ec566a1591201d6b720eb5e163355f3d1e386b0afc7aaa6ee65b7ad0233b28c5" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "b5c09f3664f2f5e7dd33b6adbbecf9e9985235e35b232568a387509f3b74b276" + }, + { + "path": "commands/help.md", + "sha256": "970ccfba03f33c8ab9ec205da997228e94c69d58ec067a984a0c75e06fa90ecc" + }, + { + "path": "commands/convert.md", + "sha256": "9714fc178abdcab00a1c5acb01bb8e6804a42960b114c8c85f24adea82f0bff3" + }, + { + "path": "skills/pdf-to-pptx-tool/SKILL.md", + "sha256": "8bb4b88cef7d42b4d8bedeb90f861b393b163a88d609301f2d967c7932bf5381" + } + ], + "dirSha256": "794ce7a38a90a62052648749aa8cd0a1e3658a65cd7fc4bd1bbfb44d6467e450" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/pdf-to-pptx-tool/SKILL.md b/skills/pdf-to-pptx-tool/SKILL.md new file mode 100644 index 0000000..cef7588 --- /dev/null +++ b/skills/pdf-to-pptx-tool/SKILL.md @@ -0,0 +1,513 @@ +--- +name: skill-pdf-to-pptx-tool +description: Convert PDF to PowerPoint presentations +--- + +# When to use +- Converting PDF documents to editable PowerPoint presentations +- Creating slide decks from PDF reports or documents +- Need high-quality PDF to PPTX conversion with custom DPI +- Want multi-level verbosity logging for debugging conversions + +# PDF to PowerPoint Converter Skill + +## Purpose + +This skill provides comprehensive guidance for using `pdf-to-pptx-tool`, a professional CLI tool that converts PDF documents into PowerPoint presentations. Each PDF page becomes a high-quality slide with customizable resolution. + +## When to Use This Skill + +**Use this skill when:** +- You need to convert PDF documents to PowerPoint format +- You want to customize conversion quality (DPI settings) +- You need to debug conversion issues with verbose logging +- You're working with multi-page PDF documents +- You need programmatic PDF to PPTX conversion in workflows + +**Do NOT use this skill for:** +- Editing existing PowerPoint files (use PowerPoint directly) +- Converting other formats (images, Word docs) to PPTX +- Extracting text from PDFs (use PDF text extraction tools) +- Creating PowerPoint from scratch (use PowerPoint or python-pptx) + +## CLI Tool: pdf-to-pptx-tool + +A modern Python CLI tool built with Click, featuring multi-level verbosity logging, shell completion, and type-safe code. + +### Installation + +```bash +# Clone the repository +git clone https://github.com/dnvriend/pdf-to-pptx-tool.git +cd pdf-to-pptx-tool + +# Install globally with uv +uv tool install . +``` + +### Prerequisites + +- Python 3.14+ +- `poppler` system library (for PDF rendering) + - macOS: `brew install poppler` + - Ubuntu/Debian: `apt-get install poppler-utils` + - Windows: Download from poppler releases + +### Quick Start + +```bash +# Basic conversion +pdf-to-pptx-tool convert document.pdf slides.pptx + +# High quality (300 DPI) +pdf-to-pptx-tool convert report.pdf presentation.pptx --dpi 300 + +# With verbose logging +pdf-to-pptx-tool -v convert input.pdf output.pptx +``` + +## Progressive Disclosure + +
+📖 Core Commands (Click to expand) + +### convert - Convert PDF to PowerPoint + +Converts a PDF document to PowerPoint format, creating one slide per PDF page with customizable quality settings. + +**Usage:** +```bash +pdf-to-pptx-tool convert INPUT_PDF OUTPUT_PPTX [OPTIONS] +``` + +**Arguments:** +- `INPUT_PDF`: Path to input PDF file (required) + - Must exist and be a valid PDF file + - Supports any PDF version + - No size limit (memory permitting) +- `OUTPUT_PPTX`: Path to output PowerPoint file (required) + - Will be created or overwritten + - Extension should be `.pptx` + - Parent directory must exist +- `--dpi INTEGER`: Resolution for page conversion (optional) + - Default: 200 DPI (good quality, reasonable size) + - Range: 72-600 DPI + - Higher DPI = better quality but larger files + - Recommended: 200-300 for presentations +- `-v, --verbose`: Multi-level verbosity + - No flag: Warnings/errors only + - `-v`: INFO level (operations and progress) + - `-vv`: DEBUG level (detailed steps) + - `-vvv`: TRACE level (library internals) + +**Examples:** +```bash +# Example 1: Basic conversion (default 200 DPI) +pdf-to-pptx-tool convert quarterly-report.pdf q4-presentation.pptx + +# Example 2: High quality for detailed diagrams +pdf-to-pptx-tool convert technical-diagram.pdf slides.pptx --dpi 300 + +# Example 3: Lower quality for quick preview +pdf-to-pptx-tool convert draft.pdf preview.pptx --dpi 150 + +# Example 4: With INFO logging to see progress +pdf-to-pptx-tool -v convert large-doc.pdf output.pptx + +# Example 5: With DEBUG logging for troubleshooting +pdf-to-pptx-tool -vv convert problematic.pdf fixed.pptx + +# Example 6: Batch conversion with shell loop +for pdf in *.pdf; do + pdf-to-pptx-tool convert "$pdf" "${pdf%.pdf}.pptx" +done +``` + +**Output:** +- Creates PowerPoint file at specified path +- Slide properties: + - Aspect ratio: 16:9 (widescreen) + - Dimensions: 10" × 5.625" + - Layout: One full-slide image per PDF page + - Background: Transparent +- Console output: + - Success: "✓ Successfully converted input.pdf to output.pptx" + - Error: "✗ Error: [detailed error message]" +- Exit codes: + - 0: Success + - 1: Error (file not found, invalid input, conversion failed) + +--- + +### completion - Generate shell completion scripts + +Generates shell completion scripts for bash, zsh, or fish shells. + +**Usage:** +```bash +pdf-to-pptx-tool completion SHELL +``` + +**Arguments:** +- `SHELL`: Shell type (required) + - Options: `bash`, `zsh`, `fish` + - Case-insensitive + +**Examples:** +```bash +# Generate bash completion +eval "$(pdf-to-pptx-tool completion bash)" + +# Generate zsh completion +eval "$(pdf-to-pptx-tool completion zsh)" + +# Generate fish completion +pdf-to-pptx-tool completion fish | source + +# Save to file for permanent installation +pdf-to-pptx-tool completion bash > ~/.pdf-to-pptx-tool-completion.bash +echo 'source ~/.pdf-to-pptx-tool-completion.bash' >> ~/.bashrc +``` + +**Output:** +Shell-specific completion script printed to stdout. + +
+ +
+⚙️ Advanced Features (Click to expand) + +### Multi-Level Verbosity Logging + +The tool supports progressive verbosity levels for debugging and monitoring conversions. + +**Logging Levels:** + +| Flag | Level | Output | Use Case | +|------|-------|--------|----------| +| (none) | WARNING | Errors/warnings only | Production, quiet mode | +| `-v` | INFO | + Operations, progress | Normal debugging | +| `-vv` | DEBUG | + Detailed steps, file sizes | Development, troubleshooting | +| `-vvv` | TRACE | + Library internals (pdf2image, PIL, pptx) | Deep debugging | + +**Examples:** +```bash +# Quiet mode - only see errors +pdf-to-pptx-tool convert input.pdf output.pptx + +# INFO - see conversion progress +pdf-to-pptx-tool -v convert input.pdf output.pptx +# Output: +# [INFO] Starting PDF to PPTX conversion +# [INFO] Converting input.pdf to output.pptx (DPI: 200) +# [INFO] Converting PDF pages to images... +# [INFO] Converted 5 pages +# [INFO] Creating PowerPoint presentation... +# [INFO] Saving presentation to output.pptx + +# DEBUG - see detailed processing +pdf-to-pptx-tool -vv convert input.pdf output.pptx +# Additional output: +# [DEBUG] Input: input.pdf, Output: output.pptx, DPI: 200 +# [DEBUG] Validating input file: input.pdf +# [DEBUG] Input file size: 2.45 MB +# [DEBUG] Using DPI setting: 200 +# [DEBUG] Processing slide 1/5 +# [DEBUG] Output file size: 8.23 MB + +# TRACE - see library internals +pdf-to-pptx-tool -vvv convert input.pdf output.pptx +# Shows pdf2image, PIL, and pptx library debug messages +``` + +### DPI Quality Guidelines + +Choose DPI based on your use case: + +| DPI | Quality | File Size | Best For | +|-----|---------|-----------|----------| +| 72 | Low | Smallest | Quick previews, draft slides | +| 150 | Medium | Small | Web presentations, email | +| 200 | Good | Medium | **Default - recommended for most** | +| 300 | High | Large | Print quality, detailed diagrams | +| 600 | Very High | Very Large | Professional print, posters | + +**Trade-offs:** +- **Higher DPI**: Better quality, larger file size, slower conversion +- **Lower DPI**: Faster conversion, smaller files, lower quality +- **Sweet spot**: 200-300 DPI for most presentations + +### Batch Processing + +Process multiple PDFs efficiently: + +```bash +# Convert all PDFs in directory +for pdf in *.pdf; do + echo "Converting $pdf..." + pdf-to-pptx-tool convert "$pdf" "${pdf%.pdf}.pptx" +done + +# With custom DPI +for pdf in *.pdf; do + pdf-to-pptx-tool convert "$pdf" "${pdf%.pdf}.pptx" --dpi 300 +done + +# With error handling +for pdf in *.pdf; do + if pdf-to-pptx-tool -v convert "$pdf" "${pdf%.pdf}.pptx"; then + echo "✓ Converted $pdf" + else + echo "✗ Failed to convert $pdf" + fi +done +``` + +### Shell Completion + +Enable tab completion for faster usage: + +```bash +# Bash - add to ~/.bashrc +eval "$(pdf-to-pptx-tool completion bash)" + +# Zsh - add to ~/.zshrc +eval "$(pdf-to-pptx-tool completion zsh)" + +# Fish - save to completions directory +mkdir -p ~/.config/fish/completions +pdf-to-pptx-tool completion fish > ~/.config/fish/completions/pdf-to-pptx-tool.fish +``` + +**Benefits:** +- Tab-complete commands: `pdf-to-pptx-tool ` +- Tab-complete options: `pdf-to-pptx-tool convert --` +- Tab-complete file paths automatically + +
+ +
+🔧 Troubleshooting (Click to expand) + +### Common Issues + +**Issue: "poppler not found" or PDF conversion fails** +```bash +# Symptom +RuntimeError: Failed to convert PDF pages: poppler not found +``` + +**Solution:** +Install poppler system library: +```bash +# macOS +brew install poppler + +# Ubuntu/Debian +sudo apt-get install poppler-utils + +# Fedora +sudo dnf install poppler-utils + +# Verify installation +pdftoppm -v +``` + +--- + +**Issue: "File not found" error** +```bash +# Symptom +✗ Error: Input PDF file not found: document.pdf +``` + +**Solution:** +- Verify file path is correct +- Use absolute paths if needed +- Check file permissions +```bash +# Check file exists +ls -l document.pdf + +# Use absolute path +pdf-to-pptx-tool convert /full/path/to/document.pdf output.pptx +``` + +--- + +**Issue: Output file is too large** +```bash +# Symptom +Generated 50MB PPTX from 2MB PDF +``` + +**Solution:** +Reduce DPI setting: +```bash +# Try lower DPI +pdf-to-pptx-tool convert input.pdf output.pptx --dpi 150 + +# Or use default 200 DPI +pdf-to-pptx-tool convert input.pdf output.pptx +``` + +--- + +**Issue: Images look blurry in PowerPoint** +```bash +# Symptom +Text and diagrams appear pixelated +``` + +**Solution:** +Increase DPI setting: +```bash +# Use higher quality +pdf-to-pptx-tool convert input.pdf output.pptx --dpi 300 + +# For print quality +pdf-to-pptx-tool convert input.pdf output.pptx --dpi 600 +``` + +--- + +**Issue: Conversion is very slow** +```bash +# Symptom +Large PDF takes minutes to convert +``` + +**Solution:** +1. Use DEBUG logging to see progress: +```bash +pdf-to-pptx-tool -vv convert large.pdf output.pptx +``` + +2. Consider lower DPI for faster conversion: +```bash +pdf-to-pptx-tool convert large.pdf output.pptx --dpi 150 +``` + +3. Split large PDF into chunks and convert separately + +--- + +**Issue: Permission denied writing output file** +```bash +# Symptom +PermissionError: [Errno 13] Permission denied: 'output.pptx' +``` + +**Solution:** +- Check directory write permissions +- Use different output location +```bash +# Write to home directory +pdf-to-pptx-tool convert input.pdf ~/output.pptx + +# Or create directory first +mkdir -p output-dir +pdf-to-pptx-tool convert input.pdf output-dir/output.pptx +``` + +### Getting Help + +```bash +# Tool help +pdf-to-pptx-tool --help + +# Command help +pdf-to-pptx-tool convert --help + +# Completion help +pdf-to-pptx-tool completion --help + +# Version info +pdf-to-pptx-tool --version +``` + +### Debug Workflow + +When conversion fails, use this debugging workflow: + +```bash +# 1. Check file exists and is readable +ls -lh document.pdf +file document.pdf + +# 2. Verify poppler is installed +pdftoppm -v + +# 3. Try with DEBUG logging +pdf-to-pptx-tool -vv convert document.pdf test.pptx + +# 4. Try with lower DPI if memory issues +pdf-to-pptx-tool -vv convert document.pdf test.pptx --dpi 150 + +# 5. Check Python and dependencies +python --version +pdf-to-pptx-tool --version +``` + +
+ +## Exit Codes + +- `0`: Success - conversion completed successfully +- `1`: Error - file not found, invalid input, conversion failed, or permission denied + +## Output Formats + +**Default PowerPoint Output:** +- **Format**: Office Open XML (.pptx) +- **Aspect Ratio**: 16:9 widescreen +- **Slide Size**: 10 inches × 5.625 inches +- **Layout**: One full-slide image per PDF page +- **Image Format**: PNG embedded in slides +- **Compatibility**: PowerPoint 2007+ (Windows/Mac/Online) + +**Console Output:** +```bash +# Success +✓ Successfully converted document.pdf to slides.pptx + +# Error +✗ Error: Input PDF file not found: document.pdf +``` + +**Logging Output (with -v/-vv/-vvv):** +```bash +[INFO] Starting PDF to PPTX conversion +[INFO] Converting document.pdf to slides.pptx (DPI: 200) +[DEBUG] Input file size: 2.45 MB +[INFO] Converted 10 pages +[DEBUG] Output file size: 12.78 MB +[INFO] Conversion completed successfully +``` + +## Best Practices + +1. **Start with default DPI (200)**: Good balance of quality and file size +2. **Use verbose logging for debugging**: `-vv` shows detailed conversion steps +3. **Test with sample PDFs first**: Verify quality before batch processing +4. **Monitor output file sizes**: Adjust DPI if files are too large +5. **Batch process efficiently**: Use shell loops for multiple files +6. **Enable shell completion**: Speeds up command-line usage +7. **Keep poppler updated**: Ensures compatibility with latest PDF features +8. **Use absolute paths**: Avoids confusion with relative paths +9. **Verify prerequisites**: Check poppler installation before bulk conversions +10. **Handle errors gracefully**: Check exit codes in scripts + +## Resources + +- **GitHub Repository**: https://github.com/dnvriend/pdf-to-pptx-tool +- **Python Dependencies**: + - pdf2image (PDF to image conversion) + - python-pptx (PowerPoint file creation) + - Pillow (Image processing) + - Click (CLI framework) +- **System Dependencies**: poppler (PDF rendering engine) +- **Related Tools**: + - PyPDF2 (PDF text extraction) + - ReportLab (PDF generation) + - pandoc (Universal document converter)