1# Editing Presentations
2 
3## Template-Based Workflow
4 
5When using an existing presentation as a template:
6 
71. **Analyze existing slides**:
8   ```bash
9   python scripts/thumbnail.py template.pptx
10   python -m markitdown template.pptx
11   ```
12   Review `thumbnails.jpg` to see layouts, and markitdown output to see placeholder text.
13 
142. **Plan slide mapping**: For each content section, choose a template slide.
15 
16   ⚠️ **USE VARIED LAYOUTS** — monotonous presentations are a common failure mode. Don't default to basic title + bullet slides. Actively seek out:
17   - Multi-column layouts (2-column, 3-column)
18   - Image + text combinations
19   - Full-bleed images with text overlay
20   - Quote or callout slides
21   - Section dividers
22   - Stat/number callouts
23   - Icon grids or icon + text rows
24 
25   **Avoid:** Repeating the same text-heavy layout for every slide.
26 
27   Match content type to layout style (e.g., key points → bullet slide, team info → multi-column, testimonials → quote slide).
28 
293. **Unpack**: `python scripts/office/unpack.py template.pptx unpacked/`
30 
314. **Build presentation** (do this yourself, not with subagents):
32   - Delete unwanted slides (remove from `<p:sldIdLst>`)
33   - Duplicate slides you want to reuse (`add_slide.py`)
34   - Reorder slides in `<p:sldIdLst>`
35   - **Complete all structural changes before step 5**
36 
375. **Edit content**: Update text in each `slide{N}.xml`.
38   **Use subagents here if available** — slides are separate XML files, so subagents can edit in parallel.
39 
406. **Clean**: `python scripts/clean.py unpacked/`
41 
427. **Pack**: `python scripts/office/pack.py unpacked/ output.pptx --original template.pptx`
43 
44---
45 
46## Scripts
47 
48| Script | Purpose |
49|--------|---------|
50| `unpack.py` | Extract and pretty-print PPTX |
51| `add_slide.py` | Duplicate slide or create from layout |
52| `clean.py` | Remove orphaned files |
53| `pack.py` | Repack with validation |
54| `thumbnail.py` | Create visual grid of slides |
55 
56### unpack.py
57 
58```bash
59python scripts/office/unpack.py input.pptx unpacked/
60```
61 
62Extracts PPTX, pretty-prints XML, escapes smart quotes.
63 
64### add_slide.py
65 
66```bash
67python scripts/add_slide.py unpacked/ slide2.xml      # Duplicate slide
68python scripts/add_slide.py unpacked/ slideLayout2.xml # From layout
69```
70 
71Prints `<p:sldId>` to add to `<p:sldIdLst>` at desired position.
72 
73### clean.py
74 
75```bash
76python scripts/clean.py unpacked/
77```
78 
79Removes slides not in `<p:sldIdLst>`, unreferenced media, orphaned rels.
80 
81### pack.py
82 
83```bash
84python scripts/office/pack.py unpacked/ output.pptx --original input.pptx
85```
86 
87Validates, repairs, condenses XML, re-encodes smart quotes.
88 
89### thumbnail.py
90 
91```bash
92python scripts/thumbnail.py input.pptx [output_prefix] [--cols N]
93```
94 
95Creates `thumbnails.jpg` with slide filenames as labels. Default 3 columns, max 12 per grid.
96 
97**Use for template analysis only** (choosing layouts). For visual QA, use `soffice` + `pdftoppm` to create full-resolution individual slide images—see SKILL.md.
98 
99---
100 
101## Slide Operations
102 
103Slide order is in `ppt/presentation.xml` → `<p:sldIdLst>`.
104 
105**Reorder**: Rearrange `<p:sldId>` elements.
106 
107**Delete**: Remove `<p:sldId>`, then run `clean.py`.
108 
109**Add**: Use `add_slide.py`. Never manually copy slide files—the script handles notes references, Content_Types.xml, and relationship IDs that manual copying misses.
110 
111---
112 
113## Editing Content
114 
115**Subagents:** If available, use them here (after completing step 4). Each slide is a separate XML file, so subagents can edit in parallel. In your prompt to subagents, include:
116- The slide file path(s) to edit
117- **"Use the Edit tool for all changes"**
118- The formatting rules and common pitfalls below
119 
120For each slide:
1211. Read the slide's XML
1222. Identify ALL placeholder content—text, images, charts, icons, captions
1233. Replace each placeholder with final content
124 
125**Use the Edit tool, not sed or Python scripts.** The Edit tool forces specificity about what to replace and where, yielding better reliability.
126 
127### Formatting Rules
128 
129- **Bold all headers, subheadings, and inline labels**: Use `b="1"` on `<a:rPr>`. This includes:
130  - Slide titles
131  - Section headers within a slide
132  - Inline labels like (e.g.: "Status:", "Description:") at the start of a line
133- **Never use unicode bullets (•)**: Use proper list formatting with `<a:buChar>` or `<a:buAutoNum>`
134- **Bullet consistency**: Let bullets inherit from the layout. Only specify `<a:buChar>` or `<a:buNone>`.
135 
136---
137 
138## Common Pitfalls
139 
140### Template Adaptation
141 
142When source content has fewer items than the template:
143- **Remove excess elements entirely** (images, shapes, text boxes), don't just clear text
144- Check for orphaned visuals after clearing text content
145- Run visual QA to catch mismatched counts
146 
147When replacing text with different length content:
148- **Shorter replacements**: Usually safe
149- **Longer replacements**: May overflow or wrap unexpectedly
150- Test with visual QA after text changes
151- Consider truncating or splitting content to fit the template's design constraints
152 
153**Template slots ≠ Source items**: If template has 4 team members but source has 3 users, delete the 4th member's entire group (image + text boxes), not just the text.
154 
155### Multi-Item Content
156 
157If source has multiple items (numbered lists, multiple sections), create separate `<a:p>` elements for each — **never concatenate into one string**.
158 
159**❌ WRONG** — all items in one paragraph:
160```xml
161<a:p>
162  <a:r><a:rPr .../><a:t>Step 1: Do the first thing. Step 2: Do the second thing.</a:t></a:r>
163</a:p>
164```
165 
166**✅ CORRECT** — separate paragraphs with bold headers:
167```xml
168<a:p>
169  <a:pPr algn="l"><a:lnSpc><a:spcPts val="3919"/></a:lnSpc></a:pPr>
170  <a:r><a:rPr lang="en-US" sz="2799" b="1" .../><a:t>Step 1</a:t></a:r>
171</a:p>
172<a:p>
173  <a:pPr algn="l"><a:lnSpc><a:spcPts val="3919"/></a:lnSpc></a:pPr>
174  <a:r><a:rPr lang="en-US" sz="2799" .../><a:t>Do the first thing.</a:t></a:r>
175</a:p>
176<a:p>
177  <a:pPr algn="l"><a:lnSpc><a:spcPts val="3919"/></a:lnSpc></a:pPr>
178  <a:r><a:rPr lang="en-US" sz="2799" b="1" .../><a:t>Step 2</a:t></a:r>
179</a:p>
180<!-- continue pattern -->
181```
182 
183Copy `<a:pPr>` from the original paragraph to preserve line spacing. Use `b="1"` on headers.
184 
185### Smart Quotes
186 
187Handled automatically by unpack/pack. But the Edit tool converts smart quotes to ASCII.
188 
189**When adding new text with quotes, use XML entities:**
190 
191```xml
192<a:t>the &#x201C;Agreement&#x201D;</a:t>
193```
194 
195| Character | Name | Unicode | XML Entity |
196|-----------|------|---------|------------|
197| `“` | Left double quote | U+201C | `&#x201C;` |
198| `”` | Right double quote | U+201D | `&#x201D;` |
199| `‘` | Left single quote | U+2018 | `&#x2018;` |
200| `’` | Right single quote | U+2019 | `&#x2019;` |
201 
202### Other
203 
204- **Whitespace**: Use `xml:space="preserve"` on `<a:t>` with leading/trailing spaces
205- **XML parsing**: Use `defusedxml.minidom`, not `xml.etree.ElementTree` (corrupts namespaces)
206