Can't use asciidoctor -o option in nonlocal directory with ditaa diagram and :data-uri:

[oddhack]

(This may be related to #110)

Asciidoctor 1.5.8, asciidoctor-diagram 1.5.10

If the :data-uri: attribute is set, a ditaa diagram is included (see attachment), and the asciidoctor invocation includes -o someotherpath/file.html, I see the following error:

asciidoctor -b html5 -r asciidoctor-diagram -o out/index.html test.adoc
asciidoctor: WARNING: image to embed not found or not readable: <current directory>/diagram.png

and indeed, there is no 'diagram.png' in the invocation directory. There is one in the 'out/' directory left over after execution, but it's not imbedded in the generated HTML in out/index.html, which contains just

<img src="data:image/png;base64," alt="diagram" width="130" height="98">

Remove the :data-uri: attribute and the warning goes away - but then it's not a single-file HTML document as desired.

Don't use the -o option, or use a -o option without an output directory, and the warning goes away, and the HTML contains the imbedded image. But then I can't put my output where I want to (without additional commands following asciidoctor):

asciidoctor -b html5 -r asciidoctor-diagram -o index.html test.adoc

How can I target asciidoctor output to a different directory, and still have my ditaa diagram inlined in the generated document? I've tried setting the outdir/imagesdir options in various combinations but without success.

[oddhack]

Arggh, cannot attach a .adoc. Trying as a .txt:
test.txt

[mojavelinux]

Asciidoctor Diagram tries to infer the output location for images based on the imagesdir attribute and -o option. If you want to be explicit, just set the imagesoutdir attribute explicitly.

Since you are embedding the images, then both imagesdir and imagesoutdir should resolve to system paths. The surest way to make it work is to set them to absolute paths.

[oddhack]

@mojavelinux thanks. This helps with the original problem - but now the problem I've got is inlining a static image also included in the actual document. If I also have an image::images/file.png[] directive in the document, and specify the imagesdir and imagesoutdir attributes to be the target output directory as well as in the -o option, then the generated ditaa image is inlined; but now it can't find the static images/file.png, with the same warning message.

[mojavelinux]

It now seems like you are running into a more classic problem of getting the path to static images correct. It's suspicious that the image target starts with images/. That should be part of the imagesdir value. Thus, you'd have something like:

• imagesdir=/path/to/images
• image::file.png[]

The resolved path should then be /path/to/images/file.png.

[oddhack]

I'm really confused now about the relationship between these variables and the different ways of getting images, after trying many combinations of imagesdir and imagesoutdir. Suppose I have the following document:

= Test
Title
:doctype: book
:data-uri:

image:images/OpenVX.png[align="center",{halfimagewidth}]

<<<

[ditaa, target="diagram"]
....
+-------+
| A box |
+-------+
....

Test document

and a static file, images/OpenVX.png .

Suppose I desire to get an output document in $cwd/out/index.html (via '-o out/index.html').

How can I specify imagesdir and imagesoutdir to let this happen? I've tried every combination of them I can think of and concluded (a) either imagesdir must not be specified, or imagesdir must point to the current directory, in order to successfully pull in the static OpenVX.png; but, (b) imagesdir must point to $cwd/out in order that the dynamically generated diagram.png be put in the right place, and successfully included in the output HTML. Specifically:

• unspecified imagesdir, unspecified imagesoutdir -> WARNING about diagram.png not found
• imagesdir=$cwd/out, unspecified imagesoutdir -> WARNING about OpenVX.png not found
• unspecified imagesdir, imagesoutdir=$cwd/out -> WARNING about diagram.png not found
• imagesdir=$cwd, imagesoutdir=$cwd/out -> WARNING about diagram.png not found
• imagesdir=imagesoutdir=$cwd/out -> WARNING about OpenVX.png not found

The behavior of imagesdir with the static image is sensible enough, but seems incompatible with the desired output location for the document containing the imbedded generated image. Am I missing another combination of variables that will work?

[oddhack]

Incidentally, this appears to be literally the exact scenario, down to the directory names, that @pepijnve discussed in #39 (comment) , but I don't see a resolution to his comment in #39.

[oddhack]

Ah, I see that setting imagesdir=$cwd, imagesoutdir=$cwd works - but leaves the dynamically generated diagram.png behind in $cwd. Also I have no idea why this appears to work when specifying imagesoutdir=$cwd/out does not.

[mojavelinux]

There are limits to the scenarios the current model can handle. You're hitting those limits, particularly because you are using data-uri. We're trying to use a single attribute (imagesdir) to handle entirely too many concerns. Asciidoctor Diagram helps a little bit by supporting imagesoutdir (which defaults to the directory used by -o), but that still doesn't necessarily address all the scenarios.

All that's to say that what you're encountering is not unexpected. Until we redesign some things in core regarding images, the best we can do is figure out how to make sense of what options do work as it stands now and document them. And yes, it's complicated. This is essentially the work I have to do when trying to answer these types of questions. And there are a lot of permutations to consider (esp when image generation is involved).

[pepijnve]

@mojavelinux at the moment diagram passes the path to the image implicitly to asciidoctor via the target attribute of the generated node. I can change this so that an absolute path is passed instead; that would remove the ambiguity. Just not sure if this might break other scenarios. Is AbstractNode#image_uri clever enough to relativize the image path again for the HTML output?

[pepijnve]

Just tested this and it doesn't do that. I can generate absolute vs relative paths in target based on the presence of the data-uri attribute. That would definitely make this particular case simpler.

A more robust alternative would be to have an extra node attribute besides target that specifies the exact local location of the image. Asciidoctor could then use that as an optional hint when trying to find images on disk like in the data-uri case.

[mojavelinux]

Is AbstractNode#image_uri clever enough to relativize the image path again for the HTML output?

If data-uri is set, when comes back is a data uri, so the path dissolves away. However, if data-uri is not set, it will use the path as provided.

I can generate absolute vs relative paths in target based on the presence of the data-url attribute. That would definitely make this particular case simpler.

That's great news.

A more robust alternative would be to have an extra node attribute besides target that specifies the exact local location of the image. Asciidoctor could then use that as an optional hint when trying to find images on disk like in the data-url case.

Exactly what I was thinking in terms of the redesign in core. We're trying to store too much information in a single value.

[pepijnve]

99d195d does the absolute path thing based on the data-uri attribute. That should simplify things in the short term.

[mojavelinux]

Thanks @pepijnve!!

[oddhack]

This is all going over my head but I'm glad you're making some progress :-) In the meantime, ISTM my only option is to find a combination of attributes which works, and clean up manually by moving files around after the build is complete?

