metanorma-core 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75534ea08c92e8ce3d6c9011c6f0ffb3cda325ba1a0955ca3715f12c8023ff84
-  data.tar.gz: d8afbb2d77828838eb694ede69fcb7bed5d680f7b224913726c55d6d6e2537e5
+  metadata.gz: ed26c327953bc5f8571454087342a413f4c5c7e9f1f4030b3f438cccc7e037d1
+  data.tar.gz: c7d871e81da7a7c84615ef357a3abea8717ef1a1fb3380af6b5ae436f25eede9
 SHA512:
-  metadata.gz: 40e5e611703c2f81216430d2af7e14ec4544c2de8feec7bf02ff00964c7df08e315ec46a1fc24deca556e161ff91b40493aee80bcdf6890eaaaea6a2b3474793
-  data.tar.gz: a7da456887f1dd604d1834d416299756f420839d6a76c284d49211c2203a9b7781d5cd79ec7cd12de49416602c13541ad6688b40758497e510f0fa6d7a1d360d
+  metadata.gz: 24192aefbe3788198362fec82be7b6e95336a34ca358aba0ee7b20a85f8d772b79f6f077f300a6a9970c69f24f13ca412805485c0d73e41ab33c5ded8764a55b
+  data.tar.gz: 723335b30b227377c3f552506f81081c892c4772c489ddc143a63d8f909257d29795c7b99cfb0a23e996559c5b9dbc77ae5a98ee4500c4929ddcd82f81474a38

data/lib/metanorma/asciidoctor_extensions/glob_include_processor.rb

@@ -1,6 +1,26 @@
 module Metanorma
+  # Asciidoctor extensions registered globally when metanorma-core is
+  # loaded. Provides the +include::pattern[]+ glob support used across
+  # the metanorma stack.
   module AsciidoctorExtensions
+    # Asciidoctor +IncludeProcessor+ that expands glob patterns in
+    # +include::+ directives. When the +target+ contains a +*+, the
+    # files matching the glob (relative to the including reader's
+    # +dir+) are included in reverse-sorted order, each separated
+    # from the next by a blank line unless the +adjoin-option+
+    # attribute is set.
+    #
+    # @example In an Asciidoc document
+    #   include::sections/*.adoc[]
     class GlobIncludeProcessor < ::Asciidoctor::Extensions::IncludeProcessor
+      # @param _doc [Asciidoctor::Document] containing document (unused).
+      # @param reader [Asciidoctor::Reader] the include site's reader.
+      # @param target_glob [String] glob pattern relative to
+      #   +reader.dir+.
+      # @param attributes [Hash] include directive attributes;
+      #   recognises +"adjoin-option"+ to suppress the inter-file
+      #   blank line.
+      # @return [Asciidoctor::Reader] the reader, mutated in place.
       def process(_doc, reader, target_glob, attributes)
         Dir[File.join reader.dir, target_glob].sort.reverse_each do |target|
           content = File.readlines target
@@ -10,6 +30,12 @@ module Metanorma
         reader
       end
 
+      # Whether this processor handles the given include +target+.
+      # Triggers on any target containing +*+ — sufficient for the
+      # glob patterns the metanorma stack uses.
+      #
+      # @param target [String] include directive target.
+      # @return [Boolean]
       def handles?(target)
         target.include? "*"
       end

data/lib/metanorma/config/config.rb

@@ -1,17 +1,41 @@
 module Metanorma
+  # Configuration mixin for the +Metanorma+ module. Provides the
+  # +Metanorma.configure+ block-based setup pattern and the
+  # +Metanorma.configuration+ accessor for read access.
+  #
+  # @example
+  #   Metanorma.configure do |c|
+  #     c.logs = %i[error fatal]
+  #   end
   module Config
+    # Yield the singleton {Metanorma::Configuration} for in-place
+    # mutation, e.g. flipping which log severities are printed.
+    #
+    # @yieldparam [Metanorma::Configuration] the singleton config.
+    # @return [Metanorma::Configuration, nil] the config if no block
+    #   was given (preserving the original semantics), otherwise the
+    #   block's return value.
     def configure
       if block_given?
         yield configuration
       end
     end
 
+    # Lazily-instantiated singleton {Metanorma::Configuration} for the
+    # +Metanorma+ module.
+    #
+    # @return [Metanorma::Configuration]
     def configuration
       @configuration ||= Configuration.new
     end
   end
 
+  # Mutable runtime configuration for the metanorma stack. Currently
+  # carries only the +logs+ severity allowlist consumed by
+  # {Metanorma::Util#log}; other settings can be added here as
+  # cross-cutting needs arise.
   class Configuration
+    # @return [Array<Symbol>] severities printed by {Metanorma::Util#log}.
     attr_accessor :logs
 
     def initialize

