Re: DIagrams and PlantUML

On Wed, Jan 27, 2016 at 8:35 PM, Shane McCarron <shane@aptest.com> 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

Received on Tuesday, 9 February 2016 20:49:49 UTC