metanorma-document 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc7125fd4984bbedebb8d471fc29d0d34d5b56b7de1ec518570bc27f8e0671d5
-  data.tar.gz: bc63e4f58ba6053d66df6a2671737c0ce051057ef4e0b14fc51154d050ca0c67
+  metadata.gz: a15c5f341f9fbc477322f57c757f26896b1ba2bd3e80a89815ba6942a44c5c6c
+  data.tar.gz: 95f0e2d121bc523f38600fe0d5e3e058f7c6b8212b4e5e8b4ab4654d06b10a83
 SHA512:
-  metadata.gz: 45e13915f1b88579d06b94968c5a7f469fdbf77b6980cf3cb68d6747bb9fd1a87d111c8388d2f0f337ba5ccde71aa96c7f755ca6d0080f8ccafa154a15ed7075
-  data.tar.gz: 1a6ab72e96afe880682ffb9646273e794dec60ce1a2e208d794054fe99ea38c6adf09672678a8234ebf805b800ab491bfa01332efcd663b65c403e8cd617712c
+  metadata.gz: 01eee74753ce15ebf8bd68a3523130d7231eee75c42c2bb3551b67b30fd79e022c8e12858a1aae6d6fc03baf6bbac511b5b5e62db0b054487ee5c1bb62650c2c
+  data.tar.gz: 499dc86b2c426e22f107443b8939eead6e2861ab985b9dd427c54a2572531f11ab9c09114b7aa44e9c2fd0dd16eb5dfd36366dbc4f8b2c7c2c713994d6e53aa2

data/README.adoc

@@ -75,6 +75,34 @@ BaseRenderer                  # Core HTML rendering, document assembly, CSS/JS p
     └── RiboseRenderer        # Ribose-specific formatting
 ....
 
+===== Drop Pattern
+
+Block elements (notes, examples, sourcecode, formulas, figures, admonitions) use the Drop pattern:
+
+[source,ruby]
+# A Drop captures rendered content via RendererContext, then passes
+# data to a Liquid template. The renderer never emits HTML directly.
+def render_note(note, **_opts)
+  drop = Drops::NoteDrop.from_model(note, renderer: renderer_context)
+  @output << render_liquid("_note.html.liquid", { "block" => drop })
+end
+
+Each Drop class inherits from `BlockElementDrop` and implements `.from_model(model, renderer:)` which:
+
+. Captures child content via `renderer.capture_output { ... }`
+. Returns a new Drop instance with pre-rendered HTML strings
+. The Liquid template reads Drop attributes and outputs final HTML
+
+`RendererContext` is a facade that exposes only the rendering methods Drops need, maintaining encapsulation.
+
+===== Class Name Ownership
+
+The HTML renderer owns its class names entirely. **No XML-originated class names appear in the HTML output.**
+
+* Block-level classes (`note-block`, `formula`, `figure`, etc.) are assigned by the renderer based on what it's rendering
+* Inline span classes use `SPAN_ROLE_CLASSES` to map XML span roles to HTML-specific names (e.g., `boldtitle` → `title-text`, `citesec` → `xref-section`)
+* The XML's `class_attr` is read as **input only** to determine semantic role, never emitted directly
+
 ==== Presentation XML
 
 The HTML renderer expects **presentation XML** (not source XML). Presentation XML contains `fmt-*` display elements (`fmt-title`, `fmt-xref`, `fmt-link`, `fmt-concept`, `fmt-definition`, `fmt-preferred`, etc.) alongside semantic elements. The renderer prioritizes `fmt-*` elements for rendering, falling back to semantic elements when display elements are absent.
