Re: DIagrams and PlantUML

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

On Tue, Feb 9, 2016 at 2:48 PM, Tab Atkins Jr. <jackalmage@gmail.com> wrote:

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



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