metanorma-plugin-glossarist 0.3.8 → 0.3.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6af197cf777b6758b7501329133036b1473879481f64286c06e38a3799361b08
-  data.tar.gz: 0b8e385ddc8117c9f1793b813b304fcad57492d6379d14130152c97c818c699c
+  metadata.gz: 0e98a4e95056510d3c6071f7c46e4bd378b2898e7fa75b44e14d5ca423efc4ca
+  data.tar.gz: ebbf812935c1fb98b523675892813de831c1ec87d152d0de78d1fd9103d6342d
 SHA512:
-  metadata.gz: cd8f7aa3303315bac0579615dd3263fa76858accc6bfc7d4fd4aae8f9847f913023b0c038cc72a06df783710aeed5f655047fdb480c993cb2bbb64bf26b60ce9
-  data.tar.gz: 9f7c701f371ac937e815a8ce8242125dcbba3c9b7d84d9b1630f3d02530d1a6a0c2a4f7b37e0b2bd7b09f89425d82da48c4f7fb4d4a3419dd3e6a5337c10d245
+  metadata.gz: 99d6b54e76a006d51f7f657e5d408139e0dbcb1af14545f17d8f08f157d7c197c52a88934c84238560d5860dc0131fe78b4b4933c155934aea11410239a8cf6e
+  data.tar.gz: 34f5d1c25bb615c2a2a3efdac7710b9dd8e06d0c98c4f63bc4f8846475a952715fdf2269ca4dbc970a9bd5e0bdc17327f9f8204ef2c3a5ba42ed30a75d299747

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

@@ -5,14 +5,20 @@ require "set"
 module Metanorma
   module Plugin
     module Glossarist
+      # Renders iev termbank and dataset bibliography entries as AsciiDoc
+      # bibliography items for rendered concepts.
+      #
+      # Bibliography lookups go through the typed Glossarist::BibliographyData
+      # model — entries are matched by `id` and read via BibliographyEntry
+      # accessors (#reference, #title, #link).
       class BibliographyRenderer
         IEV_ENTRY = "* [[[ievtermbank,IEV]]], _IEV: Electropedia_"
         IEV_ANCHOR = "ievtermbank"
 
-        def initialize(existing_anchors: [], bibliography_data: {})
+        def initialize(existing_anchors: [], bibliography: nil)
           @rendered = {}
           @existing_anchors = Set.new(existing_anchors)
-          @bibliography_data = bibliography_data
+          @bibliography = bibliography
         end
 
         def render_entry(concept, lang: "eng")
@@ -32,15 +38,14 @@ module Metanorma
             source_entries(l10n)
           end.flatten
 
-          xref_entries = concepts.filter_map do |concept|
+          xref = concepts.filter_map do |concept|
             l10n = concept.localization(lang)
             next unless l10n
 
             xref_entries(l10n)
           end.flatten
 
-          all_entries.concat(xref_entries)
-
+          all_entries.concat(xref)
           all_entries.sort.join("\n")
         end
 
@@ -75,26 +80,30 @@ module Metanorma
           xref_ids.filter_map do |ref_id|
             next if @rendered.value?(ref_id)
             next if @existing_anchors.include?(ref_id)
-            next unless @bibliography_data.key?(ref_id)
-
-            anchor = ref_id
-            @rendered[ref_id] = anchor
+            next unless bibliography_entry(ref_id)
 
-            format_entry(anchor, ref_id)
+            @rendered[ref_id] = ref_id
+            format_entry(ref_id, ref_id)
           end
         end
 
         def format_entry(anchor, ref)
-          bib = @bibliography_data[ref]
-          return "* [[[#{anchor},#{ref}]]]" unless bib
+          entry = bibliography_entry(ref)
+          return "* [[[#{anchor},#{ref}]]]" unless entry
 
-          display_ref = bib["reference"] || ref
+          display_ref = entry.reference || ref
           parts = ["* [[[#{anchor},#{display_ref}]]]"]
