asciidoctor-rhrev 1.9.2 → 1.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1da65b61e67581cc903950852a590dbd89c965414c2abaa40059bb8f445e4c6a
-  data.tar.gz: 2d6fa89231f2724df9152df5346318a05dfdf1465eb64dfd9d29df114ab6e9fa
+  metadata.gz: 98b0e2be6dfcba7e7865f380b4bcffe103bc94114ef1e7c4164cb90e2ecc463d
+  data.tar.gz: abbd012a8186d9f28cb9e438467dd1dfa741cbb9cf9f7dee83ad777765ad8a73
 SHA512:
-  metadata.gz: 3eb4539c96fbdfb34d70335963d9312121ef2a5c93af4f049731822d0ee236b9c8d2feaf296c225e5e50b12486a599da539ff98e6c79948ff0e573991535cf41
-  data.tar.gz: 9fe21ece1dd48a8d1c4acc605ad1b4fb9872296ff56a2438f9ccf9689d218c392899ea4c243a879957754b9bc537fd807a8b5e279b967f2d25b77c6aca6372ab
+  metadata.gz: 536952505824ad5d26f9338bd1e8ee77c43da3e585b6590845fd56bb76014ccec742a35d25c51ab1d908b2a79775c5feb9c1877d39cedd7af2e9f7418224e23a
+  data.tar.gz: 6508ab015c404efb30b4f4f841d09d4204289c9979eca9f178ae8ca2e9c4f1431c65ebd0519af2cac7374515efe056eb3381d1eca5a532c1a8ac8bd5f1bdad4d

data/CHANGELOG.adoc

@@ -1,5 +1,10 @@
 = Changelog
 
+== 1.10.0 (2026-10-28)
+
+* Change bar links, enabled with `rhrev-change-bars-link` alongside `rhrev-change-bars` (PDF backend). Every change bar links to the revision history row of its change, and each filled column of a change bar table links to the row of its own revision. A block that rolls up into its section's row or into the `all` entry links to that row, a table cell links to its table's row, and a block without a row of its own links to its revision's header row. The link of a bar also covers the gap between the text and the bar. Links of nested blocks sit above their section's link, so a click follows the innermost change. The revision history table carries one named destination per row, header, and `all` entry. New regression file `tests/regression/change-bar-links.rb` (gem)
+* Note: gem-only; the Antora extension is unaffected, npm still bumps concurrently per the standing 1.5.1 policy
+
 == 1.9.2 (2026-10-27)
 
 * Change bar table labels stand upright, one character per line, read from top to bottom, with the labels of all columns sharing one bottom line; labels no longer turn 90 degrees. `ink_change_bar_table_label` draws each label (gem)

data/lib/asciidoctor/rhrev/change_bars.rb

@@ -22,6 +22,12 @@ module Asciidoctor
       # filled, and every page with a box labels each column at the top of
       # its body, so an isolated change still shows which revision it is.
       # Without lanes, as in collapse mode, table draws the bar too.
+      #
+      # With rhrev-change-bars-link set, every bar and every filled table
+      # column links to the revision history row of the change it marks:
+      # each bar records the marked node it inks for, and once the
+      # revision history has rendered with a named destination on every
+      # row, ink_change_bar_links annotates the recorded areas.
       module ChangeBars
         CHANGE_BAR_STYLES = %w(bar table).freeze
 
@@ -48,6 +54,12 @@ module Asciidoctor
           @change_bar_section_stack = []
           @change_bar_grid_labeled_pages = {}
           @change_bar_margin_warned = false
+          if doc.attr? 'rhrev-change-bars-link'
+            @change_bar_links = []
+            @change_bar_link_dests = ::Set.new
+          else
+            @change_bar_links = @change_bar_link_dests = nil
+          end
         end
 
         # Resolved lazily on first ink: the theme (and @media/@folio_placement)
@@ -129,7 +141,7 @@ module Asciidoctor
         end
 
         def record_change_bar_start node
-          @change_bar_starts[node] = { page: page_number, cursor: cursor, lanes: (node_change_bar_lanes node) }
+          @change_bar_starts[node] = { page: page_number, cursor: cursor, lanes: (node_change_bar_lanes node), node: node }
         end
 
         def take_change_bar_start node
