canon 0.1.5 → 0.1.7

data/docs/features/diff-formatting/colors-and-symbols.adoc

@@ -0,0 +1,606 @@
+---
+layout: default
+title: Colors and Symbols
+parent: Diff Formatting
+grand_parent: Features
+nav_order: 5
+---
+
+:toc:
+:toclevels: 3
+
+== Purpose
+
+Canon uses a carefully designed color scheme and symbol system to communicate
+the nature and severity of differences in document comparisons.
+
+== Diff classification
+
+Canon classifies differences into three distinct categories, each with unique
+visual markers and directional colors.
+
+[cols="1,1,1,3",options="header"]
+|===
+| Type | Marker | Color | Meaning
+
+h| Formatting-only
+| `[` (removed) +
+`]` (added)
+| Dark gray (removed) +
+Light gray (added)
+| Purely cosmetic differences with no semantic meaning. +
+Only whitespace, line breaks, or indentation differ. +
+Content is semantically identical.
+
+h| Informative
+| `<` (removed) +
+`>` (added)
+| Blue (removed) +
+Cyan (added)
+| Differences that don't affect current match results. +
+May become normative with different match option settings. +
+Provides context about ignored differences.
+
+h| Normative
+| `-` (removed) +
+`+` (added)
+| Red (removed) +
+Green (added)
+| Semantic differences that affect match results. +
+Requires developer attention. +
+Represents actual content changes.
+|===
+
+=== Classification hierarchy
+
+The classification follows a strict hierarchy:
+
+----
+formatting < informative < normative
+----
+
+A difference is classified using the highest applicable category:
+
+normative:: the differences leads to semantic changes that are considered normative
+informative:: the differences leads to semantic changes that are considered informative
+formatting-only:: the differences do not cause any semantic difference
+
+== Formatting-only detection
+
+Formatting-only differences are detected through aggressive normalization:
+
+. Collapse all whitespace (spaces, tabs, newlines) to single space
+. Strip leading and trailing whitespace
+. Compare normalized content
+
+If the normalized content is identical, the difference is classified as formatting-only.
+
+.Example: Formatting-Only Difference
+====
+[source]
+----
+  5|   5[ | <p class="section-break"><br clear="all" class="section"></p>
+   |   5] | <p class="section-break"><br clear="all" class="section"><div class="WordSection2">
+  6|   6] | <div class="WordSection2">
+----
+
+These lines differ only in how content is split across lines. The semantic content (when
+whitespace is normalized) is identical, so they show as formatting-only with `[` (dark gray) for
+removed and `]` (light gray) for added lines.
+====
+
+== Color Coding
+
+=== By Difference Type
+
+==== Formatting-Only (Gray Tones)
+
+Formatting-only changes use directional gray tones to indicate low visual priority:
+
+* **Dark gray** (`[`): Formatting-only removal
+* **Light gray** (`]`): Formatting-only addition
+* Purely cosmetic
+* Safe to ignore
+* No semantic impact
+
+==== Informative (Blue Tones)
+
+Informative changes use blue tones to indicate medium visual priority:
+
+* **Blue** (`<`): Informative removal
+* **Cyan** (`>`): Informative addition
+* Context-dependent
+* Currently ignored
+* May matter with different settings
+
+==== Normative (Red/Green)
+
+Normative changes use red/green for high visual priority:
+
+* **Red** (`-`): Content removed (normative difference)
+* **Green** (`+`): Content added (normative difference)
+* Requires attention
+* Affects comparison result
+
+== Symbol Meanings
+
+=== Line-Level Markers
+
+==== Formatting Markers (Gray)
+
+* `[` - Line removed (formatting-only difference, dark gray)
+* `]` - Line added (formatting-only difference, light gray)
+
+==== Informative Markers (Blue)
+
+* `<` - Line removed (informative difference, blue)
+* `>` - Line added (informative difference, cyan)
+
+==== Normative Markers (Red/Green)
+
+* `-` - Line removed (normative difference, red)
+* `+` - Line added (normative difference, green)
+
+==== Context Marker
+
+* ` ` (space) - Unchanged line (context)
+
+=== Line Numbers
+
+Line numbers are displayed in yellow with pipe separators:
+
+```
+ 123|  45+ | content here
+^^^^  ^^
+old   new
+line  line
+```
+
+* Left number: Line number in original file
+* Right number: Line number in modified file
+* Empty space (` `) when line doesn't exist in that file
+
+== Visual Examples
+
+=== Formatting-Only Change (Gray Tones)
+
+[source]
+----
+  5|   5[ | <p>Content that spans        (dark gray)
+   |   5] | <p>Content that spans multiple lines</p>    (light gray)
+  6|   6] | multiple lines</p>           (light gray)
+----
+
+=== Informative Change (Blue Tones)
+
+[source]
+----
+  10|  10< | <div  class="test">         (blue)
+    |  10> | <div class="test">          (cyan)
+----
+
+=== Normative Change (Red/Green)
+
+[source]
+----
+  15|  15- | <title>Old Title</title>    (red)
+    |  15+ | <title>New Title</title>    (green)
+----
+
+=== Mixed Context
+
+[source]
+----
+  20|  20  | <body>
+  21|  21[ |   <p>Hello</p>                                (dark gray)
+    |  21] |   <p>Hello</p><span>World</span>             (light gray)
+  22|  22] |   <span>World</span>                         (light gray)
+  23|  23- | <footer>2023</footer>                        (red)
+    |  23+ | <footer>2024</footer>                        (green)
+  24|  24  | </body>
+----
+
+This example shows:
+
+* Line 20, 24: Unchanged context (space marker)
+* Lines 21-22: Formatting-only change (`[` dark gray, `]` light gray)
+* Line 23: Normative change (`-` red, `+` green)
+
+== Configuration
+
+Colors can be disabled for terminal compatibility:
+
+[source,ruby]
+----
+result = Canon.compare(doc1, doc2, format: :xml, use_color: false)
+----
+
+When colors are disabled:
+
+* Markers remain (`  [ ] < > - +`)
+* All text appears in terminal default color
+* Line numbers and pipes remain visible
+
+
+
+
+=== Tree Diff Symbols
+
+In by-object diff mode, box-drawing characters create a visual tree structure:
+
+[cols="1,3"]
+|===
+|Symbol |Meaning
+
+|`├──`
+|Tree branch (child element)
+
+|`└──`
+|Last tree branch (last child)
+
+|`│`
+|Tree continuation (vertical line)
+
+|`-`
+|Deletion marker (red)
+
+|`+`
+|Addition marker (green)
+
+|`~`
+|Change marker (yellow)
+|===
+
+.Example: Tree structure with symbols
+[example]
+====
+[source]
+----
+root
+├── - item: "Old value"              # Deleted (red -)
+├── + item: "New value"               # Added (green +)
+└── ~ title                           # Modified (yellow ~)
+    ├── - "Old Title"                 # Old value
+    └── + "New Title"                 # New value
+----
+====
+
+== Character Visualization Symbols
+
+When `use_color: true`, Canon visualizes invisible characters using Unicode symbols. See link:character-visualization.html[Character Visualization] for the complete mapping.
+
+Common examples:
+
+[cols="2,1,2"]
+|===
+|Character |Symbol |Unicode
+
+|Regular space
+|`░`
+|U+2591 (Light Shade)
+
+|Tab
+|`⇥`
+|U+21E5 (Rightwards Arrow to Bar)
+
+|Non-breaking space
+|`␣`
+|U+2423 (Open Box)
+
+|Line feed
+|`↵`
+|U+21B5 (Downwards Arrow with Corner Leftwards)
+
+|Zero-width space
+|`→`
+|U+2192 (Rightwards Arrow)
+|===
+
+== Namespace Rendering
+
+=== Namespace Display Format
+
+Canon makes namespace information explicit in diff output, particularly when comparing XML elements and attributes:
+
+[cols="2,3"]
+|===
+|Namespace State |Display Format
+
+|Empty namespace
+|`ns:[{blank}]`
+
+|Populated namespace
+|`ns:[http://example.com]`
+|===
+
+.Example: Namespace display in diff output
+[example]
+====
+[source]
+----
+# Element with no namespace
+- <element ns:[{blank}]>content</element>
+
+# Element with namespace
++ <element ns:[http://example.com]>content</element>
+----
+====
+
+=== Namespace Mismatch Classification
+
+When elements or attributes differ, Canon classifies the mismatch type:
+
+[cols="2,3"]
+|===
+|Mismatch Type |Message Format
+
+|Same namespace, different name
+|`mismatched element name: 'oldname' vs 'newname' (ns:[http://example.com])`
+
+|Different namespace, same name
+|`mismatched element namespace: 'element' (ns:[{blank}] vs ns:[http://example.com])`
+
+|Both name and namespace differ
+|`mismatched element name and namespace: 'old' (ns:[uri1]) vs 'new' (ns:[uri2])`
+|===
+
+.Example: Namespace mismatch messages
+[example]
+====
+[source]
+----
+# Name differs, same namespace
+mismatched element name: 'item' vs 'product' (ns:[http://shop.com])
+
+# Namespace differs, same name
+mismatched element namespace: 'element' (ns:[{blank}] vs ns:[http://example.com])
+----
+====
+
+=== Attribute Namespace Rendering
+
+The same namespace rendering applies to attributes:
+
+.Example: Attribute namespace in diffs
+[example]
+====
+[source]
+----
+# Attribute with no namespace
+- <element attr="value" ns:[{blank}]/>
+
+# Attribute with namespace
++ <element ns:attr="value" ns:[http://ns.com]/>
+
+# Mismatch message
+mismatched attribute namespace: 'id' (ns:[{blank}] vs ns:[http://example.com])
+----
+====
+
+== Header and Metadata Colors
+
+[cols="2,2,3"]
+|===
+|Element |Color |Purpose
+
+|Section headers
+|Cyan + Bold
+|"Visual Diff:", "Line-by-line diff:", etc.
+
+|Algorithm name
+|Cyan + Bold
+|"Algorithm: SEMANTIC TREE DIFF", "Algorithm: DOM DIFF"
+
+|Success messages
+|Green + Bold
+|"✅ Files are semantically equivalent"
+
+|Separators
+|Cyan + Bold
+|"━━━━" (Unicode box drawing)
+
+|Legend headers
+|Cyan + Bold
+|"Character Visualization Legend:"
+
+|Category names
+|Yellow + Bold
+|"Common Whitespace:", "Unicode Spaces:", etc.
+|===
+
+== Normative vs Informative Classification
+
+The color distinction between normative and informative diffs is crucial:
+
+=== Normative Diffs (Red/Green)
+
+**Definition**: Differences that cause files to be non-equivalent based on the current match configuration.
+
+**When shown**:
+* Match dimension is set to `:strict` or `:normalize`
+* The difference persists even after applying normalization
+
+.Example: Normative attribute difference
+[example]
+====
+[source]
+----
+# With attribute_order: :strict
+   5|   -| <item id="a" name="foo"/>    # Red (normative)
+     |  6+| <item name="foo" id="a"/>    # Green (normative)
+----
+
+The attribute order difference is normative because `attribute_order: :strict` treats it as significant.
+====
+
+=== Informative Diffs (Cyan)
+
+**Definition**: Differences that don't affect file equivalence based on the current match configuration.
+
+**When shown**:
+* Match dimension is set to `:ignore` or `:normalize` handled the difference
+* The difference exists but is ignored for equivalence purposes
+* Shown with `show_diffs: :all` or `show_diffs: :informative`
+
+.Example: Informative whitespace difference
+[example]
+====
+[source]
+----
+# With structural_whitespace: :ignore
+   5| ~~ | <item>                       # Cyan (informative)
+     | ~~ |   <name>Widget</name>        # Extra indentation ignored
+----
+
+The whitespace difference is informative because `structural_whitespace: :ignore` means it doesn't affect equivalence.
+====
+
+== Color Control
+
+=== Enabling/Disabling Colors
+
+Colors are controlled by the `use_color` option:
+
+.CLI
+[example]
+====
+[source,bash]
+----
+# Enable colors (default)
+canon diff file1.xml file2.xml --color
+
+# Disable colors
+canon diff file1.xml file2.xml --no-color
+----
+====
+
+.Ruby API
+[example]
+====
+[source,ruby]
+----
+# Enable colors
+Canon.compare(file1, file2, format: :xml, color: true)
+
+# Disable colors
+Canon.compare(file1, file2, format: :xml, color: false)
+----
+====
+
+.RSpec
+[example]
+====
+[source,ruby]
+----
+RSpec.configure do |config|
+  # Enable for local, disable for CI
+  config.canon.xml.diff.use_color = !ENV['CI']
+end
+----
+====
+
+=== Environment Variable
+
+[source,bash]
+----
+# Disable colors globally
+export CANON_USE_COLOR=false
+
+# Enable colors globally
+export CANON_USE_COLOR=true
+----
+
+
+== Diff Type Display Options
+
+Control which types of diffs to show using the `show_diffs` option:
+
+[cols="2,3"]
+|===
+|Option |What's Shown
+
+|`:all` (default)
+|Both normative and informative diffs
+
+|`:normative`
+|Only normative diffs (red/green)
+
+|`:informative`
+|Only informative diffs (cyan)
+|===
+
+.Example: Show only normative diffs
+[example]
+====
+[source,bash]
+----
+# CLI - only show differences that affect equivalence
+canon diff file1.xml file2.xml --show-diffs normative
+----
+
+[source,ruby]
+----
+# Ruby API
+Canon.compare(file1, file2,
+  format: :xml,
+  show_diffs: :normative
+)
+----
+====
+
+== Visual Examples
+
+=== Complete Diff with All Colors
+
+.Full-color diff example
+[example]
+====
+[source]
+----
+Algorithm: SEMANTIC TREE DIFF        # Cyan + Bold
+
+Visual Diff:                         # Cyan + Bold
+root
+├── ~ attributes                     # Yellow (normative)
+│   ├── - id: "old"                 # Red (normative deletion)
+│   └── + id: "new"                 # Green (normative addition)
+├── ~~ whitespace                    # Cyan (informative)
+│   └── ~~ extra spaces             # Cyan (informative)
+└── + element                        # Green (normative addition)
+    └── value: "new"
+
+Line-by-line diff (XML mode):       # Cyan + Bold
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━    # Cyan
+
+   1|  1 | <root>                    # Default (context)
+   2|   -| <item░id="old"/>          # Red (normative deletion)
+     |  2+| <item░id="new"/>          # Green (normative addition)
+   3| ~~ | <p>Text</p>               # Cyan (informative)
+     | ~~ | <p>░░Text</p>             # Cyan (extra spaces, informative)
+----
+====
+
+== Colorblind-Friendly Features
+
+While Canon uses colors, it also provides symbols that work without color:
+
+* **Symbols** (`-`, `+`, `~`) distinguish change types
+* **Line numbers** show correspondence
+* **Tree structure** shows hierarchy
+* **Text labels** describe differences
+
+The combination ensures diffs are readable even without color perception.
+
+
+== Related Features
+
+* link:display-filtering.adoc[Display Filtering] - Control which diff types to show
+* link:context-and-grouping.adoc[Context and Grouping] - Control surrounding context
+* link:../match-options/index.adoc[Match Options] - Configure what's considered normative vs informative
+
+== See Also
+
+* link:character-visualization.html[Character Visualization] - Detailed whitespace visualization
+* link:algorithm-specific-output.html[Algorithm-Specific Output] - Diff format variations
+* link:context-and-grouping.html[Context and Grouping] - Controlling diff context
+* link:../index.html[Diff Formatting] - Overview of formatting features