coradoc-adoc 2.0.19 → 2.0.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 817eba65c55a5dea765ab8e80ee5542a1353741659c8a32ef4eb80e39f052dcb
-  data.tar.gz: 25a07bc63696b7ba27933c9724c0a5ada466dc7cd0f37350ae4c9a4a475afbec
+  metadata.gz: fad1b11f8028b7157066b7a2d4474b2d20e3cab1e526e0347ca36015cdf3ad90
+  data.tar.gz: d143bb70ec7ab2e3a1656a5e9ed72d52bb0b2f1341b3566efa02ef44343a2044
 SHA512:
-  metadata.gz: c3d26bcc8f91f799f455f051109933875545219b14e9556cc4d5774dcda16e9abdcb1f0e6a090f1d9aea35c49d4d7f5ed8c6bae2b1e47a76cc75a86270e47cd7
-  data.tar.gz: 50a575b3666d1d6df0a8813a9761345ced5d895b2c73bf80347d8fb24e36c396389d4901fa22a6f34e1adcea6cb4d5b697bdab121dc495603da88740753e821d
+  metadata.gz: 7848b8f80f104e960265ed5dbd295d4dfc7ad4cecb401b81765ae21ba6d16a31e02024ebfd7c65c1c86e0fd433512788a92ab4600b348293d895980bf2b5b446
+  data.tar.gz: c6a55d7b4abecd086fcbde8015fd54b217eb3a442f86699bd1ab110affc1f1dc20f9ff54ef24668dcc77fdcb1cf609b09651308bc4122ea47a05535e18585879

data/lib/coradoc/asciidoc/parser/block.rb

@@ -105,12 +105,24 @@ module Coradoc
         end
 
         def block_content(n_deep = 3)
-          c = block_image
+          block_container_content(n_deep).repeat(1)
+        end
+
+        # Single source of truth for "what can appear inside a non-verbatim
+        # block container". Used by block_content, block_style (non-verbatim
+        # branch), and block_style_exact (non-verbatim branch).
+        #
+        # `table` is listed before `text_line` so a leading `|===` is parsed
+        # as a table rather than mis-bracketed as text. The recursive `block`
+        # alternative handles every other delimited block.
+        def block_container_content(n_deep)
+          c = table.as(:table)
+          c |= block_image
           c |= block(n_deep - 1) if n_deep.positive?
           c |= list
           c |= text_line(false, unguarded: true)
           c |= empty_line.as(:line_break)
-          c.repeat(1)
+          c
         end
 
         # Block delimiter: 4+ identical characters, or 2 dashes for open
@@ -155,12 +167,7 @@ module Coradoc
                         text_line(false, unguarded: true, verbatim: true) |
                           empty_line.as(:line_break)
                       else
-                        c = block_image
-                        c |= block(n_deep - 1) if n_deep.positive?
-                        c |= list
-                        c |= text_line(false, unguarded: true)
-                        c |= empty_line.as(:line_break)
-                        c
+                        block_container_content(n_deep)
                       end
 
             (closing_pattern.absent? >> content).repeat(1)
@@ -213,12 +220,7 @@ module Coradoc
                         text_line(false, unguarded: true, verbatim: true) |
                           empty_line.as(:line_break)
                       else
-                        alt = block_image
-                        alt |= block(n_deep - 1) if n_deep.positive?
-                        alt |= list
-                        alt |= text_line(false, unguarded: true)
-                        alt |= empty_line.as(:line_break)
-                        alt
+                        block_container_content(n_deep)
                       end
 
             (closing_pattern.absent? >> content).repeat(1)

data/lib/coradoc/asciidoc/transform/element_transformers/admonition_styles.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module AsciiDoc
+    module Transform
+      module ElementTransformers
+        # Admonition style registry. Single source of truth for "which
+        # positional attribute names map to an admonition block."
+        #
+        # Built-in AsciiDoc admonition styles are always recognized. Callers
+        # can register additional styles (e.g. +DANGER+, +SAFETY+) without
+        # modifying dispatch code — the registry is consulted by every
+        # block-form transformer that needs to decide between an admonition
+        # and the block's native type.
+        module AdmonitionStyles
+          BUILTIN = %w[note tip warning caution important editor todo].freeze
+
+          @custom = []
+
+          class << self
+            # True if +style+ (case-insensitive) is a known admonition style.
+            def admonition?(style)
+              return false if style.nil?
+
+              name = style.to_s.downcase
+              BUILTIN.include?(name) || custom.include?(name)
+            end
+
+            # Register an additional admonition style. Open for extension.
+            def register(style)
+              name = style.to_s.downcase
+              @custom << name unless @custom.include?(name) || BUILTIN.include?(name)
+              self
+            end
+
+            # Reset custom registrations. Intended for specs.
+            def reset!
+              @custom = []
+              self
+            end
+
+            def custom
+              @custom.dup
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/asciidoc/transform/element_transformers/block_transformer.rb

