Update docs and templates to recommend an absolute path for the `pdf-…

…themesdir` (#1750)

CHANGELOG.adoc

@@ -9,7 +9,7 @@ This document provides a high-level view of the changes introduced by release.
 
 === 0.43.5
 
-...
+- Update docs and templates to recommend an absolute path for the `pdf-themesdir` (#1750)
 
 === 0.43.4
 

doc/users-guide/modules/ROOT/pages/faq.adoc

@@ -114,6 +114,25 @@ This is not supported by Asciidoctor PDF.
 
 See xref:faq/diagrams-in-pdf-without-text.adoc[] for more details.
 
+=== Themes are not used when creating a PDF via the IDE
+
+To use a theme when creating PDFs in the IDE, always specify an absolute directory pointing to the `themes` folder.
+
+When specifying the folder in a regular AsciiDoc file, use the `{docdir}` attribute as a prefix to point to a folder
+relative to the current document:
+
+[source,asciidoc]
+----
+:pdf-themesdir: {docdir}/themes
+----
+
+When specifying a theme relative in an `.asciidoctorconfig` file, use the folder of that file by prefixing `{asciidoctorconfigdir}`:
+
+[source,asciidoc]
+----
+:pdf-themesdir: {asciidoctorconfigdir}/themes
+----
+
 == Other Troubles
 
 === Something is not working as I expect it to work, where can I get help?

doc/users-guide/modules/ROOT/pages/features/advanced/pdf-non-latin-languages.adoc

@@ -19,7 +19,7 @@ A complete example is available in https://github.com/ahus1/asciidoctor-deepdive
 [source,text]
 ----
 = 标题
-:pdf-themesdir: themes <1>
+:pdf-themesdir: {docdir}/themes <1>
 :pdf-theme: zh_CN <2>
 :pdf-fontsdir: fonts <3>
 

src/main/resources/AsciiDocBundle.properties

@@ -644,10 +644,12 @@ asciidoc.attributes.builtin.pdf-style.default-value=not set
 asciidoc.attributes.builtin.pdf-style.values=any
 
 asciidoc.attributes.builtin.pdf-themesdir.text=The directory where the theme file is located. Specifying an absolute path is recommended.\n\
+Prefix with {docdir} to ensure a path relative to the current document\n\
 If you use images in your theme, image paths are resolved relative to this directory. If :pdf-theme: ends with .yml, and :pdf-themesdir: is not specified, then :pdf-themesdir: defaults to the directory of the path specified by :pdf-theme:.
 asciidoc.attributes.builtin.pdf-themesdir.default-value=not set
 asciidoc.attributes.builtin.pdf-themesdir.values=any
 asciidoc.attributes.builtin.pdf-stylesdir.text=The directory where the theme file is located. Specifying an absolute path is recommended.\n\
+Prefix with {docdir} to ensure a path relative to the current document\n\
 If you use images in your theme, image paths are resolved relative to this directory. If :pdf-theme: ends with .yml, and :pdf-themesdir: is not specified, then :pdf-themesdir: defaults to the directory of the path specified by :pdf-theme:.
 asciidoc.attributes.builtin.pdf-stylesdir.default-value=not set
 asciidoc.attributes.builtin.pdf-stylesdir.values=any

src/main/resources/liveTemplates/AsciiDocLiveTemplates.xml

@@ -304,7 +304,7 @@
       <option name="AsciiDoc" value="true" />
     </context>
   </template>
-  <template name="ad-config-pdf" value="// use these attributes to configure some attributes for asciidoctor-pdf&#10;:pdf-page-size: $pdfSize$&#10;// see https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc&#10;:pdf-themesdir: $pdfTheme$&#10;" description="PDF-configuration for page-size and themesdir" toReformat="true" toShortenFQNames="true">
+  <template name="ad-config-pdf" value="// use these attributes to configure some attributes for asciidoctor-pdf&#10;:pdf-page-size: $pdfSize$&#10;// see https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc&#10;:pdf-themesdir: {docdir}/$pdfTheme$&#10;" description="PDF-configuration for page-size and themesdir" toReformat="true" toShortenFQNames="true">
     <variable name="pdfSize" expression="" defaultValue="&quot;A4&quot;" alwaysStopAt="true" />
     <variable name="pdfTheme" expression="" defaultValue="&quot;../pdfTheme&quot;" alwaysStopAt="true" />
     <context>