metanorma-core 0.2.2 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e0fe54371f36297eba65fd7cea8649359c7ca0f50195f388d48c82266bc220f
-  data.tar.gz: a18e98b49080a74314677f7aae1b382ae64083e4b9ce21c773959cc9e94439b2
+  metadata.gz: 68e4e30c0ecd25f66ab9f39d7132b23d05f3266a5afba3a6e67f91916329385c
+  data.tar.gz: 3d9d4072b81250ec95cb81d7630eeaaf1115338ba24469ee62a58d25bbfe8910
 SHA512:
-  metadata.gz: 6d0a9c5cc7e45bbdfd7c4eafda1028e66c8a904c7d7550d95248d966034215a3a2a2baee6a7bcf54b9aedab8ae984e11e4751f70f4bd9fbff8319bdca56f18f7
-  data.tar.gz: 4b0244d3496a619dccc2dd2ae4dbfb449b84a86949bd51d052c486a148ba2f321643cfd1fb00c857061ded783fb532c6734fbfe34282e11f3bbb5bdc8d62dd2d
+  metadata.gz: 002dd0efbf7c11b30d665b62f377fac848f3636448728ee01012062b332c5e33bec62523f2b6ff194f2c6651efcec93ec24ad33edfeeb11212be9e00fb1b3e90
+  data.tar.gz: e2ebc0042409579e2f17312a96b6f8c77a8247235d243500d4f888282738aaf83bda659dfa6a77ab93010fd4675ed1230c426cc50696070e8a1fba740c30f66d

data/README.adoc

@@ -11,3 +11,5 @@ image:https://img.shields.io/github/commits-since/metanorma/metanorma-core/lates
 
 This is a core repository for plugin dependencies of Metanorma, allowing metanorma-standoc and metanorma to share code without circular dependencies.
 
+
+<!-- canary: automerge stub verification, revert not needed -->

data/docs/implementing-sts-output-for-a-flavour.adoc

