docbook 0.1.0

data/docs/interfaces/cli/format-command.adoc

@@ -0,0 +1,109 @@
+---
+layout: default
+title: format
+parent: CLI Reference
+grand_parent: Interfaces
+nav_order: 1
+---
+
+== format
+
+Format and prettify a DocBook XML file with consistent indentation and a clean structure.
+
+=== Usage
+
+[source,bash]
+----
+$ docbook format INPUT [options]
+----
+
+=== Arguments
+
+[cols="2,4"]
+|===
+| Argument | Description
+
+| `INPUT` | Path to the DocBook XML file to format (required)
+|===
+
+=== Options
+
+[cols="3,1,4"]
+|===
+| Option | Default | Description
+
+| `--output`, `-o` FILE | stdout | Write formatted output to a file instead of stdout
+| `--xinclude` | `false` | Resolve XInclude elements before formatting
+|===
+
+=== Behavior
+
+The `format` command parses the input XML file and re-serializes it with:
+
+* Pretty-printed indentation
+* An XML declaration (`<?xml version="1.0" encoding="utf-8"?>`)
+* UTF-8 encoding
+
+When the `--xinclude` option is enabled, all `xi:include` elements are resolved *before* formatting. This produces a single, self-contained XML file with all included content inlined.
+
+=== Examples
+
+==== Format to a file
+
+[source,bash]
+----
+$ docbook format article.xml -o formatted.xml
+Written to formatted.xml
+----
+
+The output is a cleanly indented XML document:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="utf-8"?>
+<article xmlns="http://docbook.org/ns/docbook" version="5.0">
+  <info>
+    <title>My Article</title>
+  </info>
+  <section xml:id="intro">
+    <title>Introduction</title>
+    <para>Some content here.</para>
+  </section>
+</article>
+----
+
+==== Format to stdout
+
+Omit the `--output` option to print to standard output:
+
+[source,bash]
+----
+$ docbook format article.xml
+<?xml version="1.0" encoding="utf-8"?>
+<article xmlns="http://docbook.org/ns/docbook" version="5.0">
+  ...
+</article>
+----
+
+==== Resolve XIncludes, then format
+
+Use `--xinclude` to inline all XInclude references before formatting:
+
+[source,bash]
+----
+$ docbook format book.xml --xinclude -o book-complete.xml
+Written to book-complete.xml
+----
+
+This is useful for producing a single merged file from a modular DocBook project where chapters are split across multiple files using XIncludes.
+
+=== Use Cases
+
+* *Normalize XML formatting* before committing changes to version control
+* *Resolve XIncludes* to produce a single self-contained document from a modular project
+* *Debug XML structure* by pretty-printing a compact or minified file
+
+=== See Also
+
+* <<to-html-command,to-html>> -- Convert DocBook XML to HTML (also supports `--xinclude`)
+* <<roundtrip-command,roundtrip>> -- Round-trip test to verify parse/serialize fidelity

data/docs/interfaces/cli/index.adoc

