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
Hi all,

I am using AsciiDoc (another Eclipse WG now) in my projects where ever possible to document.

There is very good tool support available - for the build pipeline (i.e. using a Maven build task, GitLab etc.) and in IDEs with plugins offering visualization of code changes immediately in a split view.

My best practice for graphs is using PlantUML where possible and generate SVG form it to include it in AcsiiDoc. In corner cases ditaa, direct SVG or PNG is used.
Advantage of PlantUML is maintainability, because the diagram is generated (and self-arranged) - which can be a problem in seldom cases and then using ditaa is an option - there you have to do the arrangement by yourself. If that is still is not an option, then some other editor (or generator, i.e. IDE class diagram export) is used to generate SVG or PNG - the last one is not scalable (bitmap instead of vector graphic) and therefore less preferred...

I can write some developer documentation for the tooling, if necessary.

Writing documentation within your IDE, developers main tool, helps a lot - specially when code examples added in the document and linking to TCKs in case of specs need to be done.
Having a text format for graphs helps to maintain high quality with tool support like diff or search & replace (for the text and it's graphs at the same time).
You also could add some automated testing, when building the documentation. Or even generate AsciiDoc or PlantUML from code and check the last with ArchUnit...

If you ever used it, you will not miss it any more!

Best,
Jan

Am 18.06.21 um 16:49 schrieb Reza Rahman:
+1. I think this is a flexible and sensible way to go.

On Jun 18, 2021, at 4:57 AM, Ondro Mihályi <ondrej.mihalyi@xxxxxxxxx> wrote:


I personally like the ditaa ASCII diagrams, they are easy to read in the source code, they can be embedded unlike PNG/SVG so no need to edit another file and look good enough in the generated PDF. I'm not in favor of PlantUML in this case, to me it's just another variant of SVG (not readable source code), requires people to learn a non-trivial language, install an additional dependency to generate and can't be easily previewed in github etc.

I can imagine that we allow using ditaa ASCII diagrams for simple diagrams and SVG for more complex ones. If an ASCII diagram becomes more complex, then we can easily replace it with an SVG if it gets too complex.

Ondro

st 16. 6. 2021 o 20:38 Kevin Sutter <sutter@xxxxxxxxxx> napísal(a):
I beg to differ, Markus.  Once you go beyond a very simple image, I don't see how you can create and maintain these asciidoc images without some tooling.

For example, the more complicated image in Nathan's example is really difficult (or impossible) to visualize without running through the rendering process.  I mean can someone really visualize what this puml syntax would render?

<noname>


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:

<noname>

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:
<noname>

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

 _______________________________________________
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