docbook 0.1.0

data/docs/interfaces/ruby-api/xref-resolution.adoc

@@ -0,0 +1,156 @@
+---
+layout: default
+title: XRef Resolution
+parent: Ruby API
+grand_parent: Interfaces
+nav_order: 4
+---
+
+== XRef Resolution
+
+The `Docbook::XrefResolver` class builds an `xml:id` lookup map from a parsed DocBook document and provides methods to resolve cross-references (`xref` elements and `linkend` attributes) to their target titles.
+
+=== Why Resolve Cross-References
+
+DocBook uses `xml:id` attributes to identify elements and `linkend` attributes on `<xref>` elements to reference them. When generating HTML, you typically want to display the target's title text rather than the raw ID. The `XrefResolver` provides an O(1) lookup for resolving these references.
+
+=== Creating a Resolver
+
+[source,ruby]
+----
+require "docbook"
+
+# Parse the document
+xml_string = File.read("book.xml")
+document = Docbook::Document.from_xml(xml_string)
+
+# Create and resolve
+xref_resolver = Docbook::XrefResolver.new(document).resolve!
+----
+
+The `resolve!` method traverses the entire document tree, collects all elements with `xml:id` attributes, and builds a hash map. It returns `self` so you can chain calls.
+
+=== Resolving Cross-Reference Titles
+
+Use `title_for(linkend)` to look up the title text for a given `xml:id`:
+
+[source,ruby]
+----
+# Look up the title for a specific xml:id
+title = xref_resolver.title_for("intro")
+# => "Introduction"
+
+title = xref_resolver.title_for("chapter-1")
+# => "Getting Started"
+
+title = xref_resolver.title_for("nonexistent-id")
+# => nil (no element with this ID)
+----
+
+This is used internally by `Docbook::Output::Html` to resolve `<xref linkend="intro"/>` into the text "Introduction" in the generated HTML.
+
+=== Retrieving Elements by ID
+
+Use the `[]` operator to retrieve the actual element object for a given `xml:id`:
+
+[source,ruby]
+----
+# Get the element with xml:id="intro"
+element = xref_resolver["intro"]
+# => #<Docbook::Elements::Section:0x0000...>
+
+element.title.content  # => "Introduction"
+element.xml_id         # => "intro"
+----
+
+This returns the parsed element object, giving you full access to its attributes and child elements.
+
+=== How the ID Map Works
+
+The `resolve!` method recursively traverses the document tree, visiting each element and recording those that have an `xml:id` attribute. The traversal is type-aware -- it knows which child collections to visit for each element type:
+
+[cols="2,5"]
+|===
+| Element Type | Child Collections Traversed
+
+| `Book` | `part`, `chapter`, `appendix`, `preface`, `glossary`, `bibliography`, `index`
+| `Article` | `section`
+| `Part` | `chapter`, `appendix`, `reference`, `glossary`, `bibliography`, `index`
+| `Chapter`, `Appendix`, `Section`, `Preface` | `section`
+| `Reference` | `refentry`
+|===
+
+=== Title Extraction
+
+The resolver uses different strategies to extract titles depending on the element type:
+
+[cols="2,5"]
+|===
+| Element Type | Title Source
+
+| `Article`, `Book` | `info.title.content`
+| `Section`, `Chapter`, `Appendix`, `Preface`, `Part`, `Reference` | `title.content` (or `info.title.content` as fallback)
+| Other elements | `title.content` (best-effort via `rescue nil`)
+|===
+
+=== Complete Example
+
+A full workflow that parses, resolves cross-references, and generates HTML:
+
+[source,ruby]
+----
+require "docbook"
+
+# Parse the document
+xml_string = File.read("book.xml")
+document = Docbook::Document.from_xml(xml_string)
+
+# Build the cross-reference map
+xref_resolver = Docbook::XrefResolver.new(document).resolve!
+
+# Look up specific elements
+chapter_element = xref_resolver["chapter-1"]
+puts "Chapter 1: #{chapter_element.title.content}"
+# => "Chapter 1: Getting Started"
+
+# Resolve an xref to its target title
+xref_title = xref_resolver.title_for("chapter-1")
+puts "XRef target: #{xref_title}"
+# => "XRef target: Getting Started"
+
+# Now generate HTML with resolved cross-references
+html = Docbook::Output::Html.new(
+  document,
+  xref_resolver: xref_resolver,
+  output_mode: :single_file,
+  base_path: File.dirname(File.expand_path("book.xml"))
+).to_html
+
+File.write("output.html", html)
+----
+
+=== Integration with HTML Output
+
+The `XrefResolver` is designed to work with `Docbook::Output::Html`. Pass the resolver to the HTML generator's constructor, and it will automatically resolve all `<xref>` elements:
+
+[source,ruby]
+----
+# Without xref_resolver: <xref linkend="intro"/> renders as "intro"
+# With xref_resolver: <xref linkend="intro"/> renders as "Introduction"
+
+html_with_xrefs = Docbook::Output::Html.new(
+  document,
+  xref_resolver: xref_resolver,
+  output_mode: :single_file
+).to_html
+----
+
+=== Element Lookup Fallback
+
+When the `XrefResolver` cannot find an element by ID, the HTML generator falls back to a recursive document search via `find_in_document`. This provides a safety net for elements that may not be captured by the type-aware traversal (for example, deeply nested elements in unusual structures).
+
+=== See Also
+
+* *<<parsing,Parsing Documents>>* -- Parse XML into element models before resolving xrefs
+* *<<html-output,HTML Output>>* -- Use the resolver when generating HTML
+* *<<xinclude,XInclude Resolution>>* -- Resolve XIncludes before parsing (so included elements get their IDs registered)

