asciidoctor-rhrev 1.5.0 → 1.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0d0f5e91fc8b4f30c8325d121249758b652632641f7216a32c76d30d7096676
-  data.tar.gz: 0ea9ee18142768232c7b8a14bc2a656fed2b7cb2829bc4f0dcbb42c6e7a57d24
+  metadata.gz: 749dcca33dd6cedd4b545e1f7fe8ae07c25c662d1475268b105654241a40f4d3
+  data.tar.gz: b9f5eb774c855c427e7c891f6f6dc5623566fe04bd9b4ce62d1fb8c95817f697
 SHA512:
-  metadata.gz: bd5f85f7135ac2b0ba735dc71f25747d8e8a44a1e0b59520cdb4e42317ad98fc56d7cfd3a8054cc8d801f7c4be42037d8e8fa03e960d9f3efd70d5ccfd92c26a
-  data.tar.gz: 8432383a8b45809314e0db49f508ca842bb3662ed487f38f8228810694d308480da4ab581129176a3f21083ce2626a2f8ce203b450444e228c83788a713dd51d
+  metadata.gz: 6dce05ff64190cf02cff0fdf39af62d481c1b3e43d7c447673a41276c644d3668a6fa5bef77fb1d19bfcb31fc555a36ebab52985bac41e174a1fb565b0117797
+  data.tar.gz: eb056701ebd0a0289143fde96aef7dea2d5e16bae03cadcee183865a74e80623a6ffd088267bb071de31b69eeaae61fc3cb1ee78e3c431acfe701e1b1792fe6b

data/CHANGELOG.adoc

@@ -1,14 +1,27 @@
 = Changelog
 
+== 1.5.2 (2026-09-01)
+
+* Fix revision-history and `pagerhref` page numbers being off by a fixed, per-document offset for every `page_numbering_start_at` mode other than `body` (PDF backend). `Converter#record_rhrev_body_start_page` always assumed a `body`-mode restart (wherever structural body content first renders), the only mode where that assumption holds; reported directly with real page numbers from a real document under `after-toc` (an 11-page discrepancy, exactly the front matter preceding the real restart point) and `cover` (a consistent 1-page discrepancy, exactly the cover page numbering there is contiguous with, not reset after). `Converter#compute_rhrev_page_numbering_start_page` now reads the document's own resolved mode directly, matching asciidoctor-pdf's own logic (`converter.rb`'s own `page_numbering_start_at` branches), and `Converter#correct_rhrev_page_numbering` (called once, after the whole document, table of contents included, has rendered) corrects every number `record_rhrev_body_start_page`'s own eager, body-mode-only capture recorded during traversal: `toc`/`after-toc`'s real restart point is not knowable any earlier, confirmed directly against asciidoctor-pdf's own source, since it only finalizes the table of contents' real page extent after inking it. `Catalog#recompute_display_pages` applies the correction from each entry's own already-stored real physical page number (`page_sortable`), never re-derived. An explicit integer `page_numbering_start_at` remains a known, undocumented-no-longer limitation: that mode's own formula is a genuinely different shape (the body's own first page is labeled the given integer, not necessarily displayed page "1"), not confirmed against a real build, so left unhandled rather than risk a second, differently-wrong number. Verified directly against real `asciidoctor-pdf` builds for `after-toc` and `cover` (not assumed from source reading alone): the revision-history table's own reported page cross-checked against the number actually printed in the footer of the real page a marked entry lands on, confirmed wrong before the fix and correct after, for both modes independently; `body` mode and the two existing pagination regression fixtures produce byte-identical rendered text before and after. New regression fixture, `tests/regression/rhrev-page-numbering-start-at.rb`
+* Note: gem-only; the Antora extension (HTML output, no physical PDF page concept) is unaffected, npm still bumps concurrently per the standing 1.5.1 policy
+
+== 1.5.1 (2026-08-28)
+
+* Fix the Antora extension's table-cell change bars tagging only the marked cell's nested content instead of its own `<td>`/`<th>`, the deliberate difference noted in 1.5.0 below. The earlier attempt (a real Opal subclass of `Html5Converter`, registered via `ConverterFactory`) broke real Antora builds whenever a sibling package's own `@asciidoctor/core` install disagreed in version with the consuming site's; the fix instead patches `$convert_table` directly onto whichever converter class is already resolved for the current document (`doc.getConverter()`), never a separately-required or separately-registered class, so it cannot collide with Antora's own converter registration regardless of version drift elsewhere in the process. The cell's own `<td>`/`<th>` now carries the `rhrev-changed` role directly, matching the PDF backend's margin bar and Asciidoctor's native HTML5 backend (npm)
+* Fix a manual-mode `pagerhref` table's marked cell drawing no change bar at all (PDF backend), a previously documented limitation. `Converter#convert_table` computes the marked-row data for a change bar and clears it again before returning, correct for an ordinary table, but a `pagerhref` table instead defers its real render to `Converter#ink_pagerhref_tables`, much later, by which point that data had already been cleared, or worse, held a different table's value entirely. `Converter#allocate_pagerhref_table_extent` now stashes each `pagerhref` table's own marked-row data alongside its reserved page extent, and `ink_pagerhref_tables` restores it immediately before that specific table's deferred render, so the existing cell-bar mechanism reaches it correctly (gem)
+* Note: gem and npm release concurrently from this version on, one version number for both regardless of which side's code actually changed
+
 == 1.5.0 (2026-08-28)
 