@@ -21,7 +21,7 @@ module Coradoc
             # line; we join with "\n" so whitespace, indentation, and blank
             # lines are preserved. Treating these as paragraphs would collapse
             # whitespace and join consecutive lines into a single flowing text.
-            def transform_verbatim_block(block, klass)
+            def transform_verbatim_block(block, klass, language_override: nil)
               non_break_lines = Array(block.lines).reject do |line|
                 line.is_a?(Coradoc::AsciiDoc::Model::LineBreak) ||
                   line.is_a?(Coradoc::AsciiDoc::Model::Break::PageBreak)
@@ -34,7 +34,7 @@ module Coradoc
                 id: block.id,
                 title: ToCoreModel.extract_title_text(block.title),
                 content: content_lines,
-                language: ToCoreModel.extract_block_language(block)
+                language: language_override || ToCoreModel.extract_block_language(block)
               )
             end
 
@@ -47,9 +47,54 @@ module Coradoc
             end
 
             def transform_pass_block(block)
+              style = first_positional_attr(block)
+              return transform_stem_block(block, style) if STEM_STYLES.key?(style.to_s.downcase)
+
               transform_verbatim_block(block, Coradoc::CoreModel::PassBlock)
             end
 
+            # AsciiDoc recognizes three STEM block styles. The default
+            # `[stem]` resolves to LaTeX; the other two name their
+            # interpreter explicitly. Single source of truth for the
+            # style→language mapping.
+            STEM_STYLES = {
+              'stem' => 'latex',
+              'latexmath' => 'latex',
+              'asciimath' => 'asciimath'
+            }.freeze
+
+            def transform_stem_block(block, style)
+              language = STEM_STYLES.fetch(style.to_s.downcase, 'latex')
+              transform_verbatim_block(block, Coradoc::CoreModel::StemBlock,
+                                       language_override: language)
+            end
+
+            # Dispatch entry point for any block whose AsciiDoc model carries
+            # an attribute list (delimited blocks + open blocks). Per the
+            # AsciiDoc spec, every delimited block accepts admonition styles
+            # in its attribute line. Admonition style wins for example,
+            # sidebar, quote, and open blocks; verbatim blocks (source,
+            # listing) intentionally ignore it because their verbatim
+            # semantics are stronger than the annotation label.
+            def transform_with_admonition_check(block, native_class)
+              style = first_positional_attr(block)
+              return transform_admonition_block(block, style) if AdmonitionStyles.admonition?(style)
+
+              transform_typed_block(block, native_class)
+            end
+
+            def transform_example_block(block)
+              transform_with_admonition_check(block, Coradoc::CoreModel::ExampleBlock)
+            end
+
+            def transform_sidebar_block(block)
+              transform_with_admonition_check(block, Coradoc::CoreModel::SidebarBlock)
+            end
+
+            def transform_quote_block(block)
+              transform_with_admonition_check(block, Coradoc::CoreModel::QuoteBlock)
+            end
+
             # Open blocks (`--`) are generic containers. AsciiDoc allows
             # casting them to a different block type via positional
             # attributes: verbatim types (`[source]`, `[listing]`,
@@ -60,41 +105,53 @@ module Coradoc
             def transform_open_block(block)
               semantic = open_block_semantic(block)
               case semantic
-              when :source_code
+              when :source
                 transform_source_block(block)
               when :listing
                 transform_listing_from_open(block)
               when :literal
                 transform_literal_from_open(block)
               when :admonition
-                transform_admonition_from_open(block)
+                transform_admonition_block(block, first_positional_attr(block))
               else
                 transform_typed_block(block, Coradoc::CoreModel::OpenBlock)
               end
             end
 
