| Re: [jakartaee-platform-dev] Image formats in the specification |
I will concede that if you know what this image looks like, then updating
the labels within the diagram is much, much easier.
Also, as far as external tools are concerned... What I was referring
to was the generation of the Specification document (pdf and/or html).
It seems that I would need to install another utility of some sort
on my Mac in order to build the Specification document if we go this Asciidoc/puml
route. Maybe this can easily be done via our pom dependencies? If
so, then that would help a great deal. Currently, I just get some
ugly callstacks when I attempt to build the docs and I'm not sure what
has to be done to correct them.
Creating and/or maintaining SVG files does also require some type of external
tool. But, once the resulting files are put into the git repository,
no additional tools are required to build the document. That's what
I was attempting to say about requiring or not requiring additional tools.
Thanks for the discussion!
---------------------------------------------------
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: "Markus
Karg" <markus@xxxxxxxxxxxxxxx>
To: "'jakartaee-platform
developer discussions'" <jakartaee-platform-dev@xxxxxxxxxxx>
Date: 06/16/2021
11:44
Subject: [EXTERNAL]
Re: [jakartaee-platform-dev] Image formats in the specification
Sent by: "jakartaee-platform-dev"
<jakartaee-platform-dev-bounces@xxxxxxxxxxx>
Looking at the example Ondro posted below, I need to say that I can clearly read the asciidoc variant in source code, but I think I wouldhave problems to understand the source code of the SVG. Speaking of tools: With SVG you definitively force the usage of tools to create them, while asciidoc variant is created by vi.
-Markus
Von:jakartaee-platform-dev
[mailto:jakartaee-platform-dev-bounces@xxxxxxxxxxx]
Im Auftrag von Kevin Sutter
Gesendet: Mittwoch, 16. Juni 2021 14:56
An: jakartaee-platform developer discussions
Betreff: Re: [jakartaee-platform-dev] Image formats in the specification
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:
| @startuml |
| left to right direction |
| skinparam monochrome true |
| skinparam linetype ortho |
| rectangle wc as "Web Client" |
| rectangle ws as "Web Server" { |
| rectangle cred as "Credential" |
| rectangle jsp as "JSP/Servlet\nObject" { |
| rectangle foo as "Authentication" |
| } |
| label "Session\nContext" |
| ' force jsp to the right |
| cred -[hidden]- jsp |
| } |
| 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/
--
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
_______________________________________________
jakartaee-platform-dev mailing list
jakartaee-platform-dev@xxxxxxxxxxx
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/jakartaee-platform-dev