-* Add change bars and revision-history roll-up for paragraphs, ordered/unordered/description lists, admonitions, open blocks, quotes, verses, and sidebars: an `rhrevN-M` attribute on one of these blocks inks a change bar the same way a section or table does, but adds its change text as a bullet to the entry of its nearest enclosing section, since it has no title or section number for a row of its own. A block with no enclosing section adds its change text to the document-level `all` entry instead. Available in both the PDF backend and Asciidoctor's HTML5 backend
-* Add table-cell change bars: an individual table cell needs the AsciiDoc-style cell syntax (`a|`) to carry an `rhrevN-M` attribute at all, since a plain cell never parses its content as blocks. In the PDF backend the bar draws in the page margin at the cell's real rendered row height, correct for a wrapped, multi-line cell. In the HTML backend the changed cell's `<td>`/`<th>` carries the `rhrev-changed` role directly. The cell's change text rolls onto its enclosing table's entry, or the table's nearest enclosing section if the table has no id of its own, or the document-level `all` entry if neither exists
+* Add change bars and revision-history roll-up for paragraphs, ordered/unordered/description lists, admonitions, open blocks, quotes, verses, and sidebars: an `rhrevN-M` attribute on one of these blocks inks a change bar the same way a section or table does, but adds its change text as a bullet to the entry of its nearest enclosing section, since it has no title or section number for a row of its own. A block with no enclosing section adds its change text to the document-level `all` entry instead. Available in the PDF backend, Asciidoctor's HTML5 backend, and the Antora extension
+* Add table-cell change bars: an individual table cell needs the AsciiDoc-style cell syntax (`a|`) to carry an `rhrevN-M` attribute at all, since a plain cell never parses its content as blocks. In the PDF backend the bar draws in the page margin at the cell's real rendered row height, correct for a wrapped, multi-line cell. In Asciidoctor's HTML5 backend the changed cell's `<td>`/`<th>` carries the `rhrev-changed` role directly. In the Antora extension the cell's marked nested content carries the role instead, a deliberate difference: no converter-level override exists there for tagging a `<td>`/`<th>` directly without risking conflicts with Antora's own HTML5 converter customization, and the unmodified converter already supports a role on ordinary content. In every backend, the cell's change text rolls onto its enclosing table's entry, or the table's nearest enclosing section if the table has no id of its own, or the document-level `all` entry if neither exists
 * Fix `convert_section` reading `page_number` before the chapter-opening page break instead of after (PDF backend): a chapter-opening section's revision-history entry and anchor destination recorded the page before the break, one page too low
 * Fix revision-history and `pagerhref` page numbers showing the physical PDF page index instead of the reader-visible page, when `page_numbering_start_at: body` (the default) and the document has real preamble content before the body starts (PDF backend)
 * Fix the HTML backend's revision-history table not rendering at all when the only revision-history content was a document-level `all` entry and no block had its own entry
 * Fix `rhrev-table-extra-blank-row` being silently ignored for an initial-release document (`revnumber` `1.0`/`1`): the initial-release table is built through a separate code path from the regular revision-history table and never checked the attribute
