metanorma-plugin-glossarist 0.3.9 → 0.4.0

data/lib/metanorma/plugin/glossarist/field_filter.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Plugin
+    module Glossarist
+      # A single field-based filter specification: a path through the concept
+      # graph, a matcher kind, and the comparison value.
+      #
+      # FieldFilter is the structured representation behind ConceptFilter's
+      # field-filter DSL. ConceptFilter parses the legacy pseudo-syntax
+      # (e.g. +key.start_with(pattern)=ignored+) into FieldFilter instances;
+      # future syntaxes (regex, contains) only need a new matcher symbol.
+      FieldFilter = Struct.new(:path, :matcher, :value, keyword_init: true) do
+        START_WITH_SUFFIX = /\.start_with\(([^)]+)\)\z/
+
+        # Parses a single filter hash entry (path-key, optional value) into
+        # a FieldFilter. Two shapes are recognized:
+        #
+        #   - "data.path" => "value" → matcher :eq, value "value"
+        #   - "data.path.start_with(pattern)" => _ → matcher :start_with,
+        #     value "pattern" (the hash value is ignored)
+        #
+        # @param path [String] raw filter key
+        # @param raw_value [String, nil] raw filter value
+        # @return [FieldFilter]
+        def self.from_options_entry(path, raw_value)
+          if (match = path.match(START_WITH_SUFFIX))
+            FieldFilter.new(
+              path: match.pre_match,
+              matcher: :start_with,
+              value: match[1],
+            )
+          else
+            FieldFilter.new(path: path, matcher: :eq, value: raw_value)
+          end
+        end
+
+        # Applies the filter to a single concept via the given path resolver.
+        # @param resolver [ConceptPathResolver]
+        # @param concept [ManagedConcept]
+        def match?(resolver, concept)
+          actual = resolver.resolve(concept, path)
+          case matcher
+          when :start_with then actual&.start_with?(value.to_s)
+          else actual == value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/plugin/glossarist/liquid/custom_blocks/with_glossarist_context.rb

@@ -31,7 +31,7 @@ module Metanorma
 
             @contexts.each do |local_context|
               path = local_context[:file_path].strip
-              collection = registry ? registry.concepts_at(path) : load_collection(path)
+              collection = concepts_for(registry, path)
               filtered = ConceptFilter.new(@raw_filters).apply(collection)
               context[local_context[:name]] = filtered.map do |c|
                 ManagedConceptDrop.new(c)
@@ -51,10 +51,14 @@ module Metanorma
             end
           end
 
-          def load_collection(folder_path)
-            collection = ::Glossarist::ManagedConceptCollection.new
-            collection.load_from_files(folder_path)
-            collection
+          def concepts_for(registry, path)
+            return registry.concepts_at(path) if registry
+
+            fallback_store(path).concepts
+          end
+
+          def fallback_store(path)
+            ::Glossarist::GlossaryStore.new.load_directory(path)
           end
         end
       end

data/lib/metanorma/plugin/glossarist/liquid_rendering.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "liquid"
-
 module Metanorma
   module Plugin
     module Glossarist
@@ -16,7 +14,10 @@ module Metanorma
             Liquid::LocalFileSystem.new(include_paths, patterns)
           template.registers[:dataset_registry] = registry if registry
           rendered = template.render(assigns)
-          raise template.errors.first.cause if template.errors.any?
+          if template.errors.any?
+            error = template.errors.first
+            raise error.cause || error
+          end
 
           rendered
         end

data/lib/metanorma/plugin/glossarist/liquid_templates/_concept.liquid

@@ -29,9 +29,14 @@ domain:[{{ l10n.data.domain }}]
 {% for note in l10n.data.notes.definitions -%}
 [NOTE]
 ====
-{{ note.content | sanitize_references }}
-====
+{{ note.content | sanitize_references }}{% for example in note.examples %}
 
+[example]
+====
+{{ example.content | sanitize_references }}
+====
+{% endfor %}
+====
 {% endfor %}
 {% if l10n.data.annotations -%}
 {% for annotation in l10n.data.annotations.definitions -%}

