asciidoctor-rhrev 1.6.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d50d58f6581222d194cf031114bf6aeb82525b1662e6765c4e24c5c4f0e530cd
-  data.tar.gz: b45e1e49cc09002e1267c1e31221658ec9aa26a5ca49d4ef9dc8ea3ba857e0d4
+  metadata.gz: 7ff948e637bb99f9d64376d94ad293310988680a558ef3796aa797911210ad48
+  data.tar.gz: f47c7b2ecf6aa55d7e396b44221e8d7af6445c9c6085a71182e8b0a457e09226
 SHA512:
-  metadata.gz: 0cf35ff6b4b52a1b9851b8eb103efd5eafc0922f59045d4830b5a390a2a62607060ff79442d5c26e129512efaf06cbd0c4dfc06808f992b14fe3203f94a2e3cf
-  data.tar.gz: 39ac612cba2f168c9cf4b26eddaea213246d18a90a3b25283b38f82c035756ae78597b01090466ae97ffe644f53f813e8f6b907a7957f5bd4f470d8ecc607e73
+  metadata.gz: a908055a506c6d32629d381a800c2c8911e649e0d4dfcd51ea2b5bb64a7d70e6bd4bb45229541947b9e840df95a9c3335d03179634cfe8efd99d51bedc8a5cb5
+  data.tar.gz: 8f5442540754978416479cf2b90f01d207993659b9e243277cdc1d645475dec294379691b62b88d1b7ad55ef3748f4af318486ea3bc7fc3ee6d6e08e2cf3d74b

data/CHANGELOG.adoc

@@ -1,5 +1,13 @@
 = Changelog
 