@@ -0,0 +1,405 @@
+= Implementing STS output for a Metanorma flavour
+:toc: macro
+:toclevels: 3
+
+toc::[]
+
+== Purpose and audience
+
+This is a developer guide for implementing https://www.niso.org/standards-committees/sts[NISO STS] /
+ISO STS output for a Metanorma flavour *from scratch*, using the metanorma-core
+_document-model output leg_.
+
+It is written for metanorma-core maintainers and flavour/taste contributors — the
+people who add a new semantic-XML-to-STS output format to a flavour. It is not an
+author guide: authors selecting STS output for an existing flavour need only the
+document attribute (e.g. `:output-extensions:`) documented on metanorma.org.
+
+The mechanism described here is the *Feature B* document-model convergence
+(metanorma-core#12): a flavour or taste declares two classes — a *reader* and a
+*transformer* — and metanorma-core drives the read/transform/serialise chain. No
+flavour re-implements the output plumbing, and metanorma-core never depends on the
+STS artefact gem.
+
+The worked examples are the two production adoptions:
+
+* *OIML* — STS contributed by the OIML *taste* over the ISO base flavour
+  (metanorma-oiml + metanorma-taste).
+* *ISO* — STS native to the *flavour* (metanorma-iso).
+
+== The big picture
+
+Metanorma builds a document in stages:
+
+[source]
+----
+input.adoc --> semantic XML --> (presentation XML) --> output (HTML/PDF/DOCX/STS/...)
+----
+
+Most rendered outputs (HTML, PDF, DOCX) are generated from *presentation XML* — the
+semantic XML enriched with rendering metadata. STS can be generated from *either*
+leg, depending on what your STS transformer consumes. metanorma-core's default treats
+STS as a *semantic*-leg format, and ISO's native `isosts` does exactly that; but a
+flavour or taste whose STS transformer needs the rendered presentation XML can opt
+into the *presentation* leg, as the OIML taste's `oimlsts` does. You declare the leg
+(see <<step-3-make-the-format-selectable>>).
+
+The document-model output leg turns that "semantic XML -> STS XML" step into a
+declarative contract. A flavour declares, per output format:
+
+* a *reader* that parses the input XML string into a document model, and
+* a *transformer* that maps that model to the STS model and serialises it.
+
+metanorma-core's `Processor#output` recognises the format and runs the chain
+(`Processor#render_via_document_model`), so the flavour ships two classes instead of
+bespoke output code.
+
+== The contract
+
+The contract is `Metanorma::Processor#document_transformers`
+(`metanorma-core/lib/metanorma/processor/processor.rb`). It returns a hash mapping an
+output-format symbol to a spec:
+
+[source,ruby]
+----
+def document_transformers
+  {
+    myflavoursts: {
+      reader: MyFlavour::Sts::SourceDocument,     # required
+      transformer: MyFlavour::Sts::Standard,      # required
+      to_xml_options: {},                         # default {}
+      strip_default_namespace: false,             # default false
+      post_process: nil,                          # default identity
+    },
+  }
+end
+----
+
+Spec keys (metanorma-core contract):
+
+`:reader`:: (required) responds to `.from_xml(String) -> model`. Parses the input
+XML into a document model.
+
+`:transformer`:: (required) responds to `.new(model, options)`; the instance responds
+to `#transform -> target`, and the target responds to `#to_xml`. See
+<<the-adapter-pattern>>.
+
+`:to_xml_options`:: hash splatted into `target.to_xml(**opts)` (default `{}`).
+
+`:strip_default_namespace`:: strip `xmlns="..."` from the input XML before
+`from_xml` (default `false`). Set `true` when your reader's model does not expect the
+Metanorma default namespace on the root.
+
+`:post_process`:: a callable `(xml, transformer, options) -> xml` run on the
+serialised string (default identity). Use it for namespace / processing-metadata /
+language fix-ups that must happen on the serialised output.
+
+Two further keys are read by the *metanorma compile driver* (not by metanorma-core)
+to make the format selectable; see <<step-3-make-the-format-selectable>>:
+
+`:suffix`:: the output filename suffix, e.g. `"oiml.sts.xml"`.
+
+`:presentation`:: `true` if the format is generated from *presentation* XML;
+omit/`false` for the *semantic* leg. Per-transformer choice: OIML's `oimlsts` sets
+`true`, ISO's native `isosts` uses the semantic leg.
+
+=== How metanorma-core drives it
+
+`Processor#output` routes any registered format through the document-model leg:
+
+[source,ruby]
+----
+def output(isodoc_node, inname, outname, format, options = {})
+  options_preprocess(options)
+  transformers = effective_document_transformers(options)
+  if transformers.key?(format)
+    render_via_document_model(isodoc_node, inname, outname, format,
+                              options, transformers.fetch(format))
+  else
+    File.open(outname, "w:UTF-8") { |f| f.write(isodoc_node) }
+  end
+end
+----
+
+`render_via_document_model` is the whole chain, duck-typed — it never names a
+concrete reader/transformer/model gem, so those stay out of metanorma-core's
+dependencies:
+
+[source,ruby]
+----
+xml = document_model_input_xml(isodoc_node, inname)       # semantic or presentation leg
+xml = xml.gsub(/\sxmlns="[^"]*"/, "") if spec[:strip_default_namespace]
+transformer = spec.fetch(:transformer)
+  .new(spec.fetch(:reader).from_xml(xml), options)
+out = transformer.transform.to_xml(**(spec[:to_xml_options] || {}))
+out = spec[:post_process].call(out, transformer, options) if spec[:post_process]
+----
+
+The input XML comes from `isodoc_node` (the semantic leg) or, when that is nil, from
+reading `inname` (the presentation leg). Which leg fires is governed by
+`use_presentation_xml`. The metanorma-core default treats STS and RFC as semantic-leg
+formats:
+
+[source,ruby]
+----
+def use_presentation_xml(ext)     # metanorma-core default
+  case ext
+  when :html, :doc, :pdf then true
+  else false   # STS, RFC, ... default to the semantic leg
+  end
+end
+----
+
+A flavour overrides this per format. ISO keeps `isosts` on the semantic leg when its
+native STS is enabled (and falls back to the presentation leg for the legacy path):
+
+[source,ruby]
+----
+def use_presentation_xml(ext)     # metanorma-iso
+  return false if ext == :isosts && Metanorma::Iso::Sts.enabled?  # native STS: semantic
+  return true if %i[html_alt sts isosts].include?(ext)            # legacy path: presentation
+  super
+end
+----
+
+A *taste* declares the leg instead through the `:presentation` key of its spec (Route
+B); OIML sets `presentation: true`, putting `oimlsts` on the presentation leg. Pick
+the leg your transformer actually consumes.
+
+[#the-adapter-pattern]
+== Step 1 — Build the STS transformer (in the artefact gem)
+
+The reader and transformer live in the flavour's *artefact gem* (e.g.
+metanorma-oiml), never in metanorma-core.
+
+=== The reader
+
+The reader responds to `.from_xml(String) -> model`. In practice this is a thin
+entry point on your source-document model:
+
+[source,ruby]
+----
+module Metanorma::Oiml::Sts::Transformer
+  class SourceDocument
+    def self.from_xml(input)
+      parse(input)   # -> a SourceDocument model instance
+    end
+  end
+end
+----
+
+=== The transformer (adapter)
+
+The transformer must satisfy: `.new(model, options)`, `#transform -> target`, and
+`target#to_xml`. The cleanest way to meet this while reusing an existing conversion
+pipeline is the *adapter-is-its-own-target* pattern from metanorma-oiml
+(`lib/metanorma/oiml/sts/transformer/standard.rb`):
+
+[source,ruby]
+----
+class Standard
+  def initialize(model, options = {})
+    @model = model
+    @options = options
+  end
+
+  def transform
+    @document_transformer = DocumentTransformer.new(Context.new(@model))
+    self                      # the adapter is its own #to_xml target
+  end
+
+  def to_xml(**_options)
+    @document_transformer.transform_to_xml(@model)   # full existing pipeline
+  end
+end
+----
+
+`#to_xml` runs the *full* existing conversion pipeline (model build plus the
+namespace / processing-metadata / language post-processing on the serialised
+string), so the driven output is byte-identical to the gem's standalone converter
+(`Metanorma::Oiml::Sts::Transformer.convert`). Returning the raw `#transform` model
+instead would drop that post-processing — a common trap.
+
+TIP: If your gem already has a standalone `convert` (or an `oiml-sts`-style CLI),
+make the adapter's output byte-equal to it and add a byte-equivalence test. That is
+your safety net that the unified path did not change behaviour.
+
+== Step 2 — Register the format
+
+There are two registration routes. Choose by *what owns the flavour*.
+
+=== Route A — flavour-native (the flavour has its own Processor)
+
+If STS belongs to the flavour itself (ISO), override `document_transformers` on the
+flavour's `Metanorma::Processor` subclass:
+
+[source,ruby]
+----
+module Metanorma::Iso
+  class Processor < Metanorma::Processor
+    def document_transformers
+      {
+        isosts: {
+          reader: Metanorma::Iso::Sts::SourceDocument,
+          transformer: Metanorma::Iso::Sts::Standard,
+        },
+      }
+    end
+  end
+end
+----
+
+This is zero-arg and static: the flavour always offers the format.
+
+=== Route B — taste-contributed (a taste over a base flavour)
+
+If STS belongs to a *taste* over a base flavour (OIML is a taste over ISO), the taste
+contributes the spec through the per-taste hook in metanorma-taste, *without*
+metanorma-taste depending on the artefact gem.
+
+Declare a `data/<taste>/transformers.rb` shim in the taste gem
+(metanorma-taste/data/oiml/transformers.rb):
+
+[source,ruby]
+----
+Metanorma::TasteRegister.register_document_transformers(:oiml) do
+  require "metanorma/oiml/sts"          # loaded lazily — only for OIML builds
+
+  {
+    oimlsts: {
+      reader: Metanorma::Oiml::Sts::Transformer::SourceDocument,
+      transformer: Metanorma::Oiml::Sts::Transformer::Standard,
+      strip_default_namespace: false,
+      to_xml_options: {},
+      suffix: "oiml.sts.xml",           # compile-driver keys (Step 3)
+      presentation: true,
+    },
+  }
+end
+----
+
+How the hook works (`metanorma-taste/lib/metanorma/taste_register.rb`):
+
+* `register_document_transformers(taste, &block)` stores the block, keyed by taste.
+* `document_transformers_for(taste)` is memoised: on first use it requires the taste's
+  `data/<taste>/transformers.rb` shim (`load_transformer_hook`), then calls the block.
+* Because the `require "metanorma/oiml/sts"` sits *inside* the block, the artefact gem
+  loads only for builds that use the taste. metanorma-taste keeps no hard dependency
+  on it. If the shim declares transformers but the artefact gem is not in the bundle,
+  the hook raises `UnknownTasteError` telling the user to add it.
+
+The taste-aware `Processor#effective_document_transformers` then merges the taste's
+specs onto the flavour's `document_transformers`, keyed by `options[:supplied_type]`
+(the active taste). Base flavours and tastes without the hook are unaffected:
+
+[source,ruby]
+----
+def effective_document_transformers(options = {})
+  base = document_transformers
+  taste = options[:supplied_type]
+  unless taste && defined?(Metanorma::TasteRegister) &&
+      Metanorma::TasteRegister.respond_to?(:document_transformers_for)
+    return base
+  end
+  base.merge(Metanorma::TasteRegister.document_transformers_for(taste) || {})
+end
+----
+
+NOTE: `supplied_type` is the seam that carries taste identity to the shared, stateless
+processor. No per-build state is kept on the processor instance.
+
+[#step-3-make-the-format-selectable]
+== Step 3 — Make the format selectable in the compile driver
+
+For a user to request the format (e.g. `:output-extensions: oimlsts`), the metanorma
+compile driver must know its suffix and which leg it uses. This is threaded via
+`supplied_type` (`metanorma/lib/metanorma/compile/compile_options.rb`):
+
+* `supplied_type` originates from `options[:type]` and is copied into the isodoc
+  options (`copy_isodoc_options_attrs`: `ret[:supplied_type] = options[:supplied_type]`),
+  so the taste-aware processor sees it.
+* `effective_output_formats` merges the processor's `output_formats` with the
+  `:suffix` of each taste-contributed format, so the format passes extension
+  validation and gets an output filename:
++
+[source,ruby]
+----
+def effective_output_formats(options)
+  @processor.output_formats.merge(
+    taste_transformers(options).transform_values { |s| s[:suffix] }.compact,
+  )
+end
+----
+* `uses_presentation_xml?` honours both the processor's answer and the taste spec's
+  `:presentation` flag:
++
+[source,ruby]
+----
+def uses_presentation_xml?(ext, options)
+  @processor.use_presentation_xml(ext) ||
+    (taste_transformers(options)[ext] || {})[:presentation] == true
+end
+----
+
+For a *flavour-native* format (Route A), the compile driver reads the same keys off
+the flavour's own `document_transformers`; set `:suffix` there too if the format is
+user-selectable, and override `use_presentation_xml` to pick the leg (ISO's `isosts`
+returns `false` for the semantic leg).
+
+== Step 4 — Deprecate the standalone converter (optional)
+
+If the artefact gem had a standalone STS converter or CLI (e.g. `oiml-sts convert`),
+deprecate it in favour of the unified path once the driver is in place. Keep the code
+(the adapter delegates to it) but emit a deprecation notice from the old CLI entry
+points, and document the metanorma-driven path as canonical. metanorma-oiml#24 is the
+reference.
+
+== Conforming to the official STS specifications
+
+The transformer must emit *conformant* STS. Source the normative models from:
+
+* *NISO STS* — ANSI/NISO Z39.102, the NISO Standards Tag Suite.
+* *ISO STS* — the ISO profile/extension of NISO STS.
+
+Model the transformer's output against these tag sets (element/attribute names,
+allowed content models, metadata blocks). Validate generated output against the STS
+DTD/schema as part of your test suite; do not rely on visual inspection of the PDF/
+HTML, which can look correct while the STS XML is non-conformant.
+
+== Testing (smoke tests)
+
+At minimum:
+
+. *Build test* — compile a small document requesting the new format and assert the
+  output file is produced with the expected suffix and a well-formed STS root.
+. *Byte-equivalence test* — assert the driven output equals the standalone converter's
+  output (guards the adapter, per <<the-adapter-pattern>>).
+. *Registration test* — for a taste, assert `document_transformers_for(:yourtaste)`
+  returns the spec and that `effective_document_transformers` merges it under
+  `supplied_type`.
+. *Schema validation* — validate the generated STS against the NISO/ISO STS schema.
+
+The OIML and ISO STS specs in metanorma-oiml / metanorma-iso are the templates.
+
+== Checklist
+
+[cols="1,3"]
+|===
+| Artefact gem | `reader` (`.from_xml`) + `transformer` (`Standard` adapter, byte-equal to standalone `convert`)
+| Registration | Route A: override `document_transformers` on the flavour Processor. Route B: `data/<taste>/transformers.rb` shim with a lazy `require`
+| Selectable | `:suffix` (+ `:presentation` only if presentation-leg) so the compile driver exposes it
+| Leg | Declare it per what your transformer consumes: semantic (`use_presentation_xml` `false`, e.g. ISO `isosts`) or presentation (`presentation: true`, e.g. OIML `oimlsts`)
+| Deprecate | old standalone converter/CLI emits a deprecation notice
+| Conformance | output validated against NISO/ISO STS schema
+| Tests | build + byte-equivalence + registration + schema
+|===
+
+== Reference
+
+* metanorma-core#12 — Feature B document-model convergence (design: Decision + Alignment)
+* metanorma-core#13 — taste-aware `Processor#effective_document_transformers`
+* metanorma/metanorma#589 — compile-driver output selection (`supplied_type`, `effective_output_formats`, `uses_presentation_xml?`)
+* metanorma/metanorma-iso#1610 — mature STS-ISO transformer adoption (flavour-native, Route A)
+* metanorma/metanorma-oiml#24 — STS core-driver adapter + `oiml-sts` CLI deprecation (Route B artefact)
+* metanorma/metanorma-taste#188 — per-taste hook + OIML `:oimlsts` registration
+* NISO STS (ANSI/NISO Z39.102) and ISO STS official specifications

data/lib/metanorma/core/flavor.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Core
+    # One entry in the flavor/taste table — the single source of truth
+    # for flavor identity across the ecosystem.
+    #
+    # A FLAVOR entry (base_flavor nil): a document model family — model
+    # root, processor, per-format renderers, pubid module, gem name.
+    # A TASTE entry (base_flavor set): a config-only variant of a flavor
+    # — no model of its own; it carries the publisher discriminator,
+    # branding directory, and doctype map, and inherits everything else
+    # through its base chain.
+    #
+    # renderers values: a renderer class, or a Proc resolver taking
+    # (document, **options) and returning a class — flavor-owned variant
+    # selection (publisher/profile/doctype). Returning nil falls through
+    # to the next matching entry.
+    class Flavor
+      attr_reader :name, :base_flavor, :gem, :model_root, :processor,
+                  :renderers, :pubid_module, :branding_dir,
+                  :publisher_abbr, :doctype_map, :semantic_input
+
+      def initialize(name:, base_flavor: nil, gem: nil, model_root: nil,
+                     processor: nil, renderers: {}, pubid_module: nil,
+                     branding_dir: nil, publisher_abbr: nil, doctype_map: {},
+                     semantic_input: false)
+        @name = name&.to_sym
+        @base_flavor = base_flavor&.to_sym
+        @gem = gem || "metanorma-#{name}"
+        @model_root = model_root
+        @processor = processor
+        @renderers = renderers
+        @pubid_module = pubid_module
+        @branding_dir = branding_dir
+        @publisher_abbr = publisher_abbr
+        @doctype_map = doctype_map
+        @semantic_input = semantic_input
+      end
+
+      def taste? = !!base_flavor
+
+      def renderer_for(format, document, **options)
+        entry = renderers[format]
+        return nil unless entry
+
+        entry.is_a?(Proc) ? entry.call(document, **options) : entry
+      end
+
+      def matches?(document_class)
+        return false unless document_class.is_a?(Class)
+
+        root = model_root_class
+        return false unless root
+
+        !!(document_class <= root)
+      end
+
+      def model_root_class
+        return @model_root_class if @model_root_class
+
+        # Never cache a miss: the flavor gem may load after the first
+        # lookup (lazy string roots resolve once the owning gem is
+        # required), and a cached nil would poison every later walk.
+        klass = if model_root.is_a?(Class)
+                  model_root
+                elsif model_root && Object.const_defined?(model_root)
+                  Object.const_get(model_root)
+                end
+        @model_root_class = klass
+        klass
+      end
+
+      def pubid_module_const
+        return nil unless pubid_module
+
+        begin
+          require "pubid"
+        rescue LoadError
+          return nil
+        end
+        Object.const_get(pubid_module.to_s)
+      rescue NameError
+        raise ArgumentError,
+              "Flavor #{name.inspect}: pubid module #{pubid_module} could "               "not be resolved — fix the flavor's registration"
+      end
+    end
+  end
+end

data/lib/metanorma/core/flavor_loader.rb

@@ -27,6 +27,12 @@ module Metanorma
       #   taste alias matched).
       def taste2flavor(stdtype)
         stdtype = stdtype.to_sym
+        entry = Flavors.find(stdtype)
+        return entry.base_flavor if entry&.taste?
+
+        # Transitional: taste entries land in the table with
+        # metanorma-taste's restructure PR; until then fall back to
+        # TasteRegister.aliases. Removed in this branch's final commit.
         tastes = Metanorma::TasteRegister.instance.aliases
         tastes[stdtype] and stdtype = tastes[stdtype].to_sym
         stdtype

data/lib/metanorma/core/flavor_registry.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Core
+    # The process-wide flavor/taste table. Registered most-specific-last;
+    # resolution walks most-specific-first so flavor gems (loaded after
+    # the harness defaults) win, and taste entries fall through to their
+    # base chain by yielding nil.
+    class FlavorRegistry
+      include Enumerable
+
+      def initialize
+        @flavors = []
+      end
+
+      def register(flavor)
+        @flavors << flavor
+        self
+      end
+
+      def each(&) = @flavors.each(&)
+
+      def find_by_name(name)
+        @flavors.reverse_each.find { |f| f.name == name.to_sym }
+      end
+
+      def flavor_for(document)
+        @flavors.reverse_each.find { |f| f.matches?(document.class) }
+      end
+
+      # Renderer class for (document, format): walk matching entries
+      # most-specific-first; a taste without its own renderer for the
+      # format yields nil and falls through to the base flavor entry.
+      def renderer_for(format, document, **options)
+        @flavors.reverse_each.each do |flavor|
+          next unless flavor.matches?(document.class)
+
+          renderer = flavor.renderer_for(format, document, **options)
+          return renderer if renderer
+        end
+        nil
+      end
+
+      # Canonical FLAVOR entry for a stdtype/taste name: follows the
+      # base_flavor chain so compile loads the base flavor's gem and
+      # processor while the taste supplies config.
+      def canonical(name)
+        entry = find_by_name(name)
+        return nil unless entry
+
+        entry = find_by_name(entry.base_flavor) while entry&.base_flavor
+        entry
+      end
+    end
+  end
+end

data/lib/metanorma/core/flavors.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Core
+    # The composition-layer API over the flavor/taste table. Replaces
+    # the former scattered mechanisms: Registry-only processor dispatch,
+    # FlavorLoader.taste2flavor, CLI hand-merged dictionaries, and the
+    # renderer registries the harness once carried.
+    module Flavors
+      class << self
+        def table
+          @table ||= FlavorRegistry.new
+        end
+
+        def register(flavor)
+          table.register(flavor)
+        end
+
+        # Compile-time: canonical flavor entry for a stdtype name
+        # (taste chains resolved), loading its gem if needed.
+        def resolve(type)
+          canonical = table.canonical(type)
+          return nil unless canonical
+
+          unless backends.include?(canonical.name)
+            require canonical.gem
+          end
+          canonical
+        end
+
+        # Render-time: renderer class for (document, format).
+        def renderer_for(document, format:, **options)
+          table.renderer_for(format, document, **options)
+        end
+
+        def flavor_for(document)
+          table.flavor_for(document)
+        end
+
+        def find(name)
+          table.find_by_name(name)
+        end
+
+        # Tastes of a given base flavor (for dictionaries/projections).
+        def tastes_of(base)
+          table.select { |f| f.taste? && f.base_flavor == base.to_sym }
+        end
+
+        def available_tastes
+          table.select(&:taste?).map(&:name)
+        end
+
+        private
+
+        def backends
+          Metanorma::Registry.instance.supported_backends
+        rescue NameError
+          []
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/core/version.rb

@@ -1,5 +1,5 @@
 module Metanorma
   module Core
-    VERSION = "0.2.2".freeze
+    VERSION = "0.2.4".freeze
   end
 end

data/lib/metanorma/processor/processor.rb

@@ -70,6 +70,29 @@ module Metanorma
       {}
     end
 
+    # The flavor's own {#document_transformers}, merged with the document-model
+    # specs contributed by the active taste (+options[:supplied_type]+). Those
+    # specs come from +Metanorma::TasteRegister+ when it supports the per-taste
+    # hook; base flavors (no taste), and installed tastes without the hook, are
+    # unaffected -- the base map is returned unchanged. {#document_transformers}
+    # stays zero-arg (flavors override it) and the taste specs are merged on
+    # top. No per-build state is kept on the shared processor instance: the
+    # taste identity rides entirely on +options[:supplied_type]+.
+    #
+    # @param options [Hash] processor options; reads +:supplied_type+.
+    # @return [Hash{Symbol => Hash}] merged format symbol -> spec.
+    def effective_document_transformers(options = {})
+      base = document_transformers
+      taste = options[:supplied_type]
+      unless taste && defined?(Metanorma::TasteRegister) &&
+          Metanorma::TasteRegister.respond_to?(:document_transformers_for)
+        return base
+      end
+
+      contributed = Metanorma::TasteRegister.document_transformers_for(taste)
+      base.merge(contributed || {})
+    end
+
     # Convert an input file to Metanorma semantic XML by routing it
     # through the {Metanorma::Input::Asciidoc} processor with this
     # processor's Asciidoctor backend. Override for non-Asciidoc
@@ -131,9 +154,10 @@ module Metanorma
     #   string (document-model leg).
     def output(isodoc_node, inname, outname, format, options = {})
       options_preprocess(options)
-      if document_transformers.key?(format)
+      transformers = effective_document_transformers(options)
+      if transformers.key?(format)
         render_via_document_model(isodoc_node, inname, outname, format,
-                                  options)
+                                  options, transformers.fetch(format))
       else
         File.open(outname, "w:UTF-8") { |f| f.write(isodoc_node) }
       end
