Story: PlantUML integration: recipe and codegen scaffold

Table of Contents

This page documents a story in Sprint 18. It captures the goal, current status, acceptance criteria, and the tasks that compose it.

Goal

Make PlantUML diagrams a first-class citizen of ORE Studio's documentation workflow. A how-to recipe explains how to write and embed a .puml diagram in any org-mode document; a new compass add diagram sub-command scaffolds a .puml file with the standard licence header, @startuml / @enduml delimiters, and the project skin/style preamble so every diagram is consistent from the first line.

Status

Field Value
State DONE
Parent sprint Sprint 18
Now Complete.
Waiting on Nothing.
Next None.
Last touched 2026-05-28

Acceptance

  • doc/recipes/plantuml/how_do_i_add_a_plantuml_diagram.org exists and explains: install/verify PlantUML, write the .puml source, run plantuml to export the PNG, and embed it in org-mode with an #+attr_html: / #+attr_latex: figure block.
  • compass add diagram <slug> (or equivalent sub-command) scaffolds <slug>.puml with the standard AGPL licence header, @startuml / @enduml, and the shared skin preamble; the generated file matches the convention of existing diagrams in the repo.
  • Existing .puml files are audited; any that lack the standard header are updated.

Tasks

Task State Start End Description
Task: Add PlantUML recipe and extend codegen with puml scaffold DONE 2026-05-28 2026-05-28 PlantUML integration: recipe and codegen scaffold

Decisions

Out of scope

  • Automating PNG regeneration in CI (diagrams are regenerated manually when the source changes).
  • Switching to SVG output — PNG is the current convention.

Emacs 29.1 (Org mode 9.6.6)