-            ADMONITION_TYPES = %w[note tip warning caution important].freeze
+            VERBATILE_CAST_STYLES = %w[source listing literal].freeze
 
             def open_block_semantic(block)
+              style = first_positional_attr(block)
+              return nil unless style
+
+              case style.to_s.downcase
+              when *VERBATILE_CAST_STYLES then :"#{style.downcase}"
+              else :admonition if AdmonitionStyles.admonition?(style)
+              end
+            end
+
+            # Returns the first positional attribute on the block's
+            # attribute list as a String, or nil if absent. Centralizes the
+            # shape-walking that was previously inlined in
+            # `transform_admonition_from_open` and `open_block_semantic`.
+            def first_positional_attr(block)
               attrs = block.attributes
               return nil unless attrs.is_a?(Coradoc::AsciiDoc::Model::AttributeList)
 
               first = attrs.positional&.first
               return nil unless first.is_a?(Coradoc::AsciiDoc::Model::AttributeListAttribute)
 
-              case first.value.to_s.downcase
-              when 'source' then :source_code
-              when 'listing' then :listing
-              when 'literal' then :literal
-              when *ADMONITION_TYPES then :admonition
-              end
+              first.value.to_s
             end
 
-            def transform_admonition_from_open(block)
-              type = block.attributes.positional.first.value.to_s.downcase
+            # Single admonition dispatch used by every block-form path
+            # (example / sidebar / quote / pass / open). Builds an
+            # AnnotationBlock with annotation_type set from the style and
+            # the block's body lines joined into a single content string.
+            def transform_admonition_block(block, type)
               content_lines = Array(block.lines).map { |line| ToCoreModel.extract_text_content(line) }.join("\n")
               Coradoc::CoreModel::AnnotationBlock.new(
-                annotation_type: type,
+                annotation_type: type.to_s.downcase,
                 content: content_lines,
                 title: ToCoreModel.extract_title_text(block.title)
               )

data/lib/coradoc/asciidoc/transform/element_transformers/document_transformer.rb

@@ -12,6 +12,7 @@ module Coradoc
               children = ToCoreModel.transform(doc.sections || doc.contents || [])
               children = CalloutMerger.call(children)
               children = prepend_frontmatter(children, doc.frontmatter)
