RubyGems - docbook - Versions diffs - 0.1.0 - Mend

docbook 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (271) hide show

checksums.yaml +7 -0
data/CHANGELOG.md +5 -0
data/CLAUDE.md +19 -0
data/CODE_OF_CONDUCT.md +10 -0
data/README.adoc +335 -0
data/Rakefile +12 -0
data/docs/.lycheeignore +33 -0
data/docs/Gemfile +10 -0
data/docs/INDEX.adoc +67 -0
data/docs/_config.yml +186 -0
data/docs/advanced/element-classes.adoc +185 -0
data/docs/advanced/frontend-customization.adoc +193 -0
data/docs/advanced/index.adoc +14 -0
data/docs/advanced/templates.adoc +123 -0
data/docs/features/element-coverage.adoc +373 -0
data/docs/features/html-output/data-model.adoc +285 -0
data/docs/features/html-output/directory-mode.adoc +180 -0
data/docs/features/html-output/index.adoc +90 -0
data/docs/features/html-output/single-file-mode.adoc +125 -0
data/docs/features/index-generation.adoc +197 -0
data/docs/features/index.adoc +63 -0
data/docs/features/numbering.adoc +183 -0
data/docs/features/toc-generation.adoc +150 -0
data/docs/features/xinclude/fragid-schemes.adoc +287 -0
data/docs/features/xinclude/index.adoc +119 -0
data/docs/features/xinclude/text-includes.adoc +123 -0
data/docs/features/xinclude/xml-includes.adoc +167 -0
data/docs/getting-started/index.adoc +50 -0
data/docs/getting-started/installation.adoc +113 -0
data/docs/getting-started/quick-start.adoc +161 -0
data/docs/guides/converting-article.adoc +188 -0
data/docs/guides/converting-book.adoc +192 -0
data/docs/guides/index.adoc +12 -0
data/docs/guides/roundtrip-testing.adoc +129 -0
data/docs/interfaces/cli/format-command.adoc +109 -0
data/docs/interfaces/cli/index.adoc +73 -0
data/docs/interfaces/cli/roundtrip-command.adoc +125 -0
data/docs/interfaces/cli/to-html-command.adoc +178 -0
data/docs/interfaces/cli/validate-command.adoc +104 -0
data/docs/interfaces/index.adoc +101 -0
data/docs/interfaces/ruby-api/html-output.adoc +186 -0
data/docs/interfaces/ruby-api/index.adoc +111 -0
data/docs/interfaces/ruby-api/parsing.adoc +202 -0
data/docs/interfaces/ruby-api/xinclude.adoc +162 -0
data/docs/interfaces/ruby-api/xref-resolution.adoc +156 -0
data/docs/lychee.toml +42 -0
data/docs/reference/cli-options.adoc +155 -0
data/docs/reference/content-block-types.adoc +243 -0
data/docs/reference/glossary.adoc +119 -0
data/docs/reference/index.adoc +12 -0
data/docs/reference/supported-elements.adoc +749 -0
data/docs/understanding/architecture.adoc +145 -0
data/docs/understanding/content-pipeline.adoc +102 -0
data/docs/understanding/data-models.adoc +156 -0
data/docs/understanding/index.adoc +34 -0
data/exe/docbook +7 -0
data/frontend/dist/app.css +1 -0
data/frontend/dist/app.iife.js +24 -0
data/frontend/package-lock.json +1445 -0
data/frontend/package.json +22 -0
data/frontend/src/App.vue +230 -0
data/frontend/src/app.ts +8 -0
data/frontend/src/components/AppSidebar.vue +116 -0
data/frontend/src/components/AppendixSection.vue +39 -0
data/frontend/src/components/BlockRenderer.vue +358 -0
data/frontend/src/components/ChapterSection.vue +32 -0
data/frontend/src/components/ContentRenderer.vue +13 -0
data/frontend/src/components/EbookContainer.vue +147 -0
data/frontend/src/components/EbookTopBar.vue +116 -0
data/frontend/src/components/PartSection.vue +44 -0
data/frontend/src/components/ReferenceEntry.vue +80 -0
data/frontend/src/components/SearchModal.vue +286 -0
data/frontend/src/components/SectionContent.vue +31 -0
data/frontend/src/components/SettingsPanel.vue +236 -0
data/frontend/src/components/TocTreeItem.vue +135 -0
data/frontend/src/composables/useEbookStore.ts +191 -0
data/frontend/src/composables/useSearch.ts +249 -0
data/frontend/src/env.d.ts +7 -0
data/frontend/src/stores/documentStore.ts +221 -0
data/frontend/src/stores/uiStore.ts +98 -0
data/frontend/src/styles.css +253 -0
data/frontend/tsconfig.json +24 -0
data/frontend/tsconfig.node.json +11 -0
data/frontend/vite.config.ts +30 -0
data/lib/docbook/cli.rb +123 -0
data/lib/docbook/document.rb +67 -0
data/lib/docbook/elements/abbrev.rb +16 -0
data/lib/docbook/elements/acknowledgements.rb +22 -0
data/lib/docbook/elements/address.rb +18 -0
data/lib/docbook/elements/alt.rb +16 -0
data/lib/docbook/elements/annotation.rb +18 -0
data/lib/docbook/elements/appendix.rb +34 -0
data/lib/docbook/elements/article.rb +31 -0
data/lib/docbook/elements/att.rb +15 -0
data/lib/docbook/elements/attribution.rb +20 -0
data/lib/docbook/elements/audioobject.rb +18 -0
data/lib/docbook/elements/author.rb +18 -0
data/lib/docbook/elements/bibliography.rb +24 -0
data/lib/docbook/elements/bibliomixed.rb +40 -0
data/lib/docbook/elements/biblioref.rb +20 -0
data/lib/docbook/elements/blockquote.rb +26 -0
data/lib/docbook/elements/book.rb +36 -0
data/lib/docbook/elements/buildtarget.rb +16 -0
data/lib/docbook/elements/callout.rb +22 -0
data/lib/docbook/elements/calloutlist.rb +22 -0
data/lib/docbook/elements/caution.rb +30 -0
data/lib/docbook/elements/chapter.rb +62 -0
data/lib/docbook/elements/citation.rb +16 -0
data/lib/docbook/elements/citerefentry.rb +26 -0
data/lib/docbook/elements/citetitle.rb +20 -0
data/lib/docbook/elements/classname.rb +16 -0
data/lib/docbook/elements/code.rb +16 -0
data/lib/docbook/elements/colophon.rb +22 -0
data/lib/docbook/elements/computeroutput.rb +18 -0
data/lib/docbook/elements/copyright.rb +17 -0
data/lib/docbook/elements/danger.rb +28 -0
data/lib/docbook/elements/date.rb +16 -0
data/lib/docbook/elements/dedication.rb +22 -0
data/lib/docbook/elements/dir.rb +16 -0
data/lib/docbook/elements/emphasis.rb +18 -0
data/lib/docbook/elements/entry.rb +30 -0
data/lib/docbook/elements/entrytbl.rb +22 -0
data/lib/docbook/elements/equation.rb +26 -0
data/lib/docbook/elements/example.rb +30 -0
data/lib/docbook/elements/fieldsynopsis.rb +21 -0
data/lib/docbook/elements/figure.rb +28 -0
data/lib/docbook/elements/filename.rb +16 -0
data/lib/docbook/elements/firstname.rb +16 -0
data/lib/docbook/elements/firstterm.rb +18 -0
data/lib/docbook/elements/footnote.rb +22 -0
data/lib/docbook/elements/footnoteref.rb +21 -0
data/lib/docbook/elements/foreignphrase.rb +18 -0
data/lib/docbook/elements/formalpara.rb +20 -0
data/lib/docbook/elements/function.rb +16 -0
data/lib/docbook/elements/glossary.rb +24 -0
data/lib/docbook/elements/glossdef.rb +18 -0
data/lib/docbook/elements/glossentry.rb +26 -0
data/lib/docbook/elements/glosssee.rb +18 -0
data/lib/docbook/elements/glossseealso.rb +18 -0
data/lib/docbook/elements/glossterm.rb +18 -0
data/lib/docbook/elements/holder.rb +16 -0
data/lib/docbook/elements/honorific.rb +16 -0
data/lib/docbook/elements/imagedata.rb +29 -0
data/lib/docbook/elements/imageobject.rb +22 -0
data/lib/docbook/elements/important.rb +30 -0
data/lib/docbook/elements/index.rb +26 -0
data/lib/docbook/elements/indexdiv.rb +22 -0
data/lib/docbook/elements/indexentry.rb +22 -0
data/lib/docbook/elements/indexterm.rb +34 -0
data/lib/docbook/elements/info.rb +25 -0
data/lib/docbook/elements/informalexample.rb +24 -0
data/lib/docbook/elements/informalfigure.rb +20 -0
data/lib/docbook/elements/inlinemediaobject.rb +22 -0
data/lib/docbook/elements/itemizedlist.rb +21 -0
data/lib/docbook/elements/legalnotice.rb +22 -0
data/lib/docbook/elements/link.rb +26 -0
data/lib/docbook/elements/listitem.rb +32 -0
data/lib/docbook/elements/literal.rb +16 -0
data/lib/docbook/elements/literallayout.rb +22 -0
data/lib/docbook/elements/mediaobject.rb +26 -0
data/lib/docbook/elements/msg.rb +20 -0
data/lib/docbook/elements/msgexplan.rb +22 -0
data/lib/docbook/elements/msgset.rb +22 -0
data/lib/docbook/elements/note.rb +30 -0
data/lib/docbook/elements/orderedlist.rb +23 -0
data/lib/docbook/elements/orgname.rb +16 -0
data/lib/docbook/elements/para.rb +61 -0
data/lib/docbook/elements/paragraph_like.rb +18 -0
data/lib/docbook/elements/parameter.rb +16 -0
data/lib/docbook/elements/part.rb +38 -0
data/lib/docbook/elements/personname.rb +22 -0
data/lib/docbook/elements/phrase.rb +20 -0
data/lib/docbook/elements/preface.rb +58 -0
data/lib/docbook/elements/primary.rb +16 -0
data/lib/docbook/elements/procedure.rb +24 -0
data/lib/docbook/elements/productname.rb +18 -0
data/lib/docbook/elements/productnumber.rb +16 -0
data/lib/docbook/elements/programlisting.rb +28 -0
data/lib/docbook/elements/property.rb +16 -0
data/lib/docbook/elements/pubdate.rb +16 -0
data/lib/docbook/elements/publishername.rb +16 -0
data/lib/docbook/elements/quotation.rb +24 -0
data/lib/docbook/elements/quote.rb +18 -0
data/lib/docbook/elements/refentry.rb +32 -0
data/lib/docbook/elements/refentrytitle.rb +16 -0
data/lib/docbook/elements/reference.rb +26 -0
data/lib/docbook/elements/refmeta.rb +29 -0
data/lib/docbook/elements/refmiscinfo.rb +16 -0
data/lib/docbook/elements/refname.rb +16 -0
data/lib/docbook/elements/refnamediv.rb +22 -0
data/lib/docbook/elements/refpurpose.rb +16 -0
data/lib/docbook/elements/refsect1.rb +22 -0
data/lib/docbook/elements/refsect2.rb +22 -0
data/lib/docbook/elements/refsect3.rb +22 -0
data/lib/docbook/elements/refsection.rb +32 -0
data/lib/docbook/elements/releaseinfo.rb +16 -0
data/lib/docbook/elements/remark.rb +20 -0
data/lib/docbook/elements/replaceable.rb +16 -0
data/lib/docbook/elements/row.rb +15 -0
data/lib/docbook/elements/screen.rb +28 -0
data/lib/docbook/elements/secondary.rb +16 -0
data/lib/docbook/elements/sect1.rb +26 -0
data/lib/docbook/elements/sect2.rb +24 -0
data/lib/docbook/elements/sect3.rb +24 -0
data/lib/docbook/elements/sect4.rb +24 -0
data/lib/docbook/elements/sect5.rb +22 -0
data/lib/docbook/elements/section.rb +66 -0
data/lib/docbook/elements/see.rb +16 -0
data/lib/docbook/elements/seealso.rb +18 -0
data/lib/docbook/elements/set.rb +26 -0
data/lib/docbook/elements/setindex.rb +24 -0
data/lib/docbook/elements/sidebar.rb +22 -0
data/lib/docbook/elements/simplesect.rb +32 -0
data/lib/docbook/elements/step.rb +26 -0
data/lib/docbook/elements/substeps.rb +18 -0
data/lib/docbook/elements/subtitle.rb +16 -0
data/lib/docbook/elements/surname.rb +16 -0
data/lib/docbook/elements/table.rb +24 -0
data/lib/docbook/elements/tag.rb +20 -0
data/lib/docbook/elements/tbody.rb +15 -0
data/lib/docbook/elements/term.rb +37 -0
data/lib/docbook/elements/tertiary.rb +16 -0
data/lib/docbook/elements/textobject.rb +18 -0
data/lib/docbook/elements/tfoot.rb +15 -0
data/lib/docbook/elements/tgroup.rb +21 -0
data/lib/docbook/elements/thead.rb +15 -0
data/lib/docbook/elements/tip.rb +30 -0
data/lib/docbook/elements/title.rb +16 -0
data/lib/docbook/elements/toc.rb +24 -0
data/lib/docbook/elements/tocdiv.rb +22 -0
data/lib/docbook/elements/tocentry.rb +20 -0
data/lib/docbook/elements/topic.rb +26 -0
data/lib/docbook/elements/type.rb +16 -0
data/lib/docbook/elements/uri.rb +16 -0
data/lib/docbook/elements/userinput.rb +18 -0
data/lib/docbook/elements/variable.rb +16 -0
data/lib/docbook/elements/variablelist.rb +19 -0
data/lib/docbook/elements/varlistentry.rb +17 -0
data/lib/docbook/elements/version.rb +16 -0
data/lib/docbook/elements/videoobject.rb +18 -0
data/lib/docbook/elements/warning.rb +30 -0
data/lib/docbook/elements/xref.rb +18 -0
data/lib/docbook/elements/year.rb +16 -0
data/lib/docbook/elements.rb +204 -0
data/lib/docbook/models/document_metadata.rb +30 -0
data/lib/docbook/models/document_root.rb +33 -0
data/lib/docbook/models/index_entry.rb +28 -0
data/lib/docbook/models/reading_position.rb +22 -0
data/lib/docbook/models/section_number.rb +18 -0
data/lib/docbook/models/section_root.rb +29 -0
data/lib/docbook/models/toc_node.rb +24 -0
data/lib/docbook/models.rb +16 -0
data/lib/docbook/output/data.rb +196 -0
data/lib/docbook/output/html.rb +1450 -0
data/lib/docbook/output/index_generator.rb +281 -0
data/lib/docbook/output.rb +8 -0
data/lib/docbook/services/document_builder.rb +258 -0
data/lib/docbook/services/element_to_hash.rb +287 -0
data/lib/docbook/services/index_generator.rb +134 -0
data/lib/docbook/services/numbering_service.rb +186 -0
data/lib/docbook/services/toc_generator.rb +138 -0
data/lib/docbook/services.rb +14 -0
data/lib/docbook/templates/document.html.liquid +20 -0
data/lib/docbook/templates/partials/_head.liquid +39 -0
data/lib/docbook/templates/partials/_scripts.liquid +10 -0
data/lib/docbook/version.rb +5 -0
data/lib/docbook/xinclude_resolver.rb +217 -0
data/lib/docbook/xref_resolver.rb +78 -0
data/lib/docbook.rb +17 -0
data/sig/docbook.rbs +4 -0
metadata +385 -0

