DIagrams and PlantUML

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

DIagrams and PlantUML

Shane McCarron
Okay Spec hive-mind, I have a quandary.  The Web Payments (IG, WG) and the Credentials Community Group, and the Verifiable Claims Task Force, and possibly others, are using PlantUML to draw clever little flow diagrams etc.  PlantUML is a simple textual UML grammar.  The plantuml engine is open source, and relies upon GraphViz (also open source) to generate various formats, including SVG.

All that's great.  But the people using this don't *want* to have to generate an SVG version of their diagrams.  They just want to include the PlantUML source and have magic occur.  That is *possible* in ReSpec using @data-transform and a function, but the way it is possible is by relying upon a plantuml proxy server at www.plantuml.com.  I am personally wary of this because 1) we have no control over it, and 2) it just feels rude to start hitting their server all the time.

So, here are the options as I see them:
  1. Put an instance of a plantuml server up at the W3C somewhere and hit that for dynamic diagram generation.
  2. Use the plantuml.com server and just (fingers crossed) hope it keeps working.
  3. Add something into the github flow so that when certain filetypes are pushed (*.pml) updated versions of their static versions are automatically generated and put into the repo (*.svg).  That generation could happen using plantuml.com or a w3c server or something else.
  4. Tell people to generate static versions by hand and commit them into the repo.
What do others think?  Is there a more sensible way to approach this problem?

P.S.  If you want to see an example of what is being done, check out the use case document we are working on at [1] or the web payments flows work as described in its wiki at [2].  Or, of course, just look at the plantuml site at [3]



--
Shane McCarron
Managing Director, Applied Testing and Technology, Inc.
Reply | Threaded
Open this post in threaded view
|

Re: DIagrams and PlantUML

Marcos Caceres-4


On January 28, 2016 at 3:37:26 PM, Shane McCarron ([hidden email]) wrote:
> So, here are the options as I see them:
> 4. Tell people to generate static versions by hand and commit them into
> the repo.

This. Relying on a third party to do the conversion as a service from some proprietary format seems tremendously wasteful, insecure, etc. (all the things you mentioned).  

> What do others think? Is there a more sensible way to approach this
> problem?

It's extremely rare that once a diagram is done, it will be updated very often... maybe one updates a diagram 10-20 times max during the whole life of a standards project (~5 years). So I would personally throw this into the "would be nice... someday after we finish the actual spec" pile. 



Reply | Threaded
Open this post in threaded view
|

Re: DIagrams and PlantUML

Shane McCarron

On Jan 27, 2016 10:53 PM, "Marcos Caceres" <[hidden email]> wrote:


On January 28, 2016 at 3:37:26 PM, Shane McCarron ([hidden email]) wrote:
> So, here are the options as I see them:
> 4. Tell people to generate static versions by hand and commit them into
> the repo.

This. Relying on a third party to do the conversion as a service from some proprietary format seems tremendously wasteful, insecure, etc. (all the things you mentioned).  

> What do others think? Is there a more sensible way to approach this
> problem?

It's extremely rare that once a diagram is done, it will be updated very often... maybe one updates a diagram 10-20 times max during the whole life of a standards project (~5 years). So I would personally throw this into the "would be nice... someday after we finish the actual spec" pile. 


Yeah...  I am inclined to not put too much effort into automating it.  I do have a node.js script that can generate an svg from source (via the proxy service) that I suppose I could put in the repo so other editors can use it or something.  Just as a tool to ease the generation of the "static" diagrams.  

Any other opinions out there? 
Reply | Threaded
Open this post in threaded view
|

Re: DIagrams and PlantUML

Michael Cooper-2
In reply to this post by Shane McCarron
Whatever the approach to generating diagrams, it will be important to have at least an alt text, plus a long description unless the meaning conveyed by the diagram is fully conveyed by the surrounding text. Unless the diagram generator tool does a good job of that (which isn't usually the case although is in principle possible) there would be a need to manually enhance those aspects of the inserted image anyways, in order to meet the Pubrules requirement that TR documents conform to WCAG 2.0 level AA. That might impact the feasibility of fully automating the process.

Michael

On 27/01/2016 11:35 PM, Shane McCarron wrote:
Okay Spec hive-mind, I have a quandary.  The Web Payments (IG, WG) and the Credentials Community Group, and the Verifiable Claims Task Force, and possibly others, are using PlantUML to draw clever little flow diagrams etc.  PlantUML is a simple textual UML grammar.  The plantuml engine is open source, and relies upon GraphViz (also open source) to generate various formats, including SVG.

All that's great.  But the people using this don't *want* to have to generate an SVG version of their diagrams.  They just want to include the PlantUML source and have magic occur.  That is *possible* in ReSpec using @data-transform and a function, but the way it is possible is by relying upon a plantuml proxy server at www.plantuml.com.  I am personally wary of this because 1) we have no control over it, and 2) it just feels rude to start hitting their server all the time.

