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/getting-started/quick-start.adoc ADDED Viewed

@@ -0,0 +1,161 @@
+---
+layout: default
+title: Quick Start
+parent: Getting Started
+nav_order: 2
+---
+== Quick Start
+This page walks you through the three most common operations using the `docbook` command-line tool: validating, converting to HTML, and formatting DocBook XML files.
+=== Prerequisites
+Make sure the gem is installed and the `docbook` command is available. See <<installation>> for details.
+For these examples, we will use a sample DocBook 5 article file called `article.xml`:
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<article xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="my-article">
+  <info>
+    <title>Getting Started with DocBook</title>
+  </info>
+  <section xml:id="intro">
+    <title>Introduction</title>
+    <para>This is a sample DocBook article demonstrating the basic features
+    of the Metanorma DocBook gem.</para>
+  </section>
+  <section xml:id="usage">
+    <title>Usage</title>
+    <para>See the <xref linkend="intro"/> for background information.</para>
+  </section>
+</article>
+----
+=== 1. Validate a DocBook File
+The `validate` command checks whether an XML file is well-formed:
+[source,bash]
+----
+$ docbook validate article.xml
+article.xml: valid
+----
+If the file contains errors, the command prints each error to stderr and exits with code 1:
+[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
+----
+*TIP:* The `validate` command checks XML well-formedness using Nokogiri. It does not validate against the DocBook schema (DTD or RelaxNG).
+=== 2. Convert to HTML
+The `to-html` command converts a DocBook XML file to a self-contained HTML document.
+==== Single-File Mode (default)
+[source,bash]
+----
+$ docbook to-html article.xml -o output.html
+Written to output.html
+----
+This produces a single HTML file with all assets (CSS, JavaScript, images) embedded inline. Images are converted to Base64 data URIs, making the file completely self-contained and portable.
+To write to stdout instead of a file, omit the `--output` option:
+[source,bash]
+----
+$ docbook to-html article.xml
+<!DOCTYPE html><html>...
+----
+==== Directory Mode
+Use `--output-type directory` to generate a multi-file output suitable for web serving:
+[source,bash]
+----
+$ docbook to-html article.xml -o my-book --output-type directory
+Written to my-book/index.html and assets/
+----
+Directory mode creates the following structure:
+[source]
+----
+my-book/
+  index.html          # HTML shell with Vue.js app
+  docbook.data.json   # Structured content data (TOC, sections, index)
+  assets/
+    app.css           # Stylesheet
+    app.iife.js       # Vue.js application bundle
+----
+==== XInclude Resolution
+By default, XIncludes are resolved before conversion. To disable this:
+[source,bash]
+----
+$ docbook to-html book.xml -o output.html --no-xinclude
+----
+=== 3. Format (Prettify) DocBook XML
+The `format` command reformats a DocBook XML file with consistent indentation:
+[source,bash]
+----
+$ docbook format article.xml -o formatted.xml
+Written to formatted.xml
+----
+The output is a properly indented XML document with an XML declaration:
+[source,xml]
+----
+<?xml version="1.0" encoding="utf-8"?>
+<article xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="my-article">
+  <info>
+    <title>Getting Started with DocBook</title>
+  </info>
+  <section xml:id="intro">
+    <title>Introduction</title>
+    <para>This is a sample DocBook article demonstrating the basic features
+    of the Metanorma DocBook gem.</para>
+  </section>
+</article>
+----
+To print to stdout, omit the `--output` option:
+[source,bash]
+----
+$ docbook format article.xml
+----
+To resolve XIncludes before formatting:
+[source,bash]
+----
+$ docbook format book.xml --xinclude -o book-flat.xml
+Written to book-flat.xml
+----
+=== Next Steps
+Now that you can validate, convert, and format DocBook files, explore the full documentation:
+* *<<interfaces,Interfaces>>* -- Detailed CLI reference and Ruby API documentation
+* *<<../interfaces/cli/,CLI Reference>>* -- All commands, options, and examples
+* *<<../interfaces/ruby-api/,Ruby API>>* -- Programmatic access to parsing, XInclude resolution, cross-references, and HTML output

data/docs/guides/converting-article.adoc ADDED Viewed

@@ -0,0 +1,188 @@
+---
+layout: default
+title: Converting an Article
+parent: Guides
+nav_order: 2
+---
+# Converting an Article
+Articles are simpler than books -- they have a flat structure with no
+parts, chapters, or appendices. This guide shows how to convert a
+DocBook article to HTML.
+== Article structure
+A DocBook article uses `<section>` elements for its hierarchy instead
+of the part/chapter structure of a book. Here is a complete example:
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<article xmlns="http://docbook.org/ns/docbook" version="5.0"
+         xml:id="api-design">
+  <info>
+    <title>API Design Principles</title>
+    <author>
+      <personname>
+        <firstname>Alex</firstname>
+        <surname>Architect</surname>
+      </personname>
+    </author>
+    <pubdate>2025-01-15</pubdate>
+  </info>
+  <section xml:id="s-overview">
+    <title>Overview</title>
+    <para>This article presents key principles for designing
+      robust and maintainable APIs.</para>
+    <section xml:id="s-overview-goals">
+      <title>Design Goals</title>
+      <para>An API should be consistent, discoverable, and
+        resilient to change.</para>
+    </section>
+  </section>
+  <section xml:id="s-patterns">
+    <title>Common Patterns</title>
+    <para>REST APIs typically follow these patterns:</para>
+    <itemizedlist>
+      <listitem>
+        <para>Use nouns for resource endpoints.</para>
+      </listitem>
+      <listitem>
+        <para>Return appropriate HTTP status codes.</para>
+      </listitem>
+      <listitem>
+        <para>Version your API from the start.</para>
+      </listitem>
+    </itemizedlist>
+    <example>
+      <title>Sample endpoint</title>
+      <programlisting language="bash">
+curl -X GET https://api.example.com/v1/users \
+  -H "Authorization: Bearer TOKEN"
+      </programlisting>
+    </example>
+  </section>
+  <section xml:id="s-error-handling">
+    <title>Error Handling</title>
+    <para>Always provide structured error responses:</para>
+    <programlisting language="json">
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "The 'email' field is required."
+  }
+}
+    </programlisting>
+    <note>
+      <title>Important</title>
+      <para>Never expose internal stack traces in production
+        error responses.</para>
+    </note>
+    <warning>
+      <para>Returning HTML error pages from a JSON API endpoint
+        breaks client parsing.</para>
+    </warning>
+  </section>
+  <section xml:id="s-figure-example">
+    <title>Architecture Diagram</title>
+    <figure>
+      <title>System Architecture</title>
+      <mediaobject>
+        <imageobject>
+          <imagedata fileref="images/architecture.png"/>
+        </imageobject>
+      </mediaobject>
+    </figure>
+  </section>
+</article>
+----
+== CLI conversion
+To convert the article to a single HTML file:
+....
+docbook to-html article.xml -o article.html
+....
+For directory output:
+....
+docbook to-html article.xml -o article-out --output-type directory
+....
+Note that XInclude resolution is enabled by default for `to-html`. If
+your article does not use XIncludes, this has no effect.
+== Ruby API conversion
+[source,ruby]
+----
+require "docbook"
+xml = File.read("article.xml")
+# Parse the article
+doc = Docbook::Document.from_xml(xml)
+# Resolve cross-references
+xref = Docbook::XrefResolver.new(doc).resolve!
+# Generate HTML (single file)
+html = Docbook::Output::Html.new(
+  doc,
+  xref_resolver: xref,
+  output_mode: :single_file,
+  base_path: File.dirname(File.expand_path("article.xml"))
+).to_html
+File.write("article.html", html)
+----
+== What to expect in the output
+The article conversion produces the following:
+* **Title** -- The article title from `<info><title>` appears in the
+  browser tab and as the document header.
+* **Section tree** -- Each `<section>` becomes a navigable entry in the
+  TOC sidebar. Nested sections appear as children.
+* **Numbering** -- Sections receive hierarchical numbers (1, 1.1, 2,
+  2.1, etc.).
+* **Code blocks** -- `<programlisting>` elements are rendered with
+  Prism.js syntax highlighting. The `language` attribute determines the
+  highlighting language.
+* **Lists** -- `<itemizedlist>` renders as a bulleted list,
+  `<orderedlist>` as a numbered list.
+* **Admonitions** -- `<note>`, `<warning>`, `<caution>`, `<important>`,
+  and `<tip>` render as styled callout boxes.
+* **Figures** -- `<figure>` with `<mediaobject>` renders the image with
+  an optional caption.
+* **Examples** -- `<example>` renders with its title and content.
+== Inline content
+Articles support the same inline elements as books. The following
+elements are rendered correctly inside `<para>` and other block
+elements:
+* `<emphasis>` -- Italic or bold (based on `role` attribute)
+* `<code>` and `<literal>` -- Monospace inline code
+* `<link xlink:href="...">` -- Hyperlinks
+* `<xref linkend="...">` -- Cross-references to other sections
+* `<filename>` -- File names in monospace
+* `<quote>` -- Quoted text
+* `<citetitle>` -- Citation titles

