Posted by abelsromero on Jan 23, 2015; 9:17am
URL: https://discuss.asciidoctor.org/asciidoctor-maven-plugin-and-images-tp2695p2696.html

First of all, thanks for such a thoroughly explanation, I'd try to answer point by point.
As a briefing, the main thing to understand is that  there're two separate processes:
1. Generating the images url in the final document: here imagesDir parameter (and other parameters) is used to generate the final path, which is not checked.
2. Copying resources to target folder: this is done by the plugin based on some configuration, and not by asciidoctorj or ascidoctor (ruby core).
You see, the trick is getting the correct configuration so that the final target path matches the one being generated.

= 1/ first use-case: renaming
You got it right.

== 2/ second use-case: location of the image folder
imageDir is just used to generate the images url in the final document. If you are using an HTML backend, this parameter is prepended to the image filename. In other words, nor the maven plugin, nor asciidoctorj or asciidoctor (the ruby final engine) validates if the path is correct, it just generates the path.
It is expected that imageDir is a relative to basePath, which by default is the same as sourceDirectory. Also keep in mind that if relativeBaseDir is set to true, all resources will be looked for in a relative location  to its AsciiDoc file...this is tricky.

Regarding the final target folder, the plugin kinda 'assumes' images and other resources are in a path relative to the AsciiDoc documents and I think this is an issue that we should fix. Currently only resources under the 'sourceDirectory' parameter are copied, and 'basePath' resources should be copied too.
Adding this behaviour you should be able to achieve what I think you want to do using this configuration:

<basePath>../../imgs<basePath>
<images>images</images> // this would work as long as image files are in ../../imgs/images. If you set the image files directly under  ../../imgs, images will be copied to 'target/generated-docs/' and the value should be <images></images>

However, this struck me as a weird and hard to maintain configuration. Anyway, please, feel free to open an issue on GitHub regarding baseDir resources not being copied.

About copying only used images, currently asciidoctorj (nor asciidoctor) does not provide information on things like that, it's something that has been discussed sometime and is on the work, but don't expect it soon, sorry :%

==  gradle plugin has a special note
The gradle feature is a copy-from-to function with no relation to the asciidoctor conversion process (afaik). This is easy to integrate in gradle and of course we could include something similar, but this is harder in maven and it can already be done using other plugins like http://maven.apache.org/plugins/maven-resources-plugin/. Just attach it to process-resources (assuming you use generate-resources for asciidoctor) and you'll be fine.

==  asciidoctor-pdf issue
Indeed, that's a serious issue. You have to understant that every backend is a made with a different implementation and some undesired different behauvour between some of them may arise :%

additional parameter imagesdir_out
I can see the option to set some conversion pattern useful sometimes, but I said before, it seems to me like something hard to maintain. Hard, not from the plugin but for consumers, what I mean, is that having to match different sources folders to different target folder can be complicated to deal with in a collaborative environment.

Finally, if you really want to get into the philosophy and understand what's under the hood, I recommend you to have a look at asciidoctor manual http://asciidoctor.org/docs/user-manual/ and play a bit with the command tool.

And thanks again for such analysis,  this really helps to see other points of view to improve the tools.