data/docs/interfaces/ruby-api/html-output.adoc ADDED Viewed

@@ -0,0 +1,186 @@
+---
+layout: default
+title: HTML Output
+parent: Ruby API
+grand_parent: Interfaces
+nav_order: 2
+---
+== HTML Output
+The `Docbook::Output::Html` class generates HTML from a parsed DocBook document.
+=== Constructor
+[source,ruby]
+----
+html_generator = Docbook::Output::Html.new(
+  document,                           # Parsed DocBook element (required)
+  xref_resolver: xref_resolver,       # XrefResolver instance (optional)
+  output_mode: :single_file,          # :single_file or :directory
+  base_path: "/path/to/xml/dir",      # Base path for image resolution
+  output_path: "/path/to/output"      # Output directory (required for directory mode)
+)
+----
+==== Parameters
+[cols="2,1,5"]
+|===
+| Parameter | Required | Description
+| `document` | Yes | A parsed DocBook element from `Document.from_xml`
+| `xref_resolver` | No | A `Docbook::XrefResolver` instance (call `resolve!` first). Used to resolve `xref` elements to target titles.
+| `output_mode` | No | `:single_file` (default) or `:directory`. Controls how images and assets are handled.
+| `base_path` | No | Directory containing the source XML file. Used to locate images referenced by relative paths.
+| `output_path` | No | Output directory for directory mode. Required when `output_mode` is `:directory`.
+|===
+=== Generating HTML
+Call `to_html` on the generator instance to produce the HTML output:
+[source,ruby]
+----
+html = html_generator.to_html
+# => "<!DOCTYPE html><html>..."  (String)
+----
+=== Output Modes
+==== Single-File Mode
+Produces a self-contained HTML string with all assets embedded:
+[source,ruby]
+----
+require "docbook"
+xml_string = File.read("article.xml")
+document = Docbook::Document.from_xml(xml_string)
+xref_resolver = Docbook::XrefResolver.new(document).resolve!
+html = Docbook::Output::Html.new(
+  document,
+  xref_resolver: xref_resolver,
+  output_mode: :single_file,
+  base_path: File.dirname(File.expand_path("article.xml"))
+).to_html
+File.write("output.html", html)
+----
+In single-file mode:
+* CSS and JavaScript are embedded inline in the HTML
+* Images are converted to Base64 data URIs (using the `Marcel` gem for MIME type detection)
+* All content data (TOC, sections, index) is embedded in `<script>` tags as JSON
+* The resulting file is completely self-contained
+==== Directory Mode
+Produces an HTML shell plus separate data and asset files:
+[source,ruby]
+----
+require "docbook"
+require "fileutils"
+xml_string = File.read("book.xml")
+resolved = Docbook::XIncludeResolver.resolve_string(xml_string, base_path: "book.xml")
+document = Docbook::Document.from_xml(resolved.to_xml)
+xref_resolver = Docbook::XrefResolver.new(document).resolve!
+output_dir = "/var/www/html/book"
+FileUtils.mkdir_p(output_dir)
+html = Docbook::Output::Html.new(
+  document,
+  xref_resolver: xref_resolver,
+  output_mode: :directory,
+  base_path: File.dirname(File.expand_path("book.xml")),
+  output_path: output_dir
+).to_html
+# The generator writes docbook.data.json to output_path automatically
+# The returned HTML string is the index.html content
+File.write(File.join(output_dir, "index.html"), html)
+----
+In directory mode, the `to_html` method also writes `docbook.data.json` to the `output_path` directory. The directory structure is:
+[source]
+----
+output_dir/
+  index.html           # HTML returned by to_html
+  docbook.data.json    # Written automatically by to_html
+----
+[NOTE]
+====
+The CLI's `write_output` method handles copying `app.css` and `app.iife.js` to the `assets/` subdirectory. When using the Ruby API directly, you are responsible for copying the frontend assets if you need them.
+====
+=== Cross-Reference Resolution
+The `xref_resolver` parameter is used to resolve `<xref>` elements in the document. When an `xref` element has a `linkend` attribute, the resolver looks up the target element by its `xml:id` and returns the title text:
+[source,ruby]
+----
+# Without xref_resolver, xref elements display the raw linkend value
+# With xref_resolver, xref elements display the target's title
+xref_resolver = Docbook::XrefResolver.new(document).resolve!
+html = Docbook::Output::Html.new(
+  document,
+  xref_resolver: xref_resolver,
+  output_mode: :single_file
+).to_html
+----
+=== Image Handling
+Images are handled differently based on the output mode:
+* *Single-file mode:* Images are read from disk, Base64-encoded, and embedded as data URIs
+* *Directory mode:* Images reference their original file paths (relative to the output directory)
+The `base_path` parameter is used to locate image files on disk. The generator searches the base path and all parent directories to find referenced images. It also checks common prefixes like `resources/` and `../resources/`.
+=== Generated Data Structure
+The `to_html` method builds a structured data model internally before rendering. This model includes:
+[cols="2,5"]
+|===
+| Component | Description
+| *Title* | The document title extracted from `<info><title>` or the root element's `<title>`
+| *TOC* | Hierarchical table of contents with section IDs, titles, and types
+| *Numbering* | Computed numbering for parts (Roman), chapters (Arabic), appendices (Alpha), and sections (hierarchical)
+| *Content* | Section content organized by section ID, with blocks for paragraphs, code, images, lists, etc.
+| *Index* | Collected `indexterm` elements grouped alphabetically with see/see-also support
+|===
+=== Supported Content Types
+The HTML generator processes the following block-level content types from each section:
+* Paragraphs (`para`, `formalpara`)
+* Code listings (`programlisting`, `screen`, `literallayout`)
+* Images and figures (`mediaobject`, `figure`, `informalfigure`, `inlinemediaobject`)
+* Lists (`orderedlist`, `itemizedlist`, `variablelist`)
+* Admonitions (`note`, `warning`, `caution`, `important`, `tip`, `danger`)
+* Examples (`example`, `informalexample`)
+* Block quotes (`blockquote`)
+* Glossary entries (`glossentry`)
+* Bibliography entries (`bibliomixed`)
+* Reference entries (`refentry`)
+* Index sections (`index`, `setindex`)
+* Nested sections (`section`, `simplesect`)
+=== See Also
+* *<<parsing,Parsing Documents>>* -- Parse XML before generating HTML
+* *<<xref-resolution,XRef Resolution>>* -- Resolve cross-references for the HTML generator
+* *<<xinclude,XInclude Resolution>>* -- Resolve XIncludes before parsing

