metanorma 2.4.3 → 2.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 157d526ec5945e1eb8faae4f4cc75466fbbf59ec367695264edd10d22d10bd37
-  data.tar.gz: 84eb4ecb451f7614da76abba559a4fe5b750425516dc78357480b68c5d50fe16
+  metadata.gz: e9167ec4dc502678a508ea35bb8ed81d3914487b0dd2f2562b2e26bd2803faff
+  data.tar.gz: cfe251c6ed0436df5b7f9eba6c01e368fb0bee55651366a83a949f403f2b10bc
 SHA512:
-  metadata.gz: 04f311680d84a53dca58be88d51f85df772f5bc75ab928393a55f37253b342ba68d0931da23142ddd45f3a3ec11bb2f778ef165878f02d790f46fca64935a022
-  data.tar.gz: b73810634afb80f8c8dc5b4613421759479b7550262645efa42357b3f53d37ddbfc5f9d2520681ecbade585703baa840b489f975a0d9c28917a095bc93a8663c
+  metadata.gz: 5fe17ebf90571ce884b547f38a8736947d749ad9ec45a7dfcc9e8bb1aef91f2b0e2e284d509d70da150cb806c402945555d698c6f06e03006a46500e4648707e
+  data.tar.gz: 6bf8355bd20b904f7fc7960aadbbbb6363e052b0c7d83689562f0f1fea4811a0785006f24e1766fbf5d354a44424b37f7ea749328229b8e0af925ab90288176f

data/.rubocop.yml

@@ -3,8 +3,20 @@
 inherit_from:
   - https://raw.githubusercontent.com/riboseinc/oss-guides/main/ci/rubocop.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/lib/metanorma/collection/artifact_store.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "digest"
