v2.2.0

This is a minor release in the Asciidoctor PDF 2 release line. This release builds on numerous enhancements that were introduced in Asciidoctor PDF 2.

It's now possible to specify a background image per layout by using the {page-layout} attribute reference in the path. You can configure the page margins for rotated pages separately using the page-margin-rotated theme key or pdf-page-margin-rotated document attribute. Inside the theme, you can reference the resolved value of the imagesdir attribute from the document using the {docimagesdir} attribute reference. Instead of having to add the breakable option to all headings to get orphan detection, you can enable it globally in the theme by setting the heading-min-height-after key to the value auto. The theme now accepts a relative font size (e.g., 0.75em) almost anywhere a font size can be set. The font properties of the mark for ordered lists can now be controlled using the olist-marker category. The asciidoctor-pdf CLI now accepts two new options. You can pass --sourcemap to enable the :sourcemap option on the processor for tracking warnings down to the line number. You can use the --theme option as an alternative to -a pdf-theme= to save some typing.

During the development of this release, numerous bugs were founds and fixed. And the documentation conntinues to be improved.

Distribution

• RubyGem (asciidoctor-pdf)

Changelog

Enhancements

• allow page background image to be specified per layout using +{page-layout}+ attribute reference in path (#1739)
• allow page margin for rotated page to be configured independently using page-margin-rotated theme key or pdf-page-margin-rotated document attribute (#1719)
• allow orphan detection to be enabled for all section titles and discrete headings by setting heading-min-height-after to auto in theme (#2268)
• set docimagesdir attribute when attribute substitutions are applied to value from theme (#2278)
• start page numbering and running content on empty verso page before first chapter of prepress book if start-at value is 0 (#2252)
• don't force page break after TOC with automatic placement in article if title-page attribute is set and value of toc-break-after theme key is auto (#1768)
• add --theme option to CLI as shorthand for -a pdf-theme (#2250)
• add --sourcemap option to CLI to enable :sourcemap option on processor (#2265)
• broaden support for relative font sizes in theme to more than just inline elements; document support for relative font sizes
• allow theme to control font properties of marker for ordered list using olist-marker category (#2279)
• allow theme to control font style of marker (per marker or all markers) for unordered list

Improvements

• add internal Document#attr_unspecified? method to simplify check for an attribute which has not been set or unset

Bug Fixes

• always set imagesdir attribute to value of themesdir when resolving images from theme
• allow top keys in title-page theme category to accept a fixed value (e.g., 1in) (#2269)
• prevent orphan detection for heading (section title or discrete heading) from modifying document state (#2288)

Compliance

• configure table borders in way that is compatible with prawn-table > 0.2.2
• don't coerce font size < 1 to relative font size; relative font size should be specified in units

Release meta

Released on: 2022-07-22
Released by: @mojavelinux
Release beer: Superfood Swell by Athletic Brewing Company

Logs: resolved issues | full diff

Credits

A very special thanks to all the awesome supporters of the Asciidoctor OpenCollective campaign, who provide critical funding for the ongoing development of this project.

v2.1.6

This is a patch release in the 2.1.x release line that includes a backport of a bug fix from the 2.2.x release line.

If the font size of a codespan (the codespan key in the theme) is set to a relative value such as 0.9em, the converter will not crash whenn processing a monospace table cell. Asciidoctor 2.2.x will add even broader support for using relative font sizes in the theme.

Distribution

• RubyGem (asciidoctor-pdf)

Changelog

Bug Fixes

• resolve font size for monospaced cell when font size value on codespan key in theme is relative (#2281)

Release meta

Released on: 2022-07-19
Released by: @mojavelinux
Release beer: Trichotomous by 4 Noses Brewing Company

Logs: resolved issues | full diff

Credits

A very special thanks to all the awesome supporters of the Asciidoctor OpenCollective campaign, who provide critical funding for the ongoing development of this project.

v2.1.5

This is a patch release in the 2.1.x release line that includes backports of bug fixes from the 2.2.x release line.

If a block caption has both a background color and an outside margin, the background color will be placed at the location of the text rather than stacked above it. If the font size is set on tables in the theme, the font scaling will not compound in a nested table. Rather, the font size in the nested table will match the font size in the parent table.

Distribution

• RubyGem (asciidoctor-pdf)

Changelog

Bug Fixes

• fix position of background color on caption with outside margin (#2271)
• don't allow font scale to compound when entering nested table (#2276)

Release meta

Released on: 2022-07-10
Released by: @mojavelinux
Release beer: DDH Juicy Bits by WeldWerks Brewing

Logs: resolved issues | full diff

Credits

A very special thanks to all the awesome supporters of the Asciidoctor OpenCollective campaign, who provide critical funding for the ongoing development of this project.

v2.1.4

This is a patch release in the 2.1.x release line that includes backports from the 2.2.x release line. It fixes several issues that have been hiding in the shadows for a long time and enhances the warning message for truncated table cells.

If the alt text for a block image, video, or audio exceeds the width of the content area, the text will wrap to the next line instead of being advanced to the next page. This fix prevents a fixed width table cell from breaching the height of the page. In the event that a table cell does exceed the height of a page, and the sourcemap is enabled, the warning message will include the source location of the cell. The converter will no longer suggest enabling the allow-uri-read attribute if an image target contains a colon, but is not a URL. If a custom role contains the text-transform property, that transform will be applied the value of an attribute reference. Previously, the transform would be applied before attribute references are resolved.

Distribution

• RubyGem (asciidoctor-pdf)

Changelog

Improvements

• include source location in warning message for truncated table cell if sourcemap is enabled (#2261)

Bug Fixes

• allow alt text for block image, video, and audio to wrap to next line on same page (#2258)
• apply text-tranform from custom role on phrase after attributes have been resolved (#2263)
• make URL check more strict so image target containing a colon is not mistaken as a URL

Release meta

Released on: 2022-06-25
Released by: @mojavelinux
Release beer: We Are the Weirdos by Beer Zombies Brewing

Logs: resolved issues | full diff

Credits

A very special thanks to all the awesome supporters of the Asciidoctor OpenCollective campaign, who provide critical funding for the ongoing development of this project.

v2.1.3

This is a patch release in the 2.1.x release line that backports fixes from the 2.2.x release line. It addresses a few minor layout bugs and one hairy bug that was staring us straight in the face.

If the value of either the page-numbering-start-at or running-content-start-at theme key is set to 1, the converter was treating that value as 1 instead of 2. Now it will interpret it as entered. If you import a page using the image macro, the converter will restore the margin and column layout on the page that follows it. Various border-color keys now accept the value transparent rather than causing the converter to crash.

Distribution

• RubyGem (asciidoctor-pdf)

Changelog

Bug Fixes

• interpret start-at theme keys with value 1 correctly (as 1 instead of 2) (#2255)
• restore column layout after importing page(s) from PDF (#2253)
• fix crash when border color is transparent (thematic-break-border-color, admonition-column-rule, quote-border-color, verse-border-color)
• ensure page margin is restored after imported page

Release meta

Released on: 2022-06-23
Released by: @mojavelinux
Release beer: Safe Stream IPA by Athletic Brewing Co.

Logs: resolved issues | full diff

Credits

A very special thanks to all the awesome supporters of the Asciidoctor OpenCollective campaign, who provide critical funding for the ongoing development of this project.

v2.1.2

This is a patch release in the 2.1.x release line. It fixes a few minor bugs. If the layout is changed from portrait to landscape or vice-versa in the main document, that same change is applied to the scratch document. This ensures that the extent of the content block is computed correctly. If an extended converter overrides the get_entries_for_toc method, the converter looks at that result instead of Document#sections? to determine if the TOC should be inserted. And the converter now uses the correct logic to insert an empty page before the TOC with automatic placement in a prepress book.

Numerous updates and enhancements were made to the docs during this release cycle as well.

The 2.2.x release line will be created following this patch release.

Distribution

• RubyGem (asciidoctor-pdf)

Changelog

Bug Fixes

• apply page layout from main document to new page in scratch document (#2248)
• use correct logic to insert page before TOC with automatic placement when doctype=book and media=prepress
• use get_entries_for_toc to determine if the TOC is non-empty rather than Document#sections?

Release meta

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

Logs: resolved issues | full diff

Credits

A very special thanks to all the awesome supporters of the Asciidoctor OpenCollective campaign, who provide critical funding for the ongoing development of this project.

v2.1.1

This is the first patch release in the 2.1.x release line. It's once again focused on the columnar layout, fixing one edge case and providing additional information for extensions. This release also addresses a crash when using CodeRay as the syntax highlighter and a code block uses a source language that CodeRay does not recognize.

An SVG that's shorter than the height of the current column will be placed in the correct column. The Extent for a decorated block provides access to the zero-based column where the block starts (from.column) and where the cursor was when the block was encountered (current.column). This information is used by the extended converter in the docs that demonstrates how to imprint the source language label on a code block.

The converter now draws a border around a phrase with a custom role using the base border color if the role defines a border width without a border color.

Distribution

• RubyGem (asciidoctor-pdf)

Changelog

Improvements

• store zero-based column on Extent for extensions to use to position cursor at start of extent

Bug Fixes

• place block image in SVG format in correct column when align is left and page columns are enabled (#2241)
• accurately trap LoadError from CodeRay if source language is not recognized on code block
• only draw rounded rectangle around phrase if border-radius is > 0
• use base-border-color value if border width is set on role for inline phrase but not border color

Release meta

Released on: 2022-06-14
Released by: @mojavelinux
Release beer: Field Guide by Outer Range Brewing Co.

Logs: resolved issues | full diff

Credits

A very special thanks to all the awesome supporters of the Asciidoctor OpenCollective campaign, who provide critical funding for the ongoing development of this project.

v2.1.0

We did it! We got beyond the Asciidoctor PDF 2.0 release. This is the first minor release in the Asciidoctor PDF 2 release line. This release introduces the long-awaited support for multiple columns on the document body, which is activated using the page-columns theme key. This version also brings support for scaling images relative to the intrinsic width using either the scale attribute or the pdfwidth attribute expressed using a value with the iw unit. Support for text formatting on the index term is honored when the term is displayed in the index. You can avoid a page break between the part and its first chapter by setting the heading-part-break-after theme key to avoid. Finally, a bibliography entry now includes a backlink to the first reference to it in the body of the document.

During the development of this release, numerous bugs were founds and fixed, which have all been backported to the 2.0.x branch and included in the 2.0.8 release.

Don't forget that there are loads of examples of how to extend the converter to customize it to suit your specific publishing needs. See https://docs.asciidoctor.org/pdf-converter/latest/extend/use-cases/

Distribution

• RubyGem (asciidoctor-pdf)

Changelog

Enhancements

• arrange body of article or manpage doctype into multiple columns if page-columns key is set in theme (#327)
• allow column gap to be specified using page-column-gap key (#327)
• introduce convert_index_categories method to handle rendering of categories for index inside column box (#327)
• rename convert_index_list method to convert_index_term to make its purpose more clear (#327)
• add save_theme helper to work with a copy of the theme within a scope (#2196)
• add support for scale attribute or iw unit on pdfwidth attribute on image macros (#1933)
• add backlink from bibref on bibliography entry to first reference to that entry in the document (#1737)
• preserve text formatting on index term in index section (#897)
• don't insert page break between part and first chapter if heading-part-break-after key in theme is avoid (#1795)

Release meta

Released on: 2022-06-10
Released by: @mojavelinux
Release beer: Atomic Torpedo by Sierra Nevada Brewing Co.

Logs: resolved issues | full diff

Credits

A very special thanks to all the awesome supporters of the Asciidoctor OpenCollective campaign, who provide critical funding for the ongoing development of this project.

v2.0.8

This is a patch release in the 2.0.x release line focused on fixing various rendering bugs when the content in the document body is arranged into columns. These issues were discovered while working on multi-column support in the main branch. Although support for multiple columns is not included in this release line, users who are using an extended converter to add multi-column support will benefit from these fixes. The main fix is that the converter correctly computes the value of end cursor of an extent when the column box starts below top of page. The code for how columns are handled in the scratch document has also been refactored so that the logic is encapsulated in the ColumnBox class.

This is also the first release where the release notes were generated automatically (except for this summary) as part of the release process.

Distribution

• RubyGem (asciidoctor-pdf)

Changelog

Improvements

• encapsulate logic to adjust column box inside float and dry run
• automatically set height on column box if not specified; update value automatically when reflowing margins

Bug Fixes

• correctly compute value of to cursor on extent when column box starts below top of page (#2230)
• fix crash in ColumnBox#move_past_bottom when :reflow_margins option is not set
• fix x position of SVG when advanced to next column of column box
• at_page_top? should consider top of column box to be top of page
• prevent SVG image taller than column from being advanced to next column
• don't push section that follows index section in article to new page if last page of index does not extend to bottom of page

Release meta

Released on: 2022-06-08
Released by: @mojavelinux
Release beer: Houblon Deluxe by Pure Project Brewing

Logs: resolved issues | full diff

Credits

A very special thanks to all the awesome supporters of the Asciidoctor OpenCollective campaign, who provide critical funding for the ongoing development of this project.

v2.0.7

This patch release focuses on fixes related to image processing and rendering. First, it fixes a crash if an inline image without an explicit width is used in the doctitle or a section title with an automatic ID. The converter now delegates to prawn-gmagick, if available, to read an image referenced in an SVG, thus adding support for more formats and improving performance. The path of that image can now refer to any location within the Asciidoctor jail (i.e., base dir) rather than being restricted to the docdir. When prawn-gmagick is not available, and the converter encounters a corrupt or incomplete PNG or JPG, it will not recommend using prawn-gmagick (as the problem is with the image data, not the format). The prawn-gmagick integration is now verified to work on macOS.

This release was the first test of automating the release notes. The script didn't work entirely, but we're a step closer.

Distribution

• RubyGem (asciidoctor-pdf)

Changelog

Improvements

• don't recommend prawn-gmagick if PNG or JPG is corrupt or incomplete
• add helper method to determine when to recommend the prawn-gmagick gem

Bug Fixes

• fix crash when doctitle or section title with automatic ID contains inline image without explicit width (#2228)
• use prawn-gmagick, if available, to read raster image referenced by SVG (#2223)
• allow image path in SVG to refer to any location within Asciidoctor jail (no restriction if safe mode is unsafe) (#1941)

Release meta

Released on: 2022-06-03
Released by: @mojavelinux
Release beer: Living the Ska Dream by Living the Dream Brewing

Logs: resolved issues | full diff

Credits

A very special thanks to all the awesome supporters of the Asciidoctor OpenCollective campaign, who provide critical funding for the ongoing development of this project.