metanorma-core 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 314a93ed63df1389dfb3e950e63d7ebff4ccf3c1a0e1698d678ddb898ab9fc47
-  data.tar.gz: 4ef731b709d7f26820209291edea8d576992d457f0161dae1cc3d4c810433f5f
+  metadata.gz: 41c7086b0f760b06a87c99ce115f66d31c1a8e30a6f43a182e1ed81a076b0ee6
+  data.tar.gz: a55d956d5122b77c0078b9d48adb4c4c3b6c97b1c7638498a8a9d31d342b799b
 SHA512:
-  metadata.gz: 03ed6bb9d50427ca61a7659458c8e154329566a968e3cf80f9bf4a9e46c859358bbab811ab1d76481f13797525f6651e80fb2d565eeb0408f41979ae10658c1b
-  data.tar.gz: 5e69aa811a9385a9938e0707a37334c51929e880633b707fe32590c599787ebe2bd8c5fc6d96e08d948da149079d7bbf52a119441ca27e3d504279286c76ca10
+  metadata.gz: c37685805cfcff21fe4bb18e2a17661242c36a7605aa257736875c5735870e875fcfeb399f3769c25cd8ec4515a68561f8bcc8a503b970c805fe04251e2c2f6f
+  data.tar.gz: 4ce50e2bba70f304654640489d89a8d3e9fe45b2e42c3b34f634985b8d79db23bdb5f9e2f2da15bda5fdd6da9b0089b344657e9cbc131ce26d80a0011662ac82

data/.rubocop.yml

@@ -1,8 +1,31 @@
+# Auto-generated by Cimas: Do not edit it manually!
+# See https://github.com/metanorma/cimas
 inherit_from:
   - https://raw.githubusercontent.com/riboseinc/oss-guides/main/ci/rubocop.yml
+  # .rubocop_todo.yml MUST be the last entry. inherit_from is last-wins:
+  # if listed before oss-guides, the shared config's stricter Metrics/
+  # (MethodLength, BlockLength, etc.) rules override the todo's per-file
+  # grandfathering, and the todo becomes inert on those cops. Empirically
+  # verified on suma 2026-07-06: with todo listed first, 34 Metrics/* offenses
+  # remained; moved last, cleared. Every gem in the metanorma-org fleet
+  # already ships a `.rubocop_todo.yml` on its live tree (audited 2026-07-06,
+  # 54/54 have it), so this reference is safe to emit unconditionally.
+  - .rubocop_todo.yml
+
+# Rubocop plugins enabled centrally so every metanorma-org gem picks them up
+# on cimas sync — best practice belongs at the shared-template layer, not
+# per-repo. Per ronaldtse feedback on metanorma/ci#332.
+plugins:
+  - rubocop-rspec
+  - rubocop-performance
+  - rubocop-rake
 
 # local repo-specific modifications
 # ...
 
 AllCops:
-  TargetRubyVersion: 3.4
+  # 3.3 matches the org-wide minimum being pushed via #274 (Raise minimum
+  # Ruby version to 3.3 due to EOL of 3.2 on 2026-03-31). Was 3.4 before
+  # this commit — 3.4 was above the org's stated minimum and would have
+  # applied Rubocop rules that fail-close on gems still targeting 3.3.
+  TargetRubyVersion: 3.3

data/Gemfile

@@ -7,5 +7,8 @@ git_source(:github) { |repo| "https://github.com/#{repo}" }
 gemspec
 
 gem "gem-release"
+# top-level, not the gemspec development group: the release job installs
+# without development/test, and bundle exec rake release needs rake
+gem "rake"
 
 eval_gemfile("Gemfile.devel") rescue nil

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

@@ -1,5 +1,5 @@
 module Metanorma
   module Core
-    VERSION = "0.2.1".freeze
+    VERSION = "0.2.3".freeze
   end
 end

data/lib/metanorma/input/asciidoc.rb

@@ -115,7 +115,7 @@ module Metanorma
       # attribute is bare (no value).
       EMPTY_ADOC_OPTIONS_DEFAULT_FALSE =
         %w(hierarchical-assets break-up-urls-in-tables toc-figures
-           toc-tables toc-recommendations).freeze
+           toc-tables toc-recommendations toc-examples).freeze
 
       # Convert an Asciidoc-style attribute name (kebab-case, possibly
       # ending in +-override+ or +-pdf+) into the Ruby symbol used in

data/lib/metanorma/processor/processor.rb

@@ -43,6 +43,56 @@ module Metanorma
       }
     end
 