+
+module Metanorma
+  class Collection
+    # Durable, content-addressed store for staged collection-build artefacts.
+    #
+    # Enables incremental (batched) builds and resumption across runs: an
+    # artefact is named +<docid-slug>.<content-hash>.<stage>.<format>+, so a
+    # document already built with identical inputs is detected by filename alone
+    # and reused, and an interrupted run resumes by recomputing which artefacts
+    # are already present.
+    #
+    # Reuse is keyed on the caller-supplied content hash of the document's
+    # *input closure* (source + resolved includes + templates + referenced
+    # schemas + tool versions + options) -- never on file presence alone. See
+    # metanorma/iso-10303#455 for why presence-keyed reuse of compiled XML is
+    # unsound; the store deliberately requires a content hash it does not infer.
+    #
+    # Disabled by default: the collection renderer uses NullArtifactStore unless
+    # an incremental build is explicitly requested (opt-in, never default).
+    class ArtifactStore
+      DEFAULT_DIRNAME = ".metanorma-collection-cache"
+
+      # The artefact-stage vocabulary, and the one non-redundant property each
+      # stage carries: the format it is serialised as (also its file extension).
+      # THIS IS ITS HOME: every producer and consumer names its stage from this
+      # table by symbol, never a bare string literal elsewhere; an unknown stage
+      # raises (KeyError via +fetch+), so the vocabulary cannot drift outside
+      # this file. The stage's *name* is the filename token, so it is not stored
+      # here -- that would just restate the key. The stages trace the pipeline
+      # (isolated compile -> index -> reinflate); each role is documented inline:
+      STAGE_FORMATS = {
+        # Compiled Semantic XML, unresolved cross-document repo:() references
+        # PRESERVED as deterministic stubs (neither stripped nor resolved). The
+        # unit of an isolated per-document compile; a pure function of the
+        # document's input closure, hence content-addressable and reusable.
+        semantic: "xml",
+        # This document's contribution to the global anchor index: its anchors
+        # and ids (type => {label/UUID => anchor-id}). Aggregated across all
+        # documents to build the anchor -> owning-document index used at
+        # reinflation.
+        anchors: "json",
+        # Reinflated Presentation XML: the preserved stubs resolved against the
+        # global index into real cross-document links. Shared source for the PDF
+        # and Word collection outputs, and per-document for HTML.
+        presentation: "xml",
+      }.freeze
+
+      attr_reader :dir
+
+      def initialize(dir)
+        @dir = dir
+        FileUtils.mkdir_p(@dir)
+      end
+
+      # <docid-slug>.<content-hash>.<stage>.<format>
+      # +stage+ must be a key of STAGE_FORMATS; an unknown stage raises KeyError.
+      def path(docid, content_hash, stage)
+        format = STAGE_FORMATS.fetch(stage)
+        File.join(@dir, "#{slug(docid)}.#{content_hash}.#{stage}.#{format}")
+      end
+
+      # Is this exact (document, input-closure, stage) artefact already present?
+      # This is the resumption / skip predicate: a hit is byte-identical to a
+      # fresh build because the hash covers every input that determines output.
+      def key?(docid, content_hash, stage)
+        File.exist?(path(docid, content_hash, stage))
+      end
+
+      def read(docid, content_hash, stage)
+        f = path(docid, content_hash, stage)
+        File.exist?(f) ? File.read(f, encoding: "UTF-8") : nil
+      end
+
+      # Idempotent write: the same (docid, content_hash, stage) always maps to
+      # the same path and the content is a pure function of the hash, so a re-run
+      # overwrites with identical bytes -- no side effects on repeat.
+      def write(docid, content_hash, stage, content)
+        f = path(docid, content_hash, stage)
+        File.write(f, content, encoding: "UTF-8")
+        f
+      end
+
+      # Remove every stored version of this document whose content hash is not
+      # +keep_hash+ -- the superseded artefacts left behind when the document's
+      # content changed. Keeps exactly one (current) version per document per
+      # stage, bounding disk to current state without losing the cache the next
+      # build resumes from.
+      def prune_superseded(docid, keep_hash)
+        STAGE_FORMATS.each do |stage, ext|
+          keep = path(docid, keep_hash, stage)
+          Dir[File.join(@dir, "#{slug(docid)}.*.#{stage}.#{ext}")].each do |f|
+            f == keep or File.delete(f)
+          end
+        end
+      end
+
+      # Wipe the entire store. The escape hatch when inputs the content hash
+      # cannot see -- imported EXPRESS schemas, templates, included files -- have
+      # changed, so the cache can no longer be trusted; the next build recompiles
+      # everything. Tracking such shared-input changes is the collection
+      # maintainer's responsibility, not the build's.
+      def clear
+        FileUtils.rm_rf(@dir)
+        FileUtils.mkdir_p(@dir)
+      end
+
+      # SHA256 over the input closure, truncated to 16 hex (64 bits -- ample for
+      # a per-collection store, and short enough to stay well inside filename
+      # length limits). Each input is hashed to a fixed-width digest and the
+      # digests concatenated before the final hash, so no two distinct closures
+      # collide on the pre-truncation digest. The caller assembles the closure;
+      # the store does not infer it.
+      def self.content_hash(*inputs)
+        digests = inputs.map { |i| Digest::SHA256.hexdigest(i.to_s) }
+        Digest::SHA256.hexdigest(digests.join)[0, 16]
+      end
+
+      private
+
+      def slug(docid)
+        docid.to_s.gsub(/[^A-Za-z0-9._-]+/, "-")
+          .gsub(/-{2,}/, "-").gsub(/\A-|-\z/, "")
+      end
+    end
+
+    # Null object: the store disabled (the default). Never reports a hit, never
+    # writes. Lets the renderer treat "no incremental build" as the no-store
+    # path without a conditional at every call site (open/closed).
+    class NullArtifactStore
+      def path(*_args) = nil
+      def key?(*_args) = false
+      def read(*_args) = nil
+      def write(*_args) = nil
+      def prune_superseded(*_args) = nil
+      def clear(*_args) = nil
+    end
+  end
+end

data/lib/metanorma/collection/filelookup/filelookup.rb

@@ -3,7 +3,6 @@ require "htmlentities"
 require "metanorma-utils"
 require "marcel"
 require_relative "filelookup_sectionsplit"
-require_relative "base"
 require_relative "utils"
 
 module Metanorma
@@ -57,17 +56,18 @@ module Metanorma
         entry = file_entry(manifest, k, idx) or return
         bibdata_process(entry, i)
         bibitem_process(entry)
-        @files[key(i)] = entry
+        @files[entry_key(i)] = entry
       end
 
       def read_file_idents(manifest)
         id = manifest.identifier
