Behaviour of relative path resolution

[pajoma]

Following the theming guide for PDFs, I am trying to set the attribute "pdf-stylesdir" and use a common theme for several documents using the following structure:
repo/concepts/themes and repo/concepts/documents/projXY/doc1/

In doc1 I have a Gradle build file and a subdirectory content with my asciidoc files.

When I use 'pdf-stylesdir': '../../../themes/pdf' in my build file in doc1 and I run gradle clean asciidoctor the file is expected to be in repo/concepts/documents/themes (as expected, since it is relative to the source directory, which is the subdirectory docs in doc1).

For the value 'pdf-stylesdir': '../../../../themes/pdf'(one directory below), it searches in repo (two directories below). Looks a bit like a recursion bug.

Sorry if this the wrong component of asciidoctor, I was not sure if this issue is related to asciidoctor, asciidoctor-pdf or the Gradle Plugin.

[pajoma]

Ok, I thought I just copy the themes folder into the subfolder documents without touching the build script.

Resulting error message:
(Errno::ENOENT) D:/path/to/repo/concepts/themes/custom-theme.yml (yes, that's where I want the folder to be)

I copy the folder themes back into the folder concepts and I get the error message:
(Errno::ENOENT) D:/path/to/repo/concepts/documents/themes/custom-theme.yml (wait, I just removed the folder from here)

confused

Having D:/path/to/repo/concepts/themes/custom-theme.yml AND D:/path/to/repo/concepts/documents/themes/custom-theme.yml --> BUILD SUCCESSFUL

[mojavelinux]

In general, I don't recommend using relative paths for roots like pdf-stylesdir. It is best to use Gradle to resolve the absolute path. Can you confirm you have done that step?

[pajoma]

Good to know, thanks for the tip. I have the following build file now

def workspaceDir = projectDir.getParentFile().getParentFile().getPath()
println "Workspace: " + workspaceDir

defaultTasks 'asciidoctor'
asciidoctor {
    backends = ['pdf'] 
    sourceDir  'docs'

    attributes  'workspaceDir': workspaceDir, 
                'pdf-style': 'custom',
                'pdf-stylesdir': workspaceDir+'/.themes/pdf'
}

and it seems to work.

[mojavelinux]

The reason I recommend using an absolute path is because there are a lot of different roots involved here and, even if you can reason about them, it requires a lot of brain power to know what the relative path means. It's just much better in a build system to be using absolute paths resolved by the build tool.

[mojavelinux]

With Gradle, you should be able to use file() instead of constructing the path manually. But go with what works in the end.

[mojavelinux]

An open question is whether the pdf-stylesdir value, if a relative path, should be resolved relative to the base_dir option.

[mojavelinux]

The value of pdf-themesdir and pdf-fontsdir is resolved relative to the current working directory. However, if you use {docdir} as the first segment, you can build a value that is relative to the document directory.

:pdf-theme: chronicles
:pdf-themesdir: {docdir}

In Asciidoctor PDF 2, you will also be able to use the {docdir} token when passing the attribute via the API or CLI.

-a pdf-themesdir={docdir}