docbook 0.1.0

data/docs/understanding/architecture.adoc

@@ -0,0 +1,145 @@
+---
+layout: default
+title: Architecture
+parent: Understanding
+nav_order: 1
+---
+
+# Architecture
+
+The Metanorma DocBook gem is organized into distinct modules, each
+responsible for a specific phase of document processing. This page
+describes the purpose of each module and how they interact.
+
+== Module structure
+
+=== Docbook::Document
+
+The entry point for parsing. `Document.from_xml` accepts an XML string,
+detects the root element name (such as `book` or `article`), looks up
+the corresponding element class in `ROOT_ELEMENT_MAP`, and delegates
+to that class's `from_xml` method.
+
+=== Docbook::Elements
+
+Contains 157 element classes, one per supported DocBook XML element.
+Each class inherits from `Lutaml::Model::Serializable` and declares
+typed attributes and XML mappings using the lutaml-model DSL. Classes
+are autoloaded on demand from `lib/docbook/elements/`.
+
+=== Docbook::XIncludeResolver
+
+Resolves XInclude directives before model parsing. It iterates through
+`xi:include` elements in a Nokogiri document, fetching referenced files
+and replacing the include elements with the included content. Supports
+both XML and text parse modes, plus `fragid` extensions for line-range
+and search-based text extraction.
+
+=== Docbook::XrefResolver
+
+After parsing, builds an O(1) hash map of `xml:id` values to their
+corresponding element objects. The resolver walks the element tree
+recursively, collecting every element that has an `xml_id`. Callers
+then use `title_for(linkend)` to resolve cross-reference text.
+
+=== Docbook::Output::Html
+
+The HTML generation engine. It takes a parsed element tree and an
+optional `XrefResolver`, then walks the tree to produce structured
+data (TOC, content blocks, numbering, index). The final output is
+rendered through a Liquid template with inline or linked JSON data
+for the Vue SPA frontend.
+
+=== Docbook::Output::Data
+
+Defines the data model classes used by the HTML generator:
+`ContentBlock`, `SectionData`, `NumberingBuilder`, `DocbookOutput`,
+and related types. These classes hold the intermediate representation
+between the element tree and JSON serialization.
+
+=== Docbook::Models
+
+A parallel set of pre-computed models (`DocumentRoot`, `TocNode`,
+`SectionRoot`, etc.) that represent the final JSON structure consumed
+by the Vue SPA. These are separate from `Output::Data` because they
+include additional metadata like reading position and generator version.
+
+=== Docbook::CLI
+
+A Thor-based command-line interface that provides the `format`,
+`validate`, `to-html`, and `roundtrip` commands. It wires together
+the parsing, resolution, and output modules based on user options.
+
+== Data flow
+
+The following diagram shows the complete data flow from XML input to
+final HTML output:
+
+....
+                  +-----------------+
+                  |   XML Input     |
+                  | (string/file)   |
+                  +--------+--------+
+                           |
+                           v
+                  +--------+--------+
+                  | XIncludeResolver |  (optional)
+                  |  resolve xi:    |
+                  |  include refs   |
+                  +--------+--------+
+                           |
+                           v
+                  +--------+--------+
+                  | Document.from_xml|
+                  | Nokogiri parse   |
+                  | -> Element model |
+                  +--------+--------+
+                           |
+                           v
+                  +--------+--------+
+                  | XrefResolver     |
+                  | Build O(1) ID   |
+                  | lookup hash     |
+                  +--------+--------+
+                           |
+                           v
+                  +--------+--------+
+                  | Output::Html     |
+                  | Section tree    |
+                  | Numbering       |
+                  | Content blocks  |
+                  | Index collection|
+                  +--------+--------+
+                           |
+                           v
+                  +--------+--------+
+                  | Liquid Template  |
+                  | Inline JSON      |
+                  | or linked JSON   |
+                  +--------+--------+
+                           |
+                           v
+                  +--------+--------+
+                  |   HTML Output   |
+                  | (single file or |
+                  |  directory)     |
+                  +-----------------+
+....
+
+In single-file mode, all JSON data and CSS/JS assets are embedded
+directly into the HTML. In directory mode, the JSON is written to
+`docbook.data.json` and assets are copied to an `assets/` subdirectory.
+
+== Element model system
+
+Every DocBook element is represented by a Ruby class that inherits from
+`Lutaml::Model::Serializable`. This provides:
+
+* **Typed attributes** via the `attribute` DSL method
+* **Mixed content** support via the `mixed_content` declaration
+* **XML serialization** via `from_xml` / `to_xml`
+* **JSON serialization** via `to_json`
+
+The `each_mixed_content` method yields child nodes (both `String` and
+element objects) in document order, which is essential for correct
+inline content rendering.

