resolves #1210 allow theme to control min height required after section (PR #1220)

- allow theme to control min height required after section to keep on same page
- don't shift section to next page if requirement isn't met and section is empty

6 files changed, 68 insertions, 4 deletions

diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc
index 1d492d03..af807aef 100644
--- a/CHANGELOG.adoc
+++ b/CHANGELOG.adoc
@@ -17,6 +17,7 @@ For a detailed view of what has changed, refer to the {uri-repo}/commits/master[
 * don't rely on base_line_height_length theme key in converter (should be internal to theme)
 * set fallback value for base (root) font size
 * reduce min font size in base theme
+* allow theme to configure the minimum height required after a section title for it to stay on same page (#1210)
 * convert hyphen to underscore in theme key for admonition icon type (#1217)
 * always resolve images in running content relative to themesdir (instead of document) (#1183)
 * honor text alignment role on abstract paragraph(s)
diff --git a/data/themes/base-theme.yml b/data/themes/base-theme.yml
index 4fdcd328..8036fdde 100644
--- a/data/themes/base-theme.yml
+++ b/data/themes/base-theme.yml
@@ -40,6 +40,7 @@ heading_h6_font_size: 10
 heading_line_height: 1.15
 heading_margin_top: 4
 heading_margin_bottom: 12
+heading_min_height_after: 20
 title_page_align: center
 title_page_line_height: 1.15
 title_page_logo_top: 10%
diff --git a/data/themes/default-theme.yml b/data/themes/default-theme.yml
index e26898ff..5293b336 100644
--- a/data/themes/default-theme.yml
+++ b/data/themes/default-theme.yml
@@ -102,6 +102,7 @@ heading:
   line_height: 1
   margin_top: $vertical_rhythm * 0.4
   margin_bottom: $vertical_rhythm * 0.9
+  min_height_after: $base_line_height_length * 1.5
 title_page:
   align: right
   logo:
diff --git a/docs/theming-guide.adoc b/docs/theming-guide.adoc
index a2cb2e13..ee2e9f5b 100644
--- a/docs/theming-guide.adoc
+++ b/docs/theming-guide.adoc
@@ -1431,6 +1431,12 @@ The keys in this category control the style of most headings, including part tit
 |heading:
   margin-bottom: 9.6
 
+|min-height-after
+|<<measurement-units,Measurement>> +
+(default: $base-font-size * $base-line-height * 1.5)
+|heading:
+  min-height-after: 0.5in
+
 |chapter-break-before
 |always {vbar} auto +
 (default: always)
diff --git a/lib/asciidoctor-pdf/converter.rb b/lib/asciidoctor-pdf/converter.rb
index b525fe67..d2752cb7 100644
--- a/lib/asciidoctor-pdf/converter.rb
+++ b/lib/asciidoctor-pdf/converter.rb
@@ -530,10 +530,15 @@ class Converter < ::Prawn::Document
           start_new_part sect unless @theme.heading_part_break_before == 'auto'
         end
       end
-      # FIXME smarter calculation here!!
-      unless cursor > (height_of title) + (@theme.heading_margin_top || 0) + (@theme.heading_margin_bottom || 0) + (@root_font_size * @theme.base_line_height * 1.5)
-        start_new_page
-      end unless at_page_top?
+      unless at_page_top?
+        # FIXME this height doesn't account for impact of text transform or inline formatting
+        heading_height =
+          (height_of_typeset_text title, line_height: (@theme[%(heading_h#{hlevel}_line_height)] || @theme.heading_line_height)) +
+          (@theme[%(heading_h#{hlevel}_margin_top)] || @theme.heading_margin_top || 0) +
+          (@theme[%(heading_h#{hlevel}_margin_bottom)] || @theme.heading_margin_bottom || 0)
+        heading_height += (@theme.heading_min_height_after || 0) if sect.blocks?
+        start_new_page unless cursor > heading_height
+      end
       # QUESTION should we store pdf-page-start, pdf-anchor & pdf-destination in internal map?
       sect.set_attr 'pdf-page-start', (start_pgnum = page_number)
       # QUESTION should we just assign the section this generated id?
diff --git a/spec/section_spec.rb b/spec/section_spec.rb
index 40cec9a1..26d38dee 100644
--- a/spec/section_spec.rb
+++ b/spec/section_spec.rb
@@ -273,6 +273,56 @@ describe 'Asciidoctor::PDF::Converter - Section' do
     (expect text[2][:font_size]).to eql 10.5
   end
 
+  it 'should not force title of empty section to next page if it fits on page' do
+    pdf = to_pdf <<~EOS, analyze: true
+    == Section A
+
+    [%hardbreaks]
+    #{(['filler'] * 41).join ?\n}
+
+    == Section B
+    EOS
+
+    section_b_text = (pdf.find_text 'Section B')[0]
+    (expect section_b_text[:page_number]).to eql 1
+  end
+
+  it 'should force section title to next page to keep with first line of section content' do
+    pdf = to_pdf <<~EOS, analyze: true
+    == Section A
+
+    [%hardbreaks]
+    #{(['filler'] * 41).join ?\n}
+
+    == Section B
+
+    content
+    EOS
+
+    section_b_text = (pdf.find_text 'Section B')[0]
+    (expect section_b_text[:page_number]).to eql 2
+    content_text = (pdf.find_text 'content')[0]
+    (expect content_text[:page_number]).to eql 2
+  end
+
+  it 'should not force section title to next page to keep with content if heading_min_height_after is zero' do
+    pdf = to_pdf <<~EOS, pdf_theme: { heading_min_height_after: 0 }, analyze: true
+    == Section A
+
+    [%hardbreaks]
+    #{(['filler'] * 41).join ?\n}
+
+    == Section B
+
+    content
+    EOS
+
+    section_b_text = (pdf.find_text 'Section B')[0]
+    (expect section_b_text[:page_number]).to eql 1
+    content_text = (pdf.find_text 'content')[0]
+    (expect content_text[:page_number]).to eql 2
+  end
+
   it 'should not add break before chapter if break-before key in theme is auto' do
     pdf = to_pdf <<~'EOS', pdf_theme: { heading_chapter_break_before: 'auto' }, analyze: true
     = Document Title