metanorma 2.0.0 → 2.5.5

data/lib/metanorma/collection/sectionsplit/sectionsplit.rb

@@ -1,11 +1,30 @@
 require "yaml"
-require_relative "../../util/util"
+require "fileutils"
+require "metanorma-core"
 require_relative "../xrefprocess/xrefprocess"
+require_relative "collection"
+require "concurrent-ruby"
 
 module Metanorma
   class Collection
+    # Sectionsplit is a collection render nested inside a collection render:
+    # a document is split into one output file per section, and those files are
+    # then rendered as their own (sub-)collection.
+    #
+    # Two output-location invariants matter (both load-bearing -- see the
+    # collection architecture review plan and metanorma/iso-10303#208):
+    #
+    # * XML section files are always written FLAT to the split directory
+    #   (basename only). HTML output may instead carry a directory taken from
+    #   sectionsplit_filename, reattached only at HTML compile time
+    #   (preserve_directory_structure?).
+    # * A sectionsplit document's content is emitted at the sectionsplit output
+    #   location (the collection root, unless sectionsplit_filename sets a
+    #   directory), NOT at the document's own :out_path. Anything relativising a
+    #   URL for such a document (e.g. attachment/citation links) must base it on
+    #   the split location, or the ../../ overshoots.
     class Sectionsplit
-      attr_accessor :filecache, :key
+      attr_accessor :filecache, :key, :whole_presentation_file
 
       def initialize(opts)
         @input_filename = opts[:input]
@@ -17,71 +36,76 @@ module Metanorma
         @fileslookup = opts[:fileslookup]
         @ident = opts[:ident]
         @isodoc = opts[:isodoc]
+        @isodoc_presxml = opts[:isodoc_presxml]
+        @document_suffix = opts[:document_suffix]
+        @sectionsplit_filename = opts[:sectionsplit_filename] ||
+          "{basename_legacy}.{sectionsplit-num}"
+        @parent_idx = opts[:parent_idx] || 0
       end
 
       def ns(xpath)
         @isodoc.ns(xpath)
       end
 
-      def build_collection
-        collection_setup(@base, @dir)
-        files = sectionsplit # (@input_filename, @base, @dir, @compile_opts)
-        input_xml = Nokogiri::XML(File.read(@input_filename,
-                                            encoding: "UTF-8"), &:huge)
-        collection_manifest(@base, files, input_xml, @xml, @dir).render(
-          { format: %i(html), output_folder: "#{@output_filename}_collection",
-            coverpage: File.join(@dir, "cover.html") }.merge(@compile_opts),
-        )
-      end
-
-      def collection_manifest(filename, files, origxml, _presxml, dir)
-        File.open(File.join(dir, "#{filename}.html.yaml"), "w:UTF-8") do |f|
-          f.write(collectionyaml(files, origxml))
-        end
-        Metanorma::Collection.parse File.join(dir, "#{filename}.html.yaml")
-      end
-
-      def collection_setup(filename, dir)
-        FileUtils.mkdir_p "#{filename}_collection" if filename
-        FileUtils.mkdir_p dir
-        File.open(File.join(dir, "cover.html"), "w:UTF-8") do |f|
-          f.write(coll_cover)
-        end
-      end
-
-      def coll_cover
-        <<~COVER
-          <html><head><meta charset="UTF-8"/></head><body>
-                <h1>{{ doctitle }}</h1>
-                <h2>{{ docnumber }}</h2>
-                <nav>{{ navigation }}</nav>
-              </body></html>
-        COVER
-      end
-
       SPLITSECTIONS =
         [["//preface/*", "preface"], ["//sections/*", "sections"],
          ["//annex", nil],
          ["//bibliography/*[not(@hidden = 'true')]", "bibliography"],
          ["//indexsect", nil], ["//colophon", nil]].freeze
 
-      # Input XML is Semantic
-      # def sectionsplit(filename, basename, dir, compile_options, fileslookup = nil, ident = nil)
+      # Input XML is Semantic XML
       def sectionsplit
         xml = sectionsplit_prep(File.read(@input_filename), @base, @dir)