-* Note: this release is gem-only. The Antora extension's revision-history logic (`antora-extension/antora-rhrev-html.js`) is a separate, independently maintained implementation from the gem's Ruby code and does not yet include the paragraph/list/table-cell coverage above; the npm package skips 1.5.0
+* Fix the Antora extension's cross-page catalog builder (`antora-rhrev-html.js`): rewritten from a regex/heuristic-anchor-guessing scan to real per-page parsing, needed for any block type beyond the original six (section, floating title, example, listing, table, image) to reach a real Antora-built site at all
+* Fix `Block#setContent is not a function` in the Antora extension on a modern `@asciidoctor/core`, found while verifying the above
+* Note: the gem published first; the Antora extension's parity work landed in a separate, later commit under the same version number
 
 == 1.4.0 (2026-08-14)
 

data/lib/asciidoctor/rhrev/catalog.rb

@@ -59,20 +59,56 @@ module Asciidoctor
           @entries.each do |revision, entry_list|
             entry_list.each do |entry|
               next unless entry[:anchor] == anchor
-              
-              virtual_page_number = physical_page_number - (start_page_number - 1)
+
               entry[:dest] = {
                 anchor: anchor,
-                page: (virtual_page_number < 1 ? 
-                  (Asciidoctor::PDF::RomanNumeral.new physical_page_number, :lower) : 
-                  virtual_page_number).to_s,
+                page: (displayed_page_for physical_page_number, start_page_number).to_s,
                 page_sortable: physical_page_number,
                 y: y
               }
             end
           end
         end
-        
+
+        # The reader-visible page number for one physical page, given the
+        # physical page that displays as "1" (start_page_number) - a plain
+        # page number once numbering has started there, a lowercase roman
+        # numeral for anything still before it. Shared by link_dest_to_page
+        # (the eager, first-pass conversion, correct as-is for
+        # page-numbering-start-at: body, the common case) and
+        # recompute_display_pages (the deferred, corrected conversion for
+        # every other mode, see that method's own docblock).
+        def displayed_page_for physical_page_number, start_page_number
+          virtual_page_number = physical_page_number - (start_page_number - 1)
+          virtual_page_number < 1 ? (Asciidoctor::PDF::RomanNumeral.new physical_page_number, :lower) : virtual_page_number
+        end
+
+        # Recomputes every entry's own :dest][:page] from its already-stored
+        # :page_sortable (the real physical page number, unconditionally
+        # correct, set by link_dest_to_page above regardless of mode) and
+        # the given, now-final start_page_number.
+        #
+        # Needed because link_dest_to_page's own formula, applied eagerly
+        # during document traversal, is only ever correct for page-
+        # numbering-start-at: body: for toc/after-toc/cover/an explicit
+        # integer, the real physical page that displays as "1" is not
+        # knowable that early (asciidoctor-pdf itself only finalizes it
+        # after inking the table of contents, confirmed directly against
+        # its own source, converter.rb's convert_document). The converter
+        # calls this once, after the whole document (table of contents
+        # included) has rendered, with the real, corrected start_page_number
+        # its own compute_rhrev_page_numbering_start_page works out; entries
+        # already correct (body mode) are simply recomputed to the same
+        # value they already held, a harmless no-op.
+        def recompute_display_pages start_page_number
+          @entries.each_value do |entry_list|
+            entry_list.each do |entry|
+              next unless (dest = entry[:dest]) && dest[:page_sortable]
+              dest[:page] = (displayed_page_for dest[:page_sortable], start_page_number).to_s
+            end
+          end
+        end
+
         def sorted_revisions
           # Collect all unique revisions from entries, all_entries, and cover_entries
           all_revisions = (@entries.keys + @all_entries.keys + @cover_entries.keys).uniq

data/lib/asciidoctor/rhrev/converter.rb

@@ -48,13 +48,14 @@ module Asciidoctor
         # `body_offset = (body_start_page_number = page_number) - 1` line).
         # Captured once, from whichever of convert_preamble/convert_section
         # runs first; every later call is a no-op via the memoized ivar.
-        # Used as the start_page_number fed to Catalog#link_dest_to_page, so
-        # entries display the reader-visible page (matching page_numbering_
-        # start_at: body, the default), not a raw physical index that runs
-        # ahead by however many roman-numeral-numbered front-matter pages a
-        # title page, TOC, or preamble content added before the body starts.
-        # Other page_numbering_start_at modes (toc, after-toc, cover, an
-        # explicit integer) are not accounted for and stay a known limitation.
+        #
+        # Correct as the FINAL value only for page-numbering-start-at: body
+        # (the default): every entry recorded against it during traversal
+        # (Catalog#link_dest_to_page, @anchor_catalog below) is provisional
+        # for any other mode, corrected once, after the whole document has
+        # rendered, by correct_rhrev_page_numbering (convert_document, see
+        # its own docblock for why the correction cannot happen any
+        # earlier for toc/after-toc specifically).
         def record_rhrev_body_start_page
           @rhrev_body_start_page ||= page_number unless scratch?
         end