data/docs/interfaces/ruby-api/index.adoc ADDED Viewed

@@ -0,0 +1,111 @@
+---
+layout: default
+title: Ruby API
+parent: Interfaces
+nav_order: 2
+has_children: true
+---
+== Ruby API
+The `docbook` gem provides a programmatic Ruby API for parsing, processing, and converting DocBook XML documents. This is the same API that powers the CLI, exposed for direct use in Ruby applications.
+=== Getting Started
+Add the gem to your project and require it:
+[source,ruby]
+----
+require "docbook"
+----
+All public classes are under the `Docbook` module namespace.
+=== Core Classes
+The Ruby API revolves around four core classes:
+[cols="3,5"]
+|===
+| Class | Purpose
+| `Docbook::Document` | Entry point for parsing XML strings into typed Ruby element models. Supports 39 root element types.
+| `Docbook::XIncludeResolver` | Resolves `xi:include` elements in XML documents. Must be called *before* parsing with `Document.from_xml`.
+| `Docbook::XrefResolver` | Builds an `xml:id` lookup map from a parsed document and resolves `xref`/`linkend` references to titles.
+| `Docbook::Output::Html` | Generates HTML from a parsed document in single-file or directory mode.
+|===
+=== Processing Pipeline
+A typical processing pipeline has four stages:
+[source,ruby]
+----
+require "docbook"
+# Stage 1: Read the XML file
+xml_string = File.read("book.xml")
+# Stage 2: Resolve XIncludes (optional, but usually needed)
+resolved = Docbook::XIncludeResolver.resolve_string(xml_string, base_path: "book.xml")
+# Stage 3: Parse into Ruby element models
+document = Docbook::Document.from_xml(resolved.to_xml)
+# Stage 4: Resolve cross-references
+xref_resolver = Docbook::XrefResolver.new(document).resolve!
+# Stage 5: Generate HTML
+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)
+----
+[TIP]
+====
+Stages 2 and 4 are optional but recommended. XInclude resolution should happen *before* parsing because the parser needs a single, complete XML document. Cross-reference resolution should happen *after* parsing so the resolver can traverse the element tree.
+====
+=== Error Handling
+The gem defines a base error class `Docbook::Error` that is raised for invalid input:
+[source,ruby]
+----
+begin
+  Docbook::Document.from_xml("<invalid>not docbook</invalid>")
+rescue Docbook::Error => e
+  puts "Parse error: #{e.message}"
+  # => "Unsupported DocBook root element: invalid"
+end
+----
+Common error scenarios:
+* Empty or invalid XML -- raises `Docbook::Error, "Empty or invalid XML document"`
+* Unsupported root element -- raises `Docbook::Error, "Unsupported DocBook root element: <name>"`
+* Missing file -- raises `Errno::ENOENT` from `File.read`
+=== Element Models
+All DocBook elements are modeled as `Lutaml::Model::Serializable` subclasses under the `Docbook::Elements` namespace. These models provide:
+* *Typed attributes* -- Every XML element maps to a Ruby class with typed attributes (strings, collections, nested models)
+* *Mixed content* -- Elements that support mixed content (text interspersed with child elements) provide an `each_mixed_content` method for traversal
+* *XML round-tripping* -- Models can be serialized back to XML via `to_xml`
+For example, a `<book>` element is represented as `Docbook::Elements::Book` with attributes for `info`, `part`, `chapter`, `appendix`, `preface`, `bibliography`, `glossary`, and `index`.
+=== Detailed Documentation
+Explore each component in detail:
+* *<<parsing,Parsing Documents>>* -- How to parse XML and access element models
+* *<<html-output,HTML Output>>* -- Generating HTML in single-file and directory modes
+* *<<xinclude,XInclude Resolution>>* -- Resolving `xi:include` elements
+* *<<xref-resolution,XRef Resolution>>* -- Building ID maps and resolving cross-references