So, here are the options as I see them:
  1. Put an instance of a plantuml server up at the W3C somewhere and hit that for dynamic diagram generation.
  2. Use the plantuml.com server and just (fingers crossed) hope it keeps working.
  3. Add something into the github flow so that when certain filetypes are pushed (*.pml) updated versions of their static versions are automatically generated and put into the repo (*.svg).  That generation could happen using plantuml.com or a w3c server or something else.
  4. Tell people to generate static versions by hand and commit them into the repo.
What do others think?  Is there a more sensible way to approach this problem?

P.S.  If you want to see an example of what is being done, check out the use case document we are working on at [1] or the web payments flows work as described in its wiki at [2].  Or, of course, just look at the plantuml site at [3]



--
Shane McCarron
Managing Director, Applied Testing and Technology, Inc.

Reply | Threaded
Open this post in threaded view
|

Re: DIagrams and PlantUML

Shane McCarron
Yeah, we are aware of those requirements.  They exist whether or not we do something clever to generate the SVG / PNG version of a diagram.  One of the things we want to look at is if the SVG generated by GraphViz / PlantUML is able to be enhanced to improve its accessibility as the SVG A11Y work firms up.  Rich?

On Fri, Jan 29, 2016 at 9:31 AM, Michael Cooper <[hidden email]> wrote:
Whatever the approach to generating diagrams, it will be important to have at least an alt text, plus a long description unless the meaning conveyed by the diagram is fully conveyed by the surrounding text. Unless the diagram generator tool does a good job of that (which isn't usually the case although is in principle possible) there would be a need to manually enhance those aspects of the inserted image anyways, in order to meet the Pubrules requirement that TR documents conform to WCAG 2.0 level AA. That might impact the feasibility of fully automating the process.

Michael

On 27/01/2016 11:35 PM, Shane McCarron wrote:
Okay Spec hive-mind, I have a quandary.  The Web Payments (IG, WG) and the Credentials Community Group, and the Verifiable Claims Task Force, and possibly others, are using PlantUML to draw clever little flow diagrams etc.  PlantUML is a simple textual UML grammar.  The plantuml engine is open source, and relies upon GraphViz (also open source) to generate various formats, including SVG.

All that's great.  But the people using this don't *want* to have to generate an SVG version of their diagrams.  They just want to include the PlantUML source and have magic occur.  That is *possible* in ReSpec using @data-transform and a function, but the way it is possible is by relying upon a plantuml proxy server at www.plantuml.com.  I am personally wary of this because 1) we have no control over it, and 2) it just feels rude to start hitting their server all the time.

So, here are the options as I see them:
  1. Put an instance of a plantuml server up at the W3C somewhere and hit that for dynamic diagram generation.
  2. Use the plantuml.com server and just (fingers crossed) hope it keeps working.
  3. Add something into the github flow so that when certain filetypes are pushed (*.pml) updated versions of their static versions are automatically generated and put into the repo (*.svg).  That generation could happen using plantuml.com or a w3c server or something else.
  4. Tell people to generate static versions by hand and commit them into the repo.
What do others think?  Is there a more sensible way to approach this problem?

P.S.  If you want to see an example of what is being done, check out the use case document we are working on at [1] or the web payments flows work as described in its wiki at [2].  Or, of course, just look at the plantuml site at [3]



--
Shane McCarron
Managing Director, Applied Testing and Technology, Inc.




--
Shane McCarron
Managing Director, Applied Testing and Technology, Inc.
Reply | Threaded
Open this post in threaded view
|

Re: DIagrams and PlantUML

Tab Atkins Jr.
In reply to this post by Shane McCarron
On Wed, Jan 27, 2016 at 8:35 PM, Shane McCarron <[hidden email]> wrote:

