document breakable and unbreakable options (PR #2135)

7 files changed, 144 insertions, 30 deletions

diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
index 46f0e48c..c2bab2be 100644
--- a/docs/modules/ROOT/nav.adoc
+++ b/docs/modules/ROOT/nav.adoc
@@ -10,9 +10,9 @@
 * xref:import-pdf-pages.adoc[]
 * xref:interdocument-xrefs.adoc[]
 * xref:roles.adoc[]
-* xref:verbatim-blocks.adoc[]
-** xref:syntax-highlighting.adoc[]
-** xref:autofit-text.adoc[]
+* xref:breakable-and-unbreakable.adoc[]
+* xref:syntax-highlighting.adoc[]
+* xref:autofit-text.adoc[]
 * xref:stem.adoc[]
 * xref:passthrough-content.adoc[]
 * xref:autowidth-tables.adoc[]
diff --git a/docs/modules/ROOT/pages/breakable-and-unbreakable.adoc b/docs/modules/ROOT/pages/breakable-and-unbreakable.adoc
new file mode 100644
index 00000000..0ebfdd4e
--- /dev/null
+++ b/docs/modules/ROOT/pages/breakable-and-unbreakable.adoc
@@ -0,0 +1,96 @@
+= Breakable and Unbreakable Options
+:description: By default, most blocks are breakable with built-in anchor and caption orphan prevention. The unbreakable option prevents a block from breaking.
+
+[#default]
+== Default breakable behavior
+
+The following blocks are breakable with built-in anchor and caption orphan prevention by default:
+
+* Admonitions
+* Block images
+* Code blocks (literal, listing, and source)
+* Examples
+* Open blocks
+* Quote blocks
+* Sidebars
+* Table of Contents
+* Verses
+
+[.term]*Breakable with built-in anchor and caption orphan prevention* means that a block can break across pages but the converter will automatically move the block to the next page, when necessary, to ensure a block's anchor and caption are kept together with the block.
+
+Tables and section headings are only breakable by default.
+That means table captions may be orphaned if a table breaks across pages, and a section heading and its first content block aren't kept together automatically.
+However, orphan prevention can be applied to individual section headings and tables using the `breakable` option.
+
+[#breakable]
+== Breakable option
+
+Orphan prevention isn't applied to tables and section headings by default.
+The `breakable` option can be applied to a table to ensure that a table's anchor and caption are kept together with the table if it breaks across pages.
+
+[,asciidoc]
+----
+.Optional table caption
+[#optional-id%breakable] <.>
+|===
+|Content |Content
+
+|Content |Content
+|===
+----
+<.> Assign the `breakable` option to a table, using the shorthand percent symbol (`%`) for the `option` attribute name, to indicate that the table's caption and anchor should be kept with the table.
+
+The `breakable` option can also be applied to a section title to keep the title and its anchor with the first block of content in the section.
+
+[,asciidoc]
+----
+[%breakable]
+=== Title of a section
+
+First block of content in the section.
+----
+
+Don't assign the `breakable` option any other block types because <<default,caption and anchor orphan prevention is automatically applied to them by default>>.
+
+[#unbreakable]
+== Unbreakable option
+
+When the `unbreakable` option is applied to a block, the converter will advance the block and its caption and anchor to the next page if it detects that the block would break across pages.
+
+[,asciidoc]
+----
+.Optional title of block
+[%unbreakable] <.>
+====
+Content in an example block.
+
+More content in an example block.
+====
+----
+<.> Assign the `unbreakable` option to a block, using the shorthand percent symbol (`%`) for the `option` attribute name, to prevent the block from breaking across pages.
+
+The `unbreakable` option can be assigned to individual blocks of the following types:
+
+* Admonitions
+* Block images
+* Code blocks (literal, listing, and source)
+* Examples
+* Open blocks
+* Quote blocks
+* Sidebars
+* Tables
+* Verses
+
+If a block is larger than a single page, it will break across pages even if it's assigned the `unbreakable` option.
+
+[#dry-run-performance]
+.Why can't I assign unbreakable globally? Why don't section headings and tables have built-in orphan prevention?
+****
+The logic in the converter that calculates the extent of a block, which includes its anchor, title, borders, background, and all applicable margins and paddings, uses multiple passes -- what we call "`dry runs`" -- to get an accurate measure of where the block begins and ends, and therefore, whether it breaks across pages.
+When the converter determines that a block's caption and anchor would be orphaned or that a block breaks when it's marked as unbreakable, it has to advance to the next page and potentially repeat the extent calculation depending on the block's context.
+Background shading and borders--styles that are applied to code blocks, examples, and sidebars by default, that are often applied to tables, and that can be applied to other block types and section headings--add significant complexity, and therefore processing time, to the dry runs required to calculate each block's extent.
+
+We decided it was best for people to opt-in to the converter behavior required for `unbreakable` and table and section heading orphan prevention (`breakable`) on an individual block basis due to the performance costs.
+****
+
+
diff --git a/docs/modules/ROOT/pages/optimize-pdf.adoc b/docs/modules/ROOT/pages/optimize-pdf.adoc
index 3dbab6f0..48498847 100644
--- a/docs/modules/ROOT/pages/optimize-pdf.adoc
+++ b/docs/modules/ROOT/pages/optimize-pdf.adoc
@@ -10,13 +10,6 @@ If you don't do this step, the platform may reject your upload or fail to displa
 (For KDP, `-a optimize` works best.
 For GitLab repository preview, either `-a optimize` or `hexapdf optimize` will do the trick.)
 
-== Shaded blocks and performance
-
-Certain blocks are rendered with a shaded background, such as verbatim (listing, literal, and source), sidebar, and example blocks.
-In order to calculate the dimensions of the shaded region, Asciidoctor PDF has to "`dry run`" the block to determine how many pages it consumes.
-While this strategy has a low impact when processing shorter blocks, it can drastically deteriorate performance when processing a block that spans dozens of pages.
-As a general rule of thumb, you should avoid using shaded blocks which span more than a handful of pages.
-
 == Enable stream compression
 
 A simple way to reduce the size of the PDF file is to enable stream compression (using the FlateDecode method).
diff --git a/docs/modules/ROOT/pages/verbatim-blocks.adoc b/docs/modules/ROOT/pages/verbatim-blocks.adoc
deleted file mode 100644
index cbb910f0..00000000
--- a/docs/modules/ROOT/pages/verbatim-blocks.adoc
+++ /dev/null
@@ -1,10 +0,0 @@
-= Verbatim Blocks
-
-Verbatim blocks are listing, literal, and source blocks.
-
-== Verbatim blocks and performance
-
-Verbatim blocks are rendered with a shaded background.
-In order to calculate the dimensions of the shaded region, Asciidoctor PDF has to "`dry run`" the block to determine how many pages it consumes.
-While this strategy has a low impact when processing shorter blocks, it can drastically deteriorate performance when processing a block that spans dozens of pages.
-As a general rule of thumb, you should avoid creating verbatim blocks which span more than a handful of pages.
diff --git a/docs/modules/ROOT/pages/whats-new.adoc b/docs/modules/ROOT/pages/whats-new.adoc
index 75cca1dc..5cd29755 100644
--- a/docs/modules/ROOT/pages/whats-new.adoc
+++ b/docs/modules/ROOT/pages/whats-new.adoc
@@ -23,6 +23,31 @@ See xref:theme:role.adoc#built-in[Built-in roles] for details.
 To control the indent of inner paragraphs, you can set the new `prose-text-indent-inner` key in your theme.
 See xref:theme:prose.adoc[] for details.
 
+[#breakable]
+== Breakable by default
+
+In Asciidoctor PDF 2.0, the following blocks are breakable with automatic anchor and caption orphan prevention by default:
+
+* Admonitions
+* Block images
+* Code blocks (literal, listing, and source)
+* Examples
+* Open blocks
+* Quote blocks
+* Sidebars
+* Table of Contents
+* Verses
+
+Tables and section headings are only breakable by default.
+That means table captions may be orphaned if a table breaks across pages, and a section heading and its first content block aren't kept together automatically.
+However, orphan prevention can be applied to individual section headings and tables using the xref:breakable-and-unbreakable.adoc#breakable[breakable option].
+
+[#unbreakable]
+== Unbreakable option
+
+The `unbreakable` option can be applied to delimited blocks, admonitions, and tables.
+When the xref:breakable-and-unbreakable.adoc#unbreakable[unbreakable option] is applied to a block, the converter will advance the block and its caption and anchor to the next page if it detects that the block would break across pages.
+
 == Blocks and block captions
 
 Blocks and block captions gained a lot of new features in Asciidoctor PDF 2.0.
@@ -30,10 +55,10 @@ Here are just a few of the highlights:
 
 Smart bottom margins::
 Blocks now have smarter bottom margins that prevent extra space from being added below them, particularly when blocks are nested.
-xref:theme:blocks.adoc#border-width[Border width]::
-The border width of delimited blocks, admonitions, and block images can be customized per edge with the `border-width` key.
-xref:theme:blocks.adoc#border-style[Border style]::
-The border style of delimited blocks, admonitions, and block images can be changed with the `border-style` key.
+Border width::
+The border width of delimited blocks, admonitions, and block images can be customized per edge with the xref:theme:blocks.adoc#border-width[border-width key].
+Border style::
+The border style of delimited blocks, admonitions, and block images can be changed with the xref:theme:blocks.adoc#border-style[border-style key].
 Styles include dashed, dotted, double, and solid.
 Line height::
 Wherever font properties are accepted in the theme, you can now control the line height of blocks using the `line-height` key.
@@ -58,12 +83,22 @@ Allow caption `max-width` to be set to percentage of content by passing argument
 Border widths and styles::
 The table border width can be customized per edge with the xref:theme:blocks.adoc#border-width[border-width key].
 The border line style can be xref:theme:tables.adoc#border-style[specified per edge by assigning an array of styles] to the `border-style` key.
+Styles include dashed, dotted, and solid.
 
 Grid widths and styles::
 The width of table grid lines can be specified for rows and columns with the xref:theme:tables.adoc#grid-width[grid-width key].
 The style of the grid lines can be specified for rows and columns with the xref:theme:tables.adoc#grid-style[grid-style key].
+Styles include dashed, dotted, and solid.
 //allow horizontal and vertical lines of table grid to be styled independently (#1875) (*@hextremist*)
 
+.*Notable fixes for tables*
+* An error message is logged if table cell is truncated.
+* Instead of raising an error, log error and skip table if cell content can't fit into column width of table.
+* The content of AsciiDoc table cell is prevented from overrunning content on subsequent pages.
+* The top and bottom padding is taken into account when computing height of AsciiDoc table cell.
+* Vertical center alignment is correctly applied to regular table cells.
+* The border bottom is correctly applied to a table row when frame and grid are disabled.
+
 == Callout lists and numbers
 
 The theming language now has a xref:theme:callout.adoc[callout-list category].
diff --git a/docs/modules/theme/nav.adoc b/docs/modules/theme/nav.adoc
index c4b57b53..f9ba6456 100644
--- a/docs/modules/theme/nav.adoc
+++ b/docs/modules/theme/nav.adoc
@@ -1,10 +1,6 @@
 * xref:index.adoc[]
 ** xref:language.adoc[]
 *** xref:measurement-units.adoc[]
-*** xref:blocks.adoc[]
-*** xref:tables.adoc[]
-*** xref:text.adoc[]
-*** xref:image.adoc[]
 *** xref:color.adoc[]
 *** xref:variables.adoc[]
 *** xref:math-operations.adoc[]
@@ -14,6 +10,10 @@
 *** xref:prepare-custom-font.adoc[]
 *** xref:fallback-font.adoc[]
 *** xref:cjk.adoc[]
+** xref:blocks.adoc[]
+** xref:tables.adoc[]
+** xref:text.adoc[]
+** xref:image.adoc[]
 ** xref:extend-theme.adoc[]
 ** xref:custom-role.adoc[]
 ** xref:add-running-content.adoc[]
diff --git a/docs/modules/theme/pages/table.adoc b/docs/modules/theme/pages/table.adoc
index fbf7e3f8..3e6563b8 100644
--- a/docs/modules/theme/pages/table.adoc
+++ b/docs/modules/theme/pages/table.adoc
@@ -20,7 +20,7 @@ table:
   background-color: #FFFFFF
 
 |border-color
-|xref:tables.adoc#border-color[Color] {vbar} xref:tables.adoc#border-color[Color[\]] +
+|xref:tables.adoc#border-color[Color] {vbar} xref:tables.adoc#border-color[Color[ \]] +
 (default: `'000000'`)
 |[source]
 table:
@@ -113,7 +113,7 @@ table:
   grid-color: #EEEEEE
 
 |grid-style
-|xref:tables.adoc#grid-style[Grid style]` {vbar} xref:tables.adoc#grid-style[Grid style[ \]] +
+|xref:tables.adoc#grid-style[Grid style] {vbar} xref:tables.adoc#grid-style[Grid style[ \]] +
 (default: `$table-border-style`)
 |[source]
 table: