provide more accurate details about how the theme and related attributes are resolved

1 files changed, 16 insertions, 11 deletions

diff --git a/docs/modules/theme/pages/apply-theme.adoc b/docs/modules/theme/pages/apply-theme.adoc
index a24e66c7..a0f497cb 100644
--- a/docs/modules/theme/pages/apply-theme.adoc
+++ b/docs/modules/theme/pages/apply-theme.adoc
@@ -12,15 +12,15 @@ When using JRuby, the file path may begin with `uri:classloader:` to reference a
 +
 If the value of the `pdf-theme` attribute ends with `.yml` (e.g., `custom-theme.yml`), the name is assumed to be an absolute or relative file path.
 If the path is relative, it's resolved starting from the value of the `pdf-themesdir` attribute.
-If the `pdf-themesdir` attribute is not specified, the current working directory is used instead.
+If the `pdf-themesdir` attribute is not specified, it is resolved from the current working directory instead.
 +
 If the value of the `pdf-theme` attribute doesn't end with `.yml` (e.g., `base`), the suffix `-theme.yml` is automatically appended to build a valid absolute or relative file path (i.e., `<name>-theme.yml`).
-If the resulting file path is relative, it's resolved starting from the value of the `pdf-themesdir` attribute.
-If the `pdf-themesdir` is not specified, the built-in themes directory is used instead (rather than the current working directory).
+The value is then treated as a relative path (even if it's absolute) and resolved starting from the value of the `pdf-themesdir` attribute.
+If the `pdf-themesdir` is not specified, the built-in themes directory is used as the starting point instead (rather than the current working directory).
 +
 You can use the `+{docdir}+` token as the first path segment in the name to build an absolute path starting from the directory of the source document.
 +
-Can be specified using the `--theme` CLI option as a shorthand.
+The theme name or file path can be specified using the `--theme` CLI option as a shorthand.
 
 pdf-themesdir:: The directory path where the theme file is located.
 When using JRuby, the directory path may begin with `uri:classloader:` to reference a location on the classpath.
@@ -28,14 +28,16 @@ When using JRuby, the directory path may begin with `uri:classloader:` to refere
 If the path is relative, the value is resolved starting from the current working directory.
 You can use the `+{docdir}+` token as the first path segment to build an absolute path starting from the directory of the source document.
 +
-Relative image paths in your theme are resolved starting from this location.
-(In the future, these relative paths may be resolved starting from the directory where the theme file is located, which could be different).
+If not specified, the value of this attribute will default to the absolute directory of the theme file (as specified by the `pdf-theme` attribute).
+If you want to use an ancestory directory instead, you must specify both the `pdf-themesdir` attribute and the `pdf-theme` attribute, and the `pdf-theme` attribute must be a path (at any depth) relative to the value of `pdf-themesdir`.
++
+Relative image paths in your theme (such as image targets) are resolved starting from this location.
 
 pdf-fontsdir:: The directory path or paths where the fonts used by your theme, if any, are located.
 When using JRuby, each path may begin with `uri:classloader:` to reference a location on the classpath.
 +
 Multiple entries must be separated by either a comma or a semicolon.
-To reference a file inside a JAR file on the classpath, prefix with the path with `uri:classloader:` (AsciidoctorJ only).
+To reference a file inside a JAR file on the classpath, prefix with the path with `uri:classloader:` (JRuby only).
 If the path is relative, the value is resolved starting from the current working directory.
 +
 You can use the `+{docdir}+` token as the first path segment to create an absolute path starting from the directory of the document.
@@ -67,12 +69,15 @@ You can shorten `-a pdf-theme=` to `--theme`:
 If all goes well, Asciidoctor PDF will convert your document without any errors or warnings.
 
 TIP: You only need to specify the `pdf-fontsdir` if you're using custom fonts in your theme.
+By default, `pdf-fontsdir` resolves to the directory of the bundled fonts.
 
 You can skip setting the `pdf-themesdir` attribute by passing the relative path of your theme file to the `theme` option:
 
  $ asciidoctor-pdf --theme resources/themes/basic-theme.yml -a pdf-fontsdir=resources/fonts doc.adoc
 
-These relative paths are resolved starting from the current working directory.
+In this case, the `pdf-themesdir` will be set automatically to the directory of the path specified by the `pdf-theme` attribute ([.path]_resources/themes_ in the previous example).
+
+If a relative path is specified for `pdf-themesdir` or `pdf-fontsdir`, or `pdf-theme` when `pdf-themesdir` is not specified, that path is resolved starting from the current working directory.
 Alternately, you can use `+{docdir}+` as the first path segment to anchor them to the directory of the source document instead.
 
 If you're having difficulty getting the converter to locate your theme or fonts, you can specify absolute paths instead, which are used as is.
@@ -80,7 +85,7 @@ If you're having difficulty getting the converter to locate your theme or fonts,
  $ asciidoctor-pdf --theme /path/to/resources/themes/basic-theme.yml -a pdf-fontsdir=/path/to/resources/fonts doc.adoc
 
 Relative font paths in the theme are resolved starting from the directory resolved from the `pdf-fontsdir` attribute.
-All other paths in the theme are resolved starting from the directory where the theme file is found.
+All other paths in the theme are resolved starting from the value of the `pdf-themesdir` attribute.
 You can prefix paths in the theme using the `+{docdir}+` or `+{docimagesdir}+` attribute references.
 
 == Using Maven and Gradle
@@ -95,6 +100,6 @@ Speaking of Java, you can bundle and distribute your theme and fonts in a jar fi
 To reference the theme file and/or directory of fonts from inside the jar, refer to their location on the classpath using the `uri:classloader:` prefix.
 Here's how you'd load both the theme and fonts from the classpath:
 
- $ asciidoctorj -b pdf -a pdf-theme="uri:classloader:/path/to/themes/my-theme.yml" -a pdf-fontsdir="uri:classloader:/path/to/fonts" document.adoc
+ $ asciidoctorj -b pdf -a pdf-theme=uri:classloader:/path/to/themes/my-theme.yml -a pdf-fontsdir=uri:classloader:/path/to/fonts document.adoc
 
-This only works when running Asciidoctor PDF on the JVM.
+This only works when running Asciidoctor PDF with JRuby (i.e., on the JVM).