+== 1.7.0 (2026-09-02)
+
+* Replace 1.6.0's per-item list change bars with a different design, after real user feedback that the syntax it needed was too heavy: marking one item required a `+` continuation, an attribute line, and a two-line empty open block, four lines to mark a single bullet, far more than every other rhrev-markable construct's own single attribute line. 1.6.0's mechanism (`Converter#propagate_list_item_content_marks`, the attached-continuation-block workaround, `list_item` added to the roll-up contexts) is fully removed, not just superseded
+* Add per-item targeting instead, staying on the list's own existing attribute line: one or more trailing positional attributes name which item(s), by 1-based position, get the bar, `[rhrev1-2="Reworded step two",2]`. Several items and a dash range both work, mixed freely, `[rhrev1-2="Reworded the middle steps",2,4-6]`. No positional attribute at all keeps the exact behavior from every release before 1.6.0: one bar over the whole list. Confirmed directly before this design was picked, not assumed: a bare positional attribute cannot collide with anything AsciiDoc already claims on a list (style, and so on), since Asciidoctor tracks positional index by each entry's own place in the bracket, not by counting unnamed entries only, so a named `rhrev1-2="..."` occupying position 1 never contests a trailing bare position. The revision-history roll-up needs no new code at all: a targeted list is still just a marked list, already one of the existing roll-up contexts, already rolling up to its enclosing section correctly
+* `Converter#convert_list_item` reads the innermost enclosing list's own target set off a stack `Converter#convert_targeted_list` maintains (the same shape `@change_bar_section_stack` already uses for nested sections), not off the list argument directly: for a `dlist` using the `unordered`, `ordered`, or `qanda` style, asciidoctor-pdf synthesizes a brand-new `List` object with no attributes of its own to render through, never the real, marked `dlist` node, so the stack is what carries the real target set down correctly regardless of which path produced the call. A `dlist` using the default or horizontal style has no per-item mechanism to target at all (asciidoctor-pdf renders those inline inside `convert_dlist` itself, no per-entry call to override, the same structural gap table-row-level marking has); a positional entry on one of those two styles falls back to marking the whole block, with a warning, rather than silently doing nothing
+* Fix a bug caught during development, before this ever shipped: `bracket_change_bar`, the shared helper every other bar-inking call site already uses, gates on `change_bar? node`, checking the bracketed node's OWN attributes. A targeted item never carries the mark itself, only the enclosing list does, so reusing `bracket_change_bar` unmodified silently swallowed every targeted item's bar, real rendering showed no bar at all despite the target set correctly including the item's index. `Converter#ink_targeted_list_item_change_bar` is the fix, the same shape minus that gate, since membership in the already-resolved target set answers the "should this bar" question on its own. New regression file, `tests/regression/list-item-target-change-bars.rb`, includes a spy on `ink_change_bar` (the same technique `table-cell-change-bar.rb`'s own manual-mode pagerhref check already establishes) specifically because this exact bug would have passed every other check in the file: the revision-history roll-up is a separate mechanism from bar-inking and stayed correct the whole time the bar itself was silently missing
+* Note: gem-only; the Antora extension (HTML output, no page-margin bar geometry the same way) is unaffected, npm still bumps concurrently per the standing 1.5.1 policy
+
 == 1.6.0 (2026-09-02)
 
 * Add per-item change bars and revision-history roll-up for individual items in an unordered or ordered list (PDF backend), previously only possible for a whole marked list. `Converter#convert_list_item` brackets asciidoctor-pdf's own per-item render call (`convert_list` calls it once per item directly, a real granular hook, unlike table rows) the same way the existing paragraph/ulist/olist/dlist overrides already bracket their own whole-block calls. No AsciiDoc syntax attaches a block attribute list directly to a list item's own bullet line, confirmed directly against a real parse: the attribute list is silently dropped, not attached to the item, the list, or anywhere else. The working construct, the same shape as an `a|` table cell's own workaround, is a block attribute list on content the item already legitimately attaches via a `+` continuation. `Converter#propagate_list_item_content_marks` copies a marked carrier block's rhrev attribute onto the enclosing item and strips it from the carrier, at prescan time, before real rendering: the strip matters because `convert_list_item`'s own `traverse_list_item` call renders an item's attached blocks through this same converter, so a left-marked carrier would independently trigger its own bar-inking hook too, a second bad bar. `list_item` is now one of the roll-up contexts, resolved via the same nearest-enclosing-section walk every other roll-up context already uses, reusing that mechanism unchanged. A marked sub-list attached to an item keeps its own independent mark; the new marker-carrier context set deliberately excludes ulist/olist/dlist/list_item so a compound item's own nested sub-list is never swallowed into the parent item's mark. A `dlist` using the `unordered`, `ordered`, or `qanda` style gets the same per-item support, since asciidoctor-pdf itself renders those through synthesized list items routed through the same hook; the default and `horizontal` `dlist` styles render each term and description pair inline with no per-item method call to override, the same category of structural gap table-row-level marking has, not attempted here. Verified directly: a real fixture rendered to PNG shows exactly one bar, spanning only the marked item, not the whole list and not bleeding into neighboring items; the revision-history table shows exactly one bullet for the marked item, nothing from its unmarked siblings. New regression file, `tests/regression/list-item-change-bars.rb`, confirmed to fail (a raised `NoMethodError`) without the fix and pass with it

data/lib/asciidoctor/rhrev/converter.rb

@@ -1,5 +1,6 @@
 require 'asciidoctor/pdf' unless defined? Asciidoctor::PDF
 require 'fileutils'
+require 'set'
 require_relative 'helpers'
 require_relative 'catalog'
 require_relative 'renderer'
@@ -399,40 +400,151 @@ module Asciidoctor
           bracket_change_bar(node) { super }
         end
 
+        # A list marked with only the change-text attribute, [rhrev1-2="..."],
+        # is unchanged from every prior release: bracket_change_bar covers
+        # the whole list, one bar, one roll-up bullet.
+        #
+        # A list marked with one or more trailing positional attributes,
+        # [rhrev1-2="...",2] or [rhrev1-2="...",2,4-6], instead targets
+        # specific items by their 1-based position: no bar over the whole
+        # list, a separate bar for just the named item(s), inked by
+        # convert_list_item below. The roll-up bullet is unaffected either
+        # way, still the list's own single entry, [rhrev1-2="..."] is read
+        # exactly as before.
+        #
+        # A bare positional attribute cannot collide with a list's own
+        # style (ulist [square], olist numbering, and so on): confirmed
+        # directly, Asciidoctor tracks positional index by each entry's own
+        # place in the bracket, not by counting unnamed entries only, so a
+        # named rhrev1-2="..." occupying position 1 never contests the
+        # trailing bare position(s) after it.
         def convert_ulist node
