Document re-entrant update workflow, slideId support, and template-based iterative deck authoring

[jongalloway]

Summary

The re-entrant deck update work adds important new user-facing capabilities, but the current PR does not update the docs surface.

We should add documentation for:

• --update-existing <previous.pptx>
• --template <template.pptx> used together with update mode
• slide extLst-based managed slide reconciliation at a conceptual level
• slideId directives
• --write-slide-ids
• an end-to-end workflow that starts from authoring a deck, applies a template, makes manual PowerPoint edits, updates the Markdown, and regenerates safely

Why this matters

Without docs, the new behavior is hard to discover and easy to misuse.

In particular, users need to understand that:

• a previous/generated deck and a rendering template are different semantic entities
• --update-existing reconciles against an existing managed deck
• --template controls layouts, masters, and Template[n] rendering during both fresh generation and update scenarios
• explicit slideId directives improve mapping stability
• --write-slide-ids can bootstrap those directives into source automatically
• unmanaged slides are preserved, but changed managed slides are still replaced wholesale

Current gap

The current PR branch changes only code and tests. It does not touch:

• README.md
• doc/using-templates.md
• or any dedicated walkthrough document for iterative update workflows

Documentation updates needed

1. README update

Add a concise feature section to README.md covering:

• what re-entrant deck update mode is
• the required CLI syntax
• how --update-existing and --template differ
• what --write-slide-ids does
• a short example command sequence

Recommended README examples:

marp2pptx deck.md --template conference-template.pptx -o deck.pptx
marp2pptx deck.md --write-slide-ids -o deck.pptx
marp2pptx deck.md --update-existing previous-deck.pptx --template conference-template.pptx -o updated-deck.pptx

2. Update doc/using-templates.md

Expand the template docs so they cover update mode explicitly.

Important additions:

• clarify that --template is the rendering source
• clarify that --update-existing is the reconciliation source
• explain how Template[n] behaves when a separate template is provided during updates
• include a short “fresh render vs update render” comparison

3. Add a walkthrough doc

Create a new walkthrough document, likely something like:

• doc/updating-existing-decks.md
• or doc/reentrant-update-workflow.md

This should be a practical, start-to-finish guide.

Recommended walkthrough content

Scenario

Use a realistic workflow such as:

1. Create a Marp deck.
2. Render it with a PowerPoint template.
3. Add manual PowerPoint-only content such as a marketing slide.
4. Optionally run --write-slide-ids to persist explicit mapping into source.
5. Change the Markdown.
6. Re-run with --update-existing <previous.pptx> --template <template.pptx>.
7. Verify what was preserved and what was regenerated.

Explain expected behavior clearly

The walkthrough should explicitly call out:

• managed slides are matched by slide identity, not ordinal position
• unmanaged slides are preserved
• changed managed slides are replaced rather than merged shape-by-shape
• existing explicit slideId directives are preserved
• --write-slide-ids adds only missing directives

Include at least one template-slide example

Show a deck that uses:

<!-- _layout: Template[1] -->

Then show the matching update command with both:

• --update-existing previous-deck.pptx
• --template conference-template.pptx

Include troubleshooting notes

Document common mistakes such as:

• forgetting to pass the previous deck to --update-existing
• expecting --template to act as the previous deck
• assuming changed managed slides preserve manual edits inside the same slide
• assuming slideId directives carry forward automatically

Acceptance criteria

• README.md mentions re-entrant update mode and --write-slide-ids
• README.md shows the distinction between previous deck and template
• doc/using-templates.md covers update-mode usage with templates
• a new walkthrough doc exists for iterative deck authoring and update workflows
• docs include at least one Template[n] example in update mode
• docs include at least one --write-slide-ids example
• docs clearly state the current limitation that changed managed slides are replaced wholesale

Related work

• Follow-up to Add re-entrant deck update mode using slide extLst metadata #133
• Closely related to PR Add re-entrant deck update mode using slide extLst metadata #134

Suggested labels

• type:feature
• area:rendering