metanorma-document 0.2.12 → 0.2.13

data/lib/metanorma/html/templates/_footnotes.html.liquid

@@ -1,11 +1,11 @@
 <section class="footnotes-section" aria-label="Footnotes">
 <h2 class="footnotes-title">Footnotes</h2>
-<div class="footnotes">
+<ol class="footnotes">
 {% for entry in footnotes %}
-<div id="footnote-{{ entry.number }}" class="footnote">
-<a href="#fnref-{{ entry.number }}" class="footnote-backref" aria-label="Back to reference">&#x21A9;</a><span class="footnote-label">{{ entry.label }}</span>
-{{ entry.content_html }}
-</div>
+<li id="footnote-{{ entry.number }}" class="footnote">
+<a href="#fnref-{{ entry.number }}" class="footnote-backref">
+<sup>{{ entry.reference | escape }}</sup></a> {{ entry.content_html }}
+</li>
 {% endfor %}
-</div>
+</ol>
 </section>

data/lib/metanorma/html/templates/_formula.html.liquid

@@ -1,6 +1,6 @@
 <div{% if block.id %} id="{{ block.id }}"{% endif %} class="{{ block.css_class }}">
 {{ block.stem_html }}
-{% if block.where_label %}<p class="formula-where">where,</p>{% endif %}
+{% if block.where_html %}<p class="formula-where">where</p>{% endif %}
 {{ block.where_html }}
 {% if block.number_html %}<span class="formula-number">{{ block.number_html }}</span>{% endif %}
 </div>

data/lib/metanorma/html/templates/_header.html.liquid

@@ -12,7 +12,7 @@
     </button>
     <div class="header-settings">
       <button class="reader-btn settings-toggle" id="settings-toggle" aria-label="Reader settings" title="Settings">
-        <svg viewBox="0 0 20 20" fill="currentColor"><path fill-rule="evenodd" d="M7.84 1.804A1 1 0 0 1 8.82 1h2.36a1 1 0 0 1 .98.804l.331 1.652a6.994 6.994 0 0 1 1.929 1.115l1.598-.54a1 1 0 0 1 1.186.447l1.18 2.044a1 1 0 0 1-.205 1.251l-1.267 1.113a7.047 7.047 0 0 1 0 2.228l1.267 1.113a1 1 0 0 1 .206 1.25l-1.18 2.045a1 1 0 0 1-1.187.447l-1.598-.54a6.994 6.994 0 0 1-1.929 1.115l-.33 1.652a1 1 0 0 1-.98.804H8.82a1 1 0 0 1-.98-.804l-.331-1.652a6.994 6.994 0 0 1-1.929-1.115l-1.598.54a1 1 0 0 1-1.186-.447l-1.18-2.044a1 1 0 0 1 .205-1.251l1.267-1.114a7.05 7.05 0 0 1 0-2.227L1.821 7.773a1 1 0 0 1-.206-1.25l1.18-2.045a1 1 0 0 1 1.187-.447l1.598.54A6.994 6.994 0 0 1 7.51 3.456l.33-1.652ZM10 13a3 3 0 1 0 0-6 3 3 0 0 0 0 6Z" clip-rule="evenodd"/></svg>
+        <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"><circle cx="8" cy="8" r="1.5"/><path d="M8 1v2M8 13v2M1 8h2M13 8h2M3.05 3.05l1.41 1.41M11.54 11.54l1.41 1.41M3.05 12.95l1.41-1.41M11.54 4.46l1.41-1.41"/></svg>
       </button>
       <div class="settings-dropdown" id="settings-dropdown">
         <button class="reader-btn font-decrease" id="font-decrease" aria-label="Decrease font size" title="Smaller text">

data/lib/metanorma/html/templates/_iso_cover.html.liquid

@@ -4,7 +4,7 @@
 {% if publisher_logos %}
   <div class="cover-publishers">
   {% for logo in publisher_logos %}
-    {{ logo }}
+    <span class="cover-logo">{{ logo }}</span>
   {% endfor %}
   </div>
 {% endif %}

data/lib/metanorma/html/templates/document.html.liquid

@@ -35,10 +35,6 @@
 </div>
 <button class="toc-hamburger" id="toc-hamburger" aria-label="Open table of contents">&#9776;</button>
 <button class="back-to-top" id="back-to-top" aria-label="Back to top"><svg viewBox="0 0 12 12" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><polyline points="3,8 6,4 9,8"/></svg></button>