-          bracket_change_bar(node) { super }
+          convert_targeted_list(node) { super }
         end
 
         def convert_olist node
-          bracket_change_bar(node) { super }
+          convert_targeted_list(node) { super }
         end
 
+        # dlist's unordered/ordered/qanda styles synthesize real ListItem
+        # objects and route them through convert_list_item the same as
+        # ulist/olist, confirmed directly against asciidoctor-pdf's own
+        # source (convert_dlist's own case statement, then convert_list),
+        # so per-item targeting reaches them too. The default and
+        # horizontal styles render every term/description pair inline
+        # inside convert_dlist itself, with no per-entry call to override
+        # at all, the same structural gap table-row-level marking has;
+        # per-item targets on one of those two styles fall back to marking
+        # the whole block instead, with a warning, rather than silently
+        # doing nothing.
+        DLIST_STYLES_ROUTING_THROUGH_LIST_ITEM = %w(unordered ordered qanda).freeze
+
         def convert_dlist node
-          bracket_change_bar(node) { super }
+          targets = list_item_change_bar_targets node
+          if (::Set === targets) && !(DLIST_STYLES_ROUTING_THROUGH_LIST_ITEM.include? node.style)
+            log :warn, %(rhrev per-item list marking is not supported for a dlist using the '#{node.style || 'default'}' style; marking the whole block instead)
+            targets = :all
+          end
+          convert_targeted_list(node, targets) { super }
+        end
+
+        # Shared by convert_ulist/convert_olist/convert_dlist: computes the
+        # target set (unless the caller, convert_dlist, already resolved
+        # it), pushes it so convert_list_item can read the innermost
+        # enclosing list's own targets, and either brackets the whole list
+        # (targets == :all) or leaves bar-inking to convert_list_item
+        # entirely (targets is a real index Set, or nil, not marked at
+        # all). The stack, not a single ivar, matters for a list nested
+        # inside a marked item's own content: the same shape
+        # @change_bar_section_stack already uses for nested sections.
+        #
+        # Takes the real conversion as a block, not a bare super call
+        # inside this method: super here would look for
+        # Converter#convert_targeted_list up the ancestor chain, which
+        # does not exist, since this method's own name differs from the
+        # three real converter entry points calling it. The block, called
+        # from inside convert_ulist/convert_olist/convert_dlist
+        # themselves, keeps super resolving to the right upstream method,
+        # the same reason bracket_change_bar takes a block rather than
+        # 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
+          if targets == :all
+            bracket_change_bar(node) { yield }
+          else
+            yield
+          end
+        ensure
+          @list_change_bar_target_stack.pop
+        end
+
+        # The target set for the list currently being converted: :all
+        # (bar the whole list, the only behavior before this feature
+        # existed), nil (not marked for the current revision at all), or a
+        # Set of 1-based item positions parsed from one or more trailing
+        # positional attributes, expanding an N-M token into a range.
+        # Reuses change_bar? for the marked/not-marked check, the same
+        # predicate every other bar-inking decision in this file already
+        # uses, so this only ever answers for the current revnumber.
+        def list_item_change_bar_targets node
+          return nil unless change_bar? node
+          raw = node.instance_variable_get(:@attributes)
+          positional_keys = raw.keys.select {|k| ::Integer === k }.sort
+          return :all if positional_keys.empty?
+          targets = ::Set.new
+          positional_keys.each do |key|
+            token = raw[key].to_s
+            if (m = /\A(\d+)-(\d+)\z/.match token)
+              (m[1].to_i..m[2].to_i).each {|i| targets << i }
+            elsif /\A\d+\z/.match? token
+              targets << token.to_i
+            end
+          end
+          targets.empty? ? :all : targets
         end
 
         # A single item within a ulist/olist (and a dlist using the