-        sanitised_id = key(@isodoc.docid_prefix("", manifest.identifier.dup))
+        sanitised_id =
+          entry_key(@isodoc.docid_prefix("", manifest.identifier.dup))
         #       if manifest.bibdata and # NO, DO NOT FISH FOR THE GENUINE IDENTIFIER IN BIBDATA
         #         d = manifest.bibdata.docidentifier.detect { |x| x.primary } ||
         #           manifest.bibdata.docidentifier.first
         #         k = d.id
-        #         i = key(@isodoc.docid_prefix(d.type, d.id.dup))
+        #         i = entry_key(@isodoc.docid_prefix(d.type, d.id.dup))
         #       end
         [id, sanitised_id]
       end
@@ -158,24 +158,10 @@ module Metanorma
         end
       end
 
-      # Substitute special strings in filename patterns
-      # @param pattern [String] filename pattern with placeholders
-      # @param options [Hash] substitution values
-      # @option options [Integer] :document_num document index
-      # @option options [String] :basename filename without extension
-      # @option options [String] :basename_legacy full filename with extension
-      # @option options [Integer] :sectionsplit_num sectionsplit index
+      # Substitute special strings in filename patterns.
+      # See Util.substitute_filename_pattern.
       def substitute_filename_pattern(pattern, options = {})
-        pattern or return pattern
-        result = pattern.dup
-        options[:document_num] and
-          result.gsub!(/\{document-num\}/, options[:document_num].to_s)
-        result.gsub!(/\{basename\}/, options[:basename]) if options[:basename]
-        options[:basename_legacy] and
-          result.gsub!(/\{basename_legacy\}/, options[:basename_legacy])
-        options[:sectionsplit_num] and
-          result.gsub!(/\{sectionsplit-num\}/, options[:sectionsplit_num].to_s)
-        result
+        Util.substitute_filename_pattern(pattern, options)
       end
 
       # TODO make the output file location reflect source location universally,

data/lib/metanorma/collection/filelookup/filelookup_sectionsplit.rb

@@ -18,7 +18,6 @@ module Metanorma
         # Save the original out_path before it gets modified
         original_out_path = @files[key][:out_path]
         s, sectionsplit_manifest = sectionsplit(key)
-        # section_split_instance_threads(s, manifest, key)
         s.each_with_index do |f1, i|
           add_section_split_instance(f1, manifest, key, i)
         end
@@ -29,18 +28,6 @@ module Metanorma
         original_out_path
       end
 
-      def section_split_instance_threads(s, manifest, key)
-        @mutex = Mutex.new
-        pool = Concurrent::FixedThreadPool.new(4)
-        s.each_with_index do |f1, i|
-          pool.post do
-            add_section_split_instance(f1, manifest, key, i)
-          end
-        end
-        pool.shutdown
-        pool.wait_for_termination
-      end
-
       def cleanup_section_split_instance(key, manifest, original_out_path)
         # Delete the sectionsplit index.html from source directory after it's copied to output
         @files_to_delete << manifest["#{key}:index.html"][:ref]
@@ -54,6 +41,14 @@ module Metanorma
         end
         # @files[key].delete(:ids).delete(:anchors)
         @files[key][:indirect_key] = @sectionsplit.key
+        # sectionsplit is HTML-only; hand the parent its whole Presentation XML
+        # so the collection PDF/presentation concatenation inlines the document
+        # intact (raw_file) instead of degrading to a bibdata-only, namespace-
+        # less stub. file_compile early-returns for sectionsplit, so this
+        # :outputs entry is what concatenate1 consumes.
+        # https://github.com/metanorma/iso-10303/issues/208
+        @files[key][:outputs] =
+          { presentation: @sectionsplit.whole_presentation_file }
       end
 
       def add_section_split_cover(manifest, sectionsplit_manifest, ident)
@@ -134,7 +129,7 @@ module Metanorma
         # file[:url] contains full path with directory for HTML output, but XML is basename only
         xml_basename = File.basename(file[:url])
         presfile = File.join(File.dirname(@files[key][:ref]), xml_basename)
-        newkey = key("#{key.strip} #{file[:title]}")
+        newkey = entry_key("#{key.strip} #{file[:title]}")
         xml = Nokogiri::XML(File.read(presfile), &:huge)
         [presfile, newkey, xml]
       end

data/lib/metanorma/collection/filelookup/utils.rb

