514 lines
13 KiB
Markdown
514 lines
13 KiB
Markdown
---
|
||
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
|
||
|
||
<details>
|
||
<summary><strong>📖 Core Commands (Click to expand)</strong></summary>
|
||
|
||
### 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.
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><strong>⚙️ Advanced Features (Click to expand)</strong></summary>
|
||
|
||
### 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>`
|
||
- Tab-complete options: `pdf-to-pptx-tool convert --<TAB>`
|
||
- Tab-complete file paths automatically
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><strong>🔧 Troubleshooting (Click to expand)</strong></summary>
|
||
|
||
### 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
|
||
```
|
||
|
||
</details>
|
||
|
||
## 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)
|