plantuml !include "cannot include file"

[tja-m]

Observed vs. expected behavior

Scenario

• A document including PlantUML files as embedded figures
• Included puml files use !include to further puml files.

Behaviour

• Sometimes preview contains error message instead of rendered diagram:

ERROR uri:classloader:/gems/asciidoctor-2.0.15/lib/asciidoctor/parser.rb:build_block: .../package1-classes.puml:0 Failed to generate image: PlantUML preprocessing failed: [From  (line 4) ]
@startuml 'https://plantuml.com/class-diagram 
!include classes/Class1.puml!0 
^^^^^ cannot include classes/Class1.puml

• Rendering PDF results in the same error message
• Opening the puml files, which are included from AsciiDoc directly in IntelliJ PUML editor typically also fix display in AsciiDoc preview.
  • Rendering PDF still fails.

The behaviour is similar to Issue 175: plantuml !include not working but with different error message.

Steps to reproduce

• Open attached document asciidoctor-intellij-puml-include-v2.zip in IntelliJ
  • Sometimes it happens, sometimes it doesn't, when trying to render a PDF. Somtimes preview is broken. I cannot exactly tell, what triggers which behaviour. Only it seems, that opening the diagrams in PUML editor seems to help fixing broken display in preview.

Environment

Plugin Version: 0.33.6

IntelliJ Details:
IntelliJ IDEA 2021.1.3 (Ultimate Edition)
Build #IU-211.7628.21, built on June 29, 2021
...
Runtime version: 11.0.11+9-b1341.60 amd64
VM: OpenJDK 64-Bit Server VM by JetBrains s.r.o.
Windows 10 10.0
GC: G1 Young Generation, G1 Old Generation
Memory: 8192M
Cores: 12
Non-Bundled Plugins: org.intellij.plugins.hcl (0.7.10), org.jetbrains.kotlin (211-1.5.21-release-317-IJ7442.40), PlantUML integration (5.5.1), Pythonid (211.7628.24), org.asciidoctor.intellij.asciidoc (0.33.6)
Kotlin: 211-1.5.21-release-317-IJ7442.40

asciidoctor-intellij-puml-include-v2.zip

[ahus1]

I had a brief look and my hypothesis is the following: There are relative includes within the plantuml diagrams. When opening them in the plantuml plugin for IntelliJ they work fine. When they are rendered in AsciiDoc, the relative include paths in plantuml are interpreted from the document folder, not the include folder.

I'm not yet sure when the images in the preview render; maybe the plantuml plugin creates the image in a temporary folder. I'll need to do some more research here...

[ahus1]

I had another look: PlantUML will resolve the includes relative to the current file.

When using includes like include::puml/package1/package1-classes.puml[], the current file will be where the main document is located (model.adoc in your case). Due to that a relative include !include classes/Class1.puml!0 will fail when executed from Asciidoctor (although it works when opening a single diagram in the PlantUML plugin, as this would have a different starting path).

To make this work both in the IDE and the command line, I recommend the following:

• change the PlantUML includes so they start at the folder of the main document (for example !include puml/package1/classes/Class1.puml!0)
• in the PlantUML settings in your IDE, add as "Additional 'plantuml.include.path' the folder where you main document resides. This will make the new includes work the IDE's PlantUML editor.

As this setting is using a system environment variable I am hesitant to add it to the AsciiDoc plugin. Most likely it will interfere with rendering PlantUML diagrams, as setting this in the AsciiDoc plugin will affect all plugins running in the same JVM.

Please let me know if this answer is helpful and if this issue an be closed.

[ahus1]

This question has been inactive for some days, therefore I close it. If the issue persists, comment here and I'll re-open the issue.

[sponiro]

I read up about Include file resolution in Asciidoctor. The path resolution of a relative include is described as relative to the including (i.e. current) file. What if we could manage to change the working directory to the plantuml file when an include for such a file is done? I just borrowed the working directory concept - it might work differently.
For example:

[plantuml, package1-classes, svg]
....
include::puml/package1/package1-classes.puml[]
....

So, when passing rendering to Plantuml the "working" directoy could be changed to puml/package1. All relative paths inside package1-classes.puml would be based on that directory. It seems that Plantuml in IntelliJ IDEA does it that way.