asciidoctor/asciidoctor-pdf v2.0.0.alpha.1 on GitHub

I'm not even sure where to begin with summarizing this release, which has been in the works for well over two years. While still based on the same technology (Prawn), this release is a drastic improvement over the previous release line (thanks to some clever ingenuity and pure grit). I suppose I should start with the fact that the number of tests increased by almost 1,000 (from 1,032 to 1,890), which now cover 99.5% of the code. You can imagine those increases teased out a lot of bugs, which is reflected in the lengthy CHANGELOG and the 150 resolved issues.

Apart from a plethora of bug fixes, the flagship enhancements this release brings are that blocks are breakable by default, all blocks are arranged using the same logic, extra margin is not added below the last block of a parent, and the theming system is much more comprehensive.

Reworking how blocks are arranged was the primary issue that was holding up this release. Previously, when the converter needed to know the boundaries of a block, it would render the block in a scratch document and return its height. This approach had several key flaws. First, the height in the scratch documented didn't always line up with the height of the block when rendered in the primary document, so the border and background would be off. The process also required that blocks be unbreakable by default in order to work reliably. And it didn't account for orphaned block titles. The logic has been completely rewritten to compute the extent of the block (start and end cursor) with intelligent positioning using multiple passes in order to get an accurate measure of the where the block begins and ends. As part of that change, blocks no longer need to be unbreakable, and thus have been changed to be breakable by default. The new logic also ensures that if no content is written on the first page, or only the block title fits, the block will automatically be advanced to the next page (regardless of whether the block is breakable). You can read more about the requirements and design behind this change in #2003 and #2004 (and the batch of related issues resolved by those issues).

As part of the new arrange block logic, the open block now serves as a generic container for keeping chunks of content together that don't themselves support the unbreakable option. And while tables now support the unbreakable option, this is the mechanism used behind the scenes to achieve that behavior.

Another big enhancement that was holding up the release was an overhaul of margin handling. In previous releases, the converter would add a bottom margin to the last block inside of another block or list. There were some hacks in place to minimize this quirk, but many edge cases still slipped through. The margin handling has been rewritten so that the bottom margin is only added to a block if it is followed by another block within the same enclosure (such as inside a sidebar). Top margins have been dropped and all margins are defined from the bottom edge of the block. With this new logic in place, you should no longer expect to see gaps at the bottom of content, and it drastically simplifies both the theme and the converter code.

For those who've been waiting for it, you can now apply a role defined in a theme to a paragraph. The role can be used to control the font properties, text alignment, and text transform. Speaking of the theme, there are many new categories and keys, and several have been renamed for consistency. There are also several new built-in themes for producing print-optimized PDFs and for replacing the bundle serif font (Noto Serif) with the equivalent sans font. Consult the theming guide for details.

On the compliance front, Asciidoctor PDF 2 will require Ruby 2.7 and JRuby 9.2 at a minimum.

Last but not least, during this development cycle, the docs for Asciidoctor moved to https://docs.asciidoctor.org. Thanks to the work by Sarah, the docs for Asciidoctor PDF are being migrated to join the family.

We do not 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 in a few weeks.

Distribution

RubyGem (asciidoctor-pdf)

Changelog

Enhancements

