Table of Contents

• 1. Welcome
• 2. Quick Navigation
  • 2.1. By Your Role
  • 2.2. By Task
  • 2.3. By Format
• 3. Learning Path
  • 3.1. Level 1: Get Started (5 minutes)
  • 3.2. Level 2: Learn Interfaces (15 minutes)
  • 3.3. Level 3: Understand Canon (30 minutes)
  • 3.4. Level 4: Master Features (1 hour)
  • 3.5. Level 5: Advanced Topics (As needed)
• 4. Popular Topics
• 5. Getting Help
• 6. What’s New
  • 6.1. Version 0.x (Current)

Canon provides canonicalization, pretty-printing, and semantic comparison for XML, HTML, JSON, and YAML formats.

1. Welcome

Canon helps you:

• Format documents into canonical or human-readable forms

• Compare documents semantically, not just textually

• Test with RSpec matchers that understand structure

• Debug with clear, color-coded diff output

2. Quick Navigation

2.1. By Your Role

Developer

Start with Ruby API to integrate Canon into your applications.

QA Engineer

Start with RSpec Matchers for testing XML/JSON/YAML generation.

DevOps

Start with CLI for command-line formatting and comparison.

Architect

Start with Architecture to understand Canon’s design.

2.2. By Task

Format a document

• Quick Start: Formatting

• Ruby API: Formatting

• CLI: format command

Compare documents

• Quick Start: Comparing

• Ruby API: Comparison

• CLI: diff command

Test XML generation

• Guide: Testing XML Generation

• RSpec Matchers

Debug test failures

• Guide: Debugging Test Failures

• Character Visualization

2.3. By Format

XML

W3C Canonical XML 1.1, namespace handling, attribute ordering

HTML

HTML4/5 detection, rendered whitespace handling

JSON

Sorted keys, semantic comparison

YAML

Sorted keys, alias handling

3. Learning Path

3.1. Level 1: Get Started (5 minutes)

1. Install Canon

2. Try basic examples

3. Understand core concepts

3.2. Level 2: Learn Interfaces (15 minutes)

Choose your interface:

• Ruby API - Integrate into applications

• CLI - Command-line usage

• RSpec - Testing integration

3.3. Level 3: Understand Canon (30 minutes)

1. Architecture overview

2. Comparison algorithms

3. Diff output modes

3.4. Level 4: Master Features (1 hour)

1. Match options and profiles

2. Configuration profiles - YAML-based presets with element-level whitespace control

3. Format-specific canonicalization

4. Customizing diff output

3.5. Level 5: Advanced Topics (As needed)

• DOM Diff Algorithm Details

• Semantic Tree Diff Details

• Extending Canon

4. Popular Topics

• Options Across Interfaces - Same options in CLI, Ruby API, and RSpec

• Environment Variables - Configure Canon via ENV variables

• Configuration Profiles - YAML presets with element-level whitespace control

• Match Profiles - Pre-configured comparison strategies

• Color-Coded Diffs - Understanding diff output

• Size Limits - Preventing hangs on large files

• CLI Options Reference - Complete option listing

5. Getting Help

Found a bug?

Report an issue on GitHub

Have a question?

Check Glossary or search this documentation

Want to contribute?

See Contributing to Documentation

6. What’s New

6.1. Version 0.x (Current)

• Semantic tree diff algorithm (experimental)

• Size limits for large files

• Enhanced character visualization

• Environment variable configuration

• Configuration profiles with element-level whitespace classification

• Three-way whitespace sensitivity: strict, normalize, insensitive

See Full Changelog