data/docs/lychee.toml

@@ -0,0 +1,42 @@
+# Lychee Link Checker Configuration
+# For Metanorma DocBook Documentation
+
+cache = true
+max_cache_age = "1d"
+include_verbatim = true
+
+include = [
+  "_site/**/*.html",
+  ".*\\.adoc$",
+  ".*\\.md$"
+]
+
+exclude = [
+  ".git",
+  ".github",
+  "node_modules",
+  "vendor",
+  ".bundle",
+  ".sass-cache",
+  ".jekyll-cache",
+  "_site/.jekyll-cache",
+  "Gemfile.lock"
+]
+
+max_redirects = 10
+max_retries = 3
+timeout = 30
+
+accept = [
+  "100..=103",
+  "200..=299",
+  "429"
+]
+
+user_agent = "lychee/docbook-docs-link-checker"
+scheme = ["https", "http", "file"]
+include_mail = false
+max_concurrency = 10
+verbose = "warn"
+require_https = false
+index_files = ["index.html"]

data/docs/reference/cli-options.adoc

@@ -0,0 +1,155 @@
+---
+layout: default
+title: CLI Options
+parent: Reference
+nav_order: 1
+---
+
+# CLI Options
+
+The `docbook` command-line tool is built on Thor. It provides four
+commands: `format`, `validate`, `to-html`, and `roundtrip`.
+
+== Global behavior
+
+* The executable is `docbook` (installed to `exe/`).
+* All commands that accept `INPUT` take a file path argument.
+* The tool exits with code 0 on success and code 1 on failure.
+* Error messages are written to stderr.
+
+== format
+
+Formats and prettifies a DocBook XML file.
+
+....
+docbook format INPUT [options]
+....
+
+[cols="1,1,1,1,3"]
+|===
+| Option | Alias | Default | Description
+
+| `--output PATH`
+| `-o`
+| stdout
+| Output file path. When omitted, the formatted XML is written to
+  standard output.
+
+| `--xinclude`
+| _(none)_
+| `false`
+| Resolve XInclude directives before formatting.
+|===
+
+The command parses the input XML, then re-serializes it with pretty
+printing (indentation) and an XML declaration with UTF-8 encoding.
+
+== validate
+
+Checks whether a DocBook XML file is well-formed.
+
+....
+docbook validate INPUT
+....
+
+This command has no options. It reads the file, parses it with
+Nokogiri, and checks for parse errors. If the document is well-formed,
+it prints `INPUT: valid`. If errors are found, each error is printed
+to stderr and the command exits with code 1.
+
+Note: this validates XML well-formedness only, not DocBook schema
+conformance.
+
+== to-html
+
+Converts a DocBook XML file to an interactive HTML page.
+
+....
+docbook to-html INPUT [options]
+....
+
+[cols="1,1,1,1,3"]
+|===
+| Option | Alias | Default | Description
+
+| `--output PATH`
+| `-o`
+| stdout
+| Output file path (single-file mode) or output directory path
+  (directory mode).
+
+| `--xinclude`
+| _(none)_
+| `true`
+| Resolve XInclude directives before processing. Enabled by default
+  for the `to-html` command.
+
+| `--output-type TYPE`
+| _(none)_
+| `single_file`
+| Output type: `single_file` or `directory`. In single-file mode,
+  all data is inlined into one HTML file. In directory mode, JSON
+  data and assets are written as separate files.
+|===
+
+=== Single-file mode
+
+....
+docbook to-html book.xml -o output.html
+...
+
+Produces a single `output.html` file with all JSON data, CSS, and
+JavaScript embedded inline. The file can be opened directly in a
+browser without a web server.
+
+=== Directory mode
+
+....
+docbook to-html book.xml -o my-book --output-type directory
+....
+
+Creates a `my-book/` directory containing:
+
+* `index.html` -- HTML shell with Vue SPA mount point
+* `docbook.data.json` -- Full document data as JSON
+* `assets/app.css` -- Compiled stylesheet
+* `assets/app.iife.js` -- Bundled JavaScript
+
+The directory mode requires the `--output` option.
+
+== roundtrip
+
+Tests that DocBook XML files can be parsed and re-serialized
+successfully.
+
+....
+docbook roundtrip INPUT [INPUT...]
+....
+
+This command has no options. It accepts one or more file paths. For
+each file, it parses the XML, serializes it back, re-parses the output,
+and reports success or failure. At the end, it prints a summary of
+total files and failure count.
+
+== Quick reference table
+
+[cols="1,1,1"]
+|===
+| Command | Input | Output
+
+| `format`
+| File path
+| Pretty-printed XML (file or stdout)
+
+| `validate`
+| File path
+| Pass/fail status
+
+| `to-html`
+| File path
+| HTML file or directory
+
+| `roundtrip`
+| One or more file paths
+| Pass/fail status per file
+|===

