summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorIvan Dolgov <ivan@qvarnlabs.com>2017-09-14 16:16:34 +0300
committerIvan Dolgov <ivan@qvarnlabs.com>2017-09-14 16:16:34 +0300
commitd21718d9911500105ea7b43f03ef19fbb11faf6f (patch)
treee47fefe931d77642026ad46380720d965cca9230
parentea9e776e50ed805c33327c067a0e99c6f92e4f03 (diff)
downloadql-ikiwiki-publish-d21718d9911500105ea7b43f03ef19fbb11faf6f.tar.gz
Add PlantUML support design doc
-rw-r--r--docs/plantuml.mdwn80
1 files changed, 80 insertions, 0 deletions
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.