data/lib/metanorma/plugin/glossarist/mention_extractor.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Plugin
+    module Glossarist
+      # Extracts bibliography-citable mention IDs from concept text using
+      # +Glossarist::ReferenceExtractor+ as the single canonical parser.
+      #
+      # Bibliography relevance = +BibliographicReference+ (from +<<anchor>>+
+      # xrefs) and +ConceptReference+ instances whose +#cite?+ is true (from
+      # +{{cite:id}}+ mentions). Other mention kinds (fig/table/formula/urn)
+      # reference assets or concepts, not bibliography entries.
+      class MentionExtractor
+        def initialize(text)
+          @text = text
+        end
+
+        def bibliography_ids
+          refs = ::Glossarist::ReferenceExtractor.new
+            .extract_from_text(@text.to_s)
+          refs.filter_map { |ref| bibliography_id(ref) }.uniq
+        end
+
+        private
+
+        def bibliography_id(ref)
+          case ref
+          when ::Glossarist::BibliographicReference
+            ref.anchor
+          when ::Glossarist::ConceptReference
+            ref.concept_id if ref.cite?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/plugin/glossarist/non_verbal_formatters/base.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Plugin
+    module Glossarist
+      module NonVerbalFormatters
+        # Shared rendering helpers for non-verbal entity formatters.
+        #
+        # Each formatter owns the kind-specific body (image block, table
+        # block, stem block) and delegates anchor, caption, and a11y
+        # framing to this base. Localized text is resolved by ISO 639 code
+        # with graceful fallback to the first available value.
+        class Base
+          def initialize(entity, lang: "eng")
+            @entity = entity
+            @lang = lang
+          end
+
+          def to_asciidoc
+            parts = [anchor_line, caption_line, body].compact.reject(&:empty?)
+            "#{parts.join("\n")}\n"
+          end
+
+          protected
+
+          attr_reader :entity, :lang
+
+          # Subclasses implement this with the kind-specific AsciiDoc body
+          # (e.g. image::, table, stem block).
+          def body
+            raise NotImplementedError
+          end
+
+          def anchor_line
+            id = entity.id
+            id ? "[[#{id}]]" : nil
+          end
+
+          def caption_line
+            text = localized(entity.caption)
+            text ? ".#{text}" : nil
+          end
+
+          def alt_text
+            localized(entity.alt)
+          end
+
+          def description_text
+            localized(entity.description)
+          end
+
+          # Picks the value for the requested language, falling back to
+          # the first available value if missing. Returns nil for empty
+          # or absent hashes.
+          def localized(hash)
+            return nil if hash.nil? || hash.empty?
+
+            hash[lang] || hash.values.first
+          end
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/plugin/glossarist/non_verbal_formatters/figure.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Plugin
+    module Glossarist
+      module NonVerbalFormatters
+        # Renders a Glossarist::Figure as an AsciiDoc image block.
+        #
+        # Picks a single best image variant: vector (SVG) preferred for
+        # resolution-independence, then any first image. Subfigures are
+        # rendered recursively as separate image blocks so each carries
+        # its own anchor and caption.
+        class Figure < Base
+          ROLE_PRIORITY = %w[vector raster print light dark].freeze
+
+          protected
+
+          def body
+            image = best_image
+            return subfigure_blocks if image.nil?
+
+            line = "image::#{image.src}[#{image_attrs(image)}]"
+            subfigure_blocks ? "#{line}\n\n#{subfigure_blocks}" : line
+          end
+
+          private
+
+          def best_image
+            images = Array(entity.images)
+            return nil if images.empty?
+
+            ROLE_PRIORITY.each do |role|
+              found = images.find { |img| img.role == role }
+              return found if found
+            end
+            images.first
+          end
+
+          def image_attrs(image)
+            attrs = []
+            attrs << alt_text if alt_text
+            attrs << "width=#{image.width}" if image.width
+            attrs << "height=#{image.height}" if image.height
+            attrs.join(",")
+          end
+
+          def subfigure_blocks
+            subs = Array(entity.subfigures)
+            return nil if subs.empty?
+
+            subs.map do |sub|
+              self.class.new(sub, lang: lang).to_asciidoc
+            end.join("\n").strip
+          end
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/plugin/glossarist/non_verbal_formatters/formula.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Plugin
+    module Glossarist
+      module NonVerbalFormatters
+        # Renders a Glossarist::Formula as an AsciiDoc stem block.
+        #
+        # The expression hash is keyed by language (matching caption/alt);
+        # the +notation+ field carries the markup language (latex, mathml,
+        # asciimath) but the body is format-agnostic — Metanorma's stem
+        # block accepts any notation supported by the renderer.
+        class Formula < Base
+          protected
+
+          def body
+            expr = localized(entity.expression)
+            return "" if expr.nil? || expr.empty?
+
+            <<~STEM
+              [stem]
+              ++++
+              #{expr}
+              ++++
+            STEM
+          end
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/plugin/glossarist/non_verbal_formatters/table.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Plugin
+    module Glossarist
+      module NonVerbalFormatters
+        # Renders a Glossarist::Table as an AsciiDoc table block.
+        #
+        # Two payload shapes are supported:
+        #   - +format: structured+ — +content+ has +headers+ and +rows+
+        #     arrays, rendered as an AsciiDoc table.
+        #   - +format: asciidoc+ (or any non-structured) — +content+ is a
+        #     raw markup string emitted verbatim between caption and the
+        #     next block.
+        class Table < Base
+          STRUCTURED = "structured"
+
+          protected
+
+          def body
+            entity.format == STRUCTURED ? structured_table : raw_block
+          end
+
+          private
+
+          def structured_table
+            lines = ["|==="]
+            append_headers(lines)
+            Array(entity.content&.dig("rows")).each do |row|
+              lines << "|#{Array(row).join(' |')}"
+            end
+            lines << "|==="
+            lines.join("\n")
+          end
+
+          def append_headers(lines)
+            headers = Array(entity.content&.dig("headers"))
+            lines << "|#{headers.join(' |')}" unless headers.empty?
+          end
+
+          def raw_block
+            content = entity.content
+            (content&.dig("asciidoc") || content&.dig("text")).to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/plugin/glossarist/non_verbal_formatters.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Plugin
+    module Glossarist
+      # Namespace for per-kind AsciiDoc formatters for dataset-level
+      # non-verbal entities. Adding a new kind = adding a new formatter
+      # class and registering it in NonVerbalRenderer::FORMATTERS.
+      module NonVerbalFormatters
+        autoload :Base, "metanorma/plugin/glossarist/non_verbal_formatters/base"
+        autoload :Figure,
+                 "metanorma/plugin/glossarist/non_verbal_formatters/figure"
+        autoload :Table,
+                 "metanorma/plugin/glossarist/non_verbal_formatters/table"
+        autoload :Formula,
+                 "metanorma/plugin/glossarist/non_verbal_formatters/formula"
+      end
+    end
+  end
+end

