If the absolute path of the generated image contains a double underscore, the image will not be found

[oddhack]

Edit: after @mojavelinux moved this issue here I produced a minimal case in the attached zipfile that doesn't require using Docker or our spec repo. Reproduce by downloading the attachment to /tmp and

unzip test102.zip
cd test102
make works
make fails

The file gems.txt shows all the gems I have installed - basically everything is up to date as of posting time.

The problem seems to be sensitive to following asciidoctor markup as well as the path on which equation SVGs are being generated, e.g. removing everything after the latexmath[] directive makes the failure case go away.

---

TL;DR we have a pretty complex document build which I'm integrating into Github Actions. Actions extracts the repository under /__w/SYCL-Docs/SYCL-Docs/ - I don't think I can control this location - and on this path, I see lots of errors like this:

asciidoctor: WARNING: image to embed not found or not readable: /<em>w/SYCL-Docs/SYCL-Docs/adoc/out/equations_temp/stem-5373936b5901139f132b498255a95fa5.svg

(see here: https://github.com/KhronosGroup/SYCL-Docs/pull/117/checks?check_run_id=2066711877)

This is not Docker-specific, but path-specific: running the build on a repo located under /__w/ results in the errors and putting it under a more common path like /sycl does not get errors.

The '/<em>w/' part of the error suggests that at some point in the toolchain, the '__w' may be getting interpreted as asciidoctor markup rather than as a literal pathname. I have tried replicating the error using just a regular image: directive but have not been able to, which leads me to think something about the way asciidoctor-pdf is interacting with asciidoctor-mathematical is responsible, rather than general handling of paths in image: directives.

If you need to reproduce our build to diagnose the problem, here's a recipe assuming you can run docker:

# In your shell:
docker run -it --rm khronos-group/docker-images:asciidoctor-spec /bin/bash

# Inside the Docker image, build under /__w/ - should fail
mkdir -p /__w/SYCL-Docs
cd /__w/SYCL-Docs
git clone https://github.com/KhronosGroup/SYCL-Docs.git
cd SYCL-Docs/adoc
git checkout 9cc7b456ab2ef288a3f758634dc24a4d0e715fee
make QUIET= pdf
# Lots of 'image to embed not found or readable errors' followed by build failing

# Now build under /sycl/ - should work
make clean
mv /__w /sycl
cd /sycl/SYCL-Docs/SYCL-Docs/adoc
make pdf
# No errors and build succeeds

If this is too complex I can try to strip down the document markup - the problem appears to happen at the first latexmath:[] directive in the doc.
test102.zip

[mojavelinux]

It seems pretty clear to me what is going on. The __ character sequence is an unconstrained formatting mark and will thus match anywhere in a paragraph, even if found in the target of an image. The way Asciidoctor Mathematical works is that it replaces the STEM macros (e.g., latexmath) with an inline image macro. The target of this macro will be the absolute path of the generated image, which in your case includes __. At that point, the Asciidoctor processor applies normal substitutions, which is going to interpret that formatting mark if it finds a matching pair.

Since Asciidoctor Mathematical replaces the text pre-substitution, it needs to protect against absolute paths which may contain formatting marks. There are two ways Asciidoctor Mathematical can do this. a) It can enclose the image macro in a passthrough macro so that it's hidden from substitutions or b) It can store the base path to the generated images in an attribute and use an attribute reference in the target. a) is probably the simplest approach, but that is up for Asciidoctor Mathematical to decide.

There's nothing Asciidoctor PDF can do about this since it's not Asciidoctor PDF that's interpreting the formatting marks. It's happening inside the core processor, and it's behavior is correct given the input it is receiving. This issue belongs in Asciidoctor Mathematical, though GitHub Actions using a path with double underscores is what makes this situation arise.

[oddhack]

@mojavelinux thanks for the analysis.

I've produced a minimal example, linked in a zip file from the issue header, which has been updated.

[mojavelinux]

@ProgramFan What I would recommend is to check whether the path to the generated image for an inline equation contains a sequence of one or more underscores. If it does, wrap the macro in pass:c,m[]. You'll need to escape the closing bracket of the inline macro with a backslash.

[mojavelinux]

Thanks for providing the reproducible example, @oddhack!

[oddhack]

Thanks for providing the reproducible example, @oddhack!

NP. Our spec toolchain is fairly arcane.