Re: [jakartaee-platform-dev] Image formats in the specification

["Kevin Sutter" <sutter@xxxxxxxxxx>]

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

@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/

--

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