PDF generation doesn't respect "resources" configuration attribute

[ge0ffrey]

Using the "resources" element in the plugin configuration, we can grab images from 2 directories. We use this to include shared images and a book-specific images. This works perfectly for the html output.

However for the PDF output, configured like this:

              <goals>
                <goal>process-asciidoc</goal>
              </goals>
              <configuration>
                <backend>pdf</backend>
                <resources>
                  <resource>
                    <directory>src/main/asciidoc</directory>
                  </resource>
                  <resource>
                    <directory>${project.basedir}/../shared-kie-docs/src/main/asciidoc</directory>
                  </resource>
                </resources>
                <sourceDocumentName>index.adoc</sourceDocumentName>
                <outputDirectory>${project.build.directory}/generated-docs/pdf</outputDirectory>
              </configuration>

The images end up broken in the pdf and the maven console shows messages like these for images not residing in src/main/asciidoc:

  asciidoctor: WARNING: image to embed not found or not readable: /home/.../kie-docs/docs/optaplanner-wb-es-docs/src/main/asciidoc/KieServer/kie-server-simple-architecture.png
asciidoctor: WARNING: image to embed not found or not readable: /home/.../kie-docs/docs/optaplanner-wb-es-docs/src/main/asciidoc/KieServer/kie-server-architecture.png

[abelsromero]

That's kind of expected. Maybe we should add a warning in the README to avoid confusions. The plugin just copies the resources to the target(s), but it does not modify any configuration, for instance, in this case it does not modify the imagesdir attribute. That affects backends that embed images or other resources from source directory like PDF.

In order to solve this, you can setup the imagesdir accordingly in every document section when rendering to pdf like this:

= Title
:imagesdir: images

This is just a document to test images includes.

== First Section

This images is in `images` directory.

image::asciidoctor-icon.jpg[]

== Second Sections
// Replaces imagesdir value from this point on when using PDF backend
ifdef::backend-pdf[]
:imagesdir: more-images
endif::[]

This images isn't.
image::ruby.png[]

But beware, because this affects the document, so once imagesdir is modified the new value remains.

Alternatively, you could try to build an extension that adjustes the imagesdir dinamically looking for images in diferent directories, but I think the option above is more manteinable. Still if you are interested on the extension, I think I'll give it a try for fun.

[mojavelinux]

I think we need to take a step back and focus on "That's kind of expected".

The HTML and PDF converters need images at different times. The PDF converter needs the image at the time of the conversion since it embeds the image into the output document. The HTML converter needs the image at the time the document is viewed, so those images need to be copied along with the HTML (unless data-uri is set, in which case it acts like the PDF converter).

There is no need to copy resources when converting to PDF. Everything goes in the PDF document. However, it does mean that the imagesdir needs to point to the source location of the images. If for some reason it needs to be different, just set imagesdir appropriately in the plugin configuration and you're done. No need for a Treeprocessor. (However, I do recommend setting the imagesdir to a relative path to the source document so that images appear in the preview).

The one exception is if you have a mix of static source images and generated images (via Asciidoctor Diagram). In that case, things get trickier. You need to first copy the static source images to the output folder, then configure Asciidoctor Diagram to write images to that location, and finally configure Asciidoctor to look in the generated images folder to resolve all images. No doubt, this is the hardest scenario to configure...but AFAIK it is possible.

When converting to HTML, the imagesdir should be the relative path from the HTML document to the image...as it is the browser that uses this value to resolve the image.

[mojavelinux]

If there are ways we can make this simpler either through code changes or documentation changes, I'm 100% in favor. I'm just trying to help you understand the scenarios first.

[mojavelinux]

Using the "resources" element in the plugin configuration, we can grab images from 2 directories. We use this to include shared images and a book-specific images. This works perfectly for the html output.

In this case, you'll want to set the imagesdir attribute in the plugin configuration to the absolute path of the target images directory (the directory where you are collecting all the images). Asciidoctor PDF uses a system path to read in the images, so an absolute path will work here.

[mojavelinux]

It's important to keep in mind that Asciidoctor PDF essentially requires that all images be in the same directory (or relative to that directory). I refer to this as the images "catalog". This catalog can be anywhere though. The image "target" is the path relative to this catalog root. That's the best way to think of it.

[abelsromero]

If there are ways we can make this simpler either through code changes or documentation changes, I'm 100% in favor. I'm just trying to help you understand the scenarios first.

We could add and option to enable some sort of resources automanaging specific for PDF, some option that enables a custom pipeline that:

1. Copy resources to staging area under target but not in the path were documents are generated. Something managed by the plugin.
2. Sets imagedir to staging area path.

Note that targetPath in the <resource> sections would be ignored.

From a design stand point, it can be made in a way that other backends can 'hook' custom logic in the future. But this should be optional, so that if someone wants to tailor the whole process manually it can still be done. The only thing I don't like -as with any automation- is that it hides details, making it harder for people to understand how it works.

[mojavelinux]

I think it's worth exploring that route. We should emphasize, though, that this is only necessary if you're merging images from multiple source locations (including using Asciidoctor Diagram to generate images to a temporary folder). If you are not, conversion to PDF is actually simpler since you don't have to move images at all.

[ge0ffrey]

@abelsromero Agreed with in PDF appproach of "first copy all resources directories" to a generated directory and then use that as the images input directory

[ge0ffrey]

@mojavelinux Why doesn't asciidoctor want to support multiple images directories? For our use case, we have several guides (= several maven modules) that have a set of shared adoc files (which contain images). So we have this:

/kie-shared-docs/src/main/asciidoc/howToContribute.adoc
/kie-shared-docs/src/main/asciidoc/images/pullRequestScreenshot.png

/drools-docs/src/main/asciidoc/index.adoc // includes howToContribute.adoc too
/drools-docs/src/main/asciidoc/gettingStartedWithDrools.adoc
/drools-docs/src/main/asciidoc/images/droolsLogo.png

/jbpm-docs/src/main/asciidoc/index.adoc // includes howToContribute.adoc too
/jbpm-docs/src/main/asciidoc/gettingStartedWithJbpm.adoc
/jbpm-docs/src/main/asciidoc/images/jbpmLogo.png

With only 1 images directory, we'd have to put pullRequestScreenshot.png, droolsLogo.png and jbpmLogo.png in the same maven module in the same git repository. This makes it painful to build out a reusable set of common adoc sections for an organization, such as:

• common legal section (with company logo png)
• common open source sections, such as "how to contribute"
• common company introduction, such as address, mission, about us, etc
• ...

[mojavelinux]

Why doesn't asciidoctor want to support multiple images directories?

Because Asciidoctor doesn't check for the presence of the image, at least not in all cases. Though I suppose that if a certain attribute is set, such as imagedirs, then that behavior could be introduced. That would have to happen in core, though. And, we'd still have to differentiate between source image directories and image paths in the output document (such as in the case of HTML).