@@ -70,7 +71,80 @@ module Asciidoctor
           virtual = physical_page_number - (start_at - 1)
           (virtual < 1 ? (RomanNumeral.new physical_page_number, :lower) : virtual).to_s
         end
-        
+
+        # The physical PDF page that displays as reader-visible page "1",
+        # computed the same way asciidoctor-pdf itself does (converter.rb's
+        # own convert_document), reading the document's own resolved
+        # page-numbering-start-at mode, rather than assuming a body-mode
+        # restart the way record_rhrev_body_start_page's own capture always
+        # has.
+        #
+        # Called once, from convert_document, AFTER the whole document
+        # (table of contents included) has rendered: toc/after-toc
+        # genuinely cannot be answered any earlier. Confirmed directly
+        # against asciidoctor-pdf's own source: for the standard case (an
+        # automatic, top-of-document toc, not an explicit toc::[] macro),
+        # its real page extent, and therefore the toc/after-toc offset, is
+        # already known before traverse even starts (allocate_toc's own
+        # dry run measures it up front) - but for a toc::[] macro placed
+        # inside a preamble or elsewhere, that extent is only known once
+        # traverse actually reaches and inks it, and asciidoctor-pdf's own
+        # correction for that case runs only after traverse doc returns
+        # (the num_front_matter_pages[1] = toc_extent.to.page adjustment,
+        # gated on title_as_page && !toc_at_top). Reading @toc_extent once,
+        # after super has fully returned, gives the correct, final value
+        # either way, without this method needing to know which of the two
+        # internal paths asciidoctor-pdf actually took.
+        #
+        # Deliberately does not handle an explicit integer
+        # page-numbering-start-at: that mode's own body page is LABELED the
+        # given integer, not necessarily displayed page "1" at all (a
+        # genuinely different formula shape, physical - anchor + label,
+        # not physical - anchor + 1), and is left as the same known
+        # limitation record_rhrev_body_start_page's own prior docblock
+        # already named, rather than risk a second, differently-wrong
+        # formula for a mode not confirmed against a real build.
+        def compute_rhrev_page_numbering_start_page node
+          body_start = @rhrev_body_start_page || 1
+          case (mode = @theme.page_numbering_start_at || 'body')
+          when 'cover'
+            front_cover_path, = resolve_background_image node.document, @theme, 'front-cover-image', theme_key: :cover_front_image
+            front_cover_path ? 1 : body_start
+          when 'toc'
+            (extent = @toc_extent) ? extent.from.page : body_start
+          when 'after-toc'
+            if (extent = @toc_extent)
+              after_toc_page = extent.to.page
+              after_toc_page += 1 if @ppbook && (recto_page? after_toc_page)
+              after_toc_page + 1
+            else
+              body_start
+            end
+          else
+            body_start
+          end
+        end
+
+        # Applies compute_rhrev_page_numbering_start_page's own real,
+        # mode-aware result, correcting every page number recorded during
+        # traversal under the wrong, body-mode-only assumption. A no-op,
+        # deliberately, when the corrected value matches what
+        # record_rhrev_body_start_page already captured (page-numbering-
+        # start-at: body, the common case, and any other mode this method
+        # could not confidently resolve): no entry is touched twice for
+        # nothing.
+        def correct_rhrev_page_numbering node
+          return unless @catalog
+          corrected = compute_rhrev_page_numbering_start_page node
+          return if corrected == @rhrev_body_start_page
+          @rhrev_body_start_page = corrected
+          @catalog.recompute_display_pages corrected
+          @anchor_catalog&.each_value do |entry|
+            next unless (dest = entry[:dest]) && dest[:physical_page]
+            dest[:page] = rhrev_display_page dest[:physical_page]
+          end
+        end
+
         def convert_document node
           @revision_prefix = node.attr 'revhistoryprefix', 'rhrev'
           init_change_bars node
@@ -87,7 +161,15 @@ module Asciidoctor
           
           # Render document (this will visit all nodes and update entry metadata)
           result = super