-          parts << ", _#{bib['title']}_" if bib["title"]
-          parts << ". Available at: #{bib['link']} " if bib["link"]
+          parts << ", _#{entry.title}_" if entry.title
+          parts << ". Available at: #{entry.link} " if entry.link
           parts.join
         end
 
+        def bibliography_entry(ref_id)
+          return nil unless @bibliography
+
+          @bibliography.find(ref_id)
+        end
+
         def extract_content_xrefs(l10n)
           parts = []
           l10n.definition&.each { |d| parts << d.content.to_s }

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

@@ -3,64 +3,83 @@
 module Metanorma
   module Plugin
     module Glossarist
+      # Filters a concept collection by lang, domain, section, tag, generic
+      # field paths, and sort_by. Composable: every filter narrows the
+      # collection independently.
+      #
+      # Section filtering supports cascading membership: a concept in
+      # section "3.1.1" is also a member of "3.1" and "3" via transitive
+      # ancestor traversal. This requires a DatasetRegister collaborator
+      # (passed via `#apply`'s second arg) when section filtering is used.
       class ConceptFilter
         COLLECTION_FILTERS = %w[lang domain group section tag sort_by].freeze
         SORT_LAST = ["￿"].freeze
+        SECTION_REF_TYPE = "section"
+        DOMAIN_REF_TYPE = "domain"
 
         def initialize(filters)
           @filters = filters || {}
           @resolver = ConceptPathResolver.new
         end
 
-        def apply(collection)
-          result = collection
+        # Applies all configured filters in canonical order.
+        # @param collection [Enumerable<ManagedConcept>]
+        # @param register [Glossarist::DatasetRegister, nil] required for
+        #   cascading section filtering; ignored otherwise.
+        # @return [Array<ManagedConcept>]
+        def apply(collection, register: nil)
+          result = collection.to_a
           result = filter_by_lang(result) if @filters.key?("lang")
           if @filters.key?("domain") || @filters.key?("group")
             result = filter_by_domain(result)
           end
-          result = filter_by_section(result) if @filters.key?("section")
+          if @filters.key?("section")
+            result = filter_by_section(result,
+                                       register)
+          end
           result = filter_by_tag(result) if @filters.key?("tag")
-          result = filter_by_field(result) if field_filter?
+          result = filter_by_field(result) if field_filters?
           result = sort(result) if @filters.key?("sort_by")
           result
         end
 
         private
 
-        def field_filter?
+        def field_filters?
           (@filters.keys - COLLECTION_FILTERS).any?
         end
 
-        def field_filter_key
-          (@filters.keys - COLLECTION_FILTERS).first
-        end
-
         def filter_by_lang(collection)
           lang = @filters["lang"]
           collection.reject { |c| c.localization(lang).nil? }
         end
 
         def filter_by_domain(collection)
-          domain = @filters["domain"] || @filters["group"]
-          collection.select do |c|
-            c.data.domains&.any? { |d| d.concept_id == domain }
+          domain_id = @filters["domain"] || @filters["group"]
+          collection.select do |concept|
+            domain_ids(concept).include?(domain_id)
           end
         end
 
         def filter_by_tag(collection)
           tag = @filters["tag"]
-          collection.select do |c|
-            c.data.tags&.include?(tag)
-          end
+          collection.select { |c| c.data.tags&.include?(tag) }
         end
 
-        def filter_by_section(collection)
-          section_id = @filters["section"]
-          collection.select do |c|
-            c.data.domains&.any? { |d| d.concept_id == "section-#{section_id}" }
+        def filter_by_section(collection, register)
+          target_id = @filters["section"]
+          cascade = SectionCascade.new(register)
+          collection.select do |concept|
+            cascade.member?(concept, target_id)
           end
         end
 
+        def domain_ids(concept)
+          Array(concept.data&.domains)
+            .select { |d| d.ref_type == DOMAIN_REF_TYPE }
+            .filter_map(&:concept_id)
+        end
+
         def sort(collection)
           field = @filters["sort_by"]
           return collection unless field
@@ -84,29 +103,32 @@ module Metanorma
         end
 
         def filter_by_field(collection)