make delimited blocks breakable by default; require the unbreakable option on the block to retain the previous "keep together" behavior (#2004, #578, #509, #240)
add support for the %unbreakable option on a table to prevent it from being split across pages (#2022, #871, #819, #331)
add support for the %breakable option on a table (special case) to keep the caption and ID with the start of the table (#2022, #993)
implement smart bottom margins on blocks to prevent extra space below blocks, particularly nested blocks (#1515, #1513, #1845)
drop support for top-margin key on block and prose categories in theme; space between delimited blocks and lists now controlled using bottom margins only (#1515)
allow location of anchor for block to be positioned relative to content using block-anchor-top key in theme (#2013)
allow page numbering and running content to start after first page of a document without a title page by assigning an integer to the respective start_at theme key (#1644)
allow page numbering and running content to start after toc (wherever it's placed) by assigning the keyword after-toc to the respective start_at theme key (#1763)
allow theme to configure page numbering to start at cover (#1727)
allow the front and back cover images to be defined in the theme (#1584)
allow the front and back cover images to be specified as a data URI (#1584)
allow theme to control margin and content margin of running content per periphery (header or footer) and per side (recto or verso) (#994)
allow theme to control border style of delimited blocks (example, sidebar, code, admonition, verse, quote) (#1586)
allow theme to control font color of first line of abstract using abstract-first-line-font-color key
allow theme to control background color and border offset (only for background) of links (#1705)
support custom role on paragraph to allow theme to control font properties (#483)
change lead category in theme to built-in role named lead (#2031)
allow theme to control line height of blocks using line-height property where font properties are accepted (#2032)
don't render index section if index is empty (i.e., there are no index entries)
allow title of special section to be hidden by setting untitled option on section
stabilize font paths in built-in themes by prefixing paths with GEM_FONTS_DIR (#1568)
assign page-layout attribute in running content so it can be used to select a background per layout (#1570)
reset numbering of footnotes in each chapter (#1639)
add chapter xreftext to label of footnote reference that refers to previous chapter (#1639)
add support for assigning the same font file to all font variants (i.e., styles) using the wildcard key (*) (#1588)
bundle Noto Sans in addition to Noto Serif and add built-in theme sans-with-fallback-font (#2010)
allow caption max-width to be set to percentage of content by passing argument to fit-content function (#1494)
allow theme to control text alignment of caption independent of box alignment (#1493)
set chapter-numeral attribute in running content on pages in chapter if sectnums attribute is set (#1373)
set part-numeral attribute in running content on pages in part if partnums attribute is set (#1373)
add support for normal_italic font style (to reset font style to normal, then apply italic) (#1603)
honor text alignment roles (e.g., text-left) or list-text-align theme key on callout lists
honor text alignment roles (e.g., text-center) on block image (#1609)
honor role and inherited role on inline image (#1939, #1376)
disable running header and/or footer on toc pages if noheader and/or nofooter option is set on toc macro (#1378)
add support for preamble toc placement
only insert macro toc at location of first toc macro
ignore requested pages not found in imported PDF (#1616)
disable document outline if outline document attribute is unset (#1619)
keep temporary artifacts (for debugging) if KEEP_ARTIFACTS env var is set
define a dest name "toc" at the top of the default toc location
normalize space characters in authors content and drop lines with unresolved attribute references (#1642)
skip image block with missing image if computed alt text resolves to empty string (#1645)
custom theme does not inherit from base theme by default; must be specified explicitly using extends: base (#1640)
allow theme to configure number of index columns using index_columns key (#1663)
configure AsciiDoc table cell to inherit font properties from table and scale font size of nested blocks (#926)
scale font size of literal table cell (#1696)
add support for id attribute on link macro
add support for link attribute on icon macro (#1915)
allow theme to configure width of block border on ends separate from sides (#1693)
add additional glyphs to built-in fonts (heavy checkmark to fallback font; both checkmarks to monospaced font; numero sign to prose and fallback fonts) (#1625)
allow theme to specify text decoration style, color, and width for captions (globally)
allow admonition icon image to be remote (if allow-uri-read is set) or data URI (#1711)
allow theme to configure font color of unresolved footnote using unresolved role
show textual label on admonition if icon image fails to embed (#1741)
allow theme to disable title page by assigning false to title_page category key (#1754)
allow Rouge theme to be specified as theme class or instance (API only)
allow theme to control font size of dot leader in TOC
allow section to override outlinelevels for self and children using outlinelevels attribute on section
use value of author attribute for PDF info and pdfmark if locked by the API (#1778)
only extend theme in extends hierarchy once unless modified with !important (#1800)
add print-optimized themes (default-for-print and default-for-print-with-fallback-font) (#1699)
add support for power operator in theme (with same precedence as multiply and divide) (#1813)
include floor and ceil match characters in fallback font (#1832) (@oddhack)
allow horizontal and vertical lines of table grid to be styled independently (#1875) (@Hextremist)
allow theme to define the characters for typographical quotation marks (#1880) (@klonfish)
allow theme to control top margin of callout lists that immediately follow a code block using callout-list-margin-top-after-code key (#1895)
introduce layout_general_heading to allow extended converter to access node (#1904)
use Document#authors to retrieve authors instead of extracting the information from the indexed document attributes
add support for character references that contain both uppercase and lowercase hexadecimal characters (#1990) (@etiwnad)
log error and skip table instead of raising error if cell content cannot fit into column width of table (#2009)
extract arrange_section method to compute whether section title should be advanced to next page (#2023)
introduce callout-list category in theme to control font properties and item spacing of callout lists (#1722)
only indent inner paragraphs (paragraphs that follow an adjacent paragraph) if prose-text-indent-inner key is set in theme (#2034)
stop and restart conversion in scratch document once the code determines the block does not fit in the available space (#2003)

Bug Fixes

reimplement arrange block logic by using scratch document to compute extent for content block in primary document instead of height (#2003, #2016, #789)
correctly compute height of delimited block attached to description of item in horizontal dlist (follow-up to #2003)
do not crash if item in horizontal description list has no desc
do not crash if item in unordered description list has no desc and do not append subject stop to term
ensure that Time.parse is loaded
resolve images in theme correctly when theme is loaded from classloader (JRuby only) (#1829)
log warning rather than crash if front cover image cannot be embedded (such as a broken SVG)
do not insert blank line in index when term is forced to break (#1665)
honor prepress page margins on subsequent pages in index (#1929)
use more robust strategy for line height normalization that accounts for case when line contains only monospaced text (#1650)
add support for line-height property on lead role as documented
prevent generator from allocating space for placeholder null char (used for anchors) if font is missing glyph (#1672)
ensure background and admonition icon image files are closed after being read (#1566)
ensure temporary images generated by running content are cleaned up (#1566)
fix encoding of indent in wrapped source blocks when font is AFM (#1934)
fix spacing after first line of indented paragraph (#1557)
fix crash if btn or kbd macro is used in section title (#1563)
fix crash when applying text transform to heading cell in table body (#1575)
allow custom inline role to control text transform when it's not the only role on the phrase
do not convert already converted intrinsic width for block and inline SVG
honor font style when looking for glyph in font
resolve character references in custom admonition label (as defined via caption attribute)
convert blocks inside abstract, not just the contents of the blocks
only suggest installing prawn-gmagick gem if not loaded (#1578)
applying double border style to thematic break should honor border width
warn once instead of crashing if page background image cannot be embedded (#1780)
warn once instead of crashing if cache-uri is set but library is not available
sanitize values of PDF info values (#1594)
configure headings to inherit font styles from theme (#1604)
use conum font family defined in theme for conum in verbatim block (#1611)
apply font color and text transform from theme to terms in horizontal dlist (#1994)
prevent content of AsciiDoc table cell from overrunning content on subsequent pages (#1623)
account for top/bottom padding when computing height of AsciiDoc table cell
log error message if table cell is truncated (#1626)
take hard line breaks into account when computing natural width of table cell (#1762)
use "toc" as the default dest name for the macro toc
position page split indicator correctly when block has transparent border
replace block macro with missing PDF target with alt text
consistently use default margin when page margin resolves to empty array
sort page numbers in index numerically instead of lexicographically; sort mixed page number types correctly (#1657)
use informal title prefixed with down indicator for collapsible block (#1660)
don't apply border, shading, or padding to collapsible block (#1660)
escape bare ampersand in attribution and citetitle of quote or verse block (#1662)
fix numeric assertions in test suite (#1542)
prevent converter for list item from inserting new page to position marker when next page is already instantiated (#2001)
keep block anchor with code block when block is moved to next page (#1897)
keep block anchor with admonition block when block is moved to next page
remove poorly-defined (and undocumented) border bottom property for caption
fix crash when theme specifies CMYK value for table border color (#1700)
fallback gracefully if unrecognized convert-time syntax highlighter is used
correctly process a sequence of two or more callouts separated by spaces in a source block (#1898)
allow callouts sub to be disabled on source blocks (#1704)
show missing footnote reference in superscript
fix crash when icons=font and admonition_label_min_width is set in theme
use oembed API over HTTPS to get thumbnail for Vimeo video
show link to Vimeo video if allow-uri-read attribute is not set
don't apply syntax highlighting if Rouge lexer fails to highlight source; show plain source instead
don't apply syntax highlighting to source block if specialchars sub is disabled
apply border bottom to correct table row when frame and grid are disabled (#1873)
allow caption max width to be set by theme to fixed value
fix crash when footnote is defined in section title with auto-generated ID
do not duplicate footnotes in desc of horizontal description list (#1775)
allow an index term to be defined in section title with auto-generated ID
fix alignment of link box for image in running content with numeric vertical alignment
fix vertical center alignment of normal table cell
short-circuit xreftext containing a circular reference path
prevent PDF page import from corrupting references in PDF (#1726)
display decimal list marker correctly when list is reversed (e.g., 10., 09., 08., etc)
use correct spacing for dotted border dash on table (length and spacing should match width)
set color space on page with only image so font color is preserved in running content (#1742)
compute font size for superscript and subscript correctly when parent element uses em and % units (#1745)
respect hyphenation exceptions when word is adjacent to non-word character (#1715)
fix crash when TOC is enabled and index is empty
align TOC section properly when index exceeds one page and section_indent is positive (#1735)
fix left margin drift when indentation is active across a page break (#1735, #1949)
render image at end of section title in corresponding toc entry (#1752)
allow inline image to be enclosed in link macro (alt text was breaking parsing)
prevent inline image from rendering multiple times if fallback font is used for alt text (#1858)
allow theme to set font style of first line of abstract to normal
resize admonition label to fit if height exceeds height of content box
fix crash when underline style is used in Rouge theme
fix crash when Text token is not defined in custom Rouge theme
fix crash when Pygments style is not recognized; fall back to pastie style
avoid loss of precision in CMYK color value for conum or footnote font
use value of untitled-label attribute as fallback value for doctitle in running content (#1772)
use value of untitled-label attribute as fallback value for Title field in pdfmark (follow-up to #1772)
show sensible error message if background image cannot be loaded (e.g., data is corrupt)
honor alignment role when aligning alt text for missing block image
don't crash when rendering alt text for block image if value of align attribute is invalid (#1781)
correctly scale down SVG that only marginally exceeds bounds of page when fit=scale-down
prevent font scale from compounding for nested blocks in AsciiDoc table cell (#2007)
don't suppress actual error message when theme cannot be loaded; may contain information about theme being extended
force inline image to fit within table cell when width is larger than available space (#1798)
hide print annotation for bare email address (#1806)
patch float precision constant so prawn-table does not fail to arrange cells that span columns (#1835)
capture footnotes in AsciiDoc table cell and render them with other footnotes at end of article/chapter (#1777)
prevent PDF from being used as logo image on title page (since it cannot work properly anyway)
don't crash when generating TOC if section title is empty
escape closing square bracket around alt text of missing image so it doesn't get matched as part of a link macro
use value of author attribute in PDF info and pdfmark if authors attribute is not set (#1922)
honor pdf-folio-placement setting even when media=prepress (#1917)
honor pre-wrap role on phrase (#1927)
verify alignment of list marker in AsciiDoc table cell (#1965)
don't crash if value of width attribute on image has invalid format (#1970)
don't render borders and backgrounds in scratch document
don't insert blank page after document title if first block (chapter or toc macro) has nonfacing option (#1988)
coerce negated variable reference to number if value of variable is numeric
prepress page margins should honor value of pdf-folio-placement (#1918)
ensure callout number in callout list stays with primary text when item is advanced to next page (#1967)

Compliance

drop support for Ruby < 2.7 and JRuby < 9.2 (#1681, #2038)
declare the matrix gem as a dependency to fix compatibility with Ruby 3.1
use YAML.safe_load from Ruby stdlib instead of safe_yaml gem
drop deprecated Pdf module alias in API (leaving only PDF)
remove deprecated "ascii" fonts; only bundle the more complete "subset" fonts
remove support for <color> tag in passthrough content; use <font color="..."> instead (may affect themes)
remove asciidoctor-pdf/converter and asciidoctor-pdf/version shim scripts; use asciidoctor/pdf/converter and asciidoctor/pdf/version instead
rename Optimizer#generate_file method to Optimizer#optimize_file
drop support for deprecated pdf-style and pdf-stylesdir attributes (#1827)
drop use of the undocumented vertical-spacing key from the built-in themes
rename the outline-list category in the theme to list and map the outline-list- keys to list- with warning if found (#1894)
rename the literal category in the theme to codespan and map the literal- keys to codespan- with warning if found (#1796)
rename the blockquote category key in the theme to quote and map the blockquote- prefix to quote- with warning if found (#2054)
rename the key category key in theme to kbd and map the key- prefix to kbd- with warning if found (#2052)
remove unneeded _mb functions (e.g., uppercase_mb); multibyte support for upcase, downcase, and capitalize is now provided by corelib

Build / Infrastructure::

migrate Linux CI jobs to GitHub Actions (#1814)
enable CI job on macOS (#1817)
add Ruby 3.1 to CI matrix; use as primary Ruby
test against Asciidoctor upstream (#1821)
skip tests for unreadable files when euid is 0
use prawn-table release and drop recommendation to use the development version (converter now patches prawn-table)

Release meta

Released on: 2022-04-20
Released by: @mojavelinux
Release beer: Rochefort 10 by Brasserie de Rochefort

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.

asciidoctor/asciidoctor-pdf v2.0.0.alpha.1 v2.0.0 Alpha 1 on GitHub