@@ -1,56 +1,12 @@
 module Metanorma
   class Collection
     class FileLookup
-      # Also parse all ids in doc (including ones which won't be xref targets)
-      def read_ids(xml)
-        ret = {}
-        xml.traverse do |x|
-          x.text? and next
-          x["id"] and ret[x["id"]] = true
-        end
-        ret
-      end
-
-      # map locality type and label (e.g. "clause" "1") to id = anchor for
-      # a document
-      # Note: will only key clauses, which have unambiguous reference label in
-      # locality. Notes, examples etc with containers are just plunked against
-      # UUIDs, so that their IDs can at least be registered to be tracked
-      # as existing.
-      def read_anchors(xml)
-        xrefs = @isodoc.xref_init(@lang, @script, @isodoc, @isodoc.i18n,
-                                  { locale: @locale })
-        xrefs.parse xml
-        xrefs.get.each_with_object({}) do |(k, v), ret|
-          read_anchors1(k, v, ret)
-        end
-      end
-
-      def read_anchors1(key, val, ret)
-        val[:type] ||= "clause"
-        ret[val[:type]] ||= {}
-        index = if val[:container] || val[:label].nil? || val[:label].empty?
-                  UUIDTools::UUID.random_create.to_s
-                else val[:label].gsub(%r{<[^<>]+>}, "")
-                end
-        ret[val[:type]][index] = key
-        v = val[:value] and ret[val[:type]][v.gsub(%r{<[^<>]+>}, "")] = key
-      end
-
       def anchors_lookup(anchors)
         anchors.values.each_with_object({}) do |v, m|
           v.each_value { |v1| m[v1] = true }
         end
       end
 
-      # return citation url for file
-      # @param doc [Boolean] I am a Metanorma document,
-      # so my URL should end with html or pdf or whatever
-      def url(ident, options)
-        data = get(ident)
-        data[:url] || targetfile(data, options)[1]
-      end
-
       # are references to the file to be linked to a file in the collection,
       # or externally? Determines whether file suffix anchors are to be used
       def url?(ident)
@@ -58,7 +14,10 @@ module Metanorma
         data[:url]
       end
 
-      def key(ident)
+      # Normalise an identifier to its @files hash key: decode entities, squeeze
+      # whitespace, and strip a leading "metanorma-collection " prefix. Distinct
+      # from Util::key, which does NOT strip that prefix.
+      def entry_key(ident)
         @c.decode(ident).gsub(/(\p{Zs})+/, " ")
           .sub(/^metanorma-collection /, "")
       end
@@ -68,13 +27,13 @@ module Metanorma
       end
 
       def get(ident, attr = nil)
-        if attr then @files[key(ident)][attr]
-        else @files[key(ident)]
+        if attr then @files[entry_key(ident)][attr]
+        else @files[entry_key(ident)]
         end
       end
 
       def set(ident, attr, value)
-        @files[key(ident)][attr] = value
+        @files[entry_key(ident)][attr] = value
       end
 
       def each

data/lib/metanorma/collection/manifest/manifest.rb

@@ -20,6 +20,12 @@ module Metanorma
         @config = manifest_postprocess(config)
       end
 
+      # Ordered pipeline of in-place tree-walks over the manifest; the order is
+      # load-bearing. expand_yaml must run early because it grafts nested
+      # `fileref` manifests into this tree, so every later pass sees the full
+      # entry set; bibdata sets @lang/@script used downstream; compile_adoc
+      # turns .adoc sources into .xml before filexist verifies them. Each pass
+      # recurses the manifest independently (see the architecture review plan).
       def manifest_postprocess(config)
         manifest_bibdata(config)
         manifest_expand_yaml(config, @dir)

data/lib/metanorma/collection/renderer/fileparse.rb

@@ -14,24 +14,46 @@ module Metanorma
       # @param internal_refs [Hash{String=>Hash{String=>String}] schema name to
       #   anchor to filename
       # @return [String] XML content
+      # Each pass below mutates the SAME Nokogiri tree in place; the inline
+      # comments state the post-condition each pass guarantees on exit. The
+      # contract between passes is "the tree is now in state X" -- there is no
+      # intermediate typed representation, so the ordering is load-bearing.
+      # `sso` truthy (sectionsplit_output) => `xml` is Presentation XML and the
+      # semantic-only passes are skipped; otherwise `xml` is Semantic XML.
+      # See the pipeline map in the collection architecture review plan.
       def update_xrefs(file, docid, internal_refs)
         xml, sso = update_xrefs_prep(file, docid)