+        # Retain the whole (un-split) Presentation XML. sectionsplit is an
+        # HTML-only mechanism, but the collection PDF/presentation path must
+        # inline each document intact; without this the sectionsplit parent
+        # reaches concatenation with no presentation output and degrades to a
+        # bibdata-only, namespace-less <metanorma> stub that mn2pdf drops.
+        # https://github.com/metanorma/iso-10303/issues/208
+        @whole_presentation_file = write_whole_presentation(xml)
         @key = Metanorma::Collection::XrefProcess::xref_preprocess(xml, @isodoc)
-        SPLITSECTIONS.each_with_object([]) do |n, ret|
+        empty = empty_doc(xml)
+        empty1 = empty_attachments(empty)
+        @mutex = Mutex.new
+        # @pool = Concurrent::FixedThreadPool.new(4)
+        @pool = Concurrent::FixedThreadPool.new(1)
+        sectionsplit1(xml, empty, empty1, 0)
+      end
+
+      # xml is Presentation XML
+      def sectionsplit1(xml, empty, empty1, idx)
+        ret = SPLITSECTIONS.each_with_object([]) do |n, m|
           conflate_floatingtitles(xml.xpath(ns(n[0]))).each do |s|
-            ret << sectionfile(xml, emptydoc(xml), "#{@base}.#{ret.size}", s,
-                               n[1])
+            # require "debug"; binding.b
+            sectionsplit2(xml, idx.zero? ? empty : empty1, s, n[1],
+                          { acc: m, idx: idx })
+            idx += 1
           end
         end
+        @pool.shutdown
+        @pool.wait_for_termination
+        ret
       end
 
+      def sectionsplit2(xml, empty, chunks, parentnode, opt)
+        @pool.post do
+          output_filename = Util.substitute_filename_pattern(
+            @sectionsplit_filename,
+            document_num: @parent_idx, basename: File.basename(@base, ".*"),
+            basename_legacy: @base, sectionsplit_num: opt[:idx]
+          )
+          warn "Sectionsplit: #{output_filename}"
+          a = sectionfile(xml, empty, output_filename, chunks,
+                          parentnode)
+          @mutex.synchronize { opt[:acc] << a }
+        end
+      end
+
+      # TODO move to metanorma-utils
       def block?(node)
         %w(p table formula admonition ol ul dl figure quote sourcecode example
-           pre note pagebrreak hr bookmark requirement recommendation permission
-           svgmap inputform toc passthrough review imagemap).include?(node.name)
+           pre note pagebreak hr bookmark requirement recommendation permission
+           svgmap inputform toc passthrough annotation imagemap).include?(node.name)
       end
 
       def conflate_floatingtitles(nodes)
@@ -96,53 +120,69 @@ module Metanorma
 
       def sectionsplit_prep(file, filename, dir)
         @splitdir = dir
-        xml1filename, type = sectionsplit_preprocess_semxml(file, filename)
-        Compile.new.compile(
-          xml1filename,
-          { format: :asciidoc, extension_keys: [:presentation], type: type }
-         .merge(@compile_opts),
-        )
-        Nokogiri::XML(File.read(xml1filename.sub(/\.xml$/, ".presentation.xml"),
-                                encoding: "utf-8"), &:huge)
+        xml, type = sectionsplit_preprocess_semxml(file, filename)
+        flags = { format: :asciidoc, extension_keys: [:presentation],
+                  type: type }.merge(@compile_opts)
+        Compile.new.compile(xml, flags)
+        f = File.open(xml.sub(/\.xml$/, ".presentation.xml"), encoding: "utf-8")
+        r = Nokogiri::XML(f, &:huge)
+        f.close
+        r.xpath("//xmlns:svgmap1").each { |x| x.name = "svgmap" }
+        r
+      end
+
+      # Persist the whole, svgmap-restored Presentation XML (the in-memory doc,
+      # not the on-disk tmp which still carries the internal svgmap1 marker) so
+      # the collection PDF path can inline the document whole. Written flat to
+      # the split output directory, where the per-section files also live.
+      def write_whole_presentation(xml)
+        fname = File.join(@splitdir, "#{@base}.whole.presentation.xml")
+        File.write(fname, xml.to_xml, encoding: "UTF-8")
+        fname
       end
 
       def sectionsplit_preprocess_semxml(file, filename)
         xml = Nokogiri::XML(file, &:huge)