data/lib/metanorma/core/boilerplate.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+require "asciidoctor"
+require "nokogiri"
+
+module Metanorma
+  module Core
+    # Inline-snippet boilerplate handling shared across metanorma-standoc
+    # and metanorma (collection layer). Provides Liquid + inline-Asciidoc
+    # substitution into docidentifier-like snippets, plus the
+    # option-isolating Asciidoctor convert wrapper used to keep nested
+    # conversions from leaking attribute / extension-registry state.
+    #
+    # Standoc's Cleanup::Boilerplate includes this module and overrides
+    # {#boilerplate_snippet_cleanup} to apply standoc-specific namespace
+    # cleanup and footnote separation; the metanorma collection layer
+    # calls into it as module functions
+    # (e.g. +Metanorma::Core::Boilerplate.docidentifier_boilerplate_isodoc+)
+    # without including the module — both forms are supported via
+    # +extend self+ at the bottom of this module.
+    module Boilerplate
+      # Asciidoctor attributes that are safe to inherit from an outer
+      # conversion context into an isolated nested convert. Anything not
+      # in this set is dropped.
+      SAFE_SHARED_ATTRIBUTES = {
+        "source-highlighter" => "html-pipeline",
+        "nofooter" => "",
+        "no-header-footer" => "",
+      }.freeze
+
+      # Convert a snippet of Asciidoc-with-Liquid text into the
+      # localised, cleaned-up XML string suitable for substitution into
+      # a surrounding document. Three stages run in order:
+      #
+      # 1. Liquid substitution via +isodoc.populate_template+.
+      # 2. Asciidoc-to-XML conversion via {#adoc2xml} (wraps in a
+      #    headless dummy document, runs an isolated Asciidoctor
+      #    convert, extracts the +//sections+ subtree).
+      # 3. {#boilerplate_snippet_cleanup} extension hook (default
+      #    identity; standoc overrides for namespace-cleanup +
+      #    footnote separation).
+      # 4. Localisation via +isodoc.i18n.l10n+.
+      #
+      # @param adoc [String] Snippet of Asciidoc text, possibly
+      #   containing Liquid expressions like
+      #   +{% if seriesabbr %}{{seriesabbr}}{% endif %}+.
+      # @param isodoc [#populate_template, #i18n] An isodoc converter
+      #   instance. Must respond to +populate_template(text, options)+
+      #   for Liquid substitution and +i18n+ (returning an object
+      #   responding to +l10n(text, lang, script)+).
+      # @param lang [String] BCP-47 language tag (e.g. "en") passed to
+      #   +l10n+. Owned by the caller because the docidentifier-template
+      #   pipeline runs outside the isodoc converter's own +@lang+
+      #   state in the collection use case.
+      # @param script [String] ISO-15924 script tag (e.g. "Latn"),
+      #   passed to +l10n+ for the same reason as +lang+.
+      # @param backend [Symbol] Asciidoctor backend symbol
+      #   (e.g. +:standoc+, +:iso+). Determines which converter
+      #   Asciidoctor dispatches to for the inner conversion.
+      # @param flush_caches [Boolean] If true, the dummy document
+      #   wrapper includes +:flush-caches:+, telling Asciidoctor to
+      #   discard cached parse results before running this snippet.
+      #   Standoc threads its converter-level +@flush_caches+ through
+      #   here. Defaults to false.
+      # @param localdir [String, nil] Filesystem path used as the inner
+      #   conversion's +:base_dir+ if the caller does not supply one
+      #   explicitly. Standoc passes its +@localdir+; the collection
+      #   layer passes the collection's +@dirname+.
+      # @return [String] The substituted, cleaned-up XML/text snippet
+      #   ready to splice into the surrounding document.
+      def boilerplate_snippet_convert(adoc, isodoc, lang:, script:, backend:,
+                                      flush_caches: false, localdir: nil)
+        b = isodoc.populate_template(adoc, nil)
+        node = adoc2xml(b, backend, flush_caches: flush_caches,
+                                    localdir: localdir)
+        ret = boilerplate_snippet_cleanup(node)
+        isodoc.i18n.l10n(ret.children.to_xml, lang, script).strip
+      end
+
+      # Extension hook invoked by {#boilerplate_snippet_convert} on the
+      # output of {#adoc2xml} before localisation. Default
+      # implementation is the identity. Standoc's Cleanup::Boilerplate
+      # overrides it to apply boilerplate_xml_cleanup and footnote
+      # renumbering; the metanorma collection layer leaves it as
+      # identity (no standoc-namespace cleanup needed at that stage).
+      #
+      # @param node [Nokogiri::XML::Node] The +//sections+ subtree
+      #   returned by Asciidoctor for the snippet.
+      # @return [Nokogiri::XML::Node] The (possibly transformed) node
+      #   whose children will be serialised as the snippet's output.
+      def boilerplate_snippet_cleanup(node)
+        node
+      end
+
+      # Iterate over every +<docidentifier @boilerplate>+ element in
+      # +xmldoc+ and replace its content with the Liquid-substituted,
+      # Asciidoc-rendered output. Called from standoc's cleanup
+      # pipeline (post-processing semantic XML) and from the metanorma
+      # collection layer (pre-processing the collection bibdata before
+      # MergeBibitems hands it to Relaton — see issue
+      # https://github.com/metanorma/metanorma/issues/558).
+      #
+      # The +@boilerplate+ attribute is removed in all matched cases;
+      # substitution is performed only when its value is +"true"+.
+      # The output of {#boilerplate_snippet_convert} is a serialised
+      # +<sections><p>...</p></sections>+; the inner +<p>+ children
+      # are spliced into the docidentifier (or the raw output if no
+      # +<p>+ was produced).
+      #
+      # @param xmldoc [Nokogiri::XML::Document, Nokogiri::XML::Node]
+      #   The document or subtree to scan. **Mutated in place**: every
+      #   matched +<docidentifier @boilerplate>+ has its
+      #   +@boilerplate+ attribute stripped, and (when its value was
+      #   +"true"+) its content replaced with the substituted output.
+      # @param isodoc [#populate_template, #i18n] Isodoc instance, see
+      #   {#boilerplate_snippet_convert}.
+      # @param lang [String] see {#boilerplate_snippet_convert}.
+      # @param script [String] see {#boilerplate_snippet_convert}.
+      # @param backend [Symbol] see {#boilerplate_snippet_convert}.
+      # @param flush_caches [Boolean] see {#boilerplate_snippet_convert}.
+      # @param localdir [String, nil] see {#boilerplate_snippet_convert}.
+      # @return [Nokogiri::XML::Document, Nokogiri::XML::Node] The
+      #   input +xmldoc+, mutated in place.
+      # @see .docidentifier_templates?
+      def docidentifier_boilerplate_isodoc(xmldoc, isodoc, lang:, script:,
+                                           backend:, flush_caches: false,
+                                           localdir: nil)
+        xmldoc.xpath("//docidentifier[@boilerplate]").each do |d|
+          do_substitute = d["boilerplate"] == "true"
+          d.delete("boilerplate")
+          do_substitute or next
+          id = boilerplate_snippet_convert(
+            d.children.to_xml, isodoc,
+            lang: lang, script: script, backend: backend,
+            flush_caches: flush_caches, localdir: localdir,
+          )
+          p_node = Nokogiri::XML(id).at("//p")
+          new_children = p_node ? p_node.children.to_xml : id
+          # If the rendered template is blank (e.g. a Liquid template
+          # that gates on a missing docnumeric), drop the
+          # <docidentifier> entirely instead of leaving an empty
+          # element behind. Downstream Relaton flavours
+          # (relaton-iho, relaton-cc, …) eagerly call Pubid::*::Identifier.parse
+          # on the docidentifier content; an empty string is truthy
+          # in Ruby and would crash that parser, so the empty element
+          # must not survive this pass.
+          if new_children.to_s.strip.empty?
+            d.remove
+          else
+            d.children = new_children
+          end
+        end
+        xmldoc
+      end
+
+      # Predicate: are there any +<docidentifier @boilerplate="true">+
+      # nodes in +xmldoc+ that {#docidentifier_boilerplate_isodoc} would
+      # substitute? Callers use this to decide whether to refresh
+      # downstream state (e.g. re-seed +isodoc.meta+ from the resolved
+      # bibdata) after the substitution pass — cheap pre-check, avoids
+      # depending on a return-value side channel from the mutating
+      # substitution method.
+      #
+      # @param xmldoc [Nokogiri::XML::Document, Nokogiri::XML::Node]
+      # @return [Boolean]
+      def docidentifier_templates?(xmldoc)
+        xmldoc.xpath("//docidentifier[@boilerplate = 'true']").any?
+      end
+
+      # Wrap +text+ in the standard headless dummy document used across
+      # the metanorma stack and run an isolated Asciidoctor convert
+      # against the given backend. Returns the +//sections+ subtree as
+      # a Nokogiri node so callers can splice its children into a
+      # surrounding document.
+      #
+      # If +text+ is already valid XML (root element parses), it is
+      # returned verbatim — this lets callers stash pre-converted XML
+      # alongside Asciidoc snippets without a special case.
+      #
+      # @param text [String] Asciidoc snippet, or already-converted XML.
+      # @param flavour [Symbol] Asciidoctor backend.
+      # @param flush_caches [Boolean] Add +:flush-caches:+ to the
+      #   dummy header. See {#boilerplate_snippet_convert}.
+      # @param localdir [String, nil] Forwarded to
+      #   {#isolated_asciidoctor_convert} via the options hash.
+      # @return [Nokogiri::XML::Node, String] +//sections+ subtree
+      #   for converted Asciidoc; original +text+ if input was XML.
+      def adoc2xml(text, flavour, flush_caches: false, localdir: nil)
+        Nokogiri::XML(text).root and return text
+        f = flush_caches ? ":flush-caches:\n" : ""
+        doc = <<~ADOC
+          = X
+          A
+          :semantic-metadata-headless: true
+          :no-isobib:
+          #{f}:novalid:
+          :!sectids:
+
+          #{text}
+        ADOC
+        c = isolated_asciidoctor_convert(
+          doc, backend: flavour, header_footer: true, localdir: localdir,
+        )
+        Nokogiri::XML(c).at("//xmlns:sections")
+      end
+
+      # Run +Asciidoctor.convert+ with curated options so that
+      # attributes, +base_dir+, and safe-mode setting do NOT leak in
+      # from any outer conversion context. Forces +novalid+ for the
+      # inner conversion. The conversion stack is tracked in
+      # +@isolated_conversion_stack+ for diagnostics; the +ensure+
+      # pop guarantees the marker is balanced even on exception.
+      #
+      # +localdir+ may be passed inside +options+ as +:localdir+; if
+      # so it becomes +:base_dir+ for the inner convert (unless the
+      # caller supplied an explicit +:base_dir+). The +:localdir+ key
+      # is stripped before delegating to +Asciidoctor.convert+ so it
+      # does not appear as an unknown option. Callers that include
+      # this module from a class with +@localdir+ get +:base_dir+
+      # wired up from there as a fallback.
+      #
+      # @param content [String] Asciidoc input.
+      # @param options [Hash] Asciidoctor convert options. Recognised
+      #   special key: +:localdir+ (used for +:base_dir+ defaulting
+      #   and stripped before forwarding).
+      # @return [String] Asciidoctor convert output.
+      def isolated_asciidoctor_convert(content, options = {})
+        @isolated_conversion_stack ||= []
+        @isolated_conversion_stack << true
+        begin
+          preserved = extract_preserved_options(options)
+          options = options.dup
+          options.delete(:localdir)
+          isolated = preserved.merge(options).merge(
+            attributes: (preserved[:attributes] || {}).merge(
+              "novalid" => "",
+            ),
+          )
+          ::Asciidoctor.convert(content, isolated)
+        ensure
+          @isolated_conversion_stack.pop
+        end
+      end
+
+      # Compute the option set carried over from outer conversion
+      # state: a curated subset (+:safe+, +:base_dir+) plus the
+      # SAFE_SHARED_ATTRIBUTES hash if the caller did not supply
+      # +:attributes+. Caller's own option hash takes precedence
+      # for everything except +"novalid"+, which the caller of
+      # {#isolated_asciidoctor_convert} forces.
+      #
+      # @param user_opt [Hash] Caller-supplied options. Recognised:
+      #   +:safe+, +:attributes+, +:base_dir+, +:localdir+.
+      # @return [Hash] Preserved options to merge in front of
+      #   +user_opt+ for the inner +Asciidoctor.convert+.
+      def extract_preserved_options(user_opt)
+        options = {}
+        options[:safe] = user_opt[:safe] if user_opt.key?(:safe)
+        localdir = user_opt[:localdir] ||
+          (defined?(@localdir) ? @localdir : nil)
+        if localdir && !user_opt.key?(:base_dir)
+          options[:base_dir] = localdir
+        end
+        if user_opt[:attributes].nil?
+          options[:attributes] = SAFE_SHARED_ATTRIBUTES.dup
+        end
+        options
+      end
+
+      # Make every method callable as both
+      # +Metanorma::Core::Boilerplate.method+ (for the metanorma
+      # collection-layer caller, which does not include the module)
+      # and as a regular public instance method (for includers like
+      # +Metanorma::Standoc::Cleanup::Boilerplate+).
+      extend self
+    end
+  end
+end