data/docs/guides/converting-book.adoc ADDED Viewed

@@ -0,0 +1,192 @@
+---
+layout: default
+title: Converting a Book
+parent: Guides
+nav_order: 1
+---
+# Converting a Book
+This guide walks through converting a complete DocBook 5 book document
+to HTML using the Metanorma DocBook gem.
+== Sample book structure
+A typical DocBook book has the following structure:
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<book xmlns="http://docbook.org/ns/docbook" version="5.0"
+      xml:id="my-book">
+  <info>
+    <title>My Technical Book</title>
+    <author>
+      <personname>
+        <firstname>Jane</firstname>
+        <surname>Developer</surname>
+      </personname>
+    </author>
+    <copyright>
+      <year>2025</year>
+      <holder>Acme Corp</holder>
+    </copyright>
+  </info>
+  <preface xml:id="preface">
+    <title>Preface</title>
+    <para>This book explains how to use the DocBook conversion tool.</para>
+  </preface>
+  <part xml:id="part-fundamentals">
+    <title>Part I. Fundamentals</title>
+    <chapter xml:id="ch-intro">
+      <title>Introduction</title>
+      <para>Content of the introduction chapter.</para>
+      <section xml:id="ch-intro-overview">
+        <title>Overview</title>
+        <para>Detailed overview content.</para>
+      </section>
+    </chapter>
+    <chapter xml:id="ch-setup">
+      <title>Getting Started</title>
+      <para>Setup instructions here.</para>
+    </chapter>
+  </part>
+  <appendix xml:id="appendix-a">
+    <title>Appendix A. Additional Resources</title>
+    <para>Supplementary material.</para>
+  </appendix>
+  <glossary xml:id="glossary">
+    <title>Glossary</title>
+    <glossentry>
+      <glossterm>DocBook</glossterm>
+      <glossdef>
+        <para>A semantic markup language for technical documentation.</para>
+      </glossdef>
+    </glossentry>
+  </glossary>
+  <bibliography xml:id="bibliography">
+    <title>References</title>
+    <bibliomixed>
+      <abbrev>DocBook5</abbrev>
+      <title>DocBook 5: The Definitive Guide</title>
+    </bibliomixed>
+  </bibliography>
+  <index xml:id="index"/>
+</book>
+----
+== Step 1: Validate the input
+Before conversion, validate that the XML is well-formed:
+....
+docbook validate book.xml
+....
+If the file is valid, the command prints `book.xml: valid` and exits
+with code 0. If there are errors, they are printed to stderr and the
+command exits with code 1.
+== Step 2: Check XIncludes (if applicable)
+If your book uses `<xi:include>` to pull in chapters from separate
+files, verify that all referenced files exist and are well-formed XML.
+XInclude resolution is enabled by default for `to-html`.
+== Step 3: Convert to single-file HTML
+For a self-contained HTML file:
+....
+docbook to-html book.xml -o output.html
+....
+This produces `output.html` with all data, CSS, and JavaScript
+inlined. You can open it directly in any browser.
+== Step 4: Convert to directory output
+For a directory-based output with linked assets:
+....
+docbook to-html book.xml -o my-book --output-type directory
+....
+This creates a `my-book/` directory containing:
+* `index.html` -- The HTML shell with the Vue SPA mount point
+* `docbook.data.json` -- The full document data as JSON
+* `assets/app.css` -- The compiled stylesheet
+* `assets/app.iife.js` -- The bundled JavaScript
+== Step 5: Open in browser
+Open the HTML file or directory in a web browser. You should see:
+* **TOC sidebar** -- A collapsible tree showing all parts, chapters,
+  and sections with their section numbers.
+* **Section numbering** -- Parts labeled with Roman numerals (I, II),
+  chapters with Arabic numbers (1, 2), and sections with hierarchical
+  dotted numbers (1.1, 1.2.3).
+* **Chapter navigation** -- Click any TOC entry to navigate to that
+  section.
+* **Search** -- Use the search function to find sections by title.
+* **Index page** -- If the book contains `<indexterm>` elements, an
+  index section with entries grouped by letter.
+* **Settings** -- Theme, font size, reading mode, and other preferences.
+== Using the Ruby API
+You can also convert programmatically:
+[source,ruby]
+----
+require "docbook"
+xml = File.read("book.xml")
+# Parse
+doc = Docbook::Document.from_xml(xml)
+# Resolve cross-references
+xref = Docbook::XrefResolver.new(doc).resolve!
+# Generate HTML
+html = Docbook::Output::Html.new(
+  doc,
+  xref_resolver: xref,
+  output_mode: :single_file,
+  base_path: File.dirname(File.expand_path("book.xml"))
+).to_html
+File.write("output.html", html)
+----
+== Troubleshooting
+Unsupported root element::
+Ensure the XML root element is one of the 37 supported types listed
+in `Document::ROOT_ELEMENT_MAP`. The most common roots are `book`,
+`article`, and `set`.
+Missing images in output::
+The converter resolves image paths relative to the input file's
+directory. It also searches parent directories and common prefixes
+like `resources/`. If images are still missing, check that the
+`fileref` attribute in `<imagedata>` points to a valid file.
+XInclude errors::
+XInclude resolution requires that referenced files exist and are
+accessible from the input file's location. Check file paths and
+permissions.
+Empty output::
+If the output HTML appears empty, the document may not contain any
+recognized block elements. Ensure chapters and sections contain
+`<para>`, `<programlisting>`, or other supported block elements.