data/lib/metanorma/plugin/glossarist/non_verbal_renderer.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Plugin
+    module Glossarist
+      # Renders dataset-level non-verbal entities (Figure, Table, Formula)
+      # as AsciiDoc blocks. MECE sibling to BibliographyRenderer: where
+      # BibliographyRenderer owns citation provenance, NonVerbalRenderer
+      # owns the rendering of authored figures/tables/formulas.
+      #
+      # Per-kind formatting is delegated to a formatter class registered
+      # in +FORMATTERS+. Adding a new kind = adding one formatter class
+      # and one entry here; the dispatcher itself never changes shape.
+      class NonVerbalRenderer
+        FORMATTERS = {
+          figures: NonVerbalFormatters::Figure,
+          tables: NonVerbalFormatters::Table,
+          formulas: NonVerbalFormatters::Formula,
+        }.freeze
+
+        # @param collections [Hash{Symbol => NonVerbalCollection, nil}]
+        #   one entry per non-verbal kind, e.g.
+        #   `{ figures: FigureCollection, tables: ..., formulas: ... }`.
+        #   Missing or nil entries are silently skipped.
+        def initialize(collections:, lang: "eng")
+          @collections = collections
+          @lang = lang
+        end
+
+        # Render every entity in the named collection.
+        #
+        # @param kind [Symbol] key in FORMATTERS (e.g. +:figures+)
+        # @return [String] AsciiDoc blocks joined by blank lines, or ""
+        def render_kind(kind)
+          collection = @collections[kind]
+          return "" if collection.nil? || collection.entries.empty?
+
+          entries = collection.entries
+          "#{entries.map { |e| format_one(kind, e) }.join("\n\n")}\n"
+        end
+
+        # Render the non-verbal entities referenced by a concept's
+        # figures/tables/formulas ref collections, in deterministic order
+        # (figures, tables, formulas). Unknown refs are skipped silently —
+        # they will surface as missing anchors during Metanorma rendering.
+        #
+        # @param concept [Glossarist::ManagedConcept]
+        # @return [String]
+        def render_concept_refs(concept)
+          FORMATTERS.keys.filter_map do |kind|
+            refs = concept_refs(concept, kind)
+            next if refs.empty?
+
+            blocks = refs.filter_map { |ref| render_ref(kind, ref) }
+            next if blocks.empty?
+
+            "#{blocks.join("\n\n")}\n"
+          end.join("\n")
+        end
+
+        private
+
+        def render_ref(kind, ref)
+          collection = @collections[kind]
+          return nil unless collection
+
+          entity = collection.by_id(ref.entity_id)
+          return nil unless entity
+
+          format_one(kind, entity)
+        end
+
+        def format_one(kind, entity)
+          FORMATTERS.fetch(kind).new(entity, lang: @lang).to_asciidoc
+        end
+
+        def concept_refs(concept, kind)
+          refs = concept.data&.public_send(kind)
+          Array(refs)
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/plugin/glossarist/sanitize.rb

