Call ditaa with command line arguments

[saschazelzer]

Hi,

is it possible to specify command line arguments or something equivalent in the asciidoc file when running ditaa? I would like to control effects like box shadows and box separations which is possible via ditaa command line arguments --no-separation and --no-shadows.

Thanks.

[pepijnve]

No that's not yet possible, but shouldn't be too hard to add. I propose adding support for passing ditaa command line arguments as block attributes. For instance:

[ditaa,no-shadows, round-corners]
...

[pepijnve]

Resolved by 887a577
I ended up adding support for an options attribute that takes the ditaa command line arguments as value. You can write, for instance,

[ditaa, options="--no-shadows --scale 2.5 --round-corner"]

[saschazelzer]

Awesome, thanks!

However, the image caching mechanism seems to be too aggressive now. Changing the options without changing the ascii image does not regenerate it. Is there some work-around?

[pepijnve]

Thanks for catching that one. The options are indeed not taken into account for the cache validation. Oversight on my part. I'll try to fix that this evening.

[pepijnve]

5149ac6 makes the ditaa processor take the options attribute into account when deciding if the image needs to be regenerated or not.

[mojavelinux]

I'm definitely in support of this approach, but I wonder if we should also have the option of making these customizations globally using document attributes. wdyt? Something like:

:ditaa-options: no-shadows,round-corners

or even

:ditaa-option-no-shadows:
:ditaa-option-round-corners:

[pepijnve]

Sounds like a good idea. My first implementation actually had the options in the form you're using above; without the double-dashes. That looked more asciidoc-like in my eyes than raw command line arguments. I backed away from that approach thinking that it might be easier for users (and less documentation work) if you could just use the command line arguments of the tool in question as is.
That idea doesn't work 100% though since only a subset of the options are supported so I probably still have to document this anyway.

If we go ahead with the above syntax then the same syntax should be supported on the blocks themselves imo.
So you could either do

:ditaa-options: no-shadows, round-corners, scale=2.5

globally or

[ditaa, options="no-shadows,round-corners,scale=2.5"]

at the block level.

@saschazelzer any preference from your side? Make it look asciidoc-ish or stick with the raw command line options?

[mojavelinux]

I like what you've suggested, esp the document level attribute.

[saschazelzer]

I would definitely use document attributes if they were available. As a consequence, the syntax should be the same at the block level, as you already said. Your example above looks good to me. I am not an expert asciidoc user (yet) though.

[pepijnve]

Reopening for syntax change and document attribute support

[pepijnve]

I ended up implementing the following:

• The Ditaa extension supports the options scale, antialias, separation, round-corners, shadows and debug
• Options can be specified per block as <option>=<value> or globally as a document attribute of the form :ditaa-option-<option>: <value>
• Block level options override global options
• Default values are Ditaa's defaults

The semantics of the options are

• scale: scale factor specified as a decimal number (e.g. scale=1.5)
• antialias: true to enable antialiasing; false to disable it
• separation: true to leave spacing between adjacent blocks; false to remove it
• round-corners: true to force round corners everywhere; false to use corner style from diagram
• shadows: true to enable drop shadows; false to disable them
• debug: true to display a debug grid in the diagram; false to remove it

[mojavelinux]

Huge 👍 !

[saschazelzer]

This is great, thanks!