update extended converter that avoids a page break after a heading and use it in the test case

3 files changed, 43 insertions, 37 deletions

diff --git a/docs/modules/extend/examples/pdf-converter-avoid-break-after-heading.rb b/docs/modules/extend/examples/pdf-converter-avoid-break-after-heading.rb
new file mode 100644
index 00000000..a024cdf3
--- /dev/null
+++ b/docs/modules/extend/examples/pdf-converter-avoid-break-after-heading.rb
@@ -0,0 +1,32 @@
+class PDFConverterAvoidBreakAfterSectionTitle < (Asciidoctor::Converter.for 'pdf')
+  register_for 'pdf'
+
+  def arrange_heading node, title, opts
+    return if y >= page_height / 3 # <1>
+    orphaned = nil
+    dry_run single_page: true do # <2>
+      start_page = page
+      theme_font :heading, level: opts[:level] do
+        if opts[:part]
+          ink_part_title node, title, opts # <3>
+        elsif opts[:chapterlike]
+          ink_chapter_title node, title, opts # <3>
+        else
+          ink_general_heading node, title, opts # <3>
+        end
+      end
+      if page == start_page
+        page.tare_content_stream
+        orphaned = stop_if_first_page_empty do # <4>
+          if node.context == :section
+            traverse node
+          else # discrete heading
+            convert (siblings = node.parent.blocks)[(siblings.index node).next]
+          end
+        end
+      end
+    end
+    start_new_page if orphaned # <5>
+    nil
+  end
+end
diff --git a/docs/modules/extend/examples/pdf-converter-avoid-break-after-section-title.rb b/docs/modules/extend/examples/pdf-converter-avoid-break-after-section-title.rb
deleted file mode 100644
index 28f01c78..00000000
--- a/docs/modules/extend/examples/pdf-converter-avoid-break-after-section-title.rb
+++ /dev/null
@@ -1,26 +0,0 @@
-class PDFConverterAvoidBreakAfterSectionTitle < (Asciidoctor::Converter.for 'pdf')
-  register_for 'pdf'
-
-  def arrange_section sect, title, opts = {}
-    return if @y >= (@margin_box.absolute_top / 3) # <1>
-    orphaned = nil
-    dry_run single_page: true do # <2>
-      start_page = page
-      theme_font :heading, level: opts[:level] do
-        if opts[:part]
-          ink_part_title sect, title, opts # <3>
-        elsif opts[:chapterlike]
-          ink_chapter_title sect, title, opts # <3>
-        else
-          ink_general_heading sect, title, opts # <3>
-        end
-      end
-      if page == start_page
-        page.tare_content_stream
-        orphaned = stop_if_first_page_empty { traverse sect } # <4>
-      end
-    end
-    start_new_page if orphaned # <5>
-    nil
-  end
-end
diff --git a/docs/modules/extend/pages/use-cases.adoc b/docs/modules/extend/pages/use-cases.adoc
index 2c18941f..54aa339b 100644
--- a/docs/modules/extend/pages/use-cases.adoc
+++ b/docs/modules/extend/pages/use-cases.adoc
@@ -108,27 +108,27 @@ Then, you can add this number in the left margin at the start of each paragraph
 include::example$pdf-converter-numbered-paragraphs.rb[]
 ----
 
-== Avoid break after section title
+== Avoid break after heading
 
-This functionality is already provided by the converter if you set the `breakable` option on section title.
-The code is presented here to explain how it works and if you want to make this behavior automatic.
+This functionality is already provided by the converter if you set the `breakable` option on section title or discrete heading.
+The code is presented here both to explain how it works and to use to make this behavior automatic.
 
-If the section title is followed by content that doesn't fit on the current page, and the `breakable` option is not set on the section title, the converter will leave the section title behind, making it an orphan.
-You can fix this behavior by overridding the `arrange_section` method in an extended converter.
+If an in-flow heading is followed by content that doesn't fit on the current page, and the `breakable` option is not set on the heading, the converter will orphan the heading on the current page.
+You can fix this behavior by overridding the `arrange_heading` method in an extended converter.
 
-This extended converter takes this opportunity to use `dry_run` to make an attempt to write content in the remaining space on the page.
-If no content is written, it advances to the next page before the section title is written.
+This extended converter takes this opportunity to use `dry_run` to make an attempt to write content in the remaining space on the page after the heading.
+If no content is written, it advances to the next page before inking the heading (and its corresponding anchor).
 
-.Extended converter that avoids a page break after a section title
+.Extended converter that avoids a page break after a heading
 [,ruby]
 ----
-include::example$pdf-converter-avoid-break-after-section-title.rb[]
+include::example$pdf-converter-avoid-break-after-heading.rb[]
 ----
 <.> An optional optimization to skip this logic if the cursor is above the bottom third of the page.
 <.> Initiate a dry run up to the end of the current page.
-<.> Render the section title as normal.
+<.> Render the heading as normal.
 <.> Proceed with converting content until the end of the page is reached. Returns true if content is written, false otherwise.
-<.> Start new page before rendering section title if orphaned.
+<.> Start new page before rendering heading if orphaned.
 
 == Additional TOC entries