asciidoctor-pdf 1.5.0.alpha.16 → 1.5.0.alpha.17

data/asciidoctor-pdf.gemspec

@@ -1,54 +1,53 @@
-# -*- encoding: utf-8 -*-
-require File.expand_path '../lib/asciidoctor-pdf/version', __FILE__
-require 'open3' unless defined? Open3
+begin
+  require_relative 'lib/asciidoctor/pdf/version'
+rescue LoadError
+  require 'asciidoctor/pdf/version'
+end
 
 Gem::Specification.new do |s|
   s.name = 'asciidoctor-pdf'
-  s.version = Asciidoctor::Pdf::VERSION
-
-  s.summary = 'Converts AsciiDoc documents to PDF using Prawn'
-  s.description = <<-EOS
-An extension for Asciidoctor that converts AsciiDoc documents to PDF using the Prawn PDF library.
-  EOS
-
+  s.version = Asciidoctor::PDF::VERSION
+  s.summary = 'Converts AsciiDoc documents to PDF using Asciidoctor and Prawn'
+  s.description = 'An extension for Asciidoctor that converts AsciiDoc documents to PDF using the Prawn PDF library.'
   s.authors = ['Dan Allen', 'Sarah White']
   s.email = 'dan@opendevise.com'
-  s.homepage = 'https://github.com/asciidoctor/asciidoctor-pdf'
+  s.homepage = 'https://asciidoctor.org/docs/asciidoctor-pdf'
   s.license = 'MIT'
-
-  s.required_ruby_version = '>= 1.9.3'
-
-  files = begin
-    (result = Open3.popen3('git ls-files -z') {|_, out| out.read }.split %(\0)).empty? ? Dir['**/*'] : result
+  # NOTE required ruby version is informational only; it's not enforced since it can't be overridden and can cause builds to break
+  #s.required_ruby_version = '>= 2.3.0'
+  s.metadata = {
+    'bug_tracker_uri' => 'https://github.com/asciidoctor/asciidoctor-pdf/issues',
+    'changelog_uri' => 'https://github.com/asciidoctor/asciidoctor-pdf/blob/master/CHANGELOG.adoc',
+    'mailing_list_uri' => 'http://discuss.asciidoctor.org',
+    'source_code_uri' => 'https://github.com/asciidoctor/asciidoctor-pdf'
+  }
+
+  # NOTE the logic to build the list of files is designed to produce a usable package even when the git command is not available
+  begin
+    files = (result = `git ls-files -z`.split ?\0).empty? ? Dir['**/*'] : result
   rescue
-    Dir['**/*']
+    files = Dir['**/*']
   end