data/lib/metanorma/core/flavor_loader.rb

@@ -4,9 +4,27 @@ require "date"
 
 module Metanorma
   module Core
+    # Locate and load the right flavor gem (e.g. +metanorma-iso+,
+    # +metanorma-itu+) for a given standard type, registering its
+    # processor with {Metanorma::Registry} as a side effect.
+    #
+    # Standard types may be specified as a "taste" name
+    # (e.g. +:bipm+, +:icc+) which is mapped to its canonical flavor
+    # via {Metanorma::TasteRegister}. Flavor gems follow the
+    # +metanorma-<flavor>+ naming convention.
+    #
+    # The +load_flavor+ entry point both resolves and loads, and is
+    # idempotent: if the flavor's processor is already registered,
+    # no gem load is attempted.
     module FlavorLoader
       module_function
 
+      # Resolve a standard type or taste name to its canonical flavor
+      # symbol via the TasteRegister.
+      #
+      # @param stdtype [Symbol, String] standard type or taste name.
+      # @return [Symbol] canonical flavor symbol (the input if no
+      #   taste alias matched).
       def taste2flavor(stdtype)
         stdtype = stdtype.to_sym
         tastes = Metanorma::TasteRegister.instance.aliases
@@ -14,10 +32,24 @@ module Metanorma
         stdtype
       end
 