-          path = field_filter_key
-          value = @filters[path]
-
-          start_with = path.include?(".start_with(")
-          path, match_value = extract_start_with(path, value, start_with)
+          path, value, start_with = field_filter_spec
+          start_with_match_value = extract_start_with_value(path, value)
+          path, match_value = if start_with_match_value
+                                [start_with_match_value[:path],
+                                 start_with_match_value[:value]]
+                              else
+                                [path, value]
+                              end
 
           collection.select do |concept|
             actual = @resolver.resolve(concept, path)
-            if start_with
-              actual&.start_with?(match_value)
-            else
-              actual == value
-            end
+            start_with ? actual&.start_with?(match_value) : actual == value
           end
         end
 
-        def extract_start_with(path, value, start_with)
-          return [path, value] unless start_with
+        def field_filter_spec
+          path = (@filters.keys - COLLECTION_FILTERS).first
+          start_with = path.include?(".start_with(")
+          [path, @filters[path], start_with]
+        end
 
+        def extract_start_with_value(path, _value)
           match = path.match(/^([^.]+(?:\.[^.]+)*)\.start_with\(([^)]+)\)$/)
-          return [path, value] unless match
+          return nil unless match
 
-          [match[1], match[2]]
+          { path: match[1], value: match[2] }
         end
       end
     end

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

@@ -15,6 +15,7 @@ module Metanorma
         BLOCK_REGEX = /^\[glossarist,(.+?),(.+?)\]$/m
         BIBLIOGRAPHY_REGEX = /^glossarist::render_bibliography\[(.*?)\]$/m
         BIBLIOGRAPHY_ENTRY_REGEX = /^glossarist::render_bibliography_entry\[(.*?)\]$/m