-        @nested || sso or
+        # post: repository docidentifiers supplied on bibitems naming a
+        # collection file; `sso` resolved (Presentation vs Semantic).
+        @nested || sso || @reinflate or
           Metanorma::Collection::XrefProcess::xref_process(xml, xml, nil, docid,
                                                            @isodoc, sso)
+        # post (semantic only): intra-doc xref/eref turned into internal erefs;
+        # repo bibitems copied; indirect bibliography inserted.
         @ncnames = {}
         @nested or update_indirect_refs_to_docs(xml, docid, internal_refs, sso)
-        @files.add_document_suffix(docid, xml)
+        # post: bibitem[@type='internal'] anchors resolved to the containing
+        # collection document.
+        @reinflate or @files.add_document_suffix(docid, xml)
+        # post: every @id/@anchor namespaced with this doc's NCName suffix, so
+        # concatenated documents do not collide.
         @nested or update_sectionsplit_refs_to_docs(xml, docid, internal_refs,
                                                     sso)
+        # post: erefs targeting a sectionsplit document point at the specific
+        # split section file that holds the anchor.
         update_direct_refs_to_docs(xml, docid, sso)
+        # post: repo(current-metanorma-collection/x) bibitems replaced in situ
+        # with resolved bibdata + citation URI; their erefs become hyperlinks.
         ::Metanorma::Collection::Util::hide_refs(xml)
+        # post: references containers with only hidden bibitems flagged hidden.
         sso and eref2link(xml, sso)
-        @nested or svgmap_resolve(xml, docid, sso)
+        @nested || @reinflate or svgmap_resolve(xml, docid, sso)
         xml.to_xml
       end
 
-      ## sso files are Presentation XML; otherwise, Semantic XML
+      ## sso (sectionsplit_output) truthy => Presentation XML, else Semantic.
+      ## This is the single discriminator that decides which grammar `xml`
+      ## carries and therefore which passes in update_xrefs run.
       def update_xrefs_prep(file, docid)
         docxml = file.is_a?(String) ? Nokogiri::XML(file, &:huge) : file
         supply_repo_ids(docxml)
@@ -121,8 +143,13 @@ presxml)
       # Do not do this if this is a sectionsplit collection or a nested manifest.
       # Return false if bibitem is not to be further processed
       def strip_unresolved_repo_erefs(_document_id, bib_docid, erefs, bibitem)
-        %r{^current-metanorma-collection/(?!Missing:)}.match?(bib_docid.text) and
+        if %r{^current-metanorma-collection/(?!Missing:)}.match?(bib_docid.text)
+          # Isolated build: keep the cross-document ref as a stub (its bibitemid
+          # and repository docidentifier intact) for a later reinflation pass to
+          # relink, rather than resolving it now against an absent target.
+          @preserve_unresolved and return false
           return true
+        end
         @nested and return false
         erefs[bibitem["id"]]&.each { |x| x.parent and strip_eref(x) }
         false

data/lib/metanorma/collection/renderer/fileprocess.rb

@@ -4,6 +4,8 @@ require "isodoc"
 require "metanorma-utils"
 require_relative "fileparse"
 require_relative "filelocation"
+require_relative "../artifact_store"
+require "json"
 
 module Metanorma
   class Collection
@@ -67,8 +69,11 @@ module Metanorma
           if @files.get(ident, :attachment) then copy_file_to_dest(ident)
           else
             file, fname = @files.targetfile_id(ident, read: true)
+            @preserve_unresolved && member_stored?(ident, file) and next
             warn "\n\n\n\n\nProcess #{fname}: #{DateTime.now.strftime('%H:%M:%S')}"
             collection_xml = update_xrefs(file, ident, internal_refs)
+            @preserve_unresolved and
+              store_member_artefacts(ident, file, collection_xml)
             # Strip .xml or .html extension, but NOT section numbers like .0
             fname_base = File.basename(fname)
             collection_filename = fname_base
@@ -83,6 +88,31 @@ module Metanorma
         end
       end
 