data/docs/guides/index.adoc ADDED Viewed

@@ -0,0 +1,12 @@
+---
+layout: default
+title: Guides
+nav_order: 7
+has_children: true
+---
+# Guides
+This section contains task-oriented tutorials that walk you through
+common scenarios step by step. Each guide is self-contained and
+includes complete examples you can run immediately.

data/docs/guides/roundtrip-testing.adoc ADDED Viewed

@@ -0,0 +1,129 @@
+---
+layout: default
+title: Round-trip Testing
+parent: Guides
+nav_order: 3
+---
+# Round-trip Testing
+The `docbook roundtrip` command verifies that the element model can
+faithfully parse and re-serialize a DocBook XML document. This is
+essential for ensuring model completeness and serialization fidelity.
+== How round-trip testing works
+The round-trip test performs the following sequence:
+. **Parse** -- The input XML is parsed into element model objects via
+  `Document.from_xml`.
+. **Serialize** -- The model objects are serialized back to XML using
+  `to_xml` with pretty printing enabled.
+. **Re-parse** -- The serialized XML is parsed again.
+. **Compare** -- If the second parse succeeds without errors, the test
+  passes.
+A successful round-trip confirms that:
+* All elements and attributes in the input are represented in the model.
+* The XML serialization produces valid DocBook XML.
+* The serialized output can be parsed again without errors.
+Note that the test does not compare the original and re-serialized XML
+strings character-by-character. Differences in whitespace, attribute
+order, and namespace declarations are acceptable as long as the
+re-parsing succeeds.
+== Using the CLI
+Test one or more files:
+....
+docbook roundtrip book.xml
+docbook roundtrip chapter1.xml chapter2.xml chapter3.xml
+....
+For each file, the command prints either `filename.xml: OK` or
+`filename.xml: FAIL - error message`. At the end, it prints a summary:
+....
+3 files, 0 failures
+....
+If any file fails, the command exits with code 1.
+== Using in CI pipelines
+Round-trip testing is valuable in continuous integration. Add a step
+to your CI configuration that runs round-trip tests against a corpus
+of DocBook files:
+[source,yaml]
+----
+# GitHub Actions example
+- name: Round-trip test
+  run: |
+    find spec/fixtures -name '*.xml' -print0 | \
+      xargs -0 bundle exec docbook roundtrip
+----
+This discovers all XML fixture files and tests them in a single
+invocation. The command fails the build if any file does not
+round-trip successfully.
+== Ruby API
+You can also run round-trip tests programmatically:
+[source,ruby]
+----
+require "docbook"
+def roundtrip_test(xml_string)
+  parsed = Docbook::Document.from_xml(xml_string)
+  serialized = parsed.to_xml(declaration: true, encoding: "utf-8")
+  reparsed = Docbook::Document.from_xml(serialized)
+  true
+rescue => e
+  puts "Round-trip failed: #{e.message}"
+  false
+end
+----
+== Interpreting failures
+Round-trip failures typically indicate one of the following issues:
+Unsupported element::
+If the input contains an element that has no corresponding model class,
+`Document.from_xml` raises a "Unsupported root element" error. The
+solution is to add the missing element class.
+Missing attribute::
+If an element's XML mapping does not declare an attribute that appears
+in the input, the attribute is silently dropped during parsing. The
+re-serialized XML will lack the attribute. This usually manifests as
+a different parse result on the second pass.
+Broken mixed content::
+If an element declares `mixed_content` but its child element mappings
+are incomplete, some children may be lost during serialization. Check
+that all expected child elements are declared in the element class.
+Serialization error::
+If the model's `to_xml` produces malformed XML (for example, due to
+incorrect namespace handling), the re-parse step will fail with a
+Nokogiri parse error. The error message usually identifies the line
+and column where the problem occurs.
+== Testing with XIncludes
+Round-trip testing operates on the raw XML without resolving XIncludes.
+If you want to test XInclude resolution as well, resolve the includes
+first, then run the round-trip on the resolved document:
+....
+# Resolve XIncludes first, then round-trip the resolved XML
+resolved = Docbook::XIncludeResolver.resolve_string(xml_string, base_path: "book.xml")
+Docbook::Document.from_xml(resolved.to_xml)
+....