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
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
_______________________________________________
jakartaee-platform-dev mailing list
jakartaee-platform-dev@xxxxxxxxxxx
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/jakartaee-platform-dev