data/docs/understanding/content-pipeline.adoc

@@ -0,0 +1,102 @@
+---
+layout: default
+title: Content Pipeline
+parent: Understanding
+nav_order: 2
+---
+
+# Content Pipeline
+
+The content pipeline transforms a DocBook XML document into a rendered
+HTML page with an embedded Vue SPA. Each step produces a well-defined
+intermediate representation. Understanding this pipeline is essential
+for debugging output or extending the gem.
+
+== Step 1: XML input
+
+The pipeline begins with raw XML, provided either as a file path or a
+string. The CLI reads the file and passes the string to the parsing
+layer. The XML may reference external files via XInclude or contain
+`xml:id` attributes for cross-referencing.
+
+== Step 2: XInclude resolution
+
+If XInclude processing is enabled (the default for `to-html`), the
+`XIncludeResolver` preprocesses the Nokogiri document. It iterates
+through all `xi:include` elements, fetches the referenced files, and
+replaces the include directives with the actual content. This step
+handles nested includes by re-scanning after each resolution. Text
+includes with `fragid` attributes support line-range extraction and
+search-based filtering.
+
+== Step 3: Parsing into element model
+
+`Document.from_xml` parses the (possibly resolved) XML string. It
+detects the root element name and delegates to the corresponding
+element class (for example, `Elements::Book` for `<book>`). The
+lutaml-model library maps each XML element to a typed Ruby object
+with declared attributes, collections, and mixed content.
+
+== Step 4: XRef resolution
+
+The `XrefResolver` walks the parsed element tree and builds a hash
+map of `xml:id` values to element objects. This provides O(1) lookup
+for resolving `<xref linkend="...">` references. The resolver also
+extracts the best available title text from each target element.
+
+== Step 5: Section data collection
+
+The HTML generator performs a recursive tree walk over the parsed
+document, collecting `SectionData` objects. Each `SectionData` records
+the section's ID, title, type (part, chapter, section, appendix, etc.),
+and child sections. The resulting tree mirrors the document's logical
+structure and is used for the table of contents.
+
+== Step 6: Numbering
+
+The `NumberingBuilder` assigns numbers to each section in the tree.
+It uses different numbering schemes depending on the section type:
+
+* **Parts** receive uppercase Roman numerals (I, II, III).
+* **Chapters** receive Arabic numerals scoped to their parent part
+  (1, 2, 3).
+* **Sections** receive hierarchical dotted numbers (1.1, 1.2.3).
+* **Appendices** receive uppercase letters (A, B, C).
+
+The numbering map is a simple hash of ID to formatted number string.
+
+== Step 7: Content map building
+
+For each section, the HTML generator calls `each_mixed_content` on the
+corresponding element object. This yields `String` nodes and typed
+element objects in document order. A `case` statement dispatches each
+element to a builder method that produces `ContentBlock` instances.
+Paragraphs become `paragraph` blocks with inline children; code
+listings become `code` blocks with a `language` attribute; figures
+become `image` blocks with `src` and `alt` attributes.
+
+== Step 8: Index collection and generation
+
+The `IndexCollector` traverses the element tree looking for
+`<indexterm>` elements. It collects primary, secondary, and tertiary
+terms along with their containing section IDs. The `IndexGenerator`
+then groups collected terms by first letter, producing an `Index` model
+with `IndexGroup` children, each containing sorted `IndexTerm` entries.
+
+== Step 9: Template rendering
+
+The assembled `DocbookOutput` model (containing title, TOC, content,
+and index) is serialized to JSON and inserted into a Liquid template.
+In single-file mode, the JSON replaces placeholder tokens
+(`[[DOCBOOK_DATA]]`, `[[DOCBOOK_TOC]]`, `[[DOCBOOK_CONTENT]]`,
+`[[DOCBOOK_INDEX]]`) directly in the HTML. In directory mode, the
+placeholders are set to `null` and the JSON is written to a separate
+file that the Vue SPA fetches at runtime.
+
+== Step 10: Output
+
+The final step writes the rendered HTML to disk. Single-file mode
+produces one self-contained HTML file with all data inlined. Directory
+mode creates an output directory with `index.html`, `docbook.data.json`,
+and an `assets/` directory containing `app.css` and `app.iife.js` copied
+from the frontend build.

