docbook 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a64ef89c39e9981b971c18bca30eda85a2ab034f3c5a176d32ae55fc6c311c09
+  data.tar.gz: '0931c9d12ced953ea69c9538af2a9c3f320d2ee9135c3d9247b4a0b1bca1786f'
+SHA512:
+  metadata.gz: 04e31fbc21354f7aa37acc67c08d3d6c107916ea255bc90c015d8316624a3c2eb65ca2f64aba6cf12ab78a1dc85ea5ddad0394b42339458cc7939b912ae9fc09
+  data.tar.gz: f0524cb42079fa8909d25a75358658a6e1528a280f95ec426617b9da9441c959976ca776fc267ff86aa66aaa309c2c27db77874acef39b3c2eb4455a0139c9b2

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-04-05
+
+- Initial release

data/CLAUDE.md

@@ -0,0 +1,19 @@
+# CLAUDE.md
+
+## Critical Rules
+
+### NEVER HANDLE RAW XML ELEMENTS
+You MUST NOT handle raw XML elements (such as those from Nokogiri) in HTML processing code. Any violation will be considered a serious error.
+
+**Rule:** All HTML generation must go through the Docbook model classes only. If the Docbook models are insufficient, they MUST be improved to support the required functionality.
+
+**Why:** Handling raw XML bypasses the abstraction layer and creates brittle, non-portable code that doesn't work with the established model infrastructure.
+
+**How to apply:** When processing XML content for HTML output, always use the Lutaml::Model-based Docbook element classes (in `lib/docbook/elements/`). If an element type is not supported in the models, add it to the appropriate element class rather than processing raw XML nodes.
+
+### Examples
+- **WRONG:** `node.xpath('...')` or `Nokogiri::XML::Node` manipulation in HTML generation
+- **RIGHT:** Use element classes like `Docbook::Elements::InformalFigure`, `Docbook::Elements::MediaObject`, etc.
+
+### Image Path Resolution
+Image paths should be resolved using the Docbook element's xml:base when available, per the Docbook spec. The `process_image` method in Html class handles this by searching parent paths as a fallback when xml:base is not preserved by the parser.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"docbook" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["ronald.tse@ribose.com"](mailto:"ronald.tse@ribose.com").

data/README.adoc