-<div class="fn-annotation-pane" id="fn-annotation-pane">
-  <div class="fn-annotation-header"><span class="fn-annotation-label" id="fn-annotation-label"></span></div>
-  <div class="fn-annotation-body" id="fn-annotation-content"></div>
-</div>
 {{ scripts }}
 </body>
 </html>

data/lib/metanorma/html/theme.rb

@@ -2,186 +2,113 @@
 
 module Metanorma
   module Html
-    class Theme < Lutaml::Model::Serializable
-      THEMES_DIR = File.join(File.dirname(__FILE__), "..", "..", "..", "data",
-                             "themes")
-      TEMPLATES_ROOT = File.join(File.dirname(__FILE__), "templates")
-
-      # --- Primary palette ---
-      attribute :primary, :string, default: -> { "#28388A" }
-      attribute :accent, :string, default: -> { "#9C60C1" }
-      attribute :gradient, :string, default: -> {
-        "linear-gradient(135deg, #28388A 0%, #3a4ba0 50%, #9C60C1 100%)"
-      }
-      attribute :primary_light, :string, default: -> { "#eef0f8" }
-      attribute :accent_light, :string, default: -> { "#f5eef9" }
-      attribute :primary_dark, :string, default: -> { "#1c2660" }
-      attribute :accent_deep, :string
-      attribute :warm, :string
-      attribute :warm_light, :string
-
-      # --- Text & backgrounds ---
-      attribute :text_color, :string, default: -> { "#1a1a2e" }
-      attribute :text_light, :string, default: -> { "#4a4a6a" }
-      attribute :text_muted, :string, default: -> { "#8888a0" }
-      attribute :bg, :string, default: -> { "#fff" }
-      attribute :bg_light, :string, default: -> { "#fafbff" }
-      attribute :border, :string, default: -> { "#e0e2ee" }
-      attribute :sidebar_bg, :string, default: -> { "#f7f7fc" }
-
-      # --- Typography ---
-      attribute :font_body, :string, default: -> {
-        '"Source Serif 4", "Noto Serif", Georgia, "Times New Roman", serif'
-      }
-      attribute :font_sans, :string, default: -> {
-        '"DM Sans", "Helvetica Neue", Arial, sans-serif'
-      }
-      attribute :font_mono, :string, default: -> {
-        '"JetBrains Mono", "Fira Code", "Courier New", monospace'
-      }
-      attribute :font_url, :string, default: -> { "https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,300..700;1,9..40,300..700&family=Source+Serif+4:ital,opsz,wght@0,8..60,300..700;1,8..60,300..700&family=JetBrains+Mono:wght@400;500&display=swap" }
-
-      # --- Layout constants ---
-      attribute :content_max_width, :string, default: -> { "50em" }
-      attribute :sidebar_width, :string, default: -> { "260px" }
-      attribute :header_height, :string, default: -> { "52px" }
-      attribute :radius_sm, :string, default: -> { "4px" }
-      attribute :radius_md, :string, default: -> { "8px" }
-      attribute :shadow_sm, :string, default: -> {
-        "0 1px 3px rgba(40,56,138,0.08)"
-      }
-      attribute :shadow_md, :string, default: -> {
-        "0 4px 12px rgba(40,56,138,0.12)"
-      }
-
-      # --- Block element colors ---
-      attribute :note_color, :string, default: -> { "var(--mn-accent)" }
-      attribute :note_bg, :string, default: -> { "var(--mn-accent-light)" }
-      attribute :note_border, :string, default: -> { "var(--mn-accent)" }
-      attribute :example_color, :string, default: -> { "#0d9488" }
-      attribute :example_bg, :string, default: -> { "rgba(232, 248, 245, 0.6)" }
-      attribute :example_border, :string, default: -> { "#0d9488" }
-      attribute :admonition_color, :string, default: -> { "#b8860b" }
-      attribute :admonition_bg, :string, default: -> {
-        "rgba(255, 252, 245, 0.8)"
-      }
-      attribute :admonition_border, :string, default: -> { "#e8a820" }
-
-      # --- Footer & cover ---
-      attribute :footer_border_color, :string
-      attribute :cover_separator_color, :string
-
-      # --- Computed CSS (gradients) ---
-      attribute :header_background, :string
-      attribute :cover_background, :string
-      attribute :cover_after_bg, :string
-      attribute :cover_before_bg, :string
-      attribute :progress_bar_color, :string
-
-      # --- Dark mode overrides ---
-      attribute :dark_bg, :string, default: -> { "#0f1118" }
-      attribute :dark_bg_light, :string, default: -> { "#1a1d2a" }
-      attribute :dark_border, :string, default: -> { "#2e3248" }
-      attribute :dark_sidebar, :string, default: -> { "#141620" }
-      attribute :dark_text, :string, default: -> { "#e2e6f0" }
-      attribute :dark_text_light, :string, default: -> { "#c0c8dc" }
-      attribute :dark_text_muted, :string, default: -> { "#96a0b8" }
-      attribute :dark_primary_light, :string, default: -> { "#1e2140" }
-      attribute :dark_accent_light, :string, default: -> { "#2a2040" }
-      attribute :dark_note_bg, :string
-      attribute :dark_example_bg, :string
-      attribute :dark_admonition_bg, :string
-      attribute :dark_code_bg, :string
-      attribute :dark_code_border, :string
-
-      # --- Arbitrary per-element CSS overrides ---
-      attribute :extra_css, :string
-
-      # --- Publisher metadata ---
-      attribute :publishers, :string, collection: true, default: -> { [] }
-      attribute :publisher_name, :string
-      attribute :logos_light, :hash, default: -> { {} }
-      attribute :logos_dark, :hash, default: -> { {} }
-      attribute :doctype_labels, :hash, default: -> { {} }
-
-      # --- Document identifier formatting ---
-      attribute :doc_id_strip_prefix, :string
-
-      # --- Section ordering ---
-      attribute :preface_order, :string, collection: true, default: -> {
-        %w[foreword introduction abstract clause acknowledgements executivesummary]
-      }
-      attribute :clause_order, :string, collection: true, default: -> {
-        %w[sections annex bibliography indexsect]
-      }
-      attribute :preface_wrap, :boolean, default: -> { false }
-      attribute :toc_filter_types, :string, collection: true, default: -> { [] }
-
-      # --- Non-YAML state (set programmatically) ---
-      attr_accessor :theme_dir
-
-      def self.load(flavor)
-        dir_theme = File.join(THEMES_DIR, flavor.to_s, "theme.yaml")
-        flat_theme = File.join(THEMES_DIR, "#{flavor}.yaml")
-
-        if File.exist?(dir_theme)
-          from_directory(dir_theme, flavor)
-        elsif File.exist?(flat_theme)
-          from_file(flat_theme)
-        else
-          new
-        end
-      end
-
-      def self.from_file(path)
-        from_yaml(File.read(path))
-      end
-
-      def self.from_directory(path, flavor)
-        theme = from_yaml(File.read(path))
-        theme.theme_dir = File.join(THEMES_DIR, flavor.to_s)
-        theme
-      end
-
-      def logos
-        logos_light
-      end
-
-      def theme_templates_dir
-        return nil unless theme_dir
-
-        dir = File.join(theme_dir, "templates")
-        File.directory?(dir) ? dir : nil
-      end
-
-      def theme_assets_dir
-        return nil unless theme_dir
-
-        dir = File.join(theme_dir, "assets")
-        File.directory?(dir) ? dir : nil
-      end
-
-      def theme_css_path
-        return nil unless theme_dir
-
-        path = File.join(theme_dir, "custom.css")
-        File.exist?(path) ? path : nil
-      end
-
-      def resolve_template(template_name)
-        if theme_templates_dir
-          flavor_path = File.join(theme_templates_dir, template_name)
-          return flavor_path if File.exist?(flavor_path)
-        end
-        File.join(TEMPLATES_ROOT, template_name)
-      end
-
-      def resolve_asset(filename)
-        if theme_assets_dir
-          flavor_path = File.join(theme_assets_dir, filename)
-          return flavor_path if File.exist?(flavor_path)
-        end
-        nil
+    class Theme
+      # Primary palette
+      attr_accessor :primary, :accent, :gradient,
+                    :primary_light, :accent_light, :primary_dark,
+                    :accent_deep, :warm, :warm_light
+
+      # Text & backgrounds
+      attr_accessor :text_color, :text_light, :text_muted,
+                    :bg, :bg_light, :border, :sidebar_bg
+
+      # Typography
+      attr_accessor :font_body, :font_sans, :font_mono, :font_url
+
+      # Layout constants
+      attr_accessor :content_max_width, :sidebar_width, :header_height,
+                    :radius_sm, :radius_md, :shadow_sm, :shadow_md
+
+      # Block element colors (driven via CSS variables, eliminates extra_css)
+      attr_accessor :note_color, :note_bg, :note_border,
+                    :example_color, :example_bg, :example_border,
+                    :admonition_color, :admonition_bg, :admonition_border
+
+      # Footer accent
+      attr_accessor :footer_border_color
+
+      # Cover separator
+      attr_accessor :cover_separator_color
+
+      # Computed CSS (gradients — cannot use CSS variables alone)
+      attr_accessor :header_background, :cover_background,
+                    :cover_after_bg, :cover_before_bg,
+                    :progress_bar_color
+
+      # Dark mode overrides
+      attr_accessor :dark_bg, :dark_bg_light, :dark_border, :dark_sidebar,
+                    :dark_text, :dark_text_light, :dark_text_muted,
+                    :dark_primary_light, :dark_accent_light,
+                    :dark_note_bg, :dark_example_bg, :dark_admonition_bg,
+                    :dark_code_bg, :dark_code_border
+
+      # Arbitrary per-element CSS overrides (search, sourcecode, etc.)
+      attr_accessor :extra_css
+
+      def initialize
+        @primary        = "#28388A"
+        @accent         = "#9C60C1"
+        @gradient       = "linear-gradient(135deg, #28388A 0%, #3a4ba0 50%, #9C60C1 100%)"
+        @primary_light  = "#eef0f8"
+        @accent_light   = "#f5eef9"
+        @primary_dark   = "#1c2660"
+        @accent_deep    = nil
+        @warm           = nil
+        @warm_light     = nil
+        @text_color     = "#1a1a2e"
+        @text_light     = "#4a4a6a"
+        @text_muted     = "#8888a0"
+        @bg             = "#fff"
+        @bg_light       = "#fafbff"
+        @border         = "#e0e2ee"
+        @sidebar_bg     = "#f7f7fc"
+        @font_body      = '"Source Serif 4", "Noto Serif", Georgia, "Times New Roman", serif'
+        @font_sans      = '"DM Sans", "Helvetica Neue", Arial, sans-serif'
+        @font_mono      = '"JetBrains Mono", "Fira Code", "Courier New", monospace'
+        @font_url       = "https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,300..700;1,9..40,300..700&family=Source+Serif+4:ital,opsz,wght@0,8..60,300..700;1,8..60,300..700&family=JetBrains+Mono:wght@400;500&display=swap"
+        @content_max_width = "50em"
+        @sidebar_width     = "260px"
+        @header_height     = "52px"
+        @radius_sm = "4px"
+        @radius_md = "8px"
+        @shadow_sm = "0 1px 3px rgba(40,56,138,0.08)"
+        @shadow_md = "0 4px 12px rgba(40,56,138,0.12)"
+
+        # Block element defaults
+        @note_color      = "var(--mn-accent)"
+        @note_bg         = "var(--mn-accent-light)"
+        @note_border     = "var(--mn-accent)"
+        @example_color   = "#0d9488"
+        @example_bg      = "rgba(232, 248, 245, 0.6)"
+        @example_border  = "#0d9488"
+        @admonition_color = "#b8860b"
+        @admonition_bg = "rgba(255, 252, 245, 0.8)"
+        @admonition_border = "#e8a820"
+        @footer_border_color = nil
+        @cover_separator_color = nil
+
+        @header_background = nil
+        @cover_background  = nil
+        @cover_after_bg    = nil
+        @cover_before_bg   = nil
+        @progress_bar_color = nil
+        @extra_css = nil
+
+        # Dark mode defaults
+        @dark_bg          = "#0f1118"
+        @dark_bg_light    = "#1a1d2a"
+        @dark_border      = "#2e3248"
+        @dark_sidebar     = "#141620"
+        @dark_text        = "#e2e6f0"
+        @dark_text_light  = "#c0c8dc"
+        @dark_text_muted  = "#96a0b8"
+        @dark_primary_light = "#1e2140"
+        @dark_accent_light  = "#2a2040"
+        @dark_note_bg     = nil
+        @dark_example_bg  = nil
+        @dark_admonition_bg = nil
+        @dark_code_bg     = nil
+        @dark_code_border = nil
       end
 
       def to_css_root

