Skip to main content
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [jakartaee-platform-dev] Image formats in the specification

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

Back to the top