From d21718d9911500105ea7b43f03ef19fbb11faf6f Mon Sep 17 00:00:00 2001
From: Ivan Dolgov <ivan@qvarnlabs.com>
Date: Thu, 14 Sep 2017 16:16:34 +0300
Subject: Add PlantUML support design doc

---
 docs/plantuml.mdwn | 80 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)
 create mode 100644 docs/plantuml.mdwn

diff --git a/docs/plantuml.mdwn b/docs/plantuml.mdwn
new file mode 100644
index 0000000..c8d2bca
--- /dev/null
+++ b/docs/plantuml.mdwn
@@ -0,0 +1,80 @@
+# PlantUML support
+
+PlantUML is a tool for generating UML (and some non-UML) diagrams from plain text
+descriptions. Instead of creating and linking diagram images in Ikiwiki Markdown
+files, embedded PlantUML source code is a more handy and git-friendly solution.
+
+The best way to implement this feature would of course be a PlantUML plugin for
+Ikiwiki, but since we are much more comfortable with Python than Ruby we are
+addind it to `ql-ikiwiki-publish`.
+
+## Implementation
+
+The idea is to detect diagram code included in wiki pages and replace it with a
+link to a generated diagram image.
+
+It is also useful to be able to include external UML files instead of embedding
+code directly into wiki pages. This way we can easily preview the diagrams
+before committing.
+
+So basically what `ql-ikiwiki-publish` will be doing is as follows:
+
+1. Recognize relevant diagram code.
+
+2. Copy it into a temporary file.
+
+3. Generate a diagram image by running `plantuml` with the temp file as an
+   argument.
+
+4. Copy the diagram image into Ikiwiki output directory.
+
+5. Replace embedded diagram code or diagram file include statement with a `img`
+   directive containing a path or link to the diagram image.
+
+### Code block syntax
+
+In case of directly embedded diagram code, the most sensibe syntax seems to be
+PlantUML within Markdown code block, which would look like this:
+
+[[!format  md """
+```
+@startuml
+Alice -> Bob: Hello
+Bob -> Alice: Hello
+@enduml
+```
+"""]]
+
+Or like this:
+
+[[!format  md """
+    @startuml
+    Alice -> Bob: Hello
+    Bob -> Alice: Hello
+    @enduml
+"""]]
+
+In case when raw PlantUML code needs to be shown instead of an image, `format`
+directive syntax can be used to prevent the code from being replaced by
+`ql-ikiwiki-publish`:
+
+```
+[[!format  md """
+@startuml
+Alice -> Bob: Hello
+Bob -> Alice: Hello
+@enduml
+"""]]
+```
+
+### External file syntax
+
+In order to include an external diagram code file, we need a custom syntax only
+recognizable by `ql-ikiwiki-publish` but preferably ignored by other Markdown
+parsers. This can be achieved by using HTML comment syntax:
+
+[[!format  html """
+<!-- INCLUDE_UML: some_file.puml -->
+"""]]
+
+Pandoc-style triple dash can be also used to make it even more parser-friendly.
-- 
cgit v1.2.1