+    # Per-format "document model" publishing specs. Override in a flavor to
+    # register injected reader + transformer classes for a document-model
+    # output leg (Presentation/Semantic XML -> reader -> transformer -> XML),
+    # so the flavor declares two classes rather than re-implementing the
+    # read/transform/serialise chain in {#output}. The classes need not live
+    # in the +Metanorma::+ tree.
+    #
+    # Each value is a Hash with keys:
+    #   :reader                  - responds to +.from_xml(String)+ -> model
+    #                              (required)
+    #   :transformer             - responds to +.new(model, options)+; the
+    #                              instance responds to +#transform+ -> target,
+    #                              and the target responds to +#to_xml+
+    #                              (required)
+    #   :to_xml_options          - Hash splatted into +target.to_xml(**opts)+
+    #                              (default +{}+)
+    #   :strip_default_namespace - strip +xmlns="..."+ before +from_xml+
+    #                              (default +false+)
+    #   :post_process            - callable +(xml, transformer, options)+
+    #                              -> xml (default identity)
+    #
+    # @return [Hash{Symbol => Hash}] format symbol -> spec. Empty by default,
+    #   so flavors that do not use this leg are unaffected.
+    def document_transformers
+      {}
+    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
@@ -87,19 +137,80 @@ module Metanorma
       options[:output_formats] ||= output_formats
     end
 
-    # Default output-writer: dump the rendered output string to a
-    # UTF-8 file. Override for binary formats (Word, PDF) that need
-    # different post-processing.
+    # Default output-writer. If +format+ is registered in
+    # {#document_transformers}, render it through the document-model leg
+    # ({#render_via_document_model}); otherwise dump the rendered output
+    # string to a UTF-8 file. Flavors override this for binary formats
+    # (Word, PDF) that need different post-processing, calling +super+ for
+    # the document-model and passthrough cases.
     #
-    # @param isodoc_node [String] rendered output content.
-    # @param _inname [String] source filename (unused at this base level).
+    # @param isodoc_node [String, nil] rendered output content, or the
+    #   semantic XML string on the document-model semantic leg.
+    # @param inname [String] source filename.
     # @param outname [String] destination path.
-    # @param _format [Symbol] output format (unused at this base level).
-    # @param _options [Hash] processor options (unused at this base level).
-    # @return [Integer] bytes written (Ruby's +File#write+ return).
-    def output(isodoc_node, _inname, outname, _format, _options = {})
-      File.open(outname, "w:UTF-8") { |f| f.write(isodoc_node) }
+    # @param format [Symbol] output format.
+    # @param options [Hash] processor options.
+    # @return [Object] bytes written (passthrough) or the serialised XML
+    #   string (document-model leg).
+    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 a document-model output leg: read the input XML into a model via
+    # the registered reader, transform it, serialise, optionally post-process,
+    # and write. The input XML comes from +isodoc_node+ (semantic leg) or,
+    # when that is nil, from reading +inname+ (presentation leg) — so both
+    # {#use_presentation_xml} settings are supported transparently. The driver
+    # is duck-typed: it never names a concrete reader/transformer/target-model
+    # gem, keeping those out of metanorma-core's dependencies.
+    #
+    # @param isodoc_node [String, nil] semantic XML string, or nil on the
+    #   presentation leg.
+    # @param inname [String] input filename (read on the presentation leg).
+    # @param outname [String, nil] destination path; written when non-nil.
+    # @param format [Symbol] output-format symbol; must be a key of
+    #   {#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 = 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)
+        .new(spec.fetch(:reader).from_xml(xml), options)
+      out = transformer.transform.to_xml(**(spec[:to_xml_options] || {}))
+      if (post = spec[:post_process])
+        out = post.call(out, transformer, options)
+      end
+      File.open(outname, "w:UTF-8") { |f| f.write(out) } if outname
+      out
+    end
+
+    # Resolve the input XML string from whichever leg fired: the semantic
+    # leg passes the XML as +isodoc_node+; the presentation leg passes nil
+    # and the presentation-XML file path as +inname+.
+    #
+    # @param isodoc_node [String, nil] semantic XML string, or nil.
+    # @param inname [String] presentation-XML file path (used when node nil).
+    # @return [String] the input XML.
+    def document_model_input_xml(isodoc_node, inname)
+      return isodoc_node if isodoc_node
+
+      File.read(inname, encoding: "UTF-8")
     end
+    private :document_model_input_xml
 
     # Read processor-relevant options from the input file's header
     # via {Metanorma::Input::Asciidoc#extract_options}, merging in

data/metanorma-core.gemspec

@@ -23,10 +23,10 @@ Gem::Specification.new do |spec|
     f.match(%r{^(test|spec|features|bin|.github)/}) \
     || f.match(%r{Rakefile|bin/rspec})
   end
-  spec.required_ruby_version = Gem::Requirement.new(">= 3.1.0")
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.3.0")
 
   spec.add_dependency "asciidoctor"
-  spec.add_dependency "metanorma-taste", "~> 1.0.0"
+  spec.add_dependency "metanorma-taste", "~> 1.1.0"
   spec.add_dependency "metanorma-utils"
   spec.add_dependency "nokogiri"
 

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: metanorma-core
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.3
 platform: ruby
 authors:
 - Ribose Inc.
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-25 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asciidoctor
@@ -30,14 +29,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.0.0
+        version: 1.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.0.0
+        version: 1.1.0
 - !ruby/object:Gem::Dependency
   name: metanorma-utils
   requirement: !ruby/object:Gem::Requirement
@@ -164,6 +163,7 @@ 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
@@ -184,7 +184,6 @@ homepage: https://github.com/metanorma/metanorma-core
 licenses:
 - BSD-2-Clause
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -192,15 +191,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Metanorma Core
 test_files: []