# 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 an `img`
   Ikiwiki 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:

        @startuml
        Alice -> Bob: Hello
        Bob -> Alice: Hello
        @enduml

In case when raw PlantUML code needs to be shown instead of an image, a `format`
directive 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:

    <!-- INCLUDE_UML: some_file.puml -->

Pandoc-style triple dash can be also used to make it even more parser-friendly:

    <!--- INCLUDE_UML: some_file.puml -->

## Testing

Run `ql-ikiwiki-publish` against a provided test page:

    cd docs/plantuml-test/
    ../../ql-ikiwiki-publish
    firefox ...