@@ -0,0 +1,73 @@
+---
+layout: default
+title: CLI Reference
+parent: Interfaces
+nav_order: 1
+has_children: true
+---
+
+== CLI Reference
+
+The `docbook` command-line interface is built on http://whatisthor.com/[Thor] and provides four commands for working with DocBook XML files.
+
+=== Global Behavior
+
+The CLI executable is installed as `docbook` (via the gem's `exe/docbook` entry point). All commands follow a consistent pattern:
+
+* Accept an `INPUT` file path as the primary argument
+* Support common options like `--output` / `-o` for specifying output destinations
+* Exit with code 0 on success and code 1 on failure
+* Print error messages to stderr and informational messages to stdout
+
+=== Command Summary
+
+[cols="2,1,5",options="header"]
+|===
+| Command | Since | Description
+
+| `format` | 0.1.0 | Reformat and prettify DocBook XML with consistent indentation
+| `validate` | 0.1.0 | Check XML well-formedness of a DocBook file
+| `to-html` | 0.1.0 | Convert DocBook XML to a self-contained HTML document or a directory with assets
+| `roundtrip` | 0.1.0 | Round-trip test one or more XML files (parse, serialize, re-parse) for regression testing
+|===
+
+=== Getting Help
+
+Each command has built-in help accessible via `docbook help COMMAND`:
+
+[source,bash]
+----
+$ docbook help to-html
+Commands:
+  docbook to-html INPUT  # Convert DocBook XML to HTML
+
+Options:
+  -o, --output=OUTPUT          # Output file or directory
+      --xinclude=XINCLUDE      # Resolve XIncludes before processing
+                               # Default: true
+      --output_type=OUTPUT_TYPE  # Output type: single_file or directory
+                               # Default: single_file
+----
+
+=== Detailed Command Documentation
+
+Select a command below for detailed usage instructions, options, and examples:
+
+* <<format-command,format>> -- Reformat DocBook XML
+* <<validate-command,validate>> -- Validate XML well-formedness
+* <<to-html-command,to-html>> -- Convert to HTML
+* <<roundtrip-command,roundtrip>> -- Round-trip test
+
+=== Exit Codes
+
+All commands follow standard Unix conventions:
+
+[cols="1,4"]
+|===
+| Code | Meaning
+
+| `0` | Success
+| `1` | Failure (validation errors, parse errors, file not found, etc.)
+|===
+
+The CLI sets `exit_on_failure?` to `true`, so any unhandled exception will cause a non-zero exit.

data/docs/interfaces/cli/roundtrip-command.adoc

@@ -0,0 +1,125 @@
+---
+layout: default
+title: roundtrip
+parent: CLI Reference
+grand_parent: Interfaces
+nav_order: 4
+---
+
+== roundtrip
+
+Round-trip test one or more DocBook XML files by parsing them, serializing back to XML, and re-parsing the result.
+
+=== Usage
+
+[source,bash]
+----
+$ docbook roundtrip INPUT...
+----
+
+=== Arguments
+
+[cols="2,4"]
+|===
+| Argument | Description
+
+| `INPUT...` | One or more paths to DocBook XML files (required, at least one)
+|===
+
+=== Behavior
+
+The `roundtrip` command performs the following steps for each input file:
+
+1. Read the file as a string
+2. Parse it into a DocBook element model using `Docbook::Document.from_xml`
+3. Serialize the model back to XML with an XML declaration
+4. Re-parse the serialized output
+
+If both parse operations succeed, the file passes. If any step raises an exception, the file fails.
+
+The command processes all input files and reports the total number of failures. It exits with code 1 if any file fails.
+
+=== Exit Codes
+
+[cols="1,4"]
+|===
+| Code | Condition
+
+| `0` | All files round-tripped successfully
+| `1` | One or more files failed the round-trip test
+|===
+
+=== Examples
+
+==== Test a single file
+
+[source,bash]
+----
+$ docbook roundtrip article.xml
+article.xml: OK
+----
+
+==== Test multiple files
+
+[source,bash]
+----
+$ docbook roundtrip article.xml book.xml chapter.xml
+article.xml: OK
+book.xml: OK
+chapter.xml: OK
+----
+
+==== Failure case
+
+When a file cannot survive the round trip, the error message is shown:
+
+[source,bash]
+----
+$ docbook roundtrip good.xml bad.xml
+good.xml: OK
+bad.xml: FAIL - Unsupported DocBook root element: html
+2 files, 1 failures
+$ echo $?
+1
+----
+
+==== Test all XML files in a project
+
+[source,bash]
+----
+$ docbook roundtrip spec/fixtures/*.xml
+----
+
+=== Use Cases
+
+* *Regression testing* -- Verify that changes to the gem's parsing or serialization code do not break existing documents
+* *CI integration* -- Run round-trip tests on a corpus of DocBook files as part of your test suite
+* *Debugging* -- Identify documents that the gem cannot parse or serialize correctly
+* *Quality assurance* -- Ensure that the parse/serialize cycle is lossless for your document set
+
+=== How It Works
+
+The round-trip test exercises the full parse-serialize pipeline:
+
+[source,ruby]
+----
+# Simplified logic of the roundtrip command
+xml_string = File.read(input)
+parsed = Docbook::Document.from_xml(xml_string)
+output = parsed.to_xml(declaration: true, encoding: "utf-8")
+reparsed = Docbook::Document.from_xml(output)
+# If both parses succeed, the file passes
+----
+
+Note that the round-trip test does *not* compare the original and serialized XML strings character by character. It only verifies that both the original and the serialized output can be successfully parsed. Whitespace, attribute ordering, and namespace declarations may differ between the original and serialized forms.
+
+=== Limitations
+
+* Does not check for semantic equivalence between original and round-tripped content
+* Does not resolve XIncludes before testing
+* Does not validate against the DocBook schema
+
+=== See Also
+
+* <<validate-command,validate>> -- Check XML well-formedness
+* <<format-command,format>> -- Reformat DocBook XML

data/docs/interfaces/cli/to-html-command.adoc

@@ -0,0 +1,178 @@
+---
+layout: default
+title: to-html
+parent: CLI Reference
+grand_parent: Interfaces
+nav_order: 3
+---
+
+== to-html
+
+Convert a DocBook XML file to an HTML document.
+
+=== Usage
+
+[source,bash]
+----
+$ docbook to-html INPUT [options]
+----
+
+=== Arguments
+
+[cols="2,4"]
+|===
+| Argument | Description
+
+| `INPUT` | Path to the DocBook XML file to convert (required)
+|===
+
+=== Options
+
+[cols="3,1,4"]
+|===
+| Option | Default | Description
+
+| `--output`, `-o` PATH | stdout | Output file path (single-file mode) or directory path (directory mode)
+| `--xinclude` | `true` | Resolve XInclude elements before processing
+| `--output-type` MODE | `single_file` | Output mode: `single_file` or `directory`
+|===
+
+=== Output Modes
+
+The `to-html` command supports two output modes, controlled by the `--output-type` option.
+
+==== Single-File Mode (`single_file`)
+
+Produces a single, self-contained HTML file with everything embedded inline:
+
+* CSS and JavaScript are embedded directly in the HTML
+* Images are converted to Base64 data URIs
+* All content data (TOC, sections, index) is embedded in `<script>` tags as JSON
+
+This mode is ideal for:
+
+* Distributing a single file (e.g., email attachments, downloads)
+* Offline reading with no external dependencies
+* Embedding in other HTML pages
+
+[source,bash]
+----
+$ docbook to-html book.xml -o output.html
+Written to output.html
+----
+
+==== Directory Mode (`directory`)
+
+Produces a directory with separate files:
+
+[source]
+----
+output-dir/
+  index.html           # HTML shell that loads the Vue.js reader
+  docbook.data.json    # Structured content (TOC, sections, index, numbering)
+  assets/
+    app.css            # Compiled stylesheet
+    app.iife.js        # Vue.js application bundle
+----
+
+In directory mode:
+
+* The `index.html` file contains the HTML structure and embedded CSS/JS
+* Content data is loaded from `docbook.data.json` at runtime
+* Images reference their original file paths (no Base64 embedding)
+
+This mode is ideal for:
+
+* Web serving (the directory can be deployed to any static host)
+* Large documents (JSON is loaded on demand by the Vue.js reader)
+* Interactive reading experience with table of contents navigation
+
+[source,bash]
+----
+$ docbook to-html book.xml -o my-book --output-type directory
+Written to my-book/index.html and assets/
+----
+
+[IMPORTANT]
+====
+When using `--output-type directory`, the `--output` option is *required*. The CLI will raise an error if no output path is provided.
+====
+
+=== XInclude Resolution
+
+By default, XIncludes are resolved before conversion (`--xinclude` defaults to `true`). This means any `xi:include` elements in the input file are processed and their content inlined before parsing.
+
+To skip XInclude resolution (for example, if the file does not use XIncludes or you want to process them separately):
+
+[source,bash]
+----
+$ docbook to-html book.xml -o output.html --no-xinclude
+----
+
+=== Generated Content
+
+The HTML output includes several computed features:
+
+[cols="2,5"]
+|===
+| Feature | Description
+
+| *Table of Contents* | Automatically generated from the document structure with hierarchical numbering
+| *Section Numbering* | Parts use Roman numerals (I, II, III), chapters use Arabic numbers (1, 2, 3), appendices use letters (A, B, C), sections use hierarchical numbering (1.1, 1.2.3)
+| *Cross-References* | `xref` elements are resolved to the target section's title
+| *Image Handling* | Single-file mode: Base64 data URIs. Directory mode: relative file paths
+| *Index Generation* | `indexterm` elements are collected and grouped alphabetically with see/see-also support
+|===
+
+=== Supported DocBook Elements
+
+The HTML output handles a wide range of DocBook elements, including:
+
+* *Block elements:* `para`, `section`, `chapter`, `part`, `appendix`, `preface`, `blockquote`, `programlisting`, `screen`, `literallayout`
+* *Lists:* `orderedlist`, `itemizedlist`, `variablelist`
+* *Admonitions:* `note`, `warning`, `caution`, `important`, `tip`, `danger`
+* *Media:* `mediaobject`, `inlinemediaobject`, `imageobject`, `imagedata`, `figure`, `informalfigure`
+* *Tables:* `table`, `tgroup`, `thead`, `tbody`, `row`, `entry`
+* *Inline:* `emphasis`, `link`, `xref`, `code`, `literal`, `filename`, `quote`, `citetitle`
+* *Bibliography:* `bibliomixed`, `biblioref`
+* *Glossary:* `glossentry`, `glossterm`, `glossdef`
+* *Reference pages:* `refentry`, `refnamediv`, `refsection`
+
+=== Examples
+
+==== Convert a simple article
+
+[source,bash]
+----
+$ docbook to-html article.xml -o article.html
+Written to article.html
+----
+
+==== Convert a book with XIncludes
+
+[source,bash]
+----
+$ docbook to-html book.xml -o book.html
+Written to book.html
+----
+
+==== Convert to directory for web serving
+
+[source,bash]
+----
+$ docbook to-html book.xml -o /var/www/html/book --output-type directory
+Written to /var/www/html/book/index.html and assets/
+----
+
+==== Pipe output to another command
+
+[source,bash]
+----
+$ docbook to-html article.xml | tidy -q -indent -xml > pretty.html
+----
+
+=== See Also
+
+* <<format-command,format>> -- Reformat DocBook XML
+* <<../ruby-api/html-output,Ruby API: HTML Output>> -- Programmatic HTML generation
+* <<../ruby-api/xinclude,Ruby API: XInclude Resolution>> -- XInclude processing details

data/docs/interfaces/cli/validate-command.adoc

@@ -0,0 +1,104 @@
+---
+layout: default
+title: validate
+parent: CLI Reference
+grand_parent: Interfaces
+nav_order: 2
+---
+
+== validate
+
+Validate the well-formedness of a DocBook XML file.
+
+=== Usage
+
+[source,bash]
+----
+$ docbook validate INPUT
+----
+
+=== Arguments
+
+[cols="2,4"]
+|===
+| Argument | Description
+
+| `INPUT` | Path to the DocBook XML file to validate (required)
+|===
+
+=== Behavior
+
+The `validate` command reads the input file and parses it with Nokogiri's XML parser. If the file is well-formed XML, it prints a success message to stdout. If parsing errors are found, each error is printed to stderr and the command exits with code 1.
+
+[IMPORTANT]
+====
+This command checks *well-formedness* only (valid XML syntax). It does not validate against the DocBook 5 DTD or RelaxNG schema. For schema validation, use an external tool like `jing` or `xmllint --valid`.
+====
+
+=== Exit Codes
+
+[cols="1,4"]
+|===
+| Code | Condition
+
+| `0` | The file is well-formed XML (no parse errors)
+| `1` | The file contains XML parse errors
+|===
+
+=== Examples
+
+==== Valid file
+
+[source,bash]
+----
+$ docbook validate article.xml
+article.xml: valid
+----
+
+==== Invalid file
+
+When the XML contains syntax errors, each error is reported:
+
+[source,bash]
+----
+$ docbook validate broken.xml
+broken.xml: 6:14: FATAL: Opening and ending tag mismatch: section line 4 and artcle
+broken.xml: 1 file, 1 failures
+$ echo $?
+1
+----
+
+==== Validate multiple files in a script
+
+Since the command exits with code 1 on failure, it integrates well with shell scripts:
+
+[source,bash]
+----
+#!/bin/bash
+set -e
+for f in xml/*.xml; do
+  docbook validate "$f"
+done
+echo "All files are valid"
+----
+
+==== Use in CI pipelines
+
+[source,bash]
+----
+# GitHub Actions example
+- name: Validate DocBook files
+  run: |
+    find . -name '*.xml' -exec docbook validate {} \;
+----
+
+=== Limitations
+
+* *No schema validation* -- Only checks XML well-formedness, not DocBook 5 schema compliance
+* *No XInclude resolution* -- XIncludes are not resolved before validation; the raw XML is checked as-is
+* *Single file at a time* -- Only one file can be validated per invocation (use a shell loop for batches)
+
+=== See Also
+
+* <<format-command,format>> -- Reformat and prettify XML files
+* <<roundtrip-command,roundtrip>> -- Round-trip test for deeper structural validation

data/docs/interfaces/index.adoc

@@ -0,0 +1,101 @@
+---
+layout: default
+title: Interfaces
+nav_order: 3
+has_children: true
+---
+
+== Interfaces
+
+The `docbook` gem provides two complementary interfaces for working with DocBook XML:
+
+* The *command-line interface* (CLI) for quick, scriptable operations
+* The *Ruby API* for programmatic integration into Ruby applications
+
+=== Which Interface Should You Use?
+
+[cols="3,4,4"]
+|===
+| | *CLI* | *Ruby API*
+
+| *Best for* | One-off conversions, shell scripts, CI pipelines | Application integration, custom processing pipelines, batch operations
+| *Audience* | Developers, authors, automation engineers | Ruby developers building tools or services
+| *Flexibility* | Fixed set of commands and options | Full access to parsing, traversal, and output internals
+| *Setup* | Zero code -- just run `docbook` commands | Add `require "docbook"` to your project
+|===
+
+=== Interface Overview
+
+==== Command-Line Interface
+
+The `docbook` CLI is a Thor-based command-line tool installed with the gem. It provides four commands:
+
+[cols="2,5"]
+|===
+| Command | Description
+
+| `docbook validate INPUT` | Check XML well-formedness
+| `docbook to-html INPUT` | Convert DocBook XML to HTML
+| `docbook format INPUT` | Prettify (reformat) DocBook XML
+| `docbook roundtrip INPUT...` | Round-trip test for regression testing
+|===
+
+All commands accept file paths as arguments. The CLI handles XInclude resolution, cross-reference resolution, and output generation automatically.
+
+See <<cli/index,CLI Reference>> for detailed documentation of each command.
+
+==== Ruby API
+
+The Ruby API gives you fine-grained control over every stage of the DocBook processing pipeline:
+
+1. *Parsing* -- `Docbook::Document.from_xml(xml_string)` parses XML into typed Ruby objects
+2. *XInclude Resolution* -- `Docbook::XIncludeResolver` resolves `xi:include` elements before parsing
+3. *Cross-Reference Resolution* -- `Docbook::XrefResolver` builds an ID map for `xref` and `linkend` lookups
+4. *HTML Output* -- `Docbook::Output::Html` generates HTML in single-file or directory mode
+
+The core classes are:
+
+[cols="3,5"]
+|===
+| Class | Purpose
+
+| `Docbook::Document` | Entry point for parsing XML into element models
+| `Docbook::XIncludeResolver` | Resolves XInclude elements in XML documents
+| `Docbook::XrefResolver` | Builds xml:id lookup map and resolves cross-references
+| `Docbook::Output::Html` | Generates HTML from parsed document models
+|===
+
+See <<ruby-api/index,Ruby API>> for detailed documentation of each component.
+
+=== Combining Both Interfaces
+
+You can combine the CLI and Ruby API in the same project. For example, use the CLI for quick ad-hoc conversions during development, and the Ruby API when you need to embed DocBook processing into a web application or a custom publishing pipeline.
+
+A typical Ruby workflow looks like this:
+
+[source,ruby]
+----
+require "docbook"
+
+# 1. Resolve XIncludes (before parsing)
+xml_string = File.read("book.xml")
+resolved = Docbook::XIncludeResolver.resolve_string(xml_string, base_path: "book.xml")
+
+# 2. Parse into Ruby objects
+document = Docbook::Document.from_xml(resolved.to_xml)
+
+# 3. Resolve cross-references
+xref_resolver = Docbook::XrefResolver.new(document).resolve!
+
+# 4. 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)
+----
+
+Explore the <<cli/index,CLI Reference>> and <<ruby-api/index,Ruby API>> pages for comprehensive documentation.