resolves asciidoctor#2013 allow location of anchor for block to be po…

…sitioned relative to content using block-anchor-top key in theme (PR asciidoctor#2048)

CHANGELOG.adoc

@@ -14,6 +14,7 @@ Enhancements::
 * 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 block bottom margins 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 is 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)

docs/theming-guide.adoc

@@ -2389,6 +2389,12 @@ The bottom margin is only added if the block is followed by an adjacent block wi
 
 3+|[#key-prefix-block]*Key Prefix:* <<key-prefix-block,block>>
 
+|anchor-top
+|<<measurement-units,Measurement>> +
+(default: 0)
+|block:
+  anchor-top: -12
+
 //|padding
 //|<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>>
 //|block:

lib/asciidoctor/pdf/converter.rb

@@ -1561,7 +1561,7 @@ def convert_image node, opts = {}
               end
               image_y = y
               image_cursor = cursor
-              add_dest_for_block node, y: image_y if node.id
+              add_dest_for_block node if node.id
               # NOTE: workaround to fix Prawn not adding fill and stroke commands on page that only has an image;
               # breakage occurs when running content (stamps) are added to page
               update_colors if graphic_state.color_space.empty?
@@ -1592,7 +1592,7 @@ def convert_image node, opts = {}
               end
               image_y = y
               image_cursor = cursor
-              add_dest_for_block node, y: image_y if node.id
+              add_dest_for_block node if node.id
               # NOTE: workaround to fix Prawn not adding fill and stroke commands on page that only has an image;
               # breakage occurs when running content (stamps) are added to page
               update_colors if graphic_state.color_space.empty?
@@ -4174,7 +4174,10 @@ def add_dest_for_block node, id: nil, y: nil
           dest_x = bounds.absolute_left.truncate 4
           # QUESTION: when content is aligned to left margin, should we keep precise x value or just use 0?
           dest_x = 0 if dest_x <= page_margin_left
-          dest_y = y || @y
+          unless (dest_y = y)
+            dest_y = @y
+            dest_y += [page_height - dest_y, -@theme.block_anchor_top.to_f].min
+          end
           # TODO: find a way to store only the ref of the destination; look it up when we need it
           node.set_attr 'pdf-destination', (node_dest = (dest_xyz dest_x, dest_y))
           add_dest id, node_dest

spec/admonition_spec.rb

@@ -17,8 +17,25 @@
     (expect admon_page_numbers).to eql [2]
   end
 
-  # NOTE: for now, the margin top setting is ignored, so the test will pass with any value
-  it 'should place anchor below top margin of block' do
+  it 'should place anchor directly at top of block' do
+    input = <<~EOS
+    paragraph
+
+    [NOTE#admon-1]
+    ====
+    filler
+    ====
+    EOS
+
+    lines = (to_pdf input, analyze: :line).lines
+    pdf = to_pdf input
+    (expect (dest = get_dest pdf, 'admon-1')).not_to be_nil
+    (expect dest[:y]).to eql lines[0][:from][:y]
+  end
+
+  it 'should offset anchor from top of block by amount of block_anchor_top' do
+    pdf_theme = { block_anchor_top: -12 }
+
     input = <<~EOS
     paragraph
 
@@ -28,11 +45,10 @@
     ====
     EOS
 
-    pdf_theme = { block_margin_top: 10 }
     lines = (to_pdf input, pdf_theme: pdf_theme, analyze: :line).lines
     pdf = to_pdf input, pdf_theme: pdf_theme
     (expect (dest = get_dest pdf, 'admon-1')).not_to be_nil
-    (expect dest[:y]).to eql lines[0][:from][:y]
+    (expect dest[:y]).to eql (lines[0][:from][:y] + -pdf_theme[:block_anchor_top])
   end
 
   it 'should keep anchor with block if block is advanced to next page' do

spec/image_spec.rb

@@ -13,22 +13,34 @@
     (expect images[0].data).to eql image_data
   end
 
-  # NOTE: for now, the margin top setting is ignored, which this test asserts
-  it 'should place anchor above top margin of block image' do
+  it 'should place anchor directly at top of block image' do
     input = <<~'EOS'
     paragraph
 
     [#tux]
     image::tux.png[Tux]
     EOS
 
-    pdf_theme = { block_margin_top: 10 }
+    images = (to_pdf input, analyze: :image).images
+    pdf = to_pdf input
+    (expect (image_dest = get_dest pdf, 'tux')).not_to be_nil
+    (expect image_dest[:y]).to eql images[0][:y]
+  end
+
+  it 'should offset anchor from top of block image by amount of block_anchor_top' do
+    input = <<~'EOS'
+    paragraph
+
+    [#tux]
+    image::tux.png[Tux]
+    EOS
+
+    pdf_theme = { block_anchor_top: -12 }
 
     images = (to_pdf input, pdf_theme: pdf_theme, analyze: :image).images
     pdf = to_pdf input, pdf_theme: pdf_theme
     (expect (image_dest = get_dest pdf, 'tux')).not_to be_nil
-    #(expect image_dest[:y]).to eql images[0][:y] + 10
-    (expect image_dest[:y]).to eql images[0][:y]
+    (expect image_dest[:y]).to eql (images[0][:y] + -pdf_theme[:block_anchor_top])
   end
 
   it 'should place anchor at top of block image if advanced to next page' do

spec/listing_spec.rb

@@ -51,8 +51,7 @@
     (expect dest[:y]).to eql 805.89
   end
 
-  # NOTE: for now, the margin top setting is ignored, so the test will pass with any value
-  it 'should place anchor below top margin of block' do
+  it 'should place anchor directly at top of block' do
     input = <<~'EOS'
     paragraph
 
@@ -62,13 +61,30 @@
     ----
     EOS
 
-    pdf_theme = { block_margin_top: 10 }
+    lines = (to_pdf input, analyze: :line).lines
+    pdf = to_pdf input
+    (expect (dest = get_dest pdf, 'listing-1')).not_to be_nil
+    (expect dest[:page_number]).to be 1
+    (expect dest[:y]).to eql lines[0][:from][:y]
+  end
+
+  it 'should offset anchor from top of block by value of block_anchor_top' do
+    input = <<~'EOS'
+    paragraph
+
+    [#listing-1]
+    ----
+    listing
+    ----
+    EOS
+
+    pdf_theme = { block_anchor_top: -12 }
 
     lines = (to_pdf input, pdf_theme: pdf_theme, analyze: :line).lines
     pdf = to_pdf input, pdf_theme: pdf_theme
     (expect (dest = get_dest pdf, 'listing-1')).not_to be_nil
     (expect dest[:page_number]).to be 1
-    (expect dest[:y]).to eql lines[0][:from][:y]
+    (expect dest[:y]).to eql (lines[0][:from][:y] + -pdf_theme[:block_anchor_top])
   end
 
   it 'should place anchor at top of block if advanced to next page' do