data/docs/understanding/data-models.adoc

@@ -0,0 +1,156 @@
+---
+layout: default
+title: Data Models
+parent: Understanding
+nav_order: 3
+---
+
+# Data Models
+
+The gem uses two separate model namespaces, each serving a distinct
+purpose in the pipeline. All model classes inherit from
+`Lutaml::Model::Serializable`, which provides XML and JSON
+serialization through a declarative DSL.
+
+== Output::Data models (`Docbook::Output`)
+
+These classes are defined in `lib/docbook/output/data.rb` and are used
+by the HTML generator to build the intermediate representation that
+becomes the JSON payload for the Vue SPA.
+
+=== DocbookOutput
+
+The top-level output model. Contains `title`, `toc` (a `Toc` instance),
+`content` (a `ContentData` instance), and `index` (an `Index`
+instance). This single model encapsulates everything the Vue SPA needs
+to render the document.
+
+=== ContentBlock
+
+A recursive tree node representing a single block of content. Each
+block has a `type` (such as `:paragraph`, `:code`, `:image`), optional
+text, source URL, alt text, title, language, and CSS class name. Block
+types that can contain nested content use the `children` attribute,
+which holds an array of child `ContentBlock` instances.
+
+=== SectionData
+
+Represents a section in the table of contents tree. Each entry has an
+`id`, `title`, `type` (part, chapter, section, appendix, etc.), an
+optional `number`, and `children` (an array of nested `SectionData`
+instances).
+
+=== NumberingEntry
+
+A simple key-value pair mapping a section ID to its formatted number
+string. These are collected into an array within the `Toc` model.
+
+=== ContentData and ContentEntry
+
+`ContentData` wraps a collection of `ContentEntry` objects. Each
+`ContentEntry` maps a section ID (the `key`) to a `SectionContent`
+instance containing the section's rendered content blocks. This
+key-value structure serializes cleanly to JSON and provides O(1)
+section lookup in the Vue SPA.
+
+=== SectionContent
+
+Holds the content for a single section: a `section_id` and an array
+of `ContentBlock` instances representing the section's body.
+
+=== Toc
+
+Combines the `SectionData` tree (the recursive TOC structure) with the
+`NumberingEntry` collection (the computed numbering map).
+
+=== IndexTerm
+
+Represents a single index entry with `primary`, `secondary`, and
+`tertiary` term text, plus the `section_id` and `section_title` where
+the term appears. Also holds `sees` and `see_alsos` arrays for
+cross-references.
+
+=== IndexGroup
+
+Groups index terms under a `letter` heading. Contains an array of
+`IndexTerm` entries.
+
+=== Index
+
+The top-level index model with a `title` and an array of `IndexGroup`
+instances, one per letter of the alphabet.
+
+=== DocumentData
+
+A minimal model holding only the document `title`. Used in single-file
+mode to initialize the `DOCBOOK_DATA` JavaScript object before merging
+in the TOC, content, and index.
+
+=== NumberingBuilder
+
+A stateful builder that tracks counters for parts (Roman numerals),
+chapters (Arabic, scoped per part), sections (hierarchical, scoped per
+parent), and appendices (uppercase letters). It exposes methods like
+`next_part`, `next_chapter`, `next_section`, and `next_appendix` that
+increment the appropriate counter and return the formatted number. The
+final `numbering` hash maps section IDs to their computed numbers.
+
+== Models namespace (`Docbook::Models`)
+
+Defined in `lib/docbook/models/`, these classes represent the full
+document structure as consumed by the Vue SPA. They include additional
+metadata beyond what the output data models carry.
+
+=== DocumentRoot
+
+The top-level model for the complete document. Contains `title`,
+`metadata` (a `DocumentMetadata` instance), `toc` (an array of
+`TocNode`), `sections` (an array of `SectionRoot`), `index` (an array
+of `IndexEntry`), `numbering` (an array of `SectionNumber`), and a
+`reading_position`. Also includes `generator` and `generated_at`
+strings for debugging.
+
+=== DocumentMetadata
+
+Stores document-level information: `author`, `author_name`, `title`,
+`subtitle`, `productname`, `version`, `pubdate`, `release_info`, and
+`abstract`. All fields are strings.
+
+=== TocNode
+
+A recursive tree node for the table of contents. Each node has an `id`,
+`title`, `type`, `number`, optional `page` (for PDF navigation), and
+`children` (an array of nested `TocNode` instances).
+
+=== SectionRoot
+
+Represents a section in the pre-computed document structure. Contains
+`id`, `type`, `title`, `number`, and `children` (nested `SectionRoot`
+instances). For reference entries, it also holds a `refname` string.
+
+=== SectionNumber
+
+A simple mapping of section `id` to its computed `number` string and
+`type`. Used by the Vue SPA to display section numbers in the UI.
+
+=== IndexEntry
+
+Represents an index term with `primary`, `secondary`, `tertiary`,
+`see_also`, `section_id`, `section_title`, and a `sort_key` for
+alphabetical ordering.
+
+=== ReadingPosition
+
+Tracks the user's reading progress. Contains `section_id`,
+`percentage`, `last_read_at`, `reading_mode`, and `scroll_position`.
+This data is persisted in the Vue SPA via localStorage.
+
+== Serialization
+
+Both model namespaces serialize to JSON for the Vue SPA. The output
+data models (`Output::Data`) are what the Ruby HTML generator
+constructs and serializes. The `Models` namespace provides the
+TypeScript-compatible schema that the Vue SPA expects. In practice,
+the HTML generator uses the `Output::Data` classes directly, and the
+JSON they produce is consumed by the Pinia `documentStore` in the
+frontend.

