1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
|
= Breakable and Unbreakable Blocks
:description: By default, most blocks are breakable with built-in anchor and caption orphan prevention. The unbreakable option prevents a block from breaking across pages.
Asciidoctor PDF gives the author some control over where content blocks are placed using the `unbreakable` and `breakable` options, and tries to provide sensible defaults when these options are not used.
[#default]
== Breakable by default
The following blocks are breakable by default.
This breakable behavior includes automatic anchor and caption orphan prevention.
* Admonitions
* Block images
* Code blocks (literal, listing, and source)
* Examples
* Open blocks
* Quote blocks
* Sidebars
* 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 with the block.
Tables and sections are breakable by default, but do not provide automatic anchor and caption orphan prevention.
For tables, that means the anchor and caption can be left on the current page if the table is advanced to the next page.
For sections, that means the section's title may be left on the current page if the first content block doesn't fit.
However, you can turn on orphan prevention for tables and sections by adding the (seemingly redundant) `breakable` option as a hint.
[#breakable]
== Breakable option
Orphan prevention isn't applied to tables and sections by default.
The `breakable` option can be applied to a table to ensure the anchor and caption are kept with the table if it gets advanced to the next page.
[,asciidoc]
----
.Optional table title
[#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 be applied to a section to ensure the title is kept with the first block of content if the first block gets advanced to the next page.
[,asciidoc]
----
[%breakable]
=== Title of a section
First block of content in the section.
----
You don't need to assign the `breakable` option any other block types because <<default,it is enabled 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 and it can fit on a single page.
[,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 with the `unbreakable` option is taller than a single page, it will not be advanced and, instead, break across pages.
In this case, the automatic orphan protection is still applied.
The converter does not honor the `unbreakable` option on all content blocks in AsciiDoc, such as lists and paragraphs.
In these cases, the author can elect to wrap the content in an open block with the `unbreakable` option.
[,asciidoc]
----
[%unbreakable]
--
If this paragraph does not fit in the remaining space on this page,
and it is short enough to fit on a page by itself,
the converter will advance it to the next page so it does not break.
--
----
Internally, the open block enclosure is exactly how `unbreakable` is supported on tables.
[#dry-run-performance]
.Why can't I assign unbreakable globally? Why don't sections and tables have orphan prevention by default?
****
The logic in the converter that calculates the extent of a block, which includes its title, main content, and padding, uses multiple passes, called "`dry runs`", to get an accurate measurement of where a block begins, ends, and 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 convert it again in order to redo the extent calculation.
This logic is vital for decorating the block with a border and background because the extent must be pixel accurate.
All these dry runs add additional processing time and effort to the conversion.
Making all blocks unbreakable by default adds a lot of extra steps (not to mention leaving behind a lot of gaps in the document).
Orphan prevents adds almost as many since it's a similar process.
Doing that by default for tables and sections would be too complex and costly.
To recoup some of the processing time, we decided to make some trade-offs.
Therefore, blocks are breakable by default and authors must opt-in to get orphan prevention for tables and sections.
****
|