> Okay Spec hive-mind, I have a quandary.  The Web Payments (IG, WG) and the
> Credentials Community Group, and the Verifiable Claims Task Force, and
> possibly others, are using PlantUML to draw clever little flow diagrams etc.
> PlantUML is a simple textual UML grammar.  The plantuml engine is open
> source, and relies upon GraphViz (also open source) to generate various
> formats, including SVG.
>
> All that's great.  But the people using this don't *want* to have to
> generate an SVG version of their diagrams.  They just want to include the
> PlantUML source and have magic occur.  That is *possible* in ReSpec using
> @data-transform and a function, but the way it is possible is by relying
> upon a plantuml proxy server at www.plantuml.com.  I am personally wary of
> this because 1) we have no control over it, and 2) it just feels rude to
> start hitting their server all the time.
>
> So, here are the options as I see them:
>
> 1. Put an instance of a plantuml server up at the W3C somewhere and hit that
> for dynamic diagram generation.
> 2. Use the plantuml.com server and just (fingers crossed) hope it keeps
> working.
> 3. Add something into the github flow so that when certain filetypes are pushed
> (*.pml) updated versions of their static versions are automatically
> generated and put into the repo (*.svg).  That generation could happen using
> plantuml.com or a w3c server or something else.
> 4. Tell people to generate static versions by hand and commit them into the
> repo.
>
> What do others think?  Is there a more sensible way to approach this
> problem?
>
> P.S.  If you want to see an example of what is being done, check out the use
> case document we are working on at [1] or the web payments flows work as
> described in its wiki at [2].  Or, of course, just look at the plantuml site
> at [3]
>
> [1]
> http://www.opencreds.org/specs/source/use-cases/#how-a-verifiable-claim-might-be-used
> [2] https://github.com/w3c/webpayments/wiki/Flows
> [3] http://www.plantuml.com

Bikeshed similarly generates railroad diagrams for people from simple
textual instructions.  It just has the generator integrated into its
codebase (I maintain both a JS port (the original) and a Python port
(for Bikeshed) of the generator, for this purpose).

#1 is wrong - don't put more things on a dynamic
every-single-time-a-user-views-the-spec codepath.  Common usage of
ReSpec (using it live, rather than saving static snapshots) is already
bad enough on this front.

#2 is *definitely* wrong, as Marcos says.

#3 seems like a fine idea, but as Marcos says, is low-priority, given
that #4 isn't hard either.

#4 is good for now. ^_^

~TJ

Reply | Threaded
Open this post in threaded view
|

Re: DIagrams and PlantUML

Shane McCarron
I think that I like #4 too.  Definitely NOT #1 ;-)

On Tue, Feb 9, 2016 at 2:48 PM, Tab Atkins Jr. <[hidden email]> wrote:
On Wed, Jan 27, 2016 at 8:35 PM, Shane McCarron <[hidden email]> wrote:
> Okay Spec hive-mind, I have a quandary.  The Web Payments (IG, WG) and the
> Credentials Community Group, and the Verifiable Claims Task Force, and
> possibly others, are using PlantUML to draw clever little flow diagrams etc.
> PlantUML is a simple textual UML grammar.  The plantuml engine is open
> source, and relies upon GraphViz (also open source) to generate various
> formats, including SVG.
>
> All that's great.  But the people using this don't *want* to have to
> generate an SVG version of their diagrams.  They just want to include the
> PlantUML source and have magic occur.  That is *possible* in ReSpec using
> @data-transform and a function, but the way it is possible is by relying
> upon a plantuml proxy server at www.plantuml.com.  I am personally wary of
> this because 1) we have no control over it, and 2) it just feels rude to
> start hitting their server all the time.
>
> So, here are the options as I see them:
>
> 1. Put an instance of a plantuml server up at the W3C somewhere and hit that
> for dynamic diagram generation.
> 2. Use the plantuml.com server and just (fingers crossed) hope it keeps
> working.
> 3. Add something into the github flow so that when certain filetypes are pushed
> (*.pml) updated versions of their static versions are automatically
> generated and put into the repo (*.svg).  That generation could happen using
> plantuml.com or a w3c server or something else.
> 4. Tell people to generate static versions by hand and commit them into the
> repo.
>
> What do others think?  Is there a more sensible way to approach this
> problem?
>
> P.S.  If you want to see an example of what is being done, check out the use
> case document we are working on at [1] or the web payments flows work as
> described in its wiki at [2].  Or, of course, just look at the plantuml site
> at [3]
>
> [1]
> http://www.opencreds.org/specs/source/use-cases/#how-a-verifiable-claim-might-be-used
> [2] https://github.com/w3c/webpayments/wiki/Flows
> [3] http://www.plantuml.com

Bikeshed similarly generates railroad diagrams for people from simple
textual instructions.  It just has the generator integrated into its
codebase (I maintain both a JS port (the original) and a Python port
(for Bikeshed) of the generator, for this purpose).

#1 is wrong - don't put more things on a dynamic
every-single-time-a-user-views-the-spec codepath.  Common usage of
ReSpec (using it live, rather than saving static snapshots) is already
bad enough on this front.

#2 is *definitely* wrong, as Marcos says.

#3 seems like a fine idea, but as Marcos says, is low-priority, given
that #4 isn't hard either.

#4 is good for now. ^_^

~TJ



--
Shane McCarron
Managing Director, Applied Testing and Technology, Inc.