canon 0.1.3 → 0.1.5

data/docs/OPTIONS.adoc

@@ -0,0 +1,1387 @@
+= Comparison options reference
+:toc: left
+:toclevels: 3
+:sectanchors:
+:sectlinks:
+
+== Overview
+
+Canon provides a flexible, format-aware semantic comparison system for XML, HTML, JSON, and YAML documents. The comparison process follows a three-phase architecture that allows fine-grained control over how documents are compared.
+
+This document describes all available options for controlling Canon's comparison behavior across three interfaces: CLI, Ruby API, and RSpec matchers.
+
+== Architecture
+
+Canon's comparison flow consists of three distinct phases:
+
+[source]
+----
+┌──────────────────────────────────────────────────────────────────┐
+│                     CANON COMPARISON FLOW                        │
+└──────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────┐
+│   Input Documents   │
+│   (File 1, File 2)  │
+└──────────┬──────────┘
+           │
+           ▼
+╔══════════════════════════════════════════════════════════════════╗
+║                        PHASE 1: PREPROCESSING                     ║
+╠══════════════════════════════════════════════════════════════════╣
+║  Options:                                                         ║
+║  • none       - No preprocessing                                  ║
+║  • c14n       - Canonical form (XML C14N, JSON/YAML sorted)       ║
+║  • normalize  - Normalize whitespace                              ║
+║  • format     - Pretty-print with standard formatting             ║
+╚══════════════════════════════════════════════════════════════════╝
+           │
+           ▼
+┌─────────────────────┐
+│  Preprocessed Docs  │
+└──────────┬──────────┘
+           │
+           ▼
+╔══════════════════════════════════════════════════════════════════╗
+║                      PHASE 2: SEMANTIC MATCHING                   ║
+╠══════════════════════════════════════════════════════════════════╣
+║  Match Dimensions:                                                ║
+║  • text_content          (strict|normalize|ignore)                ║
+║  • structural_whitespace (strict|normalize|ignore)                ║
+║  • attribute_whitespace  (strict|normalize|ignore) [XML/HTML]     ║
+║  • attribute_order       (strict|ignore) [XML/HTML]               ║
+║  • attribute_values      (strict|normalize|ignore) [XML/HTML]     ║
+║  • key_order            (strict|ignore) [JSON/YAML]               ║
+║  • comments             (strict|normalize|ignore)                 ║
+║                                                                    ║
+║  Match Profiles:                                                  ║
+║  • strict         - All dimensions strict (exact matching)        ║
+║  • rendered       - Mimics browser/CSS rendering behavior         ║
+║  • spec_friendly  - Test-friendly (ignores formatting diffs)      ║
+║  • content_only   - Only semantic content matters                 ║
+╚══════════════════════════════════════════════════════════════════╝
+           │
+           ├─ Equivalent? ──► Return true
+           │
+           ├─ Different? ──┐
+           │               │
+           ▼               ▼
+╔══════════════════════════════════════════════════════════════════╗
+║                   PHASE 3: DIFF RENDERING                         ║
+╠══════════════════════════════════════════════════════════════════╣
+║  Diff Options:                                                    ║
+║  • mode            - by_line (XML/HTML) | by_object (JSON/YAML)   ║
+║  • use_color       - Colorized output (terminal colors)           ║
+║  • context_lines   - Lines of context around changes              ║
+║  • grouping_lines  - Group nearby changes into blocks             ║
+╚══════════════════════════════════════════════════════════════════╝
+           │
+           ▼
+┌─────────────────────┐
+│   Formatted Diff    │
+│      Output         │
+└─────────────────────┘
+----
+
+== Match Dimensions Reference
+
+Match dimensions control which aspects of documents are compared and how strictly they are compared. Each dimension can be set to one of several behaviors.
+
+=== text_content
+
+*Purpose*: Controls how text content within elements is compared.
+
+*Applies to*: XML, HTML, JSON, YAML
+
+*Behaviors*:
+
+* `strict` - Text must match exactly, character-for-character including all whitespace
+* `normalize` - Whitespace is normalized (collapsed/trimmed) before comparison
+* `ignore` - Text content is completely ignored in comparison
+
+*XML Example*:
+
+.Input Files
+[source,xml]
+----
+<!-- File 1 -->
+<message>Hello   World</message>
+
+<!-- File 2 -->
+<message>Hello World</message>
+----
+
+.Comparison Results
+|===
+|Behavior |Result |Explanation
+
+|`strict`
+|Different
+|Whitespace differs (3 spaces vs 1 space)
+
+|`normalize`
+|Equivalent
+|Both normalize to "Hello World"
+
+|`ignore`
+|Equivalent
+|Text content ignored, structure matches
+|===
+
+*JSON Example*:
+
+.Input Files
+[source,json]
+----
+// File 1
+{"message": "Hello   World"}
+
+// File 2
+{"message": "Hello World"}
+----
+
+.Comparison Results
+|===
+|Behavior |Result |Explanation
+
+|`strict`
+|Different
+|String values differ
+
+|`normalize`
+|Equivalent
+|Whitespace normalized in strings
+
+|`ignore`
+|Equivalent
+|Only structure compared
+|===
+
+=== structural_whitespace
+
+*Purpose*: Controls how whitespace between elements (indentation, newlines) is handled.
+
+*Applies to*: XML, HTML, JSON, YAML
+
+*Behaviors*:
+
+* `strict` - All structural whitespace must match exactly
+* `normalize` - Structural whitespace is normalized
+* `ignore` - Structural whitespace is completely ignored
+
+*XML Example*:
+
+.Input Files
+[source,xml]
+----
+<!-- File 1 -->
+<root>
+  <item>A</item>
+  <item>B</item>
+</root>
+
+<!-- File 2 -->
+<root><item>A</item><item>B</item></root>
+----
+
+.Comparison Results
+|===
+|Behavior |Result |Explanation
+
+|`strict`
+|Different
+|Indentation and newlines differ
+
+|`normalize`
+|Equivalent
+|Whitespace between elements normalized
+
+|`ignore`
+|Equivalent
+|Only element structure compared
+|===
+
+*JSON Example*:
+
+.Input Files
+[source,json]
+----
+// File 1
+{
+  "items": [
+    "A",
+    "B"
+  ]
+}
+
+// File 2
+{"items":["A","B"]}
+----
+
+.Comparison Results
+|===
+|Behavior |Result |Explanation
+
+|`strict`
+|Different
+|Formatting differs
+
+|`normalize`
+|Equivalent
+|Both have same structure
+
+|`ignore`
+|Equivalent
+|Structure identical
+|===
+
+=== attribute_whitespace
+
+*Purpose*: Controls how whitespace in attribute values is handled.
+
+*Applies to*: XML, HTML only
+
+*Behaviors*:
+
+* `strict` - Attribute value whitespace must match exactly
+* `normalize` - Whitespace in attribute values is normalized
+* `ignore` - Whitespace in attribute values is ignored
+
+*XML Example*:
+
+.Input Files
+[source,xml]
+----
+<!-- File 1 -->
+<div class="item  active">Content</div>
+
+<!-- File 2 -->
+<div class="item active">Content</div>
+----
+
+.Comparison Results
+|===
+|Behavior |Result |Explanation
+
+|`strict`
+|Different
+|Attribute value whitespace differs (2 spaces vs 1)
+
+|`normalize`
+|Equivalent
+|"item  active" normalizes to "item active"
+
+|`ignore`
+|Equivalent
+|Only attribute presence compared
+|===
+
+*HTML Special Behavior*:
+
+HTML's `class` attribute is space-separated, so normalization is particularly useful:
+
+[source,html]
+----
+<!-- These are equivalent with normalize -->
+<div class="btn  primary   active">Click</div>
+<div class="btn primary active">Click</div>
+----
+
+=== attribute_order
+
+*Purpose*: Controls whether attribute order matters.
+
+*Applies to*: XML, HTML only
+
+*Behaviors*:
+
+* `strict` - Attributes must appear in the same order
+* `ignore` - Attribute order doesn't matter (set-based comparison)
+
+*XML Example*:
+
+.Input Files
+[source,xml]
+----
+<!-- File 1 -->
+<element id="123" class="active" data-value="test"/>
+
+<!-- File 2 -->
+<element class="active" data-value="test" id="123"/>
+----
+
+.Comparison Results
+|===
+|Behavior |Result |Explanation
+
+|`strict`
+|Different
+|Attribute order differs
+
+|`ignore`
+|Equivalent
+|Same attributes present (unordered comparison)
+|===
+
+*HTML Special Behavior*:
+
+HTML attributes are inherently unordered by the HTML spec, so the default for HTML formats is `ignore`:
+
+[source,html]
+----
+<!-- These are always equivalent for HTML -->
+<input type="text" id="name" class="form-control">
+<input class="form-control" id="name" type="text">
+----
+
+=== attribute_values
+
+*Purpose*: Controls how attribute values are compared.
+
+*Applies to*: XML, HTML only
+
+*Behaviors*:
+
+* `strict` - Attribute values must match exactly
+* `normalize` - Whitespace in values is normalized
+* `ignore` - Only attribute presence is checked, values ignored
+
+*XML Example*:
+
+.Input Files
+[source,xml]
+----
+<!-- File 1 -->
+<element id="123" class="normative"/>
+
+<!-- File 2 -->
+<element id="456" class="informative"/>
+----
+
+.Comparison Results
+|===
+|Behavior |Result |Explanation
+
+|`strict`
+|Different
+|Attribute values differ
+
+|`normalize`
+|Different
+|Values still differ after normalization
+
+|`ignore`
+|Equivalent
+|Both have `id` and `class` attributes (values ignored)
+|===
+
+*Use Case*: Useful when you want to verify that certain attributes exist but don't care about their specific values (e.g., testing that generated IDs are present).
+
+=== key_order
+
+*Purpose*: Controls whether object key order matters.
+
+*Applies to*: JSON, YAML only
+
+*Behaviors*:
+
+* `strict` - Keys must appear in the same order
+* `ignore` - Key order doesn't matter (unordered comparison)
+
+*JSON Example*:
+
+.Input Files
+[source,json]
+----
+// File 1
+{
+  "name": "John",
+  "age": 30,
+  "city": "NYC"
+}
+
+// File 2
+{
+  "city": "NYC",
+  "name": "John",
+  "age": 30
+}
+----
+
+.Comparison Results
+|===
+|Behavior |Result |Explanation
+
+|`strict`
+|Different
+|Key order differs
+
+|`ignore`
+|Equivalent
+|Same keys and values (unordered)
+|===
+
+*YAML Example*:
+
+.Input Files
+[source,yaml]
+----
+# File 1
+name: John
+age: 30
+city: NYC
+
+# File 2
+city: NYC
+name: John
+age: 30
+----
+
+.Comparison Results
+|===
+|Behavior |Result |Explanation
+
+|`strict`
+|Different
+|Key order differs
+
+|`ignore`
+|Equivalent
+|Same structure and values
+|===
+
+=== comments
+
+*Purpose*: Controls how comments are compared.
+
+*Applies to*: XML, HTML, YAML (JSON doesn't support comments in standard spec)
+
+*Behaviors*:
+
+* `strict` - Comments must match exactly (including whitespace)
+* `normalize` - Whitespace in comments is normalized
+* `ignore` - Comments are completely ignored
+
+*XML Example*:
+
+.Input Files
+[source,xml]
+----
+<!-- File 1 -->
+<root>
+  <!-- This is a comment -->
+  <element>Value</element>
+</root>
+
+<!-- File 2 -->
+<root>
+  <element>Value</element>
+</root>
+----
+
+.Comparison Results
+|===
+|Behavior |Result |Explanation
+
+|`strict`
+|Different
+|File 1 has a comment, File 2 doesn't
+
+|`normalize`
+|Different
+|Still different (comment present vs absent)
+
+|`ignore`
+|Equivalent
+|Comments ignored, structure matches
+|===
+
+*YAML Example*:
+
+.Input Files
+[source,yaml]
+----
+# File 1
+# Configuration file
+name: test
+# Database settings
+database: prod
+
+# File 2
+name: test
+database: prod
+----
+
+.Comparison Results
+|===
+|Behavior |Result |Explanation
+
+|`strict`
+|Different
+|Comments differ
+
+|`normalize`
+|Different
+|Comments still differ
+
+|`ignore`
+|Equivalent
+|Comments ignored
+|===
+
+== Preprocessing Options
+
+Preprocessing transforms documents before comparison. This happens in Phase 1 of the comparison flow.
+
+=== none
+
+*Description*: No preprocessing applied. Documents are compared as-is.
+
+*Use when*: You want to compare the exact input without any modifications.
+
+=== c14n
+
+*Description*: Apply canonical form:
+
+* *XML/HTML*: W3C XML Canonicalization (C14N) 1.1
+* *JSON*: Sort keys alphabetically, normalize whitespace
+* *YAML*: Sort keys, normalize to standard YAML format
+
+*Use when*: You want to eliminate all formatting differences before comparison.
+
+=== normalize
+
+*Description*: Normalize whitespace throughout the document:
+
+* Collapse multiple whitespace to single space
+* Trim leading/trailing whitespace
+* Normalize line endings
+
+*Use when*: You want to ignore whitespace differences but preserve structure.
+
+=== format
+
+*Description*: Pretty-print the document with standard formatting:
+
+* *XML/HTML*: 2-space indentation, one element per line
+* *JSON*: 2-space indentation, standard JSON formatting
+* *YAML*: Standard YAML formatting
+
+*Use when*: You want both documents formatted consistently before comparison.
+
+== Match Profiles
+
+Match profiles are predefined combinations of match dimension settings. They provide convenient shortcuts for common comparison scenarios.
+
+=== strict
+
+*Description*: Exact matching - all dimensions are set to `strict`.
+
+*Settings*:
+[source,ruby]
+----
+{
+  preprocessing: :none,
+  text_content: :strict,
+  structural_whitespace: :strict,
+  attribute_whitespace: :strict,
+  attribute_order: :strict,
+  attribute_values: :strict,
+  key_order: :strict,
+  comments: :strict
+}
+----
+
+*Use when*: You need character-perfect matching.
+
+=== rendered
+
+*Description*: Mimics how browsers/CSS engines render content.
+
+*Settings*:
+[source,ruby]
+----
+{
+  preprocessing: :none,
+  text_content: :normalize,
+  structural_whitespace: :normalize,
+  attribute_whitespace: :normalize,
+  attribute_order: :ignore,
+  attribute_values: :strict,
+  key_order: :ignore,
+  comments: :ignore
+}
+----
+
+*Use when*: Comparing rendered output (HTML) where formatting doesn't affect display.
+
+=== spec_friendly
+
+*Description*: Test-friendly comparison that ignores most formatting differences.
+
+*Settings*:
+[source,ruby]
+----
+{
+  preprocessing: :normalize,
+  text_content: :normalize,
+  structural_whitespace: :ignore,
+  attribute_whitespace: :normalize,
+  attribute_order: :ignore,
+  attribute_values: :strict,
+  key_order: :ignore,
+  comments: :ignore
+}
+----
+
+*Use when*: Writing tests where you care about content but not formatting.
+
+=== content_only
+
+*Description*: Only semantic content matters - maximum tolerance for formatting.
+
+*Settings*:
+[source,ruby]
+----
+{
+  preprocessing: :normalize,
+  text_content: :normalize,
+  structural_whitespace: :ignore,
+  attribute_whitespace: :ignore,
+  attribute_order: :ignore,
+  attribute_values: :ignore,
+  key_order: :ignore,
+  comments: :ignore
+}
+----
+
+*Use when*: You only care about the structural content, not any formatting or attribute details.
+
+== Format Defaults
+
+Each format has sensible defaults based on its typical usage:
+
+[cols="1,1,1,1,1,1,1,1",options="header"]
+|===
+|Dimension |XML |HTML |HTML4 |HTML5 |JSON |YAML
+
+|preprocessing
+|none
+|none
+|none
+|none
+|none
+|none
+
+|text_content
+|strict
+|normalize
+|normalize
+|normalize
+|strict
+|strict
+
+|structural_whitespace
+|strict
+|normalize
+|normalize
+|normalize
+|strict
+|strict
+
+|attribute_whitespace
+|strict
+|normalize
+|normalize
+|normalize
+|—
+|—
+
+|attribute_order
+|strict
+|ignore
+|ignore
+|ignore
+|—
+|—
+
+|attribute_values
+|strict
+|strict
+|strict
+|strict
+|—
+|—
+
+|key_order
+|—
+|—
+|—
+|—
+|strict
+|strict
+
+|comments
+|strict
+|ignore
+|ignore
+|ignore
+|—
+|strict
+|===
+
+*Diff Mode Defaults*:
+
+* XML/HTML: `by_line`
+* JSON/YAML: `by_object`
+
+== Verbose Mode
+
+When `verbose: true` is specified, Canon returns detailed information about the comparison results in a Hash structure instead of a simple boolean.
+
+=== Return Structure
+
+Verbose mode returns a Hash with two keys:
+
+[source,ruby]
+----
+{
+  differences: Array,    # Array of difference objects
+  preprocessed: Array    # Two-element array of preprocessed content
+}
+----
+
+=== differences
+
+An array of difference objects. Each difference object contains:
+
+* *For XML/HTML*:
+  - `:node1` - The node from the first document
+  - `:node2` - The node from the second document (or nil if missing)
+  - `:diff1` - Difference code (e.g., `Canon::Comparison::UNEQUAL_ELEMENTS`)
+  - `:diff2` - Corresponding code for second document
+  - Additional context depending on the difference type
+
+* *For JSON/YAML*:
+  - `:path` - Path to the difference (e.g., "user.name" or "[2].id")
+  - `:value1` - Value from first document
+  - `:value2` - Value from second document
+  - `:diff_code` - Type of difference (e.g., `Canon::Comparison::UNEQUAL_PRIMITIVES`)
+
+If documents are equivalent, `differences` will be an empty array.
+
+=== preprocessed
+
+A two-element array containing the preprocessed versions of both documents that were used for comparison.
+
+**Important**: The preprocessed content respects match options. For example:
+
+* When `comments: :ignore` is set, comments are removed from the preprocessed XML
+* When `structural_whitespace: :ignore` is set, whitespace-only text nodes are filtered from XML
+* For HTML with `preprocessing: :rendered`, the content is normalized to match browser rendering
+
+This ensures that diff rendering shows only the content that was actually compared, avoiding confusion from showing differences in ignored content.
+
+.Example: XML with comments ignored
+[source,ruby]
+----
+xml1 = <<~XML
+  <root>
+    <!-- This comment will be filtered -->
+    <item>Value</item>
+  </root>
+XML
+
+xml2 = "<root><item>Value</item></root>"
+
+result = Canon::Comparison.equivalent?(xml1, xml2,
+  match: { comments: :ignore },
+  verbose: true
+)
+
+# result[:preprocessed][0] will have the comment removed
+# This ensures diff rendering doesn't show comment differences
+# that were ignored during comparison
+----
+
+=== Using Verbose Results
+
+.Check for equivalence
+[source,ruby]
+----
+result = Canon::Comparison.equivalent?(doc1, doc2, verbose: true)
+
+if result[:differences].empty?
+  puts "Documents are equivalent"
+else
+  puts "Found #{result[:differences].size} differences"
+end
+----
+
+.Access preprocessed content for custom processing
+[source,ruby]
+----
+result = Canon::Comparison.equivalent?(xml1, xml2,
+  match: { structural_whitespace: :ignore },
+  verbose: true
+)
+
+preprocessed1, preprocessed2 = result[:preprocessed]
+
+# Use preprocessed content for custom diff rendering
+# or further analysis
+----
+
+.Iterate through differences
+[source,ruby]
+----
+result = Canon::Comparison.equivalent?(json1, json2, verbose: true)
+
+result[:differences].each do |diff|
+  puts "Path: #{diff[:path]}"
+  puts "  Expected: #{diff[:value1].inspect}"
+  puts "  Got:      #{diff[:value2].inspect}"
+end
+----
+
+== Usage
+
+=== CLI Interface
+
+==== Command Syntax
+
+[source,bash]
+----
+canon diff FILE1 FILE2 [OPTIONS]
+----
+
+==== Match Control Options
+
+[source,bash]
+----
+--match-profile PROFILE          # strict|rendered|spec_friendly|content_only
+--preprocessing MODE             # none|c14n|normalize|format
+
+# Match dimensions
+--text-content BEHAVIOR          # strict|normalize|ignore
+--structural-whitespace BEHAVIOR # strict|normalize|ignore
+--attribute-whitespace BEHAVIOR  # strict|normalize|ignore (XML/HTML only)
+--attribute-order BEHAVIOR       # strict|ignore (XML/HTML only)
+--attribute-values BEHAVIOR      # strict|normalize|ignore (XML/HTML only)
+--key-order BEHAVIOR            # strict|ignore (JSON/YAML only)
+--comments BEHAVIOR             # strict|normalize|ignore
+----
+
+==== Diff Display Options
+
+[source,bash]
+----
+--diff-mode MODE                # by_line|by_object
+--color / --no-color            # Enable/disable colorized output
+--context-lines N               # Number of context lines around changes
+--diff-grouping-lines N         # Group changes within N lines
+----
+
+==== Format Specification
+
+[source,bash]
+----
+--format FORMAT                 # xml|html|json|yaml (for both files)
+--format1 FORMAT                # Format of first file
+--format2 FORMAT                # Format of second file
+----
+
+==== CLI Examples
+
+.Use a match profile
+[source,bash]
+----
+canon diff file1.xml file2.xml --match-profile spec_friendly
+----
+
+.Override a specific dimension
+[source,bash]
+----
+canon diff file1.xml file2.xml --text-content normalize
+----
+
+.Combine profile with overrides
+[source,bash]
+----
+canon diff file1.xml file2.xml \
+  --match-profile spec_friendly \
+  --comments strict \
+  --diff-mode by_line
+----
+
+.Preprocess before comparing
+[source,bash]
+----
+canon diff file1.xml file2.xml --preprocessing normalize
+----
+
+.Multiple dimension overrides
+[source,bash]
+----
+canon diff file1.xml file2.xml \
+  --text-content normalize \
+  --structural-whitespace ignore \
+  --attribute-order ignore
+----
+
+.JSON comparison with custom diff settings
+[source,bash]
+----
+canon diff config1.json config2.json \
+  --match-profile spec_friendly \
+  --key-order ignore \
+  --context-lines 5 \
+  --no-color
+----
+
+.HTML comparison with rendered profile
+[source,bash]
+----
+canon diff page1.html page2.html \
+  --match-profile rendered \
+  --diff-grouping-lines 2
+----
+
+=== Ruby API Interface
+
+==== Method Signature
+
+[source,ruby]
+----
+Canon::Comparison.equivalent?(obj1, obj2, options = {})
+----
+
+==== Options Hash
+
+[source,ruby]
+----
+{
+  # Match control
+  match_profile: Symbol,      # :strict, :rendered, :spec_friendly, :content_only
+  preprocessing: Symbol,      # :none, :c14n, :normalize, :format
+  match: Hash,                # Hash of dimension => behavior
+
+  # Diff control
+  verbose: Boolean,           # Return diff details if different
+  diff: Hash                  # Diff rendering options
+}
+----
+
+==== Match Options Hash
+
+[source,ruby]
+----
+{
+  text_content: Symbol,          # :strict, :normalize, :ignore
+  structural_whitespace: Symbol, # :strict, :normalize, :ignore
+  attribute_whitespace: Symbol,  # :strict, :normalize, :ignore (XML/HTML)
+  attribute_order: Symbol,       # :strict, :ignore (XML/HTML)
+  attribute_values: Symbol,      # :strict, :normalize, :ignore (XML/HTML)
+  key_order: Symbol,            # :strict, :ignore (JSON/YAML)
+  comments: Symbol              # :strict, :normalize, :ignore
+}
+----
+
+==== Diff Options Hash
+
+[source,ruby]
+----
+{
+  mode: Symbol,           # :by_line, :by_object
+  use_color: Boolean,     # Enable/disable colors
+  context_lines: Integer, # Lines of context
+  grouping_lines: Integer # Group changes within N lines
+}
+----
+
+==== Ruby API Examples
+
+.Basic comparison with auto-detection
+[source,ruby]
+----
+require "canon/comparison"
+
+xml1 = File.read("file1.xml")
+xml2 = File.read("file2.xml")
+
+Canon::Comparison.equivalent?(xml1, xml2)
+# => true or false
+----
+
+.Use a match profile
+[source,ruby]
+----
+Canon::Comparison.equivalent?(xml1, xml2,
+  match_profile: :spec_friendly
+)
+----
+
+.Preprocess before comparison
+[source,ruby]
+----
+Canon::Comparison.equivalent?(xml1, xml2,
+  preprocessing: :normalize
+)
+----
+
+.Override specific match dimensions
+[source,ruby]
+----
+Canon::Comparison.equivalent?(xml1, xml2,
+  match: {
+    text_content: :normalize,
+    structural_whitespace: :ignore,
+    comments: :ignore
+  }
+)
+----
+
+.Combine profile with dimension overrides
+[source,ruby]
+----
+Canon::Comparison.equivalent?(xml1, xml2,
+  match_profile: :spec_friendly,
+  match: {
+    comments: :strict  # Override profile setting
+  }
+)
+----
+
+.Get verbose diff output
+[source,ruby]
+----
+result = Canon::Comparison.equivalent?(xml1, xml2,
+  match_profile: :spec_friendly,
+  verbose: true
+)
+
+if result.is_a?(Hash)
+  # Verbose mode returns a Hash with :differences and :preprocessed keys
+  if result[:differences].empty?
+    # Documents are equivalent
+    puts "Files match!"
+  else
+    # Documents differ, result[:differences] contains diff details
+    puts "Differences found:"
+    puts result[:differences]
+
+    # result[:preprocessed] contains the preprocessed content
+    # that was used for comparison, respecting match options
+    # (e.g., whitespace-only nodes filtered for XML)
+    preprocessed1, preprocessed2 = result[:preprocessed]
+  end
+else
+  # Non-verbose mode returns boolean
+  puts result ? "Files match!" : "Files differ"
+end
+----
+
+.Verbose with custom diff options
+[source,ruby]
+----
+result = Canon::Comparison.equivalent?(xml1, xml2,
+  match_profile: :spec_friendly,
+  verbose: true,
+  diff: {
+    mode: :by_line,
+    use_color: true,
+    context_lines: 5,
+    grouping_lines: 2
+  }
+)
+----
+
+.JSON comparison
+[source,ruby]
+----
+json1 = File.read("config1.json")
+json2 = File.read("config2.json")
+
+Canon::Comparison.equivalent?(json1, json2,
+  match_profile: :spec_friendly,
+  match: {
+    key_order: :ignore
+  }
+)
+----
+
+.Explicit format specification
+[source,ruby]
+----
+Canon::Comparison::XmlComparator.equivalent?(xml1, xml2,
+  match_profile: :strict,
+  match: {
+    attribute_order: :ignore
+  }
+)
+----
+
+=== RSpec Interface
+
+==== Global Configuration
+
+[source,ruby]
+----
+# spec/spec_helper.rb or spec/support/canon.rb
+require "canon/rspec_matchers"
+
+Canon::RSpecMatchers.configure do |config|
+  # Format-specific configuration
+  config.<format>.match.profile = Symbol
+  config.<format>.match.options = Hash
+  config.<format>.preprocessing = Symbol
+  config.<format>.diff.mode = Symbol
+  config.<format>.diff.use_color = Boolean
+  config.<format>.diff.context_lines = Integer
+  config.<format>.diff.grouping_lines = Integer
+end
+----
+
+*Supported formats*: `xml`, `html`, `json`, `yaml`
+
+==== Match Configuration
+
+For each format, set match profile or individual dimension options:
+
+[source,ruby]
+----
+# Using a profile
+config.<format>.match.profile = :spec_friendly
+
+# OR using individual dimension options
+config.<format>.match.options = {
+  text_content: :normalize,
+  structural_whitespace: :ignore,
+  attribute_whitespace: :normalize,  # XML/HTML only
+  attribute_order: :ignore,          # XML/HTML only
+  attribute_values: :strict,         # XML/HTML only
+  key_order: :ignore,               # JSON/YAML only
+  comments: :ignore
+}
+----
+
+==== Diff Configuration
+
+For each format:
+
+[source,ruby]
+----
+config.<format>.diff.mode = :by_line           # :by_line or :by_object
+config.<format>.diff.use_color = true
+config.<format>.diff.context_lines = 3
+config.<format>.diff.grouping_lines = 10
+----
+
+==== Matcher Syntax
+
+[source,ruby]
+----
+# Basic matchers
+expect(actual).to be_equivalent_xml_to(expected)
+expect(actual).to be_equivalent_html_to(expected)
+expect(actual).to be_equivalent_json_to(expected)
+expect(actual).to be_equivalent_yaml_to(expected)
+
+# With verbose output (shows diff on failure)
+expect(actual).to be_equivalent_xml_to(expected, verbose: true)
+
+# Override with profile
+expect(actual).to be_equivalent_xml_to(expected, verbose: true)
+  .with_profile(:rendered)
+
+# Override with specific options
+expect(actual).to be_equivalent_xml_to(expected, verbose: true)
+  .with_options(
+    text_content: :strict,
+    structural_whitespace: :strict
+  )
+
+# Combine profile and option overrides
+expect(actual).to be_equivalent_xml_to(expected, verbose: true)
+  .with_profile(:spec_friendly)
+  .with_options(comments: :strict)
+----
+
+==== RSpec Examples
+
+.Global configuration for XML
+[source,ruby]
+----
+Canon::RSpecMatchers.configure do |config|
+  config.xml.match.profile = :spec_friendly
+  config.xml.preprocessing = :normalize
+  config.xml.match.options = {
+    text_content: :normalize,
+    structural_whitespace: :ignore,
+    comments: :ignore
+  }
+  config.xml.diff.mode = :by_line
+  config.xml.diff.use_color = true
+  config.xml.diff.context_lines = 3
+end
+----
+
+.Global configuration for HTML
+[source,ruby]
+----
+Canon::RSpecMatchers.configure do |config|
+  config.html.match.profile = :rendered
+  config.html.match.options = {
+    structural_whitespace: :ignore
+  }
+  config.html.diff.mode = :by_line
+  config.html.diff.grouping_lines = 2
+end
+----
+
+.Global configuration for JSON
+[source,ruby]
+----
+Canon::RSpecMatchers.configure do |config|
+  config.json.match.profile = :spec_friendly
+  config.json.match.options = {
+    key_order: :ignore
+  }
+  config.json.diff.mode = :by_object
+  config.json.diff.context_lines = 5
+end
+----
+
+.Basic spec usage
+[source,ruby]
+----
+RSpec.describe "XML comparison" do
+  it "compares XML documents" do
+    actual = File.read("actual.xml")
+    expected = File.read("expected.xml")
+
+    expect(actual).to be_equivalent_xml_to(expected)
+  end
+end
+----
+
+.With verbose output
+[source,ruby]
+----
+it "shows diff on failure" do
+  expect(actual).to be_equivalent_xml_to(expected, verbose: true)
+end
+----
+
+.Override global config with profile
+[source,ruby]
+----
+it "uses strict matching for this test" do
+  expect(actual).to be_equivalent_xml_to(expected, verbose: true)
+    .with_profile(:strict)
+end
+----
+
+.Override specific dimensions
+[source,ruby]
+----
+it "requires strict whitespace for this test" do
+  expect(actual).to be_equivalent_xml_to(expected, verbose: true)
+    .with_options(
+      structural_whitespace: :strict,
+      text_content: :strict
+    )
+end
+----
+
+.Combine profile and overrides
+[source,ruby]
+----
+it "uses spec_friendly but checks comments" do
+  expect(actual).to be_equivalent_xml_to(expected, verbose: true)
+    .with_profile(:spec_friendly)
+    .with_options(comments: :strict)
+end
+----
+
+.HTML comparison
+[source,ruby]
+----
+it "compares HTML with rendered profile" do
+  expect(actual_html).to be_equivalent_html_to(expected_html, verbose: true)
+    .with_profile(:rendered)
+end
+----
+
+.JSON comparison
+[source,ruby]
+----
+it "compares JSON ignoring key order" do
+  expect(actual_json).to be_equivalent_json_to(expected_json, verbose: true)
+    .with_options(key_order: :ignore)
+end
+----
+
+== Configuration Precedence
+
+When options are specified in multiple places, Canon resolves them using the following precedence hierarchy (highest to lowest):
+
+[source]
+----
+1. Per-test explicit options (highest priority)
+   ↓
+2. Per-test profile
+   ↓
+3. Global config explicit options
+   ↓
+4. Global config profile
+   ↓
+5. Format defaults (lowest priority)
+----
+
+=== Precedence Example
+
+.Global configuration
+[source,ruby]
+----
+Canon::RSpecMatchers.configure do |config|
+  config.xml.match.profile = :spec_friendly  # Sets multiple dimensions
+  config.xml.match.options = { comments: :strict }  # Explicit override
+end
+----
+
+The `:spec_friendly` profile sets:
+- `text_content: :normalize`
+- `structural_whitespace: :ignore`
+- `comments: :ignore`
+
+But the explicit `comments: :strict` in options overrides the profile setting.
+
+.Per-test usage
+[source,ruby]
+----
+expect(actual).to be_equivalent_xml_to(expected)
+  .with_profile(:rendered)  # Sets: text_content=normalize, structural_whitespace=normalize
+  .with_options(structural_whitespace: :ignore)  # Explicit override
+----
+
+*Final resolved options*:
+- `text_content: :normalize` (from `:rendered` per-test profile)
+- `structural_whitespace: :ignore` (from per-test explicit option)
+- `comments: :strict` (from global explicit option)
+- Other dimensions use `:rendered` profile or format defaults
+
+=== Resolution Rules
+
+. Explicit options always override profile settings
+. Per-test options override global configuration
+. Profile settings are merged (not replaced) - explicit options from lower precedence levels are preserved
+. Missing dimensions fall back to the next level in the hierarchy
+. At the bottom, format defaults provide the final fallback
+
+This allows you to:
+
+* Set sensible defaults globally
+* Use profiles for common scenarios
+* Override specific dimensions when needed
+* Maintain fine-grained control per test