+      # Map a canonical flavor symbol to its gem name.
+      #
+      # @param stdtype [Symbol, String] canonical flavor symbol.
+      # @return [String] gem name (e.g. +"metanorma-iso"+).
       def stdtype2flavor_gem(stdtype)
         "metanorma-#{stdtype}"
       end
 
+      # Load the flavor gem for +stdtype+ if its processor is not yet
+      # registered, and return the canonical flavor symbol.
+      #
+      # On a fatal LoadError, an error log file is written and
+      # +abort+ is called via {Metanorma::Util#log} (severity +:fatal+).
+      # If the gem loads but does not register a processor under the
+      # expected canonical name, the same fatal-abort path runs.
+      #
+      # @param stdtype [Symbol, String] standard type or taste name.
+      # @return [Symbol] canonical flavor symbol.
       def load_flavor(stdtype)
         canonical = taste2flavor(stdtype)
         gem_name = stdtype2flavor_gem(canonical)
@@ -29,6 +61,13 @@ module Metanorma
         canonical
       end
 
+      # Require the flavor gem and log success / failure. On +LoadError+,
+      # delegates to {.write_flavor_error_log} which produces a fatal
+      # abort. Used internally by {.load_flavor}.
+      #
+      # @param gem_name [String] gem name (e.g. +"metanorma-iso"+).
+      # @param stdtype [Symbol, String] standard type for the user-facing
+      #   info log line.
       def require_flavor_gem(gem_name, stdtype)
         Metanorma::Util.log("[metanorma] Info: Loading `#{gem_name}` gem " \
                             "for standard type `#{stdtype}`.", :info)