@@ -0,0 +1,335 @@
+= DocBook
+:toc:
+:toclevels: 2
+
+== Purpose
+
+DocBook is a Ruby gem for parsing, transforming, and generating HTML from
+DocBook 5 XML documents. It provides a complete toolkit for working with
+DocBook documents including XInclude resolution, validation, formatting, and
+high-quality HTML output.
+
+Key features:
+
+* **DocBook XML Parsing**: Full support for DocBook 5 elements via lutaml-model
+* **XInclude Resolution**: Resolve XInclude references in DocBook documents
+* **HTML Output**: Generate professional HTML documentation with Vue 3 SPA
+* **CLI Tools**: Format, validate, and convert DocBook documents
+
+== Installation
+
+Add to your application Gemfile:
+
+[source,ruby]
+----
+gem 'docbook'
+----
+
+Then execute:
+
+[source,bash]
+----
+$ bundle install
+----
+
+Or install directly:
+
+[source,bash]
+----
+$ gem install docbook
+----
+
+== Quick start
+
+=== Convert DocBook XML to HTML
+
+[source,bash]
+----
+$ docbook to-html input.xml -o output.html
+----
+
+=== With XInclude resolution
+
+[source,bash]
+----
+$ docbook to-html --xinclude input.xml -o output.html
+----
+
+=== Format DocBook XML
+
+[source,bash]
+----
+$ docbook format input.xml -o output.xml
+----
+
+=== Validate DocBook XML
+
+[source,bash]
+----
+$ docbook validate input.xml
+input.xml: valid
+----
+
+=== Ruby API
+
+[source,ruby]
+----
+require 'docbook'
+
+# Parse a DocBook document
+article = Docbook::Elements::Article.from_xml(File.read('input.xml'))
+
+# Convert to HTML
+html_output = Docbook::Output::Html.new(article).to_html
+
+# Write to file
+File.write('output.html', html_output)
+----
+
+== CLI Commands
+
+=== to-html
+
+Convert DocBook XML to HTML with Vue 3 SPA output.
+
+[source,bash]
+----
+# Basic usage
+$ docbook to-html INPUT -o OUTPUT
+
+# With XInclude resolution
+$ docbook to-html --xinclude INPUT -o OUTPUT
+
+# Output to stdout
+$ docbook to-html INPUT
+----
+
+Options:
+
+* `-o, --output FILE`: Output file (default: stdout)
+* `--xinclude`: Resolve XIncludes before processing
+
+=== format
+
+Format/prettify DocBook XML documents.
+
+[source,bash]
+----
+# Basic usage
+$ docbook format INPUT -o OUTPUT
+
+# With XInclude resolution
+$ docbook format --xinclude INPUT -o OUTPUT
+----
+
+Options:
+
+* `-o, --output FILE`: Output file (default: stdout)
+* `--xinclude`: Resolve XIncludes before processing
+
+=== validate
+
+Validate DocBook XML for well-formedness.
+
+[source,bash]
+----
+$ docbook validate input.xml
+input.xml: valid
+----
+
+Returns exit code 0 if valid, exit code 1 with error messages if invalid.
+
+=== roundtrip
+
+Round-trip test DocBook XML files (parse and re-serialize).
+
+[source,bash]
+----
+$ docbook roundtrip input1.xml input2.xml
+input1.xml: OK
+input2.xml: OK
+2 files, 0 failures
+----
+
+== HTML Output Features
+
+The HTML output is a self-contained Vue 3 SPA that works with `file://` protocol
+(no server required).
+
+=== Vue 3 SPA
+
+* **Pre-compiled Vue 3**: No build step required at runtime
+* **FlexSearch**: Full-text search across all headings
+* **Collapsible TOC**: Hierarchical table of contents with expand/collapse
+* **Keyboard navigation**: Press `/` to search, `Esc` to close
+
+=== Theme Support
+
+* **Dark mode**: Toggle between light, dark, and system preference
+* **Font selection**: Sans-serif (Inter) and serif (Merriweather) options
+* **Persistent settings**: Theme and font preferences saved to localStorage
+
+=== Document Structure
+
+* **Chapter numbering**: Roman numerals for chapters (I, II, III...)
+* **Appendix numbering**: "Appendix A", "Appendix B", etc.
+* **Section numbering**: Dot notation (1.1, 1.2, 2.1...)
+* **Part organization**: Parts contain chapters, appendices, and references
+
+=== Content Types
+
+The HTML output supports rendering of:
+
+* Paragraphs and formal paragraphs
+* Ordered and unordered lists
+* Variable lists
+* Figures and media objects
+* Tables with headers and footers
+* Code blocks with syntax highlighting
+* Block quotations
+* Admonitions (note, warning, caution, important, tip, danger)
+* Bibliography and glossary
+* Procedure steps
+* Sidebars
+
+== Ruby API
+
+=== Parsing DocBook Documents
+
+[source,ruby]
+----
+require 'docbook'
+
+# Parse from file
+article = Docbook::Elements::Article.from_xml(File.read('article.xml'))
+
+# Parse book with parts
+book = Docbook::Elements::Book.from_xml(File.read('book.xml'))
+
+# Parse with XInclude resolution
+xml_string = File.read('main.xml')
+resolved = Docbook::XIncludeResolver.resolve_string(xml_string, base_path: 'main.xml')
+docbook_doc = Docbook::Document.from_xml(resolved.to_xml)
+----
+
+=== Document Types
+
+The gem automatically detects and parses:
+
+* `article` - Article documents
+* `book` - Book documents with parts, chapters, appendices
+* `chapter` - Chapter documents
+* `section` - Section documents
+* `refentry` - Reference manual pages
+
+=== HTML Output
+
+[source,ruby]
+----
+require 'docbook'
+
+# Create HTML output
+article = Docbook::Elements::Article.from_xml(File.read('input.xml'))
+html_output = Docbook::Output::Html.new(article).to_html
+
+# Write to file
+File.write('output.html', html_output)
+----
+
+=== Document Model
+
+Access document structure through the element model:
+
+[source,ruby]
+----
+book = Docbook::Elements::Book.from_xml(File.read('book.xml'))
+
+# Access book elements
+book.info.title.content  # Book title
+book.part                 # Array of parts
+book.chapter              # Array of top-level chapters
+book.appendix             # Array of appendices
+book.glossary             # Array of glossaries
+book.bibliography         # Array of bibliographies
+
+# Access part contents
+book.part.each do |part|
+  puts part.title.content
+  part.chapter.each do |chapter|
+    puts "  #{chapter.title.content}"
+  end
+end
+----
+
+== Building the Vue Frontend
+
+The HTML output uses a pre-compiled Vue 3 frontend. To rebuild after
+frontend changes:
+
+[source,bash]
+----
+cd frontend
+npm install
+npm run build
+----
+
+This generates the Vue bundle in `lib/docbook/frontend/dist/`.
+
+The bundle is automatically included when generating HTML output through the Ruby API.
+
+== Development
+
+After checking out the repo, run `bin/setup` to install dependencies:
+
+[source,bash]
+----
+bin/setup
+----
+
+Run the test suite:
+
+[source,bash]
+----
+bundle exec rake spec
+----
+
+Run specific test files:
+
+[source,bash]
+----
+bundle exec rspec spec/output/html_spec.rb
+bundle exec rspec spec/cli_spec.rb
+----
+
+== Architecture
+
+The gem follows a modular architecture:
+
+* **Parser**: Uses lutaml-model for DocBook element mapping
+* **XInclude Resolver**: Nokogiri-based XInclude processing
+* **HTML Generator**: Ruby-based HTML transformation with Vue 3 SPA
+* **CLI**: Thor-based command-line interface
+
+=== Element Classes
+
+The gem defines element classes for all major DocBook 5 elements:
+
+* **Structural**: article, book, chapter, part, section, appendix, preface
+* **Block**: para, formalpara, blockquote, literallayout
+* **Lists**: orderedlist, itemizedlist, variablelist
+* **Links**: link, xref, uri
+* **Inline**: emphasis, code, literal, filename, classname, function
+* **Media**: mediaobject, figure, table
+* **Admonitions**: note, warning, caution, important, tip, danger
+* **Bibliography**: bibliography, bibliomixed
+* **Glossary**: glossary, glossentry
+* **Metadata**: info, title, author, copyright
+
+== Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/metanorma/metanorma-docbook.
+
+== License
+
+Copyright Ribose. https://opensource.org/licenses/MIT[MIT License].

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/docs/.lycheeignore