data/lib/metanorma/html.rb

@@ -18,24 +18,13 @@ module Metanorma
           remove_method :children
         end
 
-        def self.children(node)
+        # moxml 0.5.36+ passes `entity_bearing:`. The Nokogiri adapter
+        # does not use it, so accept it and ignore it.
+        def self.children(node, **)
           node.children.to_a
         end
       end
-    end
-
-    # Patch missing Moxml module method used by lutaml-model XML serializer
-    ::Moxml.class_eval do
-      def self.preprocess_entities(text)
-        if block_given?
-          yield text
-        else
-          text
-        end
-      end
-    end
 
-    module Html
       Lutaml::Xml::XmlElement.class_eval do
         remove_method :order
 

data/lib/metanorma/ietf_document/metadata/ietf_bib_data_extension_type.rb

@@ -3,6 +3,31 @@
 module Metanorma
   module IetfDocument
     module Metadata
+      class PiSettings < Lutaml::Model::Serializable
+        attribute :toc, :string
+        attribute :tocdepth, :string
+        attribute :symrefs, :string
+        attribute :sortrefs, :string
+        attribute :compact, :string
+        attribute :subcompact, :string
+        attribute :strict, :string
+        attribute :comments, :string
+        attribute :notedraftinprogress, :string
+
+        xml do
+          element "pi"
+          map_element "toc", to: :toc
+          map_element "tocdepth", to: :tocdepth
+          map_element "symrefs", to: :symrefs
+          map_element "sortrefs", to: :sortrefs
+          map_element "compact", to: :compact
+          map_element "subcompact", to: :subcompact
+          map_element "strict", to: :strict
+          map_element "comments", to: :comments
+          map_element "notedraftinprogress", to: :notedraftinprogress
+        end
+      end
+
       class IetfBibDataExtensionType < Lutaml::Model::Serializable
         attribute :doctype, :string
         attribute :flavor, :string