-          
+
+          # Correct every page number recorded during traversal under the
+          # body-mode-only assumption record_rhrev_body_start_page always
+          # makes: the real mode-aware value is only knowable now, after
+          # the whole document (table of contents included) has rendered.
+          # Must run before ink_revision_history/ink_pagerhref_tables below,
+          # both real consumers of the numbers this corrects.
+          correct_rhrev_page_numbering node
+
           # Ink revision history if allocated
           if @revision_history_extent && @catalog
             ink_revision_history node, @revision_history_extent
@@ -141,7 +223,7 @@ module Asciidoctor
               context: node.context,
               level: node.level
             }
-            @anchor_catalog[node.id][:dest] = { page: (rhrev_display_page page_num), y: cursor }
+            @anchor_catalog[node.id][:dest] = { page: (rhrev_display_page page_num), physical_page: page_num, y: cursor }
 
             # Link destination to page for revision history
             revision_history.link_dest_to_page node.id, page_num, (@rhrev_body_start_page || 1), y: cursor
@@ -191,10 +273,15 @@ module Asciidoctor
           # margin bar at draw time (table_cell_change_bar_patch.rb reads this
           # ivar back via Prawn::Table::Cell#row), independent of whether the
           # table itself is marked. See marked_table_cell_bar_rows for why
-          # this matches by row index alone. Known gap: for a manual-mode
-          # pagerhref table, this ivar is stale by the time
-          # ink_pagerhref_tables performs the deferred real ink pass later,
-          # so cell-level bars do not reach that combination.
+          # this matches by row index alone. For a manual-mode pagerhref
+          # table, this value is stashed onto @pagerhref_tables in
+          # allocate_pagerhref_table_extent below and restored by
+          # ink_pagerhref_tables right before that table's real, deferred
+          # render: this ivar itself would otherwise already be nil (or
+          # worse, another table's stale value) by the time that later pass
+          # runs, since every ordinary convert_table call clears it in its
+          # own ensure block below, long before ink_pagerhref_tables ever
+          # starts.
           @rhrev_table_cell_bar_rows = marked_table_cell_bar_rows(node) if @change_bar_attr && !scratch?
 
           if !has_id && !has_rhrev && !has_pagerhref
@@ -708,7 +795,7 @@ module Asciidoctor
               context: node.context
             }
             page_num = page_number
-            @anchor_catalog[node.id][:dest] = { page: (rhrev_display_page page_num), y: cursor }
+            @anchor_catalog[node.id][:dest] = { page: (rhrev_display_page page_num), physical_page: page_num, y: cursor }
 
             revision_history.link_dest_to_page node.id, page_num, (@rhrev_body_start_page || 1), y: cursor
           end
@@ -770,10 +857,16 @@ module Asciidoctor
           extent.each_page { |first_page| start_new_page unless first_page }
           move_cursor_to extent.to.cursor
           
-          # Store for later re-rendering with actual page numbers
+          # Store for later re-rendering with actual page numbers.
+          # bar_rows is @rhrev_table_cell_bar_rows as convert_table computed
+          # it for THIS node, a few lines before this method was called;
+          # stashed here since the ivar itself will not survive to
+          # ink_pagerhref_tables's own later pass, see that ivar's own
+          # comment in convert_table for why.
           @pagerhref_tables << {
             node: node,
-            extent: extent
+            extent: extent,
+            bar_rows: @rhrev_table_cell_bar_rows
           }
         end
         
@@ -790,15 +883,25 @@ module Asciidoctor
           @pagerhref_tables.each do |table_info|
             extent = table_info[:extent]
             node = table_info[:node]
-            
+
             # Go back to the allocated space
             go_to_page extent.from.page
             move_cursor_to extent.from.cursor
-            
+
+            # Restore THIS table's own bar-row data for
+            # table_cell_change_bar_patch.rb to read during the real render
+            # below, the fix for the gap convert_table's own ivar comment
+            # describes: without this, the ivar is either nil or another
+            # table's stale value by this point, since every ordinary
+            # convert_table call already cleared it right after computing
+            # it, long before this loop ever runs.
+            @rhrev_table_cell_bar_rows = table_info[:bar_rows]
+
             # Re-render the table with flag set to prevent recursion
             @rendering_deferred_table = true
             super_convert_table node
             @rendering_deferred_table = false
+            @rhrev_table_cell_bar_rows = nil
           end
         end
         

metadata

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