asciidoctor-pdf 1.5.0.beta.4 → 1.5.0.beta.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5128f12524a44fcbb19f0127e8bf0ec546f0287e80fae2bb6ccb70a1a69a2a7e
-  data.tar.gz: fa168da5cd4a10528e3bb732467d2f129d64fdaf26d182b874ccf6a70729bc51
+  metadata.gz: f6a1fbcfb416a485f625f2b12c4b7c30806e0d05cdf3ecc327b2ae6b0b04003e
+  data.tar.gz: bb1f4811237d7478cd132474175e11fbc1fa9e4755a0888ba1bb633215174b16
 SHA512:
-  metadata.gz: b91e25292d981f9409298c7ad49acd41e9c259e56dde1935d7e03d54326ee8aca9c0ef9a02532aab172c42da1fd7bbcad943c047a523af3990486ae05f1d2acc
-  data.tar.gz: 3034f7607666738c74c47bca7f6400568030e100a4e2bc5ca2de268ab4c2d0ba94afc531b20c0ed72b5d04a592a22735eb95b6846d7a93c2c467799bf96d1092
+  metadata.gz: f8ed0674cbc59c95bd5408874381d24708d3d07f3c6762297e9352727ddab3a67afae2e32bd48585feac84f57f9cfc03d8cee1388003617772a457591354793a
+  data.tar.gz: 1d38fa4fce88891b32d15b52829244222f5a1ada6269ad6108ed38cda7ed8a202d8793a4dab1ff9eadd597c53768994e0bf844e94587752d5ce51f7801677152

data/CHANGELOG.adoc

@@ -5,6 +5,17 @@
 This document provides a high-level view of the changes to the {project-name} by release.
 For a detailed view of what has changed, refer to the {uri-repo}/commits/master[commit history] on GitHub.
 