-        # unordered/ordered/qanda styles, which asciidoctor-pdf itself
-        # synthesizes into real ListItem objects routed through here the
-        # same way), rather than the whole list. asciidoctor-pdf's own
-        # convert_list calls this once per item directly (not through the
-        # normal node.convert dispatch), a real granular hook, so the same
-        # bracket_change_bar shape as the nine block types above applies
-        # unchanged: bare super forwards list/opts along with node
-        # automatically. The bracket spans traverse_list_item's own call at
-        # the end of the real convert_list_item, which covers the item's
-        # marker, its principal text, and any attached continuation content
-        # together, correct even for a compound, multi-block item.
+        # unordered/ordered/qanda styles, real ListItem objects
+        # asciidoctor-pdf itself synthesizes and routes through here the
+        # same way). Reads the innermost enclosing list's own target set
+        # off the top of the stack convert_targeted_list maintains, not
+        # off list itself: for a dlist's synthesized styles, list here is
+        # a brand-new List object asciidoctor-pdf builds on the fly with
+        # no attributes of its own, never the real, marked dlist node, so
+        # reading list's own attributes directly would never see the
+        # mark. The stack is what carries the real target set down
+        # correctly regardless of which path produced this call.
+        #
+        # list.items.index node relies on plain object identity, correct
+        # here: asciidoctor-pdf's own convert_list passes each item
+        # straight from list.items into this method, no copying.
         #
-        # A dlist using its default or horizontal style is NOT covered:
-        # asciidoctor-pdf renders those two styles' term/description pairs
-        # entirely inline inside convert_dlist itself, with no per-entry
-        # method call to override, the same category of structural gap
-        # table-row-level marking has (see LIST_ITEM_MARKER_CARRIER_
-        # CONTEXTS's own docblock and the project's declined-features
-        # notes); a bigger, riskier lift, not attempted here.
+        # Deliberately not bracket_change_bar: its own change_bar? node
+        # gate checks the item's OWN attributes, always false here, the
+        # mark lives on the enclosing list, never the item. That gate is
+        # exactly right for every other bracket_change_bar caller (the
+        # node being bracketed is the node that was actually marked); it
+        # would silently swallow every targeted item's bar here, caught
+        # directly by real rendering showing no bar at all despite the
+        # target set correctly including this item's index. ink_targeted_
+        # list_item_change_bar mirrors bracket_change_bar's own shape
+        # without that gate, since membership in targets already answers
+        # the "should this bar" question on its own.
         def convert_list_item node, list, opts = {}
-          bracket_change_bar(node) { super }
+          targets = @list_change_bar_target_stack&.last
+          if (::Set === targets) && (idx = list.items.index node) && (targets.include? idx + 1)
+            ink_targeted_list_item_change_bar { super }
+          else
+            super
+          end
+        end
+
+        def ink_targeted_list_item_change_bar
+          bar_from = { page: page_number, cursor: cursor } if @change_bar_attr && !scratch?
+          result = yield
+          ink_change_bar bar_from, { page: page_number, cursor: cursor } if bar_from
+          result
         end
 
         def convert_rhrev node
@@ -552,24 +664,7 @@ module Asciidoctor
         # none yet for the matching revision), rather than needing its own
         # id, its own destination, or a generated label. See
         # rollup_child_revision_entries.