@@ -254,7 +266,7 @@ module Asciidoctor
         # Inks one page's share of a table box between top and bottom: the
         # columns from change_bar_table_columns, the columns of lanes
         # filled, the first column nearest the text.
-        def ink_change_bar_table pgnum, top, bottom, lanes, settings
+        def ink_change_bar_table pgnum, top, bottom, lanes, settings, from = nil
           width = settings[:table_column_width]
           on_right = change_bar_on_right? pgnum, settings
           column_of = change_bar_table_columns @change_bar_lane_index.size, settings[:table_max_columns]
@@ -262,8 +274,9 @@ module Asciidoctor
           left = on_right ? bounds.right + settings[:offset] : bounds.left - settings[:offset] - count * width
           left = change_bar_inside_page left, count * width, settings[:table_border_width] / 2.0, on_right, settings
           column_x = ->(column) { on_right ? left + column * width : left + (count - 1 - column) * width }
-          lanes.map {|lane| column_of[lane] }.uniq.each do |column|
+          lanes.group_by {|lane| column_of[lane] }.each do |column, column_lanes|
             ink_change_bar_fill (column_x.call column), top, bottom, width, settings[:color]
+            record_change_bar_link from, column_lanes, (column_x.call column), width, top, bottom if from
           end
           save_graphics_state do
             if settings[:table_grid_width] > 0
@@ -316,6 +329,7 @@ module Asciidoctor
 
         # Paints the bar page by page; from/to are { page:, cursor: }, and
         # from[:lanes] lists the table columns to fill, the first when absent.
+        # from[:node] names the marked node a link resolves against.
         # Called immediately after the block is rendered, so all spanned pages exist.
         def ink_change_bar from, to
           return if scratch? || from.nil? || to.nil?
@@ -329,15 +343,21 @@ module Asciidoctor
               top = pgnum == from[:page] ? from[:cursor] : bounds.top
               bottom = pgnum == to[:page] ? to[:cursor] : 0
               next if (height = top - bottom) <= 0
-              next ink_change_bar_table pgnum, top, bottom, lanes, settings if change_bar_table? settings
-              ink_change_bar_fill (change_bar_x pgnum, settings), top, bottom, settings[:width], settings[:color]
+              next ink_change_bar_table pgnum, top, bottom, lanes, settings, from if change_bar_table? settings
+              x = change_bar_x pgnum, settings
+              ink_change_bar_fill x, top, bottom, settings[:width], settings[:color]
+              # A bar a few points wide makes a poor click target, so its
+              # link also covers the gap between the text and the bar
+              edge = (change_bar_on_right? pgnum, settings) ? bounds.right : bounds.left
+              left = [x, edge].min
+              record_change_bar_link from, lanes, left, ([x + settings[:width], edge].max - left), top, bottom
             end
           end
         end
 
-        def ink_change_bar_for_extent extent, lanes = nil
+        def ink_change_bar_for_extent extent, lanes = nil, node = nil
           return unless extent
