search

asciidoctor / asciidoctor-pdf

:page_with_curl: Asciidoctor PDF: A native PDF converter for AsciiDoc based on Asciidoctor and Prawn, written entirely in Ruby.
https://docs.asciidoctor.org/pdf-converter/latest/
MIT License
1.13k stars 499 forks source link

Arrows not shown in BPMN diagrams #2526

Closed janwesterkamp closed 3 weeks ago

janwesterkamp commented 3 weeks ago

BPMN drawings do not show arrows in their connections, only lines are visible in PDF version.

The SVGs generated from Asciidoctor(J) Diagram shows the arrows and so the simultaneously created HTML version shows them in the correct way too, as tooling like the Camunda Modeler or Eclipse IDE does.

BPMN source example: bpmn-example.bpmn.zip

SVG generated: bpmn-example

PDF generated with error: BPMN error.pdf

Environment:

macOS Intel 14.5 (23F79)
Java SE 21.0.3
JRuby 9.4.7.0
Maven 3.9.7
Asciidoctor Maven Plugin 3.0.0
AsciidoctorJ 2.5.13
AsciidoctorJ Diagram 2.3.0
AsciidoctorJ PDF 2.3.17
bmnn-js 10.2.1
bpmn-js-cmd 0.4.0

This issue was created originally in asciidoctor/asciidoctorj-pdf (https://github.com/asciidoctor/asciidoctorj-pdf/issues/105). @robertpanzer tested it in a pure ruby environment with the same error and suggested to open it here. He also documented a workaround with using PNG instead of SVG formatting until this bug is fixed.

mojavelinux commented 3 weeks ago

This appears to be a limitation of prawn-svg. If I use Prawn and feed the image directly to the svg function provided by prawn-svg, the arrows are missing there too. Unless the feature of SVG that is required to draw the errors is supported by prawn-svg, they will not work in Asciidoctor PDF.

mojavelinux commented 3 weeks ago

Feel free to reopen once this issue is resolved upstream and we'll upgrade prawn-svg.

janwesterkamp commented 3 weeks ago

Hi @mojavelinux, thanks for your analysis! I will create an issue upstream in prawn-svg to have it fixed there.

I am a little bit surprised that there are completely separate workflows for rendering and integrating BPMNs in the different output formats like PDF and HTML. May be it could make sense to have this as a configuration option, so deviations could be limited and behaviour could be under user control. What you think about it?

In my current use case, I need to document the (arc42) software architecture and this error came up late, as it shows up on the PDF version in BPMN diagrams only. For the deployment diagrams having hyperlink support would be my next challenge in the PDF version (opposed to the buggy marker functionality, this is not supported at all in prawn-svg yet, according to the documentation). However, the HTML workflow requires JavaScript tooling (bpmn-js-cmd, bpmn-js etc. with node), which will be not my first choice in every case... The other use case for using these diagrams in EF Specification Working Groups, reviewers need to be aware of these separate workflows and check both versions of the documents (PDF and HTML). With a configurable workflow/toolchain, this could help to choose the best (and single) one for a use case.

mojavelinux commented 3 weeks ago

Thanks for filing the issue upstream.

I'm not really sure how your additional commentary pertains to Asciidoctor PDF in any way. It sounds more like you're talking about the diagram extensions for Asciidoctor. Diagrams are not a core part of the AsciiDoc language and are thus served by extensions. Those extensions then use various diagramming tools to convert text-oriented diagrams into images. When the diagram extension feeds the generated images back into the processor (Asciidoctor), the converter will include them in the rendered document (regardless of whether that is HTML or PDF, the process is the same).

While it's true that there are lots of different diagram input formats, and lots of different tools to convert those inputs to images, that has absolutely nothing to do with Asciidoctor PDF and how it works. If the image is valid, it will be included. If the image library can't handle some part of it, that has to be dealt with upstream (as in this case).

If you are concerned about how much software is required to process diagrams, perhaps you might consider trying Asciidoctor Kroki, which provides a diagram server to alleviate those installation requirements. If you have questions about the diagram extensions, please direct them to the project chat at https://chat.asciidoctor.org. This issue tracker is not the place for this discussion.

janwesterkamp commented 3 weeks ago

Oh, this was my misunderstanding and confusion, sorry: I thought asciidoctor-pdf does not make use of the SVG image files generated by the asciidoctor-diagram extension and used by the HTML version. But when it does and the rendering (which is done by the browser in the HTML version) by the prawn-svg is the issue because of limited functionality, this make sense.

My further analysis of the SVG source turned out, that the marker-element, may be in combination with the url is the root cause, because this is only used in the BPMN originated SVG, not in the ones like from other diagram sources as ditaa or PlantUML (because low level functionality as polygon-elements are used to draw arrows only), so let's see the outcome on the prawn-svg project.