Maybe it would be helpful to document some common usage scenarios involving these variables?

[pepijnve]

@oddhack in short the way asciidoctor-diagram and asciidoctor talk to each other is kind of fragile. Everything needs to be exactly right in order for things to work correctly; in particular when data-uri is used. I've made a small change to asciidoctor-diagram that will make this simpler to use. I'll get that released asap.

What @mojavelinux and I were discussing is a longer term fix that makes the communication between the core and the extension more robust.

[pepijnve]

@oddhack could you give 1.5.11 a try and see if things work better now?

[oddhack]

@pepijnve the imbedding works now without needing to set either imagesdir or imagesoutdir, and the generated image is in the outdir specified with -o, which is exactly what I was trying to do. Thank you very much!

[mojavelinux]

@oddhack I'm so happy to hear that! 🎉

I'm going to note down the ideas we had here and take it up as a task to improve core so we can make this integration more solid.

Do you think there's anything worth adding to the docs in the meantime?

[oddhack]

@mojavelinux TL;DR not at present.

Prior to the 1.5.11 update, I would have said that the "Image Output Location" section needed to be rewritten - but now, I'm hoping that things Just Work As Described. I did a brief re-check with my trivial sample and various combinations of imagesoutdir / imagesdir, and observed behavior seems consistent with that description.