Stream: IG creation
Topic: PlantUML in markdown
Jose Costa Teixeira (Dec 10 2020 at 16:20):
For those who want to test plantuml in markdown, this may work (it's alpha, not fully tested, not sure if it's legal, it may depend on the version of plantuml that is in the CI build):
Jose Costa Teixeira (Dec 10 2020 at 16:21):
@Michaela Ziegler @John Moehrke
Jose Costa Teixeira (Dec 10 2020 at 16:22):
You can just wrap the include in an html div. If you want, you can try that solution and do some testing for me :)
<div>
{% include usecase1.svg %}
</div>
Michaela Ziegler (Dec 10 2020 at 16:54):
Jose Costa Teixeira said:
You can just wrap the include in an html div. If you want, you can try that solution and do some testing for me :smile:
<div>
{% include usecase1.svg %}
</div>
that works :+1: (not with the template we use of course)
Jean Duteau (Dec 10 2020 at 17:12):
You don't need to wrap it in a <div> if you're using Markdown. This works just fine:
# Establishment Registration UML Diagram
The following UML diagram shows the data elements for an Establishment Registration operation. More details about the data elements can be found in the definition tables below.
Each request has a set of elements that identify the request:
* operation ID
* operation date/time
* request ID
* request version
It then has the information about the Registrant, i.e the organization that is registering the establishments, and then one-to-many sets of Establishment information along with an optional US Agent and Importer (if the Establishment is not located in the US) and a set of Business Operations for the Establishment.
{% include EstablishmentRegistrationLogicalModel.svg %}
Jose Costa Teixeira (Dec 10 2020 at 17:13):
That one didn't work for me
Frank Oemig (Feb 09 2021 at 10:49):
What is necessary to convert the plantuml file in image source to the output directory?
Jose Costa Teixeira (Feb 09 2021 at 11:37):
Plantuml output is not stored as a file - it is currently just a SVG which gets embedded in the html
Lloyd McKenzie (Feb 09 2021 at 14:55):
Why do you want the plantuml in your output?
John Moehrke (Feb 09 2021 at 15:52):
the IG builder will automatically convert some plantuml (must be .plantuml extension) to SVG graphics in the output. Not all forms of plantuml work. You just need to call for the svg in your markdown or html and magic happens. If you fail to do that, then the svg disappears. So (a) make sure you have the right kind of plantuml text file, with .plantuml extension, in the images-source folder; and (b) call for the filename with svg extension in your markdown or html.
John Moehrke (Feb 09 2021 at 15:53):
no error, warning, or info is thrown if the plantuml is not the right kind for it to render, nor a warning if you don't call for the svg and thus it is removed.
Lloyd McKenzie (Feb 09 2021 at 16:25):
Note that the SVG will actually contain the source plantUml as an embedded comment
Frank Oemig (Feb 09 2021 at 18:05):
I want to use the drawing functionality to visualize and explain on some pages.
I have placed the file in image source and referenced the svg in MD. But nothing happens, and I cannot figure out why.
Can there be something wrong with the plantuml dialect? I have used a given simple example.
John Moehrke (Feb 09 2021 at 18:06):
what style of plantuml are you using? Can you provide the link or code here?
John Moehrke (Feb 09 2021 at 18:06):
it only works with sequence diagrams
Frank Oemig (Feb 09 2021 at 18:27):
Ah, ok. Will verify my example. My intend was to use it for class diagrams.
Jean Duteau (Feb 09 2021 at 18:29):
it doesn't work for class diagrams because plantuml needs graphviz for that. i have some class diagrams in my SPL implementation guide but I generate the images before running the publisher and put the generated images in the images folder.
Frank Oemig (Feb 09 2021 at 18:32):
Thx, that is what I have done before as well. My hope was that this miracle helps me here too.
Jean Duteau (Feb 09 2021 at 18:33):
@Josh Mandel @Grahame Grieve @Mark Iantorno Is there a chance of having graphviz added to the build machines so that plantuml class diagrams could be auto-generated by the publisher?
Josh Mandel (Feb 09 2021 at 18:41):
Is it just a question of adding a dependency, or is there code to be written too?
Jean Duteau (Feb 09 2021 at 18:42):
just a dependency
Josh Mandel (Feb 09 2021 at 18:45):
Can you propose an edit to this line if there's an apt package available?
Jean Duteau (Feb 09 2021 at 18:47):
RUN apt-get update && apt-get -y install python3 python3-pip gosu openssl wget graphviz
(there is an apt package available)
pull request created with the change
John Moehrke (Feb 09 2021 at 19:39):
I think we have resisted as this might be easy on the server.. but this now adds yet-another thing that us authors need to add to our machines.
John Moehrke (Feb 09 2021 at 19:39):
I want the feature, but for now I just generate the SVG using plantuml web site, and save it in my images folder.
John Moehrke (Feb 09 2021 at 19:40):
much smaller pain, than installing yet-another tool on everyones desktop
Jean Duteau (Feb 09 2021 at 19:41):
sure, but I already have plantuml and graphviz installed on my machine. if you don't want to do that, you can keep doing what you are doing - generate the images outside of the publisher.
Frank Oemig (Feb 09 2021 at 20:03):
You can add an environment variable to _genonce.bat setting GRAPHVIZ_DOT to dot.exe. Then class diagram generation works.
Thanks for all your help
Jean Duteau (Feb 09 2021 at 20:44):
it will work locally but it won't work on the build platform because graphviz isn't available (at least not yet)
Josh Mandel (Feb 09 2021 at 21:18):
Thanks for the PR; merged and pushing the updated image to our build system.
Josh Mandel (Feb 09 2021 at 21:26):
Done. FYI @Jean Duteau if you want to test this out.
Jean Duteau (Feb 09 2021 at 21:34):
John Moehrke said:
the IG builder will automatically convert some plantuml (must be .plantuml extension) to SVG graphics in the output. Not all forms of plantuml work. You just need to call for the svg in your markdown or html and magic happens. If you fail to do that, then the svg disappears. So (a) make sure you have the right kind of plantuml text file, with .plantuml extension, in the images-source folder; and (b) call for the filename with svg extension in your markdown or html.
hmm, with Josh adding graphviz as a dependency on the build machine, I want to move my files into the build queue. but I must be missing something. Here's what I have which I think matches what John said:
a) four xx.plantuml files in input/images-sources folder
b) four xx-intro.md files in input/intro-notes folder that has a link to the xxx.svg file
But I'm not getting the PlantUML to be called.
John Moehrke (Feb 09 2021 at 22:31):
your markdown needs to pull in the svg
<div>
{%include xx.svg%}
</div>
Jean Duteau (Feb 09 2021 at 22:31):
okay, i'll try that. thx
Jean Duteau (Feb 09 2021 at 22:53):
@Josh Mandel works locally and in the build environment! thanks a lot!
Jose Costa Teixeira (Feb 09 2021 at 23:23):
sorry, I was traveling, I missed this thread and only saw the commit on email
Jose Costa Teixeira (Feb 09 2021 at 23:24):
catching up now: I guess it doesn't harm to have graphviz, but most diagrams can render fine by adding this in the diagram
!pragma graphviz_dot smetana
Jose Costa Teixeira (Feb 09 2021 at 23:24):
https://plantuml.com/smetana02
Jose Costa Teixeira (Feb 09 2021 at 23:27):
graphviz license is Common Public License, I think. @Lloyd McKenzie is that kosher?
Jose Costa Teixeira (Feb 09 2021 at 23:27):
John Moehrke said:
I want the feature, but for now I just generate the SVG using plantuml web site, and save it in my images folder.
Sorry John for not documenting the workaround (use the smetana directive in your diagrams).
Jose Costa Teixeira (Feb 09 2021 at 23:28):
John Moehrke said:
much smaller pain, than installing yet-another tool on everyones desktop
This I agree, so I will try to use the smetana directive whenever possible
Jean Duteau (Feb 09 2021 at 23:51):
i'm not stuck on using graphviz. if this alternate method works for the diagrams that we need and we don't need graphviz, then I'm fine with marking up my files as needed.
Jean Duteau (Feb 09 2021 at 23:51):
i was only offering it for those who wanted to do class files
Lloyd McKenzie (Feb 10 2021 at 00:10):
I'm pretty sure the Eclipse license is fine, but I'm not an expert. @Grahame Grieve ?
Jose Costa Teixeira (Feb 10 2021 at 00:12):
Grahame Grieve (Feb 10 2021 at 00:26):
sure. but something you register with the OS, and hook into Jekyll, anything but full GPL is ok
Jose Costa Teixeira (Feb 10 2021 at 07:05):
Great. I'll add this to the things to document
Jose Costa Teixeira (Feb 10 2021 at 07:06):
This=install graphviz or use the alternative
Last updated: Apr 12 2022 at 19:14 UTC