-        type = xml.root.name.sub("-standard", "").to_sym
+        type = xml.root["flavor"]
+        type ||= xml.root.name.sub("-standard", "").to_sym
         sectionsplit_update_xrefs(xml)
         xml1 = sectionsplit_write_semxml(filename, xml)
-        @filecache ||= []
-        @filecache << xml1
-        [xml1.path, type]
+        @tmp_filename = xml1
+        [xml1, type]
       end
 
       def sectionsplit_update_xrefs(xml)
         if c = @fileslookup&.parent
-          n = c.nested
-          c.nested = true # so unresolved erefs are not deleted
-          c.update_xrefs(xml, @ident, {})
-          c.nested = n
+          # nested mode so unresolved erefs are not deleted
+          c.with_nested { c.update_xrefs(xml, @ident, {}) }
+          xml.xpath("//xmlns:svgmap").each { |x| x.name = "svgmap1" }
+          # do not process svgmap until after files are split
         end
       end
 
       def sectionsplit_write_semxml(filename, xml)
-        Tempfile.open([filename, ".xml"], encoding: "utf-8") do |f|
-          # f.write(@isodoc.to_xml(svg_preprocess(xml)))
+        outname = Pathname.new("tmp_#{filename}").sub_ext(".xml").to_s
+        File.open(outname, "w:UTF-8") do |f|
           f.write(@isodoc.to_xml(xml))
-          f
         end
+        outname
       end
 
-      def emptydoc(xml)
+      def empty_doc(xml)
         out = xml.dup
         out.xpath(
-          ns("//preface | //sections | //annex | //bibliography/clause | " \
-             "//bibliography/references[not(@hidden = 'true')] | //indexsect | " \
-             "//colophon"),
+          ns("//preface | //sections | //annex | " \
+          "//references/bibitem[not(@hidden = 'true')] | " \
+          "//indexsect | //colophon"),
         ).each(&:remove)
+        ::Metanorma::Collection::Util::hide_refs(out)
         out
       end
 