data/docs/understanding/index.adoc

@@ -0,0 +1,34 @@
+---
+layout: default
+title: Understanding
+nav_order: 5
+has_children: true
+---
+
+# Understanding
+
+This section explains how the Metanorma DocBook gem works internally.
+It covers the architecture, data flow, and design decisions that shape
+the library.
+
+== When to read this section
+
+Read these pages when you want to do any of the following:
+
+* **Extend the gem** -- Adding new DocBook element types, custom output
+  formats, or additional template variables requires understanding the
+  module structure and element class design.
+* **Debug output** -- If the HTML output does not match your expectations,
+  the content pipeline and data model pages will help you trace where a
+  particular element is transformed or lost.
+* **Contribute** -- Contributors should understand the full pipeline from
+  XML input to rendered HTML before submitting patches.
+
+== What is covered
+
+* <<architecture, Architecture>> -- The major modules and how they fit
+  together.
+* <<content-pipeline, Content Pipeline>> -- The step-by-step data flow
+  from XML input to final output.
+* <<data-models, Data Models>> -- The Ruby classes that represent
+  parsed and computed document data.

data/exe/docbook

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "docbook"
+require "docbook/cli"
+
+Docbook::CLI.start(ARGV)

data/frontend/dist/app.css

@@ -0,0 +1 @@
+.modal-enter-active[data-v-bc71f312],.modal-leave-active[data-v-bc71f312]{transition:opacity .2s ease}.modal-enter-from[data-v-bc71f312],.modal-leave-to[data-v-bc71f312]{opacity:0}.modal-enter-active>div[data-v-bc71f312]:last-child,.modal-leave-active>div[data-v-bc71f312]:last-child{transition:transform .2s ease,opacity .2s ease}.modal-enter-from>div[data-v-bc71f312]:last-child,.modal-leave-to>div[data-v-bc71f312]:last-child{transform:scale(.95);opacity:0}.reference-entry[data-v-3a1b793d]{font-family:Inter,system-ui,-apple-system,sans-serif}.reference-name[data-v-3a1b793d]{font-family:JetBrains Mono,Fira Code,ui-monospace,monospace}.reference-badge[data-v-3a1b793d]{letter-spacing:.05em}.ebook-topbar[data-v-b409adda]{position:fixed;top:0;left:0;right:0;z-index:30;background:#ffffffe6;-webkit-backdrop-filter:blur(8px);backdrop-filter:blur(8px);border-bottom:1px solid rgba(0,0,0,.05);transition:left .2s ease}.dark{background:#111827e6;border-bottom-color:#ffffff1a}.ebook-topbar--with-sidebar[data-v-b409adda]{left:280px}@media (max-width: 1023px){.ebook-topbar--with-sidebar[data-v-b409adda]{left:0}}.ebook-topbar button[data-v-b409adda]{min-width:44px;min-height:44px}.theme-day{--ebook-bg: #ffffff;--ebook-bg-secondary: #f9fafb;--ebook-text: #1f2937;--ebook-text-muted: #6b7280;--ebook-accent: #0891b2;--ebook-accent-light: #ecfeff;--ebook-border: #e5e7eb;--ebook-code-bg: #1f2937;--ebook-code-text: #e5e7eb;--ebook-example-bg: #f0fdf4;--ebook-example-border: #22c55e;--ebook-reference-accent: #0891b2;--ebook-reference-bg: rgba(8, 145, 178, .03);--ebook-reference-name: #0e7490;--ebook-reference-badge-bg: #f3f4f6;--ebook-reference-badge-text: #6b7280}.theme-sepia{--ebook-bg: #fdf6e3;--ebook-bg-secondary: #f5efe0;--ebook-text: #5c5347;--ebook-text-muted: #8b7355;--ebook-accent: #b8860b;--ebook-accent-light: #fef9e7;--ebook-border: #e0d5c0;--ebook-code-bg: #3d3d3d;--ebook-code-text: #f5f5dc;--ebook-example-bg: #f0ead6;--ebook-example-border: #8b7355;--ebook-reference-accent: #b8860b;--ebook-reference-bg: rgba(184, 134, 11, .05);--ebook-reference-name: #8b6914;--ebook-reference-badge-bg: #e8dcc8;--ebook-reference-badge-text: #6b5d4d}.theme-sepia body,.theme-sepia{background-color:var(--ebook-bg);color:var(--ebook-text)}.theme-night{--ebook-bg: #111827;--ebook-bg-secondary: #1f2937;--ebook-text: #e5e7eb;--ebook-text-muted: #9ca3af;--ebook-accent: #22d3ee;--ebook-accent-light: rgba(34, 211, 238, .1);--ebook-border: #374151;--ebook-code-bg: #030712;--ebook-code-text: #e5e7eb;--ebook-example-bg: rgba(34, 197, 94, .1);--ebook-example-border: #22c55e;--ebook-reference-accent: #22d3ee;--ebook-reference-bg: rgba(34, 211, 238, .05);--ebook-reference-name: #22d3ee;--ebook-reference-badge-bg: #374151;--ebook-reference-badge-text: #9ca3af}.theme-night body,.theme-night{background-color:var(--ebook-bg);color:var(--ebook-text)}.theme-oled{--ebook-bg: #000000;--ebook-bg-secondary: #0a0a0a;--ebook-text: #ffffff;--ebook-text-muted: #a1a1aa;--ebook-accent: #60a5fa;--ebook-accent-light: rgba(96, 165, 250, .1);--ebook-border: #27272a;--ebook-code-bg: #18181b;--ebook-code-text: #fafafa;--ebook-example-bg: rgba(34, 197, 94, .05);--ebook-example-border: #22c55e;--ebook-reference-accent: #60a5fa;--ebook-reference-bg: rgba(96, 165, 250, .03);--ebook-reference-name: #60a5fa;--ebook-reference-badge-bg: #27272a;--ebook-reference-badge-text: #a1a1aa}.theme-oled body,.theme-oled{background-color:var(--ebook-bg);color:var(--ebook-text)}body{background-color:var(--ebook-bg, #ffffff);color:var(--ebook-text, #1f2937);transition:background-color .2s ease,color .2s ease}.ebook-container{font-size:var(--ebook-font-size, 18px);font-weight:var(--ebook-font-weight, 400);line-height:var(--ebook-line-height, 1.6)}.ebook-container.theme-day,.ebook-container.theme-sepia,.ebook-container.theme-night,.ebook-container.theme-oled{--bg: var(--ebook-bg);--text: var(--ebook-text)}*{box-sizing:border-box}html{scroll-behavior:smooth}body{font-family:Inter,system-ui,sans-serif;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}body.font-serif{font-family:Merriweather,Georgia,serif}body.font-sans{font-family:Inter,system-ui,sans-serif}.font-mono{font-family:JetBrains Mono,ui-monospace,monospace}.dark{color-scheme:dark}@media print{.lg\:translate-x-0,#sidebar,#sidebar-toggle,.sticky{display:none!important}}.toc-active{color:#2563eb;background:#dbeafe}.dark .toc-active{color:#60a5fa;background:#1e3a5f}.db-bibentry{padding-left:2em;text-indent:-2em;margin-bottom:.5em}.db-changelog-release{border-left:3px solid #60a5fa;padding-left:1rem;margin:1.5rem 0}.dark .db-changelog-release{border-left-color:#3b82f6}.db-appendix-wrap{border-left:4px solid #8b5cf6;padding-left:1rem;margin-left:-1rem}.dark .db-appendix-wrap{border-left-color:#a78bfa}.db-preface-wrap{border-left:4px solid #22c55e;padding-left:1rem;margin-left:-1rem}.dark .db-preface-wrap{border-left-color:#16a34a}mark.bg-yellow-200,mark.bg-yellow-600{padding:0 2px;border-radius:2px}[x-cloak]{display:none!important}::-webkit-scrollbar{width:8px;height:8px}::-webkit-scrollbar-track{background:transparent}::-webkit-scrollbar-thumb{background:#cbd5e1;border-radius:4px}.dark ::-webkit-scrollbar-thumb{background:#4b5563}::-webkit-scrollbar-thumb:hover{background:#94a3b8}.dark ::-webkit-scrollbar-thumb:hover{background:#6b7280}.db-content h1{font-size:1.875rem;font-weight:700;margin-bottom:1rem}.db-content h2{font-size:1.25rem;font-weight:600;margin-top:2rem;margin-bottom:.75rem}.db-content h3{font-size:1.125rem;font-weight:600;margin-top:1.5rem;margin-bottom:.5rem}.db-content p{margin-bottom:1rem;line-height:1.75}.db-content ul,.db-content ol{margin-bottom:1rem;padding-left:1.5rem}.db-content li{margin-bottom:.25rem;line-height:1.6}.db-content code{font-family:JetBrains Mono,ui-monospace,monospace;font-size:.875em;background:#f1f5f9;padding:.125rem .375rem;border-radius:.25rem}.dark .db-content code{background:#374151}.db-content pre{font-family:JetBrains Mono,ui-monospace,monospace;font-size:.875rem;background:#f1f5f9;padding:1rem;border-radius:.5rem;overflow-x:auto;margin-bottom:1rem}.dark .db-content pre{background:#1f2937}.db-content a{color:#2563eb;text-decoration:underline}.dark .db-content a{color:#60a5fa}.db-content img{max-width:100%;height:auto;border-radius:.5rem;box-shadow:0 4px 6px -1px #0000001a}.dark .db-content img{box-shadow:0 4px 6px -1px #0000004d}.db-content blockquote{border-left:4px solid #d1d5db;padding-left:1rem;margin:1rem 0;font-style:italic;color:#6b7280}.dark .db-content blockquote{border-left-color:#4b5563;color:#9ca3af}.db-content table{width:100%;border-collapse:collapse;margin-bottom:1rem}.db-content th,.db-content td{border:1px solid #e5e7eb;padding:.5rem;text-align:left}.dark .db-content th,.dark .db-content td{border-color:#374151}.db-content th{background:#f9fafb;font-weight:600}.dark .db-content th{background:#1f2937}