+              children = insert_title_heading_after_frontmatter(children, title_text)
 
               Coradoc::CoreModel::DocumentElement.new(
                 id: doc.id,
@@ -32,6 +33,31 @@ module Coradoc
               [block, *children]
             end
 
+            # Per the AsciiDoc spec, the document title (`= Title`) is the
+            # document's level-0 heading. Asciidoctor renders it as an
+            # <h1> at the top of the body by default. Emit a HeaderElement
+            # at level 0 so consumers that walk the body's children see the
+            # title (the standard ProseMirror/HTML rendering pattern)
+            # instead of having to read Document.title separately.
+            #
+            # The title attribute on DocumentElement is preserved for
+            # consumers that read it directly. The title heading is placed
+            # after any FrontmatterBlock (frontmatter is metadata that
+            # precedes the body).
+            def insert_title_heading_after_frontmatter(children, title_text)
+              return children if title_text.nil? || title_text.strip.empty?
+
+              title_heading = Coradoc::CoreModel::HeaderElement.new(
+                level: 0,
+                title: title_text,
+                content: title_text
+              )
+              frontmatter_count = children.count do |child|
+                child.is_a?(Coradoc::CoreModel::FrontmatterBlock)
+              end
+              children.insert(frontmatter_count, title_heading)
+            end
+
             def transform_section(section, parent_id: nil)
               title_text = ToCoreModel.extract_title_text(section.title)
               section_id = section.id || Coradoc::CoreModel::IdGenerator.generate_from_title(

data/lib/coradoc/asciidoc/transform/element_transformers.rb

@@ -11,6 +11,7 @@ module Coradoc
         autoload :TableTransformer, "#{__dir__}/element_transformers/table_transformer"
         autoload :OtherTransformer, "#{__dir__}/element_transformers/other_transformer"
         autoload :IncludeTransformer, "#{__dir__}/element_transformers/include_transformer"
+        autoload :AdmonitionStyles, "#{__dir__}/element_transformers/admonition_styles"
       end
     end
   end

data/lib/coradoc/asciidoc/transform/from_core_model.rb

@@ -40,12 +40,18 @@ module Coradoc
                          Coradoc::AsciiDoc::Model::Header.new(title: '')
                        end
 
-              sections, frontmatter = extract_frontmatter(Array(element.children))
+              # Pull FrontmatterBlock out first so strip_title_heading sees
+              # the body children in their natural order (frontmatter →
+              # title heading → body). The reverse-direction strip then
+              # matches on a level-0 HeaderElement wherever it sits among
+              # the remaining children.
+              without_frontmatter, frontmatter = extract_frontmatter(Array(element.children))
+              without_title = strip_title_heading(without_frontmatter, element.title)
 
               Coradoc::AsciiDoc::Model::Document.new(
                 id: element.id,
                 header: header,
-                sections: flatten_children(sections),
+                sections: flatten_children(without_title),
                 frontmatter: frontmatter
               )
             when CoreModel::SectionElement
@@ -64,6 +70,27 @@ module Coradoc
             end
           end
 
+          # The forward direction (DocumentTransformer#insert_title_heading_after_frontmatter)
+          # emits a level-0 HeaderElement after any FrontmatterBlock so
+          # consumers that walk the children see the title. On the reverse
+          # path, that HeaderElement would round-trip back as a separate
+          # body element and the title would be emitted twice (once via
+          # the document header, once via the heading child). Drop it
+          # before serialization when it carries the same text as the
+          # document title.
+          def strip_title_heading(children, document_title)
+            return children unless document_title && !document_title.strip.empty?
+
+            index = children.find_index do |child|
+              child.is_a?(CoreModel::HeaderElement) &&
+                child.level.to_i.zero? &&
+                child.title.to_s == document_title.to_s
+            end
+            return children unless index
+
+            children.reject.with_index { |_, i| i == index }
+          end
+
           # Transforms each CoreModel child and flattens one level so a
           # transform that returns multiple siblings (e.g. a source block
           # followed by its re-expanded callout paragraphs) stays in

data/lib/coradoc/asciidoc/transform/to_core_model_registrations.rb

@@ -48,14 +48,19 @@ module Coradoc
               priority: 10
             )
 
+            # Quote / Example / Sidebar blocks all share the same dispatch:
+            # check the attribute style for an admonition label first
+            # (`[NOTE]\n====` → AnnotationBlock), fall back to the block's
+            # native CoreModel type. Single source of truth lives in
+            # BlockTransformer#transform_with_admonition_check.
             {
-              Coradoc::AsciiDoc::Model::Block::Quote => Coradoc::CoreModel::QuoteBlock,
-              Coradoc::AsciiDoc::Model::Block::Example => Coradoc::CoreModel::ExampleBlock,
-              Coradoc::AsciiDoc::Model::Block::Side => Coradoc::CoreModel::SidebarBlock
-            }.each do |block_class, core_model_class|
+              Coradoc::AsciiDoc::Model::Block::Quote => :transform_quote_block,
+              Coradoc::AsciiDoc::Model::Block::Example => :transform_example_block,
+              Coradoc::AsciiDoc::Model::Block::Side => :transform_sidebar_block
+            }.each do |block_class, method|
               Registry.register_with_priority(
                 block_class,
-                ->(model) { Blk.transform_typed_block(model, core_model_class) },
+                ->(model) { Blk.public_send(method, model) },
                 priority: 10
               )
             end

data/lib/coradoc/asciidoc/version.rb

@@ -2,6 +2,6 @@
 
 module Coradoc
   module AsciiDoc
-    VERSION = '2.0.19'
+    VERSION = '2.0.20'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: coradoc-adoc
 version: !ruby/object:Gem::Version
-  version: 2.0.19
+  version: 2.0.20
 platform: ruby
 authors:
 - Ribose Inc.
@@ -317,6 +317,7 @@ files:
 - lib/coradoc/asciidoc/transform/attribute_list_to_metadata.rb
 - lib/coradoc/asciidoc/transform/callout_merger.rb
 - lib/coradoc/asciidoc/transform/element_transformers.rb
+- lib/coradoc/asciidoc/transform/element_transformers/admonition_styles.rb
 - lib/coradoc/asciidoc/transform/element_transformers/block_transformer.rb
 - lib/coradoc/asciidoc/transform/element_transformers/document_transformer.rb
 - lib/coradoc/asciidoc/transform/element_transformers/include_transformer.rb