canon 0.1.8 → 0.1.10

data/old-docs/DOM_DIFF.adoc

@@ -1,1017 +0,0 @@
----
-layout: default
-title: DOM Diff
-nav_order: 42
-parent: Advanced Topics
----
-= DOM Diff Architecture
-:toc:
-:toclevels: 3
-
-== General
-
-Canon implements an advanced DOM (Document Object Model) diff algorithm as its default comparison method. Unlike simple text-based diff tools, Canon's DOM diff operates on the semantic structure of documents, providing precise, context-aware comparisons that respect the document's hierarchical nature.
-
-The DOM diff architecture is built on a sophisticated multi-layer pipeline that separates semantic comparison from textual representation, enabling features like normative/informative classification, intelligent grouping, and format-aware rendering.
-
-== When to use DOM diff
-
-DOM diff is Canon's **default algorithm** and is automatically used when you compare documents without explicitly specifying `diff_algorithm: :semantic`.
-
-DOM diff is ideal for:
-
-* **Standard document comparisons** where you need to see line-by-line differences
-* **Format-preserving comparisons** that respect the original document structure
-* **Normative vs informative analysis** of document changes
-* **Fine-grained control** over what constitutes a meaningful difference
-* **All document formats** (XML, HTML, JSON, YAML)
-
-For semantic tree-level operations (MERGE, SPLIT, UPGRADE, DOWNGRADE), see link:TREE_DIFF.adoc[Semantic Tree Diff].
-
-== Core architecture
-
-=== Architectural layers
-
-Canon's DOM diff follows a strict separation of concerns across six distinct layers:
-
-[source]
-----
-┌─────────────────────────────────────────┐
-│  Layer 1: Comparison                    │
-│  Creates semantic DiffNodes             │
-└─────────────────┬───────────────────────┘
-                  ↓
-┌─────────────────────────────────────────┐
-│  Layer 2: Mapping                       │
-│  Maps DiffNodes → DiffLines             │
-└─────────────────┬───────────────────────┘
-                  ↓
-┌─────────────────────────────────────────┐
-│  Layer 3: Blocking                      │
-│  Groups DiffLines → DiffBlocks          │
-└─────────────────┬───────────────────────┘
-                  ↓
-┌─────────────────────────────────────────┐
-│  Layer 4: Contexting                    │
-│  Adds context → DiffContexts            │
-└─────────────────┬───────────────────────┘
-                  ↓
-┌─────────────────────────────────────────┐
-│  Layer 5: Reporting                     │
-│  Wraps in DiffReport                    │
-└─────────────────┬───────────────────────┘
-                  ↓
-┌─────────────────────────────────────────┐
-│  Layer 6: Formatting                    │
-│  Renders to human-readable output       │
-└─────────────────────────────────────────┘
-----
-
-Each layer has a single, well-defined responsibility and operates independently of the others. This separation enables powerful features like filtering normative-only differences or rendering the same comparison in multiple formats.
-
-=== Key design principles
-
-**Separation of concerns**::
-Business logic (comparison, mapping, blocking) is completely separated from presentation (formatting). Formatters receive structured data and only handle rendering.
-
-**Information expert**::
-Each object knows about its own data. `DiffNode` knows if it's normative, `DiffLine` inherits from its `DiffNode`, `DiffBlock` aggregates from its lines.
-
-**Single responsibility**::
-Each class does exactly one thing: Comparator compares, Mapper maps, BlockBuilder groups, Formatter renders.
-
-**Tell, don't ask**::
-Objects expose behavior (`normative?`) rather than raw data, encapsulating decision-making logic within the appropriate class.
-
-== Core classes
-
-=== DiffNode
-
-Represents a **semantic difference** between two DOM nodes. Created during the Comparison Layer.
-
-[source,ruby]
-----
-class DiffNode
-  attr_reader :node1      # Element from first document
-  attr_reader :node2      # Element from second document
-  attr_reader :dimension  # Match dimension causing difference
-  attr_reader :reason     # Human-readable explanation
-  attr_accessor :normative # true/false (set by DiffClassifier)
-end
-----
-
-**Purpose**:: Captures **what** differs at the semantic/DOM level, independent of text representation.
-
-**Key attributes**::
-* `node1`, `node2`: The actual DOM elements being compared
-* `dimension`: Which match dimension detected the difference (`:text_content`, `:attribute_whitespace`, `:element_structure`, etc.)
-* `reason`: Descriptive text explaining the difference (e.g., "7 vs 9", "attribute 'class' differs")
-* `normative`: Whether this difference affects semantic equivalence
-
-**Example**::
-[source,ruby]
-----
-DiffNode.new(
-  node1: <Element "div">,
-  node2: <Element "div">,
-  dimension: :text_content,
-  reason: "Text differs: 'Old' vs 'New'"
-)
-----
-
-=== DiffLine
-
-Represents a **single line** in the diff output. Links textual representation to semantic `DiffNode`. Created during the Mapping Layer.
-
-[source,ruby]
-----
-class DiffLine
-  attr_reader :line_number # Line number in original text
-  attr_reader :content     # Text content of the line
-  attr_reader :type        # :unchanged, :added, :removed, :changed
-  attr_reader :diff_node   # Reference to semantic DiffNode
-
-  def normative?           # Inherited from diff_node
-  def informative?         # Opposite of normative?
-end
-----
-
-**Purpose**:: Bridges semantic differences (DiffNodes) to textual representation (lines of text).
-
-**Key attributes**::
-* `line_number`: Position in the original document
-* `content`: The actual text of the line
-* `type`: Type of change (`:unchanged`, `:added`, `:removed`, `:changed`)
-* `diff_node`: Reference to the semantic DiffNode causing this line to differ
-
-**Example**::
-[source,ruby]
-----
-DiffLine.new(
-  line_number: 5,
-  content: "<p>New text</p>",
-  type: :changed,
-  diff_node: diff_node  # Links to semantic difference
-)
-# => normative? returns true if diff_node.normative? is true
-----
-
-=== DiffBlock
-
-Represents a **contiguous block of changes** in the diff. Groups consecutive DiffLines together. Created during the Blocking Layer.
-
-[source,ruby]
-----
-class DiffBlock
-  attr_reader :start_idx   # Starting line index
-  attr_reader :end_idx     # Ending line index
-  attr_reader :types       # Array of change types ['-', '+', '!']
-  attr_reader :diff_lines  # Array of DiffLine objects
-  attr_reader :diff_node   # DiffNode if all lines from same node
-  attr_accessor :normative # true if ANY diff_line is normative
-
-  def size                 # Number of lines in block
-  def includes_type?(type) # Check if block contains type
-end
-----
-
-**Purpose**:: Groups contiguous changed lines into logical units for display and filtering.
-
-**Key attributes**::
-* `start_idx`, `end_idx`: Line range for this block
-* `types`: Types of changes in this block (e.g., `['-', '+']` for removal+addition)
-* `diff_lines`: The actual DiffLine objects in this block
-* `diff_node`: Reference to DiffNode if all lines belong to the same semantic difference
-* `normative`: `true` if **any** line in the block is normative
-
-**Example**::
-[source,ruby]
-----
-DiffBlock.new(
-  start_idx: 10,
-  end_idx: 12,
-  types: ['-', '+'],
-  diff_lines: [removed_line, added_line],
-  normative: true
-)
-# => This block represents a normative change spanning lines 10-12
-----
-
-=== DiffContext
-
-Represents a **context** - a group of DiffBlocks with surrounding context lines. Created during the Contexting Layer.
-
-[source,ruby]
-----
-class DiffContext
-  attr_reader :start_idx   # Start of context (includes context lines)
-  attr_reader :end_idx     # End of context (includes context lines)
-  attr_reader :blocks      # Array of DiffBlock objects
-  attr_reader :lines       # Array of all lines (changes + context)
-  attr_accessor :normative # true if contains normative blocks
-
-  def size                 # Total lines in context
-  def block_count          # Number of diff blocks
-  def gap_to(other)        # Distance to another context
-  def overlaps?(other)     # Check if contexts overlap
-end
-----
-
-**Purpose**:: Provides surrounding context for groups of changes, making diffs easier to understand.
-
-**Key attributes**::
-* `start_idx`, `end_idx`: Extended range including context lines before/after
-* `blocks`: The DiffBlock objects contained in this context
-* `lines`: All lines including context (unchanged lines around changes)
-* `normative`: `true` if this context contains any normative blocks
-
-**Example**::
-[source,ruby]
-----
-DiffContext.new(
-  start_idx: 8,      # Starts 2 lines before first change
-  end_idx: 15,       # Ends 2 lines after last change
-  blocks: [block1, block2],
-  normative: true
-)
-# => Context spans lines 8-15, includes 2 diff blocks
-----
-
-== The DOM diff pipeline
-
-=== Layer 1: Comparison
-
-**Input**:: Two documents (doc1, doc2) + match options
-
-**Process**:: `XmlComparator.equivalent?(doc1, doc2, options)`
-
-**Output**:: Array of `DiffNode` objects
-
-**How it works**::
-
-1. Parse both documents into DOM trees
-2. Compare nodes recursively according to match dimensions
-3. For each difference found, create a `DiffNode`
-4. `DiffClassifier` sets `normative` based on match dimension behavior
-5. Return array of classified `DiffNode` objects
-
-**Example**::
-[source,ruby]
-----
-# Input documents
-doc1 = "<div><p>Old text</p></div>"
-doc2 = "<div><p>New text</p></div>"
-
-# Comparison creates DiffNode
-diff_node = DiffNode.new(
-  node1: <Element "p">,
-  node2: <Element "p">,
-  dimension: :text_content,
-  reason: "Text differs: 'Old text' vs 'New text'",
-  normative: true  # Set by DiffClassifier
-)
-
-result.diff_nodes
-# => [diff_node]
-----
-
-=== Layer 2: Mapping (DiffNodes → DiffLines)
-
-**Input**:: DiffNode array, text1, text2
-
-**Process**:: `DiffNodeMapper.map(diff_nodes, text1, text2)`
-
-**Output**:: Array of `DiffLine` objects
-
-**How it works**::
-
-1. Run text-based diff (using `Diff::LCS`) on the serialized text
-2. For each changed line, find the corresponding `DiffNode`
-3. Create `DiffLine` linking the line to its semantic `DiffNode`
-4. Inherit `normative` status from the linked `DiffNode`
-
-**Example**::
-[source,ruby]
-----
-# From the DiffNode above, create DiffLines
-diff_lines = [
-  DiffLine.new(
-    line_number: 1,
-    content: "<div>",
-    type: :unchanged,
-    diff_node: nil  # No semantic difference for this line
-  ),
-  DiffLine.new(
-    line_number: 2,
-    content: "<p>Old text</p>",
-    type: :removed,
-    diff_node: diff_node  # Links to semantic difference
-  ),
-  DiffLine.new(
-    line_number: 2,
-    content: "<p>New text</p>",
-    type: :added,
-    diff_node: diff_node  # Same DiffNode
-  )
-]
-----
-
-**Why this matters**:: The link between `DiffLine` and `DiffNode` preserves semantic information throughout the pipeline. A formatter can ask `diff_line.normative?` and get the answer from the original semantic comparison.
-
-=== Layer 3: Blocking (DiffLines → DiffBlocks)
-
-**Input**:: DiffLine array, `show_diffs` option
-
-**Process**:: `DiffBlockBuilder.build_blocks(diff_lines, show_diffs)`
-
-**Output**:: Array of `DiffBlock` objects
-
-**How it works**::
-
-1. Identify runs of consecutive changed lines
-2. Group each run into a `DiffBlock`
-3. Set `block.normative` based on constituent lines
-4. Filter blocks according to `show_diffs` option
-
-**Filtering options**::
-* `show_diffs: :normative` - Keep only blocks with `normative? == true`
-* `show_diffs: :informative` - Keep only blocks with `normative? == false`
-* `show_diffs: :all` - Keep all blocks (default)
-
-**Example**::
-[source,ruby]
-----
-# From DiffLines above
-diff_block = DiffBlock.new(
-  start_idx: 1,
-  end_idx: 2,
-  types: ['-', '+'],
-  diff_lines: [removed_line, added_line],
-  normative: true  # Any line is normative → block is normative
-)
-
-# With show_diffs: :normative
-# => This block is kept (normative? == true)
-
-# With show_diffs: :informative
-# => This block is filtered out
-----
-
-=== Layer 4: Contexting (DiffBlocks → DiffContexts)
-
-**Input**:: DiffBlock array, `context_lines`, `grouping_lines` options
-
-**Process**:: `DiffContextBuilder.build_contexts(blocks, options)`
-
-**Output**:: Array of `DiffContext` objects
-
-**How it works**::
-
-1. **Group nearby blocks**: Blocks within `grouping_lines` of each other are grouped together
-2. **Expand with context**: Add `context_lines` unchanged lines before and after each group
-3. **Create contexts**: Wrap each group in a `DiffContext` object
-
-**Example**::
-[source,ruby]
-----
-# Options
-context_lines = 3    # Show 3 lines before/after
-grouping_lines = 5   # Group blocks within 5 lines
-
-# If two blocks are 4 lines apart, they're grouped into one context
-# If they're 6 lines apart, they become separate contexts
-
-diff_context = DiffContext.new(
-  start_idx: 0,      # Includes 3 context lines before
-  end_idx: 8,        # Includes 3 context lines after
-  blocks: [block1, block2],
-  normative: true
-)
-----
-
-=== Layer 5: Reporting (Wrap in DiffReport)
-
-**Input**:: DiffContext array + metadata
-
-**Process**:: `DiffReportBuilder.build(diff_nodes, text1, text2, opts)`
-
-**Output**:: `DiffReport` object
-
-**How it works**::
-
-1. Orchestrate layers 2-4 (Mapping → Blocking → Contexting)
-2. Collect metadata (file names, element name, etc.)
-3. Wrap everything in a `DiffReport` object
-
-**Example**::
-[source,ruby]
-----
-diff_report = DiffReport.new(
-  element_name: "document",
-  file1_name: "old.xml",
-  file2_name: "new.xml",
-  contexts: [context1, context2],
-  has_differences: true
-)
-----
-
-=== Layer 6: Formatting (Render to string)
-
-**Input**:: `DiffReport` object
-
-**Process**:: `Formatter.format(diff_report)`
-
-**Output**:: Formatted string
-
-**How it works**::
-
-1. Iterate through contexts in the report
-2. Render each context with appropriate visualization
-3. Apply colors, line numbers, and symbols
-4. Return formatted output
-
-**Example**::
-[source,ruby]
-----
-# Formatter receives structured DiffReport
-# NO comparison, NO filtering, NO business logic
-# ONLY rendering
-
-formatted = ByLine::XmlFormatter.format(diff_report)
-# =>
-# 1 | <div>
-# 2-| <p>Old text</p>
-#  +| <p>New text</p>
-# 3 | </div>
-----
-
-== Matching vs formatting stages
-
-A key architectural feature of Canon's DOM diff is the **complete separation** between matching (semantic comparison) and formatting (visual representation).
-
-=== Matching stage (Layers 1-2)
-
-The matching stage determines **what** differs:
-
-1. **Semantic comparison**: Compare DOM nodes according to match dimensions
-2. **Classification**: Classify differences as normative or informative
-3. **Mapping**: Link semantic differences to text line positions
-
-**Output**: Structured data about differences (`DiffNode[]` → `DiffLine[]`)
-
-**No formatting**: The matching stage knows nothing about colors, symbols, or visual representation
-
-=== Formatting stage (Layers 3-6)
-
-The formatting stage determines **how** to display differences:
-
-1. **Grouping**: Group lines into blocks, blocks into contexts
-2. **Filtering**: Apply `show_diffs` to filter normative/informative
-3. **Rendering**: Apply visual representation (colors, line numbers, symbols)
-
-**Input**: Structured data from matching stage
-
-**No comparison**: The formatting stage never compares documents or makes semantic decisions
-
-=== Why this matters
-
-**Flexibility**::
-The same comparison result can be formatted in multiple ways without re-running the comparison.
-
-[source,ruby]
-----
-# Compare once
-result = Canon.compare(doc1, doc2, format: :xml)
-
-# Format multiple ways
-puts Canon::DiffFormatter::ByLine::XmlFormatter.format(result.report)
-puts Canon::DiffFormatter::ByObject::XmlFormatter.format(result.report)
-
-# No need to re-compare!
-----
-
-**Testability**::
-Each stage can be tested independently. Matchers test semantic comparison, formatters test visual output.
-
-**Maintainability**::
-Changes to comparison logic don't affect formatting, and vice versa.
-
-== Normative vs informative classification
-
-One of Canon's most powerful features is the ability to classify differences as **normative** (semantically significant) or **informative** (cosmetic).
-
-=== How classification works
-
-Classification happens in Layer 1 (Comparison) via `DiffClassifier`:
-
-[source,ruby]
-----
-# For each DiffNode
-dimension = diff_node.dimension           # e.g., :attribute_whitespace
-behavior = match_options[dimension]       # e.g., :ignore
-
-diff_node.normative = (behavior != :ignore)
-----
-
-**Logic**::
-* If the match dimension is set to `:ignore` → `normative = false` (informative only)
-* Otherwise → `normative = true` (normative difference)
-
-=== Propagation through layers
-
-The `normative` flag propagates through the pipeline:
-
-[source]
-----
-DiffNode.normative?
-    ↓
-DiffLine.normative? (inherits from diff_node)
-    ↓
-DiffBlock.normative? (true if ANY line is normative)
-    ↓
-DiffContext.normative? (true if ANY block is normative)
-----
-
-=== Filtering by classification
-
-Use `show_diffs` to filter based on classification:
-
-[source,ruby]
-----
-# Show only normative differences
-Canon.compare(doc1, doc2,
-  match: { attribute_whitespace: :ignore },
-  show_diffs: :normative
-)
-# => Hides attribute whitespace changes
-
-# Show only informative differences
-Canon.compare(doc1, doc2,
-  show_diffs: :informative
-)
-# => Shows only cosmetic changes
-
-# Show all differences
-Canon.compare(doc1, doc2,
-  show_diffs: :all
-)
-# => Shows everything (default)
-----
-
-== Comparison with semantic tree diff
-
-Canon provides two diff algorithms:
-
-[cols="1,2,2"]
-|===
-| Feature | DOM Diff (Default) | Semantic Tree Diff
-
-| **Algorithm**
-| Line-based diff with semantic awareness
-| Tree-edit distance with operation detection
-
-| **Output**
-| Line-by-line differences
-| High-level operations (MERGE, SPLIT, etc.)
-
-| **Granularity**
-| Fine-grained (every line)
-| Coarse-grained (tree structures)
-
-| **Use case**
-| Standard comparisons, detailed analysis
-| Semantic refactoring analysis
-
-| **Performance**
-| Fast for most documents
-| Slower for large trees
-
-| **API**
-| `Canon.compare(doc1, doc2)` (default)
-| `Canon.compare(doc1, doc2, diff_algorithm: :semantic)`
-
-| **Classes**
-| DiffNode, DiffLine, DiffBlock, DiffContext
-| TreeNode, Operation, NodeSignature
-|===
-
-**When to use DOM diff**::
-* For regular document comparisons
-* When you need line-level details
-* When performance is critical
-* For all document formats
-
-**When to use semantic tree diff**::
-* For analyzing structural refactoring
-* When you need operation-level insights (MERGE, SPLIT)
-* For detecting semantic patterns
-* See link:TREE_DIFF.adoc[Semantic Tree Diff] for details
-
-== Examples
-
-=== Basic DOM diff
-
-[source,ruby]
-----
-require 'canon'
-
-doc1 = <<~XML
-  <doc>
-    <p>Hello</p>
-  </doc>
-XML
-
-doc2 = <<~XML
-  <doc>
-    <p>World</p>
-  </doc>
-XML
-
-result = Canon.compare(doc1, doc2, format: :xml)
-puts result.diff
-# =>
-# 1 | <doc>
-# 2-|   <p>Hello</p>
-#  +|   <p>World</p>
-# 3 | </doc>
-----
-
-=== Normative-only differences
-
-[source,ruby]
-----
-doc1 = '<div class="foo" id="1">Text</div>'
-doc2 = '<div id="1" class="foo">Text</div>'
-
-# Attribute order is ignored by default
-result = Canon.compare(doc1, doc2,
-  format: :xml,
-  show_diffs: :normative
-)
-
-puts result.diff
-# => (empty - no normative differences)
-----
-
-=== Informative-only differences
-
-[source,ruby]
-----
-doc1 = '<p>Text</p>'
-doc2 = '<p>  Text  </p>'  # Extra whitespace
-
-result = Canon.compare(doc1, doc2,
-  format: :xml,
-  match: { text_whitespace: :ignore },
-  show_diffs: :informative
-)
-
-puts result.diff
-# => Shows the whitespace difference (informative only)
-----
-
-=== Accessing structured data
-
-[source,ruby]
-----
-result = Canon.compare(doc1, doc2, format: :xml)
-
-# Access DiffNodes
-result.diff_nodes.each do |node|
-  puts "#{node.dimension}: #{node.reason}"
-  puts "Normative: #{node.normative?}"
-end
-
-# Access DiffReport
-report = result.report
-puts "Total contexts: #{report.contexts.length}"
-puts "Has differences: #{report.has_differences?}"
-
-# Access DiffContexts
-report.contexts.each do |context|
-  puts "Context lines #{context.start_idx}-#{context.end_idx}"
-  puts "Normative: #{context.normative?}"
-end
-----
-
-== Implementation details
-
-=== Element name matching
-
-`DiffNodeMapper` links `DiffLine` objects to `DiffNode` objects by matching element names:
-
-[source,ruby]
-----
-# Extract element name from line
-line = "<bibitem id='123'>"
-element_name = extract_element_name(line)
-# => "bibitem"
-
-# Find DiffNode with matching element
-diff_node = diff_nodes.find do |node|
-  node.node1.name == element_name ||
-  node.node2.name == element_name
-end
-
-# Create DiffLine linked to DiffNode
-DiffLine.new(
-  content: line,
-  diff_node: diff_node  # Linked!
-)
-----
-
-This ensures that each changed line is correctly associated with its semantic difference.
-
-=== Block grouping
-
-`DiffBlockBuilder` groups consecutive changed lines:
-
-[source,ruby]
-----
-# Lines: U, U, C, C, C, U, C, U
-# Blocks: [C, C, C], [C]
-#
-# Block 1: lines 2-4 (3 consecutive changes)
-# Block 2: line 6 (1 change)
-----
-
-=== Context expansion
-
-`DiffContextBuilder` expands blocks with surrounding lines:
-
-[source,ruby]
-----
-# Block at lines 10-12
-# context_lines = 3
-# → Context spans lines 7-15
-#
-# Lines 7-9:   Context before
-# Lines 10-12: Actual changes
-# Lines 13-15: Context after
-----
-
-=== Context merging
-
-Nearby blocks are merged into a single context:
-
-[source,ruby]
-----
-# Block 1 at lines 10-12
-# Block 2 at lines 18-20
-# Gap = 5 lines
-# grouping_lines = 5
-# → Both blocks in same context (gap ≤ grouping_lines)
-
-# Block 1 at lines 10-12
-# Block 2 at lines 25-27
-# Gap = 12 lines
-# grouping_lines = 5
-# → Separate contexts (gap > grouping_lines)
-----
-
-== Real-world examples
-
-These examples demonstrate Canon's DOM diff output using actual test cases from IsoDoc specs. The examples use color highlighting to show different types of changes.
-
-=== Understanding diff symbols
-
-Canon uses a dual-column line number format with specific symbols and colors to indicate different types of changes.
-
-**Line number format:**
-
-Canon displays two line numbers for each line:
-```
-oldnum|newnum  | content
-```
-
-For example:
-```
-   1|   1  | <div>           # Line 1 in both files (unchanged)
-   2|    - | <p>Old</p>      # Line 2 in file 1, removed
-    |   2+ | <p>New</p>      # Line 2 in file 2, added
-   3|   3  | </div>          # Line 3 in both files (unchanged)
-```
-
-**Line-level symbols:**
-
-`-` (in new column):: Removed line - old file has this line, new file doesn't
-`+` (in new column):: Added line - new file has this line, old file doesn't
-`!` (in new column):: Changed line (character-level diff within the line)
-`~` (in new column):: Informative change (cosmetic difference)
-(blank):: Unchanged line (context)
-
-**Character visualization:**
-
-Canon visualizes invisible characters to make differences clear. The most common visualizations are:
-
-* Regular space (U+0020): `░` (light shade)
-* Non-breaking space (U+00A0): `␣` (open box)
-* Tab (U+0009): `⇥` (rightwards arrow to bar)
-
-For complete character visualization mappings, see link:CHARACTER_VISUALIZATION.adoc[Character Visualization].
-
-**Character-level highlighting:**
-
-For lines marked with `!` (changed), Canon highlights specific character ranges:
-
-* Deleted characters: red text
-* Added characters: green text
-* Unchanged characters: normal color
-
-**Normative vs informative:**
-
-* **Normative differences** (red/green) affect semantic equivalence
-* **Informative differences** (cyan) are cosmetic only
-
-=== Example 1: Normative text content change
-
-This example shows a simple text content change from IsoDoc source code tests.
-
-**Input documents:**
-
-[source,xml]
-----
-<!-- Document 1 -->
-<sourcecode>
-  <body>puts "Hello, world."</body>
-</sourcecode>
-
-<!-- Document 2 -->
-<sourcecode>
-  <body>puts "Goodbye, world."</body>
-</sourcecode>
-----
-
-**Diff output:**
-
-++++
-<div style="font-family: 'Courier New', monospace; background: #f5f5f5; padding: 15px; border: 1px solid #ddd; margin: 10px 0;">
-<div><span style="color: #cccc00;">   1|   1  |</span> <span style="color: #999;">&lt;sourcecode&gt;</span></div>
-<div><span style="color: #cccc00;">   2|   2  |</span> <span style="color: #999;">  &lt;body&gt;puts░"Hello,░world."&lt;/body&gt;</span></div>
-<div><span style="color: #cccc00;">   3|    - |</span> <span style="color: #cc0000;">  &lt;body&gt;puts░"Goodbye,░world."&lt;/body&gt;</span></div>
-<div><span style="color: #cccc00;">    |   3+ |</span> <span style="color: #00cc00;">  &lt;body&gt;puts░"Goodbye,░world."&lt;/body&gt;</span></div>
-<div><span style="color: #cccc00;">   4|   4  |</span> <span style="color: #999;">&lt;/sourcecode&gt;</span></div>
-</div>
-++++
-
-This is a **normative difference** - the text content actually changed, affecting semantic equivalence.
-
-=== Example 2: Character-level change
-
-When only part of a line changes, Canon uses the `!` symbol and highlights specific character ranges.
-
-**Input documents:**
-
-[source,xml]
-----
-<!-- Document 1 -->
-<p>Hello, world</p>
-
-<!-- Document 2 -->
-<p>Hello there, world</p>
-----
-
-**Diff output:**
-
-++++
-<div style="font-family: 'Courier New', monospace; background: #f5f5f5; padding: 15px; border: 1px solid #ddd; margin: 10px 0;">
-<div><span style="color: #cccc00;">1!|</span> &lt;p&gt;Hello<span style="color: #00cc00;"> there</span>, world&lt;/p&gt;</div>
-</div>
-++++
-
-The `!` indicates a changed line, with:
-
-* `[Hello]` and `[, world</p>]` unchanged (normal color)
-* `[ there]` added (green text)
-
-=== Example 3: Informative attribute order
-
-This example shows how attribute reordering is treated as informative (cosmetic) by default.
-
-**Input documents:**
-
-[source,xml]
-----
-<!-- Document 1 -->
-<div class="TOC" id="_toc">Content</div>
-
-<!-- Document 2 -->
-<div id="_toc" class="TOC">Content</div>
-----
-
-**With default settings:**
-
-No diff shown - attribute order is normalized automatically, so documents are considered equivalent.
-
-**With `show_diffs: :informative`:**
-
-++++
-<div style="font-family: 'Courier New', monospace; background: #f5f5f5; padding: 15px; border: 1px solid #ddd; margin: 10px 0;">
-<div><span style="color: #cccc00;">   1|    ~ |</span> <span style="color: #00cccc;">&lt;div░class="TOC"░id="_toc"&gt;Content&lt;/div&gt;</span></div>
-<div><span style="color: #cccc00;">    |   1~ |</span> <span style="color: #00cccc;">&lt;div░id="_toc"░class="TOC"&gt;Content&lt;/div&gt;</span></div>
-</div>
-++++
-
-The `~` symbol and cyan color indicate this is an **informative difference** - it doesn't affect semantic equivalence.
-
-=== Example 4: Mixed normative and informative
-
-This example combines both normative and informative differences, showing how `show_diffs` filters the output.
-
-**Input documents:**
-
-[source,xml]
-----
-<!-- Document 1 -->
-<root>
-  <p>Old text</p>
-  <div class="x" id="1">Same content</div>
-</root>
-
-<!-- Document 2 -->
-<root>
-  <p>New text</p>
-  <div id="1" class="x">Same content</div>
-</root>
-----
-
-**With `show_diffs: :all` (show everything):**
-
-++++
-<div style="font-family: 'Courier New', monospace; background: #f5f5f5; padding: 15px; border: 1px solid #ddd; margin: 10px 0;">
-<div><span style="color: #cccc00;">   1|   1  |</span> <span style="color: #999;">&lt;root&gt;</span></div>
-<div><span style="color: #cccc00;">   2|    - |</span> <span style="color: #cc0000;">  &lt;p&gt;Old░text&lt;/p&gt;</span></div>
-<div><span style="color: #cccc00;">    |   2+ |</span> <span style="color: #00cc00;">  &lt;p&gt;New░text&lt;/p&gt;</span></div>
-<div><span style="color: #cccc00;">   3|    ~ |</span> <span style="color: #00cccc;">  &lt;div░class="x"░id="1"&gt;Same░content&lt;/div&gt;</span></div>
-<div><span style="color: #cccc00;">    |   3~ |</span> <span style="color: #00cccc;">  &lt;div░id="1"░class="x"&gt;Same░content&lt;/div&gt;</span></div>
-<div><span style="color: #cccc00;">   4|   4  |</span> <span style="color: #999;">&lt;/root&gt;</span></div>
-</div>
-++++
-
-**With `show_diffs: :normative` (only semantic changes):**
-
-++++
-<div style="font-family: 'Courier New', monospace; background: #f5f5f5; padding: 15px; border: 1px solid #ddd; margin: 10px 0;">
-<div><span style="color: #cccc00;">   1|   1  |</span> <span style="color: #999;">&lt;root&gt;</span></div>
-<div><span style="color: #cccc00;">   2|    - |</span> <span style="color: #cc0000;">  &lt;p&gt;Old░text&lt;/p&gt;</span></div>
-<div><span style="color: #cccc00;">    |   2+ |</span> <span style="color: #00cc00;">  &lt;p&gt;New░text&lt;/p&gt;</span></div>
-<div><span style="color: #cccc00;">   3|   3  |</span> <span style="color: #999;">  &lt;div░id="1"░class="x"&gt;Same░content&lt;/div&gt;</span></div>
-<div><span style="color: #cccc00;">   4|   4  |</span> <span style="color: #999;">&lt;/root&gt;</span></div>
-</div>
-++++
-
-The attribute order difference (line 3) is hidden because it's informative.
-
-**With `show_diffs: :informative` (only cosmetic changes):**
-
-++++
-<div style="font-family: 'Courier New', monospace; background: #f5f5f5; padding: 15px; border: 1px solid #ddd; margin: 10px 0;">
-<div><span style="color: #cccc00;">   1|   1  |</span> <span style="color: #999;">&lt;root&gt;</span></div>
-<div><span style="color: #cccc00;">   2|   2  |</span> <span style="color: #999;">  &lt;p&gt;New░text&lt;/p&gt;</span></div>
-<div><span style="color: #cccc00;">   3|    ~ |</span> <span style="color: #00cccc;">  &lt;div░class="x"░id="1"&gt;Same░content&lt;/div&gt;</span></div>
-<div><span style="color: #cccc00;">    |   3~ |</span> <span style="color: #00cccc;">  &lt;div░id="1"░class="x"&gt;Same░content&lt;/div&gt;</span></div>
-<div><span style="color: #cccc00;">   4|   4  |</span> <span style="color: #999;">&lt;/root&gt;</span></div>
-</div>
-++++
-
-The text change (line 2) is hidden because it's normative, not informative.
-
-=== Color reference
-
-For accessibility, here are the specific colors used:
-
-[cols="1,2,3"]
-|===
-| Type | Color | Usage
-
-| Line numbers/pipes
-| Yellow: #cccc00
-| All line prefixes (e.g., `1\|`, `2-\|`, `+\|`)
-
-| Removed (normative)
-| Red: #cc0000
-| Lines with `-` symbol
-
-| Added (normative)
-| Green: #00cc00
-| Lines with `+` symbol
-
-| Changed (normative)
-| Red/green text
-| Character ranges in `!` lines
-
-| Informative
-| Cyan: #00cccc
-| Lines with `~` symbol
-
-| Context
-| Gray: #999999
-| Unchanged lines
-|===
-
-== See also
-
-* link:TREE_DIFF.adoc[Semantic Tree Diff] - For tree-level semantic operations
-* link:MATCH_OPTIONS.adoc[Match Options] - For controlling match dimensions
-* link:DIFF_ARCHITECTURE.adoc[Diff Architecture] - For implementation details
-* link:NORMATIVE_INFORMATIVE_DIFFS.adoc[Normative/Informative Diffs] - For classification details