@@ -39,6 +78,13 @@ module Metanorma
         write_flavor_error_log(e, gem_name)
       end
 
+      # Write a dated error-log file capturing a failed gem load and
+      # abort with a user-facing fatal message that points the user at
+      # the metanorma issue tracker.
+      #
+      # @param err [Exception] the LoadError raised by +require+.
+      # @param gem_name [String] gem name that failed to load.
+      # @return [void] (calls +abort+ via {Metanorma::Util#log}).
       def write_flavor_error_log(err, gem_name)
         error_log = "#{Date.today}-error.log"
         File.write(error_log, err)
@@ -58,6 +104,13 @@ module Metanorma
         Metanorma::Util.log(msg, :fatal)
       end
 
+      # Fatal-abort path for the case where the flavor gem loaded but
+      # did not register a processor for the requested standard type.
+      #
+      # @param gem_name [String] gem name that loaded.
+      # @param stdtype [Symbol, String] standard type that the gem did
+      #   not register a processor for.
+      # @return [void] (calls +abort+ via {Metanorma::Util#log}).
       def flavor_unsupported(gem_name, stdtype)
         Metanorma::Util.log("[metanorma] Error: The `#{gem_name}` gem does " \
                             "not support the standard type #{stdtype}. " \

data/lib/metanorma/core/isodoc.rb

@@ -5,17 +5,58 @@ require_relative "flavor_loader"
 
 module Metanorma
   module Core
+    # Construction and initialisation of an isodoc converter instance for a
+    # given Metanorma flavor. Two entry points:
+    #
+    # - {.resolve_converter} — pick the right converter class for the
+    #   flavor + output stage (presentation XML or HTML), instantiate it,
+    #   and return a fresh, *uninitialised* converter.
+    # - {.init} — wire i18n, metadata, and xref state onto an existing
+    #   converter, returning it ready for use.
+    #
+    # Callers usually need both: +init(resolve_converter(flavor), ...)+.
+    # The collection layer's +Util::isodoc_create+ is the canonical wrapper
+    # around that pair.
     module Isodoc
+      # Stand-in for the Asciidoctor +node+ argument that converters expect
+      # when their +presentation_xml_converter+ / +html_converter+ factory
+      # methods are invoked outside an actual Asciidoctor conversion. The
+      # +attr+ and +attributes+ stubs return empty values so the factory
+      # can run without a real document context.
       class EmptyNode
+        # @param _ [String] attribute name (ignored).
+        # @return [nil]
         def attr(_)
           nil
         end
 
+        # @return [Hash] empty attribute set.
         def attributes
           {}
         end
       end
 
+      # Initialise the i18n / metadata / xref state on an existing
+      # converter. Mutates the converter in place and returns it.
+      #
+      # The converter must already implement the standard Metanorma
+      # converter contract: +#init_i18n+, +#i18n_init+, +#metadata_init+,
+      # +#meta+, +#xref_init+, +#xrefs+, and (optionally) +#info+.
+      #
+      # @param converter [Object] An IsoDoc-style converter instance,
+      #   typically returned by {.resolve_converter}.
+      # @param lang [String] BCP-47 language tag (e.g. "en").
+      # @param script [String] ISO-15924 script tag (e.g. "Latn").
+      # @param locale [String, nil] Optional BCP-47 locale tag for
+      #   region-specific overrides.
+      # @param i18nyaml [Hash, String, nil] Either a parsed i18n hash or
+      #   a path to a YAML file. Forwarded to +init_i18n+.
+      # @param xml [Nokogiri::XML::Node, nil] If supplied, +converter.info+
+      #   is invoked against it so document-level metadata can be primed.
+      # @param localdir [String, nil] If supplied, wired into both
+      #   +converter.meta+ and +converter.xrefs.klass+ so file lookups
+      #   resolve relative to the right directory.
+      # @return [Object] the same +converter+, fully initialised.
       def self.init(converter, lang:, script:, locale: nil,
                     i18nyaml: nil, xml: nil, localdir: nil)
         converter.init_i18n(i18nyaml: i18nyaml, language: lang,
@@ -30,6 +71,21 @@ module Metanorma
         converter
       end
 
+      # Resolve the right IsoDoc converter for a given Metanorma flavor
+      # and output stage, and return a fresh, *uninitialised* instance
+      # of it. The flavor's gem (e.g. metanorma-iso) is autoloaded via
+      # {Metanorma::Core::FlavorLoader.load_flavor} if it is not already
+      # registered.
+      #
+      # @param flavor [Symbol, String] Metanorma flavor (e.g. +:iso+,
+      #   +:standoc+) or a taste name resolvable to one.
+      # @param presxml [Boolean] If true (default), return the flavor's
+      #   presentation-XML converter; otherwise its HTML converter.
+      # @return [Object] An IsoDoc-style converter instance, ready to
+      #   pass to {.init}.
+      # @raise [RuntimeError] If no Asciidoctor converter is registered
+      #   for the resolved flavor, or if the converter does not support
+      #   the requested output stage.
       def self.resolve_converter(flavor, presxml: true)
         resolved = Metanorma::Core::FlavorLoader.load_flavor(flavor)
         conv_class = ::Asciidoctor::Converter.for(resolved.to_s) ||
@@ -43,6 +99,33 @@ module Metanorma
                 "#{presxml ? 'presentation XML' : 'HTML'} conversion"
         conv_instance.send(method_name, EmptyNode.new)
       end
+
+      # Convenience wrapper combining {.resolve_converter} and {.init}:
+      # resolve the converter for +flavor+ and immediately initialise it
+      # with the supplied i18n / metadata kwargs. Most callers want this
+      # one-stop helper rather than the two-step form.
+      #
+      # @param flavor [Symbol, String] flavor or taste name; resolved via
+      #   {Metanorma::Core::FlavorLoader.load_flavor}.
+      # @param lang [String] BCP-47 language tag (e.g. "en").
+      # @param script [String] ISO-15924 script tag (e.g. "Latn").
+      # @param locale [String, nil] optional BCP-47 locale tag.
+      # @param i18nyaml [Hash, String, nil] either a parsed i18n hash or
+      #   a path to a YAML file. Forwarded to +init_i18n+.
+      # @param xml [Nokogiri::XML::Node, nil] if supplied, +converter.info+
+      #   is invoked against it for metadata priming.
+      # @param localdir [String, nil] wired into +converter.meta+ and
+      #   +converter.xrefs.klass+ for relative file-lookup resolution.
+      # @param presxml [Boolean] if true (default), return the flavor's
+      #   presentation-XML converter; otherwise its HTML converter.
+      # @return [Object] a fully initialised IsoDoc-style converter.
+      # @see https://github.com/metanorma/metanorma/issues/558
+      def self.create(flavor, lang:, script:, locale: nil, i18nyaml: nil,
+                      xml: nil, localdir: nil, presxml: true)
+        conv = resolve_converter(flavor, presxml: presxml)
+        init(conv, lang: lang, script: script, locale: locale,
+                   i18nyaml: i18nyaml, xml: xml, localdir: localdir)
+      end
     end
   end
 end

data/lib/metanorma/core/version.rb

@@ -1,5 +1,5 @@
 module Metanorma
   module Core
-    VERSION = "0.1.2".freeze
+    VERSION = "0.2.0".freeze
   end
 end

data/lib/metanorma/input/asciidoc.rb

@@ -2,7 +2,25 @@ require "nokogiri"
 
 module Metanorma
   module Input
+    # Asciidoc input processor. Wraps Asciidoctor to convert raw
+    # Asciidoc source into the flavor's semantic XML, and parses the
+    # document header to extract metanorma- and Asciidoctor-level
+    # configuration attributes (used by {Metanorma::Processor#extract_options}
+    # and friends).
     class Asciidoc < Base
+      # Convert +file+ to the target backend's output by running
+      # +Asciidoctor.convert+ with safe-mode and metanorma-specific
+      # attributes.
+      #
+      # @param file [String] raw Asciidoc source.
+      # @param filename [String] +docfile+ value, used by Asciidoctor
+      #   for include-relative path resolution.
+      # @param type [Symbol] Asciidoctor backend symbol (e.g. +:iso+,
+      #   +:standoc+).
+      # @param options [Hash] passthrough options. Recognised:
+      #   +:log+ (Asciidoctor logger), +:novalid+ (skip validation),
+      #   +:output_dir+ (forwarded as the +output_dir+ attribute).
+      # @return [String] Asciidoctor convert output.
       def process(file, filename, type, options = {})
         require "asciidoctor"
         out_opts = { to_file: false, safe: :safe, backend: type,
@@ -13,12 +31,28 @@ module Metanorma
         ::Asciidoctor.convert(file, out_opts)
       end
 
+      # Split a raw Asciidoc file into its header and body. The header
+      # is everything up to the first blank line.
+      #
+      # @param file [String] raw Asciidoc source.
+      # @return [Array<(String, String), (nil, nil)>] +[header, body]+;
+      #   +[nil, nil]+ if +file+ does not split.
       def header(file)
         ret = file.split("\n\n", 2) or return [nil, nil]
         ret[0] and ret[0] += "\n"
         [ret[0], ret[1]]
       end
 
+      # Read metanorma-specific attributes from an Asciidoc header.
+      # Supports both bare (e.g. +:document-class:+) and +mn-+ prefixed
+      # forms (e.g. +:mn-document-class:+); +document-class+ and +flavor+
+      # are aliases. Returns a +.compact+'d hash so absent keys are
+      # omitted entirely.
+      #
+      # @param file [String] raw Asciidoc source (header is
+      #   re-extracted internally).
+      # @return [Hash] subset of the keys +:type+, +:extensions+,
+      #   +:relaton+, +:asciimath+, +:novalid+.
       def extract_metanorma_options(file)
         hdr, = header(file)
         /\n:(?:mn-)?(?:document-class|flavor):\s+(?<type>\S[^\n]*)\n/ =~ hdr
@@ -39,10 +73,20 @@ module Metanorma
         }.compact
       end
 
+      # Normalise a bare-attribute form (e.g. +":use-xinclude:"+) so a
+      # value-less attribute reads as +"true"+, while a present-value
+      # attribute is left in its natural shape.
+      #
+      # @param attr [String, nil] line matching +":NAME:"+ ...
+      # @param name [String] attribute name (without colons).
+      # @return [String, nil] +"true"+ if value-less, the value
+      #   otherwise; +nil+ if +attr+ was +nil+.
       def empty_attr(attr, name)
         attr&.sub(/^#{name}:\s*$/, "#{name}: true")&.sub(/^#{name}:\s+/, "")
       end
 
+      # Asciidoc attributes whose presence is parsed as a string value
+      # (no boolean default). See {#extract_options}.
       ADOC_OPTIONS =
         %w(htmlstylesheet htmlcoverpage htmlintropage scripts
            scripts-override scripts-pdf wordstylesheet i18nyaml
@@ -61,19 +105,37 @@ module Metanorma
            localize-number iso-word-bg-strip-color modspec-identifier-base)
           .freeze
 
+      # Boolean Asciidoc attributes that default to +true+ if the
+      # attribute is bare (no value).
       EMPTY_ADOC_OPTIONS_DEFAULT_TRUE =
         %w(data-uri-image suppress-asciimath-dup use-xinclude
            source-highlighter).freeze
 
+      # Boolean Asciidoc attributes that default to +false+ if the
+      # 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
 
+      # Convert an Asciidoc-style attribute name (kebab-case, possibly
+      # ending in +-override+ or +-pdf+) into the Ruby symbol used in
+      # this gem's option hashes.
+      #
+      # @param name [String] attribute name from Asciidoc header.
+      # @return [Symbol]
       def attr_name_normalise(name)
         name.delete("-").sub(/override$/, "_override").sub(/pdf$/, "_pdf")
           .to_sym
       end
 
+      # Read processor-relevant options from an Asciidoc header. Three
+      # categories are scanned: string-valued ({ADOC_OPTIONS}), boolean
+      # default-true ({EMPTY_ADOC_OPTIONS_DEFAULT_TRUE}), and boolean
+      # default-false ({EMPTY_ADOC_OPTIONS_DEFAULT_FALSE}). The result
+      # is +.compact+'d so absent keys are omitted.
+      #
+      # @param file [String] raw Asciidoc source.
+      # @return [Hash{Symbol => String, Boolean}]
       def extract_options(file)
         hdr, = header(file)
         ret = ADOC_OPTIONS.each_with_object({}) do |w, acc|

data/lib/metanorma/input/base.rb

@@ -1,6 +1,14 @@
 module Metanorma
   module Input
+    # Abstract base for input processors. Concrete subclasses
+    # (e.g. {Metanorma::Input::Asciidoc}) override {#process} to
+    # convert raw input text into ISODoc semantic XML.
     class Base
+      # @param _file [String] raw input contents.
+      # @param _filename [String] source filename for relative
+      #   path resolution.
+      # @param _type [Symbol] target backend symbol.
+      # @raise [RuntimeError] abstract base — subclasses must override.
       def process(_file, _filename, _type)
         raise "This is an abstract class"
       end

data/lib/metanorma/processor/processor.rb

@@ -2,13 +2,39 @@
 #
 
 module Metanorma
+  # Abstract base class for Metanorma flavor processors. Each flavor
+  # gem (metanorma-iso, metanorma-itu, etc.) defines a subclass and
+  # registers it with {Metanorma::Registry}; the registry then
+  # dispatches input documents to the appropriate processor based on
+  # the document's declared flavor / class.
+  #
+  # Subclasses MUST set +@short+, +@input_format+, and (if Asciidoctor
+  # is the input parser) +@asciidoctor_backend+ in their +initialize+,
+  # and MAY override {#output_formats}, {#use_presentation_xml},
+  # {#options_preprocess}, and {#output} to customise their output
+  # pipeline.
   class Processor
-    attr_reader :short, :input_format, :asciidoctor_backend
+    # @return [Symbol] short name registered with the Registry
+    #   (e.g. +:iso+, +:itu+).
+    attr_reader :short
 
+    # @return [Symbol] input parser identifier (typically +:asciidoc+).
+    attr_reader :input_format
+
+    # @return [Symbol, nil] Asciidoctor backend symbol used when the
+    #   processor's input is Asciidoc (e.g. +:iso+, +:standoc+);
+    #   +nil+ for non-Asciidoc inputs.
+    attr_reader :asciidoctor_backend
+
+    # @raise [RuntimeError] always — concrete flavors must override.
     def initialize
       raise "This is an abstract class!"
     end
 
+    # Mapping of output-format name to file extension. Subclasses
+    # typically extend this with HTML / Word / PDF entries.
+    #
+    # @return [Hash{Symbol => String}] format symbol -> file extension.
     def output_formats
       {
         xml: "xml",
@@ -17,6 +43,17 @@ module Metanorma
       }
     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
+    # inputs.
+    #
+    # @param file [String] the raw input contents.
+    # @param filename [String] the source filename (used for relative
+    #   path resolution in includes).
+    # @param options [Hash] passthrough options for the input
+    #   processor; see {Metanorma::Input::Asciidoc#process}.
+    # @return [String] Metanorma semantic XML.
     def input_to_isodoc(file, filename, options = {})
       Metanorma::Input::Asciidoc.new.process(file, filename,
                                              @asciidoctor_backend, options)
@@ -26,6 +63,13 @@ module Metanorma
     #   raise "This is an abstract class!"
     # end
 
+    # Whether the given output extension is downstream of the
+    # presentation XML stage (and therefore needs presentation XML
+    # generated first). Defaults to true for HTML/Word/PDF. Other formats
+    # such as RFC and STS are generated directly from semantic XML
+    #
+    # @param ext [Symbol] output-format symbol.
+    # @return [Boolean]
     def use_presentation_xml(ext)
       case ext
       when :html, :doc, :pdf then true
@@ -34,21 +78,48 @@ module Metanorma
       end
     end
 
+    # Mutate +options+ in place to ensure +:output_formats+ is set.
+    # Override to add other flavor-specific defaults.
+    #
+    # @param options [Hash] processor options.
+    # @return [Hash] +options+ with +:output_formats+ defaulted.
     def options_preprocess(options)
       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.
+    #
+    # @param isodoc_node [String] rendered output content.
+    # @param _inname [String] source filename (unused at this base level).
+    # @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) }
     end
 
+    # Read processor-relevant options from the input file's header
+    # via {Metanorma::Input::Asciidoc#extract_options}, merging in
+    # this processor's +output_formats+ for downstream stages.
+    #
+    # @param file [String] raw input contents.
+    # @return [Hash] extracted options.
     def extract_options(file)
       Metanorma::Input::Asciidoc.new.extract_options(file)
         .merge(output_formats: output_formats)
     end
 
+    # Read metanorma-specific options from the input file's header
+    # via {Metanorma::Input::Asciidoc#extract_metanorma_options}.
+    #
+    # @param file [String] raw input contents.
+    # @return [Hash] metanorma-specific options
+    #   (+:type+, +:extensions+, +:relaton+, +:asciimath+, +:novalid+).
     def extract_metanorma_options(file)
       Metanorma::Input::Asciidoc.new.extract_metanorma_options(file)
     end
   end
-end
+end

data/lib/metanorma/util/util.rb

@@ -1,6 +1,20 @@
 module Metanorma
+  # Cross-cutting helpers used by the metanorma stack: logging gated by
+  # {Metanorma::Configuration#logs}, ordering of output-format extensions
+  # for execution, and recursive hash key normalisation.
   module Util
     class << self
+      # Print +message+ to stdout if +type+ is in
+      # {Metanorma::Configuration#logs}; abort the process if
+      # +type+ is +:fatal+ regardless of whether it was printed.
+      #
+      # @param message [String] the message to print.
+      # @param type [Symbol] severity, defaults to +:info+. Common
+      #   values: +:info+, +:warning+, +:error+, +:fatal+. The
+      #   configured +logs+ list determines which severities are
+      #   printed; +:fatal+ always aborts on top of (or instead of)
+      #   printing.
+      # @return [void]
       def log(message, type = :info)
         log_types = Metanorma.configuration.logs.map(&:to_s) || []
 
@@ -13,7 +27,14 @@ module Metanorma
         end
       end
 
-      # dependency ordering
+      # Sort key used to put output-format extensions in execution order.
+      # +xml+ runs first because the semantic XML feeds everything else;
+      # +rxl+ second; +presentation+ third (consumed by HTML/Word/PDF);
+      # everything else last (alphabetical via the caller's sort
+      # stability).
+      #
+      # @param ext [Symbol] output-format extension symbol.
+      # @return [Integer] ordinal for sorting.
       def sort_extensions_execution_ord(ext)
         case ext
         when :xml then 0
@@ -24,12 +45,25 @@ module Metanorma
         end
       end
 
+      # Stable-sort a list of output-format extensions by execution
+      # priority (see {.sort_extensions_execution_ord}).
+      #
+      # @param ext [Array<Symbol>] extensions to sort.
+      # @return [Array<Symbol>] sorted in execution order.
       def sort_extensions_execution(ext)
         ext.sort do |a, b|
           sort_extensions_execution_ord(a) <=> sort_extensions_execution_ord(b)
         end
       end
 
+      # Recursively normalise the keys of a Hash (and any nested Hashes
+      # / Enumerables) to Strings. Used to canonicalise YAML/JSON-derived
+      # configuration that may have been parsed with mixed symbol /
+      # string keys.
+      #
+      # @param hash [Hash, Enumerable, Object] the value to normalise.
+      # @return [Hash, Array, Object] the normalised value; non-collections
+      #   are returned unchanged.
       def recursive_string_keys(hash)
         case hash
         when Hash then hash.map do |k, v|

data/lib/metanorma-core.rb

@@ -10,6 +10,7 @@ require "metanorma/registry/registry"
 require "metanorma/asciidoctor_extensions"
 require "metanorma/core/flavor_loader"
 require "metanorma/core/isodoc"
+require "metanorma/core/boilerplate"
 
 module Metanorma
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: metanorma-core
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-27 00:00:00.000000000 Z
+date: 2026-05-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asciidoctor
@@ -154,6 +154,7 @@ files:
 - 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_loader.rb
 - lib/metanorma/core/isodoc.rb
 - lib/metanorma/core/version.rb