@@ -5,7 +5,6 @@ module Metanorma
     module Glossarist
       module Sanitize
         REF_REGEX = /{{(urn:[^,{}]+),([^}]+?)}}(.*)$/m
-        XREF_REGEX = /<<((?>[^,>\n]+))(?:,[^>\n]*)?>>/
 
         def self.references(str)
           return str unless str&.match?(REF_REGEX)
@@ -16,12 +15,6 @@ module Metanorma
             "{{#{urn},#{m[2]}}}#{m[3]}"
           end
         end
-
-        def self.extract_xrefs(text)
-          return [] unless text
-
-          text.scan(XREF_REGEX).map(&:first).uniq
-        end
       end
     end
   end

data/lib/metanorma/plugin/glossarist/section_renderer.rb

@@ -18,7 +18,7 @@ module Metanorma
         # @param register [Glossarist::DatasetRegister, nil] for cascading
         # @param renderer [TemplateRenderer] concept renderer
         # @param depth [Integer] base heading depth for sections
-        # @param options [Hash] :sort_by, :anchor_prefix
+        # @param options [Hash] :sort_by, :anchor_prefix, :non_verbal
         def initialize(dataset:, register:, renderer:, depth:, **options)
           @dataset = dataset
           @register = register
@@ -26,6 +26,7 @@ module Metanorma
           @depth = depth
           @sort_by = options[:sort_by] || DEFAULT_SORT_BY
           @anchor_prefix = options[:anchor_prefix]
+          @non_verbal = options[:non_verbal]
         end
 
         # @param sections [Array<Glossarist::Section>]
@@ -55,7 +56,8 @@ module Metanorma
           heading = "#{'=' * (@depth + 1)} #{section.name || section.id}"
           body = @renderer.render_concepts(concepts,
                                            depth: @depth + 1,
-                                           anchor_prefix: @anchor_prefix)
+                                           anchor_prefix: @anchor_prefix,
+                                           non_verbal: @non_verbal)
           "#{heading}\n\n#{body}"
         end
       end

data/lib/metanorma/plugin/glossarist/template_renderer.rb

@@ -9,16 +9,19 @@ module Metanorma
         def initialize(file_system:, lang: "eng")
           @file_system = file_system
           @lang = lang
-          @template_cache = {}
         end
 
-        def render_concepts(concepts, depth:, anchor_prefix: nil)
+        def render_concepts(concepts, depth:, anchor_prefix: nil,
+                            non_verbal: nil)
           tree = build_concept_tree(concepts)
-          parts = tree.map { |c| render_tree_node(c, depth, anchor_prefix) }
+          parts = tree.map do |node|
+            render_tree_node(node, depth, anchor_prefix, non_verbal)
+          end
           normalize_whitespace(parts.join("\n\n"))
         end
 
-        def render_concept(concept, depth:, anchor_prefix: nil)
+        def render_concept(concept, depth:, anchor_prefix: nil,
+                           non_verbal: nil)
           l10n = concept.localization(@lang)
           context = {
             "concept" => concept.to_liquid,
@@ -26,27 +29,23 @@ module Metanorma
             "depth_marker" => "=" * (depth + 1),
             "anchor" => build_anchor(concept.data.id.to_s, anchor_prefix),
           }
-          template_content = cached_template(concept)
-          rendered = render_template(template_content, context)
+          rendered = render_template(File.read(DEFAULT_TEMPLATE), context)
+          if non_verbal
+            rendered += "\n\n#{non_verbal.render_concept_refs(concept)}"
+          end
           normalize_whitespace(rendered)
         end
 
         private
 
-        def cached_template(concept)
-          version = concept.schema_version
-          @template_cache[version] ||= begin
-            path = File.join(TEMPLATES_DIR, "_concept_#{version}.liquid")
-            File.exist?(path) ? File.read(path) : File.read(DEFAULT_TEMPLATE)
-          end
-        end
-
-        def render_tree_node((concept, children), depth, anchor_prefix)
+        def render_tree_node((concept, children), depth, anchor_prefix,
+                             non_verbal)
           result = render_concept(concept, depth: depth,
-                                           anchor_prefix: anchor_prefix)
+                                           anchor_prefix: anchor_prefix,
+                                           non_verbal: non_verbal)
           children.each do |child_node|
             result += "\n" + render_tree_node(child_node, depth + 1,
-                                              anchor_prefix)
+                                              anchor_prefix, non_verbal)
           end
           result
         end