data/docs/reference/content-block-types.adoc

@@ -0,0 +1,243 @@
+---
+layout: default
+title: Content Block Types
+parent: Reference
+nav_order: 3
+---
+
+# Content Block Types
+
+The HTML generator produces structured content using `ContentBlock`
+instances. Each block has a `type` field that determines how the Vue
+SPA renders it. This page lists all block types used in the system.
+
+== Block-level types
+
+These types represent top-level content blocks within a section.
+
+[cols="1,3"]
+|===
+| Type | Description
+
+| `paragraph`
+| A paragraph of text, potentially containing inline child blocks.
+
+| `code`
+| A code listing. The `language` attribute specifies the language for
+  syntax highlighting. The `text` attribute holds the source code.
+
+| `image`
+| An image block. The `src` attribute holds the image URL (either a
+  file path or a base64 data URI). The `alt` attribute provides
+  alternative text. The `title` attribute provides an optional caption.
+
+| `blockquote`
+| A block quotation. The `text` attribute holds the attribution.
+  Children contain the quoted paragraphs.
+
+| `ordered_list`
+| A numbered list. Children are `list_item` blocks.
+
+| `itemized_list`
+| A bulleted list. Children are `list_item` blocks.
+
+| `list_item`
+| A single list item. Children contain the item's content blocks.
+
+| `definition_list`
+| A definition list (variable list in DocBook). Children alternate
+  between `definition_term` and `definition_description` blocks.
+
+| `definition_term`
+| The term being defined. Children contain inline content.
+
+| `definition_description`
+| The definition body. Children contain block-level content.
+
+| `note`
+| An informational note admonition. Children contain the note body.
+  The `text` attribute holds an optional title.
+
+| `warning`
+| A warning admonition about potential problems.
+
+| `caution`
+| A caution admonition about unexpected behavior.
+
+| `important`
+| An important information admonition.
+
+| `tip`
+| A helpful suggestion admonition.
+
+| `danger`
+| A danger admonition about risk of harm.
+
+| `example`
+| A formal example. The `text` attribute holds the example title.
+  Children contain the example content (code blocks, paragraphs, etc.).
+
+| `example_output`
+| An informal example output block. Children contain the content.
+
+| `section`
+| A nested section within a parent block. Children contain the
+  section's content blocks, typically starting with a `heading`.
+
+| `heading`
+| A section heading. The `text` attribute holds the heading text.
+|===
+
+== Inline types
+
+These types appear as children of `paragraph` and other block-level
+types. They represent inline formatting and links.
+
+[cols="1,3"]
+|===
+| Type | Description
+
+| `text`
+| Plain text content.
+
+| `strong`
+| Bold text. Rendered from `<emphasis role="bold">`.
+
+| `italic`
+| Italic text. Rendered from `<emphasis role="italic">`.
+
+| `emphasis`
+| Emphasized text (default rendering from `<emphasis>` with no role).
+
+| `codetext`
+| Inline monospace code. Rendered from `<code>`, `<literal>`,
+  `<filename>`, `<classname>`, `<function>`, `<parameter>`, and
+  other technical inline elements.
+
+| `link`
+| A hyperlink. The `src` attribute holds the URL. The `text` attribute
+  holds the display text. Rendered from `<link>` and `<citetitle>`
+  with an `href` attribute.
+
+| `biblioref`
+| A bibliographic reference. The `src` attribute holds a fragment
+  link to the bibliography entry. Rendered from `<biblioref>`.
+
+| `citation`
+| A bibliographic citation without a link. Rendered from `<citetitle>`
+  without an `href`.
+
+| `citation_link`
+| A citable title with a hyperlink. Rendered from `<citetitle>` with
+  an `href` attribute.
+
+| `xref`
+| An internal cross-reference. The `src` attribute holds the fragment
+  link (`#id`). The `text` attribute holds the resolved title of the
+  target element. Rendered from `<xref>`.
+
+| `inline_image`
+| An inline image within text flow. The `src` attribute holds the
+  image URL. Rendered from `<inlinemediaobject>`.
+|===
+
+== Bibliography types
+
+These types represent structured bibliography entries.
+
+[cols="1,3"]
+|===
+| Type | Description
+
+| `bibliography_entry`
+| A single bibliography entry. Children contain the entry's parts.
+
+| `biblio_abbrev`
+| The abbreviation or citation key for the entry.
+
+| `biblio_citetitle`
+| The title of the cited work (without a link).
+
+| `biblio_personname`
+| A person's name (first + surname) from `<personname>`.
+
+| `biblio_firstname`
+| A person's first name.
+
+| `biblio_surname`
+| A person's surname.
+
+| `biblio_orgname`
+| An organization name.
+
+| `biblio_publishername`
+| A publisher's name.
+
+| `biblio_pubdate`
+| The publication date.
+
+| `biblio_bibliosource`
+| A bibliographic source reference.
+|===
+
+== Index types
+
+These types represent the generated index content.
+
+[cols="1,3"]
+|===
+| Type | Description
+
+| `index_section`
+| The top-level index section. The `text` attribute holds the index
+  title. Children contain `index_letter` blocks.
+
+| `index_letter`
+| A letter group in the index. The `text` attribute holds the letter.
+  Children contain `index_entry` blocks.
+
+| `index_entry`
+| A single index entry. Children contain the term text and
+  cross-references.
+
+| `index_reference`
+| A link from an index entry to the section where the term appears.
+  The `src` attribute holds the section fragment link. The `text`
+  attribute holds the section title.
+
+| `index_see`
+| A "see" cross-reference to another index term.
+
+| `index_see_also`
+| A "see also" cross-reference to a related term.
+|===
+
+== Reference entry types
+
+These types represent `<refentry>` (man-page style) content.
+
+[cols="1,3"]
+|===
+| Type | Description
+
+| `reference_entry`
+| A complete reference entry. Children contain the entry's parts.
+
+| `reference_meta`
+| Metadata for the reference entry (e.g., manual volume number).
+
+| `reference_badge`
+| A category badge (e.g., "pi" for processing instructions, "param"
+  for parameters). Displayed prominently at the top of the entry.
+
+| `reference_name`
+| The headword or name of the reference entry. This is the primary
+  identifier, derived from `<refname>` or `<refentrytitle>`.
+
+| `reference_definition`
+| The one-line definition from `<refpurpose>`.
+
+| `description_section`
+| A content section within the reference entry, corresponding to a
+  `<refsection>`. Children contain the section's blocks.
+|===

