Good points Kevin, and thanks Ondro for inlining that stuff since I didn't realize my attachments would not come through (learning something new every day).
I think all of the diagram DSLs supported by the asciidoc diagram plugin eventually use Graphviz, so I guess it's just a cost of using it. I've mitigated it with the NetBeans plugin that can show a preview image of the .puml files, or by pasting them into the PlantUML website to render them.
Whether this is the path chosen or not, thanks for the opportunity to present it!
- Nathan Erwin
POJD - Plain Old Java Developer
Thanks for the examples!
I ran into the issue that Ondro pointed out that additional utilities
would need to be installed in order to render some of the images. In
my opinion, that is a drawback.
Another drawback
is that some (all?) of the images are not renderable unless you build the
spec. At least with either png or svg, you can view the images in
git as you are browsing the directory. Except for the very simple
diagrams that are inlined with asciidoc, these puml files do not seem to
easily render.
Personally, I'm
failing to see the advantages of moving to these asciidoc/puml images.
But, I'm still willing to be educated...
---------------------------------------------------
Kevin Sutter
STSM, Jakarta EE and MicroProfile architect @ IBM
e-mail: sutter@xxxxxxxxxx Twitter: @kwsutter
phone: tl-553-3620 (office), 507-253-3620 (office)
LinkedIn: https://www.linkedin.com/in/kevinwsutter
Part-time schedule: Tue, Wed, Thu (off on Mon and Fri)
From:
"Ondro
Mihályi" <ondrej.mihalyi@xxxxxxxxx>
To:
jakartaee-platform
developer discussions <jakartaee-platform-dev@xxxxxxxxxxx>
Date:
06/16/2021
07:00
Subject:
[EXTERNAL]
Re: [jakartaee-platform-dev] Image formats in the specification
Sent
by: "jakartaee-platform-dev"
<jakartaee-platform-dev-bounces@xxxxxxxxxxx>
Hi Markus,
I just add an example here in text.
For example, the following asciidoc uses
ditaasyntax:
[ditaa, Platform_Spec-3.svg, svg]
....
Web Client
Web Server
+--------+
+--------+
| | Request access to |
|
| | -----------------> |
|
| | protected resource |
|
+--------+
+--------+
and will generate the following SVG picture
out of the box:
It can also generate a PNG but on my
computer it's lower quality than SVG. And the text in SVG is searchable
in the document.
Generating PlantUML diagrams requires
Graphviz installed on the OS and dot command available, otherwise Asciidoc
will generate a blank image. But PlantUML allows a lot more flexibility
than ditaa. For example, the following diagram:
is generated from
| skinparam
monochrome true |
|
| rectangle
wc as "Web Client" |
|
| rectangle
ws as "Web Server" { |
|
| rectangle
cred as "Credential" |
|
| rectangle
jsp as "JSP/Servlet\nObject" { |
|
| rectangle
foo as "Authentication" |
|
| wc
-->> cred : Request access to\nprotected resource |
|
@enduml
st 16. 6. 2021 o 7:56 Markus Karg
<markus@xxxxxxxxxxxxxxx>
napísal(a):
Can
you post the asciidoc for this, so we can better understand the benefits
of this format (which is not just diffability, but also the fact that it
is comprehensible as it does not just describe geometric shapes but actually
the kind of diagram).
-Markus
Von: jakartaee-platform-dev
[mailto:jakartaee-platform-dev-bounces@xxxxxxxxxxx]
Im Auftrag von Nathan Erwin
Gesendet: Mittwoch, 16. Juni 2021 01:36
An: jakartaee-platform developer discussions
Betreff: Re: [jakartaee-platform-dev] Image formats in the specification
Kevin,
I created a quick demo of using the Asciidoctor
Diagram plugin (https://docs.asciidoctor.org/diagram-extension/latest/)
to generate png and svg images in the Security section of the spec on this
forked branch: https://github.com/nderwin-forks/jakartaee-platform/tree/spike/images-with-asciidoc.
See the Initial Request (Platform_Spec-3.png) and Initial Authentication
(Platform_Spec-4.png) sections.
I used ditaa and PlantUML to show examples
of embedding the diagram description either inline, or as an external file,
and for generating each type of image. Note that it'll be difficult
in some cases to make new images match the old ones exactly as drawing
the diagram is done from a textual description of suggested actions.
The upside is that the source of the images is diffable text.
- Nathan Erwin
POJD - Plain Old Java Developer
On Tue, Jun 15, 2021 at 3:35 PM Kevin
Sutter <sutter@xxxxxxxxxx>
wrote:
Is there anyone with
AsciiDoc experience that could demonstrate how to create and maintain an
image with AsciiDoc? If someone could take one of our existing images
in the Platform Spec and convert it to AsciiDoc, that would be a great
example. Otherwise, I would lean towards going forward with the SVG
conversions since we already have a PR with those updates done. And,
we know of open-source SVG editors that make maintenance doable.
Other thoughts or suggestions?
---------------------------------------------------
Kevin Sutter
STSM, Jakarta EE and MicroProfile architect @ IBM
e-mail: sutter@xxxxxxxxxx Twitter: @kwsutter
phone: tl-553-3620 (office), 507-253-3620 (office)
LinkedIn: https://www.linkedin.com/in/kevinwsutter
Part-time schedule: Tue, Wed, Thu (off on Mon and Fri)
From: "Kevin
Sutter" <sutter@xxxxxxxxxx>
To: jakartaee-platform
developer discussions <jakartaee-platform-dev@xxxxxxxxxxx>
Date: 06/03/2021
09:40
Subject: [EXTERNAL]
Re: [jakartaee-platform-dev] Image formats in the specification
Sent by: "jakartaee-platform-dev"
<jakartaee-platform-dev-bounces@xxxxxxxxxxx>
Hi,
I agree with Markus that SVG is nice, but each editor throws wrinkles into
the generated SVG. When we did the first couple images that needed
modification (https://github.com/eclipse-ee4j/jakartaee-platform/pull/217),
I verified that the resulting images could be modified via Inkscape (https://inkscape.org/).
This seems like a nice open-source, semi-easy-to-use vector graphics editor.
I didn't realize that AsciiDoctor had a solution for images. If someone
wants to compare or demonstrate this solution as compared to SVG (using
one of the existing diagrams in the Platform spec), I'd be very interested
in learning more.
---------------------------------------------------
Kevin Sutter
STSM, Jakarta EE and MicroProfile architect @ IBM
e-mail: sutter@xxxxxxxxxx Twitter: @kwsutter
phone: tl-553-3620 (office), 507-253-3620 (office)
LinkedIn: https://www.linkedin.com/in/kevinwsutter
Part-time schedule: Tue, Wed, Thu (off on Mon and Fri)
From: Dmitri
Cerkas via jakartaee-platform-dev <jakartaee-platform-dev@xxxxxxxxxxx>
To: 'jakartaee-platform
developer discussions' <jakartaee-platform-dev@xxxxxxxxxxx>
Cc: Dmitri
Cerkas <dmitricerkas@xxxxxxxxx>
Date: 06/03/2021
02:42
Subject: [EXTERNAL]
Re: [jakartaee-platform-dev] Image formats in the specification
Sent by: "jakartaee-platform-dev"
<jakartaee-platform-dev-bounces@xxxxxxxxxxx>
Ok. When the final decision is made let me know that this is how I begin
the image conversion to the new format also for other specifications of
Jakarta EE.
Dmitri.
On Thursday, June 3, 2021, 09:00:12 AM GMT+2, Markus Karg <markus@xxxxxxxxxxxxxxx>
wrote:
Clearly moving away from binary image formats is a huge benefit as it allows
to diff them, which is very nice.
But as least people write SVGs manually, the diff is not very self-explanatory:
Drawing software often completely rewrites the SVG or adds clutter.
So I see a source-based image format the most useful.
While I do not know Asciidoctor very well, I think it is exactly what we
should strive for.
If Jakarta EE spec moves to Asciidoctor and this works well, I could imagine
that most Jakarta specs would follow.
-Markus
Von:jakartaee-platform-dev [mailto:jakartaee-platform-dev-bounces@xxxxxxxxxxx]
Im Auftrag von Ivar Grimstad
Gesendet: Donnerstag, 3. Juni 2021 08:14
An: jakartaee-platform-dev@xxxxxxxxxxx
Betreff: [jakartaee-platform-dev] Image formats in the specification
Hi,
I can't remember if we reached any conclusion for how to handle the images,
diagrams, and illustrations in the specification document.
Currently, there is a pull request for replacing the PNGs with SVGs [1]
that needs some feedback.
Does this conversion step help now? Or should we move directly to a text-based
format to generate the diagrams from the Asciidoc to make editing easier?
Something like AsciiDoctor Diagram [2]?
Ivar
[1] https://github.com/eclipse-ee4j/jakartaee-platform/pull/365
[2] https://asciidoctor.org/docs/asciidoctor-diagram/
-- Ivar
Grimstad
Jakarta
EE Developer Advocate | Eclipse
Foundation Eclipse
Foundation-
Community. Code. Collaboration.
_______________________________________________
jakartaee-platform-dev mailing list
jakartaee-platform-dev@xxxxxxxxxxx
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/jakartaee-platform-dev_______________________________________________
jakartaee-platform-dev mailing list
jakartaee-platform-dev@xxxxxxxxxxx
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/jakartaee-platform-dev
_______________________________________________
jakartaee-platform-dev mailing list
jakartaee-platform-dev@xxxxxxxxxxx
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/jakartaee-platform-dev
_______________________________________________
jakartaee-platform-dev mailing list
jakartaee-platform-dev@xxxxxxxxxxx
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/jakartaee-platform-dev_______________________________________________
jakartaee-platform-dev mailing list
jakartaee-platform-dev@xxxxxxxxxxx
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/jakartaee-platform-dev_______________________________________________
jakartaee-platform-dev mailing list
jakartaee-platform-dev@xxxxxxxxxxx
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/jakartaee-platform-dev
_______________________________________________
jakartaee-platform-dev mailing list
jakartaee-platform-dev@xxxxxxxxxxx
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/jakartaee-platform-dev