+        NON_VERBAL_REGEX = /^glossarist::render_(figures|tables|formulas)\[(.*?)\]$/m
 
         BIB_ANCHOR_REGEX = /^\*\s*\[\[\[([^,]+)/
 
@@ -69,32 +70,47 @@ module Metanorma
         end
 
         def process_line(document, input_lines, current_line, liquid_doc)
-          if (match = current_line.match(DATASET_ATTR_REGEX))
-            process_dataset_tag(document, input_lines, liquid_doc, match)
-          elsif (match = current_line.match(RENDER_REGEX))
-            process_render_tag(liquid_doc, match)
-          elsif (match = current_line.match(IMPORT_SECTIONS_REGEX))
-            process_import_sections_tag(document, liquid_doc, match)
-          elsif (match = current_line.match(IMPORT_REGEX))
-            process_import_tag(liquid_doc, match)
-          elsif (match = current_line.match(BIBLIOGRAPHY_REGEX))
-            process_bibliography(document, liquid_doc, match)
-          elsif (match = current_line.match(BIBLIOGRAPHY_ENTRY_REGEX))
-            process_bibliography_entry(document, liquid_doc, match)
-          elsif (match = current_line.match(BLOCK_REGEX))
-            process_glossarist_block(document, liquid_doc, input_lines, match)
+          handler = directive_handler(current_line)
+          if handler
+            handler.call(document, input_lines, liquid_doc)
           else
-            if /^==+ \S/.match?(current_line)
-              @title_depth = current_line.sub(/ .*$/,
-                                              "").size
-            end
-            if (match = current_line.match(BIB_ANCHOR_REGEX))
-              @existing_bib_anchors << match[1]
-            end
-            liquid_doc.add_content(current_line)
+            handle_plain_line(current_line, liquid_doc)
+          end
+        end
+
+        # Returns a callable that handles the directive on +line+, or nil
+        # for plain content. Keeping the dispatch table small (regex →
+        # block) lets us add a new directive by appending one entry.
+        def directive_handler(line)
+          if (m = line.match(DATASET_ATTR_REGEX))
+            ->(doc, lines, ldoc) { process_dataset_tag(doc, lines, ldoc, m) }
+          elsif (m = line.match(RENDER_REGEX))
+            ->(_, _, ldoc) { process_render_tag(ldoc, m) }
+          elsif (m = line.match(IMPORT_SECTIONS_REGEX))
+            ->(doc, _, ldoc) { process_import_sections_tag(doc, ldoc, m) }
+          elsif (m = line.match(IMPORT_REGEX))
+            ->(_, _, ldoc) { process_import_tag(ldoc, m) }
+          elsif (m = line.match(BIBLIOGRAPHY_REGEX))
+            ->(doc, _, ldoc) { process_bibliography(doc, ldoc, m) }
+          elsif (m = line.match(BIBLIOGRAPHY_ENTRY_REGEX))
+            ->(doc, _, ldoc) { process_bibliography_entry(doc, ldoc, m) }
+          elsif (m = line.match(NON_VERBAL_REGEX))
+            ->(_, _, ldoc) { process_non_verbal(ldoc, m) }
+          elsif (m = line.match(BLOCK_REGEX))
+            ->(doc, lines, ldoc) { process_glossarist_block(doc, ldoc, lines, m) }
           end
         end
 
+        def handle_plain_line(current_line, liquid_doc)
+          if /^==+ \S/.match?(current_line)
+            @title_depth = current_line.sub(/ .*$/, "").size
+          end
+          if (match = current_line.match(BIB_ANCHOR_REGEX))
+            @existing_bib_anchors << match[1]
+          end
+          liquid_doc.add_content(current_line)
+        end
+
         def process_dataset_tag(document, input_lines, liquid_doc, match)
           @seen_glossarist = true
           @registry.register(document, match[1])
@@ -157,7 +173,8 @@ module Metanorma
           renderer = @renderer
           rendered = renderer.render_concept(concept,
                                              depth: @title_depth,
-                                             anchor_prefix: options["anchor-prefix"])
+                                             anchor_prefix: options["anchor-prefix"],
+                                             non_verbal: non_verbal_for(context_name))
           liquid_doc.add_content("\n#{rendered}")
         end
 
@@ -172,13 +189,15 @@ module Metanorma
           return unless dataset
 
           filter_options = options.except(*RENDER_OPTIONS)
-          concepts = ConceptFilter.new(filter_options).apply(dataset)
+          concepts = ConceptFilter.new(filter_options)
+            .apply(dataset, register: @registry.register_for(context_name))
           concepts = concepts.select(&:default_designation)
           @rendered_concepts.concat(concepts)
           renderer = @renderer
           rendered = renderer.render_concepts(concepts,
                                               depth: @title_depth,
-                                              anchor_prefix: options["anchor-prefix"])
+                                              anchor_prefix: options["anchor-prefix"],
+                                              non_verbal: non_verbal_for(context_name))
           liquid_doc.add_content("\n#{rendered}")
         end
 
@@ -188,39 +207,47 @@ module Metanorma
           context_name = matches[0]
           options = parse_options(matches[1..])
 
-          sections = @registry.register_sections(context_name)
+          register = @registry.register_for(context_name)
+          sections = register&.sections
           return unless sections && !sections.empty?
 
           dataset = @registry.resolve_dataset(nil, context_name)
           return unless dataset
 
-          renderer = @renderer
-          sort_by = options["sort_by"] || "term"
+          parts = render_sections(dataset, register, sections, context_name, options)
+          liquid_doc.add_content("\n#{parts.join("\n\n")}")
+        end
+
+        def render_sections(dataset, register, sections, context_name, options)
           section_filter = SectionFilter.new(
             exclude: (options["section_exclude"] || "").split("|"),
             include: (options["section_include"] || "").split("|"),
           )
           filtered = section_filter.apply(sections)
-          parts = render_section_concepts(filtered, dataset, renderer,
-                                          sort_by, options)
-          liquid_doc.add_content("\n#{parts.join("\n\n")}")
+          renderer = SectionRenderer.new(
+            dataset: dataset,
+            register: register,
+            renderer: @renderer,
+            depth: @title_depth,
+            sort_by: options["sort_by"] || SectionRenderer::DEFAULT_SORT_BY,
+            anchor_prefix: options["anchor-prefix"],
+            non_verbal: non_verbal_for(context_name),
+          )
+          renderer.render(filtered) do |concepts|
+            @rendered_concepts.concat(concepts)
+          end
         end
 
-        def render_section_concepts(sections, dataset, renderer, sort_by,
-                                    options)
-          sections.filter_map do |section|
-            filter_options = { "section" => section.id, "sort_by" => sort_by }
-            concepts = ConceptFilter.new(filter_options).apply(dataset)
-            concepts = concepts.select(&:default_designation)
-            next if concepts.empty?
+        # Builds a NonVerbalRenderer scoped to a dataset context, or
+        # returns nil if the dataset has no figures/tables/formulas. The
+        # resulting renderer is passed through to TemplateRenderer and
+        # SectionRenderer so concept-attached refs render as AsciiDoc
+        # blocks alongside the concept body.
+        def non_verbal_for(context_name)
+          collections = @registry.non_verbal_collections(context_name)
+          return nil if collections.empty?
 
-            @rendered_concepts.concat(concepts)
-            heading = "#{'=' * (@title_depth + 1)} #{section.name || section.id}"
-            rendered = renderer.render_concepts(concepts,
-                                                depth: @title_depth + 1,
-                                                anchor_prefix: options["anchor-prefix"])
-            "#{heading}\n\n#{rendered}"
-          end
+          NonVerbalRenderer.new(collections: collections)
         end
 
         def process_bibliography(document, liquid_doc, match)
@@ -237,7 +264,7 @@ module Metanorma
 
           renderer = BibliographyRenderer.new(
             existing_anchors: @existing_bib_anchors,
-            bibliography_data: @registry.bibliography_data,
+            bibliography: @registry.bibliography_for(dataset_name),
           )
           liquid_doc.add_content(renderer.render_all(concepts))
         end
@@ -250,12 +277,27 @@ module Metanorma
 
           renderer = BibliographyRenderer.new(
             existing_anchors: @existing_bib_anchors,
-            bibliography_data: @registry.bibliography_data,
+            bibliography: @registry.bibliography_for(dataset_name),
           )
           entry = renderer.render_entry(concept)
           liquid_doc.add_content(entry) if entry
         end
 
+        # Renders all dataset-level entities of a non-verbal kind
+        # (figures, tables, formulas) as AsciiDoc blocks. The directive
+        # shape is +glossarist::render_<kind>[dataset]+.
+        def process_non_verbal(liquid_doc, match)
+          @seen_glossarist = true
+          kind = :"#{match[1]}"
+          dataset_name = match[2].strip
+          collection = @registry.non_verbal_collection(dataset_name, kind)
+          return unless collection
+
+          renderer = NonVerbalRenderer.new(collections: { kind => collection })
+          rendered = renderer.render_kind(kind)
+          liquid_doc.add_content("\n#{rendered}") unless rendered.empty?
+        end
+
         def relative_file_path(document, file_path)
           return file_path if File.absolute_path?(file_path)
 

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

@@ -5,95 +5,160 @@ require "glossarist"
 module Metanorma
   module Plugin
     module Glossarist
+      # Resolves, caches, and exposes dataset models for a document.
+      #
+      # Single source of truth for everything the preprocessor needs from a
+      # glossarist dataset: concepts, section hierarchy, bibliography, and
+      # dataset-level non-verbal entities (figures, tables, formulas).
+      # Each is exposed as the typed Glossarist model object so callers
+      # never poke at raw YAML hashes.
       class DatasetRegistry
+        BIBLIOGRAPHY_FILENAME = "bibliography.yaml"
+        REGISTER_FILENAME = "register.yaml"
+
+        # Map of plural kind symbol → (collection class, subdirectory name).
+        # Adding a new non-verbal kind = adding one entry here. The accessor
+        # `{kind}_for` and loader are derived from this table.
+        NON_VERBAL_KINDS = {
+          figures: [::Glossarist::Collections::FigureCollection, "figures"],
+          tables: [::Glossarist::Collections::TableCollection, "tables"],
+          formulas: [::Glossarist::Collections::FormulaCollection, "formulas"],
+        }.freeze
+
         def initialize
-          @datasets = {}
-          @path_cache = {}
-          @bibliography_data = {}
-          @context_names = []
+          @stores = {}
+          @registers = {}
+          @bibliographies = {}
+          @non_verbal = {}
+          @context_paths = {}
         end
 
         def register(document, contexts)
-          paths = contexts.split(";").map do |context|
+          contexts.split(";").map do |context|
             context_name, file_path = context.split(":", 2).map(&:strip)
             path = relative_file_path(document, file_path)
-            @datasets[context_name] = load_dataset(path).to_a
+            @context_paths[context_name] = path
             "#{context_name}=#{path}"
           end
-          @context_names.concat(paths)
-        end
-
-        def load_cached(path)
-          @path_cache[path] ||= load_dataset(path)
         end
 
         def resolve_dataset(document, dataset_name)
-          dataset = @datasets[dataset_name]
-          return dataset if dataset
+          return concepts_for(dataset_name) if @context_paths.key?(dataset_name)
 
-          return unless document
+          path = relative_file_path(document, dataset_name) if document
+          return unless path
 
-          path = relative_file_path(document, dataset_name)
-          @datasets[dataset_name] = load_dataset(path).to_a
+          concepts_at(path)
         end
 
         def find_concept(dataset_name, concept_name, document = nil)
           dataset = resolve_dataset(document, dataset_name)
           return unless dataset
 
-          dataset.find do |concept|
-            concept.default_designation == concept_name
-          end
+          dataset.find { |concept| concept.default_designation == concept_name }
         end
 
         def context_path(key)
-          return nil if @context_names.empty?
+          @context_paths[key]
+        end
 
-          found = @context_names.find do |context|
-            context_name, = context.split("=")
-            context_name.strip == key
-          end
-          found&.split("=")&.last&.strip
+        # Returns the DatasetRegister for a registered context, or nil.
+        # The DatasetRegister is the single source of truth for section
+        # hierarchy and concept→section membership (cascading ancestors).
+        def register_for(context_name)
+          path = @context_paths[context_name]
+          return nil unless path
+
+          register_at(path)
         end
 
         def register_sections(context_name)
-          dataset_path = context_path(context_name)
-          return nil unless dataset_path
+          register_for(context_name)&.sections
+        end
+
+        # Returns the BibliographyData for a registered context, or nil.
+        # Exposed as the typed model so callers iterate entries via
+        # BibliographyEntry accessors (#id, #reference, #title, #link).
+        def bibliography_for(context_name)
+          path = @context_paths[context_name]
+          return nil unless path
 
-          @register_cache ||= {}
-          @register_cache[dataset_path] ||=
-            ::Glossarist::DatasetRegister.from_directory(dataset_path)
-          @register_cache[dataset_path]&.sections
+          bibliography_at(path)
         end
 
-        def bibliography_data
-          @bibliography_data
+        # Returns concepts cached at an absolute path. Used by Liquid
+        # blocks that receive a pre-resolved absolute path.
+        def concepts_at(path)
+          store_for(path).concepts
         end
 
-        private
+        # Returns the typed NonVerbalCollection for a registered context
+        # (e.g. FigureCollection), or nil if the dataset has no such
+        # subdirectory. +kind+ is one of the keys of NON_VERBAL_KINDS.
+        def non_verbal_collection(context_name, kind)
+          unless NON_VERBAL_KINDS.key?(kind)
+            raise ArgumentError, "unknown non-verbal kind: #{kind.inspect}"
+          end
+
+          path = @context_paths[context_name]
+          return nil unless path
+
+          collection_class, subdir = NON_VERBAL_KINDS.fetch(kind)
+          non_verbal_at(path, kind, subdir, collection_class)
+        end
 
-        def load_dataset(path)
-          @path_cache[path] ||= begin
-            collection = ::Glossarist::ManagedConceptCollection.new
-            collection.load_from_files(path)
-            load_bibliography_data(path)
-            collection
+        NON_VERBAL_KINDS.each_key do |kind|
+          define_method("#{kind}_for") do |context_name|
+            non_verbal_collection(context_name, kind)
           end
         end
 
-        def load_bibliography_data(dataset_path)
-          bib_path = File.join(dataset_path, "bibliography.yaml")
-          return unless File.exist?(bib_path)
+        # Returns all available non-verbal collections for a context as a
+        # hash keyed by kind symbol (e.g. +{ figures: FigureCollection }+).
+        # Kinds whose subdirectory doesn't exist are omitted. Convenient
+        # for building a NonVerbalRenderer in one call.
+        def non_verbal_collections(context_name)
+          NON_VERBAL_KINDS.each_with_object({}) do |(kind, _), memo|
+            collection = non_verbal_collection(context_name, kind)
+            memo[kind] = collection if collection
+          end
+        end
 
-          entries = YAML.safe_load_file(bib_path,
-                                        permitted_classes: [Symbol, Date])
-          return unless entries.is_a?(Array)
+        private
 
-          @bibliography_data = entries.each_with_object({}) do |entry, hash|
-            hash[entry["id"]] = entry if entry["id"]
+        def concepts_for(context_name)
+          path = @context_paths[context_name]
+          path ? concepts_at(path) : nil
+        end
+
+        def store_for(path)
+          @stores[path] ||= begin
+            store = ::Glossarist::GlossaryStore.new
+            store.load_directory(path)
+            store
           end
         end
 
+        def register_at(path)
+          @registers[path] ||=
+            ::Glossarist::DatasetRegister.from_directory(path)
+        end
+
+        def bibliography_at(path)
+          @bibliographies[path] ||= begin
+            file = File.join(path, BIBLIOGRAPHY_FILENAME)
+            ::Glossarist::BibliographyData.from_file(file)
+          end
+        end
+
+        def non_verbal_at(path, kind, subdir, collection_class)
+          dir = File.join(path, subdir)
+          return nil unless File.directory?(dir)
+
+          @non_verbal[path] ||= {}
+          @non_verbal[path][kind] ||= collection_class.from_directory(dir)
+        end
+
         def relative_file_path(document, file_path)
           return file_path if File.absolute_path?(file_path)
 

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.load_cached(path) : load_collection(path)
+              collection = registry ? registry.concepts_at(path) : load_collection(path)
               filtered = ConceptFilter.new(@raw_filters).apply(collection)
               context[local_context[:name]] = filtered.map do |c|
                 ManagedConceptDrop.new(c)

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/section_cascade.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Plugin
+    module Glossarist
+      # Resolves whether a concept is a member of a target section, including
+      # via cascading ancestor traversal (concept-model: gloss:hasChildSection
+      # is owl:TransitiveProperty — a concept in "3.1.1" is also in "3.1"
+      # and "3").
+      #
+      # Resolution order:
+      #   1. DatasetRegister#concept_section_ids(concept) when register is
+      #      available — the canonical V3 path with full cascading.
+      #   2. Direct ConceptReference domain match (ref_type: "section") —
+      #      legacy/fallback when no register is provided. Still applies
+      #      cascading by walking the register's section tree if available.
+      class SectionCascade
+        SECTION_REF_TYPE = "section"
+
+        def initialize(register = nil)
+          @register = register
+        end
+
+        # True if the concept belongs to target_id or any of target_id's
+        # descendant sections (cascading membership).
+        def member?(concept, target_id)
+          return false unless concept&.data
+
+          if @register
+            cascade_member?(concept, target_id)
+          else
+            local_member?(concept, target_id)
+          end
+        end
+
+        private
+
+        def cascade_member?(concept, target_id)
+          concept_ids = @register.concept_section_ids(concept)
+          return false if concept_ids.nil? || concept_ids.empty?
+
+          concept_ids.any?(target_id)
+        end
+
+        def local_member?(concept, target_id)
+          Array(concept.data.domains).any? do |domain|
+            domain.ref_type == SECTION_REF_TYPE &&
+              (domain.concept_id == target_id ||
+               descendant_of?(domain.concept_id, target_id))
+          end
+        end
+
+        def descendant_of?(child_id, ancestor_id)
+          return false unless @register
+
+          ancestors = @register.section_ancestor_ids(child_id)
+          ancestors.include?(ancestor_id)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Plugin
+    module Glossarist
+      # Renders concepts grouped by section, with cascading membership and
+      # configurable sort order.
+      #
+      # Extracted from DatasetPreprocessor to keep section rendering as a
+      # single MECE concern: it owns section → concepts resolution, heading
+      # depth, and per-section rendering. Callers retain ownership of the
+      # rendered-concept accumulator (passed via the block) so the
+      # preprocessor's global state stays in one place.
+      class SectionRenderer
+        DEFAULT_SORT_BY = "term"
+
+        # @param dataset [Enumerable<ManagedConcept>] the full dataset
+        # @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, :non_verbal
+        def initialize(dataset:, register:, renderer:, depth:, **options)
+          @dataset = dataset
+          @register = register
+          @renderer = renderer
+          @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>]
+        # @yield [Array<ManagedConcept>] concepts matched for each section
+        # @return [Array<String>] one rendered block per non-empty section
+        def render(sections)
+          sections.filter_map do |section|
+            concepts = concepts_for(section)
+            next if concepts.empty?
+
+            yield concepts if block_given?
+
+            block_for(section, concepts)
+          end
+        end
+
+        private
+
+        def concepts_for(section)
+          filter_options = { "section" => section.id, "sort_by" => @sort_by }
+          concepts = ConceptFilter.new(filter_options)
+            .apply(@dataset, register: @register)
+          concepts.select(&:default_designation)
+        end
+
+        def block_for(section, concepts)
+          heading = "#{'=' * (@depth + 1)} #{section.name || section.id}"
+          body = @renderer.render_concepts(concepts,
+                                           depth: @depth + 1,
+                                           anchor_prefix: @anchor_prefix,
+                                           non_verbal: @non_verbal)
+          "#{heading}\n\n#{body}"
+        end
+      end
+    end
+  end
+end

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

