Re: DIagrams and PlantUML

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 <http://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 <http://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 <http://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
>
>
> -- 
> Shane McCarron
> Managing Director, Applied Testing and Technology, Inc.