data/lib/metanorma/ietf_document/metadata.rb

@@ -9,8 +9,6 @@ module Metanorma
                "metanorma/ietf_document/metadata/ietf_bibliographic_item"
       autoload :IetfEditorialGroup,
                "metanorma/ietf_document/metadata/ietf_editorial_group"
-      autoload :PiSettings,
-               "metanorma/ietf_document/metadata/pi_settings"
     end
   end
 end

data/lib/metanorma/iso_document/metadata/iso_bib_data_extension_type.rb

@@ -3,18 +3,66 @@
 module Metanorma
   module IsoDocument
     module Metadata
+      # Extension point for bibliographical definitions of ISO/IEC documents.
+      # Document type element with language attribute.
+      class DoctypeElement < Lutaml::Model::Serializable
+        attribute :language, :string
+        attribute :abbreviation, :string
+        attribute :value, :string
+
+        xml do
+          element "doctype"
+          map_attribute "language", to: :language, render_empty: true
+          map_attribute "abbreviation", to: :abbreviation
+          map_content to: :value
+        end
+      end
+
+      # Stage name element with abbreviation attribute.
+      class StagenameElement < Lutaml::Model::Serializable
+        attribute :abbreviation, :string
+        attribute :value, :string
+
+        xml do
+          element "stagename"
+          map_attribute "abbreviation", to: :abbreviation
+          map_content to: :value
+        end
+      end
+
       class IsoBibDataExtensionType < Lutaml::Model::Serializable
