asciidoctor-pdf 2.0.0.alpha.1 → 2.0.0.beta.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 51c4377f62ca11147b6d896ed5e3951b4a1f592a1ae0d2361ed7285a751af428
-  data.tar.gz: 6d4011e829d0ffc774cd75833f633c76dbed53e1e9ada8c35d4d436c998ed82e
+  metadata.gz: f3c96a0b756ccd22c3aec10c571e5ef0280a0003398f48a86287037c52d13a85
+  data.tar.gz: c611aec1ecafd132c9415babfc193929bbe52879b6282cc752d6def346ce9d56
 SHA512:
-  metadata.gz: beac89c0b3c561e881e4f0c80d350f01cb2a46f14ce19779dd69a7e08173c8c6ba19fb072ffab76b0dc305ec083aa3e8305aa977b584643b18a9ed3475e3d2cd
-  data.tar.gz: b347acb25d851c82ae9fddb6996bff0864fada2442237c9f6d4933ec18c1a9cf437ed85b1128fa857aab41c504fc237b29d6f104328a5ab00da7ecd4cf75df5d
+  metadata.gz: 517791afccee6a976f59244b08ffdd062f09d2153d04917a61b969ef525752eee70d8118586932757e3f6fd175880f899a60d768cfc4b8e8ef6cabdad5f5f239
+  data.tar.gz: 3ae8abd3251302def2b2305a4c9aebe940235735d0c0204891c909e383ac8622eb21b158d3d844a49b60dab5f1c5d82e8252961c1f2247b6158a7975d9d7c50b

data/CHANGELOG.adoc

@@ -5,6 +5,99 @@
 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/main[commit history] on GitHub.
 