data/docs/interfaces/ruby-api/parsing.adoc ADDED Viewed

@@ -0,0 +1,202 @@
+---
+layout: default
+title: Parsing Documents
+parent: Ruby API
+grand_parent: Interfaces
+nav_order: 1
+---
+== Parsing Documents
+The `Docbook::Document` class is the primary entry point for parsing DocBook XML into typed Ruby objects.
+=== Basic Parsing
+Use `Document.from_xml` to parse an XML string:
+[source,ruby]
+----
+require "docbook"
+xml = <<~XML
+  <article xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="sample">
+    <info>
+      <title>Sample Article</title>
+    </info>
+    <section xml:id="intro">
+      <title>Introduction</title>
+      <para>Hello, DocBook world.</para>
+    </section>
+  </article>
+XML
+document = Docbook::Document.from_xml(xml)
+# => #<Docbook::Elements::Article:0x0000...>
+----
+The method returns an instance of the appropriate element class based on the root element name. In this case, it returns a `Docbook::Elements::Article` because the root element is `<article>`.
+=== Supported Root Elements
+`Document.from_xml` automatically detects the root element and selects the correct parser. The gem supports 39 root element types:
+[cols="3,3,3"]
+|===
+| Structural | Sectioning | Reference
+| `article` | `section` | `refentry`
+| `book` | `sect1` | `reference`
+| `chapter` | `sect2` | `refsection`
+| `appendix` | `sect3` | `refsect1`
+| `preface` | `sect4` | `refsect2`
+| `part` | `sect5` | `refsect3`
+| `set` | `simplesect` |
+| `topic` | `para` |
+|===
+[cols="3,3,3"]
+|===
+| Front Matter | Back Matter | Other
+| `dedication` | `bibliography` | `index`
+| `acknowledgements` | `glossary` | `setindex`
+| `colophon` | | `toc`
+|===
+=== Checking Root Element Support
+Before parsing, you can check whether a specific root element is supported:
+[source,ruby]
+----
+# Check if a root element name is supported
+Docbook::Document.supports?("article")   # => true
+Docbook::Document.supports?("html")      # => false
+# List all supported root element names
+Docbook::Document.supported_root_elements
+# => ["article", "book", "chapter", "appendix", "preface", "part",
+#     "section", "refentry", "bibliography", "glossary", "set",
+#     "reference", "topic", "dedication", "acknowledgements",
+#     "colophon", "index", "toc", "sect1", "sect2", "sect3",
+#     "sect4", "sect5", "refsection", "refsect1", "refsect2",
+#     "refsect3", "setindex", "para", "simplesect"]
+----
+=== Error Handling
+Parsing errors raise `Docbook::Error`:
+[source,ruby]
+----
+# Empty XML
+Docbook::Document.from_xml("")
+# => raises Docbook::Error: "Empty or invalid XML document"
+# Unsupported root element
+Docbook::Document.from_xml("<html><body>Not DocBook</body></html>")
+# => raises Docbook::Error: "Unsupported DocBook root element: html"
+----
+Always wrap parsing in a rescue block for robust applications:
+[source,ruby]
+----
+begin
+  document = Docbook::Document.from_xml(xml_string)
+rescue Docbook::Error => e
+  warn "Failed to parse document: #{e.message}"
+  exit 1
+end
+----
+=== Accessing Parsed Elements
+Once parsed, the returned object is a fully populated element model. The available attributes depend on the element type:
+[source,ruby]
+----
+# Parse a book
+document = Docbook::Document.from_xml(book_xml)
+# document is a Docbook::Elements::Book
+document.xml_id           # => "my-book" (the xml:id attribute)
+document.version          # => "5.0"
+document.info             # => #<Docbook::Elements::Info:...>
+document.info.title       # => #<Docbook::Elements::Title:...>
+document.info.title.content  # => "My Book Title"
+document.chapter          # => [#<Docbook::Elements::Chapter:...>, ...]
+document.appendix         # => [#<Docbook::Elements::Appendix:...>, ...]
+document.part             # => [#<Docbook::Elements::Part:...>, ...]
+document.preface          # => [#<Docbook::Elements::Preface:...>, ...]
+----
+[source,ruby]
+----
+# Parse an article
+document = Docbook::Document.from_xml(article_xml)
+# document is a Docbook::Elements::Article
+document.info.title.content  # => "Article Title"
+document.section             # => [#<Docbook::Elements::Section:...>, ...]
+document.section.first.title # => #<Docbook::Elements::Title:...>
+document.section.first.title.content  # => "Introduction"
+----
+=== Mixed Content Traversal
+Many DocBook elements support *mixed content* -- a mixture of text strings and child elements. The `each_mixed_content` method yields each child node in document order:
+[source,ruby]
+----
+section = document.section.first
+section.each_mixed_content do |node|
+  case node
+  when String
+    # Raw text content between elements
+    puts "Text: #{node}"
+  when Docbook::Elements::Para
+    puts "Paragraph: #{node.content}"
+  when Docbook::Elements::MediaObject
+    puts "Media object"
+  when Docbook::Elements::ProgramListing
+    puts "Code listing: #{node.content}"
+  when Docbook::Elements::OrderedList
+    puts "Ordered list"
+  # ... many more element types
+  end
+end
+----
+This is the primary mechanism for traversing element content in the HTML generation pipeline. The `each_mixed_content` method yields both `String` instances (for text nodes) and typed element objects (for child elements).
+=== File-Based Parsing
+A complete file-based parsing workflow:
+[source,ruby]
+----
+require "docbook"
+# Read the file
+xml_string = File.read("book.xml")
+# Optionally resolve XIncludes first
+resolved_xml = Docbook::XIncludeResolver.resolve_string(xml_string, base_path: "book.xml")
+# Parse
+document = Docbook::Document.from_xml(resolved_xml.to_xml)
+# Work with the parsed document
+puts "Title: #{document.info&.title&.content}"
+puts "Chapters: #{document.chapter&.size || 0}"
+document.chapter&.each do |chapter|
+  puts "  - #{chapter.title&.content}"
+end
+----
+=== See Also
+* *<<html-output,HTML Output>>* -- Convert parsed documents to HTML
+* *<<xinclude,XInclude Resolution>>* -- Resolve XIncludes before parsing
+* *<<xref-resolution,XRef Resolution>>* -- Build cross-reference maps from parsed documents