+      def empty_attachments(xml)
+        xml.dup
+      end
+
       def sectionfile(fulldoc, xml, file, chunks, parentnode)
         fname = create_sectionfile(fulldoc, xml.dup, file, chunks, parentnode)
         { order: chunks.last["displayorder"].to_i, url: fname,
@@ -152,12 +192,17 @@ module Metanorma
       def create_sectionfile(xml, out, file, chunks, parentnode)
         ins = out.at(ns("//metanorma-extension")) || out.at(ns("//bibdata"))
         sectionfile_insert(ins, chunks, parentnode)
-        Metanorma::Collection::XrefProcess::xref_process(out, xml, @key, @ident, @isodoc)
-        outname = "#{file}.xml"
-        File.open(File.join(@splitdir, outname), "w:UTF-8") do |f|
-          f.write(out)
-        end
-        outname
+        sectionfile_fn_filter(sectionfile_annotation_filter(out))
+        Metanorma::Collection::XrefProcess::xref_process(out, xml, @key,
+                                                         @ident, @isodoc, true)
+        # XML files are always written flat to the splitdir (_files directory)
+        # Directory structure from sectionsplit_filename is only used for HTML output
+        xml_filename = "#{File.basename(file)}.xml"
+        full_path = File.join(@splitdir, xml_filename)
+        File.open(full_path, "w:UTF-8") { |f| f.write(out) }
+        # Return full file path (with directory) for use in manifest
+        # This preserves directory info for HTML rendering without affecting XML storage
+        "#{file}.xml"
       end
 
       def sectionfile_insert(ins, chunks, parentnode)
@@ -168,50 +213,88 @@ module Metanorma
         end
       end
 
+      def sectionfile_fn_filter(xml)
+        ids = sectionfile_fn_filter_prep(xml)
+        xml.root.xpath(ns("./fmt-footnote-container/fmt-fn-body")).each do |f|
+          ids.has_key?(f["id"]) or f.remove
+        end
+        seen = {}
+        xml.root.xpath(ns("/fmt-footnote-container/fmt-fn-body"))
+          .each_with_index do |fnbody, i|
+            sectionfile_fn_filter_renumber(fnbody, i, ids, seen)
+          end
+        xml
+      end
+
+      # map fmt-fn-body/@id = fn/@target to fn
+      def sectionfile_fn_filter_prep(xml)
+        xml.xpath(ns("//fn")).each_with_object({}) do |f, m|
+          m[f["target"]] ||= []
+          m[f["target"]] << f
+        end
+      end
+
+      FN_CAPTIONS = ".//fmt-fn-label/span[@class = 'fmt-caption-label']".freeze
+
+      def sectionfile_fn_filter_renumber(fnbody, idx, ids, seen)
+        sectionfile_fn_filter_fn_renumber(fnbody, idx, ids, seen)
+        sectionfile_fn_filter_fnbody_renumber(fnbody, idx, ids)
+      end
+
+      def sectionfile_fn_filter_fn_renumber(fnbody, idx, ids, seen)
+        ids[fnbody["id"]].each do |f|
+          @isodoc_presxml.renumber_document_footnote(f, idx, seen)
+          fnlabel = f.at(ns(FN_CAPTIONS)) and
+            fnlabel.children = @isodoc_presxml.fn_ref_label(f)
+        end
+      end
+
+      def sectionfile_fn_filter_fnbody_renumber(fnbody, _idx, ids)
+        fnlabel = fnbody.at(ns(FN_CAPTIONS)) or return
+        fnbody["reference"] = ids[fnbody["id"]].first["reference"]
+        fnlabel.children = @isodoc_presxml.fn_body_label(fnbody)
+      end
+
+      # map fmt-annotation-body/@id = fmt-annotation-{start/end}/@target
+      # to fmt-annotation-{start/end}
+      def sectionfile_annotation_filter_prep(xml)
+        xml.xpath(ns("//fmt-annotation-start | //fmt-annotation-end"))
+          .each_with_object({}) do |f, m|
+            m[f["target"]] ||= []
+            m[f["target"]] << f
+          end
+      end
+
+      def sectionfile_annotation_filter(xml)
+        ids = sectionfile_annotation_filter_prep(xml)
+        xml.root.xpath(ns("./annotation-container/fmt-annotation-body"))
+          .each do |f|
+          ids.has_key?(f["id"]) or f.remove
+        end
+        xml.root.xpath(ns("./annotation-container/fmt-annotation-body"))
+          .each_with_index do |fnbody, i|
+            sectionfile_annotation_filter_renumber(fnbody, i, ids)
+          end
+        xml
+      end
+
+      def sectionfile_annotation_filter_renumber(fnbody, _idx, ids)
+        ids[fnbody["id"]].each do |f|
+          case f.name
+          when "fmt-annotation-start"
+            f.children = @isodoc_presxml.comment_bookmark_start_label(f)
+          when "fmt-annotation-end"
+            f.children = @isodoc_presxml.comment_bookmark_end_label(f)
+          end
+        end
+      end
+
       def titlerender(section)
-        title = section.at(ns("./title")) or return "[Untitled]"
+        title = section.at(ns("./fmt-title")) or return "[Untitled]"
         t = title.dup
         t.xpath(ns(".//tab | .//br")).each { |x| x.replace(" ") }
-        t.xpath(ns(".//strong")).each { |x| x.replace(x.children) }
-        t.children.to_xml
-      end
-
-      def collectionyaml(files, xml)
-        ret = {
-          directives: ["presentation-xml", "bare-after-first"],
-          bibdata: {
-            title: {
-              type: "title-main", language: @lang,
-              content: xml.at(ns("//bibdata/title")).text
-            },
-            type: "collection",
-            docid: {
-              type: xml.at(ns("//bibdata/docidentifier/@type")).text,
-              id: xml.at(ns("//bibdata/docidentifier")).text,
-            },
-          },
-          manifest: {
-            level: "collection", title: "Collection",
-            docref: files.sort_by { |f| f[:order] }.each.map do |f|
-              { fileref: f[:url], identifier: f[:title] }
-            end
-          },
-        }
-        ::Metanorma::Util::recursive_string_keys(ret).to_yaml
-      end
-
-      def section_split_cover(col, ident, _one_doc_coll)
-        dir = File.dirname(col.file)
-        collection_setup(nil, dir)
-        r = ::Metanorma::Collection::Renderer
-          .new(col, dir, output_folder: "#{ident}_collection",
-                         format: %i(html), coverpage: File.join(dir, "cover.html"))
-        r.coverpage
-        # filename = one_doc_coll ? "#{ident}_index.html" : "index.html"
-        filename = File.basename("#{ident}_index.html") # ident can be a directory with YAML indirection
-        FileUtils.mv File.join(r.outdir, "index.html"), File.join(dir, filename)
-        FileUtils.rm_rf r.outdir
-        filename
+        t.xpath(ns(".//bookmark")).each(&:remove)
+        t.xpath(".//text()").map(&:text).join
       end
     end
   end

data/lib/metanorma/collection/util/disambig_files.rb

@@ -10,13 +10,12 @@ module Metanorma
           name.sub(%r{^(\./)?(\.\./)+}, "")
         end
 
-        def source2dest_filename(name, disambig = true)
+        def source2dest_filename(name, disambig: true, preserve_dirs: false)
           n = strip_root(name)
-          dir = File.dirname(n)
-          base = File.basename(n)
-          if disambig && @seen_filenames.include?(base)
+          dir = preserve_dirs ? "." : File.dirname(n)
+          base = preserve_dirs ? n : File.basename(n)
+          disambig && @seen_filenames.include?(base) and
             base = disambiguate_filename(base)
-          end
           @seen_filenames << base
           dir == "." ? base : File.join(dir, base)
         end

data/lib/metanorma/collection/util/util.rb

@@ -1,42 +1,57 @@
+require "marcel"
+
 module Metanorma
   class Collection
     module Util
       class << self
+        def mime_file_recognised?(filename)
+          mime_type = Marcel::MimeType.for name: filename
+          mime_type != "application/octet-stream"
+        end
+
+        def anchor_id_attributes
+          Metanorma::Utils::anchor_attributes(presxml: true) +
+            [%w(* id), %w(* anchor), %w(link bibitemid), %w(fmt-link bibitemid)]
+        end
+
         def gather_bibitems(xml)
           xml.xpath("//xmlns:bibitem[@id]").each_with_object({}) do |b, m|
-            if m[b["id"]]
+            id = b["anchor"] || b["id"]
+            if m[id]
               b.remove
               next
               # we can't update duplicate bibitem, processing updates wrong one
             else
-              m[b["id"]] = b
+              m[id] = b
             end
           end
         end
 
-        def gather_bibitemids(xml)
+        def gather_bibitemids(xml, presxml)
           xml.xpath("//*[@bibitemid]").each_with_object({}) do |e, m|
-            /^semantic__/.match?(e.name) and next
+            presxml && %w(xref eref link).include?(e.name) and next
             m[e["bibitemid"]] ||= []
             m[e["bibitemid"]] << e
           end
         end
 
-        def gather_citeases(xml)
+        def gather_citeases(xml, presxml)
           xml.xpath("//*[@citeas]").each_with_object({}) do |e, m|
-            /^semantic__/.match?(e.name) and next
-            m[e["citeas"]] ||= []
-            m[e["citeas"]] << e
+            presxml && %w(xref eref link).include?(e.name) and next
+            k = key(e["citeas"])
+            m[k] ||= []
+            m[k] << e
           end
         end
 
-        def add_suffix_to_attributes(doc, suffix, tag_name, attr_name,
-isodoc)
+        # Skip SVGs, they are processed by Vectory::SvgDocument#suffix_ids
+        def add_suffix_to_attrs(doc, suffix, tag, attr, isodoc)
           (suffix.nil? || suffix.empty?) and return
-          doc.xpath(isodoc.ns("//#{tag_name}[@#{attr_name}]")).each do |elem|
-            a = elem.attributes[attr_name].value
+          doc.xpath(isodoc.ns("//#{tag}[@#{attr}][not(ancestor-or-self::*[local-name()='svg'])]")).each do |elem|
+            # doc.xpath(isodoc.ns("//#{tag}[@#{attr}]")).each do |elem|
+            a = elem.attributes[attr].value
             /_#{suffix}$/.match?(a) or
-              elem.attributes[attr_name].value = "#{a}_#{suffix}"
+              elem.attributes[attr].value = "#{a}_#{suffix}"
           end
         end
 
@@ -53,18 +68,140 @@ isodoc)
           p.absolute? ? path : File.join(dir, path)
         end
 