+      # Persist an isolated member's stub-bearing Semantic XML and its anchor
+      # contribution to the content-addressed store, so a later reinflation pass
+      # can relink the stubs and a re-run can resume without recompiling.
+      # Within-campaign content key for a member. (Cross-build soundness needs
+      # the full input closure -- source + includes + templates + schemas +
+      # versions; see the plan gotcha. Here the source bytes + tool version
+      # suffice because inputs are frozen across a single build campaign.)
+      def member_content_hash(source)
+        ArtifactStore.content_hash(source, ::Metanorma::VERSION)
+      end
+
+      # Resume predicate: is this member already compiled and stored for its
+      # current input content? If so the isolated compile can skip it.
+      def member_stored?(ident, source)
+        @artifact_store.key?(ident, member_content_hash(source), :semantic)
+      end
+
+      def store_member_artefacts(ident, source, semantic_xml)
+        hash = member_content_hash(source)
+        @artifact_store.write(ident, hash, :semantic, semantic_xml)
+        @artifact_store.write(ident, hash, :anchors,
+                              JSON.generate(@files.get(ident, :anchors) || {}))
+        @keep_cache or @artifact_store.prune_superseded(ident, hash)
+      end
+
       # gather internal bibitem references
       def gather_internal_refs
         @files.keys.each_with_object({}) do |i, refs|
@@ -183,22 +213,53 @@ module Metanorma
       def update_bibitem_prep(bib, identifier)
         docid = get_bibitem_docid(bib, identifier) or return [nil, nil]
         newbib = dup_bibitem(docid, bib)
-        url = @files.url(docid, relative: true,
-                                doc: !@files.get(docid, :attachment))
-        # Use :outputs[:html] if available (after compilation),
-        # otherwise convert :out_path to HTML (before compilation)
-        current_html = @files.get(identifier, :outputs)&.dig(:html)
-        if !current_html && (out_path = @files.get(identifier, :out_path))
-          # Convert .xml to .html, following same logic as ref_file_xml2html
-          current_html = if out_path.end_with?(".xml")
-                           out_path.sub(/\.xml$/, ".html")
-                         else
-                           "#{out_path}.html"
-                         end
-        end
+        attachment = @files.get(docid, :attachment)
+        url = @files.url(docid, relative: true, doc: !attachment)
+        current_html = referencing_html_location(identifier, attachment)
         url = make_relative_path(current_html, url) if current_html
         [newbib, url]
       end
+
+      # Location of the HTML that will carry the cross-reference to the target,
+      # used as the base for relativising the attachment/citation URL.
+      #
+      # Normally this is the referencing document's own output (:outputs[:html]
+      # after compilation, else :out_path converted to .html before it).
+      #
+      # But when the referencing document is sectionsplit, its content is not
+      # emitted at its own out_path: it is split into section files written at
+      # the sectionsplit output location (the collection root, unless a
+      # sectionsplit_filename directory is configured). Relativising an
+      # attachment URL against the unsplit out_path then overshoots -- the
+      # ../../ climbs above the split file and the attachment link breaks
+      # (https://github.com/metanorma/iso-10303/issues/208). So for attachment
+      # targets of a sectionsplit document, base the relative path on the
+      # sectionsplit output directory instead.
+      def referencing_html_location(identifier, attachment)
+        attachment && @files.get(identifier, :sectionsplit) and
+          return sectionsplit_ref_html(identifier)
+        document_ref_html(identifier)
+      end
+
+      # The split section files sit at the sectionsplit output directory: the
+      # collection root, or the directory of a configured sectionsplit_filename.
+      def sectionsplit_ref_html(identifier)
+        d = @files.preserve_directory_structure?(identifier)
+        d ? File.join(File.dirname(d), "x.html") : "x.html"
+      end
+
+      # Use :outputs[:html] if available (after compilation), otherwise convert
+      # :out_path to HTML (before compilation), following ref_file_xml2html.
+      def document_ref_html(identifier)
+        @files.get(identifier, :outputs)&.dig(:html) ||
+          out_path_to_html(@files.get(identifier, :out_path))
+      end
+
+      def out_path_to_html(out_path)
+        out_path or return nil
+        out_path.end_with?(".xml") and return out_path.sub(/\.xml$/, ".html")
+        "#{out_path}.html"
+      end
     end
   end
 end