+== 1.5.0.beta.5 (2019-09-13) - @mojavelinux
+
+* pass styles for inline elements downwards when parsing, allowing role to override default styles for element (#1219)
+* document title in outline should point to second page if document has cover page (#1268)
+* start at setting for running content and page numbering must account for disabled title page (book doctype) (#1263)
+* start at setting for running content and page numbering must account for front cover (#1266)
+* preserve indentation that uses tabs in verbatim blocks when tabsize is not set (#1258)
+* use consistent line height for list items and toc entries if text is entirely monospace (#1204)
+* fix spacing between items in qanda list
+* expand home directory reference in theme name when value ends with .yml and no themedir is specified
+
 == 1.5.0.beta.4 (2019-09-04) - @mojavelinux
 
 * always use ; as delimiter to separate multiple font dirs to be compatible with JAR paths (#1250)

data/README.adoc

@@ -1,6 +1,6 @@
 = Asciidoctor PDF: A native PDF converter for AsciiDoc
 Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>
-v1.5.0.beta.4, 2019-09-04
+v1.5.0.beta.5, 2019-09-13
 // Settings:
 :experimental:
 :idprefix:
@@ -24,25 +24,25 @@ endif::[]
 :project-name: Asciidoctor PDF
 :project-handle: asciidoctor-pdf
 // Variables:
-:release-version: 1.5.0.beta.4
+:release-version: 1.5.0.beta.5
 // URIs:
-:uri-asciidoctor: http://asciidoctor.org
-:uri-gem: http://rubygems.org/gems/asciidoctor-pdf
-:uri-project: https://github.com/asciidoctor/asciidoctor-pdf
-:uri-project-repo: {uri-project}
-:uri-project-issues: {uri-project-repo}/issues
-:uri-project-list: http://discuss.asciidoctor.org
-:uri-prawn: http://prawnpdf.org
-:uri-prawn-gmagick: https://github.com/packetmonkey/prawn-gmagick
-:uri-prawn-svg: https://github.com/mogest/prawn-svg
-:uri-asciidoctor-mathematical: https://github.com/asciidoctor/asciidoctor-mathematical
-:uri-rvm: http://rvm.io
-:uri-graphicsmagick: http://www.graphicsmagick.org
+:url-asciidoctor: http://asciidoctor.org
+:url-gem: http://rubygems.org/gems/asciidoctor-pdf
+:url-project: https://github.com/asciidoctor/asciidoctor-pdf
+:url-project-repo: {url-project}
+:url-project-issues: {url-project-repo}/issues
+:url-project-list: http://discuss.asciidoctor.org
+:url-prawn: http://prawnpdf.org
+:url-prawn-gmagick: https://github.com/packetmonkey/prawn-gmagick
+:url-prawn-svg: https://github.com/mogest/prawn-svg
+:url-asciidoctor-mathematical: https://github.com/asciidoctor/asciidoctor-mathematical
+:url-rvm: http://rvm.io
+:url-graphicsmagick: http://www.graphicsmagick.org
 
 ifdef::status[]
 image:https://img.shields.io/travis/asciidoctor/asciidoctor-pdf/master.svg[Build Status (Travis CI),link=https://travis-ci.org/asciidoctor/asciidoctor-pdf]
 image:https://ci.appveyor.com/api/projects/status/524bhoms3j2dp1o3/branch/master?svg=true[Build Status (AppVeyor),link=https://ci.appveyor.com/project/asciidoctor/asciidoctor-pdf]
-image:https://img.shields.io/gem/v/asciidoctor-pdf.svg[Latest Release, link={uri-gem}]
+image:https://img.shields.io/gem/v/asciidoctor-pdf.svg[Latest Release, link={url-gem}]
 image:https://img.shields.io/badge/license-MIT-blue.svg[MIT License, link=#copyright]
 endif::[]
 
@@ -53,7 +53,7 @@ Instead, you can use it to convert directly from AsciiDoc to PDF.
 Its aim is to take the pain out of creating PDF documents from AsciiDoc.
 endif::[]
 ifndef::env-site[]
-_Lo and behold_, a native PDF converter for AsciiDoc built with {uri-asciidoctor}[Asciidoctor] and {uri-prawn}[Prawn]! +
+_Lo and behold_, a native PDF converter for AsciiDoc built with {url-asciidoctor}[Asciidoctor] and {url-prawn}[Prawn]! +
 _No more middleman._ +
 _No more DocBook toolchain._ +
 It's AsciiDoc straight to PDF!
@@ -62,10 +62,10 @@ toc::[]
 
 == Prawn, the Majestic PDF Generator
 
-{uri-project}[{project-name}] is made possible by an amazing Ruby gem named Prawn.
+{url-project}[{project-name}] is made possible by an amazing Ruby gem named Prawn.
 And what a gem it is!
 
-{uri-prawn}[Prawn] is a nimble PDF writer for Ruby.
+{url-prawn}[Prawn] is a nimble PDF writer for Ruby.
 More important, it's a hackable platform that offers both high level APIs for the most common needs and low level APIs for bending the document model to accommodate special circumstances.
 
 With Prawn, you can write text, draw lines and shapes and place images _anywhere_ on the page and add as much color as you like.
@@ -542,7 +542,7 @@ If an image dimension matches the height or width of the page, the positioning k
 
 == Fonts in SVG Images
 
-Asciidoctor PDF uses {uri-prawn-svg}[prawn-svg] to embed SVGs in the PDF document, including SVGs generated by Asciidoctor Diagram.
+Asciidoctor PDF uses {url-prawn-svg}[prawn-svg] to embed SVGs in the PDF document, including SVGs generated by Asciidoctor Diagram.
 
 Actually, it's not accurate to say that prawn-svg embeds the SVG.
 Rather, prawn-svg is an SVG _renderer_.
@@ -583,17 +583,17 @@ If you're using fonts in your SVG, and you want those fonts to be preserved, tho
 
 In order to embed an image into a PDF, Asciidoctor PDF must understand how to read it.
 To perform this work, Asciidoctor delegates to the underlying libraries.
-{uri-prawn}[Prawn] provides support for reading JPG and PNG images.
-{uri-prawn-svg}[prawn-svg] brings support for SVG images.
+{url-prawn}[Prawn] provides support for reading JPG and PNG images.
+{url-prawn-svg}[prawn-svg] brings support for SVG images.
 Without any additional libraries, those are the only supported image file formats.
 
-If you need support for additional image formats, such as GIF, TIFF, or interlaced PNG--and you don't want to convert those images to a supported format--you must install the {uri-prawn-gmagick}[prawn-gmagick] (>= 0.0.9) Ruby gem.
-prawn-gmagick is an extension for Prawn based on {uri-graphicsmagick}[GraphicsMagick] that adds support for all the image formats recognized by that library.
+If you need support for additional image formats, such as GIF, TIFF, or interlaced PNG--and you don't want to convert those images to a supported format--you must install the {url-prawn-gmagick}[prawn-gmagick] (>= 0.0.9) Ruby gem.
+prawn-gmagick is an extension for Prawn based on {url-graphicsmagick}[GraphicsMagick] that adds support for all the image formats recognized by that library.
 prawn-gmagick has the added benefit of significantly reducing the time it takes to generate a PDF containing a lot of images.
 
 The prawn-gmagick gem uses native extensions to compile against GraphicsMagick.
 This system prerequisite limits installation to Linux and OSX.
-Please refer to the {uri-prawn-gmagick}[README for prawn-gmagick] to learn how to install it.
+Please refer to the {url-prawn-gmagick}[README for prawn-gmagick] to learn how to install it.
 
 Once this gem is installed, Asciidoctor automatically switches over to it to handle embedding of all images.
 In addition to support for more additional image file formats, this gem also speeds up image processing considerably, so we highly recommend using it if you can.
@@ -734,13 +734,13 @@ That prototype can be found in the https://github.com/asciidoctor/asciidoctor-ex
 
 === Asciidoctor Mathematical
 
-{uri-asciidoctor-mathematical}[Asciidoctor Mathematical] is an extension for Asciidoctor that provides alternate processing of STEM blocks and inline macros (currently only latexmath).
+{url-asciidoctor-mathematical}[Asciidoctor Mathematical] is an extension for Asciidoctor that provides alternate processing of STEM blocks and inline macros (currently only latexmath).
 After the document has been parsed, the extension locates all the latexmath blocks and inline macros, converts the equations to images using Mathematical, then replaces them with image nodes.
 Conversion then proceeds as normal.
 
 Asciidoctor Mathematical is a Ruby gem that uses native extensions.
 It has a few system prerequisites which limit installation to Linux and OSX.
-Please refer to the {uri-asciidoctor-mathematical}#installation[installation section] in the Asciidoctor Mathematical README to learn how to install it.
+Please refer to the {url-asciidoctor-mathematical}#installation[installation section] in the Asciidoctor Mathematical README to learn how to install it.
 
 Once Asciidoctor Mathematical is installed, you just need to enable it when invoking Asciidoctor PDF using the `-r` flag:
 
@@ -760,7 +760,7 @@ You control this setting using the `mathematical-format` AsciiDoc attribute:
 
  $ asciidoctor-pdf -r asciidoctor-mathematical -a mathematical-format=svg sample.adoc
 
-Refer to the {uri-asciidoctor-mathematical}#readme[README] for Asciidoctor Mathematical to learn about additional settings and options.
+Refer to the {url-asciidoctor-mathematical}#readme[README] for Asciidoctor Mathematical to learn about additional settings and options.
 
 == Skipping Passthrough Content
 
@@ -951,7 +951,7 @@ To contribute code, simply fork the project on GitHub, hack away and send a pull
 *All pull requests must include a) tests that verify the code change and b) an entry in the CHANGELOG.adoc file to document what changed.*
 If a pull request is missing tests or a CHANGELOG entry, *it will not be merged*.
 
-Feel free to use the {uri-project-issues}[issue tracker] or {uri-project-list}[Asciidoctor mailing list] to provide feedback or suggestions in other ways.
+Feel free to use the {url-project-issues}[issue tracker] or {url-project-list}[Asciidoctor mailing list] to provide feedback or suggestions in other ways.
 
 == Development
 
@@ -967,7 +967,7 @@ You can retrieve the source of {project-name} in one of two ways:
 
 ==== Option 1: Fetch Using Git
 
-If you want to clone the git repository, simply copy the {uri-project-repo}[GitHub repository URL] and pass it to the `git clone` command:
+If you want to clone the git repository, simply copy the {url-project-repo}[GitHub repository URL] and pass it to the `git clone` command:
 
  $ git clone https://github.com/asciidoctor/asciidoctor-pdf
 
@@ -986,7 +986,7 @@ We'll leverage the project configuration to install the necessary dependencies.
 
 === Install Dependencies
 
-If you're using {uri-rvm}[RVM], we recommend creating a new gemset to work with {project-name}:
+If you're using {url-rvm}[RVM], we recommend creating a new gemset to work with {project-name}:
 
  $ rvm use 2.5@asciidoctor-pdf --create
 

data/docs/theming-guide.adoc

@@ -22,6 +22,7 @@ ifndef::icons[:conum-guard-yaml: # #]
 ifdef::backend-pdf[:conum-guard-yaml: # #]
 :url-fontforge: https://fontforge.github.io/en-US/
 :url-fontforge-scripting: https://fontforge.github.io/en-US/documentation/scripting/
+:url-prawn: http://prawnpdf.org
 
 ////
 Topics remaining to document:
@@ -734,7 +735,7 @@ Cannot be styled as italic, bold or bold_italic.
 Used as the fallback font in the `default-with-fallback-font` theme.
 
 TIP: If you want to specify the location of custom fonts using the `pdf-fontsdir` attribute, yet still be able to use the bundled fonts, you need to refer to the bundled fonts using the `GEM_FONTS_DIR` token.
-To do so, you can either a) prefix the path of the bundled font in the theme file with the segment `GEM_FONTS_DIR` (e.g., `GEM_FONTS_DIR/mplus1p-regular-fallback.ttf`, or b) include `GEM_FONT_DIR` in the value of the `pdf-fontsdir` attribute, separated from the location of your custom fonts by a semi-colon (e.g., `path/to/your/fonts;GEM_FONTS_DIR`).
+To do so, you can either a) prefix the path of the bundled font in the theme file with the segment `GEM_FONTS_DIR` (e.g., `GEM_FONTS_DIR/mplus1p-regular-fallback.ttf`, or b) use relative paths in the theme file and include `GEM_FONT_DIR` in the value of the `pdf-fontsdir` attribute separated by the location of your custom fonts using a semi-colon (e.g., `"path/to/your/fonts;GEM_FONTS_DIR"`).
 
 === Custom Fonts
 
@@ -749,11 +750,13 @@ A collection typically consists of all four font styles:
 * bold
 * bold_italic
 
-You'll need all four styles to support AsciiDoc content properly.
+You'll need all four variants to support AsciiDoc content properly.
+Otherwise, the converter will likely crash.
+If you don't have one of the variants, you can simply reuse the normal variant in its place.
 _Asciidoctor PDF cannot italicize a font dynamically like a browser can, so the italic styles are required._
 
 In order for a third-party font to work properly with Prawn (and hence Asciidoctor PDF), several modifications are required.
-See <<Prepare a Custom Font>> to learn how to prepare your font for use with Asciidoctor PDF.
+See <<Preparing a Custom Font>> to learn how to prepare your font for use with Asciidoctor PDF.
 
 Once you've obtained the TTF files, put them in the directory inside your project where you want to store the fonts.
 It's recommended that you name them consistently so it's easier to type the names in the theme file.
@@ -779,6 +782,9 @@ font:
       bold_italic: roboto-bold_italic.ttf
 ----
 
+CAUTION: You must declare all four variants.
+If you're missing the font file for one of the variants, configure it to use the same font file as the normal variant.
+
 You can use the key that you assign to the font in the font catalog anywhere the `font-family` property is accepted in the theme file.
 For example, to use the Roboto font for all headings, use:
 
@@ -792,13 +798,17 @@ When you execute Asciidoctor PDF, specify the directory where the fonts reside u
 
  $ asciidoctor-pdf -a pdf-theme=basic-theme.yml -a pdf-fontsdir=path/to/fonts document.adoc
 
-You can specify multiple directories by separating the entries with a semi-colon:
+You can specify multiple directories by separating the entries with a semi-colon and enclosing the value in double quotes:
 
- $ asciidoctor-pdf -a pdf-theme=basic-theme.yml -a pdf-fontsdir=path/to/fonts;path/to/more-fonts document.adoc
+ $ asciidoctor-pdf -a pdf-theme=basic-theme.yml -a pdf-fontsdir="path/to/fonts;path/to/more-fonts" document.adoc
 
 To include the bundled fonts in the search, use the `GEM_FONTS_DIR` token:
 
- $ asciidoctor-pdf -a pdf-theme=basic-theme.yml -a pdf-fontsdir=path/to/fonts;GEM_FONTS_DIR document.adoc
+ $ asciidoctor-pdf -a pdf-theme=basic-theme.yml -a pdf-fontsdir="path/to/fonts;GEM_FONTS_DIR" document.adoc
+
+When running Asciidoctor PDF on the JVM (perhaps using AsciidoctorJ PDF), you can refer a directory inside of any JAR file on the classpath by prefixing the path with `uri:classloader:`:
+
+ $ asciidoctorj -b pdf -a pdf-theme=basic-theme.yml -a pdf-fontsdir="uri:classloader:/path/to/fonts;GEM_FONTS_DIR" document.adoc
 
 TIP: When Asciidoctor PDF creates the PDF, it only embeds the glyphs from the font that are needed to render the characters present in the document.
 Effectively, it subsets the font.
@@ -941,6 +951,11 @@ If the filename is absolute, it's used as is.
 If the filename begins with `./`, it's resolved as a theme file relative to the current theme file.
 Otherwise, the filename is resolved as a theme file in the normal way (relative to the value of the `pdf-themesdir` attribute).
 
+CAUTION: If you define the <<Custom fonts,font catalog>> in a theme that extends from `default`, you *must* redeclare any built-in font that on which the combined theme depends.
+You can find those definitions in default theme.
+You'll then need to include `GEM_FONTS_DIR` in the value of the `pdf-fontsdir` attribute so that the converter can find and register them.
+To avoid having to do this, make sure you set the font family for any element that declares a font family in the default theme.
+
 Currently, the base theme is always loaded first.
 Then, the files referenced by the extends key are loaded in order.
 Finally, the keys in the current file are loaded.
@@ -963,7 +978,7 @@ Each time a theme is loaded, the keys are overlaid onto the keys from the previo
 
 The keys in the `role` category define custom roles for formatting.
 The name of the role is the first subkey level.
-The role name may not contain a hyphen or underscore.
+The role name may not contain an underscore.
 The keys under the role are the concrete theming properties.
 
 Here's an example of a role for making text red:
@@ -998,6 +1013,41 @@ You'll need to define these in your theme if you'd like to make use of them when
 
 3+|[#key-prefix-role]*Key Prefix:* <<key-prefix-role,role-<name>{zwsp}>>
 
+|background-color
+|<<colors,Color>> +
+(default: _not set_)
+|role:
+  highlight:
+    background-color: #ffff00
+
+|border-color
+|<<colors,Color>> +
+(default: _not set_)
+|role:
+  found:
+    border-color: #cccccc
+
+|border-offset
+|<<values,Number>> +
+(default: 0)
+|role:
+  found:
+    border-offset: 2
+
+|border-radius
+|<<values,Number>> +
+(default: _not set_)
+|role:
+  found:
+    border-radius: 3
+
+|border-width
+|<<values,Number>> +
+(default: _not set_)
+|role:
+  found:
+    border-width: 0.5
+
 |font-color
 |<<colors,Color>> +
 (default: _inherit_)
@@ -4078,6 +4128,7 @@ If `pdf-theme` ends with `.yml`, and `pdf-themesdir` is not specified, then `pdf
 
 pdf-fontsdir:: The directory or directories where the fonts used by your theme, if any, are located.
 Multiple entries must be separated by a semi-colon.
+To reference a file inside a JAR file on the classpath, prefix with the path with `uri:classloader:` (AsciidoctorJ only).
 _Specifying an absolute path is recommended._
 
 Let's assume that you've put your theme files inside a directory named `resources` with the following layout:
@@ -4120,6 +4171,8 @@ The only thing you need to add to an existing build is the attributes mentioned
 * https://github.com/asciidoctor/asciidoctor-maven-examples/tree/master/asciidoctor-pdf-with-theme-example[Maven Example]
 * https://github.com/asciidoctor/asciidoctor-gradle-examples/tree/master/asciidoc-to-pdf-with-theme-example[Gradle Example]
 
+TIP: To reference a theme file or directory of fonts inside a JAR file on the classpath, prefix the path with `uri:classloader:`.
+
 == Theme-Related Document Attributes
 
 There are various settings in the theme you control using document attributes.
@@ -4363,6 +4416,133 @@ For more information about source highlighting with Rouge, refer to the http://r
 * http://www.sitepoint.com/hackable-pdf-typesetting-in-ruby-with-prawn[Hackable PDF typesetting in Ruby with Prawn]
 ////
 
+== Extending the Converter
+
+This converter uses {url-prawn}[Prawn] under the covers to generate the PDF.
+Prawn is a low-level PDF writer that can load fonts, ink text, embed images, add graphics, and draw lines.
+With those operations alone, this converter manages to produce a PDF from an AsciiDoc document.
+This section explains the role of theming in this process and how to extend the converter to take it further.
+
+=== Going Beyond Theming
+
+While creating the PDF document, there are thousands of small decisions the converter must make about how to instruct Prawn to layout the content elements on the page (so-called "`hackable typesetting`").
+But once these elements are written, they can't be moved or styled (as is the case with HTML and CSS).
+To help influence those decisions--and thus prevent the converter from becoming too opinionated, a theming system was introduced.
+That theming system is described in this document.
+
+The theme support is there to provide basic customizations (fonts, colors, borders, spacing, etc.).
+But it can only go so far.
+At some point, it becomes necessary to extend the converter to meet advanced design requirements.
+
+Before you dive into extending this converter, you'll need to understand how to use Prawn.
+The article https://www.sitepoint.com/hackable-pdf-typesetting-in-ruby-with-prawn/[Hackable PDF Typesetting in Ruby with Prawn] gives a crash course in how to create your first PDF document containing text, graphics, and images with Prawn.
+That article is essential reading for working with Asciidoctor PDF, which uses many of the same operations (as well as many helpful add-ons).
+Once you feel comfortable with Prawn, you're ready to extend the converter.
+
+=== Tailoring Conversion
+
+The methods on a converter class that handle conversion follow the pattern `convert_<name>` for block elements (e.g., `convert_example`) and `convert_inline_<name>` for inline elements (e.g., `convert_inline_anchor`), where `<name>` is the name of the element.
+
+When you override a block element, you write PDF objects directly to the Prawn Document (the current context).
+When you override an inline element, you return pseudo-HTML, which is then parsed and converted into PDF objects.
+
+The pseudo-HTML in Asciidoctor PDF evolved from the inline formatting in Prawn, now supporting the following elements: a, br, button, code, color, del, em, font, img, key, mark, span, strong, sub, sup.
+All decimal and hexadecimal character references are supported, as well as the named entities amp, apos, gt, lt, nbsp, and quot (e.g., `\&apos;`.
+You can change the font color using `rgb` attribue on the `color` element (e.g., `<color rgb="#ff0000">`) and the font family and size using `name` and `size` attributes on the `font` element, respectively (e.g., `<font name="sans" size="12">`).
+You can also use the `style` attribute on `span` to control the font color, weight, and style using the relevant CSS property names.
+The pseudo-HTML in Asciidoctor PDF also supports the `class` attribute on any element for applying roles from the theme.
+(Though not recommended, you can pass this pseudo-HTML straight through to Prawn using an inline passthrough in AsciiDoc).
+
+=== Defining the Extended Converter
+
+Starting with Asciidoctor 2, defining an extending converter and registering it in place of the original is very straightforward.
+
+.custom-pdf-converter.rb
+[source,ruby]
+----
+class CustomPDFConverter < (Asciidoctor::Converter.for 'pdf')
+  register_for 'pdf'
+
+  # overrides go here
+end
+----
+
+As it stands, the converter doesn't do anything differently than the primary converter because we haven't yet overridden any of its methods.
+Let's do that now, starting by overriding the thematic break (aka horizonal rule) to make it render like a ribbon:
+
+[source,ruby]
+----
+  def convert_thematic_break node
+    theme_margin :thematic_break, :top
+    stroke_horizontal_rule 'FF0000', line_width: 0.5, line_style: :solid
+    move_down 1
+    stroke_horizontal_rule 'FF0000', line_width: 1, line_style: :solid
+    move_down 1
+    stroke_horizontal_rule 'FF0000', line_width: 0.5, line_style: :solid
+    theme_margin :thematic_break, :bottom
+  end
+----
+
+This converter will replace the thematic break with a red ribbon.
+
+Another way to override the converter is to modify the node, then delegate back to the primary converter.
+Let's put a page break before all paragraphs unless the cursor is at the top of the page.
+We'll call `super` to let the primary converter handle the work of rendering the paragraph.
+
+[source,ruby]
+----
+  def convert_paragraph node
+    bounds.move_past_bottom unless at_page_top?
+    super
+  end
+----
+
+Now let's look at how to modify an inline element.
+Let's say we want to override the kbd element.
+
+[source,ruby]
+----
+  def convert_inline_kbd node
+    %(<strong><color rgb="AA0000">#{(node.attr 'keys').join ' + '}</color></strong>)
+  end
+----
+
+Refer to the primary converter to discover the pseudo-HTML you can use for inline elements.
+
+So far we've just been biting around the edges.
+A more realistic use case is to customize the part title page in a multi-part book.
+Since this is a specialized section element, there's a dedicated method named `layout_part_title` that you'll need to override.
+
+Let's customize the part title page by making the background orange, making the font white, centering the title on the page, and disabling the running content.
+(You don't need to start a new page before and after the part title since that's already done for you).
+
+[source,ruby]
+----
+  def layout_part_title node, title, opts = {}
+    fill_absolute_bounds 'E64C3D'
+    move_down 20
+    typeset_text title, (calc_line_metrics 1.5), color: 'FFFFFF', inline_format: true, align: :center, size: 42
+    page.instance_variable_set :@imported_page, true
+  end
+----
+
+The method `typeset_text` and `calc_line_metrics` are provided by Asciidoctor PDF to make writing text easier.
+If you wanted, you could just use the low-level `text` method provided by Prawn.
+
+To find all the available methods to override, consult the https://www.rubydoc.info/github/asciidoctor/asciidoctor-pdf/Asciidoctor/Pdf/Converter[API docs].
+For deeper examples of how to override the behavior of the converter, refer to the extended converter in the https://github.com/mraible/infoq-mini-book/blob/master/src/main/ruby/asciidoctor-pdf-extensions.rb[InfoQ Mini-Book template].
+
+Now that you've seen some examples of how to extend the converter, let's look at how to use it.
+
+=== Using the Extended Converter
+
+To use this converter, register it by passing the path to the `-r` flag when calling the `asciidoctor-pdf` command:
+
+ $ asciidoctor-pdf -r ./custom-pdf-converter.rb document.adoc
+
+That's all there is too it.
+Now you're hacking the typesetting!
+
 [appendix]
 == Preparing a Custom Font
 

data/lib/asciidoctor-pdf/converter.rb

@@ -103,6 +103,7 @@ class Converter < ::Prawn::Document
   BlankLineRx = /\n{2,}/
   CjkLineBreakRx = /(?=[\u3000\u30a0-\u30ff\u3040-\u309f\p{Han}\uff00-\uffef])/
   WhitespaceChars = ' ' + TAB + LF
+  ValueSeparatorRx = /;|,/
   SourceHighlighters = ['coderay', 'pygments', 'rouge'].to_set
   PygmentsBgColorRx = /^\.highlight +{ *background: *#([^;]+);/
   ViewportWidth = ::Module.new
@@ -184,13 +185,15 @@ class Converter < ::Prawn::Document
 
     on_page_create &(method :init_page)
 
+    marked_page_number = page_number
+    # NOTE a new page will already be started (page_number = 2) if the front cover image is a PDF
     layout_cover_page doc, :front
-    if (insert_title_page = doc.doctype == 'book' || (doc.attr? 'title-page'))
+    has_front_cover = page_number > marked_page_number
+    if (use_title_page = doc.doctype == 'book' || (doc.attr? 'title-page'))
       layout_title_page doc
-      # NOTE a new page will already be started if the cover image is a PDF
       start_new_page unless page.empty?
+      has_title_page = page_number == (has_front_cover ? 3 : 2)
     else
-      # NOTE a new page will already be started if the cover image is a PDF
       start_new_page unless page.empty?
       body_start_page_number = page_number
       if doc.header? && !doc.notitle
@@ -214,11 +217,11 @@ class Converter < ::Prawn::Document
         indent 0, pagenum_width do
           toc_page_nums = layout_toc doc, num_toc_levels, toc_page_nums, 0, toc_start
         end
-        move_down @theme.block_margin_bottom unless insert_title_page
+        move_down @theme.block_margin_bottom unless use_title_page
         toc_end = @y
       end
       # NOTE reserve pages for the toc; leaves cursor on page after last page in toc
-      if insert_title_page
+      if use_title_page
         toc_page_nums.each { start_new_page }
       else
         (toc_page_nums.first...toc_page_nums.last).each { start_new_page }
@@ -228,25 +231,27 @@ class Converter < ::Prawn::Document
 
     start_new_page if @ppbook && verso_page?
 
-    if insert_title_page
+    if use_title_page
+      zero_page_offset = has_front_cover ? 1 : 0
+      first_page_offset = has_title_page ? zero_page_offset.next : zero_page_offset
       body_offset = (body_start_page_number = page_number) - 1
-      front_matter_sig = [@theme.running_content_start_at || 'body', @theme.page_numbering_start_at || 'body', insert_toc]
-      # NOTE start running content from title or toc, if specified (default: body)
+      running_content_start_at = @theme.running_content_start_at || 'body'
+      running_content_start_at = 'toc' if running_content_start_at == 'title' && !has_title_page
+      running_content_start_at = 'body' if running_content_start_at == 'toc' && !insert_toc
+      page_numbering_start_at = @theme.page_numbering_start_at || 'body'
+      page_numbering_start_at = 'toc' if page_numbering_start_at == 'title' && !has_title_page
+      page_numbering_start_at = 'body' if page_numbering_start_at == 'toc' && !insert_toc
+      front_matter_sig = [running_content_start_at, page_numbering_start_at]
+      # table values are number of pages to skip before starting running content and page numbering, respectively
       num_front_matter_pages = {
-        ['title', 'title', true] => [0, 0],
-        ['title', 'title', false] => [0, 0],
-        ['title', 'toc', true] => [0, 1],
-        ['title', 'toc', false] => [0, 1],
-        ['title', 'body', true] => [0, body_offset],
-        ['title', 'body', false] => [0, 1],
-        ['toc', 'title', true] => [1, 0],
-        ['toc', 'title', false] => [1, 0],
-        ['toc', 'toc', true] => [1, 1],
-        ['toc', 'toc', false] => [1, 1],
-        ['toc', 'body', true] => [1, body_offset],
-        ['body', 'title', true] => [body_offset, 0],
-        ['body', 'title', false] => [1, 0],
-        ['body', 'toc', true] => [body_offset, 1],
+        ['title', 'title'] => [zero_page_offset, zero_page_offset],
+        ['title', 'toc'] => [zero_page_offset, first_page_offset],
+        ['title', 'body'] => [zero_page_offset, body_offset],
+        ['toc', 'title'] => [first_page_offset, zero_page_offset],
+        ['toc', 'toc'] => [first_page_offset, first_page_offset],
+        ['toc', 'body'] => [first_page_offset, body_offset],
+        ['body', 'title'] => [body_offset, zero_page_offset],
+        ['body', 'toc'] => [body_offset, first_page_offset],
       }[front_matter_sig] || [body_offset, body_offset]
     else
       # Q: what if there's only a toc page, but not title?
@@ -279,7 +284,7 @@ class Converter < ::Prawn::Document
       end
     end
 
-    add_outline doc, (doc.attr 'outlinelevels', num_toc_levels), toc_page_nums, num_front_matter_pages[1]
+    add_outline doc, (doc.attr 'outlinelevels', num_toc_levels), toc_page_nums, num_front_matter_pages[1], has_front_cover
     if state.pages.size > 0 && (initial_zoom = @theme.page_initial_zoom)
       case initial_zoom.to_sym
       when :Fit
@@ -1078,7 +1083,7 @@ class Converter < ::Prawn::Document
     end
 
     indent marker_width do
-      convert_content_for_list_item node, :colist, margin_bottom: @theme.outline_list_item_spacing
+      convert_content_for_list_item node, :colist, margin_bottom: @theme.outline_list_item_spacing, normalize_line_height: true
     end
   end
 
@@ -1113,10 +1118,10 @@ class Converter < ::Prawn::Document
           else
             term_text = term.text
           end
-          layout_prose term_text, margin_top: 0, margin_bottom: @theme.description_list_term_spacing, align: :left
+          layout_prose term_text, margin_top: 0, margin_bottom: @theme.description_list_term_spacing, align: :left, normalize_line_height: true
         end
         indent(@theme.description_list_description_indent || 0) do
-          convert_content_for_list_item desc, :dlist_desc
+          convert_content_for_list_item desc, :dlist_desc, normalize_line_height: true
         end if desc
       end
     end
@@ -1313,16 +1318,16 @@ class Converter < ::Prawn::Document
     end
 
     if complex
-      convert_content_for_list_item node, list_type, opts
+      convert_content_for_list_item node, list_type, (opts.merge normalize_line_height: true)
     else
-      convert_content_for_list_item node, list_type, (opts.merge margin_bottom: @theme.outline_list_item_spacing)
+      convert_content_for_list_item node, list_type, (opts.merge margin_bottom: @theme.outline_list_item_spacing, normalize_line_height: true)
     end
   end
 
   def convert_content_for_list_item node, list_type, opts = {}
     if list_type == :dlist # qanda
       terms, desc = node
-      [*terms].each {|term| layout_prose %(<em>#{term.text}</em>), opts }
+      [*terms].each {|term| layout_prose %(<em>#{term.text}</em>), (opts.merge margin_top: 0, margin_bottom: @theme.description_list_term_spacing) }
       if desc
         layout_prose desc.text, opts if desc.text?
         convert_content_for_block desc
@@ -1608,17 +1613,14 @@ class Converter < ::Prawn::Document
         else
           subs.delete_all :specialcharacters, :callouts
         end
-        # the indent guard will be added by the source highlighter logic
-        source_string = node.content || ''
+        # NOTE indentation guards will be added by the source highlighter logic
+        source_string = expand_tabs node.content
       end
     else
       highlighter = nil
-      prev_subs = nil
       source_string = guard_indentation node.content
     end
 
-    bg_color_override = nil
-
     source_chunks = case highlighter
     when 'coderay'
       source_string, conum_mapping = extract_conums source_string
@@ -2239,7 +2241,7 @@ class Converter < ::Prawn::Document
       end
       text = %(#{text}, #{pagenums.join ', '})
     end
-    layout_prose text, align: :left, margin: 0
+    layout_prose text, align: :left, margin: 0, normalize_line_height: true
 
     term.subterms.each do |subterm|
       indent @theme.description_list_description_indent do
@@ -2703,6 +2705,7 @@ class Converter < ::Prawn::Document
       string = %(<a anchor="#{anchor}">#{string}</a>)
     end
     margin_top top_margin
+    string = ZeroWidthSpace + string if opts.delete :normalize_line_height
     typeset_text string, calc_line_metrics((opts.delete :line_height) || @theme.base_line_height), {
       color: @font_color,
       # NOTE normalize makes endlines soft (replaces "\n" with ' ')
@@ -2751,7 +2754,8 @@ class Converter < ::Prawn::Document
         margin_top: margin[:top],
         margin_bottom: margin[:bottom],
         align: (@theme.caption_align || @base_align).to_sym,
-        normalize: false
+        normalize: false,
+        normalize_line_height: true
       }.merge(opts)
       if side == :top && @theme.caption_border_bottom_color
         stroke_horizontal_rule @theme.caption_border_bottom_color
@@ -2833,7 +2837,7 @@ class Converter < ::Prawn::Document
     end
     sections.each do |sect|
       theme_font :toc, level: (sect.level + 1) do
-        sect_title = @text_transform ? (transform_text sect.numbered_title, @text_transform) : sect.numbered_title
+        sect_title = ZeroWidthSpace + (@text_transform ? (transform_text sect.numbered_title, @text_transform) : sect.numbered_title)
         # NOTE only write section title (excluding dots and page number) if this is a dry run
         if scratch?
           # FIXME use layout_prose
@@ -3255,7 +3259,7 @@ class Converter < ::Prawn::Document
     end
   end
 
-  def add_outline doc, num_levels = 2, toc_page_nums = [], num_front_matter_pages = 0
+  def add_outline doc, num_levels = 2, toc_page_nums = [], num_front_matter_pages = 0, has_front_cover = false
     if ::String === num_levels
       if num_levels.include? ':'
         num_levels, expand_levels = num_levels.split ':', 2
@@ -3281,9 +3285,8 @@ class Converter < ::Prawn::Document
 
     outline.define do
       # FIXME use sanitize: :plain_text once available
-      if (doctitle = document.sanitize(doc.doctitle use_fallback: true))
-        # FIXME link to title page if there's a cover page (skip cover page and ensure blank page)
-        page title: doctitle, destination: (document.dest_top 1)
+      if (doctitle = document.sanitize(doc.doctitle use_fallback: true)) && document.page_count > (has_front_cover ? 2 : 1)
+        page title: doctitle, destination: (document.dest_top has_front_cover ? 2 : 1)
       end
       unless toc_page_nums.none? || (toc_title = doc.attr 'toc-title').nil_or_empty?
         page title: toc_title, destination: (document.dest_top toc_page_nums.first)
@@ -3328,7 +3331,7 @@ class Converter < ::Prawn::Document
 
   def register_fonts font_catalog, fonts_dir
     return unless font_catalog
-    dirs = (fonts_dir.split ';', -1).map do |dir|
+    dirs = (fonts_dir.split ValueSeparatorRx, -1).map do |dir|
       dir == 'GEM_FONTS_DIR' || dir.empty? ? ThemeLoader::FontsDir : dir
     end
     font_catalog.each do |key, styles|
@@ -3572,14 +3575,65 @@ class Converter < ::Prawn::Document
     (height_of string, leading: line_metrics.leading, final_gap: line_metrics.final_gap) + line_metrics.padding_top + line_metrics.padding_bottom
   end
 
+  # NOTE only used when tabsize attribute is not specified
+  # tabs must always be replaced with spaces in order for the indentation guards to work
+  def expand_tabs string
+    if string.nil_or_empty?
+      ''
+    elsif string.include? TAB
+      full_tab_space = ' ' * (tab_size = 4)
+      (string.split LF, -1).map do |line|
+        if line.empty?
+          line
+        elsif (tab_idx = line.index TAB)
+          if tab_idx == 0
+            leading_tabs = 0
+            line.each_byte do |b|
+              break unless b == 9
+              leading_tabs += 1
+            end
+            line = %(#{full_tab_space * leading_tabs}#{rest = line.slice leading_tabs, line.length})
+            next line unless rest.include? TAB
+          end
+          # keeps track of how many spaces were added to adjust offset in match data
+          spaces_added = 0
+          idx = 0
+          result = ''
+          line.each_char do |c|
+            if c == TAB
+              # calculate how many spaces this tab represents, then replace tab with spaces
+              if (offset = idx + spaces_added) % tab_size == 0
+                spaces_added += (tab_size - 1)
+                result = result + full_tab_space
+              else
+                unless (spaces = tab_size - offset % tab_size) == 1
+                  spaces_added += (spaces - 1)
+                end
+                result = result + (' ' * spaces)
+              end
+            else
+              result = result + c
+            end
+            idx += 1
+          end
+          result
+        else
+          line
+        end
+      end.join LF
+    else
+      string
+    end
+  end
+
+  # Add an indentation guard at the start of indented lines.
+  # Expand tabs to spaces if tabs are present
   def guard_indentation string
-    if string
+    unless (string = expand_tabs string).empty?
       string[0] = GuardedIndent if string.start_with? ' '
       string.gsub! InnerIndent, GuardedInnerIndent if string.include? InnerIndent
-      string
-    else
-      ''
     end
+    string
   end
 
   def guard_indentation_in_fragments fragments

data/lib/asciidoctor-pdf/formatted_text/transform.rb

@@ -121,8 +121,7 @@ class Transform
   end
 
   # FIXME pass styles downwards to child elements rather than decorating on way out of hierarchy
-  def apply(parsed)
-    fragments = []
+  def apply(parsed, fragments = [], inherited = nil)
     previous_fragment_is_text = false
     # NOTE we use each since using inject is slower than a manual loop
     parsed.each do |node|
@@ -133,14 +132,16 @@ class Transform
           unless (pcdata = node[:pcdata]).empty?
             tag_name = node[:name]
             attributes = node[:attributes]
-            # NOTE decorate child fragments with styles from this element
-            fragments << apply(pcdata).map {|fragment| build_fragment(fragment, tag_name, attributes) }
+            parent = clone_fragment inherited
+            # NOTE decorate child fragments with inherited properties from this element
+            apply(pcdata, fragments, (build_fragment parent, tag_name, attributes))
             previous_fragment_is_text = false
           # NOTE skip element if it has no children
           #else
           #  # NOTE handle an empty anchor element (i.e., <a ...></a>)
           #  if (tag_name = node[:name]) == :a
-          #    fragments << build_fragment({ text: DummyText }, tag_name, node[:attributes])
+          #    seed = clone_fragment inherited, text: DummyText
+          #    fragments << build_fragment(seed, tag_name, node[:attributes])
           #    previous_fragment_is_text = false
           #  end
           end
@@ -149,7 +150,7 @@ class Transform
           case node[:name]
           when :br
             if @merge_adjacent_text_nodes && previous_fragment_is_text
-              fragments << { text: %(#{fragments.pop[:text]}#{LF}) }
+              fragments << (clone_fragment inherited, text: %(#{fragments.pop[:text]}#{LF}))
             else
               fragments << { text: LF }
             end
@@ -163,6 +164,9 @@ class Transform
               text: (attributes[:alt].delete ZeroWidthSpace),
               callback: [InlineImageRenderer],
             }
+            if inherited && (link = inherited[:link])
+              fragment[:link] = link
+            end
             if (img_w = attributes[:width])
               fragment[:image_width] = img_w
             end
@@ -172,9 +176,9 @@ class Transform
         end
       when :text
         if @merge_adjacent_text_nodes && previous_fragment_is_text
-          fragments << { text: %(#{fragments.pop[:text]}#{node[:value]}) }
+          fragments << (clone_fragment inherited, text: %(#{fragments.pop[:text]}#{node[:value]}))
         else
-          fragments << { text: node[:value] }
+          fragments << (clone_fragment inherited, text: node[:value])
         end
         previous_fragment_is_text = true
       when :charref
@@ -188,14 +192,14 @@ class Transform
           text = [(node[:value].to_i 16)].pack('U1')
         end
         if @merge_adjacent_text_nodes && previous_fragment_is_text
-          fragments << { text: %(#{fragments.pop[:text]}#{text}) }
+          fragments << (clone_fragment inherited, text: %(#{fragments.pop[:text]}#{text}))
         else
-          fragments << { text: text }
+          fragments << (clone_fragment inherited, text: text)
         end
         previous_fragment_is_text = true
       end
     end
-    fragments.flatten
+    fragments
   end
 
   def build_fragment(fragment, tag_name, attrs = {})
@@ -206,39 +210,36 @@ class Transform
     when :em
       styles << :italic
     when :button, :code, :key, :mark
-      # NOTE prefer old value, except for styles and callback, which should be combined
-      fragment.update(@theme_settings[tag_name]) {|k, oval, nval| k == :styles ? oval.merge(nval) : (k == :callback ? oval.union(nval) : oval) }
+      fragment.update(@theme_settings[tag_name]) {|k, oval, nval| k == :styles ? oval.merge(nval) : (k == :callback ? oval.union(nval) : nval) }
     when :color
-      if !fragment[:color]
-        if (rgb = attrs[:rgb])
-          case rgb.chr
-          when '#'
-            fragment[:color] = rgb[1..-1]
-          when '['
-            # treat value as CMYK array (e.g., "[50, 100, 0, 0]")
-            fragment[:color] = rgb[1..-1].chomp(']').split(', ').map(&:to_i)
-            # ...or we could honor an rgb array too
-            #case (vals = rgb[1..-1].chomp(']').split(', ')).size
-            #when 4
-            #  fragment[:color] = vals.map(&:to_i)
-            #when 3
-            #  fragment[:color] = vals.map {|e| '%02X' % e.to_i }.join
-            #end
-          else
-            fragment[:color] = rgb
-          end
-        # QUESTION should we even support r,g,b and c,m,y,k as individual values?
-        elsif (r_val = attrs[:r]) && (g_val = attrs[:g]) && (b_val = attrs[:b])
-          fragment[:color] = [r_val, g_val, b_val].map {|e| '%02X' % e.to_i }.join
-        elsif (c_val = attrs[:c]) && (m_val = attrs[:m]) && (y_val = attrs[:y]) && (k_val = attrs[:k])
-          fragment[:color] = [c_val.to_i, m_val.to_i, y_val.to_i, k_val.to_i]
+      if (rgb = attrs[:rgb])
+        case rgb.chr
+        when '#'
+          fragment[:color] = rgb[1..-1]
+        when '['
+          # treat value as CMYK array (e.g., "[50, 100, 0, 0]")
+          fragment[:color] = rgb[1..-1].chomp(']').split(', ').map(&:to_i)
+          # ...or we could honor an rgb array too
+          #case (vals = rgb[1..-1].chomp(']').split(', ')).size
+          #when 4
+          #  fragment[:color] = vals.map(&:to_i)
+          #when 3
+          #  fragment[:color] = vals.map {|e| '%02X' % e.to_i }.join
+          #end
+        else
+          fragment[:color] = rgb
         end
+      # QUESTION should we even support r,g,b and c,m,y,k as individual values?
+      elsif (r_val = attrs[:r]) && (g_val = attrs[:g]) && (b_val = attrs[:b])
+        fragment[:color] = [r_val, g_val, b_val].map {|e| '%02X' % e.to_i }.join
+      elsif (c_val = attrs[:c]) && (m_val = attrs[:m]) && (y_val = attrs[:y]) && (k_val = attrs[:k])
+        fragment[:color] = [c_val.to_i, m_val.to_i, y_val.to_i, k_val.to_i]
       end
     when :font
-      if !fragment[:font] && (value = attrs[:name])
+      if (value = attrs[:name])
         fragment[:font] = value
       end
-      if !fragment[:size] && (value = attrs[:size])
+      if (value = attrs[:size])
         # FIXME can we make this comparison more robust / accurate?
         if %(#{f_value = value.to_f}) == value || %(#{value.to_i}) == value
           fragment[:size] = f_value
@@ -250,10 +251,10 @@ class Transform
         fragment[:width] = value
         if (value = attrs[:align])
           fragment[:align] = value.to_sym
-          (fragment[:callback] ||= []) << InlineTextAligner
+          fragment[:callback] = ((fragment[:callback] ||= []) << InlineTextAligner).uniq
         end
       end
-      #if !fragment[:character_spacing] && (value = attrs[:character_spacing])
+      #if (value = attrs[:character_spacing])
       #  fragment[:character_spacing] = value.to_f
       #end
     when :a
@@ -273,12 +274,11 @@ class Transform
           if (type = attrs[:type])
             fragment[:type] = type.to_sym
           end
-          (fragment[:callback] ||= []) << InlineDestinationMarker
+          fragment[:callback] = ((fragment[:callback] ||= []) << InlineDestinationMarker).uniq
           visible = false
         end
       end
-      # NOTE prefer old value, except for styles, which should be combined
-      fragment.update(@theme_settings[:link]) {|k, oval, nval| k == :styles ? oval.merge(nval) : oval } if visible
+      fragment.update(@theme_settings[:link]) {|k, oval, nval| k == :styles ? oval.merge(nval) : nval } if visible
     when :sub
       styles << :subscript
     when :sup
@@ -325,9 +325,9 @@ class Transform
       when 'line-through'
         styles << :strikethrough
       else
-        fragment.update(@theme_settings[class_name]) {|k, oval, nval| k == :styles ? oval.merge(nval) : oval } if @theme_settings.key? class_name
+        fragment.update(@theme_settings[class_name]) {|k, oval, nval| k == :styles ? oval.merge(nval) : nval } if @theme_settings.key? class_name
         if fragment[:background_color] || (fragment[:border_color] && fragment[:border_width])
-          ((fragment[:callback] ||= []) << TextBackgroundAndBorderRenderer).uniq!
+          fragment[:callback] = ((fragment[:callback] || []) << TextBackgroundAndBorderRenderer).uniq
         end 
       end
     end if attrs.key?(:class)
@@ -335,6 +335,18 @@ class Transform
     fragment
   end
 
+  def clone_fragment fragment, append = nil
+    if fragment
+      fragment = fragment.dup
+      fragment[:styles] = fragment[:styles].dup if fragment.key? :styles
+      fragment[:callback] = fragment[:callback].dup if fragment.key? :callback
+    else
+      fragment = {}
+    end
+    fragment.update append if append
+    fragment
+  end
+
   def to_styles(font_style, text_decoration = nil)
     case font_style
     when 'bold'

data/lib/asciidoctor-pdf/theme_loader.rb

@@ -48,7 +48,7 @@ class ThemeLoader
       if theme_dir
         theme_path = ::File.absolute_path theme_name, (theme_dir = ::File.expand_path theme_dir)
       else
-        theme_dir = ::File.dirname(theme_path = (::File.absolute_path theme_name))
+        theme_dir = ::File.dirname(theme_path = (::File.expand_path theme_name))
       end
     else
       theme_dir = theme_dir ? (::File.expand_path theme_dir) : ThemesDir

data/lib/asciidoctor-pdf/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 module Asciidoctor
 module PDF
-  VERSION = '1.5.0.beta.4'
+  VERSION = '1.5.0.beta.5'
 end
 Pdf = PDF unless const_defined? :Pdf, false
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asciidoctor-pdf
 version: !ruby/object:Gem::Version
-  version: 1.5.0.beta.4
+  version: 1.5.0.beta.5
 platform: ruby
 authors:
 - Dan Allen
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-09-05 00:00:00.000000000 Z
+date: 2019-09-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asciidoctor