@@ -107,8 +135,15 @@ HTML structure is defined in `.liquid` templates under `lib/metanorma/html/templ
 `_header.html.liquid` :: Sticky header with publisher logos
 `_footer.html.liquid` :: Footer with copyright
 `_cover.html.liquid` :: Cover page layout
+`_iso_cover.html.liquid` :: ISO-specific cover page
 `_footnotes.html.liquid` :: Footnotes section
 `_doc_title.html.liquid` :: Document title rendering
+`_note.html.liquid` :: Note block
+`_example.html.liquid` :: Example block
+`_sourcecode.html.liquid` :: Source code block
+`_formula.html.liquid` :: Formula block
+`_figure.html.liquid` :: Figure block
+`_admonition.html.liquid` :: Admonition block
 
 Templates use `Liquid::LocalFileSystem` for partials (prefixed with `_`). The `render_liquid` method handles template caching via `TEMPLATE_CACHE`.
 
@@ -151,26 +186,32 @@ Renderer instance methods:
 `theme` :: Returns the `Theme` instance (override in subclasses).
 `render_liquid(template_name, assigns)` :: Renders a Liquid template with caching.
 
- == Document Flavors
+== Document Flavors
+
+The gem provides a hierarchy of document flavors:
+
+* BasicDocument - Basic document model
+* StandardDocument - Standard document model (extends BasicDocument)
+* IsoDocument - ISO standard document model (extends StandardDocument)
+* IecDocument - IEC standard document model
+* IeeeDocument - IEEE standard document model
+* IetfDocument - IETF standard document model
+* IhoDocument - IHO standard document model
+* OimlDocument - OIML standard document model
+* BipmDocument - BIPM standard document model
+* ItuDocument - ITU standard document model
+* OgcDocument - OGC standard document model
+* CcDocument - CC standard document model
+* RiboseDocument - Ribose standard document model
+
+== Supported XML Formats
 
- The gem provides a hierarchy of document flavors:
+This library targets the modern Metanorma XML format which uses `<metanorma>` as the root element.
 
- * BasicDocument - Basic document model
- * StandardDocument - Standard document model (extends BasicDocument)
- * IsoDocument - ISO standard document model (extends StandardDocument)
- * IecDocument - IEC standard document model
- * IeeeDocument - IEEE standard document model
- * IetfDocument - IETF standard document model
- * IhoDocument - IHO standard document model
- * OimlDocument - OIML standard document model
- * BipmDocument - BIPM standard document model
- * ItuDocument - ITU standard document model
- * OgcDocument - OGC standard document model
- * CcDocument - CC standard document model
- * RiboseDocument - Ribose standard document model
+Legacy XML formats that use flavor-specific root elements (e.g. `<iso-standard>`, `<m3d-standard>`, `<csa-standard>`, `<un-standard>`) are *not supported*.
 
- == Supported XML Formats
+== Documentation
 
- This library targets the modern Metanorma XML format which uses `<metanorma>` as the root element.
+Detailed architecture documentation is in the `docs/` directory:
 
- Legacy XML formats that use flavor-specific root elements (e.g. `<iso-standard>`, `<m3d-standard>`, `<csa-standard>`, `<un-standard>`) are *not supported*.
+* xref:docs/html-renderer.adoc[HTML Renderer Architecture] — renderer pipeline, drop pattern, class name ownership, template system

data/data/stylesheets/components/bibliography.css

@@ -12,7 +12,7 @@
   border-bottom: 1px solid var(--color-border);
 }
 .norm-ref-entry:last-child { border-bottom-color: transparent; }
-.std-doc-number { font-weight: 500; color: var(--mn-primary); font-family: var(--font-sans); }
-.std-year { font-weight: 500; }
+.ref-doc-number { font-weight: 500; color: var(--mn-primary); font-family: var(--font-sans); }
+.ref-year { font-weight: 500; }
 .biblio-link { color: inherit; text-decoration: none; }
 .biblio-link:hover { color: var(--mn-primary); text-decoration: underline; }

data/data/stylesheets/components/inline.css

@@ -1,8 +1,8 @@
 /* === Inline Elements === */
 .fn-marker { vertical-align: super; font-size: 0.78em; color: var(--mn-primary); font-family: var(--font-sans); }
 .small-caps { font-variant: small-caps; letter-spacing: 0.03em; }
-.obligation { font-style: italic; color: var(--mn-accent); }
-.bold-title { font-weight: 700; }
+.obligation-text { font-style: italic; color: var(--mn-accent); }
+.title-text { font-weight: 700; }
 
 /* Math container — hover dropdown for source formats */
 .math-container { position: relative; display: inline; }
@@ -30,28 +30,27 @@
   border-radius: 2px; transition: background 0.15s, color 0.15s;
 }
 .stem-copy-btn:hover { background: var(--mn-primary-light); color: var(--mn-primary); }
-.nonboldtitle { font-weight: 400; }
+.subtitle-text { font-weight: 400; }
 
-.citesec, .citefig, .citetbl, .citeapp {
+.xref-section, .xref-fig, .xref-table, .xref-app {
   color: var(--mn-primary);
   text-decoration: underline;
   text-decoration-color: rgba(40,56,138,0.2);
   cursor: pointer;
 }
-.citesec:hover, .citefig:hover, .citetbl:hover, .citeapp:hover {
+.xref-section:hover, .xref-fig:hover, .xref-table:hover, .xref-app:hover {
   color: var(--mn-accent);
 }
 
-.doc-subtitle { font-weight: 400; }
-.doc-part-number { font-weight: 500; }
-.doc-part-title { font-style: italic; }
-.doc-publisher, .doc-publisher-name { font-weight: 500; }
-.std-doc-number { font-weight: 500; }
-.std-year { font-weight: 500; }
+.ref-part-number { font-weight: 500; }
+.ref-title { font-style: italic; }
+.ref-publisher, .ref-publisher-name { font-weight: 500; }
+.ref-doc-number { font-weight: 500; }
+.ref-year { font-weight: 500; }
 .xref-label { font-weight: 600; }
 a.xref { color: var(--mn-primary); text-decoration: none; border-bottom: 1px solid var(--mn-primary-light); }
 a.xref:hover { border-bottom-color: var(--mn-primary); }
-.doc-content a.xref .element-name { font-style: italic; }
+.doc-content a.xref .element-label { font-style: italic; }
 
 .kbd-hint {
   display: inline-block;

data/docs/html-renderer.adoc

@@ -0,0 +1,261 @@
+= HTML Renderer Architecture
+
+== Overview
+
+The HTML renderer converts a Metanorma document model (parsed from presentation XML) into a complete, self-contained HTML document. It produces all body content, header, footer, table of contents, CSS theming, and JavaScript interactivity.
+
+== Pipeline
+
+....
+Generator.generate(doc)
+  ├── Auto-selects renderer by document class
+  ├── Renderer.new
+  └── renderer.generate_full_document(doc)
+        ├── Header (publisher logos, document title)
+        ├── ToC sidebar
+        ├── Body content (recursive render)
+        ├── Footnotes
+        ├── Footer (copyright)
+        └── Asset pipeline (inline CSS + JS)
+....
+
+== Renderer Hierarchy
+
+[source,ruby]
+BaseRenderer                  # Core HTML rendering, document assembly, CSS/JS pipeline
+└── StandardRenderer          # Terms, definitions, annexes, bibliography
+    ├── IsoRenderer           # ISO cover page, copyright, title formatting
+    │   ├── IccRenderer       # ICC publisher styling
+    │   └── PdfaRenderer      # PDF Association publisher styling
+    ├── IecRenderer           # IEC-specific formatting
+    ├── IeeeRenderer          # IEEE-specific formatting
+    ├── IetfRenderer          # IETF-specific formatting
+    ├── IhoRenderer           # IHO-specific formatting
+    ├── ItuRenderer           # ITU-specific formatting
+    ├── OgcRenderer           # OGC-specific formatting
+    ├── OimlRenderer          # OIML-specific formatting
+    ├── BipmRenderer          # BIPM-specific formatting
+    ├── CcRenderer            # CC-specific formatting
+    └── RiboseRenderer        # Ribose-specific formatting
+
+=== Renderer Selection
+
+The `Generator` uses a two-tier lookup:
+
+1. **Taste match**: If the document's publisher matches a registered taste, use that renderer.
+2. **Model class**: Walk the ancestor chain from most specific to `BaseRenderer`.
+
+[source,ruby]
+# ICC documents are IsoDocument::Root but use IccRenderer
+Metanorma::Html::Generator.register_taste(
+  Metanorma::IsoDocument::Root,
+  "ICC",
+  Metanorma::Html::IccRenderer
+)
+
+== Class Name Ownership
+
+The HTML renderer owns its class names entirely. **No XML-originated class names appear in the HTML output.**
+
+The XML document model's `class_attr` is read as **input only** to determine semantic role. The renderer maps XML roles to HTML-specific class names via `SPAN_ROLE_CLASSES`:
+
+[source,ruby]
+SPAN_ROLE_CLASSES = {
+  "boldtitle" => "title-text",
+  "citefig" => "xref-fig",
+  "citesec" => "xref-section",
+  "fmt-element-name" => "element-label",
+  "fmt-obligation" => "obligation-text",
+  # ...
+}.freeze
+
+Block-level classes (`note-block`, `formula`, `figure`, etc.) are assigned by the renderer based on what it's rendering — never carried over from XML.
+
+Inline span classes go through `html_class_for_span`:
+
+[source,ruby]
+def html_class_for_span(xml_class)
+  SPAN_ROLE_CLASSES[xml_class] || "span-#{xml_class}"
+end
+
+Raw XML content (e.g., boilerplate) passes through Nokogiri post-processing that remaps any remaining XML class names.
+
+== Drop Pattern
+
+Block elements (notes, examples, sourcecode, formulas, figures, admonitions) use the Drop pattern to separate data capture from template rendering.
+
+=== How It Works
+
+. A `Drop` class captures rendered content via `RendererContext`
+. The Drop passes pre-rendered HTML strings to a Liquid template
+. The template reads Drop attributes and outputs final HTML
+
+[source,ruby]
+# In the renderer:
+def render_note(note, **_opts)
+  drop = Drops::NoteDrop.from_model(note, renderer: renderer_context)
+  @output << render_liquid("_note.html.liquid", { "block" => drop })
+end
+
+# In the Drop:
+class NoteDrop < BlockElementDrop
+  def self.from_model(note, renderer:)
+    content_html = renderer.capture_output do
+      note.content.each { |para| renderer.render_paragraph(para) }
+    end
+    new(id: renderer.safe_attr(note, :id),
+        label_html: renderer.escape_html(label),
+        content_html: content_html,
+        css_class: "note-block")
+  end
+end
+
+=== BlockElementDrop
+
+All block drops inherit from `BlockElementDrop`, which provides common attributes:
+
+`id` :: HTML element id
+`type` :: Block type identifier
+`label_html` :: Pre-rendered label (e.g., "NOTE", "EXAMPLE 1")
+`content_html` :: Pre-rendered inner content
+`css_class` :: HTML-specific class name
+
+=== RendererContext
+
+`RendererContext` is a facade inside `BaseRenderer` that exposes only the rendering methods Drops need. Drops call renderer methods through this facade — the renderer's private interface stays encapsulated.
+
+[source,ruby]
+class RendererContext
+  def safe_attr(obj, method_name)
+  def escape_html(text)
+  def extract_block_label(block, default)
+  def extract_plain_text(node)
+  def capture_output(&block)
+  def render_paragraph(p)
+  def render_mixed_inline(node)
+  def render_inline_element(el)
+  def render_unordered_list(ul)
+  def render_ordered_list(ol)
+  def render_definition_list(dl)
+  def render_table(table)
+  def render_figure(figure)
+end
+
+== Liquid Templates
+
+HTML structure is defined in `.liquid` templates under `lib/metanorma/html/templates/`.
+
+[horizontal]
+`document.html.liquid` :: Full document shell (`<html>`, `<head>`, `<body>`)
+`_header.html.liquid` :: Sticky header with publisher logos
+`_footer.html.liquid` :: Footer with copyright
+`_cover.html.liquid` :: Generic cover page layout
+`_iso_cover.html.liquid` :: ISO-specific cover page
+`_iso_doc_title.html.liquid` :: ISO document title rendering
+`_doc_title.html.liquid` :: Generic document title rendering
+`_footnotes.html.liquid` :: Footnotes section
+`_note.html.liquid` :: Note block
+`_example.html.liquid` :: Example block
+`_sourcecode.html.liquid` :: Source code block
+`_formula.html.liquid` :: Formula block
+`_figure.html.liquid` :: Figure block
+`_admonition.html.liquid` :: Admonition block
+
+Templates use `Liquid::LocalFileSystem` for partials (prefixed with `_`). The `render_liquid` method handles template caching.
+
+=== Template Example
+
+`_note.html.liquid`:
+
+[source,liquid]
+----
+<div{% if block.id %} id="{{ block.id }}"{% endif %} class="{{ block.css_class }}">
+  {% if block.label_html %}
+  <p class="note-label"><strong>{{ block.label_html }}</strong></p>
+  {% endif %}
+  <div class="note-content">
+    {{ block.content_html }}
+  </div>
+</div>
+----
+
+== Theming
+
+Each renderer has a `Theme` object controlling colors, typography, and layout. Theme properties are emitted as CSS custom properties (`--mn-primary`, `--font-body`, etc.).
+
+[source,ruby]
+class MyRenderer < Metanorma::Html::StandardRenderer
+  def theme
+    @theme ||= begin
+      t = Theme.new
+      t.primary = "#1a5276"
+      t.accent = "#2e86c1"
+      t.font_body = '"Charter", serif'
+      t
+    end
+  end
+end
+
+=== Theme Properties
+
+[horizontal]
+`primary` :: Primary brand color
+`accent` :: Accent/highlight color
+`gradient` :: Header gradient
+`font_body` :: Body text font stack
+`font_sans` :: Sans-serif font stack
+`font_mono` :: Monospace font stack
+`font_url` :: Google Fonts URL
+`note_border` :: Note block border color
+`note_bg` :: Note block background
+`example_border` :: Example block border color
+`example_bg` :: Example block background
+`admonition_border` :: Admonition border color
+`admonition_bg` :: Admonition background
+`extra_css` :: Additional CSS string appended after defaults
+
+== Presentation XML
+
+The HTML renderer expects **presentation XML** (not source XML). Presentation XML contains `fmt-*` display elements alongside semantic elements:
+
+- `fmt-title` — formatted section/block titles
+- `fmt-xref` — formatted cross-reference text
+- `fmt-link` — formatted link text
+- `fmt-concept` — formatted concept references
+- `fmt-definition` — formatted term definitions
+- `fmt-preferred` — formatted preferred term names
+
+The renderer prioritizes `fmt-*` elements for rendering, falling back to semantic elements when display elements are absent.
+
+== Asset Pipeline
+
+The `AssetPipeline` compiles CSS and JavaScript from modular source files into inline `<style>` and `<script>` blocks for self-contained output.
+
+=== CSS
+
+[horizontal]
+`data/stylesheets/base/` :: Reset, typography, layout, dark mode, print
+`data/stylesheets/components/` :: Component stylesheets (inline, tables, notes, etc.)
+
+=== JavaScript
+
+[horizontal]
+`data/javascripts/core/` :: Reader, theme, scroll, navigation, reveal
+`data/javascripts/components/` :: ToC, search, lightbox, code copy, glossary, etc.
+
+== Extending
+
+To add a new flavor renderer:
+
+. Subclass the appropriate base (usually `IsoRenderer` or `StandardRenderer`)
+. Override `theme` with brand colors/fonts
+. Override `publisher_logo_map` with logo filenames
+. Register with the Generator:
+
+[source,ruby]
+Metanorma::Html::Generator.register(
+  Metanorma::MyDocument::Root,
+  Metanorma::Html::MyRenderer
+)
+
+To customize how a specific block renders, override the `render_*` method and either emit HTML directly or use the Drop pattern with a new template.

data/lib/metanorma/document/version.rb

@@ -2,7 +2,7 @@
 
 module Metanorma
   module Document
-    VERSION = "0.2.0"
+    VERSION = "0.2.1"
     Version = VERSION
   end
 end