coradoc 2.0.19 → 2.0.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dfb7ecfe3eb593e8a88dc23950b2e75fb5bafd4ea8f31ee7840c44e1cdaadd28
-  data.tar.gz: 1835d0ac0defa944dc45d26c967d3e9ddb0d20a599f79c85657531689c67faf0
+  metadata.gz: 05f1c48e0de6edb3f2473ab0e1c0cdb4747c513bf805820b8456846888b86c37
+  data.tar.gz: caaadd87ea878292673070688c08c8a7bfb7c39c58173f928e1960eb5af397ad
 SHA512:
-  metadata.gz: b1a73e74172ae6af0dd2a5426f520b546170c2a4f00910f91dd45211bccf448ca187d45b64ba94030549331008a50adaff283ca1ced17c39bb164d6a6cd9a032
-  data.tar.gz: 57efec479b5c118c4c18d99d7e0b0090046ef1c42ed17b265804f044467775fb82781bec4a7c3a119b24a428ff46ec50c642e4557488471447f5e96af48d4572
+  metadata.gz: 86f2108a83a94d30b5660586c5b83085b1b9f1ebd0ab470d21292f258cc0473d4769eb266394082d335a7d39ed2499297f0d4d1f1e2ac517c42f3d5b3bbe3527
+  data.tar.gz: aa4241a2a9c0ae8cec854b747b76a709bb8954b9bbbf6a3c15b3ebaad77f7b1dea199fc57129541fadcce94bee957cde48f7c3bda906379a5095a4893efdd0e1

data/lib/coradoc/core_model/block.rb

@@ -53,10 +53,16 @@ module Coradoc
       #   @return [String, nil] language identifier for source code blocks
       attribute :language, :string
 
+      # @!attribute callouts
+      #   @return [Array<Callout>] callout annotations attached to this
+      #     block. Empty for most block types; populated by format gems
+      #     when AsciiDoc-style `<N>` annotations follow a verbatim block.
+      attribute :callouts, Callout, collection: true, default: -> { [] }
+
       private
 
       def comparable_attributes
-        super + %i[block_semantic_type content]
+        super + %i[block_semantic_type content callouts]
       end
     end
   end

data/lib/coradoc/core_model/callout.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # A single callout annotation attached to a verbatim block.
+    #
+    # Callouts are the AsciiDoc convention for annotating individual lines
+    # of a source/listing block: `<1>` markers appear inside the code and
+    # matching `<1> explanation` lines follow the block. Markdown has no
+    # native equivalent, so each format gem decides how to render them.
+    #
+    # The CoreModel stores each annotation as a typed Callout on its parent
+    # block, with the in-code marker `<index>` preserved in the block's
+    # `content` for verbatim round-trip.
+    class Callout < Base
+      # @!attribute index
+      #   @return [Integer, nil] 1-based callout number matching the
+      #     `<N>` marker embedded in the parent block's content.
+      attribute :index, :integer
+
+      # @!attribute content
+      #   @return [String, nil] human-readable annotation text.
+      attribute :content, :string
+
+      private
+
+      def comparable_attributes
+        super + %i[index content]
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/callout_text.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Shared helpers for rendering Callout-annotated verbatim blocks.
+    #
+    # Both the Markdown and HTML spokes need to (a) order callouts by their
+    # numeric index and (b) strip AsciiDoc-style `<N>` markers from the
+    # raw code so they don't leak as literal text in the output format.
+    # Centralizing these operations here keeps the behavior consistent
+    # across spokes and avoids copy-paste drift.
+    module CalloutText
+      module_function
+
+      def ordered(callouts)
+        Array(callouts).sort_by { |c| c.index || Float::INFINITY }
+      end
+
+      # Removes callout markers (`<N>`) from `code` for the indices
+      # referenced by `callouts`. Returns `code` unchanged when no
+      # callouts are provided or none carry a usable index, so literal
+      # `<N>` sequences in code without callouts are preserved.
+      def strip_markers(code, callouts)
+        list = Array(callouts)
+        return code if list.empty?
+
+        indices = list.filter_map(&:index).uniq
+        return code if indices.empty?
+
+        pattern = /<\s*(?:#{indices.join('|')})\s*>/
+        code.to_s.lines(chomp: true).map { |line| line.gsub(pattern, '').rstrip }.join("\n")
+      end
+    end
+  end
+end

data/lib/coradoc/core_model.rb

@@ -12,6 +12,8 @@ module Coradoc
     # Autoload submodules lazily using relative paths
     autoload :Base, "#{__dir__}/core_model/base"
     autoload :ChildrenContent, "#{__dir__}/core_model/children_content"
+    autoload :Callout, "#{__dir__}/core_model/callout"
+    autoload :CalloutText, "#{__dir__}/core_model/callout_text"
     autoload :Block, "#{__dir__}/core_model/block"
     autoload :AnnotationBlock, "#{__dir__}/core_model/annotation_block"
     autoload :ListBlock, "#{__dir__}/core_model/list_block"

data/lib/coradoc/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Coradoc
-  VERSION = '2.0.19'
+  VERSION = '2.0.20'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: coradoc
 version: !ruby/object:Gem::Version
-  version: 2.0.19
+  version: 2.0.20
 platform: ruby
 authors:
 - Ribose Inc.
@@ -60,6 +60,8 @@ files:
 - lib/coradoc/core_model/bibliography.rb
 - lib/coradoc/core_model/bibliography_entry.rb
 - lib/coradoc/core_model/block.rb
+- lib/coradoc/core_model/callout.rb
+- lib/coradoc/core_model/callout_text.rb
 - lib/coradoc/core_model/children_content.rb
 - lib/coradoc/core_model/comment_block.rb
 - lib/coradoc/core_model/comment_line.rb