data/docs/reference/glossary.adoc

@@ -0,0 +1,119 @@
+---
+layout: default
+title: Glossary
+parent: Reference
+nav_order: 4
+---
+
+# Glossary
+
+This glossary defines key terms used throughout the Metanorma DocBook
+gem documentation.
+
+DocBook 5::
+An OASIS standard XML vocabulary for marking up technical documents.
+DocBook 5 uses namespaces (`http://docbook.org/ns/docbook`) and
+supports structural elements like books, articles, chapters, sections,
+and a rich set of inline and block elements.
+
+XInclude::
+A W3C standard for including external XML or text files into an XML
+document using `<xi:include>` elements. The gem's `XIncludeResolver`
+handles resolution before model parsing, supporting both XML and text
+parse modes.
+
+fragid::
+A fragment identifier extension used with XInclude text includes.
+Supports `line=` (RFC 5147 line ranges), `char=` (character ranges),
+and `search=` (pattern-based extraction) schemes for pulling specific
+portions of included text files.
+
+xml:id::
+The standard XML attribute for assigning a unique identifier to an
+element. In DocBook, `xml:id` values serve as anchors for
+cross-references (`<xref linkend="...">`) and TOC navigation.
+
+linkend::
+An attribute used by `<xref>` and other referencing elements to point
+to the `xml:id` of a target element. The `XrefResolver` builds an O(1)
+lookup map from `xml:id` values to element objects for efficient
+resolution.
+
+lutaml-model::
+A Ruby library (`Lutaml::Model::Serializable`) that provides a
+declarative DSL for mapping between XML, JSON, and Ruby objects.
+The DocBook gem uses it as the base class for all element and data
+model classes, providing automatic serialization and deserialization.
+
+ContentBlock::
+A data model class (`Docbook::Output::ContentBlock`) representing a
+single unit of content in the HTML output. Each block has a `type`
+(paragraph, code, image, etc.), optional text content, and optional
+children forming a recursive tree. The Vue SPA renders blocks
+using the `BlockRenderer` component.
+
+SectionData::
+A data model class representing a section in the table of contents
+tree. Each entry has an ID, title, type (part, chapter, section, etc.),
+and nested children. The tree is built by the HTML generator and
+serialized as part of the TOC data.
+
+NumberingBuilder::
+A stateful Ruby class that assigns section numbers using different
+schemes: Roman numerals for parts (I, II, III), Arabic numerals for
+chapters (1, 2, 3), hierarchical dotted numbers for sections (1.1,
+1.2.3), and uppercase letters for appendices (A, B, C).
+
+TOC::
+Table of contents. The gem generates a recursive `SectionData` tree
+that represents the document's logical structure. The Vue SPA renders
+this as a collapsible sidebar with expand/collapse navigation.
+
+RefEntry::
+A DocBook element type (`<refentry>`) used for man-page style reference
+documentation. It contains a `refmeta` (metadata), `refnamediv` (name
+and purpose), and `refsection` elements (description content). The gem
+renders RefEntry with specialized content block types.
+
+mixed content::
+An XML concept where an element can contain both text nodes and child
+elements interspersed. For example, `<para>Hello <emphasis>world</emphasis>
+!</para>` has mixed content. The lutaml-model `mixed_content` declaration
+and `each_mixed_content` method handle traversal of these nodes in
+document order.
+
+Vue SPA::
+A Vue 3 single-page application embedded in the generated HTML. It
+provides an interactive ebook reader with a table of contents sidebar,
+search, theme switching, and reading mode selection. The SPA reads
+document data from inline JSON or an external JSON file.
+
+single file mode::
+An output mode where all document data, CSS, and JavaScript are
+embedded into a single HTML file. The resulting file is self-contained
+and can be opened directly in a browser without a web server. JSON data
+is stored in `window.DOCBOOK_DATA`.
+
+directory mode::
+An output mode where the HTML, JSON data, and assets are written as
+separate files in an output directory. The HTML file loads CSS and JS
+from `assets/` and fetches document data from `docbook.data.json` at
+runtime. Requires a web server or local file access.
+
+Liquid template::
+The template engine (Liquid) used to generate the HTML shell. Templates
+are stored in `lib/docbook/templates/` and use partials for the document
+head and scripts. Template variables control asset inlining, and
+placeholder tokens are replaced with JSON data after rendering.
+
+FlexSearch::
+A JavaScript full-text search library used in the Vue SPA for
+client-side search. The search index is built over TOC titles and
+persisted in IndexedDB to avoid rebuilding on each page load. The
+`useSearch` composable manages the search lifecycle.
+
+Prism.js::
+A lightweight syntax highlighting library loaded from cdnjs. It
+provides language-aware code highlighting for `<programlisting>`
+blocks based on the `language` attribute. The autoloader plugin
+loads additional language grammars on demand.