@@ -0,0 +1,33 @@
+# Lychee ignore patterns
+# These link types are valid but lychee can't verify them
+
+# Ignore .adoc source files
+\.adoc$
+
+# Ignore .html files with inconsistent paths
+\.html$
+
+# Ignore file:// URLs
+file://
+
+# Ignore directory links
+file://.*/docbook/$
+file://.*/docbook/.*/$
+file://.*/docs/$
+file://.*/docs/.*/$
+
+# Ignore example domain links
+http://example\.com/.*
+http://a\.com/.*
+http://b\.com/.*
+
+# Ignore GitHub-specific links
+https://github\.com/[^/]+/[^/]+/edit/.*
+https://github\.com/[^/]+/[^/]+/blob/.*
+
+# Ignore mailto links
+mailto:.*
+
+# Ignore localhost
+http://localhost:.*
+http://127\.0\.0\.1:.*

data/docs/Gemfile

@@ -0,0 +1,10 @@
+source "https://rubygems.org"
+
+gem "jekyll", "~> 4.3"
+gem "jekyll-asciidoc"
+gem "just-the-docs"
+
+group :jekyll_plugins do
+  gem "jekyll-seo-tag"
+  gem "jekyll-sitemap"
+end

data/docs/INDEX.adoc

@@ -0,0 +1,67 @@
+---
+layout: default
+title: Home
+nav_order: 1
+description: "Metanorma DocBook: Parse, transform, and generate HTML from DocBook 5 XML"
+permalink: /
+---
+= Metanorma DocBook Documentation
+:toc: macro
+:toclevels: 2
+
+[.lead]
+Metanorma DocBook is a Ruby gem for parsing, accessing, and converting DocBook 5 XML documents to interactive HTML.
+
+toc::[]
+
+== Welcome
+
+Metanorma DocBook helps you:
+
+* **Parse** DocBook 5 XML into Ruby object models using 149 element classes
+* **Convert** DocBook to self-contained HTML with a Vue 3 interactive reader
+* **Resolve** XIncludes with text fragid extensions (`search=`, `line=`, `char=`)
+* **Validate** and **format** DocBook XML from the command line
+
+== Quick Navigation
+
+=== By Your Role
+
+**Developer**::
+Start with link:getting-started/ruby-api/[Ruby API] to integrate DocBook parsing into your applications.
+
+**Technical Writer**::
+Start with link:guides/converting-book/[Converting a Book] to convert DocBook documents to HTML.
+
+**DevOps**::
+Start with link:interfaces/cli/[CLI Reference] for command-line usage in pipelines.
+
+=== By Task
+
+**Convert DocBook to HTML**::
+link:getting-started/quick-start/#to-html[Quick Start: to-html] | link:interfaces/cli/to-html-command[CLI: to-html] | link:interfaces/ruby-api/html-output[Ruby API: HTML Output]
+
+**Resolve XIncludes**::
+link:features/xinclude/text-includes[Text Includes] | link:features/xinclude/fragid-schemes[fragid Schemes] | link:interfaces/ruby-api/xinclude[Ruby API]
+
+**Format and validate XML**::
+link:interfaces/cli/format-command[format] | link:interfaces/cli/validate-command[validate]
+
+=== By Document Type
+
+link:guides/converting-book[**Book**]:: Multi-part books with chapters, appendices, glossary, and index
+link:guides/converting-article[**Article**]:: Standalone articles with sections
+link:reference/supported-elements[**Reference pages**]:: RefEntry manual pages
+
+== Learning Path
+
+. *Get Started (5 minutes)* -- link:getting-started/installation[Install] and link:getting-started/quick-start[try basic commands]
+. *Learn Interfaces (15 minutes)* -- link:interfaces/cli/[CLI] or link:interfaces/ruby-api/[Ruby API]
+. *Explore Features (30 minutes)* -- link:features/html-output/[HTML output], link:features/xinclude/[XInclude], link:features/numbering[Numbering]
+. *Understand Internals (as needed)* -- link:understanding/architecture[Architecture], link:understanding/data-models[Data Models]
+
+== Getting Help
+
+**Found a bug?**:: link:https://github.com/metanorma/docbook/issues[Report an issue on GitHub]
+
+**Have a question?**:: Check link:reference/glossary[Glossary] or search this documentation