-        #
-        # list_item is included: enclosing_section's own node.parent walk
-        # already skips past a marked item's containing ulist/olist/dlist to
-        # the nearest section correctly, no special-casing needed there. Its
-        # own mark, however, never arrives via the item's own attributes
-        # directly, see propagate_list_item_content_marks below.
-        ROLLUP_CONTEXTS = [:paragraph, :ulist, :olist, :dlist, :list_item, :admonition, :open, :quote, :verse, :sidebar].freeze
-
-        # Contexts propagate_list_item_content_marks accepts as a list
-        # item's own marker carrier: everything ROLLUP_CONTEXTS covers
-        # except list_item itself (the item is the propagation target, not
-        # a valid source) and ulist/olist/dlist (a nested sub-list attached
-        # to an item already has its own independent, correct mark-and-
-        # roll-up path via convert_ulist/convert_olist/convert_dlist and
-        # this same ROLLUP_CONTEXTS walk; swallowing its mark into the
-        # parent item here would both steal it from the sub-list and give
-        # the item a mark it never earned).
-        LIST_ITEM_MARKER_CARRIER_CONTEXTS = (ROLLUP_CONTEXTS - [:list_item, :ulist, :olist, :dlist]).freeze
+        ROLLUP_CONTEXTS = [:paragraph, :ulist, :olist, :dlist, :admonition, :open, :quote, :verse, :sidebar].freeze
 
         # Walks up from node to its nearest enclosing :section, or nil if
         # none exists, i.e. node sits in the document preamble. Shared by
@@ -773,60 +868,6 @@ module Asciidoctor
           end
         end
 
-        # No canonical AsciiDoc syntax attaches a block attribute list
-        # directly to one list item's own bullet line; confirmed directly
-        # (Asciidoctor.load, a real fixture): the attribute list is silently
-        # dropped, not attached to the item, the list, or anywhere else. The
-        # working construct, the same shape as an a| table cell's own
-        # workaround, is a block attribute list on content the item already
-        # legitimately attaches via a `+` continuation:
-        #
-        #   * Item two
-        #   +
-        #   [rhrev1-2="Added item two"]
-        #   --
-        #   --
-        #
-        # or with real visible continuation text instead of an empty open
-        # block. Copies any rhrev-prefixed attribute from the item's own
-        # directly-attached marker block onto the item itself, then strips
-        # it from that block, the same two reasons propagate_cell_content_
-        # marks strips its own source: convert_list_item's traverse_list_
-        # item call renders an item's attached blocks through this same
-        # converter, so a left-marked carrier would independently trigger
-        # its own bar-inking hook too, and the strip keeps
-        # node_carries_own_rhrev?/rollup_child_revision_entries from later
-        # finding and rolling up the same mark a second time from the
-        # carrier's own now-redundant position in the tree.
-        #
-        # Deliberately only the item's own direct children (item.blocks),
-        # not a recursive descent: a compound item nesting a sub-list of
-        # its own must not have that sub-list's independent marks stolen
-        # and reattributed to the outer item, LIST_ITEM_MARKER_CARRIER_
-        # CONTEXTS excludes ulist/olist/dlist/list_item for exactly this
-        # reason, restricting a valid carrier to paragraph/admonition/open/
-        # quote/verse/sidebar.
-        #
-        # Must run before rollup_child_revision_entries and before real
-        # rendering, so the item's own attributes are already in place by
-        # the time either reads them.
-        def propagate_list_item_content_marks doc
-          doc.find_by(context: :list_item).each do |item|
-            item.blocks.each do |node|
-              next unless LIST_ITEM_MARKER_CARRIER_CONTEXTS.include? node.context
-              attr_entries = (node.instance_variable_get(:@attributes) rescue nil)
-              next if attr_entries.nil? || attr_entries.empty?
-
-              attr_entries.keys.each do |key|
-                key_str = key.to_s
-                next unless key_str.start_with?(@revision_prefix)
-                item.set_attr key_str, attr_entries[key]
-                node.remove_attr key_str
-              end
-            end
-          end
-        end
-
         def rollup_table_cell_revision_entries doc
           doc.find_by(context: :table).each do |table|
             cells = (table.rows[:head] + table.rows[:body]).flatten
@@ -1059,7 +1100,6 @@ module Asciidoctor
             end
 
             propagate_cell_content_marks doc
-            propagate_list_item_content_marks doc
             rollup_child_revision_entries doc
             rollup_table_cell_revision_entries doc
 

metadata

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