docbook 0.1.0

data/docs/advanced/element-classes.adoc

@@ -0,0 +1,185 @@
+---
+layout: default
+title: Element Class Design
+parent: Advanced
+nav_order: 3
+---
+
+# Element Class Design
+
+Every supported DocBook XML element is represented by a Ruby class in
+the `Docbook::Elements` namespace. This page explains the design
+patterns and how to add new element types.
+
+== Base class
+
+All element classes inherit from `Lutaml::Model::Serializable`, which
+provides:
+
+* Automatic XML parsing and serialization via `from_xml` / `to_xml`
+* JSON serialization via `to_json`
+* Attribute declaration with type checking
+* Mixed content handling
+
+== DSL methods
+
+The lutaml-model DSL provides several methods for declaring how an
+element maps to Ruby attributes:
+
+=== attribute
+
+Declares a typed attribute on the class. Basic types include `:string`,
+`:integer`, and `:float`. Complex types reference other element classes.
+
+[source,ruby]
+----
+attribute :content, :string
+attribute :role, :string
+attribute :xml_id, Lutaml::Xml::W3c::XmlIdType
+attribute :title, Title
+attribute :section, Section, collection: true
+----
+
+The `collection: true` option indicates that the attribute holds an
+array of values rather than a single value.
+
+=== mixed_content
+
+Declares that the element can contain a mix of text and child elements.
+This is essential for elements like `<para>` that contain both raw text
+and inline markup (`<emphasis>`, `<code>`, `<link>`, etc.).
+
+[source,ruby]
+----
+xml do
+  element "para"
+  mixed_content
+end
+----
+
+=== map_content
+
+Maps the element's text content (the text between tags) to an attribute.
+
+[source,ruby]
+----
+xml do
+  map_content to: :content
+end
+----
+
+=== map_element
+
+Maps a child XML element to a Ruby attribute. The first argument is the
+XML element name; the `to:` option specifies the Ruby attribute.
+
+[source,ruby]
+----
+xml do
+  map_element "title", to: :title
+  map_element "para", to: :para
+  map_element "section", to: :section
+end
+----
+
+=== map_attribute
+
+Maps an XML attribute to a Ruby attribute.
+
+[source,ruby]
+----
+xml do
+  map_attribute "role", to: :role
+  map_attribute "xml:id", to: :xml_id
+  map_attribute "xlink:href", to: :xlink_href
+end
+----
+
+== Mixed content traversal
+
+Elements that declare `mixed_content` support the `each_mixed_content`
+method. This method yields each child node in document order, as either
+a `String` (for text nodes) or a typed element object.
+
+[source,ruby]
+----
+element.each_mixed_content do |node|
+  case node
+  when String
+    # Handle text content
+  when Docbook::Elements::Emphasis
+    # Handle <emphasis> inline element
+  when Docbook::Elements::Link
+    # Handle <link> inline element
+  end
+end
+----
+
+This pattern is the foundation of the HTML generator's content
+rendering. The `build_inline_content` and `build_element_content`
+methods in `Output::Html` use `each_mixed_content` exclusively to
+process element children.
+
+== Adding a new element
+
+To add support for a new DocBook element:
+
+. **Create the element class** in `lib/docbook/elements/`. The file
+  name should match the element name (for example, `acknowledgements.rb`
+  for `<acknowledgements>`). Declare attributes and XML mappings.
+
+. **Add an autoload entry** in `lib/docbook/elements.rb`:
++
+[source,ruby]
+----
+autoload :NewElement, "#{__dir__}/elements/new_element"
+----
+
+. **Add the attribute to the parent element**. If `<newelement>` can
+  appear inside `<chapter>`, add it to the `Chapter` class:
++
+[source,ruby]
+----
+attribute :newelement, NewElement, collection: true
+# and in the xml block:
+map_element "newelement", to: :newelement
+----
+
+. **Add a case in the HTML generator**. In `lib/docbook/output/html.rb`,
+  add a `when` branch in the appropriate `case` statement (either
+  `build_element_content` or `build_inline_content`) to handle the new
+  element type and produce the corresponding `ContentBlock`.
+
+. **Add to ROOT_ELEMENT_MAP** if the element can be a document root.
+  In `lib/docbook/document.rb`, add an entry like:
++
+[source,ruby]
+----
+"newelement" => Elements::NewElement,
+----
+
+== ROOT_ELEMENT_MAP
+
+The `Document::ROOT_ELEMENT_MAP` constant maps XML root element names
+to their Ruby classes. This map is used by `Document.from_xml` to
+dispatch parsing. The map currently supports 37 root element types
+including `article`, `book`, `chapter`, `section`, `appendix`,
+`refentry`, `bibliography`, `glossary`, `set`, `reference`, `topic`,
+and all numbered section variants (`sect1` through `sect5`,
+`refsect1` through `refsect3`).
+
+== Collections
+
+Many attributes use `collection: true` because DocBook elements can
+appear multiple times within their parent. For example, a `<book>`
+can contain multiple `<chapter>` elements:
+
+[source,ruby]
+----
+attribute :chapter, Chapter, collection: true
+----
+
+The lutaml-model library automatically accumulates multiple XML
+elements into the array. In code, always use `Array(value)` when
+iterating over collection attributes, since they may be `nil` when
+no child elements are present.