data/docs/_config.yml

@@ -0,0 +1,186 @@
+# Jekyll configuration for Metanorma DocBook documentation
+# Uses Just the Docs theme - https://just-the-docs.com/
+
+# Site settings
+title: Metanorma DocBook Documentation
+description: Parse, transform, and generate HTML from DocBook 5 XML documents
+url: https://www.metanorma.org
+baseurl: /docbook
+
+# Repository
+repository: metanorma/docbook
+
+# Theme
+theme: just-the-docs
+remote_theme: just-the-docs/just-the-docs@v0.7.0
+color_scheme: light
+
+# AsciiDoc support
+asciidoc: {}
+asciidoctor:
+  attributes:
+    idprefix: ''
+    idseparator: '-'
+    source-highlighter: rouge
+    icons: font
+    experimental: true
+    sectanchors: true
+    linkattrs: true
+    sectnums: true
+    toc: left
+    toclevels: 3
+
+# Search configuration
+search_enabled: true
+search:
+  heading_level: 3
+  previews: 3
+  preview_words_before: 5
+  preview_words_after: 10
+  tokenizer_separator: /[\s/]+/
+  rel_url: true
+  button: true
+
+# Navigation
+nav_sort: case_insensitive
+nav_fold: true
+
+# External links
+aux_links:
+  "Source":
+    - "https://github.com/metanorma/docbook"
+  "Report Issues":
+    - "https://github.com/metanorma/docbook/issues"
+
+aux_links_new_tab: true
+
+# Back to top
+back_to_top: true
+back_to_top_text: "Back to top"
+
+# Heading anchors
+heading_anchors: true
+
+# Footer
+footer_content: 'Copyright &copy; 2025 Ribose. Distributed under the <a href="https://github.com/metanorma/docbook/blob/main/LICENSE.txt">BSD 2-Clause License</a>.'
+
+# Footer last edit timestamp
+last_edit_timestamp: true
+last_edit_time_format: "%b %e %Y at %I:%M %p"
+
+# Enable code copy button
+enable_copy_code_button: true
+
+# Callouts
+callouts_level: quiet
+callouts:
+  highlight:
+    color: yellow
+  important:
+    title: Important
+    color: blue
+  new:
+    title: New
+    color: green
+  note:
+    title: Note
+    color: purple
+  warning:
+    title: Warning
+    color: red
+
+# Plugins
+plugins:
+  - jekyll-asciidoc
+  - jekyll-seo-tag
+  - jekyll-sitemap
+
+# Markdown settings (for any markdown files)
+markdown: kramdown
+kramdown:
+  input: GFM
+  hard_wrap: false
+  syntax_highlighter: rouge
+
+# Collections for organizing content
+collections:
+  getting-started:
+    permalink: "/:path/"
+    output: true
+
+  interfaces:
+    permalink: "/:collection/:path/"
+    output: true
+
+  features:
+    permalink: "/:collection/:path/"
+    output: true
+
+  understanding:
+    permalink: "/:collection/:path/"
+    output: true
+
+  advanced:
+    permalink: "/:collection/:path/"
+    output: true
+
+  guides:
+    permalink: "/:collection/:path/"
+    output: true
+
+  reference:
+    permalink: "/:collection/:path/"
+    output: true
+
+# Just the Docs collection configuration
+just_the_docs:
+  collections:
+    getting-started:
+      name: Getting Started
+      nav_fold: false
+    interfaces:
+      name: Interfaces
+      nav_fold: true
+    features:
+      name: Features
+      nav_fold: true
+    understanding:
+      name: Understanding
+      nav_fold: true
+    advanced:
+      name: Advanced
+      nav_fold: true
+    guides:
+      name: Guides
+      nav_fold: true
+    reference:
+      name: Reference
+      nav_fold: true
+
+# Defaults
+defaults:
+  - scope:
+      path: ""
+      type: getting-started
+    values:
+      layout: default
+
+# Include additional files
+include:
+  - "*.adoc"
+
+# Exclude from processing
+exclude:
+  - Gemfile
+  - Gemfile.lock
+  - node_modules
+  - vendor
+  - .sass-cache
+  - .jekyll-cache
+  - .bundle
+  - README.md
+  - LICENSE
+  - .git
+  - .gitignore
+
+permalink: pretty