+== 2.0.0.beta.1 (2022-05-04) - @mojavelinux
+
+Enhancements::
+
+* introduce `index-pagenum-sequence-style` document attribute to control style of sequential page numbers in index when media=screen (#1656)
+* allow entry for document in outline to be controlled using `outline-title` attribute (#1789)
+* allow extended converter to insert or filter toc entries by overriding `get_entries_for_toc` method (#2097)
+* add `asciidoctor/pdf/nopngmagick` script to unregister Gmagick handler for PNG images only (#1687)
+* allow theme to configure which end the caption is placed for a block image (#2115)
+* add `Page#imported` method to mark page as imported (which suppresses running contennt)
+* add support for `smallcaps` text transform by replacing lowercase letters with small capital variants (#1192)
+* use `base-border-color` as default border color; control appearance of border using `border-width` value alone (#2134)
+* remove border colors in base theme so all border colors can be controlled using `base-border-color` when extending theme
+* enable running footer when using base theme
+
+Bug Fixes::
+
+* allow border width of block image to be specified as an array (1, 2, or 4 values) (#2119)
+* rename `delete_page` extension method to `delete_current_page` to avoid conflict with incompatible method on `Prawn::Document`
+* remap `table-caption-side` theme key to `table-caption-end` (#2125)
+* add missing glyph for `ÿ` in built-in fonts
+* remove use of deprecated keys in chronicles-dark-theme.yml
+
+=== Details
+
+{url-repo}/releases/tag/v2.0.0.beta.1[git tag] | {url-repo}/compare/v2.0.0.alpha.3\...v2.0.0.beta.1[full diff]
+
+== 2.0.0.alpha.3 (2022-05-01) - @mojavelinux
+
+Enhancements::
+
+* allow border width of block to be specified per edge using 4-value array (#2102)
+* allow padding on block to be specified using 2-value array for ends and sides or 3-value array with implied left side value (#2104)
+* allow margins in running content to be specified using 2-value array for ends and sides or 3-value array with implied left side value (#2104)
+* allow theme to set border and padding on headings per level (#434)
+
+Improvements::
+
+* reduce top and bottom padding on quote and verse blocks in base theme
+* use uniform top and bottom padding on quote blocks in default theme
+* change `inscribe_` method prefix in converter to `ink_`
+
+Bug Fixes::
+
+* allow `ink_toc` method in extended converter to insert page above TOC page
+* remap `layout_` methods contributed to converter by prepended module
+* neutralize padding hacks in themes designed before the converter had smart margins
+* allow smallest ends or sides border width on block to be less than 1
+* cap border corners on block when width is defined using array (uniform or otherwise) (#2103)
+* fix crash in certain circumstances when theme does not define value for `base-border-width` key
+* use sensible fallbacks for table border and grid color and width (retains backwards compatibility)
+
+=== Details
+
+{url-repo}/releases/tag/v2.0.0.alpha.3[git tag] | {url-repo}/compare/v2.0.0.alpha.2\...v2.0.0.alpha.3[full diff]
+
+== 2.0.0.alpha.2 (2022-04-29) - @mojavelinux
+
+Enhancements::
+
+* separate `align` and `text-align` keys in theme schema; remap old keys for backwards compatibility (#2095)
+* allow theme to control the border on all sides of tables independently (#902)
+* keep section title with first block of content is `breakable` option is set on section (#2075, #38)
+* pass the `part` and `chapterlike` options to the `arrange_section` method for convenience
+* add support for `background-color` property on caption (#1995)
+* add support for image-based icons, resolved from `iconsdir` and having the `icontype` file extension (#1770)
+* add `asciidoctor/pdf/nogmagick` script to prevent loading prawn-gmagick gem (#1687)
+* change name of `untitled` option on special section to `notitle`
+* allow the title of any section to be hidden using the `notitle` option
+* allow imported PDF page to be referenced in TOC by enclosing in parent section with `notitle` option (#1213)
+* allow entry for preface to be added to TOC without adding title to body using the `notitle` option on the preface section (#1786)
+* automatically promote the `notitle` option from the first block in the premable to preface section; restore lead role on opening paragraph (#1786)
+
+Improvements::
+
+* change "icon" to "icon image" in warning about missing admonition icon image
+* report admonition type in warning about missing implicit admonition icon image
+
+Bug Fixes::
+
+* set the base font of the front cover image is a PDF and the title page is not active (#2092)
+* pass through warnings in background SVG to logger (#1940)
+* keep closing quote with trailing ellipsis in text enclosed in typographic quotes (#321)
+* collapse space in front of hidden index term (#2061)
+* delete dests on page before deleting it (keeps generated PDF clean of obsolete destinations)
+* don't call `arrange_section` if section title is hidden
+* remove `theme_font` enclosure around call to `start_new_chapter` and `start_new_part`
+* change `layout_` method prefix in converter to `inscribe_` (#2099)
+
+=== Details
+
+{url-repo}/releases/tag/v2.0.0.alpha.2[git tag] | {url-repo}/compare/v2.0.0.alpha.1\...v2.0.0.alpha.2[full diff]
+
 == 2.0.0.alpha.1 (2022-04-20) - @mojavelinux
 
 Enhancements::
@@ -559,7 +652,7 @@ Bug Fixes::
 * allow theme to disable font kerning
 * add support for default theme alignment for tables (#1164)
 * add theming support to (inline) roles on phrases (#368)
-* allow theme to customize style of titles in running content (#1044)
+* allow theme to customize style of titles in running content using `title-style` key (#1044)
 * add support for the built-in big and small roles on phrases (#459)
 * route AFM font warning through Asciidoctor logger
 * upgrade code font (M+ 1mn) to TESTFLIGHT-63a

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]>
-v2.0.0.alpha.1, 2022-04-20
+v2.0.0.beta.1, 2022-05-04
 // Settings:
 :experimental:
 :idprefix:
@@ -24,7 +24,7 @@ endif::[]
 :project-handle: asciidoctor-pdf
 // Variables:
 :release-line: 2.0.x
-:release-version: 2.0.0.alpha.1
+:release-version: 2.0.0.beta.1
 // URIs:
 :url-asciidoctor: http://asciidoctor.org
 :url-gem: http://rubygems.org/gems/asciidoctor-pdf
@@ -170,7 +170,7 @@ ifndef::env-site[You can also <<development,run the code from source>> if you wa
 To install {project-name}, first make sure you have satisfied the <<Prerequisites,prerequisites>>.
 Then, install the gem from RubyGems.org using the following command:
 
- $ gem install asciidoctor-pdf
+ $ gem install asciidoctor-pdf --pre
 
 If you're using Ruby 3.1 or better, you must also install the matrix gem until Prawn 2.5.0 or better is released.
 
@@ -713,23 +713,41 @@ If you're using fonts in your SVG, and you want those fonts to be preserved, tho
 
 == Supporting Additional Image File Formats
 
-In order to embed an image into a PDF, Asciidoctor PDF must understand how to read it.
+In order to embed an image into a PDF, Asciidoctor PDF must understand how to decode it.
 To perform this work, Asciidoctor delegates to the underlying libraries.
-{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.
+{url-prawn}[Prawn] provides support for decoding JPG and PNG images.
+{url-prawn-svg}[prawn-svg] brings support for translating SVG images to PDF commands.
+Without any additional libraries, those are the only image file formats supported by Asciidoctor PDF.
 
-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.
+If you need support for additional image formats, such as GIF, TIFF, WebP, or interlaced PNG--and you don't want to convert those images to a supported format like JPG--you must install the {url-prawn-gmagick}[prawn-gmagick] (>= 0.0.9) Ruby gem.
+prawn-gmagick is an extension for Prawn that delegates image decoding to {url-graphicsmagick}[GraphicsMagick] to add support for all image formats recognized by that library.
+
+prawn-gmagick has the additional benefit of *significantly* reducing the processing time, power, and memory necessary to generate a PDF that contains a lot of PNG images.
+For large books (such as Pro Git), you might see the conversion time drop by as much as half.
+Decoding PNG images requires a lot of mathematical computation, a task Ruby is not particularly efficient at performing.
+That's why adding the prawn-gmagick gem to the converter makes such a substantial difference.
+
+As an alternative to using prawn-gmagick, you could optimize the images you pass into Asciidoctor PDF, either by scaling them down or converting them to an uncompressed format like JPG.
 
 The prawn-gmagick gem uses native extensions to compile against GraphicsMagick.
-This system prerequisite limits installation to Linux and OSX.
+This system prerequisite limits installation to C Ruby running on Linux and macOS.
 Please refer to the {url-prawn-gmagick}[README for prawn-gmagick] to learn how to install it.
 
-Once this gem is installed, Asciidoctor automatically loads it, then delegates to it to handle all image embedding.
-In addition to support for additional image file formats, this gem also speeds up image processing considerably.
-We highly recommend using this gem if you're able to install it.
+ $ gem install prawn-gmagick
+
+When this gem is installed, Asciidoctor automatically detects and loads it, then delegates all image decoding to GraphicsMagick by way of the bridge it provides.
+We highly recommend using this gem with Asciidoctor PDF if you're able to install it.
+
+The one downside of delegating to GraphicsMagick is that it can mangle certain PNG images.
+If this happens, you can instruct Asciidoctor PDF to not delegate to GraphicsMagick to load PNG images by requiring `asciidoctor/pdf/nopngmagick` when calling Asciidoctor PDF, as follows:
+
+ $ asciidoctor-pdf -r asciidoctor/pdf/nopngmagick doc.adoc
+
+You can also tell Asciidoctor PDF not to use prawn-gmagick at all by requiring `asciidoctor/pdf/nogmagick` when calling Asciidoctor PDF, as follows:
+
+ $ asciidoctor-pdf -r asciidoctor/pdf/nogmagick doc.adoc
+
+Granted, bypassing prawn-gmagick means you no longer get support for additional image formats that Prawn cannot handle or the PNG acceleration.
 
 == Importing PDF Pages
 

data/data/fonts/ABOUT-mplus1p-subset

@@ -17,6 +17,7 @@ The following changes were made using fontforge to produce mplus1p-regular-fallb
  ** General Punctuation (U+2000–U203a)
  ** Geometric Shapes (U+25a0–U25ff)
  ** Assorted Symbols (U+20ac, U+2122, U+21d0–U+21d5, U+2190–U+2195, U+2610–U+2611, U+2713–U+2714)
+ ** Latin Small Capital Letters (U+1D00, U+0299, U+1D04, U+1D05, U+1D07, U+A730, U+0262, U+029C, U+026A, U+1D0A, U+1D0B, U+029F, U+1D0D, U+0274, U+1D0F, U+1D18, U+A7AF (missing), U+0280, U+A731, U+1D1B, U+1D1C, U+1D20, U+1D21, U+028F, U+1D22)
  ** .notdef glyph
 * Added BOM (U+feff), hair space (U+200a), zero-width space (U+200b) and line feed (U+000a) characters (from blank)
 * Manually added non-breaking hyphen (U+2011) from hyphen (U+002d)

data/data/fonts/ABOUT-notosans-subset

@@ -17,6 +17,7 @@ The following changes were made using fontforge to produce the notosans-*-subset
  ** General Punctuation (U+2000–U203a)
  ** Geometric Shapes (U+25a0–U25ff)
  ** Assorted Symbols (U+20ac, U+2122, U+21d0, U+21d2, U+2190, U+2192)
+ ** Latin Small Capital Letters (U+1D00, U+0299, U+1D04, U+1D05, U+1D07, U+A730 (missing), U+0262, U+029C, U+026A, U+1D0A, U+1D0B, U+029F, U+1D0D, U+0274, U+1D0F, U+1D18, U+A7AF (missing), U+0280, U+A731 (missing), U+1D1B, U+1D1C, U+1D20, U+1D21, U+028F, U+1D22, U+01EB)
  ** .notdef glyph
 * Imported ballot boxes from Font Awesome (U+2610, U+2611) (Noto Serif Regular only)
 * Added line feed character (U+000a)

data/data/fonts/ABOUT-notoserif-subset

@@ -17,6 +17,7 @@ The following changes were made using fontforge to produce the notoserif-*-subse
  ** General Punctuation (U+2000–U203a)
  ** Geometric Shapes (U+25a0–U25ff)
  ** Assorted Symbols (U+20ac, U+2122, U+21d0, U+21d2, U+2190, U+2192)
+ ** Latin Small Capital Letters (U+1D00, U+0299, U+1D04, U+1D05, U+1D07, U+A730 (missing), U+0262, U+029C, U+026A, U+1D0A, U+1D0B, U+029F, U+1D0D, U+0274, U+1D0F, U+1D18, U+A7AF (missing), U+0280, U+A731 (missing), U+1D1B, U+1D1C, U+1D20, U+1D21, U+028F, U+1D22, U+01EB)
  ** .notdef glyph
 * Imported ballot boxes from Font Awesome (U+2610, U+2611) (Noto Serif Regular only)
 * Added line feed character (U+000a)

data/data/themes/base-theme.yml

@@ -1,24 +1,19 @@
-# NOTE file is read "as is"; variables are not parsed; key layout must be flat
+# NOTE: file is read "as is"; variables are not parsed; key layout must be flat
 page_background_color: 'FFFFFF'
 page_layout: portrait
 page_initial_zoom: FitH
-# 36 is equivalent to 0.5in
-page_margin: 36
+page_margin: 36 # 36 is 0.5in
 page_margin_inner: 48
 page_margin_outer: 24
 page_size: A4
-base_align: left
-#base_font_color: '333333'
+base_text_align: left
 base_font_color: '000000'
-#base_font_family: Times-Roman
 base_font_family: Helvetica
 base_font_size: 12
-# QUESTION should we rename to min_font_size?
 base_font_size_min: 6
 base_font_style: normal
 base_line_height: 1.15
-base_border_color: 'EEEEEE'
-base_border_width: 0.5
+base_border_color: '000000'
 role_lead_font_size: 13.5
 role_line-through_text_decoration: line-through
 role_underline_text_decoration: underline
@@ -46,8 +41,7 @@ heading_line_height: 1.15
 heading_margin_top: 4
 heading_margin_bottom: 12
 heading_min_height_after: 20
-title_page_align: center
-title_page_line_height: 1.15
+title_page_text_align: center
 title_page_logo_top: 10%
 title_page_title_top: 40%
 title_page_title_font_size: 18
@@ -69,43 +63,37 @@ abstract_line_height: 1.4
 abstract_padding: 0
 abstract_title_align: center
 abstract_title_font_style: bold
-admonition_column_rule_color: 'EEEEEE'
 admonition_column_rule_width: 0.5
 admonition_padding: [4, 12, 4, 12]
 admonition_label_font_style: bold
 admonition_label_text_transform: uppercase
-quote_border_color: 'EEEEEE'
 quote_border_left_width: 4
-quote_padding: [6, 12, 6, 14]
-verse_border_color: 'EEEEEE'
+quote_padding: [3, 12, 3, 14]
 verse_border_left_width: 4
-verse_padding: [6, 12, 6, 14]
+verse_padding: [3, 12, 3, 14]
 code_font_family: Courier
 code_font_size: 10.8
 code_line_height: 1.2
 code_padding: 9
-code_border_color: 'EEEEEE'
 code_border_width: 0.5
 conum_line_height: 1.15
 conum_glyphs: circled
 example_background_color: 'FFFFFF'
-example_border_color: 'EEEEEE'
 example_border_width: 0.5
 example_padding: 12
 image_align: left
 prose_margin_bottom: 12
 sidebar_background_color: 'EEEEEE'
+sidebar_border_width: 0.5
 sidebar_padding: 12
 sidebar_title_align: center
 sidebar_title_font_style: bold
-table_border_color: '000000'
 table_border_style: solid
 table_border_width: 0.5
 table_cell_padding: 2
 table_head_font_style: bold
 table_head_border_bottom_width: 1.25
 table_body_stripe_background_color: 'EEEEEE'
-thematic_break_border_color: 'EEEEEE'
 thematic_break_border_style: solid
 thematic_break_border_width: 0.5
 thematic_break_margin_bottom: 12
@@ -113,5 +101,8 @@ toc_indent: 15
 toc_line_height: 1.4
 footnotes_font_size: 9
 footnotes_item_spacing: 3
+footer_border_width: 0.5
+footer_font_size: 10
+footer_height: 30
 footer_recto_right_content: '{page-number}'
 footer_verso_left_content: '{page-number}'

data/data/themes/default-theme.yml

@@ -22,7 +22,7 @@ page:
   margin_outer: 0.59in
   size: A4
 base:
-  align: justify
+  text_align: justify
   # color as hex string (leading # is optional)
   font_color: 333333
   # color as RGB array
@@ -96,7 +96,7 @@ menu:
   caret_content: " <font size=\"1.15em\" color=\"#B12146\">\u203a</font> "
   font_style: bold
 heading:
-  align: left
+  text_align: left
   font_color: $base_font_color
   font_style: bold
   # h1 is used for part titles (book doctype) or the doctitle (article doctype)
@@ -114,7 +114,7 @@ heading:
   margin_bottom: $vertical_rhythm * 0.9
   min_height_after: $base_line_height_length * 1.5
 title_page:
-  align: right
+  text_align: right
   logo:
     top: 10%
   title:
@@ -148,7 +148,7 @@ abstract:
   font_style: italic
   first_line_font_style: bold
   title:
-    align: center
+    text_align: center
     font_color: $heading_font_color
     font_size: $heading_h4_font_size
     font_style: $heading_font_style
@@ -168,8 +168,8 @@ quote:
   font_size: $base_font_size_large
   border_color: $base_border_color
   border_width: 0
-  border_left_width: 5
-  padding: [0, $horizontal_rhythm, $block_margin_bottom * 0.25, $horizontal_rhythm + $quote_border_left_width / 2]
+  border_left_width: $horizontal_rhythm / 3
+  padding: [$vertical_rhythm / 4, $horizontal_rhythm, $vertical_rhythm / 4, $horizontal_rhythm + $quote_border_left_width / 2]
   cite:
     font_size: $base_font_size_small
     font_color: $role_subtitle_font_color
@@ -218,7 +218,7 @@ sidebar:
   border_width: $base_border_width
   padding: [$vertical_rhythm, $vertical_rhythm * 1.25, $vertical_rhythm, $vertical_rhythm * 1.25]
   title:
-    align: center
+    text_align: center
     font_color: $heading_font_color
     font_size: $heading_h4_font_size
     font_style: $heading_font_style
@@ -243,6 +243,7 @@ table:
   background_color: $page_background_color
   border_color: DDDDDD
   border_width: $base_border_width
+  grid_width: $base_border_width
   cell_padding: 3
   head:
     font_style: bold

data/docs/theming-guide.adoc

@@ -1147,7 +1147,7 @@ The name of the role is the first subkey level.
 The role name may contain a hyphen, but *a role name cannot contain an underscore*.
 The keys under the role are the theming properties.
 
-IMPORTANT: Custom roles only apply to inline phrases and paragraphs.
+IMPORTANT: Custom roles only apply to paragraphs and inline phrases.
 
 Here's an example of a role for making text red:
 
@@ -4223,11 +4223,12 @@ The keys in this category control the arrangement and style of tables and table
   caption:
     text-align: left
 
-|caption-side
+|caption-end
 |top {vbar} bottom +
 (default: top)
 |table:
-  caption-side: bottom
+  caption:
+    end: bottom
 
 |caption-max-width
 |fit-content {vbar} fit-content(percentage) {vbar} none {vbar} <<measurement-units,Measurement>> +
@@ -5910,19 +5911,19 @@ Refer to the primary converter to discover the pseudo-HTML you can use for inlin
 
 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.
+Since this is a specialized section element, there's a dedicated method named `ink_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
+def ink_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.imported
+end
 ----
 
 The method `typeset_text` and `calc_line_metrics` are provided by Asciidoctor PDF to make writing text easier.