last diagram of each type populating across document

[elisa-riscv]

I am working on a fully featured pdf document that has numerous Wavedrom and Graphviz diagrams. We are making use of customization in addition to asciidoctor-mathematical, asciidoctor-bibtex, and of course asciidoctor-diagram. My problem is that for both Wavedrom and Graphiviz diagrams, the last diagram in the text is populated backwards to with the result that the same graphical output appears for all spots where Wavedrom diagrams should appear, and likewise the same graphical output appears for all spot where Graphviz diagrams should appear. Following is a screen shot that shows what should be completely different diagrams. The second diagram in this screen shot is from an svg that I generated before the build for comparison:

[pepijnve]

I'll need some more information to go on than what you've provided so far. It sounds like the targets of your diagrams are all the same causing the files to get overwritten. I might be able to tell you more if you provide some snippets of your asciidoc source document.

[elisa-riscv]

I've been editing this response as I test options.

I tried setting explicit targets and forgot to put in a comma after indicating svg, with the result that the build generated a series of pngs. I appears that the build is a bit allergic to svgs. Working on figuring out the exact syntax required.

I've tried several options and have concluded that setting the output to svg causes the targets to be overwritten, however, if I allow the default png then the graphical output is generated into the images directory that I set in the book header. I think that for now we can make use of pngs. Please let me know if you want more information. It would be nice to be able to have svg output.

Thanks for your quick response!

[pepijnve]

Have a look at https://docs.asciidoctor.org/diagram-extension/latest/#creating-a-diagram

The block attributes are always key-value pairs. When the key is omitted, it is derived implicitly from the index of the attribute. For block macros

[diagram-type, generated-file-name, generated-image-format]

is equivalent to

[diagram-type, target=generated-file-name, format=generated-image-format]

If you do not care about the name of the generated diagram file, the simplest is to write

[wavedrom, format=svg]

Alternatively if you want SVG for all your wavedrom diagrams you can set this at the document level as well like this

:wavedrom-format: svg

[wavedrom]

The syntax you're probably trying

[wavedrom,,svg]

should work as well, but there was a parsing bug in asciidoctor at one point that you might be hitting. See https://github.com/asciidoctor/asciidoctor-diagram/issues/305 and https://github.com/asciidoctor/asciidoctor/issues/3813 for the details.

[elisa-riscv]

Thanks for the clarification.

In my opinion, the current documentation at https://docs.asciidoctor.org/diagram-extension/latest/#creating-a-diagram could use some improvement. I suggest that the macro syntax be introduced with .... [diagram-type, target=file-name, format=image-format] ....

After that, the point that it's possible to omit the key names because the parser automatically assigns (it does not derive--the word derive gives an incorrect connotation here) those keynames based on order of appearance in the macro, is easier to understand.

I am not a fan of the use of the phrases, "generated-file-name" and "generated-image-format" because adding the file name and the format precedes the generation and therefore using the past tense creates a subtle dissonance for the literal-minded.

I am certain that I hit the bug, because the diagrams were working properly without filenames for a while.

Thanks for your timely responses.

[mojavelinux]

Would you be willing to submit a pull request that includes your suggested changes to the documentation?

[pepijnve]

In my opinion, the current documentation at https://docs.asciidoctor.org/diagram-extension/latest/#creating-a-diagram could use some improvement. I suggest that the macro syntax be introduced with .... [diagram-type, target=file-name, format=image-format] ....

I was thinking the exact same thing yesterday. It would be better to introduce the full, explicit syntax first rather than start with the compact form.

After that, the point that it's possible to omit the key names because the parser automatically assigns (it does not derive--the word derive gives an incorrect connotation here) those keynames based on order of appearance in the macro, is easier to understand.

I'm not a native English speaker, nor a professional writer, so no surprises that there are subtley incorrect connotations. Why is 'derive' in the meaning of 'infer' or 'deduce' wrong in this context though? I'm not sure what the incorrect connotation is here.

I am not a fan of the use of the phrases, "generated-file-name" and "generated-image-format" because adding the file name and the format precedes the generation and therefore using the past tense creates a subtle dissonance for the literal-minded.

Any suggestions for replacements? 'name of file that will be generated' is a bit verbose. 'target-file-name'?

[mojavelinux]

Any suggestions for replacements? 'name of file that will be generated' is a bit verbose. 'target-file-name'?

I think output-file-name would work here. Just like with the converter itself, we are assuming that the software is going to create something for us from the input given. It's the same concept here. The "output" is well defined in conversion (particularly within this ecosystem) as meaning the thing that the software creates.

"target" could be confusing since that is used in AsciiDoc to indicate the subject of a reference. So the user might think that it needs to exist already.

[mojavelinux]

Another possible alternative to "output" is "destination", but it's my second choice.

[pepijnve]

The name of the attribute is, perhaps a bit unfortunately in retrospect, target though. [diagram-type, target=output-file-name]. Should we consider renaming that? I can keep support for target in place for backwards compatibility of course.

[elisa-riscv]

How about [diagram-type, output=output-file-name, format=image-format] ?

[pepijnve]

I updated the text a bit for the 2.2.0 release. There's still a lot of room for improvement on the documentation front. Any help here is much appreciated.

[elisa-riscv]

I do intend to suggest some edits in a pull request and apologize for the delays. I have had some real emergencies come up. I need to meet a deadline this week and plan to free up some time soon.

On Mon, Aug 30, 2021 at 2:08 PM Pepijn Van Eeckhoudt < @.***> wrote:

I updated the text a bit for the 2.2.0 release. There's still a lot of room for improvement on the documentation front. Any help here is much appreciated.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/asciidoctor/asciidoctor-diagram/issues/365#issuecomment-908697828, or unsubscribe https://github.com/notifications/unsubscribe-auth/ASTDNUTFAXAHINIT323XOG3T7PXOFANCNFSM5CBQGQTQ . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

[pepijnve]

Closing this issue for now. Still happy to accept any documentation improvement PRs when/if they are submitted.