@@ -155,9 +179,13 @@ module Metanorma
     #   {#document_transformers}.
     # @param options [Hash] processor options, passed to the transformer and
     #   post-processor.
+    # @param spec [Hash, nil] pre-resolved transformer spec; when nil it is
+    #   resolved from {#effective_document_transformers} (so callers that pass
+    #   the old five-argument signature still work).
     # @return [String] the serialised (and post-processed) output XML.
-    def render_via_document_model(isodoc_node, inname, outname, format, options)
-      spec = document_transformers.fetch(format)
+    def render_via_document_model(isodoc_node, inname, outname, format, options,
+                                  spec = nil)
+      spec ||= effective_document_transformers(options).fetch(format)
       xml = document_model_input_xml(isodoc_node, inname)
       xml = xml.gsub(/\sxmlns="[^"]*"/, "") if spec[:strip_default_namespace]
       transformer = spec.fetch(:transformer)

data/lib/metanorma-core.rb

@@ -8,6 +8,9 @@ require "metanorma/input"
 require "metanorma/processor/processor"
 require "metanorma/registry/registry"
 require "metanorma/asciidoctor_extensions"
+require "metanorma/core/flavor"
+require "metanorma/core/flavor_registry"
+require "metanorma/core/flavors"
 require "metanorma/core/flavor_loader"
 require "metanorma/core/isodoc"
 require "metanorma/core/boilerplate"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: metanorma-core
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.4
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-21 00:00:00.000000000 Z
+date: 2026-09-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asciidoctor
@@ -164,12 +164,16 @@ files:
 - Gemfile
 - LICENSE
 - README.adoc
+- docs/implementing-sts-output-for-a-flavour.adoc
 - lib/metanorma-core.rb
 - lib/metanorma/asciidoctor_extensions.rb
 - lib/metanorma/asciidoctor_extensions/glob_include_processor.rb
 - lib/metanorma/config/config.rb
 - lib/metanorma/core/boilerplate.rb
+- lib/metanorma/core/flavor.rb
 - lib/metanorma/core/flavor_loader.rb
+- lib/metanorma/core/flavor_registry.rb
+- lib/metanorma/core/flavors.rb
 - lib/metanorma/core/isodoc.rb
 - lib/metanorma/core/version.rb
 - lib/metanorma/input.rb