v2.0.5

This patch release is a continuation of 2.0.4 to fix a long-standing issue in the calculation of the TOC extent (the page range) when the sectids attribute is unset. All TOC entries are now included when computing the TOC extent so it matches the TOC extent when inked in the primary document. This patch release fixes another long-standing issue in the calculation of the width of a marked phrase (a phrase with a background color and/or border) when text justification is on.

Distribution

• RubyGem (asciidoctor-pdf)

Changelog

Bug Fixes

• do not filter TOC entries without an ID when computing the TOC extent (#2210)
• fix width of multi-word phrase with background and border offset (#2059)

Release meta

Released on: 2022-05-26
Released by: @mojavelinux
Release beer: 7-Speed IPA by Living the Dream

Logs: resolved issues | full diff

Credits

A very special thanks to all the awesome supporters of the Asciidoctor OpenCollective campaign who provided critical funding for the development of this release as well as ongoing development of the project.

v2.0.4

This is a very minor patch release to fix a regression in the calculation of the TOC extent (the page span of the TOC) when the sectids attribute is toggled in the document. We expect to put out another patch release shortly to fix the issue more comprehensively.

Distribution

• RubyGem (asciidoctor-pdf)

Changelog

Bug Fixes

• fix calculation of TOC extent when TOC entry has children but no ID (#2208)

Release meta

Released on: 2022-05-26
Released by: @mojavelinux
Release beer: Ghost in the Machine by Parish Brewing Co.

Logs: resolved issues | full diff

Credits

A very special thanks to all the awesome supporters of the Asciidoctor OpenCollective campaign who provided critical funding for the development of this release as well as ongoing development of the project.

v2.0.3

Leveraging our new automated release process, we're putting out patch releases as fast and furious as the fixes for bugs we discover. This is a patch release that only fixes bugs and does not introduce any new functionality.

The fixes include adjusting the TrimBox on pages so the optimizer can successfully produce PDF/X compatible documents using Ghostscript, setting the height of an image resized to fit the height of a page accurately so it does not cause a page to be skipped, and truncating the title page contents to fit on a single page, logging a warning if this occurs. The one minor improvement is that an extended converter can access the optimize quality and compliance settings specified by the user through the @optimize instance variable.

Distribution

• RubyGem (asciidoctor-pdf)

Changelog

Improvements

• compute the optimize settings in init_pdf and store as Hash instead of after writing the PDF file

Bug Fixes

• adjust TrimBox to fit inside of BleedBox when using optimizer and compliance is PDF/X (#2203)
• set height of resized image to available height to avoid float precision error when scaling down image to fit page (#2205)
• prevent content on title page from overrunning the bounds of a single page and warn; restriction applies to ink_title_page

Release meta

Released on: 2022-05-25
Released by: @mojavelinux
Release beer: Ghost in the Machine by Parish Brewing Co.

Logs: resolved issues | full diff

Credits

A very special thanks to all the awesome supporters of the Asciidoctor OpenCollective campaign who provided critical funding for the development of this release as well as ongoing development of the project.

v2.0.2

In keeping with semantic versioning, this is a patch release that only fixes bugs and does not introduce any new functionality. We're continuing to work on bug fixes that didn't make it into 2.0.0. This release fixes two issues that pertain to table layouts. The first is that the column width calculation has been fixed in certain cases when the table contains colspans. The second is that the table will be advanced to the next page if the first row does not fit in the remaining space on the page when it contains a rowspan.

Distribution

• RubyGem (asciidoctor-pdf)

Changelog

Bug Fixes

• use specified column widths to avoid bugs in column width calculation when using colspans (#1368)
• advance table to next page if rowspan in first row does not fit in space remaining on current page (#403)

Release meta

Released on: 2022-05-22
Released by: @mojavelinux
Release beer: The Citra Bomb One by HopLark

Logs: resolved issues | full diff

Credits

A very special thanks to all the awesome supporters of the Asciidoctor OpenCollective campaign who provided critical funding for the development of this release as well as ongoing development of the project.

v2.0.1

In keeping with semantic versioning, this is a patch release that only fixes bugs and does not introduce any new functionality. Shortly after the 2.0.0, there were two edge case bugs discovered. The first is that an inline image that is resized to fit the height of the page would cause the converter to go into an infinite loop trying to position it on the following page. We added a safeguard against this infinite loop in general, then fixed the position calculation so it would fit. We also discovered that long contiguous lines in a source block with linenums enabled would cause the line to be advanced to the next page and into the linenum gutter, which was also fixed.

Distribution

• RubyGem (asciidoctor-pdf)

Changelog

Bug Fixes

• scale inline image to fit within available height of page, accounting for the top padding of the line and the bottom gutter (#2193)
• short-circuit formatted_text routine and log error if fragments in first line cannot fit on a new page
• break and wrap long contiguous text in source block when linenums are enabled (#2198)

Release meta

Released on: 2022-05-21
Released by: @mojavelinux
Release beer: Xocolatl by Wild Blue Yonder

Logs: resolved issues | full diff

Credits

A very special thanks to all the awesome supporters of the Asciidoctor OpenCollective campaign who provided critical funding for the development of this release as well as ongoing development of the project.

v2.0.0

We began the journey towards the 2.0.0 release over two years ago with a goal of making this converter more accurate, easier to extend, and more thoroughly documented. It all started with #789. The result has turned out to be better than anything we could have hoped for. We never thought it would include basic support for image floats, and yet here we are. And despite all the changes, this release is backwards compatible with all existing themes and extended converters written for 1.6.x.

PDF, and printable documents in general, present what often feels like a bottomless pit of requirements. By providing a more robust framework, the hope is that users will be able to build on it to serve their own needs rather than having to wait and lobby for changes to the converter itself. The extended converter use cases page in the new docs highlights just how far this converter can be stretched to accommodate those needs. (If you look close, you can even find a recipe for applying a multi-column layout).

Getting the converter to work this way led to solutions for hundreds of open issues, 222 to be exact. With > 2,000 tests riding in on > 1,500 new commits means this converter is far more stable than it has ever been in the past. The converter is well-tested, better organized, and sufficiently documented. And while it still has limitations, that list has been cut down substantially.

This release marks a switch to semantic versioning and leaner releases in the future. Although this software is now very stable, the release also marks a shift in strategy to begin exploring other approaches to producing PDF documents, most likely by leveraging web technologies. We have pushed this PDF generation library well beyond its limits and intended use. To take this conversion further, new solutions are needed. We're leaving this repository in a state where it can continue to be maintained within the boundaries of what it currently provides. We wouldn't go so far as to call it maintenance mode, but maintenance will certainly become the focus.

Distribution

• RubyGem (asciidoctor-pdf)

Changelog

For a more complete list of enhancements, improvements, and bug fixes that are included in this major milestone, see the What's New page in the documentation.

Improvements

• use more stable approach to recreating current bounds in scratch document
• add foundation to support multi-column layout for the body of an article (using an extended converter only)

Release meta

Released on: 2022-05-18
Released by: @mojavelinux
Release beer: 🎄 St. Bernardus Christmas Ale by St. Bernardus

Logs: resolved issues | full diff

Credits

A huge shout out to Sarah White (@graphitefriction) for collecting the raw materials of docs scattered throughout the repository and elsewhere and organizing them into a documentation component in the Asciidoctor documentation site. Not only do those docs make Asciidoctor PDF more approachable for new users, they also make the task of supporting all users a lot easier.

A very special thanks to all the awesome supporters of the Asciidoctor OpenCollective campaign who provided critical funding for the development of this release as well as ongoing development of the project.

v2.0.0 RC 1

As we rounded up the issues and polished the documentation in preparation for the 2.0.0 release, we were able to squeeze in a few more enhancements, improvements, and bug fixes. We're more confident than ever that we're ready for a final release, which is why this release has been labeled as the release candidate.

The main enhancement is that it's now possible to position the caption for code and example blocks on the bottom end (below the block) using the theme. You can also use the theme to turn on text hyphenation. In an effort to organize the code, we've sorted the methods in the converter and marked which methods are private. This will give you more confidence when writing an extended converter. We've added a whole bunch of examples of extended converters to the docs. On the bug fix front, we finally fixed a long-standing issue that the top padding of line height was not being applied to the first line on the page when content is split across pages. We also addressed a few edge cases, like removing the image border on the title page logo, not leaving behind an entry for an empty notitle section at the bottom of the TOC and outline, and looking for the correct alignment role names on a block image. Since the focus of this release was largely on documentation, there have been a bunch of additions and improvements there as well.

The final 2.0.0 will follow this release shortly.

Distribution

• RubyGem (asciidoctor-pdf)

Changelog

Enhancements

• allow theme to position caption for code and example blocks below block using caption-end key (#1730)
• allow hyphenation to be turned on and configured using the base-hyphens key in the theme (#2161)
• replace docdir attribute reference in value of pdf-themesdir and pdf-fontsdir attributes (if not already replaced) (#412)
• split out start_title_page method from ink_title_page to make customization of the title page simpler using an extended converter
• introduce start_toc_page method to handle positioning cursor at first page of TOC

Improvements

• reclassify and mark which methods in the converter are private
• organize methods in converter
• add DOM traversal methods to simplify the logic in the converter
• remove requirement to add dummy text to title page to preserve it

Bug Fixes

• apply top line height padding to first line of text when text runs to top of next page (#2173)
• don't add entry to outline for notitle section if no content follows it
• don't add entry to TOC for notitle section if no content follows it
• look for block align roles on image instead of text align roles (#2176)
• use correct left value when creating bounding box
• don't apply border on block images to logo image on title page

Release meta

Released on: 2022-05-17
Released by: @mojavelinux
Release beer: Strata-Ford IPA by Athletic Brewing

Logs: resolved issues | full diff

Credits

A very special thanks to all the awesome supporters of the Asciidoctor OpenCollective campaign who provided critical funding for the development of this release as well as ongoing development of the project.

v2.0.0 Beta 2

We received a lot of great feedback from the first beta that led to nearly a dozen bug fixes. While wrapping up documentation tasks for the 2.0.0, we had a breakthrough with wrapping...

Thanks to numerous changes and improvements to the code leading up to the 2.0.0 release, we determined it was easier to support image floats than to document how to patch them in. Thus, we're thrilled to announce that this release supports wrapping paragraph text around a floating image (a block image with the float attribute set)!

As part of that change, we updated the converter to coerce the image caption to automatically fit within the bounds of the image if the float attribute is set. Other types of blocks can be enlisted in float wrapping using an extended converter, which is now documented. We also added orphan checking to discrete headings, added a key to control the column gap in the index section, and added support for the text-transform property and the normal_italic font style to the first line of the abstract. The spacing around a thematic break is now controlled using padding instead of margins. The built-in theme suffix with-fallback-font has been changed to with-font-fallbacks, the sans-with-fallback-font has been renamed to default-sans-with-font-fallbacks, and there's a new default-sans theme. Finally, it's now possible to override the convert handler for listing, literal, stem, and pass blocks.

During this development cycle, the new docs for Asciidoctor PDF continued to be improved and reorganized. There's almost full coverage for the new features added in 2.0.0. Speaking of coverage, the test suite has surpassed the 2,000 test mark!

We're going to give users a chance to try this release so we can uncover any unexpected regressions, errors, or problem areas. If they come up, we will try to address them quickly so that we can turn around a final release very soon.

Distribution

• RubyGem (asciidoctor-pdf)

Changelog

Enhancements

• add support for float attribute on image; wrap ensuing paragraphs around image with float attribute (#353)
• add supports_float_wrapping? method for extended converter to override to enlist other blocks in float wrapping; add example to docs (#353)
• add image-float-gap key to theme to control space around image float (#353)
• add support for text-transform property on first line of abstract in theme (#2141)
• rename resolve_alignment_from_role to resolve_text_align_from_role to reflect proper terminology and purpose; alias old method name
• add support for orphan avoidance to discrete headings to match behavior of section titles (using call to arrange_heading) (#2151)
• rename arrange_section to arrange_heading to reflect proper terminology and purpose
• add index-column-gap key to theme to control size of gap between columns
• coerce image-caption-max-width to fit-content if float attribute is set on block image (#2150)
• add support for text box with fixed height via :height option to typeset_text helper
• configure typeset_text and ink_prose to return remaining fragments when :height option is specified
• add support for :indent_paragraphs option to formatted text box (#353)
• if float attribute is set on block image, set max width on caption to fit-content if max width not already set to a fit-content value
• add built-in default-sans theme

Improvements

• rename theme suffix with-fallback-font to with-font-fallbacks
• rename sans-with-fallback-font theme to default-sans-with-font-fallbacks
• configure spacing around thematic break using thematic-break-padding key instead of margin top and bottom (#2164)
• rename convert_listing_or_literal to convert_code and alias old name
• reify convert handler for STEM blocks (convert_stem)
• reify convert handler for pass blocks (convert_pass) and remove block decoration

Bug Fixes

• honor caption-align when element align is not left and caption-max-width is % of element width (e.g., fit-content(50%)) (#2156)
• do not orphan sidebar title (#2158)
• allow theme to set font style of first line of abstract to normal_italic (#2138)
• add support for :color option to Prawn::Text::Formatted::Box directly and remove workarounds
• preserve columns on subsequent pages in the index section (#2149)
• fix return value of cursor method inside block for column box in index section
• correctly detect preceding code block when determining whether to collapse top margin of colist
• apply bottom margin to thematic break that falls at top of page (#2164)
• allow extended converter to override convert_code method to handle convert_listing and convert_literal calls
• restore margin below pass block
• remove use of deprecated theme keys in default-for-print theme

Release meta

Released on: 2022-05-14
Released by: @mojavelinux
Release beer: The Thistle by Iron Mule Brewery

Logs: resolved issues | full diff

Credits

A very special thanks to all the awesome supporters of the Asciidoctor OpenCollective campaign who provided critical funding for the development of this release as well as ongoing development of the project.

v2.0.0 Beta 1

The march is on towards the 2.0.0 release! We've determined that converter's behavior and APIs are now stable for this major release. The focus now turns towards fixing bugs, compatibility issues, and minor features that don't introduce breaking changes or deprecations.

Notable new features in this release include a new document attribute (index-pagenum-sequence-style) to control the style of page sequences in the index, a new document attribute (outline-title) to control the text and appearance of the title in the PDF outline, a new API method to control which elements are enlisted in the TOC and the corresponding logic to support non-sections, support for the smallcaps text transform (e.g., Sᴍᴀʟʟ Cᴀᴘᴛɪᴀʟ Lᴇᴛᴛᴇʀs) and updates to the bundled fonts to support those glyphs, and the ability to control the color of all borders using the base-border-color key when extending the base theme. In the theme, the caption-end key was added to the image category and the caption-side key on the table category was renamed to caption-end to be consistent.

During this development cycle, the new docs for Asciidoctor PDF continued to be improved and reorganized. Along with lots of updates to the theming guide, they include a new page that covers a variety of use cases that can be addressed using an extended converter. The new docs will now go live on https://docs.asciidoctor.org in conjunction with this release.

We're going to give users a chance to try this release so we can uncover any unexpected regressions, errors, or problem areas. If they come up, we will try to address them quickly so that we can turn around a final release very soon.

May the 4th be with you! 🤺

Distribution

• RubyGem (asciidoctor-pdf)

Changelog

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

Release meta

Released on: 2022-05-04
Released by: @mojavelinux
Release beer: In the Steep by Outer Range Brewing

Logs: resolved issues | full diff

Credits

A very special thanks to all the awesome supporters of the Asciidoctor OpenCollective campaign who provided critical funding for the development of this release as well as ongoing development of the project.

v2.0.0 Alpha 3

This release was mostly about improving consistency and compatibility as we near the Asciidoctor 2.0.0 release.

The main new feature is support for setting a border and padding per heading level, including the document title of an article. Implementing this feature meant adding support for setting the border width and padding independently on all edges of a block and capping the border corners. Any time a padding or margin value can be specified in the theme using an array value, the 2- and 3-value forms are now accepted. To help with the transition to Asciidoctor PDF 2.0.0, bottom padding hacks detected in an older theme are automatically neutralize to retain the same appearance to the degree possible. The top and bottom padding on quote and verse blocks is now uniform in the default theme, and tighter in the base theme. The default border and grid color and width for tables has been updated to match the behavior of the previous stable release. As usual, consult the CHANGELOG for a more detailed view of what has changed.

During this development cycle, the new docs for Asciidoctor PDF continued to be improved and reorganized thanks to the work by Sarah. The new docs will go live on https://docs.asciidoctor.org at the same time Asciidoctor PDF 2.0.0 is released.

To reiterate, we don't anticipate having many alpha releases or a long prerelease cycle. We're going to give users a chance to try this release so we can uncover any unexpected regressions, errors, or problem areas. If they come up, we will try to address them quickly so that we can turn around a final release very soon.

Distribution

• RubyGem (asciidoctor-pdf)

Changelog

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)

Release meta

Released on: 2022-04-30
Released by: @mojavelinux
Release beer: Proper Pour by Boulevard Brewing

Logs: resolved issues | full diff

Credits

A very special thanks to all the awesome supporters of the Asciidoctor OpenCollective campaign who provided critical funding for the development of this release as well as ongoing development of the project.