+        # The document is a horizontal standard.
         attribute :horizontal, :boolean
+
+        # Editorial groups associated with the production of the document.
         attribute :editorial_group, IsoProjectGroup
+
+        # Name of the publication stage of the document.
         attribute :stage_name, :string
+
+        # Category of IEC Standard applicable.
         attribute :category, :string
+
+        # Type of document being updated by this document, if it is an amendment or technical corrigendum.
         attribute :updates_document_type, :string
         attribute :semx_id, :string
+
+        # Document type (e.g. "international-standard").
         attribute :doctype, DoctypeElement, collection: true
+
+        # Document flavor (e.g. "iso").
         attribute :flavor, :string
+
+        # ICS classification codes.
         attribute :ics, Ics, collection: true
+
+        # Structured identifier (project number, part).
         attribute :structuredidentifier, StructuredIdentifier
+
+        # Name of the publication stage.
         attribute :stagename, StagenameElement
+
+        # Sub-document type.
         attribute :subdoctype, :string
 
         xml do

data/lib/metanorma/iso_document/metadata/iso_bibliographic_item.rb

@@ -3,34 +3,101 @@
 module Metanorma
   module IsoDocument
     module Metadata
+      # The bibliographical description of an ISO/IEC document.
+      # Language element with current attribute.
+      class LanguageElement < Lutaml::Model::Serializable
+        attribute :current, :string
+        attribute :value, :string
+
+        xml do
+          element "language"
+          map_attribute "current", to: :current
+          map_content to: :value
+        end
+      end
+
+      # Script element with current attribute.
+      class ScriptElement < Lutaml::Model::Serializable
+        attribute :current, :string
+        attribute :value, :string
+
+        xml do
+          element "script"
+          map_attribute "current", to: :current
+          map_content to: :value
+        end
+      end
+
       class IsoBibliographicItem < Lutaml::Model::Serializable
