canon 0.1.8 → 0.1.9

data/old-docs/README.old.adoc

@@ -1,2831 +0,0 @@
-= Canon: Canonicalization for serialization formats
-
-Canon allows you to format, canonicalize, or compare various serialization
-formats, DOM-based (XML, HTML) or object-based (JSON, YAML).
-
-Its main features:
-
-* Canonicalization and pretty-printing for XML, HTML, JSON, and YAML
-* Comparison of XML, HTML, JSON, and YAML documents
-
-
-== 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 MECE (Mutually Exclusive,
-Collectively Exhaustive) principles for clean 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 MECE compliance 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].
-
-
-== Installation
-
-Add this line to your application's Gemfile:
-
-[source,ruby]
-----
-gem 'canon'
-----
-
-And then execute:
-
-[source,bash]
-----
-$ bundle install
-----
-
-Or install it yourself as:
-
-[source,bash]
-----
-$ gem install canon
-----
-
-
-== Usage
-
-=== Ruby API
-
-==== 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
-
-===== General
-
-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.
-====
-
-===== Basic usage
-
-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
-----
-====
-
-
-
-===== Options at a glance
-
-The `Canon::Comparison.equivalent?` method has a variety of options that tailor
-comparison behavior.
-
-The following options control comparison behavior:
-
-`collapse_whitespace`:: (default: `true`) when `true`, trims and collapses whitespace
-(<<collapse_whitespace>>)
-
-`normalize_tag_whitespace`:: (default: `false`) when `true`, normalizes whitespace
-boundaries around tags for flexible comparison (<<normalize_tag_whitespace>>)
-
-`ignore_comments`:: (default: `true`) when `true`, ignores HTML/XML comments
-(<<ignore_comments>>)
-
-`ignore_attr_order`:: (default: `true`) when `true`, ignores attribute ordering
-(<<ignore_attr_order>>)
-
-`ignore_text_nodes`:: (default: `false`) when `true`, ignores all text content
-(<<ignore_text_nodes>>)
-
-`verbose`:: (default: `false`) when `true`, returns array of differences instead of boolean
-(<<verbose>>)
-
-
-[[collapse_whitespace]]
-==== collapse_whitespace
-
-`collapse_whitespace: {true|false}` default: `true`
-
-When `true`, all text content within the document is trimmed (i.e. space removed
-from left and right) and whitespace is collapsed (i.e. tabs, new lines, multiple
-whitespace characters are replaced by a single whitespace).
-
-XML mode:: Whitespace is collapsed in text nodes only. Whitespace within
-attribute values is preserved.
-
-HTML mode:: Whitespace is collapsed in text nodes only. Whitespace within
-attribute values is preserved. Additionally, empty text nodes between elements
-are removed.
-
-Usage:
-
-[source,ruby]
-----
-Canon::Comparison.equivalent?(doc1, doc2, collapse_whitespace: true)
-----
-
-.HTML examples with collapse_whitespace
-[example]
-====
-When `true` the following HTML strings are considered equal:
-
-[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>'
-Canon::Comparison.equivalent?(html1, html2, collapse_whitespace: true)
-# => true
-----
-
-When `true` the following HTML strings are considered equal:
-
-[source,html]
-----
-<html>
-  <title>
-    This is my title
-  </title>
-</html>
-
-<html><title>This is my title</title></html>
-----
-
-[source,ruby]
-----
-html1 = <<~HTML
-  <html>
-    <title>
-      This is my title
-    </title>
-  </html>
-HTML
-html2 = '<html><title>This is my title</title></html>'
-Canon::Comparison.equivalent?(html1, html2, collapse_whitespace: true)
-# => true
-----
-====
-
-.XML examples with collapse_whitespace
-[example]
-====
-When `true` the following XML strings are considered equal:
-
-[source,xml]
-----
-<root>
-  <item>   Some text   </item>
-</root>
-
-<root><item>Some text</item></root>
-----
-
-[source,ruby]
-----
-xml1 = "<root>\n  <item>   Some text   </item>\n</root>"
-xml2 = '<root><item>Some text</item></root>'
-Canon::Comparison.equivalent?(xml1, xml2, collapse_whitespace: true)
-# => true
-----
-====
-
-[[normalize_tag_whitespace]]
-==== normalize_tag_whitespace
-
-`normalize_tag_whitespace: {true|false}` default: `false`
-
-When `true`, normalizes whitespace at tag boundaries by collapsing multiple
-whitespace characters (spaces, tabs, newlines) to a single space and stripping
-leading/trailing whitespace from text nodes. This enables "forgiving whitespace
-mode" for comparing documents that use different pretty-print formatting while
-maintaining the same semantic content.
-
-This option is specifically designed for comparing documents where:
-
-* One document is compact (no indentation/line breaks)
-* The other document is pretty-printed (with indentation/line breaks)
-* You want to ignore these formatting differences
-
-[NOTE]
-`normalize_tag_whitespace` is more aggressive than `collapse_whitespace`:
-
-* `collapse_whitespace` only trims and collapses whitespace within text content
-* `normalize_tag_whitespace` additionally handles whitespace at tag boundaries,
-making it suitable for comparing compact vs pretty-printed documents
-
-When both options are enabled, `normalize_tag_whitespace` takes precedence.
-
-Usage:
-
-[source,ruby]
-----
-Canon::Comparison.equivalent?(doc1, doc2, normalize_tag_whitespace: true)
-----
-
-.When to use normalize_tag_whitespace
-[example]
-Use this option when:
-
-1. **Comparing generated output with expected fixtures**: Your test generates
-pretty-printed XML/HTML but your fixture is compact (or vice versa)
-
-2. **Mixed formatting in test suites**: Some tests use pretty-printed expected
-values while others use compact format
-
-3. **Flexible test fixtures**: You want to maintain human-readable test fixtures
-with indentation but compare them against compact generated output
-
-4. **Format-agnostic testing**: Testing semantic equivalence regardless of
-whether the output is formatted or compact
-
-.XML examples with normalize_tag_whitespace
-[example]
-When `true`, documents with different tag boundary whitespace are considered equal:
-
-[source,xml]
-----
-<!-- Pretty-printed with line breaks and indentation -->
-<root>
-  <item>
-    <name>Widget</name>
-    <price>10.00</price>
-  </item>
-</root>
-
-<!-- Compact on a single line -->
-<root><item><name>Widget</name><price>10.00</price></item></root>
-----
-
-[source,ruby]
-----
-pretty = <<~XML
-  <root>
-    <item>
-      <name>Widget</name>
-      <price>10.00</price>
-    </item>
-  </root>
-XML
-
-compact = '<root><item><name>Widget</name><price>10.00</price></item></root>'
-
-Canon::Comparison.equivalent?(pretty, compact, normalize_tag_whitespace: true)
-# => true
-----
-
-When `false` (default), the whitespace differences matter:
-
-[source,ruby]
-----
-Canon::Comparison.equivalent?(pretty, compact, normalize_tag_whitespace: false)
-# => false (whitespace at tag boundaries differs)
-----
-
-This also handles complex nested structures:
-
-[source,xml]
-----
-<!-- Pretty-printed -->
-<document>
-  <metadata>
-    <title>My Document</title>
-    <author>
-      <name>John Doe</name>
-      <email>john@example.com</email>
-    </author>
-  </metadata>
-</document>
-
-<!-- Compact -->
-<document><metadata><title>My Document</title><author><name>John Doe</name><email>john@example.com</email></author></metadata></document>
-----
-
-[source,ruby]
-----
-pretty_doc = <<~XML
-  <document>
-    <metadata>
-      <title>My Document</title>
-      <author>
-        <name>John Doe</name>
-        <email>john@example.com</email>
-      </author>
-    </metadata>
-  </document>
-XML
-
-compact_doc = '<document><metadata><title>My Document</title><author><name>John Doe</name><email>john@example.com</email></author></metadata></document>'
-
-Canon::Comparison.equivalent?(pretty_doc, compact_doc, normalize_tag_whitespace: true)
-# => true
-----
-
-.HTML examples with normalize_tag_whitespace
-[example]
-When `true`, HTML with different formatting is considered equal:
-
-[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>'
-
-Canon::Comparison.equivalent?(pretty_html, compact_html, normalize_tag_whitespace: true)
-# => true
-----
-
-.RSpec configuration for normalize_tag_whitespace
-[example]
-For test suites that consistently need forgiving whitespace mode, configure it
-globally:
-
-[source,ruby]
-----
-# spec/spec_helper.rb
-require 'canon/rspec_matchers'
-
-RSpec.configure do |config|
-  # Enable forgiving whitespace mode globally for all Canon matchers
-  Canon::RSpecMatchers.configure do |canon_config|
-    canon_config.normalize_tag_whitespace = true
-  end
-end
-
-# Now all XML/HTML comparisons will use forgiving whitespace mode
-RSpec.describe 'My tests' do
-  it 'compares pretty-printed with compact XML' do
-    pretty_xml = <<~XML
-      <root>
-        <item>Value</item>
-      </root>
-    XML
-
-    compact_xml = '<root><item>Value</item></root>'
-
-    # These will be considered equivalent due to global configuration
-    expect(pretty_xml).to be_xml_equivalent_to(compact_xml)
-  end
-
-  it 'compares HTML with different formatting' do
-    pretty_html = <<~HTML
-      <div>
-        <p>Content</p>
-      </div>
-    HTML
-
-    compact_html = '<div><p>Content</p></div>'
-
-    expect(pretty_html).to be_html_equivalent_to(compact_html)
-  end
-end
-----
-
-To disable it for specific tests when globally enabled:
-
-[source,ruby]
-----
-# This test needs exact whitespace matching
-it 'checks exact whitespace' do
-  # Temporarily disable normalize_tag_whitespace
-  original = Canon::RSpecMatchers.normalize_tag_whitespace
-  Canon::RSpecMatchers.normalize_tag_whitespace = false
-
-  begin
-    expect(xml1).to be_xml_equivalent_to(xml2)
-  ensure
-    Canon::RSpecMatchers.normalize_tag_whitespace = original
-  end
-end
-----
-
-.Comparison with collapse_whitespace
-[example]
-Understanding the difference between `collapse_whitespace` and
-`normalize_tag_whitespace`:
-
-[source,ruby]
-----
-# Example XML with whitespace variations
-pretty = '<root>  <item>  Value  </item>  </root>'
-compact = '<root><item>Value</item></root>'
-
-# With collapse_whitespace only (default)
-Canon::Comparison.equivalent?(
-  pretty,
-  compact,
-  collapse_whitespace: true,
-  normalize_tag_whitespace: false
-)
-# => false
-# Reason: Whitespace at tag boundaries (spaces between > and <) differs
-
-# With normalize_tag_whitespace
-Canon::Comparison.equivalent?(
-  pretty,
-  compact,
-  normalize_tag_whitespace: true
-)
-# => true
-# Reason: All whitespace at tag boundaries is normalized
-----
-
-Key differences:
-
-|===
-|Feature |collapse_whitespace |normalize_tag_whitespace
-
-|Trims text content
-|✓
-|✓
-
-|Collapses internal whitespace
-|✓
-|✓
-
-|Normalizes tag boundaries
-|✗
-|✓
-
-|Use case
-|Flexible text comparison
-|Flexible format comparison
-|===
-
-[[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
-----
-====
-
-[[ignore_comments]]
-==== ignore_comments
-
-`ignore_comments: {true|false}` default: `true`
-
-When `true`, ignores comments such as `<!-- This is a comment -->`.
-
-Usage:
-
-[source,ruby]
-----
-Canon::Comparison.equivalent?(doc1, doc2, ignore_comments: true)
-----
-
-.HTML examples with ignore_comments
-[example]
-====
-When `true` the following HTML strings are considered equal:
-
-[source,html]
-----
-<!-- This is a comment -->
-<!-- This is another comment -->
-----
-
-[source,ruby]
-----
-html1 = '<!-- This is a comment -->'
-html2 = '<!-- This is another comment -->'
-Canon::Comparison.equivalent?(html1, html2, ignore_comments: true)
-# => true
-----
-
-When `true` the following HTML strings are considered equal:
-
-[source,html]
-----
-<a href="/admin"><!-- This is a comment -->Link</a>
-<a href="/admin">Link</a>
-----
-
-[source,ruby]
-----
-html1 = '<a href="/admin"><!-- This is a comment -->Link</a>'
-html2 = '<a href="/admin">Link</a>'
-Canon::Comparison.equivalent?(html1, html2, ignore_comments: true)
-# => true
-----
-
-When `false` comments are compared:
-
-[source,ruby]
-----
-html1 = '<div><!-- comment 1 --><p>Text</p></div>'
-html2 = '<div><!-- comment 2 --><p>Text</p></div>'
-Canon::Comparison.equivalent?(html1, html2, ignore_comments: false)
-# => false
-----
-====
-
-.XML examples with ignore_comments
-[example]
-====
-When `true` the following XML strings are considered equal:
-
-[source,xml]
-----
-<root>
-  <!-- First comment -->
-  <item>Data</item>
-</root>
-
-<root>
-  <!-- Different comment -->
-  <item>Data</item>
-</root>
-----
-
-[source,ruby]
-----
-xml1 = '<root><!-- First comment --><item>Data</item></root>'
-xml2 = '<root><!-- Different comment --><item>Data</item></root>'
-Canon::Comparison.equivalent?(xml1, xml2, ignore_comments: true)
-# => true
-----
-====
-
-[[ignore_text_nodes]]
-==== ignore_text_nodes
-
-`ignore_text_nodes: {true|false}` default: `false`
-
-When `true`, ignores all text content. Text content is anything that is included
-between an opening and a closing tag, e.g. `<tag>THIS IS TEXT CONTENT</tag>`.
-
-Usage:
-
-[source,ruby]
-----
-Canon::Comparison.equivalent?(doc1, doc2, ignore_text_nodes: true)
-----
-
-.HTML examples with ignore_text_nodes
-[example]
-====
-When `true` the following HTML strings are considered equal:
-
-[source,html]
-----
-<a href="/admin">SOME TEXT CONTENT</a>
-<a href="/admin">DIFFERENT TEXT CONTENT</a>
-----
-
-[source,ruby]
-----
-html1 = '<a href="/admin">SOME TEXT CONTENT</a>'
-html2 = '<a href="/admin">DIFFERENT TEXT CONTENT</a>'
-Canon::Comparison.equivalent?(html1, html2, ignore_text_nodes: true)
-# => true
-----
-
-When `true` the following HTML strings are considered equal:
-
-[source,html]
-----
-<i class="icon"></i><b>Warning:</b>
-<i class="icon"></i><b>Message:</b>
-----
-
-[source,ruby]
-----
-html1 = '<i class="icon"></i><b>Warning:</b>'
-html2 = '<i class="icon"></i><b>Message:</b>'
-Canon::Comparison.equivalent?(html1, html2, ignore_text_nodes: true)
-# => true
-----
-
-When `false` text content is compared:
-
-[source,ruby]
-----
-html1 = '<p>Hello</p>'
-html2 = '<p>Goodbye</p>'
-Canon::Comparison.equivalent?(html1, html2, ignore_text_nodes: false)
-# => false
-----
-====
-
-.XML examples with ignore_text_nodes
-[example]
-====
-When `true` the following XML strings are considered equal:
-
-[source,xml]
-----
-<item>First value</item>
-<item>Second value</item>
-----
-
-[source,ruby]
-----
-xml1 = '<item>First value</item>'
-xml2 = '<item>Second value</item>'
-Canon::Comparison.equivalent?(xml1, xml2, ignore_text_nodes: 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
-----
-====
-
-
-=== Diff formatting configuration
-
-==== 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.
-
-==== 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
-
-=== 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
-
-
-=== RSpec matchers
-
-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
-====
-
-
-== Command-line interface
-
-=== 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
-----
-
-==== Format detection
-
-[cols="1,1"]
-|===
-|File Extension |Detected Format
-
-|`.xml`
-|XML
-
-|`.html`, `.htm`
-|HTML
-
-|`.json`
-|JSON
-
-|`.yaml`, `.yml`
-|YAML
-|===
-
-=== 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)
-
-`--collapse-whitespace` / `--no-collapse-whitespace`:: Control whitespace
-normalization in text nodes (default: collapse)
-
-`--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
-
-
-== 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].