canon 0.1.8 → 0.1.9

data/old-docs/TMP.adoc

@@ -1,3384 +0,0 @@
-= Canon: Canonicalization for serialization formats
-
-A Ruby library for canonicalizing and pretty-printing XML, HTML, YAML, and JSON
-with RSpec matchers for equivalence testing.
-
-
-== Purpose
-
-Canon provides canonicalization and pretty-printing for various serialization
-formats (XML, HTML, JSON, YAML), producing standardized forms suitable for
-comparison, testing, digital signatures, and human-readable output.
-
-
-== Architecture
-
-Canon follows an **orchestrator pattern** with clear separation of concerns.
-
-=== Comparison module
-
-The `Canon::Comparison` module (123 lines) acts as a pure orchestrator that:
-
-* Detects input format (XML, HTML, JSON, YAML)
-* Validates format compatibility
-* Delegates to format-specific comparator classes
-
-Format-specific comparators:
-
-* `Canon::Comparison::XmlComparator` - XML semantic comparison
-* `Canon::Comparison::HtmlComparator` - HTML semantic comparison
-* `Canon::Comparison::JsonComparator` - JSON/Ruby object comparison
-* `Canon::Comparison::YamlComparator` - YAML comparison (delegates to JsonComparator)
-
-Each comparator is self-contained and handles all comparison logic for its format.
-
-=== DiffFormatter module
-
-The `Canon::DiffFormatter` class (171 lines) acts as a pure orchestrator that:
-
-* Manages diff options (colors, visualization, context)
-* Detects diff mode (by-object vs by-line)
-* Delegates to mode-specific and format-specific formatters
-
-Two diff modes:
-
-**By-object mode** (tree-based semantic diff):
-
-* `Canon::DiffFormatter::ByObject::BaseFormatter` - Factory and common logic
-* `Canon::DiffFormatter::ByObject::XmlFormatter` - XML DOM differences
-* `Canon::DiffFormatter::ByObject::JsonFormatter` - Ruby object differences
-* `Canon::DiffFormatter::ByObject::YamlFormatter` - YAML differences
-
-**By-line mode** (line-based diff):
-
-* `Canon::DiffFormatter::ByLine::BaseFormatter` - LCS algorithm and factory
-* `Canon::DiffFormatter::ByLine::XmlFormatter` - DOM-guided XML line diff
-* `Canon::DiffFormatter::ByLine::JsonFormatter` - Semantic JSON line diff
-* `Canon::DiffFormatter::ByLine::YamlFormatter` - Semantic YAML line diff
-* `Canon::DiffFormatter::ByLine::SimpleFormatter` - Fallback line diff
-
-Each formatter handles format-specific intelligence (DOM parsing, token
-highlighting, semantic understanding).
-
-=== Object-oriented diff foundation
-
-Canon uses three foundational classes for managing diff data:
-
-* `Canon::Diff::DiffBlock` - Represents a contiguous block of changes
-* `Canon::Diff::DiffContext` - Groups diff blocks with surrounding context
-* `Canon::Diff::DiffReport` - Top-level container for complete diff results
-
-These classes ensure clean separation by providing clear ownership of diff data
-at different granularity levels.
-
-
-== Features
-
-=== Ruby API
-
-Single API for working with all four formats (XML, HTML, JSON, YAML).
-
-
-=== XML canonicalization
-
-Format XML documents according to the
-https://www.w3.org/TR/xml-c14n11/[W3C Canonical XML Version 1.1] specification.
-
-Key features:
-
-* Namespace declaration ordering (lexicographic by prefix)
-* Attribute ordering (lexicographic by namespace URI, then local name)
-* Character encoding normalization to UTF-8
-* Special character encoding in text and attributes
-* Removal of superfluous namespace declarations
-* Support for xml:base, xml:lang, xml:space, and xml:id attributes
-* Processing instruction and comment handling
-* Document subset support with attribute inheritance
-
-=== HTML canonicalization
-
-Format HTML 4/5 and XHTML documents with consistent formatting. Automatically
-detects HTML vs XHTML and applies appropriate formatting.
-
-=== YAML canonicalization
-
-Format YAML documents with keys sorted alphabetically at all levels of the
-structure.
-
-=== JSON canonicalization
-
-Format JSON documents with keys sorted alphabetically at all levels of the
-structure.
-
-
-=== Output modes
-
-Canon supports two output modes for all formats:
-
-`c14n` (canonical):: Compact output without indentation, suitable for digital
-signatures, hashing, and equivalence testing. Removes formatting whitespace.
-
-`pretty` (pretty-print):: Human-readable output with consistent indentation.
-Configurable indent size and type (spaces or tabs). This is the default mode for
-CLI commands.
-
-
-=== RSpec matchers
-
-Provides matchers for testing equivalence between serialized formats.
-
-NOTE: RSpec matchers always use canonical (c14n) mode for comparison to ensure
-formatting differences don't affect test results.
-
-=== Comparison API
-
-Canon provides a `Canon::Comparison` module for semantic comparison of HTML and
-XML documents.
-
-The `Canon::Comparison.equivalent?` method compares two documents for semantic
-equivalence, ignoring formatting differences that don't affect meaning.
-
-Key features:
-
-* Semantic comparison (content, not formatting)
-* Whitespace normalization
-* Comment handling (can ignore or include)
-* Attribute sorting
-* Support for both HTML and XML documents
-* Optional verbose diff output
-
-NOTE: `Canon::Comparison.equivalent?` adopts option names used by the excellent
-https://github.com/vkononov/compare-xml[`compare-xml` gem].
-
-
-
-== Usage
-
-=== Command-line usage
-
-=== Installation
-
-After installing the gem, the `canon` command will be available:
-
-[source,bash]
-----
-$ gem install canon
-$ canon --help
-----
-
-=== Format command
-
-The `format` command formats files in XML, HTML, JSON, or YAML.
-
-==== Output modes
-
-`pretty` (default):: Human-readable output with indentation (2 spaces default)
-`c14n`:: Canonical form without indentation
-
-==== Command syntax
-
-[source,bash]
-----
-canon format FILE [OPTIONS]
-----
-
-==== Options
-
-`-f, --format FORMAT`:: Specify format: `xml`, `html`, `json`, or `yaml`
-(auto-detected from extension if not specified)
-
-`-m, --mode MODE`:: Output mode: `pretty` (default) or `c14n`
-
-`-i, --indent N`:: Indentation spaces for pretty mode (default: 2)
-
-`--indent-type TYPE`:: Indentation type: `space` (default) or `tab`
-
-`-o, --output FILE`:: Write output to file instead of stdout
-
-`-c, --with-comments`:: Include comments in canonical XML output
-
-==== Examples
-
-[source,bash]
-----
-# Pretty-print (default mode)
-$ canon format input.xml
-<?xml version="1.0" encoding="UTF-8"?>
-<root>
-  <a>1</a>
-  <b>2</b>
-</root>
-
-# Canonical mode (compact)
-$ canon format input.xml --mode c14n
-<root><a>1</a><b>2</b></root>
-
-# Custom indentation
-$ canon format input.xml --mode pretty --indent 4
-$ canon format input.json --indent 4
-
-# Tab indentation
-$ canon format input.xml --indent-type tab
-$ canon format input.html --mode pretty --indent-type tab
-
-# Specify format explicitly
-$ canon format data.txt --format xml
-
-# Save to file
-$ canon format input.xml --output formatted.xml
-
-# Include XML comments in canonical output
-$ canon format doc.xml --mode c14n --with-comments
-
-# HTML files
-$ canon format page.html
-$ canon format page.html --mode c14n
-----
-
-
-=== Diff command
-
-Compare two files using **semantic comparison** that understands the structure of
-XML, HTML, JSON, and YAML formats. Unlike traditional text-based diff tools,
-`canon diff` compares the meaning and structure of your data, not just the
-characters.
-
-==== Command syntax
-
-[source,bash]
-----
-canon diff FILE1 FILE2 [OPTIONS]
-----
-
-==== Diff modes
-
-Canon supports two diff modes optimized for different use cases:
-
-===== by-object mode (default for JSON/YAML)
-
-Compares files **semantically** by their data structure and displays differences
-as a visual tree showing what changed in the structure.
-
-Best for::
-* Configuration files where you care about what values changed
-* API responses where structure matters
-* Comparing semantic equivalence across formats
-
-Features::
-* Tree visualization with box-drawing characters
-* Shows only what changed (additions, removals, modifications)
-* Ignores formatting differences automatically
-* Color-coded output (red=removed, green=added, yellow=changed)
-
-===== by-line mode (default for HTML, optional for XML)
-
-Compares files **line-by-line** after canonicalization, showing traditional
-diff-style output.
-
-Best for::
-* HTML markup where line-level changes matter
-* Reviewing exact textual differences
-* When you need to see the full document context
-
-Features::
-* Traditional diff format with line numbers
-* Shows before/after for each change
-* Better for understanding markup structure changes
-
-[NOTE]
-* JSON and YAML always use **by-object** mode
-* HTML always uses **by-line** mode
-* XML uses **by-object** mode by default, but can use **by-line** with `--by-line`
-
-==== Options
-
-===== Format options
-
-`-f, --format FORMAT`:: Format for both files: `xml`, `html`, `json`, or `yaml`
-(auto-detected from extension if not specified)
-
-`--format1 FORMAT`:: Format for first file (when comparing different formats)
-
-`--format2 FORMAT`:: Format for second file (when comparing different formats)
-
-===== Comparison options
-
-`-v, --verbose`:: Show detailed differences in tree format (default: just show
-if files differ)
-
-`--by-line`:: Use line-by-line diff for XML (default: by-object mode)
-
-`--ignore-attr-order` / `--no-ignore-attr-order`:: Control whether attribute/key
-ordering matters (default: ignore order)
-
-`--ignore-comments`:: Ignore XML/HTML comments during comparison (overrides
-`--with-comments`)
-
-`--ignore-text-nodes`:: Ignore all text node content, only compare structure
-
-`-c, --with-comments`:: Include comments in comparison (sets `ignore_comments: false`)
-
-===== Output options
-
-`--color` / `--no-color`:: Enable/disable colored output (default: enabled)
-
-==== Examples
-
-===== Basic comparison
-
-[source,bash]
-----
-# Compare two JSON files (shows if equivalent or different)
-$ canon diff config1.json config2.json
-Files are semantically different
-
-# Compare two XML files
-$ canon diff file1.xml file2.xml
-✅ Files are semantically equivalent
-----
-
-===== Verbose mode examples
-
-====== JSON comparison (by-object mode)
-
-[example]
-Given these two JSON files:
-
-.config1.json
-[source,json]
-----
-{
-  "name": "myapp",
-  "version": "1.0.0",
-  "settings": {
-    "debug": true,
-    "port": 8080
-  }
-}
-----
-
-.config2.json
-[source,json]
-----
-{
-  "version": "2.0.0",
-  "name": "myapp",
-  "settings": {
-    "debug": false,
-    "port": 8080
-  }
-}
-----
-
-Running with `--verbose`:
-
-[source,bash]
-----
-$ canon diff config1.json config2.json --verbose
-Visual Diff:
-├── settings.debug:
-│   ├── - true
-│   └── + false
-└── version:
-    ├── - "1.0.0"
-    └── + "2.0.0"
-----
-
-The tree shows:
-
-* Key order difference (`version` moved) is ignored
-* Only semantic changes are shown: `debug` and `version` values changed
-
-====== XML comparison (by-object mode with DOM-guided semantic matching)
-
-Canon's XML diff uses **hybrid DOM-guided line diff** that semantically matches
-elements across documents using identity attributes (such as `id`, `ref`, `name`,
-`key`) and element paths. This ensures that corresponding elements are compared
-even when they appear at different line positions in the files.
-
-[example]
-Given these two XML files:
-
-.document1.xml
-[source,xml]
-----
-<standard-document>
-  <preface>
-    <foreword id="fwd">
-      <p>First paragraph</p>
-    </foreword>
-  </preface>
-  <sections>
-    <clause id="scope">
-      <title>Scope</title>
-    </clause>
-  </sections>
-</standard-document>
-----
-
-.document2.xml
-[source,xml]
-----
-<standard-document>
-  <preface>
-    <foreword displayorder="2" id="fwd">
-      <p>First paragraph</p>
-    </foreword>
-  </preface>
-  <sections>
-    <clause id="scope">
-      <title>Scope</title>
-      <p>New content</p>
-    </clause>
-  </sections>
-</standard-document>
-----
-
-Running with `--verbose` using by-object mode (default):
-
-[source,bash]
-----
-$ canon diff document1.xml document2.xml --verbose
-Visual Diff:
-├── preface.foreword:
-│   └── + displayorder="2"
-└── sections.clause.p:
-    └── + "New content"
-----
-
-The DOM-guided diff shows:
-
-* The `<foreword id="fwd">` elements are **semantically matched** by their `id`
-attribute, even though they may be at different positions
-* Only the **added** `displayorder` attribute is shown for foreword
-* The **added** `<p>` element in clause is shown
-* Unchanged content is not displayed
-
-[example]
-Example with element matching when positions differ:
-
-.file1.xml
-[source,xml]
-----
-<root>
-  <item id="1" name="Widget" price="10.00"/>
-  <item id="2" name="Gadget" price="20.00"/>
-</root>
-----
-
-.file2.xml
-[source,xml]
-----
-<root>
-  <item price="20.00" name="Gadget" id="2"/>
-  <item id="1" name="Widget" price="15.00"/>
-</root>
-----
-
-Running with `--verbose`:
-
-[source,bash]
-----
-$ canon diff file1.xml file2.xml --verbose
-Visual Diff:
-└── root.item[id="1"].price:
-    ├── - "10.00"
-    └── + "15.00"
-----
-
-The semantic matching shows:
-
-* Elements are matched by `id` attribute (`id="1"` with `id="1"`, `id="2"` with `id="2"`)
-* Position changes are ignored (item with `id="2"` moved from second to first)
-* Attribute reordering is ignored (price/name order changed)
-* Only the semantic change is shown: `price` value changed for item `id="1"`
-
-[NOTE]
-DOM-guided semantic matching features:
-
-* **Identity attributes**: Matches elements using `id`, `ref`, `name`, or `key` attributes
-* **Element paths**: Uses full element path for matching (e.g., `root.item`)
-* **Token-level highlighting**: Shows differences at semantic token level (element
-names, attribute names, attribute values)
-* **Parent filtering**: Skips parent elements that only differ in children to
-avoid redundant output
-* **Line range mapping**: Maps DOM elements to exact line ranges in pretty-printed
-output for accurate diff display
-
-====== XML comparison (by-line mode)
-
-The `--by-line` option switches to traditional line-by-line diff after
-canonicalization, useful when you need to see exact line-level changes.
-
-[example]
-Using the previous example files, but with `--by-line`:
-
-[source,bash]
-----
-$ canon diff document1.xml document2.xml --by-line --verbose
-Line-by-line diff:
-   4 - |     <foreword id="fwd">
-   4 + |     <foreword displayorder="2" id="fwd">
-   5   |       <p>First paragraph</p>
-  10 + |       <p>New content</p>
-  11   |     </clause>
-----
-
-The by-line mode shows:
-
-* Traditional diff format with line numbers
-* Full line context after canonicalization
-* All changes at line level (not semantic level)
-* Useful for reviewing exact textual differences
-
-====== YAML comparison (by-object mode)
-
-YAML comparison uses by-object mode to show semantic differences in the data
-structure, ignoring formatting and key ordering differences.
-
-[example]
-Given these two YAML files:
-
-.config1.yaml
-[source,yaml]
-----
-database:
-  host: localhost
-  port: 5432
-  name: mydb
-logging:
-  level: info
-  format: json
-----
-
-.config2.yaml
-[source,yaml]
-----
-logging:
-  level: debug
-  format: json
-database:
-  port: 5432
-  host: localhost
-  name: production
-----
-
-Running with `--verbose`:
-
-[source,bash]
-----
-$ canon diff config1.yaml config2.yaml --verbose
-Visual Diff:
-├── database.name:
-│   ├── - "mydb"
-│   └── + "production"
-└── logging.level:
-    ├── - "info"
-    └── + "debug"
-----
-
-The by-object mode shows:
-
-* Section reordering (`logging` before `database`) is ignored
-* Key reordering within sections (`port` before `host`) is ignored
-* Only semantic value changes are displayed
-* Tree structure clearly shows the path to each change
-
-===== Comparison options examples
-
-[source,bash]
-----
-# Include comments in XML comparison
-$ canon diff doc1.xml doc2.xml --with-comments --verbose
-
-# Ignore all text content, only compare structure
-$ canon diff template1.html template2.html --ignore-text-nodes
-
-# Don't collapse whitespace (exact whitespace comparison)
-$ canon diff file1.xml file2.xml --no-collapse-whitespace
-
-# Compare different formats (must have same structure)
-$ canon diff config.json config.yaml --format1 json --format2 yaml --verbose
-----
-
-===== HTML comparison (by-line mode only)
-
-HTML comparison always uses by-line mode after canonicalization, which is ideal
-for reviewing markup structure changes.
-
-[example]
-Given these two HTML files:
-
-.page1.html
-[source,html]
-----
-<!DOCTYPE html>
-<html>
-  <head>
-    <title>My Page</title>
-  </head>
-  <body>
-    <div class="header">
-      <h1>Welcome</h1>
-      <p>Introduction text</p>
-    </div>
-    <div class="content">
-      <p>Main content</p>
-    </div>
-  </body>
-</html>
-----
-
-.page2.html
-[source,html]
-----
-<!DOCTYPE html>
-<html>
-  <head>
-    <title>My Updated Page</title>
-  </head>
-  <body>
-    <nav class="header">
-      <h1>Welcome</h1>
-      <p>Updated introduction</p>
-    </nav>
-    <div class="content">
-      <p>Main content</p>
-      <p>Additional paragraph</p>
-    </div>
-  </body>
-</html>
-----
-
-Running with `--verbose`:
-
-[source,bash]
-----
-$ canon diff page1.html page2.html --verbose
-Line-by-line diff:
-   4 - |     <title>My Page</title>
-   4 + |     <title>My Updated Page</title>
-   7 - |     <div class="header">
-   7 + |     <nav class="header">
-   9 - |       <p>Introduction text</p>
-   9 + |       <p>Updated introduction</p>
-  10 - |     </div>
-  10 + |     </nav>
-  13 + |       <p>Additional paragraph</p>
-  14   |     </div>
-----
-
-The line-by-line mode shows:
-
-* Element name changes (`<div>` to `<nav>`)
-* Text content changes
-* Added elements with proper indentation context
-* Line numbers help locate changes in the document
-
-===== Exit codes
-
-* `0` - Files are semantically equivalent
-* `1` - Files are semantically different
-
-=== Ruby API usage
-
-=== Basic formatting (c14n mode)
-
-The `Canon.format` method produces canonical output by default.
-
-Syntax:
-
-[source,ruby]
-----
-Canon.format({content}, {format})
-Canon.format_{format}({content})  # Format-specific shorthand
-----
-
-Where,
-
-`{content}`:: The input string
-`{format}`:: The format type (`:xml`, `:html`, `:json`, or `:yaml`)
-
-.Canonical formatting examples
-[example]
-====
-[source,ruby]
-----
-require 'canon'
-
-# XML - compact canonical form
-xml = '<root><b>2</b><a>1</a></root>'
-Canon.format(xml, :xml)
-# => "<root><a>1</a><b>2</b></root>"
-
-Canon.format_xml(xml)  # Shorthand
-# => "<root><a>1</a><b>2</b></root>"
-
-# HTML - compact canonical form
-html = '<div><p>Hello</p></div>'
-Canon.format(html, :html)
-Canon.format_html(html)  # Shorthand
-
-# JSON - canonical with sorted keys
-json = '{"z":3,"a":1,"b":2}'
-Canon.format(json, :json)
-# => {"a":1,"b":2,"z":3}
-
-# YAML - canonical with sorted keys
-yaml = "z: 3\na: 1\nb: 2"
-Canon.format(yaml, :yaml)
-----
-====
-
-=== Pretty-print mode
-
-For human-readable output with indentation, use the format-specific pretty
-printer classes.
-
-Syntax:
-
-[source,ruby]
-----
-Canon::{Format}::PrettyPrinter.new(indent: {n}, indent_type: {type}).format({content})
-----
-
-Where,
-
-`{Format}`:: The format module (`Xml`, `Html`, `Json`)
-`{n}`:: Number of spaces (default: 2) or tabs (use 1 for tabs)
-`{type}`:: Indentation type: `'space'` (default) or `'tab'`
-`{content}`:: The input string
-
-.Pretty-print examples
-[example]
-====
-[source,ruby]
-----
-require 'canon/xml/pretty_printer'
-require 'canon/html/pretty_printer'
-require 'canon/json/pretty_printer'
-
-xml_input = '<root><b>2</b><a>1</a></root>'
-
-# XML with 2-space indentation (default)
-Canon::Xml::PrettyPrinter.new(indent: 2).format(xml_input)
-# =>
-# <?xml version="1.0" encoding="UTF-8"?>
-# <root>
-#   <a>1</a>
-#   <b>2</b>
-# </root>
-
-# XML with 4-space indentation
-Canon::Xml::PrettyPrinter.new(indent: 4).format(xml_input)
-
-# XML with tab indentation
-Canon::Xml::PrettyPrinter.new(
-  indent: 1,
-  indent_type: 'tab'
-).format(xml_input)
-
-# HTML with 2-space indentation
-html_input = '<div><p>Hello</p></div>'
-Canon::Html::PrettyPrinter.new(indent: 2).format(html_input)
-
-# JSON with 2-space indentation
-json_input = '{"z":3,"a":{"b":1}}'
-Canon::Json::PrettyPrinter.new(indent: 2).format(json_input)
-
-# JSON with tab indentation
-Canon::Json::PrettyPrinter.new(
-  indent: 1,
-  indent_type: 'tab'
-).format(json_input)
-----
-====
-
-=== Parsing
-
-The `Canon.parse` method parses content into Ruby objects or Nokogiri documents.
-
-Syntax:
-
-[source,ruby]
-----
-Canon.parse({content}, {format})
-Canon.parse_{format}({content})  # Format-specific shorthand
-----
-
-Where,
-
-`{content}`:: The input string
-`{format}`:: The format type (`:xml`, `:html`, `:json`, or `:yaml`)
-
-.Parsing examples
-[example]
-====
-[source,ruby]
-----
-# Parse XML → Nokogiri::XML::Document
-xml_doc = Canon.parse(xml_input, :xml)
-xml_doc = Canon.parse_xml(xml_input)
-
-# Parse HTML → Nokogiri::HTML5::Document (or XML::Document for XHTML)
-html_doc = Canon.parse(html_input, :html)
-html_doc = Canon.parse_html(html_input)
-
-# Parse JSON → Ruby Hash/Array
-json_obj = Canon.parse(json_input, :json)
-json_obj = Canon.parse_json(json_input)
-
-# Parse YAML → Ruby Hash/Array
-yaml_obj = Canon.parse(yaml_input, :yaml)
-yaml_obj = Canon.parse_yaml(yaml_input)
-----
-====
-
-=== Comparison
-
-The `Canon::Comparison.equivalent?` method compares two HTML or XML documents.
-
-The Comparison module uses a depth-first comparison based on the two DOM trees
-by traversing them in parallel and comparing nodes.
-
-In XML mode:
-
-* Parsing: accepts Moxml (`Moxml::Document`) or Nokogiri
-(`Nokogiri::XML::Document`)
-* Comments: normalized and compared unless `ignore_comments: true`
-* Whitespace: collapses whitespace in text nodes unless `collapse_whitespace: false`
-* Sorts attributes alphabetically before comparison
-
-In HTML mode:
-
-* Parsing: accepts Nokogiri (`Nokogiri::HTML5` or `Nokogiri::HTML`)
-* Normalizes HTML comments in `<style>` and `<script>` tags
-* Sorts attributes alphabetically before comparison
-* Collapses whitespace for text content comparison
-* Removes empty text nodes between elements
-
-[NOTE]
-====
-The comparison module is automatically used by Canon's RSpec matchers
-(`be_html_equivalent_to`, `be_xml_equivalent_to`, etc.) to provide reliable
-semantic comparison in tests.
-====
-
-
-Syntax:
-
-[source,ruby]
-----
-Canon::Comparison.equivalent?({doc1}, {doc2}, {options})
-----
-
-Where,
-
-`{doc1}`:: First document object (String, Nokogiri::HTML::Document, or supported XML document)
-`{doc2}`:: Second document object (String, Nokogiri::HTML::Document, or supported XML document)
-`{options}`:: Hash of comparison options (optional)
-
-Canon::Comparison for XML supports Moxml::Document and Nokogiri::XML::Document
-as input.
-
-Returns:
-
-* `true` if documents are equivalent
-* `false` if documents differ
-* `Array` of differences if `verbose: true` option is set
-
-.Basic comparison examples
-[example]
-====
-[source,ruby]
-----
-require 'canon/comparison'
-
-# HTML comparison - ignores whitespace and comments by default
-html1 = '<div><p>Hello</p></div>'
-html2 = '<div> <p> Hello </p> </div>'
-Canon::Comparison.equivalent?(html1, html2)
-# => true
-
-# HTML with different content
-html3 = '<div><p>Goodbye</p></div>'
-Canon::Comparison.equivalent?(html1, html3)
-# => false
-
-# XML comparison
-xml1 = '<root><a>1</a><b>2</b></root>'
-xml2 = '<root>  <b>2</b>  <a>1</a>  </root>'
-Canon::Comparison.equivalent?(xml1, xml2)
-# => true
-
-# With Nokogiri documents
-doc1 = Nokogiri::HTML5(html1)
-doc2 = Nokogiri::HTML5(html2)
-Canon::Comparison.equivalent?(doc1, doc2)
-# => true
-----
-====
-
-=== RSpec usage
-
-=== General
-
-RSpec matchers for testing equivalence between serialized formats. All matchers
-use canonical (c14n) mode for comparison.
-
-See <<Diff formatting configuration>> for details on configuring diff output
-in RSpec matchers.
-
-.RSpec matcher examples
-[example]
-====
-[source,ruby]
-----
-require 'rspec'
-require 'canon'
-
-RSpec.describe 'Serialization equivalence' do
-  # Unified matcher with format parameter
-  it 'compares XML' do
-    xml1 = '<root><a>1</a><b>2</b></root>'
-    xml2 = '<root>  <b>2</b>  <a>1</a>  </root>'
-    expect(xml1).to be_serialization_equivalent_to(xml2, format: :xml)
-  end
-
-  it 'compares HTML' do
-    html1 = '<div><p>Hello</p></div>'
-    html2 = '<div> <p> Hello </p> </div>'
-    expect(html1).to be_serialization_equivalent_to(html2, format: :html)
-  end
-
-  it 'compares JSON' do
-    json1 = '{"a":1,"b":2}'
-    json2 = '{"b":2,"a":1}'
-    expect(json1).to be_serialization_equivalent_to(json2, format: :json)
-  end
-
-  it 'compares YAML' do
-    yaml1 = "a: 1\nb: 2"
-    yaml2 = "b: 2\na: 1"
-    expect(yaml1).to be_serialization_equivalent_to(yaml2, format: :yaml)
-  end
-
-  # Format-specific matchers
-  it 'uses format-specific matchers' do
-    expect(xml1).to be_xml_equivalent_to(xml2)    # XML
-    expect(xml1).to be_analogous_with(xml2)       # XML (legacy)
-    expect(html1).to be_html_equivalent_to(html2) # HTML
-    expect(json1).to be_json_equivalent_to(json2) # JSON
-    expect(yaml1).to be_yaml_equivalent_to(yaml2) # YAML
-  end
-end
-----
-====
-
-[IMPORTANT]
-====
-RSpec matchers always canonicalize both sides before comparing, so:
-
-* Formatting differences (whitespace, indentation) are ignored
-* Attribute order in XML/HTML is normalized
-* Key order in JSON/YAML is normalized
-* Tests focus on content equality, not formatting
-====
-
-
-=== Usage examples
-
-==== Using predefined profiles
-
-Use a profile for XML comparison:
-
-[source,ruby]
-----
-expect(actual_xml).to be_xml_equivalent_to(
-  expected_xml,
-  match_profile: :spec_friendly
-)
-----
-
-Use a profile for HTML comparison:
-
-[source,ruby]
-----
-expect(actual_html).to be_html_equivalent_to(
-  expected_html,
-  match_profile: :content_only
-)
-----
-
-==== Using explicit match options
-
-Override specific dimensions:
-
-[source,ruby]
-----
-expect(actual_xml).to be_xml_equivalent_to(
-  expected_xml,
-  match_options: {
-    text_content: :normalize,
-    structural_whitespace: :ignore,
-    attribute_whitespace: :strict,
-    comments: :ignore
-  }
-)
-----
-
-==== Combining profiles and explicit options
-
-Explicit options override profile settings:
-
-[source,ruby]
-----
-expect(actual_xml).to be_xml_equivalent_to(
-  expected_xml,
-  match_profile: :spec_friendly,
-  match_options: {
-    attribute_whitespace: :strict  # Override just this dimension
-  }
-)
-----
-
-==== Global configuration
-
-Set a global default profile for all tests:
-
-[source,ruby]
-----
-# In spec_helper.rb
-Canon::RSpecMatchers.configure do |config|
-  config.xml_match_profile = :spec_friendly
-  config.html_match_profile = :rendered
-end
-----
-
-Override global profile in specific tests:
-
-[source,ruby]
-----
-# This test uses strict matching despite global spec_friendly
-expect(actual_xml).to be_xml_equivalent_to(
-  expected_xml,
-  match_profile: :strict
-)
-----
-
-== Configuration
-
-=== Comparison options
-
-=== Overview
-
-Canon provides a flexible matching system for XML, HTML, JSON, and YAML
-comparisons.
-
-This system allows precise control over how whitespace and formatting
-differences are handled during comparison.
-
-These options apply to the `Canon::Comparison.equivalent?` method, Canon's
-RSpec matchers as well as for the command-line `canon diff` tool to perform
-semantic comparison.
-
-The system uses a two-phase architecture:
-
-* *Preprocessing phase*: What to compare (normalization, canonicalization, formatting)
-* *Matching phase*: How to compare (4 dimensions × 3 behaviors)
-
-The system uses `match_options` and `match_profile` parameters that offer
-precise control over comparison behavior.
-
-`ignore_attr_order`:: (default: `true`) when `true`, ignores attribute ordering
-(<<ignore_attr_order>>)
-
-`verbose`:: (default: `false`) when `true`, returns array of differences instead
-of boolean (<<verbose>>)
-
-
-=== Preprocessing phase
-
-The preprocessing phase determines what content is compared.
-
-Canon supports four preprocessing options:
-
-[cols="1,3"]
-|===
-| Option | Description
-
-| `:none`
-| No preprocessing - compare raw content as-is
-
-| `:c14n`
-| Apply XML Canonicalization (C14N) to normalize structure before comparison
-
-| `:normalize`
-| Apply whitespace normalization (collapsing, trimming) before comparison
-
-| `:format`
-| Apply format-specific pretty-printing to standardize formatting before comparison
-
-|===
-
-The preprocessing option is controlled via the `preprocessing` parameter and
-defaults based on the format being compared.
-
-=== Matching phase
-
-The matching phase defines how content is compared across four independent
-dimensions. Each dimension can be configured with one of three mutually
-exclusive behaviors.
-
-=== Match dimensions
-
-The matching phase operates on four collectively exhaustive dimensions:
-
-[cols="1,3"]
-|===
-| Dimension | What it controls
-
-| `text_content`
-| Text content within elements/values
-
-| `structural_whitespace`
-| Whitespace between tags/elements (indentation, line breaks)
-
-| `attribute_whitespace`
-| Whitespace within attribute values
-
-| `comments`
-| How comments are handled
-|===
-
-These four dimensions are collectively exhaustive - they cover all aspects of
-whitespace and formatting in structured documents.
-
-=== Match behaviors
-
-For each dimension, you can specify one of three mutually exclusive behaviors:
-
-[cols="1,3"]
-|===
-| Behavior | Description
-
-| `:strict`
-| Exact character-for-character matching (including all whitespace)
-
-| `:normalize`
-| Collapse consecutive whitespace to single spaces, trim leading/trailing whitespace
-
-| `:ignore`
-| Don't compare this dimension at all
-|===
-
-=== Match profiles
-
-==== Overview
-
-Canon provides a set of predefined match profiles optimized for common use cases.
-
-The following table shows how each profile configures the four match dimensions:
-
-[cols="1,1,1,1,1"]
-|===
-|Profile |text_content |structural_whitespace |attribute_whitespace |comments
-
-|`strict` |`:strict` |`:strict` |`:strict` |`:strict`
-
-|`rendered` |`:normalize` |`:ignore` |`:normalize` |`:ignore`
-
-|`spec_friendly` |`:normalize` |`:ignore` |`:normalize` |`:ignore`
-
-|`content_only` |`:normalize` |`:ignore` |`:ignore` |`:ignore`
-
-|===
-
-The key differences between profiles are:
-
-strict:: Exact matching on all dimensions - use for byte-for-byte comparison
-rendered:: Mimics browser rendering - collapses text, ignores formatting and comments
-spec_friendly:: Same as rendered - ideal for test specifications
-content_only:: Most permissive - only compares text content, ignores all formatting and attribute whitespace
-
-NOTE: The `rendered` and `spec_friendly` profiles have identical configurations
-but serve different semantic purposes in your codebase.
-
-==== Strict profile
-
-The `strict` profile is the default for XML and requires exact matching:
-
-[source,ruby]
-----
-{
-  text_content: :strict,
-  structural_whitespace: :strict,
-  attribute_whitespace: :strict,
-  comments: :strict
-}
-----
-
-Use this when:
-
-* You need exact byte-for-byte comparison
-* Whitespace is semantically significant
-* Working with canonicalized or pre-normalized content
-
-==== Rendered profile
-
-The `rendered` profile mimics how browsers render HTML/XML:
-
-[source,ruby]
-----
-{
-  text_content: :normalize,
-  structural_whitespace: :ignore,
-  attribute_whitespace: :normalize,
-  comments: :ignore
-}
-----
-
-Use this when:
-
-* Comparing HTML documents where rendering matters
-* Whitespace between tags doesn't affect output
-* Comments are documentation-only
-
-This is the default profile for HTML comparisons.
-
-==== Spec-friendly profile
-
-The `spec_friendly` profile ignores all formatting differences:
-
-[source,ruby]
-----
-{
-  text_content: :normalize,
-  structural_whitespace: :ignore,
-  attribute_whitespace: :normalize,
-  comments: :ignore
-}
-----
-
-Use this when:
-
-* Writing test specifications
-* Formatting/indentation style doesn't matter
-* Generated vs. hand-written content comparison
-* CI/CD environments with different formatters
-
-==== Content-only profile
-
-The `content_only` profile focuses solely on actual content:
-
-[source,ruby]
-----
-{
-  text_content: :normalize,
-  structural_whitespace: :ignore,
-  attribute_whitespace: :ignore,
-  comments: :ignore
-}
-----
-
-Use this when:
-
-* Only semantic content matters
-* All whitespace (including in attributes) is insignificant
-* Maximum tolerance for formatting differences
-
-
-=== Format-specific defaults
-
-==== General
-
-Different formats have different default behaviors optimized for their typical
-use cases.
-
-==== XML defaults
-
-[source,ruby]
-----
-{
-  preprocessing: :none,
-  match_profile: :strict
-}
-----
-
-XML defaults to strict matching because:
-
-* XML whitespace can be semantically significant
-* XML is often machine-generated with consistent formatting
-* Canonicalization (C14N) is available for normalization when needed
-
-==== HTML defaults
-
-[source,ruby]
-----
-{
-  preprocessing: :none,
-  match_profile: :rendered
-}
-----
-
-HTML defaults to rendered-style matching because:
-
-* Browsers collapse whitespace when rendering
-* Indentation and formatting are for readability only
-* Comments are typically documentation
-
-==== JSON defaults
-
-[source,ruby]
-----
-{
-  preprocessing: :format,
-  match_profile: :rendered
-}
-----
-
-JSON applies pretty-printing before comparison because:
-
-* JSON whitespace is never semantically significant
-* Minified vs. formatted JSON should be equivalent
-* Pretty-printing ensures consistent structure
-
-==== YAML defaults
-
-[source,ruby]
-----
-{
-  preprocessing: :format,
-  match_profile: :rendered
-}
-----
-
-YAML applies pretty-printing because:
-
-* YAML formatting can vary significantly
-* Indentation styles differ between generators
-* Content equivalence is what matters
-
-
-
-==== Dimension-specific examples
-
-=== Text content dimension
-
-The `text_content` dimension controls how text within elements is compared.
-
-==== Strict behavior (exact whitespace)
-
-When `text_content: :strict`, all whitespace in text content must match exactly.
-
-.XML examples with strict text_content
-[example]
-The following XML strings are **not** considered equal because whitespace differs:
-
-[source,xml]
-----
-<p>  text with  spaces  </p>
-<p>text with spaces</p>
-----
-
-[source,ruby]
-----
-actual = "<p>  text with  spaces  </p>"
-expected = "<p>text with spaces</p>"
-
-expect(actual).not_to be_xml_equivalent_to(
-  expected,
-  match_options: {
-    text_content: :strict,
-    structural_whitespace: :ignore,
-    attribute_whitespace: :strict,
-    comments: :ignore
-  }
-)
-# => true (documents are NOT equivalent)
-----
-
-Even differences in leading/trailing whitespace matter:
-
-[source,xml]
-----
-<item>   Value   </item>
-<item>Value</item>
-----
-
-[source,ruby]
-----
-xml1 = "<item>   Value   </item>"
-xml2 = "<item>Value</item>"
-
-expect(xml1).not_to be_xml_equivalent_to(
-  xml2,
-  match_options: { text_content: :strict, structural_whitespace: :ignore }
-)
-# => true (documents are NOT equivalent)
-----
-
-.HTML examples with strict text_content
-[example]
-[source,html]
-----
-<a href="/admin">   SOME TEXT   </a>
-<a href="/admin">SOME TEXT</a>
-----
-
-[source,ruby]
-----
-html1 = '<a href="/admin">   SOME TEXT   </a>'
-html2 = '<a href="/admin">SOME TEXT</a>'
-
-expect(html1).not_to be_html_equivalent_to(
-  html2,
-  match_options: { text_content: :strict, structural_whitespace: :ignore }
-)
-# => true (documents are NOT equivalent)
-----
-
-==== Normalize behavior (collapse whitespace)
-
-When `text_content: :normalize`, consecutive whitespace is collapsed to single spaces and leading/trailing whitespace is trimmed.
-
-.XML examples with normalized text_content
-[example]
-The following XML strings **are** considered equal:
-
-[source,xml]
-----
-<p>  text with  multiple   spaces  </p>
-<p>text with multiple spaces</p>
-----
-
-[source,ruby]
-----
-actual = "<p>  text with  multiple   spaces  </p>"
-expected = "<p>text with multiple spaces</p>"
-
-expect(actual).to be_xml_equivalent_to(
-  expected,
-  match_options: {
-    text_content: :normalize,
-    structural_whitespace: :ignore,
-    attribute_whitespace: :strict,
-    comments: :ignore
-  }
-)
-# => true (documents are equivalent)
-----
-
-Tabs and newlines are also normalized:
-
-[source,xml]
-----
-<description>
-  This is a
-  multi-line
-  description
-</description>
-
-<description>This is a multi-line description</description>
-----
-
-[source,ruby]
-----
-xml1 = <<~XML
-  <description>
-    This is a
-    multi-line
-    description
-  </description>
-XML
-
-xml2 = "<description>This is a multi-line description</description>"
-
-expect(xml1).to be_xml_equivalent_to(
-  xml2,
-  match_options: { text_content: :normalize, structural_whitespace: :ignore }
-)
-# => true (documents are equivalent)
-----
-
-.HTML examples with normalized text_content
-[example]
-[source,html]
-----
-<a href="/admin">   SOME   TEXT   CONTENT   </a>
-<a href="/admin">SOME TEXT CONTENT</a>
-----
-
-[source,ruby]
-----
-html1 = '<a href="/admin">   SOME   TEXT   CONTENT   </a>'
-html2 = '<a href="/admin">SOME TEXT CONTENT</a>'
-
-expect(html1).to be_html_equivalent_to(
-  html2,
-  match_options: { text_content: :normalize, structural_whitespace: :ignore }
-)
-# => true (documents are equivalent)
-----
-
-Multi-line HTML text:
-
-[source,html]
-----
-<p>
-  This is a paragraph
-  with multiple lines
-  of text.
-</p>
-
-<p>This is a paragraph with multiple lines of text.</p>
-----
-
-[source,ruby]
-----
-html1 = <<~HTML
-  <p>
-    This is a paragraph
-    with multiple lines
-    of text.
-  </p>
-HTML
-
-html2 = "<p>This is a paragraph with multiple lines of text.</p>"
-
-expect(html1).to be_html_equivalent_to(
-  html2,
-  match_options: { text_content: :normalize, structural_whitespace: :ignore }
-)
-# => true (documents are equivalent)
-----
-
-=== Structural whitespace dimension
-
-The `structural_whitespace` dimension controls whitespace between tags (indentation, line breaks, formatting).
-
-==== Strict behavior
-
-When `structural_whitespace: :strict`, all whitespace between tags must match exactly, including indentation and line breaks.
-
-.XML examples with strict structural_whitespace
-[example]
-These documents are **not** equivalent due to different indentation:
-
-[source,xml]
-----
-<root>
-  <item>Value</item>
-</root>
-
-<root>
-    <item>Value</item>
-</root>
-----
-
-[source,ruby]
-----
-xml1 = "<root>\n  <item>Value</item>\n</root>"
-xml2 = "<root>\n    <item>Value</item>\n</root>"
-
-expect(xml1).not_to be_xml_equivalent_to(
-  xml2,
-  match_options: {
-    text_content: :normalize,
-    structural_whitespace: :strict,
-    attribute_whitespace: :strict,
-    comments: :ignore
-  }
-)
-# => true (documents are NOT equivalent - indentation differs)
-----
-
-==== Ignore behavior (formatting doesn't matter)
-
-When `structural_whitespace: :ignore`, all whitespace between tags is ignored, making pretty-printed and compact formats equivalent.
-
-.XML examples with ignored structural_whitespace
-[example]
-Pretty-printed vs compact XML **are** considered equal:
-
-[source,xml]
-----
-<!-- Pretty-printed with indentation -->
-<root>
-  <a>
-    <b>text</b>
-  </a>
-</root>
-
-<!-- Compact on one line -->
-<root><a><b>text</b></a></root>
-----
-
-[source,ruby]
-----
-compact = "<root><a><b>text</b></a></root>"
-formatted = <<~XML
-  <root>
-    <a>
-      <b>text</b>
-    </a>
-  </root>
-XML
-
-expect(compact).to be_xml_equivalent_to(
-  formatted,
-  match_options: {
-    text_content: :normalize,
-    structural_whitespace: :ignore,
-    attribute_whitespace: :strict,
-    comments: :ignore
-  }
-)
-# => true (documents are equivalent)
-----
-
-Complex nested structures with different indentation:
-
-[source,xml]
-----
-<!-- 2-space indentation -->
-<document>
-  <metadata>
-    <title>My Document</title>
-    <author>
-      <name>John Doe</name>
-    </author>
-  </metadata>
-</document>
-
-<!-- 4-space indentation -->
-<document>
-    <metadata>
-        <title>My Document</title>
-        <author>
-            <name>John Doe</name>
-        </author>
-    </metadata>
-</document>
-
-<!-- Compact -->
-<document><metadata><title>My Document</title><author><name>John Doe</name></author></metadata></document>
-----
-
-[source,ruby]
-----
-two_spaces = <<~XML
-  <document>
-    <metadata>
-      <title>My Document</title>
-      <author>
-        <name>John Doe</name>
-      </author>
-    </metadata>
-  </document>
-XML
-
-four_spaces = "<document>\n    <metadata>\n        <title>My Document</title>\n        <author>\n            <name>John Doe</name>\n        </author>\n    </metadata>\n</document>"
-
-compact = "<document><metadata><title>My Document</title><author><name>John Doe</name></author></metadata></document>"
-
-expect(two_spaces).to be_xml_equivalent_to(
-  four_spaces,
-  match_options: { structural_whitespace: :ignore }
-)
-# => true
-
-expect(two_spaces).to be_xml_equivalent_to(
-  compact,
-  match_options: { structural_whitespace: :ignore }
-)
-# => true
-----
-
-.HTML examples with ignored structural_whitespace
-[example]
-[source,html]
-----
-<!-- Pretty-printed -->
-<div class="container">
-  <header>
-    <h1>Welcome</h1>
-    <p>Introduction text</p>
-  </header>
-</div>
-
-<!-- Compact -->
-<div class="container"><header><h1>Welcome</h1><p>Introduction text</p></header></div>
-----
-
-[source,ruby]
-----
-pretty_html = <<~HTML
-  <div class="container">
-    <header>
-      <h1>Welcome</h1>
-      <p>Introduction text</p>
-    </header>
-  </div>
-HTML
-
-compact_html = '<div class="container"><header><h1>Welcome</h1><p>Introduction text</p></header></div>'
-
-expect(pretty_html).to be_html_equivalent_to(
-  compact_html,
-  match_options: { structural_whitespace: :ignore }
-)
-# => true (documents are equivalent)
-----
-
-==== Normalize behavior
-
-When `structural_whitespace: :normalize`, whitespace between tags is collapsed to single spaces.
-
-.XML examples with normalized structural_whitespace
-[example]
-[source,xml]
-----
-<root>
-
-
-  <item>Value</item>
-
-
-</root>
-
-<root> <item>Value</item> </root>
-----
-
-[source,ruby]
-----
-xml1 = "<root>\n\n\n  <item>Value</item>\n\n\n</root>"
-xml2 = "<root> <item>Value</item> </root>"
-
-expect(xml1).to be_xml_equivalent_to(
-  xml2,
-  match_options: { structural_whitespace: :normalize }
-)
-# => true (documents are equivalent - whitespace normalized)
-----
-
-=== Attribute whitespace dimension
-
-The `attribute_whitespace` dimension controls whitespace within attribute values.
-
-==== Strict behavior (exact attribute whitespace)
-
-When `attribute_whitespace: :strict`, whitespace in attribute values must match exactly.
-
-.XML examples with strict attribute_whitespace
-[example]
-These documents are **not** equivalent due to attribute whitespace differences:
-
-[source,xml]
-----
-<div class=" foo  bar ">text</div>
-<div class="foo bar">text</div>
-----
-
-[source,ruby]
-----
-actual = '<div class=" foo  bar ">text</div>'
-expected = '<div class="foo bar">text</div>'
-
-expect(actual).not_to be_xml_equivalent_to(
-  expected,
-  match_options: {
-    text_content: :normalize,
-    structural_whitespace: :ignore,
-    attribute_whitespace: :strict,
-    comments: :ignore
-  }
-)
-# => true (documents are NOT equivalent)
-----
-
-Leading/trailing whitespace in attributes:
-
-[source,xml]
-----
-<item id=" 123 " name="  Widget  "/>
-<item id="123" name="Widget"/>
-----
-
-[source,ruby]
-----
-xml1 = '<item id=" 123 " name="  Widget  "/>'
-xml2 = '<item id="123" name="Widget"/>'
-
-expect(xml1).not_to be_xml_equivalent_to(
-  xml2,
-  match_options: { attribute_whitespace: :strict }
-)
-# => true (documents are NOT equivalent)
-----
-
-.HTML examples with strict attribute_whitespace
-[example]
-[source,html]
-----
-<a href="/admin" class=" button  primary ">Link</a>
-<a href="/admin" class="button primary">Link</a>
-----
-
-[source,ruby]
-----
-html1 = '<a href="/admin" class=" button  primary ">Link</a>'
-html2 = '<a href="/admin" class="button primary">Link</a>'
-
-expect(html1).not_to be_html_equivalent_to(
-  html2,
-  match_options: { attribute_whitespace: :strict }
-)
-# => true (documents are NOT equivalent)
-----
-
-==== Normalize behavior (collapse attribute whitespace)
-
-When `attribute_whitespace: :normalize`, whitespace in attribute values is collapsed and trimmed.
-
-.XML examples with normalized attribute_whitespace
-[example]
-These documents **are** considered equal:
-
-[source,xml]
-----
-<div class=" foo  bar ">text</div>
-<div class="foo bar">text</div>
-----
-
-[source,ruby]
-----
-actual = '<div class=" foo  bar ">text</div>'
-expected = '<div class="foo bar">text</div>'
-
-expect(actual).to be_xml_equivalent_to(
-  expected,
-  match_options: {
-    text_content: :normalize,
-    structural_whitespace: :ignore,
-    attribute_whitespace: :normalize,
-    comments: :ignore
-  }
-)
-# => true (documents are equivalent)
-----
-
-Multiple attributes with whitespace:
-
-[source,xml]
-----
-<item id=" 123 " name="  Widget  " category="  tools  "/>
-<item id="123" name="Widget" category="tools"/>
-----
-
-[source,ruby]
-----
-xml1 = '<item id=" 123 " name="  Widget  " category="  tools  "/>'
-xml2 = '<item id="123" name="Widget" category="tools"/>'
-
-expect(xml1).to be_xml_equivalent_to(
-  xml2,
-  match_options: { attribute_whitespace: :normalize }
-)
-# => true (documents are equivalent)
-----
-
-.HTML examples with normalized attribute_whitespace
-[example]
-[source,html]
-----
-<a href="/admin" class=" button  primary " id="  main-link  ">Link</a>
-<a href="/admin" class="button primary" id="main-link">Link</a>
-----
-
-[source,ruby]
-----
-html1 = '<a href="/admin" class=" button  primary " id="  main-link  ">Link</a>'
-html2 = '<a href="/admin" class="button primary" id="main-link">Link</a>'
-
-expect(html1).to be_html_equivalent_to(
-  html2,
-  match_options: { attribute_whitespace: :normalize }
-)
-# => true (documents are equivalent)
-----
-
-==== Ignore behavior
-
-When `attribute_whitespace: :ignore`, attribute values are not compared at all (only attribute names are checked).
-
-.Example with ignored attribute_whitespace
-[example]
-[source,ruby]
-----
-xml1 = '<item class="foo">text</item>'
-xml2 = '<item class="completely different">text</item>'
-
-expect(xml1).to be_xml_equivalent_to(
-  xml2,
-  match_options: { attribute_whitespace: :ignore }
-)
-# => true (attribute values are not compared)
-----
-
-=== Comments dimension
-
-The `comments` dimension controls how XML/HTML comments are compared.
-
-==== Strict behavior
-
-When `comments: :strict`, comments must match exactly, including their content and position.
-
-.XML examples with strict comments
-[example]
-These documents are **not** equivalent due to different comments:
-
-[source,xml]
-----
-<root><!-- First comment --><a>text</a></root>
-<root><!-- Different comment --><a>text</a></root>
-----
-
-[source,ruby]
-----
-xml1 = "<root><!-- First comment --><a>text</a></root>"
-xml2 = "<root><!-- Different comment --><a>text</a></root>"
-
-expect(xml1).not_to be_xml_equivalent_to(
-  xml2,
-  match_options: { comments: :strict }
-)
-# => true (documents are NOT equivalent - comments differ)
-----
-
-==== Ignore behavior (comments don't affect comparison)
-
-When `comments: :ignore`, comments are completely ignored during comparison.
-
-.XML examples with ignored comments
-[example]
-These documents **are** considered equal despite different comments:
-
-[source,xml]
-----
-<root><!-- comment --><a>text</a></root>
-<root><!-- different --><a>text</a></root>
-<root><a>text</a></root>
-----
-
-[source,ruby]
-----
-with_comment = "<root><!-- comment --><a>text</a></root>"
-different_comment = "<root><!-- different --><a>text</a></root>"
-no_comment = "<root><a>text</a></root>"
-
-expect(with_comment).to be_xml_equivalent_to(
-  different_comment,
-  match_options: {
-    text_content: :normalize,
-    structural_whitespace: :ignore,
-    attribute_whitespace: :strict,
-    comments: :ignore
-  }
-)
-# => true (documents are equivalent - comments ignored)
-
-expect(with_comment).to be_xml_equivalent_to(
-  no_comment,
-  match_options: {
-    text_content: :normalize,
-    structural_whitespace: :ignore,
-    attribute_whitespace: :strict,
-    comments: :ignore
-  }
-)
-# => true (documents are equivalent - comments ignored)
-----
-
-Complex document with multiple comments:
-
-[source,xml]
-----
-<!-- Document header -->
-<document>
-  <!-- Metadata section -->
-  <metadata>
-    <title>My Document</title>
-    <!-- Author information -->
-    <author>John Doe</author>
-  </metadata>
-  <!-- Main content -->
-  <content>
-    <p>Text</p>
-  </content>
-</document>
-
-<document>
-  <metadata>
-    <title>My Document</title>
-    <author>John Doe</author>
-  </metadata>
-  <content>
-    <p>Text</p>
-  </content>
-</document>
-----
-
-[source,ruby]
-----
-with_comments = <<~XML
-  <!-- Document header -->
-  <document>
-    <!-- Metadata section -->
-    <metadata>
-      <title>My Document</title>
-      <!-- Author information -->
-      <author>John Doe</author>
-    </metadata>
-    <!-- Main content -->
-    <content>
-      <p>Text</p>
-    </content>
-  </document>
-XML
-
-without_comments = <<~XML
-  <document>
-    <metadata>
-      <title>My Document</title>
-      <author>John Doe</author>
-    </metadata>
-    <content>
-      <p>Text</p>
-    </content>
-  </document>
-XML
-
-expect(with_comments).to be_xml_equivalent_to(
-  without_comments,
-  match_options: { comments: :ignore }
-)
-# => true (documents are equivalent)
-----
-
-.HTML examples with ignored comments
-[example]
-[source,html]
-----
-<!-- Navigation -->
-<nav>
-  <!-- Primary menu -->
-  <ul>
-    <li>Home</li>
-  </ul>
-</nav>
-
-<nav>
-  <ul>
-    <li>Home</li>
-  </ul>
-</nav>
-----
-
-[source,ruby]
-----
-html_with_comments = <<~HTML
-  <!-- Navigation -->
-  <nav>
-    <!-- Primary menu -->
-    <ul>
-      <li>Home</li>
-    </ul>
-  </nav>
-HTML
-
-html_without_comments = <<~HTML
-  <nav>
-    <ul>
-      <li>Home</li>
-    </ul>
-  </nav>
-HTML
-
-expect(html_with_comments).to be_html_equivalent_to(
-  html_without_comments,
-  match_options: { comments: :ignore }
-)
-# => true (documents are equivalent)
-----
-
-==== Normalize behavior
-
-When `comments: :normalize`, comment content is trimmed and whitespace is collapsed before comparison.
-
-.Example with normalized comments
-[example]
-[source,ruby]
-----
-xml1 = "<root><!--   comment   with   spaces   --><a>text</a></root>"
-xml2 = "<root><!-- comment with spaces --><a>text</a></root>"
-
-expect(xml1).to be_xml_equivalent_to(
-  xml2,
-  match_options: { comments: :normalize }
-)
-# => true (comments are normalized before comparison)
-----
-
-==== Precedence resolution
-
-When multiple configuration sources are present, Canon resolves them in this order (highest to lowest precedence):
-
-. Explicit `match_options` hash in the test
-. Named `match_profile` in the test
-. Global format-specific profile (e.g., `xml_match_profile`)
-. Format-specific defaults (e.g., XML → strict, HTML → rendered)
-
-.Example of precedence resolution
-====
-[source,ruby]
-----
-# Global configuration
-Canon::RSpecMatchers.configure do |config|
-  config.xml_match_profile = :spec_friendly
-end
-
-# This uses strict for attribute_whitespace (explicit option)
-# and spec_friendly for other dimensions (global profile)
-expect(actual).to be_xml_equivalent_to(
-  expected,
-  match_options: {
-    attribute_whitespace: :strict
-  }
-)
-----
-====
-
-
-[[ignore_attr_order]]
-==== ignore_attr_order
-
-`ignore_attr_order: {true|false}` default: `true`
-
-When `true`, all attributes are sorted before comparison and only attributes of
-the same type are compared.
-
-Usage:
-
-[source,ruby]
-----
-Canon::Comparison.equivalent?(doc1, doc2, ignore_attr_order: true)
-----
-
-.HTML examples with ignore_attr_order
-[example]
-====
-When `true` the following HTML strings are considered equal:
-
-[source,html]
-----
-<a href="/admin" class="button" target="_blank">Link</a>
-<a class="button" target="_blank" href="/admin">Link</a>
-----
-
-[source,ruby]
-----
-html1 = '<a href="/admin" class="button" target="_blank">Link</a>'
-html2 = '<a class="button" target="_blank" href="/admin">Link</a>'
-Canon::Comparison.equivalent?(html1, html2, ignore_attr_order: true)
-# => true
-----
-
-When `false` attributes are compared in order:
-
-[source,ruby]
-----
-html1 = '<a href="/admin" class="button">Link</a>'
-html2 = '<a class="button" href="/admin">Link</a>'
-Canon::Comparison.equivalent?(html1, html2, ignore_attr_order: false)
-# => false
-----
-====
-
-.XML examples with ignore_attr_order
-[example]
-====
-When `true` the following XML strings are considered equal:
-
-[source,xml]
-----
-<item id="1" name="Widget" price="10.00"/>
-<item price="10.00" id="1" name="Widget"/>
-----
-
-[source,ruby]
-----
-xml1 = '<item id="1" name="Widget" price="10.00"/>'
-xml2 = '<item price="10.00" id="1" name="Widget"/>'
-Canon::Comparison.equivalent?(xml1, xml2, ignore_attr_order: true)
-# => true
-----
-====
-
-
-[[verbose]]
-==== verbose
-
-`verbose: {true|false}` default: `false`
-
-When `true`, instead of returning a boolean value `Canon::Comparison.equivalent?`
-returns an array of all errors encountered when performing a comparison.
-
-WARNING: When `true`, the comparison takes longer! Not only because more
-processing is required to produce meaningful differences, but also because in
-this mode, comparison does **NOT** stop when a first difference is encountered,
-because the goal is to capture as many differences as possible.
-
-Usage:
-
-[source,ruby]
-----
-Canon::Comparison.equivalent?(doc1, doc2, verbose: true)
-----
-
-Return values in verbose mode:
-
-* Empty array `[]` if documents are equivalent
-* Array of difference hashes if documents differ
-
-Each difference hash contains:
-
-`node1`:: The first node involved in the difference
-`node2`:: The second node involved in the difference
-`diff1`:: Difference code for the first node
-`diff2`:: Difference code for the second node
-
-Difference codes:
-
-* `Canon::Comparison::EQUIVALENT` (1) - Nodes are equivalent
-* `Canon::Comparison::MISSING_ATTRIBUTE` (2) - Attribute missing
-* `Canon::Comparison::MISSING_NODE` (3) - Node missing
-* `Canon::Comparison::UNEQUAL_ATTRIBUTES` (4) - Attributes differ
-* `Canon::Comparison::UNEQUAL_COMMENTS` (5) - Comments differ
-* `Canon::Comparison::UNEQUAL_ELEMENTS` (7) - Element names differ
-* `Canon::Comparison::UNEQUAL_NODES_TYPES` (8) - Node types differ
-* `Canon::Comparison::UNEQUAL_TEXT_CONTENTS` (9) - Text content differs
-
-.Verbose mode examples
-[example]
-====
-[source,ruby]
-----
-# Verbose mode with equivalent documents
-html1 = '<div>Hello</div>'
-html2 = '<div>Hello</div>'
-result = Canon::Comparison.equivalent?(html1, html2, verbose: true)
-# => [] (empty array indicates equivalence)
-
-# Verbose mode with different text content
-html1 = '<div>Hello</div>'
-html2 = '<div>Goodbye</div>'
-result = Canon::Comparison.equivalent?(html1, html2, verbose: true)
-# => [{
-#   node1: <Nokogiri::XML::Text>,
-#   node2: <Nokogiri::XML::Text>,
-#   diff1: 9,  # UNEQUAL_TEXT_CONTENTS
-#   diff2: 9   # UNEQUAL_TEXT_CONTENTS
-# }]
-
-# Verbose mode with different element names
-html1 = '<div>Test</div>'
-html2 = '<span>Test</span>'
-result = Canon::Comparison.equivalent?(html1, html2, verbose: true)
-# => [{
-#   node1: <Nokogiri::XML::Element: div>,
-#   node2: <Nokogiri::XML::Element: span>,
-#   diff1: 7,  # UNEQUAL_ELEMENTS
-#   diff2: 7   # UNEQUAL_ELEMENTS
-# }]
-
-# Verbose mode with missing attributes
-html1 = '<div class="foo" id="bar">Test</div>'
-html2 = '<div class="foo">Test</div>'
-result = Canon::Comparison.equivalent?(html1, html2, verbose: true)
-# => [{
-#   node1: <Nokogiri::XML::Element: div>,
-#   node2: <Nokogiri::XML::Element: div>,
-#   diff1: 2,  # MISSING_ATTRIBUTE
-#   diff2: 2   # MISSING_ATTRIBUTE
-# }]
-
-# Check difference type programmatically
-result = Canon::Comparison.equivalent?(html1, html2, verbose: true)
-if result.empty?
-  puts "Documents are equivalent"
-else
-  result.each do |diff|
-    case diff[:diff1]
-    when Canon::Comparison::UNEQUAL_TEXT_CONTENTS
-      puts "Text content differs"
-    when Canon::Comparison::UNEQUAL_ELEMENTS
-      puts "Element names differ"
-    when Canon::Comparison::MISSING_ATTRIBUTE
-      puts "Attributes differ"
-    end
-  end
-end
-----
-====
-
-=== Input validation
-
-Canon provides comprehensive input validation for all supported formats (XML,
-HTML, JSON, YAML). When malformed input is detected, Canon raises a
-`Canon::ValidationError` with detailed location information to help you quickly
-identify and fix the problem.
-
-==== Purpose
-
-Input validation ensures that:
-
-* Malformed documents are detected early with clear error messages
-* Syntax errors show exact line and column numbers
-* Error details appear in RSpec test output (not hidden in log files)
-* Users receive actionable feedback about what's wrong and where
-
-==== How it works
-
-Canon validates input **before parsing** using format-specific validators:
-
-* `Canon::Validators::XmlValidator` - Strict XML syntax validation
-* `Canon::Validators::HtmlValidator` - HTML5 and XHTML validation
-* `Canon::Validators::JsonValidator` - JSON syntax validation
-* `Canon::Validators::YamlValidator` - YAML syntax validation
-
-Validation happens automatically when you use Canon's formatters or comparison
-methods.
-
-==== Validation error format
-
-When validation fails, Canon raises `Canon::ValidationError` with:
-
-* `format` - The format being validated (`:xml`, `:html`, `:json`, `:yaml`)
-* `line` - Line number where the error occurred (if available)
-* `column` - Column number where the error occurred (if available)
-* `details` - Additional context about the error
-
-.Validation error example
-[example]
-[source,ruby]
-----
-require 'canon'
-
-malformed_xml = '<root><unclosed>'
-
-begin
-  Canon.format(malformed_xml, :xml)
-rescue Canon::ValidationError => e
-  puts e.message
-  # XML Validation Error: Premature end of data in tag unclosed line 1
-  #   Line: 1
-  #   Column: 18
-
-  puts "Format: #{e.format}"     # => :xml
-  puts "Line: #{e.line}"          # => 1
-  puts "Column: #{e.column}"      # => 18
-end
-----
-
-==== Format-specific validation
-
-===== XML validation
-
-Uses Nokogiri's strict XML parsing to detect:
-
-* Unclosed tags
-* Mismatched tags
-* Invalid XML declaration
-* Malformed attributes
-* Invalid character references
-
-.XML validation examples
-[example]
-[source,ruby]
-----
-# Unclosed tag
-Canon.format('<root><item>', :xml)
-# => Canon::ValidationError: XML Validation Error: Premature end of data in tag item line 1
-#      Line: 1
-
-# Mismatched tags
-Canon.format('<root><item></root>', :xml)
-# => Canon::ValidationError: XML Validation Error: Opening and ending tag mismatch: item line 1 and root
-#      Line: 1
-----
-
-===== HTML validation
-
-Automatically detects HTML5 vs XHTML and applies appropriate validation:
-
-* HTML5: Uses Nokogiri::HTML5 parser with error filtering
-* XHTML: Uses strict XML parsing
-
-Special handling:
-
-* Strips XML declarations from HTML (common in legacy HTML files)
-* Filters out non-critical HTML5 parser warnings
-* Only reports significant errors (level 2+)
-
-.HTML validation examples
-[example]
-[source,ruby]
-----
-# Malformed XHTML
-xhtml = '<html xmlns="http://www.w3.org/1999/xhtml"><body><p>Unclosed'
-Canon.format(xhtml, :html)
-# => Canon::ValidationError: HTML Validation Error: Premature end of data in tag p line 1
-#      Line: 1
-
-# HTML5 with errors
-html5 = '<div><span></div>'
-Canon.format(html5, :html)
-# => Canon::ValidationError: HTML Validation Error: Unexpected end tag : span
-#      Line: 1
-----
-
-===== JSON validation
-
-Validates JSON syntax using Ruby's JSON parser:
-
-* Missing/extra braces or brackets
-* Trailing commas
-* Invalid escape sequences
-* Invalid numbers
-
-Provides context showing the error location in the JSON structure.
-
-.JSON validation examples
-[example]
-[source,ruby]
-----
-# Missing closing brace
-Canon.format('{"key": "value"', :json)
-# => Canon::ValidationError: JSON Validation Error: unexpected token at '{"key": "value"'
-#      Details: Error at position 16
-
-# Trailing comma (invalid in JSON)
-Canon.format('{"a": 1,}', :json)
-# => Canon::ValidationError: JSON Validation Error: unexpected token at '{"a": 1,}'
-#      Details: Error at position 8
-----
-
-===== YAML validation
-
-Validates YAML syntax using Psych (Ruby's YAML parser):
-
-* Invalid indentation
-* Unclosed brackets/braces
-* Invalid anchors/aliases
-* Type mismatches
-
-Shows error location with line numbers and context.
-
-.YAML validation examples
-[example]
-[source,ruby]
-----
-# Unclosed bracket
-Canon.format("key: {unclosed", :yaml)
-# => Canon::ValidationError: YAML Validation Error: (<unknown>): did not find expected node content...
-#      Line: 1
-#      Details: Shows context around error
-
-# Invalid indentation
-yaml = <<~YAML
-  parent:
-  child: value
-YAML
-Canon.format(yaml, :yaml)
-# => Canon::ValidationError: YAML Validation Error: mapping values are not allowed in this context
-#      Line: 2
-----
-
-==== Validation in RSpec tests
-
-Canon's RSpec matchers automatically propagate validation errors to test output,
-making it easy to see what's wrong:
-
-.RSpec validation error example
-[example]
-[source,ruby]
-----
-require 'canon/rspec_matchers'
-
-RSpec.describe 'XML validation' do
-  it 'validates input' do
-    malformed_xml = '<root><unclosed>'
-    expected_xml = '<root><item/></root>'
-
-    # This will fail with a clear validation error message
-    expect(malformed_xml).to be_xml_equivalent_to(expected_xml)
-  end
-end
-
-# Test output shows:
-# Canon::ValidationError:
-#   XML Validation Error: Premature end of data in tag unclosed line 1
-#     Line: 1
-#     Column: 18
-----
-
-The error appears directly in the RSpec output, not hidden in separate error
-files or logs.
-
-==== Validation in comparison
-
-Validation also occurs when using `Canon::Comparison.equivalent?`:
-
-.Comparison validation example
-[example]
-[source,ruby]
-----
-require 'canon/comparison'
-
-xml1 = '<root><item/></root>'
-xml2 = '<root><unclosed>'
-
-Canon::Comparison.equivalent?(xml1, xml2)
-# => Canon::ValidationError: XML Validation Error: Premature end of data in tag unclosed line 1
-#      Line: 1
-#      Column: 18
-----
-
-==== Benefits
-
-Input validation provides several key benefits:
-
-**Early error detection**:: Problems are caught before processing begins, saving
-time and providing clear feedback
-
-**Precise error location**:: Line and column numbers pinpoint exactly where the
-problem is, especially useful in large documents
-
-**Clear error messages**:: Descriptive messages explain what's wrong and often
-suggest how to fix it
-
-**Test-friendly**:: Errors appear in RSpec output where developers expect them,
-not in separate log files
-
-**Format-aware**:: Each validator understands format-specific rules and provides
-relevant error details
-
-=== Reporting options (diff options)
-
-==== General
-
-Canon provides comprehensive diff formatting capabilities across three interfaces:
-RSpec matchers, CLI commands, and the Ruby API. All interfaces support the same
-set of parameters for consistent behavior.
-
-==== Parameters
-
-The following table shows all available diff formatting parameters and their
-availability across interfaces:
-
-[cols="1,1,1,1,2,1"]
-|===
-|Parameter |RSpec |CLI |Ruby API |Description |Default
-
-|`use_color`
-|✓
-|✓
-|✓
-|Enable/disable colored output
-|`true`
-
-|`diff_mode`
-|✓
-|✓
-|✓
-|Comparison mode: `:by_object` or `:by_line`
-|`:by_line` (RSpec), `:by_object` (XML/JSON/YAML)
-
-|`context_lines`
-|✓
-|✓
-|✓
-|Number of unchanged lines to show around each change
-|`3`
-
-|`diff_grouping_lines`
-|✓
-|✓
-|✓
-|Maximum line distance to group separate diffs into context blocks
-|`10`
-|===
-
-==== Interface-specific usage
-
-===== RSpec matchers configuration
-
-Configure diff formatting for RSpec matchers using `Canon::RspecMatchers`:
-
-[source,ruby]
-----
-require 'canon/rspec_matchers'
-
-# Configure globally for all matchers
-Canon::RspecMatchers.diff_mode = :by_object
-Canon::RspecMatchers.use_color = true
-Canon::RspecMatchers.context_lines = 5
-Canon::RspecMatchers.diff_grouping_lines = 10
-
-# Use in specs
-RSpec.describe 'My comparison' do
-  it 'shows formatted diff' do
-    expect(actual_xml).to be_xml_equivalent_to(expected_xml)
-  end
-end
-----
-
-===== CLI usage
-
-Pass options to the `canon diff` command:
-
-[source,bash]
-----
-# Basic diff with default settings
-$ canon diff file1.xml file2.xml --verbose
-
-# Customize diff output
-$ canon diff file1.xml file2.xml \
-  --verbose \
-  --by-line \
-  --no-color \
-  --context-lines 5 \
-  --diff-grouping-lines 10
-----
-
-===== Ruby API usage
-
-Use `Canon::DiffFormatter` directly in your code:
-
-[source,ruby]
-----
-require 'canon/diff_formatter'
-require 'canon/comparison'
-
-# Compare documents
-comparison = Canon::Comparison.new(doc1, doc2)
-result = comparison.compare
-
-# Format diff output
-formatter = Canon::DiffFormatter.new(
-  use_color: true,
-  mode: :by_object,
-  context_lines: 5,
-  diff_grouping_lines: 10
-)
-
-diff_output = formatter.format(result)
-puts diff_output
-----
-
-==== Parameter details
-
-===== use_color
-
-Controls whether diff output includes ANSI color codes.
-
-* Type: Boolean
-* Default: `true`
-* Colors used:
-** Red: Deletions/removed content
-** Green: Additions/inserted content
-** Yellow: Modified content
-** Cyan: Element names and structure
-
-[source,ruby]
-----
-# Disable colors for plain text output
-Canon::RspecMatchers.use_color = false
-
-# CLI
-$ canon diff file1.xml file2.xml --no-color --verbose
-----
-
-===== diff_mode
-
-Determines the comparison and display strategy.
-
-* Type: Symbol (`:by_object` or `:by_line`)
-* Default: `:by_line` for RSpec matchers, format-dependent for CLI/API
-* Modes:
-** `:by_object` - Semantic tree-based comparison showing structural changes
-** `:by_line` - Line-by-line diff after canonicalization
-
-[source,ruby]
-----
-# Use object-based diff for RSpec matchers
-Canon::RspecMatchers.diff_mode = :by_object
-
-# CLI - XML uses by-object by default, force by-line
-$ canon diff file1.xml file2.xml --by-line --verbose
-----
-
-===== context_lines
-
-Number of unchanged lines to display around each change for context.
-
-* Type: Numeric
-* Default: `3`
-* Range: `0` to any positive integer
-* Effect: Higher values show more surrounding context, lower values show only changes
-
-[source,ruby]
-----
-# Show 5 lines of context around each change
-Canon::RspecMatchers.context_lines = 5
-
-# CLI
-$ canon diff file1.xml file2.xml --context-lines 5 --verbose
-
-# Ruby API
-formatter = Canon::DiffFormatter.new(context_lines: 5)
-----
-
-===== diff_grouping_lines
-
-Maximum line distance between separate changes to group them into a single
-context block.
-
-* Type: Numeric or `nil`
-* Default: `nil` (no grouping)
-* Effect: When set, changes within N lines of each other are grouped into
-context blocks with a header showing the number of diffs in the block
-
-[source,ruby]
-----
-# Group changes that are within 10 lines of each other
-Canon::RspecMatchers.diff_grouping_lines = 10
-
-# CLI
-$ canon diff file1.xml file2.xml --diff-grouping-lines 10 --verbose
-
-# Ruby API
-formatter = Canon::DiffFormatter.new(diff_grouping_lines: 10)
-----
-
-.Example of grouped diff output
-[example]
-When `diff_grouping_lines` is set to `10`, changes close together are grouped:
-
-[source]
-----
-Context block has 3 diffs (lines 5-18):
-   5 - |     <foreword id="fwd">
-   5 + |     <foreword displayorder="2" id="fwd">
-   6   |       <p>First paragraph</p>
-   ...
-  15 - |     <title>Scope</title>
-  15 + |     <title>Application Scope</title>
-  16   |     </clause>
-  17 + |     <p>New content</p>
-  18   |   </sections>
-----
-
-Without grouping, these would appear as separate diff sections.
-
-=== Visualization options
-
-==== Enhanced diff output features
-
-Canon's diff formatter includes several enhancements designed to make diffs more
-readable and informative, especially when working with RSpec test failures.
-
-===== Color-coded line numbers and structure
-
-**Purpose**: Improve readability by distinguishing structural elements from
-content changes.
-
-When color mode is enabled (`use_color: true`), the diff formatter uses a
-consistent color scheme:
-
-* **Yellow**: Line numbers and pipe separators
-* **Red**: Deletion markers (`-`) and removed content
-* **Green**: Addition markers (`+`) and inserted content
-* **Default terminal color**: Unchanged context lines (no ANSI codes applied)
-
-This color scheme helps differentiate between:
-
-* The diff structure (line numbers, pipes)
-* Content that was removed (red)
-* Content that was added (green)
-* Content that stayed the same (your terminal's default color)
-
-.Example colored diff output
-[example]
-In a colored terminal, a typical diff line appears as:
-
-[source]
-----
-   5|   5 |   <p>First paragraph</p>     # Context line (yellow numbers/pipes, default text)
-   6|     -|   <old>Text</old>            # Deletion (yellow numbers/pipes, red marker/content)
-    |   6+|   <new>Text</new>             # Addition (yellow numbers/pipes, green marker/content)
-----
-
-Where:
-
-* Line numbers (`5`, `6`) are in yellow
-* Pipe separators (`|`) are in yellow
-* Markers (`-`, `+`) are in red/green respectively
-* Changed content is highlighted in red (deletions) or green (additions)
-* Unchanged content uses your terminal's default color (no forced white/black)
-
-**Why this matters**: When running tests with RSpec, the framework initially sets
-output to red. Canon's diff formatter explicitly resets colors to prevent RSpec's
-red from bleeding into the diff output, ensuring consistent and readable diffs.
-
-===== Whitespace visualization
-
-**Purpose**: Make invisible whitespace and special characters visible in diffs.
-
-Whitespace changes can be difficult to spot in traditional diffs because spaces,
-tabs, and other invisible characters don't appear in output. Canon visualizes
-these changes using a comprehensive set of Unicode symbols that are safe for use
-with CJK (Chinese, Japanese, Korean) text.
-
-**Visualization scope**: Character visualization is applied only to **diff lines**
-(additions, deletions, and changes), not to context lines (unchanged lines). This
-ensures that:
-
-* Context lines display content in its original form without substitution
-* Only actual changes show visualization, making differences easier to spot
-* Within changed lines showing token-level diffs, unchanged tokens are displayed
-in the terminal's default color (not red/green) to distinguish them from actual
-changes
-
-====== Default character visualization map
-
-Canon provides a comprehensive CJK-safe character mapping for common non-visible
-characters encountered in diffs:
-
-NOTE: These visualization symbols appear **only in diff lines** (additions,
-deletions, and changes), not in context lines (unchanged lines).
-
-.Common whitespace characters
-[cols="1,1,1,2"]
-|===
-|Character |Unicode |Symbol |Description
-
-|Regular space
-|U+0020
-|`░`
-|Light Shade (U+2591)
-
-|Tab
-|U+0009
-|`⇥`
-|Rightwards Arrow to Bar (U+21E5)
-
-|Non-breaking space
-|U+00A0
-|`␣`
-|Open Box (U+2423)
-|===
-
-.Line endings
-[cols="1,1,1,2"]
-|===
-|Character |Unicode |Symbol |Description
-
-|Line feed (LF)
-|U+000A
-|`↵`
-|Downwards Arrow with Corner Leftwards (U+21B5)
-
-|Carriage return (CR)
-|U+000D
-|`⏎`
-|Return Symbol (U+23CE)
-
-|Windows line ending (CRLF)
-|U+000D U+000A
-|`↵`
-|Downwards Arrow with Corner Leftwards (U+21B5)
-
-|Next line (NEL)
-|U+0085
-|`⏎`
-|Return Symbol (U+23CE)
-
-|Line separator
-|U+2028
-|`⤓`
-|Downwards Arrow to Bar (U+2913)
-
-|Paragraph separator
-|U+2029
-|`⤓`
-|Downwards Arrow to Bar (U+2913)
-|===
-
-.Unicode spaces (various widths)
-[cols="1,1,1,2"]
-|===
-|Character |Unicode |Symbol |Description
-
-|En space
-|U+2002
-|`▭`
-|White Rectangle (U+25AD)
-
-|Em space
-|U+2003
-|`▬`
-|Black Rectangle (U+25AC)
-
-|Four-per-em space
-|U+2005
-|`⏓`
-|Metrical Short Over Long (U+23D3)
-
-|Six-per-em space
-|U+2006
-|`⏕`
-|Metrical Two Shorts Over Long (U+23D5)
-
-|Thin space
-|U+2009
-|`▯`
-|White Vertical Rectangle (U+25AF)
-
-|Hair space
-|U+200A
-|`▮`
-|Black Vertical Rectangle (U+25AE)
-
-|Figure space
-|U+2007
-|`□`
-|White Square (U+25A1)
-
-|Narrow no-break space
-|U+202F
-|`▫`
-|White Small Square (U+25AB)
-
-|Medium mathematical space
-|U+205F
-|`▭`
-|White Rectangle (U+25AD)
-
-|Ideographic space
-|U+3000
-|`⎵`
-|Bottom Square Bracket (U+23B5)
-
-|Ideographic half space
-|U+303F
-|`⏑`
-|Metrical Breve (U+23D1)
-
-|===
-
-.Zero-width characters (invisible troublemakers)
-[cols="1,1,1,2"]
-|===
-|Character |Unicode |Symbol |Description
-
-|Zero-width space
-|U+200B
-|`→`
-|Rightwards Arrow (U+2192)
-
-|Zero-width non-joiner
-|U+200C
-|`↛`
-|Rightwards Arrow with Stroke (U+219B)
-
-|Zero-width joiner
-|U+200D
-|`⇢`
-|Rightwards Dashed Arrow (U+21E2)
-
-|Zero-width no-break space (BOM)
-|U+FEFF
-|`⇨`
-|Rightwards White Arrow (U+21E8)
-|===
-
-.Bidirectional/RTL markers
-[cols="1,1,1,2"]
-|===
-|Character |Unicode |Symbol |Description
-
-|Left-to-right mark
-|U+200E
-|`⟹`
-|Long Rightwards Double Arrow (U+27F9)
-
-|Right-to-left mark
-|U+200F
-|`⟸`
-|Long Leftwards Double Arrow (U+27F8)
-
-|LTR embedding
-|U+202A
-|`⇒`
-|Rightwards Double Arrow (U+21D2)
-
-|RTL embedding
-|U+202B
-|`⇐`
-|Leftwards Double Arrow (U+21D0)
-
-|Pop directional formatting
-|U+202C
-|`↔`
-|Left Right Arrow (U+2194)
-
-|LTR override
-|U+202D
-|`⇉`
-|Rightwards Paired Arrows (U+21C9)
-
-|RTL override
-|U+202E
-|`⇇`
-|Leftwards Paired Arrows (U+21C7)
-|===
-
-.Control characters
-[cols="1,1,1,2"]
-|===
-|Character |Unicode |Symbol |Description
-
-|Null
-|U+0000
-|`␀`
-|Symbol for Null (U+2400)
-
-|Soft hyphen
-|U+00AD
-|`­‐`
-|Hyphen (U+2010)
-
-|Backspace
-|U+0008
-|`␈`
-|Symbol for Backspace (U+2408)
-
-|Delete
-|U+007F
-|`␡`
-|Symbol for Delete (U+2421)
-|===
-
-====== CJK safety
-
-The visualization characters are specifically chosen to avoid conflicts with CJK
-text:
-
-* **No middle dots** (`·`) - commonly used as separators in CJK
-* **No bullets** (`∙`) - used in CJK lists
-* **No circles** (`◌◍◎`) - look similar to CJK characters like ○ ●
-* **No small dots** (`⋅`) - conflict with CJK punctuation
-
-Instead, Canon uses:
-* Box characters (`□▭▬▯▮▫`) for various space types
-* Arrow symbols (`→↛⇢⇨⟹⟸⇒⇐`) for zero-width and directional characters
-* Control Pictures block symbols (`␀␈␡`) for control characters
-
-====== Customizing character visualization
-
-You can customize the character visualization map for your specific needs:
-
-[source,ruby]
-----
-require 'canon/diff_formatter'
-
-# Create custom visualization map
-custom_map = Canon::DiffFormatter.merge_visualization_map({
-  ' '  => '·',    # Use middle dot for spaces (if not using CJK)
-  "\t" => '→',    # Use simple arrow for tabs
-  "\u200B" => '⚠' # Warning symbol for zero-width space
-})
-
-# Use custom map with formatter
-formatter = Canon::DiffFormatter.new(
-  use_color: true,
-  visualization_map: custom_map
-)
-
-# The custom map merges with defaults, so unspecified
-# characters still use the default visualization
-----
-
-====== Visualization in action
-
-.Whitespace visualization examples
-[example]
-[source]
-----
-# Space added between tags
-  10|     -| <tag>Value</tag>           # No space
-    |  10+| <tag>░Value</tag>           # Space added (green light shade)
-
-# Tab character
-  15|     -| <tag>⇥Value</tag>          # Tab (red arrow-to-bar)
-    |  15+| <tag>░░Value</tag>          # Two spaces (green light shades)
-
-# Non-breaking space (U+00A0)
-  20|     -| <tag>Value</tag>           # Regular space
-    |  20+| <tag>Value␣</tag>           # Non-breaking space (green open box)
-
-# Zero-width space (U+200B)
-  25|     -| <word1><word2>             # No zero-width space
-    |  25+| <word1>→<word2>             # Zero-width space (green arrow)
-
-# Mixed invisible characters
-  30|     -| <p>Text▬more</p>           # Em space (red black rectangle)
-    |  30+| <p>Text░more</p>            # Regular space (green light shade)
-----
-
-Where visualization symbols appear in:
-
-* Red when showing removed/deleted characters
-* Green when showing added/inserted characters
-* Bold to make them more visible
-
-**When is this useful?**
-
-1. **Test failures due to formatting**: Your test expects compact XML but receives
-pretty-printed XML with different indentation
-
-2. **Mixed whitespace**: Some parts of your code use tabs while others use spaces
-
-3. **Non-breaking spaces**: Copy-pasted content from browsers often contains
-U+00A0 instead of regular spaces
-
-4. **Zero-width characters**: Invisible Unicode characters that cause mysterious
-comparison failures
-
-5. **RTL/LTR markers**: Bidirectional text markers in internationalized content
-
-6. **Template differences**: Generated output has invisible character differences
-
-.Real-world example: Non-breaking space from web copy-paste
-[example]
-Without whitespace visualization, these two lines look identical:
-
-[source,xml]
-----
-<foreword id="fwd">
-<foreword id="fwd">
-----
-
-With whitespace visualization enabled, the difference is immediately visible:
-
-[source]
-----
-   4|     -| <foreword░id="fwd">         # Regular space (U+0020)
-    |   4+| <foreword␣id="fwd">          # Non-breaking space (U+00A0)
-----
-
-The different symbols (`░` vs `␣`) clearly show that one uses a regular space
-while the other uses a non-breaking space, likely from copying text from a web
-page or word processor.
-
-.Real-world example: Zero-width characters
-[example]
-Zero-width characters are completely invisible but affect comparison:
-
-[source,xml]
-----
-<item>Widget</item>
-<item>Widget</item>  <!-- Contains U+200B zero-width space after "Widget" -->
-----
-
-The diff shows:
-
-[source]
-----
-   5|     -| <item>Widget</item>
-    |   5+| <item>Widget→</item>         # Zero-width space visualized as →
-----
-
-The rightwards arrow (`→`) reveals the presence of a zero-width space that would
-otherwise be impossible to detect.
-
-===== Non-ASCII character detection
-
-**Purpose**: Alert users when diffs contain non-ASCII characters that might cause
-unexpected comparison failures or encoding issues.
-
-When Canon detects non-ASCII characters (any character with Unicode codepoint >
-U+007F) in a diff block, it displays a yellow warning with the specific
-characters and their Unicode codepoints.
-
-.Non-ASCII warning format
-[example]
-[source]
-----
-Context block has 3 diffs (lines 10-25):
-(WARNING: non-ASCII characters detected in diff: [' ' (U+00A0, shown as: ␣), '—' (U+2014, shown as: —)])
-
-  10|     -| <p>Hello░world</p>
-    |  10+| <p>Hello␣world</p>          # Contains non-breaking space (U+00A0)
-  15|     -| <p>Text - more text</p>
-    |  15+| <p>Text — more text</p>     # Contains em dash (U+2014)
-----
-
-The warning appears immediately after the "Context block has X diffs" header.
-
-**Common non-ASCII characters in diffs**:
-
-|===
-|Character |Unicode |Name |Common source
-
-|` ` (looks like space)
-|U+00A0
-|Non-breaking space
-|Copy-paste from web browsers, word processors
-
-|`—`
-|U+2014
-|Em dash
-|Word processors, smart quotes enabled
-
-|`–`
-|U+2013
-|En dash
-|Word processors, smart quotes enabled
-
-|`'` `'`
-|U+2018, U+2019
-|Smart single quotes
-|Word processors, text editors with smart quotes
-
-|`"` `"`
-|U+201C, U+201D
-|Smart double quotes
-|Word processors, text editors with smart quotes
-
-|`…`
-|U+2026
-|Ellipsis
-|Word processors
-
-|Various
-|U+2000-U+200B
-|Various spaces
-|HTML entities, special formatting
-|===
-
-**Why this matters**:
-
-1. **Invisible differences**: Many non-ASCII characters look identical to their
-ASCII equivalents but cause comparison failures
-
-2. **Encoding issues**: Non-ASCII characters may behave differently across
-systems with different encodings
-
-3. **Copy-paste errors**: Content copied from browsers or documents often
-includes non-breaking spaces instead of regular spaces
-
-4. **Smart quotes**: Text editors may automatically convert straight quotes to
-curly quotes
-
-.Practical example
-[example]
-A test fails because the expected output was copied from a web page:
-
-[source,ruby]
-----
-# Expected (copied from documentation website - contains U+00A0)
-expected = '<p>Hello world</p>'  # Space between "Hello" and "world" is U+00A0
-
-# Actual (generated by code - contains regular space)
-actual = '<p>Hello world</p>'    # Space is U+0020
-
-expect(actual).to be_xml_equivalent_to(expected)
-# FAILS: Documents appear identical but contain different space characters
-----
-
-Canon's diff output shows:
-
-[source]
-----
-Context block has 1 diff (line 1):
-(WARNING: non-ASCII characters detected in diff: [' ' (U+00A0)])
-
-   1|    -| <p>Hello world</p>          # U+0020 (regular space)
-    |  1+| <p>Hello░world</p>           # U+00A0 (non-breaking space, shown as block)
-----
-
-The warning alerts you to check for non-breaking spaces, and the light shade
-block visualization shows where the difference occurs.
-
-===== Configuration and usage
-
-All enhanced diff features are enabled by default when `use_color` is `true` and
-automatically applied across all Canon interfaces:
-
-[source,ruby]
-----
-# RSpec matchers (automatically enabled)
-expect(xml1).to be_xml_equivalent_to(xml2)
-# Output includes: colored line numbers, whitespace visualization, non-ASCII warnings
-
-# CLI (enabled by default)
-$ canon diff file1.xml file2.xml --verbose
-# Output includes all enhanced features
-
-# Ruby API (controlled by use_color parameter)
-formatter = Canon::DiffFormatter.new(use_color: true)  # Enhanced features enabled
-formatter = Canon::DiffFormatter.new(use_color: false) # Plain text only
-----
-
-To disable colored output (and all color-dependent enhancements):
-
-[source,ruby]
-----
-# RSpec
-Canon::RspecMatchers.use_color = false
-
-# CLI
-$ canon diff file1.xml file2.xml --no-color --verbose
-
-# Ruby API
-formatter = Canon::DiffFormatter.new(use_color: false)
-----
-
-When `use_color` is `false`:
-
-* Line numbers and pipes are plain text
-* Whitespace is not visualized (remains invisible)
-* Non-ASCII warnings are still shown (but without yellow color)
-* Content changes are shown without color highlighting
-
-
-== Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run
-`rake spec` to run the tests. You can also run `bin/console` for an interactive
-prompt that will allow you to experiment.
-
-
-== Contributing
-
-Bug reports and pull requests are welcome on GitHub at
-https://github.com/lutaml/canon.
-
-
-== Copyright and license
-
-Copyright Ribose.
-https://opensource.org/licenses/BSD-2-Clause[BSD-2-Clause License].