-          ink_change_bar({ page: extent.from.page, cursor: extent.from.cursor, lanes: lanes },
+          ink_change_bar({ page: extent.from.page, cursor: extent.from.cursor, lanes: lanes, node: node },
             { page: extent.to.page, cursor: extent.to.cursor })
         end
 
@@ -365,7 +385,7 @@ module Asciidoctor
                 instance_exec(&block)
               else
                 block.call extent
-                ink_change_bar_for_extent extent, lanes
+                ink_change_bar_for_extent extent, lanes, node
               end
             end
           else
@@ -382,13 +402,97 @@ module Asciidoctor
         # casing the others don't.
         def bracket_change_bar node
           if @change_bar_attr && !scratch? && (lanes = node_change_bar_lanes node)
-            bar_from = { page: page_number, cursor: cursor, lanes: lanes }
+            bar_from = { page: page_number, cursor: cursor, lanes: lanes, node: node }
           end
           result = yield
           ink_change_bar bar_from, { page: page_number, cursor: cursor } if bar_from
           result
         end
 
+        # Records the area of a bar or table column on the current page, at
+        # x and width relative to the current bounds, for the link
+        # ink_change_bar_links adds once the revision history has rendered.
+        def record_change_bar_link from, lanes, x, width, top, bottom
+          return unless @change_bar_links && (node = from[:node])
+          left = bounds.absolute_left + x
+          @change_bar_links << {
+            page: page_number,
+            rect: [left, bounds.absolute_bottom + bottom, left + width, bounds.absolute_bottom + top],
+            node: node,
+            lanes: lanes,
+          }
+        end
+
+        # Contexts that carry a revision history row of their own when
+        # they have an id (Converter#prescan_document).
+        OWN_ENTRY_CONTEXTS = [:section, :floating_title, :example, :listing, :table, :image].freeze
+
+        # The anchor of the revision history row a marked node's change
+        # text lands in, :all for the revision's All row, or nil when the
+        # node has no row: the node's own id for the contexts with rows of
+        # their own, the enclosing table's id for a table cell, and
+        # otherwise the enclosing section's id, as rollup_child_revision_
+        # entries and rollup_table_cell_revision_entries file them.
+        def change_bar_entry_anchor node
+          if node.context == :table_cell
+            table = node.parent
+            table = table.parent until table.nil? || table.context == :table
+            return table.id if table&.id
+            node = table
+          elsif OWN_ENTRY_CONTEXTS.include? node.context
+            return node.id
+          elsif !(Converter::ROLLUP_CONTEXTS.include? node.context)
+            return nil
+          end
+          (section = enclosing_section node) && section.id ? section.id : :all
+        end
+
+        # Destination names for a revision history row: the row of anchor,
+        # the All row, and the revision's header row, for a revision group
+        # key such as 1-3.
+        def change_bar_entry_dest group, anchor
+          %(_rhrev_entry_#{group}_#{anchor})
+        end
+
+        def change_bar_all_dest group
+          %(_rhrev_all_#{group})
+        end
+
+        def change_bar_revision_dest group
+          %(_rhrev_revision_#{group})
+        end
+
+        # The destination a recorded link points at: the row of the newest
+        # revision among the link's lanes that the node marks, or that
+        # revision's header row when the revision history has no row for
+        # the node. Nil when neither rendered.
+        def change_bar_link_dest link
+          lane_of = ->(z) { @change_bar_lane_index&.[](z) || 0 }
+          marks = @change_bar_matcher.marks link[:node].attributes
+          mark, = marks.select {|_, z| link[:lanes].include? lane_of.call z }.max_by {|_, z| lane_of.call z }
+          return unless mark
+          group = revision_history.revision_key mark.to_s.delete_prefix @revision_prefix
+          anchor = change_bar_entry_anchor link[:node]
+          row = anchor == :all ? (change_bar_all_dest group) : (change_bar_entry_dest group, anchor if anchor)
+          [row, (change_bar_revision_dest group)].find {|name| name && (@change_bar_link_dests.include? name) }
+        end
+
+        # Adds a link annotation over every recorded bar and table column
+        # whose revision history row rendered. Viewers hit the annotation
+        # added last, and a section's bar, recorded once the section ends,
+        # covers the bars of the blocks inside it, so the tallest areas go
+        # first and every nested block keeps a link of its own on top.
+        def ink_change_bar_links
+          return if scratch? || @change_bar_links.nil? || @change_bar_links.empty?
+          current = page_number
+          @change_bar_links.sort_by.with_index {|link, i| [-(link[:rect][3] - link[:rect][1]), i] }.each do |link|
+            next unless (dest = change_bar_link_dest link)
+            go_to_page link[:page] unless page_number == link[:page]
+            link_annotation link[:rect], Border: [0, 0, 0], Dest: dest
+          end
+          go_to_page current unless page_number == current
+        end
+
         # The heading ink methods run after arrange_heading / start_new_chapter
         # have settled the page, so this is the first accurate start position.
         def ink_general_heading node, title, opts = {}

data/lib/asciidoctor/rhrev/converter.rb

@@ -193,6 +193,9 @@ module Asciidoctor
           if @revision_history_extent && @catalog
             ink_revision_history node, @revision_history_extent
           end
+
+          # After the revision history, whose rows carry the destinations
+          ink_change_bar_links
           
           # Re-render tables with pagerhrefs (only in manual mode)
           ink_pagerhref_tables if @manual_mode && @pagerhref_tables && !@pagerhref_tables.empty?
@@ -314,7 +317,7 @@ module Asciidoctor
             if @change_bar_attr && !scratch? && (lanes = node_change_bar_lanes node) &&
                 !(!at_page_top? && ((node.option? 'unbreakable') ||
                   ((node.option? 'breakable') && (node.id || node.title?))))
-              bar_from = { page: page_number, cursor: cursor, lanes: lanes }
+              bar_from = { page: page_number, cursor: cursor, lanes: lanes, node: node }
             end
             result = super
             catalog_block_anchor node
@@ -332,14 +335,14 @@ module Asciidoctor
           # PDF targets import whole pages; there is no cursor flow to mark
           if @change_bar_attr && !scratch? && (lanes = node_change_bar_lanes node) &&
               !((node.attr 'target').to_s.downcase.end_with? '.pdf')
-            bar_from = { page: page_number, cursor: cursor, lanes: lanes }
+            bar_from = { page: page_number, cursor: cursor, lanes: lanes, node: node }
           end
           result = super
           catalog_block_anchor node
           if bar_from
             bar_to = { page: page_number, cursor: cursor }
             # Images never split; a page change means the image moved wholesale
-            bar_from = { page: bar_to[:page], cursor: bounds.top, lanes: bar_from[:lanes] } if bar_to[:page] > bar_from[:page]
+            bar_from = bar_from.merge page: bar_to[:page], cursor: bounds.top if bar_to[:page] > bar_from[:page]
             ink_change_bar bar_from, bar_to
           end
           result
@@ -469,9 +472,10 @@ module Asciidoctor
         # trying to call super itself.
         def convert_targeted_list node, targets = (list_item_change_bar_targets node)
           @list_change_bar_target_stack ||= []
-          @list_change_bar_target_stack.push targets
+          # The list rides along so an item's bar links to the list's row
+          @list_change_bar_target_stack.push(targets && (targets.merge node: node))
           if targets && !targets[:whole].empty? && !scratch?
-            bar_from = { page: page_number, cursor: cursor, lanes: targets[:whole] }
+            bar_from = { page: page_number, cursor: cursor, lanes: targets[:whole], node: node }
             result = yield
             ink_change_bar bar_from, { page: page_number, cursor: cursor }
             result
@@ -559,14 +563,14 @@ module Asciidoctor
         def convert_list_item node, list, opts = {}
           targets = @list_change_bar_target_stack&.last
           if targets && (idx = list.items.index node) && (lanes = targets[:items][idx + 1])
-            ink_targeted_list_item_change_bar(lanes) { super }
+            ink_targeted_list_item_change_bar(lanes, targets[:node]) { super }
           else
             super
           end
         end
 
-        def ink_targeted_list_item_change_bar lanes
-          bar_from = { page: page_number, cursor: cursor, lanes: lanes } if @change_bar_attr && !scratch?
+        def ink_targeted_list_item_change_bar lanes, list
+          bar_from = { page: page_number, cursor: cursor, lanes: lanes, node: list } if @change_bar_attr && !scratch?
           result = yield
           ink_change_bar bar_from, { page: page_number, cursor: cursor } if bar_from
           result

data/lib/asciidoctor/rhrev/renderer.rb

@@ -449,12 +449,12 @@ module Asciidoctor
               header_text = "*#{major_changes_text} #{revision_label} #{prev_rev_text}*"
             end
             
-            page_cell = build_text_cell table, 0, "*#{page_label}*"
+            page_cell = build_text_cell table, 0, "#{change_bar_link_anchor change_bar_revision_dest revision}*#{page_label}*"
             header_cell = build_text_cell table, 1, header_text
             table.rows.body << [page_cell, header_cell]
             
             if (all_change = revision_history.instance_variable_get(:@all_entries)[revision])
-              row = build_list_row table, all_text, all_change, nil, nil, template_location_cell, template_asciidoc_cell, doc, is_all_or_cover: true
+              row = build_list_row table, "#{change_bar_link_anchor change_bar_all_dest revision}#{all_text}", all_change, nil, nil, template_location_cell, template_asciidoc_cell, doc, is_all_or_cover: true
               table.rows.body << row
             end
             
@@ -475,7 +475,8 @@ module Asciidoctor
             
             entries.each do |entry|
               location = build_location_text entry, doc
-              row = build_list_row table, location, entry[:change], entry[:anchor], entry, template_location_cell, template_asciidoc_cell, doc
+              dest = change_bar_entry_dest revision, entry[:anchor] if @change_bar_link_dests && entry[:anchor]
+              row = build_list_row table, location, entry[:change], entry[:anchor], entry, template_location_cell, template_asciidoc_cell, doc, dest: dest
               table.rows.body << row
             end
           end
@@ -518,15 +519,21 @@ module Asciidoctor
           lines.join("\n")
         end
         
-        def build_list_row table, location_text, change_text, anchor, entry, template_location_cell, template_asciidoc_cell, doc, is_all_or_cover: false
+        def build_list_row table, location_text, change_text, anchor, entry, template_location_cell, template_asciidoc_cell, doc, is_all_or_cover: false, dest: nil
+          if dest
+            @change_bar_link_dests << dest
+            # Raw formatter markup, as asciidoctor-pdf converts an inline anchor
+            dest_marker = %(<a id="#{dest}">#{::Asciidoctor::PDF::Converter::DummyText}</a>)
+          end
           if anchor && location_text != '???'
             location_cell = ::Asciidoctor::Table::Cell.new(template_location_cell.column, "", template_asciidoc_cell.attributes.dup)
             location_cell.inner_document.blocks.clear
             para_block = ::Asciidoctor::Block.new(location_cell.inner_document, :paragraph)
             formatted_location = format_with_role(location_text, 'rhrevpage')
-            para_block.lines = ["<a anchor=\"#{anchor}\">#{formatted_location}</a>"]
+            para_block.lines = ["#{dest_marker}<a anchor=\"#{anchor}\">#{formatted_location}</a>"]
             location_cell.inner_document.blocks << para_block
           else
+            location_text = %([[#{dest}]]#{location_text}) if dest
             location_cell = ::Asciidoctor::Table::Cell.new(template_location_cell.column, location_text, template_location_cell.attributes.dup)
           end
           
@@ -585,6 +592,14 @@ module Asciidoctor
           [location_cell, change_cell]
         end
         
+        # An inline anchor naming dest, which also records it as rendered,
+        # or an empty string without rhrev-change-bars-link.
+        def change_bar_link_anchor dest
+          return '' unless @change_bar_link_dests
+          @change_bar_link_dests << dest
+          %([[#{dest}]])
+        end
+
         def build_cell table, col_idx, text
           column = table.columns[col_idx]
           ::Asciidoctor::Table::Cell.new column, text

data/lib/asciidoctor/rhrev/table_cell_change_bar_patch.rb

@@ -49,14 +49,14 @@ if defined? ::Prawn::Table
       module Rhrev
         module TableCellChangeBarPatch
           # The change-bar lanes the cell draws (ChangeBars#change_bar_lanes),
-          # or nil for an unmarked cell.
-          attr_accessor :rhrev_marked
+          # or nil for an unmarked cell, and the marked Asciidoctor cell.
+          attr_accessor :rhrev_marked, :rhrev_marked_node
 
           def draw_background pt
             if @rhrev_marked && @pdf.respond_to?(:ink_change_bar)
               x, y = pt
               page = @pdf.page_number
-              @pdf.ink_change_bar({ page: page, cursor: y, lanes: @rhrev_marked }, { page: page, cursor: y - height })
+              @pdf.ink_change_bar({ page: page, cursor: y, lanes: @rhrev_marked, node: @rhrev_marked_node }, { page: page, cursor: y - height })
             end
             super
           end
@@ -82,8 +82,10 @@ if defined? ::Prawn::Table
                   next unless (cell_data = data[r] && data[r][c]).is_a?(::Hash)
                   if (content = cell_data[:content]).is_a? ::Prawn::Table::Cell
                     content.rhrev_marked = lanes
+                    content.rhrev_marked_node = cell
                   else
                     cell_data[:rhrev_marked] = lanes
+                    cell_data[:rhrev_marked_node] = cell
                   end
                 end
               end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asciidoctor-rhrev
 version: !ruby/object:Gem::Version
-  version: 1.9.2
+  version: 1.10.0
 platform: ruby
 authors:
 - 白一百 baiyibai