@@ -12,13 +12,17 @@ module Metanorma
           @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,
@@ -28,6 +32,9 @@ module Metanorma
           }
           template_content = cached_template(concept)
           rendered = render_template(template_content, context)
+          if non_verbal
+            rendered += "\n\n#{non_verbal.render_concept_refs(concept)}"
+          end
           normalize_whitespace(rendered)
         end
 
@@ -41,12 +48,14 @@ module Metanorma
           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.8"
+      VERSION = "0.3.10"
     end
   end
 end

data/lib/metanorma-plugin-glossarist.rb

@@ -21,8 +21,14 @@ module Metanorma
       autoload :Document, "metanorma/plugin/glossarist/document"
       autoload :Liquid, "metanorma/plugin/glossarist/liquid"
       autoload :LiquidRendering, "metanorma/plugin/glossarist/liquid_rendering"
+      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"
+      autoload :SectionRenderer, "metanorma/plugin/glossarist/section_renderer"
       autoload :TemplateRenderer,
                "metanorma/plugin/glossarist/template_renderer"
     end

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.7"
+  spec.add_dependency "glossarist", "~> 2.8", ">= 2.8.16"
   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.8
+  version: 0.3.10
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-15 00:00:00.000000000 Z
+date: 2026-06-20 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.7
+        version: 2.8.16
   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.7
+        version: 2.8.16
 - !ruby/object:Gem::Dependency
   name: liquid
   requirement: !ruby/object:Gem::Requirement
@@ -111,8 +111,16 @@ 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/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
+- lib/metanorma/plugin/glossarist/section_renderer.rb
 - lib/metanorma/plugin/glossarist/template_renderer.rb
 - lib/metanorma/plugin/glossarist/version.rb
 - metanorma-plugin-glossarist.gemspec