1. Purpose

Canon provides extensive options for customizing diff output to make differences clear, actionable, and easy to understand.

This section covers all aspects of diff output formatting, from basic color schemes to advanced filtering options.

2. Features overview

Canon’s diff formatting includes:

  • Display filtering: Control which differences appear in output based on whether they affect equivalence

  • Colors and symbols: Visual indicators for different types of changes

  • Diff display themes: Choose from light, dark, retro, or claude color schemes

  • Character visualization: Make invisible characters visible

  • Context and grouping: Control how much surrounding context to show

  • Algorithm-specific output: Different output styles for different diff algorithms

  • Whitespace adjacency: Stray whitespace-only text nodes are anchored at themselves instead of cascading into mismatches against neighbouring content. The Reason line names the direction relative to the partner (before/after/adjacent to) (details)

3. Available formatting options

3.1. Display filtering

Filter which differences appear in output while maintaining correct equivalence determination.

  • Show all differences (default)

  • Show only normative differences (affect equivalence)

  • Show only informative differences (don’t affect equivalence)

See Display filtering for complete details.

3.2. Colors and symbols

Canon uses color-coded output to distinguish different types of changes:

  • Red: Normative deletions

  • Green: Normative additions

  • Yellow: Normative structural changes

  • Cyan: Informative differences

See Colors and symbols for details.

3.3. Diff display themes

Choose from 4 predefined color themes (light, dark, retro, claude) or create custom themes:

  • Light theme: Light terminal backgrounds

  • Dark theme: Dark terminals (default)

  • Retro theme: Amber CRT, low blue light

  • Claude theme: Maximum contrast with colored backgrounds

See Themes for complete theme documentation.

3.4. Character visualization

Make invisible characters visible in diff output:

  • Whitespace visualization (spaces, tabs, newlines)

  • Non-ASCII character detection

  • CJK-safe Unicode symbols

Controlled via Canon::Config:

  • true — (default) apply the full visualization map; spaces → ░, tabs → ⇥, NBSP → ␣

  • false — disable all substitution; useful for copying output or CI tooling that cannot render Unicode symbols

  • :content_only — reserved; currently behaves as true

Canon::Config.configure do |cfg|
  cfg.xml.diff.character_visualization = false
end

See Character visualization for details.

3.5. Context and grouping

Control how much surrounding context to show:

  • Context lines: Number of unchanged lines around changes

  • Grouping: Combine nearby changes into single blocks

See Context and grouping for details.

3.6. Display preprocessing

Normalize both documents through the same formatter before the line diff, so that formatting differences between expected and actual do not confuse the LCS algorithm:

  • :none — use documents as-is (default)

  • :pretty_print — run through Canon::PrettyPrinter::Xml (one tag per line)

  • :c14n — run through XML C14N normalization

See Display preprocessing for details, including the character-visualization constraint for future extensibility.

3.7. Pretty-diff mode

:pretty_diff is a text-LCS diff mode that bypasses DiffNodeMapper entirely. It applies display_preprocessing to both sides and runs Diff::LCS.sdiff on the resulting plain-text lines, guaranteeing that every line-level change is visible — even when DiffNodeMapper’s DOM-address correlation is unreliable.

Use it as a reliable fallback when :by_line shows no output for changes you know are present (issue #85).

formatter = Canon::DiffFormatter.new(
  mode: :pretty_diff,
  display_preprocessing: :pretty_print,
  context_lines: 3,
)

See Pretty-diff mode for details and limitations.

3.8. Algorithm-specific output

Different diff algorithms produce different output styles:

  • DOM diff: Line-by-line or by-object output

  • Semantic tree diff: Operation-based output with tree structure

See Algorithm-specific output for details.

4. Common use cases

4.1. Testing

Focus on actionable differences by filtering informative diffs:

Canon::Config.configure do |config|
  config.xml.diff.show_diffs = :normative
  config.xml.diff.use_color = true
end

4.2. Debugging

See all differences with maximum context:

result = Canon::Comparison.equivalent?(doc1, doc2,
  verbose: true,
  show_diffs: :all
)

4.3. CI/CD pipelines

Clean, focused output for automated testing:

canon diff expected.xml actual.xml \
  --show-diffs normative \
  --no-color

5. Configuration

Diff formatting can be configured:

  • Globally via Canon::Config.configure

  • Per-format (XML, HTML, JSON, YAML)

  • Per-operation via method parameters

See CLI options and Ruby API for configuration details.

6. See also