skill-pdf-to-pptx-tool

What this skill does

# 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/comp