PlantUML !include preprocessor?

[anb0s]

I'm using lot of !include files in PlantUML diagrams to have clear sturcture and DRY.

== UML class diagram test with kroki
[plantuml, "diagram-classes", svg]
....
!include <src/style-presets.iuml>

class BlockProcessor
class DiagramBlock
class DitaaBlock
class PlantUmlBlock

BlockProcessor <|-- DiagramBlock
DiagramBlock <|-- DitaaBlock
DiagramBlock <|-- PlantUmlBlock
....

For local builds with plantuml.jar it works, but with remote server like PlantUML server or kroki it does not work. I understand that it is not wanted, because it will do preprocessing with knowlegde of PlantUML syntax and has to be updated etc.

Is there other solution to solve similar structural problems at client side?

[ggrossetie]

One solution is to use the Asciidoctor include directive:

[plantuml, "diagram-classes", svg]
....
include::src/style-presets.iuml[]

class BlockProcessor
class DiagramBlock
class DitaaBlock
class PlantUmlBlock

BlockProcessor <|-- DiagramBlock
DiagramBlock <|-- DitaaBlock
DiagramBlock <|-- PlantUmlBlock
....

Kroki ignores the PlantUML include directive for security reasons.
Otherwise, you will be able to fetch content from Internet or read files from the file system:

!include </etc/passwd>

We could also the fetch the content in a preprocessing task before sending the content to Kroki.
Please note that the same issue exists on Vega where you can load data from an URL: https://vega.github.io/vega/docs/data/ but this feature is also disabled for security reasons.

[anb0s]

For using the Asciidoctor include derective i've to rework all the diagrams. It would be good to have a preprocessing task at client before sending it to the server. So at the end this would be good just to include the diagram files:
e.g.
presentation.adoc:

[plantuml, "diagram-classes", svg]
....
include::src/diagram-classes.puml[]
....

The diagram file itself includes other needed files.

src/diagram-classes.puml:

@startuml
!include <style-presets.iuml>

class BlockProcessor
class DiagramBlock
class DitaaBlock
class PlantUmlBlock

BlockProcessor <|-- DiagramBlock
DiagramBlock <|-- DitaaBlock
DiagramBlock <|-- PlantUmlBlock
@enduml

So the preprocessor should fetch all the files recursevly and avoid loading same files (include loop).

P.S.: similar was implemented in the vscode-plantuml plugin.

[anb0s]

@Mogztter Thanks!

I'm waiting for the new version of asciidoctor-kroki as refrenced in asciidoctor-vscode :)

Do you have a timeline (milestones) for new version?

[ggrossetie]

No timeline, I want to play with it a few days before publishing a new version. As far as I know you are already using it?

[ggrossetie]

I'm waiting for the new version of asciidoctor-kroki as refrenced in asciidoctor-vscode :)

@anb0s If you could confirm that the integration is working smoothly in VS Code that would be nice. If we found a blocker we could fix it before the release.
I will integrate the latest version (master) in the Asciidoctor Browser Extension and in an Antora documentation site to make sure that everything is working as expected.

[anb0s]

@Mogztter i'm using VSCode and have no free time to integrate asciidoc-kroki by myself now, so i'm asking for it :)

@danyill Do you have a hint how to use private builds of extensions in VSCode? May be i will find some time for it...

I'm testing asciidoc-kroki together with own scripts in node.js environment with asciidoctor and reveal.js. I will maybe have time tomorow to test it more or after vacation after 15.06. then...

[danyill]

hey @Mogztter @anb0s you guys are doing great work here 👏 👏 👏

You can test this with the Asciidoctor VS Code extension by:

1. Clone the VS Code extension. I'd suggest checking out my branch for removal of plantuml to avoid any contamination.... danyill:issue-308-remove-plantuml (see asciidoctor/asciidoctor-vscode#311)
2. Install the dependencies normally npm i.
3. Go to your asciidoctor-kroki directory and run npm link
4. Return to the VS code extension directory and run npm link asciidoctor-kroki
5. Open the extension folder in VS Code and then going Run > Start Debugging (there's an error I haven't figured out so when you get something about error code 2 just click "Debug Anyway" it's not functional).
6. VS Code should open a new window/instance with just this extension enabled and you should be able to test as you'd normally use the editor.

I hope to find some time to test before too long (I've noticed for instance that with kroki-fetch-diagram set you can easily get many images with different filenames saved if you type the filename and the preview or symbol outline keeps updating.).

[ggrossetie]

set you can easily get many images with different filenames saved if you type the filename and the preview or symbol outline keeps updating.).

But the filename should now be stable? We are now using the target filename right?

It made me think that now we cannot tell if we need to fetch the image again from the server because we are no longer using the md5sum of the diagram as filename...
We will probably need to address this issue because it can greatly affect performance.

[scphantm]

Im just stabbing in the dark here, but would this affect this bug. plantuml-stdlib/C4-PlantUML#156

Thanks

[ggrossetie]

Sort of, the PlantUML preprocessor resolves !include directives in order to create a "standalone" diagram definition.

Unfortunately, it can't resolve "complex" statements like %get_variable_value. Instead, the PlantUML preprocessor will try to read a file (using %get_variable_value("RELATIVE_INCLUDE")/C4.puml as path) on your local file system.

It's tricky because it's a preprocessor, so it cannot evaluate PlantUML syntax such as the if condition or the %get_variable_value function.

Do you send your diagrams to the public instance https://kroki.io or to a local instance?

If you want to use the built-in version of C4, I would recommend to use the following syntax:

!include <c4/C4_Context.puml>

In this case, the preprocessor will ignore the !include directive and Kroki server will resolve the !include directive using built-in C4 definition files.

[scphantm]

we are using the public instance of kroki. i switched to the includes you suggested and got a whole bunch of

Skipping preprocessing of PlantUML standard library include file '<c4/C4_Context.puml>'

lines. no errors, my SRE guys will be please. thank you.

[ggrossetie]

Cool!

got a whole bunch of [...] lines. no errors, my SRE guys will be please.

This issue will be addressed as part of #147.
I'm glad it's working for you 👍🏻

[jdomag]

@Mogztter @scphantm
Can you elaborate more on how to make use include statements?
The below code doesn't work as expected

[plantuml, "mydiagram", png]
----
!include my_planuml.iuml
----