+        # Identifier of the document.
         attribute :doc_identifier, DocIdentifier, collection: true
+
+        # Collection of all title elements, grouped by language via consolidation mapping.
+        # Access: titles.items (raw), titles.per_language (grouped), titles.for_language("en")
         attribute :titles, AbstractTitle, collection: TitleCollection
+
+        # Type of the document.
         attribute :type, :string
+
+        # Fetched date
         attribute :fetched, Metanorma::Document::Relaton::DateTime
+
+        # URIs associated with the document.
         attribute :uri, Metanorma::Document::Relaton::TypedUri, collection: true
+
+        # Link/source
         attribute :source, :string, collection: true
+
+        # Document number
         attribute :docnumber, :string
+
+        # Contributors
         attribute :contributor, Metanorma::Document::Relaton::ContributionInfo,
                   collection: true
+
+        # Edition
         attribute :edition, Metanorma::Document::Relaton::Edition,
                   collection: true
+
+        # Version
         attribute :version, Metanorma::Document::Relaton::VersionInfo
+
+        # Notes
         attribute :note, Metanorma::Document::Relaton::TypedNote,
                   collection: true
+
+        # Language codes
         attribute :language, LanguageElement, collection: true
+
+        # Script codes
         attribute :script, ScriptElement, collection: true
+
+        # Abstract of the document.
         attribute :abstract, Metanorma::Document::Components::DataTypes::FormattedString,
                   collection: true
+
+        # Publication status of the document.
         attribute :status, IsoDocumentStatus
+
+        # Copyright information
         attribute :copyright, Metanorma::Document::Relaton::CopyrightAssociation,
                   collection: true
+
+        # Relations to other documents
         attribute :relation, Metanorma::Document::Relaton::DocumentRelation,
                   collection: true
+
+        # Formatted reference
         attribute :formattedref, Metanorma::Document::Components::DataTypes::FormattedString
+
+        # Dates
         attribute :date, Metanorma::Document::Relaton::BibliographicDate,
                   collection: true
+
+        # Place of publication
         attribute :place, :string, collection: true
+
+        # Extension point of the bibliographical description.
         attribute :ext, IsoBibDataExtensionType
         attribute :keyword, Metanorma::Document::Relaton::KeywordType,
                   collection: true
@@ -38,6 +105,8 @@ module Metanorma
                   collection: true
         attribute :editorialgroup, Metanorma::StandardDocument::Metadata::EditorialGroupType
         attribute :semx_id, :string
+
+        # Schema version (used by collection/entry bibdata, e.g. "v1.2.9").
         attribute :schema_version, :string
 
         xml do
@@ -81,6 +150,8 @@ module Metanorma
           map "ext", to: :ext
         end
 
+        # Returns the title for a given language (defaults to English)
+        # Uses consolidation-mapped per_language grouping for efficiency
         def title_for(language = "en")
           return nil unless titles
 
@@ -94,6 +165,7 @@ module Metanorma
           end
         end
 
+        # Primary title (English by default)
         def title
           @title ||= title_for("en")
         end