-  s.files = files.grep %r/^(?:(?:data|lib)\/.+|docs\/theming-guide\.adoc|Gemfile|Rakefile|(?:CHANGELOG|LICENSE|NOTICE|README)\.adoc|#{s.name}\.gemspec)$/
+  s.files = files.grep %r/^(?:(?:data|lib)\/.+|docs\/theming-guide\.adoc|(?:CHANGELOG|LICENSE|NOTICE|README)\.adoc|\.yardopts|#{s.name}\.gemspec)$/
   # FIXME optimize-pdf is currently a shell script, so listing it here won't work
-  #s.executables = ['asciidoctor-pdf', 'optimize-pdf']
+  #s.executables = (files.grep %r/^bin\//).map {|f| File.basename f }
   s.executables = ['asciidoctor-pdf']
-  s.test_files = files.grep %r/^(?:test|spec|feature)\/.*$/
-
   s.require_paths = ['lib']
-
-  s.has_rdoc = true
-  s.rdoc_options = ['--charset=UTF-8', '--title="Asciidoctor PDF"', '--main=README.adoc', '-ri']
-  s.extra_rdoc_files = ['CHANGELOG.adoc', 'LICENSE.adoc', 'NOTICE.adoc', 'README.adoc']
-
-  s.add_development_dependency 'rake'
-  #s.add_development_dependency 'rdoc', '~> 4.1.0'
-
-  s.add_runtime_dependency 'asciidoctor', '>= 1.5.0'
-  # prawn >= 2.0.0 requires Ruby >= 2.0.0, so we must cast a wider net to support Ruby 1.9.3
-  s.add_runtime_dependency 'prawn', '>= 1.3.0', '< 2.3.0'
-  s.add_runtime_dependency 'prawn-table', '0.2.2'
-  # prawn-templates >= 0.0.5 requires prawn >= 2.2.0, so we must cast a wider net to support Ruby 1.9.3
-  s.add_runtime_dependency 'prawn-templates', '>= 0.0.3', '<= 0.1.1'
-  # prawn-svg >= 0.22.1 requires Ruby >= 2.0.0, so we must cast a wider net to support Ruby 1.9.3
-  s.add_runtime_dependency 'prawn-svg', '>= 0.21.0', '< 0.28.0'
-  s.add_runtime_dependency 'prawn-icon', '1.3.0'
-  s.add_runtime_dependency 'safe_yaml', '~> 1.0.4'
-  s.add_runtime_dependency 'thread_safe', '~> 0.3.6'
-  # For our usage, treetop 1.6.2 is slower than 1.5.3
-  s.add_runtime_dependency 'treetop', '1.5.3'
+  #s.test_files = files.grep %r/^(?:test|spec|feature)\/.*$/
+
+  s.add_runtime_dependency 'asciidoctor', '>= 1.5.0', '< 3.0.0'
+  s.add_runtime_dependency 'prawn', '~> 2.2.0'
+  s.add_runtime_dependency 'prawn-table', '~> 0.2.0'
+  s.add_runtime_dependency 'prawn-templates', '~> 0.1.0'
+  s.add_runtime_dependency 'prawn-svg', '~> 0.29.0'
+  s.add_runtime_dependency 'prawn-icon', '~> 2.3.0'
+  s.add_runtime_dependency 'safe_yaml', '~> 1.0.0'
+  s.add_runtime_dependency 'thread_safe', '~> 0.3.0'
+  s.add_runtime_dependency 'concurrent-ruby', '~> 1.1.0'
+  # For our usage, treetop 1.6 is slower than treetop 1.5
+  s.add_runtime_dependency 'treetop', '~> 1.5.0'
+
+  s.add_development_dependency 'rake', '~> 12.3.0'
+  s.add_development_dependency 'rspec', '~> 3.8.0'
+  s.add_development_dependency 'pdf-inspector', '~> 1.3.0'
 end

data/bin/asciidoctor-pdf

@@ -1,9 +1,9 @@
 #!/usr/bin/env ruby
 
-if File.exist?(asciidoctor_pdf = (File.expand_path '../../lib/asciidoctor-pdf', __FILE__))
+if File.file?(asciidoctor_pdf = (File.expand_path '../../lib/asciidoctor/pdf.rb', __FILE__))
   require asciidoctor_pdf
 else
-  require 'asciidoctor-pdf'
+  require 'asciidoctor/pdf'
 end
 require 'asciidoctor/cli'
 
@@ -11,7 +11,7 @@ options = Asciidoctor::Cli::Options.new backend: 'pdf', header_footer: true
 
 # FIXME provide an API in Asciidoctor for sub-components to print version information
 unless ARGV != ['-v'] && (ARGV & ['-V', '--version']).empty?
-  $stdout.write %(Asciidoctor PDF #{Asciidoctor::Pdf::VERSION} using )
+  $stdout.write %(Asciidoctor PDF #{Asciidoctor::PDF::VERSION} using )
   # NOTE the print_version method was added in Asciidoctor 1.5.2
   if options.respond_to? :print_version
     options.print_version

data/data/themes/default-theme.yml

@@ -20,7 +20,7 @@ font:
       italic: mplus1p-regular-fallback.ttf
       bold_italic: mplus1p-regular-fallback.ttf
   fallbacks:
-    - M+ 1p Fallback
+  - M+ 1p Fallback
 page:
   background_color: ffffff
   layout: portrait
@@ -80,7 +80,7 @@ heading:
   font_color: $base_font_color
   font_family: $base_font_family
   font_style: bold
-  # h1 is used for part titles (book doctype only)
+  # h1 is used for part titles (book doctype) or the doctitle (article doctype)
   h1_font_size: floor($base_font_size * 2.6)
   # h2 is used for chapter titles (book doctype only)
   h2_font_size: floor($base_font_size * 2.15)
@@ -144,7 +144,7 @@ admonition:
   padding: [0, $horizontal_rhythm, 0, $horizontal_rhythm]
   #icon:
   #  tip:
-  #    name: fa-lightbulb-o
+  #    name: far-lightbulb
   #    stroke_color: 111111
   #    size: 24
   label:
@@ -235,6 +235,9 @@ toc:
     #content: ". "
     font_color: a9a9a9
     #levels: 2 3
+footnotes:
+  font_size: round($base_font_size * 0.75)
+  item_spacing: $outline_list_item_spacing / 2
 # NOTE in addition to footer, header is also supported
 footer:
   font_size: $base_font_size_small

data/docs/theming-guide.adoc

@@ -31,8 +31,14 @@ Topics remaining to document:
 The theming system in Asciidoctor PDF is used to control the layout and styling of the PDF file Asciidoctor PDF generates from AsciiDoc.
 This document describes how the theming system works, how to define a custom theme in YAML and how to activate the theme when running Asciidoctor PDF.
 
-IMPORTANT: If you're using a custom theme, you're expected to bring your own fonts or declare the fonts from the default theme.
-If you don't declare your own fonts, the built-in PDF (afm) fonts will be used, which only support WINANSI characters (similar to Basic Latin).
+IMPORTANT: If you're creating a custom theme, you're expected to supply your own fonts.
+We recognize this can be a major obstacle when you're starting out.
+Therefore, your other option is to simply redeclare the fonts from the https://github.com/asciidoctor/asciidoctor-pdf/blob/master/data/themes/default-theme.yml[default theme] in the <<Custom Fonts,font catalog>>.
+Asciidoctor PDF will then resolve the fonts that are bundled with the gem.
+
+WARNING: If you don't declare your own fonts, the built-in (AFM) fonts declared in https://github.com/asciidoctor/asciidoctor-pdf/blob/master/data/themes/base-theme.yml[base theme] will be used instead.
+Using AFM fonts can result in missing functionality and warnings.
+See the <<Built-In (AFM) Fonts>> section to learn more about these limitations.
 
 toc::[]
 
@@ -96,6 +102,9 @@ When creating a new theme, you only have to define the keys you want to override
 All the available keys are documented in <<Keys>>.
 The converter uses the information from the theme map to help construct the PDF.
 
+WARNING: If you start a new theme from scratch, we strongly recommend defining TrueType fonts and specifying them in the `base` and `literal` categories.
+Otherwise, Asciidoctor PDF will use built-in AFM fonts, which can result in missing functionality and warnings.
+
 [TIP]
 ====
 Instead of creating a theme from scratch, another option is to download the https://github.com/asciidoctor/asciidoctor-pdf/blob/master/data/themes/default-theme.yml[default-theme.yml] file from the source repository.
@@ -563,6 +572,8 @@ title_page:
   background_image: title-cover.png
 ----
 
+In this case, the image is resolved relative to theme directory.
+
 Here's how the image is specified using the inline image macro:
 
 [source,yaml]
@@ -571,12 +582,15 @@ title_page:
   background_image: image:title-cover.png[]
 ----
 
+In this case, the image is resolved relative to the value of the `imagesdir` attribute.
+Wrapping the value in the image macro sends a hint to the converter to resolve it just like other images.
+
 Like in the AsciiDoc syntax, the inline image macro allows you to supply set the width of the image and the alignment:
 
 [source,yaml]
 ----
 title_page:
-  logo_image: image:logo.png[width=250,align=center] 
+  logo_image: image:logo.png[width=250,align=center]
 ----
 
 === Quoted String
@@ -649,6 +663,9 @@ For anything outside of that, PDF is BYOF (Bring Your Own Font).
 Even though the built-in fonts require the content to be encoded in WINANSI, _you still type your AsciiDoc document in UTF-8_.
 Asciidoctor PDF encodes the content into WINANSI when building the PDF.
 
+CAUTION: Built-in fonts do not use the <<fallback-fonts,fallback fonts>>.
+In order for the fallback font to kick in, you must be using a TrueType font.
+
 .WINANSI Encoding Behavior
 ****
 When using the built-in PDF (AFM) fonts on a block of content in your AsciiDoc document, any character that cannot be encoded to WINANSI is replaced with a logic "`not`" glyph (`&#172;`) and you'll see the following warning in your console:
@@ -658,6 +675,9 @@ When using the built-in PDF (AFM) fonts on a block of content in your AsciiDoc d
 
 This behavior differs from the default behavior in Prawn, which simply crashes.
 
+You'll often see this warning if you're using callouts in your document and you haven't specified a TrueType font in your theme.
+To prevent this warning, you need to specify a TrueType font.
+
 For more information about how Prawn handles character encodings for built-in fonts, see https://github.com/prawnpdf/prawn/blob/master/CHANGELOG.md#vastly-improved-handling-of-encodings-for-pdf-built-in-afm-fonts[this note in the Prawn CHANGELOG].
 ****
 
@@ -689,7 +709,7 @@ This limitation may be lifted in the future.
 The limited character set of WINANSI, or the bland look of the built-in fonts, may motivate you to load your own font.
 Custom fonts can enhance the look of your PDF theme substantially.
 
-To start, you need to find a collection of TTF file of the font you want to use.
+To start, you need to find a TTF file collection for the font you want to use.
 A collection typically consists of all four styles of a font:
 
 * normal
@@ -881,7 +901,7 @@ See <<Title Page>> for details.
 |Inline image macro^[2]^ +
 (default: _not set_)
 |page:
-  background_image: +image:page-bg.png[]+
+  background_image: image:page-bg.png[]
 
 |layout
 |portrait {vbar} landscape +
@@ -1262,7 +1282,7 @@ TIP: The title page can be disabled from the document by setting the `notitle` a
 |Inline image macro^[2]^ +
 (default: _not set_)
 |title_page:
-  +background_image: image:title.png[]+
+  background_image: image:title.png[]
 
 |font_color
 |<<colors,Color>> +
@@ -1314,7 +1334,7 @@ TIP: The title page can be disabled from the document by setting the `notitle` a
 (default: _not set_)
 |title_page:
   logo:
-    +image: image:logo.png[pdfwidth=25%]+
+    image: image:logo.png[pdfwidth=25%]
 
 |top
 |Percentage^[3]^ +
@@ -1452,7 +1472,7 @@ TIP: The title page can be disabled from the document by setting the `notitle` a
 |<<quoted-string,Quoted string>> +
 (default: ', ')
 |title_page:
-  revision:
+  authors:
     delimiter: '; '
 
 |font_color
@@ -1780,8 +1800,18 @@ The keys in this category are used to control the style of literal, listing and
 (default: 9)
 |code:
   padding: 11
+
+3+|[#key-prefix-table-cell]*Key Prefix:* <<key-prefix-code-linenum,code_linenum>>^[2]^
+
+|font_color
+|<<colors,Color>> +
+(default: #999999)
+|code:
+  linenum_font_color: #ccc
 |===
 . The line_gap is used to tune the height of the background color applied to a span of block text highlighted using Rouge.
+. The code_linenum category only applies when using Pygments as the source highlighter.
+Otherwise, the style is controlled by the source highlighter theme.
 
 [#keys-callout-numbers]
 === Callout Numbers
@@ -2273,7 +2303,7 @@ The keys in this category control the arrangement and style of admonition blocks
 |admonition:
   icon:
     tip:
-      name: fa-fire
+      name: fas-fire
 
 |stroke_color
 |<<colors,Color>> +
@@ -2294,10 +2324,10 @@ The keys in this category control the arrangement and style of admonition blocks
 
 . The top and bottom padding values are ignored on admonition_label_padding.
 . `<name>` can be `note`, `tip`, `warning`, `important`, or `caution`.
-The subkeys in the icon category cannot be flattened (e.g., `tip_name: fa-lightbulb-o` is not valid syntax).
+The subkeys in the icon category cannot be flattened (e.g., `tip_name: far-lightbulb` is not valid syntax).
 . Required.
 See the `.yml` files in the https://github.com/jessedoyle/prawn-icon/tree/master/data/fonts[prawn-icon repository] for a list of valid icon names.
-The prefix (e.g., `fa-`) determines which font set to use.
+The prefix (e.g., `fas-`) determines which font set to use.
 
 [#keys-image]
 === Image
@@ -2565,10 +2595,105 @@ The keys in this category control the arrangement and style of outline list item
 |<<colors,Color>> +
 (default: _inherit_)
 |outline_list:
-  marker_font_color: #3c763d 
+  marker_font_color: #3c763d
+
+|text_align^[2]^
+|<<text-alignments,Text alignment>> +
+(default: $base_align)
+|outline_list:
+  text_align: left
 |===
 
 . Controls the color of the bullet glyph that marks items in unordered lists and the number for items in ordered lists.
+. Controls the alignment of the list text only, not nested content (blocks or lists).
+
+[#keys-ulist]
+=== Unordered List
+
+The keys in this category control the arrangement and style of unordered list items.
+
+[cols="3,4,5l"]
+|===
+|Key |Value Type |Example
+
+3+|[#key-prefix-ulist-marker]*Key Prefix:* <<key-prefix-ulist-marker,ulist_marker>>
+
+|font_family
+|<<fonts,Font family name>> +
+(default: _inherit_)
+|ulist:
+  marker:
+    font_family: Noto Serif
+
+|font_size
+|<<values,Number>> +
+(default: _inherit_)
+|ulist:
+  marker:
+    font_size: 9
+
+|font_color
+|<<colors,Color>> +
+(default: $outline_list_marker_font_color)
+|ulist:
+  marker:
+    font_color: #cccccc
+
+|line_height
+|<<values,Number>> +
+(default: $base_line_height)
+|ulist:
+  marker:
+    line_height: 1.5
+|===
+
+[cols="3,4,5l"]
+|===
+|Key |Value Type |Example
+
+3+|*Key Prefix:* ulist_marker_<type>^[1]^
+
+|content
+|<<quoted-string,Quoted string>>
+|ulist:
+  marker:
+    disc:
+      content: "\uf140"
+
+|font_family
+|<<fonts,Font family name>> +
+(default: _inherit_)
+|ulist:
+  marker:
+    disc:
+      font_family: fas
+
+|font_size
+|<<values,Number>> +
+(default: _inherit_)
+|ulist:
+  marker:
+    disc:
+      font_size: 9
+
+|font_color
+|<<colors,Color>> +
+(default: _inherit_)
+|ulist:
+  marker:
+    disc:
+      font_color: #ff0000
+
+|line_height
+|<<values,Number>> +
+(default: _inherit_)
+|ulist:
+  marker:
+    disc:
+      line_height: 2
+|===
+
+. <type> is one of disc, square, circle, checked, unchecked
 
 [#keys-table]
 === Table
@@ -2803,7 +2928,7 @@ The keys in this category control the arrangement and style of tables and table
 |<<fonts,Font family name>> +
 (default: $table_head_font_family)
 |table:
-  header_cell: 
+  header_cell:
     font_family: Noto Sans
 
 |font_size
@@ -3024,6 +3149,13 @@ The keys in this category control the arrangement and style of running header an
 |===
 |Key |Value Type |Example
 
+3+|[#key-prefix-running_content]*Key Prefix:* <<key-prefix-running_content,running_content>>
+|start_at
+|title {vbar} toc {vbar} body +
+(default: body)
+|running_content:
+  start_at: toc
+
 3+|[#key-prefix-header]*Key Prefix:* <<key-prefix-header,header>>
 
 |background_color^[1]^
@@ -3086,7 +3218,7 @@ The keys in this category control the arrangement and style of running header an
 |header:
   line_height: 1.2
 
-|padding
+|padding^[3]^
 |<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>> +
 (default: 0)
 |header:
@@ -3104,14 +3236,14 @@ The keys in this category control the arrangement and style of running header an
 |header:
   vertical_align: center
 
-|<side>_columns^[3]^
+|<side>_columns^[4]^
 |Column specs triple +
 (default: _not set_)
 |header:
   recto:
     columns: <25% =50% >25%
 
-|<side>_<position>_content^[3,4]^
+|<side>_<position>_content^[4,5]^
 |<<quoted-string,Quoted string>> +
 (default: '\{page-number}')
 |header:
@@ -3181,7 +3313,7 @@ The keys in this category control the arrangement and style of running header an
 |footer:
   line_height: 1.2
 
-|padding
+|padding^[3]^
 |<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>> +
 (default: 0)
 |footer:
@@ -3199,14 +3331,14 @@ The keys in this category control the arrangement and style of running header an
 |footer:
   vertical_align: top
 
-|<side>_columns^[3]^
+|<side>_columns^[4]^
 |Column specs triple +
 (default: _not set_)
 |footer:
   verso:
     columns: <50% =0% <50%
 
-|<side>_<position>_content^[3,4]^
+|<side>_<position>_content^[4,5]^
 |<<quoted-string,Quoted string>> +
 (default: '\{page-number}')
 |footer:
@@ -3216,6 +3348,7 @@ The keys in this category control the arrangement and style of running header an
 |===
 . The background color spans the width of the page, as does the border when a background color is specified.
 . If the height is not set, the running content at this periphery is disabled.
+. If the side padding is negative, the content will bleed into the margin of the page.
 . `<side>` can be `recto` (right-hand, odd-numbered pages) or `verso` (left-hand, even-numbered pages).
 Where the page sides fall in relation to the physical or printed page number is controlled using the `pdf-folio-placement` attribute (except when `media=prepress`, which implies `physical`).
 . `<position>` can be `left`, `center` or `right`.
@@ -3401,7 +3534,7 @@ These settings override equivalent keys defined in the theme file, where applica
 |<face>-cover-image^[1]^
 |path^[2]^ {vbar} image macro^[3]^ +
 (format can be image or PDF)
-|+:front-cover-image: image:front-cover.pdf[]+
+|:front-cover-image: image:front-cover.pdf[]
 
 |media
 |screen {vbar} print {vbar} prepress
@@ -3409,7 +3542,7 @@ These settings override equivalent keys defined in the theme file, where applica
 
 |page-background-image^[4]^
 |path^[2]^ {vbar} image macro^[3]^
-|+:page-background-image: image:bg.jpg[]+
+|:page-background-image: image:bg.jpg[]
 
 |pagenums^[5]^
 |flag (default: _set_)
@@ -3441,16 +3574,21 @@ These settings override equivalent keys defined in the theme file, where applica
 
 |title-logo-image
 |path^[2]^ {vbar} image macro^[3]^
-|+:title-logo-image: image:logo.png[top=25%, align=center, pdfwidth=0.5in]+
+|:title-logo-image: image:logo.png[top=25%, align=center, pdfwidth=0.5in]
+
+|title-page^[8]^
+|flag (default: _not set_)
+|:title-page:
 
 |title-page-background-image
 |path^[2]^ {vbar} image macro^[3]^
-|+:title-page-background-image: image:title-bg.jpg[]+
+|:title-page-background-image: image:title-bg.jpg[]
 |===
 
 . `<face>` can be `front` or `back`.
 . The path is resolved relative to base_dir.
 . The target of the image macro is resolved relative to `imagesdir`.
+If the image macro syntax is not used, the value is resolved relative to the base directory, which defaults to the document directory.
 . Page background images are automatically scaled to fit within the bounds of the page.
 +
 NOTE: Page backgrounds do not currently work when using AsciidoctorJ PDF.
@@ -3463,6 +3601,7 @@ Use the `noheader` and `nofooter` attributes to disable the running header and f
 . _(Experimental)_ The `text-alignment` document attribute is intended as a simple way to toggle text justification.
 The value of this attribute overrides the `base_align` key set by the theme.
 For more fine-grained control, you should customize using the theme.
+. Force a title page to be added even when the doctype is not book.
 
 == Publishing Mode