+        def hide_refs(docxml)
+          p = "//xmlns:references[xmlns:bibitem]"\
+            "[not(./xmlns:bibitem[not(@hidden) or @hidden = 'false'])]"
+          docxml.xpath(p).each do |f|
+            f["hidden"] = "true"
+          end
+        end
+
         def key(ident)
           @c ||= HTMLEntities.new
           @c.decode(ident).gsub(/(\p{Zs})+/, " ")
         end
 
-        class Dummy
-          def attr(_key); end
+        # Substitute special strings in filename patterns. Single source for
+        # both FileLookup#substitute_filename_pattern and sectionsplit.
+        # @param pattern [String] filename pattern with placeholders
+        # @param options [Hash] substitution values:
+        #   :document_num, :basename, :basename_legacy, :sectionsplit_num
+        def substitute_filename_pattern(pattern, options = {})
+          pattern or return pattern
+          subs = { "{document-num}" => options[:document_num],
+                   "{basename}" => options[:basename],
+                   "{basename_legacy}" => options[:basename_legacy],
+                   "{sectionsplit-num}" => options[:sectionsplit_num] }
+          subs.each_with_object(pattern.dup) do |(token, val), result|
+            val and result.gsub!(token, val.to_s)
+          end
+        end
+
+        def taste2flavor(taste)
+          ::Metanorma::Core::FlavorLoader.taste2flavor(taste)
+        end
+
+        def taste2isodoc_attrs(taste, format)
+          tastes = Metanorma::TasteRegister.instance.aliases
+          tastes[taste.to_sym] or return {}
+          Metanorma::TasteRegister.isodoc_attrs(taste.to_sym, format)
+        end
+
+        def taste2coverpage_pdf_portfolio(taste)
+          tastes = Metanorma::TasteRegister.instance.aliases
+          tastes[taste.to_sym] or return nil
+          taste = Metanorma::TasteRegister.instance.get(taste.to_sym)
+          ret = taste.config.base_override&.filename_attributes
+            &.coverpage_pdf_portfolio or return
+          File.join(taste.directory, ret)
+        end
+
+        SVG_NS = "http://www.w3.org/2000/svg".freeze
+
+        # update relative URLs, url(#...), in CSS in @style attrs (incl. SVG),
+        # and in include SVG url(#..) attrs,
+        # not processed already by add_suffix_to_attrs
+        def url_in_css_styles(doc, ids, document_suffix)
+          update_ids_css(doc.root, ids, document_suffix)
+          doc.xpath("//i:svg", "i" => SVG_NS).each do |s|
+            svg = Vectory::SvgDocument.new(s.to_xml)
+            svg.suffix_ids(document_suffix)
+          end
+        end
+
+        # replicates Vectory update_ids_css, but skips over svgs,
+        # which are processed separately by Vectory::SvgDocument#suffix_ids
+        def update_ids_css(document, ids, suffix)
+          suffix = suffix.is_a?(Integer) ? sprintf("%09d", suffix) : suffix
+          document.xpath(".//m:style[not(ancestor::i:svg)]",
+                         "m" => SVG_NS, "i" => SVG_NS).each do |s|
+            s.children = update_ids_css_string(s.children.to_xml, ids, suffix)
+          end
+          document.xpath(".//*[@style][not(ancestor::i:svg)]",
+                         "i" => SVG_NS).each do |s|
+            s["style"] = update_ids_css_string(s["style"], ids, suffix)
+          end
+        end
+
+        # Updates ID references in a CSS style string.
+        # Replicates Vectory update_ids_css_string
+        def update_ids_css_string(style, ids, suffix)
+          ids.each do |i|
+            style = style.gsub(%r[##{i}\b],
+                               sprintf("#%<id>s_%<suffix>s", id: i,
+                                                             suffix: suffix))
+              .gsub(%r(\[id\s*=\s*['"]?#{i}['"]?\]),
+                    sprintf("[id='%<id>s_%<suffix>s']", id: i,
+                                                        suffix: suffix))
+          end
+          style
+        end
+
+        #           doc.xpath("//*[@style]").each do |s|
+        #             s["style"] = url_in_css_styles1(s["style"], document_suffix)
+        #           end
+        #           doc.xpath("//i:svg//i:style", "i" => "http://www.w3.org/2000/svg")
+        #             .each do |s|
+        #               s.children = url_in_css_styles1(s.text, document_suffix)
+        #           end
+        #
+        #         # KILL
+        #         def url_in_css_styles1(style, document_suffix)
+        #           style.gsub(%r{url\(#([^()]+)\)}, "url(#\\1_#{document_suffix})")
+        #         end
+
+        # @deprecated Call Metanorma::Core::Isodoc.resolve_converter directly.
+        def load_isodoc(flavor, presxml: false)
+          Metanorma::Core::Isodoc.resolve_converter(flavor, presxml: presxml)
+        end
+
+        # @deprecated Call Metanorma::Core::Isodoc.create directly. Kept as
+        #   a back-compat shim so existing callers keep working unchanged
+        #   while the wrapper is retired.
+        def isodoc_create(flavor, lang, script, xml, presxml: false)
+          Metanorma::Core::Isodoc.create(flavor, lang: lang, script: script,
+                                                 xml: xml, presxml: presxml)
+        end
+
+        # Dummy asciidoc header used by the prefatory-content parse so we
+        # can run Asciidoctor against arbitrary text. If +docidentifier+
+        # is supplied, it is injected as +:docidentifier:+ so the flavor
+        # processor's metadata_id has a real value to put into the
+        # bibdata, instead of falling back to its (Liquid-templated)
+        # docid_template. This prevents the prefatory parse from feeding
+        # an unresolved Liquid template through Relaton/pubid in flavors
+        # whose relaton-* gem eagerly parses the docidentifier in
+        # content= (issue #558).
+        def asciidoc_dummy_header(docidentifier: nil)
+          attrs = docidentifier ? ":docidentifier: #{docidentifier}\n" : ""
+          "= X\nA\n#{attrs}\n"
         end
 
-        def load_isodoc(doctype)
-          x = Asciidoctor.load nil, backend: doctype.to_sym
-          x.converter.html_converter(Dummy.new) # to obtain Isodoc class
+        def nokogiri_to_temp(xml, filename, suffix)
+          file = Tempfile.new([filename, suffix])
+          file.write(xml.to_xml(indent: 0))
+          file.close
+          [file, file.path]
         end
       end
     end