data/docs/advanced/frontend-customization.adoc

@@ -0,0 +1,193 @@
+---
+layout: default
+title: Frontend Customization
+parent: Advanced
+nav_order: 2
+---
+
+# Frontend Customization
+
+The HTML output includes a Vue 3 single-page application that provides
+an interactive ebook reader experience. This page describes the
+frontend architecture and how to customize it.
+
+== Build toolchain
+
+The frontend lives in the `frontend/` directory at the project root.
+It uses the following toolchain:
+
+* **Vue 3** (v3.4+) with the Composition API
+* **TypeScript** for type safety
+* **Vite** (v5.2+) for building
+* **Pinia** for state management
+* **FlexSearch** for client-side full-text search
+
+Build the frontend with:
+
+....
+cd frontend
+npm install
+npm run build
+....
+
+This produces two files in `frontend/dist/`:
+
+* `app.css` -- The compiled stylesheet
+* `app.iife.js` -- The bundled JavaScript (IIFE format)
+
+These files are copied into the HTML output by the Ruby generator.
+
+== Components
+
+The Vue application consists of the following components:
+
+=== EbookContainer
+
+The top-level layout component. It renders the sidebar, content area,
+and settings panel. It manages the overall layout state and applies
+theme CSS classes to the root container.
+
+=== AppSidebar
+
+The left sidebar containing the table of contents tree. It uses
+`TocTreeItem` components recursively to render the nested section
+hierarchy. Clicking a TOC entry navigates to the corresponding section.
+
+=== ContentRenderer
+
+Responsible for rendering the main document content. It looks up the
+active section's content blocks from the `documentStore` and delegates
+to `BlockRenderer` for each block.
+
+=== BlockRenderer
+
+A recursive component that renders a single `ContentBlock`. It
+switches on the block's `type` to produce the appropriate HTML:
+paragraphs, code blocks, images, lists, admonitions, and so on.
+
+=== SearchModal
+
+A full-screen search overlay powered by FlexSearch. It indexes TOC
+titles and provides instant search-as-you-type results. The search
+index is persisted in IndexedDB to avoid rebuilding on each page load.
+
+=== SettingsPanel
+
+A slide-out panel for reading preferences: theme selection, font size,
+line height, margin width, and reading mode. Settings are persisted
+in localStorage via the `useEbookStore` composable.
+
+=== TocTreeItem
+
+Renders a single entry in the table of contents tree, including its
+section number and expand/collapse toggle for nested children.
+
+=== ReferenceEntry
+
+A specialized component for rendering `<refentry>` elements (man-page
+style reference entries) with their badge, name, definition, and
+description sections.
+
+== State management
+
+=== documentStore (Pinia)
+
+The central data store. It loads document data from
+`window.DOCBOOK_DATA` (single-file mode) or fetches
+`docbook.data.json` (directory mode). It exposes computed properties
+for `title`, `sections`, `numbering`, `content`, and `index`, plus a
+`getSectionContent(id)` lookup method.
+
+=== uiStore (Pinia)
+
+Manages UI state: theme (light/dark/system), font family
+(sans/serif), sidebar visibility, search visibility, and the active
+section ID. Theme and font preferences are persisted in localStorage.
+
+== Composables
+
+=== useSearch
+
+Provides full-text search over TOC entries using FlexSearch. The
+composable builds a `Document` index with forward tokenization and
+persists the serialized index in IndexedDB. On subsequent loads, it
+attempts to restore the index from IndexedDB before rebuilding.
+
+=== useEbookStore
+
+A global singleton (not Pinia-based) that manages reading preferences:
+reading mode, font size, font weight, line height, margin, and theme.
+It uses a reactive state object with `watch`-based auto-persistence
+to localStorage. Available themes are:
+
+[cols="1,1,3"]
+|===
+| Theme | Description | Background
+
+| `day`
+| Light theme
+| White background
+
+| `sepia`
+| Warm reading theme
+| Cream/parchment background
+
+| `night`
+| Dark theme
+| Dark gray background
+
+| `oled`
+| Pure black theme
+| Black background (for OLED screens)
+|===
+
+Reading modes:
+
+[cols="1,3"]
+|===
+| Mode | Description
+
+| `scroll`
+| Continuous scrolling through all content
+
+| `page`
+| Paginated view with page-turn navigation
+
+| `chapter`
+| One chapter at a time with next/previous navigation
+
+| `reference`
+| Compact layout for reference entry pages
+|===
+
+== Fonts
+
+The frontend loads three font families from Google Fonts:
+
+[cols="1,1,2"]
+|===
+| Font | CSS family | Usage
+
+| Inter
+| `font-sans`
+| Body text, UI elements
+
+| Merriweather
+| `font-serif`
+| Reading mode serif option
+
+| JetBrains Mono
+| `font-mono`
+| Code blocks, inline code
+|===
+
+== Customizing the frontend
+
+To modify the reader's appearance or behavior:
+
+. Edit the Vue components in `frontend/src/`.
+. Run `npm run build` in the `frontend/` directory.
+. Regenerate the HTML output using the `docbook to-html` command.
+
+The Ruby generator always uses the latest built assets from
+`frontend/dist/`, so changes take effect immediately after rebuilding.