data/docs/interfaces/ruby-api/xinclude.adoc ADDED Viewed

@@ -0,0 +1,162 @@
+---
+layout: default
+title: XInclude Resolution
+parent: Ruby API
+grand_parent: Interfaces
+nav_order: 3
+---
+== XInclude Resolution
+The `Docbook::XIncludeResolver` class resolves http://www.w3.org/2001/XInclude/[XInclude] elements in DocBook XML documents. XInclude resolution must happen *before* parsing with `Document.from_xml`, because the parser needs a single, complete XML document.
+=== Why Resolve XIncludes First
+DocBook documents are often modular: a book may include chapters from separate files using `<xi:include>` elements. The `Document.from_xml` parser expects a single XML document with no unresolved XIncludes. The `XIncludeResolver` expands these references to produce a merged document.
+=== Class Methods
+The resolver provides two class-level entry points:
+==== `resolve(doc)`
+Resolves XIncludes in a Nokogiri document object. Processes `xi:include` elements iteratively to handle nested includes.
+[source,ruby]
+----
+require "nokogiri"
+require "docbook"
+doc = Nokogiri::XML(File.read("book.xml"))
+Docbook::XIncludeResolver.resolve(doc)
+# => returns the same Nokogiri document with xi:include elements replaced
+----
+==== `resolve_string(xml_string, base_path:)`
+Resolves XIncludes in a raw XML string. This is the most convenient method for most use cases. The `base_path` parameter tells the resolver where to look for included files.
+[source,ruby]
+----
+require "docbook"
+xml_string = File.read("book.xml")
+resolved = Docbook::XIncludeResolver.resolve_string(xml_string, base_path: "book.xml")
+resolved.to_xml  # => merged XML string with all xi:include expanded
+----
+[IMPORTANT]
+====
+The `base_path` parameter should be the path to the XML file itself (not just the directory). The resolver extracts the directory from this path to resolve relative `href` attributes in `xi:include` elements.
+====
+=== Resolution Process
+The resolver processes XIncludes iteratively:
+1. Find all `xi:include` elements in the document
+2. For each include, resolve the `href` to a file path relative to the base directory
+3. Replace the `xi:include` element with the included content
+4. Re-scan for any new `xi:include` elements (handles nested includes)
+5. Repeat until no more `xi:include` elements remain
+This iterative approach ensures that deeply nested includes (file A includes file B, which includes file C) are fully resolved.
+=== Include Types
+The resolver handles two types of XIncludes:
+==== XML Includes (default)
+Standard XML includes where the `parse` attribute is omitted or set to `"xml"`. The root element of the included file replaces the `xi:include` element:
+[source,ruby]
+----
+# book.xml contains:
+#   <xi:include href="chapters/chapter1.xml"/>
+#
+# After resolution, the <chapter> element from chapter1.xml
+# replaces the xi:include element
+----
+==== Text Includes
+Text includes where `parse="text"`. The file contents are included as plain text:
+[source,ruby]
+----
+# Includes a code snippet as literal text
+# <xi:include href="code/example.rb" parse="text"/>
+----
+==== Text Includes with Fragid
+Text includes also support the `fragid` attribute for selecting a subset of the file content. This is an extension based on the DocBook xslTNG specification:
+* `fragid="line=START,END"` -- Select lines from START to END (RFC 5147 line scheme)
+* `fragid="char=START,END"` -- Select characters from START to END (RFC 5147 char scheme)
+* `fragid="search=#PATTERN#[;after|;before],#STOP#"` -- Select lines matching a literal pattern
+* `fragid="search=/REGEX/,/STOP/"` -- Select lines matching a regex pattern
+=== Complete Example
+A full workflow for resolving XIncludes before parsing:
+[source,ruby]
+----
+require "docbook"
+# Read the main document
+xml_string = File.read("book.xml")
+# Resolve all XIncludes
+resolved = Docbook::XIncludeResolver.resolve_string(
+  xml_string,
+  base_path: "book.xml"
+)
+# Now parse the merged document
+document = Docbook::Document.from_xml(resolved.to_xml)
+puts "Chapters: #{document.chapter&.size || 0}"
+document.chapter&.each do |chapter|
+  puts "  - #{chapter.title&.content}"
+end
+----
+=== Handling Nested Includes
+The resolver handles nested includes automatically. Consider this scenario:
+* `book.xml` includes `part1.xml`
+* `part1.xml` includes `chapter1.xml` and `chapter2.xml`
+After resolution, all content is merged into a single document:
+[source,ruby]
+----
+resolved = Docbook::XIncludeResolver.resolve_string(
+  File.read("book.xml"),
+  base_path: "book.xml"
+)
+# The resolved document contains content from book.xml,
+# part1.xml, chapter1.xml, and chapter2.xml
+----
+=== Error Handling
+The resolver is designed to be tolerant of errors:
+* If a referenced file does not exist, the `xi:include` element is left in place (no error raised)
+* If the resolver encounters an unexpected error during processing, it returns the original document unchanged
+* The resolver uses Nokogiri's `url` attribute to determine the base directory for relative path resolution
+=== Namespace Handling
+The resolver ensures that namespace declarations are properly preserved when merging documents. If an included file declares namespaces that are not present in the main document, the resolver adds the namespace declarations to the root element.
+=== See Also
+* *<<parsing,Parsing Documents>>* -- Parse resolved XML into element models
+* *<<xref-resolution,XRef Resolution>>* -- Resolve cross-references after parsing
+* *<<html-output,HTML Output>>* -- Generate HTML from parsed documents