data/lib/metanorma/plugin/glossarist/version.rb

@@ -3,7 +3,7 @@
 module Metanorma
   module Plugin
     module Glossarist
-      VERSION = "0.3.9"
+      VERSION = "0.4.0"
     end
   end
 end

data/lib/metanorma-plugin-glossarist.rb

@@ -19,8 +19,15 @@ module Metanorma
                "metanorma/plugin/glossarist/dataset_preprocessor"
       autoload :DatasetRegistry, "metanorma/plugin/glossarist/dataset_registry"
       autoload :Document, "metanorma/plugin/glossarist/document"
+      autoload :FieldFilter, "metanorma/plugin/glossarist/field_filter"
       autoload :Liquid, "metanorma/plugin/glossarist/liquid"
       autoload :LiquidRendering, "metanorma/plugin/glossarist/liquid_rendering"
+      autoload :MentionExtractor,
+               "metanorma/plugin/glossarist/mention_extractor"
+      autoload :NonVerbalFormatters,
+               "metanorma/plugin/glossarist/non_verbal_formatters"
+      autoload :NonVerbalRenderer,
+               "metanorma/plugin/glossarist/non_verbal_renderer"
       autoload :Sanitize, "metanorma/plugin/glossarist/sanitize"
       autoload :SectionCascade, "metanorma/plugin/glossarist/section_cascade"
       autoload :SectionFilter, "metanorma/plugin/glossarist/section_filter"

data/metanorma-plugin-glossarist.gemspec

@@ -26,7 +26,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = ">= 3.1.0"
 
   spec.add_dependency "asciidoctor"
-  spec.add_dependency "glossarist", "~> 2.8", ">= 2.8.16"
+  spec.add_dependency "glossarist", "~> 2.8", ">= 2.9.0"
   spec.add_dependency "liquid"
   spec.add_dependency "metanorma-utils"
   spec.metadata["rubygems_mfa_required"] = "true"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: metanorma-plugin-glossarist
 version: !ruby/object:Gem::Version
-  version: 0.3.9
+  version: 0.4.0
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-18 00:00:00.000000000 Z
+date: 2026-07-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asciidoctor
@@ -33,7 +33,7 @@ dependencies:
         version: '2.8'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.8.16
+        version: 2.9.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -43,7 +43,7 @@ dependencies:
         version: '2.8'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.8.16
+        version: 2.9.0
 - !ruby/object:Gem::Dependency
   name: liquid
   requirement: !ruby/object:Gem::Requirement
@@ -100,6 +100,7 @@ files:
 - lib/metanorma/plugin/glossarist/dataset_preprocessor.rb
 - lib/metanorma/plugin/glossarist/dataset_registry.rb
 - lib/metanorma/plugin/glossarist/document.rb
+- lib/metanorma/plugin/glossarist/field_filter.rb
 - lib/metanorma/plugin/glossarist/liquid.rb
 - lib/metanorma/plugin/glossarist/liquid/custom_blocks/with_glossarist_context.rb
 - lib/metanorma/plugin/glossarist/liquid/custom_filters.rb
@@ -111,6 +112,13 @@ files:
 - lib/metanorma/plugin/glossarist/liquid/multiply_local_file_system.rb
 - lib/metanorma/plugin/glossarist/liquid_rendering.rb
 - lib/metanorma/plugin/glossarist/liquid_templates/_concept.liquid
+- lib/metanorma/plugin/glossarist/mention_extractor.rb
+- lib/metanorma/plugin/glossarist/non_verbal_formatters.rb
+- lib/metanorma/plugin/glossarist/non_verbal_formatters/base.rb
+- lib/metanorma/plugin/glossarist/non_verbal_formatters/figure.rb
+- lib/metanorma/plugin/glossarist/non_verbal_formatters/formula.rb
+- lib/metanorma/plugin/glossarist/non_verbal_formatters/table.rb
+- lib/metanorma/plugin/glossarist/non_verbal_renderer.rb
 - lib/metanorma/plugin/glossarist/sanitize.rb
 - lib/metanorma/plugin/glossarist/section_cascade.rb
 - lib/metanorma/plugin/glossarist/section_filter.rb