data/docs/advanced/index.adoc

@@ -0,0 +1,14 @@
+---
+layout: default
+title: Advanced
+nav_order: 6
+has_children: true
+---
+
+# Advanced
+
+This section covers advanced topics for developers who want to customize
+or extend the Metanorma DocBook gem beyond its default behavior.
+
+Topics include the Liquid template system, frontend customization, and
+the design patterns behind element classes.

data/docs/advanced/templates.adoc

@@ -0,0 +1,123 @@
+---
+layout: default
+title: Liquid Templates
+parent: Advanced
+nav_order: 1
+---
+
+# Liquid Templates
+
+The HTML output is generated using the Liquid template engine. Templates
+are located in `lib/docbook/templates/`. The system uses Liquid's
+`LocalFileSystem` for partial resolution, so `{% include 'partials/head' %}`
+resolves to `templates/partials/_head.liquid`.
+
+== Template files
+
+=== document.html.liquid
+
+The main template. It produces a complete HTML5 document with:
+
+* A `<head>` section that includes the `_head` partial (fonts, Tailwind
+  CSS, Prism.js styles, and the app CSS).
+* A `<div id="docbook-app">` mount point for the Vue SPA.
+* An inline `<script>` block that defines `window.DOCBOOK_DATA` with
+  placeholder tokens for JSON data.
+* The `_scripts` partial (Prism.js and the app JavaScript).
+
+=== partials/_head.liquid
+
+Provides the document head content:
+
+* **Prism.js CSS** -- Syntax highlighting theme loaded from cdnjs.
+* **Google Fonts** -- Inter (sans-serif), Merriweather (serif), and
+  JetBrains Mono (monospace) loaded from Google Fonts CDN.
+* **Tailwind CSS** -- The Tailwind CDN script with a custom
+  configuration that sets `darkMode: 'class'` and registers the three
+  font families.
+* **Custom styles** -- Inline `<style>` block with TOC active states,
+  bibliography entry indentation, and appendix border styling.
+* **App CSS** -- Conditionally inlined or linked. When `assets_inline`
+  is true (single-file mode), the CSS is embedded in a `<style>` tag.
+  In directory mode, it is loaded from `assets/app.css`.
+
+=== partials/_scripts.liquid
+
+Provides the document scripts:
+
+* **Prism.js** -- Core library and autoloader plugin from cdnjs for
+  syntax highlighting of code blocks.
+* **App JS** -- Conditionally inlined or linked. When `assets_inline`
+  is true, the JavaScript is embedded in a `<script>` tag. In directory
+  mode, it is loaded from `assets/app.iife.js`.
+
+== Template variables
+
+The following variables are passed to the Liquid template by the Ruby
+HTML generator:
+
+[cols="1,1,4"]
+|===
+| Variable | Type | Description
+
+| `docbook_title`
+| String
+| The document title, extracted from the root element.
+
+| `base_url`
+| String
+| The base URL for asset references. `"."` in directory mode, `""`
+  in single-file mode.
+
+| `assets_inline`
+| Boolean
+| When true, CSS and JS are inlined. When false, they are linked.
+
+| `app_css`
+| String
+| The contents of `frontend/dist/app.css`.
+
+| `app_js`
+| String
+| The contents of `frontend/dist/app.iife.js`.
+|===
+
+== Placeholder tokens
+
+The main template uses four placeholder tokens that are replaced via
+Ruby string substitution (`gsub`) after Liquid rendering:
+
+`[[DOCBOOK_DATA]]`::
+Replaced with the `DocumentData` JSON (title only) in single-file mode,
+or `null /* loaded from docbook.data.json */` in directory mode.
+
+`[[DOCBOOK_TOC]]`::
+Replaced with the full TOC JSON (sections tree + numbering) in
+single-file mode, or `null` in directory mode.
+
+`[[DOCBOOK_CONTENT]]`::
+Replaced with the content data JSON (keyed by section ID) in
+single-file mode, or `null` in directory mode.
+
+`[[DOCBOOK_INDEX]]`::
+Replaced with the index data JSON (grouped by letter) in single-file
+mode, or `null` in directory mode.
+
+The use of string substitution rather than Liquid variables is
+intentional: the JSON payloads are large and may contain characters
+(like `{%`) that would conflict with Liquid's template syntax.
+
+== Output modes
+
+=== Single-file mode
+
+All data is embedded inline. The resulting HTML file is self-contained
+and can be opened directly in a browser without a web server. The
+JSON is injected into `window.DOCBOOK_DATA` using `Object.assign()`.
+
+=== Directory mode
+
+The JSON is written to `docbook.data.json`. The template placeholders
+are set to `null`, and the Vue SPA's `documentStore.loadFromWindow()`
+detects that inline data is absent and fetches the external JSON file
+instead. CSS and JS assets are linked from the `assets/` subdirectory.